A self-hosted Discord music bot with a web UI for library management and playback control.
More screenshots
 |
 |
 |
 |
 |
 |
 |
 |
 |
Theme examples
 |
 |
 |
 |
 |
 |
 |
 |
 |
 |
 |
 |
 |
 |
 |
 |
 |
 |
 |
 |
 |
 |
 |
 |
 |
 |
- Import songs — Paste a link from YouTube, SoundCloud, Spotify, Apple Music, Tidal, or Google Drive. Metadata auto-fills from the source, and admins pick which sources to enable.
- Playback — Play, pause, seek, skip, loop, and shuffle. Reorder the queue, promote songs to play next, or remove them. Full audio filter suite: 15-band equalizer, compressor, karaoke, timescale, tremolo, vibrato, rotation, distortion, channel mix, low pass, and rate.
- Metadata editing — Customize title, artist, album, cover art, tags (with colors), and per-song volume boost — all from the web UI.
- Playlists — Create private or public playlists. Smart playlists auto-populate from tags: tag a song and it joins that tag's playlist.
- Song requests — Users request songs, reviewers approve or deny in the web UI with optional DM notifications.
- Permissions — Role-based access: control who can play, manage the queue, review requests, or administer settings.
- Setup wizard — Guided first-run setup picks your server, admin roles, and sources so you're ready to go.
- Web UI — Real-time player and queue updates over WebSocket, custom themes, responsive layout, motion-powered animations with tactile clay press effects, and Discord avatar menu.
Alfira is built to be simple to own and operate. One container, one config file, one database file. No external services, no cloud dependencies — just Docker. It runs on a home NAS as comfortably as on a VPS. If you want to share the web UI with others outside your LAN, add a reverse proxy with TLS.
The web UI is the primary interface — the Discord bot handles playback, but the web app is where you browse your library, manage playlists, tweak your equalizer, and review song requests. This keeps the feature set rich without fighting Discord's UX limitations.
Alfira also makes no assumptions about what you're listening to. A pop song, an hour-long dungeon ambience, a sound effect for your TTRPG session — they're all the same shape. Use it as a music bot, a tabletop audio player, or both.
See Development Choices for the full story behind the tools and architectural decisions.
Alfira only needs Docker.
# 1. Grab the compose file and env
curl -o docker-compose.yml https://raw.githubusercontent.com/ebears/alfira/main/docker-compose.yml && curl -o .env https://raw.githubusercontent.com/ebears/alfira/main/.env.example
# 2. Edit .env with your preferred editor (vi / nano / vim / emacs / micro / code / zed)
vi .env
# 3. Start the stack — web UI at http://localhost:3001
docker compose up -d
# 4. Open the web UI, log in with Discord, and complete the setup wizard.See the Installation Guide for full details.
| Document | Description |
|---|---|
| Installation Guide | Setup, environment variables, Docker commands |
| Tech Stack | Technology stack and project structure |
| Development Choices | Tools, architecture decisions, and their why |
| Troubleshooting | Common issues and solutions |
This project is licensed under the MIT License — see the LICENSE file for details.