Music on hold

Whenever someone is on hold — a plain hold, a caller waiting while you consult a transfer target, or part of a conference you split off — they hear music, and nothing of the call. The music player is a participant only the held parties can hear.

Which playlist plays#

The holding extension's playlist (moh_playlist_id on the extension),
else the tenant default playlist,
else the built-in ScaiLabs Classics: public-domain piano recordings (Satie, Debussy, Mozart, Schubert).

A playlist without tracks is skipped. Playlists loop; with shuffle on they play in random order, otherwise in the order you set.

Three kinds of playlist#

`scope`	Who manages it	Who can use it
`platform`	ScaiLabs (read-only)	everyone
`tenant`	tenant admins (`scaidial:trunks:manage`); one can be the tenant default	every extension in the tenant
`personal`	the user who made it	extensions that user manages

Tenant admins manage playlists on ScaiDial → Music on hold; ScaiWave users manage their personal playlists in ScaiWave.

Uploading music#

bash
# Create a playlist (admins get a tenant playlist; others a personal one, or pass "personal": true)
PL=$(curl -s -X POST $SCAIDIAL/moh/playlists -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"name": "Reception", "shuffle": true}' | jq -r .data.id)

# Upload a song. rights_confirmed=true is required.
curl -s -X POST $SCAIDIAL/moh/playlists/$PL/tracks -H "$AUTH" \
  -F file=@"spring-theme.mp3" -F rights_confirmed=true -F title="Spring theme" -F artist="Our band"

# Make it the tenant default
curl -s -X PATCH $SCAIDIAL/moh/playlists/$PL -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"is_default": true}'

Formats: MP3, WAV, FLAC, OGG/Opus, M4A/AAC.
Limits: 40 MB and 15 minutes per file, at least 5 seconds; 50 tracks per playlist; 20 tenant playlists and 5 personal playlists per user.
Conversion: tracks are mixed to mono, converted to phone quality (16 kHz) and levelled to a calm volume, so loud and quiet songs play at the same level.
Rights: whoever uploads confirms the tenant may play the music to callers (own recordings, licensed or royalty-free music). The confirmation is recorded with their user id. Commercial music usually needs a licence for public playback.

Endpoints#

Method + path	Does
`GET /moh/playlists`	Platform, tenant and your own playlists (admins also see users' personal ones), plus the upload limits
`POST /moh/playlists`	`{name, shuffle?, personal?}`
`PATCH /moh/playlists/{id}`	`{name?, shuffle?, is_default?}` (`is_default`: admins, tenant playlists)
`DELETE /moh/playlists/{id}`	Deletes it and its tracks; extensions using it fall back to the tenant default
`GET /moh/playlists/{id}/tracks`	Tracks in play order
`POST /moh/playlists/{id}/tracks`	Multipart upload: `file`, `rights_confirmed=true`, `title?`, `artist?`
`PUT /moh/playlists/{id}/order`	`{track_ids: [...]}` — every track once, in the new order
`DELETE /moh/tracks/{id}`	Removes a track
`GET /moh/tracks/{id}/audio`	The converted track (`audio/flac`) to preview

Playlist: id, name, scope, owner_user_id, shuffle, is_default, track_count, duration_ms, editable. Track: id, playlist_id, title, artist, duration_ms, size_bytes, position, license, source_url, created_at.

Choosing a playlist for an extension#

PATCH /extensions/{id} with {"moh_playlist_id": "<playlist id>"} ("" = the tenant default), or the Music on hold field in the extension form. Users can choose for extensions they manage in ScaiWave.