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 a specific DisplayMode in your presentation map. 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 a specific DisplayMode in your presentation map. 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 from your strings.xml file that identifies a text 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 format requires secure HTTP, “https//:”.
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 from your strings.xml file that identifies a text string Sonos displays if the action succeeds.
failureMessageStringId string (Optional) A stringId value from your strings.xml file that identifies a text 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. The Sonos app will use this enum to look up the string to use in the strings.xml file. 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 The number of seconds remaining in the current show, rounded up to the nearest integer, or 0 if no show is playing.
secondsToNextShow int 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.