Skip to content

lyrics: add --url option to fetch lyrics from a given URL - #7102

Open
jenish0908 wants to merge 1 commit into
beetbox:masterfrom
jenish0908:fix/6439-lyrics-url
Open

jenish0908 wants to merge 1 commit into
beetbox:masterfrom
jenish0908:fix/6439-lyrics-url

Conversation

@jenish0908

@jenish0908 jenish0908 commented Oct 13, 2026 •

Copy link
Copy Markdown

Description

Fixes #6439.

Adds a --url option to the lyrics command so lyrics can be fetched from a specific URL when the search picks the wrong match (e.g. several LRCLib records for one song):

beet lyrics -f --url https://lrclib.net/api/get/26627014 disco chaos

This picks up from #6548 and follows the review feedback there:

  • The option is --url and is read via self.config["url"]. The item is not modified up front; lyrics_url is only stored once lyrics are actually fetched, like for any other match.
  • Instead of special-casing LRCLib, each backend now declares which URLs it can handle (URL_PAT / handles_url) and how to fetch them (fetch_url). The URL goes through that backend's normal parsing, so raw HTML is never stored as lyrics:
    • lrclib: https://lrclib.net/api/get/<id> (the source URL beets already prints)
    • genius, tekstowo, musixmatch: their lyrics pages, via the existing scrape()
    • lrcmux: its configured /get?... URL
    • google doesn't claim any URLs since it scrapes arbitrary sites.
  • If the URL doesn't belong to any enabled source, the command fails with an error listing the enabled sources. There is no silent fallback to the regular search.
  • Since a URL points at a single song, the command errors out if the query matches more than one track.

The existing fetch() methods of the scraping backends and lrcmux now delegate to fetch_url(), so search results and explicit URLs share one code path.

A couple of behaviours worth flagging for review:

  • --url does not imply -f, so existing lyrics are kept unless -f is passed (consistent with the other options). Happy to change this if you'd prefer --url to force.
  • For LRCLib, the duration ranking is skipped for an explicit URL, but synced lyrics whose last timestamp runs past the track length are still dropped in favour of plain lyrics, same as today.

AI disclosure: I used Claude Code to help implement this and write the tests, following the approach I proposed in the issue. I reviewed and tested all the changes myself.

To Do

  • Documentation.
  • Changelog.
  • Tests.

Let each backend recognise URLs it can fetch lyrics from directly, so
that a URL is parsed by the backend that owns it. Unrecognised URLs and
queries matching more than one track are rejected.

Fixes beetbox#6439
@jenish0908
jenish0908 requested a review from a team as a code owner October 13, 2026 09:39
@github-actions github-actions Bot added the lyrics lyrics plugin label Oct 13, 2026
@codecov

codecov Bot commented Oct 13, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 79.53%. Comparing base (18967aa) to head (6689be1).
✅ All tests successful. No failed tests found.

Additional details and impacted files
@@            Coverage Diff             @@
##           master    #7102      +/-   ##
==========================================
+ Coverage   79.26%   79.53%   +0.26%     
==========================================
  Files         149      149              
  Lines       21216    21254      +38     
  Branches     3276     3283       +7     
==========================================
+ Hits        16817    16904      +87     
+ Misses       3585     3537      -48     
+ Partials      814      813       -1     
Files with missing lines Coverage Δ
beetsplug/lyrics.py 92.45% <100.00%> (+9.24%) ⬆️

... and 2 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.

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: force / use a specific URL for lyrics

1 participant