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:
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.
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.
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}
GET /projects/{unique_id or index}/close?token={token}
To start playing a project :
GET /projects/{unique_id or index}/play?token={token}
GET /projects/{unique_id or index}/pause?token={token}
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",
}
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:
- You would be regularly polling the projects to know their status (if they are playing, if they have been modified, etc...).
- Using WebSockets: This is much better to work with as the websockets will send you the notifications. There are 3 sockets in OnTheAir CG depending on the type of update you want to receive.
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.