#281 refinements: transcoded filename extensions, allowDownload:2 caveats in docs

This commit is contained in:
Alan Grainger
2026-08-20 07:35:49 +12:00
parent a2776f9933
commit 2a5580e5a2
5 changed files with 81 additions and 7 deletions
+12 -3
View File
@@ -61,10 +61,17 @@ function withMimeExtension (filename: string, mime: string | undefined): string
* @param asset * @param asset
* @param [servedSize] - what size Immich will actually serve. Defaults to * @param [servedSize] - what size Immich will actually serve. Defaults to
* ImageSize.original (the bytes match the original asset). * 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 let servedMime: string | undefined
if (servedSize === ImageSize.original) { if (override) {
servedMime = override
} else if (servedSize === ImageSize.original) {
servedMime = asset.originalMimeType servedMime = asset.originalMimeType
} else if (servedSize === ImageSize.thumbnail) { } else if (servedSize === ImageSize.thumbnail) {
servedMime = 'image/webp' servedMime = 'image/webp'
@@ -83,7 +90,9 @@ export function getFilename (asset: Asset, servedSize: ImageSize = ImageSize.ori
// By default, use the asset's original filename // By default, use the asset's original filename
const cleanName = asset.originalFileName ? sanitize(asset.originalFileName) : '' const cleanName = asset.originalFileName ? sanitize(asset.originalFileName) : ''
if (!cleanName) return withMimeExtension(asset.id, servedMime) 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
: cleanName.replace(/\.[a-zA-Z0-9]{2,5}$/, '') : cleanName.replace(/\.[a-zA-Z0-9]{2,5}$/, '')
return withMimeExtension(stem, servedMime) return withMimeExtension(stem, servedMime)
+6 -1
View File
@@ -79,7 +79,12 @@ export async function assetBuffer (req: IncomingShareRequest, res: Response, ass
} }
if (attachment && asset.originalFileName) { 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}`) res.setHeader('Content-Disposition', `attachment; filename*=UTF-8''${filename}`)
} }
headerList.forEach(header => { headerList.forEach(header => {
+9 -3
View File
@@ -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 Failure = { asset: Asset, url: string, status?: number, error?: unknown }
type StageOutcome = StagedAsset | { failure: Failure } | null type StageOutcome = StagedAsset | { failure: Failure } | null
@@ -171,7 +171,7 @@ async function archiveStaged (archive: Archiver, stages: Promise<StageOutcome>[]
break break
} }
// archive.file queues the entry; archiver lazily opens and reads it. // 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 // 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. // so recover them from the headers we already fetched - no extra calls.
const stagedAsset = asset.originalFileName ? asset : enrichFromHeaders(asset, fetched.response) 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. // Use the array index in the path so we never collide on duplicate IDs.
const tempfile = join(options.stagingDir, `${index}-${asset.id}`) const tempfile = join(options.stagingDir, `${index}-${asset.id}`)
const streamed = await streamBodyToTempFile(fetched.response, tempfile, options.idleTimeoutMs) const streamed = await streamBodyToTempFile(fetched.response, tempfile, options.idleTimeoutMs)
if ('failure' in streamed) return { failure: { asset, url, error: streamed.failure } } if ('failure' in streamed) return { failure: { asset, url, error: streamed.failure } }
return { tempfile, asset: stagedAsset, endpoint } return { tempfile, asset: stagedAsset, endpoint, servedMime }
} }
/** /**
+45
View File
@@ -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')
})
})
+9
View File
@@ -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). 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` ## `downloadFromImmichConcurrencyLimit`
**Type:** `int` · **Default:** `20` **Type:** `int` · **Default:** `20`