flowviant 0.125.22 → 0.125.23

package/bin/lib/videoEncode.mjs

@@ -0,0 +1,406 @@
+/**
+ * THE VIDEO KIND'S FILE FORMATS, IN PLAIN BYTES (2026-10-26, the video kind).
+ *
+ * The render tool (videoRender.mjs) photographs an animation page frame by
+ * frame in the machine's own browser. What turns those frames into the file a
+ * card hands back lives here, with no dependency and no I/O:
+ *
+ *  · `decodePng` — the browser's screenshots (8-bit RGB or RGBA, never
+ *    interlaced) into pixels;
+ *  · `createGifEncoder` — a looping GIF89a: each frame cropped to what changed
+ *    since the last one, its own colour table (the exact colours when there
+ *    are at most 256, else a median cut), LZW-coded;
+ *  · `muxMp4` / `muxWebm` — the H.264 or VP9 chunks the browser's own
+ *    WebCodecs encoder produced, in a progressive MP4 (moov first) or a WebM
+ *    with a duration and cues, so a <video> knows how long it is and can seek.
+ *
+ * MEASURED, not assumed (2026-10-26, Chrome 149 and its headless shell, Linux):
+ * WebCodecs encodes `avc1.42001f`, `avc1.640028`, `vp09.00.10.08` and `vp8`
+ * with exact timestamps, and H.264 output carries its `avcC` record as the
+ * decoder config's description. No ffmpeg was on the machine; none is needed.
+ */
+
+import { inflateSync } from 'node:zlib';
+
+const PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+
+/** A PNG the browser wrote → `{ width, height, channels, data }` (RGB or RGBA
+ *  bytes, row-major). Throws in words on anything else. */
+export function decodePng(bytes) {
+  const buf = Buffer.from(bytes);
+  if (buf.length < 33 || !buf.subarray(0, 8).equals(PNG_SIGNATURE)) throw new Error('the frame is not a PNG');
+  let width = 0, height = 0, depth = 0, type = -1, interlace = 0;
+  const idat = [];
+  for (let at = 8; at + 8 <= buf.length;) {
+    const length = buf.readUInt32BE(at), kind = buf.toString('latin1', at + 4, at + 8);
+    const body = buf.subarray(at + 8, at + 8 + length);
+    if (kind === 'IHDR') {
+      width = body.readUInt32BE(0); height = body.readUInt32BE(4);
+      depth = body[8]; type = body[9]; interlace = body[12];
+    } else if (kind === 'IDAT') idat.push(body);
+    else if (kind === 'IEND') break;
+    at += 12 + length;
+  }
+  const channels = type === 2 ? 3 : type === 6 ? 4 : 0;
+  if (depth !== 8 || !channels || interlace) throw new Error(`the frame PNG is an unsupported layout (depth ${depth}, colour type ${type}, interlace ${interlace})`);
+  const raw = inflateSync(Buffer.concat(idat));
+  const stride = width * channels;
+  if (raw.length < height * (stride + 1)) throw new Error('the frame PNG is truncated');
+  const data = Buffer.alloc(height * stride);
+  for (let y = 0; y < height; y++) {
+    const filter = raw[y * (stride + 1)];
+    const src = y * (stride + 1) + 1, row = y * stride, prev = row - stride;
+    for (let x = 0; x < stride; x++) {
+      const a = x >= channels ? data[row + x - channels] : 0;
+      const b = y > 0 ? data[prev + x] : 0;
+      const c = x >= channels && y > 0 ? data[prev + x - channels] : 0;
+      let v = raw[src + x];
+      if (filter === 1) v += a;
+      else if (filter === 2) v += b;
+      else if (filter === 3) v += (a + b) >> 1;
+      else if (filter === 4) {
+        const p = a + b - c, pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);
+        v += pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+      } else if (filter !== 0) throw new Error(`the frame PNG uses unknown filter ${filter}`);
+      data[row + x] = v & 255;
+    }
+  }
+  return { width, height, channels, data };
+}
+
+/** Pixels of any channel count → packed RGB (alpha composited over white,
+ *  which is what an opaque GIF or video frame shows). */
+export function toRgb({ width, height, channels, data }) {
+  if (channels === 3) return { width, height, rgb: data };
+  const rgb = Buffer.alloc(width * height * 3);
+  for (let i = 0, j = 0; i < data.length; i += 4, j += 3) {
+    const a = data[i + 3];
+    rgb[j] = (data[i] * a + 255 * (255 - a)) / 255;
+    rgb[j + 1] = (data[i + 1] * a + 255 * (255 - a)) / 255;
+    rgb[j + 2] = (data[i + 2] * a + 255 * (255 - a)) / 255;
+  }
+  return { width, height, rgb };
+}
+
+// ── GIF ──────────────────────────────────────────────────────────────────
+
+/** The colour table and the index of every pixel of one RGB region: its exact
+ *  colours when it has 256 or fewer, otherwise a median cut of its 15-bit
+ *  histogram (no dithering — these are drawn animations, and dither noise
+ *  would only grow the file). */
+export function quantize(rgb) {
+  const count = rgb.length / 3;
+  const exact = new Map();
+  for (let i = 0; i < rgb.length && exact.size <= 256; i += 3) {
+    const key = (rgb[i] << 16) | (rgb[i + 1] << 8) | rgb[i + 2];
+    if (!exact.has(key)) exact.set(key, exact.size);
+  }
+  const indices = new Uint8Array(count);
+  if (exact.size <= 256) {
+    const palette = Buffer.alloc(exact.size * 3);
+    for (const [key, i] of exact) { palette[i * 3] = key >> 16; palette[i * 3 + 1] = (key >> 8) & 255; palette[i * 3 + 2] = key & 255; }
+    for (let i = 0, p = 0; p < count; i += 3, p++) indices[p] = exact.get((rgb[i] << 16) | (rgb[i + 1] << 8) | rgb[i + 2]);
+    return { palette, indices };
+  }
+  const hist = new Uint32Array(32768);
+  for (let i = 0; i < rgb.length; i += 3) hist[((rgb[i] >> 3) << 10) | ((rgb[i + 1] >> 3) << 5) | (rgb[i + 2] >> 3)]++;
+  let bins = [];
+  for (let b = 0; b < 32768; b++) if (hist[b]) bins.push(b);
+  const channel = (b, c) => (c === 0 ? b >> 10 : c === 1 ? (b >> 5) & 31 : b & 31);
+  const boxes = [bins];
+  while (boxes.length < 256) {
+    // Split the box with the widest channel range (weighted by population).
+    let best = -1, bestScore = 0, bestChannel = 0;
+    boxes.forEach((box, i) => {
+      if (box.length < 2) return;
+      for (let c = 0; c < 3; c++) {
+        let lo = 31, hi = 0, n = 0;
+        for (const b of box) { const v = channel(b, c); if (v < lo) lo = v; if (v > hi) hi = v; n += hist[b]; }
+        const score = (hi - lo) * Math.sqrt(n);
+        if (score > bestScore) { bestScore = score; best = i; bestChannel = c; }
+      }
+    });
+    if (best < 0) break;
+    const box = boxes[best].sort((x, y) => channel(x, bestChannel) - channel(y, bestChannel));
+    let half = 0, total = 0;
+    for (const b of box) total += hist[b];
+    let cut = 0;
+    for (; cut < box.length - 1; cut++) { half += hist[box[cut]]; if (half * 2 >= total) break; }
+    // Both halves keep a bin: a box whose weight sits in its LAST bin (one
+    // anti-aliased shape on a white page) ran the loop out and split into
+    // itself and an empty box, again and again — a palette of 256 empty boxes
+    // and one colour, measured on a real render.
+    cut = Math.min(cut, box.length - 2);
+    boxes.splice(best, 1, box.slice(0, cut + 1), box.slice(cut + 1));
+  }
+  const boxOf = new Uint8Array(32768);
+  const palette = Buffer.alloc(boxes.length * 3);
+  const sums = boxes.map(() => [0, 0, 0, 0]);
+  boxes.forEach((box, i) => { for (const b of box) boxOf[b] = i; });
+  for (let i = 0; i < rgb.length; i += 3) {
+    const s = sums[boxOf[((rgb[i] >> 3) << 10) | ((rgb[i + 1] >> 3) << 5) | (rgb[i + 2] >> 3)]];
+    s[0] += rgb[i]; s[1] += rgb[i + 1]; s[2] += rgb[i + 2]; s[3]++;
+  }
+  sums.forEach(([r, g, b, n], i) => { palette[i * 3] = n ? Math.round(r / n) : 0; palette[i * 3 + 1] = n ? Math.round(g / n) : 0; palette[i * 3 + 2] = n ? Math.round(b / n) : 0; });
+  for (let i = 0, p = 0; p < count; i += 3, p++) indices[p] = boxOf[((rgb[i] >> 3) << 10) | ((rgb[i + 1] >> 3) << 5) | (rgb[i + 2] >> 3)];
+  return { palette, indices };
+}
+
+/** GIF's LZW over `indices` at `minCodeSize`, packed LSB-first into 255-byte
+ *  sub-blocks and terminated. The code-size step follows the decoder's
+ *  (omggif's encoder, which every browser reads). */
+export function lzwEncode(indices, minCodeSize) {
+  const clear = 1 << minCodeSize, eoi = clear + 1;
+  const table = new Map();
+  let codeSize = minCodeSize + 1, next = eoi + 1;
+  const out = [];
+  let acc = 0, bits = 0;
+  const emit = (code) => {
+    acc |= code << bits; bits += codeSize;
+    while (bits >= 8) { out.push(acc & 255); acc >>>= 8; bits -= 8; }
+  };
+  emit(clear);
+  let prefix = indices[0];
+  for (let i = 1; i < indices.length; i++) {
+    const k = indices[i];
+    const key = (prefix << 8) | k;
+    const hit = table.get(key);
+    if (hit !== undefined) { prefix = hit; continue; }
+    emit(prefix);
+    if (next === 4096) {
+      emit(clear);
+      next = eoi + 1; codeSize = minCodeSize + 1; table.clear();
+    } else {
+      if (next >= 1 << codeSize) codeSize++;
+      table.set(key, next++);
+    }
+    prefix = k;
+  }
+  emit(prefix);
+  emit(eoi);
+  if (bits > 0) out.push(acc & 255);
+  const blocks = [];
+  for (let i = 0; i < out.length; i += 255) {
+    const part = out.slice(i, i + 255);
+    blocks.push(part.length, ...part);
+  }
+  blocks.push(0);
+  return Buffer.from(blocks);
+}
+
+/**
+ * A looping GIF, frame by frame: `add(rgb, delayCs)` takes one full frame's
+ * packed RGB and how long it shows (centiseconds); `finish()` returns the
+ * file. A frame identical to the one before lengthens it instead of adding
+ * one; any other frame is cropped to the rectangle that changed and drawn
+ * over the last (disposal 1). `bytes()` is the size so far, so a caller can
+ * stop at a ceiling rather than build a file it will refuse.
+ */
+export function createGifEncoder(width, height) {
+  const parts = [];
+  let size = 0;
+  const push = (b) => { parts.push(b); size += b.length; };
+  const head = Buffer.alloc(13);
+  head.write('GIF89a', 0, 'latin1');
+  head.writeUInt16LE(width, 6); head.writeUInt16LE(height, 8);
+  head[10] = 0; head[11] = 0; head[12] = 0; // no global table
+  push(head);
+  // NETSCAPE2.0: loop forever.
+  push(Buffer.from([0x21, 0xff, 0x0b, ...Buffer.from('NETSCAPE2.0', 'latin1'), 0x03, 0x01, 0x00, 0x00, 0x00]));
+  let previous = null;
+  let pending = null; // { image: Buffer, delay }
+  const flush = () => {
+    if (!pending) return;
+    const { x, y, w, h, rgb } = pending.region;
+    const { palette, indices } = quantize(rgb);
+    let bitsPer = 1;
+    while (1 << bitsPer < palette.length / 3) bitsPer++;
+    const tableSize = 1 << bitsPer;
+    const gce = Buffer.from([0x21, 0xf9, 0x04, 0x04, pending.delay & 255, pending.delay >> 8, 0, 0]);
+    const desc = Buffer.alloc(10);
+    desc[0] = 0x2c;
+    desc.writeUInt16LE(x, 1); desc.writeUInt16LE(y, 3); desc.writeUInt16LE(w, 5); desc.writeUInt16LE(h, 7);
+    desc[9] = 0x80 | (bitsPer - 1); // local colour table
+    const table = Buffer.alloc(tableSize * 3);
+    palette.copy(table);
+    push(gce); push(desc); push(table);
+    push(Buffer.from([Math.max(2, bitsPer)]));
+    push(lzwEncode(indices, Math.max(2, bitsPer)));
+    pending = null;
+  };
+  return {
+    add(rgb, delayCs) {
+      if (rgb.length !== width * height * 3) throw new Error('a GIF frame is the wrong size');
+      const delay = Math.max(1, Math.min(65535, Math.round(delayCs)));
+      let x0 = 0, y0 = 0, x1 = width - 1, y1 = height - 1;
+      if (previous) {
+        x0 = width; y0 = height; x1 = -1; y1 = -1;
+        for (let y = 0; y < height; y++) {
+          for (let x = 0; x < width; x++) {
+            const i = (y * width + x) * 3;
+            if (rgb[i] !== previous[i] || rgb[i + 1] !== previous[i + 1] || rgb[i + 2] !== previous[i + 2]) {
+              if (x < x0) x0 = x; if (x > x1) x1 = x; if (y < y0) y0 = y; if (y > y1) y1 = y;
+            }
+          }
+        }
+        if (x1 < 0) { pending.delay = Math.min(65535, pending.delay + delay); return; }
+      }
+      flush();
+      const w = x1 - x0 + 1, h = y1 - y0 + 1;
+      const region = Buffer.alloc(w * h * 3);
+      for (let y = 0; y < h; y++) rgb.copy(region, y * w * 3, ((y0 + y) * width + x0) * 3, ((y0 + y) * width + x1 + 1) * 3);
+      pending = { region: { x: x0, y: y0, w, h, rgb: region }, delay };
+      previous = Buffer.from(rgb);
+    },
+    bytes: () => size,
+    finish() {
+      flush();
+      push(Buffer.from([0x3b]));
+      return Buffer.concat(parts);
+    },
+  };
+}
+
+// ── MP4 (H.264) ──────────────────────────────────────────────────────────
+
+const u8 = (n) => Buffer.from([n & 255]);
+const u16 = (n) => { const b = Buffer.alloc(2); b.writeUInt16BE(n); return b; };
+const u32 = (n) => { const b = Buffer.alloc(4); b.writeUInt32BE(n >>> 0); return b; };
+const box = (type, ...body) => {
+  const content = Buffer.concat(body);
+  return Buffer.concat([u32(content.length + 8), Buffer.from(type, 'latin1'), content]);
+};
+const fullBox = (type, version, flags, ...body) => box(type, u8(version), u8(flags >> 16), u16(flags & 0xffff), ...body);
+const MATRIX = Buffer.concat([0x00010000, 0, 0, 0, 0x00010000, 0, 0, 0, 0x40000000].map(u32));
+
+/**
+ * One H.264 track in a progressive MP4 (moov before mdat). `chunks` are
+ * WebCodecs output in order — `{ key, timestamp (µs), duration (µs), data }`
+ * with length-prefixed NAL units (`avc: { format: 'avc' }`) — and
+ * `description` the decoder config's avcC record.
+ */
+export function muxMp4({ width, height, description, chunks }) {
+  if (!description?.length) throw new Error('the H.264 encoder supplied no avcC description');
+  if (!chunks.length) throw new Error('the encoder produced no frames');
+  const timescale = 1_000_000;
+  const durations = chunks.map((c, i) => Math.max(1, Math.round(c.duration ?? ((chunks[i + 1]?.timestamp ?? c.timestamp) - c.timestamp)) || 1));
+  const total = durations.reduce((a, b) => a + b, 0);
+  const movieMs = Math.round(total / 1000);
+  const stts = [];
+  for (const d of durations) {
+    if (stts.length && stts.at(-1)[1] === d) stts.at(-1)[0]++;
+    else stts.push([1, d]);
+  }
+  const keys = chunks.map((c, i) => (c.key ? i + 1 : 0)).filter(Boolean);
+  const build = (mdatOffset) => {
+    const avc1 = box('avc1',
+      Buffer.alloc(6), u16(1), Buffer.alloc(16), u16(width), u16(height),
+      u32(0x00480000), u32(0x00480000), u32(0), u16(1), Buffer.alloc(32), u16(0x0018), u16(0xffff),
+      box('avcC', Buffer.from(description)));
+    const stbl = box('stbl',
+      fullBox('stsd', 0, 0, u32(1), avc1),
+      fullBox('stts', 0, 0, u32(stts.length), ...stts.flatMap(([n, d]) => [u32(n), u32(d)])),
+      fullBox('stss', 0, 0, u32(keys.length), ...keys.map(u32)),
+      fullBox('stsc', 0, 0, u32(1), u32(1), u32(chunks.length), u32(1)),
+      fullBox('stsz', 0, 0, u32(0), u32(chunks.length), ...chunks.map((c) => u32(c.data.length))),
+      fullBox('stco', 0, 0, u32(1), u32(mdatOffset)));
+    const minf = box('minf',
+      fullBox('vmhd', 0, 1, u16(0), u16(0), u16(0), u16(0)),
+      box('dinf', fullBox('dref', 0, 0, u32(1), fullBox('url ', 0, 1))),
+      stbl);
+    const mdia = box('mdia',
+      fullBox('mdhd', 0, 0, u32(0), u32(0), u32(timescale), u32(total), u16(0x55c4), u16(0)),
+      fullBox('hdlr', 0, 0, u32(0), Buffer.from('vide', 'latin1'), Buffer.alloc(12), Buffer.from('VideoHandler\0', 'latin1')),
+      minf);
+    const trak = box('trak',
+      fullBox('tkhd', 0, 3, u32(0), u32(0), u32(1), u32(0), u32(movieMs), Buffer.alloc(8), u16(0), u16(0), u16(0), u16(0), MATRIX, u32(width * 65536), u32(height * 65536)),
+      mdia);
+    const mvhd = fullBox('mvhd', 0, 0, u32(0), u32(0), u32(1000), u32(movieMs), u32(0x00010000), u16(0x0100), Buffer.alloc(10), MATRIX, Buffer.alloc(24), u32(2));
+    return box('moov', mvhd, trak);
+  };
+  const ftyp = box('ftyp', Buffer.from('isom', 'latin1'), u32(0x200), Buffer.from('isomiso2avc1mp41', 'latin1'));
+  const sizing = build(0);
+  const moov = build(ftyp.length + sizing.length + 8);
+  const payload = Buffer.concat(chunks.map((c) => Buffer.from(c.data)));
+  return Buffer.concat([ftyp, moov, u32(payload.length + 8), Buffer.from('mdat', 'latin1'), payload]);
+}
+
+// ── WebM (VP9 / VP8) ─────────────────────────────────────────────────────
+
+const ebmlSize = (n) => {
+  for (let len = 1; len <= 8; len++) {
+    if (n < 2 ** (7 * len) - 1) {
+      const b = Buffer.alloc(len);
+      let v = n;
+      for (let i = len - 1; i >= 0; i--) { b[i] = v % 256; v = Math.floor(v / 256); }
+      b[0] |= 0x80 >> (len - 1);
+      return b;
+    }
+  }
+  throw new Error('an EBML element is too large');
+};
+const idBytes = (id) => { const hex = id.toString(16); return Buffer.from(hex.length % 2 ? `0${hex}` : hex, 'hex'); };
+const el = (id, ...body) => { const content = Buffer.concat(body); return Buffer.concat([idBytes(id), ebmlSize(content.length), content]); };
+const uint = (n, width = 0) => {
+  const bytes = [];
+  let v = n;
+  do { bytes.unshift(v % 256); v = Math.floor(v / 256); } while (v > 0);
+  while (bytes.length < width) bytes.unshift(0);
+  return Buffer.from(bytes);
+};
+const float64 = (n) => { const b = Buffer.alloc(8); b.writeDoubleBE(n); return b; };
+const str = (s) => Buffer.from(s, 'latin1');
+
+/**
+ * One video track in a WebM, with its duration, a cluster per keyframe and
+ * the cues that point at them (so a player can seek). `codec` is
+ * `'V_VP9'` or `'V_VP8'`; `chunks` as for `muxMp4`, timestamps in µs.
+ */
+export function muxWebm({ width, height, codec = 'V_VP9', chunks }) {
+  if (!chunks.length) throw new Error('the encoder produced no frames');
+  const last = chunks.at(-1);
+  const durationMs = (last.timestamp + (last.duration ?? 0)) / 1000;
+  const header = el(0x1a45dfa3, el(0x4286, uint(1)), el(0x42f7, uint(1)), el(0x42f2, uint(4)), el(0x42f3, uint(8)),
+    el(0x4282, str('webm')), el(0x4287, uint(4)), el(0x4285, uint(2)));
+  const info = el(0x1549a966, el(0x2ad7b1, uint(1_000_000)), el(0x4d80, str('flowviant')), el(0x5741, str('flowviant')), el(0x4489, float64(durationMs)));
+  const tracks = el(0x1654ae6b, el(0xae, el(0xd7, uint(1)), el(0x73c5, uint(1)), el(0x83, uint(1)), el(0x86, str(codec)), el(0x9c, uint(0)),
+    el(0xe0, el(0xb0, uint(width)), el(0xba, uint(height)))));
+  // A new cluster at every keyframe, and before a block's offset from its
+  // cluster could leave a signed 16-bit millisecond.
+  const clusters = [];
+  for (const c of chunks) {
+    const ms = Math.round(c.timestamp / 1000);
+    const open = clusters.at(-1);
+    if (!open || c.key || ms - open.start > 30_000) clusters.push({ start: ms, blocks: [] });
+    const at = clusters.at(-1);
+    const rel = Buffer.alloc(2); rel.writeInt16BE(ms - at.start);
+    at.blocks.push(el(0xa3, Buffer.from([0x81]), rel, u8(c.key ? 0x80 : 0), Buffer.from(c.data)));
+  }
+  const clusterBytes = clusters.map((c) => el(0x1f43b675, el(0xe7, uint(c.start)), ...c.blocks));
+  // SeekHead with fixed-width positions, so its size does not depend on them.
+  const seek = (id, pos) => el(0x4dbb, el(0x53ab, idBytes(id)), el(0x53ac, uint(pos, 8)));
+  const seekHeadFor = (infoPos, tracksPos, cuesPos) => el(0x114d9b74, seek(0x1549a966, infoPos), seek(0x1654ae6b, tracksPos), seek(0x1c53bb6b, cuesPos));
+  const seekLength = seekHeadFor(0, 0, 0).length;
+  const infoPos = seekLength, tracksPos = infoPos + info.length;
+  let clusterPos = tracksPos + tracks.length;
+  const cuePoints = clusters.map((c, i) => {
+    const point = el(0xbb, el(0xb3, uint(c.start)), el(0xb7, el(0xf7, uint(1)), el(0xf1, uint(clusterPos))));
+    clusterPos += clusterBytes[i].length;
+    return point;
+  });
+  const cues = el(0x1c53bb6b, ...cuePoints);
+  const segmentBody = Buffer.concat([seekHeadFor(infoPos, tracksPos, clusterPos), info, tracks, ...clusterBytes, cues]);
+  return Buffer.concat([header, idBytes(0x18538067), ebmlSize(segmentBody.length), segmentBody]);
+}
+
+// ── What a delivered file must look like ────────────────────────────────
+
+/** The container the bytes are, by their own header: 'gif', 'mp4', 'webm'
+ *  or null. A file whose name and bytes disagree is not a delivery. */
+export function sniffVideo(bytes) {
+  const b = Buffer.from(bytes);
+  if (b.length >= 6 && /^GIF8[79]a$/.test(b.toString('latin1', 0, 6))) return 'gif';
+  if (b.length >= 12 && b.toString('latin1', 4, 8) === 'ftyp') return 'mp4';
+  if (b.length >= 4 && b.readUInt32BE(0) === 0x1a45dfa3) return 'webm';
+  return null;
+}