SMAPI object types
Here's a list of the SMAPI objects that may be included in SMAPI requests and responses. This page also includes details about objects with complex types. See the SMAPI reference for details on where Sonos uses these objects. Any other fields that may be in the WSDL are not yet implemented and are reserved for future use. Download the WSDL from SOAP requests and responses.
httpHeader
Name | Type | Description |
---|---|---|
header | string | (Optional) The HTTP header. |
value | string | (Optional) The HTTP header value. |
itemType
The SMAPI itemType
element identifies either a collection of media (mediaCollection
) or a single playable item (mediaMetadata
), both of which are described in detail in getMetadata. Different item types combine with certain attributes to enable functionality in the Sonos app.
mediaCollection item types
The following table lists the item types that identify containers of media, which are returned as mediaCollection
elements. You can display media collections in the Sonos app using a grid, list, or other display modes. See Customize display for details.
itemType | Description | Default Display Mode |
---|---|---|
album | An album container is a list of tracks. List these tracks in the order in which they appear on the album. If the album appears as a direct descendant of an artist , then the artist name will not display beneath the album name. This container type requires albumArtURI elements. | Hero |
albumList | An albumList container is a list of albums by different artists. The Sonos app displays items in albumList containers with the name of the artist below the name of the album. You might use an albumList container to present a list of Top 100 Albums or New Releases. | Grid |
artist | An artist container is a list of album , playlist , program , or container sub-containers. If you provide an albumArtURI element, the Sonos app will display the artwork. | Grid |
artistTrackList | An artistTrackList container is a list of tracks by the same artist. The Sonos app displays these tracks with only the name of the track. The name of the artist is omitted because presumably all tracks in this container are by the same artist. | List |
audiobook | An audiobook container is a list of chapters that are represented by tracks. The tracks are not user-selectable individually and they must remain in chronological order so that the chapters play in succession. An audiobook requires the canResume play mode attribute set to true. Other optional play mode attributes allowed include canSeek and canSkip . See Save & resume playback for how to implement audiobooks. | List |
collection | A generic container. For example, a list of genres or playlists. This is similar to the container and other item types. | List |
container | A generic container. For example, a list of genres or playlists. This is similar to the collection and other item types. | List |
favorites & favorite | These item types have been deprecated. Use the containsFavorite flag in your getMetadata response to indicate whether a collection contains favorites or not. See Add favorites for details. | |
genre | A genre container is a list of sub-containers, such as album or playlist . It can also be a list of trackMetadata or streamMetadata items. | List |
playlist | A playlist container is a list of tracks. If you provide an albumArtURI element, the Sonos app will show the artwork next to the name of the playlist. See Add album art for details on how to specify this artwork. If you include an artist for the playlist , the Sonos app assumes it is the playlist creator. It will display the artist name beneath the playlist name. Return the playlist tracks in the order that they should play, instead of sorting them based on their order within the album they came from. | List |
search | The search container is a list of searchable categories. Return the search itemType only for getMetadata requests for the search id . See Add search for details. | List |
streamList | This is reserved for a future implementation. It is not implemented. | |
trackList | A trackList contains a list of tracks from different albums. Items in this type of container display in the Sonos app with the name of the artist shown below the name of the track. By comparison, tracks that show within an album container don't include this second line. Each track in an album container is presumed to be from the same artist. | List |
other | A generic container. The other itemType is the default type if no itemType is provided in the XML response. This is similar to the collection and container item types. | List |
mediaMetadata item types
The following table lists the item types that identify playable media items, which are returned as mediaMetadata
elements.
itemType | Description |
---|---|
program | A stream of segments of tracks, such as for programmed radio. |
show | A non-live radio stream, such as a radio show. |
stream | An Internet radio stream, usually live. |
track | An audio file, such as a music track. |
other | The other itemType is the default type if no itemType is provided in the XML response. Your SMAPI service should always provide an itemType to the Sonos player if you know it. |
mediaCollection
A complex type describing a collection of media items, such as an album
, an artist
, program
, audiobook
, podcast
, or any other container
. Includes the following Boolean properties:
readOnly
renameable
userContent
These must be set to enable certain features, such as playlist editing. See Add playlists for details. Note that while canReorderItems
and canDeleteItems
exist in the WSDL, Sonos does not support these properties.
Collections can implement one of three sets of metadata to describe the contents:
- For music collections:
artist
andartistId
. Collections can optionally indicate a creator. For example, acollection
could represent an album andartist
would indicate the album artist. - For audio books:
author
,authorId
,narrator
, andnarratorId
- For podcasts:
podcast
,podcastId
,producer
, andproducerId
.
Name | Type | Description |
---|---|---|
albumArtURI | string(128) | (Optional, recommended) A reference to a digital image of the album art. This is optional but recommended. See Add album art for details. |
artist | string(64) | (Optional) Creator for the container. For example, if the collection is an album, then artist would indicate the album artist. Do not include newlines ("/n"). |
artistId | string(255) | (Optional) The unique ID of the artist. |
author | string | (Optional) The display name of the book author. |
authorId | string | (Optional) The unique ID of the book author. |
canAddToFavorites | Boolean | (Optional, default=true ) The collection can be added to user favorites. |
canEnumerate | Boolean | (Optional, default=true ) The collection can be enumerated via a subsequent call to getMetadata using the ID of this collection. Set this value to false to indicate that the user interface cannot “open” the collection to see the contents. The collection can still be enumerated programmatically so this flag is a hint to the Sonos user interface that it can be displayed but not opened. |
canPlay | Boolean | (Optional, default=false ) The collection can be “played” by enumerating the contents as a single flat list of mediaItems. |
canResume | Boolean | (Optional) Indicates whether or not the item can be replayed and resumed where it left off. See Save & resume playback for details. |
canScroll | Boolean | (Optional, default=false ) Capability flag indicating that the collection supports the getScrollIndices feature. |
canSkip | Boolean | (Optional, default=true ) The user is permitted to skip forward among items in the container. Your service may need to prevent this to implement business rules around radio streams. |
containsFavorite | Boolean | (Optional, default=false ) The collection contains user favorites. Set this flag to true for a collection to indicate that the collection contains favorites . Then, any time a user makes changes to an item in this collection, increment the favorites value in getLastUpdate to update the controller cache to show the changes. See Add favorites for details. |
displayType | string(64) | (Optional) Used by the Sonos app to determine how to display items. The app maps the displayType to the Browse Options > Container Displays section in your Integration Submission Form. See Customize display for details. |
id | string(255) | The unique ID of the collection. |
isEphemeral | Boolean | (Optional, default=false ) Indicates whether the collection is short-lived or not, for example, a daily playlist created by your service. If true , Sonos players will not allow it to be added to Sonos Favorites or alarms. If false , Sonos players allow it to be added. |
isExplicit | Boolean | (Optional, default=false ) Indicates that a container is explicit and should be filtered when a Sonos system has explicit filtering turned on. If the isExplicit flag is true , containers will not be playable, selectable, or browseable when a Sonos system has enabled explicit filtering. See Tag & filter explicit content for details. |
isFavorite | Boolean | (Optional) Indicates whether or not the container is a favorite. If the isFavorite flag is true , the container is in the library and the Info View option is "Remove from library." If the flag is false , the container is not in the library and the Info View option is "Add to library." If the flag does not exist, both options are shown, so for optimal user experience, you should add this element. |
itemType | enum | The application-defined type of the collection. Recognized values are collections of media, such as: - artist - album - genre - playlist - search - favorite - favorites - collection - container - albumList - trackList - streamList - artistTrackList - audiobook - other See mediaCollection item types for details. |
narrator | string | (Optional) The display name of the audiobook narrator. |
narratorId | string | (Optional) The unique ID of the audiobook narrator. |
podcast | string | (Optional) The name of the podcast. This is different from the title of the individual podcast episode. See Add podcasts for details. |
podcastId | string | (Optional) The unique ID of the podcast. |
positionInformation | complex | (Optional) You can provide the latest play position to Sonos in this element. Sonos uses it to resume playback. See below for details on sub-elements. See Save & resume playback for implementation details. |
producer | string | (Optional) The name of a podcast producer, provider, or network that created that podcast or podcast episode. See Add podcasts for details. |
producerId | string | (Optional) The unique ID of the producer. |
releaseDate | dateTime | (Optional) Date that a podcast was released, in ISO 8601 standard format. See Add podcasts for details. |
semanticType | enum | (Optional) An extension of itemType . This element gives Sonos apps and players more information about your metadata while allowing older controllers and players to browse and play newer types of content. The only supported value is podcast . See Add podcasts for details. |
summary | string(1024) | (Optional) Displays up to 1024 characters of text next to an item in hero and editorial view. See Customize display for details. |
tags | complex | (Optional, but recommended if supported) Use this object to tag or label content as explicit in the Sonos app if you support it. See below for details on sub-elements. See Tag & filter explicit content for details. |
title | string(64) | The name of the collection. Do not include newlines ("/n"). |
total | int | (Optional) Refers to the total number of items within the mediaCollection. |
mediaMetadata
Name | Type | Description |
---|---|---|
displayType | string | (Optional) Used by the Sonos app to determine how to display items. The app maps the displayType to the Browse Options > Container Displays section in your Integration Submission Form. See Customize display for details. |
dynamic | complex | (Optional) A dynamic element containing a property consisting of a name value pair. See the Dynamic ratings section in Develop ratings for an example of how the dynamic element is used in ratings. |
id | string(255) | A unique ID for this item. |
isEphemeral | Boolean | (Optional, default=false ) Indicates whether the media is short-lived or not. If true , Sonos players will not allow it to be added to Sonos Favorites or alarms. If false , Sonos players allow it to be added. |
isExplicit | Boolean | (Optional, default=false ) Indicates that a media object is explicit and should be filtered when a Sonos system has explicit filtering turned on. If the isExplicit flag is true, media objects will not be playable or selectable when a Sonos system has enabled explicit filtering. See Tag & filter explicit content for details. |
isFavorite | Boolean | Indicates whether or not the item is a favorite item. If the isFavorite flag is true , the item is in the library and the Info View option is to remove the item from library. If the flag is false , the item is not in the library and the Info View option is to add the item to the library. If the flag does not exist, both options are shown, so for optimal user experience, you should add this element. |
itemType | enum | Application defined type. Recognized values are single playable items, such as: - stream - show - track - program - other See mediaMetadata item types for details. |
mimeType | string | The media type for this item. See Supported audio formats for details. |
positionInformation | complex | (Optional) You can provide the latest play position to Sonos in this element. Sonos uses it to resume playback. See below for details on sub-elements. See Save & resume playback for implementation details. |
releaseDate | dateTime | (Optional) Date that a podcast episode was released, in ISO 8601 standard format. See Add podcasts for details. |
semanticType | enum | (Optional) An extension of itemType . This element gives Sonos apps and players more information about your metadata while allowing older controllers and players to browse and play newer types of content. The only supported value is episode.podcast . See Add podcasts for details. |
streamMetadata | complex | Audio stream metadata (used when the item is associated with a stream). |
summary | string | (Optional) A block of text displayed next to an item in hero and editorial view. See See Customize display for details. Also used in podcasts. See Add podcasts for details. |
tags | complex | (Optional, but recommended if supported) Use this object to badge or label content as explicit in the Sonos app if you support it.See below for details on sub-elements. See Tag & filter explicit content for details. |
title | string | The display name for this item. Do not include newlines ("/n"). |
trackMetadata | complex | Audio track metadata (used when the item is associated with a track). |
positionInformation
Name | Type | Description |
---|---|---|
id | string(255) | The unique identifier for the track requested. This will have a maximum length of 255. |
index | int | Reserved for future use. Set this value to 0 . |
offsetMillis | int | The number of milliseconds into the track where play is to resume. See Save & resume playback for details. |
isCompleted | Boolean | (Optional) Refers to whether or not the content has been completely listened to. Used in podcasts to change the indicator from a pie chart to a check mark. See Add podcasts for details. |
relatedActions
Related actions allow services to provide new functionality for listeners in the Sonos Info View. For usage, see Add actions. There are two formats you provide for the contents of the relatedActions
list.
- Define related actions in XML as part of the SOAP envelope when returning a getExtendedMetadata response. You provide this along side other custom actions including
relatedPlay
,relatedText
, andrelatedBrowse
elements. - Define related actions in an array of JSON objects when returning a response to an HTTP REST request. For a JSON example, see REST request.
The relatedActions
list can contain one or more action structures. See the following sub-structures.
action
One or more action structures are within a relatedActions structure. An action can contain either of the following:
openUrlAction
: Define an open URL action by including theopenUrlAction
sub-structure with theactionType
value set toopenUrl
. For usage, see Web page.simpleHttpRequestAction
: Define an HTTP request action by including thesimpleHttpRequestAction
sub-structure with theactionType
value set tosimpleHttpRequest
. For usage, see REST request.
The action structure is comprised of the following:
Name | Type | Description |
---|---|---|
id | string | A unique ID for this action. |
title | string | A stringId value that identifies a localization string Sonos uses as a label in the Info View. |
actionType | enum | Valid values are: - The openUrl value is required in combination with the openUrlAction structure.- The simpleHttpRequest value is required in combination the simpleHttpRequestAction structure. |
openUrlAction | choice | The openUrlAction structure is required if the actionType value is openUrl . This contains a required url structure, which is a string representing the URL Sonos opens when the listener selects this action from the Info View. The URL requires the HTTPS format. |
simpleHttpRequestAction | choice | The simpleHttpRequestAction structure is required if the actionType value is simpleHttpRequest . See simpleHttpRequestAction for details. |
showInBrowse | Boolean | (Optional) By default, the action shows in the Info View when the listener is using either the browse or now-playing modes. When this value is false , the action does not show in the Info View for the browse mode, but only in the Info View for the now-playing mode. |
successMessageStringId | string | (Optional) A stringId value that identifies a localization string Sonos displays if the action succeeds. |
failureMessageStringId | string | (Optional) A stringId value that identifies a localization string Sonos displays if the action fails. |
simpleHttpRequestAction
The simpleHttpRequestAction
structure is an option within an action structure and is comprised of the following:
Name | Type | Description |
---|---|---|
url | string | When the user selects the action from the Info View, Sonos calls this URL, which executes a method to perform the action. |
method | string | The HTTP Method to use in the request. Valid values include: - GET - DELETE - POST - PUT |
httpHeaders | complex | (Optional) An optional list of name-value pairs containing any additional HTTP headers to be sent in the HTTP request. |
refreshOnSuccess | Boolean | (Optional) A value of true causes Sonos to update the container the listener is browsing in after the HTML request successfully executes. |
relatedBrowse
Name | Type | Description |
---|---|---|
id | string(128) | The unique ID that should be browsed to get the corresponding information. When you pass this id as the argument to getMetadata , it will return a list of items corresponding to the type , for example, RELATED_ARTISTS for a list of related artists. |
type | string(32) | An enum type that describes the relation of this browse to the item passed as the parameter. This string isn't used directly in the UI, but rather is a signal indicating which string the UI should show. |
For example, if the type is RELATED_ARTISTS
, Sonos can use the result id
as the argument to a getMetadata
call and your service will return a list of related artists. The fact that this item is returned in the result of a getExtendedMetadata
request indicates that a related browse of the specified type exists.
If possible, the server shouldn’t include this item in the result if there will not be any results when doing the related browse. RELATED_ARTISTS
is a Sonos-created type that Sonos apps automatically know how to handle. You can also create your own custom types. See Add actions for details.
relatedPlay
Use relatedPlay
in the getExtendedMetadata
response to offer an option to immediately play a stream or programmed radio from the Info View.
Name | Type | Description |
---|---|---|
id | string(128) | The unique ID of the stream or programmed radio to play. |
type | string(32) | An enum type describing the itemType , currently stream or programmed radio. |
title | string(64) | The title of the stream or programmed radio. |
canPlay | Boolean | If true , the user can choose the option to play the stream or radio, if false , the option is greyed out. |
You can have more than one related play item in the Info View, but the maximum amount of items you can have in the Info View is 30. See Add actions for details.
relatedText
Name | Type | Description |
---|---|---|
id | string(128) | The unique ID of the item the related text is about. This should be the same as the ID passed as the argument to getExtendedMetadata . |
type | string(32) | An enum type describing the relation of this text. Sonos apps recognize the following enums: - ARTIST_BIO - ALBUM_NOTES - BOOK_NOTES You can also create your own enums. See Add actions for details. |
The fact that this item is returned in the result of a getExtendedMetadata
call indicates that some related text of the specified type exists. If possible, the server shouldn't include this item in the result if no such related text content exists. To get the actual body of the text, the Sonos app will send a getExtendedMetadataText
request, passing both the ID and type as arguments.
streamMetadata
If your SMAPI service returns streamMetadata
, it should return this streamMetadata
in the getMetadata and getMediaMetadata responses.
Name | Type | Description |
---|---|---|
bitrate | int | (Optional) The bitrate of the stream, in kbps. |
currentHost | string(64) | (Optional) The current host or DJ of the stream, if any. |
currentShow | string(64) | The name of the current show playing on the stream, if any. |
currentShowId | string(64) | The ID of the current show playing on the stream, if any. |
description | string | A description of the show. |
hasOutOfBandMetadata | Boolean | This is deprecated. We recommend that you embed metadata in-line with your content at regular intervals using the ICY protocol or into HLS segments using ID3. Including metadata in a different location than the content to which it refers (what we call out-of-band metadata) is non-standard and increases the calls sent from players to your service. See Supported audio formats for details. |
isEphemeral | Boolean | True if the stream is short-lived. If so, Sonos players will not allow it to be added to Sonos Favorites or alarms. False if it is not short-lived. |
logo | string(128) | (Optional) A reference to a digital image for the station/show. |
secondsRemaining | int | (Optional) The number of seconds remaining in the current show, rounded up to the nearest integer, or 0 if no show is playing. |
secondsToNextShow | int | (Optional) The number of seconds until the next scheduled show – can be different than secondsRemaining when no show is playing, or when schedule information is missing for some time interval. |
tags
Name | Type | Description |
---|---|---|
explicit | int | (Optional, default=0 ) Set to 1 to indicate that a mediaMetadata or mediaCollection item is explicit. |
trackMetadata
Name | Type | Description |
---|---|---|
album | string(64) | (Optional) The display name of the album. Do not include newlines ("/n"). |
albumArtist | string(64) | The display name of the album artist (sometimes referred to as compilation artist). |
albumArtistId | string(128) | (Optional) The unique ID of the albumArtist . |
albumArtURI | string(128) | (Optional, recommended) A reference to a digital image of the album art. See Add album art for details. |
albumId | string(128) | (Optional) The unique ID of the album. |
artist | string(64) | The display name of the artist. Do not include newlines ("/n"). |
artistId | string(128) | (Optional) The unique ID of the artist. |
author | string | (Optional) The display name of the book author. |
authorId | string | (Optional) The unique ID of the book author. |
book | string | (Optional) The display name of the audiobook. |
bookId | string | (Optional) The unique ID of the audiobook. |
canAddToFavorites | Boolean | (Optional, default=true ) The track can be added to user favorites. |
canPlay | Boolean | (Optional, default=true ) When true , the track can be played; the user has the rights or permission to play it. |
canResume | Boolean | (Optional, default=false ) Indicates whether or not the item can be replayed and resumed where it left off. See Save & resume playback for details. |
canSeek | Boolean | (Optional, default=true ) When true , the seek functionality is enabled on tracks. Your service can disable seek functionality on a per-track basis by setting this flag to false . Tracks in a radio stream ignore this flag and seek is always false . |
canSkip | Boolean | (Optional, default=true ) When true , the user is permitted to skip forward among items in the container. A service may need to prevent this to implement business rules around radio streams. |
composer | string(64) | (Optional) The display name of the composer. |
composerId | string(128) | (Optional) The unique ID of the composer. |
duration | int | Length of audio track in seconds. This is required for HLS track types if you want to allow scrubbing or skipping. See HTTP Live Streaming (HLS) for details. |
genre | string(64) | The display name of the genre. |
genreId | string(128) | The unique ID for the genre. |
host | string | (Optional) The host of the podcast. |
hostId | string | (Optional) The unique ID for the host. |
narrator | string | (Optional) The display name of the audiobook narrator. |
narratorId | string | (Optional) The unique ID of the audiobook narrator. |
podcast | string | (Optional) The display name of the podcast. |
podcastId | string | (Optional) The unique ID for the podcast. |
producer | string | (Optional) The display name of the podcast producer. |
producerId | string | (Optional) The unique ID for the producer. |
rating | int | The rating ID for a track. |
trackNumber | int | The track number for the track on an album. |
userInfo
Name | Type | Description |
---|---|---|
userIdHashCode | string | Your service's immutable opaque identifier of the user. Sonos will use this for personalization options available in a future release. We strongly urge you to avoid putting any identifying information in this string. For additional security, Sonos does not store this information in its raw form but stores a hash value of this string. |
nickname | string(32) | (Optional) The user's screen name. If you provide this field, Sonos will use it to pre-fill the account nickname during account setup. |
Updated 12 months ago