Liquidsoap svn : Language reference

Liquidsoap scripting language reference

Categories

The Source / ... categories contain all functions that return sources.
The Input functions are those which build elementary sources
(playing files, synthesizing sound, etc.).
The Output functions are those which take a source and register it
for being streamed to the outside (file, soundcard, audio server, etc.).
The Visualization functions are experimental ones that let you
visualize in real-time some aspects of the audio stream.
The Sound Processing functions are those which basically work on the source
as a continuous audio stream. They would typically be mixers of streams,
audio effects or analysis.
Finally, Track Processing functions are basically all
others, often having a behaviour that depends on or affects the extra
information that liquidsoap puts in streams: track limits and metadata.

auth ((string,string)->bool – defaults to fun (_,_) -> false): Authentication function. f(login,password) returns true if the user should be granted access for this login. Override any other method if used.

buffer (float – defaults to 2.): Duration of the pre-buffered data.

debug (bool – defaults to false): Run in debugging mode by not catching some exceptions.

icy_metadata_charset (string – defaults to ""): ICY (shoutcast) metadata charset. Guessed if empty. Default for shoutcast is ISO-8859-1. Set to that value if all your clients send metadata using this charset and automatic detection is not working for you.

on_connect (([(string*string)])->unit – defaults to fun (_) -> ()): Function to execute when a source is connected. Its receives the list of headers, of the form: (<label>,<value>). All labels are lowercase.

on_disconnect (()->unit – defaults to {()}): Functions to excecute when a source is disconnected

new_track_on_metadata (bool – defaults to true): Treat new metadata as new track.

on_connect (([(string*string)])->unit – defaults to fun (_) -> ()): Function to execute when a source is connected. Its receives the list of headers, of the form: (<label>,<value>). All labels are lowercase.

on_disconnect (()->unit – defaults to {()}): Function to excecute when a source is disconnected

playlist_mode (string – defaults to "normal"): Valid modes are “normal”, “random”, “randomize” and “first”. The first ones have the same meaning as for the mode parameter of the playlist operator. The last one discards all entries but the first one.

poll_delay (float – defaults to 2.): Polling delay when trying to connect to the stream.

Forwards the given lastfm stream. The relay can be paused/resumed using the start/stop telnet commands.

id (string – defaults to ""): Force the value of the source ID.

autostart (bool – defaults to true): Initially start relaying or not.

bind_address (string – defaults to ""): Address to bind on the local machine. This option can be useful if your machine is bound to multiple IPs. “” means no bind address.

buffer (float – defaults to 10.): Duration of the pre-buffered data.

debug (bool – defaults to false): Run in debugging mode by not catching some exceptions.

max (float – defaults to 25.): Maximum duration of the buffered data.

new_track_on_metadata (bool – defaults to true): Treat new metadata as new track.

on_connect (([(string*string)])->unit – defaults to fun (_) -> ()): Function to execute when a source is connected. Its receives the list of headers, of the form: (<label>,<value>). All labels are lowercase.

on_disconnect (()->unit – defaults to {()}): Function to excecute when a source is disconnected

start (bool – defaults to true): Start input as soon as it is created. Disabling it is only taken into account for a fallible input.

start (bool – defaults to true): Automatically start outputting whenever possible. If true, an infallible (normal) output will start outputting as soon as it is created, and a fallible output will (re)start as soon as its source becomes available for streaming.

check_next ((request('a))->bool – defaults to <code><fun></code>): Function used to filter next tracks. A candidate track is only validated if the function returns true on it. The function is called before resolution, hence metadata will only be available for requests corresponding to local files. This is typically used to avoid repetitions, but be careful: if the function rejects all attempts, the playlist will enter into a consuming loop and stop playing anything.

conservative (bool – defaults to false): If true, estimated remaining time on the current track is not considered when computing queue length.

mode (string – 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).

prefix (string – defaults to ""): Add a constant prefix to all requests. Useful for passing extra information using annotate, or for resolution through a particular protocol, such as replaygain.

reload (int – defaults to 0): Amount of time (in seconds or rounds), when applicable, before which the playlist is reloaded; 0 means never.

reload_mode (string – defaults to "seconds"): Unit of the reload parameter, either 'rounds', 'seconds' or 'watch' (reload the file whenever it is changed).

timeout (float – defaults to 20.): Timeout (in sec.) for a single download.

Custom playlist source written using the script language. Will read directory or playlist, play all files and stop. Returns a pair (reload,source) where reload is a function of type (?uri:string)->unit used to reload the source and source is the actual source. The reload function can optionally be called with a new playlist URI. Otherwise, it reloads the previous URI.

id (string – defaults to ""): Force the value of the source ID.

random (bool – defaults to false): Randomize playlist content

on_done (()->unit – defaults to {()}): Function to execute when the playlist is finished

Loop on a playlist of local files, and never fail. In order to do so, it has to check every file at the loading, so the streamer startup may take a few seconds. To avoid this, use a standard playlist, and put only a few local files in a default safe_playlist in order to ensure the liveness of the streamer.

mode (string – 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).

prefix (string – defaults to ""): Add a constant prefix to all requests. Useful for passing extra information using annotate, or for resolution through a particular protocol, such as replaygain.

reload (int – defaults to 0): Amount of time (in seconds or rounds), when applicable, before which the playlist is reloaded; 0 means never.

reload_mode (string – defaults to "seconds"): Unit of the reload parameter, either 'rounds', 'seconds' or 'watch' (reload the file whenever it is changed).

start (bool – defaults to true): Automatically start outputting whenever possible. If true, an infallible (normal) output will start outputting as soon as it is created, and a fallible output will (re)start as soon as its source becomes available for streaming.

Create a buffer between two different clocks. The speed of the output is adapted so that no buffer underrun or overrun occurs. This wonderful behavior has a cost: the pitch of the sound might be changed a little.

id (string – defaults to ""): Force the value of the source ID.

averaging (float – defaults to 30.): Half-life for the averaging of the buffer size, in seconds.

buffer (float – defaults to 1.): Amount of data to pre-buffer, in seconds.

fallible (bool – defaults to false): Allow the child source to fail, in which case the output will be (temporarily) stopped.

start (bool – defaults to true): Automatically start outputting whenever possible. If true, an infallible (normal) output will start outputting as soon as it is created, and a fallible output will (re)start as soon as its source becomes available for streaming.

start (bool – defaults to true): Automatically start outputting whenever possible. If true, an infallible (normal) output will start outputting as soon as it is created, and a fallible output will (re)start as soon as its source becomes available for streaming.

options ([(string*string)] – defaults to []): List of parameters, depends on the driver.

start (bool – defaults to true): Automatically start outputting whenever possible. If true, an infallible (normal) output will start outputting as soon as it is created, and a fallible output will (re)start as soon as its source becomes available for streaming.

start (bool – defaults to true): Automatically start outputting whenever possible. If true, an infallible (normal) output will start outputting as soon as it is created, and a fallible output will (re)start as soon as its source becomes available for streaming.

reopen_delay (float – defaults to 120.): Prevent re-opening within that delay, in seconds.

reopen_on_metadata (bool – defaults to false): Re-open on every new metadata information.

reopen_when (()->bool – defaults to {false}): When should the output be re-opened.

start (bool – defaults to true): Automatically start outputting whenever possible. If true, an infallible (normal) output will start outputting as soon as it is created, and a fallible output will (re)start as soon as its source becomes available for streaming.

(unlabeled) (format('a)): Encoding format.

(unlabeled) (string): Process to pipe data to. Some strftime conversion specifiers are available: %SMHdmY. You can also use $(..) interpolation notation for metadata.

append (bool – defaults to false): Do not truncate but append in the file if it exists.

dir_perm (int – defaults to 511): Permission of the directories if some have to be created, up to umask. Although you can enter values in octal notation (0oXXX) they will be displayed in decimal (for instance, 0o777 = 7*8^2 + 7*8 + 7 = 511).

fallible (bool – defaults to false): Allow the child source to fail, in which case the output will be (temporarily) stopped.

flush (bool – defaults to false): Perform a flush after each write.

on_close ((string)->unit – defaults to fun (_) -> ()): This function will be called for each file, after that it is finished and closed. The filename will be passed as argument.

perm (int – defaults to 438): Permission of the file if it has to be created, up to umask. You can and should write this number in octal notation: 0oXXX. The default value is however displayed in decimal (0o666 = 6*8^2 + 6*8 + 6 = 438).

reopen_delay (float – defaults to 120.): Prevent re-opening within that delay, in seconds.

reopen_on_metadata (bool – defaults to false): Re-open on every new metadata information.

reopen_when (()->bool – defaults to {false}): When should the output be re-opened.

start (bool – defaults to true): Automatically start outputting whenever possible. If true, an infallible (normal) output will start outputting as soon as it is created, and a fallible output will (re)start as soon as its source becomes available for streaming.

(unlabeled) (format('a)): Encoding format.

(unlabeled) (string): Filename where to output the stream. Some strftime conversion specifiers are available: %SMHdmY. You can also use $(..) interpolation notation for metadata.

start (bool – defaults to true): Automatically start outputting whenever possible. If true, an infallible (normal) output will start outputting as soon as it is created, and a fallible output will (re)start as soon as its source becomes available for streaming.

start (bool – defaults to true): Automatically start outputting whenever possible. If true, an infallible (normal) output will start outputting as soon as it is created, and a fallible output will (re)start as soon as its source becomes available for streaming.

start (bool – defaults to true): Automatically start outputting whenever possible. If true, an infallible (normal) output will start outputting as soon as it is created, and a fallible output will (re)start as soon as its source becomes available for streaming.

start (bool – defaults to true): Automatically start outputting whenever possible. If true, an infallible (normal) output will start outputting as soon as it is created, and a fallible output will (re)start as soon as its source becomes available for streaming.

auth ((string,string)->bool – defaults to fun (_,_) -> false): Authentication function. f(login,password) returns true if the user should be granted access for this login. Override any other method if used.

buffer (int – defaults to 327675): Maximun buffer per-client.

burst (int – defaults to 65534): Initial burst of data sent to the client.

chunk (int – defaults to 1024): Send data to clients using chunks of at least this length.

start (bool – defaults to true): Automatically start outputting whenever possible. If true, an infallible (normal) output will start outputting as soon as it is created, and a fallible output will (re)start as soon as its source becomes available for streaming.

on_error ((string)->float – defaults to fun (_) -> 3.): Callback executed when an error happens. The callback receives a string representation of the error that occured and returns a float. If returned value is positive, connection will be tried again after this amount of time (in seconds).

start (bool – defaults to true): Automatically start outputting whenever possible. If true, an infallible (normal) output will start outputting as soon as it is created, and a fallible output will (re)start as soon as its source becomes available for streaming.

start (bool – defaults to true): Automatically start outputting whenever possible. If true, an infallible (normal) output will start outputting as soon as it is created, and a fallible output will (re)start as soon as its source becomes available for streaming.

start (bool – defaults to true): Automatically start outputting whenever possible. If true, an infallible (normal) output will start outputting as soon as it is created, and a fallible output will (re)start as soon as its source becomes available for streaming.

start (bool – defaults to true): Automatically start outputting whenever possible. If true, an infallible (normal) output will start outputting as soon as it is created, and a fallible output will (re)start as soon as its source becomes available for streaming.

start (bool – defaults to true): Automatically start outputting whenever possible. If true, an infallible (normal) output will start outputting as soon as it is created, and a fallible output will (re)start as soon as its source becomes available for streaming.

start (bool – defaults to true): Automatically start outputting whenever possible. If true, an infallible (normal) output will start outputting as soon as it is created, and a fallible output will (re)start as soon as its source becomes available for streaming.

start (bool – defaults to true): Automatically start outputting whenever possible. If true, an infallible (normal) output will start outputting as soon as it is created, and a fallible output will (re)start as soon as its source becomes available for streaming.

(?id:string,?override:string,'a,
source(audio='#b,video='#c,midi='#d))->
source(audio='#b,video='#c,midi='#d)
where 'a is either float or ()->float

Multiply the amplitude of the signal.

id (string – defaults to ""): Force the value of the source ID.

override (string – defaults to "liq_amplify"): Specify the name of a metadata field that, when present and well-formed, overrides the amplification factor for the current track. Well-formed values are floats in decimal notation (e.g. '0.7') which are taken as normal/linear multiplicative factors; values can be passed in decibels with the suffix 'dB' (e.g. '-8.2 dB', but the spaces do not matter).

(unlabeled) (anything that is either float or ()->float): Multiplicative factor.

Generic cross operator, allowing the composition of the N last seconds of a track with the beginning of the next track.

id (string – defaults to ""): Force the value of the source ID.

active (bool – defaults to false): The active behavior is to keep ticking the child's clock when the operator is not streaming. Otherwise the child's clock is strictly based on what is streamed off the child source, which results in time-dependent active sources to be frozen when that source is stopped.

conservative (bool – defaults to false): Do not trust remaining time estimations, always buffering data in advance. This avoids being tricked by skips, either manual or caused by skip_blank().

duration (float – defaults to 5.): Duration in seconds of the crossed end of track. This value can be changed on a per-file basis using a special metadata field.

inhibit (float – defaults to -1.): Minimum delay between two transitions. It is useful in order to avoid that a transition is triggered on top of another when an end-of-track occurs in the first one. Negative values mean duration+1. Warning: zero inhibition can cause infinite loops.

minimum (float – defaults to -1.): Minimum duration (in sec.) for a cross: If the track ends without any warning (e.g. in case of skip) there may not be enough data for a decent composition. Set to 0. to avoid having transitions after skips, or more to avoid transitions on short tracks. With the negative default, transitions always occur.

override (string – defaults to "liq_start_next"): Metadata field which, if present and containing a float, overrides the 'duration' parameter for current track.

(unlabeled) ((source('a),source('a))->source('a)): Composition of an end of track and the next track.

(?id:string,?frequency:'a,?monitor:int,
?sidechain_filter:int,?threshold_level:'b,
source(audio='#c,video='#d,midi='#e))->
source(audio='#c,video='#d,midi='#e)
where 'a, 'b is either float or ()->float

Normalize the signal. Dynamic normalization of the signal is sometimes the only option, and can make a listening experience much nicer. However, its dynamic aspect implies some limitations which can go as far as creating saturation in some extreme cases. If possible, consider using some track-based normalization techniques such as those based on replay gain. See the documentation for more details.

id (string – defaults to ""): Force the value of the source ID.

gain_max (anything that is either float or ()->float – defaults to 6.): Maximal gain value (dB).

gain_min (anything that is either float or ()->float – defaults to -6.): Minimal gain value (dB).

k_down (anything that is either float or ()->float – defaults to 0.1): Coefficient when the power must go down (between 0 and 1, slowest to fastest).

k_up (anything that is either float or ()->float – defaults to 0.005): Coefficient when the power must go up (between 0 and 1, slowest to fastest).

target (anything that is either float or ()->float – defaults to -13.): Desired RMS (dB).

threshold (anything that is either float or ()->float – defaults to -40.): Minimal RMS for activaing gain control (dB).

window (float – defaults to 0.1): Duration of the window used to compute the current RMS power (second).

Cross operator, allowing the composition of the N last seconds of a track with the beginning of the next track, using a transition function depending on the relative power of the signal before and after the end of track.

id (string – defaults to ""): Force the value of the source ID.

active (bool – defaults to false): The active behavior is to keep ticking the child's clock when the operator is not streaming. Otherwise the child's clock is strictly based on what is streamed off the child source, which results in time-dependent active sources to be frozen when that source is stopped.

conservative (bool – defaults to false): Do not trust remaining time estimations, always buffering data in advance. This avoids being tricked by skips, either manual or caused by skip_blank().

duration (float – defaults to 5.): Duration in seconds of the crossed end of track.

inhibit (float – defaults to -1.): Minimum delay between two transitions. It is useful in order to avoid that a transition is triggered on top of another when an end-of-track occurs in the first one. Negative values mean duration+1. Warning: zero inhibition can cause infinite loops.

minimum (float – defaults to -1.): Minimum duration (in sec.) for a cross: If the track ends without any warning (e.g. in case of skip) there may not be enough data for a decent composition. Set to 0. to avoid having transitions after skips, or more to avoid transitions on short tracks. With the negative default, transitions always occur.

width (float – defaults to 1.): Width of the power computation window.

(unlabeled) ((float,float,[(string*string)],[(string*string)],
source(audio='#a+1,video=0,midi=0),
source(audio='#a+1,video=0,midi=0))->
source(audio='#a+1,video=0,midi=0)): Transition function, composing from the end of a track and the next track. It also takes the power of the signal before and after the transition, and the metadata.

(?id:string,?active:bool,ratio:'a,
source(audio='#b+1,video=0,midi=0))->
source(audio='#c+1,video=0,midi=0)
where 'a is either float or ()->float

Slow down or accelerate an audio stream by stretching (sounds lower) or squeezing it (sounds higher).

id (string – defaults to ""): Force the value of the source ID.

active (bool – defaults to true): The active behavior is to keep ticking the child's clock when the operator is not streaming. Otherwise the child's clock is strictly based on what is streamed off the child source, which results in time-dependent active sources to be frozen when that source is stopped.

ratio (anything that is either float or ()->float): A value higher than 1 means slowing down.

merge (bool – defaults to false): Merge the track with its appended track.

(unlabeled) (source('a))

(unlabeled) (([(string*string)])->source('a)): Given the metadata, build the source producing the track to append. This source is allowed to fail (produce nothing) if no relevant track is to be appended.

(unlabeled) (([(string*string)])->unit): Function called on every beginning of track in the stream, with the corresponding metadata as argument. If there is no metadata at the beginning of track, the empty list is passed. That function should be fast because it is ran in the main thread.

Prepend an extra track before every track. Set the metadata 'liq_prepend' to 'false' to inhibit prepending on one track.

id (string – defaults to ""): Force the value of the source ID.

merge (bool – defaults to false): Merge the track with its appended track.

(unlabeled) (source(audio='#a,video='#b,midi='#c))

(unlabeled) (([(string*string)])->source(audio='#a,video='#b,midi='#c)): Given the metadata, build the source producing the track to prepend. This source is allowed to fail (produce nothing) if no relevant track is to be appended. However, success must be immediate or it will not be taken into account.

Play only one track of every successive source, except for the last one which is played as much as available. Sources are released after being used, allowing them to shutdown cleanly and free their resources.

id (string – defaults to ""): Force the value of the source ID.

merge (bool – defaults to false): Merge tracks when advancing from one source to the next one. This will NOT merge consecutive tracks from the last source; see merge_tracks() if you need that too.

(?id:string,?color:int,?cycle:bool,?font:string,
?metadata:string,?size:int,?speed:int,?x:int,?y:int,'a,
source(audio='#b,video='#c+1,midi='#d))->
source(audio='#b,video='#c+1,midi='#d)
where 'a is either string or ()->string

(?id:string,?color:int,?cycle:bool,?font:string,
?metadata:string,?size:int,?speed:int,?x:int,?y:int,'a,
source(audio='#b,video='#c+1,midi='#d))->
source(audio='#b,video='#c+1,midi='#d)
where 'a is either string or ()->string

(?id:string,?blend_mode:string,?opacity:'a,
source(audio='#b,video='#c+1,midi='#d),
source(audio='#b,video='#c+1,midi='#d))->
source(audio='#b,video='#c+1,midi='#d)
where 'a is either float or ()->float

Composites second input on the first input with user-defined blend mode and opacity (by Janne Liljeblad).

Call a function in N seconds. If the result of the function is positive or null, the task will be scheduled again after this amount of time (in seconds).

fast (bool – defaults to true): Set to false if the execution of the code can take long in order to lower its priority below that of request resolutions and fast timeouts. This is only effective if you set a dedicated queue for fast tasks, see the “scheduler” settings for more details.

source (string – defaults to "broadcast"): Source for tracks. Should be one of: “broadcast”, “user”, “recommendation” or “unknown”. Since liquidsoap is intented for radio broadcasting, this is the default. Sources other than user don't need duration to be set.

test ((string)->int): Function used to determine if a file should be decoded by the decoder. Returned values are: 0: no decodable audio, -1: decodable audio but number of audio channels unknown, x: fixed number of decodable audio channels.

Register an external file decoder. The encoder should output in WAV format to his standard output (stdout) and read data from the file it receives. The estimated remaining duration for this decoder will be unknown until the buffer last seconds of the file. If possible, it is recommended to decode from stdin and use add_decoder.

name (string): Format/decoder's name.

description (string): Description of the decoder.

test ((string)->int): Function used to determine if a file should be decoded by the decoder. Returned values are: 0: no decodable audio, -1: decodable audio but number of audio channels unknown, x: fixed number of decodable audio channels.

buffer (float – defaults to 5.)

(unlabeled) ((string)->string): Process to start. The function takes the filename as argument and returns the process to start.

Enable replay gain metadata resolver. This resolver will process any file decoded by liquidsoap and add a replay_gain metadata when this value could be computed. For a finer-grained replay gain processing, use the replay_gain protocol.

extract_replaygain (string – defaults to "/usr/local/lib/liquidsoap/scm/extract-replaygain"): The extraction program

Register a HTTP handler on the harbor. The given function receives as argument the full requested uri (e.g. “foo?var=bar”), http protocol version, possible input data and the list of HTTP headers and returns the answer sent to the client, including HTTP headers. Registered uri can be regular expressions (e.g. “.+\.php”) and can override default metadata handlers.

Create a raw request, i.e. for files that should not be decoded for streaming. Creation may fail if there is no available RID, which cannot be detected currently: in that case one will obtain a request that will fail to be resolved.

Extract substrings from a string.
Perl compatible regular expressions are recognized. Hence, special characters should be escaped.
Returns a list of (index,value).
If the list does not have a pair associated to some index, it means that the corresponding pattern was not found.

Parse command line options:
getopt("-o") returns “1” if “-o” was passed without any parameter, “0” otherwise.
getopt(default="X","-o") returns “Y” if “-o Y” was passed, “X” otherwise.
The result is removed from the list of arguments, affecting subsequent
calls to argv() and getopt().