# Rlottie Player (/libs/image_support/rlottie)



<Callout type="warn">
  Rlottie is deprecated.  Consider using the [Lottie (lv\_lottie)](/widgets/lottie) Widget instead.
</Callout>

The [Rlottie animation player for LVGL](https://github.com/ValentiWorkLearning/lv_rlottie)
is a 3rd-party extension for LVGL that allows playing Lottie animations in LVGL.
It provides an interface to [Samsung/rlottie](https://github.com/Samsung/rlottie)
library's C API.  This Lottie player is not part of LVGL; it needs to be built
separately.

Building Rlottie [#building-rlottie]

To build Samsung's Rlottie, you will need a C++14-compatible compiler and optionally
CMake 3.14 or higher.

To build on a desktop you can follow the instructions from Rlottie's
[README](https://github.com/Samsung/rlottie/blob/master/README.md).

In the most basic case it looks like this:

```bash title="bash" lineNumbers=1
mkdir rlottie_workdir
cd rlottie_workdir
git clone https://github.com/Samsung/rlottie.git
mkdir build
cd build
cmake ../rlottie
make -j
sudo make install
```

And finally add the `-lrlottie` flag to your linker.

On embedded systems you need to take care of integrating Rlottie to the
given build system.

See the ESP-IDF example below.

Usage [#usage]

You can use animation from files or raw data (text). In either case
first you need to enable <ApiLink name="LV_USE_RLOTTIE" /> in `lv_conf.h` by setting its
value to `1`.

The `width` and `height` of the Widget is set in the `lv_rlottie_create_from_...()`
function, and the animation will be scaled accordingly.

Use Rlottie from File [#use-rlottie-from-file]

To create a Lottie animation from a file, use:

```c title=" " lineNumbers=1
lv_obj_t * lottie = lv_rlottie_create_from_file(parent, width, height, "path/to/lottie.json");
```

Note that, Rlottie uses the standard STDIO C file API, so you can use
the path "normally" and no LVGL specific driver letter is required.

Use Rlottie from Raw String Data [#use-rlottie-from-raw-string-data]

`lv_example_rlottie_approve.c` contains an example animation in raw
format. Instead of storing the JSON string, a hex array is stored for the
following reasons:

* avoid escaping `"` character in the JSON file
* some compilers don't support very long strings

`lvgl/scripts/filetohex.py` can be used to convert a Lottie file a hex
array. E.g.:

```bash title="bash" lineNumbers=1
./filetohex.py path/to/lottie.json --filter-character --null-terminate > out.txt
```

`--filter-character` filters out non-ASCII characters and `--null-terminate`
makes sure that a trailing zero is appended to properly terminate the string.

To create an animation from raw data:

```c title=" " lineNumbers=1
extern const uint8_t lottie_data[];
lv_obj_t* lottie = lv_rlottie_create_from_raw(parent, width, height, (const char *)lottie_data);
```

Getting Animations [#getting-animations]

Lottie is standard and popular format so you can find many animation
files on the web.  For example:  [https://lottiefiles.com/](https://lottiefiles.com/) .

You can also create your own animations with Adobe After Effects or
similar software.

Controlling Animations [#controlling-animations]

LVGL provides two functions to control the animation mode:
<ApiLink name="lv_rlottie_set_play_mode" /> and <ApiLink name="lv_rlottie_set_current_frame" />.
You'll combine your intentions when calling the first method, like in
these examples:

```c title=" " lineNumbers=1
lv_obj_t * lottie = lv_rlottie_create_from_file(scr, 128, 128, "test.json");
lv_obj_center(lottie);
// Pause to a specific frame
lv_rlottie_set_current_frame(lottie, 50);
lv_rlottie_set_play_mode(lottie, LV_RLOTTIE_CTRL_PAUSE); // The specified frame will be displayed and then the animation will pause

// Play backward and loop
lv_rlottie_set_play_mode(lottie, LV_RLOTTIE_CTRL_PLAY | LV_RLOTTIE_CTRL_BACKWARD | LV_RLOTTIE_CTRL_LOOP);

// Play forward once (no looping)
lv_rlottie_set_play_mode(lottie, LV_RLOTTIE_CTRL_PLAY | LV_RLOTTIE_CTRL_FORWARD);
```

The default animation mode is **play forward with loop**.

If you don't enable looping, a <ApiLink name="LV_EVENT_READY" /> is sent when the
animation cannot make more progress without looping.

To get the number of frames in an animation or the current frame index,
you can cast the <ApiLink name="lv_obj_t" /> instance to a <ApiLink name="lv_rlottie_t" /> instance
and inspect the `current_frame` and `total_frames` members.

ESP-IDF Example [#esp-idf-example]

Background [#background]

Rlottie can be expensive to render on embedded hardware. Lottie
animations tend to use a large amount of CPU time and can use large
portions of RAM. This will vary from lottie to lottie but in general for
best performance:

* Limit total # of frames in the animation
* Where possible, try to avoid bezier type animations
* Limit animation render size

If your ESP32 chip does not have SPIRAM you will face severe limitations
in render size.

To give a better idea on this, lets assume you want to render a 240x320
lottie animation.

In order to pass initialization of the lv\_rlottie\_t object, you need
240x320x32/8 (307k) available memory. The latest ESP32-S3 has 256kb RAM
available for this (before FreeRTOS and any other initialization starts
taking chunks out). So while you can probably start to render a 50x50
animation without SPIRAM, PSRAM is highly recommended.

Additionally, while you might be able to pass initialization of the
`lv_rlottie_t` object, as rlottie renders frame to frame, this consumes
additional memory. A 30-frame animation that plays over 1 second
probably has minimal issues, but a 300 frame animation playing over 10
seconds could very easily crash due to lack of memory as rlottie
renders, depending on the complexity of the animation.

Rlottie will not compile for the IDF using the `-02` compiler option at
this time.

For stability in lottie animations, this author has found that they run best in the
IDF when enabling <ApiLink name="LV_MEM_CUSTOM" /> (using `stdlib.h`)

For all its faults, when running right-sized animations, they provide a
wonderful utility to LVGL on embedded LCDs and can look really good when
done properly.

When picking/designing a lottie animation consider the following
limitations:

* Build the lottie animation to be sized for the intended size.
* It can scale/resize, but performance will be best when the base lottie size is as intended.
* Limit total number of frames, the longer the lottie animation is,
  the more memory it will consume for rendering (rlottie consumes IRAM for rendering).
* Build the lottie animation for the intended frame rate.
* Default lottie is 60fps, embedded LCDs likely won't go above 30fps.

IDF Setup [#idf-setup]

Where the LVGL simulator uses the installed rlottie lib, the IDF works
best when using rlottie as a submodule under the components directory.

```bash title="bash" lineNumbers=1
cd 'your/project/directory'
git add submodule
git add submodule https://github.com/Samsung/rlottie.git ./components/rlottie/rlottie
git submodule update --init --recursive
```

Now, Rlottie is available as a component in the IDF, but it requires
some additional changes and a CMakeLists file to tell the IDF how to
compile.

Rlottie Patch File [#rlottie-patch-file]

Rlottie relies on dynamic linking for an image loader lib. This needs
to be disabled as the IDF doesn't play nice with dynamic linking.

A patch file is available in LVGL under:
`/env_support/esp/rlottie/0001-changes-to-compile-with-esp-idf.patch`

Apply the patch file to your rlottie submodule.

CMakeLists for IDF [#cmakelists-for-idf]

An example CMakeLists file has been provided at
`/env_support/esp/rlottie/CMakeLists.txt`

Copy this CMakeLists file to
`'your-project-directory'/components/rlottie/`

In addition to the component CMakeLists file, you'll also need to tell
your project level CMakeLists in your IDF project to require rlottie:

```console title="console" lineNumbers=1
REQUIRES "lvgl" "rlottie"
```

From here, you should be able to use lv\_rlottie objects in your ESP-IDF
project as any other widget in LVGL ESP examples. Please remember that
these animations can be highly resource constrained and this does not
guarantee that every animation will work.

Additional Rlottie Considerations in ESP-IDF [#additional-rlottie-considerations-in-esp-idf]

While unnecessary, removing the `rlottie/rlottie/example` folder can remove
many un-needed files for this embedded LVGL application.

From here, you can use the relevant LVGL `lv_rlottie...()` functions to create
lottie animations in LVGL on embedded hardware!

Please note, that while lottie animations are capable of running on many
ESP chips, below is recommended for best performance.

* ESP32-S3-WROOM-1-N16R8

  * 16mb quad spi flash
  * 8mb octal spi PSRAM
* IDF4.4 or higher

The Esp-box devkit meets this spec and
[https://github.com/espressif/esp-box](https://github.com/espressif/esp-box) is a great starting point to adding
lottie animations.

You will need to enable <ApiLink name="LV_USE_RLOTTIE" /> through **idf.py** menuconfig under
LVGL component settings.

Additional Changes to Make Use of SPIRAM [#additional-changes-to-make-use-of-spiram]

<ApiLink name="lv_alloc" display="lv_alloc/realloc" /> does not make use of SPIRAM. Given the high memory usage
of lottie animations, it is recommended to shift as much out of internal
DRAM into SPIRAM as possible. In order to do so, SPIRAM will need to be
enabled in the menuconfig options for your given espressif chip.

There may be a better solution for this, but for the moment the
recommendation is to make local modifications to the LVGL component in
your espressif project. This is as simple as swapping
<ApiLink name="lv_alloc" display="lv_alloc/lv_realloc" /> calls in \`lv\_rlottie.c\`\` with <ApiLink name="heap_caps_malloc" /> (for
IDF) with the appropriate <ApiLink name="MALLOC_CAP" /> call --- for SPIRAM usage this is
<ApiLink name="MALLOC_CAP_SPIRAM" />.

```c title=" " lineNumbers=1
rlottie->allocated_buf = heap_caps_malloc(allocated_buf_size+1, MALLOC_CAP_SPIRAM);
```

Examples [#examples]

Load a Lottie animation from raw data [#load-a-lottie-animation-from-raw-data]

<LvglExample name="lv_example_rlottie_1" path="libs/rlottie/lv_example_rlottie_1" />

Load a Lottie animation from a file [#load-a-lottie-animation-from-a-file]

<LvglExample name="lv_example_rlottie_2" path="libs/rlottie/lv_example_rlottie_2" />

API [#api]