Discord Music Bot

A lightweight Discord music bot that plays audio in voice channels using YouTube, Youtube Music and Spotify (via YT Music).

Contents

• Features
• Architecture
• Requirements
• Quick start (local)
• Docker
• Configuration
• Usage
• Contributing
• License

Features

• Play tracks and playlists by URL or search term (YouTube / Spotify)
• Join voice channels, queue tracks, skip
• Download/stream via yt-dlp and ytmusicapi
• Pluggable download/processing strategies for YouTube and Spotify

Architecture

Project layout (key folders):

• main.py — Bot entrypoint; loads cogs from src/boundary and starts the bot.
• src/boundary/ — Command cogs exposed to Discord (e.g. music_boundary.py).
• src/service/ — Business logic and orchestration (player, queue, download services).
• src/data/ — Domain models (e.g. Music).
• src/utils/ — Helpers and strategy implementations (downloaders and processors).

The bot uses a small-service design: boundary (commands) -> service layer -> utils (download/processing).

Requirements

• Python 3.10+ recommended

• System ffmpeg (for audio playback) — install with your package manager, e.g. Debian/Ubuntu: sudo apt install ffmpeg

• The Python dependencies are listed in requirements.txt.

• A file named cookie.txt with your Youtube Cookies for yt-dlp, read (this)["https://github.com/ytdl-org/youtube-dl"] to know what it does and how to get it

• A .env file with your private tokens, this should be its structure: DISCORD_TOKEN=[token] SPOTIPY_CLIENT_ID=[token] SPOTIPY_CLIENT_SECRET=[token] Required Python packages (from requirements.txt):

• discord.py[voice]

• yt-dlp[default]

• ytmusicapi

• spotipy (optional; used by Spotify strategy)

Quick start (local)

1. Clone the repository:

git git@github.com:JPSP9547/DiscordBot.git
cd DiscordBot

2. Create and activate a virtual environment, then install dependencies:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3. Set the Discord bot token and optional Spotify credentials (or use .env or .envrc):

export DISCORD_TOKEN="your-bot-token-here"
# (optional, only required for Spotify lookups)
export SPOTIPY_CLIENT_ID="..."
export SPOTIPY_CLIENT_SECRET="..."

4. Run the bot:

python main.py

Or use docker (recommend way) You should see "Bot is ready" in the logs once the bot connects.

Docker

This repository contains a Dockerfile and docker-compose.yml for containerized runs.

Build and run with docker-compose:

docker compose up --build

Be sure to provide the DISCORD_TOKEN (and optional Spotify credentials) to the container environment via Compose or a .env file.

Configuration

• DISCORD_TOKEN (required): your Discord bot token.
• SPOTIPY_CLIENT_ID / SPOTIPY_CLIENT_SECRET (optional): needed for the Spotify strategy to use Spotify Web API client credentials.

Notes:

• The bot's command prefix is $ (see main.py).
• main.py dynamically loads Python files from src/boundary/ as cogs; add new command cogs there.

Usage

Common commands (in src/boundary/music_boundary.py):

• $join — Bot joins your voice channel.
• $play <url or search term> — Play a track or playlist (queues results).
• $skip — Skip the currently playing track.
• $stop — Not implemented yet.

Example flow:

1. Join a voice channel.
2. Run $join in text chat.
3. Run $play never gonna give you up or $play <youtube-or-spotify-url>.

Development notes

• The download strategies live under src/utils/download_strategy/. To add support for another source, implement the DownloaderStrategy interface and register it in PlayerService as needed.
• The Spotify strategy uses spotipy and ytmusicapi to map Spotify track IDs to YouTube Music videos.