package

github.com/OrelSokolov/lottie.cr

1.0.0 / published Nov 2, 2026 / repository

Pure-Crystal Lottie (Bodymovin) player: parse animated-vector JSON, evaluate the composition at any frame and rasterize it to straight-alpha RGBA8 through the nanosvg.cr rasterizer. A faithful twin of rlottie's evaluation model (see egui.cr's plans/lottie-port.md): frame counting, path conventions (rounded rects, ovals), fill rules and color quantization deliberately copy the reference so the outputs match within a float epsilon — the verification dataset in spec/dataset/ was generated FROM rlottie.

lottie.cr

Pure-Crystal Lottie (Bodymovin) player: parses animated-vector JSON, evaluates the composition at any frame and rasterizes it to straight-alpha RGBA8 through the nanosvg.cr rasterizer.

A faithful twin of rlottie's evaluation model: frame counting, path conventions (rounded rects, ovals, polystars), trim paths, repeaters, gradient resolution and color quantization deliberately copy the reference so the outputs match within a float epsilon — the verification dataset in spec/dataset/ was generated FROM rlottie, and the twin spec replays it frame-by-frame, path-point-by-path-point.

Installation

  1. Add the dependency to your shard.yml:
dependencies:
  lottie:
    github: OrelSokolov/lottie.cr
  1. Run shards install

Usage

require "lottie"

anim = Lottie::Animation.load("emoji.json").not_nil!

# Evaluate frame 42: flat painted paths (points + element codes,
# paint, fill rule, combined opacity) in bottom-up draw order.
draws = anim.evaluate(42)

# Or rasterize straight to an RGBA8 buffer.
buf = Bytes.new(256 * 256 * 4)
anim.render(42, buf, 256, 256)

Supported features

  • Shape layers: paths (sh), rects (rc), ellipses (el), polystars/polygons (sr, fractional point counts included)
  • Paints: solid fills/strokes, linear/radial gradients, fill rules
  • Path operations: trim paths (tm, simultaneous + individual), repeaters (rp, nested repeaters included)
  • Transform chains: layer parents, group nesting, layer/group opacity, precomps with time remapping/stretch
  • Gradient quirks: legacy opacity stops, highlight length/angle, rlottie's construction budgets (an over-budget item is dropped exactly where the reference drops it)

Not supported (yet)

Masks, mattes, effects (ef), text, images, expressions, merge paths (mm), dashes (dd).

Verification

The spec suite is a twin test against rlottie:

  1. assets are rendered by rlottie's own render tree, dumped as JSON (points, element codes, colors, gradients) — see egui.cr's scripts/make_lottie_dataset.cr;
  2. the port replays every dump and must reproduce the geometry index-for-index (colors exactly, coordinates within 1e-3 — rlottie computes in float32).

The dataset covers a hand-crafted spinner, three phase-D feature assets (polystar, trim path, repeater) and nine Noto emoji animations.

License

MIT © Oleg Sokolov

API