‚̧Not Preposterously Macho
    Wondering what‚Äôs next for npm?Check out our public roadmap! ¬Ľ

    node-appletv
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.0¬†‚Äʬ†Public¬†‚Äʬ†Published

    node-appletv

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

    npm version Maintainability Coverage Build 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, 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:

    Meta

    You can find me on Twitter @evandcoleman

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

    Install

    npm i node-appletv

    DownloadsWeekly Downloads

    43

    Version

    1.1.0

    License

    MIT

    Unpacked Size

    5.6 MB

    Total Files

    232

    Last publish

    Collaborators

    • avatar