Velato API Reference

Overview

Velato parses Lottie JSON animations and renders them to vello Scenes. Core workflow: parse JSON → create renderer → render frames.

Quick Reference

Type	Purpose
`Composition`	Parsed Lottie animation model
`Renderer`	Renders composition to graphics
`RenderSink`	Trait for custom backends (vello::Scene implements it)

Parsing

rust

use velato::Composition;

// From string (implements FromStr)
let comp = Composition::from_str(json_str)?;
let comp: Composition = json_str.parse()?;  // Also works

// From bytes
let comp = Composition::from_slice(bytes)?;

// From serde_json::Value
let comp = Composition::from_json(value)?;

Composition Fields

rust

comp.frames      // Range<f64> - valid frame range [start, end)
comp.frame_rate  // f64 - frames per second
comp.width       // usize - canvas width
comp.height      // usize - canvas height

Rendering

rust

use velato::{Composition, Renderer};
use velato::vello::kurbo::Affine;

let mut renderer = Renderer::new();

// Convenience method - returns new Scene
let scene = renderer.render_to_vello_scene(&comp, frame, Affine::IDENTITY, 1.0);

// Or append to existing scene
let mut scene = vello::Scene::new();
renderer.append(&comp, frame, Affine::IDENTITY, 1.0, &mut scene);

Animation Loop Pattern

rust

use std::time::Instant;  // or `instant::Instant` for WASM compatibility

let start = Instant::now();
let mut renderer = Renderer::new();

// In render callback:
let elapsed = start.elapsed().as_secs_f64();
let frame_offset = (elapsed * comp.frame_rate) % (comp.frames.end - comp.frames.start);
let frame = comp.frames.start + frame_offset;  // IMPORTANT: add frames.start

let scene = renderer.render_to_vello_scene(&comp, frame, Affine::IDENTITY, 1.0);

Common Mistakes

Mistake	Fix
Forgetting `frames.start` offset	Always add `comp.frames.start` to calculated frame
Creating new Renderer per frame	Reuse single Renderer instance
Using frame outside valid range	Ensure `comp.frames.contains(&frame)`
Using alpha as percentage (0-100)	Alpha is normalized (0.0-1.0), not percentage

Re-exports

rust

use velato::vello;           // vello crate (when feature="vello")
use velato::vello::kurbo;    // kurbo geometry types
use velato::model;           // runtime model types (Layer, Content, etc.)

Unsupported Features

Position keyframe (ti, to) easing, time remapping (tm), text layers, image embedding, advanced shapes (stroke dash, zig-zag), advanced effects (motion blur, drop shadows), correct color stop handling, split rotations, split positions.