The REST API is a new feature and is subject to change. It will be finalized in a subsequent release.
The Control Panel's REST API allows other programs on the same local area network to control certain aspects of your show. It can be enabled and the network port specified from the Settings > Integration tab.
The REST API uses the HTTP protocol (not HTTPS). No authentication is required to access the API commands.
Queries requesting information use the GET verb and return a response in the JSON format.
Messages that update the player use the PUT verb. Any data that is required to complete the update (e.g. a sequence identifier) is embedded in the URL. The one exception is /v1/player/mainSequences/resetQueue which uses the POST verb.
You can test the API from the computer running the Control Panel by opening a tab in your web browser and going to this URL:
http://127.0.0.1:8001/swagger/index.html
Replace 8001 with the port you selected for the REST API on the Integration tab. Your web browser should display a screen that looks similar to this:
The Swagger web page
Status
GET /v1/player/status
Gets the current player status.
The status response includes mute status and audio volume, which can be controlled using commands listed in the Audio Volume section below.
The status response includes the master dimmer level, which can be controlled using commands listed in the Master Dimmer section below.
The Play Shows section of the Control Panel can be in one of 3 modes (indicated by the playerMode property in the response):
•Disabled (playerMode=disabled) - no playback, not even scheduled shows
•Show Player (playerMode=show) - plays scheduled or on-demand shows created in the Create Shows section.
oThe player may be playing a show (hasActiveShow=true), or waiting for a scheduled show (hasActiveShow=false).
oIf a show is playing, then playingQueue, upcomingQueue, and activeShow will be populated. The playbackState property will reflect whether sequences are playing or paused.
oTo make changes to the upcoming queue, see the commands in the Main Sequences section below.
oOverride sequences can be retrieved or started using commands in the Override Sequences section below.
•Cue List Player (playerMode=live) - create a cue list, and then click Play to start each cue. Can be used as a jukebox.
oThe cueList array will be populated when in this mode. The cue list is also available separately - see the Cue List section below.
Sample JSON response:
{ "playerMode": "show", "syncMode": "none", "hasActiveShow": true, "upcomingShows": [], "playingQueue": { "items": [ { "id": "3a1ae119-fcf9-4819-a612-41e82643286d", "itemId": "c5a28ee7-6676-492e-9b25-d7973b87d8c3", "name": "Amazing Grace (Party Version)-Yule-SHORT", "hasMediaFile": true, "mediaFilename": "Amazing Grace (Party Version)-Yule-SHORT.mp3", "sequenceSource": "showMusical", "startTime": "2024-11-07T12:37:33.6098051-06:00", "duration": "00:00:30.9000000", "playedDuration": "00:00:10.6289825", "remainingDuration": "00:00:20.2710175", "isPauseOnStart": false, "isPauseOnEnd": false, "isTimeDelay": false, "hasError": false, "errorText": null } ], "duration": "00:00:30.9000000" }, "upcomingQueue": { "items": [ { "id": "e15dbf80-7c4b-4d2a-b37e-713a4df0e1cb", "itemId": "21fdf57f-c551-4cd6-b930-210c73dc21f3", "name": "Carol Of The Bells-Pentatonix-SHORT", "hasMediaFile": true, "mediaFilename": "Carol Of The Bells-Pentatonix-SHORT.mp3", "sequenceSource": "showMusical", "startTime": "2024-11-07T12:37:44.4477552-06:00", "duration": "00:00:22.7000000", "playedDuration": "00:00:00", "remainingDuration": "00:00:22.7000000", "isPauseOnStart": false, "isPauseOnEnd": false, "isTimeDelay": false, "hasError": false, "errorText": null }, { "id": "281aba12-ddd5-4f5a-a91e-96bf2ea51e1e", "itemId": "03d2b298-e307-4322-b1dd-1d94bb50d2c2", "name": "Linus And Lucy-Vince Guaraldi-SHORT", "hasMediaFile": true, "mediaFilename": "Linus And Lucy-Vince Guaraldi-SHORT.mp3", "sequenceSource": "showMusical", "startTime": "2024-11-07T12:37:44.4477552-06:00", "duration": "00:00:20.4000000", "playedDuration": "00:00:00", "remainingDuration": "00:00:20.4000000", "isPauseOnStart": false, "isPauseOnEnd": false, "isTimeDelay": false, "hasError": false, "errorText": null }, { "id": "4bb1d03a-c4f1-43c0-aff0-65d88c07166f", "itemId": "55055498-cd0b-4182-b87c-692933835875", "name": "Music Box Dancer (Radio Version)-DJ Schwede-SHORT", "hasMediaFile": true, "mediaFilename": "Music Box Dancer (Radio Version)-DJ Schwede-SHORT.mp3", "sequenceSource": "showMusical", "startTime": "2024-11-07T12:37:44.4477552-06:00", "duration": "00:00:13.4000000", "playedDuration": "00:00:00", "remainingDuration": "00:00:13.4000000", "isPauseOnStart": false, "isPauseOnEnd": false, "isTimeDelay": false, "hasError": false, "errorText": null } ], "duration": "00:00:56.5000000" }, "cueList": [], "selectedCues": [], "lastSelectedCueIndex": -1, "playbackState": "playing", "isPaused": false, "isStopped": false, "isLooping": false, "isPlayingVideoMedia": false, "isMuted": false, "volumeLevel": 39, "dimmingLevel": 97, "pendingStopOption": null, "onDemandShowActive": true, "activeShow": { "name": "2022 Florida", "startTime": null, "endTime": null, "isShuttingDown": false, "hasStarted": true, "isInitialized": true, "initializePercentComplete": 100, "isPaused": false, "isInterrupted": false, "isStopped": false, "isWaitingForStartTrigger": false, "isOnDemandShow": true }, "hasVideoMedia": false } |
Audio Volume
GET /v1/player/isMuted
Gets the mute state, true or false.
Sample JSON response:
{ "isMuted": false } |
PUT /v1/player/isMuted/{enabled}
Sets the mute state. The "enabled" parameter must be true or false.
GET /v1/player/volumeLevel
Gets the audio volume level, 0 to 100.
Sample JSON response:
{ "volumeLevel": 55 } |
PUT /v1/player/volumeLevel/{volumeValue}
Sets the audio volume level. The "volumeValue" parameter must be an integer value in the range 0 to 100.
Master Dimmer
GET /v1/player/dimmingLevel
Gets the master dimmer level, 0 to 100.
Sample JSON response:
{ "dimmingLevel": 100 } |
PUT /v1/player/dimmingLevel/{dimmerValue}
Sets the master dimmer level. The "dimmerValue" parameter must be an integer value in the range 0 to 100.
Playback Control
PUT /v1/player/stop/{stopOption}
Stops playback. The "stopOption" parameter must be either "immediately" or "aftersong".
•In the Show Player, this will initiate show shutdown.
•In the Cue List Player, this will stop playing the current cue.
PUT /v1/player/pause/{pauseOption}
Pauses playback. The "pauseOption" parameter must be either "immediately" or "aftersong".
PUT /v1/player/resume
Resumes playback after a pause.
PUT /v1/player/skipForward
Stops playing the current sequence and moves on to the next one.
•In the Show Player, the next item in the upcoming queue will be played.
•In the Cue List Player, the next cue in the list will be played. If at the end of the cue list, play will be stopped.
Main Sequences
The commands in this section only work when the Show Player is active.
GET /v1/player/mainSequences
Gets a list of all of the sequences in the Main Section of the show that is currently playing. Note that the itemId property is not permanent -- it changes every time the show is started.
Sample JSON response:
[ { "itemId": "1556ce6a-5f80-469d-8d4d-e051cba7f80c", "name": "A Mad Russians Christmas-TransSiberian Orchestra-SHORT", "source": "showMusical", "hasError": false, "duration": "00:00:25.3100000", "hasMediaFile": true, "mediaFilename": "A Mad Russians Christmas-TransSiberian Orchestra-SHORT.mp3" }, { "itemId": "1b192cbd-180c-4f6b-b7e5-00fb40df69a7", "name": "Amazing Grace (Party Version)-Yule-SHORT", "source": "showMusical", "hasError": false, "duration": "00:00:30.9000000", "hasMediaFile": true, "mediaFilename": "Amazing Grace (Party Version)-Yule-SHORT.mp3" }, { "itemId": "c84d0997-8d96-450f-97c3-cda79e403340", "name": "Carol Of The Bells-Pentatonix-SHORT", "source": "showMusical", "hasError": false, "duration": "00:00:22.7000000", "hasMediaFile": true, "mediaFilename": "Carol Of The Bells-Pentatonix-SHORT.mp3" }, { "itemId": "d27d15e5-b975-4984-a3f1-bb4ca230b1cd", "name": "Linus And Lucy-Vince Guaraldi-SHORT", "source": "showMusical", "hasError": false, "duration": "00:00:20.4000000", "hasMediaFile": true, "mediaFilename": "Linus And Lucy-Vince Guaraldi-SHORT.mp3" }, { "itemId": "f29eaa1b-20e1-4afc-b16b-1ab510e33b88", "name": "Music Box Dancer (Radio Version)-DJ Schwede-SHORT", "source": "showMusical", "hasError": false, "duration": "00:00:13.4000000", "hasMediaFile": true, "mediaFilename": "Music Box Dancer (Radio Version)-DJ Schwede-SHORT.mp3" } ] |
PUT /v1/player/mainSequences/repeatCurrent
If there is a sequence from the main section of the show that is currently being played, this command ensures that the same sequence is also at the top of the upcoming queue. If the sequence being played is already at the top of the queue, no action is taken.
PUT /v1/player/mainSequences/playNext/{id}
This command ensures that the sequence with the specified id is at the top of the upcoming queue. If the sequence is already in the queue, it is moved to the top; otherwise a new entry is inserted at the top of the queue. The identifier used in this request must be an "itemId" property of one of the sequences listed in the GET mainSequences response.
POST /v1/player/mainSequences/resetQueue
Replaces the sequences in the upcoming queue (as shown in the GET status response) with the sequences supplied in this request. Identifiers used in this request are the "itemId" properties of sequences listed in the GET mainSequences response.
Sample JSON request:
{ "ids": [ "8e266d54-66f2-4830-8713-a79245b6484e", "e6756ba0-3b22-4447-8f7c-0e0f3c0e2cf1" ] } |
Override Sequences
The commands in this section only work when the Show Player is active.
GET /v1/player/overrides
Gets a list of all Override sequences defined in the Show Player.
Sample JSON response:
[ { "id": "c5589d1c-fc8d-4a6f-ba8d-e675454755df", "name": "No Parking", "type": "playImmediately", "sequences": [ { "id": "081615fb-5e0b-4d7f-b1bc-861bea20fb68", "name": "No Parking", "lightsOffAtEnd": true, "runTimes": 1, "repeatTimes": 1, "markIn": null, "markOut": null } ] } ] |
PUT /v1/player/overrides/play/{id}
Plays the override sequence with the specified id. The identifier is the outer id property from GET overrides, not the one inside the sequences list.
Triggers
PUT /v1/player/trigger/{n}-{u}-{c}
Invokes the same action as the physical trigger. It can be a start trigger or a trigger for an interactive group.
•n is an integer between 0 and 15. 0 is the regular network, 1 is Aux A, etc. n can also be a string "Regular", "AuxA", "AuxB", etc. Case is ignored.
•u is a hex value between 01 and F0 and represents the unit id.
•c is an integer between 1 and 512 and represents the circuit.
Cue List
The commands in this section only work when the Cue List Player is active.
GET /v1/player/cueList
Gets the list of cues currently displayed in the Cue List Player.
Sample JSON response:
[ { "id": "df0d9368-00f6-4e08-b125-65c4c7a04b38", "name": "A Mad Russians Christmas-TransSiberian Orchestra-SHORT", "isActive": true, "notes": "Christmas Eve and Other Stories is the debut studio album by the American rock band Trans-Siberian Orchestra. It was released on October 15, 1996, through Lava Records and Atlantic Records. It is the first album in the band's \"Christmas trilogy\", with The Christmas Attic (1998) and The Lost Christmas Eve (2004) coming afterward. All three albums, as well as their The Ghosts of Christmas Eve DVD, were featured in the box set of The Christmas Trilogy. The album's cover art was created by Edgar Jerins.", "lightsOffAtEnd": true, "repeatTimes": 0, "markIn": null, "markOut": null, "timeCode": null, "autoFollow": false }, { "id": "0de6839c-721f-4c6c-923e-d3739325127b", "name": "Amazing Grace (Party Version)-Yule-SHORT", "isActive": false, "notes": "\"Amazing Grace\" is a Christian hymn published in 1779, with words written in 1772 by the English poet and Anglican clergyman John Newton. ", "lightsOffAtEnd": true, "repeatTimes": 0, "markIn": null, "markOut": null, "timeCode": null, "autoFollow": false }, { "id": "85c99fd2-1ce2-4185-8151-160c9a88ca9a", "name": "Carol Of The Bells-Pentatonix-SHORT", "isActive": true, "notes": "PTXmas is the second extended play album by the a cappella group Pentatonix. The album was digitally released on November 12, 2012, and physical versions were available from November 13, 2012. The deluxe edition was released on November 19, 2013 with 2 additional tracks.", "lightsOffAtEnd": true, "repeatTimes": 0, "markIn": null, "markOut": null, "timeCode": null, "autoFollow": true }, { "id": "8b35f351-7256-4b70-ab7f-b80070511ce0", "name": "Linus And Lucy-Vince Guaraldi-SHORT", "isActive": true, "notes": "", "lightsOffAtEnd": true, "repeatTimes": 0, "markIn": null, "markOut": null, "timeCode": null, "autoFollow": false }, { "id": "fdb8ad13-730c-4cba-a0dd-f19804c443c1", "name": "Music Box Dancer (Radio Version)-DJ Schwede-SHORT", "isActive": true, "notes": "", "lightsOffAtEnd": true, "repeatTimes": 1, "markIn": null, "markOut": null, "timeCode": null, "autoFollow": false } ] |
PUT /v1/player/cueList/play/{id}
Plays the cue with the specified id. The identifier is the id property from GET cueList above. Only cues where the isActive flag is true can be played.