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.

Endpoint

POST

Request parameters

This command requires a playerId to determine the target of the command. See the Control documentation for details.

See the table below for descriptions of parameters in the body.

Parameter Type Value
appId string 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.
clipType clipType (Optional) Sonos plays a built-in sound when you send this parameter. The default value is CHIME.
httpAuthorization string (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.
name string User identifiable string.
priority priority (Optional) Clip priority. Clips are low priority by default.
streamUrl string (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.
volume integer (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.

The player will uses the following rules to determine the audio clip sound:

  1. If there is a streamUrl parameter, Sonos plays this.
  2. Sonos uses the clipType parameter if there is no streamUrl.
  3. Sonos uses the CHIME clip if you do not specify the above parameters.

Response

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

In the event of a failure, returns a globalError.

Example

Request

Response