Core concepts & glossary

RadioButler uses a handful of recurring building blocks. Understanding these makes every later screen much easier. They fit together like this: a Radio station has Presenters (who each use a Voice), pulls text from Sources via Requests to create News and Features, plays music organised in Music Boxes, and broadcasts it all according to Radio Programs placed on the Scheduler.

Bed timing: Cue-in, Start next & Fade-out

A bed is background audio that plays under spoken content (news, weather, traffic, a feature, an opener…). These three timing values — which appear in many places across the app — control exactly how the voice sits on the bed. All are in seconds and may use decimals; some accept negative values.

Getting started: register & log in

Registration (the public home page)

On the public site index.aspx the "Start your radio here" form creates your account and first station in a few minutes. You can refine everything later, so don't worry about getting every choice perfect now.

The same home page also contains an About, Workflow, Pricing, Who we are and Contact section (with a contact form: Your name, Your email, Subject, Message → Send message). These are informational and don't require an account.

Logging in

The login box sits at the bottom of the left sidebar on the public pages.

The navigation menu

After login the left sidebar shows the full menu. Items appear roughly in the order you'd set a station up: from Overview down through content, music, voices, billing and Logout. Some items (such as Test getdata) are only visible to administrator accounts. The chapters of this manual follow this same order.

Overview (dashboard)

The Overview is the first screen after login and a launch pad for the three things every station needs. It lists what you already have and gives an "Add…" link for each.

Radio stations

This is the master settings page for one station. You can run several stations under one account — each one has its own settings on this page. It is long because almost everything the station does — how it speaks, what news/weather/traffic it makes, how loud it is, how it advertises — is configured here. You reach it by clicking a station on the Overview, or via Add radio station. Settings are grouped between horizontal divider lines; each group is explained below. At the very bottom, Save changes stores everything and Delete radio station removes the station and all its data.

Identity

DAB+ (digital radio broadcasting)

Music & replay behaviour

How a moderation blends two songs together

This is one of the core features that makes the station sound like real radio: the presenter doesn't talk in silence between songs — the talk is woven into the music so it never stops dead. The same mechanism is used for the hourly opener. It works in four steps:

1. The current song reaches its Start next point and begins fading out. The presenter's moderation starts right there — over the fading tail of the song.
2. The moderation plays.
3. The next song starts underneath at a lower volume (not silent). Its instrumental intro — the part before its Ramp1, where the vocals begin — runs under the end of the moderation, timed so the vocals come in exactly when the moderation finishes.
4. A music bed fills any remaining room. If the moderation is longer than that intro (longer than Ramp1), the earlier part would be empty — so a music bed (the bed you upload) plays under the moderation and fades out just as the next song arrives; the song starts into the fading bed. If the moderation is short and the intro (Ramp1) long, there is no room and no bed is used.

Incoming call auto-check

Music Wish responses (e-mail to the listener)

When a listener sends a Music Wish from your player, RadioButler decides whether the song will be played and then e-mails the listener the outcome. These three fields define that e-mail — one subject line and two body texts (one for "yes", one for "no"). If you leave them blank, a built-in default text in the station's language is used instead. The full decision process is described under How to → Music Request.

All three may contain placeholders that are filled in automatically:

Facebook auto-posting

Lets the station automatically publish posts (e.g. about what's playing or breaking news) to a Facebook page.

Two tracks to Facebook

A news story can reach your page two ways, and they never overlap — each story is posted once.

Keywords apply to news only — never to events, weather, traffic or tides. They also need a page id, an access token and a Facebook machine model to be filled in above. Set Facebook Min Relevance to 0 and track 1 is off while the keywords keep working; leave Facebook keywords empty and only the relevance decides. Posting happens once an hour, so a story typically appears within the hour rather than instantly.

Be sparing with the keywords: a word as common as your own town name puts nearly every local story on the page.

The image template

Instead of generating a fresh AI picture for every post, you can give the station one fixed background. RADIOButler loads it, darkens the lower half and writes the headline of the story onto it in white, with the station name above in orange. The body of the post stays as it is — the image carries the headline, the text carries the story.

The template applies to both tracks above — relevance posts and keyword posts look the same in the timeline, which is rather the point.

Sum compressor (loudness processing on the final mix)

A dynamics compressor evens out volume so the station sounds consistent and "loud" like commercial radio. These are standard audio-engineering parameters.

News & weather (station defaults)

These defaults apply when a program doesn't specify its own news settings.

How a bed's timing works (News / Weather / Opener beds)

Every bed uses the same three values to control how the voice sits on the background music. Important: the Cue-in is removed first, and Start next is then measured from where the Cue-in ends — i.e. from the first moment of the bed that listeners actually hear.

Opener (hourly intro)

The opener is the spoken intro that starts each hour. It blends into the first song of the hour exactly like a moderation (see “How a moderation blends two songs together” above): the first song's instrumental intro runs quietly under the end of the opener, and a music bed fills any gap.

Local news

Weather

The forecast is prepared at about 35 minutes past the hour and goes on air in the hour that follows. It is not a data dump read aloud: live measurements are turned into a short spoken forecast by the AI, translated into your station's language, spoken by your weather presenter, and laid over a bed.

The one thing that makes a forecast credible

A listener is looking out of the window while you speak. If you tell them it is sunny and it has just clouded over, they stop believing you — so the forecast is built around two facts, not one: what it is doing now, and what it is about to do in the next few hours.

How it is built

Where the data comes from

The hand-over from the news

If the Radio Program has “Use news greeting in weather” switched on, the weather presenter does not simply start talking — they take over from the news presenter by name: “Thanks, Thore. The weather in Helgoland …”

Three of these hand-overs are written and recorded once per combination of news presenter, weather presenter, language and place, and then re-used and varied. They cost nothing per broadcast, and they are what makes two AI voices sound like two people in one studio.

The fields

Upload Weather to an FTP server (optional)

If you also publish the weather audio to your own server: Active switch plus Host, UserName, Password, RootPath (target folder) and Port.

Traffic

The traffic report is produced fresh, on demand: when the news are over, the station asks for one and waits (at most two minutes) until it is ready. It is written by the AI from live data and read by your traffic presenter over a bed.

What decides whether something gets reported

This is the part that changed most, and it is worth understanding — it is the difference between a station people believe and one they switch off.

Two live sources are queried around your centre point:

• Incidents — what is reported: roadworks, closures, accidents.
• Flow — what is measured: how fast the traffic on each stretch is actually moving, and how much time that costs compared to a free road.

The flow leads, the incidents explain. A stretch is only reported when it is measurably jammed. The nearest incident then supplies the reason. If none is found, the jam is reported without a reason — no cause is ever invented.

The filters, in order

Your roads first

Not every jam matters equally to your listeners. The commuter routes of your area do — and if something is happening on one of them, it should be the first thing they hear, even when a bigger jam sits somewhere they never drive.

That is what Default roads is for. List the roads that matter (A 27 | B 71 | Hauptstrasse). Anything found on one of them is named first.

When there is not enough to say

Some mornings the roads around you are simply clear. Rather than let the bulletin fall short, the search then looks further out.

All the filters still apply in the wider ring, so nothing gets in that would not have been broadcast anyway — you simply get to hear about the motorway thirty kilometres out instead of half a bulletin of silence. Leave Radius max at 0 (or below the normal radius) and nothing widens.

From data to audio

The AI is given the items as data, together with strict rules: never read a field name out loud, never invent a cause, and only mention extra travel time when a delay was actually measured. It must not fill a gap by saying that the roads are clear — if there is nothing to say about a point, it says nothing.

Found nothing at all? Then your No traffic found prompt is used instead, and the station says so.

The fields

These are the station's defaults. A Radio Program can override them for its own hour — prompt, radius, presenter, how many reports.

Spoken moderations

This is the station's default AI model for everything the presenter says around the music: the short links before and after a song ("That was …", "Next up is …"), the longer music expert story about a song or an artist, and the moderation wrapped around an urgent message. The field is called Music expert AI Model for historical reasons — it is not limited to the music expert segment any more.

Feature length limits

Advertising defaults

Activation & saving

Presenters (Anchors / Moderators)

A presenter is the on-air personality that reads your content. Each presenter is bound to one text-to-speech Voice and carries its own name, character, greetings and audio processing, so different shows can sound like different people. A presenter comes together in three stages — what they say, how they sound, and a final polish — before it reaches the air.

Audio processing (EQ / Compressor / Normalizer)

This is the “final polish” stage. After the voice has spoken the text, each of these is applied to this presenter's voice audio (only the ones you switch on), so every presenter sits well in the mix and sounds consistent:

Voices

Voices lists every text-to-speech voice available to your account; clicking one opens its editor (voice.aspx). A voice is the raw "vocal cords" — a presenter then uses it to actually speak. Voices run on ElevenLabs, and a handful of ElevenLabs dials shape how each voice sounds (the same text can sound calm and steady or lively and expressive depending on these). (Google voices are no longer used.)

AI Models (machine models)

An AI model is a registered connection to a Large Language Model — a GPT, Gemini or DeepSeek model — that writes the words: news scripts, weather, presenter greetings and outros, traffic, music-expert talk, even replies to listener calls. You set one up once here, give it a name, and then pick that name on every screen that asks for an "AI model". Crucially, a model only produces text — a Voice later turns that text into audio.

Each entry combines three things: a base model (which underlying model/version, picked from the dropdown — this drives capability and the per-token price), your own API key for that provider, and a system message that frames every request. The same base model can exist several times with different keys, names or system messages — for example a "factual news" entry and a "playful banter" entry built on the same GPT model.

Radio Player

The Radio Player is a ready-made web player that RadioButler hosts for you. Visitors press play to hear your live stream and see what's on right now — the current song's cover art, your station name, the current and upcoming shows (each with its presenters' photos), and a song-request form so listeners can wish for a track. You don't build it: you pick a station, style it here, then copy a one-line snippet into your own website. Everything on this page is about look and wording — there is no audio processing here. A live example is radiohelgoland.de.

Two outputs come back to you at the bottom: the Radio Player URL (a direct link to the hosted player you can share as-is) and the Example HTML snippet (an <iframe> you paste into your site to embed the player inline). Style changes you save here apply to both immediately.

The Music Wish form

Built into the player is a Music Wish (Musikwunsch) form: a listener can ask for a specific track and add a short greeting to friends or family. The wish is queued automatically and, when it fits the format, is usually played within a few minutes — no manual step needed. Greetings are meant to stay positive and friendly. After the decision, the listener is e-mailed the outcome; the subject and the "yes"/"no" wording are set on the Radio station page (Music Wish responses).

How to

Practical how-tos and the technical detail behind certain features. More topics will be added here over time.

Music Request — how a song wish reaches the air

What happens after a listener submits a wish on the player: the API the player calls, the automatic review of the greeting, the playout, and the e-mail the listener receives.

The API behind the form

The Music Wish form is pure client-side JavaScript that talks to a small set of public HTTP handlers (.ashx) on the RadioButler server (e.g. https://www.radiobutler.com/). All of them are simple GET requests and send the CORS header Access-Control-Allow-Origin: *, which is what lets the player work when it is embedded on your own website (a different domain). Each station is identified by its radio id (a GUID), which is baked into the player. The flow has three steps — two look-ups while the listener types, and one submit:

How the song search works (in detail)

While the listener types, the player runs two autocomplete look-ups against the handlers above — search-artists.ashx as they type an artist, and search-songs.ashx as they type a title. Each returns at most 10 suggestions. The whole point of the search is that a listener can only ever pick a track your station can actually play right now: it applies the same availability, ban-list and (optionally) MusicBox rules that the playout itself uses. So a wish is never “lost” because it was impossible to fulfil — impossible tracks simply never appear.

The filter funnel. Every candidate passes the same chain of filters before it can appear as a suggestion. Each step only ever removes tracks — so the list gets shorter and more relevant, never longer:

How results are ordered

The survivors are not returned in database order — they are ranked so the most useful suggestions come first, then the list is cut to ten:

When a song counts as “in your MusicBox”

When “MusicBox Songs Only” is on, the search (and the wish itself) is limited to the tracks your station's MusicBoxes can draw on. A song is “in your MusicBox” when its own genre tags lead — through the genre pools that build your MusicBoxes — to a MusicBox that belongs to your station:

Rules the server enforces

The verification & decision process — is a wish played?

Submitting a wish does not guarantee it airs. Every wish passes through four stages, and can be stopped at the first two:

Embed the Music Wish form on your own website

You can put the wish form straight onto your station's website. It talks to the public RadioButler API directly from the visitor's browser — every endpoint sends Access-Control-Allow-Origin: *, so there is no backend, no API key and no CORS proxy to set up. You only need your station's radio id.

The integration is the same three calls described under How the song search works — two autocomplete look-ups and one submit. Quick recap:

Option A — drop it into your page (recommended)

Because the API is browser-friendly, the whole feature is just HTML plus a little JavaScript. The snippet below searches as the listener types and sends the wish. A complete, styled page with a proper artist + song autocomplete dropdown, greeting counter and status messages is provided separately as musicwish-widget-example.html — set its RADIO_ID and open it in a browser.

<!-- Minimal drop-in: type a song, send a wish. (The full example file adds
     a proper artist+song autocomplete dropdown.) -->
<input id="song" placeholder="Wish a song… (type >=2 chars)">
<button id="send">Send</button>

<script>
const BASE = "https://www.radiobutler.com/";   // trailing slash
const RADIO = "YOUR-RADIO-ID";                  // your station GUID
let songId = null;

// While typing: search and remember the first match (demo — use a dropdown in real life)
document.getElementById("song").addEventListener("input", async e => {
  const q = e.target.value.trim();
  songId = null;
  if (q.length < 2) return;
  const r = await fetch(BASE + "search-songs.ashx?radioId=" + encodeURIComponent(RADIO)
                             + "&song=" + encodeURIComponent(q));
  const list = await r.json();          // [{ Id, SongName, ArtistName, ... }]
  if (list.length) songId = list[0].Id; // pick the first suggestion
});

// On send: post the wish. "wishedby" convention is "<first name> aus <town>".
document.getElementById("send").addEventListener("click", async () => {
  if (!songId) return alert("Type a song first.");
  const u = BASE + "wishasong.ashx?radioid=" + encodeURIComponent(RADIO)
    + "&songid="        + encodeURIComponent(songId)
    + "&wishedby="      + encodeURIComponent("Anna aus Hamburg")
    + "&wishedbyemail=" + encodeURIComponent("anna@example.com")
    + "&greetingtext="  + encodeURIComponent("Hi to all my friends!");
  const r = await fetch(u);
  const d = await r.json();             // { "message": "Ok" } or { "error": "..." }
  alert(d.message === "Ok" ? "Wish sent!" : (d.error || "Could not send."));
});
</script>

Option B — call the API from a backend (Python · Java · C#)

Sometimes you'd rather drive the API from your own server — to test it, to build a custom form that posts to your backend first, or to script wishes. The same GET calls work from any language. Each example searches for a song and then submits a wish.

Python

import requests   # pip install requests

BASE = "https://www.radiobutler.com/"
RADIO_ID = "YOUR-RADIO-ID"

def search_songs(text, artist_id=None):
    params = {"radioId": RADIO_ID, "song": text}
    if artist_id:
        params["artistId"] = artist_id
    r = requests.get(BASE + "search-songs.ashx", params=params, timeout=10)
    return r.json()          # [{ "Id","SongName","ArtistId","ArtistName","Duration" }]

def wish(song_id, wished_by, email="", greeting=""):
    params = {"radioid": RADIO_ID, "songid": song_id,
              "wishedby": wished_by, "wishedbyemail": email, "greetingtext": greeting}
    r = requests.get(BASE + "wishasong.ashx", params=params, timeout=10)
    return r.json()          # { "message": "Ok" }  or  { "error": "..." }

songs = search_songs("viva la vida")
if songs:
    s = songs[0]
    print("Wishing:", s["SongName"], "-", s["ArtistName"])
    print(wish(s["Id"], "Anna aus Hamburg", "anna@example.com", "Hi to all my friends!"))

Java

// Java 11+ (java.net.http). Parsing kept tiny; use Jackson/Gson in production.
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import java.util.regex.*;

public class MusicWish {
    static final String BASE = "https://www.radiobutler.com/";
    static final String RADIO_ID = "YOUR-RADIO-ID";
    static final HttpClient HTTP = HttpClient.newHttpClient();

    static String enc(String s) { return URLEncoder.encode(s, StandardCharsets.UTF_8); }

    static String get(String url) throws Exception {
        HttpRequest req = HttpRequest.newBuilder(URI.create(url)).GET().build();
        return HTTP.send(req, HttpResponse.BodyHandlers.ofString()).body();
    }

    public static void main(String[] args) throws Exception {
        String json = get(BASE + "search-songs.ashx?radioId=" + enc(RADIO_ID)
                               + "&song=" + enc("viva la vida"));
        Matcher m = Pattern.compile("\"Id\":\"([^\"]+)\",\"SongName\":\"([^\"]+)\"").matcher(json);
        if (m.find()) {
            String songId = m.group(1), name = m.group(2);
            System.out.println("Wishing: " + name);
            String res = get(BASE + "wishasong.ashx?radioid=" + enc(RADIO_ID)
                + "&songid="        + enc(songId)
                + "&wishedby="      + enc("Anna aus Hamburg")
                + "&wishedbyemail=" + enc("anna@example.com")
                + "&greetingtext="  + enc("Hi to all my friends!"));
            System.out.println(res);
        }
    }
}

C#

// .NET (HttpClient + System.Text.Json)
using System;
using System.Net;
using System.Net.Http;
using System.Text.Json;
using System.Threading.Tasks;

class MusicWish
{
    const string BASE = "https://www.radiobutler.com/";
    const string RADIO_ID = "YOUR-RADIO-ID";
    static readonly HttpClient http = new HttpClient();
    static string Enc(string s) => WebUtility.UrlEncode(s);

    static async Task Main()
    {
        string json = await http.GetStringAsync(
            $"{BASE}search-songs.ashx?radioId={Enc(RADIO_ID)}&song={Enc("viva la vida")}");

        using var doc = JsonDocument.Parse(json);   // [{ "Id","SongName","ArtistName",... }]
        if (doc.RootElement.GetArrayLength() == 0) return;
        var first = doc.RootElement[0];
        string songId = first.GetProperty("Id").GetString();
        Console.WriteLine("Wishing: " + first.GetProperty("SongName").GetString());

        string res = await http.GetStringAsync(
            $"{BASE}wishasong.ashx?radioid={Enc(RADIO_ID)}&songid={Enc(songId)}" +
            $"&wishedby={Enc("Anna aus Hamburg")}&wishedbyemail={Enc("anna@example.com")}" +
            $"&greetingtext={Enc("Hi to all my friends!")}");
        Console.WriteLine(res);                      // { "message": "Ok" }
    }
}

Scheduler

The Scheduler is the weekly calendar of your station. It shows the seven days across the top and the 24 hours down the side, as a grid. Into each slot you place a Program Schedule (a reusable template), and RadioButler then automatically generates the actual hourly programs from those templates.

Program templates

This screen lists your Program Schedules — the reusable templates that the Scheduler places into the week. From here you create a new template or open an existing one to edit it (which opens the Program Schedule detail page). A template defines the standard "shape" of an hour so you don't rebuild it every day.

Program Schedule (template detail)

This is where a recurring hour is defined in full. It has the same building blocks as a single Radio Program, but the values here are the standard/defaults used every time the template runs, plus the days and hours it applies to. Many fields are therefore prefixed "Standard" or "Default".

Identity & timing

Presenters & AI requests

Standard news / local news / weather / traffic

For each of these four content types the template carries the same set of defaults (identical idea to the station defaults, but specific to this template):

Traffic additionally has Default roads (the roads to name first) and Default max traffics (how many reports the announcement may contain). Weather/traffic use their own Default … AI model and presenter as listed. See Traffic on the Radio station page.

Opener, Outro & extras

The Outro — the hour's closing link

The outro is the last presenter link of the hour. It airs over the intro of the final song; after it, nothing but that song plays until the news — no further moderation, no jingle, no local news. If your ads are set to run before the news, the ad break still airs as usual.

An outro is only produced when an Outro AI model is set. It is charged like an opener (≈ €0.01 plus the text-to-speech cost).

What it says

If you leave Outro AI prompt empty, RadioButler writes the outro itself, in the tone of the presenter's Character:

Writing your own prompt

If you fill in Outro AI prompt, that prompt is used exactly as you wrote it — nothing is appended, and none of the behaviour above is added automatically. To get facts into the text, put a placeholder where you want them. Upper/lower case does not matter:

Radio Program (single hour detail)

A Radio Program is one concrete hour on one concrete date — often generated automatically from a Program Schedule, but fully editable by hand. The fields mirror the template, minus the "Standard/Default" wording, because here they are the real values for this specific hour.

Identity & timing

Presenters & AI requests

News, Local news, Weather, Traffic

Each content type has its own block of fields. They behave exactly like the station/template versions:

Opener, Outro, Music expert & moderation

Within the source/news editing area you may also see small helper buttons such as Title / Changed title (edit the headline), Summerize text (have the AI shorten a text) and Count wishes — these act on the individual item you're editing.

News

The News menu (page newslist.aspx, titled "Actual news") shows the current pool of finished news stories the system has gathered and written. Clicking a story opens it for viewing (newsdetails.aspx) or editing (news.aspx), where you can correct the headline or text before it airs.

Editing a single news item (news.aspx)

Requests

A Request is a saved instruction that turns raw source material into finished content. It says which sources to read, what to look for (keywords/topics), and how the AI should write the result. The Requests menu lists them; clicking one opens the editor (newsrequest.aspx).

How a story is scored

Everything a request does hangs off one number: the relevance of a story. It decides what is aired, in which order, and what is quietly dropped. It is worth knowing how it comes about, because two of the three parts of it are yours to set.

Request type — what the request is for

The type is not decoration: it decides which part of the station comes looking for this request. A request nobody asks for produces nothing.

Events: how far ahead to look

Max age is of no use here. It limits how far back a story may lie — but an event lies in the future, so every event passes that test, including the one in eight months. That is what Event days ahead is for.

Shorten & Combine — several stories, one piece

By default a request produces one item per story: three stories become three separate reads, one after another. That is right for a news bulletin. It is quite wrong for “the three best events this week”, which should sound like one presenter talking, not like a list being read out.

That is what these two stages are for. They are independent — you can use either, both, or neither.

When each stage runs

Writing a combine prompt

Tell it what the piece is, how long it may be, and what must not be lost. For a “what's on” slot:

“Turn these event listings into one coherent radio text of at most 150 words. Give the date, the place and the time for each one. Address the listener personally. Do not use a list — write it as if you were telling a friend what is on this week.”

The fields

Basics

What to include, what to leave out

How the AI writes it

Extras

Sources

A Source is where raw information enters RadioButler: an RSS feed, a web page that is scraped, or an e-mail inbox. The Sources menu lists them; the editor (newssource.aspx) is detailed because it must teach the system how to read each particular feed and how to turn it into clean text. You can also test a source right here. There are several built-in sources (e.g. "News of the world", regional feeds); you can add nearly any source, and the team can build custom ones for a small fee.

Identity & fetching

Reading the feed (RSS/XML tag mapping)

RSS feeds wrap each article's parts in named "tags". These fields tell RadioButler which tag holds which part, so it can extract the right text.

Cleaning the text

AI rewriting (headline / news / feature text)

A source can carry its own AI instructions for three outputs. Each has its own model and prompt.

Select news

This screen lets you hand-pick which available stories go into a program's news block, instead of letting the system choose automatically. You first choose the station (top drop-down); the page then shows the program and a list of available news with checkboxes.

Features

Features are longer, recurring AI-produced segments — stories, "this day in history", business round-ups, and so on. The Features menu (features.aspx) lists them in a table (Title, Status, Radio, Created); clicking one opens the editor (feature.aspx).

Header & AI

Content source

When it runs

Shape & sound

When editing an existing feature, a Quick Access URL and a Productions history (past generated episodes) may also appear below the buttons.

Blocks

A Block is a piece of audio that must appear at a precise, fixed moment — for example a fixed insert tied to the news, a switch to an external live stream, or a station element that always plays at a certain second of the hour. The Blocks menu (block.aspx) lists existing blocks (Name, Type, Language, Radio); clicking one opens the detail editor (blockdetails.aspx). A block is a container: it defines when (type, time, days/hours, validity) and holds one or more BlockItems — the actual audio pieces that play.

Two things decide everything else:

• The block says WHEN. StartTime is the exact second inside the hour, Precision the tolerance around it. When a block is due, the streamer shortens the running song so the block starts on time.
• The items say WHAT. They play one after another, in Order No — a bed, then the content, then an outro. Each item's Probability only decides whether that item is part of this airing at all; it is not a lottery that picks a single winner.

Block (the container)

Schedule overview — what already runs in which hour

Blocks are easy to pile up: three blocks at 20:00 in the 10–11 hour and nothing at all in 11–12. The Schedule overview on the block page makes that visible before you save. It sits right under the day checkboxes and lists all weekdays and all hours for the radio chosen in the Radio dropdown:

• One chip per block and slot. Every block that is ticked for that weekday and hour appears in the cell as mm:ss Name, sorted by start time. Long names are cut off — move the mouse over a chip to see the full title, the block type, the radio and the exact slot.
• Only this radio. The grid shows the blocks whose Radio is the one currently selected in the dropdown. Blocks defined for "All radios" are not shown; switching the dropdown redraws the grid without a page reload.
• Only what is valid today. Blocks whose Valid from / Valid until range does not include today are left out.
• Live preview of the block you edit. The current block is drawn in orange and follows every change to its name, start time, hours, days or radio immediately — no need to save first. Today's column is highlighted.
• Same start time = warning. If two blocks in the same cell share the exact same StartTime, both chips get a red border and the tooltip says so. Move one of them to another second or hour, or give the hour to a different block.

BlockItem (added dynamically with “+ Add BlockItem”)

Each click on + Add BlockItem inserts a fresh item row on the page. A block can hold several items, and they all play, in Order No order. Each item carries its own probability, validity and hour/day rules, so a block can still vary what it contains. Every item row contains:

Additional news blocks — a short bulletin between the hours

The main news sits at the top of the hour. An Additional news block is the short bulletin in between — typically at half past: a bed comes up, the presenter reads a couple of stories with a whoosh between them, the bed fades out, the music comes back. Radio Vaterland, for example, runs one at :28 every hour. How many stories it contains is set once per station, in Count news in additional news on the Radio station page (default 2).

Like an Event block it is produced before it airs — the stories are picked, rewritten for radio, spoken and mixed with the bed into one file. The block itself only says when; the bed comes from its single BlockItem.

Where the stories come from

This is the part that surprises people, so it is worth being precise: you do not choose a Request on the block. The block has no field for it. Instead, RadioButler collects every Request of the station's customer whose type is “Additional news”, throws all their stories into one pool, ranks the pool by relevance, and takes the top two.

So you steer the content purely through the Requests:

• Want a business bulletin at half past? Give that Request the type Additional news — and make sure no other Request of that type exists, or its stories will compete for the same two slots.
• Want two bulletins with different content at different times? That is not what Additional news is for — a station has one additional bulletin. Use Event blocks instead; there the Request is chosen on the item, so any number of differently sourced slots can exist side by side.

How a story is prepared

How to set one up

Event blocks — a bed, an AI text, an outro

An Event block answers a request like: “every Tuesday at 17:20, give me the three most fitting stories of this Request — not read out one by one, but woven into one coherent piece, with a bed underneath and an outro at the end.”

It differs from every other block in one respect: it is produced about 15 minutes before it airs and mixed into a single finished file. That is what makes a bed under the voice possible — an ordinary block only cross-fades between its items and could never hold a bed underneath a spoken piece.

How to set one up

Live stream items — relaying an external source

A BlockItem with File type Stream does not download anything. At the block's time the station connects to the address you gave and relays whatever comes out of it, live — an Icecast or Shoutcast stream, an HLS feed, or simply a file served over http.

Events

An event is something that will happen: a concert on Friday, a guided walk at four, an exhibition that runs all month. RadioButler can turn a calendar into a spoken segment — “Tonight on the island: …” — that airs to the second, every day, with no one touching it.

This page follows one event all the way through: from the line in an XML feed, through the Source and the Request, into an Event block, and out of the speakers. Four pieces have to fit together. If the segment stays silent, one of them is misconfigured — and the table at the end tells you which.

The chain

1. The XML feed

Anything that can produce an RSS 2.0 file can feed events into RadioButler — a scraper you write, an export from a town's calendar, a script that reads a newsletter. One item per event on one day. An exhibition that runs for a week is not one item, it is seven — otherwise it can only ever be announced once.

<item>
  <title>Guided dune walk</title>
  <pubDate>Tue, 15 Jul 2026 09:50:00 +0200</pubDate>   <!-- the event STARTS here -->
  <description>Guided dune walk, 9.50, ferry pier</description>
  <content:encoded>Meet at the ferry pier at 9.50. Two hours across the dune with a
       naturalist, who will show you the orchids and the seal bank. Adults 12 euro,
       children free.</content:encoded>                <!-- the text the AI works from -->
  <link>https://example.com/events/dune-walk</link>
  <guid>dune-walk-0715</guid>
</item>

2. The Source

Create a Source for the feed. Only a few fields matter here, but one of them is the rule from the top of this page, in field form.

3. The Request

The Request is where the choosing happens: which events, how far ahead, and in what words. Set Request type to Event — without that, none of the event logic below applies and the Request behaves like an ordinary news query.

Within the window you allow, events are ranked so that sooner beats later: today first, then tomorrow, then the rest. An event does not get worse for having been announced early — its date is what counts, not its age. Anything already past is dropped outright and never used as filler.

The combine prompt

Every chosen event is handed to the AI in one single call, and the combine prompt tells it what to build from them. This is the difference between a list and a segment. A prompt that works tends to say: write one flowing text, not an item-by-item list; give each event what it is, where, and when; take nothing that is not in the material; write numbers and times as words, because this will be spoken and not read; stay under a word limit; and — this one matters — name the time frame explicitly. Left to itself, an AI handed a thin set of events will invent one, and you get a Tuesday segment that opens with “this weekend”.

4. The Block

The Event block is the slot on air. It is produced about fifteen minutes before it is due: the Request is asked, the AI writes, the presenter speaks, and bed, voice and outro are mixed into one finished file. At the appointed second that file plays. Nothing is decided live.

When nothing airs

The chain fails quietly — that is its worst property. Work down this table in order; the first row is the cause far more often than the rest put together.

Jingles

Jingles are short station idents (sung names, sound logos) inserted automatically between elements. The page lists your jingles (Name, Description, Path, Actions) and has an Add New Jingle form. How often jingles may play is also limited by "Min time between jingles" on the Radio station page.

Beds

A bed is the background music a spoken element runs over — the news, the weather, the traffic report, the hour opener. For a long time a station had exactly one of each, uploaded on the Radio station page, and it was used around the clock. This page lifts that limit: you can hold as many beds as you like per element and decide, per weekday and per hour, which one is used.

The reason it exists is sponsoring. “The weather is brought to you by Autohaus Müller” is a bed with a claim in it — and a sponsor buys hours, not a whole day. Two sponsors, one for the morning and one for the drive home, are two beds on the same station with different hours ticked.

The fields

Which hour to tick

One rule, and it holds for all four kinds of bed: tick the hour in which the listener hears it. You never have to think about when RadioButler produces the element.

That distinction matters because the production runs ahead of the airtime. Weather, news and traffic for the 7 o'clock hour are written and voiced during the second half of the 6 o'clock hour; the opener is built right around the change of hour, sometimes a minute or two before, sometimes a minute or two after. RadioButler resolves the bed against the hour it goes out in every case.

Two consequences worth knowing:

Several beds in the same hour

Nothing breaks and nothing is dropped: the matching beds rotate at random, weighted. For every single element, RadioButler collects the beds of that kind whose day, hour and date window fit and whose file it can find, and draws one of them.

Each element draws for itself, too. Opener, news, weather and traffic of the same hour are decided independently, so different sponsors inside one hour are the normal case rather than a fault.

Week at a glance

Below the list sits a grid of seven days by twenty-four hours for the selected station and bed type — the current week, in the station's local time, with the campaign windows applied. It answers the one question everybody asks after adding a third bed: what actually runs when?

The play log

Every time a bed is used, RadioButler records it: which bed, which station, which hour, and the sponsor name as it stood at that moment (so renaming the bed later does not rewrite last month's paperwork). The list on this page shows a running total and the count for the current month per bed — enough for the conversation with the sponsor, and the basis for an invoice attachment.

Which bed wins

For each element the chain is the same, and the first step that produces something wins:

When a bed doesn't air

Work down the list; in practice it is almost always one of the first three.

Playlist (songs played)

This is the play log: every song the station has played, newest first, with a search box. From here you can also block a song or artist so it never plays again.

Song upload

Adds your own music to the library. You upload a ZIP archive of audio files; RadioButler extracts and catalogues them. Maximum size is 2 GB. Sub-folders inside the ZIP are fine, but do not put ZIP files inside the ZIP (nested archives won't work).

Music Boxes

A Music Box is a rule-based pool of songs. Instead of building fixed playlists, you describe the kind of music you want (genre, popularity, mood, tempo, language, complexity…) and the Music Box automatically selects matching songs. The menu (musicbox.aspx) lists your boxes (Name, Description, Age Groups, Radio); clicking one opens the detail editor (musicboxdetail.aspx).

Basics

Selection rules (relevance, popularity, complexity)

Every song carries three scores from 0 to 100:

• Relevance — how significant the song is in the context of music history (its lasting importance), independent of how well-known it is.
• Popularity — how popular the song actually became (in parts of the world).
• Complexity — how musically complex/demanding the song is.

For each score you set a minimum (and, for popularity/complexity, a maximum) that a song must meet to enter the box. A minimum of 0 means "no minimum"; a maximum of 100 means "no maximum".

Tempo & language mix

Character lists

Using the + / − buttons you build lists that further shape the box:

MusicBox Analysis

This report shows how many songs each Music Box actually yields as its rules get progressively relaxed — so you can see whether a box is too strict (too few songs) or too loose. Pick a station first; if none is chosen you'll see "Please select a radio to see its MusicBoxes."

Songs in a box (musicboxsongs.aspx)

Lists the individual Artist / Song entries a box currently contains, each with Block song / Block artist controls and a link to the banned list.

Banned songs & artists

The list of everything you've blocked. It has two tables — banned songs and banned artists — and lets you lift a ban.

If nothing is blocked you'll see "No banned songs found." / "No banned artists found."

Streaming

This is where the finished live audio is sent out to one or more streaming providers (servers that listeners or platforms connect to, such as Icecast or a DAB+ feed). The menu (streaming.aspx, "Streaming Providers") lists configured outputs (Active, Name, URL, Radio, Type); clicking one opens the detail editor.

Podcasts

RadioButler can also produce podcast episodes automatically from your news/requests. The menu lists your podcasts; clicking one opens its editor.

eMail accounts

An e-mail account lets RadioButler receive information by e-mail and turn it into on-air content — for example breaking-news alerts or listener submissions sent to a dedicated mailbox. The menu lists your accounts; the editor configures one inbox and how incoming mail is processed.

Mailbox connection

Processing incoming mail into content

Calls

Incoming calls lists recent listener phone-ins handled by ElevenLabs AI voice agents. Click a date to see a summary and full transcript of the call. You review them here and decide which may be broadcast. (Whether calls are auto-checked first is set on the Radio station page.)

If there are none you'll see "No calls".

Campaigns (advertising)

Advertising is organised as Campaigns, each containing one or more Spots (the individual adverts). A campaign defines when and how often its spots run; the station's Ad position / Max spots settings decide where in the hour they land. The menu lists campaigns; clicking one opens the campaign editor.

Campaign editor (campaign.aspx)

Spot editor (spot.aspx)

Account & balance

Your Account page shows your prepaid credit and the history of what you've spent and topped up. RadioButler is pay-as-you-go: each produced item is deducted from this balance.

Customer profile

Your own account/company details — the billing contact behind the login. Reached from account-related links.

Admin & test tools

Administrator accounts see a few extra items used for setup and troubleshooting. Normal users can ignore this chapter.

Background programs (overview only)

RadioButler's website is the control panel; the actual work is done by a large set of small background programs running on the server. You never start or operate these directly — the switches and fields on the website tell them what to do. They are listed here only so you understand what a button on a page actually sets in motion. (Per your request, these are mentioned, not individually documented.)

Music Archive — overview

The RadioButler Music Archive is a separate web application (titled "RadioButler music archive") used to curate the central music library: the artists, the songs and all the metadata that the main RadioButler uses to choose music. It is where songs get their genres, moods, energy and other tags — exactly the properties the Music Boxes later filter on. You log in with your account; some actions (e.g. seeing every radio's genres) are reserved for administrators.

Search (artists & songs)

The Archive's home page is a search over the whole library. You can search by artist and/or song title, optionally including file matches, then act on the results.

Genres & Sub-Genres

This is the most important screen in the Archive. RadioButler organises music on two levels, and this page manages both and the link between them.

The connection: a Genre is essentially a bundle of Sub-Genres (stored as "GenreSpotifyGenre" links). When a Music Box asks for a Genre, RadioButler expands it to all its mapped Sub-Genres, and from those to the songs carrying those Sub-Genre tags. Mapping the right Sub-Genres into a Genre is therefore what decides which songs a Genre — and any Music Box using it — can play.

Top of the page — choose / add / edit a Genre

Add Sub-Genre

Creates a new Sub-Genre. Besides its name, a Sub-Genre can carry a seasonal window — outside that date range songs of this Sub-Genre are not played (this is what powers, e.g., Christmas music only appearing in December; it matches the seasonal rule the song selector applies).

Sub-Genres list & mapping

All Sub-Genres are listed as checkboxes. This is where you connect Sub-Genres to the Genre chosen at the top.

Songs in a Sub-Genre / rename / delete / combine

Clicking a Sub-Genre opens its song list, where you can also rename or delete it. A separate "Combine" screen lets you merge Sub-Genres.

Song details

The full record of one song. Many of these fields are the very properties Music Boxes filter on, so accurate tagging here directly improves music selection. The page also shows play history, recommendations and chart positions.

Artist details

The record of one artist: their information, their songs, and "anecdotes" the presenter can tell on air.

Legal / Impressum

The legal notice (Impressum), terms & conditions and privacy information. Operator:

Screens and fields reflect the current build; minor wording may differ as the product evolves.