Load animations

The runtime loads Lottie JSON (.json) and dotLottie (.lottie) animations from a file path or directly from memory. Attach a render target before loading, so the animation can be sized against it.

From a file path

The simplest option handles both formats, choosing by file contents:

if (dotlottie_load_animation_path(player, "animations/loader.lottie") != DOTLOTTIE_SUCCESS) {
  fprintf(stderr, "could not load animation\n");
}

The path is read during the call, so the string doesn't need to outlive it.

From memory

When you already hold the bytes — from an archive, a network response, or an embedded resource — load them directly instead of writing a temporary file.

For Lottie JSON, pass a null-terminated string:

dotlottie_load_animation_data(player, json_string);

For a .lottie file, pass the raw bytes and their length. The data is binary, so it is not null-terminated and the size is required:

dotlottie_load_dotlottie_data(player, (const char *)bytes, byte_count);

.lottie support comes from the dotlottie feature, which is on by default. Without it, this returns FeatureNotEnabled.

Understanding the two formats

A .lottie file is the richer container. Themes, slots with image assets, and state machines are all packaged inside it, which is why some features only work once you load one. See What is dotLottie for the format itself.

Reading the manifest

A .lottie file carries a manifest listing everything it contains. Read it as a JSON string with the two-call pattern:

size_t size = 0;
if (dotlottie_get_manifest(player, NULL, &size) == DOTLOTTIE_SUCCESS) {
  char *manifest = malloc(size);
  dotlottie_get_manifest(player, manifest, NULL);

  printf("%s\n", manifest);   /* parse with your JSON library */
  free(manifest);
}

This returns ManifestNotAvailable for plain Lottie JSON, which has no manifest. The runtime does not include a JSON parser, so use whichever one your project already has.

Multiple animations in one file

A .lottie file can hold several animations, each with an ID from the manifest. The first is loaded by default; switch to another by ID:

dotlottie_load_animation(player, "success-state");

Switching resets playback and clears the active theme, so reapply any theme afterwards. Check which animation is current:

size_t size = 0;
if (dotlottie_get_animation_id(player, NULL, &size) == DOTLOTTIE_SUCCESS) {
  char *id = malloc(size);
  dotlottie_get_animation_id(player, id, NULL);
  /* ... */
  free(id);
}

Both functions need the dotlottie feature.

Checking what loaded

Reading the animation's dimensions and length is a good way to confirm a load worked as expected:

float width = 0.0f, height = 0.0f;
dotlottie_get_animation_size(player, &width, &height);

float total = 0.0f, duration = 0.0f;
dotlottie_get_total_frames(player, &total);
dotlottie_get_duration(player, &duration);

printf("%.0fx%.0f, %.0f frames, %.2fs\n", width, height, total, duration);

Custom fonts

Animations with text layers need their fonts available. Fonts live in a process-wide registry rather than on a player, so dotlottie_load_font() takes no player handle and one registration serves every player in your process.

dotlottie_load_font("Inter-Bold", font_bytes, font_byte_count);

The name must match the font family the animation references. Font data is copied, so you can free your buffer afterwards. Remove a font when you no longer need it:

dotlottie_unload_font("Inter-Bold");

Register fonts before loading an animation that uses them. Font rendering requires the tvg-ttf feature for TrueType or tvg-otf for OpenType. Fonts packaged inside a .lottie file are picked up automatically and need no registration.

Handling failures

Loading is the most common place to see a non-zero result, and the code tells you what went wrong:

If an image or font inside an otherwise valid animation fails to decode, the animation still loads — the asset is simply not drawn. That usually means the matching codec feature (tvg-png, tvg-jpg, tvg-webp) or font feature was left out of the build.

Learn more

• Control playback — play the animation you loaded

• Apply themes and slots — restyle it at runtime

• C API reference — full signatures