#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
+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()
}
})
})
}