Skip to content

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.md
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.md
index 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`.
---