pylrclib

A multi-command CLI for searching, downloading, inspecting, cleansing, and publishing lyrics around LRCLIB.

pylrclib is built for people who keep a real music library: audio files in one folder, plain lyrics in another, synced .lrc files somewhere else, and sometimes YAML metadata standing in for missing tags. It gives you one CLI for finding LRCLIB records, saving lyrics locally, checking local matches before upload, cleaning noisy LRC files, and publishing lyrics back to LRCLIB.

Package name: pylrclib-cli
Command name: pylrclib

Features

• Find LRCLIB records by text search, structured artist/title metadata, or exact LRCLIB id.
• Download lyrics as .txt, .lrc, or both, with predictable file naming.
• Upload local plain lyrics, synced lyrics, mixed records, or instrumental markers.
• Flag incorrect LRCLIB records by id.
• List and download public LRCLIB database dumps.
• Match lyrics from audio filenames, YAML-declared files, and normalized Artist - Title names.
• Preview local matches before publishing so you can catch bad pairings.
• Clean .lrc files with default rules or fine-tuned --keep-* options.
• Diagnose a workspace before a large upload run.
• Switch CLI output between English and Chinese with --lang auto|en_US|zh_CN.

Lyrics Model

The CLI treats lyrics as explicit states:

State	Meaning
plain	Unsynced plain-text lyrics.
synced	Timed LRC lyrics.
mixed	Both plain and synced lyrics are available.
instrumental	Instrumental / no-vocals track.

The same model is used by search, down, up, and inspect, while cleanse uses the same LRC parser to normalize synced lyric files.

Installation

Install from PyPI:

pip install pylrclib-cli

Then check the CLI:

pylrclib --help
pylrclib --version

Install from source when developing:

pip install -e .

Quick Start

Search LRCLIB:

pylrclib search --query "Aimer Ref:rain"
pylrclib search --artist "Aimer" --title "Ref:rain"

Download the best matching lyrics:

pylrclib down \
  --artist "Aimer" \
  --title "Ref:rain" \
  --output-dir ./lyrics

Download both plain text and synced LRC for an exact LRCLIB record:

pylrclib down \
  --lrclib-id 12345 \
  --output-dir ./lyrics \
  --save-mode both

Inspect local matches before uploading:

pylrclib inspect \
  --tracks ./music \
  --plain-dir ./lyrics_plain \
  --synced-dir ./lyrics_lrc \
  --show-all-candidates

Upload local lyrics:

pylrclib up \
  --tracks ./music \
  --plain-dir ./lyrics_plain \
  --synced-dir ./lyrics_lrc \
  --lyrics-mode auto

Flag an incorrect LRCLIB record:

pylrclib flag --lrclib-id 12345 --content "wrong lyrics"

List or download database dumps:

pylrclib dumps
pylrclib dumps --limit 1 --download --output-dir ./dumps

Clean LRC files, first as a preview and then with write-back:

pylrclib cleanse ./lyrics_lrc
pylrclib cleanse ./lyrics_lrc --write

Diagnose the workspace:

pylrclib doctor \
  --tracks ./music \
  --plain-dir ./lyrics_plain \
  --synced-dir ./lyrics_lrc

Commands

search

Use search to inspect remote LRCLIB records before downloading or uploading.

pylrclib search --query "artist title"
pylrclib search --title "Song Title" --artist "Artist Name"
pylrclib search --lrclib-id 12345

Common options:

--query TEXT
--title TEXT
--artist TEXT
--album TEXT
--lrclib-id N
--limit N
--preview-lines N
--max-retries N
--user-agent TEXT
--api-base URL
--json
--yes
--non-interactive

down

Use down to fetch lyrics from LRCLIB and write them locally.

Input modes:

1. Scan local audio or YAML metadata with --tracks.
2. Download one manually specified track with --artist and --title.
3. Fetch one exact LRCLIB record with --lrclib-id.

pylrclib down --tracks ./music --output-dir ./lyrics
pylrclib down --artist "Artist" --title "Song" --output-dir ./lyrics
pylrclib down --lrclib-id 12345 --output-dir ./lyrics --save-mode both

Save modes:

Mode	Behavior
auto	Save .lrc when synced lyrics exist, otherwise save .txt when plain lyrics exist.
plain	Save only .txt.
synced	Save only .lrc.
both	Save both .txt and .lrc when available.

Naming modes:

Mode	Behavior
auto	Use local track basename when scanning files, otherwise use Artist - Title.
track-basename	Force the source audio/YAML basename when available.
artist-title	Use Artist - Title.

Common options:

--tracks PATH
--artist TEXT
--title TEXT
--album TEXT
--duration N
--lrclib-id N
--output-dir PATH
--plain-dir PATH
--synced-dir PATH
--save-mode auto|plain|synced|both
--naming auto|track-basename|artist-title
--skip-existing
--overwrite
--allow-derived-plain
--no-derived-plain
--preview-lines N
--max-retries N
--user-agent TEXT
--api-base URL
--yes
--non-interactive

up

Use up to publish local lyrics to LRCLIB.

The upload workflow:

1. Discover audio files or YAML metadata.
2. Query LRCLIB external matches. The deprecated /api/get-cached path is skipped with a warning because current LRCLIB returns 404 for it.
3. Resolve local plain and synced lyric candidates.
4. Classify lyrics as plain, synced, mixed, instrumental, invalid, or empty.
5. Optionally normalize matched LRC content when --cleanse is enabled.
6. Build an upload plan from --lyrics-mode.
7. Publish lyrics or mark the track instrumental.
8. Optionally move or rename processed files.

Recommended split-directory workflow:

pylrclib up \
  --tracks ./music \
  --plain-dir ./lyrics_plain \
  --synced-dir ./lyrics_lrc \
  --cleanse \
  --cleanse-write \
  --done-lrc ./done_lyrics \
  --lyrics-mode auto

Upload modes:

Mode	Behavior
auto	Upload the best available local lyrics. Mixed wins over synced, synced wins over plain.
plain	Require plain lyrics.
synced	Require synced lyrics. Plain lyrics may be derived unless disabled.
mixed	Require both plain and synced lyrics, or derive plain from synced when allowed.
instrumental	Publish instrumental metadata.

Local matching checks:

1. Same basename as the audio or YAML file.
2. YAML-declared filenames.
3. Normalized Artist - Title.* matches.
4. Interactive selection when multiple candidates exist.

Supported local lyric extensions:

Type	Extensions
Plain	.txt, .lyrics, .lyric
Synced	.lrc

Common options:

--tracks PATH
--lyrics-dir PATH
--plain-dir PATH
--synced-dir PATH
--done-tracks PATH
--done-lrc PATH
-f, --follow
-r, --rename
-c, --cleanse
--cleanse-write
--keep-headers
--keep-credits
--keep-translations
--keep-instrumental-marker
--allow-non-lrc
--ignore-duration-mismatch
--lyrics-mode auto|plain|synced|mixed|instrumental
--allow-derived-plain
--no-derived-plain
-d, --default TRACKS_DIR LYRICS_DIR
-m, --match
--preview-lines N
--max-retries N
--max-pow-iterations N
--user-agent TEXT
--api-base URL
--yes
--non-interactive

flag

Use flag to report an incorrect LRCLIB record by id.

pylrclib flag --lrclib-id 12345 --content "wrong lyrics"
pylrclib flag --lrclib-id 12345 --yes

Common options:

--lrclib-id N
--content TEXT
--preview-lines N
--max-retries N
--max-pow-iterations N
--user-agent TEXT
--api-base URL
--yes
--non-interactive

dumps

Use dumps to list public LRCLIB database dumps, emit their metadata as JSON, or download the newest entries.

pylrclib dumps
pylrclib dumps --json
pylrclib dumps --limit 1 --download --output-dir ./dumps

Common options:

--limit N
--json
--download
--output-dir PATH
--overwrite
--max-retries N
--user-agent TEXT

inspect

Use inspect to see what up would find locally without publishing anything.

pylrclib inspect \
  --tracks ./music \
  --plain-dir ./lyrics_plain \
  --synced-dir ./lyrics_lrc \
  --show-all-candidates

Common options:

--tracks PATH
--lyrics-dir PATH
--plain-dir PATH
--synced-dir PATH
--lyrics-mode auto|plain|synced|mixed|instrumental
--preview-lines N
--show-all-candidates

cleanse

Use cleanse to normalize .lrc files. Without --write, the command previews the cleansed output and leaves files unchanged.

pylrclib cleanse ./lyrics_lrc
pylrclib cleanse ./lyrics_lrc --write
pylrclib cleanse song.lrc another.lrc

cleanse removes common noisy content such as header tags, credit lines, duplicate CJK translation lines, and pure-music marker lines by default. Invalid files are not rewritten into empty files.

Every cleanse rule has a keep flag for precision:

pylrclib cleanse ./lyrics_lrc --write --keep-translations
pylrclib cleanse ./lyrics_lrc --write --keep-headers --keep-credits

Inside pylrclib up, --cleanse controls in-memory LRC normalization for preview and upload. Without it, matched .lrc files are uploaded as read from disk. Add --cleanse-write to write the normalized LRC content back to the matched file before upload. The same --keep-* flags refine upload-time cleansing. Use the standalone cleanse command when you want to bulk-normalize files without uploading.

Common options:

paths ...
--lrc-dir PATH
--write
--keep-headers
--keep-credits
--keep-translations
--keep-instrumental-marker
--preview-lines N

doctor

Use doctor to print resolved configuration, count local inputs, and catch obvious workflow conflicts.

pylrclib doctor \
  --tracks ./music \
  --plain-dir ./lyrics_plain \
  --synced-dir ./lyrics_lrc

Common options:

--tracks PATH
--lyrics-dir PATH
--plain-dir PATH
--synced-dir PATH
--done-tracks PATH
--done-lrc PATH
-f, --follow
-r, --rename
-c, --cleanse
--lyrics-mode auto|plain|synced|mixed|instrumental
-d, --default TRACKS_DIR LYRICS_DIR
-m, --match
--preview-lines N
--max-retries N
--user-agent TEXT
--api-base URL

YAML Metadata

YAML files can be used as track inputs when audio metadata is unavailable or inconvenient.

track: Song Title
artist: Artist Name
album: Album Name
duration: 180
plain_file: song.txt
synced_file: song.lrc
lyrics_file: song.lrc
lrc_file: song.lrc

Required fields:

track
artist
album
duration

Optional lyric filename fields:

plain_file
synced_file
lyrics_file
lrc_file

Environment Variables

Most directory, metadata, network, and preview options can be provided through environment variables:

PYLRCLIB_TRACKS_DIR
PYLRCLIB_LYRICS_DIR
PYLRCLIB_PLAIN_DIR
PYLRCLIB_SYNCED_DIR
PYLRCLIB_DONE_TRACKS_DIR
PYLRCLIB_DONE_LRC_DIR
PYLRCLIB_OUTPUT_DIR
PYLRCLIB_ARTIST
PYLRCLIB_TITLE
PYLRCLIB_ALBUM
PYLRCLIB_DURATION
PYLRCLIB_LRCLIB_ID
PYLRCLIB_FLAG_CONTENT
PYLRCLIB_API_BASE
PYLRCLIB_USER_AGENT
PYLRCLIB_PREVIEW_LINES
PYLRCLIB_MAX_HTTP_RETRIES
PYLRCLIB_MAX_POW_ITERATIONS
PYLRCLIB_LIMIT
PYLRCLIB_LANG

CLI arguments take precedence over environment variables. Environment variables take precedence over hardcoded defaults.

Language

pylrclib supports English and Chinese output:

pylrclib --lang en_US --help
pylrclib --lang zh_CN --help
pylrclib --lang auto --help

You can also set the language once for a shell session:

export PYLRCLIB_LANG=zh_CN
pylrclib --help

Help Reference

The command help is the source of truth for current defaults and exact option names:

pylrclib -h
pylrclib search -h
pylrclib down -h
pylrclib up -h
pylrclib flag -h
pylrclib dumps -h
pylrclib inspect -h
pylrclib cleanse -h
pylrclib doctor -h

Development

Install development dependencies:

pip install -e ".[dev]"

Run tests:

python -m pytest -q

Run coverage:

python -m coverage run --source=pylrclib -m pytest -q
python -m coverage report -m

As of the 0.4.8 release prep, the local suite has 122 tests and reports 94% line coverage.

Run linting, type checking, and packaging checks before publishing:

ruff check .
mypy pylrclib
python -m build
twine check dist/*

When changing CLI arguments, defaults, or help text, refresh the README summaries against:

python -m pylrclib --lang en_US -h
python -m pylrclib --lang en_US search -h
python -m pylrclib --lang en_US down -h
python -m pylrclib --lang en_US up -h
python -m pylrclib --lang en_US flag -h
python -m pylrclib --lang en_US inspect -h
python -m pylrclib --lang en_US cleanse -h
python -m pylrclib --lang en_US doctor -h

中文速览

pylrclib 是一个围绕 LRCLIB 的歌词命令行工具，可以搜索、下载、检查、清洗和上传歌词。

常用命令：

pylrclib search --query "歌手 歌名"
pylrclib down --artist "歌手" --title "歌名" --output-dir ./lyrics
pylrclib inspect --tracks ./music --lyrics-dir ./lyrics --show-all-candidates
pylrclib up --tracks ./music --plain-dir ./plain --synced-dir ./lrc
pylrclib cleanse ./lrc --write
pylrclib doctor --tracks ./music --lyrics-dir ./lyrics

使用中文界面：

pylrclib --lang zh_CN --help
export PYLRCLIB_LANG=zh_CN

License

MIT