tellers-timeline

The timeline engine for tools that make the cut.

Read timelines. Make edits. Keep everything in sync.

Install · Try it · Features · Standardization · Contribute

tellers-timeline is an open-source timeline engine, written in Rust and available in Python, built around OpenTimelineIO. Use it to build editors, automate cuts, and exchange timelines between tools.

Our ambition is full OTIO coverage, with an editing API that handles the work around the format: insert and overlap policies, linked audio and video, stable identity, media bounds, and document cleanup. We're also developing shared conventions for effects and IDs so more of an edit can travel between applications.

Install

Python — prebuilt wheels for Linux x86-64, macOS Intel and Apple Silicon, and Windows x86-64:

pip install tellers-timeline

Rust — add the library to your application:

cargo add tellers-timeline-core

Python imports tellers_timeline; Rust imports tellers_timeline_core. Building the Python package from source requires Rust and Cargo.

Make your first edit

Create a video track, insert a clip at two seconds, and serialize the timeline:

from tellers_timeline import Clip, MediaReference, Stack, Timeline, Track

stack = Stack([Track(kind="video", id="main-video")])
clip = Clip(
    5.0,
    {"DEFAULT_MEDIA": MediaReference("file:///media/shot.mov")},
    id="opening-shot",
)

stack.insert_item_at_time_by_id(
    "main-video",
    2.0,
    clip,
    "override",          # Replace material overlapping the new clip.
    "split_and_insert",  # Split a gap when inserting inside one.
)

timeline = Timeline(stack)
timeline.sanitize()
assert not timeline.validate()
print(timeline.to_json())

Editing APIs take time in seconds; OTIO serialization carries RationalTime values and rates. Load an existing document with Timeline.parse_json(text).

In Rust, work directly with the core types and shared effect conventions:

use tellers_timeline_core::{ColorLut, Timeline, Track, TrackKind};

let mut timeline = Timeline::default();
timeline.add_track(Track::new(TrackKind::Video, Some("main-video".into())));
timeline.push_color_lut(ColorLut::new("film-look").with_name("Film look"));
timeline.sanitize();

println!("{}", timeline.to_json().unwrap());

What works today

Full coverage is the goal. This table tracks the current implementation and the remaining work; it is not a claim of complete OTIO conformance.

The library manipulates edit data. Media playback, effect rendering, and export encoding belong to the application using it.

Building a shared language for editing

OTIO is the foundation. Alongside broader format support, we want applications to agree on what an effect means, which object an edit addresses, and how related clips stay together. These are project conventions and proposals for wider interoperability; they are not ratified OTIO standards.

Bring real timelines, editor integrations, and competing representations. The standardization work should be shaped by interoperability tests and adoption.

Explore and build

• Developer guide — architecture, local setup, editing semantics, visual test UI, and releases.
• Contributing — bug reports, feature proposals, compatibility fixtures, and pull requests.
• Rust API · Python type signatures · Example timelines · JSON Schema

Built by Tellers for timelines that can move between tools.