Add music → Add loops → Set the key → Compose up → Go Live on X
How it works · On X · Licensing · Run it · Docs
Captured on 30 October 2026 from web/ served locally with the same endpoints nginx provides: a starter track stood in for the Icecast stream, and the off-air state was forced by making /radio fail.
LOFI 247 is a self-hosted, 24/7 lofi radio station that live-streams to X (Twitter), with animated ambient visuals, a now-playing overlay and a browser-based web player. Point it at a folder of music and a folder of looping background videos, give it an X stream key, and it runs around the clock on a cheap VPS: Liquidsoap shuffles the playlist, Icecast distributes the audio, FFmpeg composites the video and now-playing text and pushes RTMP to X, and nginx serves a visual player for anyone listening in a browser.
Built by Matt (RVAClassic, Operator Uplift) in July 2026.
| No dead air If music/ is empty or fails, Liquidsoap falls back to the ambient bed in assets/, then to silence, instead of dying. If visuals/ is empty, the streamer generates a procedural gradient-and-grain loop. |
A push that heals itself FFmpeg runs inside an infinite retry loop with a 5-second backoff, and a stalled read or write times out after 15 seconds instead of freezing, so network blips and hiccups on X's side recover on their own. |
Closed by default Icecast is reachable only inside the compose network, the slskd web UI binds to 127.0.0.1, FFmpeg errors are scrubbed of the stream key, and the web player is served with a strict Content Security Policy. |
Four always-on services (icecast, liquidsoap, streamer, web) plus the optional slskd run with restart: unless-stopped, next to a one-shot data-init that hands the shared radio-data volume to Liquidsoap's non-root user. Liquidsoap writes nowplaying.txt for the overlay and nowplaying.json for the web player into that volume on every track change.
Full service diagram
flowchart LR
music[("music/")]
subgraph acquire ["Acquisition (optional, profile: acquire)"]
slskd["slskd<br/>Soulseek client :5030"] --> dl[("downloads/")]
end
dl -- "human curation<br/>scripts/ingest-music.sh" --> music
music --> liq["Liquidsoap<br/>playlist engine"]
liq -- "mp3 stream" --> ice["Icecast<br/>:8000 /radio"]
liq -- "nowplaying.txt + .json" --> data[("radio-data volume")]
vis[("visuals/<br/>ambient loops")] --> ff["FFmpeg streamer<br/>video + overlay + audio"]
ice --> ff
data -- "drawtext overlay" --> ff
ff -- "RTMP h264/aac" --> x(["X Live"])
ice -- "proxied /radio" --> web["nginx web player<br/>:8080"]
data -- "/nowplaying.json" --> web
web --> browser(["Browser listeners"])
Liquidsoap 2.4.5 · Icecast 2.5.0 · FFmpeg on Alpine 3.22 with libx264 and drawtext · nginx 1.30.4 · slskd 0.25.1 (optional) · Docker Compose · vanilla JavaScript web player with Web Audio · GitHub Actions
![]() 00-dusk-drift with Amber Hours |
![]() 01-deep-night with Last Train Home |
![]() 02-warm-sunset with Rain on the Sill |
Rendered on 30 October 2026 with the streamer's own filter graph (build_filters in engine/streamer/entrypoint.sh) and encoder flags at the .env.example defaults, 1280×720 at 30 fps, written to a local FLV file instead of X. The handle is the @yourhandle placeholder until you set OVERLAY_HANDLE.
The now-playing line sits in the lower left and the station bug in the top right, both sized from the canvas height so other resolutions stay readable. The streamer prefers a Noto Sans CJK face, so Japanese, Korean and Chinese artist names render instead of empty boxes.
Warning
Licensing: read this before you go live. Publicly rebroadcasting music on X requires the rights to do so. Streaming tracks you do not have a license for will get you DMCA takedowns and can get your X account suspended. The bundled Soulseek client is included only for acquiring content you already have the rights to distribute. See docs/MUSIC.md for legal sourcing options (label agreements, Creative Commons, royalty-free catalogs, commissioning artists directly).
| In the repo Three starter tracks in music/, amber-hours, rain-on-the-sill and last-train-home: original ambient pieces synthesized for this project and released CC0 1.0. No attribution required. |
One command for morescripts/fetch-cc-music.sh adds a vetted batch of 13 tracks: 7 CC0 (HoliznaCC0, Joel Putman) and 6 CC BY 4.0 (Kevin MacLeod, Ketsa), each checked as real audio, tagged and loudness-normalized. |
Credit what needs it The CC BY tracks require a standing credit where viewers can see it, such as your pinned post or bio. ATTRIBUTION.md lists every track, source and license, with a ready-to-paste credit block. |
Your own music goes through scripts/ingest-music.sh, which normalizes it to -14 LUFS as 320 kbps MP3; tags drive the on-air overlay. The optional slskd client only fills downloads/, which never broadcasts directly: a human curates tracks into music/.
The three starter loops in visuals/ (00-dusk-drift, 01-deep-night, 02-warm-sunset) are 30-second gradient clips in the player's dusk palette, made with the loop recipe in docs/VISUALS.md, which also covers generating scene loops with Seedance 2.0 and normalizing any clip with scripts/prep-visual.sh.
Every push to main and every pull request runs shell syntax checks, ShellCheck, a JavaScript parse check and compose validation, then boots the whole stack with a test tone and a dummy RTMP sink and checks the web player, now-playing metadata, audio through /radio and the RTMP push. |
CI workflow | |
Vercel publishes main to lofi247-gold.vercel.app, the repository homepage. The station itself, with its audio, now-playing data and push to X, runs on your own server with Docker. |
Homepage | |
| Going live is not automatic: once FFmpeg is pushing, you still click Go Live in X Live Studio, and X's 24-hour cap per livestream means rotating the broadcast by hand once a day. | 24/7 on X |
| Prerequisites A VPS with Docker: 2 vCPU and 4 GB RAM comfortably handle 720p30. An X account with X Premium, which RTMP stream keys require. Music you have the rights to broadcast. |
Read first docs/MUSIC.md and ATTRIBUTION.md before anything airs, docs/VPS-SETUP.md for the bootstrap, and docs/X-STREAMING.md for the key. |
What CI proves The stack boots, Liquidsoap writes now-playing, audio flows through /radio and FFmpeg pushes RTMP to a test sink. It never touches X. |
On a VPS (Ubuntu 24.04 recommended; docs/VPS-SETUP.md has the full walkthrough, including the bootstrap script):
git clone https://github.com/operatoruplift/lofi247.git # or your fork
cd lofi247
cp .env.example .env
# Fill in: X_RTMP_URL + X_STREAM_KEY (see docs/X-STREAMING.md),
# ICECAST_SOURCE_PASSWORD, ICECAST_ADMIN_PASSWORD,
# STATION_NAME, OVERLAY_HANDLE
# No X key yet? Leave X_STREAM_KEY at its placeholder to run in preview mode:
# the web player + audio come up and the streamer stays idle (see below).
nano .env
# Add content. Quickest start: fetch a vetted batch of CC / public-domain
# tracks straight onto the box (credits required: see ATTRIBUTION.md):
./scripts/fetch-cc-music.sh
# Or copy your own library over (run these from your local machine).
# --chmod=F644 forces every copied file world-readable: liquidsoap and the
# streamer run as non-root uids, so a track synced from a tight-umask machine
# silently never airs (all services "Up", ambient bed plays, real tracks don't).
# Details: docs/VPS-SETUP.md#6-getting-music-and-visuals-onto-the-box
rsync -av --chmod=F644 ~/my-lofi-tracks/ user@vps:~/lofi247/music/
rsync -av --chmod=F644 ~/my-loops/ user@vps:~/lofi247/visuals/
# Launch
docker compose up -d
# Watch it come up
docker compose logs -f streamer
./scripts/status.shOpen http://your-vps:8080 for the web player.
No X key yet? Leave X_STREAM_KEY at its placeholder (your-x-stream-key) and the streamer stays idle in preview mode: Icecast and the :8080 web player still come up, so you can watch the whole stack work before you have X Premium or a real key. Fill the key in when you're ready to broadcast.
Going live is not automatic once the encoder connects. When FFmpeg is pushing, X only shows the source as receiving: you still have to click Go Live in X Live Studio for anything to reach your timeline. The full click path is in docs/X-STREAMING.md.
To also run the optional Soulseek client:
docker compose --profile acquire up -dNote
"Runs forever" is the VPS side. X caps a single livestream at ~24 h and has no broadcast-rotation API, so keeping the channel visibly live means a ~60-second manual broadcast rotation once a day; see docs/X-STREAMING.md.
Requirements
- A VPS with Docker: 2 vCPU / 4 GB RAM comfortably handles 720p30 (see the sizing guide in docs/VPS-SETUP.md)
- An X account with X Premium (required for RTMP stream keys)
- Music you have the rights to broadcast
- Optional: ambient video loops (the streamer generates a fallback visual if you have none)
Repository layout
| Path | What it is |
|---|---|
docker-compose.yml |
The whole stack: icecast, liquidsoap, streamer, web, slskd (optional), plus the one-shot data-init |
docker-compose.ci.yml |
CI-only override: a dummy RTMP sink for the smoke test |
.env.example |
Every knob, documented: copy to .env and fill in |
engine/liquidsoap/radio.liq |
Playlist logic, fallback chain, now-playing writes |
engine/streamer/ |
Custom FFmpeg container + entrypoint (compositing, overlay, RTMP push, retry loop) |
engine/nginx/default.conf |
Web player vhost: static files, /nowplaying.json, /config.json, /radio proxy |
engine/nginx/40-lofi-config.sh |
Writes the player's branding config from STATION_NAME and OVERLAY_HANDLE at start |
web/ |
Browser player (HTML/CSS/JS, Web Audio visualizer) |
music/ |
Your curated library: what actually broadcasts |
visuals/ |
Looping background videos (see docs/VISUALS.md) |
assets/ |
The emergency ambient bed, kept outside music/ so it never enters the playlist |
downloads/ |
slskd landing zone: never broadcast directly |
scripts/vps-setup.sh |
Idempotent Ubuntu 24.04 bootstrap (Docker, UFW, dirs) |
scripts/status.sh |
One-glance operator status |
scripts/fetch-cc-music.sh |
Fetches the vetted CC / CC0 batch into music/ |
scripts/ingest-music.sh |
Curation step: downloads → music |
scripts/prep-visual.sh |
Normalize/transcode videos for the streamer |
docs/ |
The guides listed below |
| Set it up VPS setup: provider sizing and pricing, Ubuntu 24.04 setup, firewall, deploy, updating Streaming to X: the RTMP URL and stream key, encoder settings, 24/7 broadcast strategy, the Restream fallback |
Fill it Music: sourcing legally, the ingest workflow, library conventions Visuals: generating ambient loops (Seedance 2.0) and prepping them for the streamer Attribution: every vetted track and the credit it needs |
Fix it Troubleshooting: first-run failure modes by symptom, from no audio and tracks not airing to a blank web player and "not live on X" |
Built on the shoulders of excellent open source: Liquidsoap · Icecast · FFmpeg · nginx · slskd
Inspired by every lofi girl studying at 2am, everywhere.
The code in this repo is released under the MIT License, copyright © 2026 operatoruplift. Fork it, run it, modify it; just keep the license and copyright notice.
The MIT License covers this code only. The music and visuals you stream through it are a separate matter and remain your responsibility to license: see the warning above and docs/MUSIC.md.
Code is MIT licensed (see LICENSE). Music carries its own licenses, listed in ATTRIBUTION.md.
Built by Matt Sim, founder of Operator Uplift. More builds at github.com/operatoruplift. Want one built for your product? Book a 15-minute call.


