Liquidsoap configuration
ALSA configuration
Alsa internal buffer size
Default: 0
set("alsa.alsa_buffer",0)
This setting is only used in buffered alsa I/O, and affects latency. Set to 0 to disable this setting and use ALSA's default.
Buffer size, in frames
Default: 1
set("alsa.buffer_length",1)
This is only used for buffered ALSA I/O, and affects latency.
Number of periods
Default: 0
set("alsa.periods",0)
Set to 0 to disable this setting and use ALSA's default.
Audio settings
Conversion settings
Samplerate conversion settings
Libsamplerate conversion settings
Default: "zero_order"
set("audio.converter.samplerate.libsamplerate.quality","zero_order")
Resampling quality, one of: “best”, “medium”, “fast”, “zero_order”, “linear”. Refer to ocaml-samplerate for details.
Preferred samplerate converter
Default: "libsamplerate"
set("audio.converter.samplerate.preferred","libsamplerate")
Preferred samplerate converter.
Audioscrobbler configuration.
Clock settings
Handling of streaming errors
Default: false
set("clock.allow_streaming_errors",false)
Control the behaviour of clocks when an error occurs during streaming. This has no effect on errors occurring during source initializations. By default, any error will cause liquidsoap to shutdown. If errors are allowed, faulty sources are simply removed and clocks keep running. Allowing errors can result in complex surprising situations; use at your own risk!
Decoder settings
Maximum debugging information (dev only)
Default: false
set("decoder.debug",false)
WARNING: Do not enable unless a developer instructed you to do so! The debugging mode makes it easier to understand why decoding fails, but as a side effect it will crash liquidsoap at the end of every track.
Decoders and order used to decode files.
Default: ["META","WAV","MIDI","FLAC","SDL/IMAGE","MAD","AAC","MP4","OGG","CAMLIMAGES"]
set("decoder.file_decoders",["META","WAV","MIDI","FLAC","SDL/IMAGE","MAD","AAC","MP4","OGG","CAMLIMAGES"])
File extensions used for guessing audio formats
File extensions used for guessing AAC format
Default: ["aac"]
set("decoder.file_extensions.aac",["aac"])
File extensions used for guessing FLAC format
Default: ["flac"]
set("decoder.file_extensions.flac",["flac"])
File extensions used for guessing mpeg audio format
Default: ["mp3","mp2","mp1"]
set("decoder.file_extensions.mad",["mp3","mp2","mp1"])
File extensions used for guessing MP3 format (DEPRECATED, use *.mad configuration keys!)
Default: ["mp3","mp2","mp1"]
set("decoder.file_extensions.mp3",["mp3","mp2","mp1"])
File extensions used for guessing MP4 format
Default: ["m4a","m4b","m4p","m4v","m4r","3gp","mp4"]
set("decoder.file_extensions.mp4",["m4a","m4b","m4p","m4v","m4r","3gp","mp4"])
File extensions used for guessing OGG format
Default: ["ogv","oga","ogx","ogg"]
set("decoder.file_extensions.ogg",["ogv","oga","ogx","ogg"])
File extensions used for decoding metadata using TAGLIB
Default: ["mp3"]
set("decoder.file_extensions.taglib",["mp3"])
File extensions used for guessing WAV format
Default: ["wav"]
set("decoder.file_extensions.wav",["wav"])
Mime-types used for guessing audio formats
Mime-types used for guessing AAC format
Default: ["audio/aac","audio/aacp","audio/x-hx-aac-adts"]
set("decoder.mime_types.aac",["audio/aac","audio/aacp","audio/x-hx-aac-adts"])
Mime-types used for guessing PCM/BASIC format
Default: ["audio/basic"]
set("decoder.mime_types.basic",["audio/basic"])
Mime-types used for guessing FLAC format
Default: ["audio/x-flac"]
set("decoder.mime_types.flac",["audio/x-flac"])
Mime-types used for guessing mpeg audio format
Default: ["audio/mpeg","audio/MPA"]
set("decoder.mime_types.mad",["audio/mpeg","audio/MPA"])
Mime-types used for guessing MP3 format (DEPRECATED, use *.mad configuration keys!)
Default: ["audio/mpeg","audio/MPA"]
set("decoder.mime_types.mp3",["audio/mpeg","audio/MPA"])
Mime-types used for guessing MP4 format
Default: ["audio/mp4","application/mp4"]
set("decoder.mime_types.mp4",["audio/mp4","application/mp4"])
Mime-types used for guessing OGG format.
Default: ["application/ogg","application/x-ogg","audio/x-ogg","audio/ogg","video/ogg"]
set("decoder.mime_types.ogg",["application/ogg","application/x-ogg","audio/x-ogg","audio/ogg","video/ogg"])
Mime-types used for decoding metadata using TAGLIB
Default: ["audio/mpeg"]
set("decoder.mime_types.taglib",["audio/mpeg"])
Mime-types used for guessing WAV format
Default: ["audio/vnd.wave","audio/wav","audio/wave","audio/x-wav"]
set("decoder.mime_types.wav",["audio/vnd.wave","audio/wav","audio/wave","audio/x-wav"])
Decoders and order used to decode streams.
Default: ["WAV","PCM/BASIC","FLAC","MAD","AAC","OGG"]
set("decoder.stream_decoders",["WAV","PCM/BASIC","FLAC","MAD","AAC","OGG"])
Taglib settings
By default, taglib will only attempt reading metadata from files that it detects as valid. This may fail, for example if the reported mime type isn't “audio/mpeg”. If you set this configuration key to true, then all files successfully recognized by liquidsoap will be considered as MPEG by taglib. In this case, taglib configuration keys for file extensions and mime types (“decoder.file_extensions.taglib” and “decoder.mime_types.taglib”) are not used, and file detection is only done based on the corresponding settings from the MAD MPEG decoder.
Default: false
set("decoder.taglib.force_mpeg",false)
Encoder settings
Metadata settings
Exported metdata
Default: ["artist","title","album","genre","date","tracknumber","comment","track","year"]
set("encoder.encoder.export",["artist","title","album","genre","date","tracknumber","comment","track","year"])
The list of labels of exported metadata.
Frame format
Audio (PCM) format
Default number of channels
Default: 2
set("frame.audio.channels",2)
Samplerate
Default: 44100
set("frame.audio.samplerate",44100)
Tentative frame duration in seconds
Default: 0.04
set("frame.duration",s="s>
Replay gain
Replay gain is a proposed standard that is (more or less) respected by many open-source tools. It provides a way to obtain an overall uniform perceived loudness over a track or a set of tracks. The computation of the loudness is based on how the human ear actually perceives each range of frequency. Having computed the average perceived loudness on a track or an album, it is easy to renormalize the tracks when playing, ensuring a comfortable, consistent listening experience.
Because it is track-based, replay gain does not suffer from the typical problems of stream-based, dynamic approaches. Namely, these distort the initial audio, since they constantly adapt the amplification factor. Sometimes it oscillates too quickly in a weird audible way. Sometimes it does not adapt quickly enough, leading to under or over-amplified sections.
On the other hand, replay gain has its drawbacks. First, it requires an initial computation that is a bit costly. This computation can be done once for all for local files – subsequent calls can then retrieve the result from the metadata. Although not impossible in theory, there is no recipe for liquidsoap to offer the same feature on remote files.
How to use replay gain in Liquidsoap
In theory, there are two independant parts: computing the replay gain and tagging the files with that information, and retrieving the gain from the metadata when playing the file, in order to renormalize it. In practice, everybody will want to use the same script that triggers the computation if needed even if they do not need that part, because the replay gain metadata is stored in some exotic format that liquidsoap does not support directly yet. Instead, it relies on the replay gain computation tools to extract them.
Renormalizing according to some metadata field
The amplify() operator can behave according to metadata. Its override parameter indicates a metadata field that, when present and well-formed, overrides the amplification factor. Well formed fields are floats (e.g. 2 or 0.7) for linear amplification factors and floats postfixed with dB (e.g. -2 dB) for logarithmic ones.
For replay gain implementation, the amplify operator would typically be added immediately on top of the basic tracks source, before transitions or other audio processing operators. We follow these lines in the next example, where the replay_gain field is used to carry the information:
list = playlist("~/playlist")
default = single("~/default.ogg")
s = fallback([list,default])
s = amplify(1.,override="replay_gain",s)
# Here: other effects, and finally the output...
You may also take care of not losing the information brought by the metadata. This may be the case for instance if you
use smart_crossfade before applying normalization. Hence, normalization should be done as soon as possible
in the script, if possible just after the initial source.
Computing and retrieving the data
In practice, the replay gain information can be found in various fields depending on the audio format and the replay gain computation tool.
Liquidsoap provides a script for extracting the replay gain value from mp3, ogg/vorbis and flac files. It requires the tools
mp3gain (resp. vorbisgain and ogginfo, resp. metaflac) for mp3 (resp. ogg/vorbis, resp. flac) files processing, and will affect your files:
after the first computation of the replay gain, that information will be stored in the metadata.
Optionally, this script can also use the file binary in order to detect the content of an audio file not only using its extension, which is necessary
with, for instance, protocols that download files across the network, such as ftp.
Then, there are at least two ways to use it in your liquidsoap script:
using the replay gain metadata resolver, or the replay_gain protocol.
The metadata solution is uniform: without changing anything, all your
files will have a new replay_gain metadata when the computation suceeded. However, this can be problematic,
for example, for jingles,
or if you have large files that would take a very long time
to be analyzed by replaygain tools.
The protocol solution gives you more control on when the replaygain analysis
is performed, but requires that you change some uri into replay_gain:uri.
We briefly discuss below how to do it conveniently in some typical cases.
Note that our replaygain support for remote files can be problematic.
As such, it would analyze the file after each download, which
may be uselessly costly. One should instead make sure that the file has
been analyzed on the remote machine, so that the local analysis only retrieves
the precomputed value. In any case, remote files can only be treated through
the addition of a metadata resolver, and cannot work with the replay_gain
protocol technique (replaygain:ftp://host/file.ogg will call
the script using the ftp://host/file.ogg as the URI parameter, and
it will fail).
The replay gain metadata resolver is not enabled by default. You can do it
by adding the following code in your script:
enable_replaygain_metadata ()
The replay_gain protocol is enabled by default.
In this case, everytime you need replaygain information about a file,
access it through your new protocol: for example,
replace /path/to/file.mp3
by replay_gain:/path/to/file.mp3.
The resolving of the protocol will trigger a call to our script,
which will return an annotated request, finally resulting in your file
with the extra replay_gain metadata.
Prepending replay_gain: is easy if you are using a script
behind some request.dynamic operator. If you are using the
playlist operator, you can use its prefix parameter.