> ## Documentation Index
> Fetch the complete documentation index at: https://daily-ms-ws-body-url-encode.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Gladia Speech-to-Text

> GladiaSTTService streams real-time STT over Gladia's WebSocket API: 99+ languages, custom vocabulary, translation, and sentiment.

## Overview

`GladiaSTTService` provides real-time speech recognition using Gladia's WebSocket API with support for 99+ languages, custom vocabulary, translation, sentiment analysis, and advanced audio processing features for comprehensive transcription.

<CardGroup cols={2}>
  <Card title="Gladia STT API Reference" icon="code" href="https://reference-server.pipecat.ai/en/latest/api/pipecat.services.gladia.html">
    Pipecat's API methods for Gladia STT integration
  </Card>

  <Card title="Example Implementation" icon="play" href="https://github.com/pipecat-ai/pipecat/blob/main/examples/voice/voice-gladia.py">
    Complete example with interruption handling
  </Card>

  <Card title="Gladia Documentation" icon="book" href="https://docs.gladia.io/api-reference/live-flow">
    Official Gladia documentation and features
  </Card>

  <Card title="Gladia Platform" icon="microphone" href="https://www.gladia.io/">
    Access multilingual transcription and API keys
  </Card>
</CardGroup>

## Installation

To use Gladia services, install the required dependency:

```bash theme={null}
uv add "pipecat-ai[gladia]"
```

## Prerequisites

### Gladia Account Setup

Before using Gladia STT services, you need:

1. **Gladia Account**: Sign up at [Gladia](https://www.gladia.io/)
2. **API Key**: Generate an API key from your account dashboard
3. **Region Selection**: Choose your preferred region (EU-West or US-West)

### Required Environment Variables

* `GLADIA_API_KEY`: Your Gladia API key for authentication
* `GLADIA_REGION`: Your preferred region (optional, defaults to "eu-west")

## Configuration

### GladiaSTTService

<ParamField path="api_key" type="str" required>
  Gladia API key for authentication.
</ParamField>

<ParamField path="region" type="Literal['us-west', 'eu-west']" default="None">
  Region used to process audio. Defaults to `"eu-west"` when `None`.
</ParamField>

<ParamField path="url" type="str" default="https://api.gladia.io/v2/live">
  Gladia API URL for session initialization.
</ParamField>

<ParamField path="encoding" type="str" default="wav/pcm">
  Audio encoding format. Init-only -- not part of runtime-updatable settings.
</ParamField>

<ParamField path="bit_depth" type="int" default="16">
  Audio bit depth. Init-only -- not part of runtime-updatable settings.
</ParamField>

<ParamField path="channels" type="int" default="1">
  Number of audio channels. Init-only -- not part of runtime-updatable settings.
</ParamField>

<ParamField path="sample_rate" type="int" default="None">
  Audio sample rate in Hz. When `None`, uses the pipeline's configured sample
  rate.
</ParamField>

<ParamField path="model" type="str" default="None" deprecated>
  Model to use for transcription. *Deprecated in v0.0.105. Use
  `settings=GladiaSTTService.Settings(...)` instead.*
</ParamField>

<ParamField path="params" type="GladiaInputParams" default="None" deprecated>
  Additional configuration parameters. *Deprecated in v0.0.105. Use
  `settings=GladiaSTTService.Settings(...)` instead.*
</ParamField>

<ParamField path="settings" type="GladiaSTTService.Settings" default="None">
  Runtime-configurable settings for the STT service. See [Settings](#settings)
  below.
</ParamField>

<ParamField path="max_buffer_size" type="int" default="20971520">
  Maximum size of audio buffer in bytes (default 20MB).
</ParamField>

<ParamField path="should_interrupt" type="bool" default="True">
  Whether the bot should be interrupted when Gladia VAD detects user speech. See
  [User Turn
  Strategies](/api-reference/server/utilities/turn-management/user-turn-strategies#externaluserturnstrategies)
  if you pass your own `user_turn_strategies`.
</ParamField>

<ParamField path="ttfs_p99_latency" type="float" default="1.49">
  P99 latency from speech end to final transcript in seconds. Override for your
  deployment. See [stt-benchmark](https://github.com/pipecat-ai/stt-benchmark).
</ParamField>

### Settings

Runtime-configurable settings passed via the `settings` constructor argument using `GladiaSTTService.Settings(...)`. These can be updated mid-conversation with `STTUpdateSettingsFrame`. See [Service Settings](/pipecat/fundamentals/service-settings) for details.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `model` | `str` | `None` | STT model identifier. *(Inherited from base STT settings.)* |
| `language` | `Language \| str` | `None` | Language for speech recognition. *(Inherited from base STT settings.)* |
| `language_config` | `LanguageConfig` | `None` | Detailed language configuration with code switching support. |
| `custom_metadata` | `Dict[str, Any]` | `None` | Additional metadata to include with requests. |
| `endpointing` | `float` | `None` | Silence duration in seconds to mark end of speech. |
| `maximum_duration_without_endpointing` | `int` | `5` | Maximum utterance duration (seconds) without silence. |
| `pre_processing` | `PreProcessingConfig` | `None` | Audio pre-processing options (audio enhancer, speech threshold). |
| `realtime_processing` | `RealtimeProcessingConfig` | `None` | Real-time processing features (custom vocabulary, translation, NER, sentiment). |
| `messages_config` | `MessagesConfig` | `None` | WebSocket message filtering options. |
| `enable_vad` | `bool` | `False` | Enable Gladia VAD for end-of-utterance detection. Use without other VAD in the agent. |

## Usage

### Basic Setup

```python theme={null}
from pipecat.services.gladia.stt import GladiaSTTService

stt = GladiaSTTService(
    api_key=os.getenv("GLADIA_API_KEY"),
)
```

### With Language Configuration

```python theme={null}
from pipecat.services.gladia.stt import GladiaSTTService
from pipecat.services.gladia.config import LanguageConfig

stt = GladiaSTTService(
    api_key=os.getenv("GLADIA_API_KEY"),
    region="us-west",
    settings=GladiaSTTService.Settings(
        model="solaria-1",
        language_config=LanguageConfig(
            languages=["en", "es"],
            code_switching=True,
        ),
    ),
)
```

### With Real-time Processing

```python theme={null}
from pipecat.services.gladia.stt import GladiaSTTService
from pipecat.services.gladia.config import (
    RealtimeProcessingConfig,
    CustomVocabularyConfig,
    CustomVocabularyItem,
    TranslationConfig,
)

stt = GladiaSTTService(
    api_key=os.getenv("GLADIA_API_KEY"),
    settings=GladiaSTTService.Settings(
        realtime_processing=RealtimeProcessingConfig(
            custom_vocabulary=True,
            custom_vocabulary_config=CustomVocabularyConfig(
                vocabulary=[
                    CustomVocabularyItem(value="Pipecat", intensity=0.8),
                    "Gladia",
                ],
            ),
            translation=True,
            translation_config=TranslationConfig(
                target_languages=["fr", "de"],
                model="enhanced",
            ),
        ),
    ),
)
```

## Notes

* **Session-based connection**: Gladia uses a two-step connection process: first an HTTP POST to initialize a session, then a WebSocket connection to the returned session URL. The session URL and ID are managed automatically.
* **Audio buffering**: The service buffers audio data locally and sends it when connected. If the connection drops and reconnects, buffered audio is automatically re-sent to minimize transcript gaps.
* **Keepalive**: Empty audio chunks are sent periodically to keep the Gladia connection alive (keepalive interval: 5s, timeout: 20s).
* **Built-in VAD**: Set `enable_vad=True` in Settings to use Gladia's server-side VAD. The service proposes each turn boundary and automatically requests `ExternalUserTurnStrategies`, which resolve those proposals into `UserStartedSpeakingFrame` and `UserStoppedSpeakingFrame`, so you don't need to configure turn strategies manually. Pass your own `user_turn_strategies` only to override this. When using Gladia's VAD, do not enable another VAD in your pipeline.
* **Translation**: Gladia supports real-time translation to multiple target languages. Translation results are pushed as `TranslationFrame`s.

<Tip>
  The `GladiaInputParams` / `params=` pattern is deprecated as of v0.0.105. Use
  `Settings` / `settings=` instead. See the [Service Settings
  guide](/pipecat/fundamentals/service-settings) for migration details.
</Tip>

## Event Handlers

Gladia STT supports the standard [service connection events](/api-reference/server/events/service-events):

| Event | Description |
| - | - |
| `on_connected` | Connected to Gladia WebSocket |
| `on_disconnected` | Disconnected from Gladia WebSocket |

```python theme={null}
@stt.event_handler("on_connected")
async def on_connected(service):
    print("Connected to Gladia")
```