node-appletv
A node module for interacting with an Apple TV (4th-generation or later) over the Media Remote Protocol.
Overview
node-appletv
is a node.js
implementation of the Media Remote Protocol which shipped with the 4th-generation Apple TV. This is the protocol that the Apple TV remote app uses, so this should enable the creation of an Apple TV remote app for various platforms. It can also be used in a homebridge
plugin to connect Apple TV events to HomeKit and vice versa. node-appletv
can be used as a standalone command line application, or as a module in your own node app. Keep reading for installation and usage instructions.
Documentation
Developer documentation for node-appletv
can be found here.
Usage
As a standalone cli
# Install
$ npm install -g node-appletv
# Display built-in help
$ appletv --help
The appletv
cli supports several commands, such as:
pair
: Scans for Apple TVs on the local network and initiates the pairing process
command <command>
: Execute a command on an Apple TV (play, pause, menu, volume, wake, suspend, etc.)
state
: Logs state changes from an Apple TV (now playing info)
queue
: Requests the current playback queue from an Apple TV
artwork
: Requests the current now playing artwork from an Apple TV
messages
: Logs all raw messages from an Apple TV
help <command>
: Get help for a specific command
As a node module
$ npm install --save node-appletv
node-appletv
makes heavy use of Promises. All functions, except for the observe functions, return Promises.
Examples
Scan for Apple TVs and pair
import { scan } from 'node-appletv';
let devices = await scan();
// devices is an array of AppleTV objects
let device = devices[0];
await device.openConnection();
let callback = await device.pair();
// the pin is provided onscreen from the Apple TV
await callback(pin);
// you're paired!
let credentials = device.credentials.toString();
console.log(credentials);
Connect to a paired Apple TV
import { scan, parseCredentials, NowPlayingInfo } from 'node-appletv';
// see example above for how to get the credentials string
let credentials = parseCredentials(credentialsString);
let devices = await scan(uniqueIdentifier)[]
let device = devices[0];
await device.openConnection(credentials);
// you're connected!
// press menu
await device.sendKeyCommand(AppleTV.Key.Menu);
console.log("Sent a menu command!");
// monitor now playing info
device.on('nowPlaying', (info: NowPlayingInfo) => {
console.log(info.toString());
});
The uniqueIdentifier
is advertised by each Apple TV via Bonjour. Use an app like Bonjour Browser to find it. The identifier is also the first value in the string value of the Credentials
object.
See homebridge-theater-mode for a more practical use of this module.
Development
node-appletv
is written in Typescript. Edit files in the src
directory and then run npm link
to clean, build, and create the symlinks to use the library and cli.
Acknowledgments
node-appletv
would not have been possible without the work of these people:
- Jean Regisser who reversed the protobuf spec of the MediaRemoteTV protocol
- Pierre Ståhl who implemented the protocol in Python
- Khaos Tian for reversing the HomeKit protocol which also uses SRP encryption
- Zach Bean for implementing the HAP client spec
Meta
You can find me on Twitter @evandcoleman
Distributed under the MIT license. See LICENSE
for more information.