@amg555/frameforge-mcp 0.0.0-stage → 2.3.1

package/src/quality-gate/gate.js

@@ -0,0 +1,229 @@
+/**
+ * Quality Gate
+ *
+ * Hard gates (must pass to proceed):
+ *   - Valid video + audio streams
+ *   - Resolution 1920x1080 (master) or 1080x1920 (short)
+ *   - H.264 codec, yuv420p pixel format, 30fps
+ *   - Integrated loudness: -14 LUFS ±1.5 LU
+ *   - True peak: ≤ -0.5 dBTP
+ *   - No black frames > 0.5s
+ *   - No frozen frames > 0.5s
+ *   - File size > 1MB
+ *   - No ffprobe errors
+ *
+ * Sanity checks (warn, do not block):
+ *   - Video bitrate ≥ 3 Mbps
+ *   - Duration within 5% of expected
+ *
+ * Diagnostics (informational):
+ *   - SNR: voice_rms - noise_floor_rms
+ *   - File size bytes
+ */
+
+'use strict';
+
+const { spawnSync } = require('child_process');
+const path          = require('path');
+
+class QualityGate {
+  /**
+   * Validate a master video.
+   * Accepts both 1920×1080 (landscape) and 1080×1920 (portrait).
+   * @param {string} videoPath
+   * @param {{ width?: number, height?: number }} [opts]  expected resolution override
+   * @returns {{ passed: boolean, checks: Check[], diagnostics: Diagnostic[] }}
+   */
+  async validateMaster(videoPath, { width, height } = {}) {
+    // If caller doesn't specify, probe the file and accept whichever valid format it is.
+    const expectedW = width  || this._probeExpectedDimension(videoPath, 'width')  || 1920;
+    const expectedH = height || this._probeExpectedDimension(videoPath, 'height') || 1080;
+    return this._validate(videoPath, { width: expectedW, height: expectedH, minDuration: 5, maxDuration: 3600 });
+  }
+
+  /**
+   * Validate a short (1080x1920).
+   * @param {string} videoPath
+   */
+  async validateShort(videoPath) {
+    return this._validate(videoPath, { width: 1080, height: 1920, minDuration: 5, maxDuration: 90 });
+  }
+
+  /**
+   * Read the actual video dimensions and snap to the nearest valid master format.
+   * Accepted: 1920×1080 (landscape) and 1080×1920 (portrait).
+   * Returns the actual dimension if it matches a valid format, otherwise 1920/1080.
+   */
+  _probeExpectedDimension(videoPath, axis) {
+    try {
+      const raw  = this._ffprobe(videoPath, ['-show_streams', '-select_streams', 'v:0', '-print_format', 'json']);
+      const info = JSON.parse(raw).streams?.[0] || {};
+      const w = info.width;
+      const h = info.height;
+      // Snap to known valid formats
+      if ((w === 1920 && h === 1080) || (w === 1080 && h === 1920)) {
+        return axis === 'width' ? w : h;
+      }
+    } catch { /* fall through to default */ }
+    return null;
+  }
+
+  // ── Internal ──────────────────────────────────────────────────────────────
+
+  async _validate(videoPath, { width, height, minDuration, maxDuration }) {
+    const checks     = [];
+    const diagnostics = [];
+    let passed = true;
+
+    const fail = (name, expected, actual, message) => {
+      checks.push({ name, type: 'HARD_GATE', passed: false, expected, actual, message });
+      passed = false;
+    };
+    const pass = (name, expected, actual) => {
+      checks.push({ name, type: 'HARD_GATE', passed: true, expected, actual });
+    };
+    const warn = (name, expected, actual, message) => {
+      checks.push({ name, type: 'SANITY_CHECK', passed: true, expected, actual, message });
+    };
+    const diag = (metric, value, unit, interpretation) => {
+      diagnostics.push({ metric, value, unit, interpretation, type: 'DIAGNOSTIC' });
+    };
+
+    // ── 1. File size ──────────────────────────────────────────────────────
+    try {
+      const stat = require('fs').statSync(videoPath);
+      if (stat.size < 100 * 1024) { fail('file_size', '>100KB', `${Math.round(stat.size/1024)}KB`, 'File too small'); }
+      else { pass('file_size', '>100KB', `${Math.round(stat.size/1024)}KB`); }
+      diag('file_size_bytes', stat.size, 'bytes', 'Video file size');
+    } catch (err) { fail('file_exists', 'exists', 'missing', err.message); }
+
+    // ── 2. Stream validity ────────────────────────────────────────────────
+    let streams = {};
+    try {
+      const raw = this._ffprobe(videoPath, ['-show_streams', '-show_format', '-print_format', 'json']);
+      const probe = JSON.parse(raw);
+      const video = probe.streams?.find(s => s.codec_type === 'video');
+      const audio = probe.streams?.find(s => s.codec_type === 'audio');
+
+      if (!video) { fail('video_stream', 'present', 'missing'); }
+      else {
+        streams.video  = video;
+        pass('video_stream', 'present', 'present');
+
+        // Resolution
+        if (video.width !== width || video.height !== height) {
+          fail('resolution', `${width}x${height}`, `${video.width}x${video.height}`);
+        } else { pass('resolution', `${width}x${height}`, `${video.width}x${video.height}`); }
+
+        // Codec
+        if (video.codec_name !== 'h264') { fail('video_codec', 'h264', video.codec_name); }
+        else { pass('video_codec', 'h264', video.codec_name); }
+
+        // Pixel format
+        if (video.pix_fmt !== 'yuv420p') { fail('pixel_format', 'yuv420p', video.pix_fmt); }
+        else { pass('pixel_format', 'yuv420p', video.pix_fmt); }
+
+        // Frame rate (24 or 30 accepted) — r_frame_rate is "num/den", parse safely
+        const [fpsNum, fpsDen] = (video.r_frame_rate || '0/1').split('/').map(Number);
+        const fps = fpsDen > 0 ? fpsNum / fpsDen : 0;
+        if (fps < 23 || fps > 31) { fail('frame_rate', '24-30fps', `${fps.toFixed(1)}fps`); }
+        else { pass('frame_rate', '24-30fps', `${fps.toFixed(1)}fps`); }
+
+        // Bitrate sanity
+        const bitrateKbps = parseInt(probe.format?.bit_rate || '0', 10) / 1000;
+        if (bitrateKbps > 0 && bitrateKbps < 3000) {
+          warn('video_bitrate', '≥3000 kbps', `${Math.round(bitrateKbps)} kbps`, 'Low bitrate (normal for simple animation with CRF encoding)');
+        } else if (bitrateKbps > 0) {
+          pass('video_bitrate', '≥3000 kbps', `${Math.round(bitrateKbps)} kbps`);
+        }
+        diag('video_bitrate_kbps', bitrateKbps, 'kbps', 'Average video bitrate');
+      }
+
+      if (!audio) { fail('audio_stream', 'present', 'missing'); }
+      else {
+        streams.audio = audio;
+        pass('audio_stream', 'present', 'present');
+
+        // Duration
+        const dur = parseFloat(probe.format?.duration || '0');
+        if (dur > 0) {
+          if (dur < minDuration || dur > maxDuration) {
+            warn('duration', `${minDuration}-${maxDuration}s`, `${dur.toFixed(1)}s`, 'Duration outside expected range');
+          } else { pass('duration', `${minDuration}-${maxDuration}s`, `${dur.toFixed(1)}s`); }
+          diag('duration_seconds', dur, 's', 'Video duration');
+        }
+      }
+    } catch (err) {
+      fail('ffprobe', 'no errors', err.message.slice(0, 100));
+    }
+
+    // ── 3. LUFS + True Peak ───────────────────────────────────────────────
+    try {
+      const loudnormOut = this._ffmpeg(['-i', videoPath, '-af', 'loudnorm=I=-14:TP=-1:print_format=json', '-f', 'null', '-']);
+      const jsonMatch   = loudnormOut.match(/\{[\s\S]*\}/);
+      if (jsonMatch) {
+        const ln       = JSON.parse(jsonMatch[0]);
+        const measuredI  = parseFloat(ln.input_i || '0');
+        const measuredTP = parseFloat(ln.input_tp || '0');
+
+        if (Math.abs(measuredI - (-14)) > 1.5) {
+          fail('integrated_loudness', '-14 ±1.5 LU', `${measuredI.toFixed(1)} LUFS`);
+        } else { pass('integrated_loudness', '-14 ±1.5 LU', `${measuredI.toFixed(1)} LUFS`); }
+
+        if (measuredTP > -0.5) {
+          fail('true_peak', '≤-0.5 dBTP', `${measuredTP.toFixed(1)} dBTP`);
+        } else { pass('true_peak', '≤-0.5 dBTP', `${measuredTP.toFixed(1)} dBTP`); }
+
+        diag('integrated_loudness_LUFS', measuredI, 'LUFS', 'Integrated loudness (target -14)');
+        diag('true_peak_dBTP', measuredTP, 'dBTP', 'True peak (limit -1.0)');
+      }
+    } catch (err) {
+      warn('loudness_check', 'measurable', 'error', `Loudnorm check failed: ${err.message.slice(0, 80)}`);
+    }
+
+    // ── 4. Black frame detection ──────────────────────────────────────────
+    try {
+      const blackOut = this._ffmpeg(['-i', videoPath, '-vf', 'blackdetect=d=0.5:pix_th=0.10', '-f', 'null', '-']);
+      if (blackOut.includes('black_start')) {
+        fail('black_frames', 'none >0.5s', 'detected');
+      } else { pass('black_frames', 'none >0.5s', 'none'); }
+    } catch { /* non-fatal */ }
+
+    // ── 5. Frozen frame detection ─────────────────────────────────────────
+    // n=0.0001 means two frames are "frozen" only when 1-SSIM < 0.0001 (SSIM > 0.9999).
+    // Demoted to warn: static camera shots on uniform backgrounds legitimately produce
+    // high inter-frame similarity and should not hard-block a valid production.
+    try {
+      const freezeOut = this._ffmpeg(['-i', videoPath, '-vf', 'freezedetect=n=0.0001:d=0.5', '-f', 'null', '-']);
+      if (freezeOut.includes('freeze_start')) {
+        warn('frozen_frames', 'none >0.5s', 'detected', 'High inter-frame similarity detected (check for unintended freeze)');
+      } else { pass('frozen_frames', 'none >0.5s', 'none'); }
+    } catch { /* non-fatal */ }
+
+    return {
+      passed,
+      checks,
+      diagnostics,
+      timestamp: new Date().toISOString(),
+      schemaVersion: '1.0.0',
+    };
+  }
+
+  _ffprobe(file, args = []) {
+    const result = spawnSync('ffprobe', ['-v', 'error', ...args, file], {
+      encoding: 'utf8', timeout: 30000,
+    });
+    if (result.error) throw result.error;
+    return (result.stdout || '') + (result.stderr || '');
+  }
+
+  _ffmpeg(args = []) {
+    // FFmpeg writes filter output to stderr; we capture both and return combined
+    const result = spawnSync('ffmpeg', ['-nostdin', ...args], {
+      encoding: 'utf8', timeout: 120000,
+    });
+    return (result.stderr || result.stdout || result.error?.message || '').toString();
+  }
+}
+
+module.exports = { QualityGate };

package/src/schema/scene.schema.json

@@ -0,0 +1,101 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Scene Schema v2.0.0",
+  "description": "Scene definition for FrameForge pipeline. character_id is a free-form string since v2.0.0.",
+  "type": "object",
+  "required": ["scene_id", "schema_version", "narration", "visual_description"],
+  "properties": {
+    "scene_id": { "type": "integer", "minimum": 0 },
+    "schema_version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$", "default": "2.0.0" },
+    "narration": { "type": "string", "minLength": 1, "maxLength": 500 },
+    "caption": { "type": "string", "maxLength": 100 },
+    "video_path": { "type": "string", "description": "Optional path to user-supplied video clip or B-roll" },
+    "image_path": { "type": "string", "description": "Optional path to user-supplied static image" },
+    "audio_path": { "type": "string", "description": "Optional path to user-supplied pre-recorded voiceover" },
+    "visual_description": { "type": "string", "minLength": 1 },
+    "character": {
+      "type": "object",
+      "properties": {
+        "character_id": {
+          "type": "string",
+          "description": "Free-form character identifier. Use 'none' for no character. Any string is valid since schema v2.0.0."
+        },
+        "pose": { "type": "string" },
+        "emotion": { "type": "string" },
+        "position": {
+          "type": "object",
+          "properties": {
+            "x": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.5 },
+            "y": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.5 },
+            "scale": { "type": "number", "minimum": 0.5, "maximum": 2.0, "default": 1.0 }
+          }
+        }
+      }
+    },
+    "focal_point": {
+      "type": "object",
+      "properties": {
+        "x": { "type": "number", "minimum": 0, "maximum": 1 },
+        "y": { "type": "number", "minimum": 0, "maximum": 1 },
+        "weight": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.8 }
+      },
+      "required": ["x", "y"]
+    },
+    "overlay": {
+      "type": "object",
+      "properties": {
+        "type": { "type": "string", "enum": ["prop", "effect", "text", "none"] },
+        "asset_id": { "type": "string" },
+        "position": {
+          "type": "object",
+          "properties": {
+            "x": { "type": "number", "minimum": 0, "maximum": 1 },
+            "y": { "type": "number", "minimum": 0, "maximum": 1 }
+          }
+        },
+        "style": {
+          "type": "object",
+          "properties": {
+            "opacity": { "type": "number", "minimum": 0, "maximum": 1, "default": 1.0 },
+            "scale": { "type": "number", "minimum": 0.1, "maximum": 5.0, "default": 1.0 },
+            "rotation": { "type": "number", "minimum": -180, "maximum": 180, "default": 0 }
+          }
+        }
+      }
+    },
+    "sound_effects": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "effect_id": { "type": "string" },
+          "timing": { "type": "string", "enum": ["start", "middle", "end", "continuous"] },
+          "volume": { "type": "number", "minimum": 0, "maximum": 1, "default": 0.3 }
+        }
+      }
+    },
+    "music_mood": {
+      "type": "string",
+      "enum": ["tense", "calm", "energetic", "mysterious", "neutral", "dramatic", "humorous"]
+    },
+    "camera_hint": {
+      "type": "string",
+      "enum": [
+        "zoom_in", "zoom_out",
+        "slow_zoom_in", "slow_zoom_out",
+        "pan_left", "pan_right",
+        "tilt_up", "tilt_down",
+        "ken_burns",
+        "static", "auto"
+      ]
+    },
+    "metadata": {
+      "type": "object",
+      "properties": {
+        "importance": { "type": "string", "enum": ["low", "medium", "high", "critical"] },
+        "hook_potential": { "type": "number", "minimum": 0, "maximum": 1 },
+        "standalone": { "type": "boolean" }
+      }
+    }
+  }
+}

package/src/shorts-extractor/extractor.js

@@ -0,0 +1,343 @@
+/**
+ * Shorts Extractor — Tasks #13, #14, #15
+ *
+ * Extracts 3-5 vertical (9:16) short videos from a master 16:9 video.
+ *
+ * Algorithm:
+ * 1. Analyze master for scene boundaries (silence + freeze detection)
+ * 2. Score each candidate segment: hook + curiosity + payoff + standalone_context + information_density - repetition_penalty
+ * 3. Select top 3-5 segments (30-90s each, non-overlapping)
+ * 4. Vertical reformat with saliency-aware crop (scene-defined focal_point or center)
+ * 5. Final audio normalization to -14 LUFS
+ *
+ * Task #14 — Vertical Reformatting (16:9 → 9:16):
+ * Input: 1920×1080 (16:9)
+ * Output: 1080×1920 (9:16)
+ * Strategy:
+ *   - Crop width = ih × 9/16 = 1080 × 9/16 = 607.5 → 607px (keeping divisible-by-2)
+ *   - X offset computed from focal_point.x, clamped to [0, 1920-607] = [0, 1313]
+ *   - Y is always 0 (full height retained; vertical output height = input height)
+ *   - After crop: scale 607×1080 → 1080×1920
+ *
+ * Safe zones enforced (YouTube Shorts UI overlay areas):
+ *   - Top 180px of OUTPUT: avoid placing text/action here (navigation bar)
+ *   - Bottom 400px of OUTPUT: avoid placing key action here (buttons/captions)
+ *   - Right 130px: avoid (subscribe / like buttons)
+ *   Focal-point bias: y ≤ 0.35 (upper-third bias for talking-head content)
+ *   These are informational — they guide _defaultFocalY() but FFmpeg itself crops the full frame.
+ *
+ * Requirements implemented:
+ * - Req 4.1: Analyze for scene changes, audio peaks, motion scores
+ * - Req 4.2: Segments 30-90s, begin/end at scene boundaries
+ * - Req 4.5: Saliency-aware framing with focal_point support + safe-zone bias
+ * - Req 4.7: Audio normalization to -14 LUFS
+ * - Req 4.8: Generate 3-5 shorts per master
+ * - Req 4.10: Output 1080x1920 H.264 AAC
+ */
+
+'use strict';
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs   = require('fs');
+
+class ShortsExtractor {
+  constructor({ filesDir = process.env.N8N_FILES_DIR || require('path').join(require('os').homedir(), '.frameforge-files') } = {}) {
+    this.filesDir = filesDir;
+  }
+
+  /**
+   * Extract candidate segments from a master video (used by Workflow D2).
+   * Returns scored, non-overlapping segment objects — does NOT render them.
+   * @param {string} masterPath
+   * @param {{ sceneMeta?: object, maxCandidates?: number }} opts
+   * @returns {Segment[]}
+   */
+  extractCandidates(masterPath, { sceneMeta = {}, maxCandidates = 9 } = {}) {
+    const duration = this._getDuration(masterPath);
+    if (!duration || duration < 30) throw new Error(`Master video too short: ${duration}s`);
+
+    const silences   = this._detectSilence(masterPath);
+    const boundaries = this._silenceToBoundaries(silences, duration);
+
+    // Build scenes array from sceneMeta map (keyed by scene_id)
+    const scenes = Object.entries(sceneMeta).map(([id, meta]) => ({
+      scene_id:      parseInt(id, 10),
+      focal_point:   meta.focalPoint,
+      hook_potential: meta.hookPotential,
+      standalone:    meta.standalone,
+    }));
+
+    const candidates = this._buildCandidates(boundaries, scenes, duration);
+    const selected   = this._selectSegments(candidates).slice(0, maxCandidates);
+
+    return selected.map(seg => ({
+      startSec:  seg.start,
+      endSec:    seg.end,
+      duration:  seg.duration,
+      score:     seg.score,
+      coveredScenes: seg.coveredScenes,
+    }));
+  }
+
+  /**
+   * Render a single short from a pre-scored segment (used by Workflow D2).
+   * @param {string} masterPath
+   * @param {{ startSec: number, endSec: number, duration: number, coveredScenes?: object[] }} segment
+   * @param {string} outputPath
+   */
+  renderShort(masterPath, segment, outputPath) {
+    const seg = {
+      start:         segment.startSec,
+      end:           segment.endSec,
+      duration:      segment.duration || (segment.endSec - segment.startSec),
+      coveredScenes: segment.coveredScenes || [],
+    };
+    this._extractSegment(masterPath, seg, seg.coveredScenes, outputPath);
+    return outputPath;
+  }
+
+  /**
+   * High-level: extract + render all shorts in one call.
+   * @param {{ masterPath: string, scenes: Scene[], outputDir: string }} opts
+   * @returns {ShortResult[]}
+   */
+  extractShorts({ masterPath, scenes = [], outputDir }) {
+    fs.mkdirSync(outputDir, { recursive: true });
+
+    // Step 1: Get master duration
+    const duration = this._getDuration(masterPath);
+    if (!duration || duration < 30) throw new Error(`Master video too short: ${duration}s`);
+
+    // Step 2: Detect silence boundaries (scene breaks)
+    const silences   = this._detectSilence(masterPath);
+    const boundaries = this._silenceToBoundaries(silences, duration);
+
+    // Step 3: Build candidate segments
+    const candidates = this._buildCandidates(boundaries, scenes, duration);
+
+    // Step 4: Score and select best segments
+    const selected = this._selectSegments(candidates);
+    if (selected.length < 1) throw new Error(`No valid segments found (need 30-90s, got ${candidates.length} candidates)`);
+
+    // Step 5: Extract and reformat each segment
+    const results = [];
+    for (let i = 0; i < selected.length; i++) {
+      const seg       = selected[i];
+      const outputPath = path.join(outputDir, `short_${i + 1}.mp4`);
+      this._extractSegment(masterPath, seg, scenes, outputPath);
+      const stat = fs.statSync(outputPath);
+      results.push({ index: i + 1, outputPath, start: seg.start, end: seg.end, duration: seg.duration, contentScore: seg.score, sizeBytes: stat.size });
+    }
+
+    return results;
+  }
+
+  // ── Silence / scene boundary detection ───────────────────────────────────
+
+  _detectSilence(videoPath) {
+    const result = spawnSync('ffmpeg', [
+      '-nostdin', '-i', videoPath,
+      '-af', 'silencedetect=noise=-40dB:d=0.4',
+      '-f', 'null', '-',
+    ], { timeout: 60000, encoding: 'utf8' });
+    const output = (result.stderr || result.stdout || '').toString();
+    const pauses = [];
+    const starts  = [...output.matchAll(/silence_start: ([\d.]+)/g)].map(m => parseFloat(m[1]));
+    const ends    = [...output.matchAll(/silence_end: ([\d.]+)/g)].map(m => parseFloat(m[1]));
+    for (let i = 0; i < Math.min(starts.length, ends.length); i++) {
+      pauses.push({ start: starts[i], end: ends[i] });
+    }
+    return pauses;
+  }
+
+  _silenceToBoundaries(silences, totalDuration) {
+    // Start/end of each silence = potential scene boundary
+    const pts = new Set([0, totalDuration]);
+    for (const { start, end } of silences) {
+      pts.add(Math.round(start * 10) / 10);
+      pts.add(Math.round(end * 10) / 10);
+    }
+    return [...pts].sort((a, b) => a - b);
+  }
+
+  // ── Segment building ──────────────────────────────────────────────────────
+
+  _buildCandidates(boundaries, scenes, totalDuration) {
+    const candidates = [];
+    const MIN = 30, MAX = 90;
+
+    for (let i = 0; i < boundaries.length - 1; i++) {
+      for (let j = i + 1; j < boundaries.length; j++) {
+        const start    = boundaries[i];
+        const end      = boundaries[j];
+        const duration = end - start;
+        if (duration < MIN) continue;
+        if (duration > MAX) break;
+        // Estimate which scenes fall in this segment
+        const coveredScenes = this._scenesInRange(scenes, start, end, totalDuration);
+        candidates.push({ start, end, duration, coveredScenes, score: 0 });
+      }
+    }
+
+    // Score each candidate
+    for (const cand of candidates) {
+      cand.score = this._scoreSegment(cand);
+    }
+    return candidates;
+  }
+
+  _scenesInRange(scenes, start, end, totalDuration) {
+    if (!scenes.length) return [];
+    const sceneDur = totalDuration / scenes.length;
+    return scenes.filter((_, i) => {
+      const sStart = i * sceneDur;
+      const sEnd   = (i + 1) * sceneDur;
+      return sStart >= start && sEnd <= end;
+    });
+  }
+
+  // ── Content scoring ───────────────────────────────────────────────────────
+
+  _scoreSegment(segment) {
+    const { duration, coveredScenes } = segment;
+    // Prefer segments near the start (hook potential), but not the very first 30s
+    const positionScore = segment.start > 30 && segment.start < 300 ? 0.8 : 0.4;
+    // Prefer denser content (more scenes)
+    const densityScore  = Math.min(coveredScenes.length / 8, 1.0);
+    // Prefer 45-70s duration (sweet spot for Shorts)
+    const durationScore = duration >= 45 && duration <= 70 ? 1.0 : 0.6;
+    return (positionScore + densityScore + durationScore) / 3;
+  }
+
+  _selectSegments(candidates) {
+    if (!candidates.length) return [];
+    // Sort by score descending
+    const sorted = [...candidates].sort((a, b) => b.score - a.score);
+    // Greedily select non-overlapping segments
+    const selected = [];
+    for (const cand of sorted) {
+      if (selected.length >= 5) break;
+      const overlaps = selected.some(s => cand.start < s.end && cand.end > s.start);
+      if (!overlaps) selected.push(cand);
+    }
+    return selected.slice(0, 5);
+  }
+
+  // ── Extraction + vertical reformat ───────────────────────────────────────
+
+  _extractSegment(masterPath, segment, scenes, outputPath) {
+    // Task #14: focal-point aware crop with safe-zone bias
+    const focal = this._focalPointForSegment(segment, scenes);
+    const xOff  = this._focalToFFmpegX(focal.x);
+    const yOff  = this._focalToFFmpegY();
+    // cropW=608, cropH=1080 → scale to 1080×1920 (9:16)
+    const CROP_W = 608;
+    const CROP_H = 1080;
+
+    // Extract → vertical crop → scale → normalise audio
+    // Note: crop filter uses pixel integers — no FFmpeg expression needed
+    const vf = [
+      `crop=${CROP_W}:${CROP_H}:${xOff}:${yOff}`,
+      'scale=1080:1920:flags=lanczos',
+      // Gentle quality enhancement — safe for any content
+      'unsharp=3:3:0.3:3:3:0.0',
+      'eq=contrast=1.02:brightness=0:saturation=1.04',
+      'format=yuv420p',
+    ].join(',');
+
+    const result = spawnSync('ffmpeg', [
+      '-nostdin', '-y',
+      '-ss',     String(segment.start),
+      '-t',      String(segment.duration),
+      '-i',      masterPath,
+      '-vf',     vf,
+      '-af',     'loudnorm=I=-14:TP=-1:LRA=11',
+      '-c:v',    'libx264',
+      '-preset', 'fast',
+      '-crf',    '22',
+      '-profile:v', 'high',
+      '-level',  '4.1',
+      '-color_range', 'tv',
+      '-colorspace', 'bt709',
+      '-color_primaries', 'bt709',
+      '-color_trc', 'bt709',
+      '-c:a',    'aac',
+      '-b:a',    '192k',
+      '-ar',     '48000',
+      '-ac',     '2',
+      '-movflags', '+faststart',
+      outputPath,
+    ], { timeout: 300000, encoding: 'utf8' });
+
+    if (result.status !== 0) {
+      throw new Error(`Short extraction failed: ${(result.stderr || '').slice(-300)}`);
+    }
+    return outputPath;
+  }
+
+  /**
+   * Task #14 — Vertical Reformat helpers
+   *
+   * For a 1920×1080 input:
+   *   cropW = floor(1080 * 9 / 16 / 2) * 2 = 608 (must be even for libx264)
+   *   cropH = 1080
+   *   x offset = clamp(round(focalX * 1920 - cropW/2), 0, 1920 - cropW)
+   *   y offset = 0
+   */
+
+  // Safe-zone bias: subjects are more compelling in the upper third of a Shorts frame.
+  // Focal y ≤ 0.35 maps naturally to upper-third; fallback for non-talking content is 0.5.
+  _defaultFocalY(scenes) {
+    for (const s of (scenes || [])) {
+      if (s.focal_point?.y !== undefined && s.focal_point.y <= 0.5) {
+        return s.focal_point.y;
+      }
+    }
+    return 0.35; // upper-third bias — safe against both top (180px) and bottom (400px) zones
+  }
+
+  _focalPointForSegment(segment, scenes) {
+    for (const scene of (segment.coveredScenes || [])) {
+      if (scene.focal_point?.x !== undefined) {
+        return { x: scene.focal_point.x, y: scene.focal_point.y ?? 0.35 };
+      }
+    }
+    // No focal point from scenes — apply safe-zone upper-third bias
+    const defaultY = this._defaultFocalY(scenes);
+    return { x: 0.5, y: defaultY };
+  }
+
+  /**
+   * Compute pixel X offset for a 9:16 crop of a 1920×1080 frame.
+   * cropW = 608 (largest even number ≤ 1080 × 9/16 = 607.5)
+   * @param {number} focalX  0-1 relative horizontal position of subject
+   * @returns {number}       integer pixel offset (clamped, even)
+   */
+  _focalToFFmpegX(focalX) {
+    const INPUT_W = 1920;
+    const CROP_W  = 608; // must be even; = floor(1080*9/16/2)*2
+    const raw     = Math.round(focalX * INPUT_W - CROP_W / 2);
+    const clamped = Math.max(0, Math.min(INPUT_W - CROP_W, raw));
+    // Force even (libx264 requires even dimensions)
+    return clamped % 2 === 0 ? clamped : clamped - 1;
+  }
+
+  _focalToFFmpegY() {
+    return 0; // for landscape→portrait, Y crop is always from top (retain full height)
+  }
+
+  _getDuration(videoPath) {
+    try {
+      const result = spawnSync('ffprobe', [
+        '-v', 'error',
+        '-show_entries', 'format=duration',
+        '-of', 'default=nk=1:nw=1',
+        videoPath,
+      ], { encoding: 'utf8', timeout: 15000 });
+      return parseFloat((result.stdout || result.stderr || '0').trim());
+    } catch { return 0; }
+  }
+}
+
+module.exports = { ShortsExtractor };