> ## 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](/docs/features/gateway-voice-notes) — the bot layer already wires `stt_tool` for you.
</Note>

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

<Steps>
  <Step title="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
    ```
  </Step>

  <Step title="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")
    ```
  </Step>
</Steps>

***

## 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

<CodeGroup>
  ```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")
  ```
</CodeGroup>

### 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

<CodeGroup>
  ```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")
  ```
</CodeGroup>

### 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:

<AccordionGroup>
  <Accordion title="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>

  <Accordion title="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         |
  </Accordion>
</AccordionGroup>

***

## 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.
</Note>

***

## Best Practices

<AccordionGroup>
  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Bot CLI" icon="robot" href="/docs/cli/bot">
    Full bot CLI reference
  </Card>

  <Card title="AudioAgent" icon="volume-high" href="/docs/sdk/reference/praisonaiagents/classes/AudioAgent">
    Core AudioAgent class
  </Card>

  <Card title="Voice Notes" icon="microphone" href="/docs/features/gateway-voice-notes">
    Automatic transcription of inbound voice messages in gateway bots
  </Card>
</CardGroup>