imgtune 0.1.0 → 0.2.0

package/dist/hints.js

@@ -8,6 +8,7 @@ import { cleanLocate } from "./locate-join.js";
 import { DEFAULT_VIEWPORTS } from "./config.js";
 import { fitSizes, maxPerWidth } from "./group-sizes.js";
 import { MAX_MAX_QUALITIES, MIN_MAX_QUALITIES, planQualityCap, qualitiesLine } from "./qualities-cap.js";
+import { reasonText } from "./media-model.js";
 export const DEFAULT_HINT_LIMIT = 10;
 const usage = "usage: imgtune hints <scan.json> [<scan.json> ...] [--page <text>] [--component <name>] [--limit N] [--offset N] [--min-kb N] [--format text|json] [--flat] [--qualities 75,85,100] [--max-qualities N]";
 function nonNegativeInteger(name, text) {
@@ -98,7 +99,8 @@ export function parseHintsArgs(argv) {
  * planQualityCap); it applies only when no --qualities list was given (that list is the framework's own).
  */
 export function hintsOf(result, qualities, plan) {
-    return (result.images ?? []).filter(hasFix).map((record) => {
+    // An animated image is a hint even without a sizes or byte saving: its saving is an encode (see animatedLines).
+    return (result.images ?? []).filter((record) => hasFix(record) || record.fix.animated !== undefined).map((record) => {
         const served = record.current.format;
         const rawTarget = served !== undefined ? record.fix.quality?.perFormat[served] : undefined;
         // With the framework's allowed qualities, the target goes up to one of them. The quality saving was estimated at the
@@ -208,6 +210,16 @@ export function hintsOf(result, qualities, plan) {
         }
         if (record.fix.format !== undefined || served !== undefined)
             hint.format = { current: served, best: record.fix.format };
+        if (record.fix.animated !== undefined) {
+            hint.animated = record.fix.animated;
+            if (record.current.src !== undefined)
+                hint.src = record.current.src;
+            // The animated saving is the encode's alone (est.): the target is encoded at the needed width, so perViewBytes less the
+            // target's bytes already holds the width change. Adding the record's sizes part would count it twice. A real sizes
+            // proposal is still printed as information (renderHint), but it adds nothing to the saving.
+            const encoded = animatedSavingOf(record.fix.animated);
+            hint.bytes = { saved: encoded, addedForSharpness: record.fix.bytes.addedForSharpness, quality: encoded };
+        }
         return hint;
     });
 }
@@ -280,8 +292,9 @@ export function renderHint(hint, rank) {
         lines.push(`   find: ${hint.find.component} in ${hint.find.glob}`);
     if (hint.width !== undefined)
         lines.push(`   width ${hint.width}px (device pixels needed)`);
-    else
+    else if (hint.animated === undefined || hint.sizes.proposed !== undefined) {
         lines.push(`   sizes ${safeText(hint.sizes.current ?? "none")} -> ${safeText(hint.sizes.proposed ?? "-")} (${hint.sizes.basis ?? "-"})`);
+    }
     if (hint.sizesAuto !== undefined)
         lines.push(`   alternative: sizes="${safeText(hint.sizesAuto)}" (Chrome, Edge, Firefox 150+; Safari falls back to ${safeText(hint.sizes.proposed ?? "-")})`);
     if (hint.via === "prod-sourcemap") {
@@ -292,6 +305,8 @@ export function renderHint(hint, rank) {
     }
     else if (hint.file === undefined && hint.find === undefined && hint.kind !== "owner")
         lines.push("   owner unknown");
+    if (hint.animated !== undefined)
+        lines.push(...animatedLines(hint.animated, hint.src, hint.alt));
     const parts = [];
     if (hint.quality)
         parts.push(`quality ${hint.quality.current}${qualityTarget(hint.quality)} (max of ${hint.quality.samples}, ${safeText(hint.quality.group)})`);
@@ -301,7 +316,9 @@ export function renderHint(hint, rank) {
         lines.push(`   ${parts.join("  ")}`);
     if (hint.qualityNote !== undefined)
         lines.push(`   ${safeText(hint.qualityNote)}`);
-    lines.push(`   ${savesText(hint)}, +${kb(hint.bytes.addedForSharpness)} sharpness (separate)  rung ${hint.rung}`);
+    // An animated hint's saving is an estimate from the sample encodes, and its rung is that estimate, not the image measurement.
+    const animated = hint.animated !== undefined;
+    lines.push(`   ${savesText(hint)}${animated ? " est." : ""}, +${kb(hint.bytes.addedForSharpness)} sharpness (separate)  rung ${animated ? "estimate" : hint.rung}`);
     return lines;
 }
 /** The group a hint belongs to: its file:line, else its nearest component, else its selector. */
@@ -493,6 +510,11 @@ export function renderGroup(group, rank) {
     const ids = group.hints.map((h) => h.id);
     const shown = ids.slice(0, 8).join(" ");
     lines.push(`   ids ${shown}${ids.length > 8 ? ` (+${ids.length - 8} more; --flat lists each image)` : ""}`);
+    // An animated image's hint is its own (its target and bytes are not a sizes or quality change), so it is printed here.
+    for (const hint of group.hints) {
+        if (hint.animated !== undefined)
+            lines.push(`   ${safeText(hint.id)}`, ...animatedLines(hint.animated, hint.src));
+    }
     return lines;
 }
 /** The text of a grouped selection: a count line, then each group. */
@@ -511,6 +533,386 @@ export function renderHints(hints, total, offset, page) {
     const body = hints.flatMap((hint, i) => renderHint(hint, offset + i + 1));
     return `${head}${body.join("\n")}\n`;
 }
+// ---------------------------------------------------------------------------------------------------------------------
+// Animated images and `<video>` (Task 8): the text of their hints and of the Video section of a page. Every estimated byte
+// figure is marked "est."; a hint names the sample encodes once. Page-derived names and attributes are JSON strings.
+// ---------------------------------------------------------------------------------------------------------------------
+/** The note that marks a figure as an estimate from the 2-second sample encodes. A hint says it once. */
+export const SAMPLE_NOTE = "(estimate from 2 s samples)";
+/** The `type` of the two sources a video hint names: AV1 first, H.264 as the fallback. */
+const AV1_TYPE = 'video/mp4; codecs=av01.0.08M.08';
+const H264_TYPE = 'video/mp4; codecs=avc1.640028';
+/** The H.264 fallback recipe an animated GIF's video hint gives. It is not encoded by imgtune (performance first). */
+const H264_RECIPE = "libx264 -preset veryfast -crf 23 -pix_fmt yuv420p -movflags +faststart -an";
+const FORMAT_LABEL = { gif: "GIF", webp: "WebP", apng: "APNG" };
+/**
+ * The label of a candidate's bytes. An NVENC candidate's bytes are its GPU encode scaled to a CPU encode (÷1.4), so the label
+ * says so: performance before precision, but the number is never presented as a measured CPU encode.
+ */
+export function estLabel(c) {
+    return c.encoder === "nvenc" ? "est. (GPU-encoded, scaled to a CPU encode ÷1.4)" : "est.";
+}
+/**
+ * The quality mark of a candidate: an NVENC candidate's cq is read as the CPU CRF (the same number, a fixed offset of 0), so
+ * the recipe's CRF is approximate. Empty for a CPU encode.
+ */
+export function qualityApprox(c) {
+    return c.encoder === "nvenc" ? " (approx.)" : "";
+}
+/** The smallest candidate of one codec, or undefined. The first of equal bytes wins. */
+export function smallestCandidate(candidates, codec) {
+    let best;
+    for (const c of candidates ?? []) {
+        if (c.codec === codec && (best === undefined || c.bytes < best.bytes))
+            best = c;
+    }
+    return best;
+}
+/**
+ * The quality evidence of an encode: VMAF with its bar, and the still-frame guard with its bar. A bar the candidate does not
+ * carry is said so, not guessed: the run's flag is not in the scan file.
+ */
+export function evidenceOf(c) {
+    const bar = (value) => (value === undefined ? "bar not recorded" : `bar ${value}`);
+    return `VMAF ${c.vmaf.toFixed(1)} (${bar(c.vmafBar)}), still ${c.still.toFixed(1)} (${bar(c.stillBar)})`;
+}
+/** The codec as a hint names it: "av1", "h264", or the codec's own name. */
+function codecName(codec) {
+    return codec === "av1-mp4" ? "av1" : codec === "h264-mp4" ? "h264" : codec;
+}
+/** The targets of an animated image's encode (see AnimatedTargets). The main one's bytes are the saving's basis. */
+export function animatedTargetsOf(animated) {
+    const avif = smallestCandidate(animated.estimate, "animated-avif");
+    const webp = smallestCandidate(animated.estimate, "animated-webp");
+    const av1 = smallestCandidate(animated.estimate, "av1-mp4");
+    const h264 = smallestCandidate(animated.estimate, "h264-mp4");
+    const video = av1 !== undefined && (animated.target?.main === "video" || (avif === undefined && webp === undefined));
+    return { avif, webp, av1, h264, video, main: video ? av1 : (avif ?? webp) };
+}
+/** The bytes per view an animated image saves: its bytes per view less the main target's encode, floored at 0 (est.). */
+export function animatedSavingOf(animated) {
+    const main = animatedTargetsOf(animated).main;
+    return main === undefined ? 0 : Math.max(0, animated.perViewBytes - main.bytes);
+}
+/**
+ * The fallback of an image-target hint, built only from the candidates that exist: the `<picture>` with an AVIF source (for
+ * AVIF, with or without WebP), a plain `src` swap for WebP alone (WebP animates everywhere it shows an image), and for a CSS
+ * background an `image-set()` with the existing types.
+ */
+function imageFallbackOf(context, targets, src) {
+    if (context === "css-background") {
+        const types = [
+            targets.avif !== undefined ? 'url(<avif>) type("image/avif")' : undefined,
+            targets.webp !== undefined ? 'url(<webp>) type("image/webp")' : undefined,
+        ].filter((t) => t !== undefined);
+        return `fallback: image-set(${types.join(", ")})`;
+    }
+    if (targets.avif !== undefined) {
+        return `fallback: <picture><source type="image/avif" srcset="…"><img src=${JSON.stringify(src ?? "")}></picture>`;
+    }
+    return "plain src swap to the animated WebP (WebP animates in every browser that shows the image)";
+}
+/** Browser coverage of each option, as the hint states it (the caniuse data is not in the repo: these are the stated facts). */
+const COVERAGE = {
+    webp: "animated WebP: all current browsers",
+    avif: "animated AVIF: Chrome 85+, Firefox 113+, Safari 16.4+",
+    av1: "AV1 video: Chrome, Firefox, Edge; Safari only on devices with AV1 hardware decode, so keep the H.264 fallback",
+};
+/**
+ * The exact encoder settings of a candidate, as an agent runs them: the encoder, its preset and CRF (or q), and the pixel
+ * format and container options that follow. An AV1 CRF is a CRF, never a q (see the quality label in animatedLines).
+ */
+export function encoderRecipe(codec, c) {
+    const av1 = c.av1Encoder === "libaom-av1" ? `libaom-av1 -cpu-used 8 -row-mt 1 -crf ${c.quality} -b:v 0` : `libsvtav1 -preset 10 -crf ${c.quality}`;
+    switch (codec) {
+        case "av1-mp4":
+            return `${av1} -pix_fmt yuv420p -movflags +faststart`;
+        case "animated-avif":
+            return `${av1}, -f avif`;
+        case "animated-webp":
+            return `libwebp_anim -q:v ${c.quality} -loop 0`;
+        case "h264-mp4":
+            return `libx264 -preset veryfast -crf ${c.quality} -pix_fmt yuv420p -movflags +faststart -an`;
+    }
+}
+/**
+ * The line that says a target is capped at the file's own width: the device width needs more than the file has, so the
+ * target is the file's width and a wider one would add bytes, not detail. Undefined when the target is not capped.
+ */
+export function sourceCapLine(need, sourceWidth, served) {
+    if (need === undefined || sourceWidth === undefined || !(need > sourceWidth) || served !== sourceWidth)
+        return undefined;
+    return `   source is ${sourceWidth}px wide; needed ${need}px: serve ${sourceWidth}px (upscaling adds bytes, not detail)`;
+}
+/**
+ * The lines of an animated image's hint. An image target (AVIF and/or WebP, with a fallback built from the candidates that
+ * exist) when the encode offers one; the `<video>` replacement with its AV1 source and the H.264 recipe when the target is
+ * video. With no encode, the bytes per view and the reason. `src` is the served file's URL, printed as a JSON string; `alt`
+ * is the image's alt text, which the `<video>` keeps as its accessible name.
+ */
+export function animatedLines(animated, src, alt) {
+    const { info, perViewBytes } = animated;
+    const head = `animated ${FORMAT_LABEL[info.format]} ${(info.durationMs / 1000).toFixed(1)} s, ${info.frames} frames`;
+    const targets = animatedTargetsOf(animated);
+    const { avif, webp, av1, h264, main } = targets;
+    if (main === undefined) {
+        return [`   ${head}: ${kb(perViewBytes)}/view; not encoded: ${safeText(reasonText(animated.notEncoded ?? "no passing quality"))}`];
+    }
+    const saves = animatedSavingOf(animated);
+    const offered = [
+        avif !== undefined ? `animated AVIF CRF ${avif.quality}${qualityApprox(avif)} at ${avif.width}px (${encoderRecipe("animated-avif", avif)}): ${kb(avif.bytes)} ${estLabel(avif)}` : undefined,
+        webp !== undefined ? `animated WebP q${webp.quality} at ${webp.width}px (${encoderRecipe("animated-webp", webp)}): ${kb(webp.bytes)} ${estLabel(webp)}` : undefined,
+    ].filter((part) => part !== undefined);
+    const coverage = [];
+    if (avif !== undefined)
+        coverage.push(COVERAGE.avif);
+    if (webp !== undefined)
+        coverage.push(COVERAGE.webp);
+    const cap = sourceCapLine(animated.need, animated.sourceWidth, main.width);
+    if (targets.video && av1 !== undefined) {
+        // An empty alt is a decorative image: the <video> is hidden from assistive technology, with no label. Otherwise the alt is
+        // kept as the accessible name (role="img", aria-label).
+        const decorative = alt !== undefined && alt.trim() === "";
+        const altPart = decorative
+            ? ' aria-hidden="true"'
+            : alt !== undefined
+                ? ` role="img" aria-label=${JSON.stringify(safeText(alt))}`
+                : "";
+        const lines = [`   ${head}: replace with <video autoplay muted loop playsinline poster="<first frame>"${altPart}>`];
+        if (decorative)
+            lines.push('     the image is decorative (alt=""): the <video> is aria-hidden, with no label');
+        else if (alt !== undefined)
+            lines.push("     the image's alt text is kept as the <video>'s aria-label (role=\"img\"): the accessible name does not change");
+        lines.push(`     <source src="…-${av1.width}.av1.mp4" type="${AV1_TYPE}"> AV1 MP4 (${encoderRecipe("av1-mp4", av1)}), CRF ${av1.quality}${qualityApprox(av1)}, ${av1.width}px, ${kb(av1.bytes)} ${estLabel(av1)}`);
+        lines.push(h264 !== undefined
+            ? `     <source src="…-${h264.width}.h264.mp4" type="${H264_TYPE}"> H.264 MP4 (${encoderRecipe("h264-mp4", h264)}), ${h264.width}px, ${kb(h264.bytes)} ${estLabel(h264)}`
+            : `     <source src="…-${av1.width}.h264.mp4" type="${H264_TYPE}"> H.264 fallback, not measured: ${H264_RECIPE} at ${av1.width}px wide`);
+        if (cap !== undefined)
+            lines.push(cap);
+        lines.push(`   evidence: ${evidenceOf(av1)}`);
+        lines.push(`   browsers: ${COVERAGE.av1}`);
+        if (offered.length > 0)
+            lines.push(`   alternative: ${offered.join(", ")}`);
+        if (offered.length > 0)
+            lines.push(...coverage.map((line) => `   browsers: ${line}`));
+        lines.push(`   saves ${kb(saves)}/view est. ${SAMPLE_NOTE}`);
+        return lines;
+    }
+    const fallback = imageFallbackOf(animated.context, targets, src);
+    const lines = [`   ${head}: serve ${offered.join(", ")}; ${fallback}; saves ${kb(saves)}/view est. ${SAMPLE_NOTE}`];
+    if (cap !== undefined)
+        lines.push(cap);
+    lines.push(`   evidence: ${evidenceOf(main)}`);
+    lines.push(...coverage.map((line) => `   browsers: ${line}`));
+    return lines;
+}
+/** The name a video records by: where it is in the page, a file or component, else its selector. */
+export function videoWhere(video) {
+    if (video.locator.file !== undefined)
+        return `${video.locator.file}:${video.locator.line ?? 0}`;
+    return video.locator.component[0] ?? video.locator.selector;
+}
+/**
+ * The bytes a view and a play save, est. The lever steps are per play (the full file less the encode); the view's share is
+ * the same fraction of the bytes the page loads per view.
+ */
+export function videoSavingOf(video) {
+    if (video.steps === undefined || video.estimate === undefined)
+        return { view: 0, play: 0 };
+    const { audio, resolution, codec, quality } = video.steps;
+    const play = audio + resolution + codec + quality;
+    const { perView, perPlay } = video.bytes;
+    return { view: perPlay > 0 ? (play * perView) / perPlay : 0, play };
+}
+/**
+ * One record per file of each page: a URL that two `<video>` elements of a page use is one file, fetched once per page view.
+ * Of the records sharing a URL, the one with the most bytes per view stands for it (the page's own elements keep their rows).
+ */
+export function onePerFile(videos) {
+    const byFile = new Map();
+    for (const video of videos) {
+        const key = `${video.page}\n${video.src}`;
+        const current = byFile.get(key);
+        if (current === undefined || video.bytes.perView > current.bytes.perView)
+            byFile.set(key, video);
+    }
+    return [...byFile.values()];
+}
+/**
+ * The Video section's totals: bytes per view and per play over the files (each URL once per page, see onePerFile), and the
+ * saveable bytes (an estimate, marked when any video has steps). Undefined with no video.
+ */
+export function videoTotalsLine(videos) {
+    if (videos.length === 0)
+        return undefined;
+    const files = onePerFile(videos);
+    const sum = (values) => values.reduce((total, v) => total + v, 0);
+    const savings = files.map(videoSavingOf);
+    const est = files.some((v) => v.steps !== undefined && v.estimate !== undefined) ? " est." : "";
+    return `video: ${kb(sum(files.map((v) => v.bytes.perView)))}/view, ${kb(sum(files.map((v) => v.bytes.perPlay)))}/play, saveable ${kb(sum(savings.map((s) => s.view)))}/view (${kb(sum(savings.map((s) => s.play)))}/play)${est}`;
+}
+/** A video's encode in one phrase: the encode at its width with its bytes, or why it was not encoded. */
+export function videoStatusOf(video) {
+    const e = video.estimate;
+    if (e === undefined)
+        return `not encoded: ${safeText(reasonText(video.notEncoded ?? "no passing quality"))}`;
+    return `${codecName(e.codec)} CRF ${e.quality}${qualityApprox(e)}, ${e.width}px, ${kb(e.bytes)} ${estLabel(e)}`;
+}
+/** One video as a row of a page's Video section: its place (quoted by the caller), its bytes, and its encode or reason. */
+export function videoRowOf(video, quote) {
+    return `${quote(videoWhere(video))}: ${kb(video.bytes.perView)}/view, ${kb(video.bytes.perPlay)}/play; ${videoStatusOf(video)}`;
+}
+/** What the bytes per view are, as a hint says it: the autoplay full file, the bytes seen in the scan, or none. */
+function viewBasisOf(video) {
+    const b = video.bytes;
+    if (b.perViewBasis === "full-file")
+        return "autoplay: full file";
+    if (b.perViewBasis === "none")
+        return "not loaded before play";
+    return b.browserDependent ? "preload=auto: browser-dependent, bytes seen in the scan" : "bytes seen in the scan";
+}
+/**
+ * The bytes per view of a width plan (audit), est. (scaled): each viewport's bytes at its width are the encode's bytes times
+ * (w / w_encoded)², the pixel ratio, and the per-view share of the file. They are summed over the viewports and divided by
+ * their count, the same average the image savings use. Without an encode, "not encoded" and the reason.
+ */
+function bytesAtPlan(video, plan) {
+    const est = video.estimate;
+    if (est === undefined || video.bytes.perPlay <= 0) {
+        return `not encoded${video.notEncoded !== undefined ? `: ${safeText(reasonText(video.notEncoded))}` : ""}`;
+    }
+    if (plan.perViewport.length === 0)
+        return "-";
+    const ratio = video.bytes.perView / video.bytes.perPlay;
+    const total = plan.perViewport.reduce((sum, v) => sum + est.bytes * (v.width / est.width) ** 2 * ratio, 0);
+    return `${kb(total / plan.perViewport.length)}/view est. (scaled)`;
+}
+/** Audit: each viewport's need, and the bytes per view at one, two and three widths. No pick: the agent chooses. */
+function widthOptionLines(options) {
+    const lines = [];
+    const first = options[0];
+    if (first !== undefined && first.perViewport.length > 0) {
+        lines.push(`   viewports: ${first.perViewport.map((v) => `${JSON.stringify(safeText(v.viewport))} needs ${v.need}px`).join(", ")}`);
+    }
+    lines.push("   widths → bytes/view (audit: no pick)");
+    return lines;
+}
+/**
+ * The line that says a video's served width is capped at its file's own: a viewport needs more than the file has, and the
+ * plan serves the file's width. Undefined when no viewport is capped (or the file's width is not known).
+ */
+export function videoSourceCapLine(video) {
+    const source = video.probe?.width;
+    const plan = video.widths;
+    if (plan === undefined || source === undefined || !(source > 0))
+        return undefined;
+    // The plan's needs are already capped at the file's width, so the need is taken from the boxes: what the page shows.
+    const need = Math.max(0, ...video.perViewport.filter((v) => v.boxWidth > 0).map((v) => Math.ceil(v.boxWidth * v.dpr)));
+    if (!(need > source) || !plan.perViewport.some((row) => row.width === source))
+        return undefined;
+    return sourceCapLine(need, source, source);
+}
+/** Scan: the `<source>` list of the planned widths, AV1 then H.264 for each, with the encode's CRF and bytes at its width. */
+function targetLines(video, plan) {
+    if (plan.containerDriven) {
+        return plan.perViewport.map((row) => {
+            const box = video.perViewport.find((v) => v.viewport === row.viewport);
+            const boxText = box !== undefined ? `box ${box.boxWidth} px at ${box.dpr}x` : "box not read";
+            return `     viewport ${JSON.stringify(safeText(row.viewport))}: ${boxText}, serve ${row.width}px`;
+        });
+    }
+    const est = video.estimate;
+    const lines = [];
+    for (const source of plan.sources) {
+        const media = source.media !== undefined ? `media="${source.media}" ` : "";
+        for (const kind of ["av1", "h264"]) {
+            const codec = kind === "av1" ? "av1-mp4" : "h264-mp4";
+            const label = kind === "av1" ? "AV1" : "H.264";
+            // Every source names the exact encoder settings an agent runs: the estimate's codec, preset and CRF. At the estimate's
+            // own width that is measured; at another width the same settings apply, which is not measured there.
+            const same = est !== undefined && est.codec === codec ? est : undefined;
+            let at;
+            if (same !== undefined && same.width === source.width) {
+                at = ` ${label} MP4 (${encoderRecipe(codec, same)}), CRF ${same.quality}${qualityApprox(same)}, ${same.width}px, ${kb(same.bytes)} ${estLabel(same)}`;
+            }
+            else if (same !== undefined) {
+                at = ` ${label} MP4 (${encoderRecipe(codec, same)}), CRF ${same.quality}${qualityApprox(same)}, ${source.width}px: same settings, not measured at this width`;
+            }
+            else if (kind === "h264") {
+                at = ` H.264 MP4 (${H264_RECIPE}), ${source.width}px: not measured (no H.264 encode for this video)`;
+            }
+            else {
+                at = ` AV1 MP4 (libsvtav1 -preset 10 -pix_fmt yuv420p -movflags +faststart), CRF not measured: no AV1 encode passed for this video`;
+            }
+            lines.push(`     <source ${media}src="…-${source.width}.${kind}.mp4" type="${kind === "av1" ? AV1_TYPE : H264_TYPE}">${at}`);
+        }
+    }
+    return lines;
+}
+/**
+ * The lines of one video's hint: where and the bytes; the levers of the encode (audio, resolution, re-encode, one line each
+ * with its bytes per play; never a quality line, as the encode's quality is the re-encode); the loading, codec and poster
+ * levers; the target sources (or the widths table in audit); the evidence; and the saving. Without steps, the target and its
+ * bytes only. Without an encode, the reason.
+ */
+export function videoLines(video, rank = 1) {
+    const lines = [`${rank}. ${safeText(video.id)}  ${JSON.stringify(safeText(videoWhere(video)))}  ${safeText(video.page)}`];
+    lines.push(`   bytes: ${kb(video.bytes.perView)}/view (${viewBasisOf(video)}), ${kb(video.bytes.perPlay)}/play`);
+    const est = video.estimate;
+    if (est !== undefined && video.steps !== undefined) {
+        const s = video.steps;
+        lines.push(`   audio: drop the track (muted video): saves ${kb(s.audio)}/play est.`);
+        lines.push(`   resolution: serve ${est.width}px: saves ${kb(s.resolution)}/play est.`);
+        lines.push(`   re-encode (${codecName(est.codec)} CRF ${est.quality}): saves ${kb(s.codec)}/play est.`);
+    }
+    if (video.levers.loading !== undefined) {
+        const loading = video.levers.loading;
+        const attr = video.attributes.preload === "" ? "no preload attribute" : `preload=${JSON.stringify(safeText(video.attributes.preload))}`;
+        const action = video.attributes.autoplay
+            ? "autoplay fetches the file on load: lazy-load the video until it is in view"
+            : loading.belowFold
+                ? 'below the fold: set preload="none"'
+                : 'set preload="metadata"';
+        lines.push(`   loading: ${attr} loads ${kb(loading.perViewBytes)}/view before play: ${action}`);
+    }
+    if (video.levers.codec !== undefined)
+        lines.push("   codec: no AV1 source: serve AV1 first, H.264 fallback");
+    if (video.levers.posterMissing === true)
+        lines.push('   poster: none: add poster="<first frame>" (audited as an image)');
+    for (const note of video.levers.info)
+        lines.push(`   info: ${safeText(note)}`);
+    if (video.widthOptions !== undefined) {
+        lines.push(...widthOptionLines(video.widthOptions));
+        for (const plan of video.widthOptions) {
+            lines.push(`     ${plan.widths.length} width(s): ${plan.widths.map((w) => `${w}px`).join(", ")} → ${bytesAtPlan(video, plan)}`);
+        }
+    }
+    else if (video.widths !== undefined) {
+        lines.push(...targetLines(video, video.widths));
+        const cap = videoSourceCapLine(video);
+        if (cap !== undefined)
+            lines.push(cap);
+    }
+    if (est !== undefined)
+        lines.push(`   evidence: ${evidenceOf(est)}`);
+    else if (video.notEncoded !== undefined)
+        lines.push(`   not encoded: ${safeText(reasonText(video.notEncoded))}`);
+    if (est !== undefined && video.steps !== undefined) {
+        const s = videoSavingOf(video);
+        lines.push(`   saves ${kb(s.view)}/view est., ${kb(s.play)}/play est. ${SAMPLE_NOTE}`);
+    }
+    else if (est !== undefined) {
+        lines.push(`   ${SAMPLE_NOTE}`);
+    }
+    return lines;
+}
+/** The hints command's Video part: each video's hint, numbered. Empty with no video. */
+export function renderVideoHints(videos) {
+    if (videos.length === 0)
+        return "";
+    const body = videos.flatMap((video, i) => videoLines(video, i + 1));
+    return `${videos.length} video(s) on the page(s), self-hosted files:\n${body.join("\n")}\n`;
+}
 /**
  * The line that says where the sources of a file came from: the dev page it was located on, or, when hinted images still
  * have no file:line, the command that locates them. Undefined when every hint has its source.
@@ -538,6 +940,13 @@ function planJson(plan) {
         estTotalBytes: Math.round(plan.total),
     };
 }
+/** The videos of the selected pages, for the hints command (none when a --component filter is given: videos have no sizes). */
+function videosOf(results, args) {
+    if (args.component !== undefined)
+        return [];
+    const page = args.page?.toLowerCase();
+    return results.flatMap((r) => r.videos ?? []).filter((v) => page === undefined || v.page.toLowerCase().includes(page));
+}
 /** `imgtune hints <scan.json> [<scan.json> ...] ...`: reads the pages' scan files, returns the text or JSON to print. */
 export async function hintsCommand(argv, cwd) {
     const args = parseHintsArgs(argv);
@@ -568,12 +977,13 @@ export async function hintsCommand(argv, cwd) {
     if (dropped > 0)
         notes.push(`${dropped} sizes proposal(s) left out: no saving (their predicted outcome adds bytes or changes nothing)`);
     const filtered = selectHints(all, { ...args, limit: Number.MAX_SAFE_INTEGER, offset: 0 });
+    const videos = videosOf(results, args);
     if (args.top !== undefined) {
         const top = groupHints(filtered).slice(0, args.top);
         if (args.format === "json") {
             return { output: `${JSON.stringify({ top: top.map((g, i) => ({ rank: i + 1, key: g.key, saved: g.saved, images: g.hints.length, pages: g.pages.map((p) => pathOf(p)), file: g.hints[0].file ?? null, line: g.hints[0].line ?? null, component: g.hints[0].component, sizes: combinedSizes(g) })), qualities: planJson(plan) }, null, 2)}\n`, exitCode: 0 };
         }
-        return { output: `${notes.length > 0 ? `${notes.join("\n")}\n` : ""}${renderTop(top)}`, exitCode: 0 };
+        return { output: `${notes.length > 0 ? `${notes.join("\n")}\n` : ""}${renderTop(top)}${renderVideoHints(videos)}`, exitCode: 0 };
     }
     // JSON is not cut to the text default: it is all of it unless --limit is passed, and `truncated` says whether it is.
     const jsonLimit = args.limitGiven ? args.limit : Number.MAX_SAFE_INTEGER;
@@ -606,10 +1016,11 @@ export async function hintsCommand(argv, cwd) {
                     ids: group.hints.map((h) => h.id),
                     hints: group.hints,
                 })),
+                ...(videos.length > 0 ? { videos } : {}),
             };
             return { output: `${JSON.stringify(body, null, 2)}\n`, exitCode: 0 };
         }
-        const text = renderGroups(selectedGroups, groups.length, filtered.length, args.offset, args.page);
+        const text = `${renderGroups(selectedGroups, groups.length, filtered.length, args.offset, args.page)}${renderVideoHints(videos)}`;
         return { output: notes.length > 0 ? `${notes.join("\n")}\n${text}` : text, exitCode: 0 };
     }
     const selected = selectHints(all, args.format === "json" ? { ...args, limit: jsonLimit } : args);
@@ -624,10 +1035,11 @@ export async function hintsCommand(argv, cwd) {
             truncated: args.offset + selected.length < filtered.length,
             qualities: planJson(plan),
             hints: selected,
+            ...(videos.length > 0 ? { videos } : {}),
         };
         return { output: `${JSON.stringify(body, null, 2)}\n`, exitCode: 0 };
     }
-    const text = renderHints(selected, filtered.length, args.offset, args.page);
+    const text = `${renderHints(selected, filtered.length, args.offset, args.page)}${renderVideoHints(videos)}`;
     return { output: notes.length > 0 ? `${notes.join("\n")}\n${text}` : text, exitCode: 0 };
 }
 /** How many hints the PR comment lists. */