Skip to content

replaygain: add metaflac backend#6800

Open
SamadBallaj1 wants to merge 3 commits into
beetbox:masterfrom
SamadBallaj1:fix-issue-1203
Open

replaygain: add metaflac backend#6800
SamadBallaj1 wants to merge 3 commits into
beetbox:masterfrom
SamadBallaj1:fix-issue-1203

Conversation

@SamadBallaj1

@SamadBallaj1 SamadBallaj1 commented Jun 28, 2026

Copy link
Copy Markdown

Closes #1203

The replaygain plugin can't compute ReplayGain when metaflac is the only tool available. The existing backends (command, gstreamer, audiotools, ffmpeg) each need something heavier installed, which doesn't work on minimal setups like a NAS where those won't install. Issue #1203 asks for a metaflac based option so FLAC users on those setups can still tag ReplayGain.

This adds a metaflac backend for that case. It runs metaflac --add-replay-gain to compute the gain and reads the values back with metaflac --show-tag. I modeled it on the existing CommandBackend since both wrap an external tool. It only handles FLAC, skips other formats, and shifts the gain to the configured targetlevel like the other backends.

One limitation: metaflac scans a whole album in one pass, so the files of an album need the same sample rate and channel layout.

Before, selecting the metaflac backend failed:

$ beet replaygain
UserError: Selected ReplayGain backend metaflac is not supported.

After, the backend works and the plugin tests pass:

$ python -m pytest test/plugins/test_replaygain.py
7 passed, 4 skipped

The 4 skipped are the Opus R128 cases, which don't apply to the metaflac path.

To Do

  • Documentation.
  • Changelog.
  • Tests.

@SamadBallaj1 SamadBallaj1 requested a review from a team as a code owner June 28, 2026 23:25
@github-actions github-actions Bot added the replaygain replaygain plugin label Jun 28, 2026
@codecov

codecov Bot commented Jun 28, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 83.92857% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 75.47%. Comparing base (0fd0e82) to head (2d354c2).
✅ All tests successful. No failed tests found.

Files with missing lines Patch % Lines
beetsplug/replaygain.py 83.92% 6 Missing and 3 partials ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##           master    #6800      +/-   ##
==========================================
+ Coverage   74.88%   75.47%   +0.58%     
==========================================
  Files         163      163              
  Lines       20998    21054      +56     
  Branches     3307     3312       +5     
==========================================
+ Hits        15725    15890     +165     
+ Misses       4519     4393     -126     
- Partials      754      771      +17     
Files with missing lines Coverage Δ
beetsplug/replaygain.py 46.58% <83.92%> (+20.25%) ⬆️

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

@SamadBallaj1 SamadBallaj1 force-pushed the fix-issue-1203 branch 3 times, most recently from 5b41a28 to 345b72f Compare June 29, 2026 12:59
@SamadBallaj1

Copy link
Copy Markdown
Author

Pushed some updates, this is ready for review whenever you have a chance. Thanks.

@snejus snejus left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Looks good, have you tested it yourself?

Comment thread beetsplug/replaygain.py Outdated
Comment on lines +686 to +687
for item in task.items:
if self.format_supported(item):

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Suggested change
for item in task.items:
if self.format_supported(item):
for item in filter(self.format_supported, task.items):

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

Yes. I ran it locally on a FLAC file with the metaflac backend and it wrote the correct ReplayGain tags (track gain got arund -11.5 dB, peak close to 1.0). The metaflac tests also pass on my machine.



class MetaflacBackendMixin(BackendMixin):
plugin_config: ClassVar[dict[str, Any]] = {"backend": "metaflac"}

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Would you mind installing flac in this part of the workflow, in ci.yaml?

      - name: Install system dependencies on Ubuntu

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

Thanks @snejus for the review. I updated the track loop to use filter like you suggested and also added flac to the Ubuntu deps so the metaflac tests run on CI. All clear now, both pushed.

@SamadBallaj1 SamadBallaj1 requested a review from snejus July 5, 2026 19:02
Add a MetaflacBackend that computes ReplayGain for FLAC files with metaflac --add-replay-gain and reads the values back with --show-tag. Only FLAC is supported. Includes docs, a changelog entry, and tests.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

replaygain replaygain plugin

Projects

None yet

Development

Successfully merging this pull request may close these issues.

replaygain: metaflac backend

2 participants