Smech Radio Overview
Smech Radio is Smech Labs' sovereign web radio node — a self-hosted Icecast/ICY relay with a modern web player portal and server-side ad insertion (SSAI) for a single royalty-free live broadcast feed. No third-party streaming platform in the signal path.
Domains & Endpoints
| Endpoint | Protocol | Purpose |
|---|---|---|
| radio.smech.xyz | HTTPS | Primary Portal & Web Player — player UI, live now-playing metadata, ad slots |
| radio.smech.xyz/stream | Icecast / ICY over HTTPS | Real-Time Live Stream Endpoint — SSAI pre-roll, then the live broadcast feed |
Sovereign Digital Web Radio & Live Stream2Cast Audio Node — Icecast/ICY protocol, real-time broadcast feed, SSAI / dynamic pre-roll integration via VAST 4.0.
Architecture
Three pieces, one domain:
- Upstream Icecast source — the actual live broadcast (self-hosted on the VPS, or a free-tier Icecast relay provider). Smech Radio never originates audio itself; it relays and instruments an existing mountpoint.
- Relay app (Bun/Node) — terminates client connections at
/stream, strips the upstream's own ICY interleaving, prepends a pre-roll ad, and re-interleaves freshStreamTitlemetadata on its own byte boundaries. Also serves/and/metadata. - Static portal — the player page itself, deployable as-is to GitHub Pages for a CDN-backed mirror.
/stream has to be answered by a process that
can hold an open connection and write bytes as they arrive. See
Deployment for how radio.smech.xyz is split
between the two.
Deployment
Two supported upstream sources, picked via UPSTREAM_ICECAST_URL:
- Free Icecast relay provider — point
UPSTREAM_ICECAST_URLat a hosted free-tier mountpoint. Fastest to stand up, no server to manage for the audio source itself. - Self-hosted Icecast on a cheap low-RAM/low-core VPS — Icecast2 itself is light (fine on a 1 vCPU / 512MB–1GB box); the relay app adds negligible overhead since it streams rather than buffers.
Because GitHub Pages can't proxy /stream, the same VPS that runs
Icecast (or reaches the free relay) also runs the Bun relay app behind Nginx,
and DNS for the apex radio.smech.xyz points at that VPS — Nginx
serves the portal directly and reverse-proxies /stream and
/metadata to the Bun process on localhost. The GitHub Pages copy of
the portal (same public/index.html) stays as a CDN-backed mirror;
its player simply points at the VPS-hosted /stream URL instead of
a relative path.
# On the VPS
git clone https://github.com/Smech-Labs/smech-radio.git
cd smech-radio
bun install
cp .env.example .env # set UPSTREAM_ICECAST_URL, AD_EXCHANGE_VAST_URL, ADSENSE_CLIENT_ID
bun run server/index.tsNginx terminates TLS for radio.smech.xyz and reverse-proxies
/stream + /metadata to 127.0.0.1:8787
(see deploy/nginx.conf.example in the repo).