Android TV - test apk

[rayearth2162-ship-it]

Enhancement

Hi there. I've previously used smugmug and one of the most used features is the smugmug app on Android TV. Having migrated to Lychee I was sad not to have any way of displaying my Lychee photos on TV.

I have used Gemini to create an android TV apk which seems to work ok (I'm not a coder at all!). It has been built on macosx and pushed to my Nvidia Shield Pro. So no guarantee it will work with other combinations.

I have attached here the code created by AI, in case it is helpful for anyone else.

Here are the source files. Can be built using
./build-apk.sh

The apk will be in android/app/build/outputs/apk/debug/app-debug.apk, which can then be sideloaded on to android TV.

lychee-tv-addon-github.zip

See some screenshots of the test app

[ildyria]

Looks good !

Do you have a github repository with the code though ? :)

[rayearth2162-ship-it]

The code is in the zip file. I'm not a programmer so I don't think it is appropriate for me to upload it to github as I didn't programme it. More than happy for anyone to pick it up from here.

Here's AI's overview:

1. PROJECT OVERVIEW

---

This project is an Android TV Leanback client application for self-hosted Lychee
photo servers (compatible with Lychee v5, v6, and v7).

• Frontend Stack: React 19, TypeScript, Tailwind CSS v4, Lucide React icons.
• Native Android Container: Capacitor 7 (@capacitor/core, @capacitor/android, @capacitor/cli).
• Target Hardware: Nvidia Shield TV, Chromecast with Google TV, Sony Bravia,
  Xiaomi Mi Box, Amazon Fire TV, and any Leanback/Android TV device.
• Primary Input Model: 5-way D-Pad remote control (Up / Down / Left / Right / OK Center
  plus Back key), with full desktop keyboard and mouse fallback.

2. ARCHITECTURE DIAGRAM

---

                  +------------------------------------------+
                  |             Android TV Device            |
                  |  (Nvidia Shield / Leanback Remote D-Pad) |
                  +--------------------+---------------------+
                                       |
                                       v

+-------------------------------------------------------------------------------+
| React 19 Single Page App (Running inside Capacitor Web View) |
| |
| src/App.tsx (Global State Manager, Screen Router & Remote Key Router) |
| | |
| +---> src/components/LoginScreen.tsx (Server connection & input blur) |
| +---> src/components/CachedThumbnail.tsx (Recycled off-screen images) |
| +---> src/components/PhotoDetail.tsx (EXIF metadata, video player/seek)|
| +---> src/components/SlideshowView.tsx (Ken Burns zoom, black bars lock) |
| | |
| src/utils/thumbnailCache.ts (IndexedDB persistent disk + in-memory LRU) |
| |
| src/api.ts (Universal Network Layer) |
| |-- Native Mode (Android TV): CapacitorHttp (Java stack, bypasses CORS) |
| -- Web Mode (Browser dev): fetch / Vite proxy |
+------------------------------------------+------------------------------------+
|
v
+------------------------------------------+
| Self-Hosted Lychee API |
| (v5 / v6 / v7 Endpoints) |
+------------------------------------------+

3. FILE DIRECTORY & FUNCTIONS

---

ROOT LEVEL CONFIGURATION & SCRIPTS:

• build-apk.sh
  Automated build script. Compiles web bundle (npm run build), syncs assets
  to Android container (npx cap sync), writes Android TV Leanback manifest
  declarations, configures banner drawables, applies Java 17 compile
  compatibility patches across Gradle subprojects, and assembles the debug APK.

• capacitor.config.json
  Capacitor native project configuration:

  • appId: "org.lycheeorg.lycheetv"
  • appName: "Lychee TV"
  • server.cleartext: true (allows connecting to local HTTP servers)
  • plugins.CapacitorHttp.enabled: true (enables native HTTP requests)

• setup-android-banner.sh
  Copies 16:9 banner icon (banner.png) to Android res/drawable, drawable-xhdpi,
  and drawable-xxhdpi directories for Leanback launcher support.

• vite.config.ts
  Vite bundler configuration with React and Tailwind CSS v4 plugins, plus local
  proxy settings for development.

• package.json
  NPM dependencies and build commands:

  • Dependencies: React 19, @capacitor/core, @capacitor/android, Tailwind CSS, lucide-react.
  • Scripts: "dev", "build", "lint".

• index.html
  HTML entry point with viewport scaling and OpenGraph / favicon definitions.

• metadata.json
  Project descriptor and capabilities definitions.

SOURCE CODE (src/):

• src/main.tsx
  Application bootstrap and React DOM root rendering.

• src/index.css
  Global styles, font smoothing, custom scrollbars, and Ken Burns keyframe
  animation definitions (kenBurnsZoom10, kenBurnsZoom30, kenBurnsZoom60).

• src/types.ts
  Core TypeScript contracts:

  • LycheePhoto: ID, title, description, URLs, EXIF metadata (camera, lens, ISO, shutter, aperture, dates), is_video flag, formatted duration string.
  • LycheeAlbum: ID, title, description, cover_url, photos_count, sub_albums_count, sub_albums array, photos array.
  • ServerConfig: url, username, password, apiKey, isDemo.

• src/App.tsx (Main Application Controller)

  • Viewport routing: 'albums', 'album_detail', 'photo_detail', 'slideshow', 'login'.
  • D-Pad Remote Router: Handles Android TV remote keycodes (19/Up, 20/Down, 21/Left, 22/Right, 23/OK, 4/Back).
  • Focus Matrix: Manages 2D grid coordinates (albumGridFocus, photoGridFocus) and top bar button states.
  • Buffer Scrolling (scrollWithBuffer): Maintains a 40px margin above and below focused items to prevent remote navigation from clipping against TV edges.
  • Independent Album Sorting: Saves sorting preferences (Date asc, Date desc, A to Z, Z to A) individually per album ID in localStorage with no cascading/inheritance.
  • Predictive Buffer Prefetching: Pre-fetches the next 15-20 upcoming thumbnails ahead of cursor movement.

• src/api.ts (Universal Networking Engine)

  • universalRequest(): Detects Capacitor.isNativePlatform(). Uses CapacitorHttp on Android TV (native Java stack, bypasses browser CORS restrictions). Uses standard fetch in browser.
  • getHeaders(): Injects Authorization: Bearer when token is present, adds X-XSRF-TOKEN when cookies exist, and sets Accept/Content-Type to application/json.
  • login(): Authenticates via token validation against /api/v2/Albums or session login via /api/v2/Auth::login.
  • fetchAlbums(): Fetches root albums from /api/v2/Albums and extracts covers from ThumbAlbumResource.
  • fetchAlbumContent(): Fetches subalbums (/api/v2/Album::albums) and photos (/api/v2/Album::photos) with multi-page pagination (up to 5,000 photos per album).

• src/utils/thumbnailCache.ts (Dual-Tier Caching System)

  • In-memory LRU Map holding up to 2,000 blob object URLs for instant rendering.
  • IndexedDB disk storage ('LycheeThumbCacheDB', store: 'thumbnails') for persistent offline/disk caching.
  • Video duration parser and duration cache.

• src/mockData.ts
  High-resolution archival fallback dataset (DEMO_ALBUMS) with EXIF metadata for Offline Demo Mode.

COMPONENTS (src/components/):

• src/components/SlideshowView.tsx

  • Full Photo Display (Constant Black Bars): Calculates aspect ratio against screen dimensions to fit the full photo with black pillarbox/letterbox bars.
  • Contained Ken Burns Zoom: Subtle zoom motion runs inside a fixed bounding canvas (overflow: hidden). Black bars stay completely constant and never shift.
  • Timers: 10s, 30s, and 60s intervals with synchronized zoom speeds (3% for 10s, 6% for 30s, 10% for 60s) and an on-screen zoom toggle.

• src/components/PhotoDetail.tsx

  • Fullscreen high-resolution photo viewer and native HTML5 video player.
  • D-Pad seek controls (skips 10% backward/forward on Left/Right buttons).
  • Collapsible EXIF metadata panel (camera, lens, ISO, shutter, aperture, timestamp).

• src/components/CachedThumbnail.tsx

  • Thumbnail element backed by thumbnailCache.ts.
  • Displays VideoDurationBadge for video assets.

• src/components/LoginScreen.tsx

  • Settings modal for URL, API Token, Username, and Password.
  • Soft Keyboard Manager: Explicitly blurs all text inputs when navigating to action buttons to dismiss on-screen keyboard on Android TV.
  • Instant "Offline Demo Mode" button.

• src/components/ApkInstructionsModal.tsx

  • Helpful in-app modal detailing ADB sideloading and build commands.

4. KEY DESIGN PATTERNS & ENGINEERING DETAILS

---

A. REMOTE NAVIGATION MATRIX:
Focus is maintained in App.tsx via coordinate states:

• albumGridFocus: { col: number, row: number } (4 columns)
• photoGridFocus: { col: number, row: number } (5 columns)
• topBarFocus: 'albums' | 'sort' | 'slideshow' | 'settings' | null

When on row 0 of a grid, pressing ArrowUp moves focus into topBarFocus.
Pressing ArrowDown from topBarFocus returns focus to row 0.

B. ANDROID TV CORS BYPASS:
Android TV WebViews enforce strict CORS on cross-origin fetch() calls from
https://localhost to third-party domains. Because Lychee servers typically do
not send permissive CORS headers for arbitrary Android origins, native requests
are routed through CapacitorHttp, which uses Android's HttpURLConnection
in Java, completely bypassing WebView CORS.

C. SLIDESHOW BOUNDING BOX GEOMETRY:
Instead of zooming the outer container (which would shrink the black pillarboxes
and cause jarring layout shifts between photos of different aspect ratios),
SlideshowPhotoSlide measures the natural image dimensions and sets a fixed
pixel width/height canvas matching the exact photo bounds. The image inside
is then scaled with CSS transform: scale() while the outer canvas has
overflow: hidden. The black bars remain 100% constant throughout the transition.

D. JAVA 17 COMPATIBILITY:
Capacitor 7 defaults to Java 21, but many developer systems run JDK 17.
build-apk.sh automatically patches capacitor.build.gradle and root build.gradle
to set sourceCompatibility and targetCompatibility to JavaVersion.VERSION_17,
ensuring builds succeed across both JDK 17 and JDK 21 environments.

5. QUICK START & BUILD COMMANDS

---

Web Development Preview:
npm install
npm run dev

Android TV APK Build:
chmod +x ./build-apk.sh
./build-apk.sh

Output APK Location:
android/app/build/outputs/apk/debug/app-debug.apk

Sideloading to Android TV / Nvidia Shield via ADB:
adb connect <ANDROID_TV_IP>:5555
adb install -r android/app/build/outputs/apk/debug/app-debug.apk

[ildyria]

I will investigate it and see if I can make a proper repo for it under LycheeOrg then :)