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.mdindex 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 worksdiff --git a/skills/brag/SKILL.md b/skills/brag/SKILL.mdindex 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, shareableYou 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.mdindex 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:```bashnpx 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.mdnew file mode 100644index 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.