Skip to content

Developers

How can we help you?

← Go back

Segment

The segment resource represents a portion of an asset.

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

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

{
  "resource_type": "segment",
  "id": 245,
  "external_id": "AB123",
  "type": "Segment type",
  "position": 1,
  "start": "00:00:10.100",
  "end": "00:01:20.355",
  "self_link": "https://movida.bebanjo.net/api/segments/702211",
  "asset_link": "https://movida.bebanjo.net/api/assets/1539475"
}

Segment attributes

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

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

  • type (optional): the type of the segment. There is a closed list of values.

  • position (optional): Position of the segment within the asset. If none is given, the last position will be assigned.

  • start (optional): Timecode representing the beginning of the segment. Required only if end is present and it should be less than the end.

  • end (optional): timecode representing the end of the segment. Mandatory only if start is present and it should be greater than the start.

Get a list of all segments of an asset

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

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

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

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

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

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

<?xml version="1.0" encoding="utf-8" ?>
<segments type="array">
  <total-entries>2</total-entries>
  <segment>
    <id type="integer">245</id>
    <external-id>AB123</external-id>
    <type>Segment type</type>
    <position type="integer">1</position>
    <start type="duration">00:00:10.100</start>
    <end type="duration">00:01:20.355</end>
    <link rel="self" href="https://movida.bebanjo.net/api/segments/245"/>
    <link rel="asset" href="https://movida.bebanjo.net/api/assets/123"/>
  </segment>
  <segment>
    <id type="integer">246</id>
    <external-id>AB124</external-id>
    <type>Segment type</type>
    <position type="integer">2</position>
    <start type="duration">00:01:20.211</start>
    <end type="duration">00:03:23.333</end>
    <link rel="self" href="https://movida.bebanjo.net/api/segments/246"/>
    <link rel="asset" href="https://movida.bebanjo.net/api/assets/123"/>
  </segment>
</segments>

{
  "total_entries": 2,
  "entries": [
    {
      "resource_type": "segment",
      "id": 245,
      "external_id": "AB123",
      "type": "Segment type",
      "position": 1,
      "start": "00:00:10.100",
      "end": "00:01:20.355",
      "self_link": "https://movida.bebanjo.net/api/segments/245",
      "asset_link": "https://movida.bebanjo.net/api/assets/123"
    },
    {
      "resource_type": "segment",
      "id": 246,
      "external_id": "25062252",
      "type": null,
      "position": 2,
      "start": "00:01:20.211",
      "end": "00:03:23.333",
      "self_link": "https://movida.bebanjo.net/api/segments/246",
      "asset_link": "https://movida.bebanjo.net/api/assets/123"
    }
  ]
}

This is a paginated resource.

Creating segments for an asset

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

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

$ cat segment.xml

$ cat segment.json

<segment>
  <external-id>AB123</external-id>
  <position>3</position>
  <start>00:02:10</start>
  <end>00:03:20</end>
</segment>

{
  "external_id": "AB123",
  "position": 3,
  "start": "00:02:10",
  "end": "00:03:20"
}

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

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

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

<?xml version="1.0" encoding="UTF-8"?>
<segment>
  <id type="integer">246</id>
  <external-id>AB123</external-id>
  <type nil="true"></type>
  <position>3</position>
  <start>00:02:10.000</start>
  <end>00:03:20.000</end>
  <link rel="self" href="https://movida.bebanjo.net/api/segments/246"/>
  <link rel="asset" href="https://movida.bebanjo.net/api/assets/123"/>
</segment>

{
  "resource_type": "segment",
  "id": 246,
  "external_id": "AB123",
  "type": null,
  "position": 3,
  "start": "00:02:10.000",
  "end": "00:03:20.000",
  "self_link": "https://movida.bebanjo.net/api/segments/246",
  "asset_link": "https://movida.bebanjo.net/api/assets/123"
}

Creating segments for an asset providing a type

If the Segment Types enumeration exists, you can add types to your segments, eg: this enumeration has the following values: Type 1, Type2 and Type 3. If the enumeration has these values: Type 1, Type 2 and Type 3. If you try to create a segment with an invalid type, e.g. Type 4, then you will receive an message error.

$ cat segment.xml

$ cat segment.json

<segment>
  <external-id>AB123</external-id>
  <type>Type 1</type>
  <position>3</position>
  <start>00:02:10</start>
  <end>00:03:20</end>
</segment>

{
  "external_id": "AB123",
  "type": "Type 1",
  "position": 3,
  "start": "00:02:10",
  "end": "00:03:20"
}

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

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

Mediagenix On-Demand will return the full XML/JSON of the segment just created with the type included:

<?xml version="1.0" encoding="UTF-8"?>
<segment>
  <id type="integer">246</id>
  <external-id>AB123</external-id>
  <type>Type 1</type>
  <position>3</position>
  <start>00:02:10.000</start>
  <end>00:03:20.000</end>
  <link rel="self" href="https://movida.bebanjo.net/api/segments/246"/>
  <link rel="asset" href="https://movida.bebanjo.net/api/assets/123"/>
</segment>

{
  "resource_type": "segment",
  "id": 246,
  "external_id": "AB123",
  "type": "Type 1",
  "position": 3,
  "start": "00:02:10.000",
  "end": "00:03:20.000",
  "self_link": "https://movida.bebanjo.net/api/segments/246",
  "asset_link": "https://movida.bebanjo.net/api/assets/123"
}

Updating a segment

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

$ cat segment.xml

$ cat segment.json

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

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

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

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

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

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

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

{
  "resource_type": "segment",
  "id": 246,
  "external_id": "AB123",
  "type": "Type 2",
  "position": 3,
  "start": "00:02:20.123",
  "end": "00:03:20.000",
  "self_link": "https://movida.bebanjo.net/api/segments/246",
  "asset_link": "https://movida.bebanjo.net/api/assets/123"
}

Delete a segment of an asset

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

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

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

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

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