ATV-Companion

English | 中文

---

English

A TypeScript SDK for Apple TV Companion protocol - scan, pair, and remote control Apple TV devices.

$3

This project is a TypeScript port of the Companion protocol implementation from pyatv.

Code generated by AI (cc)

Original Python code forked from: pyatv by @postlund

$3

- Device Discovery: Scan for Apple TV devices on your local network via mDNS/Bonjour
- Pairing: Pair with Apple TV using PIN-based authentication (SRP)
- Remote Control: Send HID commands (Up, Down, Left, Right, Menu, Select, Home, etc.)
- Media Control: Play, Pause, Next/Previous track, Volume control
- App Launch: Launch apps by bundle ID or deep link URL
- Event Subscription: Subscribe to device events

$3

``bash npm install atv-companion

`or`


pnpm add atv-companion


$3
- Node.js >= 18.0.0
$3
#### 1. Scan for devices

`typescript import { scan } from 'atv-companion';

const devices = await scan({ timeout: 5000 }); console.log(devices);`

#### 2. Pair with Apple TV

`typescript import { CompanionConnection, CompanionProtocol, CompanionPairSetupProcedure, } from 'atv-companion';

const connection = new CompanionConnection('192.168.1.100', 49152); const protocol = new CompanionProtocol(connection);

await connection.connect();

const pairSetup = new CompanionPairSetupProcedure(protocol); await pairSetup.startPairing();

// Enter the PIN shown on Apple TV screen const credentials = await pairSetup.finishPairing('1234'); console.log('Credentials:', credentials);

connection.close();`

#### 3. Remote Control

`typescript import { CompanionAPI, HidCommand } from 'atv-companion';

const api = new CompanionAPI('192.168.1.100', 49152, credentials); await api.connect();

// Send button commands await api.pressButton(HidCommand.Menu); await api.pressButton(HidCommand.Up); await api.pressButton(HidCommand.Select);

// Media control await api.play(); await api.pause(); await api.setVolume(0.5);

// Launch app await api.launchApp('com.apple.TVWatchList');

await api.disconnect();`

`$3`

#### HidCommand

| Command | Description | |---------|-------------| |Up| Navigate up | |Down| Navigate down | |Left| Navigate left | |Right| Navigate right | |Menu| Menu button | |Select| Select/OK button | |Home| Home button | |VolumeUp| Volume up | |VolumeDown| Volume down | |Siri| Activate Siri | |PlayPause | Play/Pause toggle |

`$3`

Run the examples:

`bash

`Scan for devices`


pnpm run example:scan
Pair with Apple TV

ATV_HOST=192.168.1.100 ATV_PIN=1234 pnpm run example:pair
Remote control

ATV_HOST=192.168.1.100 ATV_CREDENTIALS= pnpm run example:remote


$3
MIT
---
中文
Apple TV Companion 协议的 TypeScript SDK - 扫描、配对和远程控制 Apple TV 设备。
$3
本项目是 pyatv 中 Companion 协议实现的 TypeScript 移植版本。
代码由 AI (cc) 生成
原始 Python 代码来自: pyatv by @postlund
$3
- 设备发现: 通过 mDNS/Bonjour 扫描局域网内的 Apple TV 设备
- 配对: 使用 PIN 码认证 (SRP) 与 Apple TV 配对
- 遥控器: 发送 HID 命令 (上、下、左、右、菜单、选择、主页等)
- 媒体控制: 播放、暂停、上/下一曲、音量控制
- 启动应用: 通过 Bundle ID 或深度链接 URL 启动应用
- 事件订阅: 订阅设备事件
$3

`bash npm install atv-companion

`或`


pnpm add atv-companion


$3
- Node.js >= 18.0.0
$3
#### 1. 扫描设备

`typescript import { scan } from 'atv-companion';

const devices = await scan({ timeout: 5000 }); console.log(devices);`

#### 2. 与 Apple TV 配对

`typescript import { CompanionConnection, CompanionProtocol, CompanionPairSetupProcedure, } from 'atv-companion';

const connection = new CompanionConnection('192.168.1.100', 49152); const protocol = new CompanionProtocol(connection);

await connection.connect();

const pairSetup = new CompanionPairSetupProcedure(protocol); await pairSetup.startPairing();

// 输入 Apple TV 屏幕上显示的 PIN 码 const credentials = await pairSetup.finishPairing('1234'); console.log('凭证:', credentials);

connection.close();`

#### 3. 遥控器控制

`typescript import { CompanionAPI, HidCommand } from 'atv-companion';

const api = new CompanionAPI('192.168.1.100', 49152, credentials); await api.connect();

// 发送按钮命令 await api.pressButton(HidCommand.Menu); await api.pressButton(HidCommand.Up); await api.pressButton(HidCommand.Select);

// 媒体控制 await api.play(); await api.pause(); await api.setVolume(0.5);

// 启动应用 await api.launchApp('com.apple.TVWatchList');

await api.disconnect();`

`$3`

#### HidCommand

| 命令 | 描述 | |------|------| |Up| 向上导航 | |Down| 向下导航 | |Left| 向左导航 | |Right| 向右导航 | |Menu| 菜单按钮 | |Select| 选择/确认按钮 | |Home| 主页按钮 | |VolumeUp| 音量增加 | |VolumeDown| 音量减少 | |Siri| 激活 Siri | |PlayPause | 播放/暂停切换 |

`$3`

运行示例:

`bash

`扫描设备`


pnpm run example:scan
与 Apple TV 配对

ATV_HOST=192.168.1.100 ATV_PIN=1234 pnpm run example:pair
遥控器控制

ATV_HOST=192.168.1.100 ATV_CREDENTIALS= pnpm run example:remote

$3

MIT

ATV-Companion

English | 中文

---

English

A TypeScript SDK for Apple TV Companion protocol - scan, pair, and remote control Apple TV devices.

$3

This project is a TypeScript port of the Companion protocol implementation from pyatv.

Code generated by AI (cc)

Original Python code forked from: pyatv by @postlund

$3

``bash npm install atv-companion

`or`


pnpm add atv-companion


$3
- Node.js >= 18.0.0
$3
#### 1. Scan for devices

`typescript import { scan } from 'atv-companion';

const devices = await scan({ timeout: 5000 }); console.log(devices);`

#### 2. Pair with Apple TV

`typescript import { CompanionConnection, CompanionProtocol, CompanionPairSetupProcedure, } from 'atv-companion';

const connection = new CompanionConnection('192.168.1.100', 49152); const protocol = new CompanionProtocol(connection);

await connection.connect();

const pairSetup = new CompanionPairSetupProcedure(protocol); await pairSetup.startPairing();

// Enter the PIN shown on Apple TV screen const credentials = await pairSetup.finishPairing('1234'); console.log('Credentials:', credentials);

connection.close();`

#### 3. Remote Control

`typescript import { CompanionAPI, HidCommand } from 'atv-companion';

const api = new CompanionAPI('192.168.1.100', 49152, credentials); await api.connect();

// Send button commands await api.pressButton(HidCommand.Menu); await api.pressButton(HidCommand.Up); await api.pressButton(HidCommand.Select);

// Media control await api.play(); await api.pause(); await api.setVolume(0.5);

// Launch app await api.launchApp('com.apple.TVWatchList');

await api.disconnect();`

`$3`

#### HidCommand

`$3`

Run the examples:

`bash

`Scan for devices`


pnpm run example:scan
Pair with Apple TV

ATV_HOST=192.168.1.100 ATV_PIN=1234 pnpm run example:pair
Remote control

ATV_HOST=192.168.1.100 ATV_CREDENTIALS= pnpm run example:remote


$3
MIT
---
中文
Apple TV Companion 协议的 TypeScript SDK - 扫描、配对和远程控制 Apple TV 设备。
$3
本项目是 pyatv 中 Companion 协议实现的 TypeScript 移植版本。
代码由 AI (cc) 生成
原始 Python 代码来自: pyatv by @postlund
$3
- 设备发现: 通过 mDNS/Bonjour 扫描局域网内的 Apple TV 设备
- 配对: 使用 PIN 码认证 (SRP) 与 Apple TV 配对
- 遥控器: 发送 HID 命令 (上、下、左、右、菜单、选择、主页等)
- 媒体控制: 播放、暂停、上/下一曲、音量控制
- 启动应用: 通过 Bundle ID 或深度链接 URL 启动应用
- 事件订阅: 订阅设备事件
$3

`bash npm install atv-companion

`或`


pnpm add atv-companion


$3
- Node.js >= 18.0.0
$3
#### 1. 扫描设备

`typescript import { scan } from 'atv-companion';

const devices = await scan({ timeout: 5000 }); console.log(devices);`

#### 2. 与 Apple TV 配对

`typescript import { CompanionConnection, CompanionProtocol, CompanionPairSetupProcedure, } from 'atv-companion';

const connection = new CompanionConnection('192.168.1.100', 49152); const protocol = new CompanionProtocol(connection);

await connection.connect();

const pairSetup = new CompanionPairSetupProcedure(protocol); await pairSetup.startPairing();

// 输入 Apple TV 屏幕上显示的 PIN 码 const credentials = await pairSetup.finishPairing('1234'); console.log('凭证:', credentials);

connection.close();`

#### 3. 遥控器控制

`typescript import { CompanionAPI, HidCommand } from 'atv-companion';

const api = new CompanionAPI('192.168.1.100', 49152, credentials); await api.connect();

// 发送按钮命令 await api.pressButton(HidCommand.Menu); await api.pressButton(HidCommand.Up); await api.pressButton(HidCommand.Select);

// 媒体控制 await api.play(); await api.pause(); await api.setVolume(0.5);

// 启动应用 await api.launchApp('com.apple.TVWatchList');

await api.disconnect();`

`$3`

#### HidCommand

`$3`

运行示例:

`bash

`扫描设备`


pnpm run example:scan
与 Apple TV 配对

ATV_HOST=192.168.1.100 ATV_PIN=1234 pnpm run example:pair
遥控器控制

ATV_HOST=192.168.1.100 ATV_CREDENTIALS= pnpm run example:remote

$3

MIT