Merge pull request #286 from trecoool/feat/motion-photos

This commit is contained in:
Alan Grainger
2026-09-17 21:34:22 +12:00
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 {