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 albums, tracks, 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, album loading, random-track loading, artwork, and streaming URLs
• A managed Navidrome 0.61.2 sidecar bound to 127.0.0.1, with native folder selection, first-user setup, process lifecycle control, and app-private server data
• 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

The server password is held only in memory. Resonant remembers the server address and username locally, but secure credential persistence is intentionally deferred until the desktop keychain integration is added.

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 places it in Tauri's ignored sidecar build directory. The binary is 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 local password. Resonant starts its bundled Navidrome process on 127.0.0.1:4533, stores the Navidrome database under the app data directory, and stops it when Resonant closes. The app clears its demo content while Navidrome scans and waits for real indexed tracks before showing the library.
• Existing server: enter the URL and credentials for a Navidrome or OpenSubsonic server you already run.

The local password and remote server password are held only in memory. Browser development can preview the interface and connect to servers that allow the development origin, but 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
    └── managed Navidrome sidecar
        ├── official, pinned, checksum-verified binary
        ├── loopback-only 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.

Current boundaries

• Navidrome is bundled; FFmpeg is not yet bundled. Native browser-supported audio formats play directly, while formats that require transcoding still need FFmpeg available on the system.
• The local server is intentionally reachable only from this computer. Listening from another device will be a separate, explicitly enabled feature.
• Credentials are session-only until OS keychain integration lands.

Next milestones

1. Move remote requests into Tauri's HTTP plugin and store credentials in the OS keychain.
2. Add album and artist detail routes with deterministic library pagination.
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 an explicit remote-access flow without weakening the local-only default.

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