Transcription Guide for retrocast

Overview

The retrocast transcription module enables you to transcribe podcast audio files to searchable text using state-of-the-art speech recognition models. The module supports multiple backends optimized for different platforms and use cases.

Features

🎯 Multiple Backends: MLX Whisper (Apple Silicon), faster-whisper (CUDA/CPU), OpenAI Whisper
🚀 Auto-Detection: Automatically selects the best available backend for your platform
💾 Content Deduplication: SHA256 hashing prevents re-transcribing the same audio
🔍 Full-Text Search: Search across all transcribed content using SQLite FTS5
📝 Multiple Formats: Export as TXT, JSON, SRT (subtitles), or VTT (WebVTT)
✅ Schema Validation: Validate JSON transcription files against Pydantic models
📊 Rich CLI: Progress bars, colored output, and detailed status messages

Installation

retrocast provides convenient poe tasks to install transcription backends for different platforms.

For Apple Silicon (macOS)

MLX Whisper provides the best performance on M1/M2/M3 Macs:

# Recommended: Use poe task
poe install:transcription-mlx

# Alternative: Direct uv command
uv sync --extra transcription-mlx

For Linux with CUDA

For systems with NVIDIA GPUs and CUDA support:

# Recommended: Use poe task
poe install:transcription-cuda

# Alternative: Direct uv command
uv sync --extra transcription-cuda

For CPU-Only (Any Platform)

For systems without GPU acceleration:

# Recommended: Use poe task
poe install:transcription-cpu

# Alternative: Direct uv command
uv sync --extra transcription-cpu

Verify Installation

After installing a backend, verify it's working:

# List available backends
retrocast transcription backends list

# Test specific backend
retrocast transcription backends test mlx-whisper
# Or test faster-whisper
retrocast transcription backends test faster-whisper

Backend Comparison

retrocast supports multiple transcription backends, each optimized for different platforms and use cases:

MLX Whisper (Apple Silicon)

Best for: M1/M2/M3 Macs

Pros:
- Fastest performance on Apple Silicon (3-5x faster than CPU)
- Native Metal acceleration
- Low memory usage
- Optimized for macOS
Cons:
- Only works on macOS with Apple Silicon
- Requires MLX framework
Installation: poe install:transcription-mlx

Faster-Whisper (CUDA/CPU)

Best for: Linux with NVIDIA GPUs or any platform without Apple Silicon

Pros:
- Excellent CUDA GPU performance (2-4x faster than OpenAI Whisper)
- Works on any platform (Windows, Linux, macOS)
- Automatic CPU fallback if CUDA not available
- Lower memory usage than OpenAI Whisper
- More accurate than OpenAI Whisper in some cases
Cons:
- Requires CUDA setup for GPU acceleration
- Slightly more complex installation on Windows
Installation:
- CUDA: poe install:transcription-cuda
- CPU: poe install:transcription-cpu

When to Use Which Backend

Scenario	Recommended Backend	Alternative
macOS with M1/M2/M3	MLX Whisper	faster-whisper (CPU)
Linux with NVIDIA GPU	faster-whisper (CUDA)	-
Windows with NVIDIA GPU	faster-whisper (CUDA)	-
Any platform, CPU-only	faster-whisper (CPU)	-
Maximum accuracy	faster-whisper (large model)	MLX Whisper (large model)
Quick drafts	Any backend with tiny/base model	-

Quick Start

1. Check Available Backends

Before transcribing, check which backends are available on your system:

retrocast transcription backends list

Example output:

┌────────────────┬─────────────────┬───────────────────────┬──────────────────────────────────────────────┐
│ Backend        │     Status      │ Platform              │ Description                                  │
├────────────────┼─────────────────┼───────────────────────┼──────────────────────────────────────────────┤
│ mlx-whisper    │ ✓ Available     │ macOS (Apple Silicon) │ MLX Whisper - optimized for Apple Silicon    │
│                │                 │                       │ M1/M2/M3                                     │
│ faster-whisper │ ✗ Not Available │ Any platform (CPU)    │ Faster-Whisper - optimized Whisper with      │
│                │                 │                       │ CUDA/CPU support                             │
└────────────────┴─────────────────┴───────────────────────┴──────────────────────────────────────────────┘

2. Test a Specific Backend

retrocast transcription backends test mlx-whisper
# Or test faster-whisper
retrocast transcription backends test faster-whisper

3. Transcribe Your First File

# Transcribe a single audio file
retrocast transcription process episode.mp3

# Transcribe all audio files in a directory
retrocast transcription process /path/to/podcast/episodes/

# Transcribe with specific options
retrocast transcription process --model medium --format srt episode.mp3

CLI Command Reference

`retrocast transcription process`

Transcribe audio files to text.

Usage:

retrocast transcription process [OPTIONS] PATHS...

Arguments:

PATHS: One or more audio files or directories containing audio files

Options:

Option	Values	Default	Description
`--backend`	auto, mlx-whisper, faster-whisper	auto	Transcription backend to use
`--model`	tiny, base, small, medium, large	base	Whisper model size
`--language`	en, es, fr, etc.	auto-detect	Audio language code
`--output-dir`	PATH	app_dir/transcriptions	Output directory for transcription files
`--format`	txt, json, srt, vtt	json	Output format
`--force`	flag	false	Re-transcribe even if already exists
`--db`	PATH	app_dir/overcast.db	Database file path

Supported Audio Formats:

MP3 (.mp3)
M4A (.m4a)
OGG (.ogg)
Opus (.opus)
WAV (.wav)
FLAC (.flac)
AAC (.aac)

`retrocast transcription backends list`

List all available transcription backends with their status.

Usage:

retrocast transcription backends list

Shows a table with backend name, availability status, platform requirements, and description.

`retrocast transcription backends test`

Test if a specific backend is available and properly configured.

Usage:

retrocast transcription backends test BACKEND_NAME

Example:

retrocast transcription backends test mlx-whisper
retrocast transcription backends test faster-whisper

`retrocast transcription search`

Search transcribed content using full-text search.

Usage:

retrocast transcription search [OPTIONS] QUERY

Arguments:

QUERY: Search query (supports full-text search syntax)

Options:

Option	Type	Default	Description
`--podcast`	TEXT	-	Filter by podcast title
`--limit`	INT	10	Maximum number of results
`--db`	PATH	app_dir/overcast.db	Database file path

`retrocast transcription validate`

Validate all JSON transcription files against the expected schema.

Usage:

retrocast transcription validate [OPTIONS]

Options:

Option	Type	Default	Description
`--output-dir`	PATH	app_dir/transcriptions	Directory containing transcription JSON files
`--verbose`, `-v`	FLAG	-	Show detailed validation errors for each file

Description:

The validate command checks all JSON transcription files in the specified directory to ensure they conform to the expected schema. It provides:

Real-time progress: Shows a progress bar with file counts and percentage complete
Comprehensive validation: Checks for:
- JSON parsing errors (malformed JSON)
- Schema violations (missing required fields, invalid data types)
- Data constraints (negative durations, invalid timestamps)
Summary report: Displays a table with counts and percentages of valid/invalid/error files
Error details: Lists problematic files and shows specific validation errors in verbose mode
Proper exit codes: Returns 0 if all files are valid, 1 if any errors are found

Example Output:

Validating 42 transcription file(s)...

  Validating TestPodcast/episode1.json... ━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:05

═══ Validation Summary ═══

 Status         │ Count │ Percentage 
────────────────┼───────┼────────────
 Valid          │    40 │      95.2% 
 Invalid Schema │     1 │       2.4% 
 Parse Errors   │     1 │       2.4% 
 Total          │    42 │     100.0% 

Files with validation errors (1):
  • TestPodcast/invalid_episode.json

Examples:

# Validate all transcriptions in default directory
retrocast transcription validate

# Show detailed errors for each invalid file
retrocast transcription validate --verbose

# Validate transcriptions in a custom directory
retrocast transcription validate --output-dir /path/to/transcriptions

Use Cases:

Verify transcription file integrity after processing
Detect corrupted or malformed JSON files
Ensure schema compliance before sharing or archiving
Troubleshoot transcription issues
Validate files after manual edits or migrations

Usage Examples

Basic Transcription

# Transcribe a single file with defaults (base model, JSON output)
retrocast transcription process episode.mp3

Batch Processing

# Transcribe all MP3 files in a directory
retrocast transcription process ~/Downloads/podcasts/

# Transcribe multiple specific files
retrocast transcription process episode1.mp3 episode2.mp3 episode3.m4a

Model Selection

# Use tiny model (fastest, lowest accuracy)
retrocast transcription process --model tiny episode.mp3

# Use medium model (balanced speed/accuracy)
retrocast transcription process --model medium episode.mp3

# Use large model (slowest, highest accuracy)
retrocast transcription process --model large episode.mp3

Model Size Comparison:

Model	Size	Speed	Accuracy	Use Case
tiny	39M	Fastest	Lowest	Quick drafts, testing
base	74M	Fast	Good	General use (default)
small	244M	Moderate	Better	Higher quality needed
medium	769M	Slow	Very Good	Professional transcripts
large	1550M	Slowest	Best	Maximum accuracy

Language Specification

# Transcribe Spanish audio
retrocast transcription process --language es podcast_espanol.mp3

# Transcribe French audio
retrocast transcription process --language fr interview.mp3

# Auto-detect language (default)
retrocast transcription process podcast.mp3

Output Formats

# Plain text with timestamps
retrocast transcription process --format txt episode.mp3

# JSON with full metadata and segments
retrocast transcription process --format json episode.mp3

# SRT subtitle format (for video)
retrocast transcription process --format srt episode.mp3

# WebVTT format (for web players)
retrocast transcription process --format vtt episode.mp3

Format Details:

TXT: Human-readable plain text with optional timestamps and speaker labels
JSON: Machine-readable format with complete metadata, segments, and timing
SRT: SubRip subtitle format for video players
VTT: WebVTT format for HTML5 video players

Re-transcribing Files

# By default, already-transcribed files are skipped
retrocast transcription process episode.mp3
# Output: "Already transcribed (use --force to re-transcribe)"

# Force re-transcription (e.g., to try a different model)
retrocast transcription process --force --model large episode.mp3

Custom Output Directory

# Save transcriptions to a specific directory
retrocast transcription process --output-dir ~/transcripts/ episode.mp3

# Organize by project
retrocast transcription process --output-dir ~/projects/podcast-analysis/transcripts/ *.mp3

Searching Transcriptions

# Search all transcriptions
retrocast transcription search "machine learning"

# Search within a specific podcast
retrocast transcription search --podcast "My Podcast" "neural networks"

# Limit results
retrocast transcription search --limit 5 "python programming"

# Search for phrases
retrocast transcription search "artificial intelligence"

Search Results Example:

Found 3 result(s) for: machine learning

1. Tech Talk - Episode 42
   Time: 15:23
   We discuss the fundamentals of machine learning and how it's transforming...

2. AI Weekly - The Future of ML
   Time: 08:45
   Machine learning models have become increasingly sophisticated in recent...

3. Data Science Podcast - ML Basics
   Time: 22:10
   Let's dive into machine learning algorithms and their applications...

Validating Transcriptions

# Validate all transcription files in the default directory
retrocast transcription validate

# Get detailed error messages for each invalid file
retrocast transcription validate --verbose

# Validate transcriptions in a custom directory
retrocast transcription validate --output-dir ~/my-transcripts/

# Use validation in scripts (check exit code)
if retrocast transcription validate; then
    echo "All transcriptions are valid!"
else
    echo "Some transcriptions have errors"
fi

Validation Output Example:

Validating 12 transcription file(s)...

✓ TechPodcast/episode1.json
✓ TechPodcast/episode2.json
✗ TechPodcast/episode3.json: Validation failed
    Field: ('duration',), Error: Input should be greater than or equal to 0

═══ Validation Summary ═══

 Status         │ Count │ Percentage 
────────────────┼───────┼────────────
 Valid          │    11 │      91.7% 
 Invalid Schema │     1 │       8.3% 
 Parse Errors   │     0 │       0.0% 
 Total          │    12 │     100.0%

Workflow Examples

Transcribe a Podcast Series

# 1. Download episodes (using podcast-archiver or manually)
# 2. List available backends
retrocast transcription backends list

# 3. Transcribe entire directory with medium model for better quality
retrocast transcription process --model medium --format json ~/podcasts/my-show/

# 4. Search the transcribed content
retrocast transcription search "topic of interest"

Create Subtitles for Video

# Extract audio from video first (using ffmpeg)
ffmpeg -i video.mp4 -vn -acodec copy audio.m4a

# Transcribe to SRT format
retrocast transcription process --format srt --model medium audio.m4a

# The .srt file can now be used with video players

Multi-language Podcast Analysis

# Transcribe English episodes
retrocast transcription process --language en --podcast "English Show" english_episodes/

# Transcribe Spanish episodes
retrocast transcription process --language es --podcast "Spanish Show" spanish_episodes/

# Search across both
retrocast transcription search "technology"

Understanding Output

Directory Structure

Transcriptions are saved in a structured directory:

~/.config/retrocast/transcriptions/
├── Podcast Name/
│   ├── Episode Title.json
│   ├── Episode Title.txt
│   ├── Episode Title.srt
│   └── Episode Title.vtt
└── Another Podcast/
    └── ...

JSON Format

The JSON output includes complete metadata:

{
  "text": "Full transcription text...",
  "language": "en",
  "duration": 3600.5,
  "segments": [
    {
      "start": 0.0,
      "end": 5.2,
      "text": "Welcome to the show.",
      "speaker": null
    }
  ],
  "metadata": {
    "backend": "faster-whisper",
    "model_size": "base",
    "device": "cuda",
    "compute_type": "float16",
    "transcription_time": 45.2,
    "real_time_factor": 0.0125,
    "language_probability": 0.99
  }
}

Database Storage

Transcriptions are also stored in SQLite for fast searching:

transcriptions table: Metadata (title, backend, model, duration, etc.)
transcription_segments table: Individual segments with timing and text
Full-text search: Enabled on segment text for fast queries

Performance Tips

Model Selection

Quick drafts: Use --model tiny for rapid transcription
General use: Use --model base (default) for good balance
High quality: Use --model medium or large for important content

Backend Selection

Apple Silicon (M1/M2/M3): MLX Whisper is 3-5x faster than CPU alternatives
NVIDIA GPU (CUDA): faster-whisper provides excellent performance (2-4x faster than CPU)
CPU-only: faster-whisper with int8 quantization provides best CPU performance
Auto mode: The CLI automatically selects the best available backend

Processing Time

Approximate real-time factors (time to transcribe 1 hour of audio):

Model	MLX (Apple Silicon)	faster-whisper (CUDA)	faster-whisper (CPU)
tiny	2-3 min	2-4 min	8-12 min
base	4-6 min	4-8 min	15-25 min
small	8-12 min	8-15 min	35-50 min
medium	15-25 min	15-30 min	90-120 min
large	30-45 min	30-60 min	3-4 hours

Times are approximate and depend on audio quality, speaking rate, and hardware.

Real-Time Factor (RTF) Examples:

RTF = 0.05 means 3 minutes to transcribe 1 hour (very fast)
RTF = 0.25 means 15 minutes to transcribe 1 hour (good)
RTF = 1.0 means 1 hour to transcribe 1 hour (real-time)

Batch Processing Tips

# Process multiple files efficiently
# The CLI shows progress for each file
retrocast transcription process --model base podcast_dir/*.mp3

# For very large batches, consider using smaller models first
retrocast transcription process --model tiny large_archive/

# Then re-transcribe important episodes with larger models
retrocast transcription process --force --model large important_episode.mp3

Troubleshooting

Backend Not Available

Problem: retrocast transcription backends list shows backend as "Not Available"

Solution:

# For MLX on macOS (Apple Silicon)
poe install:transcription-mlx

# For faster-whisper with CUDA (Linux with GPU)
poe install:transcription-cuda

# For faster-whisper CPU-only (any platform)
poe install:transcription-cpu

# Verify installation
retrocast transcription backends test mlx-whisper

CUDA Not Detected

Problem: faster-whisper not using GPU

Solution:

# Check PyTorch CUDA availability
python -c "import torch; print(torch.cuda.is_available())"

# Reinstall PyTorch with CUDA support
pip install torch --index-url https://download.pytorch.org/whl/cu121

Out of Memory Errors

Problem: Transcription fails with memory errors

Solution:

Use a smaller model: --model tiny or --model base
Process files one at a time instead of batches
Close other applications to free memory

Slow Transcription Speed

Problem: Transcription takes too long

Solution:

Use a smaller model (tiny or base)
Ensure backend is properly installed (MLX on macOS, CUDA on Linux)
Check that GPU is being used (if applicable)
Try a different backend: --backend mlx-whisper

Search Returns No Results

Problem: retrocast transcription search finds nothing

Solution:

Verify transcriptions exist: Check database or output directory
Try simpler queries: Single words instead of phrases
Check podcast filter: Remove --podcast to search all
Verify database path: Use --db to specify correct database

Advanced Usage

Using with Datasette

View and query transcriptions in a web interface:

# Install datasette
pip install datasette

# Open database in Datasette
datasette ~/.config/retrocast/overcast.db

Navigate to the transcriptions and transcription_segments tables to explore.

Scripting and Automation

#!/bin/bash
# Auto-transcribe new podcast downloads

DOWNLOAD_DIR="$HOME/podcasts/downloads"
TRANSCRIPT_DIR="$HOME/podcasts/transcripts"

# Watch for new files and transcribe
for file in "$DOWNLOAD_DIR"/*.mp3; do
  if [ -f "$file" ]; then
    retrocast transcription process \
      --model base \
      --format json \
      --output-dir "$TRANSCRIPT_DIR" \
      "$file"
  fi
done

Integration with Other Tools

# Python script to process transcriptions
import json
from pathlib import Path

# Read JSON transcription
transcript_path = Path("~/.config/retrocast/transcriptions/Podcast/Episode.json")
with open(transcript_path.expanduser()) as f:
    data = json.load(f)

# Extract full text
full_text = data["text"]

# Process segments
for segment in data["segments"]:
    print(f"[{segment['start']:.1f}s] {segment['text']}")

Frequently Asked Questions (FAQ)

Q: Which backend should I use?

A: It depends on your hardware:

Apple Silicon Mac (M1/M2/M3): Use MLX Whisper for best performance
NVIDIA GPU (Linux/Windows): Use faster-whisper with CUDA
CPU only: Use faster-whisper with CPU mode

The --backend auto option (default) automatically selects the best available backend.

Q: How long does transcription take?

A: Processing time depends on audio length, model size, and hardware. As a rule of thumb:

MLX Whisper on Apple Silicon: ~5-10% of audio duration for base model
faster-whisper on CUDA: ~5-15% of audio duration for base model
CPU mode: ~20-50% of audio duration for base model

Use smaller models (tiny, base) for faster processing, larger models (medium, large) for better accuracy.

Q: Will I lose my transcriptions if I move the audio files?

A: No. Transcriptions are identified by a SHA256 content hash, not file path. If you move or rename an audio file, retrocast can still find the existing transcription via the hash.

Q: How do I re-transcribe a file with a different model?

A: Use the --force flag:

retrocast transcription process --force --model large episode.mp3

Q: Can I transcribe files that aren't downloaded through retrocast?

A: Yes. The process command accepts any audio file path:

retrocast transcription process /path/to/any/audio.mp3

Q: How do I know which backends are installed?

A: Run:

retrocast transcription backends list

Q: Why is transcription slow even with GPU?

A: Check that:

The GPU backend is actually being used (backends list shows ✓ Available)
You're not using too large a model for your GPU memory
PyTorch CUDA is properly installed: python -c "import torch; print(torch.cuda.is_available())"

Q: Can I transcribe multiple languages?

A: Yes. Either:

Let Whisper auto-detect the language (default behavior)
Specify the language explicitly: --language es for Spanish

Q: How do I search within a specific podcast?

A: Use the --podcast filter:

retrocast transcription search --podcast "Tech Talk" "machine learning"

Q: What audio formats are supported?

A: MP3, M4A, OGG, Opus, WAV, FLAC, and AAC.

Q: How do I verify my transcription files are valid?

A: Use the retrocast transcription validate command to check all JSON transcription files against the expected schema:

# Validate all transcriptions
retrocast transcription validate

# Get detailed error messages
retrocast transcription validate --verbose

This will identify:

Malformed JSON files
Missing required fields
Invalid data types or values (e.g., negative durations)
Schema violations

The command returns exit code 0 if all files are valid, making it useful in scripts and CI/CD pipelines.

Future Enhancements

The following features are planned for future releases:

Speaker Diarization: Identify and label different speakers using pyannote.audio
Interactive Browser: Textual-based TUI for browsing transcriptions
Export to Datasette: Improved integration with Datasette for web-based exploration

Support

For issues, feature requests, or questions:

GitHub Issues: https://github.com/crossjam/retrocast/issues
Implementation Plan: See plans/2025-12-16-transcription-implementation-plan.md

Credits

Built on OpenAI Whisper
MLX backend uses mlx-whisper
faster-whisper backend uses faster-whisper

FilesExpand file tree

TRANSCRIPTION.md

Latest commit

History

TRANSCRIPTION.md

File metadata and controls

Transcription Guide for retrocast

Overview

Features

Installation

For Apple Silicon (macOS)

For Linux with CUDA

For CPU-Only (Any Platform)

Verify Installation

Backend Comparison

MLX Whisper (Apple Silicon)

Faster-Whisper (CUDA/CPU)

When to Use Which Backend

Quick Start

1. Check Available Backends

2. Test a Specific Backend

3. Transcribe Your First File

CLI Command Reference

retrocast transcription process

retrocast transcription backends list

retrocast transcription backends test

retrocast transcription search

retrocast transcription validate

Usage Examples

Basic Transcription

Batch Processing

Model Selection

Language Specification

Output Formats

Re-transcribing Files

Custom Output Directory

Searching Transcriptions

Validating Transcriptions

Workflow Examples

Transcribe a Podcast Series

Create Subtitles for Video

Multi-language Podcast Analysis

Understanding Output

Directory Structure

JSON Format

Database Storage

Performance Tips

Model Selection

Backend Selection

Processing Time

Batch Processing Tips

Troubleshooting

Backend Not Available

CUDA Not Detected

Out of Memory Errors

Slow Transcription Speed

Search Returns No Results

Advanced Usage

Using with Datasette

Scripting and Automation

Integration with Other Tools

Frequently Asked Questions (FAQ)

Q: Which backend should I use?

Q: How long does transcription take?

Q: Will I lose my transcriptions if I move the audio files?

Q: How do I re-transcribe a file with a different model?

Q: Can I transcribe files that aren't downloaded through retrocast?

Q: How do I know which backends are installed?

Q: Why is transcription slow even with GPU?

Q: Can I transcribe multiple languages?

Q: How do I search within a specific podcast?

Q: What audio formats are supported?

Q: How do I verify my transcription files are valid?

Future Enhancements

Support

Credits

`retrocast transcription process`

`retrocast transcription backends list`

`retrocast transcription backends test`

`retrocast transcription search`

`retrocast transcription validate`