Class Library

constructor

• new Library(): Library

  Creates an empty project library.

  Returns Library

builtInEffects

effects

filters

media

subtitles

transitions

addEffect

• addEffect(options: EffectDataOptions): Promise<string>

  Registers a custom effect definition in the library.

  Parameters

  • options: EffectDataOptions

    Effect definition options.

  Returns Promise<string>

  A promise that resolves to the created effect ID.

addFilter

• addFilter(options: FilterDataOptions): Promise<string>

  Registers a filter definition in the library.

  Parameters

  • options: FilterDataOptions

    Filter definition options.

  Returns Promise<string>

  A promise that resolves to the created filter ID.

addMedia

• addMedia(
      source: string | Uint8Array<ArrayBufferLike> | File,
      mimeType?: string,
      filename?: string,
      id?: string,
      forcedHash?: string,
  ): Promise<null | string>

  Imports media into the library from a file, URL, or raw bytes.

  Parameters

  • source: string | Uint8Array<ArrayBufferLike> | File

    Media source to import.

  • OptionalmimeType: string

    Optional MIME type override for byte or URL inputs.

  • Optionalfilename: string

    Optional filename override.

  • Optionalid: string

    Optional ID override.

  • OptionalforcedHash: string

  Returns Promise<null | string>

  A promise that resolves to the created media ID, or null if creation fails before an ID is available.

addSerializedMedia

• addSerializedMedia(data: any): Promise<string>

  Restores a serialized media asset into the library.

  Parameters

  • data: any

    Serialized media payload.

  Returns Promise<string>

  A promise that resolves to the restored media ID.

addSubtitles

• addSubtitles(subtitles: Subtitles): string

  Adds a subtitles asset to the library.

  Parameters

  • subtitles: Subtitles

    Subtitles asset to add.

  Returns string

  The subtitles asset ID.

addTransition

• addTransition(options: TransitionDataOptions): Promise<string>

  Registers a transition definition in the library.

  Parameters

  • options: TransitionDataOptions

    Transition definition options.

  Returns Promise<string>

  A promise that resolves to the created transition ID.

applyMediaFitStrategies

• applyMediaFitStrategies(): Promise<void>

  Refits clips whose media loaded with different dimensions/duration than the project was serialized with — the "injected media" template flow: the host swaps a media's permanentUrl in the serialized payload (e.g. a user logo replacing a template logo), and the freshly loaded asset no longer matches the clip styles/trims that were laid out for the old asset.

  Must run after both the library (media loaded, dimensions known) and the timeline (clips initialized) are ready; the engine calls it at the end of initialization.

  Detection per media (backwards compatible with projects that predate media size serialization):

  1. Preferred: the serialized media width/height (captured before load() overwrote them) differ from the loaded ones.
  2. Fallback: the previous media size is derived from the deserialized clip styles (raw size + crop); it is only trusted when every clip of the media agrees on it.

  When a change is detected, visual clips are refit through the same updateMediaData path as replaceMedia, honoring each clip's own fitStrategy first, then mediaData.fitStrategy (fitStyle default FitStyleEnum.MATCH_SCALE, toCrop default true). Timed clips additionally get their right trim adjusted so the trimmed timeline duration stays what the project intended, mirroring the replaceMedia trim behavior.

  Returns Promise<void>

  A promise that resolves after all media have been processed.

clearAllCustomData

• clearAllCustomData(): void

  Removes all custom metadata stored on the library.

  Returns void

  Nothing.

createBuiltInEffects

• createBuiltInEffects(): Promise<void>

  Creates and initializes the built-in effect definitions exposed by the SDK.

  Returns Promise<void>

  A promise that resolves after all built-in effects have been registered.

createFilmstripWorker

• createFilmstripWorker(mediaId: string): Promise<void>

  Queues filmstrip extraction for a media asset.

  Parameters

  • mediaId: string

    Media asset ID to process.

  Returns Promise<void>

  A promise that resolves after the request has been queued.

deleteMedia

• deleteMedia(id: string): Promise<void>

  Deletes a media asset and removes any clips that depend on it.

  Parameters

  • id: string

    Media asset ID to delete.

  Returns Promise<void>

  A promise that resolves after deletion completes.

destroy

• destroy(): Promise<void>

  Destroys active background workers and releases all media assets.

  Returns Promise<void>

  A promise that resolves after teardown completes.

extractAudioFromMedia

• extractAudioFromMedia(
      mediaId: string,
      audioTrackIndex?: number,
  ): Promise<null | string>

  Extracts an audio track from a video media asset and imports it back into the library.

  Parameters

  • mediaId: string

    Video media asset ID.

  • audioTrackIndex: number = 0

    Audio stream index to extract.

  Returns Promise<null | string>

  A promise that resolves to the new audio media ID, or null if extraction fails.

getAllCustomData

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

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

  Returns undefined | Map<string, unknown>

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

getAllEffectIds

• getAllEffectIds(): string[]

  Returns all available effect IDs, including registered custom effects and built-in effects.

  Returns string[]

  The combined effect ID list.

getBuiltInEffectIds

• getBuiltInEffectIds(): string[]

  Returns the IDs of built-in effects shipped with the SDK.

  Returns string[]

  The built-in effect IDs.

getCustomData

• getCustomData(key: string): unknown

  Returns a previously stored library metadata value.

  Parameters

  • key: string

    Metadata key to look up.

  Returns unknown

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

getEffectById

• getEffectById(id: string): undefined | EffectData

  Returns an effect definition by ID, including built-in effects.

  Parameters

  • id: string

    Effect definition ID.

  Returns undefined | EffectData

  The matching effect definition, or undefined if not found.

getFilterById

• getFilterById(id: string): undefined | FilterData

  Returns a filter definition by ID.

  Parameters

  • id: string

    Filter definition ID.

  Returns undefined | FilterData

  The matching filter definition, or undefined if not found.

getFilterIds

• getFilterIds(): string[]

  Returns the IDs of all registered filters.

  Returns string[]

  The registered filter IDs.

getMediaById

• getMediaById(id: string): undefined | MediaData

  Returns a media asset by its library ID.

  Parameters

  • id: string

    Media asset ID to look up.

  Returns undefined | MediaData

  The matching media asset, or undefined if not found.

getRegisteredEffectIds

• getRegisteredEffectIds(): string[]

  Returns the IDs of custom effects registered in this library instance.

  Returns string[]

  The registered custom effect IDs.

getSubtitlesById

• getSubtitlesById(id: string): undefined | Subtitles

  Returns a subtitles asset by ID.

  Parameters

  • id: string

    Subtitles asset ID.

  Returns undefined | Subtitles

  The matching subtitles asset, or undefined if not found.

getSubtitlesIds

• getSubtitlesIds(): string[]

  Returns the IDs of all subtitles assets in the library.

  Returns string[]

  The subtitles asset IDs.

getTransitionById

• getTransitionById(id: string): undefined | TransitionData

  Returns a transition definition by ID.

  Parameters

  • id: string

    Transition definition ID.

  Returns undefined | TransitionData

  The matching transition definition, or undefined if not found.

getTransitionIds

• getTransitionIds(): string[]

  Returns the IDs of all registered transitions.

  Returns string[]

  The registered transition IDs.

hasCustomData

• hasCustomData(key: string): boolean

  Indicates whether the library 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.

hasLoadingMedia

• hasLoadingMedia(): boolean

  Indicates whether any media load is still in progress (status not yet settled to READY/ERROR/DESTROYED). Unlike isProcessing, a pending background hash does not count.

  Returns boolean

  true while any media is loading.

hasPendingMedia

• hasPendingMedia(): boolean

  Indicates whether any media is still in progress: loading, transcoding, or waiting for its (background) hash. Media in the ERROR state does not count — errors are final, not pending.

  Returns boolean

  true while any media operation is pending.

init

• init(): Promise<void>

  Initializes all library assets and built-in effect definitions.

  Returns Promise<void>

  A promise that resolves after the library is ready for use.

isAllMediaRestorable

• isAllMediaRestorable(): Promise<boolean>

  Verifies that every ready media payload is restorable: its hash is present in at least one active storage provider, which is what project restore needs (StorageController::getMedia returns the first provider hit). Weaker than isAllMediaSynced — some providers may still be missing payloads.

  Returns false while any media is still pending (in progress is never skipped) or when a ready media's hash is missing from every readable active provider. Providers whose stored list cannot be read are skipped, but if none can be read the result is false (unverifiable is not restorable). Media in the ERROR state does not block the result — errors are final. With no active providers this resolves to true.

  Returns Promise<boolean>

  A promise that resolves to true when every media is restorable from storage.

isAllMediaSynced

• isAllMediaSynced(): Promise<boolean>

  Verifies against the active storage providers that every ready media payload is fully persisted, so hosts can check it is safe to leave the editor.

  Strict semantic: every active provider must have every ready media hash (syncAllMedia stores into each provider individually). Returns false while any media is still pending (in progress is never skipped), when any ready media's hash is missing from any active provider (run syncAllMedia), or when a provider's stored list cannot be read (unverifiable is not synced). Media in the ERROR state (failed load or failed hash) does not block the result — errors are final. With no active providers this resolves to true (there is nothing to sync to). For the weaker "can the project load back" check see isAllMediaRestorable.

  Returns Promise<boolean>

  A promise that resolves to true when all media is synced to all active providers.

isProcessing

• isProcessing(): boolean

  Indicates whether any media asset is still loading, transcoding, or processing.

  A media that is READY but still waiting for its background hash (see Settings::setMediaBackgroundHashing) also counts as processing, so serialization (Engine::isSafeToSerialize) waits for hashes and never persists a media without its storage-restore key.

  Returns boolean

  true if any media item is still processing; otherwise false.

probeMediaData

• probeMediaData(
      file: string | Uint8Array<ArrayBufferLike> | File,
  ): Promise<null | MediaInfo>

  Reads media metadata without adding the media to the library.

  Parameters

  • file: string | Uint8Array<ArrayBufferLike> | File

    Media source to probe.

  Returns Promise<null | MediaInfo>

  A promise that resolves to media metadata, or null if probing fails.

removeEffect

• removeEffect(id: string): void

  Removes a custom effect definition from the library.

  Parameters

  • id: string

    Effect definition ID to remove.

  Returns void

  Nothing.

removeFilter

• removeFilter(id: string): void

  Removes a filter definition from the library.

  Parameters

  • id: string

    Filter definition ID to remove.

  Returns void

  Nothing.

removeSubtitles

• removeSubtitles(id: string): void

  Removes a subtitles asset from the library and deletes dependent timeline clips.

  Parameters

  • id: string

    Subtitles asset ID to remove.

  Returns void

  Nothing.

removeTransition

• removeTransition(id: string): void

  Removes a transition definition from the library.

  Parameters

  • id: string

    Transition definition ID to remove.

  Returns void

  Nothing.

removeUnusedAssets

• removeUnusedAssets(): Promise<void>

  Removes unused media, subtitles, effects, filters, and transitions from the library.

  Returns Promise<void>

  A promise that resolves after all removable assets have been processed.

removeUnusedEffects

• removeUnusedEffects(): void

  Removes custom effects that are not referenced by any clip on the timeline.

  Returns void

  Nothing.

removeUnusedFilters

• removeUnusedFilters(): void

  Removes filters that are not referenced by any clip on the timeline.

  Returns void

  Nothing.

removeUnusedMedia

• removeUnusedMedia(): Promise<void>

  Removes media assets that are not referenced by any clip on the timeline.

  Returns Promise<void>

  A promise that resolves after all unused media items have been deleted.

removeUnusedSubtitles

• removeUnusedSubtitles(): void

  Removes subtitles assets that are not referenced by any clip on the timeline.

  Returns void

  Nothing.

removeUnusedTransitions

• removeUnusedTransitions(): void

  Removes transitions that are not referenced by any layer on the timeline.

  Returns void

  Nothing.

replaceMedia

• replaceMedia(
      id: string,
      file: string | Uint8Array<ArrayBufferLike> | File,
      replaceOptions?: ReplaceMediaOptions,
  ): Promise<boolean>

  Replaces an existing media asset with new source content while preserving the media ID.

  Parameters

  • id: string

    Media asset ID to replace.

  • file: string | Uint8Array<ArrayBufferLike> | File

    Replacement media source.

  • OptionalreplaceOptions: ReplaceMediaOptions

    Optional replacement behavior.

  Returns Promise<boolean>

  A promise that resolves to true if replacement succeeds.

replaceSerializedMedia

• replaceSerializedMedia(data: any): Promise<boolean>

  Replaces an existing media asset with serialized media data.

  Parameters

  • data: any

    Serialized replacement media payload.

  Returns Promise<boolean>

  A promise that resolves to true if replacement succeeds.

serialize

• serialize(): {
      customData?: [string, unknown][];
      effects: {
          autoFit?: boolean;
          blendMode?: NORMAL | ADD | SCREEN | MULTIPLY;
          fragmentSrc: string;
          id: string;
          inputTextures?: {
              mipmap?: OFF | ON;
              name: string;
              scaleMode?: NEAREST | LINEAR;
              url: string;
              wrapMode?: CLAMP | REPEAT | MIRRORED_REPEAT;
          }[];
          name: string;
          noTransform?: boolean;
          padding?: number;
          properties: {
              defaultValue: Required<any>;
              description?: string;
              initOnly?: boolean;
              label?: string;
              max?: number | number[];
              min?: number | number[];
              name: string;
              step?: number | number[];
              type: PropertyDescriptionTypeEnum;
          }[];
          provider: string;
      }[];
      filters: { id: string; lutUrl: string; name: string; provider: string }[];
      media: {
          customData?: [string, unknown][];
          duration?: number;
          filename: string;
          fitStrategy?: {
              fitStyle?: ORIGINAL | MATCH_SCALE | OUTSIDE | INSIDE | MATCH_SIZE;
              toCrop?: boolean;
          };
          hash?: string;
          height?: number;
          id: string;
          mimeType?: string;
          name?: string;
          permanentUrl?: string;
          placeholderClipIds?: string[];
          type: string;
          width?: number;
      }[];
      subtitles: {
          duration: number;
          id: string;
          language: string;
          textBlocks: {
              duration: number;
              text: string;
              time: number;
              wordTimings?: number[];
          }[];
      }[];
      transitions: {
          id: string;
          inputTextures?: {
              mipmap?: OFF
              | ON;
              name: string;
              scaleMode?: NEAREST | LINEAR;
              url: string;
              wrapMode?: CLAMP | REPEAT | MIRRORED_REPEAT;
          }[];
          name: string;
          properties: {
              defaultValue: Required<any>;
              description?: string;
              initOnly?: boolean;
              label?: string;
              max?: number | number[];
              min?: number | number[];
              name: string;
              step?: number | number[];
              type: PropertyDescriptionTypeEnum;
          }[];
          provider: string;
          transitionSrc: string;
      }[];
  }

  Serializes the library and all serializable assets it owns.

  Returns {
      customData?: [string, unknown][];
      effects: {
          autoFit?: boolean;
          blendMode?: NORMAL | ADD | SCREEN | MULTIPLY;
          fragmentSrc: string;
          id: string;
          inputTextures?: {
              mipmap?: OFF | ON;
              name: string;
              scaleMode?: NEAREST | LINEAR;
              url: string;
              wrapMode?: CLAMP | REPEAT | MIRRORED_REPEAT;
          }[];
          name: string;
          noTransform?: boolean;
          padding?: number;
          properties: {
              defaultValue: Required<any>;
              description?: string;
              initOnly?: boolean;
              label?: string;
              max?: number | number[];
              min?: number | number[];
              name: string;
              step?: number | number[];
              type: PropertyDescriptionTypeEnum;
          }[];
          provider: string;
      }[];
      filters: { id: string; lutUrl: string; name: string; provider: string }[];
      media: {
          customData?: [string, unknown][];
          duration?: number;
          filename: string;
          fitStrategy?: {
              fitStyle?: ORIGINAL | MATCH_SCALE | OUTSIDE | INSIDE | MATCH_SIZE;
              toCrop?: boolean;
          };
          hash?: string;
          height?: number;
          id: string;
          mimeType?: string;
          name?: string;
          permanentUrl?: string;
          placeholderClipIds?: string[];
          type: string;
          width?: number;
      }[];
      subtitles: {
          duration: number;
          id: string;
          language: string;
          textBlocks: {
              duration: number;
              text: string;
              time: number;
              wordTimings?: number[];
          }[];
      }[];
      transitions: {
          id: string;
          inputTextures?: {
              mipmap?: OFF
              | ON;
              name: string;
              scaleMode?: NEAREST | LINEAR;
              url: string;
              wrapMode?: CLAMP | REPEAT | MIRRORED_REPEAT;
          }[];
          name: string;
          properties: {
              defaultValue: Required<any>;
              description?: string;
              initOnly?: boolean;
              label?: string;
              max?: number | number[];
              min?: number | number[];
              name: string;
              step?: number | number[];
              type: PropertyDescriptionTypeEnum;
          }[];
          provider: string;
          transitionSrc: string;
      }[];
  }

  The serialized library payload.

setAllCustomData

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

  Replaces all custom library 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 library 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.

storeAllMedia

• storeAllMedia(): Promise<void>

  Persists every library media item through the configured storage controller.

  Returns Promise<void>

  A promise that resolves after all store requests have settled.

syncAllMedia

• syncAllMedia(): Promise<void>

  Synchronizes stored media across all configured storage providers.

  Returns Promise<void>

  A promise that resolves after synchronization completes.

waitForMediaLoadsToSettle

• waitForMediaLoadsToSettle(checkIntervalMS?: number): Promise<void>

  Resolves once no media load is in progress (see hasLoadingMedia). Used to defer derived-data extraction (samples/filmstrip) while an import batch is still loading.

  Parameters

  • checkIntervalMS: number = 100

    Poll interval in milliseconds.

  Returns Promise<void>

  A promise that resolves when all media loads have settled.

Staticdeserialize

• deserialize(data: object): Library

  Creates a library instance from serialized data.

  Parameters

  • data: object

    Serialized library payload.

  Returns Library

  The deserialized library.