@amg555/frameforge-mcp 2.4.2 → 2.4.4

package/CHANGELOG.md

@@ -4,6 +4,66 @@ All notable changes to FrameForge are documented here.
 
 ---
 
+## [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
+- **Sentence-Synchronized Subtitles (`src/video-renderer/scene-animator.js`)**:
+  - Replaced static slide titles, topic banners, and category tags (`// CHRONICLE`, `// HERITAGE`, top headlines) with sentence-synchronized broadcast subtitles centered at bottom with subtle frosted glass backing pills.
+  - Automatically slices narration scripts into sentence beats keyed to duration (`DURATION / sentenceCount`) with smooth spring entrance transitions (`spring(localT, 0.04, 210, 16)`).
+  - Word wrapping for long sentences to prevent clipping.
+
+- **3-Beat Progressive Choreography & Dynamic Camera (`src/video-renderer/scene-animator.js`)**:
+  - Added multi-beat progression across all 9 doodle themes:
+    - `doodle_dressing`: Beat 1 browsing wardrobe $\to$ Beat 2 trying on shirt $\to$ Beat 3 smiling & waving in glowing amber mirror.
+    - `doodle_shiver_cold`: Beat 1 shivering alone $\to$ Beat 2 "NOT FOR COLD" stamp $\to$ Beat 3 "NOT FOR PROTECTION" stamp with character contemplating.
+    - `doodle_hunter_savannah`: Character walking with spear across savannah grass swatting mosquitoes under sun.
+    - `doodle_sewing_needle`: Campfire $\to$ loupe zoom into bone needle stitching animal hide $\to$ archaeological timeline badge.
+    - `doodle_shame_reflection`: Looking down $\to$ water reflection ripples clear $\to$ blush & Theory of Mind halo.
+    - `doodle_tribe_meeting`: Two clans approach $\to$ peace greeting $\to$ social language connection arc.
+    - `doodle_thinking_future`: Campfire thinker $\to$ thought cloud $\to$ planning for tomorrow tools & sunrise.
+    - `doodle_microscope_lice`: Character scratching itching pelt $\to$ microscope slide $\to$ head vs body lice divergence badge.
+  - Added subtle cinematic camera drift and breathing (`camZoom`, `camPanX`, `camPanY`) via progress $p = t / DURATION$.
+
+### Fixed
+- **Regex Parsing Bug in Template Literal (`src/video-renderer/scene-animator.js`)**:
+  - Fixed syntax error caused by unescaped newline in regex literal inside template literal string.
+- **Theme Detection Priority (`src/video-renderer/scene-animator.js`)**:
+  - Prioritized specific narrative themes (`doodle_microscope_lice`, `doodle_shiver_cold`, `doodle_hunter_savannah`, `doodle_tribe_meeting`, `doodle_thinking_future`, `doodle_sewing_needle`, `doodle_shame_reflection`) ahead of general wardrobe dressing to guarantee every scene gets its exact script-matched visual doodle.
+
+---
+
 ## [2.4.2] — 2026-11-09
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amg555/frameforge-mcp",
-  "version": "2.4.2",
+  "version": "2.4.4",
   "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.2',   code.includes("version: '2.4.2'"));
+check('SERVER_INFO version 2.4.4',   code.includes("version: '2.4.4'"));
 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.2',        cfWorker.includes("'2.4.2'"));
+check('cf-worker version 2.4.4',        cfWorker.includes("'2.4.4'"));
 check('wrangler.toml has kv_namespaces',fs.readFileSync('./cloudflare-mcp/wrangler.toml','utf8').includes('kv_namespaces'));
 
 // ── plugins/skills present ────────────────────────────────────────────────

package/src/cli/make.js

@@ -99,6 +99,7 @@ function parseArgs(argv) {
     topic: '', topicsFile: '', language: 'en',
     style: 'educational comedy', channels: ['file'],
     orientation: 'landscape',
+    captions: false, subtitles: false,
     scenesFile: '', scriptFile: '', mediaDir: '',
     shorts: true, dryRun: false,
     noResearch: false, noScript: false, noImages: false, noTts: false, noPublish: false,
@@ -115,6 +116,9 @@ 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 '--channels':      args.channels    = (argv[++i] || 'file').split(',').map(s => s.trim()); break;
       case '--no-research':   args.noResearch  = true; break;
@@ -436,6 +440,7 @@ async function runSingleVideo(args, topic, outDir, workflows) {
     title,
     style: args.style || '',
     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.2',
+  version: '2.4.4',
 };
 
 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);
 
@@ -285,6 +292,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 +300,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 +332,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,
@@ -366,6 +374,7 @@ class VideoRenderer {
     outputPath,
     manifest,
     musicMood,
+    showCaptions = false,
   }) {
     let htmlContent;
     if (html && typeof html === 'string' && html.trim().length > 0) {
@@ -399,6 +408,7 @@ class VideoRenderer {
         height: renderHeight,
         sceneIndex,
         musicMood,
+        showCaptions,
       });
     }
 
@@ -434,13 +444,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',