transcribe-cli

CLI tool for transcribing audio and video files using OpenAI Whisper API.

Features

• Audio Transcription: Transcribe MP3, WAV, FLAC, AAC, M4A files
• Video Support: Extract and transcribe audio from MKV, MP4, AVI, MOV
• Batch Processing: Process entire directories with concurrent API calls
• Multiple Output Formats: Plain text (TXT) and subtitles (SRT)
• Large File Support: Automatic chunking for files >25MB
• Resume Support: Continue interrupted transcriptions

Requirements

• Python 3.9+
• FFmpeg 4.0+
• OpenAI API key

Installation

1. Install FFmpeg

Linux (Ubuntu/Debian):

sudo apt update && sudo apt install ffmpeg -y

macOS (Homebrew):

brew install ffmpeg

Windows (Chocolatey):

choco install ffmpeg -y

2. Install transcribe-cli

pip install transcribe-cli

Or install from source:

git clone https://github.com/jmagly/transcribe-cli.git
cd transcribe-cli
pip install -e .

3. Configure API Key

export OPENAI_API_KEY=sk-your-api-key-here

Or create a .env file:

cp .env.example .env
# Edit .env and add your API key

Quick Start

# Transcribe a single file
transcribe audio.mp3

# Transcribe video (extracts audio automatically)
transcribe video.mkv

# Output as SRT subtitles
transcribe audio.mp3 --format srt

# Batch process a directory
transcribe batch ./recordings

# Extract audio only (no transcription)
transcribe extract video.mkv

Usage

Transcribe Command

transcribe <file> [OPTIONS]

Options:
  -o, --output-dir PATH   Output directory (default: current)
  -f, --format TEXT       Output format: txt, srt (default: txt)
  -l, --language TEXT     Language code or 'auto' (default: auto)
  --verbose               Enable verbose output
  --help                  Show help message

Batch Command

transcribe batch <directory> [OPTIONS]

Options:
  -o, --output-dir PATH   Output directory
  -f, --format TEXT       Output format: txt, srt
  -c, --concurrency INT   Max concurrent jobs (1-20, default: 5)
  -r, --recursive         Scan subdirectories
  --dry-run               Preview files without processing
  --verbose               Enable verbose output
  --help                  Show help message

Examples:

# Preview what would be processed
transcribe batch ./recordings --dry-run

# Process subdirectories
transcribe batch ./media --recursive

# Combine options
transcribe batch ./videos --recursive --format srt --concurrency 3

Extract Command

transcribe extract <file> [OPTIONS]

Options:
  -o, --output PATH       Output audio file path
  -f, --format TEXT       Output format: mp3, wav (default: mp3)
  --verbose               Enable verbose output
  --help                  Show help message

Config Command

transcribe config [OPTIONS]

Options:
  --show        Show current configuration
  --init        Create default config file
  --locations   Show config file search paths
  --help        Show help message

Configuration

Config File

Create a transcribe.toml file in your project directory:

transcribe config --init

Example configuration:

[output]
format = "txt"

[processing]
concurrency = 5
language = "auto"
recursive = false

[logging]
verbose = false

Config files are searched in this order:

1. ./transcribe.toml
2. ./.transcriberc
3. ~/.config/transcribe/config.toml
4. ~/.transcriberc

Environment Variables

Settings can also be configured via environment variables:

Variable	Description	Default
OPENAI_API_KEY	OpenAI API key (required)	-
TRANSCRIBE_OUTPUT_DIR	Default output directory	.
TRANSCRIBE_FORMAT	Default output format	txt
TRANSCRIBE_CONCURRENCY	Max concurrent jobs	5
TRANSCRIBE_LANGUAGE	Default language	auto

Development

Setup

# Clone repository
git clone https://github.com/jmagly/transcribe-cli.git
cd transcribe-cli

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/macOS
# or: venv\Scripts\activate  # Windows

# Install with dev dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Testing

# Run tests
pytest

# Run with coverage
pytest --cov=src/transcribe_cli --cov-report=html

# Run linting
black src tests
flake8 src tests
mypy src

Project Structure

src/transcribe_cli/
├── cli/          # CLI commands (Typer)
├── config/       # Configuration management
├── core/         # Audio extraction, transcription
├── output/       # Output formatters (TXT, SRT)
├── models/       # Data models
└── utils/        # Utilities

License

MIT

Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes with tests
4. Run pytest and pre-commit run --all-files
5. Submit a pull request

Acknowledgments

• OpenAI Whisper for speech recognition
• FFmpeg for audio/video processing
• Typer for CLI framework