Spaces:
Running
Running
| title: Cadence | |
| sdk: static | |
| app_port: 7860 | |
| pinned: false | |
| app_build_command: npm run build | |
| # 🎧 Cadence — YouTube music dashboard | |
| **Three ways to run it:** | |
| | | What | Needs | | |
| |---|---|---| | |
| | **`cadence-dashboard.html`** | The whole dashboard in **one file** — double-click it, host it anywhere, no install | nothing (demo mode) | | |
| | **This project** | The same dashboard wired to a real backend: YouTube Music search, radio, audio streaming | Python 3 (`./run.sh`) | | |
| | **`cadence-android/`** | The same dashboard as an **installable Android app** (PWA): home-screen icon, full-screen, offline | any https static host | | |
| The single file starts in **demo mode** (built-in catalog, simulated playback, every panel and | |
| interaction live) and can be pointed at the backend from **⚙ Settings** for real search and audio. | |
| To rebuild it after editing the dashboard: `python3 standalone/build_standalone.py`. | |
| --- | |
| # Backend version | |
| Search any song by name, stream it, and let the engine keep the music going with artist | |
| radios and similar-song suggestions — wrapped in a browser dashboard with live playback, | |
| suggestion and cache telemetry. | |
| No API key needed: search/radio/artist/genre data comes from YouTube Music's public data | |
| (via `ytmusicapi`), and the audio is pulled with `yt-dlp` and served by this server so the | |
| browser can play, seek and buffer it like a normal audio file. | |
| ``` | |
| ┌────────────────────────────────────────────────────────────────────────────┐ | |
| │ Cadence · dashboard [ search songs, artists, albums… ] CH Queue │ | |
| ├───────────┬───────────────────────────────────────────────┬────────────────┤ | |
| │ Overview │ ▢ now playing ▢ queue ▢ buffered ▢ radio │ Up next │ | |
| │ Search │ ┌──────────────────┐ ┌─────────────────────┐ │ (queue rail) │ | |
| │ Trending │ │ Now playing │ │ Suggestion feed │ │ track 3 of 42 │ | |
| │ Genres │ │ art + controls │ │ + reason labels │ │ ... │ | |
| │ Recent │ └──────────────────┘ └─────────────────────┘ │ │ | |
| │ ─────── │ ┌──────────────────┐ ┌─────────────────────┐ │ │ | |
| │ Engine │ │ Trending in CH │ │ Trending artists │ │ │ | |
| │ cache … │ └──────────────────┘ └─────────────────────┘ │ │ | |
| ├───────────┴───────────────────────────────────────────────┴────────────────┤ | |
| │ now playing · transport · seek · volume │ | |
| └────────────────────────────────────────────────────────────────────────────┘ | |
| ``` | |
| ## Run it | |
| ```bash | |
| ./run.sh # installs deps if needed → http://localhost:8000 | |
| # or | |
| pip install -r requirements.txt | |
| PORT=8000 python3 app.py | |
| ``` | |
| Then open **http://localhost:8000** (dashboard) — the older single-column player is kept at | |
| **/classic**. | |
| ## Dashboard views | |
| | View | What you get | | |
| |---|---| | |
| | **Overview** | Live tiles (now playing, queue depth, *buffered ahead*, radio engine), a now-playing hero with one-click *Play similar* / *Artist radio*, the **suggestion feed** with a reason per track ("Up next", "Similar to X", "More from X"), trending tracks + artists, and recently played | | |
| | **Search** | Any song / artist / album by name, with live suggestions in the search box; artists render as cards, songs as a playable list | | |
| | **Trending** | YouTube Music charts for 69 regions (defaults to 🇨🇭 Switzerland) — charting tracks plus trending artists with rank and up/down trend | | |
| | **Genres & moods** | 38 tiles (moods + genres) → curated playlists → playable track lists, all browsable without typing anything | | |
| | **Artist** | Top songs, monthly listeners, "Fans also like" similar artists, albums & singles | | |
| | **Album / playlist** | Full track lists with play-all and per-track *similar songs* | | |
| | **Recently played** | Local listening history (stored in your browser) | | |
| | **Queue rail** | The full upcoming queue, click any row to jump; collapses via the Queue button | | |
| | **Engine panel** | Server telemetry: cache size vs. 3 GB cap, tracks cached, downloads, average fetch time, in-flight downloads, uptime | | |
| Everything is hash-routed (`#/artist/…`, `#/playlist/…`, `#/genre/…`), so views are | |
| shareable and the browser back button works. | |
| ## How the "keep playing" engine works | |
| * Play any track → the server downloads the audio once into a local cache and serves it | |
| with HTTP Range support (seeking/buffering/replays are instant). | |
| * While you listen, the next track is **prefetched** — the "Buffered ahead" tile polls | |
| `/api/ready/<id>` and flips to *Ready ✓* when it's on disk. | |
| * When the queue runs low, radio suggestions for the current track are appended | |
| automatically (the "Radio" badge appears in the player bar), so playback never dead-ends. | |
| * ✨ on any row = "play similar songs" → seeds a station from that track. | |
| ## Keyboard | |
| `/` search · `space` play/pause · `n` / `p` next/prev · `←` `→` skip 10 s · `s` shuffle · | |
| `r` repeat (off/queue/track) · `m` mute · `q` toggle queue rail. OS media keys work too. | |
| ## API | |
| | Endpoint | Purpose | | |
| |---|---| | |
| | `GET /api/search?q=&limit=` | songs + artists for a query | | |
| | `GET /api/suggest?q=` | search-box autocomplete | | |
| | `GET /api/radio?videoId=&limit=` | "similar songs" / up-next radio for a track | | |
| | `GET /api/artist?id=\|name=` | top songs, albums, similar artists, monthly listeners | | |
| | `GET /api/artist/radio?id=` | continuous artist station | | |
| | `GET /api/trending?country=CH` | regional chart tracks + trending artists + region list | | |
| | `GET /api/genres` · `GET /api/genre?params=` · `GET /api/playlist?id=` | browse tree and playlists | | |
| | `GET /api/album?id=` | album track list | | |
| | `GET /api/stream/<videoId>` | cached audio with Range support (the `<audio>` source) | | |
| | `POST /api/prefetch/<videoId>` · `GET /api/ready/<videoId>` | warm the cache / check if a track is buffered | | |
| | `GET /api/stats` | engine telemetry for the sidebar panel | | |
| | `GET /healthz` | health probe (`{"status":"ok"}`) for Render/Fly/Railway | | |
| | `GET /manifest.webmanifest` · `GET /sw.js` · `/static/pwa/icons/*` | installable-PWA assets | | |
| | `GET /api/img?u=` · `GET /api/thumb/<videoId>` | image proxies (allow-listed hosts only) | | |
| ## Deploy it | |
| **No credit card: [DEPLOY-FREE.md](DEPLOY-FREE.md)** — run the backend on your own machine and | |
| put a free open-source https tunnel in front of it (`bash run.sh` + `bash tunnel.sh`, or a single `bash tunnel.sh --with-backend`), or host the app | |
| as static files. Everything Cadence depends on is open source (Flask, gunicorn, yt-dlp, | |
| ytmusicapi, cloudflared); only the hosting was ever proprietary. | |
| **Paid/simple clouds: [DEPLOY.md](DEPLOY.md)** — Render, Railway and Fly are pre-configured | |
| (`render.yaml`, `railway.json`, `fly.toml`). Whichever you pick, the dashboard, the PWA assets | |
| and the API are served from the same https origin, so the installed Android app needs no | |
| backend URL and there is no CORS or mixed-content setup. | |
| The dashboard is server-backed, so it needs the Flask app running (a static host alone can't | |
| stream or search). | |
| **Docker** | |
| ```bash | |
| docker build -t cadence . | |
| docker run -p 8000:8000 -v cadence-data:/data cadence | |
| ``` | |
| **Render / Railway / Fly.io / any PaaS** — push the repo, it detects the `Procfile`: | |
| `gunicorn --bind 0.0.0.0:$PORT --workers 1 --threads 16 --timeout 180 app:app`. | |
| Set `CADENCE_CACHE` to a mounted volume (e.g. `/data`) so the audio cache survives restarts. | |
| One worker is deliberate: the cache, download locks and stats live in-process. | |
| **Reverse proxy** — keep response buffering off for `/api/stream/` (Nginx: `proxy_buffering off;`) | |
| so seeking stays snappy. | |
| ## The standalone single-file dashboard | |
| `cadence-dashboard.html` is generated from these same sources by `standalone/build_standalone.py`: | |
| * CSS, icons, dashboard logic and a demo engine are inlined — **zero external requests**, so it | |
| works from `file://`, a USB stick, GitHub Pages/Netlify/S3, or an e-mail attachment. | |
| * **Demo mode** synthesises a catalog (12 artists, 48 tracks, 32 regions, moods, genres, playlists), | |
| generates artwork as inline SVG, and runs a virtual player so progress, queue growth, radio | |
| suggestions and the telemetry panel all behave exactly like the live app. | |
| * **Server mode** (⚙ Settings → enter a URL) switches every request to the real backend. The | |
| backend sends CORS headers, so the file can be hosted on a different origin. Mixed content | |
| applies: an `https` page needs an `https` backend. | |
| ## Android app (installable PWA) | |
| `standalone/build_standalone.py` also emits `cadence-android/` — the app shell plus | |
| `manifest.webmanifest`, `sw.js` and a full icon set. Host that folder on any https static host | |
| (Netlify Drop, GitHub Pages, nginx…), open it on the phone and tap **Install**. | |
| On phones the dashboard switches to a purpose-built layout (≤640 px): 2×2 tile grid, | |
| full-width search, icon nav strip, compact 104 px player bar with thumb-reachable transport, | |
| and the queue as a full-height sheet. Touch devices also drop the keyboard hints and turn | |
| artist names inside track rows into plain text — Chrome's touch adjustment would otherwise | |
| turn a "play this song" tap into "open this artist". | |
| Install criteria, mixed-content rules and how to get a signed `.apk` are documented in | |
| [`cadence-android/README.md`](cadence-android/README.md). | |
| ## Layout | |
| ``` | |
| cadence/ | |
| ├── app.py # Flask: search, radio, artist, trending, genres, stream, images, stats | |
| ├── templates/dashboard.html # the dashboard shell (nav · panels · rail · player bar) | |
| ├── templates/index.html # the classic single-column UI (/classic) | |
| ├── static/dash.css # dashboard theme (dark, glassy) | |
| ├── static/dash.js # router, views, player, radio growth, telemetry | |
| ├── static/style.css static/app.js # classic UI | |
| ├── standalone/runtime.js # demo engine + backend connector (injected into the single file) | |
| ├── standalone/build_standalone.py # builds cadence-dashboard.html | |
| ├── requirements.txt · run.sh · Dockerfile · Procfile | |
| ``` | |
| ## How search ranks results | |
| `/api/search` runs three YouTube Music searches in parallel (relevance-ordered, filtered songs, | |
| filtered artists) and merges them with de-duplication. Ordering: | |
| 1. **YouTube's own relevance position** leads — it encodes popularity, so the canonical recording | |
| beats karaoke and cover versions ("karma police" → Radiohead, not a band called Karma Police). | |
| 2. **Exact title / artist matches** lift near-ties — `"song 2"` puts Blur's track first. | |
| 3. **Artist queries** are detected automatically (many results by one artist vs. many songs with | |
| that title) and that artist's catalogue is promoted — `"nirvana"`, `"blur"`, `"drake"`. | |
| 4. Results sharing nothing with the query are **dropped**, so a nonsense query returns an honest | |
| "no matches" with suggestions instead of random noise. | |
| Typical latency is 0.5–1.5 s (the three lookups run concurrently, not in sequence). | |
| ## Troubleshooting | |
| **"YouTube refused to serve this audio to the server's IP address"** (HTTP 503, code `youtube_blocked`) | |
| — YouTube rate-limits/blocks media downloads from many **datacenter and cloud IPs** (VPS, CI, some | |
| PaaS egress ranges). The dashboard keeps working (search, charts, genres, suggestions, artist pages); | |
| only the audio bytes are refused. | |
| * Run it on your **own machine / home connection** — this is the normal setup and works. | |
| * On a VPS, route `yt-dlp` through a **residential VPN/proxy** (`HTTPS_PROXY` env var), or use a | |
| local machine as the playback backend. | |
| * The app tells you this explicitly instead of silently skipping tracks, and stops rather than | |
| hammering YouTube with retries. | |
| **`WARNING: No supported JavaScript runtime could be found`** — harmless for audio-only use. Current | |
| `yt-dlp` prefers the `deno` runtime for YouTube's JS challenges; most formats still resolve without | |
| it. If a specific track returns *"Requested format is not available"*, install `deno` and re-run. | |
| **First play is slow, then instant** — by design: the track is downloaded once into the cache | |
| (≈1–2 s), then served locally with Range support. | |
| **Port already in use** — `PORT=8010 ./run.sh`. | |
| ## Notes & limits | |
| * Audio cache: `~/.cache/cadence` locally, `/data` in Docker (max ~3 GB, oldest evicted). | |
| Images cached in `…/img`. | |
| * Only the first play of a track costs a download (~1–2 s); after that it's local. | |
| * Regional trending charts are YouTube *trending videos*, so some titles arrive in | |
| video-style formatting rather than clean song metadata. Genre/mood playlists come from | |
| YouTube Music proper. | |
| * Lyrics are not included — YouTube Music's lyrics endpoint rejects key-less requests. | |
| * Built for personal use: it talks to the same public endpoints a browser does, so be | |
| sensible with volume. | |