Troubleshooting

Here are some common questions other partners have asked after starting their implementation. For more help, see questions tagged "sonos" on StackOverflow.

Why am I seeing so many getExtendedMetadata calls?

If you have implemented ratings or favorites, these capabilities can cause additional getExtendedMetadata requests. See the getExtendedMetadata for details.

The number of players in your system will affect the number of getExtendedMetadata requests you see; the more players, the more requests.

Why is my favorites container not updating?

Be sure you’ve implemented favorites as described in Add favorites.

Be sure that you've properly implemented getLastUpdate to account for the value associate with your favorites containers and the value associated with your catalog. Common issues include:

• A controller made a call to createItem, deleteItem, or rateItem, but your service did not return a changed favorites value after when the controller called getLastUpdate. If the favorites value is not changed, the controller will not update content in your favorites containers.
• You could be changing the favorites value every time the controller calls getLastUpdate, regardless of whether or not you changed content due to a createItem, deleteItem, or rateItem call. You should only change the favorites value when something in a favorites container has changed.
• You could be changing your catalog value every time a controller calls getLastUpdate, regardless of whether or not you changed catalog content. You should change the catalog value at a longer interval, except in special circumstances where all content on a service is frequently updated or generated by users.

Why am I not seeing two line display?

Two line display is only available for certain container types on Sonos: albumList, trackList, or streamList. See SMAPI object types for details.

Why does it take so long to add tracks to my queue using multi-select?

When you add tracks to the queue using multi-select, the controller sends individual SOAP requests to your service for each track rather one request for a group of tracks (as would be the case when adding using the "All Tracks" node). It takes longer to add tracks when sending individual requests.

In what situations should I return a track, album, artist, stream, or program ID?

An ID should only be returned in cases where the relevant metadata is present. For example, in cases where all tracks on an album cannot be viewed, and the album cannot be added to Sonos favorites or Sonos playlists, you should not be returning an album ID, as these will automatically cause these options to be generated in the Info View. See Content IDs for details.

What text can I customize within the controller?

• You can customize text in the Info View. See Add actions for details.
• You can customize search categories. See Add search for details. Note that any modifications you make to search categories will appear after all other standard categories available.
• You can customize the titles of your containers. See getMetadata for details.
• You can customize text and localize your site using strings. See Strings and localization for details.

Why are you asking me for so many service logos?

We require different kinds of logos for our controllers and our website:

• Circular service logos for desktop controllers.
• Square logos for mobile controllers.
• A rectangular logo for the Sonos website.

See Add images for details.

When do I need to implement a custom error message?

A custom error message should be implemented in any situation where no standard Sonos error is applicable. For example, there might be multiple reasons why a user is no longer authorized to log in, and thus a custom error message would need to be implemented as LoginUnauthorized cannot be raised for all. See Error handling for details.

The controller keeps asking me to reauthorize – why is it doing this?

Generally, if the controller is asking for reauthorization too frequently, it means that token refresh is not implemented correctly. See Use authentication tokens for details.

How long should it take to browse into a container?

Sonos recommends a browse time of 500 milliseconds or less, but Sonos controllers will wait for the length of the timeout, as long as 10 seconds. Browse times vary depending on the distance communications have to travel through the network from a controller to your service and then back again.

How do I make the All Tracks node appear or disappear?

You can make the All Tracks node appear by setting canPlay equal to true for a container. See getMetadata for details. Please note that this node can only appear for certain containers (those containing solely tracks rather than playlists, albums, stations, etc.). See Add play/shuffle all for details.

Why am I having trouble streaming AAC files?

There are several possible approaches to take with issues around AAC/Mp4 files on Sonos.

• Ensure that your AAC files are encoded in a way that is optimized for streaming. Make sure the "moov" atom occurs before the "mdat" atom in the file and use large chunk sizes (e.g. make sure the "stco" atom size is small, compared to the "stsz" atom size).
• Ensure that your CDN does not have a timeout of less than 10 seconds.
• Ensure that your streaming url’s are kept viable for the duration of the track being played. Shorter viability (but not shorter than 15 sec.) may be okay, if the Mp4 file is constructed in a very streaming-friendly manner.  If not, our "streaming" of the file may require multiple accesses over time which the timeout will prevent.

See Streaming basics for details.

Why am I having trouble streaming FLAC files?

The primary issue with FLAC files on Sonos is their size. Sonos streams files, rather than downloading them first so you get music as soon as possible. However, this means that these large files are reliant on a good internet connection, in addition to prompt responsiveness on the server hosting the files. If your internet connection isn't great, or the server hosting the files is responding slowly, streaming of FLAC files will be difficult.

5 Mb is the minimum broadband speed required to stream FLAC on Sonos. If streaming different FLAC music to multiple speakers, we recommend a higher broadband speed. This requirement can vary based on your internet usage (large file downloads, gaming, video streaming, etc.). Here are some suggested specs:

• 5.0 Megabits per second - 1 FLAC stream
• 7.5 Megabits per second - 2 FLAC streams
• 10 Megabits per second - 3 or more FLAC streams

See FLAC best practices for details.