#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.
This commit is contained in:
trecoool
2026-08-24 14:35:28 +02:00
parent 8c2c2219ce
commit 4021c66cec
17 changed files with 384 additions and 23 deletions
+8
View File
@@ -16,6 +16,10 @@ export const ICON_FULLSCREEN = '<svg class="pswp__icn" viewBox="0 0 24 24" aria-
export const ICON_FULLSCREEN_EXIT = '<svg class="pswp__icn" viewBox="0 0 24 24" aria-hidden="true"><path fill="currentColor" d="M14,14H19V16H16V19H14V14M5,14H10V19H8V16H5V14M8,5H10V10H5V8H8V5M19,8V10H14V5H16V8H19Z"/></svg>'
export const ICON_INFO = '<svg class="pswp__icn" viewBox="0 0 24 24" aria-hidden="true"><path fill="currentColor" d="M11,9H13V7H11M12,20C7.59,20 4,16.41 4,12C4,7.59 7.59,4 12,4C16.41,4 20,7.59 20,12C20,16.41 16.41,20 12,20M12,2A10,10 0 0,0 2,12A10,10 0 0,0 12,22A10,10 0 0,0 22,12A10,10 0 0,0 12,2M11,17H13V11H11V17Z"/></svg>'
export const ICON_BACK = '<svg class="pswp__icn" viewBox="0 0 24 24" aria-hidden="true"><path fill="currentColor" d="M20,11V13H8L13.5,18.5L12.08,19.92L4.16,12L12.08,4.08L13.5,5.5L8,11H20Z"/></svg>'
// Motion photo (Live Photo) toggle - play when stopped, pause while the
// clip is running. Same pair Immich uses in its own asset viewer.
export const ICON_MOTION_PLAY = '<svg class="pswp__icn" viewBox="0 0 24 24" aria-hidden="true"><path fill="currentColor" d="M10 16.5L16 12L10 7.5M22 12C22 6.46 17.54 2 12 2C10.83 2 9.7 2.19 8.62 2.56L9.32 4.5C10.17 4.16 11.06 3.97 12 3.97C16.41 3.97 20.03 7.59 20.03 12C20.03 16.41 16.41 20.03 12 20.03C7.59 20.03 3.97 16.41 3.97 12C3.97 11.06 4.16 10.12 4.5 9.28L2.56 8.62C2.19 9.7 2 10.83 2 12C2 17.54 6.46 22 12 22C17.54 22 22 17.54 22 12M5.47 3.97C6.32 3.97 7 4.68 7 5.47C7 6.32 6.32 7 5.47 7C4.68 7 3.97 6.32 3.97 5.47C3.97 4.68 4.68 3.97 5.47 3.97Z"/></svg>'
export const ICON_MOTION_PAUSE = '<svg class="pswp__icn" viewBox="0 0 24 24" aria-hidden="true"><path fill="currentColor" d="M22 12C22 6.46 17.54 2 12 2C10.83 2 9.7 2.19 8.62 2.56L9.32 4.5C10.17 4.16 11.06 3.97 12 3.97C16.41 3.97 20.03 7.59 20.03 12C20.03 16.41 16.41 20.03 12 20.03C7.59 20.03 3.97 16.41 3.97 12C3.97 11.06 4.16 10.12 4.5 9.28L2.56 8.62C2.19 9.7 2 10.83 2 12C2 17.54 6.46 22 12 22C17.54 22 22 17.54 22 12M5.47 7C4.68 7 3.97 6.32 3.97 5.47C3.97 4.68 4.68 3.97 5.47 3.97C6.32 3.97 7 4.68 7 5.47C7 6.32 6.32 7 5.47 7M9 9H11V15H9M13 9H15V15H13"/></svg>'
export const ICON_CLOSE = '<svg viewBox="0 0 24 24" aria-hidden="true"><path fill="currentColor" d="M19,6.41L17.59,5L12,10.59L6.41,5L5,6.41L10.59,12L5,17.59L6.41,19L12,13.41L17.59,19L19,17.59L13.41,12L19,6.41Z"/></svg>'
// Sidebar field rows (file / camera / lens / map)
@@ -27,3 +31,7 @@ export const ICON_MAP = '<svg viewBox="0 0 24 24" aria-hidden="true"><path fill=
// Check glyph shown inside selected tiles' checkmark circle
export const CHECK_SVG = '<svg viewBox="0 0 24 24" aria-hidden="true"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"/></svg>'
// Motion photo indicator drawn in the corner of a gallery tile. Same glyph
// as ICON_MOTION_PLAY without PhotoSwipe's `pswp__icn` sizing class.
export const ICON_MOTION_BADGE = '<svg viewBox="0 0 24 24" aria-hidden="true"><path fill="currentColor" d="M10 16.5L16 12L10 7.5M22 12C22 6.46 17.54 2 12 2C10.83 2 9.7 2.19 8.62 2.56L9.32 4.5C10.17 4.16 11.06 3.97 12 3.97C16.41 3.97 20.03 7.59 20.03 12C20.03 16.41 16.41 20.03 12 20.03C7.59 20.03 3.97 16.41 3.97 12C3.97 11.06 4.16 10.12 4.5 9.28L2.56 8.62C2.19 9.7 2 10.83 2 12C2 17.54 6.46 22 12 22C17.54 22 22 17.54 22 12M5.47 3.97C6.32 3.97 7 4.68 7 5.47C7 6.32 6.32 7 5.47 7C4.68 7 3.97 6.32 3.97 5.47C3.97 4.68 4.68 3.97 5.47 3.97Z"/></svg>'
+109 -3
View File
@@ -1,9 +1,16 @@
// PhotoSwipe UI element registrations: back button, caption (description),
// download button, fullscreen toggle. Each is gated by config or feature
// detection. The info sidebar lives in `sidebar.ts`.
// download button, fullscreen toggle, motion photo toggle. Each is gated by
// config or feature detection. The info sidebar lives in `sidebar.ts`.
import { state } from './state.js'
import { ICON_BACK, ICON_DOWNLOAD, ICON_FULLSCREEN, ICON_FULLSCREEN_EXIT } from './icons.js'
import {
ICON_BACK,
ICON_DOWNLOAD,
ICON_FULLSCREEN,
ICON_FULLSCREEN_EXIT,
ICON_MOTION_PAUSE,
ICON_MOTION_PLAY
} from './icons.js'
// PhotoSwipe types are not bundled with the project. These two interfaces
// describe just enough of the surface we touch to keep the rest of the file
@@ -23,6 +30,8 @@ interface PswpUiElementConfig {
interface PswpInstance {
currIndex: number
element: HTMLElement
// A slide's `container` is its `.pswp__zoom-wrap` element.
currSlide?: { container?: HTMLElement }
ui: {
registerElement: (config: PswpUiElementConfig) => 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 `<video>` is created on demand with `preload="none"`: nothing is fetched
* from Immich until a visitor actually presses the button.
*/
export function registerMotionButton (lightbox: LightboxInstance) {
lightbox.on('uiRegister', () => {
lightbox.pswp.ui.registerElement({
name: 'motion-button',
order: 6,
isButton: true,
html: ICON_MOTION_PLAY,
onInit: (el: HTMLElement, pswp: PswpInstance) => {
let video: HTMLVideoElement | 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
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 = () => {
const clip = video
if (!clip) return
video = null
clip.pause()
clip.parentElement?.classList.remove(MOTION_PLAYING_CLASS)
clip.remove()
update()
}
const play = () => {
const item = state.items[pswp.currIndex]
const wrap = currentZoomWrap(pswp)
if (!item?.motionUrl || !wrap) return
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.playsInline = true
clip.preload = 'none'
clip.src = item.motionUrl
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('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()
})
pswp.on('change', () => {
stop()
update()
})
pswp.on('destroy', stop)
update()
}
})
})
}
+7 -3
View File
@@ -1,6 +1,6 @@
// PhotoSwipe instantiation, data-source construction, history / hash
// navigation. Individual UI elements (caption, download, fullscreen,
// sidebar) live in lightbox-ui.ts and sidebar.ts.
// navigation. Individual UI elements (caption, download, fullscreen, motion
// photo, sidebar) live in lightbox-ui.ts and sidebar.ts.
// Runtime URL resolved by Express static, not a TS-resolvable module path.
// @ts-expect-error - browser-only ESM URL
@@ -13,7 +13,8 @@ import {
registerBackButton,
registerCaption,
registerDownloadButton,
registerFullscreenButton
registerFullscreenButton,
registerMotionButton
} from './lightbox-ui.js'
import { registerSidebar } from './sidebar.js'
import { registerLazyDetail } from './metadata.js'
@@ -238,6 +239,9 @@ 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.
registerMotionButton(state.lightbox)
if (state.metadataConfig.descriptionInCaption) registerCaption(state.lightbox)
if (state.metadataConfig.sidebarHasContent) registerSidebar(state.lightbox)
// Lazy album items load their exif / description / filename on open; this
+12 -5
View File
@@ -1,12 +1,12 @@
// Per-tile DOM construction: anchor, image, thumbhash blur background, video
// play icon, selection checkmark, click + long-press handlers.
// play icon, motion-photo badge, selection checkmark, click + long-press.
// Runtime URL resolved by Express static, not a TS-resolvable module path.
// @ts-expect-error - browser-only ESM URL
import { thumbHashToDataURL } from '/share/static/thumbhash/thumbhash.js' // eslint-disable-line import/no-absolute-path
import { state, LONG_PRESS_MS } from './state.js'
import { CHECK_SVG } from './icons.js'
import { CHECK_SVG, ICON_MOTION_BADGE } from './icons.js'
import { enterSelectMode, toggleSelection } from './selection.js'
import { openLightbox } from './lightbox.js'
@@ -39,9 +39,9 @@ function decodeThumbhash (base64: string): string | null {
* Positioning is taken from the precomputed `state.layout`.
*
* The tile shows the thumbhash blur as a background, an `<img>` 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) {
+7
View File
@@ -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,
+1
View File
@@ -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
+20 -6
View File
@@ -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<ShareResol
return { ok: true, link: share.link }
}
async function resolveSharedAsset (req: Request, keyType: KeyType): Promise<SharedAssetResolution> {
async function resolveSharedAsset (req: Request, keyType: KeyType, allowMotion = false): Promise<SharedAssetResolution> {
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<Shar
// Confirm the asset belongs to this share (defence in depth - Immich also
// enforces this via the share key).
const asset = resolved.link.assets.find(a => 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.
+15 -1
View File
@@ -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)
}
+3
View File
@@ -45,6 +45,9 @@ export interface GalleryItem {
// Pre-stringified JSON describing the video source (used to build a <video>
// element for video slides in the PhotoSwipe lightbox)
videoData?: string
// Playback URL for a motion photo's clip, when the asset has one and
// ipp.motionPhotos is enabled. Drives the tile badge + lightbox toggle.
motionUrl?: string
// Immich uses "description" but this is our caption
description?: string
downloadFilename: string
+6
View File
@@ -61,6 +61,10 @@ 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).
livePhotoVideoId?: string;
// True for album assets enumerated via the timeline API, which give us only
// grid fields (id, type, ratio, thumbhash, isTrashed, fileCreatedAt). Their
// exif / originalFileName / description are fetched lazily when the asset is
@@ -101,6 +105,8 @@ export interface TimelineBucketAssets {
// UTC offset (hours, may be fractional) at the time each photo was taken.
// Applying it to fileCreatedAt yields the photographer's local time.
localOffsetHours: number[];
// Motion photo (Live Photo) clip id; null for ordinary assets.
livePhotoVideoId: (string | null)[];
}
export interface SharedLink {