Musyc - Discord Music Bot

A Discord music bot built with Python that can search, download, and play music from YouTube. The bot features intelligent music search using vector embeddings and supports queue management for seamless music playback.

Features

• 🎵 Music Search: Search for music by name or YouTube URL
• 🎯 Intelligent Search: Uses vector embeddings for semantic music search
• 📥 Auto Download: Automatically downloads and caches music from YouTube
• 🎧 Queue Management: Add multiple songs to a queue
• ⏯️ Playback Controls: Play, pause, resume, skip, and stop functionality
• 🗄️ Database Storage: MongoDB integration for music metadata and embeddings
• 🔍 Vector Search: MongoDB Atlas Vector Search for intelligent music discovery

System Requirements

Prerequisites

• Python 3.12+ (managed with pyenv)
• FFmpeg (required for audio processing)
• MongoDB (with Atlas Vector Search support)
• Poetry (for dependency management)

FFmpeg Installation

Ubuntu/Debian:

sudo apt update
sudo apt install ffmpeg

macOS (with Homebrew):

brew install ffmpeg

Windows:

Download from FFmpeg official website and add to PATH.

Installation

1. Clone the Repository

git clone <repository-url>
cd Musyc

2. Python Environment Setup

Install and configure pyenv (if not already installed):

# Install pyenv (Linux/macOS)
curl https://pyenv.run | bash

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc

# Reload shell
source ~/.bashrc

# Install Python 3.12
pyenv install 3.12.0
pyenv local 3.12.0

3. Install Dependencies with Poetry

# Install Poetry (if not already installed)
curl -sSL https://install.python-poetry.org | python3 -

# Install project dependencies
poetry install

4. MongoDB Setup

Option A: Local MongoDB with Docker

# Start MongoDB using the provided docker-compose
docker-compose up -d

Option B: MongoDB Atlas

1. Create a MongoDB Atlas account
2. Create a new cluster
3. Get your connection string

5. MongoDB Database Configuration

Create the required database and collection with vector search index:

1. Database: Musyc
2. Collection: Musics
3. Vector Search Index:
   • Index Name: default
   • Path: embeddings
   • Dimensions: 384
   • Similarity: dotProduct

MongoDB Atlas Vector Search Index Configuration:

{
  "fields": [
    {
      "type": "vector",
      "path": "embeddings",
      "numDimensions": 384,
      "similarity": "dotProduct"
    }
  ]
}

6. Environment Configuration

Create a .env file in the project root:

# Discord Bot Configuration
DISCORD_BOT_KEY=your_discord_bot_token_here

# MongoDB Configuration
MONGODB_URI=mongodb://localhost:27019  # For local Docker setup
# MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/  # For Atlas

# YouTube API Configuration
YOUTUBE_API_KEY=your_youtube_api_key_here

Getting API Keys:

Discord Bot Token:

1. Go to Discord Developer Portal
2. Create a new application
3. Go to "Bot" section
4. Create a bot and copy the token

YouTube API Key:

1. Go to Google Cloud Console
2. Create a new project or select existing one
3. Enable YouTube Data API v3
4. Create credentials (API Key)
5. Restrict the key to YouTube Data API v3

Usage

Running the Bot

# Using Poetry
poetry run python -m musyc

# Or using the installed script
poetry run musyc

Discord Bot Commands

• $play <music_name_or_url> - Play music by name or YouTube URL
• $pause - Pause the current music
• $resume - Resume paused music
• $stop - Stop music and disconnect from voice channel
• $skip - Skip to the next song in queue
• $queue - Show current music and queue

Example Usage

$play Never Gonna Give You Up
$play https://www.youtube.com/watch?v=dQw4w9WgXcQ
$queue
$skip
$pause
$resume
$stop

Project Structure

Musyc/
├── src/
│   └── musyc/
│       ├── __main__.py          # Application entry point
│       ├── discord/
│       │   └── bot.py           # Discord bot implementation
│       ├── file_manager/
│       │   ├── database_manager.py  # MongoDB operations
│       │   └── vectorizer.py        # Text embedding generation
│       └── ytb/
│           ├── api.py           # YouTube API integration
│           ├── handler.py       # YouTube URL/name handling
│           ├── pytube.py        # YouTube video info extraction
│           └── video_downloader.py  # Video download and processing
├── musics/                      # Downloaded music cache
├── docker-compose.yaml          # MongoDB Docker setup
├── pyproject.toml              # Poetry configuration
└── README.md

Dependencies

The project uses the following key dependencies:

• discord.py: Discord API wrapper
• sentence-transformers: Text embedding generation (all-MiniLM-L6-v2 model)
• pymongo: MongoDB driver
• yt-dlp: YouTube video downloading
• google-api-python-client: YouTube Data API
• python-dotenv: Environment variable management
• numpy: Numerical operations for embeddings

Additional Configuration Notes

Sentence Transformers Model

The bot uses the all-MiniLM-L6-v2 model for generating text embeddings. This model:

• Generates 384-dimensional embeddings
• Runs on CPU by default
• Is automatically downloaded on first use (~90MB)

Audio Processing

• Music is downloaded as MP3 files (192kbps quality)
• FFmpeg is used for audio format conversion
• Audio is played at 48kHz, stereo, 128kbps bitrate

Database Schema

Each music document in MongoDB contains:

{
  "_id": "uuid4_string",
  "name": "Song Title",
  "path": "/path/to/audio/file.mp3",
  "url": "https://youtube.com/watch?v=...",
  "video_id": "youtube_video_id",
  "embeddings": [0.1, 0.2, ...]  // 384-dimensional vector
}

Troubleshooting

Common Issues

1. FFmpeg not found: Ensure FFmpeg is installed and in your PATH
2. MongoDB connection failed: Check your MONGODB_URI and ensure MongoDB is running
3. Discord bot not responding: Verify DISCORD_BOT_KEY is correct and bot has proper permissions
4. YouTube API quota exceeded: Check your YouTube API quota in Google Cloud Console

Bot Permissions

Ensure your Discord bot has the following permissions:

• Send Messages
• Connect to Voice Channels
• Speak in Voice Channels
• Use Slash Commands (if applicable)

License

This project is licensed under the MIT License.

Support

For issues and questions, please open an issue on the GitHub repository.