couch-tv README

项目的 README,来自 github.com/Seagey/couch-tv。合并为一个 markdown 文件:README.md。

couch-tv on a TV: the Night home screen with the glass clock, Keep watching and the app dock

Your own home screen and phone remote for the TV.
Scenes with a glass clock, your apps in your order, Keep watching across apps, and a phone remote that finds a show and starts it. No ads on the home screen. Open source.

Latest release MIT licence Google TV, Android TV, Fire TV, Samsung, LG, Roku, Apple TV and more

Set it up  ·  Which TVs  ·  Docs  ·  What's new

Get started

  1. With your AI agent, the easiest way. Open this folder in Claude Code (or any coding agent) and say "set this up on my TV". It reads AGENTS.md, finds your TV, asks which option you want and a few questions (who watches, the look, your apps), reads the plan back, and changes nothing on the TV until you say yes.
  2. From your phone or a computer: couchtv.sites.underseage.studio, with the free Setup app on a Mac or Windows computer. It also checks whether your TV will work.
  3. By hand: docs/SETUP.md has every step, from developer mode to the TV home, and how to undo it.

Pick the way for your TV before you start. Not every way does the whole job on every TV:

Way What you need Google TV Android TV Fire TV Samsung or LG
AI agent (AGENTS.md) A computer on the TV's Wi-Fi with Claude Code or another coding agent Yes, Home button included Yes Yes, Home button included (Amazon's home flashes up first). The full phone remote keeps a computer on at home Yes, as an app that a computer at home that stays on opens. Their own Home button still opens their own menu
From your phone (website) The TV remote and a phone on the same Wi-Fi. No computer Only part: the app and the phone remote, but Google keeps the Home button. AI or the Setup app adds the Home button once, even afterwards Yes. On Android TV 10 and newer the app asks Android to make it the home Only part: Home needs three one off grants from a computer, and on current Fire OS the phone remote can't press keys or type No
Setup app (website) A Mac or Windows computer on the same Wi-Fi, once Yes, Home button included Yes, Android TV 7.1 and newer Yes on Fire OS 6, 7 and 8 (Amazon's home flashes up first) No
By hand (docs/SETUP.md) A Mac or Linux computer with Python 3.11 or newer Yes Yes on-tv/README.md, Fire TV docs/SAMSUNG.md, docs/LG.md, with a computer at home that stays on

Other TVs: Will it work on my TV?

[!NOTE] Set couch-tv up with 0.10 or older on a Google TV? 0.11 and newer leave the Google home and setup apps switched on. Read If your TV loops after a restart before you next restart your TV.

Updates

The newest release is 0.12 (9 November 2026), on the Releases page. These are on main, in the next release:

Every change, with credits: docs/UPDATES.md.

Three ways to run it

Will it work on my TV?

A is the TV home only, B adds the computer bridge, C lives on the TV (the three ways).

Your TV A B C
Google TV Yes Yes Partial
Google TV box Yes Yes Partial
Older Android TV Yes Yes Yes
Android 6 TV Experimental Not tested Experimental
XGIMI projector Yes Not reported Yes
Nvidia Shield Yes, untested Yes Yes, untested
Fire TV on Fire OS Partial Partial Partial
Fire TV on Vega OS App only Beta No
Samsung App only As an app No
LG App only As an app No
Roku App only As a channel No
Hisense VIDAA App only Beta No
Philips with Titan OS Not yet Remote only, Beta No
Older Philips with Saphi No Beta No
VIZIO No Remote, Beta (home in the TV's webview by hand, Beta, one set) No
Panasonic Viera No Beta No
Apple TV No Beta No
TiVo OS No Beta No

Beta means a computer at home that stays on, and the maker's own Home button still opens the maker's own home.

It depends on the model, not the brand. Open Settings, System, About (or Device Preferences, About) on the TV: "Android TV OS" means yes (brand by brand).

Want everything on a TV that is not Google TV or Android TV? Plug in a Google TV box (for example the Google TV Streamer) and set couch-tv up on that, and you get everything, on any TV with an HDMI port.

Test your own TV (changes nothing on it, and installs nothing outside this folder):

git clone https://github.com/Seagey/couch-tv.git && cd couch-tv
python3 --version                                  # needs 3.11 or newer
python3 -m venv .venv && .venv/bin/pip install -r bridge/requirements.txt
.venv/bin/python scripts/find-tvs.py               # lists the TVs on your Wi-Fi
.venv/bin/python scripts/check-tv.py <tv address>  # says which options that TV can run

It knocks on the ports each kind of TV answers on, so it can tell a Samsung from a Google TV without touching anything. More, including the check by hand and --adb: docs/PLATFORMS.md.

Home backgrounds

Five scenes take turns every 20 seconds, each with a big glass clock that sits just behind the scenery: the peaks, the volcano and the misty hills overlap the digits, and on the lake the clock floats with its reflection under the water. Or pick the Classic look, your own photos, or a scene you design yourself.

Night Golden hour Waterline Fog Dawn Classic

Night, Golden hour, Waterline, Fog, Dawn and Classic. Shown with sample shows and sample people.

The phone remote

Your phone becomes the remote: arrows, volume, typing and the power button. Ask for a show by name ("put on Bluey") and couch-tv finds where it streams and starts it in the right app, past "Who's watching?" on Android TV. There is an optional assistant for "put on something funny": Claude with the bridge, or Claude and other AI services in on-TV mode. Needs option B or C.

The phone remote: the Remote tab with The Bear playing, and the Watch tab with Keep watching and the apps

The phone remote · TV remotes and keys · Ask with any AI service

Kids mode

A kids profile's home is one shelf of shows you chose, as big posters that open straight into each show, plus only the apps you allow. No other apps, no settings, no grown ups' Keep watching. Leaving it needs the parent PIN. Optional, and off unless you set it up.

Kids mode on the TV The parent PIN

How Kids mode works and what it cannot do · Every setting

Settings on the TV

No computer and no config.json needed for the everyday settings. Pick the gear in the dock, or press the remote's own Settings button, and change the language, the place for the weather, the look and scenes, your apps and their order, the people and the quick buttons, with any remote.

Home settings on the TV

Every Home setting in full

And a lot more

One home, many TVs

The same home on Google TV and Android TV, an app on Apple TV, a channel on Roku, and Fire TV, Samsung and LG versions, with Beta paths for more.

Couch TV on Apple TV The couch-tv channel on Roku couch-tv on a Fire TV Stick

Apple TV (Beta), Roku and a Fire TV Stick.

Documentation

Set up Use Your TV
Every setup step The TV home Samsung
config.json, every setting The phone remote LG
On-TV mode, no computer TV remotes and keys Roku
The bridge in Docker Make your own scene Fire TV Stick
For your AI agent Ask with any AI service Hisense VIDAA
Take couch-tv off All updates Apple TV
Troubleshooting Two TVs in sync Every brand
Which TVs work How it works, privacy, limits Philips, Panasonic, VIZIO and more

Everything else: docs/.

Credits

Shout me a coffee

couch-tv is free. If it made your day a bit easier and you'd like to say thanks, you can shout me a coffee, any amount you like.

MIT licence, see LICENSE. Your settings, secrets and watch history stay on your own computer and TV: privacy and safety.

couch-tv (Seagey/couch-tv)

正在搜索数据库…

这是什么?couch-tv 会把 Google TV(现在也包括三星电视)上充满广告的主屏幕,替换成你自己的无广告主屏幕,还能加上手机遥控器,并可选安装 Claude 助手,让它理解诸如按剧情描述找节目之类的请求。
这个要我自己安装,还是让我的 AI 代理替我设置?把仓库交给你的 AI 编程代理即可。它会检测你用的是 Google TV 还是三星电视,并带你走对应的设置流程,你无需自己照着手动安装步骤操作。
我要怎么让它在电视上运行?有三个选项:A)只替换主屏幕,不需要电脑;B)添加电脑桥接,以启用手机遥控器、搜索和 Claude 助手;C)完全在电视上的应用里运行,不需要电脑。
我需要一直开着电脑吗?只有在你想用手机遥控器、“put on Bluey”搜索或 Claude 助手(选项 B)时才需要。这需要一台在家里常开的 Mac、Linux 设备或 Raspberry Pi;只替换主屏幕和在电视上运行这两个选项都不需要电脑。
每个电视品牌的使用方式都一样吗?不一样。只有在 Google TV/Android TV 上它才是真正替换主屏幕;在三星电视上,它只是一个需要你自己打开的应用,因为三星不允许任何东西替换其真正的主屏幕。而最新的 Fire TV 棒(Vega OS)则完全不支持。
Claude 助手能看到三星电视上实际正在播放的内容吗?不能。三星不会向网络暴露截图或播放状态,因此 couch-tv 是通过计算按键的时机来操作,而不是读取屏幕;在选择用户配置文件的界面上,它就直接选中当前高亮的那个配置文件。
动态主屏幕背景是什么样的?共有五个场景(山峰、火山、薄雾山丘、水岸、雾气),每 20 秒轮换一次,背后是半透明的玻璃质感时钟。你还可以添加自己的照片,或设计带有自定义时钟叠层的场景。
它能和我的智能家居系统集成吗?可以,但这是可选的。如果你已经在运行 Home Assistant,它可以以图块形式显示每个房间的空调、你的场景和脚本,并支持门铃摄像头叠层;不过在你自行配置之前,这些功能都是关闭的。
couch-tv 会用更新通知来烦我吗?只有在你同意时才会。首次启动时它会询问一次是否检查新版本;即便同意了,它也只大约每周向 GitHub 检查一次,并且始终提供手动的“Check for updates now”选项。
我可以在 Fire TV 棒上使用它吗?可以,但有一些限制。在 Fire OS 上,它通过变通方法实现,在 Amazon 自带的启动器短暂闪现后,把 Home 键的控制权拿回来;而在较新的 Fire TV Vega OS 上则完全不支持。
作者
Seagey
大小
33.8 MB
星标
1.5K
时长
23天
提交 · 90 天