From 4021c66cec793ce800d0103012a788f6cb55b9fd Mon Sep 17 00:00:00 2001 From: trecoool Date: Mon, 24 Aug 2026 14:35:28 +0200 Subject: [PATCH] #200 motion photo (Live Photo) support Show a badge on the gallery thumbnail and a lightbox toggle that plays the photo's clip over the still, matching Immich's own viewer. The clip is a hidden Immich asset, but the existing share key already authorises it - checkSharedLinkAccess whitelists each shared asset's livePhotoVideoId - so no new upstream access is involved. The video route accepts a clip id only when a shared still points at it. Both enumeration paths already carry the field (AssetResponseDto for individual shares, TimeBucketAssetResponseDto for album buckets), so album shares cost no extra upstream requests. Gated by ipp.motionPhotos (default true). The clip is preload="none" and is only fetched when a visitor presses the toggle. --- app/config.json | 1 + app/public/photoswipe-overrides.css | 22 ++++++ app/public/style.css | 18 +++++ app/src/client/icons.ts | 8 ++ app/src/client/lightbox-ui.ts | 112 +++++++++++++++++++++++++++- app/src/client/lightbox.ts | 10 ++- app/src/client/tiles.ts | 17 +++-- app/src/gallery/builder.ts | 7 ++ app/src/immich.ts | 1 + app/src/index.ts | 26 +++++-- app/src/share.ts | 16 +++- app/src/shared/types.ts | 3 + app/src/types.ts | 6 ++ app/tests/albumTimeline.test.ts | 17 ++++- app/tests/galleryInitJson.test.ts | 23 +++++- app/tests/motionPhoto.test.ts | 104 ++++++++++++++++++++++++++ docs/config/ipp-options.md | 16 ++++ 17 files changed, 384 insertions(+), 23 deletions(-) create mode 100644 app/tests/motionPhoto.test.ts diff --git a/app/config.json b/app/config.json index 86d6464..1bef94d 100644 --- a/app/config.json +++ b/app/config.json @@ -6,6 +6,7 @@ }, "maxDownloadQuality": "original", "maxZoomQuality": "preview", + "motionPhotos": true, "downloadedFilename": 0, "allowDownload": 0, "downloadFromImmichConcurrencyLimit": 20, diff --git a/app/public/photoswipe-overrides.css b/app/public/photoswipe-overrides.css index 6a401fb..1fe3881 100644 --- a/app/public/photoswipe-overrides.css +++ b/app/public/photoswipe-overrides.css @@ -139,6 +139,28 @@ 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. */ +.pswp__motion-video { + position: absolute; + inset: 0; + width: 100%; + height: 100%; + object-fit: contain; + pointer-events: none; /* PhotoSwipe keeps handling drag / zoom / swipe */ +} + +.pswp__zoom-wrap.pswp--motion-playing .pswp__img { + opacity: 0; +} + +/* PhotoSwipe's `.pswp__button { display: block }` outranks the browser's + `[hidden]` rule, so a toolbar button that hides itself needs this. */ +.pswp__button[hidden] { + display: none; +} + /* Smooth backdrop fade in/out to match Immich's open/close feel */ .pswp__bg { transition: opacity var(--pswp-transition-duration); diff --git a/app/public/style.css b/app/public/style.css index 9738ebc..c4044a7 100644 --- a/app/public/style.css +++ b/app/public/style.css @@ -213,6 +213,24 @@ html, body { opacity: 1; } +/* Motion photo (Live Photo) indicator, top-right to match Immich's grid */ +.motion-icon { + position: absolute; + top: 4px; + right: 4px; + width: 24px; + height: 24px; + color: #fff; + opacity: 0.85; + filter: drop-shadow(0 1px 2px rgba(0, 0, 0, 0.6)); + pointer-events: none; +} + +.motion-icon svg { + width: 100%; + height: 100%; +} + /* ===== Header (title + asset count + download action) ===== */ #header { diff --git a/app/src/client/icons.ts b/app/src/client/icons.ts index 5e36f63..642aee2 100644 --- a/app/src/client/icons.ts +++ b/app/src/client/icons.ts @@ -16,6 +16,10 @@ export const ICON_FULLSCREEN = ' void } @@ -161,3 +170,100 @@ export function registerFullscreenButton (lightbox: LightboxInstance) { }) }) } + +// Set on the zoom wrap while a motion photo's clip is painting, so CSS can +// fade the still out underneath it. +const MOTION_PLAYING_CLASS = 'pswp--motion-playing' + +/** + * The `.pswp__zoom-wrap` of the slide currently on screen. Mounting the clip + * inside it is what makes pan / zoom free: that element carries PhotoSwipe's + * transform, so an `inset: 0` child stays pinned to the photo without any + * geometry tracking of our own. + */ +function currentZoomWrap (pswp: PswpInstance): HTMLElement | null { + const container = pswp.currSlide?.container + if (container instanceof HTMLElement) return container + // Fallback for PhotoSwipe builds that don't expose the slide off `pswp`. + const fallback = pswp.element.querySelector('.pswp__item[aria-hidden="false"] .pswp__zoom-wrap') + return fallback instanceof HTMLElement ? fallback : null +} + +/** + * Register the motion photo (Live Photo) toggle: swaps the still for its short + * clip and returns to the still when the clip ends. The button hides itself on + * slides with no clip, and the server omits `motionUrl` altogether when + * `ipp.motionPhotos` is off, so it then never appears at all. + * + * The `` whose `src` - * is held back until the tile enters the viewport (see - * `loadVisibleTiles`), a play overlay for videos, and a selection - * checkmark + long-press handler if the share allows downloads. + * is held back until the tile enters the viewport (see `loadVisibleTiles`), + * a play overlay for videos, a corner badge for motion photos, and a + * selection checkmark + long-press handler if the share allows downloads. * * Click opens the lightbox unless selection mode is active, in which case * it toggles the item's selection. @@ -82,6 +82,13 @@ export function createTile (index: number): HTMLAnchorElement { a.appendChild(playIcon) } + if (item.motionUrl) { + const motion = document.createElement('div') + motion.className = 'motion-icon' + motion.innerHTML = ICON_MOTION_BADGE + a.appendChild(motion) + } + // Selection checkmark (rendered only when select mode is even possible - // i.e. when the page included the toolbar element) if (state.toolbarEl) { diff --git a/app/src/gallery/builder.ts b/app/src/gallery/builder.ts index 8cd7892..e57d9b4 100644 --- a/app/src/gallery/builder.ts +++ b/app/src/gallery/builder.ts @@ -48,6 +48,7 @@ export async function gallery (res: Response, share: SharedLink, openItem?: numb // share's own download toggle (`share.allowDownload`) is on. Deliberately // independent of IPP's `allowDownload` config. const zoomUpgrade = getConfigOption('ipp.maxZoomQuality', 'preview') === 'fullsize' && share.allowDownload !== false + const motionPhotos = !!getConfigOption('ipp.motionPhotos', true) const descriptionInCaption = shareMetadataAllowed && !!getConfigOption('ipp.showMetadata.description.caption', false) const descriptionInSidebar = shareMetadataAllowed && !!getConfigOption('ipp.showMetadata.description.sidebar', false) const sidebarHasContent = shareMetadataAllowed && (descriptionInSidebar || metadataGroupActive('exif') || metadataGroupActive('location')) @@ -78,6 +79,11 @@ 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. + const motionUrl = motionPhotos && asset.type === AssetType.image && asset.livePhotoVideoId + ? videoUrl(share.key, asset.livePhotoVideoId) + : undefined // Plain text; the client uses textContent so no escaping needed here. // Description is included if EITHER surface (caption or sidebar) wants it. const descriptionEnabled = descriptionInCaption || descriptionInSidebar @@ -95,6 +101,7 @@ export async function gallery (res: Response, share: SharedLink, openItem?: numb thumbnailUrl, downloadUrl, videoData, + motionUrl, description: itemDescription || undefined, downloadFilename: downloadFilename(asset), width, diff --git a/app/src/immich.ts b/app/src/immich.ts index 89d5a22..19b68c9 100644 --- a/app/src/immich.ts +++ b/app/src/immich.ts @@ -411,6 +411,7 @@ function timelineBucketToAssets (bucket: TimelineBucketAssets): Asset[] { // timeline does when grouping by local day / month. localDateTime: localDateTimeFromOffset(fileCreatedAt, bucket.localOffsetHours?.[i]), thumbhash: bucket.thumbhash?.[i] || undefined, + livePhotoVideoId: bucket.livePhotoVideoId?.[i] || undefined, width, height, needsDetail: true diff --git a/app/src/index.ts b/app/src/index.ts index 7805638..1f7b30b 100644 --- a/app/src/index.ts +++ b/app/src/index.ts @@ -23,7 +23,7 @@ import { Asset, AssetType, ImageSize, KeyType, SharedLink } from './types' import { getConfigOption } from './config/access' import { loadConfig } from './config/loader' import { addResponseHeaders, asyncHandler, errorHandler } from './http' -import { canDownload } from './share' +import { canDownload, findMotionPhotoStill } from './share' import { toString } from './utils/text' import { decrypt, encrypt } from './encrypt' import { respondToInvalidRequest } from './invalidRequestHandler' @@ -121,7 +121,7 @@ async function resolveShare (req: Request, keyType: KeyType): Promise { +async function resolveSharedAsset (req: Request, keyType: KeyType, allowMotion = false): Promise { if (!isId(req.params.id)) { return { ok: false, status: 404, reason: 'Invalid ID for ' + req.path } } @@ -130,10 +130,24 @@ async function resolveSharedAsset (req: Request, keyType: KeyType): Promise a.id === req.params.id) - if (!asset) { - return { ok: false, status: 404, reason: 'Asset not found in share' } + 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. + 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. + asset: { ...parent, id: req.params.id, type: AssetType.video, originalFileName: undefined, originalMimeType: undefined } + } + } } - return { ok: true, link: resolved.link, asset } + return { ok: false, status: 404, reason: 'Asset not found in share' } } /* @@ -253,7 +267,7 @@ app.get('/share/:type(photo|video)/:key/:id/:size?', decodeCookie, asyncHandler( // The resolved asset gives assetBuffer access to originalMimeType and // originalFileName (needed for Content-Disposition and for requiresOriginal // to recognise videos/animated images and bypass the preview downgrade). - const resolved = await resolveSharedAsset(req, KeyType.key) + const resolved = await resolveSharedAsset(req, KeyType.key, req.params.type === 'video') if (!resolved.ok) { // Password-protected: redirect to the share page so the visitor gets the // unlock prompt, rather than returning an error. diff --git a/app/src/share.ts b/app/src/share.ts index d48ddab..8db2f55 100644 --- a/app/src/share.ts +++ b/app/src/share.ts @@ -1,4 +1,4 @@ -import { DownloadAll, SharedLink } from './types' +import { Asset, DownloadAll, SharedLink } from './types' import { getConfigOption } from './config/access' import dayjs from 'dayjs' @@ -78,3 +78,17 @@ function expiryDateLocale (): string | undefined { return 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. + */ +export function findMotionPhotoStill (share: SharedLink, clipId: string): Asset | undefined { + if (!clipId) return undefined + return share.assets.find(asset => asset.livePhotoVideoId === clipId) +} diff --git a/app/src/shared/types.ts b/app/src/shared/types.ts index e774adf..6798e9c 100644 --- a/app/src/shared/types.ts +++ b/app/src/shared/types.ts @@ -45,6 +45,9 @@ export interface GalleryItem { // Pre-stringified JSON describing the video source (used to build a