@hoardodile/host 0.0.0

package/dist/render/index.d.ts

@@ -0,0 +1,125 @@
+import { Readable } from 'node:stream';
+import { ResolvedImageVariant } from '@hoardodile/sdk-types/image-variant';
+
+type FfmpegPaths = {
+    readonly ffmpeg: string;
+    readonly ffprobe: string;
+};
+type ResolveDeps = {
+    readonly env?: NodeJS.ProcessEnv;
+    /** Override for tests so they never hit the real module. */
+    readonly loadStatic?: () => string | undefined;
+    /** Override for tests so they never hit the real module. */
+    readonly loadStaticFfprobe?: () => string | undefined;
+};
+declare function resolveFfmpegPaths(deps?: ResolveDeps): FfmpegPaths;
+
+/**
+ * Level of downscaling applied to animated thumbnails: they use 1/3 the
+ * still-image area cap, which keeps animated WebP file sizes sane.
+ */
+declare const ANIMATED_AREA_DIVISOR = 3;
+/**
+ * Recursively remove any `.writing-<pid>-<ts>` temp files left behind by a
+ * previous process crash. Safe to call fire-and-forget at startup.
+ */
+declare function cleanOrphanedTempFiles(thumbRoot: string): Promise<void>;
+declare const WEBP_QUALITY = 82;
+declare const PREVIEW_WEBP_QUALITY = 90;
+declare const AVIF_QUALITY = 65;
+declare const PREVIEW_AVIF_QUALITY = 70;
+/**
+ * Level of CPU effort the AVIF encoder spends reducing file size
+ * (0 = fastest/largest … 9 = slowest/smallest; sharp's default is 4).
+ * Thumbs are cache-once artifacts re-encoded in bulk by the precache
+ * sweep, where AVIF encode dominates wall time; effort 2 cuts encode
+ * cost substantially for a few percent larger output — measured on the
+ * precache bench (see bench/precache.bench.ts).
+ */
+declare const AVIF_EFFORT = 2;
+type RenderResult = {
+    readonly path: string;
+    readonly bytes: number;
+};
+type ImageThumbInput = string | Buffer | {
+    readonly openStream: () => Promise<Readable>;
+    /**
+     * Byte-range read into the underlying source. Lets the metadata
+     * step read a small header window instead of streaming the
+     * whole entry — libvips full-reads non-seekable input.
+     */
+    readonly readRange?: (start: number, end: number) => Promise<Buffer>;
+};
+type ImageThumbRenderResult = RenderResult & {
+    readonly format: "webp" | "avif";
+    readonly displayWidth: number;
+    readonly displayHeight: number;
+    readonly animated: boolean;
+};
+type VideoFrameSource = string | Readable;
+/**
+ * Encode an image thumb in a single sharp pipeline: one metadata read,
+ * animation detection, resize, and encode. Encodes to the variant's
+ * `format`, downgrading an animated source to WebP (sharp cannot encode
+ * animated AVIF).
+ */
+declare function renderImageThumbOnce(opts: {
+    readonly input: ImageThumbInput;
+    readonly resolveDest: (fmt: "webp" | "avif") => string;
+    /**
+     * The resolved render plan: codec, fit policy, area cap and
+     * per-format qualities. The pipeline is a pure consumer of the
+     * variant — everything that decides the output bytes lives in it.
+     */
+    readonly variant: ResolvedImageVariant;
+    readonly ext?: string;
+}): Promise<ImageThumbRenderResult>;
+/**
+ * Encode `sourcePath` to WebP at `destPath`, sized so that
+ * `width × height < maxArea`. Animated sources are kept animated.
+ * @throws `Error` from sharp.
+ */
+declare function renderImageWithArea(sourcePath: string, destPath: string, maxArea: number, quality: number, animated: boolean): Promise<RenderResult>;
+/**
+ * Capture a frame from a file path or readable stream via ffmpeg and
+ * encode, sized so that `width × height < maxArea`.
+ * @throws `Error` with ffmpeg stderr when ffmpeg exits non-zero.
+ */
+declare function renderVideoFrame(opts: {
+    readonly source: VideoFrameSource;
+    readonly destPath: string;
+    readonly ffmpeg: FfmpegPaths;
+    readonly maxArea: number;
+    readonly quality: number;
+    readonly format?: "webp" | "avif";
+    readonly timeSeconds?: number;
+    /** Required when `source` is a stream — ffmpeg cannot infer container from `pipe:0`. */
+    readonly ext?: string;
+}): Promise<RenderResult>;
+/**
+ * Extract an audio file's embedded artwork (ID3 APIC, FLAC PICTURE, MP4
+ * `covr`) and encode it as a thumbnail. ffmpeg exposes the artwork as a
+ * still video stream, so this rides the same still-frame pipeline as
+ * {@link renderVideoFrame} — only the container hint differs.
+ * @throws `Error` with ffmpeg stderr when the file carries no artwork.
+ */
+declare function renderAudioCoverArt(opts: {
+    readonly source: VideoFrameSource;
+    readonly destPath: string;
+    readonly ffmpeg: FfmpegPaths;
+    readonly maxArea: number;
+    readonly quality: number;
+    readonly format?: "webp" | "avif";
+    /** Required when `source` is a stream — ffmpeg cannot infer container from `pipe:0`. */
+    readonly ext?: string;
+}): Promise<RenderResult>;
+/**
+ * Compute target pixel dimensions that keep the aspect ratio while
+ * guaranteeing `width × height < maxArea`.
+ */
+declare function fitInsideArea(srcWidth: number, srcHeight: number, maxArea: number): {
+    readonly width: number;
+    readonly height: number;
+};
+
+export { ANIMATED_AREA_DIVISOR, AVIF_EFFORT, AVIF_QUALITY, type FfmpegPaths, type ImageThumbInput, type ImageThumbRenderResult, PREVIEW_AVIF_QUALITY, PREVIEW_WEBP_QUALITY, type RenderResult, type VideoFrameSource, WEBP_QUALITY, cleanOrphanedTempFiles, fitInsideArea, renderAudioCoverArt, renderImageThumbOnce, renderImageWithArea, renderVideoFrame, resolveFfmpegPaths };

package/dist/render/index.js

@@ -0,0 +1,430 @@
+import { createRequire } from 'module';
+import { spawn } from 'child_process';
+import { readdir, rm, mkdir, rename } from 'fs/promises';
+import { join, extname, dirname } from 'path';
+import sharp from 'sharp';
+import { AUDIO_FFMPEG_INPUT_FORMAT } from '@hoardodile/sdk-types/media-exts';
+import 'crypto';
+import '@hoardodile/sdk-types';
+
+// src/render/ffmpeg.ts
+var requireCjs = createRequire(import.meta.url);
+function resolveFfmpegPaths(deps = {}) {
+  const env = deps.env ?? process.env;
+  const ffmpegEnv = env.FFMPEG_PATH;
+  const ffprobeEnv = env.FFPROBE_PATH;
+  const staticFfmpeg = ffmpegEnv === void 0 || ffmpegEnv.length === 0 ? (deps.loadStatic ?? loadInstallerFfmpeg)() : void 0;
+  const ffmpeg = ffmpegEnv !== void 0 && ffmpegEnv.length > 0 ? ffmpegEnv : staticFfmpeg ?? "ffmpeg";
+  const staticFfprobe = ffprobeEnv === void 0 || ffprobeEnv.length === 0 ? (deps.loadStaticFfprobe ?? loadInstallerFfprobe)() : void 0;
+  const ffprobe = ffprobeEnv !== void 0 && ffprobeEnv.length > 0 ? ffprobeEnv : staticFfprobe ?? "ffprobe";
+  return { ffmpeg, ffprobe };
+}
+function loadInstallerFfmpeg() {
+  return loadInstallerPath("ffmpeg-static");
+}
+function loadInstallerFfprobe() {
+  return loadInstallerPath("@derhuerst/ffprobe-static");
+}
+function loadInstallerPath(moduleName) {
+  try {
+    const mod = requireCjs(moduleName);
+    if (typeof mod === "string" && mod.length > 0) return mod;
+    if (mod !== null && typeof mod === "object" && "path" in mod && typeof mod.path === "string") {
+      return mod.path;
+    }
+    return void 0;
+  } catch {
+    return void 0;
+  }
+}
+function extToAudioInputFormat(ext) {
+  return AUDIO_FFMPEG_INPUT_FORMAT[ext.toLowerCase()];
+}
+
+// src/probe/video.ts
+var FFMPEG_INPUT_FORMAT = {
+  ".mp4": "mp4",
+  ".m4v": "mp4",
+  ".webm": "webm",
+  ".mov": "mov",
+  ".mkv": "matroska",
+  ".avi": "avi"
+};
+function extToFfmpegInputFormat(ext) {
+  return FFMPEG_INPUT_FORMAT[ext.toLowerCase()];
+}
+var PROBE_HEADER_BYTES = 256 * 1024;
+
+// src/probe/image.ts
+var THUMB_BUFFER_MAX_BYTES = 32 * 1024 * 1024;
+var sharpPromise;
+function loadSharp() {
+  sharpPromise ??= import('sharp').catch((err) => {
+    sharpPromise = void 0;
+    throw new Error(
+      `sharp is not installed \u2014 add "sharp" to your dependencies to enable image probing: ${err instanceof Error ? err.message : String(err)}`
+    );
+  });
+  return sharpPromise;
+}
+var ANIMATED_EXT_HINTS = /* @__PURE__ */ new Set([".gif", ".webp", ".avif"]);
+async function sharpFromReadable(stream, options) {
+  if (typeof stream.read !== "function") {
+    throw new Error("expected a readable stream");
+  }
+  const { default: sharp2 } = await loadSharp();
+  const descriptor = options === void 0 || Object.keys(options).length === 0 ? void 0 : { ...options };
+  const instance = descriptor === void 0 ? sharp2() : sharp2(descriptor);
+  stream.pipe(instance);
+  return instance;
+}
+function isReadable(input) {
+  return typeof input === "object" && input !== null && typeof input.pipe === "function" && !("openStream" in input);
+}
+function isReopenableImageStream(input) {
+  return typeof input === "object" && input !== null && !Buffer.isBuffer(input) && "openStream" in input && typeof input.openStream === "function";
+}
+function sharpImageInputOpts(input, ext, pages, animated) {
+  const opts = { pages };
+  if (animated === true) opts.animated = true;
+  if (typeof input === "string" && (ext === ".jpg" || ext === ".jpeg" || ext === ".jfif")) {
+    opts.sequentialRead = true;
+  }
+  return opts;
+}
+function needsFullAnimationScan(meta, ext) {
+  if (ext === ".gif") return true;
+  if (ANIMATED_EXT_HINTS.has(ext) && (meta.pages ?? 1) > 1) return true;
+  if (meta.pageHeight !== void 0 && meta.height !== void 0 && meta.pageHeight !== meta.height) {
+    return true;
+  }
+  return false;
+}
+async function bufferCapped(input, maxBytes) {
+  const chunks = [];
+  let total = 0;
+  for await (const chunk of input) {
+    const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+    total += bytes.byteLength;
+    if (total > maxBytes) {
+      input.destroy();
+      throw new Error(`probe input exceeds the ${maxBytes}-byte cap`);
+    }
+    chunks.push(bytes);
+  }
+  return Buffer.concat(chunks);
+}
+async function readImageMetadata(input, ext) {
+  if (isReopenableImageStream(input)) {
+    if (input.readRange !== void 0 && ext !== ".gif") {
+      const head = await input.readRange(0, PROBE_HEADER_BYTES);
+      if (head.length > 0) {
+        try {
+          const { default: sharp3 } = await loadSharp();
+          const shallowMeta3 = await sharp3(
+            head,
+            sharpImageInputOpts(head, ext, 1)
+          ).metadata();
+          if (!needsFullAnimationScan(shallowMeta3, ext)) {
+            return { meta: shallowMeta3, animated: false };
+          }
+        } catch {
+        }
+      }
+    }
+    const stream = await input.openStream();
+    const shallow2 = await sharpFromReadable(stream, { pages: 1 });
+    const shallowMeta2 = await shallow2.metadata();
+    if (!needsFullAnimationScan(shallowMeta2, ext)) {
+      return { meta: shallowMeta2, animated: false };
+    }
+    const fullStream = await input.openStream();
+    const fullMeta2 = await sharpFromReadable(fullStream, {
+      pages: -1,
+      animated: true
+    }).then((s) => s.metadata());
+    return { meta: fullMeta2, animated: (fullMeta2.pages ?? 1) > 1 };
+  }
+  if (isReadable(input)) {
+    if (ext === ".gif") {
+      const data = await bufferCapped(input, THUMB_BUFFER_MAX_BYTES);
+      return readImageMetadata(data, ext);
+    }
+    try {
+      const shallow2 = await sharpFromReadable(input, { pages: 1 });
+      const shallowMeta2 = await shallow2.metadata();
+      if (!needsFullAnimationScan(shallowMeta2, ext)) {
+        return { meta: shallowMeta2, animated: false };
+      }
+      return {
+        meta: shallowMeta2,
+        animated: (shallowMeta2.pages ?? 1) > 1
+      };
+    } finally {
+      input.destroy();
+    }
+  }
+  const { default: sharp2 } = await loadSharp();
+  const shallow = sharp2(input, sharpImageInputOpts(input, ext, 1));
+  const shallowMeta = await shallow.metadata();
+  if (!needsFullAnimationScan(shallowMeta, ext)) {
+    return { meta: shallowMeta, animated: false };
+  }
+  const fullMeta = await sharp2(
+    input,
+    sharpImageInputOpts(input, ext, -1, true)
+  ).metadata();
+  return { meta: fullMeta, animated: (fullMeta.pages ?? 1) > 1 };
+}
+
+// src/render/pipeline.ts
+var ANIMATED_AREA_DIVISOR = 3;
+var ORPHANED_TEMP_RE = /\.writing-\d+-\d+$/;
+async function cleanOrphanedTempFiles(thumbRoot) {
+  await removeOrphanedInDir(thumbRoot);
+}
+async function removeOrphanedInDir(dir) {
+  let entries;
+  try {
+    entries = await readdir(dir);
+  } catch {
+    return;
+  }
+  await Promise.all(
+    entries.map(async (entry) => {
+      const full = join(dir, entry);
+      if (ORPHANED_TEMP_RE.test(entry)) {
+        await rm(full, { force: true }).catch(() => {
+        });
+      } else {
+        await removeOrphanedInDir(full);
+      }
+    })
+  );
+}
+var WEBP_QUALITY = 82;
+var PREVIEW_WEBP_QUALITY = 90;
+var AVIF_QUALITY = 65;
+var PREVIEW_AVIF_QUALITY = 70;
+var AVIF_EFFORT = 2;
+function isReopenableImageStream2(input) {
+  return typeof input === "object" && input !== null && !Buffer.isBuffer(input) && "openStream" in input;
+}
+async function renderImageThumbOnce(opts) {
+  const ext = opts.ext ?? (typeof opts.input === "string" ? extname(opts.input).toLowerCase() : "");
+  const { meta, animated } = await readImageMetadata(opts.input, ext);
+  const h = meta.pageHeight ?? meta.height;
+  if (meta.width === void 0 || h === void 0) {
+    throw new Error("image source is missing dimensions");
+  }
+  const requested = opts.variant.format;
+  const format = animated && requested === "avif" ? "webp" : requested;
+  const area = animated ? Math.floor(opts.variant.maxArea / ANIMATED_AREA_DIVISOR) : opts.variant.maxArea;
+  const dims = opts.variant.fit === "exact" ? { width: meta.width, height: h } : fitInsideArea(meta.width, h, area);
+  const destPath = opts.resolveDest(format);
+  await mkdir(dirname(destPath), { recursive: true });
+  const pipeline = isReopenableImageStream2(opts.input) ? await sharpFromReadable(await opts.input.openStream(), {
+    pages: animated ? -1 : 1,
+    animated: animated || void 0
+  }) : sharp(
+    opts.input,
+    sharpImageInputOpts(opts.input, ext, animated ? -1 : 1, animated)
+  );
+  const result = await encodeImageFile(
+    pipeline,
+    destPath,
+    {
+      // `exact` carries no resize bounds: the encoder writes the
+      // source pixels verbatim.
+      maxWidth: opts.variant.fit === "exact" ? void 0 : dims.width,
+      maxHeight: opts.variant.fit === "exact" ? void 0 : dims.height,
+      quality: format === "webp" ? opts.variant.webpQuality : opts.variant.avifQuality,
+      animated: animated || void 0
+    },
+    format
+  );
+  return {
+    ...result,
+    format,
+    displayWidth: dims.width,
+    displayHeight: dims.height,
+    animated
+  };
+}
+async function renderImageWithArea(sourcePath, destPath, maxArea, quality, animated) {
+  await mkdir(dirname(destPath), { recursive: true });
+  return encodeSharpWithArea({
+    pipeline: sharp(sourcePath, { animated }),
+    destPath,
+    maxArea,
+    quality,
+    format: "webp",
+    animated
+  });
+}
+async function renderVideoFrame(opts) {
+  return renderFfmpegStill({
+    ...opts,
+    inputFormat: opts.ext === void 0 ? void 0 : extToFfmpegInputFormat(opts.ext)
+  });
+}
+async function renderAudioCoverArt(opts) {
+  return renderFfmpegStill({
+    ...opts,
+    inputFormat: opts.ext === void 0 ? void 0 : extToAudioInputFormat(opts.ext)
+  });
+}
+async function renderFfmpegStill(opts) {
+  await mkdir(dirname(opts.destPath), { recursive: true });
+  const jpeg = await extractFrameAtTimeJpeg({
+    source: opts.source,
+    timeSeconds: opts.timeSeconds ?? 0,
+    ffmpeg: opts.ffmpeg,
+    inputFormat: opts.inputFormat
+  });
+  return encodeSharpWithArea({
+    pipeline: sharp(jpeg),
+    destPath: opts.destPath,
+    maxArea: opts.maxArea,
+    quality: opts.quality,
+    format: opts.format ?? "avif",
+    animated: false
+  });
+}
+async function encodeSharpWithArea(opts) {
+  const meta = await opts.pipeline.metadata();
+  const h = meta.pageHeight ?? meta.height;
+  const dims = meta.width !== void 0 && h !== void 0 ? fitInsideArea(meta.width, h, opts.maxArea) : void 0;
+  return encodeImageFile(
+    opts.pipeline,
+    opts.destPath,
+    {
+      maxWidth: dims?.width,
+      maxHeight: dims?.height,
+      quality: opts.quality,
+      animated: opts.animated || void 0
+    },
+    opts.format
+  );
+}
+async function encodeImageFile(pipeline, destPath, opts, format) {
+  const tmp = `${destPath}.writing-${process.pid}-${Date.now()}`;
+  try {
+    const oriented = opts.animated === true ? pipeline : pipeline.rotate();
+    const resized = opts.maxWidth === void 0 && opts.maxHeight === void 0 ? oriented : oriented.resize({
+      width: opts.maxWidth,
+      height: opts.maxHeight,
+      fit: "inside",
+      withoutEnlargement: true
+    });
+    const encoded = format === "webp" ? resized.webp({ quality: opts.quality }) : resized.avif({ quality: opts.quality, effort: AVIF_EFFORT });
+    const info = await encoded.toFile(tmp);
+    await rename(tmp, destPath);
+    return { path: destPath, bytes: info.size };
+  } catch (err) {
+    await rm(tmp, { force: true }).catch(() => {
+    });
+    throw err;
+  }
+}
+function fitInsideArea(srcWidth, srcHeight, maxArea) {
+  const area = srcWidth * srcHeight;
+  if (area <= maxArea) return { width: srcWidth, height: srcHeight };
+  const scale = Math.sqrt(maxArea / area);
+  return {
+    width: Math.max(1, Math.floor(srcWidth * scale)),
+    height: Math.max(1, Math.floor(srcHeight * scale))
+  };
+}
+function extractFrameAtTimeJpeg(opts) {
+  if (typeof opts.source === "string") {
+    return extractFrameAtTimeJpegFromPath(opts.source, opts);
+  }
+  return extractFrameAtTimeJpegFromStream(opts.source, opts);
+}
+function extractFrameAtTimeJpegFromPath(sourcePath, opts) {
+  const args = ["-hide_banner", "-loglevel", "error"];
+  if (opts.timeSeconds > 0) {
+    args.push("-ss", String(opts.timeSeconds));
+  }
+  args.push("-i", sourcePath);
+  args.push(
+    "-vf",
+    "scale=iw*sar:ih,scale='min(1024,iw)':-2",
+    "-frames:v",
+    "1",
+    "-f",
+    "image2",
+    "-vcodec",
+    "mjpeg",
+    "pipe:1"
+  );
+  return runFfmpegJpegExtract(args, opts.ffmpeg, void 0);
+}
+function extractFrameAtTimeJpegFromStream(source, opts) {
+  if (opts.inputFormat === void 0) {
+    return Promise.reject(
+      new Error("stream video frame extraction requires an input format hint")
+    );
+  }
+  const args = ["-hide_banner", "-loglevel", "error"];
+  args.push("-probesize", "100M", "-analyzeduration", "100M");
+  args.push("-f", opts.inputFormat, "-i", "pipe:0");
+  if (opts.timeSeconds > 0) {
+    args.push("-ss", String(opts.timeSeconds));
+  }
+  args.push(
+    "-vf",
+    "scale=iw*sar:ih,scale='min(1024,iw)':-2",
+    "-frames:v",
+    "1",
+    "-f",
+    "image2",
+    "-vcodec",
+    "mjpeg",
+    "pipe:1"
+  );
+  return runFfmpegJpegExtract(args, opts.ffmpeg, source);
+}
+function runFfmpegJpegExtract(args, ffmpeg, source) {
+  return new Promise((resolve, reject) => {
+    const fromStream = source !== void 0;
+    const child = spawn(ffmpeg.ffmpeg, args, {
+      stdio: fromStream ? ["pipe", "pipe", "pipe"] : ["ignore", "pipe", "pipe"]
+    });
+    const stdout = child.stdout;
+    const stderr = child.stderr;
+    if (stdout === null || stderr === null) {
+      reject(new Error("ffmpeg stdio was not configured"));
+      return;
+    }
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    stdout.on("data", (chunk) => stdoutChunks.push(chunk));
+    stderr.on("data", (chunk) => stderrChunks.push(chunk));
+    if (source !== void 0) {
+      source.on("error", reject);
+      source.pipe(child.stdin);
+      child.stdin?.on("error", () => {
+      });
+    }
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code !== 0) {
+        const msg = Buffer.concat(stderrChunks).toString("utf8").trim();
+        reject(new Error(`ffmpeg exited ${code}${msg ? `: ${msg}` : ""}`));
+        return;
+      }
+      const out = Buffer.concat(stdoutChunks);
+      if (out.length === 0) {
+        reject(new Error("ffmpeg produced no output"));
+        return;
+      }
+      resolve(out);
+    });
+  });
+}
+
+export { ANIMATED_AREA_DIVISOR, AVIF_EFFORT, AVIF_QUALITY, PREVIEW_AVIF_QUALITY, PREVIEW_WEBP_QUALITY, WEBP_QUALITY, cleanOrphanedTempFiles, fitInsideArea, renderAudioCoverArt, renderImageThumbOnce, renderImageWithArea, renderVideoFrame, resolveFfmpegPaths };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map