Command line

Introduction

The JOCLoudness application is a windows console applications that loads a wave file (.wav) and give us the following data of the file:

  • Integrated loudness
  • Vector of short term loudness
  • Vector of momentary loudness
  • Vector and maximum true peak level
  • Loudness range value
JOCLoudness block diagram
JOCLoudness block diagram

Input parameters

Name Mandatory Description 
 /audio file  YES  Input audio file (check accepted wav formats below)
 /tin  NO  Trim in point in seconds. Point to start analize loudness parameters.
 /tout  NO  Trim out point in seconds. Point to stop analyze the loudness parameters.
 /config  NO  Filename of the input config file (check config parameters below)
 /outlouddata  NO  Filename of the output file with loudness data parameters
 /outaudiofile  NO  Filename of the output file with audio processed segment (check wav out format below)
 /logsfile  NO  Filename of the output log file
 /verbose NO  Display extra information to the screen

Example:

JOCLoudness.exe "c:\audiotest\totest.wav" /tin:1.1 /tout:20 /outaudiofile:"c:\out\outpartialfile.wav" /config:configcustom.ini /outlouddata:"c:\dataloud\loud.txt" /logsfile:"c:\logsloud.log"

 

This command does the follow:

  • Calculates the loudness parameters of the “totest.wav” from 1.1 seconds to 20 seconds
  • Saves the loudness parameters to “c:\dataloud\loud.txt” using config parameters loaded from “configcustom.ini” file
  • Saves the wav file “c:\out\outpartialfile.wav” that contains the audio segment from 1.1s to 20s from input file
  • Generates or append the “c:\logsloud.log” that contains the log data

In the following lines you can find the input and output files involved in previous example:

Loudness Configuration file

The input configuration file is a .ini file (text format). The values that you can set in config file are explained in the following table:

 Name Default value  Value range   Used in Directshow module  Description
 action loudness loudness,filter  No Sets the action to perfom
 MapChanel  [L R C Ls Rs 0] Yes Sets where the channels are located in audio input file. The first position of  the vector indicates the first audio channel in the input file, second position is second channel, etc…
L = Left channel
R = Right channel
C = Center channel
Ls = Left surround channel
Rs = Right surround channel
0 = Nothing (not use this channel)
 ReadBlockSizeInSamplesPerChannel  1024 1… 2147483647  No  Audio samples per channel read in each iteration of the application loop
TRUE PEAK SECTION
 TPCalc  0  0,1 Yes  Indicates if the application calculates the true peak value.
We recommend set TPCalc = 0, it’s a TIME CONSUMING FEATURE!!! (need to improve the oversampler LPF filter implementation)
 TPDecaytimeMS  1700 1… 60000  Yes  [True peak config] The time needed in milliseconds since the audio peak is detected to the true peak meter shows the detected value minus TPDecayValueDB
 TPDecayValueDB  -20  -0.1 … -99999  Yes  [True peak config] Value substracted (in dB) to detected peak after TPDecaytimeMS milliseconds
 TPRefreshInvervalMS  250 1… 60000  Yes  [True peak config] The refresh interval of true peak metter in miliseconds
PRESET SELECTION SECTION
 Preset  r128 r128, a85, custom  Yes  Set the following configuration values according to R128 or A/85.
 The following values only have effect if Preset = custom
PRE FILTER SECTION
 PreFilterCoefsAuto 1 0,1  Yes  Indicates if the application calculates the pre filter coefs automatically according to the sampling frequency of the input file.
(*)
 PreFilterACoefs  [1.0 -1.69065929318241 0.73248077421585]  Yes  Set the A coefs of the pre filter (Order 2 IIR filter)
The coefs order is: [a0 a1 a2]
 PreFilterBCoefs  [1.53512485958697 -2.69169618940638 1.19839281085285]  Yes Set the B coefs of the pre filter (Order 2 IIR filter)
The coefs order is: [b0 b1 b2]

RLB FILTER SECTION
 
 RLBPreFilterCoefsAuto  1  0,1  Yes  Indicates if the application calculates the rlb filter coefs automatically according to the sampling frequency of the input file.
(*)
 RLBFilterACoefs  [1.0 -1.99004745483398 0.99007225036621]  Yes  Set the A coefs of the rlb filter (Order 2 IIR filter)
The coefs order is: [a0 a1 a2]
 RLBFilterBCoefs  [1.0 -2.0 1.0]  Yes  Set the B coefs of the pre filter (Order 2 IIR filter)
The coefs order is: [b0 b1 b2]
MOMENTARY LOUDNESS PARAMETERS SECTION
 MomentaryAudioBlockDurationMS  400  1…3000  Yes  Sets the momentary audio block window duration in milliseconds
 MomentaryAudioBlockOverlapping  0.75 0…1  Yes  Sets the windows overlapping of the momentary audio window

SHORT TERM LOUDNESS PARAMETERS SECTION
 ShortTermAudioBlockDurationMS  3000 1…10000  No  Sets the short term audio block window duration in milliseconds
 ShortTermAudioBlockOverlapping  0.75 0…1  No  Sets the windows overlapping of the short term audio window

INTEGRATE LOUDNESS PARAMETERS SECTION
 IntegrateAlg  BS17702  BS17702, BS1770 No  Indicates which integrate algorithm will use the application
 IntegrateGating  1 0,1 No  If the IntegrateAlg = BS17702, this parameter indicates if the integrate algorithm uses gating block or not
 IntegrateAbsoluteThresholdDB  -70 0…-999999 No  If the IntegrateGating = 1, this parameter indicates the absolute threshold in LUFS
 IntegrateRelativeThresholdDB  -10 -1…-999999 No  If the IntegrateGating = 1, this parameter indicates in LU the relative threshold applied to calculate the loudness integrate value

RESULTS PRESENTATION SECTION
 ResultPrecission  1  -1…20 No  Indicates the number of decimal positions in the results value
-1 = max precission
 ResultUnits  LUFS  LUFS, LKFS No  Indicate the loudness units that shows the results file

LOUDNESS RANGE SECTION
 LRACalc  1  0,1 No  Indicates if the application calculates the loudness range values
 LRAAudioBlockDurationMS  3000  1…10000 No  Sets the LRA audio block window duration  in milliseconds
 LRAAudioBlockOverlapping  0.75  0…1 No  Sets the windows overlapping of the LRA audio window
 LRAAbsoluteThresholdDB  -70  0…-999999 No  Indicates the absolute threshold in LUFS used to calc LRA value
 LRARelativeThresholdDB  -20 -1…-999999 No  Indicates in LU the relative threshold applied to calculate the LRA value
 LRALowPercentile  10  0…100 No  Set the low percentile to calculate de LRA value
 LRAHighPercentile  95  0…100 No  Set the high percentile to calculate de LRA value

(*) The ITU-R BS1770-2 and ITU-R BS1770 indicates the pre and rlb filter coefficients referred to a sampling frequency of 48KHz. If the input audio file has a different audio sampling frequency and the coefficients are set in auto mode the application calculates the filter coefficients in order to keep the filter weighting curve characteristics.

If no config file are set JOCLoudness application uses the default config values.

In the following table you can dowload 3 diferent config example file:

 R128 preset file Download
 A/85 preset file Download
 Custom preset file Download

Accepted input wave (.wav) formats

 Header type  Sample type  Sample frequencies
  Integer sample bits
  Float sample bits
 16 bytes
18 bytes
40 bytes (WAVEEX)		 Integer
Float		  All  8
16
24		  32

Output wave (.wav) format

 Header type  Sample type  Sample frequencies
  Float sample bits
 16 bytes Float  All (same as input)  32

EBU compliance test

EBU gives a set of audio file to test the implementation of loudness meter, and also gives the expected results and tolerances. If the results of the JOCLoudness meter are according to the expected EBU results we can say that the JOCLoudness meter meets the minimum requirements to be EBU compliant.

In the following tables we can see that the results obtained by JOCLoudness meter are perfecly inside EBU tolerances:

Minimum EBU Tech 3341 requirements for loudness measure:

 Test case File  EBU Expected  [LUFS]  EBU accepted tolerance CJOCLoudness result [LUFS]
 1  seq-3341-5-16bit-v02.wav  I = -23.0  +-0.1  I = -23.0
 2  seq-3341-6-5channels-16bit.wav  I = -33.0  +-0.1  I = -33.0
 3  seq-3341-3-16bit-v02.wav  I = -23.0  +-0.1  I = -23.0
 4  seq-3341-4-16bit-v02.wav  I = -23.0  +-0.1  I = -23.0
 5  seq-3341-5-16bit-v02.wav  I = -23.0  +-0.1  I = -23.0
 6a  seq-3341-6-5channels-16bit.wav  I = -23.0  +-0.1  I = -23.0
 6b  seq-3341-6-6channels-WAVEEX-16bit.wav  I = -23.0  +-0.1  I = -23.0
 7  seq-3341-7_seq-3342-5-24bit.wav  I = -23.0  +-0.1  I = -23.0
 8  seq-3341-2011-8_seq-3342-6-24bit-v02.wav  I = -23.0  +-0.1  I = -23.1

Minimum EBU Tech 3342 requirements for loudness range (LRA) measure:

 Test case File  EBU Expected  LRA [LU]  EBU accepted tolerance CJOCLoudness result [LU]
 1  seq-3342-1-16bit.wav  I = 10.0  +-1  I = 10.0
 2  seq-3342-2-16bit.wav  I = 5.0  +-1  I = 5.0
 3  seq-3342-3-16bit.wav  I = 20.0  +-1  I = 20.0
 4  seq-3342-4-16bit.wav  I = 15.0  +-1  I = 15.0
 5  seq-3341-7_seq-3342-5-24bit.wav  I = 5.0  +-1  I = 4.9
 6  seq-3341-2011-8_seq-3342-6-24bit-v02.wav  I = 15.0  +-1  I = 14.9
Here you can download the files used to perform the EBU test:

Viewing those results we can say that JOCLoudness meter meets the minimum requirements to be EBU compliant, and this is indicated by EBU R128 compliant logo:

R128 compliant logo
R128 compliant logo

 

JOCLoudness implementation details

This application is completely developed in ansi C++ using the ITU, EBU, ATSC standards, and WAV specs as reference. Only tipical C++ ansi libraries (math, stdio, list, vector, etc…) was used, all application modules are implemented from zero: WAV reader, WAV writer, IIR filters, FIR filters, etc…

This gives the following advantages to this application:

  • Portable source code (Linux, MAC os, etc…)
  • Easy deployment (no dependencies)
  • Easy error correction (no strange code from others)
  • Very easy to improve

On the other hand, the bad point of absolutely the self made application are:

  • More work 🙂

The architecture that the JOCLoudness was made allows to transform, in an easy way, the command line application in a real time loudness meter application.

In the following figure we can see the general block diagram of JOCLouness used in R128 (EBU mode):

General block diagram of JOCLouness used in R128
General block diagram of JOCLouness used in R128

The wavreader reads the integer or float samples from the wav file and it transforms them into double, the double precision (64b) samples are sent to channel mapper who allocates the channels according to readmapchanel config parameter. For each channel the samples are sent to channel proc. module (see below). The samples processed by channel proc. module are multiplied by a factor (specified in ITU-R BS.1770-2 recommendation), then are added and sent to the output data file. TO calculate I (integrate loudness) value the same samples are sent to Gate module (see below).

In the following figure we can see a detailed block diagram of channel proc. module:

Detailed block diagram of channel proc. module
Detailed block diagram of channel proc. module

When a sample enters in channel proc. module it’s sent to 4 different modules:

  • True peak module

Following the ITU-R BS.1770-2 recommendation to calculate the true peak level, first it oversamples the signal (put zeros), and after that the signal enters into a low pas filter (LFP) to reconstruct them, and finally apply an algorithm to extract the true peak value.

  • Loudness momentary calculation (M)

First we filter the entering samples with the PRE filter, after that the signal is filtered by RLB filter, and in the last step MeanFast does a mean of a number of samples specified intrinsically in config parameters.

  • Loudness short term calculation (ST)

It does the same as Loudness momentary module, only change the parameters used to do the final mean.

  • Loudness range calculation (LRA)

It does the same as Loudness momentary module, only change the parameters used to do the final mean.

 

To get Integrate Loudness value we need to apply a gate specified in the ITU-R BS.1770-2, in the following fgure can see a block diagram of gate module:

Block diagram of gate module
Block diagram of gate module
The first step in the gate module simply discard samples that are lower than specified threshold (absolute trheshold). The second module stores all samples inside the integration time and atfer that it calculates a relative threshold. Once relative threshold is calculated, the stored samples are thresholded again, this time with the relative threshold. Finally the mean modules does a simple mean, and the result is presented in log scale.

Future work

  • Improve speed of low pass filter (LPF) of oversampler of TP meter (Done in JOCLoudnessDS).

Download JOCLoudness (win version)

(Tested with: Windows XP SP3, Windows 7 (32b and 64b))

  • Here you can find a link to download the exe file:  JOCLoudness.exe
  • Or you can download a zip that contains: JOCLoudness.exe , example.bat, totest.wav, and and 3 different config files:  JOCLoudness.zip

If you use the Example.bat remember to set PATH var to app directory!!!

if you detect any bug, or do you want to suggest improvements please email me!

One thought on “Command line”

Leave a comment