Configure display types

To create display types for containers, you’ll need to:

  • Add them to your presentation map.
  • Configure lines and strings (this is optional).
  • Configure your getMetadata mediaMetadata and mediaCollection elements to return displayType and summary metadata for containers that use these elements.

See below for details, or click one of the tutorials to walk through a guided implementation.

Create display types in your presentation map

In the presentation map, create a display type with the DisplayType element. Set an id for the display type to reference the display type in the getMetadata response. For example, the id for the display type below is genreGrid:

Next, choose a display mode to define the layout of the object. As shown in the overview, there are five display modes: GRID, LIST, HERO, EDITORIAL, and HERO_EDITORIAL. Continuing with the example above, let’s say you want the genreGrid display type to be a grid with the default amount of lines. In your presentation map, set the display mode to GRID, as shown below:

If you provide a DisplayType in the presentation map, it overrides the default presentation mode for the container, except for an album view, as you wouldn’t want tracks in an album to be displayed other than as a list.

Configure lines (optional)

Within the DisplayType in the presentation map, you can set the lines that you want to display for that DisplayType. You can configure lines using token keywords that will be mapped to metadata in the getMetadata response, use stringIds from your strings file, or a combination of both.


Configure lines in DisplayType elements in your presentation map using the Lines element with Line elements for each line. Use a token or stringId parameter to specify the contents of the line.

Using Tokens

A token represents text that will be replaced with metadata from the getMetadata response. Use the token parameter to display the following metadata (see getMetadata for details):

  • genre – the genre returned in the metadata.
  • artist – the artist returned in the metadata.
  • album – the album returned in the metadata.
  • title – the title returned in the metadata.
  • summary – the summary returned in the metadata.

Here’s an example:

In this example,

displays the title from the metadata response and

displays the artist.

Configuring strings

Use the stringId parameter to display a named string in the strings.xml file. For example:

In this example:

displays the string in your strings.xml file with the stringId named “TITLE_BY_ARTIST” and

displays the string in your strings.xml file with the stringId named “NEW_RELEASE”.

Using tokens in strings

You can use tokens in strings to include metadata returned from your getMetadata response. To use a token in a string, enter one of the tokens shown in the bulleted list above surrounded by brackets. For example, you may want to call out a recently added title in an editorial view. To do so, you could add the following stringId in your strings.xml file:

See Strings and Localization to learn how to configure your strings file.

Configure getMetadata responses

When you want to display items using your new display type, return it in the getMetadata response. For example:

When you return mediaMetadata or mediaCollection to a getMetadata request, the displayType for the item determines how it is displayed on the controller. For example, Sonos controllers display the mediaCollection shown above as a genreGrid display type when a user browses into it:

genreGrid DisplayType

The getMetadata response for the container includes the Cooking Playlist:

Likewise, the display type for the Cooking Playlist is the genreMood display type, which is associated with the HERO display mode in the presentation map:

When you browse into the Cooking Playlist container, the controller uses the genreMood display type to display the contents:

genreMood DisplayType

Define display type for item type

You can define the default display types for item types. This can help simplify your integration, as well as provide a consistent browse experience for users.

For example, SMAPI is designed so that the parent container defines the display type used to render its children. Because of this, if a user displays a container using a related browse call, the call only provides an ID for the item, and not the parent container, so the user may not see the display type you intended. Instead they’ll see the default display type. You can set the default display type for item types to mitigate this issue.

To set a default display type for an item type, enter the itemType in the type attribute of the DisplayType element in the presentation map:

This entry in the presentation map means that any podcast that doesn’t already have a valid display type will have the HERO DisplayMode. Note that podcast is a semanticType, an extension of itemType. See SMAPI object types for details about item types and Add podcasts for details about podcasts and semantic types.


See the tutorials for detailed examples: