feat(server): separate quality for thumbnail and preview images (#13006)

* allow different thumbnail and preview quality, better config structure

* update web and api

* wording

* remove empty line?

open-api/immich-openapi-specs.json

@@ -11654,6 +11654,28 @@
         ],
         "type": "object"
       },
+      "SystemConfigGeneratedImageDto": {
+        "properties": {
+          "format": {
+            "$ref": "#/components/schemas/ImageFormat"
+          },
+          "quality": {
+            "maximum": 100,
+            "minimum": 1,
+            "type": "integer"
+          },
+          "size": {
+            "minimum": 1,
+            "type": "integer"
+          }
+        },
+        "required": [
+          "format",
+          "quality",
+          "size"
+        ],
+        "type": "object"
+      },
       "SystemConfigImageDto": {
         "properties": {
           "colorspace": {
@@ -11662,34 +11684,18 @@
           "extractEmbedded": {
             "type": "boolean"
           },
-          "previewFormat": {
-            "$ref": "#/components/schemas/ImageFormat"
+          "preview": {
+            "$ref": "#/components/schemas/SystemConfigGeneratedImageDto"
           },
-          "previewSize": {
-            "minimum": 1,
-            "type": "integer"
-          },
-          "quality": {
-            "maximum": 100,
-            "minimum": 1,
-            "type": "integer"
-          },
-          "thumbnailFormat": {
-            "$ref": "#/components/schemas/ImageFormat"
-          },
-          "thumbnailSize": {
-            "minimum": 1,
-            "type": "integer"
+          "thumbnail": {
+            "$ref": "#/components/schemas/SystemConfigGeneratedImageDto"
           }
         },
         "required": [
           "colorspace",
           "extractEmbedded",
-          "previewFormat",
-          "previewSize",
-          "quality",
-          "thumbnailFormat",
-          "thumbnailSize"
+          "preview",
+          "thumbnail"
         ],
         "type": "object"
       },

open-api/typescript-sdk/src/fetch-client.ts

@@ -1100,14 +1100,16 @@ export type SystemConfigFFmpegDto = {
     transcode: TranscodePolicy;
     twoPass: boolean;
 };
+export type SystemConfigGeneratedImageDto = {
+    format: ImageFormat;
+    quality: number;
+    size: number;
+};
 export type SystemConfigImageDto = {
     colorspace: Colorspace;
     extractEmbedded: boolean;
-    previewFormat: ImageFormat;
-    previewSize: number;
-    quality: number;
-    thumbnailFormat: ImageFormat;
-    thumbnailSize: number;
+    preview: SystemConfigGeneratedImageDto;
+    thumbnail: SystemConfigGeneratedImageDto;
 };
 export type JobSettingsDto = {
     concurrency: number;

server/src/config.ts

@@ -20,6 +20,7 @@ import {
   VideoContainer,
 } from 'src/enum';
 import { ConcurrentQueueName, QueueName } from 'src/interfaces/job.interface';
+import { ImageOutputConfig } from 'src/interfaces/media.interface';
 
 export interface SystemConfig {
   ffmpeg: {
@@ -109,11 +110,8 @@ export interface SystemConfig {
     template: string;
   };
   image: {
-    thumbnailFormat: ImageFormat;
-    thumbnailSize: number;
-    previewFormat: ImageFormat;
-    previewSize: number;
-    quality: number;
+    thumbnail: ImageOutputConfig;
+    preview: ImageOutputConfig;
     colorspace: Colorspace;
     extractEmbedded: boolean;
   };
@@ -259,11 +257,16 @@ export const defaults = Object.freeze<SystemConfig>({
     template: '{{y}}/{{y}}-{{MM}}-{{dd}}/{{filename}}',
   },
   image: {
-    thumbnailFormat: ImageFormat.WEBP,
-    thumbnailSize: 250,
-    previewFormat: ImageFormat.JPEG,
-    previewSize: 1440,
-    quality: 80,
+    thumbnail: {
+      format: ImageFormat.WEBP,
+      size: 250,
+      quality: 80,
+    },
+    preview: {
+      format: ImageFormat.JPEG,
+      size: 1440,
+      quality: 80,
+    },
     colorspace: Colorspace.P3,
     extractEmbedded: false,
   },

server/src/dtos/system-config.dto.ts

@@ -473,26 +473,10 @@ export class SystemConfigThemeDto {
   customCss!: string;
 }
 
-class SystemConfigImageDto {
+class SystemConfigGeneratedImageDto {
   @IsEnum(ImageFormat)
   @ApiProperty({ enumName: 'ImageFormat', enum: ImageFormat })
-  thumbnailFormat!: ImageFormat;
-
-  @IsInt()
-  @Min(1)
-  @Type(() => Number)
-  @ApiProperty({ type: 'integer' })
-  thumbnailSize!: number;
-
-  @IsEnum(ImageFormat)
-  @ApiProperty({ enumName: 'ImageFormat', enum: ImageFormat })
-  previewFormat!: ImageFormat;
-
-  @IsInt()
-  @Min(1)
-  @Type(() => Number)
-  @ApiProperty({ type: 'integer' })
-  previewSize!: number;
+  format!: ImageFormat;
 
   @IsInt()
   @Min(1)
@@ -501,6 +485,24 @@ class SystemConfigImageDto {
   @ApiProperty({ type: 'integer' })
   quality!: number;
 
+  @IsInt()
+  @Min(1)
+  @Type(() => Number)
+  @ApiProperty({ type: 'integer' })
+  size!: number;
+}
+
+class SystemConfigImageDto {
+  @Type(() => SystemConfigGeneratedImageDto)
+  @ValidateNested()
+  @IsObject()
+  thumbnail!: SystemConfigGeneratedImageDto;
+
+  @Type(() => SystemConfigGeneratedImageDto)
+  @ValidateNested()
+  @IsObject()
+  preview!: SystemConfigGeneratedImageDto;
+
   @IsEnum(Colorspace)
   @ApiProperty({ enumName: 'Colorspace', enum: Colorspace })
   colorspace!: Colorspace;

server/src/interfaces/media.interface.ts

@@ -10,11 +10,14 @@ export interface CropOptions {
   height: number;
 }
 
-export interface ThumbnailOptions {
-  size: number;
+export interface ImageOutputConfig {
   format: ImageFormat;
-  colorspace: string;
   quality: number;
+  size: number;
+}
+
+export interface ThumbnailOptions extends ImageOutputConfig {
+  colorspace: string;
   crop?: CropOptions;
   processInvalidImages: boolean;
 }

server/src/migrations/1727471863507-SeparateQualityForThumbnailAndPreview.ts

@@ -0,0 +1,37 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class SeparateQualityForThumbnailAndPreview1727471863507 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      update system_metadata
+      set value = jsonb_set(value, '{image}', jsonb_strip_nulls(
+        jsonb_build_object(
+          'preview', jsonb_build_object(
+            'format', value->'image'->'previewFormat',
+            'quality', value->'image'->'quality',
+            'size', value->'image'->'previewSize'),
+          'thumbnail', jsonb_build_object(
+            'format', value->'image'->'thumbnailFormat',
+            'quality', value->'image'->'quality',
+            'size', value->'image'->'thumbnailSize'),
+          'extractEmbedded', value->'extractEmbedded',
+          'colorspace', value->'colorspace'
+        )))
+        where key = 'system-config'`);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      update system_metadata
+        set value = jsonb_set(value, '{image}', jsonb_strip_nulls(jsonb_build_object(
+          'previewFormat', value->'image'->'preview'->'format',
+          'previewSize', value->'image'->'preview'->'size',
+          'thumbnailFormat', value->'image'->'thumbnail'->'format',
+          'thumbnailSize', value->'image'->'thumbnail'->'size',
+          'extractEmbedded', value->'extractEmbedded',
+          'colorspace', value->'colorspace',
+          'quality', value->'image'->'preview'->'quality'
+        )))
+        where key = 'system-config'`);
+  }
+}

server/src/services/media.service.spec.ts

@@ -285,7 +285,7 @@ describe(MediaService.name, () => {
     });
 
     it.each(Object.values(ImageFormat))('should generate a %s preview for an image when specified', async (format) => {
-      systemMock.get.mockResolvedValue({ image: { previewFormat: format } });
+      systemMock.get.mockResolvedValue({ image: { preview: { format } } });
       assetMock.getByIds.mockResolvedValue([assetStub.image]);
       const previewPath = `upload/thumbs/user-id/as/se/asset-id-preview.${format}`;
 
@@ -307,7 +307,7 @@ describe(MediaService.name, () => {
     });
 
     it('should delete previous preview if different path', async () => {
-      systemMock.get.mockResolvedValue({ image: { thumbnailFormat: ImageFormat.WEBP } });
+      systemMock.get.mockResolvedValue({ image: { thumbnail: { format: ImageFormat.WEBP } } });
       assetMock.getByIds.mockResolvedValue([assetStub.image]);
 
       await sut.handleGeneratePreview({ id: assetStub.image.id });
@@ -464,7 +464,7 @@ describe(MediaService.name, () => {
     it.each(Object.values(ImageFormat))(
       'should generate a %s thumbnail for an image when specified',
       async (format) => {
-        systemMock.get.mockResolvedValue({ image: { thumbnailFormat: format } });
+        systemMock.get.mockResolvedValue({ image: { thumbnail: { format } } });
         assetMock.getByIds.mockResolvedValue([assetStub.image]);
         const thumbnailPath = `upload/thumbs/user-id/as/se/asset-id-thumbnail.${format}`;
 
@@ -487,7 +487,7 @@ describe(MediaService.name, () => {
     );
 
     it('should delete previous thumbnail if different path', async () => {
-      systemMock.get.mockResolvedValue({ image: { thumbnailFormat: ImageFormat.WEBP } });
+      systemMock.get.mockResolvedValue({ image: { thumbnail: { format: ImageFormat.WEBP } } });
       assetMock.getByIds.mockResolvedValue([assetStub.image]);
 
       await sut.handleGenerateThumbnail({ id: assetStub.image.id });

server/src/services/media.service.ts

@@ -10,7 +10,6 @@ import {
   AssetType,
   AudioCodec,
   Colorspace,
-  ImageFormat,
   LogLevel,
   StorageFolder,
   TranscodeHWAccel,
@@ -175,18 +174,15 @@ export class MediaService {
       return JobStatus.FAILED;
     }
 
-    await this.storageCore.moveAssetImage(asset, AssetPathType.PREVIEW, image.previewFormat);
-    await this.storageCore.moveAssetImage(asset, AssetPathType.THUMBNAIL, image.thumbnailFormat);
+    await this.storageCore.moveAssetImage(asset, AssetPathType.PREVIEW, image.preview.format);
+    await this.storageCore.moveAssetImage(asset, AssetPathType.THUMBNAIL, image.thumbnail.format);
     await this.storageCore.moveAssetVideo(asset);
 
     return JobStatus.SUCCESS;
   }
 
   async handleGeneratePreview({ id }: IEntityJob): Promise<JobStatus> {
-    const [{ image }, [asset]] = await Promise.all([
-      this.configCore.getConfig({ withCache: true }),
-      this.assetRepository.getByIds([id], { exifInfo: true, files: true }),
-    ]);
+    const [asset] = await this.assetRepository.getByIds([id], { exifInfo: true, files: true });
     if (!asset) {
       return JobStatus.FAILED;
     }
@@ -195,7 +191,7 @@ export class MediaService {
       return JobStatus.SKIPPED;
     }
 
-    const previewPath = await this.generateThumbnail(asset, AssetPathType.PREVIEW, image.previewFormat);
+    const previewPath = await this.generateThumbnail(asset, AssetPathType.PREVIEW);
     if (!previewPath) {
       return JobStatus.SKIPPED;
     }
@@ -213,9 +209,9 @@ export class MediaService {
     return JobStatus.SUCCESS;
   }
 
-  private async generateThumbnail(asset: AssetEntity, type: GeneratedImageType, format: ImageFormat) {
+  private async generateThumbnail(asset: AssetEntity, type: GeneratedImageType) {
     const { image, ffmpeg } = await this.configCore.getConfig({ withCache: true });
-    const size = type === AssetPathType.PREVIEW ? image.previewSize : image.thumbnailSize;
+    const { size, format, quality } = image[type];
     const path = StorageCore.getImagePath(asset, type, format);
     this.storageCore.ensureFolders(path);
 
@@ -226,13 +222,13 @@ export class MediaService {
         const didExtract = shouldExtract && (await this.mediaRepository.extract(asset.originalPath, extractedPath));
 
         try {
-          const useExtracted = didExtract && (await this.shouldUseExtractedImage(extractedPath, image.previewSize));
+          const useExtracted = didExtract && (await this.shouldUseExtractedImage(extractedPath, image.preview.size));
           const colorspace = this.isSRGB(asset) ? Colorspace.SRGB : image.colorspace;
           const imageOptions = {
             format,
             size,
             colorspace,
-            quality: image.quality,
+            quality,
             processInvalidImages: process.env.IMMICH_PROCESS_INVALID_IMAGES === 'true',
           };
 
@@ -274,10 +270,7 @@ export class MediaService {
   }
 
   async handleGenerateThumbnail({ id }: IEntityJob): Promise<JobStatus> {
-    const [{ image }, [asset]] = await Promise.all([
-      this.configCore.getConfig({ withCache: true }),
-      this.assetRepository.getByIds([id], { exifInfo: true, files: true }),
-    ]);
+    const [asset] = await this.assetRepository.getByIds([id], { exifInfo: true, files: true });
     if (!asset) {
       return JobStatus.FAILED;
     }
@@ -286,7 +279,7 @@ export class MediaService {
       return JobStatus.SKIPPED;
     }
 
-    const thumbnailPath = await this.generateThumbnail(asset, AssetPathType.THUMBNAIL, image.thumbnailFormat);
+    const thumbnailPath = await this.generateThumbnail(asset, AssetPathType.THUMBNAIL);
     if (!thumbnailPath) {
       return JobStatus.SKIPPED;
     }

server/src/services/person.service.ts

@@ -574,7 +574,7 @@ export class PersonService {
       format: ImageFormat.JPEG,
       size: FACE_THUMBNAIL_SIZE,
       colorspace: image.colorspace,
-      quality: image.quality,
+      quality: image.thumbnail.quality,
       crop: this.getCrop({ old: { width: oldWidth, height: oldHeight }, new: { width, height } }, { x1, y1, x2, y2 }),
       processInvalidImages: process.env.IMMICH_PROCESS_INVALID_IMAGES === 'true',
     } as const;

server/src/services/system-config.service.spec.ts

@@ -135,11 +135,16 @@ const updatedConfig = Object.freeze<SystemConfig>({
     template: '{{y}}/{{y}}-{{MM}}-{{dd}}/{{filename}}',
   },
   image: {
-    thumbnailFormat: ImageFormat.WEBP,
-    thumbnailSize: 250,
-    previewFormat: ImageFormat.JPEG,
-    previewSize: 1440,
-    quality: 80,
+    thumbnail: {
+      size: 250,
+      format: ImageFormat.WEBP,
+      quality: 80,
+    },
+    preview: {
+      size: 1440,
+      format: ImageFormat.JPEG,
+      quality: 80,
+    },
     colorspace: Colorspace.P3,
     extractEmbedded: false,
   },

web/src/lib/components/admin-page/settings/image/image-settings.svelte

@@ -11,6 +11,7 @@
     SettingInputFieldType,
   } from '$lib/components/shared-components/settings/setting-input-field.svelte';
   import { t } from 'svelte-i18n';
+  import SettingAccordion from '$lib/components/shared-components/settings/setting-accordion.svelte';
 
   export let savedConfig: SystemConfigDto;
   export let defaultConfig: SystemConfigDto;
@@ -24,73 +25,96 @@
   <div in:fade={{ duration: 500 }}>
     <form autocomplete="off" on:submit|preventDefault>
       <div class="ml-4 mt-4 flex flex-col gap-4">
-        <SettingSelect
-          label={$t('admin.image_thumbnail_format')}
-          desc={$t('admin.image_format_description')}
-          bind:value={config.image.thumbnailFormat}
-          options={[
-            { value: ImageFormat.Jpeg, text: 'JPEG' },
-            { value: ImageFormat.Webp, text: 'WebP' },
-          ]}
-          name="format"
-          isEdited={config.image.thumbnailFormat !== savedConfig.image.thumbnailFormat}
-          {disabled}
-        />
+        <SettingAccordion
+          key="thumbnail-settings"
+          title={$t('admin.image_thumbnail_title')}
+          subtitle={$t('admin.image_thumbnail_description')}
+          isOpen={true}
+        >
+          <SettingSelect
+            label={$t('admin.image_format')}
+            desc={$t('admin.image_format_description')}
+            bind:value={config.image.thumbnail.format}
+            options={[
+              { value: ImageFormat.Jpeg, text: 'JPEG' },
+              { value: ImageFormat.Webp, text: 'WebP' },
+            ]}
+            name="format"
+            isEdited={config.image.thumbnail.format !== savedConfig.image.thumbnail.format}
+            {disabled}
+          />
 
-        <SettingSelect
-          label={$t('admin.image_thumbnail_resolution')}
-          desc={$t('admin.image_thumbnail_resolution_description')}
-          number
-          bind:value={config.image.thumbnailSize}
-          options={[
-            { value: 1080, text: '1080p' },
-            { value: 720, text: '720p' },
-            { value: 480, text: '480p' },
-            { value: 250, text: '250p' },
-            { value: 200, text: '200p' },
-          ]}
-          name="resolution"
-          isEdited={config.image.thumbnailSize !== savedConfig.image.thumbnailSize}
-          {disabled}
-        />
+          <SettingSelect
+            label={$t('admin.image_resolution')}
+            desc={$t('admin.image_resolution_description')}
+            number
+            bind:value={config.image.thumbnail.size}
+            options={[
+              { value: 1080, text: '1080p' },
+              { value: 720, text: '720p' },
+              { value: 480, text: '480p' },
+              { value: 250, text: '250p' },
+              { value: 200, text: '200p' },
+            ]}
+            name="resolution"
+            isEdited={config.image.thumbnail.size !== savedConfig.image.thumbnail.size}
+            {disabled}
+          />
 
-        <SettingSelect
-          label={$t('admin.image_preview_format')}
-          desc={$t('admin.image_format_description')}
-          bind:value={config.image.previewFormat}
-          options={[
-            { value: ImageFormat.Jpeg, text: 'JPEG' },
-            { value: ImageFormat.Webp, text: 'WebP' },
-          ]}
-          name="format"
-          isEdited={config.image.previewFormat !== savedConfig.image.previewFormat}
-          {disabled}
-        />
+          <SettingInputField
+            inputType={SettingInputFieldType.NUMBER}
+            label={$t('admin.image_quality')}
+            desc={$t('admin.image_thumbnail_quality_description')}
+            bind:value={config.image.thumbnail.quality}
+            isEdited={config.image.thumbnail.quality !== savedConfig.image.thumbnail.quality}
+            {disabled}
+          />
+        </SettingAccordion>
 
-        <SettingSelect
-          label={$t('admin.image_preview_resolution')}
-          desc={$t('admin.image_preview_resolution_description')}
-          number
-          bind:value={config.image.previewSize}
-          options={[
-            { value: 2160, text: '4K' },
-            { value: 1440, text: '1440p' },
-            { value: 1080, text: '1080p' },
-            { value: 720, text: '720p' },
-          ]}
-          name="resolution"
-          isEdited={config.image.previewSize !== savedConfig.image.previewSize}
-          {disabled}
-        />
+        <SettingAccordion
+          key="preview-settings"
+          title={$t('admin.image_preview_title')}
+          subtitle={$t('admin.image_preview_description')}
+          isOpen={true}
+        >
+          <SettingSelect
+            label={$t('admin.image_format')}
+            desc={$t('admin.image_format_description')}
+            bind:value={config.image.preview.format}
+            options={[
+              { value: ImageFormat.Jpeg, text: 'JPEG' },
+              { value: ImageFormat.Webp, text: 'WebP' },
+            ]}
+            name="format"
+            isEdited={config.image.preview.format !== savedConfig.image.preview.format}
+            {disabled}
+          />
 
-        <SettingInputField
-          inputType={SettingInputFieldType.NUMBER}
-          label={$t('admin.image_quality')}
-          desc={$t('admin.image_quality_description')}
-          bind:value={config.image.quality}
-          isEdited={config.image.quality !== savedConfig.image.quality}
-          {disabled}
-        />
+          <SettingSelect
+            label={$t('admin.image_resolution')}
+            desc={$t('admin.image_resolution_description')}
+            number
+            bind:value={config.image.preview.size}
+            options={[
+              { value: 2160, text: '4K' },
+              { value: 1440, text: '1440p' },
+              { value: 1080, text: '1080p' },
+              { value: 720, text: '720p' },
+            ]}
+            name="resolution"
+            isEdited={config.image.preview.size !== savedConfig.image.preview.size}
+            {disabled}
+          />
+
+          <SettingInputField
+            inputType={SettingInputFieldType.NUMBER}
+            label={$t('admin.image_quality')}
+            desc={$t('admin.image_preview_quality_description')}
+            bind:value={config.image.preview.quality}
+            isEdited={config.image.preview.quality !== savedConfig.image.preview.quality}
+            {disabled}
+          />
+        </SettingAccordion>
 
         <SettingSwitch
           title={$t('admin.image_prefer_wide_gamut')}

web/src/lib/i18n/en.json

@@ -54,21 +54,23 @@
     "failed_job_command": "Command {command} failed for job: {job}",
     "force_delete_user_warning": "WARNING: This will immediately remove the user and all assets. This cannot be undone and the files cannot be recovered.",
     "forcing_refresh_library_files": "Forcing refresh of all library files",
+    "image_format": "Format",
     "image_format_description": "WebP produces smaller files than JPEG, but is slower to encode.",
     "image_prefer_embedded_preview": "Prefer embedded preview",
     "image_prefer_embedded_preview_setting_description": "Use embedded previews in RAW photos as the input to image processing when available. This can produce more accurate colors for some images, but the quality of the preview is camera-dependent and the image may have more compression artifacts.",
     "image_prefer_wide_gamut": "Prefer wide gamut",
     "image_prefer_wide_gamut_setting_description": "Use Display P3 for thumbnails. This better preserves the vibrance of images with wide colorspaces, but images may appear differently on old devices with an old browser version. sRGB images are kept as sRGB to avoid color shifts.",
-    "image_preview_format": "Preview format",
-    "image_preview_resolution": "Preview resolution",
-    "image_preview_resolution_description": "Used when viewing a single photo and for machine learning. Higher resolutions can preserve more detail but take longer to encode, have larger file sizes, and can reduce app responsiveness.",
+    "image_preview_description": "Medium-size image with stripped metadata, used when viewing a single asset and for machine learning",
+    "image_preview_quality_description": "Preview quality from 1-100. Higher is better, but produces larger files and can reduce app responsiveness. Setting a low value may affect machine learning quality.",
+    "image_preview_title": "Preview Settings",
     "image_quality": "Quality",
-    "image_quality_description": "Image quality from 1-100. Higher is better for quality but produces larger files, this option affects the Preview and Thumbnail images.",
+    "image_resolution": "Resolution",
+    "image_resolution_description": "Higher resolutions can preserve more detail but take longer to encode, have larger file sizes and can reduce app responsiveness.",
     "image_settings": "Image Settings",
     "image_settings_description": "Manage the quality and resolution of generated images",
-    "image_thumbnail_format": "Thumbnail format",
-    "image_thumbnail_resolution": "Thumbnail resolution",
-    "image_thumbnail_resolution_description": "Used when viewing groups of photos (main timeline, album view, etc.). Higher resolutions can preserve more detail but take longer to encode, have larger file sizes, and can reduce app responsiveness.",
+    "image_thumbnail_description": "Small thumbnail with stripped metadata, used when viewing groups of photos like the main timeline",
+    "image_thumbnail_quality_description": "Thumbnail quality from 1-100. Higher is better, but produces larger files and can reduce app responsiveness.",
+    "image_thumbnail_title": "Thumbnail Settings",
     "job_concurrency": "{job} concurrency",
     "job_created": "Job created",
     "job_not_concurrency_safe": "This job is not concurrency-safe.",