How it works
- You call a mutation with the station and one or more studios.
- VRA Cloud resolves each studio by id or by its internal name within the station.
- VRA Cloud sends an internal command to the Core of each studio over the studio bus.
- The Core applies the state and publishes its new state to VRA Cloud and all clients.
The Core needs to be online. A command to a studio without a running Core is not queued. The Core also keeps its own rules, so while the Core is in a state like standby it rejects the command like it would from the app.
Authentication
Authenticate as a Machine User of the station, or as a cloud user who has the station active. Moving studios between stations needs a machine user with Studio routing turned on, see Move a studio to another station.Addressing a studio
studio_id accepts the studio id or the studio name, the internal name of the studio in VRA Cloud. Names are matched exactly and only within the given station, so a script can use Studio_1 instead of a UUID. A studio belongs to the station it feeds right now, so after a studio moves to another station, address it with that station.
Put a studio on air
state is a StudioStateCommand: GO_ON_AIR, GO_OFF_AIR, START_RECORDING or TOGGLE. TOGGLE flips between off air and on air, and a recording studio goes off air. START_RECORDING only works for a studio on Core v2 with recording turned on, and the Core treats it like on air.
A studio reports its state in air_state, a StudioState: ON_AIR, OFF_AIR or RECORDING. The mutation does not return it. The Core applies the command a moment later, so read air_state from studio_routing.
Switch several studios at once
The station level mutation takes a list of studios with their new state. Every studio is resolved before anything is sent, so one unknown name fails the whole call and no studio changes.Activate or deactivate a Core
state is ACTIVE, DEACTIVATED or TOGGLE. A deactivated Core stops handling switcher and camera commands until it is activated again.
Move a studio to another station
A studio feeds one station at a time. Moving it to another station of your broadcaster prepares the studio for that station’s broadcast: its Core, Output Players and clients switch to the data of the new station. The move takes effect at once, also while the studio is on air. Turn on Studio routing for the machine user in VRA Cloud under Settings, Machine users. With it, the machine user can move any studio of the broadcaster to any station of the broadcaster, not only those of its own station. List the studios and the station each one feeds:studio_id accepts the studio id or its internal name, matched across the whole broadcaster. When two studios share a name, use the id. Moving a studio to the station it already feeds changes nothing.
Every move opens a new station session. station_session_id is its id, and Studio.activeStationSession returns the open one. Recordings stay with the station the studio fed when they started.
Follow the switch
The apps of the studio switch without a restart, each in a few seconds. Every app publishes its progress as a retained JSON message on the studio’s MQTT bus:STATION feature with issueMqttStudioToken and subscribe to station/+/state. Only the apps publish there. The message carries app, hostname, station_id, session_id, phase (IDLE, SWITCHING, READY or FAILED), started_at, finished_at, steps and error. An app has finished the move when its phase is READY and its session_id is the new station_session_id.
Response
Every mutation returns the same shape.- ok - the command was sent.
- studio_ids - ids of the studios it was sent to, useful when you addressed them by name.
No studio 'name' in this station, a station you have no access to returns Not authorized for this station. setStudioStation returns Not authorized to route studios. when Studio routing is off for the machine user.
Related
- AutomationLink ingest to push now playing data through the same API.
- Core Control API for control on the studio network, including Bitfocus Companion.