Lottie Fills - Angular

Play a Lottie animation as the fill of a block, with the images and fonts that it references by URL.

A square page filled with an aerial photo of a coast, drawn by the Lottie fill at 1.5 seconds

6 mins

estimated time

A video fill plays a Lottie .json file or a dotLottie .lottie archive. The block shows the whole animation, and its layers stay out of reach. To edit the layers, import the Lottie as blocks instead. In the editor, an uploaded Lottie .json file becomes one video block.

import type { EditorPlugin, EditorPluginContext } from '@cesdk/cesdk-js';
import { isEngineError } from '@cesdk/cesdk-js';

import {
  BlurAssetSource,
  CaptionPresetsAssetSource,
  ImageColorsAssetSource,
  ColorPaletteAssetSource,
  CropPresetsAssetSource,
  DemoAssetSources,
  EffectsAssetSource,
  FiltersAssetSource,
  PagePresetsAssetSource,
  StickerAssetSource,
  TextAssetSource,
  TextComponentAssetSource,
  TypefaceAssetSource,
  UploadAssetSources,
  VectorShapeAssetSource
} from '@cesdk/cesdk-js/plugins';
import { VideoEditorConfig } from '@cesdk/core-configs-web/video-editor';
import packageJson from './package.json';

/**
 * CE.SDK Plugin: Lottie Fills Guide
 *
 * Demonstrates how to play a Lottie animation as the fill of a block:
 * - Writing a Lottie document that references an image by URL
 * - Setting the document as the file of a video fill
 * - Waiting until the Lottie and its image are loaded
 * - Handling a file that is not a Lottie
 * - Exporting a video of the animation
 */
class Example implements EditorPlugin {
  name = packageJson.name;

  version = packageJson.version;

  async initialize({ cesdk }: EditorPluginContext): Promise<void> {
    if (!cesdk) {
      throw new Error('CE.SDK instance is required for this plugin');
    }

    await cesdk.addPlugin(new VideoEditorConfig());

    // Add asset source plugins
    await cesdk.addPlugin(new BlurAssetSource());
    await cesdk.addPlugin(new CaptionPresetsAssetSource());
    await cesdk.addPlugin(new ImageColorsAssetSource());
    await cesdk.addPlugin(new ColorPaletteAssetSource());
    await cesdk.addPlugin(new CropPresetsAssetSource());
    await cesdk.addPlugin(
      new UploadAssetSources({
        include: [
          'ly.img.image.upload',
          'ly.img.video.upload',
          'ly.img.audio.upload'
        ]
      })
    );
    await cesdk.addPlugin(
      new DemoAssetSources({
        include: [
          'ly.img.templates.video.*',
          'ly.img.image.*',
          'ly.img.audio.*',
          'ly.img.video.*'
        ]
      })
    );
    await cesdk.addPlugin(new EffectsAssetSource());
    await cesdk.addPlugin(new FiltersAssetSource());
    await cesdk.addPlugin(
      new PagePresetsAssetSource({
        include: [
          'ly.img.page.presets.instagram.*',
          'ly.img.page.presets.facebook.*',
          'ly.img.page.presets.x.*',
          'ly.img.page.presets.linkedin.*',
          'ly.img.page.presets.pinterest.*',
          'ly.img.page.presets.tiktok.*',
          'ly.img.page.presets.youtube.*',
          'ly.img.page.presets.video.*'
        ]
      })
    );
    await cesdk.addPlugin(new StickerAssetSource());
    await cesdk.addPlugin(new TextAssetSource());
    await cesdk.addPlugin(new TextComponentAssetSource());
    await cesdk.addPlugin(new TypefaceAssetSource());
    await cesdk.addPlugin(new VectorShapeAssetSource());

    await cesdk.actions.run('scene.create', {
      mode: 'Video',
      layout: 'DepthStack',
      page: { width: 1000, height: 1000, unit: 'Pixel' }
    });

    const engine = cesdk.engine;
    const page = engine.block.findByType('page')[0]!;
    engine.block.setDuration(page, 3);

    // A 3 second Lottie at 30 frames per second. Its image layer fades in a
    // photo and zooms into it. The asset names the photo by an absolute URL.
    const lottie = {
      v: '5.7.0',
      fr: 30,
      ip: 0,
      op: 90,
      w: 1000,
      h: 1000,
      assets: [
        {
          id: 'photo',
          w: 2500,
          h: 1667,
          u: '',
          p: 'https://img.ly/static/ubq_samples/sample_1.jpg',
          e: 0
        }
      ],
      layers: [
        {
          ty: 2,
          refId: 'photo',
          ip: 0,
          op: 90,
          st: 0,
          ks: {
            a: { a: 0, k: [1250, 833] },
            p: { a: 0, k: [500, 500] },
            s: {
              a: 1,
              k: [
                { t: 0, s: [60, 60] },
                { t: 90, s: [80, 80] }
              ]
            },
            o: {
              a: 1,
              k: [
                { t: 0, s: [0] },
                { t: 30, s: [100] }
              ]
            }
          }
        }
      ]
    };

    // A buffer holds the document in memory and gives it a URI
    const lottieURI = engine.editor.createBuffer();
    const bytes = new TextEncoder().encode(JSON.stringify(lottie));
    engine.editor.setBufferData(lottieURI, 0, bytes);

    // A video fill plays the Lottie. Set a hosted .json or .lottie URL the same way.
    const block = engine.block.create('graphic');
    engine.block.setShape(block, engine.block.createShape('rect'));
    engine.block.setWidth(block, 1000);
    engine.block.setHeight(block, 1000);
    const fill = engine.block.createFill('video');
    engine.block.setString(fill, 'fill/video/fileURI', lottieURI);
    engine.block.setFill(block, fill);
    engine.block.appendChild(page, block);
    engine.block.setDuration(block, 3);

    // The load finishes when the Lottie and the images it references are loaded
    await engine.block.forceLoadAVResource(fill);
    console.log(engine.block.getAVResourceTotalDuration(fill)); // 3

    // A file that is not a Lottie or a video does not load
    const brokenURI = engine.editor.createBuffer();
    engine.editor.setBufferData(
      brokenURI,
      0,
      new TextEncoder().encode('not a Lottie')
    );
    const brokenFill = engine.block.createFill('video');
    engine.block.setString(brokenFill, 'fill/video/fileURI', brokenURI);
    try {
      await engine.block.forceLoadAVResource(brokenFill);
    } catch (error) {
      if (isEngineError(error)) {
        console.log(error.code); // 'EDITOR.RESOURCE_LOAD_FAILED'
      }
    }
    engine.block.destroy(brokenFill);
    engine.editor.destroyBuffer(brokenURI);

    // A video export draws every frame of the Lottie
    const exportVideo = async () => {
      const video = await engine.block.exportVideo(page, {
        mimeType: 'video/mp4'
      });
      await cesdk.utils.downloadFile(video, 'video/mp4');
    };

    cesdk.ui.setComponentOrder({ in: 'ly.img.navigation.bar' }, [
      'ly.img.undoRedo.navigationBar',
      'ly.img.spacer',
      {
        id: 'ly.img.action.navigationBar',
        onClick: exportVideo,
        key: 'export-video',
        label: 'Export Video',
        icon: '@imgly/Video',
        variant: 'plain',
        color: 'accent'
      }
    ]);

    // Show the photo after its fade-in
    engine.block.setPlaybackTime(page, 1.5);
  }
}

export default Example;

This guide covers how to give a Lottie document a URI, how to set it as a fill, how to wait for the Lottie and its references, which references the engine loads, how to export a video, and the errors to expect.

Creating the Scene#

The example loads the video editor configuration and creates a video scene with a 1000 × 1000 page. The page lasts 3 seconds, the length of the animation.

Writing a Lottie Document#

The example writes its Lottie in code, so it runs without a hosted file. The document runs for 90 frames at 30 frames per second. Its image layer fades in a photo and zooms into it. The image asset names the photo by an absolute URL.

// A 3 second Lottie at 30 frames per second. Its image layer fades in a
// photo and zooms into it. The asset names the photo by an absolute URL.
const lottie = {
  v: '5.7.0',
  fr: 30,
  ip: 0,
  op: 90,
  w: 1000,
  h: 1000,
  assets: [
    {
      id: 'photo',
      w: 2500,
      h: 1667,
      u: '',
      p: 'https://img.ly/static/ubq_samples/sample_1.jpg',
      e: 0
    }
  ],
  layers: [
    {
      ty: 2,
      refId: 'photo',
      ip: 0,
      op: 90,
      st: 0,
      ks: {
        a: { a: 0, k: [1250, 833] },
        p: { a: 0, k: [500, 500] },
        s: {
          a: 1,
          k: [
            { t: 0, s: [60, 60] },
            { t: 90, s: [80, 80] }
          ]
        },
        o: {
          a: 1,
          k: [
            { t: 0, s: [0] },
            { t: 30, s: [100] }
          ]
        }
      }
    }
  ]
};

Storing the Document in a Buffer#

engine.editor.createBuffer() returns a buffer:// URI, and engine.editor.setBufferData() writes the document into it. A buffer has no directory, so a document in a buffer names its images by absolute URL. The Buffers guide explains buffers in detail.

// A buffer holds the document in memory and gives it a URI
const lottieURI = engine.editor.createBuffer();
const bytes = new TextEncoder().encode(JSON.stringify(lottie));
engine.editor.setBufferData(lottieURI, 0, bytes);

Setting the Lottie as a Fill#

engine.block.createFill('video') creates the fill, and its fill/video/fileURI property takes the URI of the Lottie. For a hosted file, set its https URL the same way. engine.block.setFill() gives the fill to a graphic block.

// A video fill plays the Lottie. Set a hosted .json or .lottie URL the same way.
const block = engine.block.create('graphic');
engine.block.setShape(block, engine.block.createShape('rect'));
engine.block.setWidth(block, 1000);
engine.block.setHeight(block, 1000);
const fill = engine.block.createFill('video');
engine.block.setString(fill, 'fill/video/fileURI', lottieURI);
engine.block.setFill(block, fill);
engine.block.appendChild(page, block);
engine.block.setDuration(block, 3);

Loading the Lottie and Its References#

engine.block.forceLoadAVResource() finishes when the Lottie and every image and font that it references are loaded. engine.block.getAVResourceTotalDuration() then returns the duration in seconds, the frame count divided by the frame rate.

// The load finishes when the Lottie and the images it references are loaded
await engine.block.forceLoadAVResource(fill);
console.log(engine.block.getAVResourceTotalDuration(fill)); // 3

Referenced Images and Fonts#

A Lottie can reference files instead of embedding them. An image asset names its file with its u directory and its p file name. A font names its file in fonts.list[].fPath. An asset with e: 1 or a data: URI is embedded and loads with the document.

A relative reference resolves against the URL of the Lottie. In https://example.com/anims/intro.json, an asset with u: 'images/' and p: 'photo.png' loads https://example.com/anims/images/photo.png.

The engine loads these references:

http and https URLs
bundle:// URIs
relative references that stay in the directory of the Lottie

The engine refuses a path that starts with /, a .. that leaves the directory of the Lottie, a backslash and a buffer:// URI. The Lottie then draws without that image or font, and the engine logs a warning that names the reference. A reference that fails to load has the same result. The engine loads at most 256 different references of one Lottie. It draws without the others and logs a warning with their number. The export and the forced load wait for each reference before they finish. A URI resolver receives each reference after it resolves against the Lottie URL.

Handling Errors#

A file that is neither a Lottie nor a video does not load, and engine.block.forceLoadAVResource() rejects with EDITOR.RESOURCE_LOAD_FAILED. The example destroys the fill and its buffer afterwards.

// A file that is not a Lottie or a video does not load
const brokenURI = engine.editor.createBuffer();
engine.editor.setBufferData(
  brokenURI,
  0,
  new TextEncoder().encode('not a Lottie')
);
const brokenFill = engine.block.createFill('video');
engine.block.setString(brokenFill, 'fill/video/fileURI', brokenURI);
try {
  await engine.block.forceLoadAVResource(brokenFill);
} catch (error) {
  if (isEngineError(error)) {
    console.log(error.code); // 'EDITOR.RESOURCE_LOAD_FAILED'
  }
}
engine.block.destroy(brokenFill);
engine.editor.destroyBuffer(brokenURI);

Exporting a Video#

engine.block.exportVideo() renders every frame of the Lottie into an MP4 file. The example adds an Export Video button to the navigation bar that downloads the file.

// A video export draws every frame of the Lottie
const exportVideo = async () => {
  const video = await engine.block.exportVideo(page, {
    mimeType: 'video/mp4'
  });
  await cesdk.utils.downloadFile(video, 'video/mp4');
};

Troubleshooting#

An image or a font is missing: the engine logs a warning that names the reference. Check that the reference is an http, https or bundle:// URI, or a relative path inside the directory of the Lottie. A Lottie with more than 256 different references draws without the rest.
A document in a buffer draws without its images: a relative reference has no directory to resolve against. Name each image by an absolute URL.
A .lottie archive does not load: an archive must be a valid dotLottie file within the engine limits: at most 1,024 entries, 128 MiB uncompressed and 32 MiB for the animation JSON. Otherwise engine.block.forceLoadAVResource() rejects with SCENE.LOTTIE_ARCHIVE_INVALID, SCENE.LOTTIE_ARCHIVE_TOO_MANY_ENTRIES, SCENE.LOTTIE_ARCHIVE_TOO_LARGE or SCENE.LOTTIE_ARCHIVE_UNSAFE_PATH.

API Reference#

Method	Description
`editor.createBuffer()`	Create a buffer and return its URI
`editor.setBufferData(uri, offset, data)`	Write the Lottie document into the buffer
`editor.destroyBuffer(uri)`	Free a buffer
`block.createFill('video')`	Create a video fill
`block.setString(fill, 'fill/video/fileURI', uri)`	Set the Lottie file of the fill
`block.setFill(block, fill)`	Give the block the fill
`block.forceLoadAVResource(fill)`	Load the Lottie and its references
`block.getAVResourceTotalDuration(fill)`	Read the duration of the animation in seconds
`block.exportVideo(page, options)`	Export a video of the animation

Next Steps#

Import Lottie Animations: import the layers of a Lottie as editable blocks.
Video Fills: play videos as fills.
URI Resolver: redirect the URLs that the engine loads.