Sonos Music API - Getting Started Guide

Audio formats

Sonos can stream individual files or play Internet radio streams supported by your music service.

File Formats

Your music service may support any or all of the following combinations of file formats, codecs, media types, sample rates, and transport methods:

Codec Formats Media Types (mimeType) Sample Rates Transport Methods
.m4a, .mp4, .aac audio/mp4, audio/aac,
application/x-mpegURL, application/, audio/x-mpegurl
48 kHz, 44.1 kHz, 32 kHz, 24 kHz, 22.05 kHz, 16 kHz, 11.025 kHz, 8 kHz HTTP, HTTPS
FLAC .flac audio/flac 48 kHz, 44.1 kHz, 32 kHz, 24 kHz, 22.05 kHz, 16 kHz, 11.025 kHz, 8 kHz HTTP, HTTPS
MP3 .mp3 audio/mp3, audio/mpeg3, audio/mpeg 48 kHz, 44.1 kHz, 32 kHz, 24 kHz, 22.05 kHz, 16 kHz HTTP, HTTPS
.ogg application/ogg 48 kHz, 44.1 kHz, 32 kHz, 24 kHz, 22.05 kHz, 16 kHz, 11.025 kHz, 8 kHz HTTP, HTTPS
WMA .asf, .wma audio/wma, audio/x-ms-wma 48 kHz, 44.1 kHz, 32 kHz, 24 kHz, 22.05 kHz, 16 kHz, 11.025 kHz, 8 kHz HTTP, HTTPS, MMS, RTSP

Sonos does not support WMA voice files.

Some formats offer little or no compression while others are highly compressed. Users with lower bandwidth or who are farther away from the locations actually serving the audio files may experience delays, general slowness, or time outs with larger files. Using file formats with compression can help improve the listening experience for these users. Players will support audio at any bitrate that you send.

You must provide the media type using the proper case (lower or upper) in order to properly display two lines of metadata. See Customizing Item Display (i.e. Albums, Tracks, Playlists) for details.

See HTTP Live Streaming (HLS) for details on how to send HLS content to Sonos.

Use a TOC in the header for files encoded with a VBR

You can encode your audio using a constant bitrate (CBR) or a variable bitrate (VBR). When you encode your audio with a CBR, such as 128 or 256 kbps, the player will process the audio faster, but the files will be larger. You can encode with a VBR to reduce file size while maintaining the quality of the audio. This method enables you to encode your audio around a target range, such as between 65-320 kbps. MP3, WMA, AAC, and Ogg-Vorbis audio formats support VBR.

Sonos players require a table of contents (TOC) in the Xing header for audio files encoded with a VBR, otherwise scrubbing will not work properly. See this MP3 Extensions documentation for more details about the VBR Xing header.

Embed metadata in streaming content using Icecast2 or id3v2

Sonos players read metadata using the Icecast2 ICY streaming protocol for streaming content that is not HLS. Use the following best practices when sending metadata using Icecast2:

  • Send "icy-metadata: 1" with the request so we can get metadata in the stream.
  • Handle the "icy-metaint" header.
  • Handle the "icy-name" header.
  • Players only check for the "StreamTitle" key within the embedded metadata in the stream.

For HLS content, use ID3v2 frames for metadata, as defined in the ID3 tag version 2.3.0 documentation. Sonos players read the following ID3v2 tags:

  • COMM—comments
  • PRIV—private frame
  • TALB—album/move/show
  • TCMP—iTunes compilation
  • TCOM—composer
  • TCON—content type
  • TIT2—title/song name/content
  • TPE1—lead performer, soloist
  • TPE2—band/orchestra
  • TPOS—part of a set
  • TRCK—track number
  • WXXX—user defined url link

Use the WXXX tag if you want your stream to have artwork that changes, like an Internet radio stream that changes artwork for each song. We use this tag to specify the size of the artwork and the URL. To do this, you must separate these strings with a null character, such as \0. The first string should start with "artworkURL_" followed by the width of the image in pixels and "x". For example, this string will be set to "artworkURL_640x" for an image that is 640 pixels wide. The second string should be the full album art URI (example: http://server/path/art.jpg"). Together, the strings would look like this: "artworkURL_640x\0".