TypeScript SDK for Apple TV Companion protocol - scan, pair, and remote control
npm install atv-companion---
A TypeScript SDK for Apple TV Companion protocol - scan, pair, and remote control Apple TV devices.
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
- 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
``bash`
npm install atv-companionor
pnpm add atv-companion
- Node.js >= 18.0.0
#### 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();
`
#### 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 |
Run the examples:
`bashScan for devices
pnpm run example:scan
$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
``MIT