Skip to content

lyrics: Write lyrics to sidecar files (.lrc/.txt) - #7117

Open
arsaboo wants to merge 7 commits into
beetbox:masterfrom
arsaboo:lyrics-sidecar-files
Open

arsaboo wants to merge 7 commits into
beetbox:masterfrom
arsaboo:lyrics-sidecar-files

Conversation

@arsaboo

@arsaboo arsaboo commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

Description

Adds optional sidecar lyrics files to the lyrics plugin, for players and servers that read lyrics from a file next to the track instead of from tags (Jellyfin, Plexamp, mpv, many DAPs).

Usage

lyrics:
   write_files: no        # write .lrc/.txt next to each track
   remove_embedded: no    # delete the lyrics tags afterwards
beet lyrics --write-files              # fetch and write files
beet lyrics --local --write-files      # back-fill existing lyrics, no network
beet lyrics --local --write-files --remove-embedded   # move tags -> files
  • Fixes Lyrics: Allow using sidecar files (.lrc) for lyrics #6396; supersedes the approach in POC lyrics to txt #6698 (same-stem files rather than slugified names in a separate directory).

  • .lrc when the lyrics are synced, .txt when they are not.

  • The file is named exactly like the audio file and written next to it, since that is how players look for it.

  • Lyrics already stored in the database are published as well, so an existing library can be migrated offline with --local --write-files.

  • A file that already holds the same lyrics is left untouched.

  • remove_embedded clears USLT and SYLT once the file has the lyrics. Tags that hold different lyrics are kept, and a warning is logged, so lyrics that exist nowhere else are never lost. The database keeps the lyrics either way.

  • Both options default to no, so current behavior is unchanged.

  • Documentation. (If you've added a new command-line flag, for example, find the appropriate page under docs/ to describe it.)

  • Changelog. (Add an entry to docs/changelog.rst to the bottom of one of the lists near the top of the document.)

  • Tests. (Very much encouraged but not strictly required.)

@arsaboo
arsaboo requested a review from a team as a code owner October 27, 2026 20:21
Copilot AI balanced review requested due to automatic review settings October 27, 2026 20:21
@github-actions github-actions Bot added the lyrics lyrics plugin label Oct 27, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Writing lyrics can overwrite unrelated on-disk tags with database values, while unhandled directory-creation errors can prevent later tracks from being processed.

2 open issues
What changed in this PR

grug sees lyrics plugin gain optional sidecar files for players that read lyrics beside tracks. This addresses #6396 with same-stem files, rather than the separate-directory approach in #6698.

Changes:

  • Add .lrc and .txt output, including offline export of existing lyrics.
  • Add optional embedded-lyrics removal after sidecar writing, with checks for differing lyrics.
  • Add documentation and tests for file writing, tag removal, and timestamp conversion.
File Description
test/​util/​test_lyrics.py Test SYLT-to-LRC conversion and timestamp precision.
test/​plugins/​test_lyrics.py Test sidecar output, tag removal, failures, and command options.
docs/​plugins/​lyrics.rst Explain sidecar options, offline export, and tag handling.
docs/​changelog.rst Announce optional lyrics sidecar files.
beetsplug/​lyrics.py Add sidecar writing and guarded embedded-lyrics removal.
beets/​util/​lyrics.py Add SYLT-to-LRC timestamp formatting.

Review effort: Balanced

Comment thread beetsplug/lyrics.py Resolved
Comment thread beetsplug/lyrics.py Resolved
@codecov

codecov Bot commented Oct 27, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 88.67925% with 12 lines in your changes missing coverage. Please review.
✅ Project coverage is 81.04%. Comparing base (ee6e08a) to head (ce0435b).
✅ All tests successful. No failed tests found.

Files with missing lines Patch % Lines
beetsplug/lyrics.py 87.50% 8 Missing and 4 partials ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##           master    #7117      +/-   ##
==========================================
+ Coverage   81.02%   81.04%   +0.01%     
==========================================
  Files         150      150              
  Lines       21228    21326      +98     
  Branches     3242     3257      +15     
==========================================
+ Hits        17201    17284      +83     
- Misses       3212     3226      +14     
- Partials      815      816       +1     
Files with missing lines Coverage Δ
beets/util/lyrics.py 97.16% <100.00%> (+0.23%) ⬆️
beetsplug/lyrics.py 89.29% <87.50%> (-0.42%) ⬇️

... and 3 files with indirect coverage changes

🚀 New features to boost your workflow:
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@arsaboo

arsaboo commented Nov 15, 2026

Copy link
Copy Markdown
Contributor Author

@snejus lrclib fixture refreshed (that test passes now). google-lyricsontop fails because lyricsontop.com is expired, so I removed the page for now.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Clearing all SYLT frames after comparing only the first can delete lyrics from additional frames that were never copied to the sidecar.

3 open issues
2 resolved since last review

Review effort: Balanced

Comment thread beetsplug/lyrics.py Resolved
Comment thread beetsplug/lyrics.py Resolved
Comment thread beetsplug/lyrics.py Resolved
Remove the embedded lyrics through mediafile instead of Item.write(),
which writes every database media field and could overwrite unrelated
tags on disk.

Also catch FilesystemError, which mkdirall() raises for bytes paths, so
that one unwritable track does not stop the whole command.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Embedded-lyrics removal can delete uncopied USLT frames, while timestamps at 100 minutes or beyond fail to round-trip and can lose synchronized entries.

2 open issues
3 resolved since last review

Review effort: Balanced

Comment thread beetsplug/lyrics.py Resolved
Comment thread beets/util/lyrics.py Resolved
@arsaboo
arsaboo force-pushed the lyrics-sidecar-files branch from 3ae9b5a to ce0435b Compare November 16, 2026 12:55

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

lyrics lyrics plugin

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Lyrics: Allow using sidecar files (.lrc) for lyrics

2 participants