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

# Meta Speech-to-Text

> Streaming STT with MetaSTTService: Muse Voice realtime transcription with 25 language support and three segmentation modes.

## Overview

`MetaSTTService` provides real-time speech-to-text using Meta's Muse Voice WebSocket API. The service streams audio to Meta's realtime transcription endpoint and emits interim and final transcription frames.

The API key is sent in the handshake frame rather than an HTTP header, and the session's configuration is fixed once the server accepts the handshake, so a settings change triggers a reconnection.

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

  <Card title="Voice Example" icon="play" href="https://github.com/pipecat-ai/pipecat/blob/main/examples/voice/voice-meta.py">
    Complete voice bot example with Meta STT
  </Card>

  <Card title="Transcription Example" icon="play" href="https://github.com/pipecat-ai/pipecat/blob/main/examples/transcription/transcription-meta.py">
    Transcription-only example with Meta STT
  </Card>

  <Card title="Meta Voice API Documentation" icon="book" href="https://dev.meta.ai/docs/api-reference/voice/realtime">
    Official Meta Muse Voice API documentation
  </Card>
</CardGroup>

## Installation

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

## Prerequisites

Before using `MetaSTTService`, you need:

1. **Meta Account**: Access to the Meta Model API
2. **API Key**: A Meta Model API key for authentication

### Required Environment Variables

* `META_API_KEY`: Your Meta Model API key

## Configuration

<ParamField path="api_key" type="str" required>
  Meta Model API key, sent as a Bearer token in the handshake.
</ParamField>

<ParamField path="url" type="str" default="wss://api.meta.ai/v1/asr/realtime">
  WebSocket endpoint URL for the Meta STT API.
</ParamField>

<ParamField path="sample_rate" type="int" default="None">
  Audio sample rate in Hz. When `None`, uses the pipeline's configured sample
  rate. Audio at anything other than 24000 is resampled to 16000, the only other
  rate the API accepts.
</ParamField>

<ParamField path="settings" type="MetaSTTService.Settings" default="None">
  Runtime-updatable settings overriding defaults. See [Settings](#settings)
  below.
</ParamField>

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

## Settings

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

| Parameter             | Type              | Default                       | Description                                                                                                                                                  |
| --------------------- | ----------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `model`               | `str`             | `"muse-voice-transcribe-1.0"` | Meta model to use. *(Inherited from base STT settings.)*                                                                                                     |
| `language`            | `Language \| str` | `Language.EN`                 | Single language to bias recognition toward. Replaced by `language_bias` when set. Leave both unset for auto-detection. *(Inherited from base STT settings.)* |
| `language_bias`       | `list[Language]`  | `None`                        | Languages to bias recognition toward, for speech that switches between them. Replaces the single `language` bias when set.                                   |
| `mode`                | `str`             | `"ENDPOINTING"`               | Segmentation mode: `"ENDPOINTING"` for model-driven turn boundaries, `"PUSH_TO_TALK"` for client-driven turns, or `"DIARIZATION"` for speaker attribution.   |
| `keywords`            | `list[str]`       | `None`                        | Terms to bias recognition toward. Biasing raises the odds a term is recognized but doesn't guarantee its spelling.                                           |
| `emit_audio_progress` | `bool`            | `False`                       | Whether the server reports progress for every processed audio chunk.                                                                                         |
| `zdr_override`        | `bool \| None`    | `None`                        | Forces metadata-only logging when `True`, or allows content retention when `False`. Leave unset to use the account's setting.                                |

### Supported Languages

Meta STT supports 25 languages for recognition biasing:

Arabic, Bengali, German, English, Spanish, French, Hebrew, Hindi, Indonesian, Italian, Japanese, Kannada, Korean, Marathi, Malay, Dutch, Polish, Portuguese, Tamil, Telugu, Thai, Tagalog, Turkish, Vietnamese, Mandarin Chinese

## Usage

### Basic Setup

```python theme={null}
from pipecat.services.meta.stt import MetaSTTService
import os

stt = MetaSTTService(
    api_key=os.getenv("META_API_KEY"),
)
```

### With Custom Settings

```python theme={null}
from pipecat.services.meta.stt import MetaSTTService
from pipecat.transcriptions.language import Language
import os

stt = MetaSTTService(
    api_key=os.getenv("META_API_KEY"),
    settings=MetaSTTService.Settings(
        language=Language.ES,
        keywords=["Pipecat", "AI"],
    ),
)
```

### Multilingual Mode

For speech that switches between languages, use `language_bias`:

```python theme={null}
from pipecat.services.meta.stt import MetaSTTService
from pipecat.transcriptions.language import Language
import os

stt = MetaSTTService(
    api_key=os.getenv("META_API_KEY"),
    settings=MetaSTTService.Settings(
        language_bias=[Language.EN, Language.ES, Language.FR],
    ),
)
```

### Push-to-Talk Mode

For client-controlled turn boundaries:

```python theme={null}
from pipecat.services.meta.stt import MetaSTTService
import os

stt = MetaSTTService(
    api_key=os.getenv("META_API_KEY"),
    settings=MetaSTTService.Settings(
        mode="PUSH_TO_TALK",
    ),
)
```

## Notes

* **Endpointing modes**: In the default `ENDPOINTING` mode, the server marks turn boundaries itself, emitting `speechStart`, cumulative partial transcripts, `speechEnd`, and finally `speechComplete` with post-processed text. Those boundaries segment transcripts only — Pipecat's own VAD and turn strategies still decide when the user's turn ends. In `PUSH_TO_TALK` mode, the client controls turn boundaries. In `DIARIZATION` mode, turns are attributed to speakers.
* **Audio resampling**: The API accepts only 16 kHz or 24 kHz audio. Audio at 24 kHz is sent unchanged; any other sample rate is resampled to 16 kHz automatically.
* **Settings updates**: Any settings change triggers a reconnection because Meta fixes the session's configuration when it accepts the handshake.
* **Session duration**: Sessions are capped at 60 minutes. The server closes the socket when a session reaches that limit, and the base class reconnects into a fresh one.
* **Language biasing**: Meta biases recognition on English language names (e.g., `"English"`, `"Mandarin Chinese"`) rather than codes. An unmapped or unrecognized language degrades to auto-detection.

## Event Handlers

Supports the standard [service connection events](/api-reference/server/events/service-events) (`on_connected`, `on_disconnected`, `on_connection_error`).

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

@stt.event_handler("on_disconnected")
async def on_disconnected(service):
    print(f"Disconnected from Meta STT")
```