Homebridge Music


Homebridge plugin for iTunes with Airplay speakers

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.

$3

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.

$3

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.

$3

Key | Default | Description
--- | ------- | -----------
service | "switch" | Defines what type of service and volume characteristic Homebridge Music uses.
Possible values are: "switch" for Switch and Volume; "speaker" for Speaker and Volume; "light" for LightBulb and Brightness; and "fan" for Fan and Rotation Speed.
Selecting "light" or "fan" enables changing the volume from Siri and from Apple's Home app.
Selecting "speaker" is not supported by the Apple's Home app.
brightness | false | Flag whether to expose volume as Brightness in combination with Switch or Speaker.
Setting this flag enables volume control from Siri.
script | "iTunes"
"Music"| Name of the AppleScript library to interact with the player and speakers.
The default depends on the macOS version, see AppleScript.
speakername | ".*" _(any)_ | Regular expression to be used as filter for speaker names.
track | "" _(none)_ | Name of the track for the player to start.
Note that iTunes and Music will report an error when trying to Play when no current track has been set. You might want to change the default when starting iTunes or Music from Homebridge Music.
resetTrack | false | Reset current track to default track on stop.
heartrate | 5 | Heartbeat interval in seconds.
Player and speaker states are refreshed every heartrate seconds.
timeout | 5 | Timeout in seconds for AppleScript commands.
Increase this when seeing timeout error in the log. Note that HomeKit apps are blocked while the command to apply changed characteristics runs.

$3

Script | Player | Speakers | macOS
---------------- | -------| -------- | -----------
iTunes | iTunes | iTunes AirPlay speakers | < 10.15 Catalina
Music | Music | Music AirPlay speakers | >= 10.15 Catalina
iTunes-Airfoil | iTunes | Airfoil | < 10.15 Catalina
Music-Airfoil | Music | Airfoil | >= 10.15 Catalina
EyeTV-Airfoil | EyeTV v3* | Airfoil | < 10.15 Catalina
_n/a_ | EyeTV v4* | Airfoil | n/a

\*) 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:

Function | Schema | Description
--- | ------- | -----------
getState(initial) | GetState | Gets player and speaker states.
setPlayerOn(on, track) | SetOn | Switches Player On/Off.
changeTrack(next) | SetOn | Sets next/previous track.
setPlayerVolume(vol) | SetVolume | Sets Player Volume.
setSpeakerOn(id, on) | SetOn | Switches Speaker On/Off.
setSpeakerVolume(id, vol) | SetVolume | Sets Speaker Volume.

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.

$3

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`.