codeplay-common 4.5.0 → 4.5.2

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

@@ -1,11 +1,22 @@
 // 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');
@@ -31,7 +42,7 @@ 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] || '';
-const appStoreDownloadUrl = /^https:\/\/apps\.apple\.com\/app\/id\d+$/.test(configuredAppStoreUrl)
+let appStoreDownloadUrl = /^https:\/\/apps\.apple\.com\/app\/id\d+$/.test(configuredAppStoreUrl)
   ? configuredAppStoreUrl
   : '';
 const promoDesignIndex = createHash('sha1').update(`${appUniqueId}:${appName}`).digest()[0] % 4;
@@ -42,6 +53,16 @@ const promoDesigns = [
   { 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');
@@ -51,7 +72,7 @@ const spatialXrVideoPath = path.join(
   spatialXrDirectory,
   `${appFilePrefix}-spatial-xr-3d-sbs-lr-3840x1080.mp4`,
 );
-const iconPath = path.join(projectDirectory, 'resources', 'icon-only.png');
+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`);
@@ -65,13 +86,13 @@ 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 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;
@@ -80,7 +101,7 @@ const spatialEyeWidth = 1920;
 const spatialEyeHeight = 1080;
 const spatialOutputWidth = spatialEyeWidth * 2;
 const spatialOutputHeight = spatialEyeHeight;
-const promoCopySchemaVersion = 5;
+const promoCopySchemaVersion = 5;
 const promoCopySchema = {
   type: 'object',
   additionalProperties: false,
@@ -169,41 +190,62 @@ function sanitizeFileNamePart(value) {
     .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 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'
-      + '- Do not add extra marketing text unless it is specifically requested.\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 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 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'
+      + '- Do not add extra marketing text unless it is specifically requested.\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 [];
@@ -226,7 +268,7 @@ function roundTimelineValue(value) {
   return Math.round(value * 100) / 100;
 }
 
-function mapOutputTimeToSource(outputTime) {
+function mapOutputTimeToSource(outputTime) {
   let remainingTime = outputTime;
   for (const segment of editSegments) {
     const segmentDuration = segment.end - segment.start;
@@ -235,150 +277,150 @@ function mapOutputTimeToSource(outputTime) {
     }
     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) {
+  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;
+  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)` : ''}.`,
-  );
-}
+    `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)
@@ -421,91 +463,93 @@ function commandExists(command) {
   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() {
+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,
@@ -526,6 +570,10 @@ function parseArguments() {
     } 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;
@@ -550,6 +598,7 @@ function parseArguments() {
       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');
@@ -560,10 +609,10 @@ function parseArguments() {
       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.');
+      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}`);
@@ -573,6 +622,9 @@ function parseArguments() {
   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.');
   }
@@ -580,6 +632,11 @@ function parseArguments() {
   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'], {
@@ -723,12 +780,54 @@ function createCopyFingerprint(appContext, inputPaths) {
   })).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() {
-  const result = spawnSync('codex', ['--version'], {
-    encoding: 'utf8',
-    windowsHide: true,
-  });
-  return !result.error && result.status === 0 ? 'codex' : '';
+  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) {
@@ -800,12 +899,12 @@ function buildPromoCopyPrompt(appContext, previousError = '') {
 
 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.
+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.
@@ -912,11 +1011,10 @@ function validatePromoCopy(value) {
       }
       cleanedScene[field] = cleaned;
     }
-    const narrationWords = cleanedScene.narration.split(/\s+/).length;
-    if (narrationWords > sceneWindows[sceneIndex].maxNarrationWords) {
-      throw new Error(
-        `Scene ${sceneIndex + 1} narration has ${narrationWords} words; maximum is ${sceneWindows[sceneIndex].maxNarrationWords}.`,
-      );
+    const maximumNarrationWords = sceneWindows[sceneIndex].maxNarrationWords;
+    const narrationWords = cleanedScene.narration.split(/\s+/);
+    if (narrationWords.length > maximumNarrationWords) {
+      cleanedScene.narration = narrationWords.slice(0, maximumNarrationWords).join(' ');
     }
     return cleanedScene;
   });
@@ -1072,7 +1170,7 @@ async function generateOrLoadPromoCopy(
   const framePaths = extractAnalysisFrames(ffmpegCommand, analysisInputPath, analysisCrop);
   let previousError = '';
   let generated;
-  for (let attempt = 1; attempt <= 2; attempt += 1) {
+  for (let attempt = 1; attempt <= 3; attempt += 1) {
     const prompt = buildPromoCopyPrompt(appContext, previousError);
     try {
       generated = provider === 'openai'
@@ -1082,7 +1180,7 @@ async function generateOrLoadPromoCopy(
       break;
     } catch (error) {
       previousError = error.message;
-      if (attempt === 2 || /unavailable|not configured|not signed in/i.test(previousError)) throw error;
+      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.`);
     }
   }
@@ -1220,22 +1318,99 @@ function formatAssTime(seconds) {
   return `${hours}:${String(minutes).padStart(2, '0')}:${String(wholeSeconds).padStart(2, '0')}.${String(remainder).padStart(2, '0')}`;
 }
 
-function createCaptionFile(promoCopy) {
+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 x = index === sceneWindows.length - 1 ? 895 : 720;
     const fadeIn = window.end - window.start <= 3 ? 180 : 220;
     const fadeOut = index === sceneWindows.length - 1 ? 350 : fadeIn;
     const fade = `\\fad(${fadeIn},${fadeOut})`;
     return [
-      `Dialogue: 0,${start},${end},Kicker,,0,0,0,,{\\pos(${x},225)${fade}}${escapeAssText(scene.kicker.toUpperCase())}`,
-      `Dialogue: 0,${start},${end},Title,,0,0,0,,{\\pos(${x},270)${fade}}${escapeAssText(scene.title_line_1.toUpperCase())}\\N${escapeAssText(scene.title_line_2.toUpperCase())}`,
-      `Dialogue: 0,${start},${end},Body,,0,0,0,,{\\pos(${x},470)${fade}}${escapeAssText(scene.body)}`,
+      `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('  /  ');
@@ -1248,17 +1423,22 @@ WrapStyle: 2
 
 [V4+ Styles]
 Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding
-Style: Brand,Segoe UI,30,&H00FFFFFF,&H00FFFFFF,&H50000000,&H00000000,1,0,0,0,100,100,2,0,1,1,0,7,0,0,0,1
-Style: Kicker,Segoe UI Semibold,25,&H00C3D523,&H00C3D523,&H50000000,&H00000000,1,0,0,0,100,100,2,0,1,1,0,7,0,0,0,1
-Style: Title,Segoe UI Semibold,76,&H00FFFFFF,&H00FFFFFF,&H80000000,&H00000000,1,0,0,0,100,100,0,0,1,2,0,7,0,0,0,1
-Style: Body,Segoe UI,35,&H00D8E3F0,&H00D8E3F0,&H70000000,&H00000000,0,0,0,0,100,100,0,0,1,1,0,7,0,0,0,1
-Style: Footer,Segoe UI Semibold,22,&H00FFFFFF,&H00FFFFFF,&H50000000,&H00000000,1,0,0,0,100,100,2,0,1,1,0,7,0,0,0,1
+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)},Brand,,0,0,0,,{\\pos(720,78)\\fad(350,350)}${captionAppName}
+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)},Footer,,0,0,0,,{\\pos(720,1008)\\fad(350,350)}${footer}
+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 });
@@ -1442,8 +1622,75 @@ function validateOutput(ffprobeCommand, outputPath, targetWidth, targetHeight) {
   );
 }
 
-function generatePromo(ffmpegCommand, inputPath, outputPath, crop, targetWidth, targetHeight) {
+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';
@@ -1476,12 +1723,13 @@ function generatePromo(ffmpegCommand, inputPath, outputPath, crop, targetWidth,
     videoSourceFilter,
     ...videoTrimFilters,
     videoSequenceFilter,
-    `[bgsrc]scale=1920:1080:force_original_aspect_ratio=increase,crop=1920:1080,gblur=sigma=34,eq=brightness=-0.40:saturation=1.30,drawbox=x=0:y=0:w=iw:h=ih:color=${promoDesign.background}@0.72:t=fill[background]`,
-    `[background]drawbox=x=${promoDesign.panelX}:y=30:w=${promoDesign.panelWidth}:h=1020:color=black@0.58:t=fill,drawbox=x=${promoDesign.panelX + 7}:y=37:w=${promoDesign.panelWidth - 14}:h=1006:color=${promoDesign.accent}@0.24:t=3,drawbox=x=680:y=176:w=1050:h=2:color=${promoDesign.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=0xffb020@0.90:t=fill[stage]`,
-    '[phonesrc]scale=-2:980,setsar=1[phone]',
-    `[stage][phone]overlay=x=${promoDesign.phoneX}:y=50:shortest=1[layout]`,
+    `[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]',
-    `[layout][icon]overlay=x=720:y=650:enable=between(t\\,${finalSceneStart}\\,${expectedDuration}):shortest=1[branded]`,
+    `[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]`,
@@ -1621,26 +1869,34 @@ function getTargetDimensions(videoDetails) {
     : { width: 1920, height: 1080 };
 }
 
-function getBatchOutputPath(inputPath, targetWidth, targetHeight) {
+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-${targetWidth}x${targetHeight}.mp4`,
+    `${appFilePrefix}-${sourceName}-promo-english-voiceover${layoutSuffix}-${targetWidth}x${targetHeight}.mp4`,
   );
 }
 
-function getSingleOutputPath(inputPath, targetWidth, targetHeight) {
+function getSingleOutputPath(inputPath, targetWidth, targetHeight, layoutSuffix = '') {
   const sourceName = sanitizeFileNamePart(path.basename(inputPath, path.extname(inputPath)));
   return path.join(
     outputVideoDirectory,
-    `${appFilePrefix}-${sourceName}-promo-english-voiceover-${targetWidth}x${targetHeight}.mp4`,
+    `${appFilePrefix}-${sourceName}-promo-english-voiceover${layoutSuffix}-${targetWidth}x${targetHeight}.mp4`,
   );
 }
 
 async function main() {
   const options = parseArguments();
+  await ensureAppStoreDownloadUrl();
   if (options.listVoices) {
     printVoiceCatalog();
     return;
@@ -1657,15 +1913,21 @@ async function main() {
     return;
   }
 
-  const ffmpegCommand = getExecutable('ffmpeg');
+  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();
+  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)]
@@ -1687,21 +1949,21 @@ async function main() {
     const outputPath = options.output
       ? path.resolve(options.output)
       : options.input
-        ? getSingleOutputPath(inputPath, target.width, target.height)
-        : getBatchOutputPath(inputPath, target.width, target.height);
+        ? 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 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,
@@ -1771,7 +2033,7 @@ async function main() {
       'edge-tts is required for natural neural voices. Install it with: py -m pip install edge-tts',
     );
   }
-  createCaptionFile(promoCopyResult.copy);
+  createCaptionFile(promoCopyResult.copy, layoutName);
   console.log(`Creating natural neural narration with: ${voice.label}`);
   const narrationSegmentPaths = createNarrationSegments(
     pythonCommand,
@@ -1791,6 +2053,7 @@ async function main() {
       source.crop,
       source.target.width,
       source.target.height,
+      layoutName,
     );
     validateOutput(
       ffprobeCommand,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeplay-common",
-  "version": "4.5.0",
+  "version": "4.5.2",
   "description": "Common build scripts and files",
   "scripts": {
 	"postinstall": "node scripts/sync-files.js",