Liquidsoap

Website	http://liquidsoap.info/
License	GPL
OS	GNU/Linux, OS X, Windows
Media	Streaming media
Format	OGG, MP3
Interface	Specialised programming language
Wikipedia	http://en.wikipedia.org/wiki/Draft:Liquidsoap
Thumbnail

NB: The version of liquidsoap currently installed via apt is 1.3.3 (while the latest version is 1.4.2). The links on this page are for this older version.

https://www.liquidsoap.info/doc-1.3.3/

Cookbook

From: https://www.liquidsoap.info/doc-1.3.3/cookbook.html

The recipes show how to build a source with a particular feature. You can try short snippets by wrapping the code in an out(..) operator and passing it directly to liquidsoap:

 liquidsoap -v 'out(recipe)'

For longer recipes, you might want to create a short script:

#!/usr/bin/liquidsoap -v

set("log.file.path","/tmp/<script>_YOURNAME.log")
set("log.stdout",true)

recipe = single("/my/default.ogg")
out(recipe)

Now a version that sends to an icecast server... (NB: YOU NEED A passwords.liq file with the appropriate passwords...

# %include "passwords.liq"
ICECAST_SERVER_HOST="echo.lurk.org"
ICECAST_SERVER_PORT=9999
ICECAST_SERVER_PASSWORD="hackme"

#!/usr/bin/liquidsoap -v

set("log.file.path","/tmp/<script>_YOURNAME.log")
set("log.stdout",true)
%include "passwords.liq"

recipe = single("/my/default.ogg")
output.icecast(%vorbis,
      host = ICECAST_SERVER_HOST, port = ICECAST_SERVER_PORT,
      password = ICECAST_SERVER_PASSWORD, mount = "prototyping.ogg",
      mksafe(recipe))

See the quickstart guide for more information on how to run Liquidsoap, on what is this out(..) operator, etc.

Getting started / outpus

So the very simplest test for liquidsoap can be like this:

liquidsoap -v 'out(single("/my/default.ogg"))'

Here you run liquidsoap from the command-line and specify the program at the same time.

• single plays a single file
• out is a convenience function that uses output.preferred to try to play output to your sound card (NB: this doesn't make sense to use if you are connected to a server and can't hear sound output directly) -- see #Outputs below!

Like with any scripting language, it's much more convenient for making composing and changing your liquidsoap program to save it in its own file, the convention is to use the extension ".liq" for a liquidsoap script. When you make a script, you have to add two special lines that tell liquidsoap where to write message (the "log" file).

Basic outputs of interest:

• out which is the shortcut for output.preferred: play to the soundcard directly (if possible)
• output.file: play to a file
• output.icecast Send audio to an icecast server

Live interruption with fallback

A very useful model is to make a stream that plays from will take its content from another stream, and fallback to a "safety" program when that stream isn't available. This allows for a program to be remotely stopped and (re)started, without breaking the continuit of the main stream. A good example is given in the "complete case" of a program that uses the fallback function to allow a live program to cut-in and interrupt an otherwise automated program.

#!/usr/bin/liquidsoap -v

set("log.file.path","/tmp/<script>.log")
set("log.stdout",true)

%include "passwords.liq"

# Add the ability to relay live shows
liveorstatic =
  fallback(track_sensitive=false,
           [input.http("http://echo.lurk.org:999/prototyping_live.ogg"),
            single("brownnoise.mp3")])

# out(liveorstatic)
output.icecast(%vorbis,
      host = ICECAST_SERVER_HOST, port = ICECAST_SERVER_PORT,
      password = ICECAST_SERVER_PASSWORD, mount = "prototyping.ogg",
      mksafe(liveorstatic))

Sound processing

liquidsoap can be used to process / filter sound either in a streaming pipeline, or used "offline" to directly produce an audio output (file).

See https://www.liquidsoap.info/doc-1.4.2/reference.html#source-sound-processing

Links / Projects / Radio streams that use liquidsoap

• Data Radio. Here a script created a day and night playlist, with a "fallback" to allow a live stream to interrupt.

playlist

playlist source

mode (of type string, which defaults to "randomize"): Play the files in the playlist either in the order (“normal” mode), or shuffle the playlist each time it is loaded, and play it in this order for a whole round (“randomize” mode), or pick a random file in the playlist each time (“random” mode).

say_metadata

say_metadata filter

examples

liquidsoap 'out(noise())'

liquidsoap 'out(playlist("playlist.pls"))'
liquidsoap 'output.prefered(mksafe(playlist("playlist.pls")))'
liquidsoap 'output.file(%mp3,"output.mp3",mksafe(playlist("playlist.pls")))'

with playlist.pls:

brown.ogg

Observations:

• WAV files don't seem to work, but ogg + mp3 seem OK! (or was this the stereo problem)
• explicit output modules (like output.file) seem to require the use of mksafe (out doesn't need this).

Doesn't work with mono source material -- default seems to be stereo...

  [decoder:3] Unable to decode "./speech0001.mp3" as {audio=2;video=0;midi=0}!
  2020/05/11 17:42:04 [decoder.mad:3] File "./speech0003.mp3" has an incompatible number of channels.

  WAV file "speech0001.wav" has content type {audio=1;video=0;midi=0} but {audio=2;video=0;midi=0} was expected.

How would you output a mono audio stream?

Presentation

Recently presented at Fosdem2020 also on vimeo

Documentation conventions

The docs have cryptic syntax, for instance the say_metadata filter is described with the signature:

 (source(?A), ?pattern : string) -> source(?A)

Which means you can call this function like:

 say_metadata(mysource)

or

 say_metadata(mysource, pattern="")