Goal: There should be less friction when sharing great HDR app experiences on the web. This macOS Hammerspoon script takes a clipboard full of HDR HEIC data from Screenshot.app (or ⇧⌘⌃4) and, on a quick double-paste, converts it into whatever a GitHub issue or similar website actually accepts:
- a web-standard lossy JPEG with an Ultra HDR gain map (
uhdr), - a Safari/Preview-faithful 16-bit lossless PNG (
png-hdr), - the new lossless non-proprietary HDR AVIF format (
avif, not for GitHub yet), - or a universal 8-bit PNG (
png-sdr), to avoid switching Screenshot.app’s capture format manually.
Cycle modes with ⌃⌥⌘-H.
Situation: In macOS 26 Tahoe, when enabled as shown below, Screenshot.app and screencapture can capture HDR screenshots, including via the normal clipboard keyboard shortcuts (e.g. ⌃⇧⌘-4).
HDR formats are complex, evolving, and not always lossless. Apple’s semi-proprietary lossless HDR HEIC encoding doesn’t render in most web browsers or survive through website uploads. PNG has no standard HDR mechanism. PNG can carry 16-bit HDR data as a container, but only Safari and Preview know what to do with it. Other viewers read the 16-bit PNG’s pixel values as ordinary sRGB, so the image looks blown out rather than merely flat.
Problem: After switching Screenshot.app to HDR Capture Mode, pasting the HEIC into a GitHub text box in Safari does nothing. GitHub silently drops it. Chrome-based browsers instead convert the HEIC to PNG client-side before upload, which strips the HDR data and uploads a washed-out image.
Solution: Paste twice quickly in Safari. Hammerspoon runs a Swift snippet heic-hdr-decode to read the HEIC out as a macOS-only PNG or a TIFF. This part has to stay Apple-only. It reads proprietary tone-curve metadata that no cross-platform library understands. From there, libvips can optionally convert that TIFF into an Ultra HDR (uhdr) JPEG, which gets written back to the clipboard in place of the original HEIC.
As I understand it, --interpretation scrgb isn’t a complete match to P3. So there’s noticeable loss in gamut versus the original HEIC. It’s directionally correct, though.
Dependencies: brew install libvips for uhdr jpg, brew install libavif for avif, XCode CLI tools (for swiftc), Hammerspoon.
The Underlying Commands the Script Uses
sleep 10; screencapture -H -theic -x ~/Desktop/screenshot-screenshot4.heic
# uhdr
~/.hammerspoon/bin/heic-hdr-decode ~/Desktop/screenshot-screenshot4.heic /tmp/test5.tiff uhdr
vips copy /tmp/test5.tiff /tmp/test4-uhdr.jpg --interpretation scrgb
# avif
~/.hammerspoon/bin/heic-hdr-decode "~/Desktop/screenshot-screenshot4.heic" /tmp/test-hdr.png png-hdr
avifenc --ignore-icc --cicp 12/16/1 -d 10 /tmp/test-hdr.png /tmp/test-avifenc.avifHow to Configure Screenshot.app Capture Format and Example of HEIC -> Ultra HDR JPEG:
Limitations & Notes:
- LLMs were used to create this script and examine the possibility space around these HDR formats.
- The lossless AVIF format is not supported in many website uploads.
- Tests were done using https://www.wide-gamut.com/test/image-hdr
- Quick check for HDR that I noticed: only foreground app can show HDR on macOS. Switch to Finder next to this Safari window with HDR images. Safari will drop the extra brightness becoming less bright for these HDR images. SDR images unaffected.
Comparisons
Either of the original HEIC files can be viewed by pressing the “Raw” button on the Gist below, especially in Safari.
| HDR capture and clipboard conversion to lossy JPEG UHDR | PNG SDR capture |
|---|---|
See Also
- HEIC Converter.app (No HDR support)
- https://heic-converter-app.com