Sonos

https://docs.sonos.com/
Admin
Sonos provides a developer platform and documentation for partners to integrate content services and...
Tokens:336,096
Snippets:1,207
Trust Score:10
Update:1 year ago
Show doc for...
Tokens:
Raw
### Library Context Localization Example

Source: https://docs.sonos.com/docs/add-search

Example JSON structure for localizing library context types (local and global) in US English.

```json
{
    "en-US":{
      "common":{
         ...
          },
      "integration":{
        "library_type_local": "Local",
        "library_type_global": "Global"
        ...
      }
}

```

--------------------------------

### GET itemWindow Request Examples (Shell, Node, Ruby, PHP, Python)

Source: https://docs.sonos.com/reference/itemwindow

Provides examples of GET requests to the `/itemWindow` endpoint using various programming languages. This includes setting headers for authorization and content type, and defining query parameters for track retrieval.

```Shell
curl --request GET \
     --url 'https://www.example.com/cloudqueue/v2.0/itemWindow?reason=refresh&itemId=%7BYOUR_ITEM_ID%7D&previousWindowSize=null&upcomingWindowSize=null&queueVersion=%7BYOUR_QUEUE_VERSION%7D&isExplicit=true' \
     --header 'Authorization: <long-auth-token-string>' \
     --header 'accept: application/json'
```

--------------------------------

### Sonos API: Example 'play' Reason Request

Source: https://docs.sonos.com/reference/reason-parameter

Shows a Sonos player making a GET /itemWindow request with the reason 'play'. This indicates an explicit user action to start playback after it was paused but not suspended, provided 'notifyUserIntent' is enabled.

```plaintext
GET /itemWindow?reason=play
```

--------------------------------

### Custom Category Example

Source: https://docs.sonos.com/docs/add-search

Example JSON structure for defining custom categories in US English, including common and integration-specific localizations.

```json
{
    "en-US":{
      "common":{
         ...
          },
      "integration":{
        "CATEGORY_TYPE_CONCERT": "Concerts",
        ...
      }
}

```

--------------------------------

### Get Playback Status (Example URL)

Source: https://docs.sonos.com/reference/playback-getplaybackstatus-groupid

Provides an example of the URL structure to call the getPlaybackStatus command. It requires the protocol, API version, and a target groupId.

```HTTP
get {protocol}://api.ws.sonos.com/control/api/{version}/groups/{groupId}/playback
```

--------------------------------

### Accessibility Strings in i18next (JSON)

Source: https://docs.sonos.com/docs/strings-and-localization

Example demonstrating how to provide specific and localized strings for accessibility features like VoiceOver or TalkBack within the 'integration' section of an i18next file.

```json
"en-US":{
	"common":{
          ...
          },
    "integration":{
			"THUMBS_UP":"Thumbs up",
			"THUMBS_DOWN":"Thumbs down",
			"REMOVE_THUMBS_UP":"Thumbs up removed",
			"REMOVE_THUMBS_DOWN":"Thumbs down removed"
	},
}
```

--------------------------------

### Retrieve Playback Context (Shell)

Source: https://docs.sonos.com/reference/context

This example shows how to make a GET request to the Sonos context endpoint to retrieve playback information. It includes example query parameters for contextVersion and queueVersion.

```Shell
GET https://www.example.com/cloudqueue/v2.0/context?contextVersion=cv123&queueVersion=qv102
```

--------------------------------

### Handle SMAPI Search Request

Source: https://docs.sonos.com/docs/add-search

This example shows a basic structure for handling a SMAPI `search()` request within a service. The service receives a query and category information and is expected to return relevant search results.

```smapi
search(
  query: string,
  category: string,
  options: {
    returnFacets: boolean
  }
): Promise<SearchResponse>
```

--------------------------------

### Sonos getAppLink Request Example (XML)

Source: https://docs.sonos.com/docs/getapplink

Demonstrates a sample HTTP request from the Sonos app to your service to get app link information. It includes essential headers and the SOAP envelope with the getAppLink method.

```xml
CONNECTION: close
ACCEPT-ENCODING: gzip
HOST: smapi.acme.com
USER-AGENT: Linux UPnP/1.0 Sonos/31.3-20100 (ICRU_iPhone3,1); iOS/Version 6.1.3 (Build 10B329)
CONTENT-LENGTH: 520
CONTENT-TYPE: text/xml; charset="utf-8"
SOAPACTION: "http://www.sonos.com/Services/1.1#getAppLink"

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.sonos.com/Services/1.1">
   <s:Header>
      <credentials xmlns="http://www.sonos.com/Services/1.1">
         <deviceId>B8-E9-37-C0-01-18:0</deviceId>
         <deviceProvider>Sonos</deviceProvider>
      </credentials>
   </s:Header>
   <s:Body>
      <getAppLink xmlns="http://www.sonos.com/Services/1.1">
         <householdId>Sonos_4czgmbzy91wJnRf8VuKB0eYPyF_1405dcfa</householdId>
         <hardware>Android 7,2</hardware>
         <osVersion>Version 7.2</osVersion>
         <sonosAppName>ACR_Nexus7,2</sonosAppName>
         <callbackPath>sonos://x-callback-url/addAccount?state=sid%3D55555%26OAuthDeviceID%3DSonos_household%26callbackPath%3D%2FaddAccount</callbackPath>   
      </getAppLink>
   </s:Body>
</s:Envelope>
```

--------------------------------

### Sonos SMAPI match command request example

Source: https://docs.sonos.com/reference/musicserviceaccounts

Example of a POST request to the Sonos SMAPI 'match' endpoint. This command is used to get the account ID of a music service user from a player. It requires household ID, a hashed user ID, nickname, and service ID.

```http
POST {protocol}://api.ws.sonos.com/control/api/{version}/households/{householdId}/musicServiceAccounts/match

{
  "userIdHashCode": "opaque_user_hash",
  "nickname": "My Music Service Account",
  "serviceId": "service_id_123",
  "linkCode": null,
  "linkDeviceId": null
}

Headers:
X-Sonos-Corr-Id: <uuid>
```

--------------------------------

### Sonos Two-Button Rating Implementation Example

Source: https://docs.sonos.com/docs/configure-ratings

Example demonstrating the configuration for a two-button rating system in Sonos. It involves setting up multiple actions with thumbs-up/thumbs-down icons and associated states.

```text
First Action State
First Action Input| Second Action Input  
---
|   
**Second Action State**
First Action Input| Second Action Input  
---
|   
**Third Action State**
First Action Input| Second Action Input  
---
|   
```

--------------------------------

### SMAPI SOAP Envelope Example with Header

Source: https://docs.sonos.com/docs/soap-request-and-response

An example of a complete SOAP envelope including both credentials and context elements in the header.

```APIDOC
## SMAPI SOAP Envelope Example

### Description

This example demonstrates a full SOAP envelope with both `credentials` and `context` elements included in the SOAP header, as required by SMAPI.

### Method

Not Applicable (SOAP Request)

### Endpoint

Not Applicable (SOAP Request)

### Parameters

(See individual element documentation for detailed parameter breakdown)

### Request Example

```xml
<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>
      <loginToken>
        <token>YOUR_AUTH_TOKEN</token>
        <key>YOUR_REFRESH_TOKEN</key>
        <householdId>YOUR_HOUSEHOLD_ID</householdId>
      </loginToken>
    </credentials>
    <context xmlns="http://www.sonos.com/Services/1.1">
      <timeZone>-05:00</timeZone>
      <contentFiltering>
        <explicit>true</explicit>
      </contentFiltering>
    </context>
  </s:Header>
  <s:Body>
    <!-- Your SMAPI request body content here -->
  </s:Body>
</s:Envelope>
```

### Response

Not Applicable (This is a request example)

```

--------------------------------

### Account Matching Workflow Overview

Source: https://docs.sonos.com/docs/account-matching

Provides a high-level overview of the account matching process within the Sonos Direct Control integration.

```APIDOC
## Account Matching Workflow Overview

### Description
This section outlines the general workflow for account matching in the Sonos Direct Control integration, detailing the sequence of events and interactions between the music service and Sonos.

### Method
Not Applicable (Describes a workflow, not a specific endpoint)

### Endpoint
Not Applicable

### Parameters
Not Applicable

### Request Example
Not Applicable

### Response
Not Applicable
```

--------------------------------

### Cloud Queue Implementation for Sonos Track Lists

Source: https://docs.sonos.com/docs/account-matching

Details the necessity of a cloud queue to serve lists of tracks to Sonos players, providing a sample implementation reference and further details on audio playback.

```text
A cloud queue to serve the list of tracks to Sonos players. See our cloud queue sample server for a sample implementation and Play audio for details about cloud queues.
```

--------------------------------

### Sonos Direct Control - User Info for Account Matching

Source: https://docs.sonos.com/docs/account-matching

Illustrates how Sonos players retrieve and use the userInfo object for account matching, including populating hashed user info for pre-existing accounts via getUserInfo.

```text
When a guest uses your app to play content on Sonos, the player gets the elements of the userInfo object in the match command (the match command contains a deconstructed version of the userInfo object).

Players call getUserInfo to populate the hashed user info for pre-existing accounts. For example, an owner may have added an account to their household before you implemented userInfo. Therefore, you must implement getUserInfo.
```

--------------------------------

### Prerequisites for Sonos Direct Control Implementation

Source: https://docs.sonos.com/docs/account-matching

Outlines the essential requirements for integrating a music service with Sonos Direct Control, including account matching, authentication, and playback capabilities.

```APIDOC
## Prerequisites for Sonos Direct Control Implementation

### Description
To utilize Sonos account matching, an existing SMAPI implementation is required for authorization and content. Key prerequisites include:

*   **`userInfo` Object Support**: Implement the `userInfo` object in `getDeviceAuthToken` response and handle it in the `match` command. Ensure `getUserInfo` is implemented to populate hashed user info for pre-existing accounts. Enable the `userInfo` capability.
*   **Authentication**: Implement browser authentication to authenticate Sonos listeners.
*   **Music Playback**: Support music playback using a music service endpoint and the `getMediaURI` method for static content.
*   **Info View**: Implement `getExtendedMetadata` and `getExtendedMetadataText` for displaying additional track information.
*   **Cloud Queue**: Maintain a cloud queue to serve track lists to Sonos players. A sample server is available.
*   **Service ID**: Know your service ID for testing and production. Obtain it from Sonos during integration.

### Method
Not Applicable (Describes prerequisites, not specific endpoints)

### Endpoint
Not Applicable

### Parameters
Not Applicable

### Request Example
Not Applicable

### Response
Not Applicable
```

--------------------------------

### Get Metadata Status (Ruby)

Source: https://docs.sonos.com/reference/playbackmetadata

Ruby implementation for fetching Sonos metadata status. This example uses the 'net/http' library to perform the GET request.

```ruby
require 'net/http'
require 'uri'

def get_metadata_status(group_id, token)
  uri = URI.parse("https://api.ws.sonos.com/control/api/v1/groups/#{group_id}/playbackMetadata")
  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true
  request = Net::HTTP::Get.new(uri.request_uri)
  request['accept'] = 'application/json'
  request['authorization'] = "Bearer #{token}"

  response = http.request(request)
  if response.code != '200'
    raise "HTTP error! status: #{response.code}"
  end
  JSON.parse(response.body)
end
```

--------------------------------

### Music Playback with getMediaURI for Sonos

Source: https://docs.sonos.com/docs/account-matching

Outlines the implementation of music playback using a music service endpoint and the getMediaURI method, which is necessary for serving static content to Sonos players.

```text
Music playback using a music service endpoint and the getMediaURI method to serve static content.
```

--------------------------------

### Example Sonos Cloud API Request URL

Source: https://docs.sonos.com/docs/control

An example of a specific API request to create a group within a household. This demonstrates how to fill in the placeholders from the general URL structure.

```HTTP
https://api.ws.sonos.com/control/api/v1/households/{householdId}/groups/createGroup
```

--------------------------------

### Get Metadata Status (PHP)

Source: https://docs.sonos.com/reference/playbackmetadata-getmetadatastatus-groupid

A PHP example for retrieving Sonos metadata status, utilizing cURL functions to send a GET request to the specified API endpoint.

```PHP
<?php

function getMetadataStatus($groupId) {
    $url = "https://api.ws.sonos.com/control/api/v1/groups/{$groupId}/playbackMetadata";

    $ch = curl_init($url);

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array(
        'Accept: application/json'
        // Add any other required headers like Authorization
    ));

    $response = curl_exec($ch);

    if (curl_errno($ch)) {
        echo 'Curl error: ' . curl_error($ch);
        curl_close($ch);
        return null;
    }

    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode == 200) {
        return json_decode($response, true);
    } else {
        echo "HTTP Error: " . $httpCode . "\n";
        return null;
    }
}

// Example usage:
// $groupId = 'YOUR_GROUP_ID';
// $metadata = getMetadataStatus($groupId);
// if ($metadata) {
//     print_r($metadata);
// }

?>
```

--------------------------------

### Enable userInfo Capability for Sonos Service

Source: https://docs.sonos.com/docs/account-matching

Details the process of enabling the 'userInfo' capability for a music service to facilitate account matching and personalization within the Sonos ecosystem. Refer to 'Test your service' for specific instructions.

```text
Enable the `userInfo` capability for your service. See Test your service for details.
```

--------------------------------

### Get Metadata Status (PHP)

Source: https://docs.sonos.com/reference/playbackmetadata

PHP code example for retrieving metadata status from Sonos API. It uses cURL functions to send the GET request and handle the response.

```php
<?php

function getMetadataStatus(string $groupId, string $token): array {
    $url = "https://api.ws.sonos.com/control/api/v1/groups/{$groupId}/playbackMetadata";
    
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'accept: application/json',
        "authorization: Bearer {$token}"
    ]);

    $response = curl_exec($ch);
    
    if (curl_errno($ch)) {
        throw new Exception('cURL error: ' . curl_error($ch));
    }
    
    $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    if ($http_code !== 200) {
        throw new Exception("HTTP error! Status: {$http_code}");
    }

    curl_close($ch);
    return json_decode($response, true);
}

?>
```

--------------------------------

### Cloud Queue Base URL Example

Source: https://docs.sonos.com/docs/cloud-queue-play-audio

An example of a Cloud Queue base URL, including the service path and API version. The version number indicates compatibility with specific API functionalities.

```plaintext
https://www.example.com/musicqueue/v2.1/
```

--------------------------------

### Sonos Playback Success Example (HTTP POST)

Source: https://docs.sonos.com/docs/control

Demonstrates a successful HTTP POST request to initiate playback on a specified Sonos group. Includes example request and response headers and a minimal JSON body.

```HTTP
POST /groups/RINCON_00012345678001400:0/playback:1/play HTTP/1.1
Host: api.ws.sonos.com/control/v1
Content-Type: application/json
Authorization: Bearer <token>
User-Agent: Apache-HttpClient/4.5.10 (Java/1.8.0_162)


```

```HTTP
HTTP/1.1 200 OK
Access-Control-Allow-Origin: 
Content-Type: application/json
Server: Apache-Coyote/1.1
X-Sonos-Group-Id: RINCON_00012345678001400:0
X-Sonos-Household-Id: Sonos_1bdj48fbvjJDSkwO90djantsse948J.GNR-OWd0284lDeq325dk
X-Sonos-MAC: 0003dk59fj23
X-Sonos-Type: none
X-Sonos-User-Id: 2049233325
Content-Length: 2
Expires: Mon, 30 Jul 2018 20:28:32 GMT
Cache-Control: max-age=0, no-cache, no-store
Pragma: no-cache
Date: Mon, 30 Jul 2018 20:28:32 GMT
Connection: close

{}
```

--------------------------------

### Get Metadata Status (Node.js)

Source: https://docs.sonos.com/reference/playbackmetadata-getmetadatastatus-groupid

Example of fetching metadata status using Node.js, likely with a library like 'axios' or the built-in 'fetch'. It shows making a GET request to the Sonos API endpoint.

```JavaScript
// Node.js example (requires a fetch implementation or library like axios)
// const fetch = require('node-fetch'); // or import fetch from 'node-fetch';

async function getMetadataStatus(groupId) {
    const url = `https://api.ws.sonos.com/control/api/v1/groups/${groupId}/playbackMetadata`;
    try {
        const response = await fetch(url, {
            method: 'GET',
            headers: {
                'accept': 'application/json'
                // Add any other required headers like Authorization
            }
        });
        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        const data = await response.json();
        return data;
    } catch (error) {
        console.error('Error fetching metadata status:', error);
        throw error;
    }
}

// Example usage:
// getMetadataStatus('YOUR_GROUP_ID').then(data => console.log(data)).catch(err => console.error(err));
```

--------------------------------

### Sonos API: Example 'queueCompleted' Reason Request

Source: https://docs.sonos.com/reference/reason-parameter

An example of a Sonos player sending a GET /itemWindow request with the reason 'queueCompleted'. This signifies that the player has finished fetching audio for the current window and is checking for more tracks.

```plaintext
GET /itemWIndow?reason=queueCompleted
```

--------------------------------

### GET /cloudqueue/v2.0/context

Source: https://docs.sonos.com/reference/context

Players request the playback context to get information about the playback conditions, such as the container type, metadata, versions, playback policies, and reporting options. For example, the container type could be a program on a radio station or a playlist.

```APIDOC
## GET /cloudqueue/v2.0/context

### Description
Players request the playback context to get information about the playback conditions, such as the container type, metadata, versions, playback policies, and reporting options. For example, the container type could be a program on a radio station or a playlist.

### Method
GET

### Endpoint
/cloudqueue/v2.0/context

### Parameters
#### Query Parameters
- **contextVersion** (string) - Required - Indicates the current state of the context. This string identifies when the player fetched the current context. Your server can ignore this field or trigger special processing to sync if it differs from the expected value.
- **queueVersion** (string) - Required - Indicates the current state of the queue. This string identifies when the player fetched the current queue. Your server can ignore this field or trigger special processing to sync if it differs from the expected value.

### Request Example
```json
{
  "example": "GET https://www.example.com/cloudqueue/v2.0/context?contextVersion=cv123&queueVersion=qv102"
}
```

### Response
#### Success Response (200)
- **contextVersion** (string) - Description
- **queueVersion** (string) - Description
- **container** (object) - Description
  - **type** (string) - Description
  - **name** (string) - Description
  - **id** (object) - Description
  - **service** (object) - Description
- **reports** (object) - Description
  - **sendUpdateAfterMillis** (integer) - Description (Defaults to 0)
  - **sendPlaybackActions** (boolean) - Description (Defaults to true)
  - **playbackPolicies** (object) - Description
    - **canSkip** (boolean) - Description (Defaults to true)
    - **limitedSkips** (boolean) - Description (Defaults to true)
    - **canSkipToItem** (boolean) - Description (Defaults to true)
    - **canSkipBack** (boolean) - Description (Defaults to true)
    - **canSeek** (boolean) - Description (Defaults to true)
    - **canRepeat** (boolean) - Description (Defaults to true)
    - **canRepeatOne** (boolean) - Description (Defaults to true)
    - **canCrossfade** (boolean) - Description (Defaults to true)
    - **canShuffle** (boolean) - Description (Defaults to true)
    - **showNNextTracks** (integer) - Description (Defaults to 0)
    - **showNPreviousTracks** (integer) - Description (Defaults to 0)

#### Response Example
```json
{
  "example": "{\n  \"contextVersion\": \"string\",\n  \"queueVersion\": \"string\",\n  \"container\": {\n    \"type\": \"string\",\n    \"name\": \"string\",\n    \"id\": {\n      \"service\": {}\n    },\n    \"service\": {}\n  },\n  \"reports\": {\n    \"sendUpdateAfterMillis\": 0,\n    \"sendPlaybackActions\": true,\n    \"playbackPolicies\": {\n      \"canSkip\": true,\n      \"limitedSkips\": true,\n      \"canSkipToItem\": true,\n      \"canSkipBack\": true,\n      \"canSeek\": true,\n      \"canRepeat\": true,\n      \"canRepeatOne\": true,\n      \"canCrossfade\": true,\n      \"canShuffle\": true,\n      \"showNNextTracks\": 0,\n      \"showNPreviousTracks\": 0\n    }\n  }\n}"
}
```
```

--------------------------------

### Sonos Account Options

Source: https://docs.sonos.com/docs/account-matching

Details the options available to Sonos owners for managing their music and playlists within Sonos itself.

```APIDOC
## Sonos Account Options

### Description
Sonos owners can choose specific options for their Sonos accounts, such as adding songs to Sonos Favorites or Playlists, searching for songs, and sharing songs.

### Method
Not Applicable (Describes features, not a specific endpoint)

### Endpoint
Not Applicable

### Parameters
Not Applicable

### Request Example
Not Applicable

### Response
Not Applicable
```

--------------------------------

### Sonos Initial GET Request for Audio File

Source: https://docs.sonos.com/docs/playback-on-sonos

Demonstrates the initial HTTP GET request a Sonos player makes to retrieve an audio file from a music service. Includes the 'Referer' header to identify the source as Sonos.

```PowerShell
GET
http://acme.example.com/music/t_85787.mp3
Referer:sonos-mymusicservice.example.com
```

--------------------------------

### v2.0 Item Attributes - Update Report Example

Source: https://docs.sonos.com/reference/v20-item-attributes

This JSON example shows the structure for an 'update' type report for an item in the 'items' array. It reflects the current playback state, including updated duration played, time since playback started, and playhead positions.

```JSON
{
  "items":[
    {
      "id":"this_is_the_cloud_queue_item_id",
      "mediaUrl":"http://media.host.example.com/path/12345.mp3",
      "queueVersion":"xyz",
      "type":"update",
      "durationPlayedMillis":31914,
      "timeSincePlaybackMillis":33742,
      "positionMillis":45000,
      "positionMillisAtSegmentStart":14000
    },
    "..."
  ]
}
```

--------------------------------

### Get Metadata

Source: https://docs.sonos.com/docs/add-search

Retrieves metadata for a specified container, used by the Sonos app to display categories like 'Songs' or 'Artists'.

```APIDOC
## POST /websites/sonos/metadata

### Description
This endpoint is used by the Sonos application to request metadata for a given container ID. It helps in fetching categories or items to be displayed to the user.

### Method
POST

### Endpoint
/websites/sonos/metadata

### Parameters
#### Request Body
- **id** (string) - Required - The identifier of the container for which to retrieve metadata (e.g., 'search').
- **index** (integer) - Required - The starting index for the metadata items.
- **count** (integer) - Required - The number of metadata items to retrieve.

### Request Example
```xml
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.sonos.com/Services/1.1">
   <soapenv:Header>
      <ns:credentials>
        ...
      </ns:credentials>
   </soapenv:Header>
   <soapenv:Body>
      <ns:getMetadata>
         <ns:id>search</ns:id>
         <ns:index>0</ns:index>
         <ns:count>10</ns:count>
      </ns:getMetadata>
   </soapenv:Body>
</soapenv:Envelope>
```

### Response
#### Success Response (200)
- **index** (integer) - The starting index of the returned metadata.
- **count** (integer) - The number of metadata items returned.
- **total** (integer) - The total number of available metadata items.
- **mediaCollection** (array) - An array of media collection objects.
  - **id** (string) - Unique identifier for the media collection.
  - **itemType** (string) - Type of the item (e.g., 'search').
  - **title** (string) - Display title for the media collection.
  - **canPlay** (boolean) - Indicates if the item can be played.
  - **canEnumerate** (boolean) - Indicates if the item can be enumerated.
  - **albumArtURI** (string) - URI for the album art.

#### Response Example
```xml
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.sonos.com/Services/1.1">
   <s:Body>
      <ns:getMetadataResponse>
         <ns:getMetadataResult>
            <ns:index>0</ns:index>
            <ns:count>2</ns:count>
            <ns:total>2</ns:total>
            <ns:mediaCollection>
               <ns:id>search:songs</ns:id>
               <ns:itemType>search</ns:itemType>
               <ns:title>Songs</ns:title>
               <ns:canPlay>false</ns:canPlay>
               <ns:albumArtURI/>
            </ns:mediaCollection>
            <ns:mediaCollection>
               <ns:id>search:artists</ns:id>
               <ns:itemType>search</ns:itemType>
               <ns:title>Artists</ns:title>
               <ns:canPlay>false</ns:canPlay>
               <ns:albumArtURI/>
            </ns:mediaCollection>
         </ns:getMetadataResult>
      </ns:getMetadataResponse>
   </s:Body>
</s:Envelope>
```
```

--------------------------------

### Best Practices for getMediaURI

Source: https://docs.sonos.com/reference/getmediauri

Guidelines and recommendations for implementing the getMediaURI endpoint, including tracking user actions and encrypting content for DRM.

```APIDOC
## Best Practices for getMediaURI

### Use implicit and explicit actions to track user actions
Implement implicit and explicit actions to monitor user interactions with media playback on Sonos. Explicit actions are those chosen directly by the user (e.g., play, seek, skip), while implicit actions are initiated by the Sonos system (e.g., playing the next song in a queue).

To receive these actions, enable the "Support the ability to receive implicit or explicit actions for `getMediaURI` requests" capability in your service configuration. This is particularly useful if you limit concurrent streaming devices, as a Sonos Household counts as one device.

### Encrypt tracks for Digital Rights Management (DRM)
Secure your audio content by encrypting tracks accessed by Sonos. Provide decryption details to Sonos through the fields in the `getMediaURI` response, specifically `deviceSessionKey` and `contentKey`.

For audio delivered via HLS, Sonos players will make `getContentKey` requests for keys to decrypt individual segments. Ensure your implementation handles these requests according to the SMAPI object types and encryption details.
```

--------------------------------

### Localization File Example for Custom Actions (i18next)

Source: https://docs.sonos.com/docs/add-actions

Example of a localization file using the i18next format to define display text for custom actions in the Sonos Info View. This allows for user-friendly labels for features like 'About the Artist' or 'Start Radio'.

```json
{
    "en-US":{
      "common":{
          ...
          },
      "integration":{
        "ABOUT_ARTIST": "About the Artist",
        "RELATED_SONGS": "Related Songs",
        "START_RADIO": "Start Radio",
        "CONCERTS": "Concerts",
        "SAVE_MUSIC": "Save to My Acme Music",
        ...
      }
    },
}
```

--------------------------------

### Sonos API Target Objects and Sample Paths

Source: https://docs.sonos.com/docs/control

This section provides examples of how to construct API paths for different target object types in the Sonos ecosystem, such as households, groups, sessions, and players.

```HTTP
/households/[householdId]
```

```HTTP
/groups/[groupId]
```

```HTTP
/playbackSessions/[sessionId]
```

```HTTP
/players/[playerId]
```

--------------------------------

### Sonos SMAPI Full SOAP Envelope Example

Source: https://docs.sonos.com/docs/soap-requests-and-responses

Provides a complete example of a SOAP envelope including both the <credentials> and <context> elements within the SOAP header for a Sonos SMAPI request.

```XML
<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>
  </s:Header>
  <s:Header>
    <context xmlns="http://www.sonos.com/Services/1.1">
      <timeZone>
        -05:00
      </timeZone>
      <contentFiltering>
        <explicit>
          true
        </explicit>
      </contentFiltering>
    </context>
  </s:Header>
  <s:Body>
    ...
  </s:Body>
</s:Envelope>
```

--------------------------------

### Sonos Player Configuration Example

Source: https://docs.sonos.com/reference/groups-object

This JSON snippet shows the configuration for a single Sonos player. It includes the player's ID, name, icon, websocket URL for communication, software version, device IDs, API version, minimum API version, and supported capabilities.

```json
{
      "id": "RINCON_8HJLQE01RW4B21097", // PlayroomPlayerId
      "name": "Playroom",
      "icon": "playroom",
      "websocketUrl": "wss://192.168.55.135:1443/websocket/api",
      "softwareVersion": "38.5-43170-DevPreview",
      "deviceIds": [
        "RINCON_8HJLQE01RW4B21097" // PlayroomPlayerId
      ],
      "apiVersion": "1.0.0-DevPreview+1234",
      "minApiVersion": "1.0.0",
      "capabilities" : [
        "PLAYBACK",
        "CLOUD"
      ]
    }
```

--------------------------------

### Get Metadata for Root Container

Source: https://docs.sonos.com/docs/content-on-sonos

This endpoint retrieves metadata for the root container of the Sonos service. It allows specifying the starting index and the number of items to retrieve.

```APIDOC
## POST /websites/sonos/getMetadata

### Description
Retrieves metadata for the root container, including a list of media collections.

### Method
POST

### Endpoint
/websites/sonos

### Parameters
#### Request Body
- **id** (string) - Required - The ID of the container to retrieve metadata for (e.g., "root").
- **index** (integer) - Required - The starting index for the list of items.
- **count** (integer) - Required - The number of items to return.

### Request Example
```xml
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope">
  <soap:Body>
    <getMetadata xmlns="http://www.sonos.com/Services/1.1">
      <id>root</id>
      <index>0</index>
      <count>100</count>
    </getMetadata>
  </soap:Body>
</soap:Envelope>
```

### Response
#### Success Response (200)
- **index** (integer) - The starting index of the returned list.
- **count** (integer) - The number of items returned in this list.
- **total** (integer) - The total possible items in the list.
- **mediaCollection** (array) - An array of media collection objects.
  - **id** (string) - The content ID of the media item.
  - **itemType** (string) - The type of the media collection (e.g., "container", "albumList", "trackList").
  - **title** (string) - The display title for the media item.
  - **summary** (string) - A summary or description of the media item.
  - **albumArtURI** (string) - The URI for the album art.

#### Response Example
```xml
<Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.sonos.com/Services/1.1">
  <Body>
    <getMetadataResponse>
      <getMetadataResult>
        <index>0</index>
        <count>5</count>
        <total>5</total>
        <mediaCollection>
          <id>artists</id>
          <itemType>container</itemType>
          <title>Artists</title>
          <summary>Choose music based on your preferred artist.</summary>
          <albumArtURI>https://acmemusic.example.com/assets/images/artists.jpg</albumArtURI>
        </mediaCollection>
        <mediaCollection>
          <id>albums</id>
          <itemType>albumList</itemType>
          <title>Albums</title>
          <summary>Choose an album to play.</summary>
          <albumArtURI>https://acmemusic.example.com/assets/images/albums.jpg</albumArtURI>
        </mediaCollection>
        <mediaCollection>
          <id>composers</id>
          <itemType>container</itemType>
          <title>Composers</title>
          <summary>Choose music based on your preferred composer.</summary>
          <albumArtURI>https://acmemusic.example.com/assets/images/composers.jpg</albumArtURI>
        </mediaCollection>
        <mediaCollection>
          <id>genres</id>
          <itemType>container</itemType>
          <title>Genres</title>
          <summary>Choose a musical genre.</summary>
          <albumArtURI>https://acmemusic.example.com/assets/images/genres.jpg</albumArtURI>
        </mediaCollection>
        <mediaCollection>
          <id>songs</id>
          <itemType>trackList</itemType>
          <title>Songs</title>
          <summary>Choose a song.</summary>
          <albumArtURI>https://acmemusic.example.com/assets/images/songs.jpg</albumArtURI>
        </mediaCollection>
      </getMetadataResult>
    </getMetadataResponse>
  </Body>
</Envelope>
```
```

--------------------------------

### Get Volume (cURL)

Source: https://docs.sonos.com/reference/groupvolume-getvolume-groupid

Example of how to retrieve the volume and mute state of a Sonos group using cURL. Requires a valid groupId and the 'accept: application/json' header.

```shell
curl --request GET \
     --url https://api.sonos.com/control/api/v1/groups/groupId/groupVolume \
     --header 'accept: application/json'
```

--------------------------------

### Container Hierarchy Example

Source: https://docs.sonos.com/docs/cs-content-on-sonos

Illustrates a typical browsing path within the Sonos app, showing how a user navigates from a music service's root container through various media collections (like albums) to reach a playable media item (a track). This structure helps in understanding the flow of content requests and responses.

```text
Container Hierarchy| Items in Container| Item Metadata| Item Type| Item Description  
---|---|---|---|---
Browse| Music Service| `mediaCollection`| container| The service name at the top of the content hierarchy. The user selects this from the Sonos app’s top-level list of services to browse into this service’s root container.  
.../Music Service| Albums| `mediaCollection`| albumList| A collection identifying a list of albums. The user selects the **Albums** collection from the root container to browse into a new **Albums** container holding a list of albums.  
.../.../Albums| The Rocks 1st Album| `mediaCollection`| album| A collection identifying an album. The user selects **The Rocks 1st Album** collection from the **Albums** container to browse into a new **The Rocks 1st Album** container holding a list of songs that are on the album.  
.../.../.../The Rocks 1st Album| Satisfy  
  
Artificial Sugar| `mediaMetadata`| track| The song is a playable item track. The user selects a playable item such as **Satisfy** from the **The Rocks 1st Album** container to choose the track.
```

--------------------------------

### Get Metadata Status (Node.js)

Source: https://docs.sonos.com/reference/playbackmetadata

Example of fetching metadata status using Node.js, typically with a library like 'node-fetch'. This snippet shows how to construct the request and handle the response.

```javascript
async function getMetadataStatus(groupId, token) {
  const url = `https://api.ws.sonos.com/control/api/v1/groups/${groupId}/playbackMetadata`;
  const response = await fetch(url, {
    method: 'GET',
    headers: {
      'accept': 'application/json',
      'authorization': `Bearer ${token}`
    }
  });
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  return await response.json();
}
```

--------------------------------

### Load Audio Clip Request Example

Source: https://docs.sonos.com/reference/audioclip

This example demonstrates how to schedule an audio clip for playback on a Sonos player using the loadAudioClip API command. It includes essential parameters such as playerId, name, appId, priority, and streamUrl.

```curl
curl -X POST https://api.ws.sonos.com/control/api/v1/players/{playerId}/audioClip \
  -H "Content-Type: application/json" \
  -d '{ 
    "name": "MyClipName", 
    "appId": "com.example.app", 
    "priority": "HIGH", 
    "streamUrl": "http://example.com/audio.mp3", 
    "volume": 80, 
    "clipLEDBehavior": "WHITE_LED_QUICK_BREATHING" 
  }'
```

--------------------------------

### getAppLink Request Example (XML)

Source: https://docs.sonos.com/docs/add-browser-authentication

An example of a getAppLink request sent from the Sonos app to a music service. It includes headers and the SOAP envelope containing householdId, hardware details, and callback information.

```XML
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.sonos.com/Services/1.1">
   <s:Header>
      <ns:context>
      </ns:context>
      <ns:credentials>
      </ns:credentials>
   </s:Header>
   <s:Body>
      <ns:getAppLink>
         <ns:householdId>Sonos_ghsAflSonosakevCzmxcmFhN7pN</ns:householdId>
         <ns:hardware>iPhone8,2</ns:hardware>
         <ns:osVersion>Version 9.3.3 (Build 13G34)</ns:osVersion>
         <ns:sonosAppName>ICRU_iPhone8,2</ns:sonosAppName>
         <ns:callbackPath>sonos://x-callback-url/addAccount?state=sid%3D61703%26OAuthDeviceID%3DSonos_ghsAflSonosakevCzmxcmFhN7pN%26callbackPath%3D%2FaddAccount</ns:callbackPath>
      </ns:getAppLink>
   </s:Body>
</s:Envelope>
```

--------------------------------

### getMediaURI Request for Track Playback (XML)

Source: https://docs.sonos.com/docs/playback-on-sonos

Example of a SOAP request made by a Sonos player to a service to get the media URI for a specific track. It includes the track's content ID.

```XML
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.sonos.com/Services/1.1">
  <soap:Header>
   ...
  </soap:Header>
  <soap:Body>
    <ns:getMediaURI>
      <ns:id>t_85787</ns:id>
    </ns:getMediaURI>
  </soap:Body>
</soap:Envelope>
```

--------------------------------

### GET /getMetadata (Example for Root Container)

Source: https://docs.sonos.com/docs/content-on-sonos

When a user selects the 'Music Service' from the Sonos app, a `getMetadata` request is made with the content ID `root` to retrieve the top-level container's content.

```APIDOC
## GET /getMetadata

### Description
Retrieves metadata for a given content ID, typically used when a user navigates through the Sonos app's browse interface.

### Method
GET

### Endpoint
`/getMetadata`

### Parameters
#### Query Parameters
- **id** (string) - Required - The content ID of the item to retrieve metadata for. For the top-level music service container, this is `"root"`.

### Request Example
```
GET /getMetadata?id=root HTTP/1.1
Host: your-service.com

```

### Response
#### Success Response (200)
- **response** (object) - Contains a list of `mediaCollection` or `mediaMetadata` objects.
  - **mediaCollection** (array) - A list of collections available within the specified container.
  - **mediaMetadata** (array) - A list of media items (e.g., tracks) available within the specified container.

#### Response Example (for id=root)
```json
{
  "response": {
    "mediaCollection": [
      {
        "@type": "musicService/albums",
        "title": "Albums",
        "contentId": "albums"
      },
      {
        "@type": "musicService/artists",
        "title": "Artists",
        "contentId": "artists"
      }
    ]
  }
}
```
```

--------------------------------

### Sonos Personalization Options

Source: https://docs.sonos.com/docs/account-matching

Describes how Sonos owners and guests can personalize music playback through the Sonos app, depending on whether they have an account with the music service.

```APIDOC
## Sonos Personalization Options

### Description
Sonos owners with an account can personalize music playback via the Sonos app. This includes options like adding songs to playlists, starting radio stations, managing favorites, browsing artist/album info, and rating songs.

If the owner does not have an account, users have limited options, primarily searching for songs in existing libraries or sharing them.

### Method
Not Applicable (Describes features, not a specific endpoint)

### Endpoint
Not Applicable

### Parameters
Not Applicable

### Request Example
Not Applicable

### Response
Not Applicable
```

--------------------------------

### setVolume API Command Example (POST)

Source: https://docs.sonos.com/reference/groupvolume

This snippet demonstrates the POST request to the setVolume API endpoint. It includes the base URL structure, path parameters, and a sample request body for setting the volume of a Sonos group.

```HTTP
POST {protocol}://api.ws.sonos.com/control/api/{version}/groups/{groupId}/groupVolume

{
  "volume": 50
}
```

--------------------------------

### Sonos API cURL Request Example

Source: https://docs.sonos.com/reference/playback-getplaybackstatus-groupid

This snippet demonstrates how to make a GET request to the Sonos API to retrieve playback information for a group. It includes the necessary URL, headers, and authentication method.

```shell
curl --request GET \
     --url https://api.ws.sonos.com/control/api/v1/groups/groupId/playback \
     --header 'accept: application/json'
```
Tokens:
Raw