GlobalCue API
Introduction
GlobalCue has a simple HTTP-based API, which allows presenter cues to be inserted by third-party software (for example, BitFocus Companion).
Presenter IDs
Every presenter has unique, random ID, which looks something like 321-567-0789. You can find this ID at the end of the "presenter link", on the session setup page.
For example, if the presenter link is https://globalcue.live/pres/123-456-7890 then the presenter ID is the 123-456-7890 part at the end.
Cues
To inject a cue, make an HTTP POST request to a URL like this: https://globalcue.live/api/presenter/{Presenter-ID}/{Cue-Name}. The request does not need a body - but any body that do include you will be ignored.
{Cue-Name} should be replaced with "forward", "back" or "black", and {Presenter-ID} should be replaced with the presenter ID
For example:
- POST to https://globalcue.live/api/presenter/forward/123-456-7890 to inject a "forward" cue
- POST to https://globalcue.live/api/presenter/back/123-456-7890 to inject a "back" cue
- POST to https://globalcue.live/api/presenter/black/123-456-7890 to inject a "black" cue
Presenter Control
In much the same way that you can inject cues, you can perform Pause, Play and Solo actions on a presenter.
Simply replace the cue name in the URL with "pause", "play" or "solo".
For example:
- POST to https://globalcue.live/api/presenter/pause/123-456-7890 to pause a presenter
- POST to https://globalcue.live/api/presenter/play/123-456-7890 to play ("unpause") a presenter
- POST to https://globalcue.live/api/presenter/solo/123-456-7890 to solo a presenter
Alternative URL Arrangment
As well as the examples above, GlobalCue accepts API URLs with the action and the presenter ID reversed, for example:
- POST to https://globalcue.live/api/presenter/123-456-7890/forward to inject a "forward" cue
- POST to https://globalcue.live/api/presenter/123-456-7890/pause to pause a presenter
Depending on how you're using a system like Companion, this might make it simpler to set up.
Companion
We're hoping to get easier-to-use support for GlobalCue added to BitFocus Companion, but for the moment it works well using the Companion's built-in generic HTTP support.
You can configure Companion (2.1.x) like this
- On the Instances tab, add a "Generic HTTP Request" and name it "GlobalCue"
- Set the "Base URL" parameter of the new Instance to "https://globalcue.live/api/presenter/". Don't forget the slash at the end, that's important!
- Select a button you'd like to configure to send a Forward cue, and set the "Key Down" action to "GlobalCue: POST"
- In the button action options, edit the "URI" option to read "forward/{Presenter-ID}, replacing {Presenter-ID} with the presenter ID number (See above)"}
- Repeat the previous two steps for the back button, setting its URI option to "back/{Presenter-ID}
The method above is good if you want to have multiple presenters each with a small number of buttons. If you want to add lots of buttons for a small number of presenters, you might find it easier to put the presenter ID into the "Base URL", like this
- On the Instances tab, add a "Generic HTTP Request" and name it "GlobalCue"
- Set the "Base URL" parameter of the new Instance to "https://globalcue.live/api/presenter/{Presenter-ID}/". Don't forget the slash at the end.
- Select a button you'd like to configure to send a Forward cue, and set the "Key Down" action to "GlobalCue: POST"
- In the button action options, edit the "URI" option to read "forward"
- Repeat the previous two steps for the the other buttons, setting their URI option to "back", "black", "play", "pause", etc
With this arrangement you will need to make a separate Companion Instance for each presenter.