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

> Text-to-speech service using Amazon Polly

## Overview

`AWSPollyTTSService` provides high-quality text-to-speech synthesis through Amazon Polly with support for standard, neural, and generative engines. The service offers extensive language support, SSML features, and voice customization options including prosody controls for pitch, rate, and volume.

<CardGroup cols={2}>
  <Card title="AWS Polly API Reference" icon="code" href="https://reference-server.pipecat.ai/en/latest/api/pipecat.services.aws.tts.html">
    Pipecat's API methods for AWS Polly 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 generative engine
  </Card>

  <Card title="AWS Polly Documentation" icon="book" href="https://docs.aws.amazon.com/polly/">
    Official AWS Polly documentation and features
  </Card>

  <Card title="Voice Samples" icon="microphone" href="https://docs.aws.amazon.com/polly/latest/dg/voicelist.html">
    Browse available voices and languages
  </Card>
</CardGroup>

## Installation

To use AWS Polly services, install the required dependencies:

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

## Prerequisites

### AWS Account Setup

Before using AWS Polly TTS services, you need:

1. **AWS Account**: Sign up at [AWS Console](https://aws.amazon.com/)
2. **IAM User**: Create an IAM user with Polly permissions
3. **Access Keys**: Generate access key ID and secret access key
4. **Voice Selection**: Choose from available voices in the [voice list](https://docs.aws.amazon.com/polly/latest/dg/voicelist.html)

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

### AWSPollyTTSService

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

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

<ParamField path="aws_session_token" type="str" default="None">
  AWS session token for temporary credentials.
</ParamField>

<ParamField path="region" type="str" default="None">
  AWS region for Polly service. Defaults to `us-east-1` if not set via
  environment variable.
</ParamField>

<ParamField path="voice_id" type="str" default="Joanna" deprecated>
  Voice ID to use for synthesis. *Deprecated in v0.0.105. Use
  `settings=AWSPollyTTSService.Settings(voice=...)` instead.*
</ParamField>

<ParamField path="sample_rate" type="int" default="None">
  Output audio sample rate in Hz. When `None`, uses the pipeline's configured
  sample rate. AWS Polly internally synthesizes at 16kHz and resamples to the
  target rate.
</ParamField>

<ParamField path="params" type="InputParams" default="None" deprecated>
  *Deprecated in v0.0.105. Use `settings=AWSPollyTTSService.Settings(...)`
  instead.*
</ParamField>

<ParamField path="settings" type="AWSPollyTTSService.Settings" default="None">
  Runtime-configurable settings. See [Settings](#settings) below.
</ParamField>

### Settings

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

| Parameter       | Type              | Default     | Description                               |
| --------------- | ----------------- | ----------- | ----------------------------------------- |
| `model`         | `str`             | `None`      | Model identifier. *(Inherited.)*          |
| `voice`         | `str`             | `None`      | Voice identifier. *(Inherited.)*          |
| `language`      | `Language \| str` | `None`      | Language for synthesis. *(Inherited.)*    |
| `engine`        | `str`             | `NOT_GIVEN` | Engine type (e.g., "neural", "standard"). |
| `pitch`         | `str`             | `NOT_GIVEN` | Pitch adjustment for SSML.                |
| `rate`          | `str`             | `NOT_GIVEN` | Speaking rate for SSML.                   |
| `volume`        | `str`             | `NOT_GIVEN` | Volume for SSML.                          |
| `lexicon_names` | `List[str]`       | `NOT_GIVEN` | List of lexicon names for pronunciation.  |

## Usage

### Basic Setup

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

tts = AWSPollyTTSService(
    settings=AWSPollyTTSService.Settings(
        voice="Joanna",
    ),
)
```

### With Voice Customization

```python theme={null}
from pipecat.transcriptions.language import Language

tts = AWSPollyTTSService(
    api_key=os.getenv("AWS_SECRET_ACCESS_KEY"),
    aws_access_key_id=os.getenv("AWS_ACCESS_KEY_ID"),
    region="us-east-1",
    settings=AWSPollyTTSService.Settings(
        voice="Matthew",
        engine="neural",
        language=Language.EN_US,
        rate="110%",
        volume="loud",
    ),
)
```

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

## Notes

* **Engine selection**: AWS Polly supports `"standard"`, `"neural"`, and `"generative"` engines. Not all voices support all engines. Check the [AWS voice list](https://docs.aws.amazon.com/polly/latest/dg/voicelist.html) for compatibility.
* **Pitch control**: The `pitch` parameter only works with the `"standard"` engine. Neural and generative engines ignore it.
* **Audio resampling**: Polly synthesizes PCM at 16kHz internally. The service automatically resamples to match your pipeline's sample rate.