codeplay-common 4.3.5 → 4.3.6

package/files/generate-ai-promo-video.js

@@ -0,0 +1,1525 @@
+// Generate an English app promo video from the original Android capture.
+// Usage: node generate-ai-promo-video.js
+// Optional: node generate-ai-promo-video.js --input path/to/source.mp4 --output path/to/output.mp4
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { createHash } = require('node:crypto');
+const { spawnSync } = require('node:child_process');
+
+const projectDirectory = __dirname;
+const capacitorConfigPath = path.join(projectDirectory, 'capacitor.config.json');
+const capacitorConfig = JSON.parse(fs.readFileSync(capacitorConfigPath, 'utf8'));
+const appName = String(capacitorConfig.appName || '').trim();
+const appUniqueId = String(capacitorConfig.android?.APP_UNIQUE_ID ?? '').trim();
+const packageId = String(capacitorConfig.appId || '').trim();
+
+if (!appName) throw new Error('capacitor.config.json is missing appName.');
+if (!appUniqueId) throw new Error('capacitor.config.json is missing android.APP_UNIQUE_ID.');
+if (!packageId) throw new Error('capacitor.config.json is missing appId.');
+
+const appFilePrefix = `${appUniqueId}. ${sanitizeFileNamePart(appName)}`;
+const playStoreDownloadUrl = `https://play.google.com/store/apps/details?id=${encodeURIComponent(packageId)}`;
+const sourceVideoDirectory = path.join(projectDirectory, 'Auto-Screenshot', 'Video', 'Output');
+const outputVideoDirectory = path.join(projectDirectory, 'Auto-AI-Video');
+const spatialXrDirectory = path.join(outputVideoDirectory, 'Google-Play-XR-Spatial');
+const spatialXrVideoPath = path.join(
+  spatialXrDirectory,
+  `${appFilePrefix}-spatial-xr-3d-sbs-lr-3840x1080.mp4`,
+);
+const iconPath = path.join(projectDirectory, 'src', 'assets', 'icons', 'icon-512.webp');
+const temporaryDirectory = path.join(projectDirectory, 'agent-temp', 'ai-promo-video');
+const captionPath = path.join(temporaryDirectory, `${appUniqueId}-promo-english.ass`);
+const narrationTrackPath = path.join(temporaryDirectory, `${appUniqueId}-promo-narration.wav`);
+const voicePreviewDirectory = path.join(projectDirectory, 'Auto-AI-Video', 'Voice-Samples');
+const promoCopyCachePath = path.join(
+  projectDirectory,
+  'Auto-AI-Video',
+  `${appFilePrefix}-promo-copy.json`,
+);
+const analysisFrameDirectory = path.join(temporaryDirectory, 'ai-analysis');
+const promoCopySchemaPath = path.join(temporaryDirectory, 'promo-copy-schema.json');
+const promoCopyResultPath = path.join(temporaryDirectory, 'promo-copy-result.json');
+const ffmpegFallbackDirectory = 'W:\\Tools\\ffmpeg\\bin';
+const sceneCount = 7;
+const minimumSourceDuration = 12;
+const minimumPreferredPromoDuration = 24;
+const maximumPromoDuration = 40;
+let expectedDuration = 34;
+let editSegments = [];
+let sceneWindows = [];
+const thumbnailTime = 2;
+const thumbnailWidth = 3840;
+const thumbnailHeight = 2160;
+const maximumThumbnailBytes = 2 * 1024 * 1024;
+const spatialEyeWidth = 1920;
+const spatialEyeHeight = 1080;
+const spatialOutputWidth = spatialEyeWidth * 2;
+const spatialOutputHeight = spatialEyeHeight;
+const promoCopySchemaVersion = 3;
+const promoCopySchema = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['footer_keywords', 'scenes', 'youtube'],
+  properties: {
+    footer_keywords: {
+      type: 'array',
+      minItems: 3,
+      maxItems: 3,
+      items: { type: 'string' },
+    },
+    scenes: {
+      type: 'array',
+      minItems: sceneCount,
+      maxItems: sceneCount,
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['kicker', 'title_line_1', 'title_line_2', 'body', 'narration'],
+        properties: {
+          kicker: { type: 'string' },
+          title_line_1: { type: 'string' },
+          title_line_2: { type: 'string' },
+          body: { type: 'string' },
+          narration: { type: 'string' },
+        },
+      },
+    },
+    youtube: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['title', 'description'],
+      properties: {
+        title: { type: 'string' },
+        description: { type: 'string' },
+      },
+    },
+  },
+};
+const neuralVoiceCatalog = {
+  aria: {
+    name: 'en-US-AriaNeural',
+    label: 'Aria — US English, confident and polished',
+  },
+  ava: {
+    name: 'en-US-AvaMultilingualNeural',
+    label: 'Ava — US English, expressive and conversational',
+  },
+  emma: {
+    name: 'en-US-EmmaMultilingualNeural',
+    label: 'Emma — US English, cheerful and clear',
+  },
+  jenny: {
+    name: 'en-US-JennyNeural',
+    label: 'Jenny — US English, friendly and warm',
+  },
+  michelle: {
+    name: 'en-US-MichelleNeural',
+    label: 'Michelle — US English, pleasant and composed',
+  },
+  sonia: {
+    name: 'en-GB-SoniaNeural',
+    label: 'Sonia — UK English, polished and professional',
+  },
+  libby: {
+    name: 'en-GB-LibbyNeural',
+    label: 'Libby — UK English, friendly and positive',
+  },
+  neerja: {
+    name: 'en-IN-NeerjaExpressiveNeural',
+    label: 'Neerja — Indian English, expressive and natural',
+  },
+  natasha: {
+    name: 'en-AU-NatashaNeural',
+    label: 'Natasha — Australian English, friendly and positive',
+  },
+  clara: {
+    name: 'en-CA-ClaraNeural',
+    label: 'Clara — Canadian English, clear and friendly',
+  },
+};
+function sanitizeFileNamePart(value) {
+  return String(value)
+    .trim()
+    .replace(/[<>:"/\\|?*\u0000-\u001F]/g, '_')
+    .replace(/[. ]+$/g, '') || 'App';
+}
+
+function findVideos(directory) {
+  if (!fs.existsSync(directory)) return [];
+  return fs.readdirSync(directory, { withFileTypes: true })
+    .flatMap((entry) => {
+      const entryPath = path.join(directory, entry.name);
+      if (entry.isDirectory()) return findVideos(entryPath);
+      return entry.isFile() && /\.mp4$/i.test(entry.name) ? [entryPath] : [];
+    })
+    .sort((left, right) => left.localeCompare(right));
+}
+
+function isExcludedBatchSource(inputPath) {
+  const relativePath = path.relative(sourceVideoDirectory, inputPath);
+  const platformDirectory = relativePath.split(path.sep)[0].toLowerCase();
+  return platformDirectory === 'samsung';
+}
+
+function roundTimelineValue(value) {
+  return Math.round(value * 100) / 100;
+}
+
+function mapOutputTimeToSource(outputTime) {
+  let remainingTime = outputTime;
+  for (const segment of editSegments) {
+    const segmentDuration = segment.end - segment.start;
+    if (remainingTime <= segmentDuration) {
+      return Math.min(segment.end - 0.05, segment.start + remainingTime);
+    }
+    remainingTime -= segmentDuration;
+  }
+  return editSegments.at(-1).end - 0.05;
+}
+
+function configurePromoTimeline(sourceDuration) {
+  if (!Number.isFinite(sourceDuration) || sourceDuration < minimumSourceDuration) {
+    throw new Error(
+      `The shortest source video must be at least ${minimumSourceDuration} seconds.`,
+    );
+  }
+
+  const introTrim = sourceDuration >= 20 ? Math.min(2, sourceDuration * 0.04) : 0;
+  const usableDuration = sourceDuration - introTrim;
+  const preferredDuration = Math.max(
+    minimumPreferredPromoDuration,
+    Math.round(sourceDuration * 0.6),
+  );
+  expectedDuration = roundTimelineValue(Math.min(maximumPromoDuration, usableDuration, preferredDuration));
+
+  const tailDuration = expectedDuration >= minimumPreferredPromoDuration
+    ? roundTimelineValue(Math.min(7, expectedDuration * 0.2))
+    : 0;
+  const mainDuration = roundTimelineValue(expectedDuration - tailDuration);
+  const tailStart = roundTimelineValue(sourceDuration - tailDuration);
+  const mainEnd = roundTimelineValue(introTrim + mainDuration);
+
+  editSegments = tailDuration > 0 && mainEnd + 0.5 < tailStart
+    ? [
+      { start: roundTimelineValue(introTrim), end: mainEnd },
+      { start: tailStart, end: roundTimelineValue(sourceDuration) },
+    ]
+    : [{
+      start: roundTimelineValue(introTrim),
+      end: roundTimelineValue(introTrim + expectedDuration),
+    }];
+
+  sceneWindows = Array.from({ length: sceneCount }, (_, index) => {
+    const start = roundTimelineValue((expectedDuration * index) / sceneCount);
+    const end = index === sceneCount - 1
+      ? expectedDuration
+      : roundTimelineValue((expectedDuration * (index + 1)) / sceneCount);
+    const sceneDuration = end - start;
+    return {
+      start,
+      end,
+      sourceTime: roundTimelineValue(mapOutputTimeToSource(start + (sceneDuration / 2))),
+      maxNarrationWords: Math.max(7, Math.floor(sceneDuration * 2.15)),
+    };
+  });
+
+  console.log(
+    `Adaptive promo timeline: ${expectedDuration}s from ${sourceDuration.toFixed(2)}s source; `
+      + `${editSegments.length} edit segment${editSegments.length === 1 ? '' : 's'}.`,
+  );
+}
+
+function escapeAssText(value) {
+  return String(value)
+    .replace(/\\/g, '\\\\')
+    .replace(/{/g, '\\{')
+    .replace(/}/g, '\\}')
+    .replace(/\r?\n/g, '\\N');
+}
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    encoding: 'utf8',
+    windowsHide: true,
+    stdio: options.inherit ? 'inherit' : 'pipe',
+    input: options.input,
+    maxBuffer: 10 * 1024 * 1024,
+  });
+
+  if (result.error) {
+    if (result.error.code === 'ENOENT') {
+      throw new Error(`${command} was not found.`);
+    }
+    throw result.error;
+  }
+
+  if (result.status !== 0) {
+    throw new Error(
+      String(result.stderr || result.stdout || `${command} exited with code ${result.status}.`).trim(),
+    );
+  }
+
+  return String(result.stdout || '').trim();
+}
+
+function commandExists(command) {
+  const result = spawnSync(command, ['-version'], {
+    encoding: 'utf8',
+    windowsHide: true,
+  });
+  return !result.error && result.status === 0;
+}
+
+function getExecutable(command) {
+  if (commandExists(command)) return command;
+
+  const fallbackPath = path.join(ffmpegFallbackDirectory, `${command}.exe`);
+  return fs.existsSync(fallbackPath) ? fallbackPath : '';
+}
+
+function parseArguments() {
+  const args = process.argv.slice(2);
+  const options = {
+    aiModel: '',
+    aiProvider: 'auto',
+    copyOnly: false,
+    input: '',
+    listVoices: false,
+    output: '',
+    previewVoices: false,
+    refreshAiCopy: false,
+    spatialXrOnly: false,
+    thumbnailsOnly: false,
+    voice: 'sonia',
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (argument === '--input') {
+      options.input = path.resolve(args[index + 1] || '');
+      index += 1;
+    } else if (argument === '--output') {
+      options.output = path.resolve(args[index + 1] || '');
+      index += 1;
+    } else if (argument === '--voice') {
+      options.voice = String(args[index + 1] || '').trim();
+      index += 1;
+    } else if (argument === '--ai-provider') {
+      options.aiProvider = String(args[index + 1] || '').trim().toLowerCase();
+      index += 1;
+    } else if (argument === '--ai-model') {
+      options.aiModel = String(args[index + 1] || '').trim();
+      index += 1;
+    } else if (argument === '--refresh-ai-copy') {
+      options.refreshAiCopy = true;
+    } else if (argument === '--copy-only') {
+      options.copyOnly = true;
+    } else if (argument === '--thumbnails-only') {
+      options.thumbnailsOnly = true;
+    } else if (argument === '--spatial-xr-only') {
+      options.spatialXrOnly = true;
+    } else if (argument === '--list-voices') {
+      options.listVoices = true;
+    } else if (argument === '--preview-voices') {
+      options.previewVoices = true;
+    } else if (argument === '--help' || argument === '-h') {
+      console.log(`Generate an adaptive promotional video for ${appName}.`);
+      console.log('');
+      console.log('Usage:');
+      console.log('  node generate-ai-promo-video.js');
+      console.log('  node generate-ai-promo-video.js --input source.mp4 --output promo.mp4');
+      console.log('  node generate-ai-promo-video.js --voice aria');
+      console.log('  node generate-ai-promo-video.js --refresh-ai-copy');
+      console.log('  node generate-ai-promo-video.js --copy-only');
+      console.log('  node generate-ai-promo-video.js --thumbnails-only');
+      console.log('  node generate-ai-promo-video.js --spatial-xr-only');
+      console.log('  node generate-ai-promo-video.js --ai-provider auto|codex|openai');
+      console.log('  node generate-ai-promo-video.js --ai-model MODEL_NAME');
+      console.log('  node generate-ai-promo-video.js --list-voices');
+      console.log('  node generate-ai-promo-video.js --preview-voices');
+      console.log('');
+      console.log(
+        `Without --input, every MP4 under ${sourceVideoDirectory} except Samsung is processed.`,
+      );
+      process.exit(0);
+    } else {
+      throw new Error(`Unknown argument: ${argument}`);
+    }
+  }
+
+  if (!['auto', 'codex', 'openai'].includes(options.aiProvider)) {
+    throw new Error('--ai-provider must be auto, codex, or openai.');
+  }
+  if (options.output && !options.input) {
+    throw new Error('--output can only be used together with --input.');
+  }
+
+  return options;
+}
+
+function getPythonExecutable() {
+  for (const candidate of ['py', 'python']) {
+    const result = spawnSync(candidate, ['-m', 'edge_tts', '--version'], {
+      encoding: 'utf8',
+      windowsHide: true,
+    });
+    if (!result.error && result.status === 0) return candidate;
+  }
+  return '';
+}
+
+function printVoiceCatalog() {
+  console.log('Natural female neural voices:');
+  console.log('');
+  for (const [alias, voice] of Object.entries(neuralVoiceCatalog)) {
+    console.log(`  ${alias.padEnd(10)} ${voice.label} (${voice.name})`);
+  }
+  console.log('');
+  console.log('Use an alias above or any full Edge TTS neural voice name with --voice.');
+}
+
+function resolveVoice(input) {
+  const alias = String(input || '').trim().toLowerCase();
+  return neuralVoiceCatalog[alias] || {
+    name: String(input || '').trim(),
+    label: String(input || '').trim(),
+  };
+}
+
+function escapeFilterPath(filePath) {
+  return filePath
+    .replace(/\\/g, '/')
+    .replace(':', '\\:')
+    .replace(/'/g, "\\'");
+}
+
+function readTextIfPresent(filePath, maximumLength = 12000) {
+  if (!fs.existsSync(filePath)) return '';
+  return fs.readFileSync(filePath, 'utf8').slice(0, maximumLength);
+}
+
+function readJsonIfPresent(filePath) {
+  try {
+    return JSON.parse(readTextIfPresent(filePath, 50000));
+  } catch {
+    return {};
+  }
+}
+
+function extractHtmlMetadata(html) {
+  const title = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1] || '';
+  const description = html.match(
+    /<meta[^>]+name=["']description["'][^>]+content=["']([^"']*)["']/i,
+  )?.[1] || html.match(
+    /<meta[^>]+content=["']([^"']*)["'][^>]+name=["']description["']/i,
+  )?.[1] || '';
+  return { title: title.trim(), description: description.trim() };
+}
+
+function stripMarkup(value) {
+  return String(value)
+    .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, ' ')
+    .replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, ' ')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/\{\{[^}]+\}\}/g, ' ')
+    .replace(/&[a-zA-Z#0-9]+;/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function collectAppContext() {
+  const manifestCandidates = [
+    path.join(projectDirectory, 'src', 'manifest.webmanifest'),
+    path.join(projectDirectory, 'public', 'manifest.webmanifest'),
+    path.join(projectDirectory, 'manifest.webmanifest'),
+  ];
+  const manifest = readJsonIfPresent(manifestCandidates.find((candidate) => fs.existsSync(candidate)) || '');
+  const htmlMetadata = extractHtmlMetadata(
+    readTextIfPresent(path.join(projectDirectory, 'src', 'index.html'), 30000),
+  );
+  const pageDirectory = path.join(projectDirectory, 'src', 'pages');
+  const pageFiles = fs.existsSync(pageDirectory)
+    ? fs.readdirSync(pageDirectory)
+      .filter((name) => /\.(?:f7|html)$/i.test(name))
+      .sort()
+      .slice(0, 30)
+    : [];
+  let remainingPageCharacters = 12000;
+  const visiblePageText = [];
+
+  for (const fileName of pageFiles) {
+    if (remainingPageCharacters <= 0) break;
+    const text = stripMarkup(
+      readTextIfPresent(path.join(pageDirectory, fileName), Math.min(5000, remainingPageCharacters)),
+    );
+    if (text) {
+      const excerpt = text.slice(0, Math.min(2500, remainingPageCharacters));
+      visiblePageText.push({ file: fileName, text: excerpt });
+      remainingPageCharacters -= excerpt.length;
+    }
+  }
+
+  return {
+    identity: {
+      appName,
+      appUniqueId,
+      appId: String(capacitorConfig.appId || '').trim(),
+      orientation: String(capacitorConfig.orientation || '').trim(),
+    },
+    storeMetadata: {
+      name: manifest.name || '',
+      shortName: manifest.short_name || '',
+      description: manifest.description || htmlMetadata.description,
+      categories: Array.isArray(manifest.categories) ? manifest.categories : [],
+      pageTitle: htmlMetadata.title,
+    },
+    productNotes: readTextIfPresent(path.join(projectDirectory, 'GROWTH_ASO_PLAN.md'), 12000),
+    routeConfiguration: readTextIfPresent(path.join(projectDirectory, 'src', 'js', 'routes.js'), 6000),
+    visiblePageText,
+  };
+}
+
+function createCopyFingerprint(appContext, inputPaths) {
+  const sources = inputPaths.map((inputPath) => {
+    const sourceStats = fs.statSync(inputPath);
+    return {
+      relativePath: path.relative(projectDirectory, inputPath),
+      size: sourceStats.size,
+      modified: sourceStats.mtimeMs,
+    };
+  });
+  return createHash('sha256').update(JSON.stringify({
+    schemaVersion: promoCopySchemaVersion,
+    appContext,
+    sources,
+    sceneWindows,
+  })).digest('hex');
+}
+
+function getCodexExecutable() {
+  const result = spawnSync('codex', ['--version'], {
+    encoding: 'utf8',
+    windowsHide: true,
+  });
+  return !result.error && result.status === 0 ? 'codex' : '';
+}
+
+function detectActiveVideoCrop(ffmpegCommand, inputPath, videoDetails) {
+  const videoStream = videoDetails.streams?.find((stream) => stream.codec_type === 'video') || {};
+  const sourceWidth = Number(videoStream.width || 0);
+  const sourceHeight = Number(videoStream.height || 0);
+  if (sourceWidth <= sourceHeight) return null;
+
+  const result = spawnSync(ffmpegCommand, [
+    '-hide_banner',
+    '-ss', '8',
+    '-t', '4',
+    '-i', inputPath,
+    '-vf', 'cropdetect=limit=18:round=2:reset=0',
+    '-f', 'null',
+    process.platform === 'win32' ? 'NUL' : '/dev/null',
+  ], {
+    encoding: 'utf8',
+    windowsHide: true,
+    maxBuffer: 10 * 1024 * 1024,
+  });
+  if (result.error || result.status !== 0) return null;
+  const matches = [...String(result.stderr || '').matchAll(/crop=(\d+):(\d+):(\d+):(\d+)/g)];
+  const detected = matches.at(-1)?.slice(1).map(Number);
+  if (!detected) return null;
+  const [width, height, x, y] = detected;
+  const isCentralPortrait = width < sourceWidth * 0.8
+    && height >= sourceHeight * 0.9
+    && height > width
+    && Math.abs((x + (width / 2)) - (sourceWidth / 2)) <= sourceWidth * 0.03;
+  return isCentralPortrait ? { width, height, x, y } : null;
+}
+
+function cropFilter(crop) {
+  return crop ? `crop=${crop.width}:${crop.height}:${crop.x}:${crop.y},` : '';
+}
+
+function extractAnalysisFrames(ffmpegCommand, inputPath, crop) {
+  fs.mkdirSync(analysisFrameDirectory, { recursive: true });
+  return sceneWindows.map((scene, index) => {
+    const framePath = path.join(
+      analysisFrameDirectory,
+      `scene-${String(index + 1).padStart(2, '0')}.jpg`,
+    );
+    run(ffmpegCommand, [
+      '-hide_banner',
+      '-loglevel', 'error',
+      '-y',
+      '-ss', String(scene.sourceTime),
+      '-i', inputPath,
+      '-frames:v', '1',
+      '-vf', `${cropFilter(crop)}setparams=colorspace=bt709:color_primaries=bt709:color_trc=bt709:range=tv,scale=768:-2,format=yuvj420p`,
+      '-q:v', '3',
+      framePath,
+    ]);
+    return framePath;
+  });
+}
+
+function buildPromoCopyPrompt(appContext, previousError = '') {
+  const timingRequirements = sceneWindows.map((scene, index) => ({
+    scene: index + 1,
+    outputStartSeconds: scene.start,
+    outputEndSeconds: scene.end,
+    sourceFrameSeconds: scene.sourceTime,
+    maximumNarrationWords: scene.maxNarrationWords,
+  }));
+  return `Create factual, high-conversion ASO/SEO copy for a ${expectedDuration}-second mobile-app promo video.
+
+The ${sceneWindows.length} supplied images are ordered scene 1 through scene ${sceneWindows.length}. Use both those images and the sanitized project context below. Do not inspect files, run commands, or edit anything. Return only JSON matching the supplied schema.
+
+Rules:
+- Generate exactly ${sceneWindows.length} scenes in the same order as the images and timings.
+- Use only features supported by the images or project context. Never invent claims.
+- The authoritative app name is ${JSON.stringify(appName)}. Mention it naturally in the final narration and final body.
+- APP_UNIQUE_ID is internal and must never appear in audience-facing copy.
+- Each kicker: 2-30 characters. Each title line: 1-22 characters. Body: 8-72 characters.
+- Narration must fit its scene's maximum word count. Use natural spoken English for a warm UK female voice.
+- Keep captions punchy, specific and readable. Prefer user benefits and relevant search intent.
+- footer_keywords must contain exactly 3 distinct, natural app-search phrases, each 2-24 characters.
+- Generate a YouTube upload title and description from the same verified features.
+- YouTube title: 40-100 characters, include ${JSON.stringify(appName)} and one strong natural search phrase, without clickbait.
+- YouTube description: 350-1500 characters with readable paragraphs. Put the clearest app summary and primary search phrase in the opening two lines, explain the demonstrated features, add a simple call to action, and finish with exactly 3 relevant hashtags on one line.
+- Do not add download links or URLs; the script will append the verified Google Play URL built from the configured package ID. Do not add chapter timestamps or unsupported availability claims.
+- Keep YouTube text natural and useful; do not repeat keywords unnaturally.
+- Avoid prices, ratings, awards, competitor names, unsupported superlatives, and words such as best, guaranteed, or free.
+- No emoji, quotation marks, line breaks, markdown, or ending punctuation in kickers/titles/keywords.
+
+Scene timing requirements:
+${JSON.stringify(timingRequirements, null, 2)}
+
+Sanitized app context (no credentials):
+${JSON.stringify(appContext, null, 2)}
+${previousError ? `\nYour previous output was invalid: ${previousError}\nCorrect that issue in this response.` : ''}`;
+}
+
+function cleanGeneratedString(value) {
+  return String(value || '').replace(/\s+/g, ' ').trim();
+}
+
+function cleanGeneratedDescription(value) {
+  return String(value || '')
+    .replace(/\r\n?/g, '\n')
+    .split('\n')
+    .map((line) => line.trim())
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+function addPlayStoreDownloadLink(description) {
+  const cleanedDescription = cleanGeneratedDescription(description);
+  if (cleanedDescription.includes(playStoreDownloadUrl)) return cleanedDescription;
+
+  const lines = cleanedDescription.split('\n');
+  let finalContentIndex = lines.length - 1;
+  while (finalContentIndex >= 0 && !lines[finalContentIndex].trim()) finalContentIndex -= 1;
+  const finalLine = lines[finalContentIndex]?.trim() || '';
+  const hashtags = finalLine.match(/#[\p{L}\p{N}_]+/gu) || [];
+  const hasFinalHashtagLine = hashtags.length === 3
+    && !finalLine.replace(/#[\p{L}\p{N}_]+/gu, '').trim();
+  const downloadBlock = `Download ${appName} on Google Play:\n${playStoreDownloadUrl}`;
+
+  if (!hasFinalHashtagLine) {
+    return `${cleanedDescription}\n\n${downloadBlock}`;
+  }
+
+  const descriptionBody = lines.slice(0, finalContentIndex).join('\n').trimEnd();
+  return `${descriptionBody}\n\n${downloadBlock}\n\n${finalLine}`;
+}
+
+function validatePromoCopy(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('AI copy is not a JSON object.');
+  }
+  if (!Array.isArray(value.scenes) || value.scenes.length !== sceneWindows.length) {
+    throw new Error(`AI copy must contain exactly ${sceneWindows.length} scenes.`);
+  }
+  if (!Array.isArray(value.footer_keywords) || value.footer_keywords.length !== 3) {
+    throw new Error('AI copy must contain exactly 3 footer keywords.');
+  }
+  if (!value.youtube || typeof value.youtube !== 'object' || Array.isArray(value.youtube)) {
+    throw new Error('AI copy must contain YouTube upload metadata.');
+  }
+
+  const footerKeywords = value.footer_keywords.map((keyword, index) => {
+    const cleaned = cleanGeneratedString(keyword);
+    if (cleaned.length < 2 || cleaned.length > 24) {
+      throw new Error(`Footer keyword ${index + 1} must be 2-24 characters.`);
+    }
+    return cleaned;
+  });
+  if (new Set(footerKeywords.map((keyword) => keyword.toLowerCase())).size !== 3) {
+    throw new Error('Footer keywords must be distinct.');
+  }
+
+  const constraints = {
+    kicker: [2, 30],
+    title_line_1: [1, 22],
+    title_line_2: [1, 22],
+    body: [8, 72],
+    narration: [8, 120],
+  };
+  const scenes = value.scenes.map((scene, sceneIndex) => {
+    if (!scene || typeof scene !== 'object' || Array.isArray(scene)) {
+      throw new Error(`Scene ${sceneIndex + 1} is invalid.`);
+    }
+    const cleanedScene = {};
+    for (const [field, [minimum, maximum]] of Object.entries(constraints)) {
+      const cleaned = cleanGeneratedString(scene[field]);
+      if (cleaned.length < minimum || cleaned.length > maximum) {
+        throw new Error(
+          `Scene ${sceneIndex + 1} ${field} must be ${minimum}-${maximum} characters.`,
+        );
+      }
+      cleanedScene[field] = cleaned;
+    }
+    const narrationWords = cleanedScene.narration.split(/\s+/).length;
+    if (narrationWords > sceneWindows[sceneIndex].maxNarrationWords) {
+      throw new Error(
+        `Scene ${sceneIndex + 1} narration has ${narrationWords} words; maximum is ${sceneWindows[sceneIndex].maxNarrationWords}.`,
+      );
+    }
+    return cleanedScene;
+  });
+  const finalCopy = `${scenes.at(-1).body} ${scenes.at(-1).narration}`.toLowerCase();
+  if (!finalCopy.includes(appName.toLowerCase())) {
+    throw new Error(`The final scene must mention the app name ${JSON.stringify(appName)}.`);
+  }
+
+  const youtubeTitle = cleanGeneratedString(value.youtube.title);
+  const youtubeDescription = cleanGeneratedDescription(value.youtube.description);
+  if (youtubeTitle.length < 40 || youtubeTitle.length > 100) {
+    throw new Error('YouTube title must be 40-100 characters.');
+  }
+  if (youtubeDescription.length < 350 || youtubeDescription.length > 1500) {
+    throw new Error('YouTube description must be 350-1500 characters.');
+  }
+  if (Buffer.byteLength(youtubeDescription, 'utf8') > 5000) {
+    throw new Error('YouTube description exceeds the 5,000-byte API limit.');
+  }
+  if (/[<>]/.test(`${youtubeTitle}${youtubeDescription}`)) {
+    throw new Error('YouTube metadata cannot contain angle brackets.');
+  }
+  if (!youtubeTitle.toLowerCase().includes(appName.toLowerCase())
+    || !youtubeDescription.toLowerCase().includes(appName.toLowerCase())) {
+    throw new Error(`YouTube title and description must mention ${JSON.stringify(appName)}.`);
+  }
+  const descriptionLines = youtubeDescription.split('\n').filter(Boolean);
+  const finalDescriptionLine = descriptionLines.at(-1) || '';
+  const hashtags = finalDescriptionLine.match(/#[\p{L}\p{N}_]+/gu) || [];
+  if (hashtags.length !== 3 || finalDescriptionLine.replace(/#[\p{L}\p{N}_]+/gu, '').trim()) {
+    throw new Error('YouTube description must finish with a line containing exactly 3 hashtags.');
+  }
+
+  return {
+    footer_keywords: footerKeywords,
+    scenes,
+    youtube: {
+      title: youtubeTitle,
+      description: youtubeDescription,
+    },
+  };
+}
+
+function parseAiJson(rawValue) {
+  const text = String(rawValue || '').trim()
+    .replace(/^```(?:json)?\s*/i, '')
+    .replace(/\s*```$/, '');
+  return JSON.parse(text);
+}
+
+function generateCopyWithCodex(prompt, framePaths, modelName) {
+  const codexCommand = getCodexExecutable();
+  if (!codexCommand) {
+    throw new Error('Codex CLI is unavailable or not signed in.');
+  }
+  fs.mkdirSync(temporaryDirectory, { recursive: true });
+  fs.writeFileSync(promoCopySchemaPath, `${JSON.stringify(promoCopySchema, null, 2)}\n`, 'utf8');
+  const args = [
+    'exec',
+    '--ephemeral',
+    '--ignore-rules',
+    '--sandbox', 'read-only',
+    '--skip-git-repo-check',
+    '--color', 'never',
+    '--output-schema', promoCopySchemaPath,
+    '--output-last-message', promoCopyResultPath,
+    '-C', projectDirectory,
+  ];
+  if (modelName) args.push('--model', modelName);
+  for (const framePath of framePaths) args.push('--image', framePath);
+  args.push('-');
+  run(codexCommand, args, { input: prompt });
+  return {
+    copy: parseAiJson(fs.readFileSync(promoCopyResultPath, 'utf8')),
+    model: modelName || 'Codex configured model',
+    provider: 'codex',
+  };
+}
+
+async function generateCopyWithOpenAi(prompt, framePaths, modelName) {
+  const apiKey = String(process.env.OPENAI_API_KEY || '').trim();
+  if (!apiKey) throw new Error('OPENAI_API_KEY is not configured.');
+  const model = modelName || process.env.OPENAI_PROMO_MODEL || 'gpt-4o-mini';
+  const content = [{ type: 'input_text', text: prompt }];
+  for (const framePath of framePaths) {
+    content.push({
+      type: 'input_image',
+      image_url: `data:image/jpeg;base64,${fs.readFileSync(framePath).toString('base64')}`,
+      detail: 'low',
+    });
+  }
+  const response = await fetch('https://api.openai.com/v1/responses', {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      model,
+      store: false,
+      max_output_tokens: 2500,
+      input: [{ role: 'user', content }],
+      text: {
+        format: {
+          type: 'json_schema',
+          name: 'promo_video_copy',
+          strict: true,
+          schema: promoCopySchema,
+        },
+      },
+    }),
+  });
+  const result = await response.json();
+  if (!response.ok) {
+    throw new Error(`OpenAI Responses API failed: ${result.error?.message || response.statusText}`);
+  }
+  const outputText = result.output_text || result.output
+    ?.flatMap((item) => item.content || [])
+    .find((item) => item.type === 'output_text')?.text;
+  if (!outputText) throw new Error('OpenAI returned no promo copy.');
+  return { copy: parseAiJson(outputText), model, provider: 'openai' };
+}
+
+async function generateOrLoadPromoCopy(
+  options,
+  ffmpegCommand,
+  analysisInputPath,
+  allInputPaths,
+  analysisCrop,
+) {
+  const appContext = collectAppContext();
+  const fingerprint = createCopyFingerprint(appContext, allInputPaths);
+  if (!options.refreshAiCopy && fs.existsSync(promoCopyCachePath)) {
+    try {
+      const cached = JSON.parse(fs.readFileSync(promoCopyCachePath, 'utf8'));
+      if (cached.schemaVersion === promoCopySchemaVersion && cached.fingerprint === fingerprint) {
+        return {
+          copy: validatePromoCopy(cached.copy),
+          fromCache: true,
+          model: cached.model,
+          provider: cached.provider,
+        };
+      }
+    } catch (error) {
+      console.warn(`Ignoring invalid AI copy cache: ${error.message}`);
+    }
+  }
+
+  const provider = options.aiProvider === 'auto'
+    ? (process.env.OPENAI_API_KEY ? 'openai' : 'codex')
+    : options.aiProvider;
+  console.log(`Analyzing ${sceneWindows.length} video scenes for app-specific promo copy...`);
+  const framePaths = extractAnalysisFrames(ffmpegCommand, analysisInputPath, analysisCrop);
+  let previousError = '';
+  let generated;
+  for (let attempt = 1; attempt <= 2; attempt += 1) {
+    const prompt = buildPromoCopyPrompt(appContext, previousError);
+    try {
+      generated = provider === 'openai'
+        ? await generateCopyWithOpenAi(prompt, framePaths, options.aiModel)
+        : generateCopyWithCodex(prompt, framePaths, options.aiModel);
+      generated.copy = validatePromoCopy(generated.copy);
+      break;
+    } catch (error) {
+      previousError = error.message;
+      if (attempt === 2 || /unavailable|not configured|not signed in/i.test(previousError)) throw error;
+      console.warn(`AI copy attempt ${attempt} was invalid; requesting a corrected result.`);
+    }
+  }
+
+  const cache = {
+    schemaVersion: promoCopySchemaVersion,
+    fingerprint,
+    appName,
+    appUniqueId,
+    provider: generated.provider,
+    model: generated.model,
+    generatedAt: new Date().toISOString(),
+    copy: generated.copy,
+  };
+  fs.mkdirSync(path.dirname(promoCopyCachePath), { recursive: true });
+  fs.writeFileSync(promoCopyCachePath, `${JSON.stringify(cache, null, 2)}\n`, 'utf8');
+  return { ...generated, fromCache: false };
+}
+
+function createSpatialMetadataSource(promoCopy) {
+  const suffix = ' | Spatial 3D XR Preview';
+  const maximumBaseLength = 100 - suffix.length;
+  let titleBase = promoCopy.youtube.title.slice(0, maximumBaseLength).trim();
+  if (titleBase.length < promoCopy.youtube.title.length && titleBase.includes(' ')) {
+    titleBase = titleBase.slice(0, titleBase.lastIndexOf(' ')).trim();
+  }
+  const spatialIntroduction = [
+    `Experience ${appName} as a stereoscopic 3D floating-screen preview for Android XR.`,
+    'The mobile app interface remains a 2D experience, presented with depth for headset viewing.',
+  ].join(' ');
+  return {
+    description: `${spatialIntroduction}\n\n${promoCopy.youtube.description}`,
+    inputPath: spatialXrVideoPath,
+    outputPath: spatialXrVideoPath,
+    platform: 'Google-Play-XR-Spatial',
+    recommendedVisibility: 'Unlisted',
+    spatialStereo: true,
+    title: `${titleBase}${suffix}`,
+  };
+}
+
+function writeYoutubeUploadMetadata(promoCopy, sourceVideos) {
+  return sourceVideos.map((source) => {
+    const metadataDirectory = path.dirname(source.outputPath);
+    const relativeInputPath = path.relative(sourceVideoDirectory, source.inputPath);
+    const platform = source.platform || (relativeInputPath.startsWith('..')
+      ? path.basename(metadataDirectory)
+      : relativeInputPath.split(path.sep)[0]);
+    const metadataJsonPath = path.join(
+      metadataDirectory,
+      `${appFilePrefix}-youtube-upload-metadata.json`,
+    );
+    const metadataTextPath = path.join(
+      metadataDirectory,
+      `${appFilePrefix}-youtube-upload-metadata.txt`,
+    );
+    const metadata = {
+      appName,
+      appUniqueId,
+      packageId,
+      playStoreDownloadUrl,
+      platform,
+      videoFile: path.basename(source.outputPath),
+      thumbnailFile: path.basename(getThumbnailPath(source.outputPath)),
+      recommendedVisibility: source.recommendedVisibility || '',
+      title: source.title || promoCopy.youtube.title,
+      description: addPlayStoreDownloadLink(
+        source.description || promoCopy.youtube.description,
+      ),
+    };
+    const visibilityText = metadata.recommendedVisibility
+      ? `\n\nRECOMMENDED VISIBILITY\n${metadata.recommendedVisibility}`
+      : '';
+    const textContent = `TITLE\n${metadata.title}\n\nDESCRIPTION\n${metadata.description}${visibilityText}\n`;
+    fs.mkdirSync(metadataDirectory, { recursive: true });
+    fs.writeFileSync(metadataJsonPath, `${JSON.stringify(metadata, null, 2)}\n`, 'utf8');
+    fs.writeFileSync(metadataTextPath, textContent, 'utf8');
+    return { metadataJsonPath, metadataTextPath, platform };
+  });
+}
+
+function getThumbnailPath(videoPath) {
+  return path.join(
+    path.dirname(videoPath),
+    `${appFilePrefix}-youtube-thumbnail-${thumbnailWidth}x${thumbnailHeight}.jpg`,
+  );
+}
+
+function createVideoThumbnail(ffmpegCommand, ffprobeCommand, videoPath, spatialStereo = false) {
+  const thumbnailPath = getThumbnailPath(videoPath);
+  fs.mkdirSync(path.dirname(thumbnailPath), { recursive: true });
+  let thumbnailSize = Infinity;
+
+  for (const quality of [2, 4, 6, 8, 10]) {
+    const stereoCrop = spatialStereo ? 'crop=iw/2:ih:0:0,' : '';
+    run(ffmpegCommand, [
+      '-hide_banner',
+      '-loglevel', 'error',
+      '-y',
+      '-ss', String(thumbnailTime),
+      '-i', videoPath,
+      '-frames:v', '1',
+      '-vf', `${stereoCrop}scale=${thumbnailWidth}:${thumbnailHeight}:flags=lanczos,setsar=1`,
+      '-q:v', String(quality),
+      thumbnailPath,
+    ]);
+    thumbnailSize = fs.statSync(thumbnailPath).size;
+    if (thumbnailSize <= maximumThumbnailBytes) break;
+  }
+
+  const details = getVideoDetails(ffprobeCommand, thumbnailPath);
+  const imageStream = details.streams?.find((stream) => stream.codec_type === 'video') || {};
+  if (Number(imageStream.width) !== thumbnailWidth
+    || Number(imageStream.height) !== thumbnailHeight) {
+    throw new Error(`Thumbnail resolution is not ${thumbnailWidth}x${thumbnailHeight}.`);
+  }
+  if (thumbnailSize > maximumThumbnailBytes) {
+    throw new Error(
+      `Thumbnail is ${(thumbnailSize / 1024 / 1024).toFixed(2)}MB; maximum is 2MB.`,
+    );
+  }
+  console.log(
+    `Created thumbnail: ${thumbnailPath} (${Math.round(thumbnailSize / 1024)}KB)`,
+  );
+  return thumbnailPath;
+}
+
+function formatAssTime(seconds) {
+  const centiseconds = Math.round(seconds * 100);
+  const hours = Math.floor(centiseconds / 360000);
+  const minutes = Math.floor((centiseconds % 360000) / 6000);
+  const wholeSeconds = Math.floor((centiseconds % 6000) / 100);
+  const remainder = centiseconds % 100;
+  return `${hours}:${String(minutes).padStart(2, '0')}:${String(wholeSeconds).padStart(2, '0')}.${String(remainder).padStart(2, '0')}`;
+}
+
+function createCaptionFile(promoCopy) {
+  const captionAppName = escapeAssText(appName.toUpperCase());
+  const events = sceneWindows.flatMap((window, index) => {
+    const scene = promoCopy.scenes[index];
+    const start = formatAssTime(window.start);
+    const end = formatAssTime(window.end);
+    const x = index === sceneWindows.length - 1 ? 895 : 720;
+    const fadeIn = window.end - window.start <= 3 ? 180 : 220;
+    const fadeOut = index === sceneWindows.length - 1 ? 350 : fadeIn;
+    const fade = `\\fad(${fadeIn},${fadeOut})`;
+    return [
+      `Dialogue: 0,${start},${end},Kicker,,0,0,0,,{\\pos(${x},225)${fade}}${escapeAssText(scene.kicker.toUpperCase())}`,
+      `Dialogue: 0,${start},${end},Title,,0,0,0,,{\\pos(${x},270)${fade}}${escapeAssText(scene.title_line_1.toUpperCase())}\\N${escapeAssText(scene.title_line_2.toUpperCase())}`,
+      `Dialogue: 0,${start},${end},Body,,0,0,0,,{\\pos(${x},470)${fade}}${escapeAssText(scene.body)}`,
+    ];
+  });
+  const footer = promoCopy.footer_keywords
+    .map((keyword) => escapeAssText(keyword.toUpperCase()))
+    .join('  /  ');
+  const captionContent = `[Script Info]
+ScriptType: v4.00+
+PlayResX: 1920
+PlayResY: 1080
+ScaledBorderAndShadow: yes
+WrapStyle: 2
+
+[V4+ Styles]
+Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding
+Style: Brand,Segoe UI,30,&H00FFFFFF,&H00FFFFFF,&H50000000,&H00000000,1,0,0,0,100,100,2,0,1,1,0,7,0,0,0,1
+Style: Kicker,Segoe UI Semibold,25,&H00C3D523,&H00C3D523,&H50000000,&H00000000,1,0,0,0,100,100,2,0,1,1,0,7,0,0,0,1
+Style: Title,Segoe UI Semibold,76,&H00FFFFFF,&H00FFFFFF,&H80000000,&H00000000,1,0,0,0,100,100,0,0,1,2,0,7,0,0,0,1
+Style: Body,Segoe UI,35,&H00D8E3F0,&H00D8E3F0,&H70000000,&H00000000,0,0,0,0,100,100,0,0,1,1,0,7,0,0,0,1
+Style: Footer,Segoe UI Semibold,22,&H00FFFFFF,&H00FFFFFF,&H50000000,&H00000000,1,0,0,0,100,100,2,0,1,1,0,7,0,0,0,1
+
+[Events]
+Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
+Dialogue: 0,0:00:00.00,${formatAssTime(expectedDuration)},Brand,,0,0,0,,{\\pos(720,78)\\fad(350,350)}${captionAppName}
+${events.join('\n')}
+Dialogue: 0,0:00:00.00,${formatAssTime(expectedDuration)},Footer,,0,0,0,,{\\pos(720,1008)\\fad(350,350)}${footer}
+`;
+
+  fs.mkdirSync(temporaryDirectory, { recursive: true });
+  fs.writeFileSync(captionPath, captionContent, 'utf8');
+}
+
+function synthesizeNeuralSpeech(pythonCommand, voiceName, text, destinationPath) {
+  run(pythonCommand, [
+    '-m', 'edge_tts',
+    '--voice', voiceName,
+    '--rate', '+4%',
+    '--pitch', '+0Hz',
+    '--text', text,
+    '--write-media', destinationPath,
+  ]);
+
+  if (!fs.existsSync(destinationPath) || fs.statSync(destinationPath).size < 1000) {
+    throw new Error(`Neural narration synthesis failed: ${destinationPath}`);
+  }
+}
+
+function createNarrationSegments(pythonCommand, voiceName, promoCopy) {
+  const segmentDirectory = path.join(temporaryDirectory, 'narration-segments');
+  fs.mkdirSync(segmentDirectory, { recursive: true });
+
+  const segmentPaths = promoCopy.scenes.map((scene, index) => (
+    path.join(segmentDirectory, `segment-${String(index + 1).padStart(2, '0')}.mp3`)
+  ));
+
+  promoCopy.scenes.forEach((scene, index) => {
+    synthesizeNeuralSpeech(
+      pythonCommand,
+      voiceName,
+      scene.narration,
+      segmentPaths[index],
+    );
+  });
+
+  return segmentPaths;
+}
+
+function createVoicePreviews(pythonCommand) {
+  const previewText = `Discover what ${appName} can do. Explore the highlights and get started today.`;
+  fs.mkdirSync(voicePreviewDirectory, { recursive: true });
+
+  for (const [alias, voice] of Object.entries(neuralVoiceCatalog)) {
+    const previewPath = path.join(voicePreviewDirectory, `${alias}-${voice.name}.mp3`);
+    console.log(`Creating ${alias} preview: ${voice.label}`);
+    synthesizeNeuralSpeech(pythonCommand, voice.name, previewText, previewPath);
+  }
+
+  console.log(`Created voice previews: ${voicePreviewDirectory}`);
+}
+
+function createNarrationTrack(ffmpegCommand, segmentPaths) {
+  const inputArguments = segmentPaths.flatMap((segmentPath) => ['-i', segmentPath]);
+  const segmentFilters = sceneWindows.map((scene, index) => {
+    const delay = Math.round((scene.start + (index === 0 ? 0.25 : 0.2)) * 1000);
+    return `[${index}:a]aresample=48000,aformat=sample_fmts=fltp:channel_layouts=stereo,adelay=${delay}|${delay}[n${index}]`;
+  });
+  const inputs = sceneWindows.map((scene, index) => `[n${index}]`).join('');
+  const filterGraph = [
+    ...segmentFilters,
+    `${inputs}amix=inputs=${sceneWindows.length}:normalize=0:duration=longest,highpass=f=80,lowpass=f=12000,loudnorm=I=-16:TP=-2:LRA=7,apad=whole_dur=${expectedDuration}[narration]`,
+  ].join(';');
+
+  run(ffmpegCommand, [
+    '-hide_banner',
+    '-y',
+    ...inputArguments,
+    '-filter_complex', filterGraph,
+    '-map', '[narration]',
+    '-t', String(expectedDuration),
+    '-c:a', 'pcm_s16le',
+    '-ar', '48000',
+    '-ac', '2',
+    narrationTrackPath,
+  ]);
+
+  if (!fs.existsSync(narrationTrackPath) || fs.statSync(narrationTrackPath).size < 1000) {
+    throw new Error('The narration track was not created.');
+  }
+}
+
+function getVideoDetails(ffprobeCommand, videoPath) {
+  return JSON.parse(run(ffprobeCommand, [
+    '-v', 'error',
+    '-show_entries', 'stream=codec_name,codec_type,width,height,r_frame_rate,sample_aspect_ratio,sample_rate,channels',
+    '-show_entries', 'format=duration,size,bit_rate',
+    '-of', 'json',
+    videoPath,
+  ]));
+}
+
+function validateInput(ffprobeCommand, inputPath) {
+  const details = getVideoDetails(ffprobeCommand, inputPath);
+  const videoStream = details.streams?.find((stream) => stream.codec_type === 'video');
+  const audioStream = details.streams?.find((stream) => stream.codec_type === 'audio');
+  const duration = Number(details.format?.duration || 0);
+
+  if (!videoStream || !audioStream) {
+    throw new Error('The source must contain both video and audio streams.');
+  }
+  if (Number(videoStream.width) < 480 || Number(videoStream.height) < 1080) {
+    throw new Error('The source resolution is too small for the promotional layout.');
+  }
+  if (duration < minimumSourceDuration) {
+    throw new Error(`The source must be at least ${minimumSourceDuration} seconds.`);
+  }
+  return details;
+}
+
+function validateOutput(ffprobeCommand, outputPath, targetWidth, targetHeight) {
+  const details = getVideoDetails(ffprobeCommand, outputPath);
+  const videoStream = details.streams?.find((stream) => stream.codec_type === 'video') || {};
+  const audioStream = details.streams?.find((stream) => stream.codec_type === 'audio') || {};
+  const duration = Number(details.format?.duration || 0);
+
+  if (videoStream.codec_name !== 'h264') throw new Error('Output video is not H.264.');
+  if (Number(videoStream.width) !== targetWidth || Number(videoStream.height) !== targetHeight) {
+    throw new Error(`Output resolution is not ${targetWidth}x${targetHeight}.`);
+  }
+  if (videoStream.sample_aspect_ratio !== '1:1') {
+    throw new Error(`Output sample aspect ratio is ${videoStream.sample_aspect_ratio}; expected 1:1.`);
+  }
+  if (audioStream.codec_name !== 'aac') throw new Error('Output audio is not AAC.');
+  if (Math.abs(duration - expectedDuration) > 0.2) {
+    throw new Error(`Output duration is ${duration.toFixed(2)}s; expected ${expectedDuration}s.`);
+  }
+
+  console.log(
+    `Validated: ${targetWidth}x${targetHeight}, H.264/AAC, ${duration.toFixed(2)}s, `
+      + `${Math.round(Number(details.format?.bit_rate || 0) / 1000)} kbps.`,
+  );
+}
+
+function generatePromo(ffmpegCommand, inputPath, outputPath, crop, targetWidth, targetHeight) {
+  const subtitleFilterPath = escapeFilterPath(captionPath);
+  const is4K = targetWidth >= 3840 || targetHeight >= 2160;
+  const videoBitrate = is4K ? '24M' : '9M';
+  const maximumBitrate = is4K ? '32M' : '12M';
+  const bufferSize = is4K ? '48M' : '18M';
+  const h264Level = is4K ? '5.1' : '4.2';
+  const segmentCount = editSegments.length;
+  const videoSourceLabels = editSegments.map((_, index) => `[videosource${index}]`).join('');
+  const audioSourceLabels = editSegments.map((_, index) => `[audiosource${index}]`).join('');
+  const videoSourceFilter = segmentCount === 1
+    ? `[0:v]${cropFilter(crop)}format=yuv420p,setparams=colorspace=bt709:color_primaries=bt709:color_trc=bt709:range=tv[videosource0]`
+    : `[0:v]${cropFilter(crop)}format=yuv420p,setparams=colorspace=bt709:color_primaries=bt709:color_trc=bt709:range=tv,split=${segmentCount}${videoSourceLabels}`;
+  const audioSourceFilter = segmentCount === 1
+    ? '[0:a]aresample=48000:async=1000:first_pts=0[audiosource0]'
+    : `[0:a]aresample=48000:async=1000:first_pts=0,asplit=${segmentCount}${audioSourceLabels}`;
+  const videoTrimFilters = editSegments.map((segment, index) => (
+    `[videosource${index}]trim=start=${segment.start}:end=${segment.end},setpts=PTS-STARTPTS[v${index}]`
+  ));
+  const audioTrimFilters = editSegments.map((segment, index) => (
+    `[audiosource${index}]atrim=start=${segment.start}:end=${segment.end},asetpts=PTS-STARTPTS[a${index}]`
+  ));
+  const videoSequenceFilter = segmentCount === 1
+    ? '[v0]fps=30,setpts=PTS-STARTPTS,split=2[bgsrc][phonesrc]'
+    : `${editSegments.map((_, index) => `[v${index}]`).join('')}concat=n=${segmentCount}:v=1:a=0,fps=30,setpts=PTS-STARTPTS,split=2[bgsrc][phonesrc]`;
+  const audioSequenceFilter = segmentCount === 1
+    ? '[a0]loudnorm=I=-20:TP=-2:LRA=11[appaudio-pre]'
+    : `${editSegments.map((_, index) => `[a${index}]`).join('')}concat=n=${segmentCount}:v=0:a=1,loudnorm=I=-20:TP=-2:LRA=11[appaudio-pre]`;
+  const finalSceneStart = sceneWindows.at(-1).start;
+  const audioFadeOutStart = Math.max(0, expectedDuration - 0.65);
+  const filterGraph = [
+    videoSourceFilter,
+    ...videoTrimFilters,
+    videoSequenceFilter,
+    '[bgsrc]scale=1920:1080:force_original_aspect_ratio=increase,crop=1920:1080,gblur=sigma=34,eq=brightness=-0.40:saturation=1.30,drawbox=x=0:y=0:w=iw:h=ih:color=0x07101f@0.72:t=fill[background]',
+    '[background]drawbox=x=105:y=30:w=500:h=1020:color=black@0.58:t=fill,drawbox=x=112:y=37:w=486:h=1006:color=0x23d5c3@0.24:t=3,drawbox=x=680:y=176:w=1050:h=2:color=0x23d5c3@0.55:t=fill,drawbox=x=680:y=960:w=1050:h=2:color=white@0.16:t=fill,drawbox=x=680:y=176:w=10:h=786:color=0xffb020@0.90:t=fill[stage]',
+    '[phonesrc]scale=-2:980,setsar=1[phone]',
+    '[stage][phone]overlay=x=134:y=50:shortest=1[layout]',
+    '[1:v]scale=145:145,format=rgba,colorchannelmixer=aa=0.96[icon]',
+    `[layout][icon]overlay=x=720:y=650:enable=between(t\\,${finalSceneStart}\\,${expectedDuration}):shortest=1[branded]`,
+    `[branded]ass=filename='${subtitleFilterPath}',scale=${targetWidth}:${targetHeight}:flags=lanczos,setsar=1,format=yuv420p,setparams=colorspace=bt709:color_primaries=bt709:color_trc=bt709:range=tv[video]`,
+    audioSourceFilter,
+    ...audioTrimFilters,
+    audioSequenceFilter,
+    `[appaudio-pre]afade=t=in:st=0:d=0.12,afade=t=out:st=${audioFadeOutStart}:d=0.65[appaudio]`,
+    '[2:a]aresample=48000,aformat=sample_fmts=fltp:channel_layouts=stereo,asplit=2[voicekey][voice]',
+    '[appaudio][voicekey]sidechaincompress=threshold=0.015:ratio=10:attack=15:release=350:makeup=1[ducked]',
+    '[ducked][voice]amix=inputs=2:weights=0.72 1.12:normalize=0,alimiter=limit=0.84:level=false[audio]',
+  ].join(';');
+
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+
+  run(ffmpegCommand, [
+    '-hide_banner',
+    '-y',
+    '-i', inputPath,
+    '-loop', '1',
+    '-framerate', '30',
+    '-i', iconPath,
+    '-i', narrationTrackPath,
+    '-filter_complex', filterGraph,
+    '-map', '[video]',
+    '-map', '[audio]',
+    '-t', String(expectedDuration),
+    '-c:v', 'libx264',
+    '-preset', 'medium',
+    '-profile:v', 'high',
+    '-level', h264Level,
+    '-pix_fmt', 'yuv420p',
+    '-r', '30',
+    '-b:v', videoBitrate,
+    '-maxrate', maximumBitrate,
+    '-bufsize', bufferSize,
+    '-c:a', 'aac',
+    '-b:a', '192k',
+    '-ar', '48000',
+    '-movflags', '+faststart',
+    outputPath,
+  ], { inherit: true });
+}
+
+function generateSpatialXrPromo(ffmpegCommand, inputPath, outputPath) {
+  const foregroundWidth = 1760;
+  const foregroundHeight = 990;
+  const leftForegroundX = 96;
+  const rightForegroundX = 64;
+  const foregroundY = 45;
+  const filterGraph = [
+    `[0:v]scale=${spatialEyeWidth}:${spatialEyeHeight}:flags=lanczos,setsar=1,split=3[base][leftsource][rightsource]`,
+    '[base]gblur=sigma=48,eq=brightness=-0.34:saturation=0.82,split=2[leftbg][rightbg]',
+    `[leftsource]scale=${foregroundWidth}:${foregroundHeight}:flags=lanczos[leftforeground]`,
+    `[rightsource]scale=${foregroundWidth}:${foregroundHeight}:flags=lanczos[rightforeground]`,
+    `[leftbg]drawbox=x=${leftForegroundX - 7}:y=${foregroundY - 7}:w=${foregroundWidth + 14}:h=${foregroundHeight + 14}:color=0x23d5c3@0.55:t=4[leftstage]`,
+    `[rightbg]drawbox=x=${rightForegroundX - 7}:y=${foregroundY - 7}:w=${foregroundWidth + 14}:h=${foregroundHeight + 14}:color=0x23d5c3@0.55:t=4[rightstage]`,
+    `[leftstage][leftforeground]overlay=x=${leftForegroundX}:y=${foregroundY}:shortest=1[left]`,
+    `[rightstage][rightforeground]overlay=x=${rightForegroundX}:y=${foregroundY}:shortest=1[right]`,
+    `[left][right]hstack=inputs=2,setsar=1,format=yuv420p,setparams=colorspace=bt709:color_primaries=bt709:color_trc=bt709:range=tv[video]`,
+  ].join(';');
+
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  run(ffmpegCommand, [
+    '-hide_banner',
+    '-y',
+    '-i', inputPath,
+    '-filter_complex', filterGraph,
+    '-map', '[video]',
+    '-map', '0:a:0',
+    '-t', String(expectedDuration),
+    '-c:v', 'libx264',
+    '-preset', 'medium',
+    '-profile:v', 'high',
+    '-level', '5.1',
+    '-pix_fmt', 'yuv420p',
+    '-r', '30',
+    '-b:v', '18M',
+    '-maxrate', '24M',
+    '-bufsize', '36M',
+    '-x264opts', 'frame-packing=3',
+    '-metadata:s:v:0', 'stereo_mode=left_right',
+    '-c:a', 'aac',
+    '-b:a', '192k',
+    '-ar', '48000',
+    '-movflags', '+faststart',
+    outputPath,
+  ], { inherit: true });
+}
+
+function validateSpatialXrOutput(ffmpegCommand, ffprobeCommand, outputPath) {
+  validateOutput(
+    ffprobeCommand,
+    outputPath,
+    spatialOutputWidth,
+    spatialOutputHeight,
+  );
+  const result = spawnSync(ffmpegCommand, [
+    '-hide_banner',
+    '-loglevel', 'trace',
+    '-i', outputPath,
+    '-map', '0:v:0',
+    '-c:v', 'copy',
+    '-bsf:v', 'trace_headers',
+    '-frames:v', '1',
+    '-f', 'null',
+    process.platform === 'win32' ? 'NUL' : '/dev/null',
+  ], {
+    encoding: 'utf8',
+    windowsHide: true,
+    maxBuffer: 10 * 1024 * 1024,
+  });
+  const trace = `${result.stdout || ''}\n${result.stderr || ''}`;
+  if (result.error || result.status !== 0
+    || !/frame_packing_arrangement_type[^\n]*=\s*3/i.test(trace)) {
+    throw new Error('Spatial XR output is missing side-by-side 3D frame-packing metadata.');
+  }
+  console.log('Validated spatial metadata: stereoscopic side-by-side left-right (type 3).');
+}
+
+function createSpatialXrAssets(ffmpegCommand, ffprobeCommand, inputPath) {
+  console.log(`Generating stereoscopic Spatial XR promo: ${spatialXrVideoPath}`);
+  generateSpatialXrPromo(ffmpegCommand, inputPath, spatialXrVideoPath);
+  validateSpatialXrOutput(ffmpegCommand, ffprobeCommand, spatialXrVideoPath);
+  createVideoThumbnail(ffmpegCommand, ffprobeCommand, spatialXrVideoPath, true);
+  console.log(`Created Spatial XR promo video: ${spatialXrVideoPath}`);
+}
+
+function getTargetDimensions(videoDetails) {
+  const videoStream = videoDetails.streams?.find((stream) => stream.codec_type === 'video') || {};
+  const sourceWidth = Number(videoStream.width || 0);
+  const sourceHeight = Number(videoStream.height || 0);
+  return sourceWidth > sourceHeight
+    ? { width: sourceWidth, height: sourceHeight }
+    : { width: 1920, height: 1080 };
+}
+
+function getBatchOutputPath(inputPath, targetWidth, targetHeight) {
+  const relativeDirectory = path.relative(sourceVideoDirectory, path.dirname(inputPath));
+  const sourceName = sanitizeFileNamePart(path.basename(inputPath, path.extname(inputPath)));
+  return path.join(
+    outputVideoDirectory,
+    relativeDirectory,
+    `${appFilePrefix}-${sourceName}-promo-english-voiceover-${targetWidth}x${targetHeight}.mp4`,
+  );
+}
+
+function getSingleOutputPath(inputPath, targetWidth, targetHeight) {
+  const sourceName = sanitizeFileNamePart(path.basename(inputPath, path.extname(inputPath)));
+  return path.join(
+    outputVideoDirectory,
+    `${appFilePrefix}-${sourceName}-promo-english-voiceover-${targetWidth}x${targetHeight}.mp4`,
+  );
+}
+
+async function main() {
+  const options = parseArguments();
+  if (options.listVoices) {
+    printVoiceCatalog();
+    return;
+  }
+
+  if (options.previewVoices) {
+    const previewPythonCommand = getPythonExecutable();
+    if (!previewPythonCommand) {
+      throw new Error(
+        'edge-tts is required for natural neural voices. Install it with: py -m pip install edge-tts',
+      );
+    }
+    createVoicePreviews(previewPythonCommand);
+    return;
+  }
+
+  const ffmpegCommand = getExecutable('ffmpeg');
+  const ffprobeCommand = getExecutable('ffprobe');
+  const voice = resolveVoice(options.voice);
+
+  if (!ffmpegCommand || !ffprobeCommand) {
+    throw new Error('FFmpeg and FFprobe were not found in PATH or W:\\Tools\\ffmpeg\\bin.');
+  }
+  if (!fs.existsSync(iconPath)) throw new Error(`App icon was not found: ${iconPath}`);
+
+  const inputPaths = options.input
+    ? [path.resolve(options.input)]
+    : findVideos(sourceVideoDirectory).filter((inputPath) => !isExcludedBatchSource(inputPath));
+  if (inputPaths.length === 0) {
+    throw new Error(`No MP4 videos were found under: ${sourceVideoDirectory}`);
+  }
+  for (const inputPath of inputPaths) {
+    if (!fs.existsSync(inputPath)) throw new Error(`Source video was not found: ${inputPath}`);
+  }
+
+  console.log(`Preparing ${inputPaths.length} source video${inputPaths.length === 1 ? '' : 's'}...`);
+  const sourceVideos = inputPaths.map((inputPath) => {
+    const details = validateInput(ffprobeCommand, inputPath);
+    const duration = Number(details.format?.duration || 0);
+    const crop = detectActiveVideoCrop(ffmpegCommand, inputPath, details);
+    const target = getTargetDimensions(details);
+    const outputPath = options.output
+      ? path.resolve(options.output)
+      : options.input
+        ? getSingleOutputPath(inputPath, target.width, target.height)
+        : getBatchOutputPath(inputPath, target.width, target.height);
+    return { crop, duration, inputPath, outputPath, target };
+  });
+  configurePromoTimeline(Math.min(...sourceVideos.map((source) => source.duration)));
+  const analysisSource = [...sourceVideos].sort((left, right) => (
+    (right.target.width * right.target.height) - (left.target.width * left.target.height)
+  ))[0];
+  const promoCopyResult = await generateOrLoadPromoCopy(
+    options,
+    ffmpegCommand,
+    analysisSource.inputPath,
+    inputPaths,
+    analysisSource.crop,
+  );
+  console.log(
+    `${promoCopyResult.fromCache ? 'Using cached' : 'Generated'} AI promo copy `
+      + `(${promoCopyResult.provider}, ${promoCopyResult.model}).`,
+  );
+  console.log(`AI promo copy: ${promoCopyCachePath}`);
+  const nonSpatialXrSource = sourceVideos.find((source) => (
+    /(^|[\\/])google-play-xr-non-spatial([\\/]|$)/i.test(source.inputPath)
+  ));
+  const spatialMetadataSource = nonSpatialXrSource
+    ? createSpatialMetadataSource(promoCopyResult.copy)
+    : null;
+  const youtubeMetadataFiles = writeYoutubeUploadMetadata(
+    promoCopyResult.copy,
+    spatialMetadataSource ? [...sourceVideos, spatialMetadataSource] : sourceVideos,
+  );
+  for (const metadataFile of youtubeMetadataFiles) {
+    console.log(
+      `${metadataFile.platform} YouTube metadata: ${metadataFile.metadataTextPath}`,
+    );
+  }
+  if (options.copyOnly) return;
+  if (options.spatialXrOnly) {
+    if (!nonSpatialXrSource || !spatialMetadataSource) {
+      throw new Error('A Google-Play-XR-Non-Spatial source video is required.');
+    }
+    if (!fs.existsSync(nonSpatialXrSource.outputPath)) {
+      throw new Error(
+        `Generate the non-spatial XR promo first: ${nonSpatialXrSource.outputPath}`,
+      );
+    }
+    createSpatialXrAssets(
+      ffmpegCommand,
+      ffprobeCommand,
+      nonSpatialXrSource.outputPath,
+    );
+    return;
+  }
+  if (options.thumbnailsOnly) {
+    const thumbnailSources = spatialMetadataSource
+      ? [...sourceVideos, spatialMetadataSource]
+      : sourceVideos;
+    for (const source of thumbnailSources) {
+      if (!fs.existsSync(source.outputPath)) {
+        throw new Error(`Generated promo video was not found: ${source.outputPath}`);
+      }
+      createVideoThumbnail(
+        ffmpegCommand,
+        ffprobeCommand,
+        source.outputPath,
+        Boolean(source.spatialStereo),
+      );
+    }
+    console.log(`Completed ${thumbnailSources.length} promotional thumbnails.`);
+    return;
+  }
+
+  const pythonCommand = getPythonExecutable();
+  if (!pythonCommand) {
+    throw new Error(
+      'edge-tts is required for natural neural voices. Install it with: py -m pip install edge-tts',
+    );
+  }
+  createCaptionFile(promoCopyResult.copy);
+  console.log(`Creating natural neural narration with: ${voice.label}`);
+  const narrationSegmentPaths = createNarrationSegments(
+    pythonCommand,
+    voice.name,
+    promoCopyResult.copy,
+  );
+  createNarrationTrack(ffmpegCommand, narrationSegmentPaths);
+  for (const [index, source] of sourceVideos.entries()) {
+    console.log(
+      `Generating promo ${index + 1}/${sourceVideos.length}: ${source.inputPath} `
+        + `-> ${source.target.width}x${source.target.height}`,
+    );
+    generatePromo(
+      ffmpegCommand,
+      source.inputPath,
+      source.outputPath,
+      source.crop,
+      source.target.width,
+      source.target.height,
+    );
+    validateOutput(
+      ffprobeCommand,
+      source.outputPath,
+      source.target.width,
+      source.target.height,
+    );
+    console.log(`Created promo video: ${source.outputPath}`);
+    createVideoThumbnail(ffmpegCommand, ffprobeCommand, source.outputPath);
+  }
+  if (nonSpatialXrSource && spatialMetadataSource) {
+    createSpatialXrAssets(
+      ffmpegCommand,
+      ffprobeCommand,
+      nonSpatialXrSource.outputPath,
+    );
+  }
+  console.log(
+    `Completed ${sourceVideos.length + (spatialMetadataSource ? 1 : 0)} promotional videos.`,
+  );
+}
+
+main().catch((error) => {
+  console.error(`Promo generation failed: ${error.message}`);
+  process.exitCode = 1;
+});