imgtune 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,79 @@
 # Changelog
 
+## 0.2.0 (2026-11-14)
+
+- Animated media and video. `scan` measures animated GIFs (in an `<img>` or a CSS background), animated WebP and APNG, and
+  self-hosted `<video>` elements with a plain file source. Each page gets a Video section with the bytes per view and per
+  play, and the levers (audio, width, codec, preload, poster). Adaptive streams (HLS, DASH, Mux, Cloudflare Stream) and
+  third-party iframes (YouTube, Vimeo) are not reported. A video hosted on another site follows the third-party rules.
+- Hints for animated media. A large animated GIF gets `<video autoplay muted loop playsinline>` with AV1 first and an H.264
+  fallback. The H.264 fallback is a recipe (libx264, CRF 23, yuv420p, faststart), marked not measured. The animated-image
+  alternative is shown with its size. A small `<img>` GIF or a CSS background gets an animated AVIF or WebP, and only its
+  `src` changes. A `<video>` hint names each lever: the width per breakpoint (`<source media>`), the CRF, the codec, the
+  audio track of a muted video, and `preload`. A poster is audited through the image pipeline. Duration and frame rate are
+  informational notes only, never part of the claim.
+- Static GIFs (one frame) get the normal image hints. Animated images stay in the image totals.
+- Bytes per view and per play. Per view is what the first view fetches: an autoplay video counts its full file,
+  `preload="auto"` counts the bytes the scan saw (labelled browser-dependent), and `preload="metadata"` or `"none"` counts 0.
+  Per play is the full file, shown for every video, so a large click-to-play file is not missed. A URL's bytes are the union
+  of the byte ranges read, capped at the file length, and a length probe reads the size when the server sends no
+  Content-Length, so a looping video is not counted once per loop. Posters count as images.
+- Quality bars. A candidate must reach VMAF 93 (`--video-bar`) against the served file at its display size. A still-frame
+  guard (SSIMULACRA2 on the stillest frames) catches blurred text in screen recordings. Its bar is `--video-still-bar`
+  (default 65), lowered to at most 10 points below the best the same codec reaches on that content, and never below 20. The
+  relative bar catches the loss the encode adds, not what a format can never reproduce, such as GIF dither. For GIF sources
+  both frames of the guard are blurred slightly (Gaussian, sigma 1) before scoring, so dither the eye averages out does not
+  fail it.
+- Encodes and budget. Encodes run on the heaviest animated assets first (by per-view bytes), at most `--media-budget` per run
+  (default 20) and within `--media-time` seconds (default 600). Assets over the budget keep their cheap hints and are marked
+  "over --media-budget". The CRF search runs on 2 s sample clips: one for a video of up to 6 s, three for a longer one. The
+  full-file bytes are extrapolated from the samples and labelled as an estimate; nothing is encoded in full. Each asset is
+  encoded once per run, keyed by URL and content hash in the result cache. Widths are snapped to a few buckets first.
+- Video widths. `scan` and `check` serve each video at most `--max-video-widths` widths (default 2): each viewport gets the
+  smallest kept width that covers its display width times its device pixel ratio. `audit` does not choose: it reports each
+  viewport's needed width and the bytes per view at one, two and three widths.
+- ffmpeg. The system ffmpeg on `PATH` is used; ImgTune does not bundle it. Without it, animated media is still detected, and
+  its bytes and needed width are still reported, with one note: `install ffmpeg for verified video and GIF hints`. ffmpeg and
+  ffprobe read only the protocols they need, and a URL input goes through the egress proxy (the scan's own policy for
+  private addresses), so a scanned page cannot reach a private host through a video.
+- `imgtune image` accepts GIF, animated WebP and APNG (candidates: animated AVIF, animated WebP and AV1 MP4 at `--width`),
+  and MP4 and WebM. `--reference <original>` checks a candidate against the original with the same VMAF and still-frame bars.
+  It prints one line, `VMAF <v> (bar <b>) still p10 <s> (bar <sb>): pass|fail`, and exits 0 or 1.
+- `audit` locates `<video>` and GIF elements at `file:line`, as it locates images. `hints` prints the animated and video hints.
+- Network idle. A streaming media request does not hold the wait for network idle, so an autoplay video does not hold each
+  resize up to `--idle-timeout`.
+- Scan JSON. Each page gains `videos` and `mediaNote`, and an animated image record gains `fix.animated`. The resume record
+  gains the media settings (`mediaBudget`, `mediaTime`, `videoBar`, `videoStillBar`, `maxVideoWidths`, `ffmpeg`).
+- New flags, with their defaults: `--media-budget <N>` (20, 0 to 1000), `--media-time <s>` (600, 1 to 3600), `--video-bar <n>`
+  (93), `--video-still-bar <n>` (65), `--max-video-widths <n>` (2, 1 to 3). `--survey` and `--no-quality` make no encodes.
+  `image` takes `--reference`, `--video-bar` and `--video-still-bar`.
+- `--gpu-encode` (experimental, off by default). The media encodes run on the GPU with NVENC (`av1_nvenc`, `h264_nvenc`), and
+  VMAF runs on the GPU with `libvmaf_cuda` when the ffmpeg on `PATH` has it. The NVENC bytes are scaled by 1 / 1.4 to a CPU
+  encode and labelled `est. (GPU-encoded, scaled to a CPU encode ÷1.4)`. Each GPU is proven by a small test encode first, and
+  a width under 144 px is encoded on the CPU. In our measurements it was slower than the CPU on 2 s samples (CUDA starts once
+  per ffmpeg process), so the CPU stays the default.
+- `--gpu-device` takes a comma list (`0,1`). The first GPU scores. With `--gpu-encode`, each listed GPU gets its own encode
+  workers beside the CPU ones. `--gpu` alone is unchanged.
+- Ctrl-C and SIGTERM stop the whole run: the media phase is aborted, the pages already written are kept, and the process
+  exits 130 (SIGINT) or 143 (SIGTERM) within 2 s.
+- Media fetches and the ffmpeg reads of a page's videos go through the egress proxy. ffmpeg's `httpproxy` tunnel is allowed,
+  so `https` videos are read through it.
+- Animated WebP and APNG are decoded one frame at a time, only for the frames of each 2 s sample window, and streamed to
+  ffmpeg. A long animation does not fill memory, and the pixel limit applies to each frame.
+- A measured page's JSON is written after its image estimates and before the media phase, so a long media phase does not
+  hold back the results.
+- Cache: `CACHE_VERSION` is 3. Entries from 0.1 are not read, so the first scan on 0.2 is cold.
+- Changes for 0.1 users:
+  - A scan that encodes media takes longer. The encodes are bounded by `--media-time` (600 s) and `--media-budget` (20
+    assets); `--no-quality` or `--survey` keeps the 0.1 timing.
+  - Without ffmpeg on `PATH`, `scan` prints one note and gives no encode hints.
+  - `--resume` scans a 0.1 page again when the new run encodes media, because its record has no media settings. A run with
+    no encodes (`--no-quality`, `--survey`, or no ffmpeg) resumes 0.1 pages as before.
+  - The JSON gains fields (`videos`, `mediaNote`, `fix.animated`, the resume media settings); existing fields are unchanged.
+    Animated GIFs, WebP and APNG keep their place in the image totals, but their hint is now a video or animated-image hint.
+  - `<video>` elements are not image records: their bytes are in the Video section, and their posters are images.
+  - The cache is not reused across the version change (see above).
+
 ## 0.1.0 (2026-11-03)
 
 - LCP first. Each scanned page reads the largest contentful paint before its first scroll, per viewport. A page's report

package/README.md

@@ -143,6 +143,46 @@ Every fix hint is labelled with the strength of its evidence, the rung it stands
 A ceiling is never derived from the existing `sizes` value. When a usage is measured, its `sizes` comes from the layout
 the browser resolved, not from a guess.
 
+## GIFs and video
+
+`scan` also measures animated media: animated GIFs in an `<img>` or a CSS background, animated WebP and APNG, and
+self-hosted `<video>` elements with a plain file source. Static GIFs get the normal image hints.
+
+- **Out of scope, not reported:** adaptive streams (HLS, DASH, Mux, Cloudflare Stream) and third-party iframes (YouTube,
+  Vimeo). A video hosted on another site follows the third-party rules (`--block-third-party`, `--allow-host`).
+- **ffmpeg** is used from `PATH`; ImgTune does not bundle it. Without it, `scan` still reports each animated image's and
+  video's bytes and the width it needs, and prints one note: `install ffmpeg for verified video and GIF hints`. The encodes,
+  and so the fix hints with a size, need it.
+- **Encodes run on the CPU by default.** `--gpu-encode` is **experimental**: it moves the sample encodes to the GPU (NVENC
+  `av1_nvenc` / `h264_nvenc`, preset p4, constant quality in VBR; `libvmaf_cuda` for the VMAF). It uses the `--gpu-device`
+  list, else GPU 0, in workers beside the CPU ones. Each GPU is proven by a tiny test encode first; a width under 144 px or
+  an NVENC failure is encoded on the CPU for that candidate. NVENC is larger at equal quality, so its bytes are reported as
+  NVENC bytes ÷ 1.4, labelled `est. (GPU-encoded, scaled to a CPU encode ÷1.4)`. In our measurements `--gpu-encode` was
+  slower than the CPU (per-process CUDA start-up); see the report before using it. `--gpu` and `--gpu-device` only pick the
+  SSIMULACRA2 GPU scorer (the first device) unless `--gpu-encode` is given. The hint's recipe is the CPU one (`libsvtav1` / `libx264`), and an NVENC
+  quality is marked `approx.` (CRF = cq).
+- **Hints.** A large animated GIF gets `<video autoplay muted loop playsinline>` with AV1 first and an H.264 fallback, and
+  the animated-image alternative with its size. A small `<img>` GIF or a CSS background gets an animated AVIF or WebP. A
+  `<video>` hint names each lever: the width per breakpoint (`<source media>`), the CRF, the codec, the audio track of a
+  muted video, and `preload`. A poster is audited as an image. Duration and frame rate are informational only.
+- **Bytes: per view and per play.** Per view is what the first view fetches. An autoplay video counts its full file,
+  `preload="auto"` counts the bytes the scan saw (browser-dependent), and `preload="metadata"` or `"none"` counts 0. Per
+  play is the full file. Both are shown for every video, so a large click-to-play file is not missed. Animated images stay
+  in the image totals; `<video>` has its own Video section, and posters count as images.
+- **Estimates come from 2 s samples.** One sample for a video of up to 6 s, three for a longer one. The full-file bytes
+  are extrapolated from the samples and labelled as an estimate; nothing is encoded in full.
+- **Quality bars.** VMAF must reach `--video-bar` (default 93) against the served file at its display size. A still-frame
+  guard (SSIMULACRA2 on the stillest frames) catches blurred text in screen recordings and must reach `--video-still-bar`
+  (default 65), lowered to at most 10 points below the best the codec reaches on that content, and never below 20. The
+  relative bar catches the loss the encode adds, not what the format can never reproduce, such as GIF dither.
+- **Budget and widths.** Encodes run on the heaviest animated assets first, at most `--media-budget` per run (default 20)
+  and within `--media-time` seconds (default 600). Assets over the budget keep their cheap hints and are marked "over
+  --media-budget". A video is served at most `--max-video-widths` widths (default 2): each viewport gets the smallest
+  kept width that covers its display width times its device pixel ratio. `audit` reports the bytes at one, two and three
+  widths instead, and the agent chooses. `--no-quality` and `--survey` make no encodes.
+- **Check an agent's output** with `imgtune image <candidate> --reference <original>`: the same VMAF and still-frame bar,
+  exit 0 on pass and 1 on fail (see the table below).
+
 ## Commands
 
 | command | what it does |
@@ -155,6 +195,7 @@ the browser resolved, not from a guess.
 | `imgtune summary <run dir \| scan.json ...>` | the one-screen summary of a run directory (`run.json`) or of scan files |
 | `imgtune scan --recheck <scan.json> [--ids a,b,c]` | rescans only the named images at the viewports where they rendered; prints before and after; exits 1 on a failed check |
 | `imgtune image <file\|url\|glob>` | measures image files without a page: bytes now, the lowest quality per format that meets the bar, and at a `--width` the bytes at each needed width; `--min-score` sets the bar (default 90), `--write <dir>` writes optimised copies |
+| `imgtune image <animated.gif\|.webp\|.png\|video> --reference <original>` | checks a re-encoded video or animated file against the original: `VMAF … still p10 …: pass\|fail` with exit 0 or 1; `--video-bar` (default 93) and `--video-still-bar` (default 65) set the bars; without `--reference` an animated file gets its candidates (needs ffmpeg) |
 | `imgtune compare <before.json> <after.json>` | compares two scans of one page image by image: the bytes saved and the sharpness bytes added, as two numbers; drift (a changed layout, server variance, a view not loaded) is excluded and its totals printed; `--format json`, `--limit` |
 | `imgtune report` | a Markdown run report from the agent's ledger (`.imgtune/ledger.jsonl`); `--compare <file>` adds the bytes from `imgtune compare --format json`; `--out <file>` writes it |
 

package/dist/animated.js

@@ -0,0 +1,176 @@
+// Animation detection by byte parsing: GIF, animated WebP and APNG. It needs no decoder and no sharp, so a scan can
+// tell an animated file from a still one from the bytes it already downloaded. Only the container structure is read
+// (block headers, chunk lengths and the timing fields); pixels are never decoded.
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+/**
+ * Returns the animation in a file, or undefined when the file is not animated (one frame, another format, or a
+ * format this does not read). A truncated or corrupt file never throws: it reports what was readable before the
+ * damage, or undefined. Used by the scan to decide whether an image is a GIF or animated WebP/APNG that a video
+ * encode could replace.
+ */
+export function animationOf(buffer) {
+    try {
+        const info = detect(buffer);
+        return info && info.frames > 1 ? info : undefined;
+    }
+    catch {
+        // Every read below is bounds-checked, so this is a last guard for a malformed buffer, not a normal path.
+        return undefined;
+    }
+}
+function detect(b) {
+    const head6 = b.toString("latin1", 0, 6);
+    if (head6 === "GIF87a" || head6 === "GIF89a")
+        return parseGif(b);
+    if (b.length >= 12 && b.toString("latin1", 0, 4) === "RIFF" && b.toString("latin1", 8, 12) === "WEBP") {
+        return parseWebp(b);
+    }
+    if (b.length >= 8 && b.subarray(0, 8).equals(PNG_SIGNATURE))
+        return parseApng(b);
+    return undefined;
+}
+/** Colour-table size in bytes for a packed-flags byte whose table flag is set (3 bytes per entry, 2^(n+1) entries). */
+function colourTableBytes(packed) {
+    return 3 * 2 ** ((packed & 0x07) + 1);
+}
+/**
+ * Skips a run of GIF data sub-blocks (a size byte, then that many bytes, ending with a zero-size block) starting at
+ * p, and returns the offset just after the terminator. A run that runs past the end returns an offset past the end,
+ * which the caller's loop treats as the end of the file.
+ */
+function skipSubBlocks(b, p) {
+    while (p < b.length) {
+        const size = b[p];
+        if (size === 0)
+            return p + 1;
+        p += size + 1;
+    }
+    return p;
+}
+/**
+ * Walks GIF blocks. Frames are counted as image descriptors (0x2C); each frame's delay comes from the Graphic
+ * Control Extension (0x21 0xF9) just before it, in hundredths of a second. The loop count comes from the NETSCAPE2.0
+ * application extension.
+ */
+function parseGif(b) {
+    if (b.length < 13)
+        return undefined;
+    let pos = 13;
+    if (b[10] & 0x80)
+        pos += colourTableBytes(b[10]);
+    let frames = 0;
+    let durationMs = 0;
+    let pendingDelayCs = 0;
+    let loop;
+    while (pos < b.length) {
+        const introducer = b[pos];
+        if (introducer === 0x3b)
+            break; // trailer: end of the GIF
+        if (introducer === 0x21) {
+            // Extension: label, then sub-blocks. Application extensions start with an 11-byte identifier sub-block.
+            if (pos + 2 > b.length)
+                break;
+            const label = b[pos + 1];
+            if (label === 0xf9 && pos + 6 <= b.length) {
+                pendingDelayCs = b.readUInt16LE(pos + 4);
+            }
+            else if (label === 0xff && pos + 3 + 11 <= b.length) {
+                const identifier = b.toString("latin1", pos + 3, pos + 14);
+                if (identifier === "NETSCAPE2.0" || identifier === "ANIMEXTS1.0") {
+                    const loopBlock = pos + 14;
+                    if (loopBlock + 5 <= b.length && b[loopBlock] === 3 && b[loopBlock + 1] === 1) {
+                        loop = b.readUInt16LE(loopBlock + 2);
+                    }
+                }
+            }
+            pos = skipSubBlocks(b, pos + 2);
+        }
+        else if (introducer === 0x2c) {
+            // Image descriptor: separator, 4 x u16 position and size, packed flags, then LZW code size and sub-blocks.
+            if (pos + 10 > b.length)
+                break;
+            const packed = b[pos + 9];
+            let p = pos + 10;
+            if (packed & 0x80)
+                p += colourTableBytes(packed);
+            p += 1; // LZW minimum code size
+            frames += 1;
+            // A delay of 0 or 1 cs is shown as 10 cs (100 ms), as browsers show it, so the length is not understated.
+            durationMs += (pendingDelayCs <= 1 ? 10 : pendingDelayCs) * 10;
+            pendingDelayCs = 0;
+            pos = skipSubBlocks(b, p);
+        }
+        else {
+            break; // not a block introducer: the file is corrupt from here on
+        }
+    }
+    return { format: "gif", frames, durationMs, loop: loop ?? 1 };
+}
+/**
+ * Walks RIFF chunks of a WebP. Animation needs the VP8X animation flag (bit 1 of its first byte). ANIM holds the loop
+ * count (u16 at data offset 4). Each ANMF chunk is one frame, and its 24-bit duration is at data offset 12.
+ */
+function parseWebp(b) {
+    let pos = 12;
+    let animated = false;
+    let loop = 0;
+    let frames = 0;
+    let durationMs = 0;
+    while (pos + 8 <= b.length) {
+        const type = b.toString("latin1", pos, pos + 4);
+        const size = b.readUInt32LE(pos + 4);
+        const data = pos + 8;
+        if (type === "VP8X" && data + 1 <= b.length) {
+            animated = (b[data] & 0x02) !== 0;
+        }
+        else if (type === "ANIM" && data + 6 <= b.length) {
+            loop = b.readUInt16LE(data + 4);
+        }
+        else if (type === "ANMF" && data + 15 <= b.length) {
+            frames += 1;
+            durationMs += b.readUIntLE(data + 12, 3);
+        }
+        pos = data + size + (size & 1); // chunks are padded to an even length
+    }
+    if (!animated)
+        return undefined;
+    return { format: "webp", frames, durationMs, loop };
+}
+/**
+ * Walks PNG chunks of an APNG. The acTL chunk must come before the first IDAT; it holds num_frames and num_plays (0
+ * means loop forever). Each fcTL chunk is one frame, and its delay is delay_num / delay_den seconds (a zero
+ * delay_den means 100).
+ */
+function parseApng(b) {
+    let pos = 8;
+    let frames;
+    let loop = 0;
+    let durationMs = 0;
+    let sawIdat = false;
+    while (pos + 8 <= b.length) {
+        const length = b.readUInt32BE(pos);
+        const type = b.toString("latin1", pos + 4, pos + 8);
+        const data = pos + 8;
+        if (data + length > b.length)
+            break; // a chunk cut short by truncation
+        if (type === "IDAT") {
+            sawIdat = true;
+        }
+        else if (type === "acTL" && !sawIdat && length >= 8) {
+            frames = b.readUInt32BE(data);
+            loop = b.readUInt32BE(data + 4);
+        }
+        else if (type === "fcTL" && length >= 26) {
+            const delayNum = b.readUInt16BE(data + 20);
+            const delayDen = b.readUInt16BE(data + 22) || 100;
+            durationMs += (delayNum * 1000) / delayDen;
+        }
+        else if (type === "IEND") {
+            break;
+        }
+        pos = data + length + 4; // skip the CRC
+    }
+    if (frames === undefined)
+        return undefined;
+    return { format: "apng", frames, durationMs: Math.round(durationMs), loop };
+}

package/dist/backgrounds.js

@@ -6,7 +6,8 @@
 // Pure parsing and sizing here; the measurement (fetches, decodes, resize estimates) is in remote.ts, and the records are
 // built in buildBackgroundRecords below.
 import { sha1 } from "./atomic.js";
-import { rungOfPage, searchHintsOf } from "./images.js";
+import { losslessServed, rungOfPage, searchHintsOf } from "./images.js";
+import { animatedTarget } from "./media-model.js";
 import { loaderName, sanitizeText, urlPattern } from "./locate.js";
 /** The most background elements read per viewport: a page with more keeps the first of them in document order. */
 export const MAX_BACKGROUND_ELEMENTS = 1000;
@@ -290,7 +291,9 @@ export function buildBackgroundRecords(input) {
         }
         const saved = members.reduce((sum, m) => sum + m.est, 0) / viewportCount;
         const served = member.format;
-        const best = served === "jpeg" || served === "png" ? (saved > 0 ? "avif" : served) : served;
+        const animatedMember = members.find((m) => m.animated !== undefined);
+        const lossless = losslessServed(served, animatedMember !== undefined);
+        const best = lossless ? (saved > 0 ? "avif" : served) : served;
         const locator = locatorOfBackground(pageUrl, url, member.bg, source);
         const notes = [
             `css background: layer ${member.layer + 1}, background-size "${sanitizeText(member.size, 60)}", drawn ${Math.round(member.displayedCss)} CSS px at the reference viewport`,
@@ -328,6 +331,14 @@ export function buildBackgroundRecords(input) {
         };
         if (best !== undefined)
             record.fix.format = best;
+        if (animatedMember?.animated !== undefined) {
+            record.fix.animated = {
+                info: animatedMember.animated,
+                context: "css-background",
+                target: animatedTarget("css-background", undefined),
+                perViewBytes: members.reduce((sum, m) => sum + m.bytes, 0) / viewportCount,
+            };
+        }
         records.push(record);
     }
     return records.filter((r) => r.perViewport.some((p) => p.loaded || p.skipped !== undefined));

package/dist/check-report.js

@@ -1,12 +1,12 @@
 // The Markdown report of `imgtune check`: a pure builder over the survey results, the deep results, the route grouping and
 // the deep selection. No browser, no files. The audit mode extends it with source-aware sections; the sections below keep
 // their order so the two stay comparable. Page-derived text goes through mdText and mdCode (see text.ts).
-import { hintsOf } from "./hints.js";
+import { hintsOf, videoRowOf, videoSavingOf, videoTotalsLine } from "./hints.js";
 import { lcpLinesOf } from "./lcp.js";
 import { planQualityCap, qualitiesLine } from "./qualities-cap.js";
 import { hasFix } from "./images.js";
 import { APPROX_MARK, siteNumbers } from "./remote.js";
-import { errorLine, mdCode, mdText } from "./text.js";
+import { errorLine, mdCode, mdText, safeText } from "./text.js";
 /** How many fixes, heavy pages, sharpness images and survey route types the report lists in full. */
 export const REPORT_FIXES = 15;
 export const REPORT_SHARPNESS = 15;
@@ -153,6 +153,10 @@ export function buildCheckReport(input) {
     const notMeasured = (pages) => pages.length - measured(pages).length - count(pages, "broken") - count(pages, "failed");
     out(`survey ${input.urls.surveyed} page(s): ${survey.length} ok, ${count(input.survey, "broken")} broken, ${count(input.survey, "failed")} failed, ${notMeasured(input.survey)} not measured · deep ${input.deep.length} page(s)${retried > 0 ? ` (${retried} retried)` : ""}: ${deepOk.length} ok, ${count(input.deep, "failed")} failed, ${notMeasured(input.deep)} not measured`);
     out(`time: survey ${input.timings.survey.toFixed(1)} s, deep ${input.timings.deep.toFixed(1)} s, total ${(input.timings.survey + input.timings.deep).toFixed(1)} s`, "");
+    // The media phase's note is printed once, at the top (the same note is on each page that has media).
+    const media = [...input.survey, ...input.deep].find((p) => p.mediaNote !== undefined)?.mediaNote;
+    if (media !== undefined)
+        out(mdText(media), "");
     if (input.stop !== undefined) {
         out("## Stopped before the deep phase", "", `${mdText(input.stop.reason)}`, `Fix: ${mdText(input.stop.fix)}`, "");
     }
@@ -192,6 +196,17 @@ export function buildCheckReport(input) {
         out(`Merged across the deep pages: one file:line when located, else one image pattern with the same proposed sizes. Ranked by the total saving over the pages. Top ${Math.min(REPORT_FIXES, fixes.length)} of ${fixes.length}.`, "");
         fixes.slice(0, REPORT_FIXES).forEach((fix, i) => out(...fixLines(fix, i + 1), ""));
     }
+    // 3b. Video: the self-hosted <video> files of the deep pages, per view and per play, largest saveable first.
+    const videos = deepOk.flatMap((p) => (p.videos ?? []).map((video) => ({ page: p.url, video })));
+    if (videos.length > 0) {
+        out("## Video", "");
+        out(`${videoTotalsLine(videos.map((v) => v.video))} (${videos.length} video(s) on ${deepOk.filter((p) => (p.videos ?? []).length > 0).length} deep page(s))`, "");
+        const ranked = [...videos].sort((a, b) => videoSavingOf(b.video).view - videoSavingOf(a.video).view || a.page.localeCompare(b.page));
+        for (const row of ranked.slice(0, REPORT_FIXES)) {
+            out(`- ${mdCode(videoRowOf(row.video, (text) => JSON.stringify(safeText(text))))} on ${mdCode(pathOf(row.page))}`);
+        }
+        out("");
+    }
     // 4. Heavy but not wasteful.
     out("## Heavy but not wasteful", "");
     const heavyCut = percentile(deepTotals.map((t) => t.kb), 0.75);
@@ -280,6 +295,8 @@ export function buildCheckReport(input) {
         ? `- Route types group URLs by template (locale and device variant stripped), as check does; the route file column names the file(s) each type renders from. Only the heaviest page of each type is deep-scanned; ${input.selection.leftOut.length} type(s) were not (see the table).`
         : `- Route types group URLs by template (locale and device variant stripped). Only the heaviest page of each type is deep-scanned; ${input.selection.leftOut.length} type(s) were not (see the table).`, input.options.qualities !== undefined
         ? `- Quality targets are snapped up to the allowed qualities ${input.options.qualities.join(", ")}; a snapped target's quality saving is void and counts as 0.${input.qualitiesNote !== undefined ? ` (${mdText(input.qualitiesNote)})` : ""}`
-        : "- Quality targets are not snapped (no --qualities given): a target the framework cannot serve is not the saving it looks like.", `- Third-party requests: ${input.options.thirdParty}${input.options.allowHosts ? ` (hosts kept: ${input.options.allowHosts.map(mdText).join(", ")})` : ""}. Blocking can drop images a page loads through its own API on another host.`, `- Pages with images still loading at settle show the images that loaded; the rest are not measured.`, input.options.gpu !== undefined ? `- Quality was scored on the GPU ${input.options.gpu} (with the CPU fallback noted in the page JSON).` : "- Quality was scored on the CPU.", "");
+        : "- Quality targets are not snapped (no --qualities given): a target the framework cannot serve is not the saving it looks like.", `- Third-party requests: ${input.options.thirdParty}${input.options.allowHosts ? ` (hosts kept: ${input.options.allowHosts.map(mdText).join(", ")})` : ""}. Blocking can drop images a page loads through its own API on another host.`, `- Pages with images still loading at settle show the images that loaded; the rest are not measured.`, ...(videos.length > 0
+        ? [`- Video bytes: per view as the page loads them (autoplay: the whole file). The saveable bytes come from 2 s sample encodes: est.`]
+        : []), input.options.gpu !== undefined ? `- Quality was scored on the GPU ${input.options.gpu} (with the CPU fallback noted in the page JSON).` : "- Quality was scored on the CPU.", "");
     return `${lines.join("\n")}\n`;
 }

package/dist/check.js

@@ -7,7 +7,7 @@ import { mkdir, readFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { DEFAULT_VIEWPORTS } from "./config.js";
 import { writeFileAtomic } from "./atomic.js";
-import { parseGpuDevice } from "./gpu.js";
+import { gpuSettingOf, gpuSettingOne } from "./gpu.js";
 import { parseQualities } from "./hints.js";
 import { BROKEN_EXIT, surveyStop } from "./broken.js";
 import { DEFAULT_THIRD_PARTY, parseAllowHosts, thirdPartyFromFlags } from "./third-party.js";
@@ -36,6 +36,8 @@ export function parseCheckFlags(argv) {
         const arg = argv[i];
         if (arg === "--no-cache")
             args.noCache = true;
+        else if (arg === "--gpu-encode")
+            args.gpuEncode = true;
         else if (arg === "--ignore-robots")
             args.ignoreRobots = true;
         else if (arg === "--block-third-party")
@@ -44,9 +46,9 @@ export function parseCheckFlags(argv) {
         else if (arg === "--allow-third-party")
             continue;
         else if (arg === "--gpu")
-            args.gpu ??= { device: 0 };
+            args.gpu ??= gpuSettingOne(0);
         else if (arg === "--gpu-device") {
-            args.gpu = { device: parseGpuDevice(valueOf(argv, i, arg)) };
+            args.gpu = gpuSettingOf(valueOf(argv, i, arg));
             i++;
         }
         else if (arg === "--urls-from" ||
@@ -203,6 +205,7 @@ export async function scanCheckPages(input) {
             shellWord(surveyDir),
             ...(settings.thirdParty.block ? ["--block-third-party"] : []),
             ...(settings.noCache ? ["--no-cache"] : []),
+            ...(settings.gpuEncode ? ["--gpu-encode"] : []),
         ].join(" "),
     });
     log(`survey: ${urls.length} URL(s), ${routes.types.length} route type(s)`);
@@ -236,10 +239,11 @@ export async function scanCheckPages(input) {
             if (page.status === "ok")
                 expected.set(page.url, page.counts.images);
         const flags = [
-            ...(settings.gpu !== undefined ? ["--gpu-device", String(settings.gpu.device)] : []),
+            ...(settings.gpu !== undefined ? ["--gpu-device", settings.gpu.devices.join(",")] : []),
             ...(settings.thirdParty.block ? ["--block-third-party"] : []),
             ...(settings.thirdParty.allowHosts.length > 0 ? ["--allow-host", shellWord(settings.thirdParty.allowHosts.join(","))] : []),
             ...(settings.noCache ? ["--no-cache"] : []),
+            ...(settings.gpuEncode ? ["--gpu-encode"] : []),
             ...(settings.ignoreRobots ? ["--ignore-robots"] : []),
             ...(settings.pageConcurrency !== undefined ? ["--page-concurrency", String(settings.pageConcurrency)] : []),
             ...(settings.idleTimeoutMs !== undefined ? ["--idle-timeout", String(settings.idleTimeoutMs)] : []),

package/dist/cli.js

@@ -21,6 +21,10 @@ const progress = (message) => {
 const OPTION_HELP = {
     out: ["--out <dir>", "directory for the JSON files (default: .imgtune/scan)"],
     noCache: ["--no-cache", "do not read or write the result cache in .imgtune/cache (the numbers are computed again)"],
+    gpuEncode: [
+        "--gpu-encode",
+        "EXPERIMENTAL: encode the videos and animated images on the GPU (NVENC, CUDA VMAF); off by default (CPU encodes). Bytes are scaled to a CPU encode (÷1.4)",
+    ],
     root: [
         "--root <dir>",
         "folder project source files are read from (default: the nearest folder above the cwd that holds the file, else the nearest with a package.json or .git)",
@@ -58,6 +62,14 @@ const OPTION_HELP = {
     resume: ["--resume", "reuse the complete pages already in --out that were scanned with the same options"],
     maxPages: ["--max-pages <N>", "stop after N pages (scanned or resumed); run again with --resume to continue"],
     maxImages: ["--max-images <N>", "stop after the page that brings the images counted to N (checked between pages)"],
+    mediaBudget: [
+        "--media-budget <N>",
+        "sample-encode at most N animated images and videos per run, heaviest first, 0 to 1000 (default 20); the rest keep their cheap hints",
+    ],
+    mediaTime: ["--media-time <s>", "time limit of the media encodes, in seconds, 1 to 3600 (default 600)"],
+    videoBar: ["--video-bar <n>", "minimum VMAF of a video or animated encode, 0 to 100 (default 93)"],
+    videoStillBar: ["--video-still-bar <n>", "minimum SSIMULACRA2 of the still-frame guard, 0 to 100 (default 65)"],
+    maxVideoWidths: ["--max-video-widths <n>", "the most widths each video is served at, 1 to 3 (default 2)"],
     maxQualities: [
         "--max-qualities <N>",
         "the most values next.config's images.qualities may list, 1 to 4 (default 2): next/image qualities are clustered, each mapped up",
@@ -95,7 +107,10 @@ const OPTION_HELP = {
         "--gpu",
         "score with the GPU scorer (imgtune-ssimu2-gpu, see the docs); opt-in. Falls back to the CPU with a warning",
     ],
-    gpuDevice: ["--gpu-device <n>", "the GPU to score on, by CUDA index (implies --gpu; default 0; see the GPU notes)"],
+    gpuDevice: [
+        "--gpu-device <n[,n]>",
+        "the GPU to score on, by CUDA index (implies --gpu; default 0; see the GPU notes). A comma list (0,1) gives each GPU its own encode workers with --gpu-encode; the first scores",
+    ],
     locateOnly: [
         "--locate-only",
         "read the source of the flagged images from a dev page (React owner data) or a built page with source maps (prod-sourcemap); not a measurement (needs --from)",
@@ -134,6 +149,7 @@ const SCAN_HELP = commandHelp("imgtune scan <url> [<url> ...] [options]", [
     "out",
     "root",
     "noCache",
+    "gpuEncode",
     "aggressive",
     "viewports",
     "survey",
@@ -146,6 +162,11 @@ const SCAN_HELP = commandHelp("imgtune scan <url> [<url> ...] [options]", [
     "resume",
     "maxPages",
     "maxImages",
+    "mediaBudget",
+    "mediaTime",
+    "videoBar",
+    "videoStillBar",
+    "maxVideoWidths",
     "maxQualities",
     "pageConcurrency",
     "idleTimeout",
@@ -187,6 +208,7 @@ Options:
   --out <dir>                     the check directory (default ${DEFAULT_CHECK_DIR}/<timestamp>)
   --qualities <list>              the framework's allowed qualities, e.g. 75,85,100: targets are snapped up to them
   --gpu, --gpu-device <n>         score the deep pages with the GPU scorer (see the GPU notes; not the survey)
+  --gpu-encode                    EXPERIMENTAL: encode the deep pages' videos and animated images on the GPU (see scan --help)
   --page-concurrency <N>          pages at once in the deep phase (default 1)
   --idle-timeout <ms>             cap on the network-idle wait in the deep phase (default 10000)
   --block-third-party             abort the requests to other sites (off by default; can drop images a page loads from its API)
@@ -222,6 +244,7 @@ Options:
   --qualities <list>              the allowed qualities (default: images.qualities of next.config, else Next's [75])
   --out <dir>                     the audit directory (default ${DEFAULT_AUDIT_DIR}/<timestamp>)
   --gpu, --gpu-device <n>         score the deep pages with the GPU scorer (see the GPU notes; not the survey)
+  --gpu-encode                    EXPERIMENTAL: encode the deep pages' videos and animated images on the GPU (see scan --help)
   --page-concurrency <N>          pages at once in the deep phase (default 1)
   --idle-timeout <ms>             cap on the network-idle wait in the deep phase (default 10000)
   --block-third-party             abort the requests to other sites (off by default; can drop images a page loads from its API)
@@ -252,6 +275,7 @@ Options:
   --dev <origin>                  locate the deep pages at the same paths on this dev server (a running dev server)
   --qualities <list>              the framework's allowed qualities, e.g. 75,85,100 (passed to hints)
   --gpu, --gpu-device <n>         score the deep pages with the GPU scorer (see the GPU notes; not the survey)
+  --gpu-encode                    EXPERIMENTAL: encode the deep pages' videos and animated images on the GPU (see scan --help)
   --page-concurrency <N>          pages at once in the survey (default 4) and in the deep phase (default 1)
   --idle-timeout <ms>             cap on the network-idle wait (default 3000 in the survey, 10000 in the deep phase)
   --no-cache                      do not read or write the result cache
@@ -298,17 +322,29 @@ against the file itself: 90 (visually lossless) unless --min-score sets another.
 --write names a folder for optimised copies (existing names are never overwritten).
 Evidence is "file-mode". Globs: ** walks folders (node_modules and dot folders are skipped).
 
+Media: an animated GIF, animated WebP or APNG gets the candidates of animated AVIF, animated WebP and AV1 MP4 at --width
+(the file's own width by default), each the lowest-bytes quality that meets the video bars. A video (MP4, MOV, WebM) is
+described; with --reference <original> a candidate is checked against the original: VMAF and the still-frame guard, one
+verdict line "VMAF <v> (bar <b>) still p10 <s> (bar <sb>): pass|fail", exit 0 on pass and 1 on fail. Media is local files
+only. The encodes need ffmpeg on PATH; without it the sizes are still measured.
+
 Options:
-  --width <css px>      the CSS width the image is shown at (the width is then the user's, not the file's)
+  --width <css px>      the CSS width the image is shown at (the width is then the user's, not the file's); for media, the width
+                        compared or searched at (the candidate's own width with --reference)
   --dpr <list>          device pixel ratios for --width (default 1,2)
   --formats <list>      avif, webp, jpeg (default all three)
   --min-score <n>       the SSIMULACRA2 bar, above 0 and at most 100 (default 90)
   --write <dir>         write optimised copies (best format, at the largest needed width) into this folder
-  --format <text|json>  text (default) or JSON
+  --reference <file>    compare one media candidate with this original (local file): the verdict line and the exit code
+  --video-bar <n>       the minimum VMAF of a media encode or check, 0 to 100 (default 93)
+  --video-still-bar <n> the still-frame guard's bar, 0 to 100 (default 65), lowered for a source whose own best encode scores low
+  --format <text|json>  text (default) or JSON (--json is the same)
   --gpu                 score with the GPU scorer (opt-in; falls back to the CPU with a warning)
-  --gpu-device <n>      the GPU to score on, by CUDA index (implies --gpu; default 0). CUDA numbers the GPUs fastest first
+  --gpu-device <n>      the GPU to score on, by CUDA index (implies --gpu; default 0). A comma list is accepted: the first GPU
+                        scores. CUDA numbers the GPUs fastest first
                         unless CUDA_DEVICE_ORDER=PCI_BUS_ID; with CUDA_VISIBLE_DEVICES set, n indexes the devices it lists.
                         The scorer prints the name of the GPU it opened: check it.
+  --gpu-encode          EXPERIMENTAL: encode the videos and animated images on the GPU (NVENC, CUDA VMAF), off by default
   --no-cache            do not read or write the result cache in .imgtune/cache
   -h, --help            show this help
 `;
@@ -355,6 +391,28 @@ Options:
   --version           print the version
   -h, --help          show this help
 `;
+/** Shell exit codes of a run stopped by a signal: 128 + the signal number. */
+const SIGNAL_EXIT = { SIGINT: 130, SIGTERM: 143 };
+/** The most a first signal waits for the run to clean up (media scratch, ffmpeg children) before the process exits. */
+const CLEANUP_MS = 2000;
+/** Aborted on the first SIGINT or SIGTERM: the media phase and the image command stop, ffmpeg children are killed and their
+ * scratch folders removed (the abort is seen in their `finally` blocks). The process then exits within CLEANUP_MS with the
+ * signal's exit code, so a Ctrl-C or a supervisor's SIGTERM always ends the run. A second signal exits at once.
+ */
+const interrupt = new AbortController();
+let interrupts = 0;
+/** The first signal received, which sets the exit code of an interrupted run. */
+let received;
+for (const signal of ["SIGINT", "SIGTERM"]) {
+    process.on(signal, () => {
+        interrupts++;
+        received ??= signal;
+        if (interrupts > 1)
+            process.exit(SIGNAL_EXIT[signal]);
+        interrupt.abort();
+        setTimeout(() => process.exit(SIGNAL_EXIT[signal]), CLEANUP_MS);
+    });
+}
 async function main() {
     const argv = process.argv.slice(2);
     if (argv.includes("--version")) {
@@ -415,9 +473,9 @@ async function main() {
         return;
     }
     if (argv[0] === "image") {
-        const outcome = await imageCommand(argv.slice(1), process.cwd());
+        const outcome = await imageCommand(argv.slice(1), process.cwd(), undefined, undefined, interrupt.signal);
         process.stdout.write(outcome.output);
-        process.exitCode = outcome.exitCode;
+        process.exitCode = received !== undefined ? SIGNAL_EXIT[received] : outcome.exitCode;
         return;
     }
     if (argv[0] === "hints") {
@@ -455,9 +513,9 @@ async function main() {
         process.exitCode = 2;
         return;
     }
-    const outcome = await scanCommand(argv.slice(1), process.cwd(), progress);
+    const outcome = await scanCommand(argv.slice(1), process.cwd(), progress, interrupt.signal);
     process.stdout.write(outcome.output);
-    process.exitCode = outcome.exitCode;
+    process.exitCode = received !== undefined ? SIGNAL_EXIT[received] : outcome.exitCode;
 }
 main().catch((err) => {
     if (err instanceof ChromiumMissingError) {