@x12i/youtube-video-uploader-cli 1.2.0 → 1.4.0

package/src/actions/journey-overlay.js

@@ -0,0 +1,623 @@
+import ffmpeg from 'fluent-ffmpeg';
+import ffmpegStatic from 'ffmpeg-static';
+import ffprobeStatic from 'ffprobe-static';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { Resvg } from '@resvg/resvg-js';
+import { getVideoMetadata } from './shorten.js';
+
+if (ffmpegStatic && fs.existsSync(ffmpegStatic)) {
+  ffmpeg.setFfmpegPath(ffmpegStatic);
+}
+if (ffprobeStatic?.path && fs.existsSync(ffprobeStatic.path)) {
+  ffmpeg.setFfprobePath(ffprobeStatic.path);
+}
+
+/**
+ * Escape XML special characters for safe SVG embedding.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function escapeXml(text) {
+  if (!text) return '';
+  return String(text)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+/**
+ * Truncate a string and add an ellipsis if it exceeds maxLength.
+ *
+ * @param {string} str
+ * @param {number} maxLength
+ * @returns {string}
+ */
+export function truncate(str, maxLength) {
+  if (!str || str.length <= maxLength) return str;
+  return str.slice(0, Math.max(0, maxLength - 1)) + '…';
+}
+
+/**
+ * Build tracks list for the sidebar from raw metadata / songs.
+ *
+ * @param {object} params
+ * @param {string} params.currentSongKey
+ * @param {object} [params.rawMetadata]
+ * @param {string} [params.mode='before-current']
+ * @param {number} [params.maxVisibleRows=8]
+ * @param {'title' | 'stage' | 'both'} [params.sidebarLabel='title']
+ * @returns {Array<{ index: number, title: string, isCurrent: boolean, isUpcoming: boolean }>}
+ */
+export function resolveJourneyTracks({ currentSongKey, rawMetadata, mode = 'before-current', maxVisibleRows = 8, sidebarLabel = 'title' }) {
+  let allTracks = [];
+
+  const formatTrackLabel = (rawTitle, stage) => {
+    if (sidebarLabel === 'stage') {
+      return stage || rawTitle;
+    }
+    if (sidebarLabel === 'both') {
+      return stage ? `${stage}: ${rawTitle}` : rawTitle;
+    }
+    return rawTitle;
+  };
+
+  if (rawMetadata?.songs && typeof rawMetadata.songs === 'object' && !Array.isArray(rawMetadata.songs)) {
+    const orderedKeys = Array.isArray(rawMetadata.playlist?.orderedSongKeys)
+      ? rawMetadata.playlist.orderedSongKeys
+      : Object.keys(rawMetadata.songs);
+
+    allTracks = orderedKeys.map((key, idx) => {
+      const songData = rawMetadata.songs[key] || {};
+      const rawTitle = songData.youtube?.snippet?.title || path.basename(key, path.extname(key));
+      const stage = songData.journeyStage || songData.albumRole;
+      return {
+        key,
+        title: formatTrackLabel(rawTitle, stage),
+        rawTitle,
+        stage: stage || '',
+        journeyStage: stage || '',
+        trackNumber: songData.trackNumber ?? idx + 1,
+        totalTracks: orderedKeys.length,
+      };
+    });
+  } else if (Array.isArray(rawMetadata?.videos)) {
+    allTracks = rawMetadata.videos.map((v, idx) => {
+      const rawTitle = v.title || path.basename(v.filename, path.extname(v.filename));
+      const stage = v.journeyStage || v.albumRole;
+      return {
+        key: v.filename,
+        title: formatTrackLabel(rawTitle, stage),
+        rawTitle,
+        stage: stage || '',
+        journeyStage: stage || '',
+        trackNumber: v.trackNumber ?? idx + 1,
+        totalTracks: rawMetadata.videos.length,
+      };
+    });
+  }
+
+  const currentIndex = allTracks.findIndex(t => t.key === currentSongKey || path.basename(t.key) === path.basename(currentSongKey));
+
+  if (currentIndex === -1) {
+    // Fallback: show only the current track
+    const songData = rawMetadata?.songs?.[currentSongKey] || {};
+    const singleRawTitle = songData.youtube?.snippet?.title || (currentSongKey ? path.basename(currentSongKey, path.extname(currentSongKey)) : 'Current Track');
+    const stage = songData.journeyStage || songData.albumRole;
+    return [{
+      index: 1,
+      totalTracks: allTracks.length || 1,
+      title: formatTrackLabel(singleRawTitle, stage),
+      rawTitle: singleRawTitle,
+      stage: stage || '',
+      journeyStage: stage || '',
+      isCurrent: true,
+      isUpcoming: false,
+    }];
+  }
+
+  let visibleList = [];
+  if (mode === 'all') {
+    visibleList = allTracks.map((t, i) => ({
+      index: i + 1,
+      totalTracks: allTracks.length,
+      title: t.title,
+      rawTitle: t.rawTitle,
+      stage: t.stage,
+      journeyStage: t.journeyStage,
+      isCurrent: i === currentIndex,
+      isUpcoming: i > currentIndex,
+    }));
+  } else {
+    // 'before-current'
+    visibleList = allTracks.slice(0, currentIndex + 1).map((t, i) => ({
+      index: i + 1,
+      totalTracks: allTracks.length,
+      title: t.title,
+      rawTitle: t.rawTitle,
+      stage: t.stage,
+      journeyStage: t.journeyStage,
+      isCurrent: i === currentIndex,
+      isUpcoming: false,
+    }));
+  }
+
+  if (maxVisibleRows && visibleList.length > maxVisibleRows) {
+    // Cap visible rows and add +N more
+    const overflowCount = visibleList.length - maxVisibleRows + 1;
+    const capped = visibleList.slice(0, maxVisibleRows - 1);
+    capped.push({
+      index: maxVisibleRows,
+      totalTracks: allTracks.length,
+      title: `+${overflowCount} more`,
+      stage: '',
+      isCurrent: false,
+      isUpcoming: false,
+      isOverflow: true,
+    });
+    return capped;
+  }
+
+  return visibleList;
+}
+
+/**
+ * Generate SVG string for the journey overlay.
+ *
+ * @param {object} params
+ * @param {number} [params.width=1920]
+ * @param {number} [params.height=1080]
+ * @param {Array<object>} [params.tracks=[]]
+ * @param {string} [params.centerText]
+ * @param {boolean} [params.showSidebar=true]
+ * @param {'dark' | 'light'} [params.theme='dark']
+ * @param {'left' | 'right'} [params.position='right']
+ * @param {'badge' | 'panel'} [params.style='badge']
+ * @param {string} [params.stage]
+ * @param {number} [params.step]
+ * @param {number} [params.totalSteps]
+ * @param {string} [params.badgeText='Beyond Art']
+ * @returns {string} SVG xml content
+ */
+export function generateJourneySvg(params) {
+  const {
+    width = 1920,
+    height = 1080,
+    tracks = [],
+    centerText = '',
+    showSidebar = true,
+    theme = 'dark',
+    position = 'right',
+    style = 'badge',
+    stage = '',
+    step = null,
+    totalSteps = null,
+    badgeText = 'Beyond Art',
+  } = params;
+
+  const isDark = theme === 'dark';
+  const sidebarBg = isDark ? 'rgba(15, 23, 42, 0.85)' : 'rgba(255, 255, 255, 0.90)';
+  const sidebarBorder = isDark ? 'rgba(255, 255, 255, 0.12)' : 'rgba(0, 0, 0, 0.10)';
+  const textPrimary = isDark ? '#f8fafc' : '#0f172a';
+  const textSecondary = isDark ? '#94a3b8' : '#64748b';
+  const textHighlight = isDark ? '#38bdf8' : '#0284c7';
+  const highlightBadgeBg = isDark ? 'rgba(56, 189, 248, 0.18)' : 'rgba(2, 132, 199, 0.12)';
+  const highlightBadgeBorder = isDark ? 'rgba(56, 189, 248, 0.40)' : 'rgba(2, 132, 199, 0.30)';
+
+  let sidebarSvg = '';
+  if (showSidebar && (tracks.length > 0 || stage)) {
+    if (style === 'panel') {
+      const panelWidth = 440;
+      const rowHeight = 44;
+      const panelPadding = 24;
+      const panelHeight = panelPadding * 2 + tracks.length * rowHeight;
+      const panelX = position === 'left' ? 60 : width - panelWidth - 60;
+      const panelY = 60;
+
+      let rowsSvg = '';
+      tracks.forEach((track, idx) => {
+        const rowY = panelY + panelPadding + idx * rowHeight;
+        const truncatedTitle = truncate(track.title, 34);
+
+        if (track.isCurrent) {
+          rowsSvg += `
+            <rect x="${panelX + 12}" y="${rowY}" width="${panelWidth - 24}" height="${rowHeight - 6}" rx="8" fill="${highlightBadgeBg}" stroke="${highlightBadgeBorder}" stroke-width="1.5" />
+            <circle cx="${panelX + 32}" cy="${rowY + (rowHeight - 6) / 2}" r="5" fill="${textHighlight}" />
+            <text x="${panelX + 48}" y="${rowY + (rowHeight - 6) / 2 + 5}" font-family="system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif" font-size="16" font-weight="700" fill="${textHighlight}">${escapeXml(truncatedTitle)}</text>
+          `;
+        } else if (track.isUpcoming) {
+          rowsSvg += `
+            <circle cx="${panelX + 32}" cy="${rowY + (rowHeight - 6) / 2}" r="3" fill="${textSecondary}" opacity="0.5" />
+            <text x="${panelX + 48}" y="${rowY + (rowHeight - 6) / 2 + 5}" font-family="system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif" font-size="15" font-weight="400" fill="${textSecondary}" opacity="0.6">${escapeXml(truncatedTitle)}</text>
+          `;
+        } else if (track.isOverflow) {
+          rowsSvg += `
+            <text x="${panelX + 48}" y="${rowY + (rowHeight - 6) / 2 + 5}" font-family="system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif" font-size="14" font-weight="500" fill="${textSecondary}" font-style="italic">${escapeXml(truncatedTitle)}</text>
+          `;
+        } else {
+          rowsSvg += `
+            <circle cx="${panelX + 32}" cy="${rowY + (rowHeight - 6) / 2}" r="3.5" fill="${textSecondary}" />
+            <text x="${panelX + 48}" y="${rowY + (rowHeight - 6) / 2 + 5}" font-family="system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif" font-size="15" font-weight="500" fill="${textPrimary}">${escapeXml(truncatedTitle)}</text>
+          `;
+        }
+      });
+
+      sidebarSvg = `
+        <g id="sidebar">
+          <rect x="${panelX}" y="${panelY}" width="${panelWidth}" height="${panelHeight}" rx="16" fill="${sidebarBg}" stroke="${sidebarBorder}" stroke-width="1.5" />
+          ${rowsSvg}
+        </g>
+      `;
+    } else {
+      // Modern sleek corner badge (default)
+      const currentTrack = tracks.find(t => t.isCurrent && !t.isOverflow) || tracks.find(t => !t.isOverflow) || {};
+      const stageName = stage || currentTrack.stage || currentTrack.journeyStage || (currentTrack.isOverflow ? '' : currentTrack.title) || 'Decision';
+      const stepNum = step !== null && step !== undefined ? step : (currentTrack.index || 1);
+      const totalCount = totalSteps !== null && totalSteps !== undefined ? totalSteps : (currentTrack.totalTracks || 11);
+      const badgeLabel = badgeText || 'Beyond Art';
+
+      const panelWidth = Math.max(300, Math.min(420, stageName.length * 16 + 120));
+      const panelHeight = 84;
+      const panelX = position === 'left' ? 60 : width - panelWidth - 60;
+      const panelY = 60;
+
+      sidebarSvg = `
+        <g id="journey-badge">
+          <rect x="${panelX}" y="${panelY}" width="${panelWidth}" height="${panelHeight}" rx="16" fill="rgba(15, 23, 42, 0.65)" stroke="rgba(255, 255, 255, 0.14)" stroke-width="1.2" />
+          <text x="${panelX + 22}" y="${panelY + 31}" font-family="system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="13" font-weight="700" letter-spacing="1.5" fill="${textHighlight}">STEP ${String(stepNum).padStart(2, '0')} / ${String(totalCount).padStart(2, '0')}</text>
+          <text x="${panelX + panelWidth - 22}" y="${panelY + 31}" font-family="system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="12" font-weight="500" letter-spacing="1" fill="${textSecondary}" text-anchor="end">${escapeXml(badgeLabel)}</text>
+          <text x="${panelX + 22}" y="${panelY + 63}" font-family="system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="24" font-weight="700" letter-spacing="0.5" fill="${textPrimary}">${escapeXml(stageName)}</text>
+        </g>
+      `;
+    }
+  }
+
+  let centerTextSvg = '';
+  if (centerText && centerText.trim()) {
+    const textStr = escapeXml(centerText.trim());
+    const approxCharWidth = 24;
+    const boxWidth = Math.min(width - 240, Math.max(500, textStr.length * approxCharWidth + 80));
+    const boxHeight = 84;
+    const boxX = (width - boxWidth) / 2;
+    const boxY = (height - boxHeight) / 2;
+
+    centerTextSvg = `
+      <g id="center-text">
+        <rect x="${boxX}" y="${boxY}" width="${boxWidth}" height="${boxHeight}" rx="42" fill="rgba(15, 23, 42, 0.45)" stroke="rgba(255, 255, 255, 0.12)" stroke-width="1" />
+        <text x="${width / 2}" y="${height / 2 + 11}" font-family="system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif" font-size="34" font-weight="500" letter-spacing="1.2" fill="rgba(248, 250, 252, 0.78)" text-anchor="middle">${textStr}</text>
+      </g>
+    `;
+  }
+
+  return `
+    <svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">
+      ${sidebarSvg}
+      ${centerTextSvg}
+    </svg>
+  `.trim();
+}
+
+/**
+ * Render SVG string to a PNG buffer using @resvg/resvg-js.
+ *
+ * @param {string} svgContent
+ * @param {number} [width=1920]
+ * @param {number} [height=1080]
+ * @returns {Buffer}
+ */
+export function renderSvgToPng(svgContent, width = 1920, height = 1080) {
+  const resvg = new Resvg(svgContent, {
+    fitTo: {
+      mode: 'width',
+      value: width,
+    },
+  });
+  const pngData = resvg.render();
+  return pngData.asPng();
+}
+
+/**
+ * Apply journey overlay to video.
+ *
+ * @param {object} params
+ * @param {string} params.inputPath
+ * @param {string} params.outputPath
+ * @param {object} params.action
+ * @param {object} [params.entry]
+ * @param {object} [params.rawMetadata]
+ * @param {object} [params.journeyConfig]
+ * @param {boolean} [params.dryRun=false]
+ * @param {(msg: string) => void} [params.onWarn]
+ * @returns {Promise<{ outputPath: string, duration?: number, dryRun?: boolean, command?: string }>}
+ */
+export async function applyJourneyOverlay(params) {
+  const {
+    inputPath,
+    outputPath,
+    action = {},
+    entry = {},
+    rawMetadata = {},
+    journeyConfig = {},
+    context = {},
+    dryRun = false,
+    onWarn,
+  } = params;
+
+  const currentSongKey = entry.filename || entry.songKey || path.basename(inputPath);
+  const maxCenterChars = journeyConfig.maxCenterChars || 60;
+
+  // Extract center concepts or legacy center text
+  let rawConcepts = [];
+  if (Array.isArray(action.centerConcepts) && action.centerConcepts.length > 0) {
+    rawConcepts = action.centerConcepts;
+  } else if (action.centerText !== undefined && String(action.centerText).trim()) {
+    rawConcepts = [String(action.centerText).trim()];
+  }
+
+  const concepts = rawConcepts.map((text, idx) => {
+    const str = String(text).trim();
+    if (str.length > maxCenterChars) {
+      if (onWarn) {
+        onWarn(`Center concept [${idx}] for "${currentSongKey}" exceeds maxCenterChars (${maxCenterChars}); truncating.`);
+      }
+      return truncate(str, maxCenterChars);
+    }
+    return str;
+  }).filter(Boolean);
+
+  const conceptsDisplayMode = action.conceptsDisplayMode || (action.centerConcepts ? 'full' : 'intro');
+  const conceptDisplaySeconds = typeof action.conceptDisplaySeconds === 'number' && action.conceptDisplaySeconds > 0
+    ? action.conceptDisplaySeconds
+    : 7;
+  const conceptFadeSeconds = typeof action.conceptFadeSeconds === 'number' && action.conceptFadeSeconds >= 0
+    ? action.conceptFadeSeconds
+    : 1;
+
+  const isJourneyEnabled = journeyConfig.enabled !== false;
+  const showSidebar = isJourneyEnabled && action.showSidebar !== false;
+  const sidebarLabel = journeyConfig.sidebarLabel || 'title';
+  const sidebarDisplayDuration = journeyConfig.sidebarDisplayDuration !== undefined
+    ? journeyConfig.sidebarDisplayDuration
+    : (journeyConfig.displayDuration ?? 5);
+
+  const tracks = showSidebar
+    ? resolveJourneyTracks({
+        currentSongKey,
+        rawMetadata,
+        mode: journeyConfig.mode || 'before-current',
+        maxVisibleRows: journeyConfig.style === 'panel' ? (journeyConfig.maxVisibleRows || 8) : null,
+        sidebarLabel,
+      })
+    : [];
+
+  let videoMeta = { duration: 0, width: 1920, height: 1080, fps: 30 };
+  if (fs.existsSync(inputPath)) {
+    try {
+      videoMeta = await getVideoMetadata(inputPath);
+    } catch (err) {
+      if (!dryRun) throw err;
+    }
+  }
+
+  const width = videoMeta.width || 1920;
+  const height = videoMeta.height || 1080;
+  const videoDuration = videoMeta.duration || 0;
+
+  const sidebarDurationSec = sidebarDisplayDuration === 'full'
+    ? (videoDuration > 0 ? videoDuration : 300)
+    : (typeof sidebarDisplayDuration === 'number' ? sidebarDisplayDuration : 5);
+
+  const conceptsTotalDuration = conceptsDisplayMode === 'intro'
+    ? sidebarDurationSec
+    : (videoDuration > 0 ? videoDuration : 300);
+
+  if (dryRun) {
+    const conceptsSummary = concepts.length > 0
+      ? `concepts=${concepts.length} [mode=${conceptsDisplayMode}, ${conceptDisplaySeconds}s cycle, ${conceptFadeSeconds}s fade]`
+      : `concepts=none`;
+    const plan = `Journey overlay: sidebar=${showSidebar} (${tracks.length} tracks, label=${sidebarLabel}, duration=${sidebarDisplayDuration}s), ${conceptsSummary} -> ${outputPath}`;
+    return {
+      outputPath,
+      duration: videoMeta.duration,
+      dryRun: true,
+      command: plan,
+    };
+  }
+
+  const tempFilesToClean = [];
+
+  try {
+    const tempDir = path.join(os.tmpdir(), `journey_overlay_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`);
+    fs.mkdirSync(tempDir, { recursive: true });
+    tempFilesToClean.push(tempDir);
+
+    let tempSidebarPath = null;
+    if (showSidebar && (tracks.length > 0 || entry.journeyStage || entry.albumRole)) {
+      const sidebarSvg = generateJourneySvg({
+        width,
+        height,
+        tracks,
+        centerText: '',
+        showSidebar: true,
+        theme: journeyConfig.theme || 'dark',
+        position: journeyConfig.position || 'right',
+        style: journeyConfig.style || 'badge',
+        stage: entry.journeyStage || entry.albumRole || (tracks.find(t => t.isCurrent)?.stage),
+        step: typeof entry.trackNumber === 'number' ? entry.trackNumber : (entry.playlistPosition !== undefined ? entry.playlistPosition + 1 : (tracks.find(t => t.isCurrent)?.index)),
+        totalSteps: rawMetadata.album?.trackCount || rawMetadata.album?.arc?.length || tracks[0]?.totalTracks || 11,
+        badgeText: journeyConfig.badgeText || 'Beyond Art',
+      });
+      const sidebarPngBuffer = renderSvgToPng(sidebarSvg, width, height);
+      tempSidebarPath = path.join(
+        tempDir,
+        `journey_sidebar_${Date.now()}_${Math.random().toString(36).slice(2, 6)}.png`
+      );
+      fs.writeFileSync(tempSidebarPath, sidebarPngBuffer);
+    }
+
+    // Schedule concept slots
+    const uniqueConcepts = Array.from(new Set(concepts));
+    const uniqueConceptPaths = [];
+
+    for (let u = 0; u < uniqueConcepts.length; u++) {
+      const conceptSvg = generateJourneySvg({
+        width,
+        height,
+        tracks: [],
+        centerText: uniqueConcepts[u],
+        showSidebar: false,
+        theme: journeyConfig.theme || 'dark',
+        position: journeyConfig.position || 'left',
+      });
+      const conceptPngBuffer = renderSvgToPng(conceptSvg, width, height);
+      const tempConceptPath = path.join(
+        tempDir,
+        `journey_concept_${u}_${Date.now()}_${Math.random().toString(36).slice(2, 6)}.png`
+      );
+      fs.writeFileSync(tempConceptPath, conceptPngBuffer);
+      uniqueConceptPaths.push(tempConceptPath);
+    }
+
+    const slots = [];
+    if (concepts.length > 0 && conceptsTotalDuration > 0) {
+      const maxSlots = Math.max(1, Math.ceil(conceptsTotalDuration / conceptDisplaySeconds));
+      for (let s = 0; s < maxSlots; s++) {
+        const st = s * conceptDisplaySeconds;
+        const et = Math.min(conceptsTotalDuration, (s + 1) * conceptDisplaySeconds);
+        if (st >= conceptsTotalDuration || et <= st) break;
+        const phrase = concepts[s % concepts.length];
+        const uniqueIndex = uniqueConcepts.indexOf(phrase);
+        slots.push({ slotIndex: s, st, et, phrase, uniqueIndex });
+      }
+    }
+
+    const tmpOutputPath = path.join(tempDir, 'overlay_output.mp4');
+
+    return await new Promise((resolve, reject) => {
+      const command = ffmpeg();
+      command.input(inputPath);
+
+      let nextInputIndex = 1;
+      let currentV = '[0:v]';
+      const filterLines = [];
+
+      if (tempSidebarPath) {
+        const sbInputIdx = nextInputIndex++;
+        const sbLoopSeconds = Math.max(sidebarDurationSec, 1);
+        command.input(tempSidebarPath).inputOptions(['-loop', '1', '-t', `${sbLoopSeconds}`]);
+
+        const isSbFull = sidebarDisplayDuration === 'full' || (videoDuration > 0 && sidebarDurationSec >= videoDuration);
+        const sbFadeIn = 0.5;
+        const sbFadeOut = 0.5;
+        const nextV = (slots.length === 0) ? '[outv]' : '[v_after_sb]';
+
+        if (isSbFull) {
+          filterLines.push(`[${sbInputIdx}:v]format=rgba,fade=in:st=0:d=${sbFadeIn}:alpha=1[sb_faded]`);
+          filterLines.push(`${currentV}[sb_faded]overlay=0:0${nextV}`);
+        } else {
+          const sbFadeOutStart = Math.max(sbFadeIn, sidebarDurationSec - sbFadeOut);
+          filterLines.push(`[${sbInputIdx}:v]format=rgba,fade=in:st=0:d=${sbFadeIn}:alpha=1,fade=out:st=${sbFadeOutStart}:d=${sbFadeOut}:alpha=1[sb_faded]`);
+          filterLines.push(`${currentV}[sb_faded]overlay=0:0:enable='between(t,0,${sidebarDurationSec})'${nextV}`);
+        }
+        currentV = nextV;
+      }
+
+      if (slots.length > 0) {
+        const concatInputs = [];
+        slots.forEach((slot, idx) => {
+          const inputIdx = nextInputIndex++;
+          const dur = slot.et - slot.st;
+          command.input(uniqueConceptPaths[slot.uniqueIndex]).inputOptions([
+            '-loop', '1',
+            '-t', `${dur}`,
+          ]);
+
+          const fIn = Math.min(conceptFadeSeconds, dur / 2);
+          const fOut = Math.min(conceptFadeSeconds, dur / 2);
+          const fadeOutStart = Math.max(0, dur - fOut);
+          const fadeParts = [];
+          if (fIn > 0) fadeParts.push(`fade=in:st=0:d=${fIn}:alpha=1`);
+          if (fOut > 0) fadeParts.push(`fade=out:st=${fadeOutStart}:d=${fOut}:alpha=1`);
+          const fadeFilter = fadeParts.length
+            ? `format=rgba,${fadeParts.join(',')}`
+            : 'format=rgba';
+          filterLines.push(`[${inputIdx}:v]trim=0:${dur},setpts=PTS-STARTPTS,${fadeFilter}[c_slot_${idx}]`);
+          concatInputs.push(`[c_slot_${idx}]`);
+        });
+
+        if (slots.length === 1) {
+          filterLines.push(`${concatInputs[0]}copy[concepts]`);
+        } else {
+          filterLines.push(`${concatInputs.join('')}concat=n=${slots.length}:v=1:a=0[concepts]`);
+        }
+        filterLines.push(`${currentV}[concepts]overlay=0:0:eof_action=pass[outv]`);
+        currentV = '[outv]';
+      }
+
+      if (filterLines.length === 0) {
+        filterLines.push('[0:v]null[outv]');
+      }
+
+      const outputOpts = [
+        '-map', '[outv]',
+        '-map', '0:a?',
+        '-c:v', 'libx264',
+        '-preset', 'veryfast',
+        '-crf', '18',
+        '-c:a', 'copy',
+        '-pix_fmt', 'yuv420p',
+        '-movflags', '+faststart',
+        '-shortest',
+      ];
+      if (videoDuration > 0) {
+        outputOpts.push('-t', `${videoDuration}`);
+      }
+
+      const cleanup = (removeOutput = false) => {
+        for (const f of tempFilesToClean) {
+          try { fs.rmSync(f, { recursive: true, force: true }); } catch {}
+        }
+        if (fs.existsSync(tmpOutputPath)) {
+          try { fs.unlinkSync(tmpOutputPath); } catch {}
+        }
+        if (removeOutput && fs.existsSync(outputPath)) {
+          try { fs.unlinkSync(outputPath); } catch {}
+        }
+      };
+
+      command
+        .complexFilter(filterLines)
+        .outputOptions(outputOpts)
+        .output(tmpOutputPath)
+        .on('end', () => {
+          try {
+            fs.mkdirSync(path.dirname(path.resolve(outputPath)), { recursive: true });
+            fs.copyFileSync(tmpOutputPath, outputPath);
+          } catch (err) {
+            cleanup(true);
+            reject(new Error(`Journey overlay compositing failed: ${err.message}`));
+            return;
+          }
+          cleanup(false);
+          resolve({
+            outputPath,
+            duration: videoMeta.duration,
+          });
+        })
+        .on('error', (err) => {
+          cleanup(true);
+          reject(new Error(`Journey overlay compositing failed: ${err.message}`));
+        })
+        .run();
+    });
+  } catch (err) {
+    for (const f of tempFilesToClean) {
+      try { fs.rmSync(f, { recursive: true, force: true }); } catch {}
+    }
+    throw err;
+  }
+}