## R128GAIN

Copyright © 2011-2014 by Peter Belkner (http://home.snafu.de/pbelkner/)

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

R128GAIN is a FFmpeg and SoX based EBU R128 compliant loudness scanner. It helps you normalizing the loudness of your audio and video files to the same level.

Home: |  | http://r128gain.sourceforge.net/
Project: |  | http://sourceforge.net/projects/r128gain/
Download: |  | http://sourceforge.net/projects/r128gain/files/r128gain/1.0/
For playback see also: |  | http://in-ffsox.sourceforge.net/

### Content

1. History
2. Upgarde to Full FFmpeg
3. Usage
4. Applying the Gain
5. Command Line Syntax
6. Building from Scratch
7. Test Cases
8. Why You Won't Post at Hydrogenaudio Forum

### 1. History

2014-10-04 | 1.0.10 | Made R128GAIN compatible with the latest FFmpeg (cf. changed FFmpeg ABI).
2014-05-18 | 1.0.8 |

- Configuration files `"wingui.ini"` and `"gtkgui.ini"`, respectively, per user (i.e. not global any longer).
  Note: You have to reconfigure the application because the old configuration is lost.
- Dynamically link to `
  ` which is nowadays needed by `
  `

2014-03-30 | 1.0.6 |

- Reimplemented remuxing according to the respective FFmpeg example.

2013-12-20 | 1.0.5 |

- Fixed a subtle yet setious bug letting R128GAIN crash under certain circumstances.
- Reverted back to avutil-52 (i.e. being compatible with Zeranoe's FFmpeg builds again).

2013-12-18 | 1.0.4 |

- Support for multiple frames in a FFmpeg packet.
- Support for bumped avutil-53 (instead of avutil-52 as before).
- Added a "Building from Scratch" section to the documentation.

2013-11-30 | 1.0.3 |

- Added a command option preset supporting applying the gain to video files.
- Removed a restriction with respect to editing the command option on the native Windows GUI.
- Added a section on how to apply the gain by using the command option to the documentation.
- Added "Why You Won't Post at Hydrogenaudio Forum" to the documentation.

2013-11-18 | 1.0.2 |

- Adapt build process to latest FFmpeg.
- SoX with FLAC 1.3.0.
- SoX with WavPack 4.70.0.
- Fixed "Failed opening 'r128gain-tools/liblibMagickCore-6.Q16.so'" bug on Linux.

2013-08-07 | 1.0.1 |

- AVFMT_FLAG_GENPTS by default brings back smooth conversion to MKV for various broken VOBs.
- Minor fixes.
- No support via HA forum any longer.

2013-07-14 | 1.0 |

- Various fixes and improvements.

2012-10-14 | 1.0-α-6 |

- Added ATSC A/85 support.
- Added ReplayGain2 support.
- Added an option `"--reference"` in order to define the reference loudness (EBU R128: -23 LUFS).
- Added an option `"--db"` in order to force dB as unit instead of LU/TP.
- Added an option `"--quiet"` in order to suppress any writing to stdout.
- Fixed loading `"libsox.so.1"`.
- Fixed overwriting of files.

2012-08-17 | 1.0-α-4 |

- The core library `"lib1770"` was restructured in order to avoid duplicated computations. Scanning the EBU R128 test vector demonstrates that there is performance boost of about 40% (without true peak computation).
- The new `"lib1770"` now supports parallel computations. As demonstrated by the multithreaded `"example2"` program compared to sequential `"example1"` program parallelism may give another performance boost of about 50% (not yet used by `R128GAIN`).

2012-08-15 | 1.0-α-3 |

- Added `"--ffmpeg"` and `"--sox"` command line options in order to allow for providing the path to the respective shared libraries.
- Fixed missing the `"TP"`, `"TPDB"`, `"AP"`, and `"APDB"` environment variables.

2012-05-27 | 1.0-α-2 |

- Added a CLI (command line) only version (i.e. without GUI.)
- Provided Linux 64 bit builds.
- Fixed crashing CLI on Windows XP.

2012-05-18 | 1.0-α-1 |

- Unicode/UTF16 support for Win32.
- GTK2 and GTK3 GUIs for Linux.
- GTK2 GUI for Win32.
- No static buffers any longer.
- 75% rewrite (BS.1770 algorithm unchanged).

2012-04-06 | 0.9.7 | Added an option to the command line (`--tags=[rg|bwf]`) and the GUI (drop down box) for letting R128GAIN write BWF tags instead of ReplayGain tags. The following BWF tags are currently supported (depending on the format they may appear converted to upper case):

- LoudnessValue
- LoudnessRange
- MaxTruePeakLevel

2012-03-18 | 0.9.6-3 |

- Fixes a bug that under certain circumstances a file was written twice.
- Upgraded to SoX 14.4.0.

2012-02-11 | 0.9.6 |

- According to FFmpeg.org: FFmpeg development has gone into OVERDRIVE. As a consequence R128GAIN wasn't compiling any longer using the latest FFmpeg versions. This release ports R128GAIN to the latest FFmpeg API.
- Added a command line and GUI option to allow choosing between the EBU R128-2 (current, dating from 2011) and EBU R128-1 (former, dating from 2010) standards.
- The release requires `"avformat-54.dll"` and `"avcodec-54.dll"`, and is now again in line with the latest FFmpeg builds from http://ffmpeg.zeranoe.com/builds/win32/shared/.

2012-02-07 | 0.9.5 |

- Fixed a bug in 0.9.4 that only either the loudness or the loudness range could be computed but not both together.

2012-02-04 | 0.9.4 |

- Implemented the EBU R128 loudness range (LRA) algorithm (not available for the ReplayGain and BS.1770 sequence algorithms.)
- Provided four respective environment variables for the command option:
  - %TR%: The track loudness range.
  - %TRDB%: The track loudness range in dB/LU.
  - %AR%: The album loudness range.
  - %ARDB%: The album loudness range in dB/LU.
- The API of LIB1770 (implementing the loudness range algorithm) has slightly changed in order to allow for providing the length of a block (either 400 ms or 3000 ms.)

2012-01-06 | 0.9.3 |

- Provided four more environment variables for the command option:
  - %TL%: The track loudness relative to full scale.
  - %TLDB%: The track loudness relative to full scale in dB/LUFS.
  - %AL%: The album loudness relative to full scale.
  - %ALDB%: The album loudness relative to full scale in dB/LUFS.

2011-12-18 | 0.9.2 |

- LINUX SUPPORT added:
  - The Linux version is build in a VMware Player 4.0.1 running Debian 6.0.3.
  - The VMware Player is set up following the instructions found here using a Debian 6.0.3 small CD image.
  - Currently CLI only.
- Completly restructured build process.

2011-12-09 | 0.9.1 |

- Provided more environment variables for the command option:
  - %RATE%: The sample rate.
  - %NCH%: The number of channels.
  - %BITS%: The bit depth.
- Added more presets for the command option:
  - Physically apply the track gain using SoX (default):

    > `sox "%TRACK%" "%DN%\%BN%.wav" gain %TGDB%`

  - Convert to MP3 and physically apply the track gain using lame (very useful for creating MP3s to be used with your mobile MP3 player, requires "lame.exe" to be copied into the subfolder "r128gain"):

    > `lame --noreplaygain --scale %TG% -V2 "%TRACK%" "%DN%\%BN%.mp3"`

  - Decode using SoX and convert to MP3 by physically applying the track gain using lame (very useful for creating MP3s to be used with your mobile MP3 player, requires "lame.exe" to be copied into the subfolder "r128gain"):

    > `sox --no-dither "%TRACK%" -t raw - | lame --noreplaygain --scale %TG% -r --bitwidth %BITS% -s %RATE% -V2 - "%DN%\%BN%.mp3"`

- Fixed a glitch regarding switching between the "command" and other output modes.

2011-11-20 | 0.9 |

- Set default gate to -10.0 LUFS and default block overlap to 75% (according to the latest EBU R128 and BS1770-2 specifications.)
- Avoid division by zero in LIB1770 (implies a slight API change.)
- Further improved GUI synchronization.

2011-10-08 | 0.8.8 |

- Implemented some GUI synchronization with respect to the "command" feature.
- Wrapped arguments in the "command" preset with double quotation marks (").
- Extended number of lines in input list.
- Distribute limited versions of "sox.exe" and "ffmpeg.exe" for usage whithin the "command".

2011-10-03 | 0.8.7 |

- Implemented an alternate BS.1770 statistics using a histogram as proposed in "http://lac.linuxaudio.org/2011/download/lm-pres.pdf". The histogram based statistics avoids memory overflow and appears to improve performance. The new histogram based statistics is default.
- The public API of `lib1770` is changed slightly in order to allow for choosing the statistcs algorithm, either histogram or sequence.
- Provided an option to execute a command in addition to the build-in actions to be enabled via the "Format" drop down box. The command's environment provides the following variables:
  - %PATH%: The systems's path extended by the sub-directory `"r128gain"`.
  - %TRACK%: The complete path to the source track.
  - %NAME%: The name of the source track including the extension.
  - %BN%: The base name of the source track, i.e. excluding the extension.
  - %EXT%: The extension of the source track.
  - %DN%: The output directory.
  - %TG%: The track gain.
  - %TGDB%: The track gain in dB.
  - %TP%: The track peak.
  - %TPDB%: The track peak in dB.
  - %AG%: The album gain.
  - %AGDB%: The album gain in dB.
  - %AP%: The album peak.
  - %APDB%: The album peak in dB.

2011-07-10 | 0.8.6 | Allow choosing the BS.1770 block overlap by parameter partition (1, 2, 3, ...). The corresponding overlap in % is (1 - 1/partition) * 100%.
2011-05-15 | 0.8.5 | Important: Requires "bumped" FFmpeg, i.e. `"avformat-53.dll"`, `"avcodec-53.dll"`, and `"avutil-51.dll"`. For upgrading to the latest full FFmpeg build get the respective DDLs from

> http://ffmpeg.zeranoe.com/builds/win32/shared/, or
> http://www.bizzeh.com/ffmpeg/free/shared/.

Please note that FFmpeg's MP3 muxer (in `"avformat-53.dll"`) now calculates a XING header, i.e. MP3s processed with R128GAIN now contain the correct length information.

### 2. Upgrade to Full FFmpeg

In order to upgrade to full FFmpeg support (i.e. to all FFmpeg supported formats and codecs) do the following:

- Google for "zeranoe ffmpeg builds".
- Pick the latest W32 or W64, respectively, shared build and substitute the corresponding DLLs and EXEs in R128GAIN's sub-directory "r128gain-tools".

### 3. Usage

R128GAIN supports a variety of configuration options:

1. Of course, EBU 128 mode is the default:

   - It uses the gated BS.1770 algorithm.
   - It determines peaks at 4 x up-sampled rate (True Peak).
   - It writes tags with respect to -23 LUFS (compatible with EBU 128).

2. Instead you may choose ReplayGain compliance:

   - It uses the classic "gain_analysis.c" as it is found e.g. in WaveGain and as it is re-distributed with the WA SDK.
   - Peaks are determined without up-sampling (no "True Peak") as required by Notat.
   - Tags are written according to the RG standard (i.e. just as calculated by "gain_analysis.c" without any alteration).

3. Finally you may choose your own profile. The following seems to be the most wanted:

   - You may choose the BS.1770 algorithm.
   - You may choose "True Peak" (i.e. up-sampling for peak determination).
   - You may choose "Loudness Range".
   - You may choose to write the tags RG compatible (i.e. with respect to -18 LUFS).
   - You may fine tune the -18 LUFS.
   - In order to get an idea how to fine tune the -18 LUFS you may first run a linear regression between RG and BS.1770.

Further options:

- Converting to FLAC.
- You may choose to tag the files in place (please be very careful with this option, if something's going wrong your files may be lost forever).
- FFmpeg based I/O.
- Comes with minimal FFmpeg (supporting only a restricted set of "open" codecs, e.g. WAV, FLAC, OGG/Vorbis).

### 4. Applying the Gain

The default behaviour of R128GAIN is

- to calculate various measures, and
- if an output folder is specified, to write respective tags to the output file's header without altering the audio or video streams.

This approach requires an appropriate playback system to make use of the information stored by the tags. Sometimes this is not desirable and the audio should be amplified or attenuated in order to comply with a certain standard. Following are two examples how to achieve this by means of the "command" feature.

Common to both examples

- is the idea to store the altered (i.e. amplified or attenuated) audio stream in a lossless format to avoid any degartion of the audio, and
- that you have to enter an output directory before you may edit the command field.

Audio Only

The following command uses SoX in order to apply the track gain in dB, i.e. `
` to an audio file `
` and writes the result to a WAV file `
`

Audio and Video

The following command uses FFmpeg in order to apply the track gain using an appropriate audio filter `
` to the (decoded) audio stream of a multimedia file `
` and writes the result to a MKV file `
` The video is verbatim copied by `-vcodec copy,` and the audio is encoded to FLAC by `-acodec flac:`

In order to make this work upgrading to full FFmpeg is recommended.

The Command Environment

> TRACK: | full path to the input file (including directory name and extension)
> NAME: | name of the input file (excluding directory name, including extension)
> EXT: | extension of the input file
> DN: | output directory name (i.e. that's what you've entered in the "Output" field)
> RATE: | sample rate of the input audio
> NCH: | number of channels of the input audio
> BITS: | bit depth of the (decoded) input audio
> TL: | track loudness
> TLDB: | track loudness in dB
> TG: | track gain to apply in order to achieve compliance with a certain standards
> TGDB: | track gain to apply in order to achieve compliance with a certain standards in dB
> TR: | track loudness range
> TRDB: | track loudness range in dB
> TP: | track peak
> TPDB: | track peak in dB
> AL: | album loudness
> ALDB: | album loudness in dB
> AG: | album gain to apply in order to achieve compliance with a certain standards
> AGDB: | album gain to apply in order to achieve compliance with a certain standards in dB
> AR: | album loudness range
> ARDB: | album loudness range in dB
> AP: | album peak
> APDB: | album peak in dB

### 5. Command Line Syntax

>     $ r128gain --help
>     An EBU R128 (http://tech.ebu.ch/loudness) compliant loudness scanner.
>     For details refer to "http://r128gain.sourceforge.net/".

>     Usage: r128gain [options] (file|directory)+ [-o <directory> [<format>]]

>     Options:
>       --r128              Run in EBU R128-2011 compliance mode (default).
>       --r128-2011         Run in EBU R128-2011 compliance mode (default).
>       --r128-2010         Run in EBU R128-2010 compliance mode.
>       --a85               Run in ATSC A/85:2011 compliance mode.
>       --a85-2011          Run in ATSC A/85:2011 compliance mode.
>       --rg2               Run in ReplayGain2 compliance mode.
>       --rg                Run in ReplayGain compliance mode.
>       --reference=<float>  Set reference loudness in LUFS.
>       --r128-compatible   Calibrate output according to EBU R128.
>       --rg-compatible     Calibrate output according to ReplayGain.
>       --db                Use dB as unit rather then LU/TP.
>       --partition=<int>   BS.1770 overlap
>                           (overlap in % = (1 - 1/partition) * 100%,
>                           default: 4, i.e. 75% overlap).
>       --gate=<float>      BS.1770 gate (-10.0 .. -8.0, default: -10.0).
>       --rg-calibration=<float>  Aequivalent to use for ReplayGain
>                           loudness (default: -18.0).
>       --no-peak           Don't calculate the maximum peak.
>       --sample-peak       Calculate the maxium peak without up-sampling.
>       --true-peak         Calculate the maxium peak at 192 kHz (default).
>       --range=on,--range  Calculate loudness range (default).
>       --range=off,--no range  Don't calculate loudness range.
>       --tags=[rg|bwf]     Write ReplayGain (default) or BWF tags.
>       --fast              Switch off up-sampling and don't calculate
>                           loudness range.
>       --mono=off          Treat mono as stereo (default).
>       --mono=on,--mono    Don't treat mono as stereo.
>       --quiet             Supress output to stdout.
>       --progress=on       Display progress (default).
>       --progress=off      Don't display progress.
>       --traditional       Format output traditionally.
>       --cpmod             Copy access rights (experimental).
>       --command=<string>  Run command on each track.
>       --overwrite         Overwrite already existing output files.
>       --in-place          Overwrite original files (not recommended).
>       --loglevel=<integer>  Set FFmpeg loglevel.
>       --regression        Calculate linear regression between EBU R128
>                           and ReplayGain.
>       --duration          Print out duration.
>       --version           Display version information.
>       --ffmpeg=<path>     Directory of the FFmpeg shared libraries.
>       --sox=<path>        Directory of the SoX shared libraries.
>       --lame=<path>       Directory of the Lame shared libraries.
>       --magick=<path>     Directory of the ImageMagick shared libraries.
>       --help              Display this information.

>     Format:
>       mkv                 Wrap into MKV container (recommended).
>       flac                Encode into FLAC (not recommend).
>       lame [a=album|track|<int>] [q=<float>]  Convert into MP3 and
>                           apply album (default) or track gain with
>                           quality (default: 2.0).

### 6. Building from Scratch

>     * download "r128gain-<ver>-src.tar.gz"
>     * download "r128gain-<ver>-tools.tar.gz"

>     * run:

>         tar xfvz r128gain-<ver>-src.tar.gz
>         tar xfvz r128gain-<ver>-tools.tar.gz
>         cd r128gain-<ver>
>         ./configure --bindir=/usr/local/bin --mode=full --gui=cli
>         make
>         make install

>     * available configuration options (selection)

>       --bindir:   where to install the binaries

>       --mode:     if omitted, both versions, i.e. full and tiny, will be build
>         * full:   extended FFmpeg and lame
>         * tiny:   crippled FFmpeg and no lame

>       --gui:      if omitted, all GUIs possible will be build
>         * cli:    command line interface
>         * gtk2:   gtk2 gui (if gtk2 development packages are available)
>         * gtk3:   gtk3 gui (if gtk3 development packages are available)
>         * win32:  native win32 gui (on MS Windows only)

### 7. Test Cases

Results for the EBU R128 test vector:

Test cases for Loudness Metering (tech3341.pdf):

>     $ r128gain ~/ebu-loudness-test-setv03/*3341*.wav
>     SoX sucessfully loaded.
>     FFmpeg sucessfully loaded.
>     analyzing ...
>       [1/9] "seq-3341-1-16bit.wav": -23.0 LUFS (-0.0 LU)
>           peak: -22.9 TPFS, range: 0.0 LU
>       [2/9] "seq-3341-2-16bit.wav": -33.0 LUFS (10.0 LU)
>           peak: -32.7 TPFS, range: 0.0 LU
>       [3/9] "seq-3341-2011-8_seq-3342-6-24bit-v02.wav": -23.0 LUFS (0.0 LU)
>           peak: -2.6 TPFS, range: 15.3 LU
>       [4/9] "seq-3341-3-16bit-v02.wav": -23.0 LUFS (0.0 LU)
>           peak: -23.0 TPFS, range: 13.0 LU
>       [5/9] "seq-3341-4-16bit-v02.wav": -23.0 LUFS (0.0 LU)
>           peak: -23.0 TPFS, range: 13.0 LU
>       [6/9] "seq-3341-5-16bit-v02.wav": -23.0 LUFS (-0.0 LU)
>           peak: -20.0 TPFS, range: 6.0 LU
>       [7/9] "seq-3341-6-5channels-16bit.wav": -23.0 LUFS (0.0 LU)
>           peak: -24.0 TPFS, range: 0.0 LU
>       [8/9] "seq-3341-6-6channels-WAVEEX-16bit.wav": -23.0 LUFS (0.0 LU)
>           peak: -24.0 TPFS, range: 0.0 LU
>       [9/9] "seq-3341-7_seq-3342-5-24bit.wav": -23.0 LUFS (-0.0 LU)
>           peak: -8.9 TPFS, range: 4.8 LU
>       [ALBUM]: -23.2 LUFS (0.2 LU)
>           peak: -2.6 TPFS, range: 15.6 LU
>     done.

Test cases for Loudness Range (tech3342.pdf):

>     $ r128gain ~/ebu-loudness-test-setv03/*3342*.wav
>     SoX sucessfully loaded.
>     FFmpeg sucessfully loaded.
>     analyzing ...
>       [1/6] "seq-3341-2011-8_seq-3342-6-24bit-v02.wav": -23.0 LUFS (0.0 LU)
>           peak: -2.6 TPFS, range: 15.3 LU
>       [2/6] "seq-3341-7_seq-3342-5-24bit.wav": -23.0 LUFS (-0.0 LU)
>           peak: -8.9 TPFS, range: 4.8 LU
>       [3/6] "seq-3342-1-16bit.wav": -22.6 LUFS (-0.4 LU)
>           peak: -20.0 TPFS, range: 10.0 LU
>       [4/6] "seq-3342-2-16bit.wav": -16.8 LUFS (-6.2 LU)
>           peak: -15.0 TPFS, range: 5.0 LU
>       [5/6] "seq-3342-3-16bit.wav": -20.1 LUFS (-2.9 LU)
>           peak: -20.0 TPFS, range: 20.0 LU
>       [6/6] "seq-3342-4-16bit.wav": -24.5 LUFS (1.5 LU)
>           peak: -20.0 TPFS, range: 15.0 LU
>       [ALBUM]: -21.2 LUFS (-1.8 LU)
>           peak: -2.6 TPFS, range: 16.5 LU
>     done.

### 8. Why You Won't Post at Hydrogenaudio Forum

Having a question and thinking Hydrogenaudio forum is a good place to ask? Here's what you've to be prepared for:

Soon a "Super Moderator" will show up with a random nonsense "answer" pushing you away (this particular nonsense doesn't even care about that the question is about video and that the HA forum hyped fb2000 is for audio only).

To get an idea about HA forum you might read "OK, I tried hydrogen audio. It didn't go too well" by wgscott:

> My exchange with the "moderator" got worse. To his credit, he eventually apologized, but at that point I resigned, took my (now) dead dog avatar off, and logged out. I requested he delete the account.

> What horrible, horrible people.

> The one thing that does concern me is that these are guys going around wearing "Scientific" on their arm-bands. Scientists have enough of an image problem as it is. We don't need this. I would much rather hang with people who think USB cables sound different and music is described with words like "gooey" than those folks.

> wgscott #4

> They aren't scientists.

> They are anonymous keyboard bullies who slavishly ape what they wrongly perceive to be the aims and methodology of the natural sciences. It actually reminds me more of how things are done in the so-called social sciences (behavioral psychology and so on).

> [...]

> The "moderator" guy (and it almost certainly was a guy) clearly interpreted this as a "lack of respect". It takes a twisted perspective to see it that way, but clearly their self-imposed idiot-logical confines and bizarre rules and rigidity prevent them from seeing it any other way. The behavior is much more reminiscent of a religious cult. I spend almost all my time with scientists. My wife is one. Most of my friends are. None behave this way. Not one.

> wgscott #13

> That is a fascist mentality, not a scientific one. A scientific one, ideally would be, "what is it that sounds different, and how can we test that?" or "how can I reproduce what you found in my system?" or something along those lines.

> wgscott #22