Voice

Unified text-to-speech module for AI agents. Supports local (Piper) and cloud (ElevenLabs) TTS backends.

Installation

pip install -r requirements.txt

For local TTS (optional):

pip install piper-tts huggingface_hub

Quick Start

from voice import speak, speak_async, set_backend

# Local TTS (default, offline, free)
speak("Hello world")

# Non-blocking
speak_async("This won't block")

# Use ElevenLabs (requires API key)
speak("Natural voice", backend="elevenlabs")

# Switch default backend
set_backend("elevenlabs")
speak("Now using ElevenLabs")

Configuration

ElevenLabs

Set environment variables:

export ELEVENLABS_API_KEY="your-api-key"
export ELEVENLABS_VOICE_ID="voice-id"  # Optional

Or configure programmatically:

from voice import configure_elevenlabs

configure_elevenlabs(
    api_key="your-api-key",
    voice_id="voice-id",
    model_id="eleven_v3"
)

Local TTS (Piper)

Voice models are downloaded automatically from Hugging Face on first use. No configuration required.

API

Core Functions

Function	Description
speak(text, backend=None, force=False, voice="male")	Speak text (blocking)
speak_async(text, ...)	Speak text (non-blocking)
announce(prefix, message)	Dual-part announcement with beep
say(text) / say_async(text)	Aliases for speak

Backend Management

Function	Description
get_backend()	Get current backend ("local" or "elevenlabs")
set_backend(backend)	Set default backend
is_backend_available(backend)	Check if backend is available

Mute Control

Function	Description
mute() / unmute()	Mute/unmute audio
toggle_mute()	Toggle mute state
is_muted()	Check mute state

Sound Effects

Function	Description
play_beep()	Play alert beep
play_startup_chime()	Play startup chime

ElevenLabs Specific

Function	Description
configure_elevenlabs(api_key, voice_id, ...)	Configure ElevenLabs settings
elevenlabs_generate_to_file(text, path)	Generate audio to file

Status

from voice import get_status

status = get_status()
# {
#   "backend": "local",
#   "muted": False,
#   "local_available": True,
#   "elevenlabs_available": True,
#   ...
# }

Backends

Local (Piper TTS)

• Offline, no API key needed
• Free, unlimited usage
• Robotic but clear voices
• Two voices: male (danny) and female (amy)

ElevenLabs

• Cloud-based, requires API key
• Natural, expressive voices
• Pay-per-character pricing
• Many voice options

Voice Presets (ElevenLabs)

from voice import VOICE_PRESETS, configure_elevenlabs

# Available presets: conversational, narration, expressive, stable
configure_elevenlabs(voice_settings=VOICE_PRESETS["expressive"])

License

MIT