Audio Control
Core Platformaudio_announce_writeAudio ControlSpeaks a message over the facility's speakers now, louder than the music, in the facility's announcement language unless lang is given. Everyone at the facility hears it, so it asks for confirmation.
Actions:
- speak: Speak now. Speaks text now. boost (how much louder than the music) is used only for callers who can change Audio Control settings; others get the facility's default. Needs text. Asks for confirmation.
Parameters
| Name | Type | Description |
|---|---|---|
action* | "speak" | What to do; each action is described in the tool description. |
text | string | What to say |
lang | string | Language and accent code, for example en-gb, en-au or ja-jp |
boost | integer | How much louder than the music, 0 to 50 (default 25 unless the facility set its own) |
facilityId | string | Facility ID. Optional when the connected facility is the one you mean. |
confirm | boolean | Set only after the user confirmed the preview returned by the first call |
audio_control_writeAudio ControlPlays, pauses, changes the volume or source of the facility's speakers, mutes, or skips tracks now. Volume is held to the caller's limit (audio_status_read live youCan.volumeLimit). Get sourceIds from audio_status_read sources. The schedule can change the music again at its next change; to keep a change for a while, use a hold in the Audio Control app.
Actions:
- play: Play. Starts the music and waits until the speakers report they are playing.
- pause: Pause. Pauses the music and waits until the speakers report they have stopped. Also stops a scheduled start that is still retrying.
- set_volume: Set volume. Sets the speakers' group volume, 0 to 100, held to the caller's volume limit. Needs volume.
- mute: Mute. Mutes the speakers without pausing the music.
- unmute: Unmute. Unmutes the speakers.
- skip_next: Next track. Skips to the next track (has no effect on radio).
- skip_previous: Previous track. Goes back to the previous track (has no effect on radio).
- play_source: Play a source. Switches the speakers to a favourite, Performance Hub stream or approved source and starts it, then checks that they are playing. Where the brand or organisation blocks personal streaming services, those are refused (code SOURCE_BLOCKED); offer a business or approved source instead. Needs sourceId.
Parameters
| Name | Type | Description |
|---|---|---|
action* | "play" | "pause" | "set_volume" | "mute" | "unmute" | "skip_next" | "skip_previous" | "play_source" | What to do; each action is described in the tool description. |
facilityId | string | Facility ID. Optional when the connected facility is the one you mean. |
volume | integer | Volume from 0 (silent) to 100 (set_volume) |
sourceId | string | sourceId from audio_status_read sources (play_source) |
audio_history_readAudio ControlWhat the facility's speakers played and who changed them, newest first: tracks and announcements, play, pause, volume and source changes with who or what did them (a person, a workflow, the schedule, a member check-in, someone on site or the speakers themselves), and settings changes. Plays and activity are kept for 13 months, settings changes for two years.
Actions:
- played: Played. Tracks and announcements that played, with title, artist, album, playlist and the kind of source.
- activity: Activity. Play, pause, volume, mute, source and speaker changes, and actions people or automations asked for with their result (sent, confirmed, failed or skipped).
- settings: Settings changes. Changes to the Audio Control settings: which section, which fields and who changed them.
Parameters
| Name | Type | Description |
|---|---|---|
action* | "played" | "activity" | "settings" | What to do; each action is described in the tool description. |
from | string | Only entries at or after this time (ISO 8601) |
to | string | Only entries before this time (ISO 8601) |
limit | integer | Items per page (default 25, at most 100) |
cursor | string | nextCursor from the previous page |
facilityId | string | Facility ID. Optional when the connected facility is the one you mean. |
audio_status_readAudio ControlWhat the facility's speakers are doing now (playing or not, volume, track, source, holds), the sources they can play, and open alerts. Use it before audio_control_write: sources gives the sourceId for play_source. For what played earlier and who changed it, use audio_history_read.
Actions:
- live: Now playing. The speakers' last known state (null when they haven't been heard from for 30 days): transportState, volume, muted, track, source kind, the speakers playing together, whether the screen that runs them is online, the last error, holds in force, and youCan (changeSettings, and volumeLimit, the loudest volume the caller may set).
- sources: Sources. What the speakers can play: their favourites, Performance Hub streams and the organisation's approved sources, each with its kind (business, personal, radio, ...). Favourites are read from the speakers at most hourly unless refresh is true.
- alerts: Open alerts. Alerts open at the facility now: no music during opening hours, the screen that runs the speakers offline, or a speaker error, each with when it started. Also how many minutes of silence raise an alert and how many alert rules apply.
Parameters
| Name | Type | Description |
|---|---|---|
action* | "live" | "sources" | "alerts" | What to do; each action is described in the tool description. |
facilityId | string | Facility ID. Optional when the connected facility is the one you mean. |
refresh | boolean | Ask the speakers for their favourites now instead of the hour's cached list (sources) |
limit | integer | Items per page (default 25, at most 100) (sources) |
cursor | string | nextCursor from the previous page (sources) |