M|Replay REST API

REST API Quick start guide

Currently the only thing you can do with the REST API is to add new markers and clips and change the playback rate. If you have any additional request, please let us know.

M|Replay uses port 8090 by default, but this can be configured in the preferences of M|Replay.

General requests

Retrieve the list of available inputs

GET /inputs

Returns a list of inputs that are available.

Retrieve the list of available outputs

GET /outputs

Returns a list of outputs that are available.

Get infos about the current session

GET /status

{  
  "playback_rate" : 0,
  "remaining_time" : 1151.04,
  "remaining_timecode" : "00:19:11:01",
  "current_time" : 1151.04,
  "current_timecode" : "00:19:11:01",
  "playhead_time" : 60883.040000000001,
  "playhead_timecode" : "16:54:43:01",
  "delay_time": 0.00,
  "delay_timecode": "00:00:00:00",
  "drop_frame" : false,
  "loop_recording" : false,
  "framerate" : 25,
  "remaining_space" : "Remaining Space: 404 GB"
}

Working with Markers

Creating markers using "POST"

To add a marker, you can either use GET or POST.

When using the POST method, you should pass a json dictionary with "name" to set the title of the marker, as well as indicate at which position the marker should be set.

  • "live" the 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 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 marker will be set at the time indicated in the "time" value you pass in the JSON
Note that:
  • when using "live" or "playead", you must also specify an "offset", even if it is zero.
  • when using "absolute" time, you must specify a "time" value. You should also make sure that the TC you indicate is within the range of the session

Creating markers at the "live" time

POST add_marker
     {
      "name": "This is my Marker",
      "reference": "live",
      "offset": "00:00:00:00"
     }
     

Note that the syntax will be the same to create a marker at the "playhead" position.


Creating markers at an "absolute" time

POST add_marker
     {
      "name": "This is my Marker",
      "reference": "live",
      "time": "09:20:10:00"
     }
     


Creating markers using "GET"

When using the GET method, you don't need to pass a JSON, everything can be done in one url, so it is pretty convenient.

GET /add_marker?name=This%20is%20my%20Marker&reference=live


Retrieving markers

You can also retrieve the list of markers that were already created:

GET /markers

Returns a list of markers already created.

Example response:

      [
         {
         "ClipMarkerUniqueID" : "CCA8743A-BC76-45DF-88A9-B0A4F008F5AD",
         "ClipMarkerInPointString" : "16:33:17;30",
         "ClipMarkerIsMarker" : true,
         "ClipMarkerName" : "Marker",
         "ClipMarkerInPoint" : 562170797.44815099
         },
         {
         "ClipMarkerUniqueID" : "1FCB7520-33A6-40D5-B7C1-9B0FE85D98B1",
         "ClipMarkerInPointString" : "16:33:17;58",
         "ClipMarkerIsMarker" : true,
         "ClipMarkerName" : "Marker (1)",
         "ClipMarkerInPoint" : 562170797.91526401
         }
      ]
     

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

GET /markers/1

Returns the specified marker information.

Working with Clips

Creating clips using "POST"

To add a clip, you can either use GET or POST. You can also either specify a clip name, in point and out point. So in other words, create from scratch, or you can as in the user interface "mark" an in point and an out point and the clip will be automatically created in the user interface, just as if you click on the button.

When using the POST method, you should pass a json dictionary with "name" to set the title of the clip as well as the in/out and duration.

Creating clips with in and out points

First let's see how to create a clip ourselves. Note that if duration is provided, then out_point is ignored.

POST add_clip
 {
   "name": "Mon clip",
   "in_point": "00:01:00:00",
   "out_point": "00:02:30:00",
   "duration": "00:01:30:00"
}

Creating clips by setting in and out points

Or you can ask to mark an in point, and specify wether you want to set the in (or out) point at the "live" or "playhead" position. The example below shows how to mark an in point at the "live" time. You can set the "live reference" to false if you want to mark the in or out at the "playhead" position.

GET mark_in
{
  "live_reference"  : "true"
}
GET mark_out
{
  "live_reference"  : "true"
}


Creating clips using "GET"

When using the GET method, you don't need to pass a JSON, everything can be done in one url, so it is pretty convenient.

GET /add_clip?name=Mon%20clip&in_point=00%3A01%3A00%3A00&out_point=00%3A02%3A00%3A00
GET /add_clip?name=Mon%20clip&reference_in_point=live


Retrieving clips

You can also retrieve the list of clips that were already created:

GET /clips

Returns a list of markers already created.

Example response:

[
  {
    "ClipMarkerIsMarker" : false,
    "ClipMarkerName" : "Clip",
    "ClipMarkerInPointString" : "16:33:36;45",
    "ClipMarkerInPoint" : 562170816.71799803,
    "ClipMarkerOutPoint" : 562170819.28794098,
    "ClipMarkerOutPointString" : "16:33:39;19",
    "ClipMarkerDuration" : 2.5699429512023926,
    "ClipMarkerUniqueID" : "A4E2DF35-A9D5-45FA-943D-761522556E44"
  }
]

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

GET /clips/1

Returns the specified clip information.

Controlling Playback

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

You can use the following kind of request to control the position of the playhead. 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...
About the time values that can be used (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,...
  • 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
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%3B10&reference=absolute

Playhead position - Go to frame

You can use the following kind of request to control the position of the playhead. This will do the same thing as when using the left and right arrows for example. Values here are expressed in frames, you can use a value > 1 to jump multiple frames, but here is the code to go to next/previous frame:

Go to next frame

GET /set_frame_offset?frame_offset=1

Go to previous frame

GET /set_frame_offset?frame_offset=-1

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.