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

package/README.md

@@ -144,6 +144,32 @@ npx @x12i/youtube-video-uploader-cli ./my-videos --client-secrets-file ./client_
 
 ---
 
+## 🔁 Replacing a Video in a Playlist (`swap`)
+
+Re-uploads a song (e.g. a new version with lyrics subtitles) and swaps it into a playlist in place of the old video. The old video is **unlisted, never deleted**, so existing direct links keep working.
+
+```bash
+yt-uploader swap ./song-v2.mp4 --playlist PLxxxx --old-video VIDEOID
+yt-uploader swap ./song-v2.mp4 --playlist PLxxxx --old-video VIDEOID --dry-run
+```
+
+The swap runs as a resumable five-step state machine (state persisted to `.swap-history.json` after every step):
+
+1. **UPLOAD** — upload the new video *unlisted* (metadata carried over from the old video)
+2. **LOCATE** — find the old video's playlist item + position
+3. **INSERT** — insert the new video at the old position
+4. **REMOVE** — remove the old playlist item
+5. **FINALIZE** — old video → unlisted, new video → public
+
+If any step fails, re-run the same command — completed steps are skipped automatically (no duplicate uploads or playlist entries). A missing old video aborts with a "needs manual review" flag instead of guessing.
+
+**Quota cost:** ~150 shared-pool units + 1 upload-bucket unit per swap (well within the 10,000/day default pool).
+
+**Notes:**
+- OAuth scopes are now `youtube.upload` + `youtube.force-ssl` (narrower than before) — existing `token.json` files need a one-time re-consent.
+- The target playlist must use **Manual** ordering for position-preserving inserts (set in YouTube Studio).
+- Videos from an unverified Google Cloud project are forced private until the project passes YouTube's API audit.
+
 ## 🛠️ Programmatic Node.js API
 
 ```javascript

package/bin/cli.js

@@ -4,7 +4,9 @@ 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 } from '../src/index.js';
+import { authenticate } from '../src/auth.js';
 
 // Read package.json for version
 const pkgPath = new URL('../package.json', import.meta.url);
@@ -21,6 +23,9 @@ program
   .option('-m, --metadata <file>', 'Custom path to metadata.json file')
   .option('-f, --force', 'Force re-upload of already uploaded videos', false)
   .option('-n, --dry-run', 'Preview video uploads and estimate quota without uploading', false)
+  .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('--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')
@@ -38,6 +43,12 @@ program
       if (options.metadata) {
         console.log(`${pc.bold('📄 Metadata File   :')} ${pc.white(path.resolve(options.metadata))}`);
       }
+      if (options.limit) {
+        console.log(`${pc.bold('🎯 Batch Limit     :')} ${pc.cyan(`${options.limit} videos max`)}`);
+      }
+      if (options.safeQuota) {
+        console.log(`${pc.bold('🛡️  Safe Quota Mode :')} ${pc.green('ENABLED (capped under daily 10,000 units)')}`);
+      }
       if (options.dryRun) {
         console.log(`${pc.yellow(pc.bold('🔍 Mode            :'))} ${pc.yellow('DRY RUN (no uploads will be made)')}`);
       }
@@ -56,6 +67,9 @@ program
         metadataFile: options.metadata,
         force: options.force,
         dryRun: options.dryRun,
+        limit: options.limit ? parseInt(options.limit, 10) : undefined,
+        safeQuota: options.safeQuota,
+        maxQuota: options.maxQuota ? parseInt(options.maxQuota, 10) : undefined,
         tokenFile,
         clientSecretsFile: options.clientSecretsFile,
         clientId: options.clientId,
@@ -68,18 +82,21 @@ program
               pc.bold(`Found `) +
               pc.green(pc.bold(`${event.total}`)) +
               pc.bold(` item(s): `) +
-              pc.cyan(`${event.toProcess.length} to upload`) +
+              pc.cyan(`${event.toProcess.length} to upload now`) +
+              (event.deferred?.length ? `, ` + pc.yellow(`${event.deferred.length} deferred`) : '') +
               `, ` +
               pc.dim(`${event.skipped.length} skipped`)
             );
 
             if (event.playlistId) {
-              console.log(pc.dim(`Playlist ID: ${event.playlistId}`));
+              console.log(pc.dim(`Playlist ID        : ${event.playlistId}`));
+            } else if (event.needsPlaylistCreation) {
+              console.log(pc.cyan(`Playlist Creation  : "${event.playlist.snippet?.title}"`));
             }
 
             console.log(
               pc.bold(`Estimated API Quota: `) +
-              (event.estimatedQuota > DAILY_DEFAULT_QUOTA ? pc.red(pc.bold(`${event.estimatedQuota} units`)) : pc.cyan(`${event.estimatedQuota} units`)) +
+              (event.estimatedQuota > DAILY_DEFAULT_QUOTA ? pc.red(pc.bold(`${event.estimatedQuota} units`)) : pc.green(pc.bold(`${event.estimatedQuota} units`))) +
               pc.dim(` / ${DAILY_DEFAULT_QUOTA} daily default units`)
             );
 
@@ -88,12 +105,27 @@ program
             }
             console.log();
 
+            if (event.deferred?.length > 0) {
+              for (const d of event.deferred) {
+                console.log(`  ${pc.yellow('⏳ [DEFERRED]')} ${pc.dim(d.filename)} ${pc.dim(`(${d.reason})`)}`);
+              }
+              console.log();
+            }
+
             if (event.skipped.length > 0) {
               for (const s of event.skipped) {
-                console.log(`  ${pc.dim('⏭️  [SKIPPED]')} ${pc.dim(s.filename)} ${pc.dim(`(${s.reason})`)}`);
+                console.log(`  ${pc.dim('⏭️  [SKIPPED] ')} ${pc.dim(s.filename)} ${pc.dim(`(${s.reason})`)}`);
               }
               console.log();
             }
+          } else if (event.type === 'authenticated_channel') {
+            console.log(pc.green(`👤 Authenticated Channel: `) + pc.bold(event.channel.title) + pc.dim(` (${event.channel.customUrl || event.channel.id})`));
+            console.log();
+          } else if (event.type === 'playlist_create_start') {
+            console.log(`  ${pc.cyan('📑')} Creating playlist: ${pc.bold(event.playlist.snippet?.title)}...`);
+          } else if (event.type === 'playlist_create_success') {
+            console.log(pc.green(`     ✅ Playlist created! URL: `) + pc.underline(pc.blue(event.url)));
+            console.log();
           } else if (event.type === 'upload_start') {
             process.stdout.write(`  ${pc.cyan('⬆️ ')} [${event.index + 1}/${event.total}] Uploading ${pc.bold(event.item.filename)} ("${event.item.title}")... `);
           } else if (event.type === 'upload_success') {
@@ -124,6 +156,9 @@ program
         console.log(`  • Total items    : ${pc.bold(result.total)}`);
         console.log(`  • Uploaded       : ${pc.green(pc.bold(result.uploaded.length))}`);
         console.log(`  • Skipped        : ${pc.dim(result.skipped.length)}`);
+        if (result.deferred?.length > 0) {
+          console.log(`  • Deferred       : ${pc.yellow(pc.bold(result.deferred.length))} ${pc.dim('(run again tomorrow for the next batch)')}`);
+        }
         if (result.failed.length > 0) {
           console.log(`  • Failed         : ${pc.red(pc.bold(result.failed.length))}`);
         }
@@ -132,6 +167,10 @@ program
         if (result.failed.length > 0) {
           console.log(pc.red(`⚠️  Batch completed with ${result.failed.length} failure(s).`));
           process.exit(1);
+        } else if (result.deferred?.length > 0) {
+          console.log(pc.green(pc.bold(`🎉 Batch completed! ${result.uploaded.length} videos uploaded today.`)));
+          console.log(pc.cyan(`👉 Run the exact same command tomorrow to upload the remaining ${result.deferred.length} videos.`));
+          console.log();
         } else if (result.uploaded.length > 0) {
           console.log(pc.green(pc.bold(`🎉 All videos successfully uploaded to YouTube!`)));
           console.log();
@@ -146,4 +185,117 @@ 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.parse(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/youtube-video-uploader-cli",
-  "version": "1.0.0",
+  "version": "1.2.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/auth.js

@@ -8,18 +8,55 @@ import pc from 'picocolors';
 
 export const YOUTUBE_SCOPES = [
   'https://www.googleapis.com/auth/youtube.upload',
-  'https://www.googleapis.com/auth/youtube',
+  'https://www.googleapis.com/auth/youtube.force-ssl',
 ];
 
 export const DEFAULT_REDIRECT_URI = 'http://localhost:3000/oauth2callback';
 export const DEFAULT_TOKEN_FILENAME = 'token.json';
 
+/**
+ * Load .env file into process.env if present in current or parent directories.
+ */
+export function loadDotEnv() {
+  let curr = process.cwd();
+  for (let i = 0; i < 5; i++) {
+    const envPath = path.join(curr, '.env');
+    if (fs.existsSync(envPath)) {
+      try {
+        const lines = fs.readFileSync(envPath, 'utf-8').split('\n');
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed || trimmed.startsWith('#')) continue;
+          const eqIdx = trimmed.indexOf('=');
+          if (eqIdx !== -1) {
+            const key = trimmed.slice(0, eqIdx).trim();
+            let val = trimmed.slice(eqIdx + 1).trim();
+            if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+              val = val.slice(1, -1);
+            }
+            if (!process.env[key]) {
+              process.env[key] = val;
+            }
+          }
+        }
+        break;
+      } catch {
+        // Ignore read errors
+      }
+    }
+    const parent = path.dirname(curr);
+    if (parent === curr) break;
+    curr = parent;
+  }
+}
+
 /**
  * Extract Client ID and Client Secret from file or environment.
  * @param {object} options
  * @returns {{ clientId: string, clientSecret: string, redirectUri: string }}
  */
 export function resolveOAuthCredentials(options = {}) {
+  loadDotEnv();
   let clientId = options.clientId || process.env.YOUTUBE_CLIENT_ID || process.env.GOOGLE_CLIENT_ID;
   let clientSecret = options.clientSecret || process.env.YOUTUBE_CLIENT_SECRET || process.env.GOOGLE_CLIENT_SECRET;
   const redirectUri = options.redirectUri || DEFAULT_REDIRECT_URI;

package/src/index.d.ts

@@ -81,3 +81,76 @@ export const DAILY_DEFAULT_QUOTA: number;
 export const DEFAULT_CATEGORY_ID: string;
 export const DEFAULT_PRIVACY_STATUS: string;
 export const VALID_PRIVACY_STATUSES: Set<string>;
+
+// ─── Playlist video swap ───────────────────────────────────────────────────
+
+export type SwapStatus =
+  | 'pending'
+  | 'uploaded'
+  | 'located'
+  | 'inserted'
+  | 'removed'
+  | 'finalized'
+  | 'failed';
+
+export interface SwapRecord {
+  songKey: string;
+  oldVideoId: string;
+  playlistId: string;
+  newVideoPath?: string;
+  newVideoId?: string;
+  oldPlaylistItemId?: string;
+  oldPosition?: number;
+  newPlaylistItemId?: string;
+  status: SwapStatus;
+  lastError?: string;
+  updatedAt?: string;
+}
+
+export class SwapStore {
+  constructor(targetFolder?: string, stateFilename?: string);
+  getRecord(songKey: string): SwapRecord | null;
+  initRecord(record: { songKey: string; playlistId: string; oldVideoId: string; newVideoPath?: string }): SwapRecord;
+  updateRecord(songKey: string, fields: Partial<SwapRecord>): SwapRecord;
+  listRecords(status?: SwapStatus): SwapRecord[];
+}
+
+export function uploadNewVideo(
+  youtube: youtube_v3.Youtube,
+  newVideoPath: string,
+  opts?: { oldVideoId?: string; meta?: VideoMetadata; retries?: number }
+): Promise<{ videoId: string; url: string }>;
+
+export function findPlaylistItem(
+  youtube: youtube_v3.Youtube,
+  playlistId: string,
+  oldVideoId: string
+): Promise<{ playlistItemId: string; position: number } | null>;
+
+export function insertAtPosition(
+  youtube: youtube_v3.Youtube,
+  playlistId: string,
+  newVideoId: string,
+  position: number
+): Promise<{ newPlaylistItemId: string }>;
+
+export function removeOldItem(youtube: youtube_v3.Youtube, oldPlaylistItemId: string): Promise<void>;
+
+export function finalizeSwap(youtube: youtube_v3.Youtube, oldVideoId: string, newVideoId: string): Promise<void>;
+
+export function swapSong(params: {
+  youtube: youtube_v3.Youtube;
+  songKey: string;
+  newVideoPath: string;
+  playlistId: string;
+  oldVideoId: string;
+  meta?: VideoMetadata;
+  stateDir?: string;
+  stateFile?: string;
+  fresh?: boolean;
+  onEvent?: (event: { type: string; [key: string]: any }) => void;
+}): Promise<{ record: SwapRecord }>;
+
+export const QUOTA_PER_SWAP: number;
+export const DEFAULT_SWAP_STATE_FILENAME: string;
+export const SWAP_STATUSES: string[];

package/src/index.js

@@ -9,3 +9,12 @@ export {
   QUOTA_PER_PLAYLIST_ITEM,
   DAILY_DEFAULT_QUOTA,
 } from './uploader.js';
+export { SwapStore, DEFAULT_SWAP_STATE_FILENAME, SWAP_STATUSES } from './swap/store.js';
+export {
+  uploadNewVideo,
+  findPlaylistItem,
+  insertAtPosition,
+  removeOldItem,
+  finalizeSwap,
+} from './swap/steps.js';
+export { swapSong, QUOTA_PER_SWAP } from './swap/swapSong.js';

package/src/metadata.js

@@ -8,13 +8,29 @@ export const VALID_PRIVACY_STATUSES = new Set(['private', 'unlisted', 'public'])
 export const DEFAULT_CATEGORY_ID = '10'; // Music
 export const DEFAULT_PRIVACY_STATUS = 'private';
 
+export function interpolateTemplates(text, variables = {}) {
+  if (!text || typeof text !== 'string') return text;
+  return text.replace(/\{\{([^}]+)\}\}/g, (match, key) => {
+    const trimmed = key.trim();
+    return variables[trimmed] !== undefined && variables[trimmed] !== null ? variables[trimmed] : match;
+  });
+}
+
 /**
  * Load, validate, and normalize metadata for batch video uploading.
+ * Supports both the flat videos array format and the rich album/playlist/songs schema.
  * 
  * @param {string} targetFolder - Path to folder containing videos
  * @param {string} [customMetadataPath] - Optional custom path to metadata.json
  * @returns {{
  *   playlistId: string | null,
+ *   playlist?: {
+ *     key?: string,
+ *     snippet?: object,
+ *     status?: object,
+ *     publishStatusAfterQc?: string
+ *   },
+ *   templateVariables: Record<string, string | null>,
  *   privacyStatus: 'private' | 'unlisted' | 'public',
  *   categoryId: string,
  *   videos: Array<{
@@ -24,6 +40,8 @@ export const DEFAULT_PRIVACY_STATUS = 'private';
  *     tags: string[],
  *     categoryId?: string,
  *     privacyStatus?: 'private' | 'unlisted' | 'public',
+ *     trackNumber?: number,
+ *     playlistPosition?: number,
  *     filePath: string
  *   }>
  * }}
@@ -52,14 +70,101 @@ export function loadMetadata(targetFolder, customMetadataPath) {
 
   const defaultPrivacy = VALID_PRIVACY_STATUSES.has(rawConfig.privacyStatus)
     ? rawConfig.privacyStatus
-    : DEFAULT_PRIVACY_STATUS;
+    : (rawConfig.uploadPolicy?.initialVideoPrivacyStatus && VALID_PRIVACY_STATUSES.has(rawConfig.uploadPolicy.initialVideoPrivacyStatus)
+        ? rawConfig.uploadPolicy.initialVideoPrivacyStatus
+        : DEFAULT_PRIVACY_STATUS);
+
+  const defaultCategory = String(
+    rawConfig.categoryId || rawConfig.uploadPolicy?.categoryId || DEFAULT_CATEGORY_ID
+  );
+
+  const templateVariables = {
+    channelUrl: rawConfig.templateVariables?.channelUrl || rawConfig.channel?.channelUrl || null,
+    playlistUrl: rawConfig.templateVariables?.playlistUrl || null,
+    ...(rawConfig.templateVariables || {}),
+  };
+
+  let playlistId = rawConfig.playlistId ? String(rawConfig.playlistId).trim() : null;
+  let playlist = null;
+
+  if (rawConfig.playlist) {
+    playlist = {
+      key: rawConfig.playlist.key || 'default_playlist',
+      snippet: rawConfig.playlist.youtube?.snippet || rawConfig.playlist.snippet || null,
+      status: rawConfig.playlist.youtube?.status || rawConfig.playlist.status || { privacyStatus: defaultPrivacy },
+      publishStatusAfterQc: rawConfig.playlist.publishStatusAfterQc,
+    };
+    if (rawConfig.playlist.playlistId) {
+      playlistId = String(rawConfig.playlist.playlistId).trim();
+    }
+  }
+
+  let rawVideos = [];
 
-  const defaultCategory = String(rawConfig.categoryId || DEFAULT_CATEGORY_ID);
-  const playlistId = rawConfig.playlistId ? String(rawConfig.playlistId).trim() : null;
+  if (rawConfig.songs && typeof rawConfig.songs === 'object' && !Array.isArray(rawConfig.songs)) {
+    const orderedKeys = Array.isArray(rawConfig.playlist?.orderedSongKeys)
+      ? rawConfig.playlist.orderedSongKeys
+      : Object.keys(rawConfig.songs);
 
-  let rawVideos = Array.isArray(rawConfig.videos) ? rawConfig.videos : [];
+    const seen = new Set();
+
+    for (const songKey of orderedKeys) {
+      const songData = rawConfig.songs[songKey];
+      if (songData) {
+        seen.add(songKey);
+        const snippet = songData.youtube?.snippet || {};
+        const status = songData.youtube?.status || {};
+        const insertOptions = songData.youtube?.insertOptions || {};
+        rawVideos.push({
+          filename: songKey,
+          title: snippet.title || path.basename(songKey, path.extname(songKey)),
+          description: snippet.description || '',
+          tags: snippet.tags || [],
+          categoryId: snippet.categoryId || rawConfig.uploadPolicy?.categoryId || defaultCategory,
+          privacyStatus: status.privacyStatus || rawConfig.uploadPolicy?.initialVideoPrivacyStatus || defaultPrivacy,
+          defaultLanguage: snippet.defaultLanguage || rawConfig.uploadPolicy?.defaultLanguage || 'en',
+          defaultAudioLanguage: snippet.defaultAudioLanguage || rawConfig.uploadPolicy?.defaultAudioLanguage || 'en',
+          license: status.license || rawConfig.uploadPolicy?.license || 'youtube',
+          embeddable: status.embeddable !== undefined ? status.embeddable : true,
+          publicStatsViewable: status.publicStatsViewable !== undefined ? status.publicStatsViewable : true,
+          selfDeclaredMadeForKids: status.selfDeclaredMadeForKids !== undefined ? status.selfDeclaredMadeForKids : (rawConfig.uploadPolicy?.selfDeclaredMadeForKids ?? false),
+          notifySubscribers: insertOptions.notifySubscribers !== undefined ? insertOptions.notifySubscribers : (rawConfig.uploadPolicy?.notifySubscribersOnInitialUpload ?? false),
+          trackNumber: songData.trackNumber,
+          playlistPosition: songData.playlistPosition !== undefined ? songData.playlistPosition : songData.playlistItem?.position,
+        });
+      }
+    }
 
-  // If no videos array was provided in metadata.json, auto-discover all .mp4 files in the folder
+    // Add any remaining songs not in orderedSongKeys
+    for (const [songKey, songData] of Object.entries(rawConfig.songs)) {
+      if (!seen.has(songKey)) {
+        const snippet = songData.youtube?.snippet || {};
+        const status = songData.youtube?.status || {};
+        const insertOptions = songData.youtube?.insertOptions || {};
+        rawVideos.push({
+          filename: songKey,
+          title: snippet.title || path.basename(songKey, path.extname(songKey)),
+          description: snippet.description || '',
+          tags: snippet.tags || [],
+          categoryId: snippet.categoryId || rawConfig.uploadPolicy?.categoryId || defaultCategory,
+          privacyStatus: status.privacyStatus || rawConfig.uploadPolicy?.initialVideoPrivacyStatus || defaultPrivacy,
+          defaultLanguage: snippet.defaultLanguage || rawConfig.uploadPolicy?.defaultLanguage || 'en',
+          defaultAudioLanguage: snippet.defaultAudioLanguage || rawConfig.uploadPolicy?.defaultAudioLanguage || 'en',
+          license: status.license || rawConfig.uploadPolicy?.license || 'youtube',
+          embeddable: status.embeddable !== undefined ? status.embeddable : true,
+          publicStatsViewable: status.publicStatsViewable !== undefined ? status.publicStatsViewable : true,
+          selfDeclaredMadeForKids: status.selfDeclaredMadeForKids !== undefined ? status.selfDeclaredMadeForKids : (rawConfig.uploadPolicy?.selfDeclaredMadeForKids ?? false),
+          notifySubscribers: insertOptions.notifySubscribers !== undefined ? insertOptions.notifySubscribers : (rawConfig.uploadPolicy?.notifySubscribersOnInitialUpload ?? false),
+          trackNumber: songData.trackNumber,
+          playlistPosition: songData.playlistPosition !== undefined ? songData.playlistPosition : songData.playlistItem?.position,
+        });
+      }
+    }
+  } else if (Array.isArray(rawConfig.videos)) {
+    rawVideos = rawConfig.videos;
+  }
+
+  // If no videos were defined, auto-discover all .mp4 files in the folder
   if (rawVideos.length === 0 && fs.existsSync(resolvedFolder)) {
     const files = fs.readdirSync(resolvedFolder);
     const mp4Files = files.filter(f => f.toLowerCase().endsWith('.mp4') && !f.startsWith('.'));
@@ -73,13 +178,13 @@ export function loadMetadata(targetFolder, customMetadataPath) {
 
   const videos = rawVideos.map((item, index) => {
     if (!item.filename) {
-      throw new Error(`Video at index ${index} in metadata.json is missing required "filename" property.`);
+      throw new Error(`Video at index ${index} in metadata is missing required "filename" property.`);
     }
 
     const filename = String(item.filename);
     const filePath = path.isAbsolute(filename) ? filename : path.join(resolvedFolder, filename);
-    const title = item.title ? String(item.title) : path.basename(filename, path.extname(filename));
-    const description = item.description ? String(item.description) : '';
+    const rawTitle = item.title ? String(item.title) : path.basename(filename, path.extname(filename));
+    const rawDescription = item.description ? String(item.description) : '';
     const tags = Array.isArray(item.tags) ? item.tags.map(t => String(t).trim()).filter(Boolean) : [];
 
     const privacyStatus = item.privacyStatus && VALID_PRIVACY_STATUSES.has(item.privacyStatus)
@@ -88,6 +193,10 @@ export function loadMetadata(targetFolder, customMetadataPath) {
 
     const categoryId = item.categoryId ? String(item.categoryId) : defaultCategory;
 
+    // Apply template interpolation for known variables
+    const title = interpolateTemplates(rawTitle, templateVariables);
+    const description = interpolateTemplates(rawDescription, templateVariables);
+
     return {
       filename,
       filePath,
@@ -96,11 +205,22 @@ export function loadMetadata(targetFolder, customMetadataPath) {
       tags,
       categoryId,
       privacyStatus,
+      defaultLanguage: item.defaultLanguage || 'en',
+      defaultAudioLanguage: item.defaultAudioLanguage || 'en',
+      license: item.license || 'youtube',
+      embeddable: item.embeddable !== undefined ? item.embeddable : true,
+      publicStatsViewable: item.publicStatsViewable !== undefined ? item.publicStatsViewable : true,
+      selfDeclaredMadeForKids: item.selfDeclaredMadeForKids !== undefined ? item.selfDeclaredMadeForKids : false,
+      notifySubscribers: item.notifySubscribers !== undefined ? item.notifySubscribers : false,
+      trackNumber: item.trackNumber,
+      playlistPosition: item.playlistPosition,
     };
   });
 
   return {
     playlistId,
+    playlist,
+    templateVariables,
     privacyStatus: defaultPrivacy,
     categoryId: defaultCategory,
     videos,

package/src/state.js

@@ -63,6 +63,45 @@ export class UploadState {
     this.save();
   }
 
+  /**
+   * Check if a playlist has already been created.
+   * @param {string} [key='default']
+   * @returns {{ playlistId: string, url: string, createdAt: string } | null}
+   */
+  getPlaylist(key = 'default') {
+    if (this.data.playlists && this.data.playlists[key]) {
+      return this.data.playlists[key];
+    }
+    if (this.data.playlistId) {
+      return {
+        playlistId: this.data.playlistId,
+        url: `https://www.youtube.com/playlist?list=${this.data.playlistId}`,
+        createdAt: this.data.playlistCreatedAt || null,
+      };
+    }
+    return null;
+  }
+
+  /**
+   * Record a created playlist.
+   * @param {string} key 
+   * @param {string} playlistId 
+   * @param {string} [url] 
+   */
+  recordPlaylistInfo(key, playlistId, url) {
+    if (!this.data.playlists) {
+      this.data.playlists = {};
+    }
+    const resolvedUrl = url || `https://www.youtube.com/playlist?list=${playlistId}`;
+    this.data.playlists[key] = {
+      playlistId,
+      url: resolvedUrl,
+      createdAt: new Date().toISOString(),
+    };
+    this.data.playlistId = playlistId;
+    this.save();
+  }
+
   /**
    * Record playlist association.
    * @param {string} filename