FreeLCS User Manual


Introduction

Features

Requirements

Debian modifications needed before installation

Ubuntu Server modifications needed before FreeLCS installation

Installation

Installing FreeLCS on a computer without a graphical user interface

FFmpeg / Libav-tools allowed wrapper and codec formats

Files that FreeLCS creates in your system

Usage

Loudness History Graphics

Machine readable results

MXF audio remixing

Mounting the server HotFolder from OS X

Making an permanent alias to the mount from OS X

Mounting the server HotFolder from windows 7

Making the mount permanent in windows 7

Html Progress Report

Static ip - address for the server

Static ip - address for Ubuntu Server and Debian without a GUI

Optimizing processing speed

Configuring software Raid

How to partition disks bigger than 2 TB on Linux

Notes on loudness correction usage

Setting up automatic security updates

Automatic security updates on Ubuntu Server and Debian

Synchronizing clock to a NTP time server

Cloning a FreeLCS installation to another machine (without a display)

How to report a bug

Run FreeLCS programs so that possible error messages can be seen

FreeLCS development

FAQ


















Introduction

FreeLCS stands for Free Loudness Correction Server. FreeLCS lets you automatically correct audio files to EBU R128 target loudness level.

The software lets you easily set up a server that shares one of it's folders to the network. Users of your network can then drop audio files to the server for automatic loudness correction. For each processed file the server also creates a loudness history graphics file which shows loudness variations inside the file.

The software is very fast even on modest hardware giving 15 times faster than realtime processing (16 bit stereo files, TruePeak measurement turned on) on a server with one Intel Core 2 Duo processor, 2 GB Ram, 3 internal Sata disks in software RAID 0.

FreeLCS uses other open source programs to get the job done (Linux, libebur128, gnuplot, FFmpeg / libav-tools (optional), sox, mediainfo). All software is free and Open Source.


Features




Requirements



Installation

Note that FreeLCS installation always requires connection to the internet, since the installer fetches needed packages from the net.

The installation instructions below apply to Ubuntu Desktop. This is the most user friendly of the supported operating systems. Installation on other supported platforms differs from the instructions below.

If you use Ubuntu Server (Ubuntu version without any graphical user interface) then the installation procedure is described here.

If you use Debian Desktop (with a graphical user interface), then you first need to make some modifications to the Debian system and then you can follow installation instructions for Ubuntu Desktop below. Things that needs to be done differently on Debian are pointed out in the instructions.






sudo apt-get update

sudo apt-get -y install python3 idle3


















If the installer program opens up in a text editor instead of showing you the window above, then the file manager you are using prevents the program from running. This happens at least on Ubuntu 14.04.























































Files that FreeLCS creates on your system

FreeLCS writes some files onto your disk. In addition to installing some programs FreeLCS needs to do it's job, it also writes files that start up FreeLCS every time the computer starts.

Installed programs:

If you want to uninstall FreeLCS you can remove these programs with the following terminal command:

sudo apt-get remove mediainfo sox gnuplot samba

FreeLCS needs sox 14.4.0 and if you are running an older os version (Ubuntu 12.04), then the sox version available in os package repositories is older than 14.4.0. In this case FreeLCS installer compiles sox 14.4.0 from source code. Libebur128 is always compiled from source.

You can find out where the compiled programs are installed with the following terminal commands:

which loudness
which sox


You can remove these programs with these commands (replace the "path_to_command" with the output from the "which" command above):

sudo rm path_to_command


FreeLCS needs to start every time the computer starts up, so some start up scripts are created on your system. There are two different init systems used on the currently supported operating systems. "Init" is the traditional operating system start up system and "systemd" is a new one that got introduced in Debian 8. Ubuntu will also move to using systemd as their startup system.

Files created on an init based os (Ubuntu 12.04, 14.04, Debian 7):

/usr/bin/LoudnessCorrection.py
/usr/bin/HeartBeat_Checker.py
/etc/LoudnessCorrection_Settings.pickle
/etc/samba/smb.conf
/etc/init.d/loudnesscorrection_init_script
/etc/rc2.d/S99loudnesscorrection_init_script   (Only on Ubuntu 12.04 and 14.04)
/etc/rc2.d/S21loudnesscorrection_init_script  
(Only on Debian 7. The number at the start of the file name (S21loudnesscorrection_init_script) varies).

If you want to remove FreeLCS then stop FreeLCS and delete the startup files with these terminal commands:

sudo /etc/init.d/loudnesscorrection_init_script stop
sudo rm path_to_file  

Files created on a systemd based os (Debian 8, Ubuntu 16.04 and newer):

/usr/bin/LoudnessCorrection.py
/usr/bin/HeartBeat_Checker.py
/etc/LoudnessCorrection_Settings.pickle
/etc/samba/smb.conf
/etc/systemd/system/loudnesscorrection_init_script
/etc/systemd/system/freelcs.service

If you want to remove FreeLCS then stop FreeLCS and delete the startup files with these terminal commands:

systemctl stop freelcs.service
systemctl disable freelsc.service
rm path_to_file


Explanation of FreeLCS startup files:

/usr/bin/LoudnessCorrection.py
/usr/bin/HeartBeat_Checker.py
/etc/LoudnessCorrection_Settings.pickle
/etc/init.d/loudnesscorrection_init_script      (on systemd based oses the path is: /etc/systemd/system/loudnesscorrection_init_script)

/etc/rc2.d/S99loudnesscorrection_init_script

/etc/systemd/system/freelcs.service

/etc/samba/smb.conf



Usage

FreeLCS usage is very simple.
  1. First you mount FreeLCS HotFolder through the network.
  2. Then you drag some files to the HotFolder .
  3. A couple of minutes later you can drag loudness corrected files back from "HotFolder / 00-Corrected_Files" to your computer .

Mounting of the HotFolder is explained in it's own chapter.











Loudness History Graphics




Mounting the server HotFolder from OS X









Making an permanent alias to the HotFolder in OS X

When you have mounted the HotFolder you can make an alias for it that stays on your desktop. You can then skip all the steps above and mount the HotFolder just by double clicking on the alias.







Mounting the server HotFolder from windows 7












Making the mount permanent in windows 7

You can tell windows that you want the HotFolder always to be mounted when the computer starts up.












Html Progress Report

If you selected "Write html progress report" = "yes" in the installer then an html file will appear in "HotFolder / 00-Calculation_Queue_Information / 00-Calculation_Queue_Information.html". This file can be opend in an web-browser and it shows an view inside the loudness calculation queue. The html progress report is updated every 5 seconds and it shows how many files are waiting for a processing slot to open, what files are currently processed and the names of 100 last files that were processed and the time processing was finished.

The upper part of the window shows the names of next 10 first files that are coming in for processing and above that the total number of files waiting in queue is shown. Date and time are also shown and updated every 5 seconds. You can use the time display to easily check if the server is up and running.

The middle gray part shows the names of files that are currently being processed. The number of files that are simultaneously processed depends on what you selected as the "Number Of Processor Cores To Use" in the installer. Each file is simultaneously processed by two processor cores so if you selected six cores to be used, then three files are processed at the same time (in the example picture below 14 cores are assigned, so seven files can be processed simultaneously).

The bottom of the page shows the last 100 files that were processed.





Static ip - address for the server

The server needs to have an address that does not change. You network administrator can give you an static ip-address to use.

The following instructions are for Ubuntu Desktop. If your operating system is Ubuntu Server or Debian without a graphical desktop, then you need to follow the instructions here.























Optimizing processing speed

If you have a fast enough processor, for example 1 x Intel Core 2 Duo, then the processor is able to process files much quicker than a single hard disk is able to serve it. When multiple files are processed at the same time, there will be lots of reading and writing going on and the speed of the disk becomes the bottleneck of the system. You can get more speed out of you system by setting up three disks in a raid 0 array and putting the HotFolder onto the raid.

An alternative to software raid and multiple rotating disks is to use a single Solid State Disk (SSD) as the HotFolder disk. SSD - disks are very fast, but they have one disadvantage over traditional rotating disks. SSD - disks wear out much more quickly than traditional disk. Modern SSDs have hardware that tries to even out the wear that writing causes to SSD memory cells. A typical SSD has a life span that is roughly equal to a rotating disk when the SSD is in an environment that corresponds to typical desktop usage. If your FreeLCS - server processes lots of audio files all the time, then the SSD - disk is going to wear out sooner than expected. SSD might be a good solution if you buy two disks and keep the other as spare.

Another thing that affects processing speed is the setting "Number Of Processor Cores To Use" in the installer. Each file that is processed ties up two processor cores, but if you have a fast disk and a hyper-threading capable processor, you might get more speed by setting the "Number Of Processor Cores To Use" to a bigger number than you have actual physical processor cores.

After you have set up raid you can find the sweet spot of your system by doing a simple test.

First collect a bunch of typical files that the server is going to process when doing real work. The total size of the files should at minimum be double the size of ram you have on your server, but more files is better. Save the files on the server, but don't put them in the HotFolder yet.

  1. Delete all files from the HotFolder.
  2. Run the FreeLCS installer and set the "Number Of Processor Cores To Use" to the number of physical processor cores you have and reboot.
  3. Wait for FreeLCS to start up.
  4. Open the html-progress report in your web-browser and see that the time displayed on the page is advancing. If not then LoudnessCorrection is not running yet.
  5. Now you need to make the test files appear in the HotFolder. The quickest way to make this happen is to create hard links for the test files in the HotFolder. This makes the files appear immediately without making physical copies of the files.
date  ;  ln   /path_to_test_files/*   /path_to_hotfolder/
  1. This command displays the current time which also is the time files were linked to the HotFolder, take note of the time.
  2. Wait for processing to finish and take a look at the html-progress report and see the time the last files processing finished.
  3. Calculate the time it took.
  4. Repeat the process from step 1, but add two to the "Number Of Processor Cores To Use" in the installer.

You should find the fastest processing time in 2 - 4 rounds of the test.


Our test servers sweet spot is to use six cores even though there is only two physical processor cores. Our test server specs are:

1 x Intel Core 2 Duo Processor
2 GB Ram
1 TB hard disk for Ubuntu
3 x 1 TB hard disks in a software raid 0 array for the "HotFolder".
1 Gbit Ethernet


The speed test results for our test server were:


With more than 6 cores the processing time started to increase rapidly.


Configuring software Raid

Linux software raid configuration is a bit out of the scope of this document.  Here are the steps that were required to get our server's raid set up. The steps I followed were mostly from here: http://www.linuxhomenetworking.com/wiki/index.php/Quick_HOWTO_:_Ch26_:_Linux_Software_RAID


Warning !!!!!!!  Linux knowledge is required here. If you are not careful these commands can mess up your system  :)

cd /etc/mdadm

mv mdadm.conf mdadm.conf.orig

echo "DEVICE partitions" > /etc/mdadm/mdadm.conf

mdadm --detail --scan >> /etc/mdadm/mdadm.conf

/dev/md0: UUID="229f0670-c8c2-4145-b2f4-b1100d9cb918" TYPE="jfs"

UUID=229f0670-c8c2-4145-b2f4-b1100d9cb918    /mountpoint/raid-disk        auto    defaults    0 0


How to partition disks bigger than 2 TB on Linux

sudo parted -a optimal /dev/sdb
mklabel gpt
mkpart primary 0% 100%
set 1 raid on
quit


Notes on loudness correction usage



Setting up automatic security updates

The server can be made quite maintenance free by:
To make the server boot automatically after an power outage you need to find an option in the computers bios that says something like: "Restart after power failure".

Then tell Ubuntu to install security updates without human intervention. The following instructions apply to Ubuntu Desktop, if you are using Ubuntu Server or Debian then you need to follow instructions here.
  1. Press the "windows" key on the keyboard to bring up Ubuntu search function, write: update
  2. You should now see an icon for "Update Manager", start it up by clicking on it.





  1. Click on "Settings".





  1. Click on the "Updates" - tab and then on the box "When there are security updates:".





  1. Select "Download and install automatically" from the drop down list.




  1. Next the OS asks for your password.




  1. Click on "Close".





Now security updates are downloaded and installed automatically. Some of them are applied immediately but some of them (new versions of the Linux kernel) may come into effect only after a reboot.

Automatic weekly reboot with Crontab

sudo crontab -e

Ubuntu will prompt:

no crontab for root - using an empty one

Select an editor.  To change later, run 'select-editor'.

  1. /bin/ed
  2. /bin/nano        <---- easiest
  3. /usr/bin/vim.basic
  4. /usr/bin/vim.tiny

Choose 1-4 [2]:

This means that Ubuntu wants to know which text based text editor you would like to use to edit the crontab - file, press "2". This will select the "nano" - text editor.

Now the text editor opens up in Terminal and shows some text that Ubuntu automatically inserted into the crontab, navigate to the bottom of it and add the following line:


00 07 * * 1 /sbin/reboot

This command will reboot the computer every monday at 07:00 am. Save the crontab - file with the keyboard command ctrl + o, then press enter to accept the filename. Now that text is saved, exit the editor with the keyboard command ctrl + x. The crontab comes into effect immediately, no need to reboot.

The fields in the crontab commandline mean (from left to right):

Field                     Allowed Values

Minutes                 0-59
Hours                    0-23
Day of month        1-31 (* means every day)
Month                   1-12 (* means every month)
Day of week          0-7 (0 or 7 is Sun)

The last field is the full path to the command we want Cron to run.

Automatic weekly reboot with systemd

With systemd we need to create two text files that instructs systemd for what to do (reboot) and when (weekly at a specific time).

First create the file "reboot_weekly.service" that instructs systemd what to do (reboot). Startup the nano - editor to create the file with the command:

sudo nano /etc/systemd/system/reboot_weekly.service

Add the following content to the file:

[Unit]
Desciption=Reboot Weekly

[Service]
Type=simple

ExecStart=/sbin/reboot

Now create the file "reboot_weekly.timer" that instructs systemd when to run the task (every Monday morning at 07:00). Startup the nano - editor to create the file with the command:

sudo nano /etc/systemd/system/reboot_weekly.timer

Add the following content to the file:

[Unit]
Description=Reboot Weekly

[Timer]
OnCalendar=Mon *-*-* 00:07:00
Unit=reboot_weekly.service

[Install]
WantedBy=timers.target

Then we need to enable the timer with the command:

sudo systemctl enable reboot_weekly.timer  &&  systemctl start reboot_weekly.timer



Synchronizing clock to a NTP time server

If you have a NTP - server on your network, you can sync FreeLCS server clock to it daily using the ntpdate command.

On Ubuntu 12.04, 14.04 and Debian 7 automatic tasks are created with Crontab. On Debian 8, Ubuntu 16.04 and newer these tasks are created with systemd. Below there are instructions for both of these methods.

Get time with Crontab


See chapter: Setting up automatic security updates to see how to edit crontab.

The following line in crontab will sync the clock to timeserver 192.168.1.110 every day at 06:25 am.

25 06 * * * /usr/sbin/ntpdate 192.168.1.110


( Debian: ntpdate is not installed by default, you can install it with the command:   sudo apt-get -y install ntpdate )

Get time with systemd

With systemd we need to create two text files that instructs systemd for what to do (get time from a timeserver) and when (daily at a specific time).

First create the file "synchronize_clock.service" that instructs systemd what to do (get time). Startup the nano - editor to create the file with the command:

sudo nano /etc/systemd/system/synchronize_clock.service

Add the following content to the file:

[Unit]
Desciption=Synchronize Clock

[Service]
Type=simple

ExecStart=/usr/sbin/ntpdate 192.168.1.110

Now create the file "synchronize_clock.timer" that instructs systemd when to run the task (every day at 06:25 am). Startup the nano - editor to create the file with the command:

sudo nano /etc/systemd/system/synchronize_clock.timer

Add the following content to the file:

[Unit]
Description=Synchronize Clock

[Timer]
OnCalendar=*-*-* 00:06:25
Unit=
synchronize_clock.service

[Install]
WantedBy=timers.target

Then we need to enable the timer with the command:

sudo systemctl enable synchronize_clock.timer  &&  systemctl start synchronize_clock.timer


( Debian: ntpdate is not installed by default, you can install it with the command:   sudo apt-get -y install ntpdate )

Cloning a FreeLCS installation to another machine (without a display)

The 2.3 release of FreeLCS introduces a tool that can be used to backup and restore a FreeLCS installation. This functionality can be used to clone a installation to any number of Ubuntu machines. Neither the backup nor the restore scripts requires a graphical desktop and both can be run over a ssh - connection on a 'headless machine' .

This functionality is targeted at advanced users who know their way around Linux and the Terminal.

Note: the backup script can be found in FreeLCS zip - file in location: 'Backup_FreeLCS_configuration / 00-backup_freelcs_configuration.sh'.

Usage

  1. Install FreeLCS with the normal graphical installer and adjust settings the way you want.
  2. Then run '00-backup_freelcs_configuration.sh' to make a backup of the installation settings. Files needed for restoration and a restoration script will be created in directory 'freelcs_backup'.
  3. Copy the contents of dir 'freelcs_backup' to all machines that you want to have the same configuration and run the restoration script '00-restore_freelcs_configuration.sh' on each.
  4. The restoration script will install all programs and scripts that FreeLCS needs to function. After restoration all machines will have identical FreeLCS installation.
  5. Reboot the machines or start loudness correction scripts manually (restoration script displays the startup command at the end of the run).
Result: The FreeLCS installation has been cloned to several machines.

Important notes:



How to report a bug

If you have found an error in FreeLCS software or documentation please report it so that it can be corrected.

If you find that FreeLCS software crashes or behaves in ways it should not, try first to find out if the problem is caused by a file in the HotFolder. If a certain file or file format causes the problem please make a copy of the file / files for later use. The files might be needed to confirm that the bugfix really solves the problem.

When you file a bugreport keep in mind that the developer needs to be able to reproduce the bug in his own system in order to fix it. So when reporting a bug report the following:
Report bugs here (requires creating an free account): https://sourceforge.net/p/freelcs/tickets/
When you have logged in navigate to the link above and click the "Create Ticket" - button on the left. When you create a ticket, the developer gets the bugreport in email.





Run FreeLCS programs so that possible error messages can be seen

LoudnessCorrection.py


LoudnessCorrection.py is the program that is responsible for processing the files that appear in the HotFolder. Normally LoudnessCorrection.py runs in the background and has no way to display error messages to the user. The program can however be manually started in the Terminal.

Now there are two ways to run LoudnessCorrection.py, the first one discards all settings user defined in the installer and runs with default settings. When you run the program in this mode you need to add the full path to the target directory at the end of the command. The target directory is the directory which has Hotfolder "LoudnessCorrection" inside it. Note that running the program like this the language defaults to english meaning the program expects the HotFolder name to be "LoudnessCorrection".

Note that when running in this mode the program outputs a lot of text, it tells all the time what it is doing.


The second way to run LoudnessCorrection.py is to use the settings that user defined in the installer. The settings are stored in file /etc/Loudness_Correction_Settings.pickle


When running in this mode there will be no output unless the program crashes.


HeartBeat_Checker.py


HeartBeat_Checker does not display anything unless it crashes.



Installer.py

Installer only displays something if it crashes.


Typical Python error message

If a program crashes then the Python3 interpreter displays an error message telling what went wrong. A typical Python error message looks like this:





If you get a message like this please copy it to the bug report. This message is valuable since it tells the developer exactly on which line of the program code the error happened.

To copy text from the Terminal first select the text to be copied and then copy it with the keyboard command: shift + ctrl + c

Paste the text to the bug report.


FreeLCS development

FreeLCS development happens on Github ( https://github.com/mhartzel/freelcs). All new versions of software are uploaded there before official release. Unreleased versions are untested so it is recommended that normal users do not use these versions on their production servers. The reason for this is that when new program code is added and old is modified it is possible that new bugs creep in.

If however you have encountered a bug you can navigate to that webpage and check the changelog there (Documentation/Changelog.txt) to see if the bug has already been fixed. If you want to test the latest software versions you can download all files in the git-repository like this: