{"id":49926360,"url":"https://github.com/papernick/lrc_tools","last_synced_at":"2026-06-04T20:00:14.104Z","repository":{"id":358342126,"uuid":"1241009702","full_name":"PaperNick/lrc_tools","owner":"PaperNick","description":"CLI tool for embedding, extracting, cleaning, and inspecting LRC lyrics in MP3 files via SYLT/USLT ID3 frames","archived":false,"fork":false,"pushed_at":"2026-05-16T22:15:57.000Z","size":14,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-17T00:48:47.720Z","etag":null,"topics":["cli","id3","id3v2","lrc","lrclib","lyrics","metadata","mp3","music","python","sylt","synced","syncedlyrics","uslt"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PaperNick.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-16T21:10:35.000Z","updated_at":"2026-05-16T22:15:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/PaperNick/lrc_tools","commit_stats":null,"previous_names":["papernick/lrc_tools"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/PaperNick/lrc_tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PaperNick%2Flrc_tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PaperNick%2Flrc_tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PaperNick%2Flrc_tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PaperNick%2Flrc_tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PaperNick","download_url":"https://codeload.github.com/PaperNick/lrc_tools/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PaperNick%2Flrc_tools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33917184,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-04T02:00:06.755Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","id3","id3v2","lrc","lrclib","lyrics","metadata","mp3","music","python","sylt","synced","syncedlyrics","uslt"],"created_at":"2026-05-17T00:11:22.818Z","updated_at":"2026-06-04T20:00:14.070Z","avatar_url":"https://github.com/PaperNick.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# lrc_tools\n\nUnified CLI for reading, embedding, extracting, cleaning, and inspecting LRC lyrics in MP3 files.\n\n\n## Requirements\n\n- Python 3.10+\n- [mutagen](https://mutagen.readthedocs.io/) - audio metadata library\n\n\n## Install\n\n\n### Pre-built binaries\n\n\u003e [!NOTE]\n\u003e Pre-built binaries for Linux, Windows, and macOS are available on the [releases page](https://github.com/PaperNick/lrc_tools/releases).\n\n\n### Build from source\n\nCreate a virtual environment, install dependencies, and build with PyInstaller:\n\n```shell\npython3 -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt\npyinstaller lrc_tools.spec\n```\n\nThe binary will be at `dist/lrc_tools`. Copy it anywhere on your `PATH`:\n\n```shell\ncp dist/lrc_tools ~/.local/bin/\n```\n\n### Run with Python directly\n\nEach script can be run without building:\n\n```shell\npython3 src/lrc_tools.py --help\n```\n\n## Usage\n\nAll examples below assume the binary `lrc_tools` is on your `PATH`.\nReplace `lrc_tools` with `python3 src/lrc_tools.py` if running from source.\n\n```shell\n# Show available subcommands\nlrc_tools --help\n\n# Get help for a specific subcommand\nlrc_tools read --help\nlrc_tools embed --help\nlrc_tools extract --help\nlrc_tools clean --help\nlrc_tools inspect --help\n```\n\n---\n\n### read\n\nRead embedded lyrics from an MP3 directly to stdout.\n\n```shell\n# Print summary of available lyrics (to stderr)\nlrc_tools read song.mp3\n\n# Output timed lyrics (SYLT) as LRC format\nlrc_tools read song.mp3 timed\n\n# Output plain lyrics (USLT) as plain text\nlrc_tools read song.mp3 plain\n\n# Include language code header on the first line\nlrc_tools read song.mp3 timed --include-lang\nlrc_tools read song.mp3 plain --include-lang\n\n# Pipe\nlrc_tools read song.mp3 plain | grep \"love\"\n```\n\nWhen no `kind` is specified, a summary is printed to stderr showing which lyric types are available.\n\nThe `--include-lang` flag prepends a `Language: xx` header line using the resolved\n2-letter ISO 639-1 code (e.g. `Language: ja` for Japanese, `Language: en` for English).\n\n---\n\n### embed\n\nEmbed LRC lyrics into an MP3 as SYLT (synchronized) and/or USLT (unsynchronized) frames.\n\n```shell\n# Embed with auto-discovered LRC file\nlrc_tools embed song.mp3\n\n# Specify LRC file explicitly\nlrc_tools embed song.mp3 lyrics.lrc\n\n# Override language (3-letter ISO 639-2 code)\nlrc_tools embed song.mp3 --lang kor\n\n# Modify original MP3 instead of creating a copy\nlrc_tools embed song.mp3 --in-place\n\n# Write to a specific output file\nlrc_tools embed song.mp3 --output tagged.mp3\n\n# Skip embedding timed (SYLT) or plain (USLT) lyrics\nlrc_tools embed song.mp3 --no-timed\nlrc_tools embed song.mp3 --no-plain\n\n# Preview without writing\nlrc_tools embed song.mp3 --dry-run\n```\n\nIf no LRC file is provided, it auto-discovers one by globbing `{stem}*.lrc` (e.g. `song.ko.lrc` for `song.mp3`). Language is auto-detected from the filename suffix (e.g. `.ko.lrc` -\u003e `kor`), and defaults to `eng`.\n\n---\n\n### extract\n\nExtract embedded timed/plain (SYLT/USLT) lyrics from an MP3 to an LRC file.\n\n```shell\n# Extract to auto-named file (e.g. song.en.lrc)\nlrc_tools extract song.mp3\n\n# Extract only timed (SYLT) or only plain (USLT) lyrics\nlrc_tools extract song.mp3 timed\nlrc_tools extract song.mp3 plain\n\n# Specify output path\nlrc_tools extract song.mp3 --output lyrics.lrc\n\n# Preview what would be written\nlrc_tools extract song.mp3 --dry-run\n```\n\nOutput is named `{stem}.{lang_2letter}.lrc` by default (e.g. `song.en.lrc`).\n\nWhen no `kind` is specified, timed (SYLT) is preferred over plain (USLT) when both are present. Use `timed` or `plain` to extract a specific type only.\n\n---\n\n### clean\n\nRemove SYLT/USLT frames from an MP3.\n\n```shell\n# Remove all lyrics frames\nlrc_tools clean song.mp3\n\n# Remove only timed (SYLT) or only plain (USLT) lyrics\nlrc_tools clean song.mp3 --timed-only\nlrc_tools clean song.mp3 --plain-only\n\n# Skip confirmation prompt\nlrc_tools clean song.mp3 --yes\n\n# Preview what would be removed\nlrc_tools clean song.mp3 --dry-run\n```\n\nConfirms before modifying by default. Use `--yes` or `-y` to skip.\n\n---\n\n### inspect\n\nInspect an MP3 or LRC file and print its type classification.\n\nCheck an MP3 file:\n\n```shell\nlrc_tools inspect song.mp3\n# TIMED+PLAIN: song.mp3\n# TIMED: song.mp3\n# PLAIN: song.mp3\n# NO_LYRICS: song.mp3\n```\n\nCheck an LRC file:\n\n```shell\nlrc_tools inspect lyrics.lrc\n# TIMED: lyrics.lrc\n# PLAIN: lyrics.lrc\n# NO_LYRICS: lyrics.lrc\n```\n\n\n## Bash completion\n\nA bash completion script is available by calling `lrc_tools completions`. It provides tab-completion for subcommands, flags (both short and long) and positional arguments like `.mp3` and `.lrc` files.\n\n### Requirements\n\nMake sure the `bash-completion` package is installed:\n\n```shell\n# Debian-based\nsudo apt install bash-completion\n\n# Fedora\nsudo dnf install bash-completion\n\n# Arch\nsudo pacman -S bash-completion\n\n# macOS (Homebrew)\nbrew install bash-completion\n```\n\n### Local install (per-user)\n\n```shell\nCOMPLETION_DIR=\"$HOME/.local/share/bash-completion/completions\"\nmkdir -p \"$COMPLETION_DIR\"\nlrc_tools completions \u003e \"$COMPLETION_DIR/lrc_tools\"\n```\n\n### Global install (system-wide)\n\n```shell\nlrc_tools completions | sudo tee /usr/share/bash-completion/completions/lrc_tools\n```\n\nRestart your shell to activate\n\n\u003e [!NOTE]\n\u003e If you rename the binary, the bash completion filename must match it.\n\u003e\n\u003e ```shell\n\u003e mv lrc_tools my-lyric-tool\n\u003e my-lyric-tool completions \u003e \"$COMPLETION_DIR/my-lyric-tool\"\n\u003e ```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpapernick%2Flrc_tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpapernick%2Flrc_tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpapernick%2Flrc_tools/lists"}