feat(android): Chromecast cast + album autoplay (spec 060 T010-T014) #1221

Merged
chris merged 3 commits from feature/060-cast-android into main 2026-10-14 17:33:27 +02:00
Owner

Implements the Android sender lane of the approved cast design (docs/superpowers/specs/2026-10-14-android-cast-chromecast-design.md §5.1/6/7): CAF sender + Default Media Receiver (CC1AD845), phone as remote, album autoplay slideshow. No custom receiver, no Cast queue — RemoteMediaClient.load() per item (Immich-verified pattern).

T010 deps/wiring — play-services-cast-framework 22.3.1, androidx.mediarouter 1.8.1, appcompat 1.8.0 (libs.versions.toml); CastOptionsProvider registered as manifest meta-data. CAF's AAR floors minSdk at 23 — app minSdk 25 satisfies it (verified at manifest merge). MainActivity: ComponentActivity → FragmentActivity and Theme.Memories: framework Material → Theme.AppCompat.Light — both are hard prerequisites of MediaRouteButton's chooser/controller DialogFragments (verified in mediarouter 1.8.1 sources).

T011 CastController (AppContainer singleton, main-thread CAF) — session lifecycle via SessionManagerListener; viewer pager settle → fresh POST /api/media/token → ?st= on the URL → MediaInfo(STREAM_TYPE_BUFFERED, contentType, MEDIA_TYPE_PHOTO/MOVIE).load(autoplay). Latest-wins job per settle so rapid swipes can't leave the TV behind the phone. Rendition mapping (pure, tested): photo → preview (thumbnail fallback), video → video_rendition (spec 059 field newly parsed into TimelineItemDto/Ui) with /original?purpose=view fallback. Token/load/disconnect failures emit typed events → snackbars; mint failure skips the item and self-heals on the next LOAD.

T012 UI — CastRouteButton (AndroidView over MediaRouteButton using the CAF merged selector, per-placement mediaRouteTheme overlays for white-on-black vs dark-on-light glyphs) in the viewer top bar (new optional ViewerTopBar trailing slot) and the album top bar; connected-state indicator is the button's own drawable state; no-devices stays with the system picker (design §7).

T013 album autoplay — AlbumSlideshow: interruptible state machine (photo interval default 5 s, picker 2/3/5/8/10 s; video advances on receiver terminal-idle finished/error/canceled with a generous 4 h stall cap; load failures skip; pause/resume/next/prev/stop). Overflow action → interval dialog → mini player bar (prev/play-pause/next/stop) on the album screen. Foreground-scoped by design: leaving the screen stops the run; a foreground service is a documented follow-up (code comment + ISSUE-158).

T014 tests — AlbumSlideshowTest (virtual clock: interval advance, video-complete advance, stall cap, pause/resume incl. during video, next/prev, stop, skip/finish rules), CastMediaTest (rendition mapping + st query building), HttpMediaTokenApiTest (MockWebServer: path/body/auth/response/401). FakeMemoriesApi gained mintMediaToken.

Validation (apps/android, exact CI command): ./gradlew :core:test :app:testDebugUnitTest :app:assembleDebug — BUILD SUCCESSFUL; 454 unit tests, 0 failures; app-debug.apk built. :app:assembleRelease also verified green.

Contract assumptions (backend lane built in parallel):

  • POST /api/media/token body {mediaItemId, rendition} → {token, expiresAt(epochSecs)}; rendition ∈ {original, preview, thumbnail, video_rendition} matching the derived-type names DerivedAssetController accepts.
  • Auth: the task states session-cookie auth; this client's durable credential is the API bearer token (cookie is discarded after login), so the mint call sends Authorization: Bearer like every other call, with the session cookie riding along in the cookie jar when the process still holds one — assumes the endpoint accepts either, as the rest of /api/media does.
  • The signed URLs we hand Chromecast are the exact server-relative paths the payloads already carry (derived/preview|thumbnail|video_rendition, /original?purpose=view) + ?st= — the backend's ?st= acceptance on those endpoints is assumed per design §5.3.

KNOWN_ISSUES: ISSUE-158 (device matrix unverified, foreground-only slideshow, backend dependency).

Implements the Android sender lane of the approved cast design (docs/superpowers/specs/2026-10-14-android-cast-chromecast-design.md §5.1/6/7): CAF sender + Default Media Receiver (CC1AD845), phone as remote, album autoplay slideshow. No custom receiver, no Cast queue — RemoteMediaClient.load() per item (Immich-verified pattern). **T010 deps/wiring** — play-services-cast-framework 22.3.1, androidx.mediarouter 1.8.1, appcompat 1.8.0 (libs.versions.toml); CastOptionsProvider registered as manifest meta-data. CAF's AAR floors minSdk at 23 — app minSdk 25 satisfies it (verified at manifest merge). MainActivity: ComponentActivity → FragmentActivity and Theme.Memories: framework Material → Theme.AppCompat.Light — both are hard prerequisites of MediaRouteButton's chooser/controller DialogFragments (verified in mediarouter 1.8.1 sources). **T011 CastController** (AppContainer singleton, main-thread CAF) — session lifecycle via SessionManagerListener; viewer pager settle → fresh POST /api/media/token → ?st= on the URL → MediaInfo(STREAM_TYPE_BUFFERED, contentType, MEDIA_TYPE_PHOTO/MOVIE).load(autoplay). Latest-wins job per settle so rapid swipes can't leave the TV behind the phone. Rendition mapping (pure, tested): photo → preview (thumbnail fallback), video → video_rendition (spec 059 field newly parsed into TimelineItemDto/Ui) with /original?purpose=view fallback. Token/load/disconnect failures emit typed events → snackbars; mint failure skips the item and self-heals on the next LOAD. **T012 UI** — CastRouteButton (AndroidView over MediaRouteButton using the CAF merged selector, per-placement mediaRouteTheme overlays for white-on-black vs dark-on-light glyphs) in the viewer top bar (new optional ViewerTopBar trailing slot) and the album top bar; connected-state indicator is the button's own drawable state; no-devices stays with the system picker (design §7). **T013 album autoplay** — AlbumSlideshow: interruptible state machine (photo interval default 5 s, picker 2/3/5/8/10 s; video advances on receiver terminal-idle finished/error/canceled with a generous 4 h stall cap; load failures skip; pause/resume/next/prev/stop). Overflow action → interval dialog → mini player bar (prev/play-pause/next/stop) on the album screen. Foreground-scoped by design: leaving the screen stops the run; a foreground service is a documented follow-up (code comment + ISSUE-158). **T014 tests** — AlbumSlideshowTest (virtual clock: interval advance, video-complete advance, stall cap, pause/resume incl. during video, next/prev, stop, skip/finish rules), CastMediaTest (rendition mapping + st query building), HttpMediaTokenApiTest (MockWebServer: path/body/auth/response/401). FakeMemoriesApi gained mintMediaToken. **Validation (apps/android, exact CI command)**: ./gradlew :core:test :app:testDebugUnitTest :app:assembleDebug — BUILD SUCCESSFUL; 454 unit tests, 0 failures; app-debug.apk built. :app:assembleRelease also verified green. **Contract assumptions (backend lane built in parallel)**: - POST /api/media/token body {mediaItemId, rendition} → {token, expiresAt(epochSecs)}; rendition ∈ {original, preview, thumbnail, video_rendition} matching the derived-type names DerivedAssetController accepts. - Auth: the task states session-cookie auth; this client's durable credential is the API bearer token (cookie is discarded after login), so the mint call sends Authorization: Bearer like every other call, with the session cookie riding along in the cookie jar when the process still holds one — assumes the endpoint accepts either, as the rest of /api/media does. - The signed URLs we hand Chromecast are the exact server-relative paths the payloads already carry (derived/preview|thumbnail|video_rendition, /original?purpose=view) + ?st= — the backend's ?st= acceptance on those endpoints is assumed per design §5.3. KNOWN_ISSUES: ISSUE-158 (device matrix unverified, foreground-only slideshow, backend dependency).
Cast to Chromecast with the phone as remote, via the CAF sender against
Google's Default Media Receiver (CC1AD845) - no custom receiver, no Cast
queue (verified Immich pattern): RemoteMediaClient.load() per item.

T010 - deps + wiring:
- play-services-cast-framework 22.3.1, androidx.mediarouter 1.8.1,
  appcompat 1.8.0 via libs.versions.toml; CAF minSdk floor 23 (checked at
  manifest merge) satisfied by minSdk 25, documented in the version file.
- CastOptionsProvider (OptionsProvider) with DEFAULT_MEDIA_RECEIVER_
  APPLICATION_ID, registered as manifest meta-data.
- MainActivity becomes FragmentActivity and Theme.Memories becomes an
  AppCompat theme - both are hard prerequisites of MediaRouteButton's
  chooser/controller DialogFragments (verified in mediarouter sources).

T011 - CastController (AppContainer singleton, main-thread CAF):
- session lifecycle via SessionManagerListener; connection exposed as a
  StateFlow; defensive when Play services is absent.
- viewer pager settle -> mint POST /api/media/token (new client method,
  bearer + cookie-jar auth like every call here) -> append ?st= ->
  MediaInfo(BUFFERED, mime, MEDIA_TYPE_PHOTO/MOVIE) -> load(autoplay).
  Latest-wins job so rapid swipes can never leave the TV on an older page.
- rendition mapping: photo -> preview (thumbnail fallback), video ->
  video_rendition (spec 059 field newly parsed) with original?purpose=view
  fallback; pure and unit-tested in CastMedia.
- token mint / load / disconnect failures emit typed events for snackbars;
  mint failure skips the item (self-heals on the next LOAD).

T012 - UI:
- CastRouteButton (AndroidView over MediaRouteButton, merged CAF selector,
  per-placement mediaRouteTheme overlays for white-on-black vs dark-on-light
  glyphs) in the viewer top bar (new ViewerTopBar trailing slot) and the
  album top bar; connected-state indicator is the button's own drawable
  state; no-devices stays with the system picker.
- viewer + album drain cast events into their snackbars.

T013 - album autoplay:
- AlbumSlideshow: interruptible state machine over the album items -
  photo interval (default 5 s, picker 2/3/5/8/10 s), video advances on
  receiver terminal-idle (finished/error/canceled) with a generous 4 h
  stall cap, load failures skip, all-failed or end-of-album finishes.
- overflow action "play album on TV" -> interval dialog -> mini player
  bar (prev / play-pause / next / stop) on the album screen; foreground
  scoped by design (leaving the screen stops the run; foreground service is
  a documented follow-up, not built here).

T014 - JVM tests: AlbumSlideshowTest (virtual-clock state machine),
CastMediaTest (rendition + st URL building), HttpMediaTokenApiTest
(MockWebServer contract); FakeMemoriesApi gained the mint method.
Verified: :core:test + :app:testDebugUnitTest (454 tests, 0 failures) +
:app:assembleDebug, plus assembleRelease.
docs: KNOWN_ISSUES - cast device-verification gap (spec 060, ISSUE-158)
All checks were successful
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 2s
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build Android CI image (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
Build and Deploy / Run scoped PR tests (push) Successful in 5s
Build and Deploy / Android unit tests and debug APK (push) Successful in 5m57s
e62ea4d59e
JVM/build verification only for T010-T014: the on-hardware Chromecast
matrix (swipe-sync, autoplay, token self-heal, screen-off/TV-off session
behavior) still needs manual runs, the slideshow is foreground-scoped by
design, and LOADs depend on the parallel backend lane's
POST /api/media/token being deployed.
fix(android): bound slideshow LOAD with timeout to avoid wedged state (spec 060 review)
All checks were successful
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 2s
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build Android CI image (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
Build and Deploy / Run scoped PR tests (push) Successful in 5s
Build and Deploy / Android unit tests and debug APK (push) Successful in 3m23s
1d35f836d8
chris merged commit 526cf597e3 into main 2026-10-14 17:33:27 +02:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
chris/memories!1221
No description provided.