# academysoftwarefoundation/opentimelineio architecture

> Architecture diagram of the GitHub repository academysoftwarefoundation/opentimelineio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/academysoftwarefoundation/opentimelineio
- Repository: https://github.com/academysoftwarefoundation/opentimelineio

## Overview

##### Project Type and Purpose
- This is an open-source, dual-language library/toolset rather than a web app:
- Core implemented in C++ for an in-memory timeline data model (“opentime” + “opentimelineio”).
- Official Python bindings (py-opentimelineio) exposing the C++ core idiomatically.
- A plugin system for adapters (file I/O), media linkers, hook scripts, and schema definitions.
- Command-line tools (otiocat, otioconvert, etc.) and a minimal Qt-based viewer (opentimelineview).
- Examples, tests, docs bundled alongside build scripts (CMake, setup.py).

##### File-Structure Highlights
- Top-level tooling & governance: CMakeLists.txt, setup.py/pyproject.toml, Makefile, GitHub workflows.
- src/deps: third-party vendored libs (pybind11, rapidjson, Imath).
- src/opentime: standalone C++ time library (rationalTime, timeRange, timeTransform).
- src/opentimelineio: core C++ data model, algorithms, serialization/deserialization.
- src/py-opentimelineio:
a. CMake subdirs for building Python extension modules (opentime-bindings, otio-bindings).
b. Pure-Python wrapper packages (opentimelineio.adapters, .algorithms, .console, .core, .plugins, .schema).
- src/opentimelineview: PySide viewer widgets and console stub.
- tests: C++ & Python unit tests; baselines for adapter formats.
- examples: minimal C++ & Python usage demos, sample plugins.
- docs/tutorials: architecture, adapters, plugin tutorials on ReadTheDocs.

##### README Insights
- Emphasizes C++ core + Python API + plugin extensibility.
- Plugin points: adapters (I/O), media linkers, hook scripts, schema defs.
- Build/install via CMake/pip.
- Viewer program built on PySide2.

##### Components
a. Core C++ Library (“opentimelineio” + “opentime”)
- No external deps at runtime.
- Provides: SerializableObject, Timeline, Track, Clip, Effect, serialization APIs.
b. Build System
- CMake → produces:
- libopentime.a / .so
- libopentimelineio.a / .so
- Python extension modules (opentime_bindings, otio_bindings)
- setup.py (setuptools) wraps CMake build on pip install.
c. Python Binding Layer
- Extension modules loaded by Python packages under src/py-opentimelineio/opentimelineio.
- Exposes C++ classes/methods to Python.
d. Plugin System
- Entry points defined in plugin_manifest.json files.
- Adapters (read/write formats)
- Media linkers
- Hook scripts
- Schema defs
e. CLI Tools & Viewer
- otiocat, otioconvert, otiopluginfo, etc.
- opentimelineview (Qt widgets)
- Rely on Python API + plugins
f. External Dependencies
- Vendored: pybind11, rapidjson, Imath
- Python: PySide2 (viewer), click/argparse (console), setuptools entry points.
g. Examples & Tests (separate, not in production flow)

##### Relationships & Data Flow
- Developer writes C++ or Python code → links against C++ core or imports Python package.
- CLI tools & viewer import top-level Python package → invoke core functionality.
- Adapters/plugin loading: Python package discovers plugins via entry points → adapter code → calls into core deserialization.
- Core serialization writes .otio; adapters serialize to other formats.
- Build pipeline: source → CMake build → libraries + Python wheels via setup.py → PyPI.

##### Architectural Patterns & Principles
- Layered architecture: Core (C++) → Binding (C++ → Python) → Application (CLI, viewer, plugins).
- Plugin-based extensibility via standardized manifests & entry points.
- Separation of concerns: time library separate from timeline library.
- Vendored dependencies isolate third-party code.
- Single responsibility: each package/subdir has a clear role.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build System
    subgraph "Build System" 
        BuildSystem["CMakeLists.txt / setup.py / pyproject.toml"]:::build
    end

    %% Vendored Dependencies
    subgraph "Vendored Dependencies"
        pybind11["pybind11"]:::cpp
        rapidjson["rapidjson"]:::cpp
        Imath["Imath"]:::cpp
    end

    %% C++ Core
    subgraph "C++ Core" 
        TimeLib["opentime (rationalTime, timeRange, timeTransform)"]:::cpp
        TimelineLib["opentimelineio (composable, clip, timeline, track, serialization, algo)"]:::cpp
    end

    %% Python Extension Modules
    subgraph "Python Extension Modules"
        OpTimeBindings["opentime_bindings"]:::binding
        OtioBindings["otio_bindings"]:::binding
    end

    %% Python Package
    subgraph "Python Package"
        coreWrappers["core wrappers & utils"]:::python
        adapters["adapters (I/O)"]:::plugin
        algorithms["algorithms"]:::python
        consolePkg["console/CLI tools"]:::python
        pluginsPkg["plugin framework"]:::plugin
        schema["schema definitions"]:::plugin
        schemadef["schema codegen"]:::plugin
        hooks["hooks.py"]:::plugin
        mediaLinker["media_linker.py"]:::plugin
    end

    %% CLI & Viewer
    subgraph "Application Layer"
        CLIViewer["CLI Tools & Viewer"]:::app
        Viewer["Qt Viewer"]:::app
    end

    %% Plugin System
    subgraph "Plugin System"
        pluginManifest["manifest.py"]:::plugin
        examplePlugin["sample_plugin/otio_counter"]:::plugin
    end

    %% Examples & Tests
    subgraph "Examples & Tests"
        examples["examples (C++ & Python demos)"]:::grey
        tests["tests (C++ & Python)"]:::grey
    end

    %% Connections
    BuildSystem -->|builds| TimeLib
    BuildSystem -->|builds| TimelineLib
    BuildSystem -->|produces| OpTimeBindings
    BuildSystem -->|produces| OtioBindings

    pybind11 -->|vendored into| TimeLib
    rapidjson -->|vendored into| TimelineLib
    Imath -->|vendored into| TimelineLib

    OpTimeBindings -->|exposes| coreWrappers
    OtioBindings -->|exposes| coreWrappers

    coreWrappers -->|imported by| consolePkg
    coreWrappers -->|imported by| adapters
    coreWrappers -->|imported by| algorithms
    adapters -->|I/O| TimelineLib
    pluginsPkg -->|discovers via entry points| adapters
    pluginsPkg -->|discovers via entry points| mediaLinker
    pluginsPkg -->|discovers via entry points| hooks
    pluginsPkg -->|discovers via entry points| schema
    schemadef -->|generates| schema

    consolePkg -->|runs| CLIViewer
    CLIViewer -->|uses| coreWrappers
    Viewer -->|imports| coreWrappers
    Viewer -->|uses| mediaLinker

    pluginManifest -->|defines| pluginsPkg
    examplePlugin -->|manifest| pluginManifest

    examples -->|demonstrate| coreWrappers
    examples -->|demonstrate| adapters
    tests -->|validate| TimeLib
    tests -->|validate| TimelineLib
    tests -->|validate| coreWrappers

    %% Click Events
    click BuildSystem "https://github.com/academysoftwarefoundation/opentimelineio/blob/main/CMakeLists.txt"
    click BuildSystem "https://github.com/academysoftwarefoundation/opentimelineio/blob/main/setup.py"
    click BuildSystem "https://github.com/academysoftwarefoundation/opentimelineio/blob/main/pyproject.toml"
    click pybind11 "https://github.com/academysoftwarefoundation/opentimelineio/tree/main/src/deps/pybind11"
    click rapidjson "https://github.com/academysoftwarefoundation/opentimelineio/tree/main/src/deps/rapidjson"
    click Imath "https://github.com/academysoftwarefoundation/opentimelineio/tree/main/src/deps/Imath"
    click TimeLib "https://github.com/academysoftwarefoundation/opentimelineio/tree/main/src/opentime/"
    click TimelineLib "https://github.com/academysoftwarefoundation/opentimelineio/tree/main/src/opentimelineio/"
    click OpTimeBindings "https://github.com/academysoftwarefoundation/opentimelineio/tree/main/src/py-opentimelineio/opentime-bindings/"
    click OtioBindings "https://github.com/academysoftwarefoundation/opentimelineio/tree/main/src/py-opentimelineio/opentimelineio-bindings/"
    click coreWrappers "https://github.com/academysoftwarefoundation/opentimelineio/tree/main/src/py-opentimelineio/opentimelineio/core/"
    click adapters "https://github.com/academysoftwarefoundation/opentimelineio/tree/main/src/py-opentimelineio/opentimelineio/adapters/"
    click algorithms "https://github.com/academysoftwarefoundation/opentimelineio/tree/main/src/py-opentimelineio/opentimelineio/algorithms/"
    click consolePkg "https://github.com/academysoftwarefoundation/opentimelineio/tree/main/src/py-opentimelineio/opentimelineio/console/"
    click pluginsPkg "https://github.com/academysoftwarefoundation/opentimelineio/tree/main/src/py-opentimelineio/opentimelineio/plugins/"
    click schema "https://github.com/academysoftwarefoundation/opentimelineio/tree/main/src/py-opentimelineio/opentimelineio/schema/"
    click schemadef "https://github.com/academysoftwarefoundation/opentimelineio/tree/main/src/py-opentimelineio/opentimelineio/schemadef/"
    click hooks "https://github.com/academysoftwarefoundation/opentimelineio/blob/main/src/py-opentimelineio/opentimelineio/hooks.py"
    click mediaLinker "https://github.com/academysoftwarefoundation/opentimelineio/blob/main/src/py-opentimelineio/opentimelineio/media_linker.py"
    click Viewer "https://github.com/academysoftwarefoundation/opentimelineio/tree/main/src/opentimelineview/"
    click pluginManifest "https://github.com/academysoftwarefoundation/opentimelineio/blob/main/src/py-opentimelineio/opentimelineio/plugins/manifest.py"
    click examplePlugin "https://github.com/academysoftwarefoundation/opentimelineio/tree/main/examples/sample_plugin/otio_counter/"
    click examples "https://github.com/academysoftwarefoundation/opentimelineio/tree/main/examples/"
    click tests "https://github.com/academysoftwarefoundation/opentimelineio/tree/main/tests/"

    %% Styles
    classDef cpp fill:#cce5ff,stroke:#004085,color:#004085;
    classDef build fill:#e2e3e5,stroke:#6c757d,color:#383d41;
    classDef binding fill:#fff3cd,stroke:#856404,color:#856404;
    classDef python fill:#d4edda,stroke:#155724,color:#155724;
    classDef app fill:#d1ecf1,stroke:#0c5460,color:#0c5460;
    classDef plugin fill:#f8d7da,stroke:#721c24,color:#721c24;
    classDef grey fill:#e2e3e5,stroke:#6c757d,color:#383d41;
```
