beetbox / beetbox/beets

ReplayGain metaflac backend alters input files

Open Beginner friendly
#6,915 0 comments 0 reactions 0 assignees View on GitHub
replaygain
Dominant language
Python
Stars
15.7k
Forks
2.1k
Avg merge
4d 21h
Merged PRs (30d)
31

Description

### Problem

When using the [ReplayGain](https://beets.readthedocs.io/en/stable/plugins/replaygain.html) plugin with the [metaflac backend](https://beets.readthedocs.io/en/stable/plugins/replaygain.html#metaflac), the [current implementation](https://github.com/beetbox/beets/pull/6800) works in two parts:

1. Write the ReplayGain tags to the input files (source: [beetsplug/replaygain.py#L709-L712](https://github.com/beetbox/beets/blob/74c2d98ee5c30d6dd6d4ffd4e6389984827a9f02/beetsplug/replaygain.py#L709-L712)).
2. Read the ReplayGain tags from the input files (source: [beetsplug/replaygain.py#L714-L733](https://github.com/beetbox/beets/blob/74c2d98ee5c30d6dd6d4ffd4e6389984827a9f02/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](https://xiph.org/flac/changelog.html#flac-132-01-jan-2017), released on 01-Jan-2017 - discussed in ).

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

### Minimal reproduction

1. `config.yaml`:

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

2. Import a FLAC file with no ReplayGain tags:

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

Contributor guide

Open the contributing guide

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.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.