Audio Control

Core Platform
audio_announce_writeAudio Control

Speaks 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

NameTypeDescription
action*"speak"What to do; each action is described in the tool description.
textstringWhat to say
langstringLanguage and accent code, for example en-gb, en-au or ja-jp
boostintegerHow much louder than the music, 0 to 50 (default 25 unless the facility set its own)
facilityIdstringFacility ID. Optional when the connected facility is the one you mean.
confirmbooleanSet only after the user confirmed the preview returned by the first call
audio_control_writeAudio Control

Plays, 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

NameTypeDescription
action*"play" | "pause" | "set_volume" | "mute" | "unmute" | "skip_next" | "skip_previous" | "play_source"What to do; each action is described in the tool description.
facilityIdstringFacility ID. Optional when the connected facility is the one you mean.
volumeintegerVolume from 0 (silent) to 100 (set_volume)
sourceIdstringsourceId from audio_status_read sources (play_source)
audio_history_readAudio Control

What 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

NameTypeDescription
action*"played" | "activity" | "settings"What to do; each action is described in the tool description.
fromstringOnly entries at or after this time (ISO 8601)
tostringOnly entries before this time (ISO 8601)
limitintegerItems per page (default 25, at most 100)
cursorstringnextCursor from the previous page
facilityIdstringFacility ID. Optional when the connected facility is the one you mean.
audio_status_readAudio Control

What 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

NameTypeDescription
action*"live" | "sources" | "alerts"What to do; each action is described in the tool description.
facilityIdstringFacility ID. Optional when the connected facility is the one you mean.
refreshbooleanAsk the speakers for their favourites now instead of the hour's cached list (sources)
limitintegerItems per page (default 25, at most 100) (sources)
cursorstringnextCursor from the previous page (sources)