OTIO Format

OTIO Output

OTIO timeline data is generated automatically for highlights and is available through the otio_edit field on each highlight. You do not need to pass an OTIO yes/no flag when creating or assigning a task. We emit standard OpenTimelineIO schemas:

Timeline.1
Track.1
Clip.2
ExternalReference.1
RationalTime.1
TimeRange.1

Example Timeline

A single-clip highlight timeline:

{
  "OTIO_SCHEMA": "Timeline.1",
  "name": "event_000_goal",
  "tracks": {
    "OTIO_SCHEMA": "Stack.1",
    "children": [
      {
        "OTIO_SCHEMA": "Track.1",
        "name": "V1",
        "kind": "Video",
        "children": [
          {
            "OTIO_SCHEMA": "Clip.2",
            "name": "event_000_goal",
            "active_media_reference_key": "DEFAULT_MEDIA",
            "media_references": {
              "DEFAULT_MEDIA": {
                "OTIO_SCHEMA": "ExternalReference.1",
                "target_url": "s3://bucket/path/media.mxf",
                "name": ""
              }
            },
            "source_range": {
              "OTIO_SCHEMA": "TimeRange.1",
              "start_time": {
                "OTIO_SCHEMA": "RationalTime.1",
                "rate": 30.0,
                "value": 37080.0
              },
              "duration": {
                "OTIO_SCHEMA": "RationalTime.1",
                "rate": 30.0,
                "value": 900.0
              }
            }
          }
        ]
      }
    ]
  }
}

Multi-clip timelines follow the same structure with additional Clip.2 objects on the track. Each clip represents a contiguous segment of source media — gaps between clips are dead time that is cut out.

Package and Recap EDLs

Highlight packages and recaps return a merged OTIO Timeline.1 in otio_timeline. This package-level EDL is composed from the selected highlights’ stored otio_edit payloads. Each package clip preserves the selected highlight’s media reference and source range, and adds provenance in clip metadata:

Metadata Field	Description
`edit_id`	Source highlight ID. This matches an ID in `selected_edit_ids`.
`project_id`	Source project/game ID.
`event_type`	Source highlight event type.
`event_description`	Source highlight description when available.
`package_id`	Highlight package or recap ID.
`package_sequence_index`	Position of the selected highlight in the package.
`package_window_index`	Window index when a selected highlight contributes multiple ranges.

Source highlights have otio_edit generated automatically for package and recap EDL generation. Package and recap creation requires every matched source highlight to have otio_edit; the API does not build package EDLs from rendered clips or editor-project JSON.

Time Mapping

OTIO start values are stream-relative, then shifted by source_start_offset. Use:

event_stream_frames = event_stream_time_seconds * framerate
otio_start_frame = source_start_offset + event_stream_frames

Where:

source_start_offset is optional and defaults to 0
event_stream_time_seconds is measured from stream start

srt_zero_relative_smpte_timecode is used to interpret ingest timing and align stream clocking, but it is not automatically added as an additional OTIO frame offset. If you need OTIO values in a house timeline (for example, start at 01:00:00:00), convert that timecode to frames at the task framerate and include it in source_start_offset.

Drop-Frame Rules

Drop-frame timecode (HH:MM:SS;FF) is only valid for 29.97 or 59.94.

Configuring OTIO Output

OTIO edit generation is automatic. The optional otio object on Create Task or Assign Task is only for overriding media-reference metadata or timeline offsets:

Field	Type	Required	Description
`target_url`	string	No	Optional media URI override referenced in the OTIO `ExternalReference.target_url` (e.g., an S3 path or asset ID). If omitted, Narrative uses its generated source/archive reference.
`source_start_offset`	integer	No	Frame offset for the source start position. This is the Value field of an OTIO `RationalTime`. Since the `framerate` is already specified at the top level, only the integer frame count is needed. Defaults to `0`.
`metadata`	object	No	Free-form metadata attached verbatim to every OTIO `ExternalReference.metadata` produced for this task. Useful for stashing house asset IDs, color-space hints, workflow tags, or anything OTIO-aware downstream tools need to read off the source media.

Omit otio when you do not need custom OTIO metadata or offsets. OTIO edit data will still be generated. The framerate at the top level of the request (ffprobe rational format, e.g., "30000/1001") is used both for interpreting the SMPTE timecode during SRT ingest and as the rate for all OTIO RationalTime values. If omitted, the framerate is inferred from the stream, but this can be inconsistent with VFR encoding. srt_zero_relative_smpte_timecode does not replace source_start_offset; they serve different purposes:

srt_zero_relative_smpte_timecode: stream ingest clock interpretation
source_start_offset: explicit OTIO frame offset applied to output start_time.value

Example:

{
  "sport": "soccer",
  "srt_zero_relative_smpte_timecode": "01:00:00:00",
  "framerate": "30000/1001",
  "otio": {
    "target_url": "s3://bucket/path/media.mxf",
    "source_start_offset": 0,
    "metadata": {"house_asset_id": "abc-123"}
  }
}

Deprecated: `webhook_schema` + `wh_schema_config`

Earlier versions of the API gated OTIO output through a two-field pair:

{
  "webhook_schema": "otio",
  "wh_schema_config": {
    "target_url": "s3://bucket/path/media.mxf",
    "source_start_offset": 0
  }
}

Both fields are still accepted for backward compatibility but should not be used in new integrations. OTIO edit generation no longer needs a toggle; use the top-level otio object only when you need metadata or timing overrides.

Portrait Crop (`Narrative_SmartCrop` Effect)

Portrait crop data is encoded as a standard OTIO effect attached to each clip in the timeline. This uses the effects array on Clip.2 to define a dynamic 9:16 crop recipe with animated control points. Each clip gets its own independent Narrative_SmartCrop effect. Control point times are relative to the clip (starting at 0, up to the clip’s duration).

Example

The same timeline from above, extended with a portrait crop effect:

{
  "OTIO_SCHEMA": "Timeline.1",
  "name": "event_000_goal",
  "tracks": {
    "OTIO_SCHEMA": "Stack.1",
    "children": [
      {
        "OTIO_SCHEMA": "Track.1",
        "name": "V1",
        "kind": "Video",
        "children": [
          {
            "OTIO_SCHEMA": "Clip.2",
            "name": "event_000_goal",
            "active_media_reference_key": "DEFAULT_MEDIA",
            "media_references": {
              "DEFAULT_MEDIA": {
                "OTIO_SCHEMA": "ExternalReference.1",
                "target_url": "s3://bucket/path/media.mxf",
                "name": ""
              }
            },
            "source_range": {
              "OTIO_SCHEMA": "TimeRange.1",
              "start_time": {
                "OTIO_SCHEMA": "RationalTime.1",
                "rate": 30.0,
                "value": 37080.0
              },
              "duration": {
                "OTIO_SCHEMA": "RationalTime.1",
                "rate": 30.0,
                "value": 900.0
              }
            },
            "effects": [
              {
                "OTIO_SCHEMA": "Effect.1",
                "effect_name": "Narrative_SmartCrop",
                "name": "9:16 Portrait Automation",
                "metadata": {
                  "formatting": {
                    "target_aspect": "9:16",
                    "coordinate_system": "normalized_0_to_1",
                    "origin": "top_left"
                  },
                  "interpolation": "linear",
                  "control_points": [
                    {
                      "time": {
                        "OTIO_SCHEMA": "RationalTime.1",
                        "rate": 30.0,
                        "value": 0.0
                      },
                      "center_x": 0.5
                    },
                    {
                      "time": {
                        "OTIO_SCHEMA": "RationalTime.1",
                        "rate": 30.0,
                        "value": 450.0
                      },
                      "center_x": 0.75
                    },
                    {
                      "time": {
                        "OTIO_SCHEMA": "RationalTime.1",
                        "rate": 30.0,
                        "value": 900.0
                      },
                      "center_x": 0.3
                    }
                  ]
                }
              }
            ]
          }
        ]
      }
    ]
  }
}

Effect Schema

Field	Type	Description
`OTIO_SCHEMA`	string	Always `"Effect.1"`
`effect_name`	string	Always `"Narrative_SmartCrop"`
`name`	string	Human-readable label (e.g. `"9:16 Portrait Automation"`)
`metadata`	object	Crop definition (see below)

`metadata` Fields

Field	Type	Description
`formatting`	object	Defines the target crop format
`interpolation`	string	Always `"linear"` — smooth movement between control points
`control_points`	array	Animated positions defining the crop path

`formatting` Fields

Field	Type	Description
`target_aspect`	string	Target aspect ratio (`"9:16"`)
`coordinate_system`	string	Always `"normalized_0_to_1"` — works on any resolution
`origin`	string	Coordinate origin (`"top_left"`)

`control_points[]` Fields

Field	Type	Description
`time`	RationalTime	Position in the clip’s local timeline (starts at `0`)
`center_x`	float	Horizontal center of the crop window, normalized 0–1 (0 = left edge, 1 = right edge)

Interpolate linearly between control points to produce a smooth camera pan.

Converting `center_x` to Pixels

To compute the crop window’s left edge in pixels at a given center_x:

crop_width  = frame_height * 9 / 16
crop_left_px = clamp(
  center_x * frame_width - crop_width / 2,
  0,
  frame_width - crop_width
)

Introduction

Concepts

OTIO Output

Example Timeline

Package and Recap EDLs

Time Mapping

Drop-Frame Rules

Configuring OTIO Output

Deprecated: `webhook_schema` + `wh_schema_config`

Portrait Crop (`Narrative_SmartCrop` Effect)

Example

Effect Schema

`metadata` Fields

`formatting` Fields

`control_points[]` Fields

Converting `center_x` to Pixels

​OTIO Output

​Example Timeline

​Package and Recap EDLs

​Time Mapping

​Drop-Frame Rules

​Configuring OTIO Output

​Deprecated: webhook_schema + wh_schema_config

​Portrait Crop (Narrative_SmartCrop Effect)

​Example

​Effect Schema

​metadata Fields

​formatting Fields

​control_points[] Fields

​Converting center_x to Pixels

OTIO Output

Example Timeline

Package and Recap EDLs

Time Mapping

Drop-Frame Rules

Configuring OTIO Output

Deprecated: `webhook_schema` + `wh_schema_config`

Portrait Crop (`Narrative_SmartCrop` Effect)

Example

Effect Schema

`metadata` Fields

`formatting` Fields

`control_points[]` Fields

Converting `center_x` to Pixels