Skip to content

README.md

Latest commit

 

History

History
201 lines (152 loc) · 10.4 KB

README.md

File metadata and controls

201 lines (152 loc) · 10.4 KB
Raw

WaveFlow logo

WaveFlow

Local music player for desktop — built with Tauri 2, React 19 & Rust

Version Downloads Tauri 2 React 19 Rust License Platform

WaveFlow is a desktop music player for the audio files you already own. It scans your folders, organizes everything by album, artist and genre, and plays it back through a fast, high-fidelity audio engine. No subscription, no streaming service, no account: your music stays on your machine.

Install — grab the bundle for your OS on the latest release; every release page lists the per-distro one-liner (AUR / COPR / apt / winget) and the standalone installers.

Screenshots

The immersive view: a track's Canvas clip looping beside lyrics synced word by word, with a romanization under each line
Immersive view · Canvas clip, lyrics synced word by word, romanization under each line

Home view with a greeting, mood radio and recently played A playlist page whose header takes its colour from the album artwork
Home · mood radio, Daily Mix, recently played Playlists · the header takes its colour from the cover
Album detail view with multi-disc grouping and the side Now Playing panel The in-app plugin store listing the official plugins
Album · multi-disc grouping, Now Playing panel with artist bio Plugin store · verified installs, one click
The mini-player showing the current track with its lyrics highlighted word by word The Now Playing side panel with the track's Canvas clip looping in place of the cover
Mini-player · always on top, lyrics word by word Now Playing panel · the Canvas clip loops in place of the cover

The floating desktop lyrics window over a desktop, showing the current line
Desktop lyrics · a floating line above every window

Album artwork shown in the screenshots belongs to its respective rights holders. WaveFlow does not bundle or distribute any music.

Features

🎧 Playback · docs

  • MP3, FLAC, WAV, AIFF, Ogg Vorbis, Opus, AAC, ALAC and DSD
  • Gapless playback and a real two-decoder crossfade
  • Exclusive output on Windows, Linux and macOS, and DSD over PCM (DoP), which sends DSD untouched to a compatible DAC (opt-in)
  • ReplayGain, 6-band EQ with presets, speed 0.5×–2×, A-B repeat, sleep timer
  • Seed and mood radio, album shuffle, OS media controls, a queue that survives a restart

🎤 Lyrics · docs

  • Synced lyrics from LRCLIB, Musixmatch, NetEase, Megalobiz and Genius — or from a plugin
  • Word-by-word karaoke, with the word timing estimated when a provider only has lines
  • Romanization for Japanese, Korean and Chinese, and translations beside the original
  • In the lyrics panel, the immersive view, the mini-player and a floating desktop window

📚 Library · docs

  • Folder scan with a live watcher; browse by album, artist, genre or folder
  • Search and filters, with pinyin for Chinese titles
  • A tag editor that keeps every tag it does not edit, and 5-star ratings written back to your files
  • Duplicates, a "Needs attention" tab, multi-artist split
  • Hi-Res badges, loudness and BPM analysis

🎶 Playlists · docs · smart playlists

  • Drag-and-drop, M3U import and export, a header coloured from the cover
  • Smart playlists built from rules, with a live count
  • Daily Mix and On Repeat, generated from what you play

🎨 Interface · docs

  • 5 skins × 14 themes, dark mode, a high-contrast mode
  • Immersive now-playing with Canvas clips, animated covers and a cover slideshow
  • Always-on-top mini-player, system tray, Windows taskbar buttons
  • Statistics and WaveFlow Wrapped, all computed locally
  • 17 languages including right-to-left, a separate library per profile, automatic backups

🔌 Connections · docs

  • Deezer artwork, Last.fm bios and scrobbling, TheAudioDB, Discord Rich Presence
  • Optional DLNA / UPnP server and MPD server, so the clients you already use can play from or control WaveFlow
  • Your own waveflow-server: its catalogue joins your library, and favourites, ratings and playlists follow you across devices (RFC-005)
  • Everything fetched is cached locally, and an offline mode cuts all network access

🧩 Plugins · docs · RFC-002

  • Sandboxed WebAssembly plugins with permissions, from an in-app store with verified installs
  • Official plugins: Web Radio (30 000+ stations), Apple Motion Artwork (animated covers) and Release Radar (new releases from your artists)

Tech Stack

  • App — Tauri 2 · Rust · SQLite (sqlx, FTS5) · tokio
  • Frontend — React 19 · TypeScript · Vite · Tailwind CSS 4 · Framer Motion
  • Audio — symphonia + libopus (decoding) · cpal (output) · rubato (resampling) · rtrb (lock-free ring buffer)
  • Metadata & images — lofty · image + fast_image_resize · resvg
  • Plugins — wasmtime + WASI p2
  • Toolchain — Bun

Getting Started

Requires Bun, Rust and the platform dependencies listed in CONTRIBUTING.md.

# Install dependencies
bun install

# Run the desktop app in development mode
bun run tauri dev

# Build for production
bun run tauri build

Development Commands

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/:

Community

English and French both welcome.

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 <https://www.gnu.org/licenses/>.

See LICENSE for the full text. Third-party notices are listed in THIRD_PARTY_NOTICES.md.