Turn your Home Assistant installation into a phone-friendly music quiz for local or remote guests
Beatify is an open-source Home Assistant integration that plays music through supported speakers while participants submit answers from their phones. This guide covers the prerequisites, the recommended HACS installation, the documented manual installation alternative, first-time configuration, local verification, and the workflow for hosting a game. Once Beatify works correctly on your local network, we will show how to provide remote HTTP access with Localtonet without configuring inbound router port forwarding or requiring a public IP address.
📋 What's in this guide
How Beatify works inside Home Assistant
Beatify is a self-hosted music party game implemented as a Home Assistant custom integration. A host chooses a speaker, music source, playlist, and game settings. Participants then join from their phones and compete by guessing a song's release year or, in Title & Artist mode, entering the track title and artist.
The important architectural detail is that Beatify does not run as a separate standalone server with its own documented listener. Its browser interfaces are served through the existing Home Assistant HTTP listener. In a typical installation using Home Assistant's documented default web port, the local base address resembles http://YOUR-HA-IP:8123. Beatify adds routes beneath that address, including the host interface at /beatify/admin and the guest interface at /beatify/play.
Music does not play through each participant's phone. Beatify controls a supported speaker through Home Assistant, while phones function as game controllers. This arrangement keeps the shared audio in the room and avoids asking every guest to install a dedicated app or create a Beatify account.
Host access and player access are different
Beatify deliberately separates host controls from the player experience. The host opens the sidebar launcher or visits /beatify/admin. On a device without an active Home Assistant session, opening that route redirects the user to the normal Home Assistant login flow. After authentication, that browser can access the game controls.
The player route at /beatify/play is designed for guests. Players can join without a Home Assistant login, which is why sharing a Beatify game is convenient but also why exposure must be deliberate. Anyone who can reach an active public player URL may be able to reach the guest joining interface. The host should stop public access when it is no longer needed.
The available project instructions install Beatify into Home Assistant. They do not establish a separate Beatify Docker image, standalone server command, independent TCP port, or separate service manager. Configure and verify Home Assistant first, then install Beatify into that working system.
Prerequisites and compatibility checks
Check the complete playback chain before installing the integration. A successful setup needs a compatible Home Assistant version, at least one supported speaker path, and a usable music source. Installing the files alone will not make a game playable if the speaker or provider cannot play requested tracks.
Home Assistant version
The current Beatify repository documentation specifies Home Assistant 2025.1 or newer. An older project website page displays a lower 2024.1 requirement, so the safer requirement for a new installation is the newer value stated in the current repository documentation. If your Home Assistant installation is older than 2025.1, update it through the supported update process for your Home Assistant installation method before proceeding.
Back up Home Assistant before updating it or installing a custom integration. The exact backup and update procedure depends on whether you use Home Assistant OS, Container, Core, or another supported deployment model, so this guide does not invent one universal command for those different environments.
Supported speaker path
Beatify requires a speaker available through Music Assistant, Sonos, or Alexa. Music Assistant can also provide a path to speaker ecosystems that Beatify does not control directly. In particular, Chromecast, Nest, and HomePod devices are documented as working through Music Assistant.
Confirm that Home Assistant can already see and control the intended speaker. If normal playback or device control is unreliable before Beatify is installed, resolve that underlying integration problem first. Beatify cannot compensate for a disconnected speaker, a broken media integration, or a device that Home Assistant cannot address.
Music source
Beatify supports music from Spotify, Apple Music, YouTube Music, Tidal, Deezer, and Amazon Music, subject to the speaker and provider arrangement used in the installation. It can also use a personal library made available through Music Assistant, including Plex, Jellyfin, or local files.
Most streaming services require a plan that permits selecting and playing a specific track on demand. For example, the project documentation warns that Spotify Free cannot provide the required on-demand behavior. Beatify v4.4.0 added a documented exception named ytmusic_free, which can stream YouTube Music without a Premium account after that provider has first been installed in Music Assistant. This is version-specific behavior, so verify that Beatify 4.4.0 or a later compatible release is installed before expecting that option.
| Requirement | What to verify | Why it matters |
|---|---|---|
| Home Assistant | Version 2025.1 or newer | That is the current minimum stated by the Beatify repository documentation. |
| Speaker | Available through Music Assistant, Sonos, or Alexa | Beatify sends shared game audio to a supported speaker rather than each guest phone. |
| Streaming provider | Account can play a selected track on demand | Free tiers that prevent on-demand selection generally cannot support the required playback workflow. |
| Personal library | Library is available through Music Assistant | Plex, Jellyfin, and local files can provide music without relying on a commercial streaming subscription. |
| Guest devices | Modern browser and network reachability | Participants use the browser-based player page and do not install a separate Beatify app. |
| Remote access | Local Beatify routes work before tunneling | A tunnel can publish a reachable local service, but it cannot repair an incomplete Beatify or Home Assistant configuration. |
Beatify must request particular tracks during a quiz. A provider tier that only offers shuffled or restricted playback may not satisfy that requirement. Use a compatible paid plan, a personal library through Music Assistant, or the documented ytmusic_free path introduced in Beatify 4.4.0.
Install Beatify through HACS or manually
HACS is the recommended installation route because Beatify is available in its default store. There is no need to add a custom HACS repository for the normal recommended workflow. Use the manual Git installation only when you intentionally manage custom component files yourself and have command-line access to the Home Assistant configuration storage.
Recommended method: install from the default HACS store
Open HACS in Home Assistant
Sign in to Home Assistant with an account that can manage integrations and open HACS. This guide assumes HACS is already installed and functioning. Beatify's documentation does not make HACS itself part of the Beatify package.
Search for Beatify
Use the HACS search interface and search for Beatify. It is listed in the default HACS store, so the recommended procedure does not require entering a separate repository URL.
Download the integration
Open the Beatify result and select the HACS download action. Allow HACS to finish placing the integration files before leaving the page or restarting Home Assistant.
Restart Home Assistant
Restart Home Assistant after the download. This restart is part of the documented installation sequence and allows Home Assistant to discover the newly installed custom integration.
Do not skip the restart even if HACS reports that the download completed. A completed file download and an integration loaded by Home Assistant are separate states. If Beatify does not appear when you try to add it, first confirm that the restart actually completed.
Manual installation with Git
The Beatify repository also documents a command-line installation. Run these commands only from an environment where /config is the actual Home Assistant configuration directory and where Git is available. The project does not document one universal way to obtain a shell because that varies among Home Assistant installation types.
cd /config/custom_components
git clone https://github.com/mholzi/beatify.git beatify
# Restart Home AssistantThe final comment is an instruction to restart Home Assistant, not a restart command. Use the normal restart operation supported by your Home Assistant deployment. Do not paste an unrelated service command from another installation model, since Home Assistant OS, Container, and Core environments are managed differently.
Use either the recommended HACS installation or the documented manual Git installation for a particular Beatify directory. Mixing HACS-managed files with an independently cloned repository can make ownership and future updates unclear. If an earlier installation already exists, back up the configuration and establish how it was installed before replacing files.
Beatify does not provide separate documented installation instructions for a standalone Docker container. If Home Assistant itself runs in a container, Beatify is still installed as a Home Assistant custom integration using storage that maps to the Home Assistant configuration directory. Do not create a second container or expose an invented Beatify port.
Add and configure the Beatify integration
Downloading the component is only the installation phase. The next phase is adding Beatify to Home Assistant and completing its first-run wizard. Keep your supported speaker and music provider ready so the wizard can build a usable game configuration.
Open Devices & Services
In Home Assistant, go to Settings, then Devices & Services. This is the standard integration management area used by Beatify's documented configuration flow.
Add Beatify
Select Add Integration, search for Beatify, and select it. If it is absent, confirm that the HACS download or manual clone completed and that Home Assistant was restarted afterward.
Open the Beatify launcher
Look for Beatify in the Home Assistant sidebar, open it, and select Open Beatify. The launcher opens the game in a full-screen tab without the normal Home Assistant interface around it.
Choose the speaker
On the first visit, use the guided wizard to select the supported speaker that will play the quiz audio. If the expected speaker is missing, return to Home Assistant or Music Assistant and resolve its availability before continuing.
Choose the music service and playlist
Select the configured music source and a playlist. Confirm that the source can play chosen tracks on demand. A personal Plex, Jellyfin, or local-file library must be available through Music Assistant to be used in this workflow.
After the initial wizard, returning hosts normally go directly to the Ready to host screen rather than repeating all first-run selections. Configuration choices available in an individual release may evolve, so use the labels presented by the installed Beatify version instead of relying on options from an older screenshot.
If the sidebar item is missing
Restart Home Assistant and check again. Beatify's documentation specifically identifies a restart as the first response when the sidebar entry is absent. Also verify that the integration was added under Devices & Services rather than only downloaded through HACS.
You can test the documented direct admin route if the sidebar remains unavailable:
http://YOUR-HA-IP:8123/beatify/admin
Replace YOUR-HA-IP with the local address you already use to reach Home Assistant. Port 8123 is the evidenced default endpoint for this workflow, but an existing reverse proxy or customized Home Assistant HTTP configuration may use a different address. Use the listener that actually works in your deployment rather than forcing the example value.
Start your first Beatify music quiz
Test the first game with one host browser and at least one player phone. This small rehearsal confirms the complete chain: Home Assistant loads Beatify, the host can authenticate, the guest can join, the selected speaker plays music, and answers reach the active game.
Open Beatify as the host
Select Beatify from the Home Assistant sidebar and then select Open Beatify, or browse directly to /beatify/admin. Complete the normal Home Assistant login if the browser is not already authenticated.
Review the game setup
Confirm the speaker, music service, and playlist selected in the wizard. Make sure the speaker is powered on, reachable, and set to a suitable volume before guests join.
Display the guest QR code
On the Ready to host screen, show the QR code. A participant scans it with a phone, opens the browser page, and enters a player name. No separate Beatify account or app is required for the player workflow.
Confirm players in the lobby
Wait until the expected participants appear in the Beatify lobby. If a phone cannot join, test the player route directly on the same local network before changing speaker or music-provider settings.
Start the game
Select Start game when the lobby is ready. Confirm that the first track begins on the chosen speaker and that the player interface accepts the expected year or title-and-artist response.
What authentication does and does not protect
Any Home Assistant user account can host according to Beatify's current documentation. Beatify does not distinguish between Home Assistant administrator and non-administrator accounts for this host role. Host actions still require a valid Home Assistant login, preventing an unauthenticated visitor from using the admin route to begin games, control playback, operate connected game effects, or end the game.
Players remain unaffected by that login gate. The guest route stays password-free to support QR-code entry. This is intentional application behavior, not an authentication failure. Treat the player URL as an invitation to the active game and share it only with intended participants.
Verify Beatify locally before adding remote access
Remote publishing should be the final integration step, not a troubleshooting shortcut. If Beatify fails on the local network, placing a tunnel in front of it adds another variable without solving the underlying issue.
Check the documented browser routes
| Route | Expected audience | Verification |
|---|---|---|
/beatify/admin |
Host | Opens the host interface and requires the normal Home Assistant login when the browser is not authenticated. |
/beatify/play |
Players | Opens the guest participation interface without requiring each player to hold a Home Assistant account. |
/beatify/static/dashboard.html |
Browser display | Confirms that the documented Beatify dashboard path is being served by the Home Assistant listener. |
Test the host route in your normal browser. Then use a private browsing window or a second device to understand what an unauthenticated visitor sees. The host route should invoke Home Assistant authentication, while the player route is intentionally available without that login.
Run a complete local round
A page loading successfully is not enough to verify a music game. Start a short local session and check each dependency in sequence:
- The Beatify sidebar launcher or direct admin route opens.
- The host can authenticate through Home Assistant.
- The selected speaker appears in Beatify.
- The selected provider or personal library is available.
- A guest phone can open the player page and join the lobby.
- The game starts and the intended track plays through the speaker.
- The guest can submit an answer and continue through the round.
If all of these checks pass on the local network, you have isolated the application layer from the remote-access layer. Any later external failure can then be investigated through the Home Assistant listener, Localtonet client, tunnel status, or public address without questioning whether Beatify itself was installed correctly.
Note the local IP address and port that successfully load Home Assistant from the device where the Localtonet client will run. The client must be able to reach that exact target. Do not assume that an address reachable from your laptop is automatically reachable from another server, container, or isolated network.
Provide remote Beatify access with a Localtonet HTTP tunnel
Once local verification is complete, an HTTP tunnel can make the Home Assistant listener reachable to guests outside the local network. With Localtonet, our client application establishes an outbound connection from the selected device to a relay server. This avoids inbound router port forwarding, a public IP requirement, VPN setup, and inbound firewall changes.
The tunnel targets the Home Assistant local IP address and port because Beatify is served through Home Assistant. It does not target a separate Beatify port. If the verified local endpoint is http://192.0.2.10:8123, for example, the target values are the corresponding local address and port. Use your real private address rather than copying that documentation-only example.
An HTTP tunnel publishes the service at a public HTTPS address. HTTP and File Server tunnels can use a random subdomain, a custom subdomain, or a custom domain through the available Process Type choices. Exact custom-domain DNS requirements should be taken from the current dashboard and documentation because they can change and are not established by the evidence for this guide.
Install and run the Localtonet client
Install our client application on the Home Assistant device or on another device that can reach the verified Home Assistant IP address and port. Keep the client running whenever remote Beatify access is required. Current installation packages and platform-specific instructions should be obtained from our official download and documentation pages.
Authenticate the intended device
Select or authenticate the device using its device-specific token. Never copy a token into a public guide, screenshot, chat, or shared configuration. Tokens identify the client device and must be treated as credentials.
Select an available relay server
Choose an available relay server or region from the current Localtonet dashboard. Do not hardcode a server code from another user's setup because availability can vary by account, plan, region, or current platform configuration.
Create an HTTP tunnel to Home Assistant
Create the appropriate HTTP tunnel and enter the local IP address and port that passed local verification. For a standard Home Assistant listener this is commonly port 8123, but use the real listener in your deployment. Select the desired Process Type from the options available to your account.
Start and test the tunnel
Creating a tunnel does not start it. Select Start, wait until the chosen client is connected and the tunnel is running, then open the assigned public HTTPS address. Test the Beatify player route from a device that is not using the local network.
The general public player address is formed from the assigned tunnel address and Beatify's player path:
https://YOUR-ASSIGNED-PUBLIC-ADDRESS/beatify/playThe host route follows the same pattern:
https://YOUR-ASSIGNED-PUBLIC-ADDRESS/beatify/adminDo not publish a private assigned address in documentation or screenshots without reviewing whether it should be shared. The player address is intended for invited participants, while the admin address should be used only by authenticated hosts.
For current dashboard details, consult our Localtonet HTTP tunnel documentation . The dashboard is authoritative for available server selections, Process Type choices, and account-specific options.
Beatify routes are served by the same Home Assistant HTTP endpoint. Tunneling that listener may make other Home Assistant paths reachable at the public address as well. Home Assistant authentication still protects authenticated areas, but the tunnel should not be treated as a path-level Beatify-only security boundary. Review the full exposed service, maintain strong Home Assistant credentials, and stop the tunnel when remote access is not needed.
Test from a genuinely external connection
A browser on the same LAN may hide routing or name-resolution problems. Disable Wi-Fi on a test phone and use its mobile connection, or test from another trusted external network. Open the public player path, join with a temporary name, and confirm that the lobby updates on the host screen.
Also test the public admin path in a private browser window. It should invoke the Home Assistant login flow. Do not enter credentials into a page if the address is not the exact public address assigned through your Localtonet configuration.
Security and safe operating practices
Remote access changes Beatify from a local party service into an internet-reachable application path. The convenient guest experience remains intentionally unauthenticated, while host controls depend on Home Assistant authentication. Safe operation therefore requires attention to both the application behavior and the tunnel lifecycle.
Do not expose more than the event requires
Keep the tunnel stopped during setup work unless an external test is necessary. Start it shortly before remote participants need access, and stop it when the game concludes. Deleting an unused tunnel is appropriate when the address and configuration will not be reused.
Avoid sharing the public base address more broadly than necessary. Even though protected Home Assistant routes require authentication, the base listener may contain intentionally public or separately configured paths. Review your own Home Assistant integrations and proxy configuration because Beatify documentation cannot describe every custom route in an individual installation.
Understand the role of HTTPS
Localtonet HTTP and File Server Process Types serve content at a public HTTPS address. That protects the public browser connection to the tunnel edge. It does not remove the need for Home Assistant authentication, careful URL sharing, safe account management, or correct local network configuration.
Do not describe this workflow as bypassing security controls. The Localtonet client must be installed by an authorized operator on a device that is permitted to reach Home Assistant. Follow your organization's network policies and use least-privilege access practices.
Troubleshooting installation, playback, and remote access
Beatify does not appear in HACS
Confirm that HACS is functioning and that you searched the default store for the exact name Beatify. The recommended current workflow does not require adding the project as a custom repository. If the search index appears stale, use the normal HACS refresh behavior available in your installed version rather than entering an unverified repository category or URL.
Beatify was downloaded but cannot be added
Restart Home Assistant. Downloading through HACS does not by itself load a new custom component into the running Home Assistant process. After the restart, go to Settings, Devices & Services, Add Integration, and search again.
For a manual installation, confirm that the repository was cloned to the documented /config/custom_components/beatify destination and that /config is genuinely your Home Assistant configuration path. If your deployment maps the configuration elsewhere, do not assume the path inside one environment matches the path seen from another.
The sidebar entry is missing
Restart Home Assistant, then reload the browser. Also confirm that Beatify was added as an integration and was not merely downloaded. As a direct check, open http://YOUR-HA-IP:8123/beatify/admin using the working Home Assistant host and port for your network.
The expected speaker is unavailable
Verify that the speaker is supported directly through Music Assistant, Sonos, or Alexa. Chromecast, Nest, and HomePod need Music Assistant. Confirm that Home Assistant or Music Assistant can control the speaker outside Beatify before investigating game settings.
A speaker that is offline, disconnected, or absent from the underlying integration will not become usable merely by reinstalling Beatify. Resolve the device integration first, restart affected components if their own documentation requires it, and then reopen the Beatify wizard.
The playlist appears but tracks do not play
Check whether the streaming account permits on-demand playback. A free provider tier may display catalog information yet refuse the specific playback action Beatify needs. Spotify Free is explicitly documented as unsuitable for selected-track playback.
If you intend to use the free YouTube Music route added in Beatify 4.4.0, verify both the Beatify version and the presence of ytmusic_free in Music Assistant. It must be installed in Music Assistant first. Alternatively, use a supported personal music library through Music Assistant.
The local page works but the public page does not
Work through the connection path in order:
- Confirm that Home Assistant and the Beatify route still load locally.
- Confirm that the device running our Localtonet client can reach the same local IP and port.
- Confirm that the intended Localtonet client device is connected.
- Confirm that the correct device token and an available relay server were selected.
- Confirm that the HTTP tunnel was started, not merely created.
- Use the currently assigned public address shown by the tunnel.
- Append the correct route, such as
/beatify/play.
A stopped client, stopped tunnel, obsolete public address, or unreachable local target can all produce similar browser symptoms. Check status before changing Beatify's installation.
The public Home Assistant page opens but Beatify does not
Test the exact local Beatify route again. If /beatify/admin or /beatify/play fails locally, the tunnel is correctly reaching Home Assistant and the remaining problem is in the Beatify installation, integration state, or route availability.
If the route works locally but not through the public address, verify that you are appending the path to the assigned tunnel base address without accidentally retaining the local hostname or port. Do not expose the raw Home Assistant port separately as a workaround.
The admin page asks guests to sign in
That is expected for /beatify/admin. The admin route is for hosts and uses Home Assistant authentication. Guests should use the QR code or the /beatify/play route. Do not give guests host credentials simply to avoid using the correct player page.
A player can open the page but cannot join the active game
Confirm that the host has reached the Ready to host or lobby screen and that the QR code belongs to the current session. Test one local player before troubleshooting remote connectivity. If local players also fail, investigate the Beatify session rather than the tunnel. If only remote players fail, verify the public URL and tunnel state.
The tunnel stopped unexpectedly
Localtonet tunnels are available only while the selected client device remains connected and the tunnel is running. Check that the device is powered on, our client application is still running, and the network permits its outbound connection. Then inspect the tunnel state in the dashboard and start it again if appropriate.
Frequently asked questions
What Home Assistant version does Beatify require?
The current Beatify repository documentation requires Home Assistant 2025.1 or newer. An older project website page displays a lower requirement, but a new installation should follow the newer requirement from the current repository documentation.
Is HACS required to install Beatify?
HACS is the recommended method, and Beatify is available in its default store. A manual Git installation is also documented for users with command-line access to the Home Assistant configuration directory. Beatify must be followed by a Home Assistant restart in either installation workflow.
Does Beatify have a standalone Docker image?
The available project instructions document Beatify as a Home Assistant custom integration. They do not establish a separate Beatify Docker image, standalone startup command, or independent service port. If Home Assistant runs in a container, Beatify is still installed into Home Assistant's configuration storage.
Which speakers can Beatify use?
Beatify supports speakers through Music Assistant, Sonos, or Alexa. Chromecast, Nest, and HomePod can be used when they are available through Music Assistant. Verify ordinary playback through the underlying integration before configuring Beatify.
Can Beatify use my own music library?
Yes. Beatify can use a personal library supplied through Music Assistant, including Plex, Jellyfin, or local files. This provides an alternative to a commercial streaming subscription.
Do guests need Home Assistant accounts?
No. Guests use the password-free Beatify player route, normally reached through the game's QR code. The host interface is different and requires a valid Home Assistant login.
Does remote access expose only the Beatify player page?
No path-only isolation should be assumed. Beatify is served by the Home Assistant HTTP listener, so tunneling that listener may make other Home Assistant paths reachable at the public address. Protected areas still depend on Home Assistant authentication, while the Beatify player route is intentionally password-free.
Does creating a Localtonet tunnel immediately make Beatify public?
No. Creating a tunnel and running it are separate lifecycle states. The selected client device must be connected, and the tunnel must be started before the assigned public URL becomes available. You can later stop or delete the tunnel.
Do I need router port forwarding for this workflow?
No. Our Localtonet client establishes an outbound connection to a relay server, so this workflow does not require inbound router port forwarding, a public IP address, VPN setup, or inbound firewall changes.
Make your verified Beatify game available to remote guests
Install and test Beatify locally first, then use a Localtonet HTTP tunnel to connect the working Home Assistant listener to a public HTTPS address. Keep host credentials and device tokens private, share the guest route deliberately, and stop the tunnel after the game.
Get Started Free →
