No description
Find a file
Elijah 4ac18c8a45
All checks were successful
Validate and publish Kaleido / android (push) Successful in 2m15s
Release 0.1.4 with smoother browsing and Library tab focus
Section switches pause about half as long, the first move from the
Home hero to the rows no longer freezes, Movies/TV row moves no longer
skip frames, and Right from the Library tab reaches the sort controls.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-24 13:14:32 -07:00
.forgejo/workflows Initial Beta build 2026-10-24 09:09:55 -07:00
app Smooth section switches and first row moves on weaker TVs 2026-10-24 13:11:45 -07:00
distribution Release 0.1.4 with smoother browsing and Library tab focus 2026-10-24 13:14:32 -07:00
docs Smooth section switches and first row moves on weaker TVs 2026-10-24 13:11:45 -07:00
gradle/wrapper Initial Beta build 2026-10-24 09:09:55 -07:00
scripts Smooth section switches and first row moves on weaker TVs 2026-10-24 13:11:45 -07:00
.gitignore Initial Beta build 2026-10-24 09:09:55 -07:00
AGENTS.md Smooth section switches and first row moves on weaker TVs 2026-10-24 13:11:45 -07:00
build.gradle.kts Initial Beta build 2026-10-24 09:09:55 -07:00
Build.ps1 Initial Beta build 2026-10-24 09:09:55 -07:00
CHANGELOG.md Release 0.1.4 with smoother browsing and Library tab focus 2026-10-24 13:14:32 -07:00
gradle.properties Initial Beta build 2026-10-24 09:09:55 -07:00
gradlew Initial Beta build 2026-10-24 09:09:55 -07:00
gradlew.bat Initial Beta build 2026-10-24 09:09:55 -07:00
README.md Initial Beta build 2026-10-24 09:09:55 -07:00
settings.gradle.kts Initial Beta build 2026-10-24 09:09:55 -07:00
version.properties Release 0.1.4 with smoother browsing and Library tab focus 2026-10-24 13:14:32 -07:00

Kaleido

A native Kotlin / Jetpack Compose / Media3 client for personal Plex movie and television libraries on Android TV 9 and newer. Built for a remote, with cinematic server artwork, focused content rows, discovery hubs, paged libraries, and an original dark visual design inspired by the supplied references.

Build on Windows

  1. Run scripts/bootstrap.py with Python 3 to download an isolated JDK 17, Gradle 8.13, and Android command-line tools under .tools/.
  2. Set JAVA_HOME to the extracted JDK directory and run .tools/sdk/cmdline-tools/latest/bin/sdkmanager.bat --sdk_root=<absolute .tools/sdk path> "platforms;android-36" "build-tools;35.0.0". Accept the SDK license when prompted.
  3. Run ./Build.ps1 -Test for the debug APK, unit tests, and lint. Run ./Build.ps1 -Release for the optimized release APK.

Open the project root in Android Studio to use an existing local Android SDK instead. Set ANDROID_HOME and use the bundled Gradle distribution or the wrapper.

The first local build creates .tools/kaleido-signing.jks. Keep a private backup of this file and its credentials. Every app update must use the same signing key. Debug and release builds share this local key so the test installation can receive the release through the updater. CI uses an ephemeral validation key and publishes only the locally signed distribution APK. For alternate signing, set KALEIDO_KEYSTORE, KALEIDO_STORE_PASSWORD, KALEIDO_KEY_ALIAS, and KALEIDO_KEY_PASSWORD.

Connect

Open Kaleido and enter its code at plex.tv/link. Settings → Sign in with Plex can link an account while keeping the current connection until successful server selection; Back cancels linking. Choose a server if more than one is available. The client tests the discovered server connections and prefers TLS. A manual server URL / token connection is also available. The credentials are AES-GCM encrypted with an Android Keystore key, never backed up, and removed on sign-out. Local HTTP servers remain supported. Account tokens are sent only to Plex account endpoints; server tokens are sent to the selected Plex server.

.env and signing keys are ignored by Git. No test credentials are included in source code, BuildConfig, resources, or APKs. scripts/device.py seed is an optional debug-only provisioning helper: it sends .env credentials to private app data over the already-authorized ADB connection. Kaleido immediately encrypts them and deletes the staging file. Release builds never read this staging file.

Remote and playback

D-pad moves focus, OK activates, and Back returns through details and seasons. In the player, OK shows controls; Left/Right while controls are hidden seeks; dedicated media keys control playback. The on-screen controls provide pause, seeking, audio, subtitles, next episode, and exit. Back first hides controls, then exits playback. Stopping or leaving the app reports the latest position to Plex.

Direct stream is the default, requesting original resolution and remuxing where supported, with transcoding fallback. The player gear also exposes original-file playback, transcoding, audio, subtitles, speed, quality, and chapters. Media3's SurfaceView preserves supported HDR. Actual HDR, Dolby Vision, codecs, and audio passthrough depend on the device, connected display/receiver, source profile, and server. Plex owns transcoding capability and any account entitlements. Unsupported subtitle formats use server conversion. Intro and credit buttons appear when the server supplies markers. Scrubbing displays server-generated video previews or chapter thumbnails when available; the timeline also shows buffered progress. Episode endings and Skip credits show a cancellable five-second next-episode countdown, season episodes, and related shows.

Updates and releases

Kaleido checks the public repository releases on launch and foreground entry, at most once per six hours. Settings offers an immediate check. It downloads the release APK over HTTPS, checks its supplied SHA-256 when available, and verifies the package name, increasing Android version code, and installed signing certificate before opening Android's package installer. Android requires a one-time “allow from this source” permission and confirmation for each installation.

To publish a version:

  1. Increment both fields in version.properties and update CHANGELOG.md.
  2. Run ./Build.ps1 -Release -Test, then python scripts/package_release.py.
  3. Commit the source and distribution/, push main, and push the matching v<versionName> tag.

The Forgejo workflow builds, tests, and lints the source, verifies the prebuilt signed distribution, then publishes its APK and checksum using Forgejo's repository-scoped token. The private production signing key never leaves the developer machine. The checked-in APK also provides a repository-file update channel, with an immutable tag URL in distribution/latest.json, for installations before the first Forgejo release is ready.

Structure and references

PlexApi.kt owns Plex transport and server-relative API calls; SecureSession.kt owns credential encryption; KaleidoViewModel.kt owns navigation and async screen data; Screens.kt and Theme.kt implement the TV UI; Playback.kt owns Media3, stream negotiation, track selection, lifecycle, and timeline reporting; AppUpdater.kt verifies updates. Artwork has bounded memory and disk caches. Library data is paged in batches of 100.

Implementation follows the official Plex Media Server API, Android Compose guidance, and Media3 documentation. This is an independent client, unaffiliated with Plex. No existing Plex client source is copied.