Liquidsoap

Introduction

This document provides a basic setup for using LiquidSoap to host your RadioReference feed. This document is written with a Debian Jessie system in mind. Other Debian/Ubuntu-based distributions should be similar.

Before you begin, you need to make sure your sound card is configured. See the article on ALSA for more information and instructions.

Installing LiquidSoap

To install LiquidSoap, run this command as root:

apt-get install liquidsoap

As long as you're using recommends on your installations, you should get everything you need. Particularly, MP3 support is needed and comes from the liquidsoap-plugin-lame package that is now in the normal repository. This will be installed if you're using recommends.

If you're using ALSA for your sound input, you may also need to install the plugin for ALSA. This is not included by default and can be installed with this command as root:

apt-get install liquidsoap-plugin-alsa

User Permissions for Audio Capture

For whatever reason, the default installation of liquidsoap from the repository on Debian doesn't actually give the liquidsoap user proper permissions to capture audio. If you're planning to run liquidsoap as a service on the system, you'll need to fix the permissions for the liquidsoap user. If you're running it any other way, the user account you use will need to be added to the audio group. Use this command as root:

usermod -aG audio <username>

Replace <username> with the literal name of the user (either liquidsoap or another account name).

Basic LiquidSoap Configuration

In the directory /etc/liquidsoap, create a file called radioref.liq with this content:

#!/usr/bin/liquidsoap -v
radio = input.alsa(device="<device>")
output.icecast(%mp3(stereo=false, bitrate=16, samplerate=22050),
 host="audio3.radioreference.com", 
 port=80, password="xxxxxxxxx", genre="Scanner", 
 description="Scanner audio", mount="/xxxxxxxx", 
 name="Baltimore Maryland Police/Fire/EMS", user="source",
 url="http://www.scanbaltimore.com", radio)

Replace <device> with the name of your ALSA device. If you followed the instructions in the ALSA article, you would have created a device to abstract your hardware. Use the name of this device here. If not, you can either use a direct ALSA reference to your hardware (such as "hw:0,0") or just remove the device="<device>" directive completely.

Because we added an interpreter line at the top of the file, we should mark it as executable using this command:

chmod +x /etc/liquidsoap/radioref.liq

Additional Uses

Once "radio" is defined and processed, this object can be used multiple times to serve multiple streams, or pull back input.alsa() to run different effects.

Using Another Stream as Input

You can also define another stream as an input source:

radio = (input.http(max=30.0, "http://path.to.stream/")):source(1,0,0))

If you do this, you will need to add 'fallible=true' to the output.icecast options.

Amplifying Input

If you need to amplify the input of the stream, you could do that using this modifier:

radio = amplify(2.0,input.alsa())

This was used the amplify after some friends complained about the low volume. The amplification made the input a comfortable volume for most people's defaults. A BCD-396T was feeding the sound card through line-in at volume level 3.

Additional Outputs

In the same file you can add additional outputs. For instance, if you are running your own icecast server at home, or have an OGG feed. An example line is below:

output.icecast.vorbis( host="www.scanbaltimore.com", port = 8000, 
 password = "xxxxxxxx", genre="Scanner", description="Scanner audio",
 mount="/xxxxxxx", name="Baltimore Maryland Police/Fire/EMS", user="source",
 url="http://www.scanbaltimore.com", stereo=false, quality=5.0, radio)

The OGG stream uses quality instead of bitrate as an option.

Logging Output to a File

If you'd like to log your output to a file, an MP3 output is most suitable because it will just log the MP3 chunks to a file. The example below provides a file that logs chunks every 15 minutes for an entire week. This creates a lot of files but can be very useful:

output.file(%mp3(stereo=false, bitrate=8, samplerate=8000),
 "/radioarchive/rr-feed-%w-%H_%M.mp3",
 reopen_when={0m or 15m or 30m or 45m},
 radio)

The file above will be named by weekday number (0-6), hour, and minute of start). You can refer to the liquidsoap documentation for additional substitution variables.

Test Your Configuration

Using the user account that will run the stream, test the stream first. This example uses the liquidsoap user account. Replace the username with the account that will actually run liquidsoap.

su - liquidsoap -c "/etc/liquidsoap/radioref.liq"

You should see a message that the stream has started running and it should not exit immediately. If it does exit immediately, you'll need to review the output.

If everything is successful, exit the run using Ctrl+C. Next, test it as a service using root if you plan to run it this way on the system (recommended):

service liquidsoap start

Check the log file at /var/log/liquidsoap/radioref.log to make sure there are no errors. Also verify that the process is running using this command:

ps aux | grep liquidsoap

You should see an output like this:

liquids+  6907  5.0  1.0  97236  9992 ?        Sl   00:01  60:44 /usr/bin/liquidsoap -d /etc/liquidsoap/rr8770.liq

Troubleshooting the File Not Found Problem

You may see an error with ALSA reporting File Not Found in the liquidsoap log. If this is the case, I've found this to be because the user account you're using is not part of the audio group on the system. See the instructions above to resolve this.

Configure LiquidSoap for Startup

If you're using LiquidSoap as a service on the system, configure it to start automatically using this command as root:

update-rc.d liquidsoap enable

LiquidSoap Documentation

LiquidSoap has a tremendous number of features. You can find additional documentation and API information here.