Release Kaleido 0.1.8 with cast browsing and refreshed title pages
All checks were successful
Validate and publish Kaleido / android (push) Successful in 2m8s

This commit is contained in:
Elijah 2026-10-25 21:49:24 -07:00
parent 119f1ae5a9
commit 5199bb0928
28 changed files with 982 additions and 187 deletions

View file

@ -1,59 +1,70 @@
# Kaleido
A native client for personal Plex movie and television libraries on Android TV 9 and newer. Built for a remote, with cinematic artwork, movie and TV discovery, next-episode rows, and filterable libraries. Powered by Kotlin, Jetpack Compose, and Media3.
A Plex client for Android TV, designed for browsing from the couch. Kaleido puts your movies, shows and next episodes up front, with large artwork and controls that work with a remote.
**[Download the latest release](https://git.elijahkuntz.com/Elijah/Kaleido/releases/latest)** · Android TV 9 or newer · Requires a Plex Media Server
## What's in the app
### Find something to watch
- **Home** brings together featured titles, Plex recommendations and Continue Watching. Resume a movie or get back to your current series without digging through your library.
- **Movies** starts with recent releases and recommendations. **TV Shows** leads with your next episodes, new seasons and newly added episodes.
- **Library** gives you an A–Z poster grid with genre, watched-status and sorting controls. Search finds movies, shows and episodes across your libraries.
- **Title pages** include ratings, a synopsis and cast portraits with character names. Select an actor to see their available movies and shows. Series pages put seasons first, with cast and related shows below.
### Watch the way you want
Original quality plays the source video where your TV supports it. You can also ask Plex to convert to 4K, 1080p, 720p or 480p for a slower connection or a different device.
Choose audio tracks, subtitles, playback speed and chapters from the player. Tap Left or Right to skip ten seconds, or hold to scrub through the timeline with thumbnail previews. Skip intros and credits, and let the next episode start after a short, cancellable countdown. Previews and skip markers appear when Plex supplies them; HDR and format support depend on your TV and server.
### Keep your place
Playback progress and watched status sync with Plex, so your place carries across clients. Mark a movie, season or whole show watched or unwatched from its information page. You can set the playback percentage that counts as watched, too.
Settings groups connection, playback, interface and updates in one place. Navigation tap sounds can be turned on or off. The built-in updater checks for releases and downloads new versions without another manual sideload.
## Install
1. Download **Kaleido.apk** from the [latest release](https://git.elijahkuntz.com/Elijah/Kaleido/releases/latest) and install it on your Android TV.
2. Open Kaleido and enter the code at [plex.tv/link](https://plex.tv/link).
3. Choose your Plex server and start browsing.
A manual server URL and token connection is also available. For future updates, use **Settings → Updates**. Android will ask you to confirm the installation.
## Screenshots
Captured from Kaleido **0.1.7** running on Android TV with a live Plex library. Select a screenshot to view it at full resolution.
Captured from Kaleido **0.1.8** running on Android TV with a live Plex library. Select a screenshot to view it at full resolution.
**Home** — a cinematic feature with playback actions and integrated Continue Watching.
[![Kaleido Home with a cinematic Parasite feature and Continue Watching row](docs/screenshots/home.webp)](docs/screenshots/home.webp)
[![Kaleido Home with cinematic featured artwork and a Continue Watching row](docs/screenshots/home.webp)](docs/screenshots/home.webp)
| Movie discovery | TV discovery |
| --- | --- |
| [![Movies with focused backdrop artwork, audience ratings, and recently released posters](docs/screenshots/movies.webp)](docs/screenshots/movies.webp) | [![TV shows with next-episode thumbnails and newly added seasons](docs/screenshots/tv.webp)](docs/screenshots/tv.webp) |
| A–Z library | Title details |
| Movie information and cast | TV show information and seasons |
| --- | --- |
| [![Movie library with a six-column poster grid, genre filters, and sorting](docs/screenshots/library.webp)](docs/screenshots/library.webp) | [![Title details with synopsis, audience ratings, cast, and playback action](docs/screenshots/details.webp)](docs/screenshots/details.webp) |
| [![Movie information with synopsis, ratings, watched controls and actor portraits](docs/screenshots/details.webp)](docs/screenshots/details.webp) | [![TV show information with a fitted poster, readable synopsis and Seasons first](docs/screenshots/show.webp)](docs/screenshots/show.webp) |
## Build on Windows
| Actor filmography | Settings |
| --- | --- |
| [![Actor page showing available movies and television series across Plex libraries](docs/screenshots/actors.webp)](docs/screenshots/actors.webp) | [![Settings category rail with playback quality and watched preferences](docs/screenshots/settings.webp)](docs/screenshots/settings.webp) |
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.
| A–Z library | Cast and related shows |
| --- | --- |
| [![Movie library with a six-column poster grid, genre filters, and sorting](docs/screenshots/library.webp)](docs/screenshots/library.webp) | [![Show information with actor portraits and related series from Plex](docs/screenshots/related.webp)](docs/screenshots/related.webp) |
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.
## Build from source
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`.
Kaleido is written in Kotlin with Jetpack Compose and Media3. On Windows, the local toolchain can be set up with `scripts/bootstrap.py`, then built with:
## Connect
```powershell
.\Build.ps1 -Release -Test
```
Open Kaleido and enter its code at [plex.tv/link](https://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.
See the [development guide](docs/development.md) for setup and releases, the [design notes](docs/design-system.md), and [device testing](docs/runtime-verification.md).
`.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](https://git.elijahkuntz.com/Elijah/Kaleido/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](https://developer.plex.tv/pms/), [Android Compose guidance](https://developer.android.com/compose), and [Media3 documentation](https://developer.android.com/media/media3). This is an independent client, unaffiliated with Plex. No existing Plex client source is copied.
Kaleido is in active development. It is an independent project and is not affiliated with Plex.