Skip to content

Commit 9901b8f

Browse files
feat(skills): extend the fully-silent marker to faceless-explainer and pr-to-video
Both workflows reuse product-launch's audio model — their Step 3.1 gates carried the same undefined "marked silent" phrase, and their (intentionally identical) audio.mjs copies had the same unconditional BGM retrieve. Port the `music: none` marker handling into both copies, define the marker in their SKILL.md Step 3.1 and story-design references, and turn the copies' "intentionally identical" header claim into a byte-identity pin test so the next fix can't silently miss one of them. Co-Authored-By: Claude Opus 4.8 <[email protected]>
1 parent 34613df commit 9901b8f

8 files changed

Lines changed: 154 additions & 9 deletions

File tree

‎skills-manifest.json‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,8 @@
66
"files": 144
77
},
88
"faceless-explainer": {
9-
"hash": "4d51aa098ae2ebcf",
10-
"files": 18
9+
"hash": "252dc83791af7ed7",
10+
"files": 19
1111
},
1212
"figma": {
1313
"hash": "0e6e96f5a76ff824",
@@ -58,7 +58,7 @@
5858
"files": 132
5959
},
6060
"pr-to-video": {
61-
"hash": "932a3a6b30d9aec5",
61+
"hash": "7284a4e789f5447c",
6262
"files": 28
6363
},
6464
"product-launch-video": {

‎skills/faceless-explainer/SKILL.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -113,7 +113,9 @@ The audio script handles narration, word timings, BGM lookup from HeyGen's music
113113

114114
If there is no narration and no `SCRIPT.md`, skip voice generation. BGM may still run if the storyboard has a music mood.
115115

116-
**Gate:** audio job has started, or the project is marked silent.
116+
**The canonical fully-silent marker** (shared across the workflows that reuse this audio model): `music: none` in the STORYBOARD.md top YAML block **and** no `SCRIPT.md`. That combination marks the project silent — no narration, no BGM, no SFX. `audio.mjs` recognizes it and generates nothing (it removes any stale `audio_meta.json`; an absent `audio_meta.json` is what assemble treats as silent), so this step is a clean skip. `music: none` with narration keeps TTS and turns only BGM off. Use exactly this spelling — don't improvise other markers.
117+
118+
**Gate:** audio job has started, or the project is marked silent (`music: none` + no `SCRIPT.md`).
117119

118120
---
119121

‎skills/faceless-explainer/references/story-design.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -210,6 +210,13 @@ Treat `user_script.txt` as source material. Rewrite, reorder, merge, or omit to
210210

211211
Do not rewrite the user's words. Segment the script into frame-sized chunks at sentence or paragraph boundaries (you may split a long sentence at a natural clause boundary, but do not change words). Final duration follows the provided script.
212212

213+
## Music & silence
214+
215+
The storyboard's top YAML block carries a `music:` field — the BGM mood the audio step retrieves against (e.g. `music: confident minimal tech underscore`). Omitting it falls back to `message:` → `arc:` → a neutral default, so BGM plays unless turned off explicitly.
216+
217+
- **`music: none`** — BGM off (narration, if any, still runs).
218+
- **`music: none` + no `SCRIPT.md`** — the canonical **fully-silent marker**: no narration, no BGM, no SFX. `audio.mjs` generates nothing and the audio step is a clean skip. Use exactly this spelling when the user asks for a silent / music-free video.
219+
213220
## Frame template
214221

215222
Use the exact fields required by the core storyboard format. This is the narrative shape each frame should satisfy:

‎skills/faceless-explainer/scripts/audio.mjs‎

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@
2323
// node audio.mjs fetch-sfx --storyboard ./STORYBOARD.md --hyperframes .
2424

2525
import { spawnSync } from "node:child_process";
26-
import { existsSync, readFileSync, writeFileSync } from "node:fs";
26+
import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
2727
import { dirname, join, resolve } from "node:path";
2828
import { fileURLToPath } from "node:url";
2929
import { parseStoryboard } from "./lib/storyboard.mjs";
@@ -138,6 +138,22 @@ function runGenerate(argv) {
138138
text: l.text,
139139
}))
140140
: [];
141+
// The canonical fully-silent marker (SKILL.md Step 3.1): `music: none` in
142+
// the storyboard's top YAML block turns BGM off; combined with no SCRIPT.md
143+
// the project is fully silent — generate nothing and remove any stale meta
144+
// from a previous run (assemble treats an absent audio_meta.json as silent).
145+
const bgmOff =
146+
String(g.extra?.music ?? "")
147+
.trim()
148+
.toLowerCase() === "none";
149+
if (bgmOff && !lines.length) {
150+
rmSync(outPath, { force: true });
151+
rmSync(neutralPath(outPath), { force: true });
152+
console.log(
153+
"✓ audio generate: project marked silent (music: none, no SCRIPT.md) — nothing to generate",
154+
);
155+
return;
156+
}
141157
if (!lines.length) console.error("· no SCRIPT.md — silent film (BGM only)");
142158

143159
// BGM mood: storyboard `music:` → message → arc → default. `mode: retrieve` is
@@ -147,7 +163,9 @@ function runGenerate(argv) {
147163
provider: "auto",
148164
speed,
149165
lines,
150-
bgm: { mode: "retrieve", query, blob: g.message || "", arc: g.arc || "" },
166+
bgm: bgmOff
167+
? { mode: "none" }
168+
: { mode: "retrieve", query, blob: g.message || "", arc: g.arc || "" },
151169
};
152170
if (userVoice) request.voice = userVoice;
153171

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
import assert from "node:assert/strict";
2+
import { existsSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
3+
import { tmpdir } from "node:os";
4+
import { join } from "node:path";
5+
import { spawnSync } from "node:child_process";
6+
import test from "node:test";
7+
8+
const script = new URL("./audio.mjs", import.meta.url).pathname;
9+
10+
// The header of this adapter declares it "intentionally identical across the
11+
// reusing skills" — pin that contract so a fix landing in one copy can't
12+
// silently miss the other (the fully-silent marker bug did exactly that).
13+
test("audio.mjs is byte-identical to pr-to-video's copy (the stated contract)", () => {
14+
const here = readFileSync(script, "utf8");
15+
const sibling = readFileSync(
16+
new URL("../../pr-to-video/scripts/audio.mjs", import.meta.url),
17+
"utf8",
18+
);
19+
assert.equal(here, sibling);
20+
});
21+
22+
// ── the canonical fully-silent marker (SKILL.md Step 3.1) ────────────────────
23+
// Same contract as product-launch (see its audio.test.mjs): `music: none` in
24+
// the storyboard's top YAML block + no SCRIPT.md ⇒ generate nothing; with
25+
// narration ⇒ TTS runs, BGM off.
26+
27+
function runAudioRaw({ storyboard, scriptMd = null, preexistingMeta = null }) {
28+
const dir = mkdtempSync(join(tmpdir(), "faceless-audio-"));
29+
const engine = join(dir, "engine.mjs");
30+
writeFileSync(join(dir, "STORYBOARD.md"), storyboard);
31+
if (scriptMd != null) writeFileSync(join(dir, "SCRIPT.md"), scriptMd);
32+
if (preexistingMeta != null) writeFileSync(join(dir, "audio_meta.json"), preexistingMeta);
33+
writeFileSync(
34+
engine,
35+
`import { readFileSync, writeFileSync } from "node:fs";
36+
const argv = process.argv.slice(2);
37+
const flag = (name) => argv[argv.indexOf(name) + 1];
38+
const request = JSON.parse(readFileSync(flag("--request"), "utf8"));
39+
writeFileSync(new URL("request.json", import.meta.url), JSON.stringify(request));
40+
writeFileSync(flag("--out"), JSON.stringify({ voices: [], bgm: null, sfx: [] }));
41+
`,
42+
);
43+
const result = spawnSync(
44+
process.execPath,
45+
[script, "--hyperframes", dir, "--storyboard", join(dir, "STORYBOARD.md")],
46+
{ encoding: "utf8", env: { ...process.env, HF_MEDIA_ENGINE: engine } },
47+
);
48+
return { dir, result };
49+
}
50+
51+
test("music: none + no SCRIPT.md = fully silent: no engine run, no audio_meta.json", () => {
52+
const { dir, result } = runAudioRaw({ storyboard: "---\nmessage: Test\nmusic: none\n---\n" });
53+
54+
assert.equal(result.status, 0, result.stderr);
55+
assert.match(result.stdout, /marked silent/);
56+
assert.equal(existsSync(join(dir, "request.json")), false);
57+
assert.equal(existsSync(join(dir, "audio_meta.json")), false);
58+
});
59+
60+
test("fully-silent run removes stale audio_meta.json from a previous non-silent run", () => {
61+
const { dir, result } = runAudioRaw({
62+
storyboard: "---\nmessage: Test\nmusic: none\n---\n",
63+
preexistingMeta: JSON.stringify({ bgm: { path: "old.mp3" }, voices: [], sfx: [] }),
64+
});
65+
66+
assert.equal(result.status, 0, result.stderr);
67+
assert.equal(existsSync(join(dir, "audio_meta.json")), false);
68+
});
69+
70+
test("music: none with narration keeps TTS but turns BGM off (not fully silent)", () => {
71+
const { dir, result } = runAudioRaw({
72+
storyboard: "---\nmessage: Test\nmusic: none\n---\n",
73+
scriptMd: "## Hook (Frame 1)\n\n Spoken line for frame one.\n",
74+
});
75+
76+
assert.equal(result.status, 0, result.stderr);
77+
const request = JSON.parse(readFileSync(join(dir, "request.json"), "utf8"));
78+
assert.equal(request.bgm.mode, "none");
79+
assert.equal(request.lines.length, 1);
80+
});
81+
82+
test("a storyboard music mood still retrieves BGM (marker is exact, not fuzzy)", () => {
83+
const { dir, result } = runAudioRaw({
84+
storyboard: "---\nmessage: Test\nmusic: upbeat synthwave with heavy drums\n---\n",
85+
});
86+
87+
assert.equal(result.status, 0, result.stderr);
88+
const request = JSON.parse(readFileSync(join(dir, "request.json"), "utf8"));
89+
assert.equal(request.bgm.mode, "retrieve");
90+
assert.equal(request.bgm.query, "upbeat synthwave with heavy drums");
91+
});

‎skills/pr-to-video/SKILL.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -161,7 +161,9 @@ The audio script handles narration, word timings, BGM lookup from HeyGen's music
161161

162162
If there is no narration and no `SCRIPT.md`, skip voice generation. BGM may still run if the storyboard has a music mood.
163163

164-
**Gate:** audio job has started, or the project is marked silent.
164+
**The canonical fully-silent marker** (shared across the workflows that reuse this audio model): `music: none` in the STORYBOARD.md top YAML block **and** no `SCRIPT.md`. That combination marks the project silent — no narration, no BGM, no SFX. `audio.mjs` recognizes it and generates nothing (it removes any stale `audio_meta.json`; an absent `audio_meta.json` is what assemble treats as silent), so this step is a clean skip. `music: none` with narration keeps TTS and turns only BGM off. Use exactly this spelling — don't improvise other markers.
165+
166+
**Gate:** audio job has started, or the project is marked silent (`music: none` + no `SCRIPT.md`).
165167

166168
---
167169

‎skills/pr-to-video/references/story-design.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -185,6 +185,13 @@ Estimate while writing: `duration ≈ ceil(word_count / 2.2)`. 29 words → 13s
185185

186186
**Write each line as discrete cues, not one run-on breath.** Step 5 reveals each on-screen piece _when the voiceover names it_ (the anti-PowerPoint mechanism). A line with clear phrase boundaries — "Three retries — then it backs off — then it gives up clean" — hands the shot its reveal cadence for free; a single long clause leaves the frame nothing to pace to.
187187

188+
## Music & silence
189+
190+
The storyboard's top YAML block carries a `music:` field — the BGM mood the audio step retrieves against (e.g. `music: confident minimal tech underscore`). Omitting it falls back to `message:` → `arc:` → a neutral default, so BGM plays unless turned off explicitly.
191+
192+
- **`music: none`** — BGM off (narration, if any, still runs).
193+
- **`music: none` + no `SCRIPT.md`** — the canonical **fully-silent marker**: no narration, no BGM, no SFX. `audio.mjs` generates nothing and the audio step is a clean skip. Use exactly this spelling when the user asks for a silent / music-free video.
194+
188195
## Frame template
189196

190197
```md

‎skills/pr-to-video/scripts/audio.mjs‎

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@
2323
// node audio.mjs fetch-sfx --storyboard ./STORYBOARD.md --hyperframes .
2424

2525
import { spawnSync } from "node:child_process";
26-
import { existsSync, readFileSync, writeFileSync } from "node:fs";
26+
import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
2727
import { dirname, join, resolve } from "node:path";
2828
import { fileURLToPath } from "node:url";
2929
import { parseStoryboard } from "./lib/storyboard.mjs";
@@ -138,6 +138,22 @@ function runGenerate(argv) {
138138
text: l.text,
139139
}))
140140
: [];
141+
// The canonical fully-silent marker (SKILL.md Step 3.1): `music: none` in
142+
// the storyboard's top YAML block turns BGM off; combined with no SCRIPT.md
143+
// the project is fully silent — generate nothing and remove any stale meta
144+
// from a previous run (assemble treats an absent audio_meta.json as silent).
145+
const bgmOff =
146+
String(g.extra?.music ?? "")
147+
.trim()
148+
.toLowerCase() === "none";
149+
if (bgmOff && !lines.length) {
150+
rmSync(outPath, { force: true });
151+
rmSync(neutralPath(outPath), { force: true });
152+
console.log(
153+
"✓ audio generate: project marked silent (music: none, no SCRIPT.md) — nothing to generate",
154+
);
155+
return;
156+
}
141157
if (!lines.length) console.error("· no SCRIPT.md — silent film (BGM only)");
142158

143159
// BGM mood: storyboard `music:` → message → arc → default. `mode: retrieve` is
@@ -147,7 +163,9 @@ function runGenerate(argv) {
147163
provider: "auto",
148164
speed,
149165
lines,
150-
bgm: { mode: "retrieve", query, blob: g.message || "", arc: g.arc || "" },
166+
bgm: bgmOff
167+
? { mode: "none" }
168+
: { mode: "retrieve", query, blob: g.message || "", arc: g.arc || "" },
151169
};
152170
if (userVoice) request.voice = userVoice;
153171

0 commit comments

Comments
 (0)