Encoders are used to define formats into which raw sources should be
encoded by an output. Syntax for encoder is:
%encoder(parameters...) or, if you use default parameters,
Please note that not all encoding formats are available at all time. Most of them require optional dependencies. If a format is not available, you should see an error like this:
Error 12: Unsupported encoder: %sine(). You must be missing an optional dependency.
In particular, due to limitations with static linking on windows,
%ffmpeg encoder is available with our windows
build. However, this encoder provides a lot of codecs and formats, and
it is quite likely that it can provide what you need.
In most liquidsoap scripts, the encoding format determines what kind of data is streamed.
The type of an encoding format depends on its parameter. For example,
%mp3 has type
%mp3(mono) has type
The type of an output like
output.file is something like
(...,format('a),...,source('a))->source('a). This means
that your source will have to have the same type as your format.
For example if you write
then the playlist source will have to stream stereo audio. Thus it will reject mono and video files.
Liquidsoap provides operators that can be used to convert sources
into a format acceptable for a given encoder. For instance, the
mean operator transforms any audio source into a mono
source and the
audio_to_stereo operator transforms any
audio source into a stereo source.
All parameters are optional, and the parenthesis are not needed when
no parameter is passed. In the following default values are shown. As a
special case, the keywords
be used to indicate the number of channels (whether is is passed as an
integer or a boolean).
Mp3 encoder comes in 3 flavors:
%mp3.cbr: Constant bitrate encoding
%mp3.vbr: Variable bitrate, quality-based encoding.
%mp3.abr: Average bitrate based encoding.
Parameters common to each flavor are:
mono=true/false: Encode stereo or mono data (default:
stereo_mode: One of:
"default"). Default means that the underlying library (
libmp3lame) will pick the stereo mode based on compression ration and input channels.
samplerate=44100: Encoded data samplerate (default:
internal_quality=2: Lame algorithms internal quality. A value between
0being highest quality and
9the worst (default:
id3v2=true: Add an
id3v2tag to encoded data (default:
false). This option is only valid if liquidsoap has been compiled with taglib support.
bitrate: Encoded data fixed bitrate
quality: Quality of encoded data; ranges from
0(highest quality) to
bitrate: Average bitrate
min_bitrate: Minimum bitrate
max_bitrate: Maximum bitrate
hard_min: Enforce minimal bitrate
128kbps bitrate encoding:
- Variable bitrate with quality
6and samplerate of
- Average bitrate with mean of
128kbps, maximum bitrate
Optionally, liquidsoap can insert a message within mp3 data. You can
set its value using the
msg parameter. Setting it to
"" disables this feature. This is its default value.
Shine is the fixed-point mp3 encoder. It is useful on architectures
without a FPU, such as ARM. It is named
%mp3.fxp and its parameters are:
%wav(stereo=true, channels=2, samplesize=16, header=true, duration=10.)
false, the encoder outputs raw
duration is optional and is used to set the WAV length
Because Liquidsoap encodes a possibly infinite stream, there is no way to know in advance the duration of encoded data. Since WAV header has to be written first, by default its length is set to the maximum possible value. If you know the expected duration of the encoded data and you actually care about the WAV length header then you should use this parameter.
See detailed ffmpeg encoders article.
The following formats can be put together in an Ogg container. The
syntax for doing so is
%ogg(x,y,z) but it is also possible
to just write
%vorbis(...), for example, instead of
All ogg encoders have a
bytes_per_page parameter, which
can be used to try to limit ogg logical pages size. For instance:
# Try to limit vorbis pages size to 1024 bytes %vorbis(bytes_per_page=1024)
# Variable bitrate %vorbis(samplerate=44100, channels=2, quality=0.3) % Average bitrate %vorbis.abr(samplerate=44100, channels=2, bitrate=128, max_bitrate=192, min_bitrate=64) # Constant bitrate %vorbis.cbr(samplerate=44100, channels=2, bitrate=128)
Quality ranges from -0.2 to 1, but quality -0.2 is only available with the aotuv implementation of libvorbis.
Opus is a lossy audio compression made especially suitable for interactive real-time applications over the Internet. Liquidsoap supports Opus data encapsulated into Ogg streams.
The encoder is named
%opus and its parameters are as
follows. Please refer to the Opus documentation for
information about their meanings and values.
vbr: one of
application: One of
complexity: Integer value between
max_bandwidth: One of
samplerate: input samplerate. Must be one of:
frame_size: encoding frame size, in milliseconds. Must be one of:
bitrate: encoding bitrate, in
kbps. Must be a value between
512. You can also set it to
channels: currently, only
2channels are allowed.
stereo: equivalent to
signal: one of
%theora(quality=40,width=640,height=480, picture_width=255,picture_height=255, picture_x=0, picture_y=0, aspect_numerator=1, aspect_denominator=1, keyframe_frequency=64, vp3_compatible=false, soft_target=false, buffer_delay=5, speed=0)
You can also pass
bitrate=x explicitly instead of a
quality. The default dimensions are liquidsoap’s default, from the
%speex(stereo=false, samplerate=44100, quality=7, mode=wideband, # One of: wideband|narrowband|ultra-wideband frames_per_packet=1, complexity=5)
You can also control quality using
The flac encoding format comes in two flavors:
%flacis the native flac format, useful for file output but not for streaming purpose
%ogg(%flac,...)is the ogg/flac format, which can be used to broadcast data with icecast
The parameters are:
%flac(samplerate=44100, channels=2, compression=5, bits_per_sample=16)
compression ranges from 0 to 8 and
bits_per_sample should be one of:
32. Please note that
32 bits per sample is currently not supported by the
This encoder can do both AAC and AAC+.
Its syntax is:
%fdkaac(channels=2, samplerate=44100, bandwidth="auto", bitrate=64, afterburner=false, aot="mpeg2_he_aac_v2", transmux="adts", sbr_mode=false)
aot is one of:
bandwidth is one of:
"auto", any supported
transmux is one of:
Bitrate can be either constant by passing:
You can consult the Hydrogenaudio knowledge base for more details on configuration values and meanings.
%gstreamer encoder can be used to encode streams
gstreamer multimedia framework. This encoder
extends liquidsoap with all available GStreamer formats which includes
most, if not all, formats available to your operating system.
The encoder’s parameters are as follows:
%gstreamer(channels=2, audio="lamemp3enc", has_video=true, video="x264enc", muxer="mpegtsmux", metadata="metadata", log=5, pipeline="")
Please refer to the Gstreamer encoder page for a detailed explanation of this encoder.
For a detailed presentation of external encoders, see this page.
%external(channels=2,samplerate=44100,header=true, restart_on_crash=false, restart_on_metadata,restart_after_delay=30, process="progname")
Only one of
restart_after_delay should be passed. The delay is
specified in seconds. The encoding process is mandatory, and can also be
passed directly as a string, without