Add Lavalink music playback with slash and prefix controls

Integrate Riffy and Lavalink v4 for play, queue, join, nowplaying, and music subcommands. Add prefix shortcuts for join, leave, pause, resume, skip, stop, and volume. Separate pause and resume with synced now-playing embed buttons. Include Lavalink docker-compose service and env configuration.

Author: codebymitch

.env.example

@@ -54,5 +54,18 @@ BACKUP_DIR=./backups
 BACKUP_RETENTION_DAYS=14
 POSTGRES_RESTORE_URL=
 
+# Music (Lavalink + Riffy) — requires a Lavalink v4 server
+# Local dev: run Lavalink via docker compose (see README), then use localhost below.
+# Docker Compose bot service uses LAVALINK_HOST=lavalink instead.
+LAVALINK_HOST=localhost
+LAVALINK_PORT=2333
+LAVALINK_PASSWORD=youshallnotpass
+LAVALINK_SECURE=false
+LAVALINK_NAME=Main
+# Optional: override nodes as JSON array (for multiple Lavalink nodes)
+# LAVALINK_NODES=[{"host":"lavalink","port":2333,"password":"youshallnotpass","secure":false,"name":"Main"}]
+LAVALINK_SEARCH_PLATFORM=ytmsearch
+LAVALINK_REST_VERSION=v4
+
 # Optional Feature/API Keys
 TMDB_API_KEY=

README.md

@@ -111,7 +111,22 @@ TitanBot is fully containerized for easy deployment.
    docker-compose up -d
    ```
 
-This will start both the bot and a persistent PostgreSQL database.
+This will start the bot, PostgreSQL, and Lavalink (when music is enabled).
+
+### Music
+
+Music uses [Lavalink v4](https://github.com/lavalink-devs/Lavalink) via [Riffy](https://github.com/riffy-rb/riffy), similar to [Musicify](https://github.com/codebymitch/Musicify).
+
+1. Set in `.env`:
+   ```env
+   LAVALINK_HOST=lavalink
+   LAVALINK_PORT=2333
+   LAVALINK_PASSWORD=youshallnotpass
+   LAVALINK_SECURE=false
+   ```
+2. With Docker Compose, Lavalink is included automatically when you `docker compose up`.
+3. On Railway, deploy Lavalink separately or as another service and point `LAVALINK_HOST` at the private hostname.
+4. Use `/play <song>` from a voice channel, or `/join` to connect without playing. Prefix shortcuts: `join`, `np`, `leave`, `pause`, `resume`, `skip`, `stop`, `volume <0-100>`, or `music <subcommand>`. Use `/nowplaying` and `/queue` for status; `/music` for loop, shuffle, seek, and other controls.
 
 ### Using GitHub Container Registry
 

docker-compose.yml

@@ -10,10 +10,27 @@ services:
       - GUILD_ID=${GUILD_ID}
       - MULTI_GUILD=${MULTI_GUILD:-false}
       - DATABASE_URL=postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}
+      - LAVALINK_HOST=lavalink
+      - LAVALINK_PORT=2333
+      - LAVALINK_PASSWORD=${LAVALINK_PASSWORD:-youshallnotpass}
+      - LAVALINK_SECURE=false
       - PORT=3000
     depends_on:
       db:
         condition: service_healthy
+      lavalink:
+        condition: service_started
+    networks:
+      - titan-network
+
+  lavalink:
+    image: ghcr.io/lavalink-devs/lavalink:4
+    container_name: titanbot-lavalink
+    restart: unless-stopped
+    environment:
+      - LAVALINK_PASSWORD=${LAVALINK_PASSWORD:-youshallnotpass}
+    volumes:
+      - ./lavalink/application.yml:/opt/Lavalink/application.yml
     networks:
       - titan-network
 

lavalink/application.yml

@@ -0,0 +1,27 @@
+server:
+  port: 2333
+  address: 0.0.0.0
+
+lavalink:
+  plugins:
+    - dependency: "dev.lavalink.youtube:youtube-plugin:1.13.5"
+      snapshot: false
+  server:
+    password: "${LAVALINK_PASSWORD:youshallnotpass}"
+    sources:
+      youtube: false
+      bandcamp: true
+      soundcloud: true
+      http: true
+      local: false
+
+plugins:
+  youtube:
+    enabled: true
+    allowSearch: true
+    allowDirectVideoIds: true
+    allowDirectPlaylistIds: true
+    clients:
+      - MUSIC
+      - ANDROID_TESTSUITE
+      - WEB