lyrics: write synced LRC lyrics to SYLT ID3 frame by benstev1 · Pull Request #6566 · beetbox/beets

benstev1 · 2026-04-21T21:24:26Z

When the lyrics plugin writes LRC-formatted (timestamped) lyrics to an ID3-tagged audio file, store the timing data in the SYLT (synchronized lyrics) frame and plain text in USLT, rather than writing raw LRC text verbatim to USLT.

Fixes #6541

Description

This PR:

Adds a Lyrics.sylt property that converts [mm:ss.cc] LRC lines to (text, milliseconds) pairs for use with the ID3v2 SYLT frame.
After writing via item.try_write(), opens the file with mutagen to replace USLT with clean plain text and write a proper SYLT frame.
Clears any stale SYLT frame when lyrics become unsynced.
Non-ID3 formats (FLAC, OGG, etc.) are silently skipped.

(...)

To Do

Documentation.
Changelog.
Tests.

When the lyrics plugin writes LRC-formatted (timestamped) lyrics to an ID3-tagged audio file, store the timing data in the SYLT (synchronized lyrics) frame and plain text in USLT, rather than writing raw LRC text verbatim to USLT. Fixes beetbox#6541

…nk line

codecov · 2026-04-21T21:57:06Z

Codecov Report

❌ Patch coverage is 94.11765% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 72.69%. Comparing base (da16db1) to head (de8cbfa).

Files with missing lines	Patch %	Lines
beets/util/lyrics.py	92.85%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #6566      +/-   ##
==========================================
+ Coverage   72.46%   72.69%   +0.23%     
==========================================
  Files         161      161              
  Lines       20719    20735      +16     
  Branches     3280     3283       +3     
==========================================
+ Hits        15014    15074      +60     
+ Misses       4979     4934      -45     
- Partials      726      727       +1

Files with missing lines	Coverage Δ
beetsplug/lyrics.py	`87.42% <100.00%> (+8.72%)`	⬆️
beets/util/lyrics.py	`96.73% <92.85%> (-0.70%)`	⬇️

... and 1 file 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.

snejus · 2026-04-21T22:34:08Z

Have you considered adding support for this tag to mediafile first?

benstev1 · 2026-04-22T18:04:21Z

Went ahead and implemented these. Heres a breakdown:

-- do we have another option than hardcoding english for everything?
fixed in the latest commit. Changed lang="eng" to lang="XXX" (ISO 639-2 for "undetermined") for both the USLT and SYLT frames. This is actually what the upstream mediafile library itself does for USLT

-- you should log the error here, completely ignoring it will make debugging harder
Also fixed, added a module-level log = logging.getLogger(name) using beets' own logging wrapper and changed the bare except: pass to except Exception as exc: log.warning(...).

-- would it make sense to move this into beet's main tag-writing function? / Have you considered adding support to mediafile first?
The mediafile library has no SYLT support at all, no storage class, no field, so there's nothing to hook into yet. The proper long-term fix would be a separate PR to the upstream mediafile repo adding a synced_lyrics = MediaField(MP3SYLTStorageStyle(...)) field, after which the lyrics plugin could simply set item.synced_lyrics = lyrics.sylt and let the normal write path handle it. Would be a larger undertaking but something that should be implemented in the future.

snejus · 2026-04-22T18:36:45Z

The mediafile library has no SYLT support at all, no storage class, no field, so there's nothing to hook into yet. The proper long-term fix would be a separate PR to the upstream mediafile repo adding a synced_lyrics = MediaField(MP3SYLTStorageStyle(...)) field, after which the lyrics plugin could simply set item.synced_lyrics = lyrics.sylt and let the normal write path handle it. Would be a larger undertaking but something that should be implemented in the future.

Ultimately, writing tags is mediafile's responsibility, and thus I'm not comfortable with lyrics plugin taking some of this responsibility here, especially given how complex the plugin is already.

Would you be happy to add support for SYLT to mediafile, even if it's a larger undertaking?

benstev1 · 2026-04-22T18:53:28Z

I'll give it a go!

snejus · 2026-04-22T19:09:00Z

Thank you so much!

benstev1 · 2026-04-22T19:39:08Z

Ok I opened a PR in mediafile with the changes. Wasn't as difficult as it looked so I got it done pretty quickly. Its issue #108 in the mediafile repo if you'd like to take a look. If everything looks good there I'll update this PR to accommodate it and we can go from there!

benstev1 · 2026-04-22T22:22:40Z

Ok it looks like everything is working end to end. Both PR's are up to date. Let me know if there are any more changes that need to be made.

Copilot

Pull request overview

This PR try make lyrics plugin write synced LRC better for ID3: put timing in SYLT, keep plain text for USLT, so more players show lyrics right.

Changes:

Add Lyrics.sylt to convert [mm:ss.cc] LRC lines into (text, milliseconds) pairs.
Change lyrics plugin write path to store plain text in item.lyrics and pass synced_lyrics tag data when writing.
Update docs/changelog and add tests for SYLT conversion + write-call behavior.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
`beets/util/lyrics.py`	Add `Lyrics.sylt` property to derive SYLT timing tuples from LRC timestamps.
`beetsplug/lyrics.py`	Adjust `add_item_lyrics` to split plain vs synced timing and pass `synced_lyrics` via `try_write()`.
`test/plugins/test_lyrics.py`	Update overwrite expectation for synced lyrics + add new unit tests for `Lyrics.sylt` and write kwargs.
`docs/plugins/lyrics.rst`	Document SYLT/USLT behavior for synced lyrics on ID3 files.
`docs/changelog.rst`	Add changelog entry for SYLT/USLT behavior change.

        if lyrics_text not in {None, item.lyrics}:
            item.lyrics = lyrics_text
            item.store()
            if write:
-                item.try_write()
+                item.try_write(tags={"synced_lyrics": sylt_data})


+class TestSyncedLyricsWrite(LyricsPluginMixin):
+    """Tests that add_item_lyrics passes the correct synced_lyrics tag."""
+
+    SYNCED_LRC = "[00:01.00] hello\n[00:02.00] world"
+
+    @pytest.fixture
+    def backend_name(self):
+        return "lrclib"
+
+    def test_sylt_data_passed_for_synced_lyrics(
+        self, monkeypatch, helper, lyrics_plugin
+    ):
+        monkeypatch.setattr(
+            lyrics_plugin, "find_lyrics", lambda _: Lyrics(self.SYNCED_LRC)
+        )
+        item = helper.create_item(id=1, lyrics="")
+        calls = []
+        monkeypatch.setattr(
+            type(item), "try_write", lambda self, **kw: calls.append(kw) or True
+        )
+
+        lyrics_plugin.add_item_lyrics(item, write=True)
+
+        assert calls == [
+            {"tags": {"synced_lyrics": [("hello", 1000), ("world", 2000)]}}
+        ]
+
+    def test_plain_text_stored_in_lyrics_for_synced(
+        self, monkeypatch, helper, lyrics_plugin
+    ):
+        monkeypatch.setattr(
+            lyrics_plugin, "find_lyrics", lambda _: Lyrics(self.SYNCED_LRC)
+        )
+        item = helper.create_item(id=1, lyrics="")
+        monkeypatch.setattr(type(item), "try_write", lambda self, **kw: True)
+
+        lyrics_plugin.add_item_lyrics(item, write=True)
+
+        assert item.lyrics == "hello\nworld"
+
+    def test_sylt_cleared_for_plain_lyrics(
+        self, monkeypatch, helper, lyrics_plugin
+    ):
+        monkeypatch.setattr(
+            lyrics_plugin, "find_lyrics", lambda _: Lyrics("plain lyrics")
+        )
+        item = helper.create_item(id=1, lyrics="")
+        calls = []
+        monkeypatch.setattr(
+            type(item), "try_write", lambda self, **kw: calls.append(kw) or True
+        )
+
+        lyrics_plugin.add_item_lyrics(item, write=True)
+
+        assert calls == [{"tags": {"synced_lyrics": None}}]


snejus · 2026-04-24T19:12:26Z

Now that mediafile is released, update the requirement in pyproject.toml and run uv tool run 'poetry<2' lock.

Resolve whichever @ShimmerGlass's and Copilot's comments you've addressed, and I will have a final look then.

… to 0.17.0

snejus · 2026-05-21T20:08:36Z

@benstev1 are you planning to come back to this by any chance?

benstev1 · 2026-05-21T23:43:37Z

Sorry about that yeah i'll come back and tackle this. My term ended for school and I forgot about it.

…lock

snejus · 2026-05-22T11:41:39Z

No worries!

Regarding poetry.lock, I would suggest

git checkout master poetry.lock
uv tool run 'poetry<2' lock

my comments were answered

benstev1 · 2026-05-22T19:09:55Z

All I did was run the command you posted and I'm failing a doc check? Its not something I've seen before its asking for a 'line_length' positional arg, do you know how to fix this?

snejus · 2026-05-22T19:27:49Z

Just fixed poetry.lock. Will have a look at the docs failure soon

snejus

Looks good, just a pair of small comments

snejus · 2026-05-22T19:39:32Z

+        for ts, text in self._split_lines:
+            if not ts:
+                continue
+            ts_m = re.match(r"\[(\d{2}):(\d{2})\.(\d{2})\]", ts)


Compile this pattern as the class attribute so that it's reused.

snejus · 2026-05-22T19:46:49Z

+                minutes = int(ts_m[1])
+                seconds = int(ts_m[2])
+                centiseconds = int(ts_m[3])


I think you can reduce this to

Suggested change

minutes = int(ts_m[1])

seconds = int(ts_m[2])

centiseconds = int(ts_m[3])

m, s, cs = map(int, ts_m.groups())

benstev1 requested a review from a team as a code owner April 21, 2026 21:24

github-actions Bot added the lyrics lyrics plugin label Apr 21, 2026

Fix formatting: resolve changelog merge conflict and remove extra bla…

dc0a0bf

…nk line

benstev1 force-pushed the feat/sylt-synchronized-lyrics branch from 72bca2f to dc0a0bf Compare April 21, 2026 21:37

Fix docstrfmt line wrapping in changelog and lyrics docs

1b7b7a2

benstev1 force-pushed the feat/sylt-synchronized-lyrics branch from 2dab9c0 to 1b7b7a2 Compare April 21, 2026 21:43

Move SYLT changelog entry to Unreleased section

f472389

ShimmerGlass previously requested changes Apr 21, 2026

View reviewed changes

Comment thread beetsplug/lyrics.py Outdated

Comment thread beetsplug/lyrics.py Outdated

Comment thread beetsplug/lyrics.py Outdated

Address review: use XXX lang code, log save errors

26759b9

benstev1 force-pushed the feat/sylt-synchronized-lyrics branch from 30026c3 to 26759b9 Compare April 22, 2026 18:00

Use mediafile synced_lyrics field instead of _write_sylt_to_id3

78d9f89

benstev1 force-pushed the feat/sylt-synchronized-lyrics branch from d9b659a to 78d9f89 Compare April 22, 2026 22:11

fix: ruff formatting and lint errors

edb1934

benstev1 force-pushed the feat/sylt-synchronized-lyrics branch from 655b409 to edb1934 Compare April 22, 2026 22:14

snejus requested a review from Copilot April 24, 2026 09:53

Copilot started reviewing on behalf of snejus April 24, 2026 09:53 View session

Copilot AI reviewed Apr 24, 2026

View reviewed changes

fix: keep LRC in DB, pass plain text to USLT via tags, bump mediafile…

c9b1bae

… to 0.17.0

benstev1 force-pushed the feat/sylt-synchronized-lyrics branch from e62466c to c9b1bae Compare April 24, 2026 20:41

fix: ruff line length

d20c916

benstev1 force-pushed the feat/sylt-synchronized-lyrics branch from 193b777 to d20c916 Compare April 24, 2026 20:44

snejus reviewed Apr 25, 2026

View reviewed changes

Comment thread poetry.lock

benstev1 added 4 commits May 21, 2026 19:48

fix: keep LRC in USLT, simplify synced_lyrics write path, fix poetry.…

85d5509

…lock

merge: resolve changelog and poetry.lock conflicts with master

fc8217f

fix: regenerate poetry.lock after merge with master

21b1906

fix: move SYLT changelog entry to Unreleased section

fc4a3fc

benstev1 and others added 2 commits May 22, 2026 15:04

Fixed Poetry lock

b09b01e

Merge branch 'master' into feat/sylt-synchronized-lyrics

d9ef72c

Update poetry.lock

de8cbfa

snejus requested changes May 22, 2026

View reviewed changes

Conversation

benstev1 commented Apr 21, 2026

Description

To Do

Uh oh!

codecov Bot commented Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

snejus commented Apr 21, 2026

Uh oh!

benstev1 commented Apr 22, 2026

Uh oh!

snejus commented Apr 22, 2026

Uh oh!

benstev1 commented Apr 22, 2026

Uh oh!

snejus commented Apr 22, 2026

Uh oh!

benstev1 commented Apr 22, 2026

Uh oh!

benstev1 commented Apr 22, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

snejus commented Apr 24, 2026

Uh oh!

Uh oh!

snejus commented May 21, 2026

Uh oh!

benstev1 commented May 21, 2026

Uh oh!

snejus commented May 22, 2026

Uh oh!

benstev1 commented May 22, 2026

Uh oh!

snejus commented May 22, 2026

Uh oh!

snejus left a comment

Choose a reason for hiding this comment

Uh oh!

snejus May 22, 2026

Choose a reason for hiding this comment

Uh oh!

snejus May 22, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

codecov Bot commented Apr 21, 2026 •

edited

Loading