feat(android): Phase 0 media viewer — pinch-zoom, video playback, load states #1112

Merged
chris merged 1 commit from ux-android-viewer into main 2026-10-11 14:56:03 +02:00
Owner

What

Spec 055 Phase 0 for the Android app's full-bleed media viewer:

  • Pinch-zoom on photos — 1x–5x, focal-anchored zoom, two-finger pan clamped so the image can never be panned out of the viewport, double-tap to toggle fit/2x. Plain Compose pointer APIs (ViewerZoomState + ViewerGestures), no extra libraries.
  • Swipe-to-page still works at 1x — explicit gesture ownership: one finger at 1x is never consumed (the HorizontalPager keeps it), two fingers or a one-finger pan while zoomed are consumed by the transform layer. Paging is disabled while zoomed; settling on a new page always returns to 1x.
  • Video playback via media3-exoplayer: muted-by-default (rememberSaveable, so autoplay is never loud), tap reveals a control row with play/pause, seek, and a mute toggle. Only the current page holds a decoder.
  • Load states on both media types: subtle spinner placeholder while loading, friendly error copy with a retry action. All new user-facing strings live in string resources — German default (values/strings.xml), English (values-en), Danish (values-da).
  • Top bar: localized capture date + position (e.g. "12. September 2026 · 3 / 148") and a back button. No favorite/share/download/trash (those are a later slice).
  • System back exits the zoom first, then falls through to normal navigation.

Supporting changes:

  • TimelineItemUi now carries payload dimensions (width/height) so the pan clamp bounds against the fitted content size; unknown dimensions fall back to the viewport size.
  • MemoriesApp passes the authenticated TokenProvider into the viewer and observes the timeline list via collectAsStateWithLifecycle instead of a .value snapshot, so pages loaded by the viewer's near-end loadMore actually become pageable.
  • Pause/Volume glyphs are drawn with Canvas: material-icons-core ships neither and the extended artifact would add megabytes to an APK built without minification.
  • versionCode 4 → 5 (0.1.3 → 0.1.4).

Payload fields relied on

All fields already present on TimelineItemDto / the timeline contract — nothing invented:

Field Use
mediaType "photo" vs "video" page (zoomable image vs player)
captureTimestamp top-bar date label (localized LONG format; null-tolerant)
dimensions (width/height) pan-clamp bounds for the zoomed content
thumbnailUrl Coil fallback while the preview is missing
previewUrl image page source; preferred video playback URL

There is no videoDuration field; the seek slider reads duration from the player once metadata is available.

Known gap: video cannot play yet (tracked as ISSUE-115)

Video playback currently always lands in the error/retry state, for two server-side reasons:

  1. /api/media/{mediaItemId}/original?purpose=view is reserved in the OpenAPI contract but not exposed by a user-facing controller (only the worker-scoped /api/worker/jobs/{jobId}/media/{mediaItemId}/original exists).
  2. The worker's video_preview job reports video_preview_not_implemented, so no video rendition exists to serve either.

The client prefers previewUrl and falls back to the original endpoint, so a future video rendition is picked up with no further client change. The error state is friendly and retryable rather than a crash or a silent black screen.

Verification

cd apps/android && ./gradlew :app:testDebugUnitTest :app:assembleDebug — green (97 unit tests, debug APK assembled).

New JVM tests: ViewerZoomStateTest (scale clamps, focal-anchor invariance across zoom steps, pan clamping including the unknown-dimensions fallback, double-tap toggle, fitContentSize letterboxing), ViewerDateTest (ISO/offset timestamps, null/garbage tolerance), VideoPlaybackUrlTest. TimelineViewModelTest now asserts dimensions ride through to the UI model. TimelineJsonTest needed no change: DTO parsing already covered mediaType/dimensions.

## What Spec 055 Phase 0 for the Android app's full-bleed media viewer: - **Pinch-zoom on photos** — 1x–5x, focal-anchored zoom, two-finger pan clamped so the image can never be panned out of the viewport, double-tap to toggle fit/2x. Plain Compose pointer APIs (`ViewerZoomState` + `ViewerGestures`), no extra libraries. - **Swipe-to-page still works at 1x** — explicit gesture ownership: one finger at 1x is never consumed (the `HorizontalPager` keeps it), two fingers or a one-finger pan while zoomed are consumed by the transform layer. Paging is disabled while zoomed; settling on a new page always returns to 1x. - **Video playback** via media3-exoplayer: muted-by-default (`rememberSaveable`, so autoplay is never loud), tap reveals a control row with play/pause, seek, and a mute toggle. Only the current page holds a decoder. - **Load states** on both media types: subtle spinner placeholder while loading, friendly error copy with a retry action. All new user-facing strings live in string resources — German default (`values/strings.xml`), English (`values-en`), Danish (`values-da`). - **Top bar**: localized capture date + position (e.g. "12. September 2026 · 3 / 148") and a back button. No favorite/share/download/trash (those are a later slice). - **System back exits the zoom first**, then falls through to normal navigation. Supporting changes: - `TimelineItemUi` now carries payload `dimensions` (width/height) so the pan clamp bounds against the fitted content size; unknown dimensions fall back to the viewport size. - `MemoriesApp` passes the authenticated `TokenProvider` into the viewer and observes the timeline list via `collectAsStateWithLifecycle` instead of a `.value` snapshot, so pages loaded by the viewer's near-end `loadMore` actually become pageable. - Pause/Volume glyphs are drawn with Canvas: `material-icons-core` ships neither and the extended artifact would add megabytes to an APK built without minification. - versionCode 4 → 5 (0.1.3 → 0.1.4). ## Payload fields relied on All fields already present on `TimelineItemDto` / the timeline contract — nothing invented: | Field | Use | |---|---| | `mediaType` | "photo" vs "video" page (zoomable image vs player) | | `captureTimestamp` | top-bar date label (localized LONG format; null-tolerant) | | `dimensions` (`width`/`height`) | pan-clamp bounds for the zoomed content | | `thumbnailUrl` | Coil fallback while the preview is missing | | `previewUrl` | image page source; preferred video playback URL | There is no `videoDuration` field; the seek slider reads duration from the player once metadata is available. ## Known gap: video cannot play yet (tracked as ISSUE-115) Video playback currently always lands in the error/retry state, for two server-side reasons: 1. `/api/media/{mediaItemId}/original?purpose=view` is **reserved in the OpenAPI contract but not exposed by a user-facing controller** (only the worker-scoped `/api/worker/jobs/{jobId}/media/{mediaItemId}/original` exists). 2. The worker's `video_preview` job reports `video_preview_not_implemented`, so no video rendition exists to serve either. The client prefers `previewUrl` and falls back to the original endpoint, so a future video rendition is picked up with no further client change. The error state is friendly and retryable rather than a crash or a silent black screen. ## Verification `cd apps/android && ./gradlew :app:testDebugUnitTest :app:assembleDebug` — green (97 unit tests, debug APK assembled). New JVM tests: `ViewerZoomStateTest` (scale clamps, focal-anchor invariance across zoom steps, pan clamping including the unknown-dimensions fallback, double-tap toggle, `fitContentSize` letterboxing), `ViewerDateTest` (ISO/offset timestamps, null/garbage tolerance), `VideoPlaybackUrlTest`. `TimelineViewModelTest` now asserts `dimensions` ride through to the UI model. `TimelineJsonTest` needed no change: DTO parsing already covered `mediaType`/`dimensions`.
feat(android): Phase 0 media viewer — pinch-zoom, video playback, load states
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 / Build postgres image (push) Has been skipped
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 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 4s
Build and Deploy / Android unit tests and debug APK (push) Successful in 3m47s
c7ff24eaa5
Pinch-zoom (1x–5x, focal-anchored, clamped pan) with double-tap toggle on
photos; swipe-to-page keeps working at 1x through explicit gesture ownership
in ViewerGestures (one finger at 1x stays with the pager, two fingers or a
zoomed pan are consumed by the transform layer). Videos play through
media3-exoplayer, muted-by-default with a tap-revealed control row
(play/pause, seek, mute). Image and video pages both get a subtle loading
placeholder and a friendly error state with retry. The viewer top bar shows
the localized capture date plus position and a back button; system back
exits the zoom first, then falls through to navigation.

Timeline items now carry payload `dimensions` through TimelineItemUi so the
pan clamp can bound against the fitted content size (viewport fallback when
unknown). All new user-facing copy lives in de (default)/en/da string
resources; Pause/Volume glyphs are drawn locally because material-icons-core
has neither and the extended artifact would bloat an unminified APK.

Video playback relies on `previewUrl` first and falls back to
`/api/media/{id}/original?purpose=view`; that endpoint is currently only
reserved in the OpenAPI contract and the worker's `video_preview` job
reports video_preview_not_implemented, so videos surface the error/retry
state until the rendition slice lands (ISSUE-115).
chris merged commit 2758ddf889 into main 2026-10-11 14:56:03 +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!1112
No description provided.