Encoding Formats

When sending audio or video to an output — a file, an Icecast stream, an HLS endpoint — you need to specify how it should be encoded. Liquidsoap uses encoder values for this. They are passed directly to output operators and define the codec, bitrate, channels, and other format details.

output.file(%mp3(bitrate=128), "/tmp/archive.mp3", source)
output.icecast(%opus(bitrate=96), host="...", mount="stream.opus", source)

This page covers all built-in encoders, their parameters, and how to choose among them.

Encoder Syntax

Encoders are written with a % prefix followed by optional parameters in parentheses:

%encoder_name(parameter1=value1, parameter2=value2)

All parameters are optional and have defaults. The following are equivalent:

%mp3
%mp3()
%mp3(bitrate=128, samplerate=44100, stereo=true)

You can write mono=true or channels=1 interchangeably. Parameters can appear in any order.

Format Availability

Not every encoder is available in every build. Some require optional libraries. If you try to use an unavailable encoder, you will see:

Error 12: Unsupported encoder: %xyz().
You must be missing an optional dependency.

To check what is available in your build, run liquidsoap --build-config.

Choosing an Encoder

The right encoder depends on your use case:

Live streaming (Icecast, SHOUTcast): Use a format your listeners’ players support. %mp3 has the widest compatibility. %opus and %vorbis are well-supported in modern browsers and offer good quality at lower bitrates. %fdkaac is a good choice when AAC is required for Icecast. Lossless formats like %flac (via %ogg(%flac)) are an option if your listeners can handle the bandwidth.

HLS: Use %ffmpeg — it is the only encoder that can produce the container formats (MPEG-TS, fMP4) that HLS segments require. See the FFmpeg encoder page for details.

Archiving: Use lossless formats when quality matters: %flac for compressed lossless, %wav for raw PCM. If storage is a concern, %mp3 or %opus at high bitrate are good lossy choices.

Re-encoding / transcoding: Use %ffmpeg, which gives access to all FFmpeg codecs and containers. It is the most flexible option and the only one supporting video. See the FFmpeg encoder page for details.

Real-time / embedded: %shine (fixed-point MP3) is designed for architectures without a hardware FPU (e.g. some ARM boards). %opus at small frame sizes (frame_size=10.) is well-suited for low-latency applications like voice.

Format Reference

MP3

MP3 encoding is provided by libmp3lame and comes in three flavors:

• %mp3 or %mp3.cbr: Constant bitrate
• %mp3.vbr: Variable bitrate, quality-based
• %mp3.abr: Average bitrate with optional min/max bounds

Common parameters (all three flavors):

%mp3 / %mp3.cbr parameters:

%mp3.vbr parameters:

%mp3.abr parameters:

Examples:

# Standard 128 kbps stereo stream
output.icecast(%mp3(bitrate=128), host="myserver", mount="stream.mp3", source)

# High-quality VBR archive
output.file(%mp3.vbr(quality=0), "/tmp/archive.mp3", source)

# Average bitrate with bounds
output.file(%mp3.abr(bitrate=192, min_bitrate=128, max_bitrate=320), "/tmp/out.mp3", source)

# Low-bitrate mono speech (use mean() to downmix stereo to mono)
output.file(%mp3(bitrate=32, mono=true), "/tmp/speech.mp3", mean(source))

Shine

Shine is a fixed-point MP3 encoder. It is useful on systems without a hardware floating-point unit (FPU), such as some embedded ARM devices, or anywhere libmp3lame is unavailable. It produces constant-bitrate MP3 only.

%shine(channels=2, samplerate=44100, bitrate=128)

WAV

WAV output writes PCM audio with a standard RIFF/WAV header. Useful for archiving uncompressed audio or piping to external tools.

%wav(stereo=true, channels=2, samplesize=16, header=true, duration=10.)

Because Liquidsoap encodes a potentially infinite stream, the WAV header length field is set to its maximum value by default. If you know the duration in advance and need an accurate header, set duration explicitly.

Examples:

# Uncompressed 24-bit stereo archive
output.file(%wav(samplesize = 24), "/tmp/archive.wav", source)

# Raw PCM pipe to external process
output.external(
  %wav(header = false),
  "ffmpeg -f s16le -ar 44100 -ac 2 -i - out.mp4",
  source
)

FLAC

FLAC is a lossless compressed format. It comes in two variants:

• %flac: Native FLAC file format. Suitable for file output, not for streaming.
• %ogg(%flac): FLAC encapsulated in an Ogg container. Can be streamed via Icecast.

%flac(samplerate=44100, channels=2, compression=5, bits_per_sample=16)

Examples:

# Lossless archive
output.file(%flac(compression=8, bits_per_sample=24), "/tmp/archive.flac", source)

# Streamable Ogg/FLAC
output.icecast(%ogg(%flac), host="myserver", mount="stream.flac", source)

FDK-AAC

FDK-AAC is a high-quality AAC encoder from Fraunhofer, supporting both AAC-LC and HE-AAC (AAC+). It is well-suited for Icecast streaming.

%fdkaac(channels=2, samplerate=44100, bitrate=64, bandwidth="auto",
        afterburner=false, aot="mpeg4_he_aac_v2", transmux="adts", sbr_mode=false)

aot values:

transmux values: "raw", "adif", "adts", "latm", "latm_out_of_band", "loas".

See the Hydrogenaudio knowledge base for details on configuration values.

Examples:

# HE-AAC v2 stream at 48 kbps — good quality at low bitrate
output.icecast(
  %fdkaac(bitrate = 48, aot = "mpeg4_he_aac_v2"),
  host="myserver",
  mount="stream.aac",
  source
)

# AAC-LC for Icecast, ADTS muxing
output.file(
  %fdkaac(bitrate = 192, aot = "mpeg4_aac_lc", transmux = "adts"),
  "/tmp/out.aac",
  source
)

# Variable bitrate, high quality
output.file(%fdkaac(vbr = 5, aot = "mpeg4_aac_lc"), "/tmp/archive.aac", source)

Ogg Container

Ogg is a free, open container format. Several codecs can be encapsulated in it:

%ogg(codec1, codec2, ...)

As a shorthand, you can write %vorbis(...) instead of %ogg(%vorbis(...)). Both produce an Ogg stream.

All Ogg encoders share a bytes_per_page parameter that limits the size of Ogg logical pages:

# Limit page size to 4096 bytes
%vorbis(bytes_per_page=4096)

Vorbis

Vorbis is a free, open lossy audio codec. It comes in three bitrate modes:

# Variable bitrate (default)
%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)

Examples:

# Standard Ogg/Vorbis stream
output.icecast(%vorbis(quality=0.5), host="myserver", mount="stream.ogg", source)

# High-quality archive
output.file(%vorbis(quality=0.9), "/tmp/archive.ogg", source)

Opus

Opus is a modern, versatile lossy codec optimised for both voice and music. It excels at low bitrates and low latency and is well-supported in browsers and modern players. Opus is always encapsulated in Ogg.

%opus(samplerate=48000, channels=2, bitrate="auto",
      vbr="unconstrained", complexity=9, frame_size=20.)

See the Opus documentation for full details.

Examples:

# General-purpose music stream
output.icecast(%opus(bitrate=128), host="myserver", mount="stream.opus", source)

# Low-bitrate voice stream (use mean() to downmix stereo to mono)
output.icecast(%opus(bitrate=24, application="voip", signal="voice", channels=1), host="myserver", mount="stream-voice.opus", mean(source))

# Low-latency real-time audio
output.icecast(%opus(frame_size=10., application="restricted_lowdelay"), host="myserver", mount="stream-ll.opus", source)

FFmpeg

The %ffmpeg encoder provides access to all FFmpeg codecs and containers, including video. It is the most powerful and flexible option, and the only one suitable for HLS output.

See the dedicated FFmpeg encoder page for full documentation.

# AAC audio in an MPEG-TS container
output.file(%ffmpeg(format="mpegts", %audio(codec="aac", b="128k")), "/tmp/out.ts", source)