MovieRecorder's REST API allows you to retrieve MovieRecorder's inputs and outputs, control the playback, create clips, etc... If you have additional needs, don't hesitate to reach out to us.
MovieRecorder uses port 8080 by default, but this can be configured in the preferences of MovieRecorder.
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 MovieRecorder. "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 controlling your ingest can be sensitive content at a time, an authorization mechanism will be required if you decide to enable it in MovieRecorder's preferences. (General -> HTTP Remote Control -> Require Password).
If this feature is enabled, it implies that you have to send the password defined in MovieRecorder and send the password with each request.
So for example if your password is "1234", you will have to add it to your request:
GET http://localhost:8080/sources?password=1234
Unique ID, or Index?
Each source, destination or scheduled recording can be addressed using either its unique_id or its index.
The unique_id of an item is unique. It will not change.
The index is the position of the input or output in opening order. The index '0' would represent the first input or output, then '1' would represent the second and so on.
Getting information about the MovieRecorder Instance
Get info about MovieRecorder
You can get some info about the application itself
The following request 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).
The following request returns the recording name of the source.
GET http://localhost:8080/sources/{n}/recording_name
Response:
{
"recording_name": "My Recording Name"
}
To set the recording name of a source:
PUT http://localhost:8080/sources/{n}/recording_name
Body:
{
"recording_name": "My Recording Name"
}
Controlling the "reel" name of a source
The following request returns the reel name of the source.
GET http://localhost:8080/sources/{n}/reel_name
Response:
{
"reel_name": "001"
}
To set the reel name of a source:
PUT http://localhost:8080/sources/{n}/reel_name
Body:
{
"reel_name": "001"
}
Change 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.
PUT http://localhost:8080/sources/{n}/recording_settings
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
Stop
Stops the recording of the source identified by the unique id or the index.
GET http://localhost:8080/sources/{n}/stop
Other Controls
Pauses the recording of the source identified by the unique id or the index.
GET http://localhost:8080/sources/{n}/pause
Resumes (after a pause) the recording of the source identified by the unique id or the index.
GET http://localhost:8080/sources/{n}/resume
Continues the recording in a new file.
GET http://localhost:8080/sources/{n}/manual_split
Disables/Enables the ability to start/pause/resume/stop recording on the source identified by the unique id or the index.
GET http://localhost:8080/sources/{n}/lock
GET http://localhost:8080/sources/{n}/unlock
Gang Controls
Instead of controlling each source individually, you can control them together by simply sending an array of sources that you want to control. You simply pass an array of unique ids or indexes of sources to control. If you don't pass any array, you will control all sources.
The following is the response to the creation of a new scheduled recording. It confirms and returns the UID of the scheduled recording that was created.
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.
Valid values for the type key are: Boolean, Text, Number, Date/Time and Multiple Choice
Working with Metadata Sets
The following request will retrieve all the metadata sets available for MovieRecorder.
The following request will get the info of the metadata set assigned toa specific source. WARNING: this does not return the current values of the metadata, but the metadata set itself, see the next request to get the metadata values set on the source.
GET http://localhost:8080/sources/{n}/metadata_set
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
For more Information
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.