Tag and filter explicit content

Tag and filter explicit content

Your service 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  in the Sonos app. For filtering, your service can decide not to return explicit content in your 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. 

Because we offer both tagging and filtering, your service can handle explicit content a few different ways. Your service could choose to only implement explicit tagging. This will let your listeners know if they are choosing to play explicit content. If you are going to filter explicit content on Sonos, we highly recommend that you tag it as well. Filtering content without tagging could create a confusing experience for your listeners.

Tag explicit content

The following examples show what explicit content looks like in the Sonos app if your service takes advantage of this feature. Your service 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 your 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 your 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

We use a different mechanism for filtering explicit content than we do for tagging explicit content. This allows you to implement a filtering experience on Sonos that mirrors the one you offer in your app or on your website. If your service filters explicit content on Sonos, we highly recommend that you tag it as well to offer the best experience for your listeners.

To filter explicit content, your service must enable the Include SMAPI context headers with all requests and Support content filtering capability flags in your Sonos Labs application. Users can enable filtering for their entire Sonos system in the Sonos app. 

If you support filtering, Sonos systems send an <explicit> flag in SOAP request headers. This flag nests within the <context> and <contentFiltering> objects. 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 is how Sonos marks explicit content as non-playable if you return it when filtering is on. It also allows a Sonos system 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 with a stringId of filterDescription to your strings table. 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 filterDescription to explain that you filter explicit content out of radio streams, but users can still play it on demand. See Customizing Strings and Localization for details.

Here you can see that "Your Music Service" uses filterDescription to tell their users that filtering prevents the playback of explicit content. Below that, you can see what that would look like in their strings table.

<stringtables xmlns="http://sonos.com/sonosapi">
  <stringtable rev="1" xml:lang="en-US">
  ...
    <string stringId="filterDescription">Filtering prevents the playback of explicit content.</string>
  ...
  </stringtable>
</stringtables>