Converting RAW to HEIC inside Apple Photos: App Intents, HDR gain maps, and never losing a metadata field

I built an iOS/iPadOS/macOS app called RawToHEIC. The pitch is one sentence: you select RAW photos in the Photos app, tap Share, pick "Convert RAW to HEIC," and a few seconds later your library has HEICs that are up to 10× smaller — with every edit, album, favorite, and GPS coordinate intact.

That sentence took an order of magnitude more engineering than it sounds like. This post is the part developers actually want: where the hard parts were, the decisions I'd defend, and the platform behavior that cost me days. If you're building anything that touches PhotoKit, ImageIO, or App Intents, some of this will save you time.

Why an App Intent, and specifically not a Share Extension

The first real decision shaped everything else. There are two obvious ways to put "do something with these photos" into the Photos Share sheet: a classic Share Extension, or an App Intent.

A Share Extension feels like the natural choice. It's the old, well-trodden path. But it has a fatal limitation for this particular app: extensions run in a sandboxed, memory-constrained host process with a restricted permission surface. Crucially, the operation at the heart of this app — deleting the user's RAW originals from their Photos library after a successful conversion — requires deleteAssets, and that requires app-level Photos permissions that an extension host doesn't grant the way a full app does.

App Intents are the answer. An App Intent invoked from the Share sheet runs with the parent app's identity and permissions. So the architecture became: the intent is a thin entry point that collects the selected assets and hands the actual work to the main app, which has the permissions to write and (with confirmation) delete in the library.

This also solved a memory problem before it started. Intent-hosting UI on iOS lives under tight memory limits — the inline "Snippet" you show in the Share sheet has to stay lean. So conversion does not run in the intent context. The intent shows the estimate and confirmation Snippet; the heavy lifting — decode, encode, library writes — happens in the main app process where there's room to breathe. The design rule I held myself to: the Snippet stays within about 10 MB over baseline, and no pixel-crunching happens inside it.

One target, SwiftUI multiplatform, no Mac Catalyst, no separate extension target. One AppIntent as the front door. If you're weighing Share Extension vs. App Intent for anything that needs real library mutation, that permission asymmetry is the deciding factor, and it's not well advertised.

The data-integrity invariants, because this app deletes people's photos

Here's the thing that kept me up at night. The entire value proposition is reclaiming storage, which means deleting RAW originals. An app that occasionally loses someone's photo is not a storage app, it's a tragedy generator. So before I wrote much conversion code, I wrote down the invariants the system must never violate, and I enforce them with precondition in debug builds and with unit tests.

The non-negotiable ones:

• A RAW is never deleted before its HEIC is successfully written to Photos and verified by a synchronous PHAsset.fetchAssets lookup. Not "the write returned success." Verified present, by fetching it back. The order is sacred: convert, write, fetch-to-confirm, then the original becomes eligible for deletion.
• Deletes are batched. Exactly one deleteAssets call per batch, never one call per asset. This matters both for the UX (a single system confirmation prompt instead of death-by-a-thousand-dialogs) and for atomicity.
• If the user didn't opt into deletion, the delete code path is not merely skipped — it's unreachable. Guarded by precondition. "Off" doesn't mean "we chose not to call it." It means there is no live path to the deletion call at all.
• Temp HEIC files are moved, not copied, into Photos, and unlinked in the same change block. No orphaned temp files, no double the disk usage mid-flight.
• If the app is killed mid-batch, partial deletion is impossible. Because deletion only happens in one batched call after all conversions have drained and been verified, a crash at any earlier point leaves every original untouched. Even termination during the system delete prompt results in no deletion, because PhotoKit cancels unresolved change requests.

There's a subtler one that took a real-world failure to appreciate. Re-linking a converted HEIC into its original album is a separate PhotoKit change request, and it can fail independently. The rule: if the album re-link fails, keep the new HEIC, flag the asset as a partial restore, and do not delete the original — regardless of the batch's delete setting. A photo that lost its album home is not a successful conversion, so its original earns a stay of execution. Better a duplicate than an orphan.

If you take one thing from this section: when your app does something irreversible to user data, write the safety invariants down as explicit, testable assertions first, in plain language, before you write the feature. They become both your spec and your regression net.

Keeping everything: edits, albums, favorites, locations

"Convert the photo" is the easy 20%. "Convert the photo and have it still be the same entry in the user's library" is the other 80%.

A naive converter produces a fresh image stripped of context: no album membership, no favorite status, no caption, dropped EXIF and GPS, original creation date replaced by "now." That's worthless for a real library. So a large chunk of the work is metadata and relationship preservation:

• EXIF / TIFF / GPS / orientation / camera settings are carried forward at encode time. The encoder writes the source's properties into the HEIC as it's created, rather than trying to patch them in afterward (more on why "afterward" is a trap below).
• Album membership is restored by re-adding the new asset to each collection the original belonged to — and as noted above, a failure here vetoes the original's deletion.
• Favorites, captions, creation date are mirrored onto the new asset via PHAssetChangeRequest.

The encode-time-vs-after-the-fact distinction matters more than I expected, which brings me to the gotchas.

ImageIO and PhotoKit will lie to you politely

Several days of this project were spent discovering platform behavior that is technically documented somewhere but bites hard in practice. A few that are worth knowing if you're in this neighborhood:

Auxiliary data (gain maps) silently drops on finalize if the dictionary is incomplete. CGImageDestinationAddAuxiliaryDataInfo will happily accept your aux data and then drop it on CGImageDestinationFinalize if the dictionary is missing kCGImageAuxiliaryDataInfoDataDescription (width, height, pixel format, bytes-per-row). No error. The file just finalizes without the gain map. For ISO 21496-1 aux specifically, you also need the Metadata entry, or the aux writes empty. And the Metadata field is a CGImageMetadata ref, not Data — if you try to round-trip it with a naive as? Data cast it silently fails, and you have to go through CGImageMetadataCreateXMPData / CGImageMetadataCreateFromXMPData. None of these failures announce themselves. You find them by opening the output and noticing the HDR is gone.

Re-encoding a decoded gain-mapped HEIC primary fails Finalize on iOS 26. If you decode a gain-mapped HEIC and try to write it back out through any CGImageDestination path to patch metadata after the fact, finalize fails. The lossless CGImageDestinationCopyImageSource works, but its XMP merge can't populate the classic EXIF/TIFF property dictionaries. The practical consequence drove an architecture decision: write metadata at original encode time, not as a post-pass. If you're planning a "convert now, fix metadata later" pipeline, test that assumption early, because on current OSes the later step may not exist.

Some metadata just doesn't survive HEIC, period. Canon's MakerNote, for instance, doesn't make it through HEIC encoding — that's an ImageIO/HEIC platform limitation, not something I can fix. I keep a regression test that asserts the loss so I notice if the platform ever changes, but I'm honest in the app's design that it's a known boundary.

Auxiliary metadata doesn't round-trip via the public API. kCGImageAuxiliaryDataInfoMetadata does not come back via CGImageSourceCopyAuxiliaryDataInfoAtIndex on macOS 15 / iOS 18. The apple:HDRGainMapHeadroom XMP tag gets written (Photos itself presumably reads it via private API) but you can't read it back publicly to assert on it. The lesson for testing: assert on observable contracts, not on values the public API won't return to you.

The meta-lesson across all of these: ImageIO's failure mode is silence. It returns success and gives you a subtly wrong file. The only defense is to read your own output back and verify properties, which — usefully — is the same discipline the delete-safety invariants already demanded.

HDR is where it got genuinely interesting

Modern photos carry HDR via a gain map — a secondary image that tells a display how to brighten highlights beyond SDR. Preserving or synthesizing that correctly is most of what separates a serious converter from a toy.

The policy I landed on has three branches:

1. iPhone ProRAW DNG: render an HDR companion via CIRAWFilter's extendedDynamicRangeAmount, then let ImageIO compute the calibrated auxiliary gain map from the (SDR, HDR) pair. I tried extracting the embedded aux from the ProRAW DNG directly and removed it — it required boostShadowAmount = 0 to match Apple's private SDR base, which made the file render dark in non-HDR-aware viewers like Quick Look and browsers. Letting ImageIO derive the aux from a proper SDR/HDR pair produces a file that looks right everywhere, which matters more than matching one private code path.
2. Other RAW (Canon, Sony, Nikon, Fuji…): synthesize an ISO 21496-1 gain map from the RAW's extended dynamic range, where the sensor data actually supports it. Don't fabricate HDR that wasn't captured.
3. Edited-in-Photos inputs: flat SDR. If someone already baked their look in Photos, inventing an HDR interpretation on top is the wrong call.

The principle underneath all three: match what the source genuinely contains, and produce a file that degrades gracefully on viewers that don't understand gain maps. HDR that only looks right in one app isn't preserved, it's trapped.

Making a long batch feel calm

Converting five hundred RAWs is not instant, so the UX problem is "don't make the user stare at a spinner or babysit the app."

• Live Activity via ActivityKit shows progress on the Lock Screen and Dynamic Island on iPhone/iPad, and a menu-bar tile on Mac. Content updates are rate-limited to ≤ 1 Hz with a coalescing limiter — ActivityKit punishes chatty updates, and nobody needs 60 fps progress text.
• iOS 26's BGContinuedProcessingTask lets large batches keep running with the screen off, which is the difference between "convert your whole library" being realistic or not.
• On iOS/iPadOS, conversion is a serial async loop — one item at a time, deliberately, to stay well within memory limits. On macOS there's an opt-in Turbo Mode that runs bounded-concurrent (a heuristic on cores and memory, clamped to 2–6 and never exceeding cores − 2). The single batched deleteAssets still runs exactly once after everything drains. The heavy per-item render runs off the actor; the bookkeeping — DB writes, progress, outcome recording — stays serialized on it. PhotoKit writes are funneled through a single PhotoLibrary actor so they're always ordered.

There's a SQLite-backed queue underneath so a batch is durable and resumable, and database migrations run exactly once at launch before any data access — boring infrastructure that earns its keep the first time someone force-quits mid-batch and reopens to find their place held.

What I'd tell another developer

Three things, if you're building in this space:

1. Decide App Intent vs. Share Extension by the permissions you need, not by familiarity. If you need to mutate or delete library assets, the App Intent path is the one that actually works.
2. Write your irreversible-action safety rules as explicit, testable invariants before the feature exists. "Verify before delete, batch the deletes, make the off-path unreachable" reads like common sense and is shockingly easy to violate by accident under refactoring. Tests are how you keep it true.
3. Trust nothing ImageIO returns; read your output back. Its failure mode is a confident success with a quietly wrong file. Verification isn't paranoia here, it's the contract.

If you want to see the result of all this, RawToHEIC is on the App Store — a one-time $19.99, universal across iPhone, iPad, and Mac, fully on-device, zero telemetry. There's more on the formats and the HDR handling at rawtoheic.app. And if you're a developer hitting any of these same ImageIO or PhotoKit walls, my inbox is open — I learned most of this the slow way and I'm happy to compare notes.