An open-source engine that turns a plain description of a radio station (jingle every N tracks, no artist twice inside a 10-track window, a weekend that feels different from a weekday, mix blocks of specific genres) into iTunes-XML playlists that drop straight into Music. Every track placement is explained, and the same inputs always produce byte-for-byte identical output. Built for, and running in production on, a real UK internet radio station.
The problem
Rebirth Radio, a UK internet station, runs on a bespoke generator: a 2,196-slot weekly playlist whose template interleaves commercial music, sequential night and weekend blocks, genre-tagged mixes, jingles, and references back to the previous week. It works, but every rule is baked into code. It is a single-station system by construction.
Then the station wanted a second offering, Rebirth Classics. The obvious path was to fork the generator and hardcode a second template. The obvious path scales badly: every future station becomes another fork, another copy of the constraint logic, another thing to maintain in lockstep, and every copy is another place to break a station that is already on air.
The decision: generalise, don’t fork
Station Studio is the alternative. Instead of a second bespoke generator, it is a general-purpose station-authoring tool: a station becomes data, not code. A station is a named template (the slot layout), its source-pool bindings, and its rules. New stations are authored through configuration alone, with no engine changes.
The bet paid off twice over. Rebirth Classics was authored on the new engine, and the original Rebirth Radio schedule was then ported onto the same shared engine, so one engine now drives both production stations, while the original bespoke generator is kept intact and operational as a safety net rather than switched off in a big-bang cutover.
The engine
At the core is a single pure function: a station template plus a week number in, a list of fully traced slots out.
Every layout block declares exactly one of eight sampling strategies, and the engine routes by name to a per-strategy sampler:
weighted: the default content strategy. Weights are computed at sampling time from remaining² (an artist’s remaining pool count squared), so under-represented artists are actively favoured as a block plays out. A three-tier fallback (artist-dedup → relaxed-dedup → unconstrained) widens the candidate set only when a tier finds nobody eligible, and a sliding window (default 10) enforces “no same artist within the last N picks”.window: a deterministic consecutive read: N tracks in pool order from the cursor, no randomness.sequential: walks a named cursor through a pool, so a block continues exactly where it left off last week.pick: a plain RNG-controlled pick, seedable off the station for reproducibility.jingle / mix: pick from a single-genre subset, with mix adding an exclusion window so the same track does not recur too soon.prev_ref: reads the previous week’s slot at a fixed position, giving cross-week continuity.archive_ref: reads a fixed position from a reference pool.
The layout walk is a pure function of its inputs. That single property is what makes everything downstream possible: reproducibility, the trace, and the test harness.
Determinism, and showing the working
Two properties set the output apart from “shuffle”.
Byte-for-byte reproducibility. The same template, the same source files, and the same week number produce the same playlist, byte-for-byte. This is not an aspiration; it is pinned by a byte-equality test harness that regenerates output and compares it against committed sequence snapshots. iTunes-export IDs are stable too, derived deterministically from the station, week, and slot position.
A trace for every pick. Each slot records why its track was chosen and why each rejected candidate was rejected: for example, that a cursor for a named block sits at a given position and this is the Nth slot of that block. The per-slot trace viewer surfaces all of it: the pool a track came from, the strategy that placed it, and its position in that pool.
History is kept, not overwritten. Regeneration is non-destructive: each run appends a new numbered version rather than clobbering the last, and external playlist links stay stable across regenerations. The trace viewer exposes that history directly: a version picker steps through every past generation of a given week.
Editing a generated week
The trace became the way in, not only the explanation. On a week’s page each song now shows the rule that put it there, in plain words (“Shuffled from POP, no artist twice in 10”), and why the engine picked it. Clicking a song marks every song from the same rule and opens that rule beside the list. A change can go to every identical rule at once, which matters on real stations: one starter station repeats the same rule 21 times. Saving offers to regenerate the weeks made with the old rules, one at a time and in order, because each week continues from the one before.
That last step surfaced a real bug. Regenerating a past week on a station with persistent cursors started each sequence from where the latest week had left it, so an unchanged week could come out different. Each generation now records the cursor positions it started from, so regenerating a past week starts where that week started and leaves the weeks after it alone.
In the station editor the week’s songs now sit beside the blocks, each change waiting to be saved is listed in plain words with its own Undo, and songs, runs of songs or whole sections can be dragged to play somewhere else, from the keyboard as well as the mouse.
An exception is replayed, not patched in. One song of a generated week can now be changed for that week only, by swapping it or by changing its rule just there, and it stays changed when the week is generated again. A rule change is worked out by replaying the week with that one rule changed, with the same seed and inputs, stopping once it has played, so the new song is picked in exactly the context the original was. Each change is saved as a new version of the week, so Rollback undoes it too. The cost was measured rather than guessed: a replay takes up to about four seconds on Rebirth Radio’s 2,196 songs, so a week allows at most 20 rule changes, while swaps cost nothing.
The architecture
The template JSON is the source of truth. The UI is deliberately replaceable: it reads and writes the same JSON the engine consumes, so nothing about a station lives only in the interface. A station actually carries two documents: the template (the engine contract: sources, cursor, layout) and a separate sidecar (the editor’s view: sections, colours, grouping). Stripping the sidecar changes nothing about generation; it is a visualisation overlay, not part of the engine contract.
The sidecar’s home is a small architecture story in itself. It began on disk, where concurrent editor writes and request-time reads raced over the same file. It moved into the database as the authoritative copy, with the disk file demoted to a committable export artefact, and a schema validator wired in at the write boundary so any path that persists a sidecar (fixtures, scripts, future endpoints) is checked, not just the one intended entry point.
The stack is a FastAPI backend (stations, source imports, generation) with a thin SvelteKit frontend, over SQLite, with full iTunes-XML round-trip so real libraries go in and playable playlists come out.
Rigor
Testing is a four-layer pyramid, each layer earning its place:
- Backend unit + integration. Pytest over the engine and API.
- Byte-equality. Full generation pinned against committed sequence snapshots, so a reproducibility regression fails the build.
- Frontend unit. Vitest + Testing Library over component behaviour and state machines.
- End-to-end. Playwright + axe-core across the real backend, real frontend and real browser, with accessibility smoke tests running WCAG A/AA at multiple routes, including a narrow mobile viewport.
CI runs several jobs in parallel and gates the merge on all of them, including install smokes for both the pip wheel and the Docker image, and a migration-parity check that the migration history builds the same schema the models declare. The backend suite alone runs 1,502 tests, on top of the frontend and end-to-end layers.
Delivery: a real client engagement
The engineering exists to serve a live product, and the delivery was run to match.
- A real client, on a real cadence.
- Rebirth Radio is an on-air station, not a demo. Its schedule refreshes roughly weekly to twice-weekly, and each refresh is delivered the whole way to air: the engine generates iTunes-XML playlists that are pushed into a cloud media server, which is what actually feeds the station. The client’s own music libraries arrive as iTunes-XML exports, drop into a conventional inbox, and map one-to-one onto the engine’s source pools; a single idempotent bootstrap command imports them, seeds the station, and regenerates, so a library refresh flows through with no bespoke steps.
- Business analysis: turning “feel” into architecture.
- The hardest part was not the code, it was capturing what the station should sound like (the feel) and turning that into something a machine can execute. That analysis ran as joint sessions with the station: feedback, design and innovation worked out together and set against a delivery plan, then formalised into the template grammar and the engine’s strategy set. Subjective taste in; a precise, reproducible specification out.
- Iterative, design-first delivery.
- The build shipped as a long sequence of small, named, coherent slices, each one designed → discussed → implemented → reviewed → shipped. Anything non-trivial starts with a written design before any code, and every shipped slice is logged with why it exists, what shipped, and what was deliberately deferred: a durable decision record rather than tribal memory.
- Review as a habit.
- Two-commit slices get a mid-slice review (the first commit reviewed before the second is written) plus a whole-slice review once it ships. That multi-pass discipline has caught real bugs on already-settled structure that a single final review would have missed.
- Planned and tracked with the client.
- Delivery plans, feature tickets and feedback are managed on a shared Trello board, so what is in flight and what is coming next stays legible to the client without a meeting; the engineering design discussions and the decision log live alongside the code.
- Professional release management.
- Updates ship as versioned releases, not ad-hoc pushes: semantic versioning, a Keep-a-Changelog history, and public releases published through automated pipelines (1.20.1 at the time of writing), with the documentation site built and deployed the same way. Since 1.6.0 each release is also a Mac and Windows download that offers Update now.
- Safe iteration on something that is on air.
- The byte-equality guarantee is not only a testing nicety, it is the delivery safeguard: because generation is pinned against committed snapshots for the production stations, any change that would alter a live station’s output fails the build before it can reach the client. That is what makes fast iteration on a running station safe rather than nerve-wracking.
Trade-offs and what is next
Some decisions were about what not to build yet:
- Wizard first, editor after. The authoring wizard produced the canonical template first. The station editor that followed (blocks on a canvas, the week’s songs beside them, drag to move, undo for each change) works on that same template, so the data model did not change when the richer editor landed.
- Strategies added on demand. The engine grew its strategy set as real stations needed them, rather than speculatively up front.
- Original kept running. Even after porting Rebirth Radio onto the shared engine, the original bespoke generator is kept intact and operational, a deliberate safety net over a hard cutover.
Four install channels ship as first-class (a Mac or Windows download, Docker, a pip wheel and a dev clone), with example stations and starter and product documentation in the box, so the whole pipeline is runnable, and understandable, in minutes.
The weeks no longer stop at the export. Station Player plays each one in station order, without iTunes, and Station Server puts it on air, with Studio sending each week to it directly over a link. That side of the story, built with an AI agent in short releases shaped by its users, is the Station Server and Station Player case study.
