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.
- Audio playback — symphonia decoder + cpal output, supports MP3, FLAC, WAV, OGG Vorbis, AAC, ALAC (M4A)
- Real-time engine — lock-free 3-thread architecture (decoder, ring buffer, cpal callback), zero allocations in the hot path
- Library scanning — point to any folder, metadata extraction via lofty, embedded artwork extraction
- Multi-artist — automatic split of
"Artist A, Artist B"into individual, independently-linkable artists - Album & artist detail pages — clickable album/artist cards open a dedicated view with tracklist, discography, and stats
- Now Playing panel — Spotify-style right-edge panel with large artwork, clickable artists, and artist biography
- Metadata enrichment — Deezer public API (artist images, album covers, labels) + Last.fm (artist biographies) cached 30 days locally; artwork is downloaded into a hash-addressed on-disk cache so it renders offline on re-visits
- Playlists — create, edit, delete, add tracks from folders/albums/artists in bulk
- Likes — heart any track, dedicated "Liked tracks" view
- Search — instant full-text search (FTS5 contentless) across titles, artists, albums with prefix matching
- Queue — persistent queue with shuffle (Fisher-Yates), repeat (off/all/one), auto-advance
- Resume — remembers last track + position across app restarts
- Audio settings — volume normalization (-3 dB), mono downmix, crossfade slider (UI ready)
- Virtual scroll — handles 6000+ tracks without UI freeze (@tanstack/react-virtual)
- Dark mode — animated radial transition via View Transitions API
- i18n — French & English, auto-detected, switchable in settings
- Accessibility — keyboard navigation, ARIA roles, focus rings,
prefers-reduced-motion - Profiles — isolated per-profile database (libraries, playlists, settings, play history)
| Layer | Technologies |
|---|---|
| Desktop shell | Tauri 2.10 |
| Frontend | React 19, TypeScript, Vite 8, Tailwind CSS 4, Lucide icons |
| Backend | Rust, SQLite (sqlx), FTS5 contentless full-text search |
| Audio | symphonia 0.5 (decode), cpal 0.15 (output), rubato 0.15 (resample), rtrb 0.3 (SPSC ring) |
| External metadata | Deezer public API (no auth) + Last.fm (user-provided API key) via reqwest 0.12 with rustls |
| Package manager | Bun |
# Install dependencies
bun install
# Run the desktop app in development mode
bun run tauri dev
# Build for production
bun run tauri buildbun 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 # Prettierwaveflow/
├── src/ # React frontend
│ ├── components/
│ │ ├── common/ # Reusable UI (NavItem, Artwork, ArtistLink, modals, EmptyState)
│ │ ├── layout/ # Sidebar, TopBar, AppLayout, QueuePanel, NowPlayingPanel
│ │ ├── player/ # PlayerBar, PlaybackControls, VolumeControl, ProgressBar
│ │ └── views/ # Home, Library, Playlist, AlbumDetail, ArtistDetail, Liked, Recent, Settings, etc.
│ ├── contexts/ # ThemeContext, PlayerContext, LibraryContext, PlaylistContext, ProfileContext
│ ├── hooks/ # useTheme, usePlayer, useLibrary, usePlaylist, useProfile
│ ├── lib/
│ │ ├── tauri/ # Typed invoke() wrappers (track, browse, player, playlist, detail, integration)
│ │ ├── playlistVisuals.ts # Shared color/icon constants for playlists
│ │ └── PlaylistIcon.tsx # Icon dispatcher component
│ ├── i18n/locales/ # fr.json, en.json
│ ├── types/ # ViewId, LibraryTab, NavItemProps, etc.
│ ├── App.tsx # Provider tree
│ └── main.tsx # Entry point
├── src-tauri/ # Rust backend
│ ├── src/
│ │ ├── audio/ # Audio engine (engine, decoder, output, resampler, state, analytics)
│ │ ├── commands/ # Tauri commands (library, playlist, track, browse, player, scan, profile, deezer, integration)
│ │ ├── db/ # Database open/migrate helpers (app.db + per-profile data.db)
│ │ ├── deezer.rs # Deezer public API client (search/get artist & album)
│ │ ├── lastfm.rs # Last.fm API client (artist.getInfo with HTML strip)
│ │ ├── lrclib.rs # LRCLIB API client (synchronized lyrics)
│ │ ├── metadata_artwork.rs # Shared on-disk cache for remote artwork (blake3-hashed)
│ │ ├── queue.rs # Persistent queue operations (fill, advance, shuffle, restore)
│ │ ├── state.rs # AppState (profile pool, paths, global app_db)
│ │ ├── paths.rs # Filesystem layout
│ │ ├── error.rs # AppError + AppResult
│ │ └── lib.rs # Tauri setup, command registration, shutdown hook
│ ├── migrations/
│ │ ├── app/ # Global app.db schema (profile list, app_setting, deezer cache tables)
│ │ └── profile/ # Per-profile SQLite schema (FTS5 contentless, triggers, indexes, lyrics)
│ ├── Cargo.toml
│ └── tauri.conf.json
└── package.json
┌─ Tauri commands (tokio) ┌─ Decoder thread (std) ┌─ cpal callback (real-time)
│ player_play, pause, seek │ symphonia FormatReader + │ pop f32 from SPSC ring
│ → crossbeam::Sender ──────►│ Decoder + rubato Resampler │ × volume × normalization
│ │ push f32 → rtrb::Producer ──►│ mono downmix (if enabled)
│ │ emit position/state events │ → device native format
└──────────────────────────────┴───────────────────────────────┴──────────────────────────
Rules: the cpal callback never allocates, never locks, never logs. It only touches rtrb::Consumer and Atomic* fields in SharedPlayback.
Strings are externalized in src/i18n/locales/. To add a language:
- Create
src/i18n/locales/xx.json(same structure asfr.json) - Import it in
src/i18n/index.tsand add toSUPPORTED_LANGUAGES - It will appear in the Settings language selector automatically
GPL-3.0 — see LICENSE