Manage Assets (Images & Audio)

Lottie animations often rely on external assets like images and audio files. dotlottie-js handles the bundling of these assets into the .lottie file primarily through the animations you add and the build() process.

How Assets are Handled

In dotlottie-js, you typically do not explicitly add individual image or audio files directly to the DotLottie instance. Instead, asset management works as follows:

Define Assets in Lottie JSON: Ensure the Lottie JSON data for your animations correctly defines the assets it uses within its assets array.
- For images, this typically involves an entry with id, w, h, u (path, often empty for embedded), and p (filename or Base64 data).
- For audio, similar entries exist, identified by specific properties (like extra.audioparams).
- Crucially, if embedding assets, the p property should contain the Base64 encoded data (e.g., data:image/png;base64,...) or the filename that corresponds to an asset that will be discovered.
Add Animation: Add the Lottie animation(s) containing these asset definitions to your DotLottie instance using dotlottie.addAnimation({ id: '...', data: yourLottieJsonWithAssets }) or dotlottie.addAnimation({ id: '...', url: '...' }).
Build Process: When you call await dotlottie.build(), the library automatically:
- Discovers Assets: Scans the assets arrays of all added animations.
- Extracts Data: If assets are embedded (Base64 in p), it extracts the data.
- Bundles Assets: Writes the extracted or discovered asset data into appropriate directories within the .lottie archive (e.g., images/, audio/). It assigns filenames based on the asset definitions.
- Updates Lottie JSON: Modifies the u (path) and p (filename) properties within the Lottie JSON files inside the archive to correctly reference the bundled asset paths (e.g., u: 'images/', p: 'image_1.png').
- De-duplicates (Optional): If enableDuplicateImageOptimization: true was set in the constructor, it attempts to identify and store identical image assets only once.

In summary: Asset management is primarily implicit. You provide animations with correctly defined assets, and build() handles the bundling and linking.

Retrieving Bundled Assets

After loading a .lottie file (fromURL, fromArrayBuffer) or after calling build() on a new instance, you can access the discovered and bundled assets.

Retrieving All Images: `dotlottie.getImages()`

Returns an array of objects, each representing a bundled image asset.

// Assuming 'dotlottie' is a loaded or built instance
const allImages = dotlottie.getImages();
console.log(`Found ${allImages.length} images.`);

for (const image of allImages) {
  console.log(`Image ID: ${image.id}, FileName: ${image.fileName}`);

  // Access image data (async methods)
  try {
    // Get as ArrayBuffer
    // const arrayBuffer = await image.toArrayBuffer();
    // console.log(` ArrayBuffer size: ${arrayBuffer.byteLength}`);
    // Get as Base64 string
    // const base64 = await image.toBase64();
    // console.log(` Base64 preview: ${base64.substring(0, 60)}...`);
    // Get as Blob (Browser only)
    // const blob = await image.toBlob();
    // console.log(` Blob size: ${blob.size}, type: ${blob.type}`);
    // const objectUrl = URL.createObjectURL(blob); // Create URL for <img> src
    // console.log(` Object URL: ${objectUrl}`);
    // URL.revokeObjectURL(objectUrl); // Clean up later
  } catch (error) {
    console.error(`Error getting data for image ${image.id}:`, error);
  }
}

Each object representing an image in the returned array provides access to:

id: The unique ID used in Lottie JSON assets.
fileName: The filename within the .lottie archive.
Methods to retrieve the image data asynchronously, such as toArrayBuffer(), toBase64(), and toBlob().

Retrieving All Audio: `dotlottie.getAudio()`

Returns an array of objects, each representing a bundled audio asset. Works identically to getImages().

const allAudio = dotlottie.getAudio();
console.log(`Found ${allAudio.length} audio assets.`);

for (const audio of allAudio) {
  console.log(`Audio ID: ${audio.id}, FileName: ${audio.fileName}`);
  // Use await audio.toArrayBuffer(), await audio.toBase64(), await audio.toBlob()
}

Each object representing an audio asset provides similar access to id, fileName, and data retrieval methods.

Finding Assets Used by a Specific Animation

To determine which assets belong to a particular animation, you need to:

Get the animation object (await dotlottie.getAnimation(animId)).
Get its Lottie JSON data (await animation.toJSON()).
Inspect the assets array within the Lottie JSON data. The id of assets listed there corresponds to the id of the objects returned by getImages() and getAudio().

async function findAnimationAssets(animationId) {
  // Get the animation object - needs await
  const animation = await dotlottie.getAnimation(animationId);
  if (!animation) {
    console.log(`Animation ${animationId} not found.`);
    return;
  }

  const lottieJson = await animation.toJSON(); // Get the Lottie JSON data

  if (!lottieJson.assets || lottieJson.assets.length === 0) {
    console.log(`Animation ${animationId} has no assets defined.`);
    return;
  }

  const imageAssets = dotlottie.getImages();
  const audioAssets = dotlottie.getAudio();

  console.log(`Assets used by animation ${animationId}:`);
  lottieJson.assets.forEach((assetDef) => {
    // Check if it's an image asset (has w, h)
    if (typeof assetDef.w === "number" && typeof assetDef.h === "number") {
      const foundImage = imageAssets.find((img) => img.id === assetDef.id);
      if (foundImage) {
        console.log(` - Image: ID=${foundImage.id}, FileName=${foundImage.fileName}`);
      }
    }
    // Add similar check for audio assets if identifiable (e.g., by filename extension or specific properties)
    // Example check based on structure often seen with audio assets:
    else if (assetDef.extra && assetDef.extra.audioparams) {
      const foundAudio = audioAssets.find((aud) => aud.id === assetDef.id);
      if (foundAudio) {
        console.log(` - Audio: ID=${foundAudio.id}, FileName=${foundAudio.fileName}`);
      }
    }
  });
}

// findAnimationAssets('animation_1');

Next up: Managing Themes

Manage Assets