Otio Docs

OTIO Docs

Context: $ARGUMENTS

Quick start

• Find an OTIO class / function / adapter: → Step 2 (search --query <term>)
• Read the full API section: → Step 3 (section --page <page> --id <anchor>)
• Grab a whole tutorial / API page: → Step 4 (fetch --page <name>)
• Prime cache for offline use: → Step 5 (index)

When to use

• User asks "what does otio.schema.Clip take?" or "how do I subclass Track?"
• Need to confirm an adapter exists (EDL, FCP7-XML, FCPXML, AAF, ALE, XGES, SVG) before recommending.
• Need the otioconvert / otiotool / otiostat CLI surface (CLIs are documented via --help, not readthedocs — this skill pulls the tutorials + Python-API pages instead).
• Need to cite the canonical readthedocs URL or GitHub source of truth.
• Before writing OTIO Python code: verify API surface (classes, methods, serialization fields).

Step 1 — Know the page catalog

uv run ${CLAUDE_SKILL_DIR}/scripts/otiodocs.py list-pages

Common picks:

Read references/adapters.md for the full adapter matrix + references/pages.md for the URL catalog.

Step 2 — Search first

uv run ${CLAUDE_SKILL_DIR}/scripts/otiodocs.py search --query "RationalTime" --limit 5

Scoped to one page:

uv run ${CLAUDE_SKILL_DIR}/scripts/otiodocs.py search --query "fcpx_xml" --page tut-adapters

Use --format json for machine-parseable output.

First run downloads; subsequent hit ~/.cache/otio-docs/.

Step 3 — Read one section in full

uv run ${CLAUDE_SKILL_DIR}/scripts/otiodocs.py section --page api-schema --id opentimelineio.schema.Clip

--id accepts a Sphinx anchor id OR a heading keyword fallback.

Step 4 — Fetch a whole page

uv run ${CLAUDE_SKILL_DIR}/scripts/otiodocs.py fetch --page tut-adapters

Pair with --format json for structured output.

Step 5 — Prime the cache

uv run ${CLAUDE_SKILL_DIR}/scripts/otiodocs.py index

Fetches every known page into ~/.cache/otio-docs/. Override with OTIO_DOCS_CACHE=/path.

Clear: uv run ${CLAUDE_SKILL_DIR}/scripts/otiodocs.py clear-cache.

Gotchas

• Canonical repo moved from PixarAnimationStudios to AcademySoftwareFoundation. The GitHub URL github.com/AcademySoftwareFoundation/OpenTimelineIO is the source of truth — OTIO is now an ASWF project. Old PixarAnimationStudios/OpenTimelineIO URLs redirect but are stale; don't cache/cite them.
• CLIs do NOT have readthedocs pages. otioconvert --help, otiocat --help, otiostat --help, otiotool --help, and otiopluginfo --help are the authoritative CLI reference. This skill pulls the Python tutorials + API docs that ground the CLI behavior; for CLI flags run the tools with --help.
• Native vs community adapters:
  • Native (shipped with opentimelineio core pip package): otio_json (.otio), otiod (directory form), otioz (zipped form with media).
  • Community (installed via pip install OpenTimelineIO-Plugins meta-package): cmx_3600 (EDL), fcp_xml (FCP7/Premiere XML), fcpx_xml (FCPXML), aaf_adapter (Avid), ale (Avid Log Exchange), burnins (render timecode burn-in), maya_sequencer, xges (GStreamer Editing Services), svg (render timeline to SVG).
  • Installing OpenTimelineIO-Plugins auto-installs opentimelineio core. Don't pip-install opentimelineio and then expect AAF/EDL/FCPXML to work — you need the meta-package.
• RationalTime is rate-aware, not just a float. RationalTime(value=24, rate=24.0) = 1 second. Do NOT convert to seconds prematurely — do all arithmetic in the native rate to avoid rounding drift. Use rescaled_to(new_rate) when changing.
• TimeRange uses start + duration, NOT start + end. end_time_exclusive() and end_time_inclusive() compute end on demand. Mixing these up off-by-ones every timeline.
• Track kind is case-sensitive: "Video" or "Audio". Not "video" / "audio". Lowercase is a common source of "no clips found" bugs.
• Clip.media_reference can be MissingReference — not None. Check isinstance(clip.media_reference, opentimelineio.schema.MissingReference) before treating as loaded.
• Sphinx anchors for Python API use moduleName.ClassName form (dotted path). Not the mangled C++ form you'd see in C++ Doxygen.
• AAF adapter requires pyaaf2 (a non-PyPI-resolved dep on some systems). If pip install OpenTimelineIO-Plugins fails on AAF only, install pyaaf2 first.
• Round-trips lose data. FCP7-XML → OTIO → FCPXML preserves structure, NOT every effect/generator. Adapter docs enumerate exactly what round-trips cleanly.
• .otio is the canonical lossless format. When in doubt, convert to .otio first; all other adapters lose detail.
• Cache is per-page only, not per-OTIO-version. After a new OTIO release, clear-cache then index.
• The script is stdlib-only. No pip dependencies.

Examples

Example 1 — "What does opentimelineio.schema.Clip take?"

uv run ${CLAUDE_SKILL_DIR}/scripts/otiodocs.py search --query "class Clip" --page api-schema --limit 3
uv run ${CLAUDE_SKILL_DIR}/scripts/otiodocs.py section --page api-schema --id opentimelineio.schema.Clip

Example 2 — "Is there an AAF adapter?"

uv run ${CLAUDE_SKILL_DIR}/scripts/otiodocs.py search --query "AAF" --page tut-adapters --limit 5

Example 3 — "How do RationalTime arithmetic and rate conversion work?"

uv run ${CLAUDE_SKILL_DIR}/scripts/otiodocs.py fetch --page tut-time-ranges

Example 4 — "How do I write a custom schema plugin?"

uv run ${CLAUDE_SKILL_DIR}/scripts/otiodocs.py fetch --page tut-schemadef

Example 5 — "Where do OTIO algorithms like track_trimmed_to_range live?"

uv run ${CLAUDE_SKILL_DIR}/scripts/otiodocs.py search --query "track_trimmed" --page api-algorithms

Troubleshooting

Error: unknown page: foo

Cause: Not in the catalog. Solution: Run list-pages — common mistakes: schema instead of api-schema; adapters instead of tut-adapters.

Error: urlopen error [SSL: CERTIFICATE_VERIFY_FAILED]

Cause: macOS Python without certs. Solution: /Applications/Python\ 3.x/Install\ Certificates.command or set SSL_CERT_FILE.

Search returns zero hits for a class name

Cause: Class is in a different module than expected — e.g. Clip is in schema, RationalTime is in opentime, track_trimmed_to_range is in algorithms. Solution: Drop --page to search all pages.

Cache stale after OTIO release

Solution: clear-cache then index.

Reference docs

• Adapter matrix (native vs community, round-trip fidelity, install steps) → references/adapters.md
• URL catalog + page descriptions → references/pages.md