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 (tvlauncher or launcherx); 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 and choose Launcher settings to set 4, 5, 6 or 7 apps per row, turn animations on or off, and opt into advanced effects (tile lift, icon zoom and smooth ambient-colour transitions; they may use more memory).
• Follow theme clears the on-TV choices. Pushing or resetting a theme clears them too.
• 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, 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 and Uzbek (Latin). 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:...).
• 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.

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.

Most lists disable the update service, so updates arrive only when you re-enable it. If one lands, the worst case is a package coming back and you re-run the script.

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 and Network/ADB debugging off, and revoke the USB debugging authorisations.
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. 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. If an app stops playing or the TV reports "No internet" (the resolver is down or unreachable), switch back with tools/tv.py 'settings put global private_dns_mode opportunistic'.

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.