Homie Music Web Player

The music website at https://music.homiebot.app is a remote control for Homie's Discord playback. It does not stream or proxy music to the browser. Members continue listening inside their Discord voice channel.

Member workflow

Open https://music.homiebot.app and choose Continue with Discord.
Select a server shared with Homie.
Join a voice channel in that server through Discord.
Search for a song, playlist, or paste a YouTube URL.
Use the live player to pause, resume, revisit the previous track, skip, stop, change repeat or volume, shuffle, clear upcoming songs, remove songs, or drag them into a new order.

Playback notices and errors are posted in the connected voice channel's built-in text chat, regardless of whether playback was started from Discord or the website.

The player displays the current artwork, requester, elapsed progress, prepared-track state, worker health, cache count, free disk space, and Discord gateway latency. Browser state follows Discord changes over an authenticated WebSocket.

Members can only add music from the voice channel they currently occupy. Once a queue exists, browser controls require the member to be in Homie's current voice channel. The dedicated music controller repeats this live check for every action; browser-supplied permission claims are never trusted.

Production configuration

The PM2 process is homie-music-web. It binds only to 127.0.0.1:3213 and has a 400 MB memory restart limit.

Required Discord application values already used by Homie's dashboard:

CLIENT_ID
DISCORD_CLIENT_SECRET

The website reads only these selected OAuth values from .env; it does not load or use the Discord bot token. Its production public URL defaults to https://music.homiebot.app and can be changed with HOMIE_MUSIC_WEB_PUBLIC_URL.

In the Discord Developer Portal, add this exact OAuth2 redirect:

https://music.homiebot.app/auth/callback

Configure the production TLS reverse proxy so only https://music.homiebot.app forwards to http://127.0.0.1:3213. WebSocket upgrades must be enabled for /ws. Never proxy the internal database, bot RPC, or music RPC ports 3210–3212.

Security behaviour

Discord OAuth requests only identify and guilds.
Sessions expire after 12 hours and use HTTP-only, Secure, SameSite=Lax cookies in production.
OAuth state expires after 10 minutes and is tied to the initiating client.
State-changing requests require the exact site origin, JSON content type, and a per-session CSRF token.
APIs are rate limited and restricted to the signed-in member's servers shared with Homie.
WebSocket subscriptions require the same authenticated session, origin, guild access, and CSRF token.
The music controller fetches current Discord membership and voice state before acting.
Browser actions are written to Homie's music action audit history.

Production checks

pm2 describe homie-music-web
pm2 logs homie-music-web --lines 100

From the production machine, the local health check should return JSON with ok: true:

http://127.0.0.1:3213/healthz

After the public proxy and Discord redirect are configured, verify login, server selection, WebSocket live updates, same-channel rejection, song addition, queue reordering, and logout at https://music.homiebot.app.

If login returns a redirect error, confirm the Discord Developer Portal URI matches exactly, including HTTPS and /auth/callback. If the page reports no shared servers, confirm Homie and the signed-in account are both still members. If controls are disabled, join Homie's Discord voice channel and allow the next live update to arrive.