couch-tv完整入门指南:3种部署方式,5分钟打造你自己的电视遥控器

原创2026-11-14 20:33:311,443 阅读

couch-tv完整入门指南:3种部署方式,5分钟打造你自己的电视遥控器

couch-tv 是一个免费开源项目,帮你把电视变成自己的:用一个带玻璃时钟和风景场景的电视主屏幕替换 Google TV 默认主页(没有广告),再把手机变成完整的电视遥控器——方向键、音量、打字输入、电源开关全都有,还可以选配 Claude AI 助手,说一句"放部喜剧"它就找到并开播。这篇文章带你用 3 种部署方式,从零开始 5 分钟搭建好自己的电视遥控器。

couch-tv 电视主屏幕:夜景场景、玻璃时钟与 Keep watching 续看栏

1分钟了解 couch-tv:它是什么

一句话概括:你自己的 Google TV 主页 + 手机遥控器,外加可选的 Claude 助手。核心能力包括:

功能 说明
🏠 场景主屏幕 5 套风景场景每 20 秒轮换(夜晚、黄昏、水面、雾、黎明),支持自己的照片和 Classic 风格
📱 手机遥控器 手机浏览器打开即用,方向键、音量、打字、电源按钮一应俱全
🔍 按名字找片 "放 Bluey",couch-tv 自动找到该剧在哪个流媒体平台并直接开播
▶️ Keep watching 跨 App 的"续看"栏目,最多 10 部剧,按人区分
🧒 儿童模式 只放你选好的节目,退出需要家长 PIN 码
🤖 AI 助手(可选) 接入 Claude 等 AI 服务,"放部搞笑的"这种模糊需求也能搞定
🏠 智能家庭 可接 Home Assistant:空调、场景、门铃卡片

couch-tv 手机遥控器界面:Remote 遥控页与 Watch 观看页

1分钟兼容性检查:我的电视能用吗

先说结论:Google TV / Android TV 体验最完整,三星、LG、Roku、Apple TV 等也有对应方案(多为 Beta)。在电视上打开 设置 → 系统 → 关于,看到 "Android TV OS" 字样就说明支持。

不确定也不怕,项目自带只读检测脚本,不改动电视任何内容:

.venv/bin/python scripts/find-tvs.py               # 列出 Wi-Fi 上所有电视
.venv/bin/python scripts/check-tv.py <电视地址>     # 判断这台电视能跑哪几种方式

脚本通过探测各品牌电视的端口来识别设备(比如 Roku 的 8060 端口),全程只读。完整兼容矩阵见 docs/PLATFORMS.md。

3种部署方式对比:5分钟选对你的方案

couch-tv 提供三种运行方式,按"要不要一台常开的电脑"来区分:

A. 仅电视主页 B. 电脑桥接 C. 电视内运行(On-TV)
新主屏幕 ✅ ✅ ✅
手机遥控器 ❌ ✅ ✅
需要常开的电脑 不需要 需要(Mac / Linux / 树莓派) 不需要
远程开机电视 ❌ ✅(Wake-on-LAN) ❌
跨 App 续看 部分 ✅ 部分
AI 助手 ❌ ✅(Claude) 可选(自带 API key)

选择建议:只想换个清爽主页 → 方式 A;有一台家里常开的电脑或 NAS → 方式 B(功能最全、测试最充分);没有常开电脑但想要手机遥控器 → 方式 C。

方式一:AI 代部署(新手最快路径)

这是官方推荐的最简单方式:把仓库交给 AI agent,它会自动找电视、问问题、给出计划,你确认之前不会改动电视任何东西。

第 1 步:克隆仓库

git clone https://gitcode.com/gh_mirrors/co/couch-tv
cd couch-tv
python3 -m venv .venv && .venv/bin/pip install -r bridge/requirements.txt

第 2 步:打开 AI 编程助手(如 Claude Code),对它说:"set this up on my TV"(在我的电视上部署)。

它会读取 AGENTS.md 中的指令,按顺序执行:

  1. 找电视:运行 scripts/find-tvs.py 和 scripts/check-tv.py,向你念出检测结果;
  2. 提问:谁看这台电视、喜欢什么视觉风格、常用哪些 App、要不要儿童模式和 PIN 码;
  3. 复述计划:把完整方案读给你听,等你明确说"yes"才会动手;
  4. 部署并验证:装好主页、配好遥控器,最后教你怎么撤销。

整个过程你只需要回答几个问题 + 在电视上按两次"允许"。

couch-tv 儿童模式主页:大海报节目架与家长 PIN 码保护

方式二:电脑桥接(功能最全,B 方案)

适合家里有一台 Mac、Linux 主机或树莓派可以常开。全部步骤在 docs/SETUP.md,这里给你精简版。

第 1 步:开启电视开发者模式(所有方式都需要)

  1. 电视上:设置 → 系统 → 关于 → Android TV OS 版本号,连续按 7 次,解锁开发者选项;
  2. 打开 USB debugging(USB 调试),如有 Network debugging 也打开;
  3. 记住电视的 IP 地址(设置 → 网络 → 你的 Wi-Fi),建议在路由器上给电视设固定地址。

第 2 步:配置 config.json

cp config.example.json config.json

打开 config.example.json 照着填:tvs 填电视 IP、people 填家里成员名字、weather 填城市坐标、country 填两位国家码。每个字段的完整说明在 docs/CONFIG.md。

第 3 步:配对电视

.venv/bin/python bridge/pair_tv.py living-room

电视会显示一个 6 位验证码,输入即可,电视会把它识别为"Couch TV bridge"遥控器。

第 4 步:构建手机遥控器并启动 bridge

cd remote && npm ci && npm run build && cd ..
.venv/bin/python bridge/server.py

在手机上打开 http://你的电脑地址:5400,点"添加到主屏幕",遥控器就装好了(docs/REMOTE.md 有 iPhone / Android 的详细步骤)。

第 5 步:把主屏幕装到电视上

TV_IP=<电视地址> APK=couch-tv-home.apk BRIDGE_URL=http://<电脑地址>:5400 sh tv-home/tools/apply.sh

apply.sh 会安装 App 并设为主页。放心:它只关环境模式广告,电视自带主页和设置 App 都保持开启,随时可安全撤销。

想让 bridge 常驻运行? 用 macOS 的 launchd 或 Linux 的 systemd 示例文件:

用 Docker 跑在 NAS 上? 仓库自带 Compose 配置(Synology 等 NAS 均可):

docker compose -f examples/docker/compose.yaml up -d --build

原理和排坑细节见 docs/DOCKER.md 与 examples/docker/compose.yaml。

方式三:On-TV 模式(不用任何电脑)

方式 C 把 bridge 直接装进电视上的一个 App(dev.couchtv.ontv,显示名 Couch TV):手机遥控器由电视自己提供(http://<电视IP>:5400),电视通过自己的调试端口控制自己,家里什么都不用常开。

步骤精简版(完整指南见 on-tv/README.md):

  1. 开启开发者模式(同方式二第 1 步);
  2. 安装 couch-tv-ontv.apk(从 Releases 下载,或用 sh scripts/build-apk.sh 自行构建):
.venv/bin/python on-tv/scripts/real-tv.py --ip <电视IP> install couch-tv-ontv.apk
  1. 电视上打开 Couch TV App,它会显示地址和一个 6 位配对码;
  2. 手机打开该地址、输入配对码,遥控器配好;
  3. (可选)在 App 里打开 Use as home screen,让它接管主页。

注意:方式 C 不能远程开机电视(电视休眠后 App 也睡了);Samsung/LG/Roku/Apple TV 等非 Android 电视不支持此方式,请走方式 B。

Roku 版 couch-tv 频道:同一套主屏幕也能跑在 Roku 上

装好之后:5分钟玩出花样

1. 在电视上改设置,不用碰电脑

主页底部齿轮图标(或按遥控器设置键)打开 Home settings:语言、天气城市、场景、12/24 小时制、App 顺序、人物列表、快捷按钮,全部可视化修改。

couch-tv 电视端设置页:语言、场景、App 与快捷按钮一目了然

2. 按住 App 名称的 OK 键即可拖动调整 App 顺序;App Store 磁贴里可以添加新 App。

3. 开启儿童模式(可选):给小孩建一个 profile 并标记 "kid": true,再配置儿童主页——一排放大海报的节目架 + 最多 6 个允许的 App,退出要家长 PIN。详见 docs/TV-HOME.md。

4. 换个心情换个景:不满意的内置场景?任意一张照片都能用 docs/MAKE-A-SCENE.md 一键做成带玻璃时钟的自定义场景。

安全、隐私与撤销

  • 数据不出门:你的设置、密钥、观看历史全部只存在自己的电脑和电视上;
  • bridge 无密码:默认同网段任何人(包括孩子)都能用遥控器,建议访客走访客 Wi-Fi,或在 config.json 里设置 bridge.pairing_key 加密码;
  • 绝不端口转发:bridge 只适合内网,远程使用请走自建 VPN;
  • 随时可撤销:apply.sh 不删除任何东西。恢复 Google 主页:
TV_IP=<电视地址> sh tv-home/tools/undo.sh

完整卸载指南(含只用电视遥控器的撤销法)见 docs/UNINSTALL.md。

延伸阅读

想了解 看这里
全部部署细节与撤销 docs/SETUP.md
config.json 每个字段 docs/CONFIG.md
手机遥控器安装细节 docs/REMOTE.md
电视主页全部功能 docs/TV-HOME.md
各品牌电视专属指南(三星/LG/Roku…) docs/README.md
故障排查 docs/TROUBLESHOOTING.md

最后提醒:部署前建议给电视和电脑都设好路由器固定 IP,这是后续 90% 小问题的根源。现在去克隆仓库、交给你的 AI 助手,5 分钟后你的电视就不一样了 🛋️

登录后查看全文
couch-tv