Klippy

Tracks, items, assets

This page explains how timeline rows (tracks) are structured and how items (media, text, zoom, transitions, captions) are represented in state. It reflects the implementation in the Redux slices and types underapp/types and app/store.

1) Tracks (rows)

  • Each timeline row is an integer index (row) starting at 0.
  • Media and text items store their row; reordering updates this value (see row handles in the Timeline UI).
  • Visible rows are configurable (projectState.visibleRows); the timeline virtualizes off‑screen rows.

2) Items (clips & overlays)

Video / Image / Audio (MediaFile)

  • Time within source: startTime → endTime (trim).
  • Placement on timeline: positionStart → positionEnd (seconds).
  • Row index: row; layering via zIndex and opacity.
  • Transform: optional x/y/width/height/rotation and fit/mask/crop.
  • Audio: volume, pan/EQ, optional visualizations.
  • Effects: advancedEffects collection and CSS filter presets.
  • Transitions: per‑clip transition (type/duration/direction) and global between‑clip transitions map.
  • Other: includeInMerge, playbackSpeed, mimeType.

Text (TextElement)

  • Lives on the timeline like media: positionStart/positionEnd, row, zIndex.
  • Typography + box: font, size, color, background, padding; dimensions computed for layout.
  • Transforms and opacity supported for overlay composition.

Zoom (ZoomElement)

  • Defines a camera‑like zoom/pan window active between positionStart/positionEnd.
  • Rendered as a separate track to preview focus regions and create dynamic framing.

Transitions (ITransition)

  • Between‑clip transitions are tracked in a map (betweenClipTransitions) keyed by ID.
  • Selectors build pairs (fromClip/toClip) for rendering and editing in the Transitions panel.

3) Captions, transcript, and preview lane

  • Caption tracks (CaptionTrack) live in projectState.captionTracks; active track ID is separate.
  • Transcript data is stored per media in the transcripts slice (words + timings).
  • Edits slice holds remove/mute/silence ranges visualized in the preview lane; clicking focuses the range.

4) Timing model

An item’s segment time (startTime → endTime) trims the source file. Its timeline time (positionStart → positionEnd) decides when it appears in the composition. The UI keeps these in sync when you drag edges or move clips.

5) Asset storage

  • Files are stored in IndexedDB with IDs (files store). Project JSON references items by fileId.
  • Utilities in app/store/index.ts: storeFile, getFile, listFiles, storeProject, listProjects.
  • Media panel manages file IDs (projectState.filesID) and syncs additions/removals.

6) Drag, drop, and snapping

  • Drag logic uses consolidated hooks (useTimelineDragAndDrop) to update overlay positions and rows.
  • Snapping uses calculated points and guidelines; drop zones highlight valid placements.
  • Row reordering changes the row field on affected items.

7) Where to look in code

  • Types: app/types/media.ts, app/types/text.ts, app/types/zoom.ts, app/types/transitions.ts, app/types/captions.ts
  • Slices: app/store/slices/projectSlice.ts (content), timelineSlice.ts (playback), editsSlice.ts (ranges)
  • Selectors: app/store/selectors/timelineSelectors.ts, derivedSelectors.ts
  • Timeline UI: app/components/editor/timeline/* (rows, items, snapping, grid)