1. History

2. Introduction

3. Usage

3.1. Loudness Measurement

In the simplest case we want to analyze the (integrated) loudness of a track or, a bit more general, an album. Assuming the album is stored in some folder (in the following examples the folder is "~/2012_live_at_the_georgia_theatre") we may issue the following command:

$ bs1770gain ~/2012_live_at_the_georgia_theatre
/home/home/2012_live_at_the_georgia_theatre
analyzing "2012_live_at_the_georgia_theatre" ...
  [1/3] "01_intro_like_i_am.mkv":
      integrated:  -16.2 LUFS / -6.8 LU
  [2/3] "02_good_one_coming_on.mkv":
      integrated:  -15.9 LUFS / -7.1 LU
  [3/3] "03_up_in_smoke.mkv":
      integrated:  -15.6 LUFS / -7.4 LU
  [ALBUM]:
      integrated:  -15.9 LUFS / -7.1 LU
done.

The figure behind the slash is the gain one has to apply in order to achieve a certain loudness. Which loudness to choose depends on the users preferences and there are several standards to choose from, noatbly EBU R128, ATSC A/85, and ReplayGain 2.0 (cf. above). BS1770GAIN silently assumes EBU R128. If we want to alter this we have to utilize the --atsc or --replaygain options, respectively. For example, if we want to normalize to ATSC A/85 we have to issue the command

$ bs1770gain ~/2012_live_at_the_georgia_theatre --atsc
/home/home/2012_live_at_the_georgia_theatre
analyzing "2012_live_at_the_georgia_theatre" ...
  [1/3] "01_intro_like_i_am.mkv":
      integrated:  -16.2 LUFS / -7.8 LU
  [2/3] "02_good_one_coming_on.mkv":
      integrated:  -15.9 LUFS / -8.1 LU
  [3/3] "03_up_in_smoke.mkv":
      integrated:  -15.6 LUFS / -8.4 LU
  [ALBUM]:
      integrated:  -15.9 LUFS / -8.1 LU
done.

In general, if we want to analyze properties out of intergrated loudness, maximum shortterm loudness, maximum momentary loudness, loudness range, maximum sample peak, or maximum true peak we have to choose the appropriate command line switches out of -i/--integrated, -s/--shortterm, -m/--momentary, -r/--range, -p/--samplepeak, and -t/--truepeak, respectivley. Assuming we're interested in all of these properties at once we have to issue following command:

$ bs1770gain ~/2012_live_at_the_georgia_theatre -ismrpt
/home/home/2012_live_at_the_georgia_theatre
analyzing "2012_live_at_the_georgia_theatre" ...
  [1/3] "01_intro_like_i_am.mkv":
       integrated:  -16.2 LUFS / -6.8 LU
        shortterm:  -12.3 LUFS / -10.7 LU
        momentary:  -12.3 LUFS / -10.7 LU
            range:  4.9 LUFS
      sample peak:  -2.2 SPFS / 0.772912
        true peak:  -2.2 TPFS / 0.774780
  [2/3] "02_good_one_coming_on.mkv":
       integrated:  -15.9 LUFS / -7.1 LU
        shortterm:  -12.0 LUFS / -11.0 LU
        momentary:  -12.0 LUFS / -11.0 LU
            range:  5.9 LUFS
      sample peak:  -2.9 SPFS / 0.714886
        true peak:  -2.9 TPFS / 0.714886
  [3/3] "03_up_in_smoke.mkv":
       integrated:  -15.6 LUFS / -7.4 LU
        shortterm:  -12.3 LUFS / -10.7 LU
        momentary:  -12.3 LUFS / -10.7 LU
            range:  5.4 LUFS
      sample peak:  -2.8 SPFS / 0.726805
        true peak:  -2.8 TPFS / 0.726805
  [ALBUM]:
       integrated:  -15.9 LUFS / -7.1 LU
        shortterm:  -12.0 LUFS / -11.0 LU
        momentary:  -12.0 LUFS / -11.0 LU
            range:  5.3 LUFS
      sample peak:  -2.2 SPFS / 0.772912
        true peak:  -2.2 TPFS / 0.774780
done.

If we want to analyze just a short part of the files (say starting at 1 minute and lasting 30 seconds) we may issue the following command utilizing the -b/--begin and -d/--duration options:

$ bs1770gain ~/2012_live_at_the_georgia_theatre -b 1:00 -d 30
/home/home/2012_live_at_the_georgia_theatre
analyzing "2012_live_at_the_georgia_theatre" ...
  [1/3] "01_intro_like_i_am.mkv":
      integrated:  -17.0 LUFS / -6.0 LU
  [2/3] "02_good_one_coming_on.mkv":
      integrated:  -15.4 LUFS / -7.6 LU
  [3/3] "03_up_in_smoke.mkv":
      integrated:  -16.0 LUFS / -7.0 LU
  [ALBUM]:
      integrated:  -16.1 LUFS / -6.9 LU
done.

3.2. Applying the Gain

With the help of BS1770GAIN we can adjust the loudness on the fly. There are two ways to achieve this:

• write REPLAYGAIN tags with the respective information to the file and leave the task of applying the gain to the playback device, or
• actually apply the gain.

In each case we have to instruct BS1770GAIN where to write the output files by means of the -o/--output switch which has to point to the output folder. If we want BS1770GAIN to really apply the gain and not just to write tags to the files we also have to supply the -a/--apply switch. Two examples follow in order to illustrate this.

The first example shows how to just write REPLAYGAIN tags to the output files. In this case we only have to supply the -o/--output switch:

$ bs1770gain ~/2012_live_at_the_georgia_theatre -o ./test
/home/home/number-3/2012_live_at_the_georgia_theatre
analyzing "2012_live_at_the_georgia_theatre" ...
  [1/3] "01_intro_like_i_am.mkv":
      integrated:  -16.2 LUFS / -6.8 LU
  [2/3] "02_good_one_coming_on.mkv":
      integrated:  -15.9 LUFS / -7.1 LU
  [3/3] "03_up_in_smoke.mkv":
      integrated:  -15.6 LUFS / -7.4 LU
  [ALBUM]:
      integrated:  -15.9 LUFS / -7.1 LU
remuxing "2012_live_at_the_georgia_theatre" ...
  [1/3] "01_intro_like_i_am.mkv" ... done.
  [2/3] "02_good_one_coming_on.mkv" ... done.
  [3/3] "03_up_in_smoke.mkv" ... done.
done.

We can convince ourselves that there are indeed REPLAYGAIN tags written to the files and that the video and the audio streams are not altered. To that means we make use of the -l/--list switch:

$ bs1770gain ./test/2012_live_at_the_georgia_theatre -l
./test/2012_live_at_the_georgia_theatre
Input #0, matroska,webm, from './test/2012_live_at_the_georgia_theatre/01_intro_like_i_am.mkv':
  Metadata:
    title           : Intro / Like I Am
    REPLAYGAIN_TRACK_GAIN: -6.81 LU
    CREATION_TIME   : 2013-02-09 13:41:04
    ARTIST          : Blackberry Smoke
    ALBUM           : Live At The Georgia Theatre
    YEAR            : 2012
    DISC            : 1/1
    track           : 1
    GENRE           : Rock
    REPLAYGAIN_ALBUM_GAIN: -7.05 LU
    REPLAYGAIN_ALGORITHM: ITU BS.1770
    REPLAYGAIN_REFERENCE_LOUDNESS: -23.00
    ENCODER         : Lavf56.15.101
  Duration: 00:05:15.36, start: 0.033000, bitrate: 7516 kb/s
    Stream #0:0: Video: mpeg2video (Main), yuv420p(tv, smpte170m), 720x480 [SAR 32:27 DAR 16:9], max. 8700 kb/s, SAR 186:157 DAR 279:157, 59.94 fps, 59.94 tbr, 1k tbn, 59.94 tbc (default)
    Stream #0:1: Audio: ac3, 48000 Hz, stereo, fltp, 448 kb/s (default)
Input #0, matroska,webm, from './test/2012_live_at_the_georgia_theatre/02_good_one_coming_on.mkv':
  Metadata:
    title           : Good One Coming On
    REPLAYGAIN_TRACK_GAIN: -7.05 LU
    CREATION_TIME   : 2013-02-09 13:46:45
    ARTIST          : Blackberry Smoke
    ALBUM           : Live At The Georgia Theatre
    YEAR            : 2012
    DISC            : 1/1
    track           : 2
    GENRE           : Rock
    REPLAYGAIN_ALBUM_GAIN: -7.05 LU
    REPLAYGAIN_ALGORITHM: ITU BS.1770
    REPLAYGAIN_REFERENCE_LOUDNESS: -23.00
    ENCODER         : Lavf56.15.101
  Duration: 00:03:37.27, start: 0.033000, bitrate: 7741 kb/s
    Stream #0:0: Video: mpeg2video (Main), yuv420p(tv, smpte170m), 720x480 [SAR 32:27 DAR 16:9], max. 8700 kb/s, SAR 186:157 DAR 279:157, 59.94 fps, 59.94 tbr, 1k tbn, 59.94 tbc (default)
    Stream #0:1: Audio: ac3, 48000 Hz, stereo, fltp, 448 kb/s (default)
Input #0, matroska,webm, from './test/2012_live_at_the_georgia_theatre/03_up_in_smoke.mkv':
  Metadata:
    title           : Up In Smoke
    REPLAYGAIN_TRACK_GAIN: -7.37 LU
    CREATION_TIME   : 2013-02-09 10:09:16
    ARTIST          : Blackberry Smoke
    ALBUM           : Live At The Georgia Theatre
    YEAR            : 2012
    DISC            : 1/1
    track           : 3
    GENRE           : Rock
    REPLAYGAIN_ALBUM_GAIN: -7.05 LU
    REPLAYGAIN_ALGORITHM: ITU BS.1770
    REPLAYGAIN_REFERENCE_LOUDNESS: -23.00
    ENCODER         : Lavf56.15.101
  Duration: 00:03:33.77, start: 0.033000, bitrate: 8151 kb/s
    Stream #0:0: Video: mpeg2video (Main), yuv420p(tv, smpte170m), 720x480 [SAR 32:27 DAR 16:9], max. 8700 kb/s, SAR 186:157 DAR 279:157, 59.94 fps, 59.94 tbr, 1k tbn, 59.94 tbc (default)
    Stream #0:1: Audio: ac3, 48000 Hz, stereo, fltp, 448 kb/s (default)

$ bs1770gain ~/2012_live_at_the_georgia_theatre -ao ./test
/home/home/number-3/2012_live_at_the_georgia_theatre
analyzing "2012_live_at_the_georgia_theatre" ...
  [1/3] "01_intro_like_i_am.mkv":
      integrated:  -16.2 LUFS / -6.8 LU
  [2/3] "02_good_one_coming_on.mkv":
      integrated:  -15.9 LUFS / -7.1 LU
  [3/3] "03_up_in_smoke.mkv":
      integrated:  -15.6 LUFS / -7.4 LU
  [ALBUM]:
      integrated:  -15.9 LUFS / -7.1 LU
transcoding "2012_live_at_the_georgia_theatre" ...
  [1/3] "01_intro_like_i_am.mkv" ... done.
  [2/3] "02_good_one_coming_on.mkv" ... done.
  [3/3] "03_up_in_smoke.mkv" ... done.
done.

An obvious difference to the previous example is that BS1770GAIN now uses the term transcoding instead of remuxing. The reason for that is that the streams are now altered and no REPLAYGAIN-tags appear if we make the contents of the transcoded files visible by means of the -l/--list switch:

$ bs1770gain ./test/2012_live_at_the_georgia_theatre -l
./test/2012_live_at_the_georgia_theatre
Input #0, matroska,webm, from './test/2012_live_at_the_georgia_theatre/01_intro_like_i_am.mkv':
  Metadata:
    title           : Intro / Like I Am
    GENRE           : Rock
    CREATION_TIME   : 2013-02-09 13:41:04
    ARTIST          : Blackberry Smoke
    ALBUM           : Live At The Georgia Theatre
    YEAR            : 2012
    DISC            : 1/1
    track           : 1
    ENCODER         : Lavf56.15.101
  Duration: 00:05:16.87, start: 0.033000, bitrate: 8626 kb/s
    Stream #0:0: Video: mpeg2video (Main), yuv420p(tv, smpte170m), 720x480 [SAR 32:27 DAR 16:9], max. 8700 kb/s, SAR 186:157 DAR 279:157, 59.94 fps, 59.94 tbr, 1k tbn, 59.94 tbc (default)
    Stream #0:1: Audio: flac, 48000 Hz, stereo, s32 (24 bit) (default)
Input #0, matroska,webm, from './test/2012_live_at_the_georgia_theatre/02_good_one_coming_on.mkv':
  Metadata:
    title           : Good One Coming On
    GENRE           : Rock
    CREATION_TIME   : 2013-02-09 13:46:45
    ARTIST          : Blackberry Smoke
    ALBUM           : Live At The Georgia Theatre
    YEAR            : 2012
    DISC            : 1/1
    track           : 2
    ENCODER         : Lavf56.15.101
  Duration: 00:03:38.77, start: 0.033000, bitrate: 8827 kb/s
    Stream #0:0: Video: mpeg2video (Main), yuv420p(tv, smpte170m), 720x480 [SAR 32:27 DAR 16:9], max. 8700 kb/s, SAR 186:157 DAR 279:157, 59.94 fps, 59.94 tbr, 1k tbn, 59.94 tbc (default)
    Stream #0:1: Audio: flac, 48000 Hz, stereo, s32 (24 bit) (default)
Input #0, matroska,webm, from './test/2012_live_at_the_georgia_theatre/03_up_in_smoke.mkv':
  Metadata:
    title           : Up In Smoke
    GENRE           : Rock
    CREATION_TIME   : 2013-02-09 10:09:16
    ARTIST          : Blackberry Smoke
    ALBUM           : Live At The Georgia Theatre
    YEAR            : 2012
    DISC            : 1/1
    track           : 3
    ENCODER         : Lavf56.15.101
  Duration: 00:03:35.27, start: 0.033000, bitrate: 9266 kb/s
    Stream #0:0: Video: mpeg2video (Main), yuv420p(tv, smpte170m), 720x480 [SAR 32:27 DAR 16:9], max. 8700 kb/s, SAR 186:157 DAR 279:157, 59.94 fps, 59.94 tbr, 1k tbn, 59.94 tbc (default)
    Stream #0:1: Audio: flac, 48000 Hz, stereo, s32 (24 bit) (default)

The most important observation is that the audio stream now is a 24 bit FLAC and no longer an AC3.

It may happen that it is not appropriate to base the gain on the measurement of the integrated loudness but insteed on the maximum shorterm loudness or on the maximum momentary loudness. For that means there is the -u/--use switch which has to be supplied with the method to use, i.e. integrated, shorterm, or momentary. The following illustrates this:

$ bs1770gain ~/2012_live_at_the_georgia_theatre -o ./test -u shortterm
/home/home/number-3/2012_live_at_the_georgia_theatre
analyzing "2012_live_at_the_georgia_theatre" ...
  [1/3] "01_intro_like_i_am.mkv":
      shortterm:  -12.3 LUFS / -10.7 LU
  [2/3] "02_good_one_coming_on.mkv":
      shortterm:  -12.0 LUFS / -11.0 LU
  [3/3] "03_up_in_smoke.mkv":
      shortterm:  -12.3 LUFS / -10.7 LU
  [ALBUM]:
      shortterm:  -12.0 LUFS / -11.0 LU
remuxing "2012_live_at_the_georgia_theatre" ...
  [1/3] "01_intro_like_i_am.mkv" ... done.
  [2/3] "02_good_one_coming_on.mkv" ... done.
  [3/3] "03_up_in_smoke.mkv" ... done.
done.

4. Command Line Syntax

$ bs1770gain ~/2012_live_at_the_georgia_theatre -h
Usage:  bs1770gain [options] <file/dir> [<file/dir> ...]

Options:
 -h,--help:  print this message and exit
 -i,--integrated:  calculate integrated loudness
 -s,--shorterm:  calculate maximum shortterm loudness
 -m,--momentary:  claculate maximum momentary loudness
 -r,--range:  calculate loudness range
 -p,--samplepeak:  calculate maximum sample peak
 -t,--truepeak:  calculate maximum true peak
 -b <timestamp>,--begin <timestamp>:  begin decoding at
   timestamp (in microseconds, format: hh:mm:ss.mus)
 -d <duration>,--duration <duration>:  let decoding
   last duration (in microseconds, format: hh:mm:ss.mus)
 -u <method>,--use <method>:  base replay gain calculation
   on method (with respect to the -a/--apply and -o/--output
   options),
   method:  integrated (default), shortterm, or momentary
 -a:  apply the EBU/ATSC/RG album gain to the output
   (in conjunction with the -o/--output option)
 -o <folder>,--output <folder>:  write RG tags
   or apply the EBU/ATSC/RG gain, respectively,
   and output to folder
 -f <file>,--file <file>:  write analysis to file
 -x,--extensions:  enable extensions:
   1) read metadata from per-folder CSV file "folder.csv"
   2) copy file "folder.jpg" from source to destination
      folder
 -l,--list:  print FFmpeg format/stream information
 --ebu:  calculate replay gain according to EBU R128
   (-23.0 LUFS, default)
 --atsc:  calculate replay gain according to ATSC A/85
   (-24.0 LUFS)
 --replaygain:  calculate replay gain according to
   ReplayGain 2.0 (-18.0 LUFS)
 --apply <q>:  apply the EBU/ATSC/RG gain to the output
   (in conjunction with the -o/--output option),
   q=0.0 (album gain) ... 1.0 (track gain),
   default:  0.0 (album gain)
 --audio <index>:  select audio index (corresponds to
   [0:<index>] in FFmpeg listing, cf. -l/--list option)
 --video <index>:  select video index (corresponds to
   [0:<index>] in FFmpeg listing, cf. -l/--list option)
 --drc <drc>:  set AC3 dynamic range compression (DRC)
 --format <format>:  convert to format
 --loglevel <level>:  set loglevel,
   level:  quiet, panic, fatal, error, warning, info,
   verbose, debug
 --time:  print out duration of program invocation

Command line arguments can be mixed up in any order.

5. Test Cases