[Postponed] Resizer: capability-gated multi-frame resize for animated AVIF/WebP/GIF (blocked on backend sequence decoding)

[parisek]

Follow-up to #60.

Background

#60 fixes the regression where the resizer flattened animated AVIF / WebP / GIF to a single frame: it now detects an animated source and passes the original through untouched (timber_kit_resizer_skip_animated, default true). That's the correct, portable default — but the animated source is then served at full size, unresized.

This issue tracks the next step: actually resize/crop animated sources when — and only when — the active backend can re-encode them with animation preserved, falling back to passthrough otherwise.

The hard requirement: decide at RUNTIME, never assume

The original bug came from a static assumption (an allow-list that silently sent AVIF into a single-frame pipeline). We must not reintroduce that shape. The multi-frame path must be gated on a runtime capability probe, so on a backend that can't write animated output we fall back to passthrough instead of flattening.

Concretely, before attempting an animated re-encode, probe the active backend for the target format:

• Imagick present? extension_loaded('imagick').
• Format multi-image read+write? Imagick::queryFormats() + the format's multi-image (+) capability. (magick -list format shows e.g. AVIF rw+, WEBP* rw+, GIF* rw+ when the coder supports multiple images.)
• libheif new enough for AVIF/HEIC sequences? Gate AVIF/HEIC on a libheif version probe, or — most robust — a tiny round-trip self-test done once and cached: encode a 2-frame in-memory image to the target format with writeImages(..., true), read it back, assert getNumberImages() > 1. If the round-trip fails, treat the backend as "cannot animate this format" and pass through.
• Cache the probe result per (format) per request/process so it isn't repeated per image.

Decision table per source:

Source animated?	Backend can re-encode animated <fmt>?	Action
no	—	resize normally (current path)
yes	yes	multi-frame resize (this issue)
yes	no	passthrough (the #60 behaviour — never flatten)

Implementation notes

• Spatie\Image cannot express multi-frame. The animated branch must be a dedicated raw Imagick path: new Imagick($src) → coalesceImages() → per-frame cropImage() / scaleImage() → setImageFormat() / quality → writeImages($target, true) (note: writeImages, plural, with $adjoin = true). Reuse the existing crop-position / variant normalisation.
• Wire it into the existing gate. Today timber_kit_resizer_skip_animated => false just reverts to the flattening pipeline (no multi-frame write exists), so the escape hatch is currently a no-op-toward-animation. This issue makes false meaningful: attempt the capability-gated animated resize; still fall back to passthrough when the probe says the backend can't.
• Scope: AVIF, WebP, GIF. GIF multi-frame write via Imagick is reliable; WebP via libwebp is reliable; AVIF via libheif is the fragile one — hence the round-trip self-test gate.
• Quality/size: animated re-encodes can be large; consider a per-format max-frames / max-dimension guard and log()/filter to opt out per project.

Production reality (motivating data)

On the wearemullet production box (Cloudways): PHP 8.3.31, ImageMagick 7.1.2-8, libheif 1.20.2, Imagick loaded, AVIF/HEIC/WEBP/GIF all rw+, GD AVIF+WebP+GIF. So on capable servers like this, animated AVIF resize is genuinely achievable — the runtime probe lets those servers benefit while older/leaner backends keep the safe passthrough.

Acceptance criteria

• Runtime capability probe per target format (Imagick + multi-image flag + libheif sequence support / cached round-trip self-test).
• Animated source + capable backend → resized variants that retain animation (verified getNumberImages() > 1 on output).
• Animated source + incapable backend → passthrough (original returned, never flattened).
• Static sources unchanged.
• Probe result memoised; no per-image backend spin-up beyond what fix(resizer)!: preserve animation for AVIF/WebP/GIF (passthrough on by default) #60 already does.
• Tests: capable-backend (skip if unavailable in CI) animated round-trip; incapable-backend → passthrough; probe memoisation.

Related

• fix(resizer)!: preserve animation for AVIF/WebP/GIF (passthrough on by default) #60 — passthrough fix (the safe default this builds on)

[parisek]

Production reality check (wearemullet) — corrects the "achievable on prod" premise

Verified library versions and actual decode behaviour on the wearemullet production box (Cloudways) and the local DDEV box (read-only — version probes + an in-memory round-trip, no writes):

	dev (DDEV)	production
ImageMagick (php-imagick)	7.1.1-43	7.1.2-8
libheif (system)	1.19.8	1.15.1
canEncodeAnimated('avif') round-trip	2 (capable)	2 (capable)
getNumberImages() on bara.avif (avis, 42 frames)	1	1

The team-slider AVIFs are genuine animated image-sequences (avis brand, moov/tracks, 37–43 frames). Neither box decodes them as multi-frame — ImageMagick's HEIC coder reads top-level image items, not sequence tracks, so getNumberImages() returns 1 even on prod's 7.1.2-8. The round-trip self-test passes (IM reads back its own 2-frame write), but that does not imply it can read externally-authored AVIF sequences.

Consequences:

• For these files, multi-frame resize is not achievable on prod either — passthrough is the only correct outcome (not resize). The motivating-data claim that "animated AVIF resize is genuinely achievable" on this box does not hold for avis sequences.
• The original Imagick-authoritative detection would have flattened these on prod too (getNumberImages()=1 → treated static), exactly as on dev. fix(resizer)!: preserve animation for AVIF/WebP/GIF (passthrough on by default) #60's passthrough never triggered because it trusted the frame count; the manual twig workaround was the only thing preserving the production animation.

Fix (in #62): detection is now a union of the Imagick frame count and the structural byte-sniff (avis / VP8X ANIM / GIF descriptors); the multi-frame path only runs when the backend actually decodes >1 frame from the source. A structurally-animated source the backend under-decodes now passes through (animation preserved) instead of being flattened. Verified end-to-end on the wearemullet DDEV box: the team AVIFs passthrough (original served, animation intact), static images still resize normally.

[parisek]

Scope decision: PR #62 narrowed to detection + passthrough; multi-frame resize deferred (stays here)

After building and testing the full capability-gated multi-frame path, we're narrowing PR #62 to deliver only what's genuinely useful and reliable now: robust animation detection + passthrough. The multi-frame resize (this issue's original title) is deferred and remains tracked here.

Why defer the resize:

• No commonly-available ImageMagick decodes the real animated AVIF image-sequences as multi-frame — verified getNumberImages()=1 on both the dev box (libheif 1.19.8) and production (ImageMagick 7.1.2-8). So the multi-frame path could never even run for these files; passthrough is the correct outcome.
• Transparency limitation (the other reason): animated WebP output loses its alpha channel through the Imagick pipeline on the tested build (coalesce keeps alpha, but the animated-WebP encoder drops it; per-frame alpha activation + transparent background did not fix it). Animated AVIF output preserved alpha; GIF is binary. So a multi-frame resize would silently strip transparency for WebP targets — unacceptable without a per-source, alpha-aware capability gate.

What PR #62 ships: isAnimated() becomes a union of Imagick's frame count and the structural sniff (avis / VP8X ANIM / GIF descriptors), so animated sources the backend under-decodes are still detected and passed through (never flattened). Surface unchanged from #60.

Remaining future work for this issue:

• Capability-gated multi-frame resize (when a backend can both decode the source frames and re-encode the target with animation).
• Alpha-aware capability probe: round-trip an alpha-bearing animated frame and only resize when transparency survives for the target format; otherwise passthrough.
• AVIF image-sequence (avis/moov tracks) decode support — blocked on ImageMagick's HEIC coder iterating sequence tracks (libheif ≥1.20 sequence API; not exposed by current IM coders).

[parisek]

Investigation log & postponement record

This documents the full attempt at multi-frame resize with animation preserved, so the work is defined for the future. Status: postponed — blocked on backend (ImageMagick/libheif) being able to decode AVIF image-sequences as multi-frame. PR #62 shipped only the safe, reliable subset (animation detection + passthrough); everything below is the deferred part.

Goal

Resize/crop animated AVIF/WebP/GIF and keep the animation, instead of passing the full-size original through.

What was built (then removed from PR #62)

• Runtime capability probe canEncodeAnimated() — memoised per format, backed by a real round-trip self-test (probeAnimatedEncode()): build a 2-frame in-memory image, getImagesBlob() (adjoined), read back, assert getNumberImages() > 1. Never assume from a version string.
• Raw-Imagick multi-frame path processAnimatedVariant() — new Imagick($src) → coalesceImages() → per-frame scaleImage() / cover-scale + cropImage() → writeImages($target, true); imagickFrameCount frame cap; all handles freed.
• cropOffset() pure positional-crop helper. Full TDD + reviews. It all worked for GIF (unit tests resized a real 2-frame GIF and read back >1 frame in DDEV).

The blocker — verified across THREE environments (two dev + production)

The real-world sources (wearemullet team-slider) are animated AVIF image-sequences: major brand = avis, moov/tracks, 37–43 frames (e.g. bara.avif: stsz sample_count = 42, 95 078 B). Yet every available ImageMagick decodes them as one frame:

Environment	ImageMagick	libheif	getNumberImages() on the 42-frame bara.avif	AVIF write round-trip (canEncodeAnimated)
timber-kit DDEV	7.1.1-43	1.19.8	1	2 (capable)
wearemullet DDEV	7.1.1-43	1.19.8	1	2 (capable)
wearemullet production (Cloudways)	7.1.2-8	1.15.1 (system)	1	2 (capable)

heif-info (libheif 1.19.8) on the file: MIME type: image/avif-sequence, main brand: avis, but it lists only image: 320x320 (id=1), primary — i.e. it does not enumerate the sequence frames.

Root cause: ImageMagick's HEIC coder reads top-level image items, not sequence tracks (moov). An AVIF image-sequence has exactly one top-level item (the primary) plus the frames in a track. libheif's sequence/track reading API arrived in 1.20, and even then the IM coder must call it — current IM coders (7.1.1-43 and prod 7.1.2-8) don't. The round-trip passes only because IM reads back its own 2-frame write, which is not a track-based sequence.

Things we tried to unblock it

• Compile libheif 1.20.2 and swap it under the existing ImageMagick (built in-container with built-in dav1d/aom, installed over the multiarch path, ldconfig). Result: getNumberImages() still 1. Confirms libheif alone is insufficient — the IM coder doesn't iterate sequence tracks regardless of libheif version. (Reverted cleanly; php-imagick intact.)
• Full prod reproduction (compile IM 7.1.2-8 + libheif 1.20.2 in a custom DDEV image) was scoped but not pursued: high effort, risks the php-imagick ABI, and prod itself (IM 7.1.2-8) already shows the same 1-frame result — so it would not have changed the outcome.

Transparency (second blocker, independent of the above)

Even where multi-frame does work (GIF, and IM-authored multi-frame AVIF), animated WebP output drops the alpha channel on the tested IM/libwebp build: after coalesceImages() the frame still has alpha, but the animated-WebP encoder writes it out opaque (alpha_ch=n); per-frame setImageAlphaChannel(ACTIVATE) + transparent background did not fix it. Animated AVIF output preserved alpha; GIF is binary only. So a multi-frame resize that targets WebP would silently strip transparency.

Conclusion / why postponed

For the real files, multi-frame resize is not achievable on any environment we have (dev or prod), so passthrough is the correct outcome — which is exactly what PR #62 now guarantees via union detection. Pursuing the resize further is blocked on server-side technology, not on our code.

Unblock criteria (revisit when the server stack updates)

• An ImageMagick build whose HEIC coder iterates AVIF sequence tracks (needs libheif ≥1.20 sequence API and coder support) — verify with getNumberImages() > 1 on a real avis file.
• Alpha-aware capability probe: round-trip an alpha-bearing animated frame and only resize when transparency survives for the target format; otherwise passthrough. (Covers the animated-WebP alpha loss.)
• Re-introduce processAnimatedVariant() / canEncodeAnimated() / cropOffset() (full history on the feature/resizer-animated-multiframe branch, pre-narrowing commits) behind the hardened detection that fix(resizer): robust animation detection + passthrough for animated AVIF/WebP/GIF (#61) #62 ships.

Related: #60 (passthrough), PR #62 (detection + passthrough — the shipped subset).