@amg555/frameforge-mcp 2.4.3 → 2.4.5

package/CHANGELOG.md

@@ -4,6 +4,62 @@ All notable changes to FrameForge are documented here.
 
 ---
 
+## [2.4.5] — 2026-11-10
+
+### Fixed
+- **Browser Code Animation Dispatch in `src/video-renderer/renderer.js`**:
+  - Fixed `ReferenceError: camera is not defined` inside `_renderCodeAnimationScene`. Previously, missing parameter destructuring caused the browser animation engine to throw on every scene, silently falling back to static FFmpeg image slideshows.
+  - Added full pass-through of `camera`, `visualType`, and `focalPoint` into `_renderCodeAnimationScene`.
+- **Manifest Ingest Preservation (`src/workflows/ingest.js`, `src/workflows/assets.js`)**:
+  - `normaliseIngestScene` now retains `prompt`, `style`, and `theme`, and falls back to `raw.prompt` for `visual_description`.
+  - Added `--theme` and `--aesthetic` CLI options to `src/cli/make.js`.
+
+### Enhanced
+- **Audio-Driven Continuous Camera Director (`src/video-renderer/scene-animator.js`)**:
+  - Replaced hardcoded timer modulo cuts with continuous trajectory over `p = t / window.DURATION`.
+  - Camera movements (`slow_zoom_in`, `slow_zoom_out`, `pan_left`, `pan_right`, `tilt_up`, `tilt_down`, `ken_burns`, `static`, and `auto`) now smoothly scale to exact narration length.
+- **Max-Quality Organic Doodle Anatomy (`src/video-renderer/scene-animator.js`)**:
+  - Overhauled `drawDoodleCharacter`: replaced straight vertical spine line with contoured human torso (shoulders, ribcage, waist, hips), clavicle accents, articulated knees, and planted feet.
+  - Removed forced ground drop shadows, forced rosy cheek blush, and forced specular eye highlights.
+- **Light Parchment Hand-Drawn Inking Aesthetic (`hand_drawn_doodle`)**:
+  - Warm parchment paper backgrounds (`#faf7f2`, `#f6f1e8`, `#fdfbf7`) with dark charcoal inking (`#1c1917`), subtle line grain, and organic 12fps line boil.
+  - Removed all unwanted text stamps and banners (`NOT FOR COLD`, `THEORY OF MIND`, etc.) from narrative doodle themes.
+  - Added `doodle_modern_vs_prehistoric` split-screen comparison theme.
+
+---
+
+## [2.4.4] — 2026-11-09
+
+### Added
+- **Optional Captions via Prompt / Flag (`src/video-renderer/scene-animator.js`, `src/video-renderer/renderer.js`, `src/cli/make.js`)**:
+  - Captions, subtitle pills, and on-screen text are now disabled by default (`SHOW_CAPTIONS = false`).
+  - Added `detectCaptionsRequested(text)` to automatically enable captions when explicitly asked in prompt (e.g. `with captions`, `show captions`, `add subtitles`, `subtitles: true`).
+  - Added CLI flags `--captions`, `--subtitles`, `--with-captions` to `src/cli/make.js`.
+  - Added `showCaptions` option to MCP tools `create_video_from_script` and `publish_video`.
+  - Guarded all FFmpeg video-clip subtitle burn-in filters with `effectiveShowCaptions`.
+
+- **Multi-Shot Dynamic Camera Director (`src/video-renderer/scene-animator.js`)**:
+  - Scenes longer than 6.5s automatically trigger dynamic multi-shot camera cuts every 5.5s (`shotDur = 5.5`).
+  - Progresses cleanly through 4 cinematic angles: Wide establishing $\to$ Medium push-in $\to$ Action close-up $\to$ Dynamic high angle using spring transition interpolations (`shotCutSpring`), eliminating static camera stagnation.
+
+- **Pacing & Duration Scaling (`src/workflows/script.js`)**:
+  - Upgraded target scene count formula to `targetDuration ? Math.max(8, Math.ceil(targetDuration / 4.5)) : Math.max(sceneCount, 55)` to guarantee tight 4-6 second scene pacing matching high-retention video essay benchmarks.
+  - LLM instructions explicitly require 12-25 words per scene to prevent monolithic 30-50s static scenes.
+
+### Enhanced
+- **Visual Rendering Quality Polish (`src/video-renderer/scene-animator.js`)**:
+  - Ground contact drop shadows (`ellipse(0, legLength, 34, 7)`) anchor all characters to the ground plane.
+  - Specular eye highlights and warm rosy cheek blush (`rgba(251, 113, 133, 0.28)`) enhance character expressiveness.
+  - Round line caps (`ctx.lineCap = 'round'`, `ctx.lineJoin = 'round'`) for clean, hand-crafted doodle aesthetics.
+
+- **Near-Lossless FFmpeg Encoding (`src/video-renderer/renderer.js`)**:
+  - Upgraded CRF from 20/22 to `17` (visually lossless).
+  - Upgraded encoding preset from `veryfast` to `fast` for superior inter-frame motion estimation.
+  - Added `-x264-params aq-mode=3:deblock=-1,-1` to eliminate gradient banding on dark animated canvas backgrounds while preserving razor-sharp vector line art.
+  - Upgraded audio output stream to 320 kbps AAC stereo.
+
+---
+
 ## [2.4.3] — 2026-11-09
 
 ### Enhanced

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amg555/frameforge-mcp",
-  "version": "2.4.3",
+  "version": "2.4.5",
   "description": "FrameForge — AI video production engine for agentic IDEs. npx @amg555/frameforge-mcp. FFmpeg + TTS run on your machine. 21 MCP tools.",
   "publishConfig": {
     "access": "public"

package/scripts/deep-validate.js

@@ -20,7 +20,7 @@ check('batch handling',              code.includes('Array.isArray(body)'));
 check('ping handler',                code.includes("method === 'ping'"));
 check('notifications/init',          code.includes("notifications/initialized"));
 check('body size limit',             code.includes('MAX_BODY_BYTES'));
-check('SERVER_INFO version 2.4.3',   code.includes("version: '2.4.3'"));
+check('SERVER_INFO version 2.4.5',   code.includes("version: '2.4.5'"));
 check('18 tools defined (incl get_job_status)', code.includes('get_job_status'));
 check('export_to_editor tool defined', code.includes('export_to_editor'));
 check('edit_video tool defined', code.includes('edit_video'));
@@ -299,7 +299,7 @@ check('cf-worker has checkRateLimit',   cfWorker.includes('checkRateLimit'));
 check('cf-worker hashes token (SHA-256)', cfWorker.includes('SHA-256'));
 check('cf-worker uses RATE_LIMITS KV',  cfWorker.includes('env.RATE_LIMITS'));
 check('cf-worker returns 429 on limit', cfWorker.includes('429'));
-check('cf-worker version 2.4.3',        cfWorker.includes("'2.4.3'"));
+check('cf-worker version 2.4.5',        cfWorker.includes("'2.4.5'"));
 check('wrangler.toml has kv_namespaces',fs.readFileSync('./cloudflare-mcp/wrangler.toml','utf8').includes('kv_namespaces'));
 
 // ── plugins/skills present ────────────────────────────────────────────────

package/src/cli/make.js

@@ -98,7 +98,9 @@ function parseArgs(argv) {
     mode: 'full-auto',
     topic: '', topicsFile: '', language: 'en',
     style: 'educational comedy', channels: ['file'],
+    theme: '',
     orientation: 'landscape',
+    captions: false, subtitles: false,
     scenesFile: '', scriptFile: '', mediaDir: '',
     shorts: true, dryRun: false,
     noResearch: false, noScript: false, noImages: false, noTts: false, noPublish: false,
@@ -115,7 +117,12 @@ function parseArgs(argv) {
       case '--language':      args.language    = (argv[++i] || 'en').toLowerCase(); break;
       case '--orientation':   args.orientation = (argv[++i] || 'landscape').toLowerCase(); break;
       case '--portrait':      args.orientation = 'portrait'; break;
+      case '--captions':
+      case '--subtitles':
+      case '--with-captions': args.captions = true; break;
       case '--style':         args.style       = argv[++i] || args.style; break;
+      case '--theme':
+      case '--aesthetic':     args.theme       = argv[++i] || ''; break;
       case '--channels':      args.channels    = (argv[++i] || 'file').split(',').map(s => s.trim()); break;
       case '--no-research':   args.noResearch  = true; break;
       case '--no-script':     args.noScript    = true; break;
@@ -419,6 +426,7 @@ async function runSingleVideo(args, topic, outDir, workflows) {
     topic,
     title,
     style: args.style || '',
+    theme: args.theme || '',
     language: args.language,
     voice: resolvedVoice,
   });
@@ -435,7 +443,9 @@ async function runSingleVideo(args, topic, outDir, workflows) {
     topic,
     title,
     style: args.style || '',
+    theme: args.theme || '',
     language: args.language,
+    showCaptions: Boolean(args.captions || args.subtitles),
     renderWidth,
     renderHeight,
   });

package/src/mcp-server/server.js

@@ -420,6 +420,7 @@ const TOOLS = {
         theme,
         title,
         language,
+        showCaptions,
       });
 
       if (!renderResult.passed) {
@@ -584,10 +585,11 @@ Example scene:
         topic:          { type: 'string',  description: 'Overall topic/genre for visual aesthetic and background motion (e.g. "Kerala history", "crypto finance", "AI robotics")' },
         style:          { type: 'string',  description: 'Visual style/theme override (e.g. cinematic_documentary, finance_executive, cyber_tech, retro_synthwave, nature_organic, hype_sports, minimal_luxury, breaking_news, cosmic_space)' },
         theme:          { type: 'string',  description: 'Theme preset alias' },
+        showCaptions:   { type: 'boolean', default: false, description: 'Display on-screen synchronized subtitles/captions. Default false (clean canvas without text unless explicitly requested in prompt).' },
         productionId:   { type: 'string',  description: 'Optional — reuse an existing productionId' },
       },
     },
-    handler: async ({ scenes, title = 'FrameForge Video', orientation = 'landscape', voice, language, skipTts = false, parallelism = 1, withMusic = true, musicVolume = 0.07, topic = '', style = '', theme = '', productionId }) => {
+    handler: async ({ scenes, title = 'FrameForge Video', orientation = 'landscape', voice, language, skipTts = false, parallelism = 1, withMusic = true, musicVolume = 0.07, topic = '', style = '', theme = '', showCaptions = false, productionId }) => {
       const { runAssets } = require('../workflows/assets');
       const { runRender } = require('../workflows/render');
 
@@ -663,6 +665,7 @@ Example scene:
         theme,
         title,
         language,
+        showCaptions,
       });
       const renderResult = await runRender({
         productionId: pid,
@@ -676,6 +679,7 @@ Example scene:
         theme,
         title,
         language,
+        showCaptions,
       });
 
       if (!renderResult.passed) {
@@ -1633,7 +1637,7 @@ Allows the agent in Claude Code, Cursor, or any IDE to inspect the visual output
 
 const SERVER_INFO = {
   name:    'video-pipeline',
-  version: '2.4.3',
+  version: '2.4.5',
 };
 
 const CAPABILITIES = {

package/src/video-renderer/renderer.js

@@ -171,7 +171,14 @@ class VideoRenderer {
     speed = 1.0,
     clipVolume = 0,
     colorGrade = null,
+    showCaptions = false,
   } = {}) {
+    const { detectCaptionsRequested } = require('./scene-animator');
+    const effectiveShowCaptions = Boolean(
+      showCaptions ||
+      detectCaptionsRequested(`${caption} ${narration} ${topic} ${style} ${visualDescription}`) ||
+      process.env.FRAMEFORGE_SHOW_CAPTIONS === '1'
+    );
     const outputPath = path.join(this.vdir, `scene_${sceneIndex}_out.mp4`);
 
     // Idempotency: skip if already rendered and manifest says so
@@ -197,7 +204,7 @@ class VideoRenderer {
       const startSec = parseTimestamp(trimStart != null ? trimStart : startTime);
       const sp = buildSpeedFilters(speed);
 
-      const captionFilter = this._captionFilter(caption);
+      const captionFilter = effectiveShowCaptions ? this._captionFilter(caption) : '';
       const scaleFilter = `scale=${renderWidth}:${renderHeight}:force_original_aspect_ratio=increase:flags=lanczos,crop=${renderWidth}:${renderHeight}`;
       const colorFilter = buildColorFilter(colorGrade);
 
@@ -271,11 +278,14 @@ class VideoRenderer {
           caption,
           narration,
           visualDescription,
+          visualType,
           topic,
           style,
           theme,
           title,
           language,
+          camera,
+          focalPoint,
           html,
           code,
           clampedDur,
@@ -285,6 +295,7 @@ class VideoRenderer {
           outputPath,
           manifest,
           musicMood,
+          showCaptions: effectiveShowCaptions,
         });
       } catch (err) {
         console.warn(`[Renderer] Code-driven browser scene render failed (${err.message}), falling back to procedural animation`);
@@ -292,7 +303,7 @@ class VideoRenderer {
     }
 
     // Priority 3: Procedural dynamic animated fallback (dynamic moving gradients / camera drift)
-    const captionFilter = this._captionFilter(caption);
+    const captionFilter = effectiveShowCaptions ? this._captionFilter(caption) : '';
     let inputArgs = [];
     let vf = '';
 
@@ -324,12 +335,12 @@ class VideoRenderer {
       '-af', `apad=whole_dur=${clampedDur}`,
       '-t', String(clampedDur),
       '-map', '0:v:0', '-map', '1:a:0',
-      '-c:v', 'libx264', '-preset', 'veryfast', '-crf', '22',
+      '-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',
-      '-c:a', 'aac', '-b:a', '192k', '-ar', '48000', '-ac', '2',
+      '-x264-params', 'colorprim=bt709:transfer=bt709:colormatrix=bt709:aq-mode=3:deblock=-1,-1',
+      '-c:a', 'aac', '-b:a', '320k', '-ar', '48000', '-ac', '2',
       '-movflags', '+faststart',
       '-pix_fmt', 'yuv420p',
       outputPath,
@@ -352,11 +363,14 @@ class VideoRenderer {
     caption,
     narration,
     visualDescription,
+    visualType = 'code_animation',
     topic = '',
     style = '',
     theme = '',
     title = '',
     language = '',
+    camera = 'auto',
+    focalPoint = null,
     html = null,
     code = null,
     clampedDur,
@@ -366,6 +380,7 @@ class VideoRenderer {
     outputPath,
     manifest,
     musicMood,
+    showCaptions = false,
   }) {
     let htmlContent;
     if (html && typeof html === 'string' && html.trim().length > 0) {
@@ -384,6 +399,7 @@ class VideoRenderer {
         topic,
       });
     } else {
+      const effectiveCam = camera || selectCameraHint(sceneIndex, focalPoint || {});
       htmlContent = generateSceneHtml({
         caption,
         narration,
@@ -399,6 +415,9 @@ class VideoRenderer {
         height: renderHeight,
         sceneIndex,
         musicMood,
+        showCaptions,
+        camera: effectiveCam,
+        cameraHint: effectiveCam,
       });
     }
 
@@ -434,13 +453,13 @@ class VideoRenderer {
       '-i', framesPattern,
       '-i', voicePath,
       '-map', '0:v:0', '-map', '1:a:0',
-      '-c:v', 'libx264', '-preset', 'veryfast', '-crf', '20',
+      '-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',
+      '-x264-params', 'colorprim=bt709:transfer=bt709:colormatrix=bt709:aq-mode=3:deblock=-1,-1',
       '-pix_fmt', 'yuv420p',
-      '-c:a', 'aac', '-b:a', '192k', '-ar', '48000', '-ac', '2',
+      '-c:a', 'aac', '-b:a', '320k', '-ar', '48000', '-ac', '2',
       '-af', `apad=whole_dur=${clampedDur}`,
       '-t', String(clampedDur),
       '-movflags', '+faststart',