Plan & Build
Dev Portal

Tag & filter explicit content

You can tag and filter explicit content for your listeners that use the Sonos app. Explicit content includes content that has excessive profanities, inappropriate references, or a Parental Advisory warning label. Tagged content will appear with an "E" next to the content in the Sonos app, as shown below.

For filtering, your service can decide not to return explicit content in your30 responses so it won't show up in the Sonos app. Or you could return explicit content and the Sonos app will show it as unplayable.

You can choose to only implement explicit tagging without filtering. This will let your listeners know if they are choosing to play explicit content.

You can also implement filtering, which enables listeners to not show explicit content if they filter it out using a setting in the Sonos app. If you are going to filter explicit content on Sonos, we highly recommend that you tag it as well. Otherwise, filtering content without tagging could create a confusing experience for your listeners.

Where tags show up in the app

You can tag explicit songs, albums, artists, radio stations, and other content for your listeners. Listeners see explicit tags in most places they see content in the Sonos app, such as:

  • browsing
  • searching
  • the queue
  • Sonos Favorites
  • Sonos Playlists
  • the Now Playing screen

Listeners don't see explicit tags in these locations:

  • Info View
  • Album View
  • the Now Playing footer
  • the mini player for the Sonos app for PC
  • widget notifications for the Sonos app for Android

How to tag explicit content

To take advantage of explicit tagging, your service should include the tags type in mediaMetadata and mediaCollection objects. The tags type should contain the explicit element. Set explicit to "1" to tag explicit content. Set explicit to "0" for content that isn't explicit and doesn't need tagging. The explicit element defaults to “0” if you choose not to include it. If content doesn't need to be tagged, you don't need to return the tags type at all.  See getMetadata and getMediaMetadata for details about mediaMetadata and mediaCollection objects.

Explicit tagging is not supported for in-stream metadata on HLS tracks. You can tag containers, so we recommend tagging any HLS stream that may play explicit content. See HTTP Live Stream (HLS) for details about how Sonos players support HLS.

Please note, we make the following recommendations for tagging explicit content:

  • Use explicit tags for playable containers if at least one item within the container is explicit. Listeners can play these containers in their entirety without browsing the contents.

      <mediaCollection>
    <id>playlist:2</id>
    <itemType>playlist</itemType>
    <displayType>recommended</displayType>
    <title>Explicit Playlist</title>
    <tags>
      <explicit>1</explicit>
    </tags>
    <canPlay>true</canPlay>
    <canEnumerate>true</canEnumerate>
    <canResume>false</canResume>
  </mediaCollection>

  • For audiobooks, use explicit tags at the book level and not for each individual chapter. Listeners can play audiobooks in their entirety without browsing the chapters.

      <mediaCollection>
    <id>bk:1</id>
    <itemType>audiobook</itemType>
    <displayType>booksEditorial</displayType>
    <title>The Adventures of Reading</title>
    <summary>A summary of the audiobook.</summary>
    <isFavorite>false</isFavorite>
    <tags>
      <explicit>1</explicit>
    </tags>
    <authorId>ar:34</authorId>
    <author>John Doe</author>
    <narratorId>ar:35</narratorId>
    <narrator>Jane D</narrator>
    <canPlay>true</canPlay>
    <canEnumerate>false</canEnumerate>
    <albumArtURI>https://example.com/assets/images/book1.jpg</albumArtURI>
    <canResume>true</canResume>
  </mediaCollection>

  • For programmed and streaming radio, use explicit tags for any stations that may play explicit content. This way, your listeners won’t be surprised if explicit content plays on the station they are playing.

      <mediaMetadata>
    <id>streamrad:1</id>
    <itemType>stream</itemType>
    <title>Explicit stream</title>
    <tags>
      <explicit>1</explicit>
    </tags>
    <mimeType>audio/m3u8</mimeType>
  </mediaMetadata>

Sample Responses

When your service sends a mediaMetadata object that should have an explicit tag, it should look something like this:

    <mediaMetadata>
      <id>track0001</id>
      <title>Kiss Kiss (single)</title>
      <mimeType>audio/x-ms-wma</mimeType>
      <itemType>track</itemType>
      <tags>
        <explicit>1</explicit>
      </tags>
      <trackMetadata>
        <albumId>album0001</albumId>
        <duration>253</duration>
        <artistId>artist0001</artistId>
        <artist>Chris Brown</artist>
        <album>Kiss Kiss [featuring T-Pain]</album>
        <albumArtURI>http://example.com/track0001.jpg</albumArtURI>
      </trackMetadata>
    </mediaMetadata>

When your service sends a mediaCollection object that should have an explicit tag, it should look something like this:

    <mediaCollection>
      <id>genre_mood:1</id>
      <itemType>container</itemType>
      <displayType>genreMood</displayType>
      <title>Entering Beast Mode</title>
      <summary>Summary of the media collection.</summary>
      <canPlay>false</canPlay>
      <ns:albumArtURI>https://acmemusic.example.com/assets/images/beast.jpg</ns:albumArtURI>
      <tags>
        <explicit>1</explicit>
      </tags>
    </mediaCollection>

Filter explicit content

You can offer the ability for listeners to filter explicit content on their Sonos household. When Listeners enable filtering in the Sonos app, they enable it for their entire household. This means that everyone in the household will have the same experience. By default, the Sonos app displays this content as unplayable, but you can also set up your service to not display content tagged as explicit or to substitute non-explicit content when the filter is on. The implementation details are up to you.

Since tagging and filtering are two different features, you will have to implement them separately. However, if you enable filtering, you should also enable tagging.

To filter explicit content, your service must enable the following capability flags:

  • Include SMAPI context headers with all requests
  • Support content filtering

See Add capabilities for details.

If you support filtering, Sonos systems send an explicit flag in SOAP request headers. See SOAP requests and responses for details. This flag nests within the context and contentFilteringobjects. The value of explicit is true if the Sonos household sending the request has enabled explicit filtering.  Sonos won't send the contentFiltering or explicit objects if users haven't enabled explicit content filtering.

Here is an example of a SMAPI SOAP header with explicit filtering enabled:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header>
    <credentials xmlns="http://www.sonos.com/Services/1.1">
      <deviceId>
        XX-BB-33-55-66-77:H
      </deviceId>
      <deviceProvider>
        Sonos
      </deviceProvider>
    </credentials>
    <context>
      <timeZone>
        -05:00
      </timeZone>
      <contentFiltering>
        <explicit>
          true
        </explicit>
      </contentFiltering>
    </context>
  </s:Header>
  <s:Body>
  ...
  </s:Body>
</s:Envelope>

We provide the explicit element in the SOAP header so that your service can choose not to send explicit content in your SMAPI responses. This prevents any explicit content from showing up in the Sonos app. Your service can substitute censored versions of explicit content if you have them.

If you do return explicit content to a household that has enabled explicit filtering, the Sonos app will display it as non-playable items. Explicit tracks won’t be playable or selectable. Explicit containers won’t be playable or selectable, and users won’t be able to browse their contents.

Regardless of how you decide to filter, be sure to set isExplicit to true for any explicit items in your responses. This enables Sonos to do things like update the playability of items saved to a Sonos favorite or playlist when filtering is turned on or off. For example, a listener could add an explicit item to Sonos favorites when filtering is off. If another listener in that household enables explicit filtering, Sonos will make that item unplayable.

Here is an example of an explicit mediaMetadata object:

<ns:mediaMetadata>
  <ns:id>streamId:5</ns:id>
  <ns:itemType>stream</ns:itemType>
  <ns:title>Stream Name</ns:title>
  <ns:isExplicit>true</ns:isExplicit>
  <ns:mimeType>application/x-mpegURL</ns:mimeType>
</ns:mediaMetadata>

For a container whose contents are all explicit, you can return isExplicit at the mediaCollection level instead of for individual chapters or tracks. When filtering is on, users won't be able to play, select, or browse this container. If only one or two items in a container are explicit, you could choose to filter those items out at the mediaMetadata level. This way the rest of the container is still playable. For instance, if an album has one explicit song, set isExplicit to true on that track instead of the album so your listeners can still enjoy the clean songs on the album.

Here is an example of an explicit mediaCollection object:

<ns:mediaCollection>
  <ns:id>progradio:1</ns:id>
  <ns:itemType>program</ns:itemType>
  <ns:title>Some Radio</ns:title>
  <ns:isExplicit>true</ns:isExplicit>
</ns:mediaCollection>

Add FilterDescription to your strings table

When you enable explicit filtering, you can choose to add a string to your Localization file. This string displays a message for your listeners on the Parental Controls page in the Sonos app. This can be helpful to inform your listeners about your service's filtering policies. For example, you could use filter-description to explain that your service filters explicit content out of radio streams, but users can still play it on demand. See Localization for details.

Here's an example using FilterDescription to tell users that filtering on "Your Music Service" prevents the playback of explicit content:

Here's what that looks like in the i18file:

{
    "en-US":{
      "common":{
          ...
          },
      "integration":{
        "FILTER_DESCRIPTION": "Filtering prevents the playback of explicit content.",
        ...
      }
    }

Updated 7 months ago