From 2a5580e5a2e59547c66b787430304b673630c18f Mon Sep 17 00:00:00 2001 From: Alan Grainger <16197738+alangrainger@users.noreply.github.com> Date: Thu, 20 Aug 2026 07:35:49 +1200 Subject: [PATCH] #281 refinements: transcoded filename extensions, allowDownload:2 caveats in docs --- app/src/gallery/filename.ts | 15 ++++++++-- app/src/stream/asset.ts | 7 ++++- app/src/stream/download.ts | 12 ++++++-- app/tests/downloadFilename.test.ts | 45 ++++++++++++++++++++++++++++++ docs/config/ipp-options.md | 9 ++++++ 5 files changed, 81 insertions(+), 7 deletions(-) create mode 100644 app/tests/downloadFilename.test.ts diff --git a/app/src/gallery/filename.ts b/app/src/gallery/filename.ts index 1329523..705f00e 100644 --- a/app/src/gallery/filename.ts +++ b/app/src/gallery/filename.ts @@ -61,10 +61,17 @@ function withMimeExtension (filename: string, mime: string | undefined): string * @param asset * @param [servedSize] - what size Immich will actually serve. Defaults to * ImageSize.original (the bytes match the original asset). + * @param [servedMimeOverride] - actual MIME of the served bytes when they + * differ from the original (a `/video/playback` transcode). Ignored when it + * doesn't map to a known extension, so an unrecognised content-type can't + * strip the filename's extension. */ -export function getFilename (asset: Asset, servedSize: ImageSize = ImageSize.original): string { +export function getFilename (asset: Asset, servedSize: ImageSize = ImageSize.original, servedMimeOverride?: string): string { + const override = mimeToExt(servedMimeOverride) ? servedMimeOverride : undefined let servedMime: string | undefined - if (servedSize === ImageSize.original) { + if (override) { + servedMime = override + } else if (servedSize === ImageSize.original) { servedMime = asset.originalMimeType } else if (servedSize === ImageSize.thumbnail) { servedMime = 'image/webp' @@ -83,7 +90,9 @@ export function getFilename (asset: Asset, servedSize: ImageSize = ImageSize.ori // By default, use the asset's original filename const cleanName = asset.originalFileName ? sanitize(asset.originalFileName) : '' if (!cleanName) return withMimeExtension(asset.id, servedMime) - const stem = servedSize === ImageSize.original + // Keep the original extension only when the served bytes really are the + // original file; a size downgrade or playback transcode replaces it. + const stem = servedSize === ImageSize.original && !override ? cleanName : cleanName.replace(/\.[a-zA-Z0-9]{2,5}$/, '') return withMimeExtension(stem, servedMime) diff --git a/app/src/stream/asset.ts b/app/src/stream/asset.ts index 6be31b5..8fabf0b 100644 --- a/app/src/stream/asset.ts +++ b/app/src/stream/asset.ts @@ -79,7 +79,12 @@ export async function assetBuffer (req: IncomingShareRequest, res: Response, ass } if (attachment && asset.originalFileName) { - const filename = encodeURI(getFilename(asset, servedSize)) + // Playback downloads serve Immich's transcode, so the filename extension + // must follow the response's content-type, not the original file's. + const playbackMime = useVideoPlayback + ? (data.headers.get('content-type') || '').split(';')[0].trim() || undefined + : undefined + const filename = encodeURI(getFilename(asset, servedSize, playbackMime)) res.setHeader('Content-Disposition', `attachment; filename*=UTF-8''${filename}`) } headerList.forEach(header => { diff --git a/app/src/stream/download.ts b/app/src/stream/download.ts index 96485b7..a80d645 100644 --- a/app/src/stream/download.ts +++ b/app/src/stream/download.ts @@ -48,7 +48,7 @@ export async function sweepStaleStagingDirs (maxAgeMs = 60 * 60 * 1000) { } } -type StagedAsset = { tempfile: string, asset: Asset, endpoint: ImageEndpoint } +type StagedAsset = { tempfile: string, asset: Asset, endpoint: ImageEndpoint, servedMime?: string } type Failure = { asset: Asset, url: string, status?: number, error?: unknown } type StageOutcome = StagedAsset | { failure: Failure } | null @@ -171,7 +171,7 @@ async function archiveStaged (archive: Archiver, stages: Promise[] break } // archive.file queues the entry; archiver lazily opens and reads it. - archive.file(result.tempfile, { name: getFilename(result.asset, result.endpoint.servedSize) }) + archive.file(result.tempfile, { name: getFilename(result.asset, result.endpoint.servedSize, result.servedMime) }) } // After abort, wait for any in-flight stages to settle before we delete @@ -216,12 +216,18 @@ async function stageOne (share: SharedLink, asset: Asset, index: number, options // so recover them from the headers we already fetched - no extra calls. const stagedAsset = asset.originalFileName ? asset : enrichFromHeaders(asset, fetched.response) + // Playback-fallback downloads serve Immich's transcode; carry the response + // content-type so the zip entry's extension matches the actual bytes. + const servedMime = endpoint.subpath === '/video/playback' + ? (fetched.response.headers.get('content-type') || '').split(';')[0].trim() || undefined + : undefined + // Use the array index in the path so we never collide on duplicate IDs. const tempfile = join(options.stagingDir, `${index}-${asset.id}`) const streamed = await streamBodyToTempFile(fetched.response, tempfile, options.idleTimeoutMs) if ('failure' in streamed) return { failure: { asset, url, error: streamed.failure } } - return { tempfile, asset: stagedAsset, endpoint } + return { tempfile, asset: stagedAsset, endpoint, servedMime } } /** diff --git a/app/tests/downloadFilename.test.ts b/app/tests/downloadFilename.test.ts new file mode 100644 index 0000000..95fb03e --- /dev/null +++ b/app/tests/downloadFilename.test.ts @@ -0,0 +1,45 @@ +import { describe, it, expect, vi } from 'vitest' +import { AssetType, ImageSize, KeyType } from '../src/types' +import type { Asset } from '../src/types' +import { getFilename } from '../src/gallery/filename' + +/* +getFilename reads `ipp.downloadedFilename` via getConfigOption; mock the +config-access module so tests exercise the default (original filename) mode +without loading a real config file. +*/ +vi.mock('../src/config/access', () => ({ + getConfigOption: (_path: string, fallback?: unknown) => fallback +})) + +function videoAsset (originalFileName: string, originalMimeType = 'video/x-msvideo'): Asset { + return { + id: 'asset-id', + key: 'k', + keyType: KeyType.key, + type: AssetType.video, + isTrashed: false, + originalFileName, + originalMimeType + } +} + +describe('getFilename servedMime override (playback-fallback downloads)', () => { + it('swaps the extension to match the transcoded bytes', () => { + expect(getFilename(videoAsset('clip.avi'), ImageSize.original, 'video/mp4')).toBe('clip.mp4') + expect(getFilename(videoAsset('holiday.MOV', 'video/quicktime'), ImageSize.original, 'video/mp4')).toBe('holiday.mp4') + }) + + it('keeps the name unchanged when the served mime matches the original', () => { + expect(getFilename(videoAsset('clip.mp4', 'video/mp4'), ImageSize.original, 'video/mp4')).toBe('clip.mp4') + }) + + it('ignores an unrecognised content-type instead of stripping the extension', () => { + expect(getFilename(videoAsset('clip.avi'), ImageSize.original, 'application/octet-stream')).toBe('clip.avi') + expect(getFilename(videoAsset('clip.avi'), ImageSize.original, undefined)).toBe('clip.avi') + }) + + it('does not affect ordinary original downloads', () => { + expect(getFilename(videoAsset('clip.avi'), ImageSize.original)).toBe('clip.avi') + }) +}) diff --git a/docs/config/ipp-options.md b/docs/config/ipp-options.md index 22ca756..d9fefe8 100644 --- a/docs/config/ipp-options.md +++ b/docs/config/ipp-options.md @@ -66,6 +66,15 @@ Show the download UI - the "download all" zip, the multi-select download, and th The bulk-zip and per-asset buttons can be toggled independently once downloads are allowed - see [`gallery.showDownloadZip`](/config/gallery#showdownloadzip) and [`lightbox.showDownload`](/config/lightbox#showdownload). +> [!NOTE] +> With `2`, IPP shows the download UI even on shares whose **own** download toggle in Immich is off - but Immich still refuses to serve those shares' original files, so IPP works around it where it can: +> +> - **Videos** are downloaded as the transcoded playback file instead of the original (the same stream the visitor can already watch). The filename extension follows the transcoded format, typically `.mp4`. +> - **Photos** download normally as long as [`maxDownloadQuality`](#maxdownloadquality) is below `original`; with `maxDownloadQuality: original` they fail, because the original file is exactly what Immich is refusing to serve. +> - **Gifs** always download as the original file (their preview is a static frame), so they fail on these shares. +> +> To guarantee full-quality downloads of everything, leave the share's download permission on in Immich. + ## `downloadFromImmichConcurrencyLimit` **Type:** `int` ยท **Default:** `20`