Skip to content

Developers

How can we help you?

← Go back

Marker

The marker resource represents a point or portion of an asset.

In Mediagenix On-Demand land, a marker looks like this:

<?xml version="1.0" encoding="utf-8" ?>
<marker>
  <id type="integer">245</id>
  <external-id>AB123</external-id>
  <type>Marker type</type>
  <start type="duration">00:00:10.100</start>
  <end type="duration">00:01:20.355</end>
  <runtime type="duration">00:01:10.255</runtime>
  <link rel="self" href="https://movida.bebanjo.net/api/markers/245"/>
  <link rel="asset" href="https://movida.bebanjo.net/api/assets/123"/>
</marker>

{
  "resource_type": "marker",
  "id": 245,
  "external_id": "AB123",
  "type": "Marker type",
  "start": "00:00:10.100",
  "end": "00:01:20.355", 
  "runtime": "00:01:10.255",
  "self_link": "https://movida.bebanjo.net/api/markers/702211",
  "asset_link": "https://movida.bebanjo.net/api/assets/1539475"
}

Marker attributes

  • id (required): Mediagenix On-Demand internal identifier of the marker.

  • external-id (optional): Identifier of the marker in a external system.

  • type (required): the type of the marker. Please, contact your Customer Success Manager in order to define the list of marker types suitable for your company.

  • start (required): Timecode representing the beginning of the marker. It should be less than the end.

  • end (optional): Timecode representing the end of the marker. It should be greater than the start.

  • runtime (optional): Timecode representing the duration of the marker.

Get a list of all markers of an asset

Markers are accessed via an asset. Inside an asset, one of the related link nodes is the markers node, identified by the rel attribute. Like here:

<asset>
  <!-- ... -->
  <link rel="markers" href="https://movida.bebanjo.net/api/assets/123/markers"/>
  <!-- ... -->
</asset>

{
  "resource_type": "asset",
  // ...
  "markers_link": "https://movida.bebanjo.net/api/assets/123/markers",
  // ...
}

If we follow that link, we can fetch the list of all markers for that asset.

$ curl --digest -u robot_user:password https://movida.bebanjo.net/api/assets/123/markers

$ curl --digest -u robot_user:password -H "Accept: application/json" https://movida.bebanjo.net/api/assets/123/markers

<?xml version="1.0" encoding="utf-8" ?>
<markers type="array">
  <total-entries>2</total-entries>
  <marker>
    <id type="integer">245</id>
    <external-id>AB123</external-id>
    <type>Marker type</type>
    <start type="duration">00:00:10.100</start>
    <end type="duration">00:01:20.355</end>
    <runtime type="duration">00:01:10.255</runtime>
    <link rel="self" href="https://movida.bebanjo.net/api/markers/245"/>
    <link rel="asset" href="https://movida.bebanjo.net/api/assets/123"/>
  </marker>
  <marker>
    <id type="integer">246</id>
    <type>Marker type</type>
    <start type="duration">00:01:20.211</start>
    <link rel="self" href="https://movida.bebanjo.net/api/markers/246"/>
    <link rel="asset" href="https://movida.bebanjo.net/api/assets/123"/>
  </marker>
</markers>

{
  "total_entries": 2,
  "entries": [
    {
      "resource_type": "marker",
      "id": 245,
      "external_id": "AB123",
      "type": "Marker type",
      "start": "00:00:10.100", 
      "end": "00:01:20.355",
      "runtime": "00:01:10.255",
      "self_link": "https://movida.bebanjo.net/api/markers/245",
      "asset_link": "https://movida.bebanjo.net/api/assets/123"
    },
    {
      "resource_type": "marker",
      "id": 246,
      "type": "Marker type",
      "start": "00:01:20.211",
      "self_link": "https://movida.bebanjo.net/api/markers/246",
      "asset_link": "https://movida.bebanjo.net/api/assets/123"
    }
  ]
}

This is a paginated resource.

Creating markers for an asset

To create markers, you just need to POST proper XML/JSON marker representation (similar to the ones you get when fetching a marker) to the markers URL of an asset. That URL can be found in a link which rel attribute equals to markers.

For example, this POST would create an marker (we’ll use curl’s @ option, which reads data to be posted from a file):

$ cat marker.xml

$ cat marker.json

<marker>
  <external-id>AB123</external-id>
  <type>Marker type</type>
  <start>00:02:10</start>
  <end>00:03:20</end>
</marker>

{
  "external_id": "AB123",
  "type": "Marker type",
  "start": "00:02:10",
  "end": "00:03:20"
}

$ curl --digest -u robot_user:password -H "Content-Type: application/xml" -X POST -d @marker.xml "https://movida.bebanjo.net/api/assets/123/markers"

$ curl --digest -u robot_user:password -H "Content-Type: application/json" -H "Accept: application/json" -X POST -d @marker.json "https://movida.bebanjo.net/api/assets/123/markers"

Mediagenix On-Demand will return the full XML/JSON of the marker just created:

<?xml version="1.0" encoding="UTF-8"?>
<marker>
  <id type="integer">246</id>
  <external-id>AB123</external-id>
  <type>Marker type</type>
  <start>00:02:10.000</start>
  <end>00:03:20.000</end>
  <runtime type="duration">00:02:10.000</runtime>
  <link rel="self" href="https://movida.bebanjo.net/api/markers/246"/>
  <link rel="asset" href="https://movida.bebanjo.net/api/assets/123"/>
</marker>

{
  "resource_type": "marker",
  "id": 246,
  "external_id": "AB123",
  "type": "Marker type",
  "start": "00:02:10.000",
  "end": "00:03:20.000",
  "runtime": "00:02:10.000",
  "self_link": "https://movida.bebanjo.net/api/markers/246",
  "asset_link": "https://movida.bebanjo.net/api/assets/123"
}

Updating a marker

You can update markers issuing a PUT request to the URL of a given marker, as the following example illustrates. This example only updates the markers’s start timecode.

$ cat marker.xml

$ cat marker.json

<marker>
  <type>Type 2</type>
  <start>00:02:20.123</start>
</marker>

{
  "type": "Type 2",
  "start": "00:02:20.123"
}

Now we send the XML/JSON as the body of a PUT request to the markers’s URL:

$ curl --digest -u robot_user:password -H "Content-Type: application/xml" -X PUT -d @markers.xml "https://movida.bebanjo.net/api/markers/246"

$ curl --digest -u robot_user:password -H "Content-Type: application/json" -H "Accept: application/json" -X PUT -d @markers.json "https://movida.bebanjo.net/api/markers/246"

The PUT request would return the updated XML/JSON of the marker:

<marker>
  <id type="integer">246</id>
  <external-id>AB123</external-id>
  <type>Type 2</type>
  <start>00:02:20.123</start>
  <end>00:03:20.000</end>
  <runtime>00:00:59.877</runtime>
  <link rel="self" href="https://movida.bebanjo.net/api/markers/246"/>
  <link rel="asset" href="https://movida.bebanjo.net/api/assets/123"/>
</marker>

{
  "resource_type": "marker",
  "id": 246,
  "external_id": "AB123",
  "type": "Type 2",
  "start": "00:02:20.123",
  "end": "00:03:20.000",
  "runtime": "00:00:59.877",
  "self_link": "https://movida.bebanjo.net/api/markers/246",
  "asset_link": "https://movida.bebanjo.net/api/assets/123"
}

Delete a marker of an asset

The following example shows how to destroy a particular marker. Only a DELETE HTTP request to its URL is required:

$ curl --digest -u robot_user:password -X DELETE "https://movida.bebanjo.net/api/markers/246"

$ curl --digest -u robot_user:password -H "Accept: application/json" -X DELETE "https://movida.bebanjo.net/api/markers/246"

The DELETE request doesn’t return anything, as that marker is now gone.

Deleting a marker won’t have any side-effect on linked resources such as the parent asset.