homie/ your community
Guides & help A little guidance

Music player guide

Use Homie's web remote to control Discord music playback, queues, volume, and repeat.

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

  1. Open https://music.homiebot.app and choose Continue with Discord.
  2. Search the listening-room cards and select a server shared with Homie.
  3. Join a voice channel in that server through Discord.
  4. Search for a song, playlist, or paste a YouTube URL.
  5. Use the persistent playback bar to pause, resume, revisit the previous track, skip, or stop. Room settings hold volume and repeat. Each queued track has accessible move-up, move-down, and remove buttons; dragging is also supported.

The Add music form resolves a song or playlist and adds it directly; it is not a separate search-results browser. The voice room is your actual Discord voice channel. Join that channel in Discord before adding music. Stop/disconnect and clearing the upcoming queue require confirmation.

Room settings starts collapsed on phones so the add form and queue are easier to reach. The playback bar stays at the bottom of the screen, with space reserved below the page for scrolling and keyboard navigation.

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 and prepared-track state. Connection details expands to show worker health, cache count, free disk space and gateway latency. Browser state follows Discord changes over an authenticated WebSocket. Interrupted updates disable playback controls until a fresh room state arrives; session expiry returns to sign-in. Pending additions cannot be double-submitted.

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 port 3220 or the bot and music RPC ports 3211–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 browser with an HTTP-only cookie.
  • Logging out invalidates the session and closes its existing live connections.
  • 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.

Replacement frontend and local verification

The old frontend script and stylesheet have been retired. music-web/public/index.html loads listening-room.css and the native ES modules in studio/. views.mjs renders the landing page, server cards and room; main.mjs owns session state, room navigation, live updates and actions. Shared UI primitives, icons and base styles live in web-shared/public/, served under /shared/ by both web applications. No new production packages or service processes are required.

Start the existing configured services, then npm run music-web:start. Production already has its PM2 instance; do not start a duplicate. Run npm run web-pages:check, npm run web-pages:test, and node tests/music-web.test.js for the production asset graph, browser interaction checks and web API/security checks. Browser tests use an isolated local server and test Discord/music adapters, never production queues. They use the existing development-only Playwright package and an installed Chrome/Edge/Chromium. HOMIE_TEST_BROWSER overrides the executable and HOMIE_WEB_SCREENSHOTS selects a screenshot directory.

Interactive Discord consent and audio playback remain live acceptance checks in a controlled server; simulated provider tests do not verify them.

Keep exploringEverything Homie can do Set up Homie Feature playbook