VectoBeat

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:

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

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

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 before committing.
4. 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.