Musical Recording Captioning

Caption recordings of musical theater, concerts, or any video that has lyrics on Genius.

How it works

1. Fetches all track lyrics for an album from the Genius API
2. Transcribes the audio locally using Whisper (via faster-whisper) to get word-level timestamps
3. Fuzzy-matches each lyric line to the transcript to determine timing
4. Writes a .srt subtitle file

All processing after the initial Genius lyrics fetch runs entirely offline.

Prerequisites

• Python 3.10+
• ffmpeg installed and on your PATH
• A Genius API access token — get one at https://genius.com/api-clients

Installation

pip install musicalrecordingcaptioning

Or from source:

git clone https://github.com/you/MusicalRecordingCaptioning
cd MusicalRecordingCaptioning
python -m venv .venv && source .venv/bin/activate
pip install -e .

The installer automatically downloads the default Whisper model (small) so the first run works offline.

Configuration

Copy .env.example to .env and fill in your token:

GENIUS_ACCESS_TOKEN=your_token_here

Or pass it directly via --genius-token.

Usage

# Basic usage (token from .env, auto-detects language)
mrc recording.mp4 --url https://genius.com/albums/Lin-manuel-miranda/Hamilton

# Specify language explicitly for faster, more accurate transcription
mrc recording.mp4 --url https://genius.com/albums/Lin-manuel-miranda/Hamilton --language en

# French show
mrc spectacle.mp4 --url https://genius.com/albums/... --language fr

# Specify output file and a larger model for better accuracy
mrc show.mp4 --url https://genius.com/albums/Claude-michel-schonberg/Les-miserables-original-broadway-cast-recording \
    --output les-mis.srt --model medium --language fr

# Also caption dialogue and non-song audio with the raw Whisper transcript
mrc recording.mp4 --url https://genius.com/albums/Lin-manuel-miranda/Hamilton --keep-transcription

# Pass token explicitly
mrc concert.mp3 --url https://genius.com/albums/Anais-mitchell/Hadestown \
    --genius-token abc123

Options

Caption format

Lyric lines are wrapped with ♪ symbols (♪ lyrics here ♪), matching standard subtitle convention for sung content. When --keep-transcription is enabled, dialogue and non-song audio appear as plain text captions.

Whisper models

Only the small model is downloaded at install time. Other models are downloaded on first use when specified via --model.