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

package/README.md

@@ -412,7 +412,7 @@ The actions pipeline allows non-destructive video modifications (shortening, bac
 
 1. **`shorten`**: Cut video at `cutPoint`, smoothly fade out audio and video into the cut, then append a silent padding buffer.
 2. **`replace-background`**: Keep existing audio and swap the visual background with a freshly sourced stock video or photo.
-3. **`journey-overlay`**: Burn in a sidebar playlist graphic (tracking past and current songs) and optional centered text.
+3. **`journey-overlay`**: Burn in a modern journey overlay graphic (either a sleek top-right step badge or playlist panel) and optional cycling center concepts.
 
 ### `metadata.json` Actions Configuration
 
@@ -423,19 +423,32 @@ The actions pipeline allows non-destructive video modifications (shortening, bac
   ],
   "journey": {
     "enabled": true,
-    "mode": "before-current",
+    "style": "badge",
+    "position": "right",
+    "sidebarLabel": "stage",
+    "sidebarDisplayDuration": 4,
     "theme": "dark",
-    "displayDuration": 5,
     "maxCenterChars": 60
   },
   "songs": {
     "01-first.mp4": {
+      "journeyStage": "Decision",
       "actions": [
         { "type": "shorten", "cutPoint": "02:15", "fadeDuration": 3, "paddingDuration": 2 },
-        { "type": "journey-overlay", "centerText": "What does the night sound like?" }
+        { 
+          "type": "journey-overlay", 
+          "conceptsDisplayMode": "full",
+          "conceptDisplaySeconds": 7,
+          "conceptFadeSeconds": 1,
+          "centerConcepts": [
+            "You don't feel ready.",
+            "Move anyway."
+          ]
+        }
       ]
     },
     "02-second.mp4": {
+      "journeyStage": "Sensation",
       "actions": [
         { "type": "replace-background", "query": "empty highway sunrise" }
       ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/youtube-video-uploader-cli",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "CLI tool to batch upload MP4 videos to YouTube via YouTube Data API v3 with OAuth2, metadata.json config, playlist assignment, and smart upload-state resume.",
   "main": "src/index.js",
   "types": "src/index.d.ts",

package/src/actions/index.js

@@ -116,6 +116,7 @@ export async function runActionsPipeline(entry, actions = [], context = {}) {
         const res = await shortenVideo({
           inputPath: currentInput,
           outputPath: stepOutput,
+          entry,
           ...action,
           dryRun: true,
           onWarn,
@@ -205,6 +206,7 @@ export async function runActionsPipeline(entry, actions = [], context = {}) {
         await shortenVideo({
           inputPath: currentInput,
           outputPath: stepOutput,
+          entry,
           ...action,
           dryRun: false,
           onWarn,

package/src/actions/journey-overlay.js

@@ -74,23 +74,29 @@ export function resolveJourneyTracks({ currentSongKey, rawMetadata, mode = 'befo
     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;
+      const stage = songData.journeyStage || songData.albumRole;
       return {
         key,
         title: formatTrackLabel(rawTitle, stage),
-        journeyStage: 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;
+      const stage = v.journeyStage || v.albumRole;
       return {
         key: v.filename,
         title: formatTrackLabel(rawTitle, stage),
-        journeyStage: stage,
+        rawTitle,
+        stage: stage || '',
+        journeyStage: stage || '',
         trackNumber: v.trackNumber ?? idx + 1,
+        totalTracks: rawMetadata.videos.length,
       };
     });
   }
@@ -101,10 +107,14 @@ export function resolveJourneyTracks({ currentSongKey, rawMetadata, mode = 'befo
     // 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;
+    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,
     }];
@@ -114,7 +124,11 @@ export function resolveJourneyTracks({ currentSongKey, rawMetadata, mode = 'befo
   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,
     }));
@@ -122,19 +136,25 @@ export function resolveJourneyTracks({ currentSongKey, rawMetadata, mode = 'befo
     // '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 (visibleList.length > maxVisibleRows) {
+  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,
@@ -155,7 +175,12 @@ export function resolveJourneyTracks({ currentSongKey, rawMetadata, mode = 'befo
  * @param {string} [params.centerText]
  * @param {boolean} [params.showSidebar=true]
  * @param {'dark' | 'light'} [params.theme='dark']
- * @param {'left'} [params.position='left']
+ * @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) {
@@ -166,7 +191,12 @@ export function generateJourneySvg(params) {
     centerText = '',
     showSidebar = true,
     theme = 'dark',
-    position = 'left',
+    position = 'right',
+    style = 'badge',
+    stage = '',
+    step = null,
+    totalSteps = null,
+    badgeText = 'Beyond Art',
   } = params;
 
   const isDark = theme === 'dark';
@@ -179,64 +209,86 @@ export function generateJourneySvg(params) {
   const highlightBadgeBorder = isDark ? 'rgba(56, 189, 248, 0.40)' : 'rgba(2, 132, 199, 0.30)';
 
   let sidebarSvg = '';
-  if (showSidebar && tracks.length > 0) {
-    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 {
-        // Past tracks
-        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>
-        `;
-      }
-    });
+  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>
-    `;
+      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 = 14;
-    const boxWidth = Math.min(width - 200, Math.max(320, textStr.length * approxCharWidth + 60));
-    const boxHeight = 64;
+    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 - 140;
+    const boxY = (height - boxHeight) / 2;
 
     centerTextSvg = `
       <g id="center-text">
-        <rect x="${boxX}" y="${boxY}" width="${boxWidth}" height="${boxHeight}" rx="32" fill="${sidebarBg}" stroke="${sidebarBorder}" stroke-width="1.5" />
-        <text x="${width / 2}" y="${boxY + boxHeight / 2 + 6}" font-family="system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif" font-size="20" font-weight="600" fill="${textPrimary}" text-anchor="middle">${textStr}</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>
     `;
   }
@@ -337,7 +389,7 @@ export async function applyJourneyOverlay(params) {
         currentSongKey,
         rawMetadata,
         mode: journeyConfig.mode || 'before-current',
-        maxVisibleRows: journeyConfig.maxVisibleRows || 8,
+        maxVisibleRows: journeyConfig.style === 'panel' ? (journeyConfig.maxVisibleRows || 8) : null,
         sidebarLabel,
       })
     : [];
@@ -384,7 +436,7 @@ export async function applyJourneyOverlay(params) {
     tempFilesToClean.push(tempDir);
 
     let tempSidebarPath = null;
-    if (showSidebar && tracks.length > 0) {
+    if (showSidebar && (tracks.length > 0 || entry.journeyStage || entry.albumRole)) {
       const sidebarSvg = generateJourneySvg({
         width,
         height,
@@ -392,7 +444,12 @@ export async function applyJourneyOverlay(params) {
         centerText: '',
         showSidebar: true,
         theme: journeyConfig.theme || 'dark',
-        position: journeyConfig.position || 'left',
+        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(
@@ -511,8 +568,7 @@ export async function applyJourneyOverlay(params) {
         '-c:v', 'libx264',
         '-preset', 'veryfast',
         '-crf', '18',
-        '-c:a', 'aac',
-        '-b:a', '192k',
+        '-c:a', 'copy',
         '-pix_fmt', 'yuv420p',
         '-movflags', '+faststart',
         '-shortest',

package/src/actions/replace-background.js

@@ -19,6 +19,31 @@ if (ffprobeStatic?.path && fs.existsSync(ffprobeStatic.path)) {
   ffmpeg.setFfprobePath(ffprobeStatic.path);
 }
 
+/**
+ * Find companion file with matching stem and target extension.
+ *
+ * @param {string} sourcePath
+ * @param {string} ext
+ * @returns {string | null}
+ */
+export function findCompanionFile(sourcePath, ext) {
+  if (!sourcePath) return null;
+  const dir = path.dirname(sourcePath);
+  const stem = path.basename(sourcePath, path.extname(sourcePath)).trim().toLowerCase();
+  const direct = path.join(dir, `${path.basename(sourcePath, path.extname(sourcePath))}.${ext}`);
+  if (fs.existsSync(direct)) return direct;
+  if (fs.existsSync(dir)) {
+    try {
+      const files = fs.readdirSync(dir);
+      const match = files.find(f => f.toLowerCase().endsWith('.' + ext.toLowerCase()) && path.basename(f, path.extname(f)).trim().toLowerCase() === stem);
+      if (match) return path.join(dir, match);
+    } catch {
+      // ignore
+    }
+  }
+  return null;
+}
+
 /**
  * Extract audio track from a video file.
  *
@@ -36,12 +61,22 @@ export function extractAudio(inputVideoPath, outputAudioPath) {
   return new Promise((resolve, reject) => {
     ffmpeg(inputVideoPath)
       .noVideo()
-      .audioCodec('aac')
-      .audioBitrate('192k')
+      .audioCodec('copy')
       .outputOptions(['-movflags', '+faststart'])
       .output(outputAudioPath)
       .on('end', () => resolve(outputAudioPath))
-      .on('error', (err) => reject(new Error(`Failed to extract audio from ${inputVideoPath}: ${err.message}`)))
+      .on('error', () => {
+        // Fallback to high-bitrate AAC if copy is not container-compatible
+        ffmpeg(inputVideoPath)
+          .noVideo()
+          .audioCodec('aac')
+          .audioBitrate('320k')
+          .outputOptions(['-ar', '48000', '-movflags', '+faststart'])
+          .output(outputAudioPath)
+          .on('end', () => resolve(outputAudioPath))
+          .on('error', (err) => reject(new Error(`Failed to extract audio from ${inputVideoPath}: ${err.message}`)))
+          .run();
+      })
       .run();
   });
 }
@@ -73,9 +108,11 @@ export async function replaceBackground(params) {
   const provider = action.provider || entry.media?.provider || 'auto';
   const orientation = action.orientation || entry.media?.orientation || 'landscape';
   const mode = action.mode || entry.media?.mode || 'video-loop';
+  const assPath = action.assPath || entry.assPath || findCompanionFile(entry.sourcePath || inputPath, 'ass');
 
   if (dryRun) {
-    const plan = `Replace background: query="${query}" (${provider}, ${orientation}, mode: ${mode}) + audio from ${inputPath} -> ${outputPath}`;
+    const subsNote = assPath ? ` + subtitles (${path.basename(assPath)})` : '';
+    const plan = `Replace background: query="${query}" (${provider}, ${orientation}, mode: ${mode}) + audio from ${inputPath}${subsNote} -> ${outputPath}`;
     return {
       outputPath,
       dryRun: true,
@@ -136,6 +173,7 @@ export async function replaceBackground(params) {
     targetWidth: action.width || 1920,
     targetHeight: action.height || 1080,
     fps: action.fps || 30,
+    assPath,
     dryRun: false,
   });
 

package/src/actions/shorten.js

@@ -11,6 +11,31 @@ if (ffprobeStatic?.path && fs.existsSync(ffprobeStatic.path)) {
   ffmpeg.setFfprobePath(ffprobeStatic.path);
 }
 
+/**
+ * Find companion file with matching stem and target extension.
+ *
+ * @param {string} sourcePath
+ * @param {string} ext
+ * @returns {string | null}
+ */
+export function findCompanionFile(sourcePath, ext) {
+  if (!sourcePath) return null;
+  const dir = path.dirname(sourcePath);
+  const stem = path.basename(sourcePath, path.extname(sourcePath)).trim().toLowerCase();
+  const direct = path.join(dir, `${path.basename(sourcePath, path.extname(sourcePath))}.${ext}`);
+  if (fs.existsSync(direct)) return direct;
+  if (fs.existsSync(dir)) {
+    try {
+      const files = fs.readdirSync(dir);
+      const match = files.find(f => f.toLowerCase().endsWith('.' + ext.toLowerCase()) && path.basename(f, path.extname(f)).trim().toLowerCase() === stem);
+      if (match) return path.join(dir, match);
+    } catch {
+      // ignore
+    }
+  }
+  return null;
+}
+
 /**
  * Parse time expression to seconds.
  * Supports: 'mm:ss', 'hh:mm:ss', seconds as string or number.
@@ -132,6 +157,7 @@ export async function shortenVideo(params) {
     paddingFill = 'black',
     fadeTargets = ['audio', 'video'],
     dryRun = false,
+    entry = {},
     onWarn,
   } = params;
 
@@ -144,7 +170,10 @@ export async function shortenVideo(params) {
     throw new Error(`Action "shorten" cutPoint must be greater than 0 (received: ${cutPoint}).`);
   }
 
-  let videoMeta = { duration: 0, width: 1920, height: 1080, fps: 30, sampleRate: 44100 };
+  const audioSourcePath = params.audioSourcePath || entry.sourceWav || findCompanionFile(entry.sourcePath || inputPath, 'wav');
+  const hasSeparateAudio = Boolean(audioSourcePath && fs.existsSync(audioSourcePath) && audioSourcePath !== inputPath);
+
+  let videoMeta = { duration: 0, width: 1920, height: 1080, fps: 30, sampleRate: 48000 };
   if (fs.existsSync(inputPath)) {
     try {
       videoMeta = await getVideoMetadata(inputPath);
@@ -175,7 +204,7 @@ export async function shortenVideo(params) {
   const width = videoMeta.width || 1920;
   const height = videoMeta.height || 1080;
   const fps = videoMeta.fps || 30;
-  const sampleRate = videoMeta.sampleRate || 44100;
+  const sampleRate = hasSeparateAudio ? 48000 : (videoMeta.sampleRate || 48000);
 
   const shouldFadeVideo = fadeTargets.includes('video');
   const shouldFadeAudio = fadeTargets.includes('audio');
@@ -183,7 +212,8 @@ export async function shortenVideo(params) {
   if (dryRun) {
     const videoFadePart = shouldFadeVideo ? `, fade out at ${fadeStart.toFixed(1)}s for ${effectiveFadeDuration.toFixed(1)}s` : '';
     const audioFadePart = shouldFadeAudio ? `, audio fade out at ${fadeStart.toFixed(1)}s for ${effectiveFadeDuration.toFixed(1)}s` : '';
-    const plan = `Shorten: trim to ${cutSeconds.toFixed(1)}s${videoFadePart}${audioFadePart} + ${paddingDuration}s silent padding (${paddingFill}) -> ${outputPath}`;
+    const wavNote = hasSeparateAudio ? ` [audio from ${path.basename(audioSourcePath)}]` : '';
+    const plan = `Shorten: trim to ${cutSeconds.toFixed(1)}s${videoFadePart}${audioFadePart}${wavNote} + ${paddingDuration}s silent padding (${paddingFill}) -> ${outputPath}`;
     return {
       outputPath,
       duration: totalDuration,
@@ -200,6 +230,12 @@ export async function shortenVideo(params) {
     // Input 0: source video
     command.input(inputPath);
 
+    let audioInputIndex = 0;
+    if (hasSeparateAudio) {
+      command.input(audioSourcePath);
+      audioInputIndex = 1;
+    }
+
     const complexFilters = [];
 
     // Filter video 0
@@ -209,28 +245,30 @@ export async function shortenVideo(params) {
     }
     complexFilters.push(`[0:v]${v0Filter}[v0]`);
 
-    // Filter audio 0
+    // Filter audio
     let a0Filter = `atrim=0:${cutSeconds},asetpts=PTS-STARTPTS`;
     if (shouldFadeAudio && effectiveFadeDuration > 0) {
       a0Filter += `,afade=t=out:st=${fadeStart}:d=${effectiveFadeDuration}`;
     }
-    complexFilters.push(`[0:a]${a0Filter}[a0]`);
+    complexFilters.push(`[${audioInputIndex}:a]${a0Filter}[a0]`);
 
     if (paddingDuration > 0) {
-      // Input 1 for audio padding: anullsrc
+      // Audio silence input
+      const silenceIndex = audioInputIndex + 1;
       command.input(`anullsrc=r=${sampleRate}:cl=stereo`).inputOptions(['-f', 'lavfi', '-t', `${paddingDuration}`]);
 
       if (paddingFill === 'freeze-frame') {
         // Use the last frame of the trimmed portion as padding
         complexFilters.push(`[v0]split=2[v0_out][v0_last]`);
         complexFilters.push(`[v0_last]trim=${Math.max(0, cutSeconds - 0.04)}:${cutSeconds},setpts=PTS-STARTPTS,loop=loop=-1:size=1:start=0,trim=0:${paddingDuration},setpts=PTS-STARTPTS[vpad]`);
-        complexFilters.push(`[v0_out][a0][vpad][1:a]concat=n=2:v=1:a=1[outv][outa]`);
+        complexFilters.push(`[v0_out][a0][vpad][${silenceIndex}:a]concat=n=2:v=1:a=1[outv][outa]`);
       } else {
         // Plain black padding via lavfi color, forced to match the trimmed video
+        const colorIndex = silenceIndex + 1;
         command.input(`color=c=black:s=${width}x${height}:r=${fps}:d=${paddingDuration}`).inputOptions(['-f', 'lavfi']);
         complexFilters.push(`[v0]format=yuv420p,setsar=1[v0f]`);
-        complexFilters.push(`[2:v]scale=${width}:${height}:flags=neighbor,setsar=1,fps=${fps},format=yuv420p[vpad]`);
-        complexFilters.push(`[v0f][a0][vpad][1:a]concat=n=2:v=1:a=1[outv][outa]`);
+        complexFilters.push(`[${colorIndex}:v]scale=${width}:${height}:flags=neighbor,setsar=1,fps=${fps},format=yuv420p[vpad]`);
+        complexFilters.push(`[v0f][a0][vpad][${silenceIndex}:a]concat=n=2:v=1:a=1[outv][outa]`);
       }
     } else {
       complexFilters.push(`[v0]copy[outv]`);
@@ -246,7 +284,8 @@ export async function shortenVideo(params) {
         '-crf', '18',
         '-preset', 'veryfast',
         '-c:a', 'aac',
-        '-b:a', '192k',
+        '-b:a', '320k',
+        '-ar', '48000',
         '-pix_fmt', 'yuv420p',
         '-movflags', '+faststart',
         `-t`, `${totalDuration}`,

package/src/batch/plan.js

@@ -116,11 +116,12 @@ export function planBatchActions(sourceDir, options = {}) {
   const journeyConfig = {
     enabled: true,
     mode: 'before-current',
-    position: 'left',
-    displayDuration: 5,
+    position: 'right',
+    displayDuration: 4,
     sidebarDisplayDuration: undefined,
-    sidebarLabel: 'title',
+    sidebarLabel: 'stage',
     theme: 'dark',
+    style: 'badge',
     maxCenterChars: 60,
     maxVisibleRows: 8,
     ...(rawMetadata.journey || {}),

package/src/cli/preview-journey.js

@@ -38,11 +38,12 @@ export async function previewJourney(songKey, options = {}) {
   const journeyConfig = {
     enabled: true,
     mode: 'before-current',
-    position: 'left',
-    displayDuration: 5,
+    position: 'right',
+    displayDuration: 4,
     sidebarDisplayDuration: undefined,
-    sidebarLabel: 'title',
+    sidebarLabel: 'stage',
     theme: 'dark',
+    style: 'badge',
     maxCenterChars: 60,
     maxVisibleRows: 8,
     ...(rawMetadata.journey || {}),
@@ -71,7 +72,7 @@ export async function previewJourney(songKey, options = {}) {
     currentSongKey: songKey,
     rawMetadata,
     mode: journeyConfig.mode,
-    maxVisibleRows: journeyConfig.maxVisibleRows,
+    maxVisibleRows: journeyConfig.style === 'panel' ? journeyConfig.maxVisibleRows : null,
     sidebarLabel: journeyConfig.sidebarLabel,
   });
 
@@ -86,6 +87,10 @@ export async function previewJourney(songKey, options = {}) {
     showSidebar: journeyConfig.enabled !== false,
     theme: journeyConfig.theme,
     position: journeyConfig.position,
+    style: journeyConfig.style,
+    stage: songData.journeyStage || songData.albumRole,
+    step: typeof songData.trackNumber === 'number' ? songData.trackNumber : (songData.playlistPosition !== undefined ? songData.playlistPosition + 1 : undefined),
+    totalSteps: rawMetadata.album?.trackCount || rawMetadata.album?.arc?.length || (tracks[0]?.totalTracks) || 11,
   });
 
   const pngBuffer = renderSvgToPng(svgContent, width, height);

package/src/index.d.ts

@@ -505,7 +505,9 @@ export type VideoAction = ShortenAction | ReplaceBackgroundAction | JourneyOverl
 export interface JourneyConfig {
   enabled?: boolean;
   mode?: 'before-current' | 'all';
-  position?: 'left';
+  position?: 'left' | 'right';
+  style?: 'badge' | 'panel';
+  badgeText?: string;
   displayDuration?: number | 'full';
   sidebarDisplayDuration?: number | 'full';
   sidebarLabel?: 'title' | 'stage' | 'both';
@@ -614,7 +616,12 @@ export function generateJourneySvg(params: {
   centerText?: string;
   showSidebar?: boolean;
   theme?: 'dark' | 'light';
-  position?: 'left';
+  position?: 'left' | 'right';
+  style?: 'badge' | 'panel';
+  stage?: string;
+  step?: number;
+  totalSteps?: number;
+  badgeText?: string;
 }): string;
 
 export function renderSvgToPng(svgContent: string, width?: number, height?: number): Buffer;

package/src/media/compose.js

@@ -3,6 +3,7 @@ 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';
 
 // Configure ffmpeg and ffprobe paths if available
 if (ffmpegStatic && fs.existsSync(ffmpegStatic)) {
@@ -12,6 +13,47 @@ if (ffprobeStatic?.path && fs.existsSync(ffprobeStatic.path)) {
   ffmpeg.setFfprobePath(ffprobeStatic.path);
 }
 
+const ASS_FILTER_UNSAFE = /['\[\]:;\\,]/;
+
+/**
+ * Return a safe path to pass to ffmpeg's `ass=` filter.
+ *
+ * @param {string} assPath
+ * @returns {{ filterPath: string | null, cleanupPath?: string }}
+ */
+export function resolveAssFilterPath(assPath) {
+  if (!assPath || !fs.existsSync(assPath)) {
+    return { filterPath: null };
+  }
+  if (!ASS_FILTER_UNSAFE.test(assPath)) {
+    return { filterPath: assPath };
+  }
+  const cleanupPath = path.join(
+    os.tmpdir(),
+    `compose-ass-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.ass`
+  );
+  try {
+    fs.copyFileSync(assPath, cleanupPath);
+    return { filterPath: cleanupPath, cleanupPath };
+  } catch {
+    return { filterPath: assPath };
+  }
+}
+
+/**
+ * Quote and escape special characters in path for ffmpeg filter syntax.
+ *
+ * @param {string} filePath
+ * @returns {string}
+ */
+export function escapeForFfmpeg(filePath) {
+  const escaped = String(filePath)
+    .replaceAll('\\', '\\\\')
+    .replaceAll(':', '\\:')
+    .replaceAll("'", "\\'");
+  return `'${escaped}'`;
+}
+
 /**
  * Get the duration of an audio or video file in seconds using ffprobe.
  *
@@ -72,6 +114,7 @@ export async function composeVideo(options) {
     targetHeight = 1080,
     fps = 30,
     dryRun = false,
+    assPath = null,
     onProgress,
   } = options;
 
@@ -98,12 +141,31 @@ export async function composeVideo(options) {
   }
 
   const isImage = bgDuration === 0 || mode === 'ken-burns';
-  const scaleCropFilter = `scale=${targetWidth}:${targetHeight}:force_original_aspect_ratio=increase,crop=${targetWidth}:${targetHeight},format=yuv420p`;
+  const baseScaleFilter = `scale=${targetWidth}:${targetHeight}:force_original_aspect_ratio=increase,crop=${targetWidth}:${targetHeight},format=yuv420p`;
+
+  let assCleanupPath = null;
+  let scaleCropFilter = baseScaleFilter;
+  if (assPath && fs.existsSync(assPath)) {
+    const resolved = resolveAssFilterPath(assPath);
+    if (resolved.filterPath) {
+      assCleanupPath = resolved.cleanupPath || null;
+      scaleCropFilter = `${baseScaleFilter},ass=${escapeForFfmpeg(resolved.filterPath)}`;
+    }
+  }
+
+  const cleanup = () => {
+    if (assCleanupPath && fs.existsSync(assCleanupPath)) {
+      try { fs.unlinkSync(assCleanupPath); } catch {}
+      assCleanupPath = null;
+    }
+  };
 
   if (dryRun) {
+    cleanup();
+    const subsNote = assPath ? ` + subtitles (${path.basename(assPath)})` : '';
     const planDescription = isImage
-      ? `Image (${backgroundPath}) + Audio (${audioPath}, ${audioDuration.toFixed(1)}s) -> ${outputPath} [${targetWidth}x${targetHeight} @ ${fps}fps, mode: ${mode}]`
-      : `Video (${backgroundPath}, ${bgDuration.toFixed(1)}s) + Audio (${audioPath}, ${audioDuration.toFixed(1)}s) -> ${outputPath} [${targetWidth}x${targetHeight} @ ${fps}fps, mode: ${mode}]`;
+      ? `Image (${backgroundPath}) + Audio (${audioPath}, ${audioDuration.toFixed(1)}s)${subsNote} -> ${outputPath} [${targetWidth}x${targetHeight} @ ${fps}fps, mode: ${mode}]`
+      : `Video (${backgroundPath}, ${bgDuration.toFixed(1)}s) + Audio (${audioPath}, ${audioDuration.toFixed(1)}s)${subsNote} -> ${outputPath} [${targetWidth}x${targetHeight} @ ${fps}fps, mode: ${mode}]`;
 
     return {
       outputPath,
@@ -116,15 +178,22 @@ export async function composeVideo(options) {
   return new Promise((resolve, reject) => {
     const command = ffmpeg();
 
+    const audioOpts = [
+      '-c:a', 'aac',
+      '-b:a', '320k',
+      '-ar', '48000',
+    ];
+
     if (isImage) {
       if (mode === 'ken-burns') {
         const totalFrames = Math.max(30, Math.ceil(audioDuration * fps));
+        const kenBurnsFilter = `scale=8000:-1,zoompan=z='min(zoom+0.0008,1.25)':d=${totalFrames}:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)':s=${targetWidth}x${targetHeight}:fps=${fps},${scaleCropFilter}`;
         command
           .input(backgroundPath)
           .inputOptions(['-loop', '1'])
           .input(audioPath)
           .complexFilter([
-            `scale=8000:-1,zoompan=z='min(zoom+0.0008,1.25)':d=${totalFrames}:x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)':s=${targetWidth}x${targetHeight}:fps=${fps},${scaleCropFilter}[v]`,
+            `${kenBurnsFilter}[v]`,
           ])
           .outputOptions([
             '-map', '[v]',
@@ -132,8 +201,7 @@ export async function composeVideo(options) {
             '-c:v', 'libx264',
             '-preset', 'veryfast',
             '-crf', '20',
-            '-c:a', 'aac',
-            '-b:a', '192k',
+            ...audioOpts,
             '-shortest',
             `-t`, `${audioDuration}`,
             '-pix_fmt', 'yuv420p',
@@ -147,11 +215,12 @@ export async function composeVideo(options) {
           .input(audioPath)
           .videoFilters([scaleCropFilter])
           .outputOptions([
+            '-map', '0:v',
+            '-map', '1:a',
             '-c:v', 'libx264',
             '-preset', 'veryfast',
             '-crf', '20',
-            '-c:a', 'aac',
-            '-b:a', '192k',
+            ...audioOpts,
             '-shortest',
             `-t`, `${audioDuration}`,
             `-r`, `${fps}`,
@@ -169,11 +238,12 @@ export async function composeVideo(options) {
           .input(audioPath)
           .videoFilters([scaleCropFilter])
           .outputOptions([
+            '-map', '0:v',
+            '-map', '1:a',
             '-c:v', 'libx264',
             '-preset', 'veryfast',
             '-crf', '20',
-            '-c:a', 'aac',
-            '-b:a', '192k',
+            ...audioOpts,
             '-shortest',
             `-t`, `${audioDuration}`,
             `-r`, `${fps}`,
@@ -187,11 +257,12 @@ export async function composeVideo(options) {
           .input(audioPath)
           .videoFilters([scaleCropFilter])
           .outputOptions([
+            '-map', '0:v',
+            '-map', '1:a',
             '-c:v', 'libx264',
             '-preset', 'veryfast',
             '-crf', '20',
-            '-c:a', 'aac',
-            '-b:a', '192k',
+            ...audioOpts,
             '-shortest',
             `-t`, `${audioDuration}`,
             `-r`, `${fps}`,
@@ -208,12 +279,14 @@ export async function composeVideo(options) {
     command
       .output(outputPath)
       .on('end', () => {
+        cleanup();
         resolve({
           outputPath,
           duration: audioDuration,
         });
       })
       .on('error', (err) => {
+        cleanup();
         // Clean up partial output if any
         if (fs.existsSync(outputPath)) {
           try {