A Discord bot that plays music in your voice channel. Drop a song name or a link in the assigned text channel and it starts playing, or tag it and talk to it like a DJ: it picks the music, answers in its own voice and keeps the radio running.
- No tag needed: in the listening channel, the fast router reads the intent of every message. "pausá" pauses, "mostrame la cola" shows the queue, "cumbia" plays a search, and a mood like "poneme algo tranqui" goes to the DJ.
- Talk to it like a DJ: tag the bot with a plain request ("poneme algo tranqui de rock nacional") and it chooses the songs, queues them and answers in character.
- Radio voice: with a voice configured, the DJ speaks in the gap before a song starts and never over it. One song in three runs without a line and autoplay songs talk less. Short lines keep the run moving (who asked, what just played, what comes next); every fifth line is longer and gets one fact about the song or artist, only when the model is sure of it.
- Personality per server: ask it to talk a certain way (
@DJ sé un dj cumbiero) and the setting lives with the server. - Play anything: YouTube links and search terms, and
open.spotify.comlinks (track, album, playlist, artist). Other pasted links are rejected before they reach the extractor. - Full control surface: pause, resume, skip, shuffle, radio, clear (the button asks for confirmation) and a paginated queue view, as buttons on the now-playing message or by asking
@DJin plain language. - Playlists: paste a playlist link and it queues up to 50 songs.
- Leaves when done: disconnects when the queue ends (unless radio is on) or the voice channel empties.
- Remembers its channel: the listening channel and persona are per server and survive restarts.
- Welcome audio: plays
assets/welcome.mp3the first time it joins a voice channel each session (optional).
- Bun 1.4+: runs the TypeScript sources natively (no build step), installs dependencies, lints and runs the tests
- TypeScript: explicit ports and state types, checked in CI with
tsc --noEmit - Discord: discord.js + distube
- Multimedia: ffmpeg on
PATH - Downloader: yt-dlp on
PATH - LLM: any OpenAI-compatible Responses API endpoint (
/responses) for the DJ's voice and song picks - Decision router (optional): Jev through TypeSafe or OpenCode's System One endpoint
The internals are described in docs/architecture.md: capability ports, providers, one command bus, a station state machine and a tested dependency rule.
- Bun 1.4+
- FFmpeg on
PATH - yt-dlp on
PATH - A Discord bot: create one in the Discord developer portal and invite it with Send Messages, Embed Links, Attach Files, Add Reactions, Read Message History, Connect and Speak. Enable the Message Content privileged intent.
-
Install dependencies:
bun install
-
Set the bot token:
export DISCORD_TOKEN=your_bot_token -
(Optional) give it a voice: point the bot at any OpenAI-compatible Responses API endpoint (
/responses):export LLM_BASE_URL=https://your-endpoint/v1/responses export LLM_API_KEY=your_api_key export LLM_MODEL=your_model # optional, defaults to deepseek-v4-flash
Without these, the bot still plays music: announcements go out as plain text, refusals keep their plain reason, and tagged song requests are unavailable. The buttons, fast-routed controls and plain messages in the listening channel keep working.
-
(Optional) Spotify credentials: Spotify links work without them by scraping a web token, which is fragile. Set the credentials from a Spotify app to use the official API:
export MUSIC_METADATA_CLIENT_ID=your_client_id export MUSIC_METADATA_CLIENT_SECRET=your_client_secret
-
(Optional) fast action routing: point
DECISION_BASE_URLat a System One endpoint. With the official TypeSafe API:export DECISION_BASE_URL=https://api.typesafe.ai/v1/systemone export DECISION_MODEL=jev-latest export DECISION_API_KEY=your_typesafe_key
Or with OpenCode's Console endpoint and the same OpenCode key (set it explicitly; there is no fallback):
export DECISION_BASE_URL=https://opencode.ai/inference/systemone/v1/systemone export DECISION_MODEL=jev-1.13-free # optional export DECISION_API_KEY=your_opencode_key
Without it, or when the model is unavailable, the DJ falls back to choosing actions with the conversation model.
-
(Optional) radio voice: give the DJ a voice in the voice channel with ElevenLabs. Add a male Spanish (Argentina) voice from the voice library and copy its ID:
export SPEECH_API_KEY=your_api_key export SPEECH_VOICE_ID=your_voice_id export SPEECH_MODEL_ID=eleven_v4 # optional
The line is written while the previous song plays and airs in the gap, so the music never plays underneath it. The first song after a reconnect, and the autoplay songs, are written on the spot. The provider checks its character quota every five minutes and skips lines when the period is exhausted, so the free tier never breaks playback. Lines target 100 characters and are hard-capped at 120; the fifth line targets 210 and is capped at 230. Audio tags (
[laughs],[sighs],[excited]) direct the delivery. -
(Optional) welcome audio: put an MP3 at
assets/welcome.mp3.
bun run start
# or, while developing
bun run devbun run check runs lint, typecheck and the test suite.
-
Point it at a channel (the author needs Manage Channels):
@DJ #music -
Play something: join a voice channel and post a link or search term in the listening channel:
never gonna give you up -
Control playback: the buttons on the now-playing message cover everything, or ask in your own words:
@DJ pausá @DJ seguí @DJ saltéala @DJ mostrame la cola @DJ sacá la 3 -
Talk to the DJ:
@DJ poneme algo tranqui para el asado -
Set its personality (Manage Server; ask in the listening channel):
@DJ sé un dj cumbiero que no para de hacer chistes
bun run testruns the unit tests;bun testworks too.bun run typecheckchecks the TypeScript contracts.bun run test:e2eruns the live suite against a real guild. It reads the token and model variables from~/.config/dj/discord.env(override withE2E_ENV_FILE,E2E_GUILD,E2E_VOICE,E2E_TEXT) and needs the bot service stopped so two clients do not share the token.
src/
index.ts, app.ts process entry and composition root
config.ts the only environment reader
core/ clock, errors, logger, async, text, TTL map
ports/ capability interfaces
providers/ music, speech, language-model, classifier, settings
dj/ persona, prompts, conversation, replies, announcements
on-air/ station state machine, script, host
commands/ command specs, bus, fast router
discord/ gateway, handlers, views, message slot