Music Bot for Discord

VectoBeat delivers premium audio playback, plan-aware control panel workflows, concierge/success pod tooling, and meticulous observability built on Python, discord.py, Lavalink v4, and a Next.js control panel.

---

Overview · Capabilities · Architecture · Setup · Commands · Operations · Contributing

---

🎯 Overview

VectoBeat is a production-ready Discord music bot that emphasises audibility, runtime transparency, and administrative control. Lavalink powers audio transport and yt-dlp handles multi-source ingestion while the control panel enforces plan rules, queue sync, concierge/success pod workflows, and compliance exports.

🎧 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 Queue sync + telemetry webhooks with plan-aware redaction Structured logging and error surfacing Vercel Speed Insights & Web Analytics

🧩 Extensibility Themed embed factory with single-source branding Typed configuration (Pydantic) and `.env` overrides Control panel bridges for concierge/success pod + server settings Well documented commands, service boundaries, and plan enforcement

^* 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 scrubbing, 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
Control Panel & Ops	Queue sync + telemetry webhooks, plan-aware `/settings`, concierge/success pod lifecycle, compliance exports, regional routing
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 with plan-aware settings, concierge/success pod, and audit bridges LavalinkManager managing node lifecycle & authentication AudioService (yt-dlp) enabling multi-source fallback QueueSync + Telemetry services mirroring state to the control panel and webhooks Next.js App Router control panel with Prisma/MySQL and durable queue sync store

Key Modules bot/src/commands: Slash command suites (connection, playback, diagnostics, queue, ops) bot/src/services: Lavalink glue, queue sync, concierge client, status API frontend/app/api: Control-panel APIs (account, concierge, security/audit, bot bridges) frontend/lib: Auth, plan capabilities, durable queue store

System Overview

High-level interaction map between Discord, the VectoBeat runtime, Lavalink, and upstream media sources.

A prose + Mermaid breakdown of the data flow lives in docs/architecture.md (source: docs/system_architecture.mmd). Regenerate the 4K system diagram with:

npx -y @mermaid-js/mermaid-cli -i docs/system_architecture.mmd -o assets/images/architecture.png -w 3840 -H 2160 -b transparent

For the full documentation index (deployment, ops, troubleshooting, and API guides), start at docs/README.md.

---

⚙️ Setup

Keep a single root .env for bot + frontend; CI fails on stray env files.

Compose builds use the repo root as context; ensure plan-capabilities.json and Prisma schema stay present when building images.

Never commit secrets: .env is gitignored. Rotate Discord/Stripe/SMTP keys if credentials leak.

1️⃣ Env (root only) Copy .env.example → .env. One file powers bot + frontend. cp .env.example .env python3 scripts/validate_env.py Before publishing invites, swap the hero badge client IDs for your live bot.

2️⃣ Local dev Bot: cd bot && python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt && set -a && source ../.env && set +a && python -m src.main Frontend: cd frontend && npm install && set -a && source ../.env && set +a && npm run dev -p 3050

3️⃣ Docker (parity) Full stack with MySQL, Redis, Lavalink. cp .env.example .env docker compose up -d --build docker compose logs -f frontend bot

Services: frontend 3050, bot status 3051, bot metrics 3052, Lavalink 2333, MySQL 3306, Redis 6379.

Compose builds from frontend/Dockerfile and bot/Dockerfile using the repo root as context; healthchecks restart until dependencies are ready.

Docs index, deployment, ops, and troubleshooting guides live under docs/.

---

🎮 Commands

Use /help in Discord for in-bot guidance. Categories below list every command with a short description (see docs/command_reference.md for the generated source).

Info: Spotify tracks are proxied via YouTube search unless a Lavalink Spotify plugin is configured.

Warning: Queue control commands enforce DJ/Manage perms when collaborative mode is off.

Heads up: Concierge and scaling/chaos commands are gated by plan tier and authenticated bot API calls.

Category	Command	Description
Voice	/connect	Join caller’s voice channel (permission + node checks).
	/disconnect	Leave voice, destroy player, clear queue state.
	/voiceinfo	Latency, queue length, active status, permission checklist.
Playback	/play	Search/URL resolve (YouTube/SoundCloud/Spotify), enqueue, autoplay.
	/nowplaying	Live now-playing embed with progress.
	/skip	Skip current track.
	/stop	Stop playback and clear queue.
	/pause	Pause playback.
	/resume	Resume playback.
	/volume	Set volume (0–200%).
	/volume-info	Show current and default volume.
	/loop	Toggle Off/Track/Queue loop modes.
	/timeshift	Move to a timestamp within the current track (mm:ss).
	/replay	Restart current track.
Queue	/queue	Paginated queue with now-playing and up-next.
	/queueinfo	Queue summary (duration, loop, up-next).
	/shuffle	Shuffle queued tracks (≥2).
	/move	Reorder items by position.
	/remove	Remove track by 1-based index.
	/clear	Clear queued tracks.
Playlists	/playlist save	Persist current queue as a named playlist.
	/playlist load	Load a saved playlist (append/replace).
	/playlist list	List saved guild playlists.
	/playlist delete	Remove a saved playlist.
	/playlist sync	Attach an external URL to a saved playlist.
Profiles	/profile show	Display default volume/autoplay/embed style.
	/profile set-volume	Persist default volume for the guild.
	/profile set-autoplay	Toggle autoplay when queue finishes.
	/profile set-announcement	Choose between rich embeds and minimal text.
DJ Controls	/dj add-role	Grant DJ permissions to a role.
	/dj remove-role	Revoke DJ permissions from a role.
	/dj clear	Open queue control by clearing DJ roles.
	/dj show	Display configured DJ roles and actions.
Diagnostics & Help	/ping	Gateway latency/uptime snapshot.
	/status	Latency p95, guild footprint, Lavalink stats, CPU/RAM.
	/lavalink	Per-node stats (players, CPU, memory, frame deficit).
	/guildinfo	Guild demographics and configuration.
	/permissions	Audit bot channel permissions with remediation tips.
	/botinfo	Application metadata and runtime.
	/uptime	Formatted uptime with timestamps.
	/help	Grouped list of available commands.
Automation & Ops	/concierge request	File a concierge ticket for migrations/incidents (Growth+).
	/concierge usage	Show remaining concierge hours this cycle.
	/concierge resolve	Staff: resolve a concierge ticket.
	/success request	Submit a request to your success pod (Scale).
	/success status	View recent success pod lifecycle updates.
	/success contact	Show your account manager and escalation path.
	/success acknowledge	Staff: acknowledge and assign a success pod request.
	/success schedule	Staff: schedule a success pod session.
	/success resolve	Staff: resolve a success pod request.
	/success set-contact	Staff: update account manager contact info.
	/settings queue-limit	Adjust queue cap (plan-aware).
	/settings collaborative	Toggle collaborative queue (DJ/Manage perms enforced).
	/scaling evaluate	Force an autoscaling evaluation.
	/scaling status	Show scaling metrics and last signal.
	/chaos run	Trigger a chaos experiment immediately.
	/chaos status	Show recent chaos drills and schedule.
	/compliance export	Download compliance-ready JSONL events (admins).

---

🧭 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.
• Keep the queue sync publisher healthy (docs/queue_sync.md) so the control panel reflects live queues.
• 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.

---

🛡️ Security & Compliance

Enterprise customers rely on VectoBeat to demonstrate residency, threat mitigation, and secure coding practices. Two canonical documents now live under docs/security:

• Threat Model (docs/security/threat-model.md) – enumerates assets, attacker goals, trust boundaries, and mitigation strategies for secrets, automation, and residency.
• Secure Coding Guidelines (docs/security/secure-coding-guidelines.md) – covers encryption standards, secret rotation cadence, rate limiting rules, CSRF/CSP expectations, input validation, and incident-response hooks.
• Privacy-by-Design Controls (docs/security/privacy-controls.md) – documents retention policies, delete/export workflows, and localized consent notices embedded in the control panel.
• Compliance Export Jobs (docs/backend/compliance-export-jobs.md) – explains how scheduled/on-demand export jobs pull queue/moderation/billing data and deliver encrypted payloads via S3/SFTP.
• Queue-Based Processing (docs/backend/queue-processing.md) – covers Redis-backed job queues for analytics exports and embed override propagation, plus worker configuration.
• Observability Metrics (docs/observability/metrics.md) – enumerates shard load, Lavalink health, automation success, API error budgets, and concierge SLA metrics + alerting guidance.

Keep both artifacts in sync with your deployments. Any new surface (API route, slash command, or residency zone) must be reflected in the threat model and inherit the published secure coding rules.

---

🤝 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. Bot checks: cd bot && python -m compileall src && pytest -q (plus ../scripts/typecheck.sh if pyright is installed).
4. Frontend checks: cd frontend && npm run lint && npm run test:server-settings.
5. (Optional) Exercise queue scenarios via python scripts/run_scenarios.py bot/tests/scenarios/basic_queue.yaml when touching playback logic.
6. Regenerate slash-command docs if commands change: python scripts/generate_command_reference.py (see docs/command_reference.md).
7. Update diagrams when docs/system_architecture.mmd changes: npx -y @mermaid-js/mermaid-cli -i docs/system_architecture.mmd -o assets/images/architecture.png -w 3840 -H 2160 -b transparent.
8. Spin up the sandbox via docker compose up -d --build (see docs/local_sandbox.md) to verify Lavalink/Redis/MySQL locally.
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.