simple-ffmpegjs 0.4.4 → 0.5.0

package/src/ffmpeg/subtitle_builder.js

@@ -630,21 +630,175 @@ function loadSubtitleFile(filePath, options, canvasWidth, canvasHeight) {
   return ass;
 }
 
+/**
+ * Regex matching emoji characters: inherently visual + variation-selector emoji.
+ * Captures each emoji (including trailing \uFE0F) as a group.
+ */
+const EMOJI_RE = /(\p{Emoji_Presentation}|\p{Emoji}\uFE0F)/gu;
+
+/**
+ * Segment text into emoji and non-emoji runs, wrapping emoji characters
+ * with ASS \fn override tags to explicitly switch to the emoji font.
+ *
+ * If emojiFont is null/undefined, returns plain escaped text (no font switching).
+ *
+ * @param {string} text - Raw text
+ * @param {string} primaryFont - The main text font family
+ * @param {string|null} emojiFont - The detected emoji font family, or null
+ * @returns {string} ASS-escaped text with inline \fn tags for emoji
+ */
+function segmentTextForASS(text, primaryFont, emojiFont) {
+  if (!emojiFont) return escapeASSText(text);
+
+  let result = "";
+  let lastIndex = 0;
+
+  for (const match of text.matchAll(EMOJI_RE)) {
+    if (match.index > lastIndex) {
+      result += escapeASSText(text.slice(lastIndex, match.index));
+    }
+    result += `{\\fn${emojiFont}}${escapeASSText(match[0])}{\\fn${primaryFont}}`;
+    lastIndex = match.index + match[0].length;
+  }
+
+  if (lastIndex < text.length) {
+    result += escapeASSText(text.slice(lastIndex));
+  }
+
+  return result;
+}
+
+/**
+ * Build ASS content for a text clip that contains emoji.
+ * Uses \pos for pixel-precise positioning and \fad for fade animations.
+ * When emojiFont is provided, emoji characters are wrapped in \fn tags
+ * so libass uses the correct font instead of relying on broken fallback.
+ *
+ * @param {Object} clip - Text clip (already resolved with defaults)
+ * @param {number} canvasWidth - Video width
+ * @param {number} canvasHeight - Video height
+ * @param {string|null} [emojiFont] - Detected system emoji font name, or null
+ * @returns {string} Complete ASS file content
+ */
+function buildTextClipASS(clip, canvasWidth, canvasHeight, emojiFont) {
+  const {
+    text = "",
+    position: clipStart,
+    end: clipEnd,
+    fontFamily = "Sans",
+    fontSize = 48,
+    fontColor = "#FFFFFF",
+    borderColor,
+    borderWidth = 0,
+    shadowColor,
+    shadowX = 0,
+    shadowY = 0,
+    backgroundColor,
+    backgroundOpacity,
+    xPercent,
+    yPercent,
+    x,
+    y,
+    xOffset = 0,
+    yOffset = 0,
+    animation,
+    opacity = 1,
+  } = clip;
+
+  const shadowDepth =
+    shadowColor ? Math.max(Math.abs(shadowX), Math.abs(shadowY), 1) : 0;
+  const borderStyle = backgroundColor ? 3 : 1;
+  const backColor = backgroundColor || shadowColor || "#000000";
+  const backOpacity = backgroundColor
+    ? (typeof backgroundOpacity === "number" ? backgroundOpacity : 0.5)
+    : 0.5;
+
+  let ass = generateASSHeader(canvasWidth, canvasHeight, "Emoji Text");
+
+  ass += generateASSStyles([
+    {
+      name: "EmojiText",
+      fontFamily,
+      fontSize,
+      primaryColor: fontColor,
+      outlineColor: borderColor || "#000000",
+      backColor,
+      outline: borderWidth,
+      shadow: shadowDepth,
+      alignment: 7,
+      borderStyle,
+      marginL: 0,
+      marginR: 0,
+      marginV: 0,
+      opacity,
+      outlineOpacity: borderColor ? 1 : 0,
+    },
+  ]);
+
+  // Compute pixel position for \pos tag
+  // Alignment 7 = top-left, so \an5 override centers the text at \pos(x,y)
+  let posX = canvasWidth / 2;
+  let posY = canvasHeight / 2;
+  if (typeof xPercent === "number") posX = Math.round(xPercent * canvasWidth);
+  else if (typeof x === "number") posX = x;
+  if (typeof yPercent === "number") posY = Math.round(yPercent * canvasHeight);
+  else if (typeof y === "number") posY = y;
+  posX += xOffset;
+  posY += yOffset;
+
+  // Build inline override tags
+  let overrides = `\\an5\\pos(${posX},${posY})`;
+
+  const anim = animation || {};
+  const animType = anim.type || "none";
+  if (animType === "fade-in") {
+    const fadeIn = Math.round((typeof anim.in === "number" ? anim.in : 0.25) * 1000);
+    overrides += `\\fad(${fadeIn},0)`;
+  } else if (animType === "fade-out") {
+    const fadeOut = Math.round((typeof anim.out === "number" ? anim.out : 0.25) * 1000);
+    overrides += `\\fad(0,${fadeOut})`;
+  } else if (animType === "fade-in-out" || animType === "fade") {
+    const fadeIn = Math.round((typeof anim.in === "number" ? anim.in : 0.25) * 1000);
+    const fadeOut = Math.round((typeof anim.out === "number" ? anim.out : fadeIn / 1000) * 1000);
+    overrides += `\\fad(${fadeIn},${fadeOut})`;
+  }
+
+  const segmentedText = segmentTextForASS(text, fontFamily, emojiFont || null);
+  const dialogueText = `{${overrides}}${segmentedText}`;
+
+  ass += generateASSEvents([
+    {
+      start: clipStart,
+      end: clipEnd,
+      style: "EmojiText",
+      text: dialogueText,
+    },
+  ]);
+
+  return ass;
+}
+
 /**
  * Build the FFmpeg filter string for ASS subtitles
  * @param {string} assFilePath - Path to the ASS file
  * @param {string} inputLabel - Current video stream label
+ * @param {Object} [options] - Optional settings
+ * @param {string} [options.fontsDir] - Directory for libass font lookup (for fontFile support)
  * @returns {{ filter: string, finalLabel: string }}
  */
-function buildASSFilter(assFilePath, inputLabel) {
-  // Escape path for FFmpeg filter (must survive two levels of av_get_token)
-  const escapedPath = assFilePath
-    .replace(/\\/g, "/")
-    .replace(/:/g, "\\:")
-    .replace(/'/g, "'\\\\\\''" );
+function buildASSFilter(assFilePath, inputLabel, options) {
+  const escapeFn = (p) =>
+    p.replace(/\\/g, "/").replace(/:/g, "\\:").replace(/'/g, "'\\\\\\''" );
+
+  const escapedPath = escapeFn(assFilePath);
+  let filterParams = `ass='${escapedPath}'`;
+
+  if (options && options.fontsDir) {
+    filterParams += `:fontsdir='${escapeFn(options.fontsDir)}'`;
+  }
 
   const outputLabel = "[outass]";
-  const filter = `${inputLabel}ass='${escapedPath}'${outputLabel}`;
+  const filter = `${inputLabel}${filterParams}${outputLabel}`;
 
   return {
     filter,
@@ -691,6 +845,8 @@ function validateSubtitleClip(clip) {
 module.exports = {
   buildKaraokeASS,
   buildSubtitleASS,
+  buildTextClipASS,
+  segmentTextForASS,
   buildASSFilter,
   loadSubtitleFile,
   parseSRT,

package/src/ffmpeg/text_passes.js

@@ -74,10 +74,12 @@ async function runTextPasses({
   intermediateCrf,
   batchSize = 75,
   onLog,
+  tempDir,
 }) {
   const tempOutputs = [];
   let currentInput = baseOutputPath;
   let passes = 0;
+  const intermediateDir = tempDir || path.dirname(baseOutputPath);
 
   for (let i = 0; i < textWindows.length; i += batchSize) {
     const batch = textWindows.slice(i, i + batchSize);
@@ -89,7 +91,7 @@ async function runTextPasses({
     );
 
     const batchOutput = path.join(
-      path.dirname(baseOutputPath),
+      intermediateDir,
       `textpass_${i}_${path.basename(baseOutputPath)}`
     );
     tempOutputs.push(batchOutput);

package/src/ffmpeg/video_builder.js

@@ -1,5 +1,6 @@
 const DEFAULT_KEN_BURNS_ZOOM = 0.15;
 const DEFAULT_PAN_ZOOM = 1.12;
+const MIN_PAN_ZOOM = 1.04;
 
 function clamp01(value) {
   if (typeof value !== "number" || !Number.isFinite(value)) {
@@ -151,16 +152,20 @@ function resolveKenBurnsOptions(kenBurns, width, height, sourceWidth, sourceHeig
     endY = customEndY;
   }
 
-  // When positions indicate panning but zoom wasn't explicitly set (still at
-  // the default 1.0), apply a default pan zoom.  At zoom=1.0 the zoompan
-  // visible window equals the full image, so (iw - iw/zoom) = 0 and position
-  // values are multiplied by zero — making the pan completely invisible.
+  // At zoom=1.0 the zoompan visible window equals the full image, so
+  // (iw - iw/zoom) = 0 and position values are multiplied by zero — making
+  // any pan completely invisible.  Ensure both zoom endpoints are high enough
+  // for the pan to have a visible range.
+  // When zoom wasn't explicitly provided, use the full default pan zoom.
+  // When it was explicit but below the minimum, nudge it up just enough to
+  // make the pan work without dramatically altering the requested zoom.
   const hasPan = startX !== endX || startY !== endY;
-  const zoomWasExplicit =
-    typeof kb.startZoom === "number" || typeof kb.endZoom === "number";
-  if (hasPan && !zoomWasExplicit && startZoom === 1 && endZoom === 1) {
-    startZoom = DEFAULT_PAN_ZOOM;
-    endZoom = DEFAULT_PAN_ZOOM;
+  if (hasPan) {
+    const zoomWasExplicit =
+      typeof kb.startZoom === "number" || typeof kb.endZoom === "number";
+    const minZoom = zoomWasExplicit ? MIN_PAN_ZOOM : DEFAULT_PAN_ZOOM;
+    if (startZoom < minZoom) startZoom = minZoom;
+    if (endZoom < minZoom) endZoom = minZoom;
   }
 
   return { startZoom, endZoom, startX, startY, endX, endY, easing };
@@ -180,6 +185,27 @@ function computeOverscanWidth(width, startZoom, endZoom) {
   return overscan;
 }
 
+function computeContainedSize(srcW, srcH, outW, outH) {
+  const srcAspect = srcW / srcH;
+  const outAspect = outW / outH;
+  let cw, ch;
+  if (srcAspect > outAspect) {
+    cw = outW;
+    ch = Math.round(outW / srcAspect);
+  } else {
+    ch = outH;
+    cw = Math.round(outH * srcAspect);
+  }
+  if (cw % 2 !== 0) cw += 1;
+  if (ch % 2 !== 0) ch += 1;
+  return { cw, ch };
+}
+
+function resolveImageFit(clip) {
+  if (clip.imageFit) return clip.imageFit;
+  return clip.kenBurns ? "cover" : "blur-fill";
+}
+
 function buildVideoFilter(project, videoClips) {
   let filterComplex = "";
   let videoIndex = 0;
@@ -236,7 +262,6 @@ function buildVideoFilter(project, videoClips) {
     if (clip.type === "image" && clip.kenBurns) {
       const frames = Math.max(1, Math.round(clipDuration * fps));
       const framesMinusOne = Math.max(1, frames - 1);
-      const s = `${width}x${height}`;
 
       const { startZoom, endZoom, startX, startY, endX, endY, easing } =
         resolveKenBurnsOptions(
@@ -246,23 +271,63 @@ function buildVideoFilter(project, videoClips) {
           clip.width,
           clip.height
         );
-      // Overscan provides enough pixel resolution for smooth zoompan motion.
-      const overscanW = computeOverscanWidth(width, startZoom, endZoom);
       const zoomExpr = buildZoomExpr(startZoom, endZoom, framesMinusOne, easing);
       const xPosExpr = buildPositionExpr(startX, endX, framesMinusOne, easing);
       const yPosExpr = buildPositionExpr(startY, endY, framesMinusOne, easing);
       const xExpr = `(iw - iw/zoom)*(${xPosExpr})`;
       const yExpr = `(ih - ih/zoom)*(${yPosExpr})`;
 
-      // Scale to cover target dimensions (upscaling if needed), then center crop
-      // force_original_aspect_ratio=increase ensures image covers the target area
-      // select='eq(n,0)' uses single quotes to protect the comma from the graph parser.
-      // zoompan z/x/y values are also single-quoted — commas inside are literal.
-      filterComplex += `[${inputIndex}:v]select='eq(n,0)',setpts=PTS-STARTPTS,scale=${width}:${height}:force_original_aspect_ratio=increase,setsar=1:1,crop=${width}:${height}:(iw-${width})/2:(ih-${height})/2,scale=${overscanW}:-1,zoompan=z='${zoomExpr}':x='${xExpr}':y='${yExpr}':d=${frames}:s=${s}:fps=${fps},setsar=1:1,settb=1/${fps}${scaledLabel};`;
+      let kbFit = resolveImageFit(clip);
+      const hasSrcDims = typeof clip.width === "number" && typeof clip.height === "number"
+        && clip.width > 0 && clip.height > 0;
+      if ((kbFit === "blur-fill" || kbFit === "contain") && !hasSrcDims) {
+        kbFit = "cover";
+      }
+
+      if (kbFit === "blur-fill") {
+        const { cw, ch } = computeContainedSize(clip.width, clip.height, width, height);
+        const sigma = typeof clip.blurIntensity === "number" && Number.isFinite(clip.blurIntensity) && clip.blurIntensity > 0
+          ? clip.blurIntensity : 40;
+        const overscanCW = computeOverscanWidth(cw, startZoom, endZoom);
+        const cs = `${cw}x${ch}`;
+        const kbbgLabel = `[kbbg${videoIndex}]`;
+        const kbfgLabel = `[kbfg${videoIndex}]`;
+        const kbbgrLabel = `[kbbgr${videoIndex}]`;
+        const kbfgrLabel = `[kbfgr${videoIndex}]`;
+        filterComplex += `[${inputIndex}:v]select='eq(n,0)',setpts=PTS-STARTPTS,split${kbbgLabel}${kbfgLabel};`;
+        filterComplex += `${kbbgLabel}scale=${width}:${height}:force_original_aspect_ratio=increase,crop=${width}:${height}:(iw-${width})/2:(ih-${height})/2,gblur=sigma=${sigma},loop=${frames - 1}:1:0,setpts=N/${fps}/TB,fps=${fps},settb=1/${fps}${kbbgrLabel};`;
+        filterComplex += `${kbfgLabel}scale=${cw}:${ch}:force_original_aspect_ratio=increase,setsar=1:1,crop=${cw}:${ch}:(iw-${cw})/2:(ih-${ch})/2,scale=${overscanCW}:-1,zoompan=z='${zoomExpr}':x='${xExpr}':y='${yExpr}':d=${frames}:s=${cs}:fps=${fps},setsar=1:1,settb=1/${fps}${kbfgrLabel};`;
+        filterComplex += `${kbbgrLabel}${kbfgrLabel}overlay=(W-w)/2:(H-h)/2,setsar=1:1,settb=1/${fps}${scaledLabel};`;
+      } else if (kbFit === "contain") {
+        const { cw, ch } = computeContainedSize(clip.width, clip.height, width, height);
+        const overscanCW = computeOverscanWidth(cw, startZoom, endZoom);
+        const cs = `${cw}x${ch}`;
+        filterComplex += `[${inputIndex}:v]select='eq(n,0)',setpts=PTS-STARTPTS,scale=${cw}:${ch}:force_original_aspect_ratio=increase,setsar=1:1,crop=${cw}:${ch}:(iw-${cw})/2:(ih-${ch})/2,scale=${overscanCW}:-1,zoompan=z='${zoomExpr}':x='${xExpr}':y='${yExpr}':d=${frames}:s=${cs}:fps=${fps},setsar=1:1,pad=${width}:${height}:(ow-iw)/2:(oh-ih)/2,settb=1/${fps}${scaledLabel};`;
+      } else {
+        const s = `${width}x${height}`;
+        const overscanW = computeOverscanWidth(width, startZoom, endZoom);
+        filterComplex += `[${inputIndex}:v]select='eq(n,0)',setpts=PTS-STARTPTS,scale=${width}:${height}:force_original_aspect_ratio=increase,setsar=1:1,crop=${width}:${height}:(iw-${width})/2:(ih-${height})/2,scale=${overscanW}:-1,zoompan=z='${zoomExpr}':x='${xExpr}':y='${yExpr}':d=${frames}:s=${s}:fps=${fps},setsar=1:1,settb=1/${fps}${scaledLabel};`;
+      }
     } else {
-      filterComplex += `[${inputIndex}:v]trim=start=${
-        clip.cutFrom || 0
-      }:duration=${clipDuration},setpts=PTS-STARTPTS,fps=${fps},scale=${width}:${height}:force_original_aspect_ratio=decrease,pad=${width}:${height}:(ow-iw)/2:(oh-ih)/2,setsar=1:1,settb=1/${fps}${scaledLabel};`;
+      const fit = clip.type === "image" ? resolveImageFit(clip) : null;
+      const trimPrefix = `[${inputIndex}:v]trim=start=${clip.cutFrom || 0}:duration=${clipDuration},setpts=PTS-STARTPTS,fps=${fps}`;
+
+      if (fit === "blur-fill") {
+        const sigma = typeof clip.blurIntensity === "number" && Number.isFinite(clip.blurIntensity) && clip.blurIntensity > 0
+          ? clip.blurIntensity : 40;
+        const bgLabel = `[bg${videoIndex}]`;
+        const fgLabel = `[fg${videoIndex}]`;
+        const bgrLabel = `[bgr${videoIndex}]`;
+        const fgrLabel = `[fgr${videoIndex}]`;
+        filterComplex += `${trimPrefix},split${bgLabel}${fgLabel};`;
+        filterComplex += `${bgLabel}scale=${width}:${height}:force_original_aspect_ratio=increase,crop=${width}:${height}:(iw-${width})/2:(ih-${height})/2,gblur=sigma=${sigma}${bgrLabel};`;
+        filterComplex += `${fgLabel}scale=${width}:${height}:force_original_aspect_ratio=decrease${fgrLabel};`;
+        filterComplex += `${bgrLabel}${fgrLabel}overlay=(W-w)/2:(H-h)/2,setsar=1:1,settb=1/${fps}${scaledLabel};`;
+      } else if (fit === "cover") {
+        filterComplex += `${trimPrefix},scale=${width}:${height}:force_original_aspect_ratio=increase,crop=${width}:${height}:(iw-${width})/2:(ih-${height})/2,setsar=1:1,settb=1/${fps}${scaledLabel};`;
+      } else {
+        filterComplex += `${trimPrefix},scale=${width}:${height}:force_original_aspect_ratio=decrease,pad=${width}:${height}:(ow-iw)/2:(oh-ih)/2,setsar=1:1,settb=1/${fps}${scaledLabel};`;
+      }
     }
 
     scaledStreams.push({

package/src/loaders.js

@@ -236,7 +236,7 @@ async function loadColor(project, clipObj) {
     const ppmBuffer = generateGradientPPM(width, height, clipObj.color);
 
     const tempPath = path.join(
-      os.tmpdir(),
+      project.options.tempDir || os.tmpdir(),
       `simpleffmpeg-gradient-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.ppm`
     );
     fs.writeFileSync(tempPath, ppmBuffer);

package/src/schema/modules/image.js

@@ -12,6 +12,8 @@ module.exports = {
   width?: number;                           // Optional: source image width (skip probe / override)
   height?: number;                          // Optional: source image height (skip probe / override)
   kenBurns?: KenBurnsEffect | KenBurnsSpec; // Optional: apply pan/zoom motion to the image
+  imageFit?: ImageFit;                     // Optional: how to fit image when aspect ratio differs from output (default: "blur-fill" without Ken Burns, "cover" with Ken Burns)
+  blurIntensity?: number;                  // Optional: blur strength for blur-fill background (Gaussian sigma). Default: 40. Higher = blurrier. Typical range: 10-80.
 }`,
   enums: {
     KenBurnsEffect: [
@@ -26,6 +28,7 @@ module.exports = {
     ],
     KenBurnsAnchor: ["top", "bottom", "left", "right"],
     KenBurnsEasing: ["linear", "ease-in", "ease-out", "ease-in-out"],
+    ImageFit: ["cover", "contain", "blur-fill"],
   },
   examples: [
     {
@@ -48,11 +51,24 @@ module.exports = {
       label: "Custom Ken Burns with explicit pan endpoints",
       code: `{ type: "image", url: "photo.jpg", duration: 4, kenBurns: { type: "custom", startX: 0.2, startY: 0.8, endX: 0.7, endY: 0.3 } }`,
     },
+    {
+      label: "Landscape image in portrait video with blurred background (default)",
+      code: `{ type: "image", url: "landscape.jpg", duration: 5 }`,
+    },
+    {
+      label: "Image with black bar padding (contain)",
+      code: `{ type: "image", url: "landscape.jpg", duration: 5, imageFit: "contain" }`,
+    },
+    {
+      label: "Image scaled to fill frame (cover, crops excess)",
+      code: `{ type: "image", url: "landscape.jpg", duration: 5, imageFit: "cover" }`,
+    },
   ],
   notes: [
     "If position is omitted, the clip is placed immediately after the previous video/image clip (auto-sequencing). The first clip defaults to position 0.",
     "Use duration instead of end to specify how long the image displays: end = position + duration. Cannot use both.",
-    "Images are scaled to fill the project canvas. For Ken Burns, use images at least as large as the output resolution for best quality.",
+    "imageFit controls how images are fitted when their aspect ratio differs from the output: 'blur-fill' (default) fills empty space with a blurred version of the image, 'cover' scales up and crops to fill the frame, 'contain' pads with black bars.",
+    "Ken Burns defaults to 'cover' but respects imageFit when set. With 'blur-fill' or 'contain', the Ken Burns motion applies to the contained image while the background stays static. Source dimensions (width/height) are required for KB + blur-fill/contain; without them it falls back to cover.",
     "If width/height are provided, they override probed dimensions (useful for remote or generated images).",
     "Image clips can be placed on the same timeline as video clips and can use transitions between them.",
     "Advanced Ken Burns accepts custom zoom/pan endpoints via normalized coordinates (0 = left/top, 1 = right/bottom).",