@woosh/meep-engine 3.9.0 → 3.10.0

package/src/avif/native/heif/write_avif_file.js

@@ -0,0 +1,348 @@
+import { BoxWriter } from "../isobmff/BoxWriter.js";
+import { write_item_property } from "./write_item_property.js";
+
+/**
+ * Handler type for an image file's `meta` box.
+ * @type {string}
+ */
+const HANDLER_PICTURE = "pict";
+
+/**
+ * Assemble an AVIF file from a description of its items.
+ *
+ * ### The offset problem, and how this writer sidesteps it
+ *
+ * `iloc` holds absolute file offsets into `mdat`, and `mdat`'s position depends on the size of the
+ * metadata that precedes it — `iloc` included. Writing the offsets naively makes them wrong by the
+ * size of the difference, and iterating to a fixed point is fiddly because a changed offset can
+ * change the width of the field holding it.
+ *
+ * Fixing the offset fields at 32 bits makes the metadata size independent of the values in them,
+ * so one measure-then-patch pass converges immediately: offsets are written as zeroes, their
+ * positions recorded, the payloads laid out, and the recorded positions patched. The cost is a few
+ * bytes on small files and a 4 GiB ceiling, which the writer checks rather than silently wrapping.
+ *
+ * @param {object} description
+ * @param {string} [description.major_brand]
+ * @param {number} [description.minor_version]
+ * @param {string[]} [description.compatible_brands]
+ * @param {number} description.primary_item_id
+ * @param {Array<{id: number, item_type: string, item_name?: string, content_type?: string, hidden?: boolean, properties?: object[], essential?: boolean[], data: Uint8Array}>} description.items
+ * @param {Array<{from_item_id: number, reference_type: string, to_item_ids: number[]}>} [description.references]
+ * @returns {ArrayBuffer}
+ * @see ISO/IEC 23000-22 section 8 "AVIF file format"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function write_avif_file(description) {
+    const items = description.items;
+    const references = description.references ?? [];
+
+    if (items.length === 0) {
+        throw new Error("cannot write an AVIF file with no items");
+    }
+
+    const writer = new BoxWriter();
+
+    write_ftyp(writer, description);
+
+    const { properties, associations } = collect_properties(items);
+
+    // one entry per item, holding the position of the 32-bit offset field to patch once the
+    // payload has been laid out
+    const offset_field_positions = new Int32Array(items.length);
+
+    writer.begin_full_box("meta", 0, 0);
+
+    write_hdlr(writer);
+    write_pitm(writer, description.primary_item_id);
+    write_iinf(writer, items);
+
+    if (references.length > 0) {
+        write_iref(writer, references);
+    }
+
+    write_iprp(writer, properties, associations, items);
+    write_iloc(writer, items, offset_field_positions);
+
+    writer.end_box();
+
+    write_mdat(writer, items, offset_field_positions);
+
+    return writer.to_array_buffer();
+}
+
+/**
+ * @param {BoxWriter} writer
+ * @param {object} description
+ */
+function write_ftyp(writer, description) {
+    writer.begin_box("ftyp");
+    writer.fourcc(description.major_brand ?? "avif");
+    writer.u32(description.minor_version ?? 0);
+
+    const brands = description.compatible_brands ?? ["avif", "mif1", "miaf", "MA1B"];
+
+    for (let i = 0; i < brands.length; i++) {
+        writer.fourcc(brands[i]);
+    }
+
+    writer.end_box();
+}
+
+/**
+ * @param {BoxWriter} writer
+ */
+function write_hdlr(writer) {
+    writer.begin_full_box("hdlr", 0, 0);
+    writer.u32(0);
+    writer.fourcc(HANDLER_PICTURE);
+    writer.u32(0);
+    writer.u32(0);
+    writer.u32(0);
+    writer.utf8_string("");
+    writer.end_box();
+}
+
+/**
+ * @param {BoxWriter} writer
+ * @param {number} primary_item_id
+ */
+function write_pitm(writer, primary_item_id) {
+    if (primary_item_id > 0xffff) {
+        writer.begin_full_box("pitm", 1, 0);
+        writer.u32(primary_item_id);
+    } else {
+        writer.begin_full_box("pitm", 0, 0);
+        writer.u16(primary_item_id);
+    }
+
+    writer.end_box();
+}
+
+/**
+ * @param {BoxWriter} writer
+ * @param {object[]} items
+ */
+function write_iinf(writer, items) {
+    writer.begin_full_box("iinf", 0, 0);
+    writer.u16(items.length);
+
+    for (let i = 0; i < items.length; i++) {
+        const item = items[i];
+
+        writer.begin_full_box("infe", 2, item.hidden === true ? 1 : 0);
+        writer.u16(item.id);
+        writer.u16(0);
+        writer.fourcc(item.item_type);
+        writer.utf8_string(item.item_name ?? "");
+
+        if (item.item_type === "mime") {
+            writer.utf8_string(item.content_type ?? "");
+        }
+
+        writer.end_box();
+    }
+
+    writer.end_box();
+}
+
+/**
+ * @param {BoxWriter} writer
+ * @param {Array<{from_item_id: number, reference_type: string, to_item_ids: number[]}>} references
+ */
+function write_iref(writer, references) {
+    writer.begin_full_box("iref", 0, 0);
+
+    for (let i = 0; i < references.length; i++) {
+        const reference = references[i];
+
+        writer.begin_box(reference.reference_type);
+        writer.u16(reference.from_item_id);
+        writer.u16(reference.to_item_ids.length);
+
+        for (let j = 0; j < reference.to_item_ids.length; j++) {
+            writer.u16(reference.to_item_ids[j]);
+        }
+
+        writer.end_box();
+    }
+
+    writer.end_box();
+}
+
+/**
+ * Gather the distinct properties across all items, so identical properties are stored once.
+ *
+ * Deduplication is by serialised bytes rather than by object identity: two items built
+ * independently will carry equal-but-distinct `ispe` structs, and storing both would bloat `ipco`
+ * for no reason.
+ *
+ * @param {object[]} items
+ * @returns {{properties: object[], associations: Array<Array<{index: number, essential: boolean}>>}}
+ */
+function collect_properties(items) {
+    const properties = [];
+    const keys = new Map();
+    const associations = [];
+
+    for (let i = 0; i < items.length; i++) {
+        const item = items[i];
+        const item_properties = item.properties ?? [];
+        const essential = item.essential ?? [];
+
+        const item_associations = [];
+
+        for (let j = 0; j < item_properties.length; j++) {
+            const property = item_properties[j];
+
+            const probe = new BoxWriter();
+
+            write_item_property(probe, property);
+
+            const key = bytes_to_key(probe.to_bytes());
+
+            let index = keys.get(key);
+
+            if (index === undefined) {
+                properties.push(property);
+
+                index = properties.length;
+
+                keys.set(key, index);
+            }
+
+            item_associations.push({ index, essential: essential[j] === true });
+        }
+
+        associations.push(item_associations);
+    }
+
+    return { properties, associations };
+}
+
+/**
+ * A byte array as a string usable as a `Map` key.
+ *
+ * Chunked because `String.fromCharCode.apply` over a whole array overflows the argument stack once
+ * the array gets large, and an embedded ICC profile or a codec configuration carrying a big
+ * sequence header will get large.
+ *
+ * @param {Uint8Array} bytes
+ * @returns {string}
+ */
+function bytes_to_key(bytes) {
+    const CHUNK = 4096;
+
+    if (bytes.length <= CHUNK) {
+        return String.fromCharCode.apply(null, bytes);
+    }
+
+    let key = "";
+
+    for (let i = 0; i < bytes.length; i += CHUNK) {
+        key += String.fromCharCode.apply(null, bytes.subarray(i, Math.min(i + CHUNK, bytes.length)));
+    }
+
+    return key;
+}
+
+/**
+ * @param {BoxWriter} writer
+ * @param {object[]} properties
+ * @param {Array<Array<{index: number, essential: boolean}>>} associations
+ * @param {object[]} items
+ */
+function write_iprp(writer, properties, associations, items) {
+    writer.begin_box("iprp");
+
+    writer.begin_box("ipco");
+
+    for (let i = 0; i < properties.length; i++) {
+        write_item_property(writer, properties[i]);
+    }
+
+    writer.end_box();
+
+    // the narrow association form only reaches property index 127
+    const wide = properties.length > 127;
+
+    writer.begin_full_box("ipma", 0, wide ? 1 : 0);
+    writer.u32(items.length);
+
+    for (let i = 0; i < items.length; i++) {
+        const item_associations = associations[i];
+
+        writer.u16(items[i].id);
+        writer.u8(item_associations.length);
+
+        for (let j = 0; j < item_associations.length; j++) {
+            const association = item_associations[j];
+
+            if (wide) {
+                writer.u16((association.essential ? 0x8000 : 0) | association.index);
+            } else {
+                writer.u8((association.essential ? 0x80 : 0) | association.index);
+            }
+        }
+    }
+
+    writer.end_box();
+
+    writer.end_box();
+}
+
+/**
+ * Write `iloc` with one 32-bit offset field per item, left at zero and recorded for patching.
+ *
+ * @param {BoxWriter} writer
+ * @param {object[]} items
+ * @param {Int32Array} offset_field_positions filled in
+ */
+function write_iloc(writer, items, offset_field_positions) {
+    writer.begin_full_box("iloc", 0, 0);
+
+    // offset_size = 4, length_size = 4
+    writer.u8(0x44);
+    // base_offset_size = 0, reserved = 0
+    writer.u8(0x00);
+
+    writer.u16(items.length);
+
+    for (let i = 0; i < items.length; i++) {
+        writer.u16(items[i].id);
+        writer.u16(0);
+        writer.u16(1);
+
+        offset_field_positions[i] = writer.position;
+
+        writer.u32(0);
+        writer.u32(items[i].data.length);
+    }
+
+    writer.end_box();
+}
+
+/**
+ * @param {BoxWriter} writer
+ * @param {object[]} items
+ * @param {Int32Array} offset_field_positions
+ */
+function write_mdat(writer, items, offset_field_positions) {
+    writer.begin_box("mdat");
+
+    for (let i = 0; i < items.length; i++) {
+        const offset = writer.position;
+
+        if (offset > 4294967295) {
+            throw new Error("file exceeds the 4 GiB limit of this writer's 32-bit item offsets");
+        }
+
+        writer.bytes(items[i].data);
+
+        writer.patch_u32(offset_field_positions[i], offset);
+    }
+
+    writer.end_box();
+}

package/src/avif/native/heif/write_item_property.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Write one item property box.
+ *
+ * The inverse of {@link parse_item_property}. Properties this implementation does not model are
+ * carried through from their captured bytes, so a file that was read and is being written back
+ * keeps them — and, more importantly, keeps its `ipma` indices meaningful.
+ *
+ * @param {BoxWriter} writer
+ * @param {object} property one of the structs in `ItemProperty.js`
+ * @see ISO/IEC 23000-22 section 7.3 "AV1 Image Item Properties"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function write_item_property(writer: BoxWriter, property: object): void;
+//# sourceMappingURL=write_item_property.d.ts.map

package/src/avif/native/heif/write_item_property.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write_item_property.d.ts","sourceRoot":"","sources":["../../../../../src/avif/native/heif/write_item_property.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,iEANW,MAAM,QA6KhB"}

package/src/avif/native/heif/write_item_property.js

@@ -0,0 +1,182 @@
+/**
+ * Write one item property box.
+ *
+ * The inverse of {@link parse_item_property}. Properties this implementation does not model are
+ * carried through from their captured bytes, so a file that was read and is being written back
+ * keeps them — and, more importantly, keeps its `ipma` indices meaningful.
+ *
+ * @param {BoxWriter} writer
+ * @param {object} property one of the structs in `ItemProperty.js`
+ * @see ISO/IEC 23000-22 section 7.3 "AV1 Image Item Properties"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function write_item_property(writer, property) {
+    switch (property.type) {
+        case "ispe":
+            writer.begin_full_box("ispe", 0, 0);
+            writer.u32(property.width);
+            writer.u32(property.height);
+            writer.end_box();
+            break;
+
+        case "pixi":
+            writer.begin_full_box("pixi", 0, 0);
+            writer.u8(property.bits_per_channel.length);
+
+            for (let i = 0; i < property.bits_per_channel.length; i++) {
+                writer.u8(property.bits_per_channel[i]);
+            }
+
+            writer.end_box();
+            break;
+
+        case "av1C":
+            writer.begin_box("av1C");
+            writer.u8(0x80 | (property.version & 0x7f));
+            writer.u8(((property.seq_profile & 0x7) << 5) | (property.seq_level_idx_0 & 0x1f));
+            writer.u8(
+                ((property.seq_tier_0 & 1) << 7)
+                | ((property.high_bitdepth & 1) << 6)
+                | ((property.twelve_bit & 1) << 5)
+                | ((property.monochrome & 1) << 4)
+                | ((property.chroma_subsampling_x & 1) << 3)
+                | ((property.chroma_subsampling_y & 1) << 2)
+                | (property.chroma_sample_position & 0x3)
+            );
+            writer.u8(
+                property.initial_presentation_delay_minus_one >= 0
+                    ? 0x10 | (property.initial_presentation_delay_minus_one & 0x0f)
+                    : 0
+            );
+            writer.bytes(property.config_obus);
+            writer.end_box();
+            break;
+
+        case "colr":
+            writer.begin_box("colr");
+            writer.fourcc(property.colour_type);
+
+            if (property.colour_type === "nclx") {
+                writer.u16(property.colour_primaries);
+                writer.u16(property.transfer_characteristics);
+                writer.u16(property.matrix_coefficients);
+                writer.u8((property.full_range_flag & 1) << 7);
+            } else {
+                writer.bytes(property.icc_profile ?? new Uint8Array(0));
+            }
+
+            writer.end_box();
+            break;
+
+        case "pasp":
+            writer.begin_box("pasp");
+            writer.u32(property.h_spacing);
+            writer.u32(property.v_spacing);
+            writer.end_box();
+            break;
+
+        case "clap":
+            writer.begin_box("clap");
+            writer.u32(property.width_numerator);
+            writer.u32(property.width_denominator);
+            writer.u32(property.height_numerator);
+            writer.u32(property.height_denominator);
+            writer.i32(property.horizontal_offset_numerator);
+            writer.u32(property.horizontal_offset_denominator);
+            writer.i32(property.vertical_offset_numerator);
+            writer.u32(property.vertical_offset_denominator);
+            writer.end_box();
+            break;
+
+        case "irot":
+            writer.begin_box("irot");
+            writer.u8(property.angle & 0x3);
+            writer.end_box();
+            break;
+
+        case "imir":
+            writer.begin_box("imir");
+            writer.u8(property.axis & 0x1);
+            writer.end_box();
+            break;
+
+        case "auxC":
+            writer.begin_full_box("auxC", 0, 0);
+            writer.utf8_string(property.aux_type);
+            writer.bytes(property.aux_subtype);
+            writer.end_box();
+            break;
+
+        case "clli":
+            writer.begin_box("clli");
+            writer.u16(property.max_content_light_level);
+            writer.u16(property.max_pic_average_light_level);
+            writer.end_box();
+            break;
+
+        case "mdcv":
+            writer.begin_box("mdcv");
+
+            for (let i = 0; i < 6; i++) {
+                writer.u16(property.display_primaries[i]);
+            }
+
+            writer.u16(property.white_point_x);
+            writer.u16(property.white_point_y);
+            writer.u32(property.max_display_mastering_luminance);
+            writer.u32(property.min_display_mastering_luminance);
+            writer.end_box();
+            break;
+
+        case "cclv":
+            writer.begin_box("cclv");
+            writer.bytes(property.payload);
+            writer.end_box();
+            break;
+
+        case "a1op":
+            writer.begin_box("a1op");
+            writer.u8(property.op_index);
+            writer.end_box();
+            break;
+
+        case "lsel":
+            writer.begin_box("lsel");
+            writer.u16(property.layer_id);
+            writer.end_box();
+            break;
+
+        case "a1lx": {
+            writer.begin_box("a1lx");
+
+            // the narrow form only reaches 65535 bytes a layer; widen for anything larger rather
+            // than truncating
+            const large = property.layer_size[0] > 0xffff || property.layer_size[1] > 0xffff || property.layer_size[2] > 0xffff;
+
+            writer.u8(large ? 1 : 0);
+
+            for (let i = 0; i < 3; i++) {
+                if (large) {
+                    writer.u32(property.layer_size[i]);
+                } else {
+                    writer.u16(property.layer_size[i]);
+                }
+            }
+
+            writer.end_box();
+            break;
+        }
+
+        default:
+            if (property.type.length !== 4) {
+                throw new Error(`cannot write a property with type '${property.type}'`);
+            }
+
+            writer.begin_box(property.type);
+            writer.bytes(property.payload ?? new Uint8Array(0));
+            writer.end_box();
+            break;
+    }
+}

package/src/avif/native/index.d.ts

@@ -0,0 +1,14 @@
+export { AvifDecoder } from "./api/AvifDecoder.js";
+export { Av1EncodeContext } from "./av1/encode/Av1EncodeContext.js";
+export { decode_avif } from "./api/decode_avif.js";
+export { avif_to_sampler2d } from "./api/avif_to_sampler2d.js";
+export { sampler2d_to_avif } from "./api/sampler2d_to_avif.js";
+export { LINEAR_REFERENCE_NITS } from "./color/transfer_to_linear.js";
+export { YuvImage } from "./color/YuvImage.js";
+export { parse_avif_file } from "./heif/parse_avif_file.js";
+export { write_avif_file } from "./heif/write_avif_file.js";
+export { encode_avif, SUBSAMPLING_400, SUBSAMPLING_420, SUBSAMPLING_422, SUBSAMPLING_444 } from "./api/encode_avif.js";
+export { CHROMA_UPSAMPLING_AUTOMATIC, CHROMA_UPSAMPLING_BEST, CHROMA_UPSAMPLING_FASTEST, COLOUR_SPACE_LINEAR, COLOUR_SPACE_SIGNAL, convert_to_rgba } from "./api/convert_to_rgba.js";
+export { EFFORT_BALANCED, EFFORT_FAST, EFFORT_THOROUGH } from "./av1/encode/encode_effort.js";
+export { DECODE_BALANCED, DECODE_FAST, DECODE_THOROUGH } from "./av1/encode/decode_effort.js";
+//# sourceMappingURL=index.d.ts.map

package/src/avif/native/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/avif/native/index.js"],"names":[],"mappings":""}

package/src/avif/native/index.js

@@ -0,0 +1,56 @@
+/**
+ * A pure JavaScript AVIF codec: the ISOBMFF container, the AV1 still picture coding tools that
+ * AVIF uses, and the colour handling between them.
+ *
+ * Nothing here touches the filesystem, a worker, a canvas or WebAssembly, so the same code runs in
+ * a browser, in node and in whatever else has a JavaScript engine. Everything is synchronous.
+ *
+ * The decoder reads what libavif writes, sample for sample. The encoder writes what libavif reads,
+ * sample for sample. Both claims are checked rather than asserted — see `tools/` for how.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+export { AvifDecoder } from "./api/AvifDecoder.js";
+export { Av1EncodeContext } from "./av1/encode/Av1EncodeContext.js";
+
+export { decode_avif } from "./api/decode_avif.js";
+export { encode_avif } from "./api/encode_avif.js";
+
+export { avif_to_sampler2d } from "./api/avif_to_sampler2d.js";
+export { sampler2d_to_avif } from "./api/sampler2d_to_avif.js";
+
+export {
+    CHROMA_UPSAMPLING_AUTOMATIC,
+    CHROMA_UPSAMPLING_BEST,
+    CHROMA_UPSAMPLING_FASTEST,
+    COLOUR_SPACE_LINEAR,
+    COLOUR_SPACE_SIGNAL,
+    convert_to_rgba
+} from "./api/convert_to_rgba.js";
+
+export {
+    SUBSAMPLING_400,
+    SUBSAMPLING_420,
+    SUBSAMPLING_422,
+    SUBSAMPLING_444
+} from "./api/encode_avif.js";
+
+export {
+    EFFORT_BALANCED,
+    EFFORT_FAST,
+    EFFORT_THOROUGH
+} from "./av1/encode/encode_effort.js";
+
+export {
+    DECODE_BALANCED,
+    DECODE_FAST,
+    DECODE_THOROUGH
+} from "./av1/encode/decode_effort.js";
+
+export { LINEAR_REFERENCE_NITS } from "./color/transfer_to_linear.js";
+export { YuvImage } from "./color/YuvImage.js";
+
+export { parse_avif_file } from "./heif/parse_avif_file.js";
+export { write_avif_file } from "./heif/write_avif_file.js";

package/src/avif/native/isobmff/BoxHeader.d.ts

@@ -0,0 +1,50 @@
+/**
+ * A parsed ISOBMFF box header.
+ *
+ * Reused across a whole parse: {@link read_box_header} fills one of these in place rather than
+ * allocating, so walking a box tree of any depth allocates nothing per box.
+ *
+ * @see ISO/IEC 14496-12 section 4.2 "Object structure"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class BoxHeader {
+    /**
+     * Four character type. `uuid` here means {@link user_type} carries the real identity.
+     * @type {string}
+     */
+    type: string;
+    /**
+     * Absolute offset of the first byte of the box, its size field included.
+     * @type {number}
+     */
+    offset: number;
+    /**
+     * Total size of the box in bytes, header included.
+     * @type {number}
+     */
+    size: number;
+    /**
+     * Absolute offset of the first byte after the header.
+     * @type {number}
+     */
+    payload_offset: number;
+    /**
+     * Size of the payload in bytes.
+     * @type {number}
+     */
+    payload_size: number;
+    /**
+     * 16 byte extended type, present only when {@link type} is `uuid`. A view into the source
+     * buffer, not a copy.
+     * @type {Uint8Array|null}
+     */
+    user_type: Uint8Array | null;
+    /**
+     * Absolute offset one past the last byte of the box.
+     * @returns {number}
+     */
+    get end(): number;
+}
+//# sourceMappingURL=BoxHeader.d.ts.map

package/src/avif/native/isobmff/BoxHeader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BoxHeader.d.ts","sourceRoot":"","sources":["../../../../../src/avif/native/isobmff/BoxHeader.js"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH;IACI;;;OAGG;IACH,MAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,QAFU,MAAM,CAEL;IAEX;;;OAGG;IACH,MAFU,MAAM,CAEP;IAET;;;OAGG;IACH,gBAFU,MAAM,CAEG;IAEnB;;;OAGG;IACH,cAFU,MAAM,CAEC;IAEjB;;;;OAIG;IACH,WAFU,UAAU,GAAC,IAAI,CAER;IAEjB;;;OAGG;IACH,kBAEC;CACJ"}