OnTheAir CG REST API

REST API Quick start guide

Below is the list of REST commands that you can send to OnTheAir CG Server or OnTheAir CG Designer. Here is an example of request that you can use in a simple browser. Type the following in the url field of any browser (including mobile devices) :

http://localhost:2001/projects

This will return a dictionary with the list of projects opened in a OnTheAir CG Server application, which should look like this:

{
[
{
"status" : "Playing",
"elapsed" : "00:00:08",
"uniqueID" : "58A56C06-EBD8-450C-B5D3-662F25D1EAFE",
"duration" : "--:--:--",
"remaining" : "--:--:--",
"path" : "\/Applications\/OnTheAir CG 3\/Samples\/Projects\/AppleScript.cg3",
"displayMode" : "1080i 59.94"
},
{
"status" : "Stopped",
"elapsed" : "00:00:00",
"uniqueID" : "7B63AFB8-58F0-4B3F-AE3E-EC8B16FC8ADE",
"duration" : "00:00:10",
"remaining" : "00:00:10",
"path" : "\/Applications\/OnTheAir CG 3\/Samples\/Projects\/LowerThird.cg3",
"displayMode" : "1080i 50"
},
{
"status" : "Paused",
"elapsed" : "00:00:01",
"uniqueID" : "3C1B552C-F9DC-4691-8DE6-D57BF41775E8",
"duration" : "--:--:--",
"remaining" : "--:--:--",
"path" : "\/Applications\/OnTheAir CG 3\/Samples\/Projects\/AnalogClock2.cg3",
"displayMode" : "1080i 50"
},
]
}

About authentication

The general idea is that to see the status of a OnTheAir CG Server, get the list of projects, etc... you don't need to be authenticated. If you need to change something (start/stop playback, modify a project), then you need to use a either a token or a password in your requests.

Token or password?

With OnTheAir CG, there are 2 authentication methods:
  • Password
  • Token

The Password is set in the application itslef, and they do not expire until the user changes it in the preference of OnTheAir CG.

Tokens are unique and only one token is valid at a time. So if another client request a token, your token will be revoked, and you will need to request a new token. The idea is that only one client at a time can do modifications in order to avoid conflicts. A token is valid for as long as it is not revoked by a new token request.

How to get a token ?

To get a token, you need to know the password of a OnTheAir CG Server (the default password is "1234"). A token is returned when you use the "unlock" request using the password of the OnTheAir CG Server you are connected to. Here is an example of request you can do to retrieve a token when used on the same computer with OnTheAir CG Server running (you may have to change the IP address and port number) :

http://localhost:2001/unlock?password=1234

Sending a request that requires a token

Once you have a valid token, you can send requests that require that token. Below is an example of request using a token to start playing project at index 1 (the index is 0 based, so this will start the second project starting from the top. It also means that at least 2 projects must be loaded in OnTheAir CG Server, otherwise it won't have anything to play:

http://localhost:2001/projects/1/play?token=33AC085E-A5DF-4A2A-87C5-E45AF58A8FB5

If the token is incorrect, it should return this:

{
"success" : false,
"error" : "not authenticated"
}

With a valid token it should return the following, confirming that it could start playing.

{
"success" : true
}

Sending a request that requires a password

Requests done with a password are just slightly different, but otherwise the logic is the same

http://localhost:2001/projects/1/play?password=1234

You could also start a project by indicating its Unique ID (that you can retrieve as explained above). So this will be independent of its position in the list of projects which can vary :

http://localhost:2001/projects/3C1B552C-F9DC-4691-8DE6-D57BF41775E8/play?token=33AC085E-A5DF-4A2A-87C5-E45AF58A8FB5

If the token is correct, it should return the following and start the specified project.

{
"success" : true
}

Playback & Subtitles

Enable live subtitling

You must enable this feature first before sending subtitles records.

PUT /playback
{
"live_subtitling" : true
}
Warning: while this property is enabled passthrough CC vancs will be overrided.

You can retrieve its status by sending:

GET /playback

Disable live subtitling

Disable the subtitling will erase the previous live subtitle and let CC pass through the CG if present.

PUT /playback
{
"live_subtitling" : false
}

Send Live Subtitle

PUT /playback/subtitles
{
"text_lines" : [
{
"text": "This is the first line",
"color": "#ffffff"
},
{
"text": "This is the second line",
"color": "#ff00ff"
}
]
}

Sending a subtitle will erase the previous one.

Sending an empty object "{}" will clear the subtitle.

Erase Live Subtitle

DELETE /playback/subtitles

Same effect as sending a PUT command with an empty body.

Projects

Unique id or index ?

Each project can be addressed using either its unique_id, or its index. The unique_id is the safest way to talk to a project as it will not change and remain unique. The index is the position of that project in the list of projects that are loaded in OnTheAir CG Server. It can change depending on the other projects that are loaded and ordered.

Basic GET request for projects

To return the list of projects that are opened on that OnTheAir CG Server. :

GET /projects

To return the description of a specific project :

GET /projects/{unique_id or index}

Controlling projects

Note that when a project is opened in OnTheAir CG Server, still images and animated sequences are immediately buffered to the memory of Graphics card so projects are ready to play. You should then be careful when opening project that you still have enough memory on the Graphics card to open it. And you may need to close other projects. Videos are not buffered to the graphics card.

To open a project :

GET /projects/open?token={token}&path={projectlocalURL}

To close a project :

GET /projects/{unique_id or index}/close?token={token}

To start playing a project :

GET /projects/{unique_id or index}/play?token={token}

To pause a project :

GET /projects/{unique_id or index}/pause?token={token}

To stop a project :

GET /projects/{unique_id or index}/stop?token={token}

Note that you could also use the password authentication method instead of token (see above).

Items

Projects hold items. Items can be either a text, a shape, a ticker,...

Unique id or index ?

Each item can be addressed using either its unique_id, or its index. The unique_id is the safest way to talk to an item as it will not change and remain unique. The index is the position of that item in the OnTheAir CG project item's list (it's a zero-based order). It can change depending on the other projects that are loaded and ordered.

Basic GET request for items

To return the list of items of a project. Note that by default OnTheAir CG Server is set to only return the list of "published" items. If you want to see the complete list of items and modify them, you need to enable the option in OnTheAir CG Server to publish all items.

GET /projects/{index or uniqueID}/items

To return the description of a specific item:

GET /projects/{index or uniqueID}/items/{index or uniqueID}

Modifying items

To modify items you need to use the PUT method, and to use tokens, for example, the following request would modify the Text field of the item specified to "This is my Title", and set it as a visible item:

PUT projects/{index or uniqueID}/items/{index or uniqueID}?token={token}
{
"text" : "This is my Title",
"hidden": true
}

Note that
- properties that are not sent remain unchanged.
- if at least one property is invalid, the whole modification will be ignored.

You can also modify multiple items at a time:

PUT /projects/{index or uniqueID}/items?token={token}
[
{
"uniqueID" : "C5A781D1-E2D6-4B3C-8F98-9F443E07C615",
"text" : "This is my Title",
"hidden" : true
},
{
"uniqueID" : "E5A0880C-8073-4782-AB20-BF75CF420126",
"text" : "This is my SubTitle"
},
{
"uniqueID" : "DC68D0E0-C367-4C68-8A2C-76A5F113A940",
"width" : 150,
"hidden" : false
}, ]

Modifying rich text items

If you want to modify rich text items with the REST API, you should use html as in the following example:

PUT /projects/{project index or uniqueID}/items/{item index or uniqueID}?token={token}
{
"htmlText": "<span style='font-family:Courier; color:red; font-size: 20;'> 20px red text. </span> <span style='font-family:Courier; color:blue; font-size: 50;'> 50px blue text.</span>",
}

Change Movies, Images, or Sound Items using the complete path

You can also change the files that you are linking to on projects. So you could replace a movie, picture or sound item by another one, simply by replacing its URL

To replace a movie :

PUT /projects/{project index or uniqueID}/items/{item index or uniqueID}?token={token}

{
"moviePath": "/Media/Movies/MyMovie.mov",
}

To replace a still image :

PUT /projects/{project index or uniqueID}/items/{item index or uniqueID}?token={token}

{
"imagePath": "/Media/Images/MyImage.jpeg",
}

To replace a sound :

PUT /projects/{project index or uniqueID}/items/{item index or uniqueID}?token={token}

{
"filePath": "/Media/Sound/MySound.AIFF",
}

Change Movies, Images, or Sound Items using the relative path

Instead of using the full path to an item, you could use just the "relative path". This means that the file used will be found relatively to the location of the project itself. This allows you then to move the project and media to another location, and this will continue to work.

To replace a movie using the relative path for a file that will be located in the same folder as the project:

PUT /projects/{project index or uniqueID}/items/{item index or uniqueID}?token={token}

{
"relativePath": "../MyMovie.mov",
}

About Websockets

You have 2 options with our APIs to know some info such as if the project is playing or not:

The advantage of the WebSockets is that every update is pushed live to it so you would be notified immediately and you won't miss any update.

Contact us if you need more information about the WebSockets.

For more information

If you need more info or support about OnTheAir CG, you can find it on our support desk.