RyuMusic

A YouTube Music web client that runs entirely on your local computer☺️.

The frontend is SvelteKit with Svelte 5 and Tailwind CSS. The backend is FastAPI wrapping ytmusicapi for metadata and yt-dlp for stream URL resolution. It installs as a PWA, and it's tuned for iOS Add to Home Screen.

Why this exists

YouTube Music's web app is heavy and full of ads. RyuMusic gives you the catalog with a cleaner shell: your own tabs, a real queue, synced lyrics where available, and local storage for likes and playlists. No track is uploaded anywhere. Your likes and playlists live in the browser's IndexedDB.

One thing to know up front: playing music from YouTube requires either an unlocked browser session or a proxy that pipes bytes through FastAPI. RyuMusic tries the direct URL first, then falls back to the proxy automatically. That fallback is what keeps playback working when YouTube rate-limits the direct streams.

Quickstart

# install
cd client
npm install
cd ../server
pip install -r requirements.txt

# dev: both processes
cd ..
powershell -ExecutionPolicy Bypass -File scripts/dev.ps1

Open http://localhost:5173. Vite proxies /api/* to FastAPI on :8000.

Authentication

The YouTube Music API needs the request headers of a logged-in browser session. Anonymous mode covers search and public playlists. A personalised home feed, your liked songs, and your library need auth.

1. Go to http://localhost:5173/setup.
2. Follow the on-screen instructions. Open DevTools on music.youtube.com, find any request in the Network tab, and copy its Request Headers block. Or upload a headers_auth.json produced by ytmusicapi.
3. Save. The backend reinitialises immediately.

The file lives at server/auth/headers_auth.json. It's gitignored and only ever leaves your machine to reach YouTube itself. To remove auth, visit /setup and hit Clear.

Production build

cd client
npm run build        # outputs client/build/

# serve both the API and the SPA from one origin
cd ..
python -m uvicorn server.main:app --host 0.0.0.0 --port 8000

The backend serves /api/* and the built SPA (/, /sw.js, /assets, /icons) from the same origin, so production needs no CORS setup.

Project layout

client/    SvelteKit SPA. Svelte 5 runes, Tailwind v3, @vite-pwa/sveltekit
server/    FastAPI. ytmusicapi singleton, yt-dlp resolver, byte-piping proxy
scripts/   dev runner and icon build script

Checks

# frontend
cd client
npm run check     # svelte-kit sync + svelte-check
npm run lint
npm run build

# backend
cd ../server
python -m py_compile main.py

Notes

• ytmusicapi is pinned to 1.4.0 in server/requirements.txt. Newer releases change response shapes and occasionally break parsers. If you update it, run the checks and exercise search, album, artist, and playlist pages before committing.