image-optimizer-webui 1.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,1378 @@
1
+ from __future__ import annotations
2
+
3
+ import asyncio
4
+ import os
5
+ import re
6
+ import shutil
7
+ import struct
8
+ import subprocess
9
+ import sys
10
+ import threading
11
+ import zlib
12
+ from pathlib import Path
13
+ from typing import Callable, Optional
14
+
15
+ from PIL import Image, ImageOps
16
+
17
+ from image_optimizer import binaries
18
+
19
+ PNG_MAGIC = b"\x89PNG\r\n\x1a\n"
20
+ HEX_COLOR_RE = re.compile(r"^#?[0-9A-Fa-f]{6}$")
21
+
22
+ # How long a single pngquant/oxipng/cjpeg/avifenc invocation is allowed to
23
+ # run before it's treated as hung rather than legitimately slow. Generous
24
+ # enough for a large image on slow storage; a compression call for one
25
+ # file still running past this is far more likely stuck (malformed input,
26
+ # a bug in the binary, a stalled network drive) than working. Mirrors the
27
+ # timeout already used for the much cheaper `where`/`which` binary lookup
28
+ # in _find_binary.
29
+ SUBPROCESS_TIMEOUT = 120
30
+
31
+ # After a timed-out encoder is killed, how long to wait for it to be reaped
32
+ # before giving up on it (see Optimizer._kill_and_reap).
33
+ REAP_TIMEOUT = 2.0
34
+
35
+ # EXIF tag ids used by the retention logic below. Orientation is stripped
36
+ # because `exif_transpose` already bakes it into the pixel grid — re-writing
37
+ # it would double-rotate in any reader that
38
+ # honors EXIF orientation. GPSInfo is dropped for privacy (images may be
39
+ # publicly shared). MakerNote is vendor-specific bulk with no display value.
40
+ EXIF_TAG_ORIENTATION = 0x0112
41
+ EXIF_TAG_GPS_INFO = 0x8825
42
+ EXIF_TAG_EXIF_IFD = 0x8769
43
+ EXIF_TAG_MAKER_NOTE = 0x927C
44
+
45
+
46
+ class Optimizer:
47
+ def __init__(self, bin_dir: Optional[Path] = None, max_concurrency: int = 4):
48
+ # Searched in order, after PATH. The per-user data directory is where
49
+ # binaries fetched on first run land (see binaries.py); the repo's own
50
+ # bin/ stays last so an existing source checkout / dev workflow that
51
+ # drops the .exe next to the code keeps working unchanged.
52
+ if bin_dir:
53
+ self._bin_dirs = [Path(bin_dir)]
54
+ elif getattr(sys, "frozen", False):
55
+ self._bin_dirs = [Path(sys._MEIPASS) / "bin"]
56
+ else:
57
+ self._bin_dirs = [
58
+ binaries.binary_dir(),
59
+ Path(__file__).resolve().parent.parent / "bin",
60
+ ]
61
+ # Kept as the headline location for logging; _bin_dirs is authoritative.
62
+ self.bin_dir = self._bin_dirs[0]
63
+ self.pngquant_path: Optional[Path] = None
64
+ self.oxipng_path: Optional[Path] = None
65
+ self.cjpeg_path: Optional[Path] = None
66
+ self.avifenc_path: Optional[Path] = None
67
+ # Guards _detect_binaries: it's called once here (main thread) and
68
+ # again on every /api/health request via asyncio.to_thread (see
69
+ # image_optimizer/main.py), each on its own thread-pool thread. A real
70
+ # threading.Lock (not asyncio.Lock, which doesn't coordinate across
71
+ # OS threads) keeps two overlapping detections from interleaving
72
+ # their writes to the four *_path attributes below, which a reader
73
+ # building a /api/health response from those same attributes could
74
+ # otherwise observe half-updated.
75
+ self._detect_lock = threading.Lock()
76
+ self._detect_binaries()
77
+ self._semaphore = asyncio.Semaphore(max(1, max_concurrency))
78
+
79
+ @property
80
+ def ready(self) -> bool:
81
+ """True iff the lossy PNG path (Standard compression mode) is usable,
82
+ i.e. pngquant is available. Kept for backwards compatibility — it
83
+ only answers "can this build do the most aggressive Standard-mode
84
+ PNG pipeline?", nothing else. Callers wanting the modern answer
85
+ ("which format×mode combinations actually work right now?") should
86
+ use `available_modes()` instead.
87
+
88
+ Note in particular: `ready` says nothing about lossless / resize_only
89
+ PNG compression (those only need oxipng or even just Pillow), nor
90
+ about WebP (which needs no external binary at all — Pillow's built-in
91
+ encoder is always available). A build with neither pngquant nor
92
+ oxipng installed can still optimize WebP files successfully while
93
+ reporting `ready == False`.
94
+ """
95
+ return self.pngquant_path is not None
96
+
97
+ def available_modes(self) -> set[tuple[str, str]]:
98
+ """Returns the set of (output_format, compression_mode) tuples this
99
+ Optimizer instance can actually produce output for right now, given
100
+ which external binaries were auto-detected.
101
+
102
+ - WebP (any compression_mode) always works — Pillow's built-in
103
+ WebP encoder is the only thing needed.
104
+ - PNG lossless / resize_only need oxipng OR Pillow's PNG encoder
105
+ (oxipng just shrinks further; both modes still produce a valid
106
+ PNG without it, only bigger), so they're always available too.
107
+ - PNG standard needs pngquant specifically — oxipng only optimizes,
108
+ it doesn't do the lossy color quantization that's the whole
109
+ point of Standard mode.
110
+ - PNG screenshot needs pngquant too — it's a much tighter-quality
111
+ pngquant pass, not a different tool (see _optimize_png's
112
+ screenshot branch for the quality floor and why dithering is
113
+ forced off there).
114
+
115
+ This is the API new code should call instead of `ready` when deciding
116
+ whether to enable a particular (format, mode) option in the UI or
117
+ accept it on the server side.
118
+ """
119
+ modes = {("webp", "standard"), ("webp", "lossless"), ("webp", "resize_only")}
120
+ modes |= {("png", "lossless"), ("png", "resize_only")}
121
+ if self.pngquant_path is not None:
122
+ modes |= {("png", "standard"), ("png", "screenshot")}
123
+ # JPEG output needs mozjpeg's cjpeg — every JPEG mode is a lossy
124
+ # re-encode (JPEG is an inherently lossy codec; "lossless" maps to
125
+ # the highest quality pass, see _optimize_jpeg). No cjpeg → no JPG.
126
+ if self.cjpeg_path is not None:
127
+ modes |= {("jpg", "standard"), ("jpg", "lossless"), ("jpg", "resize_only")}
128
+ # AVIF output needs avifenc — all three modes are available when
129
+ # the binary is found. AVIF is a modern, efficient codec that
130
+ # typically produces smaller files than PNG or WebP at equivalent
131
+ # quality, but encoding is slower. Unlike JPEG (no true lossless
132
+ # codec exists, so its "lossless"/"resize_only" fall back to a
133
+ # very-high-quality pass), AVIF has a real --lossless mode, and
134
+ # both "lossless" and "resize_only" use it — same guarantee as
135
+ # PNG/WebP: no quality cost beyond whatever resizing was asked for.
136
+ if self.avifenc_path is not None:
137
+ modes |= {("avif", "standard"), ("avif", "lossless"), ("avif", "resize_only")}
138
+ return modes
139
+
140
+ def _find_binary(self, name: str) -> Optional[Path]:
141
+ try:
142
+ cmd = "where" if sys.platform == "win32" else "which"
143
+ # timeout: a hung `where`/`which` (e.g. a dead network drive on
144
+ # PATH) must not wedge detection — and with it /api/health —
145
+ # forever.
146
+ result = subprocess.run([cmd, name], capture_output=True, text=True, timeout=5)
147
+ if result.returncode == 0 and result.stdout.strip():
148
+ return Path(result.stdout.strip().splitlines()[0])
149
+ except Exception:
150
+ pass
151
+ exe_name = f"{name}.exe" if sys.platform == "win32" else name
152
+ for directory in self._bin_dirs:
153
+ local = directory / exe_name
154
+ if local.exists():
155
+ return local.resolve()
156
+ return None
157
+
158
+ @staticmethod
159
+ async def _communicate_with_timeout(
160
+ proc: "asyncio.subprocess.Process", timeout: Optional[float] = None
161
+ ) -> tuple[bytes, bytes, bool]:
162
+ """await proc.communicate() with a timeout, so a hung external
163
+ binary (malformed input, a bug in the tool itself, a stalled
164
+ network drive) fails just the one file being processed instead of
165
+ blocking its worker -- and the concurrency-limiting semaphore slot
166
+ it holds -- forever. On timeout the process is killed and reaped
167
+ (so it doesn't linger as a zombie), and a synthetic stderr message
168
+ is returned so every call site's existing
169
+ `if <output missing/returncode != 0>: msg = stderr.decode()` error
170
+ path picks this up exactly like any other subprocess failure, with
171
+ no extra branching needed at each of the four call sites.
172
+
173
+ On cancellation (e.g. the user hits Cancel): wait_for propagates
174
+ CancelledError the same as a bare communicate() would, so existing
175
+ cancel handling is unaffected -- but the child is now also killed
176
+ on the way out. Without this, cancelling unblocks the *worker*
177
+ (the await raises) but never signals the child process itself,
178
+ which would otherwise keep running as an orphan in the background.
179
+
180
+ The third element of the return value, `timed_out`, lets callers
181
+ remove any partial file the binary may have left at its own
182
+ output path before checking whether that path exists -- a killed
183
+ process can leave a non-empty but truncated/corrupt file there,
184
+ which an exists()-only (or exists()-and-size>0) check can't tell
185
+ apart from a completed one.
186
+
187
+ `timeout=None` reads the module global SUBPROCESS_TIMEOUT lazily at
188
+ call time rather than as a Python default argument value (which
189
+ would freeze whatever it was at class-definition time) -- same
190
+ reasoning as CONCURRENT_WORKERS in main.py's _run_worker_pool, and
191
+ what lets tests shrink this to something fast without threading an
192
+ explicit timeout through optimize_png/optimize_jpeg/optimize_webp/
193
+ optimize_avif.
194
+
195
+ Returns (stdout, stderr, timed_out)."""
196
+ if timeout is None:
197
+ timeout = SUBPROCESS_TIMEOUT
198
+ try:
199
+ stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=timeout)
200
+ return stdout, stderr, False
201
+ except asyncio.TimeoutError:
202
+ await Optimizer._kill_and_reap(proc)
203
+ return b"", f"timed out after {timeout:g}s (process killed)".encode(), True
204
+ except asyncio.CancelledError:
205
+ await Optimizer._kill_and_reap(proc)
206
+ raise
207
+
208
+ @staticmethod
209
+ async def _kill_and_reap(proc: "asyncio.subprocess.Process") -> None:
210
+ """Force-terminate a subprocess and wait (briefly) for it to exit,
211
+ so it's neither left running as an orphan nor left as a zombie.
212
+ The wait is bounded by REAP_TIMEOUT: this is best effort, not a
213
+ guarantee, and it says so on stderr when it gives up.
214
+
215
+ kill() reaches only the process we started. If that process had
216
+ spawned a descendant (a .bat/.cmd or shim wrapper on Windows, a
217
+ shell wrapper without `exec`), the descendant survives and keeps
218
+ the stdout/stderr pipes open. On Python releases without the
219
+ gh-119710 fix proc.wait() does not resolve until those pipes close
220
+ -- asyncio wakes the waiters from _call_connection_lost, which needs
221
+ every pipe disconnected; gh-119710 also wakes them from
222
+ _process_exited -- so an unbounded wait here blocked the worker (and
223
+ its semaphore slot) for as long as the descendant lived, which
224
+ defeated the point of the timeout. Measured: 3.11.18 and 3.12.3
225
+ block, 3.13.18 does not (patch-release dependent).
226
+
227
+ Giving up on the wait is safe: asyncio records the exit status
228
+ (and reaps the child) before the pipes can block wait(), so what
229
+ survives the timeout is a bookkeeping orphan, not a running
230
+ process.
231
+
232
+ The pipes are closed on every path, not just the one that gave up.
233
+ A survivor keeps them open either way: when wait() resolves without
234
+ the pipes closing (gh-119710 wakes it from _process_exited) the
235
+ abandoned transport is still finalized after the event loop is
236
+ closed and logs "Event loop is closed" / "I/O operation on closed
237
+ pipe". Closing goes through the transport's private handle, best
238
+ effort, because asyncio has no public way to do it."""
239
+ try:
240
+ proc.kill()
241
+ except OSError:
242
+ # ProcessLookupError (already gone) is the common case, but
243
+ # Windows can also refuse with PermissionError, and letting
244
+ # that escape would replace the caller's "timed out" result
245
+ # with an exception, skipping the encoder fallback path.
246
+ pass
247
+ try:
248
+ await asyncio.wait_for(proc.wait(), timeout=REAP_TIMEOUT)
249
+ except asyncio.TimeoutError:
250
+ status = getattr(proc, "returncode", None)
251
+ print(
252
+ f"[Warning] killed encoder pid {getattr(proc, 'pid', '?')} was not "
253
+ f"reaped within {REAP_TIMEOUT:g}s "
254
+ f"(exit status {'unknown' if status is None else status}); "
255
+ f"abandoning the wait",
256
+ file=sys.stderr,
257
+ )
258
+ except Exception:
259
+ pass
260
+ transport = getattr(proc, "_transport", None)
261
+ if transport is not None:
262
+ try:
263
+ transport.close()
264
+ except Exception:
265
+ pass
266
+
267
+ def _detect_binaries(self):
268
+ # See the comment on self._detect_lock in __init__: two concurrent
269
+ # /api/health requests must not run this body at the same time.
270
+ with self._detect_lock:
271
+ self.pngquant_path = self._find_binary("pngquant")
272
+ self.oxipng_path = self._find_binary("oxipng")
273
+ # mozjpeg releases/prebuilt zip files name the encoder either
274
+ # `cjpeg` or `cjpeg-static` (the static variant shipped by
275
+ # several Windows/AiZ builds) — try both spellings so either is
276
+ # picked up.
277
+ self.cjpeg_path = self._find_binary_any(["cjpeg", "cjpeg-static"])
278
+ self.avifenc_path = self._find_binary("avifenc")
279
+
280
+ def _find_binary_any(self, names: list[str]) -> Optional[Path]:
281
+ for name in names:
282
+ path = self._find_binary(name)
283
+ if path is not None:
284
+ return path
285
+ return None
286
+
287
+ @staticmethod
288
+ def _is_png(path: Path) -> bool:
289
+ try:
290
+ with open(path, "rb") as f:
291
+ return f.read(8) == PNG_MAGIC
292
+ except Exception:
293
+ return False
294
+
295
+ # (format -> extensions) used by _apply_growth_guard to tell whether a
296
+ # result is a genuine format conversion (nothing safe to fall back to)
297
+ # or a same-format optimize (safe to fall back to a stripped copy of
298
+ # the original).
299
+ _SAME_FORMAT_EXTS = {
300
+ "png": {".png"},
301
+ "jpg": {".jpg", ".jpeg"},
302
+ "webp": {".webp"},
303
+ }
304
+
305
+ _PNG_METADATA_CHUNKS = (b"eXIf", b"tEXt", b"zTXt", b"iTXt", b"tIME")
306
+
307
+ @staticmethod
308
+ def _strip_png_metadata(data: bytes) -> bytes:
309
+ """Remove EXIF/text/timestamp chunks from a PNG's bytes, same set
310
+ pngquant --strip / oxipng --strip safe remove. Color-management
311
+ chunks (iCCP, gAMA, cHRM, sRGB) are left alone — they're not
312
+ privacy-sensitive and removing them isn't what --strip is for."""
313
+ for chunk_type in Optimizer._PNG_METADATA_CHUNKS:
314
+ data = Optimizer._strip_png_chunks(data, chunk_type)
315
+ return data
316
+
317
+ @staticmethod
318
+ def _strip_jpeg_metadata(data: bytes) -> bytes:
319
+ """Remove all APPn metadata segments (Exif, XMP, ICC profile,
320
+ Photoshop/IPTC, ...) and COM comments from a JPEG's bytes, keeping
321
+ APP0/JFIF and everything from SOS onward untouched. Matches what
322
+ the normal cjpeg-from-PPM pipeline already produces (it starts
323
+ from raw pixels with zero metadata) — this gets the same result
324
+ on a copy of the original bytes instead of a full re-encode.
325
+ Malformed input is returned unchanged rather than raising."""
326
+ if len(data) < 4 or data[0:2] != b"\xff\xd8":
327
+ return data
328
+ out = bytearray(data[0:2])
329
+ pos = 2
330
+ n = len(data)
331
+ strip_markers = set(range(0xE1, 0xF0)) | {0xFE} # APP1-APP15, COM
332
+ while pos + 2 <= n:
333
+ if data[pos] != 0xFF:
334
+ out += data[pos:]
335
+ return bytes(out)
336
+ marker = data[pos + 1]
337
+ if marker == 0xFF: # fill byte between markers
338
+ out.append(0xFF)
339
+ pos += 1
340
+ continue
341
+ if marker == 0xD8: # stray SOI
342
+ out += data[pos:pos + 2]
343
+ pos += 2
344
+ continue
345
+ if marker == 0xDA: # SOS — metadata segments are done, entropy
346
+ # data (with any RST markers) plus EOI follow verbatim.
347
+ out += data[pos:]
348
+ return bytes(out)
349
+ if marker == 0x01 or 0xD0 <= marker <= 0xD7:
350
+ # standalone markers with no length field (shouldn't
351
+ # appear before SOS, but handled just in case)
352
+ out += data[pos:pos + 2]
353
+ pos += 2
354
+ continue
355
+ if pos + 4 > n:
356
+ break
357
+ seg_len = int.from_bytes(data[pos + 2:pos + 4], "big")
358
+ total = 2 + seg_len
359
+ if pos + total > n:
360
+ break # malformed/truncated — bail, append the raw remainder below
361
+ if marker not in strip_markers:
362
+ out += data[pos:pos + total]
363
+ pos += total
364
+ out += data[pos:]
365
+ return bytes(out)
366
+
367
+ @staticmethod
368
+ def _strip_webp_metadata(data: bytes) -> bytes:
369
+ """Remove EXIF/XMP RIFF chunks from a WebP's bytes. VP8/VP8L/VP8X/
370
+ ALPH/ANIM/ANMF/ICCP chunks are left alone. Malformed input, or
371
+ input with nothing to strip, is returned unchanged."""
372
+ if len(data) < 12 or data[0:4] != b"RIFF" or data[8:12] != b"WEBP":
373
+ return data
374
+ body = bytearray()
375
+ pos = 12
376
+ n = len(data)
377
+ removed_any = False
378
+ while pos + 8 <= n:
379
+ fourcc = data[pos:pos + 4]
380
+ size = int.from_bytes(data[pos + 4:pos + 8], "little")
381
+ total = 8 + size + (size & 1) # chunks are padded to an even length
382
+ if pos + total > n:
383
+ body += data[pos:]
384
+ pos = n
385
+ break
386
+ if fourcc in (b"EXIF", b"XMP "):
387
+ removed_any = True
388
+ else:
389
+ body += data[pos:pos + total]
390
+ pos += total
391
+ if pos < n:
392
+ body += data[pos:]
393
+ if not removed_any:
394
+ return data
395
+ riff_size = 4 + len(body) # "WEBP" + chunks, excluding the 8-byte RIFF header itself
396
+ return b"RIFF" + riff_size.to_bytes(4, "little") + b"WEBP" + bytes(body)
397
+
398
+ def _apply_growth_guard(
399
+ self,
400
+ input_path: Path,
401
+ output_path: Path,
402
+ output_format: str,
403
+ result: dict,
404
+ keep_exif: bool,
405
+ cleaned_exif: bytes,
406
+ ) -> None:
407
+ """If the just-produced output isn't actually smaller than the
408
+ original, and no format conversion was requested (the source is
409
+ already `output_format`), replace it with the original's pixel
410
+ data unchanged but with privacy-relevant metadata (EXIF/GPS, XMP,
411
+ text comments) stripped the same way the normal pipeline
412
+ promises — never re-encoded, so the result can only ever be the
413
+ same size as or smaller than the raw original.
414
+
415
+ Skipped for a genuine format conversion (e.g. Screenshot mode
416
+ forcing jpg -> png): the original bytes wouldn't be a valid file
417
+ at output_path's extension, so there's nothing safe to fall back
418
+ to there — that case is handled by each pipeline's own logic
419
+ instead (see optimize_png's pngquant-failure branch).
420
+
421
+ AVIF isn't handled here — its ISOBMFF box structure needs a real
422
+ box parser to strip safely, which is more machinery than this
423
+ narrow a case (avifenc rarely loses to an already-AVIF source)
424
+ justifies right now.
425
+
426
+ Best-effort: any failure here is swallowed and the original
427
+ (larger) result stands rather than turning a successful
428
+ compression into a failure."""
429
+ if not result.get("success") or output_format not in ("png", "jpg", "webp"):
430
+ return
431
+ if result["compressed_size"] < result["original_size"]:
432
+ return
433
+ exts = self._SAME_FORMAT_EXTS.get(output_format, set())
434
+ if input_path.suffix.lower() not in exts:
435
+ return
436
+ try:
437
+ original_bytes = input_path.read_bytes()
438
+ if output_format == "png":
439
+ if original_bytes[:8] != PNG_MAGIC:
440
+ return
441
+ stripped = self._strip_png_metadata(original_bytes)
442
+ elif output_format == "jpg":
443
+ stripped = self._strip_jpeg_metadata(original_bytes)
444
+ else:
445
+ stripped = self._strip_webp_metadata(original_bytes)
446
+ output_path.write_bytes(stripped)
447
+ if keep_exif and cleaned_exif:
448
+ if output_format == "png":
449
+ self._finalize_png_exif(output_path, cleaned_exif)
450
+ elif output_format == "jpg":
451
+ self._finalize_jpeg_exif(output_path, cleaned_exif)
452
+ # WebP has no standalone EXIF-chunk injector (the normal
453
+ # pipeline attaches it via Pillow's save(exif=...) during
454
+ # encode) — this narrow fallback leaves WebP metadata-free
455
+ # rather than risk a malformed RIFF/VP8X rewrite.
456
+ result["compressed_size"] = os.path.getsize(output_path)
457
+ result["kept_original"] = True
458
+ except Exception:
459
+ pass
460
+
461
+ @staticmethod
462
+ def _ensure_png(src: Path, dst: Path):
463
+ """Re-encode any Pillow-readable image (jpg/bmp/tiff/...) into a real PNG.
464
+
465
+ This is required because pngquant/oxipng only understand PNG input; without
466
+ this step, non-PNG sources that skip the resize path get silently copied
467
+ through unchanged but renamed to .png (invalid/mislabeled output).
468
+ """
469
+ with Image.open(src) as img:
470
+ # Bake in the EXIF orientation (phone JPEGs) — PNG has no
471
+ # orientation tag, so without this a portrait photo comes out
472
+ # sideways in the optimized output.
473
+ img = ImageOps.exif_transpose(img)
474
+ if img.mode == "CMYK":
475
+ img = img.convert("RGB")
476
+ # Drop EXIF at normalization. The compress pipeline
477
+ # (pngquant --strip / oxipng --strip safe) strips it anyway in
478
+ # production, but the test stand-in binaries only copy bytes
479
+ # through — removing it here keeps default (keep_exif=False)
480
+ # behavior deterministic across both. A cleaned copy is
481
+ # re-attached at the very end of the pipeline only when
482
+ # keep_exif=True (see _finalize_png_exif / _optimize_webp).
483
+ img.info.pop("exif", None)
484
+ img.save(dst, format="PNG")
485
+
486
+ @staticmethod
487
+ def _resize_image(src: Path, dst: Path, max_width: int):
488
+ with Image.open(src) as img:
489
+ w, h = img.size
490
+ if w <= max_width:
491
+ return
492
+ ratio = max_width / w
493
+ new_size = (max_width, int(h * ratio))
494
+ img = img.resize(new_size, Image.Resampling.LANCZOS)
495
+ img.info.pop("exif", None)
496
+ img.save(dst, format="PNG")
497
+
498
+ @staticmethod
499
+ def _make_color_map(colors: list[str], dst: Path) -> bool:
500
+ """Build a tiny reference PNG containing the given hex colors, one pixel each.
501
+
502
+ Passed to pngquant via --map so it treats these colors as important and
503
+ prioritizes keeping them in the generated palette (not a hard guarantee).
504
+ """
505
+ rgbs = []
506
+ for c in colors:
507
+ c = c.strip()
508
+ if not HEX_COLOR_RE.match(c):
509
+ continue
510
+ c = c.lstrip("#")
511
+ rgbs.append(tuple(int(c[i:i + 2], 16) for i in (0, 2, 4)))
512
+ if not rgbs:
513
+ return False
514
+ img = Image.new("RGB", (len(rgbs), 1))
515
+ img.putdata(rgbs)
516
+ img.save(dst, format="PNG")
517
+ return True
518
+
519
+ # --- EXIF retention helpers ---
520
+ @staticmethod
521
+ def _clean_exif(exif) -> None:
522
+ """Strip EXIF fields that must NOT survive into optimized output.
523
+ Mutates the PIL Exif object in place.
524
+
525
+ - Orientation: `exif_transpose` already baked it into the pixels;
526
+ re-writing it would double-rotate in any reader honoring EXIF.
527
+ - GPSInfo: privacy — full GPS retention isn't wanted by default
528
+ for images that may be publicly shared.
529
+ - MakerNote: vendor-specific bulk, no display value.
530
+ """
531
+ exif.pop(EXIF_TAG_ORIENTATION, None)
532
+ # get_ifd() caches the GPS sub-IFD on the Exif object. On Pillow 11.x,
533
+ # popping the GPSInfo pointer alone leaves that cached IFD behind, and
534
+ # tobytes() writes it back out if anything read it first. Empty it
535
+ # before dropping the pointer so this holds whatever touched the
536
+ # object earlier. Only when the tag is present: asking for a missing
537
+ # IFD would create an empty one that Pillow could serialize.
538
+ if EXIF_TAG_GPS_INFO in exif:
539
+ try:
540
+ exif.get_ifd(EXIF_TAG_GPS_INFO).clear()
541
+ except Exception:
542
+ pass
543
+ exif.pop(EXIF_TAG_GPS_INFO, None)
544
+ try:
545
+ exif.get_ifd(EXIF_TAG_EXIF_IFD).pop(EXIF_TAG_MAKER_NOTE, None)
546
+ except Exception:
547
+ # ExifIFD may be absent; nothing to clean there.
548
+ pass
549
+
550
+ @staticmethod
551
+ def _capture_cleaned_exif(src: Path) -> bytes:
552
+ """Read the source's EXIF, drop the sensitive/redundant tags, and
553
+ return the cleaned bytes (raw TIFF, starting with the II/MM byte
554
+ order mark — ready for a PNG eXIf chunk or a WebP exif= save arg).
555
+ Returns b"" if the source has no EXIF or can't be read — callers
556
+ treat that as 'no EXIF to attach' and skip the finalize step.
557
+
558
+ PIL's `Exif.tobytes()` prepends the JPEG APP1 `Exif\\x00\\x00`
559
+ marker; that prefix is wrong for both the PNG eXIf chunk and
560
+ WebP's exif= arg (both want raw TIFF), so it's stripped here."""
561
+ try:
562
+ with Image.open(src) as img:
563
+ exif = img.getexif()
564
+ if not exif:
565
+ return b""
566
+ Optimizer._clean_exif(exif)
567
+ raw = exif.tobytes() if exif else b""
568
+ if raw.startswith(b"Exif\x00\x00"):
569
+ raw = raw[6:]
570
+ return raw
571
+ except Exception:
572
+ return b""
573
+
574
+ @staticmethod
575
+ def _strip_png_chunks(data: bytes, chunk_type: bytes) -> bytes:
576
+ """Return `data` (a PNG file's bytes) with every chunk of
577
+ `chunk_type` removed. Walks the chunk stream once, stops at IEND.
578
+ Malformed input is returned with whatever was reconstructed up to
579
+ the break — never raises."""
580
+ out = bytearray(data[:8]) # PNG signature
581
+ pos = 8
582
+ n = len(data)
583
+ while pos + 8 <= n:
584
+ length = int.from_bytes(data[pos:pos + 4], "big")
585
+ ctype = data[pos + 4:pos + 8]
586
+ total = 8 + length + 4 # length field + type + data + crc
587
+ if pos + total > n:
588
+ break # malformed/truncated — bail
589
+ if ctype != chunk_type:
590
+ out += data[pos:pos + total]
591
+ if ctype == b"IEND":
592
+ break
593
+ pos += total
594
+ return bytes(out)
595
+
596
+ @staticmethod
597
+ def _find_png_chunk_offset(data: bytes, chunk_type: bytes) -> Optional[int]:
598
+ """Walk the PNG chunk stream (the same structural walk
599
+ `_strip_png_chunks` does) and return the byte offset of the first
600
+ chunk of `chunk_type` — pointing at its 4-byte length field — or
601
+ None if it isn't found or the stream is malformed/truncated.
602
+
603
+ Unlike a raw `bytes.find(b"IEND")`, this can't be fooled by those
604
+ four bytes appearing inside another chunk's *data* (e.g. a stray
605
+ tEXt/iTXt comment that happens to contain the literal text
606
+ "IEND") — it only matches an actual chunk header."""
607
+ pos = 8
608
+ n = len(data)
609
+ while pos + 8 <= n:
610
+ length = int.from_bytes(data[pos:pos + 4], "big")
611
+ ctype = data[pos + 4:pos + 8]
612
+ total = 8 + length + 4
613
+ if pos + total > n:
614
+ return None # malformed/truncated
615
+ if ctype == chunk_type:
616
+ return pos
617
+ pos += total
618
+ return None
619
+
620
+ @staticmethod
621
+ def _finalize_png_exif(png_path: Path, exif_bytes: bytes) -> None:
622
+ """Attach cleaned EXIF to a finished PNG by inserting a single
623
+ eXIf chunk before IEND. Any pre-existing eXIf chunks are removed
624
+ first, so the result is deterministic regardless of what the
625
+ compress pipeline left behind (real pngquant/oxipng strip
626
+ metadata; the test stand-in binaries copy it through). Best-effort:
627
+ never raises into the caller — a failure to attach EXIF must not
628
+ turn a successful compression into a failure."""
629
+ if not exif_bytes or exif_bytes[:2] not in (b"II", b"MM"):
630
+ return
631
+ try:
632
+ data = png_path.read_bytes()
633
+ if data[:8] != PNG_MAGIC:
634
+ return
635
+ data = Optimizer._strip_png_chunks(data, b"eXIf")
636
+ chunk_body = exif_bytes
637
+ chunk = struct.pack(">I", len(chunk_body)) + b"eXIf" + chunk_body
638
+ chunk += struct.pack(">I", zlib.crc32(b"eXIf" + chunk_body) & 0xFFFFFFFF)
639
+ iend_start = Optimizer._find_png_chunk_offset(data, b"IEND")
640
+ if iend_start is None:
641
+ return
642
+ png_path.write_bytes(data[:iend_start] + chunk + data[iend_start:])
643
+ except Exception:
644
+ pass
645
+
646
+ async def optimize_png(
647
+ self,
648
+ input_path: Path,
649
+ output_path: Path,
650
+ quality: str = "medium",
651
+ max_width: int = 0,
652
+ compression_mode: str = "standard",
653
+ protected_colors: Optional[list[str]] = None,
654
+ dithering: bool = True,
655
+ output_format: str = "png",
656
+ progress_callback: Optional[Callable] = None,
657
+ keep_exif: bool = False,
658
+ ) -> dict:
659
+ if compression_mode not in ("standard", "lossless", "resize_only", "screenshot"):
660
+ compression_mode = "standard"
661
+
662
+ # Capture a cleaned EXIF copy from the source up front (before any
663
+ # pipeline step that strips/transposes it). Attached to the output
664
+ # at the very end — Orientation is already baked into pixels by
665
+ # exif_transpose, so the retained EXIF never carries Orientation
666
+ # (double-rotation guard).
667
+ cleaned_exif = b""
668
+ if keep_exif:
669
+ cleaned_exif = self._capture_cleaned_exif(input_path)
670
+
671
+ if output_format == "webp":
672
+ return await self._optimize_webp(
673
+ input_path, output_path, quality, max_width, compression_mode,
674
+ progress_callback, keep_exif=keep_exif, cleaned_exif=cleaned_exif,
675
+ )
676
+
677
+ if output_format in ("jpg", "jpeg"):
678
+ return await self._optimize_jpeg(
679
+ input_path, output_path, quality, max_width, compression_mode,
680
+ progress_callback, keep_exif=keep_exif, cleaned_exif=cleaned_exif,
681
+ )
682
+
683
+ if output_format == "avif":
684
+ return await self._optimize_avif(
685
+ input_path, output_path, quality, max_width, compression_mode,
686
+ progress_callback, keep_exif=keep_exif, cleaned_exif=cleaned_exif,
687
+ )
688
+
689
+ original_size = os.path.getsize(input_path)
690
+ result = {
691
+ "success": False,
692
+ "original_size": original_size,
693
+ "compressed_size": original_size,
694
+ "error": None,
695
+ "warning": None,
696
+ }
697
+ temp_files: list = []
698
+
699
+ try:
700
+ working_path = input_path
701
+ loop = asyncio.get_running_loop()
702
+
703
+ # Step 0: guarantee we're working with a real PNG from here on, regardless
704
+ # of the source format and regardless of whether a resize happens next.
705
+ if not self._is_png(working_path):
706
+ normalized = output_path.with_suffix(".src.png")
707
+ await loop.run_in_executor(None, self._ensure_png, working_path, normalized)
708
+ if normalized.exists():
709
+ if progress_callback:
710
+ await progress_callback("converted to PNG")
711
+ working_path = normalized
712
+ temp_files.append(normalized)
713
+
714
+ # Screenshot mode never resizes — the whole point is preserving
715
+ # every pixel of UI text at full resolution (see the quantization
716
+ # step below for where the size reduction actually comes from).
717
+ # max_width is ignored entirely for this mode, matching the
718
+ # "one click, no manual tuning" design (see PNG8-conversion
719
+ # comment below for the empirical numbers behind this).
720
+ if max_width > 0 and compression_mode != "screenshot":
721
+ resized = output_path.with_suffix(".resized.png")
722
+ await loop.run_in_executor(None, self._resize_image, working_path, resized, max_width)
723
+ if resized.exists():
724
+ if progress_callback:
725
+ await progress_callback(f"resized to <= {max_width}px")
726
+ working_path = resized
727
+ temp_files.append(resized)
728
+
729
+ if compression_mode in ("standard", "screenshot") and self.pngquant_path:
730
+ pngquant_tmp = output_path.with_suffix(".pngquant.png")
731
+ if compression_mode == "screenshot":
732
+ # Near-lossless floor for typical UI screenshots (flat
733
+ # chrome + anti-aliased text). Was 95-100 originally;
734
+ # lowered to 75-100 after measuring pngquant's actual
735
+ # behavior on real screenshot content:
736
+ #
737
+ # For images that already clear a tight floor (flat
738
+ # UI, icons, even moderate soft-shadow/gradient cards),
739
+ # pngquant's min-max range only acts as a pass/fail
740
+ # gate, not a target it optimizes down toward — it
741
+ # already searches for the best palette it can find
742
+ # regardless of how loose `min` is. Measured
743
+ # byte-for-byte identical output across a 60-100 to
744
+ # 95-100 sweep on several synthetic screenshots, so
745
+ # this floor change costs those images nothing.
746
+ #
747
+ # What actually changes is the harder subset: images
748
+ # whose true color complexity (embedded photo/video
749
+ # thumbnails, richer gradients) couldn't clear 95 at
750
+ # all. At 95-100 those failed outright and fell all
751
+ # the way through to an oxipng-only lossless pass —
752
+ # effectively 0% quantization gain on exactly the
753
+ # files that most needed it. At 75-100 the same
754
+ # content succeeds: measured 59.5% size reduction at
755
+ # PSNR 36.7dB on a synthetic thumbnail-heavy
756
+ # screenshot, with the resulting color error
757
+ # concentrated almost entirely inside the photo-like
758
+ # regions (mean abs error ~3.3/255 there) rather than
759
+ # spread across the image — text/UI chrome measured
760
+ # ~0.07/255, i.e. still visually exact where it
761
+ # matters most for a screenshot.
762
+ #
763
+ # If an image's complexity is too high to clear even
764
+ # 75 (rare — think a screenshot that's mostly a full
765
+ # photo), pngquant exits nonzero; see the branch below
766
+ # for how that's handled (fails cleanly for a
767
+ # non-PNG source rather than risking a bloated
768
+ # lossless PNG conversion, falls through to the
769
+ # existing lossless pass for a PNG source).
770
+ #
771
+ # Dithering is deliberately OFF here regardless of the
772
+ # caller's `dithering` setting: Floyd-Steinberg spreads
773
+ # quantization error into neighboring pixels to visually
774
+ # smooth out banding, which is the right tradeoff for
775
+ # photographic gradients but actively hurts this content
776
+ # — it scatters noise into what would otherwise be huge,
777
+ # near-free-to-compress flat UI regions, and roughens
778
+ # text edges. Measured on a synthetic screenshot: with
779
+ # dithering on, output was ~75% *larger* than with it
780
+ # off, for a *worse* mean color-error score, not better
781
+ # — there's no tradeoff being given up here, dithering
782
+ # is strictly worse for this content.
783
+ q_range = "75-100"
784
+ use_dithering = False
785
+ else:
786
+ quality_map = {"high": "80-100", "medium": "65-80", "low": "50-65"}
787
+ q_range = quality_map.get(quality, "65-80")
788
+ use_dithering = dithering
789
+
790
+ if progress_callback:
791
+ await progress_callback("color quantization...")
792
+
793
+ cmd = [
794
+ str(self.pngquant_path),
795
+ "--quality", q_range,
796
+ "--speed", "1",
797
+ "--strip",
798
+ "--skip-if-larger",
799
+ ]
800
+ if not use_dithering:
801
+ cmd.append("--nofs")
802
+
803
+ map_path: Optional[Path] = None
804
+ if protected_colors:
805
+ map_path = output_path.with_suffix(".mapcolors.png")
806
+ made = await loop.run_in_executor(None, self._make_color_map, protected_colors, map_path)
807
+ if made:
808
+ cmd += ["--map", str(map_path)]
809
+ temp_files.append(map_path)
810
+ else:
811
+ map_path = None
812
+
813
+ cmd += ["--output", str(pngquant_tmp), str(working_path)]
814
+
815
+ async with self._semaphore:
816
+ proc = await asyncio.create_subprocess_exec(
817
+ *cmd,
818
+ stdout=asyncio.subprocess.PIPE,
819
+ stderr=asyncio.subprocess.PIPE,
820
+ )
821
+ _, stderr, timed_out = await self._communicate_with_timeout(proc)
822
+
823
+ if timed_out:
824
+ # A killed pngquant can leave a partial file at its own
825
+ # --output path mid-write; remove it so the exists()
826
+ # check below can't mistake a truncated PNG for a
827
+ # completed quantization pass.
828
+ try:
829
+ pngquant_tmp.unlink(missing_ok=True)
830
+ except Exception:
831
+ pass
832
+
833
+ if pngquant_tmp.exists():
834
+ working_path = pngquant_tmp
835
+ temp_files.append(pngquant_tmp)
836
+ elif proc.returncode != 0:
837
+ msg = stderr.decode().strip()
838
+ if compression_mode == "screenshot" and not self._is_png(input_path):
839
+ # pngquant couldn't hit the 95-100 near-lossless floor
840
+ # within 256 colors. For a source that's genuinely
841
+ # PNG already, falling through to the plain lossless
842
+ # pass below is safe (no format change, and it's
843
+ # still covered by the general "don't ship a bigger
844
+ # file" guard at the end of this function). But for
845
+ # a non-PNG source forced through this PNG-only mode
846
+ # (e.g. a JPEG that turns out not to be a UI
847
+ # screenshot), that fallback would silently convert
848
+ # it to a *lossless* PNG — and lossless PNG can't
849
+ # compete with the source format's own lossy
850
+ # encoding on content this color-complex. Reproduced
851
+ # empirically: a synthetic photo that failed this
852
+ # same pngquant call came out ~14x larger as a
853
+ # lossless PNG than as the original JPEG. Fail the
854
+ # file instead of shipping that.
855
+ if progress_callback:
856
+ await progress_callback(
857
+ "screenshot mode: image too color-complex for a "
858
+ "near-lossless palette, skipped (try Standard or "
859
+ "Lossless mode instead)"
860
+ )
861
+ result["success"] = False
862
+ result["error"] = (
863
+ "Screenshot mode isn't a good fit for this image — its "
864
+ "colors are too complex for a near-lossless palette "
865
+ "(this usually means it's a photo, not a UI "
866
+ "screenshot). Try Standard or Lossless mode instead."
867
+ )
868
+ return result
869
+ if progress_callback:
870
+ await progress_callback(f"pngquant: {msg} (skipped)")
871
+ result["warning"] = msg
872
+ elif progress_callback:
873
+ if compression_mode == "screenshot":
874
+ await progress_callback("skipping color quantization (pngquant not found — falling back to lossless)")
875
+ elif compression_mode != "standard":
876
+ await progress_callback(f"skipping color quantization ({compression_mode} mode)")
877
+ else:
878
+ await progress_callback("skipping color quantization (pngquant not found)")
879
+
880
+ if self.oxipng_path and working_path.suffix.lower() == ".png":
881
+ oxipng_tmp = output_path.with_suffix(".oxipng.png")
882
+
883
+ if progress_callback:
884
+ await progress_callback("depth compression...")
885
+
886
+ async with self._semaphore:
887
+ proc = await asyncio.create_subprocess_exec(
888
+ str(self.oxipng_path),
889
+ "-o", "4",
890
+ "-a",
891
+ "--strip", "safe",
892
+ "--out", str(oxipng_tmp),
893
+ str(working_path),
894
+ stdout=asyncio.subprocess.PIPE,
895
+ stderr=asyncio.subprocess.PIPE,
896
+ )
897
+ _, stderr, timed_out = await self._communicate_with_timeout(proc)
898
+
899
+ if timed_out:
900
+ # Same partial-write hazard as pngquant above: a killed
901
+ # oxipng can leave a truncated file at --out.
902
+ try:
903
+ oxipng_tmp.unlink(missing_ok=True)
904
+ except Exception:
905
+ pass
906
+
907
+ if oxipng_tmp.exists():
908
+ # Registered as a temp BEFORE the replace: if replace()
909
+ # fails (e.g. output_path unexpectedly blocked), the
910
+ # finally-sweep still removes it. On success the file
911
+ # has moved, so the sweep's exists() check skips it.
912
+ temp_files.append(oxipng_tmp)
913
+ oxipng_tmp.replace(output_path)
914
+ else:
915
+ # Unlike pngquant above, a failed oxipng pass (timeout,
916
+ # non-zero exit, or anything else that left no --out
917
+ # file) previously fell through to this copy with no
918
+ # signal at all -- stdout/stderr weren't even captured.
919
+ # The file still came out compressed (via whatever
920
+ # pngquant/normalization already produced), but
921
+ # oxipng's own depth-compression pass was silently
922
+ # skipped. Surface it the same way pngquant already
923
+ # does above.
924
+ msg = stderr.decode().strip()
925
+ if progress_callback:
926
+ await progress_callback(f"oxipng: {msg or 'skipped'} (skipped)")
927
+ result["warning"] = msg or "oxipng produced no output"
928
+ shutil.copy2(working_path, output_path)
929
+ else:
930
+ if working_path != output_path:
931
+ shutil.copy2(working_path, output_path)
932
+
933
+ # Re-attach the cleaned EXIF as the very last PNG step, AFTER
934
+ # pngquant --strip / oxipng --strip safe have run (they remove
935
+ # all metadata, which is the point of those flags). The
936
+ # injected chunk carries no Orientation (already baked into
937
+ # pixels) — see _capture_cleaned_exif / _clean_exif.
938
+ if keep_exif and cleaned_exif:
939
+ self._finalize_png_exif(output_path, cleaned_exif)
940
+
941
+ if output_path.exists():
942
+ compressed_size = os.path.getsize(output_path)
943
+ result["compressed_size"] = compressed_size
944
+ result["success"] = True
945
+ else:
946
+ result["success"] = False
947
+ result["error"] = "output file not generated"
948
+
949
+ self._apply_growth_guard(
950
+ input_path, output_path, "png", result, keep_exif, cleaned_exif
951
+ )
952
+
953
+ except Exception as e:
954
+ result["success"] = False
955
+ result["error"] = str(e)
956
+
957
+ finally:
958
+ # Sweep temps on success AND on the exception path — they live
959
+ # inside ws/output, and /api/download zips that tree with
960
+ # rglob("*"), so leftovers like *.src.png would end up in the
961
+ # user's ZIP.
962
+ for f in temp_files:
963
+ try:
964
+ if f.exists() and f != output_path:
965
+ f.unlink()
966
+ except Exception:
967
+ pass
968
+
969
+ return result
970
+
971
+ async def _optimize_webp(
972
+ self,
973
+ input_path: Path,
974
+ output_path: Path,
975
+ quality: str,
976
+ max_width: int,
977
+ compression_mode: str,
978
+ progress_callback: Optional[Callable],
979
+ *,
980
+ keep_exif: bool = False,
981
+ cleaned_exif: bytes = b"",
982
+ ) -> dict:
983
+ """WebP goes through Pillow's own encoder rather than pngquant/oxipng
984
+ (which only understand PNG) — there's no external binary dependency
985
+ for this format, so it works even without pngquant/oxipng installed."""
986
+ original_size = os.path.getsize(input_path)
987
+ result = {
988
+ "success": False,
989
+ "original_size": original_size,
990
+ "compressed_size": original_size,
991
+ "error": None,
992
+ "warning": None,
993
+ }
994
+ try:
995
+ loop = asyncio.get_running_loop()
996
+
997
+ def _encode():
998
+ with Image.open(input_path) as opened:
999
+ # Same EXIF-orientation bake-in as _ensure_png — WebP
1000
+ # output shouldn't come out sideways either.
1001
+ img = ImageOps.exif_transpose(opened)
1002
+ if img.mode == "CMYK":
1003
+ img = img.convert("RGB")
1004
+
1005
+ if max_width > 0:
1006
+ w, h = img.size
1007
+ if w > max_width:
1008
+ ratio = max_width / w
1009
+ img = img.resize((max_width, int(h * ratio)), Image.Resampling.LANCZOS)
1010
+
1011
+ # Drop any EXIF carried in info so default (keep_exif=False)
1012
+ # WebP output is metadata-free; attach the cleaned copy
1013
+ # explicitly only when requested (no Orientation → no
1014
+ # double-rotation, same guard as the PNG path).
1015
+ img.info.pop("exif", None)
1016
+ if compression_mode == "lossless" or compression_mode == "resize_only":
1017
+ save_kwargs = {"format": "WEBP", "lossless": True, "method": 6}
1018
+ else:
1019
+ quality_map = {"high": 90, "medium": 75, "low": 55}
1020
+ q = quality_map.get(quality, 75)
1021
+ save_kwargs = {"format": "WEBP", "quality": q, "method": 6}
1022
+ if keep_exif and cleaned_exif:
1023
+ save_kwargs["exif"] = cleaned_exif
1024
+ img.save(output_path, **save_kwargs)
1025
+
1026
+ if progress_callback:
1027
+ mode_desc = "lossless" if compression_mode in ("lossless", "resize_only") else f"quality={quality}"
1028
+ await progress_callback(f"encoding WebP ({mode_desc})...")
1029
+
1030
+ async with self._semaphore:
1031
+ await loop.run_in_executor(None, _encode)
1032
+
1033
+ if output_path.exists():
1034
+ result["compressed_size"] = os.path.getsize(output_path)
1035
+ result["success"] = True
1036
+ else:
1037
+ result["error"] = "output file not generated"
1038
+
1039
+ self._apply_growth_guard(
1040
+ input_path, output_path, "webp", result, keep_exif, cleaned_exif
1041
+ )
1042
+ except Exception as e:
1043
+ result["success"] = False
1044
+ result["error"] = str(e)
1045
+
1046
+ return result
1047
+
1048
+ async def _optimize_jpeg(
1049
+ self,
1050
+ input_path: Path,
1051
+ output_path: Path,
1052
+ quality: str,
1053
+ max_width: int,
1054
+ compression_mode: str,
1055
+ progress_callback: Optional[Callable],
1056
+ *,
1057
+ keep_exif: bool = False,
1058
+ cleaned_exif: bytes = b"",
1059
+ ) -> dict:
1060
+ """Lossy JPEG re-encode through mozjpeg's cjpeg, keeping the JPEG
1061
+ format (the output stays a .jpg — no conversion to PNG/WebP).
1062
+
1063
+ Why not pngquant/oxipng? Those only understand PNG input, and the
1064
+ whole point of this path is a *genuine JPEG* compression. The
1065
+ source is decoded with Pillow (EXIF orientation baked in, optional
1066
+ resize, alpha composited onto white since JPEG has no alpha
1067
+ channel), written to a PPM intermediate, then re-encoded by cjpeg
1068
+ — mozjpeg's encoder produces smaller JPEGs than stock libjpeg at
1069
+ equal quality (trellis quantization + tuned progressive output).
1070
+ The PPM detour is deliberate: several common mozjpeg Windows
1071
+ builds ship a cjpeg without the rdpng/rdjpeg readers, so the only
1072
+ input format guaranteed to work on every build is PPM/PGM.
1073
+
1074
+ Mode semantics for JPEG (an inherently lossy codec):
1075
+ - standard -> cjpeg -quality from the {high, medium, low} map
1076
+ - lossless -> no true lossless JPEG pass exists; maps to the
1077
+ highest cjpeg quality (95) so the re-encode loses as little as
1078
+ possible. Name kept for consistency with the other formats;
1079
+ the UI/available_modes docs make clear what it actually does.
1080
+ - resize_only -> resize first, then encode at that same high
1081
+ quality so the savings come from the smaller dimensions rather
1082
+ than from dropping image quality.
1083
+ """
1084
+ original_size = os.path.getsize(input_path)
1085
+ result = {
1086
+ "success": False,
1087
+ "original_size": original_size,
1088
+ "compressed_size": original_size,
1089
+ "error": None,
1090
+ "warning": None,
1091
+ }
1092
+ if self.cjpeg_path is None:
1093
+ result["error"] = "cjpeg (mozjpeg) not found — cannot produce JPEG output"
1094
+ return result
1095
+
1096
+ quality_map = {"high": 85, "medium": 75, "low": 60}
1097
+ if compression_mode in ("lossless", "resize_only"):
1098
+ q = 95
1099
+ else:
1100
+ q = quality_map.get(quality, 75)
1101
+
1102
+ temp_files: list = []
1103
+ try:
1104
+ loop = asyncio.get_running_loop()
1105
+ ppm_path = output_path.with_suffix(".src.ppm")
1106
+ tmp_jpg = output_path.with_suffix(".cjpeg.jpg")
1107
+ temp_files = [ppm_path, tmp_jpg]
1108
+
1109
+ def _prepare_ppm():
1110
+ with Image.open(input_path) as opened:
1111
+ # Same orientation bake-in as _ensure_png / _optimize_webp
1112
+ # — a portrait phone JPEG must not come out sideways.
1113
+ img = ImageOps.exif_transpose(opened)
1114
+ if img.mode == "CMYK":
1115
+ img = img.convert("RGB")
1116
+ elif img.mode not in ("RGB", "L", "I;16"):
1117
+ # RGBA/LA/PA/P carry an alpha channel JPEG can't
1118
+ # hold — composite transparency onto white instead
1119
+ # of a bare convert("RGB"), which renders it black.
1120
+ rgba = img.convert("RGBA")
1121
+ bg = Image.new("RGB", rgba.size, (255, 255, 255))
1122
+ bg.paste(rgba, mask=rgba.getchannel("A"))
1123
+ img = bg
1124
+
1125
+ if max_width > 0:
1126
+ w, h = img.size
1127
+ if w > max_width:
1128
+ ratio = max_width / w
1129
+ img = img.resize((max_width, int(h * ratio)), Image.Resampling.LANCZOS)
1130
+
1131
+ # cjpeg starts fresh from the PPM so metadata can't
1132
+ # survive (matches the keep_exif=False strip-everything
1133
+ # default). When keep_exif=True the cleaned copy is
1134
+ # re-attached after encoding via _finalize_jpeg_exif.
1135
+ img.info.pop("exif", None)
1136
+ img.save(ppm_path, format="PPM")
1137
+
1138
+ if progress_callback:
1139
+ mode_desc = "near-lossless" if compression_mode in ("lossless", "resize_only") else f"quality={q}"
1140
+ await progress_callback(f"encoding JPEG via mozjpeg ({mode_desc})...")
1141
+ await loop.run_in_executor(None, _prepare_ppm)
1142
+
1143
+ async with self._semaphore:
1144
+ proc = await asyncio.create_subprocess_exec(
1145
+ str(self.cjpeg_path),
1146
+ "-quality", str(q),
1147
+ "-progressive",
1148
+ "-optimize",
1149
+ "-outfile", str(tmp_jpg),
1150
+ str(ppm_path),
1151
+ stdout=asyncio.subprocess.PIPE,
1152
+ stderr=asyncio.subprocess.PIPE,
1153
+ )
1154
+ _, stderr, timed_out = await self._communicate_with_timeout(proc)
1155
+
1156
+ if timed_out:
1157
+ # Killed cjpeg can leave a partial file at -outfile.
1158
+ try:
1159
+ tmp_jpg.unlink(missing_ok=True)
1160
+ except Exception:
1161
+ pass
1162
+
1163
+ if tmp_jpg.exists():
1164
+ if keep_exif and cleaned_exif:
1165
+ self._finalize_jpeg_exif(tmp_jpg, cleaned_exif)
1166
+ tmp_jpg.replace(output_path)
1167
+ else:
1168
+ msg = stderr.decode().strip()
1169
+ if progress_callback:
1170
+ await progress_callback(f"cjpeg: {msg} (skipped)")
1171
+ result["warning"] = msg or "cjpeg produced no output"
1172
+ result["error"] = "cjpeg did not produce an output file"
1173
+ return result
1174
+
1175
+ if output_path.exists():
1176
+ result["compressed_size"] = os.path.getsize(output_path)
1177
+ result["success"] = True
1178
+ else:
1179
+ result["error"] = "output file not generated"
1180
+
1181
+ self._apply_growth_guard(
1182
+ input_path, output_path, "jpg", result, keep_exif, cleaned_exif
1183
+ )
1184
+ except Exception as e:
1185
+ result["success"] = False
1186
+ result["error"] = str(e)
1187
+ finally:
1188
+ for f in temp_files:
1189
+ try:
1190
+ if f.exists() and f != output_path:
1191
+ f.unlink()
1192
+ except Exception:
1193
+ pass
1194
+
1195
+ return result
1196
+
1197
+ @staticmethod
1198
+ def _finalize_jpeg_exif(jpg_path: Path, exif_bytes: bytes) -> None:
1199
+ """Attach cleaned EXIF to a finished JPEG by inserting a single APP1
1200
+ 'Exif' segment right after the SOI marker.
1201
+
1202
+ cjpeg writes metadata-free output from the PPM intermediate, so the
1203
+ finished .jpg only ever carries the EXIF we inject here (preserving
1204
+ the keep_exif=False strip-everything default). JPEG APP1 Exif
1205
+ payloads are `Exif\\x00\\x00` followed by raw TIFF; cleaned_exif
1206
+ from _capture_cleaned_exif is already the raw TIFF (prefix
1207
+ stripped), so the prefix is re-added here. Best-effort — never
1208
+ raises: a failed metadata attach must not turn a successful
1209
+ compression into a failure."""
1210
+ if not exif_bytes:
1211
+ return
1212
+ if exif_bytes[:1] not in (b"I", b"M"):
1213
+ return
1214
+ try:
1215
+ data = jpg_path.read_bytes()
1216
+ if data[:2] != b"\xff\xd8": # not a JPEG (no SOI marker) — bail
1217
+ return
1218
+ payload = b"Exif\x00\x00" + exif_bytes
1219
+ segment = b"\xff\xe1" + struct.pack(">H", len(payload) + 2) + payload
1220
+ jpg_path.write_bytes(data[:2] + segment + data[2:])
1221
+ except Exception:
1222
+ pass
1223
+
1224
+ async def _optimize_avif(
1225
+ self,
1226
+ input_path: Path,
1227
+ output_path: Path,
1228
+ quality: str,
1229
+ max_width: int,
1230
+ compression_mode: str,
1231
+ progress_callback: Optional[Callable],
1232
+ *,
1233
+ keep_exif: bool = False,
1234
+ cleaned_exif: bytes = b"",
1235
+ ) -> dict:
1236
+ """AVIF encode through avifenc. Source is decoded with Pillow (EXIF
1237
+ orientation baked in, optional resize) and written to a PNG
1238
+ intermediate, then re-encoded by avifenc.
1239
+
1240
+ The intermediate used to be a ".ppm" file under the assumption that
1241
+ avifenc needed Y4M/PPM for reliability, but real avifenc builds
1242
+ (verified against the official libavif CLI, v1.3.0) only accept
1243
+ `input.[jpg|jpeg|png|y4m]` — PPM isn't recognized at all, so every
1244
+ AVIF encode failed unconditionally. PNG is lossless (so it doesn't
1245
+ cost any quality versus the old approach) and, unlike a Y4M/PPM
1246
+ intermediate, carries an alpha channel straight through, so alpha
1247
+ is now preserved instead of being composited onto white — AVIF
1248
+ supports transparency natively, so there's no reason to throw it
1249
+ away like the JPEG intermediate has to.
1250
+
1251
+ Mode semantics:
1252
+ - standard -> avifenc -q from the {high, medium, low} map
1253
+ - lossless -> avifenc --lossless (true lossless AVIF)
1254
+ - resize_only -> avifenc --lossless after resizing, same as the
1255
+ lossless branch — AVIF supports true lossless just like PNG/WebP,
1256
+ so (like those two, and unlike JPEG, which has no lossless mode
1257
+ and has to settle for its highest quality instead) "Resize Only"
1258
+ means exactly that: savings come only from the smaller
1259
+ dimensions, never from a quality/palette change.
1260
+ """
1261
+ original_size = os.path.getsize(input_path)
1262
+ result = {
1263
+ "success": False,
1264
+ "original_size": original_size,
1265
+ "compressed_size": original_size,
1266
+ "error": None,
1267
+ "warning": None,
1268
+ }
1269
+ if self.avifenc_path is None:
1270
+ result["error"] = "avifenc not found — cannot produce AVIF output"
1271
+ return result
1272
+
1273
+ quality_map = {"high": 80, "medium": 60, "low": 40}
1274
+ # resize_only groups with lossless (not with the quality_map branch
1275
+ # below) — see the docstring: AVIF has a real --lossless mode, so
1276
+ # unlike JPEG there's no reason for "Resize Only" to cost any
1277
+ # quality here.
1278
+ is_lossless = compression_mode in ("lossless", "resize_only")
1279
+ q = quality_map.get(quality, 60) if not is_lossless else None
1280
+
1281
+ temp_files: list = []
1282
+ try:
1283
+ loop = asyncio.get_running_loop()
1284
+ intermediate_path = output_path.with_suffix(".src.png")
1285
+ tmp_avif = output_path.with_suffix(".avifenc.avif")
1286
+ temp_files = [intermediate_path, tmp_avif]
1287
+
1288
+ def _prepare_intermediate():
1289
+ with Image.open(input_path) as opened:
1290
+ img = ImageOps.exif_transpose(opened)
1291
+ if img.mode == "CMYK":
1292
+ img = img.convert("RGB")
1293
+ elif img.mode not in ("RGB", "RGBA", "L"):
1294
+ # Anything else (P/palette, LA, etc.) — normalize to
1295
+ # RGBA so a possible alpha channel survives; avifenc
1296
+ # reads alpha straight from the PNG.
1297
+ img = img.convert("RGBA")
1298
+ elif img.mode == "L":
1299
+ img = img.convert("RGB")
1300
+
1301
+ if max_width > 0:
1302
+ w, h = img.size
1303
+ if w > max_width:
1304
+ ratio = max_width / w
1305
+ img = img.resize((max_width, int(h * ratio)), Image.Resampling.LANCZOS)
1306
+
1307
+ img.info.pop("exif", None)
1308
+ img.save(intermediate_path, format="PNG")
1309
+
1310
+ if progress_callback:
1311
+ mode_desc = "lossless" if is_lossless else f"quality={q}"
1312
+ await progress_callback(f"encoding AVIF via avifenc ({mode_desc})...")
1313
+ await loop.run_in_executor(None, _prepare_intermediate)
1314
+
1315
+ cmd = [
1316
+ str(self.avifenc_path),
1317
+ ]
1318
+ if is_lossless:
1319
+ cmd += ["--lossless"]
1320
+ else:
1321
+ # avifenc has no long-form "--quality" flag — it's
1322
+ # -q/--qcolor (verified against the official CLI's --help).
1323
+ # The old "--quality" flag was simply unrecognized, so every
1324
+ # non-lossless AVIF encode failed on top of the PPM issue
1325
+ # above.
1326
+ cmd += ["-q", str(q)]
1327
+ cmd += ["--speed", "6"]
1328
+ if keep_exif and cleaned_exif:
1329
+ exif_path = output_path.with_suffix(".exif")
1330
+ exif_path.write_bytes(cleaned_exif)
1331
+ temp_files.append(exif_path)
1332
+ cmd += ["--exif", str(exif_path)]
1333
+ cmd += ["-o", str(tmp_avif), str(intermediate_path)]
1334
+
1335
+ async with self._semaphore:
1336
+ proc = await asyncio.create_subprocess_exec(
1337
+ *cmd,
1338
+ stdout=asyncio.subprocess.PIPE,
1339
+ stderr=asyncio.subprocess.PIPE,
1340
+ )
1341
+ _, stderr, timed_out = await self._communicate_with_timeout(proc)
1342
+
1343
+ if timed_out:
1344
+ # Killed avifenc can leave a partial file at -o; the
1345
+ # size>0 check below isn't enough on its own to catch a
1346
+ # truncated-but-nonempty AVIF bitstream.
1347
+ try:
1348
+ tmp_avif.unlink(missing_ok=True)
1349
+ except Exception:
1350
+ pass
1351
+
1352
+ if tmp_avif.exists() and tmp_avif.stat().st_size > 0:
1353
+ tmp_avif.replace(output_path)
1354
+ else:
1355
+ msg = stderr.decode().strip()
1356
+ if progress_callback:
1357
+ await progress_callback(f"avifenc: {msg} (skipped)")
1358
+ result["warning"] = msg or "avifenc produced no output"
1359
+ result["error"] = "avifenc did not produce an output file"
1360
+ return result
1361
+
1362
+ if output_path.exists():
1363
+ result["compressed_size"] = os.path.getsize(output_path)
1364
+ result["success"] = True
1365
+ else:
1366
+ result["error"] = "output file not generated"
1367
+ except Exception as e:
1368
+ result["success"] = False
1369
+ result["error"] = str(e)
1370
+ finally:
1371
+ for f in temp_files:
1372
+ try:
1373
+ if f.exists() and f != output_path:
1374
+ f.unlink()
1375
+ except Exception:
1376
+ pass
1377
+
1378
+ return result