A standalone audio node for Discord bots, written in Rust, with frame-accurate timing and two-deck mixing.
📚 Documentation • 🚀 Quick start • ⚙️ Configuration • 🧩 Plugins • 🇫🇷 Français
Wavyzon joins Discord voice channels, streams and mixes music, and tells your bot exactly when each sound reached Discord, so synced lyrics stay synced. If you've used Lavalink, the model is familiar: your bot does the thinking, Wavyzon does the audio, and they talk over REST and a WebSocket. It even speaks Lavalink's v4 protocol, so your existing bot can switch by changing the node address.
Wavyzon is a Rust rewrite of Cadence, the Go audio node behind greed, by the iHorizon team.
| Problem | With a classic Lavalink node | With Wavyzon |
|---|---|---|
| Timing measured in the wrong place | Position is where the decoder is, ~400 ms ahead of the network; TrackStart fires before the stream is fetched; updates every 5 s; speed filters ignored |
A wire clock: every position is stamped when the packet leaves the socket, plus a dedicated TrackAudibleEvent |
| One track per player | No real crossfades (lavalink#1093) | Two decks built in: armed crossfades, bass swap, filter sweeps, tempo matching, gapless |
| Silent failures | Dropped frames and stalls vanish | Every drop, stall and failure is an event, a log line and a metric |
| Unbounded queues | Memory grows until it crashes | Every queue, cache and backlog is bounded and observable |
| Heavy runtime | A JVM with a multi-GB heap | One static Rust binary; Opus linked statically, DAVE in pure Rust |
| Extending means forking | JVM plugins tied to Lavalink internals | A small, typed plugin API for sources, filters, events and routes |
- Voice gateway v8 with
seq_ackheartbeats and resume, exponential backoff - AES-256-GCM / XChaCha20-Poly1305 transport encryption
- DAVE end-to-end encryption through the pure-Rust
daveycrate: audio is held, never sent unencrypted - Per-connection Opus bitrate (16–384 kbps), set from the channel
- Frame-accurate positions measured at the UDP socket
- Correct under every speed and tempo filter, through crossfades and seeks
- Clock sync (
/v1/clock) and playout-delay compensation for synced lyrics
- Pre-buffered deck B, crossfades armed on the exact frame of a cue
- Equal-power or linear curves, bass swap, high-pass sweeps, loudness and tempo matching
- Gapless
nextTrackwith an automatic 3 s crossfade (configurable), DJ voice-overs with ducking
- SoundCloud search, links and playback
- Lyrics from Genius, LRCLIB (synced, timed lines) and lyrics.ovh, in the order you choose (
WAVYZON_LYRICS_ORDER), through Lavalink's LavaLyrics API - Deezer search, links and playback (
DEEZER_ARL+DEEZER_MASTER_KEY), Range-based seeking - HTTP: direct MP3 / AAC / M4A / FLAC / Ogg / WAV links and Icecast / Shoutcast radio, Range-based seeking, private addresses blocked by default
- Local files (opt-in, sandboxed in
WAVYZON_LOCAL_ROOT) - Spotify and Apple Music links and search (metadata only), mirrored by ISRC to the exact recording on a playback source
- Instant starts: prefetch, memory and disk caches
- Lavalink's equalizer, timescale, karaoke, low-pass, tremolo, vibrato, rotation, plus reverb
- Every change glides instead of jumping: no clicks
- Plugin filters under
filters.pluginFilters
- Add sources, audio filters, event listeners and HTTP routes in a few lines of Rust
- Compiled in with a cargo feature, enabled with
WAVYZON_PLUGINS, configured withWAVYZON_PLUGIN_<NAME>_<KEY> - A complete, tested example plugin (sine-tone source, bitcrush filter, event counter, stats route)
- Equalizer APO plugin: play through APO configs and presets (parametric EQ, GraphicEQ, convolution, reverb) with
pluginFilters.apo - Flowery TTS plugin: text-to-speech with LavaSrc's
ftts://identifiers, so lavalink-client'ssource: "ftts"works (on by default, no API key) - Genius lyrics plugin: lyrics from Genius, the next provider when Genius has none (on by default;
WAVYZON_PLUGIN_GENIUS_ACCESS_TOKENrecommended)
- Lavalink v4 compatible (
/v4/*), works with lavalink-client, Shoukaku, Wavelink… - Session resume with event replay, state saved across restarts
- Prometheus
/metrics, structured JSON logs, typed failures with severities - Safe defaults: no default password, constant-time auth, SSRF protection, per-source proxies
git clone https://gitlab.com/ihrz/wavyzon.git && cd wavyzon
cp .env.example .env # set WAVYZON_PASSWORD at least
docker compose up -d # listens on 127.0.0.1:2333, data in the wavyzon-data volumeNeeds Rust 1.85+, a C compiler and CMake (libopus is built and linked statically, nothing else to install).
git clone https://gitlab.com/ihrz/wavyzon.git && cd wavyzon
cargo build --release -p wavyzon
WAVYZON_PASSWORD=change-me ./target/release/wavyzoncurl -s -H "Authorization: change-me" http://localhost:2333/v1/info
curl -s -H "Authorization: change-me" "http://localhost:2333/v1/loadtracks?identifier=scsearch:midnight%20city"Then point your bot at localhost:2333 with the same password, as a
Lavalink v4 node or with the native /v1 API. See
Lavalink compatibility for client setup.
Everything is set through environment variables; see .env.example
and the full reference.
| Variable | Default | Description |
|---|---|---|
WAVYZON_PASSWORD |
required | Shared secret for every request. youshallnotpass is refused |
WAVYZON_ADDRESS |
0.0.0.0:2333 |
Listen address |
WAVYZON_PLAYBACK_SOURCES |
deezer,soundcloud |
Where Spotify / Apple Music tracks are mirrored to, in order |
DEEZER_ARL + DEEZER_MASTER_KEY |
Enable Deezer streaming (account ARL cookie and 16-byte stream cipher key) | |
WAVYZON_LYRICS_ORDER |
lrclib,lyricsovh,genius |
Lyrics providers on /v4/lyrics (LavaLyrics API), first answer wins |
LRCLIB_ENABLED, LYRICS_ENABLED |
true |
LRCLIB (synced lyrics) and lyrics.ovh |
WAVYZON_PLUGIN_GENIUS_ACCESS_TOKEN |
Genius Client Access Token (WAVYZON_PLUGIN_GENIUS_ENABLED=false to skip Genius) |
|
WAVYZON_HTTP_ALLOW_PRIVATE |
false |
Let the HTTP source fetch private / local addresses |
WAVYZON_LOCAL_ROOT |
off | Directory the local-file source may read |
WAVYZON_PLUGINS |
all compiled in | Plugins to enable, comma-separated |
WAVYZON_PLUGIN_<NAME>_<KEY> |
Settings for a plugin | |
WAVYZON_BUFFER_MS |
10000 |
Decoded audio buffered per deck |
WAVYZON_BITRATE |
96000 |
Default Opus bitrate |
WAVYZON_PLAYOUT_DELAY_MS |
0 |
Measured Discord-to-ear delay, added to audibleAt |
WAVYZON_CROSSFADE_MS |
3000 |
Automatic crossfade into the nextTrack (0 = strict gapless) |
WAVYZON_AUDIO_CACHE_DIR |
off | Disk cache for repeat-played tracks |
WAVYZON_STATE_FILE |
off | Save sessions on shutdown, resume on start |
WAVYZON_LOG_LEVEL |
info |
debug, info, warn or error |
SPOTIFY_CLIENT_ID / _SECRET |
Spotify Web API credentials (metadata only) |
The full documentation is an mdBook in
docs/ (mdbook serve docs to read it locally).
| Topic | Page |
|---|---|
| 📦 Installation & configuration | Installation · Configuration |
| 🔌 Protocol | REST API · WebSocket & events · Lavalink v4 |
| 🎵 Audio | Wire clock · Mixing · Filters · Sources |
| 🧩 Plugins | Writing plugins · Example plugin |
| 🏗️ Internals & ops | Architecture · Observability · Deployment · Troubleshooting |
| 🔀 Migrating | From Lavalink · From Cadence |
| 🇫🇷 Français | Introduction · Démarrage rapide · Plugins |
crates/wavyzon binary: config, REST + WebSocket (/v1, /v4), sessions, plugin host, metrics
crates/wavyzon-player two decks, crossfades, gapless, filters, events, the wire clock
crates/wavyzon-voice Discord voice gateway v8, UDP/RTP, AEAD, DAVE, the 20 ms send loop
crates/wavyzon-sources SoundCloud, Deezer, HTTP, local, Spotify/Apple metadata, mirroring, caches
crates/wavyzon-analysis tempo, key, phrases, sections, vocals, loudness fingerprints
crates/wavyzon-audio PCM format, DSP, Symphonia decoding, Opus encoding
crates/wavyzon-plugin the plugin API and shared data model
crates/wavyzon-testkit fake voice gateway, mock sources, audio assertions
plugins/* plugins built with the workspace
| Resource | Link |
|---|---|
| 🦊 GitLab (main) | gitlab.com/ihrz/wavyzon |
| 🐙 GitHub (mirror) | github.com/ihrz/wavyzon |
| 📝 Changelog | CHANGELOG.md · Français |
| 🤝 Contributing | CONTRIBUTING.md |
| 🛡️ Security | SECURITY.md |
| 💬 iHorizon Discord | discord.ihorizon.org |
- Anaïs Saraiva and the iHorizon team, authors of Wavyzon.
- Cadence by greed (MIT): Wavyzon's
design, protocol and behaviour come from Cadence, and parts were translated
from its source. Its license notice is reproduced in
NOTICE. - Lavalink, whose protocol Wavyzon speaks.
- Built on tokio, axum, Symphonia, libopus via audiopus, davey, RustCrypto AEADs, reqwest, tokio-tungstenite, serde and tracing.
Wavyzon is © 2026 Anaïs Saraiva and the iHorizon team, distributed under
CC BY-NC-SA 4.0
(see LICENSE). Portions derived from Cadence remain under the
MIT terms reproduced in NOTICE.
✔️ Share: copy and redistribute the material
✔️ Adapt: remix, transform and build upon the material, plugins included
❌ Attribution: you must credit the work and indicate changes
❌ Non-Commercial: no commercial use
❌ Share Alike: modifications must keep the same license
❌ No additional restrictions: no legal or technological measures that restrict others
🚨 Zero tolerance for hate towards contributors, of any kind or level.
🌈 Inclusivity: Wavyzon is open and welcoming to everyone, whatever their origin, gender identity, sexual orientation or any other characteristic.
See CODE_OF_CONDUCT.md.
Developed with ❤️ by Anaïs Saraiva and the iHorizon team