Machine readable results

Separator characters in the machine readable results file

Machine readable results file format

MXF audio remixing

The MXF Problem

MXF remix map

Default MXF remix map

File specific MXF remix map

Detailed explanation of the channel remixing feature

FFmpeg / Libav-tools allowed wrapper and codec formats





Machine readable results

FreeLCS 3.0 lets you define how it outputs its results. Most users will want the old behavior from FreeLCS version up to 2.4 that is: create a loudness corrected audio file, a history graphics file and delete multistream files immediately after all audiostreams have been extracted to individual files (multistream extraction requires installation of FFmpeg or libav-tools). This "old" behaviour is achieved by setting "Use FreeLCS file output defaults" to "Yes".

If you would like to integrate FreeLCS as a loudness measurement step in your automated file processing workflow, then you might want to change the defaults.





When you set "Use FreeLCS file output defaults" to "No", then you can change settings for the output files FreeLCS creates.

If your FreeLCS - machine is the loudness measurement step in an automated file processing workflow, then you might want to disable some output file creation. You can prevent creation of loudness corrected files and history graphics files. You can also prevent FreeLCS from deleting multistream input files after audio extraction if you need the original file to remain on the disk for further processing.

FreeLCS 3.0 is also able to output loudness measurement results in a machine readable file. You might want this if some other device needs to read in loudness measurement results to make a decision about how the file is processed further.



Separator characters in the machine readable results file

There can be many audio streams in one input file, FreeLCS writes these streams to individual audio files before loudness processing (multistream support requires FFmpeg or libav-tools). As a single input file can result in many output files, the machine readable results file may consist of loudness results of many audio files.

Loudness measurement results of a single file needs to be separated from each other by a known character or group of characters for a machine be able to interpret the results. If the input file resulted to many output files, then we need to separate each record of results with another known character or group of characters. The separator characters must be chosen from a group of characters that can never appear in a file name.

This problem has been solved when the ASCII character set was designed. The designers assigned two characters for this job: ASCII character 31 is meant for separating different values from each other and ASCII character 30 is meant for separating different records of data from each other. Character 31 is called the Unit Separator and character 30 is called the Record Separator. The operating system doesn't allow these characters in file names, so they are safe to use as data separators.

The machine readable results file is a simple text file with loudness measurement results written to it. Sometimes there might be reason for a person to open a machine readable results file in a text editor to check the values inside it. This is not possible if the ASCII character 30 is used as the record separator. In this case the user sees the results as one huge continuous line of text. This is why I chose to use the windows line feed string (ASCII character 13 followed with character 10) as the default record separator. When this record separator is used, then a machine readable results file becomes much more readable when opened in a text editor, because the editor splits results for individual audio files as separate lines of text.

However you can select any non printable ASCII character as the unit and record separator. You can use 1 or 2 character strings for each.


Machine readable results file format

The machine readable results file name is constructed like this:  InputFileName-machine_readable_results.txt

Example: Input file name is:  Euroviisut-2007-Final.mp4

Machine readable results file name is:  Euroviisut-2007-Final.mp4-machine_readable_results.txt

When you know the name of the input file, then you can get the machine readable results file name just by appending "-machine_readable_results.txt" to the name.


A machine readable results file has information about all audio streams of a single input file. Values for a single output stream are separated with the unit separator string. The record separator string is placed where a record of values for one audio stream ends and a record of values for the next audio stream begins. Unit and record separator strings are both defined during FreeLCS installation.


The items in the machine readable results file are:

Note: item count starts from zero.


00 = The number of this audio stream.
01 = Total number of supported streams in the input file.
02 = Total number of streams in the input file.
03 = Create Loudness Corrected Files (True / False).
04 = Number of files in this audio stream.

05 = Integrated Loudness (I) (If loudness is below measurement threshold, then this value is 'inf').
06 = Loudness Range (LRA).
07 = Highest Peak (dBTP or dBFS depending which measurement method the user selected during installation).
08 = Number Of Channels in this audio stream.
09 = Sample Rate.
10 = Bit Depth.
11 = Duration rounded to seconds.


12 = Loudness calculation error code (Codes explained below).
13 = Reason for error (text string).


14 = List of output filenames.


Detailed explanations of the items:

Items 00 - 04:

Items 05 - 11:

Items 12 - 13:

Items 14:



Error codes for item number 12:

0 = No Errors
1 = Loudness is below measurement threshold (-70 LUFS)
2 = Error in integrated loudness calculation
3 = File transfer failed
4 = Audio duration is less than 1 second
5 = Zero channels in audio stream
6 = Channel count bigger than 6 is unsupported
7 = No Audio Streams Found In File
8 = Sox encountered an error
9 = There are unsupported audio streams in input MXF - file while MXF audio remixing function is on. When MXF audio remixing feature is on, then this situation may produce unexpected results meaning that audio channels inside the MXF file might be combined in ways that the user did not anticipate. MXF audio remixing works correctly only when FreeLCS is able to process all files inside the MXF wrapper.
10 = File wrapper format is not supported
11 = Audio compression codec is not supported
100 = Unknown Error

If you want a machine to interpret the values inside the machine readable file, then you first must check the item 12 for errors. If item 12 is zero, then FreeLCS successfully processed the file. Then check item 1 for information about how many output files resulted from the input file. Item 1 tells you how many loudness results you need to read (one record of results for each supported input stream). Now you can read in the loudness measurement results for each supported input stream (items 5 - 7 for each record). If item 12 is not zero, then an error happened and there are no loudness calculation results to read (exception error code 9). The error number tells you what the the error was and the error message text is located in item 13.

Example 1:

FreeLCS has processed a input file that has only one audio stream in it. It is a wav file named: Test_File-01.wav  The machine readable results file name is:  Test_File-01.wav-machine_readable_results.txt

The values inside the machine readable results file are below. Note that I have changed the unit separator character to comma here to make the text more human readable :)

1, 1, 1, True, 1, -22.9, 12.2, -6.7, 2, 48000, 16, 3070, 0,  , Test_File-01_-23_LUFS.wav


Example 2:

FreeLCS has processed a transport stream file that had 14 audio streams in it. All streams were first saved to separate files and then went through loudness processing.

The input file name was:  20120712-2000-0000091191.mpg  and the machine readable results file name was:  20120712-2000-0000091191.mpg-machine_readable_results.txt

The result records for the files are separated by the record separator, in this case it is ASCII characters 13 and 10 (which is the code that instructs a text editor to split the text to separate text lines).

There are now 14 records of results because the one input file resulted in 14 output files. Note that there was an error processing streams 4 and 6. The streams were present in the transport stream, but they had zero audio channels.

The values inside the machine readable results file are below. Note that I have changed the unit separator character to comma here to make the text more human readable :)


1, 12, 14, True, 1, -21.5, 10.7, -8.5, 2, 48000, 16, 600, 0,  , 20120712-2000-0000091191-AudioStream-1-ChannelCount-2_-23_LUFS.wav
2, 12, 14, True, 1, -18.0, 4.2, -0.6, 2, 48000, 16, 600, 0,  , 20120712-2000-0000091191-AudioStream-2-ChannelCount-2_-23_LUFS.wav
3, 12, 14, True, 1, -24.0, 13.0, -5.8, 2, 48000, 16, 600, 0,  , 20120712-2000-0000091191-AudioStream-3-ChannelCount-2_-23_LUFS.wav
4, 12, 14, True, 0, 0, 0, 0, 0, 0, 0, 0, 5, There are zero audio channels in stream number 4, 
5, 12, 14, True, 1, -20.7, 11.3, -6.7, 2, 48000, 16, 600, 0,  , 20120712-2000-0000091191-AudioStream-5-ChannelCount-2_-23_LUFS.wav
6, 12, 14, True, 0, 0, 0, 0, 0, 0, 0, 0, 5, There are zero audio channels in stream number 6, 
7, 12, 14, True, 1, -17.2, 12.6, -6.1, 2, 48000, 16, 600, 0,  , 20120712-2000-0000091191-AudioStream-7-ChannelCount-2_-23_LUFS.wav
8, 12, 14, True, 1, -24.8, 10.7, -10.1, 2, 48000, 16, 58, 0,  , 20120712-2000-0000091191-AudioStream-8-ChannelCount-2_-23_LUFS.wav
9, 12, 14, True, 1, -23.9, 3.1, -9.7, 2, 48000, 16, 600, 0,  , 20120712-2000-0000091191-AudioStream-9-ChannelCount-2_-23_LUFS.wav
10, 12, 14, True, 1, -23.4, 10.0, -4.2, 2, 48000, 16, 600, 0,  , 20120712-2000-0000091191-AudioStream-10-ChannelCount-2_-23_LUFS.wav
11, 12, 14, True, 1, -22.6, 6.6, -7.5, 2, 48000, 16, 600, 0,  , 20120712-2000-0000091191-AudioStream-11-ChannelCount-2_-23_LUFS.wav
12, 12, 14, True, 1, -18.8, 14.1, -1.6, 2, 48000, 16, 600, 0,  , 20120712-2000-0000091191-AudioStream-12-ChannelCount-2_-23_LUFS.wav
13, 12, 14, True, 1, -20.0, 2.8, -8.2, 2, 48000, 16, 600, 0,  , 20120712-2000-0000091191-AudioStream-13-ChannelCount-2_-23_LUFS.wav
14, 12, 14, True, 1, -21.4, 8.2, -3.5, 2, 48000, 16, 600, 0,  , 20120712-2000-0000091191-AudioStream-14-ChannelCount-2_-23_LUFS.wav



Example 3:

FreeLCS has processed a file that had 16 audio streams in it. EBU R128 only supports channel counts up to 6, but streams 1 - 10 had more than 6 channels each resulting in an error. The name of the input file was:  16_audio_streams.mkv  and the name of the machine readable results file was:  16_audio_streams.mkv-machine_readable_results.txt

The values inside the machine readable results file are below. Unit separator character has been changed to comma here to make the text more human readable.


1, 6, 16, True, 0, 0, 0, 0, 0, 0, 0, 0, 6, There are 12 channels in stream 1, only channel counts from one to six are supported, 
2, 6, 16, True, 0, 0, 0, 0, 0, 0, 0, 0, 6, There are 15 channels in stream 2, only channel counts from one to six are supported, 
3, 6, 16, True, 0, 0, 0, 0, 0, 0, 0, 0, 6, There are 13 channels in stream 3, only channel counts from one to six are supported, 
4, 6, 16, True, 0, 0, 0, 0, 0, 0, 0, 0, 6, There are 14 channels in stream 4, only channel counts from one to six are supported, 
5, 6, 16, True, 0, 0, 0, 0, 0, 0, 0, 0, 6, There are 11 channels in stream 5, only channel counts from one to six are supported, 
6, 6, 16, True, 0, 0, 0, 0, 0, 0, 0, 0, 6, There are 16 channels in stream 6, only channel counts from one to six are supported, 
7, 6, 16, True, 0, 0, 0, 0, 0, 0, 0, 0, 6, There are 10 channels in stream 7, only channel counts from one to six are supported, 
8, 6, 16, True, 0, 0, 0, 0, 0, 0, 0, 0, 6, There are 9 channels in stream 8, only channel counts from one to six are supported, 
9, 6, 16, True, 0, 0, 0, 0, 0, 0, 0, 0, 6, There are 8 channels in stream 9, only channel counts from one to six are supported, 
10, 6, 16, True, 0, 0, 0, 0, 0, 0, 0, 0, 6, There are 7 channels in stream 10, only channel counts from one to six are supported, 
11, 6, 16, True, 1, -18.4, 0.0, -23.0, 6, 48000, 24, 20, 0,  , 16_audio_streams-AudioStream-11-ChannelCount-6_-23_LUFS.wav
12, 6, 16, True, 1, -18.4, 0.0, -23.0, 5, 48000, 32, 20, 0,  , 16_audio_streams-AudioStream-12-ChannelCount-5_-23_LUFS.wav
13, 6, 16, True, 1, -19.2, 0.0, -22.1, 4, 48000, 8, 20, 0,  , 16_audio_streams-AudioStream-13-ChannelCount-4_-23_LUFS.wav
14, 6, 16, True, 1, -21.2, 0.0, -23.0, 3, 48000, 16, 20, 0,  , 16_audio_streams-AudioStream-14-ChannelCount-3_-23_LUFS.wav
15, 6, 16, True, 1, -23.0, 0.0, -23.0, 2, 48000, 24, 20, 0,  , 16_audio_streams-AudioStream-15-ChannelCount-2_-23_LUFS.wav
16, 6, 16, True, 1, -26.0, 0.0, -23.0, 1, 48000, 32, 20, 0,  , 16_audio_streams-AudioStream-16-ChannelCount-1_-23_LUFS.wav



Example 4:

FreeLCS has processed a file that had 3 streams in it. The file is 3 hous 12 minutes long and first stream is 5.1 audio. The first stream is so big that the output file size would have exceeded wav format max size of 4 GB, so FreeLCS split this 5.1 file to one file per audio channel resulting in 6 output files.

The name of the input file was:  Euroviisut-2007-Final.mp4  and the name of the machine readable results file was:  Euroviisut-2007-Final.mp4-machine_readable_results.txt

The values inside the machine readable results file are below. Unit separator character has been changed to comma here to make the text more human readable. Also note that the first line of text is so long that its wraps around here to the next line, the 3 different audio streams are separated by an empty line here for better readability.


1, 3, 3, True, 6, -14.8, 4.4, -0.8, 6, 48000, 16, 11554, 0,  , Euroviisut-2007-Final-AudioStream-1-ChannelCount-6-Channel-1_-23_LUFS.wav, Euroviisut-2007-Final-AudioStream-1-ChannelCount-6-Channel-2_-23_LUFS.wav, Euroviisut-2007-Final-AudioStream-1-ChannelCount-6-Channel-3_-23_LUFS.wav, Euroviisut-2007-Final-AudioStream-1-ChannelCount-6-Channel-4_-23_LUFS.wav, Euroviisut-2007-Final-AudioStream-1-ChannelCount-6-Channel-5_-23_LUFS.wav, Euroviisut-2007-Final-AudioStream-1-ChannelCount-6-Channel-6_-23_LUFS.wav

2, 3, 3, True, 1, -10.4, 8.5, 1.3, 2, 48000, 16, 11554, 0,  , Euroviisut-2007-Final-AudioStream-2-ChannelCount-2_-23_LUFS.wav

3, 3, 3, True, 1, -16.8, 7.8, -3.1, 2, 48000, 16, 11554, 0,  , Euroviisut-2007-Final-AudioStream-3-ChannelCount-2_-23_LUFS.wav




MXF audio remixing

FreeLCS 3.0 lets you define how you want audio inside an MXF file to be recombined before loudness processing. This feature is called MXF audio remixing.

If you want to use MXF audio remixing, then you must install FFmpeg or libav-tools and allow MXF wrapper format processing during FreeLCS installation.

Important note: This function is not guaranteed to work !!!!!!! MXF is not one format, but a family of formats (more info on Wikipedia). Every hardware and software vendor seem to have their own version of it. MXF files created with one device might not be compatible with a device created by another vendor. Because of this there is no guarantee that FreeLCS can process every MXF - file you feed it. It might be a good idea to do a thorough test with a large set of different MXF files before you make this feature part of your workflow.


The MXF Problem

Consider an example where video and audio of a program is wrapper inside an MXF wrapper. The program has two versions of the audio: a stereo version (2 channels) and an 5.1 version (6 channels). Audio might be stored inside the MXF wrapper as one 8 channel audio file (Example 1), or as 8 separate mono files (Example 2).

Example 1:

Input #0, mxf, from 'Testfile-1.mxf':
    Duration: 00:45:37.20, start: 0.000000, bitrate: 59232 kb/s
        Stream #0.0: Video: mpeg2video (4:2:2), yuv422p, 1920x1080 [PAR 1:1 DAR 16:9], 50000 kb/s, 25 fps, 25 tbr, 25 tbn, 50 tbc
       Stream #0.1: Audio: pcm_s24le, 48000 Hz, 8 channels, s32, 9216 kb/s

Example 2:

Input #0, mxf, from 'Testfile-2':
    Duration: 00:45:37.20, start: 0.000000, bitrate: 60157 kb/s
        Stream #0.0: Video: mpeg2video (4:2:2), yuv422p, 1920x1080 [PAR 1:1 DAR 16:9], 50000 kb/s, 25 fps, 25 tbr, 25 tbn, 50 tbc
       Stream #0.1: Audio: pcm_s24le, 48000 Hz, 1 channels, s32, 1152 kb/s
       Stream #0.2: Audio: pcm_s24le, 48000 Hz, 1 channels, s32, 1152 kb/s
       Stream #0.3: Audio: pcm_s24le, 48000 Hz, 1 channels, s32, 1152 kb/s
       Stream #0.4: Audio: pcm_s24le, 48000 Hz, 1 channels, s32, 1152 kb/s
       Stream #0.5: Audio: pcm_s24le, 48000 Hz, 1 channels, s32, 1152 kb/s
       Stream #0.6: Audio: pcm_s24le, 48000 Hz, 1 channels, s32, 1152 kb/s
       Stream #0.7: Audio: pcm_s24le, 48000 Hz, 1 channels, s32, 1152 kb/s
       Stream #0.8: Audio: pcm_s24le, 48000 Hz, 1 channels, s32, 1152 kb/s


Audio from these MXF files can't be processed with FreeLCS because it has no knowledge about which files belong to the same audio version (mix). This information can be provided to FreeLCS in the form of a MXF remix map.


MXF remix map

A MXF remix map tells FreeLCS how audio channels inside a MXF file must be recombined before loudness processing. When a remix map is active then FreeLCS first extracts audio from the MXF wrapper and then recombines audio channels according to the remix map and writes each resulting mix to a separate audio file. Then FreeLCS moves these files to the HotFolder so that they go through the normal loudness processing.


Default MXF remix map

You can define a default remix map during FreeLCS installation. This default map is used when there is no other information available about a specific MXF file.

In the picture below a green number above a box corresponds to the number of the mix. The number inside a box defines how many audio channels this mix has. A total of 48 remix parameters can be defined meaning that channels inside an MXF file can be recombined to max 48 new audio files. The default remix map is all number 2's. This means that if there is no file specific MXF remix map found then recombine all audio files found inside a MXF file to stereo files.

If you know all your MXF files have these four mixes:
  1. Stereo
  2. 5.1
  3. Stereo
  4. Stereo

Then you could define a default remix map of: 2, 6, 2, 2  meaning that you put number 2's in boxes 1, 3 and 4 and number 6 in box 2. You can have more mix definitions than you have physical audio channels inside your MXF files, FreeLCS only recreates those mixes that can be completely created with audio channels available in the MXF file. If there are more audio channels inside an MXF file than is needed to recreate all mixes in the remix map, then the extra channels are not used for anything.



File specific MXF remix map

In addition to the default remix map the user can use file specific MXF remix maps. A file specific remix map overrides the default remix map defined during installation. For example if most of your files have the same channel configuration, then you would assign this configuration to the default MXF remix map during FreeLCS installation. Once in a while you might want to process a file that has a channel configuration differing from your regular MXF files. In this case you could override the default channel configuration only for this file with a file specific remix map.


A file specific remix map is a simple text file that contains channel counts separated with a comma. The name of the remix map file is always the same as the name of the MXF file it is used for, except the file extension of the original file ".mxf" is replaced with ".remix_map". You can have more mix definitions than you have physical audio channels inside your MXF file, FreeLCS only recreates those mixes that can be completely created with audio channels available in the MXF file. If there are more audio channels inside an MXF file than is needed to recreate all mixes in the remix map, then the extra channels are not used for anything.


Example:

The user wants to extract 5 mixes from an MXF file. These mixes are: stereo, 5.1, stereo, stereo, 5.0

MXF file name:  Testfile.mxf     
Remix map file name:  Testfile.remix_map
Contents of the remix map file:  2,6,2,2,5

As you can see, it is very easy to use file specific remix maps. You just create a text file and put some numbers in it separated by commas. The numbers are the channel counts for each mix you want FreeLCS to recombine before loudness processing.

Important: a file specific remix map must be in the FreeLCS HotFolder BEFORE the MXF file arrives there. FreeLCS checks once for each MXF file if it can find the corresponding file specific remix map, and if it is not found then FreeLCS processes the file according to the information it has available then. FreeLCS won't check for the existence of a remix map again after processing has started.


Detailed explanation of the channel remixing feature

I have seen some very peculiar MXF files. One file had several mono audio files in it except in between the mono files there was a single stereo file. How is FreeLCS supposed to know from which file to take the audio channels user has defined in a remix map ? Because of this peculiarity I designed FreeLCS to be "blind" to the physical audio files inside a MXF file, FreeLCS only "sees" a bunch of audio channels available to it. FreeLCS does not care which physical file the channel comes from, it just uses channels starting from file 1 channel 1 and going forward to the next file until it gets all channels needed to fulfill a channel count defined in a remix map.


Example:

Most MXF files will have several mono files or 8 channel files inside but consider this theoretical example. Suppose the channel counts in audio files inside a MXF file was:

Audio file 1: channels 1
Audio file 2: channels 2
Audio file 3: channels 3
Audio file 4: channels 4

What happens if the user defines a channel map where required channel counts for each mix to recreate is the opposite of the available channels inside the MXF:

Remix map: 4, 3, 2, 1


This is how FreeLCS gets channels for each channel count defined in the remix map:


Channels left in physical audio files before processing starts: 1, 2, 3, 4


Remix map item 1 needs 4 channels: FreeLCS  takes all channels from physical files: 1 and 2 totalling 3 channels, then it needs one more channel and takes the first channel of file 3. After the first mix is created channels left in physical audio files: 0, 0, 2, 4.

Remix map item 2 needs 3 channels: FreeLCS takes the 2 channels that are left in physical file 3 and then the first channel from physical file 4. After the second mix is created channels left in physical audio files: 0, 0, 0, 3.

Remix map item 3 needs 2 channels: FreeLCS takes channels 2 and 3 that are still unused in physical file 4. After the third mix is created channels left in physical audio files: 0, 0, 0, 1.

Remix map item 4 needs 1 channels: Then we only have channel 4 left of physical file 4 and that fulfills the last remix map definition for 1 channels. After the fourth mix is created channels left in physical audio files: 0, 0, 0, 0.



FFmpeg / Libav-tools allowed wrapper and codec formats

In FreeLCS 3.0 it is possible to restrict FFmpeg / libav-tools to only process a small set of formats or allow it to process all formats it supports. This feature is mainly designed to allow the user to restrict processing only to patent free formats even when FFmpeg or libav-tools is installed. Format patentability varies from country to country, see more about it in FAQ.


If you enabled MXF remixing, then you must install FFmpeg or libav-tools and allow MXF wrapper format processing. In the picture below libav-tools is allowed to process all formats it supports (All includes MXF :)





In the following picture libav-tools processing has been restricted to wrapper formats: Wav, Flac, Ogg, Matroska, MXF, Webm  and  codec formats: PCM, Flac, Vorbis.




The option "All Mpeg" enables wrapper formats: mpeg, mp2, mp3, mp4, m4v, m4a, mpegts, mpegtsraw, mpegvideo, mpeg1video, mpeg2video, vcd, svcd, dvd, vob. Some of these might be still patented and require a licence from the rights holder (see FAQ).