16 KiB
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:
.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; the workaround uses the documented AccessibilityService callbacks.
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 native shadow. Wallpaper/artwork crossfades last 320 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.
Optional Plex rows
Choose Settings → Plex media rows → Connect with Plex and enter the TV's short code at 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:
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
- Increase
versionCodeandversionNamein bothapp/src/main/AndroidManifest.xmlandapp/build.gradle. Every published update needs a greater version code. - Edit
docs/UPDATE_NOTES.md, then runscripts/build.shusing the existing signing keystore. The build generatesoutput/Luma.apkandoutput/update.jsontogether, including the APK checksum and size. - 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 and package installation API.
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).
- 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 artwork are retained during a short crossfade. A focus debounce avoids loading artwork for every passing selection.
- 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. 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. 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:
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
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.
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.
See docs/ASSETS.md for the wallpaper generation prompt and asset provenance. Android TV intent handling follows Android's TV app guidance; Plex integration follows the official Plex Media Server API documentation.