api/markers

This interface allows to add, modify and delete markers in output files of a running job. As a job may create several output files, which are part of an output graph, the output graph must be specified if there's more than one in the job.

Note:  Currently, all marker data is internally cached, and only written to the actual file when the job is being finished and the file is finalized. This is due to the specifications of the output file format (WAV/BWF).

Contents

Use Cases

• Add once or several markers to a running job's output file

Interface Usage

REST philosophy is a bit different from function-centric thinking. So to fulfill best practices, we use resource-centric interfaces:

Notes

• A success result does not guarantee, that the marker operation will be completed successfully, but only that the command was received and verified to be correct.
• All data, incl. the job ID and the markers' metadata, is passed in the REST body in JSON format (q.v. below)
• All request return 404, if the specified job does not exist.

Data Format

POST, PUT, DELETE /markers

Data must be formatted in a JSON containing these fields:

• "jobId" (mandatory): Specifies the job's ID.
• "markers" (mandatory): Contains either a single marker specification, or a list of marker specifications (as a JSON array). Each marker specification contains the following data:
  • "id" (mandatory):  ID of this marker. The ID must be unique for the job.
  • "outGraph" (optional): Specifies the name of the output graph creating the file where the marker is to be placed in. If this field is not specified, the marker(s) are set to all output files of the job.
  • "timestamp_Abs" (optional, must not be combined with other "timestamp_???" fields): Specifies the absolute time to place the marker at. This requires the job to know the absolute time (e.g. by the begin of a recording and an offset).
  • "timestamp_Rel" (optional, must not be combined with "timestamp_???" fields): Specifies the relative time from start of audio to the marker position. Pass seconds with post-comma digits, separated by a dot (".").
  • "timestamp_File" (optional, must not be combined with "timestamp_???" fields): Specifies the relative time from start of the currently recorded file to the marker position. Pass seconds with post-comma digits, separated by a dot ("."). This is identical to "timestamp_Rel", unless the job has output file switches.
  • "label" (optional): Descriptive text for the marker.

Notes

• In a POST request, the client must provide a not yet existing ID for each new marker. Otherwise, this marker will not be created.
• In a PUT or DELETE request, the client must provide existing IDs.
• If no timestamp is passed ...
  • ... for a new marker, it will be set at the position of current recording when this command is received by the ROAD Worker process. So there's an undefined amount of delay.
  • ... for an existing marker, it will keep its position, and only the label is changed.

POST Example

{
  "jobId": "JOB6",
  "markers": [
    {
      "id": "M1",
      "outGraph": "GraphOut1",
      "timestamp_Abs": "2019-01-21T17:55:20",
      "label": "This is a fix time label"
    },
    {
      "id": "M2",
      "outGraph": "GraphOut1",
      "timestamp_Rel": "817.1234"
    }
  ]
}

PUT /markers/{markerId}

Data must be formatted in a JSON containing these fields:

• "jobId" (mandatory): Specifies the job's id.
• "markers" (mandatory): Contains a single marker specification with the following data:
  • "id" (optional):  ID of the marker to be modified. The field can be omitted, because the ID is already in the URL.
  • "outGraph" (optional): Specifies the name of the output graph creating the file where the marker is to be placed in. If this field is not specified, the marker(s) are set to all output files of the job.
  • "timestamp_Abs" (optional, must not be combined with other "timestamp_???" fields): Specifies the absolute time to place the marker at. This requires the job to know the absolute time (e.g. by the begin of a recording and an offset).
  • "timestamp_Rel" (optional, must not be combined with "timestamp_???" fields): Specifies the relative time from start of audio to the marker position. Pass seconds with post-comma digits, separated by a dot (".").
  • "timestamp_File" (optional, must not be combined with "timestamp_???" fields): Specifies the relative time from start of the currently recorded file to the marker position. Pass seconds with post-comma digits, separated by a dot ("."). This is identical to "timestamp_Rel", unless the job has output file switches.
  • "label" (optional): Descriptive text for the marker.

Notes

• If no "timestamp_???" field is provided, the time position of the marker is unchanged.
• If "id" is specified in the JSON body, but doesn't match the ID from the URL, the request will fail with code 400 (Bad Request).

DELETE /markers/{markerId}

Data must be formatted in a JSON containing these fields:

• "jobId" (mandatory): Specifies the job's id.