Gathin23/cleanyourtv

Every script has a PowerShell twin next to it. On Windows with Android Studio installed nothing else is needed:

python -m venv tools\venv; tools\venv\Scripts\python.exe -m pip install -r tools\requirements.txt
powershell -ExecutionPolicy Bypass -File launcher\build-and-install.ps1 -TvHost 192.168.1.50
powershell -ExecutionPolicy Bypass -File tools\disable.ps1 -TvHost 192.168.1.50 examples\xiaomi-mi-tv-4a\debloat.txt

The install scripts ask the TV which launcher owns Home and only disable one they recognise, the four in KNOWN_STOCK_LAUNCHERS: com.google.android.tvlauncher, com.google.android.apps.tv.launcherx, com.google.android.leanbacklauncher and Xiaomi's com.mitv.tvhome (PatchWall). Pass STOCK_LAUNCHER=<package> (-StockLauncher) to override, or none to leave it alone.

tools/disable.sh (disable.ps1) applies the same rule before it disables anything: if the list contains the app that owns Home and no other app on the TV answers HOME, it skips that entry, says why, and disables the rest of the list. The setup wizard, the settings apps, a vendor FallbackHome and factory-test apps (Xiaomi's com.duokan.factorytest) answer HOME too and don't count. So a list applied before the launcher handover cannot leave the TV with nothing to start. Run the same list again once launcher/build-and-install.sh has made the new launcher Home and the entry is applied; FORCE_HOME=1 ($env:FORCE_HOME) disables it anyway.

Debloat list paths passed to disable.sh and restore.sh are relative to the directory you run from, so your own lists can live outside the repository. Absolute paths also work.

It needs JDK 17 and Android SDK platform 34. On macOS: brew install openjdk@17 android-commandlinetools and sdkmanager "platforms;android-34" "build-tools;34.0.0". On Linux the install script finds ~/Android/Sdk and the java on your PATH.

config.xml sets the dock order, hidden apps, the Live TV package, columns (tiles shrink from 5 up), rows under the dock, an optional VPN app for the network pill, and reduced_motion for TVs whose GPU cannot keep up. Themes set the same keys plus a background colour and a wallpaper.

• Click Settings for the TV's own settings. Hold OK on it for its menu: Launcher settings (with launcher_settings_button a click opens those instead and the menu leaves the row out), Native settings where the TV ships a settings app of its own beside Android's - Xiaomi China, TCL/FFALCON and Fire OS are in settings_fallback_components - because that app holds pages Android's has no row for, such as Xiaomi's Account & Security with the ADB switch; Module cards with module_cards; Edit dock with dock_row; and Reorder apps. The launcher's own page has these rows, top to bottom:
  • Reorder apps, only with launcher_settings_button: OK picks an app up, the arrows move it, Back places it, and Back again finishes.
  • Apps per row 4, 5, 6 or 7; Rows below dock 0 to 3, how many rows of tiles stay visible under the dock band; Dock band opacity 100%, 70%, 50% or 30%. The last two only do anything while the dock is its own row (dock_row, on by default).
  • Wallpaper: one picture from the theme's collection (or its wallpaper.jpg), None, or Theme default. A pick holds that picture and stops the rotation until you choose Theme default, press Follow theme, or push the theme again.
  • Animations on or off, and Advanced effects (tile lift, icon zoom and smooth ambient-colour transitions; they may use more memory) once animations are on.
  • Open on start, only with open_on_start_choice: Off, or an app that opens instead of Home the first time Home comes up after the TV starts. Once per boot, so Home and Back still reach the launcher.
  • Follow theme (reset on-TV choices), which clears every choice above. Pushing or resetting a theme clears them too.
  • Choose default home opens Android's home picker, and TV system settings the TV's own settings page.
• Change the default home: Launcher settings and the optional Default-home tile (show_home_settings_shortcut) open Android's home picker. Choose the original launcher to stop using CleanYourTV as Home, or CleanYourTV to return. The original launcher must be enabled; if the install script disabled it, run the restore script below first. Some TVs provide no home picker.

English, German, Danish, Spanish, Catalan, French, Russian, Serbian (Latin), Polish, Czech, Italian, Portuguese, Turkish, Arabic, Hebrew, Simplified Chinese, Traditional Chinese (Taiwan), Thai, Finnish, Vietnamese, Bangla, Indonesian, Norwegian Bokmål, Dutch, Uzbek (Latin), Ukrainian and Korean. The launcher follows the TV's language. Android 13+ can set it for the launcher alone: tools/tv.py 'cmd locale set-app-locales com.gathin.tvhome --locales ca'.

Hebrew mirrors the layout: menu buttons on the left, date and clock on the right with the greeting above, dock and app rows starting on the right with matching remote navigation, the input selector's icons and labels on the right, and dates with the month prefix ב (for example, 19 באוקטובר). The Clock screensaver right-aligns its date and time. Russian covers every screen, including race weekends, festival greetings and the Shamsi date. Other languages keep their original layouts.

Any TV app can declare its own tile (label, caption, glow). The launcher asks you once per app, keeps it hidden by default, and remembers the answer for that app's signing key and card name. Hold OK on Settings and choose Module cards to change your mind. How to make one: docs/modules.md; the contract: docs/specs/card.md.

Pick "Clock" in the TV's screensaver settings, or over ADB:

tools/tv.py 'settings put secure screensaver_components com.gathin.tvhome/.ClockDream; settings put secure screensaver_enabled 1'

• An optional accessibility service keeps the remote's Input button working on Google TV (INPUT_KEY_SERVICE=1 at install).
• It can bring back other buttons only the stock launcher answered, such as the YouTube button (app_keys and input_key_keycodes, in config.xml or a theme; HOME_KEY_SERVICE=1 reads app_keys too).
• A hold: prefix on an app_keys entry gives that button a second app: a normal press opens the unprefixed app, holding for half a second opens the hold one (by keycode or hold:scan:...).
• In place of an app, an app_keys entry can name an action: back, home, recents, mute, sleep, screensaver, settings or wifi, so a spare colour button can mute the TV or, held, put it in standby.
• HOME_KEY_SERVICE=1 also fixes sticks whose Home key sends ALL_APPS, and opens Settings from the remote's gear button, even one Android does not map (scancodes or keycodes in config.xml).
• With settings_key_panel the gear opens a small quick settings panel over Home or any app: TV settings, Display, Network, Apps and Launcher settings.

Up and Down move one row. The top buttons never fall through to tiles, and Down from them returns to the dock tile you came from. The last focused app is remembered, and installing or removing an app refreshes the tiles while Home is open. App banners load at xhdpi or better, so low-density TV UIs do not downsample them before the focus zoom.

Before tools/disable.sh changes anything it writes down what the TV looked like: for every package in the list whether it was enabled, already disabled or not installed, which component owned Home, and the three animation scales. That record lives in ~/.cleanyourtv/, one file per TV and list, and a second run of the same list keeps the first record instead of saving the cleaned-up state over it. If you added packages to the list since, that run adds them to the record before disabling them.

Keep the list you applied. The restore script replays the record, so a package you had disabled yourself stays disabled and Home goes back to the component that owned it:

The stock launcher argument is only a fallback: with a record, the launcher that actually owned Home is the one that gets it back, and the argument is used only when nothing answered HOME at the time or this project's launcher owned it. The stock launcher is enabled again either way, unless it was already disabled when the record was taken. Without a record (an older run, or a record you deleted) the script says so and falls back to enabling the whole list and resetting the scales to 1.0, which is what it used to do.

It leaves the new launcher installed (remove it from the TV's Settings → Apps if you want it gone) and does not know about packages you disabled outside the list. To switch back later, run the install script again; it works out which launcher to disable even when Home has fallen back to Android's chooser. If the TV is unreachable, its own Settings → Apps page can re-enable packages too.

Yes. @udhaykumarbala built a free, open-source phone app for Android that does the same cleanup over Wi-Fi: it connects to the TV, shows a plan first, saves a restore point, and only switches apps off, so everything can be put back. It's community-built.

Nothing is flashed, rooted or deleted; packages are disabled in the user profile. The risk is disabling something the TV leans on, which is why lists are applied in small batches with a restore script ready. The TV's own Settings → Apps page can re-enable packages even without the tools.

If the TV no longer starts far enough for that, or for ADB, a factory reset from its recovery menu is usually the way back (#1578): everything these tools change lives in the user data the reset wipes, so every disabled app comes back and the new launcher is gone, along with your own apps and accounts. A TV that still restarts in a loop after the reset points to the hardware rather than the debloat (#1592); Troubleshooting has the cases seen so far.

The updater is left on in most lists, so firmware updates arrive as usual. Some lists disable the TV's own updater, and on those a firmware update arrives only when you re-enable it. When one does land it installs over the cleaned-up system, so a package comes back and you re-run the script: see After a firmware update.

Streaming apps still update through the Play Store, which is left alone. The launcher just lists what is installed and launches it with intents that have been stable for a decade.

Yes, over a private Tailscale link instead of the same Wi-Fi: either Tailscale on their TV, shared with you, or a computer or Apple TV at their home routing to it. Never by opening the ADB port on their router. Step by step in docs/REMOTE.md.

It is one explicit "allow this computer" tap on the TV, the same as developing an Android app. Network ADB is plaintext on port 5555, and on firmware with ro.adb.secure=0 any device on the LAN gets a shell, so close it when you are done:

1. On the TV: Developer options → turn USB debugging, Network/ADB debugging and Wireless debugging off, whichever the TV has, and revoke the USB debugging authorisations. Wireless debugging listens on a port of its own and stays open when USB debugging goes off (seen on a Chromecast with Google TV 4K). Note that port before you switch it off (adb mdns services lists it as _adb-tls-connect._tcp) and check it straight after, before the reboot: python3 tools/adb-closed.py <tv ip> <port> must say that port is closed. After the reboot the old number reads closed either way: Wireless debugging takes a new port each time it starts.
2. Reboot the TV, then confirm the port is gone from your computer: python3 tools/adb-closed.py <tv ip> must say the port is closed. Wireless debugging must still be off in Developer options, and adb mdns services must list no _adb-tls-connect._tcp entry for the TV; if it came back, switch it off and check its new port as in step 1. With nc -vz <tv ip> 5555, only "Connection refused" counts: on macOS, Local Network privacy can block nc and make it fail with "No route to host" even while the port is open.

The launcher keeps working without debugging.

Partly, with Android's Private DNS (Android 9 and newer). Point it at an ad-blocking resolver such as AdGuard DNS and every app's ad and tracker domains stop resolving, system-wide, surviving reboots. The trade-off: that resolver then sees every DNS query the TV makes.

tools/tv.py 'settings put global private_dns_specifier dns.adguard-dns.com'
tools/tv.py 'settings put global private_dns_mode hostname'

It does not remove YouTube ads, which come from the same servers as the videos. When the TV reports "No internet", the resolver is down or unreachable and switching back restores everything: tools/tv.py 'settings put global private_dns_mode opportunistic'. That line needs debugging back on, because Android TV's Settings app has no Private DNS page (not in AOSP, and not in Google TV 14 on a Chromecast with Google TV 4K); ADB goes to the TV's address, so it connects while the resolver is down. A resolver that answers can still break one app on its own, so if a single app fails while the rest play, see one app refuses to play before you debug the app.

A few. They need no ADB, the remote switches them back, and the debloat leaves them in place (Usage & diagnostics and Apps only mode aside): their pages belong to Settings and Play services, which every list keeps. The paths are Google TV's; other Android TV builds move some of them.

• Settings → Privacy → Ads: delete the advertising ID, or turn on Opt out of Ads Personalization. On Android TV it is under About → Legal information → Ads (in Device Preferences on some sets).
• Settings → Privacy → Location off. The launcher's network pill may then say "Wi-Fi" instead of the network's name.
• Settings → Privacy → Usage & diagnostics off, before the debloat. On a Chromecast with Google TV 4K the page comes from setupwraith, which most Google TV lists disable for the launcher swap, and on a Hisense 50A6H4 it opened nothing after the debloat.
• Settings → Network & Internet → Scanning always available off. It lets Google's location service and other apps scan for Wi-Fi networks even while Wi-Fi is off, so it matters most on a TV on Ethernet.
• Settings → Accounts & Sign In → your profile → Apps only mode, where launcherx stays enabled (stock_home_redirect, or the Chromecast's debloat-keep-cast.txt). Google TV's own home then drops its personalised recommendations and casting still works, but Search and the Assistant switch off. The switch lives in launcherx, so a list that disables launcherx takes it away.

On Fire OS: Settings → Preferences → Privacy Settings, with Interest-based Ads, Device Usage Data and Collect App Usage Data off. They sync with the Amazon account, so change them in the menu, not with settings put.

Not from this repo. Chromecast built-in stays for Android phones. For iPhones, jqssun/android-airplay-server works; an install script for it is in PR #84.

Build it with the one-line script; it takes a minute and you control what goes on your TV. No prebuilt binaries.