JarekToro/bunatv

# BunATV 一个用于在本地网络控制 Apple TV 设备的 TypeScript/Bun 库。BunATV 实现了 Apple 的 Companion、MRP (Media Remote Protocol) 和 AirPlay 2 协议，让你可以直接访问每个协议发送的消息——没有抽象外观，也没有魔法分组。 ## 什么是 BunATV？ BunATV 是一个**库优先**的项目。它暴露了用于控制 Apple TV 设备的原始协议接口：发现、配对、遥控输入、音量、电源、媒体播放、应用启动、文本输入等。每个协议的 API 都与实际通过网络传输的内容密切对应。 为了方便起见，包含了一个 CLI (`bunatv`)，但它只是库之上的一层薄包装，并没有暴露所有功能。该库是主要接口。 ## 目标 - **通过构建来学习。** 通过在 TypeScript 中从头开始实现来理解 Apple 的设备控制协议——而不是通过包装或移植现有的库。 - **协议透明度。** 提供忠实于底层协议的 API，暴露原始消息和数据结构，而不是将它们隐藏在高级抽象之后。 - **逆向工程未文档化的内容。** 这些协议的许多方面并没有公开文档。这个项目是一个进行逆向工程的机会（使用 ghidra 分析 Apple Frameworks 发现了许多额外的 MRP 消息）。 - **改进我感兴趣的东西** 毫秒级精度的运行时间推算、TTL 感知的 mDNS 缓存（让后续查找变得更快），以及 Bun 在现实世界自动化中的性能特征。 ## BunATV 不是什么 - **不是 PyATV 的移植。** BunATV 深受 [PyATV](https://github.com/postlund/pyatv) 的启发，并基于其研究，但它是一个从头开始的 TypeScript 实现，有着不同的设计理念——而不是逐行的翻译。 - **不是流媒体应用。** BunATV 用于控制 Apple TV 设备。它（目前）不向它们流式传输音频或视频。 - **不是 CLI 优先。** CLI 是一个便利工具，可能会被重写。并非所有已实现的功能都在那里暴露。库 API 才是预期的接口。 ## 状态 - **Companion 协议：** 正常工作 —— 配对、连接、遥控、音量、电源、应用启动、文本输入、触摸 - **MRP 协议：** 功能正常 —— 核心遥控、播放和正在播放功能正常工作；许多高级消息类型（语音、游戏控制器、键盘）未处理 - **AirPlay 2：** 基础设施已实现（传输、认证、帧处理）——用作 MRP 的底层传输 - **RAOP (AirPlay 1 音频)：** 流式传输堆栈已实现 —— RTSP ANNOUNCE/SETUP/RECORD、UDP RTP 音频、同步数据包、重传积压、DAAP 元数据 - **CLI：** 用于发现、配对和基本控制的功能正常 ## 哪些功能可用 ### Companion 协议 - 通过 mDNS **发现**局域网上的 Apple TV - TTL 感知的解析缓存显著加快了后续查找和 CLI 命令 - 使用屏幕上的 **4 位 PIN 码**进行**配对** - 为未来的会话**重用凭证** - 用于状态更改通知的**兴趣订阅** - **遥控按键** —— HID 风格的命令（导航、菜单、主屏幕、播放/暂停等） - **音量控制** —— 获取、设置、调大、调小 - **电源/注意力状态** —— 查询和唤醒/睡眠控制 - **应用启动** —— 按 bundle ID 启动应用 - **文本输入** —— 在搜索字段和表单中输入 - **触摸输入** —— 触摸事件和手势 ### MRP 协议（通过 AirPlay 2） - **正在播放状态** —— 活动播放器、曲目元数据、带有毫秒级精度推算的播放位置 - **播放控制** —— 播放、暂停、跳过、快进/快退、章节、随机/重复模式、播放速率 - **音乐/资料库命令** —— 喜欢、不喜欢、禁止、书签、评分、心愿单、专辑/播放列表导航 - **高级遥控** —— 带有 protobuf 消息的完整 HID 命令集 - **键盘/文本输入** —— 设置、插入和清除焦点文本字段，具有键盘会话状态和编辑属性事件 - **音量** —— 设置/静音以及显式的 `getVolume`/`getVolumeMuted` 查询和被动的音量变化跟踪 - **扬声器管理** —— 添加、删除和设置 AirPlay 输出设备 - **触摸/手势控制** —— 可配置持续时间的点击和滑动 尚未实现：语音输入、游戏控制器输入、播放会话迁移、设备端点发现。 ### RAOP / AirPlay 1 音频 - **RTSP 会话** —— 带 SDP (L16 PCM, 44100 Hz, 立体声) 的 ANNOUNCE、SETUP (UDP 端口协商)、RECORD、FLUSH、TEARDOWN - **UDP 音频通道** —— 实时 RTP 数据包发送，具有针对时间漂移的突发补偿 - **控制通道** —— 每秒发送一次 UDP 同步数据包（NTP 墙上时钟 ↔ RTP 时间戳锚定）；处理来自接收器的重传请求 - **DAAP 元数据** —— 通过带有 `application/x-dmap-tagged` 的 RTSP `SET_PARAMETER` 发布标题、艺术家、专辑和持续时间 - **封面图** —— 通过 `SET_PARAMETER` 发布专辑封面（自动检测 JPEG 或 PNG） - **进度** —— 通过 `SET_PARAMETER` 以 RTP 时间戳单位发布播放位置 - **音量** —— 以 dBFS 或 0–100 百分比形式设置音量（包含 `pctToDbfs` 转换） - **MFi-SAP** —— 用于 AirPort Express 设备的 `authSetup`（静态 Curve25519 密钥） - **Digest 认证** —— 用于受保护接收器的可选密码 ## 安装/运行 此仓库专为 Bun 设计。 ### 从源码运行 ``` bun install bun run cli -- --help ``` ### 构建独立的 CLI 二进制文件 ``` bun run build:cli ./dist/bin/bunatv --help ``` ## CLI CLI 可执行文件名为 `bunatv`。 ``` Usage: bunatv Version: 1.0.0 Description: Control Apple TV devices from the command line Options: -h, --help - Show this help. -V, --version - Show the version number for this program. -o, --output - Output format (text, json, table) (Default: "text", Values: "text", "json", "table") -v, --verbose - Verbose output with detailed information (Default: false) --no-color - Disable colored output (Default: false) --debug [level] - Set logging level (silent, error, warn, info, debug, trace) (Values: "silent", "error", "warn", "info", "debug", "trace") Commands: discover - Discover Apple TV devices on the network info - Get detailed information about a specific device pair - Pair with an Apple TV device wizard - Interactive setup wizard for Apple TV connection control - Control an Apple TV device debug - Debug utilities for BunATV ``` ## 日志与调试 BunATV 使用 **pino** 和 **debug** 进行日志记录 ### 模块级 debug 过滤 (`DEBUG`) 可以通过 `DEBUG` 命名空间匹配器来过滤日志。 - `DEBUG` 在代码中默认为 `*` 示例： ``` # 显示所有日志 DEBUG=bunatv:* # 仅显示 companion protocol 日志 DEBUG=bunatv:companion:* # 显示所有 crypto 操作 DEBUG=bunatv:crypto:* # 显示特定模块 DEBUG=bunatv:hap:auth,bunatv:companion:api # 排除 noisy 模块 DEBUG=bunatv:*,-bunatv:encoding:* ``` 要查找所有可用的命名空间，请使用 [astgrep](https://ast-grep.github.io/) 运行 `ast-grep --pattern "createLogger(\$ARG)" .` ## 路线图 - **Companion 正在播放** —— Companion 协议中存在用于正在播放信息的较新协议消息，但需要进一步的逆向工程才能完全映射出来 - **AirPlay 音频/视频流传输** —— RAOP/AirPlay 1 音频发送器已完成；AirPlay 2 音频/视频流传输是下一步 - **可发布的包** —— 清理公共 API 接口并发布到 npm/JSR ## 许可证 MIT

标签：AirPlay, Apple TV控制, Bun, TypeScript, 协议实现, 安全插件, 智能设备控制, 自动化攻击