Built on the django-react front/ template (React 19 + Vite + React Compiler, same themes, menu and hooks layout).
npm i
cp .env.example .env
npm run dev # http://localhost:1212| Script | What |
|---|---|
npm run dev |
dev server |
npm run build |
typecheck + build dist/ |
npm run preview |
serve the build |
npm run lint |
oxlint |
npm run typecheck |
tsc only |
- Songs:
public/data/songs.csv(title,url;Artist - Titleis split into two lines) + songs you save from YouTube - Search: one box, two sources: My songs (instant) or YouTube (press Enter; pasted links work without a key). Swipe sideways to flip.
- YouTube API: the browser only talks to
/api/search(api/search.ts), so the key is never public. 10 searches/min per IP, results cached for an hour. - Mood playlists = library tabs: name + mood emoji, saved in
localStorage. Manage them in Moods. - Touch
- library: swipe sideways between playlist tabs; hold a song (or tap โฎ) for play next / add to queue / add to playlist / save
- mini player: tap or swipe up to open, sideways to skip
- full player: swipe down to close, sideways to skip, up for the play queue
- sheets: drag down to close
- Keys:
K/5play-pause,6/Nnext,4/Pprev,Shift+Sshuffle,Rrepeat,S//focus search,Escclose the player or go back,Ctrl+Jtheme,`sidebar
| Var | Used by | What |
|---|---|---|
YOUTUBE_API_KEY |
api/search.ts |
YouTube Data API v3 key (server only) |
APP_PY_YT_KEY |
scripts/app.py |
optional, falls back to YOUTUBE_API_KEY |
TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID |
api/visit.ts |
optional, pings you on new visits |
VITE_ENABLE_EXTRA_THEMES |
client | false keeps only light/dark |
Vercel: import the repo, add the env vars above, done. api/ becomes serverless functions, vercel.json rewrites the rest to the SPA.
api/ vercel functions: search.ts (youtube, key stays server side), visit.ts (telegram ping)
public/data/songs.csv the song library
scripts/ python desktop tool for editing songs.csv
src/
โโโ app/ entry: main.tsx, App.tsx (routes), env.d.ts
โโโ pages/ Library (tabs), Moods, Search, Queue, Settings, NotFound
โโโ components/ Layout, PlayerProvider, MiniPlayer, FullPlayer, SongList/SongRow, QueueList,
โ Sheet, DragHandle, SongActions, PlaylistSheet, ConfirmDialog, ErrorBoundary
โโโ shared/ Menu (sidebar / mobile tab bar), ThemeIcons, BackButton
โโโ hooks/
โ โโโ GET/ useGetSongs (csv), useYouTubeSearch (/api/search)
โ โโโ LOCAL/ usePlaylists, useSavedSongs, useLibrary(+Order, +Sort), usePlayer, useProgress,
โ useSwipe, useDragDismiss, useDragReorder, useLongPress, useShortcuts,
โ useTheme, useFullscreen
โโโ lib/ youtube, moods, sources, format, themes, types, playerContext, embed, confirm,
โ trackVisit (one /api/visit ping per session)
โโโ css/
scripts/app.py edits public/data/songs.csv (served at /data/songs.csv in production). Full guide: scripts/README.md.
python -m venv scripts/.venv && source scripts/.venv/bin/activate
pip install -r scripts/requirements.txt
python scripts/app.py- Search YouTube โ select โ Add selected to top
- Drag or Top / Up / Down to reorder, double-click to edit,
Deleteto remove,Ctrl+Sto save - Check embeds finds dead / private / non-embeddable videos
- Titles with commas are quoted (
"Hello, World",url), so no need to strip them
- Fork, branch off
main npm run lint && npm run buildshould pass- Small, focused PRs. Song suggestions welcome too: just edit
songs.csv
Bugs and ideas: issues.