<div align="center">

Beatra v16.0 🎶

Invite the public Beatra bot • Beatra Bot Support Server • Beatra Web Dashboard • CodeShare

Project Highlights

| Capability | Details | | --- | --- | | 🎛️ Dynamic Embeds | Auto-refreshing "Now Playing" cards with cover art, platform badges, queue countdowns, and localized metadata. | | 🪄 Smart Queue | Instant mix-ins, sequential preloading, shuffle with DJ-only guardrails, and playlist collapsing to keep channels tidy. | | 🔁 Loop Modes | Three-way loop toggle: Off, Track Repeat (endless current song), or Queue Repeat (restart queue when finished). | | 🎲 Autoplay Engine | Genre-aware autoplay with intelligent filtering—select from 20 genres (Pop, Rock, Hip-Hop, Anime, Lo-Fi, etc.) and the bot automatically queues matching music when your queue ends, filtering out tutorials, podcasts, and non-music content with smart duration and keyword detection. | | 💾 Local Audio Cache | All tracks are pre-downloaded and cached locally to eliminate stream interruptions, network lag, and voice crackling—delivering buffer-free playback even during peak Discord load or ISP throttling. | | 🛡️ Resilient Playback | Voice connection watchdog, stream retry logic, idle auto-disconnect, and graceful SIGINT shutdown. | | 🧠 Localization | Cached translations via node-json-db with runtime language switching and fallback logic. | | 📜 Static Lyrics | Fetches lyrics from Genius (web scraping) with LRCLIB fallback—button-only display with pagination support. | | ⚙️ Extensible Core | Modular providers (src/YouTube.js, src/Spotify.js, src/SoundCloud.js, src/DirectLink.js) let you add more sources quickly. |generation Discord music bot crafted with discord.js v14, engineered for cinematic embeds, lossless playback, and frictionless control across desktop and mobile.

</div>

---

✨ 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

discord-musicbot/
├── commands/           # Slash command handlers (play, help, search, language, ...)
├── events/             # Button & modal controllers for playback UI
├── src/                # Core services: MusicPlayer, MusicEmbedManager, providers
├── languages/          # 21 JSON language packs
├── database/           # node-json-db store for guild language preferences
├── config.js           # Central configuration + env fallbacks
├── index.js            # Bot bootstrap, client wiring, voice auto-cleanup
├── LICENSE             # MIT License
├── PRIVACY_POLICY.md   # Data handling details
└── TERMS_OF_SERVICE.md # Acceptable use guidelines

---

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

| Setting | Location | Purpose | | --- | --- | --- | | discord.token | .env → config.discord.token | Discord bot token used for login and REST registration. | | discord.clientId | .env → config.discord.clientId | Application ID required to register slash commands. | | discord.guildId | .env → config.discord.guildId | Optional testing guild ID for <1 minute command deployment. Leave blank for global registration. | | bot.status | .env/config.js | Activity text shown as "Listening to ...". | | bot.embedColor | .env/config.js | Hex color for all embeds. | | bot.supportServer & bot.website | .env/config.js | Populates help links and README badges. | | spotify.clientId & spotify.clientSecret | .env/config.js | Enables Spotify search, playlist and album expansion. | | genius.clientId & genius.clientSecret | .env/config.js | Optional Genius API credentials for higher rate limits (works without via web scraping). | | ytdl.cookiesFromBrowser & ytdl.cookiesFile | .env/config.js | It is an optional feature to add cookies against YouTube cookie errors. |

🔐 Never commit .env to source control. Use deployment secrets in your hosting provider or create environment variables at runtime.

---

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?

| Without API Key | With API Key | | --- | --- | | ✅ Works perfectly via web scraping | ✅ Higher rate limits | | ✅ No registration needed | ✅ Faster response times | | ⚠️ May hit rate limits on heavy use | ✅ Official API support |

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:

   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 automatic