MusicBot

✨ Why Beatra?

• Slash-first UX – /play, /search, /language, /nowplaying, and /help respond instantly with localized embeds and live-updating buttons.
• Platform polyglot – Streams from YouTube, Spotify, SoundCloud, or a direct MP3/WAV/OGG link. Spotify albums, playlists, and artist radios turn into fully hydrated queues.
• Adaptive UI – A two-row control deck (Pause, Skip, Stop, Queue, Shuffle, Volume) stays in sync with the audio engine and locks down expired sessions automatically.
• Edge-ready audio core – Preloads entire queues, heals voice reconnections, and falls back gracefully when Discord or upstream services hiccup.
• Global voice – 21 fully translated language packs shipped out-of-the-box with instant server switching.
• Privacy-first – Stores only the language preference per guild in a local JSON database. No chat logs, no audio recordings.

️ Table of Contents

1. Project Highlights
2. Folder Anatomy
3. Prerequisites
4. Quick Start
5. Configuration
6. Spotify API Setup
7. Genius API Setup (Optional)
8. YT-DLP Cookie Add
9. Sharding for Large Bots (1000+ Servers)
10. Slash Commands & Controls
11. Language Support
12. Deployment Tips
13. Troubleshooting
14. Privacy & Legal
15. Contributing

Folder Anatomy

…

Prerequisites

• Node.js ≥ 24+ (LTS recommended) and npm.
• Git for cloning the repository.
• Discord application with a bot user created in the Discord Developer Portal.
• (Optional but recommended) A VPS or host with stable bandwidth and low latency to Discord voice regions.

ℹ️ ffmpeg-static ships with the project. You do not need a system-wide FFmpeg unless you prefer using a custom build.

Quick Start

Windows fast track

# Run from the repo root
.\setup.bat
# Edit the generated .env with your credentials
.\start.bat

setup.bat verifies Node.js/npm, installs dependencies, and scaffolds a .env template if you don’t have one yet. start.bat makes sure your environment is ready and launches the bot via npm run start.

Cross-platform manual steps

# 1. Clone & enter
git clone https://github.com/umutxyp/musicbot.git discord-musicbot
cd discord-musicbot

# 2. Install dependencies
npm install

# 3. Configure secrets (see below)
Copy-Item .env .env.backup -ErrorAction SilentlyContinue
# Edit .env with your token, client ID, Spotify credentials, etc.

# 4. Boot the bot
npm run start
# or
node index.js

Slash commands register automatically when the bot starts. Guild-scoped deployment executes within seconds if GUILD_ID is provided; global rollout can take up to an hour per Discord caching rules.

Configuration

Beatra reads from both config.js defaults and environment variables via .env. Update whichever approach fits your hosting workflow.

.env Cheat Sheet

DISCORD_TOKEN=your_bot_token
CLIENT_ID=your_application_id
GUILD_ID=optional_guild_for_fast_testing
SPOTIFY_CLIENT_ID=spotify_client_id
SPOTIFY_CLIENT_SECRET=spotify_client_secret
GENIUS_CLIENT_ID=optional_genius_client_id
GENIUS_CLIENT_SECRET=optional_genius_client_secret
STATUS= Beatra | /play
EMBED_COLOR=#FF6B6B
SUPPORT_SERVER=https://discord.gg/ACJQzJuckW
WEBSITE=https://beatra.app
COOKIES_FROM_BROWSER=chrome
COOKIES_FILE=./cookies.txt

Key Settings

Spotify API Setup

1. Visit the Spotify Developer Dashboard, sign in, and click Create an App.
2. Name your integration (e.g., Beatra Bot) and enable Web API.
3. Reveal and copy the Client ID and Client Secret.
4. Add a redirect URI (any valid URL, e.g., https://localhost/callback) – although client credentials flow is used, Spotify requires at least one placeholder.
5. Paste both values into your .env (SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET).
6. Restart the bot. The credentials are cached and refreshed automatically with the client credentials grant.

Without these credentials Spotify requests fall back to zero results.

Genius API Setup (Optional)

Beatra uses web scraping by default to fetch lyrics from Genius—no API key required! However, if you want higher rate limits and faster responses, you can optionally add Genius API credentials.

Why Use Genius API?

Setup Steps

1. Visit the Genius API Clients Page, sign in with your Genius account (or create one).
2. Click New API Client and fill in:
   • App Name: Beatra Bot (or any name)
   • App Website URL: https://localhost (placeholder is fine)
   • Redirect URI: https://localhost/callback (not used, but required)
3. Click Save and reveal your Client ID and Client Secret.
4. Copy both values and add them to your .env:
   dotenv复制

   GENIUS_CLIENT_ID=your_genius_client_id
   GENIUS_CLIENT_SECRET=your_genius_client_secret

5. Restart the bot. The Genius client will now use API authentication.

Note: Even without credentials, lyrics work perfectly! The bot automatically scrapes Genius.com and falls back to LRCLIB if needed.

Lyrics Priority

The bot fetches lyrics in this order:

1. Genius (with API key if provided, otherwise web scraping)
2. LRCLIB (free lyrics database)
3. If both fail, no lyrics button appears

YouTube Cookie Setup

YouTube may occasionally block yt-dlp with a "Sign in to confirm you're not a bot" error. To fix this, you need to provide browser cookies to yt-dlp.

Method 1: Using Browser Cookies (Recommended)

1. Open your .env file or set environment variables

2. Add one of the following based on your browser:

   env复制

   # For Chrome users
   COOKIES_FROM_BROWSER=chrome
   
   # For Firefox users
   COOKIES_FROM_BROWSER=firefox
   
   # For Edge users
   COOKIES_FROM_BROWSER=edge
   
   # For Safari users
   COOKIES_FROM_BROWSER=safari

3. Make sure you're logged into YouTube in that browser

4. Restart your bot

Note: This method automatically extracts cookies from your browser, so you need to be logged into YouTube in the specified browser.

Method 2: Using cookies.txt File

1. Install a browser extension to export cookies:

   • Chrome/Edge: Get cookies.txt LOCALLY
   • Firefox: cookies.txt

2. Go to YouTube while logged in and export cookies to a file named cookies.txt

3. Place cookies.txt in your bot's root directory (same folder as index.js)

4. Add to your .env file:

   env复制

   COOKIES_FILE=./cookies.txt

5. Restart your bot

Verifying the Fix

After setting up cookies, test with:

npm start

If you still see bot detection errors:

• Make sure you're logged into YouTube in your browser
• Try clearing your browser cookies and logging in again
• Regenerate the cookies.txt file
• Try a different browser

Security Note: Keep your cookies.txt file private and never share it, as it contains your YouTube session data.

Sharding for Large Bots (1000+ Servers)

When your bot reaches 1,000+ servers, Discord requires you to use sharding to distribute the load across multiple processes. Beatra includes a fully automated sharding system powered by Discord.js's ShardingManager.

Read the complete Sharding Guide for detailed documentation, troubleshooting, and best practices.

What is Sharding?

Sharding splits your bot into multiple instances (shards), each handling a subset of servers:

• Shard 0 might handle servers 1-1000
• Shard 1 might handle servers 1001-2000
• And so on...

Discord automatically routes events to the correct shard based on server ID.

Quick Start with Sharding

Option 1: Interactive Launcher (Recommended)

.\start.bat

Choose option [2] Sharding Mode when prompted.

Option 2: Direct Sharding Launch

.\start-shard.bat
# or
node shard.js

Option 3: Normal Mode (` | Smart-detects platform links or search keywords, queues playlists/albums, and spins up the control panel. |

| /search | Presents a paginated selection menu of YouTube matches — choose with buttons. | | /nowplaying | Drops the live embed again, including queue status, repeat/shuffle flags, and volume. | | /language | Opens a flag button wall for instant localization (cached per guild). | | /help | Gorgeous, localized feature tour + live stats and support links. |

On-embed Controls

• ⏸️ / ▶️ Pause & Resume – Auth-limited to DJs, admins, or the original requester.
• ⏭️ Skip – Jumps to the next queued item (requires at least 1 upcoming track).
• ⏹️ Stop – Clears queue, tears down voice, and locks the panel.
• ** Queue** – Renders the next 10 tracks with real-time progress bar.
• ** Shuffle** – Randomizes the queue with guard rails (min. 2 tracks).
• ** Volume** – Opens a modal allowing 0–100 input.
• ** Loop** – Cycles through loop modes: Off → Track Repeat → Queue Repeat. Track mode replays the current song endlessly; Queue mode restarts the entire queue when finished.
• ** Autoplay** – Toggles genre-based autoplay (Off → On with genre selection). When enabled, the bot automatically adds matching music from your selected genre when the queue ends, keeping the music flowing seamlessly.

All button sessions carry a short-lived signature, preventing stale interactions from previous queues.

Autoplay System

Beatra features an intelligent autoplay engine that keeps the music flowing when your queue runs out.

How It Works

1. Enable Autoplay – Click the Autoplay button on the now-playing embed
2. Choose Your Genre – Select from 20 carefully curated genres:
   • Pop, Rock, Hip-Hop, Electronic, Jazz, Classical, Metal, Country
   • R&B, Indie, Latin, K-Pop, Anime, Lo-Fi, Blues, Reggae
   • Disco, Punk, Ambient, or Random (all genres)
3. Sit Back & Enjoy – When your queue ends, the bot automatically searches and queues relevant tracks

Smart Content Filtering

The autoplay system includes sophisticated filters to ensure you only get actual music:

Duration Limits:

• ✅ Minimum: 30 seconds
• ✅ Maximum: 10 minutes (600 seconds)
• ❌ Filters out: Full movies, podcasts, long tutorials, DJ sets

Keyword Blocking: Automatically skips content containing:

• Tutorial, lesson, course, how-to, guide
• Podcast, interview, talk, speech, lecture
• Review, unboxing, reaction, gameplay
• Full movie, full album, documentary
• ASMR, audiobook, story, meditation
• Mix, compilation (long-form content)

Quality Checks:

• Filters excessive emojis (spam/clickbait indicators)
• Blocks playlist-style titles with