@postfetch/core 0.9.3 → 0.10.1

package/README.md

@@ -24,9 +24,33 @@ defaults to off, uses `ffmpeg` and `ffprobe` from `PATH` unless their paths are
 set, and throws if the complete result cannot be produced. The legacy
 `(url, headers?, options?)` overload remains supported for non-remux downloads.
 
+`buildAudioSliderVideo(items, { delay: 3000 })` returns an MP4 `Blob` from one or
+more images/videos followed by exactly one audio item. `delay` is the minimum
+milliseconds per visual. The actual slot is the larger of that minimum and
+audio duration / visual count, rounded up to 30 fps (minimum two frames), so
+the complete audio plays. Slots include a right-to-left transition lasting up
+to 300 ms or half the slot. The last visual stays visible;
+a single visual has no transition. Total duration is visual count × computed
+slot duration. Videos loop or trim to fit and their own audio is discarded; the trailing
+audio loops and trims only when the minimum makes the slideshow longer than the
+track. Otherwise it plays once, padding the rounding remainder with silence.
+The default 720×1280 canvas preserves
+aspect ratio with black padding. `AudioSliderVideoOptions` supports `width` and
+`height` (positive even integers), `fetch`, `ffmpegPath`, and `ffprobePath`. Requires
+local FFprobe, FFmpeg with `libx264` and a runtime with filesystem/process access (Node, Bun,
+Deno). Downloads retain item headers and assemble HLS; temporary files are
+cleaned up on success and failure.
+
+```ts
+import { buildAudioSliderVideo } from "@postfetch/core";
+
+const blob = await buildAudioSliderVideo(result.items, { delay: 3000 });
+form.append("video", blob, "slideshow.mp4");
+```
+
 - `PostfetchOptions` — `{ fetch?: typeof fetch; preferredWidth?: number; tryMaxBytes?: number }`. `tryMaxBytes` is a soft byte cap. X probes every MP4 variant and selects the highest-quality complete result that fits, falling back to its smallest variants when none do. Other platforms return a smaller available rendition when possible and otherwise keep the normal result. Inject `fetch` to unit-test resolvers offline.
 - Every request rotates a consistent browser/app fingerprint, so a fixed user-agent never gets the whole fleet blocked.
 - No runtime dependencies, no `yt-dlp`, no cookies. `ffmpeg` is only used when
-  the opt-in `downloadBlob(..., { remux: true })` path is requested.
+  `downloadBlob(..., { remux: true })` or `buildAudioSliderVideo` is requested.
 
 See the [root README](https://github.com/chelokot/postfetch#readme) for the full API table, supported inputs and the fingerprint design.

package/dist/audio-slider.d.ts

@@ -0,0 +1,40 @@
+import { type DownloadOptions } from "./download";
+import { type MediaItem } from "./internal";
+/** Options for {@link buildAudioSliderVideo}. Requires a local FFmpeg binary. */
+export type AudioSliderVideoOptions = DownloadOptions & {
+    /** Minimum time per visual item in milliseconds, including its outgoing transition. */
+    delay: number;
+    /** Output width in pixels; a positive even integer. Defaults to 720. */
+    width?: number;
+    /** Output height in pixels; a positive even integer. Defaults to 1280. */
+    height?: number;
+    /** FFmpeg command or executable path. Defaults to `ffmpeg` from PATH. */
+    ffmpegPath?: string;
+    /** FFprobe command or executable path used to measure audio. Defaults to `ffprobe`. */
+    ffprobePath?: string;
+};
+/**
+ * Build an H.264/AAC MP4 Blob from one or more images/videos followed by exactly
+ * one audio item. Downloads preserve each item's headers and assemble HLS.
+ * Visuals retain their aspect ratio, padded with black to the output size.
+ * Video clips play from the beginning, looping or trimming to fit; their own
+ * audio is discarded. The final audio item plays in full; when the minimum
+ * slideshow duration is longer, it loops and is trimmed to the result.
+ *
+ * Each visual gets at least `delay` ms or audio duration / visual count,
+ * whichever is longer (rounded up to 30 fps, minimum two frames). Adjacent
+ * visuals slide right to left over the last 300 ms or half the slot, whichever
+ * is shorter. The last visual stays on screen; a single visual has no transition.
+ * Total duration is the number of visuals times the computed slot duration.
+ *
+ * Requires Node, Bun or Deno with filesystem/process access, FFprobe and FFmpeg
+ * with libx264. Temporary files are removed on success and failure.
+ *
+ * @example
+ * ```ts
+ * const result = await postfetch(photoUrl);
+ * const blob = await buildAudioSliderVideo(result.items, { delay: 3000 });
+ * form.append("video", blob, "slideshow.mp4");
+ * ```
+ */
+export declare function buildAudioSliderVideo(items: readonly MediaItem[], options: AudioSliderVideoOptions): Promise<Blob>;

package/dist/index.d.ts

@@ -20,6 +20,7 @@
  * @module
  */
 export { postfetch, detect, type PostfetchOptions } from "./postfetch";
+export { buildAudioSliderVideo, type AudioSliderVideoOptions } from "./audio-slider";
 export { download, downloadBlob, archive, toResponse, type Archive, type DownloadBlobOptions, type DownloadOptions, type RemuxedVideo, } from "./download";
 export { PostfetchError } from "./internal";
 export type { InstagramExtra, MediaItem, MediaKind, PinterestExtra, Platform, PlatformResult, PostAuthor, PostfetchReason, PostfetchResult, PostMetadata, RedditExtra, SoundcloudExtra, TiktokExtra, TwitterExtra, TwitterQuotedTweet, YoutubeExtra, } from "./internal";

package/dist/index.js

@@ -3313,12 +3313,112 @@ async function fetchBytes(net, url, headers) {
 function toArrayBuffer(bytes) {
   return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
 }
+
+// src/audio-slider.ts
+var fps = 30;
+async function buildAudioSliderVideo(items, options) {
+  if (!Array.isArray(items) || items.length < 2 || items.at(-1)?.kind !== "audio" || Array.from(items.slice(0, -1)).some((item) => item?.kind !== "image" && item?.kind !== "video")) {
+    throw new PostfetchError(400, "Expected one or more image/video items followed by exactly one audio item");
+  }
+  if (!options || !Number.isFinite(options.delay) || options.delay <= 0) {
+    throw new PostfetchError(400, "delay must be a positive finite number of milliseconds");
+  }
+  const width = options.width ?? 720;
+  const height2 = options.height ?? 1280;
+  for (const [name, value] of [["width", width], ["height", height2]]) {
+    if (!Number.isSafeInteger(value) || value <= 0 || value % 2 !== 0) {
+      throw new PostfetchError(400, `${name} must be a positive even integer`);
+    }
+  }
+  const visuals = items.slice(0, -1);
+  const minimumFrames = Math.max(2, Math.ceil(options.delay * fps / 1000));
+  if (!Number.isSafeInteger(minimumFrames * visuals.length)) {
+    throw new PostfetchError(400, "delay produces an unsupported video duration");
+  }
+  const io = await nodeRuntime();
+  const directory = await io.makeTempDir("postfetch-slider-");
+  try {
+    const paths = [];
+    for (const [index, item] of items.entries()) {
+      const path = `${directory}/input-${index}`;
+      const response = await download(item, options);
+      await io.writeFile(path, new Uint8Array(await response.arrayBuffer()));
+      paths.push(path);
+    }
+    const probe = await io.run(options.ffprobePath ?? "ffprobe", [
+      "-v",
+      "error",
+      "-select_streams",
+      "a:0",
+      "-show_entries",
+      "stream=duration:format=duration",
+      "-of",
+      "json",
+      paths[visuals.length]
+    ]);
+    if (!probe.success) {
+      throw new PostfetchError(500, `Audio slider duration probe failed: ${probe.stderr}`);
+    }
+    const audioDuration = readAudioDuration(probe.stdout);
+    const frames = Math.max(minimumFrames, Math.ceil(audioDuration * fps / visuals.length));
+    if (!Number.isSafeInteger(frames * visuals.length)) {
+      throw new PostfetchError(500, "Audio slider duration is too large");
+    }
+    const seconds = frames / fps;
+    const transition = Math.min(0.3, seconds / 2);
+    const duration = seconds * visuals.length;
+    const args = ["-nostdin", "-hide_banner", "-loglevel", "error", "-y", "-filter_complex_threads", "1"];
+    for (const [index, item] of visuals.entries()) {
+      args.push(...item.kind === "image" ? ["-loop", "1", "-framerate", String(fps)] : ["-stream_loop", "-1"]);
+      args.push("-i", paths[index]);
+    }
+    if (audioDuration < minimumFrames * visuals.length / fps) {
+      args.push("-stream_loop", "-1");
+    }
+    args.push("-i", paths[visuals.length]);
+    const filters = visuals.map((_, index) => `[${index}:v:0]setpts=PTS-STARTPTS,` + `scale=${width}:${height2}:force_original_aspect_ratio=decrease:force_divisible_by=2,` + `pad=${width}:${height2}:(ow-iw)/2:(oh-ih)/2,setsar=1,fps=${fps},` + `format=yuv444p,trim=duration=${seconds + (index > 0 ? transition : 0)},setpts=PTS-STARTPTS,fps=${fps},settb=AVTB[v${index}]`);
+    let current = "v0";
+    for (let index = 1;index < visuals.length; index += 1) {
+      const next = `slide${index}`;
+      filters.push(`[${current}][v${index}]xfade=transition=slideleft:duration=${transition}:offset=${index * seconds - transition},fps=${fps},settb=AVTB[${next}]`);
+      current = next;
+    }
+    filters.push(`[${current}]format=yuv420p[outv]`);
+    filters.push(`[${visuals.length}:a:0]asetpts=PTS-STARTPTS,apad,atrim=duration=${duration}[outa]`);
+    const output = `${directory}/slideshow.mp4`;
+    args.push("-filter_complex", filters.join(";"), "-map", "[outv]", "-map", "[outa]", "-t", String(duration), "-c:v", "libx264", "-preset", "veryfast", "-crf", "23", "-c:a", "aac", "-b:a", "192k", "-movflags", "+faststart", output);
+    const result = await io.run(options.ffmpegPath ?? "ffmpeg", args);
+    if (!result.success) {
+      throw new PostfetchError(500, `Audio slider video encoding failed: ${result.stderr}`);
+    }
+    const bytes = await io.readFile(output);
+    if (bytes.length === 0) {
+      throw new PostfetchError(500, "Audio slider video encoding produced an empty file");
+    }
+    return new Blob([new Uint8Array(bytes).buffer], { type: "video/mp4" });
+  } finally {
+    await io.removeDir(directory).catch(() => {
+      return;
+    });
+  }
+}
+function readAudioDuration(stdout) {
+  try {
+    const parsed = JSON.parse(stdout);
+    const stream = parsed.streams?.[0];
+    const duration = [stream?.duration, parsed.format?.duration].map(Number).find((value) => Number.isFinite(value) && value > 0);
+    if (stream && duration !== undefined)
+      return duration;
+  } catch {}
+  throw new PostfetchError(500, "Audio slider audio duration is unavailable");
+}
 export {
   toResponse,
   postfetch,
   downloadBlob,
   download,
   detect,
+  buildAudioSliderVideo,
   archive,
   PostfetchError
 };

package/dist/mp4-remux.d.ts

@@ -23,4 +23,5 @@ export type Mp4RemuxRuntime = {
  * FFmpeg only rebuilds the container and timing tables.
  */
 export declare function prepareMp4(bytes: Uint8Array, ffmpegPath?: string, ffprobePath?: string, runtime?: Mp4RemuxRuntime): Promise<PreparedMp4 | null>;
+export declare function nodeRuntime(): Promise<Mp4RemuxRuntime>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postfetch/core",
-  "version": "0.9.3",
+  "version": "0.10.1",
   "description": "Zero-dependency typed core that turns Facebook, Instagram, LinkedIn, Pinterest, Reddit, SoundCloud, TikTok, X and YouTube post URLs into media files.",
   "license": "MIT",
   "type": "module",

package/src/audio-slider.ts

@@ -0,0 +1,152 @@
+import { download, type DownloadOptions } from "./download";
+import { PostfetchError, type MediaItem } from "./internal";
+import { nodeRuntime } from "./mp4-remux";
+
+/** Options for {@link buildAudioSliderVideo}. Requires a local FFmpeg binary. */
+export type AudioSliderVideoOptions = DownloadOptions & {
+  /** Minimum time per visual item in milliseconds, including its outgoing transition. */
+  delay: number;
+  /** Output width in pixels; a positive even integer. Defaults to 720. */
+  width?: number;
+  /** Output height in pixels; a positive even integer. Defaults to 1280. */
+  height?: number;
+  /** FFmpeg command or executable path. Defaults to `ffmpeg` from PATH. */
+  ffmpegPath?: string;
+  /** FFprobe command or executable path used to measure audio. Defaults to `ffprobe`. */
+  ffprobePath?: string;
+};
+
+const fps = 30;
+
+/**
+ * Build an H.264/AAC MP4 Blob from one or more images/videos followed by exactly
+ * one audio item. Downloads preserve each item's headers and assemble HLS.
+ * Visuals retain their aspect ratio, padded with black to the output size.
+ * Video clips play from the beginning, looping or trimming to fit; their own
+ * audio is discarded. The final audio item plays in full; when the minimum
+ * slideshow duration is longer, it loops and is trimmed to the result.
+ *
+ * Each visual gets at least `delay` ms or audio duration / visual count,
+ * whichever is longer (rounded up to 30 fps, minimum two frames). Adjacent
+ * visuals slide right to left over the last 300 ms or half the slot, whichever
+ * is shorter. The last visual stays on screen; a single visual has no transition.
+ * Total duration is the number of visuals times the computed slot duration.
+ *
+ * Requires Node, Bun or Deno with filesystem/process access, FFprobe and FFmpeg
+ * with libx264. Temporary files are removed on success and failure.
+ *
+ * @example
+ * ```ts
+ * const result = await postfetch(photoUrl);
+ * const blob = await buildAudioSliderVideo(result.items, { delay: 3000 });
+ * form.append("video", blob, "slideshow.mp4");
+ * ```
+ */
+export async function buildAudioSliderVideo(
+  items: readonly MediaItem[],
+  options: AudioSliderVideoOptions,
+): Promise<Blob> {
+  if (
+    !Array.isArray(items) || items.length < 2 || items.at(-1)?.kind !== "audio" ||
+    Array.from(items.slice(0, -1)).some((item) => item?.kind !== "image" && item?.kind !== "video")
+  ) {
+    throw new PostfetchError(400, "Expected one or more image/video items followed by exactly one audio item");
+  }
+  if (!options || !Number.isFinite(options.delay) || options.delay <= 0) {
+    throw new PostfetchError(400, "delay must be a positive finite number of milliseconds");
+  }
+  const width = options.width ?? 720;
+  const height = options.height ?? 1280;
+  for (const [name, value] of [["width", width], ["height", height]] as const) {
+    if (!Number.isSafeInteger(value) || value <= 0 || value % 2 !== 0) {
+      throw new PostfetchError(400, `${name} must be a positive even integer`);
+    }
+  }
+  const visuals = items.slice(0, -1);
+  const minimumFrames = Math.max(2, Math.ceil(options.delay * fps / 1000));
+  if (!Number.isSafeInteger(minimumFrames * visuals.length)) {
+    throw new PostfetchError(400, "delay produces an unsupported video duration");
+  }
+  const io = await nodeRuntime();
+  const directory = await io.makeTempDir("postfetch-slider-");
+  try {
+    // Numbered local paths keep remote filenames out of FFmpeg arguments.
+    const paths: string[] = [];
+    for (const [index, item] of items.entries()) {
+      const path = `${directory}/input-${index}`;
+      const response = await download(item, options);
+      await io.writeFile(path, new Uint8Array(await response.arrayBuffer()));
+      paths.push(path);
+    }
+    const probe = await io.run(options.ffprobePath ?? "ffprobe", [
+      "-v", "error", "-select_streams", "a:0", "-show_entries",
+      "stream=duration:format=duration", "-of", "json", paths[visuals.length],
+    ]);
+    if (!probe.success) {
+      throw new PostfetchError(500, `Audio slider duration probe failed: ${probe.stderr}`);
+    }
+    const audioDuration = readAudioDuration(probe.stdout);
+    const frames = Math.max(minimumFrames, Math.ceil(audioDuration * fps / visuals.length));
+    if (!Number.isSafeInteger(frames * visuals.length)) {
+      throw new PostfetchError(500, "Audio slider duration is too large");
+    }
+    const seconds = frames / fps;
+    const transition = Math.min(0.3, seconds / 2);
+    const duration = seconds * visuals.length;
+    const args = ["-nostdin", "-hide_banner", "-loglevel", "error", "-y", "-filter_complex_threads", "1"];
+    for (const [index, item] of visuals.entries()) {
+      args.push(...(item.kind === "image" ? ["-loop", "1", "-framerate", String(fps)] : ["-stream_loop", "-1"]));
+      args.push("-i", paths[index]);
+    }
+    // If the track sets the duration, play it once and pad only the frame-rounding
+    // remainder; do not start the song again for a fraction of a second.
+    if (audioDuration < minimumFrames * visuals.length / fps) {
+      args.push("-stream_loop", "-1");
+    }
+    args.push("-i", paths[visuals.length]);
+    const filters = visuals.map((_, index) =>
+      `[${index}:v:0]setpts=PTS-STARTPTS,` +
+      `scale=${width}:${height}:force_original_aspect_ratio=decrease:force_divisible_by=2,` +
+      `pad=${width}:${height}:(ow-iw)/2:(oh-ih)/2,setsar=1,fps=${fps},` +
+      `format=yuv444p,trim=duration=${seconds + (index > 0 ? transition : 0)},setpts=PTS-STARTPTS,fps=${fps},settb=AVTB[v${index}]`,
+    );
+    let current = "v0";
+    for (let index = 1; index < visuals.length; index += 1) {
+      const next = `slide${index}`;
+      filters.push(`[${current}][v${index}]xfade=transition=slideleft:duration=${transition}:offset=${index * seconds - transition},fps=${fps},settb=AVTB[${next}]`);
+      current = next;
+    }
+    filters.push(`[${current}]format=yuv420p[outv]`);
+    filters.push(`[${visuals.length}:a:0]asetpts=PTS-STARTPTS,apad,atrim=duration=${duration}[outa]`);
+    const output = `${directory}/slideshow.mp4`;
+    args.push(
+      "-filter_complex", filters.join(";"), "-map", "[outv]", "-map", "[outa]",
+      "-t", String(duration), "-c:v", "libx264", "-preset", "veryfast", "-crf", "23",
+      "-c:a", "aac", "-b:a", "192k", "-movflags", "+faststart", output,
+    );
+    const result = await io.run(options.ffmpegPath ?? "ffmpeg", args);
+    if (!result.success) {
+      throw new PostfetchError(500, `Audio slider video encoding failed: ${result.stderr}`);
+    }
+    const bytes = await io.readFile(output);
+    if (bytes.length === 0) {
+      throw new PostfetchError(500, "Audio slider video encoding produced an empty file");
+    }
+    return new Blob([new Uint8Array(bytes).buffer], { type: "video/mp4" });
+  } finally {
+    await io.removeDir(directory).catch(() => undefined);
+  }
+}
+
+function readAudioDuration(stdout: string): number {
+  try {
+    const parsed = JSON.parse(stdout) as { streams?: Array<{ duration?: string }>; format?: { duration?: string } };
+    const stream = parsed.streams?.[0];
+    const duration = [stream?.duration, parsed.format?.duration]
+      .map(Number).find((value) => Number.isFinite(value) && value > 0);
+    if (stream && duration !== undefined) return duration;
+  } catch {
+    // Missing, malformed or non-finite metadata cannot guarantee a complete track.
+  }
+  throw new PostfetchError(500, "Audio slider audio duration is unavailable");
+}

package/src/index.ts

@@ -20,6 +20,7 @@
  * @module
  */
 export { postfetch, detect, type PostfetchOptions } from "./postfetch";
+export { buildAudioSliderVideo, type AudioSliderVideoOptions } from "./audio-slider";
 export {
   download,
   downloadBlob,

package/src/mp4-remux.ts

@@ -161,7 +161,7 @@ function parseVideoMetadata(value: string): Pick<PreparedMp4, "duration" | "heig
 // Deno, Bun and Node all expose the Node compatibility modules used here. They
 // stay behind dynamic imports so browser/edge consumers that leave remux off do
 // not load or execute any process/filesystem code.
-async function nodeRuntime(): Promise<Mp4RemuxRuntime> {
+export async function nodeRuntime(): Promise<Mp4RemuxRuntime> {
   const [{ spawn }, { mkdtemp, readFile, rm, writeFile }, { tmpdir }, { join }] = await Promise.all([
     import("node:child_process"),
     import("node:fs/promises"),