<div align="center">

Beatify

<img src="images/beatify-logo.png" alt="Beatify Logo" width="400">

Multiplayer Music Trivia Quiz Game for Home Assistant

Turn any gathering into an unforgettable music trivia experience. Guests scan, songs play, everyone competes. It's that simple.

Get Started • Supported Speakers • See It In Action

---

</div> <br>

What Is Beatify?

Beatify is an open-source music quiz game for Home Assistant — a multiplayer music trivia party game that turns your smart speakers into a game show.

A song plays through your Sonos, Alexa, or Music Assistant speakers. Everyone races to guess the release year. Points fly. Streaks build. Champions emerge.

No apps to download. No accounts to create. Just scan a QR code and play.

---

<br>

Why Parties Are Better With Beatify

Zero Friction Entry — Guests scan a QR code. That's it. No apps. No accounts. No WiFi password drama. 10 seconds from scan to playing.

Uses Your Existing Smart Speakers — Works with Music Assistant, Sonos, and Alexa speakers you already have. See Supported Speakers for details.

Your Music, Your Vibe — Spotify, Apple Music, YouTube Music, or Tidal playlists. Curated song packs included. Create your own.

Runs Locally — No cloud. No subscription. No data leaves your network. Fast, private, reliable.

Everyone Competes — Points, streaks, power-ups, and a dramatic finale with podium and stats. Real competition, real laughs.

---

<br>

Setup In Home Assistant

Step 1: Install

Via HACS (Recommended) — One click to add the repository, then install:

Or manually:

HACS → ⋮ Menu → Custom Repositories
→ URL: https://github.com/mholzi/beatify
→ Category: Integration
→ Install "Beatify"
→ Restart Home Assistant

Manual

cd /config/custom_components
git clone https://github.com/mholzi/beatify.git beatify
# Restart Home Assistant

Step 2: Configure

Or manually:

Settings → Devices & Services → Add Integration → "Beatify"

That's it. Beatify is now installed.

---

<br>

Opening Beatify (Admin)

After installation, access Beatify to start a game:

Option 1: HA Sidebar (Recommended)

Beatify automatically adds itself to your Home Assistant sidebar.

1. Open Home Assistant
2. Look for Beatify in the left sidebar
3. Click to open the launcher
4. Hit "Open Beatify" — the game opens in a fullscreen new tab (no HA chrome)

Tip: If you don't see Beatify in the sidebar, restart Home Assistant.

Option 2: Direct URL

http://YOUR-HA-IP:8123/beatify/admin

Option 3: HA Companion App

1. Open the HA Companion app
2. Tap the menu (☰) or swipe from left
3. Select Beatify from the sidebar

Starting a Game

1. Select a speaker — Only supported speakers appear
2. Choose your music service — Spotify or Apple Music (depends on speaker)
3. Pick playlists — Select one or more
4. Adjust settings — Language, timer, difficulty
5. Start Game — Share the QR code with guests

<div align="center"> <!-- SCREENSHOT: QR code display with join URL --> <img src="images/qr-lobby.png" alt="QR code lobby screen" width="400">

Print it. Display it. Share it.

</div>

---

<br>

The Experience

<div align="center">

For Players

<!-- SCREENSHOT: Player's phone showing the year slider and album art --> <img src="images/player-gameplay.png" alt="Player guessing screen" width="350">

Slide to guess. Tap to submit. Pray you're right.

</div>

The Rush A song starts playing. The clock is ticking. You know this song... but was it '85 or '87?

The Strategy Answer fast for bonus points. Hit a streak for multipliers. Feeling confident? Bet double-or-nothing.

The Reveal The year drops. The room erupts. Someone nailed it. Someone was way off. Everyone's laughing.

Gold confetti bursts for exact guesses. Chart positions and fun facts appear. You just learned that song spent 22 weeks at #1.

<br> <div align="center">

For Hosts

<!-- SCREENSHOT: Admin setup screen with media player and playlist selection --> <img src="images/admin-setup.png" alt="Admin setup screen" width="700">

Select speakers. Pick playlists. Start the party.

</div>

Full Control Skip tracks. Adjust volume. Pause the game. End early if needed. All from your phone.

Customize the Challenge Set round timers (15s/30s/45s) and difficulty levels (Easy/Normal/Hard) to match your group.

Print the QR Physical QR code printout for the coffee table. Guests join themselves.

Play Along Join as a player with admin controls. Compete and manage simultaneously.

---

<br>

Game Features

<div align="center"> <!-- SCREENSHOT: Reveal screen showing correct year, fun fact, and scores --> <img src="images/reveal-screen.png" alt="Round reveal with scores" width="600">

The moment of truth. Every single round.

</div>

Scoring That Creates Drama

Choose your difficulty—each changes how points are awarded:

| Difficulty | Exact | Close | Near | The Vibe | |------------|-------|-------|------|----------| | 😊 Easy | 10 pts | ±7 yrs = 5 pts | ±10 yrs = 1 pt | Forgiving | | 🎯 Normal | 10 pts | ±3 yrs = 5 pts | ±5 yrs = 1 pt | Balanced | | 🔥 Hard | 10 pts | ±2 yrs = 3 pts | — | Punishing |

Speed Bonus

Submit instantly: 2x multiplier Submit at deadline: 1x multiplier Linear scale in between. Hesitation costs points.

Streak Milestones

• 3 in a row: +20 bonus points
• 5 in a row: +50 bonus points
• 10 in a row: +100 bonus points
• 15 in a row: +150 bonus points
• 20 in a row: +250 bonus points
• 25 in a row: +400 bonus points

Miss one? Streak resets. The pressure is real.

Double or Nothing

Feeling confident? Toggle the bet before submitting. Score points: Double them. Score zero: Lose it all.

Artist Challenge (Optional)

Know your artists? Enable this mode in game setup. Guess the artist after the song: +5 bonus points. Alternate names accepted—"Prince" or "The Artist" both count.

---

<br>

The Finale

<div align="center"> <!-- SCREENSHOT: End game podium showing top 3 players with medals --> <img src="images/podium-screen.png" alt="Winner podium" width="500">

Glory. Bragging rights. Maybe a rematch.

</div>

Fireworks explode for the winner. Full podium with medals. Personal stats. Best streaks. Bets won.

See how your game compared to all-time averages. Set a new record? Rainbow confetti and a "NEW RECORD!" badge.

Everything you need to demand a rematch.

---

<br>

Viewing & Selecting Playlists

Playlists are displayed on the main Beatify admin screen:

1. Open Beatify (see above)
2. Scroll to the Playlists section
3. Check the boxes next to playlists you want to use in your game
4. Selected playlists show their song count

Included Playlists

Beatify comes with 2,453 songs across 23 curated playlists:

• 🎸 60s Classics — 45 tracks from the golden age of rock & roll
• 🎹 80s Hits — 208 classic hits from the decade of synths and MTV
• 🎵 90s Hits — 32 essential tracks from the decade
• 🎵 2000s Pop Anthems — 150 essential pop hits from the 2000s
• 🎤 90s & 2000s Hip-Hop Bangers — 40 tracks from 2Pac, Eminem, JAY-Z, Nas, Dr. Dre and more
• 🇪🇸 100% en Español — 127 Latin & Spanish classics
• 🎬 100 Greatest Movie Themes — 162 iconic film soundtracks
• ☀️ 100 Summer Anthems — 112 feel-good tracks from 1957-2020
• 🇬🇧 British Invasion & Britpop — 100 tracks from The Beatles to Blur
• 🎭 Cologne Carnival — 290 German carnival favorites
• 🕺 Disco & Funk Classics — 76 essential disco and funk tracks from the 70s and 80s
• 💥 Eurodance 90s — 100 party songs from the eurodance era
• 🏆 Eurovision Winners (1956-2025) — 72 winning songs
• 💃 Fiesta Latina 90s — 50 Latin party anthems from Shakira, Ricky Martin, Maná
• 🤘 Greatest Metal Songs — 52 legendary tracks across all major metal subgenres
• 🎯 Greatest Hits of All Time — 180 chart-toppers across four decades
• 🎵 Motown & Soul Classics — 100 iconic soul tracks from Diana Ross, Marvin Gaye, The Temptations
• 🎤 One-Hit Wonders — 98 flash-in-the-pan classics
• 💔 Power Ballads — 99 epic rock ballads from the 80s and 90s
• 🎸 Pure Pop Punk — 100 essential pop-punk tracks from the 2000s
• 🇩🇪 Schlager Classics — 60 German schlager classics
• 🇳🇱 Top 100 Dutch Classics — 100 Nederlandstalig tracks
• ⛵ Yacht Rock — 100 smooth West Coast classics from the 70s and 80s

Adding Custom Playlists

Custom playlists are stored in: config/beatify/playlists/

See Creating Playlists for the JSON format.

---

<br>

Creating Playlists

Beatify uses simple JSON playlists stored in config/beatify/playlists/.

{
  "name": "80s Classics",
  "songs": [
    {
      "year": 1983,
      "uri": "spotify:track:4cOdK2wGLETKBW3PvgPWqT",
      "fun_fact": "Spent 8 weeks at #1"
    },
    {
      "y