loadAudioClip

post

{protocol}://api.ws.sonos.com/control/api/{version}/players/{playerId}/audioClip

Use the loadAudioClip command in the audioClip namespace to schedule an audio clip for playback. The command returns immediately, indicating whether the audio clip was successfully scheduled or not.

The player can handle multiple audio clips and implements a simple priority system to determine playback order:

A High priority audio clip can interrupt another high priority audio clip if the latter has played for more then 10 seconds.
A high priority audio clip can interrupt a low priority audio clip at any time.
A low priority audio clip can interrupt a low priority audio clip at any time.

Path Params

playerId

string

required

Target playerId

Body Params

name

string

required

length ≤ 64

User identifiable string.

appId

string

required

length ≤ 127

This string identifies the app that created the audioClip. Companies should use their reversed Internet domain name as the identifier, similar to com.acme.app.

priority

string

enum

Priority rules: LOW cannot interrupt HIGH, all other interruptions allowed

Allowed:

clipType

string

enum

(Optional) Sonos plays a built-in sound when you send this parameter. The default value is CHIME.

Allowed:

streamUrl

string | null

(Optional) Sonos will play this URL when you provide one. The caller does not need to specify a CUSTOM clipType in addition to providing the streamUrl. Sonos supports only MP3 or WAV files as audio clips.

httpAuthorization

string | null

(Optional) Set a string to pass in the Authorization header when fetching the streamUrl. Omit this parameter to omit the Authorization header. Sonos includes the Authorization header when the streamUrl is secure (HTTPS). Sonos supports an httpAuthorization value up to 512 bytes.

volume

int32 | null

0 to 100

(Optional) Audio Clip playback volume, between 0 and 100. There are internal upper and lower limits for the audio clip volume level in order to prevent the audio clip from being too loud or inaudible. If the parameter is beyond those limits, Sonos automatically adjusts the audio clip volume to the lower or upper limit. The default behavior is to playback at the current player volume.

clipLEDBehavior

string

enum

Defaults to NONE

(Optional) Sonos shows a LED pattern along with the sound when you send this parameter. The default value is NONE.

Allowed:

Headers

X-Sonos-Api-Key

uuid

deprecated

Client API Key for the integration. Required in V1 but deprecated in V2.

X-Sonos-Corr-Id

uuid

Correlation UUID for data tracking purposes

Responses

200Returns an audioClip object, which list characteristics, including the id, of the enqueued audio clip.

400Returns an audioClip object, which list characteristics, including the id, of the enqueued audio clip.

401Returns an audioClip object, which list characteristics, including the id, of the enqueued audio clip.

403Returns an audioClip object, which list characteristics, including the id, of the enqueued audio clip.

404Returns an audioClip object, which list characteristics, including the id, of the enqueued audio clip.

499Returns an audioClip object, which list characteristics, including the id, of the enqueued audio clip.

500Returns an audioClip object, which list characteristics, including the id, of the enqueued audio clip.

503Returns an audioClip object, which list characteristics, including the id, of the enqueued audio clip.