Voice Quality Audition

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)

---

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

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

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.14, 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-tg-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

---

Reference Documentation

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

Post-Execution Reflection

After this skill completes, reflect before closing the task:

0. Locate yourself. — Find this SKILL.md's canonical path (Glob for this skill's name) before editing. All corrections target THIS file and its sibling references/ — never other documentation. 1. What failed? — Fix the instruction that caused it. If it could recur, add it as an anti-pattern. 2. What worked better than expected? — Promote it to recommended practice. Document why. 3. What drifted? — Any script, reference, or external dependency that no longer matches reality gets fixed now. 4. Log it. — Every change gets an evolution-log entry with trigger, fix, and evidence.

Do NOT defer. The next invocation inherits whatever you leave behind.

---

---

voice-quality-audition Evolution Log

Voice Catalog

Comprehensive listing of Kokoro TTS voices with quality grades, characteristics, and selection guidance.

Grade Criteria

Female Voices

af_heart (Heart) -- Grade A

The current default English voice. Excellent naturalness with warm, expressive delivery. Handles long passages well without listener fatigue. Best all-around female voice.

Strengths: Natural cadence, warm tone, good breath pacing, handles punctuation naturally. Weaknesses: None significant at current Kokoro version. Recommended for: Default TTS, long-form reading, notifications.

af_bella (Bella) -- Grade A-

Near-excellent naturalness. Slightly more formal tone than Heart. Excellent for professional or narration contexts.

Strengths: Clear enunciation, professional tone, consistent quality across sentence lengths. Weaknesses: Slightly less warm than Heart; minor rhythm variations on complex sentences. Recommended for: Professional narration, formal notifications.

af_nicole (Nicole) -- Grade B-

Above average clarity. Noticeable synthetic quality on certain vowel sounds but generally pleasant.

Strengths: Good clarity, distinctive timbre. Weaknesses: Some vowel sounds feel synthetic; pacing can be uneven on long passages. Recommended for: Short notifications, variety rotation.

af_aoede (Aoede) -- Grade C+

Acceptable quality. Serviceable for notifications but has noticeable robotic artifacts on longer passages.

Strengths: Distinct voice character, handles short phrases well. Weaknesses: Robotic pacing on complex sentences, inconsistent stress patterns. Recommended for: Short alerts, variety when primary voices are unavailable.

af_kore (Kore) -- Grade C+

Similar tier to Aoede. Acceptable for short-form use.

Strengths: Clear articulation on short phrases. Weaknesses: Unnatural rhythm on long passages, occasional emphasis on wrong syllables. Recommended for: Short alerts only.

af_sarah (Sarah) -- Grade C+

Acceptable quality with a softer delivery style.

Strengths: Softer tone may suit certain content types. Weaknesses: Tends to lose clarity on technical or complex words; rhythm inconsistencies. Recommended for: Casual short notifications.

Male Voices

am_adam (Adam) -- Grade F+

Poor quality with significant artifacts. Not recommended for regular use.

Strengths: Recognizably male voice. Weaknesses: Significant synthetic artifacts, unnatural pacing, poor handling of punctuation. Recommended for: Testing only.

am_michael (Michael) -- Unrated

Not yet formally evaluated. Needs audition assessment.

Strengths: TBD. Weaknesses: TBD. Recommended for: Audition candidate.

am_echo (Echo) -- Grade D

Below average quality. Robotic delivery unsuitable for extended listening.

Strengths: Intelligible on short phrases. Weaknesses: Robotic tone, poor prosody, unpleasant on long passages. Recommended for: Testing only.

am_puck (Puck) -- Unrated

Not yet formally evaluated. Needs audition assessment.

Strengths: TBD. Weaknesses: TBD. Recommended for: Audition candidate.

Chinese Voice

zf_xiaobei -- Default Chinese Voice

Configured via TTS_VOICE_ZH. Used when CJK character ratio exceeds 20% (detected by detect_language in tts-common.sh). Not included in the English audition rotation.

Voice Selection Guidance

For Default TTS (TTS_VOICE_EN)

Use af_heart (Grade A). It provides the best naturalness and listener comfort for the primary use case of reading Claude Code responses aloud via Telegram.

For Variety or Rotation

If implementing voice rotation, limit to Grade B- and above: af_heart, af_bella, af_nicole.

For Short Notifications Only

Any Grade C+ voice is acceptable for brief alerts: af_aoede, af_kore, af_sarah.

Male Voices

The male voice catalog is currently weak. am_michael and am_puck are unrated and should be auditioned before use. am_adam (F+) and am_echo (D) are not recommended for production.

Configuration

Voices are configured in ~/.claude/automation/claude-telegram-sync/mise.toml:

[env]
TTS_VOICE_EN = "af_heart"      # Kokoro English voice ID
TTS_VOICE_ZH = "zf_xiaobei"    # Kokoro Chinese voice ID
TTS_VOICE_SAY_EN = "Samantha"  # macOS say fallback (English)
TTS_VOICE_SAY_ZH = "Ting-Ting" # macOS say fallback (Chinese)

The shell library tts-common.sh also reads EN_VOICE and ZH_VOICE environment variables, defaulting to af_heart and zf_xiaobei respectively.