Build your first Anim composition

This tutorial builds a small vector scene with moving shapes, Bézier easing, repeated motion, and group transparency. You will validate the source, inspect its timing, and export frames and video.

---

Prerequisites

Install the Anim preview CLI, then verify it:

anim --version

---

1. Understanding the Anim Philosophy

Anim is a purely functional, statically typed animation language. Unlike traditional animation systems that rely on mutable state update loops or keyframe mutation, Anim operates on Signals:

Signal<T> = f(Time) -> T

Every animated attribute (position, size, opacity, or a color switch) is a pure function of time. Given the same source and exact time (t), the canonical CPU path is designed to compute the same frame without depending on playback history.

---

2. Step 1: Composing a Little Scene

Create a file named hello_anim.anim in your working directory.

Start by composing basic primitives — rectangles, ellipses, and triangles — into a little owl perched on a branch. Even this first example has a bit of life: a firefly blinks beside the owl, so the result already feels like a scene rather than a diagram:

Live canvasStep 1: A Little Owl at Night

400 × 30060 fps

Animated preview for Step 1: A Little Owl at Night.

Loading renderer…

0.00s · 1 / 1

Rendered SVGStep 1: A Little Owl at Night

Loading rendered frames…

// Step 1: primitives compose a little owl on a branch; a firefly pulses beside it.
let night = stack(children: [
  rect(x: 0px, y: 0px, width: 600px, height: 400px, fill: #0b1026),
  ellipse(x: 470px, y: 54px, width: 80px, height: 80px, fill: #fde68a),
  ellipse(x: 120px, y: 70px, width: 5px, height: 5px, fill: #fef9c3),
  ellipse(x: 360px, y: 300px, width: 4px, height: 4px, fill: #fef9c3),
  rect(x: 120px, y: 300px, width: 360px, height: 14px, fill: #4a2c12),
  ellipse(x: 236px, y: 150px, width: 128px, height: 150px, fill: #7c3f12),
  ellipse(x: 250px, y: 190px, width: 100px, height: 100px, fill: #a16207),
  ellipse(x: 244px, y: 148px, width: 54px, height: 54px, fill: #fef3c7),
  ellipse(x: 302px, y: 148px, width: 54px, height: 54px, fill: #fef3c7),
  ellipse(x: 258px, y: 162px, width: 26px, height: 26px, fill: #1f2937),
  ellipse(x: 318px, y: 162px, width: 26px, height: 26px, fill: #1f2937),
  ellipse(x: 265px, y: 167px, width: 9px, height: 9px, fill: #ffffff),
  ellipse(x: 325px, y: 167px, width: 9px, height: 9px, fill: #ffffff),
  triangle(x1: 288px, y1: 180px, x2: 312px, y2: 180px, x3: 300px, y3: 198px, fill: #f97316),
  triangle(x1: 238px, y1: 150px, x2: 258px, y2: 118px, x3: 276px, y3: 150px, fill: #7c3f12),
  triangle(x1: 324px, y1: 150px, x2: 342px, y2: 118px, x3: 362px, y3: 150px, fill: #7c3f12),
  ellipse(x: 262px, y: 292px, width: 22px, height: 14px, fill: #f97316),
  ellipse(x: 316px, y: 292px, width: 22px, height: 14px, fill: #f97316)
]);
let owl = step(before: night, after: night, at: 0s);
let brighten = tween(from: 0.15, to: 1.0, start: 0s, end: 0.7s);
let dim = tween(from: 1.0, to: 0.15, start: 0s, end: 0.7s);
let glow = repeat(signal: sequence(first: brighten, second: dim, at: 0.7s), every: 1.4s);
let firefly = opacity(value: glow, scene: stack(children: [
  ellipse(x: 408px, y: 226px, width: 28px, height: 28px, fill: #fde68a),
  ellipse(x: 416px, y: 234px, width: 12px, height: 12px, fill: #fef9c3)
]));
export let main = composition(width: 600px, height: 400px, duration: 3s, fps: 60fps, scene: stack(children: [owl, firefly]));

TerminalAfter saving the source as example.anim

anim render example.anim --range 0..120 -o frame_%04d.png

Notice that dimensional values require explicit units:

• Lengths: px (e.g. 800px, 16px)
• Time: s or ms (e.g. 2s, 500ms)
• Frame Rate: fps (e.g. 60fps)
• Colors: #rrggbb, #rrggbbaa, or rgb(0, 0, 0) with channels from 0 to 255

---

3. Step 2: Adding Motion with Signals

Next, create continuous signals using tween and a custom Bézier easing curve. A paper airplane glides into the sky and back out over three seconds, with a gentle bob so it feels like it is really flying:

Live canvasStep 2: A Gliding Paper Airplane

400 × 30060 fps

Animated preview for Step 2: A Gliding Paper Airplane.

Loading renderer…

0.00s · 1 / 1

Rendered SVGStep 2: A Gliding Paper Airplane

Loading rendered frames…

// Step 2: easing glides a paper airplane across the summer sky and back.
let sky_scene = stack(children: [
  rect(x: 0px, y: 0px, width: 600px, height: 400px, fill: #bae6fd),
  ellipse(x: 54px, y: 48px, width: 90px, height: 90px, fill: #fef9c3),
  ellipse(x: 430px, y: 92px, width: 130px, height: 46px, fill: #ffffff),
  ellipse(x: 470px, y: 70px, width: 84px, height: 62px, fill: #ffffff),
  ellipse(x: 150px, y: 320px, width: 170px, height: 60px, fill: #ffffff),
  ellipse(x: 210px, y: 300px, width: 120px, height: 60px, fill: #ffffff)
]);
let sky = step(before: sky_scene, after: sky_scene, at: 0s);
let ease_out = cubic_bezier(x1: 0.18, y1: 0.9, x2: 0.24, y2: 1.0);
let enter = tween(from: -280px, to: 0px, start: 0s, end: 1s, easing: ease_out);
let leave = tween(from: 0px, to: 280px, start: 0s, end: 2s, easing: ease_out);
let glide = sequence(first: enter, second: leave, at: 1s);
let dip_up = tween(from: 0px, to: -18px, start: 0s, end: 1s, easing: cubic_bezier(x1: 0.4, y1: 0, x2: 0.6, y2: 1));
let dip_down = tween(from: -18px, to: 0px, start: 0s, end: 1s, easing: cubic_bezier(x1: 0.4, y1: 0, x2: 0.6, y2: 1));
let bob = repeat(signal: sequence(first: dip_up, second: dip_down, at: 1s), every: 2s);
let plane = translate(x: 300px + glide, y: 196px + bob, scene: stack(children: [
  triangle(x1: 54px, y1: 0px, x2: -46px, y2: -26px, x3: -8px, y3: 2px, fill: #e2e8f0),
  triangle(x1: 54px, y1: 0px, x2: -46px, y2: 26px, x3: -8px, y3: 2px, fill: #cbd5e1),
  triangle(x1: 54px, y1: 0px, x2: -10px, y2: 2px, x3: -14px, y3: 0px, fill: #94a3b8)
]));
export let main = composition(width: 600px, height: 400px, duration: 3s, fps: 60fps, scene: stack(children: [sky, plane]));

TerminalAfter saving the source as example.anim

anim render example.anim --range 0..120 -o frame_%04d.png

Here, enter and leave are joined into one glide signal. The expression 300px + glide automatically promotes the static base position into signal arithmetic, while the Bézier curve gives the airplane its smooth swoop.

---

4. Step 3: Sequencing and Repeating Animation

Anim provides sequence and repeat to structure timelines without keyframe mutation. Here they power the calm, four-second breathing rhythm of a friendly star buddy:

Live canvasStep 3: A Breathing Star Buddy

400 × 30060 fps

Animated preview for Step 3: A Breathing Star Buddy.

Loading renderer…

0.00s · 1 / 1

Rendered SVGStep 3: A Breathing Star Buddy

Loading rendered frames…

// Step 3: sequence and repeat give a star buddy its calm breathing rhythm.
let night_scene = stack(children: [
  rect(x: 0px, y: 0px, width: 600px, height: 400px, fill: #100d1d),
  ellipse(x: 90px, y: 70px, width: 5px, height: 5px, fill: #fde68a),
  ellipse(x: 500px, y: 90px, width: 4px, height: 4px, fill: #fde68a),
  ellipse(x: 150px, y: 300px, width: 4px, height: 4px, fill: #fde68a),
  ellipse(x: 470px, y: 260px, width: 5px, height: 5px, fill: #fde68a),
  ellipse(x: 120px, y: 350px, width: 360px, height: 120px, fill: #211638)
]);
let night = step(before: night_scene, after: night_scene, at: 0s);
let grow = tween(from: 0.8, to: 1.12, start: 0s, end: 1s, easing: cubic_bezier(x1: 0.4, y1: 0, x2: 0.6, y2: 1));
let shrink = tween(from: 1.12, to: 0.8, start: 0s, end: 1s, easing: cubic_bezier(x1: 0.4, y1: 0, x2: 0.6, y2: 1));
let breath = repeat(signal: sequence(first: grow, second: shrink, at: 1s), every: 2s);
let star = translate(x: 300px, y: 188px, scene: scale(x: breath, y: breath, scene: stack(children: [
  triangle(x1: 0px, y1: -80px, x2: -64px, y2: 48px, x3: 64px, y3: 48px, fill: #fbbf24),
  triangle(x1: 0px, y1: 80px, x2: -64px, y2: -48px, x3: 64px, y3: -48px, fill: #fbbf24),
  ellipse(x: -24px, y: -18px, width: 15px, height: 19px, fill: #78350f),
  ellipse(x: 9px, y: -18px, width: 15px, height: 19px, fill: #78350f),
  ellipse(x: -15px, y: 6px, width: 30px, height: 15px, fill: #78350f)
])));
export let main = composition(width: 600px, height: 400px, duration: 4s, fps: 60fps, scene: stack(children: [night, star]));

TerminalAfter saving the source as example.anim

anim render example.anim --range 0..120 -o frame_%04d.png

---

5. Step 4: Layering and Visual Effects

Use stack to composite elements in painter's order (first child rendered at back, last child on top), then add group transparency with opacity to make a sparkling pile of treasure fade up inside an open chest:

Live canvasStep 4: A Treasure Chest Reveal

400 × 30060 fps

Animated preview for Step 4: A Treasure Chest Reveal.

Loading renderer…

0.00s · 1 / 1

Rendered SVGStep 4: A Treasure Chest Reveal

Loading rendered frames…

// Step 4: stacking and opacity reveal the sparkling treasure inside a chest.
let scene_bg = stack(children: [
  rect(x: 0px, y: 0px, width: 600px, height: 400px, fill: #1a120b),
  rect(x: 0px, y: 322px, width: 600px, height: 78px, fill: #3b2a17),
  rounded_rect(x: 200px, y: 214px, width: 200px, height: 128px, rx: 16px, ry: 16px, fill: #7c4a1e),
  rounded_rect(x: 194px, y: 150px, width: 212px, height: 72px, rx: 18px, ry: 18px, fill: #8b5a2b),
  rect(x: 200px, y: 248px, width: 200px, height: 20px, fill: #a97142),
  rounded_rect(x: 286px, y: 248px, width: 28px, height: 40px, rx: 6px, ry: 6px, fill: #fbbf24)
]);
let chest = step(before: scene_bg, after: scene_bg, at: 0s);
let appear = tween(from: 0.0, to: 1.0, start: 0s, end: 1.2s);
let treasure = opacity(value: appear, scene: translate(x: 300px, y: 210px, scene: stack(children: [
  ellipse(x: -74px, y: -6px, width: 148px, height: 42px, fill: #f59e0b),
  ellipse(x: -44px, y: -18px, width: 32px, height: 32px, fill: #fbbf24),
  ellipse(x: -8px, y: -24px, width: 32px, height: 32px, fill: #fde047),
  ellipse(x: 26px, y: -16px, width: 28px, height: 28px, fill: #fbbf24),
  triangle(x1: 0px, y1: -46px, x2: -16px, y2: -24px, x3: 16px, y3: -24px, fill: #f43f5e),
  triangle(x1: 0px, y1: -6px, x2: -16px, y2: -24px, x3: 16px, y3: -24px, fill: #fb7185)
])));
let up = tween(from: 0.6, to: 1.3, start: 0s, end: 0.5s);
let down = tween(from: 1.3, to: 0.6, start: 0s, end: 0.5s);
let twinkle = repeat(signal: sequence(first: up, second: down, at: 0.5s), every: 1s);
let sparkle = opacity(value: appear, scene: translate(x: 300px, y: 138px, scene: scale(x: twinkle, y: twinkle, scene: stack(children: [
  triangle(x1: 0px, y1: -22px, x2: -7px, y2: 0px, x3: 7px, y3: 0px, fill: #fffbeb),
  triangle(x1: 0px, y1: 22px, x2: -7px, y2: 0px, x3: 7px, y3: 0px, fill: #fffbeb),
  triangle(x1: -22px, y1: 0px, x2: 0px, y2: -7px, x3: 0px, y3: 7px, fill: #fffbeb),
  triangle(x1: 22px, y1: 0px, x2: 0px, y2: -7px, x3: 0px, y3: 7px, fill: #fffbeb)
]))));
export let main = composition(width: 600px, height: 400px, duration: 3s, fps: 60fps, scene: stack(children: [chest, treasure, sparkle]));

TerminalAfter saving the source as example.anim

anim render example.anim --range 0..120 -o frame_%04d.png

---

6. Step 5: Exporting the Main Composition

Every executable .anim document must export exactly one binding named main of type composition:

export let main = composition(
  width: 800px,
  height: 600px,
  duration: 4s,
  fps: 60fps,
  scene: scene_content
);

The composition binds together render target dimensions, continuous timeline duration, canonical frame rate, and the root scene tree.

---

7. Step 6: Validating and Inspecting Your Source

At each step, replace the contents of hello_anim.anim with the complete source shown in that step. After Step 4, use the CLI to check it for syntax, type, or unit errors:

anim check hello_anim.anim

If successful, anim check exits cleanly with code 0. Next, inspect the composition parameters and timing metadata:

anim inspect hello_anim.anim --json

Output:

{
  "schema_version": 1,
  "compositions": [
    {
      "name": "main",
      "width": 600,
      "height": 400,
      "duration": {
        "numerator": 3,
        "denominator": 1,
        "unit": "seconds"
      },
      "frame_rate": {
        "numerator": 60,
        "denominator": 1,
        "unit": "frames_per_second"
      },
      "frame_count": 180
    }
  ]
}

---

8. Step 7: Rendering Frames and Videos

Rendering a Single Frame

To render frame 60 (at 1.0 second) as a PNG image:

anim render hello_anim.anim --frame 60 -o frame_60.png

Rendering a Sequence of Frames

To render frames 0 through 120 as a numbered sequence:

Create the destination directory, then render the complete half-open frame range:

mkdir -p frames
anim render hello_anim.anim --range 0..180 -o frames/frame_%04d.png

Rendering Video Output

To render the entire three-second animation as an MP4 or WebM video:

Video export requires a local FFmpeg installation:

anim render hello_anim.anim --range 0..180 -o output.mp4 --video raster --background "#000000"

---

Summary

Congratulations! You have completed the Anim tutorial. You learned how to:

1. Compose expressive scene geometry with explicit units (px, #hex, s, fps).
2. Build smooth continuous signals with tween and cubic_bezier.
3. Construct complex timelines with sequence and repeat.
4. Composite scenes with stack, translate, scale, and opacity.
5. Export main: composition.
6. Use anim check, anim inspect, and anim render CLI commands.

Proceed to the How-to Guides for specialized workflows such as Lottie JSON import and 2D Mesh Deformation physics!