https://github.com/instazdll/waveflow
🌊 WaveFlow — Spotify-style desktop music player for your local library. Lock-free Rust audio (FLAC/MP3/DSD up to DSD1024), 6-band EQ, ReplayGain, gapless, crossfade, synced lyrics (LRCLIB), Last.fm scrobbling, DLNA server.
https://github.com/instazdll/waveflow
audio-player desktop-app dlna dsd equalizer flac hi-res-audio lastfm local-music lrclib lyrics music-player react replaygain rust scrobbling spotify-clone tauri tauri-app typescript
Last synced: 27 days ago
JSON representation
🌊 WaveFlow — Spotify-style desktop music player for your local library. Lock-free Rust audio (FLAC/MP3/DSD up to DSD1024), 6-band EQ, ReplayGain, gapless, crossfade, synced lyrics (LRCLIB), Last.fm scrobbling, DLNA server.
- Host: GitHub
- URL: https://github.com/instazdll/waveflow
- Owner: InstaZDLL
- License: gpl-3.0
- Created: 2026-04-09T06:57:56.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-12T23:31:12.000Z (about 1 month ago)
- Last Synced: 2026-05-13T00:28:35.864Z (about 1 month ago)
- Topics: audio-player, desktop-app, dlna, dsd, equalizer, flac, hi-res-audio, lastfm, local-music, lrclib, lyrics, music-player, react, replaygain, rust, scrobbling, spotify-clone, tauri, tauri-app, typescript
- Language: Rust
- Homepage: https://www.waveflow.app
- Size: 3.29 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: docs/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: .github/SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
WaveFlow
Local music player for desktop — built with Tauri 2, React 19 & Rust
---
WaveFlow is a local music player desktop app with a Spotify-inspired 3-panel UI. It scans your local audio folders, organizes tracks by album/artist/genre, and plays them with a real-time audio engine — no streaming, no cloud, your music stays on your machine.
## Download
Pre-built bundles for every tagged release are on the [GitHub Releases page](https://github.com/InstaZDLL/WaveFlow/releases/latest). Pick the one that matches your environment:
### Linux
**Recommended — use your distro's package manager** so updates flow through the same tool you already use for the rest of your system:
- **Arch / Manjaro / EndeavourOS** — install [`waveflow-bin`](https://aur.archlinux.org/packages/waveflow-bin) from the AUR:
```bash
yay -S waveflow-bin # or paru, etc.
```
- **Fedora / RHEL / Rocky / Alma / CentOS Stream** — enable the [InstaZDLL/waveflow COPR](https://copr.fedorainfracloud.org/coprs/instazdll/waveflow/) once, then install via `dnf`:
```bash
sudo dnf copr enable instazdll/waveflow
sudo dnf install waveflow
```
- **Debian / Ubuntu / Mint / Pop!\_OS** — add the apt repo once, then install via `apt`. Note the package name is `wave-flow` (kebab-case, required by Debian naming rules — Tauri bundles it that way from the `WaveFlow` product name):
```bash
sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://packages.buildkite.com/instazdll/waveflow/gpgkey \
| sudo gpg --dearmor -o /etc/apt/keyrings/waveflow.gpg
echo "deb [signed-by=/etc/apt/keyrings/waveflow.gpg] https://packages.buildkite.com/instazdll/waveflow/any/ any main" \
| sudo tee /etc/apt/sources.list.d/waveflow.list
sudo apt update && sudo apt install wave-flow
```
Standalone bundles (for everything else, or if you'd rather skip a repo):
- `WaveFlow__linux-x86_64.deb` — Debian / Ubuntu / Mint / Pop!\_OS. Native install via `apt`/`dpkg`, integrates with the system menu.
- `WaveFlow__linux-x86_64.rpm` — Fedora / RHEL / openSUSE / Rocky / Alma. Native install via `dnf`/`rpm`.
- `WaveFlow__linux-x86_64.AppImage` — Anything else (Calculate Linux, Oracle Linux, NixOS, …). `chmod +x` then run; no install required.
### Windows
- **One-liner via [winget](https://github.com/microsoft/winget-cli)** — `winget install InstaZDLL.WaveFlow`. Auto-tracks updates with `winget upgrade`.
- `WaveFlow__windows-x86_64-setup.exe` — NSIS installer, **per-user** install under `%LOCALAPPDATA%`, doesn't need admin. This is what the in-app updater patches.
- `WaveFlow__windows-x86_64.msi` — MSI installer, **system-wide** install under `Program Files`, suitable for IT deployment via GPO/SCCM. Requires admin.
Both are Authenticode-signed. SmartScreen may still warn the first few users while a fresh certificate accumulates reputation — click **More info → Run anyway**.
### macOS
- `WaveFlow__macos-universal.dmg` — Intel + Apple Silicon in one bundle.
The macOS build is **not Apple-Developer-signed yet**, so Gatekeeper will block the first launch:
- macOS 14 (Sonoma) and earlier: **right-click the app → Open**, confirm the dialog.
- macOS 15 (Sequoia) and later: launch normally, then go to **System Settings → Privacy & Security** and click **Open Anyway** next to the blocked app.
- Terminal escape hatch (any version): `xattr -cr /Applications/WaveFlow.app`
### Auto-updates
Once installed (any of the above), the in-app updater fetches future versions automatically — but only the AppImage and the NSIS setup are auto-updatable. DEB / RPM / MSI are managed by their respective package managers and stay on the version you installed until you upgrade them externally.
## Features
| Area | Highlights | Deep dive |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| **Playback** | Symphonia + cpal, lock-free 3-thread engine, real dual-decoder crossfade, ReplayGain, variable playback speed (0.5×–2×), output-device picker, OS media controls (SMTC / MPRIS / MediaRemote), persistent queue with shuffle / repeat / auto-advance | [docs](docs/features/playback.md) |
| **Library** | Folder scanning + filesystem watcher, on-demand audio analysis (peak, loudness, ReplayGain, BPM), Hi-Res badges, multi-artist split, POPM 5-star ratings, A-Z navigator, multi-select action bar | [docs](docs/features/library.md) |
| **Playlists** | Drag-and-drop reorder (virtualised), bulk add from any source, M3U import / export with basename-fallback matching, likes, recently-played | [docs](docs/features/playlists.md) |
| **Smart playlists** | Auto-generated **Daily Mix** family bucketed by tempo, with composite artist-photo covers rendered from your Deezer cache | [docs](docs/features/smart-playlists.md) |
| **Integrations** | Deezer (artwork + labels), Last.fm (bios + scrobbling with retry queue), LRCLIB (synchronised lyrics), Discord Rich Presence ("Listening to WaveFlow" with cover + progress bar) — all cached locally for offline use | [docs](docs/features/integrations.md) |
| **UI & UX** | Spotify-style 3-panel layout, system tray, statistics dashboard with JSON export, **WaveFlow Wrapped** year-in-review (story-style overlay), virtual scroll for 6000+ tracks, dark mode (View Transitions API), 17 locales (RTL-aware), per-profile isolated DB with scheduled auto-backup, signed auto-updater | [docs](docs/features/ui.md) |
## Tech Stack
| Layer | Technologies |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Desktop shell** | Tauri 2.10 (tray icon, opener, dialog, updater plugins) |
| **OS media controls** | souvlaki 0.8 (SMTC / MPRIS / MediaRemote bridge) |
| **Discord Rich Presence** | discord-rich-presence 1.1 (local IPC named pipe, no auth) |
| **Frontend** | React 19, TypeScript, Vite 8, Tailwind CSS 4, Lucide icons, `@dnd-kit` (drag-and-drop), `@tanstack/react-virtual` (virtualization) |
| **Backend** | Rust, SQLite (sqlx), FTS5 contentless full-text search |
| **Audio** | symphonia 0.5 (decode), cpal 0.17 (output), rubato 2.0 (resample), rtrb 0.3 (SPSC ring) |
| **Metadata extraction** | lofty 0.24 (tags, embedded art, POPM, INITIALKEY) |
| **Imaging** | image 0.25 + fast_image_resize 6 (SIMD thumbnails) |
| **Filesystem watcher** | notify 8 (debounced rescans of watched folders) |
| **External APIs** | Deezer public API (no auth) + Last.fm (read + signed methods via md-5 + reqwest 0.12 with rustls) + LRCLIB (synchronized lyrics) |
| **Package manager** | Bun |
## Getting Started
```bash
# Install dependencies
bun install
# Run the desktop app in development mode
bun run tauri dev
# Build for production
bun run tauri build
```
## Development Commands
```bash
bun run dev # Vite dev server only (no Tauri shell)
bun run typecheck # TypeScript check
bun run lint # ESLint
bun run lint:fix # ESLint with auto-fix
bun run format # Prettier
# Rust backend
cargo check --manifest-path src-tauri/Cargo.toml --all-targets
cargo test --manifest-path src-tauri/Cargo.toml
```
## Documentation
Per-feature deep dives, architecture and storage layout live under [`docs/`](docs/README.md):
- **Features** — [playback](docs/features/playback.md) · [library](docs/features/library.md) · [playlists](docs/features/playlists.md) · [smart playlists](docs/features/smart-playlists.md) · [integrations](docs/features/integrations.md) · [UI & UX](docs/features/ui.md)
- **Architecture** — [audio engine](docs/architecture/audio.md) · [database & paths](docs/architecture/storage.md)
- **Contributing** — [CONTRIBUTING.md](CONTRIBUTING.md) · [RELEASING.md](RELEASING.md)
## License
```
Copyright (C) 2026 InstaZDLL
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see .
```
See [LICENSE](LICENSE) for the full text.