WaveFlow Server

Your music, everywhere you listen.
A self-hosted music server in one Rust binary — with a web player built in, and the OpenSubsonic API your apps already speak.

Point WaveFlow Server at the folders where your music lives. It builds your library, streams it to your browser, your phone and your desktop, and converts on the fly when the connection is tight.
No PostgreSQL, no Redis, no identity provider: one binary, one database file, one key file.
Your files. Your server. Every player.

Install  ·  Features  ·  Screenshots  ·  Apps  ·  Documentation  ·  Develop

_{The web player · your library, with mixes made from what you actually listen to}

---

Why WaveFlow Server

📦 Up in a minute	One container, on a server, a NAS or a Raspberry Pi 4 or 5. The catalogue lives in a single SQLite file, kept with its key: back up the two together, with the artwork, canvas and podcast folders beside them, as the operations guide explains.
📱 Your apps already work	Subsonic players connect as they are, with no plugin. Each release is run against Symfonium, Feishin, DSub and Juliet, and the results are published.
🌐 A player in the browser	No app to install: open the server's address and listen, on a desktop or a phone, and keep tracks for when you are offline.
🔁 Nothing moves under you	Album and artist IDs are derived from your tags, so rebuilding the catalogue gives the same IDs back: the links and references your apps hold keep working.
🔍 Knows what your files really are	The audio of every lossless file is measured, and a FLAC that was once an MP3 is shown for what it is.
🛡️ Yours, and only yours	Your audio files are never rewritten. Nothing leaves the server unless you switch it on, and every outbound request is listed.

Features

🎧 Listening

• A complete web player compiled into the server: albums, artists, songs, genres, folders, search as you type, queue, history and favourites.
• Mixes made from your own listening, listening statistics, and similar songs drawn from your library.
• Synced lyrics from the files or their .lrc, with a full-screen immersive view; LRCLIB fills the gaps once you switch it on.
• Streams the original, or converts on the fly to MP3, Opus or AAC, with seeking inside a conversion and server-side volume levelling (ReplayGain).
• Offline listening for the tracks you keep, installable as an app on a phone, keyboard shortcuts, media keys and lock-screen controls.
• 14 themes, light and dark, in nine languages: English, French, German, Spanish, Italian, Japanese, Korean, and Simplified and Traditional Chinese.

📚 Your library

• Scans quickly and keeps up: only what changed is read again, one damaged folder does not stop the rest, and a watcher picks up new files as they land.
• Tags or folders: browse by album and artist, or by the folders on your disk.
• Thirteen credit roles (composer, producer, featured artist…), and a joined credit like Artist A, Artist B split into two artists when you decide it should be.
• Missing files keep their data: favourites, ratings and plays wait for the file to come back. A purge can be undone for a week.
• Uploads: a library can accept files sent from a client.

✨ Discovery

• Artist pages with biographies and similar artists from Last.fm, portraits from Deezer and fanart banners from TheAudioDB, once you opt in.
• Choose the portrait and the banner yourself, or let the server find a banner.
• Smart playlists that fill themselves from rules, internet radio and podcasts.

📋 Playlists and sharing

• Playlists with repeats, public playlists for the other accounts, and .m3u import and export.
• Share links that open a player page in any browser, with an optional expiry and visit limit.
• Scrobbling to ListenBrainz, Last.fm and Maloja, through a durable queue that survives restarts and retries a service that is down.

🔒 Accounts and safety

• Several accounts, each seeing only the libraries it belongs to.
• Argon2id passwords, tokens stored only as hashes, the Subsonic password encrypted with a local key, and sign-in protected against guessing.
• A one-time token guards the first-run setup, so a stranger cannot claim a fresh server.
• Backups: waveflow-server database backup copies the database and its key together, and the server makes a copy of both before every upgrade.

Screenshots

Artist · a portrait and a banner, chosen or found	Now playing · with what is actually being streamed
Album · in one of the light themes	Statistics · counted from your own plays
Quality · every lossless file measured, not taken at its word

Install

You need FFmpeg and ffprobe, on PATH or beside the waveflow-server executable (already in the Docker image). Nothing else: no database server, no cache, no broker.

Docker

docker run -d --name waveflow \
  -p 4533:4533 \
  -v waveflow-data:/data \
  -v /path/to/music:/music:ro \
  ghcr.io/instazdll/waveflow-server:2.0.1

The image is built for linux/amd64 and linux/arm64 (a Raspberry Pi 4 or 5 on a 64-bit system) and published under the same tags on both registries:

Registry	Image
GitHub Container Registry	ghcr.io/instazdll/waveflow-server
Docker Hub	docker.io/instazdll/waveflow-server

Each release is tagged with its version, and latest follows the latest stable release.

On Fedora, RHEL and other systems where SELinux is enforcing, Podman refuses the container your music folder until it is labelled for containers: mount it as /path/to/music:/music:ro,z. The operations guide says what that changes on the host.

With Compose, set WAVEFLOW_MUSIC_PATH to your music folder, which is mounted read-only:

WAVEFLOW_MUSIC_PATH=/path/to/music docker compose up -d

To reach it from outside your home over HTTPS, packaging/caddy/ runs the same server behind Caddy, which obtains and renews the certificate itself; the operations guide explains it, including how to move a server already started with the file above without starting over on an empty volume.

First steps

Open http://your-host:4533. The setup screen creates the administrator account; it asks for the one-time token the server wrote in its data directory:

docker exec waveflow cat /data/setup-token

Then add your music under that account (admin below), and the first scan starts on its own:

docker exec waveflow waveflow-server library add --owner admin --name Music --path /music

From the command line instead of the browser

docker exec -e WAVEFLOW_ACCOUNT_PASSWORD='at-least-twelve-characters' \
  waveflow waveflow-server account create-admin --username admin

Connect a Subsonic app

Subsonic apps use a dedicated password, separate from the web one:

docker exec -e WAVEFLOW_SUBSONIC_PASSWORD='a-different-app-password' \
  waveflow waveflow-server credential set --actor admin --username admin

On your own network, point your app at http://your-host:4533 with that username and password. The server speaks plain HTTP, and Subsonic apps send their credentials with every request: -p 4533:4533 above publishes it on every interface of the host, which suits a network you trust and nothing wider. To listen from outside, put it behind a reverse proxy that terminates TLS, give your apps its https:// address, and set WAVEFLOW_PUBLIC_URL to it. The operations guide says how to publish the port when a proxy sits in front, and has the rest, including backups and the instance key.

From source

Requires Rust 1.98+ and bun.

bun --cwd=webapp install
bun run build              # the web player first, then the server: the order matters

export WAVEFLOW_ACCOUNT_PASSWORD='at-least-twelve-characters'
cargo run -- account create-admin --username admin
cargo run -- library add --owner admin --name Music --path /path/to/music
cargo run

Works with your apps

Each release is checked against real clients, and every result is read back from the server rather than from what the app displayed. The last run was on 2026-10-27 and 2026-10-28:

App	Tested on	What it was seen doing
Symfonium	Android	Browse, seek in every format, favourites, ratings, bookmarks, lyrics
Feishin	Windows desktop	Browse, folders, synced lyrics, radio, playlists
DSub	Android	Folders, podcasts, play queue, playlists, sharing
Juliet	iPhone	Browse, transcoding, play queue, playlists
WaveFlow Desktop	Windows, macOS, Linux	Syncs your library and listening across devices, through the native API

What each app does and does not use, and where an app has a limitation of its own, is in the compatibility matrix.

Documentation

For	Read
Run it	Operations: setup, backups, the instance key, reverse proxies, optional features · Privacy: every host the server can contact
Build a client	Native API v2 · Subsonic / OpenSubsonic · the interactive reference at /reference on any server
What changed	CHANGELOG
Everything else	The documentation index: the compatibility matrix, the design RFCs, the plans

How it works

Principle	What it means
One process	src/main.rs loads the settings and serves; everything else sits behind app() in src/app/router.rs, so the test suite drives the very router main serves
One database	SQLite in WAL mode with foreign keys and a single writer. Migrations are dated, embedded at compile time and checksummed
One catalogue, three surfaces	The native API, the Subsonic API and the web player call the same domain services, so they cannot drift apart
Privacy in the query	Access is checked inside the SQL, through library membership. Something missing and something belonging to another account answer the same 404
Read-only files	The scanner and every tag operation leave your audio files untouched

Built with axum, SQLite through sqlx, FFmpeg, lofty, React 19 and Vite, compiled into the binary with rust-embed. RFC-002 is the design.

Development

cargo fmt --all --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features          # hermetic: temporary SQLite databases, no service to start

bun --cwd=webapp run test
bun --cwd=webapp x playwright install chromium
bun --cwd=webapp run test:e2e

FFmpeg and ffprobe must be on PATH, since the suite drives a real media service. Commits need a DCO sign-off (git commit -s) and a Conventional Commit message. CONTRIBUTING.md has the rest, and CLAUDE.md the conventions in depth.

Community

• 🐛 Bug? → Bug report
• ✨ Idea? → Feature request
• 🔒 Security? → Private disclosure, never a public issue.

English and French are both welcome.

Related

• WaveFlow: the desktop player, which syncs with this server.
• WaveFlow QuickPlay: a tiny player for the file in front of you.

License

WaveFlow Server is licensed under AGPL-3.0-only: it runs as a network service, so anyone you serve it to is entitled to its source. The desktop application and waveflow-core are GPL-3.0-only.

The WaveFlow logo, its favicons and app icons come unchanged from the logo kit kept with the desktop application under design/logo/, whose usage guide governs them. The wordmark is Inter SemiBold converted to outlines; Inter is under the SIL Open Font License 1.1, which permits its use in a logo.

The screenshots show albums and artist photos from the maintainer's own library, used for illustration only.