# Load animations
Load Lottie JSON and .lottie animations from a file path or from memory, read the manifest, switch between animations, and register custom fonts.

The runtime loads Lottie JSON (`.json`) and dotLottie (`.lottie`) animations from a file path or directly from memory. Attach a [render target](/en/runtimes/distributions/native/v0.x/render-targets) before loading, so the animation can be sized against it.

## From a file path

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

```c
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:

```c
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:

```c
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

| Format                | Contains                                                                         |
| --------------------- | -------------------------------------------------------------------------------- |
| Lottie JSON           | A single animation                                                               |
| dotLottie (`.lottie`) | A ZIP archive: one or more animations, images, fonts, themes, and state machines |

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](/en/runtimes/overview/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:

```c
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:

```c
dotlottie_load_animation(player, "success-state");
```

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

```c
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:

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

```c
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:

```c
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:

| Result                 | Likely cause                                                      |
| ---------------------- | ----------------------------------------------------------------- |
| `InvalidParameter`     | Null argument, zero size, unreadable path, or malformed animation |
| `FeatureNotEnabled`    | A `.lottie` file in a build without the `dotlottie` feature       |
| `ManifestNotAvailable` | Asked for a manifest on plain Lottie JSON                         |

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](/en/runtimes/distributions/native/v0.x/playback-control) — play the animation you loaded
- [Apply themes and slots](/en/runtimes/distributions/native/v0.x/theming-and-slots) — restyle it at runtime
- [C API reference](/en/runtimes/distributions/native/v0.x/api-reference) — full signatures