Import Lottie Animations

import android.net.Uri
import android.util.Log
import ly.img.engine.Color
import ly.img.engine.DesignBlock
import ly.img.engine.Engine
import ly.img.engine.MimeType
import ly.img.engine.SceneMarker
import java.nio.ByteBuffer

private const val TAG = "ImportLottie"

data class ImportLottie(
    val groups: List<DesignBlock>,
    val layerNames: List<String>,
    val ringAnimatedProperties: List<String>,
    val brandColor: Color,
    val markers: List<SceneMarker>,
    val previewPng: ByteBuffer,
)

// The archive URI comes from the caller, for example the badge.imgly that the Node.js example of
// this guide saves, copied to a file.
suspend fun importLottie(
    engine: Engine,
    archiveUri: Uri,
): ImportLottie {
    // overrideEditorConfig = true also loads the variables that the importer created for the slots.
    engine.scene.load(
        sceneUri = archiveUri,
        overrideEditorConfig = true,
        waitForResources = true,
    )

    // Each import is one group on the page. Its blocks carry the names of the Lottie layers.
    val page = engine.scene.getPages().first()
    val groups = engine.block.getChildren(page)
    val layerNames = engine.block.getChildren(groups.first()).map { engine.block.getName(it) }
    Log.i(TAG, "Imported layers: $layerNames")

    // The animation of a layer is a set of keyframe tracks on its block.
    val ring = engine.block.findByName("Ring").first()
    val ringAnimatedProperties = engine.block.getAnimatedProperties(ring)
    Log.i(TAG, "Animated properties of the ring: $ringAnimatedProperties")

    // The "brand" slot became a color variable. Setting it recolors every fill that uses the slot.
    engine.variable.setColor(
        key = "brand",
        value = Color.fromRGBA(r = 0.13F, g = 0.55F, b = 0.45F, a = 1F),
    )
    val brandColor = engine.variable.getColor(key = "brand")

    // Lottie markers became scene markers, in seconds.
    val markers = engine.scene.getMarkers()
    markers.forEach { marker ->
        Log.i(TAG, "Marker \"${marker.name}\" at ${marker.time}s for ${marker.duration}s")
    }

    val previewPng = engine.block.export(block = page, mimeType = MimeType.PNG)
    return ImportLottie(
        groups = groups,
        layerNames = layerNames,
        ringAnimatedProperties = ringAnimatedProperties,
        brandColor = brandColor,
        markers = markers,
        previewPng = previewPng,
    )
}

Lottie is a JSON format for vector animation. The @imgly/lottie-importer package turns each layer of a Lottie .json file or a dotLottie .lottie archive into blocks inside one group. Shape, text, solid, image and precomp layers become native blocks that keep their animation as keyframe tracks, so users can select and edit them like any other block.

The importer runs in Node.js and the browser. There is no Lottie importer on Android. Import the file once with the Node.js importer, save the scene as an .imgly archive, and load that archive in the app.

Loading the Converted Archive#

engine.scene.load(sceneUri, overrideEditorConfig, waitForResources) is a suspend function that loads the .imgly archive and replaces the current scene.

// overrideEditorConfig = true also loads the variables that the importer created for the slots.
engine.scene.load(
    sceneUri = archiveUri,
    overrideEditorConfig = true,
    waitForResources = true,
)

Pass a local file URI, a readable Android content URI, or a remote HTTPS URI. waitForResources = true resumes the coroutine after the bundled resources are ready. The archive bundles the scene with its resources, including the Lottie documents of layers that play back from a video fill. Pass overrideEditorConfig as true, so the engine also loads the variables that the importer created for the Lottie slots. It replaces the variables and the other editor settings of the engine with those of the archive.

Finding the Imported Blocks#

Each import is one group on the page. Each block in the group carries the name of its Lottie layer. When a layer can move outside the composition, the group also holds a block named “Composition clip” that clips the group to the composition. The animated transform, opacity and properties of a layer are keyframe tracks on its block.

// Each import is one group on the page. Its blocks carry the names of the Lottie layers.
val page = engine.scene.getPages().first()
val groups = engine.block.getChildren(page)
val layerNames = engine.block.getChildren(groups.first()).map { engine.block.getName(it) }
Log.i(TAG, "Imported layers: $layerNames")

// The animation of a layer is a set of keyframe tracks on its block.
val ring = engine.block.findByName("Ring").first()
val ringAnimatedProperties = engine.block.getAnimatedProperties(ring)
Log.i(TAG, "Animated properties of the ring: $ringAnimatedProperties")

A layer with a feature that has no native block equivalent, such as a 3D layer, became a graphic block. Its video fill plays a Lottie document that holds only that layer, so the layer still animates but users cannot edit its content.

Changing Slots Through Variables#

A Lottie slot is a value that a file marks for replacement with a slot id (sid). The importer turned each color, number, image and text slot into a variable named after the slot id. When a variable with that name already existed, it picked the first free name: <id> (2), <id> (3) and so on. The example archive holds two imports of the same badge, so the first one uses brand and the second brand (2).

// The "brand" slot became a color variable. Setting it recolors every fill that uses the slot.
engine.variable.setColor(
    key = "brand",
    value = Color.fromRGBA(r = 0.13F, g = 0.55F, b = 0.45F, a = 1F),
)
val brandColor = engine.variable.getColor(key = "brand")

Setting the variable changes every bound property: a layer opacity, an image, and a shape fill or stroke color. An opacity variable holds the block opacity from 0 to 1. An animated slot keeps its keyframes, and they override the value that the variable sets.

Reading Markers#

The importer added the Lottie markers to the scene. engine.scene.getMarkers() returns each marker with its name, its time in seconds from the start of the composition, and its duration in seconds. Each import appends its markers, so the example archive holds the markers of both badges.

// Lottie markers became scene markers, in seconds.
val markers = engine.scene.getMarkers()
markers.forEach { marker ->
    Log.i(TAG, "Marker \"${marker.name}\" at ${marker.time}s for ${marker.duration}s")
}

Saving the Scene#

To save the scene again, use engine.scene.saveToArchive(), which bundles the Lottie documents of fallback layers. After loading an archive, these documents are transient buffer:// resources, so a string save fails with SCENE.DISALLOWED_SCHEMES unless you relocate them first. The Node.js importer itself creates them as data: URIs, which a string save accepts only when its allowed resource schemes include data.

Importing Versus a Lottie Video Fill#

You can still set a .json or .lottie URI as the fill/video/fileURI of a video fill. That plays the whole animation as one block, and users cannot edit its layers. The Lottie Fills guide shows how, and how the fill loads the images and fonts that the Lottie references. The fill draws the values of the animation’s slots. Like the importer, it ignores the themes of a .lottie archive. An image slot draws only when it embeds its image as a base64 data:image/ URI. The fill ignores the slots when the animation is larger than 32 MiB. For a .lottie archive, that size includes the images in the archive. A .lottie file in a video fill must be a valid dotLottie archive, with at most 1,024 entries, 128 MiB uncompressed and 32 MiB for the animation JSON. Otherwise the fill goes into the error state with SCENE.LOTTIE_ARCHIVE_INVALID, SCENE.LOTTIE_ARCHIVE_TOO_MANY_ENTRIES, SCENE.LOTTIE_ARCHIVE_TOO_LARGE or SCENE.LOTTIE_ARCHIVE_UNSAFE_PATH.

API Reference#

Next Steps#

• Import Lottie Animations in Node.js — convert the Lottie file and save the archive.
• Keyframes — edit the keyframes of the imported blocks.
• Text Variables — learn how variables drive block properties.
• File Format Support — see which other formats CE.SDK imports.