LunoRX
A desktop music player for YouTube Music. A Rust core handles search, playback, the queue and sync, and the interface only shows what the core can actually do.
Tauri 2 · Rust (edition 2024) · Next.js 16 static export · React 19 · libmpv · macOS first, Windows and Linux supported
Version 1.0.0. It plays real YouTube audio and keeps your playlists on your own machine, with optional sync. Spotify search and playback are not supported. The Windows and Linux installers have not been run on a clean machine, and the macOS app is ad-hoc signed, so macOS asks you to approve it once. The Status table lists what works and what does not.
[!IMPORTANT]
Disclaimer
No affiliation. LunoRX and its contributors are not affiliated with, authorized by, endorsed by, or in any way officially connected with Google LLC, YouTube, YouTube Music, Spotify AB, or any of their subsidiaries or affiliates. The same goes for the lyric services the app can query (LRCLIB, LyricsPlus, Netease Cloud Music, QQ Music, Kugou, Boidu). This is an independent, unofficial, open-source project.
Trademarks. "Google", "YouTube", "YouTube Music", "Spotify" and all related names, marks, emblems and images are registered trademarks of their respective owners. They are used here only for identification and reference and do not imply any association with, or endorsement by, the trademark holders. There is no intention to infringe on these trademarks or to harm their owners.
Third-party services. The app talks to YouTube Music directly and, for lyrics, to several unofficial endpoints. These services have their own terms and may change, restrict or stop working without notice. You are responsible for using the app in a way that complies with the terms that apply to you. Security model and Lyrics describe exactly what is sent where.
Limitation of liability. The software is provided "AS IS", without warranty of any kind, and you use it at your own risk. In no event shall the authors or contributors be liable for any claim, damages or other liability, including any legal consequences, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use of or other dealings in it. You are responsible for any outcome of using this software. The MIT licence covers this repository.
Contents
Screenshots
Full-size originals are in assets/. All four were taken on macOS with real YouTube Music data.
What it is
LunoRX is a desktop-first music player built around one library that can hold tracks from more than one provider. Each playlist entry records which provider it came from. Your data lives on your machine first. An optional backend that you can host yourself syncs playlists between devices, and the app works without it.
Three rules shape the code:
- A capability counts as supported only after someone verified it. Unknown means unsupported. A track is
PLAYING once the player confirms it, not when a Play command is sent.
- The core owns the state. Search, playback, the queue and sync live in Rust. The React UI draws that state and sends commands, and it keeps no second copy of the queue.
- App sign-in (the sync backend) and provider sign-in (YouTube) are separate. Provider credentials stay in the OS key store on this machine.
Features
Listening
- Native audio through libmpv: seek, volume, resume where you left off, stream quality, loudness, PCM format and sample rate.
- Sound shaping: a ten-band equaliser, bass, treble, stereo width, headphone crossfeed, room reverb, a compressor and speed with or without pitch. 51 presets in five groups (everyday, genres, fun such as Nightcore, Slowed + reverb and Vaporwave, 8D and 4D moving sound for headphones, and rooms or devices). Settings > Audio.
- Autoplay radio. When a track ends, the core has already prepared the next related track and starts it. The up-next list is real, you can pick from it, and Previous uses it.
- Play, Shuffle and Save to playlist on every album and artist page. The core queues the remaining tracks as Up next.
- On macOS: the Now Playing widget, media keys, a Playback menu and a Sound menu in the menu bar (presets, moving sound, speed, keep pitch), which stays in step with Settings.
- Offline: keep a playlist on the device. A disk cache with a size limit handles everything else.
Finding music
- Listen Now (history and recommendations) and Explore (mood and genre tiles, then a featured song and rows, the same layout as Listen Now). Search lists YouTube Music songs and YouTube videos together, with live suggestions, and a newer search cancels the one before it.
- Play from a link: paste a
youtube.com, music.youtube.com or youtu.be link into Search and it plays at once.
- Library with liked songs, artists (with profile photos), albums and local playlists.
- Artist and album pages with real profiles, discographies and track lists.
- A command palette on
⌘K / Ctrl+K.
Lyrics
- Time-synced lyrics in a full-window layout, with an active line, gaps for intros and instrumentals, and click to seek.
- Eight sources in an order you set: LyricsPlus, LRCLIB, YouTube Music, Netease, QQ Music, Kugou, Boidu and your own files. Word-by-word timing appears where a source provides it. Where it does not, a labelled "guessed" mode is available.
- A source picker, a timing offset per source, and "Wrong song? Search by title" with a manual bind.
- Lyric Maker: play a song and type or tap along to write a
.lrc file. A calibration pass measures your input delay. Files are plain text in ~/Documents/LunoRX Lyrics/.
Your data
- Local-first playlists with an offline queue and version numbers for optimistic concurrency. When a conflict comes up, you choose to keep yours or the server's, and nothing is overwritten silently.
- Optional LunoRX account and sync: sign in or create an account at launch (or skip it), with a Cloudflare Turnstile check. Background sync, a read-only check of where each playlist stands on the server, and editing a playlist's description.
- Share a playlist: one link per playlist (
https://play.lunorx.xyz/s/<token>), read only, shown on every device. Recreate it to replace the old one, or stop sharing. A shared page has an "Open in LunoRX" button and an embed.
- Self-update: the app checks once at launch for a newer release signed with the project's key, and installs it only when you press Install. Settings > About has a Stable (full releases) or Dev (pre-releases too) channel.
Interface
- A dark glass-and-blur theme with one accent colour, which means "live". Motion follows
prefers-reduced-motion, and transparency follows prefers-reduced-transparency. The target is WCAG 2.2 AA.
- Covers are prefetched. Home and Explore feeds persist, so they draw immediately and refresh behind the rows. Artist photos are cached on disk.
Status
| Area | State |
|---|
| YouTube Music search | Works. Direct, no API key. |
| YouTube audio playback | Works through libmpv on a developer machine. libmpv must be installed. |
| YouTube sign-in | Google session cookies in the OS key store. This is a project-owner exception, described under Security model. It is not approval from the provider. |
| Spotify | Not supported. No search and no playback. The app reports it as unsupported. |
| Lyrics | Five unofficial endpoints, used with the owner's acceptance. Each one can be turned off. See Lyrics. |
| Sync with the backend | Works against a running backend: sign in or create an account, upload, background sync, share links, descriptions. Not production-hardened. Needs LUNORX_BACKEND_URL (default https://api.lunorx.xyz) to answer. |
| Library: albums and songs tabs | Partly sample data, labelled as a demo in the UI. Playlists and likes are real. |
| macOS bundle | Built by the release workflow with libmpv inside. Ad-hoc signed, not notarized. |
| Linux | Runs from source on Arch Linux under Hyprland (Wayland), with playback and MPRIS media controls. Other distributions, X11 and other window managers are targets that have not been run. Installers are not verified. Sign-in needs a Secret Service (GNOME Keyring or KWallet). See Linux notes. |
| Windows | NSIS installer built by the release workflow. Not verified on a real machine. |
| Release signing | macOS apps are ad-hoc signed (no Apple Developer account). Windows installers are unsigned. Update files are signed with the project's minisign key, and the app installs only updates that match it. |
| Licences | This repository is MIT. YouTube access comes from innerlight (MIT, in the sibling innerlight repository). libmpv is LGPL. THIRD_PARTY_NOTICES.md lists every component and licence. |
Install on Linux
No clone, no build. One command installs the released AppImage for your user (no root) and adds LunoRX to your application menu:
curl -fsSL https://raw.githubusercontent.com/LunoRX-RS/desktop/main/scripts/install-linux.sh | sh
Start it from the menu, or run lunorx. The script finds the newest release, checks the download against the release's SHA256SUMS.txt and refuses to install it if it does not match. Read it first if you like: scripts/install-linux.sh.
| You want | Run |
|---|
| Any distribution, no root (default) | curl -fsSL <url> | sh |
| A system package on Debian, Ubuntu and relatives | curl -fsSL <url> | sh -s -- --deb |
| A specific release | curl -fsSL <url> | sh -s -- --version v1.0.0 |
| See what it would do, download nothing | curl -fsSL <url> | sh -s -- --dry-run |
| Remove it again | curl -fsSL <url> | sh -s -- --uninstall |
<url> is the address above. Your library and settings live in ~/.local/share/io.lunorx.desktop and are kept when you uninstall.
Things to know:
- x86_64 only, for now. Other CPUs build from source (see Quick start).
- glibc 2.39 or newer, because the release is built on Ubuntu 24.04. That covers Ubuntu 24.04 and newer, Debian 13, Fedora 40 and newer, Arch, openSUSE Tumbleweed and the like. The script checks and stops with an explanation on older systems (
--force tries anyway). It does not support Alpine (musl).
- Nothing else to install for the AppImage. It carries libmpv and WebKitGTK. The
.deb pulls its dependencies in through apt.
- FUSE. Recent Ubuntu and Fedora no longer ship FUSE 2. The
lunorx launcher notices and unpacks the AppImage on start instead, so it still runs, a little slower to open.
- Sign-in storage needs a running Secret Service (GNOME Keyring or KWallet); see Linux notes.
- Verified so far: the download, checksum and install steps on Arch Linux, and that the AppImage bundles libmpv and WebKitGTK. Not run on other distributions, and the
--deb path has not been run at all.
Quick start
Requirements
| Tool | Used for |
|---|
Rust stable with edition 2024 (cargo, rustfmt, clippy) | The core and the Tauri shell |
| Bun, or Node 22 with npm | The frontend. tauri.conf.json calls bun run dev and bun run build, so Bun has to be on the PATH for tauri dev and tauri build as configured |
| Tauri 2 platform prerequisites | See the Tauri docs for your OS |
| libmpv | Native playback. macOS: brew install mpv. Debian/Ubuntu: libmpv-dev. Arch: mpv |
| A Secret Service (Linux only) | GNOME Keyring or KWallet, to store the sign-in token |
On Debian/Ubuntu the build also needs build-essential pkg-config libssl-dev libdbus-1-dev libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev. On Arch: base-devel webkit2gtk-4.1 libayatana-appindicator librsvg openssl dbus mpv.
Linux notes
- Window. The window keeps the window manager's own title bar, so it moves, tiles and resizes like any other window on GNOME, KDE, Hyprland, Sway and i3, on Wayland and X11. The app draws its own drag area only on macOS.
- Media keys and widgets. The app registers an MPRIS player (
org.mpris.MediaPlayer2.io.lunorx.desktop). Desktop media widgets, playerctl and the media keys your desktop routes to MPRIS players control it. On a bare window manager, run a daemon such as playerctld or bind the keys to playerctl.
- Sign-in storage. YouTube sign-in and the sync token are stored through the Secret Service. GNOME Keyring or KWallet must be running; many tiling window manager setups do not start one, so start
gnome-keyring-daemon from your session.
- Locale. libmpv needs the numeric locale
C. The app sets it for itself, so a UTF-8 system locale such as en_US.UTF-8 is fine.
- Wayland rendering. On Wayland the app sets
WEBKIT_FORCE_VBLANK_TIMER=1 unless you set it yourself. Without it the window stopped repainting on a hybrid Intel/NVIDIA laptop under Hyprland (the page froze while audio kept playing). Set WEBKIT_FORCE_VBLANK_TIMER=0 to opt out.
- Audio output. mpv picks the first output it can open, usually PipeWire, then PulseAudio, then ALSA.
Building, running and testing need no secrets.
Run it
bun install # or: npm ci
bun run tauri dev # starts next dev on :1420, then the native app
The app starts without a backend. Sync actions report an error category until a backend answers at http://127.0.0.1:8080, the default base URL in src-tauri/src/sync/settings.rs.
Build it
bun run build # next build, static export to out/
bun run tauri build # bundles for the current OS
out/ has to exist before any Rust build of the crate, because tauri::generate_context! embeds it (frontendDist: ../out). Without it the Rust build fails.
Develop the interface
bun run tauri dev # the interface inside the native app, with hot reload
The interface talks to the Rust core through Tauri IPC, so run it inside the app. bun run dev alone serves the pages in a browser, but there is no core behind them: every command fails, and the screens show their error states.
Architecture
┌──────────────────────────────────────────────────────────────┐
│ Desktop UI (src/) Next.js static export · React 19 │
│ presentation · navigation · input · login UI │
└───────────────┬──────────────────────────────────────────────┘
│ Tauri IPC (typed DTOs, validated arguments)
┌───────────────▼──────────────────────────────────────────────┐
│ Commands (src-tauri/src/commands/) thin boundary │
│ validate input → call core → return DTO. No business logic. │
└───────────────┬──────────────────────────────────────────────┘
│
┌───────────────▼──────────────────────────────────────────────┐
│ Core (src-tauri/src/core/) no UI, no Tauri types │
│ search · playback state machine · queue · lyrics · │
│ library · discovery · provider registry · caches │
├──────────────────────────────────────────────────────────────┤
│ Sync (src-tauri/src/sync/) backend client: auth, │
│ local store, offline queue, conflicts │
├──────────────────────────────────────────────────────────────┤
│ Platform (src-tauri/src/platform/) macOS media, menu │
└──────────────────────────────────────────────────────────────┘
│ HTTP (optional)
LUNOR-X backend accounts + playlists only
The dependency rules are checked in review:
- The UI calls the core through IPC. The desktop reaches the backend only through
sync/.
- Domain logic in the core uses no UI framework and no Tauri-specific API, so it can be tested without a window.
- Commands stay thin. Business logic goes in the core.
- The frontend does not re-implement search or playback orchestration.
- Provider details stay out of the generic playlist and queue models. An id from one provider is never used for another, and results are never merged by title alone.
Repository layout
desktop/
├─ src/ frontend
│ ├─ app/ Next.js entry, global CSS and design tokens
│ ├─ components/ shared UI, layout shell (Sidebar, TopBar, players)
│ ├─ features/ one folder per screen: home, explore, search,
│ │ library, artists, playlists, queue, player,
│ │ settings, sync, accounts, connections, offline…
│ ├─ lib/ stores (Zustand), playback, lyrics, prefetch, app style
│ └─ services/tauri/ one typed wrapper per IPC command group
├─ src-tauri/
│ ├─ src/core/ domain, search, playback/, lyrics, library, discovery
│ ├─ src/commands/ IPC handlers: player, search, library, lyrics, sync…
│ ├─ src/sync/ backend client, local store, offline queue
│ ├─ src/platform/ macOS Now Playing, media keys, menu
│ ├─ capabilities/ Tauri permission sets
│ ├─ build.rs declares the app manifest (every command, by name)
│ └─ tests/ ACL guards per command group, opt-in live tests
├─ tests/ frontend tests (bun:test)
├─ scripts/release/ release helpers
├─ .github/workflows/ release workflow
├─ AGENTS.md CLAUDE.md rules for coding agents working here
├─ PRODUCT.md DESIGN.md product context and the visual system
└─ RELEASING.md how a release is made
The IPC surface
A new command has to be registered in four places, and a test fails if one is missing:
- the handler in
src-tauri/src/commands/*.rs
generate_handler! in src-tauri/src/lib.rs- the command name in
src-tauri/build.rs (AppManifest::commands)
allow-<command-name> in src-tauri/capabilities/default.json
The tests/acl_*.rs files read those files and check that every handler in a group is both declared and allowed. Arguments are validated at the boundary (sizes, id shapes, ranges). Errors cross IPC as fixed categories, without raw messages or stack traces.
| Group | Commands |
|---|
| Player | player_load player_play player_pause player_resume player_stop player_seek player_set_volume player_state player_progress player_skip player_observe player_track_info player_open_external player_audio_settings player_set_audio_settings |
| Search and discovery | search_query search_cancel search_suggestions discovery_feed providers_list |
| Library | library_likes library_set_like library_artist library_album library_history library_clear_history |
| Lyrics | lyrics_source_fetch lyrics_source_search lyrics_source_bind lyrics_source_unbind lyrics_settings_get lyrics_settings_set · lrc_load lrc_save lrc_delete lrc_reveal lrc_list |
| Sync | sync_sign_in sync_sign_out sync_status sync_create_local_playlist sync_add_local_entry sync_remove_local_entry sync_upload_playlist sync_flush_pending sync_discard_pending sync_resolve_conflict sync_list_local_playlists |
| Providers | youtube_connect youtube_connect_finish youtube_disconnect youtube_connection_status provider_credential_set provider_credential_status provider_credential_clear |
| Updates | update_check update_install |
| Offline | offline_status offline_keep offline_cancel offline_remove |
Events come back through the same typed channel: core://player/state, core://player/progress, core://library/changed, core://history/changed, core://history/error, core://offline/changed and core://youtube/connection. Each subscription is removed when its component unmounts.
Playback pipeline
UI intent ─► player_load ─► core state machine ─► native host (libmpv)
▲ │
└── confirmed events ──┘
- The state machine rejects stale events by revision number, and the UI draws only what the core has confirmed.
innerlight resolves YouTube audio (one standard request, the signed-in cookie when connected; a sign-in or verification challenge is reported and not worked around), a bounded-range loopback proxy fetches it, and libmpv plays it. This path relies on the project-owner exception described under Security model.- Autoplay is a single bounded radio session, and the host's confirmed end-of-file is the only thing that advances it. The next track is prepared, and its lyrics prefetched, before it is needed. Preparation has a timeout and a bounded retry.
- Volume and seek commands are latest-wins, so dragging a slider does not queue stale commands.
- The offline cache is a disk cache with a size limit. Playlists you keep offline are pinned and never evicted.
Lyrics
Sources are tried in the order you set. The default order is your own file, then word-timed sources, then line-timed ones, then plain text.
| Source | Provides | Notes |
|---|
| My LRC | Line timing | Files made with Lyric Maker |
| LyricsPlus | Word timing | A cold request can take several seconds. Use "Try again" in the source sheet |
| Netease | Word and line timing | Supports search by title |
| LRCLIB | Line timing, plain text | Fuzzy matching with duration checks |
| QQ Music | Line timing | Supports search by title |
| Kugou | Line timing | Supports search by title |
| Boidu | Word timing | Answers only for tracks it has cached |
| YouTube Music | Plain text | No timestamps |
- Only public track metadata (title, artists, length) goes to these services. No cookie, token or account data does.
- Most of these endpoints are unofficial and could change or disappear. You can turn each source off under Settings > Lyrics. Results are cached, and misses are remembered for 24 hours, so the app does not keep asking for lyrics a service does not have.
- A line without a real timestamp is never shown as timed. Estimated and guessed timing carries a label ("estimated timing", "words guessed"), and word highlighting is real only when the source supplies word times.
- The lyric-source code lives in
src-tauri/src/core/playback/lyric_sources/.
Security model
- IPC. Every command is declared and allowed, and its arguments are validated. Native permissions are not exposed to remote content.
- Content Security Policy.
style-src 'self' with no inline styles, script-src limited to the app and YouTube, and images only from the app, data: and the known thumbnail hosts. This is why motion code mounts on the client only.
- Credentials. YouTube session cookies and the sync token live in the OS key store (Keychain, Credential Manager, Secret Service). The app does not write them to disk, log them, send them to the backend or show them in the UI. Where no secure store exists (Linux without a Secret Service), the feature fails closed. There is no in-memory or plaintext fallback.
- Secrets in the binary. None are shipped.
- Ownership. The server decides who owns what. The client never asserts a user id.
- The YouTube exception. Provider guidelines normally forbid stream extraction and cookie use. For YouTube, the project owner chose native extraction and Google-session sign-in instead of OAuth2, and
AGENTS.md records that decision. It is a decision by the project, and the provider has not approved it. Spotify has no such exception and is unsupported.
- To report a vulnerability, read SECURITY.md. Please do not open a public issue.
Design system
The theme is dark glass and blur with one accent, Lumen Lavender (#c5b4ff), which marks live state and nothing else. Panels have no borders. Only the sidebar and the player bar use blur, and everything else is flat. Components are ln- classes plus Tailwind v4 tokens declared in src/app/globals.css.
Read both before UI work. Loading, empty, unavailable, unauthorized, unsupported, failed, retrying and offline each have their own look, and an unsupported action is explained on screen instead of being hidden.
Keyboard shortcuts
| Action | macOS | Windows / Linux |
|---|
| Quick search and commands | ⌘K | Ctrl+K |
| Back / Forward | ⌘[ / ⌘] | Ctrl+[ / Ctrl+] |
| Collapse the sidebar | ⌘B | Ctrl+B |
| Play or pause (not while typing) | Space | Space |
| Close Now Playing, palette or dialog | Esc | Esc |
These are the defaults for your system. In Settings > Keyboard shortcuts you can press Change, record any combination you like, and Reset it again. Choices are stored per device, so macOS, Windows and Linux machines each keep their own. Keys are matched by physical key, so they work on any keyboard layout. Lyric Maker and the macOS Playback menu have their own shortcuts, listed on the same page.
Quality gates and tests
Run the gates for the part you changed. The policy is zero warnings. Blanket #[allow] is not accepted, and a targeted one needs the smallest possible scope and a one-line reason. Use --locked, and do not update dependencies to silence a lint.
Rust, from src-tauri/:
cargo fmt --check
cargo clippy --locked --all-targets -- -D warnings
cargo test --locked
Frontend, from the repository root:
bun run lint # tsc --noEmit
bun run build # next build, static export
bun test tests/ # frontend tests (bun:test)
| Suite | What it covers |
|---|
Unit tests (#[cfg(test)] next to the code) | Domain, search engine, playback state machine, queue, autoplay, lyrics matching and parsing, lyric sources against local mock servers, library, sync engine, persistence, and the token store (an in-memory double, so tests never touch the real keychain) |
tests/acl_*.rs | Every command is in the manifest and allowed in the capability set |
tests/backend_sync_live.rs | A real sign-in and playlist flow. Runs only when LUNORX_LIVE_BACKEND_URL is set, and otherwise skips |
tests/youtube_live.rs | Live YouTube Data API search. Runs only when LUNORX_LIVE_YOUTUBE_KEY is set, and otherwise skips |
tests/*.test.mjs | Frontend store logic |
The last full Rust run passed 648 tests with no failures, and bun test passed 23. Run them yourself for a current number. On hosted Windows CI the one test that opens a real audio device is skipped.
Not covered: end-to-end UI tests, a release bundle run on Windows or Linux, load tests, and playback against a real player in CI.
Releasing
A release is a version tag (for example v1.0.0). A tag without -rc is a full release and feeds the Stable update channel; every tag feeds Dev. Pushing the tag builds the installers and publishes them with SHA256SUMS.txt. The version lives in package.json and src-tauri/Cargo.toml, and the workflow rejects a tag that does not match both. RELEASING.md has the full steps, the platform table and the signing secrets.
Known limits
- libmpv has to be installed to run from source. Release bundles are meant to ship it, but that has only been tried on macOS, on a debug build.
- An artist photo needs a full artist profile request. The app makes two at a time and remembers the results, so the first run with many liked artists fills in gradually.
- The unofficial lyric endpoints may change or disappear at any time.
- The first request to LyricsPlus can be slow and may need one retry.
- SimpMusic is not supported, because its server answers only its own client.
- A playlist that is on the server cannot be renamed or reordered yet. Its description can be changed, online.
- The Windows and Linux installers, and installing a self-update, have not been run on a real machine yet.
Project documents
| File | Purpose |
|---|
| AGENTS.md | Working rules: architecture, hard rules, commands, definition of done |
| CLAUDE.md | Notes for Claude Code sessions |
| PRODUCT.md | Who the app is for and what it must not become |
| DESIGN.md | Tokens, components, motion and accessibility rules |
| CONTRIBUTING.md | Branching and quality gates |
| INSTALL.md | Installing a release, and the macOS "could not verify" warning |
| RELEASING.md | Tags, installers, signing |
| SECURITY.md | How to report a vulnerability (privately, through GitHub) |
| THIRD_PARTY_NOTICES.md | Components, licences and what needs attention |
| CODE_OF_CONDUCT.md | Community rules |
| LICENSE | MIT, covering this repository |
| and |
Star History
