Skip to content

fix: improve max amplitude detection and global_gain range#53

Merged
M-Igashi merged 1 commit intomasterfrom
fix/max-amplitude-issues
Jan 16, 2026
Merged

fix: improve max amplitude detection and global_gain range#53
M-Igashi merged 1 commit intomasterfrom
fix/max-amplitude-issues

Conversation

@M-Igashi
Copy link
Owner

Summary

Fixes #51 and partially addresses #52.

Changes

Issue #51: find_max_amplitude reports incorrect values

  • Fixed iterate_frames to skip Xing/Info VBR header frames

    • These frames contain metadata, not audio data
    • Their global_gain values (often 0) were incorrectly included in range calculation
    • Now matches mp3gain behavior
  • Added find_peak_amplitude function in replaygain.rs

    • Decodes audio using Symphonia to measure actual PCM peak values
    • Returns peak in normalized range (0.0-1.0+) and PCM scale (0-32768+)
  • Updated find_max_amplitude to use audio decoding

    • When replaygain feature is enabled, decodes audio for accurate peak measurement
    • Falls back to global_gain estimation when feature is disabled
  • Output format now shows Max PCM sample in 32768 scale

    • Compatible with mp3gain output format

Issue #52: MP3 peak value capped at 1.0

  • Root cause identified: Symphonia's MP3 decoder internally clamps output samples to [-1.0, 1.0] in synthesis.rs
  • Workaround implemented: Added warning for MP3 files when peak is at clipping threshold
    • Informs users that actual peak may be higher than reported
    • AAC/M4A files correctly report peaks > 1.0 (no warning needed)

Testing

Tested with various MP3 and M4A files:

# MP3 file (clipping warning shown)
$ mp3rgain -x file.mp3
  Max PCM sample: 32768.000000
    (may be clipped - actual peak could be higher)
  Max global_gain: 182
  Min global_gain: 110

# M4A file (no warning, correct peak > 32768)
$ mp3rgain -x file.m4a
  Max PCM sample: 41531.960938
  Headroom: -2.06 dB

Limitations

Issue #52 cannot be fully resolved without modifying Symphonia's MP3 decoder. The decoder's clamp at [-1.0, 1.0] is a design decision in symphonia-bundle-mp3/src/synthesis.rs:

*o = s.clamp(-1.0, 1.0);

Potential future solutions:

  1. Submit a PR to Symphonia to add an option for unclamped output
  2. Use a different MP3 decoder that doesn't clamp

- Fix iterate_frames to skip Xing/Info VBR header frames
  This matches mp3gain behavior and reports correct global_gain range

- Add find_peak_amplitude function in replaygain.rs
  Decodes audio using Symphonia to measure actual PCM peak values

- Update find_max_amplitude to use audio decoding when replaygain feature enabled
  Falls back to global_gain estimation when feature is disabled

- Add clipping warning for MP3 files when peak is at 1.0
  Symphonia's MP3 decoder clips samples to [-1.0, 1.0], so peaks > 1.0 cannot
  be detected. Warning informs users that actual peak may be higher.

- Output Max PCM sample in 32768 scale (mp3gain compatible)

Note: Issue #52 (MP3 peak capping) is a Symphonia limitation where the decoder
clamps output samples. AAC/M4A files correctly report peaks > 1.0.
@M-Igashi M-Igashi merged commit 46857dd into master Jan 16, 2026
9 checks passed
@M-Igashi M-Igashi deleted the fix/max-amplitude-issues branch January 16, 2026 20:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

find_max_amplitude (-x) does not decode audio, reports incorrect values

1 participant