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

1. On the Instances tab, add a "Generic HTTP Request" and name it "GlobalCue"
2. 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!
3. Select a button you'd like to configure to send a Forward cue, and set the "Key Down" action to "GlobalCue: POST"
4. In the button action options, edit the "URI" option to read "forward/{Presenter-ID}, replacing {Presenter-ID} with the presenter ID number (See above)"}
5. 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

1. On the Instances tab, add a "Generic HTTP Request" and name it "GlobalCue"
2. 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.
3. Select a button you'd like to configure to send a Forward cue, and set the "Key Down" action to "GlobalCue: POST"
4. In the button action options, edit the "URI" option to read "forward"
5. 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.