@amg555/frameforge-mcp 2.4.3 → 2.4.4

package/CHANGELOG.md

@@ -4,6 +4,38 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amg555/frameforge-mcp",
-  "version": "2.4.3",
+  "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.3',   code.includes("version: '2.4.3'"));
+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.3',        cfWorker.includes("'2.4.3'"));
+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.3',
+  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',

package/src/video-renderer/scene-animator.js

@@ -497,6 +497,13 @@ window.seek = async (t) => {
 </html>`;
 }
 
+// ── Captions Requested Detector ───────────────────────────────────────────────
+/** Returns true ONLY if caller explicitly asks for on-screen captions or subtitles in prompt. */
+function detectCaptionsRequested(text = '') {
+  if (!text || typeof text !== 'string') return false;
+  return /(?:with|show|display|include|enable|add)\s+(?:captions?|subtitles?|sub-titles?|subs?)|(?:captions?|subtitles?)\s*[:=]\s*(?:true|yes|1|on|always)/i.test(text);
+}
+
 // ── HTML Scene Code Generator ──────────────────────────────────────────────────
 /**
  * Generate a complete, self-contained HTML scene conforming to window.seek(t).
@@ -517,7 +524,13 @@ function generateSceneHtml({
   width = 1920,
   height = 1080,
   sceneIndex = 0,
+  showCaptions = false,
 } = {}) {
+  const captionsWanted = Boolean(
+    showCaptions ||
+    detectCaptionsRequested(`${caption} ${narration} ${topic} ${visualDescription} ${style} ${title}`) ||
+    process.env.FRAMEFORGE_SHOW_CAPTIONS === '1'
+  );
   const aestheticKey = detectAesthetic({
     topic,
     style,
@@ -627,6 +640,7 @@ function spring(t, delay = 0, tension = ${aesthetic.springTension}, friction = $
   return 1 - Math.exp(-omega * dt);
 }
 
+const SHOW_CAPTIONS = ${JSON.stringify(captionsWanted)};
 const AESTHETIC = ${JSON.stringify(aestheticKey)};
 const BG_TYPE = ${JSON.stringify(aesthetic.backgroundType)};
 const COMP_THEME = ${JSON.stringify(compTheme)};
@@ -742,9 +756,47 @@ function drawMainScene(t) {
   ctx.save();
   const p = Math.min(1, Math.max(0, t / window.DURATION));
   const enterSpring = spring(t, 0.05, 170, 13);
-  const camZoom = 1.0 + Math.sin(t * 0.45) * 0.02 + p * 0.04;
-  const camPanX = Math.sin(t * 0.35) * 12;
-  const camPanY = Math.cos(t * 0.28) * 6;
+
+  // Multi-Shot Dynamic Director: cut camera framing every 5-7s to keep pacing energetic
+  const shotDur = 5.5;
+  const shotIdx = Math.floor(t / shotDur);
+  const shotLocalT = t - shotIdx * shotDur;
+  const shotCutSpring = spring(shotLocalT, 0.02, 220, 18);
+  const shotProgress = (t % shotDur) / shotDur;
+
+  let targetZoom = 1.0;
+  let targetPanX = 0;
+  let targetPanY = 0;
+
+  if (window.DURATION > 6.5) {
+    const angle = shotIdx % 4;
+    if (angle === 1) {
+      targetZoom = 1.14 + shotProgress * 0.03;
+      targetPanX = -40 + Math.sin(t * 0.4) * 8;
+      targetPanY = -12;
+    } else if (angle === 2) {
+      targetZoom = 1.20 + shotProgress * 0.03;
+      targetPanX = 40 + Math.cos(t * 0.4) * 8;
+      targetPanY = -18;
+    } else if (angle === 3) {
+      targetZoom = 1.08 + shotProgress * 0.02;
+      targetPanX = Math.sin(t * 0.3) * 12;
+      targetPanY = 12;
+    } else {
+      targetZoom = 1.02 + shotProgress * 0.03;
+      targetPanX = Math.sin(t * 0.3) * 12;
+      targetPanY = Math.cos(t * 0.25) * 6;
+    }
+  } else {
+    targetZoom = 1.0 + Math.sin(t * 0.45) * 0.02 + p * 0.04;
+    targetPanX = Math.sin(t * 0.35) * 12;
+    targetPanY = Math.cos(t * 0.28) * 6;
+  }
+
+  const camZoom = 1.0 + (targetZoom - 1.0) * Math.min(1, Math.max(0, shotCutSpring));
+  const camPanX = targetPanX * Math.min(1, Math.max(0, shotCutSpring));
+  const camPanY = targetPanY * Math.min(1, Math.max(0, shotCutSpring));
+
   ctx.translate(W / 2 + camPanX, H * 0.50 + camPanY);
   ctx.scale(Math.min(1.04, Math.max(0.88, enterSpring)) * camZoom, Math.min(1.04, Math.max(0.88, enterSpring)) * camZoom);
   ctx.translate(-W / 2, -H * 0.50);
@@ -828,6 +880,12 @@ function drawMainScene(t) {
     ctx.translate(x, y);
     ctx.scale(scale, scale);
 
+    // Soft ground contact shadow
+    ctx.fillStyle = 'rgba(0, 0, 0, 0.28)';
+    ctx.beginPath();
+    ctx.ellipse(0, legLength, 34, 7, 0, 0, Math.PI * 2);
+    ctx.fill();
+
     const blink = (t % 3.2 < 0.14) ? 0.15 : 1.0;
     const mouthTalk = Math.abs(Math.sin(t * 14)) * 4;
     const torsoTopY = -torsoHeight;
@@ -904,6 +962,22 @@ function drawMainScene(t) {
     sCircle(-12, eyeY, Math.max(1, eyeR), seed + 23, '#0f172a', 2, '#0f172a');
     sCircle(12, eyeY, Math.max(1, eyeR), seed + 24, '#0f172a', 2, '#0f172a');
 
+    // Specular eye highlights
+    if (blink > 0.4) {
+      ctx.fillStyle = '#ffffff';
+      ctx.beginPath();
+      ctx.arc(-14, eyeY - 1.5, 1.2, 0, Math.PI * 2);
+      ctx.arc(10, eyeY - 1.5, 1.2, 0, Math.PI * 2);
+      ctx.fill();
+    }
+
+    // Warm cheek blush
+    ctx.fillStyle = 'rgba(251, 113, 133, 0.28)';
+    ctx.beginPath();
+    ctx.ellipse(-14, headCenterY + 12, 6, 3.5, 0, 0, Math.PI * 2);
+    ctx.ellipse(14, headCenterY + 12, 6, 3.5, 0, 0, Math.PI * 2);
+    ctx.fill();
+
     // Eyebrows
     if (expression === 'shivering') {
       sLine(-18, eyeY - 12 + wb(seed, 2), -6, eyeY - 7 + wb(seed, 2), seed + 25, '#0f172a', 2.5);
@@ -2084,8 +2158,8 @@ function drawMainScene(t) {
 function drawCinematicOverlay(t) {
   ctx.save();
 
-  // Subtitles / Spoken Narration - dynamic sentence progression across time
-  if (NARRATION && NARRATION.trim().length > 0) {
+  // Subtitles / Spoken Narration - ONLY rendered when explicitly asked in prompt or options
+  if (SHOW_CAPTIONS && NARRATION && NARRATION.trim().length > 0) {
     // Split narration into natural spoken sentence chunks
     const sentences = NARRATION.split(/[.!?;|]+/).map(s => s.trim()).filter(Boolean);
 
@@ -2234,6 +2308,7 @@ module.exports = {
   generateSceneCodeWithLLM,
   detectAesthetic,
   detectComponentTheme,
+  detectCaptionsRequested,
   getScriptFontStack,
   AESTHETICS,
   REGIONAL_FONTS,

package/src/workflows/render.js

@@ -36,6 +36,7 @@ async function runRender({
   theme = '',
   title = '',
   language = '',
+  showCaptions = false,
 }) {
   const sm        = new StateMachine({ mode: 'file', stateDir: STATE_DIR });
   const retryPol  = new RetryPolicy({ maxAttempts: 2, baseDelayMs: 15000 });
@@ -77,6 +78,7 @@ async function runRender({
         speed:             asset.speed,
         clipVolume:        asset.clipVolume,
         colorGrade:        asset.colorGrade,
+        showCaptions:      asset.showCaptions !== undefined ? asset.showCaptions : showCaptions,
         renderWidth,
         renderHeight,
       });

package/src/workflows/script.js

@@ -116,9 +116,9 @@ async function runScript({
 
   const facts = claims.slice(0, 8).map(c => c.safe_wording || c.claim).join('; ');
 
-  // If targetDuration is given, adjust scene count guidance (≈ 5s/scene).
-  // No ceiling — long-form documentaries, lectures, and podcasts may need hundreds of scenes.
-  const targetScenes = targetDuration ? Math.max(5, Math.round(targetDuration / 5)) : sceneCount;
+  // If targetDuration is given, adjust scene count guidance (≈ 4.5-5s per scene for high retention).
+  // No ceiling — long-form documentaries, lectures, and podcasts scale dynamically.
+  const targetScenes = targetDuration ? Math.max(8, Math.ceil(targetDuration / 4.5)) : Math.max(sceneCount, 55);
 
   const raw = await retryPol.executeStage('Script', async () => {
     const system = [
@@ -136,7 +136,7 @@ async function runScript({
       `STYLE: ${style}`,
       `LANGUAGE: ${language}`,
       '',
-      `Write exactly ${targetScenes} scenes (schema_version "2.0.0"). Each scene must have:`,
+      `Write exactly ${targetScenes} scenes (schema_version "2.0.0"). High visual pacing: 4-6 seconds per scene (12-25 spoken words). Never write monolithic 30-50s static scenes. Each scene must have:`,
       'scene_id (integer), schema_version "2.0.0",',
       'narration (15-35 words in the specified language, spoken aloud),',
       'caption (3-6 words UPPERCASE, text overlay),',