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 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 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 6 months ago