skill-aws-transcribe-tool

name	skill-aws-transcribe-tool
description	Transcribe audio using AWS Transcribe

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

# 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 package manager
• AWS credentials configured
• An existing S3 bucket for audio upload

Quick Start

# 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

📖 Core Commands (Click to expand)

transcribe - Transcribe Audio to Text

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

Usage:

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:

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

aws-transcribe-tool list-languages

Examples:

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:

aws-transcribe-tool completion generate SHELL

Arguments:

• SHELL: Shell type (bash, zsh, fish)

Examples:

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

⚙️ Advanced Features (Click to expand)

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:

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

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

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

# Cleanup after successful transcription
aws-transcribe-tool transcribe audio.mp3 out.txt bucket -c

🔧 Troubleshooting (Click to expand)

Common Issues

Issue: Command not found

# Verify installation
aws-transcribe-tool --version

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

Issue: Unsupported language code

# 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

# 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

# Verify bucket exists and is accessible
aws s3 ls s3://my-bucket

# Check bucket permissions
aws s3api get-bucket-policy --bucket my-bucket

Issue: Transcription timeout

• Large audio files may take longer to process
• Use -v flag to monitor progress
• Increase timeout or check job status manually in AWS Console

Issue: General errors

• Try with verbose flag: -vv to see detailed error information
• Check that all prerequisites are installed
• Ensure you're using Python 3.14+

Getting Help

# Show help
aws-transcribe-tool --help

# Command-specific help
aws-transcribe-tool transcribe --help
aws-transcribe-tool list-languages --help

Exit Codes

• 0: Success
• 1: Error (invalid arguments, validation failed, AWS error, or user cancelled)

Supported Audio Formats

• MP3
• MP4
• WAV
• FLAC
• Ogg
• WebM
• AMR

Best Practices

1. Use verbosity progressively: Start with -v, increase to -vv/-vvv only if needed
2. Check help first: Use --help to understand command options
3. Leverage shell completion: Install completion for better CLI experience
4. Use S3 cleanup: Enable -c flag to automatically remove uploaded audio files
5. Specify language: Always use -l for non-English audio to improve accuracy
6. Use AWS profiles: Leverage -p for different AWS accounts/environments

Resources

• GitHub: https://github.com/dnvriend/aws-transcribe-tool
• Python Package Index: https://pypi.org/project/aws-transcribe-tool/
• Amazon Transcribe Documentation: https://docs.aws.amazon.com/transcribe/