# Luma for Android TV A native, remote-first launcher built for the onn. 4K Plus Streaming device (Android 14, 2 GB RAM). It is installed alongside Projectivy as `tv.luma.launcher`. Home now opens Luma; Projectivy remains installed and enabled as a fallback. Version **1.1.5** adds updates directly from the TV and includes the wake fix introduced in 1.0.1. Every resume restores missing images, including when Android briefly pauses the launcher without stopping it. Already-loaded tiles and images are kept on pause-only resumes; leaving the launcher still releases image memory. ## Use it Press **Home**, or open **Luma** from Projectivy's app list. It can also be opened with: ```sh .tools/platform-tools/adb -s 192.168.50.195:35635 shell am start -n tv.luma.launcher/.MainActivity ``` - D-pad navigates the installed app grid; OK opens an app. - Hold OK on an app to move it, move it to the front, hide it, or open Android app info. - In move mode, arrows move the app; OK saves and Back restores the previous order. - Menu or the gear opens Luma settings. **All apps** includes hidden apps so they can be restored. - Back scrolls to the first row and stays on Luma. Home returns to Luma. ## Default launcher and Home routing **Settings → Default launcher** provides Android's Home app chooser, a Home button override toggle, and a direct Projectivy fallback. Enabling the override opens Android Accessibility settings; enable **Luma Home button** there. Turning it off in Luma disables only Luma's accessibility service. On this onn. device, Android records Luma as the Home role holder but still resolves Home to Google's launcher. Luma's accessibility workaround redirects that stock Home window and handles Home key events where Android delivers them. It runs in a separate small `:home` process so the launcher UI and its artwork can still be reclaimed while another app runs. It requests window-state events only from Google Home and Projectivy, without permission to retrieve window content. It has no polling loop or network work. Projectivy's **Settings → General → Override current launcher** is switched off to avoid competing Home handlers. Projectivy's application and accessibility service, and Button Mapper's accessibility service, remain enabled. The Projectivy app tile and **Open Projectivy** deliberately allow the fallback to remain open until the next Home press. Back stays on Luma. To return to the previous routing, turn off Luma's Home override, then open Projectivy and re-enable **Override current launcher**. No launcher needs to be disabled or uninstalled. The native chooser uses Android's [Home role API](https://developer.android.com/reference/android/app/role/RoleManager); the workaround uses the documented [AccessibilityService callbacks](https://developer.android.com/reference/android/accessibilityservice/AccessibilityService). ## Appearance **Settings → Appearance → Banner** offers: | Mode | Behavior | | --- | --- | | Artwork only (default) | Original spacious composition, cinematic wallpaper, no headline or supporting text; one full app row and a partial second row at the top | | Dynamic | Same spacious layout, with selected-app headlines and descriptions; connected Plex media can provide artwork | | Minimal | Removes the featured area's reserved space and moves the app grid higher | **App labels** offers Always, Focused only (default), and Never. Accessibility app names remain available in all modes. Other settings include 5/6/7 columns, background dimming, automatic or fixed accent colors, reduced motion, clock visibility, and 90-second scene rotation. Alpine uses the bundled original wallpaper; Aurora and Midnight are inexpensive procedural gradients. Focus uses a 6.5% scale increase, a 160 ms transition, and an app-colored cached soft shadow. Background crossfades last 280 ms. The launcher has no continuously rendered blur or background video. Optional screensaver video runs only while the screensaver is visible. The app grid uses one 260 ms scroll animation for remote focus movement. **App section text** can hide the heading, installed count, and customization hint; it is hidden by default without changing the original spacing. ## Screensaver Open **Settings → Screensaver**. The home-screen idle timer defaults to **10 minutes** and offers Off, 1, 3, 5, 10, 15, 30, and 60 minutes. Any remote button or touch wakes it without launching the selected app. It is stopped when Luma leaves the foreground, so it does not interrupt other applications. - **Scenic:** bundled NASA Earth/space photos and Luma's original alpine scene; fully offline. - **Art gallery:** bundled public-domain works by Van Gogh, Hokusai, and Jacques Louis David, with an optional download of a larger curated Met collection. - **Nature video:** a locally saved video, a user-selected file through Android's document picker, or a direct MP4/HLS URL. A built-in action downloads an 85-second NPS bird clip at 720p (about 40 MB) and loops it locally. Muted by default; muted playback does not claim audio focus. Customize photo duration (15–300 seconds), shuffle, captions, clock, framing, dimming, and video audio. Auto framing preserves complete paintings against **pure black** mattes and fills the screen for scenic photos. Fit and Fill are explicit alternatives. A caption gradient and shadows preserve contrast over bright art. The next image is decoded before an 800 ms Canvas crossfade; at most two sampled images are in use. Invalid images are skipped without clearing the displayed artwork. Video downloads are capped at 250 MB, stored privately on the TV, and can be removed from the same panel. Downloads run only while requested and are canceled when leaving the download panel or Luma. HLS streams can play directly but cannot be saved as one offline MP4. Webpage/YouTube links are not direct video sources. If a video cannot play, the screensaver falls back to scenic photos. When Luma's idle timer is enabled, its window stays awake so Android's own idle timeout cannot preempt the selected timeout. Leaving Luma releases this flag; the power button still works. Off defers to Android's own power/screen behavior. A permission-protected Android DreamService is registered for devices that allow selecting third-party system screensavers. This onn. TV does not expose the standard Dream settings activity, and its system screensaver selection has not been changed. Media provenance and source links are in [docs/ASSETS.md](docs/ASSETS.md). ## Optional Plex rows Choose **Settings → Plex media rows → Connect with Plex** and enter the TV's short code at [plex.tv/link](https://plex.tv/link). Select a server available to your account. Alternatively, enter your server URL and Plex token manually. HTTPS is required for remote addresses; HTTP is supported for local network servers. The integration reads Continue Watching and Recently Added from your server, with at most 12 items per row. Selecting Plex/Plezy can show the first Continue Watching item's artwork; focusing a media tile shows its artwork. Selecting media opens the official Plex Android app's title link. Plex controls playback. The connection is separate from Plex's own login and does not inspect another app's private data. Tokens are encrypted with AES-GCM using a key held in Android Keystore. **Disconnect Plex** removes the saved server and encrypted credential. API requests send credentials in headers, not URLs or logs. Android backup is disabled for this app. There are no analytics or advertising endpoints. Media rendering and the connection/disconnection flow were checked against a temporary local Plex fixture. A real Plex server and account have not been connected, so account authorization and actual title playback remain to be verified with your library. Pairing is user initiated; no background account polling occurs. ## Updates on every TV Open **Settings → Updates**. Checks default to **Daily**; alternatives are every 3, 6, or 12 hours, or Off. **Check now** works independently of the schedule. A check also runs when returning home if one is due. Android schedules one small, persisted, network-constrained job and may defer it while the TV is sleeping or offline. There is no continuous polling service and no automatic APK download. When a newer version is found, Luma posts a TV notification once for that version and shows an **Update** button beside the clock. Notifications can be managed in the same panel. Neither the check nor the notification opens another screen while watching an app. Select **Download & install** to download the APK. The first time, Android asks you to allow installations from Luma; Android's package installer then asks you to confirm the update with the remote. Settings and app data are retained. This uses the system installer, not silent or root installation. The default public HTTPS feed is: ```text https://git.elijahkuntz.com/Elijah/Luma/raw/branch/main/output/update.json ``` No SSH key or Forgejo account token is stored on the TV. For branch-based Forgejo URLs, Luma resolves the branch to a commit first, then reads both the manifest and APK from that immutable commit. It bounds metadata to 64 KiB and APK downloads to 32 MiB. Before opening the installer, it checks the expected SHA-256 and file size, package name, increasing version code, Android compatibility, and the installed signing certificate. A different signing key is rejected. The verified self-update is copied into a private Android PackageInstaller session with user confirmation required. Interrupted downloads are removed; completed APKs are removed after the updated app starts. ### Publish an update 1. Increase `versionCode` and `versionName` in both `app/src/main/AndroidManifest.xml` and `app/build.gradle`. Every published update needs a greater version code. 2. Edit `docs/UPDATE_NOTES.md`, then run `scripts/build.sh` using the existing signing keystore. The build generates `output/Luma.apk` and `output/update.json` together, including the APK checksum and size. 3. Commit and push the source changes, **both output files**, and release notes to `main`. The next scheduled/manual check on each TV discovers the update. No separate release upload or account setup is needed. Preserve `.tools/luma-development.keystore` separately from Git: the same signing key is required for every update. The first updater-capable APK must be installed on each TV once, through ADB, Downloader, or a file manager; later updates can be handled within Luma. Android scheduling and installation behavior follow the [JobInfo API](https://developer.android.com/reference/android/app/job/JobInfo.Builder) and [package installation API](https://developer.android.com/reference/android/content/pm/PackageManager#canRequestPackageInstalls()). ## Performance design - Platform Java/Android views and Canvas; no WebView, Compose runtime, playback engine, or third-party runtime dependencies. - Single sampled RGB565 wallpaper (960 × 540 for the bundled 1920 × 1080 image). Cinematic gradients, dimming, and artwork are composed off the UI thread into an opaque texture capped at 960 × 540; navigation crossfades the finished textures instead of re-running several full-screen shaders every frame. - App artwork is rasterized to 288 × 162. Icon cache is capped at 3 MiB; visible tiles also hold their displayed images. - Plex image cache is capped at 3 MiB. Hero images are sampled to at most roughly 1280 × 720; rows and network response sizes are bounded. - At most the current and previous composed backgrounds are displayed during a short crossfade. The compositor has one worker and one pending request; obsolete results are discarded. Its worker times out after two idle seconds. A focus debounce avoids loading Plex artwork for every passing selection. Only the focused tile draws an app-colored soft shadow. All tiles share a single 192 × 122 texture (about 92 KiB); no live elevation-shadow geometry is animated. - No boot receiver, alarms, or PowerManager wake locks. Update checks use one brief JobScheduler job, normally daily. The optional Home override is an event-driven accessibility service in a separate process; turning it off removes that bound service. The optional DreamService runs only when Android explicitly binds it as a system screensaver. - Clock updates once per minute; optional scene rotation runs only while Luma is visible. - On pause, networking and scene animations are canceled. On stop, queued work, image references, and caches are cleared. Worker threads time out after ten idle seconds. - Android can reclaim the cached launcher process while another app is running. It is not kept alive artificially. Measurements are in [docs/VALIDATION.md](docs/VALIDATION.md). PSS includes Android framework and graphics overhead and varies with device state; the APK's size does not represent RAM consumption. ## Build and install The signed APK is [output/Luma.apk](output/Luma.apk). Source is in `app/src/main/java/tv/luma/launcher`. The current workspace already contains a local JDK 17 and Android SDK under `.tools`. Rebuild without Gradle: ```sh bash scripts/build.sh .tools/platform-tools/adb -s 192.168.50.195:35635 install -r output/Luma.apk ``` For a fresh macOS checkout, run `scripts/bootstrap.sh`, review/accept the SDK licenses, then build. Alternatively use the included Gradle project with JDK 17, Gradle 8.7 and Android SDK 34. No third-party app dependencies are needed. The local build creates and reuses `.tools/luma-development.keystore`. Preserve that file to install future updates over the existing APK. It is ignored by source control. This is a development signing identity for your sideloaded build; configure your own signing identity before distributing it. To remove only Luma, run `adb uninstall tv.luma.launcher`; Projectivy remains installed. No command in the build/install scripts disables another launcher or changes the default Home app. ## Device checks ```sh python3 scripts/device_smoke.py --part navigation python3 scripts/device_smoke.py --part home-routing python3 scripts/device_smoke.py --part customization python3 scripts/device_smoke.py --part appearance-modes python3 scripts/device_smoke.py --part performance python3 scripts/device_smoke.py --part screensaver python3 scripts/device_smoke.py --part screensaver-video python3 scripts/device_smoke.py --part screensaver-timeout ``` The scripts operate the TV through ADB. Run one at a time with the TV awake. The customization checks expect the documented defaults. The Plex fixture requires `python3 scripts/plex_fixture.py` running on the host, followed by `python3 scripts/device_smoke.py --part plex`. It uses temporary ADB reverse forwarding to a loopback server and disconnects the fixture when finished. The wake regression uses a separate test APK signed with the same development key, without adding any test interface to Luma. It replays interrupted background loading, a pause/resume without another start callback, memory trimming, and five stop/start cycles. The old 1.0.0 build fails the interrupted-wake case; 1.0.1 passes. The current test also verifies nonblank composed backgrounds, their resolution limit, and cache release on stop. ```sh bash scripts/build-wake-tests.sh .tools/platform-tools/adb -s 192.168.50.195:35635 install -r output/Luma-wake-tests.apk .tools/platform-tools/adb -s 192.168.50.195:35635 shell am instrument -w -r tv.luma.launcher.tests/.WakeRegressionInstrumentation .tools/platform-tools/adb -s 192.168.50.195:35635 uninstall tv.luma.launcher.tests ``` Successful output ends with `INSTRUMENTATION_CODE: -1` and PASS lines for all cases. The runner controls activity lifecycle callbacks and should be run with no other device tests in progress. Android force-stops the target package during instrumentation and can mark its accessibility helper as stopped/crashed. After testing, check **Settings → Default launcher** and toggle **Luma Home button** off/on in Android Accessibility if needed, then reopen Luma. This is test-runner cleanup, not an action needed during normal TV wake. The same test APK also includes `tv.luma.launcher.tests/.PerformanceInstrumentation` for the background/shadow A/B benchmark. It changes only runtime view state and writes a temporary `performance.txt` in Luma's external-files directory. Reopen Luma afterward and remove the diagnostic APK. See [docs/ASSETS.md](docs/ASSETS.md) for the wallpaper generation prompt and asset provenance. Android TV intent handling follows [Android's TV app guidance](https://developer.android.com/training/tv/get-started/create); Plex integration follows the [official Plex Media Server API documentation](https://developer.plex.tv/pms/).