Debian Package of the Day (static archived copy)

Article submitted by Romain Beauxis. We have run out of good articles! Please help DPOTD and submit good articles about software you like!

Presentation

Liquidsoap is a powerful audio stream generator designed to work with icecast as a source client. It was built for the campus net-radio of the Ecole Normale Supérieure de Lyon. The tough requirements included: accepting user requests, handling remote files and play lists, scheduling special programs, mixing jingles in the stream, interacting with the website or an IRC bot, etc.

The special thing of Liquidsoap is that instead of building an ad-hoc solution for that single net-radio, it was developed as a flexible tool with which you can combine as you like the features that you want. Hence, it has then been used successfully for several other net-radios, for which the usual streaming tools weren’t enough.

Design

Describing an audio stream can be very complex: several inputs (files, stream relaying, sound card input) that can be combined in various ways (audio processing, mixing, track scheduling, fall-backs) and finally be output in various other ways (several servers, contents and formats). To make it easy without losing expressive power, Liquidsoap uses its own little scripting language for configuration.

That language has a notion of audio stream and request, and has built-in functions for combining streams in various ways. Some of its main features are:

• It is statically typed: your stream never crashes because you made a typo in a dark corner of the configuration.
• Types are inferred: you don’t have to write them.
• It is functional: you can define your own compound operations, but functions are also used to describe transitions from one stream to another.

Liquidsoap is quite versatile: it can be used as a daemon or as a command-line tool, and is not restricted to streaming to an icecast server, it can also stream to your local sound card!

Usage

If you are not aware of the way a web radio can be built using icecast, you may want to read some more documentation on this topic. In short, icecast accepts sources connections, and relays the data from these sources to its listeners. Liquidsoap acts as a source.

Let’s begin with a very simple example… Let’s say that you run an icecast server at host myhost with the password for sources being hackmeimcool, and you want to stream in Ogg/Vorbis a single looped file (it can be Ogg/Vorbis, MP3, WAV, even AAC on the SVN version). Then this may do the job for you:

$ liquidsoap 'output.icecast.vorbis(host="myhost",password="hackmeimcool",
  mount="mystream.ogg",single("/path/to/my/file"))'

Another possible usage is to relay a net-radio to your sound card using libao. For this you may try:

$ liquidsoap 'output.ao(fallback(track_sensitive=false,
  [input.http("http://www.dolebrai.net:8000/dolebrai.ogg"),blank()]))’

Liquidsoap can also be used as a scripting language, so the following does both previous examples:

#!/usr/bin/liquidsoap

# Set log to stdout and /tmp
set log.stdout = true
set log.dir = "/tmp"

# Output a file to an icecast server
file = single("/path/to/my/file")
output.icecast.vorbis(host="myhost",password="hackmeimcool",
        mount="mystream.ogg",file)

# Output a net-radio locally:
radio = fallback(track_sensitive=false,[input.http("http://www.dolebrai.net:8000/dolebrai.ogg"),blank()])
output.ao(radio)

Conclusion

The complete API is available here. We have not presented many cool features, such as:

• sound effects;
• custom transitions;
• sound card I/O;
• interaction with other components (website, external scheduler) in a more complex framework;
• many others…

Liquidsoap is already used in various net-radios, such as Dolebrai which streams libre music, and RadioPi which has a complex multi-server and multi-stream configuration.

This presentation of Liquidsoap was very very short… This is not the place for a tutorial, so let’s finish instead with a power user example, which I hope will make you eager to learn more. Just download and run, there’s nothing to edit!

Usage:

• Download this as test.liq
• Run it with this command: liquidsoap test.liq and listen!

Optionally you can test the following:

$ telnet localhost 1234

q.push /path/to/file

If you are interested in a very flexible way to design your audio stream, feel free to visit our website, drop us a mail at savonet-users@lists.sourceforge.net or join our IRC channel, #savonet at Freenode. Liquidsoap is available in Debian testing and unstable, it hasn’t been uploaded to Ubuntu yet.