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.

Refine voiceover feature documentation and implementation details

Sameer Shaika0263b4f2695
diff --git a/README.md b/README.md
index b99eedc..983383f 100644
--- a/README.md
+++ b/README.md
@@ -62,18 +62,13 @@ 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:
+Voiceover is off by default. Enable it explicitly with:
```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.
+Narration uses Kokoro through Hyperframes when enabled.
You get a `brag-output/` folder with the plan, a composition brief, share copy, and the rendered `brag.mp4`.
diff --git a/skills/brag/SKILL.md b/skills/brag/SKILL.md
index ef209bf..95d580e 100644
--- a/skills/brag/SKILL.md
+++ b/skills/brag/SKILL.md
@@ -10,21 +10,9 @@ 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.
+invocation contains `--voice`, set `voice.enabled = true`. Enable narration
+only for that run. Do not enable narration automatically and do not fall back
+to the normal no-voice workflow.
`/brag` turns the current project website or app into a short, polished, shareable launch video using Hyperframes. It is narrow, opinionated, and fun.
@@ -58,21 +46,23 @@ Parse these options:
| `--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.
+Voice is opt-in. If `--voice` is present, use Kokoro via Hyperframes and do
+not add any provider-selection logic. The voice workflow is intentionally
+single-provider in this PR.
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".
When the user gives freeform tone direction, map it to the nearest preset for pacing and structure, but preserve the user's direction in the plan and composition brief.
+## Narration guidance
+
+When `--voice` is enabled, write narration that complements the visuals, does
+not simply read visible text, matches scene pacing, sounds natural and
+conversational, and moves smoothly between scenes. Keep the script concise and
+specific to the product so the voice feels like part of the edit rather than a
+separate narration track.
+
---
## Output directory
diff --git a/skills/brag/references/step-3-compose.md b/skills/brag/references/step-3-compose.md
index 35af8f5..ffda43b 100644
--- a/skills/brag/references/step-3-compose.md
+++ b/skills/brag/references/step-3-compose.md
@@ -108,21 +108,16 @@ Hyperframes copies any SFX it selects into the same `assets/` tree after choosin
## Voiceover (only when the user explicitly asks)
-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.
+Voiceover is disabled unless the user explicitly requests it, for example
+with `--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,
+When voice is disabled, do not write a voiceover script, generate narration,
transcribe audio, duck music, add a voice track, or merge narration into the
-video. The normal video export must remain entirely audio-provider agnostic.
+video. The normal video export must remain entirely voice-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:
+When voice is enabled, write the narration lines into `brag-plan.md` under a
+`## Voiceover script` section, then generate the audio through Kokoro:
```bash
npx hyperframes tts "<narration text or path to script>" \
@@ -130,13 +125,9 @@ 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.
+If the user wants a different Kokoro voice, run `npx hyperframes tts --list`
+to see the available options. The command above is the voice implementation
+for this PR and should be used directly.
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
deleted file mode 100644
index dbf857c..0000000
--- a/skills/brag/references/voice.md
+++ /dev/null
@@ -1,89 +0,0 @@
-# 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.