zwfm-metadata: The Router That Keeps Radio Metadata Honest
An open-source Go middleware for broadcast stations that schedules, formats, and falls back across live playout, streams, webhooks, and DAB+ without letting stale Now Playing data leak through.
Metadata routing middleware for radio stations that routes metadata from inputs (playout software, APIs, and static text) to outputs (Icecast, files, and webhooks) with priority-based fallback and configurable delays.
- zwfm-metadata treats Now Playing as a routed data product, not a display string.
- Its main trick is combining priority fallback with scheduled delivery so stale metadata does not leak through.
- Structured text is not a nice-to-have here, because DAB+ DL Plus depends on preserving artist, separator, and title boundaries.
- The project reads like broadcast middleware built for real station operations, not a generic webhook relay.
Radio metadata looks simple until it goes wrong. A station can have a live DJ, an automation system, a fallback text source, a delayed stream, and several destinations that do not want the same payload at the same moment. If the wrong song title shows up late, or never gets replaced, the mistake is public.
That is the problem zwfm-metadata is built to solve. It is not a thin relay. It is a small routing layer for broadcast metadata, with expiration, fallback, delay, filters, and output-specific formatting baked in.
Radio Metadata Is a State Machine, Not a String
The core insight is that broadcast metadata changes over time. A track starts, a presenter overrides it, a fallback station ID kicks in, then the original source expires. Each update has a lifecycle, and each output may need it at a slightly different moment.
That makes the repo feel more like infrastructure than application code. The system has to know which source is authoritative, when an update becomes stale, and how to avoid replaying old state after a newer event has already won.
The Router at the Center
The main object in the codebase is the MetadataRouter. It connects inputs to outputs, decides what is currently valid, and pushes accepted metadata through a timeline before it reaches a destination.
That timeline is the real surprise. Instead of sending every change immediately, the router can hold an update, emit it later, or cancel it if a newer source takes over first. In broadcast terms, that keeps the displayed metadata aligned with the audio rather than merely aligned with the last API call.
Why Structured Text Matters for DAB+ DL Plus
This is where the project becomes unmistakably specialized. DAB+ DL Plus does not just want a single merged string. It wants the boundaries preserved between artist, separator, and title so receivers can render those parts properly.
That choice shapes the data model. A system that preserves structure can target multiple outputs without destroying meaning on the way out. A system that flattens everything early has already lost the information DAB+ needs.
| Approach | What survives | Where it breaks down |
|---|---|---|
| Raw concatenated string | One display line | Semantic boundaries disappear before output-specific formatting |
| Structured text | Artist, separator, title | Requires a slightly richer model, but supports DL Plus cleanly |
| Output-specific formatting at the edge | Source meaning plus destination rules | Lets the same metadata feed web, stream, and broadcast targets differently |
Filters, Expiration, and Fallback
The code treats stale metadata as a failure mode, not an inconvenience. Inputs can expire, filters can reject or trim fields, and the router can fall back to a lower-priority source instead of leaving an old song title in place.
That makes the filter layer feel like editorial policy for a station. One source can be cleared, another can be rejected entirely, and another can be massaged into a format that makes sense for the output without rewriting the upstream system.
// Conceptual flow
if !primary.IsAvailable() {
active = fallback
}
if update.Delay > 0 {
timeline.Schedule(update)
} else {
output.Send(format(update))
}
switch filter.Action {
case FilterClearArtist:
update.Artist = ""
case FilterReject:
return nil
}
A White-Label Backend for Broadcast Ops
The web layer matters because this is a tool meant to be operated, not admired. The repo includes a dashboard, branding hooks, payload mapping, and live updates, which makes it usable in a station environment where people need to see what is active right now.
That is a useful reminder: a backend tool can still have a front door. Here, the UI is not the product, but it is part of the contract.
Why Go Fits This Job
Go is a sensible choice for a long-running middleware service like this. It gives the project concurrency for polling and routing, a small deployment footprint, and a single binary that is easy to drop onto a station server.
The language also encourages the shape this codebase already has: clear interfaces, focused packages, and a standard library-first web server. For infrastructure that runs all day, boring is a feature.
| Option | Strength | Weakness |
|---|---|---|
| Go middleware | Single binary, concurrency, predictable deployment | Less expressive than scripting for one-off hacks |
| Embedded metadata inside an audio engine | Fewer moving parts in small setups | Harder to isolate routing policy and output quirks |
| Proprietary playout utility | Convenient if you are locked into one vendor | Opaque behavior and limited integration options |
The Open-Source Radio Stack Context
This repository makes the most sense as part of a larger broadcast stack. In ZuidWest FM's setup, Liquidsoap handles audio, while zwfm-metadata handles the program data around it. That split keeps the responsibilities clean.
The broader lesson is simple. When timing, fallback, and formatting are all first-class concerns, they deserve a dedicated component. Radio metadata is one of those cases.
What This Project Proves
The best infrastructure often comes from modeling a niche workflow precisely. zwfm-metadata succeeds because it treats broadcast metadata as a live system with priorities, expiry, and output-specific rules, not as a convenience field attached to audio.
That is why it feels bigger than its size. It encodes a real operational truth: the right metadata at the wrong time is still wrong.





