skill-aws-polly-tts-tool

What this skill does

# When to use
- Converting text to lifelike speech using AWS Polly
- Working with multiple voice engines and output formats
- Tracking TTS costs and AWS billing
- Implementing TTS in automation pipelines

# AWS Polly TTS Tool Skill

## Purpose

Professional AWS Polly text-to-speech CLI and library with agent-friendly design, enabling conversion of text to lifelike speech using Amazon Polly's deep learning technology. Supports 60+ voices in 30+ languages across four quality tiers with comprehensive cost tracking.

## When to Use This Skill

**Use this skill when:**
- You need to convert text to speech using AWS Polly
- You want to explore available voices and engines
- You need to track TTS costs or query billing data
- You're building automation with TTS capabilities
- You need SSML support for advanced speech control
- You want to work with different audio formats

**Do NOT use this skill for:**
- Non-AWS TTS services (Google, Azure, etc.)
- Real-time streaming TTS (use AWS SDK directly)
- Voice cloning or training (Polly doesn't support this)

## CLI Tool: aws-polly-tts-tool

Professional AWS Polly TTS CLI and Python library designed with CLI-first philosophy for both command-line and programmatic use.

### Installation

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

### Prerequisites

- **Python 3.12+** (Python 3.13+ has pydub compatibility issues)
- AWS credentials configured
- **ffmpeg** for audio playback (not required for file output)
- IAM permissions: `polly:DescribeVoices`, `polly:SynthesizeSpeech`, `ce:GetCostAndUsage`

### Quick Start

```bash
# Play text with default voice
aws-polly-tts-tool synthesize "Hello world"

# Save to file
aws-polly-tts-tool synthesize "Hello world" --output speech.mp3

# List available voices
aws-polly-tts-tool list-voices

# Show pricing
aws-polly-tts-tool pricing
```

## Progressive Disclosure

<details>
<summary><strong>📖 Core Commands (Click to expand)</strong></summary>

### synthesize - Convert Text to Speech

Main TTS command with full feature support including multiple engines, voices, and output formats.

**Usage:**
```bash
aws-polly-tts-tool synthesize "TEXT" [OPTIONS]
```

**Arguments:**
- `TEXT`: Text to synthesize (required, or use `--stdin`)
- `--stdin` / `-s`: Read text from stdin (enables piping)
- `--voice TEXT`: Voice ID (default: Joanna)
- `--output PATH` / `-o PATH`: Save audio to file instead of playing
- `--format TEXT` / `-f TEXT`: Output format (mp3, ogg_vorbis, pcm) - default: mp3
- `--engine TEXT` / `-e TEXT`: Voice engine (standard, neural, generative, long-form) - default: neural
- `--ssml`: Treat input as SSML markup
- `--show-cost`: Display character count and cost estimate
- `--region TEXT` / `-r TEXT`: AWS region override
- `-V/-VV/-VVV`: Verbosity (INFO/DEBUG/TRACE with AWS SDK details)

**Examples:**
```bash
# Basic synthesis with default voice (Joanna, neural)
aws-polly-tts-tool synthesize "Hello world"

# Use different voice and engine
aws-polly-tts-tool synthesize "Hello" --voice Matthew --engine generative

# Save to file with specific format
aws-polly-tts-tool synthesize "Hello world" --output speech.mp3 --format mp3

# Read from stdin
echo "Hello world" | aws-polly-tts-tool synthesize --stdin

# Read from file
cat article.txt | aws-polly-tts-tool synthesize --stdin --output article.mp3

# Use SSML for advanced control
aws-polly-tts-tool synthesize '<speak>Hello <break time="500ms"/> world</speak>' --ssml

# Show cost estimate
aws-polly-tts-tool synthesize "Hello world" --show-cost

# Multiple options combined with debugging
cat article.txt | aws-polly-tts-tool synthesize --stdin \
    --voice Joanna \
    --engine neural \
    --output article.mp3 \
    --show-cost \
    -VV
```

**Output:**
- Audio played through speakers (default) or saved to file
- Character count and cost estimate (with `--show-cost`)
- Logs to stderr, keeping stdout clean for piping

---

### list-voices - Discover Available Voices

List and filter AWS Polly voices by engine, language, and gender.

**Usage:**
```bash
aws-polly-tts-tool list-voices [OPTIONS]
```

**Options:**
- `--engine TEXT` / `-e TEXT`: Filter by engine (standard, neural, generative, long-form)
- `--language TEXT` / `-l TEXT`: Filter by language code (e.g., en-US, es-ES, fr-FR)
- `--gender TEXT` / `-g TEXT`: Filter by gender (Female, Male)
- `--region TEXT` / `-r TEXT`: AWS region override
- `-V/-VV/-VVV`: Verbosity levels

**Examples:**
```bash
# List all voices
aws-polly-tts-tool list-voices

# Filter by engine
aws-polly-tts-tool list-voices --engine neural

# Filter by language
aws-polly-tts-tool list-voices --language en-US

# Combine filters
aws-polly-tts-tool list-voices --engine neural --language en --gender Female

# Use with grep for searching
aws-polly-tts-tool list-voices | grep British
aws-polly-tts-tool list-voices --engine generative | grep Spanish
```

**Output:**
Table with Voice, Gender, Language, Engines (supported), and Description columns. Dynamically fetched from Polly API (always up-to-date).

---

### list-engines - Display Voice Engines

Show all available voice engines with technology, pricing, and best use cases.

**Usage:**
```bash
aws-polly-tts-tool list-engines
```

**Examples:**
```bash
# Show all engines with details
aws-polly-tts-tool list-engines
```

**Output:**
Table showing:
- **Standard** ($4/1M chars) - Traditional concatenative TTS, 3000 char limit
- **Neural** ($16/1M chars) - Natural human-like voices, 3000 char limit
- **Generative** ($30/1M chars) - Most advanced emotionally engaged, 3000 char limit
- **Long-form** ($100/1M chars) - Optimized for audiobooks, 100,000 char limit

---

### billing - Query AWS Costs

Query AWS Cost Explorer for actual Polly usage costs with engine breakdown.

**Usage:**
```bash
aws-polly-tts-tool billing [OPTIONS]
```

**Options:**
- `--days INT` / `-d INT`: Number of days to query (default: 30)
- `--start-date TEXT`: Custom start date (YYYY-MM-DD)
- `--end-date TEXT`: Custom end date (YYYY-MM-DD)
- `--region TEXT` / `-r TEXT`: AWS region for Cost Explorer
- `-V/-VV/-VVV`: Verbosity levels

**Examples:**
```bash
# Last 30 days of Polly costs
aws-polly-tts-tool billing

# Last 7 days
aws-polly-tts-tool billing --days 7

# Custom date range
aws-polly-tts-tool billing --start-date 2025-01-01 --end-date 2025-01-31

# With verbose output
aws-polly-tts-tool billing --days 7 -V
```

**Output:**
Total cost and breakdown by engine (Standard, Neural, Generative, Long-form) in USD.

**Note:** Requires IAM permission `ce:GetCostAndUsage`

---

### pricing - Show Pricing Information

Display static pricing information for all Polly engines with cost examples.

**Usage:**
```bash
aws-polly-tts-tool pricing
```

**Examples:**
```bash
# Show pricing table and examples
aws-polly-tts-tool pricing
```

**Output:**
Comprehensive pricing with:
- Cost per 1M characters for each engine
- Technology type and quality level
- Character limits per request
- Concurrent request limits
- Free tier information
- Best use cases
- Cost examples (1,000 words, audiobooks)

---

### info - Tool Configuration

Display AWS credentials status and tool configuration.

**Usage:**
```bash
aws-polly-tts-tool info
```

**Examples:**
```bash
# Verify AWS authentication and show config
aws-polly-tts-tool info
```

**Output:**
- AWS credential status (Valid/Invalid)
- Account ID, User ID, ARN
- Available engines
- Output formats
- Useful command examples

---

### completion - Shell Completion

Generate shell completion scripts for bash, zsh, or fish.

**Usage:**
```bash
aws-polly-tts-tool completion [bash|zsh|fish]
```

**Arguments:**
- `SHELL`: Shell type (bash, zsh, or fish) - required

**Examples:**
```bash
# Generate bash completion
aws-polly-tts-tool completion bash

# Install for bash (add to ~/.bashrc)
eval "$(aw