OnTheAir Video's REST API allows you to retrieve OTAV's status, change playlists, do controls of the playback and playing with the DGO. Also note that this REST API is not final, it's a first draft and there could be changes in the future when it is finalised.
This API is meant to be RESTful, then, using different verbs on requests leads to different behaviour on request processing. In general manner, consider theses verbs to have the described behaviour:
GET -> Retrieve data of a processable entity.
POST -> Create a new entity.
PUT -> Update a specified entity.
DELETE -> Delete an entity.
When you modify or retrieving data, be sure to handle properly the return code that is returned by the API as it indicates if the operation was successfull or not.
For POST & PUT requests you MUST supply the 'Content-Type' header with value 'application/json'.
Here is a short list common codes returned by the API:
"success": Indicates if the request was accepted and processed or not by OnTheAir Video. "error": In case of success false, indicates what was wrong when processing the request.
NOTE: OPTIONAL marked parameters indicates that these parameters can be or not be present in the response object, this is due to internal logics.
However for requests that require a body, like PUT or POST, it means that it can be passed but they are not mandatory.
Authorization
Since playlists can play sensitive content at a time, an authorization mechanism will be required if you decide to enable it in OnTheAir Video's preferences. (General -> HTTP Server -> Require Authentication).
If this feature is enabled, it implies that you have to login with one of the registred user defined in OnTheAir Video and use the token received. In case not, you can ignore this section.
Each user has an access level, it defines how much control you have. Theses are described as follows:
#
Title
Description
1
Read Only
You'll only be able to retrieve informations but not modifying it.
2
Modify Playlists
You'll only be able to modify playlists.
3
Modify And Control Playlists
You'll be able to modify playlist, control the playback and DGO.
4
Full Access
You'll be granted to execute all commands (admin privileges).
In order to make request you must first login with the following request:
{
"token": string, OPTIONAL
"error": string, OPTIONAL
"level": number
}
The token received MUST be added in the query parameter of each request you make to OTAV.
The level property is indicating the level granted to the logged user as defined in the table above.
NOTE:
The token will be invalid if you relaunch OnTheAir Video and thus you will have to remake the process again to obtain a new valid token.
In case of token invalidity, requests will send back a 401 error code
In case of not token provided, requests will send back a 403 error code
Unique id - index or display name ?
Each playlist can be addressed using either its unique_id or its index.
The unique_id of a playlist represents its display name but may be altered to ensure it is unique among other playlists opened. It will not change unless you reanme the playlist.
The index is the position of the playlist in opening order. The index '0' would represent the first playlist opened, then '1' would represent the second and so on.
Each clip can be addressed using either its unique_id, its index or eventually its display name.
The unique_id is the safest way as it will not change and remain unique, but you have to request first its value before being able to send arguments.
The index of a clip is the (zero based) position of a clip, or the order in which the playlists are displayed on screen (0 is the first playlist open, 1 is the second playlist open, etc...)
The display name is the name given to a clip inside OnTheAir Video. But pay attention that if you have mutiple clips with the same name, it will always address to the first one (in index order). Should be used as a convenience way or when you are sure the name is unique witthin the playlist.
Each action can only be addressed by its unique_id.
Controlling the playback or getting the status
Types of controls
You have three ways to control the playback. Depending on what you want to achieve:
Control the playback without specifying a playlist, or a clip. In this case, the front playlist (or the playing one) will be the one answering your requests.
Control the playback by specifying the playing you want to control, but without specifying a clip. In this case you can start the playback on a specific playlist, and the first clip (or the playing one) in the playlist will be controlled
Control the playback by specifying both the playing you want to control, as well as the clip. That's the way to start playing a specific clip in a specific playlist.
Controlling the playback without specifying a playlist or a clip:
Controlling the playback by specifying a playlist, but not the clip
You have two ways to control the playback. Either can control the playback of the playlist, without specifying a clip. In that case it behave exactly as if you were pushing the playback buttons in the playlist. Depending on which clip plays or is selected it will behave differently. If you need to stop or pause the playback, it's easier to just tell the playlist to stop or pause. But to play, you may not know which clip will start playing.
NOTE: When using playback commands (play or pause) by specifying a clip, the following parameters can be passed in the URL to set the playback's play head at a precise timecode:
"position_relative_timecode": string HH:MM:SS:FF timecode position from the clip's start
"position_media_timecode": string HH:MM:SS:FF absolute timecode in the media
"position_relative_seconds": number position after x seconds from the media's beginning
NOTE:
The "preset_duration" parameter is a theoretical value that indicates the desired duration of the playlist althougth the duration may or may not be equal to this one.
Get the playback status of a playlist
The following request will get the playback status of playlist {n}. You can use the playlist index, or a unique ID (see above).
The following request will get the info of the item {m} in playlist {n}. You can use the playlist index, or a unique ID (see above), same thing for the clip, you can use either the index or the unique ID.
>,
"segment_number" : number,
"reconcile_id" : string, OPTIONAL
"isci_code" : number, OPTIONAL"url" : string, eg. "/Users/admin/Documents/MyMovie1.mov" for FILE or STREAM"video_codec" : string, eg. "H.264""audio_codec" : string, eg. "AAC""last_modification_date" : string,
"has_in_point" : boolean,
"in_point" : number, eg. 9.902 (in seconds)"has_out_point" : boolean,
"out_point" : number, eg. 59.000 (in seconds)"closed_captions" : array <string>, OPTIONAL"languages" : array <string> OPTIONAL"live_source_name": string OPTIONALeg. "Live Source 2""is_streamed": boolean, Indicates if the stream is a remote file or not.
"playback_mode" : string,
playback mode
"resize_mode": string,
resize mode
"duration" : number, eg. 679.902 (in seconds)
"duration_timecode" : string, eg. "00:11:34" HH:MM:SS
"frames_per_second" : number,
"drop_frame" : boolean,
"is_offline": boolean, will always set to false for a LIVE or STREAM clip.
"is_valid" : boolean,
"is_cued_as_next": boolean,
"validation_status" : string,
* : if the unique_id property is not present it means that the item is still in the playlist but will be further deleted and thus cannot be accessed.
NB: If 'clip_type' is a comment item, he will only have 'unique_id', 'name', 'clip_type' & 'segment_number' properties.
Get an Apple script action of a playlist item
The following request will retrieve the action {k} set on the item {m} of playlist {n}. You can use indexes, or unique IDs (see above).
GET http://localhost:8081/playlists/{n}/items/{m}/actions/{k}
Action response object:
{
"name" : string, eg. "Display Finder Message" -> name of the AppleScript
"unique_id" : string, eg. 0650A319-B0B7-4B06-957C-F81B38470548
"position" : number, eg. 0
"position_type" : string,
The following request will open the playlist with specified path {path}. Once a scheduled playlist is open you can control it the way you do with opened playlists.
GET http://localhost:8081/scheduler/playlists?path={path}
The following request will close the playlist with specified ID. Warning ! Use this command with care as some other remote user may no longer have access to the playlist after its close.
GET http://localhost:8081/playlists/{id}/close
Get schedule's infos
GET http://localhost:8081/scheduler?include_items=1
You can retrieve several infos about the current scheduler. The query parameter "include_items" will allow you to get all the events of the scheduler. If you don't need them, don't pass it.
All properties of a clip can be changed but here are the most common to be changed. WARNING: if you change some properties that doesn't appear on this list, it might lead to unwanted UI behaviour.
PUT http://localhost:8081/playlists/{n}/items/{m}
Body:
{
"name" : string, OPTIONALeg. "MyMovie1""url" : string, OPTIONALeg. "/Volumes/Movies/MyMovie.mov" (ONLY FOR FILE or STREAM)"live_source_name" : string, OPTIONALeg. "Live Source 2" (ONLY FOR LIVE)"duration" : number, OPTIONALeg. 679.902 (in seconds) (ONLY FOR LIVE or STREAM)
"playback_mode" : string,
If you want to create a clip at a specific index {m}, you can use the following:
POST http://localhost:8081/playlists/{n}/items/{m}
Body:
{
"clip_type" : enum <
clip_type
>, REQUIRED"url" : string, REQUIRED ONLY FOR FILE or STREAMeg. "/Volumes/Movies/MyMovie.mov""live_source_name" : string, REQUIRED ONLY FOR LIVEeg. "Live Source 2""duration" : number, REQUIRED ONLY FOR STREAM OR LIVEeg. 679.902 (in seconds)
"name" : string, OPTIONALeg. "MyMovie1"
"playback_mode" : string,
If you need more info or support about OnTheAir Video, you can find it on our support desk. And if you need additional information on the API and/or the websockets, submit a ticket and we'll be happy to guide you.