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:
"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 http://localhost:8090/inputs?password=1234
Unique id - index or display name ?
To specify which output you are controlling, you can use in the url, either:
its index ⓘ
its name ⓘ
"-1" for the "selected output"
To specify which input, you can use in the body of the request, either (in order of priority in case you indicate multiple ones):
its unique ID
its index ⓘ
its name
Each clip, marker or playlist 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 M|Replay. 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.
Getting informations about the M|Replay Instance and session
Get info about M|Replay
You can get some info about the application itself
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 http://localhost:8090/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
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:
"live": the clip/marker will be set at the current "Live" time, even if the user has scrubbed and is playing back at a different position.
"playhead": the clip/marker will be set at the position of the playhead (if the user has used the jog shuttle, and is playing back in time, it will be logged at that position).
"absolute": the clip/marker will be set at the time indicated in the "time" value you pass in the JSON.
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:
"live": the playhead will move to a position relative to the "Live" time, even if the user has scrubbed and is playing back at a different position. This is ideal if you know you need to go to 1 hour prior to live time for example. If you set the time to 0, it will go to Live.
"playhead": the playhead will move to a position relative to the current position of the playhead (if the user has used the jog shuttle, and is playing back in time, it will be logged at that position). This is what you should use if you want to fine tune, and for example move just 10 seconds back compared to where you are currently.
"absolute": the playhead will move to an absolute position. This is what you will use if you know at which timecode you want to jump to. If you want to go to 8PM for example.
"in_point": the playhead will move to a position relative to the current value of the in point (before a clip is created). Allowing you to quickly jump back to that position.
"out_point": the playhead will move to a position relative to the current value of the out point (before a clip is created). Allowing you to quickly jump back to that position.
Seconds, Timecode, positive or negative
Additionally to the reference, you will define either an offset relative to that reference, or an absolute time:
When using "live", "playhead", "in_point", or "out_point", you must also specify an "offset", even if it is zero. It can be either positive or negative
When using "absolute" time, you must specify a "time" value. It can only be positive. You should also make sure that the TC you indicate is within the range of the session.
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):
seconds: You can set the position in seconds. Just enter something like 10 for 10 seconds, 3600 for one hour, etc.
timecode: You can set the position using timecode. As the : don't go well in an URL, replace them with %3A. So a 01:00:00:00 timecode will look like this: 01%3A00%3A00%3A00
positive or negative: set a negative value if you want to go in the past, and a positive value to go in the future. Of course an "absolute" timecode will only be positive as it's not relative to a previous time.
Working with Markers - In Browser
Creating markers
See above for the different time references and values.
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 http://localhost:8090/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.
}
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 http://localhost:8090/set_playback_rate?rate=0
Play forward at 1x
GET http://localhost:8090/set_playback_rate?rate=1
Play backwards at 32x
GET http://localhost:8090/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 http://localhost:8090/set_position?position=0&reference=live
Go to 1 hour before Live, using seconds
GET http://localhost:8090/set_position?position=-3600&reference=live
Go to 1 hour before Live, using timecode
GET http://localhost:8090/set_position?position=-01%3A00%3A00%3A00&reference=live
Go to 10 seconds before the current playhead position, using seconds
GET http://localhost:8090/set_position?position=-10&reference=playhead
Go to time code 16:30:10:10
GET http://localhost:8090/set_position?position=16%3A30%3A10%3A10&reference=absolute
Go to 5 seconds before the in point, using seconds
GET http://localhost:8090/set_position?position=-5&reference=in_point
Controlling Playback - In the playlists
Play a playlist
GET http://localhost:8090/playlists/{n}/play
Pause a playlist
GET http://localhost:8090/playlists/{n}/pause
Stop a playlist
GET http://localhost:8090/playlists/{n}/play
Skipt to the previous clip in a playlist
GET http://localhost:8090/playlists/{n}/skip_previous
Skipt to the next clip in a playlist
GET http://localhost:8090/playlists/{n}/skip_next
Play a specific clip in the playlist
GET http://localhost:8090/playlists/{n}/items/{m}/play
Pause a playlist
GET http://localhost:8090/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.