Code-first video & image, rendered natively on WebGPU.
Print engine logs as short text lines outside production
Claude4530dae285e2
diff --git a/.changeset/render-progress-phases.md b/.changeset/render-progress-phases.mdindex 8aa6c40c..bbad6a02 100644--- a/.changeset/render-progress-phases.md+++ b/.changeset/render-progress-phases.md@@ -6,4 +6,5 @@ Clearer render progress, sized for agents' context:- `renderVideo` logs each phase (prepare, frames, audio mix, audio encode, mux, GIF conversion) and a summary with per-phase timings. Frames log at every 10% with fps and ETA instead of every 10 frames, so an export prints about 15 lines whatever its length.- A phase that runs long logs `Still …` lines (after 10 s, then backing off to every 5 min) naming the phase and its progress, so the audio mix or the mux after the last frame no longer looks like a hang. A failed render names the phase it stopped in.- `onProgress` reports the new phases `prepare`, `audio-encode`, `mux`, `convert` and `done` alongside `render` and `audio`, with `elapsedMs`, and `fps`, `etaSec`, `phaseProgress` and `detail` where they apply. The audio mix reports each clip it mixes (`mixAudioTracks` takes an `onProgress` option), which also keeps the render worker's stall detector from firing on long mixes.+- The engine's logs are one short `[framefields] …` line each on stderr instead of pino JSON, about a fifth of the size. `NODE_ENV=production` keeps JSON on stdout; `FRAMEFIELDS_LOG_FORMAT=json|text` picks either. The render worker keeps JSON.- Removes the unused `video-worker` entry from `@framefields/renderer`.diff --git a/apps/renderer-service/src/logger.ts b/apps/renderer-service/src/logger.tsindex fecabf98..07fc01c5 100644--- a/apps/renderer-service/src/logger.ts+++ b/apps/renderer-service/src/logger.ts@@ -21,6 +21,10 @@ const version = (() => {return "unknown";})();+// The project's framefields logs through its own logger; keep its lines JSON+// like ours, also outside production. Set before any engine is imported.+process.env.FRAMEFIELDS_LOG_FORMAT ??= "json";+/** Per-job / per-request fields merged into every log line. */export const loggerContext = new AsyncLocalStorage<Record<string, unknown>>();diff --git a/packages/renderer/src/logger.ts b/packages/renderer/src/logger.tsindex 8672f7e6..f76c1427 100644--- a/packages/renderer/src/logger.ts+++ b/packages/renderer/src/logger.ts@@ -1,9 +1,60 @@-import pino from "pino";+import pino, { type DestinationStream } from "pino";-export const rendererLogger = pino({- level: (typeof process !== "undefined" && process.env?.LOG_LEVEL) || "info",+const env = typeof process !== "undefined" ? process.env : undefined;++/**+ * "json" (pino lines, for log collectors) or "text" (one short line each, for+ * people and agents reading a terminal). `FRAMEFIELDS_LOG_FORMAT` picks one;+ * otherwise production is JSON and everything else text.+ */+export function resolveLogFormat(+ vars: Record<string, string | undefined> | undefined = env,+): "json" | "text" {+ const format = vars?.FRAMEFIELDS_LOG_FORMAT?.toLowerCase();+ if (format === "json" || format === "text") return format;+ return vars?.NODE_ENV === "production" ? "json" : "text";+}++const LEVEL_TAGS: Record<number, string> = {+ 40: "warn: ",+ 50: "error: ",+ 60: "fatal: ",+};++/**+ * Turns pino's JSON lines into `[framefields] Rendered 40% (…)`: the message+ * without its `[Component]` prefix, the level only for warnings and errors,+ * and an error's message (its stack reaches the caller with the throw).+ */+export function textLogStream(+ write: (line: string) => void = (line) => process.stderr.write(line),+): DestinationStream {+ return {+ write(json: string) {+ let entry: { level?: number; msg?: unknown; err?: { message?: string } };+ try {+ entry = JSON.parse(json);+ } catch {+ write(json);+ return;+ }+ const msg = String(entry.msg ?? "").replace(/^\[[^\]]+\]\s*/, "");+ const tag = LEVEL_TAGS[entry.level ?? 0] ?? "";+ const err = entry.err?.message ? `: ${entry.err.message}` : "";+ write(`[framefields] ${tag}${msg}${err}\n`);+ },+ };+}++const options = {+ level: env?.LOG_LEVEL || "info",timestamp: pino.stdTimeFunctions.isoTime,base: {component: "renderer",},-});+};++export const rendererLogger =+ resolveLogFormat() === "text"+ ? pino(options, textLogStream())+ : pino(options);diff --git a/packages/renderer/src/tests/logger.test.ts b/packages/renderer/src/tests/logger.test.tsnew file mode 100644index 00000000..5d2068ee--- /dev/null+++ b/packages/renderer/src/tests/logger.test.ts@@ -0,0 +1,42 @@+import pino from "pino";+import { describe, expect, it } from "vitest";+import { resolveLogFormat, textLogStream } from "../logger.js";++describe("resolveLogFormat", () => {+ it("is text by default, JSON in production, and follows the override", () => {+ expect(resolveLogFormat({})).toBe("text");+ expect(resolveLogFormat({ NODE_ENV: "production" })).toBe("json");+ expect(+ resolveLogFormat({+ NODE_ENV: "production",+ FRAMEFIELDS_LOG_FORMAT: "text",+ }),+ ).toBe("text");+ expect(resolveLogFormat({ FRAMEFIELDS_LOG_FORMAT: "JSON" })).toBe("json");+ });+});++describe("textLogStream", () => {+ it("prints one short line per entry", () => {+ const lines: string[] = [];+ const log = pino(+ { base: { component: "renderer" } },+ textLogStream((line) => lines.push(line)),+ );+ log.info(+ { renderId: "vid-1", frame: 720, totalFrames: 1800 },+ "[HeadlessWebGPURenderer] Rendered 40% (720/1800 frames)",+ );+ log.warn({}, "[HeadlessWebGPURenderer] Aborted while muxing after 2.0s");+ log.error(+ { err: new Error("decoder closed") },+ "[HeadlessWebGPURenderer] Failed while mixing audio after 1.2s",+ );+ log.debug({}, "hidden below the level");+ expect(lines).toEqual([+ "[framefields] Rendered 40% (720/1800 frames)\n",+ "[framefields] warn: Aborted while muxing after 2.0s\n",+ "[framefields] error: Failed while mixing audio after 1.2s: decoder closed\n",+ ]);+ });+});diff --git a/plugins/framefields/skills/framefields-render/SKILL.md b/plugins/framefields/skills/framefields-render/SKILL.mdindex 04e84993..1b5628b3 100644--- a/plugins/framefields/skills/framefields-render/SKILL.md+++ b/plugins/framefields/skills/framefields-render/SKILL.md@@ -235,25 +235,26 @@ tsx src/render.ts### Reading render progress-`renderVideo` logs its own progress to stdout, one JSON line per event (the text is in `msg`). The log stays short however long the film is, about 15 lines for an export:+`renderVideo` logs its own progress to stderr, one short `[framefields]` line per event. The log stays short however long the film is, about 15 lines for an export:```text-Preparing 1800 frames (60.0s) at 1920x1080, 30 fps, h264-Rendering 1800 frames-Rendered 10% (180/1800 frames) · 41.2 fps · eta 39.3s+[framefields] Preparing 1800 frames (60.0s) at 1920x1080, 30 fps, h264+[framefields] Rendering 1800 frames+[framefields] Rendered 10% (180/1800 frames) · 41.2 fps · eta 39.3s…-Rendered 100% (1800/1800 frames) · 41.8 fps · in 43.1s-Mixing audio-Encoding 60.0s of audio (aac)-Muxing mp4-Done in 51.4s (14.2 MB): prepare 1.2s · render 43.1s · audio 3.2s · audio-encode 1.1s · mux 0.8s+[framefields] Rendered 100% (1800/1800 frames) · 41.8 fps · in 43.1s+[framefields] Mixing audio+[framefields] Encoding 60.0s of audio (aac)+[framefields] Muxing mp4+[framefields] Done in 51.4s (14.2 MB): prepare 1.2s · render 43.1s · audio 3.2s · audio-encode 1.1s · mux 0.8s```- **Work continues after the last frame.** "Mixing audio" decodes every audio and video clip in the film, then the soundtrack is encoded and "Muxing" writes the file. With many or long clips this takes a while. It is not a hang; wait for `Done in …`.- **A quiet phase prints `Still …` lines**, e.g. `Still mixing audio (42%, 3/7 clips: music.mp3), 1m 10s in this phase`: after 10 s, 30 s, 70 s, then backing off to one every 5 min. Each says which phase is running and for how long. A render is stuck only when no line arrives for well over the last gap. Killing it at any point leaves no video.- **A failure names its phase:** `Failed while mixing audio after 12.3s`, with the error.- **Run long exports in the background** with the longest timeout your harness allows, and read the output when it finishes rather than polling it.-- `LOG_LEVEL=warn` silences these lines; `LOG_LEVEL=debug` adds per-stage detail.+- `LOG_LEVEL=warn` silences these lines; `LOG_LEVEL=debug` adds per-stage detail. Warnings and errors read `[framefields] warn: …` / `error: …`.+- With `NODE_ENV=production` (or `FRAMEFIELDS_LOG_FORMAT=json`) the lines are pino JSON on stdout instead, with the text in `msg`; `FRAMEFIELDS_LOG_FORMAT=text` forces the short lines.- For your own progress output, `onProgress` gets every event as `{ phase, frame, totalFrames, elapsedMs, phaseProgress?, fps?, etaSec?, detail? }`. `phase` runs `prepare`, `render` (audio-only output skips it), `audio`, `audio-encode`, `mux`, `convert` (GIF only), `done`.---