@effect-motion/export 0.2.0

package/README.md

@@ -0,0 +1,35 @@
+# @effect-motion/export
+
+Node-only export tools for [effect-motion](https://www.npmjs.com/package/effect-motion): rasterize SVG frames to PNG (via [resvg](https://github.com/RazrFalcon/resvg)) and encode them into a video file (via ffmpeg).
+
+This package is for **server-side rendering** (Node). Browser playback lives in `@effect-motion/react` and does not depend on this package.
+
+## Usage
+
+```ts
+import { NodeServices } from "@effect/platform-node";
+import { Effect } from "effect";
+import { Video } from "@effect-motion/export";
+
+// scene → MP4, one call
+await Effect.runPromise(
+  Video.render(scene, "out.mp4", {
+    settings: { width: 1920, height: 1080, frameRate: 60 },
+  }).pipe(Effect.provide(NodeServices.layer)),
+);
+```
+
+`Ffmpeg.encode` and `Resvg.rasterize` are the lower-level stages if you want to drive the pipeline yourself.
+
+## Bundled ffmpeg
+
+Video encoding uses the [`ffmpeg-static`](https://www.npmjs.com/package/ffmpeg-static) binary by default — a full build that includes **libx264**, so H.264 output works out of the box with no system ffmpeg required. Installing this package downloads that binary (~45 MB) for your platform.
+
+To use a system or custom ffmpeg instead, pass `binary`:
+
+```ts
+Video.render(scene, "out.mp4", { binary: "ffmpeg" });        // system ffmpeg on PATH
+Video.render(scene, "out.mp4", { binary: "/path/to/ffmpeg" }); // a specific build
+```
+
+> **License note.** The `ffmpeg-static` build (and libx264) is **GPL-3.0**. It is a standalone executable this package invokes over a process boundary — it is not linked into effect-motion's own code, which stays MIT. If you redistribute the bundled binary, the ffmpeg/libx264 GPL terms apply to that binary; pass your own `binary` to avoid shipping it.

package/dist/Ffmpeg.d.ts

@@ -0,0 +1,45 @@
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+import { ChildProcessSpawner } from "effect/unstable/process";
+type Spawner = ChildProcessSpawner.ChildProcessSpawner;
+/** Options for {@link encode}. */
+export interface EncodeOptions {
+    /** Input framerate handed to ffmpeg (`-framerate`). */
+    readonly frameRate: number;
+    /**
+     * ffmpeg binary; defaults to the bundled `ffmpeg-static` build (falling
+     * back to `"ffmpeg"` on PATH). Set to `"ffmpeg"` or a path to use a
+     * system/custom ffmpeg instead.
+     */
+    readonly binary?: string | undefined;
+    /**
+     * Extra ffmpeg arguments appended before the output path — e.g.
+     * `["-crf", "18"]` or a `-vf` scale filter. Escape hatch for the codec
+     * surface this wrapper does not model.
+     */
+    readonly extraArgs?: ReadonlyArray<string> | undefined;
+}
+declare const EncodeError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "EncodeError";
+} & Readonly<A>;
+/**
+ * A failure encoding a video: ffmpeg not spawnable (not installed / not on
+ * PATH), or a nonzero exit. `stderr` carries ffmpeg's diagnostics when the
+ * process ran; it is empty when the binary could not be spawned at all.
+ */
+export declare class EncodeError extends EncodeError_base<{
+    readonly message: string;
+    readonly stderr: string;
+    readonly cause: unknown;
+}> {
+}
+/**
+ * Encode a stream of PNG frames into a video file at `outPath`.
+ *
+ * Pipes the PNG bytes into ffmpeg's stdin via the `image2pipe` demuxer;
+ * when the stream ends, stdin closes and ffmpeg finalizes the file. A
+ * nonzero exit or an unspawnable binary fails with a tagged
+ * {@link EncodeError}.
+ */
+export declare const encode: (pngStream: Stream.Stream<Uint8Array>, outPath: string, options: EncodeOptions) => Effect.Effect<void, EncodeError, Spawner>;
+export {};

package/dist/Ffmpeg.js

@@ -0,0 +1,90 @@
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Stream from "effect/Stream";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import ffmpegStatic from "ffmpeg-static";
+/**
+ * ffmpeg encoding is an export tool, not a renderer: it consumes the PNG
+ * frames the rasterizer produces and pipes them into ffmpeg over stdin
+ * (`-f image2pipe`), yielding a video file. No frame touches disk.
+ *
+ * By default the bundled `ffmpeg-static` binary is used (a full build with
+ * libx264, so H.264 works out of the box); `binary` overrides it to point
+ * at a system or custom ffmpeg. If the bundle is unavailable for the host
+ * platform, it falls back to `"ffmpeg"` on PATH. Process spawning goes
+ * through the `ChildProcessSpawner` service — the consumer provides it
+ * (e.g. `NodeServices.layer` from `@effect/platform-node`), the same way
+ * `Resvg.rasterizeToFile` takes a consumer-provided `FileSystem`.
+ */
+// the bundled ffmpeg (null only on a platform ffmpeg-static doesn't ship)
+const bundledFfmpeg = ffmpegStatic;
+/**
+ * A failure encoding a video: ffmpeg not spawnable (not installed / not on
+ * PATH), or a nonzero exit. `stderr` carries ffmpeg's diagnostics when the
+ * process ran; it is empty when the binary could not be spawned at all.
+ */
+export class EncodeError extends Data.TaggedError("EncodeError") {
+}
+// broadly-playable defaults: H.264 8-bit, faststart MP4 for progressive
+// playback. Flags chosen to be stable across every maintained ffmpeg (4.x+).
+const outputArgs = [
+    "-c:v",
+    "libx264",
+    "-pix_fmt",
+    "yuv420p",
+    "-movflags",
+    "+faststart",
+];
+const decoder = new TextDecoder();
+/**
+ * Encode a stream of PNG frames into a video file at `outPath`.
+ *
+ * Pipes the PNG bytes into ffmpeg's stdin via the `image2pipe` demuxer;
+ * when the stream ends, stdin closes and ffmpeg finalizes the file. A
+ * nonzero exit or an unspawnable binary fails with a tagged
+ * {@link EncodeError}.
+ */
+export const encode = (pngStream, outPath, options) => Effect.gen(function* () {
+    const binary = options.binary ?? bundledFfmpeg ?? "ffmpeg";
+    const args = [
+        "-f",
+        "image2pipe",
+        "-framerate",
+        String(options.frameRate),
+        "-i",
+        "-",
+        ...outputArgs,
+        ...(options.extraArgs ?? []),
+        "-y",
+        outPath,
+    ];
+    const command = ChildProcess.make(binary, args, {
+        // PlatformError from the stdin pipe would otherwise leak into the
+        // stream's error channel; the stream elements are pure PNG bytes,
+        // so this cast only re-labels the (unreachable) error type
+        stdin: pngStream,
+        stdout: "ignore",
+        stderr: "pipe",
+    });
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+    yield* Effect.scoped(Effect.gen(function* () {
+        const handle = yield* spawner.spawn(command);
+        // collect stderr concurrently: an unconsumed stderr pipe can
+        // fill and deadlock ffmpeg, and it is the error diagnostic
+        const stderrFiber = yield* Effect.forkChild(Stream.runFold(handle.stderr, () => "", (acc, chunk) => acc + decoder.decode(chunk)));
+        const code = yield* handle.exitCode;
+        const stderr = yield* Fiber.join(stderrFiber);
+        if (code !== 0) {
+            return yield* new EncodeError({
+                message: `ffmpeg exited with code ${code}`,
+                stderr,
+                cause: code,
+            });
+        }
+    })).pipe(Effect.catchTag("PlatformError", (cause) => Effect.fail(new EncodeError({
+        message: `Could not run "${binary}". Install ffmpeg and ensure it is on your PATH (or pass options.binary).`,
+        stderr: "",
+        cause,
+    }))));
+});

package/dist/Fonts.d.ts

@@ -0,0 +1,12 @@
+import type { ResvgRenderOptions } from "@resvg/resvg-js";
+import type * as Context from "effect/Context";
+/**
+ * Map a scene's declared fonts (the `Fonts` annotation) to resvg font
+ * options: every entry with a `src.path` becomes a `fontFiles` entry.
+ * Url-only entries are a browser concern and are skipped. System fonts
+ * stay loaded (resvg's default) — declared fonts ADD faces; pass
+ * `loadSystemFonts: false` yourself for fully self-contained output.
+ */
+export declare const resvgOptions: (scene: {
+    readonly annotations: Context.Context<never>;
+}) => ResvgRenderOptions;

package/dist/Fonts.js

@@ -0,0 +1,12 @@
+import { Fonts } from "effect-motion";
+/**
+ * Map a scene's declared fonts (the `Fonts` annotation) to resvg font
+ * options: every entry with a `src.path` becomes a `fontFiles` entry.
+ * Url-only entries are a browser concern and are skipped. System fonts
+ * stay loaded (resvg's default) — declared fonts ADD faces; pass
+ * `loadSystemFonts: false` yourself for fully self-contained output.
+ */
+export const resvgOptions = (scene) => {
+    const fontFiles = Fonts.get(scene).flatMap((font) => font.src.path === undefined ? [] : [font.src.path]);
+    return fontFiles.length === 0 ? {} : { font: { fontFiles } };
+};

package/dist/Resvg.d.ts

@@ -0,0 +1,27 @@
+import { type ResvgRenderOptions } from "@resvg/resvg-js";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import type * as PlatformError from "effect/PlatformError";
+/**
+ * Thin Effect wrappers over resvg. Rasterization is an export tool, not a
+ * renderer: it consumes the SVG document strings the string sink produces
+ * (or any other SVG) and yields PNG bytes.
+ */
+/** resvg's own options, untranslated — font config and fitTo live here */
+export type { ResvgRenderOptions } from "@resvg/resvg-js";
+declare const RasterizeError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "RasterizeError";
+} & Readonly<A>;
+/** A failure raised by resvg while parsing or rendering an SVG document. */
+export declare class RasterizeError extends RasterizeError_base<{
+    readonly cause: unknown;
+}> {
+}
+/**
+ * Rasterize an SVG document string to PNG bytes. Output dimensions come
+ * from the document itself; the string sink stamps the frame's
+ * width/height on the root.
+ */
+export declare const rasterize: (svg: string, options?: ResvgRenderOptions) => Effect.Effect<Uint8Array, RasterizeError>;
+/** `rasterize`, then persist through the FileSystem service. */
+export declare const rasterizeToFile: (svg: string, path: string, options?: ResvgRenderOptions) => Effect.Effect<void, RasterizeError | PlatformError.PlatformError, FileSystem.FileSystem>;

package/dist/Resvg.js

@@ -0,0 +1,22 @@
+import { Resvg as ResvgJs } from "@resvg/resvg-js";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+/** A failure raised by resvg while parsing or rendering an SVG document. */
+export class RasterizeError extends Data.TaggedError("RasterizeError") {
+}
+/**
+ * Rasterize an SVG document string to PNG bytes. Output dimensions come
+ * from the document itself; the string sink stamps the frame's
+ * width/height on the root.
+ */
+export const rasterize = (svg, options) => Effect.try({
+    try: () => new Uint8Array(new ResvgJs(svg, options ?? null).render().asPng()),
+    catch: (cause) => new RasterizeError({ cause }),
+});
+/** `rasterize`, then persist through the FileSystem service. */
+export const rasterizeToFile = (svg, path, options) => Effect.gen(function* () {
+    const bytes = yield* rasterize(svg, options);
+    const fs = yield* FileSystem.FileSystem;
+    yield* fs.writeFile(path, bytes);
+});

package/dist/Video.d.ts

@@ -0,0 +1,54 @@
+import * as Effect from "effect/Effect";
+import type * as Scope from "effect/Scope";
+import type { ChildProcessSpawner } from "effect/unstable/process";
+import { type Entity, Scene } from "effect-motion";
+import * as Ffmpeg from "./Ffmpeg";
+import * as Resvg from "./Resvg";
+type SceneRunner = typeof Scene.tick extends Effect.Effect<unknown, unknown, infer RR> ? RR : never;
+type SceneInternalR = SceneRunner | Scope.Scope;
+/**
+ * The one-call export path: a scene becomes a video file. Composes the whole
+ * pipeline — `Scene.stream` → SVG string sink → resvg → ffmpeg — reading the
+ * framerate and dimensions from the scene's own frame metadata and feeding
+ * declared fonts to the rasterizer.
+ */
+/**
+ * Scene settings honored by the export path — a subset of the runner's
+ * settings, passed through to `Scene.stream`. Framerate and dimensions set
+ * here become the video's framerate and dimensions.
+ */
+export interface VideoSceneSettings {
+    readonly frameRate?: number;
+    readonly width?: number;
+    readonly height?: number;
+    /** Set to `Infinity` for an intentionally infinite scene (with `frames`). */
+    readonly maxFrames?: number;
+}
+/** Options for {@link render}. */
+export interface VideoOptions {
+    /**
+     * Cap the number of frames encoded. WITHOUT it, a scene that never ends
+     * produces an encode that never ends — an infinite scene must set this.
+     */
+    readonly frames?: number;
+    /**
+     * ffmpeg binary; defaults to the bundled `ffmpeg-static` build (falls
+     * back to `"ffmpeg"` on PATH). Pass `"ffmpeg"` or a path for a
+     * system/custom ffmpeg.
+     */
+    readonly binary?: string;
+    /** Extra ffmpeg arguments, appended before the output path. */
+    readonly extraArgs?: ReadonlyArray<string>;
+    /** How many frames to rasterize concurrently (order preserved). Default 4. */
+    readonly concurrency?: number;
+    /** Scene framerate/dimensions/maxFrames for this export. */
+    readonly settings?: VideoSceneSettings;
+}
+/**
+ * Render a scene to a video file at `outPath`.
+ *
+ * Fails with {@link Ffmpeg.EncodeError} on odd output dimensions (invalid for
+ * `yuv420p`) — before any ffmpeg process is spawned — or on an ffmpeg failure.
+ */
+export declare const render: <E, R, Entities extends Entity.AnyEntity>(scene: Scene.Scene<E, R, Entities>, outPath: string, options?: VideoOptions) => Effect.Effect<void, E | Ffmpeg.EncodeError | Resvg.RasterizeError, Exclude<R, Scope.Scope | SceneInternalR> | ChildProcessSpawner.ChildProcessSpawner>;
+export {};

package/dist/Video.js

@@ -0,0 +1,53 @@
+import { Layer } from "effect";
+import * as Effect from "effect/Effect";
+import * as Sink from "effect/Sink";
+import * as Stream from "effect/Stream";
+import { Scene, Svg } from "effect-motion";
+import * as Ffmpeg from "./Ffmpeg";
+import { resvgOptions } from "./Fonts";
+import * as Resvg from "./Resvg";
+// SVG string sink + built-in shape renderers, provided internally so callers
+// don't wire renderers for the export path
+const renderLayer = Svg.layer.pipe(Layer.provideMerge(Svg.shapesLayer));
+/**
+ * Render a scene to a video file at `outPath`.
+ *
+ * Fails with {@link Ffmpeg.EncodeError} on odd output dimensions (invalid for
+ * `yuv420p`) — before any ffmpeg process is spawned — or on an ffmpeg failure.
+ */
+export const render = (scene, outPath, options = {}) => Effect.scoped(Effect.gen(function* () {
+    const renderer = yield* Svg.SvgRenderer.Context;
+    const fontOpts = resvgOptions(scene);
+    const concurrency = options.concurrency ?? 4;
+    let frames = Scene.stream(scene, options.settings ?? {});
+    if (options.frames !== undefined) {
+        frames = Stream.take(frames, options.frames);
+    }
+    // peel the first frame for metadata (framerate → ffmpeg -framerate,
+    // dimensions → yuv420p even-size check) before spawning ffmpeg
+    const [first, rest] = yield* Stream.peel(frames, Sink.head());
+    if (first._tag === "None") {
+        return; // empty scene: nothing to encode
+    }
+    const meta = first.value;
+    if (meta.width % 2 !== 0 || meta.height % 2 !== 0) {
+        const odd = meta.width % 2 !== 0
+            ? `width ${meta.width}`
+            : `height ${meta.height}`;
+        return yield* new Ffmpeg.EncodeError({
+            message: `Video dimensions must be even for yuv420p, got ${odd}. ` +
+                `Use even scene dimensions, or pass extraArgs with a scale filter.`,
+            stderr: "",
+            cause: meta,
+        });
+    }
+    const allFrames = Stream.concat(Stream.make(meta), rest);
+    const pngStream = Stream.mapEffect(allFrames, (frame) => renderer
+        .render(frame, {})
+        .pipe(Effect.flatMap((svg) => Resvg.rasterize(svg, fontOpts))), { concurrency });
+    yield* Ffmpeg.encode(pngStream, outPath, {
+        frameRate: meta.frameRate,
+        binary: options.binary,
+        extraArgs: options.extraArgs,
+    });
+})).pipe(Effect.provide(renderLayer));

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * as Ffmpeg from "./Ffmpeg";
+export { EncodeError, type EncodeOptions } from "./Ffmpeg";
+export * as Fonts from "./Fonts";
+export * as Resvg from "./Resvg";
+export { RasterizeError, type ResvgRenderOptions } from "./Resvg";
+export type { VideoOptions } from "./Video";
+export * as Video from "./Video";

package/dist/index.js

@@ -0,0 +1,6 @@
+export * as Ffmpeg from "./Ffmpeg";
+export { EncodeError } from "./Ffmpeg";
+export * as Fonts from "./Fonts";
+export * as Resvg from "./Resvg";
+export { RasterizeError } from "./Resvg";
+export * as Video from "./Video";

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@effect-motion/export",
+  "version": "0.2.0",
+  "description": "Node-only export tools for effect-motion: rasterize SVG frames to PNG via resvg",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/julia-script/effect-motion.git",
+    "directory": "packages/export"
+  },
+  "homepage": "https://github.com/julia-script/effect-motion#readme",
+  "bugs": "https://github.com/julia-script/effect-motion/issues",
+  "keywords": [
+    "effect",
+    "motion",
+    "export",
+    "svg",
+    "png",
+    "ffmpeg",
+    "video"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@resvg/resvg-js": "^2.6.2",
+    "ffmpeg-static": "^5.3.0",
+    "effect-motion": "^0.2.0"
+  },
+  "peerDependencies": {
+    "effect": ">=4.0.0-beta.94"
+  },
+  "devDependencies": {
+    "@effect/platform-node": "4.0.0-beta.94",
+    "@types/node": "^26.1.1",
+    "effect": "4.0.0-beta.94",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch --preserveWatchOutput",
+    "test": "vitest run",
+    "check": "tsc --noEmit"
+  }
+}