All checks were successful
Validate and publish Kaleido / android (push) Successful in 2m25s
52 lines
14 KiB
Markdown
52 lines
14 KiB
Markdown
# Kaleido visual system
|
||
|
||
The interface gives artwork priority. App chrome uses neutral near-black, charcoal, and white. Color belongs to the user's media. Navigation, cards, and player controls share the same restrained focus language.
|
||
|
||
## Layout and typography
|
||
|
||
- Horizontal safe gutter: 44 dp. Navigation: 62 dp, with centered text destinations and independent search/settings icons.
|
||
- Home retains a large cinematic feature: an 80 percent stage with original title artwork, synopsis, playback and information actions. The scene continues beneath Continue Watching; entering the rail scrolls the feature away and the backdrop follows focused titles. Features interleave recently released, highly rated unwatched, and Plex-suggested movies/shows, excluding Continue Watching. They shuffle per refresh and rotate every 12 seconds while the hero is active, pausing during row browsing.
|
||
- Movies uses a compact fixed preview above poster rows, with the backdrop and synopsis following focused titles. Recently released films and movie recommendations lead. TV uses a shorter preview, larger episode thumbnails, next episodes, newly added seasons, and then new episodes and show recommendations. Redundant TV hubs are omitted when their episode lists match exactly. These are deliberately different compositions.
|
||
- Library: title and discovery/full-library navigation share a 64 dp header. A 43 dp filter row sits immediately above the six-column poster grid.
|
||
- Browsing card widths: landscape 214 dp, TV episodes 264 dp, posters 120 dp. Landscape artwork uses 16:9; posters use 2:3. The full grid scales six columns to available width. Captions reserve a fixed height.
|
||
- Search uses three columns of landscape results. Episodes use their actual stills, preserving their native proportions instead of cropping them into posters.
|
||
- Movie and episode information pages place a horizontal Cast row beneath the description and actions, using Plex portraits, names and character roles. TV show pages place Seasons first, then Cast, then server-provided Related shows; season pages likewise keep Episodes ahead of Cast. Missing portraits use a neutral person placeholder. Actor cards open a six-column filmography of available movies and shows across the connected server's libraries, using Plex actor identifiers and pagination.
|
||
- TV show information uses a full-screen backdrop behind a fitted 128 × 192 dp poster and a top-aligned text block capped at 560 dp, matching movie details. The three-line summary offers a Synopsis action when truncated, opening the full text with D-pad scrolling. Its 248 dp minimum header keeps season artwork and captions on the initial screen at the standard TV density; longer titles can grow the header. The Back control stays in the safe area; focus only scrolls controls that are out of view. Artwork fades to near-black before the lower rows and disappears over the first 180 dp of scrolling. Soft text shadows preserve header contrast.
|
||
- Movie, episode, show and season information pages expose labelled Mark watched / Mark unwatched actions. Changes are sent to Plex and reflected in the title, descendant episodes/seasons, library cards, actor results and recommendations. An in-flight write survives navigation and prevents duplicate submissions. Partial episode-list records update watch fields without replacing full cast/detail metadata.
|
||
- Settings uses a fixed category rail (Connection, Playback, Interface, Updates) beside compact value/action rows. Focus selects categories; Right enters their controls and Left returns to the rail. Neutral surfaces, white focus, existing typography and restrained motion match the browsing destinations. Existing account, quality, watched-threshold, navigation-sound and updater preferences keep their behavior.
|
||
- Features use original Plex clear-logo artwork within 264 × 80 dp, falling back to title text. Detail title: 32/36 sp. Library title: 29/34 sp. Discovery rail heading: 17/22 sp. Supporting information: 10/14 sp.
|
||
- Poster and thumbnail corners: 6 dp. Compact action corners: 5 dp. Cards have no idle border; a compact bottom-right check marks watched titles, or a number shows remaining episodes for a show/season when Plex provides counts. Unwatched movies have no badge. Resumed movies/episodes only show a check after the configured playback threshold (80 percent by default), even if Plex retains a historical watched flag. Completed titles with no resume position retain Plex's watched state. Progress uses a two-dp inset line.
|
||
- The abstract six-facet aperture mark is shared by the header, sign-in, app icon, TV banner, and the cold-start aperture sequence. It uses muted sea-glass and warm ivory facets around a dark center, with no letterform or sparkle. The launcher banner and app icon place it on a diagonal light, deep sea-glass at the top right through near-black to a warm tan glow at the bottom left, with a soft vignette and nothing over the aperture; `scripts/generate_brand_tiles.py` regenerates both from `brand_mark.xml`.
|
||
- Audience ratings display Rotten Tomatoes as a percentage beside its official Popcornmeter artwork, and IMDb on its native ten-point scale beside the gold IMDb logo. Both appear when Plex exposes both; TVDB is retained as a fallback when neither is available. Critic scores and unsupported providers are omitted. Stable preview focus hydrates detail metadata, where Plex exposes the full provider list. The official red Hot mark appears at 60 percent or above and the green Stale mark below 60 percent; each fits a stable, font-scaled square without recoloring or distortion. Verified Hot is not inferred from a percentage. Asset provenance is in [brand-assets.md](brand-assets.md). The IMDb vector uses the official gold primary mark and supplied clear space from the [IMDb brand toolkit](https://brand.imdb.com/imdb).
|
||
|
||
## Focus and motion
|
||
|
||
- Discovery cards keep fixed bounds and use a two-dp white focus outline. No scale or shadow changes trigger lazy-row layout or move a neighboring row.
|
||
- Text actions scale to 1.025 over 160 ms. Navigation uses text, an understated selected underline, and a translucent charcoal focus surface.
|
||
- Navigation focus changes use Android's native UI tick. Settings > Interface > Navigation sounds toggles it immediately and persists across process restarts; it defaults to On and follows the TV's global sound-effects setting. Initial startup focus and repeated notifications for the same target are silent. The shared focus observer covers navigation, cards, buttons, dialogs, playback options and the timeline without changing key handling.
|
||
- Navigation contrast comes from a gradient extending past the controls and fading to transparent. Home/Movies/TV activate on focus. Explicit row and column links prevent beyond-bounds focus searches when holding a remote direction.
|
||
- A spaced D-pad move predicts the actual row/column destination before starting its scroll or focus change. The target backdrop is fetched and contrast-processed through the same Coil request/cache as the visible scene. Speculative artwork uses one low-priority worker so it cannot flood normal decode workers during a burst of input. Metadata starts in parallel; the visible preview and details page share that in-flight request. Rapid horizontal input settles to the latest target before starting speculative work. Full metadata uses a 64-item LRU with a 30-second lifetime, cleared on account/server changes and refreshed after watched updates. Neutral library/search grids prefetch metadata without fetching an unused full-screen backdrop.
|
||
- Home's vertical list prepares content within one viewport ahead and retains one viewport behind, using Compose's bounded lazy-layout cache window. This keeps the hero and nearby rows ready when moving between them, rather than repeatedly composing and measuring the exposed image cards during the animation. Movies/TV use the same window. The window only fills ahead after the list has scrolled, so once a section settles it is nudged 1 px and back, letting the next rows compose in idle frames instead of during the first move down. Card sizes, row targets and the large cinematic Home layout are unchanged.
|
||
- Section previews settle for 120 ms (Home artwork for 90 ms), overlapping the navigation animation, and retain previous artwork until replacement data is ready. Contrast gradients are baked into a cached bitmap on a worker thread, reducing GPU overdraw. Hero recommendation changes crossfade the artwork over 220 ms, including cache hits, and fade the title/summary out for 100 ms and back in over 180 ms. Rotation pauses on the information/next controls and preserves their focus. Vertical row changes animate to explicit row/column targets; page entrances fade and slide 28 dp over 280 ms, using per-draw alpha rather than an offscreen layer, and start once the new section's composition frames have passed (at most 300 ms). While a section enters, its cards lay out at their fixed size first and fill in artwork and titles three per frame under the fade, so the section's first frame stays short. Focusing a top tab lets its highlight draw before the section switches. The cold-start sequence lasts 2.9 seconds. The six exact facets begin as a closed, overlapping iris lit from behind; it holds there (at most 700 ms) until startup data has arrived and frames are steady, so cold-start hitches never interrupt the motion. The iris then twists 44° open and locks with a slight overshoot while light leaks through the six gaps, a single sheen crosses the settled mark, and the mark shrinks into a lockup scaled from the header brand as KALEIDO slides out from behind it. Once loading finishes (up to 600 ms extra) the camera flies through the aperture's dark center over 640 ms, revealing the app beneath as it settles from 114 percent scale. The completed mark itself is never redesigned. Android animation duration scale is honored, including animations off. It does not replay when returning from background.
|
||
- Returning from details restores the library's mode, scroll position, and previously focused title.
|
||
- Entering Movies/TV from the top bar focuses the fixed Discover control immediately. Down from Discover explicitly reveals the first catalog card; focus on already-visible targets changes before scrolling. A quick tab/Down sequence queues entry for the new destination, and focused tabs never repeat their delayed initial-focus request.
|
||
- Offscreen card navigation requests the next lazy layout instead of forcing synchronous composition between key events. Up at the top bar is consumed because there is no destination above it; it must not start a lazy-list focus search.
|
||
- Horizontal rows prepare one viewport ahead and retain half a viewport behind. New card artwork/text fills over up to three frames at fixed bounds. Horizontal focus commits on a frame boundary; a pending column accumulates rapid D-pad steps before committing the latest target, keeping accessibility layout work out of the gap between KeyDown and KeyUp.
|
||
- Horizontal presses less than 160 ms apart snap to the latest anchor and wait 70 ms before speculative metadata/artwork. Spaced presses retain the 140 ms scroll animation and immediate prediction.
|
||
- New seasons groups additions by Plex parent show ID, preserving newest-first order. Multiple seasons use the real show metadata and open its season list; single-season additions retain direct season navigation. The query samples 100 seasons before selecting up to 18 distinct shows, so one series import cannot occupy every card.
|
||
|
||
## Player
|
||
|
||
Controls occupy a shallow bottom gradient. A compact title, slim timeline, small time labels, central transport icons, and right-aligned track icons replace the rectangular button grid. The timeline is a true D-pad focus target: Up from transport reaches it, Left/Right seek, and Down returns to Play/Pause. Holding a direction increases the seek step. Dedicated media keys remain supported.
|
||
|
||
The controls fade and slide away after five seconds during playback. While they are hidden, a Left/Right tap skips 10 seconds without revealing anything (quick taps add up into one seek), and holding Left/Right reveals the focused timeline for scrubbing. OK and Down reveal them; Back hides them before exiting. Audio and subtitle panels open above their icons and restore focus when dismissed. A gear exposes quality, audio, subtitles, speed, and chapters. Quality is one list shared with Settings: Original quality (the default, direct stream of the source video), then 4K, 1080p, 720p and 480p conversions. The timeline includes buffered progress and server-generated video/chapter previews. Skip actions have opaque contrast surfaces.
|
||
|
||
Episode endings and Skip credits open a five-second, cancellable next-episode countdown with season episodes and related shows. Each player session has a unique Media3 session ID so overlapping Compose disposal and next-episode creation cannot collide.
|
||
|
||
Settings includes a persistent watched percentage. Timeline reporting scrobbles the item in Plex once the selected percentage is reached, retries a failed write, and avoids repeated scrobbles within the same player session. This preference belongs to Kaleido and does not change the Plex server's global settings. Explicit watched changes refresh the title and parent episode counts across browsing caches.
|
||
|
||
## Device review
|
||
|
||
Use `scripts/verify_ui.py browse` and `scripts/verify_ui.py player` with the authorized ADB connection. These drive the actual UI with remote key events, assert focus and navigation, and capture screens into the ignored `evidence/private/` directory. The player check uses the live Plex server's existing conversion mode. Run `Build.ps1 -Test` for compilation, unit tests, and lint. Inspect the optimized release APK on the TV before judging startup or animation performance.
|
||
|
||
Visual references: [Netflix's TV experience](https://about.netflix.com/en/news/unveiling-our-innovative-new-tv-experience), [Netflix's current TV layout guidance](https://help.netflix.com/en/node/321880164349028), and [Apple TV](https://www.apple.com/apple-tv-app/). The layout and artwork remain independent and Plex-backed.
|