TimelineEngine (core) 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: typeOperator`	Current clip groups owned by the engine.
`contentRevision`	`contentRevision: number`	Monotonic revision for changes that can affect active layer lookup.
`frameRate`	`frameRate: TimecodeFrameRate \| undefined`	Configured timeline frame rate for frame-accurate editing controls.
`geometry`	`geometry: TimelineGeometry`
`isSnappingEnabled`	`isSnappingEnabled: boolean`	Whether magnetic snapping is enabled.
`keyframes`	`keyframes: TimelineKeyframes`
`markers`	`markers: typeOperator`	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.
`media`	`media: TimelineMediaQueries`
`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: typeOperator`	Current readonly track snapshots.
`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): Marker`	Adds a marker at a timeline time.
`addTrack`	`addTrack(track: Track): TimelineCommandResult`	Appends a track to the timeline.
`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.
`commitEdit`	`commitEdit(command: TimelineEditCommand): TimelineEditCommitResult`	Resolves, validates, and commits an edit command as one history entry.
`commitEdits`	`commitEdits(commands: typeOperator): TimelineEditCommitResult[]`	Validates and applies an ordered batch atomically as one undo step.
`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(): TimelineEditCommitResult`	Copies selected clips into the clipboard, then removes them from their tracks.
`emit`	`emit(event: Key, 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.
`getClipDropFeedback`	`getClipDropFeedback(): TimelineClipDropFeedback`	Current transient drop feedback for the active clip body drag interaction.
`getClipGroup`	`getClipGroup(id: string): TimelineClipGroup \| undefined`
`getClipGroupClips`	`getClipGroupClips(groupId: string): TimelineClipEntry<string>[]`	Returns clips contained by a group in group order.
`getClipGroupForClip`	`getClipGroupForClip(id: string): TimelineClipGroup \| undefined`
`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.
`getKeyframePropertyDefinition`	`getKeyframePropertyDefinition(property: string): Readonly<TimelineKeyframePropertyDefinition<string>> \| null`	Returns one registered scalar keyframe property definition.
`getPlaybackRate`	`getPlaybackRate(): number`	Returns the current playback speed multiplier.
`getPlaybackStartTime`	`getPlaybackStartTime(options: PlaybackOptions = {}): RationalTime`	Resolves exhausted Out-point and loop-duration starts to the active range start.
`getRenderState`	`getRenderState(): object`	Returns readonly drawing content, including a non-mutating edit preview.
`getSelectedClipIds`	`getSelectedClipIds(): string[]`	Returns currently selected clip IDs in timeline track order.
`getState`	`getState(): object`	Returns a stable, deeply readonly snapshot with owned document values.
`getTime`	`getTime(): RationalTime`	Returns the current playhead time.
`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`	Invalidates content-dependent queries and renderer snapshots.
`listKeyframeProperties`	`listKeyframeProperties(): Readonly<TimelineKeyframePropertyDefinition<string>>[]`	Returns all registered scalar keyframe property definitions.
`moveTrack`	`moveTrack(trackId: string, toIndex: number): TimelineCommandResult`	Moves a track to a final zero-based row index as one undoable change.
`on`	`on(event: K, callback: (payload: indexedAccess) => void): () => void`	Subscribes to a typed event.
`pasteSelection`	`pasteSelection(time: RationalTime, targetTrackId?: string): TimelineEditCommitResult[] \| undefined`	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.
`removeMarker`	`removeMarker(id: string): boolean`	Removes a marker by id.
`removeTrack`	`removeTrack(trackId: string): TimelineCommandResult<void>`	Removes a track by id.
`renameTrack`	`renameTrack(trackId: string, name: string \| undefined): TimelineCommandResult`	Renames a track, or clears its app-defined name.
`resolveSnap`	`resolveSnap(time: RationalTime, publishFeedback: boolean = true): TimelineSnapResult \| null`	Resolves a candidate timeline time against the prepared snap index.
`selectClip`	`selectClip(clipId: string \| null): TimelineCommandResult`	Selects one clip and clears selection from all others.
`selectClips`	`selectClips(clipIds: typeOperator): TimelineCommandResult`	Selects a set of clips and clears selection from all others.
`selectTrack`	`selectTrack(trackId: string \| null): TimelineCommandResult`	Selects one track and clears selection from all others.
`setClipDropFeedback`	`setClipDropFeedback(feedback: TimelineClipDropFeedback): void`	Publishes transient drop feedback for renderer and headless UI consumers.
`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.
`setInOutRange`	`setInOutRange(startTime: RationalTime, endTime: RationalTime): TimelineCommandResult`	Atomically replaces both In/Out boundaries without intermediate range clearing.
`setInPoint`	`setInPoint(time: RationalTime \| undefined, snap?: boolean): void`	Sets or clears the in-point boundary. Clears both points when it reaches or crosses the out-point.
`setOutPoint`	`setOutPoint(time: RationalTime \| undefined, snap?: boolean): void`	Sets or clears the out-point boundary. Clears both points when it reaches or crosses the in-point.
`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.
`setTrackCollapsed`	`setTrackCollapsed(trackId: string, collapsed: boolean): TimelineCommandResult`	Sets row collapse without changing its expanded height or media visibility.
`setTrackGroup`	`setTrackGroup(trackId: string, groupId: string \| undefined): TimelineCommandResult<void>`	Assigns a track to a group or removes it from grouping.
`setTrackHeight`	`setTrackHeight(trackId: string, height: number): TimelineCommandResult<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.
`snapshot`	`snapshot(): void`	Stores the current track and marker state in undo history.
`timeToPixel`	`timeToPixel(time: RationalTime): number`	Converts a timeline time to a horizontal pixel coordinate.
`toggleClipSelection`	`toggleClipSelection(clipId: string, selected?: boolean): TimelineCommandResult<void>`	Toggles one clip in the current multi-selection.
`toggleLockTrack`	`toggleLockTrack(trackId: string, locked?: boolean): TimelineCommandResult<void>`	Enables, disables, or toggles a track's locked state.
`toggleMuteTrack`	`toggleMuteTrack(trackId: string, muted?: boolean): TimelineCommandResult<void>`	Enables, disables, or toggles a track's muted state.
`toggleTrackTarget`	`toggleTrackTarget(trackId: string, targeted?: boolean): TimelineCommandResult<void>`	Enables, disables, or toggles track targeting.
`toggleTrackVisibility`	`toggleTrackVisibility(trackId: string, visible?: boolean): TimelineCommandResult<void>`	Enables, disables, or toggles a track's output visibility.
`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.
`updateClipProperties`	`updateClipProperties(clipId: string, properties: Partial<Pick<Clip, "label" \| "opacity" \| "color">>): TimelineCommandResult<void>`	Updates user-facing clip display properties.
`updateExternalPlaybackTime`	`updateExternalPlaybackTime(time: RationalTime): ExternalPlaybackUpdate`	Advances externally clocked playback through the shared range policy.
`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`