feat(server): xmp sidecar metadata

docs/docs/features/xmp-sidecars.md

@@ -0,0 +1,13 @@
+# XMP Sidecars
+
+Immich can ingest XMP sidecars on file upload (via the CLI) as well as detect new sidecars that are placed in the filesystem for existing images.
+
+<img src={require('./img/xmp-sidecars.png').default} title='XMP sidecars' />
+
+XMP sidecars are external XML files that contain metadata related to media files. Many applications read and write these files either exclusively or in addition to the metadata written to image files. They can be a powerful tool for editing and storing metadata of a media file without modifying the mdia file itself. When Immich receives or detects an XMP sidecar for a media file, it will attempt to extract the metadata from both the sidecar as well as the media file. It will prioritize the metadata for fields in the sidecar but will fall back and use the metadata in the media file if necessary.
+
+When importing files via the CLI bulk uploader, Immich will automatically detect XMP sidecar files as files that exist next to the original media file and have the exact same name with an additional `.xmp` file extension (i.e., `PXL_20230401_203352928.MP.jpg` and `PXL_20230401_203352928.MP.jpg.xmp`).
+
+There are 2 administrator jobs associated with sidecar files: `SYNC` and `DISCOVER`. The sync job will re-scan all media with existing sidecar files and queue them for a metadata refresh. This is a great use case when third-party applications are used to modify the metadata of media. The discover job will attempt to scan the filesystem for new sidecar files for all media that does not currently have a sidecar file associated with it.
+
+<img src={require('./img/sidecar-jobs.png').default} title='Sidecar Administrator Jobs' />

server/apps/immich/src/api-v1/asset/asset.controller.ts

@@ -76,6 +76,7 @@ export class AssetController {
       [
         { name: 'assetData', maxCount: 1 },
         { name: 'livePhotoData', maxCount: 1 },
+        { name: 'sidecarData', maxCount: 1 },
       ],
       assetUploadOption,
     ),
@@ -88,18 +89,24 @@ export class AssetController {
   async uploadFile(
     @GetAuthUser() authUser: AuthUserDto,
     @UploadedFiles(new ParseFilePipe({ validators: [new FileNotEmptyValidator(['assetData'])] }))
-    files: { assetData: ImmichFile[]; livePhotoData?: ImmichFile[] },
+    files: { assetData: ImmichFile[]; livePhotoData?: ImmichFile[]; sidecarData: ImmichFile[] },
     @Body(new ValidationPipe()) dto: CreateAssetDto,
     @Response({ passthrough: true }) res: Res,
   ): Promise<AssetFileUploadResponseDto> {
     const file = mapToUploadFile(files.assetData[0]);
     const _livePhotoFile = files.livePhotoData?.[0];
+    const _sidecarFile = files.sidecarData?.[0];
     let livePhotoFile;
     if (_livePhotoFile) {
       livePhotoFile = mapToUploadFile(_livePhotoFile);
     }
 
-    const responseDto = await this.assetService.uploadFile(authUser, dto, file, livePhotoFile);
+    let sidecarFile;
+    if (_sidecarFile) {
+      sidecarFile = mapToUploadFile(_sidecarFile);
+    }
+
+    const responseDto = await this.assetService.uploadFile(authUser, dto, file, livePhotoFile, sidecarFile);
     if (responseDto.duplicate) {
       res.status(200);
     }

server/apps/immich/src/api-v1/asset/asset.core.ts

@@ -12,6 +12,7 @@ export class AssetCore {
     dto: CreateAssetDto,
     file: UploadFile,
     livePhotoAssetId?: string,
+    sidecarFile?: UploadFile,
   ): Promise<AssetEntity> {
     const asset = await this.repository.create({
       owner: { id: authUser.id } as UserEntity,
@@ -39,6 +40,7 @@ export class AssetCore {
       sharedLinks: [],
       originalFileName: parse(file.originalName).name,
       faces: [],
+      sidecarPath: sidecarFile?.originalPath || null,
     });
 
     await this.jobRepository.queue({ name: JobName.ASSET_UPLOADED, data: { asset } });

server/apps/immich/src/api-v1/asset/asset.service.spec.ts

@@ -305,7 +305,7 @@ describe('AssetService', () => {
 
       expect(jobMock.queue).toHaveBeenCalledWith({
         name: JobName.DELETE_FILES,
-        data: { files: ['fake_path/asset_1.jpeg', undefined] },
+        data: { files: ['fake_path/asset_1.jpeg', undefined, undefined] },
       });
       expect(storageMock.moveFile).not.toHaveBeenCalled();
     });
@@ -413,10 +413,12 @@ describe('AssetService', () => {
             undefined,
             undefined,
             undefined,
+            undefined,
             'fake_path/asset_1.mp4',
             undefined,
             undefined,
             undefined,
+            undefined,
           ],
         },
       });
@@ -462,10 +464,12 @@ describe('AssetService', () => {
                 'web-path-1',
                 'resize-path-1',
                 undefined,
+                undefined,
                 'original-path-2',
                 'web-path-2',
                 'resize-path-2',
                 'encoded-video-path-2',
+                undefined,
               ],
             },
           },

server/apps/immich/src/api-v1/asset/asset.service.ts

@@ -100,6 +100,7 @@ export class AssetService {
     dto: CreateAssetDto,
     file: UploadFile,
     livePhotoFile?: UploadFile,
+    sidecarFile?: UploadFile,
   ): Promise<AssetFileUploadResponseDto> {
     if (livePhotoFile) {
       livePhotoFile = {
@@ -116,14 +117,14 @@ export class AssetService {
         livePhotoAsset = await this.assetCore.create(authUser, livePhotoDto, livePhotoFile);
       }
 
-      const asset = await this.assetCore.create(authUser, dto, file, livePhotoAsset?.id);
+      const asset = await this.assetCore.create(authUser, dto, file, livePhotoAsset?.id, sidecarFile);
 
       return { id: asset.id, duplicate: false };
     } catch (error: any) {
       // clean up files
       await this.jobRepository.queue({
         name: JobName.DELETE_FILES,
-        data: { files: [file.originalPath, livePhotoFile?.originalPath] },
+        data: { files: [file.originalPath, livePhotoFile?.originalPath, sidecarFile?.originalPath] },
       });
 
       // handle duplicates with a success response
@@ -359,7 +360,13 @@ export class AssetService {
         await this.jobRepository.queue({ name: JobName.SEARCH_REMOVE_ASSET, data: { ids: [id] } });
 
         result.push({ id, status: DeleteAssetStatusEnum.SUCCESS });
-        deleteQueue.push(asset.originalPath, asset.webpPath, asset.resizePath, asset.encodedVideoPath);
+        deleteQueue.push(
+          asset.originalPath,
+          asset.webpPath,
+          asset.resizePath,
+          asset.encodedVideoPath,
+          asset.sidecarPath,
+        );
 
         // TODO refactor this to use cascades
         if (asset.livePhotoVideoId && !ids.includes(asset.livePhotoVideoId)) {

server/apps/immich/src/api-v1/asset/dto/create-asset.dto.ts

@@ -45,6 +45,9 @@ export class CreateAssetDto {
 
   @ApiProperty({ type: 'string', format: 'binary' })
   livePhotoData?: any;
+
+  @ApiProperty({ type: 'string', format: 'binary' })
+  sidecarData?: any;
 }
 
 export interface UploadFile {

server/apps/immich/src/config/asset-upload.config.ts

@@ -60,6 +60,11 @@ function fileFilter(req: AuthRequest, file: any, cb: any) {
   ) {
     cb(null, true);
   } else {
+    // Additionally support XML but only for sidecar files
+    if (file.fieldname == 'sidecarData' && file.mimetype.match(/\/xml$/)) {
+      return cb(null, true);
+    }
+
     logger.error(`Unsupported file type ${extname(file.originalname)} file MIME type ${file.mimetype}`);
     cb(new BadRequestException(`Unsupported file type ${extname(file.originalname)}`), false);
   }
@@ -95,6 +100,11 @@ function filename(req: AuthRequest, file: Express.Multer.File, cb: any) {
     return cb(null, sanitize(livePhotoFileName));
   }
 
+  if (file.fieldname === 'sidecarData') {
+    const sidecarFileName = `${fileNameUUID}.xmp`;
+    return cb(null, sanitize(sidecarFileName));
+  }
+
   const fileName = `${fileNameUUID}${req.body['fileExtension']}`;
   return cb(null, sanitize(fileName));
 }

server/apps/microservices/src/microservices.module.ts

@@ -13,7 +13,7 @@ import {
   ThumbnailGeneratorProcessor,
   VideoTranscodeProcessor,
 } from './processors';
-import { MetadataExtractionProcessor } from './processors/metadata-extraction.processor';
+import { MetadataExtractionProcessor, SidecarProcessor } from './processors/metadata-extraction.processor';
 
 @Module({
   imports: [
@@ -31,6 +31,7 @@ import { MetadataExtractionProcessor } from './processors/metadata-extraction.pr
     BackgroundTaskProcessor,
     SearchIndexProcessor,
     FacialRecognitionProcessor,
+    SidecarProcessor,
   ],
 })
 export class MicroservicesModule {}