Skip to content
tsu-ldPublic

About

Discord music bot for people who hate slash commands.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

Ask DeepWiki

tsu-ld/dj

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.

Features

  • 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.com links (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 @DJ in 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.mp3 the first time it joins a voice channel each session (optional).

Tech Stack

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

Requirements

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

Setup

  1. Install dependencies:

    bun install
  2. Set the bot token:

    export DISCORD_TOKEN=your_bot_token
  3. (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.

  4. (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
  5. (Optional) fast action routing: point DECISION_BASE_URL at 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.

  6. (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.

  7. (Optional) welcome audio: put an MP3 at assets/welcome.mp3.

Run

bun run start
# or, while developing
bun run dev

bun run check runs lint, typecheck and the test suite.

Using it

  1. Point it at a channel (the author needs Manage Channels):

    @DJ #music
    
  2. Play something: join a voice channel and post a link or search term in the listening channel:

    never gonna give you up
    
  3. 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
    
  4. Talk to the DJ:

    @DJ poneme algo tranqui para el asado
    
  5. Set its personality (Manage Server; ask in the listening channel):

    @DJ sé un dj cumbiero que no para de hacer chistes
    

Testing

  • bun run test runs the unit tests; bun test works too.
  • bun run typecheck checks the TypeScript contracts.
  • bun run test:e2e runs the live suite against a real guild. It reads the token and model variables from ~/.config/dj/discord.env (override with E2E_ENV_FILE, E2E_GUILD, E2E_VOICE, E2E_TEXT) and needs the bot service stopped so two clients do not share the token.

Layout

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

About

Discord music bot for people who hate slash commands.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Contributors

Languages