@amg555/frameforge-mcp 2.4.10 → 2.7.1

package/src/utils/transcribe.js

@@ -0,0 +1,341 @@
+/**
+ * transcribe.js — Speech Transcription & Silence Alignment via Whisper
+ *
+ * Provides word-level timestamps and speech pause detection for:
+ *   1. Precise speech-aligned video cuts (never slice words in half)
+ *   2. Karaoke/kinetic word caption generation
+ *   3. Intelligent speech-to-visual b-roll timing
+ *   4. Exporting SRT, NDJSON (engine.js), and JSON transcripts
+ */
+
+'use strict';
+
+const { spawnSync } = require('child_process');
+const path          = require('path');
+const fs            = require('fs');
+const os            = require('os');
+
+const DEFAULT_FILES_DIR = process.env.N8N_FILES_DIR || path.join(os.homedir(), '.frameforge-files');
+const TRANSCRIPTS_DIR   = path.join(DEFAULT_FILES_DIR, 'transcripts');
+
+/**
+ * Format seconds into SRT timestamp format: HH:MM:SS,mmm
+ * @param {number} sec
+ * @returns {string}
+ */
+function formatTimestampSrt(sec) {
+  const s = Math.max(0, Number(sec) || 0);
+  const hrs  = Math.floor(s / 3600);
+  const mins = Math.floor((s % 3600) / 60);
+  const secs = Math.floor(s % 60);
+  const ms   = Math.floor((s - Math.floor(s)) * 1000);
+  return `${String(hrs).padStart(2, '0')}:${String(mins).padStart(2, '0')}:${String(secs).padStart(2, '0')},${String(ms).padStart(3, '0')}`;
+}
+
+/**
+ * Format transcript segments into SRT subtitle text
+ * @param {Array<{ start: number, end: number, text?: string, word?: string }>} segments
+ * @returns {string}
+ */
+function formatAsSrt(segments = []) {
+  if (!Array.isArray(segments)) return '';
+  return segments.map((seg, idx) => {
+    const start = formatTimestampSrt(seg.start);
+    const end   = formatTimestampSrt(seg.end);
+    const text  = (seg.text || seg.word || '').trim();
+    return `${idx + 1}\n${start} --> ${end}\n${text}\n`;
+  }).join('\n');
+}
+
+/**
+ * Format transcript segments into NDJSON (one JSON object per line)
+ * Directly consumed by engine.js captions() and cuePhrase()
+ * @param {Array<{ start: number, end: number, text?: string, word?: string }>} segments
+ * @returns {string}
+ */
+function formatAsNdjson(segments = []) {
+  if (!Array.isArray(segments)) return '';
+  return segments.map(s => JSON.stringify({
+    start: Number(s.start || 0),
+    end:   Number(s.end || 0),
+    text:  (s.text || s.word || '').trim(),
+  })).join('\n');
+}
+
+/**
+ * Detect available Whisper engines
+ */
+function detectWhisper() {
+  const isWin = process.platform === 'win32';
+
+  // 1. Check faster-whisper (CTranslate2 — fastest local inference)
+  try {
+    const fwCheck = spawnSync('python', ['-c', 'import importlib.util, sys; sys.exit(0 if importlib.util.find_spec("faster_whisper") else 1)'], {
+      encoding: 'utf8',
+      timeout: 5000,
+      shell: false,
+    });
+    if (fwCheck.status === 0) {
+      return { available: true, engine: 'faster-whisper' };
+    }
+  } catch (_) {}
+
+  // 2. Python openai-whisper module check
+  try {
+    const pyCheck = spawnSync('python', ['-c', 'import importlib.util, sys; sys.exit(0 if importlib.util.find_spec("whisper") else 1)'], {
+      encoding: 'utf8',
+      timeout: 5000,
+      shell: false,
+    });
+    if (pyCheck.status === 0) {
+      return { available: true, engine: 'python-whisper' };
+    }
+  } catch (_) {}
+
+  // 3. Check CLI binary 'whisper'
+  try {
+    const cliRes = spawnSync('whisper', ['--version'], { encoding: 'utf8', timeout: 5000, shell: isWin });
+    if (cliRes.status === 0) return { available: true, engine: 'whisper-cli' };
+  } catch (_) {}
+
+  // 4. Cloud fallback if OPENAI_API_KEY
+  if (process.env.OPENAI_API_KEY) {
+    return { available: true, engine: 'openai-api' };
+  }
+
+  return { available: false, engine: 'none' };
+}
+
+/**
+ * Detect silence/pause segments using FFmpeg silencedetect filter
+ * (Deterministic, fast, works without any ML models)
+ *
+ * @param {string} audioPath
+ * @param {object} [opts]
+ * @param {number} [opts.noiseDb=-35]
+ * @param {number} [opts.minDuration=0.25]
+ * @returns {Array<{ start: number, end: number, duration: number }>}
+ */
+function detectPausesWithFFmpeg(audioPath, opts = {}) {
+  const noiseDb = opts.noiseDb != null ? opts.noiseDb : -35;
+  const minDur = opts.minDuration != null ? opts.minDuration : 0.25;
+
+  const res = spawnSync('ffmpeg', [
+    '-nostdin',
+    '-i', audioPath,
+    '-af', `silencedetect=n=${noiseDb}dB:d=${minDur}`,
+    '-f', 'null',
+    '-',
+  ], { encoding: 'utf8', timeout: 30000, shell: false });
+
+  const output = (res.stderr || '') + (res.stdout || '');
+  const pauses = [];
+
+  const startRegex = /silence_start:\s*([0-9.]+)/g;
+  const endRegex = /silence_end:\s*([0-9.]+)\s*\|\s*silence_duration:\s*([0-9.]+)/g;
+
+  let sMatch;
+  const starts = [];
+  while ((sMatch = startRegex.exec(output)) !== null) {
+    starts.push(parseFloat(sMatch[1]));
+  }
+
+  let eMatch;
+  let idx = 0;
+  while ((eMatch = endRegex.exec(output)) !== null) {
+    const end = parseFloat(eMatch[1]);
+    const duration = parseFloat(eMatch[2]);
+    const start = starts[idx] != null ? starts[idx] : Math.max(0, end - duration);
+    pauses.push({ start, end, duration });
+    idx++;
+  }
+
+  return pauses;
+}
+
+/**
+ * Snap a desired cut timestamp to the nearest speech pause/silence boundary
+ *
+ * @param {number} targetTime - Desired cut time in seconds
+ * @param {Array<{ start: number, end: number }>} pauses - Detected silence intervals
+ * @param {number} [tolerance=0.8] - Max seconds to shift the cut
+ * @returns {number} Adjusted cut timestamp
+ */
+function snapCutToPause(targetTime, pauses = [], tolerance = 0.8) {
+  if (!Array.isArray(pauses) || pauses.length === 0) return targetTime;
+
+  let bestTime = targetTime;
+  let minDiff = Infinity;
+
+  for (const p of pauses) {
+    // Middle of pause is the safest cut point
+    const mid = (p.start + p.end) / 2;
+    const diff = Math.abs(mid - targetTime);
+
+    if (diff <= tolerance && diff < minDiff) {
+      minDiff = diff;
+      bestTime = mid;
+    }
+  }
+
+  return Math.round(bestTime * 100) / 100;
+}
+
+/**
+ * Transcribe speech in audio/video to words and segments
+ *
+ * @param {string} mediaPath - Local audio or video file
+ * @param {object} [opts]
+ * @param {string} [opts.model='base'] - tiny|base|small|medium|large
+ * @param {string} [opts.language] - BCP-47 language hint
+ * @param {'ndjson'|'srt'|'json'|'all'} [opts.format] - Output format to generate
+ * @param {string} [opts.outputPath] - Optional output file path
+ * @returns {Promise<{
+ *   text: string,
+ *   duration: number,
+ *   words: Array<{ word: string, start: number, end: number }>,
+ *   segments: Array<{ id: number, start: number, end: number, text: string }>,
+ *   pauses: Array<{ start: number, end: number, duration: number }>,
+ *   files?: { srt?: string, ndjson?: string, json?: string }
+ * }>}
+ */
+async function transcribeAudio(mediaPath, opts = {}) {
+  if (!fs.existsSync(mediaPath)) {
+    throw new Error(`Media file not found for transcription: ${mediaPath}`);
+  }
+
+  const engine = detectWhisper();
+  const pauses = detectPausesWithFFmpeg(mediaPath);
+  let parsed = { text: '', duration: 0, words: [], segments: [] };
+  const isWin = process.platform === 'win32';
+  const cleanPath = mediaPath.replace(/\\/g, '/');
+  const modelName = opts.model || 'base';
+
+  // 1. faster-whisper execution
+  if (engine.engine === 'faster-whisper') {
+    const pyScript = `
+import json, sys
+from faster_whisper import WhisperModel
+model = WhisperModel("${modelName}", device="auto", compute_type="auto")
+segments, info = model.transcribe("${cleanPath}", word_timestamps=True${opts.language ? `, language="${opts.language}"` : ''})
+words = []
+seg_list = []
+idx = 0
+for s in segments:
+    seg_list.append({"id": idx, "start": round(s.start, 3), "end": round(s.end, 3), "text": s.text.strip()})
+    idx += 1
+    if s.words:
+        for w in s.words:
+            words.append({"word": w.word.strip(), "start": round(w.start, 3), "end": round(w.end, 3)})
+out = {
+    "text": " ".join([s["text"] for s in seg_list]),
+    "segments": seg_list,
+    "words": words,
+    "duration": round(info.duration, 3) if hasattr(info, "duration") else 0
+}
+print(json.dumps(out))
+`;
+    const res = spawnSync('python', ['-c', pyScript], { encoding: 'utf8', timeout: 180000, shell: false });
+    if (res.status === 0) {
+      try { parsed = JSON.parse(res.stdout); } catch (_) {}
+    }
+  }
+
+  // 2. Python openai-whisper execution
+  if (!parsed.text && engine.engine === 'python-whisper') {
+    const pyScript = `
+import whisper, json, sys
+model = whisper.load_model("${modelName}")
+result = model.transcribe("${cleanPath}", word_timestamps=True${opts.language ? `, language="${opts.language}"` : ''})
+words = []
+seg_list = []
+for idx, s in enumerate(result.get("segments", [])):
+    seg_list.append({"id": idx, "start": round(s.get("start", 0), 3), "end": round(s.get("end", 0), 3), "text": s.get("text", "").strip()})
+    for w in s.get("words", []):
+        words.append({"word": w.get("word", "").strip(), "start": round(w.get("start", 0), 3), "end": round(w.get("end", 0), 3)})
+out = {
+    "text": result.get("text", "").strip(),
+    "segments": seg_list,
+    "words": words
+}
+print(json.dumps(out))
+`;
+    const res = spawnSync('python', ['-c', pyScript], { encoding: 'utf8', timeout: 180000, shell: isWin });
+    if (res.status === 0) {
+      try { parsed = JSON.parse(res.stdout); } catch (_) {}
+    }
+  }
+
+  // 3. Fallback: measure duration via ffprobe if whisper did not provide it
+  if (!parsed.duration || parsed.duration <= 0) {
+    try {
+      const probe = spawnSync('ffprobe', [
+        '-v', 'error',
+        '-show_entries', 'format=duration',
+        '-of', 'default=noprint_wrappers=1:nokey=1',
+        mediaPath,
+      ], { encoding: 'utf8', timeout: 5000, shell: isWin });
+      parsed.duration = parseFloat((probe.stdout || '0').trim()) || 0;
+    } catch (_) {}
+  }
+
+  const result = {
+    text: parsed.text || '',
+    duration: parsed.duration || (parsed.segments?.length ? parsed.segments[parsed.segments.length - 1].end : 0),
+    words: parsed.words || [],
+    segments: parsed.segments || [],
+    pauses,
+  };
+
+  // 4. Output files generation if requested
+  if (opts.format || opts.outputPath) {
+    const targetFormat = opts.format || 'ndjson';
+    const outDir = opts.outputPath ? path.dirname(opts.outputPath) : TRANSCRIPTS_DIR;
+    fs.mkdirSync(outDir, { recursive: true });
+    const basename = path.basename(mediaPath, path.extname(mediaPath));
+    const files = {};
+
+    const segs = result.segments.length > 0
+      ? result.segments
+      : result.words.map(w => ({ start: w.start, end: w.end, text: w.word }));
+
+    if (targetFormat === 'ndjson' || targetFormat === 'all') {
+      const ndjsonPath = (opts.outputPath && targetFormat === 'ndjson')
+        ? opts.outputPath
+        : path.join(outDir, `${basename}.captions.ndjson`);
+      fs.writeFileSync(ndjsonPath, formatAsNdjson(segs), 'utf8');
+      files.ndjson = ndjsonPath;
+    }
+
+    if (targetFormat === 'srt' || targetFormat === 'all') {
+      const srtPath = (opts.outputPath && targetFormat === 'srt')
+        ? opts.outputPath
+        : path.join(outDir, `${basename}.subtitles.srt`);
+      fs.writeFileSync(srtPath, formatAsSrt(segs), 'utf8');
+      files.srt = srtPath;
+    }
+
+    if (targetFormat === 'json' || targetFormat === 'all') {
+      const jsonPath = (opts.outputPath && targetFormat === 'json')
+        ? opts.outputPath
+        : path.join(outDir, `${basename}.transcript.json`);
+      fs.writeFileSync(jsonPath, JSON.stringify(result, null, 2), 'utf8');
+      files.json = jsonPath;
+    }
+
+    result.files = files;
+  }
+
+  return result;
+}
+
+module.exports = {
+  detectWhisper,
+  detectPausesWithFFmpeg,
+  snapCutToPause,
+  formatTimestampSrt,
+  formatAsSrt,
+  formatAsNdjson,
+  transcribeAudio,
+};
+

package/src/video-editor/editor.js

@@ -24,12 +24,16 @@ const crypto        = require('crypto');
 
 const { AudioMixer }  = require('../audio-mixer/mixer');
 const { resolveFont } = require('../video-renderer/renderer');
+const { buildCameraFilter } = require('../animation/animation-system');
 
 const DEFAULT_FILES_DIR = process.env.N8N_FILES_DIR || path.join(os.homedir(), '.frameforge-files');
 
-// Supported color grading presets (all curves coordinates must be in [0, 1] range)
+// Supported color grading presets — derived from lemo-opuscar film styles catalog
+// All curves coordinates are in [0, 1] range. FFmpeg curves filter format:
+//   curves=r='in/out ...' where in/out are normalized [0,1] brightness values.
 const COLOR_GRADES = {
   none: null,
+  // ── Core presets ─────────────────────────────────────────────────────────
   cinematic: "curves=m='0/0 0.25/0.2 0.75/0.8 1/1':r='0/0 0.5/0.53 1/1':b='0/0.03 0.5/0.48 1/0.97',eq=saturation=1.12:contrast=1.05",
   warm: "curves=r='0/0 0.5/0.55 1/1':b='0/0 0.5/0.45 1/0.92',eq=saturation=1.08",
   cool: "curves=b='0/0 0.5/0.56 1/1':r='0/0 0.5/0.46 1/0.94',eq=saturation=0.98",
@@ -38,16 +42,50 @@ const COLOR_GRADES = {
   monochrome: "hue=s=0,eq=contrast=1.15",
   vibrant: "eq=saturation=1.35:contrast=1.05",
   cyberpunk: "curves=r='0/0 0.5/0.45 1/1':b='0/0.08 0.5/0.58 1/1',eq=saturation=1.3:contrast=1.1",
+  editorial_collage: "curves=vintage,eq=contrast=1.1:saturation=0.9",
+  editorial: "curves=vintage,eq=contrast=1.1:saturation=0.9",
+  product_launch: "curves=m='0/0 0.5/0.52 1/1':b='0/0 0.5/0.53 1/0.98',eq=contrast=1.08:saturation=1.05",
+  retrovhs: "curves=vintage,hue=s=0.9,eq=contrast=1.1",
+  anime: "curves=m='0/0 0.4/0.45 1/1',eq=saturation=1.4:contrast=1.12",
+  scifi: "curves=r='0/0 0.5/0.46 1/1':b='0/0 0.5/0.56 1/1',eq=contrast=1.15:saturation=1.1",
+  lofi: "curves=m='0/0.05 0.5/0.5 1/0.95',eq=saturation=0.9:contrast=0.95",
+  // ── lemo-opuscar extended film styles ────────────────────────────────────
+  // Cinematic 2.39:1 (Anamorphic) — deep teal shadows, copper highlights
+  cinematic_anamorphic: "curves=m='0/0 0.22/0.18 0.78/0.82 1/1':r='0/0 0.5/0.53 1/1':g='0/0 0.5/0.51 1/0.99':b='0/0.04 0.5/0.50 1/0.97',eq=saturation=1.18:contrast=1.07",
+  // Minimal Swiss Monochrome — stark contrast, no colour
+  swiss_mono: "hue=s=0,curves=m='0/0 0.15/0.05 0.5/0.5 0.85/0.95 1/1',eq=contrast=1.3",
+  // Anime Action — vivid, punchy, high saturation
+  anime_action: "curves=m='0/0 0.38/0.44 0.8/0.88 1/1',eq=saturation=1.45:contrast=1.15",
+  // Retro VHS 1980s — phosphor green tint, lifted blacks, slight cyan cast
+  retro_vhs_80s: "curves=r='0/0.02 0.5/0.46 1/0.94':g='0/0.03 0.5/0.52 1/1.0':b='0/0.05 0.5/0.54 1/0.98',eq=saturation=0.88:contrast=0.98",
+  // Lo-Fi Chill — pastel, soft, desaturated with warm cast
+  lofi_chill: "curves=r='0/0.04 0.5/0.52 1/0.96':b='0/0.02 0.5/0.50 1/0.94',eq=saturation=0.82:contrast=0.92",
+  // Broadcast News Financial — clinical blue, minimal warmth
+  broadcast_news: "curves=r='0/0 0.5/0.47 1/0.97':b='0/0 0.5/0.54 1/1.02',eq=saturation=1.05:contrast=1.08",
+  // 3D Isometric Blueprint — technical cobalt, washed midtones
+  blueprint: "curves=r='0/0 0.5/0.44 1/0.95':g='0/0 0.5/0.50 1/0.98':b='0/0.06 0.5/0.58 1/1.02'],eq=saturation=1.12:contrast=1.0",
+  // Vintage 16mm film — sepia warm grain simulation
+  film16mm: "curves=vintage,curves=r='0/0.02 0.5/0.53 1/0.97':b='0/0 0.5/0.44 1/0.90',eq=saturation=0.80:contrast=0.92",
+  // Product Launch — clean obsidian black, titanium silver, subtle blue accent
+  product_obsidian: "curves=m='0/0 0.3/0.22 0.7/0.78 1/1':b='0/0 0.5/0.52 1/1',eq=saturation=1.02:contrast=1.1",
 };
 
-// Supported transition types in FFmpeg xfade
+// Supported transition types in FFmpeg xfade — including all known xfade variants
 const VALID_TRANSITIONS = new Set([
   'fade', 'wipeleft', 'wiperight', 'wipeup', 'wipedown',
   'slideleft', 'slideright', 'slideup', 'slidedown',
   'circlecrop', 'rectcrop', 'distance', 'fadeblack', 'fadewhite',
   'radial', 'smoothleft', 'smoothright', 'smoothup', 'smoothdown',
   'circleopen', 'circleclose', 'dissolve', 'pixelize', 'diagtl',
-  'diagtr', 'diagbl', 'diagbr', 'hlslice', 'hrslice', 'vuslice', 'vdslice'
+  'diagtr', 'diagbl', 'diagbr', 'hlslice', 'hrslice', 'vuslice', 'vdslice',
+  // Additional xfade variants (FFmpeg 5.0+)
+  'horzopen', 'horzclose', 'vertopen', 'vertclose',
+  'coverleft', 'coverright', 'coverup', 'coverdown',
+  'revealleft', 'revealright', 'revealup', 'revealdown',
+  'zoomin', 'fadegrays', 'squeezeh', 'squeezev',
+  'hblur', 'hlwind', 'hrwind', 'vuwind', 'vdwind',
+  // Aliases recognized by plan_video_edit style configs
+  'cut', 'none',
 ]);
 
 /**
@@ -254,6 +292,9 @@ class VideoEditor {
     voicePath = null,
     colorGrade = null,
     caption = '',
+    motion = null,
+    cameraHint = null,
+    punchIn = false,
     orientation = 'landscape',
     width,
     height,
@@ -315,6 +356,15 @@ class VideoEditor {
       vfParts.push(spFilters.videoFilter);
     }
 
+    // Dynamic camera motion & punch-ins (zoompan push, drift, or pan)
+    const motionHint = (motion || cameraHint || (punchIn ? 'zoom_in' : null));
+    if (motionHint && motionHint !== 'static' && motionHint !== 'none') {
+      try {
+        const camFilter = buildCameraFilter(motionHint, { duration: finalDur, w: targetW, h: targetH });
+        if (camFilter) vfParts.push(camFilter);
+      } catch (_) {}
+    }
+
     const colorFilter = buildColorFilter(colorGrade);
     if (colorFilter) {
       vfParts.push(colorFilter);
@@ -328,14 +378,13 @@ class VideoEditor {
     vfParts.push('format=yuv420p');
 
     // Build FFmpeg command arguments
-    const ffmpegArgs = ['-nostdin', '-y'];
+    const ffmpegArgs = ['-nostdin', '-y', '-threads', '2'];
 
     // Fast input seek
     if (startSec > 0) {
       ffmpegArgs.push('-ss', startSec.toFixed(3));
     }
 
-    ffmpegArgs.push('-t', durSec.toFixed(3));
     ffmpegArgs.push('-i', videoPath);
 
     const hasVoice = voicePath && fs.existsSync(voicePath);
@@ -379,6 +428,7 @@ class VideoEditor {
 
     // Encoding parameters: broadcast quality BT.709
     ffmpegArgs.push(
+      '-threads', '4',
       '-c:v', 'libx264', '-preset', 'veryfast', '-crf', '22',
       '-profile:v', 'high', '-level', '4.1',
       '-color_range', 'tv', '-colorspace', 'bt709',
@@ -420,6 +470,7 @@ class VideoEditor {
     clips = [],
     transition = 'fade',
     transitionDuration = 0.5,
+    splitCut = 'none',
     outputPath = null,
   } = {}) {
     if (!Array.isArray(clips) || clips.length === 0) {
@@ -458,7 +509,7 @@ class VideoEditor {
 
     if (!usesTransitions) {
       // Fast concat filter without xfade
-      const ffmpegArgs = ['-nostdin', '-y'];
+      const ffmpegArgs = ['-nostdin', '-y', '-threads', '2'];
       for (const c of normClips) {
         ffmpegArgs.push('-i', c.path);
       }
@@ -467,6 +518,7 @@ class VideoEditor {
       ffmpegArgs.push(
         '-filter_complex', filter,
         '-map', '[vout]', '-map', '[aout]',
+        '-threads', '4',
         '-c:v', 'libx264', '-preset', 'veryfast', '-crf', '22',
         '-c:a', 'aac', '-b:a', '192k', '-ar', '48000', '-ac', '2',
         '-pix_fmt', 'yuv420p',
@@ -482,7 +534,7 @@ class VideoEditor {
     }
 
     // Build xfade + acrossfade filter complex
-    const ffmpegArgs = ['-nostdin', '-y'];
+    const ffmpegArgs = ['-nostdin', '-y', '-threads', '2'];
     for (const c of normClips) {
       ffmpegArgs.push('-i', c.path);
     }
@@ -520,8 +572,21 @@ class VideoEditor {
       vFilters.push(
         `${prevV}${nextV}xfade=transition=${tType}:duration=${tDur.toFixed(3)}:offset=${currentOffset.toFixed(3)}${outV}`
       );
+
+      // Split cut (lemomo-ai/lemo-opuscar): J-cut (audio leads video) or L-cut (audio trails video)
+      const sCut = clipConfig.splitCut || splitCut || 'none';
+      let curve1 = 'tri';
+      let curve2 = 'tri';
+      if (sCut === 'j-cut') {
+        curve1 = 'qsin';
+        curve2 = 'hsin';
+      } else if (sCut === 'l-cut') {
+        curve1 = 'hsin';
+        curve2 = 'qsin';
+      }
+
       aFilters.push(
-        `${prevA}${nextA}acrossfade=d=${tDur.toFixed(3)}:curve1=tri:curve2=tri${outA}`
+        `${prevA}${nextA}acrossfade=d=${tDur.toFixed(3)}:curve1=${curve1}:curve2=${curve2}${outA}`
       );
     }
 
@@ -530,6 +595,7 @@ class VideoEditor {
     ffmpegArgs.push(
       '-filter_complex', filterComplex,
       '-map', '[vout]', '-map', '[aout]',
+      '-threads', '4',
       '-c:v', 'libx264', '-preset', 'veryfast', '-crf', '22',
       '-profile:v', 'high', '-level', '4.1',
       '-color_range', 'tv', '-colorspace', 'bt709',
@@ -575,7 +641,14 @@ class VideoEditor {
     clips = [],
     audioPath = null,
     musicPath = null,
-    musicVolume = 0.08,
+    musicVolume = 0.12,
+    duckLevel = -18,
+    sfxCues = [],
+    roomProfile = null,
+    noiseGate = false,
+    stereoWiden = true,
+    platform = null,
+    targetLufs = -14,
     orientation = 'landscape',
     width,
     height,
@@ -635,6 +708,8 @@ class VideoEditor {
       const cVoice = c.audio_path || c.audioPath || null;
       const cStart = c.start_time != null ? c.start_time : (c.startTime != null ? c.startTime : (c.trim_start != null ? c.trim_start : 0));
       const cEnd = c.end_time != null ? c.end_time : (c.endTime != null ? c.endTime : (c.trim_end != null ? c.trim_end : null));
+      const cMotion = c.motion || c.camera_hint || c.cameraHint || null;
+      const cPunchIn = Boolean(c.punch_in || c.punchIn);
 
       const edited = this.editClip({
         videoPath: videoP,
@@ -646,6 +721,8 @@ class VideoEditor {
         voicePath: cVoice,
         colorGrade: cGrade,
         caption: cCaption,
+        motion: cMotion,
+        punchIn: cPunchIn,
         orientation,
         width: targetW,
         height: targetH,
@@ -693,17 +770,25 @@ class VideoEditor {
       }
     }
 
-    // Step 4: Mix background music with ducking if provided
+    // Step 4: Mix background music and professional SFX with ducking if provided
     const outFinal = outputPath || path.join(
       this.filesDir,
       `video_edit_${crypto.randomBytes(4).toString('hex')}_${Date.now()}.mp4`
     );
 
-    if (musicPath && fs.existsSync(musicPath)) {
+    if ((musicPath && fs.existsSync(musicPath)) || (Array.isArray(sfxCues) && sfxCues.length > 0)) {
       this.mixer.mixVideo({
         videoPath: currentVideoPath,
         musicPath,
         outputPath: outFinal,
+        musicVolume,
+        duckLevel,
+        sfxCues,
+        roomProfile,
+        noiseGate,
+        stereoWiden,
+        platform,
+        targetLufs,
       });
     } else {
       fs.copyFileSync(currentVideoPath, outFinal);

package/src/workflows/ingest.js

@@ -49,6 +49,7 @@ const fs      = require('fs');
 const fsp     = require('fs').promises;
 const path    = require('path');
 const crypto  = require('crypto');
+const { isWebUrl, downloadMediaWithYtDlp } = require('../utils/media-downloader');
 // ── Constants ─────────────────────────────────────────────────────────────────
 
 const VIDEO_EXTS = new Set(['.mp4','.mov','.avi','.mkv','.webm','.m4v','.flv','.ts']);
@@ -213,6 +214,15 @@ function normaliseIngestScene(raw, index, baseDir = process.cwd()) {
 
   function resolveMedia(p) {
     if (!p) return null;
+    if (isWebUrl(p)) {
+      try {
+        const dl = downloadMediaWithYtDlp(p);
+        return dl.localPath;
+      } catch (err) {
+        console.warn(`  ⚠️  Scene ${sceneId}: failed to download media URL ${p}: ${err.message}`);
+        return null;
+      }
+    }
     const resolved = path.isAbsolute(p) ? p : path.resolve(baseDir, p);
     if (!fs.existsSync(resolved)) {
       console.warn(`  ⚠️  Scene ${sceneId}: media file not found: ${resolved}`);