Luma/README.md
2026-10-17 22:38:45 -07:00

11 KiB
Raw Blame History

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.

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.

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 receivers, alarms, PowerManager wake locks, or periodic background jobs. 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.

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.