@postfetch/core 0.10.0 → 0.10.1

package/README.md

@@ -25,15 +25,19 @@ 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 milliseconds
-per visual, rounded to 30 fps (minimum two frames), including a right-to-left
-transition lasting up to 300 ms or half the delay. The last visual stays visible;
-a single visual has no transition. Total duration is visual count × rounded
-delay. Videos loop or trim to fit and their own audio is discarded; the trailing
-audio loops and trims to the result. The default 720×1280 canvas preserves
+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`, and `ffmpegPath`. Requires local
-FFmpeg with `libx264` and a runtime with filesystem/process access (Node, Bun,
+`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.
 

package/dist/audio-slider.d.ts

@@ -2,7 +2,7 @@ import { type DownloadOptions } from "./download";
 import { type MediaItem } from "./internal";
 /** Options for {@link buildAudioSliderVideo}. Requires a local FFmpeg binary. */
 export type AudioSliderVideoOptions = DownloadOptions & {
-    /** Time per visual item in milliseconds, including its outgoing transition. */
+    /** 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;
@@ -10,21 +10,25 @@ export type AudioSliderVideoOptions = DownloadOptions & {
     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 loops and is trimmed to the result.
+ * 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 `delay` ms (rounded to 30 fps, minimum two frames). Adjacent
- * visuals slide right to left over the last 300 ms or half the delay, whichever
+ * 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 rounded delay.
+ * Total duration is the number of visuals times the computed slot duration.
  *
- * Requires Node, Bun or Deno with filesystem/process access and FFmpeg with
- * libx264. Temporary files are removed on success and failure.
+ * Requires Node, Bun or Deno with filesystem/process access, FFprobe and FFmpeg
+ * with libx264. Temporary files are removed on success and failure.
  *
  * @example
  * ```ts

package/dist/index.js

@@ -3331,13 +3331,10 @@ async function buildAudioSliderVideo(items, options) {
     }
   }
   const visuals = items.slice(0, -1);
-  const frames = Math.max(2, Math.round(options.delay * fps / 1000));
-  if (!Number.isSafeInteger(frames * visuals.length)) {
+  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 seconds = frames / fps;
-  const transition = Math.min(0.3, seconds / 2);
-  const duration = seconds * visuals.length;
   const io = await nodeRuntime();
   const directory = await io.makeTempDir("postfetch-slider-");
   try {
@@ -3348,12 +3345,37 @@ async function buildAudioSliderVideo(items, 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]);
     }
-    args.push("-stream_loop", "-1", "-i", paths[visuals.length]);
+    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) {
@@ -3362,7 +3384,7 @@ async function buildAudioSliderVideo(items, options) {
       current = next;
     }
     filters.push(`[${current}]format=yuv420p[outv]`);
-    filters.push(`[${visuals.length}:a:0]asetpts=PTS-STARTPTS,atrim=duration=${duration}[outa]`);
+    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);
@@ -3380,6 +3402,16 @@ async function buildAudioSliderVideo(items, options) {
     });
   }
 }
+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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postfetch/core",
-  "version": "0.10.0",
+  "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

@@ -4,7 +4,7 @@ import { nodeRuntime } from "./mp4-remux";
 
 /** Options for {@link buildAudioSliderVideo}. Requires a local FFmpeg binary. */
 export type AudioSliderVideoOptions = DownloadOptions & {
-  /** Time per visual item in milliseconds, including its outgoing transition. */
+  /** 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;
@@ -12,6 +12,8 @@ export type AudioSliderVideoOptions = DownloadOptions & {
   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;
@@ -21,15 +23,17 @@ const fps = 30;
  * 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 loops and is trimmed to the result.
+ * 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 `delay` ms (rounded to 30 fps, minimum two frames). Adjacent
- * visuals slide right to left over the last 300 ms or half the delay, whichever
+ * 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 rounded delay.
+ * Total duration is the number of visuals times the computed slot duration.
  *
- * Requires Node, Bun or Deno with filesystem/process access and FFmpeg with
- * libx264. Temporary files are removed on success and failure.
+ * Requires Node, Bun or Deno with filesystem/process access, FFprobe and FFmpeg
+ * with libx264. Temporary files are removed on success and failure.
  *
  * @example
  * ```ts
@@ -59,13 +63,10 @@ export async function buildAudioSliderVideo(
     }
   }
   const visuals = items.slice(0, -1);
-  const frames = Math.max(2, Math.round(options.delay * fps / 1000));
-  if (!Number.isSafeInteger(frames * visuals.length)) {
+  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 seconds = frames / fps;
-  const transition = Math.min(0.3, seconds / 2);
-  const duration = seconds * visuals.length;
   const io = await nodeRuntime();
   const directory = await io.makeTempDir("postfetch-slider-");
   try {
@@ -77,12 +78,32 @@ export async function buildAudioSliderVideo(
       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]);
     }
-    args.push("-stream_loop", "-1", "-i", paths[visuals.length]);
+    // 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,` +
@@ -96,7 +117,7 @@ export async function buildAudioSliderVideo(
       current = next;
     }
     filters.push(`[${current}]format=yuv420p[outv]`);
-    filters.push(`[${visuals.length}:a:0]asetpts=PTS-STARTPTS,atrim=duration=${duration}[outa]`);
+    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]",
@@ -116,3 +137,16 @@ export async function buildAudioSliderVideo(
     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");
+}