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.

Simple Feedback

You can check the play/pause/solo status of a presenter by making a GET request to the play/pause/solo URLs. (See above)

GlobalCue will return a single character, either a "1" or a "0" to indicate if that status is active

For example:

• GET https://globalcue.live/api/presenter/pause/123-456-7890 to check if a presenter is paused
• GET https://globalcue.live/api/presenter/play/123-456-7890 to check if a presenter is in play (always returns the opposite of the "pause" URL
• GET https://globalcue.live/api/presenter/solo/123-456-7890 to check if a presenter is the only presenter in play

Advanced Feedback

A more sophisticated method of requesting presenter status is to make a GET request to https://globalcue.live/api/presenter/{Presenter-ID}/status

GlobalCue will return a JSON object containing the status of the presenter, like this:

{
    "seq": 13,
    "id" : "{Presenter-ID}",
    "name": "Presenter's Name",
    "activeHandsetCount" : 1,
    "pause": false,
    "play": true,
    "solo": false
}

To avoid the need to poll this endpoint repeatedly, the client may pass a sequence id as a URL parameter, so the URL looks like https://globalcue.live/api/presenter/{Presenter-ID}/status?seq={SequenceNumber}.

The sequence number should be set to the value obtained from the 'seq' field of the previous status request for the same presenter (just pass 0 if you don't yet know the sequence to use).

When this type of request is used, GlobalCue will delay responding to the request until the presenter changes state, at which point the request will be rapidly completed and a response will be sent - the response will contain the sequence number to use on the next request.

Clients should be aware that this sort of 'long polling' request may fail or timeout at any point on the network between the client and the GlobalCue servers, so should be ready to submit a new request whether the current one completes successfully or not.

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.

Session Information

If you know a session ID, you can find the status of all the presenters with one call, like this: https://globalcue.live/api/session/{Session-ID}/Presenters

This API will return an object which contains a collection of presenter status objects (see Advanced Feedback above). As with the presenter status feedback, you can use a long-polling method by adding a ?seq=xxx parameter to your call.