Managing Assets

Images, fonts, and audio are stored as raw binary files inside the .lottie archive. dotlottie-io exposes an identical three-method pattern for each asset type: add*, get*, and *Filenames.

dotlottie.addImage(filename, data); // Buffer → returns stored filename (string)
dotlottie.getImage(filename); // → Buffer | null
dotlottie.imageFilenames(); // → string[]

dotlottie.addFont(filename, data);
dotlottie.getFont(filename);
dotlottie.fontFilenames();

dotlottie.addAudio(filename, data);
dotlottie.getAudio(filename);
dotlottie.audioFilenames();

Two ways assets end up in a package

1. Implicitly, via addAnimation — assets embedded as base64 in the Lottie JSON are extracted automatically.

2. Explicitly, via addImage/addFont/addAudio — attach a standalone asset file directly, independent of any single animation's embedded data.

Audio format restriction

Only .mp3 is accepted for audio. Calling addAudio with any other extension throws InvalidAudioFormat.

Filename deduplication

Asset filenames must be unique within the package. Rather than throwing on a collision, add* methods rename the incoming asset and return the actual stored name:

const first = dl.addImage("logo.png", data); // → 'logo.png'
const second = dl.addImage("logo.png", data); // → 'logo_1.png'
const third = dl.addImage("logo.png", data); // → 'logo_2.png'

The rename pattern is {stem}_{n}.{ext}, incrementing n until a free name is found. Always use the returned string — not the name you passed in — as the key for later getImage/getFont/getAudio calls.

This same renaming logic is what MergeStrategy.Rename uses when merging packages, and what the automatic extraction in addAnimation uses for embedded assets.

Next up: Managing Themes