ReplayGain metaflac backend alters input files

Open Beginner friendly
#6,915 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
78/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Quiet
Tech stack
python
Domain
cli

Research direction

Start in beetsplug/replaygain.py at lines 709-733, focusing on the metaflac backend's ReplayGain write and read steps. Run the minimal import reproduction with copy enabled and inspect both the source and library files using metaflac --list. Done means the source file is unchanged while the copied library file still receives the ReplayGain tags.

Written by the indexing model from the issue text.

Description

replaygain
Problem

When using the ReplayGain plugin with the metaflac backend, the current implementation works in two parts:

  1. Write the ReplayGain tags to the input files (source: beetsplug/replaygain.py#L709-L712).
  2. Read the ReplayGain tags from the input files (source: beetsplug/replaygain.py#L714-L733).

This leads to altering the input files, which corrupts files that shouldn't be touched, especially when the input files are not in the final destination (e.g., during import).

metaflac can use --scan-replay-gain to read the ReplayGain tags without altering the input files (since FLAC 1.3.2, released on 01-Jan-2017 - discussed in https://github.com/beetbox/beets/issues/1203).

Using --scan-replay-gain instead of --add-replay-gain would fix this issue.

Minimal reproduction

  1. config.yaml:

    directory: /music
import:
  copy: yes
replaygain:
  auto: yes
  backend: metaflac

  2. Import a FLAC file with no ReplayGain tags:

    beet import /downloads/file.flac

  3. Check the ReplayGain tags on the copy beets created in the library: metaflac --list /music/.../file.flac - tags are present, as expected.

  4. Check the ReplayGain tags on the original file that was imported from: metaflac --list /downloads/file.flac - tags were also written here, unexpectedly.

Setup
  • OS: Debian GNU/Linux 13.6 (trixie) in a Visual Studio Devcontainer
  • Python version: 3.13.5
  • beets version: 2.13.1 (released on 29-Jul-2026)
  • Turning off plugins made problem go away (yes/no): N/A
AI disclaimer

I have used AI to help me write this issue report.

Dominant language
Python
Stars
15.7k
Forks
2.1k
Avg merge
3d 13h
Merged PRs (30d)
29

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from beetbox/beets

All issues in beetbox/beets

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.