v1

latestOpenAPI 3.1.02026-07-246652306.5 KB

audioClip

loadAudioClip

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.

post/players/{playerId}/audioClip

Request body

namestring required

User identifiable string.

appIdstring required

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'LOW' | 'HIGH'

Sonos uses this enumeration to order concurrent clips.

clipType'CHIME' | 'CUSTOM' | 'VOICE_ASSISTANT'

This enumeration identifies the sounds that are built into the Sonos firmware. Partners are free to use these sounds with the loadAudioClip command instead of providing custom files.

streamUrlstring nullable

(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.

httpAuthorizationstring nullable

(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.

volumeinteger nullable

(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'NONE' | 'WHITE_LED_QUICK_BREATHING'

This enumeration identifies the led patterns that are built into the Sonos firmware. Partners are free to use these led patterns along with the sound in loadAudioClip command.

Response

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

idstring required

The unique identifier for the audio clip.

namestring required

User identifiable string.

appIdstring required

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'LOW' | 'HIGH' required

Sonos uses this enumeration to order concurrent clips.

clipType'CHIME' | 'CUSTOM' | 'VOICE_ASSISTANT'

This enumeration identifies the sounds that are built into the Sonos firmware. Partners are free to use these sounds with the loadAudioClip command instead of providing custom files.

This enumeration identifies the current status of an audio clip.

clipLEDBehavior'NONE' | 'WHITE_LED_QUICK_BREATHING' required

This enumeration identifies the led patterns that are built into the Sonos firmware. Partners are free to use these led patterns along with the sound in loadAudioClip command.

errorCodestring

(Optional) Custom error code for audio clips. See the table below for details.