@crewhaus/tool-media 0.7.0

package/dist/lib/diagram.js

@@ -0,0 +1,256 @@
+/**
+ * Box-and-arrow diagrams from a node and edge list, laid out in layers.
+ *
+ * ## The layout, and why it is this one
+ *
+ * Each node is assigned to a layer one past its deepest predecessor, and
+ * layers are drawn in order — downward for `TB`, rightward for `LR`. Within
+ * a layer, nodes keep the order they were declared in. That is the whole
+ * algorithm: no force simulation, no crossing minimisation, no iteration.
+ * It is reproducible to the byte, it fits in a sentence, and it is right
+ * for the pipelines, state machines and architecture sketches this is for.
+ *
+ * It is NOT general graph layout, and does not pretend to be. A dense graph
+ * will have crossing edges and this will not untangle them. A cycle is
+ * broken by ignoring the edge that closes it when layers are assigned; that
+ * edge is still drawn — dashed, curving back — and is reported in
+ * `backEdges`, so a caller can see what happened rather than wonder why the
+ * picture looks the way it does.
+ */
+import { MediaFormatError } from "./bytes";
+import { escapeXml, estimateTextWidth, num, rect, svgDocument, text } from "./svg";
+const FONT = 13;
+const PADDING_X = 14;
+const BOX_HEIGHT = 40;
+const LAYER_GAP = 60;
+const SIBLING_GAP = 24;
+const MARGIN = 24;
+const TITLE_SIZE = 16;
+const INK = "#1f2329";
+const EDGE = "#5a6069";
+const key = (from, to) => `${from} -> ${to}`;
+/**
+ * Layer assignment. A depth-first pass in declaration order finds the edges
+ * that close a cycle; the rest form a DAG, and each node's layer is one
+ * past its deepest remaining predecessor.
+ */
+export function assignLayers(nodes, edges) {
+    const ids = nodes.map((n) => n.id);
+    const known = new Set(ids);
+    const outgoing = new Map();
+    for (const id of ids)
+        outgoing.set(id, []);
+    for (const edge of edges) {
+        if (known.has(edge.from) && known.has(edge.to)) {
+            outgoing.get(edge.from).push(edge.to);
+        }
+    }
+    const backEdges = [];
+    const backSet = new Set();
+    const state = new Map();
+    for (const id of ids)
+        state.set(id, 0);
+    // Iterative depth-first search: a deep chain must not overflow the stack.
+    for (const root of ids) {
+        if (state.get(root) !== 0)
+            continue;
+        const stack = [{ id: root, next: 0 }];
+        state.set(root, 1);
+        while (stack.length > 0) {
+            const frame = stack[stack.length - 1];
+            const children = outgoing.get(frame.id);
+            if (frame.next >= children.length) {
+                state.set(frame.id, 2);
+                stack.pop();
+                continue;
+            }
+            const child = children[frame.next];
+            frame.next++;
+            const seen = state.get(child);
+            if (seen === 1) {
+                const k = key(frame.id, child);
+                if (!backSet.has(k)) {
+                    backSet.add(k);
+                    backEdges.push({ from: frame.id, to: child });
+                }
+            }
+            else if (seen === 0) {
+                state.set(child, 1);
+                stack.push({ id: child, next: 0 });
+            }
+        }
+    }
+    const incoming = new Map();
+    for (const id of ids)
+        incoming.set(id, []);
+    for (const edge of edges) {
+        if (!known.has(edge.from) || !known.has(edge.to))
+            continue;
+        if (backSet.has(key(edge.from, edge.to)))
+            continue;
+        incoming.get(edge.to).push(edge.from);
+    }
+    // Longest path to each node, memoised. The graph is acyclic now, so the
+    // recursion terminates; `resolving` is a belt-and-braces guard.
+    const layers = new Map();
+    const resolving = new Set();
+    const depth = (id) => {
+        const cached = layers.get(id);
+        if (cached !== undefined)
+            return cached;
+        if (resolving.has(id))
+            return 0;
+        resolving.add(id);
+        let best = 0;
+        for (const parent of incoming.get(id))
+            best = Math.max(best, depth(parent) + 1);
+        resolving.delete(id);
+        layers.set(id, best);
+        return best;
+    };
+    for (const id of ids)
+        depth(id);
+    return { layers, backEdges };
+}
+/** Render a node and edge list to SVG with a layered layout. */
+export function renderDiagram(spec) {
+    if (spec.nodes.length === 0)
+        throw new MediaFormatError("a diagram needs at least one node");
+    if (spec.nodes.length > 200) {
+        throw new MediaFormatError(`${spec.nodes.length} nodes is past what a layered layout renders readably; the cap is 200`);
+    }
+    const seen = new Set();
+    for (const node of spec.nodes) {
+        if (node.id === "")
+            throw new MediaFormatError("a node id cannot be empty");
+        if (seen.has(node.id))
+            throw new MediaFormatError(`node id "${node.id}" appears twice`);
+        seen.add(node.id);
+    }
+    for (const edge of spec.edges) {
+        if (!seen.has(edge.from))
+            throw new MediaFormatError(`edge from unknown node "${edge.from}"`);
+        if (!seen.has(edge.to))
+            throw new MediaFormatError(`edge to unknown node "${edge.to}"`);
+    }
+    const direction = spec.direction ?? "TB";
+    const { layers, backEdges } = assignLayers(spec.nodes, spec.edges);
+    const labelOf = (node) => node.label ?? node.id;
+    // One box width for every node, so layers line up and edges stay short.
+    const boxWidth = Math.ceil(Math.max(64, ...spec.nodes.map((n) => estimateTextWidth(labelOf(n), FONT) + PADDING_X * 2)));
+    const maxLayer = Math.max(...[...layers.values()]);
+    const byLayer = Array.from({ length: maxLayer + 1 }, () => []);
+    for (const node of spec.nodes) {
+        byLayer[layers.get(node.id)].push(node);
+    }
+    const widest = Math.max(...byLayer.map((row) => row.length));
+    const titleOffset = spec.title === undefined ? 0 : TITLE_SIZE + 14;
+    // A back edge loops outside the boxes; reserve the room up front.
+    const loopRoom = backEdges.length > 0 ? 34 : 0;
+    const boxes = new Map();
+    let width;
+    let height;
+    if (direction === "TB") {
+        const rowSpan = widest * boxWidth + (widest - 1) * SIBLING_GAP;
+        width = rowSpan + MARGIN * 2 + loopRoom;
+        height = titleOffset + (maxLayer + 1) * BOX_HEIGHT + maxLayer * LAYER_GAP + MARGIN * 2;
+        const centre = MARGIN + rowSpan / 2;
+        for (let layer = 0; layer <= maxLayer; layer++) {
+            const row = byLayer[layer];
+            const span = row.length * boxWidth + (row.length - 1) * SIBLING_GAP;
+            let x = centre - span / 2;
+            const y = MARGIN + titleOffset + layer * (BOX_HEIGHT + LAYER_GAP);
+            for (const node of row) {
+                boxes.set(node.id, { x, y, w: boxWidth, h: BOX_HEIGHT });
+                x += boxWidth + SIBLING_GAP;
+            }
+        }
+    }
+    else {
+        width = (maxLayer + 1) * boxWidth + maxLayer * LAYER_GAP + MARGIN * 2;
+        const columnSpan = widest * BOX_HEIGHT + (widest - 1) * SIBLING_GAP;
+        height = columnSpan + MARGIN * 2 + titleOffset + loopRoom;
+        const centre = MARGIN + titleOffset + loopRoom + columnSpan / 2;
+        for (let layer = 0; layer <= maxLayer; layer++) {
+            const column = byLayer[layer];
+            const span = column.length * BOX_HEIGHT + (column.length - 1) * SIBLING_GAP;
+            let y = centre - span / 2;
+            const x = MARGIN + layer * (boxWidth + LAYER_GAP);
+            for (const node of column) {
+                boxes.set(node.id, { x, y, w: boxWidth, h: BOX_HEIGHT });
+                y += BOX_HEIGHT + SIBLING_GAP;
+            }
+        }
+    }
+    const background = spec.background ?? "#ffffff";
+    const fill = spec.nodeFill ?? "#eef2fb";
+    const stroke = spec.nodeStroke ?? "#3b6fd4";
+    const body = [
+        `<defs><marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M 0 0 L 10 5 L 0 10 z" fill="${escapeXml(EDGE)}"/></marker></defs>`,
+    ];
+    if (spec.title !== undefined) {
+        body.push(text(width / 2, MARGIN + TITLE_SIZE - 4, spec.title, TITLE_SIZE, {
+            fill: INK,
+            anchor: "middle",
+            weight: "bold",
+        }));
+    }
+    const backSet = new Set(backEdges.map((e) => key(e.from, e.to)));
+    // Edges first, so a box always sits on top of the line that reaches it.
+    for (const edge of spec.edges) {
+        const from = boxes.get(edge.from);
+        const to = boxes.get(edge.to);
+        const isBack = backSet.has(key(edge.from, edge.to));
+        const forward = layers.get(edge.to) > layers.get(edge.from);
+        let path;
+        let midX;
+        let midY;
+        if (forward) {
+            const [x1, y1] = direction === "TB"
+                ? [from.x + from.w / 2, from.y + from.h]
+                : [from.x + from.w, from.y + from.h / 2];
+            const [x2, y2] = direction === "TB" ? [to.x + to.w / 2, to.y] : [to.x, to.y + to.h / 2];
+            path = `M ${num(x1)} ${num(y1)} L ${num(x2)} ${num(y2)}`;
+            midX = (x1 + x2) / 2;
+            midY = (y1 + y2) / 2;
+        }
+        else {
+            // Back or sideways: leave and enter on the outside edge, bowing away
+            // from the boxes so the line is followable.
+            const [x1, y1] = direction === "TB"
+                ? [from.x + from.w, from.y + from.h / 2]
+                : [from.x + from.w / 2, from.y + from.h];
+            const [x2, y2] = direction === "TB" ? [to.x + to.w, to.y + to.h / 2] : [to.x + to.w / 2, to.y + to.h];
+            const bow = 28;
+            const [cx, cy] = direction === "TB"
+                ? [Math.max(x1, x2) + bow, (y1 + y2) / 2]
+                : [(x1 + x2) / 2, Math.max(y1, y2) + bow];
+            path = `M ${num(x1)} ${num(y1)} Q ${num(cx)} ${num(cy)} ${num(x2)} ${num(y2)}`;
+            // The midpoint of a quadratic at t = 0.5.
+            midX = 0.25 * x1 + 0.5 * cx + 0.25 * x2;
+            midY = 0.25 * y1 + 0.5 * cy + 0.25 * y2;
+        }
+        body.push(`<path d="${path}" fill="none" stroke="${escapeXml(EDGE)}" stroke-width="1.5"${isBack ? ' stroke-dasharray="5 3"' : ""} marker-end="url(#arrow)"/>`);
+        if (edge.label !== undefined && edge.label !== "") {
+            const w = estimateTextWidth(edge.label, 11) + 8;
+            body.push(rect(midX - w / 2, midY - 8, w, 16, background, 'rx="3"'));
+            body.push(text(midX, midY, edge.label, 11, { fill: EDGE, anchor: "middle", baseline: "middle" }));
+        }
+    }
+    for (const node of spec.nodes) {
+        const box = boxes.get(node.id);
+        body.push(`<rect x="${num(box.x)}" y="${num(box.y)}" width="${num(box.w)}" height="${num(box.h)}" rx="6" fill="${escapeXml(fill)}" stroke="${escapeXml(stroke)}" stroke-width="1.5"/>`);
+        body.push(text(box.x + box.w / 2, box.y + box.h / 2, labelOf(node), FONT, {
+            fill: INK,
+            anchor: "middle",
+            baseline: "middle",
+        }));
+    }
+    return {
+        svg: svgDocument(width, height, background, body, spec.title),
+        width,
+        height,
+        layers: spec.nodes.map((n) => ({ id: n.id, layer: layers.get(n.id) })),
+        backEdges,
+    };
+}

package/dist/lib/ffprobe.d.ts

@@ -0,0 +1,36 @@
+export type ProbeStream = {
+    readonly index: number;
+    readonly type: string;
+    readonly codec?: string;
+    readonly codecDescription?: string;
+    readonly profile?: string;
+    readonly width?: number;
+    readonly height?: number;
+    readonly frameRate?: number;
+    readonly pixelFormat?: string;
+    readonly sampleRateHz?: number;
+    readonly channels?: number;
+    readonly channelLayout?: string;
+    readonly bitRateBps?: number;
+    readonly durationSeconds?: number;
+    readonly language?: string;
+    readonly title?: string;
+};
+export type ProbeResult = {
+    readonly formatName?: string;
+    readonly formatDescription?: string;
+    readonly durationSeconds?: number;
+    readonly sizeBytes?: number;
+    readonly bitRateBps?: number;
+    readonly streamCount: number;
+    readonly streams: ReadonlyArray<ProbeStream>;
+    /** Container-level tags worth reporting, sorted by key. */
+    readonly tags: ReadonlyArray<{
+        key: string;
+        value: string;
+    }>;
+};
+/** `"30000/1001"` to 29.97. A zero denominator means ffprobe does not know. */
+export declare function parseRate(value: unknown): number | undefined;
+/** Parse ffprobe's JSON. Throws `MediaFormatError` on anything unexpected. */
+export declare function parseProbeJson(text: string): ProbeResult;

package/dist/lib/ffprobe.js

@@ -0,0 +1,154 @@
+/**
+ * Shaping `ffprobe -print_format json` output into something worth putting
+ * in a context window.
+ *
+ * ffprobe's JSON is wide, deeply optional and full of fields that are
+ * strings when they look like numbers. This module is the pure half of
+ * `MediaProbe`: it takes the text, treats every field as absent until
+ * proven otherwise, and returns a fixed shape. It is also the security
+ * boundary — the JSON came out of a process reading a file the caller
+ * supplied, so nothing in it is trusted, and nothing is passed through
+ * except the fields named below.
+ */
+import { MediaFormatError } from "./bytes";
+/** Container tags that are worth carrying; the rest are noise or private. */
+const TAG_ALLOWLIST = [
+    "album",
+    "artist",
+    "comment",
+    "composer",
+    "date",
+    "encoder",
+    "genre",
+    "major_brand",
+    "title",
+    "track",
+];
+function asObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/** A field that ffprobe may write as a number or as a numeric string. */
+function numberField(value) {
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : undefined;
+    if (typeof value !== "string")
+        return undefined;
+    const parsed = Number.parseFloat(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+function stringField(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed === "" || trimmed === "unknown" || trimmed === "N/A")
+        return undefined;
+    // Bound it: a tag is metadata, not a payload.
+    return trimmed.length > 300 ? `${trimmed.slice(0, 300)}…` : trimmed;
+}
+/** `"30000/1001"` to 29.97. A zero denominator means ffprobe does not know. */
+export function parseRate(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const parts = value.split("/");
+    if (parts.length !== 2)
+        return numberField(value);
+    const numerator = Number.parseFloat(parts[0]);
+    const denominator = Number.parseFloat(parts[1]);
+    if (!Number.isFinite(numerator) || !Number.isFinite(denominator) || denominator === 0) {
+        return undefined;
+    }
+    return Math.round((numerator / denominator) * 1000) / 1000;
+}
+function round3(value) {
+    return Math.round(value * 1000) / 1000;
+}
+/** Parse ffprobe's JSON. Throws `MediaFormatError` on anything unexpected. */
+export function parseProbeJson(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        throw new MediaFormatError(`ffprobe did not return JSON: ${err.message}`);
+    }
+    const root = asObject(parsed);
+    if (root === undefined)
+        throw new MediaFormatError("ffprobe returned JSON that is not an object");
+    const format = asObject(root["format"]) ?? {};
+    const rawStreams = Array.isArray(root["streams"]) ? root["streams"] : [];
+    const streams = [];
+    for (const entry of rawStreams) {
+        const stream = asObject(entry);
+        if (stream === undefined)
+            continue;
+        const tags = asObject(stream["tags"]) ?? {};
+        const width = numberField(stream["width"]);
+        const height = numberField(stream["height"]);
+        const frameRate = parseRate(stream["avg_frame_rate"]) ?? parseRate(stream["r_frame_rate"]);
+        const duration = numberField(stream["duration"]);
+        const bitRate = numberField(stream["bit_rate"]);
+        streams.push({
+            index: numberField(stream["index"]) ?? streams.length,
+            type: stringField(stream["codec_type"]) ?? "unknown",
+            ...(stringField(stream["codec_name"]) !== undefined
+                ? { codec: stringField(stream["codec_name"]) }
+                : {}),
+            ...(stringField(stream["codec_long_name"]) !== undefined
+                ? { codecDescription: stringField(stream["codec_long_name"]) }
+                : {}),
+            ...(stringField(stream["profile"]) !== undefined
+                ? { profile: stringField(stream["profile"]) }
+                : {}),
+            ...(width !== undefined ? { width } : {}),
+            ...(height !== undefined ? { height } : {}),
+            ...(frameRate !== undefined && frameRate > 0 ? { frameRate } : {}),
+            ...(stringField(stream["pix_fmt"]) !== undefined
+                ? { pixelFormat: stringField(stream["pix_fmt"]) }
+                : {}),
+            ...(numberField(stream["sample_rate"]) !== undefined
+                ? { sampleRateHz: numberField(stream["sample_rate"]) }
+                : {}),
+            ...(numberField(stream["channels"]) !== undefined
+                ? { channels: numberField(stream["channels"]) }
+                : {}),
+            ...(stringField(stream["channel_layout"]) !== undefined
+                ? { channelLayout: stringField(stream["channel_layout"]) }
+                : {}),
+            ...(bitRate !== undefined ? { bitRateBps: Math.round(bitRate) } : {}),
+            ...(duration !== undefined ? { durationSeconds: round3(duration) } : {}),
+            ...(stringField(tags["language"]) !== undefined
+                ? { language: stringField(tags["language"]) }
+                : {}),
+            ...(stringField(tags["title"]) !== undefined
+                ? { title: stringField(tags["title"]) }
+                : {}),
+        });
+    }
+    const formatTags = asObject(format["tags"]) ?? {};
+    const tags = [];
+    for (const key of TAG_ALLOWLIST) {
+        const value = stringField(formatTags[key]);
+        if (value !== undefined)
+            tags.push({ key, value });
+    }
+    const duration = numberField(format["duration"]);
+    const size = numberField(format["size"]);
+    const bitRate = numberField(format["bit_rate"]);
+    return {
+        ...(stringField(format["format_name"]) !== undefined
+            ? { formatName: stringField(format["format_name"]) }
+            : {}),
+        ...(stringField(format["format_long_name"]) !== undefined
+            ? { formatDescription: stringField(format["format_long_name"]) }
+            : {}),
+        ...(duration !== undefined ? { durationSeconds: round3(duration) } : {}),
+        ...(size !== undefined ? { sizeBytes: Math.round(size) } : {}),
+        ...(bitRate !== undefined ? { bitRateBps: Math.round(bitRate) } : {}),
+        streamCount: streams.length,
+        // Sorted by index, so two probes of the same file agree on the order.
+        streams: [...streams].sort((a, b) => a.index - b.index),
+        tags,
+    };
+}

package/dist/lib/identify.d.ts

@@ -0,0 +1,39 @@
+/** A format this package can name from its magic bytes. */
+export type FileKind = {
+    /** Short, stable identifier: `"png"`, `"jpeg"`, `"mp4"`, … */
+    readonly kind: string;
+    readonly mediaType: string;
+    /** Conventional extensions, lowercase, without the dot. First is preferred. */
+    readonly extensions: ReadonlyArray<string>;
+    /** Broad family, for a caller routing on it. */
+    readonly family: "image" | "audio" | "video" | "document" | "archive" | "text" | "font";
+};
+/**
+ * Name the format from the bytes. Returns `undefined` when nothing matches,
+ * which is the honest answer — "unknown" beats a guess from the extension.
+ */
+export declare function detectKind(bytes: Uint8Array): FileKind | undefined;
+/** Every format `detectKind` can name, sorted, for a tool to report. */
+export declare function knownKinds(): ReadonlyArray<string>;
+/** Look up the kinds an extension conventionally names. */
+export declare function kindsForExtension(extension: string): ReadonlyArray<string>;
+export type ImageHeader = {
+    readonly format: string;
+    readonly width: number;
+    readonly height: number;
+    /** Bits per sample (per channel), where the format states one. */
+    readonly bitDepth?: number;
+    /** A human-readable colour model: `"rgb"`, `"palette"`, `"ycbcr"`, … */
+    readonly colorType: string;
+    readonly hasAlpha: boolean;
+    /** Anything worth saying that does not fit the fields above. */
+    readonly notes?: ReadonlyArray<string>;
+};
+/** The formats `readImageHeader` understands, in the order it tries them. */
+export declare const HEADER_FORMATS: ReadonlyArray<string>;
+/**
+ * Dimensions and colour facts from a file header alone. Throws
+ * `MediaFormatError` when the bytes are not one of `HEADER_FORMATS`, or
+ * when they are but the header is malformed or truncated.
+ */
+export declare function readImageHeader(bytes: Uint8Array): ImageHeader;