Class Timeline

constructor

• new Timeline(): Timeline

  Creates an empty timeline with default playback settings.

  Returns Timeline

currentTime

fps

isPlaying

layers

layersOrder

volume

addLayer

• addLayer(layer: Layer, index?: number): Promise<void>

  Adds an existing layer instance to the timeline.

  Parameters

  • layer: Layer

    Layer instance to add.

  • Optionalindex: number

    Optional insertion index in the layer order.

  Returns Promise<void>

  A promise that resolves after the layer has been initialized.

addMedia

• addMedia(file: File): Promise<null | string>

  Imports a media file into the project library.

  Parameters

  • file: File

    Source file to add.

  Returns Promise<null | string>

  A promise that resolves to the created media ID, or null if the import fails before an ID can be returned.

adjustClipsLayout

• adjustClipsLayout(): boolean

  Reflows clips on every layer to resolve overlaps or spacing issues according to each layer's layout rules.

  Returns boolean

  true if any layer changed its clip layout; otherwise false.

alignTime

• alignTime(time: number, roundDirection?: AlignRoundEnum): number

  Aligns a time value to the nearest valid frame boundary.

  Parameters

  • time: number

    Source time in seconds.

  • roundDirection: AlignRoundEnum = AlignRoundEnum.NEAREST

    Rounding strategy used during alignment.

  Returns number

  The aligned time in seconds.

clearAllCustomData

• clearAllCustomData(): void

  Removes all custom metadata stored on the timeline.

  Returns void

  Nothing.

createLayer

• createLayer(options?: { index?: number }): Layer

  Creates, inserts, and initializes a new layer.

  Parameters

  • Optionaloptions: { index?: number }

    Optional insertion options.

  Returns Layer

  The created layer.

destroy

• destroy(): void

  Stops the render loop, destroys every layer, and removes all timeline content.

  Returns void

  Nothing.

discardProcessing

• discardProcessing(): void

  Cancels in-progress processing work for every clip on the timeline.

  Returns void

  Nothing.

extractAudio

• extractAudio(
      clip: string | Clip<Sprite, ClipStyle<Sprite>>,
  ): undefined | AudioClip

  Creates an audio clip from the audio track of a video clip.

  Parameters

  • clip: string | Clip<Sprite, ClipStyle<Sprite>>

    Video clip instance or video clip ID.

  Returns undefined | AudioClip

  The created audio clip, or undefined if extraction is not possible.

getAllCustomData

• getAllCustomData(): undefined | Map<string, unknown>

  Returns a copy of all custom metadata stored on the timeline.

  Returns undefined | Map<string, unknown>

  A copied metadata map, or undefined if no custom data has been stored.

getClipById

• getClipById(clipId: string): undefined | Clip<Sprite, ClipStyle<Sprite>>

  Returns a clip by its ID.

  Parameters

  • clipId: string

    Clip ID to look up.

  Returns undefined | Clip<Sprite, ClipStyle<Sprite>>

  The matching clip, or undefined if not found.

getClips

• getClips(): Clip<Sprite, ClipStyle<Sprite>>[]

  Returns all clips across every layer.

  Returns Clip<Sprite, ClipStyle<Sprite>>[]

  The flattened clip list.

getClipsByMediaId

• getClipsByMediaId(mediaId: string): Clip<Sprite, ClipStyle<Sprite>>[]

  Returns all clips that reference the specified media item.

  Parameters

  • mediaId: string

    Media ID to match.

  Returns Clip<Sprite, ClipStyle<Sprite>>[]

  The matching clips.

getClipsBySubtitlesId

• getClipsBySubtitlesId(subtitlesId: string): Clip<Sprite, ClipStyle<Sprite>>[]

  Returns all clips that reference the specified subtitles asset.

  Parameters

  • subtitlesId: string

    Subtitles asset ID to match.

  Returns Clip<Sprite, ClipStyle<Sprite>>[]

  The matching clips.

getCustomData

• getCustomData(key: string): unknown

  Returns a previously stored timeline metadata value.

  Parameters

  • key: string

    Metadata key to look up.

  Returns unknown

  The stored value, or undefined if the key is not present.

getFitDuration

• getFitDuration(): number

  Returns the end time of the right-most visible content on the timeline.

  Returns number

  The fit duration in seconds.

getFps

• getFps(): number

  Returns the timeline frame rate.

  Returns number

  Frames per second used for playback and time alignment.

getFrameDuration

• getFrameDuration(): number

  Returns the duration of a single timeline frame.

  Returns number

  The frame duration in seconds.

getFrameNumberFromTime

• getFrameNumberFromTime(time: number, roundDirection?: AlignRoundEnum): number

  Converts a time value into a frame number using the current timeline FPS.

  Parameters

  • time: number

    Source time in seconds.

  • roundDirection: AlignRoundEnum = AlignRoundEnum.NEAREST

    Rounding strategy used during alignment.

  Returns number

  The aligned frame number.

getFrameNumberFromTimeValues

• getFrameNumberFromTimeValues(timeValues: number[]): number[]

  Converts multiple time values into frame numbers using the current timeline FPS.

  Parameters

  • timeValues: number[]

    Source times in seconds.

  Returns number[]

  The matching frame numbers in the same order.

getIsProcessing

• getIsProcessing(): boolean

  Indicates whether any clip on the timeline is still processing media or effects.

  Returns boolean

  true if at least one clip is still processing; otherwise false.

getLayerByClipId

• getLayerByClipId(clipId: string): undefined | Layer

  Returns the layer that currently owns the specified clip.

  Parameters

  • clipId: string

    Clip ID to look up.

  Returns undefined | Layer

  The layer containing the clip, or undefined if the clip cannot be found.

getLayerById

• getLayerById(layerId: string): undefined | Layer

  Returns a layer by its ID.

  Parameters

  • layerId: string

    Layer ID to look up.

  Returns undefined | Layer

  The matching layer, or undefined if not found.

getLayerIdx

• getLayerIdx(layerId: string): number

  Returns the current order index of a layer in the timeline stack.

  Parameters

  • layerId: string

    Layer ID to look up.

  Returns number

  The zero-based layer index, or -1 if the layer is not present.

getVolume

• getVolume(): number

  Returns the current master timeline volume.

  Returns number

  The timeline volume multiplier.

hasCustomData

• hasCustomData(key: string): boolean

  Indicates whether the timeline has a stored metadata value for the provided key.

  Parameters

  • key: string

    Metadata key to test.

  Returns boolean

  true if the key exists; otherwise false.

init

• init(): Promise<void>

  Initializes all layers and starts the render loop.

  Returns Promise<void>

  A promise that resolves after timeline initialization completes.

loadSerializedData

• loadSerializedData(data: object): Promise<void>

  Replaces the current timeline state with serialized data and reinitializes rendering.

  Parameters

  • data: object

    Serialized timeline payload.

  Returns Promise<void>

  A promise that resolves after the timeline has been reloaded.

moveClipToLayer

• moveClipToLayer(clipId: string, newLayerId: string): Promise<void>

  Moves a clip from its current layer to another layer.

  Parameters

  • clipId: string

    Clip ID to move.

  • newLayerId: string

    Destination layer ID.

  Returns Promise<void>

  A promise that resolves after the move has completed.

pause

• pause(): void

  Pauses playback without changing the current playhead position.

  Returns void

  Nothing.

play

• play(): Promise<void>

  Starts timeline playback.

  Returns Promise<void>

  A promise that resolves after all layers have handled playback start.

postRender

• postRender(): void

  Runs post-render hooks for every layer after a frame has been presented.

  Returns void

  Nothing.

removeClip

• removeClip(clipId: string): boolean

  Parameters

  • clipId: string

  Returns boolean

removeLayer

• removeLayer(layerId: string): boolean

  Removes a layer and all of its clips.

  Parameters

  • layerId: string

    Layer ID to remove.

  Returns boolean

  true if the layer existed and was removed; otherwise false.

render

• render(options?: TimelineRenderOptions): Promise<void>

  Advances the timeline and renders one frame.

  Parameters

  • Optionaloptions: TimelineRenderOptions

    Optional render-loop behavior overrides.

  Returns Promise<void>

  A promise that resolves after the frame has been processed.

reset

• reset(): void

  Clears the current timeline state, destroys existing layers, and restarts the render loop with default playback settings.

  Returns void

  Nothing.

seek

• seek(value: number): void

  Moves the playhead to a specific timeline time.

  Parameters

  • value: number

    Target time, in seconds.

  Returns void

  Nothing.

serialize

• serialize(): {
      customData?: [string, unknown][];
      fitDuration: number;
      fps: number;
      layers: {
          clips: any[];
          customData?: [string, unknown][];
          id: string;
          muted?: boolean;
          name?: string;
          transitions: {
              endClipId: string;
              id: string;
              inDuration: number;
              outDuration: number;
              properties: [string, any][];
              provider: string;
              startClipId: string;
              transitionId: string;
          }[];
          visible?: boolean;
          volume?: number;
      }[];
      startTime: number;
      volume: number;
  }

  Serializes the timeline and all of its layers.

  Returns {
      customData?: [string, unknown][];
      fitDuration: number;
      fps: number;
      layers: {
          clips: any[];
          customData?: [string, unknown][];
          id: string;
          muted?: boolean;
          name?: string;
          transitions: {
              endClipId: string;
              id: string;
              inDuration: number;
              outDuration: number;
              properties: [string, any][];
              provider: string;
              startClipId: string;
              transitionId: string;
          }[];
          visible?: boolean;
          volume?: number;
      }[];
      startTime: number;
      volume: number;
  }

  The serialized timeline payload.

setAllCustomData

• setAllCustomData(data: Map<string, unknown>): void

  Replaces all custom timeline metadata with a copy of the provided map.

  Parameters

  • data: Map<string, unknown>

    Metadata entries to store.

  Returns void

  Nothing.

setCustomData

• setCustomData(key: string, value: unknown, overwrite?: boolean): boolean

  Stores an arbitrary metadata entry on the timeline instance.

  Parameters

  • key: string

    Metadata key.

  • value: unknown

    Metadata value.

  • overwrite: boolean = true

    Whether an existing value for the same key may be replaced.

  Returns boolean

  true if the value was stored; otherwise false when overwrite is disabled and the key already exists.

setFps

• setFps(fps: number): void

  Sets the timeline frame rate used for playback and frame alignment.

  Parameters

  • fps: number

    Frames per second to use.

  Returns void

  Nothing.

setSubtitles

• setSubtitles(subtitlesId: string, offset: number, clipIds?: string[]): void

  Assigns a subtitles asset to clips on the timeline.

  Parameters

  • subtitlesId: string

    Subtitles asset ID to apply.

  • offset: number

    Global subtitles offset in seconds.

  • OptionalclipIds: string[]

    Optional clip ID subset to update. When omitted, all clips are updated.

  Returns void

  Nothing.

setVolume

• setVolume(volume: number): void

  Sets the master timeline volume used by audio and video clips during playback.

  Parameters

  • volume: number

    Timeline volume multiplier.

  Returns void

  Nothing.

stop

• stop(): void

  Stops playback and resets the playhead to the start of the timeline.

  Returns void

  Nothing.

stopRenderingLoop

• stopRenderingLoop(): void

  Stops the animation-frame driven render loop without destroying timeline state.

  Returns void

  Nothing.

Staticdeserialize

• deserialize(data: object): Timeline

  Creates a timeline instance from serialized data.

  Parameters

  • data: object

    Serialized timeline payload.

  Returns Timeline

  The deserialized timeline.