Qobee

#aA+ Qobee

A local audio player for Windows, focused on fidelity. Indexes one or more music folders, plays FLAC and other lossless formats through the OS mixer, and is built so that a future bit-perfect output path can drop in without rewriting the rest of the app.

The current build delivers a complete listening experience: scanning, albums / artists / genres / playlists / favorites, search, queue management, 10-band equalizer, ReplayGain, gapless playback, sample-accurate seek, lyrics (synced + plain), a mini player, themes, accent following the cover, OS media keys, and Discord Rich Presence. The audio engine ships with two output backends — Shared (default, OS mixer) and WASAPI Exclusive (opt-in, strictly bit-perfect when the device cooperates). See "Bit-perfect honesty" below for the truth about each chain.

Concept

• Local-first: no streaming, no cloud, no media server.
• FLAC priority, other lossless formats next.
• No tag editing, no media-server features, no library lock-in.
• Sober, dark UI inspired by Cider (sidebar, album grid, artist list, album detail, track list, persistent player bar).
• Audio engine designed up front to deliver clean Shared output with a real bit-perfect path available via WASAPI Exclusive on Windows.

Bit-perfect honesty

Qobee will tell you the truth about its current playback chain rather than ship a misleading badge.

• The default backend, Shared (CpalSharedEngine), talks to WASAPI in shared mode on Windows. The OS mixer can resample, dither, apply effects, and mix Qobee's stream with other apps. It is not bit-perfect. The player bar reports Bit-perfect: false on this backend even when the in-app DSP is at unity.
• The opt-in backend, WASAPI Exclusive (WasapiExclusiveEngine), bypasses the OS mixer and reaches a strictly bit-perfect chain only when the device natively accepts the source's sample rate and channel count, the EQ is flat, ReplayGain is at unity and the volume is at 100 %. Any departure from that — resampling, upmix to a surround layout because the OS is configured that way, an EQ band that isn't 0 dB, a volume slider that isn't at the top — flips is_bit_perfect back to false. While Exclusive is active no other application can play to the same device.
• Software volume, the EQ and ReplayGain are honored on both paths because users still want them; the badge tracks them honestly.

Stack

• Rust workspace with separate crates for the audio engine, library indexing and orchestration:
  • crates/engine — Symphonia (decoding), CPAL (Shared output), WASAPI Exclusive backend, biquad EQ, and a fidelity-first DSP chain shared by both backends (see "Audio chain" below).
  • crates/library — walkdir + lofty for tag extraction, rusqlite (bundled) for storage, embedded covers cached on disk, FTS-style search, settings table.
  • crates/core — playback queue (cursor + history), repeat / shuffle / endless logic, orchestration between engine and library.
• Tauri 2 desktop shell in src-tauri/, including a Discord Rich Presence worker and a cover-hosting worker (background uploads to a public host so Discord can render local album art).
• Svelte 5 + TypeScript strict + Vite frontend in ui/.

Audio chain

The engine runs a single, deterministic DSP pipeline on top of both the Shared and Exclusive backends. Every stage is bypassable and honest about what it does — the truthful is_bit_perfect badge reflects the actual chain, not a marketing flag.

• ReplayGain peak protection. The pre-gain stage combines the RG track/album gain, a configurable safety headroom and the source's true peak (read from REPLAYGAIN_TRACK_PEAK / _ALBUM_PEAK tags) so the output never exceeds the chosen ceiling. Missing peak tags fall back to a conservative 1.0, and the attenuation actually applied is reported in the player state.
• Dither. Three profiles: tpdf (legacy white triangular PDF), shaped_hp (HF-emphasis shaping), and shaped_f_weighted (the default — F-weighted noise shaping that pushes the noise floor away from the ear's peak sensitivity). The stage is in exact bypass when the output is wider than 16 bits.
• Peak limiter. Three modes: off (passthrough), soft_clip (smooth tanh-style clipper, legacy behaviour), and lookahead_limiter (the default — true-peak look-ahead limiter with configurable ceiling, look-ahead and release).
• Logarithmic volume. The slider maps to a dB scale by default (logarithmic curve, configurable floor) so a small movement at low levels behaves like the volume control on a real amplifier. The legacy quadratic curve remains available.
• Crossfeed. Bauer-style stereo-to-headphones crossfeed with three presets (bauer, bauer_strong, custom) and tunable inter-aural delay and low-pass cutoff. Off by default.
• DSD / DoP. Native decoding of DSF and DFF files, with DSD over PCM (DoP) packing for WASAPI Exclusive devices that accept it.
• Convolver. FFT-partitioned IR convolver for room-correction or headphone-EQ filters. Loads any IR the user picks, with a per-IR gain trim to keep the output within the limiter ceiling.
• Balance + per-channel trim. Stereo balance plus an optional per-channel trim vector (≤8 channels) for asymmetric setups.
• Bit-Perfect Health panel. A live status badge surfaces every factor that breaks bit-perfect — non-native sample rate, channel upmix, non-unity volume, EQ engaged, ReplayGain attenuation, dither active, limiter biting — so the user knows exactly which stage is colouring the sound.
• Null-test diagnostic. Plays a known reference and compares it against either a loopback capture or the pre-render buffer, reporting peak/RMS difference and a BitPerfect / Modified / Inconclusive verdict.

Pinned versions:

Architecture notes

• PCM buffer is an enum, not just Vec<f32>. The engine exposes F32Interleaved, I16Interleaved, I24In32Interleaved and I32Interleaved. Only F32Interleaved is produced today, but the integer variants are part of the public API so a future bit-perfect path can plug in without breaking call sites.
• SPSC ring between decoder and audio callback uses rtrb. The current ring carries f32; an integer ring will be added alongside the Exclusive backend.
• Cover art never crosses the IPC boundary for the UI. Embedded pictures are written to a sharded on-disk cache (%APPDATA%\Qobee\covers\<aa>\<hash>.<ext>) and exposed to the webview via the custom qobee-cover:// URI scheme. The frontend loads them with plain <img> tags.
• Local covers reach Discord through a separate worker. Discord requires a public HTTPS URL or a registered asset key, neither of which fits a local file. A dedicated upload worker pushes each cover once to a public host (litterbox.catbox.moe), memoizes the URL in the settings table, and patches the active activity in place. The Discord IPC worker is never blocked on the network.
• No silent resampling. When the device's sample rate differs from the source, the engine logs an explicit warning and the player state continues to report is_bit_perfect: false.
• Smooth UI under audio cadence. Position events fire at decoder cadence, not per audio frame, and the Discord and MediaSession layers coalesce same-bucket updates so the elapsed bar never flickers and Discord's rate limit is never tripped.

Layout

Qobee/
├── Cargo.toml                     # workspace
├── crates/
│   ├── engine/                    # AudioEngine + backends + EQ
│   ├── library/                   # scan + DB + cover cache + settings
│   └── core/                      # queue + player FSM + history
├── src-tauri/                     # Tauri shell
│   ├── tauri.conf.json
│   ├── capabilities/default.json
│   ├── icons/
│   └── src/
│       ├── main.rs
│       ├── lib.rs                 # builder + qobee-cover:// protocol
│       ├── commands.rs            # Tauri command surface
│       ├── state.rs               # AppState (library + player + discord)
│       ├── discord.rs             # Discord Rich Presence worker
│       └── cover_host.rs          # async cover uploader for Discord
└── ui/                            # Svelte 5 + TS strict
    ├── package.json
    ├── vite.config.ts
    ├── svelte.config.js
    ├── tsconfig.json
    ├── index.html
    └── src/
        ├── main.ts
        ├── App.svelte
        ├── components/            # Sidebar, AlbumGrid, PlayerBar, …
        ├── lib/
        │   ├── api.ts             # typed wrappers around invoke()
        │   ├── stores.svelte.ts   # reactive app state
        │   ├── settings.svelte.ts # persisted preferences
        │   ├── accent.svelte.ts   # cover-driven accent color
        │   ├── discordPresence.ts # Discord singleton
        │   ├── mediaSession.ts    # OS media keys
        │   └── …                  # context menu, palette, format, etc.
        └── styles/global.css

Tauri commands

All commands live in src-tauri/src/commands.rs and are mirrored 1:1 in ui/src/lib/api.ts (typed wrappers).

Library / browsing:

Playback:

Queue:

Playlists / favorites:

Equalizer / settings / maintenance / Discord:

Events emitted to the UI:

Running in development

Prerequisites:

• Rust stable (≥ 1.85). The exact toolchain is pinned in rust-toolchain.toml (currently 1.96.0); rustup installs and selects it automatically inside the workspace, so your local rustfmt / clippy match CI. CI pins the same version, so the "passes locally, fails in CI" drift can't happen.
• Node.js (≥ 20)
• On Windows, the WebView2 runtime (preinstalled on Windows 11; on Windows 10 install from Microsoft if missing).

One-time setup — enable the git pre-push hook so cargo fmt --check and cargo clippy -D warnings run before every push (the two gates most prone to toolchain drift):

./scripts/setup-hooks.ps1   # macOS/Linux: ./scripts/setup-hooks.sh

Bypass a single push with git push --no-verify if you really need to.

Steps:

# 1. install JS dependencies (only needed once, and after package.json changes)
cd ui
npm install
cd ..

# 2. start the dev app — Tauri spins up vite for the frontend automatically
cargo run -p qobee-app

If you prefer the official Tauri CLI workflow, run it from the workspace root (Tauri 2's CLI looks for tauri.conf.json in subfolders only, so it must see both ui/ and src-tauri/ as siblings beneath its cwd):

cd ui
npm install
cd ..
.\ui\node_modules\.bin\tauri.cmd dev

(The tauri.conf.json points frontendDist at ../ui/dist and devUrl at http://localhost:1420, which is what npm run dev serves.)

Building for release

cd ui
npm install
npm run build
cd ..
cargo build -p qobee-app --release

The bundled installer / .exe lands under target/release/.

For a fully bundled installer (MSI, NSIS, etc.) run the Tauri CLI from the workspace root (not from ui/) so it can locate the tauri.conf.json in src-tauri/:

cd ui
npm install
cd ..
.\ui\node_modules\.bin\tauri.cmd build

The MSI / NSIS installers land under src-tauri/target/release/bundle/.

What works today

• Workspace compiles without warnings; full Vite + Tauri build is clean.
• App launches with sidebar, home, album grid, artist list, artist detail, album detail, genres, playlists, favorites, search, settings and a persistent player bar.
• Onboarding when the library is empty: a welcome screen walks the user through picking a music folder, with the same flow available later from Settings → Library.
• Drag-and-drop a folder anywhere on the window to add it as a library root and trigger a scan.
• Resizable, collapsible sidebar like Apple Music / Arc: drag the right edge to resize, drag below 140 px to collapse to icon- only mode. Width and collapsed state are persisted in localStorage.
• System tray icon (Windows) with right-click menu for show / focus, play / pause, prev / next, library, settings, quit. Left click brings the window forward.
• Windows desktop integration (opt-in per item in Settings → Windows Integration): autostart at login, start minimized, minimize-to-tray on close, audio file context menu (Play in Qobee, Add to Qobee queue, Play next, Import to library), folder context menu (Play folder, Add folder to queue, Scan folder, Import folder), qobee:// protocol handler. Every registry write goes to HKCU only; Qobee never claims the system default and never modifies machine-wide associations.
• Single-instance + deep-link forwarding: launching qobee.exe --play foo.flac while the app is already running sends the command to the existing window instead of spawning a duplicate. Same path for qobee:// deep links.
• Library scan extracts FLAC / MP3 / WAV / M4A / AAC / ALAC / OGG / Vorbis / Opus tags and embedded covers via lofty.
• Multi-root library: add as many folders as you want, scan each or rescan all in one pass.
• SQLite library lives at %APPDATA%\Qobee\library.sqlite3. Covers are cached at %APPDATA%\Qobee\covers\ and served via qobee-cover://. Logs land in %APPDATA%\Qobee\logs\ with daily rotation.
• Decoding via Symphonia, output via CPAL Shared, output device selectable from Settings.
• Play / pause / resume / next / prev, seek (Coarse), software volume in Shared mode.
• Queue: play next, add to queue, reorder, remove, jump to, inspect from a popover.
• Playlists (create / rename / delete / add / remove / play from any track) and favorites (per-track, global Favorites screen).
• Repeat (off / track / queue), shuffle, and endless playback.
• 10-band peaking EQ at ISO octave centers (Q=1.0, ±12 dB), with presets and an automatic bypass when every band is at 0 dB.
• Full audio DSP chain, shared between Shared and Exclusive backends and exposed in Settings → Audio: ReplayGain true-peak protection with safety headroom, dither (TPDF / shaped HP / shaped F-weighted), peak limiter (off / soft-clip / look-ahead, on by default), logarithmic volume curve with a configurable floor, Bauer-style crossfeed (presets + custom), native DSD/DoP playback, FFT-partitioned IR convolver, balance and per-channel trim. See "Audio settings keys" below for the full key list.
• Bit-Perfect Health badge in the player bar that lists every factor breaking bit-perfect (non-native rate, channel upmix, non-unity volume, EQ on, ReplayGain attenuation, dither, limiter biting) instead of a binary green light.
• Null-test diagnostic in Settings → Diagnostics that plays a reference signal and reports peak/RMS difference plus a BitPerfect / Modified / Inconclusive verdict.
• Search across titles, artists and albums.
• Recently played tracks / albums / artists on the home page.
• Themes (system / dark / light), configurable accent color, and an opt-in "follow cover" mode that drives the accent from the current album art.
• Now Playing fullscreen view: click the cover in the player bar (or press F) to open an immersive page with large artwork, scrubbable progress, transport controls, and a heart toggle.
• Keyboard shortcuts when no input is focused: Space (play/pause), ←/→ (-5s / +5s), n / p / Alt+← / Alt+→ (prev / next track), F (toggle Now Playing), Esc (close Now Playing or clear search), Ctrl/Cmd+F (focus search).
• Toasts for transient confirmations ("Added to favorites", "Playing next: 12 tracks") so the UI never falls back to native alert dialogs.
• Window state persistence: size, position and maximized state are restored on next launch via tauri-plugin-window-state.
• OS media keys / Bluetooth controls / Windows quick controls via the Media Session API (play, pause, next, prev, seekto, stop).
• Discord Rich Presence: title, artist, album, real cover art, and an elapsed/remaining timeline pushed in real time. The worker reconnects automatically when Discord starts/restarts and falls back silently when Discord is closed; pause hides the activity, resume restores it. Local cover hosting is opt-in for privacy: enable it from Settings → Integrations and the matching privacy notice explains exactly what gets uploaded and where.
• The player bar always shows the effective output mode and a truthful bit-perfect badge.

Audio settings keys

Every audio preference is persisted as a JSON value in the SQLite settings table under an audio.* key. Booleans, numbers and arrays are stored as JSON; enums are stored as snake_case strings. Out-of-range values read at boot are clamped and rewritten; missing keys are created with their default. The full list is below; bounds and defaults are kept in sync with crates/engine/src/audio_settings.rs and the design document.

Windows integration

Qobee ships a real Windows desktop integration, opt-in per item from Settings → Windows Integration so the user keeps control over every shell hook. None of the hooks ever require admin privileges: every registry write goes to HKCU only, and Qobee never claims to be the system-wide default audio player.

Surface

• AppUserModelID — app.qobee.player, set on the running process via SetCurrentProcessExplicitAppUserModelID. Windows uses it to group the taskbar icon, notifications, and (static) Jump List under a single identity that survives updates.
• Single instance + argument forwarding — built on tauri-plugin-single-instance. A second qobee.exe invocation forwards its argv to the running window and exits; there is never a duplicate process or window.
• Tray icon — left click brings the main window forward; right click opens a menu with Show / focus, Play / Pause, Previous, Next, Open library, Settings, Quit. Toggleable from Settings.
• Close-to-tray — when enabled, the window's close button hides the window instead of quitting; playback keeps running in the background.
• Autostart — registers (or removes) a value under HKCU\Software\Microsoft\Windows\CurrentVersion\Run\Qobee, optionally with --minimized.
• qobee:// protocol handler — registered as a soft handler under HKCU\Software\Classes\qobee. Examples: qobee://play?path=C%3A%2Fmusic%2Fa.flac, qobee://enqueue?path=..., qobee://play-next?path=..., qobee://play-folder?path=..., qobee://import-folder?path=..., qobee://library, qobee://settings.
• Audio file context menu — installs a soft OpenWithProgids hint on the 10 supported extensions (.mp3 .flac .wav .ogg .m4a .aac .opus .alac .aiff .wv) and attaches verbs Open in Qobee, Play in Qobee, Add to Qobee queue, Play next in Qobee, Import to Qobee library. Never replaces the default audio app.
• Folder context menu — adds Play folder, Add folder to queue, Scan folder, Import folder on Directory\shell, Directory\Background\shell (right-click empty space inside an open folder), and Drive\shell (right-click a drive letter).
• Command-line arguments — --play <paths>, --enqueue <paths>, --play-next <paths>, --play-folder <path>, --enqueue-folder <path>, --scan-folder <path>, --import-folder <path>, --open-library, --open-settings, --minimized. Bare paths are treated as --play <path>.

Registry footprint (HKCU only)

The NSIS installer (src-tauri/installer/qobee.nsh) registers the protocol + AUMID at install time and reverses every key listed above on uninstall. Toggling shell hooks at runtime from the Settings panel performs the equivalent registry writes through the set_windows_integration Tauri command.

What is intentionally not in yet

• Crossfade between tracks. The engine supports gapless transitions in place; crossfade would need a second active stream in parallel. Wired-in seam exists, no UI yet.
• Global hotkeys. Media keys / Bluetooth / lock-screen controls work; OS-wide hotkeys (Play/Pause from any focused app) do not.
• Scrobbling (Last.fm / ListenBrainz). Recently-played is recorded in the local library only.
• Tag editing. Qobee is read-only on the audio files.
• BASS backend. The engine-bass Cargo feature exists as a seam; the module is a stub with no external dependency.

Roadmap

• Crossfade.
• Global hotkeys (system-wide Play/Pause from any focused app).
• Dynamic taskbar Jump List (the static one already follows the AppUserModelID).
• Smart playlists (filter / sort presets).
• Scrobbling (Last.fm / ListenBrainz).
• Visualizer.
• BASS backend behind the engine-bass Cargo feature.

License

Dual-licensed under MIT or Apache-2.0. See the workspace Cargo.toml.