RadioMaster Server documentation

Install

Every release has two server downloads:

Unpack it anywhere. On Linux, /usr/local/bin is a good home if you'll run it as a service.

Setup

Run the setup once. It asks for:

• the station name shown in the app,
• the username and password the desktop apps and the web portal sign in with (the password needs at least 12 characters),
• the port (9259 unless you choose another),
• whether to use HTTPS, and whether to turn on the web portal and its port (9260).

RadioMaster-Server --setup

Without a terminal (a script, a container, a provisioning tool), give the answers as options. The password can come from the RADIOMASTER_PASSWORD environment variable so it stays out of your shell history:

RADIOMASTER_PASSWORD='a long password' RadioMaster-Server --setup --user studio --name "My Station" --https --portal

Run --setup again at any time to change these answers. Then start the station:

RadioMaster-Server

It prints the address to connect to (and the web portal's, if it's on) and the station log goes to the console. Ctrl+C, or stopping the service, saves everything and stops the encoders.

Options

With --setup the options are saved in server.json; without it they apply to that run only.

Data folder

The server keeps its own data folder, so it never mixes with a desktop RadioMaster on the same machine. By default it's ~/.config/RadioMaster-Server on Linux and %APPDATA%\RadioMaster-Server on Windows; choose another with --data.

Back up this folder to back up the station.

Run as a service

Linux (systemd)

The package includes radiomaster-server.service. It runs the server as its own unprivileged radiomaster account with its data in /var/lib/radiomaster:

sudo useradd --system --create-home --home-dir /var/lib/radiomaster radiomaster
sudo cp RadioMaster-Server /usr/local/bin/
sudo -u radiomaster RadioMaster-Server --data /var/lib/radiomaster --setup
sudo cp radiomaster-server.service /etc/systemd/system/
sudo systemctl enable --now radiomaster-server

journalctl -u radiomaster-server -f shows the station log, and sudo systemctl restart radiomaster-server restarts it. The unit adds the account to the audio group so it can use a sound card.

Windows Server

1. Run RadioMaster-Server.exe --setup once in a console.
2. Start it at boot with Task Scheduler: a new task, trigger At startup, Run whether user is logged on or not, action Start a program with the full path to RadioMaster-Server.exe. Or use a service wrapper such as NSSM:

   nssm install RadioMasterServer "C:\RadioMaster-Server\RadioMaster-Server.exe"
   nssm start RadioMasterServer

3. Run the service under the same account you ran --setup with, or pass --data so both use the same data folder.

Ports and firewall

Allow them through the firewall, for example sudo ufw allow 9259/tcp on Ubuntu, or a new inbound rule in Windows Defender Firewall. To reach the server from outside your network, forward the ports on your router, use a VPN, or put the portal on a Cloudflare Tunnel with nothing forwarded at all. The stream itself goes from the server to your Icecast or Shoutcast server, so listeners never connect to these ports.

HTTPS

Turn HTTPS on with --setup --https (setup also asks), or in the app with File → Server settings… → Use HTTPS (it takes effect when the server restarts). Everything between the apps, browsers and the server is then encrypted. A plain http:// request to the port is answered with a redirect to the same address on https://, and an address typed without https:// in the app still finds the server.

There are three ways to get a certificate:

• Let's Encrypt, looked after by the server: the easiest if you have a domain name and port 80 can reach the server.
• Your own certificate files, for example from certbot or win-acme, with --cert and --key.
• Self-signed: nothing to set up; the apps check it by its fingerprint, but browsers warn about it.

No certificate: self-signed

Without --cert and --key, the server makes a self-signed certificate the first time (tls-cert.pem and tls-key.pem in its data folder) and prints its SHA-256 fingerprint at start-up. The first time an app connects, it shows the fingerprint and asks you to trust it: check it against the one the server printed (it's also in Server settings). The app remembers it for that server and refuses a different certificate later, warning that it changed. Browsers show a warning for a self-signed certificate; use a real certificate to avoid it.

Let's Encrypt, built in

The server can get its own certificate from Let's Encrypt and renew it by itself 30 days before it runs out, so browsers and apps trust it with no warning. You need a domain name (for example studio.example.com) that points at the server, and port 80 of that name must reach the server (forward it on your router), because Let's Encrypt checks the name by fetching a file from http://studio.example.com/.well-known/acme-challenge/….

RadioMaster-Server --setup --acme studio.example.com --acme-email you@example.com

Or in the app: File → Server settings… → Use HTTPS → Get a free certificate from Let's Encrypt, with the domain names (comma-separated) and an optional email. Until the first certificate arrives the server uses its self-signed one; the new certificate is swapped in without a restart, and the settings window shows how it went and when the certificate runs out. Tick staging (or --acme-staging) to try it first: Let's Encrypt limits how often real certificates can be asked for, and staging certificates aren't trusted by browsers.

• On Linux, listening on port 80 needs root, or sudo setcap cap_net_bind_service=+ep /usr/local/bin/RadioMaster-Server once.
• Port 80 also sends browsers on to the https:// portal.
• If another program (IIS, nginx) already uses port 80, have it pass /.well-known/acme-challenge/ on to the server's port and start the server with --acme-http-port 0. Or let that program get the certificate and give the files to the server, below.

Your own certificate files (certbot, win-acme)

With a domain name pointing at the server you can get a free, trusted certificate from Let's Encrypt. Apps and browsers then trust the server like any website.

Linux, with certbot:

sudo certbot certonly --standalone -d studio.example.com
sudo RadioMaster-Server --data /var/lib/radiomaster --setup --https \
  --cert /etc/letsencrypt/live/studio.example.com/fullchain.pem \
  --key /etc/letsencrypt/live/studio.example.com/privkey.pem

The server account must be able to read both files (with the systemd unit, that's the radiomaster user; for example give a group read access to /etc/letsencrypt/live and /etc/letsencrypt/archive). The standalone challenge needs port 80 free for a moment. certbot renews the files by itself, and the server picks up the new certificate within a few minutes, with no restart.

Windows, with win-acme: win-acme (wacs.exe) can request the certificate and save it as PEM files. Choose a manual certificate for your domain, the PEM files store with a folder such as C:\certs, and point the server at them:

RadioMaster-Server.exe --setup --https --cert C:\certs\studio.example.com-chain.pem --key C:\certs\studio.example.com-key.pem

win-acme renews by itself on a schedule, and the server picks up the renewed files within a few minutes, with no restart. The file names depend on your win-acme settings; check them in the folder after the first run.

Web portal

The web portal runs the station from a browser on any computer, tablet or phone. Turn it on with --setup --portal (choose the port with --portal-port, default 9260), or in the app with File → Server settings… → Web portal (after a restart). Open http://<server>:9260, or https:// with HTTPS on, and sign in with the server's username and password.

It works on phones (the sections sit along the bottom of the screen) as well as computers:

• Studio: what's on air with its progress and levels, play / pause / stop / next / previous, the volume, the playlists (double-click a row to play it, ✕ to take it out) and the streams with start and stop.
• Library: search the server's library and add songs to any playlist, at the end or to play next; rescan.
• Carts: the cart wall. Tap a pad to play it, or Edit pads to choose each pad's sound and name.
• Generator: make a playlist from a template, keep the on-air playlist filled, and edit the templates and categories (folders are the server's).
• Adverts: the advert and jingle rules. Switch them on and off, play one now, add and edit them.
• AzuraCast: the station's now playing and listeners, skip, restart, start and stop broadcasting and AutoDJ, switch AzuraCast playlists on and off, and the connection settings. The calls go through the server, with the API key from Settings → AzuraCast.
• Log: recently played and the station log.

A banner says when a newer RadioMaster release is out than the server runs. The portal needs a port of its own; allow it through the firewall like the main port. Its pages refuse to be shown inside other sites.

Cloudflare Tunnel

A Cloudflare Tunnel puts the web portal on the internet with no port forwarding and no certificate to look after: the server connects out to Cloudflare, and Cloudflare serves your address over HTTPS. Install Cloudflare's cloudflared on the server (or put it next to RadioMaster-Server), then either:

• Your own domain: in the Cloudflare dashboard, Zero Trust → Networks → Tunnels → Create a tunnel, add a public hostname (for example studio.example.com) with the service http://localhost:9260, and copy the tunnel's token. Start the server with --tunnel-token <token> (or set CLOUDFLARE_TUNNEL_TOKEN), or paste it in Server settings → Cloudflare Tunnel.
• Just try it: --tunnel with no token gives a random https://….trycloudflare.com address. It changes each time the tunnel starts, and it's printed in the log and shown in Server settings.

CLOUDFLARE_TUNNEL_TOKEN='eyJh…' RadioMaster-Server --tunnel

The server starts cloudflared, starts it again if it stops, and stops it on exit. Switching the tunnel on or off in Server settings takes effect at once. The desktop app can connect through the tunnel address too.

Behind a reverse proxy

You don't need a reverse proxy: the server's own HTTPS is enough. Use one if you already run a web server on 443 and want the portal at a normal address such as https://studio.example.com. A proxy that serves HTTPS itself can talk to the server over plain HTTP. Either:

• Turn the server's HTTPS off and let the proxy do it (the simplest): --setup --no-https, and forward to http://127.0.0.1:9260 (portal) or :9259 (apps). Start the server with --bind 127.0.0.1 if the proxy is on the same machine, so the plain ports aren't reachable from outside.
• Keep it on: plain requests from a proxy that says the browser used HTTPS (X-Forwarded-Proto: https, Forwarded: proto=https, IIS's X-ARR-SSL or Cloudflare's CF-Visitor) are served as they are instead of being sent to https://. You can also forward to https://127.0.0.1:9260 and tell the proxy to accept the server's certificate.

"Too many redirects" (ERR_TOO_MANY_REDIRECTS)? Before 0.2.9, a proxy sending plain http:// to a server with HTTPS on got a redirect to https:// every time, and the browser went round in a loop. Update the server to 0.2.9 or newer, or turn the server's HTTPS off.

nginx

server {
    listen 443 ssl;
    server_name studio.example.com;
    ssl_certificate     /etc/letsencrypt/live/studio.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/studio.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:9260;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
        proxy_buffering off;
        proxy_read_timeout 1h;
    }
}

Keep proxy_buffering off; for the apps' port (9259) so the station's sound reaches the app straight away.

Caddy

Caddy gets and renews the Let's Encrypt certificate by itself:

studio.example.com {
    reverse_proxy 127.0.0.1:9260 {
        flush_interval -1
    }
}

IIS (Windows Server)

1. Install URL Rewrite and Application Request Routing, and in ARR's Server Proxy Settings tick Enable proxy. Set Response buffer threshold to 0 so audio isn't held back.
2. Make a site for studio.example.com with an HTTPS binding and your certificate (win-acme can set this up).
3. Add a Reverse Proxy rule (URL Rewrite → Add Rule → Reverse Proxy) that forwards to 127.0.0.1:9260, with Enable SSL Offloading ticked, and keep Reverse rewrite host in response headers off. IIS then forwards plain http:// and adds X-ARR-SSL, which the server (0.2.9 or newer) understands. You can also turn the server's HTTPS off and start it with --bind 127.0.0.1.

The generated rule in web.config looks like this:

<rewrite>
  <rules>
    <rule name="RadioMaster portal" stopProcessing="true">
      <match url="(.*)" />
      <action type="Rewrite" url="http://127.0.0.1:9260/{R:1}" />
    </rule>
  </rules>
</rewrite>

Connect from the desktop app

From the app:

1. File → Connect to Server…, type the server's address (for example 192.168.1.20:9259 or studio.example.com:9259), the username and the password.
2. RadioMaster asks whether to save your local session as a station profile. If you do, your own playlists and settings come back exactly as they were when you disconnect. If you don't, the server's playlists and settings stay in the app after you disconnect.
3. While connected, a green button with the station's name sits left of the RadioMaster logo (amber while the connection is being restored). Click it for the details or to disconnect; File → Disconnect from Server does the same.

From the login screen: Connect to Remote Server… below the sign-in box connects without a local account, using the server's username and password. Your local session is saved as the profile "Local session before remote sign-in" and comes back when you disconnect, which (like Log out) returns to the login screen. Managing local user accounts isn't available this way.

While connected

• Everything you do happens on the server: playlist edits, play/stop/next, carts, encoders, the scheduler, adverts, the generator and settings.
• Your own playback and encoders stop while you're connected (one station on air at a time) and come back on disconnect.
• Several apps can be connected at once. If two people change the same playlist at the same moment, the server's version wins and the app says so.
• The app plays the server's on-air mix on your own outputs, about half a second behind. Untick Hear the station here in the connection window when you're in the same room as the server's speakers.
• The Mic button sends your microphone to the server, which puts it on air with the station's mic settings. Studio monitor outputs on both machines go quiet while it's on.
• Music files, folders and the library are the server's, so a library folder is typed as the server sees it (for example /srv/music).
• These stay on your computer: the interface language, sound cards, the remote control API, plugins, update checks and ffmpeg. Previews and waveforms in the track editor need the files on your own computer and don't work while connected.

Server settings

While connected, File → Server settings… changes:

• the station name, and whether the server starts playing when it starts,
• the sound output (below),
• Use HTTPS, the certificate's fingerprint and Let's Encrypt (domains, email, staging, and how the last request went), and the Web portal (HTTPS and the portal after a restart),
• the Cloudflare Tunnel: on or off, the token, and the address it's using (at once),
• the server password (you type the current one first).

Sound output

The server can play through its own sound cards (into a desk or an FM transmitter, for example) as well as stream. By default it uses its default sound card. In Server settings, switch Play through the server's sound cards on or off and tick which cards to use; the change takes effect at once and each card shows its status. RadioMaster-Server --list-devices lists the cards.

With no sound card, with it switched off, or with --no-audio, the server runs on a silent clock, so automation and streaming carry on as normal. That's the usual setup on a VPS.

Move a station to the server

1. Close RadioMaster on the desktop.
2. Copy config.json, playlists.json, library.json, cues.json and plays.json from the desktop's data folder into the server's data folder.
3. Copy the music to the server, then fix the music folder paths: connect from the app and update the library folders, generator categories and advert rule folders to where the files are on the server.
4. Start the server, connect, and rescan the library.

Security

• The password is checked with Argon2 and only its hash is stored, in server.json. Sign-ins expire after a day without use, and repeated wrong passwords are slowed down.
• Whoever signs in can do everything the station can, including playlist RUN commands that start programs on the server. Use a strong password and run the server under its own unprivileged account (the systemd unit does).
• On a network you don't trust, or over the internet, turn on HTTPS, or put the server behind an HTTPS reverse proxy or a VPN. Without it the password and everything else go over the network unencrypted.
• The web portal uses the same sign-in, and its pages refuse to be shown inside other sites.

Troubleshooting

Still stuck? Ask on the Support Discord with the server's log, or open an issue.