BS1770

A Rust library that implements ITU-R BS.1770-4 loudness measurement.

Also includes a binary that writes loudness to flac tags.

Example

let sample_rate_hz = 44_100;
let bits_per_sample = 16;
let channel_samples: [Vec<i16>; 2] = load_stereo_audio();

// When converting integer samples to float, note that the maximum amplitude
// is `1 << (bits_per_sample - 1)`, one bit is the sign bit.
let normalizer = 1.0 / (1_u64 << (bits_per_sample - 1)) as f32;

let channel_power: Vec<_> = channel_samples.iter().map(|samples| {
    let mut meter = bs1770::ChannelLoudnessMeter::new(sample_rate_hz);
    meter.push(samples.iter().map(|&s| s as f32 * normalizer));
    meter.into_100ms_windows()
}).collect();

let stereo_power = bs1770::reduce_stereo(
    channel_power[0].as_ref(),
    channel_power[1].as_ref(),
);

let gated_power = bs1770::gated_mean(stereo_power.as_ref());
println!("Integrated loudness: {:.1} LUFS", gated_power.loudness_lkfs());

Tagging flac files

There is a binary flacgain included in the examples directory, build it with

RUSTFLAGS="-C target-cpu=native" cargo build --release --example flacgain

Then run

target/release/examples/flacgain FILE...

The program accepts file names or more flac files as arguments, and computes loudness for them, as well as for the collection of files (which is assumed to be an album).

By default the program only prints loudness to stdout, add the --write-tags flag to also store loudness in the metadata tags. This adds the following tags:

• BS17704_TRACK_LOUDNESS
• BS17704_ALBUM_LOUDNESS

If any REPLAYGAIN_* tags exist, the program will remove these. The rationale for these tags, instead of using ReplayGain, is that ReplayGain has become ambigous: it stores a gain (the difference between target loudness and measured loudness), but different taggers use different reference levels, which means that ReplayGain only normalizes loudness when you carefull ensure that all files in your collection use the same target setting. By storing the loudness instead of the gain, sidestep the problem. By naming the tag after the particular loudness definition (BS.1770-4), future revisions of BS.1770 will not make these tags ambiguous.

The program writes a new file and moves it over the old file, so permission bits are currently lost. The program only replaces the VORBIS_COMMENT block and leaves any other parts of the file untouched. It uses copy_file_range to enable reflinking on file systems that support this.

If you have a collection of flac files, where every leaf directory contains a single album, you can use the included script tag_collection.sh to run flacgain --write-tags on every album in your collection.

Performance

The initial focus is on correctness, the library has not been optimized yet. There is a lot of potential for optimization, for example by combining filters, unrolling loops, applying vectorization, etc.

References

• ITU-R BS.1770-4, a standard that specifies how to measure loudness, and which defines the LKFS unit (loudness units full scale, K-weighted).
• ITU-R BS.1771-1 builds upon BS.1770 with a few requirements for building loudness meters.
• EBU R 128, which specifies a target loudness level, based on the BS.1770 loudness measurement.
• EBU Tech 3341, which specifies “EBU Mode” loudness meters, but which in particular provides test vectors to confirm that a meter implements BS.1770 correctly. It also proposes to move away from the term “LKFS” introduced in BS.1770, in favor of the term “LUFS”. K-weighting would be indicated elsewhere.
• EBU Tech 3342, which specifies how to measure loudness range.

Acknowledgements

• The filter coefficient formulas are adapted from pyloudnorm by Christian Steinmetz.
• The filter coefficient formulas are originally due to Brecht De Man, but the associated paper is not openly accessible.

License

BS1770 is licensed under the Apache 2.0 license. It may be used in free software as well as closed-source applications, both for commercial and non-commercial use under the conditions given in the license. If you want to use BS1770 in your GPLv2-licensed software, you can add an exception to your copyright notice. Please do not open an issue if you disagree with the choice of license.