generateOpenTimelineComposition()v4.0.542
Converts an OpenTimelineIO (.otio) timeline into editable Remotion TSX. Each clip becomes a separate JSX node with its own timing. To also register the component in a project, use addOpenTimelineComposition().
Draft API: This API is experimental and may change.
import-timeline.tsconstresult =generateOpenTimelineComposition ({timeline :otioJson ,componentName : 'ImportedTimeline',fps : 30,width : 1920,height : 1080, }); if (result .source !== null) {console .log (result .source ,result .metadata ); } else {console .error (result .diagnostics ); }
The function is synchronous and does not read files, fetch URLs, probe media, or install packages. The generated component uses remotion and, when needed, @remotion/media. Keep these packages at the same version as @remotion/codemods.
Options
timeline
An OTIO JSON string or parsed object with a Timeline.1 root. Convert other interchange formats, such as AAF, EDL, FCPXML, .otioz, or .otiod, to OTIO JSON first.
componentName
The generated named export. Must begin with an uppercase ASCII letter and contain only letters, digits, underscores, or dollar signs.
fps
The composition frame rate, as a positive finite number. Source timing is converted to this rate. Individual clip boundaries retain fractional frames; the composition duration is rounded up to a whole frame.
width
The composition width, as a positive safe integer in pixels.
height
The composition height, as a positive safe integer in pixels. Width, height, and frame rate must be supplied because OTIO does not define the output composition settings.
resolveMedia?
A synchronous function that maps media references to browser-accessible assets. By default, supported remote URLs are used directly and public-relative paths use staticFile(). Absolute paths and file: URLs require a resolver. Assets are not copied or downloaded.
resolve-media.tsconstresult =generateOpenTimelineComposition ({timeline :otioJson ,componentName : 'Interview',fps : 30,width : 1920,height : 1080,resolveMedia : ({targetUrl }) => { if (targetUrl === 'file:///edit/interview.mov') { return {src : 'interview.mp4',source : 'public',kind : 'video'}; } return null; }, });
The resolver receives an object with the following fields.
reference
The OTIO media reference as a read-only record, including its schema and metadata.
targetUrl
The reference's URL, or null when absent. For an image sequence, this is its directory base.
path
The path of the source clip in the OTIO input.
trackKind
'Video' or 'Audio'.
Return {src, source, kind}, where source is 'url' or 'public' and kind is 'video', 'audio', or 'image'. Return null to use default resolution. A thrown error becomes an error diagnostic.
For image sequences, src is a directory base; file naming, numbering, rate, and frame step still come from the OTIO reference. Supply converted browser-decodable images under those filenames when necessary.
Return value
source
Generated TSX, or null if an error prevents importing. Unsupported effects are ignored with warnings.
metadata
{width, height, fps, durationInFrames}, or null if the timeline or output settings are invalid. Metadata remains available when media resolution fails. Only register the generated component as a composition when source is not null.
diagnostics
An ordered array of {code, severity, path, message} objects. severity is 'error', 'warning', or 'info'. path identifies the affected part of the input or options. Any error blocks source generation.
assets
An array of resolved {src, source, kind, path} objects. source is 'url' or 'public'; kind is 'video', 'audio', 'image', or 'image-sequence'. path identifies the source clip. Media availability and codec support are not verified.
annotations
An array of {path, metadata, markers} records. metadata is a record or null, and markers is an array of retained OTIO marker objects. These do not become visible overlays or effects.
globalStartTime
The original timeline start timecode as {value, rate}, or null. Composition playback starts at frame zero; no leading gap is inserted for this timecode.
Supported timelines
| Feature | Behavior |
|---|---|
| Tracks, stacks, and nesting | Preserves sequential timing, overlapping layers, and nested source ranges. |
| Clips and gaps | Supports Clip.1, Clip.2, gaps, and legacy sequences/fillers. Disabled items retain their duration. |
| Source trims and mixed frame rates | Preserves source ranges and accounts for media start timecode. |
| Forward clip retiming and freezes | Supports positive LinearTimeWarp.1 and FreezeFrame.1. |
| Other active effects | Ignored with a warning that includes the effect's name when available. |
Internal SMPTE_Dissolve transitions | Generates visual and audio fades between neighboring clips or gaps. |
| Image sequences | Supports browser-decodable images with frame numbering, padding, and frame steps. Missing-frame policy must be error. |
| Metadata, markers, and global start time | Retained in the result without rendered behavior. |
Reverse playback, retimed tracks/stacks, unsupported combinations of time effects, custom transitions, transitions at a track boundary, and transitions adjacent to nested compositions produce errors. Unknown item schemas or versions also produce errors.
Missing media and application-specific generators require resolveMedia. PNG, JPG, JPEG, SVG, and BMP are detected as still images by default. Ambiguous formats such as GIF, WebP, and AVIF require an explicit resolver choice. Convert formats such as EXR, DPX, and TIFF to browser-decodable media first.
Video tracks render visuals with embedded audio muted. Include an audio track to import sound. Images use objectFit="contain"; application-specific crop, scale, color, and effect metadata is not interpreted.
Importing in Studio
See Importing OpenTimelineIO for the workflow in Remotion Studio and remotion.new, media handling, and the CLI alternative.
Compatibility
| Browsers | Servers | Environments | |||||||
|---|---|---|---|---|---|---|---|---|---|
Chrome | Firefox | Safari | Node.js | Bun | Serverless Functions | ||||