# DotLottie Class
API reference for the DotLottie class in dotlottie-io — load, mutate, query, and serialize a .lottie package.

# `DotLottie` Class

The core class representing a loaded or built `.lottie` package. All methods are synchronous.

**Import:**

```javascript
const { DotLottie } = require("@lottiefiles/dotlottie-io");
```

## Static methods

### `DotLottie.fromFile(path, password?)`

Load a `.lottie` file directly from a filesystem path.

- **Parameters:**
  - `path`: `string` — the path to the `.lottie` file.
  - `password?`: `string` — pass to open a password-protected archive.
- **Returns:** `DotLottie`
- **Example:**
  ```javascript
  const dl = DotLottie.fromFile("package.lottie");
  ```

### `DotLottie.fromBytes(data, password?)`

Load a `.lottie` file from raw bytes.

- **Parameters:**
  - `data`: `Buffer` — e.g. the result of `fs.readFileSync`.
  - `password?`: `string` — pass to decrypt a password-protected archive.
- **Returns:** `DotLottie`
- **Example:**
  ```javascript
  const dl = DotLottie.fromBytes(readFileSync("package.lottie"));
  ```

## Serialization

### `toBytes(password?)`

Serialize the package to a `.lottie` ZIP `Buffer`.

- **Parameters:**
  - `password?`: `string` — pass to produce an AES-256 encrypted archive.
- **Returns:** `Buffer`
- **Example:**
  ```javascript
  writeFileSync("output.lottie", dl.toBytes());
  ```

## Animations

### `addAnimation(id, jsonData, options?)`

Add an animation from Lottie JSON. Automatically extracts embedded base64 assets and rewrites their references.

- **Parameters:**
  - `id`: `string` — unique identifier for this animation.
  - `jsonData`: `Buffer | string` — the Lottie JSON.
  - `options?`: [`AnimationOptions`](/docs/tools/dotlottie-io/api/types#animationoptions)
- **Returns:** `void`

### `removeAnimation(id)`

- **Parameters:** `id`: `string`
- **Returns:** `void`
- **Throws:** if `id` doesn't exist.

### `getAnimationJson(id)`

- **Parameters:** `id`: `string`
- **Returns:** `string | null` — the raw Lottie JSON, or `null` if not found.

### `animationIds()`

- **Returns:** `string[]`

See [Managing Animations](/docs/tools/dotlottie-io/core-concepts/animations) for a walkthrough.

## Themes

### `addTheme(id, name, jsonData)`

- **Parameters:**
  - `id`: `string`
  - `name`: `string | null` — optional display name.
  - `jsonData`: `Buffer | string`
- **Returns:** `void`

### `removeTheme(id)`

- **Returns:** `void`
- **Throws:** if `id` doesn't exist.

### `getThemeJson(id)`

- **Returns:** `string | null`

### `themeIds()`

- **Returns:** `string[]`

See [Managing Themes](/docs/tools/dotlottie-io/core-concepts/themes).

## State machines

### `addStateMachine(id, name, jsonData)`

- **Parameters:**
  - `id`: `string`
  - `name`: `string | null` — optional display name.
  - `jsonData`: `Buffer | string`
- **Returns:** `void`

### `removeStateMachine(id)`

- **Returns:** `void`
- **Throws:** if `id` doesn't exist.

### `getStateMachineJson(id)`

- **Returns:** `string | null`

### `stateMachineIds()`

- **Returns:** `string[]`

See [Managing State Machines](/docs/tools/dotlottie-io/core-concepts/state-machines).

## Assets

All `add*` methods return the **actual filename stored**, which may differ from the requested one on a collision — see [filename deduplication](/docs/tools/dotlottie-io/core-concepts/assets#filename-deduplication).

### `addImage(filename, data)` / `getImage(filename)` / `imageFilenames()`

- `addImage(filename: string, data: Buffer): string`
- `getImage(filename: string): Buffer | null`
- `imageFilenames(): string[]`

### `addFont(filename, data)` / `getFont(filename)` / `fontFilenames()`

- `addFont(filename: string, data: Buffer): string`
- `getFont(filename: string): Buffer | null`
- `fontFilenames(): string[]`

### `addAudio(filename, data)` / `getAudio(filename)` / `audioFilenames()`

- `addAudio(filename: string, data: Buffer): string`
- `getAudio(filename: string): Buffer | null`
- `audioFilenames(): string[]`
- **Throws:** `InvalidAudioFormat` if `filename` isn't `.mp3`.

**Example:**

```javascript
const storedName = dl.addImage("logo.png", readFileSync("logo.png"));
console.log(storedName); // 'logo.png' (or 'logo_1.png' if that name was taken)
```

See [Managing Assets](/docs/tools/dotlottie-io/core-concepts/assets).

## Query methods

### `animationsUsingTheme(themeId)`

- **Returns:** `string[]` — animation IDs referencing the given theme.

### `animationsUsedByStateMachine(stateMachineId)`

- **Returns:** `string[]` — unique animation IDs referenced by the state machine's `PlaybackState` entries.

### `assetReferences(animationId)`

- **Returns:** [`AssetReferences`](/docs/tools/dotlottie-io/api/types#assetreferences) — `{ images: string[], fonts: string[], audio: string[] }`.

### `animationsUsingAsset(filename)`

- **Returns:** `string[]` — animation IDs that reference the given asset filename.

See [Querying Relationships](/docs/tools/dotlottie-io/guides/querying-relationships) for worked examples.

## Manifest

### `getManifestJson()`

- **Returns:** `string` — the full manifest as JSON.

### `setInitial(animationId?, stateMachineId?)`

- **Parameters:**
  - `animationId?`: `string | null`
  - `stateMachineId?`: `string | null`
- **Returns:** `void`
- Pass `null` to clear either field.

### `getInitialAnimationId()`

- **Returns:** `string | null`

### `getInitialAnimation()`

- **Returns:** `string | null` — the raw Lottie JSON of the initial animation.

See [The Manifest](/docs/tools/dotlottie-io/core-concepts/manifest).

## Complete example

```javascript
const { readFileSync, writeFileSync } = require("node:fs");
const { DotLottie, DotLottieBuilder } = require("@lottiefiles/dotlottie-io");

// Build a package from scratch
const builder = new DotLottieBuilder();
builder.generator("my-tool");
builder.addAnimation("hero", JSON.stringify(myLottieJson));
builder.addTheme("dark", "Dark Theme", JSON.stringify({ rules: [] }));
const dl = builder.build();

// Add assets
const storedName = dl.addImage("logo.png", readFileSync("logo.png"));
dl.addAudio("click.mp3", readFileSync("click.mp3"));

// Save to disk
writeFileSync("output.lottie", dl.toBytes());

// Load back and inspect
const loaded = DotLottie.fromFile("output.lottie");
console.log(loaded.animationIds()); // ['hero']
console.log(loaded.imageFilenames()); // ['logo.png']

const imgData = loaded.getImage("logo.png"); // Buffer
```

Next up: [`DotLottieBuilder` Class](/docs/tools/dotlottie-io/api/dotlottie-builder-class)