Table of Contents
Liquid soap is a scripting language for programming and controlling live broadcasts.
concepts
classes of objects
Liquidsoap consists of four components
- requests which are an abstraction of a file. They take in a uri (a url or file path) and resolve it to media and metadata.
- sources which provide media data, i.e audio from a file.
- filters these are functions that take in and output an audio source.
- outputs these are the endpoints that we send our audio data to, such as an icecast mountpoint.
clocks
clocks are the secret 5th object, but are largely obscured from us except when liquidsoap's automation cannot infer a clock on its own. In real time networks there cannot be a universal clock, each computer and potentially each process will be running at its own rate. To account for any discrepancy and maintain a simple model liquidsoap makes the rule that each source has its own clock.
fallibility
If a source is fallible that means that it can stop sending audio data, breaking the chain of audio data. We can fix this with a fallback filter that switches over to another generator if the primary generator fails. By using fallback we can make our source infallible, meaning that it will always be sending audio data. Outputs will error
how streaming works
snippets and examples
working with the shell
https://www.liquidsoap.info/doc-2.3.0/cookbook.html#unix-interface-dynamic-requests
speech synthesis
say
$(time)
set metadata
annotate:
sources
single("path/to/file.mp3")
creates a source that repeats the same audio forever
playlist("path/to/file.m3u")
playlist("~/Music/")
creates a source that plays songs in sequence. It can take any file that's just a newline separated list of uris but also more advanced playlist formats like pls or m3u. playlist has 3 modes:
- normal: plays in order
- randomize: shuffles playlist and then plays in order
- random: picks a random song after each track ends
By default once a playlist is created it doesn't update itself if the file/directory it was generated from changes. The reload argument allows us to update the playlist on file change with reload="watch" or after a certain period of time or after every time it completes a round.The playlist's reload method can also be called by another function.
for remote sources we need to use input
input.<protocol>(<URI>)
programming (the radio kind)
play next
by default source combinators are track sensitive meaning that they will wait for the currently playing track to end before switching to the next one. We can make them switch instantly if we use the keyword argument track_sensitive=false. Note that some sources don't have track data and so will never have an "end" for a switch to take place at.
random([source1, source2])
will randomly pick between the provided sources
sequence([source1, source2, source3])
will play one track from each source in order and then play from the final source.
interrupt now
fallback(track_sensitive=false, [primary, secondary, tertiary])
will play whichever source is active and highest priority. If primary is normally off, and secondary is regular programming, you can override secondary by activating the primary source
the track_sensitive option lets us do instant fallback. If we don't set it false it will wait for the track to finish before switching. If the track is infinite then it will never switch!
outputting
This is actually the last step. We create an output object with any log in information we need and pass it our programming source.
output.file(%mp3, "out.mps", source)