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.

This repository contains a professional-grade audio streaming solution originally built for ZuidWest FM, Radio Rucphen, and BredaNu in the Netherlands.
- This repo turns a regional radio station into a software-defined control room with redundancy, processing, and distribution handled in one maintainable stack.
- Its real innovation is operational: failover, source forcing, and clock isolation keep broadcast paths stable even when inputs or outputs misbehave.
- The numbered Liquidsoap modules make a complex live system readable, testable, and easier to run than a monolithic script.
- It sits between raw Liquidsoap and a full radio suite like AzuraCast, aimed at broadcasters who need control more than a web UI.
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.
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.
| Layer | zwfm-liquidsoap | Raw Liquidsoap | AzuraCast | Butt |
|---|---|---|---|---|
| Operational model | Production broadcast orchestration | Flexible audio DSL | Full station management suite | Single-purpose streaming client |
| Failover | Built around redundant SRT and fallback sources | Possible, but you assemble it yourself | Supported, but wrapped in a broader UI | Very limited |
| Outputs | Icecast, DAB+, MicroMPX for FM | Whatever you script | Mostly web streaming workflows | Icecast and Shoutcast |
| Operator control | Unix socket source forcing | Depends on your script | Web UI driven | GUI driven |
| Best fit | Regional broadcasters with strict uptime needs | Engineers building from scratch | Stations wanting a web platform | Individual 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.
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.





