Resonant/README.md

Resonant

Your library, wherever you listen.

Resonant is a desktop-first music player for personal collections. The desktop app can privately serve a folder on this computer through its bundled Navidrome engine, or connect directly to an existing Navidrome or OpenSubsonic-compatible server.

What works in v0.1

• A responsive library home with paginated newest albums, a complete Songs view, favorites, search, and queue management
• Functional playback controls with seek, volume, previous, and next actions
• An offline demo library with locally synthesized audio, so the app is useful immediately after cloning
• OpenSubsonic token authentication, connection testing, complete album/song pagination, artwork, and streaming URLs
• Managed Navidrome 0.61.2 and FFmpeg sidecars, with native folder selection, first-user setup, transcoding, LAN access, process lifecycle control, and app-private server data
• One-time five-digit pairing for connecting another Resonant computer on the same network without entering a server address or credentials
• Official release download and SHA-256 verification for Apple Silicon/Intel macOS, x64/ARM64 Linux, and x64 Windows desktop builds
• A charcoal and onyx interface with coral reserved for active state and primary action
• A Tauri 2 desktop shell for macOS, Windows, and Linux development
• Keyboard-visible controls, reduced-motion support, semantic labels, and a WCAG 2.2 AA target

Local and remote server passwords are stored through the operating system credential store. Resonant restores the selected library automatically on the next desktop launch.

Run it

Requirements: Node.js 22+, Rust 1.85+, and the platform prerequisites for Tauri 2.

npm install
npm run dev

To run the desktop shell with the bundled server:

npm run desktop:dev

The first desktop run downloads the pinned official Navidrome binary for the current Rust target, verifies its release digest, and prepares the platform's pinned FFmpeg static binary. Both executables and their license notices are bundled into packaged apps, not committed to this repository.

The generic Tauri entry point also prepares the sidecar automatically, so npm run tauri dev and npm run tauri build are supported as well.

To validate the full project:

npm run check

Choose a library source

Open the library control in the lower-left corner.

• This computer: choose a music folder and a library password. Resonant starts its bundled Navidrome process on port 4533, stores the Navidrome database under the app data directory, and stops it when Resonant closes. To connect another Resonant computer, show a temporary five-digit code on the host and enter it on the other computer.
• Another computer: enter the host's pairing code, or use the manual path by entering the URL and credentials for a Navidrome or OpenSubsonic server you already run.

Passwords are saved in Keychain on macOS, Credential Manager on Windows, or Secret Service on Linux. Browser development can preview the interface and connect to servers that allow the development origin, but secure credential persistence, native folder selection, and the managed server require the Tauri desktop app.

Architecture

Resonant desktop client
├── React product interface
├── Playback and queue state
├── OpenSubsonic client
│   ├── salted token authentication
│   ├── library and artwork requests
│   └── authenticated stream URLs
└── Tauri shell
    ├── one-time LAN pairing service
    │   └── encrypted credential handoff
    └── managed Navidrome sidecar
        ├── official, pinned, checksum-verified binary
        ├── bundled FFmpeg transcoder
        ├── private-network HTTP server
        └── app-private database and logs

Navidrome or another OpenSubsonic server
├── scans and indexes music
├── owns metadata and artwork
└── streams or transcodes audio

The protocol boundary is deliberate. Resonant owns the product experience without forking the media engine, and the server can be replaced as long as it speaks OpenSubsonic.

Network boundary

The managed server is reachable by devices on the same LAN and is protected by the library password. A pairing code expires after two minutes, can be used once, and stops accepting connections after five attempts. Resonant uses the code in a password-authenticated key exchange, then encrypts the credential handoff; the library password is never sent in plain text. Pairing uses local broadcast discovery, so segmented Wi-Fi or VLAN networks may require the manual connection path.

Resonant intentionally does not configure routers, public DNS, certificates, or internet exposure. Do not forward port 4533 directly to the public internet; remote access should use a trusted VPN or a TLS reverse proxy.

Next milestones

1. Move remote requests into Tauri's HTTP plugin for stricter native networking control.
2. Add album and artist detail routes.
3. Persist the queue, favorites, and playback position, then synchronize favorites back to the server.
4. Add native media keys, system now-playing metadata, ReplayGain, and gapless transition support.
5. Add a guided VPN/TLS remote-access flow without silently exposing the library to the internet.

Product direction and accessibility principles live in PRODUCT.md. Third-party licensing and source links live in THIRD_PARTY_NOTICES.md.