Skip to content

Self-hosted personal gallery application with online photo management and albums, supporting Live/Motion Photos, EXIF parsing, geolocation recognition, and an explore map.

14.3 KB
Raw Blame
import type { MediaLogger } from './logger.ts'
import type { ExifTool } from 'exiftool-vendored'
import { randomUUID } from 'node:crypto'
import path from 'node:path'
import { mkdir, unlink, writeFile } from 'node:fs/promises'
import type { Metadata } from 'sharp'
import sharp from 'sharp'
import type { NeededExif, PhotoInfo } from '@chronoframe/contracts/photo'
import type { ExifDateTime, Tags } from 'exiftool-vendored'
import { noop } from 'es-toolkit'
import { withRetry, RetryPresets, RetryConditions } from './retry.ts'

/** Create EXIF helpers using a caller-owned ExifTool instance and temporary directory. */
export function createExifService({
  exiftool,
  tempDir,
  logger: serviceLogger,
}: {
  exiftool: Pick<ExifTool, 'read'>
  tempDir: string
  logger?: MediaLogger
}) {
  const neededKeys: Array<keyof Tags | (string & {})> = [
    'Title',
    'XPTitle',
    'Subject',
    'Keywords',
    'XPKeywords',

    'Description',
    'ImageDescription',
    'Caption-Abstract',
    'XPComment',
    'UserComment',

    'tz',
    'tzSource',
    'Orientation',
    'Make',
    'Model',
    'Software',
    'Artist',
    'Copyright',
    'ExposureTime',

    'FNumber',
    'ExposureProgram',
    'ISO',
    'OffsetTime',
    'OffsetTimeOriginal',
    'OffsetTimeDigitized',
    'ShutterSpeedValue',
    'ApertureValue',
    'BrightnessValue',
    'ExposureCompensationSet',
    'ExposureCompensationMode',
    'ExposureCompensationSetting',

    'ExposureCompensation',
    'MaxApertureValue',
    'LightSource',
    'Flash',
    'FocalLength',

    'ColorSpace',
    'ExposureMode',
    'FocalLengthIn35mmFormat',
    'SceneCaptureType',
    'LensMake',
    'LensModel',
    'MeteringMode',
    'WhiteBalance',
    'WBShiftAB',
    'WBShiftGM',
    'WhiteBalanceBias',
    'WhiteBalanceFineTune',
    'FlashMeteringMode',
    'SensingMethod',
    'FocalPlaneXResolution',
    'FocalPlaneYResolution',

    'Aperture',
    'ScaleFactor35efl',
    'ShutterSpeed',
    'LightValue',
    'Rating',

    'GPSAltitude',
    'GPSCoordinates',
    'GPSAltitudeRef',
    'GPSLatitude',
    'GPSLatitudeRef',
    'GPSLongitude',
    'GPSLongitudeRef',

    'MPImageType',

    // Motion Photo (XMP) related keys
    'MotionPhoto',
    'MotionPhotoVersion',
    'MotionPhotoPresentationTimestampUs',
    'MicroVideo',
    'MicroVideoVersion',
    'MicroVideoOffset',
    'MicroVideoPresentationTimestampUs',
  ]

  /**
   * Convert a date-like value to an ISO string, returning undefined instead of
   * throwing `RangeError: Invalid time value` when the value cannot be parsed.
   */
  const toValidISOString = (
    value: string | number | Date,
  ): string | undefined => {
    const date = value instanceof Date ? value : new Date(value)
    return Number.isNaN(date.getTime()) ? undefined : date.toISOString()
  }

  const formatExifDate = (date: string | ExifDateTime | undefined) => {
    if (!date) {
      return
    }

    // exiftool returns the raw string when it cannot parse a date
    // (e.g. "0000:00:00 00:00:00"), which `new Date()` cannot parse either.
    if (typeof date === 'string') {
      return toValidISOString(date)
    }

    return date.toISOString()
  }

  /**
   * 从 Sharp metadata 中推断颜色空间信息
   */
  const inferColorSpaceFromMetadata = (
    metadata: Metadata,
  ): string | undefined => {
    // 优先使用 ICC 配置文件信息
    if (metadata.icc) {
      const colorSpace = parseICCProfile(metadata.icc)
      if (colorSpace) {
        return colorSpace
      }
    }

    // 根据图片格式和通道数推断
    if (metadata.space) {
      const colorSpace = mapSharpSpaceToColorSpace(metadata.space)
      if (colorSpace) {
        return colorSpace
      }
    }

    // 根据图片类型的默认颜色空间
    if (metadata.format) {
      const colorSpace = getDefaultColorSpaceForFormat(metadata.format)
      if (colorSpace) {
        return colorSpace
      }
    }

    return undefined
  }

  /**
   * 解析 ICC 配置文件以确定颜色空间
   */
  const parseICCProfile = (iccBuffer: Buffer): string | undefined => {
    try {
      const iccString = iccBuffer.toString('latin1')

      // 常见的颜色空间标识符
      if (iccString.includes('sRGB') || iccString.includes('IEC61966-2.1')) {
        return 'sRGB'
      }
      if (iccString.includes('Adobe RGB') || iccString.includes('ADOBERGB')) {
        return 'Adobe RGB'
      }
      if (iccString.includes('Display P3') || iccString.includes('P3')) {
        return 'Display P3'
      }
      if (iccString.includes('ProPhoto') || iccString.includes('ROMM')) {
        return 'ProPhoto RGB'
      }
      if (iccString.includes('Wide Gamut') || iccString.includes('WideGamut')) {
        return 'Wide Gamut RGB'
      }
      if (
        iccString.includes('Rec2020') ||
        iccString.includes('ITU-R BT.2020')
      ) {
        return 'Rec. 2020'
      }
      if (iccString.includes('DCI-P3') || iccString.includes('DCI')) {
        return 'DCI-P3'
      }
      if (iccString.includes('Rec709') || iccString.includes('ITU-R BT.709')) {
        return 'Rec. 709'
      }

      // 检查 ICC 配置文件头部的颜色空间签名(偏移量 16-19)
      if (iccBuffer.length >= 20) {
        const colorSpaceSignature = iccBuffer.toString('ascii', 16, 20)
        switch (colorSpaceSignature) {
          case 'RGB ':
            return 'RGB'
          case 'CMYK':
            return 'CMYK'
          case 'GRAY':
            return 'Grayscale'
          case 'LAB ':
            return 'Lab'
          case 'XYZ ':
            return 'XYZ'
          default:
            break
        }
      }
    } catch {
      // 忽略解析错误,继续尝试其他方法
    }

    return undefined
  }

  /**
   * 将 Sharp 的 space 映射到标准颜色空间名称
   */
  const mapSharpSpaceToColorSpace = (space: string): string | undefined => {
    switch (space) {
      case 'srgb':
        return 'sRGB'
      case 'rgb16':
        return 'RGB'
      case 'cmyk':
        return 'CMYK'
      case 'lab':
        return 'Lab'
      case 'xyz':
        return 'XYZ'
      case 'grey16':
      case 'b-w':
        return 'Grayscale'
      default:
        return undefined
    }
  }

  /**
   * 根据图片格式获取默认颜色空间
   */
  const getDefaultColorSpaceForFormat = (
    format: string,
  ): string | undefined => {
    const formatLower = format.toLowerCase()
    switch (formatLower) {
      case 'jpeg':
      case 'jpg':
        return 'sRGB' // JPEG 默认使用 sRGB
      case 'png':
        return 'sRGB' // PNG 通常使用 sRGB
      case 'webp':
        return 'sRGB' // WebP 通常使用 sRGB
      case 'tiff':
      case 'tif':
        return 'sRGB' // TIFF 可能使用各种颜色空间,默认 sRGB
      case 'heif':
      case 'heic':
        return 'Display P3' // HEIC 通常支持 Display P3
      case 'avif':
        return 'sRGB' // AVIF 通常使用 sRGB,但也可能支持其他
      case 'gif':
        return 'sRGB' // GIF 使用 sRGB
      case 'bmp':
        return 'sRGB' // BMP 通常使用 sRGB
      default:
        return undefined
    }
  }

  const processExifData = (exifData: Tags, metadata: Metadata): NeededExif => {
    const date = {
      DateTimeOriginal: formatExifDate(exifData.DateTimeOriginal),
      DateTimeDigitized: formatExifDate(exifData.DateTimeDigitized),
      OffsetTime: exifData.OffsetTime,
      OffsetTimeOriginal: exifData.OffsetTimeOriginal,
      OffsetTimeDigitized: exifData.OffsetTimeDigitized,
    }

    const size = {
      ImageWidth: exifData.ExifImageWidth || metadata.width,
      ImageHeight: exifData.ExifImageHeight || metadata.height,
    }

    const result: any = structuredClone(exifData)
    for (const key in result) {
      Reflect.deleteProperty(result, key)
    }
    for (const key of neededKeys) {
      result[key] = (exifData as any)[key]
    }

    // 优先从 metadata 推断颜色空间
    const inferredColorSpace = inferColorSpaceFromMetadata(metadata)
    if (inferredColorSpace) {
      result.ColorSpace = inferredColorSpace
    } else if (!result.ColorSpace) {
      // 推断失败且 exif 中也没有 ColorSpace
      // ignore
    }

    return {
      ...date,
      ...size,
      ...result,
    }
  }

  const extractExifData = async (
    imageBuffer: Buffer,
    rawImageBuffer?: Buffer,
    logger?: MediaLogger,
  ): Promise<NeededExif | null> => {
    try {
      return await withRetry(
        async () => {
          let tempImagePath: string | null = null

          try {
            // 提取基础元数据
            let metadata = await sharp(imageBuffer).metadata()

            // 如果主buffer没有EXIF,尝试原始buffer
            if (!metadata.exif && rawImageBuffer) {
              try {
                metadata = await sharp(rawImageBuffer).metadata()
              } catch (err) {
                logger?.warn(
                  'Error extracting EXIF data from raw image buffer:',
                  err,
                )
              }
            }

            if (!metadata.exif) {
              logger?.warn('No EXIF data found in image metadata')
              return null
            }

            logger?.info('Extracting EXIF data using exiftool...')

            // 创建临时工作目录
            // The application owns the work directory and ExifTool lifecycle.
            await mkdir(tempDir, { recursive: true })
            tempImagePath = path.resolve(tempDir, `${randomUUID()}.jpg`)

            // 写入临时文件
            await writeFile(tempImagePath, rawImageBuffer || imageBuffer)

            // 使用 exiftool 读取详细 EXIF 数据
            const exifData = await exiftool.read(tempImagePath)
            const result = processExifData(exifData, metadata)

            // 记录颜色空间信息
            if (result.ColorSpace) {
              logger?.success(`Inferred ColorSpace: ${result.ColorSpace}`)
            } else {
              logger?.info('ColorSpace could not be determined')
            }

            return result
          } finally {
            // 确保清理临时文件
            if (tempImagePath) {
              await unlink(tempImagePath).catch(noop)
            }
          }
        },
        {
          ...RetryPresets.standard,
          timeout: 15000, // EXIF 处理可能需要更长时间
          retryCondition: (error) => {
            // 组合多种重试条件
            return (
              RetryConditions.fileSystemErrors(error) ||
              RetryConditions.resourceErrors(error) ||
              error.message.includes('timeout')
            )
          },
        },
        logger,
      )
    } catch (error) {
      logger?.error('EXIF extraction failed after all retries:', error)
      return null
    }
  }

  const normalizeText = (value: unknown): string | undefined => {
    if (value === null || value === undefined) {
      return undefined
    }

    if (Array.isArray(value)) {
      for (const item of value) {
        const normalized = normalizeText(item)
        if (normalized) {
          return normalized
        }
      }
      return undefined
    }

    const text = String(value).trim()
    return text.length > 0 ? text : undefined
  }

  const collectTextValues = (
    value: unknown,
    options?: { splitDelimited?: boolean },
  ): string[] => {
    const splitDelimited = options?.splitDelimited ?? false
    const results: string[] = []

    const append = (input: string) => {
      if (splitDelimited) {
        for (const part of input.split(/[;,]/)) {
          const chunk = part.trim()
          if (chunk.length > 0) {
            results.push(chunk)
          }
        }
      } else if (input.length > 0) {
        results.push(input)
      }
    }

    if (value === null || value === undefined) {
      return results
    }

    if (Array.isArray(value)) {
      for (const item of value) {
        const normalized = normalizeText(item)
        if (normalized) {
          append(normalized)
        }
      }
      return results
    }

    const normalized = normalizeText(value)
    if (normalized) {
      append(normalized)
    }

    return results
  }

  const pickFirstText = (...values: Array<unknown>): string | undefined => {
    for (const value of values) {
      const normalized = normalizeText(value)
      if (normalized) {
        return normalized
      }
    }

    return undefined
  }

  const extractPhotoInfo = (
    s3key: string,
    exifData?: NeededExif | null,
  ): PhotoInfo => {
    const fileName = path.basename(s3key, path.extname(s3key))

    let dateTaken = new Date().toISOString()
    const tagsSet = new Set<string>()

    for (const tag of collectTextValues(exifData?.Subject)) {
      tagsSet.add(tag)
    }

    for (const tag of collectTextValues(exifData?.Keywords)) {
      tagsSet.add(tag)
    }

    for (const tag of collectTextValues(exifData?.XPKeywords, {
      splitDelimited: true,
    })) {
      tagsSet.add(tag)
    }

    if (exifData?.DateTimeOriginal) {
      const dateTimeOriginal = toValidISOString(exifData.DateTimeOriginal)

      if (dateTimeOriginal) {
        dateTaken = dateTimeOriginal
      } else {
        serviceLogger?.warn(
          `Parse EXIF DateTimeOriginal failed: ${exifData.DateTimeOriginal}`,
        )
      }
    } else {
      // The match may be a false positive inside a longer digit run
      // (e.g. "9101-28-18" in "IMG119101-28-18.jpg"), so validate before use.
      const dateMatch = fileName.match(/(\d{4}-\d{2}-\d{2})/)
      const dateFromFileName = dateMatch
        ? toValidISOString(dateMatch[1]!)
        : undefined
      if (dateFromFileName) {
        dateTaken = dateFromFileName
      }
    }

    const titleFromExif = pickFirstText(
      exifData?.Title,
      exifData?.XPTitle,
      exifData?.Description,
      exifData?.ImageDescription,
      exifData?.CaptionAbstract,
    )

    let title = titleFromExif
    const cleanedFileName = fileName
      .replaceAll(/\d{4}-\d{2}-\d{2}[_-]?/g, '')
      .replaceAll(/[_-]?\d+views?/gi, '')
      .replaceAll(/[_-]+/g, ' ')
      .trim()

    if (!title) {
      title = cleanedFileName || path.basename(s3key, path.extname(s3key))
    }

    const description =
      pickFirstText(
        exifData?.Description,
        exifData?.ImageDescription,
        exifData?.CaptionAbstract,
        exifData?.XPComment,
        exifData?.UserComment,
      ) || ''

    return {
      title,
      dateTaken,
      tags: [...tagsSet],
      description,
    }
  }

  return { extractExifData, extractPhotoInfo }
}