ffmpeg-framecraft 1.0.0

package/src/engine.js

@@ -0,0 +1,365 @@
+const path = require('path');
+const fs = require('fs');
+const { run, probe } = require('./executor');
+const { cropTo916Filter, subtitleFilter, amixFilter, buildSlicesWithTransitionsFilter } = require('./filters');
+const shortsPreset = require('./presets/shorts');
+const { getTransition } = require('./presets/transitions');
+const { getPreset } = require('./presets/presets');
+const { timeStringToSeconds } = require('./utils');
+
+function sliceTimeToSeconds(value) {
+  if (typeof value === 'number' && !Number.isNaN(value)) return value;
+  if (typeof value === 'string') return timeStringToSeconds(value);
+  throw new Error(`Invalid slice time: ${value}`);
+}
+
+/**
+ * FramecraftEngine - FFmpeg-based video processing (crop, slice, transitions, subtitles, audio).
+ */
+class FramecraftEngine {
+  /**
+   * Crop video to 9:16 vertical format (720x1280).
+   * Uses ffprobe to get dimensions, then applies centered crop + scale.
+   *
+   * @param {string} inputPath - Input video path
+   * @param {string} outputPath - Output video path
+   * @param {object} [opts] - Options (future: quality presets, etc.)
+   * @param {function(object): void} [opts.onProgress] - Progress callback
+   * @returns {Promise<void>}
+   */
+  async cropTo916(inputPath, outputPath, opts = {}) {
+    const meta = await probe(inputPath);
+    const filter = cropTo916Filter(meta.width, meta.height);
+
+    await run({
+      input: inputPath,
+      output: outputPath,
+      videoFilters: filter,
+      outputOptions: shortsPreset.outputOptions(),
+      expectedDuration: meta.duration || undefined,
+      onProgress: opts.onProgress,
+    });
+  }
+
+  /**
+   * Slice video by timestamp range.
+   *
+   * @param {string} inputPath - Input video path
+   * @param {string} outputPath - Output video path
+   * @param {{ start: number|string, end: number|string }} range - Start and end time (seconds or "mm:ss.ms")
+   * @param {object} [opts] - Options
+   * @param {function(object): void} [opts.onProgress] - Progress callback
+   * @returns {Promise<void>}
+   */
+  async slice(inputPath, outputPath, range, opts = {}) {
+    let { start, end } = range;
+    start = typeof start === 'string' ? timeStringToSeconds(start) : start;
+    end = typeof end === 'string' ? timeStringToSeconds(end) : end;
+    const duration =
+      typeof start === 'number' && typeof end === 'number'
+        ? end - start
+        : undefined;
+
+    await run({
+      input: inputPath,
+      output: outputPath,
+      seek: start,
+      duration,
+      outputOptions: shortsPreset.outputOptions(),
+      expectedDuration: typeof duration === 'number' ? duration : undefined,
+      onProgress: opts.onProgress,
+    });
+  }
+
+  /**
+   * Add SRT subtitle overlay to video.
+   *
+   * @param {string} inputPath - Input video path
+   * @param {string} outputPath - Output video path
+   * @param {string} srtPath - Path to SRT file
+   * @param {object} [opts] - Style options for future AI caption styling
+   * @param {function(object): void} [opts.onProgress] - Progress callback
+   * @returns {Promise<void>}
+   */
+  async addSubtitles(inputPath, outputPath, srtPath, opts = {}) {
+    const { onProgress, ...style } = opts;
+    const filter = subtitleFilter(srtPath, style);
+
+    await run({
+      input: inputPath,
+      output: outputPath,
+      videoFilters: filter,
+      outputOptions: shortsPreset.outputOptions(),
+      onProgress,
+    });
+  }
+
+  /**
+   * Extract a single frame as thumbnail image.
+   *
+   * @param {string} inputPath - Input video path
+   * @param {string} outputPath - Output path (e.g. frame.jpg)
+   * @param {number|string} [time=0] - Timestamp in seconds or "mm:ss.ms"
+   * @returns {Promise<void>}
+   */
+  async extractThumbnail(inputPath, outputPath, time = 0) {
+    const ext = path.extname(outputPath).toLowerCase();
+    const format = ext === '.png' ? 'png' : 'image2';
+
+    await run({
+      input: inputPath,
+      output: outputPath,
+      seek: time,
+      frames: 1,
+      format,
+    });
+  }
+
+  /**
+   * Mix background music with video.
+   * Video keeps original stream; audio is mix of video audio + music (or music only if no video audio).
+   *
+   * @param {string} inputPath - Input video path
+   * @param {string} outputPath - Output video path
+   * @param {string} musicPath - Path to music/audio file
+   * @param {object} [opts] - Options
+   * @param {number} [opts.musicVolume=1] - Music volume 0-1 (future)
+   * @param {function(object): void} [opts.onProgress] - Progress callback
+   * @returns {Promise<void>}
+   */
+  async addBackgroundMusic(inputPath, outputPath, musicPath, opts = {}) {
+    const { onProgress } = opts;
+    const meta = await probe(inputPath);
+    const filterComplex = amixFilter(meta.hasAudio);
+
+    await run({
+      input: inputPath,
+      inputs: [musicPath],
+      output: outputPath,
+      complexFilter: filterComplex,
+      complexFilterMap: ['0:v', '[aout]'],
+      outputOptions: [
+        '-c:v', 'libx264', '-preset', 'medium', '-crf', '23',
+        '-c:a', 'aac', '-b:a', '128k',
+      ],
+      expectedDuration: meta.duration || undefined,
+      onProgress,
+    });
+  }
+
+  /**
+   * Extract multiple slices from one video and join them with transitions.
+   * Use this to build a single output from several time ranges (e.g. 0–10s, 20–30s, 40–50s) with fade/wipe/slide between clips.
+   *
+   * @param {string} inputPath - Input video path
+   * @param {string} outputPath - Output video path
+   * @param {object} options - Options
+   * @param {Array<{ start: number|string, end: number|string }>} options.slices - Time ranges (seconds or "H:MM:SS" / "MM:SS")
+   * @param {string|{ type: string, duration: number }} [options.transition='fade'] - Preset name (e.g. 'fade', 'wipeleft', 'dissolve') or { type, duration } in seconds
+   * @param {object} [opts] - Additional options
+   * @param {function(object): void} [opts.onProgress] - Progress callback
+   * @returns {Promise<void>}
+   */
+  async slicesWithTransitions(inputPath, outputPath, options, opts = {}) {
+    const { slices, preset } = options;
+    let transitionOption = options.transition;
+    if (transitionOption === undefined && preset) {
+      const p = typeof preset === 'string' ? getPreset(preset) : preset;
+      transitionOption = p.transition != null
+        ? { type: p.transition, duration: p.transitionDuration ?? 0.5 }
+        : 'fade';
+    }
+    transitionOption = transitionOption ?? 'fade';
+    if (!Array.isArray(slices) || slices.length === 0) {
+      throw new Error('slicesWithTransitions requires a non-empty slices array');
+    }
+
+    const meta = await probe(inputPath);
+    const fileDuration = meta.duration || 0;
+
+    const defaultTransition = getTransition(transitionOption);
+    const slicesNormalized = slices.map((slice, index) => {
+      let startSeconds = sliceTimeToSeconds(slice.start);
+      let endSeconds = sliceTimeToSeconds(slice.end);
+
+      if (fileDuration > 0) {
+        endSeconds = Math.min(endSeconds, fileDuration);
+        startSeconds = Math.min(startSeconds, endSeconds - 0.01);
+      }
+      const duration = endSeconds - startSeconds;
+      if (duration <= 0) {
+        throw new Error(
+          `slicesWithTransitions: slice ${index} has invalid or zero duration (start=${slice.start}, end=${slice.end}); file duration is ${fileDuration}s`
+        );
+      }
+
+      // For boundary between slice[i-1] -> slice[i], use slice.transition if provided,
+      // otherwise fall back to the common/default transition.
+      let transition = null;
+      if (index > 0) {
+        const transitionConfig = {
+          type: slice.transition?.type ? slice.transition.type : defaultTransition.type,
+          duration: slice.transition?.duration ? slice.transition.duration : defaultTransition.duration,
+        }
+        transition = getTransition(transitionConfig);
+        console.log('transition', transition);
+      }
+
+      return { startSeconds, endSeconds, transition };
+    });
+
+    const durations = slicesNormalized.map(
+      ({ startSeconds, endSeconds }) => endSeconds - startSeconds
+    );
+
+    let outputDuration = durations[0];
+    for (let i = 1; i < durations.length; i++) {
+      const prevDuration = durations[i - 1];
+      const currentDuration = durations[i];
+      const sliceTransition = slicesNormalized[i].transition;
+      const maxT = Math.min(prevDuration, currentDuration) - 0.01;
+      const t = Math.min(sliceTransition.duration, Math.max(0.01, maxT));
+      outputDuration = outputDuration + currentDuration - t;
+    }
+
+    const { filterComplex, mapVideo, mapAudio } = buildSlicesWithTransitionsFilter(
+      slicesNormalized,
+      meta.hasAudio
+    );
+
+    const complexFilterMap = [mapVideo];
+    if (mapAudio) complexFilterMap.push(mapAudio);
+
+    await run({
+      input: inputPath,
+      output: outputPath,
+      complexFilter: filterComplex,
+      complexFilterMap,
+      outputOptions: shortsPreset.outputOptions(),
+      expectedDuration: outputDuration,
+      onProgress: opts.onProgress,
+    });
+  }
+
+  /**
+   * Apply a named preset or run a pipeline of operations sequentially.
+   *
+   * @param {string} inputPath - Input video path
+   * @param {string} outputPath - Output video path
+   * @param {string|Array<{ op: string, [key: string]: any }>} [pipeline='shorts'] - Preset name or list of { op, ...args }
+   * @param {object} [opts] - Options
+   * @param {function(object): void} [opts.onProgress] - Progress callback
+   * @returns {Promise<void>}
+   */
+  async compose(inputPath, outputPath, pipeline = 'shorts', opts = {}) {
+    if (pipeline === 'shorts') {
+      await this.cropTo916(inputPath, outputPath, opts);
+      return;
+    }
+
+    if (!Array.isArray(pipeline) || pipeline.length === 0) {
+      throw new Error(`Unknown preset or empty pipeline: ${pipeline}`);
+    }
+
+    let current = inputPath;
+    const tempDir = path.dirname(outputPath);
+    const intermediates = [];
+
+    for (let i = 0; i < pipeline.length; i++) {
+      const step = pipeline[i];
+      const isLast = i === pipeline.length - 1;
+      const stepOutputPath = typeof step === 'object' && step.outputPath != null
+        ? step.outputPath
+        : outputPath;
+      const nextPath = isLast ? stepOutputPath : path.join(tempDir, `_compose_step_${i}.mp4`);
+
+      if (!isLast) {
+        intermediates.push(nextPath);
+      }
+
+      const op = typeof step === 'string' ? step : step.op;
+      if (!op) throw new Error(`Pipeline step ${i} missing 'op'`);
+
+      switch (op) {
+        case 'crop916':
+          await this.cropTo916(current, nextPath, opts);
+          break;
+        case 'slice':
+          if (step.start == null || step.end == null) {
+            throw new Error('slice step requires start and end');
+          }
+          await this.slice(current, nextPath, { start: step.start, end: step.end }, opts);
+          break;
+        case 'subtitles':
+          if (!step.srtPath) throw new Error('subtitles step requires srtPath');
+          await this.addSubtitles(current, nextPath, step.srtPath, opts);
+          break;
+        case 'music':
+          if (!step.musicPath) throw new Error('music step requires musicPath');
+          await this.addBackgroundMusic(current, nextPath, step.musicPath, opts);
+          break;
+        case 'slicesWithTransitions':
+          if (!step.slices?.length) throw new Error('slicesWithTransitions step requires slices array');
+          await this.slicesWithTransitions(current, nextPath, {
+            slices: step.slices,
+            transition: step.transition,
+            preset: step.preset,
+          }, opts);
+          break;
+        case 'audioOnly':
+          if (!step.outputPath) throw new Error('extractAudioOnly step requires outputPath');
+          await this.extractAudioOnly(current, step.outputPath, opts);
+          break;
+        default:
+          throw new Error(`Unknown pipeline op: ${op}`);
+      }
+
+      current = nextPath;
+    }
+
+    for (const file of intermediates) {
+      try {
+        await fs.promises.unlink(file);
+      } catch (e) {
+        if (e.code !== 'ENOENT') throw e;
+      }
+    }
+  }
+
+  /**
+   * Extract audio only from video. Converts to MP3 or M4A based on output file extension.
+   *
+   * @param {string} inputPath - Input video path
+   * @param {string} outputPath - Output audio path (.m4a = AAC, .mp3 = MP3)
+   * @param {object} [opts] - Options
+   * @param {number} [opts.bitrate] - Audio bitrate in kbps (default: 256 for AAC, 320 for MP3)
+   * @param {number} [opts.sampleRate=48000] - Sample rate in Hz
+   * @param {function(object): void} [opts.onProgress] - Progress callback
+   * @returns {Promise<void>}
+   */
+  async extractAudioOnly(inputPath, outputPath, opts = {}) {
+    const { onProgress, sampleRate = 48000 } = opts;
+    const ext = path.extname(outputPath).toLowerCase();
+    const isMp3 = ext === '.mp3';
+
+    const bitrate = opts.bitrate ?? (isMp3 ? 320 : 256);
+    const outputOptions = [
+      '-vn',
+      '-c:a',
+      isMp3 ? 'libmp3lame' : 'aac',
+      '-b:a',
+      `${bitrate}k`,
+      '-ar',
+      String(sampleRate),
+    ];
+
+    await run({
+      input: inputPath,
+      output: outputPath,
+      outputOptions,
+      onProgress,
+    });
+  }
+}
+
+module.exports = { FramecraftEngine };

package/src/executor.js

@@ -0,0 +1,158 @@
+const ffmpeg = require('fluent-ffmpeg');
+
+/**
+ * FFmpegExecutor - Single point of FFmpeg invocation.
+ * Wraps fluent-ffmpeg; can be swapped for raw spawn in Phase 2.
+ *
+ * Use complexFilter + complexFilterMap for -filter_complex (recommended) — uses
+ * fluent-ffmpeg's native API. Pass outputOptions only for encoding options.
+ *
+ * @typedef {object} ExecutorConfig
+ * @property {string} input - Input file path
+ * @property {string|string[]} [inputs] - Additional inputs (for multi-input commands)
+ * @property {string} output - Output file path
+ * @property {string|string[]} [videoFilters] - Video filter chain (-vf)
+ * @property {string|string[]} [audioFilters] - Audio filter chain (-af)
+ * @property {string} [complexFilter] - Full -filter_complex string (use fluent API; do not put in outputOptions)
+ * @property {string|string[]} [complexFilterMap] - Streams to map from filter (e.g. '[vout]' or ['[vout]','[aout]'])
+ * @property {string|string[]} [inputOptions] - Input options
+ * @property {string|string[]} [outputOptions] - Output options (encoding only; no -filter_complex/-map when using complexFilter)
+ * @property {number|string} [seek] - Input start time (seconds or timestamp)
+ * @property {number|string} [duration] - Output duration (seconds or timestamp)
+ * @property {number} [frames] - Number of frames to encode
+ * @property {string} [format] - Output format (e.g. 'mp4', 'image2')
+ * @property {number} [expectedDuration] - Expected output duration in seconds (for percent calculation)
+ * @property {function(object): void} [onProgress] - Progress callback
+ */
+
+function timemarkToSeconds(timemark) {
+  if (!timemark) return 0;
+  const parts = String(timemark).split(':');
+  if (parts.length !== 3) return 0;
+  const [h, m, s] = parts;
+  const seconds = parseFloat(s);
+  if (Number.isNaN(seconds)) return 0;
+  return Number(h) * 3600 + Number(m) * 60 + seconds;
+}
+
+/**
+ * Run FFmpeg with the given configuration.
+ *
+ * @param {ExecutorConfig} config
+ * @returns {Promise<void>}
+ */
+function run(config) {
+  return new Promise((resolve, reject) => {
+    const {
+      input,
+      inputs = [],
+      output,
+      videoFilters,
+      audioFilters,
+      complexFilter,
+      complexFilterMap,
+      inputOptions,
+      outputOptions,
+      seek,
+      duration,
+      frames,
+      format,
+      expectedDuration,
+      onProgress,
+    } = config;
+
+    let command = ffmpeg(input);
+
+    const extraInputs = Array.isArray(inputs) ? inputs : [inputs].filter(Boolean);
+    for (const inp of extraInputs) {
+      command = command.input(inp);
+    }
+
+    if (seek != null) {
+      command = command.seekInput(seek);
+    }
+    if (inputOptions && inputOptions.length > 0) {
+      command = command.inputOptions(inputOptions);
+    }
+
+    if (duration != null) {
+      command = command.duration(duration);
+    }
+    if (frames != null) {
+      command = command.frames(frames);
+    }
+    if (videoFilters) {
+      const vf = Array.isArray(videoFilters) ? videoFilters : [videoFilters];
+      command = command.videoFilters(vf);
+    }
+    if (audioFilters) {
+      const af = Array.isArray(audioFilters) ? audioFilters : [audioFilters];
+      command = command.audioFilters(af);
+    }
+    if (format) {
+      command = command.format(format);
+    }
+
+    if (complexFilter) {
+      const mapArr = complexFilterMap != null
+        ? (Array.isArray(complexFilterMap) ? complexFilterMap : [complexFilterMap])
+        : [];
+      command = command.complexFilter(complexFilter, mapArr.length ? mapArr : undefined);
+    }
+    if (outputOptions && outputOptions.length > 0) {
+      command = command.outputOptions(...outputOptions);
+    }
+
+    command = command.output(output);
+
+    if (typeof onProgress === 'function') {
+      command.on('progress', (progress) => {
+        const next = { ...progress };
+        if (expectedDuration && expectedDuration > 0 && next.timemark) {
+          const currentSeconds = timemarkToSeconds(next.timemark);
+          const rawPercent = (currentSeconds / expectedDuration) * 100;
+          if (Number.isFinite(rawPercent)) {
+            next.percent = Math.max(0, Math.min(100, rawPercent));
+          }
+        }
+        onProgress(next);
+      });
+    }
+    command.on('error', (err) => reject(err));
+    command.on('end', () => {
+      // if (typeof onProgress === 'function') onProgress({ percent: 100 });
+      resolve();
+    });
+
+    command.run();
+  });
+}
+
+/**
+ * Get video metadata (width, height, duration, etc.) via ffprobe.
+ *
+ * @param {string} inputPath
+ * @returns {Promise<{ width: number, height: number, duration: number, hasAudio: boolean }>}
+ */
+function probe(inputPath) {
+  return new Promise((resolve, reject) => {
+    ffmpeg.ffprobe(inputPath, (err, metadata) => {
+      if (err) return reject(err);
+
+      const videoStream = metadata.streams?.find((s) => s.codec_type === 'video');
+      const audioStream = metadata.streams?.find((s) => s.codec_type === 'audio');
+
+      const width = videoStream?.width ?? 0;
+      const height = videoStream?.height ?? 0;
+      const duration = metadata.format?.duration ?? 0;
+      const hasAudio = !!audioStream;
+
+      resolve({ width, height, duration, hasAudio });
+    });
+  });
+}
+
+module.exports = {
+  run,
+  probe,
+};

package/src/filters.js

@@ -0,0 +1,173 @@
+const path = require('path');
+
+/** @constant {string} Shorts target width */
+const SHORTS_WIDTH = 720;
+/** @constant {string} Shorts target height */
+const SHORTS_HEIGHT = 1280;
+
+/**
+ * Build FFmpeg -vf filter string for 9:16 vertical crop (Shorts/TikTok format).
+ * Crops centered 9:16 region from source, then scales to 720x1280.
+ *
+ * @param {number} width - Source video width
+ * @param {number} height - Source video height
+ * @returns {string} FFmpeg video filter string (crop,scale)
+ */
+function cropTo916Filter(width, height) {
+  const cropWidth = Math.floor((height * 9) / 16);
+  const cropHeight = height;
+  const x = Math.floor((width - cropWidth) / 2);
+  const y = 0;
+
+  const crop = `crop=${cropWidth}:${cropHeight}:${x}:${y}`;
+  const scale = `scale=${SHORTS_WIDTH}:${SHORTS_HEIGHT}`;
+
+  return `${crop},${scale}`;
+}
+
+/**
+ * Build FFmpeg subtitles filter string.
+ * Escape special characters in path for FFmpeg (colons, backslashes).
+ *
+ * @param {string} srtPath - Path to SRT subtitle file
+ * @param {object} [style] - Optional ASS force_style for future AI caption styling
+ * @param {string} [style.fontName] - Font name
+ * @param {string} [style.fontSize] - Font size
+ * @param {string} [style.primaryColour] - Primary colour (ASS format)
+ * @param {string} [style.outlineColour] - Outline colour
+ * @param {string} [style.backColour] - Background colour
+ * @param {number} [style.outline] - Outline thickness
+ * @param {number} [style.shadow] - Shadow depth
+ * @returns {string} FFmpeg subtitles filter string
+ */
+function subtitleFilter(srtPath, style = {}) {
+  const absPath = path.resolve(srtPath);
+  const escaped = absPath.replace(/\\/g, '\\\\').replace(/:/g, '\\:');
+
+  let filter = `subtitles='${escaped}'`;
+
+  const styleParts = [];
+  if (style.fontName) styleParts.push(`FontName=${style.fontName}`);
+  if (style.fontSize) styleParts.push(`FontSize=${style.fontSize}`);
+  if (style.primaryColour) styleParts.push(`PrimaryColour=${style.primaryColour}`);
+  if (style.outlineColour) styleParts.push(`OutlineColour=${style.outlineColour}`);
+  if (style.backColour) styleParts.push(`BackColour=${style.backColour}`);
+  if (style.outline !== undefined) styleParts.push(`Outline=${style.outline}`);
+  if (style.shadow !== undefined) styleParts.push(`Shadow=${style.shadow}`);
+
+  if (styleParts.length > 0) {
+    filter += `:force_style='${styleParts.join(',')}'`;
+  }
+
+  return filter;
+}
+
+/**
+ * Build FFmpeg -filter_complex string for mixing video with background music.
+ * Video keeps original stream; audio is mix of video audio + music.
+ *
+ * @param {boolean} [videoHasAudio=true] - Whether source video has audio track
+ * @returns {string} FFmpeg filter_complex string
+ */
+function amixFilter(videoHasAudio = true) {
+  if (videoHasAudio) {
+    return '[0:a][1:a]amix=inputs=2:duration=shortest[aout]';
+  }
+  return '[1:a]anull[aout]';
+}
+
+/**
+ * Build -filter_complex for multiple slices from one input with xfade/acrossfade transitions.
+ * Slices are applied to the same input (trim each range, then chain xfade/acrossfade).
+ *
+ * Each slice may optionally carry its own transition ({ type, duration }) which
+ * controls how the previous slice transitions into this one. If not present,
+ * the caller should already have applied the default/common transition.
+ *
+ * @param {Array<{ startSeconds: number, endSeconds: number, transition?: { type: string, duration: number } }>} slices
+ *        Normalized slice ranges in seconds, with optional per-slice transition (for slice i > 0).
+ * @param {boolean} hasAudio - Whether input has audio (to include acrossfade)
+ * @returns {{ filterComplex: string, mapVideo: string, mapAudio: string | null }}
+ */
+function buildSlicesWithTransitionsFilter(slices, hasAudio = true) {
+  if (!slices.length) throw new Error('slices must have at least one range');
+
+  const parts = [];
+  const durations = [];
+
+  for (let i = 0; i < slices.length; i++) {
+    const { startSeconds, endSeconds } = slices[i];
+    const d = endSeconds - startSeconds;
+    durations.push(d);
+    parts.push(
+      `[0:v]trim=start=${startSeconds}:end=${endSeconds},setpts=PTS-STARTPTS[v${i}]`
+    );
+    if (hasAudio) {
+      parts.push(
+        `[0:a]atrim=start=${startSeconds}:end=${endSeconds},asetpts=PTS-STARTPTS[a${i}]`
+      );
+    }
+  }
+
+  if (slices.length === 1) {
+    const filterComplex = parts.join(';');
+    return {
+      filterComplex,
+      mapVideo: '[v0]',
+      mapAudio: hasAudio ? '[a0]' : null,
+    };
+  }
+
+  let prevV = 'v0';
+  let prevA = 'a0';
+  let cumulativeOutDuration = durations[0];
+
+  for (let i = 1; i < slices.length; i++) {
+    const nextV = `v${i}`;
+    const nextA = `a${i}`;
+    const outV = i === slices.length - 1 ? 'vout' : `v${i - 1}${i}`;
+    const outA = i === slices.length - 1 ? 'aout' : `a${i - 1}${i}`;
+
+    const sliceTransition = slices[i].transition;
+    if (!sliceTransition) {
+      throw new Error(
+        `Missing transition for boundary before slice index ${i}; engine should provide default/common transition.`
+      );
+    }
+
+    const maxT = Math.min(durations[i - 1], durations[i]) - 0.01;
+    const t = Math.min(sliceTransition.duration, Math.max(0.01, maxT));
+    const type = sliceTransition.type;
+    const offset = cumulativeOutDuration - t;
+
+    parts.push(
+      `[${prevV}][${nextV}]xfade=transition=${type}:duration=${t}:offset=${offset}[${outV}]`
+    );
+    if (hasAudio) {
+      parts.push(
+        `[${prevA}][${nextA}]acrossfade=d=${t}:c1=tri:c2=tri[${outA}]`
+      );
+    }
+
+    cumulativeOutDuration = cumulativeOutDuration + durations[i] - t;
+    prevV = outV;
+    prevA = outA;
+  }
+
+  parts.push('[vout]format=yuv420p[v420]');
+  const filterComplex = parts.join(';');
+  return {
+    filterComplex,
+    mapVideo: '[v420]',
+    mapAudio: hasAudio ? '[aout]' : null,
+  };
+}
+
+module.exports = {
+  cropTo916Filter,
+  subtitleFilter,
+  amixFilter,
+  buildSlicesWithTransitionsFilter,
+  SHORTS_WIDTH,
+  SHORTS_HEIGHT,
+};