Dev Portal

Types

Sonos uses global object types in the Control and Cloud Queue APIs, such as GlobalError, playMode and playback objects. See the pages in this section for more details.

Each namespace also includes object types that players may event back to your integrations. You may also use these object types in your commands. Click the links to go to the object type description under its associated namespace.

Types (LAN)

See below for samples of how these appear through WebSockets on the LAN.

The groupCoordinatorChanged object is a LAN-only object type. Follow the link to read more.

groups

[
  {
    "type": "groups",
    "namespace": "groups",
    "householdId": "Sonos_0C8nr0lan5l5YuRfkJHTbrvq4D.ToP-I1dRlG8VTpyz5MBS"
  },
  {
    "groups": [
      {
        "id": "RINCON_7BHBFF96BF5A34300", // PlayroomPlayerIdGroupId
        "name": "Playroom",
        "coordinatorId": "RINCON_8HJLQE01RW4B21097", // PlayroomPlayerId
        "playbackState": "PLAYBACK_STATE_IDLE",
        "playerIds": [
          "RINCON_8HJLQE01RW4B21097" // PlayroomPlayerId
        ]
      },
      {
        "id": "RINCON_A8E9677G21B091499", // MasterBRPlayerIdGroupId
        "name": "Master Bedroom + 1",
        "coordinatorId": "RINCON_Y6C3211GJ59H88131", // MasterBRPlayerId
        "playbackState": "PLAYBACK_STATE_IDLE",
        "playerIds": [
          "RINCON_Y6C3211GJ59H88131", // MasterBRPlayerId
          "RINCON_B8E9377C21G061890" // BackPorchPlayerId
        ]
      },
      {
        "id": "RINCON_Z4H7803J17K741322", // FamilyRoomPlayerIdGroupId
        "name": "Family Room + 2",
        "coordinatorId": "RINCON_D7Y5432M12H127890", // FamilyRoomPlayerId
        "playbackState": "PLAYBACK_STATE_IDLE",
        "playerIds": [
          "RINCON_A4E9395C21G061898", // KitchenPlayerId
          "RINCON_C4T1256L09Q293216", // SunRoomPlayerId
          "RINCON_D7Y5432M12H127890" // FamilyRoomPlayerId
        ]
      },
    ],
    "players": [
      {
        "id": "RINCON_8HJLQE01RW4B21097", // PlayroomPlayerId
        "name": "Playroom",
        "icon": "playroom",
        "websocketUrl": "wss://192.168.55.135:1443/websocket/api",
        "softwareVersion": "38.5-43170-DevPreview",
        "deviceIds": [
          "RINCON_8HJLQE01RW4B21097" // PlayroomPlayerId
        ],
        "apiVersion": "1.0.0-DevPreview+1234",
        "minApiVersion": "1.0.0",
        "capabilities" : [
           "PLAYBACK",
           "CLOUD"
        ]
      },
      {
        "id": "RINCON_Y6C3211GJ59H88131", // MasterBRPlayerId
        "name": "Master Bedroom",
        "icon": "masterbedroom",
        "websocketUrl": "wss://192.168.55.176:1443/websocket/api",
        "softwareVersion": "38.5-43170-DevPreview",
        "deviceIds": [
          "RINCON_Y6C3211GJ59H88131" // MasterBRPlayerId
        ],
        "apiVersion": "1.0.0-DevPreview+1234",
        "minApiVersion": "1.0.0",
        "capabilities" : [
           "PLAYBACK",
           "CLOUD",
           "AIRPLAY"
        ]
      },
      {
        "id": "RINCON_B8E9377C21G061890", // BackPorchPlayerId
        "name": "Back Porch",
        "icon": "livingroom",
        "websocketUrl": "wss://192.168.55.244:1443/websocket/api",
        "softwareVersion": "38.5-43170-DevPreview",
        "deviceIds": [
          "RINCON_B8E9377C21G061890" // BackPorchPlayerId
        ],
        "apiVersion": "1.0.0-DevPreview+1234",
        "minApiVersion": "1.0.0",
        "capabilities" : [
           "PLAYBACK",
           "CLOUD"
        ]
      },
      {
        "id": "RINCON_A4E9395C21G061898", // KitchenPlayerId
        "name": "Kitchen",
        "icon": "kitchen",
        "websocketUrl": "wss://192.168.55.241:1443/websocket/api",
        "softwareVersion": "38.5-43170-DevPreview",
        "deviceIds": [
          "RINCON_A4E9395C21G061898", // KitchenPlayerId
          "RINCON_B5R0432H68L104369" // KitchenRightPlayerId
        ],
        "apiVersion": "1.0.0-DevPreview+1234",
        "minApiVersion": "1.0.0",
        "capabilities" : [
           "PLAYBACK",
           "CLOUD"
        ]
      },
      {
        "id": "RINCON_C4T1256L09Q293216", // SunRoomPlayerId
        "name": "Sun Room",
        "icon": "kitchen",
        "websocketUrl": "wss://192.168.55.187:1443/websocket/api",
        "softwareVersion": "38.5-43170-DevPreview",
        "deviceIds": [
          "RINCON_C4T1256L09Q293216" // SunRoomPlayerId
        ],
        "apiVersion": "1.0.0-DevPreview+1234",
        "minApiVersion": "1.0.0",
         "capabilities" : [
           "PLAYBACK",
           "CLOUD"
         ]
     },
      {
        "id": "RINCON_D7Y5432M12H127890", // FamilyRoomPlayerId
        "name": "Family Room",
        "icon": "familyroom",
        "websocketUrl": "wss://192.168.55.166:1443/websocket/api",
        "softwareVersion": "38.5-43170-DevPreview",
        "deviceIds": [
          "RINCON_D7Y5432M12H127890", // FamilyRoomPlayerId
          "RINCON_E6O0329J63L098571" // FamilyRoomSubPlayerId
        ],
        "apiVersion": "1.0.0-DevPreview+1234",
        "minApiVersion": "1.0.0",
         "capabilities" : [
           "PLAYBACK",
           "CLOUD",
           "AIRPLAY",
           "HT_PLAYBACK",
           "HT_POWER_STATE"
         ]
     }
    ]
  }
]

groupVolume

[
  {
    "namespace": "groupVolume",
    "householdId": "ABCD1234",
    "groupId": "XYZ-123abc456:12",
    "type": "groupVolume"
  },
  {
    "muted": "true",
    "fixed": "false",
    "volume": 80
  }
]

metadataStatus

[
  {
    "namespace": "playbackMetadata:1",
    "householdId": "Sonos_Long_Household_Id",
    "groupId": "RINCON_000A0AA000A000000:0000000000",
    "type": "metadataStatus"
  },
  {
    "container": {
      "name": "Malibu",
      "type": "album",
      "id": {
        "serviceId": "000",
        "objectId": "0000000album:0000000000",
        "accountId": "aa_000"
      },
      "service": {
        "name": "ACME Music"
      },
      "imageUrl": "http://acme.example.com/image/ab/abcd-123/400x400bb.jpeg",
      "tags": [
        "TAG_EXPLICIT"
      ]
    },
    "currentItem": {
      "track": {
        "type": "track",
        "name": "Come Down",
        "imageUrl": "http://000.000.00.00:1400/getaa?s=1&u=x-sonos-http%3asong%253a1065680000.mp4%3fsid%3d204%26flags%3d73760%26sn%3d241",
        "album": {
          "name": "Malibu"
        },
        "artist": {
          "name": "Anderson .Paak"
        },
        "id": {
          "serviceId": "000",
          "objectId": "song:1065681770",
          "accountId": "aa_000"
        },
        "service": {
          "name": "ACME Music"
        },
        "durationMillis": 176000,
        "tags": [
          "TAG_EXPLICIT"
        ]
      }
    },
    "nextItem": {
      "track": {
        "type": "track",
        "name": "Silicon Valley",
        "imageUrl": "http://000.000.00.00:1400/getaa?s=1&u=x-sonos-http%3asong%253a1065680000.mp4%3fsid%3d204%26flags%3d73760%26sn%3d241",
        "album": {
          "name": "Malibu"
        },
        "artist": {
          "name": "Anderson .Paak"
        },
        "id": {
          "serviceId": "204",
          "objectId": "song:1065681771",
          "accountId": "aa_000"
        },
        "service": {
          "name": "ACME Music"
        },
        "durationMillis": 244000,
        "tags": [
          "TAG_EXPLICIT"
        ]
      }
    }
  }
]

playbackError

[
  {
    "namespace": "playback",
    "householdId": "ABCD1234",
    "groupId": "XYZ-123abc456:12",
    "type": "playbackError"
  },
  {
    "errorCode": "ERROR_CLOUD_QUEUE_SERVER",
    "reason": "Item not found",
    "itemId": "abc",
    "queueVersion": "asdf3cbjal235jazz",
    "httpStatus": 404
  }
]

[
  {
    "namespace": "playback",
    "householdId": "ABCD1234",
    "groupId": "XYZ-123abc456:12",
    "response": "skipToPreviousTrack",
    "success": false,
    "type": "playbackError"
  },
  {
    "errorCode": "ERROR_DISALLOWED_BY_POLICY"
  }
]

[
  {
    "namespace": "playback",
    "householdId": "ABCD1234",
    "groupId": "XYZ-123abc456:12",
    "type": "playbackError"
  },
  {
    "errorCode": "ERROR_PLAYBACK_FAILED",
    "reason": "Concurrent streaming limit",
    "itemId": "abc",
    "queueVersion": "asdf3cbjal235jazz",
    "httpStatus": 403
  }
]

[
  {
    "namespace": "playback",
    "householdId": "ABCD1234",
    "groupId": "XYZ-123abc456:12",
    "type": "playbackError"
  },
  {
    "errorCode": "ERROR_PLAYBACK_NO_CONTENT",
    "reason": "No content loaded",
    "itemId": "abc",
    "queueVersion": "asdf3cbjal235jazz"
  }
]

playbackStatus

[
  {
    "namespace": "playback",
    "householdId": "ABCD1234",
    "groupId": "XYZ-123abc456:12",
    "type": "playbackStatus"
  },
  {
    "playbackState": "PLAYBACK_STATE_PLAYING",
    "positionMillis": 1,
    "itemId": "abc",
    "queueVersion": "asdf3cbjal235jazz",
    "previousItemId": "xyz",
    "previousPositionMillis": 45700,
    "playModes": {
      "repeat": false,
      "repeatOne": false,
      "crossfade": true,
      "shuffle": false
    },
    "availablePlaybackActions": {
      "canSkip": false,
      "canSkipBack": false,
      "canSeek": false,
      "canRepeat": true,
      "canRepeatOne": true,
      "canCrossfade": true,
      "canShuffle": true
    }
  }
]

playerVolume

[
  {
    "namespace": "playerVolume",
    "householdId": "ABCD1234",
    "playerId": "player12345",
    "type": "playerVolume"
  },
  {
    "muted": "true",
    "fixed": "false",
    "volume": 80
  }
]

sessionError

[
  {
    "namespace": "playbackSession",
    "householdId": "ABCD1234",
    "sessionId": "abcdef123456",
    "type": "sessionError"
  },
  {
    "errorCode": "ERROR_SESSION_EVICTED",
    "reason": "Another user joined the session."
  }
]

sessionInfo

[
   {
     "namespace": "playbackSession",
     "type": "sessionInfo",
     "householdId": "HHID_4231",
     "sessionId": "abcdef123456"
   },
   {
     "suspended": true
   }
]

Updated 11 months ago