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

# AWS Transcribe

> Speech-to-text service implementation using Amazon Transcribe's real-time transcription API

## Overview

`AWSTranscribeSTTService` provides real-time speech recognition using Amazon Transcribe's WebSocket streaming API with support for interim results, multiple languages, and configurable audio processing parameters for enterprise-grade transcription.

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

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

  <Card title="AWS Transcribe Documentation" icon="book" href="https://docs.aws.amazon.com/transcribe/latest/dg/streaming.html">
    Official AWS Transcribe documentation and features
  </Card>

  <Card title="AWS Console" icon="microphone" href="https://console.aws.amazon.com/transcribe/">
    Access AWS Transcribe services and IAM setup
  </Card>
</CardGroup>

## Installation

To use AWS Transcribe services, install the required dependency:

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

## Prerequisites

### AWS Account Setup

Before using AWS Transcribe STT services, you need:

1. **AWS Account**: Sign up at [AWS Console](https://console.aws.amazon.com/)
2. **IAM User**: Create an IAM user with Amazon Transcribe permissions
3. **Credentials**: Set up AWS access keys and region configuration

### Required Environment Variables

* `AWS_ACCESS_KEY_ID`: Your AWS access key ID
* `AWS_SECRET_ACCESS_KEY`: Your AWS secret access key
* `AWS_SESSION_TOKEN`: Session token (if using temporary credentials)
* `AWS_REGION`: AWS region (defaults to "us-east-1")

## Configuration

<ParamField path="api_key" type="str" default="None">
  AWS secret access key. If `None`, uses `AWS_SECRET_ACCESS_KEY` environment
  variable.
</ParamField>

<ParamField path="aws_access_key_id" type="str" default="None">
  AWS access key ID. If `None`, uses `AWS_ACCESS_KEY_ID` environment variable.
</ParamField>

<ParamField path="aws_session_token" type="str" default="None">
  AWS session token for temporary credentials. If `None`, uses
  `AWS_SESSION_TOKEN` environment variable.
</ParamField>

<ParamField path="region" type="str" default="None">
  AWS region for the service. If `None`, uses `AWS_REGION` environment variable
  (defaults to `"us-east-1"`).
</ParamField>

<ParamField path="sample_rate" type="int" default="None">
  Audio sample rate in Hz. When `None`, uses the pipeline's configured sample
  rate. AWS Transcribe only supports `8000` or `16000` Hz; other values are
  clamped to `16000` Hz at connect time.
</ParamField>

<ParamField path="language" type="Language" default="Language.EN" deprecated>
  Language for transcription. Supports a wide range of languages including
  English, Spanish, French, German, and many more. See [AWS Transcribe supported
  languages](https://docs.aws.amazon.com/transcribe/latest/dg/supported-languages.html).
  *Deprecated in v0.0.105. Use `settings=AWSTranscribeSTTService.Settings(...)`
  instead.*
</ParamField>

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

<ParamField path="ttfs_p99_latency" type="float" default="AWS_TRANSCRIBE_TTFS_P99">
  P99 latency from speech end to final transcript in seconds. Override for your
  deployment.
</ParamField>

### Settings

Runtime-configurable settings passed via the `settings` constructor argument using `AWSTranscribeSTTService.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` | `Language.EN` | Language for transcription. *(Inherited from base STT settings.)* |

## Usage

### Basic Setup

```python theme={null}
from pipecat.services.aws.stt import AWSTranscribeSTTService

stt = AWSTranscribeSTTService(
    api_key=os.getenv("AWS_SECRET_ACCESS_KEY"),
    aws_access_key_id=os.getenv("AWS_ACCESS_KEY_ID"),
    region=os.getenv("AWS_REGION", "us-east-1"),
)
```

### With Custom Language and Sample Rate

```python theme={null}
from pipecat.services.aws.stt import AWSTranscribeSTTService
from pipecat.transcriptions.language import Language

stt = AWSTranscribeSTTService(
    api_key=os.getenv("AWS_SECRET_ACCESS_KEY"),
    aws_access_key_id=os.getenv("AWS_ACCESS_KEY_ID"),
    region="eu-west-1",
    sample_rate=8000,
    settings=AWSTranscribeSTTService.Settings(
        language=Language.ES,
    ),
)
```

## Notes

* **Supported sample rates**: AWS Transcribe only supports `8000` Hz and `16000` Hz. If a different rate is provided, the service automatically falls back to `16000` Hz with a warning.
* **Pre-signed URL authentication**: The service uses pre-signed URLs for WebSocket authentication rather than passing credentials directly, following AWS best practices.
* **Partial results stabilization**: Enabled by default with `"high"` stability, which reduces changes to interim transcripts at the cost of slightly higher latency.

<Tip>
  The `InputParams` / `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

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

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

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