Playback
should survive.

Every track carries its own fallback chain.

When someone pastes a link, Melodix has to turn that web page into an audio stream it can pipe into a voice channel. The component that does this is called a parser, and YouTube fights it constantly, reshuffling its internals every few weeks. So Melodix keeps a chain of them, ordered fastest-first, and works down the list until one returns a playable stream. The panel beside it is that chain running: the embed your users see, and the log underneath it. Click a parser to see what it does.

SoundCloud has its own parser, scnative, built on SoundCloud's api-v2. Internet-radio URLs skip straight to ffmpeg, since there is nothing to extract.

A dropped connection should not end the song.

The chain decides which parser plays a track. The more common failure is different: the track was playing fine, and then the network moved. That is handled in three steps, cheapest first.

1. Read aheadPlayback runs from a buffer, not straight off the socket, so a stall underneath is absorbed instead of heard. The buffer does not pre-fill, so playback still starts immediately.
2. Repair in placeWhen the connection is cut, Melodix asks the server for the next byte it had not yet received and carries on. Nothing already downloaded is fetched twice.
3. Reopen, then switchIf the source is genuinely gone, the same parser reopens at the position it had reached. Only when that fails too does the chain move on.

Discord is covered the same way: a voice reconnect or a gateway drop rejoins and resumes without losing the queue, and the buffer keeps playing while it happens. Queues survive restarts.

The bot you invited can be taken away.

Public music bots are a single point of failure you do not control. Groovy and Rythm were shut down in 2021 at YouTube's request, taking every server's setup with them, and the survivors have added listener caps, queue limits and premium tiers since. Melodix runs under your Discord application, on a machine you already have, with no account to sign up for and nothing phoning home. Nobody can revoke it, meter it, or decide that skipping tracks is now a paid feature.

The trade is real: you are the one keeping it online. That means a machine that stays on, a token you keep secret, and an occasional update when YouTube changes something. In exchange the bot is yours, and it does not disappear.

Unzip, paste a token, run.

# token from the Discord Developer Portal
  $ unzip melodix-linux-amd64.zip && cd melodix-linux-amd64
  $ nano .env   # DISCORD_TOKEN=…
  $ ./melodix-discord

# Go 1.26 or newer
  $ go build -o melodix-discord ./cmd/discord
  $ DISCORD_TOKEN=your-token ./melodix-discord

The same bundle carries melodix-cli, a terminal player for your own speakers that needs no Discord account. Full setup — bot creation, invite link, every config knob, Docker — lives in docs/running.md.

What you need

required

A Discord bot token and a machine that stays online. One binary, no database server: state is a folder you pick. A small VPS or a Raspberry Pi is plenty, since YouTube playback does no transcoding.

ffmpeg · optional

Only for SoundCloud and internet radio. YouTube's Opus formats go to Discord unchanged, so the common path never touches it.

yt-dlp + a JS runtime · optional

The last parser in the chain, and the one that plays live broadcasts. Keep Node, Deno or Bun on PATH beside it, or live streams fail.

on a thin connection

BUFFER_AHEAD_MS sets how long an interruption can last before anyone hears it. MAX_AUDIO_BITRATE roughly halves bandwidth, since Discord carries 64 kbps anyway unless the server is boosted.

Few commands. Easy to remember.

Every command with its options is in the reference on GitHub.

Prebuilt binaries.

Not sure which? arm64 is Apple Silicon, Raspberry Pi and ARM cloud instances; amd64 is everything else. Each bundle ships both binaries, a ready-to-edit .env, and the docs. Or run it in Docker.

Questions worth asking first.

Something not covered here? Ask in the Ctrl+Z server or open an issue on GitHub.