Skip to content

Commit fcbfb95

Browse files
feat(skills): canonical fully-silent marker + auth status exit-code docs
product-launch's Step 3.1 gate said "or the project is marked silent" but nothing defined how to mark one, and audio.mjs unconditionally retrieved BGM. Define the canonical marker — `music: none` in the storyboard's top YAML block, plus no SCRIPT.md — and honor it: audio generate produces nothing (removing stale audio_meta.json, since absence is what assemble treats as silent), and `music: none` with narration keeps TTS while turning BGM off. Also documents the `auth status` exit-code contract (exit 1 while signed out is the normal offline state, not a failure) in the product-launch Step 0 note and the CLI skill's cloud reference. Co-Authored-By: Claude Opus 4.8 <[email protected]>
1 parent 41b62f9 commit fcbfb95

6 files changed

Lines changed: 112 additions & 7 deletions

File tree

‎skills-manifest.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@
4646
"files": 10
4747
},
4848
"media-use": {
49-
"hash": "a20b4ae436bd5cb8",
49+
"hash": "6dc869b655caf834",
5050
"files": 125
5151
},
5252
"motion-graphics": {

‎skills/hyperframes-cli/references/cloud.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,10 @@ Cloud rendering needs a HeyGen credential, stored at `~/.heygen/credentials` (`0
2121
npx hyperframes auth login # OAuth 2.0 + PKCE, opens the browser
2222
npx hyperframes auth login --api-key # CI/headless: hidden prompt, or pipe: echo "$HEYGEN_API_KEY" | ... --api-key
2323
npx hyperframes auth status # active credential source, identity, billing snapshot
24+
# exit 0 = signed in and verified; exit 1 = not signed in,
25+
# or the credential was rejected — signed-out exit 1 is the
26+
# normal offline state (scripts: `auth status || echo offline`),
27+
# not a command failure
2428
npx hyperframes auth refresh # force-refresh an OAuth token before a long job
2529
npx hyperframes auth logout # clear the stored credential
2630
```

‎skills/product-launch-video/SKILL.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ Initialize only if `hyperframes.json` is missing. Name `<project>` from the bran
2929

3030
`npx hyperframes init "videos/<project>" --non-interactive --example=blank` — `init` checks the installed skills against the latest on GitHub and updates the global set if any are out of date.
3131

32-
**Show sign-in status before the brief** — run `npx hyperframes auth status` and **relay its output verbatim (don't paraphrase or rewrite it).** It reports whether voice/BGM will use HeyGen or local engines and, when not signed in, how to sign in. **If not signed in, STOP and wait for the user to choose — sign in, or say "go"/"offline" to continue with local engines — before asking the brief or anything else.** Treat it as a real decision point, not a passing note; don't fold the choice into the brief question, and don't write keys into a per-repo `.env`. (In autonomous mode, note the status and continue offline.) See `../media-use` → Preflight for the canonical guidance.
32+
**Show sign-in status before the brief** — run `npx hyperframes auth status` and **relay its output verbatim (don't paraphrase or rewrite it).** Note the exit code contract: `auth status` **exits 1 when not signed in** (and when the stored credential is rejected) — that non-zero exit is the normal signed-out state, not a command failure, so don't treat it as an error, don't retry it, and don't chain it with `&&`/`set -e` in a way that would abort the workflow. It reports whether voice/BGM will use HeyGen or local engines and, when not signed in, how to sign in. **If not signed in, STOP and wait for the user to choose — sign in, or say "go"/"offline" to continue with local engines — before asking the brief or anything else.** Treat it as a real decision point, not a passing note; don't fold the choice into the brief question, and don't write keys into a per-repo `.env`. (In autonomous mode, note the status and continue offline.) See `../media-use` → Preflight for the canonical guidance.
3333

3434
**Confirm the brief** in two rounds — through the question UI when the environment has one, conversationally otherwise. The intro text states **message** (the ONE thing the promo must communicate, in one sentence) and **language**. Skip a question only when the user's request already answered it. (`VO_MODE` is asked in Step 1 only when a script was pasted.)
3535

@@ -110,11 +110,13 @@ Start audio after Step 3 approval. Run it in the background, then continue to St
110110

111111
`node <SKILL_DIR>/scripts/audio.mjs --script ./SCRIPT.md --storyboard ./STORYBOARD.md --hyperframes . --out ./audio_meta.json --provider <provider> --voice <voice-id> &`
112112

113-
The audio script handles narration, word timings, BGM lookup from HeyGen's music library, and timing metadata. BGM mood comes from the storyboard's `music:` field. This uses the HeyGen Audio API for retrieval, not generation, and uses the same `~/.heygen` credential as TTS. For provider details, read `../media-use/audio/references/tts.md`.
113+
The audio script handles narration, word timings, BGM lookup from HeyGen's music library, and timing metadata. BGM mood comes from the storyboard's `music:` field; **`music: none` turns BGM off**. This uses the HeyGen Audio API for retrieval, not generation, and uses the same `~/.heygen` credential as TTS. For provider details, read `../media-use/audio/references/tts.md`.
114114

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

117-
**Gate:** audio job has started, or the project is marked silent.
117+
**The canonical fully-silent marker:** `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 Step 3.1 is a clean skip. Use it when the user asks for a silent / music-free video — don't improvise other spellings.
118+
119+
**Gate:** audio job has started, or the project is marked silent (`music: none` + no `SCRIPT.md`).
118120

119121
---
120122

‎skills/product-launch-video/references/story-design.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -332,6 +332,13 @@ The five registry types:
332332

333333
Pick a small set and repeat them: default to `crossfade` (or `blur-crossfade` when the backgrounds clash), and reach for `zoom-through` at section boundaries. Frame 1's `transition_in` is a placeholder.
334334

335+
## Music & silence
336+
337+
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.
338+
339+
- **`music: none`** — BGM off (narration, if any, still runs).
340+
- **`music: none` + no `SCRIPT.md`** — the canonical **fully-silent marker**: no narration, no BGM, no SFX. `audio.mjs` generates nothing and Step 3.1 is a clean skip. Use exactly this spelling when the user asks for a silent / music-free video.
341+
335342
## Frame template
336343

337344
Use the exact fields required by the core storyboard format. The narrative shape each frame satisfies:

‎skills/product-launch-video/scripts/audio.mjs‎

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

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

142158
// BGM mood: storyboard `music:` → message → arc → default. `mode: retrieve` is
@@ -146,7 +162,9 @@ function runGenerate(argv) {
146162
provider,
147163
speed,
148164
lines,
149-
bgm: { mode: "retrieve", query, blob: g.message || "", arc: g.arc || "" },
165+
bgm: bgmOff
166+
? { mode: "none" }
167+
: { mode: "retrieve", query, blob: g.message || "", arc: g.arc || "" },
150168
};
151169
if (userVoice) request.voice = userVoice;
152170

‎skills/product-launch-video/scripts/audio.test.mjs‎

Lines changed: 75 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import assert from "node:assert/strict";
2-
import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
2+
import { existsSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
33
import { tmpdir } from "node:os";
44
import { join } from "node:path";
55
import { spawnSync } from "node:child_process";
@@ -44,3 +44,77 @@ test("--provider takes precedence over HF_TTS_PROVIDER", () => {
4444
"kokoro",
4545
);
4646
});
47+
48+
// ── the canonical fully-silent marker (SKILL.md Step 3.1) ────────────────────
49+
// `music: none` in the storyboard's top YAML block + no SCRIPT.md marks the
50+
// project fully silent: generate must produce nothing (an absent
51+
// audio_meta.json is what assemble treats as silent) and clear stale meta.
52+
53+
/** Like runAudio, but with a caller-controlled storyboard and no request assertion. */
54+
function runAudioRaw({ storyboard, scriptMd = null, preexistingMeta = null }) {
55+
const dir = mkdtempSync(join(tmpdir(), "product-launch-audio-"));
56+
const engine = join(dir, "engine.mjs");
57+
writeFileSync(join(dir, "STORYBOARD.md"), storyboard);
58+
if (scriptMd != null) writeFileSync(join(dir, "SCRIPT.md"), scriptMd);
59+
if (preexistingMeta != null) writeFileSync(join(dir, "audio_meta.json"), preexistingMeta);
60+
writeFileSync(
61+
engine,
62+
`import { readFileSync, writeFileSync } from "node:fs";
63+
const argv = process.argv.slice(2);
64+
const flag = (name) => argv[argv.indexOf(name) + 1];
65+
const request = JSON.parse(readFileSync(flag("--request"), "utf8"));
66+
writeFileSync(new URL("request.json", import.meta.url), JSON.stringify(request));
67+
writeFileSync(flag("--out"), JSON.stringify({ voices: [], bgm: null, sfx: [] }));
68+
`,
69+
);
70+
const result = spawnSync(
71+
process.execPath,
72+
[script, "--hyperframes", dir, "--storyboard", join(dir, "STORYBOARD.md")],
73+
{ encoding: "utf8", env: { ...process.env, HF_MEDIA_ENGINE: engine } },
74+
);
75+
return { dir, result };
76+
}
77+
78+
test("music: none + no SCRIPT.md = fully silent: no engine run, no audio_meta.json", () => {
79+
const { dir, result } = runAudioRaw({ storyboard: "---\nmessage: Test\nmusic: none\n---\n" });
80+
81+
assert.equal(result.status, 0, result.stderr);
82+
assert.match(result.stdout, /marked silent/);
83+
// The engine was never invoked...
84+
assert.equal(existsSync(join(dir, "request.json")), false);
85+
// ...and no meta exists (absence ⇒ assemble treats the film as silent).
86+
assert.equal(existsSync(join(dir, "audio_meta.json")), false);
87+
});
88+
89+
test("fully-silent run removes stale audio_meta.json from a previous non-silent run", () => {
90+
const { dir, result } = runAudioRaw({
91+
storyboard: "---\nmessage: Test\nmusic: none\n---\n",
92+
preexistingMeta: JSON.stringify({ bgm: { path: "old.mp3" }, voices: [], sfx: [] }),
93+
});
94+
95+
assert.equal(result.status, 0, result.stderr);
96+
assert.equal(existsSync(join(dir, "audio_meta.json")), false);
97+
});
98+
99+
test("music: none with narration keeps TTS but turns BGM off (not fully silent)", () => {
100+
const { dir, result } = runAudioRaw({
101+
storyboard: "---\nmessage: Test\nmusic: none\n---\n",
102+
scriptMd: "## Hook (Frame 1)\n\n Spoken line for frame one.\n",
103+
});
104+
105+
assert.equal(result.status, 0, result.stderr);
106+
const request = JSON.parse(readFileSync(join(dir, "request.json"), "utf8"));
107+
assert.equal(request.bgm.mode, "none");
108+
assert.equal(request.lines.length, 1);
109+
});
110+
111+
test("a storyboard music mood still retrieves BGM (marker is exact, not fuzzy)", () => {
112+
const { dir, result } = runAudioRaw({
113+
storyboard: "---\nmessage: Test\nmusic: upbeat synthwave with heavy drums\n---\n",
114+
});
115+
116+
assert.equal(result.status, 0, result.stderr);
117+
const request = JSON.parse(readFileSync(join(dir, "request.json"), "utf8"));
118+
assert.equal(request.bgm.mode, "retrieve");
119+
assert.equal(request.bgm.query, "upbeat synthwave with heavy drums");
120+
});

0 commit comments

Comments
 (0)