> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Audio Tools

> Text-to-Speech (TTS) and Speech-to-Text (STT) tools for agents

> [!NOTE]
>
> For voice-note transcription in gateway bots (Telegram/Slack/WhatsApp), see [Voice Notes](https://praison.ai/docs/features/gateway-voice-notes.md) — the bot layer already wires `stt_tool` for you.

Enable your agents to speak and listen with TTS and STT tools.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Text-to-Speech"
        T[📝 Text] --> TTS[🔊 TTS Tool]
        TTS --> A[🎵 Audio File]
    end
    
    subgraph "Speech-to-Text"
        A2[🎵 Audio] --> STT[🎤 STT Tool]
        STT --> T2[📝 Text]
    end
    
    classDef agent fill:#8B0000,color:#fff
    classDef tool fill:#189AB4,color:#fff
    
    class A,T2 agent
    class T,A2,TTS,STT tool
```

***

## Quick Start

**1. Bot CLI**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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
```

**2. Python**

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant Agent
    participant TTS as TTS Tool
    participant Audio as AudioAgent
    participant API as OpenAI/LiteLLM
    
    Agent->>TTS: tts("Hello world")
    TTS->>Audio: speech(text)
    Audio->>API: Generate audio
    API-->>Audio: Audio stream
    Audio-->>TTS: Save to file
    TTS-->>Agent: MEDIA:/path/to/audio.mp3
```

### Usage

```python Direct Function theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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.mp3
```

```python As Agent Tool theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from 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.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant Agent
    participant STT as STT Tool
    participant Audio as AudioAgent
    participant API as OpenAI/LiteLLM
    
    Agent->>STT: stt("audio.mp3")
    STT->>Audio: transcribe(file)
    Audio->>API: Whisper API
    API-->>Audio: Transcription
    Audio-->>STT: Text result
    STT-->>Agent: "Hello world"
```

### Usage

```python Direct Function theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai.tools.audio import stt_tool

result = stt_tool("recording.mp3", language="en")

if result["success"]:
    print(result["text"])  # Transcribed text
```

```python As Agent Tool theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from 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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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-tts
```

***

## Supported Providers

Audio tools use the core `AudioAgent` which supports multiple providers via LiteLLM:

> [accordion] 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` | Google |

> [accordion] 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

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    subgraph "Wrapper Layer (praisonai)"
        TTS[tts_tool]
        STT[stt_tool]
        CLI[Bot CLI --tts/--stt]
    end
    
    subgraph "Core SDK (praisonaiagents)"
        AA[AudioAgent]
    end
    
    subgraph "External"
        LL[LiteLLM]
        API[OpenAI/Azure/etc]
    end
    
    CLI --> TTS
    CLI --> STT
    TTS --> AA
    STT --> AA
    AA --> LL
    LL --> API
    
    classDef wrapper fill:#189AB4,color:#fff
    classDef core fill:#8B0000,color:#fff
    classDef external fill:#666,color:#fff
    
    class TTS,STT,CLI wrapper
    class AA core
    class LL,API external
```

> [!NOTE]
>
> Audio tools are in the **wrapper layer** (`praisonai`), not the core SDK. They wrap the core `AudioAgent` for easy use with agents and bots.

***

## Best Practices

> [accordion] 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.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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.

***

## Related

> [card] [Bot CLI](https://praison.ai/docs/cli/bot.md)
>
> Full bot CLI reference

> [card] [AudioAgent](https://praison.ai/docs/sdk/reference/praisonaiagents/classes/AudioAgent.md)
>
> Core AudioAgent class

> [card] [Voice Notes](https://praison.ai/docs/features/gateway-voice-notes.md)
>
> Automatic transcription of inbound voice messages in gateway bots


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.