feat(voice-server): add TTS provider abstraction with fallback order

[zitongcharliedeng]

Summary

• Adds pluggable TTS provider system with configurable fallback order
• Extracts ElevenLabs logic into provider class (backwards compatible)
• Adds Piper provider for free local/offline TTS
• Refactors MacOSSay provider using native command
• Adds cross-platform audio playback (afplay/aplay/powershell)

Motivation

Related to #166 and complements #171. While pai-voice adds a CLI alternative to the HTTP server, this PR adds:

1. Provider abstraction - Multiple TTS backends can coexist
2. Fallback order - Configure which providers to try via
3. Cross-platform audio - Works on macOS, Linux, and WSL
4. Local TTS option - Piper provides free offline TTS (no API costs)

Configuration

{
  "providers": ["piper", "elevenlabs", "macos"]
}

First available provider is used. If no config exists, falls back to ElevenLabs API directly (fully backwards compatible).

Providers

Provider	Type	Platform	Requirements
elevenlabs	Cloud	All	API key in ~/.env
piper	Local	Linux/WSL	piper binary + voice models
macos	Local	macOS	None (built-in)

Test plan

• Verify ElevenLabs still works when no config.json present
• Test provider fallback when first provider unavailable
• Test Piper on Linux/WSL
• Test MacOS provider on macOS
• Verify /health endpoint shows correct provider

🤖 Generated with Claude Code

[zitongcharliedeng]

Manual Testing Results

Windows WSL2 Testing (via PowerShell MediaPlayer)

Test	Provider	Result
Audio playback from WSL	ElevenLabs	✅ Passed
Audio playback from WSL	Piper	✅ Passed
Path conversion (wslpath)	N/A	✅ Working
MediaPlayer (no GUI window)	N/A	✅ Working

Test Plan Progress

• Verify ElevenLabs still works when no config.json present
• Test provider fallback when first provider unavailable
• Test Piper on Linux/WSL
• Test MacOS provider on macOS (no macOS available)
• Verify /health endpoint shows correct provider

Notes

• PowerShell MediaPlayer plays audio from WSL without opening a GUI window
• \ correctly converts WSL paths to Windows format
• Provider fallback works correctly (Piper -> ElevenLabs when Piper unavailable)
• \ type correctly detects \ via kernel release string

🤖 Manually tested by Charlie on Windows 11 :)

[zitongcharliedeng]

Re: per-agent voice IDs - This is already supported. The /notify endpoint accepts voice_id in the POST body, which gets passed to the provider. Each agent hook can pass a different voice_id per request. The Piper provider also supports voice mapping via voices.json config.

From Claude.

[zitongcharliedeng]

Addressed remaining review comments:

Naming fixes:

• Renamed SHELL_ENV to currentShellEnvironment (idiomatic camelCase)
• Renamed audio-playback.ts to desktop-audio-playback.ts for clarity
• Renamed providers/ to tts-providers/ (done previously)

Already addressed:

• providerConstructorsFromConfigNames - was already using this name
• Provider loading via loadProvider() in tts-providers/index.ts
• Config order: elevenlabs, macos-say, piper
• Interface uses synthesize() returning AudioResult (buffer + format)

Design decisions:

• Provider map is "hardcoded" because it maps config strings to TypeScript classes - this is the factory pattern, config.json controls the order/selection
• Server.ts no longer has ElevenLabs-specific logic, just calls provider.synthesize()
• Piper implementation follows official CLI usage (--model, --speaker, --output_file, stdin for text)

All commits squashed into single conventional commit: feat(voice-server): add pluggable TTS provider system

[danielmiessler]

Hey, thank you so much for this submission. We're about to change the project significantly to solve a number of core issues. Once we do that, let's revisit if it makes sense.