Melody Café (Discord Bot)

A Discord bot that joins a voice channel and plays local audio files from a directory on disk.
It supports fuzzy searching by filename, queuing, shuffle, and playback controls.

---

Features

• Join/leave voice channels
• Play a song by relative path or fuzzy name
• Queue management: view queue, skip, stop (clear queue), shuffle
• Pause/resume
• Volume control (0–200%)
• Library indexing + manual rescans
• Works with common audio formats supported by your FFmpeg build: .mp3 .wav .flac .m4a .aac .ogg .opus

---

How it works

• The bot scans MUSIC_DIR and builds an in-memory index:
  • keys include the file stem (filename without extension)
  • and the relative path without extension
• !play <query>:
  • If <query> is a real file path, it plays it
  • Otherwise it finds the best fuzzy match from the library index

Audio playback is handled via Discord voice + FFmpeg (discord.FFmpegPCMAudio).

---

Requirements

• Python 3.10+ recommended
• A Discord application + bot token
• FFmpeg installed and reachable (or provide full path)
• Voice dependencies:
  • discord.py[voice] (already in requirements)
  • PyNaCl is required for Discord voice (the bot fails early with a helpful message if missing)

---

Setup

1) Clone and install dependencies

git clone <your-repo-url>
cd melody-cafe

python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

python -m pip install -U pip
pip install -r requirements.txt

2) Create your .env

Copy the example env file:

# Windows (PowerShell)
copy .env.example .env

# macOS/Linux
cp .env.example .env

Edit .env and set:

DISCORD_TOKEN="your_real_token"
MUSIC_DIR=C:\Path\To\Your\Music\Directory
FFMPEG_PATH=ffmpeg          # or full path like C:\ffmpeg\bin\ffmpeg.exe
COMMAND_PREFIX=!

Notes:

• MUSIC_DIR should point to a folder containing audio files (it can include subfolders).
• FFMPEG_PATH can be just ffmpeg if it’s on your PATH. Otherwise set the full executable path.
• COMMAND_PREFIX defaults to ! if omitted.

3) Enable Message Content Intent (important)

This bot uses prefix commands and sets:

INTENTS.message_content = True

You must also enable Message Content Intent in the Discord Developer Portal for your bot, or commands won’t register.

4) Run the bot

python bot.py

You should see something like:

Logged in as <botname> (id: ...)
------
[INFO] Indexed ... entries from <MUSIC_DIR>

---

Commands

All commands assume the default prefix ! (configurable via .env).

Voice

• !join
  Join the caller’s voice channel.

• !leave
  Disconnect from voice.

Playback

• !play <query>
  Play a local track by fuzzy name or by path.

  Examples:

  • !play songname
  • !play subfolder/songname
  • !play C:\Music\Albums\Artist\Track01.mp3 (works if that exact file exists)

• !playall [shuffle]
  Queue everything in the library. Optional shuffle to randomize.

• !pause / !resume
  Pause/resume playback.

• !skip
  Skip the current track.

• !stop
  Stop playback and clear the queue.

• !volume <0-200>
  Set playback volume in percent (e.g. !volume 120).

Queue + Library

• !queue or !q
  Show “Now playing” and the next 20 queued items.

• !shuffle
  Shuffle the current queue.

• !list [page] [per_page]
  List library entries (defaults: page 1, 20 per page, clamped to 5–50).

• !search <query>
  Show best match without queuing it.

• !rescan
  Rebuild the library index from MUSIC_DIR.

• !where
  Show the current MUSIC_DIR and FFMPEG_PATH.

---

License

MIT. See LICENSE.