|
All checks were successful
Validate and publish Kaleido / android (push) Successful in 2m19s
The banner and app icon keep the unchanged six-facet mark but replace the flat black background with a diagonal light: deep sea-glass at the top right fading through near-black to a warm tan glow at the bottom left, with a soft vignette and nothing over the aperture. A small generator rebuilds both drawables from brand_mark.xml. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> |
||
|---|---|---|
| .forgejo/workflows | ||
| app | ||
| distribution | ||
| docs | ||
| gradle/wrapper | ||
| scripts | ||
| .gitignore | ||
| AGENTS.md | ||
| build.gradle.kts | ||
| Build.ps1 | ||
| CHANGELOG.md | ||
| gradle.properties | ||
| gradlew | ||
| gradlew.bat | ||
| README.md | ||
| settings.gradle.kts | ||
| version.properties | ||
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
- Run
scripts/bootstrap.pywith Python 3 to download an isolated JDK 17, Gradle 8.13, and Android command-line tools under.tools/. - Set
JAVA_HOMEto 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. - Run
./Build.ps1 -Testfor the debug APK, unit tests, and lint. Run./Build.ps1 -Releasefor 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:
- Increment both fields in
version.propertiesand updateCHANGELOG.md. - Run
./Build.ps1 -Release -Test, thenpython scripts/package_release.py. - Commit the source and
distribution/, pushmain, and push the matchingv<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.