Overview

Lotio is a high-performance Lottie animation frame renderer using Skia. It renders Lottie animations to PNG frames for video encoding.

What is Lotio?

Lotio is a powerful tool for converting Lottie animations into individual frames that can be used for video encoding, image sequences, or programmatic manipulation. It's built on top of Google's Skia graphics library, providing:

• High Performance: Multi-threaded rendering for fast frame generation
• PNG Output: Outputs PNG frames or stream directly to stdout
• Text Customization: Dynamic text replacement and auto-fit sizing
• Cross-Platform: Native binaries for macOS and Linux, WebAssembly for browsers
• Multiple Interfaces: Command-line tool, JavaScript library, and C++ library

What Does It Do?

Lotio takes Lottie animation JSON files and renders them frame-by-frame into image files or streams. Key features include:

Core Functionality

1. Frame Rendering: Converts Lottie animations into individual frames at any FPS
2. Format Support: Outputs PNG images (default format)
3. Text Processing:
4. Dynamic text value replacement
5. Auto-fit font sizing to fit text boxes
6. Custom font loading
7. Configurable text padding (controls how much of text box width is used)
8. Multiple text measurement modes (fast, accurate, pixel-perfect) for precision vs performance trade-offs
9. Streaming: Can stream frames directly to stdout for piping to video encoders like ffmpeg

Use Cases

• Video Encoding: Generate frame sequences for video creation
• Image Sequences: Create sprite sheets or animation frames
• Web Applications: Use the WebAssembly build for browser-based rendering
• Automation: Integrate into build pipelines or automated workflows
• Custom Rendering: Programmatically control animation playback and rendering

Architecture

Lotio is built with a modular architecture:

lotio/
|
├── src/
|
│   ├── core/          # Core functionality (animation setup, rendering, encoding)
|   |
│   ├── text/          # Text processing (configuration, font handling, sizing)
|   |
│   ├── utils/         # Utilities (logging, string utils, crash handling)
|   |
│   └── wasm/          # WebAssembly-specific code
|
├── browser/            # WebAssembly build output
|
└── third_party/skia/  # Skia graphics library

Components

1. Command-Line Interface (CLI)

A native binary (lotio) for rendering animations from the command line. See the CLI Documentation for details.

2. JavaScript Library

A WebAssembly-based library for browser use. See the JS Library Documentation for details.

3. C++ Library

Headers and static libraries for programmatic use. See the C++ Library Documentation for details.

Installation

Homebrew (macOS - Recommended)

brew tap matrunchyk/lotio
brew install lotio

From Source

See the README for build instructions.

npm (JavaScript/WebAssembly)

npm install lotio

Quick Start

Command Line

lotio --data animation.json --fps 30 frames/

JavaScript

import Lotio from 'lotio';

const animation = new Lotio({
  animation: animationData,
  wasmPath: './lotio.wasm'
});

C++

#include <lotio/core/animation_setup.h>

AnimationSetupResult result = setupAndCreateAnimation("input.json", "");

Performance

Lotio is optimized for performance:

• Multi-threaded rendering: Utilizes multiple CPU cores
• Raw RGBA output: Up to 15x faster than PNG for video encoding (use --output-format raw --output -)
• Efficient memory usage: Streams frames to reduce memory footprint
• Skia acceleration: Leverages Skia's optimized rendering pipeline
• WebAssembly optimization: Optimized WASM build for browser performance

Performance tip: For video encoding pipelines, use --output-format raw --output - for maximum speed (up to 15x faster than PNG mode).

License

See individual component licenses:
- Skia: third_party/skia/skia/LICENSE
- Lotio: See repository LICENSE file