#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
+16 -1
View File
@@ -39,6 +39,8 @@ const sharedLinkResponse = (order?: string) => ({
}
})
const MOTION_CLIP_ID = 'dddddddd-dddd-dddd-dddd-dddddddddddd'
const bucketsResponse = [{ timeBucket: '2026-06-01', count: 3 }]
// Columnar (struct-of-arrays). Index 1 is trashed and must be filtered out.
@@ -53,7 +55,9 @@ const bucketResponse = {
thumbhash: ['hashA', null, 'hashC'],
isTrashed: [false, true, false],
fileCreatedAt: ['2026-06-03T00:00:00.000Z', '2026-06-02T00:00:00.000Z', '2026-06-01T00:00:00.000Z'],
localOffsetHours: [5.5, -8, 0]
localOffsetHours: [5.5, -8, 0],
// Index 0 is a motion photo; the others are ordinary assets.
livePhotoVideoId: [MOTION_CLIP_ID, null, null]
}
function routeFetch (sharedLink: unknown) {
@@ -101,6 +105,17 @@ describe('album timeline enumeration (Immich 3.0)', () => {
expect(assets[0].width!).toBeGreaterThan(assets[0].height!)
})
it('carries the motion photo clip id through from the bucket', async () => {
// Album shares get livePhotoVideoId for free from the timeline response,
// so motion photos cost no extra upstream requests here.
vi.stubGlobal('fetch', routeFetch(sharedLinkResponse()))
const result = await getShareByKey(uniqueKey(), undefined, KeyType.key)
const assets = result.link!.assets
expect(assets[0].livePhotoVideoId).toBe(MOTION_CLIP_ID)
// null in the columnar response becomes undefined, as with thumbhash
expect(assets[1].livePhotoVideoId).toBeUndefined()
})
it('synthesises localDateTime from fileCreatedAt + localOffsetHours', async () => {
vi.stubGlobal('fetch', routeFetch(sharedLinkResponse()))
const result = await getShareByKey(uniqueKey(), undefined, KeyType.key)
+19 -4
View File
@@ -34,6 +34,14 @@ function galleryProps (item: Partial<GalleryItem>): GalleryProps {
const payload = '</script><script>alert(1)</script>'
/** Render a gallery and parse back the `#ipp-init` JSON block the client reads. */
function initParams (props: GalleryProps) {
const html = renderPage(h(Gallery, props))
const match = html.match(/<script type="application\/json" id="ipp-init">(.*?)<\/script>/s)
if (!match) throw new Error('No init JSON block in the rendered gallery')
return JSON.parse(match[1])
}
describe('gallery init JSON escaping', () => {
it('neutralises </script> in a crafted download filename', () => {
const html = renderPage(h(Gallery, galleryProps({ downloadFilename: payload })))
@@ -50,10 +58,17 @@ describe('gallery init JSON escaping', () => {
})
it('still produces JSON the client can parse back to the same items', () => {
const html = renderPage(h(Gallery, galleryProps({ downloadFilename: payload })))
const match = html.match(/<script type="application\/json" id="ipp-init">(.*?)<\/script>/s)
expect(match).not.toBeNull()
const params = JSON.parse(match![1])
// initParams throws if the block is missing, so reaching the assertion
// also proves the block is still there and still parses.
const params = initParams(galleryProps({ downloadFilename: payload }))
expect(params.items[0].downloadFilename).toBe(payload)
})
it('serialises motionUrl for a motion photo, and omits the key otherwise', () => {
const motionUrl = '/share/video/k/dddddddd-dddd-dddd-dddd-dddddddddddd'
expect(initParams(galleryProps({ motionUrl })).items[0].motionUrl).toBe(motionUrl)
// Absent (not null / empty string), so the client's `item.motionUrl` check
// and the tile badge stay off for ordinary photos.
expect(initParams(galleryProps({})).items[0]).not.toHaveProperty('motionUrl')
})
})
+104
View File
@@ -0,0 +1,104 @@
import { describe, it, expect, vi, beforeEach } from 'vitest'
import { AssetType, KeyType } from '../src/types'
import type { Asset, SharedLink } from '../src/types'
import type { Response } from 'express-serve-static-core'
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.
*/
const cfg: Record<string, unknown> = {}
vi.mock('../src/config/access', () => ({
getConfigOption: (path: string, fallback?: unknown) => (path in cfg ? cfg[path] : fallback),
getNumericConfigOption: (path: string, fallback: number) => (path in cfg ? Number(cfg[path]) : fallback)
}))
const STILL_ID = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa'
const CLIP_ID = 'dddddddd-dddd-dddd-dddd-dddddddddddd'
const UNRELATED_ID = 'eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee'
function asset (overrides: Partial<Asset> = {}): Asset {
return {
id: STILL_ID,
key: 'share-key',
keyType: KeyType.key,
type: AssetType.image,
isTrashed: false,
...overrides
}
}
function share (assets: Asset[]): SharedLink {
return {
key: 'share-key',
keyType: KeyType.key,
type: 'INDIVIDUAL',
assets,
expiresAt: null
}
}
/** Render a gallery for these assets and return the items the client receives. */
async function renderItems (assets: Asset[]) {
let html = ''
const res = {
req: { protocol: 'https', headers: { host: 'example.com' } },
header: () => {},
send: (body: string) => { html = body }
} as unknown as Response
await gallery(res, share(assets))
const match = html.match(/<script type="application\/json" id="ipp-init">(.*?)<\/script>/s)
if (!match) throw new Error('No init JSON block in the rendered gallery')
return JSON.parse(match[1]).items as Array<Record<string, unknown>>
}
describe('motion photo clip resolution', () => {
it('resolves the shared still that a clip id belongs to', () => {
const link = share([asset({ livePhotoVideoId: CLIP_ID }), asset({ id: UNRELATED_ID })])
expect(findMotionPhotoStill(link, CLIP_ID)?.id).toBe(STILL_ID)
})
it('does not resolve an id no shared asset points at', () => {
const link = share([asset({ livePhotoVideoId: CLIP_ID })])
expect(findMotionPhotoStill(link, UNRELATED_ID)).toBeUndefined()
})
it('does not match assets that have no clip', () => {
// Guards the undefined === undefined case: an empty id must not resolve to
// the first ordinary asset in the share.
const link = share([asset(), asset({ id: UNRELATED_ID })])
expect(findMotionPhotoStill(link, '')).toBeUndefined()
})
})
describe('motionUrl in the gallery init JSON', () => {
beforeEach(() => {
for (const key of Object.keys(cfg)) delete cfg[key]
})
it('emits a clip playback URL for a motion photo only', async () => {
const items = await renderItems([
asset({ livePhotoVideoId: CLIP_ID }),
asset({ id: UNRELATED_ID }),
// A video can never be the still half of a motion photo; `needsDetail`
// keeps the builder from probing Immich for its content-type.
asset({ id: CLIP_ID, type: AssetType.video, livePhotoVideoId: CLIP_ID, needsDetail: true })
])
expect(items[0].motionUrl).toBe('/share/video/share-key/' + CLIP_ID)
expect(items[1]).not.toHaveProperty('motionUrl')
expect(items[2]).not.toHaveProperty('motionUrl')
})
it('omits motionUrl when ipp.motionPhotos is off', async () => {
cfg['ipp.motionPhotos'] = false
const items = await renderItems([asset({ livePhotoVideoId: CLIP_ID })])
expect(items[0]).not.toHaveProperty('motionUrl')
})
})