effect-motion
Guides

Use the CLI

Scaffold a project, preview scenes with hot reload, and render videos

The CLI is one command each for scaffolding, previewing, and rendering, driven by two code entrypoints instead of a config file:

bun create effect-motion

The wizard asks where to create the project, which package manager to use, and whether to set up Biome, then installs a ready-to-run project:

my-project/
├─ src/
│  ├─ scenes/hello-world.ts   # a scene: a module exporting `scene`
│  ├─ assets/                 # static files
│  └─ main.ts                 # the movie — a scene composing the others
├─ studio.ts                  # what `motion studio` previews
├─ render.ts                  # what `motion render` executes
├─ AGENTS.md                  # authoring rules for AI coding agents
├─ package.json               # exact pins of effect-motion + effect
└─ tsconfig.json

Versions are pinned exactly on purpose: the effect pin is a determinism invariant (upgrading effect can change seeded random sequences), so a scaffolded project upgrades both together, deliberately.

Both entrypoints are ordinary TypeScript that imports your scenes as values — which is what makes typed resources work end to end: a scene that declares fonts or images carries that requirement in its type, and the entrypoint won't compile until the loaders are provided.

Preview — studio.ts

motion studio                    # serves ./studio.ts
motion studio ./other.studio.ts

studio.ts default-exports the studio's registration — a record of scenes, plus one layers covering all of them once any scene declares resources:

studio.ts
import { studioConfig } from "@effect-motion/cli";
import { scene as main } from "./src/main";
import { scene as helloWorld } from "./src/scenes/hello-world";

export default studioConfig({
	scenes: {
		"hello-world": helloWorld,
		main: { scene: main, fps: 30 }, // per-entry player options
	},
	// layers: Layer.mergeAll(Font.layer(…), Image.layer(…)),
});

Only registered scenes appear — registration is one import and one entry, and it's what lets the compiler prove layers covers every scene. Hot reload is plain Vite HMR over the entrypoint's import graph.

Render — render.ts

motion render                  # executes ./render.ts
motion render ./teaser.render.ts

render.ts is an ordinary program: it calls the export API and default-exports the effect. The CLI provides the platform and runs it — nothing more:

render.ts
import { Video } from "@effect-motion/export";
import * as Effect from "effect/Effect";
import { scene as main } from "./src/main";

export default Effect.gen(function* () {
	yield* Video.render(main, "./output/main.mp4", {
		settings: { frameRate: 60 },
	});
});

There are no render flags: code is the config. Knobs you'd reach for as flags (fps, seed, dpr, output paths) are values in render.ts — read process.env there if you want them switchable. The same file runs without the CLI: provide NodeServices.layer from @effect/platform-node and run it with tsx render.ts. --verbose prints full error cause chains.

Sample frames — motion frames

motion frames                          # list the scenes in ./studio.ts with their lengths
motion frames hello-world              # 6 evenly spaced PNG stills
motion frames hello-world --at 0,1.5s,50%,end
motion frames hello-world --count 9 --sheet
motion frames hello-world --count 5 --range 1s..2s --sheet
motion frames hello-world --at 50% --json -

motion frames renders chosen frames of a scene registered in studio.ts headlessly — no browser, no video. It runs the scene with the same settings the studio uses for that entry (fps, layers).

FlagMeaning
--at <selection>Comma-separated frames: an index (30), a time (1.5s, 500ms), a percentage (50%), or end
--count <n>n evenly spaced frames, first and last included (default 6; clamps to every frame once)
--range <from>..<to>Spread --count over this span instead of the whole scene, both ends included; each end is any single selector (7.5s..8.5s, 50%..end, 120..180)
--sheetWrite one contact sheet (sheet.png) instead of stills
--json <path|->Write frame state as JSON to a file, or to stdout with -
--out <dir>Output directory (default .motion/frames/<scene>/)
--dpr <n>Supersampling factor for PNGs (default 1)
--tile-width <px>Max width of each sheet tile; larger frames are downscaled, aspect kept (default 480)
--studio <file>Studio entrypoint (default ./studio.ts)

With no scene, it lists every scene key with its length in frames and seconds (each scene is run once to measure it; nothing is rendered).

Pass --at or --count/--range, not both. A time maps to frame round(seconds × frameRate); frame 0 is the first rendered frame.

  • Stills (the default) are written as <frame>.png (e.g. 0015.png), one per distinct frame; each path is printed with its frame and time.
  • --sheet lays the frames out row-major in one grid and prints tile=<i> frame=<f> time=<t> for every tile. Tiles are at most 480 px wide by default, so a nine-tile sheet of a 1080p scene stays around 1450 px wide; raise --tile-width for detail.
  • --json writes, per sampled frame, its index, time, width, height, frame rate, camera, and every instance's data. With --json alone no PNGs are written and the GPU renderer is never loaded. With -, stdout carries only the JSON; other output goes to stderr. Combine with --sheet to get both.

Fonts and images come from the studio's layers, the same ones the studio previews with; stills and sheets need them, JSON does not.

The scene ends where its video ends: once the body and every fork are done. end is that last frame; backgrounds and tails still running after Scene.finish are cut there, in the video and the player too, so no sheet shows them.

%, end and --count without --range need the scene's length, so they fail for an infinite scene; indices, times and ranges of them still work. Out-of-range frames, bad selectors and unknown scene keys exit non-zero with a message naming the offender. See Preview frames without a browser for the edit–check loop.

On this page