M|Replay REST API

M|Replay's REST API allows you to retrieve M|Replay's inputs and outputs, control the playback, create clips, etc... If you have additional needs, don't hesitate to reach out to us.
M|Replay uses port 8090 by default, but this can be configured in the preferences of M|Replay.

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:

Code Meaning Description
200 OK The request was succesfully processed.
201 Created A new resource has been created on server side.
202 Accepted The resquest was accepted but was not processed.
400 Bad Request The resquest was not well formed.
401 Unauthorized The request needs an access token to proceed. See Authorization
403 Forbidden The token provided doesn't have sufficient privileges/permissions. See Authorization
404Not found The resquest couldn't be processed. The path is not recognized.
422 Unprocessable entity The resquest is well formed but is sementically incorrect

To know if your request succeded; command, update, create and delete requests are followed with this kind of response:

Command response object:

{
  "success" : boolean,
  "error" : string OPTIONAL
}

"success": Indicates if the request was accepted and processed or not by M|Replay.
"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 M|Replay's preferences. (General -> HTTP Remote Control -> Password -> Required).

If this feature is enabled, it implies that you have to send the password defined in M|Replay 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 /inputs?password=1234

Unique id - index or display name ?

To specify which output you are controlling, you can use in the url, either:


To specify which input, you can use in the body of the request, either (in order of priority in case you indicate multiple ones):

Each clip, marker or playlist can be addressed using either its unique_id, its index or eventually its display name.

Getting informations about the M|Replay Instance and session

Get info about M|Replay

You can get some info about the application itself

GET /info
Response:
{
  "time_zone": string, eg: "Europe\/Brussels" 
  "computer_name": string, eg: "Admin's computer" 
  "application_name": string, eg: "M|Replay" 
  "application_build_number": string, eg: "402090" 
  "mac_os_version": string, eg: "14.1" 
  "application_in_demo": boolean ,
  "application_version": string eg: "4.2" 
}

Get info about the current session

And you can get some useful information about the current session as well with the following request:

GET /status
Response:
{
  "playback_rate" : number, eg: "0" 
  "remaining_time" : number, eg: "1151.04" 
  "remaining_timecode" : string, eg: "00:00:00:00" 
  "current_time" : number, eg: "1151.04" 
  "current_timecode" : string, eg: "00:00:00:00" 
  "playhead_time" : number, eg: "1151.04" 
  "playhead_timecode" : string, eg: "16:54:43:01" 
  "delay_time": number, eg: "0.00" 
  "delay_timecode": string, eg: "16:54:43:01" 
  "drop_frame" : boolean, 
  "loop_recording" : boolean, 
  "framerate" : number, eg: "25" 
  "remaining_space" : string, eg: "Remaining Space: 404 GB" 
}

Working with inputs and outputs

Retrieve the list of available inputs or outputs

To retrieve the list of available inputs:

GET /inputs
Response:
[
  {
  "name" : string, eg: "Camera 1" 
  "unique_id" : string, eg: "FDK3LAFVJFBS68" 
  "enabled" : boolean 
  }
]

To retrieve the list of available inputs:

GET /outputs
Response:

[
  {
  "name" : string, eg: "Output 1" 
  "unique_id" : string, eg: "MGFLDGHKFINGQFHDJ" 
  "device_type" : number, 
Device Type
"enabled" : boolean, "selected" : boolean, "input_unique_id" : "Camera 1" } ]

Defining which output is selected

In M|Replay, one of your output can be the selected one. This means it will be the one reacting to keyboard shortcuts, or to XC8, or to some REST requests. So it is important to change this with care. To set which output is selected, you have to use the following command:

PUT /outputs/{n}
Body:
{
  "selected": boolean, 
}

Assigning an input to an output

The following command can be used to assign an input to an output, and you can use the input UID, index, or name

Using input "Unique ID"

PUT /outputs/{n}
Body:
{
  "input_unique_id": string, eg: "GQDFLAKLK45L45"
}

Using input "Index"

PUT /outputs/{n}
Body:
{
  "input_index": number, eg: "2" 
}

Using input "Name"

PUT /outputs/{n}
Body:
{
  "input_name": string, eg: "My Camera 01"
}

Note that if you specify more than one parameter (for example if you indicate both the input unique id and its name), the priority will be first the unique id, then index, then name.

About the time references, and values

For Clips and Markers

When creating clips or markers, to indicate at which position they should be created, you will have to set what reference to use, either:

For Playhead position - Go to time

When controlling the position of the playhead, you can use the following kind of request. This will do the same thing as when clicking in the "Current Time" field in the user interface and where you can enter an "absolute" timecode to go to that timecode, or a relative time to go one hour back for example. You will set the position of the playhead and also indicate in reference to what this value should be applied:

Seconds, Timecode, positive or negative

Additionally to the reference, you will define either an offset relative to that reference, or an absolute time:

You can use either seconds or timecode, and these values can be positive or negative. Note that nothing will need to be specified, we will interpret according to what we receive):

Working with Markers - In Browser

Creating markers

See above for the different time references and values.

POST /markers
Body:
{
  "name": string, eg: "My Marker" 
  "unique_id": string, eg: "AZ21334-FGFGHGR-143356778" 
  "reference": string, 
reference
"time": string, eg: "00:00:00:00" "offset": string, eg: "00:00:00:00" "input_unique_id": string, eg: "3813338208-0" }

Modifying markers

When modify a marker, you will have to use PUT, and then you can pass any of the keys below to change their name, or position.

PUT /markers/{n}

Retrieving markers

You can retrieve all the markers:

GET /markers
Response:: array of Marker Objects

You can also retrieve just a specific marker, by indicating its index, unique_id or name:

GET /markers/{n}
Response: Marker Object

Working with Clips - In Browser

Creating clips

See above for the different time references and values.

When creating a clip, you will have to specify a duration, or an in, or out point. You will have to specify 2 of them.

POST /clips
Body:
{
  "name": string, eg: "My Clip" 
  "unique_id": string, eg: "AZ21334-FGFGHGR-143356778" 
  "reference_in_point": string, 
reference
"in_point": string, Timecode value - eg: "-00:00:10:00" "reference_out_point": string,
reference
"out_point": string, Timecode value - eg: "00:00:00:00" "duration": string, Timecode value - eg: "00:00:10:00" "unique_name": boolean "input_unique_id": string, eg: "3813338208-0" }

Modifying clips

When modify a clip, you will have to use PUT, and then you can pass any of the keys below to change their name, or in/out points.

PUT /clips{n}

Retrieving clips

You can retrieve all the clips:

GET /clips
Response:: array of Clip Objects

You can also retrieve just a specific clip, by indicating its index, unique_id or name:

GET /clips/{n}
Response:: Clip Object

Working with Playlists

Creating Playlists

You can create empty playlists. OR you can immediately add clips to your playlists when creating it. You can use either 'external' clips, or 'internal' ones.

POST /playlists
Body:
{
  "chain": boolean, 
  "loop": boolean, 
  "unique_id": string, eg: "AZ21334-FGFGHGR-143356778" 
  "name": string, eg: "Playlist 1" 
  "items": an array of clips. OPTIONAL. See the 'Adding clips to playlists' section for more info.
}

Modifying Playlists

PUT /playlists/{n}

Deleting Playlists

DELETE /playlists/{n}

Retrieving playlists

You can retrieve all the playlists:

GET /playlists
Response: array of Playlist Objects

You can also retrieve just a specific playlist, by indicating its index:

GET /playlists/{n}
Response: Playlist Object

Working with Clips - In Playlists

Adding clips to Playlists

You can add a clip at the end of the playlist, by not indicating any index:

POST /playlists/{n}/items

You can add a clip at a specific position in the playlist, by indicating an index at which you want to add the clip in the playlist:

POST /playlists/{n}/items/{indexOfClipInPlaylist}

For the body of the request, you can either add an internal clip (from the session's browser):

Body:
{
	"unique_id": string, eg: "AZ21334-FGFGHGR-143356778" 
	"playback_rate": integer, eg: 50 
	"browser_item_unique_id":string,eg: "F62AF042-28BF-4113-9334-664096779E04" 
	"input_unique_id": string, eg: "3813338208-0" 
}

Or an external clip (From the Finder)

Body:
{
	"unique_id": string, eg: "AZ21334-FGFGHGR-143356778" 
	"file_url": string, eg: "/Volumes/Videos/MyVideo.mov" 
}

Modifying clips in Playlists

PUT /playlists/{n}/items/{m}

For the body of the request, you can either modify an internal clip (from the session's browser):

Or an external clip (From the Finder)

Deleting Clips in Playlists

DELETE /playlists/{n}/items/{m}

Retrieving clips in playlists

You can retrieve all the playlists:

GET /playlists/{n}/items
Response: Array of: Playlist Internal Item Objects

Or

Response: Array of: Playlist External Item Objects

You can also retrieve just a specific clip, by indicating its index in the playlist:

GET /playlists/{n}/items/{m}

Or

Controlling Playback - In the Viewers

Playback Rate

You can use the following kind of request to control the playback rate in the viewers. 0 is stopped, 1 is normal playback speed, -1 is normal playback speed backwards, you can use positive or negative values up to 64. For example:

Stop playback

GET /set_playback_rate?rate=0

Play forward at 1x

GET /set_playback_rate?rate=1

Play backwards at 32x

GET /set_playback_rate?rate=-32


Playhead position - Go to time

See above for the different time references and values. Below are a few examples:

Go to Live

GET /set_position?position=0&reference=live

Go to 1 hour before Live, using seconds

GET /set_position?position=-3600&reference=live

Go to 1 hour before Live, using timecode

GET /set_position?position=-01%3A00%3A00%3A00&reference=live

Go to 10 seconds before the current playhead position, using seconds

GET /set_position?position=-10&reference=playhead

Go to time code 16:30:10:10

GET /set_position?position=16%3A30%3A10%3A10&reference=absolute

Go to 5 seconds before the in point, using seconds

GET /set_position?position=-5&reference=in_point

Controlling Playback - In the playlists

Play a playlist

GET /playlists/{n}/play

Pause a playlist

GET /playlists/{n}/pause

Stop a playlist

GET /playlists/{n}/play

Skipt to the previous clip in a playlist

GET /playlists/{n}/skip_previous

Skipt to the next clip in a playlist

GET /playlists/{n}/skip_next

Play a specific clip in the playlist

GET /playlists/{n}/items/{m}/play

Pause a playlist

GET /playlists/{n}/items/{m}/pause

For more information

If you need more info or support about M|replay, 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.