@amg555/frameforge-mcp 0.0.0-stage → 2.3.0

package/src/audio-mixer/mixer.js

@@ -0,0 +1,187 @@
+/**
+ * Audio Mixer
+ *
+ * Professional audio mixing with sidechain ducking.
+ * Voice track compresses to -20dB, music ducks by 15dB when voice is active.
+ * Final output: -14 LUFS ± 0.5 LU, true peak ≤ -1 dBTP.
+ *
+ * Requirements implemented:
+ * - Req 5.1: Voice compression ratio 3:1, threshold -20dBFS, attack 5ms, release 50ms
+ * - Req 5.2: Music attenuation 15dB within 200ms when voice detected
+ * - Req 5.3: Music restore within 1s when voice ends
+ * - Req 5.4: Normalize final to -14 LUFS ±0.5 LU
+ * - Req 5.6: High-pass 80Hz + low-pass 8000Hz on music track
+ * - Req 5.7: Peak below -1 dBFS across all tracks
+ */
+
+'use strict';
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+const os   = require('os');
+const fs   = require('fs');
+
+const DEFAULT_FILES_DIR = process.env.N8N_FILES_DIR || path.join(os.homedir(), '.frameforge-files');
+
+class AudioMixer {
+  constructor({ filesDir = DEFAULT_FILES_DIR } = {}) {
+    this.filesDir = filesDir;
+  }
+
+  /**
+   * Mix voice track with background music using sidechain ducking.
+   * @param {{ voicePath: string, musicPath: string|null, outputPath: string }} opts
+   * @returns {string} outputPath
+   */
+  mixWithDucking({ voicePath, musicPath = null, outputPath }) {
+    if (!musicPath || !fs.existsSync(musicPath) || fs.statSync(musicPath).size < 5000) {
+      // No music — just normalise voice
+      return this._normaliseVoice(voicePath, outputPath);
+    }
+    return this._sidechainMix(voicePath, musicPath, outputPath);
+  }
+
+  /**
+   * Apply ducking + normalization to an assembled video.
+   * Replaces the audio track in-place (creates new file).
+   * @param {{ videoPath: string, musicPath?: string, outputPath: string }} opts
+   */
+  mixVideo({ videoPath, musicPath = null, outputPath }) {
+    if (!musicPath || !fs.existsSync(musicPath)) {
+      // Normalise existing audio track
+      return this._normaliseVideo(videoPath, outputPath);
+    }
+    return this._videoWithDucking(videoPath, musicPath, outputPath);
+  }
+
+  // ── Private ───────────────────────────────────────────────────────────────
+
+  _sidechainMix(voicePath, musicPath, outputPath) {
+    // Voice: compress → sidechain trigger
+    // Music: highpass 80Hz + lowpass 8000Hz → sidechaincompress (duck on voice)
+    // Mix: loudnorm -14 LUFS
+    const filterComplex = [
+      '[0:a]acompressor=ratio=3:threshold=-20dB:attack=5:release=50[voice_comp]',
+      '[1:a]highpass=f=80,lowpass=f=8000[music_filtered]',
+      '[voice_comp][music_filtered]sidechaincompress=threshold=0.003:ratio=20:attack=0.2:release=1:makeup=2[mixed]',
+      '[mixed]loudnorm=I=-14:TP=-1:LRA=11[out]',
+    ].join(';');
+
+    const result = spawnSync('ffmpeg', [
+      '-nostdin', '-y',
+      '-i', voicePath,
+      '-i', musicPath,
+      '-filter_complex', filterComplex,
+      '-map', '[out]',
+      '-ar', '48000', '-ac', '2', '-c:a', 'aac', '-b:a', '192k',
+      outputPath,
+    ], { timeout: 120000, encoding: 'utf8' });
+
+    if (result.status !== 0) {
+      throw new Error(`Audio ducking failed: ${(result.stderr || '').slice(-300)}`);
+    }
+    return outputPath;
+  }
+
+  _videoWithDucking(videoPath, musicPath, outputPath) {
+    // Measure the video duration upfront so we can use explicit -t instead of -shortest.
+    // -shortest causes FFmpeg to hang or silently trim audio on subtitle streams and on
+    // some sidechaincompress filter graphs where the shorter stream signals EOF late.
+    const videoDur = this._getVideoDuration(videoPath);
+
+    const filterComplex = [
+      '[0:a]acompressor=ratio=3:threshold=-20dB:attack=5:release=50[voice_comp]',
+      '[1:a]aformat=sample_rates=48000:channel_layouts=stereo,highpass=f=80,lowpass=f=8000,volume=0.15[music_filtered]',
+      '[voice_comp][music_filtered]sidechaincompress=threshold=0.003:ratio=20:attack=0.2:release=1:makeup=2[mixed]',
+      '[mixed]loudnorm=I=-14:TP=-1:LRA=11[audio_out]',
+    ].join(';');
+
+    const result = spawnSync('ffmpeg', [
+      '-nostdin', '-y',
+      '-i', videoPath,          // input 0: video with voice
+      '-stream_loop', '-1',
+      '-i', musicPath,          // input 1: music (loop to fill)
+      '-filter_complex', filterComplex,
+      '-map', '0:v',
+      '-map', '[audio_out]',
+      '-c:v', 'copy',           // no re-encode of video
+      '-c:a', 'aac', '-b:a', '192k', '-ar', '48000', '-ac', '2',
+      // Use explicit -t instead of -shortest to prevent hang/trim on subtitle streams.
+      // videoDur measured by ffprobe; fallback to omitting -t if measurement failed.
+      ...(videoDur > 0 ? ['-t', String(videoDur)] : []),
+      '-movflags', '+faststart',
+      outputPath,
+    ], { timeout: 300000, encoding: 'utf8' });
+
+    if (result.status !== 0) {
+      throw new Error(`Video ducking failed: ${(result.stderr || '').slice(-300)}`);
+    }
+    return outputPath;
+  }
+
+  /** Measure total duration of a video file via ffprobe. Returns 0 on failure. */
+  _getVideoDuration(videoPath) {
+    try {
+      const result = spawnSync('ffprobe', [
+        '-v', 'error',
+        '-show_entries', 'format=duration',
+        '-of', 'default=nk=1:nw=1',
+        videoPath,
+      ], { encoding: 'utf8', timeout: 15000 });
+      const parsed = parseFloat((result.stdout || '').trim());
+      return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+    } catch { return 0; }
+  }
+
+  _normaliseVoice(voicePath, outputPath) {
+    const result = spawnSync('ffmpeg', [
+      '-nostdin', '-y',
+      '-i', voicePath,
+      '-af', 'loudnorm=I=-14:TP=-1:LRA=11',
+      '-ar', '48000', '-ac', '2', '-c:a', 'aac', '-b:a', '192k',
+      outputPath,
+    ], { timeout: 60000, encoding: 'utf8' });
+    if (result.status !== 0) throw new Error(`Voice normalise failed: ${(result.stderr || '').slice(-200)}`);
+    return outputPath;
+  }
+
+  _normaliseVideo(videoPath, outputPath) {
+    // -vf copy is not valid FFmpeg; use explicit stream maps instead
+    const result = spawnSync('ffmpeg', [
+      '-nostdin', '-y',
+      '-i', videoPath,
+      '-map', '0:v', '-map', '0:a',
+      '-af', 'loudnorm=I=-14:TP=-1:LRA=11',
+      '-c:v', 'copy',
+      '-c:a', 'aac', '-b:a', '192k',
+      '-movflags', '+faststart',
+      outputPath,
+    ], { timeout: 300000, encoding: 'utf8' });
+    if (result.status !== 0) throw new Error(`Video normalise failed: ${(result.stderr || '').slice(-200)}`);
+    return outputPath;
+  }
+
+  /**
+   * Detect pauses in an audio file (for caption sync).
+   * Returns array of { start, end } in seconds.
+   */
+  detectPauses(audioPath, { noiseTolerance = '-40dB', minPause = 0.3 } = {}) {
+    try {
+      const result = spawnSync('ffmpeg', [
+        '-nostdin', '-i', audioPath,
+        '-af', `silencedetect=noise=${noiseTolerance}:d=${minPause}`,
+        '-f', 'null', '-',
+      ], { timeout: 30000, 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], duration: ends[i] - starts[i] });
+      }
+      return pauses;
+    } catch { return []; }
+  }
+}
+
+module.exports = { AudioMixer };

package/src/cli/doctor.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+// Load keys from ~/.frameforge/config.json before any env checks
+require('../config/load-config').loadConfig();
+/**
+ * FrameForge System Doctor — Pre-flight Environment Diagnostics
+ *
+ * Verifies all required and optional runtime dependencies for running
+ * FrameForge locally on Windows, macOS, or Linux.
+ *
+ * Run: npm run doctor (or: node src/cli/doctor.js)
+ */
+
+'use strict';
+
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const COLORS = {
+  reset: '\x1b[0m',
+  green: '\x1b[32m',
+  red:   '\x1b[31m',
+  yellow:'\x1b[33m',
+  cyan:  '\x1b[36m',
+  bold:  '\x1b[1m',
+};
+
+function pass(name, detail = '') {
+  console.log(`  ${COLORS.green}✔${COLORS.reset} ${COLORS.bold}${name}${COLORS.reset} ${COLORS.cyan}${detail}${COLORS.reset}`);
+}
+
+function warn(name, detail = '', fix = '') {
+  console.log(`  ${COLORS.yellow}⚠${COLORS.reset} ${COLORS.bold}${name}${COLORS.reset} ${detail}`);
+  if (fix) console.log(`    ${COLORS.yellow}↳ Fix:${COLORS.reset} ${fix}`);
+}
+
+function fail(name, detail = '', fix = '') {
+  console.log(`  ${COLORS.red}✖${COLORS.reset} ${COLORS.bold}${name}${COLORS.reset} ${detail}`);
+  if (fix) console.log(`    ${COLORS.red}↳ Fix:${COLORS.reset} ${fix}`);
+}
+
+console.log(`\n${COLORS.bold}${COLORS.cyan}=== FrameForge System Doctor ===${COLORS.reset}\n`);
+
+let hasCriticalFailure = false;
+
+// 1. Node.js Version
+const nodeVer = process.version;
+const major = parseInt(nodeVer.replace('v', '').split('.')[0], 10);
+if (major >= 18) {
+  pass('Node.js', `${nodeVer} (>= 18 required)`);
+} else {
+  fail('Node.js', `${nodeVer} is outdated`, 'Install Node.js 18 or 20+ from https://nodejs.org');
+  hasCriticalFailure = true;
+}
+
+// 2. FFmpeg
+const ffmpeg = spawnSync('ffmpeg', ['-version'], { encoding: 'utf8', timeout: 5000, shell: process.platform === 'win32' });
+if (ffmpeg.status === 0) {
+  const firstLine = (ffmpeg.stdout || '').split('\n')[0] || '';
+  pass('FFmpeg', firstLine.slice(0, 45));
+} else {
+  fail('FFmpeg', 'Not found in PATH', 'Download FFmpeg from https://ffmpeg.org/download.html and add bin/ to PATH');
+  hasCriticalFailure = true;
+}
+
+// 3. FFprobe
+const ffprobe = spawnSync('ffprobe', ['-version'], { encoding: 'utf8', timeout: 5000, shell: process.platform === 'win32' });
+if (ffprobe.status === 0) {
+  const firstLine = (ffprobe.stdout || '').split('\n')[0] || '';
+  pass('FFprobe', firstLine.slice(0, 45));
+} else {
+  fail('FFprobe', 'Not found in PATH', 'FFprobe usually installs alongside FFmpeg. Ensure both are in PATH');
+  hasCriticalFailure = true;
+}
+
+// 4. Voice Engine (edge-tts or Cloud API)
+const edgeTts = spawnSync('edge-tts', ['--version'], { encoding: 'utf8', timeout: 5000, shell: process.platform === 'win32' });
+const hasCloudTts = Boolean(process.env.ELEVENLABS_API_KEY || process.env.AZURE_SPEECH_KEY || process.env.OPENAI_API_KEY || process.env.CUSTOM_TTS_URL);
+
+if (edgeTts.status === 0) {
+  pass('Voice Engine', `edge-tts CLI available (${(edgeTts.stdout || '').trim()})`);
+} else if (hasCloudTts) {
+  pass('Voice Engine', 'Cloud TTS API configured via environment');
+} else {
+  warn(
+    'Voice Engine',
+    'Neither edge-tts CLI nor cloud TTS API detected',
+    'Run "pip install edge-tts" for free offline voiceover, or set OPENAI_API_KEY / ELEVENLABS_API_KEY in .env'
+  );
+}
+
+// 5. System Font (for video subtitles/captions)
+const FONT_CANDIDATES = [
+  'C:\\Windows\\Fonts\\arialbd.ttf',
+  'C:\\Windows\\Fonts\\calibrib.ttf',
+  'C:\\Windows\\Fonts\\segoeui.ttf',
+  '/System/Library/Fonts/Helvetica.ttc',
+  '/Library/Fonts/Arial Bold.ttf',
+  '/usr/share/fonts/truetype/liberation/LiberationSans-Bold.ttf',
+  '/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf',
+  '/usr/share/fonts/liberation/LiberationSans-Bold.ttf',
+];
+
+const foundFont = process.env.FFMPEG_FONT || FONT_CANDIDATES.find(f => fs.existsSync(f));
+if (foundFont) {
+  pass('System Font', foundFont);
+} else {
+  warn(
+    'System Font',
+    'No standard bold font file found',
+    'Subtitles may be skipped. Set FFMPEG_FONT=/path/to/font.ttf or install Liberation/Arial font'
+  );
+}
+
+// 6. LLM Provider (Research & Scriptwriting)
+const llmProvider = (process.env.PROVIDER_LLM || 'groq').toLowerCase();
+
+// Built-in key env vars — any unknown provider can also supply LLM_BASE_URL or WEBHOOK_LLM_URL
+const builtinKeyMap = {
+  groq:       process.env.GROQ_API_KEY,
+  openrouter: process.env.OPENROUTER_API_KEY,
+  anthropic:  process.env.ANTHROPIC_API_KEY,
+  gemini:     process.env.GEMINI_API_KEY,
+  mistral:    process.env.MISTRAL_API_KEY,
+  together:   process.env.TOGETHER_API_KEY,
+  cerebras:   process.env.CEREBRAS_API_KEY,
+  openai:     process.env.OPENAI_API_KEY,
+  ollama:     'local',
+  webhook:    process.env.WEBHOOK_LLM_URL,
+};
+
+const hasLLMKey = Boolean(
+  builtinKeyMap[llmProvider] ||  // known built-in provider has a key
+  process.env.LLM_BASE_URL    ||  // custom OpenAI-compatible endpoint
+  process.env.WEBHOOK_LLM_URL ||  // webhook provider
+  llmProvider === 'ollama'        // ollama needs no key
+);
+
+const customModel    = process.env.LLM_MODEL    ? ` model=${process.env.LLM_MODEL}`    : '';
+const customEndpoint = process.env.LLM_BASE_URL ? ` endpoint=${process.env.LLM_BASE_URL}` : '';
+
+if (hasLLMKey) {
+  pass('LLM Provider', `${llmProvider}${customModel}${customEndpoint}`);
+} else {
+  warn(
+    'LLM Provider',
+    `PROVIDER_LLM=${llmProvider} but no API key found`,
+    `Run: npm run setup   OR   set the required key in .env\n` +
+    `    Free options: GROQ_API_KEY (groq) · GEMINI_API_KEY (gemini) · CEREBRAS_API_KEY (cerebras)\n` +
+    `    Any OpenAI-compatible API: set LLM_BASE_URL + PROVIDER_LLM=webhook`
+  );
+}
+
+// 7. Output directory check
+const baseDir = process.env.N8N_FILES_DIR || path.join(process.cwd(), '.frameforge-files');
+try {
+  fs.mkdirSync(baseDir, { recursive: true });
+  fs.accessSync(baseDir, fs.constants.W_OK);
+  pass('Working Dir', baseDir);
+} catch (err) {
+  fail('Working Dir', `Cannot write to ${baseDir}: ${err.message}`, 'Check disk permissions or set N8N_FILES_DIR');
+  hasCriticalFailure = true;
+}
+
+console.log('\n----------------------------------------');
+if (hasCriticalFailure) {
+  console.log(`${COLORS.red}${COLORS.bold}✖ FrameForge has missing critical dependencies above.${COLORS.reset}\n`);
+  process.exit(1);
+} else {
+  console.log(`${COLORS.green}${COLORS.bold}✔ FrameForge is ready for local video production!${COLORS.reset}\n`);
+  console.log(`Quick run:\n  ${COLORS.cyan}npm run make -- --topic "Why Did Ancient Humans Wear Clothes?"${COLORS.reset}\n`);
+  process.exit(0);
+}