DialogDetective

Documentation

DialogDetective takes the guesswork out of organizing TV series rips. Point it at a directory of video files, tell it the show name, and let AI do the detective work.

The process is simple: extract audio from each video using FFmpeg, transcribe the dialogue using Whisper, fetch episode metadata from TVMaze, then use an LLM to match what was said to the correct episode. Finally, rename or copy the files with proper episode information.

CLI Usage

dialog_detective <VIDEO_DIR> <SHOW_NAME> [OPTIONS]

Options

Operation Modes

DialogDetective supports three operation modes, controlled by the --mode option:

# Preview changes (always do this first)
dialog_detective ./videos "Breaking Bad" -s 1

# Rename files in place
dialog_detective ./videos "Breaking Bad" -s 1 --mode rename

# Copy to organized directory
dialog_detective ./videos "Breaking Bad" -s 1 --mode copy -o ./organized

Season Filtering

Since you're typically processing a single season at a time when ripping discs, specifying the correct season makes the tool much more effective.

# Process only season 1 files
dialog_detective ./videos "Breaking Bad" -s 1

# Process multiple seasons
dialog_detective ./videos "Breaking Bad" -s 1 -s 2

Filename Templates

Use --format to customize output filenames. The default template is:

{show} - S{season:02}E{episode:02} - {title}.{ext}

Available Variables

# Custom format example
dialog_detective ./videos "The Flash" -s 1 \
  --format "{show} S{season:02}E{episode:02} {title}.{ext}"

Whisper Models

DialogDetective uses Whisper for speech-to-text transcription. Models are automatically downloaded from HuggingFace on first use.

Model Selection

Choose a model based on your needs:

English-only variants (tiny.en, base.en, etc.) are slightly more accurate for English content. Quantized variants (-q5_0, -q5_1, -q8_0) are smaller but slightly less accurate.

# List all available models and see which are cached
dialog_detective --list-models

# Use a specific model
dialog_detective ./videos "Show" -s 1 --model large-v3-turbo

GPU Acceleration

DialogDetective uses whisper-rs for speech-to-text, which supports various GPU backends for faster transcription.

Pre-built Binaries

Building with GPU Support

If you have the required GPU frameworks installed on Linux or Windows, you can build with GPU acceleration:

# NVIDIA CUDA (requires CUDA toolkit)
cargo build --release --features cuda

# Vulkan (requires Vulkan SDK)
cargo build --release --features vulkan

# AMD ROCm/hipBLAS (requires ROCm)
cargo build --release --features hipblas

See the whisper-rs documentation for detailed requirements for each GPU backend.

AI Backend

DialogDetective uses external CLI tools for LLM access. You must have one of the following installed and authenticated:

• Gemini CLI (default) - Google's Gemini models
• Claude Code - Anthropic's Claude models

The CLI must be working independently before DialogDetective can use it. Test with gemini or claude in your terminal.

# Use Gemini (default)
dialog_detective ./videos "Show" -s 1

# Use Claude
dialog_detective ./videos "Show" -s 1 --matcher claude

The interface is abstracted to easily support direct API access in the future. Contributions welcome!

Cache & Storage

DialogDetective caches various data to avoid redundant processing and speed up repeated runs.

Cache Location

All cached data is stored in a platform-specific cache directory:

• macOS: ~/Library/Caches/de.westhoffswelt.dialogdetective/
• Linux: ~/.cache/dialogdetective/
• Windows: %LOCALAPPDATA%\dialogdetective\

What Gets Cached

The 24-hour TTL balances freshness with efficiency. If you need to force a refresh (e.g., after TVMaze updates episode data), simply delete the relevant cache subdirectory.

Temporary Files

During processing, DialogDetective extracts audio to temporary WAV files in your system's temp directory (/tmp, /var/folders/..., or %TEMP%). These files are automatically cleaned up when processing completes or if the program is interrupted.

Managing Cache

To clear all cached data:

# macOS
rm -rf ~/Library/Caches/de.westhoffswelt.dialogdetective/

# Linux
rm -rf ~/.cache/dialogdetective/

To clear only models (to free disk space):

# macOS
rm -rf ~/Library/Caches/de.westhoffswelt.dialogdetective/models/

# Linux
rm -rf ~/.cache/dialogdetective/models/

Use dialog_detective --list-models to see which models are currently cached and their sizes.