@tongue-core/sdk 0.1.0-rc.1 → 0.1.0-rc.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Backpine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -51,7 +51,7 @@ await Effect.runPromise(program.pipe(Effect.provide(BunServices.layer)));
 | `describeFilm(film)` | the plan as text (for agents to read) and as a JSON summary |
 | `checkFilm(path)` | problems and warnings as data |
 | `renderStills(film, { frames, scale, outDir })` / `renderSheet(…)` | PNGs drawn by the wasm raster (the player's), or tiled into one labelled sheet |
-| `renderVideo(film, options)` | an MP4 with sound: the whole film or `[from, to)`, at any scale |
+| `renderVideo(film, options)` | an MP4 with sound: the whole film or `[from, to)`, at any scale; `onStart` once the request is checked and the raster and encoder are chosen, `onProgress` while it draws. A frame that throws fails the render with `Frame <n>: <message>` |
 | `listBackends()` | every raster and encoder, each tried for real |
 | `studioServer(path, { port, remote })` | the studio on a project (rebuilt and reloaded on every edit) or on a build served anywhere |
 
@@ -67,8 +67,11 @@ browser fetches it). `.tongue/types/film` links to the SDK's `@tongue-core/film`
 project's `tsconfig.json` points editors at.
 
 A **film module** (the way films were written before projects) is a `film.tsx` in a folder with a
-`package.json`, which installs `@tongue-core/film` and compiles JSX for it
-(`"jsx": "react-jsx", "jsxImportSource": "@tongue-core/film"`). It is imported and planned directly.
+`package.json`. The SDK bundles it with Bun (into `.tongue/modules/`, JSX compiled for Tongue) against
+its own `@tongue-core/film`, the copy the engine reads, as it links a project's bundles, then plans
+it. The folder may install `@tongue-core/film` too, for its editor's types
+(`"jsx": "react-jsx", "jsxImportSource": "@tongue-core/film"` in its tsconfig); that copy isn't the one
+that runs.
 
 Either way, asset paths are relative to the root, Tongue writes `.tongue/` there (imported assets,
 builds, render work) and renders to `out/`.

package/dist/encode/encoders.d.ts

@@ -23,7 +23,8 @@ export interface EncoderSpec {
     /** The filter from the raw input to what the encoder takes (uploads to the GPU). */
     readonly filter: string | null;
     readonly encode: ReadonlyArray<string>;
-    /** AMD's HEVC encoder writes no conformance window, so 1080 rows decode as 1088. */
+    /** AMD's HEVC encoder pads the picture and writes no conformance window, or a wrong one, so 1080
+     *  rows decode as 1088 and 540 columns as 572: the window is set again when muxing. */
     readonly fixCrop: boolean;
 }
 /** Where ffmpeg and ffprobe are. */

package/dist/encode/encoders.js

@@ -23,10 +23,12 @@ async function run(cmd) {
 /** Muxes a raw HEVC stream into the MP4, setting the conformance window (no re-encode) when the
  *  driver padded the picture. Done on the raw stream: an MP4 already carries the unpadded size. */
 async function muxHevc(tools, raw, target) {
-    const probe = await run([tools.ffprobe, "-v", "error", "-select_streams", "v", "-show_frames", "-read_intervals", "%+#1", "-show_entries", "frame=width,height", "-of", "csv=p=0", raw]);
+    // From the coded size, not the decoded one: hevc_metadata replaces the stream's window, and the
+    // driver sometimes writes part of one (540 across is coded as 576 and windowed to 572).
+    const probe = await run([tools.ffprobe, "-v", "error", "-select_streams", "v", "-show_entries", "stream=coded_width,coded_height", "-of", "csv=p=0", raw]);
     const [width = 0, height = 0] = (probe.stdout.trim().split("\n")[0] ?? "").split(",").map(Number);
     if (width < target.width || height < target.height)
-        throw new EncoderError(`${raw} decodes at ${width}×${height}, smaller than ${target.width}×${target.height}.`);
+        throw new EncoderError(`${raw} is coded at ${width}×${height}, smaller than ${target.width}×${target.height}.`);
     const crop = width !== target.width || height !== target.height ? ["-bsf:v", `hevc_metadata=crop_right=${width - target.width}:crop_bottom=${height - target.height}`] : [];
     const mux = await run([tools.ffmpeg, "-hide_banner", "-v", "error", "-y", "-framerate", String(target.fps), "-i", raw, "-c", "copy", ...crop, "-tag:v", "hvc1", target.out]);
     if (mux.code !== 0)

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export type { FilmSource } from "./render/protocol.js";
 export { importAssets, type ImportReport } from "./import/importer.js";
 export { checkFilm, type CheckReport, type CheckProblem } from "./check.js";
 export { renderStills, renderSheet, type StillsOptions, type Still } from "./render/stills.js";
-export { renderVideo, defaultWorkers, type VideoOptions, type VideoResult } from "./render/pipeline.js";
+export { renderVideo, defaultWorkers, type RenderStart, type VideoOptions, type VideoResult } from "./render/pipeline.js";
 export { listBackends, type BackendsReport } from "./backends.js";
 export { studioServer, type StudioOptions } from "./studio/server.js";
 export { ENCODER_NAMES, AUTO_ENCODERS, DEFAULT_SETTINGS, isEncoderName, type EncoderName, type EncoderSettings } from "./encode/encoders.js";

package/dist/project.js

@@ -37,7 +37,7 @@ export const openProject = Effect.fn("openProject")(function* (path) {
 /** A film module: imported, its assets imported, planned. */
 const openModule = Effect.fn("openModule")(function* (project) {
     const { value, declared } = yield* Effect.tryPromise({
-        try: () => importFilm(project.film),
+        try: () => importFilm(project.film, project.workDir),
         catch: (e) => new FilmFailure({ film: project.film, phase: "load", message: `The film module failed to load: ${messageOf(e)}` }),
     });
     const assets = yield* Effect.try({

package/dist/render/film-loader.d.ts

@@ -9,8 +9,9 @@ export interface LoadedFilm {
     readonly value: unknown;
     readonly declared: ReadonlyArray<Asset>;
 }
-/** Imports a film module (an absolute path), collecting the assets its modules declare. */
-export declare function importFilm(film: string): Promise<LoadedFilm>;
+/** Imports a film module (an absolute path), collecting the assets its modules declare. `workDir`
+ *  is where its bundle goes (the film's .tongue/). */
+export declare function importFilm(film: string, workDir: string): Promise<LoadedFilm>;
 /** Media lengths (seconds) from the import manifest, by `kind:name`. */
 export declare function importedDurations(assetsDir: string): Promise<ReadonlyMap<string, number>>;
 /** Loads the bundles of a build on disk: each is a file of the build already. */

package/dist/render/film-loader.js

@@ -6,8 +6,9 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     }
     return path;
 };
-import { readFile } from "node:fs/promises";
-import { join } from "node:path";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
 import { pathToFileURL } from "node:url";
 import { collectAssets, planFilm } from "@tongue-core/film";
 import { openBuild, planFilmDoc } from "@tongue-core/project";
@@ -25,13 +26,43 @@ export function explainLoadError(message) {
 }
 // A module runs once per process, so a film's declarations are kept for when it is opened again.
 const loaded = new Map();
-/** Imports a film module (an absolute path), collecting the assets its modules declare. */
-export async function importFilm(film) {
+/** An import of @tongue-core/film or one of its entries, in a bundle Bun wrote. */
+const FILM_IMPORT = /(from\s*|import\s*\(\s*|import\s+)"(@tongue-core\/film(?:\/[\w.-]+)?)"/g;
+/** A film module bundled to run against this process's @tongue-core/film. The module may have its
+ *  own installed (its editor reads those types), but a film's elements and its scenes' now()
+ *  belong to the copy that made them, and the engine reads this one; a project's bundles are linked
+ *  to it the same way. JSX is compiled for Tongue whatever the folder's tsconfig says. The bundle is
+ *  written to `workDir` under its hash, so render processes reuse it. */
+async function bundleFilm(film, workDir) {
+    const result = await Bun.build({
+        entrypoints: [film], target: "bun", format: "esm", throw: false,
+        jsx: { runtime: "automatic", importSource: "@tongue-core/film" },
+        external: ["@tongue-core/film", "@tongue-core/film/*"],
+    });
+    const [output] = result.outputs;
+    if (!result.success || !output) {
+        throw new Error(result.logs.map((l) => (l.position ? `${relative(dirname(film), l.position.file)}:${l.position.line}:${l.position.column}: ${l.message}` : l.message)).join("\n") || "it doesn't bundle");
+    }
+    // Bun keeps an external's specifier as written; it becomes this copy's file.
+    const code = (await output.text()).replace(FILM_IMPORT, (_, lead, specifier) => `${lead}"${import.meta.resolve(specifier)}"`);
+    const file = join(workDir, "modules", `film.${new Bun.CryptoHasher("sha256").update(code).digest("hex").slice(0, 16)}.js`);
+    if (!existsSync(file)) {
+        await mkdir(dirname(file), { recursive: true });
+        const partial = `${file}.${process.pid}.tmp`;
+        await writeFile(partial, code);
+        await rename(partial, file);
+    }
+    return file;
+}
+/** Imports a film module (an absolute path), collecting the assets its modules declare. `workDir`
+ *  is where its bundle goes (the film's .tongue/). */
+export async function importFilm(film, workDir) {
     const known = loaded.get(film);
     if (known)
         return known;
     try {
-        const { value: mod, assets } = await collectAssets(() => import(__rewriteRelativeImportExtension(film)));
+        const bundle = await bundleFilm(film, workDir);
+        const { value: mod, assets } = await collectAssets(() => import(__rewriteRelativeImportExtension(pathToFileURL(bundle).href)));
         const result = { value: typeof mod === "object" && mod !== null && "default" in mod ? mod.default : undefined, declared: assets };
         loaded.set(film, result);
         return result;
@@ -67,7 +98,8 @@ export const buildHost = (dir) => ({
 export async function loadPlan(source, assetsDir) {
     const media = mediaOf(await importedDurations(assetsDir));
     if (source.kind === "module") {
-        const { value, declared } = await importFilm(source.film);
+        // The film's work folder holds its imported assets.
+        const { value, declared } = await importFilm(source.film, dirname(assetsDir));
         return planFilm(value, { assets: declared, media });
     }
     const opened = await Effect.runPromise(openBuild((path) => readFile(join(source.dir, path), "utf8"), buildHost(source.dir), source.manifest));

package/dist/render/pipeline.d.ts

@@ -22,12 +22,22 @@ export interface VideoOptions {
         readonly max: number;
     };
     readonly audioBitrate?: string;
+    /** Once the request is checked and the raster and encoder are chosen, before any frame is drawn. */
+    readonly onStart?: (start: RenderStart) => void;
     readonly onProgress?: (progress: {
         readonly frames: number;
         readonly total: number;
         readonly fps: number;
     }) => void;
 }
+export interface RenderStart {
+    readonly frames: number;
+    readonly width: number;
+    readonly height: number;
+    readonly raster: RasterName;
+    readonly encoder: string;
+    readonly workers: number;
+}
 export interface VideoResult {
     readonly out: string;
     readonly width: number;

package/dist/render/pipeline.js

@@ -48,10 +48,13 @@ const runWorker = Effect.fn("runWorker")(function* (index, job, cwd, queue, onFr
         return yield* Queue.offer(mine, segment.value);
     });
     const ready = yield* Deferred.make();
+    const reported = { last: null };
     yield* handle.stdout.pipe(Stream.decodeText(), Stream.splitLines, Stream.runForEach((line) => {
         const report = parseReport(line);
         if (!report)
             return Effect.void;
+        if (report.kind === "failed")
+            return Effect.sync(() => { reported.last = report; });
         if (report.kind === "ready")
             return Deferred.succeed(ready, undefined).pipe(Effect.andThen(next));
         const segment = segments[report.id];
@@ -61,6 +64,10 @@ const runWorker = Effect.fn("runWorker")(function* (index, job, cwd, queue, onFr
     }), Effect.mapError((e) => fail(e.message)));
     const code = yield* handle.exitCode.pipe(Effect.mapError((e) => fail(e.message)));
     if (code !== 0) {
+        // What the film did wrong, as stills says it; otherwise the worker's own last words.
+        const last = reported.last;
+        if (last)
+            return yield* new RenderFailure({ message: last.frame === null ? `A render worker failed: ${last.message}` : `Frame ${last.frame}: ${last.message}` });
         const errors = yield* Fiber.join(stderr).pipe(Effect.orElseSucceed(() => ""));
         return yield* fail(`exited with ${code}: ${errors.trim().split("\n").slice(-12).join("\n")}`);
     }
@@ -74,23 +81,31 @@ export const renderVideo = Effect.fn("renderVideo")(function* (film, options) {
     const to = options.to ?? plan.length;
     if (!(scale > 0 && scale <= 4))
         return yield* new InvalidRequest({ message: `scale must be above 0 and at most 4, not ${scale}.` });
-    if (!(Number.isInteger(from) && Number.isInteger(to) && from >= 0 && to <= plan.length && to > from)) {
-        return yield* new InvalidRequest({ message: `The range ${from}–${to} isn't inside the film (0–${plan.length}).` });
+    if (!(Number.isInteger(from) && Number.isInteger(to)))
+        return yield* new InvalidRequest({ message: `The range ${from}–${to} has to be whole frames.` });
+    if (to <= from)
+        return yield* new InvalidRequest({ message: `The range ${from}–${to} is empty: it has to end after it starts.` });
+    if (from < 0 || to > plan.length)
+        return yield* new InvalidRequest({ message: `The range ${from}–${to} isn't inside the film (frames 0–${plan.length}).` });
+    if (options.workers !== undefined && !(Number.isInteger(options.workers) && options.workers >= 1)) {
+        return yield* new InvalidRequest({ message: `workers must be a whole number, at least 1, not ${options.workers}.` });
     }
     const ffmpeg = yield* ffmpegPath;
     const ffprobe = yield* ffprobePath;
     const raster = yield* resolveRaster(options.raster ?? "auto");
     const settings = { ...DEFAULT_SETTINGS, ...options.settings };
-    const encoder = yield* resolveEncoder(options.encoder ?? "auto", settings, plan.fps, sizeAtScale(plan, scale), ffmpeg);
+    const size = sizeAtScale(plan, scale);
+    const encoder = yield* resolveEncoder(options.encoder ?? "auto", settings, plan.fps, size, ffmpeg);
     // Each render works in its own folder (removed when it ends), so renders can run side by side.
     const renders = join(film.project.workDir, "render");
     yield* fs.makeDirectory(renders, { recursive: true });
     const work = yield* fs.makeTempDirectoryScoped({ directory: renders, prefix: "render-" });
     yield* fs.makeDirectory(dirname(options.out), { recursive: true });
     const wanted = Math.max(1, Math.min(options.workers ?? defaultWorkers(), raster.maxWorkers ?? Infinity));
-    const size = options.segment ?? { min: Math.round(plan.fps), max: Math.round(plan.fps * 2) };
-    const segments = planSegments(from, to, wanted, size).map((s, id) => ({ id, ...s, out: join(work, `seg-${String(id).padStart(4, "0")}.mp4`) }));
+    const segmentSize = options.segment ?? { min: Math.round(plan.fps), max: Math.round(plan.fps * 2) };
+    const segments = planSegments(from, to, wanted, segmentSize).map((s, id) => ({ id, ...s, out: join(work, `seg-${String(id).padStart(4, "0")}.mp4`) }));
     const workers = Math.min(wanted, segments.length);
+    options.onStart?.({ frames: to - from, width: size.width, height: size.height, raster: raster.name, encoder: encoder.spec.name, workers });
     const job = {
         source: film.source, root: film.project.root, assetsDir: film.project.assetsDir, scale,
         raster: raster.name, encoder: encoder.name, settings, ffmpeg, ffprobe,
@@ -126,6 +141,8 @@ export const renderVideo = Effect.fn("renderVideo")(function* (film, options) {
     const [width = 0, height = 0, frames = 0] = stdout.trim().split(",").map(Number);
     if (frames !== total)
         return yield* new RenderFailure({ message: `Expected ${total} frames in ${options.out}, found ${frames}.` });
+    if (width !== size.width || height !== size.height)
+        return yield* new RenderFailure({ message: `${options.out} came out ${width}×${height}, not ${size.width}×${size.height} (the ${encoder.spec.name} encoder).` });
     const seconds = (performance.now() - started) / 1000;
     const result = { out: options.out, width, height, frames, duration: total / plan.fps, raster: raster.name, encoder: encoder.spec.name, workers, seconds, fps: total / seconds };
     return result;

package/dist/render/protocol.d.ts

@@ -39,6 +39,12 @@ export type WorkerReport = {
     readonly kind: "done";
     readonly id: number;
     readonly ms: number;
+}
+/** The worker is about to exit: a frame failed to draw, or (no frame) loading or encoding failed. */
+ | {
+    readonly kind: "failed";
+    readonly frame: number | null;
+    readonly message: string;
 };
 export declare class ProtocolError extends Error {
     readonly name = "ProtocolError";

package/dist/render/protocol.js

@@ -66,10 +66,23 @@ export function formatReport(r) {
         case "ready": return `ready ${r.ms.toFixed(0)}`;
         case "progress": return `progress ${r.id} ${r.frames}`;
         case "done": return `done ${r.id} ${r.ms.toFixed(0)}`;
+        // The message as a JSON string, so it stays on one line.
+        case "failed": return `failed ${r.frame ?? "-"} ${JSON.stringify(r.message)}`;
     }
 }
 /** A report line; anything else a worker prints (logs) is not a report. */
 export function parseReport(line) {
+    const failed = /^failed (-|\d+) (".*")$/.exec(line.trim());
+    if (failed) {
+        let message = null;
+        try {
+            message = JSON.parse(failed[2] ?? "");
+        }
+        catch {
+            return null;
+        }
+        return typeof message === "string" ? { kind: "failed", frame: failed[1] === "-" ? null : Number(failed[1]), message } : null;
+    }
     const [kind, ...rest] = line.trim().split(" ");
     const n = rest.map(Number);
     if (n.some((v) => !Number.isFinite(v)))

package/dist/render/stills.js

@@ -24,7 +24,7 @@ export const renderStills = Effect.fn("renderStills")(function* (film, options)
         return yield* new InvalidRequest({ message: `scale must be above 0 and at most 4, not ${scale}.` });
     const outside = options.frames.filter((f) => !(Number.isInteger(f) && f >= 0 && f < film.plan.length));
     if (outside.length)
-        return yield* new InvalidRequest({ message: `Frames ${outside.join(", ")} are outside the film (0–${film.plan.length - 1}).` });
+        return yield* new InvalidRequest({ message: `${outside.length === 1 ? `Frame ${outside.join("")} is` : `Frames ${outside.join(", ")} are`} outside the film (0–${film.plan.length - 1}).` });
     const ffmpeg = yield* ffmpegPath;
     yield* fs.makeDirectory(options.outDir, { recursive: true });
     const fail = (e) => new RenderFailure({ message: messageOf(e) });
@@ -58,7 +58,7 @@ export const renderSheet = Effect.fn("renderSheet")(function* (film, options) {
         const c = i % columns, r = Math.floor(i / columns);
         return `${c === 0 ? "0" : Array.from({ length: c }, () => "w0").join("+")}_${r === 0 ? "0" : Array.from({ length: r }, () => "h0").join("+")}`;
     };
-    const label = stills.map((s, i) => `[${i}]drawtext=text='${s.frame}':x=10:y=10:fontsize=24:fontcolor=white:box=1:boxcolor=black@0.6[l${i}]`).join(";");
+    const label = stills.map((s, i) => `[${i}]drawtext=text='${s.frame}':x=14:y=14:fontsize=24:fontcolor=white:box=1:boxcolor=black@0.6:boxborderw=6[l${i}]`).join(";");
     const stack = `${stills.map((_, i) => `[l${i}]`).join("")}xstack=inputs=${stills.length}:layout=${stills.map((_, i) => at(i)).join("|")}:fill=black`;
     const ffmpeg = yield* ffmpegPath;
     yield* runTool(ffmpeg, ["-y", "-v", "error", ...stills.flatMap((s) => ["-i", s.path]), "-filter_complex", `${label};${stack}`, out]);

package/dist/render/worker.js

@@ -14,42 +14,59 @@ import { FfmpegVideoFrames } from "./video-frames.js";
 //   bun worker.ts '<job json>'
 const started = performance.now();
 const say = (r) => console.log(formatReport(r));
-const job = parseJob(process.argv[2] ?? "");
-const plan = await loadPlan(job.source, job.assetsDir);
-const loaded = await loadAssets(plan.assets, (path) => Bun.file(join(job.assetsDir, path)).bytes(), { audio: false });
-const backend = await rasterPlugin(job.raster).create();
-const renderer = await FilmRenderer.create(plan, loaded, backend);
-const video = new FfmpegVideoFrames(job.ffmpeg, (asset) => {
-    const info = loaded.videos.get(asset.name)?.info;
-    return info ? { path: join(job.root, asset.source), info } : null;
-});
-const spec = encoderSpec(job.encoder, job.settings, plan.fps);
-const { width, height } = renderer.sizeAt(job.scale);
-// Frames go to the encoder one in flight while the next is drawn, so three buffers cycle.
-const pool = [0, 1, 2].map(() => new Uint8Array(frameBytes(width, height, "yuv420p")));
-say({ kind: "ready", ms: performance.now() - started });
-for await (const line of console) {
-    if (!line.trim())
-        continue;
-    const segment = parseSegment(line);
-    const t0 = performance.now();
-    const encoder = openEncoder({ ffmpeg: job.ffmpeg, ffprobe: job.ffprobe }, spec, { width, height, fps: plan.fps, out: segment.out });
-    for (let f = segment.from; f < segment.to; f++) {
-        const drawn = await frameWithVideo(renderer, f, job.scale, video);
-        const frame = pool[f % pool.length] ?? new Uint8Array(0);
-        if (rendersInto(backend))
-            backend.renderInto(renderer.upload(drawn), "yuv420p", frame);
-        else {
-            renderer.draw(drawn);
-            frame.set(renderer.yuv420());
+const messageOf = (e) => (e instanceof Error ? e.message : String(e));
+// A failure is reported before the worker exits, with the frame when one was being drawn, so the
+// render can say what broke.
+let drawing = null;
+const failed = (e) => {
+    say({ kind: "failed", frame: drawing, message: messageOf(e) });
+    process.exit(1);
+};
+process.on("uncaughtException", failed);
+process.on("unhandledRejection", failed);
+try {
+    const job = parseJob(process.argv[2] ?? "");
+    const plan = await loadPlan(job.source, job.assetsDir);
+    const loaded = await loadAssets(plan.assets, (path) => Bun.file(join(job.assetsDir, path)).bytes(), { audio: false });
+    const backend = await rasterPlugin(job.raster).create();
+    const renderer = await FilmRenderer.create(plan, loaded, backend);
+    const video = new FfmpegVideoFrames(job.ffmpeg, (asset) => {
+        const info = loaded.videos.get(asset.name)?.info;
+        return info ? { path: join(job.root, asset.source), info } : null;
+    });
+    const spec = encoderSpec(job.encoder, job.settings, plan.fps);
+    const { width, height } = renderer.sizeAt(job.scale);
+    // Frames go to the encoder one in flight while the next is drawn, so three buffers cycle.
+    const pool = [0, 1, 2].map(() => new Uint8Array(frameBytes(width, height, "yuv420p")));
+    say({ kind: "ready", ms: performance.now() - started });
+    for await (const line of console) {
+        if (!line.trim())
+            continue;
+        const segment = parseSegment(line);
+        const t0 = performance.now();
+        const encoder = openEncoder({ ffmpeg: job.ffmpeg, ffprobe: job.ffprobe }, spec, { width, height, fps: plan.fps, out: segment.out });
+        for (let f = segment.from; f < segment.to; f++) {
+            drawing = f;
+            const drawn = await frameWithVideo(renderer, f, job.scale, video);
+            const frame = pool[f % pool.length] ?? new Uint8Array(0);
+            if (rendersInto(backend))
+                backend.renderInto(renderer.upload(drawn), "yuv420p", frame);
+            else {
+                renderer.draw(drawn);
+                frame.set(renderer.yuv420());
+            }
+            drawing = null;
+            await encoder.write(frame);
+            const done = f - segment.from + 1;
+            if (done % 4 === 0 && f < segment.to - 1)
+                say({ kind: "progress", id: segment.id, frames: done });
         }
-        await encoder.write(frame);
-        const done = f - segment.from + 1;
-        if (done % 4 === 0 && f < segment.to - 1)
-            say({ kind: "progress", id: segment.id, frames: done });
+        await encoder.finish();
+        say({ kind: "done", id: segment.id, ms: performance.now() - t0 });
     }
-    await encoder.finish();
-    say({ kind: "done", id: segment.id, ms: performance.now() - t0 });
+    video.close();
+    backend.dispose();
+}
+catch (e) {
+    failed(e);
 }
-video.close();
-backend.dispose();

package/dist/studio/server.js

@@ -3,7 +3,7 @@ import { tmpdir } from "node:os";
 import { basename, dirname, extname, join, normalize, relative, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { studioPage } from "@tongue-core/studio/page";
-import { Effect, FileSystem, Path } from "effect";
+import { Cause, Effect, FileSystem, Path } from "effect";
 import { ChildProcessSpawner } from "effect/process";
 import { buildForWork } from "../build/build.js";
 import { FilmFailure, messageOf } from "../errors.js";
@@ -74,6 +74,8 @@ export const studioServer = Effect.fn("studioServer")(function* (filmPath, optio
             }
         }
     };
+    // What the last build said when it failed, for the studio and the terminal.
+    let failure = null;
     const rebuild = async () => {
         if (!project)
             return;
@@ -81,11 +83,12 @@ export const studioServer = Effect.fn("studioServer")(function* (filmPath, optio
         tell({ kind: "building" });
         const built = await run(buildForWork(project));
         if (built._tag === "Failure") {
-            const message = `the project doesn't build (tongue check ${relative(process.cwd(), project.root) || "."} says why)`;
-            log(`build failed: ${message}`);
-            tell({ kind: "failed", message });
+            failure = messageOf(Cause.squash(built.cause));
+            log(`build failed: ${failure}`);
+            tell({ kind: "failed", message: failure });
             return;
         }
+        failure = null;
         current = built.value.dir;
         const ms = Math.round(performance.now() - started);
         log(`built in ${ms} ms`);
@@ -94,7 +97,7 @@ export const studioServer = Effect.fn("studioServer")(function* (filmPath, optio
     if (project) {
         yield* Effect.promise(rebuild);
         if (!current)
-            return yield* new FilmFailure({ film: project.root, phase: "load", message: "The project doesn't build; run tongue check to see why." });
+            return yield* new FilmFailure({ film: project.root, phase: "load", message: `The project doesn't build: ${failure ?? `tongue check ${relative(process.cwd(), project.root) || "."} says why`}` });
     }
     const title = project ? basename(project.root) : options.remote ?? "remote build";
     const page = studioPage({

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@tongue-core/sdk",
-  "version": "0.1.0-rc.1",
+  "version": "0.1.0-rc.3",
   "description": "Everything you do with a Tongue film, as a library: start a project from a template, build it into film.json, import, plan, check, render frames and video. Built with Effect.",
   "type": "module",
-  "license": "UNLICENSED",
+  "license": "MIT",
   "author": "Backpine",
   "repository": {
     "type": "git",
@@ -35,16 +35,17 @@
   ],
   "dependencies": {
     "@effect/platform-bun": "4.0.6",
-    "@tongue-core/engine": "0.1.0-rc.1",
-    "@tongue-core/film": "0.1.0-rc.1",
-    "@tongue-core/project": "0.1.0-rc.1",
-    "@tongue-core/studio": "0.1.0-rc.1",
-    "@tongue-core/templates": "0.1.0-rc.1",
-    "@tongue-core/ui": "0.1.0-rc.1",
+    "@effect/platform-node-shared": "4.0.6",
+    "@tongue-core/engine": "0.1.0-rc.3",
+    "@tongue-core/film": "0.1.0-rc.3",
+    "@tongue-core/project": "0.1.0-rc.3",
+    "@tongue-core/studio": "0.1.0-rc.3",
+    "@tongue-core/templates": "0.1.0-rc.3",
+    "@tongue-core/ui": "0.1.0-rc.3",
     "effect": "4.0.6"
   },
   "optionalDependencies": {
-    "@tongue-core/raster-linux-x64": "0.1.0-rc.1"
+    "@tongue-core/raster-linux-x64": "0.1.0-rc.3"
   },
   "publishConfig": {
     "access": "public"