Voice Quality Audition

Compare Kokoro TTS voice quality across all available voices. Runs tts_kokoro_audition.sh which plays a passage with each top voice. Each voice announces its name before reading the passage. Uses clipboard text or a default passage.

Platform: macOS (Apple Silicon)

When to Use This Skill

Audition all available Kokoro voices to hear quality differences
Compare specific voices side-by-side for a project
Re-evaluate voice grades after a Kokoro engine upgrade
Select a new default voice for TTS_VOICE_EN or TTS_VOICE_ZH
Test how a particular passage sounds across multiple voices

Requirements

Kokoro TTS engine installed and healthy (kokoro-install.sh --health)
Apple Silicon Mac with MLX Metal available
afplay available (ships with macOS)
Audition script at plugin scripts/tts_kokoro_audition.sh
Shared library at plugin scripts/lib/tts-common.sh

Voice Catalog

Voice ID	Name	Grade	Gender
af_heart	Heart	A	Female
af_bella	Bella	A-	Female
af_nicole	Nicole	B-	Female
af_aoede	Aoede	C+	Female
af_kore	Kore	C+	Female
af_sarah	Sarah	C+	Female
am_adam	Adam	F+	Male
am_michael	Michael	unrated	Male
am_echo	Echo	D	Male
am_puck	Puck	unrated	Male

Current defaults (configured in ~/.claude/automation/claude-telegram-sync/mise.toml):

English voice: af_heart (Grade A) via TTS_VOICE_EN
Chinese voice: zf_xiaobei via TTS_VOICE_ZH
macOS say fallback EN: Samantha via TTS_VOICE_SAY_EN
macOS say fallback ZH: Ting-Ting via TTS_VOICE_SAY_ZH

See Voice Catalog for detailed characteristics and grade criteria.

Workflow Phases

Phase 1: Preflight

Verify Kokoro is installed and healthy:

kokoro-install.sh --health

All 6 checks must pass (venv, Python 3.13, mlx_audio importable, kokoro_common.py, tts_generate.py, version.json).

Phase 2: Text Selection

The audition script reads from the macOS clipboard (pbpaste). If the clipboard is empty or not text, it falls back to a built-in passage about reading in a library.

To audition with custom text, copy the desired passage to the clipboard before running.

Phase 3: Ask User — Full or Selective Audition

Use AskUserQuestion to determine scope:

Full audition — Play all 10 voices sequentially (takes several minutes)
Select specific voices — Run only a subset (e.g., top 3 female voices)

For a selective audition, edit the VOICES array in the script or pass voice IDs manually.

Phase 4: Execute Audition

~/.local/bin/tts_kokoro_audition.sh

Or directly from the plugin source:

/path/to/plugins/tts-telegram-sync/scripts/tts_kokoro_audition.sh

The script acquires the TTS lock, plays each voice sequentially with a 1-second gap, then releases the lock on exit.

Phase 5: Feedback

Use AskUserQuestion to collect the user's preference:

Which voice sounded best?
Any voices to eliminate from future consideration?
Should we update grade assignments?

Phase 6: Apply Configuration

Optionally update the default voice in mise.toml:

# ~/.claude/automation/claude-telegram-sync/mise.toml
[env]
TTS_VOICE_EN = "af_heart"   # Change to preferred voice ID
TTS_VOICE_ZH = "zf_xiaobei"

After changing mise.toml, restart the Telegram bot for the new voice to take effect.

TodoWrite Task Templates

1. [Preflight] Verify Kokoro TTS is installed and healthy (kokoro-install.sh --health)
2. [Text] Check clipboard for passage, fall back to default if empty
3. [Select] Ask user: full audition (all 10 voices) or specific voices
4. [Audition] Run tts_kokoro_audition.sh and let user listen
5. [Feedback] Ask user which voice they prefer and collect grade feedback
6. [Apply] Optionally update TTS_VOICE_EN in mise.toml and restart bot

Post-Change Checklist

Kokoro health check passed before audition
All selected voices played without errors
User confirmed preferred voice
mise.toml updated with new voice ID (if changed)
Bot restarted after configuration change (if applicable)
Voice catalog grades updated in reference doc (if re-graded)

Troubleshooting

Issue	Cause	Solution
No audio plays	Kokoro not installed	Run `kokoro-install.sh --install` or use `full-stack-bootstrap` skill
Audio cuts off mid-sentence	TTS lock stolen by another process	Check for competing TTS processes: `pgrep -la afplay`
Voice sounds wrong	Invalid voice ID in Kokoro model	Verify voice ID exists in `VOICES` array; check Kokoro version
Clipboard empty	No text copied	Script uses default passage automatically; no action needed
"ERROR: Local Kokoro not found"	Venv or script missing	Run `kokoro-install.sh --health` to diagnose; `--install` to fix
FAILED for a specific voice	Voice not available in model	Voice may require a different Kokoro version; check model compatibility
Lock not released	Script crashed without cleanup	Remove stale lock: `rm -f /tmp/kokoro-tts.lock`
All voices sound identical	Kokoro model not loaded properly	Re-download model: `kokoro-install.sh --upgrade`

Reference Documentation

Voice Catalog - Comprehensive voice listing with quality grades, characteristics, and selection guidance
Evolution Log - Change history for this skill

voice-quality-audition