AuroraMusic Discord Music Bot (v4.3.5)

Quick links:

• Latest Release: https://github.com/Soham-Das-afk/AuroraMusic/releases/latest

• Docker Hub: https://hub.docker.com/r/sohamdas103/auroramusic

• Demo Server: https://discord.gg/6nczZbSmZ6 (Join for support, testing, and updates)

• Contributing Guidelines | Security Policy

AuroraMusic is a feature-rich music bot designed for Discord servers, allowing users to play music from various sources, manage queues, and interact with an intuitive user interface. This bot supports both YouTube and Spotify, providing a seamless music experience for users.

Quick start (copy-paste)

Windows (local):

git clone https://github.com/Soham-Das-afk/AuroraMusic.git
cd AuroraMusic
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item .env.example .env
# edit .env to set BOT_TOKEN and ALLOWED_GUILD_IDS; set YOUTUBE_COOKIES=cookies/youtube.txt (recommended)
# Optional: Create valid_proxies.txt in root if you need proxies
python src/bot.py

Linux (local):

git clone https://github.com/Soham-Das-afk/AuroraMusic.git
cd AuroraMusic
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# edit .env to set BOT_TOKEN and ALLOWED_GUILD_IDS; set YOUTUBE_COOKIES=cookies/youtube.txt (recommended)
# Optional: Create valid_proxies.txt in root if you need proxies
python3 src/bot.py

Docker (both OS):

# ensure .env exists and is filled; cookies recommended at cookies/youtube.txt
# Optional: Create valid_proxies.txt in root if you need proxies
docker compose up -d --build
docker compose logs -f

Run directly with Docker (without Compose):

Windows PowerShell

# assumes you created and filled .env in the project folder
docker pull sohamdas103/auroramusic:latest
docker run --name auroramusic ^
   --env-file .env ^
   -v "$PWD/cookies:/app/src/cookies:ro" ^
   -v "$PWD/data:/app/src/data" ^
   -v "$PWD/valid_proxies.txt:/app/valid_proxies.txt:ro" ^
   -p 8080:8080 ^
   -d sohamdas103/auroramusic:latest

Linux/macOS

# assumes you created and filled .env in the project folder
docker pull sohamdas103/auroramusic:latest
docker run --name auroramusic \
   --env-file .env \
   -v "$(pwd)/cookies:/app/src/cookies:ro" \
   -v "$(pwd)/data:/app/src/data" \
   -v "$(pwd)/valid_proxies.txt:/app/valid_proxies.txt:ro" \
   -p 8080:8080 \
   -d sohamdas103/auroramusic:latest

Features

• Modern Controller UI: A welcome banner card, plus a clean controller embed with clear fields for queue, next song, and status.
• Multi-Source Playback: Play music from YouTube and Spotify, including single tracks and playlists.
• Queue Management: Add, view, shuffle, and manage a queue of tracks.
• Autoplay: Automatically find and play related tracks when the queue ends.
• Interactive Controls: Use buttons for play, pause, skip, and other controls directly in Discord.
• Slash Commands: Modern slash commands for setup and status, plus a message-based controller for music requests.
• Rich Embeds: Displays detailed information about the currently playing track and the queue.
• Voice Integration: Joins voice channels and streams high-quality audio.
• Error Handling: Provides user-friendly error messages and robust exception handling.
• Persistent State: Remembers playback history and controller channel information per guild.
• Proxy Support: Configure HTTP/HTTPS proxies via environment variables or a valid_proxies.txt file to bypass regional restrictions.
• Streaming-first playback: The bot streams audio directly from sources. On-disk pre-caching and background downloads have been removed.

Usage

Once the bot is up and running:

• Use /setup to create a dedicated music controller channel in your server.

• In the controller channel:

  • Send a song name, YouTube URL, or Spotify link (no prefix needed)
  • Use the controller buttons (Play/Pause, Skip, Previous, Stop, Loop, Shuffle)

• Helpful slash commands:

  • /help — quick usage guide and links to your controller channel
  • /ping — bot latency/status (shows AuroraMusic v4.3.4)
  • /health — configuration and queue summary
  • /cleanup — remove the controller (admin only)

Permissions note:

• The bot should have “Manage Messages” in the controller channel for auto-cleanup of helper messages.

Detailed Setup Guide

Windows (local, without Docker)

1. Install prerequisites

   • Install Python 3.11 (enable “Add to PATH”).
   • Install FFmpeg:
     • Using winget:

       winget install Gyan.FFmpeg

     • Or using Chocolatey:

       choco install ffmpeg

   • Verify:

     python --version
     ffmpeg -version

2. Get the code and set up a virtual environment

   git clone https://github.com/Soham-Das-afk/AuroraMusic.git
   cd AuroraMusic
   python -m venv .venv
   .\.venv\Scripts\Activate.ps1
   pip install -r requirements.txt

3. Configure environment

   Copy-Item .env.example .env

   • Optional: valid_proxies.txt in root (one proxy per line) or PROXY_URL in .env
   • Open .env and set:
     • BOT_TOKEN=your discord bot token
     • ALLOWED_GUILD_IDS=comma,separated,guild,ids
     • Optional: SPOTIFY_CLIENT_ID / SPOTIFY_CLIENT_SECRET
   • Optional (recommended): YOUTUBE_COOKIES=cookies/youtube.txt # helps bypass age/region restrictions
     • Optional: OWNER_CONTACT=your handle or ID for contact

4. Run the bot

   python src/bot.py

5. In Discord, run /setup in a server you own to create the music controller channel.

Tip: If venv activation is blocked, run PowerShell as admin once and execute:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Linux (local, without Docker)

1. Install prerequisites (Debian/Ubuntu example)

   sudo apt update
   sudo apt install -y python3 python3-venv python3-pip ffmpeg libopus0 libsodium23

   • Verify:

   python3 --version
   ffmpeg -version

2. Get the code and set up a virtual environment

   git clone https://github.com/Soham-Das-afk/AuroraMusic.git
   cd AuroraMusic
   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt

3. Configure environment

   cp .env.example .env

   • Edit .env and set BOT_TOKEN, ALLOWED_GUILD_IDS, and any optional values.

4. Run the bot

   python3 src/bot.py

5. Use /setup in your server to create the music controller.

Environment variables

Required:

• BOT_TOKEN — your Discord bot token
• ALLOWED_GUILD_IDS — comma-separated list of server IDs where the bot is allowed

Optional:

• SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET — enable Spotify features
• YOUTUBE_COOKIES — (recommended) path to cookies file (e.g., cookies/youtube.txt) to help bypass age or regional restrictions and improve reliability
• BOT_BANNER_URL — optional fallback image/GIF URL for the welcome banner if your Discord App doesn’t have a banner (example: https://cdn.example.com/banner.gif)
• CONTROLLER_THUMBNAIL_URL — optional controller thumbnail image URL (not shown by default; can be enabled later)
• SHOW_BANNER — show the welcome banner image card (true/false; accepts 1/0, true/false, yes/no, y/n)
• SHOW_CONTROLLER_THUMBNAIL — show a small thumbnail on controller embeds (true/false; accepts 1/0, true/false, yes/no, y/n)
• OWNER_CONTACT — contact string shown for unauthorized guilds (e.g., Discord handle/ID)
• PROXY_URL — optional single proxy URL (e.g., http://user:pass@host:port)
• PROXY_FILE — optional path to a text file containing one proxy per line (default: valid_proxies.txt in project root)
• AUTO_RESTART_ENABLED — enable daily auto-restart (true/false, default true)
• AUTO_RESTART_TIME — time for restart in HH:MM (default 06:00)
• AUTO_RESTART_TZ_OFFSET_MINUTES — timezone offset in minutes (IST=330)
• CLEAR_CACHE_ON_START — (removed) on-disk cache and background downloads are disabled; this option is deprecated in this build.
• ENABLE_GLOBAL_COMMAND_SYNC — allow global slash-command sync (true/false; default: false). Use with care to avoid rate limits.
• COMMAND_SYNC_RETRIES — number of retries for command sync attempts (default: 3)
• COMMAND_SYNC_BACKOFF_BASE — exponential backoff base for command sync retries (default: 1.5; delay = base ** attempt)
• GLOBAL_COMMAND_SYNC_OFFPEAK_ENABLED — if true, global command syncing will be deferred to an off-peak UTC window (default: false)
• GLOBAL_COMMAND_SYNC_OFFPEAK_START_HOUR_UTC — start hour (UTC) for off-peak window (0–23; default: 2)
• GLOBAL_COMMAND_SYNC_OFFPEAK_END_HOUR_UTC — end hour (UTC) for off-peak window (0–23; default: 5)

Hosting your banner image (recommended options)

If your Discord App banner isn’t set or you prefer a custom GIF, set BOT_BANNER_URL to a direct image URL. Reliable, no-login choices:

• ImgBB (simple, free):
  1. Go to https://imgbb.com/
  2. Upload your image/GIF (leave “expiration” as Don’t autodelete)
  3. After upload, open the image, choose “Embed codes” or “Links” and copy the Direct link
     • It must look like https://i.ibb.co/xxxx/banner.gif (note the i.ibb.co host and file extension)
  4. Set BOT_BANNER_URL in .env to that direct link

Tip: Avoid page/album links (they return HTML). You want links ending in .gif, .png, or .jpg with Content-Type: image/*.

Docker

Build the image and run with Docker Compose (recommended):

1. Ensure .env includes the required variables listed above.
2. Place cookies (recommended) on the host at AuroraMusic/cookies/youtube.txt and set YOUTUBE_COOKIES=cookies/youtube.txt in .env (helps bypass age/region restrictions).
3. (Optional) Place valid_proxies.txt in the root folder if you need proxy support.
4. From the project folder:

   docker compose up -d --build
   docker compose logs -f
   

Notes:

• Personal cookies and runtime data are not baked into the image. The compose file mounts:
  • ./cookies -> /app/src/cookies:ro
  • ./data -> /app/src/data
  • ./valid_proxies.txt -> /app/valid_proxies.txt:ro (if it exists)
• To stop the container:

  docker compose down
  

• Multi-arch images: Starting with v3.2.35+, images are published for linux/amd64 and linux/arm64 (Apple Silicon, Graviton, etc.). Docker will automatically pull the correct architecture manifest.

Windows (Docker Desktop)

1. Install Docker Desktop and ensure WSL 2 backend is enabled.
2. Configure .env (copy from .env.example).
3. Recommended: Place YouTube cookies at AuroraMusic/cookies/youtube.txt and set YOUTUBE_COOKIES=cookies/youtube.txt in .env (bypasses age or regional access limits).
4. Optional: Place valid_proxies.txt in the root folder if you need proxies.
5. From the project folder:

   docker compose up -d --build
   docker compose logs -f

6. Stop when needed:

   docker compose down

Linux (Docker Engine + Compose)

1. Install Docker Engine and Compose plugin (Debian/Ubuntu example):

   sudo apt update
   sudo apt install -y docker.io docker-compose-plugin
   sudo usermod -aG docker $USER
   newgrp docker
   docker compose version

2. Optional: Create valid_proxies.txt if needed.
3. Configure .env and cookies as above.
4. Build and run:

   docker compose up -d --build
   docker compose logs -f

5. Stop:

   docker compose down

Upgrade

• Docker (Compose):

  docker compose pull
  docker compose up -d --pull always

• Docker (direct run):

  docker pull sohamdas103/auroramusic:latest
  docker stop auroramusic && docker rm auroramusic
  # re-run the docker run command from above

• From source (venv):

  git pull
  pip install -r requirements.txt
  python src/bot.py

Troubleshooting/Faq

• Token/authorization errors: Double-check BOT_TOKEN in .env and that the bot was invited with the right scopes (bot + applications.commands).
• Slash commands not showing: The bot clears and re-syncs per-guild on startup, but global propagation can still take time. Try re-inviting or restarting; check logs.
• FFmpeg not found: Ensure ffmpeg -version works in your shell/terminal. Install FFmpeg and add to PATH.
• Voice playback issues on Linux: Ensure libopus0 and libsodium are installed (see Linux prerequisites).
• Permissions: In the controller channel, grant “Manage Messages” to the bot for best cleanup behavior.

Maintenance

I maintain this project when it’s needed or when I get time. If you run into issues or have suggestions, feel free to reach out directly:

• Discord: @sick._.duck.103 (Discord ID: 616499661951467530)

License

This project uses a source-available license tailored for AuroraMusic. See the LICENSE file for the full terms.