[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-105351":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":15,"stars7d":15,"stars30d":15,"stars90d":14,"forks30d":14,"starsTrendScore":16,"compositeScore":17,"rankGlobal":9,"rankLanguage":9,"license":18,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":19,"hasPages":19,"topics":21,"createdAt":9,"pushedAt":9,"updatedAt":26,"readmeContent":27,"aiSummary":9,"trendingCount":14,"starSnapshotCount":14,"syncStatus":13,"lastSyncTime":28,"discoverSource":29},105351,"couch-tv","Seagey\u002Fcouch-tv","Seagey","Your own Google TV home screen and phone remote, with an optional Claude assistant. Set it up by handing this repo to your AI agent.",null,"Python",130,21,2,0,23,69,73.77,"MIT License",false,"main",[22,23,24,25],"android-tv","claude-code","google-tv","home-screen","2026-11-01 00:14:52","# couch-tv\n\nYour own home screen and phone remote for a Google TV, and now a Samsung TV. No ads on the home\nscreen. Open source (MIT).\n\n![The Night home screen](docs\u002Fscreens\u002Fhome-night.jpg)\n\n## Updates\n\n**30 October 2026: Fire TV sticks, older TVs, smart home and your own scenes.** Sixteen people\nhave forked couch-tv so far, and six of them built something worth having. The best of it is now in\nthe main repo, credited to each of them. Download the new apps from\n[the Releases page](https:\u002F\u002Fgithub.com\u002FSeagey\u002Fcouch-tv\u002Freleases) (or ask your agent to update).\n\n- **Fire TV sticks and Fire TV Cube (Fire OS).** The \"lives on the TV\" app now takes the Home key\n  back: Amazon's own home cannot be switched off, so the app sees it come up and puts couch-tv's\n  home straight back on top. Amazon's home still flashes up for a moment first. It needs two\n  one-off grants from a computer: [on-tv\u002FREADME.md](on-tv\u002FREADME.md#fire-tv-fire-os). Confirmed\n  on a Fire TV Stick 4K (2nd gen, Fire OS 8) by [killy10o10](https:\u002F\u002Fgithub.com\u002FSeagey\u002Fcouch-tv\u002Fissues\u002F3).\n- **Older TVs no longer crash on open.** Both TV apps used a part of Android that only Android 11\n  and newer have. On Android 9 and 10 (most Fire TV sticks, and many older Android TVs) the home\n  crashed as it opened. Fixed and checked on an Android 9 emulator: the old apps crash, the new\n  ones open.\n- **Keep watching with no computer.** With no bridge (option A), Keep watching now fills from\n  Android's own Watch Next list: what each app says you are part way through, with its picture\n  and how far in you are.\n- **Smart home, if you want it.** If you run Home Assistant, the home can show your air\n  conditioning (each room, warmer, cooler, on, off, mode), your scenes as tiles, and a doorbell\n  card with the door camera over whatever is playing. It is off for everyone unless they set it\n  up, and your agent asks first ([docs\u002FCONFIG.md](docs\u002FCONFIG.md), Smart home).\n- **Design your own scene.** Put the glass clock over any photo: a landscape, your own holiday\n  shot, anything. Optionally let the skyline sit in front of the clock, like the built-in scenes.\n  [docs\u002FMAKE-A-SCENE.md](docs\u002FMAKE-A-SCENE.md).\n- **Safer setup.** `apply.sh` now makes couch-tv the chosen home and checks the TV took it before\n  it switches anything off (on some TVs the other order can leave Home on a crash-looping setup\n  screen). The TV app also checks the settings it is handed more strictly.\n- **A build on every change.** GitHub now builds both TV apps for every push and pull request, so\n  a change that breaks the build shows straight away.\n\nThank you to [fifarsi](https:\u002F\u002Fgithub.com\u002Ffifarsi\u002Fcouch-tv) and\n[ishanboss20](https:\u002F\u002Fgithub.com\u002Fishanboss20\u002Fcouch-tv) (the Android 9 crash),\n[gurpritsingh81](https:\u002F\u002Fgithub.com\u002Fgurpritsingh81\u002Fcouch-tv) (Watch Next),\n[herocode1](https:\u002F\u002Fgithub.com\u002Fherocode1\u002Fcouch-tv-hero) (the safety fixes and the install order),\n[dlandman27](https:\u002F\u002Fgithub.com\u002Fdlandman27\u002Fcouch-tv) (Fire TV) and\n[roliusz](https:\u002F\u002Fgithub.com\u002Froliusz\u002Fcouch-tv) (the doorbell, Home Assistant and own scenes).\n\n**29 October 2026: Samsung TVs.** couch-tv now works on Samsung TVs too. It was tested on a 2021\nSamsung Frame. It is the same link and the same setup: give this repo to your agent and it offers\nthe Samsung path when it finds a Samsung.\n\nWhat is the same on a Samsung: the home (scenes, clock, weather, your apps in your order), the phone\nremote, and the Claude assistant. \"Put on that show about the lawyer who never went to law school\"\nfinds Suits and plays it.\n\nWhat is different on a Samsung:\n\n- **You need a computer that stays on at home** (a Mac, a Linux box or a Raspberry Pi on the same\n  Wi-Fi, option B below). It opens couch-tv every time the TV is switched on, and it is what the\n  phone remote and the assistant talk to. Without it you can only open couch-tv yourself from\n  Samsung's app row.\n- **It is an app that opens itself, not a true home screen.** Samsung does not let any app replace\n  its home. The TV remote's own Home button still opens Samsung's menu; Home on the phone remote\n  brings couch-tv back.\n- **Playing a show.** Netflix opens the show and starts it by itself. YouTube opens the video.\n  Prime Video, Stan, Binge, Paramount+ and Apple TV are handed the title by the couch-tv app on the\n  TV, the way Samsung's own guide does it; so far Prime has been seen opening, the title page itself\n  is still to be confirmed. Disney+ and the rest open on their home page and you pick the show.\n- **No reading the screen.** Samsung gives no screenshots and no \"what is playing\" to the network.\n  So Play is pressed by timing, not by looking (only Netflix's timing is tested so far), and on a\n  \"Who's watching?\" screen couch-tv takes the highlighted profile, usually the first, rather than\n  yours by name.\n- **You install the app yourself**, with a free tool and your own Samsung account sign-in, after\n  turning on the TV's Developer Mode. A firmware update can turn Developer Mode off again; then you\n  repeat one step.\n- No picture mode switch and no ADB tools (those are Android only).\n\nOne bridge can run your Google TVs and your Samsung together, and the phone remote switches between\nthem. Full guide, limits and undo: [docs\u002FSAMSUNG.md](docs\u002FSAMSUNG.md).\n\n**28 to 29 October 2026, every TV:**\n\n- \"Put on X\" now gets past \"Who's watching?\" on Android TVs: it presses your profile (you list your\n  names per person, [docs\u002FCONFIG.md](docs\u002FCONFIG.md)) and then Play.\n- The phone remote no longer opens to a white page when the phone has just woken up\n  ([docs\u002FREMOTE.md](docs\u002FREMOTE.md)).\n- The TV home works on older TV browsers too (the 2021 Frame showed no photos and two clocks).\n\n## Home backgrounds\n\nFive scenes take turns every 20 seconds, each with a big glass clock that sits just behind the\nscenery: the peaks, the volcano and the misty hills overlap the bottom of the digits, and on the\nwaterline scene the clock floats on the lake with a blurred reflection under the surface. Your apps\nand \"keep watching\" stay put. Start on one with `?scene=\u003Cname>`, or swap in your own photos.\n**Design your own scene** (any photo, or a place you describe, with your own clock and date over\nit, and the skyline in front of the clock if you like): [docs\u002FMAKE-A-SCENE.md](docs\u002FMAKE-A-SCENE.md).\n\n| Night | Golden hour | Waterline |\n|---|---|---|\n| ![Night](docs\u002Fscreens\u002Fhome-night.jpg) | ![Golden hour](docs\u002Fscreens\u002Fhome-golden.jpg) | ![Waterline](docs\u002Fscreens\u002Fhome-water.jpg) |\n| **Fog** | **Dawn** | **Classic** (`?theme=classic`) |\n| ![Fog](docs\u002Fscreens\u002Fhome-fog.jpg) | ![Dawn](docs\u002Fscreens\u002Fhome-dawn.jpg) | ![Classic](docs\u002Fscreens\u002Fhome-classic.jpg) |\n\nShown with sample shows and sample people. On your TV, \"keep watching\" fills from what you\nactually watch.\n\n## Settings on the TV\n\nNo computer and no `config.json` needed for the everyday settings. Press down to the dock and\npick the gear, **Settings** (just before More apps). OK opens a small menu: **Home settings** is\ncouch-tv's own list, **TV settings** is Android's own (Wi-Fi, picture, sound).\n\n![Home settings on the TV](docs\u002Fscreens\u002Fhome-settings.jpg)\n\nAny remote works: up and down move, right or OK opens a section, OK changes a row, holding OK on a\nscene, an app, a person or a quick button picks it up so up and down move it, and Back steps back\nand then closes. What you change shows when the list closes.\n\n- **Language:** English, Español, Español (México), Italiano. Until one is picked here (or in\n  `config.json`), the home speaks the TV's own language if it is one of these, else English.\n- **Location:** type a town or city with the TV's on-screen keyboard (or the phone remote's Type),\n  pick it from the places found. It sets the weather's place and time zone. The place search is\n  Open-Meteo's, free and with no key. Each place shows what it belongs to (its municipality,\n  province or county, and region), so towns with the same name can be told apart; in Italian the\n  places in Italy come first.\n- **Weather:** show or hide it, °C or °F, check every 15, 30 or 60 minutes. Open-Meteo is the only\n  weather provider for now.\n- **Look and scenes:** Night scenes or Classic; which scenes take turns, in what order, how many\n  seconds each; a 12 or 24 hour clock; your own photos (below).\n- **Apps:** every app on the TV. OK moves it between home, More apps and hidden; hold OK to change\n  the order. The same order as holding OK on the dock and the phone's Arrange apps.\n- **People:** add, rename, remove and reorder who is watching.\n- **Quick buttons:** which of the sleep timer, picture mode, look and input buttons show, in what\n  order.\n- **Updates:** off until you say yes. The first time the home opens it asks once: \"Tell you when a\n  new couch-tv version is out?\" (setup can answer it for you, `home.updates`). With **Tell me about\n  new versions** on, the TV looks on GitHub once a week, so frequent releases never nag; with it off\n  nothing is checked by itself. **Check for updates now** looks straight away either way. A new release\n  puts a small dot on the gear tile and a line on the home. **Update to ...** downloads it, checks\n  it, and hands it to Android, which asks \"Do you want to update this app?\" first. Your settings,\n  people, photos and apps stay. The first time, Android asks you to let Home install apps\n  (Settings, Security and restrictions, Unknown sources). Only the app from the Releases page\n  updates this way. A copy built on your own computer, for example with your own scenes, says so\n  and is updated the way you installed it. The on-TV app (option C) does not do this yet.\n- **About:** the version, the GitHub address (github.com\u002FSeagey\u002Fcouch-tv), where the settings are\n  kept, and Reset.\n\n**Your own photos.** On a TV with a file picker, **Add photos from a USB drive or this TV** opens it\nand copies the photos you choose into the app (turned the right way up and sized for the screen).\nMany Android TV and Google TV builds have no file picker; then the list says so and you add a photo\nfrom a web address instead (a JPEG or PNG on the internet, which the TV loads each time). The on-TV\napp (option C) only takes web addresses. Your photos take turns with the scenes and replace the\nClassic look's own. Videos are not supported: a looping video under the glass clock and the\nblurred dock is heavy work for a small TV stick, and the clock's frosted fill is cut from a still\nphoto.\n\n**Smart home (optional).** If you already run Home Assistant, the home can show your air\nconditioning (each room's temperature, warmer, cooler, on, off and mode), your scenes and scripts\nas tiles, and a doorbell card with the door camera's picture over whatever is playing. It is off\nunless you add a `home_assistant` section to `config.json`; without it nothing changes.\n[docs\u002FCONFIG.md](docs\u002FCONFIG.md), Smart home, has the setup.\n\n**Where they are kept.** On the TV, and with option B on the computer too, so the phone agrees and a\nreset TV gets them back. They win over `config.json` on that TV; About, Reset home settings goes\nback to it. [docs\u002FCONFIG.md](docs\u002FCONFIG.md) has the details.\n\n**Languages.** The TV home and the phone remote both speak English, Spanish (`es`, for Spain and\neveryone else), Mexican Spanish (`es-MX`: computadora, celular, presionar, clima and the rest) and\nItalian (`it`, with a 24 hour clock unless you pick 12 hour, and the smart home words Home\nAssistant uses in Italian). The phone has its own choice (TV menu, Language), \"Same as the TV\" by\ndefault. Messages that come from the bridge itself (an error, a note about how a show opened) and\nsome screen reader labels on the phone are still in English.\n\n## Three ways to run it\n\n- **A. TV home only.** The new home screen, nothing else. You use your normal TV remote and no\n  computer has to stay on.\n- **B. Computer bridge.** The home screen plus the phone remote, \"put on Bluey\" search, turning the\n  TV on from the phone, keep watching across apps and an optional Claude assistant. A computer at\n  home (a Mac, a Linux box or a Raspberry Pi) stays on and runs the bridge.\n- **C. Lives on the TV.** The home screen and the phone remote with no computer: the bridge runs\n  inside an app on the TV. See [on-tv\u002FREADME.md](on-tv\u002FREADME.md).\n\n> **Pick your option, then follow only its steps**\n> - **A:** steps 1, 2 and 6 below.\n> - **B:** steps 1 to 6 below.\n> - **C:** [on-tv\u002FREADME.md](on-tv\u002FREADME.md) (it has its own developer mode and install steps).\n\n## Will it work on my TV?\n\n| Your TV | A. TV home only | B. Computer bridge | C. Lives on the TV |\n|---|---|---|---|\n| **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 |\n| **Google TV box** (Google TV Streamer, Chromecast with Google TV, Onn) | Yes | Yes | Partial, as above |\n| **Older Android TV** (Android 9 to 11) | Yes | Yes | Yes |\n| **Nvidia Shield** | Yes (not tested) | Yes | Yes (not tested) |\n| **Fire TV on Fire OS** (Fire TV Stick 4K Max, Fire TV Cube) | Partial. Workarounds only, and Amazon's home flashes up first | Partial | Yes, and it takes the Home key back ([how](on-tv\u002FREADME.md#fire-tv-fire-os)) |\n| **Fire TV on Vega OS** (newer Fire TV sticks) | No | No | No |\n| **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](docs\u002FSAMSUNG.md)) | No |\n| **LG** (webOS) | Possible, untested ([research](docs\u002FLG.md)) | Possible, untested | No |\n| **Roku, Apple TV, Hisense with VIDAA** | No | No | No |\n\n**Hisense, Sharp and other brands that sell more than one kind of TV:** it depends on the model,\nnot the brand. Their Google TV and Android TV models should work. Their VIDAA models run\nHisense's own system and do not. Open **Settings, System, About** (or\n**Device Preferences, About**): \"Android TV OS\" means yes. Or run `scripts\u002Fcheck-tv.py`.\nBrand by brand (TCL, Philips, Panasonic, Sharp, Xiaomi and more, untested):\n[docs\u002FTV-BRANDS.md](docs\u002FTV-BRANDS.md).\n\n**What you can and cannot do on each:**\n- **Google TV and Android TV:** everything in this repo. Your own home screen, your apps in your\n  order, the phone remote, finding and playing shows, the sleep timer. Some Google Home features and\n  the YouTube button on the remote can stop working once the Google home is switched off.\n- **Fire TV (Fire OS):** the phone remote and app launching work. Amazon does not let another home\n  screen replace its own, so the \"lives on the TV\" app (option C) watches for Amazon's home and puts\n  couch-tv's home back on top; Amazon's home still flashes up for a moment first. It needs two\n  one-off ADB grants: [on-tv\u002FREADME.md](on-tv\u002FREADME.md#fire-tv-fire-os).\n- **Samsung:** it does not run Android apps and it locks its home screen, so couch-tv goes on as a\n  Samsung app (you install it with a free tool and your own Samsung sign-in), and the bridge opens\n  it every time the TV is switched on, so it needs a computer that stays on. Samsung's own Home\n  button still opens Samsung's menu. The phone remote and the assistant work: Netflix plays the\n  show by itself, YouTube opens the video, Prime Video, Stan, Binge, Paramount+ and Apple TV are\n  handed the title, and other apps open on their home page. No \"what is playing\" and no\n  screenshots. Setup and limits: [docs\u002FSAMSUNG.md](docs\u002FSAMSUNG.md).\n- **LG:** the same approach should work (LG has a Developer Mode and a network remote), but nobody\n  has tried it yet: [docs\u002FLG.md](docs\u002FLG.md).\n- **Roku, Apple TV, VIDAA and Vega OS Fire TV:** closed. Nothing here works on them.\n\n**Want everything on a Samsung, LG or another TV?** Plug in a Google TV box (for example the Google\nTV Streamer) and set couch-tv up on that. You then get everything, on any TV with an HDMI port.\n\n**Test your own TV** (changes nothing on it, and installs nothing outside this folder):\n\n```sh\ngit clone https:\u002F\u002Fgithub.com\u002FSeagey\u002Fcouch-tv.git && cd couch-tv\npython3 --version                                  # needs 3.11 or newer\npython3 -m venv .venv && .venv\u002Fbin\u002Fpip install -r bridge\u002Frequirements.txt\n.venv\u002Fbin\u002Fpython scripts\u002Ffind-tvs.py               # lists the TVs on your Wi-Fi\n.venv\u002Fbin\u002Fpython scripts\u002Fcheck-tv.py \u003Ctv address>  # says which options that TV can run\n```\n\nIt knocks on the ports each kind of TV answers on (Android TV, Samsung, LG, Roku, Apple), so it\ncan tell a Samsung from a Google TV without touching anything. Or, by hand: on the TV open\n**Settings, System, About** (Google TV) or **Settings, Device Preferences, About** (Android TV 9 to\n11). If you see \"Android TV OS\", it works. Details and sources:\n[docs\u002FTV-COMPATIBILITY.md](docs\u002FTV-COMPATIBILITY.md).\n\nLater, once Developer options are on (step 1), `check-tv.py \u003Ctv address> --adb` also reads the\nAndroid version and the maker. That one makes the TV ask \"Allow USB debugging?\" and saves this\ncomputer's key in `~\u002F.android\u002Fadbkey`, so it waits until you have decided to go ahead.\n\n## Setting it up with an AI agent\n\nOpen this folder in Claude Code (or any coding agent) and say \"set this up on my TV\". It reads\n[AGENTS.md](AGENTS.md) and asks you two things before it touches anything: which TV you have, and\nwhich option you want.\n\nThis repo is **two separate things**. You can use the first without the second, but the second\nneeds the first's TV set up the same way (developer mode on).\n\n| | 1. The TV home | 2. The phone remote and bridge |\n|---|---|---|\n| 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. |\n| Where it lives | `tv-home\u002F` (`android\u002F` is the app, `web\u002F` is its screen) | `remote\u002F` (phone app) and `bridge\u002F` (the service) |\n| Runs on | The TV | Your phone, plus a computer that stays on |\n| Options | A and B | B (C has its own app, in `on-tv\u002F`) |\n\n## What you need\n\n**For every option:**\n- A **Google TV or Android TV** (Android 9 or newer) with Developer options and debugging on\n  (step 1).\n- A computer on the same Wi-Fi to set it up from: macOS or Linux with **Python 3.11 or newer**\n  (`python3 --version`). Missing or older: on macOS `brew install python@3.11` or the installer\n  from python.org; on Linux your distribution's package (for example `sudo apt install python3.11\n  python3.11-venv`). On a Mac the first `python3` or `git` may ask to install the developer tools:\n  say Install, it takes a few minutes. For option A that computer can go back in the cupboard\n  afterwards.\n- The TV app, `couch-tv-home.apk`: **download it from the GitHub Releases page**, or build it\n  yourself (\"Building the app\" below).\n\n**Option B also needs:**\n- An **always-on computer on the same Wi-Fi**: a Mac or a Linux box (a Raspberry Pi is fine).\n  The bridge has to be running whenever you want the remote.\n- **Node 20 or newer**, once, to build the phone app.\n- Optional, **Claude \"ask\"** (\"put on something funny\"): the Claude Code program, installed and\n  logged in to your own Claude plan. It runs `claude -p` and strips `ANTHROPIC_API_KEY` from the\n  environment first, so it never bills an API key. It is off in `config.example.json`; turn it on\n  (`\"ask\": {\"enabled\": true}`) once Claude Code works on that computer.\n- Where a show streams: nothing to set up. The bridge asks JustWatch's public search (no key) for\n  the country in `config.json` (`\"country\": \"AU\"`, or `\"US\"`, `\"GB\"` and so on).\n- A free **TMDB key is not needed** by this code. If you add your own poster lookup, put the key in\n  `.env` (see `env.example`). Never commit it.\n\n**The home with the computer off (option B):** the app carries its own copy of the home and also\nkeeps the bridge's latest copy. If the computer is off, the TV still shows the clock, the weather\nand your app row. It only loses \"keep watching\" and the picks. With option A that copy is the home.\n\n## Setup\n\n### Step 1. Developer mode on the TV (every option)\n\nDo this on the TV itself.\n\n1. Open **Settings**, then **System**, then **About** (Google TV). On Android TV 9 to 11 it is\n   **Settings, Device Preferences, About**.\n2. Go right down to **Android TV OS build** (or **Build**). Press OK on it **seven times**. A\n   countdown appears, then \"You are now a developer!\".\n3. Go back. There is a new menu called **Developer options** (under System, or Device Preferences).\n4. Find **USB debugging** and switch it on.\n5. If there is also a **Network debugging** switch (also called ADB over network or ADB\n   debugging), switch it on too. Some TVs have no such switch: on a TCL with Android TV 11, USB\n   debugging alone opened the network port. Either way, check from the computer:\n   `.venv\u002Fbin\u002Fpython scripts\u002Fcheck-tv.py \u003Ctv address>`. If it says ADB is open on port 5555,\n   everything in this repo works as it is. If it says only Wireless debugging is on, see the box\n   below.\n6. Find the TV's address: **Settings, Network and Internet, your Wi-Fi** (or **Settings, Network,\n   your Wi-Fi, details**). It looks like four numbers with dots. Give the TV a fixed address in your\n   router if you can, so it never changes.\n\nThe first time a computer connects, the TV asks \"Allow USB debugging?\". Tick **Always allow**\nand press **Allow**. You never see it again.\n\n> **Allow every computer before you switch the Google home off.** Seen on one Google TV\n> (Android 14): after `apply.sh` switched off the Google TV home and its setup app, the TV no longer\n> showed \"Allow USB debugging?\" for any new computer. Computers allowed before that kept working.\n> So connect each computer you will use (`check-tv.py \u003Ctv address> --adb`, and for option C the\n> app's **Connect ADB**) and press Allow **before** step 6. If it already happened, see \"If\n> something is stuck\" in [docs\u002FUNINSTALL.md](docs\u002FUNINSTALL.md).\n\n> **Only Wireless debugging?** Newer Google TVs (Android 11 and up) may offer only **Wireless\n> debugging**, which pairs with a code and uses a random port that changes after a restart.\n> couch-tv's scripts and the bridge speak plain ADB on a fixed port, so turn the fixed port on once\n> with Google's own tools ([Android platform-tools](https:\u002F\u002Fdeveloper.android.com\u002Ftools\u002Freleases\u002Fplatform-tools)):\n> 1. On the TV: Developer options, **Wireless debugging** on, then **Pair device with pairing\n>    code**. It shows a code and an address with a port, for example `\u003Ctv address>:37123`.\n> 2. On the computer: `adb pair \u003Ctv address>:\u003Cpairing port> \u003Ccode>`.\n> 3. Back on the Wireless debugging screen, note the port under \"IP address and port\", then\n>    `adb connect \u003Ctv address>:\u003Cthat port>`.\n> 4. `adb tcpip 5555`. Port 5555 is now open and `check-tv.py` should say ADB is open on port 5555.\n>\n> On some TVs port 5555 closes again after a restart. Then run steps 2 to 4 again (option B's\n> daily guard and the remote need it open). If your TV keeps a different fixed port open, set\n> `\"adb_port\"` on that TV in `config.json` (or `ADB_PORT=\u003Cport>` for the scripts). The Wireless\n> debugging port itself needs Google's `adb`; couch-tv cannot use it directly.\n\n> **Mac: \"allow devices on your local network\".** macOS asks once per program before it lets it\n> talk to devices at home. Say **Allow** for Terminal (or the app your AI agent runs in). A program\n> that is new to the Mac, like Google's `adb` straight after downloading it, can be blocked\n> silently: it then cannot reach the TV although everything else can. couch-tv's own tools\n> (`tv-home\u002Ftools\u002Ftvadb.py`, `on-tv\u002Fscripts\u002Freal-tv.py`, `check-tv.py`) are plain Python and run\n> inside the Python you have already allowed, so use them for everything except the one-off\n> Wireless debugging pairing above. If `adb` is blocked: System Settings, Privacy and Security,\n> Local Network, and switch on the app it runs in.\n\n### Step 2. Get the code and set up Python (every option)\n\n```sh\ngit clone https:\u002F\u002Fgithub.com\u002FSeagey\u002Fcouch-tv.git\ncd couch-tv\npython3 --version                    # 3.11 or newer\npython3 -m venv .venv\n.venv\u002Fbin\u002Fpip install -r bridge\u002Frequirements.txt\ncp config.example.json config.json\n```\n\nEdit `config.json` (it is private, it never gets committed):\n\n- `tvs`: put your TV's address in `ip`. Give it a name. Add more TVs by adding more entries.\n- `people`: the names that show on the \"who is watching\" switch, any number. None or one: no\n  switch. Two: a switch. Three or more: a round head icon that opens a list. Mark children with\n  `\"kid\": true` and visitors with `\"guest\": true` so they stay out of the household's picks.\n- `weather`: your latitude, longitude, place name and time zone (Open-Meteo, free, no key). A\n  suburb or city, never a home address.\n- `country`: two letter code, for where shows stream.\n- Option B: `bridge.host`, the name of the computer that runs the bridge, for example\n  `my-computer.local`.\n- Optional: `home` (scenes, how long each stays, 12 or 24 hour clock, how many apps in the dock,\n  apps to hide), `quick` per TV (sleep timer, picture mode, look and input buttons), `ask` and\n  `phone_remote`.\n\nEvery key, with its default: [docs\u002FCONFIG.md](docs\u002FCONFIG.md). Which TV remotes work and which\nkeys do what: [docs\u002FREMOTES.md](docs\u002FREMOTES.md). How the phone remote is hosted and how to add it to\nyour phone: [docs\u002FREMOTE.md](docs\u002FREMOTE.md).\n\nOptional settings (port, Claude location) go in `.env`. Copy `env.example` to `.env`.\n\n### Step 3. Pair the TV with the bridge (option B)\n\n```sh\n.venv\u002Fbin\u002Fpython bridge\u002Fpair_tv.py living-room\n```\n\nThe TV shows a 6 character code. Type it in and press Enter. That pairs the bridge as a remote (the\nTV lists it as \"Couch TV bridge\"). An AI agent cannot type into the waiting script: it runs that\ncommand in the background, asks you to read the code off the TV, then runs\n`.venv\u002Fbin\u002Fpython bridge\u002Fpair_tv.py living-room --code \u003Cthe code>`.\n\nThen:\n\n```sh\n.venv\u002Fbin\u002Fpython bridge\u002Fpair_tv.py living-room --adb\n```\n\nThe TV asks \"Allow USB debugging?\". Tick Always allow, then Allow. The keys it makes are stored on\nyour computer (`bridge\u002Fdata\u002F` and `~\u002F.android\u002Fadbkey`). They are in `.gitignore`.\n\n### Step 4. Build the phone remote (option B)\n\n```sh\ncd remote\nnpm ci\nnpm run build\ncd ..\n```\n\n### Step 5. Run the bridge (option B)\n\n```sh\n.venv\u002Fbin\u002Fpython bridge\u002Fserver.py\n```\n\nOpen `http:\u002F\u002Fyour-computer.local:5400` on your phone (same Wi-Fi). Add it to your home screen.\nTo keep the bridge running all the time, use `bridge\u002Fexamples\u002Fcouch-tv-bridge.plist.example`\n(macOS) or `bridge\u002Fexamples\u002Fcouch-tv-bridge.service.example` (Linux). Both set `CLAUDE_BIN` and a\n`PATH`, because a background service does not see your shell's.\n\n**Anyone on your Wi-Fi can use the remote and the assistant.** The bridge has no password, so\neveryone on the network, kids included, can change the channel, turn the TV off or ask Claude for\na show. Put visitors on a guest Wi-Fi network (most routers have one) so they cannot reach it. The\nbridge is for your home network only. Never put it on the internet or forward a port to it.\n\n`\"phone_remote\": false` is for a house that only wants the TV home and its quick settings from the\nbridge. The bridge still serves the API (the TV home needs it), and the phone page still loads if\nsomeone opens it, so the same rule applies.\n\n### Step 6. Put the TV home on the TV (options A and B; this replaces the Google home screen)\n\nGet `couch-tv-home.apk` from the GitHub Releases page (or build it, below). Look at the TV first\n(it changes nothing):\n\n```sh\nTV_IP=\u003Cyour tv address> .venv\u002Fbin\u002Fpython tv-home\u002Ftools\u002Fsurvey-tv.py\n```\n\nIt also reminds you that switching the setup wizard off makes some TVs forget their Wi-Fi. Nothing\ncan tell in advance which TVs, so plan for it on any TV: have the TV remote ready.\n\nThen install it. **Option A** (no computer stays on):\n\n```sh\nTV_IP=\u003Cyour tv address> APK=couch-tv-home.apk sh tv-home\u002Ftools\u002Fapply.sh\n```\n\n**Option B** (the home loads from the bridge):\n\n```sh\nTV_IP=\u003Cyour tv address> APK=couch-tv-home.apk BRIDGE_URL=http:\u002F\u002Fmy-computer.local:5400 sh tv-home\u002Ftools\u002Fapply.sh\n```\n\nThis installs the app, switches off the Google TV home (and ambient mode, the setup wizard and any\nad trackers you name in `EXTRA_OFF`), and makes the new home the TV's home. Other makers' own home\nscreens are left alone; the TV's default home is set to couch-tv instead. Nothing is deleted.\nIt also hands the app your `config.json` settings (people, weather, clock, look, quick buttons)\nfor its built-in copy. **Read the Undo section before you run it.**\n\nThe setup wizard goes off last, after everything else is done. If the TV then forgets its Wi-Fi,\n`apply.sh` says so: join the Wi-Fi again at the TV (Settings, Network and Internet) and run the\nsame command again. It is safe to run as often as you like.\n\n- `KEEP_SETUP=1` leaves the setup wizard on, so the Wi-Fi is never at risk. On some TVs the\n  wizard then keeps winning the Home button; if it does, the wizard has to go off.\n- **A Google TV update can switch the Google home back on.** With option B the bridge checks once\n  a day and switches it off again. With option A there is no bridge: run `apply.sh` again after an\n  update (and after you change `config.json`).\n\n### Building the app (instead of downloading it)\n\nYou need **JDK 21** and the **Android SDK** with platform 34 and build tools 34. Gradle is not\nneeded: `tv-home\u002Fandroid\u002Fgradlew` fetches Gradle 8.11.1 by itself.\n\n1. JDK 21. The simplest way, with no password needed: download the Temurin 21 JDK `.tar.gz`\n   for your computer from [adoptium.net](https:\u002F\u002Fadoptium.net\u002Ftemurin\u002Freleases\u002F?version=21), unpack\n   it into a folder you own (for example `couch-tv\u002Fbuild\u002Fjdk`, which git ignores) and point\n   `JAVA_HOME` at it (on macOS the `Contents\u002FHome` folder inside). Or install it system-wide:\n   macOS `brew install --cask temurin@21` (asks for your password), Linux\n   `sudo apt install openjdk-21-jdk`.\n2. The Android SDK command line tools: download \"Command line tools only\" from\n   [developer.android.com\u002Fstudio](https:\u002F\u002Fdeveloper.android.com\u002Fstudio), unzip into\n   `~\u002FLibrary\u002FAndroid\u002Fsdk\u002Fcmdline-tools\u002Flatest` (macOS) or `~\u002FAndroid\u002FSdk\u002Fcmdline-tools\u002Flatest`\n   (Linux).\n3. Then, with `ANDROID_HOME` set to that `sdk` folder:\n   ```sh\n   $ANDROID_HOME\u002Fcmdline-tools\u002Flatest\u002Fbin\u002Fsdkmanager \"platforms;android-34\" \"build-tools;34.0.0\"\n   $ANDROID_HOME\u002Fcmdline-tools\u002Flatest\u002Fbin\u002Fsdkmanager --licenses     # answer y to each licence\n   ```\n4. Build:\n   ```sh\n   JAVA_HOME=\u002Fpath\u002Fto\u002Fjdk-21 ANDROID_HOME=\u002Fpath\u002Fto\u002Fandroid-sdk sh scripts\u002Fbuild-apk.sh\n   ```\n   It prints where the APKs are (`dist\u002Fcouch-tv-home.apk`, plus `dist\u002Fcouch-tv-ontv.apk` for\n   option C). The on-TV app carries the phone remote inside it, so for that one the script builds\n   `remote\u002F` first, which needs **Node 20 or newer**. `apply.sh` finds `dist\u002Fcouch-tv-home.apk`\n   by itself.\n\nThe release APK is signed with your local debug key, which is fine for your own TV. The built-in\ncopy uses `config.example.json` unless you pass `CONFIG=config.json`; `apply.sh` hands the TV your\nown settings either way. Home settings, Updates offers the releases of `Seagey\u002Fcouch-tv`, which\nyour own build cannot take (another key): a fork with releases of its own builds with\n`UPDATE_REPO=owner\u002Fname sh scripts\u002Fbuild-apk.sh`, and `UPDATE_REPO=` (empty) switches updates off.\n\n## Undo: put the Google home screen back\n\nThe full guide, with the TV-remote-only way and what to do if something is stuck:\n[docs\u002FUNINSTALL.md](docs\u002FUNINSTALL.md). In short:\n\n1. **Option B: stop the bridge first**, or its daily guard switches the Google home off again\n   (macOS: `launchctl bootout gui\u002F$(id -u)\u002Fapp.couchtv.bridge`; Linux:\n   `systemctl --user disable --now couch-tv-bridge`).\n2. Everything off, including developer mode:\n   `TV_IP=\u003Cyour tv address> DEV_OFF=1 sh tv-home\u002Ftools\u002Fremove-all.sh`. If the computer cannot reach\n   the TV it says so, changes nothing and prints the TV-remote steps.\n\nOnly the home screen, keeping the app (10 seconds): `TV_IP=\u003Cyour tv address> sh tv-home\u002Ftools\u002Fundo.sh`.\nIt switches back on exactly what `apply.sh` switched off, and makes the home the TV had before the\nhome again. To remove the app as well, after that:\n`TV_IP=\u003Cyour tv address> .venv\u002Fbin\u002Fpython tv-home\u002Ftools\u002Ftvadb.py shell \"pm uninstall app.couchtv.launcher\"`.\n\nWith only the TV remote (no computer):\n\n1. On the couch-tv home, open the **Settings** tile (the gear at the end of the app row), or press\n   the Settings button on your remote.\n2. **Apps**, then **See all apps**, then **Show system apps**.\n3. Open **Google TV Home** (it says Disabled) and press **Enable**. Do the same for **Setup** (the\n   Google TV setup app). Ambient mode and the ad tracker are optional.\n4. Back in **Apps**, open **Home** (the new one) and press **Uninstall**.\n5. Press the Home button. Google TV is back.\n\nDo step 3 before step 4. If the new home is removed while Google TV Home is still off, the TV has\nno home screen. Apps still open from the remote's app buttons, and the computer undo above still\nworks.\n\nIf the TV ever loses its saved Wi-Fi after switching the setup wizard off, enable **Setup** again\n(step 3) and set the Wi-Fi from there.\n\n## How it fits together\n\n```\nphone remote (remote\u002F)  --->  bridge (bridge\u002F, always-on computer)  --->  the TV\nTV home (tv-home\u002F)      --->  bridge (for shows and picks)               (Android TV Remote\n                              TV home carries its own copy for when       protocol and ADB)\n                              there is no bridge\n```\n\n- API contract: [bridge\u002FAPI.md](bridge\u002FAPI.md).\n- How shows open in each streaming app: [bridge\u002FDEEPLINKS.md](bridge\u002FDEEPLINKS.md).\n- Watch history, taste and picks stay on your computer in `bridge\u002Fdata\u002F`. That folder is in\n  `.gitignore`. You can import your own Netflix and YouTube history: [bridge\u002FIMPORT.md](bridge\u002FIMPORT.md).\n\n## Privacy and safety\n\n- Your settings are in `config.json`, your secrets in `.env`, your data in `bridge\u002Fdata\u002F`. All\n  three are ignored by git.\n- Before you push a fork, run `scripts\u002Fprivacy-scan.sh`. It checks for private addresses, emails,\n  phone numbers, MAC addresses, home network names and secrets, in the files and the git history.\n  You can also give it a file of your own words to block: `scripts\u002Fprivacy-scan.sh my-denylist.txt`\n  (one word per line, keep that file out of the repo). `scripts\u002Finstall-hook.sh my-denylist.txt`\n  runs it before every commit.\n- Option B: anyone on your Wi-Fi can use the remote and the assistant (see step 5). The bridge only\n  listens on your home network. Do not forward a port to it.\n- Smart home (optional, off unless you add it): the Home Assistant token goes in `.env`, then\n  only into the TV app's private storage. The home page never sees it, and the app only touches the\n  rooms, scenes and doorbell you list. Make a separate Home Assistant user for the TV\n  ([docs\u002FCONFIG.md](docs\u002FCONFIG.md), Smart home).\n\n## Limits\n\n- Google TV and Android TV run everything. Fire TV (Fire OS) runs the on-TV app, with Amazon's\n  home flashing up first. Samsung runs it as an app, with a computer that stays on. Developer\n  mode has to be on.\n- A Google TV update can switch the Google home back on. Option B's bridge checks once a day and\n  switches it off again; with option A, run `apply.sh` again.\n- Some apps will not open a show directly. They open the app instead. See `bridge\u002FDEEPLINKS.md`.\n- The bridge's own messages (errors, notes) are in English in every language.\n- No support promise. It works on the TVs it was built on. Your TV may differ.\n\n## Credits\n\n- The five scene backgrounds (`scene-*.jpg`) were generated for this project and are free to use.\n  The Classic look's photos are Creative Commons from Wikimedia Commons. Both are listed in\n  `tv-home\u002Fweb\u002Fbackgrounds\u002FCREDITS.md`.\n- The streaming app logos in `remote\u002Fsrc\u002Fapp-logos\u002F` belong to their owners.\n- Fonts: Inter and Antonio (both SIL Open Font Licence).\n- Show data and posters: JustWatch (credit them if you publish anything built on this).\n- Weather: Open-Meteo.\n- The doorbell card and Home Assistant scenes on the TV started in the\n  [roliusz fork](https:\u002F\u002Fgithub.com\u002Froliusz\u002Fcouch-tv).\n\nMIT licence, see `LICENSE`.\n","2026-10-31 04:26:31","CREATED_QUERY"]