Standalone Utilities API

This section details standalone utility functions exported by dotlottie-js that provide useful, specific functionality.

`toDotLottieV1()`

Converts a V2 dotLottie file (ArrayBuffer) into a DotLottieV1 instance. This is useful for exporting or working with the older V1 format.

Function Signature (Conceptual):

async function toDotLottieV1(arrayBufferV2: ArrayBuffer): Promise<DotLottieV1>;

Import Path:

Check library exports, often included with the main package or a V1-specific entry point.

import { toDotLottieV1 } from "@dotlottie/dotlottie-js";
// Or potentially:
// import { toDotLottieV1 } from '@dotlottie/dotlottie-js/v1';

Parameters:

arrayBufferV2 (ArrayBuffer, required): An ArrayBuffer containing the data of a V2 .lottie file.

Returns:

Promise<DotLottieV1>: A promise that resolves with a new DotLottieV1 instance containing the converted V1 data.

Example Usage:

import { toDotLottieV1, DotLottie } from "@dotlottie/dotlottie-js";

(async () => {
  // Assume we have a V2 instance or buffer
  const dotlottieV2 = new DotLottie();
  // ... add V2 content ...
  await dotlottieV2.build();
  const v2Buffer = await dotlottieV2.toArrayBuffer();

  try {
    // Convert the V2 buffer to a V1 instance
    const dotlottieV1 = await toDotLottieV1(v2Buffer);
    console.log("Converted to V1 instance successfully.");

    // Now work with the V1 instance
    // await dotlottieV1.build(); // Rebuild might be needed depending on internal state
    // await dotlottieV1.download("output_v1.lottie");
  } catch (error) {
    console.error("V2 to V1 conversion failed:", error);
  }
})();

Important Considerations:

Feature Loss: V2 features (themes, state machines) present in the V2 input buffer will be lost during conversion, as V1 does not support them.
Primary Use Case: Outputting V1 .lottie files for compatibility purposes.

`makeDotLottie()`

This utility function provides a flexible way to create either a V1 or V2 dotLottie instance.

Function Signature:

export function makeDotLottie<T extends "v1" | "v2">(
  version: T,
  options?: T extends "v1" ? DotLottieV1Options : DotLottieOptions
): T extends "v1" ? DotLottieV1 : DotLottie;

Import Path:

import { makeDotLottie } from "@dotlottie/dotlottie-js";

Parameters:

version: 'v1' | 'v2' - Specifies whether to create a V1 or V2 dotLottie instance.
options (optional):
- If version is 'v1': DotLottieV1Options - Options for the V1 instance (e.g., author, version).
- If version is 'v2': DotLottieOptions - Options for the V2 instance (e.g., generator, enableDuplicateImageOptimization).

Returns:

If version is 'v1': A new, empty DotLottieV1 instance.
If version is 'v2': A new, empty DotLottie (V2) instance.

Example Usage:

import { makeDotLottie } from "@dotlottie/dotlottie-js";

// Create a V1 instance using the utility
const dotLottieV1 = makeDotLottie("v1", {
  author: "LottieFiles",
  version: "1.0.0",
});
dotLottieV1.addAnimation({
  id: "v1_anim",
  data: {
    /* ... V1 animation data ... */
  },
});
console.log("V1 instance created:", dotLottieV1.author);

// Create a V2 instance using the utility
const dotLottieV2 = makeDotLottie("v2", {
  generator: "My Awesome Tool",
  enableDuplicateImageOptimization: true,
});
dotLottieV2.addAnimation({
  id: "v2_anim",
  data: {
    /* ... V2 animation data ... */
  },
});
console.log("V2 instance created with generator:", dotLottieV2.manifest.generator);

Relation to Constructors:

makeDotLottie('v1', options) is a functional alternative to new DotLottieV1(options).
makeDotLottie('v2', options) is a functional alternative to new DotLottie(options).

`getAudio()`

Extracts a single audio asset by filename from a .lottie buffer.

Function Signature (Conceptual for getAudio):

async function getAudio(dotLottie: Uint8Array, filename: string): Promise<string | undefined>;

Import Path: Standard import. Parameters:

dotLottie (Uint8Array).
filename (string, e.g., 'audio_0.mp3'). Returns: Promise<string | undefined> (Data URL or undefined).

`getThemes()`

Extracts all themes present in a .lottie buffer.

Function Signature:

export async function getThemes(
  dotLottie: Uint8Array,
  filter?: UnzipFileFilter // Optional filter function from fflate
): Promise<Record<string, Record<string, unknown>>>;

Import Path: Standard import. Parameters:

dotLottie: Uint8Array - The raw byte data of the .lottie file.
filter (optional): UnzipFileFilter - An optional filter function (from the fflate library) to apply during unzipping.

Returns: Promise<Record<string, Record<string, unknown>>> - A Promise resolving to an object where:

Keys are the Theme IDs (string).
Values are the corresponding Theme Data objects (Record<string, unknown>).

Example:

import { getThemes } from "@dotlottie/dotlottie-js";

async function exampleGetThemes(dotLottieBuffer) {
  try {
    const themesMap = await getThemes(dotLottieBuffer);
    console.log("Themes found:", Object.keys(themesMap));

    for (const themeId in themesMap) {
      console.log(`Theme ID: ${themeId}`);
      const themeData = themesMap[themeId];
      console.log("Theme Data:", themeData);
      // Example: Access a specific property if known
      // console.log('Background Color:', themeData['background.fill.color']);
    }
  } catch (error) {
    console.error("Error extracting themes:", error);
  }
}

`isAudioAsset()`

Checks if a given asset is an audio asset.

Function Signature:

function isAudioAsset(asset: Asset.Value): asset is Asset.Image;

Import Path: Standard import. Parameters: asset (Lottie asset object). Returns: boolean. (Note: The type predicate asset is Asset.Image is a known typing issue. This function correctly identifies audio assets by inspecting properties like p or u.)