5.7 KiB
General options
Top-level options under ipp.* that don't belong to the Gallery, Lightbox or Metadata groups.
Example
Serve full-resolution images both when zooming in the lightbox and when downloading:
{
"ipp": {
"maxDownloadQuality": "fullsize",
"maxZoomQuality": "fullsize"
}
}
responseHeaders
Type: object
Change the headers sent with your web responses. The default is a 30-day Cache-Control and a permissive CORS header.
These apply to photos, videos and static files. The "download all" zip is always sent with Cache-Control: no-store
to prevent CDN issues, and the gallery page uses its own gallery.cacheTime.
{
"ipp": {
"responseHeaders": {
"Cache-Control": "public, max-age=2592000",
"Access-Control-Allow-Origin": "*"
}
}
}
maxDownloadQuality
Type: string · Default: "original"
Highest quality served for a download (the download button and "download all" zip).
"original"- the full-resolution original file (default)."fullsize"- full resolution but always browser-displayable: the original for JPEG/PNG/WebP, Immich's converted full-size image for RAW/HEIF, in JPEG or WebP per the server's image settings."preview"- only the ~1440px preview, in JPEG or WebP per the server's image settings.
maxZoomQuality
Type: string · Default: "preview"
Highest quality the lightbox loads when you zoom in past fit-to-screen.
"preview"- keep the preview (default; zoom is capped to the preview's real pixels)."fullsize"- upgrade to the full-resolution browser-displayable image on zoom, à la the Immich web viewer.
"original" is intentionally not an option (it could be an unviewable RAW/DNG or a huge file).
Independent of allowDownload - your download UI can be off while zoom is on. It only does anything where Immich can serve full resolution: the share's own "allow downloads" toggle in Immich must be on (the full-res image comes from the original file, which Immich gates on that toggle), and the format must be web-displayable (JPEG/PNG/WebP). Otherwise (RAW/HEIF, or a share with Immich downloads off) the lightbox stays on the preview. To enable zoom-up, leave the Immich share's download permission on and use allowDownload to control whether the download buttons appear.
motionPhotos
Type: bool · Default: true
Show motion photos (Live Photos) - an indicator on the gallery thumbnail, and a toggle in the lightbox that plays the photo's short clip and returns to the still when it ends. The toggle stays on: each motion photo the visitor moves to plays its clip automatically until they switch it off.
Clips are only fetched while the toggle is on, so leaving this on costs no extra bandwidth for visitors who never use it. Set to false to serve motion photos as plain stills:
{
"ipp": {
"motionPhotos": false
}
}
downloadedFilename
Type: int · Default: 0
The filename of the downloaded image.
0- the original filename if available, falling back to the Immich asset ID.1- the Immich asset ID number.2- a shortened version of the asset ID:img_plus the first 8 characters of the asset ID.
allowDownload
Type: int · Default: 0
Show the download UI - the "download all" zip, the multi-select download, and the per-asset download button in the lightbox. Purely a UI switch; it has no effect on image quality (see maxZoomQuality / maxDownloadQuality).
0- downloads off.1- follow the Immich share's own download setting (example).2- always on.
The bulk-zip and per-asset buttons can be toggled independently once downloads are allowed - see gallery.showDownloadZip and 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
maxDownloadQualityis beloworiginal; withmaxDownloadQuality: originalthey 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.
allowSlugLinks
Type: bool · Default: true
Serve shared links that have a custom URL in Immich at /s/<slug> as well as /share/<key>. Set to false to return a 404 for slug links, so that only the key form works.
showHomePage
Type: bool · Default: true
Set to false to remove the IPP shield page at / and at /share.
{
"ipp": {
"showHomePage": false
}
}
gallery
Type: object
Gallery-page options. See Gallery.
lightbox
Type: object
Lightbox options. See Lightbox.
showMetadata
Type: object
Description / EXIF / location reveal controls. See Metadata.
customInvalidResponse
Type: various
Send a custom response instead of the default 404. See Error responses.