otio-docs

name	otio-docs
description	Search and fetch official OpenTimelineIO (OTIO) docs from opentimelineio.readthedocs.io and github.com/AcademySoftwareFoundation/OpenTimelineIO: timeline primitives (RationalTime, TimeRange, TimeTransform), containers (Timeline/Stack/Track), content (Clip/Gap/Transition), MediaReferences, tutorials (quickstart, timeline-structure, time-ranges, write-a-schemadef-plugin, adapters), Python API (schema/core/opentime/algorithms/media_linker/hooks), adapter catalog (otio_json, otiod, otioz native; cmx_3600 EDL, fcp_xml, fcpx_xml, aaf_adapter, ale, burnins, maya_sequencer, xges, svg via OpenTimelineIO-Plugins). Use when the user asks to look up an OTIO class, find an adapter for a NLE format, verify Python bindings, or read OpenTimelineIO docs.
argument-hint	[query]

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:

Question	Page
"How do I read/write OTIO from Python?"	tut-quickstart
"What's Stack vs Track vs Timeline?"	tut-timeline-structure
"How do RationalTime and TimeRange work?"	tut-time-ranges
"Which adapters ship natively vs via OpenTimelineIO-Plugins?"	tut-adapters
"How do I author a custom schema?"	tut-schemadef
"Python API reference root"	api-py-root
"opentime module (RationalTime/TimeRange)"	api-opentime
"core module (SerializableObject, SerializableCollection)"	api-core
"schema module (Timeline/Clip/Gap/Track/Stack)"	api-schema
"algorithms module (stack_algo, track_algo, timeline_postprocess)"	api-algorithms
"media_linker module"	api-media-linker
"hooks module"	api-hooks
"README / repo root"	github-readme
"OpenTimelineIO-Plugins meta-package (community adapters)"	plugins-readme

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 / . Lowercase is a common source of "no clips found" bugs.

---

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