@amg555/frameforge-mcp 2.7.3 → 2.7.7

package/src/pipeline/providers.js

@@ -356,6 +356,8 @@ class TTSProvider {
    * @param {string} [opts.rate]       Speaking rate (overrides TTS_RATE)
    * @param {string} [opts.apiKey]     API key (overrides provider-specific env var)
    * @param {string} [opts.webhookUrl] Webhook URL (overrides WEBHOOK_TTS_URL)
+   * @param {string} [opts.language]   BCP-47 language hint (e.g. 'ml', 'hi', 'fr') used as fallback
+   *                                   voice selector when text is in a Latin script
    */
   constructor(opts = {}) {
     this.name        = (opts.platform || process.env.PROVIDER_TTS || 'edge-tts').toLowerCase();
@@ -371,37 +373,87 @@ class TTSProvider {
    * @param {string} [text]           narration text for language detection
    * @returns {string}
    */
-  selectNarratorVoice(explicitVoice, text = '') {
+  selectNarratorVoice(explicitVoice, text = '', langHint = '') {
     if (explicitVoice) return explicitVoice;
 
-    // Language detection for edge-tts
-    if (this.name === 'edge-tts' && text) {
-      const gender = (process.env.TTS_VOICE_GENDER || 'default').toLowerCase();
-      if (/[\u0D00-\u0D7F]/.test(text)) {
+    const gender = (process.env.TTS_VOICE_GENDER || 'default').toLowerCase();
+
+    // Language detection for edge-tts — Unicode-range script detection + BCP-47 hint
+    if (this.name === 'edge-tts') {
+      // Unicode script ranges (text content detection)
+      if (text && /[\u0D00-\u0D7F]/.test(text)) {
         return gender === 'female' ? 'ml-IN-SobhanaNeural' : 'ml-IN-MidhunNeural';
       }
-      if (/[\u0900-\u097F]/.test(text)) {
+      if (text && /[\u0900-\u097F]/.test(text)) {
         return gender === 'female' ? 'hi-IN-SwaraNeural' : 'hi-IN-MadhurNeural';
       }
-      if (/[\u0B80-\u0BFF]/.test(text)) {
+      if (text && /[\u0B80-\u0BFF]/.test(text)) {
         return gender === 'female' ? 'ta-IN-PallaviNeural' : 'ta-IN-ValluvarNeural';
       }
-      if (/[\u0C00-\u0C7F]/.test(text)) {
+      if (text && /[\u0C00-\u0C7F]/.test(text)) {
         return gender === 'female' ? 'te-IN-ShrutiNeural' : 'te-IN-MohanNeural';
       }
-      if (/[\u4E00-\u9FFF]/.test(text)) {
+      if (text && /[\u0C80-\u0CFF]/.test(text)) {
+        // Kannada
+        return gender === 'female' ? 'kn-IN-SapnaNeural' : 'kn-IN-GaganNeural';
+      }
+      if (text && /[\u0980-\u09FF]/.test(text)) {
+        // Bengali
+        return gender === 'female' ? 'bn-IN-TanishaaNeural' : 'bn-IN-BashkarNeural';
+      }
+      if (text && /[\u4E00-\u9FFF\u3400-\u4DBF]/.test(text)) {
         return gender === 'female' ? 'zh-CN-XiaoxiaoNeural' : 'zh-CN-YunjianNeural';
       }
-      if (/[\u3040-\u30FF]/.test(text)) {
+      if (text && /[\u3040-\u30FF\u31F0-\u31FF]/.test(text)) {
         return gender === 'female' ? 'ja-JP-NanamiNeural' : 'ja-JP-KeitaNeural';
       }
-      if (/[\u0600-\u06FF]/.test(text)) {
+      if (text && /[\uAC00-\uD7AF]/.test(text)) {
+        // Korean
+        return gender === 'female' ? 'ko-KR-SunHiNeural' : 'ko-KR-InJoonNeural';
+      }
+      if (text && /[\u0600-\u06FF]/.test(text)) {
         return gender === 'female' ? 'ar-SA-ZariyahNeural' : 'ar-SA-HamedNeural';
       }
+      if (text && /[\u0400-\u04FF]/.test(text)) {
+        // Cyrillic (Russian)
+        return gender === 'female' ? 'ru-RU-SvetlanaNeural' : 'ru-RU-DmitryNeural';
+      }
+
+      // BCP-47 language hint fallback (used when text is English but language is known)
+      const lang = (langHint || this._overrides.language || process.env.TTS_LANGUAGE || '').toLowerCase().slice(0, 2);
+      const LANG_VOICE_MAP = {
+        ml: gender === 'female' ? 'ml-IN-SobhanaNeural'  : 'ml-IN-MidhunNeural',
+        hi: gender === 'female' ? 'hi-IN-SwaraNeural'    : 'hi-IN-MadhurNeural',
+        ta: gender === 'female' ? 'ta-IN-PallaviNeural'  : 'ta-IN-ValluvarNeural',
+        te: gender === 'female' ? 'te-IN-ShrutiNeural'   : 'te-IN-MohanNeural',
+        kn: gender === 'female' ? 'kn-IN-SapnaNeural'    : 'kn-IN-GaganNeural',
+        bn: gender === 'female' ? 'bn-IN-TanishaaNeural' : 'bn-IN-BashkarNeural',
+        mr: gender === 'female' ? 'mr-IN-AarohiNeural'   : 'mr-IN-ManoharNeural',
+        gu: gender === 'female' ? 'gu-IN-DhwaniNeural'   : 'gu-IN-NiranjanNeural',
+        pa: gender === 'female' ? 'pa-IN-OjasvNeural'    : 'pa-IN-OjasvNeural',
+        ur: gender === 'female' ? 'ur-PK-UzmaNeural'     : 'ur-PK-AsadNeural',
+        zh: gender === 'female' ? 'zh-CN-XiaoxiaoNeural' : 'zh-CN-YunjianNeural',
+        ja: gender === 'female' ? 'ja-JP-NanamiNeural'   : 'ja-JP-KeitaNeural',
+        ko: gender === 'female' ? 'ko-KR-SunHiNeural'    : 'ko-KR-InJoonNeural',
+        ar: gender === 'female' ? 'ar-SA-ZariyahNeural'  : 'ar-SA-HamedNeural',
+        ru: gender === 'female' ? 'ru-RU-SvetlanaNeural' : 'ru-RU-DmitryNeural',
+        fr: gender === 'female' ? 'fr-FR-DeniseNeural'   : 'fr-FR-HenriNeural',
+        de: gender === 'female' ? 'de-DE-KatjaNeural'    : 'de-DE-ConradNeural',
+        es: gender === 'female' ? 'es-ES-ElviraNeural'   : 'es-ES-AlvaroNeural',
+        pt: gender === 'female' ? 'pt-BR-FranciscaNeural': 'pt-BR-AntonioNeural',
+        it: gender === 'female' ? 'it-IT-ElsaNeural'     : 'it-IT-DiegoNeural',
+        nl: gender === 'female' ? 'nl-NL-ColetteNeural'  : 'nl-NL-MaartenNeural',
+        pl: gender === 'female' ? 'pl-PL-ZofiaNeural'    : 'pl-PL-MarekNeural',
+        sv: gender === 'female' ? 'sv-SE-SofieNeural'    : 'sv-SE-MattiasNeural',
+        tr: gender === 'female' ? 'tr-TR-EmelNeural'     : 'tr-TR-AhmetNeural',
+        vi: gender === 'female' ? 'vi-VN-HoaiMyNeural'   : 'vi-VN-NamMinhNeural',
+        id: gender === 'female' ? 'id-ID-GadisNeural'    : 'id-ID-ArdiNeural',
+        th: gender === 'female' ? 'th-TH-PremwadeeNeural': 'th-TH-NiwatNeural',
+      };
+      if (lang && LANG_VOICE_MAP[lang]) return LANG_VOICE_MAP[lang];
     }
 
-    const voices  = NARRATOR_VOICES[this.name] || NARRATOR_VOICES['edge-tts'];
-    const gender  = (process.env.TTS_VOICE_GENDER || 'default').toLowerCase();
+    const voices = NARRATOR_VOICES[this.name] || NARRATOR_VOICES['edge-tts'];
     return voices[gender] || voices.default;
   }
 
@@ -411,8 +463,8 @@ class TTSProvider {
    *   voice is optional — if omitted, selectNarratorVoice() picks automatically
    * @returns {Promise<string>} resolves with outputPath
    */
-  async synthesize({ text, voice, outputPath }) {
-    const resolvedVoice = this.selectNarratorVoice(voice, text);
+  async synthesize({ text, voice, outputPath, language = '' }) {
+    const resolvedVoice = this.selectNarratorVoice(voice, text, language);
     switch (this.name) {
       case 'edge-tts':   return this._edgeTTS({ text, voice: resolvedVoice, outputPath });
       case 'elevenlabs': return this._elevenLabs({ text, voice: resolvedVoice, outputPath });
@@ -491,6 +543,13 @@ class TTSProvider {
   }
 
   async _edgeTTS({ text, voice, outputPath }) {
+    try {
+      const { isCommandAvailable, ensureEdgeTts } = require('../utils/tool-installer');
+      if (!isCommandAvailable('edge-tts')) {
+        ensureEdgeTts();
+      }
+    } catch (_) {}
+
     const rawPath   = outputPath.replace(/\.[^.]+$/, '_raw.mp3');
     const txtPath   = rawPath + '.txt';
     const safeVoice = voice || this.selectNarratorVoice(null, text);
@@ -507,11 +566,12 @@ class TTSProvider {
           proc.on('close', code => code === 0 ? resolve() : reject(new Error(`edge-tts exited ${code}: ${stderr}`)));
           proc.on('error', reject);
         });
-        // Normalise audio via FFmpeg — trim trailing silence, normalise levels
+        // Normalise audio via FFmpeg — professional sound engineer voice chain:
+        // Highpass 80Hz (sub rumble cut) -> Mud notch 300Hz -> Vocal presence 4.5kHz -> Smooth broadcast leveling
         await new Promise((resolve, reject) => {
           const proc = spawn('ffmpeg', ['-nostdin', '-y', '-threads', '2',
             '-i', rawPath,
-            '-af', 'silenceremove=stop_periods=-1:stop_duration=0.3:stop_threshold=-40dB,highpass=f=80,volume=1.0,dynaudnorm=f=150:g=5:p=0.95',
+            '-af', 'silenceremove=stop_periods=-1:stop_duration=0.3:stop_threshold=-40dB,highpass=f=80,equalizer=f=300:t=q:w=1.2:g=-1.5,equalizer=f=4500:t=q:w=1.5:g=1.5,volume=1.0,dynaudnorm=f=150:g=5:p=0.95',
             '-ar', '48000', '-ac', '2', '-c:a', 'aac', '-b:a', '192k', outputPath], { timeout: 30000 });
           let stderr = '';
           proc.stderr?.on('data', d => { stderr += d; });

package/src/skills/sync-upstream.js

@@ -99,13 +99,25 @@ const REPOSITORIES = [
     capabilities: ['edit_video', 'plan_video_edit', 'mix_audio_pro'],
     userImpact: 'New FFmpeg filter patterns or video editing operations available',
   },
+  {
+    id: 'aiinsight-shorts', repo: 'frameforge/aiinsight-shorts', branch: 'main', category: 'shorts',
+    desc: '6-style faceless-shorts skill (Deep Dive 3D, Night File 3D, Inside Out, Stick Story, Paper Atlas, Tall Tale 3D) — canvas+three.js, Kokoro TTS, Whisper word-sync, ffmpeg MP4. By Motion Graphics / AI Insight Spot.',
+    capabilities: ['create_short', 'list_short_styles'],
+    userImpact: 'New faceless-shorts styles, kit components, or rendering techniques available from aiinsight-shorts upstream',
+  },
+  {
+    id: 'openshorts', repo: 'mutonby/openshorts', branch: 'main', category: 'clip-detection',
+    desc: 'Open-source OpusClip alternative — AI viral moment detection, face-tracked 9:16 reframing (TRACK/SPLIT/SCREENCAST layouts), karaoke subtitles, hook overlays, social auto-publish. MIT. 7.9k stars.',
+    capabilities: ['detect_viral_clips', 'karaoke_subtitles'],
+    userImpact: 'New clip detection algorithms, subtitle styles, layout types, or hook rendering techniques from openshorts upstream',
+  },
 ];
 
 function fetchJson(url) {
   return new Promise((resolve, reject) => {
     const opts = {
       headers: {
-        'User-Agent': 'FrameForge-Skill-Sync/2.7.3',
+        'User-Agent': 'FrameForge-Skill-Sync/2.7.7',
         'Accept': 'application/vnd.github.v3+json',
       },
     };
@@ -176,7 +188,7 @@ async function syncSkills(opts = {}) {
   const updatedResults = results.filter(r => r.updated);
 
   manifest.lastSync = new Date().toISOString();
-  manifest.version = '2.7.3';
+  manifest.version = '2.7.7';
   manifest.updatedCount = updatedCount;
   if (updatedResults.length > 0) {
     manifest.pendingUpdates = updatedResults.map(r => {
@@ -266,7 +278,7 @@ function getUpstreamSummary() {
   return {
     repoCount,
     lastSync: manifest.lastSync,
-    version: manifest.version || '2.7.3',
+    version: manifest.version || '2.7.7',
     pendingUpdates: pending,
     hasUpdates: pending.length > 0,
     repos: manifest.repos || {},

package/src/utils/media-downloader.js

@@ -95,6 +95,13 @@ function downloadMediaWithYtDlp(url, opts = {}) {
 
   args.push('-o', outTemplate, url);
 
+  if (!detectYtDlp()) {
+    const { ensureYtDlp } = require('./tool-installer');
+    if (!ensureYtDlp()) {
+      throw new Error('yt-dlp is not installed and auto-install failed. Run: pip install yt-dlp');
+    }
+  }
+
   const res = spawnSync('yt-dlp', args, {
     encoding: 'utf8',
     timeout: 180000, // 3 min max

package/src/utils/tool-installer.js

@@ -0,0 +1,212 @@
+/**
+ * tool-installer.js — Automatic Dependency Provisioning for FrameForge
+ *
+ * Automatically checks and installs required runtime tools on demand:
+ *   - edge-tts (free broadcast-grade neural TTS)
+ *   - yt-dlp (video/audio downloader)
+ *   - whisper (word-level transcription & silence alignment)
+ *   - playwright chromium (headless browser for code-driven animation)
+ *
+ * Ensures smooth zero-config experience: users run an npm command and
+ * FrameForge automatically fetches missing binaries/packages if needed.
+ */
+
+'use strict';
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * Check if a command is executable on PATH
+ * @param {string} cmd
+ * @param {string[]} args
+ * @returns {boolean}
+ */
+function isCommandAvailable(cmd, args = ['--version']) {
+  // FFmpeg and FFprobe use single-dash -version
+  const checkArgs = (cmd === 'ffmpeg' || cmd === 'ffprobe') && args[0] === '--version'
+    ? ['-version']
+    : args;
+
+  const candidates = process.platform === 'win32' && !path.extname(cmd)
+    ? [cmd, `${cmd}.exe`, `${cmd}.cmd`, `${cmd}.bat`]
+    : [cmd];
+
+  for (const bin of candidates) {
+    try {
+      const res = spawnSync(bin, checkArgs, {
+        encoding: 'utf8',
+        timeout: 4000,
+        shell: false,
+      });
+      if (res.status === 0) return true;
+    } catch (_) {}
+  }
+  return false;
+}
+
+/**
+ * Run a package installation command synchronously with progress logging
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {string} toolName
+ * @returns {boolean}
+ */
+function runInstallCommand(cmd, args, toolName) {
+  console.log(`[ToolInstaller] 📦 Auto-installing missing dependency: ${toolName}...`);
+  try {
+    const res = spawnSync(cmd, args, {
+      stdio: 'inherit',
+      timeout: 180000, // 3 min cap
+      shell: false,
+    });
+    const ok = res.status === 0;
+    if (ok) {
+      console.log(`[ToolInstaller] ✔ Successfully installed ${toolName}`);
+    } else {
+      console.warn(`[ToolInstaller] ⚠️ Automatic install of ${toolName} exited with code ${res.status}`);
+    }
+    return ok;
+  } catch (err) {
+    console.warn(`[ToolInstaller] ⚠️ Failed to auto-install ${toolName}: ${err.message}`);
+    return false;
+  }
+}
+
+/**
+ * Ensure FFmpeg is installed. Auto-installs via system package managers if missing.
+ * @returns {boolean}
+ */
+function ensureFfmpeg() {
+  if (isCommandAvailable('ffmpeg')) return true;
+
+  console.log('[ToolInstaller] FFmpeg not found on PATH. Attempting automatic installation...');
+  if (process.platform === 'win32') {
+    if (isCommandAvailable('winget', ['--version'])) {
+      if (runInstallCommand('winget', ['install', '--id', 'Gyan.FFmpeg', '-e', '--silent', '--accept-package-agreements', '--accept-source-agreements'], 'FFmpeg (winget)')) {
+        return isCommandAvailable('ffmpeg');
+      }
+    }
+    if (isCommandAvailable('choco', ['--version'])) {
+      if (runInstallCommand('choco', ['install', 'ffmpeg', '-y'], 'FFmpeg (Chocolatey)')) {
+        return isCommandAvailable('ffmpeg');
+      }
+    }
+    if (isCommandAvailable('scoop', ['--version'])) {
+      if (runInstallCommand('scoop', ['install', 'ffmpeg'], 'FFmpeg (Scoop)')) {
+        return isCommandAvailable('ffmpeg');
+      }
+    }
+  } else if (process.platform === 'darwin') {
+    if (isCommandAvailable('brew', ['--version'])) {
+      if (runInstallCommand('brew', ['install', 'ffmpeg'], 'FFmpeg (Homebrew)')) {
+        return isCommandAvailable('ffmpeg');
+      }
+    }
+  } else if (process.platform === 'linux') {
+    if (isCommandAvailable('apt-get', ['--version'])) {
+      if (runInstallCommand('sudo', ['apt-get', 'install', '-y', 'ffmpeg'], 'FFmpeg (apt)')) {
+        return isCommandAvailable('ffmpeg');
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Ensure edge-tts is installed. Auto-installs via pip if missing.
+ * @returns {boolean}
+ */
+function ensureEdgeTts() {
+  if (isCommandAvailable('edge-tts')) return true;
+
+  console.log('[ToolInstaller] edge-tts CLI not found. Attempting auto-install...');
+  // Try python -m pip first, then bare pip
+  if (isCommandAvailable('python', ['-m', 'pip', '--version'])) {
+    if (runInstallCommand('python', ['-m', 'pip', 'install', '--quiet', 'edge-tts'], 'edge-tts')) {
+      return isCommandAvailable('edge-tts');
+    }
+  }
+  if (isCommandAvailable('pip', ['--version'])) {
+    if (runInstallCommand('pip', ['install', '--quiet', 'edge-tts'], 'edge-tts')) {
+      return isCommandAvailable('edge-tts');
+    }
+  }
+  return false;
+}
+
+/**
+ * Ensure yt-dlp is installed. Auto-installs via pip if missing.
+ * @returns {boolean}
+ */
+function ensureYtDlp() {
+  if (isCommandAvailable('yt-dlp')) return true;
+
+  console.log('[ToolInstaller] yt-dlp not found. Attempting auto-install...');
+  if (isCommandAvailable('python', ['-m', 'pip', '--version'])) {
+    if (runInstallCommand('python', ['-m', 'pip', 'install', '--quiet', 'yt-dlp'], 'yt-dlp')) {
+      return isCommandAvailable('yt-dlp');
+    }
+  }
+  if (isCommandAvailable('pip', ['--version'])) {
+    if (runInstallCommand('pip', ['install', '--quiet', 'yt-dlp'], 'yt-dlp')) {
+      return isCommandAvailable('yt-dlp');
+    }
+  }
+  return false;
+}
+
+/**
+ * Ensure whisper is installed. Auto-installs via pip if missing.
+ * @returns {boolean}
+ */
+function ensureWhisper() {
+  // Check if python has whisper module
+  const check = spawnSync('python', ['-c', 'import whisper; print("ok")'], {
+    encoding: 'utf8',
+    timeout: 4000,
+    shell: process.platform === 'win32',
+  });
+  if (check.status === 0 && (check.stdout || '').includes('ok')) return true;
+
+  console.log('[ToolInstaller] Whisper engine not found. Attempting auto-install (openai-whisper)...');
+  if (isCommandAvailable('python', ['-m', 'pip', '--version'])) {
+    if (runInstallCommand('python', ['-m', 'pip', 'install', '--quiet', 'openai-whisper'], 'openai-whisper')) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Ensure Playwright Chromium browser is installed.
+ * @returns {boolean}
+ */
+function ensurePlaywrightChromium() {
+  console.log('[ToolInstaller] Checking/installing Chromium browser for Playwright...');
+  return runInstallCommand('npx', ['playwright', 'install', 'chromium'], 'Chromium (Playwright)');
+}
+
+/**
+ * Auto-install all recommended dependencies at once
+ */
+function autoInstallAll() {
+  console.log('\n=== FrameForge Tool Provisioner ===\n');
+  const ffmpegOk = ensureFfmpeg();
+  const ttsOk    = ensureEdgeTts();
+  const ytdlpOk  = ensureYtDlp();
+  const crOk     = ensurePlaywrightChromium();
+  console.log(`\nResults: ffmpeg: ${ffmpegOk ? '✔' : '✖'}, edge-tts: ${ttsOk ? '✔' : '✖'}, yt-dlp: ${ytdlpOk ? '✔' : '✖'}, chromium: ${crOk ? '✔' : '✖'}\n`);
+  return { ffmpegOk, ttsOk, ytdlpOk, crOk };
+}
+
+module.exports = {
+  isCommandAvailable,
+  ensureFfmpeg,
+  ensureEdgeTts,
+  ensureYtDlp,
+  ensureWhisper,
+  ensurePlaywrightChromium,
+  autoInstallAll,
+};

package/src/utils/transcribe.js

@@ -204,7 +204,15 @@ async function transcribeAudio(mediaPath, opts = {}) {
     throw new Error(`Media file not found for transcription: ${mediaPath}`);
   }
 
-  const engine = detectWhisper();
+  let engine = detectWhisper();
+  if (!engine.available) {
+    try {
+      const { ensureWhisper } = require('./tool-installer');
+      if (ensureWhisper()) {
+        engine = detectWhisper();
+      }
+    } catch (_) {}
+  }
   const pauses = detectPausesWithFFmpeg(mediaPath);
   let parsed = { text: '', duration: 0, words: [], segments: [] };
   const isWin = process.platform === 'win32';

package/src/video-renderer/renderer.js

@@ -175,6 +175,7 @@ class VideoRenderer {
     colorGrade = null,
     showCaptions = false,
     showAnchor = false,
+    sfxCues = [],
   } = {}) {
     const effectiveShowCaptions = Boolean(
       showCaptions ||
@@ -200,7 +201,14 @@ class VideoRenderer {
     }
     const voiceDur   = this._getAudioDuration(voicePath);
     const dur        = (typeof duration === 'number' && duration > 0) ? Math.max(duration, voiceDur) : voiceDur;
-    const clampedDur = Math.max(1, Number.isFinite(dur) ? dur + 0.15 : 3.15);
+    // Hard cap: individual scenes should be 1–12s. Longer narration → more scenes, not longer frames.
+    // This prevents a single browser render job from blocking the pipeline for minutes.
+    const MAX_SCENE_DUR = 12;
+    const rawDur     = Number.isFinite(dur) ? dur + 0.15 : 3.15;
+    const clampedDur = Math.min(MAX_SCENE_DUR, Math.max(1, rawDur));
+    if (rawDur > MAX_SCENE_DUR) {
+      console.warn(`[Renderer] Scene ${sceneIndex}: narration duration ${rawDur.toFixed(2)}s exceeds max ${MAX_SCENE_DUR}s. Clamped. Consider splitting long narration into shorter scenes.`);
+    }
 
     const isVideoInput = Boolean(videoPath) || (videoPath && /\.(mp4|mov|webm|mkv|m4v)$/i.test(videoPath));
 
@@ -303,14 +311,17 @@ class VideoRenderer {
           manifest,
           musicMood,
           showCaptions: effectiveShowCaptions,
+          showAnchor: effectiveShowAnchor,
+          sfxCues,
         });
       } catch (err) {
-        console.warn(`[Renderer] Code-driven browser scene render failed (${err.message}), falling back to procedural animation`);
+        console.warn(`[Renderer] Code-driven browser scene render failed (${err.message}):`, err.stack || err);
       }
     }
 
-    // Priority 3: Procedural dynamic animated fallback (dynamic moving gradients / camera drift)
-    const captionFilter = effectiveShowCaptions ? this._captionFilter(caption) : '';
+    // Priority 3: Procedural dynamic animated fallback (subtle gradient / camera drift)
+    const fallbackText = caption || title || topic || '';
+    const captionFilter = effectiveShowCaptions ? this._captionFilter(caption) : (fallbackText ? this._captionFilter(fallbackText) : '');
     let inputArgs = [];
     let vf = '';
 
@@ -327,10 +338,10 @@ class VideoRenderer {
       const c0 = (pal.bg0 || '#0d1117').replace('#', '');
       const c1 = (pal.accent || '#38bdf8').replace('#', '');
       inputArgs = [
-        '-f', 'lavfi', '-i', `gradients=s=${renderWidth}x${renderHeight}:r=30:c0=0x${c0}:c1=0x${c1}:speed=0.5:type=radial`,
+        '-f', 'lavfi', '-i', `gradients=s=${renderWidth}x${renderHeight}:r=${fps}:c0=0x${c0}:c1=0x${c1}:speed=0.01:type=linear`,
         '-i', voicePath,
       ];
-      const vfFilters = ['vignette=PI/4'];
+      const vfFilters = [];
       if (captionFilter) vfFilters.push(captionFilter);
       vf = vfFilters.join(',');
     }
@@ -389,6 +400,8 @@ class VideoRenderer {
     manifest,
     musicMood,
     showCaptions = false,
+    showAnchor = false,
+    sfxCues = [],
   }) {
     let htmlContent;
     if (html && typeof html === 'string' && html.trim().length > 0) {
@@ -424,8 +437,8 @@ class VideoRenderer {
         height: renderHeight,
         sceneIndex,
         musicMood,
-        showCaptions: effectiveShowCaptions,
-        showAnchor: effectiveShowAnchor,
+        showCaptions,
+        showAnchor,
         camera: effectiveCam,
         cameraHint: effectiveCam,
       });
@@ -443,12 +456,14 @@ class VideoRenderer {
     const res = spawnSync(process.execPath, [
       harnessBin,
       'frames',
-      '--html', animHtmlPath,
-      '--out', framesDir,
-      '--fps', String(fps),
-      '--first', '0',
-      '--last', String(lastFrame),
-      '--workers', '4',
+      '--html',    animHtmlPath,
+      '--out',     framesDir,
+      '--fps',     String(fps),
+      '--first',   '0',
+      '--last',    String(lastFrame),
+      '--workers', '2',
+      '--width',   String(renderWidth),
+      '--height',  String(renderHeight),
     ], { encoding: 'utf8', timeout: 5 * 60 * 1000 });
 
     if (res.status !== 0) {
@@ -468,36 +483,51 @@ class VideoRenderer {
       }
     } catch (_) {}
 
+    // Mix SFX into voice track before encode (earshot perceptual lead contract)
+    let audioForEncode = voicePath;
+    if (Array.isArray(sfxCues) && sfxCues.length > 0) {
+      const sfxMixedPath = path.join(this.vdir, `scene_${sceneIndex}_voice_sfx.m4a`);
+      try {
+        this.mixer.mixSfxIntoAudio(voicePath, sfxCues, sfxMixedPath);
+        audioForEncode = sfxMixedPath;
+        console.log(`[Renderer] 🔊 Scene ${sceneIndex}: mixed ${sfxCues.length} SFX cue(s) into audio`);
+      } catch (sfxErr) {
+        console.warn(`[Renderer] SFX mix failed for scene ${sceneIndex} (using plain voice): ${sfxErr.message}`);
+      }
+    }
+
     const framesPattern = path.join(framesDir, 'f%06d.jpg');
-    const encResult = spawnSync('ffmpeg', [
-      '-nostdin', '-y', '-threads', '2',
-      '-framerate', String(fps),
-      '-pattern_type', 'sequence',
-      '-i', framesPattern,
-      '-i', voicePath,
-      '-map', '0:v:0', '-map', '1:a:0',
-      '-c:v', 'libx264', '-preset', 'fast', '-crf', '17',
-      '-profile:v', 'high', '-level', '4.1',
-      '-color_range', 'tv', '-colorspace', 'bt709',
-      '-color_primaries', 'bt709', '-color_trc', 'bt709',
-      '-x264-params', 'colorprim=bt709:transfer=bt709:colormatrix=bt709:aq-mode=3:deblock=-1,-1',
-      '-pix_fmt', 'yuv420p',
-      '-c:a', 'aac', '-b:a', '320k', '-ar', '48000', '-ac', '2',
-      '-af', `apad=whole_dur=${clampedDur}`,
-      '-t', String(clampedDur),
-      '-movflags', '+faststart',
-      outputPath,
-    ], { timeout: 5 * 60 * 1000, encoding: 'utf8' });
+    let encResult;
+    try {
+      encResult = spawnSync('ffmpeg', [
+        '-nostdin', '-y', '-threads', '2',
+        '-framerate', String(fps),
+        '-pattern_type', 'sequence',
+        '-i', framesPattern,
+        '-i', audioForEncode,
+        '-map', '0:v:0', '-map', '1:a:0',
+        '-c:v', 'libx264', '-preset', 'fast', '-crf', '17',
+        '-profile:v', 'high', '-level', '4.1',
+        '-color_range', 'tv', '-colorspace', 'bt709',
+        '-color_primaries', 'bt709', '-color_trc', 'bt709',
+        '-x264-params', 'colorprim=bt709:transfer=bt709:colormatrix=bt709:aq-mode=3:deblock=-1,-1',
+        '-pix_fmt', 'yuv420p',
+        '-c:a', 'aac', '-b:a', '320k', '-ar', '48000', '-ac', '2',
+        '-af', `apad=whole_dur=${clampedDur}`,
+        '-t', String(clampedDur),
+        '-movflags', '+faststart',
+        outputPath,
+      ], { timeout: 5 * 60 * 1000, encoding: 'utf8' });
+    } finally {
+      // Always clean up frames and html — even if encode fails — to avoid accumulating GBs on disk
+      try { fs.rmSync(framesDir, { recursive: true, force: true }); } catch (_) {}
+      try { fs.unlinkSync(animHtmlPath); } catch (_) {}
+    }
 
     if (encResult.status !== 0) {
       throw new Error(`Scene ${sceneIndex} video encode failed: ${(encResult.stderr || '').slice(-300)}`);
     }
 
-    try {
-      fs.rmSync(framesDir, { recursive: true, force: true });
-      fs.unlinkSync(animHtmlPath);
-    } catch (_) {}
-
     manifest?.setSceneRendered(sceneIndex, outputPath);
     return outputPath;
   }