aws-polly-tts-tool

Table of Contents

• About
• Why CLI-First?
• Features
• Installation
• Configuration
• Usage
  • Basic Synthesis
  • Voice Selection
  • Engine Selection
  • SSML Support
  • Cost Tracking
  • Verbosity and Debugging
  • Shell Completion
• Library Usage
• Commands
• Known Issues
• Development
• Resources
• License

About

aws-polly-tts-tool is a comprehensive CLI tool and Python library for Amazon Polly text-to-speech synthesis. Built with a CLI-first philosophy, it provides both command-line convenience and programmatic access to AWS Polly's full feature set.

What is Amazon Polly?

Amazon Polly is AWS's fully-managed text-to-speech service that converts text into lifelike speech using deep learning. It offers 60+ voices in 30+ languages with multiple quality tiers.

Why This Tool?

• Agent-Friendly: Designed for Claude Code and AI agents with self-documenting help and structured errors
• Composable: JSON output to stdout, logs to stderr - perfect for Unix piping
• Dual-Mode: Use as CLI or import as Python library
• Production-Ready: Type-safe, tested, linted with comprehensive error handling
• Cost-Transparent: Real-time cost estimates and AWS billing integration

Why CLI-First?

This tool prioritizes CLI design to enable:

• 🤖 AI Agent Integration: Claude Code and other AI tools can use structured commands and parse outputs
• 🔄 ReAct Loops: Clear error messages help agents self-correct and retry operations
• 🔗 Composability: Standard Unix patterns (stdin/stdout/stderr) enable piping and automation
• 🧱 Building Blocks: Commands serve as reusable components for skills, MCP servers, and scripts
• 📊 Predictability: Type-safe implementation ensures consistent behavior in automated workflows

Features

Voice Engines

• ✅ Standard - Cost-effective traditional TTS ($4/1M chars)
• ✅ Neural - Natural, human-like voices ($16/1M chars)
• ✅ Generative - Most advanced, emotionally engaged ($30/1M chars)
• ✅ Long-form - Optimized for audiobooks ($100/1M chars)

Voice Selection

• 📢 60+ voices across 30+ languages
• 🔍 Dynamic fetching from Polly API (always up-to-date)
• 🎚️ Filter by engine, language, gender
• 🌍 Multiple accents and speaking styles

Output Options

• 🎵 mp3 - General purpose (default)
• 🎶 ogg_vorbis - Open format for web
• 🎙️ pcm - Raw audio, lowest latency

Advanced Features

• 📝 Full SSML support (prosody, breaks, emphasis, phonemes)
• 💰 Dual cost tracking (estimates + AWS Cost Explorer)
• 📊 Billing queries with engine breakdown
• 🔐 AWS environment variable authentication
• 📤 Stdin support for piping

Installation

Prerequisites

• Python 3.12+ (Python 3.13+ has pydub compatibility issues - see Known Issues)
• uv package manager (recommended)
• AWS credentials configured
• ffmpeg (for audio playback - not required for file output)

Note: For a detailed explanation of how the TTS pipeline works and why these dependencies are needed, see TTS Pipeline Architecture

Install from Source

# Clone repository
git clone https://github.com/dnvriend/aws-polly-tts-tool.git
cd aws-polly-tts-tool

# Install with uv (Python 3.12)
uv tool install . --python 3.12

# Verify installation
aws-polly-tts-tool --version

Install with mise (Development)

cd aws-polly-tts-tool
mise use python@3.12
uv sync
uv tool install .

Configuration

AWS Credentials

Configure AWS credentials using any of these methods:

# Method 1: AWS CLI configuration
aws configure

# Method 2: Environment variables
export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"
export AWS_DEFAULT_REGION="us-east-1"