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.

9 min read • View on GitHub • More from oszuidwest

A broad radio control desk where multiple metadata sources feed a central routing console and then split toward several outputs. A small clock mechanism holds one update back while the rest of the system keeps moving, showing that timing and fallback are part of the job.
Radio metadata is not a string problem. It is a routing problem with timing, priority, and multiple destinations.

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.

rmens, Contributor/Maintainer · oszuidwest/zwfm-metadata GitHub Repository
Key Takeaways

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.

A close-up of a metadata card broken into three labeled blocks that move toward a receiver display. The pieces show artist, separator, and title as separate parts, explaining why structured metadata matters for DAB+ DL Plus.
Structured metadata preserves meaning that a plain concatenated string would flatten away.

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.

The scheduler is the part that keeps the router correct. Without it, the system would only be fast, not right.

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.

ApproachWhat survivesWhere it breaks down
Raw concatenated stringOne display lineSemantic boundaries disappear before output-specific formatting
Structured textArtist, separator, titleRequires a slightly richer model, but supports DL Plus cleanly
Output-specific formatting at the edgeSource meaning plus destination rulesLets 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

A hedcut-style portrait based on the verified GitHub avatar for rmens. It identifies the maintainer behind the project and gives the article a human anchor without inventing a new photograph.

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.

OptionStrengthWeakness
Go middlewareSingle binary, concurrency, predictable deploymentLess expressive than scripting for one-off hacks
Embedded metadata inside an audio engineFewer moving parts in small setupsHarder to isolate routing policy and output quirks
Proprietary playout utilityConvenient if you are locked into one vendorOpaque 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.