atv-companion

ATV-Companion

English | 中文

English

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

About

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

Features

• 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

Installation

npm install atv-companion
# or
pnpm add atv-companion

Requirements

• Node.js >= 18.0.0

Quick Start

1. Scan for devices

import { scan } from 'atv-companion';

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

2. Pair with Apple TV

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

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

API Reference

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

Examples

Run the examples:

# 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=<base64> pnpm run example:remote

License

MIT

中文

Apple TV Companion 协议的 TypeScript SDK - 扫描、配对和远程控制 Apple TV 设备。

关于

本项目是 pyatv 中 Companion 协议实现的 TypeScript 移植版本。

代码由 AI (cc) 生成

原始 Python 代码来自: pyatv by @postlund

功能特性

• 设备发现: 通过 mDNS/Bonjour 扫描局域网内的 Apple TV 设备
• 配对: 使用 PIN 码认证 (SRP) 与 Apple TV 配对
• 遥控器: 发送 HID 命令 (上、下、左、右、菜单、选择、主页等)
• 媒体控制: 播放、暂停、上/下一曲、音量控制
• 启动应用: 通过 Bundle ID 或深度链接 URL 启动应用
• 事件订阅: 订阅设备事件

安装

npm install atv-companion
# 或
pnpm add atv-companion

系统要求

• Node.js >= 18.0.0

快速开始

1. 扫描设备

import { scan } from 'atv-companion';

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

2. 与 Apple TV 配对

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. 遥控器控制

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

API 参考

HidCommand

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

示例

运行示例:

# 扫描设备
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=<base64> pnpm run example:remote

许可证

MIT