@amg555/frameforge-mcp 2.3.2 → 2.3.4

package/scripts/html-renderer/transcribe.py

@@ -0,0 +1,294 @@
+#!/usr/bin/env python3
+"""
+transcribe.py — Generate a Whisper-format caption outline from FrameForge TTS audio.
+
+Reads all voice_*.m4a (or voice_*.mp3) files from the project's audio/ directory,
+transcribes each with OpenAI Whisper (if installed) or falls back to silence-based
+segmentation via ffmpeg, and writes audio/outline.txt.
+
+audio/outline.txt format (tab-separated, one word-group per line):
+  <start_seconds>\t<end_seconds>\t<text>
+
+This file is consumed by captions() in reel/engine.js:
+  captions('audio/outline.txt');
+
+Usage:
+  # From inside a scaffolded html-renderer project:
+  uv run scripts/transcribe.py
+
+  # Or with an explicit audio directory:
+  uv run scripts/transcribe.py --audio-dir /path/to/audio/
+
+  # Or without uv (python ≥ 3.9 required):
+  python scripts/transcribe.py
+
+Requirements (Whisper path — highest quality):
+  pip install openai-whisper
+  # or: uv add openai-whisper
+
+Requirements (ffmpeg fallback — no ML dependency):
+  ffmpeg must be on PATH
+
+Environment:
+  WHISPER_MODEL   Model size: tiny | base | small | medium | large (default: base)
+  AUDIO_DIR       Override audio directory (default: audio/)
+  OUTLINE_PATH    Override output path (default: audio/outline.txt)
+"""
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+
+# ── Configuration ──────────────────────────────────────────────────────────────
+
+DEFAULT_AUDIO_DIR  = "audio"
+DEFAULT_OUTLINE    = "audio/outline.txt"
+WHISPER_MODEL      = os.environ.get("WHISPER_MODEL", "base")
+WORDS_PER_GROUP    = 6    # words per caption line (for ffmpeg fallback)
+SILENCE_THRESHOLD  = -35  # dB (for ffmpeg silence detection fallback)
+SILENCE_DURATION   = 0.3  # seconds
+
+
+# ── Helpers ────────────────────────────────────────────────────────────────────
+
+def find_audio_files(audio_dir: Path) -> list[Path]:
+    """Return all voice_*.m4a / voice_*.mp3 files sorted by scene index."""
+    files = sorted(
+        [p for p in audio_dir.iterdir() if re.match(r"voice_\d+\.(m4a|mp3)", p.name)],
+        key=lambda p: int(re.search(r"voice_(\d+)", p.name).group(1)),
+    )
+    if not files:
+        # Also accept any .m4a/.mp3 in the directory
+        files = sorted(
+            [p for p in audio_dir.iterdir() if p.suffix in (".m4a", ".mp3")],
+            key=lambda p: p.name,
+        )
+    return files
+
+
+def get_audio_duration(path: Path) -> float:
+    """Return duration in seconds using ffprobe."""
+    result = subprocess.run(
+        ["ffprobe", "-v", "quiet", "-print_format", "json", "-show_streams", str(path)],
+        capture_output=True, text=True, timeout=30,
+    )
+    if result.returncode != 0:
+        return 5.0  # fallback estimate
+    data = json.loads(result.stdout)
+    for stream in data.get("streams", []):
+        if "duration" in stream:
+            return float(stream["duration"])
+    return 5.0
+
+
+def convert_to_wav(src: Path, dst: Path) -> None:
+    """Convert audio to 16kHz mono WAV for Whisper."""
+    subprocess.run(
+        ["ffmpeg", "-y", "-i", str(src), "-ar", "16000", "-ac", "1", str(dst)],
+        capture_output=True, check=True, timeout=120,
+    )
+
+
+# ── Whisper transcription ──────────────────────────────────────────────────────
+
+def transcribe_whisper(audio_file: Path, time_offset: float) -> list[tuple[float, float, str]]:
+    """
+    Transcribe one audio file with Whisper.
+    Returns list of (start, end, text) tuples with absolute timestamps.
+    """
+    import whisper  # type: ignore
+
+    model = whisper.load_model(WHISPER_MODEL)
+
+    with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as tmp:
+        wav_path = Path(tmp.name)
+
+    try:
+        convert_to_wav(audio_file, wav_path)
+        result = model.transcribe(str(wav_path), word_timestamps=True, language=None)
+    finally:
+        wav_path.unlink(missing_ok=True)
+
+    segments = []
+    for seg in result.get("segments", []):
+        start = seg["start"] + time_offset
+        end   = seg["end"]   + time_offset
+        text  = seg["text"].strip()
+        if text:
+            segments.append((start, end, text))
+
+    return segments
+
+
+# ── FFmpeg silence-based fallback ──────────────────────────────────────────────
+
+def transcribe_ffmpeg_fallback(audio_file: Path, time_offset: float, narration: str | None = None) -> list[tuple[float, float, str]]:
+    """
+    Fallback when Whisper is not installed.
+    Uses ffmpeg silence detection to estimate word timings, then distributes
+    the narration text evenly across the detected speech segments.
+    Falls back to even word distribution if narration is unavailable.
+    """
+    duration = get_audio_duration(audio_file)
+
+    # Detect silence boundaries
+    result = subprocess.run(
+        [
+            "ffmpeg", "-i", str(audio_file),
+            "-af", f"silencedetect=noise={SILENCE_THRESHOLD}dB:d={SILENCE_DURATION}",
+            "-f", "null", "-",
+        ],
+        capture_output=True, text=True, timeout=60,
+    )
+    stderr = result.stderr
+
+    # Parse silence_start / silence_end pairs
+    starts = [float(m) for m in re.findall(r"silence_start: ([\d.]+)", stderr)]
+    ends   = [float(m) for m in re.findall(r"silence_end: ([\d.]+)", stderr)]
+
+    # Build speech segments from silence gaps
+    speech_segments: list[tuple[float, float]] = []
+    cursor = 0.0
+    for s, e in zip(starts, ends):
+        if s > cursor + 0.1:
+            speech_segments.append((cursor, s))
+        cursor = e
+    if cursor < duration - 0.1:
+        speech_segments.append((cursor, duration))
+
+    if not speech_segments:
+        speech_segments = [(0.0, duration)]
+
+    # Distribute narration text across speech segments
+    words = (narration or "").split() if narration else []
+    if not words:
+        # No narration — emit one entry per speech segment with placeholder
+        return [
+            (seg[0] + time_offset, seg[1] + time_offset, f"[scene {i+1}]")
+            for i, seg in enumerate(speech_segments)
+        ]
+
+    total_seg_dur = sum(e - s for s, e in speech_segments)
+    captions: list[tuple[float, float, str]] = []
+    word_idx = 0
+
+    for seg_start, seg_end in speech_segments:
+        seg_dur = seg_end - seg_start
+        seg_word_count = max(1, round(len(words) * (seg_dur / total_seg_dur)))
+        seg_words = words[word_idx : word_idx + seg_word_count]
+        word_idx += seg_word_count
+
+        # Split segment words into groups of WORDS_PER_GROUP
+        for i in range(0, len(seg_words), WORDS_PER_GROUP):
+            group = seg_words[i : i + WORDS_PER_GROUP]
+            frac_start = i / len(seg_words)
+            frac_end   = min(1.0, (i + WORDS_PER_GROUP) / len(seg_words))
+            t_start = seg_start + frac_start * seg_dur + time_offset
+            t_end   = seg_start + frac_end   * seg_dur + time_offset
+            captions.append((t_start, t_end, " ".join(group)))
+
+    # Append any remaining words to the last segment
+    if word_idx < len(words):
+        last = captions[-1] if captions else (time_offset, time_offset + duration, "")
+        captions.append((last[1], last[1] + 1.0, " ".join(words[word_idx:])))
+
+    return captions
+
+
+# ── Main ───────────────────────────────────────────────────────────────────────
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Generate caption outline from FrameForge TTS audio.")
+    parser.add_argument("--audio-dir",  default=os.environ.get("AUDIO_DIR", DEFAULT_AUDIO_DIR),
+                        help="Directory containing voice_*.m4a files (default: audio/)")
+    parser.add_argument("--outline",    default=os.environ.get("OUTLINE_PATH", DEFAULT_OUTLINE),
+                        help="Output path for outline.txt (default: audio/outline.txt)")
+    parser.add_argument("--script",     default=None,
+                        help="Optional: path to FrameForge script JSON for narration text (improves ffmpeg fallback)")
+    parser.add_argument("--no-whisper", action="store_true",
+                        help="Force ffmpeg fallback even if Whisper is installed")
+    args = parser.parse_args()
+
+    audio_dir   = Path(args.audio_dir)
+    outline_path = Path(args.outline)
+
+    if not audio_dir.exists():
+        print(f"[transcribe] ERROR: audio directory not found: {audio_dir}", file=sys.stderr)
+        print(f"  Copy FrameForge TTS outputs (voice_0.m4a, voice_1.m4a …) into {audio_dir}/", file=sys.stderr)
+        sys.exit(1)
+
+    audio_files = find_audio_files(audio_dir)
+    if not audio_files:
+        print(f"[transcribe] ERROR: no voice_*.m4a or voice_*.mp3 files found in {audio_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"[transcribe] Found {len(audio_files)} audio file(s) in {audio_dir}")
+
+    # Load narration text from script JSON if provided (for ffmpeg fallback)
+    narrations: list[str | None] = [None] * len(audio_files)
+    if args.script:
+        try:
+            raw = json.loads(Path(args.script).read_text())
+            script = raw.get("script", raw)
+            scenes = script.get("scenes", [])
+            for i, scene in enumerate(scenes):
+                if i < len(narrations):
+                    narrations[i] = scene.get("narration")
+            print(f"[transcribe] Loaded {len(scenes)} narration(s) from {args.script}")
+        except Exception as exc:
+            print(f"[transcribe] WARNING: could not load script JSON: {exc}", file=sys.stderr)
+
+    # Choose transcription backend
+    use_whisper = False
+    if not args.no_whisper:
+        try:
+            import whisper  # type: ignore  # noqa: F401
+            use_whisper = True
+            print(f"[transcribe] Using Whisper model '{WHISPER_MODEL}'")
+        except ImportError:
+            print("[transcribe] Whisper not installed — using ffmpeg silence-detection fallback.")
+            print("             Install for better accuracy: pip install openai-whisper")
+
+    # Transcribe each file and accumulate captions with absolute timestamps
+    all_captions: list[tuple[float, float, str]] = []
+    time_offset = 0.0
+
+    for i, audio_file in enumerate(audio_files):
+        print(f"[transcribe]   {audio_file.name} …", end=" ", flush=True)
+        try:
+            if use_whisper:
+                segments = transcribe_whisper(audio_file, time_offset)
+            else:
+                segments = transcribe_ffmpeg_fallback(audio_file, time_offset, narrations[i])
+            all_captions.extend(segments)
+            duration = get_audio_duration(audio_file)
+            time_offset += duration
+            print(f"{len(segments)} segment(s), duration {duration:.1f}s")
+        except Exception as exc:
+            duration = get_audio_duration(audio_file)
+            time_offset += duration
+            print(f"ERROR: {exc}", file=sys.stderr)
+
+    if not all_captions:
+        print("[transcribe] ERROR: no captions generated.", file=sys.stderr)
+        sys.exit(1)
+
+    # Write outline.txt
+    outline_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(outline_path, "w", encoding="utf-8") as fh:
+        for start, end, text in all_captions:
+            fh.write(f"{start:.3f}\t{end:.3f}\t{text}\n")
+
+    print(f"[transcribe] Written {len(all_captions)} caption(s) → {outline_path}")
+    print(f"[transcribe] Total duration: {time_offset:.1f}s")
+    print(f"[transcribe] Use in edit.js:  captions('{outline_path}')")
+
+
+if __name__ == "__main__":
+    main()

package/src/asset-library/README.md

@@ -148,7 +148,7 @@ Single character only.
 1920x1080 landscape.
 `;
 
-const imageUrl = await pollinations.generate({
+const imageUrl = await generateAssetVisual({
   prompt,
   width: 1920,
   height: 1080,
@@ -179,7 +179,7 @@ All assets track `schema_version: "1.0.0"` for evolution:
 - **Metadata lookup:** <10ms (PostgreSQL indexed)
 - **Semantic search:** <200ms (cached embeddings)
 - **Asset composition:** <500ms (image layering)
-- **Asset generation:** 5-15s (Pollinations API)
+- **Asset generation:** <100ms (code-driven / local procedural)
 
 ## Storage
 

package/src/asset-library/asset-library.js

@@ -7,7 +7,7 @@
  * Architecture:
  * - Metadata filtering (primary): Fast PostgreSQL lookup
  * - Semantic search (fallback): Embedding similarity if no metadata match
- * - Generation: Pollinations API with style consistency
+ * - Generation: Procedural SVG / local visual composition
  */
 
 const fs     = require('fs').promises;

package/src/cli/doctor.js

@@ -73,19 +73,26 @@ if (ffprobe.status === 0) {
   hasCriticalFailure = true;
 }
 
-// 4. Voice Engine (edge-tts or Cloud API)
+// 4. Voice Engine (edge-tts, VoxForge, or Cloud API)
 const edgeTts = spawnSync('edge-tts', ['--version'], { encoding: 'utf8', timeout: 5000, shell: process.platform === 'win32' });
-const hasCloudTts = Boolean(process.env.ELEVENLABS_API_KEY || process.env.AZURE_SPEECH_KEY || process.env.OPENAI_API_KEY || process.env.CUSTOM_TTS_URL);
+const hasCloudTts = Boolean(
+  process.env.ELEVENLABS_API_KEY ||
+  process.env.AZURE_SPEECH_KEY ||
+  process.env.OPENAI_API_KEY ||
+  process.env.CUSTOM_TTS_URL ||
+  process.env.WEBHOOK_TTS_URL ||
+  process.env.VOXFORGE_URL
+);
 
 if (edgeTts.status === 0) {
   pass('Voice Engine', `edge-tts CLI available (${(edgeTts.stdout || '').trim()})`);
 } else if (hasCloudTts) {
-  pass('Voice Engine', 'Cloud TTS API configured via environment');
+  pass('Voice Engine', 'TTS provider (VoxForge or Cloud API) configured via environment');
 } else {
   warn(
     'Voice Engine',
-    'Neither edge-tts CLI nor cloud TTS API detected',
-    'Run "pip install edge-tts" for free offline voiceover, or set OPENAI_API_KEY / ELEVENLABS_API_KEY in .env'
+    'Neither edge-tts CLI nor configured TTS provider detected',
+    'Run "pip install edge-tts" for free offline voiceover, set VOXFORGE_URL (VoxForge), or set OPENAI_API_KEY / ELEVENLABS_API_KEY in .env'
   );
 }
 

package/src/cli/make.js

@@ -36,7 +36,8 @@
  *   --channels      <list>   file,webhook  (default: file)
  *   --no-research            Skip research stage (use --topic as raw facts)
  *   --no-script              Skip script stage (requires --scenes-file)
- *   --no-images              Skip AI image generation (use video/image_path in scenes)
+ *   --no-images              Skip AI image generation (use code-driven animation or user clips)
+ *   --ai-images              Opt-in: generate AI diffusion images (default: code animation)
  *   --no-tts                 Skip TTS synthesis (use audio_path in scenes)
  *   --no-shorts              Skip Shorts extraction
  *   --no-publish             Skip publishing (render only)
@@ -84,6 +85,14 @@ const LANGUAGE_VOICES = {
 
 // ── Argument parsing ──────────────────────────────────────────────────────────
 
+// Dispatch to code-driven animation harness if invoked as `frameforge harness ...`
+if (process.argv[2] === 'harness') {
+  const harnessBin = path.resolve(__dirname, '../harness/bin/harness.mjs');
+  const { spawnSync } = require('child_process');
+  const res = spawnSync(process.execPath, [harnessBin, ...process.argv.slice(3)], { stdio: 'inherit' });
+  process.exit(res.status ?? 0);
+}
+
 function parseArgs(argv) {
   const args = {
     mode: 'full-auto',
@@ -108,6 +117,7 @@ function parseArgs(argv) {
       case '--no-research':   args.noResearch  = true; break;
       case '--no-script':     args.noScript    = true; break;
       case '--no-images':     args.noImages    = true; break;
+      case '--ai-images':     args.aiImages    = true; break;
       case '--no-tts':        args.noTts       = true; break;
       case '--no-shorts':     args.shorts      = false; break;
       case '--no-publish':    args.noPublish   = true; break;
@@ -225,84 +235,48 @@ function logSection(title) {
 }
 
 // ── Thumbnail generator ───────────────────────────────────────────────────────
-// Downloads a Pollinations image for the thumbnail prompt and optionally
-// overlays the video title with FFmpeg drawtext. Saves to <outDir>/thumbnail.jpg.
-// Non-fatal: failures are logged as warnings, not errors.
+// Generates a crisp code-driven procedural thumbnail with FFmpeg.
+// Saves to <outDir>/thumbnail.jpg. Non-fatal: failures are logged as warnings.
 
 async function generateThumbnail({ thumbnailPrompt, title, outDir }) {
-  if (!thumbnailPrompt) return null;
+  if (!thumbnailPrompt && !title) return null;
   const outputPath = path.join(outDir, 'thumbnail.jpg');
   try {
-    const model   = process.env.POLLINATIONS_MODEL || 'flux';
-    const prompt  = encodeURIComponent(thumbnailPrompt.slice(0, 500));
-    const imgUrl  = `https://image.pollinations.ai/prompt/${prompt}?width=1280&height=720&model=${model}&nologo=true`;
-    // Download image
-    const imgPath = path.join(outDir, 'thumbnail_raw.jpg');
-    await _downloadFile(imgUrl, imgPath);
-    if (!fs.existsSync(imgPath)) return null;
-
-    // Optionally burn title text with FFmpeg
     const { spawnSync } = require('child_process');
-    if (title) {
-      // Resolve a usable font (same logic as renderer.js)
-      const fontCandidates = process.platform === 'win32'
-        ? ['C:/Windows/Fonts/arialbd.ttf', 'C:/Windows/Fonts/calibrib.ttf', 'C:/Windows/Fonts/segoeui.ttf']
-        : process.platform === 'darwin'
-          ? ['/System/Library/Fonts/Helvetica.ttc', '/Library/Fonts/Arial Bold.ttf']
-          : ['/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf', '/usr/share/fonts/truetype/freefont/FreeSansBold.ttf'];
-      const font = process.env.FFMPEG_FONT
-        || fontCandidates.find(f => fs.existsSync(f))
-        || '';
-
-      if (font) {
-        const safeTitle = title.replace(/['":\\]/g, ' ').slice(0, 80);
-        const result = spawnSync('ffmpeg', [
-          '-y', '-i', imgPath,
-          '-vf', `drawtext=fontfile='${font}':text='${safeTitle}':fontcolor=white:fontsize=52:x=(w-text_w)/2:y=h-120:shadowx=3:shadowy=3:shadowcolor=black`,
-          '-q:v', '3',
-          outputPath,
-        ], { encoding: 'utf8' });
-        if (result.status === 0) {
-          fs.unlinkSync(imgPath); // remove raw
-          return outputPath;
-        }
-      }
-      // FFmpeg unavailable or failed — just rename the raw image
-      fs.renameSync(imgPath, outputPath);
-    } else {
-      fs.renameSync(imgPath, outputPath);
+    const safeTitle = (title || 'FrameForge Video').replace(/['":\\]/g, ' ').slice(0, 80);
+    const fontCandidates = process.platform === 'win32'
+      ? ['C:/Windows/Fonts/arialbd.ttf', 'C:/Windows/Fonts/calibrib.ttf', 'C:/Windows/Fonts/segoeui.ttf']
+      : process.platform === 'darwin'
+        ? ['/System/Library/Fonts/Helvetica.ttc', '/Library/Fonts/Arial Bold.ttf']
+        : ['/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf', '/usr/share/fonts/truetype/freefont/FreeSansBold.ttf'];
+    const font = process.env.FFMPEG_FONT
+      || fontCandidates.find(f => fs.existsSync(f))
+      || '';
+
+    const drawFilter = font
+      ? `drawtext=fontfile='${font}':text='${safeTitle}':fontcolor=white:fontsize=56:x=(w-text_w)/2:y=(h-text_h)/2:shadowx=3:shadowy=3:shadowcolor=black`
+      : `drawtext=text='${safeTitle}':fontcolor=white:fontsize=56:x=(w-text_w)/2:y=(h-text_h)/2:shadowx=3:shadowy=3:shadowcolor=black`;
+
+    const result = spawnSync('ffmpeg', [
+      '-y',
+      '-f', 'lavfi',
+      '-i', 'color=c=0x0f172a:s=1280x720:d=1',
+      '-vf', drawFilter,
+      '-frames:v', '1',
+      '-q:v', '3',
+      outputPath,
+    ], { encoding: 'utf8' });
+
+    if (result.status === 0 && fs.existsSync(outputPath)) {
+      return outputPath;
     }
-    return outputPath;
+    return null;
   } catch (err) {
     log('Thumbnail', `⚠️  Thumbnail generation failed (non-fatal): ${err.message}`);
     return null;
   }
 }
 
-function _downloadFile(url, destPath) {
-  return new Promise((resolve, reject) => {
-    const client = url.startsWith('https') ? https : http;
-    const file   = fs.createWriteStream(destPath);
-    function follow(u, hops) {
-      if (hops > 5) return reject(new Error('Too many redirects'));
-      client.get(u, (res) => {
-        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-          res.resume();
-          return follow(res.headers.location, hops + 1);
-        }
-        if (res.statusCode !== 200) {
-          res.resume();
-          return reject(new Error(`HTTP ${res.statusCode} downloading ${u}`));
-        }
-        res.pipe(file);
-        file.on('finish', () => file.close(resolve));
-        file.on('error', reject);
-      }).on('error', reject);
-    }
-    follow(url, 0);
-  });
-}
-
 // ── Single video runner (used by both single-topic and batch modes) ───────────
 
 async function runSingleVideo(args, topic, outDir, workflows) {
@@ -414,12 +388,18 @@ async function runSingleVideo(args, topic, outDir, workflows) {
   // ── Stage C: Assets (images + TTS) ────────────────────────────────────────
   logSection('Stage C: Assets (images + TTS)');
 
+  // Code-driven first: AI diffusion images are disabled by default to eliminate AI artifacts.
+  const enableAiImages = Boolean(args.aiImages || process.env.ENABLE_AI_IMAGES === 'true');
+  const skipImages = args.noImages !== undefined ? args.noImages : !enableAiImages;
+
+  if (!enableAiImages) {
+    log('Assets', 'ℹ️   Code-driven animation: kinetic typography & user media (diffusion disabled)');
+  }
+
   // Pass stage-skip flags into scenes so runAssets can honour them
   const preparedScenes = scenes.map(s => ({
     ...s,
-    // --no-images: mark scene as if it has a placeholder image path → renderer skips generation
-    _skipImageGen: args.noImages,
-    // --no-tts: mark scene as if it has pre-recorded audio → renderer skips TTS
+    _skipImageGen: skipImages,
     _skipTts:      args.noTts,
   }));
 
@@ -427,8 +407,9 @@ async function runSingleVideo(args, topic, outDir, workflows) {
     productionId,
     scenes:       preparedScenes,
     parallelism:  4,
-    skipImages:   args.noImages,
+    skipImages,
     skipTts:      args.noTts,
+    enableAiImages,
   });
   log('Assets', `✅  ${assetsResult.sceneCount} scenes prepared`);
 

package/src/cli/setup-keys.js

@@ -31,12 +31,9 @@
  *     openai     — OpenAI TTS. Uses OPENAI_API_KEY.
  *     webhook    — Any TTS endpoint. Set WEBHOOK_TTS_URL.
  *
- *   Image (scene visuals):
- *     pollinations — Free, no key. Best default.
- *     falai        — High quality, fast. Get key: fal.ai
- *     replicate    — FLUX models. Get key: replicate.com
- *     dalle        — DALL-E 3. Uses OPENAI_API_KEY.
- *     webhook      — Any image endpoint. Set WEBHOOK_IMAGE_URL.
+ *   Visuals & Media:
+ *     code-driven — Default. Crisp kinetic typography and cards. 0 keys needed.
+ *     user-media  — Directly supply image_path or video_path per scene.
  */
 
 'use strict';
@@ -128,7 +125,7 @@ function checkEnv(envPath) {
     { key: 'PROVIDER_TTS',   label: 'TTS provider',    optional: false },
     { key: 'ELEVENLABS_API_KEY', label: 'ElevenLabs key', optional: true, needs: env.PROVIDER_TTS === 'elevenlabs' },
     { key: 'AZURE_SPEECH_KEY',   label: 'Azure key',      optional: true, needs: env.PROVIDER_TTS === 'azure' },
-    { key: 'PROVIDER_IMAGE', label: 'Image provider',  optional: false },
+    { key: 'PROVIDER_IMAGE', label: 'Image provider',  optional: true },
     { key: 'FALAI_API_KEY',  label: 'fal.ai key',      optional: true,  needs: env.PROVIDER_IMAGE === 'falai' },
     { key: 'REPLICATE_API_KEY', label: 'Replicate key', optional: true, needs: env.PROVIDER_IMAGE === 'replicate' },
     { key: 'PUBLISH_WEBHOOK_URL', label: 'Publish webhook URL', optional: true },
@@ -175,7 +172,7 @@ Press Enter to accept a default. Ctrl+C to cancel.
   ✅  No keys are required to make videos.
       Your IDE writes the scenes — FrameForge uses free providers by default:
         • edge-tts  — free voice (no account)
-        • pollinations — free images (no account)
+        • code-driven animation — free motion graphics (no account, zero keys)
         • FFmpeg — free local render (already on your machine)
 
       You only need keys for the auto-research pipeline (FrameForge writes the
@@ -240,8 +237,8 @@ Press Enter to accept a default. Ctrl+C to cancel.
 
   cfg.PROVIDER_TTS = await menu('Choose TTS provider', [
     ['edge-tts',   'edge-tts — free, offline, 400+ voices. No key needed.'],
-    ['voxforge',   'VoxForge — custom voice cloning (github.com/amg555/voxforge). Get key: your VoxForge instance.'],
     ['elevenlabs', 'ElevenLabs — best quality + voice cloning. elevenlabs.io'],
+    ['voxforge',   'VoxForge — self-hosted voice cloning. github.com/amg555/voxforge'],
     ['azure',      'Azure Cognitive Speech. portal.azure.com'],
     ['openai',     'OpenAI TTS (uses OPENAI_API_KEY above)'],
     ['webhook',    'Custom/any OpenAI-compatible TTS endpoint'],
@@ -267,18 +264,19 @@ Press Enter to accept a default. Ctrl+C to cancel.
   }
 
   // ── Image ─────────────────────────────────────────────────────────────────
-  section('3 / 5  —  Image Generation Provider');
-  console.log('  Used for: generating AI visuals for each scene.');
-  console.log('  Skip this if you supply your own images (--no-images).');
-  console.log('  Free option: Pollinations (no key needed).\n');
+  section('3 / 5  —  Visuals & Image Provider (optional)');
+  console.log('  Default: Code-driven animations, kinetic typography, and user-provided media.');
+  console.log('  Zero keys needed for high quality vector animation.');
+  console.log('  Select a diffusion provider only if you explicitly want AI-generated pictures.\n');
 
   cfg.PROVIDER_IMAGE = await menu('Choose image provider', [
-    ['pollinations', 'Pollinations — free, no key, FLUX model. Best default.'],
-    ['falai',        'fal.ai — high quality, fast. Get key: fal.ai'],
+    ['none',         'None (Recommended) — code-driven animations & user media. Zero keys, best quality.'],
+    ['pollinations', 'Pollinations — free AI images (no key needed, FLUX model)'],
+    ['falai',        'fal.ai — fast cloud diffusion. Get key: fal.ai'],
     ['replicate',    'Replicate FLUX-schnell. Get key: replicate.com'],
-    ['dalle',        'DALL-E 3 (uses OPENAI_API_KEY above)'],
+    ['dalle',        'DALL-E 3 (uses OPENAI_API_KEY)'],
     ['webhook',      'Custom/external image API endpoint'],
-  ], 'pollinations');
+  ], 'none');
 
   if (cfg.PROVIDER_IMAGE === 'falai') {
     cfg.FALAI_API_KEY = await askSecret('  fal.ai API key');

package/src/fact-checker/review-gate.js

@@ -49,7 +49,11 @@ class FactCheckerReviewGate {
     this.stateMachine = stateMachine;
     this.notifyUrl    = notifyUrl || process.env.REVIEW_NOTIFY_URL || '';
     this.reviewsDir   = reviewsDir;
-    fs.mkdirSync(reviewsDir, { recursive: true });
+    try {
+      fs.mkdirSync(reviewsDir, { recursive: true });
+    } catch {
+      // Best-effort in restricted/sandbox environments
+    }
   }
 
   // ── Gate evaluation ───────────────────────────────────────────────────────