Music Bot for Discord
VectoBeat delivers premium audio playback, meticulous observability, and a polished operations toolchain built on Python, discord.py, and Lavalink v4.
Overview · Capabilities · Architecture · Setup · Commands · Operations · Contributing
🎯 Overview
VectoBeat is a production-ready Discord music bot that emphasises audibility, runtime transparency, and administrative control. The bot uses Lavalink for audio transport, yt-dlp for multi-source ingestion, and a thoughtfully designed slash-command surface.
| ### 🎧 Audio Excellence<br><br>* Lavalink v4 with resilient reconnects<br>* Multi-source resolution (YouTube, SoundCloud, Spotify*)<br>* Adaptive embeds with live progress bars | ### 🔍 Observability<br><br>* /status and /lavalink diagnostics<br>* /voiceinfo with latency + permission audit<br>* Structured logging and error surfacing | ### 🧩 Extensibility<br><br>* Themed embed factory with single-source branding<br>* Typed configuration (Pydantic) and `.env` overrides<br>* Well documented commands and service boundaries |
* Spotify tracks are proxied via YouTube search unless a Spotify plugin is configured for your Lavalink node.
🚀 Core Capabilities
| Domain | Highlights |
|---|---|
| Playback | Randomised search results, queue autosync, manual seek, replay, loop modes, volume control, auto-resume protection, Redis-backed playlists, history-aware autoplay |
| Queueing | Paginated queue view, move/remove/shuffle, queue metadata summary, up-next projections |
| Diagnostics | /status (latency, CPU, RAM, guild footprint), /lavalink node stats, /permissions check, /voiceinfo latency+perms |
| Branding | Config-driven logos, colours, author/footers across all embeds, with overrides per guild if required |
| Error Handling | User-facing exceptions routed to ephemeral embeds, logger visibility for unexpected faults |
🧱 Architecture
| ### Runtime Stack<br><br>* discord.py AutoShardedBot for automatic horizontal scaling<br>* LavalinkManager managing node lifecycle & authentication<br>* AudioService (yt-dlp) enabling multi-source fallback<br>* EmbedFactory centralising branding assets (logo, colour palette) | ### Key Modules<br><br>* src/commands: Slash command suites (connection, playback, diagnostics, queue)<br>* src/events: Presence rotation, playback announcers, global error handling<br>* src/services: Lavalink glue & audio resolution wrappers<br>* src/configs: Typed configuration (Pydantic) with `.env` overrides |
High-level interaction map between Discord, the VectoBeat runtime, Lavalink, and upstream media sources.
Source Mermaid definition lives at docs/system_architecture.mmd; regenerate the asset with:
```bash mmdc -i docs/system_architecture.mmd -o assets/images/architecture.png -t dark ```
⚙️ Setup
1. Environment
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
- Follow INSTALL_LAVALINK.md for deployment (Docker-ready recipe).
- Enable desired source managers (YouTube/yt-dlp, SoundCloud, Spotify plugin if licensed).
- Record host, port, password, SSL and region; update
.envandconfig.yml.
- Prepare a Redis instance (single node is sufficient). Default config assumes
45.84.196.19:32768. - Set network rules so only the bot host can access Redis.
- Populate
REDIS_HOST/PORT/PASSWORD/DBin.envor adjustconfig.yml. - Tune history-driven autoplay via
AUTOPLAY_DISCOVERY_LIMITandAUTOPLAY_RANDOM_PICK(controls recommendation breadth and randomness).
.env
DISCORD_TOKEN=YOUR_BOT_TOKEN
LAVALINK_HOST=example-host
LAVALINK_PORT=2333
LAVALINK_PASSWORD=supersecret
LAVALINK_HTTPS=false
LAVALINK_REGION=eu
REDIS_HOST=45.84.196.19
REDIS_PORT=32768
REDIS_PASSWORD=
REDIS_DB=0
AUTOPLAY_DISCOVERY_LIMIT=10
AUTOPLAY_RANDOM_PICK=true
Optional: adjust config.yml for intents, shard count, embed theme.
python -m src.main
The bot registers slash commands and reports node health on startup. Review the logs for authentication or connectivity hints.
🎮 Slash Commands
| Category | Command | Description |
|---|---|---|
| Voice | /connect |
Join caller’s voice channel, auditing missing permissions and node status. |
/disconnect |
Leave voice, destroy the Lavalink player, clear queue state. | |
/voiceinfo |
Display latency, queue length, active status and permission checklist. | |
| Playback | /play <query\|url> |
Resolve search or URL, queue up to three random candidates, start automatically. |
/skip |
Skip current track; embed shows remaining queue size. | |
/stop |
Stop playback and clear queued tracks. | |
/pause / /resume |
Pause or resume; embed indicates track title. | |
/volume |
Set volume between 0 and 200%. | |
/loop |
Toggle loop mode (Off, Track, Queue). | |
/seek mm:ss |
Jump to a timestamp within the current track. | |
/replay |
Restart currently playing track from the beginning. | |
| Queue | /queue |
Paginated queue view with “Now Playing” and upcoming entries. |
/queueinfo |
Summary overview (duration, volume, loop state, up-next block). | |
/remove <index> |
Remove track by its 1-based index. | |
/move <from> <to> |
Reorder queued items. | |
/shuffle |
Shuffle queued tracks (requires ≥2). | |
/clear |
Purge the queued tracks while leaving the current song playing. | |
| Diagnostics | /ping |
Latency snapshot (gateway + uptime + shard descriptor). |
/status |
Comprehensive metrics (latency p95, guild footprint, Lavalink stats, CPU/RAM). | |
/botinfo |
Application metadata, owners, command count, runtime environment. | |
/uptime |
Formatted uptime with Discord timestamp (absolute & relative). | |
/lavalink |
Per-node statistics: players, CPU, memory, frame deficit. | |
/voiceinfo |
See above; duplicated for quick reference. | |
/guildinfo |
Guild demographics and configuration (requires Manage Guild). | |
/permissions |
Audit the bot’s channel permissions with checkmarks. | |
| Configuration | /profile show |
Display the guild’s playback profile (default volume, autoplay, announcement style). |
/profile set-volume |
Persist a default volume applied whenever the bot joins voice. | |
/profile set-autoplay |
Toggle automatic queue refill when playback finishes. | |
/profile set-announcement |
Switch between rich embeds and minimal now-playing text. | |
| Playlists | /playlist save |
Persist the current queue (optionally including the active track) to Redis. Requires Manage Server. |
/playlist load |
Load a saved playlist into the queue, optionally replacing current items. | |
/playlist list |
Enumerate playlists stored for the guild. | |
/playlist delete |
Remove a playlist from storage. Requires Manage Server. |
🧭 Operations Runbook
Health Monitoring
#### Command Diagnostics<br><br>* /status: Watch for CPU > 70%, RAM > 500MB – investigate long queues or Lavalink issues.<br>* /lavalink: Frame deficit or high Lavalink CPU indicates node saturation.<br>* /voiceinfo: Gateway latency spike implies region/regression; check Discord status. |
#### Common Actions<br><br>* No audio? Verify Lavalink source managers (YouTube/Spotify) and logs for “requires login”.<br>* Bot silent? Confirm permissions with /permissions (connect, speak, view channel).<br>* Queue stuck? Use /stop followed by /play to reset the player.<br>* No autoplay? Check Redis reachability and VectoBeat logs for “Autoplay” warnings. |
- Capture
stdoutfor VectoBeat; enable log shipping in production (ELK, CloudWatch, etc.). - Monitor Lavalink metrics: player count, CPU, memory, frame deficit.
- Regularly patch yt-dlp for source compatibility.
- Monitor Redis availability (
INFO/PING) if playlist persistence is enabled.
🤝 Contributing
Contributions are welcome! Please review CODE_OF_CONDUCT.md and follow the steps below.
- Fork the repository and clone your fork.
- Create a feature branch
git checkout -b feature/amazing-improvement. - Run
python3 -m compileall srcbefore committing. - Submit a pull request describing the motivation, approach, and testing performed.
💬 Support
- Open issues for bugs or feature requests.
- Join the community Discord for live support and roadmap discussions.
- Star the repository to support the project’s visibility.
VectoBeat — engineered for premium audio experiences and operational clarity.
