A node module for interacting with an Apple TV (4th-generation or later) over the Media Remote Protocol.
Switch branches/tags
Nothing to show
Clone or download
Latest commit 586775d Aug 12, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin Initial commit Mar 2, 2018
dist Add select key. Aug 4, 2018
docs Simplify sendMessage Mar 19, 2018
images add gif to readme Mar 16, 2018
scripts Fix state response times Apr 15, 2018
src Add select key. Aug 4, 2018
.gitignore update gitignore Apr 8, 2018
.travis.yml fix travis? Apr 1, 2018
LICENSE Initial commit Mar 2, 2018
README.md add ci to readme Apr 1, 2018
package-lock.json version bump 1.0.10 Aug 11, 2018
package.json version bump 1.0.10 Aug 11, 2018
tsconfig.json add dist and change ts target Mar 14, 2018

README.md

node-appletv

A node module for interacting with an Apple TV (4th-generation or later) over the Media Remote Protocol.

npm version CI License

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, etc.)

state: Logs state changes from an Apple TV (now playing info)

queue: Requests the current playback queue 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';

return scan()
    .then(devices => {
    	// devices is an array of AppleTV objects
    	let device = devices[0];
    	return device.openConnection()
    		.then(device => {
    			return device.pair();
    		})
    		.then(callback => {
    			// the pin is provided onscreen from the Apple TV
    			return callback(pin);
    		});
    })
    .then(device => {
    	// you're paired!
    	let credentials = device.credentials.toString();
    	console.log(credentials);
    })
    .catch(error => {
    	console.log(error);
    });

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);

return scan(uniqueIdentifier)
    .then(devices => {
    	let device = devices[0];
    	return device.openConnection(credentials);
    })
    .then(device => {
    	// you're connected!
    	// press menu
    	return device.sendKeyCommand(AppleTV.Key.Menu);
    })
    .then(device => {
    	console.log("Sent a menu command!");
    	
    	// monitor now playing info
    	device.on('nowPlaying', (info: NowPlayingInfo) => {
    		console.log(info.toString());
    	});
    })
    .catch(error => {
    	console.log(error);
    });

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.

TODO

  • Add wake command
  • Save credentials for paired Apple TVs

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:

Meta

You can find me on Twitter @edc1591

Distributed under the MIT license. See LICENSE for more information.