Skip to content

armgit / brag

Public Imported from GitHub
0

You built it. Now brag. Turn the project you just created into a short, shareable launch video with one command.

Add voiceover support to brag skill

Sameer Shaik5d43bf8ab247
diff --git a/README.md b/README.md
index 4450cf9..b99eedc 100644
--- a/README.md
+++ b/README.md
@@ -62,6 +62,19 @@ Or steer the tone:
/brag --tone "fake Series A launch from 2016"
```
+Voiceover is off by default. Enable it explicitly with Kokoro (the local
+default provider), or opt into ElevenLabs:
+
+```text
+/brag --voice
+/brag --voice --voice-provider kokoro
+/brag --voice --voice-provider elevenlabs # requires ELEVENLABS_API_KEY
+```
+
+A provider choice alone never turns narration on. See
+[`skills/brag/references/voice.md`](skills/brag/references/voice.md) for the
+provider contract and failure behavior.
+
You get a `brag-output/` folder with the plan, a composition brief, share copy, and the rendered `brag.mp4`.
## How it works
diff --git a/skills/brag/SKILL.md b/skills/brag/SKILL.md
index 905d277..ef209bf 100644
--- a/skills/brag/SKILL.md
+++ b/skills/brag/SKILL.md
@@ -7,6 +7,25 @@ description: Turn the current project website into a short, polished, shareable
You built it. Now let's brag about it.
+## Invocation dispatch (must happen first)
+
+Before inspecting the project, parse the complete `/brag` invocation. If the
+invocation contains `--voice`, set `voice.enabled = true`. If it contains
+`--voice-provider <value>`, record that exact provider. Do not silently drop
+either flag and do not fall back to the normal no-voice workflow.
+
+When `voice.enabled` is true, validate the provider immediately:
+
+- missing provider: use `kokoro`;
+- `kokoro`: continue without credentials;
+- `elevenlabs`: require `ELEVENLABS_API_KEY`, then use the ElevenLabs adapter;
+- any other value: stop and list `kokoro` and `elevenlabs`.
+
+If an enabled provider cannot be used, report the provider-specific error and
+stop. Never complete a video while claiming that the requested voice provider
+was used when narration was skipped. Include the resolved voice state and
+provider in the plan and final handoff.
+
`/brag` turns the current project website or app into a short, polished, shareable launch video using Hyperframes. It is narrow, opinionated, and fun.
## What this skill does
@@ -38,6 +57,17 @@ Parse these options:
| `--no-music` | flag | music on |
| `--no-sfx` | flag | sfx on |
| `--title` | string | inferred from project |
+| `--voice` | flag | narration off |
+| `--voice-provider` | `kokoro`, `elevenlabs` | `kokoro` (only with `--voice`) |
+
+Voice is opt-in. Selecting a provider does not enable narration by itself.
+Read [references/voice.md](references/voice.md) before planning any run that
+contains `--voice` or `--voice-provider`.
+
+Reject an unsupported `--voice-provider` immediately and list `kokoro` and
+`elevenlabs` as the supported values. If `elevenlabs` is selected with voice
+enabled, verify `ELEVENLABS_API_KEY` before inspecting the project or creating
+the composition.
Tone can be a preset (`default`, `polished`, `yc-parody`, `chaotic`, `deadpan`, `cinematic`, `app-store`) or a creative direction such as "fake Series A launch from 2016", "museum exhibit", or "overproduced mobile game ad".
diff --git a/skills/brag/references/step-3-compose.md b/skills/brag/references/step-3-compose.md
index 3bcac47..35af8f5 100644
--- a/skills/brag/references/step-3-compose.md
+++ b/skills/brag/references/step-3-compose.md
@@ -108,7 +108,21 @@ Hyperframes copies any SFX it selects into the same `assets/` tree after choosin
## Voiceover (only when the user explicitly asks)
-Voiceover is off by default and is not offered to the user. Only add narration when the user explicitly requests it ("add a voiceover", "narrate this", etc.). In that case, write the narration lines into `brag-plan.md` under a `## Voiceover script` section, then generate the audio:
+Read [voice.md](voice.md) for the provider contract, defaults, and validation
+rules. Voiceover is disabled unless the user explicitly requests it (for
+example, "add a voiceover", `--voice`, or "narrate this"). Do not offer or
+enable narration during a normal `/brag` run.
+
+When voice is disabled, do not write a voiceover script, call a provider,
+transcribe audio, duck music, add a voice track, or merge narration into the
+video. The normal video export must remain entirely audio-provider agnostic.
+
+When voice is enabled, validate `voice.provider` before creating the
+composition. Use `kokoro` when no provider was specified. Select
+`elevenlabs` only when the user explicitly requested it, and require
+`ELEVENLABS_API_KEY` before invoking its adapter. Write the narration lines
+into `brag-plan.md` under a `## Voiceover script` section, then generate the
+audio through the provider contract:
```bash
npx hyperframes tts "<narration text or path to script>" \
@@ -116,6 +130,12 @@ npx hyperframes tts "<narration text or path to script>" \
--output <output-dir>/composition/assets/voiceover.wav
```
+The command above is the Kokoro implementation. For ElevenLabs, use the
+installed Hyperframes ElevenLabs media adapter with the same input/output
+contract; do not add provider-specific calls to the composition or skill
+pipeline. Both providers must leave one local audio artifact at
+`assets/voiceover.wav` (or an equivalent path passed to the composition).
+
Run `npx hyperframes tts --list` to see other voices.
Wire it into the composition on its own track. Music ducks to 0.12–0.15 for the duration of the voiceover, then returns to its normal level:
diff --git a/skills/brag/references/voice.md b/skills/brag/references/voice.md
new file mode 100644
index 0000000..dbf857c
--- /dev/null
+++ b/skills/brag/references/voice.md
@@ -0,0 +1,89 @@
+# Voice configuration
+
+Voiceover is an opt-in feature. The default configuration is:
+
+```yaml
+voice:
+ enabled: false
+ provider: kokoro
+```
+
+The skill accepts these invocation options:
+
+```text
+/brag --voice
+/brag --voice --voice-provider kokoro
+/brag --voice --voice-provider elevenlabs
+```
+
+`--voice` enables narration. `--voice-provider` is only meaningful when voice
+is enabled and accepts `kokoro` or `elevenlabs`; it defaults to `kokoro`.
+Provider selection must not implicitly enable voice.
+
+These flags are invocation state, not suggestions. Once `--voice` is present,
+the run must either generate narration with the resolved provider or stop with
+an actionable error. It must never silently continue with a no-voice video.
+
+## Provider contract
+
+The composition workflow treats providers through this contract:
+
+```text
+generate(text, output_path, options) -> audio file
+```
+
+A provider must accept the narration text, write one audio file at the
+requested path, and report a readable error if generation fails. The
+composition pipeline only consumes that audio file and never depends on a
+provider-specific client, API response, or merge operation.
+
+The provider boundary is:
+
+```text
+voice.enabled
+ false -> no script audio, provider selection, or audio merge
+ true -> validate provider -> generate audio -> transcribe / time scenes
+```
+
+## Providers
+
+### Kokoro (default)
+
+Kokoro runs locally through Hyperframes and does not require an API key:
+
+```bash
+npx hyperframes tts <script> --voice af_heart \
+ --output <output-dir>/composition/assets/voiceover.wav
+```
+
+Use `npx hyperframes tts --list` when a different Kokoro voice is requested.
+
+### ElevenLabs (opt-in)
+
+ElevenLabs is selected only with `--voice-provider elevenlabs`. Require
+`ELEVENLABS_API_KEY` before invoking the provider; fail with an actionable
+message if it is absent. Keep the key in the environment and never write it
+to the plan, composition, logs, or share copy.
+
+The ElevenLabs adapter must produce the same output artifact as Kokoro (a
+local WAV or MP3 at the requested path). The rest of the workflow must not
+branch on that format or on ElevenLabs response details. Use the installed
+Hyperframes media adapter/workflow for the actual request rather than adding
+an ElevenLabs client to `/brag`.
+
+Unsupported providers must fail before project inspection or composition
+creation and list the supported values: `kokoro`, `elevenlabs`.
+
+## Failure behavior
+
+- Voice disabled: skip narration, provider validation, TTS, transcription,
+ ducking, and audio-track wiring.
+- Voice enabled with an unknown provider: stop with a configuration error.
+- ElevenLabs selected without `ELEVENLABS_API_KEY`: stop before generation and
+ explain how to set it.
+- Provider request failure: preserve the provider error in the run log and
+ surface a concise message naming the selected provider.
+
+When voice is enabled, transcribe the generated artifact and use its real
+duration/word timings to pace scenes. Never use fixed scene timings just
+because the selected provider changed.