🎵 homebridge-homepod-mini-music-sensor

Transform your HomePod and Apple TV into smart sensors for HomeKit

🎯 Overview

This Homebridge plugin turns your HomePod into a music sensor and your Apple TV into power, playback, and per-app sensors for HomeKit.

Why use this plugin?

• 🎵 Create mood lighting that responds to music
• 🏠 Build multi-room audio automations
• 🌙 Trigger scenes when music stops
• 📱 No complicated setup - works out of the box
• 🎛️ Fully customizable detection settings

✨ Features

Core Features

• 🎵 Smart Music Detection - Detects when music is actively playing
• 📱 HomeKit Motion Sensor - Appears as a standard motion sensor in Home app
• 🏠 Multi-HomePod Support - Create separate sensors for each HomePod
• 📺 Apple TV Support - Power, playback, and per-app sensors
• 🚫 No Authentication Required - Works with HomePod mini without pairing
• ⚡ Fast Updates - Configurable update interval (1-60 seconds)

Advanced Features

• 🎛️ Configurable Detection - Choose what to detect: music, podcasts, movies, or all
• 🎬 Smart Filtering - Automatically filters out movies and long-form content
• ⏱️ Duration-Based Filtering - Set max duration for content detection
• 🎤 Artist Field Detection - Filter content by presence of artist metadata
• 🔄 Real-time Updates - Always knows what's playing, when it's playing

🚀 Installation

Prerequisites

Python 3 is required for this plugin to work:

# Install Python 3 (macOS)
brew install python3

# Verify installation
python3 --version

pyatv library is required to communicate with HomePods:

# Install pyatv
pip3 install pyatv

# Verify installation
python3 -m pyatv --version

On Debian and Raspberry Pi OS, use pipx when the system Python is externally managed:

sudo apt install pipx
pipx install pyatv

If Homebridge does not detect it automatically, set Python Executable Path in the plugin settings to the python executable inside the pyatv pipx/virtualenv environment. Make sure that path is accessible to the user running Homebridge.

Plugin Installation

Via Homebridge UI (Recommended)

1. Open Homebridge UI
2. Go to Plugins tab
3. Search for "HomePod Mini Music Sensor"
4. Click Install
5. Wait for installation to complete
6. Restart Homebridge

Via Terminal

npm install -g homebridge-homepod-mini-music-sensor

⚙️ Configuration

🎨 Visual Configuration Guide

This plugin is designed to be configured entirely through the Homebridge UI - no manual JSON editing required!

Step 1: Open Plugin Settings

After installing the plugin, click the ⚙️ Settings button in the Homebridge UI.

You'll see:

• 🎵 Hero Image - Beautiful HomePod visual at the top
• 🎛️ Detection Settings - Collapsible section for customizing what gets detected
• 🏠 Your HomePods - Section to add your HomePod devices

Step 2: Configure Detection Settings (Optional)

Expand the 🎛️ Detection Settings section to customize what triggers your sensors:

Available Options:

• ✅ 🎵 Detect Music (Default: ON) - Trigger when music plays
• ☐ 🎙️ Detect Podcasts (Default: OFF) - Trigger for podcasts/audiobooks
• ☐ 🎬 Detect Movies/TV (Default: OFF) - Trigger for AirPlay video
• ⏱️ Max Duration (Default: 600 seconds) - Filter by content length
• ✅ 🎤 Require Artist Field (Default: ON) - Filter out content without artist metadata
• 🔄 Update Interval (Default: 5 seconds) - How often to check status

💡 Detection Tips:

• Music Only: Keep defaults (Music: ON, Podcasts: OFF, Movies: OFF)
• Music + Podcasts: Enable both + increase Max Duration to 3600 (60 min)
• Everything: Enable all + disable 'Require Artist Field'

Step 3: Add Your HomePods

Expand the 🏠 Your HomePods section and click ➕ Add HomePod:

For each HomePod:

1. Display Name - Enter a friendly name (e.g., "Bedroom", "Kitchen")
2. Device ID - Enter the HomePod identifier (see instructions below)

📋 How to Find HomePod IDs:

1. Open Terminal
2. Run: python3 -m pyatv.scripts.atvremote scan
3. Find your HomePod in the list
4. Copy the Identifier (remove colons/dashes)
5. Example: A2:94:FB:11:E0:39 → A294FB11E039

💡 Tip: Each HomePod will appear as a separate Motion Sensor in HomeKit

Step 4: Save and Restart

1. Click SAVE button (bottom right)
2. Restart Homebridge
3. Your HomePods will now appear as motion sensors in the Home app! 🎉

Manual Configuration (config.json)

If you prefer to edit config.json manually:

{
  "platform": "HomePodMusicSensor",
  "name": "HomePod Music Sensor",
  "detectMusic": true,
  "detectPodcasts": false,
  "detectMovies": false,
  "maxDuration": 600,
  "requireArtist": true,
  "updateInterval": 5,
  "devices": [
    {
      "name": "Bedroom",
      "deviceId": "A294FB11E039"
    },
    {
      "name": "Living Room",
      "deviceId": "F2E8AA6E8D9C"
    }
  ]
}

🎯 HomeKit Automations

Once configured, each HomePod appears as a Motion Sensor in the Home app:

• ✅ Motion Detected = Content is currently playing (based on your settings)
• ❌ No Motion Detected = Nothing is playing or paused

Automation Ideas

🌅 Morning Routine

When "Bedroom" detects motion (music starts)
→ Open bedroom blinds
→ Turn on coffee maker
→ Set living room lights to 100%

💡 Mood Lighting

When "Living Room" detects motion
→ Dim living room lights to 30%
→ Set lights to warm white
→ Turn off TV

🎵 Multi-Room Audio Control

When "Kitchen" detects motion
→ Pause "Living Room" HomePod
→ Lower "Bedroom" HomePod volume to 20%

🌙 Sleep Mode

When "Bedroom" stops detecting motion (music stops)
→ Turn off all lights
→ Lock front door
→ Set thermostat to 68°F
→ Close blinds

🏃 Workout Detection

When "Gym Room" detects motion
→ Turn on fan
→ Set lights to energizing blue
→ Lock gym room door

🍳 Cooking Assistant

When "Kitchen" detects motion
→ Turn on under-cabinet lights
→ Display recipe on iPad
→ Pause other HomePods

🎭 Content Detection

What Gets Detected?

| Content Type | Default Behavior | How It's Detected | Configurable? | |-------------|------------------|-------------------|---------------| | 🎵 Music (Apple Music, Spotify) | ✅ Detected | Music type + has artist + short duration | Yes - disable if needed | | 🎙️ Podcasts | ❌ Not Detected | Long duration (>10 min) | Yes - enable in settings | | 📚 Audiobooks | ❌ Not Detected | Long duration (>10 min) | Yes - enable in settings | | 🎬 Movies/TV (AirPlay) | ❌ Not Detected | No artist field | Yes - enable + disable "Require Artist" | | 🗣️ Siri Responses | ❌ Never Detected | Not music type | No |

Detection Logic

The plugin uses smart filtering to determine if content should trigger the sensor:

1. Is anything playing? → Check playback state
2. What type of content? → Check media type (music, video, etc.)
3. Does it match settings? → Check if enabled (music/podcasts/movies)
4. How long is it? → Check against max duration
5. Has artist info? → Check artist field (if required)

Result: Sensor triggers only when ALL conditions match your settings.

🔧 Troubleshooting

Common Issues

Solutions:

• Verify IDs: python3 -m pyatv.scripts.atvremote scan
• Check HomePods are on same network as Homebridge
• Restart Homebridge
• Check Homebridge logs for errors

Solutions:

• Ensure music is actually playing (not paused)
• Test manually: python3 get_nowplaying.py YOUR_ID
• Check detection settings (maybe podcasts/movies are disabled)
• Review Homebridge logs
• Verify pyatv is working: python3 -m pyatv.scripts.atvremote --id YOUR_ID playing

Solutions:

• Enable "Require Artist Field" in settings (default: ON)
• Disable "Detect Movies/TV" in settings (default: OFF)
• Lower "Max Duration" to filter longer content

Solutions:

# Verify Python
python3 --version

# Reinstall pyatv
pip3 install --upgrade pyatv

# Test pyatv
python3 -m pyatv scan

Solutions:

• This usually means the plugin wasn't installed correctly
• Try reinstalling: npm uninstall -g homebridge-homepod-mini-music-sensor && npm install -g homebridge-homepod-mini-music-sensor
• Clear npm cache: npm cache clean --force
• Restart Homebridge

Getting More Help

If you're still experiencing issues:

1. Check the logs

   • Homebridge UI → Logs tab
   • Look for lines containing "HomePod" or "Music Sensor"

2. Enable debug logging

   • Check Homebridge debug logs for more details

3. Report an issue

   • Go to: https://github.com/DM911-AI/homebridge-homepod-mini-music-sensor/issues
   • Include:
     • Homebridge version
     • Plugin version
     • Node.js version (node --version)
     • Python version (python3 --version)
     • pyatv version (python3 -m pyatv --version)
     • Relevant log output
     • What you've already tried

📱 Supported Devices

Fully Supported

• ✅ HomePod mini (all colors)
• ✅ HomePod (1st generation - discontinued)
• ✅ HomePod (2nd generation - 2023)
• ✅ Apple TV models supported by pyatv

Requirements

• Network: Devices must be on the same local network as Homebridge
• tvOS: Any version supported by pyatv
• HomePod: No authentication required
• Apple TV: Companion and AirPlay pairing credentials are required

Apple TV Pairing

Find the Apple TV identifier, then pair both required protocols:

atvremote scan
atvremote --id YOUR_APPLE_TV_ID --protocol companion pair
atvremote --id YOUR_APPLE_TV_ID --protocol airplay pair

Enter the credentials printed by each pairing command in the matching plugin setting. See the official pyatv pairing documentation for additional details. Treat these values as passwords.

🗺️ Roadmap

Planned Features

• [x] Apple TV Support

  • Power, playback, and per-app sensors

• [ ] Song Metadata Display

  • Show current song in Eve app
  • Display artist, album, artwork
  • Expected: Version 1.5

• [x] Stereo Pair Support (Added in v1.4)

  • Detect HomePod stereo pairs
  • Create single sensor for pair

• [ ] Custom Webhooks

  • Trigger external services when music plays
  • IFTTT, Zapier integration
  • Expected: Version 1.7

• [ ] Web Dashboard

  • View all HomePods at a glance
  • See what's playing everywhere
  • Expected: Version 2.0

Suggest a Feature

Have an idea? Open a feature request on GitHub!

🤝 Contributing

Contributions are welcome and appreciated!

How to Contribute

1. Fork the repository

   git clone https://github.com/YOUR_USERNAME/homebridge-homepod-mini-music-sensor.git

2. Create a feature branch

   git checkout -b feature/AmazingFeature

3. Make your changes

   • Follow existing code style
   • Add comments for complex logic
   • Test thoroughly

4. Commit your changes

   git commit -m 'Add some AmazingFeature'

5. Push to your fork

   git push origin feature/AmazingFeature

6. Open a Pull Request
   • Describe your changes
   • Link any related issues

Development Setup

# Clone the repo
git clone https://github.com/DM911-AI/homebridge-homepod-mini-music-sensor.git
cd homebridge-homepod-mini-music-sensor

# Install dependencies
npm install

# Link for local testing
npm link

# Make changes and test

📜 License

This project is licensed under the MIT License.

What this means:

• ✅ Free to use
• ✅ Free to modify
• ✅ Free to distribute
• ✅ Can use commercially

See the LICENSE file for full details.

👏 Credits & Acknowledgments

Built With

• pyatv - Amazing Python library for controlling Apple TV and HomePod devices
  • Created by: Pierre Ståhl (@postlund)
  • Without this library, this plugin wouldn't exist!

Inspired By

• The Homebridge community's need for better HomePod integration
• Requests for music-based HomeKit automations

Special Thanks

• Homebridge team - For creating the platform
• Early testers - For feedback and bug reports
• 600+ users - For downloading and using this plugin! 🎉

👤 Author

Daniel Mazuz

🔗 Quick Links

📦 npm Package • 💻 GitHub Repository • 🐛 Report Bug • 💡 Request Feature

⭐ Support This Project

If you find this plugin useful, please consider:

• ⭐ Star this repository on GitHub
• 🐛 Report bugs and issues
• 💡 Suggest new features
• 📢 Share with friends and the community
• ☕ Buy me a coffee (coming soon!)

💙 Enjoying this plugin? Star it on GitHub and share with the community!