couch-tv

Your own home screen and phone remote for a Google TV, and now a Samsung TV, with an LG path built and waiting for its first real LG. No ads on the home screen. Open source (MIT).

!The Night home screen

Updates

4 November 2026: Fire TV extras, from a fork. Thirty four people have forked couch-tv now. From killy10o10, who runs it on a Fire TV Stick 4K (2nd gen):

• Bluetooth and Network buttons at the top right of the home. Fire OS's long-press Home menu

• Amazon's own YouTube app on Fire TV is now recognised, with its logo, so it sorts and opens

• A Fire TV Stick guide, written on the stick itself: docs/FIRE-TV-STICK.md.

1 November 2026: LG TVs. couch-tv now has an LG version, done the same way as the Samsung one: it goes on your LG as an app through LG's Developer Mode, and the computer at home opens it every time the TV is switched on. It was built from LG's own documentation and tested against a stand-in, so if you have an LG, you would be among the first to run it: give this repo to your agent, and please open an issue saying how it went. Setup and limits: docs/LG.md.

3 November 2026: older Fire TV sticks (Fire OS 6). Both TV apps now install on Android 7.1, so the Fire TV Stick 4K (1st gen) and other Fire OS 6 sticks can run them. Options A and B also take the Home key back on any Fire TV now, the way the "lives on the TV" app already did: apply.sh switches on a small Home button watch, and the undo switches it off. Checked on Android 7.1, 9 and 14 emulators with a stand-in for Amazon's home, not yet on a real Fire OS 6 stick: if you have one, please open an issue saying how it went. It comes with the next release after 0.3.

30 October 2026: Fire TV sticks, older TVs, smart home and your own scenes. Sixteen people have forked couch-tv so far, and six of them built something worth having. The best of it is now in the main repo, credited to each of them. Download the new apps from the Releases page (or ask your agent to update).

• Fire TV sticks and Fire TV Cube (Fire OS). The "lives on the TV" app now takes the Home key

• Older TVs no longer crash on open. Both TV apps used a part of Android that only Android 11

• Keep watching with no computer. With no bridge (option A), Keep watching now fills from

• Smart home, if you want it. If you run Home Assistant, the home can show your air

• Design your own scene. Put the glass clock over any photo: a landscape, your own holiday

• Safer setup. apply.sh now makes couch-tv the chosen home and checks the TV took it before

• A build on every change. GitHub now builds both TV apps for every push and pull request, so

Thank you to fifarsi and ishanboss20 (the Android 9 crash), gurpritsingh81 (Watch Next), herocode1 (the safety fixes and the install order), dlandman27 (Fire TV) and roliusz (the doorbell, Home Assistant and own scenes).

29 October 2026: Samsung TVs. couch-tv now works on Samsung TVs too. It was tested on a 2021 Samsung Frame. It is the same link and the same setup: give this repo to your agent and it offers the Samsung path when it finds a Samsung.

What is the same on a Samsung: the home (scenes, clock, weather, your apps in your order), the phone remote, and the Claude assistant. "Put on that show about the lawyer who never went to law school" finds Suits and plays it.

What is different on a Samsung:

• You need a computer that stays on at home (a Mac, a Linux box or a Raspberry Pi on the same

• It is an app that opens itself, not a true home screen. Samsung does not let any app replace

• Playing a show. Netflix opens the show and starts it by itself. YouTube opens the video.

• No reading the screen. Samsung gives no screenshots and no "what is playing" to the network.

• You install the app yourself, with a free tool and your own Samsung account sign-in, after

• No picture mode switch and no ADB tools (those are Android only).

28 to 29 October 2026, every TV:

• "Put on X" now gets past "Who's watching?" on Android TVs: it presses your profile (you list your

• The phone remote no longer opens to a white page when the phone has just woken up

• The TV home works on older TV browsers too (the 2021 Frame showed no photos and two clocks).

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 bottom of the digits, and on the waterline scene the clock floats on the lake with a blurred reflection under the surface. Your apps and "keep watching" stay put. Start on one with ?scene=, or swap in your own photos. Design your own scene (any photo, or a place you describe, with your own clock and date over it, and the skyline in front of the clock if you like): docs/MAKE-A-SCENE.md.

| Night | Golden hour | Waterline | |---|---|---| | !Night | !Golden hour | !Waterline | | Fog | Dawn | Classic (?theme=classic) | | !Fog | !Dawn | !Classic |

Shown with sample shows and sample people. On your TV, "keep watching" fills from what you actually watch.

Settings on the TV

No computer and no config.json needed for the everyday settings. Press down to the dock and pick the gear, Settings (just before More apps). OK opens a small menu: Home settings is couch-tv's own list, TV settings is Android's own (Wi-Fi, picture, sound). The remote's own gear or Settings button opens the same menu (docs/REMOTES.md).

!Home settings on the TV

Any remote works: up and down move, right or OK opens a section, OK changes a row, holding OK on a scene, an app, a person or a quick button picks it up so up and down move it, and Back steps back and then closes. What you change shows when the list closes.

• Language: English, Español, Español (México), Italiano, Deutsch, Türkçe. Until one is picked here (or in

• Location: type a town or city with the TV's on-screen keyboard (or the phone remote's Type),

• Weather: show or hide it, °C or °F, check every 15, 30 or 60 minutes. Open-Meteo is the only

• Look and scenes: Night scenes or Classic; which scenes take turns, in what order, how many

• Apps: every app on the TV. OK moves it between home, More apps and hidden; hold OK to change

• People: add, rename, remove and reorder who is watching.
• Quick buttons: which of the sleep timer, picture mode, look and input buttons show, in what

• Updates: off until you say yes. The first time the home opens it asks once: "Tell you when a

• About: the version, the GitHub address (github.com/Seagey/couch-tv), where the settings are

Your own photos. On a TV with a file picker, Add photos from a USB drive or this TV opens it and copies the photos you choose into the app (turned the right way up and sized for the screen). Many Android TV and Google TV builds have no file picker; then the list says so and you add a photo from a web address instead (a JPEG or PNG on the internet, which the TV loads each time). The on-TV app (option C) only takes web addresses. Your photos take turns with the scenes and replace the Classic look's own.

Glass panels and a video background (optional, both off to start). Under Look, **Glass panels** puts clear, softly blurred panels with a light edge behind the clock, Keep watching and the apps, so the background shows through. Blur is heavy work for an older TV, so On, no blur keeps the panels and their edges without it; a TV that cannot blur at all gets that by itself. Video background plays a short clip that loops, muted, in place of the photo, in both looks: Video link takes the address of an MP4 or MOV on the web or on a computer at home, and the switch turns it off again without losing the link. The photo stays until the clip plays, and comes back if it will not play. The video stops while an app is in front. Over a video, the Night clock is frosted white instead of cut from the photo. Both are heavier than the plain home, so on a small TV stick switch them off if the home feels slow. Thanks alonmustafa (#22). Glass app icons (also under Look) turns the app icons grey on frosted glass, like Apple's clear icons, with the app you are on in its own colours (#25). The phone remote's app grid follows the TV's choice. Links straight to Apple's own server (sylvan.apple.com, the tvOS aerials) never play: it uses a certificate from Apple's private authority, which Android and Chrome do not trust. Copies of the same aerials on other hosts, or saved on a computer at home, play fine as MOV (#27).

Smart home (optional). If you already run Home Assistant, the home can show your air conditioning (each room's temperature, warmer, cooler, on, off and mode), your scenes and scripts as tiles, and a doorbell card with the door camera's picture over whatever is playing. It is off unless you add a home_assistant section to config.json; without it nothing changes. docs/CONFIG.md, Smart home, has the setup.

Where they are kept. On the TV, and with option B on the computer too, so the phone agrees and a reset TV gets them back. They win over config.json on that TV; About, Reset home settings goes back to it. docs/CONFIG.md has the details.

Languages. The TV home and the phone remote both speak English, Spanish (es, for Spain and everyone else), Mexican Spanish (es-MX: computadora, celular, presionar, clima and the rest), Italian (it), German (de) and Turkish (tr), all three with a 24 hour clock unless you pick 12 hour, and the smart home words Home Assistant uses in each. The phone has its own choice (TV menu, Language), "Same as the TV" by default. Messages that come from the bridge itself (an error, a note about how a show opened) and some screen reader labels on the phone are still in English.

Three ways to run it

• A. TV home only. The new home screen, nothing else. You use your normal TV remote and no

• B. Computer bridge. The home screen plus the phone remote, "put on Bluey" search, turning the

• C. Lives on the TV. The home screen and the phone remote with no computer: the bridge runs

Pick your option, then follow only its steps

- A: steps 1, 2 and 6 below. With no computer at all: step 1, then "Option A with no

computer" in step 6.

- B: steps 1 to 6 below.

- C: on-tv/README.md (it has its own developer mode and install steps).

Will it work on my TV?

| Your TV | A. TV home only | B. Computer bridge | C. Lives on the TV | |---|---|---|---| | Google TV (Sony, TCL, Hisense Google TV, Philips and others) | Yes | Yes | Partial. Newer models may ask for a pairing code again after a restart | | Google TV box (Google TV Streamer, Chromecast with Google TV, Onn) | Yes | Yes | Partial, as above | | Older Android TV (Android 7.1 to 11) | Yes | Yes | Yes | | Nvidia Shield | Yes (not tested) | Yes | Yes (not tested) | | Fire TV on Fire OS (Fire OS 6, 7 and 8: Fire TV Stick 4K 1st gen and newer, Stick 4K Max, Cube) | Partial. Takes the Home key back, but Amazon's home flashes up first | Partial | Yes, and it takes the Home key back (how) | | Fire TV on Vega OS (newer Fire TV sticks) | No | No | No | | Samsung (Tizen) | App only, opened from Samsung's app row | With a computer at home: yes, as an app that opens itself, not a true home screen (how) | No | | LG (webOS) | App only, opened from LG's app row, while Developer Mode lasts | With a computer at home: as an app that opens itself, like the Samsung. Built, and run on one real LG so far (how) | No | | Roku, Apple TV, Hisense with VIDAA | No | No | No |

Hisense, Sharp and other brands that sell more than one kind of TV: it depends on the model, not the brand. Their Google TV and Android TV models should work. Their VIDAA models run Hisense's own system and do not. Open Settings, System, About (or Device Preferences, About): "Android TV OS" means yes. Or run scripts/check-tv.py. Brand by brand (TCL, Philips, Panasonic, Sharp, Xiaomi and more, untested): docs/TV-BRANDS.md.

What you can and cannot do on each:

• Google TV and Android TV: everything in this repo. Your own home screen, your apps in your

• Fire TV (Fire OS): the phone remote and app launching work. Amazon does not let another home

• Samsung: it does not run Android apps and it locks its home screen, so couch-tv goes on as a

• LG: the same as the Samsung: couch-tv goes on as an LG app through LG's Developer Mode (free

• Roku, Apple TV, VIDAA and Vega OS Fire TV: closed. Nothing here works on them.

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 (Android TV, Samsung, LG, Roku, Apple), so it can tell a Samsung from a Google TV without touching anything. Or, by hand: on the TV open Settings, System, About (Google TV) or Settings, Device Preferences, About (Android TV 9 to 11). If you see "Android TV OS", it works. Details and sources: docs/TV-COMPATIBILITY.md.

Later, once Developer options are on (step 1), check-tv.py --adb also reads the Android version and the maker. That one makes the TV ask "Allow USB debugging?" and saves this computer's key in ~/.android/adbkey, so it waits until you have decided to go ahead.

Setting it up with an AI agent

Open this folder in Claude Code (or any coding agent) and say "set this up on my TV". It reads AGENTS.md and asks you two things before it touches anything: which TV you have, and which option you want.

This repo is two separate things. You can use the first without the second, but the second needs the first's TV set up the same way (developer mode on).

| | 1. The TV home | 2. The phone remote and bridge | |---|---|---| | What it is | An Android TV app that replaces the Google TV home screen. Scenes, clock, weather, your app row, "keep watching". | A phone web app (the remote) and a small Python service (the bridge) that runs on a computer at home and talks to the TV. | | Where it lives | tv-home/ (android/ is the app, web/ is its screen) | remote/ (phone app) and bridge/ (the service) | | Runs on | The TV | Your phone, plus a computer that stays on | | Options | A and B | B (C has its own app, in on-tv/) |

What you need

For every option:

• A Google TV or Android TV (Android 7.1 or newer) with Developer options and debugging on

• A computer on the same Wi-Fi to set it up from: macOS or Linux with Python 3.11 or newer

• The TV app, couch-tv-home.apk: download it from the GitHub Releases page, or build it

Option B also needs:

• An always-on computer on the same Wi-Fi: a Mac or a Linux box (a Raspberry Pi is fine).

• Node 20 or newer, once, to build the phone app.
• Optional, Claude "ask" ("put on something funny"): the Claude Code program, installed and

• Where a show streams: nothing to set up. The bridge asks JustWatch's public search (no key) for

• A free TMDB key is not needed by this code. If you add your own poster lookup, put the key in

The home with the computer off (option B): the app carries its own copy of the home and also keeps the bridge's latest copy. If the computer is off, the TV still shows the clock, the weather and your app row. It only loses "keep watching" and the picks. With option A that copy is the home.

Setup

Step 1. Developer mode on the TV (every option)

Do this on the TV itself.

1. Open Settings, then System, then About (Google TV). On Android TV 9 to 11 it is

1. Go right down to Android TV OS build (or Build). Press OK on it seven times. A

1. Go back. There is a new menu called Developer options (under System, or Device Preferences).
2. Find USB debugging and switch it on.
3. If there is also a Network debugging switch (also called ADB over network or ADB

1. Find the TV's address: Settings, Network and Internet, your Wi-Fi (or **Settings, Network,

The first time a computer connects, the TV asks "Allow USB debugging?". Tick Always allow and press Allow. You never see it again.

Allow every computer before you switch the Google home off. Seen on one Google TV

(Android 14): after apply.sh switched off the Google TV home and its setup app, the TV no longer

showed "Allow USB debugging?" for any new computer. Computers allowed before that kept working.

So connect each computer you will use (check-tv.py --adb, and for option C the

app's Connect ADB) and press Allow before step 6. If it already happened, see "If

something is stuck" in docs/UNINSTALL.md.

Only Wireless debugging? Newer Google TVs (Android 11 and up) may offer only **Wireless

debugging**, which pairs with a code and uses a random port that changes after a restart.

couch-tv's scripts and the bridge speak plain ADB on a fixed port, so turn the fixed port on once

with Google's own tools (Android platform-tools):

1. On the TV: Developer options, Wireless debugging on, then **Pair device with pairing

code**. It shows a code and an address with a port, for example :37123.

2. On the computer: adb pair : .

git clone https://github.com/Seagey/couch-tv.git
cd couch-tv
python3 --version                    # 3.11 or newer
python3 -m venv .venv
.venv/bin/pip install -r bridge/requirements.txt
cp config.example.json config.json

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

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

cd remote
npm ci
npm run build
cd ..

.venv/bin/python bridge/server.py

TV_IP=<your tv address> .venv/bin/python tv-home/tools/survey-tv.py

TV_IP=<your tv address> APK=couch-tv-home.apk sh tv-home/tools/apply.sh

TV_IP=<your tv address> APK=couch-tv-home.apk BRIDGE_URL=http://my-computer.local:5400 sh tv-home/tools/apply.sh

$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager "platforms;android-34" "build-tools;34.0.0"
   $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager --licenses     # answer y to each licence

JAVA_HOME=/path/to/jdk-21 ANDROID_HOME=/path/to/android-sdk sh scripts/build-apk.sh

phone remote (remote/)  --->  bridge (bridge/, always-on computer)  --->  the TV
TV home (tv-home/)      --->  bridge (for shows and picks)               (Android TV Remote
                              TV home carries its own copy for when       protocol and ADB)
                              there is no bridge