lrcgen 0.2.0

AI-powered LRC generator with Whisper and LLM correction

lrcgen

AI-powered LRC generator using Whisper + optional LLM correction.

Install

pip install lrcgen

Optional extras:

# enable online LLM correction
pip install "lrcgen[online]"

# enable OpenCC (Traditional→Simplified conversion)
pip install "lrcgen[opencc]"

# enable both
pip install "lrcgen[full]"

Requirements

• Offline transcription uses Whisper models (first run may download model files).
• Online correction requires OPENAI_API_KEY (or a compatible API via OPENAI_BASE_URL).

Usage

# batch
lrcgen input/ output/
lrcgen input/ output/ --offline
lrcgen input/ output/ --online

# single file
lrcgen --audio input/song.mp3 --output out.lrc --offline

# choose whisper model/language
lrcgen --audio input/song.mp3 --output out.lrc --offline --model large-v3 --language zh

# force GPU / pick CUDA device
lrcgen --audio input/song.mp3 --output out.lrc --offline --device cuda --cuda-device 0

# lyrics-guided generation (use your full lyrics as the "source of truth")
# lyrics can be out-of-order; txt or lrc both work
lrcgen --audio input/song.mp3 --output out.lrc --offline --lyrics-file input/lyrics.txt

# tune lyrics matching (example: aim for >=90% lines replaced by canonical lyrics)
lrcgen --audio input/song.mp3 --output out.lrc --offline --lyrics-file input/lyrics.txt --lyrics-target-coverage 0.90

# by default, target coverage is 0.90; disable auto-relax by setting 0
lrcgen --audio input/song.mp3 --output out.lrc --offline --lyrics-file input/lyrics.txt --lyrics-target-coverage 0

# tweak strictness (default min score is 0.50)
lrcgen --audio input/song.mp3 --output out.lrc --offline --lyrics-file input/lyrics.txt --lyrics-min-score 0.60

# module entrypoint (same as lrcgen command)
python -m lrcgen --audio input/song.mp3 --output out.lrc --offline

# version
python -m lrcgen --version

Online config

Set env vars (e.g. via .env):

• OPENAI_API_KEY=...
• OPENAI_BASE_URL=https://api.openai.com/v1 (optional)
• OPENAI_MODEL=gpt-4o-mini (optional)

Library usage

from lrcgen.api import generate_lrc_sync

generate_lrc_sync("input/song.mp3", "out.lrc", mode="offline")

Project structure

genlrc/
	README.md
	pyproject.toml
	music_to_lrc_batch.py
	lrcgen/
		__init__.py        # package version
		__main__.py        # enables: python -m lrcgen
		cli.py             # argparse CLI entrypoint
		api.py             # stable library API (sync + async)
		whisperer.py       # Whisper transcription wrapper
		corrector.py       # optional LLM correction + guardrails
		lyrics_aligner.py  # align transcript lines to user-provided full lyrics
		utils.py           # time formatting + basic text cleaning
		config.py          # env/.env config (OPENAI_*, etc.)
		input/             # optional local test inputs (not packaged)
		output/            # optional local outputs (not packaged)
	test/
		test.py            # small unittest suite
	tools/
		clean.py           # removes dist/build/cache artifacts
	.github/workflows/
		ci.yml             # CI build + checks
		publish.yml        # tag-based publish via PyPI Trusted Publishing (OIDC)

How it fits together:

• CLI: lrcgen/cli.py parses args and calls lrcgen/api.py.
• Core pipeline: whisperer.py transcribes audio → utils.py cleans → corrector.py optionally fixes lines → writes .lrc.
• Configuration: config.py loads environment variables (and .env if present).

Features

• Offline Whisper transcription
• Optional LLM correction
• Simplified Chinese output
• Batch processing