Search Docs
Loading...
Skip to content

Lottie Fills

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
GitHub

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, load a Lottie that the importer converted into blocks.

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 frame, and the errors to expect.

Creating the Scene#

The example creates a 1000 × 1000 page of 3 seconds, the length of the animation.

// A page of 3 seconds, the length of the animation
let scene = try engine.scene.create()
let page = try engine.block.create(.page)
try engine.block.setWidth(page, value: 1000)
try engine.block.setHeight(page, value: 1000)
try engine.block.appendChild(to: scene, child: page)
try engine.block.setDuration(page, duration: 3)

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.
private let lottieDocument = """
{
  "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:// URL, and engine.editor.setBufferData(url:offset:data:) 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 URL
let lottieURL = engine.editor.createBuffer()
try engine.editor.setBufferData(url: lottieURL, offset: 0, data: Data(lottieDocument.utf8))

Setting the Lottie as a Fill#

engine.block.createFill(.video) creates the fill, and engine.block.setURL(_:property:value:) sets its fill/video/fileURI property to 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.
let block = try engine.block.create(.graphic)
try engine.block.setShape(block, shape: engine.block.createShape(.rect))
try engine.block.setWidth(block, value: 1000)
try engine.block.setHeight(block, value: 1000)
let fill = try engine.block.createFill(.video)
try engine.block.setURL(fill, property: "fill/video/fileURI", value: lottieURL)
try engine.block.setFill(block, fill: fill)
try engine.block.appendChild(to: page, child: block)
try engine.block.setDuration(block, duration: 3)

Loading the Lottie and Its References#

engine.block.forceLoadAVResource(_:) returns 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
try await engine.block.forceLoadAVResource(fill)
let duration = try engine.block.getAVResourceTotalDuration(fill)
print(duration) // 3.0

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
  • a file:// path in the directory of a local Lottie file

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. 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. 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.

Exporting a Frame#

engine.block.setPlaybackTime() seeks the page to 1.5 seconds, after the fade-in. engine.block.export() exports that frame as a PNG image.

// Seek the page to 1.5 seconds and export that frame
try engine.block.setPlaybackTime(page, time: 1.5)
let pngData = try await engine.block.export(page, mimeType: .png)
print(!pngData.isEmpty) // true

Handling Errors#

A file that is neither a Lottie nor a video does not load, and engine.block.forceLoadAVResource() throws an EngineError whose catalogCode is .editorResourceLoadFailed. The example destroys the fill and its buffer afterwards.

// A file that is not a Lottie or a video does not load
let brokenURL = engine.editor.createBuffer()
try engine.editor.setBufferData(url: brokenURL, offset: 0, data: Data("not a Lottie".utf8))
let brokenFill = try engine.block.createFill(.video)
try engine.block.setURL(brokenFill, property: "fill/video/fileURI", value: brokenURL)
var errorCode: EngineErrorCode?
do {
  try await engine.block.forceLoadAVResource(brokenFill)
} catch let error as EngineError {
  errorCode = error.catalogCode
  print(errorCode == .editorResourceLoadFailed) // true
}
try engine.block.destroy(brokenFill)
try engine.editor.destroyBuffer(url: brokenURL)

Troubleshooting#

  • An image or a font is missing: 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(_:) throws an EngineError whose catalogCode is .sceneLottieArchiveInvalid, .sceneLottieArchiveTooManyEntries, .sceneLottieArchiveTooLarge or .sceneLottieArchiveUnsafePath.

API Reference#

Method Description
editor.createBuffer() Create a buffer and return its URL
editor.setBufferData(url:offset:data:) Write the Lottie document into the buffer
editor.destroyBuffer(url:) Free a buffer
block.createFill(.video) Create a video fill
block.setURL(_:property:value:) Set the Lottie file of the fill
block.setFill(_:fill:) Give the block the fill
block.forceLoadAVResource(_:) Load the Lottie and its references
block.getAVResourceTotalDuration(_:) Read the duration of the animation in seconds
block.setPlaybackTime(_:time:) Seek the page
block.export(_:mimeType:) Export a frame

Next Steps#