🎵 Lyra - Discord YouTube Music Bot

Lyra is a self-hosted, lightweight, and modern Discord Music Bot containerized with Docker. Designed for high reliability on Unraid (home network) and Linux VPS servers.

It utilizes a hybrid streaming engine:

• YouTube Data API v3: Lightning-fast song search, playlist item resolution, and metadata lookup without triggering bot scraping blocks.
• yt-dlp: Direct Opus audio stream URL extraction on demand.
• FFmpeg: Real-time transcoding and audio streaming directly to Discord voice channels with zero disk bloat.

---

✨ Features

• Slash Commands (/): Modern Discord interaction with autocomplete and intuitive UI.
• Rich Embeds: Thumbnail previews, song duration, channel name, and live playback progress bar (/nowplaying).
• Queue Management: Add single tracks, playlists, reorder, view upcoming songs (/queue), loop (/loop), or clear (/clear).
• Quota & Bot Fallback: If your YouTube Data API v3 key is omitted or exceeds its daily quota, the bot automatically falls back to yt-dlp search without interruption.
• Smart Resource Management: Automatically leaves voice channels when idle for 5 minutes or if all human listeners leave.
• VPS Anti-Bot Support: Native support for mounting cookies.txt to bypass datacenter IP restrictions (e.g. Hetzner, DigitalOcean, AWS).
• Unraid Ready: Includes a native Unraid Docker XML template for 1-click installation via Unraid's Docker Manager.

---

📋 Slash Commands

Command	Description
/play <query or url>	Play a song or entire playlist by search query, video URL, or playlist link.
/pause	Pause currently playing track.
/resume	Resume playback if paused.
/skip	Skip the currently playing track.
/stop	Stop playback, clear the queue, and disconnect the bot from voice.
/nowplaying	Show details and visual progress bar for the current song.
/queue	Display the list of upcoming tracks.
/volume <1-100>	Adjust playback volume.
/loop	Toggle repeat mode for the current track.
/clear	Clear upcoming songs from the queue.

---

🚀 Setup Prerequisites

1. Create Discord Bot Token

1. Go to the Discord Developer Portal.
2. Click New Application, give it a name (e.g., MusicBot), and open it.
3. In the left sidebar, navigate to Bot:
   • Click Reset Token and copy the bot token (this is your DISCORD_TOKEN).
   • Under Privileged Gateway Intents, ensure Server Members Intent and Message Content Intent (if prompted) are enabled.
4. In the left sidebar, navigate to OAuth2 -> URL Generator:
   • Scopes: select bot and applications.commands.
   • Bot Permissions: select Connect, Speak, Send Messages, Embed Links, Read Message History.
   • Copy the generated URL at the bottom, paste it into your browser, and invite the bot to your Discord server.

2. (Recommended) Get YouTube Data API v3 Key

1. Go to the Google Cloud Console.
2. Create a new project or select an existing one.
3. Go to APIs & Services -> Library, search for YouTube Data API v3, and click Enable.
4. Go to APIs & Services -> Credentials -> click + Create Credentials -> API Key.
5. Copy the generated API key (this is your YOUTUBE_API_KEY).

   Note: If you don't provide an API key, the bot will automatically fall back to yt-dlp search.

---

🐳 Deployment Option A: Unraid Server

Unraid is the ideal platform for Lyra because home residential IPs rarely encounter YouTube bot challenges.

Method 1: Using the Unraid XML Template (1-Click Install)

With the prebuilt GitHub Container Registry image (ghcr.io/nate-eisner/lyra:latest), you do not even need to compile or build on Unraid!

1. Copy the included unraid-template.xml to your Unraid server at:

   /boot/config/plugins/dockerMan/templates-user/my-lyra.xml

   (Or in Unraid terminal: curl -sLo /boot/config/plugins/dockerMan/templates-user/my-lyra.xml https://raw.githubusercontent.com/nate-eisner/Lyra/main/unraid-template.xml)
2. In your Unraid WebGUI, navigate to the Docker tab and click Add Container at the bottom.
3. In the Template dropdown, select lyra.
4. Enter your DISCORD_TOKEN and (optional) YOUTUBE_API_KEY.
5. Verify the appdata path (/mnt/user/appdata/lyra).
6. Click Apply. Unraid will automatically pull the container image and start Lyra!

Method 2: Using Docker Compose on Unraid

1. Install the Docker Compose Manager plugin from Community Applications.
2. Copy this repository folder to /mnt/user/appdata/lyra/.
3. Create .env from .env.example and fill in your tokens.
4. Launch the stack via Docker Compose Manager or terminal:

   cd /mnt/user/appdata/lyra
   docker compose up -d

---

🌐 Deployment Option B: Linux VPS (Docker Compose)

1. Clone this repository on your VPS:

   git clone https://github.com/nate-eisner/Lyra.git
   cd Lyra

2. Create your configuration file:

   cp .env.example .env
   nano .env

   Fill in DISCORD_TOKEN and YOUTUBE_API_KEY.

3. Start the bot:

   docker compose up -d --build

4. View logs to verify connection:

   docker compose logs -f

---

🍪 Datacenter IP & VPS Troubleshooting (YouTube Bot Detection)

Cloud providers (AWS, DigitalOcean, Hetzner, Linode, OVH) have datacenter IP ranges that YouTube actively flags with Sign in to confirm you're not a bot or HTTP 403 Forbidden.

If you run on a VPS and encounter playback issues, export your browser cookies:

1. Install the browser extension Get cookies.txt locally (Chrome Web Store or Firefox Add-ons).
2. Go to youtube.com while signed into a Google account.
3. Open the extension and click Export to save cookies.txt.
4. Place this file on your server inside the config directory:
   • VPS: ./config/cookies.txt
   • Unraid: /mnt/user/appdata/discord-music/cookies.txt
5. The container automatically mounts this path, and the bot will use your session to authenticate stream extraction.

---

🛠️ Local Development & Testing

If running locally without Docker:

# 1. Install system dependencies (FFmpeg must be installed on your OS)
# macOS: brew install ffmpeg
# Ubuntu/Debian: sudo apt install ffmpeg nodejs

# 2. Install python dependencies
pip install -r requirements.txt

# 3. Configure environment
cp .env.example .env
# Edit .env with your DISCORD_TOKEN

# 4. Run the bot
python -m bot.main