Keywords: EBU R128, loudness

## BS1770GAIN

Copyright © 2014-2016 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 2 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/>.

BS1770GAIN is a loudness scanner compliant with ITU-R BS.1770 and its flavors EBU R128, ATSC A/85, and ReplayGain 2.0. It helps normalizing the loudness of audio and video files to the same level.

Home: |  | http://bs1770gain.sourceforge.net/
Project: |  | http://sourceforge.net/projects/bs1770gain/
Download: |  | http://sourceforge.net/projects/bs1770gain/files/bs1770gain/

### Content

1. History
2. Introduction
3. Usage
4. Command Line Syntax
5. Test Cases

### 1. History

2016-12-08 | 0.4.12 | Added UTF-16 support to the Windows Console. Linux should not be affected and should have been worked all the time because being based on UTF-8. This development was triggered by Seongkyun (Andrei) Kim who is located in Korea and provided some testing.
2016-12-06 |  | Thanks to Seongkyun (Andrei) Kim there is an introduction to `bs1770gain` in Korean language available at http://blog.naver.com/eqmaker/220879120285 and a manual at http://www.eqmaker.kr/public/BS1770GAIN_Manual_KOR-20161206.pdf.
2016-11-10 |  | To all you great people out there in the US: Thank you for electing Donald Trump!
2016-08-13 | 0.4.11 | Just recently a very talented guy who calls himself `kevinlekiller` (https://github.com/kevinlekiller/) approached me with a bunch of bugs he obviously had learned the hard way by using the tool (i.e. by not artificially testing it). But not just that, he also proposed a solution for each of the bugs: https://gist.github.com/kevinlekiller/62730fa5ddcf791107a723b1f235773e. This release mainly consists of his contributions. Fixed ignoring the `--audio=<n>` option. Fixed crashing with files containing more than 5 audio streams.
2016-07-18 | 0.4.10 | Fixed writing xml escaped strings with the `--xml` option. Please note that `bs1770gain` is not officially supported on OSX even if it seems to build on OSX platforms and that it hence don't take into account unicode mapping anomalies between OSX and Linux/Windows (NFD/NFC). It will always output the unicode dialect common on the platform and hence the generated XML is not portable between OSX and Linux/Windows.
2016-03-16 | 0.4.9 | In `"ffsox_frame_convert.c"`, replaced constant `~0ll` by `~0ull` (sould fix #811955). Replaced `av_free_packet()` by `av_packet_unref()` (should fix #810563).
2015-12-19 | 0.4.8 | There's a new option `--norm=<float>` allowing to set the reference loudness to some value apart from -23.0 (EBU R128), -24.0 (ATSC A/85), or -18.0 (ReplayGain 2.0). Loudness values are written to the output console with two places after the decimal point. Regarding the Windows version, added some support for unicode paths (i.e. non-OEM).
2015-09-15 | 0.4.7 | Fixed a serious bug regarding the `-r` option.
2015-09-12 | 0.4.6 | There's a new option `--xml` for producing XML-output. There's a new option `--stereo`. The effect is that down-mix to stereo only happens if requested. The old version always silently down-mixes to stereo which is fixed now. FFmpeg has bumped their version numbers, i.e is not binary compatible to the old version. The new binary release now requires avutil-55, swresample-2, avcodec-57, and avformat-57.
2015-06-25 | 0.4.5 | Various fixes mainly to make BS1770GAIN compile on various architectures.
2015-06-22 | 0.4.4 | Fixed "stuttering" videos. Thanks to Petter Reinholdtsen there is now an official BS1770GAIN package available on Debian. Read about Petter's plans regarding BS1770GAIN.
2015-06-15 | 0.4.3 | Automake/Autoconf compatible source code distribution. Several fixes.
2015-06-08 | 0.4.2 | Fixed memory leaks.
2015-01-29 | 0.4.1 | Several fixes.
2015-01-14 | 0.4.0 | Integrated BS.1770 analysis into the finite state machine. Added automatic TRACK and DISC tags extension. Added `--extension <extension>` option. Several fixes.
2015-01-08 | 0.3.2 | Added another extension. Several fixes.
2014-12-30 | 0.3.1 | Minor fixes.
2014-12-23 | 0.3.0 | Finite state machine for remuxing/transcoding.
2014-12-11 | 0.2.1 | Fixed a critical bug breaking the whole program (thanks to Michal Šmucr). Improved diagnostic of erroneous command line.
2014-12-07 | 0.2.0 | Added experimental options.
2014-12-04 | 0.1.1 | Compiled with `-O2`. Slightly different error handling with `getopt_long()`. Added the FFmpeg and SoX shared objects / dynamic link libraries to the release.
2014-12-01 | 0.1.0 | Initial release.

### 2. Introduction

Audio from different sources can be expected to be different loud and it would be nice to automatically adapt all these audio sources to the same loudness. Fortunately the ITU-R in their BS.1770 standard defines an algorithm which makes it possible to measure the loudness of a certain audio source. Based on the ITU-R BS.1770 measure several standards bodys defined what they think is the preferred loudness audio should normalize to, notably

- EBU R128 (Europe) says -23.0,
- ATSC A/85 (Northern America) says -24.0, and
- ReplayGain 2.0 says -18.0.

`BS1770GAIN` implements the ITU-R BS.1770 loudness measurement algorithm and makes it accessable to a user in several ways as known from the EBU R128 standard, i.e.

- measurement of the integrated loudness,
- measurement of the maximum shortterm loudness,
- measurement of the maximum momentary loudness, and
- measurement of the loudness range.

The integrated loudness is the two phase gated measurement of the mean loudness as described by ITU-R BS.1770. All measures are described in detail by EBU R128.

On top of that `BS1770GAIN` provides to additional measures not related to loudness:

- measurement of the maximum sample peak (ordinary peak), and
- measurement of the maximum true peak (peak due to upsampling).

Besides measuring the loudness `BS1770GAIN` is also able to adapt it conformant with the above mentioned statndards. 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.

Following we describe in more detail how `BS1770GAIN` has to be customized.

### 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.

Immediatly `BS1770GAIN` gives us the (integrated) loudness of each track as well as of the whole album.

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.

You may request XML output by means of the `--xml` option:

>     $ bs1770gain ~/2012_live_at_the_georgia_theatre --xml
>     <bs1770gain>
>       <album folder="2012_live_at_the_georgia_theatre">
>         <track total="3" number="1" file="01_intro_like_i_am.mkv">
>           <integrated lufs="-16.2" lu="-6.8" />
>         </track>
>         <track total="3" number="2" file="02_good_one_coming_on.mkv">
>           <integrated lufs="-15.9" lu="-7.1" />
>         </track>
>         <track total="3" number="3" file="03_up_in_smoke.mkv">
>           <integrated lufs="-15.6" lu="-7.4" />
>         </track>
>         <summary total="3">
>           <integrated lufs="-15.9" lu="-7.1" />
>         </summary>
>       </album>
>     </bs1770gain>

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-R 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-R 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-R 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)

The second example deals with really applying the gain. For that order we not only have to supply the `-o`/`--output` switch but also the `-a`/`--apply` switch:

>     $ 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.

#### 3.3. Experimental Options

We can imagine the ITU-R BS.1770 measurement device as a blackbox where time after time portions of the audio with the same length

- are floating in,
- staying for some time inside, and
- finally are floating out.

Such portions of audio are called a block. We assume that at a given time at least one audio block is inside the measurement device, but in general there are more than one are there.

The measurement device does some sophisticated calculation on the audio blocks currently inside with the loudness as the result. We don't want to go into all the details here but it should be clear that the result depends at least on the following:

- on the length of the audio blocks,
- on their overlap, and
- on what is considered to be a silence gate.

EBU R128 defines two such measurement devices,

- one we would like to call the momentary device, and
- the other one we would like to call the shortterm device.

The momentary device has the following properties:

- length: 0.4 s,
- overlap: 75 %, and
- gate: -10.0 (defined just for integrated loudness),

wheras the shorttime device has the following:

- length: 3.0 s,
- overlap: 67 %, and
- gate: -20.0 (defined just for loudness range).

After all we can calculate 6 measures from the two blocks, two of them are non-standard:

- the mean loudness of the momentary block (corresponds to the integrated loudness),
- the maximum loudness of the momentary block (corresponds to the maximum momentary loudness),
- the loudness range of the momentary block (has no correspondence to a standard term),
- the mean loudness of the shortterm block (has no correspondence to a standard term),
- the maximum loudness of the shortterm block (corresponds to the maximum shortterm loudness), and
- the loudness range of the shortterm block (corresponds to the loudness range).

This gives rise to a variety of possible parameters if one takes into account that it is possible to customize measurement devices themselfs (cf. "experimental options" under "command line syntax" below).

Finally we give an example on how to RG tag with the non-standard measure shortterm mean loudness:

>     $ ./bs1770gain ~/2012_live_at_the_georgia_theatre -o ./test -u shortterm-mean
>     /home/home/2012_live_at_the_georgia_theatre
>     analyzing "2012_live_at_the_georgia_theatre" ...
>       [1/3] "01_intro_like_i_am.mkv":
>           shortterm mean:  -16.2 LUFS / -6.8 LU
>       [2/3] "02_good_one_coming_on.mkv":
>           shortterm mean:  -16.0 LUFS / -7.0 LU
>       [3/3] "03_up_in_smoke.mkv":
>           shortterm mean:  -15.6 LUFS / -7.4 LU
>       [ALBUM]:
>           shortterm mean:  -16.0 LUFS / -7.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 -h
>     BS1770GAIN 0.4.8, Copyright (C) Peter Belkner 2014-2015.
>     http://bs1770gain.sourceforge.net/

>     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),
>        methods:  "integrated" (default), "shortterm", or
>        "momentary"
>        experimental methods:  "momentary-mean" (same as
>        "integrated"), "momentary-maximum" (same as "momentary"),
>        "shortterm-mean", or "shortterm-maximum" (same as
>        "shortterm")
>      -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 following extensions/defaults:
>        1) rename files according to TITLE tag
>        2) read metadata from per-folder CSV file "folder.csv"
>        3) copy file "folder.jpg" from source to destination
>           folder
>        4) automatically add the TRACK and DISC tags
>        5) calculate maximum true peak
>        6) convert to stereo
>      -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)
>      --track-tags:  write track tags
>      --album-tags:  write album tags
>      --unit <unit>:  write tags with <unit>
>      --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)
>      --stereo:  convert to stereo
>      --drc <float>:  set AC3 dynamic range compression (DRC)
>      --extension <extension>:  enable extension out of
>        "rename":  rename files according to TITLE tag
>        "csv":  read metadata from per-folder CSV file "folder.csv"
>        "jpg":  copy file "folder.jpg" from source to destination
>           folder
>        "tags":  automatically add the TRACK and DISC tags
>      --format <format>:  convert to format
>      --loglevel <level>:  set loglevel,
>        level:  "quiet", "panic", "fatal", "error", "warning",
>        "info", "verbose", "debug"
>      --xml:  print results in xml format
>      --time:  print out duration of program invocation
>      --norm <float>:  norm loudness to float.

>     Experimental options:
>     1) momentary block
>      --momentary-mean:  calculate mean loudness based on
>        momentary block (same as --integrated)
>      --momentary-maximum:  calculate maximum loudness based
>        on momentary block (same as --momentary)
>      --momentary-range:  calculate loudness range based on
>        momentary block
>      --momentary-length <ms>:  length of momentary block
>        in milliseconds (default: 400)
>      --momentary-overlap <percent>:  overlap of momentary
>        block in percent (default: 75)
>      --momentary-mean-gate <gate>:  silence gate for mean
>        measurement of momentary block (default: -10.0)
>      --momentary-range-gate <gate>:  silence gate for range
>        measurement of momentary block (default: -20.0)
>      --momentary-range-lower-bound <float>:  lower bound for
>        range measurement of momentary block (default: 0.1)
>      --momentary-range-upper-bound <float>:  upper bound for
>        range measurement of momentary block (default: 0.95)
>     2) shortterm block
>      --shortterm-mean:  calculate mean loudness based on
>        shortterm block
>      --shortterm-maximum:  calculate maximum loudness based
>        on shortterm block (same as --shortterm)
>      --shortterm-range:  calculate loudness range based on
>        shortterm block (same as --range)
>      --shortterm-length <ms>:  length of shortterm block
>        in milliseconds (default: 3000)
>      --shortterm-overlap <percent>:  overlap of shortterm
>        block in percent (default: 67)
>      --shortterm-mean-gate <gate>:  silence gate for mean
>        measurement of shortterm block (default: -10.0)
>      --shortterm-range-gate <gate>:  silence gate for range
>        measurement of shortterm block (default: -20.0)
>      --shortterm-range-lower-bound <float>:  lower bound for
>        range measurement of shortterm block (default: 0.1)
>      --shortterm-range-upper-bound <float>:  upper bound for
>        range measurement of shortterm block (default: 0.95)

>     Command line arguments may appear in any order.

### 5. Test Cases

Results for the EBU R128 test vector:

- Test cases for Loudness Metering (tech3341.pdf):

  >     $ bs1770gain ~/ebu-loudness-test-setv03/*3341*.wav
  >     analyzing ...
  >       [1/9] "seq-3341-1-16bit.wav":
  >           integrated:  -23.0 LUFS / -0.0 LU
  >       [2/9] "seq-3341-2-16bit.wav":
  >           integrated:  -33.0 LUFS / 10.0 LU
  >       [3/9] "seq-3341-2011-8_seq-3342-6-24bit-v02.wav":
  >           integrated:  -23.0 LUFS / 0.0 LU
  >       [4/9] "seq-3341-3-16bit-v02.wav":
  >           integrated:  -23.0 LUFS / 0.0 LU
  >       [5/9] "seq-3341-4-16bit-v02.wav":
  >           integrated:  -23.0 LUFS / 0.0 LU
  >       [6/9] "seq-3341-5-16bit-v02.wav":
  >           integrated:  -23.0 LUFS / -0.0 LU
  >       [7/9] "seq-3341-6-5channels-16bit.wav":
  >           integrated:  -23.0 LUFS / 0.0 LU
  >       [8/9] "seq-3341-6-6channels-WAVEEX-16bit.wav":
  >           integrated:  -23.0 LUFS / 0.0 LU
  >       [9/9] "seq-3341-7_seq-3342-5-24bit.wav":
  >           integrated:  -23.0 LUFS / -0.0 LU
  >       [ALBUM]:
  >           integrated:  -23.1 LUFS / 0.1 LU
  >     done.

- Test cases for Loudness Range (tech3342.pdf):

  >     $ bs1770gain ~/ebu-loudness-test-setv03/*3342*.wav -r
  >     analyzing ...
  >       [1/6] "seq-3341-2011-8_seq-3342-6-24bit-v02.wav":
  >           range:  15.2 LUFS
  >       [2/6] "seq-3341-7_seq-3342-5-24bit.wav":
  >           range:  4.8 LUFS
  >       [3/6] "seq-3342-1-16bit.wav":
  >           range:  10.0 LUFS
  >       [4/6] "seq-3342-2-16bit.wav":
  >           range:  5.0 LUFS
  >       [5/6] "seq-3342-3-16bit.wav":
  >           range:  20.0 LUFS
  >       [6/6] "seq-3342-4-16bit.wav":
  >           range:  15.0 LUFS
  >       [ALBUM]:
  >           range:  16.5 LUFS
  >     done.