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

package/bin/cli.js

@@ -21,6 +21,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 +41,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 +65,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 +80,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 +103,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 +154,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 +165,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();

package/package.json

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

@@ -14,12 +14,49 @@ export const YOUTUBE_SCOPES = [
 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/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 

package/src/uploader.js

@@ -7,8 +7,36 @@ import { authenticate } from './auth.js';
 
 export const QUOTA_PER_VIDEO_UPLOAD = 1600;
 export const QUOTA_PER_PLAYLIST_ITEM = 50;
+export const QUOTA_PER_PLAYLIST_CREATE = 50;
 export const DAILY_DEFAULT_QUOTA = 10000;
 
+import { interpolateTemplates } from './metadata.js';
+
+/**
+ * Create a YouTube Playlist.
+ * 
+ * @param {import('googleapis').youtube_v3.Youtube} youtube
+ * @param {object} snippet
+ * @param {object} [status={ privacyStatus: 'private' }]
+ * @returns {Promise<{ playlistId: string, url: string, data: any }>}
+ */
+export async function createPlaylist(youtube, snippet, status = { privacyStatus: 'private' }) {
+  const res = await youtube.playlists.insert({
+    part: ['snippet', 'status'],
+    requestBody: {
+      snippet,
+      status,
+    },
+  });
+
+  const playlistId = res.data.id;
+  return {
+    playlistId,
+    url: `https://www.youtube.com/playlist?list=${playlistId}`,
+    data: res.data,
+  };
+}
+
 /**
  * Upload a single video file to YouTube via YouTube Data API v3.
  * 
@@ -29,23 +57,37 @@ export async function uploadVideo(youtube, filePath, meta, defaultPrivacy = 'pri
     throw new Error(`Video file is empty (0 bytes): ${filePath}`);
   }
 
-  const res = await youtube.videos.insert({
+  const snippet = {
+    title: meta.title,
+    description: meta.description || '',
+    tags: meta.tags || [],
+    categoryId: String(meta.categoryId || defaultCategory || '10'),
+  };
+
+  if (meta.defaultLanguage) snippet.defaultLanguage = meta.defaultLanguage;
+  if (meta.defaultAudioLanguage) snippet.defaultAudioLanguage = meta.defaultAudioLanguage;
+
+  const status = {
+    privacyStatus: meta.privacyStatus || defaultPrivacy || 'private',
+    license: meta.license || 'youtube',
+    embeddable: meta.embeddable !== undefined ? meta.embeddable : true,
+    publicStatsViewable: meta.publicStatsViewable !== undefined ? meta.publicStatsViewable : true,
+    selfDeclaredMadeForKids: meta.selfDeclaredMadeForKids !== undefined ? meta.selfDeclaredMadeForKids : false,
+  };
+
+  const insertParams = {
     part: ['snippet', 'status'],
+    notifySubscribers: meta.notifySubscribers !== undefined ? meta.notifySubscribers : false,
     requestBody: {
-      snippet: {
-        title: meta.title,
-        description: meta.description || '',
-        tags: meta.tags || [],
-        categoryId: meta.categoryId || defaultCategory || '10',
-      },
-      status: {
-        privacyStatus: meta.privacyStatus || defaultPrivacy || 'private',
-      },
+      snippet,
+      status,
     },
     media: {
       body: fs.createReadStream(filePath),
     },
-  });
+  };
+
+  const res = await youtube.videos.insert(insertParams);
 
   const videoId = res.data.id;
   return {
@@ -60,19 +102,25 @@ export async function uploadVideo(youtube, filePath, meta, defaultPrivacy = 'pri
  * @param {import('googleapis').youtube_v3.Youtube} youtube
  * @param {string} playlistId
  * @param {string} videoId
+ * @param {number} [position]
  * @returns {Promise<any>}
  */
-export async function addToPlaylist(youtube, playlistId, videoId) {
+export async function addToPlaylist(youtube, playlistId, videoId, position) {
+  const snippet = {
+    playlistId,
+    resourceId: {
+      kind: 'youtube#video',
+      videoId,
+    },
+  };
+  if (typeof position === 'number') {
+    snippet.position = position;
+  }
+
   const res = await youtube.playlistItems.insert({
     part: ['snippet'],
     requestBody: {
-      snippet: {
-        playlistId,
-        resourceId: {
-          kind: 'youtube#video',
-          videoId,
-        },
-      },
+      snippet,
     },
   });
   return res.data;
@@ -95,7 +143,8 @@ export async function addToPlaylist(youtube, playlistId, videoId) {
  *   uploaded: Array<{ filename: string, videoId: string, url: string, addedToPlaylist: boolean }>,
  *   skipped: Array<{ filename: string, videoId?: string, reason: string }>,
  *   failed: Array<{ filename: string, error: Error }>,
- *   estimatedQuota: number
+ *   estimatedQuota: number,
+ *   playlistId?: string | null
  * }>}
  */
 export async function batchUpload(targetFolder, options = {}) {
@@ -107,7 +156,11 @@ export async function batchUpload(targetFolder, options = {}) {
   const config = loadMetadata(resolvedFolder, options.metadataFile);
   const state = new UploadState(resolvedFolder);
 
-  const playlistId = config.playlistId;
+  const playlistKey = config.playlist?.key || 'default';
+  const cachedPlaylist = state.getPlaylist(playlistKey);
+  let playlistId = config.playlistId || cachedPlaylist?.playlistId || null;
+  const needsPlaylistCreation = !playlistId && Boolean(config.playlist?.snippet);
+
   const toProcess = [];
   const skipped = [];
 
@@ -132,16 +185,53 @@ export async function batchUpload(targetFolder, options = {}) {
     }
   }
 
-  const estimatedQuota = (toProcess.length * QUOTA_PER_VIDEO_UPLOAD) +
-    (playlistId ? toProcess.length * QUOTA_PER_PLAYLIST_ITEM : 0);
+  const willHavePlaylist = Boolean(playlistId || needsPlaylistCreation);
+  const baseQuota = needsPlaylistCreation ? QUOTA_PER_PLAYLIST_CREATE : 0;
+  const costPerVideo = QUOTA_PER_VIDEO_UPLOAD + (willHavePlaylist ? QUOTA_PER_PLAYLIST_ITEM : 0);
+
+  let limit = Infinity;
+  if (options.limit !== undefined && options.limit !== null && !isNaN(options.limit)) {
+    limit = Math.max(0, parseInt(options.limit, 10));
+  }
+
+  let maxQuota = Infinity;
+  if (options.maxQuota !== undefined && options.maxQuota !== null && !isNaN(options.maxQuota)) {
+    maxQuota = parseInt(options.maxQuota, 10);
+  } else if (options.safeQuota) {
+    maxQuota = DAILY_DEFAULT_QUOTA - 50; // 9,950 units safe limit
+  }
+
+  const activeToProcess = [];
+  const deferred = [];
+
+  for (const item of toProcess) {
+    const candidateQuota = baseQuota + ((activeToProcess.length + 1) * costPerVideo);
+    if (activeToProcess.length < limit && candidateQuota <= maxQuota) {
+      activeToProcess.push(item);
+    } else {
+      deferred.push({
+        filename: item.filename,
+        reason: activeToProcess.length >= limit
+          ? `Deferred by upload limit (${limit})`
+          : `Deferred for next batch to stay under quota limit (${maxQuota} units)`,
+      });
+    }
+  }
+
+  const estimatedQuota = baseQuota + (activeToProcess.length * costPerVideo);
 
   onEvent({
     type: 'plan',
     total: config.videos.length,
-    toProcess,
+    toProcess: activeToProcess,
     skipped,
+    deferred,
     estimatedQuota,
     playlistId,
+    needsPlaylistCreation,
+    playlist: config.playlist,
+    safeQuota: Boolean(options.safeQuota),
+    limit: isFinite(limit) ? limit : null,
   });
 
   if (dryRun) {
@@ -150,19 +240,23 @@ export async function batchUpload(targetFolder, options = {}) {
       total: config.videos.length,
       uploaded: [],
       skipped,
+      deferred,
       failed: [],
       estimatedQuota,
+      playlistId,
     };
   }
 
-  if (toProcess.length === 0) {
+  if (activeToProcess.length === 0 && !needsPlaylistCreation) {
     return {
       targetFolder: resolvedFolder,
       total: config.videos.length,
       uploaded: [],
       skipped,
+      deferred,
       failed: [],
       estimatedQuota: 0,
+      playlistId,
     };
   }
 
@@ -176,12 +270,61 @@ export async function batchUpload(targetFolder, options = {}) {
 
   const youtube = google.youtube({ version: 'v3', auth });
 
+  // Verify and display authenticated channel identity
+  try {
+    const channelRes = await youtube.channels.list({
+      part: ['snippet'],
+      mine: true,
+    });
+    if (channelRes.data.items && channelRes.data.items.length > 0) {
+      const ch = channelRes.data.items[0];
+      const channelInfo = {
+        id: ch.id,
+        title: ch.snippet?.title || 'Unknown',
+        customUrl: ch.snippet?.customUrl || null,
+      };
+      onEvent({ type: 'authenticated_channel', channel: channelInfo });
+    }
+  } catch {
+    // Non-fatal
+  }
+
+  // Create playlist if needed
+  if (needsPlaylistCreation && config.playlist?.snippet) {
+    onEvent({ type: 'playlist_create_start', playlist: config.playlist });
+    try {
+      const created = await createPlaylist(
+        youtube,
+        config.playlist.snippet,
+        config.playlist.status || { privacyStatus: config.privacyStatus }
+      );
+      playlistId = created.playlistId;
+      state.recordPlaylistInfo(playlistKey, created.playlistId, created.url);
+      onEvent({ type: 'playlist_create_success', playlistId, url: created.url });
+    } catch (err) {
+      onEvent({ type: 'playlist_create_error', error: err });
+      throw new Error(`Failed to create YouTube Playlist: ${err.message}`);
+    }
+  }
+
+  // Apply playlistUrl template interpolation to pending video items
+  const playlistUrl = playlistId ? `https://www.youtube.com/playlist?list=${playlistId}` : '';
+  const finalTemplateVars = {
+    ...config.templateVariables,
+    playlistUrl: playlistUrl || config.templateVariables.playlistUrl || '',
+  };
+
+  for (const item of activeToProcess) {
+    item.title = interpolateTemplates(item.title, finalTemplateVars);
+    item.description = interpolateTemplates(item.description, finalTemplateVars);
+  }
+
   const uploaded = [];
   const failed = [];
 
-  for (let i = 0; i < toProcess.length; i++) {
-    const item = toProcess[i];
-    onEvent({ type: 'upload_start', item, index: i, total: toProcess.length });
+  for (let i = 0; i < activeToProcess.length; i++) {
+    const item = activeToProcess[i];
+    onEvent({ type: 'upload_start', item, index: i, total: activeToProcess.length });
 
     try {
       const uploadRes = await uploadVideo(
@@ -196,7 +339,7 @@ export async function batchUpload(targetFolder, options = {}) {
       if (playlistId) {
         onEvent({ type: 'playlist_start', item, videoId: uploadRes.videoId, playlistId });
         try {
-          await addToPlaylist(youtube, playlistId, uploadRes.videoId);
+          await addToPlaylist(youtube, playlistId, uploadRes.videoId, item.playlistPosition);
           addedToPlaylist = true;
           onEvent({ type: 'playlist_success', item, videoId: uploadRes.videoId, playlistId });
         } catch (playlistErr) {
@@ -228,5 +371,6 @@ export async function batchUpload(targetFolder, options = {}) {
     skipped,
     failed,
     estimatedQuota,
+    playlistId,
   };
 }