Multicam Logger REST API

Multicam Logger uses port 8888 by default, but this can be configured in the preferences of Multicam Logger.

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 Multicam Logger.
"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.

General requests

Which document will "reply"?

As Multicam Logger is a "document based" application, you can have multiple documents opened. You should note that it's the front most document that will answer to your requests.

Start and Stop logging

Once a document is created (you can not do that with the API), you can start and stop logging using the following requests.

GET /start
GET /stop

Retrieve the list of available inputs

Returns a list of inputs that are available for the "front" document. So it represents that inputs that were available when the document was created and thus can be different to what you can see in the preferences.

GET /inputs
Response (Example):
[
  "INPUT 1",
  "INPUT 2",
  "INPUT 3",
  "INPUT 4",
]

Retrieve the current state

Returns a few information, such as which input is selected in program and which one is in preview (their zero based index). Or the current timecode, the front document name and if it is currently logging or not.

GET /status
Response:
{
  "document_name" : string, eg: "My Document Name" 
  "timecode" : string, eg: "01:00:05;00" 
  "preview" : number, eg: "0" 
  "program" : number, eg: "0" 
  "logging_state" : boolean, 
 }

About the time references, and values

Time references

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

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

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

Creating markers using "POST"

When using the POST method, you should pass a json dictionary with "name" to set the title of the marker.

POST /add_marker
Body:
{
  "name": string, eg: "My Marker" 
  "reference": string, 
reference
OPTIONAL "offset": string, eg: "00:00:00:00" OPTIONAL }

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

Retrieving markers

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

GET /markers
Response:
{
  "name": string, eg: "My Marker" 
  "time": string, eg: "01:00:05;00" 
 }

You can also retrieve just a specific marker, by indicating its index (again it's zero based)

GET /markers/{n}
Response:
{
  "name": string, eg: "My Marker" 
  "time": string, eg: "01:00:05;00" 
}

Working with Angles

Changing angles & doing TAKE

You can also change the selected angle in program and preview.

IMPORTANT NOTE: If you are working with an ATEM or Tricaster, changing in the UI of Multicam Logger also changes in the production switcher. So it means you can control your production switcher from a simple web page.

Note that the index is 0 based. This also can be done either with a POST or a GET.

When using You can indicate both the program and preview, or just set the program, or just the preview.You can do it using POST:

POST /change_angle
Body:
{
  "program": number, eg: "0"  OPTIONAL
  "preview": number, eg: "1"  OPTIONAL
}

Or using a GET request:.

GET /change_angle?program=0&preview=1

For both the GET and POST requests, you can either:

Retrieving angles

You can also retrieve the list of angle changes that were done:

GET /angle_changes
Response (Array):
[
  {
    {
      "out_point" : string, eg: "01:00:05;00" 
      "in_point" : string, eg: "01:00:05;00" 
      "duration" : string, eg: "01:00:05;00" 
      "program" : number, eg: "0" 
    }
  }
]

Note that the "program" value shows the index of the inputs that was used in program. You can use GET /inputs to retrieve the names of these.

For more information

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