@amg555/frameforge-mcp 2.4.10 → 2.7.0

package/.claude-plugin/marketplace.json

@@ -1,8 +1,8 @@
 {
   "name": "frameforge",
   "displayName": "FrameForge — AI Video Production",
-  "description": "Full AI video production engine. Produce short-form reels (1080×1920), YouTube videos (1920×1080), or code-driven animated explainers — directly from your IDE. Playwright + FFmpeg renders every frame. 17 MCP tools.",
-  "version": "2.3.1",
+  "description": "Full AI video production engine. Produce short-form reels (1080×1920), YouTube videos (1920×1080), or code-driven animated explainers — directly from your IDE. Playwright + FFmpeg renders every frame. 28 MCP tools. Whisper, yt-dlp, broadcast audio, 24 film styles, ClaudeAnimationBase, onetake 39-move library, HyperFrames motion craft.",
+  "version": "2.7.0",
   "homepage": "https://github.com/AMG555/FrameForge",
   "plugins": [
     {
@@ -12,7 +12,7 @@
         {
           "name": "video-pipeline",
           "displayName": "FrameForge Video Pipeline",
-          "description": "End-to-end video production: research → script → TTS → images → render → publish. Three paths: (1) IDE writes scenes (most common, no API key), (2) code-driven Playwright animation, (3) auto-research pipeline. 17 MCP tools.",
+          "description": "End-to-end video production: research → script → TTS → images → render → publish. Three paths: (1) IDE writes scenes (most common, no API key), (2) code-driven Playwright animation, (3) auto-research pipeline. 28 MCP tools. Includes Whisper transcription, yt-dlp ingestion, broadcast-grade audio, upstream skills sync.",
           "triggerPhrases": [
             "make a video about",
             "produce a reel on",
@@ -25,7 +25,25 @@
             "run the pipeline",
             "publish video",
             "overnight batch",
-            "queue videos"
+            "queue videos",
+            "ingest this video",
+            "transcribe this",
+            "download from youtube",
+            "mix audio",
+            "sync upstream skills",
+            "check for updates"
+          ]
+        },
+        {
+          "name": "html-renderer",
+          "displayName": "HTML Renderer",
+          "description": "HTML-as-compositor rendering: pure seek(t) function, Playwright capture, closed-loop visual QA.",
+          "triggerPhrases": [
+            "html video",
+            "remotion style",
+            "code-driven animation",
+            "harness render",
+            "render animation"
           ]
         }
       ]

package/CHANGELOG.md

@@ -4,6 +4,180 @@ All notable changes to FrameForge are documented here.
 
 ---
 
+## [2.7.0] — 2026-11-11
+
+### Added
+
+- **OM Motion Library — 24 moves** (`reel/engine.js`):
+  - `beatAt(index, bpm, fps)` / `beatTime(index, bpm)` / `snapToBeat(t, bpm)` — HyperFrames beat-grid formula; each index rounded independently (never accumulated, eliminates drift).
+  - `OM` object — 24 pure `(t, opts) → CSS style` motion primitives from OneTake's 39-move library: `spring`, `rise`, `iris`, `irisClose`, `zoomThrough`, `morphRect`, `silk`, `belt`, `ripple`, `odometer`, `camera`, `handheld`, `popOut`, `drop`, `implode`, `slideExit`, `wordByWord`, `scalePop`, `revealWipe`, `typewriter`, `counterFlip`, `breathe`, `float`, `pulseOpacity`, `carryScore`.
+  - `ROOM_SFX` palette — OneTake 5-material standard (air/wood/glass/sub/bubble at −8 dBFS) for use with `cue()`.
+  - `event(type, t, meta)` + `window.__events()` — Sound-from-composition contract; render.mjs extracts cues to `sfx-events.json` after probe.
+
+- **Earshot Forge DSP Primitives** (`src/audio-mixer/mixer.js`):
+  - `forgeModalResonator(freq, q, gainDb)` — FFmpeg EQ approximating physical material resonance (wood/glass/metal/sub frequency guidelines from earshot).
+  - `forgeSVFilter(type, freq, q)` — State-variable filter: lp/hp/bp/notch.
+  - `forgeComputedRoom(sizeM, damp, earlyMs)` — Computed room from physical dimensions using Sabine RT60 approximation; produces `aecho` filter string with 3-tap early reflections.
+  - `forgeKitSoundBank(material, role)` — Maps earshot material + role to `SFX_FREQ_MAP` key.
+  - `"computed:sizeM:damp:earlyMs"` room string supported in `mix_audio_pro` and `_buildVoiceChainFilter`.
+
+- **J/L-Cut Editing in plan_video_edit** (`src/mcp-server/server.js`):
+  - Style-aware cut type assignment: cinematic/documentary → J-cut; vintage/film_16mm/lofi_chill → L-cut; fast_paced/cyberpunk/anime_action → hard cut.
+  - `audio_offset` field in every clip: negative = J-cut (audio precedes video by 0.25–0.5s), positive = L-cut (audio trails by 0.3s).
+  - `cut_type` field in `edit.json` clips; emojis in `edit-plan.md` (🎵/🔊/✂️).
+  - `bpm` param for beat-grid snapping of cut points.
+
+- **TREATMENT.md Director Document** (`src/mcp-server/server.js` — `plan_video_edit`):
+  - Auto-generated 8-section director treatment (lemo-opuscar DIRECTOR.md format): Concept, Tone, Visual Language, Sound, Narrative Arc, Shot List, Delivery, Director Notes.
+  - `generate_treatment` param (default true); path returned in `treatmentPath`.
+
+- **check_upstream_updates — Changelog Notice**:
+  - Response now includes `pendingUpdates[]` with per-repo human-readable impact descriptions.
+  - `hasUpdates` boolean field for agent routing.
+  - `hint` field shows update count or next action.
+
+- **Version Consistency Pass**:
+  - All agent configs synced to v2.7.0: `cloudflare-mcp/src/index.js`, `scripts/deep-validate.js`, `plugins/video-pipeline/.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `AGENT.md`, `README.md`, `mcp-tools.md`, `.github/copilot-instructions.md`, `.upstream-skills.json`.
+
+---
+
+## [2.6.0] — 2026-11-12
+
+### Added
+
+- **Unified Standalone CLI Commands** (`src/cli/make.js`):
+  - `frameforge download <url>` — yt-dlp media ingestion with optional subtitles (`--subtitles`), audio extraction (`--audio`), output directory (`--out-dir`), and custom naming (`--filename`).
+  - `frameforge transcribe <file>` — Whisper speech transcription exporting SRT, NDJSON, and JSON formats with model selection (`--model`) and language hints (`--language`).
+  - `frameforge sync` / `frameforge update` — Upstream skills synchronizer checking all 9 frontier repos.
+  - `frameforge doctor` and `frameforge setup` — First-class subcommand routing.
+- **15+ Year Sound Engineer Signal Chain & Procedural Audio Engine** (`src/audio-mixer/mixer.js`):
+  - Multi-element procedural SFX synthesis (shaped pink/white noise, sub-bass pitch drop, dual-sine chime harmonics, acoustic chord triads) replacing plain sine beeps across all 13 SFX types (`whoosh`, `swish`, `impact`, `deep_boom`, `punch`, `pop`, `click`, `tick`, `riser`, `chime`, `sparkle`, `buzz`, `transition`).
+  - Enhanced voice mastering chain: 80Hz rumble cut, 300Hz boxy mud notch (-1.5dB), 5kHz presence boost (+2dB), 12kHz air shelf (+1.5dB), 3:1 broadcast compressor, 6.5kHz de-esser, and -60dBFS noise gate.
+  - Acoustic pocket carving: 2.5kHz notch (-3.5dB) on music layer prevents vocal masking and guarantees intelligibility on mobile phone speakers.
+  - Dynamic sidechain ducking (-18dB attenuation) with 40ms perceptual lead and musical release.
+  - Video SFX mixing: `mixVideo` supports direct timeline SFX cue placement and two-pass EBU R128 loudness normalization.
+- **`check_upstream_updates` MCP Tool (Tool #28)** (`src/mcp-server/server.js`):
+  - Fast offline check of the last sync state across all 9 upstream reference repositories.
+  - Automatic notification caching: users and agents are visibly notified on CLI doctor runs, make runs, and tool responses whenever upstream commits are updated.
+- **Camera Motion & Punch-Ins in Video Editor** (`src/video-editor/editor.js`):
+  - `editClip` and `editAndAssemble` support dynamic camera moves (`punch_in`, `zoom_in`, `ken_burns`, `slow_zoom_out`, `pan_left`, `pan_right`) using broadcast-grade zoompan filter expressions.
+- **Frontier Craft Documentation References**:
+  - `character-animation.md`: Complete ClaudeAnimationBase guide (31 emotions, timing principles, 12fps line boil).
+  - `directing.md`: Professional directing method from lemo-opuscar (sound, rhythm, camera, staging).
+  - `earshot-audio.md`: Professional 5-loop audio quality workflow and LUFS tables.
+  - `hyperframes-motion.md`: Measured motion craft from HyperFrames launch films.
+- **Tests & Quality**:
+  - 100% test pass rate across 636 tests in 136 suites.
+
+---
+
+## [2.4.13] — 2026-11-12
+
+### Added
+
+- **HyperFrames Declarative Clips** (`engine.js`):
+  - `.clip[data-start]` elements automatically participate in the timeline during `seek(t)` without manual JS registration.
+  - Computes and binds `--lt` (local time in seconds), `--progress` ($0.0000 \to 1.0000$), `data-lt`, and `data-progress` dynamically.
+- **OneTake Continuous Camera Choreography** (`engine.js`):
+  - `cameraPath(waypoints, opts)`: Smooth continuous camera panning, zooming, and tilting across the `#stage` using cubic easing (`easeInOut`) without harsh cuts.
+  - `cameraShake(t, opts)`: Deterministic organic handheld camera noise using 2D continuous simplex noise (`noise2D`).
+- **ClaudeAnimationBase Mascot Vector Character** (`engine.js`):
+  - `mascot(emotion, opts)`: Procedural SVG mascot character supporting 12 emotions (`happy`, `excited`, `thinking`, `confused`, `skeptical`, `surprised`, `alarmed`, `celebrating`, `proud`, `curious`, `sad`, `neutral`).
+  - Includes 12fps line boil, eye blink cycle, and speech mouth flutter (`setSpeaking(true)`).
+- **gbro-collage-broll Editorial Halftone Paper Collage** (`engine.js`):
+  - `collageCard(content, opts)`: Paper collage card component featuring radial halftone dot pattern, washi tape accent strip, 2.5D perspective tilt, and drop shadow.
+- **Viral Karaoke Captions** (`engine.js`):
+  - Enhanced `captions()` and `_tickCaptions()` to split transcript segments into word tokens.
+  - Spoken words pop with $1.14\times$ scale, glow shadow, and high-contrast highlight (`#facc15`).
+- **Earshot Web Audio SFX Live Preview** (`engine.js`):
+  - Real-time procedural audio synthesis in browser preview (`!window.__playwright`) for `cue()` sound triggers (`whoosh`, `impact`, `pop`, `click`, `riser`).
+- **Lemo-Opuscar J-Cut and L-Cut Audio Splits** (`editor.js`):
+  - `splitCut: 'j-cut' | 'l-cut'` support in `concatClipsWithTransitions` using asymmetric S-curve audio crossfades (`qsin` / `hsin`).
+- **FFmpeg Concurrency & Memory Safety** (`editor.js`):
+  - Constrained x264 encoding threads (`-threads 2`) across clip trimming and transition concatenation to prevent thread pool exhaustion and memory allocation failures.
+
+### Tests & Validation
+
+- Unit tests added for camera waypoints, camera shake, declarative clips, karaoke word formatting, and mascot emotion catalog in `engine.test.js`.
+- J-cut transition assembly test added to `editor.test.js`.
+- `deep-validate.js` updated to verify all frontier primitives and editor split cut capabilities.
+- 100% test pass rate across 624 tests in 135 suites.
+
+---
+
+## [2.4.12] — 2026-11-11
+
+### Added
+
+- **`transcribe_media` MCP tool (Tool #25)** — Whisper speech transcription with word-level timestamps.
+  - Supports `openai-whisper` (local GPU/CPU), `faster-whisper` (CTranslate2), `whisper-cli` binary, or `OPENAI_API_KEY` cloud fallback.
+  - Output formats: `ndjson` (NDJSON for `engine.js captions()`/`cuePhrase()`), `srt` (standard subtitle file), `json` (full structured data), `all` (all three).
+  - Returns silence/pause boundaries for intelligent cut alignment in `plan_video_edit`.
+  - Install: `pip install openai-whisper` (local, free, no API key required).
+- **`ingest_url` MCP tool (Tool #26)** — yt-dlp-powered media ingestion from any web URL.
+  - Supports YouTube, Vimeo, Twitter/X, Instagram, TikTok, Twitch, SoundCloud, direct MP4/MP3 URLs, and 1000+ other sites.
+  - Downloads up to 1080p MP4 (video) or MP3 (audio-only). Probes and returns `duration`, `width`, `height`.
+  - Output goes to `.frameforge-files/downloads/` and can be passed directly to `edit_video`, `transcribe_media`, or any scene `video_path`/`audio_path`.
+  - Install: `pip install yt-dlp` (or `winget install yt-dlp` on Windows).
+- **`mix_audio_pro` MCP tool (Tool #27)** — Professional broadcast-grade audio post-production.
+  - Full 10+ year sound engineer signal chain: 80Hz HPF → presence +2dB@5kHz → air shelf +1.5dB@12kHz → 3:1 compressor → de-esser @6.5kHz → optional room acoustics → sidechain duck (-18dB) → stereo widener (M/S 1.4x) → procedural SFX timeline → two-pass EBU R128 loudnorm.
+  - Procedural SFX synthesis from the earshot pattern: `whoosh` (200Hz/400ms), `impact` (60Hz/500ms), `pop` (600Hz/120ms), `click` (2.5kHz/50ms), `riser` (100Hz/2s). All placed with 40ms perceptual lead.
+  - `sfxCues: [{ name, time, volume }]` — millisecond-accurate placement, no sample files required.
+  - `addReverb: true` — 30ms pre-delay + 0.3s RT60 aecho for cinematic narrator warmth.
+  - `stereoWiden: true` — mid-side extrastereo 1.4x on music layer (voice stays mono-center).
+  - `videoPath` parameter — mux the final mixed audio directly into a video file.
+  - Returns `{ measuredLufs, measuredTp, passed, chain }` with full signal chain summary.
+- **Professional AudioMixer upgrade** (`src/audio-mixer/mixer.js`):
+  - `_buildVoiceChainFilter()` — unified voice chain: HPF + presence EQ + air shelf + compressor + de-esser.
+  - `_twoPassNorm()` — two-pass EBU R128 loudnorm (measure + apply with measured values for linear accuracy).
+  - `_synthesizeSfxCue()` — earshot-pattern procedural SFX synthesis with 40ms perceptual lead via FFmpeg lavfi.
+  - `SFX_FREQ_MAP` and `PERCEPTUAL_LEAD_S` exported for consumers.
+  - `mixWithDucking()` now accepts `{ addReverb, stereoWiden, sfxCues }` optional parameters.
+  - `_sidechainMixPro()` — full pro chain replacing legacy `_sidechainMix()`.
+  - Music band now filtered to 16kHz (up from 8kHz) and stereo-widened when `stereoWiden: true`.
+  - Music attenuation updated from -15dB to -18dB for better voice intelligibility.
+  - Backward-compatible: existing callers work unchanged.
+- **`mix_audio_pro.py`** scaffold script (`plugins/...scripts/mix_audio_pro.py`) — standalone Python CLI with the same professional chain, usable from within HTML-renderer projects via `uv run scripts/mix_audio_pro.py`.
+- **Upstream skills auto-notification** (`src/skills/sync-upstream.js`):
+  - `sync_upstream_skills` MCP tool now returns `updatedRepos[]` and emits a visible user notice when any of the 9 tracked repositories has new commits.
+  - Optional `SKILL_UPDATE_WEBHOOK_URL` env var — POSTs a JSON callback whenever upstream repos update.
+  - Console output in non-silent mode now lists each updated repo and explains that techniques were automatically applied.
+- **Expanded `procedural-sfx.md` reference** — added full professional voice chain documentation (10+ year rationale per stage), music bed mood matching table, and broadcast loudness standards reference (YouTube, Podcast, Netflix, EBU R128).
+
+### Documentation
+- **CLAUDE.md** — Updated tool count to 27, added `PROFESSIONAL AUDIO WORKFLOW` section covering Whisper transcription → cuePhrase sync, yt-dlp ingestion, `mix_audio_pro` call examples, and upstream skills auto-update workflow.
+
+---
+
+## [2.4.7] — 2026-11-11
+
+### Added
+- **`quality` mode in `render_animation` MCP tool** — Closed-loop visual QA gate (1–10 per-frame score, worst frames, motion delta) is now a first-class MCP mode. Returns `{ passed, overallScore, worstFrames, motionDelta }` structured directly on the tool response — the Opus 5.5 fix-loop entry point.
+- **`golden` mode in `render_animation` MCP tool** — Golden stills regression baseline. `goldenSave: true` captures 4-keyframe SHA-256 hashes; `goldenCheck: true` compares against baseline and fails on any hash drift (refactor broke determinism).
+- **`subframes` parameter in `render_animation` full mode** — Motion-blur 180° shutter simulation. `subframes: 6` renders 6 sub-frames per output frame and blends them; eliminates ghosting on fast morphs. Default 1 (no blur). Documented in CLAUDE.md.
+- **`skipVerify` parameter in `render_animation` full mode** — Skip the automatic purity gate before full render. Default `false` (gate always runs).
+- **`sampleRate` parameter in `render_animation` quality mode** — Override samples-per-second for quality gate (default 2). Higher values = more samples = more precise worst-frame detection.
+- **Automatic purity gate before `render full`** — `render.mjs` now auto-invokes `harness verify` before starting frame rendering unless `--skip-verify` is passed or a passing `purity_report.json` is already cached.
+
+### Improved
+- **`scaffold_animation_project` edit.js generation** — Starter code now implements all 10 Motion Craft rules:
+  - Rule 1: `spring()` damped harmonic entrance instead of linear `Math.min(1, lt / 0.3)` fade.
+  - Rule 2: 3-property entrance — `opacity` + `scale(0.88→1.0)` + `translateY(40→0)` for every subject layer.
+  - Rule 3: Caption overlay staggered 0.18s after primary subject.
+  - Rule 4: Exits 0.25s, entrances 0.6s (asymmetric timing).
+  - Rule 5: 5 named layers per scene (`bg`, `env`, `subject`, `overlay`, `fg`) with correct z-ordering.
+  - Rule 7: Lissajous camera drift (`sin(0.4t)`, `cos(0.3t)`) on the `bg` layer — no scene ever freezes.
+  - Import line now includes `spring` from `reel/engine.js`.
+- **`verify_scene_quality` dynamic sample density** — Previously hardcoded to 5 samples at fixed percentiles. Now derives sample count from `sampleRate * duration`, minimum 5, evenly distributed. Enables richer QA on long-form videos at `sampleRate: 4+`.
+- **CLAUDE.md closed-loop QA protocol** — Expanded Step 5b with actionable fix guidance per issue type (blank frame, stuck motion, corner-confined, blown, low-contrast). Added Step 5c for motion-blur pass. Added Step 6 effort table (xhigh/medium per stage). Upgraded Step 9 golden regression to use the new `golden` MCP mode.
+
+### Technical
+- `render_animation` handler now returns `overallScore`, `worstFrames`, `motionDelta`, `qualityReport`, and `goldenReport` fields from the tool response — agents no longer need to read report files manually.
+- `harness.mjs quality` command now uses a separate `quality_sheet.jpg` output (not `sheet.jpg`) to avoid overwriting the visual review contact sheet.
+- `render_animation` quality/golden modes route through `harness.mjs` (not `render.mjs`) since that's where the implementations live.
+
+---
+
 ## [2.4.6] — 2026-11-10
 
 ### Enhanced

package/CLAUDE.md

@@ -20,7 +20,7 @@ You are a **video producer** working inside FrameForge. Your job is to design sc
 
 ## WHAT YOU MAY DO
 
-- Call any of the 17 FrameForge MCP tools (listed below)
+- Call any of the 28 FrameForge MCP tools (listed below)
 - Write scene arrays, narration text, captions, and visual descriptions **in your context**
 - Write animation code in `edit.js` inside a **scaffolded project directory** (e.g. `.frameforge-files/my-animation/edit.js`)
 - Read files inside `.frameforge-files/` to inspect rendered output
@@ -148,9 +148,15 @@ validate_storyboard({ storyboardPath: ".frameforge-files/my-animation/STORYBOARD
 
 **Step 4 — Write `edit.js`** (the one file you may write in an animation project):
 - Read `ANIMATION_GUIDE.md` in the project folder first
+- Also read `references/animation-patterns.md` — contains ClaudeAnimationBase 12fps boil, onetake continuous camera, and collage halftone patterns
+- Also read `references/motion-craft.md` — 10 hard motion craft rules (springs, 5-layer stack, exits faster, continuous life)
+- Also read `references/film-styles.md` — 12 cinematic styles (anamorphic, cyberpunk, anime, lofi, broadcast news...)
 - Every style must be a **pure function of `t`**
 - Use `layer('name').on(t => ({ ...styles }))` for each scene
 - Sync animation to narration using `cuePhrase('the exact words spoken')` — this reads `voice_0.captions.json` and returns the frame when those words start. **The build fails if the phrase isn't found**, so re-recording VO can never silently desync the animation.
+- **12fps organic boil** (ClaudeAnimationBase): `const step = Math.floor(lt * 12); const bx = Math.sin(seed * 19.37 + step * 2.41) * 2.4;` — never `Math.random()` inside render loop
+- **SFX cues** (earshot): `cue('whoosh', t, 0.8)` in edit.js — registered in `window.__cues` for render.mjs to read back during audio mix
+- **Onetake camera**: place all scenes on one 2.5D spatial canvas, spring-interpolate the camera between them instead of cutting
 
 **Step 5 — Pre-flight, then stills, then full render:**
 ```
@@ -167,14 +173,68 @@ render_animation({ projectDir: ".frameforge-files/my-animation/", mode: "full",
 - One `strip` per key motion or transition
 - One `crop` per story-carrying face or detail
 
-**Step 6 — Optional: hook variants**
+**Step 5b — Closed-Loop QA Fix Protocol (mandatory after full render)**
+
+After `full` render, run the quality gate:
+```
+render_animation({ projectDir: ".frameforge-files/my-animation/", mode: "quality" })
+```
+Returns `{ passed, overallScore, worstFrames: [{time, score, issues}], motionDelta }`.
+
+- **`passed: true`** → continue to Step 6.
+- **`passed: false`** → enter the fix loop (max 3 rounds):
+
+```
+Round N (repeat until passed or 3 rounds exhausted):
+  1. Read worstFrames[] — note timestamps and issue descriptions.
+  2. Open edit.js. Fix ONLY the code paths that affect those timestamps.
+     Common issues and fixes:
+       - "Blank frame"           → layer is returning opacity: 0 when it shouldn't; check lt bounds
+       - "Stuck motion"          → two frames have identical hashes; motion formula may be constant
+       - "Corner-confined"       → element x/y is outside safe zone; move to centre stage
+       - "Blown frame"           → background colour too bright; switch to #0c1116–#111827 range
+       - "Low contrast"          → scene is too dark; raise ambient layer brightness
+  3. Run: render_animation({ mode: "strip", timestamps: [t-0.5, t+0.5] })
+     for each failing timestamp to verify the fix visually.
+  4. Run: render_animation({ mode: "quality" }) again.
+  5. If passed: true → done. If still failing → next round.
+
+After 3 rounds without passing: stop, report worstFrames to user, do not re-render full film.
+```
+
+**Never re-render the full film to fix a single failing timestamp.** Use `strip` on the
+failing time range only. This is the Claude Code + Opus 5.5 closed-loop correction pattern:
+render → score worst 3 frames → patch edit.js → re-strip → re-score → ship.
+
+**Step 5c — Motion-blur pass (optional, high-quality reels)**
+
+For fast morphs or kinetic reveals that show ghost copies at standard render:
+```
+render_animation({ projectDir: "...", mode: "full", subframes: 6, audioPath: "..." })
+```
+`subframes: 6` = 180° shutter — renders 6 frames per output frame, blends them. Adds ~6× render
+time. Only needed when fast-moving elements look strobed. Standard renders use `subframes: 1`.
+
+**Step 6 — Model effort guide (Opus 5.5 / Claude Code)**
+
+| Stage | `effort` | Why |
+|-------|----------|-----|
+| Beat sheet + storyboard authorship | `xhigh` | New creative work — max reasoning |
+| First-time scene code authorship | `xhigh` | New composition, determinism critical |
+| Storyboard gate review / patch | `medium` | Analytical, not creative |
+| Strip-range patch (fix failing frames) | `medium` | Targeted surgical fix |
+| Encode-only / mux-only runs | `medium` | No creative decisions |
+
+`tool_choice` must always be `auto` — Opus 5.5 does not support forced tool use.
+
+**Step 7 — Optional: hook variants**
 
 For reels and Shorts, make 2–3 versions with different opening hooks:
 - Change only the first shot (0s–3s) in `edit.js`
 - `render_animation({ mode: "stills", timestamps: [0.0, 1.5, 3.0] })` to compare openings
 - Full render each variant, deliver as `hook_a.mp4`, `hook_b.mp4`, etc.
 
-**Step 7 — Optional: unattended / spend-capped batch**
+**Step 8 — Optional: unattended / spend-capped batch**
 ```
 // run from projectDir
 python scripts/video_job.py submit --spec spec.json --max-usd 2.00
@@ -184,14 +244,18 @@ python scripts/video_job.py result --id <jobId>
 ```
 Each step only starts if the running cost won't exceed `--max-usd`. Receipts go to `jobs/receipts.jsonl`.
 
-**Step 8 — Golden stills regression test (before any refactor)**
+**Step 9 — Golden stills regression test (before any refactor)**
 
-After the video passes QC, save the test stills:
+After the video passes QC, save the 4-keyframe golden baseline:
+```
+render_animation({ projectDir, mode: "golden", goldenSave: true })
+// → writes out/check/golden.json with SHA-256 hashes for 4 keyframes
 ```
-render_animation({ projectDir, mode: "storyboard" })  // 4 keyframes, file to out/storyboard.jpg
-// → copy out/storyboard.jpg to test/golden/storyboard.jpg
+Before future refactors, run the check:
+```
+render_animation({ projectDir, mode: "golden", goldenCheck: true })
+// → fails if any keyframe hash has drifted (refactor broke determinism)
 ```
-Before future refactors, re-run and compare. If pixels shift, the refactor broke determinism.
 
 > Requires one-time setup in the project directory: `npm install playwright && npx playwright install chromium`
 
@@ -210,7 +274,7 @@ get_job_status({ jobId })   // poll every 30s until status = "SUCCEEDED"
 
 ---
 
-## ALL 18 MCP TOOLS
+## ALL 28 MCP TOOLS
 
 **Primary — code-driven animation (no LLM key, no image gen API):**
 
@@ -236,6 +300,28 @@ get_job_status({ jobId })   // poll every 30s until status = "SUCCEEDED"
 | `generate_scene_image` | Generate one scene image |
 | `publish_video` | Deliver via file copy or HTTP webhook |
 
+**Media ingestion (yt-dlp & Whisper):**
+
+| Tool | What it does |
+|------|-------------|
+| `ingest_url` | Download video/audio from any web URL (YouTube, Vimeo, Twitter/X, TikTok, 1000+ sites) via yt-dlp |
+| `transcribe_media` | Transcribe speech with Whisper — word-level timestamps (NDJSON for `cuePhrase()`), SRT subtitles, pause detection |
+
+**Professional audio post-production:**
+
+| Tool | What it does |
+|------|-------------|
+| `mix_audio_pro` | 15+ year sound engineer chain: noise gate → 80Hz HPF → EQ → de-esser → compressor → room acoustics (5 profiles) → sidechain duck → stereo widen → 13-type SFX library (earshot) → two-pass EBU R128 loudnorm. Platform presets: youtube/podcast/broadcast/netflix/instagram. |
+
+**Editing & planning:**
+
+| Tool | What it does |
+|------|-------------|
+| `edit_video` | Autonomous local editor — cut, trim, speed-ramp, color-grade (24 presets incl. lemo-opuscar styles), reframe, captions, transitions (35+), audio mix |
+| `plan_video_edit` | Plan/Approve/Render workflow — generates `edit-plan.md` + `edit.json`. Styles: cinematic / fast_paced / documentary / vintage / cyberpunk / editorial_collage / anime_action / cinematic_anamorphic / broadcast_news / film_16mm / product_obsidian / retro_vhs_80s and more |
+| `preview_scene` | Render still frames of a scene HTML/code for visual inspection |
+| `verify_scene_quality` | Closed-loop QA gate: 1–10 score on 4 axes (content, exposure, layout, motion delta) |
+
 **Auto-research (needs a free LLM key):**
 
 | Tool | What it does |
@@ -245,6 +331,103 @@ get_job_status({ jobId })   // poll every 30s until status = "SUCCEEDED"
 | `queue_full_pipeline` | Queue a full pipeline run; returns `{ jobId }` |
 | `get_job_status` | Poll a queued job for status |
 
+**Upstream skills maintenance:**
+
+| Tool | What it does |
+|------|-------------|
+| `sync_upstream_skills` | Check & merge updates from 9 reference repos (HyperFrames, Earshot, Remotion, OneTake, lemo-opuscar, gbro-collage-broll, ClaudeAnimationBase, ffmpeg-skill). Makes GitHub API requests to fetch new commits. Returns `{ updatedRepos, perCategoryUpdates }` with `userImpact` and `capabilities[]` per changed repo. |
+| `check_upstream_updates` | Fast offline check — reads the local manifest without any network requests. Shows last sync timestamp, per-repo SHA, and which repos have been synced. Use this for a quick status check; use `sync_upstream_skills` to actually fetch new commits. |
+
+---
+
+## PROFESSIONAL AUDIO WORKFLOW
+
+### Whisper transcription → word-level caption sync
+
+```
+// Step 1: Generate TTS
+multi_voice_tts({ text: "Your narration.", outputPath: ".frameforge-files/voice_0.m4a" })
+
+// Step 2: Transcribe for exact word timestamps (requires: pip install openai-whisper)
+transcribe_media({
+  mediaPath: ".frameforge-files/voice_0.m4a",
+  model: "base",         // tiny|base|small|medium|large
+  format: "all",         // writes .ndjson (for captions()) + .srt + .json
+})
+// → returns: { outputs: { ndjson: "...", srt: "...", json: "..." }, pauses: [...] }
+
+// Step 3: Load in edit.js for word-sync captions
+// captions('audio/outline.txt');   ← use the ndjson output path
+// cuePhrase("your words here");    ← returns exact timestamp from transcript
+```
+
+### yt-dlp media ingestion
+
+```
+// Download YouTube video for B-roll
+ingest_url({ url: "https://youtube.com/watch?v=...", format: "video" })
+// → returns: { localPath: "...", duration: 45.2, width: 1920, height: 1080 }
+
+// Download audio-only (podcast, music)
+ingest_url({ url: "https://soundcloud.com/...", format: "audio" })
+// → returns: { localPath: "...", duration: 180.5 }
+
+// Then pass to any other tool
+edit_video({ clips: [{ video_path: localPath, ... }] })
+transcribe_media({ mediaPath: localPath, format: "srt" })
+```
+
+### Professional audio mix (15+ year sound engineer chain)
+
+```
+mix_audio_pro({
+  voicePath: ".frameforge-files/voice_0.m4a",
+  outputPath: ".frameforge-files/audio_pro.m4a",
+  musicPath: "/path/to/bg-music.mp3",   // optional — will be sidechain ducked
+  platform: "youtube",                   // youtube (-14) | podcast (-16) | broadcast (-23) | netflix (-27) | instagram
+  roomProfile: "cinematic",             // studio_dry | broadcast | cinematic | concert_hall | intimate
+  noiseGate: true,                      // remove breath noise between words (field recordings)
+  stereoWiden: true,                     // M/S expansion 1.4x on music layer
+  sfxCues: [                             // 13-type earshot procedural SFX library
+    { name: "whoosh",    time: 2.5,  volume: 0.8 },   // camera translation (40ms perceptual lead)
+    { name: "impact",   time: 8.0,  volume: 1.0 },   // title punch
+    { name: "pop",      time: 12.3, volume: 0.6 },   // badge reveal
+    { name: "riser",    time: 18.0, volume: 0.7 },   // build-up before climax
+    { name: "chime",    time: 25.5, volume: 0.5 },   // success / completion
+    { name: "deep_boom",time: 30.0, volume: 0.9 },   // cinematic reveal
+    { name: "sparkle",  time: 35.2, volume: 0.4 },   // aha moment
+    // Also: click | buzz | tick | swish | punch | transition
+  ],
+  // videoPath: ".frameforge-files/animation.mp4"  // optional: mux directly into video
+})
+// Returns: { outputPath, measuredLufs, measuredTp, platform, passed, chain: { noiseGate, hpf, presenceBoost,
+//           airShelf, deEsser, compressor, roomAcoustics, sidechainDuck, stereoWiden, sfxCues, masterBus } }
+```
+
+**Full signal chain** (in order):
+1. Noise gate (agate -60dBFS) — removes breath/room tone between words
+2. 80Hz HPF — removes proximity effect and desk rumble
+3. Presence +2dB@5kHz — adds speech intelligibility
+4. Air shelf +1.5dB@12kHz — adds breathiness/openness
+5. 3:1 compressor @ -20dBFS, 5ms attack, 50ms release
+6. De-esser 6.5kHz dynamic (-3dB) — removes "s/sh/ch" harshness
+7. Room acoustics (selected profile) — 0.1–0.55s RT60 reverb tail
+8. Sidechain ducking — music ducks -18dB when voice is active (40ms perceptual lead)
+9. Stereo widener — M/S extrastereo 1.4x on music layer (voice stays mono-center)
+10. SFX timeline — procedural 13-type library, millisecond-accurate placement
+11. Two-pass EBU R128 loudnorm — platform-aware LUFS target
+
+### Upstream skills auto-update
+
+Run this at the start of any session to get the latest motion craft rules, film styles,
+camera techniques, and audio presets from all 9 reference repositories:
+
+```
+sync_upstream_skills({})
+// → If repos have new commits: returns updatedRepos[] and a visible update notice
+// → Set SKILL_UPDATE_WEBHOOK_URL in .env for POST callback notifications
+```
+
 ---
 
 ## VOICE — VoxForge custom audio

package/README.md

@@ -4,14 +4,14 @@
 
 ### AI Video Production Engine for Any Agentic IDE
 
-**Any IDE. Any topic. Any style. 1080p videos from a single prompt.**
+**Any IDE. Any topic. Any style. Broadcast-quality videos from a single prompt.**
 
 [![npm](https://img.shields.io/npm/v/@amg555/frameforge-mcp.svg?label=npm)](https://www.npmjs.com/package/@amg555/frameforge-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
-[![Version](https://img.shields.io/badge/version-2.3.8-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-2.7.0-blue.svg)](CHANGELOG.md)
 [![MCP Spec](https://img.shields.io/badge/MCP-2024--11--05-blue.svg)](https://modelcontextprotocol.io/)
-[![Tests](https://img.shields.io/badge/tests-539%20passing-brightgreen.svg)](#testing)
+[![Tests](https://img.shields.io/badge/tests-636%20passing-brightgreen.svg)](#testing)
 
 </div>
 
@@ -19,6 +19,8 @@
 
 FrameForge is an MCP server your IDE agent calls to make videos. You (or your agent) write the scenes — FrameForge handles voice, images, FFmpeg compositing, and quality checking. Works in Bob, Cursor, Windsurf, Codex, opencode, Claude Code, and any MCP-capable IDE.
 
+**28 MCP tools.** Includes Whisper transcription, yt-dlp media ingestion, broadcast-grade audio post-production (EQ + de-esser + SFX synthesis + room acoustics), and auto-updating motion craft from 9 frontier video repositories.
+
 ---
 
 ## Zero-install quickstart (npx)
@@ -52,7 +54,23 @@ Add to your IDE's MCP config (works in Bob, Cursor, Windsurf, Codex, Claude Code
 }
 ```
 
-That's it. Your agent now has 19 video production & autonomous editing tools. FFmpeg and TTS run on your machine — no cloud render costs.
+That's it. Your agent now has 28 video production & autonomous editing tools. FFmpeg and TTS run on your machine — no cloud render costs.
+
+### Standalone CLI Commands (no IDE required)
+
+```bash
+# Ingest any web clip or audio via yt-dlp
+npx --package=@amg555/frameforge-mcp frameforge download "https://youtube.com/watch?v=..." --subtitles
+
+# Transcribe speech with word-level timestamps & SRT via Whisper
+npx --package=@amg555/frameforge-mcp frameforge transcribe ./narration.mp3 --format all
+
+# Sync upstream techniques from 9 frontier video repositories
+npx --package=@amg555/frameforge-mcp frameforge sync
+
+# Diagnostics and system check
+npx --package=@amg555/frameforge-mcp frameforge doctor
+```
 
 ---
 
@@ -174,7 +192,7 @@ Any combination of `image_path`, `video_path`, `audio_path` works — FrameForge
 
 ## Tools
 
-19 tools, grouped by what you're doing:
+28 tools, grouped by what you're doing:
 
 **Make a video from your own script (no LLM key)**
 
@@ -192,6 +210,20 @@ Any combination of `image_path`, `video_path`, `audio_path` works — FrameForge
 | `publish_video` | Deliver the finished video via file copy or HTTP webhook |
 | `external_platform_call` | Bridge to ElevenLabs, Runway, VoxForge, or local FFmpeg editor fallback |
 | `export_to_editor` | Bridge/import into DaVinci Resolve, Premiere Pro, After Effects, Remotion, or CapCut |
+| `plan_video_edit` | Plan/Approve/Render: analyze footage, generate `edit-plan.md` + `edit.json` with rationale per cut |
+
+**Media ingestion (yt-dlp & Whisper)**
+
+| Tool | What it does |
+|------|-------------|
+| `ingest_url` | Download video/audio from YouTube, Vimeo, Twitter/X, TikTok, and 1000+ sites via yt-dlp |
+| `transcribe_media` | Whisper transcription with word-level timestamps → NDJSON (for `cuePhrase()`), SRT, JSON |
+
+**Professional audio post-production**
+
+| Tool | What it does |
+|------|-------------|
+| `mix_audio_pro` | Broadcast-grade chain: HPF → EQ → de-esser → compressor → reverb → duck → stereo widen → SFX synthesis → two-pass EBU R128 |
 
 **Auto-research pipeline (needs a free LLM key)**
 
@@ -208,7 +240,16 @@ Any combination of `image_path`, `video_path`, `audio_path` works — FrameForge
 |------|-------------|
 | `scaffold_animation_project` | Create a project where every frame is a pure function of time `t` |
 | `validate_storyboard` | Check `STORYBOARD.md` against the 4-gate beat-sheet contract |
-| `render_animation` | Run the Playwright renderer: sheet / strip / storyboard / crop / full |
+| `render_animation` | Run the Playwright renderer: sheet / strip / storyboard / crop / full / quality / golden |
+| `preview_scene` | Render still frames of a scene HTML/code for visual inspection before full render |
+| `verify_scene_quality` | Closed-loop visual QA gate: 1–10 score on content, exposure, layout, and motion delta |
+
+**Upstream skills**
+
+| Tool | What it does |
+|------|-------------|
+| `sync_upstream_skills` | Fetch latest commits from 9 reference repos and update local manifest. Returns per-category update summary with `userImpact` and affected tools. |
+| `check_upstream_updates` | Fast offline read of local manifest — shows last sync time, per-repo SHA, and sync status without any network requests. |
 
 ---
 

package/output/harness_test_1794418727139/frames/f000000.jpg

@@ -0,0 +1 @@
+************************************************************************************************************************************************************************************************************************************************************************************************************

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@amg555/frameforge-mcp",
-  "version": "2.4.10",
-  "description": "FrameForge — AI video production engine for agentic IDEs. npx @amg555/frameforge-mcp. FFmpeg + TTS run on your machine. 23 MCP tools.",
+  "version": "2.7.0",
+  "description": "FrameForge — AI video production engine for agentic IDEs. npx @amg555/frameforge-mcp. FFmpeg + TTS on your machine. 28 MCP tools. Whisper, yt-dlp, broadcast-grade audio, 13-type SFX library, 24 film styles, ClaudeAnimationBase full guide, onetake 39-move library + OM motion primitives, HyperFrames beat-grid, earshot forge DSP, J/L-cut editing, lemo-opuscar TREATMENT.md, upstream auto-update changelog.",
   "publishConfig": {
     "access": "public"
   },
@@ -19,6 +19,7 @@
     "harness": "node src/harness/bin/harness.mjs",
     "harness:doctor": "node src/harness/bin/harness.mjs doctor",
     "harness:verify": "node src/harness/bin/harness.mjs verify",
+    "skills:sync": "node src/skills/sync-upstream.js",
     "setup": "node src/cli/setup-keys.js",
     "setup:check": "node src/cli/setup-keys.js --check",
     "doctor": "node src/cli/doctor.js",
@@ -31,7 +32,7 @@
     "start:local-render": "cross-env RENDER_MODE=full WORKER_PORT=3211 node src/worker/server-render-free.js",
     "db:migrate": "node scripts/db-migrate.js",
     "validate": "node scripts/deep-validate.js",
-    "test": "node --test src/pipeline/retry-policy.test.js src/pipeline/telemetry.test.js src/pipeline/artifact-manifest.test.js src/pipeline/artifact-retention.test.js src/pipeline/external-adapter.test.js src/workflows/publishing.test.js src/workflows/script.test.js src/workflows/ingest.test.js src/animation/animation-system.test.js src/fact-checker/review-gate.test.js src/fact-checker/checker.test.js src/utils/log-redaction.test.js src/worker/server-render-free.test.js src/worker/server.test.js src/mcp-server/server.test.js src/quality-gate/gate.test.js src/shorts-extractor/extractor.test.js src/audio-mixer/mixer.test.js src/video-renderer/scene-animator.test.js src/video-renderer/renderer.test.js src/video-editor/editor.test.js plugins/video-pipeline/skills/video-pipeline/assets/project/reel/engine.test.js src/harness/lib/pixels.test.js src/harness/lib/verify-purity.test.js src/harness/lib/verify-quality.test.js src/harness/harness.test.js src/integration.test.js",
+    "test": "node --test --test-concurrency=2 src/pipeline/retry-policy.test.js src/pipeline/telemetry.test.js src/pipeline/artifact-manifest.test.js src/pipeline/artifact-retention.test.js src/pipeline/external-adapter.test.js src/workflows/publishing.test.js src/workflows/script.test.js src/workflows/ingest.test.js src/animation/animation-system.test.js src/fact-checker/review-gate.test.js src/fact-checker/checker.test.js src/utils/log-redaction.test.js src/utils/media-downloader.test.js src/utils/transcribe.test.js src/worker/server-render-free.test.js src/worker/server.test.js src/mcp-server/server.test.js src/quality-gate/gate.test.js src/shorts-extractor/extractor.test.js src/audio-mixer/mixer.test.js src/video-renderer/scene-animator.test.js src/video-renderer/renderer.test.js src/video-editor/editor.test.js plugins/video-pipeline/skills/video-pipeline/assets/project/reel/engine.test.js src/harness/lib/pixels.test.js src/harness/lib/verify-purity.test.js src/harness/lib/verify-quality.test.js src/harness/harness.test.js src/integration.test.js",
     "lint": "echo 'No linter configured — add eslint for production'",
     "check-credentials": "node src/utils/log-redaction.js",
     "generate-assets": "node scripts/generate-initial-assets.js",