Encoding Formats in Liquidsoap 🎙️
When you’re ready to send audio (or video!) out into the world—whether to Icecast, a file, or another system—you’ll need to encode it into a suitable format. MP3, Opus, FLAC, WAV… Liquidsoap supports many, and each comes with its own settings and behaviors.
At the heart of this process are encoders—special values that you pass to output operators to define the desired stream format.
This page introduces how encoders work in Liquidsoap, how they influence your pipeline, and what formats and options are available. Don’t worry if it feels abstract at first—it’s a central concept, and it will click as you explore more! 🚀
Encoders: More Than Just Compression
In Liquidsoap, an encoder is more than just a codec or compression setting. It defines the structure of the stream—and that structure must match the source you’re feeding into it.
For example, if you write:
output.file(%mp3, "/tmp/foo.mp3", playlist("songs"))
You might think: “I want to encode this playlist as MP3.” But under
the hood, %mp3
is a format specification.
It says: This output will encode stereo PCM audio in MP3
format.
So your playlist("songs")
must produce that exact kind
of data—PCM audio, stereo. If it doesn’t, Liquidsoap may try to convert
it. But it can’t always.
🧠 Important: The encoder drives the output type. You must feed it a compatible source.
For instance:
%mp3
expectsformat(audio=pcm(stereo))
%theora
expects video%opus(channels=1)
expects mono audio
So, if you use %mp3
in your output, your source must
produce stereo PCM audio. If it doesn’t, Liquidsoap will try to adapt
it:
- Mono sources? Liquidsoap duplicates the channel to make stereo.
- Stereo sources for a mono encoder? Liquidsoap averages both channels.
Encoder Syntax
Encoders use a special syntax:
%encoder_name(parameter1=value1, parameter2=value2)
You can omit parameters if defaults are acceptable:
output.icecast(%mp3, my_source)
Parameters are optional (unless noted) and can be reordered. You can
also write mono=true
or channels=1
; both are
equivalent.
⚠️ Format Availability
Not all encoders are always available in every Liquidsoap build. Some require optional libraries.
If an encoder isn’t available, you’ll see something like:
Error 12: Unsupported encoder: %xyz().
You must be missing an optional dependency.
In this case, you might need to enable an external dependency (if you
are installing via opam
) or rebuild liquidsoap.
On our Windows build, only %ffmpeg
is included due to
linking limitations. Luckily, %ffmpeg
supports many common
formats.
🔍 Format Reference
MP3
Mp3 encoder comes in 3 flavors:
%mp3
or%mp3.cbr
: Constant bitrate encoding%mp3.vbr
: Variable bitrate, quality-based encoding.%mp3.abr
: Average bitrate based encoding.
Parameters common to each flavor are:
stereo=true/false
,mono=true/false
: Encode stereo or mono data (default:stereo
).stereo_mode
: One of:"stereo"
,"joint_stereo"
or"default"
(default:"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:44100
)internal_quality=2
: Lame algorithms internal quality. A value between0
and9
,0
being highest quality and9
the worst (default:2
).id3v2=true
: Add anid3v2
tag to encoded data (default:false
).
Parameters for %mp3
are:
bitrate
: Encoded data fixed bitrate
Parameters for %mp3.vbr
are:
quality
: Quality of encoded data; ranges from0
(highest quality) to9
(worst quality).
Parameters for %mp3.abr
are:
bitrate
: Average bitratemin_bitrate
: Minimum bitratemax_bitrate
: Maximum bitratehard_min
: Enforce minimal bitrate
Examples:
- Constant
128
kbps bitrate encoding:%mp3(bitrate=128)
- Variable bitrate with quality
6
and samplerate of22050
Hz:%mp3.vbr(quality=7,samplerate=22050)
- Average bitrate with mean of
128
kbps, maximum bitrate192
kbps andid3v2
tags:%mp3.abr(bitrate=128,max_bitrate=192,id3v2=true)
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
Shine is the fixed-point mp3 encoder. It is useful on architectures without a FPU, such as ARM.
%shine(channels=2,samplerate=44100,bitrate=128)
WAV
%wav(stereo=true, channels=2, samplesize=16, header=true, duration=10.)
If header
is false
, the encoder outputs raw
PCM. duration
is optional and is used to set the WAV length
header.
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
the duration
parameter.
FFmpeg
See detailed ffmpeg encoders article.
Ogg
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
%ogg(%vorbis(...))
.
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)
Vorbis
# 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)
Opus
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"none"
,"constrained"
or"unconstrained"
application
: One of"audio"
,"voip"
or"restricted_lowdelay"
complexity
: Integer value between0
and10
.max_bandwidth
: One of"narrow_band"
,"medium_band"
,"wide_band"
,"super_wide_band"
or"full_band"
samplerate
: input samplerate. Must be one of:8000
,12000
,16000
,24000
or48000
frame_size
: encoding frame size, in milliseconds. Must be one of:2.5
,5.
,10.
,20.
,40.
or60.
.bitrate
: encoding bitrate, inkbps
. Must be a value between5
and512
. You can also set it to"auto"
.channels
: currently, only1
or2
channels are allowed.mono
,stereo
: equivalent tochannels=1
andchannels=2
.signal
: one of"voice"
or"music"
Theora
%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
settings frame.video.height/width
.
Speex
%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 abr=x
or
vbr=y
.
Flac
The flac encoding format comes in two flavors:
%flac
is 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: 8
,
16
, 24
or 32
. Please note that
32
bits per sample is currently not supported by the
underlying libflac
.
FDK-AAC
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)
Where aot
is one of: "mpeg4_aac_lc"
,
"mpeg4_he_aac"
, "mpeg4_he_aac_v2"
,
"mpeg4_aac_ld"
, "mpeg4_aac_eld"
,
"mpeg2_aac_lc"
, "mpeg2_he_aac"
or
"mpeg2_he_aac_v2"
bandwidth
is one of: "auto"
, any supported
integer value.
transmux
is one of: "raw"
,
"adif"
, "adts"
, "latm"
,
"latm_out_of_band"
or "loas"
.
Bitrate can be either constant by passing: bitrate=64
or
variable: vbr=<1-5>
You can consult the Hydrogenaudio knowledge base for more details on configuration values and meanings.