@koda-sl/baker-cli 0.277.0-dev.1f1c09c80 → 0.280.0-dev.1f1c09c80

package/README.md

@@ -3648,6 +3648,15 @@ because a video model garbles a wordmark every time:
   the ad needs something other than the client's default.
 - **The spoken language is read off the script** when the spec does not declare it, so a
   Spanish ad is cast from Spanish voices without anyone having to say so.
+- **`sound`** (per beat) — one sound effect for that shot, rendered by ElevenLabs
+  alongside the music bed. Most beats should not have one: it belongs where the picture
+  shows a specific physical event (a drill, a door, rain on glass), not on a talking head
+  or a calm lifestyle shot. A bed plus two well-placed effects beats eight.
+- **A real brand mark is required.** `scaffold-ad` refuses to build without one in
+  `src/brand/logos/` (SVG or PNG): the mark is drawn on every frame and on the closing
+  card, so a stand-in ships an ad wearing the wrong brand.
+- **An avatar with no pinned voice cannot speak on camera.** Their lines would be read by
+  a separately cast voice, which is dubbing and looks like it.
 - **`voiceover: false`** — a music-led ad. No voice, no transcription: the `say` lines
   become on-screen text and are captioned straight from the script, so the words are
   exact. Give it `music` too.

package/dist/cli.js

@@ -30367,7 +30367,11 @@ function buildRunRecord(result, meta, plan, finalLabels) {
     },
     nodes,
     finalOutputs: finalOutputs.length > 0 ? finalOutputs : void 0,
-    ...meta.review && meta.review.length > 0 ? { review: meta.review.slice(0, 40) } : {}
+    // Sent whenever the review RAN, empty list included. Sending it only when there
+    // were findings makes a clean render and an unreviewed one look identical in the
+    // record — which is the exact ambiguity this field was added to remove: proving a
+    // review had happened once meant re-running a cached canvas and reading raw JSON.
+    ...meta.review ? { review: meta.review.slice(0, 40) } : {}
   };
 }
 function buildInitialRunRecord(runId, meta) {
@@ -31040,6 +31044,32 @@ function videoPathFromOutput(output) {
   }
   return found;
 }
+function classifyAudio(volumedetect, hasAudioStream) {
+  if (!hasAudioStream) {
+    return [
+      {
+        severity: "blocking",
+        what: "The finished video has no audio track at all \u2014 no voice, no music, nothing. An ad that plays silent in a feed is not an ad."
+      }
+    ];
+  }
+  const mean = Number.parseFloat(volumedetect.match(/mean_volume:\s*(-?[\d.]+) dB/)?.[1] ?? "");
+  const max = Number.parseFloat(volumedetect.match(/max_volume:\s*(-?[\d.]+) dB/)?.[1] ?? "");
+  const findings = [];
+  if (Number.isFinite(mean) && mean < -30) {
+    findings.push({
+      severity: "warning",
+      what: `The mix is very quiet (${mean} dB average). On a phone at half volume this is close to silence \u2014 check the music bed is not ducked into nothing under the voice.`
+    });
+  }
+  if (Number.isFinite(max) && max > -0.5) {
+    findings.push({
+      severity: "warning",
+      what: `The mix peaks at ${max} dB, which is at or over the ceiling \u2014 the voice will distort on a phone speaker. Bring the loudest track down a few dB.`
+    });
+  }
+  return findings;
+}
 var RENDER_REVIEW_UNAVAILABLE = "The render was NOT reviewed \u2014 no frame-vision key in this environment. Watch it yourself before sending it on.";
 var REVIEW_CONCURRENCY = 3;
 async function mapWithLimit(items, limit, fn) {
@@ -31055,6 +31085,21 @@ async function mapWithLimit(items, limit, fn) {
   return out;
 }
 var execFileAsync2 = promisify2(execFile2);
+async function measureAudio(video) {
+  const streams = await execFileAsync2(
+    "ffprobe",
+    ["-v", "error", "-select_streams", "a", "-show_entries", "stream=codec_type", "-of", "csv=p=0", video],
+    { timeout: 2e4 }
+  ).catch(() => null);
+  if (!streams) return [];
+  const hasAudio = streams.stdout.trim().length > 0;
+  if (!hasAudio) return classifyAudio("", false);
+  const vol = await execFileAsync2("ffmpeg", ["-i", video, "-map", "0:a:0", "-af", "volumedetect", "-f", "null", "-"], {
+    timeout: 12e4,
+    maxBuffer: 8 * 1024 * 1024
+  }).catch((e) => ({ stdout: "", stderr: e.stderr ?? "" }));
+  return classifyAudio(vol.stderr ?? "", true);
+}
 async function videoDuration(video) {
   try {
     const { stdout } = await execFileAsync2(
@@ -31118,7 +31163,12 @@ async function reviewRenderedVideo(opts) {
     }));
     const unread = perFrame.filter((f) => f.json === null).length;
     if (unread === perFrame.length && reel === null) return null;
-    const findings = [...classifyFrameFindings(perFrame, opts.windows ?? []), ...classifyReelFindings(reel)];
+    const findings = [
+      ...classifyFrameFindings(perFrame, opts.windows ?? []),
+      ...classifyReelFindings(reel),
+      // Measured, not judged: a model looking at frames cannot hear the mix.
+      ...await measureAudio(opts.video)
+    ];
     if (unread > 0) {
       findings.push({
         severity: "warning",
@@ -31444,6 +31494,9 @@ ${describeRewrites(healed.rewrites)}
     ] : [];
     if (poster) {
       await poster.flush(
+        // `review` is null only when nobody looked (no key, no ffmpeg, unreadable video);
+        // an empty array is a render that was reviewed and came back clean. The record
+        // has to keep those apart.
         buildRunRecord(result, { ...recordMeta, ...review ? { review } : {} }, progress?.planInfo(), finalLabels)
       );
     }
@@ -32521,7 +32574,7 @@ var scaffoldStaticAdCommand = defineCommand103({
 });
 
 // src/commands/canvas/scaffold-ad.ts
-import { copyFile, cp, mkdir as mkdir7, readFile as readFile16, writeFile as writeFile9 } from "fs/promises";
+import { copyFile, cp, mkdir as mkdir7, readFile as readFile16, stat as stat4, writeFile as writeFile9 } from "fs/promises";
 import path24 from "path";
 import { defineCommand as defineCommand104 } from "citty";
 
@@ -32540,6 +32593,23 @@ var Beat = z30.object({
   ).refine(oneClause, "a beat is one clause: split a second sentence into its own beat"),
   /** What is on screen while it is said, as a shot brief for the video model. */
   show: z30.string().min(1),
+  /**
+   * What this shot SOUNDS like — one effect, in words. Usually absent.
+   *
+   * An effect earns its place when the picture shows a SPECIFIC PHYSICAL EVENT the
+   * viewer expects to hear: a drill tightening a bolt, a door closing, rain on glass, a
+   * card tapping a reader, a graphic snapping into place. It grounds the shot.
+   *
+   * It does NOT belong on a talking head, on a lifestyle shot with no event in it, or
+   * on a beat that is simply someone sitting and reacting. Sound laid over those reads
+   * as a stock-library sting, and a bed of them turns a calm ad into a noisy one. Most
+   * ads are a music bed and a voice; a couple of effects at the right moments, or none
+   * at all, is a normal and often better answer than one per beat.
+   *
+   * Describe the SOUND, not the picture: "a cordless drill tightening a bolt", not "the
+   * fitter works on the rail".
+   */
+  sound: z30.string().min(1).max(200).optional(),
   /**
    * Set only when this beat's subject is talking to camera. Off by default, and
    * the default is load-bearing: a person visibly speaking under a voice that is
@@ -32834,6 +32904,10 @@ function adSpecToBlueprint(spec) {
       // No dialogue at all when nobody speaks: an empty array is what stops the engine
       // wiring a voice track, and no voice track is what makes this a music-led ad
       // rather than one with a silent narrator.
+      // One effect per beat, placed on this beat's window. The engine clamps the
+      // length to what the provider accepts. An ad emitted none of these until now,
+      // so every one shipped with a music bed and no sound design at all.
+      ...beat.sound?.trim() ? { sfx: [{ sound_effect_prompt: beat.sound.trim(), duration_s: Math.min(duration, 30) }] } : {},
       dialogue: spec.voiceover === false ? [] : [
         {
           line: beat.say,
@@ -33052,6 +33126,9 @@ async function readBrandFromWorkspace(root = ".") {
   }
   return found;
 }
+function svgIsLiveText(svg) {
+  return /<text[\s>]/i.test(svg);
+}
 
 // src/commands/canvas/composition-path.ts
 import { existsSync as existsSync4 } from "fs";
@@ -33080,7 +33157,7 @@ registerSchema({
     spec: {
       type: "string",
       required: true,
-      description: 'Path to the ad spec JSON. Shape: { format?, market?, brand?, cast?, end_card?, voice?, music?, beats: [{ say, show, on_camera?, cast? }] }. Fill `brand` from src/brand/BRAND.md \u2014 `palette` (its hex tokens, most important first) and `logo` (the repo path to the mark) are what make the ad look like the client rather than like stock. `market` is where the ad is SET; omitted, it is inferred from the voice language, and getting it wrong is what fills a Spanish ad with British houses. `say` is ONE clause ending in its own punctuation \u2014 it becomes a caption card verbatim, so two sentences in one beat produce a card holding both. `show` is the shot brief for that line. Set `on_camera` ONLY when that beat\'s subject talks to camera. `voiceover: false` makes it a MUSIC-LED ad: nobody speaks, the `say` lines become on-screen text captioned straight from the script, and it needs `music`. `cast` is WHO the ad is about, and an ad with people in it needs one: `{ "avatar": "marta" }` names a cast avatar (`baker avatars list`) and every beat is grounded on that avatar\'s identity sheet with its subject description copied verbatim \u2014 the same face here as in the rest of the company\'s work. Without it each beat invents its own stranger, which is how one 28-second ad came back with five different men playing one customer. `{ "description": "..." }` is the fallback when there is no avatar, and it scaffolds a canvas that asks you to drop a photo before it can run \u2014 so prefer the avatar. A beat sets `cast: false` for a shot they are not in. `end_card` is on by default whenever `brand` is set: the last beat becomes a flat brand plate with the mark and a call to action drawn over it. `{ "cta": "..." }` sets the button copy, `false` keeps the footage.'
+      description: 'Path to the ad spec JSON. Shape: { format?, market?, brand?, cast?, end_card?, voice?, music?, beats: [{ say, show, on_camera?, cast? }] }. Fill `brand` from src/brand/BRAND.md \u2014 `palette` (its hex tokens, most important first) and `logo` (the repo path to the mark) are what make the ad look like the client rather than like stock. `market` is where the ad is SET; omitted, it is inferred from the voice language, and getting it wrong is what fills a Spanish ad with British houses. `say` is ONE clause ending in its own punctuation \u2014 it becomes a caption card verbatim, so two sentences in one beat produce a card holding both. `show` is the shot brief for that line. Set `on_camera` ONLY when that beat\'s subject talks to camera. A beat\'s `sound` is one sound EFFECT for that shot \u2014 and MOST BEATS SHOULD NOT HAVE ONE. Add it only where the picture shows a specific physical event the viewer expects to hear (a drill tightening a bolt, a door closing, rain on glass, a graphic snapping in). On a talking head or a calm lifestyle shot it reads as a stock sting, and one per beat turns a quiet ad into a noisy one. A music bed plus two well-placed effects beats eight. `voiceover: false` makes it a MUSIC-LED ad: nobody speaks, the `say` lines become on-screen text captioned straight from the script, and it needs `music`. `cast` is WHO the ad is about, and an ad with people in it needs one: `{ "avatar": "marta" }` names a cast avatar (`baker avatars list`) and every beat is grounded on that avatar\'s identity sheet with its subject description copied verbatim \u2014 the same face here as in the rest of the company\'s work. Without it each beat invents its own stranger, which is how one 28-second ad came back with five different men playing one customer. `{ "description": "..." }` is the fallback when there is no avatar, and it scaffolds a canvas that asks you to drop a photo before it can run \u2014 so prefer the avatar. A beat sets `cast: false` for a shot they are not in. `end_card` is on by default whenever `brand` is set: the last beat becomes a flat brand plate with the mark and a call to action drawn over it. `{ "cta": "..." }` sets the button copy, `false` keeps the footage.'
     },
     avatar: {
       type: "string",
@@ -33191,6 +33268,48 @@ var scaffoldAdCommand = defineCommand104({
         ...filledPalette ? { palette: filledPalette } : {}
       };
     }
+    const speaksOnCamera = spec.data.beats.some((beat) => beat.on_camera === true);
+    if (avatar && !avatar.voiceId && speaksOnCamera) {
+      writeJson({
+        ok: false,
+        error: {
+          code: "VALIDATION_ERROR",
+          message: `Avatar \`${handle}\` has no pinned voice, and this ad has them speaking on camera. Their lines would be read by a voice cast from a description \u2014 a mouth moving under somebody else's voice, which is exactly what dubbing looks like.`,
+          fix: `Give \`${handle}\` a voice first, or drop \`on_camera\` from every beat so they appear without speaking and the narration carries the read. An avatar is a face AND a voice; casting one without the other is what puts the wrong voice in their mouth.`
+        }
+      });
+      process.exit(1);
+      return;
+    }
+    const resolvedLogo = spec.data.brand?.logo?.trim();
+    const logoExists = resolvedLogo ? await stat4(resolvedLogo).then(() => true, () => false) : false;
+    if (!logoExists) {
+      writeJson({
+        ok: false,
+        error: {
+          code: "VALIDATION_ERROR",
+          message: resolvedLogo ? `The brand mark at \`${resolvedLogo}\` does not exist, so this ad has no logo to put on screen.` : `This company has no brand mark in \`${BRAND_DIR}/logos/\`, so an ad cannot carry its logo.`,
+          fix: `Put the client's real mark in \`${BRAND_DIR}/logos/\` \u2014 an SVG is best, a PNG is fine \u2014 and run this again. Ask them for it if you have to; do NOT draw one, and do not pass a placeholder. The mark is drawn on every frame and on the closing card, so a stand-in ships an ad wearing the wrong brand.`
+        }
+      });
+      process.exit(1);
+      return;
+    }
+    if (resolvedLogo?.toLowerCase().endsWith(".svg")) {
+      const svg = await readFile16(resolvedLogo, "utf-8").catch(() => "");
+      if (svg && svgIsLiveText(svg)) {
+        writeJson({
+          ok: false,
+          error: {
+            code: "VALIDATION_ERROR",
+            message: `The mark at \`${resolvedLogo}\` draws its wordmark with live \`<text>\`, not outlines. That is a typed stand-in, not a logo: it renders in whatever font the machine happens to have, and the one that shipped this way came out reading "greenle\xE1" in every frame.`,
+            fix: `Ask the client for their real logo file and put it in \`${BRAND_DIR}/logos/\` \u2014 an outlined SVG, or a PNG at 1000px or wider. Do not redraw it.`
+          }
+        });
+        process.exit(1);
+        return;
+      }
+    }
     const blueprint = adSpecToBlueprint(spec.data);
     const slug = args.slug ?? path24.basename(specPath).replace(/\.[^.]+$/, "");
     const outPath = args.out ?? (args.slug ? path24.join("src/creatives", slug, `${slug}.canvas.json`) : path24.join(path24.dirname(specPath), `${slug}.canvas.json`));
@@ -39061,7 +39180,7 @@ function cropSprite(input, region) {
 
 // src/lib/image/io.ts
 import { randomBytes } from "crypto";
-import { glob as fsGlob, readFile as readFile23, rename, stat as stat4, writeFile as writeFile12 } from "fs/promises";
+import { glob as fsGlob, readFile as readFile23, rename, stat as stat5, writeFile as writeFile12 } from "fs/promises";
 import { dirname as dirname2, extname as extname2, join as join5, resolve as resolve4 } from "path";
 var REMOTE_RE = /^https?:\/\//i;
 var GLOB_RE = /[*?[\]{}]/;
@@ -39098,7 +39217,7 @@ async function readImageBuffer(pathOrUrl) {
 }
 async function isDirectory(path41) {
   try {
-    const s = await stat4(path41);
+    const s = await stat5(path41);
     return s.isDirectory();
   } catch {
     return false;
@@ -42495,7 +42614,7 @@ Full guide: __tooling__/docs/tools/baker/images.md`
 import { defineCommand as defineCommand167 } from "citty";
 
 // src/commands/landing/critique.ts
-import { readdir as readdir11, stat as stat6 } from "fs/promises";
+import { readdir as readdir11, stat as stat7 } from "fs/promises";
 import path31 from "path";
 import { defineCommand as defineCommand157 } from "citty";
 
@@ -43482,7 +43601,7 @@ async function writeCritiqueSnapshot(projectRoot, snapshot) {
 }
 
 // src/commands/landing/source-version.ts
-import { readdir as readdir10, readFile as readFile24, stat as stat5 } from "fs/promises";
+import { readdir as readdir10, readFile as readFile24, stat as stat6 } from "fs/promises";
 import path30 from "path";
 async function landingSourceRelPaths(landingDir) {
   const rel = [];
@@ -43515,7 +43634,7 @@ async function computeLandingSourceSha(landingDir) {
 }
 async function isFile(p) {
   try {
-    return (await stat5(p)).isFile();
+    return (await stat6(p)).isFile();
   } catch {
     return false;
   }
@@ -43668,7 +43787,7 @@ function present(f) {
 }
 async function isDir(p) {
   try {
-    return (await stat6(p)).isDirectory();
+    return (await stat7(p)).isDirectory();
   } catch {
     return false;
   }
@@ -51363,7 +51482,7 @@ var groupCommand2 = defineCommand210({
 });
 
 // src/commands/videos/ingest.ts
-import { mkdtemp as mkdtemp3, rm as rm8, stat as stat7 } from "fs/promises";
+import { mkdtemp as mkdtemp3, rm as rm8, stat as stat8 } from "fs/promises";
 import { tmpdir as tmpdir4 } from "os";
 import path40 from "path";
 import { defineCommand as defineCommand211 } from "citty";
@@ -51747,7 +51866,7 @@ async function downloadThenIngest(args, country) {
       // we allow to fetch it cannot drift apart.
       timeoutMs: downloadTimeoutMs(durationSeconds(probe.info))
     });
-    const stats = await stat7(filePath);
+    const stats = await stat8(filePath);
     if (stats.size > MAX_VIDEO_INGEST_BYTES) {
       throw new ApiError(
         "VALIDATION_ERROR",
@@ -51852,7 +51971,7 @@ var searchCommand4 = defineCommand212({
 var tagsCommand6 = makeTagsCommand("videos", "video", "/api/videos/tags");
 
 // src/commands/videos/upload.ts
-import { readFile as readFile26, stat as stat8 } from "fs/promises";
+import { readFile as readFile26, stat as stat9 } from "fs/promises";
 import { basename as basename3, extname as extname4 } from "path";
 import { defineCommand as defineCommand213 } from "citty";
 var MIME_MAP = {
@@ -51936,7 +52055,7 @@ var uploadCommand2 = defineCommand213({
       const originalFilename = basename3(filePath);
       const descriptionContext = args.context;
       if (args["dry-run"]) {
-        const fileStats = await stat8(filePath);
+        const fileStats = await stat9(filePath);
         writeJson({
           ok: true,
           dryRun: true,