skill-aws-transcribe-tool

What this skill does

# When to use

- When you need to transcribe audio files to text using Amazon Transcribe
- When you need multi-language transcription support (60+ languages)
- When you want a simple CLI interface for AWS Transcribe without AWS CLI complexity

# aws-transcribe-tool Skill

## Purpose

This skill provides access to the `aws-transcribe-tool` CLI - a command-line utility for transcribing audio files to text using Amazon Transcribe service. It handles S3 uploads, transcription job management, and transcript download.

## When to Use This Skill

**Use this skill when:**
- You need to transcribe audio files (MP3, MP4, WAV, FLAC, Ogg, WebM, AMR)
- You need multi-language transcription support
- You want automated S3 cleanup after transcription
- You need AWS profile-based authentication

**Do NOT use this skill for:**
- Real-time transcription (this is batch-only)
- Transcription without AWS credentials
- Tasks unrelated to audio transcription

## CLI Tool: aws-transcribe-tool

A CLI tool that provides a simple interface to Amazon Transcribe service. Upload audio to S3, start transcription jobs, and download results.

### Installation

```bash
# Clone and install
git clone https://github.com/dnvriend/aws-transcribe-tool.git
cd aws-transcribe-tool
uv tool install .
```

### Prerequisites

- Python 3.14+
- [uv](https://github.com/astral-sh/uv) package manager
- AWS credentials configured
- An existing S3 bucket for audio upload

### Quick Start

```bash
# Basic transcription (English)
aws-transcribe-tool transcribe interview.mp3 transcript.txt my-s3-bucket

# Dutch audio transcription
aws-transcribe-tool transcribe audio.wav output.txt my-bucket -l nl-NL

# List all supported languages
aws-transcribe-tool list-languages
```

## Progressive Disclosure

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

### transcribe - Transcribe Audio to Text

Transcribes audio files using Amazon Transcribe service. Handles S3 upload, transcription job, and transcript download.

**Usage:**
```bash
aws-transcribe-tool transcribe AUDIO_FILE OUTPUT_FILE S3_BUCKET [OPTIONS]
```

**Arguments:**
- `AUDIO_FILE`: Path to audio file (MP3, MP4, WAV, FLAC, Ogg, WebM, AMR)
- `OUTPUT_FILE`: Path where transcript will be saved
- `S3_BUCKET`: S3 bucket name for temporary audio storage

**Options:**
- `--language CODE` / `-l CODE`: Language code (default: en-US)
- `--profile NAME` / `-p NAME`: AWS profile name
- `--region NAME` / `-r NAME`: AWS region
- `--cleanup` / `-c`: Delete S3 file after successful transcription
- `--s3-key KEY`: Custom S3 key path
- `--job-name NAME` / `-j NAME`: Custom transcription job name
- `-v/-vv/-vvv`: Verbosity (INFO/DEBUG/TRACE)

**Examples:**
```bash
# Basic transcription
aws-transcribe-tool transcribe meeting.mp3 meeting.txt my-audio-bucket

# Dutch audio with verbose output
aws-transcribe-tool transcribe audio.wav out.txt my-bucket -l nl-NL -v

# Use specific AWS profile and cleanup S3 after
aws-transcribe-tool transcribe file.mp3 out.txt bucket -p work -c

# Custom S3 key path
aws-transcribe-tool transcribe voice.flac text.txt bucket --s3-key podcasts/voice.flac
```

**Output:**
Saves transcript to the specified output file and displays a preview.

---

### list-languages - List Supported Languages

Displays all supported language codes for Amazon Transcribe in a formatted table.

**Usage:**
```bash
aws-transcribe-tool list-languages
```

**Examples:**
```bash
aws-transcribe-tool list-languages
```

**Output:**
```
CODE       LANGUAGE
-------    --------------------------------
en-US      English (United States) (default)
nl-NL      Dutch (Netherlands)
de-DE      German (Germany)
...
```

---

### completion - Generate Shell Completion

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

**Usage:**
```bash
aws-transcribe-tool completion generate SHELL
```

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

**Examples:**
```bash
# Bash - add to ~/.bashrc
eval "$(aws-transcribe-tool completion generate bash)"

# Zsh - add to ~/.zshrc
eval "$(aws-transcribe-tool completion generate zsh)"

# Fish - save to completions dir
aws-transcribe-tool completion generate fish > ~/.config/fish/completions/aws-transcribe-tool.fish
```

**Output:**
Shell script content for the specified shell.

</details>

<details>
<summary><strong>⚙️  Advanced Features (Click to expand)</strong></summary>

### Multi-Level Verbosity Logging

Control logging detail with progressive verbosity levels. All logs output to stderr, keeping stdout clean for data piping.

**Logging Levels:**

| Flag | Level | Output | Use Case |
|------|-------|--------|----------|
| (none) | WARNING | Errors and warnings only | Production, quiet mode |
| `-v` | INFO | + High-level operations | Normal debugging |
| `-vv` | DEBUG | + Detailed info, full tracebacks | Development, troubleshooting |
| `-vvv` | TRACE | + Library internals | Deep debugging |

**Examples:**
```bash
# INFO level - see operations
aws-transcribe-tool transcribe audio.mp3 out.txt bucket -v

# DEBUG level - see detailed info
aws-transcribe-tool transcribe audio.mp3 out.txt bucket -vv

# TRACE level - see all internals
aws-transcribe-tool transcribe audio.mp3 out.txt bucket -vvv
```

---

### Shell Completion

Native shell completion for bash, zsh, and fish.

**Installation:**
```bash
# Bash - add to ~/.bashrc
eval "$(aws-transcribe-tool completion generate bash)"

# Zsh - add to ~/.zshrc
eval "$(aws-transcribe-tool completion generate zsh)"

# Fish - save to completions (auto-loaded)
mkdir -p ~/.config/fish/completions
aws-transcribe-tool completion generate fish > ~/.config/fish/completions/aws-transcribe-tool.fish
```

---

### OpenTelemetry Observability

The CLI supports OpenTelemetry for distributed tracing, metrics, and logs. Designed for integration with Grafana stack (Alloy, Tempo, Prometheus).

**Quick Start:**
```bash
# Enable telemetry via CLI flag
aws-transcribe-tool --telemetry transcribe audio.mp3 out.txt bucket

# Or via environment variable
export OTEL_ENABLED=true
aws-transcribe-tool transcribe audio.mp3 out.txt bucket
```

**Configuration:**

| Variable | Default | Description |
|----------|---------|-------------|
| `OTEL_ENABLED` | `false` | Enable telemetry |
| `OTEL_SERVICE_NAME` | `aws-transcribe-tool` | Service name in traces |
| `OTEL_EXPORTER_TYPE` | `console` | `console` or `otlp` |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4317` | OTLP endpoint |

---

### AWS Profile and Region Management

Use different AWS profiles and regions without modifying global configuration.

**Examples:**
```bash
# Use specific AWS profile
aws-transcribe-tool transcribe audio.mp3 out.txt bucket -p production

# Use specific region
aws-transcribe-tool transcribe audio.mp3 out.txt bucket -r eu-west-1

# Combine profile and region
aws-transcribe-tool transcribe audio.mp3 out.txt bucket -p work -r us-west-2
```

---

### S3 Cleanup

Automatically delete uploaded audio files from S3 after successful transcription.

**Examples:**
```bash
# Cleanup after successful transcription
aws-transcribe-tool transcribe audio.mp3 out.txt bucket -c
```

</details>

<details>
<summary><strong>🔧 Troubleshooting (Click to expand)</strong></summary>

### Common Issues

**Issue: Command not found**
```bash
# Verify installation
aws-transcribe-tool --version

# Reinstall if needed
cd aws-transcribe-tool
uv tool install . --reinstall
```

**Issue: Unsupported language code**
```bash
# List supported languages
aws-transcribe-tool list-languages

# Example output includes: en-US, nl-NL, de-DE, fr-FR, es-ES, etc.
```

**Issue: AWS credentials not configured**
```bash
# Verify AWS credentials
aws sts get-caller-identity

# Configure credentials
aws configure --profile my-profile

# Use profile with transcribe command
aws-transcribe-tool transcribe audio.mp3 out.txt bucket -p my-profile
```

**Issue: S3 bucket not accessible**
```bash
# Verify bucket exists and is accessible
aws s3 ls s3://my-bucket

# Check bu