Skip to content

Redesign the README: banner, player and stream cards, fixed clone URLs - #1

Merged
operatoruplift merged 2 commits into
mainfrom
claude/readme-redesign
Oct 31, 2026
Merged

operatoruplift merged 2 commits into
mainfrom
claude/readme-redesign

Conversation

@operatoruplift

Copy link
Copy Markdown
Owner

What changed

The README was thorough but text and a mermaid diagram only. This rebuilds it in the same house style as the Operator Uplift website, the operatoruplift profile and the Allowance README, and fixes two things that were wrong:

  • Header: banner, three buttons (run your own, stream to X, music licensing), the CI badge, stack badges and the MIT badge, the web player's own tagline, the Add music → Add loops → Set the key → Compose up → Go Live on X loop, and section links.
  • Web player card: three real phone screens: ready with the current track, on air with the visualizer moving, and the designed off-air state after the stream drops.
  • How it works: a Library → Liquidsoap → Icecast → FFmpeg flow card, with the visuals path drawn straight to FFmpeg, three guarantees taken from the code (no dead air, a push that heals itself, closed by default), and an accurate service count that now includes the one-shot data-init. The mermaid diagram is kept, in a collapsible section.
  • What viewers see on X: three stills of the actual stream output, one per starter loop, each with a different starter track in the overlay.
  • Music and licensing: the licensing warning is kept word for word (minus one dash). The table states what ships and what the fetcher adds, matching ATTRIBUTION.md and scripts/fetch-cc-music.sh exactly: three CC0 starter tracks in the repo, then 13 fetched tracks, 7 CC0 and 6 CC BY 4.0 that require credit.
  • Status: CI coverage, the Vercel deployment of main, and the manual Go Live and daily rotation steps on X.
  • Kept: every quickstart command and comment, preview mode, the Go Live note, the acquire profile, the 24-hour note, requirements, the repository layout (now with the files it was missing), the docs table, credits and the license section.

Fixes

  • Clone URL: the quickstart and both clone commands in docs/VPS-SETUP.md used https://github.com/YOURNAME/lofi247.git, which fails when pasted. They now use operatoruplift/lofi247 (the README adds "or your fork"). Separate commit.
  • Visuals credit: the README said the visual loops were generated with Seedance 2.0. The three bundled loops are gradient clips made with the docs/VISUALS.md recipe "before any Seedance clips exist" (commits 1ae2a95 and e983342). The README now says that, and points to the Seedance workflow in docs/VISUALS.md.

All images live in docs/readme/ (five PNGs and three JPEGs, about 1.2 MB).

How the visuals were made

Docker has no daemon in this environment, so the stack itself could not boot. Everything shown is still real output from this repository's code:

  • Stream stills: build_filters was extracted verbatim from engine/streamer/entrypoint.sh and run with run_ffmpeg's encoder flags and the .env.example defaults, reading each starter loop and a starter track served over local HTTP, writing 20 seconds to an FLV file instead of X. Each render produced H.264 1280×720 at 30 fps with AAC 44.1 kHz stereo. The overlay font is Noto Sans JP from Google Fonts, the same Source Han design as the Noto Sans CJK face the streamer image installs.
  • Web player: web/ was served with the three endpoints nginx provides: /config.json as 40-lofi-config.sh writes it from .env.example, /nowplaying.json in the exact shape radio.liq writes, and /radio streaming a starter track in place of Icecast. Headless Chromium played it with no console errors or warnings. For the off-air screen, /radio returned 503, as nginx would with Icecast down.

Checks

  • bash -n on engine/streamer/entrypoint.sh, engine/nginx/40-lofi-config.sh and all five scripts/*.sh: pass.
  • shellcheck -S error engine/streamer/entrypoint.sh scripts/*.sh (ShellCheck 0.11.0, the gate CI uses): pass. A full run reports one info-level note (SC1091 in scripts/vps-setup.sh, sourcing /etc/os-release).
  • node --check web/player.js: pass.
  • docker compose config -q, alone and with docker-compose.ci.yml, using .env.example: pass.
  • Not run here: docker compose up and the CI stack-smoke job (no Docker daemon). The CI workflow's last five runs on main all passed, the latest on 28 July 2026 for ed1c5f1.
  • README check: no broken relative links or anchors, alt text on every image, no em or en dashes. Previewed as GitHub renders it in light and dark.

Worth a look

  • I could not open lofi247-gold.vercel.app from this environment. The repository has no vercel.json, so that deployment has no /radio, /nowplaying.json or /config.json, and the player there can only show its "connecting" state. The README describes it as the repository homepage that Vercel publishes from main, and says the station itself runs on your own server. If the homepage is meant to be a live demo, it needs a stream behind it.

Suggested repository settings

  • Description (currently empty): "Self-hosted 24/7 lofi radio for X: Liquidsoap, Icecast and FFmpeg in Docker, with a browser web player."
  • Topics: lofi, radio, livestream, rtmp, liquidsoap, icecast, ffmpeg, docker-compose, self-hosted
  • Social preview: upload docs/readme/banner.png (2400 × 1200) under Settings → General → Social preview.

Generated by Claude Code

- Add a banner, buttons, CI and stack badges, the player's tagline,
  the setup loop and section links
- Add a three-phone card of the web player (ready, on air, off air),
  a library, Liquidsoap, Icecast, FFmpeg flow card and three stills
  of the X stream rendered with the streamer's own filter graph
- Add a status table and a licensing table that matches
  ATTRIBUTION.md and scripts/fetch-cc-music.sh exactly
- Fix the quickstart clone URL (it pointed at YOURNAME/lofi247)
- Correct the visuals credit: the bundled starter loops are gradient
  clips from the docs/VISUALS.md recipe, not Seedance renders
- Keep every setup step, warning, layout row, doc link and license
  note; the service diagram moves into a details block

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01TZhsuWjATuivuiFYJGpbY5
- Both git clone lines used the YOURNAME placeholder, so the
  bootstrap and launch steps failed when pasted as written

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01TZhsuWjATuivuiFYJGpbY5
@vercel

vercel Bot commented Oct 30, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
lofi247 Ready Ready Preview Oct 30, 2026 8:49pm UTC

Request Review

@operatoruplift
operatoruplift merged commit 92e5569 into main Oct 31, 2026
4 checks passed

This branch was successfully deployed

1 active deployment
Preview — 894363f0 Deployed Oct 30, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants