# Standalone Utilities
API documentation for standalone utility functions in dotlottie-js, providing specific functionalities for dotLottie files.

# 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`](/docs/tools/dotlottie-js/reference/dotlottie-v1-class) instance. This is useful for exporting or working with the older V1 format.

**Function Signature (Conceptual):**

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

**Import Path:**

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

```javascript
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`](/docs/tools/dotlottie-js/reference/dotlottie-v1-class) instance containing the converted V1 data.

**Example Usage:**

```javascript
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](/docs/tools/dotlottie-js/how-to-guides/manage-themes), [state machines](/docs/tools/dotlottie-js/how-to-guides/manage-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:**

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

**Import Path:**

```javascript
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`](/docs/tools/dotlottie-js/reference/dotlottie-v1-class#constructor) - Options for the V1 instance (e.g., `author`, `version`).
  - If `version` is `'v2'`: [`DotLottieOptions`](/docs/tools/dotlottie-js/reference/dotlottie-class#constructor) - Options for the V2 instance (e.g., `generator`, `enableDuplicateImageOptimization`).

**Returns:**

- If `version` is `'v1'`: A new, empty [`DotLottieV1`](/docs/tools/dotlottie-js/reference/dotlottie-v1-class) instance.
- If `version` is `'v2'`: A new, empty [`DotLottie`](/docs/tools/dotlottie-js/reference/dotlottie-class) (V2) instance.

**Example Usage:**

```javascript
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`):**

```typescript
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:**

```typescript
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:**

```javascript
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:**

```typescript
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`.)