Add HEIC false positive fix for iOS 18 files (v2.5.52)

HEIC files from iOS 18 devices were incorrectly flagged as corrupted due
to older libheif versions not supporting shared auxiliary images feature.

- Detect libheif "auxiliary image" errors in ImageMagick stderr
- Detect "cannot identify" errors on HEIC files in PIL
- Treat these as warnings instead of corruption flags
- Files now show as "HEIC validation skipped: libheif version limitation"

Ref: github.com/strukturag/libheif/issues/1190

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: ttlequals0

CHANGELOG.MD

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0).
 
+## [2.5.52] - 2026-01-01
+
+### Bug Fixes
+
+- **Fix HEIC false positive corruption detection for iOS 18 files**: HEIC files from iOS 18 devices were incorrectly flagged as corrupted
+  - Root cause: Older libheif versions (Ubuntu 24.04 ships 1.17.x) don't support iOS 18's use of shared auxiliary images
+  - Error message: `"Too many auxiliary image references (2.0)"` from libheif/ImageMagick
+  - This is a valid HEIF structure per spec, not file corruption (see: github.com/strukturag/libheif/issues/1190)
+  - **Solution**: Detect libheif limitation errors and treat as warnings instead of corruption
+    - Added detection for "auxiliary image" and "too many auxiliary" errors in ImageMagick stderr
+    - Added detection for "cannot identify image file" errors on HEIC files in PIL
+    - Files with this error now show as warning "HEIC validation skipped: libheif version limitation"
+    - Files are no longer incorrectly marked as corrupted
+  - Note: Full iOS 18 HEIC support requires libheif 1.19.8+ (not yet available in Ubuntu repos)
+  - Files affected: `media_checker.py`
+
+---
+
 ## [2.5.51] - 2026-01-01
 
 ### Bug Fixes

media_checker.py

@@ -909,14 +909,20 @@ def _check_image_corruption(self, file_path):
             except Exception as e:
                 pil_load_failed = True
                 pil_load_error = str(e)
+                error_lower = str(e).lower()
                 scan_output.append(f"PIL load/transform: FAILED - {str(e)}")
-                
+
                 # Check for truncation errors - these indicate actual corruption
-                if 'truncated' in str(e).lower() or 'bytes not processed' in str(e).lower():
+                if 'truncated' in error_lower or 'bytes not processed' in error_lower:
                     logger.warning(f"Image truncation detected for {file_path}: {str(e)}")
                     corruption_details.append(f"Image file is truncated: {str(e)}")
                     is_corrupted = True
                     scan_tool = "pil"
+                # HEIC files with "cannot identify" may be due to libheif limitations, not corruption
+                # Don't mark as corrupted here - let ImageMagick verify (which will also catch the libheif error)
+                elif is_heic and 'cannot identify image file' in error_lower:
+                    logger.info(f"HEIC PIL load failed (may be libheif limitation) for {file_path}: {str(e)}")
+                    # Don't mark as corrupted yet - ImageMagick will provide the definitive answer
 
         logger.info(f"Starting ImageMagick verification for: {file_path}")
 
@@ -959,6 +965,15 @@ def _check_image_corruption(self, file_path):
                     if is_gif and 'improper image header' in stderr_lower and 'readgifimage' in stderr_lower:
                         # This is a common false positive for GIFs that still work
                         logger.info(f"GIF header warning (not corruption) for {file_path}")
+                    # Check for HEIC/HEIF libheif limitation errors (iOS 18 files with shared auxiliary images)
+                    # These are NOT corruption - older libheif versions don't support newer HEIC features
+                    # See: https://github.com/strukturag/libheif/issues/1190
+                    elif is_heic and ('auxiliary image' in stderr_lower or 'too many auxiliary' in stderr_lower):
+                        warning_details.append("HEIC validation skipped: libheif version limitation (file likely valid)")
+                        scan_output.append("ImageMagick HEIC: SKIPPED (libheif limitation - not corruption)")
+                        scan_output.append(f"Note: iOS 18+ HEIC files may use features not supported by older libheif versions")
+                        logger.info(f"HEIC libheif limitation (not corruption) for {file_path}: {result.stderr[:100]}")
+                        # Don't mark as corrupted - this is a tool limitation, not file corruption
                     else:
                         corruption_details.append("ImageMagick pixel validation failed")
                         is_corrupted = True

version.py

@@ -4,7 +4,7 @@
 # Default version - this is the single source of truth
 
 
-_DEFAULT_VERSION = '2.5.51'
+_DEFAULT_VERSION = '2.5.52'
 
 
 # Allow override via environment variable for CI/CD, but default to the hardcoded version