tl/tl/data_model.org

Data model

A scene contains tracks and a flat map of groups. OTIO supplies immutable raw clips. Each clip has a track, source-frame offset, duration, and position in the root timeline.

An annotation owns an ordered vector of marks. Each mark has a stable id and an ordered vector of parts:

{:type :annotation
 :in [:root :chapter]
 :marks [{:id :moment
          :parts [{:clip :clip-a :start 10 :end 20}
                  {:clip :clip-c :start 30 :end 50}
                  {:clip :clip-a :start 10 :end 20}]}]}

A part is a half-open integer frame range within a raw clip. Repeats, trims, and order are explicit. Marks can bind notes and drawings. Those bindings belong to the mark, not to any one rendered occurrence.

Opening an annotation concatenates its parts, in mark order. Selecting footage in any timeline stores raw-clip parts immediately. Editing or deleting the context does not change the selected footage.

:in is a set of visibility edges serialized as a vector; order has no meaning. Moving replaces the source edge with the destination edge. Linking adds an edge. Associating new marks with an annotation also enables its edge in the context where the marks were selected. Other edges remain untouched. An annotation with no surviving contexts is listed at root so it can be filed again.

Compilation and projection are different operations. resolve produces ordered source segments; project-bars finds every matching raw-clip occurrence in the render context, intersects ranges, and merges adjacent/overlapping display pieces. The same projection drives lane bars, selected bars, editor summaries, and bindings. Different marks never merge into one editable mark. Repetition in the context can make one stored part appear several times.

Projection cannot be inverted: a bounding range loses gaps, order, and repetition. The editor displays each contiguous projected range separately. Expanding a mark's summary exposes its actual ordered parts for endpoint edits. Endpoint edits clamp within that clip and cannot cross the opposite endpoint. The projected display never reconstructs or replaces the stored parts. Annotation drag-and-drop changes visibility only; dragging on the timeline creates a new selection.

View state holds navigation history, per-context playheads, and the active editing context. None of these is a parent or an input to the meaning of stored marks.