| name | otio-convert |
| description | Convert and manipulate editorial timelines with OpenTimelineIO (OTIO) CLIs: otioconvert (format-to-format: EDL/FCP7-XML/FCPXML/AAF/OTIO-JSON), otiocat (concatenate/print), otiostat (timeline statistics), otiotool (filter/edit/rebuild timelines), otiopluginfo (list installed adapters), otioview (Qt viewer). Round-trip between Premiere Pro, Final Cut Pro 7/X, Avid Media Composer, DaVinci Resolve, GStreamer Editing Services. Use when the user asks to convert a Final Cut XML to Premiere, read an AAF, author an EDL, translate between NLE formats, filter an OTIO timeline programmatically, extract timeline stats, or view a timeline.
|
| argument-hint | [src] [dst] |
OTIO Convert
Context: $ARGUMENTS
Quick start
- Convert between NLE formats: → Step 2 (
otio.py convert)
- Print / concat OTIO files: → Step 3 (
otio.py cat)
- Timeline stats (track count, duration, clip count): → Step 4 (
otio.py stat)
- Filter/edit timeline programmatically: → Step 5 (
otio.py tool)
- List installed adapters / plugins: → Step 6 (
otio.py plugins)
- View a timeline in Qt viewer: → Step 7 (
otio.py view)
When to use
- User has an NLE file (EDL, FCP7 XML, FCPXML, AAF, ALE, XGES) and needs another format.
- User wants to inspect/stat/cat OTIO timelines from the shell.
- User wants to filter or transform a timeline (drop a track, trim a range, rebuild).
- User wants to know what adapters are installed.
- For deeper Python API details or class references, use
otio-docs instead.
Step 1 — Install the CLIs
OTIO is a pip package. Install core + every community adapter:
pip install OpenTimelineIO-Plugins
This gives you on PATH: otioconvert, otiocat, otiostat, otiotool, otiopluginfo, otioview (Qt; needs PyQt/PySide installed separately — pip install PyOpenTimelineIO[view]).
Verify install:
uv run ${CLAUDE_SKILL_DIR}/scripts/otio.py plugins
Step 2 — Convert formats
uv run ${CLAUDE_SKILL_DIR}/scripts/otio.py convert \
--input edit.fcpxml --output edit.otio
Format is auto-detected from the file extension. Shortcut aliases for common source→destination pairs:
| Alias | Source → Dest |
|---|
fcp7-to-fcpx | .xml (FCP7) → .fcpxml |
fcpx-to-fcp7 | .fcpxml → .xml |
edl-to-otio | .edl → .otio |
otio-to-edl | .otio → .edl |
aaf-to-otio | .aaf → .otio |
uv run ${CLAUDE_SKILL_DIR}/scripts/otio.py convert \
--input cut.edl --output cut.otio --preset edl-to-otio
The wrapper prints the real otioconvert command to stderr before running it; --dry-run echoes without executing.
Step 3 — Cat / print timelines
uv run ${CLAUDE_SKILL_DIR}/scripts/otio.py cat --input edit.otio
uv run ${CLAUDE_SKILL_DIR}/scripts/otio.py cat --input a.otio --input b.otio --output combined.otio
Pass-through for otiocat: multiple --input = concatenate in order.
Step 4 — Stats
uv run ${CLAUDE_SKILL_DIR}/scripts/otio.py stat --input edit.otio
Prints track count, clip count, total duration, start/end time ranges — matches otiostat output.
Step 5 — Transform with otiotool
otiotool is the surgical-edit multi-tool. The wrapper passes args through:
uv run ${CLAUDE_SKILL_DIR}/scripts/otio.py tool \
--input edit.otio --output flat.otio \
-- --flatten video --remove-transitions
Everything after -- is forwarded verbatim to otiotool. Common flags:
| otiotool flag | Effect |
|---|
--flatten video | collapse video tracks into one |
--flatten audio | collapse audio tracks into one |
--remove-transitions | drop all Transition objects |
--trim START END | crop global timeline range |
--copy-media-refs-from FILE | borrow media references from another OTIO |
--redact | strip clip names (useful for sharing timelines) |
Consult otiotool --help for the full list.
Step 6 — Plugin info
uv run ${CLAUDE_SKILL_DIR}/scripts/otio.py plugins
Enumerates: adapters, media linkers, schemadefs, hooks. Use to confirm an adapter (e.g. aaf_adapter, fcpx_xml) is installed before attempting conversion.
Step 7 — View
uv run ${CLAUDE_SKILL_DIR}/scripts/otio.py view --input edit.otio
Launches otioview Qt GUI (macOS/Windows/Linux with Qt). Needs PyOpenTimelineIO[view] installed.
Gotchas
OpenTimelineIO-Plugins is the right install for NLE round-trips. Just pip install opentimelineio gives you ONLY native otio_json / otiod / otioz adapters — no EDL, no FCP7 XML, no AAF.- AAF adapter needs
pyaaf2. On some systems pip install pyaaf2 has native-build hurdles. Try conda-forge: conda install -c conda-forge pyaaf2.
- Extension → adapter mapping is strict.
.edl → cmx_3600, .xml → fcp_xml (NOT FCPXML), .fcpxml → fcpx_xml, .aaf → aaf_adapter, .otio/.otiod/.otioz → native. Passing a FCPX .fcpxml file with .xml extension will misroute to FCP7 adapter.
- Round-trips lose data. EDL has no effects, no audio metadata, no generators. FCP7↔FCPX drops clip IDs. AAF↔OTIO drops some effect parameter keyframes.
.otio is the only lossless canonical format — hop through it.
otioconvert --input-adapter and --output-adapter override extension detection when the filename doesn't match (e.g. EDL with .txt extension): otioconvert -i cut.txt --input-adapter cmx_3600 -o cut.otio.otiotool is NOT a round-trip tool; it's an in-place transform. It reads OTIO, applies transforms, writes OTIO. To transform an EDL → trimmed EDL, convert EDL→OTIO, run otiotool, convert OTIO→EDL.- Track kind is case-sensitive:
"Video" / "Audio". otiotool --flatten video is lowercase arg, but the internal track.kind string is "Video". Don't mix up.
otioview needs Qt. Headless boxes (CI, SSH) can't run it. Use otiostat + otiocat for text-only inspection.- RationalTime is rate-aware.
otiostat prints durations as value@rate pairs. A 24fps timeline of 10 seconds shows 240@24, NOT . Don't interpret as seconds — divide by rate.
Examples
Example 1 — FCPXML from Final Cut Pro → Premiere-compatible FCP7 XML
uv run ${CLAUDE_SKILL_DIR}/scripts/otio.py convert \
--input cut.fcpxml --output cut.xml --preset fcpx-to-fcp7
Premiere imports both, but FCP7 XML is the stable round-trip.
Example 2 — EDL → OTIO → quick stats
uv run ${CLAUDE_SKILL_DIR}/scripts/otio.py convert --input cut.edl --output cut.otio
uv run ${CLAUDE_SKILL_DIR}/scripts/otio.py stat --input cut.otio
Example 3 — Flatten all video tracks into one
uv run ${CLAUDE_SKILL_DIR}/scripts/otio.py convert --input edit.fcpxml --output edit.otio
uv run ${CLAUDE_SKILL_DIR}/scripts/otio.py tool \
--input edit.otio --output flat.otio -- --flatten video
Example 4 — Concat two cuts into one timeline
uv run ${CLAUDE_SKILL_DIR}/scripts/otio.py cat \
--input scene1.otio --input scene2.otio --output reel.otio
Example 5 — Check AAF adapter is installed
uv run ${CLAUDE_SKILL_DIR}/scripts/otio.py plugins | grep aaf
Troubleshooting
No adapter available for file 'foo.aaf'
Cause: aaf_adapter not installed (or pyaaf2 broken).
Solution: pip install OpenTimelineIO-Plugins (gets everything). If AAF still fails: pip install pyaaf2 first.
otioview: command not found
Cause: Qt/viewer extras not installed.
Solution: pip install 'PyOpenTimelineIO[view]' or install PyQt5/PySide2 manually.
EDL round-trip loses frame rates
Cause: EDL headers don't carry rate; cmx_3600 adapter defaults to 24fps.
Solution: Pass --rate 29.97 (or whatever) to otioconvert via otio.py convert ... -- --rate 29.97, or include a leader with rate in the EDL header.
Extension mismatch — .xml file treated as FCP7 but is actually FCPX
Solution: Pass explicit adapter: otioconvert -i weird.xml --input-adapter fcpx_xml -o out.otio. Or rename file to .fcpxml first.
Wrapper prints otioconvert: command not found
Solution: Install OTIO: pip install OpenTimelineIO-Plugins. Make sure the venv is active (which otioconvert).
Reference docs
- Full adapter matrix (round-trip fidelity) + install notes → see the
otio-docs skill's references/adapters.md.
otiotool transform catalog → references/otiotool.md in this skill.
