m4k 0.3.5 → 0.3.6

package/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to `m4k` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.6]
+
+### Added
+
+- Added pinned CPU/q8 CLIP classification with user-defined candidates and input SHA-256 results.
+- Added bounded TIFF IFD1 JPEG extraction without RAW development or original fallback.
+
+### Fixed
+
+- Released cancelled model-load waiters while reusing the shared load and retaining the slot during native inference.
+
 ## [0.3.5]
 
 ### Changed

package/lib/images/classify-image.d.ts

@@ -0,0 +1,6 @@
+import { type ClassificationOptions, type ClassificationResult } from "@m4k/common";
+/** Bounded preview-only inference. No arbitrary models, remote image URLs or file outputs. */
+export declare function classifyImage(input: Uint8Array, options: ClassificationOptions, { signal }?: {
+    signal?: AbortSignal;
+}): Promise<ClassificationResult>;
+//# sourceMappingURL=classify-image.d.ts.map

package/lib/images/classify-image.js

@@ -0,0 +1,71 @@
+import { createHash } from "node:crypto";
+import sharp from "sharp";
+import { imageClassifier, validateClassificationOptions, } from "@m4k/common";
+import { waitForLoad } from "../util/wait-for-load.js";
+let classifier;
+let busy = false;
+async function loadClassifier() {
+    const { env, pipeline } = await import("@huggingface/transformers");
+    env.cacheDir = process.env.M4K_MODEL_CACHE ?? `${process.env.M4K_TMP_DIR ?? "/tmp/m4k"}/models`;
+    return pipeline("zero-shot-image-classification", imageClassifier.model, {
+        revision: imageClassifier.revision,
+        dtype: "q8",
+        device: "cpu",
+    });
+}
+async function decodePreview(input) {
+    try {
+        const image = sharp(input, { limitInputPixels: imageClassifier.maxPixels, animated: false });
+        const metadata = await image.metadata();
+        if (!["jpeg", "png", "webp"].includes(metadata.format ?? "") || (metadata.pages ?? 1) !== 1)
+            throw new RangeError("Classification requires a single JPEG, PNG or WebP preview");
+        return await image
+            .rotate()
+            .removeAlpha()
+            .toColourspace("srgb")
+            .raw()
+            .toBuffer({ resolveWithObject: true });
+    }
+    catch (error) {
+        throw error instanceof RangeError ? error : new RangeError("Invalid classification preview");
+    }
+}
+/** Bounded preview-only inference. No arbitrary models, remote image URLs or file outputs. */
+export async function classifyImage(input, options, { signal } = {}) {
+    if (!validateClassificationOptions(options))
+        throw new RangeError("Unsupported classifier configuration");
+    if (input.byteLength > imageClassifier.maxBytes)
+        throw new RangeError("Classification preview exceeds byte limit");
+    signal?.throwIfAborted();
+    if (busy)
+        throw new Error("Classifier is busy");
+    busy = true;
+    try {
+        const bytes = Uint8Array.from(input);
+        const candidates = [...options.labels];
+        const { data, info } = await decodePreview(bytes);
+        signal?.throwIfAborted();
+        const { RawImage } = await import("@huggingface/transformers");
+        classifier ??= loadClassifier().catch((error) => {
+            classifier = undefined;
+            throw error;
+        });
+        const run = await waitForLoad(classifier, signal);
+        signal?.throwIfAborted();
+        const labels = await run(new RawImage(new Uint8ClampedArray(data), info.width, info.height, 3), candidates, {
+            hypothesis_template: imageClassifier.template,
+        });
+        // Native inference cannot be preempted; retain the slot until it stops and discard cancelled results.
+        signal?.throwIfAborted();
+        return {
+            classifierId: imageClassifier.id,
+            classifierVersion: imageClassifier.version,
+            sha256: createHash("sha256").update(bytes).digest("hex"),
+            labels: labels,
+        };
+    }
+    finally {
+        busy = false;
+    }
+}
+//# sourceMappingURL=classify-image.js.map

package/lib/images/extract-embedded-preview.d.ts

@@ -0,0 +1,3 @@
+/** Bounded TIFF IFD0 -> IFD1 JPEG thumbnail extraction; no arbitrary TIFF traversal or RAW development. */
+export declare function extractEmbeddedPreview(input: Buffer): Promise<Buffer>;
+//# sourceMappingURL=extract-embedded-preview.d.ts.map

package/lib/images/extract-embedded-preview.js

@@ -0,0 +1,49 @@
+import sharp from "sharp";
+/** Bounded TIFF IFD0 -> IFD1 JPEG thumbnail extraction; no arbitrary TIFF traversal or RAW development. */
+export async function extractEmbeddedPreview(input) {
+    if (input.byteLength > 128 * 1024 * 1024)
+        throw new RangeError("RAW preview input exceeds 128 MiB");
+    const little = input.subarray(0, 4).equals(Buffer.from([73, 73, 42, 0]));
+    if (input.length < 8 || (!little && !input.subarray(0, 4).equals(Buffer.from([77, 77, 0, 42]))))
+        throw new RangeError("Embedded preview requires a TIFF-based camera file");
+    const view = new DataView(input.buffer, input.byteOffset, input.byteLength);
+    const ifd = (offset) => {
+        if (offset < 8 || offset > input.length - 2)
+            throw new RangeError("Invalid embedded preview directory");
+        const count = view.getUint16(offset, little);
+        if (count > 256 || offset + 2 + count * 12 + 4 > input.length)
+            throw new RangeError("Invalid embedded preview directory");
+        const tags = new Map();
+        for (let i = 0; i < count; i++) {
+            const at = offset + 2 + i * 12;
+            const type = view.getUint16(at + 2, little);
+            if (view.getUint32(at + 4, little) !== 1 || (type !== 3 && type !== 4))
+                continue;
+            tags.set(view.getUint16(at, little), type === 3 ? view.getUint16(at + 8, little) : view.getUint32(at + 8, little));
+        }
+        return { tags, next: view.getUint32(offset + 2 + count * 12, little) };
+    };
+    const firstOffset = view.getUint32(4, little);
+    const first = ifd(firstOffset);
+    if (!first.next || first.next === firstOffset)
+        throw new RangeError("No supported embedded JPEG preview");
+    const { tags } = ifd(first.next);
+    const offset = tags.get(0x201) ?? 0;
+    const length = tags.get(0x202) ?? 0;
+    if ((tags.has(0x103) && tags.get(0x103) !== 6) ||
+        offset < 8 ||
+        length < 2 ||
+        length > 8 * 1024 * 1024 ||
+        offset > input.length - length)
+        throw new RangeError("No supported embedded JPEG preview");
+    const jpeg = input.subarray(offset, offset + length);
+    if (jpeg[0] !== 0xff || jpeg[1] !== 0xd8)
+        throw new RangeError("No supported embedded JPEG preview");
+    const orientation = first.tags.get(0x112) ?? 1;
+    // Attach only orientation to the private intermediate; the normal transform applies it.
+    return sharp(jpeg, { limitInputPixels: 1024 * 1024 })
+        .withMetadata({ orientation: orientation >= 1 && orientation <= 8 ? orientation : 1 })
+        .jpeg()
+        .toBuffer();
+}
+//# sourceMappingURL=extract-embedded-preview.js.map

package/lib/images/image-processor.js

@@ -6,6 +6,7 @@ import sharp from "sharp";
 import { createQueue } from "tasque";
 import { ffmpeg, createTmp, randomId } from "../util/ffmpeg-processor.js";
 import { exhaustAsyncIterableToWritable } from "../util/streams.js";
+import { extractEmbeddedPreview } from "./extract-embedded-preview.js";
 export { ffmpeg };
 const imageTmpDir = `${process.env.M4K_TMP_DIR ?? "/tmp/m4k"}/image`;
 /**
@@ -18,7 +19,13 @@ const imageTmpDir = `${process.env.M4K_TMP_DIR ?? "/tmp/m4k"}/image`;
 export function processImage(input, opts, { signal } = {}) {
     const iterable = imageQueue.iterate(async function* () {
         const optsArr = Array.isArray(opts) ? opts : [opts];
-        const resolvedInput = await resolveInput(input);
+        const preview = optsArr.some((o) => o.embeddedPreview);
+        if (preview &&
+            optsArr.some((o) => !o.embeddedPreview || o.keepMetadata || o.keepExif || o.keepIcc))
+            throw new RangeError("Embedded previews require metadata stripping and cannot mix input modes");
+        const resolvedInput = preview
+            ? await extractEmbeddedPreview(await boundedInput(input))
+            : await resolveInput(input);
         const inputExt = detectExt(resolvedInput);
         if (inputExt != null && optsArr.every((o) => isImageNoOp(o, inputExt))) {
             yield { progress: 0 };
@@ -107,7 +114,9 @@ async function ffmpegDecodeToPng(input) {
                 stdio: ["pipe", "pipe", "pipe"],
             });
             let errStr = "";
-            child.stderr.on("data", (chunk) => { errStr += chunk.toString(); });
+            child.stderr.on("data", (chunk) => {
+                errStr += chunk.toString();
+            });
             child.on("close", (code) => {
                 if (code !== 0)
                     reject(new Error(`ffmpeg exited with code ${code}: ${errStr}`));
@@ -123,6 +132,22 @@ async function ffmpegDecodeToPng(input) {
             await rm(inputPath, { force: true });
     }
 }
+async function boundedInput(input) {
+    const iterable = typeof input === "string"
+        ? createReadStream(input)
+        : "stream" in input
+            ? input.stream()
+            : input;
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of iterable) {
+        size += chunk.length;
+        if (size > 128 * 1024 * 1024)
+            throw new RangeError("RAW preview input exceeds 128 MiB");
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks);
+}
 async function resolveInput(input) {
     if (typeof input === "string" || "stream" in input)
         return input;
@@ -169,8 +194,14 @@ function detectExt(input) {
             return "png";
         if (input[0] === 0x47 && input[1] === 0x49 && input[2] === 0x46)
             return "gif";
-        if (input[0] === 0x52 && input[1] === 0x49 && input[2] === 0x46 && input[3] === 0x46 &&
-            input[8] === 0x57 && input[9] === 0x45 && input[10] === 0x42 && input[11] === 0x50)
+        if (input[0] === 0x52 &&
+            input[1] === 0x49 &&
+            input[2] === 0x46 &&
+            input[3] === 0x46 &&
+            input[8] === 0x57 &&
+            input[9] === 0x45 &&
+            input[10] === 0x42 &&
+            input[11] === 0x50)
             return "webp";
         // AVIF/HEIF: ftyp box at offset 4, brand at offset 8
         if (input[4] === 0x66 && input[5] === 0x74 && input[6] === 0x79 && input[7] === 0x70) {

package/lib/index.d.ts

@@ -1,5 +1,6 @@
-export { ProcessedFile, type AudioOptions, type ImageOptions, type ProcessingError, type Progress, type QueuePosition, type VideoOptions } from "@m4k/common";
+export { ProcessedFile, type AudioOptions, type ImageOptions, type ProcessingError, type Progress, type QueuePosition, type VideoOptions, } from "@m4k/common";
 export { audioQueue, processAudio } from "./audio/audio-processor.js";
+export { classifyImage } from "./images/classify-image.js";
 export { imageQueue, processImage } from "./images/image-processor.js";
 export { getExtension } from "./util/ffmpeg-processor.js";
 export { mimeTypes } from "./util/mime.js";

package/lib/index.js

@@ -1,5 +1,6 @@
-export { ProcessedFile } from "@m4k/common";
+export { ProcessedFile, } from "@m4k/common";
 export { audioQueue, processAudio } from "./audio/audio-processor.js";
+export { classifyImage } from "./images/classify-image.js";
 export { imageQueue, processImage } from "./images/image-processor.js";
 export { getExtension } from "./util/ffmpeg-processor.js";
 export { mimeTypes } from "./util/mime.js";

package/lib/util/wait-for-load.d.ts

@@ -0,0 +1,3 @@
+/** Stop waiting on cancellation without cancelling or duplicating a shared model load. */
+export declare function waitForLoad<T>(load: Promise<T>, signal?: AbortSignal): Promise<T>;
+//# sourceMappingURL=wait-for-load.d.ts.map

package/lib/util/wait-for-load.js

@@ -0,0 +1,23 @@
+/** Stop waiting on cancellation without cancelling or duplicating a shared model load. */
+export function waitForLoad(load, signal) {
+    if (!signal)
+        return load;
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            signal.removeEventListener("abort", onAbort);
+            reject(signal.reason);
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        // Always observe settlement, even after cancellation, so a failed background load is handled.
+        load.then((value) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+        });
+        if (signal.aborted)
+            onAbort();
+    });
+}
+//# sourceMappingURL=wait-for-load.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "m4k",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "Media toolkit for node, bun, and deno",
   "keywords": [
     "audio",
@@ -33,7 +33,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@m4k/common": "^0.2.8"
+    "@huggingface/transformers": "3.8.1",
+    "@m4k/common": "^0.2.9"
   },
   "devDependencies": {
     "@ffmpeg-installer/ffmpeg": "^1.1.0",