[JamesFranc]

What

Adds Kokoro as a local narration voice for architecture walkthrough videos. Kokoro, ElevenLabs and the macOS voice now all plug in through one Voice interface.

• WALKTHROUGH_VOICE names the voice: kokoro, elevenlabs or mac.
  • Unset or empty keeps today's behaviour: ElevenLabs when ELEVEN_LABS_API_KEY is set to a non-blank value, else the macOS voice when WALKTHROUGH_MAC_VOICE is set, else a silent video with subtitles.
  • elevenlabs without a key, mac without WALKTHROUGH_MAC_VOICE, or any other value fails the render before any work starts.
• kokoro narrates through uv, running kokoro and soundfile at pinned versions under Python 3.12. KOKORO_VOICE picks the speaker (default af_heart). Only American or British English voices (prefix a or b) are accepted, because only those come back with word timings, and the render needs them to time scene cues.
• walkthrough/voice.ts defines the Voice interface and the pieces every voice shares. elevenlabs.ts, kokoro.ts and mac-voice.ts each implement it. voices.ts holds the registry and the one selection rule that both walkthrough render and check-tools use, so check-tools reports only the voice that will narrate as configured.
• Each voice's preflight sets its own exit code, so the macOS voice's exit codes are unchanged.
• Narration is cached by voice and text. Cache keys for ElevenLabs and the macOS voice are unchanged, so existing caches are reused, and tests pin all three voices' keys.

The README covers Kokoro setup and the variables. skills/architecture/references/walkthrough.md covers voice selection and adding a voice.

Why

Without an ElevenLabs key or macOS, walkthrough videos render silent, with the narration as subtitles. Kokoro gives narrated videos on any platform at no cost and without a network service. Putting voices behind one interface means adding another is a module implementing Voice, plus registry, check-tools and docs entries that the walkthrough reference lists, with no changes to the renderer.

🤖 Generated with Claude Code

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: bd0414be-3b4a-4cd7-9412-cb4b59728283

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[mdnorman]

Thank you for this! The idea is being adopted: a local Kokoro voice for walkthrough narration, behind a shared voice interface.

This repository is a published snapshot, so changes land in the source repository and reach here with a release. Rather than merging this PR, we re-implemented the idea there:

• WALKTHROUGH_KOKORO_VOICE names the speaker.
• Voice priority is ElevenLabs, then the macOS voice, then Kokoro, then a silent, subtitled render.
• You're credited as a co-author on the commit.

It will show up here in a future release. Closing this one in favour of that change.

[mdnorman]

This shipped in v1.102.0.

A correction to my earlier comment: the co-author credit is on the commit in the source repository, but the release commit here doesn't carry it. I've added a credit line to the release notes instead, and future releases will keep co-author credit on the release commit.