@mieweb/pulsevault 0.5.0 → 0.7.0

package/dist/lib/web-ready.js

@@ -1,31 +1,59 @@
-import { execFile } from 'node:child_process';
+import { execFile, spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { createInterface } from 'node:readline';
 import { promisify } from 'node:util';
 const execFileAsync = promisify(execFile);
 /**
- * Web-playability backstop for uploaded MP4 artifacts.
+ * Conform uploaded videos to one web-playable format: the one the Pulse app records.
  *
- * Browsers streaming an MP4 over progressive HTTP need two things the mobile
- * capture pipelines frequently don't provide:
+ * A video reaches PulseVault from the Pulse app (already in the target format) or from a host's
+ * own file picker: a screen recording, an iPhone HEVC `.mov` (often 10-bit HDR), a WebM from a
+ * browser recorder, a 4K clip. Browsers streaming over progressive HTTP need the `moov` atom at
+ * the front, a codec they all decode, and 8-bit SDR colour; a phone needs a sane size.
  *
- * 1. The `moov` atom at the FRONT of the file ("faststart"). iOS/Android
- *    recorders finalize the moov at the end, so a `<video>` tag must fetch the
- *    file's tail before it can render frame one — a multi-second stall behind
- *    Range requests, or a full download in naive players.
- * 2. A codec browsers actually decode. iPhones record HEVC by default, which
- *    Firefox never plays and Chrome usually can't without hardware support.
- *
- * `ensureWebReady` fixes both in place: a lossless sub-second remux
- * (`-c copy -movflags +faststart`) when only the moov position is wrong, and a
- * one-time H.264 transcode when the codec is hostile. Fail-open by design —
- * if `ffmpeg`/`ffprobe` are not installed, or the file isn't MP4-family, the
- * artifact is left byte-for-byte as uploaded and serving continues exactly as
- * before.
+ * `ensureWebReady` does the least work that gets a file there: nothing when it already
+ * conforms (a Pulse upload keeps its bytes), a lossless remux when only the container or the
+ * `moov` position is off, and otherwise one ffmpeg run that re-encodes only the streams that
+ * are off-target. Fail-open by design: without `ffmpeg`/`ffprobe`, or when a run fails or
+ * times out, the original bytes keep serving and the result says why.
+ */
+/**
+ * The format every video is served in. "Already conforms" checks exactly these properties —
+ * never the orientation: a landscape video stays landscape and a portrait one portrait, with no
+ * crop, pad or stretch.
  */
-/** Codecs every mainstream browser decodes without hardware caveats. */
-const WEB_SAFE_VIDEO_CODECS = new Set(['h264']);
+export const CONFORM_TARGET = {
+    /** MP4 with the `moov` atom at the front (faststart). */
+    container: 'mp4',
+    extension: '.mp4',
+    /**
+     * H.264, 8-bit 4:2:0 in limited range, even width and height, SDR, no rotation tag. HDR (PQ,
+     * HLG) is tone-mapped to BT.709; an SDR source keeps its own colour tags (BT.709 or BT.601),
+     * which browsers honour — so a Pulse upload from any phone keeps its bytes.
+     */
+    videoCodec: 'h264',
+    pixelFormat: 'yuv420p',
+    /** Default cap on the longest edge, in pixels (`webReady.maxEdge`). */
+    maxEdge: 1920,
+    /** AAC; a video without audio stays silent. */
+    audioCodec: 'aac',
+};
+/** The containers the conform step turns into the target: the default video `allowedExtensions`. */
+export const CONFORM_VIDEO_EXTENSIONS = [
+    '.mp4',
+    '.mov',
+    '.m4v',
+    '.webm',
+    '.mkv',
+    '.3gp',
+    '.avi',
+];
+/** ffprobe demuxers that read still or animated images, not video. */
+const IMAGE_FORMATS = /^(image2|[a-z0-9]+_pipe|gif|apng|webp)$/;
+/** Transfer functions of HDR video (PQ and HLG): tone-mapped to SDR on the way in. */
+const HDR_TRANSFERS = new Set(['smpte2084', 'arib-std-b67']);
 /**
  * Walk the file's top-level ISO-BMFF boxes and report whether `moov` appears
  * before or after `mdat`. Pure Node (a handful of 16-byte header reads) — no
@@ -33,7 +61,7 @@ const WEB_SAFE_VIDEO_CODECS = new Set(['h264']);
  * costs microseconds regardless of file size.
  *
  * Returns `"unknown"` for non-MP4 bytes, truncated headers, or files missing
- * either box — callers should treat that as "leave the file alone".
+ * either box.
  */
 export async function scanMoovPosition(filePath) {
     let fd;
@@ -56,7 +84,7 @@ export async function scanMoovPosition(filePath) {
             let boxSize = header.readUInt32BE(0);
             const boxType = header.toString('latin1', 4, 8);
             if (first) {
-                // Anything that doesn't open with ftyp isn't MP4-family — don't touch it.
+                // Anything that doesn't open with ftyp isn't MP4-family.
                 if (boxType !== 'ftyp')
                     return 'unknown';
                 first = false;
@@ -91,55 +119,267 @@ export async function scanMoovPosition(filePath) {
         await fd.close();
     }
 }
-/** ffprobe the first video stream's codec name; `null` when unprobeable. */
-async function probeVideoCodec(filePath, ffprobePath) {
+/** An ffprobe run past its `timeoutSeconds`: the file couldn't be read in time. */
+export class ProbeTimeoutError extends Error {
+}
+const DEFAULT_PROBE_TIMEOUT_SECONDS = 60;
+/**
+ * Degrees as a display rotation in (-180, 180]: the nearest quarter turn when within a degree of
+ * one (270 → -90, -180 → 180, 360 → 0, 89.9 → 90), else the angle itself (45 → 45).
+ */
+const displayRotation = (degrees) => {
+    const turns = Math.round(degrees / 90);
+    if (Math.abs(degrees - turns * 90) <= 1)
+        return [0, 90, 180, -90][((turns % 4) + 4) % 4] ?? 0;
+    const angle = ((degrees % 360) + 360) % 360;
+    return angle > 180 ? angle - 360 : angle;
+};
+/** ffprobe's `120/1` or `30000/1001` as frames per second; `undefined` for `0/0`. */
+const frameRateOf = (ratio) => {
+    const [num, den] = (ratio ?? '').split('/').map(Number);
+    const fps = num && den ? num / den : NaN;
+    return Number.isFinite(fps) && fps > 0 ? fps : undefined;
+};
+const positive = (value) => {
+    const n = typeof value === 'number' ? value : Number.parseFloat(String(value));
+    return Number.isFinite(n) && n > 0 ? n : null;
+};
+/**
+ * Run ffprobe on an untrusted upload, bounded: killed past `timeoutMs` (`ProbeTimeoutError`).
+ * Resolves its stdout, or `null` when ffprobe fails on the file.
+ */
+async function runProbe(ffprobePath, args, timeoutMs) {
+    try {
+        // Small, bounded output only (the metadata, two packets); the packet scan streams instead.
+        const { stdout } = await execFileAsync(ffprobePath, ['-v', 'error', ...args], {
+            maxBuffer: 16 * 1024 * 1024,
+            timeout: timeoutMs,
+            killSignal: 'SIGKILL',
+        });
+        return stdout;
+    }
+    catch (err) {
+        if (err.killed) {
+            throw new ProbeTimeoutError(`ffprobe timed out after ${Math.round(timeoutMs / 100) / 10} s`);
+        }
+        return null;
+    }
+}
+/**
+ * The span of the video packets — from the first packet's start to the last one's end — for a
+ * file whose header carries no duration (a WebM from a browser's MediaRecorder is written without
+ * one). Timestamps needn't start at zero, and may be negative. Demuxes without decoding.
+ */
+async function packetDuration(filePath, ffprobePath, index, timeoutMs) {
+    // One line per packet, read as it comes and kept only as the earliest start and latest end: a
+    // crafted file with millions of tiny packets costs time (bounded by the timeout), never memory.
+    const child = spawn(ffprobePath, ['-v', 'error', '-select_streams', String(index), '-show_entries', 'packet=pts_time,duration_time', '-of', 'csv=p=0', filePath], { stdio: ['ignore', 'pipe', 'ignore'] });
+    // Settles once the process is gone, whether it exited or never started (a bad path).
+    const exited = new Promise((resolve) => {
+        child.once('close', (exitCode) => resolve(exitCode));
+        child.once('error', () => resolve(null));
+    });
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        child.kill('SIGKILL');
+    }, timeoutMs);
+    let start = Infinity;
+    let end = -Infinity;
     try {
-        const { stdout } = await execFileAsync(ffprobePath, [
-            '-v', 'error',
-            '-select_streams', 'v:0',
-            '-show_entries', 'stream=codec_name',
-            '-of', 'default=noprint_wrappers=1:nokey=1',
-            filePath,
-        ]);
-        const codec = stdout.trim();
-        return codec.length > 0 ? codec : null;
+        for await (const line of createInterface({ input: child.stdout })) {
+            const [pts, duration] = line.split(',');
+            const at = Number.parseFloat(pts ?? '');
+            if (!Number.isFinite(at))
+                continue; // `N/A`
+            start = Math.min(start, at);
+            end = Math.max(end, at + (positive(duration) ?? 0));
+        }
+        const code = await exited;
+        if (timedOut)
+            throw new ProbeTimeoutError(`ffprobe timed out after ${Math.round(timeoutMs / 100) / 10} s`);
+        if (code !== 0)
+            return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    const span = end - start;
+    return Number.isFinite(span) && span > 0 ? span : null;
+}
+/** Whether a stream has at least two packets: reads only the first two. */
+async function hasTwoPackets(filePath, ffprobePath, index, timeoutMs) {
+    const stdout = await runProbe(ffprobePath, ['-select_streams', String(index), '-read_intervals', '%+#2', '-show_entries', 'packet=pts', '-of', 'csv=p=0', filePath], timeoutMs);
+    return (stdout ?? '').split('\n').filter((line) => line.trim() !== '').length >= 2;
+}
+/**
+ * ffprobe a file: its first real video stream (not cover art), its first audio stream and its
+ * duration. `null` when it isn't a video: ffprobe can't read it, it has no video stream, or it
+ * is a picture (an image file, or a stream of one frame). Each ffprobe run is bounded by
+ * `timeoutSeconds`; past it, rejects with `ProbeTimeoutError`.
+ */
+export async function probeVideo(filePath, options = {}) {
+    const ffprobePath = options.ffprobePath ?? 'ffprobe';
+    // At least 1 ms: Node treats a timeout of 0 as none.
+    const timeoutMs = Math.max(1, Math.round((options.timeoutSeconds ?? DEFAULT_PROBE_TIMEOUT_SECONDS) * 1000));
+    const stdout = await runProbe(ffprobePath, [
+        '-show_entries',
+        'stream=index,codec_type,codec_name,pix_fmt,width,height,color_transfer,color_range,nb_frames,avg_frame_rate' +
+            ':stream_disposition=attached_pic:stream_side_data=rotation:stream_tags=rotate' +
+            ':format=duration,format_name',
+        '-of', 'json',
+        filePath,
+    ], timeoutMs);
+    if (stdout === null)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
     }
     catch {
         return null;
     }
+    const streams = parsed.streams ?? [];
+    const video = streams.find((s) => s.codec_type === 'video' && !s.disposition?.attached_pic && s.width && s.height);
+    if (!video || typeof video.index !== 'number')
+        return null;
+    // A picture isn't a video: an image file (PNG, JPEG, GIF, WebP) read by an image demuxer, or
+    // a single-frame stream (an iPhone HEIC photo is an ISO-BMFF file with one HEVC frame). A
+    // container that doesn't record a frame count (MKV, WebM) is asked for its first two packets.
+    if (IMAGE_FORMATS.test(parsed.format?.format_name ?? ''))
+        return null;
+    const frames = Number(video.nb_frames);
+    if (Number.isFinite(frames) ? frames < 2 : !(await hasTwoPackets(filePath, ffprobePath, video.index, timeoutMs))) {
+        return null;
+    }
+    const audio = streams.find((s) => s.codec_type === 'audio');
+    const sideRotation = video.side_data_list?.find((d) => d.rotation !== undefined)?.rotation;
+    const rotation = Number(sideRotation ?? video.tags?.rotate ?? 0) || 0;
+    const durationSeconds = positive(parsed.format?.duration) ?? (await packetDuration(filePath, ffprobePath, video.index, timeoutMs));
+    return {
+        video: {
+            index: video.index,
+            codec: video.codec_name ?? '',
+            pixelFormat: video.pix_fmt ?? '',
+            width: video.width ?? 0,
+            height: video.height ?? 0,
+            ...(video.color_transfer ? { transfer: video.color_transfer } : {}),
+            ...(video.color_range && video.color_range !== 'unknown' ? { range: video.color_range } : {}),
+            rotation: displayRotation(rotation),
+            ...(frameRateOf(video.avg_frame_rate) ? { frameRate: frameRateOf(video.avg_frame_rate) } : {}),
+        },
+        audio: audio && typeof audio.index === 'number' ? { index: audio.index, codec: audio.codec_name ?? '' } : null,
+        durationSeconds,
+    };
 }
 // One availability probe per (binary path) per process — a missing ffmpeg
 // should cost one spawn and one warning, not one of each per upload.
 const binaryAvailable = new Map();
 const warnedMissing = new Set();
-function isBinaryAvailable(binPath) {
+/** Capability queries (`-version`, `-h`, `-filters`) answer at once; one that hangs is killed. */
+const QUERY_TIMEOUT_MS = 30_000;
+const query = (binPath, args) => execFileAsync(binPath, args, { timeout: QUERY_TIMEOUT_MS, killSignal: 'SIGKILL', maxBuffer: 4 * 1024 * 1024 });
+export function isBinaryAvailable(binPath) {
     let cached = binaryAvailable.get(binPath);
     if (!cached) {
-        cached = execFileAsync(binPath, ['-version']).then(() => true, () => false);
+        cached = query(binPath, ['-version']).then(() => true, () => false);
         binaryAvailable.set(binPath, cached);
     }
     return cached;
 }
-/** Run ffmpeg writing to a sibling tmp file, then atomically replace the original. */
-async function rewriteInPlace(filePath, ffmpegPath, args) {
-    const dir = path.dirname(filePath);
+/** Whether this host can conform videos: both `ffmpeg` and `ffprobe` run. */
+export async function webReadyAvailable(options = {}) {
+    const [ffmpeg, ffprobe] = await Promise.all([
+        isBinaryAvailable(options.ffmpegPath ?? 'ffmpeg'),
+        isBinaryAvailable(options.ffprobePath ?? 'ffprobe'),
+    ]);
+    return ffmpeg && ffprobe;
+}
+const toneMappers = new Map();
+function toneMapperOf(ffmpegPath) {
+    let cached = toneMappers.get(ffmpegPath);
+    if (!cached) {
+        cached = (async () => {
+            try {
+                const { stdout: scaleHelp } = await query(ffmpegPath, ['-hide_banner', '-h', 'filter=scale']);
+                if (scaleHelp.includes('out_transfer'))
+                    return 'scale';
+                const { stdout: filters } = await query(ffmpegPath, ['-hide_banner', '-filters']);
+                return /\szscale\s/.test(filters) ? 'zscale' : null;
+            }
+            catch {
+                return null;
+            }
+        })();
+        toneMappers.set(ffmpegPath, cached);
+    }
+    return cached;
+}
+/**
+ * Rounded to whole pixels, then down to even (at least 2): never above the limit it was scaled
+ * to (an odd `maxEdge` stays a cap), and an odd source edge loses a pixel rather than gaining one.
+ */
+const even = (n) => Math.max(2, 2 * Math.floor(Math.round(n) / 2));
+/** The displayed size (after rotation) scaled so the longest edge is at most `maxEdge`. */
+function targetSize(video, maxEdge) {
+    const sideways = Math.abs(video.rotation) === 90;
+    const width = sideways ? video.height : video.width;
+    const height = sideways ? video.width : video.height;
+    const scale = Math.min(1, maxEdge / Math.max(width, height));
+    return { width: even(width * scale), height: even(height * scale) };
+}
+/** The `-vf` chain for a re-encode: tone map (HDR), scale to the target size, 8-bit 4:2:0. */
+function videoFilter(size, hdr, toneMapper) {
+    const { width, height } = size;
+    if (hdr && toneMapper === 'scale') {
+        return (`scale=w=${width}:h=${height}:out_transfer=bt709:out_primaries=bt709` +
+            ':out_color_matrix=bt709:out_range=tv:intent=perceptual,format=yuv420p');
+    }
+    if (hdr && toneMapper === 'zscale') {
+        return ('zscale=t=linear:npl=100,format=gbrpf32le,zscale=p=bt709,tonemap=tonemap=hable:desat=0,' +
+            `zscale=t=bt709:m=bt709:r=tv,format=yuv420p,scale=${width}:${height}`);
+    }
+    // `out_range=tv`: a full-range source (`yuvj420p`, as iPhone screen recordings are) is
+    // converted to the limited range of `yuv420p`; `format` alone keeps the source's range.
+    return `scale=${width}:${height}:out_range=tv,format=yuv420p`;
+}
+class TimeoutError extends Error {
+}
+/**
+ * Run ffmpeg into a sibling tmp file, then rename it onto `outputPath` (the input itself, or a
+ * new `.mp4` beside it). The rename is atomic, so a crash never leaves a half-written artifact.
+ */
+async function rewrite(inputPath, outputPath, ffmpegPath, args, timeoutMs) {
     // randomUUID in the name: every video artifact shares one kind directory, so
     // a pid+timestamp tmp name collides when two uploads finish in the same
     // millisecond — both ffmpegs would interleave writes into one file and the
     // winner's rename would install garbage bytes over a real artifact.
-    const tmp = path.join(dir, `.webready-${randomUUID()}${path.extname(filePath) || '.mp4'}`);
+    const tmp = path.join(path.dirname(inputPath), `.webready-${randomUUID()}${CONFORM_TARGET.extension}`);
     try {
-        await execFileAsync(ffmpegPath, ['-y', '-i', filePath, ...args, tmp], {
-            // A transcode of a long upload legitimately takes minutes; cap the
-            // buffered stderr instead of the wall clock.
-            maxBuffer: 16 * 1024 * 1024,
-        });
+        try {
+            await execFileAsync(ffmpegPath, ['-y', '-v', 'error', '-i', inputPath, ...args, tmp], {
+                // Cap the buffered stderr; the wall clock is capped by the timeout.
+                maxBuffer: 16 * 1024 * 1024,
+                timeout: timeoutMs,
+                killSignal: 'SIGKILL',
+            });
+        }
+        catch (err) {
+            if (err.killed) {
+                throw new TimeoutError(`timed out after ${Math.round(timeoutMs / 100) / 10} s`);
+            }
+            throw err;
+        }
         // ffmpeg exiting 0 with an empty/absent output would still be a corrupt
         // swap — verify there are real bytes before replacing the original.
         const stat = await fs.stat(tmp);
         if (stat.size === 0)
             throw new Error('ffmpeg produced an empty output');
-        await fs.rename(tmp, filePath);
+        // `null`: the caller installs the file itself (`install: false`).
+        if (outputPath === null)
+            return tmp;
+        await fs.rename(tmp, outputPath);
+        return outputPath;
     }
     catch (err) {
         await fs.rm(tmp, { force: true });
@@ -147,19 +387,78 @@ async function rewriteInPlace(filePath, ffmpegPath, args) {
     }
 }
 /**
- * Make the MP4 at `filePath` web-playable, in place:
+ * A failed run, in words fit for the status route: never ffmpeg's stderr, which names server
+ * paths (the full error goes to the log).
+ */
+function failureOf(err) {
+    if (err instanceof TimeoutError)
+        return err.message;
+    const code = err.code;
+    return typeof code === 'number' ? `ffmpeg exited with code ${code}` : 'ffmpeg could not write the file';
+}
+/** Longest edge of a poster frame, in pixels: a card's size, not the video's. */
+const POSTER_MAX_EDGE = 640;
+const POSTER_TIMEOUT_MS = 60_000;
+/** A second in, past a fade from black; a shorter clip falls back to its first frame. */
+const POSTER_SEEK_SECONDS = [1, 0];
+/**
+ * One frame of a video as a JPEG, for a video that arrived without a thumbnail (a file from a
+ * host's own picker): its longest edge at most 640 px, turned the way the video plays. Resolves
+ * `null` when there's no frame to take (no video stream, ffmpeg missing or failing); the video
+ * then has no poster, and nothing else changes.
+ */
+export async function extractPosterFrame(filePath, options = {}) {
+    const ffmpegPath = options.ffmpegPath ?? 'ffmpeg';
+    if (!(await isBinaryAvailable(ffmpegPath)))
+        return null;
+    const scale = `scale='min(${POSTER_MAX_EDGE},iw)':'min(${POSTER_MAX_EDGE},ih)':force_original_aspect_ratio=decrease`;
+    for (const seconds of POSTER_SEEK_SECONDS) {
+        try {
+            const { stdout } = await execFileAsync(ffmpegPath, ['-v', 'error', '-ss', String(seconds), '-i', filePath, '-frames:v', '1', '-vf', scale]
+                .concat(['-pix_fmt', 'yuvj420p', '-q:v', '3', '-f', 'image2', '-c:v', 'mjpeg', 'pipe:1']), { encoding: 'buffer', maxBuffer: 8 * 1024 * 1024, timeout: POSTER_TIMEOUT_MS, killSignal: 'SIGKILL' });
+            // A seek past the end exits 0 with no frame: try the next one.
+            if (stdout.length > 0)
+                return stdout;
+        }
+        catch (err) {
+            options.logger?.error({ err, filePath }, 'pulsevault could not take a poster frame');
+            return null;
+        }
+    }
+    return null;
+}
+/** Fail at once on an option that can't work, for `ensureWebReady` and the core's `webReady`. */
+export function validateWebReadyOptions(options) {
+    const { maxEdge, timeoutSeconds, probeTimeoutSeconds } = options;
+    if (maxEdge !== undefined && !(Number.isInteger(maxEdge) && maxEdge >= 2)) {
+        throw new TypeError('`webReady.maxEdge` must be an integer of at least 2 (pixels)');
+    }
+    for (const [name, value] of [['timeoutSeconds', timeoutSeconds], ['probeTimeoutSeconds', probeTimeoutSeconds]]) {
+        if (value !== undefined && !(value > 0 && Number.isFinite(value))) {
+            throw new TypeError(`\`webReady.${name}\` must be a positive number of seconds`);
+        }
+    }
+}
+/**
+ * Bring the video at `filePath` to `CONFORM_TARGET`:
  *
- * - moov at the end + web-safe codec → lossless `-c copy -movflags +faststart`
- *   remux (sub-second, no quality change);
- * - non-web-safe codec (HEVC etc.) → one-time `libx264` transcode (audio
- *   stream-copied) with faststart;
- * - already faststart H.264, non-MP4 bytes, unprobeable files, or missing
- *   ffmpeg/ffprobe → untouched (`skipped`/`none`).
+ * - already conforming → `none`, bytes untouched;
+ * - an MP4 with conforming streams but the `moov` at the end → lossless faststart remux in
+ *   place (`remuxed`);
+ * - any other container with conforming streams → lossless remux into a new `.mp4` beside it
+ *   (`conformed`);
+ * - otherwise one ffmpeg run: the video re-encoded to H.264 when its codec, pixel format, bit
+ *   depth, size, rotation or dynamic range is off (scaled by the longest edge, rotation
+ *   applied, HDR tone-mapped), the audio re-encoded to AAC unless it already is — in place for
+ *   an MP4 (`transcoded`), into a new `.mp4` otherwise (`conformed`);
+ * - no ffmpeg/ffprobe, a file ffprobe can't read, a failed or timed-out run → `skipped` with
+ *   the reason; the original is untouched.
  *
- * The rewrite is atomic (tmp file + rename in the same directory), so a crash
- * mid-way never corrupts the served artifact. Never throws for pipeline
- * reasons — a failed ffmpeg run resolves to `skipped` with the reason, and the
- * original bytes keep serving.
+ * When the result carries `outputPath`, the conformed file was written there (`<name>.mp4`)
+ * and the original is left in place: the caller switches the artifact over, then removes it.
+ * With `install: false` nothing is renamed: every rewrite is left at a temporary path beside
+ * the input, returned as `outputPath`, for the caller to install (or remove).
+ * Never throws for pipeline reasons.
  *
  * NOTE: a rewrite changes the artifact's bytes, so any upload-time checksum
  * recorded for it (e.g. the local adapter's sidecar `checksum` from
@@ -168,56 +467,150 @@ async function rewriteInPlace(filePath, ffmpegPath, args) {
  * upload-time provenance, not current-file integrity.
  */
 export async function ensureWebReady(filePath, options = {}) {
+    validateWebReadyOptions(options);
     const ffmpegPath = options.ffmpegPath ?? 'ffmpeg';
     const ffprobePath = options.ffprobePath ?? 'ffprobe';
     const transcode = options.transcode ?? true;
+    const install = options.install ?? true;
+    const maxEdge = options.maxEdge ?? CONFORM_TARGET.maxEdge;
     const crf = options.crf ?? 23;
     const preset = options.preset ?? 'veryfast';
-    const moov = await scanMoovPosition(filePath);
-    if (moov === 'unknown') {
-        return { action: 'skipped', reason: 'not an MP4-family file (or no moov/mdat found)' };
-    }
-    if (!(await isBinaryAvailable(ffprobePath)) || !(await isBinaryAvailable(ffmpegPath))) {
+    if (!(await webReadyAvailable({ ffmpegPath, ffprobePath }))) {
         const key = `${ffmpegPath}|${ffprobePath}`;
         if (!warnedMissing.has(key)) {
             warnedMissing.add(key);
             options.logger?.error({ filePath }, 'pulsevault web-ready: ffmpeg/ffprobe not found — uploads are served as-is. ' +
-                'Install ffmpeg (apt install ffmpeg / brew install ffmpeg) to enable faststart remux and H.264 transcode.');
+                'Install ffmpeg (apt install ffmpeg / brew install ffmpeg) to conform videos for the web.');
         }
         return { action: 'skipped', reason: 'ffmpeg/ffprobe not available' };
     }
-    const codec = await probeVideoCodec(filePath, ffprobePath);
-    const codecHostile = codec !== null && !WEB_SAFE_VIDEO_CODECS.has(codec);
-    if (codecHostile && transcode) {
-        try {
-            await rewriteInPlace(filePath, ffmpegPath, [
-                '-c:v', 'libx264', '-preset', preset, '-crf', String(crf),
-                '-pix_fmt', 'yuv420p',
-                '-c:a', 'copy',
-                '-movflags', '+faststart',
-            ]);
-            return { action: 'transcoded', reason: `video codec ${codec} → h264 (+faststart)` };
-        }
-        catch (err) {
-            options.logger?.error({ err, filePath }, 'pulsevault web-ready: transcode failed; serving original bytes');
-            return { action: 'skipped', reason: `transcode failed: ${err.message}` };
-        }
+    let probe;
+    try {
+        probe = await probeVideo(filePath, { ffprobePath, timeoutSeconds: options.probeTimeoutSeconds });
     }
-    if (moov === 'end') {
-        try {
-            await rewriteInPlace(filePath, ffmpegPath, ['-c', 'copy', '-movflags', '+faststart']);
-            return { action: 'remuxed', reason: 'moov was at end of file; remuxed to faststart' };
-        }
-        catch (err) {
-            options.logger?.error({ err, filePath }, 'pulsevault web-ready: faststart remux failed; serving original bytes');
-            return { action: 'skipped', reason: `remux failed: ${err.message}` };
+    catch (err) {
+        if (!(err instanceof ProbeTimeoutError))
+            throw err;
+        options.logger?.error({ err, filePath }, 'pulsevault web-ready: ffprobe timed out; serving original bytes');
+        return { action: 'skipped', reason: err.message };
+    }
+    if (!probe)
+        return { action: 'skipped', reason: 'not a video ffprobe can read' };
+    // Phones only record quarter turns; any other angle would need its own geometry.
+    if (probe.video.rotation % 90 !== 0) {
+        return { action: 'skipped', reason: `rotation ${probe.video.rotation}° isn't a quarter turn` };
+    }
+    const { video, audio } = probe;
+    const moov = await scanMoovPosition(filePath);
+    const isMp4 = path.extname(filePath).toLowerCase() === CONFORM_TARGET.extension && moov !== 'unknown';
+    // What's off-target, stream by stream.
+    const hdr = video.transfer !== undefined && HDR_TRANSFERS.has(video.transfer);
+    const size = targetSize(video, maxEdge);
+    const videoOff = [];
+    if (video.codec !== CONFORM_TARGET.videoCodec)
+        videoOff.push(`codec ${video.codec}`);
+    if (video.pixelFormat !== CONFORM_TARGET.pixelFormat)
+        videoOff.push(`pixel format ${video.pixelFormat}`);
+    else if (video.range === 'pc')
+        videoOff.push('full range');
+    if (hdr)
+        videoOff.push(`HDR (${video.transfer})`);
+    if (video.rotation !== 0)
+        videoOff.push(`rotation ${video.rotation}°`);
+    if (video.rotation === 0 && (size.width !== video.width || size.height !== video.height)) {
+        videoOff.push(`size ${video.width}×${video.height}`);
+    }
+    const audioOff = audio !== null && audio.codec !== CONFORM_TARGET.audioCodec;
+    if (videoOff.length === 0 && !audioOff && isMp4 && moov === 'front') {
+        return { action: 'none', reason: 'already web-ready' };
+    }
+    if ((videoOff.length > 0 || audioOff) && !transcode) {
+        const off = [...videoOff, ...(audioOff ? [`audio ${audio?.codec}`] : [])].join(', ');
+        if (isMp4 && moov === 'end') {
+            try {
+                const written = await rewrite(filePath, install ? filePath : null, ffmpegPath, ['-c', 'copy', '-map', '0', '-movflags', '+faststart'], timeoutOf(options, probe));
+                return {
+                    action: 'remuxed',
+                    reason: `moov was at end of file; remuxed to faststart (${off} left as-is: transcode disabled)`,
+                    ...(install ? {} : { outputPath: written }),
+                };
+            }
+            catch (err) {
+                options.logger?.error({ err, filePath }, 'pulsevault web-ready: faststart remux failed; serving original bytes');
+                return { action: 'skipped', reason: `remux failed: ${failureOf(err)}` };
+            }
         }
+        // Not `none`: that means the file already conforms. This one is left off-target on purpose.
+        return { action: 'skipped', reason: `${off} left as-is (transcode disabled)` };
     }
-    return {
-        action: 'none',
-        reason: codecHostile
-            ? `already faststart; codec ${codec} left as-is (transcode disabled)`
-            : 'already web-ready',
-    };
+    // HDR without a way to tone-map it would come out with wrong colours tagged as right: keep
+    // the original and say what's missing instead.
+    const toneMapper = hdr ? await toneMapperOf(ffmpegPath) : null;
+    if (hdr && !toneMapper) {
+        options.logger?.error({ filePath }, 'pulsevault web-ready: HDR video, but this ffmpeg can\'t tone-map; serving original bytes');
+        return {
+            action: 'skipped',
+            reason: `HDR (${video.transfer}) needs tone mapping, which this ffmpeg can't do: FFmpeg 8 or later, or a build with zscale`,
+        };
+    }
+    const args = ['-map', `0:${video.index}`, ...(audio ? ['-map', `0:${audio.index}`] : []), '-sn', '-dn'];
+    const done = [];
+    if (videoOff.length > 0) {
+        args.push('-vf', videoFilter(size, hdr, toneMapper), '-c:v', 'libx264', '-preset', preset, '-crf', String(crf));
+        // An 8-bit SDR output must not keep the source's HDR colour tags.
+        if (hdr)
+            args.push('-color_primaries', 'bt709', '-color_trc', 'bt709', '-colorspace', 'bt709');
+        const toneMapped = hdr ? ', tone-mapped' : '';
+        done.push(`video ${videoOff.join(', ')} → h264 ${size.width}×${size.height}${toneMapped}`);
+    }
+    else {
+        args.push('-c:v', 'copy');
+    }
+    if (audioOff) {
+        args.push('-c:a', 'aac', '-b:a', '160k');
+        done.push(`audio ${audio?.codec} → aac`);
+    }
+    else if (audio) {
+        args.push('-c:a', 'copy');
+    }
+    args.push('-movflags', '+faststart');
+    const outputPath = isMp4
+        ? filePath
+        : path.join(path.dirname(filePath), `${path.basename(filePath, path.extname(filePath))}${CONFORM_TARGET.extension}`);
+    const action = !isMp4 ? 'conformed' : done.length > 0 ? 'transcoded' : 'remuxed';
+    if (!isMp4) {
+        const ext = path.extname(filePath).toLowerCase();
+        done.unshift(`container ${ext && ext !== CONFORM_TARGET.extension ? ext : 'not MP4'} → mp4`);
+    }
+    if (isMp4 && moov === 'end')
+        done.push('moov moved to the front');
+    let written;
+    try {
+        written = await rewrite(filePath, install ? outputPath : null, ffmpegPath, args, timeoutOf(options, probe));
+    }
+    catch (err) {
+        options.logger?.error({ err, filePath }, `pulsevault web-ready: ${action === 'remuxed' ? 'remux' : 'conversion'} failed; serving original bytes`);
+        return { action: 'skipped', reason: `${action === 'remuxed' ? 'remux' : 'conversion'} failed: ${failureOf(err)}` };
+    }
+    const reason = action === 'remuxed' ? 'moov was at end of file; remuxed to faststart' : `${done.join('; ')} (+faststart)`;
+    return { action, reason, ...(written !== filePath ? { outputPath: written } : {}) };
+}
+/** The longest default run: the default is computed from the upload's own (untrusted) metadata. */
+const MAX_DEFAULT_TIMEOUT_SECONDS = 3600;
+/** The wall-clock limit for one run over this video, in ms. */
+function timeoutOf(options, probe) {
+    const computed = probe.durationSeconds !== null ? 60 + 10 * workSeconds(probe) : MAX_DEFAULT_TIMEOUT_SECONDS;
+    const seconds = options.timeoutSeconds ??
+        (Number.isFinite(computed) ? Math.min(computed, MAX_DEFAULT_TIMEOUT_SECONDS) : MAX_DEFAULT_TIMEOUT_SECONDS);
+    return Math.max(1, Math.round(seconds * 1000));
+}
+/**
+ * The video's duration in seconds of 1080p30, the work of a conversion: a second of 4K at
+ * 120 fps (an iPhone recording) decodes and scales 16 times the pixels of a 1080p30 second.
+ */
+function workSeconds(probe) {
+    const { width, height, frameRate } = probe.video;
+    const pixelRate = width * height * (frameRate ?? 30);
+    return (probe.durationSeconds ?? 0) * Math.max(1, pixelRate / (1920 * 1080 * 30));
 }
 //# sourceMappingURL=web-ready.js.map