Audio Tools
Text-to-Speech (TTS) and Speech-to-Text (STT) tools for agents
Enable your agents to speak and listen with TTS and STT tools.
from praisonaiagents import Agent
agent = Agent(
name="voice-assistant",
instructions="Use audio tools when the user sends voice or asks for speech.",
tools=["text_to_speech", "speech_to_text"],
)
agent.start("Read this reply aloud.")The user sends voice or asks for spoken output; the agent transcribes input and synthesises replies with STT/TTS tools.
Quick Start
- Bot CLI
bash # Enable TTS tool for your bot praisonai bot telegram --token $TOKEN --tts # Enable both TTS and STT praisonai bot telegram --token $TOKEN --tts --stt # Auto-convert all responses to speech praisonai bot telegram --token $TOKEN --auto-tts - Python
python from praisonai.tools.audio import create_tts_tool, create_stt_tool from praisonaiagents import Agent agent = Agent( name="voice-assistant", instructions="You can speak and listen.", tools=[create_tts_tool(), create_stt_tool()], ) response = agent.chat("Say hello in audio format")
TTS Tool
Convert text to speech and get an audio file.
Usage
from praisonai.tools.audio import tts_tool
result = tts_tool("Hello world!", voice="alloy")
if result["success"]:
print(result["audio_path"]) # /tmp/tts_abc123.mp3
print(result["media_line"]) # MEDIA:/tmp/tts_abc123.mp3from praisonai.tools.audio import create_tts_tool
from praisonaiagents import Agent
agent = Agent(
name="speaker",
tools=[create_tts_tool()]
)
# Agent calls tts() tool internally
agent.chat("Convert 'Hello world' to speech")Options
| Parameter | Type | Default | Description |
|---|---|---|---|
text | str | required | Text to convert |
voice | str | "alloy" | Voice: alloy, echo, fable, onyx, nova, shimmer |
model | str | "openai/tts-1" | TTS model |
output_format | str | "mp3" | Format: mp3, opus, aac, flac, wav |
output_dir | str | temp dir | Directory to save audio |
STT Tool
Transcribe audio files to text.
Usage
from praisonai.tools.audio import stt_tool
result = stt_tool("recording.mp3", language="en")
if result["success"]:
print(result["text"]) # Transcribed textfrom praisonai.tools.audio import create_stt_tool
from praisonaiagents import Agent
agent = Agent(
name="listener",
tools=[create_stt_tool()]
)
# Agent calls stt() tool internally
agent.chat("Transcribe the file at /path/to/audio.mp3")Options
| Parameter | Type | Default | Description |
|---|---|---|---|
audio_path | str | required | Path to audio file |
language | str | auto | Language code (en, es, fr, etc.) |
model | str | "openai/whisper-1" | STT model |
Bot CLI Options
Enable audio tools when starting bots:
| Option | Description |
|---|---|
--tts | Enable TTS tool |
--tts-voice VOICE | Voice (alloy, echo, fable, onyx, nova, shimmer) |
--tts-model MODEL | TTS model (default: openai/tts-1) |
--auto-tts | Auto-convert all responses to speech |
--stt | Enable STT tool |
--stt-model MODEL | STT model (default: openai/whisper-1) |
Examples
# Basic TTS
praisonai bot telegram --token $TOKEN --tts
# Custom voice
praisonai bot telegram --token $TOKEN --tts --tts-voice nova
# Auto-TTS mode (all responses become audio)
praisonai bot telegram --token $TOKEN --auto-tts
# Full audio capabilities
praisonai bot telegram --token $TOKEN --tts --stt --auto-ttsSupported Providers
Audio tools use the core AudioAgent which supports multiple providers via LiteLLM:
TTS Providers
| Provider | Model | Notes |
|---|---|---|
| OpenAI | openai/tts-1, openai/tts-1-hd | Default, high quality |
| Azure | azure/tts-1 | Enterprise |
| ElevenLabs | elevenlabs/eleven_multilingual_v2 | Premium voices |
| Gemini | gemini/gemini-2.5-flash-preview-tts |
STT Providers
| Provider | Model | Notes |
|---|---|---|
| OpenAI | openai/whisper-1 | Default, accurate |
| Azure | azure/whisper | Enterprise |
| Groq | groq/whisper-large-v3 | Fast |
| Deepgram | deepgram/nova-2 | Real-time |
Voice Options
Available voices for OpenAI TTS:
| Voice | Description |
|---|---|
alloy | Neutral, balanced (default) |
echo | Warm, conversational |
fable | Expressive, storytelling |
onyx | Deep, authoritative |
nova | Friendly, upbeat |
shimmer | Clear, professional |
Architecture
Best Practices
Add only the tools the agent needs
Give an agent text_to_speech when it must speak and speech_to_text when it must listen — not both by reflex. Fewer tools keep the model focused and cut the chance it synthesises audio when plain text would do.
Use –auto-tts sparingly
--auto-tts converts every bot reply to speech, which adds cost and latency to short acknowledgements. Prefer --tts and let the model decide when audio adds value, reserving auto-conversion for voice-first channels.
Transcribe inbound voice before reasoning
When users send voice notes, run speech_to_text first so the model reasons over text. This keeps prompts small and lets you log and moderate the transcript like any other message.
Keep provider credentials in the environment
The tools wrap AudioAgent, which calls external TTS/STT providers. Store provider keys as environment variables so voice features work the same across local runs, bots, and CI without editing tool code.