novac 2.2.0 → 2.2.2

package/kits/kitffmpeg/kitdef.js

@@ -0,0 +1,1174 @@
+// kitdef.js — kitFFmpeg
+// Comprehensive FFmpeg wrapper: transcoding, trimming, merging, streaming,
+// filters, thumbnails, metadata, probing, and more.
+//
+// Requires: ffmpeg and ffprobe installed and available in PATH.
+// Install: https://ffmpeg.org/download.html
+//
+// const { kitFFmpeg } = require('./kitdef').kitdef;
+
+const { execSync, spawn }  = require("child_process");
+const fs   = require("fs");
+const path = require("path");
+const os   = require("os");
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function _hasFFmpeg() {
+  try { execSync("ffmpeg -version", { stdio: "pipe" }); return true; }
+  catch { return false; }
+}
+
+function _hasFFprobe() {
+  try { execSync("ffprobe -version", { stdio: "pipe" }); return true; }
+  catch { return false; }
+}
+
+function _require() {
+  if (!_hasFFmpeg()) throw new Error("ffmpeg not found in PATH. Install from https://ffmpeg.org/download.html");
+}
+
+function _requireProbe() {
+  if (!_hasFFprobe()) throw new Error("ffprobe not found in PATH.");
+}
+
+function _tmpFile(ext) {
+  return path.join(os.tmpdir(), `kitffmpeg_${Date.now()}_${Math.random().toString(36).slice(2)}${ext}`);
+}
+
+function _ext(filePath) {
+  return path.extname(filePath).toLowerCase();
+}
+
+function _run(args, options = {}) {
+  _require();
+  const cmd = ["ffmpeg", "-y", ...args].join(" ");
+  return execSync(cmd, { stdio: options.silent ? "pipe" : "inherit", ...options });
+}
+
+function _runSpawn(args, { onProgress, onLog } = {}) {
+  _require();
+  return new Promise((resolve, reject) => {
+    const proc = spawn("ffmpeg", ["-y", ...args]);
+    let stderr = "";
+    let duration = null;
+
+    proc.stderr.on("data", chunk => {
+      const text = chunk.toString();
+      stderr += text;
+      if (onLog) onLog(text);
+
+      // Parse duration for progress calculation
+      if (!duration) {
+        const dm = text.match(/Duration:\s*(\d+):(\d+):(\d+(?:\.\d+)?)/);
+        if (dm) duration = parseInt(dm[1]) * 3600 + parseInt(dm[2]) * 60 + parseFloat(dm[3]);
+      }
+
+      // Parse progress
+      if (onProgress && duration) {
+        const tm = text.match(/time=(\d+):(\d+):(\d+(?:\.\d+)?)/);
+        if (tm) {
+          const elapsed = parseInt(tm[1]) * 3600 + parseInt(tm[2]) * 60 + parseFloat(tm[3]);
+          onProgress({ percent: parseFloat(((elapsed / duration) * 100).toFixed(1)), elapsed, duration });
+        }
+      }
+    });
+
+    proc.on("close", code => {
+      if (code === 0) resolve({ code, stderr });
+      else reject(new Error(`ffmpeg exited with code ${code}\n${stderr}`));
+    });
+  });
+}
+
+function _probeRaw(filePath) {
+  _requireProbe();
+  const result = execSync(
+    `ffprobe -v quiet -print_format json -show_format -show_streams "${filePath}"`,
+    { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }
+  );
+  return JSON.parse(result);
+}
+
+function _timeStr(seconds) {
+  const h = Math.floor(seconds / 3600);
+  const m = Math.floor((seconds % 3600) / 60);
+  const s = (seconds % 60).toFixed(3);
+  return `${String(h).padStart(2,"0")}:${String(m).padStart(2,"0")}:${String(s).padStart(6,"0")}`;
+}
+
+// ── Export ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  kitdef: {
+
+    name: "kitFFmpeg",
+    version: "1.0.0",
+    description: "Comprehensive FFmpeg wrapper: transcoding, trimming, merging, filters, thumbnails, metadata, probing, streaming, and more.",
+
+    // ──────────────────────────────────────────────────────────────────────
+    // SYSTEM
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Check if ffmpeg and ffprobe are available.
+     * @returns {{ ffmpeg: boolean, ffprobe: boolean, version?: string }}
+     */
+    isAvailable() {
+      const ffmpeg  = _hasFFmpeg();
+      const ffprobe = _hasFFprobe();
+      let version = null;
+      if (ffmpeg) {
+        try {
+          const out = execSync("ffmpeg -version", { encoding: "utf8", stdio: ["ignore","pipe","pipe"] });
+          version = out.split("\n")[0].replace("ffmpeg version ", "").split(" ")[0];
+        } catch {}
+      }
+      return { ffmpeg, ffprobe, version };
+    },
+
+    /**
+     * List all available codecs.
+     * @returns {string[]}
+     */
+    listCodecs() {
+      _require();
+      const out = execSync("ffmpeg -codecs", { encoding: "utf8", stdio: ["ignore","pipe","pipe"] });
+      return out.split("\n").filter(l => /^\s[D.]/.test(l)).map(l => l.trim());
+    },
+
+    /**
+     * List all available formats.
+     * @returns {string[]}
+     */
+    listFormats() {
+      _require();
+      const out = execSync("ffmpeg -formats", { encoding: "utf8", stdio: ["ignore","pipe","pipe"] });
+      return out.split("\n").filter(l => /^\s[DE]/.test(l)).map(l => l.trim());
+    },
+
+    /**
+     * List all available filters.
+     * @returns {string[]}
+     */
+    listFilters() {
+      _require();
+      const out = execSync("ffmpeg -filters", { encoding: "utf8", stdio: ["ignore","pipe","pipe"] });
+      return out.split("\n").filter(l => /^\s[A-Z]/.test(l)).map(l => l.trim());
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // PROBING & METADATA
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Probe a media file and return full metadata.
+     * @param {string} filePath
+     * @returns {object} Full ffprobe JSON output.
+     *
+     * @example
+     *   const info = kitFFmpeg.probe("video.mp4");
+     *   console.log(info.format.duration);
+     */
+    probe(filePath) {
+      return _probeRaw(filePath);
+    },
+
+    /**
+     * Get a simplified summary of a media file.
+     * @param {string} filePath
+     * @returns {object}
+     */
+    info(filePath) {
+      const raw = _probeRaw(filePath);
+      const fmt = raw.format;
+      const videoStream = raw.streams.find(s => s.codec_type === "video");
+      const audioStream = raw.streams.find(s => s.codec_type === "audio");
+
+      return {
+        path:       filePath,
+        format:     fmt.format_name,
+        duration:   parseFloat(fmt.duration || 0),
+        size:       parseInt(fmt.size || 0),
+        bitrate:    parseInt(fmt.bit_rate || 0),
+        tags:       fmt.tags || {},
+        video: videoStream ? {
+          codec:     videoStream.codec_name,
+          width:     videoStream.width,
+          height:    videoStream.height,
+          fps:       eval(videoStream.r_frame_rate) || null,
+          bitrate:   parseInt(videoStream.bit_rate || 0),
+          pixelFmt:  videoStream.pix_fmt,
+          profile:   videoStream.profile,
+        } : null,
+        audio: audioStream ? {
+          codec:      audioStream.codec_name,
+          channels:   audioStream.channels,
+          sampleRate: parseInt(audioStream.sample_rate || 0),
+          bitrate:    parseInt(audioStream.bit_rate || 0),
+          language:   audioStream.tags?.language || null,
+        } : null,
+        streams: raw.streams.length,
+      };
+    },
+
+    /**
+     * Get the duration of a media file in seconds.
+     * @param {string} filePath
+     * @returns {number}
+     */
+    duration(filePath) {
+      return parseFloat(_probeRaw(filePath).format.duration || 0);
+    },
+
+    /**
+     * Get the resolution of a video file.
+     * @param {string} filePath
+     * @returns {{ width: number, height: number }}
+     */
+    resolution(filePath) {
+      const raw = _probeRaw(filePath);
+      const v   = raw.streams.find(s => s.codec_type === "video");
+      if (!v) throw new Error("No video stream found.");
+      return { width: v.width, height: v.height };
+    },
+
+    /**
+     * Get all metadata tags from a file.
+     * @param {string} filePath
+     * @returns {object}
+     */
+    getTags(filePath) {
+      return _probeRaw(filePath).format.tags || {};
+    },
+
+    /**
+     * Check if a file has a video stream.
+     * @param {string} filePath
+     * @returns {boolean}
+     */
+    hasVideo(filePath) {
+      return _probeRaw(filePath).streams.some(s => s.codec_type === "video");
+    },
+
+    /**
+     * Check if a file has an audio stream.
+     * @param {string} filePath
+     * @returns {boolean}
+     */
+    hasAudio(filePath) {
+      return _probeRaw(filePath).streams.some(s => s.codec_type === "audio");
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // TRANSCODING
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Convert a media file to a different format/codec.
+     * @param {string} input
+     * @param {string} output
+     * @param {object} [options]
+     * @param {string}  [options.videoCodec]   - e.g. "libx264", "libvpx", "copy"
+     * @param {string}  [options.audioCodec]   - e.g. "aac", "libmp3lame", "copy"
+     * @param {string}  [options.videoBitrate] - e.g. "2M"
+     * @param {string}  [options.audioBitrate] - e.g. "192k"
+     * @param {number}  [options.crf]          - Constant rate factor (0-51, lower = better)
+     * @param {string}  [options.preset]       - e.g. "fast", "slow", "veryslow"
+     * @param {string}  [options.pixelFormat]  - e.g. "yuv420p"
+     * @param {function}[options.onProgress]   - Progress callback
+     * @returns {Promise<{ input, output, duration }>}
+     *
+     * @example
+     *   await kitFFmpeg.convert("input.mov", "output.mp4", { videoCodec: "libx264", crf: 23 });
+     */
+    async convert(input, output, options = {}) {
+      const args = ["-i", `"${input}"`];
+      if (options.videoCodec)   args.push("-c:v", options.videoCodec);
+      if (options.audioCodec)   args.push("-c:a", options.audioCodec);
+      if (options.videoBitrate) args.push("-b:v", options.videoBitrate);
+      if (options.audioBitrate) args.push("-b:a", options.audioBitrate);
+      if (options.crf !== undefined) args.push("-crf", options.crf);
+      if (options.preset)       args.push("-preset", options.preset);
+      if (options.pixelFormat)  args.push("-pix_fmt", options.pixelFormat);
+      args.push(`"${output}"`);
+
+      await _runSpawn(args, { onProgress: options.onProgress });
+      return { input, output };
+    },
+
+    /**
+     * Re-encode a video with H.264 (most compatible format).
+     * @param {string} input
+     * @param {string} output
+     * @param {{ crf?: number, preset?: string, onProgress?: function }} [options]
+     * @returns {Promise<object>}
+     */
+    toH264(input, output, options = {}) {
+      return this.convert(input, output, {
+        videoCodec: "libx264",
+        audioCodec: "aac",
+        pixelFormat: "yuv420p",
+        crf: options.crf || 23,
+        preset: options.preset || "medium",
+        onProgress: options.onProgress,
+      });
+    },
+
+    /**
+     * Re-encode a video with H.265/HEVC (better compression than H.264).
+     * @param {string} input
+     * @param {string} output
+     * @param {{ crf?: number, preset?: string, onProgress?: function }} [options]
+     */
+    toH265(input, output, options = {}) {
+      return this.convert(input, output, {
+        videoCodec: "libx265",
+        audioCodec: "aac",
+        crf: options.crf || 28,
+        preset: options.preset || "medium",
+        onProgress: options.onProgress,
+      });
+    },
+
+    /**
+     * Convert to WebM (VP9 + Opus, ideal for web).
+     * @param {string} input
+     * @param {string} output
+     * @param {{ crf?: number, onProgress?: function }} [options]
+     */
+    toWebM(input, output, options = {}) {
+      return this.convert(input, output, {
+        videoCodec: "libvpx-vp9",
+        audioCodec: "libopus",
+        crf: options.crf || 30,
+        onProgress: options.onProgress,
+      });
+    },
+
+    /**
+     * Convert video to GIF.
+     * @param {string} input
+     * @param {string} output
+     * @param {{ fps?: number, width?: number, start?: number, duration?: number }} [options]
+     * @returns {Promise<object>}
+     */
+    async toGIF(input, output, options = {}) {
+      const fps   = options.fps || 15;
+      const width = options.width || 480;
+      const palette = _tmpFile(".png");
+
+      const baseArgs = [];
+      if (options.start)    baseArgs.push("-ss", options.start);
+      if (options.duration) baseArgs.push("-t",  options.duration);
+      baseArgs.push("-i", `"${input}"`);
+
+      // Generate palette for better quality
+      await _runSpawn([...baseArgs, "-vf", `fps=${fps},scale=${width}:-1:flags=lanczos,palettegen`, `"${palette}"`]);
+      await _runSpawn([...baseArgs, "-i", `"${palette}"`, "-filter_complex", `fps=${fps},scale=${width}:-1:flags=lanczos[x];[x][1:v]paletteuse`, `"${output}"`]);
+
+      try { fs.unlinkSync(palette); } catch {}
+      return { input, output, fps, width };
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // TRIMMING & CUTTING
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Trim a media file to a start and end time.
+     * @param {string} input
+     * @param {string} output
+     * @param {object} options
+     * @param {number|string} options.start    - Start time in seconds or "HH:MM:SS".
+     * @param {number|string} [options.end]    - End time in seconds or "HH:MM:SS".
+     * @param {number|string} [options.duration] - Duration instead of end time.
+     * @param {boolean} [options.accurate=false] - Slow but frame-accurate trim.
+     * @returns {Promise<object>}
+     *
+     * @example
+     *   await kitFFmpeg.trim("video.mp4", "clip.mp4", { start: 10, end: 30 });
+     *   await kitFFmpeg.trim("video.mp4", "clip.mp4", { start: "00:01:30", duration: 60 });
+     */
+    async trim(input, output, options = {}) {
+      const args = [];
+
+      if (!options.accurate) {
+        // Fast seek (before input)
+        if (options.start !== undefined) args.push("-ss", options.start);
+        args.push("-i", `"${input}"`);
+        if (options.end !== undefined) args.push("-to", options.end);
+        if (options.duration !== undefined) args.push("-t", options.duration);
+        args.push("-c", "copy");
+      } else {
+        // Accurate seek (slower, re-encodes)
+        args.push("-i", `"${input}"`);
+        if (options.start !== undefined) args.push("-ss", options.start);
+        if (options.end !== undefined) args.push("-to", options.end);
+        if (options.duration !== undefined) args.push("-t", options.duration);
+      }
+
+      args.push(`"${output}"`);
+      await _runSpawn(args, { onProgress: options.onProgress });
+      return { input, output, start: options.start, end: options.end };
+    },
+
+    /**
+     * Split a file into segments of a fixed duration.
+     * @param {string} input
+     * @param {string} outputPattern - e.g. "segment_%03d.mp4"
+     * @param {number} segmentSeconds
+     * @returns {Promise<{ segments: string[] }>}
+     *
+     * @example
+     *   await kitFFmpeg.split("long.mp4", "part_%03d.mp4", 600); // 10-min segments
+     */
+    async split(input, outputPattern, segmentSeconds) {
+      const args = [
+        "-i", `"${input}"`,
+        "-c", "copy",
+        "-f", "segment",
+        "-segment_time", segmentSeconds,
+        "-reset_timestamps", "1",
+        `"${outputPattern}"`,
+      ];
+      await _runSpawn(args);
+      return { input, outputPattern, segmentSeconds };
+    },
+
+    /**
+     * Cut out a section from a file (remove a range, keep the rest).
+     * @param {string} input
+     * @param {string} output
+     * @param {number} cutStart - Start of section to remove (seconds).
+     * @param {number} cutEnd   - End of section to remove (seconds).
+     * @returns {Promise<object>}
+     */
+    async cutOut(input, output, cutStart, cutEnd) {
+      const part1 = _tmpFile(_ext(input));
+      const part2 = _tmpFile(_ext(input));
+      await this.trim(input, part1, { end: cutStart });
+      await this.trim(input, part2, { start: cutEnd });
+      await this.concat([part1, part2], output);
+      try { fs.unlinkSync(part1); fs.unlinkSync(part2); } catch {}
+      return { input, output, cutStart, cutEnd };
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // MERGING & CONCATENATION
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Concatenate multiple media files into one.
+     * All files must have the same codec and resolution.
+     * @param {string[]} inputs
+     * @param {string}   output
+     * @returns {Promise<object>}
+     *
+     * @example
+     *   await kitFFmpeg.concat(["part1.mp4", "part2.mp4", "part3.mp4"], "full.mp4");
+     */
+    async concat(inputs, output) {
+      const listFile = _tmpFile(".txt");
+      const content  = inputs.map(f => `file '${path.resolve(f)}'`).join("\n");
+      fs.writeFileSync(listFile, content, "utf8");
+
+      await _runSpawn(["-f", "concat", "-safe", "0", "-i", `"${listFile}"`, "-c", "copy", `"${output}"`]);
+      try { fs.unlinkSync(listFile); } catch {}
+      return { inputs, output };
+    },
+
+    /**
+     * Merge video and audio from separate files.
+     * @param {string} videoInput
+     * @param {string} audioInput
+     * @param {string} output
+     * @param {{ shortest?: boolean }} [options]
+     * @returns {Promise<object>}
+     *
+     * @example
+     *   await kitFFmpeg.mergeAV("video.mp4", "audio.m4a", "combined.mp4");
+     */
+    async mergeAV(videoInput, audioInput, output, options = {}) {
+      const args = [
+        "-i", `"${videoInput}"`,
+        "-i", `"${audioInput}"`,
+        "-c:v", "copy",
+        "-c:a", "aac",
+      ];
+      if (options.shortest) args.push("-shortest");
+      args.push(`"${output}"`);
+      await _runSpawn(args);
+      return { videoInput, audioInput, output };
+    },
+
+    /**
+     * Stack two videos side by side (horizontally).
+     * @param {string} left
+     * @param {string} right
+     * @param {string} output
+     * @returns {Promise<object>}
+     */
+    async stackHorizontal(left, right, output) {
+      await _runSpawn([
+        "-i", `"${left}"`, "-i", `"${right}"`,
+        "-filter_complex", "hstack=inputs=2",
+        `"${output}"`,
+      ]);
+      return { left, right, output };
+    },
+
+    /**
+     * Stack two videos on top of each other (vertically).
+     * @param {string} top
+     * @param {string} bottom
+     * @param {string} output
+     * @returns {Promise<object>}
+     */
+    async stackVertical(top, bottom, output) {
+      await _runSpawn([
+        "-i", `"${top}"`, "-i", `"${bottom}"`,
+        "-filter_complex", "vstack=inputs=2",
+        `"${output}"`,
+      ]);
+      return { top, bottom, output };
+    },
+
+    /**
+     * Create a 2x2 grid from four video files.
+     * @param {string[]} inputs - Exactly 4 files.
+     * @param {string}   output
+     * @returns {Promise<object>}
+     */
+    async grid2x2(inputs, output) {
+      if (inputs.length !== 4) throw new Error("grid2x2 requires exactly 4 input files.");
+      const [a, b, c, d] = inputs;
+      await _runSpawn([
+        "-i", `"${a}"`, "-i", `"${b}"`, "-i", `"${c}"`, "-i", `"${d}"`,
+        "-filter_complex",
+        "[0:v][1:v]hstack[top];[2:v][3:v]hstack[bottom];[top][bottom]vstack",
+        `"${output}"`,
+      ]);
+      return { inputs, output };
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // AUDIO
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Extract audio from a video file.
+     * @param {string} input
+     * @param {string} output     - e.g. "audio.mp3", "audio.aac", "audio.wav"
+     * @param {{ bitrate?: string, codec?: string }} [options]
+     * @returns {Promise<object>}
+     *
+     * @example
+     *   await kitFFmpeg.extractAudio("video.mp4", "audio.mp3", { bitrate: "320k" });
+     */
+    async extractAudio(input, output, options = {}) {
+      const args = ["-i", `"${input}"`, "-vn"];
+      if (options.codec)   args.push("-c:a", options.codec);
+      if (options.bitrate) args.push("-b:a", options.bitrate);
+      args.push(`"${output}"`);
+      await _runSpawn(args);
+      return { input, output };
+    },
+
+    /**
+     * Strip all audio from a video file.
+     * @param {string} input
+     * @param {string} output
+     * @returns {Promise<object>}
+     */
+    async stripAudio(input, output) {
+      await _runSpawn(["-i", `"${input}"`, "-an", "-c:v", "copy", `"${output}"`]);
+      return { input, output };
+    },
+
+    /**
+     * Replace the audio track of a video with a different audio file.
+     * @param {string} videoInput
+     * @param {string} audioInput
+     * @param {string} output
+     * @param {{ shortest?: boolean }} [options]
+     */
+    async replaceAudio(videoInput, audioInput, output, options = {}) {
+      return this.mergeAV(videoInput, audioInput, output, options);
+    },
+
+    /**
+     * Adjust the volume of a media file.
+     * @param {string} input
+     * @param {string} output
+     * @param {number|string} volume - e.g. 0.5 (half), 2.0 (double), "6dB"
+     * @returns {Promise<object>}
+     */
+    async adjustVolume(input, output, volume) {
+      await _runSpawn(["-i", `"${input}"`, "-filter:a", `volume=${volume}`, `"${output}"`]);
+      return { input, output, volume };
+    },
+
+    /**
+     * Normalize audio loudness to a target LUFS level.
+     * @param {string} input
+     * @param {string} output
+     * @param {number} [targetLUFS=-16]
+     * @returns {Promise<object>}
+     */
+    async normalizeAudio(input, output, targetLUFS = -16) {
+      await _runSpawn([
+        "-i", `"${input}"`,
+        "-filter:a", `loudnorm=I=${targetLUFS}:TP=-1.5:LRA=11`,
+        `"${output}"`,
+      ]);
+      return { input, output, targetLUFS };
+    },
+
+    /**
+     * Mix multiple audio files into one.
+     * @param {string[]} inputs
+     * @param {string}   output
+     * @returns {Promise<object>}
+     */
+    async mixAudio(inputs, output) {
+      const args = inputs.flatMap(f => ["-i", `"${f}"`]);
+      args.push("-filter_complex", `amix=inputs=${inputs.length}:duration=longest`, `"${output}"`);
+      await _runSpawn(args);
+      return { inputs, output };
+    },
+
+    /**
+     * Convert audio to a different format.
+     * @param {string} input
+     * @param {string} output
+     * @param {{ codec?: string, bitrate?: string, sampleRate?: number, channels?: number }} [options]
+     */
+    async convertAudio(input, output, options = {}) {
+      const args = ["-i", `"${input}"`];
+      if (options.codec)      args.push("-c:a", options.codec);
+      if (options.bitrate)    args.push("-b:a", options.bitrate);
+      if (options.sampleRate) args.push("-ar", options.sampleRate);
+      if (options.channels)   args.push("-ac", options.channels);
+      args.push(`"${output}"`);
+      await _runSpawn(args);
+      return { input, output };
+    },
+
+    /**
+     * Generate a silent audio file of a given duration.
+     * @param {string} output
+     * @param {number} durationSeconds
+     * @param {{ sampleRate?: number, channels?: number }} [options]
+     */
+    async generateSilence(output, durationSeconds, options = {}) {
+      const sr = options.sampleRate || 44100;
+      const ch = options.channels   || 2;
+      await _runSpawn([
+        "-f", "lavfi", "-i", `anullsrc=r=${sr}:cl=${ch === 2 ? "stereo" : "mono"}`,
+        "-t", durationSeconds, `"${output}"`,
+      ]);
+      return { output, durationSeconds };
+    },
+
+    /**
+     * Generate a tone audio file.
+     * @param {string} output
+     * @param {{ frequency?: number, duration?: number, amplitude?: number }} [options]
+     */
+    async generateTone(output, options = {}) {
+      const freq = options.frequency || 440;
+      const dur  = options.duration  || 5;
+      const amp  = options.amplitude || 0.5;
+      await _runSpawn([
+        "-f", "lavfi", "-i", `sine=frequency=${freq}:amplitude=${amp}`,
+        "-t", dur, `"${output}"`,
+      ]);
+      return { output, frequency: freq, duration: dur };
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // VIDEO FILTERS & EFFECTS
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Scale (resize) a video.
+     * @param {string} input
+     * @param {string} output
+     * @param {number|string} width  - Width in pixels, or -1 to maintain aspect ratio.
+     * @param {number|string} height - Height in pixels, or -1 to maintain aspect ratio.
+     * @returns {Promise<object>}
+     *
+     * @example
+     *   await kitFFmpeg.scale("input.mp4", "output.mp4", 1280, 720);
+     *   await kitFFmpeg.scale("input.mp4", "output.mp4", 1280, -1); // maintain aspect
+     */
+    async scale(input, output, width, height) {
+      await _runSpawn(["-i", `"${input}"`, "-vf", `scale=${width}:${height}`, `"${output}"`]);
+      return { input, output, width, height };
+    },
+
+    /**
+     * Crop a video to a rectangle.
+     * @param {string} input
+     * @param {string} output
+     * @param {{ w: number, h: number, x?: number, y?: number }} rect
+     * @returns {Promise<object>}
+     */
+    async crop(input, output, { w, h, x = 0, y = 0 }) {
+      await _runSpawn(["-i", `"${input}"`, "-vf", `crop=${w}:${h}:${x}:${y}`, `"${output}"`]);
+      return { input, output, w, h, x, y };
+    },
+
+    /**
+     * Rotate a video.
+     * @param {string} input
+     * @param {string} output
+     * @param {90|180|270|-90} degrees
+     * @returns {Promise<object>}
+     */
+    async rotate(input, output, degrees) {
+      const transposeMap = { 90: "1", [-90]: "2", 270: "2", 180: "transpose=1,transpose=1" };
+      const filter = transposeMap[degrees];
+      if (!filter) throw new Error("Rotation must be 90, -90, 270, or 180.");
+      const vf = degrees === 180 ? filter : `transpose=${filter}`;
+      await _runSpawn(["-i", `"${input}"`, "-vf", vf, `"${output}"`]);
+      return { input, output, degrees };
+    },
+
+    /**
+     * Flip a video horizontally (mirror).
+     * @param {string} input
+     * @param {string} output
+     */
+    async flipHorizontal(input, output) {
+      await _runSpawn(["-i", `"${input}"`, "-vf", "hflip", `"${output}"`]);
+      return { input, output };
+    },
+
+    /**
+     * Flip a video vertically.
+     * @param {string} input
+     * @param {string} output
+     */
+    async flipVertical(input, output) {
+      await _runSpawn(["-i", `"${input}"`, "-vf", "vflip", `"${output}"`]);
+      return { input, output };
+    },
+
+    /**
+     * Change the playback speed of a video.
+     * @param {string} input
+     * @param {string} output
+     * @param {number} speed - e.g. 2.0 = 2x speed, 0.5 = half speed
+     * @returns {Promise<object>}
+     */
+    async setSpeed(input, output, speed) {
+      const vPts = 1 / speed;
+      const aTempo = Math.min(2.0, Math.max(0.5, speed));
+      await _runSpawn([
+        "-i", `"${input}"`,
+        "-filter_complex", `[0:v]setpts=${vPts}*PTS[v];[0:a]atempo=${aTempo}[a]`,
+        "-map", "[v]", "-map", "[a]",
+        `"${output}"`,
+      ]);
+      return { input, output, speed };
+    },
+
+    /**
+     * Reverse a video (plays backwards).
+     * @param {string} input
+     * @param {string} output
+     * @returns {Promise<object>}
+     */
+    async reverse(input, output) {
+      await _runSpawn(["-i", `"${input}"`, "-vf", "reverse", "-af", "areverse", `"${output}"`]);
+      return { input, output };
+    },
+
+    /**
+     * Apply a blur effect to a video.
+     * @param {string} input
+     * @param {string} output
+     * @param {number} [strength=5]
+     */
+    async blur(input, output, strength = 5) {
+      await _runSpawn(["-i", `"${input}"`, "-vf", `boxblur=${strength}:${strength}`, `"${output}"`]);
+      return { input, output, strength };
+    },
+
+    /**
+     * Sharpen a video.
+     * @param {string} input
+     * @param {string} output
+     * @param {number} [strength=1.5]
+     */
+    async sharpen(input, output, strength = 1.5) {
+      await _runSpawn(["-i", `"${input}"`, "-vf", `unsharp=5:5:${strength}:5:5:0`, `"${output}"`]);
+      return { input, output, strength };
+    },
+
+    /**
+     * Convert video to grayscale.
+     * @param {string} input
+     * @param {string} output
+     */
+    async grayscale(input, output) {
+      await _runSpawn(["-i", `"${input}"`, "-vf", "format=gray", `"${output}"`]);
+      return { input, output };
+    },
+
+    /**
+     * Adjust brightness, contrast, and saturation.
+     * @param {string} input
+     * @param {string} output
+     * @param {{ brightness?: number, contrast?: number, saturation?: number }} options
+     * Values: brightness [-1,1], contrast [0,2], saturation [0,3]
+     */
+    async adjustColor(input, output, { brightness = 0, contrast = 1, saturation = 1 } = {}) {
+      await _runSpawn([
+        "-i", `"${input}"`,
+        "-vf", `eq=brightness=${brightness}:contrast=${contrast}:saturation=${saturation}`,
+        `"${output}"`,
+      ]);
+      return { input, output, brightness, contrast, saturation };
+    },
+
+    /**
+     * Add a fade in/out effect to a video.
+     * @param {string} input
+     * @param {string} output
+     * @param {{ fadeIn?: number, fadeOut?: number }} [options] - Duration in seconds.
+     * @returns {Promise<object>}
+     */
+    async fade(input, output, { fadeIn = 1, fadeOut = 1 } = {}) {
+      const dur = this.duration(input);
+      const filters = [];
+      if (fadeIn)  filters.push(`fade=in:st=0:d=${fadeIn}`);
+      if (fadeOut) filters.push(`fade=out:st=${dur - fadeOut}:d=${fadeOut}`);
+      const audioFilters = [];
+      if (fadeIn)  audioFilters.push(`afade=in:st=0:d=${fadeIn}`);
+      if (fadeOut) audioFilters.push(`afade=out:st=${dur - fadeOut}:d=${fadeOut}`);
+
+      await _runSpawn([
+        "-i", `"${input}"`,
+        "-vf", filters.join(","),
+        "-af", audioFilters.join(","),
+        `"${output}"`,
+      ]);
+      return { input, output, fadeIn, fadeOut };
+    },
+
+    /**
+     * Add a watermark/overlay image to a video.
+     * @param {string} input
+     * @param {string} watermark  - Path to watermark image.
+     * @param {string} output
+     * @param {{ position?: 'topleft'|'topright'|'bottomleft'|'bottomright'|'center', opacity?: number }} [options]
+     */
+    async watermark(input, watermark, output, options = {}) {
+      const pos = options.position || "bottomright";
+      const opacity = options.opacity || 0.8;
+      const posMap = {
+        topleft:     "10:10",
+        topright:    "main_w-overlay_w-10:10",
+        bottomleft:  "10:main_h-overlay_h-10",
+        bottomright: "main_w-overlay_w-10:main_h-overlay_h-10",
+        center:      "(main_w-overlay_w)/2:(main_h-overlay_h)/2",
+      };
+      const overlay = posMap[pos] || posMap.bottomright;
+      await _runSpawn([
+        "-i", `"${input}"`,
+        "-i", `"${watermark}"`,
+        "-filter_complex", `[1:v]format=rgba,colorchannelmixer=aa=${opacity}[wm];[0:v][wm]overlay=${overlay}`,
+        "-c:a", "copy",
+        `"${output}"`,
+      ]);
+      return { input, watermark, output, position: pos };
+    },
+
+    /**
+     * Add a text overlay to a video.
+     * @param {string} input
+     * @param {string} output
+     * @param {object} options
+     * @param {string}  options.text
+     * @param {string}  [options.font="Arial"]
+     * @param {number}  [options.fontSize=36]
+     * @param {string}  [options.color="white"]
+     * @param {string}  [options.position="bottom"] - "top", "bottom", "center"
+     * @param {number}  [options.startTime]
+     * @param {number}  [options.endTime]
+     */
+    async addText(input, output, options = {}) {
+      const font      = options.font     || "Arial";
+      const size      = options.fontSize || 36;
+      const color     = options.color    || "white";
+      const pos       = options.position || "bottom";
+      const yMap      = { top: "50", center: "(h-text_h)/2", bottom: "h-text_h-50" };
+      const y         = yMap[pos] || yMap.bottom;
+      let drawtext    = `text='${options.text}':fontfile=${font}:fontsize=${size}:fontcolor=${color}:x=(w-text_w)/2:y=${y}:shadowcolor=black:shadowx=2:shadowy=2`;
+      if (options.startTime !== undefined) drawtext += `:enable='between(t,${options.startTime},${options.endTime || 9999})'`;
+
+      await _runSpawn(["-i", `"${input}"`, "-vf", `drawtext=${drawtext}`, "-c:a", "copy", `"${output}"`]);
+      return { input, output, text: options.text };
+    },
+
+    /**
+     * Apply a custom ffmpeg filter string.
+     * @param {string} input
+     * @param {string} output
+     * @param {string} videoFilter  - -vf filter string
+     * @param {string} [audioFilter] - -af filter string
+     */
+    async applyFilter(input, output, videoFilter, audioFilter) {
+      const args = ["-i", `"${input}"`, "-vf", videoFilter];
+      if (audioFilter) args.push("-af", audioFilter);
+      args.push(`"${output}"`);
+      await _runSpawn(args);
+      return { input, output };
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // THUMBNAILS & IMAGES
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Extract a single thumbnail frame from a video.
+     * @param {string} input
+     * @param {string} output   - Should be a .jpg or .png file.
+     * @param {number|string} [time=1] - Time in seconds or "HH:MM:SS".
+     * @param {{ width?: number }} [options]
+     * @returns {Promise<object>}
+     *
+     * @example
+     *   await kitFFmpeg.thumbnail("video.mp4", "thumb.jpg", 30);
+     */
+    async thumbnail(input, output, time = 1, options = {}) {
+      const args = ["-ss", time, "-i", `"${input}"`, "-frames:v", "1"];
+      if (options.width) args.push("-vf", `scale=${options.width}:-1`);
+      args.push(`"${output}"`);
+      await _runSpawn(args);
+      return { input, output, time };
+    },
+
+    /**
+     * Extract multiple thumbnail frames at regular intervals.
+     * @param {string} input
+     * @param {string} outputPattern - e.g. "thumb_%03d.jpg"
+     * @param {number} [intervalSeconds=10]
+     * @param {{ width?: number }} [options]
+     * @returns {Promise<object>}
+     */
+    async thumbnails(input, outputPattern, intervalSeconds = 10, options = {}) {
+      const args = ["-i", `"${input}"`];
+      const filters = [`fps=1/${intervalSeconds}`];
+      if (options.width) filters.push(`scale=${options.width}:-1`);
+      args.push("-vf", filters.join(","), `"${outputPattern}"`);
+      await _runSpawn(args);
+      return { input, outputPattern, intervalSeconds };
+    },
+
+    /**
+     * Extract all frames from a video as images.
+     * @param {string} input
+     * @param {string} outputPattern - e.g. "frame_%06d.png"
+     * @param {{ fps?: number }} [options]
+     * @returns {Promise<object>}
+     */
+    async extractFrames(input, outputPattern, options = {}) {
+      const args = ["-i", `"${input}"`];
+      if (options.fps) args.push("-vf", `fps=${options.fps}`);
+      args.push(`"${outputPattern}"`);
+      await _runSpawn(args);
+      return { input, outputPattern };
+    },
+
+    /**
+     * Create a video from a sequence of images.
+     * @param {string} inputPattern - e.g. "frame_%06d.png"
+     * @param {string} output
+     * @param {{ fps?: number, codec?: string }} [options]
+     * @returns {Promise<object>}
+     */
+    async fromImages(inputPattern, output, options = {}) {
+      const fps   = options.fps   || 24;
+      const codec = options.codec || "libx264";
+      await _runSpawn([
+        "-r", fps,
+        "-i", `"${inputPattern}"`,
+        "-c:v", codec,
+        "-pix_fmt", "yuv420p",
+        `"${output}"`,
+      ]);
+      return { inputPattern, output, fps };
+    },
+
+    /**
+     * Create a video slideshow from a list of images.
+     * @param {string[]} images
+     * @param {string}   output
+     * @param {{ duration?: number, fps?: number, transition?: boolean }} [options]
+     * @returns {Promise<object>}
+     */
+    async slideshow(images, output, options = {}) {
+      const duration = options.duration || 3;
+      const fps      = options.fps      || 25;
+      const listFile = _tmpFile(".txt");
+      const content  = images.map(f => `file '${path.resolve(f)}'\nduration ${duration}`).join("\n");
+      fs.writeFileSync(listFile, content, "utf8");
+
+      await _runSpawn([
+        "-f", "concat", "-safe", "0", "-i", `"${listFile}"`,
+        "-c:v", "libx264", "-pix_fmt", "yuv420p", "-r", fps,
+        `"${output}"`,
+      ]);
+      try { fs.unlinkSync(listFile); } catch {}
+      return { images, output, duration, fps };
+    },
+
+    /**
+     * Create a contact sheet (grid of thumbnails) from a video.
+     * @param {string} input
+     * @param {string} output
+     * @param {{ cols?: number, rows?: number, width?: number }} [options]
+     * @returns {Promise<object>}
+     */
+    async contactSheet(input, output, options = {}) {
+      const cols  = options.cols  || 4;
+      const rows  = options.rows  || 4;
+      const width = options.width || 320;
+      const total = cols * rows;
+      const dur   = this.duration(input);
+      const step  = dur / total;
+
+      await _runSpawn([
+        "-i", `"${input}"`,
+        "-vf", `select='not(mod(n,${Math.floor(step * 25)}))':n=${total},scale=${width}:-1,tile=${cols}x${rows}`,
+        "-frames:v", "1",
+        `"${output}"`,
+      ]);
+      return { input, output, cols, rows };
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // STREAMING & PIPING
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Stream a file to an RTMP endpoint (e.g. YouTube Live, Twitch).
+     * @param {string} input
+     * @param {string} rtmpUrl
+     * @param {{ videoBitrate?: string, audioBitrate?: string, onLog?: function }} [options]
+     * @returns {object} - { stop: function } to end the stream.
+     *
+     * @example
+     *   const stream = kitFFmpeg.streamRTMP("video.mp4", "rtmp://live.twitch.tv/live/YOUR_KEY");
+     *   // later: stream.stop();
+     */
+    streamRTMP(input, rtmpUrl, options = {}) {
+      _require();
+      const args = [
+        "-re", "-i", input,
+        "-c:v", "libx264",
+        "-b:v", options.videoBitrate || "2500k",
+        "-preset", "veryfast",
+        "-c:a", "aac",
+        "-b:a", options.audioBitrate || "128k",
+        "-f", "flv",
+        rtmpUrl,
+      ];
+      const proc = spawn("ffmpeg", ["-y", ...args]);
+      if (options.onLog) proc.stderr.on("data", d => options.onLog(d.toString()));
+      return {
+        stop: () => proc.kill("SIGTERM"),
+        pid: proc.pid,
+        rtmpUrl,
+      };
+    },
+
+    /**
+     * Capture from a webcam/device and save to file.
+     * @param {string} output
+     * @param {{ device?: string, duration?: number, format?: string }} [options]
+     * @returns {object} - { stop: function }
+     */
+    captureDevice(output, options = {}) {
+      _require();
+      const platform = process.platform;
+      let inputArgs;
+      if (platform === "darwin") {
+        inputArgs = ["-f", "avfoundation", "-i", options.device || "0:0"];
+      } else if (platform === "win32") {
+        inputArgs = ["-f", "dshow", "-i", `video=${options.device || "0"}`];
+      } else {
+        inputArgs = ["-f", "v4l2", "-i", options.device || "/dev/video0"];
+      }
+
+      const args = [...inputArgs];
+      if (options.duration) args.push("-t", options.duration);
+      args.push(output);
+
+      const proc = spawn("ffmpeg", ["-y", ...args]);
+      return { stop: () => proc.kill("SIGTERM"), pid: proc.pid, output };
+    },
+
+    /**
+     * Run a raw ffmpeg command with full control.
+     * @param {string[]} args - ffmpeg arguments (without "ffmpeg" itself).
+     * @param {{ onProgress?: function, onLog?: function }} [options]
+     * @returns {Promise<{ code, stderr }>}
+     *
+     * @example
+     *   await kitFFmpeg.raw(["-i", "input.mp4", "-vf", "negate", "output.mp4"]);
+     */
+    raw(args, options = {}) {
+      return _runSpawn(args, options);
+    },
+
+    // ──────────────────────────────────────────────────────────────────────
+    // COMPRESSION & OPTIMIZATION
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * Compress a video to reduce file size.
+     * @param {string} input
+     * @param {string} output
+     * @param {{ quality?: 'low'|'medium'|'high'|'veryhigh', onProgress?: function }} [options]
+     * @returns {Promise<{ input, output, savedBytes: number }>}
+     */
+    async compress(input, output, options = {}) {
+      const crfMap = { low: 32, medium: 28, high: 23, veryhigh: 18 };
+      const crf    = crfMap[options.quality || "medium"];
+      await this.toH264(input, output, { crf, preset: "slow", onProgress: options.onProgress });
+      const inSize  = fs.statSync(input).size;
+      const outSize = fs.statSync(output).size;
+      return { input, output, inputBytes: inSize, outputBytes: outSize, savedBytes: inSize - outSize };
+    },
+
+    /**
+     * Target a specific output file size by calculating the required bitrate.
+     * @param {string} input
+     * @param {string} output
+     * @param {number} targetMB   - Target file size in megabytes.
+     * @param {{ audioBitrate?: string }} [options]
+     * @returns {Promise<object>}
+     */
+    async targetSize(input, output, targetMB, options = {}) {
+      const dur          = this.duration(input);
+      const audioBitrateK = parseInt((options.audioBitrate || "128k")) || 128;
+      const targetBitsK   = (targetMB * 8 * 1024) / dur;
+      const videoBitrateK = Math.floor(targetBitsK - audioBitrateK);
+      if (videoBitrateK < 100) throw new Error("Target size too small for this duration.");
+      await this.convert(input, output, {
+        videoCodec: "libx264",
+        audioCodec: "aac",
+        videoBitrate: `${videoBitrateK}k`,
+        audioBitrate: `${audioBitrateK}k`,
+        onProgress: options.onProgress,
+      });
+      return { input, output, targetMB, videoBitrate: `${videoBitrateK}k` };
+    },
+
+  }
+};