Alfira is a self-hosted Discord music bot with a web UI for library management and playback control, designed for a single server.
- YouTube import — Paste links to build a shared library. Full playlists are expanded automatically and duplicates are detected.
- Metadata editing — Customize title, artist, album, and cover artwork for any song.
- Tag system — Organize songs with color-coded tags. Tags autocomplete as you type and are canonicalized so
rockandRockstay together. - Playlists — Create and manage private or public playlists from your library.
- Search & filter — Find songs by title, artist, album, or tags.
- Discord voice — Play, pause, seek, and skip from the library or any playlist.
- Loop & shuffle — Loop a song or the full queue; shuffle and restore the original order.
- Per-song volume — Boost or cut volume for individual songs, from -100% to +200%.
- Equalizer & compressor — A 15-band graphical EQ and compressor, saved at the server level.
- Up Next — Add songs to a priority queue that plays immediately after the current track.
- Quick add — Paste a YouTube link straight into the queue without saving to the library.
- Override — Replace the entire queue with a new YouTube URL and start playing instantly.
- Load playlist — Queue an entire playlist from the library.
- Responsive — Works on desktop and mobile.
- Themes — Auto, light, and dark mode plus a palette of accent colors.
- Virtual scrolling — Handles large libraries without slowing down.
- Now playing bar — Persistent playback controls with a seekable progress bar.
- PWA — Install as a standalone app.
- Discord OAuth2 — Sign in with Discord; guild membership required.
- Admin roles — Gate settings, the tag editor, and audio controls behind Discord role IDs.
- WebSocket sync — Queue state, playback position, and song metadata update across all clients in real time.
- Live events — Songs and playlists added, changed, or removed propagate instantly to every connected user.
Click to see more screenshots
# 1. Copy docker-compose.prod.yml and .env.example from this repo to the folder you want the bot to live.
curl -o docker-compose.prod.yml https://raw.githubusercontent.com/ebears/alfira/main/docker-compose.prod.yml
curl -o .env.example https://raw.githubusercontent.com/ebears/alfira/main/.env.example
# 2. Rename docker-compose.prod.yml to docker-compose.yml and .env.example to .env.
cp docker-compose.prod.yml docker-compose.yml
cp .env.example .env
# 3. Configure the .env.
nano .env # or micro, zed, code, vim, etc.
# 4. Start the stack - web UI at http://localhost:8180
docker compose up -dFor public deployment with a reverse proxy and HTTPS, see the Full Installation Guide.
| Document | Description |
|---|---|
| Installation Guide | Development and production setup, Discord configuration, reverse proxy setup |
| Configuration Reference | Complete environment variables reference |
| Tech Stack | Technology stack and project structure |
| Biome Setup | Editor setup for Biome linting and formatting |
| Troubleshooting | Common issues and solutions |
This project is licensed under the MIT License — see the LICENSE file for details.