@studiomeyer/mcp-video 1.0.0

package/src/tools/engine/text-overlay.ts

@@ -0,0 +1,143 @@
+/**
+ * Text overlay engine — animated titles, subtitles, watermarks
+ */
+
+import { execFile } from 'child_process';
+import * as fs from 'fs';
+import { logger } from '../../lib/logger.js';
+
+// ─── Types ──────────────────────────────────────────────────────────
+
+export type TextPosition = 'center' | 'top' | 'bottom' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+
+export interface TextOverlay {
+  /** Text to display */
+  text: string;
+  /** Position on screen (default: center) */
+  position?: TextPosition;
+  /** Font size (default: 48) */
+  fontSize?: number;
+  /** Font color (default: white) */
+  fontColor?: string;
+  /** Start time in seconds */
+  startTime: number;
+  /** End time in seconds */
+  endTime: number;
+  /** Fade in duration (default: 0.5s) */
+  fadeIn?: number;
+  /** Fade out duration (default: 0.5s) */
+  fadeOut?: number;
+  /** Background box behind text (default: false) */
+  showBackground?: boolean;
+  /** Background color (default: black@0.6) */
+  backgroundColor?: string;
+}
+
+// ─── Position Resolver ──────────────────────────────────────────────
+
+function resolvePosition(pos: TextPosition): { x: string; y: string } {
+  switch (pos) {
+    case 'top':          return { x: '(w-text_w)/2', y: 'h*0.08' };
+    case 'bottom':       return { x: '(w-text_w)/2', y: 'h*0.88' };
+    case 'top-left':     return { x: 'w*0.05',       y: 'h*0.05' };
+    case 'top-right':    return { x: 'w-text_w-w*0.05', y: 'h*0.05' };
+    case 'bottom-left':  return { x: 'w*0.05',       y: 'h-text_h-h*0.05' };
+    case 'bottom-right': return { x: 'w-text_w-w*0.05', y: 'h-text_h-h*0.05' };
+    default:             return { x: '(w-text_w)/2', y: '(h-text_h)/2' };
+  }
+}
+
+// ─── Filter Builder ─────────────────────────────────────────────────
+
+function buildDrawtextFilter(overlay: TextOverlay, fontPath: string): string {
+  const {
+    text,
+    position = 'center',
+    fontSize = 48,
+    fontColor = 'white',
+    startTime,
+    endTime,
+    fadeIn = 0.5,
+    fadeOut = 0.5,
+    showBackground = false,
+    backgroundColor = 'black@0.6',
+  } = overlay;
+
+  const { x, y } = resolvePosition(position);
+  const fadeInEnd = startTime + fadeIn;
+  const fadeOutStart = endTime - fadeOut;
+
+  // Escape for ffmpeg
+  const escaped = text.replace(/'/g, "\\\\'").replace(/:/g, '\\:');
+
+  // Alpha expression: fade in → hold → fade out
+  const alpha = `if(lt(t\\,${startTime})\\,0\\,if(lt(t\\,${fadeInEnd})\\,(t-${startTime})/${fadeIn}\\,if(lt(t\\,${fadeOutStart})\\,1\\,if(lt(t\\,${endTime})\\,(${endTime}-t)/${fadeOut}\\,0))))`;
+
+  let filter = `drawtext=text='${escaped}':fontfile='${fontPath}':fontsize=${fontSize}:fontcolor=${fontColor}:x=${x}:y=${y}:alpha='${alpha}':enable='between(t,${startTime},${endTime})'`;
+
+  if (showBackground) {
+    filter += `:box=1:boxcolor=${backgroundColor}:boxborderw=12`;
+  }
+
+  return filter;
+}
+
+// ─── Main Function ──────────────────────────────────────────────────
+
+export async function addTextOverlays(
+  inputPath: string,
+  outputPath: string,
+  overlays: TextOverlay[]
+): Promise<string> {
+  if (!fs.existsSync(inputPath)) throw new Error(`Input not found: ${inputPath}`);
+  if (overlays.length === 0) throw new Error('No overlays provided');
+
+  const fontPath = findFont();
+  const filters = overlays.map((o) => buildDrawtextFilter(o, fontPath)).join(',');
+
+  logger.info(`Adding ${overlays.length} text overlay(s)`);
+
+  const args = [
+    '-y',
+    '-i', inputPath,
+    '-vf', filters,
+    '-c:a', 'copy',
+    '-c:v', 'libx264',
+    '-crf', '18',
+    '-pix_fmt', 'yuv420p',
+    '-movflags', '+faststart',
+    outputPath,
+  ];
+
+  await runFfmpeg(args);
+
+  logger.info(`Text overlays added: ${outputPath}`);
+  return outputPath;
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────
+
+function findFont(): string {
+  const candidates = [
+    '/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf',
+    '/usr/share/fonts/truetype/liberation/LiberationSans-Bold.ttf',
+    '/usr/share/fonts/truetype/ubuntu/Ubuntu-Bold.ttf',
+  ];
+  for (const f of candidates) {
+    if (fs.existsSync(f)) return f;
+  }
+  return '/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf';
+}
+
+function runFfmpeg(args: string[]): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile('ffmpeg', args, { maxBuffer: 50 * 1024 * 1024 }, (error, stdout, stderr) => {
+      if (error) {
+        logger.error(`ffmpeg failed: ${stderr}`);
+        reject(new Error(`ffmpeg failed: ${stderr || error.message}`));
+        return;
+      }
+      resolve(stdout);
+    });
+  });
+}

package/src/tools/engine/tts.ts

@@ -0,0 +1,284 @@
+/**
+ * Text-to-Speech Engine
+ * Primary: ElevenLabs (best quality, multilingual)
+ * Fallback: OpenAI TTS (reliable, already integrated)
+ *
+ * No extra npm dependencies — ElevenLabs uses native fetch,
+ * OpenAI uses the already-installed openai package
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { logger } from '../../lib/logger.js';
+import { getMediaDuration } from './audio.js';
+
+// ─── Types ──────────────────────────────────────────────────────────
+
+export type TTSProvider = 'elevenlabs' | 'openai';
+
+export type ElevenLabsModel =
+  | 'eleven_multilingual_v2'
+  | 'eleven_turbo_v2_5'
+  | 'eleven_flash_v2_5';
+
+export type ElevenLabsVoice =
+  | 'rachel' | 'sarah' | 'emily' | 'charlotte' | 'alice' | 'matilda' | 'lily'
+  | 'brian' | 'adam' | 'daniel' | 'josh' | 'james' | 'liam' | 'chris' | 'george';
+
+export type OpenAIVoice =
+  | 'alloy' | 'ash' | 'coral' | 'echo' | 'fable'
+  | 'nova' | 'onyx' | 'sage' | 'shimmer';
+
+export type OpenAIModel = 'tts-1' | 'tts-1-hd';
+
+export interface TTSConfig {
+  /** Text to speak */
+  text: string;
+  /** Output path for the audio file */
+  outputPath: string;
+  /** TTS provider (default: elevenlabs) */
+  provider?: TTSProvider;
+  /** Language code (default: en) */
+  language?: string;
+  /** Speaking speed (default: 1.0) */
+  speed?: number;
+
+  // ElevenLabs specific
+  /** ElevenLabs voice name (default: adam) */
+  elevenLabsVoice?: ElevenLabsVoice | string;
+  /** ElevenLabs model (default: eleven_multilingual_v2) */
+  elevenLabsModel?: ElevenLabsModel;
+  /** Voice stability 0-1 (default: 0.5) */
+  stability?: number;
+  /** Voice similarity 0-1 (default: 0.75) */
+  similarityBoost?: number;
+
+  // OpenAI specific
+  /** OpenAI voice (default: onyx) */
+  openaiVoice?: OpenAIVoice;
+  /** OpenAI model (default: tts-1-hd) */
+  openaiModel?: OpenAIModel;
+}
+
+export interface TTSResult {
+  success: boolean;
+  audioPath: string;
+  provider: TTSProvider;
+  duration: number;
+  sizeBytes: number;
+  sizeMB: string;
+  text: string;
+  language: string;
+}
+
+// ─── ElevenLabs Voice IDs ───────────────────────────────────────────
+
+const ELEVENLABS_VOICE_IDS: Record<string, string> = {
+  rachel: '21m00Tcm4TlvDq8ikWAM',
+  sarah: 'EXAVITQu4vr4xnSDxMaL',
+  emily: 'LcfcDJNUP1GQjkzn1xUU',
+  charlotte: 'XB0fDUnXU5powFXDhCwa',
+  alice: 'Xb7hH8MSUJpSbSDYk0k2',
+  matilda: 'XrExE9yKIg1WjnnlVkGX',
+  lily: 'pFZP5JQG7iQjIQuC4Bku',
+  brian: 'nPczCjzI2devNBz1zQrb',
+  adam: 'pNInz6obpgDQGcFmaJgB',
+  daniel: 'onwK4e9ZLuTAKqWW03F9',
+  josh: 'TxGEqnHWrfWFTfGW9XjX',
+  james: 'ZQe5CZNOzWyzPSCn5a3c',
+  liam: 'TX3LPaxmHKxFdv7VOQHJ',
+  chris: 'iP95p4xoKVk53GoZ742B',
+  george: 'JBFqnCBsd6RMkjVDRZzb',
+};
+
+// ─── Main TTS Function ─────────────────────────────────────────────
+
+export async function generateSpeech(config: TTSConfig): Promise<TTSResult> {
+  const {
+    text,
+    outputPath,
+    provider = getDefaultProvider(),
+    language = 'en',
+  } = config;
+
+  // Ensure output dir exists
+  const outDir = path.dirname(outputPath);
+  if (!fs.existsSync(outDir)) fs.mkdirSync(outDir, { recursive: true });
+
+  // Ensure .mp3 extension
+  const finalPath = outputPath.endsWith('.mp3') ? outputPath : `${outputPath}.mp3`;
+
+  logger.info(`Generating speech (${provider}, ${language}, ${text.length} chars)`);
+
+  let audioPath: string;
+
+  try {
+    if (provider === 'elevenlabs') {
+      audioPath = await elevenLabsTTS(config, finalPath);
+    } else {
+      audioPath = await openaiTTS(config, finalPath);
+    }
+  } catch (error) {
+    // Fallback: try the other provider
+    const fallback = provider === 'elevenlabs' ? 'openai' : 'elevenlabs';
+    const msg = error instanceof Error ? error.message : String(error);
+    logger.warn(`${provider} TTS failed (${msg}), falling back to ${fallback}`);
+
+    try {
+      if (fallback === 'elevenlabs') {
+        audioPath = await elevenLabsTTS(config, finalPath);
+      } else {
+        audioPath = await openaiTTS(config, finalPath);
+      }
+    } catch (fallbackError) {
+      const fbMsg = fallbackError instanceof Error ? fallbackError.message : String(fallbackError);
+      throw new Error(`Both TTS providers failed. ${provider}: ${msg}, ${fallback}: ${fbMsg}`);
+    }
+  }
+
+  // Get audio stats
+  const stats = fs.statSync(audioPath);
+  let duration = 0;
+  try {
+    duration = await getMediaDuration(audioPath);
+  } catch {
+    // ffprobe might not parse the file
+  }
+
+  logger.info(`Speech generated: ${audioPath} (${duration.toFixed(1)}s, ${(stats.size / 1024).toFixed(0)} KB)`);
+
+  return {
+    success: true,
+    audioPath,
+    provider,
+    duration,
+    sizeBytes: stats.size,
+    sizeMB: (stats.size / 1024 / 1024).toFixed(2),
+    text,
+    language,
+  };
+}
+
+// ─── ElevenLabs Implementation ──────────────────────────────────────
+
+async function elevenLabsTTS(config: TTSConfig, outputPath: string): Promise<string> {
+  const apiKey = process.env.ELEVENLABS_API_KEY;
+  if (!apiKey) throw new Error('ELEVENLABS_API_KEY environment variable not set');
+
+  const voiceName = config.elevenLabsVoice ?? 'adam';
+  const voiceId = ELEVENLABS_VOICE_IDS[voiceName] ?? voiceName; // Allow raw voice IDs
+  const model = config.elevenLabsModel ?? 'eleven_multilingual_v2';
+  const language = config.language ?? 'en';
+
+  const url = `https://api.elevenlabs.io/v1/text-to-speech/${voiceId}?output_format=mp3_44100_128`;
+
+  const body: Record<string, unknown> = {
+    text: config.text,
+    model_id: model,
+    language_code: language,
+    voice_settings: {
+      stability: config.stability ?? 0.5,
+      similarity_boost: config.similarityBoost ?? 0.75,
+      style: 0.0,
+      speed: config.speed ?? 1.0,
+      use_speaker_boost: true,
+    },
+  };
+
+  logger.info(`ElevenLabs TTS: voice=${voiceName}, model=${model}, lang=${language}`);
+
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'xi-api-key': apiKey,
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`ElevenLabs API ${response.status}: ${errorText}`);
+  }
+
+  const arrayBuffer = await response.arrayBuffer();
+  fs.writeFileSync(outputPath, Buffer.from(arrayBuffer));
+
+  return outputPath;
+}
+
+// ─── OpenAI Implementation ──────────────────────────────────────────
+
+async function openaiTTS(config: TTSConfig, outputPath: string): Promise<string> {
+  const apiKey = process.env.OPENAI_API_KEY;
+  if (!apiKey) throw new Error('OPENAI_API_KEY environment variable not set');
+
+  const voice = config.openaiVoice ?? 'onyx';
+  const model = config.openaiModel ?? 'tts-1-hd';
+  const speed = config.speed ?? 1.0;
+
+  logger.info(`OpenAI TTS: voice=${voice}, model=${model}, speed=${speed}`);
+
+  // Use fetch directly (avoid OpenAI package version issues)
+  const response = await fetch('https://api.openai.com/v1/audio/speech', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify({
+      model,
+      voice,
+      input: config.text,
+      response_format: 'mp3',
+      speed,
+    }),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`OpenAI TTS API ${response.status}: ${errorText}`);
+  }
+
+  const arrayBuffer = await response.arrayBuffer();
+  fs.writeFileSync(outputPath, Buffer.from(arrayBuffer));
+
+  return outputPath;
+}
+
+// ─── List ElevenLabs Voices ─────────────────────────────────────────
+
+export async function listElevenLabsVoices(): Promise<Array<{
+  voice_id: string;
+  name: string;
+  category: string;
+  language: string;
+}>> {
+  const apiKey = process.env.ELEVENLABS_API_KEY;
+  if (!apiKey) throw new Error('ELEVENLABS_API_KEY environment variable not set');
+
+  const response = await fetch('https://api.elevenlabs.io/v1/voices', {
+    headers: { 'xi-api-key': apiKey },
+  });
+
+  if (!response.ok) throw new Error(`ElevenLabs API ${response.status}`);
+
+  const data = await response.json() as {
+    voices: Array<{ voice_id: string; name: string; category: string; labels?: Record<string, string> }>;
+  };
+
+  return data.voices.map((v) => ({
+    voice_id: v.voice_id,
+    name: v.name,
+    category: v.category,
+    language: v.labels?.language ?? 'unknown',
+  }));
+}
+
+// ─── Helper ─────────────────────────────────────────────────────────
+
+function getDefaultProvider(): TTSProvider {
+  if (process.env.ELEVENLABS_API_KEY) return 'elevenlabs';
+  if (process.env.OPENAI_API_KEY) return 'openai';
+  throw new Error('No TTS API key found. Set ELEVENLABS_API_KEY or OPENAI_API_KEY.');
+}

package/src/tools/engine/types.ts

@@ -0,0 +1,191 @@
+/**
+ * Type definitions for the Cinema Video Engine
+ */
+
+// ─── Viewport Presets ───────────────────────────────────────────────
+export const VIEWPORTS = {
+  desktop: { width: 1920, height: 1080 },
+  'desktop-4k': { width: 3840, height: 2160 },
+  tablet: { width: 768, height: 1024 },
+  'tablet-landscape': { width: 1024, height: 768 },
+  mobile: { width: 393, height: 852 },
+  'mobile-landscape': { width: 852, height: 393 },
+} as const;
+
+export type ViewportPreset = keyof typeof VIEWPORTS;
+
+export interface ViewportConfig {
+  width: number;
+  height: number;
+}
+
+// ─── Easing ─────────────────────────────────────────────────────────
+export type EasingName =
+  | 'linear'
+  | 'easeInQuad'
+  | 'easeOutQuad'
+  | 'easeInOutQuad'
+  | 'easeInCubic'
+  | 'easeOutCubic'
+  | 'easeInOutCubic'
+  | 'easeInQuart'
+  | 'easeOutQuart'
+  | 'easeInOutQuart'
+  | 'easeInQuint'
+  | 'easeOutQuint'
+  | 'easeInOutQuint'
+  | 'easeInOutSine'
+  | 'cinematic'        // slow start + cruise + slow end
+  | 'showcase';        // dramatic slow start, smooth cruise, elegant stop
+
+// ─── Scenes ─────────────────────────────────────────────────────────
+export interface SceneBase {
+  type: string;
+}
+
+export interface ScrollScene extends SceneBase {
+  type: 'scroll';
+  /** Target: 'bottom', 'top', pixel number, or CSS selector */
+  to: 'bottom' | 'top' | number | string;
+  /** Duration of the scroll in seconds */
+  duration: number;
+  /** Easing curve name (default: easeInOutCubic) */
+  easing?: EasingName;
+}
+
+export interface PauseScene extends SceneBase {
+  type: 'pause';
+  /** Duration in seconds */
+  duration: number;
+}
+
+export interface HoverScene extends SceneBase {
+  type: 'hover';
+  /** CSS selector of element to hover */
+  selector: string;
+  /** How long to hold the hover (seconds) */
+  duration: number;
+  /** Move cursor smoothly to element (default: true) */
+  animateCursor?: boolean;
+}
+
+export interface ClickScene extends SceneBase {
+  type: 'click';
+  /** CSS selector of element to click */
+  selector: string;
+  /** Wait strategy after click */
+  waitFor?: 'networkidle' | 'load' | number;
+  /** Pause after navigation (seconds, default: 1) */
+  pauseAfter?: number;
+}
+
+export interface TypeScene extends SceneBase {
+  type: 'type';
+  /** CSS selector of input field */
+  selector: string;
+  /** Text to type */
+  text: string;
+  /** Delay between keystrokes in ms (default: 80) */
+  delay?: number;
+}
+
+export interface WaitScene extends SceneBase {
+  type: 'wait';
+  /** CSS selector to wait for */
+  selector: string;
+  /** Max wait time in ms (default: 5000) */
+  timeout?: number;
+}
+
+export type Scene =
+  | ScrollScene
+  | PauseScene
+  | HoverScene
+  | ClickScene
+  | TypeScene
+  | WaitScene;
+
+// ─── Cursor Config ──────────────────────────────────────────────────
+export interface CursorConfig {
+  /** Show a visible cursor in the video (default: true) */
+  enabled: boolean;
+  /** Cursor style */
+  style?: 'dot' | 'arrow' | 'pointer' | 'custom';
+  /** Cursor color (CSS color string) */
+  color?: string;
+  /** Cursor size in px (default: 20) */
+  size?: number;
+  /** Show click animation (default: true) */
+  clickAnimation?: boolean;
+}
+
+// ─── Encoding Config ────────────────────────────────────────────────
+export type VideoCodec = 'h264' | 'h265' | 'vp9';
+export type VideoFormat = 'mp4' | 'webm';
+
+export interface EncodingConfig {
+  /** Video codec (default: h264) */
+  codec?: VideoCodec;
+  /** Output format (default: mp4) */
+  format?: VideoFormat;
+  /** Constant Rate Factor — quality (0=lossless, 51=worst). Default: 18 */
+  crf?: number;
+  /** Encoding preset (default: slow for best quality) */
+  preset?: 'ultrafast' | 'fast' | 'medium' | 'slow' | 'veryslow';
+  /** Frames per second (default: 60) */
+  fps?: number;
+}
+
+// ─── Main Recording Config ──────────────────────────────────────────
+export interface RecordingConfig {
+  /** URL to record */
+  url: string;
+  /** Output file path (without extension — auto-determined) */
+  outputPath: string;
+  /** Viewport preset or custom dimensions */
+  viewport?: ViewportPreset | ViewportConfig;
+  /** Frames per second (default: 60) */
+  fps?: number;
+  /** Scene definitions — if empty, does a default full-page scroll */
+  scenes?: Scene[];
+  /** Cursor configuration */
+  cursor?: CursorConfig;
+  /** Video encoding settings */
+  encoding?: EncodingConfig;
+  /** Dismiss cookie banners and overlays (default: true) */
+  dismissOverlays?: boolean;
+  /** Pre-scroll to trigger lazy loading (default: true) */
+  preloadContent?: boolean;
+  /** Device scale factor for retina (default: 1) */
+  deviceScaleFactor?: number;
+  /** Dark mode (default: false) */
+  darkMode?: boolean;
+  /** Custom user agent */
+  userAgent?: string;
+  /** Disable smooth scroll CSS to prevent double-easing (default: true) */
+  disableSmoothScroll?: boolean;
+}
+
+// ─── Recording Result ───────────────────────────────────────────────
+export interface RecordingResult {
+  success: boolean;
+  video: {
+    path: string;
+    format: string;
+    codec: string;
+    fps: number;
+    duration: number;
+    totalFrames: number;
+    resolution: { width: number; height: number };
+    sizeBytes: number;
+    sizeMB: string;
+  };
+  thumbnail?: {
+    path: string;
+    width: number;
+    height: number;
+  };
+  scenes: number;
+  url: string;
+  captureTime: string;
+}