TimelineEngine API

Signature

Class TimelineEngine

Properties

Name	Signature	Description
`canPasteSelection`	`canPasteSelection: boolean`	Whether copied clips are available to paste.
`canRedo`	`canRedo: boolean`	Whether a redo snapshot is available.
`canUndo`	`canUndo: boolean`	Whether an undo snapshot is available.
`clipboardCount`	`clipboardCount: number`	Number of clips currently stored in the engine clipboard.
`clipGroups`	`clipGroups: TimelineClipGroup[]`	Current clip groups owned by the engine.
`contentRevision`	`contentRevision: number`	Monotonic revision for changes that can affect active layer lookup.
`isSnappingEnabled`	`isSnappingEnabled: boolean`	Whether magnetic snapping is enabled.
`markers`	`markers: Marker[]`	Current marker list.
`maxContentTime`	`maxContentTime: RationalTime`	Maximum timeline time used for playback and scroll clamping.
`maxScrollLeft`	`maxScrollLeft: number`	Maximum horizontal scroll offset for the current viewport and content duration.
`maxScrollTop`	`maxScrollTop: number`	Maximum vertical scroll offset for the current viewport and track stack.
`maxZoomScale`	`maxZoomScale: number`	Current maximum zoom scale in pixels per second. When a frame-rate cap is lower than the content-fit floor, the content-fit floor wins so zoom never violates viewport bounds.
`minZoomScale`	`minZoomScale: number`	Current minimum zoom scale in pixels per second. This preserves the content-fit floor so users cannot zoom out past the current duration/content bounds.
`playheadTime`	`playheadTime: RationalTime`	Current playhead position.
`scrollLeft`	`scrollLeft: number`	Current horizontal scroll offset in pixels.
`scrollTop`	`scrollTop: number`	Current vertical scroll offset in pixels.
`snapThresholdPixels`	`snapThresholdPixels: number`	Magnetic snap radius in screen pixels.
`tracks`	`tracks: Track<string>[]`	Current mutable track list owned by the engine.
`zoomScale`	`zoomScale: number`	Current horizontal zoom scale in pixels per second.

Constructors

Name	Signature	Description
`constructor`	`constructor(initialState: object): TimelineEngine`	Creates an instance of the TimelineEngine.

Methods

Name	Signature	Description
`addMarker`	`addMarker(time: RationalTime, label?: string, color?: string, description?: string): object`	Adds a marker at a timeline time.
`addTrack`	`addTrack(track: Track): void`	Appends a track to the timeline.
`applyOverwrites`	`applyOverwrites(winningClipId: string): void`	Applies overwrite-edit rules for a clip against overlapping clips on its track. Fully covered clips are removed, partially covered clips are trimmed, and clips split by the winner are divided into two segments.
`cancelEdit`	`cancelEdit(): void`	Clears the active command-layer edit preview and snap guides.
`clearClipDropFeedback`	`clearClipDropFeedback(): void`	Clears transient drop feedback for the active clip body drag interaction.
`clearInOutPoints`	`clearInOutPoints(): void`	Clears both in-point and out-point boundaries.
`clearKeyframeSelection`	`clearKeyframeSelection(): void`	Clears keyframe selection.
`commitEdit`	`commitEdit(command: TimelineEditCommand): TimelineEditCommitResult`	Resolves, validates, and commits an edit command as one history entry.
`copySelection`	`copySelection(): void`	Copies selected clips into the engine clipboard.
`createClipGroup`	`createClipGroup(options: TimelineCreateClipGroupOptions): TimelineClipGroup \| null`	Creates a clip group from existing clips.
`cutSelection`	`cutSelection(): void`	Copies selected clips into the clipboard, then removes them from their tracks.
`deleteClip`	`deleteClip(clipId: string): boolean`	Removes a clip from its containing track.
`emit`	`emit(event: K, args: undefined): void`	Emits a typed event to all active subscribers. Supports type-safety by enforcing key-value mapping and allows omitting the payload argument entirely if the map type is void.
`endDrag`	`endDrag(): void`	Ends live drag preview and clears temporary cut flags.
`getActiveClip`	`getActiveClip(query: ActiveClipQuery = {}): ActiveClip<string> \| undefined`	Returns the first active clip matching an active layer query.
`getActiveClips`	`getActiveClips(time: RationalTime = ...): ActiveClip<string>[]`	Returns enabled clips under a timeline time, ordered by track and clip order. Hidden or muted tracks and disabled clips are excluded so preview and playback integrations can pick sources using the same visibility rules. Clip intervals are half-open: active at `timelineStart` and inactive at `timelineEnd`.
`getActiveClipsByTrack`	`getActiveClipsByTrack(time: RationalTime = ...): Map<string, ActiveClip<string>[]>`	Groups active clips by containing track id.
`getActiveLayers`	`getActiveLayers(options: ActiveLayerOptions<LayerName>): ActiveLayerResult<LayerName>`	Finds the clips active at a timeline time and groups them by named layer selectors. Use this for preview, playback, subtitle, and effect integrations that need to know which layer clips should be rendered or synced at the playhead. Hidden or muted tracks and disabled clips are excluded. The result preserves every match in `layers`, deduplicates matches in `all`, and exposes `primary` as a first-match convenience for each requested layer.
`getClip`	`getClip(clipId: string): { clip: Clip; clipIndex: number; track: Track; trackIndex: number } \| undefined`	Locates a clip and returns its containing track and indexes.
`getClipAtPoint`	`getClipAtPoint(input: ClipHitTestInput): ClipHitTestResult \| null`	Hit-tests timeline clips in viewport coordinates, matching canvas track layout. Clip bodies remain selectable even when their track is locked or the clip is non-editable; edge/body edit regions are only reported when the clip can be edited.
`getClipDropFeedback`	`getClipDropFeedback(): TimelineClipDropFeedback`	Current transient drop feedback for the active clip body drag interaction.
`getClipGroup`	`getClipGroup(groupId: string): TimelineClipGroup \| undefined`	Returns a clip group by id.
`getClipGroupClips`	`getClipGroupClips(groupId: string): TimelineClipLookup[]`	Returns clips contained by a group in group order.
`getClipGroupForClip`	`getClipGroupForClip(clipId: string): TimelineClipGroup \| undefined`	Returns the group containing a clip.
`getClipKeyframes`	`getClipKeyframes(clipId: string, property?: string): TimelineKeyframe[]`	Returns keyframes owned by one clip, optionally filtered by property.
`getClipPropertyValueAtTime`	`getClipPropertyValueAtTime(clipIdOrClip: string \| Clip, property: string, timelineTime: RationalTime = ...): number \| undefined`	Evaluates a keyframed clip property at a timeline time.
`getClipRect`	`getClipRect(clipId: string, geometry: TimelineInteractionGeometry = {}): ClipViewportRect \| null`	Returns the current viewport rectangle for a clip, matching canvas track layout.
`getClipRects`	`getClipRects(options: TimelineInteractionGeometry = {}): TimelineClipRect<TrackKind>[]`	Returns viewport rectangles for every clip in track order. This is the canonical geometry source for DOM clip rendering and custom canvas layers. Pointer hit testing keeps a direct low-allocation path.
`getClipSourceRange`	`getClipSourceRange(clipIdOrClip: string \| Clip): ClipSourceRange \| undefined`	Computes the source-media range covered by a clip.
`getClipSyncKey`	`getClipSyncKey(clipIdOrClip: string \| Clip): string \| undefined`	Returns a stable media sync signature for timing-affecting clip fields.
`getEditImpacts`	`getEditImpacts(): TimelineEditImpacts \| null`	Current transient impacts for the active live edit interaction. Returns null when no live edit is currently affecting other clips.
`getEditPreview`	`getEditPreview(): TimelineEditPreview \| null`	Current transient preview for the active command-layer edit. Returns null when no command preview is active.
`getFirstContentTime`	`getFirstContentTime(options: Pick<ActiveLayerOptions<LayerName>, "layers">): RationalTime \| undefined`	Finds the earliest clip start matching any requested layer.
`getKeyframeAtPoint`	`getKeyframeAtPoint(input: TimelineKeyframeHitTestInput): TimelineKeyframeHitTestResult<TrackKind> \| null`	Hit-tests timeline keyframes in viewport coordinates.
`getKeyframePropertyDefinition`	`getKeyframePropertyDefinition(property: string): Readonly<TimelineKeyframePropertyDefinition<string>> \| null`	Returns one registered scalar keyframe property definition.
`getKeyframeRects`	`getKeyframeRects(options: TimelineKeyframeGeometryOptions = {}): TimelineKeyframeRect<TrackKind>[]`	Returns viewport rectangles for keyframes in track order.
`getKeyframeRenderGeometry`	`getKeyframeRenderGeometry(options: TimelineKeyframeRenderGeometryOptions): TimelineKeyframeRenderGeometry`	Returns serializable keyframe geometry for canvas rendering.
`getKeyframeSegments`	`getKeyframeSegments(options: TimelineKeyframeSegmentGeometryOptions = {}): TimelineKeyframeSegment<TrackKind>[]`	Returns keyframe segments in track order.
`getKeyframeTangentHandleAtPoint`	`getKeyframeTangentHandleAtPoint(input: TimelineKeyframeTangentHitTestInput): TimelineKeyframeTangentHandleHitTestResult<TrackKind> \| null`	Hit-tests Bezier tangent handles in viewport coordinates.
`getPlaybackRate`	`getPlaybackRate(): number`	Returns the current playback speed multiplier.
`getState`	`getState(): TimelineState`	Returns the current engine state object.
`getTime`	`getTime(): RationalTime`	Returns the current playhead time.
`getTrackAtPoint`	`getTrackAtPoint(input: TrackHitTestInput): TimelineTrackHitTestResult<TrackKind> \| null`	Hit-tests timeline tracks in viewport coordinates, matching canvas layout.
`getTrackRects`	`getTrackRects(options: TimelineTrackGeometryOptions = {}): TimelineTrackRect[]`	Returns viewport rectangles for every track row in track order.
`getVisibleKeyframes`	`getVisibleKeyframes(options: TimelineKeyframeGeometryOptions = {}): VisibleTimelineKeyframe<TrackKind>[]`	Returns keyframes intersecting the current viewport, plus optional overscan.
`getVisibleKeyframeSegments`	`getVisibleKeyframeSegments(options: TimelineKeyframeSegmentGeometryOptions = {}): VisibleTimelineKeyframeSegment<TrackKind>[]`	Returns keyframe segments intersecting the current viewport.
`getVisibleTimelineClips`	`getVisibleTimelineClips(options: VisibleTimelineClipOptions = {}): VisibleTimelineClip<TrackKind>[]`	Returns clips intersecting the current horizontal viewport, plus optional overscan. The returned visible ranges map clipped viewport pixels back to timeline and source-media times so custom renderers can draw cached thumbnails, waveforms, annotations, or heatmaps without duplicating timeline math.
`hasKeyframeProperty`	`hasKeyframeProperty(property: string): boolean`	Returns whether a scalar keyframe property is registered.
`insertClipGroup`	`insertClipGroup(options: TimelineInsertClipGroupOptions): TimelineClipGroup \| null`	Inserts multiple clips on chosen tracks and groups them in one history entry. This convenience API uses the same grouped insert command pipeline as `commitEdit({ type: 'insert-clip-group', ... })`, including validation, edit policy checks, snapping, ripple behavior, lifecycle events, and undo history.
`invalidateContent`	`invalidateContent(): void`	Marks timeline content as changed and notifies subscribers. Use this after external metadata that affects rendering changes without a structural timeline edit, such as waveform availability, thumbnails, or cached analysis keyed by clip id.
`listKeyframeProperties`	`listKeyframeProperties(): Readonly<TimelineKeyframePropertyDefinition<string>>[]`	Returns all registered scalar keyframe property definitions.
`moveClip`	`moveClip(options: TimelineClipMoveOptions): boolean`	Moves a clip to a new timeline start time and optionally into another track. Honors track and clip movement locks, track-kind compatibility, min/max bounds, snapping, and overwrite preview state when a drag is active.
`on`	`on(event: K, callback: (payload: indexedAccess) => void): () => void`	Subscribes to a typed event.
`pasteSelection`	`pasteSelection(time: RationalTime, targetTrackId?: string): void`	Pastes clipboard clips at a timeline time. Relative offsets between copied clips are preserved. When no target track is supplied, the first targeted track is used, then the first track as fallback.
`pause`	`pause(): void`	Stops playhead playback and clears the active animation frame.
`pixelToTime`	`pixelToTime(pixel: number, rate: number = 24000): RationalTime`	Converts a horizontal pixel coordinate to timeline time.
`play`	`play(options: PlaybackOptions = {}): boolean`	Plays the timeline.
`prepareSnapping`	`prepareSnapping(ignoreClipIdOrOptions?: string \| SnapPreparationOptions): void`	Rebuilds snap targets for an upcoming drag, trim, or range-boundary gesture.
`previewEdit`	`previewEdit(command: TimelineEditCommand): TimelineEditPreview`	Resolves and publishes a non-mutating preview for an edit command.
`redo`	`redo(): void`	Restores the next redo-history snapshot when available.
`registerKeyframeProperties`	`registerKeyframeProperties(definitions: TimelineKeyframePropertyDefinition<string>[]): void`	Registers scalar keyframe property definitions.
`registerKeyframeProperty`	`registerKeyframeProperty(definition: TimelineKeyframePropertyDefinition): void`	Registers one scalar keyframe property definition.
`registerSnapProvider`	`registerSnapProvider(provider: TimelineSnapProvider): () => void`	Registers a runtime snap target provider.
`removeClipKeyframe`	`removeClipKeyframe(clipId: string, keyframeId: string, options: TimelineKeyframeMutationOptions = {}): boolean`	Removes a keyframe from one clip.
`removeMarker`	`removeMarker(id: string): boolean`	Removes a marker by id.
`removeTrack`	`removeTrack(trackId: string): boolean`	Removes a track by id.
`resolveSnap`	`resolveSnap(time: RationalTime, publishFeedback: boolean = true): TimelineSnapResult \| null`	Resolves a candidate timeline time against the prepared snap index.
`selectClip`	`selectClip(clipId: string \| null): void`	Selects one clip and clears selection from all others.
`selectClipKeyframe`	`selectClipKeyframe(clipId: string \| null, keyframeId: string \| null): void`	Selects one keyframe and clears all other keyframe selections.
`selectClips`	`selectClips(clipIds: typeOperator): void`	Selects a set of clips and clears selection from all others.
`selectTrack`	`selectTrack(trackId: string \| null): void`	Selects one track and clears selection from all others.
`setClipDropFeedback`	`setClipDropFeedback(feedback: TimelineClipDropFeedback): void`	Publishes transient drop feedback for renderer and headless UI consumers.
`setClipKeyframe`	`setClipKeyframe(input: TimelineSetClipKeyframeOptions, options: TimelineKeyframeMutationOptions = {}): TimelineKeyframe \| null`	Adds or updates one keyframe by clip, property, and exact timeline time. New keyframes created without explicit side interpolation use normalized linear defaults during evaluation.
`setDuration`	`setDuration(duration: RationalTime \| undefined): void`	Sets or clears an explicit timeline duration. When a duration is set, zoom, scroll, and playhead are clamped to that duration instead of the dynamic maximum clip end.
`setEditPolicy`	`setEditPolicy(policy: TimelineEditPolicy \| undefined): void`	Replaces the app-defined edit policy used by command validation.
`setInPoint`	`setInPoint(time: RationalTime \| undefined, snap?: boolean): void`	Sets or clears the in-point boundary.
`setOutPoint`	`setOutPoint(time: RationalTime \| undefined, snap?: boolean): void`	Sets or clears the out-point boundary.
`setPlaybackRate`	`setPlaybackRate(rate: number): void`	Updates the playback speed multiplier.
`setScrollLeft`	`setScrollLeft(scroll: number): void`	Sets horizontal scroll offset, clamped to the valid scroll range.
`setScrollTop`	`setScrollTop(scroll: number): void`	Sets vertical scroll offset, clamped to the valid track stack scroll range.
`setSnappingEnabled`	`setSnappingEnabled(enabled: boolean): void`	Enables or disables magnetic snapping.
`setSnapThresholdPixels`	`setSnapThresholdPixels(thresholdPixels: number): void`	Sets the magnetic snap radius in screen pixels.
`setTime`	`setTime(time: RationalTime): void`	Moves the playhead to an absolute timeline time. Alias for `updatePlayhead` that reads naturally in external media sync code.
`settle`	`settle(): void`	Finalizes an interaction, clears snap guides, snapshots history, and emits settled state.
`setTrackGroup`	`setTrackGroup(trackId: string, groupId: string \| undefined): void`	Assigns a track to a group or removes it from grouping.
`setTrackHeight`	`setTrackHeight(trackId: string, height: number): void`	Updates a track's expanded display height.
`setTrackHeights`	`setTrackHeights(updates: typeOperator, options: TimelineTrackHeightBatchOptions = {}): void`	Sets multiple expanded track heights and publishes a single settled/render cycle.
`setViewportHeight`	`setViewportHeight(height: number): void`	Stores the visible timeline viewport height.
`setViewportWidth`	`setViewportWidth(width: number): void`	Stores the visible timeline viewport width.
`setZoomConstraints`	`setZoomConstraints(constraints: TimelineZoomConstraints = {}): void`	Updates engine-owned zoom constraints and re-clamps the current viewport.
`setZoomScale`	`setZoomScale(scale: number): void`	Sets the zoom scale while keeping the viewport within content bounds.
`slideClip`	`slideClip(clipId: string, deltaTime: RationalTime): void`	Moves a clip by a relative timeline offset.
`slipClip`	`slipClip(clipId: string, deltaTime: RationalTime): void`	Shifts a clip's source start without moving it on the timeline.
`snapshot`	`snapshot(): void`	Stores the current track and marker state in undo history.
`sourceTimeToTimelineTime`	`sourceTimeToTimelineTime(clipIdOrClip: string \| Clip, sourceTime: RationalTime): RationalTime \| undefined`	Maps a source-media timestamp within a clip back to timeline time.
`splitClip`	`splitClip(clipId: string, splitTime: RationalTime): boolean`	Splits a clip into two clips at a timeline time.
`startDrag`	`startDrag(): void`	Captures the current track state for live drag preview.
`timelineTimeToSourceTime`	`timelineTimeToSourceTime(clipIdOrClip: string \| Clip, timelineTime: RationalTime = ...): RationalTime \| undefined`	Maps a timeline timestamp within a clip to the matching source-media time.
`timeToPixel`	`timeToPixel(time: RationalTime): number`	Converts a timeline time to a horizontal pixel coordinate.
`toggleClipSelection`	`toggleClipSelection(clipId: string, selected?: boolean): boolean`	Toggles one clip in the current multi-selection.
`toggleLockTrack`	`toggleLockTrack(trackId: string, locked?: boolean): void`	Enables, disables, or toggles a track's locked state.
`toggleMuteTrack`	`toggleMuteTrack(trackId: string, muted?: boolean): void`	Enables, disables, or toggles a track's muted state.
`toggleTrackTarget`	`toggleTrackTarget(trackId: string, targeted?: boolean): void`	Enables, disables, or toggles track targeting.
`toggleTrackVisibility`	`toggleTrackVisibility(trackId: string, visible?: boolean): void`	Enables, disables, or toggles a track's output visibility.
`trimClip`	`trimClip(clipId: string, edge: "start" \| "end", newTime: RationalTime): void`	Trims one edge of a clip to a new timeline time. Start trims also shift `sourceStart` so the visible source frame remains aligned with the new timeline boundary.
`undo`	`undo(): void`	Restores the previous undo-history snapshot when available.
`ungroupClipGroup`	`ungroupClipGroup(groupId: string): boolean`	Removes one clip group.
`ungroupClips`	`ungroupClips(clipIds: typeOperator): boolean`	Removes groups containing any of the supplied clips.
`updateClipKeyframe`	`updateClipKeyframe(input: TimelineUpdateClipKeyframeOptions, options: TimelineKeyframeMutationOptions = {}): TimelineKeyframe \| null`	Updates an existing keyframe. Committed updates merge keyframes that land on the same property and time. Preview updates (`{ commit: false }`) never delete a colliding neighbor; the keyframe keeps its current time instead, so drag previews stay non-destructive.
`updateClipKeyframeSide`	`updateClipKeyframeSide(input: TimelineUpdateClipKeyframeSideOptions, options: TimelineKeyframeMutationOptions = {}): TimelineKeyframe \| null`	Updates one side of an existing keyframe.
`updateClipKeyframeSides`	`updateClipKeyframeSides(input: TimelineUpdateClipKeyframeSidesOptions, options: TimelineKeyframeMutationOptions = {}): TimelineKeyframe \| null`	Updates one or both sides of an existing keyframe.
`updateClipProperties`	`updateClipProperties(clipId: string, properties: Partial<Pick<Clip, "label" \| "opacity" \| "color">>): boolean`	Updates user-facing clip display properties.
`updateMarker`	`updateMarker(id: string, updates: Partial<Omit<Marker, "id">>): Marker \| null`	Updates an existing marker.
`updatePlayhead`	`updatePlayhead(time: RationalTime): void`	Moves the playhead, clamped to the timeline content range.
`validateEdit`	`validateEdit(command: TimelineEditCommand): TimelineEditValidationResult`