rave2gether

A self-hosted collaborative music queue. Users can add songs via YouTube, vote on what plays next, and depending on the configured mode, manage a coin-based economy for queue access.

How it works

The backend downloads and plays music from YouTube. A shared queue is visible to all users in the browser. Depending on the operating mode, users can vote on songs, spend coins to add or vote, and moderators/admins can manage users and coins.

---

Operating Modes

The application behaviour changes significantly based on the Mode set in the backend config.

Mode	Value	Description
Simple	0	No login required. Anyone can add songs and skip/delete. No voting.
Voting	1	No login required. Anyone can vote on songs in the queue.
UserVoting	2	Login required. Users vote on songs. Moderators can skip/delete.
UserCoin	3	Login required. Adding songs and voting costs coins. Coins regenerate over time.

User management (Admin Panel) is available in modes 2 and 3. Coin management is only available in mode 3.

---

Backend

Requirements

• Go 1.21+
• yt-dlp installed and available in $PATH
• ffmpeg installed and available in $PATH (used by yt-dlp for audio conversion)
• A YouTube Data API key

Configuration

The backend reads a config.toml file. Pass the path as the first argument when running:

./rave2gether config.toml

Full config reference:

Port     = 8081
FileDir  = "/path/to/music"   # where downloaded files are stored
YTApiKey = "YOUR_API_KEY"     # YouTube Data API v3 key
Mode     = 0                  # 0=Simple, 1=Voting, 2=UserVoting, 3=UserCoin
Secret   = "your-jwt-secret"  # required for modes 2 and 3, must not be empty

[CoinConfig]           # only used in mode 3
InitialCoins = 10      # coins each user starts with
PerVoteCoins = 1       # coins deducted per vote
PerAddCoins  = 2       # coins deducted when adding a song
MaximumCoins = 100     # coin cap for regen
RegenTime    = 60      # seconds between coin regeneration ticks

[UserConfig]                       # only used in modes 2 and 3
UserConfigDir          = "/path/to/users"   # where users.txt is stored
AllowUserRegistration  = true               # allow self-registration via /api/register
ActivateUsersByDefault = false              # if false, admin must activate new users

Building

cd backend
go build -o rave2gether ./cmd/rave2gether

API

Full API documentation is available in openapi.yaml. You can view it in any OpenAPI-compatible viewer — paste it into editor.swagger.io or use the VS Code OpenAPI extension.

---

Frontend

Requirements

• Node.js 18+

Development

The frontend proxies /api requests to http://localhost:8081 in dev mode.

cd frontend
npm install
npm run dev

Production Build

npm run build

The built files land in dist/. Serve them with any static file server, or let the backend serve them directly via its /web handler.

Tech Stack

• React 18 + TypeScript
• Vite
• Tailwind CSS v4
• React Router (HashRouter)
• Axios with JWT interceptor for automatic token refresh

---

User Management

In modes 2 and 3, users must log in. The Admin Panel (visible to admins in the header) allows:

• Listing all users
• Adding users with a username, password, role and active status
• Editing existing users (role, active status, password reset)
• Deleting users

If ActivateUsersByDefault = false, newly registered users are inactive until an admin activates them via the Admin Panel.

Coin System (Mode 3 only)

Each user starts with InitialCoins coins. Coins are deducted when adding songs (PerAddCoins) or voting (PerVoteCoins). Coins regenerate by 1 every RegenTime seconds up to MaximumCoins. Moderators and admins can set or add coins to any user via the Coin Management panel.