simple-ffmpegjs 0.1.0

package/src/core/validation.js

@@ -0,0 +1,188 @@
+const fs = require("fs");
+
+function validateClips(clips, validationMode = "warn") {
+  const allowedTypes = new Set([
+    "video",
+    "audio",
+    "text",
+    "music",
+    "backgroundAudio",
+    "image",
+  ]);
+  const errors = [];
+  const warnings = [];
+
+  clips.forEach((clip, idx) => {
+    if (!allowedTypes.has(clip.type)) {
+      errors.push(`clip[${idx}]: invalid type '${clip.type}'`);
+      return;
+    }
+
+    const requiresTimeline =
+      clip.type === "video" ||
+      clip.type === "audio" ||
+      clip.type === "text" ||
+      clip.type === "image";
+    if (requiresTimeline) {
+      if (typeof clip.position !== "number" || typeof clip.end !== "number") {
+        errors.push(`clip[${idx}]: 'position' and 'end' must be numbers`);
+      } else {
+        if (clip.position < 0)
+          errors.push(`clip[${idx}]: position must be >= 0`);
+        if (clip.end <= clip.position)
+          errors.push(`clip[${idx}]: end must be > position`);
+      }
+    } else {
+      // music/backgroundAudio: allow missing position/end (defaults later)
+      if (typeof clip.position === "number" && clip.position < 0) {
+        errors.push(`clip[${idx}]: position must be >= 0`);
+      }
+      if (
+        typeof clip.end === "number" &&
+        typeof clip.position === "number" &&
+        clip.end <= clip.position
+      ) {
+        errors.push(`clip[${idx}]: end must be > position`);
+      }
+    }
+
+    // Media clips
+    if (
+      clip.type === "video" ||
+      clip.type === "audio" ||
+      clip.type === "music" ||
+      clip.type === "backgroundAudio" ||
+      clip.type === "image"
+    ) {
+      if (typeof clip.url !== "string" || clip.url.length === 0) {
+        errors.push(`clip[${idx}]: media 'url' is required`);
+      } else {
+        try {
+          if (!fs.existsSync(clip.url)) {
+            warnings.push(`clip[${idx}]: file not found at '${clip.url}'`);
+          }
+        } catch (_) {}
+      }
+      if (typeof clip.cutFrom === "number" && clip.cutFrom < 0) {
+        errors.push(`clip[${idx}]: cutFrom must be >= 0`);
+      }
+      if (
+        (clip.type === "audio" ||
+          clip.type === "music" ||
+          clip.type === "backgroundAudio") &&
+        typeof clip.volume === "number" &&
+        clip.volume < 0
+      ) {
+        errors.push(`clip[${idx}]: volume must be >= 0`);
+      }
+    }
+
+    if (clip.type === "text") {
+      // words windows
+      if (Array.isArray(clip.words)) {
+        clip.words.forEach((w, wi) => {
+          if (
+            typeof w.start !== "number" ||
+            typeof w.end !== "number" ||
+            typeof w.text !== "string"
+          ) {
+            errors.push(`clip[${idx}].words[${wi}]: invalid {text,start,end}`);
+            return;
+          }
+          if (w.end <= w.start) {
+            errors.push(`clip[${idx}].words[${wi}]: end must be > start`);
+          }
+          if (
+            typeof clip.position === "number" &&
+            typeof clip.end === "number"
+          ) {
+            if (w.start < clip.position || w.end > clip.end) {
+              warnings.push(
+                `clip[${idx}].words[${wi}]: window outside [position,end]`
+              );
+            }
+          }
+        });
+      }
+      if (Array.isArray(clip.wordTimestamps)) {
+        const ts = clip.wordTimestamps;
+        for (let i = 1; i < ts.length; i++) {
+          if (
+            !(
+              typeof ts[i] === "number" &&
+              typeof ts[i - 1] === "number" &&
+              ts[i] >= ts[i - 1]
+            )
+          ) {
+            warnings.push(
+              `clip[${idx}].wordTimestamps: not non-decreasing at index ${i}`
+            );
+            break;
+          }
+        }
+      }
+      if (clip.fontFile && !fs.existsSync(clip.fontFile)) {
+        warnings.push(
+          `clip[${idx}]: fontFile '${clip.fontFile}' not found; falling back to fontFamily`
+        );
+      }
+    }
+
+    if (clip.type === "image" && clip.kenBurns) {
+      const kb = clip.kenBurns;
+      const allowedKB = new Set([
+        "zoom-in",
+        "zoom-out",
+        "pan-left",
+        "pan-right",
+        "pan-up",
+        "pan-down",
+      ]);
+      const type = typeof kb === "string" ? kb : kb.type;
+      if (!allowedKB.has(type))
+        errors.push(`clip[${idx}]: kenBurns '${type}' invalid`);
+    }
+  });
+
+  // Visual timeline gap checks (video/image)
+  const visual = clips
+    .map((c, i) => ({ c, i }))
+    .filter(({ c }) => c.type === "video" || c.type === "image")
+    .sort((a, b) => (a.c.position || 0) - (b.c.position || 0));
+
+  if (visual.length > 0) {
+    const eps = 1e-3;
+    // Leading gap
+    if ((visual[0].c.position || 0) > eps) {
+      const start = 0;
+      const end = visual[0].c.position;
+      const msg = `visual gap [${start.toFixed(3)}, ${end.toFixed(
+        3
+      )}) — no video/image content at start`;
+      errors.push(msg);
+    }
+    // Middle gaps
+    for (let i = 1; i < visual.length; i++) {
+      const prev = visual[i - 1].c;
+      const cur = visual[i].c;
+      if ((cur.position || 0) - (prev.end || 0) > eps) {
+        const start = prev.end || 0;
+        const end = cur.position || 0;
+        const msg = `visual gap [${start.toFixed(3)}, ${end.toFixed(
+          3
+        )}) — no video/image content between clips`;
+        errors.push(msg);
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    const msg = `Validation failed:\n - ` + errors.join(`\n - `);
+    throw new Error(msg);
+  }
+  if (validationMode === "warn" && warnings.length > 0) {
+    warnings.forEach((w) => console.warn(w));
+  }
+}
+
+module.exports = { validateClips };

package/src/ffmpeg/audio_builder.js

@@ -0,0 +1,34 @@
+function buildAudioForVideoClips(project, videoClips) {
+  let audioFilter = "";
+  const labels = [];
+
+  videoClips.forEach((clip) => {
+    if (!clip.hasAudio) return;
+    const inputIndex = project.videoOrAudioClips.indexOf(clip);
+    const requestedDuration = Math.max(
+      0,
+      (clip.end || 0) - (clip.position || 0)
+    );
+    const maxAvailable =
+      typeof clip.mediaDuration === "number" && typeof clip.cutFrom === "number"
+        ? Math.max(0, clip.mediaDuration - clip.cutFrom)
+        : requestedDuration;
+    const clipDuration = Math.max(0, Math.min(requestedDuration, maxAvailable));
+
+    const adelayMs = Math.round(Math.max(0, clip.position || 0) * 1000);
+    const out = `[va${inputIndex}]`;
+    audioFilter += `[${inputIndex}:a]atrim=start=${clip.cutFrom}:duration=${clipDuration},asetpts=PTS-STARTPTS,adelay=${adelayMs}|${adelayMs}${out};`;
+    labels.push(out);
+  });
+
+  if (labels.length === 0) {
+    return { filter: "", finalAudioLabel: null, hasAudio: false };
+  }
+
+  audioFilter += `${labels.join("")}amix=inputs=${
+    labels.length
+  }:duration=longest[outa];`;
+  return { filter: audioFilter, finalAudioLabel: "[outa]", hasAudio: true };
+}
+
+module.exports = { buildAudioForVideoClips };

package/src/ffmpeg/bgm_builder.js

@@ -0,0 +1,67 @@
+function buildBackgroundMusicMix(
+  project,
+  backgroundClips,
+  existingAudioLabel,
+  visualEnd
+) {
+  if (backgroundClips.length === 0) {
+    return {
+      filter: "",
+      finalAudioLabel: existingAudioLabel,
+      hasAudio: !!existingAudioLabel,
+    };
+  }
+
+  const projectDuration =
+    project.videoOrAudioClips.filter(
+      (c) => c.type === "video" || c.type === "image"
+    ).length > 0
+      ? Math.max(
+          ...project.videoOrAudioClips
+            .filter((c) => c.type === "video" || c.type === "image")
+            .map((c) => c.end)
+        )
+      : Math.max(
+          0,
+          ...backgroundClips.map((c) => (typeof c.end === "number" ? c.end : 0))
+        );
+
+  let filter = "";
+  const bgLabels = [];
+  backgroundClips.forEach((clip, i) => {
+    const inputIndex = project.videoOrAudioClips.indexOf(clip);
+    const effectivePosition =
+      typeof clip.position === "number" ? clip.position : 0;
+    const effectiveEnd =
+      typeof clip.end === "number" ? clip.end : projectDuration;
+    const effectiveCutFrom =
+      typeof clip.cutFrom === "number" ? clip.cutFrom : 0;
+    const effectiveVolume = typeof clip.volume === "number" ? clip.volume : 0.2;
+
+    const adelay = effectivePosition * 1000;
+    const trimEnd = effectiveCutFrom + (effectiveEnd - effectivePosition);
+    const outLabel = `[bg${i}]`;
+    filter += `[${inputIndex}:a]volume=${effectiveVolume},atrim=start=${effectiveCutFrom}:end=${trimEnd},adelay=${adelay}|${adelay},asetpts=PTS-STARTPTS${outLabel};`;
+    bgLabels.push(outLabel);
+  });
+
+  if (bgLabels.length > 0) {
+    if (existingAudioLabel) {
+      filter += `${existingAudioLabel}${bgLabels.join("")}amix=inputs=${
+        bgLabels.length + 1
+      }:duration=longest[finalaudio];`;
+      return { filter, finalAudioLabel: "[finalaudio]", hasAudio: true };
+    }
+    filter += `${bgLabels.join("")}amix=inputs=${
+      bgLabels.length
+    }:duration=longest[finalaudio];`;
+    return { filter, finalAudioLabel: "[finalaudio]", hasAudio: true };
+  }
+  return {
+    filter: "",
+    finalAudioLabel: existingAudioLabel,
+    hasAudio: !!existingAudioLabel,
+  };
+}
+
+module.exports = { buildBackgroundMusicMix };

package/src/ffmpeg/command_builder.js

@@ -0,0 +1,40 @@
+function buildMainCommand({
+  inputs,
+  filterComplex,
+  mapVideo,
+  mapAudio,
+  hasVideo,
+  hasAudio,
+  videoCodec,
+  videoPreset,
+  videoCrf,
+  audioCodec,
+  audioBitrate,
+  shortest,
+  faststart,
+  outputPath,
+}) {
+  let cmd = `ffmpeg -y ${inputs} -filter_complex "${filterComplex}" `;
+  if (hasVideo && mapVideo) cmd += `-map "${mapVideo}" `;
+  if (hasAudio && mapAudio) cmd += `-map "${mapAudio}" `;
+  if (hasVideo)
+    cmd += `-c:v ${videoCodec} -preset ${videoPreset} -crf ${videoCrf} `;
+  if (hasAudio) cmd += `-c:a ${audioCodec} -b:a ${audioBitrate} `;
+  if (hasVideo && hasAudio && shortest) cmd += `-shortest `;
+  if (faststart) cmd += `-movflags +faststart `;
+  cmd += `"${outputPath}"`;
+  return cmd;
+}
+
+function buildTextBatchCommand({
+  inputPath,
+  filterString,
+  intermediateVideoCodec,
+  intermediatePreset,
+  intermediateCrf,
+  outputPath,
+}) {
+  return `ffmpeg -y -i "${inputPath}" -filter_complex "[0:v]null[invid];${filterString}" -map "[outVideoAndText]" -map 0:a? -c:v ${intermediateVideoCodec} -preset ${intermediatePreset} -crf ${intermediateCrf} -c:a copy -movflags +faststart "${outputPath}"`;
+}
+
+module.exports = { buildMainCommand, buildTextBatchCommand };

package/src/ffmpeg/strings.js

@@ -0,0 +1,21 @@
+function escapeSingleQuotes(text) {
+  return String(text).replace(/'/g, "\\'");
+}
+
+function escapeDrawtextText(text) {
+  if (typeof text !== "string") return "";
+  return text.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/:/g, "\\:");
+}
+
+function getClipAudioString(clip, inputIndex) {
+  const adelay = Math.round(Math.max(0, (clip.position || 0) * 1000));
+  const audioConcatInput = `[a${inputIndex}]`;
+  const audioStringPart = `[${inputIndex}:a]volume=${clip.volume},atrim=start=${
+    clip.cutFrom
+  }:end=${
+    clip.cutFrom + (clip.end - clip.position)
+  },adelay=${adelay}|${adelay},asetpts=PTS-STARTPTS${audioConcatInput};`;
+  return { audioStringPart, audioConcatInput };
+}
+
+module.exports = { escapeSingleQuotes, escapeDrawtextText, getClipAudioString };

package/src/ffmpeg/text_passes.js

@@ -0,0 +1,67 @@
+const path = require("path");
+const { exec } = require("child_process");
+const { buildFiltersForWindows } = require("./text_renderer");
+const { buildTextBatchCommand } = require("./command_builder");
+
+function runCmd(cmd) {
+  return new Promise((resolve, reject) => {
+    exec(cmd, (err, so, se) => {
+      if (err) {
+        console.error("FFmpeg text batch stderr:", se);
+        reject(err);
+        return;
+      }
+      resolve();
+    });
+  });
+}
+
+async function runTextPasses({
+  baseOutputPath,
+  textWindows,
+  canvasWidth,
+  canvasHeight,
+  intermediateVideoCodec,
+  intermediatePreset,
+  intermediateCrf,
+  batchSize = 75,
+}) {
+  const tempOutputs = [];
+  let currentInput = baseOutputPath;
+  let passes = 0;
+
+  for (let i = 0; i < textWindows.length; i += batchSize) {
+    const batch = textWindows.slice(i, i + batchSize);
+    const { filterString } = buildFiltersForWindows(
+      batch,
+      canvasWidth,
+      canvasHeight,
+      "[invid]"
+    );
+
+    const batchOutput = path.join(
+      path.dirname(baseOutputPath),
+      `textpass_${i}_${path.basename(baseOutputPath)}`
+    );
+    tempOutputs.push(batchOutput);
+
+    const cmd = buildTextBatchCommand({
+      inputPath: currentInput,
+      filterString,
+      intermediateVideoCodec,
+      intermediatePreset,
+      intermediateCrf,
+      outputPath: batchOutput,
+    });
+    await runCmd(cmd);
+    currentInput = batchOutput;
+    passes += 1;
+  }
+
+  if (currentInput !== baseOutputPath) {
+    return { finalPath: currentInput, tempOutputs, passes };
+  }
+  return { finalPath: baseOutputPath, tempOutputs, passes };
+}
+
+module.exports = { runTextPasses };