Skip to content
ihrzPublic

About

A standalone audio node for Discord bots, written in Rust, with frame-accurate timing and two-deck mixing.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

40 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Wavyzon: a standalone audio node for Discord bots, written in Rust

A standalone audio node for Discord bots, written in Rust, with frame-accurate timing and two-deck mixing.


Rust Discord Voice DAVE Lavalink v4 License
GitLab Pipeline Coverage GitHub mirror

📚 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.

💡 Why Wavyzon?

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

✨ Features

🎧 Discord voice done properly

  • Voice gateway v8 with seq_ack heartbeats and resume, exponential backoff
  • AES-256-GCM / XChaCha20-Poly1305 transport encryption
  • DAVE end-to-end encryption through the pure-Rust davey crate: audio is held, never sent unencrypted
  • Per-connection Opus bitrate (16–384 kbps), set from the channel

⏱️ Wire clock

  • 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

🎚️ Two-deck mixer

  • 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 nextTrack with an automatic 3 s crossfade (configurable), DJ voice-overs with ducking

🔍 Sources

  • 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

🎛️ Filters

  • 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

🧩 Plugin API

  • 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 with WAVYZON_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's source: "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_TOKEN recommended)

🔁 Operations

  • 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

🚀 Quick start

🐳 Docker (recommended)

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 volume

🦀 From source

Needs 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/wavyzon

✅ Check it

curl -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.

⚙️ Configuration

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)

📚 Documentation

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

🏗️ Architecture

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

🔗 Resources & Links

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

🏆 Credits

📄 License & Terms of Use

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.

✅ Permitted

✔️ Share: copy and redistribute the material
✔️ Adapt: remix, transform and build upon the material, plugins included

❌ Restrictions

❌ 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


⚠️ Code of Conduct

🚨 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.


🎉 Thank you for using Wavyzon

Developed with ❤️ by Anaïs Saraiva and the iHorizon team

Made with Rust Powered by tokio Decoded by Symphonia

About

A standalone audio node for Discord bots, written in Rust, with frame-accurate timing and two-deck mixing.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Contributors

Languages