Play music from YouTube, Spotify, and Deezer directly in your Discord voice channels. Fast autocomplete search, clean single-message button controls, and zero channel spam.
Audio never touches the main Python bot process. A dedicated Lavalink node handles decoding and playback streaming while Alfred manages your server requests.
Stream directly from YouTube, Spotify, and Deezer. Supports tracks, full albums, playlists, and raw audio URLs.
Instant search suggestions right inside Discord's slash command input. Filter by track name, artist, album, or playlist.
Single-message interactive UI. Pause, Skip, cycle Loop modes, and Stop using Discord buttons with instant state updates.
Alfred never speaks unless spoken to. Every embed is a direct slash reply. Buttons expire cleanly after 3 minutes of inactivity.
Deafening yourself automatically pauses playback when you are the sole listener. Alfred disconnects when voice channels empty.
Includes a companion cipher server that executes obfuscated YouTube player scripts to resolve streaming signatures reliably.
`/play` connects to your voice channel automatically - no `/join` needed. Try clicking the buttons below to test the reactive panel state machine.
| Group | Command | Description |
|---|---|---|
| MUSIC | /play | Add track, playlist or URL to queue with auto voice join |
| MUSIC | /search | Live autocomplete across tracks, artists, and playlists |
| QUEUE | /queue | Open the interactive button panel and track list |
| QUEUE | /skip | Move forward to the next queued track |
| QUEUE | /remove | Drop a specific track from the queue index |
| VOICE | /leave | Disconnect bot from voice and clear player state |
| OWNER | /stats | Display Lavalink node health and memory metrics |
| OWNER | /info | Show running bot versions, plugins, and Lavalink info |
clientId and clientSecret in configuration.masterDecryptionKey is provided.
Alfred isolates control logic from audio transport, guaranteeing high responsiveness even under heavy server load.
flowchart TD
subgraph Discord["Discord Platform"]
User["User / Discord Client"]
VC["Voice Channel"]
end
subgraph Bot["Alfred Bot"]
Hikari["hikari Gateway & lightbulb"]
Service["Alfred Service & Player State"]
end
subgraph Node["Lavalink Audio Node (JVM)"]
Lavalink["Lavalink Server Engine"]
Plugins["LavaSrc · LavaSearch · YouTube Plugin"]
end
subgraph Daemon["Signature Daemon"]
Cipher["yt-cipher Container"]
end
subgraph Sources["Audio Sources"]
YT["YouTube"]
SP["Spotify"]
SC["SoundCloud / Deezer / Bandcamp"]
end
User -->|"Slash commands & panel buttons"| Hikari
Hikari --> Service
Service -->|"REST / WebSocket (lavalink.py)"| Lavalink
Lavalink --- Plugins
Plugins -->|"JavaScript decipher requests"| Cipher
Plugins -->|"Audio stream extraction"| Sources
Lavalink ==>|"Direct voice UDP stream"| VC
Choose Docker Compose for production deployments or uv for local development.
# 1. Clone & prepare environment files cp .env.example .env cp lavalink/application.yml.example lavalink/application.yml # 2. Set DISCORD_TOKEN & CIPHER_PASSWORD in .env # Linux permissions (first run only): chown -R 322:322 lavalink/logs lavalink/plugins # 3. Start all three services (yt-cipher, Lavalink, Alfred) docker compose up -d
yt-cipher, Lavalink, and the bot in ordered sequence. To rebuild after local edits, run docker compose up -d --build bot.
# Requires Java 21+ for Lavalink winget install --id Microsoft.OpenJDK.21 -e # Terminal 1: Run Lavalink node .\scripts\lavalink.ps1 # Terminal 2: Run Alfred bot with uv uv sync --frozen uv run alfred
LAVALINK_HOST=127.0.0.1. Run checks with uv run pytest and uv run ruff check ..
# Check VPS deployment guide for machine hardening & OAuth git clone https://github.com/nauqh/alfred.git /opt/alfred cd /opt/alfred # Follow docs/deploy.md for YouTube OAuth token generator # and systemd/docker restart configurations
Comprehensive guides covering production operations, internal design specs, and multi-node clusters.
Step-by-step VPS server preparation, secrets management, automatic updates, and YouTube OAuth authentication.
In-depth architectural overview of state transitions, voice listener tracking, and Lavalink packet event handlers.
Product requirements, acceptance criteria, test assertions, and source compatibility matrices.