The REST API we have built is used internally as well for the remote control between MovieRecorder as for the web page control. We have settled for JSON over XML for its simplicity and its easy support in the browser.
The documentation is organised per object (Sources, Destinations, …) that can be accessed through the API.
The fields of each object are described with their type and a comment followed by the list of all the methods that the object has. Each method has an HTTP verb (GET, POST, …) and an unique URL.
REST API Quick start guide
Here is an example of request that you can use in a simple browser :
http://localhost:8080/sources
This will return a dictionary with the list of sources available for a MovieRecorder, which should look like this:
{
{
"is_recording" : true,
"is_paused" : false,
"is_enabled" : true,
"display_name" : "Io4K - 0 - 1",
"description" : "Io4K - 0 - 1 (1080i 59.94)",
"unique_id" : "4XT00292 - 0",
"device_name" : "Io4K - 0 - 1"
},
{
"is_recording" : false,
"is_paused" : false,
"is_enabled" : false,
"display_name" : "Io4K - 0 - 2",
"description" : "Io4K - 0 - 2 (1080i 59.94)",
"unique_id" : "4XT00292 - 1",
"device_name" : "Io4K - 0 - 2"
},
{
"is_recording" : false,
"is_paused" : false,
"is_enabled" : false,
"display_name" : "Io4K - 0 - 3",
"description" : "Io4K - 0 - 3 (1080i 59.94)",
"unique_id" : "4XT00292 - 2",
"device_name" : "Io4K - 0 - 3"
},
{
"is_recording" : false,
"is_paused" : false,
"is_enabled" : false,
"display_name" : "Io4K - 0 - 4",
"description" : "Io4K - 0 - 4 (1080i 59.94)",
"unique_id" : "4XT00292 - 3",
"device_name" : "Io4K - 0 - 4"
}
}
About the authentication
If you have enabled the password requirement on MovieRecorder, you will have to send the password with each of your requests. so for example if you want to know the list of sources available, you will have to use something like this (1234 is the default password) .
http://localhost:/sources?password=1234
If you pass the wrong password it will return:
Authentication Failed
Note that in this document, instead of writing the url that you can type in a browser (http://localhost:8080/sources), we will indicate the REST command and it will look something like this :
GET /sources
Unique id or index ?
Each source, destination or schedule can be addressed using either its unique_id, or its index :
- The unique_id is the safest way to talk to a source as it will not change and remain unique, but you have to request first its value before being able to send arguments.
- The index is the (zero based) position of that source, destination or schedule in the list of sources, destinations or schedules presented in the MovieRecorder interface. It is easy to work with as you can just send arguments to the first source, destination or schedule. But its value can change depending on the other elements in the list.
The API allows you to manipulate the sources (inputs). You can access their information, modify the recording settings (recording name, destinations), start/pause/stop recording. The following keys are the JSON object representation of a source :
Name |
Type |
Content |
device_name |
string |
The name of the source |
unique_id |
string |
A string that uniquely identifies the source |
display_name |
string |
The name chosen by the user for the source |
video_format |
string |
The name of the source format |
frame_rate |
float |
The frame rate of the source |
recording_name |
string |
The name of the recording |
reel_name |
string |
The reel name of the source. Will be written in the TC track of the QuickTime movie |
is_enabled |
boolean |
True if the source has been enabled, false otherwise |
is_locked |
boolean |
True if the source has been locked, false otherwise. A source must be unlocked to be able to start/stop the recordings |
is_recording |
boolean |
True if the source is recording (or paused), false otherwise |
is_paused |
boolean |
True if the source is paused, false otherwise |
can_be_paused |
boolean |
True if the source can be paused, false otherwise. Classic destinations can not be paused |
recording_start_date |
date |
The start date of the current recording or empty |
recording_end_date |
date |
The date at which the current recording will end. Only specified if a scheduled or timed recording is taking place |
enabled_destinations |
dictionary |
returns a an array of dictionaries specifying which destinations are enabled for the source. Each destination will show the following keys:
- "destination_name": The name of the destination
- "destination_unique_id": A string that uniquely identifies the destination
- "destination_recording_path": The path to the currently recording file (or the last recorded file if recording is stopped). This is useful when using tokens and/or counters in file names.
|
Accessing the information
GET /sources
Returns a list of sources as well as their information.
Example response:
[
{
"recording_name": "RecordingName",
"recording_start_date": "2017-05-08T12:14:09.837Z",
"is_paused": false,
"is_locked": false,
"can_be_paused": true,
"enabled_destinations": [
{
"destination_name": "QuickTime Destination",
"destination_unique_id": "D3501279-1B50-4532-84A0-0AB8AD78B02E",
"destination_recording_path": "/Volumes/Video/MyFirstSource_RecordingName.mov"
}
],
"unique_id": "AJA_01",
"display_name": "MyFirstSource",
"device_name": "AJA_01",
"reel_name": "001",
"frame_rate": 29.97,
"video_format": "1080i 59.94",
"is_recording": false,
"recording_end_date": "2017-05-08T13:35:05.539Z",
"is_enabled": true
},
{
"recording_name": "RecordingName",
"recording_start_date": "2017-05-08T12:14:09.837Z",
"is_paused": false,
"is_locked": false,
"can_be_paused": true,
"enabled_destinations": [
{
"destination_name": "QuickTime Destination",
"destination_unique_id": "D3501279-1B50-4532-84A0-0AB8AD78B02E",
"destination_recording_path": "/Volumes/Video/MySecondSource_RecordingName.mov"
}
],
"unique_id": "Blackmagic-Design_01",
"display_name": "MySecondSource",
"device_name": "Blackmagic-Design_01",
"reel_name": "001",
"frame_rate": 29.97,
"video_format": "1080i 59.94",
"is_recording": false,
"recording_end_date": "2017-05-08T13:35:05.539Z",
"is_enabled": true
}
]
GET /sources/{unique_id or index}
Returns the source and its settings identified by the unique id or the index.
Example response:
{
"recording_name": "RecordingName",
"recording_start_date": "2017-05-08T12:14:09.837Z",
"is_paused": false,
"is_locked": false,
"can_be_paused": true,
"enabled_destinations": [
{
"destination_name": "QuickTime Destination",
"destination_unique_id": "D3501279-1B50-4532-84A0-0AB8AD78B02E",
"destination_recording_path": "/Volumes/Video/MyFirstSource_RecordingName.mov"
}
],
"unique_id": "AJA_01",
"display_name": "MyFirstSource",
"device_name": "AJA_01",
"reel_name": "001",
"frame_rate": 29.97,
"video_format": "1080i 59.94",
"is_recording": false,
"recording_end_date": "2017-05-08T13:35:05.539Z",
"is_enabled": true
}
GET /sources/{unique_id or index}/thumbnail
Returns a JPEG thumbnail of the last received image.
GET /sources/{unique_id or index}/info
Returns information about the source feed: last received timecode (string), if it is recording (bool), last warning (string), vuMeterLevels (array of values from 0 to 1.0).
Control the recording
GET /sources/{unique_id or index}/record
Starts the recording of the source identified by the unique id or the index.
Optional parameters (to manage the effective recording duration or end date):
- duration: number of seconds the recording should last
- end_date: date at which the recording should end
GET /sources/{unique_id or index}/pause
Pauses the recording of the source identified by the unique id or the index.
GET /sources/{unique_id or index}/resume
Resumes (after a pause) the recording of the source identified by the unique id or the index..
GET /sources/{unique_id or index}/stop
Stops the recording of the source identified by the unique id or the index.
GET /sources/{unique_id or index}/destinations
Returns a list of unique ids of the enabled destinations for the source identified by the unique id or the index.
PUT /sources/{unique_id or index}/destinations
Pass an array of destination unique ids that the source identified by the unique id or the index should record to.
GET /sources/{unique_id or index}/recording_name
Returns the recording name of the source identified by the unique id or the index.
PUT /sources/{unique_id or index}/recording_name
Pass a string identified by the key recording_name to replace the recording name of the source identified by the unique id or the index.
GET /sources/{unique_id or index}/reel_name
Returns the reel name of the source identified by the unique id or the index.
PUT /sources/{unique_id or index}/reel_name
Pass a string identified by the key reel_name to replace the reel name of the source identified by the unique id or the index.
PUT /sources/{unique_id or index}/recording_settings
Pass a dictionary with the keys recording_name and destinations where recording name is a string and destinations is an array of destination unique ids. This method is there for your convenience and groups destinations and recording_name methods into one.
GET /sources/{unique_id or index}/lock
Disables the ability to start/pause/resume/stop recording on the source identified by the unique id or the index.
GET /sources/{unique_id or index}/unlock
Enables the ability to start/pause/resume/stop recording on the source identified by the unique id or the index.
GET /sources/{unique_id or index}/destinations
Returns a list of unique ids of the enabled destinations for the source identified by the unique id or the index.
Gang recording
Instead of controlling each source individually, you can control them together by simply sending an array of sources that you want to control.
PUT /sources/record
Pass an array of unique ids or indexes of sources to start recording these.
PUT /sources/pause
Pass an array of unique ids or indexes of sources to pause these.
PUT /sources/resume
Pass an array of unique ids or indexes of sources to resume recording (after a pause) these.
PUT /sources/stop
Pass an array of unique ids or indexes of sources to stop recording these.
The API allows you to access the list of destinations and update the path. The following keys are the JSON object representation of a destination :
Name |
Type |
Content |
name |
string |
The name of the destination. |
unique_id |
string |
A string that uniquely identifies the destination. |
preset_display_name |
string |
The name of the destination’s audio/video preset. |
path |
string |
The path the destination will record to. |
GET /destinations
Returns a list of destinations.
PUT /destinations/{unique_id or index}
Pass a new path to update the destination’s path.
The API allows you to manipulate the scheduled recordings. The following keys are the JSON object representation of a scheduled recording :
Name |
Type |
Content |
name |
string |
The name of the scheduled recording. |
unique_id |
string |
A string that uniquely identifies the scheduled recording. This property is read-only and will automatically be generated. |
is_enabled |
boolean |
True if the scheduled recording is enabled, false otherwise. |
source_unique_id |
string |
The unique id of the source that should record. |
destination_unique_ids |
array |
An array of destination unique ids that should be used for the recording. |
duration |
integer |
The duration of the recording in minutes. |
start_time |
integer |
The offset in minutes from midnight. |
weekly_repeated |
boolean |
True if the scheduled recording is to be repeated over time, false otherwise. |
recording_days |
array |
An array of the days of the week (0 being Monday and 6 Sunday) which is present only when weekly_repeated is true. |
date |
string |
The date of the recording which is present only when weekly_repeated is false. |
GET /scheduled_recordings
Returns a list of scheduled recordings.
GET /scheduled_recordings/{unique_id or index}
Returns the scheduled recording identified by the unique id or the index.
POST /scheduled_recordings
Creates a new scheduled recording.
Example body:
{
"name" : "My JSON recording",
"source_unique_id" : "OnTheAir Video",
"destination_unique_ids": ["928BEB6F-5342-4223-8CB9-5C4629B00288"],
"duration" : 30,
"start_time" : 60,
"weekly_repeated" : true,
"recording_days" : [3],
"is_enabled": false
}
This creates a scheduled recording that will record every Wednesday from 1 AM to 1:30 AM.
Example response:
{
"success" : true,
"unique_id" : "BD6C4147-E4AC-4525-B7DE-1392A2382BEE"
}
PUT /scheduled_recordings/{unique_id or index}
Pass values to update the scheduled recording identified by the unique id or the index.
The API allows you to manipulate the metadata sets.
Please note that metadata sets can be used on sources and some keys/values of metadata fields are only relevant when the set is being used on a source. See the documentation of the source object for the usage of sets on sources.
The following keys are the JSON object representation of a metadata set:
The following keys are the JSON object representation of a metadata field:
You have 2 options with our APIs to know the status of a recording:
- Using the REST api: You would be regularly polling the sources to know their status. This enables you to check the signal format but for dropped frames it would be less accurate. Indeed, as you can only get the last warning, you could miss one in between two polls.
- Using the WebSockets: This is much better to work with as the websockets will send you the notifications. There are 2 sockets. One main containing all the changes regarding the sources and destinations, and a second one with all the information for the activity & logs.
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. You can also have a look at the sample webpage that we have created (it uses websockets). On the Mac that is running MovieRecorder, you can take a look at:
http://localhost:8080/index.html
If you need more info or support about MovieRecorder, 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.