Support HEIC/HEIF Uploads via Automatic Server-Side Conversion (AVIF/JPEG) on Import

[fendtinger]

Enhancement

Lychee currently allows HEIC/HEIF files to be uploaded only when they are treated as “not processed” or accepted raw media. While uploads succeed, Lychee cannot generate previews or thumbnails for these files (stored in Digital Ocean Space/S3), even on systems where ImageMagick has full HEIC/HEIF support enabled. This leads to a poor user experience, as modern devices (especially iOS) commonly produce HEIC images by default.

Proposed Improvement
Introduce an optional, server-side preprocessing step during upload/import which automatically converts HEIC/HEIF images into a supported image format (preferably AVIF, alternatively JPEG/PNG) before Lychee’s media-type validation and thumbnail generation pipeline runs.

Key Points
• Conversion happens early in the upload/import flow (e.g. when instantiating the local file abstraction).
• Uses existing ImageMagick support when available (no new hard dependency).
• Resulting file replaces or transparently supersedes the original HEIC file for further processing.
• Keeps the original file untouched if conversion fails.
• Fully compatible with S3 / remote storage setups, as conversion occurs while the file is still local/temporary.

Benefits
• Native HEIC support without marking files as “not processed”.
• Thumbnails, previews, EXIF handling, and optimization pipelines work as expected.
• Aligns Lychee with modern camera defaults on iOS and macOS.
• Backwards compatible and optional (can be disabled via config).

Implementation Sketch
• Add a configurable hook in the upload/import pipeline (e.g. NativeLocalFile or equivalent).
• Detect HEIC/HEIF extensions early.
• Convert using ImageMagick to AVIF (preferred) or JPEG.
• Continue processing using the converted file path.

I am willing to contribute code and help refine the implementation to match Lychee’s architectural and quality standards.

[ildyria]

Hi @fendtinger

I am willing to contribute code and help refine the implementation to match Lychee’s architectural and quality standards.

Go for it! :) If you have questions about the architecture of Lychee, I tried to make some documentation in:
https://github.com/LycheeOrg/Lychee/tree/master/docs and
https://github.com/LycheeOrg/Lychee/tree/master/app/Actions/Photo#readme

I think I would extend it to being a pre-processing step (probably in the standalone queue), this would also allow Lychee to also support RAW files if then can be converted.

If you have question, you can post them here or ping us on discord, to your preference.

[fendtinger]

@ildyria ok thank you, we've started implementing :)

[ildyria]

AVIF has been added btw :)