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 item (source, destination or scheduled recording) in opening order. The index '0' would represent the first item, then '1' would represent the second and so on. WARNING! Indexes can change if you connect/disconnect or enable/disable a source for example. With "Sources", you can pass a "include_disabled_sources" parameter in the URL, the index can either be the one of all the sources, or only of the enabled ones. If you don't pass the parameter, it will be only the enabled ones. Make sure to be consistent between your request to be sure to address the appropriate source index, or prefer using unique ids.
Getting information about the MovieRecorder Instance
Get info about MovieRecorder
You can get some info about the application itself
Like other items, each source can be addressed by unique_id (stable) or by index (its position in the list).
By default, an index is evaluated among enabled sources only. To evaluate indices among all sources (including disabled), append the URL parameter include_disabled_sources=YES.
You may pass this parameter on any request that uses a source index — both when listing sources and on per‑source endpoints (e.g. /sources/{n}, /sources/{n}/info, /sources/{n}/thumbnail, /sources/{n}/destinations, etc.).
Important — be consistent: if you choose to include disabled sources, append include_disabled_sources=YES to every related request that uses an index; otherwise the same index may refer to a different source. Prefer unique_id when possible.
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).
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
Note: For any per‑source control endpoint addressed by index — /sources/{n}/record, /stop, /pause, /resume, /manual_split, /lock, /unlock — append ?include_disabled_sources=YES if you want indices evaluated among all sources (enabled + disabled). Be consistent across related requests to avoid addressing a different source.
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.
You can also pass a parameter in the url to set if you want to control all enabled sources, or just the ones selected.
Note: When sending an array of indexes (instead of unique IDs) to gang endpoints, you can control how those indexes are resolved by adding ?include_disabled_sources=YES to the URL to evaluate among all sources. Use this parameter consistently anywhere you rely on indexes.
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
[
"My First Configuration",
"My Second Configuration"
]
Restore a saved configuration
Once you know which configurations are available, you can simply restore them. Using their name, and specifying what you want to restore.
PUT http://localhost:8080/restore_configuration
Body:
{
"name": "My First Configuration"
"restore_vtr_bach_list": true,
"restore_sources": true,
"restore_av_presets": true,
"restore_destinations": true,
"restore_schedule": true,
"restore_layout": true,
}
About Websockets
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.
