lottie-converter, turning Lottie files and Telegram stickers into GIF, APNG and WEBP

The formats other apps will actually accept

Lottie is a vector animation format, and plenty of applications do not read it. This converter takes Lottie animations, both .json and the packaged .lottie form, and Telegram stickers in the .tgs format, and writes GIF, PNG, APNG, WEBP and WEBM. The problem it solves is therefore a delivery problem rather than an authoring one. A sticker designer has a .tgs file and a chat application that wants a static or animated image in a specific format, and the usual route is a web service or a desktop tool with a user interface. This is a command line tool and a set of container images, which is what a build pipeline or a batch job needs. The project also links a Telegram bot for converting stickers for WhatsApp, and points at a separate bot for downloading .tgs files in the first place, so the surrounding workflow is sticker oriented even though the converter itself takes any Lottie file.

One renderer binary and five shell wrappers

The Dockerfile shows the architecture, and it is a two layer design. The first layer is a C++ program that renders frames, and the second is a set of shell scripts that turn those frames into the final format. The multi stage image copies a single binary, lottie_to_png, out of a gcc:15 builder stage, which means the PNG path is the native one and the other formats are derived from it. The GIF image is built on debian:bookworm and additionally copies the gifski binary, which is built in a separate rust stage with cargo install of version 1.32.0. The other formats, PNG, APNG, WEBP and WEBM, use a lighter alpine based stage, because they rely on tools that are simpler to obtain. The practical consequence is that the images are not interchangeable. The gif image carries an extra dependency, and the others do not, and each image sets FORMAT so that the same shell loop can call the right script.

One command per output format

Running the container takes a host directory mounted at /source, and the converter walks it.

docker run --rm -v <path to directory>:/source edasriyan/lottie-to-gif

The same shape works for the other formats, with the image name changing to edasriyan/lottie-to-png, edasriyan/lottie-to-apng, edasriyan/lottie-to-webp and edasriyan/lottie-to-webm. Output lands next to each source file in the same directory, so the container does not need an output volume at all. Configuration is entirely through environment variables, and the documented set is short. HEIGHT sets the output image height and defaults to 512. WIDTH sets the output image width and defaults to 512. FPS sets the frame rate, and the default depends on the format, 60 for APNG, PNG and WEBP and 50 for GIF. QUALITY defaults to 90. THREADS sets the number of threads and defaults to the number of CPUs. BACKGROUND replaces transparent pixels with a colour, and accepts rgb(r,g,b), rgba(r,g,b,a), #RRGGBB or #RRGGBBAA. A run with overrides looks like this.

docker run --rm -e HEIGHT=256 -e WIDTH=256 -e FPS=30 -v /home/ed/Downloads/lottie-animations:/source edasriyan/lottie-to-apng

The compiled route, and what it asks of your machine

The alternative to Docker is to download a release for your OS and architecture and run the scripts from the archive. That route is not self contained, because each format depends on an external tool that has to be on the PATH. gifski is needed for GIF, ffmpeg for APNG and WEBM, and img2webp for WEBP. The scripts shipped in the archive are lottie_to_apng.sh, lottie_to_gif.sh, lottie_to_png.sh, lottie_to_webp.sh and lottie_to_webm.sh, and they share one command line interface.

$ ./bin/lottie_to_gif.sh -h
usage: ./bin/lottie_to_gif.sh [--help] [--output OUTPUT] [--height HEIGHT] [--width WIDTH] [--threads THREADS] [--fps FPS] [--quality QUALITY] [--background BACKGROUND] path

The path is positional and takes a .json or .tgs file, and the optional arguments mirror the environment variables used by the containers, so the same concepts appear in both interfaces. The help text also carries the format specific default for the frame rate, which is 50 for GIF. Running the script on a single file writes the result next to the source, the same rule the containers follow.

Building it with Conan and CMake

Building from source takes a C++17 compiler, make, cmake and conan. The Conan step is a two stage one, first a profile has to exist, then the dependencies are fetched.

conan profile detect

conan install --build=missing .

The build then uses a Conan aware CMake preset, and the preset name differs by platform.

cmake --preset conan-release

On Windows the preset is conan-default. The compile step passes the build type and turns the LOTTIE_MODULE option off.

cmake -DCMAKE_BUILD_TYPE=Release -DLOTTIE_MODULE=OFF CMakeLists.txt && cmake --build . --config Release

That last detail deserves a note rather than a guess. The option is named for the Lottie module, the documented build and the container build both set it to OFF, and the documentation does not say what turning it on or off changes in the renderer, so an adopter who needs specific Lottie features should resolve that question before relying on the output. The repository also carries a conanfile.txt, a .conanrc, a .devcontainer directory and a test-files/ directory, and the CI and release workflows have their own badges, with the release workflow pushing to Docker Hub.

Batch conversion is a find loop over three extensions

The container entrypoint is worth reading, because it defines exactly what gets converted. The command searches the mounted directory for files whose names end in .json, .lottie or .tgs, case insensitively, and for each one it calls the script for the format named in the FORMAT variable, passing through the width, height, frame rate, quality and background options only when those environment variables are set.

find /source -type f \( -iname \*.json -o -iname \*.lottie -o -iname \*.tgs \) | while IFS=$'\n' read -r FILE; do
    echo Converting \${FILE}... && lottie_to_\${FORMAT}.sh \${WIDTH:+--width \$WIDTH} \${HEIGHT:+--height \$HEIGHT} \${FPS:+--fps \$FPS} \${QUALITY:+--quality \$QUALITY} \${BACKGROUND:+--background \"\$BACKGROUND\"} \$FILE && echo Done.;
done

Two things follow from that. The tool converts everything it recognises in the directory, with no filter and no per file selection, so a directory that also holds unrelated .json configuration files is a problem the user has to solve rather than the tool. And the option passing is conditional, so an unset variable simply leaves the script at its own default instead of overriding it with an empty value, which is the behaviour you want when running the image from a scheduler that passes through only some variables.

Release history and the licence

The repository is not archived and the last push was on 2026-10-14. The release tags show v1.1.1 on 2024-05-26, v1.1.2 on 2024-09-04 and v1.2.0 on 2026-02-02, so the project is on a 1.x line with a long gap between the second and third of those, and a branch that keeps moving after the newest tag. The licence is MIT, which is permissive but still requires keeping the copyright and licence notice when the converter is redistributed, including in modified form. The runtime dependencies carry their own terms, of course, since gifski, ffmpeg and img2webp are separate projects, and a distribution that ships the compiled executables rather than the container images is where those terms matter most. Nothing here is legal advice, and the point to carry into a procurement conversation is narrow, namely that the tool is permissively licensed while its helper binaries are not part of it.

Editorial conclusion

lottie-converter fits a designer or developer who holds Lottie source files and needs a GIF, APNG, WEBP or WEBM for a platform that does not read Lottie, and it fits a team that already runs containers, since each output format has its own image and the only configuration is environment variables. It does not fit a workstation without the runtime dependencies, because the compiled route needs gifski, ffmpeg or img2webp on the PATH, and it does not fit a pipeline that needs Lottie features rendered differently, since the build switches the LOTTIE_MODULE option off and the documentation does not explain what that changes. Verify three things first: which external tool backs the format you need, whether the default frame rate and quality suit your animation, and what the LOTTIE_MODULE=OFF build option means for the renderer you are getting.

Frequently asked questions

Official sources

1. ed-asriyan/lottie-converter on GitHub
2. License: MIT
3. Project website
4. README
5. Releases