docs/index.html
<!doctype html>
<html class="default no-js">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<title>node-appletv</title>
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="assets/css/main.css">
</head>
<body>
<header>
<div class="tsd-page-toolbar">
<div class="container">
<div class="table-wrap">
<div class="table-cell" id="tsd-search" data-index="assets/js/search.js" data-base=".">
<div class="field">
<label for="tsd-search-field" class="tsd-widget search no-caption">Search</label>
<input id="tsd-search-field" type="text" />
</div>
<ul class="results">
<li class="state loading">Preparing search index...</li>
<li class="state failure">The search index is not available</li>
</ul>
<a href="index.html" class="title">node-appletv</a>
</div>
<div class="table-cell" id="tsd-widgets">
<div id="tsd-filter">
<a href="#" class="tsd-widget options no-caption" data-toggle="options">Options</a>
<div class="tsd-filter-group">
<div class="tsd-select" id="tsd-filter-visibility">
<span class="tsd-select-label">All</span>
<ul class="tsd-select-list">
<li data-value="public">Public</li>
<li data-value="protected">Public/Protected</li>
<li data-value="private" class="selected">All</li>
</ul>
</div>
<input type="checkbox" id="tsd-filter-inherited" checked />
<label class="tsd-widget" for="tsd-filter-inherited">Inherited</label>
<input type="checkbox" id="tsd-filter-only-exported" />
<label class="tsd-widget" for="tsd-filter-only-exported">Only exported</label>
</div>
</div>
<a href="#" class="tsd-widget menu no-caption" data-toggle="menu">Menu</a>
</div>
</div>
</div>
</div>
<div class="tsd-page-title">
<div class="container">
<ul class="tsd-breadcrumb">
<li>
<a href="globals.html">Globals</a>
</li>
</ul>
<h1>node-appletv</h1>
</div>
</div>
</header>
<div class="container container-main">
<div class="row">
<div class="col-8 col-content">
<div class="tsd-panel tsd-typography">
<a href="#node-appletv" id="node-appletv" style="color: inherit; text-decoration: none;">
<h1>node-appletv</h1>
</a>
<blockquote>
<p>A node module for interacting with an Apple TV (4th-generation or later) over the Media Remote Protocol.</p>
</blockquote>
<p><a href="https://badge.fury.io/js/node-appletv"><img src="https://badge.fury.io/js/node-appletv.svg" alt="npm version"></a>
<a href="https://codeclimate.com/github/evandcoleman/node-appletv"><img src="https://img.shields.io/codeclimate/maintainability/evandcoleman/node-appletv" alt="Maintainability"></a>
<a href="https://codeclimate.com/github/evandcoleman/node-appletv"><img src="https://img.shields.io/codeclimate/coverage/evandcoleman/node-appletv" alt="Coverage"></a>
<img src="https://img.shields.io/github/workflow/status/evandcoleman/node-appletv/Tests/develop" alt="Build">
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License"></a></p>
<p><img src="images/pairing.gif" alt=""></p>
<a href="#overview" id="overview" style="color: inherit; text-decoration: none;">
<h2>Overview</h2>
</a>
<p><code>node-appletv</code> is a <code>node.js</code> 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 <code>homebridge</code> plugin to connect Apple TV events to HomeKit and vice versa. <code>node-appletv</code> 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.</p>
<a href="#documentation" id="documentation" style="color: inherit; text-decoration: none;">
<h2>Documentation</h2>
</a>
<p>Developer documentation for <code>node-appletv</code> can be found <a href="https://evandcoleman.github.io/node-appletv/">here</a>.</p>
<a href="#usage" id="usage" style="color: inherit; text-decoration: none;">
<h2>Usage</h2>
</a>
<a href="#as-a-standalone-cli" id="as-a-standalone-cli" style="color: inherit; text-decoration: none;">
<h3>As a standalone cli</h3>
</a>
<pre><code class="language-bash"><span class="hljs-comment"># Install</span>
$ npm install -g node-appletv
<span class="hljs-comment"># Display built-in help</span>
$ appletv --<span class="hljs-built_in">help</span></code></pre>
<p>The <code>appletv</code> cli supports several commands, such as:</p>
<p><code>pair</code>: Scans for Apple TVs on the local network and initiates the pairing process</p>
<p><code>command <command></code>: Execute a command on an Apple TV (play, pause, menu, volume, wake, suspend, etc.)</p>
<p><code>state</code>: Logs state changes from an Apple TV (now playing info)</p>
<p><code>queue</code>: Requests the current playback queue from an Apple TV</p>
<p><code>artwork</code>: Requests the current now playing artwork from an Apple TV</p>
<p><code>messages</code>: Logs all raw messages from an Apple TV</p>
<p><code>help <command></code>: Get help for a specific command</p>
<a href="#as-a-node-module" id="as-a-node-module" style="color: inherit; text-decoration: none;">
<h3>As a node module</h3>
</a>
<pre><code class="language-bash">$ npm install --save node-appletv</code></pre>
<p><code>node-appletv</code> makes heavy use of Promises. All functions, except for the observe functions, return Promises.</p>
<a href="#examples" id="examples" style="color: inherit; text-decoration: none;">
<h3>Examples</h3>
</a>
<a href="#scan-for-apple-tvs-and-pair" id="scan-for-apple-tvs-and-pair" style="color: inherit; text-decoration: none;">
<h4>Scan for Apple TVs and pair</h4>
</a>
<pre><code class="language-typescript"><span class="hljs-keyword">import</span> { scan } <span class="hljs-keyword">from</span> <span class="hljs-string">'node-appletv'</span>;
<span class="hljs-keyword">let</span> devices = <span class="hljs-keyword">await</span> scan();
<span class="hljs-comment">// devices is an array of AppleTV objects</span>
<span class="hljs-keyword">let</span> device = devices[<span class="hljs-number">0</span>];
<span class="hljs-keyword">await</span> device.openConnection();
<span class="hljs-keyword">let</span> callback = <span class="hljs-keyword">await</span> device.pair();
<span class="hljs-comment">// the pin is provided onscreen from the Apple TV</span>
<span class="hljs-keyword">await</span> callback(pin);
<span class="hljs-comment">// you're paired!</span>
<span class="hljs-keyword">let</span> credentials = device.credentials.toString();
<span class="hljs-built_in">console</span>.log(credentials);</code></pre>
<a href="#connect-to-a-paired-apple-tv" id="connect-to-a-paired-apple-tv" style="color: inherit; text-decoration: none;">
<h4>Connect to a paired Apple TV</h4>
</a>
<pre><code class="language-typescript"><span class="hljs-keyword">import</span> { scan, parseCredentials, NowPlayingInfo } <span class="hljs-keyword">from</span> <span class="hljs-string">'node-appletv'</span>;
<span class="hljs-comment">// see example above for how to get the credentials string</span>
<span class="hljs-keyword">let</span> credentials = parseCredentials(credentialsString);
<span class="hljs-keyword">let</span> devices = <span class="hljs-keyword">await</span> scan(uniqueIdentifier)[]
<span class="hljs-keyword">let</span> device = devices[<span class="hljs-number">0</span>];
<span class="hljs-keyword">await</span> device.openConnection(credentials);
<span class="hljs-comment">// you're connected!</span>
<span class="hljs-comment">// press menu</span>
<span class="hljs-keyword">await</span> device.sendKeyCommand(AppleTV.Key.Menu);
<span class="hljs-built_in">console</span>.log(<span class="hljs-string">"Sent a menu command!"</span>);
<span class="hljs-comment">// monitor now playing info</span>
device.on(<span class="hljs-string">'nowPlaying'</span>, <span class="hljs-function">(<span class="hljs-params">info: NowPlayingInfo</span>) =></span> {
<span class="hljs-built_in">console</span>.log(info.toString());
});</code></pre>
<p>The <code>uniqueIdentifier</code> is advertised by each Apple TV via Bonjour. Use an app like <a href="http://www.tildesoft.com">Bonjour Browser</a> to find it. The identifier is also the first value in the string value of the <code>Credentials</code> object.</p>
<p>See <a href="https://github.com/evandcoleman/homebridge-theater-mode">homebridge-theater-mode</a> for a more practical use of this module.</p>
<a href="#development" id="development" style="color: inherit; text-decoration: none;">
<h2>Development</h2>
</a>
<p><code>node-appletv</code> is written in Typescript. Edit files in the <code>src</code> directory and then run <code>npm link</code> to clean, build, and create the symlinks to use the library and cli.</p>
<a href="#acknowledgments" id="acknowledgments" style="color: inherit; text-decoration: none;">
<h2>Acknowledgments</h2>
</a>
<p><code>node-appletv</code> would not have been possible without the work of these people:</p>
<ul>
<li><a href="https://github.com/jeanregisser">Jean Regisser</a> who reversed the protobuf <a href="https://github.com/jeanregisser/mediaremotetv-protocol">spec of the MediaRemoteTV protocol</a></li>
<li><a href="https://github.com/postlund">Pierre Ståhl</a> who <a href="https://github.com/postlund/pyatv">implemented the protocol in Python</a></li>
<li><a href="https://github.com/KhaosT">Khaos Tian</a> for <a href="https://github.com/KhaosT/HAP-NodeJS">reversing the HomeKit protocol</a> which also uses SRP encryption</li>
<li><a href="https://github.com/forty2">Zach Bean</a> for <a href="https://github.com/forty2/hap-client">implementing the HAP client spec</a></li>
</ul>
<a href="#meta" id="meta" style="color: inherit; text-decoration: none;">
<h2>Meta</h2>
</a>
<p>You can find me on Twitter <a href="https://twitter.com/evandcoleman">@evandcoleman</a></p>
<p>Distributed under the MIT license. See <code>LICENSE</code> for more information.</p>
</div>
</div>
<div class="col-4 col-menu menu-sticky-wrap menu-highlight">
<nav class="tsd-navigation primary">
<ul>
<li class="globals ">
<a href="globals.html"><em>Globals</em></a>
</li>
<li class=" tsd-kind-external-module">
<a href="modules/_bin_index_.html">"bin/index"</a>
</li>
<li class=" tsd-kind-external-module">
<a href="modules/_bin_pair_.html">"bin/pair"</a>
</li>
<li class=" tsd-kind-external-module">
<a href="modules/_bin_scan_.html">"bin/scan"</a>
</li>
<li class=" tsd-kind-external-module">
<a href="modules/_index_.html">"index"</a>
</li>
<li class=" tsd-kind-external-module">
<a href="modules/_lib_appletv_.html">"lib/appletv"</a>
</li>
<li class=" tsd-kind-external-module">
<a href="modules/_lib_browser_.html">"lib/browser"</a>
</li>
<li class=" tsd-kind-external-module">
<a href="modules/_lib_connection_.html">"lib/connection"</a>
</li>
<li class=" tsd-kind-external-module">
<a href="modules/_lib_credentials_.html">"lib/credentials"</a>
</li>
<li class=" tsd-kind-external-module">
<a href="modules/_lib_message_.html">"lib/message"</a>
</li>
<li class=" tsd-kind-external-module">
<a href="modules/_lib_now_playing_info_.html">"lib/now-<wbr>playing-<wbr>info"</a>
</li>
<li class=" tsd-kind-external-module">
<a href="modules/_lib_pairing_.html">"lib/pairing"</a>
</li>
<li class=" tsd-kind-external-module">
<a href="modules/_lib_supported_command_.html">"lib/supported-<wbr>command"</a>
</li>
<li class=" tsd-kind-external-module">
<a href="modules/_lib_util_encryption_.html">"lib/util/encryption"</a>
</li>
<li class=" tsd-kind-external-module">
<a href="modules/_lib_util_number_.html">"lib/util/number"</a>
</li>
<li class=" tsd-kind-external-module">
<a href="modules/_lib_util_tlv_.html">"lib/util/tlv"</a>
</li>
<li class=" tsd-kind-external-module">
<a href="modules/_lib_verifier_.html">"lib/verifier"</a>
</li>
<li class=" tsd-kind-external-module">
<a href="modules/_test_appletv_spec_.html">"test/appletv.spec"</a>
</li>
<li class=" tsd-kind-external-module">
<a href="modules/_test_browser_spec_.html">"test/browser.spec"</a>
</li>
<li class=" tsd-kind-external-module">
<a href="modules/_test_encryption_spec_.html">"test/encryption.spec"</a>
</li>
<li class=" tsd-kind-external-module">
<a href="modules/_test_helpers_mock_server_.html">"test/helpers/mock-<wbr>server"</a>
</li>
<li class=" tsd-kind-external-module">
<a href="modules/_test_pairing_spec_.html">"test/pairing.spec"</a>
</li>
</ul>
</nav>
<nav class="tsd-navigation secondary menu-sticky">
<ul class="before-current">
</ul>
</nav>
</div>
</div>
</div>
<footer class="with-border-bottom">
<div class="container">
<h2>Legend</h2>
<div class="tsd-legend-group">
<ul class="tsd-legend">
<li class="tsd-kind-module"><span class="tsd-kind-icon">Module</span></li>
<li class="tsd-kind-object-literal"><span class="tsd-kind-icon">Object literal</span></li>
<li class="tsd-kind-variable"><span class="tsd-kind-icon">Variable</span></li>
<li class="tsd-kind-function"><span class="tsd-kind-icon">Function</span></li>
<li class="tsd-kind-function tsd-has-type-parameter"><span class="tsd-kind-icon">Function with type parameter</span></li>
<li class="tsd-kind-index-signature"><span class="tsd-kind-icon">Index signature</span></li>
<li class="tsd-kind-type-alias"><span class="tsd-kind-icon">Type alias</span></li>
<li class="tsd-kind-type-alias tsd-has-type-parameter"><span class="tsd-kind-icon">Type alias with type parameter</span></li>
</ul>
<ul class="tsd-legend">
<li class="tsd-kind-enum"><span class="tsd-kind-icon">Enumeration</span></li>
<li class="tsd-kind-enum-member"><span class="tsd-kind-icon">Enumeration member</span></li>
<li class="tsd-kind-property tsd-parent-kind-enum"><span class="tsd-kind-icon">Property</span></li>
<li class="tsd-kind-method tsd-parent-kind-enum"><span class="tsd-kind-icon">Method</span></li>
</ul>
<ul class="tsd-legend">
<li class="tsd-kind-interface"><span class="tsd-kind-icon">Interface</span></li>
<li class="tsd-kind-interface tsd-has-type-parameter"><span class="tsd-kind-icon">Interface with type parameter</span></li>
<li class="tsd-kind-constructor tsd-parent-kind-interface"><span class="tsd-kind-icon">Constructor</span></li>
<li class="tsd-kind-property tsd-parent-kind-interface"><span class="tsd-kind-icon">Property</span></li>
<li class="tsd-kind-method tsd-parent-kind-interface"><span class="tsd-kind-icon">Method</span></li>
<li class="tsd-kind-index-signature tsd-parent-kind-interface"><span class="tsd-kind-icon">Index signature</span></li>
</ul>
<ul class="tsd-legend">
<li class="tsd-kind-class"><span class="tsd-kind-icon">Class</span></li>
<li class="tsd-kind-class tsd-has-type-parameter"><span class="tsd-kind-icon">Class with type parameter</span></li>
<li class="tsd-kind-constructor tsd-parent-kind-class"><span class="tsd-kind-icon">Constructor</span></li>
<li class="tsd-kind-property tsd-parent-kind-class"><span class="tsd-kind-icon">Property</span></li>
<li class="tsd-kind-method tsd-parent-kind-class"><span class="tsd-kind-icon">Method</span></li>
<li class="tsd-kind-accessor tsd-parent-kind-class"><span class="tsd-kind-icon">Accessor</span></li>
<li class="tsd-kind-index-signature tsd-parent-kind-class"><span class="tsd-kind-icon">Index signature</span></li>
</ul>
<ul class="tsd-legend">
<li class="tsd-kind-constructor tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited constructor</span></li>
<li class="tsd-kind-property tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited property</span></li>
<li class="tsd-kind-method tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited method</span></li>
<li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited accessor</span></li>
</ul>
<ul class="tsd-legend">
<li class="tsd-kind-property tsd-parent-kind-class tsd-is-protected"><span class="tsd-kind-icon">Protected property</span></li>
<li class="tsd-kind-method tsd-parent-kind-class tsd-is-protected"><span class="tsd-kind-icon">Protected method</span></li>
<li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-protected"><span class="tsd-kind-icon">Protected accessor</span></li>
</ul>
<ul class="tsd-legend">
<li class="tsd-kind-property tsd-parent-kind-class tsd-is-private"><span class="tsd-kind-icon">Private property</span></li>
<li class="tsd-kind-method tsd-parent-kind-class tsd-is-private"><span class="tsd-kind-icon">Private method</span></li>
<li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-private"><span class="tsd-kind-icon">Private accessor</span></li>
</ul>
<ul class="tsd-legend">
<li class="tsd-kind-property tsd-parent-kind-class tsd-is-static"><span class="tsd-kind-icon">Static property</span></li>
<li class="tsd-kind-call-signature tsd-parent-kind-class tsd-is-static"><span class="tsd-kind-icon">Static method</span></li>
</ul>
</div>
</div>
</footer>
<div class="container tsd-generator">
<p>Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p>
</div>
<div class="overlay"></div>
<script src="assets/js/main.js"></script>
<script>if (location.protocol == 'file:') document.write('<script src="assets/js/search.js"><' + '/script>');</script>
</body>
</html>