From 16ba1407666bac961f29b6c9bfac138705c1f8ef Mon Sep 17 00:00:00 2001 From: Alan Grainger <16197738+alangrainger@users.noreply.github.com> Date: Thu, 17 Sep 2026 21:45:55 +1200 Subject: [PATCH] Size motion photo clip to the still and make the toggle sticky #286 --- app/public/photoswipe-overrides.css | 10 ++-- app/src/client/icons.ts | 6 +- app/src/client/lightbox-ui.ts | 93 +++++++++++++++++++---------- app/src/client/lightbox.ts | 3 +- app/src/gallery/builder.ts | 3 +- app/src/index.ts | 9 +-- app/src/share.ts | 10 +--- app/src/types.ts | 4 +- app/tests/motionPhoto.test.ts | 10 +--- docs/config/ipp-options.md | 4 +- 10 files changed, 82 insertions(+), 70 deletions(-) diff --git a/app/public/photoswipe-overrides.css b/app/public/photoswipe-overrides.css index 1fe3881..f5b6a09 100644 --- a/app/public/photoswipe-overrides.css +++ b/app/public/photoswipe-overrides.css @@ -139,14 +139,12 @@ html.pswp-no-arrows .pswp__button--arrow { background: #000; } -/* Motion photo (Live Photo) clip. It lives inside the slide's zoom wrap, which - carries PhotoSwipe's pan/zoom transform, so it stays pinned to the still - underneath through zoom, pan and resize with no geometry tracking in JS. */ +/* Motion photo (Live Photo) clip, inside the slide's zoom wrap so it follows + PhotoSwipe's pan / zoom. Width / height are set inline from the still. */ .pswp__motion-video { position: absolute; - inset: 0; - width: 100%; - height: 100%; + top: 0; + left: 0; object-fit: contain; pointer-events: none; /* PhotoSwipe keeps handling drag / zoom / swipe */ } diff --git a/app/src/client/icons.ts b/app/src/client/icons.ts index 642aee2..3abb272 100644 --- a/app/src/client/icons.ts +++ b/app/src/client/icons.ts @@ -16,8 +16,7 @@ export const ICON_FULLSCREEN = '` is created on demand with `preload="none"`: nothing is fetched - * from Immich until a visitor actually presses the button. + * Register the motion photo (Live Photo) toggle. While on, each motion photo + * plays its clip over the still on arrival and reverts when the clip ends. + * The button hides itself on slides without a clip. Nothing is fetched from + * Immich until the toggle is turned on. */ export function registerMotionButton (lightbox: LightboxInstance) { lightbox.on('uiRegister', () => { @@ -207,59 +210,87 @@ export function registerMotionButton (lightbox: LightboxInstance) { html: ICON_MOTION_PLAY, onInit: (el: HTMLElement, pswp: PswpInstance) => { let video: HTMLVideoElement | null = null + let sizer: ResizeObserver | null = null + let stillWatcher: MutationObserver | null = null const update = () => { el.hidden = !state.items[pswp.currIndex]?.motionUrl - const label = video ? 'Stop motion photo' : 'Play motion photo' - el.innerHTML = video ? ICON_MOTION_PAUSE : ICON_MOTION_PLAY + const label = motionEnabled ? 'Stop playing motion photos' : 'Play motion photos' + el.innerHTML = motionEnabled ? ICON_MOTION_PAUSE : ICON_MOTION_PLAY el.setAttribute('aria-label', label) el.setAttribute('title', label) } - // PhotoSwipe reuses slide DOM, so the clip has to be torn down on slide - // change too, not only when it reaches its end. const stop = () => { + stillWatcher?.disconnect() + stillWatcher = null const clip = video if (!clip) return video = null + sizer?.disconnect() + sizer = null clip.pause() clip.parentElement?.classList.remove(MOTION_PLAYING_CLASS) clip.remove() - update() } const play = () => { + if (video) return const item = state.items[pswp.currIndex] const wrap = currentZoomWrap(pswp) if (!item?.motionUrl || !wrap) return + const still = loadedStill(wrap) + if (!still) { + // PhotoSwipe appends the still after it loads, which can be after + // the slide change. Wait for it. + stillWatcher?.disconnect() + stillWatcher = new MutationObserver(() => { + if (loadedStill(wrap)) play() + }) + stillWatcher.observe(wrap, { childList: true }) + return + } + stillWatcher?.disconnect() + stillWatcher = null const clip = document.createElement('video') clip.className = 'pswp__motion-video' - // Muted is not optional - browsers refuse programmatic playback of - // audible media, and Immich's motion clips are silent regardless. - clip.muted = true + clip.muted = true // required for programmatic playback clip.playsInline = true clip.preload = 'none' clip.src = item.motionUrl + // Mirror the still's inline size, which PhotoSwipe rewrites on + // resize and after each zoom gesture. + const sizeToStill = () => { + clip.style.width = still.offsetWidth + 'px' + clip.style.height = still.offsetHeight + 'px' + } + sizeToStill() + sizer = new ResizeObserver(sizeToStill) + sizer.observe(still) clip.addEventListener('ended', stop, { once: true }) - // Hide the still only once the clip is actually painting, so a slow - // clip never leaves the slide blank. The identity check keeps a late - // event from a clip we already stopped from hiding the still for good. + clip.addEventListener('error', stop, { once: true }) + // Hide the still only once the clip is painting, so a slow clip never + // leaves the slide blank. clip.addEventListener('playing', () => { if (video === clip) wrap.classList.add(MOTION_PLAYING_CLASS) }, { once: true }) wrap.appendChild(clip) video = clip - update() clip.play().catch(() => stop()) } el.addEventListener('click', () => { - if (video) stop() - else play() + motionEnabled = !motionEnabled + if (motionEnabled) play() + else stop() + update() }) + // Also fires for the opening slide, so this covers reopening with + // the toggle on. pswp.on('change', () => { stop() update() + if (motionEnabled) play() }) pswp.on('destroy', stop) update() diff --git a/app/src/client/lightbox.ts b/app/src/client/lightbox.ts index dd7fec2..c270e8a 100644 --- a/app/src/client/lightbox.ts +++ b/app/src/client/lightbox.ts @@ -239,8 +239,7 @@ export function initLightbox () { registerBackButton(state.lightbox) if (state.lightboxConfig.showDownload) registerDownloadButton(state.lightbox) registerFullscreenButton(state.lightbox) - // Hides itself on slides with no clip, so no config check is needed here - - // the server omits `motionUrl` when `ipp.motionPhotos` is off. + // No config gate: the server omits `motionUrl` when motion photos are off. registerMotionButton(state.lightbox) if (state.metadataConfig.descriptionInCaption) registerCaption(state.lightbox) if (state.metadataConfig.sidebarHasContent) registerSidebar(state.lightbox) diff --git a/app/src/gallery/builder.ts b/app/src/gallery/builder.ts index e57d9b4..d68824c 100644 --- a/app/src/gallery/builder.ts +++ b/app/src/gallery/builder.ts @@ -79,8 +79,7 @@ export async function gallery (res: Response, share: SharedLink, openItem?: numb const fullUrl = zoomUpgrade && asset.type === AssetType.image && !requiresOriginal(asset) ? photoUrl(share.key, asset.id, ImageSize.fullsize) : undefined - // Motion photo clip. Reuses the video route; Immich authorises the clip - // under the same share key. + // Motion photo clip, served through the video route under the same key. const motionUrl = motionPhotos && asset.type === AssetType.image && asset.livePhotoVideoId ? videoUrl(share.key, asset.livePhotoVideoId) : undefined diff --git a/app/src/index.ts b/app/src/index.ts index 89fd8d4..2d434e0 100644 --- a/app/src/index.ts +++ b/app/src/index.ts @@ -131,18 +131,15 @@ async function resolveSharedAsset (req: Request, keyType: KeyType, allowMotion = // enforces this via the share key). const asset = resolved.link.assets.find(a => a.id === req.params.id) if (asset) return { ok: true, link: resolved.link, asset } - // A motion photo's clip is a hidden asset that never appears in the share's - // own asset list, but Immich authorises it under the same key. Accept it only - // for the video route, and only when a shared still actually points at it - - // the whitelist stays bounded by the share's contents. + // A motion photo's clip is a hidden asset outside the share's asset list. + // Serve it on the video route only, and only if a shared still points at it. if (allowMotion) { const parent = findMotionPhotoStill(resolved.link, req.params.id) if (parent) { return { ok: true, link: resolved.link, - // The clip streams inline from /video/playback, so the still's filename - // and mime must not follow it into Content-Disposition / sizing. + // Streams inline, so the still's filename / mime must not carry over. asset: { ...parent, id: req.params.id, type: AssetType.video, originalFileName: undefined, originalMimeType: undefined } } } diff --git a/app/src/share.ts b/app/src/share.ts index 8db2f55..cdc68ba 100644 --- a/app/src/share.ts +++ b/app/src/share.ts @@ -80,13 +80,9 @@ function expiryDateLocale (): string | undefined { } /** - * Find the shared still that a motion photo (Live Photo) clip belongs to. - * - * The clip is a separate, hidden Immich asset: it never appears in the share's - * own asset list, but Immich authorises it under the same shared-link key - * (`checkSharedLinkAccess` whitelists each shared asset's `livePhotoVideoId`). - * Matching against the share's own assets is what keeps the set of ids IPP will - * serve bounded by the share's contents. + * Find the shared still that a motion photo (Live Photo) clip belongs to. The + * clip is a hidden asset that Immich authorises under the same share key; + * requiring a shared still to point at it keeps the ids IPP serves bounded. */ export function findMotionPhotoStill (share: SharedLink, clipId: string): Asset | undefined { if (!clipId) return undefined diff --git a/app/src/types.ts b/app/src/types.ts index 10492aa..1256cc9 100644 --- a/app/src/types.ts +++ b/app/src/types.ts @@ -61,9 +61,7 @@ export interface Asset { height?: number; // Base64-encoded thumbhash for tasteful blur placeholders during lazy-load thumbhash?: string; - // Motion photo (Live Photo) clip. A separate, hidden Immich asset; the same - // shared-link key authorises it (Immich's checkSharedLinkAccess whitelists - // each shared asset's livePhotoVideoId alongside the asset itself). + // Motion photo (Live Photo) clip: a hidden asset authorised by the same key livePhotoVideoId?: string; // True for album assets enumerated via the timeline API, which give us only // grid fields (id, type, ratio, thumbhash, isTrashed, fileCreatedAt). Their diff --git a/app/tests/motionPhoto.test.ts b/app/tests/motionPhoto.test.ts index 42e5884..f0fa584 100644 --- a/app/tests/motionPhoto.test.ts +++ b/app/tests/motionPhoto.test.ts @@ -6,13 +6,9 @@ import { findMotionPhotoStill } from '../src/share' import { gallery } from '../src/gallery/builder' /* - Motion photo (Live Photo) support. Two rules worth pinning down: the set of - clip ids the video route will serve stays bounded by the share's own assets, - and `motionUrl` reaches the client only for images that have a clip, and only - while `ipp.motionPhotos` is on. - - The builder reads config through config/access, so mock that module and set - options per test rather than loading a real config file. + Motion photos: clip ids stay bounded by the share's own assets, and + `motionUrl` is emitted only for images with a clip while `ipp.motionPhotos` + is on. Config is mocked per test rather than loaded from a file. */ const cfg: Record = {} vi.mock('../src/config/access', () => ({ diff --git a/docs/config/ipp-options.md b/docs/config/ipp-options.md index 49d716e..59c3a39 100644 --- a/docs/config/ipp-options.md +++ b/docs/config/ipp-options.md @@ -61,9 +61,9 @@ Highest quality the lightbox loads when you zoom in past fit-to-screen. **Type:** `bool` ยท **Default:** `true` -Show motion photos (Live Photos) - an indicator on the gallery thumbnail, and a toggle in the lightbox that plays the photo's short clip and returns to the still when it ends. +Show motion photos (Live Photos) - an indicator on the gallery thumbnail, and a toggle in the lightbox that plays the photo's short clip and returns to the still when it ends. The toggle stays on: each motion photo the visitor moves to plays its clip automatically until they switch it off. -The clip is only fetched when a visitor presses the toggle, so leaving this on costs no extra bandwidth for visitors who never use it. Set to `false` to serve motion photos as plain stills: +Clips are only fetched while the toggle is on, so leaving this on costs no extra bandwidth for visitors who never use it. Set to `false` to serve motion photos as plain stills: ```json {