zwfm-liquidsoap: The Linux Control Room Behind a Software-Defined Radio Station

A modular Liquidsoap stack that takes redundant SRT studio feeds, applies broadcast processing, and fans out to Icecast, DAB+, and FM without turning into a spaghetti script.

9 min read • View on GitHub • More from oszuidwest

A wide editorial illustration shows a single Linux server cabinet centered like a broadcast nerve center. Two studio feeds enter from the left as redundant SRT lines, while three output paths leave on the right toward web streaming, DAB+, and FM transmission, with a small operator hand poised near a manual override switch. It explains that the repo treats radio as resilient infrastructure, not just audio playback.
One stack, many delivery paths, with failover and operator control built into the layout.

This repository contains a professional-grade audio streaming solution originally built for ZuidWest FM, Radio Rucphen, and BredaNu in the Netherlands.

rmens, Project Maintainer · zwfm-liquidsoap GitHub README
Key Takeaways

The surprise in zwfm-liquidsoap is not that it streams audio. It is that it behaves like a broadcast control room, with the kind of redundancy and operator control you usually expect from hardware racks, not a Docker stack.

That matters because radio is unforgiving. If a studio feed drops, a processor stalls, or an output lags, listeners hear it immediately. This repo is built around that reality, which is why the architecture starts with failover and isolation instead of playlists and dashboards.

The radio station that lives inside one stack

The project powers multiple Dutch regional stations, including ZuidWest FM, Radio Rucphen, and BredaNu. Its job is to take studio audio over SRT, process it for broadcast, and deliver it to several destinations without turning the whole chain into a fragile one-off script.

A hedcut-style portrait of rmens based on their verified GitHub avatar. It gives a human face to the maintainer behind the broadcast stack and anchors the project in an identifiable operator rather than an abstract organization.

The core idea is failover, not just streaming

The important mental model here is a ladder of trust. Studio A is first. Studio B is the backup. If both are missing or silent, the system can fall through to a local emergency file, then to blank audio as a last resort that keeps the process alive.

A priority ladder, not a flat input list. The system keeps moving down only when the higher-priority source fails or goes silent.

Layerzwfm-liquidsoapRaw LiquidsoapAzuraCastButt
Operational modelProduction broadcast orchestrationFlexible audio DSLFull station management suiteSingle-purpose streaming client
FailoverBuilt around redundant SRT and fallback sourcesPossible, but you assemble it yourselfSupported, but wrapped in a broader UIVery limited
OutputsIcecast, DAB+, MicroMPX for FMWhatever you scriptMostly web streaming workflowsIcecast and Shoutcast
Operator controlUnix socket source forcingDepends on your scriptWeb UI drivenGUI driven
Best fitRegional broadcasters with strict uptime needsEngineers building from scratchStations wanting a web platformIndividual streamers

The comparison is the point. Raw Liquidsoap is the toolkit. AzuraCast is the suite. Butt is the client. zwfm-liquidsoap is the middle layer for a station that needs broadcast discipline, not just a way to push audio to a server.

Why the library is split into numbered modules

The repo avoids the classic Liquidsoap trap: one huge script that everyone fears to touch. Instead, conf/lib/ breaks the station into numbered pieces for settings, state, source creation, fallback, processing, and outputs.

# Pseudo-structure from the repo's modular layout
# 00_settings.liq: environment and defaults
# 20_state.liq: operator override state
# 41_source_studio.liq: SRT input factory
# 40_source_fallback.liq: priority ladder
# 50_processing.liq: broadcast processing
# 60_output_icecast.liq: isolated output clocks
# 90_radio.liq: station assembly

source = create_radio()
start_audio(source)

That numbering matters because it creates a reading order. You can trace the path from environment variables to source selection to processing to outputs without mentally untangling a monolith. In live audio, readability is operational safety.

The clever part is clock isolation

The most technical idea in the repo is also the most subtle. Each output can be buffered into its own clock domain, so a slow Icecast endpoint does not drag down the rest of the system.

A close-up editorial illustration shows a narrow bridge between audio modules, with one clogged lane on the left trying to back up while a buffer box holds the pressure. Two cleaner lanes on the right continue moving smoothly past the isolation boundary. It explains how clock isolation prevents one slow output from disturbing the rest of the broadcast chain.
A buffer boundary keeps one blocked output from poisoning the whole pipeline.

That is what keeps the stack professional-grade. A broadcast chain is only as strong as its weakest output, and this design makes that weakness local instead of contagious.

StereoTool is treated like a first-class stage, not a bolt-on

The repo does not pretend every part of the stack is open source purity theater. It integrates StereoTool where it makes sense, keeps the system alive if the license is missing, and logs the consequences rather than hiding them.

That pragmatic stance is rare and useful. Broadcast engineering often mixes open source, proprietary hardware, and vendor tools. This project accepts that reality and still keeps the control plane coherent.

Runtime control turns a script into an operating console

The Unix socket is the move that changes everything. Instead of treating Liquidsoap as a fixed config, the stack can accept a forced source like set_forced_source("studio_b") and let an operator take over live.

# Conceptual control path
# The operator can pin a source over the normal fallback ladder.
set_forced_source("studio_b")
# Later, release control and return to automatic selection.
clear_forced_source()

That is the difference between a pipeline and an operations surface. The script still has rules, but the human in the room is not locked out of the room.

What this stack is, compared with the alternatives

The repo sits in a narrow but important lane. It is not trying to be the friendliest web radio product or the simplest streaming client. It is trying to be the dependable middle layer for a broadcaster with multiple delivery targets and strict uptime expectations.

Raw Liquidsoap gives you power. AzuraCast gives you a suite. Butt gives you an easy client. zwfm-liquidsoap gives you a maintained operating pattern for regional broadcast.

That is why the codebase feels more like infrastructure than application code. It is a set of design decisions about where failure should land, who can intervene, and how many outputs can share one source without stepping on each other.

A production system that reads like infrastructure code

The deeper lesson is simple. Good broadcast engineering is not about making one stream play. It is about isolating failure, codifying fallback, and keeping human control in the loop when the machine reaches the edge of its own logic.

This repo does that in a compact, readable way. It turns a regional station into a software-defined system without pretending the physical world disappeared.