StationCast

A small, self-contained internet radio server in Go. Drop audio files into a directory and they're broadcast live to every listener, Icecast/SHOUTcast style, with a simple admin and a public listener UI

• Filesystem-first library: drop mp3, wav, flac, ogg, oga, m4a, or aac files in and they appear live via fsnotify; rename, move or delete on disk and the library follows
• True broadcast: every listener receives identical bytes, gapless across track boundaries
• Stream in any format a client supports: direct MP3 with ICY, PLS, M3U, and HLS - see Listening
• Audio chain controls for consistent perceived volume: ReplayGain, EBU R128 loudness normalization, and a final dB boost - see Environment variables
• Live metadata to every client: ID3 title / artist / album propagated via ICY StreamTitle, /now-playing JSON, SSE, and navigator.mediaSession
• Album art with iTunes fallback: iTunes Search API preferred per (artist, album), embedded ID3 art as fallback, placeholder otherwise. Cached on disk
• Web admin: shuffle / sequential / loop modes, manual queue with drag-to-reorder, upload / rename / delete, live now-playing and listener count
• Public player: live now-playing over SSE, one-click copy of every stream URL, auto-picks HLS on iOS Safari
• Security: optional reCAPTCHA v3 on the login form, STATIONCAST_MAX_LISTENERS hard cap on /stream connections
• Container-ready: multi-arch (amd64/arm64) image with PUID/PGID, only ffmpeg as a runtime dep
• Resilient broadcast: slow listeners dropped before they back up the encoder; pause injects silence so listeners stay connected

docker run -d --name stationcast --restart unless-stopped \
  -p 8000:8000 \
  -v $(pwd)/music:/music \
  -v $(pwd)/data:/data \
  -e STATIONCAST_ADMIN_PASSWORD=changeme \
  ghcr.io/rursache/stationcast:latest

Drop audio files into ./music/, open http://localhost:8000/, sign in to /admin/login with the password above

services:
  stationcast:
    image: ghcr.io/rursache/stationcast:latest
    restart: unless-stopped
    ports:
      - "8000:8000"
    volumes:
      - ./music:/music
      - ./data:/data
    environment:
      STATIONCAST_ADMIN_PASSWORD: changeme

A ready-to-edit docker-compose.yml is in the repo

Requires Go 1.25+ and ffmpeg in PATH

go build -o ./bin/stationcast ./cmd/stationcast
STATIONCAST_ADMIN_PASSWORD=changeme \
STATIONCAST_MUSIC_DIR=./music \
STATIONCAST_DATA_DIR=./data \
./bin/stationcast

filesystem (watched)
        │
        ▼
scheduler ── shuffle / sequential / loop, manual queue
        │
        ▼
ffmpeg per-track decoder  ──► PCM s16le 44.1k stereo
        │
        ▼
realtime pacer (176_400 B/s token bucket)
        │
        ▼
single long-lived ffmpeg PCM ──► MP3 encoder (gapless across tracks)
        │
        ▼
broadcast hub (ring fan-out, slow-listener drop)
        │
        ├── /stream     direct MP3 + ICY metadata
        └── ffmpeg HLS subprocess ──► /hls.m3u8 + rolling TS segments

• The filesystem is the source of truth, SQLite is just a cache index
• fsnotify picks up file add / remove / rename in real time
• The encoder runs continuously, decoder swaps happen mid-pipe, output is gapless
• Slow listeners are dropped before they back up the broadcast, keeping latency bounded
• Pause means injecting silence PCM, listeners stay connected
• iTunes Search API is consulted once per (artist, album) for missing art and the result is cached on disk

The output is a single 128 kbps MP3 at 44.1 kHz stereo regardless of input format, so every listener receives identical bytes (true broadcast)

The public web UI at / auto-picks HLS on iOS Safari and the direct MP3 stream elsewhere, so for browser listeners just point them at the root

Everything in STATIONCAST_DATA_DIR:

• stationcast.db SQLite index of tracks, queue, history, settings
• art/<id>.jpg extracted or downloaded album art
• hls/playlist.m3u8 and hls/seg-*.ts rolling HLS segments

Safe to delete: HLS segments and the SQLite file (it will rebuild from the music directory). Album art is rebuilt on next play if embedded, or re-fetched on next library scan if from iTunes

MIT