# Samsung/rlottie: a C++ library for rendering Lottie animations

> Samsung/rlottie loads Bodymovin JSON animations and renders selected frames into caller-provided surface buffers. It fits native C++ applications, but its unsupported status and custom license require careful review before adoption.

**Samsung/rlottie** — A platform independent standalone library that plays Lottie Animation. 

- Repository: https://github.com/Samsung/rlottie
- Stars: 1,444 · Forks: 283
- Language: C++
- License: NOASSERTION
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/samsung-rlottie

## Where rlottie fits in a C++ animation stack

Samsung/rlottie addresses a specific gap between design-time animation files and native applications. Animation designers can export Bodymovin JSON from After Effects through bodymovin, from Sketch through Lottie Sketch Export, or from Haiku. rlottie gives a native C++ application a way to load those files and draw their vector content without asking an engineer to recreate every animated shape by hand.

The intended users are developers embedding animation playback in an application and designers supplying Lottie assets to them. The README describes the format as compact because it is backed by JSON, but it also warns that an animation can be complex despite its file size. That distinction matters. A small JSON payload does not guarantee inexpensive parsing, low memory use, or fast rendering. The repository does not publish performance results that would justify such a conclusion.

rlottie is not a general animation editor, asset converter, or design authoring tool. Its documented scope begins with loading Bodymovin JSON and ends with rendering a requested frame into a `rlottie::Surface`. The included `lottie2gif` utility offers a separate file-oriented use case by converting one Lottie file into a GIF.

There is also a direct project-status concern. Repository metadata reports that the repository is not archived, and its last push was on 2026-09-30. However, the README explicitly says the project is archived, no longer maintained, and receives no security support, vulnerability review, patches, releases, or CVE coordination from the project. For an engineering decision, that warning is more consequential than the repository's archival flag because it removes any expectation of supported fixes.

## rlottie's file, object, and buffer flow

The public API separates the animation document from the destination pixels. An application first creates an animation object through `rlottie::Animation::loadFromFile` or `rlottie::Animation::loadFromData`. A file-backed animation is loaded from an absolute path. A data-backed animation receives raw string data plus a cache key, allowing rlottie to identify cached data associated with that payload.

After loading, the application can query `frameRate()`, `totalFrame()`, and `duration()`. These values describe the resource's timing, while the caller selects the frame number to render. This model gives the embedding application control over playback scheduling. The README does not describe an internal playback loop that automatically advances time, so treating rlottie as a source of individual frames fits its documented API.

Pixels do not come from an image file managed by rlottie. The caller creates a `rlottie::Surface` from its own buffer, width, height, and stride. It then selects synchronous or asynchronous rendering. `renderSync` writes a particular frame into that surface during the call. `render` accepts the same kind of surface and returns a `std::future<rlottie::Surface>`, which the caller retrieves with `get()` when the rendered data is needed.

The architecture therefore leaves buffer ownership with the embedding application. It also makes pixel format and buffer compatibility important integration details. The README does not specify the expected channel format, color space, premultiplication rules, lifetime requirements, or error behavior for invalid dimensions and buffers. Those points must be checked against the public headers and your rendering backend before relying on the library.

## Building rlottie with the documented Meson path

The shortest documented build path uses Meson and Ninja. Install Meson and Ninja first, then configure the repository in a directory named `build` and compile it with Ninja. The project is written in C++14 and has a public header dependency of C++11.

The first command creates the Meson build directory:

```bash
meson build
```

Meson should complete configuration without reporting a missing dependency. The second command invokes Ninja through that build directory:

```bash
ninja -C build
```

This is the documented route to a local build. The repository also contains CMake, packaging, platform, and WebAssembly-related files, but the README provides the following sequence for testing the library:

```bash
meson configure -Dtest=true
ninja test
```

The README places `meson configure -Dtest=true` before building the test suite, then uses `ninja` to compile and `ninja test` to run it. If you follow the shorter tutorial first, reconfigure the same `build` directory with `-Dtest=true`, run Ninja there, and then run the test target. The README does not define the test coverage or expected test count, so a successful test command does not prove that every Lottie feature or export works correctly.

For a first real asset check, build `lottie2gif`, which the README says is generated while the library is built. Run it against a known Lottie JSON file:

```bash
lottie2gif [lottie file name]
```

The resulting GIF provides a visual check of the supplied asset. It does not exercise your application's own `rlottie::Surface`, color format, frame scheduler, or thread integration.

## Embedding rlottie::Animation in native code

Load an animation from a file using the API shown in the README. The placeholder path must resolve to an actual Bodymovin JSON resource:

```cpp
auto animation = rlottie::Animation::loadFromFile("absolute_path/test.json");
```

For assets already held in memory, rlottie accepts raw data and a cache key:

```cpp
auto animation = rlottie::Animation::loadFromData(std::string(rawData), std::string(cacheKey));
```

The application can then inspect timing before deciding how to schedule frames. The following code follows the documented property names and return types:

```cpp
double frameRate = animation->frameRate();
size_t totalFrame = animation->totalFrame();
double duration = animation->duration();
```

Synchronous rendering writes directly into an application-owned buffer. Supplying the correct stride is part of the surface contract because it describes the distance between adjacent rows:

```cpp
rlottie::Surface surface(buffer, width , height , stride);
animation->renderSync(frameNo, surface);
```

The asynchronous route returns a future. The application must not read the rendered result before satisfying the future, and the README does not state whether the original buffer can be reused or modified while that request is outstanding:

```cpp
rlottie::Surface surface(buffer, width , height , stride);
std::future<rlottie::Surface> handle = animation->render(frameNo, surface);
rlottie::Surface surface = handle.get();
```

Retrieve the rendered result with `get()` when it is needed. The future-based API can fit applications that want render work separated from their frame request, but the README does not explain worker-thread management, failure reporting, cancellation, or concurrency guarantees.

## Runtime properties and JSON targeting

rlottie supports changing animation properties at runtime through named targets rather than forcing a new JSON resource for every visual state. The README describes this capability in the context of day and night themes, success or error events, animation of one component in response to an event, and values such as view dimensions that are unknown when the design is created.

The mechanism follows the hierarchy used by After Effects. A composition contains layers, each layer has its own timeline, and drawable objects include images, shapes, fills, strokes, and other content. Lottie can locate objects and properties by name through a `KeyPath`. The documented workflow identifies three requirements: a `KeyPath`, an `rlottie::Property`, and `setValue()`.

This is more flexible than playback of an unchanged JSON file, but it also couples native code to names and structure produced by the animation tool. A renamed layer or property can make a hard-coded key path obsolete. The README excerpt ends while introducing the detailed `KeyPath` API, so it does not provide enough information here to reproduce exact lookup and mutation calls. Before depending on runtime changes, inspect the repository's public headers and test each key path against the actual exported JSON.

The feature does not turn rlottie into a general binding system for arbitrary application state. Its documented model targets properties inside the Lottie data tree. External event handling, interpolation policy, and binding lifecycle remain the responsibility of the application. The README provides no exhaustive list of every animatable property type and does not define fallback behavior for a missing target.

## CMake, platform files, and GIF conversion

CMake is the documented alternative for building rlottie. The README creates a separate `build` directory, enters it, and configures the parent source tree. It also shows how to select an installation prefix and request a static build.

Create and enter the build directory with:

```bash
mkdir build
cd build
```

Configure the project from that directory:

```bash
cmake ..
```

The README's optional commands set `CMAKE_INSTALL_PREFIX` and disable shared libraries. They are configuration choices rather than documented requirements:

```bash
cmake -DCMAKE_INSTALL_PREFIX=~/test ..
cmake -DBUILD_SHARED_LIBS=OFF ..
```

Compile and install the result with the documented Make targets:

```bash
make -j 2
make install
```

A static library can simplify deployment when the target environment and build configuration match, but it does not remove the need to account for native code, ABI choices, and linking in the consuming application. The README does not publish an installation manifest or enumerate supported compiler, operating system, and architecture combinations. Repository files such as `.appveyor.yml`, `vs2019/`, `arm_build.sh`, `wasm_build.sh`, and platform example directories show that build-related resources exist, but their presence does not establish a supported release matrix.

For noninteractive asset inspection, `lottie2gif` is the clearest executable in the README. It converts a Lottie JSON file to GIF, which helps reviewers check visible output before wiring the animation into a native renderer. The documentation does not present it as a validator for malformed JSON, unsupported effects, or native surface compatibility.

## Unsupported status, custom licensing, and adoption limits

The strongest limitation is not a rendering limitation but the project's declared support boundary. The README says rlottie is archived, is no longer maintained, and provides no security support, vulnerability review, patches, releases, or CVE assignment and coordination. It also states that vulnerability reports may be declined because the project is unsupported. Repository metadata separately reports the repository as not archived and gives the last push date as 2026-09-30, so the repository state and the README warning are not aligned. An engineering team should not infer support from the recent push alone.

The release history contains only two entries: `v0.1` from 2020-06-19 and `v0.2` from 2020-08-19. That means the documented release line is old. The last push does not demonstrate a new release or a commitment to publish one, and the README rules out future project-provided patches and releases.

The license is marked as custom, with `COPYING` as the controlling file and related license material under `licenses/`. The repository description does not classify it under GitHub's standard license categories. Do not assume that a permissive open source license applies merely because the source is public. Before copying code, linking the library, distributing binaries, shipping an animation viewer, or using the code in a commercial product, inspect `COPYING` and the files under `licenses/` and record the obligations that apply to your distribution model.

A real alternative is a platform-native or separately maintained Lottie implementation selected for your target runtime. The alternative approach depends on the ecosystem: a platform animation runtime may connect rendering and dynamic properties to native platform facilities, while another C++ or WebAssembly implementation may provide a different API, build system, and release path. The README does not name a specific alternative or document comparative compatibility, so no performance or feature ranking is justified.

## Conclusion

Adopt rlottie only when your application already accepts an unsupported C++ animation renderer and can satisfy the custom licensing terms in COPYING. Do not choose it for a new product that requires security support, maintained releases, or predictable feature delivery. Verify your intended Lottie feature set, asynchronous rendering behavior, buffer contract, and COPYING obligations before integrating `rlottie::Animation` and `rlottie::Surface`.

## FAQ

### How do I install and build Samsung/rlottie?

The README documents both Meson and CMake builds. For the shorter Meson route, run `meson build` and then `ninja -C build`.

### How does Samsung/rlottie load and render an animation?

Load a Bodymovin JSON file with `rlottie::Animation::loadFromFile`, or use `loadFromData` for raw data. Create a `rlottie::Surface` over an application-owned buffer and render with `renderSync` or `render`.

### Is Samsung/rlottie still maintained?

The README states that the project is archived, no longer maintained, and provides no security support, vulnerability review, patches, releases, or CVE coordination. Repository metadata reports a last push on 2026-09-30, but it does not identify a new release.

### Can Samsung/rlottie change animation properties at runtime?

The documented workflow uses a `KeyPath`, an `rlottie::Property`, and `setValue()`. Names come from the hierarchy of objects and properties in the exported After Effects composition.

### What license applies to Samsung/rlottie?

GitHub does not classify the license as a standard license type, and the repository directs users to `COPYING`. The licensing files must be reviewed for the obligations that apply to a particular use or distribution.

## Sources

- [Issues](https://github.com/Samsung/rlottie/issues)
- [README](https://github.com/Samsung/rlottie/blob/master/README.md)
- [Releases](https://github.com/Samsung/rlottie/releases)
- [Samsung/rlottie on GitHub](https://github.com/Samsung/rlottie)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/samsung-rlottie