# DotLottieReader Class
API reference for the DotLottieReader class in dotlottie-io — a lazy, read-only view over a .lottie archive.

# `DotLottieReader` Class

A lightweight, read-only view over a `.lottie` archive. Only the manifest is parsed on construction — every other entry is read on demand when you call a getter.

**Import:**

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

## Static constructors

### `DotLottieReader.open(path, password?)`

Open a `.lottie` file from a filesystem path. Only the manifest is read; the file handle stays open and getters seek directly to the requested entry without reading the whole file into memory.

- **Parameters:**
  - `path`: `string`
  - `password?`: `string` — pass to open a password-protected archive. Note: when a password is provided, the file is read fully into memory — the low-memory guarantee only applies to unencrypted archives.
- **Returns:** `DotLottieReader`
- **Availability:** Node.js only — there's no filesystem in the WASM build.

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

Load from a `Buffer`/`Uint8Array`. Only the manifest is parsed on construction; each getter re-reads the ZIP central directory and decompresses only the requested entry.

- **Parameters:**
  - `data`: `Buffer` (Node.js) or `Uint8Array` (Browser)
  - `password?`: `string` — pass to decrypt a password-protected archive.
- **Returns:** `DotLottieReader`
- **Availability:** Node.js and Browser.

## Manifest (no ZIP reads after construction)

```typescript
reader.getManifestJson(): string
reader.animationIds(): string[]
reader.themeIds(): string[]
reader.stateMachineIds(): string[]
```

These are served directly from the manifest parsed at construction time.

## On-demand entry getters

Each method reads exactly one ZIP entry and returns `null` if the entry isn't present.

```typescript
reader.getAnimationJson(id: string): string | null
reader.getThemeJson(id: string): string | null
reader.getStateMachineJson(id: string): string | null
reader.getImage(filename: string): Buffer | null
reader.getFont(filename: string): Buffer | null
reader.getAudio(filename: string): Buffer | null
```

Both v1 (`animations/`, `images/`, `audio/`) and v2 (`a/`, `i/`, `u/`) path layouts are supported transparently.

## Manifest helpers

```typescript
reader.getInitialAnimationId(): string | null
reader.getInitialAnimation(): string | null // reads one ZIP entry
```

## Query methods

```typescript
reader.animationsUsingTheme(themeId: string): string[]           // manifest only, no ZIP I/O
reader.animationsUsedByStateMachine(stateMachineId: string): string[]  // one ZIP entry
reader.assetReferences(animationId: string): AssetReferences     // one ZIP entry
reader.animationsUsingAsset(filename: string): string[]          // O(n) — reads every animation entry
```

If you need `animationsUsingAsset` repeatedly, load the file with [`DotLottie`](/docs/tools/dotlottie-io/api/dotlottie-class) instead, since it parses everything once up front.

## Example

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

// From a file path — file handle stays open, nothing else is read yet
const reader = DotLottieReader.open("package.lottie");
console.log(reader.animationIds()); // from manifest, free
console.log(reader.stateMachineIds()); // from manifest, free

// Only this entry is decompressed and returned
const animJson = reader.getAnimationJson("hero");
if (animJson) {
  console.log(JSON.parse(animJson).nm);
}

// From a buffer — useful when you already have the bytes in memory
const reader2 = DotLottieReader.fromBytes(readFileSync("package.lottie"));
const font = reader2.getFont("MyFont.ttf"); // Buffer | null
```

See [How to Read a .lottie File](/docs/tools/dotlottie-io/guides/reading-a-lottie-file) for guidance on when to reach for `DotLottieReader` instead of `DotLottie`.

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