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