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 and artistId. Collections can optionally indicate a creator. For example, a collection could represent an album and artist would indicate the album artist.
For audio books: author, authorId, narrator, and narratorId
For podcasts: podcast, podcastId, producer, and producerId.

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, and relatedBrowse 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 the openUrlAction sub-structure with the actionType value set to openUrl. For usage, see Web page.
simpleHttpRequestAction: Define an HTTP request action by including the simpleHttpRequestAction sub-structure with the actionType value set to simpleHttpRequest. 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.

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.