Crate mp3rgain 

mp3rgain

Lossless MP3 volume adjustment library - a modern mp3gain replacement.

This library provides lossless MP3 volume adjustment by modifying the global_gain field in each frame’s side information.

Features

• Lossless: No re-encoding, preserves audio quality
• Fast: Direct binary manipulation, no audio decoding
• Compatible: Works with all MP3 files (MPEG1/2/2.5 Layer III)
• Reversible: Changes can be undone by applying negative gain

Optional Features

• replaygain: Enable ReplayGain analysis (requires symphonia)
  • Track gain calculation (-r flag)
  • Album gain calculation (-a flag)

Example

use mp3rgain::{apply_gain, apply_gain_db, analyze, GainOptions, Channel};
use std::path::Path;

// Simple gain adjustment: +2 steps (+3.0 dB)
let frames = apply_gain(Path::new("song.mp3"), 2).unwrap();
println!("Modified {} frames", frames);

// Or specify gain in dB directly
let frames = apply_gain_db(Path::new("song.mp3"), 4.5).unwrap();

// Builder pattern for advanced options
GainOptions::new(5)
    .wrap(true)
    .undo(true)
    .apply(Path::new("song.mp3")).unwrap();

// Channel-specific gain with undo support
GainOptions::new(3)
    .channel(Channel::Left)
    .undo(true)
    .apply(Path::new("song.mp3")).unwrap();

Modules

• analysis - MP3 file analysis and amplitude detection
• gain - Gain adjustment operations and the GainOptions builder
• ape - APEv2 tag reading, writing, and management
• replaygain - ReplayGain loudness analysis
• bs1770 - ITU-R BS.1770 loudness engine for the RG2/R128 modes (feature-gated)
• mp4meta - MP4/M4A metadata handling
• aac - AAC bitstream parsing (feature-gated)
• adts - Raw ADTS AAC streams (feature-gated)

Technical Details

Each gain step scales amplitude by 2^(1/4) ≈ 1.505 dB (fixed by MP3 specification). The global_gain field is 8 bits, allowing values 0-255.

Re-exports

pub use analysis::analyze;

pub use analysis::analyze_data;

pub use analysis::find_max_amplitude;

pub use analysis::gain_range;

pub use analysis::is_mono;

pub use analysis::ChannelMode;

pub use analysis::MaxAmplitudeResult;

pub use analysis::Mp3Analysis;

pub use analysis::MpegVersion;

pub use ape::delete_ape_tag;

pub use ape::read_ape_tag;

pub use ape::read_ape_tag_from_file;

pub use ape::write_ape_album_minmax;

pub use ape::write_ape_tag;

pub use ape::ApeItem;

pub use ape::ApeTag;

pub use ape::TAG_MP3GAIN_ALBUM_MINMAX;

pub use ape::TAG_MP3GAIN_MINMAX;

pub use ape::TAG_MP3GAIN_UNDO;

pub use ape::TAG_REPLAYGAIN_ALBUM_GAIN;

pub use ape::TAG_REPLAYGAIN_ALBUM_PEAK;

pub use ape::TAG_REPLAYGAIN_ALGORITHM;

pub use ape::TAG_REPLAYGAIN_TRACK_GAIN;

pub use ape::TAG_REPLAYGAIN_TRACK_PEAK;

pub use apply::apply_with_options;

pub use apply::predict_apply;

pub use apply::write_album_minmax;

pub use apply::write_replaygain_tags_only;

pub use apply::AacAlbumInfo;

pub use apply::ApplyOptions;

pub use apply::ApplyReport;

pub use apply::ClippingDetection;

pub use apply::TagsOnlyOptions;

pub use error::Error;

pub use error::Result;

pub use gain::apply_gain;

pub use gain::apply_gain_db;

pub use gain::apply_gain_to_peak;

pub use gain::db_to_linear;

pub use gain::db_to_steps;

pub use gain::peak_to_headroom_db;

pub use gain::peak_to_pcm_sample;

pub use gain::steps_to_db;

pub use gain::undo_gain;

pub use gain::would_clip;

pub use gain::Channel;

pub use gain::GainOptions;

pub use gain::GAIN_STEP_DB;

pub use gain::MAX_GAIN;

pub use id3v2::delete_id3v2_replaygain;

pub use id3v2::read_id3v2_replaygain;

pub use id3v2::undo_gain_id3v2;

pub use id3v2::write_id3v2_replaygain;

pub use id3v2::Id3v2ReplayGain;

Modules

aac

AAC bitstream parser for locating global_gain fields in M4A/MP4 files.

adts

Raw ADTS AAC stream support (issue #330).

analysis

ape

apply

Unified apply-gain pipeline shared between the CLI and GUI frontends.

bs1770

ITU-R BS.1770-4 integrated loudness measurement (K-weighting + gating).

error

Custom error types for mp3rgain.

gain

id3v2

ID3v2 TXXX frame storage for ReplayGain and undo tags.

mp4meta

MP4/M4A metadata handling for ReplayGain tags

replaygain

ReplayGain analysis module

Structs

StoredAlbumValues

One file’s stored RG1 values in album mode, from StoredGainTags::rg1_album_values.

StoredGainTags

Owned snapshot of the gain tags stored in one file, as returned by read_gain_tags_auto. None means the tag is absent (not an error).

Enums

GainTagSource

Tag store a StoredGainTags snapshot was read from.

TagLayout

Which container MP3 tags are written to.

Constants

ALBUM_GAIN_TOLERANCE_DB

Two stored REPLAYGAIN_ALBUM_GAIN values are “the same album” within this many dB: the 6-decimal tag format and mp3gain’s own rounding both stay well inside it.

SUPPORTED_EXTENSIONS

File extensions mp3rgain can process.

Functions

apply_gain_db_auto

Apply gain in dB, auto-dispatching by file format.

collect_audio_files

Collect supported audio file paths from a directory.

consistent_album_gain

The shared album gain and the loudest album peak across the members of one album, from each file’s stored (album_gain_db, album_peak), or None if the set is empty or the gains disagree by more than ALBUM_GAIN_TOLERANCE_DB. Stored values are residuals of each file’s current loudness, so a partial or inconsistent set cannot be mixed with a fresh analysis: any gap means the whole album gets rescanned (-s R, issue #298; GUI issue #302).

delete_gain_tags_auto

Delete ReplayGain / undo tags, auto-dispatching by file format and tag mode.

expand_audio_paths

Expand directories in paths into the supported audio files they contain (recursively), keeping plain file paths as they are and preserving input order. Shared by the CLI’s -R and the GUI’s folder drop / Add Folder, so the two agree on what a directory expands to.

is_supported_audio_path

Returns true if path is a regular audio file mp3rgain can process. Filters out macOS resource fork files (._*) and unsupported extensions.

read_gain_tags_auto

Read stored gain tags (ReplayGain plus mp3gain undo/minmax) without modifying the file, auto-dispatching by file format and tag mode.

read_undo_steps

Read the cumulative applied left-channel gain, in steps, without modifying the file — i.e. how much louder the file currently is than its original, which an undo would roll back.

undo_gain_auto

Undo previously-applied gain, auto-dispatching by file format and tag mode.