Copyright © 2016-2024 Erik Baauw. All rights reserved.

This homebridge plugin exposes controls to Apple's HomeKit for a music player, like iTunes/Music or EyeTV, running on macOS. It provides the following features:

• HomeKit support for controlling iTunes (Music as of macOS 10.15 Catalina) or EyeTV:
  • On/Off control;
  • Volume control;
  • Previous/Next track/channel;
  • View current track/channel;
• HomeKit support for controlling AirPlay speakers connected to iTunes/Music on macOS:
  • On/Off control;
  • Volume control;
• HomeKit control for Airfoil-connected speakers:
  • On/Off control;
  • Volume control;
• Provides an AppleScript framework to support other players.

Note: this is my old plugin from 2016 that I used to control my music, before moving to Sonos and Homebridge ZP.

You need a macOS system to run Homebridge Music. AppleScript is used to communicate with iTunes/Music, EyeTV, or another music player, and that only runs on macOS.

To interact with HomeKit, you need Siri or a HomeKit app on an iPhone, Apple Watch, iPad, iPod Touch, or Apple TV (4th generation or later). I recommend to use the latest released versions of iOS, watchOS, and tvOS.
Please note that Siri and even Apple's Home app still provide only limited HomeKit support. To use the full features of Homebridge Music, you might want to check out some other HomeKit apps, like the Eve app (free) or Matthias Hochgatterer's Home+ app (paid).

As HomeKit uses Bonjour to discover Homebridge, the server running Homebridge must be on the same subnet as your iDevices running HomeKit. For remote access and for HomeKit automations, you need to setup an Apple TV (4th generation or later), HomePod, or iPad as home hub.

Homebridge Music creates an accessory Music for the player. By default, this accessory contains a single ÂSwitch service, with the same name as the accessory. In addition to the standard On characteristic for play/pause control, additional characteristics are provided for Volume, Change Track, and Current Track (read-only).

For each AirPlay or Airfoil speaker, Homebridge Music creates an additional accessory, named after the speaker. By default, these accessory contain a single Switch service, with the same name as the accessory. In addition to the standard One characteristic for play/pause control, an additional characteristic is provided for Volume.

Note that neither Siri nor the Apple's Home app support Volume, even thought this is a standard HomeKit characteristic. Because of this, the type of the service, as well as the type of characteristic used for volume can be changed from config.json, see Configuration and Homebridge ZP issue #10.

To install Homebridge Music:

• Follow the instructions on the Homebridge Wiki to install Node.js and Homebridge on a macOS system;
• Install the Homebridge Music plugin through Homebridge Config UI X or manually by:

  $ sudo npm -g i homebridge-music
  

• Edit config.json and add the Music platform provided by Homebridge Music, see Configuration.

In Homebridge's config.json you need to specify a platform for Homebridge Music:

  "platforms": [
    {
      "platform": "Music"
    }
  ]

The following optional parameters can be added to modify Homebridge Music's behaviour:

Homebridge Music interacts with the music player and speakers is through AppleScript. Each player/speaker combination has an associated AppleScript file in /usr/local/lib/node_modules/homebridge-music/scripts.

Homebridge Music ships with the following scripts:

*) EyeTV v3 is a 32-bit application, which are no longer supported on macOS 10.15 Catalina.
*) EyeTV v4 is a 64-bit application and runs on Catalina, but it (currently?) lacks proper AppleScript support, see issue #14.

Each script provides the following functions to Homebridge Music:

These functions return a JSON string that conforms to the corresponding schema in /usr/local/lib/node_modules/homebridge-music/lib.

You can add your own script to support your favourite music player. To verify whether your script returns valid responses, you might want to use JSON Schema Lint.

Homebridge Music is a hobby project of mine, provided as-is, with no warranty whatsoever. I've been running it successfully at my home for years, but your mileage might vary.

The HomeKit terminology needs some getting used to. An accessory more or less corresponds to a physical device, accessible from your iOS device over WiFi or Bluetooth. A bridge (like Homebridge) is an accessory that provides access to other, bridged, accessories. An accessory might provide multiple services. Each service corresponds to a virtual device (like a lightbulb, switch, motion sensor, ..., but also: a programmable switch button, accessory information, battery status). Siri interacts with services, not with accessories. A service contains one or more characteristics. A characteristic is like a service attribute, which might be read or written by HomeKit apps. You might want to checkout Apple's HomeKit Accessory Simulator, which is distributed as an additional tool for Xcode.