explain-tts

Speak short styled explanations aloud through the homelab Kokoro TTS server, playing on the primary Mac. Powers the /explain-brief, /explain-simply, /explain-mild, /explain-quick, /explain-status, /ex

SKILL.md

GitHub

explain-tts

Portable spoken-explanation skill. Synthesis goes direct to the homelab Kokoro server (OpenAI-compatible API, URL baked into lib/config.sh, no env vars required). The audio response returns to the client that issued the command and plays locally. SSH forwarding to the Mac is an explicit opt-in fallback only (EXPLAIN_TTS_REMOTE_FALLBACK=1).

Command dispatch

Resolve the requested variant, then act exactly as specified. ${ARGUMENTS:-} is any trailing text after the command name.

Invocation Do this
/explain-brief <topic> Write a <=80-word neutral spoken script, then $SKILL/bin/tts-say --preset brief "<script>"
/explain-simply <topic> Write a <=120-word plain-language (ELI5) script, then run with --preset simply
/explain-mild <topic> Write a <=150-word measured walkthrough, then run with --preset mild
/explain-quick <topic> Write a <=25-word headline answer, then run with --preset quick
/explain-status Run $SKILL/bin/tts-selftest and summarize its report
/explain-options (bare) Run $SKILL/bin/tts-options and render the table it prints
/explain-options k=v ... Run $SKILL/bin/tts-options k=v ...; report accepted updates or validation errors
unknown /explain-* or /explain-help Render the dispatch table above verbatim

If the invocation carries no topic (${ARGUMENTS:-} empty), ask what to explain ONLY when no obvious subject exists in the current conversation; otherwise explain the most recent assistant answer at the preset's length.

Writing the spoken script (script-first presets)

  • Kokoro has no prosody markup. Differentiation comes from what you WRITE, plus voice/speed.
  • Strip markdown: no code fences, bullets, bold, links. Describe code verbally ("the retry function returns nil on timeout").
  • Expand acronyms on first use ("A P I", "S Q L"), then may use them plainly.
  • Never exceed the preset word cap; the script enforces caps mechanically, but you should hit them naturally.
  • Tone: quick=headline fact; brief=neutral summary; simply=a curious beginner could follow; mild=careful measured walkthrough with caveats.

Hard rules

  • ALWAYS foreground: never call tts-say with background execution; a bounded foreground call is the contract (background TTS causes notification loops).
  • Fail-soft: scripts are time-bounded and exit 0 even when the server or Mac is unreachable. A silent failure with a history row is success for this skill; never retry in a loop.
  • One topic per call. For long explanations synthesize the capped script, not the whole text.

Options

voice (e.g. af_heart or blend af_heart+af_bella(3)), speed (0.5-2.0), mute_until (epoch seconds). Persisted atomically in ~/.config/explain-tts/options.env; survives skill re-import/update because it lives outside the managed tree. Host-specific URL overrides also belong there via config.sh.

Playback adapters: macOS afplay; Linux paplay, pw-play, mpv, or ffplay (first available); Windows-compatible shells use PowerShell SoundPlayer when available.

Debugging order

See references/tts-pipeline.md: health probe, voices, history board, transport check.

Importing on another client

Run bin/install-explain-tts from this bundle. It copies the shared transport and all seven alias skills into ~/.agents/skills, which jcode and Claude Code both discover. The installer does not copy host options or overrides. After import, use /explain-help to confirm the alias registry and /explain-status to confirm Kokoro reachability.