A standalone audio node for Discord bots, built in Go, with frame-accurate timing and two-deck mixing.
Why · Features · Quick start · Configuration · API · Timing · Mixing · Architecture
Cadence is the audio node behind greed. It joins Discord voice channels, streams music, mixes tracks DJ-style, and tells your bot exactly when each sound reached Discord, so synced lyrics stay synced. If you've used Lavalink, the model will feel familiar: your bot does the thinking, Cadence does the audio, and they talk over REST and a WebSocket.
We ran Lavalink, and then our own fork of it, in production for a long time. Cadence exists because of what that taught us:
| Problem we kept hitting | What it cost | How Cadence handles it |
|---|---|---|
Timing was measured in the wrong place. Lavalink's position is where the decoder is, about 400 ms ahead of the network. TrackStart fires before the stream is even fetched. Updates arrive every 5 s, and position ignores speed filters. |
Live lyrics drifted by an unpredictable amount on every song | A wire clock: every position is stamped when the packet leaves the socket, plus a dedicated TrackAudibleEvent |
| One track per player. Crossfading isn't possible (lavalink#1093), so we forked the JVM node | A fork patched into upstream seams, with bugs at every seam | Two decks built in from the start: armed crossfades, bass swap, filter sweeps, tempo matching |
| The voice connection disposed an encoder it didn't own. The fork handed each player's long-lived mixer to Koe as the connection's sender, and Koe disposes its sender on re-assignment and on close, freeing the mixer's Opus encoder mid-playback | Silent audio, twice ("changing the region fixes it"), fleet-wide after a restart | Each voice connection owns its encoder, sender and DAVE session, and they die together |
| An unbounded analysis queue | Out-of-memory crash that broke YouTube playback for 16 days | Every queue, cache and backlog is bounded and observable |
Silent failures. Koe drops frames inside a catch with no log |
Hours of debugging with no trail | Every dropped frame, stall and failure becomes an event, a log line and a metric |
| DAVE send stalls of 100–400 ms about once a second (lavalink#1222) | Audible dropouts on a node that looked idle | A paced, OS-thread-locked send loop that reports any lateness as a SendStallEvent |
| JVM footprint: a 12 GB heap for a music node | A big box per region | A single static Go binary |
| Fixed encoder bitrate. Lavalink's binding has no bitrate setter | Boosted channels couldn't use their extra bandwidth | Per-connection bitrate (16–384 kbps) set from the channel |
- 🎧 Discord voice done properly: gateway v8,
seq_ackresume, AES-256-GCM / XChaCha20 transport, and DAVE end-to-end encryption through Discord's ownlibdave - ⏱️ Wire clock: frame-accurate positions measured at the socket, correct under every speed and tempo filter, with clock-sync and playout-delay support
- 🎚️ Two-deck mixer: pre-buffered deck B, beat-aligned armed crossfades, equal-power or linear curves, bass swap, high-pass sweeps, loudness matching, tempo ramps
- 🔍 Smart sources: Deezer playback with SoundCloud as a fallback, and Spotify and Apple Music links and search mirrored to the exact recording by ISRC
- 🧠 Track analysis: BPM, meter, downbeats, phrase grid, Camelot key, sections, vocals, intro and outro regions, and EBU R128 loudness, compatible with greed's automix fingerprints
- 🎛️ Filters: 15-band equalizer, timescale (speed, pitch, rate), karaoke, low-pass, tremolo, vibrato, rotation and reverb, all of which glide into a new setting instead of jumping
- 🔁 Session resume: players keep running while your bot reconnects, and missed events are replayed
- 📈 Observability: Prometheus
/metrics, structured JSON logs, typed failures with severities - 🛡️ Safe defaults: no default password, constant-time auth, per-source proxies with automatic direct fallback
cp .env.example .env
docker build -t cadence .
docker run --env-file .env -p 2333:2333 cadenceThe image includes libopus and Discord's libdave, so voice works out of the box.
Production builds need Linux, cgo, libopus and libdave:
sh libdave_install.sh v1.1.0
export PKG_CONFIG_PATH=$HOME/.local/lib/pkgconfig
go build -tags native,nolibopusfile -o cadence ./cmd/cadence
CADENCE_PASSWORD=change-me ./cadenceGet libdave_install.sh from godave.
A build without the native tag runs anywhere and passes every test, but it has no voice. Cadence refuses to start that way unless CADENCE_ALLOW_NO_VOICE=true is set, which is useful for developing search or analysis on Windows or macOS.
go test ./...Everything is set through environment variables. See .env.example.
| Variable | Default | Description |
|---|---|---|
CADENCE_PASSWORD |
required | Shared secret for every request. youshallnotpass is refused. |
CADENCE_ADDRESS |
0.0.0.0:2333 |
Listen address |
CADENCE_BUFFER_MS |
10000 |
Decoded audio buffered per deck (1 000–60 000) |
CADENCE_BITRATE |
96000 |
Default Opus bitrate when the bot doesn't send one |
CADENCE_PLAYOUT_DELAY_MS |
0 |
Measured delay from Discord receiving audio to listeners hearing it, added to audibleAt |
CADENCE_PAUSE_FADE_MS |
0 |
Fade out on pause and back in on resume (0–2000). 0 pauses instantly |
CADENCE_RESUME_TIMEOUT_SECONDS |
300 |
How long players survive a disconnected client (when resuming is enabled) |
CADENCE_UPDATE_INTERVAL_MS |
1000 |
playerUpdate cadence while playing (min 250) |
CADENCE_SEARCH_ORDER |
applemusic,spotify,deezer |
What plain-text searches query, in order |
CADENCE_ANALYSIS_WORKERS / _QUEUE |
2 / 32 |
Offline analysis concurrency and queue bound |
CADENCE_LOG_LEVEL |
info |
debug, info, warn or error |
CADENCE_AUDIO_CACHE_DIR |
off | Directory for the disk audio cache. Unset disables it |
CADENCE_AUDIO_CACHE_GB |
20 |
Disk cache size cap (1–1000). Least recently played tracks are removed first |
CADENCE_NORMALIZE |
true |
Level every track to the same loudness, from its analysis |
CADENCE_NORMALIZE_LUFS |
-14 |
Loudness target for levelling (−30 to −5) |
CADENCE_STATE_FILE |
off | Where to save sessions on shutdown so a restart resumes playback where it stopped |
DEEZER_ARL |
Deezer account session for full-length streams. List several, comma-separated, and a rejected or refusing account is skipped for the next | |
DEEZER_ARL_ROTATION |
failover |
Which listed account each stream starts with: failover (first working one), round-robin or random. The others stay as fallbacks |
DEEZER_MASTER_KEY |
16-byte key for Deezer's BF_CBC_STRIPE stream cipher. Without it nothing plays |
|
DEEZER_HIGH_QUALITY |
true |
Prefer 128 kbps MP3 over 64 kbps |
SPOTIFY_CLIENT_ID / _SECRET |
Spotify Web API credentials (metadata only) | |
APPLE_MUSIC_TOKEN |
scraped | Optional fixed developer token |
APPLE_MUSIC_STOREFRONT |
us |
Catalog storefront |
SOUNDCLOUD_ENABLED |
true |
Use SoundCloud when Deezer has no match |
SOUNDCLOUD_CLIENT_ID |
scraped | Optional fixed SoundCloud client id |
DEEZER_PROXY, SPOTIFY_PROXY, APPLE_MUSIC_PROXY, SOUNDCLOUD_PROXY |
Per-source HTTP proxy; a failed proxy falls back to direct for 60 s |
| Source | Search prefix | Links | Plays audio |
|---|---|---|---|
| Deezer | dzsearch: / dzisrc: |
tracks, albums, playlists, artists, short links | ✅ |
| Apple Music | amsearch: |
songs, albums, playlists, artists | Mirrored to Deezer |
| Spotify | spsearch: |
tracks, albums, playlists, spotify: URIs, short links |
Mirrored to Deezer |
| SoundCloud | scsearch: |
tracks, sets, short links | ✅ fallback, used only when Deezer has no match |
How mirroring works. When a Spotify or Apple track plays, Cadence takes its ISRC, the unique ID of a recording, and looks up that exact recording on Deezer. If there's no ISRC match, it falls back to a scored text search. That search penalizes remixes, live versions, sped-up versions and anything else that differs from what was requested, and rejects candidates whose length is off by more than 5 seconds. Matches are cached for 14 days and concurrent lookups are de-duplicated, so a song is resolved once.
Spotify playlists load up to 1,000 tracks. Spotify only serves public, user-made playlists to third-party apps, so its own editorial and personalised playlists (Today's Top Hits, Discover Weekly, Daily Mix) and private playlists return "not found".
Encoded tracks are plain base64url JSON, so any Cadence node can play any track, no matter which node resolved it.
All routes require Authorization: <CADENCE_PASSWORD>. The shape follows Lavalink v4 closely, under /v1.
Drop-in Lavalink v4. Cadence also speaks Lavalink's own v4 protocol (/v4/websocket, /v4/loadtracks, /v4/sessions/…, /version), so an existing bot using a Lavalink client such as lavalink-client can point at Cadence without code changes. On v4 connections only Lavalink's standard events are sent. To also receive Cadence's extras (TrackAudibleEvent, mix events, stalls), send PATCH /v4/sessions/{id} {"cadenceEvents": true} after checking that /v4/info reports "wireClock": true.
GET /v1/websocket with headers User-Id (your bot's ID) and Client-Name. To resume a session, also send Session-Id.
{ "op": "ready", "sessionId": "8e1f0c2a9b7d4e61", "resumed": false }| Op | When |
|---|---|
ready |
Right after connecting |
playerUpdate |
Every CADENCE_UPDATE_INTERVAL_MS while playing, and immediately after every event |
event |
See Events |
| Method | Route | Description |
|---|---|---|
GET |
/v1/info |
Version, sources, filters, and whether DAVE is available |
GET |
/v1/stats |
Players, sessions, uptime, analysis queue |
GET |
/v1/clock |
Node time, for clock sync |
GET |
/metrics |
Prometheus exposition |
GET |
/v1/loadtracks?identifier= |
Resolve a link, a prefixed search, an ISRC or plain text |
GET |
/v1/decodetrack?encodedTrack= |
Decode one track |
POST |
/v1/decodetracks |
Decode many tracks |
POST |
/v1/prefetch (also /v4/prefetch) |
{ "tracks": ["…"] } (up to 10). Preload the start of upcoming tracks so they play instantly |
PATCH |
/v1/sessions/{session} |
{ "resuming": true, "timeout": 300 } |
GET |
/v1/sessions/{session}/players |
All players |
GET / PATCH / DELETE |
/v1/sessions/{session}/players/{guild} |
Read, update or destroy a player |
POST |
…/players/{guild}/mix/deckb |
Pre-load the incoming track |
POST |
…/players/{guild}/mix/crossfade |
Start or arm a transition |
DELETE |
…/players/{guild}/mix |
Cancel an armed transition |
GET |
/v1/mix/analysis/{source}/{identifier} |
A finished fingerprint |
POST |
/v1/mix/analyze |
Queue offline analysis of a track |
PATCH /v1/sessions/{session}/players/{guild}?noReplace=false
{
"track": { "encoded": "eyJzb3VyY2UiOiJkZWV6ZXIi..." },
"position": 0,
"paused": false,
"volume": 100,
"filters": { "timescale": { "speed": 1.1, "pitch": 1, "rate": 1 } },
"voice": { "token": "…", "endpoint": "c-dfw09.discord.media:443", "sessionId": "…", "channelId": "…", "bitrate": 128000 },
"analyze": true
}Send "track": { "encoded": null } to stop. Two more fields work on both /v1 and /v4: "bitrate": 128000 sets the Opus bitrate (16–384 kbps) and is remembered across voice updates, and "nextTrack": { "encoded": "…" } preloads the next track so it starts on the exact frame the current one ends ({ "encoded": null } clears it). The voice and track updates can arrive in any order. A track sent before voice simply waits, without its clock moving.
filters takes Lavalink's shapes (equalizer, timescale, karaoke, lowPass, tremolo, vibrato, rotation) plus one of Cadence's own:
"filters": { "reverb": { "mix": 0.3, "room": 0.85, "damping": 0.4 } }reverb is a Freeverb (8 combs and 4 all-passes per channel, tuned for 48 kHz); every value is 0–1. It is listed in /v4/info filters, so lavalink-client passes it through unchanged.
Changes are smooth. A new filters value never switches on the next frame. Equalizer gains, pitch and speed glide to their targets (about 0.5 s), and effects that turn on or off crossfade in and out, keeping their last settings while they fade. Nightcore sweeps up instead of snapping, and toggling reverb never clicks.
Every event carries guildId, the track, and an instance counter, so your bot can ignore events from a track it has already replaced.
| Event | Meaning |
|---|---|
TrackLoadingEvent |
Accepted, now resolving (mirror lookup, stream URL) |
TrackStartEvent |
Decoding has begun |
TrackAudibleEvent |
The first packet left the socket. Carries positionMs, sentAt and audibleAt. Anchor lyrics here. |
TrackEndEvent |
reason: finished, loadFailed, stopped, replaced or cleanup |
TrackExceptionEvent |
exception{severity, message, cause, source}, where severity is common, suspicious or fault |
TrackStuckEvent |
No audio for 10 s while not finished |
MixArmedEvent / MixStartedEvent / MixPromotedEvent / MixDroppedEvent |
The crossfade lifecycle |
SendStallEvent |
The send loop fell behind schedule by stallMs |
PositionEvent |
A seek moved the clock |
WebSocketClosedEvent |
The voice gateway closed (code, reason, terminal) |
Cadence's main promise is that "position" means what listeners hear, not where the decoder happens to be.
decode ─► resample ─► time-stretch ─► effects ─► mix ─► opus ─► DAVE ─► AEAD ─► UDP
│
position + sentAt stamped here
-
The sender pulls one 20 ms frame per tick and writes it straight to the socket. There's no queue after it to drift.
-
Every frame carries its exact source position through resampling and time-stretching, so positions stay correct under nightcore, vaporwave or an automix tempo ramp.
-
playerUpdate.state.playerincludes an anchor (anchorMs,anchorSentAt,anchorAudibleAt,rate,sounding). Compute the live position as:position = anchorMs + (clientNow - offset - anchorSentAt) * rateoffsetcomes from an NTP-style exchange withGET /v1/clock. -
Set
CADENCE_PLAYOUT_DELAY_MSto the measured gap between Discord receiving audio and listeners hearing it. This one constant replaces the variable error we used to live with.
Like Spotify, Cadence keeps the first ~12 seconds of upcoming tracks ready, so pressing play doesn't wait on Deezer.
loadtrackspreloads its first result, so the usual "search, then play" flow starts from memory.- Send the next tracks in your queue to
POST /v1/prefetchand they'll start just as fast. - On play, a preloaded track starts decoding immediately while the rest is fetched in the background. A track that wasn't preloaded plays the normal way.
cadence_prefetch_total{outcome}on/metricscountsqueued,hit,miss,failedanddropped.- Disk cache. With
CADENCE_AUDIO_CACHE_DIRset, a track played a second time within 7 days, in any server, is saved to disk as it plays. From then on it starts and seeks with no Deezer requests at all. Only complete downloads are kept, and the cache never grows pastCADENCE_AUDIO_CACHE_GB. Seecadence_audio_cache_total{outcome},cadence_audio_cache_bytesandcadence_audio_cache_files. - Seeks of 10 seconds or more fetch from the target with one range request, or read the disk cache with none, and stay frame-accurate.
cadence_seek_total{outcome}countsrange,diskandfallback(a full stream, for a track whose layout cannot be proven).cadence_cdn_range_ignored_totalcounts range requests the CDN answered with the whole file. - Fallback source.
cadence_fallback_total{kind}counts searches (search) and Spotify/Apple mirrors (mirror) that SoundCloud answered because Deezer had nothing.
deck A ─► bass / sweep DSP ─┐
├─► equal-power crossfade ─► volume ─► out
deck B ─► bass / sweep DSP ─┘ (armed at a downbeat on deck A)
POST …/mix/deckbloads and pre-buffers the next track, starting from any position (for example, past its intro).POST …/mix/crossfadewithatPositionMsarms the transition. It starts on the exact frame where deck A crosses that cue.- A
profiledescribes the transition:bassSwapAt,bassSwapRamp, and high-pass sweeps on either deck.tempoRatiobeat-matches deck B, which then glides back to its natural speed over 11 s.gainRatiomatches loudness. - When the fade completes, deck B is promoted and
MixPromotedEvent,TrackEndEvent{replaced}andTrackStartEventare emitted.
The node makes no musical decisions. The planner in your bot chooses what to mix and how, and Cadence executes it to the frame.
- Voice gateway v8 with
seq_ackheartbeats and resume. Reconnects use exponential backoff and resume when they can, so audio keeps flowing through gateway blips. - DAVE through
libdave, including MLS commits, welcomes, proposals and protocol transitions. When a call negotiates E2EE, audio is held, never sent unencrypted, until the epoch is ready; a hold that lasts 15 s restarts the voice session. Calls Discord runs without E2EE (DAVE protocol 0) play straight away. - Transport encryption is
aead_aes256_gcm_rtpsize, falling back toaead_xchacha20_poly1305_rtpsize. The deprecated modes are never offered. - One Opus encoder, sender, UDP socket and DAVE session per connection, torn down together. A voice update with the same session is ignored. A new one closes the old connection and waits for its sender to exit before dialing.
cmd/cadence entry point, wiring, graceful shutdown
internal/api REST + WebSocket server
internal/session client sessions, resume, per-guild players and voice
internal/player decks, crossfades, events, the wire clock
internal/voice Discord voice gateway, DAVE, UDP, RTP, AEAD, send loop
internal/audio PCM format, resampler, WSOLA stretcher, biquads, deck DSP
internal/codec Opus encoder (libopus), MP3 / PCM decoders
internal/source track model, resolver, mirroring, match scoring
internal/source/* deezer, soundcloud, spotify, applemusic
internal/lavalink Lavalink v4 protocol compatibility
internal/analysis tempo, key, meter, phrases, structure, loudness, vocals
internal/httpx per-source HTTP clients with proxy failover and dead-connection retry
internal/cache bounded TTL LRU
internal/audiocache bounded on-disk cache of repeat-played tracks
internal/config environment configuration
internal/metrics Prometheus exposition
Cadence is in production. It is greed's only audio node, running on two servers (Dallas, US and Germany, EU), with greed routing each guild to the node nearest its voice region and failing over to the other if one goes down. The native (libopus + libdave) build plays to Discord voice with DAVE end-to-end encryption, driven by greed over the Lavalink v4 protocol. Everything above is covered by unit tests: the audio maths, filters and their ramps, reverb, analysis, voice protocol framing, player lifecycle, resolver and API. Still to do:
- Measure
CADENCE_PLAYOUT_DELAY_MSagainst a recorded client. - Move greed's client from Lavalink v4 to the
/v1protocol.
Cadence is released under the MIT License. © 2026 greed.
Cadence builds on godave and Discord's libdave (Apache-2.0 / MIT), hraban/opus (MIT), go-mp3 (Apache-2.0) and coder/websocket (ISC). The voice protocol work was cross-checked against disgo.