Sonata

A premium Apple Music web client — full custom UI with your real Apple Music library, streaming, search, queue, and playback via MusicKit JS.

🌐 Live app: aidiotic.github.io/sonata (after GitHub Pages deploy)

Quick start

Use online (GitHub Pages)

1. Open aidiotic.github.io/sonata
2. Paste your MusicKit developer token
3. Click Connect & Sign In with Apple
4. Use Sonata — Home, Library, Search, Queue, Settings, ⌘K palette

Run locally

cd web
npm install
npm run dev

Open http://localhost:5173

Optional: copy .env.example → .env and set VITE_MUSICKIT_TOKEN to skip the paste step.

MusicKit developer token

Sonata uses Apple's official MusicKit JS API. You need a JWT developer token from an Apple Developer account with MusicKit enabled.

• Token is stored only in your browser (localStorage)
• Or set VITE_MUSICKIT_TOKEN as a GitHub Actions secret for deployed builds
• Apple docs: Generating developer tokens

This is the standard way third-party Apple Music web apps work (same backend as Apple Music, your custom frontend).

Features

Feature	Shortcut
Command palette	⌘K
Play / Pause	Space
Next / Previous	⌘→ / ⌘←
Toggle queue	Sidebar · Queue
Settings	Sidebar ⚙

Display density

• Minimal ○ — compact sidebar, subtle atmosphere
• Standard ● — balanced layout
• Maximal ✦ — wide sidebar, queue panel, session stats, particles

Project structure

sonata/
├── web/                 Sonata web app (React + Vite + MusicKit JS)
│   ├── src/
│   │   ├── components/  Sidebar, player, queue, settings, atmosphere
│   │   ├── hooks/       useMusicKit — Apple Music backend
│   │   └── lib/         Bridge + theme
│   └── dist/            Production build (GitHub Pages)
├── Sonata/              Legacy macOS app (optional)
└── README.md

Deploy your own

cd web
GITHUB_PAGES=1 npm run build
# Deploy web/dist/ to any static host

For GitHub Pages on username.github.io/sonata/, the build sets base: /sonata/ automatically via GITHUB_PAGES=1.

macOS app (legacy)

The native SwiftUI app in Sonata/ is experimental. Use the web app — auth and playback work reliably in the browser.

License

Personal use. Apple Music content is subject to Apple's Terms of Service.