Video segment service#

Upon ingestion, every video is split into smaller segments. The Video Segment Service manages operations on videos at the segment-level.

OpenAPI file: VideoSegmentService.json

Endpoints#

Create video file segments#

POST /video/v1/videos/{videoRid}/{videoFileRid}/create-segments

Path parameters

videoRid string (RID) required

​

videoFileRid string (RID) required

​

Body

requests array of CreateSegment

​

Fields of CreateSegment
dataHandle Handle required

​

Set type to "s3".

s3 string

​

frameRate number required

The average frame rate (FPS) of the segment calculated as total frames / duration in seconds.

durationSeconds number required

​

timestamps SegmentTimestamps required

​

Set type to "timestampMappings".

timestampMappings TimestampMappings

​

Fields of TimestampMappings
mediaTimestamps array of number

​

absoluteTimestamps array of Timestamp

​

Fields of Timestamp
seconds integer (int64) required

​

nanos integer (int64) required

​

segmentEndTimestamp Timestamp required

​

seriesUuid string (UUID)

​

overWriteSegments boolean

If true, overlapping segments from other video files within the same video will be deleted before inserting new segments. The cached segment metadata for affected files will be recomputed.

Response

segments array of Segment

​

Fields of Segment
rid string (RID)

​

videoRid string (RID)

​

dataHandle Handle

​

Set type to "s3".

s3 string

​

frameRate number

The average frame rate (FPS) of the segment calculated as total frames / duration in seconds.

durationSeconds number

The duration of a segment in media time.

timestamps SegmentTimestamps

for videos with frame-level timestamps, we provide mappings, otherwise we just include a single list of timestamps.

Set type to "timestampMappings".

timestampMappings TimestampMappings

​

Fields of TimestampMappings
mediaTimestamps array of number

​

absoluteTimestamps array of Timestamp

​

Fields of Timestamp
seconds integer (int64)

​

nanos integer (int64)

​

Request

curl -X POST "https://api.gov.nominal.io/api/video/v1/videos/<video rid>/<video file rid>/create-segments" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "requests": [
    {
      "dataHandle": {
        "type": "s3",
        "s3": "<s3 path>"
      },
      "frameRate": 1,
      "durationSeconds": 1,
      "timestamps": {
        "type": "timestampMappings",
        "timestampMappings": {
          "mediaTimestamps": [
            1
          ],
          "absoluteTimestamps": [
            {
              "seconds": 1,
              "nanos": 1
            }
          ]
        }
      },
      "segmentEndTimestamp": {
        "seconds": 1,
        "nanos": 1
      }
    }
  ],
  "seriesUuid": "<series uuid>",
  "overWriteSegments": true
}'

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/video/v1/videos/<video rid>/<video file rid>/create-segments",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "requests": [
            {
                "dataHandle": {"type": "s3", "s3": "<s3 path>"},
                "frameRate": 1,
                "durationSeconds": 1,
                "timestamps": {
                    "type": "timestampMappings",
                    "timestampMappings": {
                        "mediaTimestamps": [1],
                        "absoluteTimestamps": [{"seconds": 1, "nanos": 1}],
                    },
                },
                "segmentEndTimestamp": {"seconds": 1, "nanos": 1},
            },
        ],
        "seriesUuid": "<series uuid>",
        "overWriteSegments": True,
    },
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/video/v1/videos/<video rid>/<video file rid>/create-segments",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "requests": [
            {
                "dataHandle": {"type": "s3", "s3": "<s3 path>"},
                "frameRate": 1,
                "durationSeconds": 1,
                "timestamps": {
                    "type": "timestampMappings",
                    "timestampMappings": {
                        "mediaTimestamps": [1],
                        "absoluteTimestamps": [{"seconds": 1, "nanos": 1}],
                    },
                },
                "segmentEndTimestamp": {"seconds": 1, "nanos": 1},
            },
        ],
        "seriesUuid": "<series uuid>",
        "overWriteSegments": True,
    },
)
response.raise_for_status()
print(response.json())

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/video/v1/videos/<video rid>/<video file rid>/create-segments",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "requests": [
                    {
                        "dataHandle": {"type": "s3", "s3": "<s3 path>"},
                        "frameRate": 1,
                        "durationSeconds": 1,
                        "timestamps": {
                            "type": "timestampMappings",
                            "timestampMappings": {
                                "mediaTimestamps": [1],
                                "absoluteTimestamps": [{"seconds": 1, "nanos": 1}],
                            },
                        },
                        "segmentEndTimestamp": {"seconds": 1, "nanos": 1},
                    },
                ],
                "seriesUuid": "<series uuid>",
                "overWriteSegments": True,
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "segments": [
    {
      "rid": "<segment rid>",
      "videoRid": "<video rid>",
      "dataHandle": {
        "type": "s3",
        "s3": "<s3 path>"
      },
      "frameRate": 1,
      "durationSeconds": 1,
      "timestamps": {
        "type": "timestampMappings",
        "timestampMappings": {
          "mediaTimestamps": [
            1
          ],
          "absoluteTimestamps": [
            {
              "seconds": 1,
              "nanos": 1
            }
          ]
        }
      }
    }
  ]
}

Create video stream segments#

POST /video/v1/videos/{videoRid}/streams/{streamUuid}/create-segments

Creates segments for a video stream. Similar to createVideoFileSegments but for streaming video.

Path parameters

videoRid string (RID) required

​

streamUuid string (UUID) required

​

Body

requests array of CreateSegment

​

Fields of CreateSegment
dataHandle Handle required

​

Set type to "s3".

s3 string

​

frameRate number required

The average frame rate (FPS) of the segment calculated as total frames / duration in seconds.

durationSeconds number required

​

timestamps SegmentTimestamps required

​

Set type to "timestampMappings".

timestampMappings TimestampMappings

​

Fields of TimestampMappings
mediaTimestamps array of number

​

absoluteTimestamps array of Timestamp

​

Fields of Timestamp
seconds integer (int64) required

​

nanos integer (int64) required

​

segmentEndTimestamp Timestamp required

​

seriesUuid string (UUID)

​

overWriteSegments boolean

If true, overlapping segments from other video files within the same video will be deleted before inserting new segments. The cached segment metadata for affected files will be recomputed.

Response

segments array of Segment

​

Fields of Segment
rid string (RID)

​

videoRid string (RID)

​

dataHandle Handle

​

Set type to "s3".

s3 string

​

frameRate number

The average frame rate (FPS) of the segment calculated as total frames / duration in seconds.

durationSeconds number

The duration of a segment in media time.

timestamps SegmentTimestamps

for videos with frame-level timestamps, we provide mappings, otherwise we just include a single list of timestamps.

Set type to "timestampMappings".

timestampMappings TimestampMappings

​

Fields of TimestampMappings
mediaTimestamps array of number

​

absoluteTimestamps array of Timestamp

​

Fields of Timestamp
seconds integer (int64)

​

nanos integer (int64)

​

Request

curl -X POST "https://api.gov.nominal.io/api/video/v1/videos/<video rid>/streams/<stream uuid>/create-segments" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "requests": [
    {
      "dataHandle": {
        "type": "s3",
        "s3": "<s3 path>"
      },
      "frameRate": 1,
      "durationSeconds": 1,
      "timestamps": {
        "type": "timestampMappings",
        "timestampMappings": {
          "mediaTimestamps": [
            1
          ],
          "absoluteTimestamps": [
            {
              "seconds": 1,
              "nanos": 1
            }
          ]
        }
      },
      "segmentEndTimestamp": {
        "seconds": 1,
        "nanos": 1
      }
    }
  ],
  "seriesUuid": "<series uuid>",
  "overWriteSegments": true
}'

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/video/v1/videos/<video rid>/streams/<stream uuid>/create-segments",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "requests": [
            {
                "dataHandle": {"type": "s3", "s3": "<s3 path>"},
                "frameRate": 1,
                "durationSeconds": 1,
                "timestamps": {
                    "type": "timestampMappings",
                    "timestampMappings": {
                        "mediaTimestamps": [1],
                        "absoluteTimestamps": [{"seconds": 1, "nanos": 1}],
                    },
                },
                "segmentEndTimestamp": {"seconds": 1, "nanos": 1},
            },
        ],
        "seriesUuid": "<series uuid>",
        "overWriteSegments": True,
    },
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/video/v1/videos/<video rid>/streams/<stream uuid>/create-segments",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "requests": [
            {
                "dataHandle": {"type": "s3", "s3": "<s3 path>"},
                "frameRate": 1,
                "durationSeconds": 1,
                "timestamps": {
                    "type": "timestampMappings",
                    "timestampMappings": {
                        "mediaTimestamps": [1],
                        "absoluteTimestamps": [{"seconds": 1, "nanos": 1}],
                    },
                },
                "segmentEndTimestamp": {"seconds": 1, "nanos": 1},
            },
        ],
        "seriesUuid": "<series uuid>",
        "overWriteSegments": True,
    },
)
response.raise_for_status()
print(response.json())

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/video/v1/videos/<video rid>/streams/<stream uuid>/create-segments",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "requests": [
                    {
                        "dataHandle": {"type": "s3", "s3": "<s3 path>"},
                        "frameRate": 1,
                        "durationSeconds": 1,
                        "timestamps": {
                            "type": "timestampMappings",
                            "timestampMappings": {
                                "mediaTimestamps": [1],
                                "absoluteTimestamps": [{"seconds": 1, "nanos": 1}],
                            },
                        },
                        "segmentEndTimestamp": {"seconds": 1, "nanos": 1},
                    },
                ],
                "seriesUuid": "<series uuid>",
                "overWriteSegments": True,
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "segments": [
    {
      "rid": "<segment rid>",
      "videoRid": "<video rid>",
      "dataHandle": {
        "type": "s3",
        "s3": "<s3 path>"
      },
      "frameRate": 1,
      "durationSeconds": 1,
      "timestamps": {
        "type": "timestampMappings",
        "timestampMappings": {
          "mediaTimestamps": [
            1
          ],
          "absoluteTimestamps": [
            {
              "seconds": 1,
              "nanos": 1
            }
          ]
        }
      }
    }
  ]
}

Get segment by timestamp#

POST /video/v1/videos/{videoRid}/get-segment-by-timestamp

Deprecated: Replaced by VideoService#getSegmentByTimestampV2, which addresses the video channel series (channel + tags) instead of a Video rid.

Returns metadata for the segment within a video containing the requested absolute timestamp.

Path parameters

videoRid string (RID) required

​

Body

timestamp Timestamp required

​

Fields of Timestamp
seconds integer (int64) required

​

nanos integer (int64) required

​

viewRangeStart Timestamp

The start of the view range used to dynamically calculate media timestamps. The first segment with an overlap with the time bounds will have its minimum media timestamp set to 0, with every subsequent segment building media time cumulatively from that offset. This will determine the starting media timestamp of the returned segment. The view range should be the same as the one requested to get the playlist and segment summaries.

Response

rid string (RID)

​

videoRid string (RID)

​

dataHandle Handle

​

Set type to "s3".

s3 string

​

frameRate number

The average frame rate (FPS) of the segment calculated as total frames / duration in seconds.

durationSeconds number

The duration of a segment in media time.

timestamps SegmentTimestamps

for videos with frame-level timestamps, we provide mappings, otherwise we just include a single list of timestamps.

Set type to "timestampMappings".

timestampMappings TimestampMappings

​

Fields of TimestampMappings
mediaTimestamps array of number

​

absoluteTimestamps array of Timestamp

​

Fields of Timestamp
seconds integer (int64)

​

nanos integer (int64)

​

When there is nothing to return, the response is HTTP 204 with no body.

Request

curl -X POST "https://api.gov.nominal.io/api/video/v1/videos/<video rid>/get-segment-by-timestamp" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "timestamp": {
    "seconds": 1,
    "nanos": 1
  }
}'

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/video/v1/videos/<video rid>/get-segment-by-timestamp",
    headers={"Authorization": "Bearer <api key>"},
    json={"timestamp": {"seconds": 1, "nanos": 1}},
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/video/v1/videos/<video rid>/get-segment-by-timestamp",
    headers={"Authorization": "Bearer <api key>"},
    json={"timestamp": {"seconds": 1, "nanos": 1}},
)
response.raise_for_status()
print(response.json())

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/video/v1/videos/<video rid>/get-segment-by-timestamp",
            headers={"Authorization": "Bearer <api key>"},
            json={"timestamp": {"seconds": 1, "nanos": 1}},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "rid": "<segment rid>",
  "videoRid": "<video rid>",
  "dataHandle": {
    "type": "s3",
    "s3": "<s3 path>"
  },
  "frameRate": 1,
  "durationSeconds": 1,
  "timestamps": {
    "type": "timestampMappings",
    "timestampMappings": {
      "mediaTimestamps": [
        1
      ],
      "absoluteTimestamps": [
        {
          "seconds": 1,
          "nanos": 1
        }
      ]
    }
  }
}

Types#

CreateSegment#

dataHandle Handle required

​

frameRate number required

The average frame rate (FPS) of the segment calculated as total frames / duration in seconds.

durationSeconds number required

​

timestamps SegmentTimestamps required

​

segmentEndTimestamp Timestamp required

​

Handle#

Set type to the name of one of the other fields, and set only that field.

s3 string

​

Segment#

rid string (RID) required

​

videoRid string (RID) required

​

dataHandle Handle required

​

frameRate number required

The average frame rate (FPS) of the segment calculated as total frames / duration in seconds.

durationSeconds number required

The duration of a segment in media time.

timestamps SegmentTimestamps required

for videos with frame-level timestamps, we provide mappings, otherwise we just include a single list of timestamps.

SegmentTimestamps#

A video segment will either contain timestamps or timestamp mappings depending on whether it is intended to be frame-mapped. Without a frame-timestamp mapping manifest file, a list of absolute timestamps will be automatically assigned to each segment based on media timestamps.. Otherwise, media timestamps will be extracted and mapped to those in the provided manifest.

Set type to the name of one of the other fields, and set only that field.

timestampMappings TimestampMappings

​

Timestamp#

Deprecated for new APIs. Use google.protobuf.Timestamp for absolute instants in proto APIs.

This legacy nanosecond precision timestamp type is represented by an epoch time in seconds and a nanosecond offset. The nanosecond offset is from the start of the epoch second, so must be less than 1 billion.

seconds integer (int64) required

​

nanos integer (int64) required

​

TimestampMappings#

contains 2 equal-length lists, which contain the video media time and user-provided absolute time for the frame at each index. Enables frame-mapping on the front-end.

mediaTimestamps array of number

​

absoluteTimestamps array of Timestamp

​

Page design based on Scalar, MIT License.