m4k 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sven
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,30 @@
+# m4k - media kit
+
+A media conversion toolkit based on [ffmpeg](https://ffmpeg.org/) and [sharp](https://sharp.pixelplumbing.com/)/[libvips](https://github.com/libvips/libvips).
+It provides queueing and progress reporting via async iterables.
+
+## Usage
+
+Image optimization happens completely in memory.
+
+```ts
+import { optimizeImage, ConvertedFile } from "m4k";
+// input is a ReadableStream or Blob
+for await (const value of optimizeImage(input, opts)) {
+  if (value instanceof ConvertedFile) {
+    // do something with the file
+  }
+}
+```
+
+For lower memory usage, video optimization happens with files.
+
+```ts
+import { optimizeVideo, ConvertedFile } from "m4k";
+// input is a file path
+for await (const value of optimizeVideo(input, opts)) {
+  if (value instanceof ConvertedFile) {
+    // do something with the file
+  }
+}
+```

package/dist/images/image-optimizer.d.ts

@@ -0,0 +1,9 @@
+import { type ImageOptimizerOptions, ConvertedFile } from "@m4k/types";
+export type Format = Required<ImageOptimizerOptions>["format"];
+export type Fit = Required<Required<ImageOptimizerOptions>["resize"]>["fit"];
+export declare function optimizeImage(input: ReadableStream | Blob, opts: ImageOptimizerOptions | ImageOptimizerOptions[], signal?: AbortSignal): AsyncGenerator<ConvertedFile | {
+    progress: number;
+} | {
+    position: number;
+}, void, unknown> | null;
+export declare const imageQueue: import("tasque").Tasque;

package/dist/images/image-optimizer.js

@@ -0,0 +1,58 @@
+import { ConvertedFile } from "@m4k/types";
+import sharp from "sharp";
+import { createQueue } from "tasque";
+import { readableFromWeb, readableToWeb } from "../util/streams";
+export function optimizeImage(input, opts, signal) {
+    const sharpInstance = sharp();
+    const iterable = imageQueue.iterate(async function* () {
+        opts = Array.isArray(opts) ? opts : [opts];
+        readableFromWeb("stream" in input ? input.stream() : input).pipe(sharpInstance);
+        const files = await Promise.all(opts.map(async ({ colorspace, crop, format = "avif", keepExif, keepIcc, keepMetadata, quality, resize, rotate, }, idx) => {
+            let s = sharpInstance.clone();
+            s = s.rotate(rotate);
+            if (resize)
+                s = s.resize({
+                    ...resize,
+                    fit: resize.fit ?? "inside",
+                });
+            if (keepMetadata)
+                s = s.keepMetadata();
+            if (keepExif)
+                s = s.keepExif();
+            if (keepIcc)
+                s = s.keepIccProfile();
+            if (colorspace)
+                s = s.toColorspace(colorspace);
+            if (crop) {
+                s = s.extract({
+                    ...crop,
+                    left: crop.left ?? 0,
+                    top: crop.top ?? 0,
+                });
+            }
+            s = s.toFormat(format, { quality });
+            return new ConvertedFile(`file${idx + 1}.${format}`, `image/${format}`, readableToWeb(s));
+        }));
+        let done = 0;
+        yield { progress: 0 };
+        for (const file of files) {
+            yield file;
+            done++;
+            yield { progress: Math.round((done / files.length) * 100) };
+        }
+    }, signal);
+    if (!iterable)
+        return null;
+    return (async function* () {
+        for await (const [position, value] of iterable) {
+            if (position !== null)
+                yield { position };
+            else
+                yield value;
+        }
+    })();
+}
+export const imageQueue = createQueue({
+    parallelize: Number(process.env.IMAGE_PARALLELIZE ?? 5),
+    max: Number(process.env.IMAGE_QUEUE_SIZE ?? 100),
+});

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { ConvertedFile } from "@m4k/types";
+export { imageQueue, optimizeImage } from "./images/image-optimizer";
+export { getExtension, optimizeVideo, tmpVideoDir, videoQueue, } from "./videos/video-optimizer";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { ConvertedFile } from "@m4k/types";
+export { imageQueue, optimizeImage } from "./images/image-optimizer";
+export { getExtension, optimizeVideo, tmpVideoDir, videoQueue, } from "./videos/video-optimizer";

package/dist/util/mime.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Mapping from file extensions to their corresponding MIME types
+ */
+export declare const mimeTypes: Record<string, string>;

package/dist/util/mime.js

@@ -0,0 +1,51 @@
+/**
+ * Mapping from file extensions to their corresponding MIME types
+ */
+export const mimeTypes = {
+    // Image formats
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    png: "image/png",
+    gif: "image/gif",
+    webp: "image/webp",
+    avif: "image/avif",
+    heic: "image/heic",
+    heif: "image/heif",
+    svg: "image/svg+xml",
+    tiff: "image/tiff",
+    tif: "image/tiff",
+    bmp: "image/bmp",
+    ico: "image/x-icon",
+    // Video formats
+    mp4: "video/mp4",
+    asx: "video/x-ms-asf",
+    asf: "video/x-ms-asf",
+    mkv: "video/x-matroska",
+    mov: "video/quicktime",
+    avi: "video/x-msvideo",
+    wmv: "video/x-ms-wmv",
+    flv: "video/x-flv",
+    webm: "video/webm",
+    m4v: "video/x-m4v",
+    mng: "video/x-mng",
+    mpg: "video/mpeg",
+    mpeg: "video/mpeg",
+    ogv: "video/ogg",
+    "3gpp": "video/3gpp",
+    "3gp": "video/3gpp",
+    ts: "video/mp2t",
+    // Audio formats
+    mp3: "audio/mpeg",
+    wav: "audio/wav",
+    ogg: "audio/ogg",
+    oga: "audio/ogg",
+    m4a: "audio/mp4",
+    aac: "audio/aac",
+    flac: "audio/flac",
+    wma: "audio/x-ms-wma",
+    m4b: "audio/mp4",
+    m4p: "audio/mp4",
+    opus: "audio/opus",
+    aiff: "audio/aiff",
+    alac: "audio/alac",
+};

package/dist/util/streams.d.ts

@@ -0,0 +1,3 @@
+import { Readable } from "node:stream";
+export declare function readableFromWeb(stream: ReadableStream): Readable;
+export declare function readableToWeb(stream: Readable): ReadableStream & AsyncIterable<Uint8Array>;

package/dist/util/streams.js

@@ -0,0 +1,8 @@
+import { Readable } from "node:stream";
+export function readableFromWeb(stream) {
+    // Currently node types don't match with TS lib types for ReadableStream, so we need to cast to any.
+    return Readable.fromWeb(stream);
+}
+export function readableToWeb(stream) {
+    return Readable.toWeb(stream);
+}

package/dist/videos/video-optimizer.d.ts

@@ -0,0 +1,15 @@
+import { ConvertedFile, type VideoOptimizerOptions } from "@m4k/types";
+export declare function optimizeVideo(inputPath: string, opts: VideoOptimizerOptions, signal?: AbortSignal): AsyncGenerator<ConvertedFile | {
+    progress: number;
+} | {
+    position: number;
+}, void, unknown> | null;
+/**
+ * Get the extension for a given format.
+ * May not be complete yet. Most of the time, the format will be the same as the extension.
+ * @param format - The format to get the extension for.
+ * @returns The extension for the given format.
+ */
+export declare function getExtension(format: string): string;
+export declare const videoQueue: import("tasque").Tasque;
+export declare const tmpVideoDir: string;

package/dist/videos/video-optimizer.js

@@ -0,0 +1,124 @@
+import { ConvertedFile } from "@m4k/types";
+import { spawn } from "node:child_process";
+import { getRandomValues } from "node:crypto";
+import { mkdir, rm } from "node:fs/promises";
+import { createQueue } from "tasque";
+import { mimeTypes } from "../util/mime";
+export function optimizeVideo(inputPath, opts, signal) {
+    const iterable = videoQueue.iterate(async function* () {
+        await mkdir(tmpVideoDir, { recursive: true });
+        const outputPath = `${tmpVideoDir}/out-${Buffer.from(getRandomValues(new Uint8Array(16))).toString("base64url")}.${getExtension(opts.format ?? "mp4")}`;
+        const inArgs = [];
+        if (opts.inputFormat)
+            inArgs.push("-f", opts.inputFormat);
+        if (opts.seek)
+            inArgs.push("-ss", opts.seek.toString());
+        if (opts.duration)
+            inArgs.push("-t", opts.duration.toString());
+        const outArgs = [];
+        if (opts.format)
+            outArgs.push("-f", opts.format);
+        if (opts.audioBitrate)
+            outArgs.push("-b:a", opts.audioBitrate.toString());
+        if (opts.videoBitrate)
+            outArgs.push("-b:v", opts.videoBitrate.toString());
+        if (opts.audioFilters)
+            outArgs.push("-af", opts.audioFilters);
+        if (opts.videoFilters)
+            outArgs.push("-vf", opts.videoFilters);
+        if (opts.complexFilters)
+            outArgs.push("-filter_complex", opts.complexFilters);
+        if (opts.aspect)
+            outArgs.push("-aspect", opts.aspect.toString());
+        if (opts.pad)
+            outArgs.push("-pad", opts.pad);
+        if (opts.fps)
+            outArgs.push("-r", opts.fps.toString());
+        if (opts.size)
+            outArgs.push("-scale", opts.size);
+        outArgs.push("-c:v", opts.videoCodec ?? "copy");
+        outArgs.push("-c:a", opts.audioCodec ?? "copy");
+        try {
+            const child = spawn(ffmpeg, ["-y", ...inArgs, "-i", inputPath, ...outArgs, outputPath], { stdio: ["pipe", "pipe", "pipe"], signal });
+            const decoder = new TextDecoder();
+            let metadataStr = "";
+            let duration = null;
+            let progress = 0;
+            let errStr = "";
+            for await (const chunk of child.stderr) {
+                const str = decoder.decode(chunk);
+                errStr += str;
+                if (duration === null) {
+                    metadataStr += str;
+                    duration = parseDuration(metadataStr);
+                    if (duration === null) {
+                        metadataStr = str.slice(-30);
+                        continue;
+                    }
+                    yield { progress };
+                    continue;
+                }
+                const match = str.match(/time=(\d\d:\d\d:\d\d.\d\d)/);
+                if (match) {
+                    const time = durationToMs(match[1]);
+                    const p = Math.round((time / duration) * 100);
+                    if (p !== progress) {
+                        progress = p;
+                        yield { progress };
+                    }
+                }
+            }
+            if (progress !== 100) {
+                yield { progress: 100 };
+            }
+            const code = await new Promise((resolve) => {
+                child.on("close", resolve);
+            });
+            if (code !== 0) {
+                throw new Error(`ffmpeg exited with code ${code}: ${errStr}`);
+            }
+            yield new ConvertedFile(outputPath, mimeTypes[opts.format ?? "mp4"]);
+        }
+        finally {
+            await rm(outputPath, { force: true });
+        }
+    }, signal);
+    if (!iterable)
+        return null;
+    return (async function* () {
+        for await (const [position, value] of iterable) {
+            if (position !== null)
+                yield { position };
+            else
+                yield value;
+        }
+    })();
+}
+/**
+ * Get the extension for a given format.
+ * May not be complete yet. Most of the time, the format will be the same as the extension.
+ * @param format - The format to get the extension for.
+ * @returns The extension for the given format.
+ */
+export function getExtension(format) {
+    return extMap[format] ?? format;
+}
+export const videoQueue = createQueue({
+    parallelize: Number(process.env.VIDEO_PARALLELIZE ?? 1),
+    max: Number(process.env.VIDEO_QUEUE_SIZE ?? 5),
+});
+export const tmpVideoDir = `${process.env.TMP_DIR ?? "/tmp"}/videos`;
+function parseDuration(metadataStr) {
+    const match = metadataStr.match(/Duration: (\d+:\d+:\d+\.\d+)/);
+    if (!match)
+        return null;
+    return durationToMs(match[1]);
+}
+function durationToMs(duration) {
+    const [, hours, minutes, seconds, centiseconds] = duration.match(/(\d+):(\d+):(\d+)\.(\d+)/)?.map(Number) ?? [];
+    return (((hours * 60 + minutes) * 60 + seconds) * 100 + centiseconds) * 10;
+}
+const ffmpeg = process.env.FFMPEG_PATH ?? (await import("@ffmpeg-installer/ffmpeg")).path;
+const extMap = {
+    matroska: "mkv",
+};

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "m4k",
+  "module": "./dist/index.js",
+  "type": "module",
+  "version": "0.1.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "prepublishOnly": "bun tsc",
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "@ffmpeg-installer/ffmpeg": "^1.1.0",
+    "tasque": "^0.1.2",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "sharp": "^0.33.5"
+  },
+  "repository": "github:sv2dev/m4k"
+}