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 Lavalink v4 with resilient reconnects Multi-source resolution (YouTube, SoundCloud, Spotify*) Adaptive embeds with live progress bars

🔍 Observability /status and /lavalink diagnostics /voiceinfo with latency + permission audit Structured logging and error surfacing

🧩 Extensibility Themed embed factory with single-source branding Typed configuration (Pydantic) and `.env` overrides 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 discord.py AutoShardedBot for automatic horizontal scaling LavalinkManager managing node lifecycle & authentication AudioService (yt-dlp) enabling multi-source fallback EmbedFactory centralising branding assets (logo, colour palette)

Key Modules src/commands: Slash command suites (connection, playback, diagnostics, queue) src/events: Presence rotation, playback announcers, global error handling src/services: Lavalink glue & audio resolution wrappers src/configs: Typed configuration (Pydantic) with `.env` overrides

System Overview

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:

npx -y @mermaid-js/mermaid-cli@10.9.0 -p docs/puppeteer-config.json -t dark \
  -i docs/system_architecture.mmd -o assets/images/architecture.png

---

⚙️ Setup

1. Environment

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. Configure Lavalink

• 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 .env and config.yml.

3. Redis (Playlists & Autoplay)

• 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/DB in .env or adjust config.yml.
• Tune history-driven autoplay via AUTOPLAY_DISCOVERY_LIMIT and AUTOPLAY_RANDOM_PICK (controls recommendation breadth and randomness).

4. Bot Configuration

.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.

5. Launch

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 /status: Watch for CPU > 70%, RAM > 500MB – investigate long queues or Lavalink issues. /lavalink: Frame deficit or high Lavalink CPU indicates node saturation. /voiceinfo: Gateway latency spike implies region/regression; check Discord status.

Common Actions No audio? Verify Lavalink source managers (YouTube/Spotify) and logs for “requires login”. Bot silent? Confirm permissions with /permissions (connect, speak, view channel). Queue stuck? Use /stop followed by /play to reset the player. No autoplay? Check Redis reachability and VectoBeat logs for “Autoplay” warnings.

Recommended Monitoring

• Capture stdout for VectoBeat; enable log shipping in production (ELK, CloudWatch, etc.).
• Monitor Lavalink metrics: player count, CPU, memory, frame deficit.
• Import the bundled Grafana dashboards in docs/grafana for shard latency, node health, and slash command throughput visualisations.
• Enable the command analytics pipeline (docs/analytics.md) to push anonymised slash usage into your data warehouse.
• Wire the queue telemetry webhook (docs/queue_telemetry.md) into your status site for real-time “now playing” indicators.
• Long-running slash commands (e.g. playlist loading) now show live progress embeds so users know what’s happening.
• 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 the Contributing Guide, then follow the steps below.

1. Fork the repository and clone your fork.
2. Create a feature branch git checkout -b feature/amazing-improvement.
3. Run python3 -m compileall src and scripts/typecheck.sh before committing.
4. (Optional) Exercise queue scenarios via scripts/run_scenarios.py tests/scenarios/basic_queue.yaml when touching playback logic.
5. Regenerate the slash-command reference via python scripts/generate_command_reference.py before publishing docs changes.
6. Spin up the local sandbox stack via docker compose -f docker-compose.local.yml up (see docs/local_sandbox.md) when you need Lavalink/Redis/Postgres locally.
7. Tune search caching via the cache section in config.yml to reduce repeated Lavlink lookups.
8. Adjust dynamic search limits via search_limits to balance latency vs. search breadth.
9. 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.

- Profile the event loop with `python scripts/profile_event_loop.py` (requires pyinstrument) and inspect `profiles/event-loop-profile.html` for hotspots.