![VectoBeat Logo](https://raw.githubusercontent.com/VectoDE/VectoBeat/main/assets/images/logo.png)

**Music Bot for Discord**

VectoBeat delivers premium audio playback, meticulous observability, and a polished operations toolchain built on **Python**, **discord.py**, and **Lavalink v4**.

[![Discord Support](https://img.shields.io/badge/Discord-Join%20Support-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/DtHPAEHxZk) [![GitHub Stars](https://img.shields.io/github/stars/VectoDE/VectoBeat?style=for-the-badge&logo=github&color=yellow)](https://github.com/VectoDE/VectoBeat/stargazers) [![Python](https://img.shields.io/badge/Python-3.11+-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/) [![License](https://img.shields.io/badge/License-Apache%202.0-0A0A0A?style=for-the-badge)](https://www.apache.org/licenses/LICENSE-2.0)

 [![Quality Gate Status](https://github.com/VectoDE/VectoBeat/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/VectoDE/VectoBeat/actions/workflows/test.yml)[![Build Status](https://github.com/VectoDE/VectoBeat/actions/workflows/build.yml/badge.svg?branch=main) ](https://github.com/VectoDE/VectoBeat/actions/workflows/build.yml)[![Release & Publish](https://github.com/VectoDE/VectoBeat/actions/workflows/deploy.yml/badge.svg?branch=main) ](https://github.com/VectoDE/VectoBeat/actions/workflows/deploy.yml)[![Documentation Guard](https://github.com/VectoDE/VectoBeat/actions/workflows/docs.yml/badge.svg?branch=main) ](https://github.com/VectoDE/VectoBeat/actions/workflows/docs.yml)[![Security Audit](https://github.com/VectoDE/VectoBeat/actions/workflows/security.yml/badge.svg?branch=main)](https://github.com/VectoDE/VectoBeat/actions/workflows/security.yml)

* * *

[Overview](#overview) · [Capabilities](#capabilities) · [Architecture](#architecture) · [Setup](#setup) · [Commands](#slash-commands) · [Operations](#operations-runbook) · [Contributing](#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._

![VectoBeat System Architecture](https://raw.githubusercontent.com/VectoDE/VectoBeat/main/assets/images/architecture.png)

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](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](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._

VectoBeat

VectoBeat delivers premium audio playback, meticulous observability, and a polished operations toolchain built.

Voting for VectoBeat

Do you want to support us?