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

package/bin/cli.js

@@ -4,12 +4,45 @@ import { Command } from 'commander';
 import path from 'node:path';
 import fs from 'node:fs';
 import pc from 'picocolors';
-import { batchUpload, DAILY_DEFAULT_QUOTA } from '../src/index.js';
+import { google } from 'googleapis';
+import {
+  batchUpload,
+  DAILY_DEFAULT_QUOTA,
+  swapSong,
+  SwapStore,
+  QUOTA_PER_SWAP,
+  batchUpdateMetadata,
+  searchMedia,
+  rankCandidates,
+  resolveMediaForMetadata,
+  composeVideo,
+  batchApplyActions,
+  previewJourney,
+} from '../src/index.js';
+import { authenticate } from '../src/auth.js';
 
 // Read package.json for version
 const pkgPath = new URL('../package.json', import.meta.url);
 const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
 
+// Auto-load .env if available
+try {
+  process.loadEnvFile?.();
+} catch {}
+try {
+  let searchDir = process.cwd();
+  for (let i = 0; i < 4; i++) {
+    const candidate = path.join(searchDir, '.env');
+    if (fs.existsSync(candidate)) {
+      process.loadEnvFile?.(candidate);
+      break;
+    }
+    const parent = path.dirname(searchDir);
+    if (parent === searchDir) break;
+    searchDir = parent;
+  }
+} catch {}
+
 const program = new Command();
 
 program
@@ -24,6 +57,10 @@ program
   .option('-l, --limit <number>', 'Maximum number of videos to upload in this run (e.g. 5 or 6)')
   .option('--safe-quota', 'Cap upload batch to stay safely within standard daily 10,000 units quota (default ~5-6 videos)', false)
   .option('--max-quota <units>', 'Maximum allowed API quota units for this run')
+  .option('--auto-media', 'Resolve and compose stock media for missing videos before uploading', false)
+  .option('--media-provider <provider>', 'Stock media provider for --auto-media: pexels, pixabay, auto (default: auto)')
+  .option('--pexels-key <key>', 'Pexels API key')
+  .option('--pixabay-key <key>', 'Pixabay API key')
   .option('--client-id <id>', 'Google OAuth Client ID')
   .option('--client-secret <secret>', 'Google OAuth Client Secret')
   .option('--client-secrets-file <file>', 'Path to client_secret.json downloaded from Google Cloud')
@@ -68,6 +105,10 @@ program
         limit: options.limit ? parseInt(options.limit, 10) : undefined,
         safeQuota: options.safeQuota,
         maxQuota: options.maxQuota ? parseInt(options.maxQuota, 10) : undefined,
+        autoMedia: options.autoMedia,
+        mediaProvider: options.mediaProvider,
+        pexelsKey: options.pexelsKey,
+        pixabayKey: options.pixabayKey,
         tokenFile,
         clientSecretsFile: options.clientSecretsFile,
         clientId: options.clientId,
@@ -75,7 +116,17 @@ program
         onEvent: (event) => {
           if (isQuiet) return;
 
-          if (event.type === 'plan') {
+          if (event.type === 'auto_media_start') {
+            console.log(pc.cyan(`🎬 Sourcing & resolving stock media (--auto-media)...`));
+          } else if (event.type === 'search_start') {
+            console.log(`  🔍 Searching ${event.provider} for "${event.query}" (${event.songKey})...`);
+          } else if (event.type === 'compose_start') {
+            console.log(`  🎞️  Composing video for ${pc.bold(event.songKey)} via ffmpeg...`);
+          } else if (event.type === 'compose_success') {
+            console.log(pc.green(`     ✅ Composed:`), pc.dim(event.outputPath));
+          } else if (event.type === 'auto_media_complete') {
+            console.log(pc.green(`✨ Stock media resolution complete.\n`));
+          } else if (event.type === 'plan') {
             console.log(
               pc.bold(`Found `) +
               pc.green(pc.bold(`${event.total}`)) +
@@ -183,4 +234,686 @@ program
     }
   });
 
+program
+  .command('swap')
+  .description('Replace a song\'s video in a YouTube playlist: upload the new video, swap the playlist entry in place, unlist (never delete) the old video')
+  .argument('<videoFile>', 'Path to the new MP4 video file')
+  .requiredOption('--playlist <id>', 'Playlist ID containing the old video')
+  .requiredOption('--old-video <videoId>', 'Video ID of the old video to replace')
+  .option('-k, --key <songKey>', 'Stable song key for swap state tracking (default: video file basename)')
+  .option('--title <title>', 'Override the new video title (default: carried over from the old video)')
+  .option('--state-file <file>', 'Swap state filename (default: .swap-history.json in target dir)')
+  .option('--token-file <file>', 'Path to store or read OAuth token (default: token.json in cwd)')
+  .option('--client-secrets-file <file>', 'Path to client_secret.json downloaded from Google Cloud')
+  .option('--client-id <id>', 'Google OAuth Client ID')
+  .option('--client-secret <secret>', 'Google OAuth Client Secret')
+  .option('--fresh', 'Discard any previous swap state for this key and start over', false)
+  .option('-n, --dry-run', 'Print the swap plan without any API calls', false)
+  .option('-q, --quiet', 'Minimal output mode', false)
+  .action(async (videoFile, options) => {
+    const isQuiet = options.quiet;
+    const videoPath = path.resolve(videoFile);
+    const songKey = options.key || path.basename(videoPath);
+    const stateDir = process.cwd();
+
+    if (!isQuiet) {
+      console.log();
+      console.log(pc.bold(pc.red(`🔁 Playlist Video Swap`)) + ` ${pc.dim(`v${pkg.version}`)}`);
+      console.log(pc.dim(`──────────────────────────────────────────────────────────`));
+      console.log(`${pc.bold('🎬 New Video      :')} ${pc.white(videoPath)}`);
+      console.log(`${pc.bold('🗑️  Old Video ID   :')} ${pc.white(options.oldVideo)}`);
+      console.log(`${pc.bold('📑 Playlist ID    :')} ${pc.white(options.playlist)}`);
+      console.log(`${pc.bold('🔑 Swap Key       :')} ${pc.white(songKey)}`);
+      console.log(pc.dim(`Estimated quota  : ~${QUOTA_PER_SWAP - 1} shared units + 1 upload`));
+      console.log();
+    }
+
+    if (!fs.existsSync(videoPath)) {
+      console.error(pc.red(`\n❌ Error: Video file not found: ${videoPath}\n`));
+      process.exit(1);
+    }
+
+    if (options.dryRun) {
+      if (!isQuiet) {
+        console.log(pc.yellow(`🔍 DRY RUN — the following steps would run:`));
+        console.log(`  1. UPLOAD    — videos.insert (unlisted), metadata carried over from old video`);
+        console.log(`  2. LOCATE    — playlistItems.list to find old item id + position`);
+        console.log(`  3. INSERT    — playlistItems.insert at the old position`);
+        console.log(`  4. REMOVE    — playlistItems.delete for the old item`);
+        console.log(`  5. FINALIZE  — old video → unlisted, new video → public`);
+        console.log();
+        console.log(pc.yellow(`✨ Dry run complete. No API calls were made.`));
+        console.log();
+      }
+      process.exit(0);
+    }
+
+    try {
+      const tokenFile = options.tokenFile
+        ? path.resolve(options.tokenFile)
+        : path.join(stateDir, 'token.json');
+
+      const auth = await authenticate({
+        tokenFile,
+        clientSecretsFile: options.clientSecretsFile,
+        clientId: options.clientId,
+        clientSecret: options.clientSecret,
+      });
+      const youtube = google.youtube({ version: 'v3', auth });
+
+      const store = new SwapStore(stateDir, options.stateFile);
+      const existing = store.getRecord(songKey);
+      if (existing && !options.fresh && !isQuiet) {
+        console.log(pc.cyan(`↩️  Resuming swap in progress (last status: ${existing.status}${existing.lastError ? ` — ${existing.lastError}` : ''})`));
+        console.log();
+      }
+
+      const { record } = await swapSong({
+        youtube,
+        songKey,
+        newVideoPath: videoPath,
+        playlistId: options.playlist,
+        oldVideoId: options.oldVideo,
+        meta: options.title ? { title: options.title } : undefined,
+        stateDir,
+        stateFile: options.stateFile,
+        fresh: options.fresh,
+        onEvent: (event) => {
+          if (isQuiet) return;
+          if (event.type === 'swap_step') {
+            console.log(pc.green(`  ✅ ${event.status.toUpperCase()}`));
+          } else if (event.type === 'swap_uploaded') {
+            console.log(pc.green(`  ⬆️  Uploaded new video: `) + pc.underline(pc.blue(event.url)));
+          } else if (event.type === 'swap_error') {
+            console.error(pc.red(`  ❌ Failed at swap step: ${event.error.message}`));
+            if (event.needsManualReview) {
+              console.error(pc.yellow(`     ⚠️  Needs manual review — the old video was not found in the playlist.`));
+            }
+          }
+        },
+      });
+
+      if (!isQuiet) {
+        console.log();
+        console.log(pc.green(pc.bold(`🎉 Swap complete!`)));
+        console.log(`  • Playlist entry replaced: ${pc.bold(options.playlist)} (position preserved)`);
+        console.log(`  • New video is public    : ${pc.underline(pc.blue(`https://youtu.be/${record.newVideoId}`))}`);
+        console.log(`  • Old video unlisted     : ${pc.dim(`https://youtu.be/${options.oldVideo} (direct links still work)`)}`);
+        console.log();
+      }
+    } catch (err) {
+      console.error(pc.red(`\n❌ Error: ${err.message}\n`));
+      process.exit(1);
+    }
+  });
+
+program
+  .command('update-metadata')
+  .alias('update-titles')
+  .description('Update titles and snippet metadata for videos and playlists on YouTube and in metadata.json')
+  .argument('[directory]', 'Target folder containing metadata.json and upload history (default: current directory)', '.')
+  .option('-d, --dir <path>', 'Explicit target directory path')
+  .option('-m, --metadata <file>', 'Custom path to metadata.json file')
+  .option('--title-postfix <postfix>', 'Postfix to append to each video title (e.g. " (long version)")')
+  .option('--playlist-postfix <postfix>', 'Postfix to append to playlist title (e.g. " (long versions)")')
+  .option('--title-prefix <prefix>', 'Prefix to prepend to each video title')
+  .option('--playlist-title <title>', 'Explicit new title for the playlist')
+  .option('--replace-pattern <pattern>', 'Regex/string pattern to replace in titles')
+  .option('--replace-with <replacement>', 'Replacement string for --replace-pattern', '')
+  .option('--sync-metadata', 'Sync titles directly from metadata.json to YouTube')
+  .option('--video <videoId>', 'Target a specific YouTube video ID')
+  .option('--title <title>', 'Explicit new title for the targeted video')
+  .option('--playlist <playlistId>', 'Target a specific YouTube playlist ID')
+  .option('--no-update-file', 'Do not update metadata.json on disk')
+  .option('-n, --dry-run', 'Preview changes without making any API calls')
+  .option('--token-file <file>', 'Path to store or read OAuth token (default: token.json in target dir)')
+  .option('--client-secrets-file <file>', 'Path to client_secret.json downloaded from Google Cloud')
+  .option('--client-id <id>', 'Google OAuth Client ID')
+  .option('--client-secret <secret>', 'Google OAuth Client Secret')
+  .option('-q, --quiet', 'Minimal output mode', false)
+  .action(async (directoryArg, options) => {
+    const targetDir = path.resolve(options.dir || directoryArg || process.cwd());
+    const isQuiet = options.quiet;
+
+    if (!isQuiet) {
+      console.log();
+      console.log(pc.bold(pc.cyan(`📝 YouTube Metadata & Title Updater`)) + ` ${pc.dim(`v${pkg.version}`)}`);
+      console.log(pc.dim(`──────────────────────────────────────────────────────────`));
+      console.log(`${pc.bold('📂 Target Folder   :')} ${pc.white(targetDir)}`);
+      if (options.titlePostfix) {
+        console.log(`${pc.bold('🏷️  Title Postfix   :')} ${pc.green(JSON.stringify(options.titlePostfix))}`);
+      }
+      if (options.playlistPostfix) {
+        console.log(`${pc.bold('📑 Playlist Postfix:')} ${pc.green(JSON.stringify(options.playlistPostfix))}`);
+      }
+      if (options.titlePrefix) {
+        console.log(`${pc.bold('🏷️  Title Prefix    :')} ${pc.green(JSON.stringify(options.titlePrefix))}`);
+      }
+      if (options.dryRun) {
+        console.log(`${pc.yellow(pc.bold('🔍 Mode            :'))} ${pc.yellow('DRY RUN (no updates will be performed)')}`);
+      }
+      console.log();
+    }
+
+    try {
+      const tokenFile = options.tokenFile
+        ? path.resolve(options.tokenFile)
+        : path.join(targetDir, 'token.json');
+
+      const result = await batchUpdateMetadata(targetDir, {
+        titlePostfix: options.titlePostfix,
+        titlePrefix: options.titlePrefix,
+        playlistPostfix: options.playlistPostfix,
+        playlistTitle: options.playlistTitle,
+        replacePattern: options.replacePattern,
+        replaceWith: options.replaceWith,
+        syncMetadata: options.syncMetadata,
+        metadataFile: options.metadata,
+        updateLocalMetadata: options.updateFile !== false,
+        singleVideoId: options.video,
+        singleVideoTitle: options.title,
+        singlePlaylistId: options.playlist,
+        dryRun: options.dryRun,
+        tokenFile,
+        clientSecretsFile: options.clientSecretsFile,
+        clientId: options.clientId,
+        clientSecret: options.clientSecret,
+        onEvent: (event) => {
+          if (isQuiet) return;
+
+          if (event.type === 'update_plan') {
+            if (event.playlist) {
+              console.log(pc.bold('📑 Playlist: ') + pc.dim(event.playlist.playlistId));
+              if (event.playlist.changed) {
+                console.log(`  ${pc.dim('Old:')} ${event.playlist.oldTitle}`);
+                console.log(`  ${pc.green('New:')} ${pc.bold(event.playlist.newTitle)}`);
+              } else {
+                console.log(`  ${pc.dim('Unchanged:')} ${event.playlist.oldTitle}`);
+              }
+              console.log();
+            }
+
+            console.log(pc.bold(`🎬 Videos (${event.videos.length} total, ${event.changedCount} item(s) to update):`));
+            for (const v of event.videos) {
+              if (v.changed) {
+                console.log(`  • ${pc.cyan(v.filename)} ${pc.dim(`(${v.videoId})`)}`);
+                console.log(`    ${pc.dim('Old:')} ${v.oldTitle}`);
+                console.log(`    ${pc.green('New:')} ${pc.bold(v.newTitle)}`);
+              } else {
+                console.log(`  • ${pc.dim(v.filename)} ${pc.dim(`(${v.videoId}) — unchanged`)}`);
+              }
+            }
+            console.log();
+            console.log(
+              pc.bold(`Estimated API Quota: `) +
+              pc.green(pc.bold(`${event.estimatedQuota} units`)) +
+              pc.dim(` / ${DAILY_DEFAULT_QUOTA} daily default units`)
+            );
+            console.log();
+          } else if (event.type === 'playlist_update_start') {
+            process.stdout.write(`  ${pc.cyan('📑')} Updating playlist title... `);
+          } else if (event.type === 'playlist_update_success') {
+            console.log(pc.green('UPDATED!'));
+          } else if (event.type === 'video_update_start') {
+            process.stdout.write(`  ${pc.cyan('🎬')} [${event.index + 1}/${event.total}] Updating "${event.item.filename}"... `);
+          } else if (event.type === 'video_update_success') {
+            console.log(pc.green('UPDATED!'));
+          } else if (event.type === 'metadata_file_saved') {
+            console.log(`  ${pc.dim('📄 Saved updated titles to metadata.json')}`);
+          }
+        },
+      });
+
+      if (!isQuiet) {
+        if (options.dryRun) {
+          console.log(pc.yellow(`✨ Dry run complete. No YouTube updates were performed.`));
+          console.log();
+          process.exit(0);
+        }
+
+        console.log(pc.dim(`──────────────────────────────────────────────────────────`));
+        console.log(pc.green(pc.bold(`🎉 All titles and metadata updated successfully!`)));
+        console.log();
+      }
+    } catch (err) {
+      console.error(pc.red(`\n❌ Error: ${err.message}\n`));
+      process.exit(1);
+    }
+  });
+
+program
+  .command('search-media')
+  .description('Search and preview ranked stock media from Pexels and Pixabay without downloading')
+  .argument('<query>', 'Search query term')
+  .option('--type <video|photo>', 'Media type to search (default: video)', 'video')
+  .option('--provider <pexels|pixabay|auto>', 'Provider to use (default: auto)', 'auto')
+  .option('--orientation <landscape|portrait|square>', 'Orientation filter')
+  .option('--min-width <px>', 'Minimum width in pixels')
+  .option('--min-height <px>', 'Minimum height in pixels')
+  .option('--min-duration <seconds>', 'Minimum duration in seconds (video only)')
+  .option('--max-duration <seconds>', 'Maximum duration in seconds (video only)')
+  .option('--count <n>', 'Number of results to show (default: 10)', '10')
+  .option('--safe-search', 'Enable safe search filtering', true)
+  .option('--pexels-key <key>', 'Pexels API key')
+  .option('--pixabay-key <key>', 'Pixabay API key')
+  .option('--json', 'Print raw structured JSON results instead of a table', false)
+  .option('-q, --quiet', 'Minimal output mode', false)
+  .action(async (query, options) => {
+    const isQuiet = options.quiet;
+    const count = parseInt(options.count, 10) || 10;
+
+    try {
+      const results = await searchMedia({
+        query,
+        type: options.type,
+        provider: options.provider,
+        orientation: options.orientation,
+        safeSearch: options.safeSearch !== false,
+        pexelsKey: options.pexelsKey,
+        pixabayKey: options.pixabayKey,
+      });
+
+      const criteria = {
+        orientation: options.orientation || 'landscape',
+        minWidth: options.minWidth ? parseInt(options.minWidth, 10) : undefined,
+        minHeight: options.minHeight ? parseInt(options.minHeight, 10) : undefined,
+        minDuration: options.minDuration ? parseFloat(options.minDuration) : undefined,
+        maxDuration: options.maxDuration ? parseFloat(options.maxDuration) : undefined,
+        avoidReuse: false,
+      };
+
+      const ranked = rankCandidates(results, criteria).slice(0, count);
+
+      if (options.json) {
+        console.log(JSON.stringify(ranked.map(r => ({
+          ...r.candidate,
+          score: Math.round(r.score * 1000) / 1000,
+          breakdown: r.breakdown,
+        })), null, 2));
+        return;
+      }
+
+      if (!isQuiet) {
+        console.log();
+        console.log(pc.bold(pc.cyan(`🔍 Stock Media Search Results`)) + ` ${pc.dim(`("${query}")`)}`);
+        console.log(pc.dim(`──────────────────────────────────────────────────────────────────────────────────────────`));
+        if (ranked.length === 0) {
+          console.log(pc.yellow(`No matching media assets found.`));
+          console.log();
+          return;
+        }
+
+        console.log(
+          pc.bold(
+            `Rank  Provider  Asset ID  Dimensions  Duration  Score   Creator             Page URL`
+          )
+        );
+        console.log(pc.dim(`──────────────────────────────────────────────────────────────────────────────────────────`));
+
+        ranked.forEach((item, idx) => {
+          const c = item.candidate;
+          const rankStr = `#${idx + 1}`.padEnd(6);
+          const provStr = c.provider.padEnd(10);
+          const idStr = String(c.id).padEnd(10);
+          const dimStr = `${c.width}x${c.height}`.padEnd(12);
+          const durStr = (c.duration ? `${c.duration.toFixed(1)}s` : 'N/A').padEnd(10);
+          const scoreStr = item.score.toFixed(3).padEnd(8);
+          const creatorStr = (c.creator?.name || 'Unknown').slice(0, 18).padEnd(20);
+          const urlStr = pc.blue(pc.underline(c.pageUrl));
+
+          console.log(`${pc.green(rankStr)}${provStr}${idStr}${dimStr}${durStr}${pc.yellow(scoreStr)}${creatorStr}${urlStr}`);
+        });
+        console.log();
+        console.log(pc.dim(`Showing top ${ranked.length} of ${results.length} total found items.`));
+        console.log();
+      }
+    } catch (err) {
+      console.error(pc.red(`\n❌ Error: ${err.message}\n`));
+      process.exit(1);
+    }
+  });
+
+program
+  .command('resolve-media')
+  .description('Search, download, and write back stock media to metadata.json')
+  .argument('[directory]', 'Target folder containing metadata.json (default: current directory)', '.')
+  .option('-d, --dir <path>', 'Explicit target directory path')
+  .option('-m, --metadata <file>', 'Custom path to metadata.json file')
+  .option('--provider <pexels|pixabay|auto>', 'Provider to use: pexels, pixabay, auto (default: auto)')
+  .option('--type <video|photo>', 'Media type to resolve (default: video)')
+  .option('--orientation <landscape|portrait|square>', 'Orientation filter')
+  .option('--compose', 'Also build the final .mp4 via ffmpeg immediately', false)
+  .option('--force', 'Re-resolve entries that already have resolvedMedia', false)
+  .option('--allow-repeat-media', 'Disable the avoid-reuse novelty check for this run', false)
+  .option('--media-dir <path>', 'Override .media-cache directory location')
+  .option('--pexels-key <key>', 'Pexels API key')
+  .option('--pixabay-key <key>', 'Pixabay API key')
+  .option('-n, --dry-run', 'Show picks without downloading or writing metadata.json', false)
+  .option('-q, --quiet', 'Minimal output mode', false)
+  .action(async (directoryArg, options) => {
+    const targetDir = path.resolve(options.dir || directoryArg || process.cwd());
+    const isQuiet = options.quiet;
+
+    if (!isQuiet) {
+      console.log();
+      console.log(pc.bold(pc.cyan(`🎬 Stock Media Resolver`)) + ` ${pc.dim(`v${pkg.version}`)}`);
+      console.log(pc.dim(`──────────────────────────────────────────────────────────`));
+      console.log(`${pc.bold('📂 Target Folder   :')} ${pc.white(targetDir)}`);
+      if (options.metadata) {
+        console.log(`${pc.bold('📄 Metadata File   :')} ${pc.white(path.resolve(options.metadata))}`);
+      }
+      if (options.compose) {
+        console.log(`${pc.bold('🎞️  Video Compose   :')} ${pc.green('ENABLED (building final .mp4 with ffmpeg)')}`);
+      }
+      if (options.dryRun) {
+        console.log(`${pc.yellow(pc.bold('🔍 Mode            :'))} ${pc.yellow('DRY RUN (no downloads or file writes)')}`);
+      }
+      console.log();
+    }
+
+    try {
+      const metadataPath = options.metadata ? path.resolve(options.metadata) : targetDir;
+      const result = await resolveMediaForMetadata(metadataPath, {
+        compose: options.compose,
+        force: options.force,
+        dryRun: options.dryRun,
+        allowRepeatMedia: options.allowRepeatMedia,
+        provider: options.provider,
+        type: options.type,
+        orientation: options.orientation,
+        cacheDir: options.mediaDir,
+        pexelsKey: options.pexelsKey,
+        pixabayKey: options.pixabayKey,
+        onEvent: (event) => {
+          if (isQuiet) return;
+
+          if (event.type === 'search_start') {
+            process.stdout.write(`  🔍 [${event.songKey}] Searching ${pc.cyan(event.provider)} for "${event.query}"... `);
+          } else if (event.type === 'search_results') {
+            console.log(pc.green(`Found ${event.totalFound} (top pick: #${event.topCandidate.id}, score: ${event.score.toFixed(3)})`));
+          } else if (event.type === 'download_start') {
+            process.stdout.write(`     ⬇️  Downloading asset ${event.provider}:${event.assetId}... `);
+          } else if (event.type === 'download_success') {
+            console.log(pc.green(`SAVED`));
+          } else if (event.type === 'compose_start') {
+            process.stdout.write(`     🎞️  Muxing audio + background into .mp4... `);
+          } else if (event.type === 'compose_success') {
+            console.log(pc.green(`COMPOSED: `) + pc.dim(event.outputPath));
+          } else if (event.type === 'item_resolved') {
+            console.log(pc.green(`  ✅ Resolved `) + pc.bold(event.songKey) + ` -> ${event.resolvedMedia.credit}`);
+            console.log();
+          } else if (event.type === 'item_skipped') {
+            console.log(pc.dim(`  ⏭️  Skipped ${event.songKey} (${event.reason})`));
+          } else if (event.type === 'item_error') {
+            console.error(pc.red(`\n  ❌ Error for ${event.songKey}: ${event.error}`));
+          }
+        },
+      });
+
+      if (!isQuiet) {
+        console.log(pc.dim(`──────────────────────────────────────────────────────────`));
+        console.log(pc.bold(`📊 Summary:`));
+        console.log(`  • Resolved       : ${pc.green(pc.bold(result.resolved.length))}`);
+        console.log(`  • Skipped        : ${pc.dim(result.skipped.length)}`);
+        if (result.errors.length > 0) {
+          console.log(`  • Errors / Review: ${pc.red(pc.bold(result.errors.length))}`);
+        }
+        console.log();
+
+        if (options.dryRun) {
+          console.log(pc.yellow(`✨ Dry run complete. No media files or metadata were written.`));
+          console.log();
+        } else if (result.resolved.length > 0) {
+          console.log(pc.green(pc.bold(`🎉 Media resolution complete!`)));
+          console.log(pc.dim(`Attribution summary saved to ATTRIBUTIONS.md`));
+          console.log();
+        }
+      }
+    } catch (err) {
+      console.error(pc.red(`\n❌ Error: ${err.message}\n`));
+      process.exit(1);
+    }
+  });
+
+program
+  .command('compose-video')
+  .description('Mux a background image or video and audio file into an MP4 video using FFmpeg')
+  .requiredOption('--background <file>', 'Path to background media file (video or image)')
+  .requiredOption('--audio <file>', 'Path to audio file (wav, mp3, etc.)')
+  .requiredOption('--output <file>', 'Output destination path for final .mp4')
+  .option('--mode <video-loop|video-trim|ken-burns>', 'Composition mode (default: video-loop)', 'video-loop')
+  .option('--width <px>', 'Output video width (default: 1920)', '1920')
+  .option('--height <px>', 'Output video height (default: 1080)', '1080')
+  .option('--fps <n>', 'Frames per second (default: 30)', '30')
+  .option('-n, --dry-run', 'Print the FFmpeg composition plan without executing', false)
+  .option('-q, --quiet', 'Minimal output mode', false)
+  .action(async (options) => {
+    const isQuiet = options.quiet;
+
+    if (!isQuiet) {
+      console.log();
+      console.log(pc.bold(pc.cyan(`🎞️  Video Composer`)));
+      console.log(pc.dim(`──────────────────────────────────────────────────────────`));
+      console.log(`${pc.bold('🎬 Background :')} ${pc.white(path.resolve(options.background))}`);
+      console.log(`${pc.bold('🎵 Audio Track:')} ${pc.white(path.resolve(options.audio))}`);
+      console.log(`${pc.bold('📹 Output     :')} ${pc.white(path.resolve(options.output))}`);
+      console.log(`${pc.bold('⚙️  Mode       :')} ${pc.cyan(options.mode)}`);
+      console.log();
+    }
+
+    try {
+      const res = await composeVideo({
+        backgroundPath: path.resolve(options.background),
+        audioPath: path.resolve(options.audio),
+        outputPath: path.resolve(options.output),
+        mode: options.mode,
+        targetWidth: parseInt(options.width, 10) || 1920,
+        targetHeight: parseInt(options.height, 10) || 1080,
+        fps: parseInt(options.fps, 10) || 30,
+        dryRun: options.dryRun,
+      });
+
+      if (!isQuiet) {
+        if (options.dryRun) {
+          console.log(pc.yellow(`🔍 DRY RUN FFmpeg Plan:`));
+          console.log(`  ${res.command}`);
+          console.log();
+        } else {
+          console.log(pc.green(pc.bold(`🎉 Video successfully composed!`)));
+          console.log(`  • Output: ${pc.underline(pc.blue(res.outputPath))}`);
+          console.log(`  • Duration: ${res.duration?.toFixed(1)}s`);
+          console.log();
+        }
+      }
+    } catch (err) {
+      console.error(pc.red(`\n❌ Error: ${err.message}\n`));
+      process.exit(1);
+    }
+  });
+
+program
+  .command('apply-actions')
+  .description('Run configured video processing actions (shorten, replace-background, journey-overlay) on videos')
+  .argument('[directory]', 'Source folder containing metadata.json and video files (default: current directory)', '.')
+  .option('-d, --dir <path>', 'Explicit target directory path')
+  .option('-m, --metadata <file>', 'Custom path to metadata.json file')
+  .option('--actions-file <file>', 'Use a separate actions spec instead of reading actions from metadata.json')
+  .option('--output-suffix <suffix>', 'Suffix for the new output folder name')
+  .option('--output-dir <path>', 'Explicit output directory (overrides suffix-based naming)')
+  .option('--only <filename|songKey>', 'Restrict this run to a single entry')
+  .option('-f, --force', 'Re-run and overwrite an existing output for an entry', false)
+  .option('-n, --dry-run', 'Print the planned ffmpeg operations per entry, write nothing', false)
+  .option('--pexels-key <key>', 'Pexels API key')
+  .option('--pixabay-key <key>', 'Pixabay API key')
+  .option('--media-dir <path>', 'Override .media-cache directory location')
+  .option('-q, --quiet', 'Minimal output mode', false)
+  .action(async (directoryArg, options, command) => {
+    const parentOpts = command?.parent?.opts() || {};
+    const dryRun = Boolean(options.dryRun || parentOpts.dryRun);
+    const force = Boolean(options.force || parentOpts.force);
+    const metadata = options.metadata || parentOpts.metadata;
+    const targetDir = path.resolve(options.dir || parentOpts.dir || directoryArg || process.cwd());
+    const isQuiet = Boolean(options.quiet || parentOpts.quiet);
+
+    if (!isQuiet) {
+      console.log();
+      console.log(pc.bold(pc.cyan(`🎬 Video Actions Pipeline`)) + ` ${pc.dim(`v${pkg.version}`)}`);
+      console.log(pc.dim(`──────────────────────────────────────────────────────────`));
+      console.log(`${pc.bold('📂 Source Folder   :')} ${pc.white(targetDir)}`);
+      if (metadata) {
+        console.log(`${pc.bold('📄 Metadata File   :')} ${pc.white(path.resolve(metadata))}`);
+      }
+      if (options.actionsFile) {
+        console.log(`${pc.bold('📋 Actions Spec    :')} ${pc.white(path.resolve(options.actionsFile))}`);
+      }
+      if (options.outputDir) {
+        console.log(`${pc.bold('📁 Target Output   :')} ${pc.white(path.resolve(options.outputDir))}`);
+      }
+      if (options.outputSuffix) {
+        console.log(`${pc.bold('🏷️  Output Suffix   :')} ${pc.cyan(options.outputSuffix)}`);
+      }
+      if (options.only) {
+        console.log(`${pc.bold('🎯 Filter Entry    :')} ${pc.yellow(options.only)}`);
+      }
+      if (dryRun) {
+        console.log(`${pc.yellow(pc.bold('🔍 Mode            :'))} ${pc.yellow('DRY RUN (no file writes or transcoding)')}`);
+      }
+      if (force) {
+        console.log(`${pc.magenta(pc.bold('⚡ Force           :'))} ${pc.magenta('ENABLED (overwriting existing output files)')}`);
+      }
+      console.log();
+    }
+
+    try {
+      const result = await batchApplyActions(targetDir, {
+        metadataFile: metadata,
+        actionsFile: options.actionsFile,
+        outputDir: options.outputDir,
+        outputSuffix: options.outputSuffix,
+        only: options.only,
+        force,
+        dryRun,
+        pexelsKey: options.pexelsKey,
+        pixabayKey: options.pixabayKey,
+        cacheDir: options.mediaDir,
+        onEvent: (event) => {
+          if (isQuiet) return;
+
+          if (event.type === 'actions_plan') {
+            console.log(
+              pc.bold(`Found `) +
+              pc.green(pc.bold(`${event.total}`)) +
+              pc.bold(` item(s) to process.`)
+            );
+            console.log(`${pc.bold('📁 Output Directory:')} ${pc.cyan(event.outputDir)}`);
+            console.log();
+          } else if (event.type === 'entry_start') {
+            console.log(`  🎬 [${event.index + 1}/${event.total}] Processing ${pc.bold(event.songKey)} (${event.actionsCount} action(s))...`);
+          } else if (event.type === 'action_start') {
+            console.log(`     ⚙️  [Action ${event.actionIndex + 1}/${event.totalActions}] Running ${pc.cyan(event.actionType)}...`);
+          } else if (event.type === 'action_complete') {
+            console.log(pc.green(`     ✅ Action complete:`), pc.dim(event.actionType));
+          } else if (event.type === 'entry_success') {
+            if (dryRun && event.steps) {
+              for (const step of event.steps) {
+                console.log(`     ${pc.dim('↳')} ${step}`);
+              }
+            } else {
+              console.log(pc.green(`  ✅ Finished ${event.songKey} ->`), pc.dim(event.outputPath));
+            }
+            console.log();
+          } else if (event.type === 'entry_skipped') {
+            console.log(pc.dim(`  ⏭️  [SKIPPED] ${event.songKey} (${event.reason})`));
+            console.log();
+          } else if (event.type === 'entry_error') {
+            console.error(pc.red(`  ❌ Error on ${event.songKey}: ${event.error.message}`));
+            console.log();
+          } else if (event.type === 'action_warn') {
+            console.warn(pc.yellow(`     ⚠️  Warning: ${event.message}`));
+          } else if (event.type === 'metadata_cloned') {
+            console.log(pc.green(`  📄 Cloned and updated metadata to:`), pc.dim(event.outputPath));
+            console.log();
+          }
+        },
+      });
+
+      if (!isQuiet) {
+        console.log(pc.dim(`──────────────────────────────────────────────────────────`));
+        console.log(pc.bold(`📊 Actions Summary:`));
+        console.log(`  • Total items    : ${pc.bold(result.total)}`);
+        console.log(`  • Processed      : ${pc.green(pc.bold(result.processed.length))}`);
+        console.log(`  • Skipped        : ${pc.dim(result.skipped.length)}`);
+        if (result.failed.length > 0) {
+          console.log(`  • Failed         : ${pc.red(pc.bold(result.failed.length))}`);
+        }
+        console.log();
+
+        if (dryRun) {
+          console.log(pc.yellow(`✨ Dry run complete. No files were written or modified.`));
+          console.log();
+        } else if (result.failed.length > 0) {
+          console.log(pc.red(`⚠️  Completed with ${result.failed.length} failure(s).`));
+          process.exit(1);
+        } else {
+          console.log(pc.green(pc.bold(`🎉 All video actions successfully applied!`)));
+          console.log(`  • Output directory: ${pc.underline(pc.cyan(result.outputDir))}`);
+          console.log();
+        }
+      }
+    } catch (err) {
+      console.error(pc.red(`\n❌ Error: ${err.message}\n`));
+      process.exit(1);
+    }
+  });
+
+program
+  .command('preview-journey')
+  .description('Generate and preview the journey overlay graphic as a standalone PNG image')
+  .argument('<songKey>', 'Song key or filename to preview')
+  .option('-d, --dir <path>', 'Source folder containing metadata.json (default: current directory)')
+  .option('-m, --metadata <file>', 'Custom path to metadata.json file')
+  .option('--center-text <text>', 'Preview a specific center text without editing metadata.json')
+  .option('--concept-index <n>', 'Index of concept in centerConcepts to preview (default: 0)')
+  .option('-o, --output <file>', 'Output path for PNG file (default: ./journey-preview-<songKey>.png)')
+  .option('-q, --quiet', 'Minimal output mode', false)
+  .action(async (songKey, options) => {
+    const isQuiet = options.quiet;
+
+    if (!isQuiet) {
+      console.log();
+      console.log(pc.bold(pc.cyan(`🖼️  Journey Overlay Preview`)) + ` ${pc.dim(`v${pkg.version}`)}`);
+      console.log(pc.dim(`──────────────────────────────────────────────────────────`));
+      console.log(`${pc.bold('🎵 Song Key   :')} ${pc.white(songKey)}`);
+      if (options.centerText) {
+        console.log(`${pc.bold('💬 Center Text:')} ${pc.green(JSON.stringify(options.centerText))}`);
+      }
+      if (options.conceptIndex !== undefined) {
+        console.log(`${pc.bold('🔢 Concept Idx:')} ${pc.cyan(options.conceptIndex)}`);
+      }
+      console.log();
+    }
+
+    try {
+      const res = await previewJourney(songKey, {
+        dir: options.dir,
+        metadata: options.metadata,
+        centerText: options.centerText,
+        conceptIndex: options.conceptIndex,
+        output: options.output,
+      });
+
+      if (!isQuiet) {
+        console.log(pc.green(pc.bold(`🎉 Preview generated!`)));
+        console.log(`  • File      : ${pc.underline(pc.blue(res.outputPath))}`);
+        console.log(`  • Resolution: ${res.width}x${res.height}`);
+        console.log(`  • Tracks    : ${res.tracksCount}`);
+        console.log();
+      }
+    } catch (err) {
+      console.error(pc.red(`\n❌ Error: ${err.message}\n`));
+      process.exit(1);
+    }
+  });
+
 program.parse(process.argv);
+