🎙️ voice-server: Local TTS for PAI - Zero API Costs (MacOS only)

[madeinoz67]

Hi everyone! I wanted to share a project I've been working on that might be
useful for PAI users who want voice notifications without external API
dependencies.

What is voice-server?

voice-server is a local-first Text-to-Speech service built specifically for
PAI. It runs entirely on your Mac using Apple Silicon, so there are:

• ❌ No API keys needed
• ❌ No per-character charges
• ❌ No rate limits
• ❌ No data sent to external services

Key Features

• 41 Built-in Voices - Numeric voice IDs (1-41) across multiple accents
• Near Real-Time - ~1.0x RTF with <500ms latency using Kokoro-82M
• Multi-language - English, British, Japanese, Chinese voices
• Drop-in Compatible - PAI ElevenLabs-compatible API Voice-Server if you're migrating
• macOS Native - Deep integration with notifications and afplay

What's New in v0.1.9

Just released today with documentation improvements:

• Fixed repository URLs
• Added Model Testing section (Kokoro vs qwen-tts comparison)
• Improved changelog generation

Quick Start with PAI

Install via Homebrew

brew tap madeinoz67/tap
brew install voice-server
pipx install mlx-audio

Start the service

brew services start voice-server

Test with PAI

curl -X POST http://localhost:8888/pai
-H "Content-Type: application/json"
-d '{"message": "PAI Algorithm initialized"}'

Voice Configuration

Voices are configured via simple numeric IDs in your PAI agent
personalities:

my-agent

Voice ID: 12 (professional male)

Speed: 1.0
Prosody: speak in a neutral tone

Model Performance

After testing multiple TTS backends on Apple Silicon:

Kokoro-82M (Recommended)

• Latency: <500ms to first audio
• Quality: Excellent, near real-time
• Voices: 41 built-in options
• Verdict: Best choice for PAI voice notifications

qwen-tts (Alternative)

• Latency: 6-15 seconds before playback
• Quality: Inconsistent, with stuttering and streaming issues
• Notes: Self-contained like Kokoro, offers more flexibility for custom
  voice cloning
• Verdict: Interesting for specialized use cases, but not recommended for
  general PAI use

Links

• Repository: https://github.com/madeinoz67/madeinoz-voice-server
• Documentation: https://madeinoz67.github.io/madeinoz-voice-server/
• bun: @madeinoz67/voice-server

Community

If you try it out, I'd love to hear:

• Which voices work best for different agent personalities
• Any performance benchmarks on different Mac models
• Feedback on voice quality for various use cases
• Experiences with other TTS backends on Apple Silicon

Open to suggestions and improvements!

[peterlynch]

great job - I did the same thing circa PAI 1.0 - glad you shared yours.

[jlacour-git]

Great work @madeinoz67 — I've been running a Kokoro-82M voice server based on your approach for a few weeks and it's been excellent. Sub-500ms latency, zero API costs, fully drop-in for PAI's /notify endpoint.

A couple of things I ran into that might be useful for you and others:

1. Voice name passthrough bug
getKokoroVoice() only handles numeric IDs (1-41). If you pass a Kokoro voice name string like "ef_dora", parseInt() returns NaN and it silently falls back to af_heart. Fix: check if the input string matches a known voice name before attempting parseInt, and pass it through unchanged.

2. Missing voices — 54, not 41
The Kokoro-82M model actually ships 54 voice files, not 41. The missing 13 are European (ef_dora, em_alex, em_santa), French (ff_siwis), Hindi (hf_alpha, hf_beta, hm_omega, hm_psi), Italian (if_sara, im_nicola), and Portuguese (pf_dora, pm_alex, pm_santa).

3. Settings integration
I use settings.json → daidentity.voiceId set to the actual Kokoro voice name (e.g., "ef_dora") rather than a numeric ID or custom alias. The hooks pass it through in the curl payload. Clean and explicit.

Setup notes for anyone trying this:

• Bun must be installed via curl -fsSL https://bun.sh/install | bash, not via Homebrew. When Bun is installed via brew install oven-sh/bun/bun, the entire Kokoro voice server install can fail due to path/dependency resolution issues. This was a painful one to debug.
• mlx-audio needs Python 3.13 (not 3.14 — spacy breaks)
• espeak-ng must be installed via brew for proper phonemization — without it, audio plays but pronunciation is garbled
• pipx install mlx-audio then manually inject: misaki, num2words, spacy, phonemizer

Happy to share diffs for the voice name passthrough + missing voices fix if helpful. Thanks for building this!

[danielmiessler]

Hey @madeinoz67, thanks for raising this, and sorry it sat for a while.

We're changing how LifeOS ships. Instead of cloning a full ~/.claude directory and running it as a complete system, LifeOS is becoming a skill you install through an agentic installer. The installer hands integration to your own AI, which reads your actual machine (your OS, your paths, your harness) and wires the hooks and system prompt in where they belong.

That's aimed right at what you hit here. The old "one directory, one layout, hope it matches your setup" approach is exactly what broke for so many people, and the new model should handle it far better because your AI does the integration per machine instead of us guessing.

So we're closing this in prep for that release. If it still bites you once the skill-based version is out, reopen or file a fresh one and we'll jump on it. Appreciate you taking the time.