Export a video
Turn a scene into an MP4 with @effect-motion/export — bundled ffmpeg, no system install
A scene is a stream of frames; @effect-motion/export turns it into a file.
The pipeline is Scene.stream → the GPU renderer (headless WebGPU in Node) →
PNG frames → ffmpeg → H.264 MP4, with no intermediate files touching disk.
One call
import { NodeServices } from "@effect/platform-node";
import { Video } from "@effect-motion/export";
import * as Effect from "effect/Effect";
import { scene } from "./my-scene";
Video.render(scene, "./output/my-scene.mp4").pipe(
Effect.provide(NodeServices.layer),
Effect.runPromise,
);Video.render reads the frame rate and dimensions from the scene's own
frame metadata — you never repeat them. Output directories are created for
you, and the result is broadly playable by default: H.264, yuv420p,
faststart. What the Player showed is what the
file contains — both consume the same frames through the same renderer.
Options
settings— per-export scene settings:frameRate, andmaxFrames(setInfinityfor an intentionally infinite scene).frames— cap the number of frames encoded. An infinite scene must set this; without it the encode runs forever.dpr— supersampling: frames render at scene dimensions × dpr while the scene keeps its authored coordinates.dpr: 2turns a 1920×1080 scene into a 4K video.binary— override the ffmpeg binary. Defaults to the bundledffmpeg-staticbuild; pass"ffmpeg"(or a path) to use your own.extraArgs— appended before the output path, e.g.["-crf", "18"]for higher quality.
Even dimensions
yuv420p requires even output dimensions (width × dpr, height × dpr).
Video.render checks before spawning ffmpeg and fails with an EncodeError
rather than silently resizing.
Fonts, images, and audio
Typed resources work the same here as in the player: provide the loader
layers with Effect.provide. In Node the load effects can read bytes from
disk — no URLs needed. Forgetting a loader is a compile error in this file,
not a runtime surprise. For a duration-driven sound scene, use
Video.prepareAudio to prepare bytes and metadata together; see
Add sound to a scene. An audio-pass failure raises
EncodeError and may leave a video-only file at the requested path. Treat
that file as an incomplete render.
ffmpeg is bundled
Installing @effect-motion/export downloads a full ffmpeg build (including
libx264) for your platform — H.264 works out of the box. The bundled build
is GPL-licensed: a standalone executable invoked over a process boundary,
not linked into your code. Pass binary if you'd rather ship your own.
Lower-level pieces
Video.render is the composed path; its pieces are exported for custom
pipelines — Ffmpeg.encode(pngStream, outPath, options) encodes any
Stream of PNG frames, and @effect-motion/renderer/node exposes the
headless renderer that produces them.