codeplay-common 4.6.4 → 4.6.6

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

@@ -1,2085 +1,2085 @@
-// 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 --layout dynamic
-// Optional: node generate-ai-promo-video.js --input path/to/source.mp4 --output path/to/output.mp4
-
-// node generate-ai-promo-video.js --layout dynamic
-// node generate-ai-promo-video.js --layout split
-// node generate-ai-promo-video.js --layout centered
-// node generate-ai-promo-video.js --layout floating
-// node generate-ai-promo-video.js --layout cinematic
-// node generate-ai-promo-video.js --layout mixed
-// node generate-ai-promo-video.js --layout random
-
-
-const fs = require('node:fs');
-const path = require('node:path');
-const { createHash } = require('node:crypto');
-const { spawnSync } = require('node:child_process');
-const { createInterface } = require('node:readline/promises');
-
-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();
-const iosStoreConfigPath = path.join(projectDirectory, 'Auto-AI-Video', 'ios-store-config.json');
-let iosStoreConfig = {};
-if (fs.existsSync(iosStoreConfigPath)) {
-  try {
-    iosStoreConfig = JSON.parse(fs.readFileSync(iosStoreConfigPath, 'utf8'));
-  } catch {
-    iosStoreConfig = {};
-  }
-}
-
-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 configuredAppStoreUrl = String(iosStoreConfig.appStoreUrl || '')
-  .match(/https:\/\/apps\.apple\.com\/app\/id\d+/)?.[0] || '';
-let appStoreDownloadUrl = /^https:\/\/apps\.apple\.com\/app\/id\d+$/.test(configuredAppStoreUrl)
-  ? configuredAppStoreUrl
-  : '';
-const promoDesignIndex = createHash('sha1').update(`${appUniqueId}:${appName}`).digest()[0] % 4;
-const promoDesigns = [
-  { accent: '0x23d5c3', background: '0x07101f', panelX: 105, panelWidth: 500, phoneX: 134 },
-  { accent: '0xffb020', background: '0x241006', panelX: 1290, panelWidth: 500, phoneX: 64 },
-  { accent: '0x9b7cff', background: '0x160d2b', panelX: 105, panelWidth: 620, phoneX: 134 },
-  { accent: '0xff5b8d', background: '0x21101a', panelX: 1240, panelWidth: 550, phoneX: 64 },
-];
-const promoDesign = promoDesigns[promoDesignIndex];
-const promoLayoutNames = [
-  'dynamic',
-  'split',
-  'centered',
-  'floating',
-  'cinematic',
-  'mixed',
-  'random',
-];
-const selectablePromoLayoutNames = promoLayoutNames.filter((layoutName) => layoutName !== 'random');
-let endCardStart = 0;
-const endCardDuration = 8;
-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, 'resources', 'icon-only.png');
-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 endCardBannerPath = path.join(outputVideoDirectory, `${appFilePrefix}-ai-end-card-banner.png`);
-const promoCopySchemaPath = path.join(temporaryDirectory, 'promo-copy-schema.json');
-const promoCopyResultPath = path.join(temporaryDirectory, 'promo-copy-result.json');
-const ffmpegFallbackDirectory = String(process.env.FFMPEG_BIN || '').trim();
-const minimumSceneCount = 7;
-const minimumSourceDuration = 12;
-let expectedDuration = 34;
-let editSegments = [];
-let sceneWindows = [];
-let sceneCount = minimumSceneCount;
-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 = 5;
-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';
-}
-
-async function ensureEndCardBanner() {
-  if (fs.existsSync(endCardBannerPath)) return;
-  throw new Error(
-    `AI end-card banner is missing. Generate it manually and save it here:\n${endCardBannerPath}\n\n`
-      + 'Create a promotional video end-card banner for this application.\n\n'
-      + 'Requirements:\n'
-      + '- Final image size must be exactly 1672 × 941 pixels.\n'
-      + '- Save it as:\n'
-      + `  ${endCardBannerPath}\n`
-      + `- Use this exact app icon file: ${iconPath}\n`
-      + '- Do not generate, redraw, reinterpret, or replace the app icon.\n'
-      + '- Use the complete official black “Download on the App Store” badge.\n'
-      + '- Use the complete official black “Get it on Google Play” badge.\n'
-      + '- Download the official badges from Apple and Google if they are not available in the project.\n'
-      + '- Do not generate or imitate the Apple, Google Play, or application logos.\n'
-      + '- Keep all logos and badge text sharp, correctly proportioned, and completely visible.\n'
-      + '- Match the background colors and visual style to the actual app icon.\n'
-      + '- Create a polished, professional background related to the app’s purpose.\n'
+// 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 --layout dynamic
+// Optional: node generate-ai-promo-video.js --input path/to/source.mp4 --output path/to/output.mp4
+
+// node generate-ai-promo-video.js --layout dynamic
+// node generate-ai-promo-video.js --layout split
+// node generate-ai-promo-video.js --layout centered
+// node generate-ai-promo-video.js --layout floating
+// node generate-ai-promo-video.js --layout cinematic
+// node generate-ai-promo-video.js --layout mixed
+// node generate-ai-promo-video.js --layout random
+
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { createHash } = require('node:crypto');
+const { spawnSync } = require('node:child_process');
+const { createInterface } = require('node:readline/promises');
+
+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();
+const iosStoreConfigPath = path.join(projectDirectory, 'Auto-AI-Video', 'ios-store-config.json');
+let iosStoreConfig = {};
+if (fs.existsSync(iosStoreConfigPath)) {
+  try {
+    iosStoreConfig = JSON.parse(fs.readFileSync(iosStoreConfigPath, 'utf8'));
+  } catch {
+    iosStoreConfig = {};
+  }
+}
+
+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 configuredAppStoreUrl = String(iosStoreConfig.appStoreUrl || '')
+  .match(/https:\/\/apps\.apple\.com\/app\/id\d+/)?.[0] || '';
+let appStoreDownloadUrl = /^https:\/\/apps\.apple\.com\/app\/id\d+$/.test(configuredAppStoreUrl)
+  ? configuredAppStoreUrl
+  : '';
+const promoDesignIndex = createHash('sha1').update(`${appUniqueId}:${appName}`).digest()[0] % 4;
+const promoDesigns = [
+  { accent: '0x23d5c3', background: '0x07101f', panelX: 105, panelWidth: 500, phoneX: 134 },
+  { accent: '0xffb020', background: '0x241006', panelX: 1290, panelWidth: 500, phoneX: 64 },
+  { accent: '0x9b7cff', background: '0x160d2b', panelX: 105, panelWidth: 620, phoneX: 134 },
+  { accent: '0xff5b8d', background: '0x21101a', panelX: 1240, panelWidth: 550, phoneX: 64 },
+];
+const promoDesign = promoDesigns[promoDesignIndex];
+const promoLayoutNames = [
+  'dynamic',
+  'split',
+  'centered',
+  'floating',
+  'cinematic',
+  'mixed',
+  'random',
+];
+const selectablePromoLayoutNames = promoLayoutNames.filter((layoutName) => layoutName !== 'random');
+let endCardStart = 0;
+const endCardDuration = 8;
+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, 'resources', 'icon-only.png');
+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 endCardBannerPath = path.join(outputVideoDirectory, `${appFilePrefix}-ai-end-card-banner.png`);
+const promoCopySchemaPath = path.join(temporaryDirectory, 'promo-copy-schema.json');
+const promoCopyResultPath = path.join(temporaryDirectory, 'promo-copy-result.json');
+const ffmpegFallbackDirectory = String(process.env.FFMPEG_BIN || '').trim();
+const minimumSceneCount = 7;
+const minimumSourceDuration = 12;
+let expectedDuration = 34;
+let editSegments = [];
+let sceneWindows = [];
+let sceneCount = minimumSceneCount;
+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 = 5;
+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';
+}
+
+async function ensureEndCardBanner() {
+  if (fs.existsSync(endCardBannerPath)) return;
+  throw new Error(
+    `AI end-card banner is missing. Generate it manually and save it here:\n${endCardBannerPath}\n\n`
+      + 'Create a promotional video end-card banner for this application.\n\n'
+      + 'Requirements:\n'
+      + '- Final image size must be exactly 1672 × 941 pixels.\n'
+      + '- Save it as:\n'
+      + `  ${endCardBannerPath}\n`
+      + `- Use this exact app icon file: ${iconPath}\n`
+      + '- Do not generate, redraw, reinterpret, or replace the app icon.\n'
+      + '- Use the complete official black “Download on the App Store” badge.\n'
+      + '- Use the complete official black “Get it on Google Play” badge.\n'
+      + '- Download the official badges from Apple and Google if they are not available in the project.\n'
+      + '- Do not generate or imitate the Apple, Google Play, or application logos.\n'
+      + '- Keep all logos and badge text sharp, correctly proportioned, and completely visible.\n'
+      + '- Match the background colors and visual style to the actual app icon.\n'
+      + '- Create a polished, professional background related to the app’s purpose.\n'
       + '- Keep the background subtle so it does not compete with the icon, title, feature text, or download badges.\n'
-      + '- Use a balanced landscape composition:\n'
-      + '  - Large actual app icon on the left.\n'
-      + '  - App Store badge followed by Google Play badge on the right.\n'
-      + '  - Maintain comfortable margins and clear space around every element.\n'
+      + '- Use a balanced landscape composition:\n'
+      + '  - Large actual app icon on the left.\n'
+      + '  - App Store badge followed by Google Play badge on the right.\n'
+      + '  - Maintain comfortable margins and clear space around every element.\n'
       + '- Add the application title prominently.\n'
       + '- Add concise promotional text describing the application’s actual features, presenting each feature one by one.\n'
       + '- Keep the title and feature text sharp, readable, accurate, and visually balanced with the icon and download badges.\n'
       + '- Do not invent unsupported features or add unrelated marketing text.\n'
-      + '- Do not add watermarks, fake UI, generated symbols, or unrelated decorations.\n'
-      + '- Rounded corners and a subtle shadow may be applied around the app icon, but its internal artwork must remain unchanged.\n'
-      + '- Use image generation only for the background.\n'
-      + '- Composite the actual app icon and official store badges afterward.\n'
-      + '- Replace the specified output file if it already exists.\n'
-      + '- Verify the final PNG dimensions are exactly 1672 × 941.\n'
-      + '- Visually inspect the completed image before finishing.\n'
-      + '- Report the final saved path.\n\n'
-      + 'Then run the video-generation command again.',
-  );
-}
-
-async function ensureAppStoreDownloadUrl() {
-  if (appStoreDownloadUrl) return;
-  const readline = createInterface({ input: process.stdin, output: process.stdout });
-  try {
-    const appStoreId = (await readline.question(
-      'Enter the iOS App Store ID (press Enter to skip): ',
-    )).trim();
-    if (!appStoreId) return;
-    if (!/^\d+$/.test(appStoreId)) {
-      throw new Error('iOS App Store ID must contain digits only.');
-    }
-    appStoreDownloadUrl = `https://apps.apple.com/app/id${appStoreId}`;
-    iosStoreConfig = { ...iosStoreConfig, appStoreUrl: appStoreDownloadUrl };
-    fs.mkdirSync(path.dirname(iosStoreConfigPath), { recursive: true });
-    fs.writeFileSync(iosStoreConfigPath, `${JSON.stringify(iosStoreConfig, null, 2)}\n`, 'utf8');
-    console.log(`Saved iOS App Store URL to ${iosStoreConfigPath}`);
-  } finally {
-    readline.close();
-  }
-}
-
-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 mapSourceTimeToOutput(sourceTime) {
-  let outputTime = 0;
-  for (const segment of editSegments) {
-    if (sourceTime < segment.start) return outputTime;
-    if (sourceTime <= segment.end) return outputTime + (sourceTime - segment.start);
-    outputTime += segment.end - segment.start;
-  }
-  return outputTime;
-}
-
-function normalizeSkippedRanges(skippedRanges, sourceDuration) {
-  const ranges = skippedRanges
-    .map((range) => ({
-      start: Math.max(0, Math.min(sourceDuration, range.start)),
-      end: Math.max(0, Math.min(sourceDuration, range.end)),
-    }))
-    .filter((range) => range.end > range.start)
-    .sort((left, right) => left.start - right.start);
-
-  return ranges.reduce((merged, range) => {
-    const previous = merged.at(-1);
-    if (previous && range.start <= previous.end) {
-      previous.end = Math.max(previous.end, range.end);
-    } else {
-      merged.push({ ...range });
-    }
-    return merged;
-  }, []);
-}
-
-function buildRetainedSegments(sourceDuration, skippedRanges) {
-  const normalizedRanges = normalizeSkippedRanges(skippedRanges, sourceDuration);
-  const retainedSegments = [];
-  let retainedStart = 0;
-
-  for (const range of normalizedRanges) {
-    if (range.start > retainedStart) {
-      retainedSegments.push({ start: retainedStart, end: range.start });
-    }
-    retainedStart = range.end;
-  }
-  if (retainedStart < sourceDuration) {
-    retainedSegments.push({ start: retainedStart, end: sourceDuration });
-  }
-
-  return {
-    retainedSegments: retainedSegments.map((segment) => ({
-      start: roundTimelineValue(segment.start),
-      end: roundTimelineValue(segment.end),
-    })),
-    skippedDuration: normalizedRanges.reduce(
-      (total, range) => total + (range.end - range.start),
-      0,
-    ),
-  };
-}
-
-function buildSceneWindows(retainedDuration, visualChangeTimes) {
-  const minimumWindowDuration = Math.max(2.5, Math.min(4, retainedDuration / 40));
-  const maximumWindowDuration = Math.max(6, Math.min(10, retainedDuration / 14));
-  const boundaries = [0];
-  const mappedChanges = visualChangeTimes
-    .map((sourceTime) => mapSourceTimeToOutput(sourceTime))
-    .filter((outputTime) => outputTime > 0 && outputTime < retainedDuration)
-    .sort((left, right) => left - right);
-
-  for (const changeTime of mappedChanges) {
-    if (changeTime - boundaries.at(-1) >= minimumWindowDuration) {
-      boundaries.push(changeTime);
-    }
-  }
-  if (retainedDuration - boundaries.at(-1) < minimumWindowDuration) boundaries.pop();
-  boundaries.push(retainedDuration);
-
-  const windows = [];
-  for (let index = 0; index < boundaries.length - 1; index += 1) {
-    const start = boundaries[index];
-    const end = boundaries[index + 1];
-    const splitCount = Math.max(1, Math.ceil((end - start) / maximumWindowDuration));
-    for (let splitIndex = 0; splitIndex < splitCount; splitIndex += 1) {
-      windows.push({
-        start: roundTimelineValue(start + (((end - start) * splitIndex) / splitCount)),
-        end: roundTimelineValue(start + (((end - start) * (splitIndex + 1)) / splitCount)),
-      });
-    }
-  }
-
-  if (windows.length >= minimumSceneCount) return windows;
-  return Array.from({ length: minimumSceneCount }, (_, index) => ({
-    start: roundTimelineValue((retainedDuration * index) / minimumSceneCount),
-    end: index === minimumSceneCount - 1
-      ? retainedDuration
-      : roundTimelineValue((retainedDuration * (index + 1)) / minimumSceneCount),
-  }));
-}
-
-function configurePromoTimeline(sourceDuration, skippedRanges = [], visualChangeTimes = []) {
-  if (!Number.isFinite(sourceDuration) || sourceDuration < minimumSourceDuration) {
-    throw new Error(
-      `The shortest source video must be at least ${minimumSourceDuration} seconds.`,
-    );
-  }
-
-  const { retainedSegments, skippedDuration } = buildRetainedSegments(
-    sourceDuration,
-    skippedRanges,
-  );
-  editSegments = retainedSegments.filter((segment) => segment.end > segment.start);
-  const retainedDuration = editSegments.reduce(
-    (total, segment) => total + (segment.end - segment.start),
-    0,
-  );
-  if (retainedDuration < minimumSourceDuration) {
-    throw new Error(
-      `At least ${minimumSourceDuration} seconds must remain after automatic cleanup.`,
-    );
-  }
-
-  expectedDuration = roundTimelineValue(retainedDuration);
-  sceneWindows = buildSceneWindows(expectedDuration, visualChangeTimes).map((window) => {
-    const sceneDuration = window.end - window.start;
-    return {
-      ...window,
-      sourceTime: roundTimelineValue(mapOutputTimeToSource(
-        window.start + (sceneDuration / 2),
-      )),
-      maxNarrationWords: Math.max(7, Math.floor(sceneDuration * 2.15)),
-    };
-  });
-  sceneCount = sceneWindows.length;
-  promoCopySchema.properties.scenes.minItems = sceneCount;
-  promoCopySchema.properties.scenes.maxItems = sceneCount;
-  endCardStart = expectedDuration;
-  expectedDuration = roundTimelineValue(expectedDuration + endCardDuration);
-
-  console.log(
-    `Feature-complete promo timeline: ${expectedDuration}s from ${sourceDuration.toFixed(2)}s source; `
-      + `${sceneCount} scenes and ${editSegments.length} retained segment${editSegments.length === 1 ? '' : 's'}`
-      + `${skippedDuration > 0 ? ` (${skippedDuration.toFixed(2)}s of redundant static footage removed)` : ''}.`,
-  );
-}
-
-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;
-
-  if (!ffmpegFallbackDirectory) return '';
-  const executableName = process.platform === 'win32' ? `${command}.exe` : command;
-  const fallbackPath = path.join(ffmpegFallbackDirectory, executableName);
-  return fs.existsSync(fallbackPath) ? fallbackPath : '';
-}
-
-function detectRedundantStaticRanges(ffmpegCommand, inputPath, sourceDuration) {
-  const minimumStaticDuration = Math.max(2, Math.min(4, sourceDuration / 60));
-  const result = spawnSync(ffmpegCommand, [
-    '-hide_banner',
-    '-nostats',
-    '-i', inputPath,
-    '-vf', `freezedetect=n=-50dB:d=${minimumStaticDuration}`,
-    '-an',
-    '-f', 'null',
-    process.platform === 'win32' ? 'NUL' : '/dev/null',
-  ], {
-    encoding: 'utf8',
-    windowsHide: true,
-    maxBuffer: 10 * 1024 * 1024,
-  });
-  if (result.error || result.status !== 0) {
-    console.warn('Static-screen analysis was unavailable; retaining the complete recording.');
-    return [];
-  }
-
-  const events = String(result.stderr || '').matchAll(
-    /lavfi\.freezedetect\.freeze_(start|end):\s*([\d.]+)/g,
-  );
-  const staticRanges = [];
-  let staticStart = null;
-  for (const event of events) {
-    const time = Number(event[2]);
-    if (event[1] === 'start') {
-      staticStart = time;
-    } else if (staticStart !== null && time > staticStart) {
-      staticRanges.push({ start: staticStart, end: time });
-      staticStart = null;
-    }
-  }
-  if (staticStart !== null && sourceDuration > staticStart) {
-    staticRanges.push({ start: staticStart, end: sourceDuration });
-  }
-
-  return staticRanges
-    .map((range) => ({
-      start: range.start + minimumStaticDuration,
-      end: range.end,
-    }))
-    .filter((range) => range.end - range.start >= 0.75);
-}
-
-function detectVisualChangeTimes(ffmpegCommand, inputPath) {
-  const result = spawnSync(ffmpegCommand, [
-    '-hide_banner',
-    '-nostats',
-    '-i', inputPath,
-    '-vf', "select='gt(scene,0.03)',showinfo",
-    '-an',
-    '-f', 'null',
-    process.platform === 'win32' ? 'NUL' : '/dev/null',
-  ], {
-    encoding: 'utf8',
-    windowsHide: true,
-    maxBuffer: 10 * 1024 * 1024,
-  });
-  if (result.error || result.status !== 0) {
-    console.warn('Visual-change analysis was unavailable; using duration-based scene coverage.');
-    return [];
-  }
-  return [...String(result.stderr || '').matchAll(/pts_time:([\d.]+)/g)]
-    .map((match) => Number(match[1]))
-    .filter(Number.isFinite);
-}
-
-function parseArguments() {
-  const args = process.argv.slice(2);
-  const options = {
-    aiModel: '',
-    aiProvider: 'auto',
-    copyOnly: false,
-    input: '',
-    layout: 'split',
-    layoutExplicit: false,
-    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 === '--layout') {
-      options.layout = String(args[index + 1] || '').trim().toLowerCase();
-      options.layoutExplicit = true;
-      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 --layout dynamic|split|centered|floating|cinematic|mixed|random');
-      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.`,
-      );
-      console.log('Redundant static pauses are shortened automatically; distinct screens are retained.');
-      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 (!promoLayoutNames.includes(options.layout)) {
-    throw new Error(`--layout must be one of: ${promoLayoutNames.join(', ')}.`);
-  }
-  if (options.output && !options.input) {
-    throw new Error('--output can only be used together with --input.');
-  }
-
-  return options;
-}
-
-function resolvePromoLayout(requestedLayout) {
-  if (requestedLayout !== 'random') return requestedLayout;
-  return selectablePromoLayoutNames[Math.floor(Math.random() * selectablePromoLayoutNames.length)];
-}
-
-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 escapeFilterText(value) {
-  return String(value).replace(/\\/g, '\\\\').replace(/'/g, "\\'").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 getCodexCandidates() {
-  const candidates = ['codex'];
-  const configuredCodexPath = String(process.env.CODEX_BIN || '').trim();
-  if (configuredCodexPath) candidates.unshift(configuredCodexPath);
-
-  if (process.platform === 'win32') {
-    const userProfile = process.env.USERPROFILE || process.env.HOME;
-    const extensionRoots = [
-      path.join(userProfile || '', '.vscode', 'extensions'),
-      path.join(userProfile || '', '.vscode-insiders', 'extensions'),
-      path.join(userProfile || '', '.vscode-server', 'extensions'),
-      path.join(userProfile || '', '.vscode-server-insiders', 'extensions'),
-    ];
-    const executableNames = ['codex.exe', 'codex'];
-
-    for (const extensionRoot of extensionRoots) {
-      if (!fs.existsSync(extensionRoot)) continue;
-      for (const extensionName of fs.readdirSync(extensionRoot)) {
-        if (!/^openai\.chatgpt-/i.test(extensionName)) continue;
-        const extensionPath = path.join(extensionRoot, extensionName, 'bin');
-        if (!fs.existsSync(extensionPath)) continue;
-        for (const platformDirectory of fs.readdirSync(extensionPath)) {
-          for (const executableName of executableNames) {
-            candidates.push(path.join(extensionPath, platformDirectory, executableName));
-          }
-        }
-      }
-    }
-  }
-
-  return [...new Set(candidates)];
-}
-
-function getCodexExecutable() {
-  for (const candidate of getCodexCandidates()) {
-    const versionResult = spawnSync(candidate, ['--version'], {
-      encoding: 'utf8',
-      windowsHide: true,
-    });
-    if (versionResult.error || versionResult.status !== 0) continue;
-
-    const loginResult = spawnSync(candidate, ['login', 'status'], {
-      encoding: 'utf8',
-      windowsHide: true,
-    });
-    if (!loginResult.error && loginResult.status === 0) return candidate;
-  }
-  return '';
-}
-
-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.
-- Cover every distinct demonstrated feature across the retained recording; do not omit later features.
-- Do not promote incidental navigation, loading states, advertisements, permission prompts, or repeated screens as features.
-- Keep each scene specific to what is visibly demonstrated in its supplied image whenever possible.
-- 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 iosBlock = appStoreDownloadUrl
-    ? `\n\nDownload ${appName} on the App Store:\n${appStoreDownloadUrl}`
-    : '';
-  const downloadBlock = `Download ${appName} on Google Play:\n${playStoreDownloadUrl}${iosBlock}`;
-
-  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 maximumNarrationWords = sceneWindows[sceneIndex].maxNarrationWords;
-    const narrationWords = cleanedScene.narration.split(/\s+/);
-    if (narrationWords.length > maximumNarrationWords) {
-      cleanedScene.narration = narrationWords.slice(0, maximumNarrationWords).join(' ');
-    }
-    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 <= 3; 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 === 3 || /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,
-      appStoreDownloadUrl,
-      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 getSceneComposition(layoutName, sceneIndex) {
-  const left = {
-    bodyY: 470,
-    phoneX: '90',
-    phoneY: '50',
-    styleSuffix: 'Left',
-    textX: 720,
-    titleY: 270,
-    kickerY: 225,
-  };
-  const right = {
-    ...left,
-    phoneX: 'W-w-90',
-    textX: 110,
-  };
-  const centered = {
-    bodyY: 925,
-    phoneX: '(W-w)/2',
-    phoneY: '220',
-    styleSuffix: 'Center',
-    textX: 960,
-    titleY: 102,
-    kickerY: 66,
-  };
-  const mixedCentered = {
-    ...left,
-    phoneX: '(W-w)/2',
-    phoneY: '110',
-    textX: 80,
-  };
-  const floating = {
-    ...left,
-    phoneX: '125+24*sin(t*0.8)',
-    phoneY: '110+14*cos(t*0.65)',
-    textX: 1050,
-  };
-  const cinematic = {
-    bodyY: 925,
-    phoneX: '(W-w)/2',
-    phoneY: '0',
-    styleSuffix: 'Center',
-    textX: 960,
-    titleY: 745,
-    kickerY: 705,
-  };
-
-  if (layoutName === 'dynamic') return sceneIndex % 2 === 0 ? left : right;
-  if (layoutName === 'centered') return centered;
-  if (layoutName === 'floating') return floating;
-  if (layoutName === 'cinematic') return cinematic;
-  if (layoutName === 'mixed') {
-    return [left, right, mixedCentered, floating, cinematic][sceneIndex % 5];
-  }
-  return left;
-}
-
-function getGlobalCaptionComposition(layoutName) {
-  if (layoutName === 'split') {
-    return {
-      brandStyle: 'BrandLeft', brandX: 720, brandY: 78,
-      footerStyle: 'FooterLeft', footerX: 720, footerY: 1008,
-    };
-  }
-  if (layoutName === 'floating') {
-    return {
-      brandStyle: 'BrandLeft', brandX: 1050, brandY: 78,
-      footerStyle: 'FooterLeft', footerX: 1050, footerY: 1008,
-    };
-  }
-  return {
-    brandStyle: 'BrandCenter', brandX: 960,
-    brandY: ['centered', 'mixed'].includes(layoutName) ? 18 : 78,
-    footerStyle: 'FooterCenter', footerX: 960, footerY: 1008,
-  };
-}
-
-function createCaptionFile(promoCopy, layoutName) {
-  const captionAppName = escapeAssText(appName.toUpperCase());
-  const events = sceneWindows.flatMap((window, index) => {
-    const scene = promoCopy.scenes[index];
-    const composition = getSceneComposition(layoutName, index);
-    const start = formatAssTime(window.start);
-    const end = formatAssTime(window.end);
-    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${composition.styleSuffix},,0,0,0,,{\\pos(${composition.textX},${composition.kickerY})${fade}}${escapeAssText(scene.kicker.toUpperCase())}`,
-      `Dialogue: 0,${start},${end},Title${composition.styleSuffix},,0,0,0,,{\\pos(${composition.textX},${composition.titleY})${fade}}${escapeAssText(scene.title_line_1.toUpperCase())}\\N${escapeAssText(scene.title_line_2.toUpperCase())}`,
-      `Dialogue: 0,${start},${end},Body${composition.styleSuffix},,0,0,0,,{\\pos(${composition.textX},${composition.bodyY})${fade}}${escapeAssText(scene.body)}`,
-    ];
-  });
-  const globalComposition = getGlobalCaptionComposition(layoutName);
-  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: BrandLeft,Segoe UI,30,&H00FFFFFF,&H00FFFFFF,&H50000000,&H00000000,1,0,0,0,100,100,2,0,1,1,0,7,0,0,0,1
-Style: BrandCenter,Segoe UI,30,&H00FFFFFF,&H00FFFFFF,&H50000000,&H00000000,1,0,0,0,100,100,2,0,1,1,0,8,0,0,0,1
-Style: KickerLeft,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: KickerCenter,Segoe UI Semibold,23,&H00C3D523,&H00C3D523,&H50000000,&H00000000,1,0,0,0,100,100,2,0,1,1,0,8,0,0,0,1
-Style: TitleLeft,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: TitleCenter,Segoe UI Semibold,58,&H00FFFFFF,&H00FFFFFF,&H80000000,&H00000000,1,0,0,0,100,100,0,0,1,2,0,8,0,0,0,1
-Style: BodyLeft,Segoe UI,35,&H00D8E3F0,&H00D8E3F0,&H70000000,&H00000000,0,0,0,0,100,100,0,0,1,1,0,7,0,0,0,1
-Style: BodyCenter,Segoe UI,29,&H00D8E3F0,&H00D8E3F0,&H70000000,&H00000000,0,0,0,0,100,100,0,0,1,1,0,8,0,0,0,1
-Style: FooterLeft,Segoe UI Semibold,22,&H00FFFFFF,&H00FFFFFF,&H50000000,&H00000000,1,0,0,0,100,100,2,0,1,1,0,7,0,0,0,1
-Style: FooterCenter,Segoe UI Semibold,22,&H00FFFFFF,&H00FFFFFF,&H50000000,&H00000000,1,0,0,0,100,100,2,0,1,1,0,8,0,0,0,1
-
-[Events]
-Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
-Dialogue: 0,0:00:00.00,${formatAssTime(expectedDuration)},${globalComposition.brandStyle},,0,0,0,,{\\pos(${globalComposition.brandX},${globalComposition.brandY})\\fad(350,350)}${captionAppName}
-${events.join('\n')}
-Dialogue: 0,0:00:00.00,${formatAssTime(expectedDuration)},${globalComposition.footerStyle},,0,0,0,,{\\pos(${globalComposition.footerX},${globalComposition.footerY})\\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],
-    );
-  });
-
-  const endCardPath = path.join(segmentDirectory, 'end-card.mp3');
-  synthesizeNeuralSpeech(
-    pythonCommand,
-    voiceName,
-    appStoreDownloadUrl
-      ? 'Now available on Google Play and the App Store. Download links are available in the description.'
-      : 'Now available on Google Play. The download link is available in the description.',
-    endCardPath,
-  );
-  segmentPaths.push(endCardPath);
-
-  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 endCardFilter = segmentPaths.length > sceneWindows.length
-    ? `[${sceneWindows.length}:a]aresample=48000,aformat=sample_fmts=fltp:channel_layouts=stereo,adelay=${endCardStart * 1000}|${endCardStart * 1000},apad=whole_dur=${expectedDuration}[endcard]`
-    : '';
-  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]`,
-    endCardFilter,
-    endCardFilter ? '[narration][endcard]amix=inputs=2:normalize=0:duration=longest,loudnorm=I=-16:TP=-2:LRA=7[narration-final]' : '',
-  ].filter(Boolean).join(';');
-
-  run(ffmpegCommand, [
-    '-hide_banner',
-    '-y',
-    ...inputArguments,
-    '-filter_complex', filterGraph,
-    '-map', endCardFilter ? '[narration-final]' : '[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 duration = Number(details.format?.duration || 0);
-
-  if (!videoStream) throw new Error('The source must contain a video stream.');
-  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 ensureAudioStream(ffmpegCommand, inputPath, details) {
-  const hasAudioStream = details.streams?.some((stream) => stream.codec_type === 'audio');
-  if (hasAudioStream) return inputPath;
-
-  const sourceHash = createHash('sha1').update(inputPath).digest('hex').slice(0, 12);
-  const audioFallbackPath = path.join(
-    temporaryDirectory,
-    `${sanitizeFileNamePart(path.basename(inputPath, path.extname(inputPath)))}-${sourceHash}-with-silent-audio.mp4`,
-  );
-  if (!fs.existsSync(audioFallbackPath)) {
-    const duration = Number(details.format?.duration || 0);
-    console.log(`Adding a silent audio track to video-only source: ${inputPath}`);
-    fs.mkdirSync(temporaryDirectory, { recursive: true });
-    run(ffmpegCommand, [
-      '-hide_banner',
-      '-y',
-      '-i', inputPath,
-      '-f', 'lavfi',
-      '-t', String(duration),
-      '-i', 'anullsrc=channel_layout=stereo:sample_rate=48000',
-      '-map', '0:v:0',
-      '-map', '1:a:0',
-      '-c:v', 'copy',
-      '-c:a', 'aac',
-      '-b:a', '192k',
-      '-ar', '48000',
-      '-t', String(duration),
-      '-movflags', '+faststart',
-      audioFallbackPath,
-    ]);
-  }
-  return audioFallbackPath;
-}
-
-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 getPromoLayoutSettings(layoutName) {
-  const settings = {
-    cinematic: { backgroundBrightness: '-0.28', backgroundSaturation: '1.05', phoneHeight: 1080 },
-    centered: { backgroundBrightness: '-0.42', backgroundSaturation: '1.18', phoneHeight: 650 },
-    dynamic: { backgroundBrightness: '-0.44', backgroundSaturation: '1.35', phoneHeight: 920 },
-    floating: { backgroundBrightness: '-0.38', backgroundSaturation: '1.25', phoneHeight: 860 },
-    mixed: { backgroundBrightness: '-0.42', backgroundSaturation: '1.30', phoneHeight: 860 },
-    split: { backgroundBrightness: '-0.40', backgroundSaturation: '1.30', phoneHeight: 980 },
-  };
-  return settings[layoutName] || settings.split;
-}
-
-function buildScenePositionExpression(layoutName, propertyName) {
-  const values = sceneWindows.map((_, index) => getSceneComposition(layoutName, index)[propertyName]);
-  if (values.every((value) => value === values[0])) return values[0];
-
-  let expression = values.at(-1);
-  for (let index = values.length - 2; index >= 0; index -= 1) {
-    const window = sceneWindows[index];
-    expression = `if(between(t\\,${window.start}\\,${window.end})\\,${values[index]}\\,${expression})`;
-  }
-  return expression;
-}
-
-function buildPromoStageFilter(layoutName) {
-  const accent = promoDesign.accent;
-  if (layoutName === 'dynamic') {
-    return `[background]drawbox=x=45:y=35:w=610:h=1010:color=black@0.38:t=fill,drawbox=x=1265:y=35:w=610:h=1010:color=black@0.38:t=fill,drawbox=x=52:y=42:w=596:h=996:color=${accent}@0.38:t=3,drawbox=x=1272:y=42:w=596:h=996:color=${accent}@0.38:t=3,drawbox=x=690:y=105:w=540:h=3:color=${accent}@0.72:t=fill[stage]`;
-  }
-  if (layoutName === 'centered') {
-    return `[background]drawbox=x=0:y=18:w=1920:h=170:color=black@0.62:t=fill,drawbox=x=0:y=875:w=1920:h=180:color=black@0.68:t=fill,drawbox=x=612:y=210:w=696:h=670:color=${accent}@0.46:t=4,drawbox=x=660:y=200:w=600:h=3:color=${accent}@0.78:t=fill[stage]`;
-  }
-  if (layoutName === 'floating') {
-    return `[background]drawbox=x=55:y=55:w=680:h=970:color=black@0.52:t=fill,drawbox=x=63:y=63:w=664:h=954:color=${accent}@0.52:t=4,drawbox=x=960:y=175:w=900:h=650:color=black@0.46:t=fill,drawbox=x=978:y=195:w=6:h=610:color=${accent}@0.85:t=fill[stage]`;
-  }
-  if (layoutName === 'cinematic') {
-    return '[background]null[stage]';
-  }
-  if (layoutName === 'mixed') {
-    return `[background]drawbox=x=35:y=28:w=1850:h=1024:color=black@0.32:t=fill,drawbox=x=43:y=36:w=1834:h=1008:color=${accent}@0.30:t=3,drawbox=x=640:y=80:w=3:h=920:color=white@0.10:t=fill,drawbox=x=1277:y=80:w=3:h=920:color=white@0.10:t=fill,drawbox=x=90:y=690:w=1740:h=3:color=${accent}@0.62:t=fill[stage]`;
-  }
-  return `[background]drawbox=x=45:y=30:w=570:h=1020:color=black@0.58:t=fill,drawbox=x=52:y=37:w=556:h=1006:color=${accent}@0.42:t=3,drawbox=x=680:y=176:w=1050:h=2:color=${accent}@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=${accent}@0.90:t=fill[stage]`;
-}
-
-function buildPromoForegroundFilter(layoutName) {
-  if (layoutName !== 'cinematic') return '[layout]null[layoutfinished]';
-  return `[layout]drawbox=x=0:y=0:w=1920:h=145:color=black@0.52:t=fill,drawbox=x=0:y=665:w=1920:h=415:color=black@0.72:t=fill,drawbox=x=90:y=690:w=1740:h=3:color=${promoDesign.accent}@0.80:t=fill[layoutfinished]`;
-}
-
-function getFinalSceneIconPosition(layoutName) {
-  const composition = getSceneComposition(layoutName, sceneWindows.length - 1);
-  if (composition.styleSuffix === 'Center') return { x: 80, y: 850 };
-  return { x: composition.textX, y: 650 };
-}
-
-function generatePromo(
-  ffmpegCommand,
-  inputPath,
-  outputPath,
-  crop,
-  targetWidth,
-  targetHeight,
-  layoutName,
-) {
-  const subtitleFilterPath = escapeFilterPath(captionPath);
-  const layoutSettings = getPromoLayoutSettings(layoutName);
-  const phoneX = buildScenePositionExpression(layoutName, 'phoneX');
-  const phoneY = buildScenePositionExpression(layoutName, 'phoneY');
-  const iconPosition = getFinalSceneIconPosition(layoutName);
-  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,tpad=stop_mode=clone:stop_duration=${endCardDuration},split=2[bgsrc][phonesrc]`
-    : `${editSegments.map((_, index) => `[v${index}]`).join('')}concat=n=${segmentCount}:v=1:a=0,fps=30,setpts=PTS-STARTPTS,tpad=stop_mode=clone:stop_duration=${endCardDuration},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=${layoutSettings.backgroundBrightness}:saturation=${layoutSettings.backgroundSaturation},drawbox=x=0:y=0:w=iw:h=ih:color=${promoDesign.background}@0.72:t=fill[background]`,
-    buildPromoStageFilter(layoutName),
-    `[phonesrc]scale=-2:${layoutSettings.phoneHeight},setsar=1[phone]`,
-    `[stage][phone]overlay=x='${phoneX}':y='${phoneY}':eval=frame:shortest=1[layout]`,
-    buildPromoForegroundFilter(layoutName),
-    '[1:v]scale=145:145,format=rgba,colorchannelmixer=aa=0.96[icon]',
-    `[layoutfinished][icon]overlay=x=${iconPosition.x}:y=${iconPosition.y}: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[captioned]`,
-    `[3:v]scale=1920:1080,format=yuv420p[cardbanner]`,
-    `[captioned][cardbanner]overlay=eof_action=repeat:enable=between(t\\,${endCardStart}\\,${expectedDuration})[cardonly]`,
-    `[cardonly]scale=${targetWidth}:${targetHeight}:flags=lanczos,setsar=1,format=yuv420p[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,
-    '-loop', '1',
-    '-i', endCardBannerPath,
-    '-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 getLayoutOutputSuffix(options, layoutName) {
-  if (!options.layoutExplicit) return '';
-  return options.layout === 'random'
-    ? `-layout-random-${layoutName}`
-    : `-layout-${layoutName}`;
-}
-
-function getBatchOutputPath(inputPath, targetWidth, targetHeight, layoutSuffix = '') {
-  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${layoutSuffix}-${targetWidth}x${targetHeight}.mp4`,
-  );
-}
-
-function getSingleOutputPath(inputPath, targetWidth, targetHeight, layoutSuffix = '') {
-  const sourceName = sanitizeFileNamePart(path.basename(inputPath, path.extname(inputPath)));
-  return path.join(
-    outputVideoDirectory,
-    `${appFilePrefix}-${sourceName}-promo-english-voiceover${layoutSuffix}-${targetWidth}x${targetHeight}.mp4`,
-  );
-}
-
-async function main() {
-  const options = parseArguments();
-  await ensureAppStoreDownloadUrl();
-  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 layoutName = resolvePromoLayout(options.layout);
-  const layoutSuffix = getLayoutOutputSuffix(options, layoutName);
-  console.log(
-    `Promo layout: ${layoutName}${options.layout === 'random' ? ' (randomly selected)' : ''}.`,
-  );
-
-  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 FFMPEG_BIN.');
-  }
-  if (!fs.existsSync(iconPath)) throw new Error(`App icon was not found: ${iconPath}`);
-  await ensureEndCardBanner();
-
-  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 processingInputPath = ensureAudioStream(ffmpegCommand, inputPath, details);
-    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, layoutSuffix)
-        : getBatchOutputPath(inputPath, target.width, target.height, layoutSuffix);
-    return { crop, duration, inputPath, outputPath, processingInputPath, target };
-  });
-  const analysisSource = [...sourceVideos].sort((left, right) => (
-    (right.target.width * right.target.height) - (left.target.width * left.target.height)
-  ))[0];
-  const sourceDuration = Math.min(...sourceVideos.map((source) => source.duration));
-  const redundantStaticRanges = detectRedundantStaticRanges(
-    ffmpegCommand,
-    analysisSource.inputPath,
-    sourceDuration,
-  );
-  const visualChangeTimes = detectVisualChangeTimes(ffmpegCommand, analysisSource.inputPath);
-  configurePromoTimeline(sourceDuration, redundantStaticRanges, visualChangeTimes);
-  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, layoutName);
-  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.processingInputPath,
-      source.outputPath,
-      source.crop,
-      source.target.width,
-      source.target.height,
-      layoutName,
-    );
-    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;
-});
+      + '- Do not add watermarks, fake UI, generated symbols, or unrelated decorations.\n'
+      + '- Rounded corners and a subtle shadow may be applied around the app icon, but its internal artwork must remain unchanged.\n'
+      + '- Use image generation only for the background.\n'
+      + '- Composite the actual app icon and official store badges afterward.\n'
+      + '- Replace the specified output file if it already exists.\n'
+      + '- Verify the final PNG dimensions are exactly 1672 × 941.\n'
+      + '- Visually inspect the completed image before finishing.\n'
+      + '- Report the final saved path.\n\n'
+      + 'Then run the video-generation command again.',
+  );
+}
+
+async function ensureAppStoreDownloadUrl() {
+  if (appStoreDownloadUrl) return;
+  const readline = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const appStoreId = (await readline.question(
+      'Enter the iOS App Store ID (press Enter to skip): ',
+    )).trim();
+    if (!appStoreId) return;
+    if (!/^\d+$/.test(appStoreId)) {
+      throw new Error('iOS App Store ID must contain digits only.');
+    }
+    appStoreDownloadUrl = `https://apps.apple.com/app/id${appStoreId}`;
+    iosStoreConfig = { ...iosStoreConfig, appStoreUrl: appStoreDownloadUrl };
+    fs.mkdirSync(path.dirname(iosStoreConfigPath), { recursive: true });
+    fs.writeFileSync(iosStoreConfigPath, `${JSON.stringify(iosStoreConfig, null, 2)}\n`, 'utf8');
+    console.log(`Saved iOS App Store URL to ${iosStoreConfigPath}`);
+  } finally {
+    readline.close();
+  }
+}
+
+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 mapSourceTimeToOutput(sourceTime) {
+  let outputTime = 0;
+  for (const segment of editSegments) {
+    if (sourceTime < segment.start) return outputTime;
+    if (sourceTime <= segment.end) return outputTime + (sourceTime - segment.start);
+    outputTime += segment.end - segment.start;
+  }
+  return outputTime;
+}
+
+function normalizeSkippedRanges(skippedRanges, sourceDuration) {
+  const ranges = skippedRanges
+    .map((range) => ({
+      start: Math.max(0, Math.min(sourceDuration, range.start)),
+      end: Math.max(0, Math.min(sourceDuration, range.end)),
+    }))
+    .filter((range) => range.end > range.start)
+    .sort((left, right) => left.start - right.start);
+
+  return ranges.reduce((merged, range) => {
+    const previous = merged.at(-1);
+    if (previous && range.start <= previous.end) {
+      previous.end = Math.max(previous.end, range.end);
+    } else {
+      merged.push({ ...range });
+    }
+    return merged;
+  }, []);
+}
+
+function buildRetainedSegments(sourceDuration, skippedRanges) {
+  const normalizedRanges = normalizeSkippedRanges(skippedRanges, sourceDuration);
+  const retainedSegments = [];
+  let retainedStart = 0;
+
+  for (const range of normalizedRanges) {
+    if (range.start > retainedStart) {
+      retainedSegments.push({ start: retainedStart, end: range.start });
+    }
+    retainedStart = range.end;
+  }
+  if (retainedStart < sourceDuration) {
+    retainedSegments.push({ start: retainedStart, end: sourceDuration });
+  }
+
+  return {
+    retainedSegments: retainedSegments.map((segment) => ({
+      start: roundTimelineValue(segment.start),
+      end: roundTimelineValue(segment.end),
+    })),
+    skippedDuration: normalizedRanges.reduce(
+      (total, range) => total + (range.end - range.start),
+      0,
+    ),
+  };
+}
+
+function buildSceneWindows(retainedDuration, visualChangeTimes) {
+  const minimumWindowDuration = Math.max(2.5, Math.min(4, retainedDuration / 40));
+  const maximumWindowDuration = Math.max(6, Math.min(10, retainedDuration / 14));
+  const boundaries = [0];
+  const mappedChanges = visualChangeTimes
+    .map((sourceTime) => mapSourceTimeToOutput(sourceTime))
+    .filter((outputTime) => outputTime > 0 && outputTime < retainedDuration)
+    .sort((left, right) => left - right);
+
+  for (const changeTime of mappedChanges) {
+    if (changeTime - boundaries.at(-1) >= minimumWindowDuration) {
+      boundaries.push(changeTime);
+    }
+  }
+  if (retainedDuration - boundaries.at(-1) < minimumWindowDuration) boundaries.pop();
+  boundaries.push(retainedDuration);
+
+  const windows = [];
+  for (let index = 0; index < boundaries.length - 1; index += 1) {
+    const start = boundaries[index];
+    const end = boundaries[index + 1];
+    const splitCount = Math.max(1, Math.ceil((end - start) / maximumWindowDuration));
+    for (let splitIndex = 0; splitIndex < splitCount; splitIndex += 1) {
+      windows.push({
+        start: roundTimelineValue(start + (((end - start) * splitIndex) / splitCount)),
+        end: roundTimelineValue(start + (((end - start) * (splitIndex + 1)) / splitCount)),
+      });
+    }
+  }
+
+  if (windows.length >= minimumSceneCount) return windows;
+  return Array.from({ length: minimumSceneCount }, (_, index) => ({
+    start: roundTimelineValue((retainedDuration * index) / minimumSceneCount),
+    end: index === minimumSceneCount - 1
+      ? retainedDuration
+      : roundTimelineValue((retainedDuration * (index + 1)) / minimumSceneCount),
+  }));
+}
+
+function configurePromoTimeline(sourceDuration, skippedRanges = [], visualChangeTimes = []) {
+  if (!Number.isFinite(sourceDuration) || sourceDuration < minimumSourceDuration) {
+    throw new Error(
+      `The shortest source video must be at least ${minimumSourceDuration} seconds.`,
+    );
+  }
+
+  const { retainedSegments, skippedDuration } = buildRetainedSegments(
+    sourceDuration,
+    skippedRanges,
+  );
+  editSegments = retainedSegments.filter((segment) => segment.end > segment.start);
+  const retainedDuration = editSegments.reduce(
+    (total, segment) => total + (segment.end - segment.start),
+    0,
+  );
+  if (retainedDuration < minimumSourceDuration) {
+    throw new Error(
+      `At least ${minimumSourceDuration} seconds must remain after automatic cleanup.`,
+    );
+  }
+
+  expectedDuration = roundTimelineValue(retainedDuration);
+  sceneWindows = buildSceneWindows(expectedDuration, visualChangeTimes).map((window) => {
+    const sceneDuration = window.end - window.start;
+    return {
+      ...window,
+      sourceTime: roundTimelineValue(mapOutputTimeToSource(
+        window.start + (sceneDuration / 2),
+      )),
+      maxNarrationWords: Math.max(7, Math.floor(sceneDuration * 2.15)),
+    };
+  });
+  sceneCount = sceneWindows.length;
+  promoCopySchema.properties.scenes.minItems = sceneCount;
+  promoCopySchema.properties.scenes.maxItems = sceneCount;
+  endCardStart = expectedDuration;
+  expectedDuration = roundTimelineValue(expectedDuration + endCardDuration);
+
+  console.log(
+    `Feature-complete promo timeline: ${expectedDuration}s from ${sourceDuration.toFixed(2)}s source; `
+      + `${sceneCount} scenes and ${editSegments.length} retained segment${editSegments.length === 1 ? '' : 's'}`
+      + `${skippedDuration > 0 ? ` (${skippedDuration.toFixed(2)}s of redundant static footage removed)` : ''}.`,
+  );
+}
+
+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;
+
+  if (!ffmpegFallbackDirectory) return '';
+  const executableName = process.platform === 'win32' ? `${command}.exe` : command;
+  const fallbackPath = path.join(ffmpegFallbackDirectory, executableName);
+  return fs.existsSync(fallbackPath) ? fallbackPath : '';
+}
+
+function detectRedundantStaticRanges(ffmpegCommand, inputPath, sourceDuration) {
+  const minimumStaticDuration = Math.max(2, Math.min(4, sourceDuration / 60));
+  const result = spawnSync(ffmpegCommand, [
+    '-hide_banner',
+    '-nostats',
+    '-i', inputPath,
+    '-vf', `freezedetect=n=-50dB:d=${minimumStaticDuration}`,
+    '-an',
+    '-f', 'null',
+    process.platform === 'win32' ? 'NUL' : '/dev/null',
+  ], {
+    encoding: 'utf8',
+    windowsHide: true,
+    maxBuffer: 10 * 1024 * 1024,
+  });
+  if (result.error || result.status !== 0) {
+    console.warn('Static-screen analysis was unavailable; retaining the complete recording.');
+    return [];
+  }
+
+  const events = String(result.stderr || '').matchAll(
+    /lavfi\.freezedetect\.freeze_(start|end):\s*([\d.]+)/g,
+  );
+  const staticRanges = [];
+  let staticStart = null;
+  for (const event of events) {
+    const time = Number(event[2]);
+    if (event[1] === 'start') {
+      staticStart = time;
+    } else if (staticStart !== null && time > staticStart) {
+      staticRanges.push({ start: staticStart, end: time });
+      staticStart = null;
+    }
+  }
+  if (staticStart !== null && sourceDuration > staticStart) {
+    staticRanges.push({ start: staticStart, end: sourceDuration });
+  }
+
+  return staticRanges
+    .map((range) => ({
+      start: range.start + minimumStaticDuration,
+      end: range.end,
+    }))
+    .filter((range) => range.end - range.start >= 0.75);
+}
+
+function detectVisualChangeTimes(ffmpegCommand, inputPath) {
+  const result = spawnSync(ffmpegCommand, [
+    '-hide_banner',
+    '-nostats',
+    '-i', inputPath,
+    '-vf', "select='gt(scene,0.03)',showinfo",
+    '-an',
+    '-f', 'null',
+    process.platform === 'win32' ? 'NUL' : '/dev/null',
+  ], {
+    encoding: 'utf8',
+    windowsHide: true,
+    maxBuffer: 10 * 1024 * 1024,
+  });
+  if (result.error || result.status !== 0) {
+    console.warn('Visual-change analysis was unavailable; using duration-based scene coverage.');
+    return [];
+  }
+  return [...String(result.stderr || '').matchAll(/pts_time:([\d.]+)/g)]
+    .map((match) => Number(match[1]))
+    .filter(Number.isFinite);
+}
+
+function parseArguments() {
+  const args = process.argv.slice(2);
+  const options = {
+    aiModel: '',
+    aiProvider: 'auto',
+    copyOnly: false,
+    input: '',
+    layout: 'split',
+    layoutExplicit: false,
+    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 === '--layout') {
+      options.layout = String(args[index + 1] || '').trim().toLowerCase();
+      options.layoutExplicit = true;
+      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 --layout dynamic|split|centered|floating|cinematic|mixed|random');
+      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.`,
+      );
+      console.log('Redundant static pauses are shortened automatically; distinct screens are retained.');
+      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 (!promoLayoutNames.includes(options.layout)) {
+    throw new Error(`--layout must be one of: ${promoLayoutNames.join(', ')}.`);
+  }
+  if (options.output && !options.input) {
+    throw new Error('--output can only be used together with --input.');
+  }
+
+  return options;
+}
+
+function resolvePromoLayout(requestedLayout) {
+  if (requestedLayout !== 'random') return requestedLayout;
+  return selectablePromoLayoutNames[Math.floor(Math.random() * selectablePromoLayoutNames.length)];
+}
+
+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 escapeFilterText(value) {
+  return String(value).replace(/\\/g, '\\\\').replace(/'/g, "\\'").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 getCodexCandidates() {
+  const candidates = ['codex'];
+  const configuredCodexPath = String(process.env.CODEX_BIN || '').trim();
+  if (configuredCodexPath) candidates.unshift(configuredCodexPath);
+
+  if (process.platform === 'win32') {
+    const userProfile = process.env.USERPROFILE || process.env.HOME;
+    const extensionRoots = [
+      path.join(userProfile || '', '.vscode', 'extensions'),
+      path.join(userProfile || '', '.vscode-insiders', 'extensions'),
+      path.join(userProfile || '', '.vscode-server', 'extensions'),
+      path.join(userProfile || '', '.vscode-server-insiders', 'extensions'),
+    ];
+    const executableNames = ['codex.exe', 'codex'];
+
+    for (const extensionRoot of extensionRoots) {
+      if (!fs.existsSync(extensionRoot)) continue;
+      for (const extensionName of fs.readdirSync(extensionRoot)) {
+        if (!/^openai\.chatgpt-/i.test(extensionName)) continue;
+        const extensionPath = path.join(extensionRoot, extensionName, 'bin');
+        if (!fs.existsSync(extensionPath)) continue;
+        for (const platformDirectory of fs.readdirSync(extensionPath)) {
+          for (const executableName of executableNames) {
+            candidates.push(path.join(extensionPath, platformDirectory, executableName));
+          }
+        }
+      }
+    }
+  }
+
+  return [...new Set(candidates)];
+}
+
+function getCodexExecutable() {
+  for (const candidate of getCodexCandidates()) {
+    const versionResult = spawnSync(candidate, ['--version'], {
+      encoding: 'utf8',
+      windowsHide: true,
+    });
+    if (versionResult.error || versionResult.status !== 0) continue;
+
+    const loginResult = spawnSync(candidate, ['login', 'status'], {
+      encoding: 'utf8',
+      windowsHide: true,
+    });
+    if (!loginResult.error && loginResult.status === 0) return candidate;
+  }
+  return '';
+}
+
+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.
+- Cover every distinct demonstrated feature across the retained recording; do not omit later features.
+- Do not promote incidental navigation, loading states, advertisements, permission prompts, or repeated screens as features.
+- Keep each scene specific to what is visibly demonstrated in its supplied image whenever possible.
+- 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 iosBlock = appStoreDownloadUrl
+    ? `\n\nDownload ${appName} on the App Store:\n${appStoreDownloadUrl}`
+    : '';
+  const downloadBlock = `Download ${appName} on Google Play:\n${playStoreDownloadUrl}${iosBlock}`;
+
+  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 maximumNarrationWords = sceneWindows[sceneIndex].maxNarrationWords;
+    const narrationWords = cleanedScene.narration.split(/\s+/);
+    if (narrationWords.length > maximumNarrationWords) {
+      cleanedScene.narration = narrationWords.slice(0, maximumNarrationWords).join(' ');
+    }
+    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 <= 3; 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 === 3 || /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,
+      appStoreDownloadUrl,
+      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 getSceneComposition(layoutName, sceneIndex) {
+  const left = {
+    bodyY: 470,
+    phoneX: '90',
+    phoneY: '50',
+    styleSuffix: 'Left',
+    textX: 720,
+    titleY: 270,
+    kickerY: 225,
+  };
+  const right = {
+    ...left,
+    phoneX: 'W-w-90',
+    textX: 110,
+  };
+  const centered = {
+    bodyY: 925,
+    phoneX: '(W-w)/2',
+    phoneY: '220',
+    styleSuffix: 'Center',
+    textX: 960,
+    titleY: 102,
+    kickerY: 66,
+  };
+  const mixedCentered = {
+    ...left,
+    phoneX: '(W-w)/2',
+    phoneY: '110',
+    textX: 80,
+  };
+  const floating = {
+    ...left,
+    phoneX: '125+24*sin(t*0.8)',
+    phoneY: '110+14*cos(t*0.65)',
+    textX: 1050,
+  };
+  const cinematic = {
+    bodyY: 925,
+    phoneX: '(W-w)/2',
+    phoneY: '0',
+    styleSuffix: 'Center',
+    textX: 960,
+    titleY: 745,
+    kickerY: 705,
+  };
+
+  if (layoutName === 'dynamic') return sceneIndex % 2 === 0 ? left : right;
+  if (layoutName === 'centered') return centered;
+  if (layoutName === 'floating') return floating;
+  if (layoutName === 'cinematic') return cinematic;
+  if (layoutName === 'mixed') {
+    return [left, right, mixedCentered, floating, cinematic][sceneIndex % 5];
+  }
+  return left;
+}
+
+function getGlobalCaptionComposition(layoutName) {
+  if (layoutName === 'split') {
+    return {
+      brandStyle: 'BrandLeft', brandX: 720, brandY: 78,
+      footerStyle: 'FooterLeft', footerX: 720, footerY: 1008,
+    };
+  }
+  if (layoutName === 'floating') {
+    return {
+      brandStyle: 'BrandLeft', brandX: 1050, brandY: 78,
+      footerStyle: 'FooterLeft', footerX: 1050, footerY: 1008,
+    };
+  }
+  return {
+    brandStyle: 'BrandCenter', brandX: 960,
+    brandY: ['centered', 'mixed'].includes(layoutName) ? 18 : 78,
+    footerStyle: 'FooterCenter', footerX: 960, footerY: 1008,
+  };
+}
+
+function createCaptionFile(promoCopy, layoutName) {
+  const captionAppName = escapeAssText(appName.toUpperCase());
+  const events = sceneWindows.flatMap((window, index) => {
+    const scene = promoCopy.scenes[index];
+    const composition = getSceneComposition(layoutName, index);
+    const start = formatAssTime(window.start);
+    const end = formatAssTime(window.end);
+    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${composition.styleSuffix},,0,0,0,,{\\pos(${composition.textX},${composition.kickerY})${fade}}${escapeAssText(scene.kicker.toUpperCase())}`,
+      `Dialogue: 0,${start},${end},Title${composition.styleSuffix},,0,0,0,,{\\pos(${composition.textX},${composition.titleY})${fade}}${escapeAssText(scene.title_line_1.toUpperCase())}\\N${escapeAssText(scene.title_line_2.toUpperCase())}`,
+      `Dialogue: 0,${start},${end},Body${composition.styleSuffix},,0,0,0,,{\\pos(${composition.textX},${composition.bodyY})${fade}}${escapeAssText(scene.body)}`,
+    ];
+  });
+  const globalComposition = getGlobalCaptionComposition(layoutName);
+  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: BrandLeft,Segoe UI,30,&H00FFFFFF,&H00FFFFFF,&H50000000,&H00000000,1,0,0,0,100,100,2,0,1,1,0,7,0,0,0,1
+Style: BrandCenter,Segoe UI,30,&H00FFFFFF,&H00FFFFFF,&H50000000,&H00000000,1,0,0,0,100,100,2,0,1,1,0,8,0,0,0,1
+Style: KickerLeft,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: KickerCenter,Segoe UI Semibold,23,&H00C3D523,&H00C3D523,&H50000000,&H00000000,1,0,0,0,100,100,2,0,1,1,0,8,0,0,0,1
+Style: TitleLeft,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: TitleCenter,Segoe UI Semibold,58,&H00FFFFFF,&H00FFFFFF,&H80000000,&H00000000,1,0,0,0,100,100,0,0,1,2,0,8,0,0,0,1
+Style: BodyLeft,Segoe UI,35,&H00D8E3F0,&H00D8E3F0,&H70000000,&H00000000,0,0,0,0,100,100,0,0,1,1,0,7,0,0,0,1
+Style: BodyCenter,Segoe UI,29,&H00D8E3F0,&H00D8E3F0,&H70000000,&H00000000,0,0,0,0,100,100,0,0,1,1,0,8,0,0,0,1
+Style: FooterLeft,Segoe UI Semibold,22,&H00FFFFFF,&H00FFFFFF,&H50000000,&H00000000,1,0,0,0,100,100,2,0,1,1,0,7,0,0,0,1
+Style: FooterCenter,Segoe UI Semibold,22,&H00FFFFFF,&H00FFFFFF,&H50000000,&H00000000,1,0,0,0,100,100,2,0,1,1,0,8,0,0,0,1
+
+[Events]
+Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
+Dialogue: 0,0:00:00.00,${formatAssTime(expectedDuration)},${globalComposition.brandStyle},,0,0,0,,{\\pos(${globalComposition.brandX},${globalComposition.brandY})\\fad(350,350)}${captionAppName}
+${events.join('\n')}
+Dialogue: 0,0:00:00.00,${formatAssTime(expectedDuration)},${globalComposition.footerStyle},,0,0,0,,{\\pos(${globalComposition.footerX},${globalComposition.footerY})\\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],
+    );
+  });
+
+  const endCardPath = path.join(segmentDirectory, 'end-card.mp3');
+  synthesizeNeuralSpeech(
+    pythonCommand,
+    voiceName,
+    appStoreDownloadUrl
+      ? 'Now available on Google Play and the App Store. Download links are available in the description.'
+      : 'Now available on Google Play. The download link is available in the description.',
+    endCardPath,
+  );
+  segmentPaths.push(endCardPath);
+
+  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 endCardFilter = segmentPaths.length > sceneWindows.length
+    ? `[${sceneWindows.length}:a]aresample=48000,aformat=sample_fmts=fltp:channel_layouts=stereo,adelay=${endCardStart * 1000}|${endCardStart * 1000},apad=whole_dur=${expectedDuration}[endcard]`
+    : '';
+  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]`,
+    endCardFilter,
+    endCardFilter ? '[narration][endcard]amix=inputs=2:normalize=0:duration=longest,loudnorm=I=-16:TP=-2:LRA=7[narration-final]' : '',
+  ].filter(Boolean).join(';');
+
+  run(ffmpegCommand, [
+    '-hide_banner',
+    '-y',
+    ...inputArguments,
+    '-filter_complex', filterGraph,
+    '-map', endCardFilter ? '[narration-final]' : '[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 duration = Number(details.format?.duration || 0);
+
+  if (!videoStream) throw new Error('The source must contain a video stream.');
+  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 ensureAudioStream(ffmpegCommand, inputPath, details) {
+  const hasAudioStream = details.streams?.some((stream) => stream.codec_type === 'audio');
+  if (hasAudioStream) return inputPath;
+
+  const sourceHash = createHash('sha1').update(inputPath).digest('hex').slice(0, 12);
+  const audioFallbackPath = path.join(
+    temporaryDirectory,
+    `${sanitizeFileNamePart(path.basename(inputPath, path.extname(inputPath)))}-${sourceHash}-with-silent-audio.mp4`,
+  );
+  if (!fs.existsSync(audioFallbackPath)) {
+    const duration = Number(details.format?.duration || 0);
+    console.log(`Adding a silent audio track to video-only source: ${inputPath}`);
+    fs.mkdirSync(temporaryDirectory, { recursive: true });
+    run(ffmpegCommand, [
+      '-hide_banner',
+      '-y',
+      '-i', inputPath,
+      '-f', 'lavfi',
+      '-t', String(duration),
+      '-i', 'anullsrc=channel_layout=stereo:sample_rate=48000',
+      '-map', '0:v:0',
+      '-map', '1:a:0',
+      '-c:v', 'copy',
+      '-c:a', 'aac',
+      '-b:a', '192k',
+      '-ar', '48000',
+      '-t', String(duration),
+      '-movflags', '+faststart',
+      audioFallbackPath,
+    ]);
+  }
+  return audioFallbackPath;
+}
+
+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 getPromoLayoutSettings(layoutName) {
+  const settings = {
+    cinematic: { backgroundBrightness: '-0.28', backgroundSaturation: '1.05', phoneHeight: 1080 },
+    centered: { backgroundBrightness: '-0.42', backgroundSaturation: '1.18', phoneHeight: 650 },
+    dynamic: { backgroundBrightness: '-0.44', backgroundSaturation: '1.35', phoneHeight: 920 },
+    floating: { backgroundBrightness: '-0.38', backgroundSaturation: '1.25', phoneHeight: 860 },
+    mixed: { backgroundBrightness: '-0.42', backgroundSaturation: '1.30', phoneHeight: 860 },
+    split: { backgroundBrightness: '-0.40', backgroundSaturation: '1.30', phoneHeight: 980 },
+  };
+  return settings[layoutName] || settings.split;
+}
+
+function buildScenePositionExpression(layoutName, propertyName) {
+  const values = sceneWindows.map((_, index) => getSceneComposition(layoutName, index)[propertyName]);
+  if (values.every((value) => value === values[0])) return values[0];
+
+  let expression = values.at(-1);
+  for (let index = values.length - 2; index >= 0; index -= 1) {
+    const window = sceneWindows[index];
+    expression = `if(between(t\\,${window.start}\\,${window.end})\\,${values[index]}\\,${expression})`;
+  }
+  return expression;
+}
+
+function buildPromoStageFilter(layoutName) {
+  const accent = promoDesign.accent;
+  if (layoutName === 'dynamic') {
+    return `[background]drawbox=x=45:y=35:w=610:h=1010:color=black@0.38:t=fill,drawbox=x=1265:y=35:w=610:h=1010:color=black@0.38:t=fill,drawbox=x=52:y=42:w=596:h=996:color=${accent}@0.38:t=3,drawbox=x=1272:y=42:w=596:h=996:color=${accent}@0.38:t=3,drawbox=x=690:y=105:w=540:h=3:color=${accent}@0.72:t=fill[stage]`;
+  }
+  if (layoutName === 'centered') {
+    return `[background]drawbox=x=0:y=18:w=1920:h=170:color=black@0.62:t=fill,drawbox=x=0:y=875:w=1920:h=180:color=black@0.68:t=fill,drawbox=x=612:y=210:w=696:h=670:color=${accent}@0.46:t=4,drawbox=x=660:y=200:w=600:h=3:color=${accent}@0.78:t=fill[stage]`;
+  }
+  if (layoutName === 'floating') {
+    return `[background]drawbox=x=55:y=55:w=680:h=970:color=black@0.52:t=fill,drawbox=x=63:y=63:w=664:h=954:color=${accent}@0.52:t=4,drawbox=x=960:y=175:w=900:h=650:color=black@0.46:t=fill,drawbox=x=978:y=195:w=6:h=610:color=${accent}@0.85:t=fill[stage]`;
+  }
+  if (layoutName === 'cinematic') {
+    return '[background]null[stage]';
+  }
+  if (layoutName === 'mixed') {
+    return `[background]drawbox=x=35:y=28:w=1850:h=1024:color=black@0.32:t=fill,drawbox=x=43:y=36:w=1834:h=1008:color=${accent}@0.30:t=3,drawbox=x=640:y=80:w=3:h=920:color=white@0.10:t=fill,drawbox=x=1277:y=80:w=3:h=920:color=white@0.10:t=fill,drawbox=x=90:y=690:w=1740:h=3:color=${accent}@0.62:t=fill[stage]`;
+  }
+  return `[background]drawbox=x=45:y=30:w=570:h=1020:color=black@0.58:t=fill,drawbox=x=52:y=37:w=556:h=1006:color=${accent}@0.42:t=3,drawbox=x=680:y=176:w=1050:h=2:color=${accent}@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=${accent}@0.90:t=fill[stage]`;
+}
+
+function buildPromoForegroundFilter(layoutName) {
+  if (layoutName !== 'cinematic') return '[layout]null[layoutfinished]';
+  return `[layout]drawbox=x=0:y=0:w=1920:h=145:color=black@0.52:t=fill,drawbox=x=0:y=665:w=1920:h=415:color=black@0.72:t=fill,drawbox=x=90:y=690:w=1740:h=3:color=${promoDesign.accent}@0.80:t=fill[layoutfinished]`;
+}
+
+function getFinalSceneIconPosition(layoutName) {
+  const composition = getSceneComposition(layoutName, sceneWindows.length - 1);
+  if (composition.styleSuffix === 'Center') return { x: 80, y: 850 };
+  return { x: composition.textX, y: 650 };
+}
+
+function generatePromo(
+  ffmpegCommand,
+  inputPath,
+  outputPath,
+  crop,
+  targetWidth,
+  targetHeight,
+  layoutName,
+) {
+  const subtitleFilterPath = escapeFilterPath(captionPath);
+  const layoutSettings = getPromoLayoutSettings(layoutName);
+  const phoneX = buildScenePositionExpression(layoutName, 'phoneX');
+  const phoneY = buildScenePositionExpression(layoutName, 'phoneY');
+  const iconPosition = getFinalSceneIconPosition(layoutName);
+  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,tpad=stop_mode=clone:stop_duration=${endCardDuration},split=2[bgsrc][phonesrc]`
+    : `${editSegments.map((_, index) => `[v${index}]`).join('')}concat=n=${segmentCount}:v=1:a=0,fps=30,setpts=PTS-STARTPTS,tpad=stop_mode=clone:stop_duration=${endCardDuration},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=${layoutSettings.backgroundBrightness}:saturation=${layoutSettings.backgroundSaturation},drawbox=x=0:y=0:w=iw:h=ih:color=${promoDesign.background}@0.72:t=fill[background]`,
+    buildPromoStageFilter(layoutName),
+    `[phonesrc]scale=-2:${layoutSettings.phoneHeight},setsar=1[phone]`,
+    `[stage][phone]overlay=x='${phoneX}':y='${phoneY}':eval=frame:shortest=1[layout]`,
+    buildPromoForegroundFilter(layoutName),
+    '[1:v]scale=145:145,format=rgba,colorchannelmixer=aa=0.96[icon]',
+    `[layoutfinished][icon]overlay=x=${iconPosition.x}:y=${iconPosition.y}: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[captioned]`,
+    `[3:v]scale=1920:1080,format=yuv420p[cardbanner]`,
+    `[captioned][cardbanner]overlay=eof_action=repeat:enable=between(t\\,${endCardStart}\\,${expectedDuration})[cardonly]`,
+    `[cardonly]scale=${targetWidth}:${targetHeight}:flags=lanczos,setsar=1,format=yuv420p[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,
+    '-loop', '1',
+    '-i', endCardBannerPath,
+    '-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 getLayoutOutputSuffix(options, layoutName) {
+  if (!options.layoutExplicit) return '';
+  return options.layout === 'random'
+    ? `-layout-random-${layoutName}`
+    : `-layout-${layoutName}`;
+}
+
+function getBatchOutputPath(inputPath, targetWidth, targetHeight, layoutSuffix = '') {
+  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${layoutSuffix}-${targetWidth}x${targetHeight}.mp4`,
+  );
+}
+
+function getSingleOutputPath(inputPath, targetWidth, targetHeight, layoutSuffix = '') {
+  const sourceName = sanitizeFileNamePart(path.basename(inputPath, path.extname(inputPath)));
+  return path.join(
+    outputVideoDirectory,
+    `${appFilePrefix}-${sourceName}-promo-english-voiceover${layoutSuffix}-${targetWidth}x${targetHeight}.mp4`,
+  );
+}
+
+async function main() {
+  const options = parseArguments();
+  await ensureAppStoreDownloadUrl();
+  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 layoutName = resolvePromoLayout(options.layout);
+  const layoutSuffix = getLayoutOutputSuffix(options, layoutName);
+  console.log(
+    `Promo layout: ${layoutName}${options.layout === 'random' ? ' (randomly selected)' : ''}.`,
+  );
+
+  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 FFMPEG_BIN.');
+  }
+  if (!fs.existsSync(iconPath)) throw new Error(`App icon was not found: ${iconPath}`);
+  await ensureEndCardBanner();
+
+  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 processingInputPath = ensureAudioStream(ffmpegCommand, inputPath, details);
+    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, layoutSuffix)
+        : getBatchOutputPath(inputPath, target.width, target.height, layoutSuffix);
+    return { crop, duration, inputPath, outputPath, processingInputPath, target };
+  });
+  const analysisSource = [...sourceVideos].sort((left, right) => (
+    (right.target.width * right.target.height) - (left.target.width * left.target.height)
+  ))[0];
+  const sourceDuration = Math.min(...sourceVideos.map((source) => source.duration));
+  const redundantStaticRanges = detectRedundantStaticRanges(
+    ffmpegCommand,
+    analysisSource.inputPath,
+    sourceDuration,
+  );
+  const visualChangeTimes = detectVisualChangeTimes(ffmpegCommand, analysisSource.inputPath);
+  configurePromoTimeline(sourceDuration, redundantStaticRanges, visualChangeTimes);
+  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, layoutName);
+  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.processingInputPath,
+      source.outputPath,
+      source.crop,
+      source.target.width,
+      source.target.height,
+      layoutName,
+    );
+    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;
+});