JPEG XL is an outstanding format – much better compression ratios than JPEG or WebP, faster than AVIF, and a good lossless mode which generally beats PNG and WebP (unlike AVIF!). It also includes a magical method of losslessly compressing existing JPEGs, shrinking them on average 20% in a totally reversible manner. Happily, support for the format is picking up – decoding is enabled by default as of Chrome 155 and Firefox 158, and GNOME, KDE, macOS and Windows (the latter with the ‘JPEG XL Image Extension’) all handle it. Android is the outlier, but if we’re lucky we could see it included in Android 18 in 2027.
Immich gained support with version 3.4.0 in November 2026, and this was my signal to convert my decades of JPEGs. In general, this is as simple as running cjxl photo.jpg photo.jxl, but the process was more involved for HDR and ‘motion photos’.
Effort
cjxl takes an --effort (-e) parameter from 1 to 10, defaulting to 7. The original JPEG is retrievable no matter the effort level – it only affects the encoding time and output size. I ran cjxl (libjxl 0.11.2) over about 20,000 photos to measure:
| Effort | Median encode | Total CPU | Time vs e7 | % smaller than original JPEG |
|---|---|---|---|---|
| 7 | 0.34 s | 1.8 h | 1.0× | 19.49% |
| 8 | 0.76 s | 4.0 h | 2.2× | 19.58% |
| 9 | 4.14 s | 24.6 h | 13.5× | 19.63% |
| 10 | 4.72 s | 27.9 h | 15.4× | 19.59% |
The overall size difference is tiny, but 9 resulted in the best compression ratios most of the time, at the cost of being more than an order of magnitude slower than 7. Interestingly, 10 almost never (~0.25%) beat 9 in my tests, despite being the slowest option (and where it did win, the difference was tens of bytes). 8 won about 12% of the time and even 7 won about 2% of the time. For a one-off archiving operation, you might as well shave off a few extra bytes with 9, but if you’re starved for CPU, 7 will get you almost the same results in much less time.
Motion photos
Google’s Motion Photo format is a somewhat cursed ‘extension’ to JPEG/HEIC/AVIF which involves appending an MP4 to a still image. This isn’t so bad for HEIC and AVIF, which inherit from ISOBMFF and store the video cleanly in an mpvd box after the primary image’s boxes, but for JPEGs the MP4 is stored after the ‘end-of-image’ (EOI) marker. Google Photos and Immich support reading these videos, but for most software it just looks like junk at the end of the file and is likely to be deleted upon save.
JXL has no built-in support for embedded MP4s, and really nor should it. Its boxes are ISOBMFF-shaped, so an mpvd box would be skipped rather than breaking anything, but nothing in libjxl reads or writes one – the video would be ignored junk there, too. Running cjxl --lossless_jpeg 1 naïvely will orphan the video data inside the converted JXL’s jbrd box (or, if it’s too big, refuse the conversion entirely) and the video certainly won’t be read by any software (but would still be intact after running djxl to retrieve the original JPEG).
Apple’s competing Live Photos more sensibly store a still image (JPEG or HEIC) and QuickTime video (MOV) side-by-side as separate files, linked by metadata. I took this approach for my library: extract the MP4 from the end of any motion photos before converting the JPEG and store it side-by-side with the JXL (photo.MP.jxl + photo.MP.mp4, photo.MP.jpg being Google’s original naming convention), linking the two in Immich so the video doesn’t show up separately.
Finding the true end of the JPEG
It’s not enough to look for the EOI marker (FF D9) by itself – a gain map (see below) contains its own EOI marker, and that byte pair might appear inside the appended MP4. Look for FF D9 followed immediately by an MP4 box header with type ftyp, rather than accepting arbitrary trailer data. It’s also worth sanity checking the declared box size.
Not every phone puts the video right after the EOI marker – I noticed some files from older Google Pixel phones left an aecDebug blob in between; the fallback is to use the (since deprecated) Camera:MicroVideoOffset attribute to find the offset, measured from the end of the file (the video starts at file size - MicroVideoOffset). Newer files drop that tag in favour of the motion photo’s Container:Directory, which lists every item in the file by type and length; ExifTool reports those as DirectoryItemSemantic and DirectoryItemLength, one value per item, e.g. Primary, GainMap, MotionPhoto and 0, 9883, 4762407 – the last length belonging to the video.
Before deleting the original JPEG, make sure it can be reconstructed:
djxlshould rebuild the JPEG prefix (minus the trailing MP4) byte-for-byte.- appending the MP4 to the rebuilt prefix should result in the original JPEG byte-for-byte.
Orphaned metadata
The above approach does leave some metadata stuck in jbrd, most notably Camera:MotionPhotoPresentationTimestampUs, which points to the time in the video where the still image appears. One could move this into the MP4’s metadata, but nothing would read it, and modifying the MP4 breaks the byte-for-byte reconstruction process above.
HDR gain maps
JPEG was standardised decades before high-dynamic-range (HDR) content was a consideration. Google’s solution is Ultra HDR: a gain map is stored as a second JPEG, usually at reduced width/height, after the EOI marker for the primary SDR image. Old decoders ignore everything after the EOI and display the SDR image normally; newer browsers and operating systems will apply the gain map in an HDR environment.
JPEG XL natively supports HDR – either by carrying HDR pixels directly, or as an SDR image plus a gain map to be applied on HDR displays. A separate gain map improves backwards compatibility and gives more control over rendering on SDR screens, rather than relying on the system to algorithmically tone map HDR content to SDR. JPEG XL gain maps belong in the jhgm box, but unfortunately cjxl as it stands will leave Ultra HDR JPEG gain maps – and any other unknown trailing bytes, like motion photo MP4s – sitting inert in jbrd. We’d end up with an SDR JXL whose gain map sits only inside that blob – djxl can still get the original file back, but no viewer will ever apply the gain map – so we need to do the work ourselves during conversion.
Building the jhgm box
Ultra HDR JPEGs contain a primary SDR JPEG, a gain map appended after the EOI and some metadata (usually an MPF entry plus hdrgm XMP) tying them together. Newer files also carry an ISO 21496-1 block in the gain map’s APP2 segment, while older files only have the XMP values, so the builder can synthesise the ISO block from GainMapMin, GainMapMax, Gamma, the offsets and the HDR capacity range.
The conversion process is as follows:
- Find the primary image’s EOI marker and use the metadata to find the appended gain map JPEG (must be a complete JPEG with ISO 21496-1 metadata, or equivalent XMP values).
- Encode the primary image as JXL (up to and including the EOI – not including the gain map).
- Encode the gain map JPEG as its own JXL, then split that container into metadata boxes and its bare codestream.
- Build a
jhgmpayload containing the ISO 21496-1 metadata, an empty colour-encoding/ICC field and the gain map codestream; insert it after theftypbox.
If we care about being able to reconstruct the original JPEG later, store some extra data in private boxes:
jxgrholds what’s needed to put the gain map back: the gain map’s original offset and length, the original file size, the gain map’s SHA-256 and reconstruction boxes.jxtlholds any other trailer data (deflate-compressed).- Verify that
djxlrebuilds the primary SDR image, thatjxlinfo -vreports ajhgmbox and that a full restore is byte-for-byte identical to the original file.
Note that photos might have both an Ultra HDR gain map and motion photo MP4 in the one file.
Other metadata
Previews
I found that photos from my DJI Mavic Air 2 drone contained reduced-size previews at the end of the file. This makes sense for slow wireless connections when using the drone, but they’re pointless for this archive, so I deleted them before converting to JXL (otherwise they’d end up in jbrd, unused).
Samsung metadata
I also had a few photos (mostly panoramas) with some Samsung ‘SEFT’ metadata. This is undocumented and likely useless outside the Samsung ecosystem, but I didn’t want to leave it languishing inside jbrd with nothing reading it, so I left those files as JPEG.
Depth maps
Google’s Pixel Camera app has a toggle for ‘social media depth features’, which embeds two more JPEGs at the end of the file: a depth map and a confidence map that records how sure the camera was of each depth estimate. These sit in the same Container:Directory list as the gain map, e.g. Primary, GainMap, Depth, Confidence. Google Photos uses them for ‘tap-to-refocus’ and adjustable background blur; these camera sensors are small enough that the entire frame is sharp, and a depth map makes the artificial bokeh adjustable after the fact (the blur is not from the lens).
JPEG XL does natively support an extra-channel type for depth, but only downsampled at powers of 2 (half size, quarter size, etc.), and my Pixel 9’s photos come out at 4080×3072px resolution with 1440×1080px depth and confidence maps (for landscape photos; portrait photos have flipped, slightly different aspect ratios) – these would have to be 1020×768px (quarter size) or 2040×1536px (half size) to work cleanly in JXL. The gain map, incidentally, is exactly quarter size.
JPEG XL’s convention is that higher sample values mean a larger distance from the camera, and it doesn’t standardise the scale. Google’s RangeInverse format points the same way, despite the name, but values are spaced in inverse distance – equal steps of 1/metres – rather than evenly in metres. This means that one gets more precision at the near end, where it counts (for focus, the difference between 5 and 10cm is significant, but 5 and 10m less so).
JPEG XL has no well-defined place to record where the near and far planes are, or what kind of scale was used. For example, in Google’s RangeInverse format, a near plane of 1m and far plane of 10m has 256 codes stepping 1/z from 1.0 down to 0.1 – each step is about 3.5mm at the front of that range and 35cm at the back. 128 ends up meaning about 1.8m, not the 5.5m you’d expect from evenly spacing 0–255 out over 1-10m.
The even bigger problem is that there’s no good channel type for confidence – optional would be the best fit, but it’s a stretch, and a private box is the more likely storage location unless the spec gets revised. All of this is moot without Google Photos support, anyway.
JPEG XL in DNG
DNG 1.7 introduced support for JPEG XL, both for losslessly (or lossily) compressing the raw image and for previews. However, the space savings are relatively modest – about 10% for lossless JPEG XL over the lossless JPEG baseline for the raw payload, apparently because camera readouts are inherently quite noisy.
More importantly, compatibility is still thin on the ground (Immich’s bundled libraw isn’t compiled against Adobe’s DNG SDK for licensing reasons and ImageMagick 7.1.2 and darktable baulk at the files). If and when support picks up – unfortunately it seems to be more of a licensing than technical problem – it’s worth revisiting, because 10% over terabytes of data is not nothing.
Scripts
For reference, here is the script for the JXL conversion, including the handling of motion photos and Ultra HDR gain maps:
"""Convert a JPEG library to JPEG XL while keeping every original byte recoverable.
Everything is recoverable except DJI-style preview images, which are deliberately stripped: a reduced-size second
JPEG that exists only for the camera roll.
Three shapes come out of a phone camera, and each needs different handling before and after cjxl:
* A plain JPEG goes straight to `cjxl --lossless_jpeg`, which stores the original file in the container's jbrd box.
`djxl` rebuilds it byte for byte, so there is nothing else to do.
* A motion photo is a JPEG with an MP4 glued on after its own end-of-image marker. cjxl would drag that video into
jbrd as well, where only libjxl can find it again, so the video is cut off first and written beside the still as
`<name>.mp4`. The .jxl keeps the still's bytes and the two files together are the original.
* An HDR gain map is a second JPEG appended the same way. cjxl leaves it in jbrd as inert bytes, so the map is moved
into the jhgm box that decoders look at instead, and the private jxgr/jxtl boxes keep what is needed to put the
original file back together on demand.
Nothing is deleted until the rebuild has been compared byte-for-byte with the file it replaces. The script is a
dry run unless --execute, and it is safe to re-run: an output that already exists is verified rather than overwritten.
./jxl-convert.py --target ~/pictures
./jxl-convert.py --target ~/pictures --execute
./jxl-convert.py --target ~/pictures --link --url http://immich:2283 --api-key KEY # attach each video to its still in Immich
Needs cjxl, djxl and jxlinfo (libjxl 0.11 or newer, where --lossless_jpeg means JPEG recompression). ffprobe is used
to check the extracted videos when it is installed. Python 3.9+.
"""
import argparse
import hashlib
import json
import os
import re
import shutil
import struct
import subprocess
import sys
import tempfile
import urllib.error
import urllib.request
import zlib
from collections import Counter
from pathlib import Path
JPEG_SUFFIXES = (".jpg", ".jpeg", ".jpe", ".jfif")
JXL_SIGNATURE = b"\x00\x00\x00\x0cJXL \r\n\x87\n"
ISO_URN = b"urn:iso:std:iso:ts:21496:-1\x00"
JHGM_VERSION = 0
SIDECAR_VERSION = 2
EOI = b"\xff\xd9"
MPF_PRIMARY = 0x030000
MPF_PREVIEW_TYPES = (0x010001, 0x010002) # Large Thumbnail (VGA / Full HD)
class JxlError(RuntimeError):
pass
# === running tools and hashing =====================================================================================
def run(command):
"""Run a conversion tool, turning a non-zero exit into an exception with its last line of output."""
result = subprocess.run(command, capture_output=True, text=True)
if result.returncode != 0:
lines = (result.stderr or result.stdout).strip().splitlines()
raise JxlError(f"{' '.join(command)} failed: {lines[-1] if lines else 'no output'}")
return result.stdout
def digest(data):
return hashlib.sha256(data).digest()
def size_label(count):
if count >= 2**30:
return f"{count / 2**30:.2f} GiB"
if count >= 2**20:
return f"{count / 2**20:.1f} MiB"
if count >= 1024:
return f"{count / 1024:.0f} KiB"
return f"{count} B"
def encode_jpeg(data, effort, scratch, name):
"""cjxl --lossless_jpeg on these bytes, returning the container bytes."""
source = scratch / name
output = source.with_suffix(".jxl")
source.write_bytes(data)
run(["cjxl", "--lossless_jpeg=1", "-e", str(effort), str(source), str(output)])
return output.read_bytes()
def decode_jpeg(container, scratch, name):
"""djxl these container bytes, returning the JPEG they rebuild."""
source = scratch / (name + ".jxl")
output = scratch / (name + ".jpg")
source.write_bytes(container)
run(["djxl", str(source), str(output), "--num_threads=0"])
return output.read_bytes()
# === reading JPEG structure ========================================================================================
#
# Everything here works on bytes rather than paths: a photo is a few megabytes, the files are read once, and giving
# the parsers data instead of a filename keeps them testable and free of seeking bookkeeping.
def u16(data, offset=0):
return struct.unpack(">H", data[offset:offset + 2])[0]
def u32(data, offset=0):
return struct.unpack(">I", data[offset:offset + 4])[0]
def jpeg_segments(data):
"""Yield (marker, payload, payload offset) from a JPEG header, up to and including the first SOS."""
if data[:2] != b"\xff\xd8":
raise JxlError("not a JPEG (no SOI)")
i = 2
while i + 1 < len(data):
if data[i] != 0xFF:
raise JxlError(f"JPEG marker expected at byte {i}")
while i < len(data) and data[i] == 0xFF:
i += 1
if i >= len(data):
break
marker = data[i]
i += 1
if marker in (0xD8, 0xD9) or 0xD0 <= marker <= 0xD7:
continue
if i + 2 > len(data):
break
length = u16(data, i)
if length < 2 or i + length > len(data):
raise JxlError(f"bad JPEG segment length at byte {i}")
yield marker, data[i + 2:i + length], i + 2
i += length
if marker == 0xDA:
return
def jpeg_end(data):
"""Offset just past the primary JPEG's end-of-image marker.
A JPEG's own bytes can contain FF D9 by chance, so the header is walked marker by marker and the entropy-coded data
after the first SOS is skipped using its byte-stuffing rules rather than searched.
"""
if data[:2] != b"\xff\xd8":
raise JxlError("not a JPEG (no SOI)")
in_scan = False
i = 2
while i + 1 < len(data):
if in_scan:
start = i
while True:
j = data.find(b"\xff", start)
if j < 0 or j + 1 >= len(data):
raise JxlError("JPEG ends inside scan data")
following = data[j + 1]
if following == 0x00 or 0xD0 <= following <= 0xD7:
start = j + 2
continue
break
i = j
in_scan = False
continue
if data[i] != 0xFF:
raise JxlError(f"JPEG marker expected at byte {i}")
while i < len(data) and data[i] == 0xFF:
i += 1
marker = data[i]
i += 1
if marker == 0xD9:
return i
if marker == 0xD8 or 0xD0 <= marker <= 0xD7:
continue
i += u16(data, i)
if marker == 0xDA:
in_scan = True
raise JxlError("JPEG has no EOI")
def app2_payloads(data):
return [payload for marker, payload, _ in jpeg_segments(data) if marker == 0xE2]
def xmp_packets(data):
"""The XMP packet from each APP1 segment that carries one."""
prefix = b"http://ns.adobe.com/xap/1.0/\x00"
return [payload.split(b"\x00", 1)[1] for marker, payload, _ in jpeg_segments(data)
if marker == 0xE1 and payload.startswith(prefix)]
def xmp_text(data):
return "\n".join(packet.decode("utf-8", "replace") for packet in xmp_packets(data))
def mpf_images(data):
"""(type, length, absolute offset) for each image named by the JPEG's MPF APP2 segment."""
for marker, payload, payload_start in jpeg_segments(data):
if marker != 0xE2 or not payload.startswith(b"MPF\x00"):
continue
tiff = payload[4:]
# MPF offsets are relative to the TIFF header at the start of the MPF payload.
base = payload_start + 4
order = {b"II": "<", b"MM": ">"}.get(tiff[:2])
if order is None or len(tiff) < 8:
continue
ifd = struct.unpack(order + "I", tiff[4:8])[0]
if ifd + 2 > len(tiff):
continue
count = struct.unpack(order + "H", tiff[ifd:ifd + 2])[0]
images = []
for index in range(count):
entry = ifd + 2 + index * 12
if entry + 12 > len(tiff):
break
tag, kind, length, value = struct.unpack(order + "HHII", tiff[entry:entry + 12])
if tag != 0xB002:
continue
start = entry + 8 if length <= 4 else value
if start + length > len(tiff):
break
block = tiff[start:start + length]
for offset in range(0, len(block) - 15, 16):
flags, size, position, _depth1, _depth2 = struct.unpack(order + "IIIHH", block[offset:offset + 16])
images.append((flags & 0x00FFFFFF, size, base + position if position else 0))
return images
return []
# === spotting what is attached to the JPEG =========================================================================
def ftyp_box(data, offset):
"""Whether an MP4 box of type ftyp starts at this offset, which is how every appended video begins."""
if offset <= 0 or offset + 8 > len(data):
return False
return data[offset + 4:offset + 8] == b"ftyp" and 8 <= u32(data, offset) <= 4096
def declared_video_lengths(data):
"""Video lengths the file's own tags claim, longest first.
Newer files list every part of the file in the motion photo's Container:Directory; older ones record only
Camera:MicroVideoOffset, measured from the end of the file.
"""
text = xmp_text(data)
lengths = []
for tag in re.findall(r"<Container:Item\b[^>]*>", text, re.S):
if re.search(r'Semantic\s*=\s*["\']MotionPhoto', tag):
length = re.search(r'Length\s*=\s*["\'](\d+)', tag)
if length:
lengths.append(int(length.group(1)))
offset = re.search(r'Camera:MicroVideoOffset\s*=\s*["\'](\d+)', text)
if offset:
lengths.append(int(offset.group(1)))
return sorted(set(lengths), reverse=True)
def video_length(data):
"""Bytes of MP4 appended to the JPEG, or 0.
The first end-of-image marker followed by an MP4 box header settles the common layout, and a stray FF D9 inside the
video's own image data is what makes the "followed by ftyp" test necessary. Older Pixel files leave an aecDebug
blob between the JPEG and the video, so when no marker leads to one, the tags are asked for the length and the
answer is only believed if a video box really starts there.
"""
start = 0
while True:
index = data.find(EOI, start)
if index < 0:
break
if ftyp_box(data, index + 2):
return len(data) - (index + 2)
start = index + 1
for length in declared_video_lengths(data):
if 0 < length < len(data) and ftyp_box(data, len(data) - length):
return length
return 0
def iso_metadata(gain_map_jpeg):
"""The ISO 21496-1 metadata blob from a gain-map JPEG's APP2 segment, or None."""
for payload in app2_payloads(gain_map_jpeg):
index = payload.find(ISO_URN)
if index >= 0:
metadata = payload[index + len(ISO_URN):]
if len(metadata) < 4:
raise JxlError("ISO 21496-1 APP2 segment has no metadata")
return metadata
return None
def xmp_iso_metadata(text):
"""Build the ISO 21496-1 metadata from hdrgm XMP, for maps that predate the APP2 block, or None.
The four values below are what the block cannot be derived without. Gamma and the offsets have defaults, and a
gain map whose base image is already HDR is refused because the payload this script writes assumes an SDR base.
"""
values = {}
hdr_base = False
for name, default in (
("GainMapMin", None),
("GainMapMax", None),
("Gamma", 1.0),
("OffsetSDR", 0.0),
("OffsetHDR", 0.0),
("HDRCapacityMin", None),
("HDRCapacityMax", None),
):
match = re.search(rf'hdrgm:{name}\s*=\s*["\']([-+0-9.eE]+)["\']', text)
if match:
try:
values[name] = float(match.group(1))
except ValueError:
return None
elif default is not None:
values[name] = default
if re.search(r'hdrgm:BaseRenditionIsHDR\s*=\s*["\']True["\']', text, re.I):
hdr_base = True
if hdr_base or any(name not in values for name in ("GainMapMin", "GainMapMax", "HDRCapacityMin", "HDRCapacityMax")):
return None
def rational(value):
denominator = 1_000_000
return struct.pack(">iI", round(value * denominator), denominator)
# Single channel, and the gain map is applied in the baseline image's colour space.
return (
struct.pack(">HHB", 0, 0, 0x40)
+ rational(values["HDRCapacityMin"])
+ rational(values["HDRCapacityMax"])
+ rational(values["GainMapMin"])
+ rational(values["GainMapMax"])
+ rational(values["Gamma"])
+ rational(values["OffsetSDR"])
+ rational(values["OffsetHDR"])
)
def find_gain_map(data, primary_end):
"""(offset, bytes, ISO metadata) for the JPEG's HDR gain map, or None.
The map is a whole JPEG of its own, named either by an MPF entry or by the hdrgm/Container XMP. Both are tried,
and a candidate only counts once an ISO 21496-1 block can be read from it or built from XMP; that check is what
keeps a Pixel Portrait's depth image or a DJI preview from being mistaken for a gain map. The hdrgm values describe
the map, so they are accepted from the map's own packet or from the primary's, whichever the file has.
"""
candidates = []
for _kind, size, offset in mpf_images(data[:primary_end]):
if size and offset >= primary_end and offset + size <= len(data) and data[offset:offset + 2] == b"\xff\xd8":
candidates.append((offset, size))
primary_text = xmp_text(data[:primary_end])
for tag in re.findall(r"<Container:Item\b[^>]*>", primary_text, re.S):
if not re.search(r'Semantic\s*=\s*["\']GainMap', tag):
continue
length = re.search(r'Length\s*=\s*["\'](\d+)', tag)
if not length:
continue
size = int(length.group(1))
for offset in range(primary_end, min(len(data), primary_end + (1 << 20))):
if data[offset:offset + 2] == b"\xff\xd8" and offset + size <= len(data):
candidates.append((offset, size))
break
for offset, size in candidates:
blob = data[offset:offset + size]
if blob[-2:] != EOI:
continue
metadata = iso_metadata(blob) or xmp_iso_metadata(xmp_text(blob)) or xmp_iso_metadata(primary_text)
if metadata:
return offset, blob, metadata
return None
def preview_layout(data):
"""A DJI-style preview bundle, "other" for any MPF layout that is more than that, or "none".
A preview is a second JPEG whose only job is display: a two-image MPF bundle whose second image is a plain JPEG
starting after the primary's end marker and running to the end of the file. Anything else is more than a preview,
and the caller keeps the file whole.
"""
if b"MPF\x00" not in data:
return "none", None
try:
end = jpeg_end(data)
images = mpf_images(data[:end])
except (JxlError, struct.error) as exc:
return "other", f"unreadable MPF/JPEG: {exc}"
segments = [segment for segment in jpeg_segments(data[:end])
if segment[0] == 0xE2 and segment[1].startswith(b"MPF\x00")]
if len(segments) != 1 or len(images) != 2:
return "other", f"{len(segments)} MPF segments, {len(images)} images"
(primary_type, _primary_size, primary_offset), (preview_type, preview_size, preview_offset) = images
if primary_type != MPF_PRIMARY or primary_offset != 0 or preview_type not in MPF_PREVIEW_TYPES:
return "other", f"MPF types {primary_type:#x}/{preview_type:#x}"
if not preview_size or preview_offset < end or data[end:preview_offset].strip(b"\0"):
return "other", "preview does not follow the primary JPEG"
preview = data[preview_offset:preview_offset + preview_size]
if not preview.startswith(b"\xff\xd8") or not preview.endswith(EOI):
return "other", "invalid preview JPEG"
if data[preview_offset + preview_size:].strip(b"\0"):
return "other", "non-zero bytes after the preview"
# A capture bundle can carry a small second JPEG too; that one is not a preview.
_marker, payload, payload_start = segments[0]
return "preview", {
"size": preview_size,
"primary_end": end,
"mpf_start": payload_start - 4,
"mpf_end": payload_start + len(payload),
}
def strip_preview(data, info):
"""The file with the preview JPEG and the MPF segment that names it removed."""
stripped = data[:info["mpf_start"]] + data[info["mpf_end"]:info["primary_end"]]
if jpeg_end(stripped) != len(stripped):
raise JxlError("the stripped JPEG does not end at its own EOI")
return stripped
def capture_bundle(data):
"""Whether the file names depth/confidence/original images, which are kept as JPEG.
Pixel Portrait bundles list Depth and Confidence in the container directory; Samsung captures use SEFT, whose
meaning is undocumented. Cutting either one down to a still would throw away images nothing else accounts for.
"""
text = xmp_text(data)
if re.search(r'Semantic\s*=\s*["\'](Depth|Confidence|Original)["\']', text):
return True
return b"SEFT" in data or b"SpecialType-PORTRAIT" in data
# === JPEG XL container boxes =======================================================================================
def parse_boxes(data):
"""[(type, raw box, payload)] for a JPEG XL container."""
if not data.startswith(JXL_SIGNATURE):
raise JxlError("not a JPEG XL container")
boxes = []
i = 0
while i + 8 <= len(data):
size = u32(data, i)
kind = data[i + 4:i + 8]
header = 8
if size == 1:
if i + 16 > len(data):
break
size = struct.unpack(">Q", data[i + 8:i + 16])[0]
header = 16
elif size == 0:
size = len(data) - i
if size < header or i + size > len(data):
raise JxlError(f"bad JXL box at byte {i}")
boxes.append((kind, data[i:i + size], data[i + header:i + size]))
i += size
if i != len(data):
raise JxlError("trailing bytes after the last JXL box")
return boxes
def make_box(kind, payload):
return struct.pack(">I", len(payload) + 8) + kind + payload
def box_payloads(container):
return {kind: payload for kind, _raw, payload in parse_boxes(container)}
def split_container(container):
"""(metadata boxes, bare codestream) from a JPEG XL container.
Encoding the gain map as its own JXL is only a way to get it compressed; what jhgm wants is the codestream, with
the reconstruction boxes that let djxl turn it back into a JPEG kept aside for jxgr.
"""
boxes = parse_boxes(container)
meta = [raw for kind, raw, _payload in boxes if kind not in (b"JXL ", b"jxlc", b"jxlp")]
parts = []
for kind, _raw, payload in boxes:
if kind == b"jxlc":
parts.append((0, payload))
elif kind == b"jxlp":
if len(payload) < 4:
raise JxlError("short jxlp box")
parts.append((u32(payload) & 0x7FFFFFFF, payload[4:]))
if not parts:
raise JxlError("no codestream in the JPEG XL container")
parts.sort(key=lambda item: item[0])
codestream = b"".join(payload for _index, payload in parts)
if not codestream.startswith(b"\xff\x0a"):
raise JxlError("codestream does not start with FF 0A")
return meta, codestream
def codestream_container(meta, codestream):
"""Wrap a bare codestream with its reconstruction boxes, so djxl rebuilds the gain-map JPEG from it."""
return JXL_SIGNATURE + b"".join(meta) + make_box(b"jxlc", codestream)
def insert_after_ftyp(container, new_boxes):
"""Insert boxes after the ftyp box, which is where jhgm belongs."""
position = 12 # past the signature box
for kind, raw, _payload in parse_boxes(container):
if kind == b"JXL ":
continue
position += len(raw)
if kind == b"ftyp":
break
return container[:position] + b"".join(new_boxes) + container[position:]
def jhgm_payload(metadata, codestream):
if len(metadata) > 0xFFFF:
raise JxlError("ISO metadata is too large for jhgm")
return (
bytes([JHGM_VERSION])
+ struct.pack(">H", len(metadata))
+ metadata
+ bytes([0]) # colour encoding, empty: the map uses the baseline image's
+ struct.pack(">I", 0) # ICC profile size
+ codestream
)
def parse_jhgm(payload):
if len(payload) < 8:
raise JxlError("short jhgm box")
size = u16(payload, 1)
pos = 3 + size
color_size = payload[pos]
pos += 1 + color_size
return payload[3:3 + size], payload[pos + 4 + u32(payload, pos):]
def sidecar_payload(offset, length, original_size, map_sha, meta):
"""jxgr: where the gain map sat, how big the file was, and the boxes needed to rebuild the map's JPEG."""
return (
bytes([SIDECAR_VERSION])
+ struct.pack(">QIQ", offset, length, original_size)
+ map_sha
+ struct.pack(">H", len(meta))
+ b"".join(meta)
)
def parse_sidecar(payload):
if len(payload) < 55 or payload[0] != SIDECAR_VERSION:
raise JxlError("unsupported jxgr box")
offset, length, original_size = struct.unpack(">QIQ", payload[1:21])
count = u16(payload, 53)
meta = []
pos = 55
for _ in range(count):
if pos + 8 > len(payload):
raise JxlError("short jxgr box")
size = u32(payload, pos)
if size < 8 or pos + size > len(payload):
raise JxlError("bad box in jxgr")
meta.append(payload[pos:pos + size])
pos += size
if pos != len(payload):
raise JxlError("trailing bytes in jxgr")
return offset, length, original_size, payload[21:53], meta
def tail_payload(tail):
"""jxtl: anything else after the primary image, deflated because it is usually an aecDebug blob."""
return bytes([2]) + struct.pack(">I", len(tail)) + zlib.compress(tail, 9)
def parse_tail(payload):
if not payload or payload[0] != 2 or len(payload) < 5:
raise JxlError("unsupported jxtl box")
expected = u32(payload, 1)
try:
tail = zlib.decompress(payload[5:])
except zlib.error as error:
raise JxlError(f"bad compressed jxtl data: {error}") from error
if len(tail) != expected:
raise JxlError(f"jxtl rebuilt {len(tail)} bytes, expected {expected}")
return tail
# === the conversion itself ==========================================================================================
def build_gain_map_jxl(data, effort):
"""Encode a JPEG that carries a gain map so the map goes to jhgm, and prove the result rebuilds the input.
The primary is encoded on its own, without the map or anything else after its end marker, so that djxl rebuilds
exactly those bytes. The map is encoded separately and only its codestream is kept for jhgm; its reconstruction
boxes go into jxgr, along with the offset and length the map had in the original file.
"""
primary_end = jpeg_end(data)
found = find_gain_map(data, primary_end)
if found is None:
raise JxlError("the file looks like it has a gain map, but none could be read")
offset, gain_map, metadata = found
base = data[:primary_end]
tail = data[primary_end:offset] + data[offset + len(gain_map):]
with tempfile.TemporaryDirectory() as scratch:
scratch = Path(scratch)
base_jxl = encode_jpeg(base, effort, scratch, "primary.jpg")
map_jxl = encode_jpeg(gain_map, effort, scratch, "gainmap.jpg")
meta, codestream = split_container(map_jxl)
if not any(kind == b"jbrd" for kind in box_payloads(map_jxl)):
raise JxlError("cjxl wrote no jbrd box for the gain map, so the restore would not be exact")
boxes = [make_box(b"jhgm", jhgm_payload(metadata, codestream))]
boxes.append(make_box(b"jxgr", sidecar_payload(offset, len(gain_map), len(data), digest(gain_map), meta)))
if tail:
boxes.append(make_box(b"jxtl", tail_payload(tail)))
container = insert_after_ftyp(base_jxl, boxes)
built = scratch / "built.jxl"
built.write_bytes(container)
if "Gain map (jhgm) box" not in run(["jxlinfo", "-v", str(built)]):
raise JxlError("jxlinfo does not see a jhgm box in the result")
if restore_still(container) != data:
raise JxlError("the new JXL does not restore the original JPEG")
return container
def restore_still(container):
"""The exact JPEG a container built here was made from."""
boxes = box_payloads(container)
if b"jhgm" not in boxes:
with tempfile.TemporaryDirectory() as scratch:
return decode_jpeg(container, Path(scratch), "rebuilt")
if b"jxgr" not in boxes:
raise JxlError("jhgm without jxgr: the original can no longer be rebuilt exactly")
_metadata, codestream = parse_jhgm(boxes[b"jhgm"])
offset, length, original_size, map_sha, meta = parse_sidecar(boxes[b"jxgr"])
with tempfile.TemporaryDirectory() as scratch:
scratch = Path(scratch)
base = decode_jpeg(container, scratch, "primary")
gain_map = decode_jpeg(codestream_container(meta, codestream), scratch, "gainmap")
if len(gain_map) != length or digest(gain_map) != map_sha:
raise JxlError("the rebuilt gain map does not match the original")
rebuilt = base + (parse_tail(boxes[b"jxtl"]) if b"jxtl" in boxes else b"")
if offset > len(rebuilt):
raise JxlError("the stored tail is shorter than the gain map offset")
rebuilt = rebuilt[:offset] + gain_map + rebuilt[offset:]
if len(rebuilt) != original_size:
raise JxlError(f"the restore rebuilt {len(rebuilt)} bytes, expected {original_size}")
return rebuilt
def encode_still(data, effort):
"""The container for one still, with its rebuild already checked (decode once, not twice)."""
if find_gain_map(data, jpeg_end(data)) is not None:
return build_gain_map_jxl(data, effort) # restores the original itself
with tempfile.TemporaryDirectory() as scratch:
scratch = Path(scratch)
container = encode_jpeg(data, effort, scratch, "still.jpg")
if decode_jpeg(container, scratch, "rebuilt") != data:
raise JxlError("the new JXL does not rebuild the JPEG")
return container
def write_part(path, data):
"""Write via a .part file, so an interrupted run never leaves a truncated output in place."""
partial = path.with_name(path.name + ".part")
partial.write_bytes(data)
return partial
def convert_photo(path, execute, effort):
"""Convert one JPEG; returns (status, bytes saved, detail)."""
data = path.read_bytes()
original_size = len(data)
output = path.with_suffix(".jxl")
if capture_bundle(data):
return "kept", 0, "depth/original bundle left as JPEG"
video_bytes = video_length(data)
if video_bytes:
offset = len(data) - video_bytes
still, clip = data[:offset], data[offset:]
video = path.with_suffix(".mp4")
if video.exists() and video.read_bytes() != clip:
raise JxlError(f"{video.name} exists and is not this video")
if output.exists():
if restore_still(output.read_bytes()) != still:
raise JxlError(f"{output.name} exists but does not rebuild this JPEG")
if execute:
if not video.exists():
os.replace(write_part(video, clip), video)
os.remove(path)
return "already", 0, "motion photo"
if not execute:
print(f" would split: {path.name} -> {output.name} + {video.name} ({size_label(video_bytes)} of MP4)")
return "split", 0, f"{size_label(video_bytes)} of MP4 -> {video.name}"
container = encode_still(still, effort)
partial = write_part(video, clip)
if shutil.which("ffprobe"):
probe = subprocess.run(
["ffprobe", "-v", "error", "-show_entries", "stream=codec_type", "-of", "csv=p=0", str(partial)],
capture_output=True, text=True,
)
if probe.returncode != 0 or "video" not in probe.stdout:
raise JxlError(f"ffprobe sees no video stream: {probe.stderr.strip() or 'no streams'}")
shutil.copystat(path, partial)
os.replace(partial, video)
detail = ", gain map in jhgm" if b"jhgm" in container else ""
saved = len(data) - len(container) - len(clip)
finish(path, output, container, saved, f" -> {output.name} + {video.name}{detail}")
return "split", saved, f"{size_label(video_bytes)} of MP4 -> {video.name}{detail}"
if not data.endswith(EOI):
return "kept", 0, "unknown trailing bytes left as JPEG"
layout, info = preview_layout(data)
if layout == "other" and find_gain_map(data, jpeg_end(data)) is None:
return "kept", 0, f"MPF layout left as JPEG ({info})"
if layout == "preview":
data = strip_preview(data, info)
detail = f", {size_label(info['size'])} preview stripped"
else:
detail = ""
if output.exists():
if restore_still(output.read_bytes()) != data:
raise JxlError(f"{output.name} exists but does not rebuild this file")
if execute:
os.remove(path)
return "already", 0, detail.lstrip(", ")
if not execute:
print(f" would convert: {path.name}{detail} -> {output.name}")
return "converted", 0, f"{path.name}{detail} -> {output.name}"
container = encode_still(data, effort)
if b"jhgm" in container:
detail += ", gain map in jhgm"
saved = original_size - len(container)
finish(path, output, container, saved, f" -> {output.name}{detail}")
return "converted", saved, detail.lstrip(", ")
def finish(path, output, container, saved, detail):
"""Write the .jxl, then delete the JPEG it was verified against."""
partial = write_part(output, container)
shutil.copystat(path, partial)
os.replace(partial, output)
print(f" converted: {path.name}{detail} ({size_label(saved)} saved)")
os.remove(path)
def convert_all(root, execute, effort):
files = sorted(path for path in Path(root).rglob("*")
if path.is_file() and path.suffix.lower() in JPEG_SUFFIXES)
print(f"CONVERTING {'(committing)' if execute else '(dry run, pass --execute to apply)'}: "
f"{len(files)} JPEGs under {root}")
counts = Counter()
saved = 0
for index, path in enumerate(files, 1):
try:
status, delta, _detail = convert_photo(path, execute, effort)
except (OSError, JxlError) as exc:
print(f" FAILED {path}: {exc}", file=sys.stderr)
counts["failed"] += 1
continue
counts[status] += 1
saved += delta
if index % 500 == 0:
print(f" {index}/{len(files)} processed", flush=True)
if not execute:
print(
f" {counts['converted']} stills would be converted, {counts['split']} motion photos would be split, "
f"{counts['already']} already converted, {counts['kept']} left as JPEG, {counts['failed']} failed"
)
return counts["failed"]
print(
f" {counts['converted']} stills converted, {counts['split']} motion photos split, "
f"{counts['already']} already converted, {counts['kept']} left as JPEG, "
f"{counts['failed']} failed, {size_label(saved)} saved"
)
return counts["failed"]
# === Immich linking =================================================================================================
class Immich:
"""The two calls linking needs: search the library, and patch a still's livePhotoVideoId."""
def __init__(self, url, api_key):
self.url = url.rstrip("/")
self.api_key = api_key
def call(self, method, path, body=None):
request = urllib.request.Request(
self.url + "/api" + path,
method=method,
data=None if body is None else json.dumps(body).encode(),
headers={"x-api-key": self.api_key, "Accept": "application/json", "Content-Type": "application/json"},
)
try:
with urllib.request.urlopen(request, timeout=60) as response:
raw = response.read()
except urllib.error.HTTPError as exc:
raise JxlError(f"{method} {path} failed: {exc.code} {exc.read().decode(errors='replace')[:200]}") from None
except OSError as exc:
raise JxlError(f"{method} {path} failed: {exc}") from None
return json.loads(raw) if raw else None
def link_pairs(root, url, api_key, execute):
"""Attach each still to the .mp4 beside it as a live photo video, so Immich shows one item rather than two.
The video is imported into encoded-video under a name of its own, so it is found by name and owner rather than by
path. A still that is not imported yet is reported and skipped; run --link again after the library scan.
"""
pairs = sorted(path for path in Path(root).rglob("*.jxl") if path.with_suffix(".mp4").exists())
print(f"LINKING {'(committing)' if execute else '(dry run)'}: {len(pairs)} stills with a video beside them")
api = Immich(url, api_key)
counts = Counter()
for still_path in pairs:
try:
suffix = "/" + still_path.relative_to(root).as_posix()
video_name = still_path.with_suffix(".mp4").name
items = api.call(
"POST", "/search/metadata",
{"filter": {"originalFileName": {"startsWith": still_path.stem + "."}}, "size": 100},
)["assets"]["items"]
still = next((asset for asset in items if asset["originalPath"].endswith(suffix)), None)
if still is None:
counts["waiting"] += 1
continue
if still.get("livePhotoVideoId"):
counts["already"] += 1
continue
video = next(
(asset for asset in items
if asset["type"] == "VIDEO" and asset["originalFileName"] == video_name
and asset["ownerId"] == still["ownerId"]),
None,
)
if video is None:
counts["waiting"] += 1
continue
if not execute:
counts["would"] += 1
continue
api.call("PATCH", f"/assets/{still['id']}", {"livePhotoVideoId": video["id"]})
counts["linked"] += 1
except (OSError, JxlError, KeyError) as exc:
print(f" FAILED {still_path}: {exc}", file=sys.stderr)
counts["failed"] += 1
print(
f" {counts['linked']} linked, {counts['already']} already linked, {counts['would']} would be linked, "
f"{counts['waiting']} waiting for an import, {counts['failed']} failed"
)
if counts["waiting"]:
print(" run a library scan, then --link again to attach the rest")
return counts["failed"]
# === entry point ====================================================================================================
def main():
parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
parser.add_argument("--target", default=".", help="directory to walk (default: the current one)")
parser.add_argument("--execute", action="store_true", help="convert, verify and delete the JPEGs (default: dry run)")
parser.add_argument("--effort", type=int, default=9, help="cjxl effort (default: 9)")
parser.add_argument("--link", action="store_true", help="after converting, attach each video to its still in Immich")
parser.add_argument("--api-key", default=os.environ.get("IMMICH_API_KEY"), help="Immich API key (default: $IMMICH_API_KEY)")
parser.add_argument("--url", default=os.environ.get("IMMICH_URL"), help="Immich base URL (default: $IMMICH_URL)")
args = parser.parse_args()
missing = [tool for tool in ("cjxl", "djxl", "jxlinfo") if not shutil.which(tool)]
if missing:
sys.exit(f"{', '.join(missing)} not installed or not on PATH")
if not 1 <= args.effort <= 10:
sys.exit("--effort must be between 1 and 10")
if args.link and not (args.api_key and args.url):
sys.exit("--link needs an API key and a URL (--api-key/--url, or $IMMICH_API_KEY/$IMMICH_URL)")
status = convert_all(args.target, args.execute, args.effort)
if args.link:
status += link_pairs(args.target, args.url, args.api_key, args.execute)
return 1 if status else 0
if __name__ == "__main__":
try:
sys.exit(main())
except JxlError as error:
print(f"error: {error}", file=sys.stderr)
sys.exit(1)