MoviePilot-TV
基于 Swift 和 SwiftUI 开发的 MoviePilot Apple TV 原生客户端。为大屏幕和 Siri Remote 遥控器交互而设计。
界面预览
核心特性
专为大屏幕和家庭观影设计，提供从浏览、搜索到订阅的完整闭环体验。
- 为家庭设计: 聚焦核心观影功能，摒弃复杂的管理员后台设置，交互简洁，适合所有家庭成员。
- 原生沉浸体验: 基于 Swift & SwiftUI 原生开发，遵循 tvOS 设计规范，提供流畅的动效和沉浸式体验。
- Siri Remote 支持: 可通过 Siri Remote 直观操作，支持长按海报进行订阅、搜索等快捷操作。
- 无缝浏览: 通过详情页预加载和持久化登录，消除等待，实现无缝切换和快速访问。
⚠️ 兼容性与已知问题
- tvOS 版本: 支持 tvOS 18.0+。本项目主要在 tvOS 26.0+ 环境下开发，建议使用最新的 tvOS 系统获得最佳体验。
- MoviePilot 版本: 自 MoviePilot-TV v0.4.0 起支持向后兼容，最低兼容 MoviePilot v3.0.4。具体见已验证的兼容版本。
- 兼容原则: TV 端以 MoviePilot Web 前端和 MoviePilot 后端当前行为为准，通常不会额外兜底修复。
- 账号登录: 不支持已开启双因素认证 (MFA/2FA) 的账号，请在关闭双因素认证后再登录。
- 密码安全: 请勿将 MoviePilot 密码与其他服务的密码设为相同值。Apple 钥匙串不可用时，本 App 会自动降级为明文持久化密码；即使 Apple TV 环境相对封闭，仍存在密码泄露风险。
安装指南
方式一：下载 IPA 并自签侧载
前往项目的 Releases，下载最新版本中的：
MoviePilot-TV-unsigned.ipa该文件需要使用自己的 Apple 账号或证书重新签名后，才能安装到 Apple TV。
可使用支持 tvOS 应用签名和侧载的工具进行安装，例如：
- ATVloadly
- 其他支持 tvOS IPA 重签名及侧载的工具
Issue#1 中已有用户确认，通过部署在 NAS 上的 ATVloadly，可以正常完成安装并使用。
方式二：社区 TestFlight 苹果测试渠道
社区用户 EricCartman9969 提供了个人 TestFlight，可通过以下链接加入：
https://testflight.apple.com/join/UK3qEnVU
[!WARNING]
该 TestFlight 由社区用户自行维护，并非本项目官方发布渠道。
> 不保证长期更新、持续可用或与最新源码版本保持一致；测试名额、构建有效期及后续维护均由提供者决定。
方式三：通过 Xcode 源码构建
准备工作
- macOS 26.0+
- Xcode 26.0+
构建步骤
- 克隆项目代码：
git clone --filter=blob:none https://github.com/CHANTXU64/MoviePilot-TV.git
# 切到最新 tag (例如 v0.4.1)
git checkout tags/v0.4.1
- 使用 Xcode 打开
MoviePilot-TV.xcodeproj。 - 选择你的真实 Apple TV 设备（需在同一局域网并已配对）。
- 为主 App 和 Top Shelf 扩展在 Signing & Capabilities 中选择自己的同一开发者团队，并在项目 Build Settings 中设置
APP_BUNDLE_IDENTIFIER（例如com.yourname.MoviePilotTV）。主 App 使用此标识，扩展使用其.TopShelf子标识。
APP_GROUP_IDENTIFIER 默认派生为 group.$(APP_BUNDLE_IDENTIFIER)，例如 group.com.yourname.MoviePilotTV；两个 target 的 entitlements、共享缓存和共享 Keychain 都使用这个值。确认该 Group 已注册到自己的团队，并为两个 App ID 启用对应的 App Groups 授权；Xcode 自动签名可管理这些配置。已有自己团队的 Group 时，只需在项目级覆盖 APP_GROUP_IDENTIFIER，不要分别修改 entitlements 或 Swift 常量，也不要全局覆盖 PRODUCT_BUNDLE_IDENTIFIER。
- 点击 Run (或
Cmd + R) 编译并安装。 - 自动续签 (可选): 免费账号签名的应用有效期通常为 7 天，可使用 Sideloadly 或项目内的
scripts/apple-tv-renew.sh续签：
BUNDLE_ID="com.yourname.MoviePilotTV" bash scripts/apple-tv-renew.sh
BUNDLE_ID="com.yourname.MoviePilotTV" bash scripts/apple-tv-renew.sh --force脚本会检查本机已有构建中主 App 和 Top Shelf 的签名，全部有效时会跳过。需要重新构建和安装时加上 --force；重新构建不保证延长签名有效期。高级配置见签名与打包说明。
开发与测试
日常快速构建运行 python3 scripts/test-tvos.py，默认不执行测试；提交前完整验收使用 python3 scripts/test-tvos.py --full，tvOS 18.5、26.5 和最新的 27.x 会同时跑。脚本使用独立构建目录和临时模拟器，Xcode Test 也使用独立测试 App，避免影响日常开发和登录数据。完整命令见 AGENTS.md，签名、Top Shelf 和发布打包的技术细节见签名与打包说明。
后端兼容性测试
如需使用自己的 MoviePilot 后端验证 TV 端接口、图片和功能兼容性，请先阅读 后端兼容性测试文档。真实后端测试可能包含副作用套件，运行前请确认测试范围。
UI 预览测试分支
UI 预览测试请切到 ai/ui-preview-mode 分支，该分支不计划合并到 main。Debug 构建运行时添加启动参数 -uiPreviewMode。
反馈与贡献
- 提交 Bug：请务必提供 MoviePilot 版本号、相关截图和复现步骤。
- 功能建议：本项目专注提供基础的客厅浏览和订阅体验，过于复杂的后端配置管理等需求暂不考虑。
- 贡献代码：代码采用纯 Swift 编写。提交 PR 前请确保在真实 Apple TV 上测试过。
协议声明
本项目原创代码基于 CC0 1.0 Universal 协议发布（公有领域）。可自由复制、修改、发布和商业使用。
鸣谢
界面及交互设计参考了 MoviePilot-Frontend 与 Apple TV 官方应用，对相关开发者表示感谢。原项目的相关参考代码和逻辑遵循原作者的 MIT License。