Project context and export

Types

ProjectCaptionRef

interface ProjectCaptionRef {
  trackId: string
  trackName: string
  trackIndex: number
  caption: CaptionElement
}

A caption element together with the id, name, and index of its track.

ProjectMediaAssetContext

interface ProjectMediaAssetContext
  extends Omit<AssetRef, 'src'> {
  usedBy: string[]
}

An asset without its src plus the ids of the elements that use it.

ProjectMediaContext

interface ProjectMediaContext {
  project: {
    id: string
    name: string
    width: number
    height: number
    fps: number
    durationMs: number
    trackCount: number
    assetCount: number
    markerCount: number
  }
  playback?: PlaybackState
  selection: { elementIds: string[] }
  assets: ProjectMediaAssetContext[]
  tracks: ProjectMediaTrackContext[]
  markers: Marker[]
  transcript: {
    hasTranscript: boolean
    captionCount: number
    wordCount: number
    startMs?: number
    endMs?: number
    vocabulary: string[]
  }
}

A structured view of the whole project, summary fields, optional playback, selection, assets with usage, tracks with elements, markers, and transcript counts with the project vocabulary.

ProjectMediaElementContext

interface ProjectMediaElementContext {
  id: string
  type: TimelineElement['type']
  trackId: string
  trackName: string
  trackIndex: number
  startMs: number
  endMs: number
  durationMs: number
  selected: boolean
  active?: boolean
  linkId?: string
  asset?: {
    id: string
    kind?: AssetRef['kind']
    name?: string
    durationMs?: number
    width?: number
    height?: number
    mimeType?: string
    nativePreview?: boolean
  }
  source?: {
    startMs: number
    endMs: number
    durationMs: number
    averageSpeed: number
    hasTimeMap: boolean
    reversed: boolean
  }
  text?: string
  caption?: {
    hasWordTimings: boolean
    wordCount: number
  }
  multicam?: {
    audioSource?: string
    angleCount: number
    sources: Array<{
      key: string
      assetId: string
      assetName?: string
      offsetMs: number
    }>
  }
  effects?: string[]
  blendMode?: string
  transition?: {
    type: string
    durationMs: number
  }
}

One element in context form, its placement, selection and active state, and the asset, source, text, caption, multicam, effect, blend, and transition details that apply to its type. Every media clip, a multicam included, reports its source window in source. A multicam adds its source offsets and angleCount, the number of angle spans its window plays.

ProjectMediaTrackContext

interface ProjectMediaTrackContext {
  id: string
  name: string
  index: number
  muted: boolean
  hidden: boolean
  locked: boolean
  magnetic: boolean
  elements: ProjectMediaElementContext[]
}

A track's id, name, index, and flags together with its elements in context form.

ProjectTranscriptCaptionContext

interface ProjectTranscriptCaptionContext {
  id: string
  trackId: string
  trackName: string
  startMs: number
  endMs: number
  durationMs: number
  text: string
  hasWordTimings: boolean
  wordCount: number
  words?: ProjectTranscriptWordContext[]
}

One caption in transcript form, its track, absolute times, text, word count, and optionally its words.

ProjectTranscriptContext

interface ProjectTranscriptContext {
  hasTranscript: boolean
  captionCount: number
  wordCount: number
  text: string
  captions: ProjectTranscriptCaptionContext[]
}

The project's captions read as a transcript, with counts, the joined text, and the captions in time order.

ProjectTranscriptOptions

interface ProjectTranscriptOptions {
  includeWords?: boolean
}

Options for getProjectTranscript, whether to include per-word timings.

ProjectTranscriptWordContext

interface ProjectTranscriptWordContext {
  text: string
  startMs: number
  endMs: number
}

One transcript word with absolute start and end times.

ProjectViewContextOptions

interface ProjectViewContextOptions {
  playback?: PlaybackState
  selection?: { elementIds: readonly string[] }
}

Options for getProjectMediaContext, the playback state and selection to fold into the view.

OtioExportOptions

interface OtioExportOptions {
  fps?: number
}

Options for OpenTimelineIO export, a frame rate for the global start time that defaults to the project fps.

Functions

summarizeProject

function summarizeProject(project: Project): string

Returns a deterministic text rendering of the project, one header line then each track from the top down with its elements, keyframes, effects, blend modes, transitions, and fades. A Layouts block names each layout's role and gives every slot's role, pixel size, and aspect.

describeLayoutChange

function describeLayoutChange(before: Project, after: Project, layoutId: Layout['id']): string[]

Returns lines that compare one layout across two projects, each slot's pixel size and aspect before and after with the width and height change in percent, then each change to the slot's fit and frame style field by field, such as corner radius 0.12 → 0, shadow removed, or stroke added (2 px #ffffff). It adds a warning when an overlay slot moves to another corner, pointing at resizeLayoutSlot for a resize in place, when an overlay slot loses its corner radius or its shadow, giving the slot to save to restore it, and when a single-slot layout that covered the frame stops covering it. Returns an empty array when after has no layout with that id.

getProjectCaptions

function getProjectCaptions(project: Project): ProjectCaptionRef[]

Returns every caption element with its track, sorted by start time, then track index, then id.

getProjectMediaContext

function getProjectMediaContext(
  project: Project,
  options: ProjectViewContextOptions = {},
): ProjectMediaContext

Returns the full project view for agents, with assets sorted by id and stripped of src, every element in context form, and the selection and playback state when given.

getProjectTranscript

function getProjectTranscript(
  project: Project,
  options: ProjectTranscriptOptions = {},
): ProjectTranscriptContext

Returns the project's captions as a transcript with absolute times and the joined text, including per-word timings when includeWords is set.

toOtio

function toOtio(project: Project, options: OtioExportOptions = {}): OtioValue

Returns the project as an OpenTimelineIO document object with one stack of tracks, markers on the stack, and project metadata under metadata.mcut.

toOtioJson

function toOtioJson(project: Project, options: OtioExportOptions = {}): string

Returns the project serialized as the contents of a .otio file.

Project context and export

On this page