@julioventura/opensquad 0.1.17

package/skills/youtube-publisher/scripts/publish.js

@@ -0,0 +1,2078 @@
+#!/usr/bin/env node
+
+import { copyFile, mkdtemp, mkdir, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { createReadStream } from 'node:fs';
+import { dirname, extname, join, resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+import { spawn } from 'node:child_process';
+import process from 'node:process';
+import console from 'node:console';
+import { fileURLToPath } from 'node:url';
+
+const DEFAULT_ENV_KEYS = {
+  youtubeClientId: 'YOUTUBE_CLIENT_ID',
+  youtubeClientSecret: 'YOUTUBE_CLIENT_SECRET',
+  youtubeRefreshToken: 'YOUTUBE_REFRESH_TOKEN',
+  youtubeChannelId: 'YOUTUBE_CHANNEL_ID',
+};
+
+const YOUTUBE_OAUTH_SCOPES = [
+  'https://www.googleapis.com/auth/youtube.upload',
+  'https://www.googleapis.com/auth/youtube.force-ssl',
+  'https://www.googleapis.com/auth/youtube.readonly',
+];
+const YOUTUBE_API_BASE = 'https://www.googleapis.com/youtube/v3';
+const YOUTUBE_UPLOAD_BASE = 'https://www.googleapis.com/upload/youtube/v3/videos';
+const YOUTUBE_THUMBNAIL_UPLOAD_BASE = 'https://www.googleapis.com/upload/youtube/v3/thumbnails/set';
+const SLIDE_DURATION_SECONDS = 10;
+const AUDIO_FADE_IN_SECONDS = 2;
+const AUDIO_FADE_OUT_SECONDS = 5;
+const BACKGROUND_AUDIO_VOLUME = 0.3;
+const MAX_THUMBNAIL_BYTES = 2 * 1024 * 1024;
+const TARGET_VIDEO_WIDTH = 1280;
+const TARGET_VIDEO_HEIGHT = 720;
+const TARGET_VIDEO_FPS = 30;
+const VIDEO_PROGRESS_SIZE = 84;
+const VIDEO_PROGRESS_MARGIN = 24;
+const VIDEO_PROGRESS_STROKE = 6;
+const SUPPORTED_IMAGE_EXTENSIONS = ['.jpg', '.jpeg', '.png'];
+const SCRIPT_DIRECTORY = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_BACKGROUND_AUDIO_PATH = resolve(SCRIPT_DIRECTORY, '..', '..', '..', 'public', 'Trilha sonora de slides.mp3');
+const DEFAULT_TRANSITION_SOUND_ASSET_PATH = resolve(SCRIPT_DIRECTORY, '..', '..', '..', 'public', 'sfx', 'slide-transition-sfx.mp3');
+const ELEVEN_LABS_VOICE_ID = 'PznTnBc8X6pvixs9UkQm';
+const DEFAULT_TITLE_VOICE_ID = 'PznTnBc8X6pvixs9UkQm';
+const BACKGROUND_AUDIO_VOLUME_WITH_VOICE = 0.12;
+const NARRATION_AUDIO_VOLUME = 1.2;
+const SLIDE_NARRATION_LEAD_IN_SECONDS = 1;
+const SLIDE_NARRATION_TITLE_TO_TEXT_PAUSE_SECONDS = 1;
+const SLIDE_NARRATION_TAIL_SECONDS = 2;
+const SLIDE_TRANSITION_BUFFER_SECONDS = 1;
+const SLIDE_TRANSITION_DURATION_SECONDS = 2;
+const DEFAULT_SLIDE_TRANSITION = 'fadeblack';
+const TRANSITION_SOUND_EFFECT_VOLUME = 0.7;
+const TRANSITION_SOUND_EFFECT_PROMPT = 'A gentle warm whoosh with a pleasing tonal bloom, subtle and polished, for a calm visual transition. No voice, no percussion hit, lightly musical.';
+
+function buildCircularProgressOverlayFilter({ slideDurationSeconds, totalVideoDurationSeconds }) {
+  const canvasSize = VIDEO_PROGRESS_SIZE;
+  const center = Math.round(canvasSize / 2);
+  const outerRadius = Math.round(canvasSize / 2) - 4;
+  const innerRadius = outerRadius - VIDEO_PROGRESS_STROKE;
+  const overlayX = TARGET_VIDEO_WIDTH - canvasSize - VIDEO_PROGRESS_MARGIN;
+  const overlayY = VIDEO_PROGRESS_MARGIN;
+  const fadeStartSeconds = Math.max(totalVideoDurationSeconds - 3, 0);
+  const fadeOpacity = `if(lt(T\\,${fadeStartSeconds}),1,max(0,min(1,(${totalVideoDurationSeconds}-T)/3)))`;
+  const ringMask = `between(hypot(X-${center},Y-${center}),${innerRadius},${outerRadius})`;
+  const loopProgress = `(mod(T\\,${slideDurationSeconds})/${slideDurationSeconds})`;
+  const sweepAngle = `(2*PI*${loopProgress})`;
+  const normalizedAngle = `mod(atan2(Y-${center}\\,X-${center})+PI/2+2*PI\\,2*PI)`;
+  const track = `color=c=0xB8C2CF@1.0:s=${canvasSize}x${canvasSize}:d=${totalVideoDurationSeconds},format=rgba,geq=r='184':g='194':b='207':a='if(${ringMask},58*${fadeOpacity},0)'[progresstrack]`;
+  const fill = `color=c=0x00D1C7@1.0:s=${canvasSize}x${canvasSize}:d=${totalVideoDurationSeconds},format=rgba,geq=r='0':g='209':b='199':a='if(${ringMask}*lt(${normalizedAngle},${sweepAngle}),255*${fadeOpacity},0)'[progressfill]`;
+  const composite = `[basevideo][progresstrack]overlay=${overlayX}:${overlayY}:format=auto[progressbase];[progressbase][progressfill]overlay=${overlayX}:${overlayY}:format=auto[vout]`;
+  return `${track};${fill};${composite}`;
+}
+
+function buildPrimarySlideshowFilter({ slideDurationSeconds, totalVideoDurationSeconds, showProgressOverlay = true }) {
+  const baseVideo = `[0:v]split=2[bg][fg];[bg]scale=${TARGET_VIDEO_WIDTH}:${TARGET_VIDEO_HEIGHT}:force_original_aspect_ratio=increase,crop=${TARGET_VIDEO_WIDTH}:${TARGET_VIDEO_HEIGHT},boxblur=20:10[bgblur];[fg]scale=${TARGET_VIDEO_HEIGHT}:${TARGET_VIDEO_HEIGHT}:force_original_aspect_ratio=decrease[fgscaled];[bgblur][fgscaled]overlay=(W-w)/2:(H-h)/2,fps=${TARGET_VIDEO_FPS}[basevideo]`;
+  if (!showProgressOverlay) {
+    return `${baseVideo};[basevideo]null[vout]`;
+  }
+  return `${baseVideo};${buildCircularProgressOverlayFilter({ slideDurationSeconds, totalVideoDurationSeconds })}`;
+}
+
+function buildFallbackSlideshowFilter({ slideDurationSeconds, totalVideoDurationSeconds, showProgressOverlay = true }) {
+  const baseVideo = `[0:v]scale=${TARGET_VIDEO_HEIGHT}:${TARGET_VIDEO_HEIGHT}:force_original_aspect_ratio=decrease,pad=w=${TARGET_VIDEO_WIDTH}:h=${TARGET_VIDEO_HEIGHT}:x=(ow-iw)/2:y=(oh-ih)/2:color=0x1A2B45,fps=${TARGET_VIDEO_FPS}[basevideo]`;
+  if (!showProgressOverlay) {
+    return `${baseVideo};[basevideo]null[vout]`;
+  }
+  return `${baseVideo};${buildCircularProgressOverlayFilter({ slideDurationSeconds, totalVideoDurationSeconds })}`;
+}
+
+function parseBooleanFlag(value, flagName) {
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  throw new Error(`${flagName} must be 'true' or 'false'`);
+}
+
+export function parseArgs(argv) {
+  const args = {
+    images: [],
+    title: '',
+    description: '',
+    deleteVideoId: '',
+    deleteOnly: false,
+    tags: [],
+    thumbnailPath: '',
+    categoryId: '22',
+    privacyStatus: 'public',
+    madeForKids: false,
+    embeddable: true,
+    publicStatsViewable: true,
+    license: 'youtube',
+    publishAt: '',
+    defaultLanguage: '',
+    defaultAudioLanguage: '',
+    recordingDate: '',
+    videoOutput: '',
+    audioTrackPath: '',
+    playlistName: '',
+    playlistPrivacy: 'private',
+    dryRun: false,
+    youtubeClientIdEnv: null,
+    youtubeClientSecretEnv: null,
+    youtubeRefreshTokenEnv: null,
+    youtubeChannelIdEnv: null,
+    voiceId: ELEVEN_LABS_VOICE_ID,
+    titleVoiceId: DEFAULT_TITLE_VOICE_ID,
+    narration: true,
+    prebuiltNarrationAudioPath: '',
+    prebuiltSlideDurations: null,
+  };
+
+  for (let index = 2; index < argv.length; index++) {
+    const current = argv[index];
+
+    if (current === '--images' && index + 1 < argv.length) {
+      args.images = argv[++index].split(',').map((entry) => entry.trim()).filter(Boolean);
+    } else if (current === '--title' && index + 1 < argv.length) {
+      args.title = argv[++index];
+    } else if (current === '--description' && index + 1 < argv.length) {
+      args.description = argv[++index];
+    } else if (current === '--delete-video-id' && index + 1 < argv.length) {
+      args.deleteVideoId = argv[++index];
+    } else if (current === '--delete-only') {
+      args.deleteOnly = true;
+    } else if (current === '--tags' && index + 1 < argv.length) {
+      args.tags = argv[++index].split(',').map((entry) => entry.trim()).filter(Boolean);
+    } else if (current === '--thumbnail' && index + 1 < argv.length) {
+      args.thumbnailPath = argv[++index];
+    } else if (current === '--category-id' && index + 1 < argv.length) {
+      args.categoryId = argv[++index];
+    } else if (current === '--privacy-status' && index + 1 < argv.length) {
+      args.privacyStatus = argv[++index];
+    } else if (current === '--made-for-kids' && index + 1 < argv.length) {
+      args.madeForKids = parseBooleanFlag(argv[++index], '--made-for-kids');
+    } else if (current === '--embeddable' && index + 1 < argv.length) {
+      args.embeddable = parseBooleanFlag(argv[++index], '--embeddable');
+    } else if (current === '--public-stats-viewable' && index + 1 < argv.length) {
+      args.publicStatsViewable = parseBooleanFlag(argv[++index], '--public-stats-viewable');
+    } else if (current === '--license' && index + 1 < argv.length) {
+      args.license = argv[++index];
+    } else if (current === '--publish-at' && index + 1 < argv.length) {
+      args.publishAt = argv[++index];
+    } else if (current === '--default-language' && index + 1 < argv.length) {
+      args.defaultLanguage = argv[++index];
+    } else if (current === '--default-audio-language' && index + 1 < argv.length) {
+      args.defaultAudioLanguage = argv[++index];
+    } else if (current === '--recording-date' && index + 1 < argv.length) {
+      args.recordingDate = argv[++index];
+    } else if (current === '--video-output' && index + 1 < argv.length) {
+      args.videoOutput = argv[++index];
+    } else if (current === '--audio-track' && index + 1 < argv.length) {
+      args.audioTrackPath = argv[++index];
+    } else if (current === '--playlist-name' && index + 1 < argv.length) {
+      args.playlistName = argv[++index];
+    } else if (current === '--playlist-privacy' && index + 1 < argv.length) {
+      args.playlistPrivacy = argv[++index];
+    } else if (current === '--youtube-client-id-env' && index + 1 < argv.length) {
+      args.youtubeClientIdEnv = argv[++index];
+    } else if (current === '--youtube-client-secret-env' && index + 1 < argv.length) {
+      args.youtubeClientSecretEnv = argv[++index];
+    } else if (current === '--youtube-refresh-token-env' && index + 1 < argv.length) {
+      args.youtubeRefreshTokenEnv = argv[++index];
+    } else if (current === '--youtube-channel-id-env' && index + 1 < argv.length) {
+      args.youtubeChannelIdEnv = argv[++index];
+    } else if (current === '--voice-id' && index + 1 < argv.length) {
+      args.voiceId = argv[++index];
+    } else if (current === '--title-voice-id' && index + 1 < argv.length) {
+      args.titleVoiceId = argv[++index];
+    } else if (current === '--no-narration') {
+      args.narration = false;
+    } else if (current === '--narration-audio' && index + 1 < argv.length) {
+      args.prebuiltNarrationAudioPath = argv[++index];
+    } else if (current === '--slide-durations' && index + 1 < argv.length) {
+      args.prebuiltSlideDurations = argv[++index].split(',').map((v) => Number(v.trim())).filter((v) => Number.isFinite(v) && v > 0);
+    } else if (current === '--dry-run') {
+      args.dryRun = true;
+    }
+  }
+
+  return args;
+}
+
+export function resolveConfiguredEnv(env, options = {}) {
+  const youtubeClientIdKey = options.youtubeClientIdEnv || DEFAULT_ENV_KEYS.youtubeClientId;
+  const youtubeClientSecretKey = options.youtubeClientSecretEnv || DEFAULT_ENV_KEYS.youtubeClientSecret;
+  const youtubeRefreshTokenKey = options.youtubeRefreshTokenEnv || DEFAULT_ENV_KEYS.youtubeRefreshToken;
+  const youtubeChannelIdKey = options.youtubeChannelIdEnv || DEFAULT_ENV_KEYS.youtubeChannelId;
+
+  return {
+    youtubeClientIdKey,
+    youtubeClientSecretKey,
+    youtubeRefreshTokenKey,
+    youtubeChannelIdKey,
+    youtubeClientId: env[youtubeClientIdKey],
+    youtubeClientSecret: env[youtubeClientSecretKey],
+    youtubeRefreshToken: env[youtubeRefreshTokenKey],
+    youtubeChannelId: env[youtubeChannelIdKey],
+  };
+}
+
+function cleanContentText(value) {
+  return String(value || '')
+    .replace(/^>\s*/gm, '')
+    .replace(/\*\[([^\]]+)\]\*/g, '$1')
+    .replace(/\[([^\]]+)\]\((https?:\/\/[^)]+)\)/g, '$1: $2')
+    .replace(/\*\*/g, '')
+    .replace(/`/g, '')
+    .replace(/_/g, '')
+    .replace(/[ \t]+\n/g, '\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .replace(/^[\s'"`<]+/, '')
+    .replace(/[\s'"`>]+$/, '')
+    .trim();
+}
+
+function extractMarkdownSection(content, headingPattern, stopPatterns = []) {
+  return cleanContentText(extractMarkdownSectionRaw(content, headingPattern, stopPatterns));
+}
+
+function extractMarkdownSectionRaw(content, headingPattern, stopPatterns = []) {
+  const stopSource = stopPatterns.length
+    ? `(?=\\n##\\s+(?:${stopPatterns.join('|')})\\b|$)`
+    : '$';
+  const regex = new RegExp(`##\\s+${headingPattern}\\s+([\\s\\S]*?)${stopSource}`, 'i');
+  const match = content.match(regex);
+  return String(match?.[1] || '');
+}
+
+function parseVerifiedSources(section) {
+  const lines = String(section || '').split(/\r?\n/);
+  const sources = [];
+  let current = null;
+
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+    if (!line) continue;
+
+    const sourceMatch = line.match(/^[-*]\s+Fonte:\s+\[([^\]]+)\]\((https?:\/\/[^)]+)\)/i);
+    if (sourceMatch) {
+      current = {
+        name: cleanContentText(sourceMatch[1]),
+        url: sourceMatch[2].trim(),
+        consultedAt: '',
+      };
+      sources.push(current);
+      continue;
+    }
+
+    const consultedMatch = line.match(/^Consultado em:\s+(.+)$/i);
+    if (consultedMatch && current) {
+      current.consultedAt = cleanContentText(consultedMatch[1]);
+    }
+  }
+
+  return sources;
+}
+
+function parseCommunicationChannels(section) {
+  return String(section || '')
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => line.match(/^[-*]\s+([^:]+):\s+(.+)$/))
+    .filter(Boolean)
+    .map((match) => ({
+      label: cleanContentText(match[1]),
+      value: cleanContentText(match[2]),
+    }));
+}
+
+export async function parseContentPackageMetadata(contentPackagePath) {
+  const content = await readFile(contentPackagePath, 'utf-8');
+  const legend = extractMarkdownSection(content, 'Legenda', ['Saiba\\s+mais', 'Hashtags', 'YouTube', 'Notas', 'Checklist']);
+  const saibaMais = extractMarkdownSection(content, 'Saiba\\s+mais', ['Hashtags', 'YouTube', 'Notas', 'Checklist']);
+  const channels = extractMarkdownSection(content, 'Canais\\s+de\\s+comunicaç[aã]o', ['Fontes\\s+verificadas', 'Slide\\s+1', 'Legenda', 'Saiba\\s+mais', 'Hashtags']);
+  const verifiedSources = extractMarkdownSectionRaw(content, 'Fontes\\s+verificadas', ['Slide\\s+1', 'Legenda', 'Saiba\\s+mais', 'Hashtags', 'Notas', 'Checklist']);
+
+  return {
+    legend,
+    saibaMais,
+    channels: parseCommunicationChannels(channels),
+    verifiedSources: parseVerifiedSources(verifiedSources),
+  };
+}
+
+function formatYouTubeSourcesBlock(sources) {
+  if (!sources.length) return '';
+
+  return [
+    'FONTES VERIFICADAS',
+    ...sources.map((source) => `${source.name}: ${source.url}${source.consultedAt ? ` | Consultado em: ${source.consultedAt}` : ''}`),
+  ].join('\n');
+}
+
+function formatBrandChannelsBlock(channels) {
+  if (!channels.length) return '';
+
+  return [
+    'ACOMPANHE A MARCA:',
+    ...channels.map((channel) => `- ${channel.label}: ${channel.value}`),
+  ].join('\n');
+}
+
+export async function buildYouTubeDescriptionFromContentPackage(contentPackagePath, baseDescription = '') {
+  const metadata = await parseContentPackageMetadata(contentPackagePath);
+  const sections = [];
+  const initial = cleanContentText(baseDescription || metadata.legend);
+  const hasSaibaMais = /SAIBA MAIS:/i.test(initial);
+  const hasChannels = /ACOMPANHE A MARCA:/i.test(initial);
+  const hasVerifiedSources = /FONTES VERIFICADAS/i.test(initial);
+
+  if (initial) {
+    sections.push(initial);
+  }
+
+  if (!hasSaibaMais && metadata.saibaMais) {
+    sections.push(`SAIBA MAIS:\n${metadata.saibaMais}`);
+  }
+
+  if (!hasChannels) {
+    const channelsBlock = formatBrandChannelsBlock(metadata.channels);
+    if (channelsBlock) {
+      sections.push(channelsBlock);
+    }
+  }
+
+  if (!hasVerifiedSources) {
+    const sourcesBlock = formatYouTubeSourcesBlock(metadata.verifiedSources);
+    if (sourcesBlock) {
+      sections.push(sourcesBlock);
+    }
+  }
+
+  return sections.join('\n\n').trim();
+}
+
+export async function deleteVideo(options, env = process.env, deps = {}) {
+  const {
+    videoId,
+    deleteVideoId,
+    dryRun,
+    youtubeClientIdEnv,
+    youtubeClientSecretEnv,
+    youtubeRefreshTokenEnv,
+    youtubeChannelIdEnv,
+  } = options;
+  const {
+    exchangeRefreshTokenImpl = exchangeRefreshToken,
+    fetchOwnChannelImpl = fetchOwnChannel,
+    fetchImpl = globalThis.fetch,
+  } = deps;
+
+  const effectiveVideoId = String(videoId || deleteVideoId || '').trim();
+  if (!effectiveVideoId) throw new Error('--delete-video-id is required');
+
+  const configuredEnv = resolveConfiguredEnv(env, {
+    youtubeClientIdEnv,
+    youtubeClientSecretEnv,
+    youtubeRefreshTokenEnv,
+    youtubeChannelIdEnv,
+  });
+
+  const {
+    youtubeClientIdKey,
+    youtubeClientSecretKey,
+    youtubeRefreshTokenKey,
+    youtubeChannelIdKey,
+    youtubeClientId,
+    youtubeClientSecret,
+    youtubeRefreshToken,
+    youtubeChannelId,
+  } = configuredEnv;
+
+  if (!youtubeClientId) throw new Error(`${youtubeClientIdKey} is not set in environment`);
+  if (!youtubeClientSecret) throw new Error(`${youtubeClientSecretKey} is not set in environment`);
+  if (!youtubeRefreshToken) throw new Error(`${youtubeRefreshTokenKey} is not set in environment`);
+  if (!youtubeChannelId) throw new Error(`${youtubeChannelIdKey} is not set in environment`);
+
+  const accessToken = await exchangeRefreshTokenImpl({
+    clientId: youtubeClientId,
+    clientSecret: youtubeClientSecret,
+    refreshToken: youtubeRefreshToken,
+  });
+
+  const channel = await fetchOwnChannelImpl(accessToken, youtubeChannelId);
+  const result = {
+    status: dryRun ? 'dry-run' : 'deleted',
+    youtubeVideoId: effectiveVideoId,
+    youtubeUrl: `https://www.youtube.com/watch?v=${effectiveVideoId}`,
+    channelId: channel.id,
+    channelTitle: channel.snippet?.title ?? null,
+    scope: YOUTUBE_OAUTH_SCOPES,
+  };
+
+  if (dryRun) {
+    return result;
+  }
+
+  const response = await fetchImpl(`${YOUTUBE_API_BASE}/videos?id=${encodeURIComponent(effectiveVideoId)}`, {
+    method: 'DELETE',
+    headers: { Authorization: `Bearer ${accessToken}` },
+  });
+
+  if (!response.ok) {
+    throw new Error(`Video deletion failed [${response.status}]: ${await response.text()}`);
+  }
+
+  return result;
+}
+
+function assertSupportedImageExtension(imagePath) {
+  const extension = extname(imagePath).toLowerCase();
+  if (!SUPPORTED_IMAGE_EXTENSIONS.includes(extension)) {
+    throw new Error(`Unsupported image format for '${imagePath}'. Use JPG, JPEG, or PNG.`);
+  }
+}
+
+function assertSupportedThumbnailExtension(imagePath) {
+  const extension = extname(imagePath).toLowerCase();
+  if (!SUPPORTED_IMAGE_EXTENSIONS.includes(extension)) {
+    throw new Error(`Unsupported thumbnail format for '${imagePath}'. Use JPG, JPEG, or PNG.`);
+  }
+}
+
+export async function ensureImageFiles(imagePaths) {
+  for (const imagePath of imagePaths) {
+    assertSupportedImageExtension(imagePath);
+    await stat(resolve(imagePath));
+  }
+}
+
+export async function ensureThumbnailFile(thumbnailPath) {
+  if (!thumbnailPath) return null;
+
+  assertSupportedThumbnailExtension(thumbnailPath);
+  const thumbnailStats = await stat(resolve(thumbnailPath));
+  if (thumbnailStats.size > MAX_THUMBNAIL_BYTES) {
+    throw new Error(`Thumbnail exceeds YouTube's 2MB limit (${thumbnailStats.size} bytes).`);
+  }
+
+  return resolve(thumbnailPath);
+}
+
+export async function resolveBackgroundAudioPath(audioTrackPath, deps = {}) {
+  const { statImpl = stat } = deps;
+  const configuredPath = String(audioTrackPath || '').trim();
+  const candidatePath = configuredPath ? resolve(configuredPath) : DEFAULT_BACKGROUND_AUDIO_PATH;
+
+  try {
+    await statImpl(candidatePath);
+    return candidatePath;
+  } catch {
+    if (configuredPath) {
+      throw new Error(`Audio track not found at '${candidatePath}'.`);
+    }
+    return null;
+  }
+}
+
+function isValidIsoDateTime(value) {
+  return !Number.isNaN(Date.parse(value));
+}
+
+export function normalizeVideoMetadata(options) {
+  const normalized = {
+    title: options.title,
+    description: options.description,
+    tags: options.tags ?? [],
+    categoryId: options.categoryId,
+    privacyStatus: options.privacyStatus,
+    madeForKids: options.madeForKids ?? false,
+    embeddable: options.embeddable ?? true,
+    publicStatsViewable: options.publicStatsViewable ?? true,
+    license: options.license || 'youtube',
+    publishAt: options.publishAt || null,
+    defaultLanguage: options.defaultLanguage || null,
+    defaultAudioLanguage: options.defaultAudioLanguage || null,
+    recordingDate: options.recordingDate || null,
+  };
+
+  if (!['youtube', 'creativeCommon'].includes(normalized.license)) {
+    throw new Error(`Unsupported license '${normalized.license}'. Use youtube or creativeCommon.`);
+  }
+
+  if (normalized.publishAt && !isValidIsoDateTime(normalized.publishAt)) {
+    throw new Error(`Invalid --publish-at value '${normalized.publishAt}'. Use an ISO 8601 datetime.`);
+  }
+
+  if (normalized.recordingDate && !isValidIsoDateTime(normalized.recordingDate)) {
+    throw new Error(`Invalid --recording-date value '${normalized.recordingDate}'. Use an ISO 8601 date or datetime.`);
+  }
+
+  if (normalized.publishAt && normalized.privacyStatus !== 'private') {
+    throw new Error('--publish-at can only be used with --privacy-status private');
+  }
+
+  return normalized;
+}
+
+function escapeConcatPath(filePath) {
+  return filePath.replace(/'/g, "'\\''");
+}
+
+async function fileExists(filePath, deps = {}) {
+  const { statImpl = stat } = deps;
+  try {
+    await statImpl(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function findWingetFfmpegCandidates(deps = {}) {
+  const {
+    env = process.env,
+    platform = process.platform,
+    readdirImpl = readdir,
+    statImpl = stat,
+  } = deps;
+
+  if (platform !== 'win32') return [];
+
+  const localAppData = String(env.LOCALAPPDATA || '').trim();
+  if (!localAppData) return [];
+
+  const packagesDir = join(localAppData, 'Microsoft', 'WinGet', 'Packages');
+  let packageEntries = [];
+
+  try {
+    packageEntries = await readdirImpl(packagesDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const candidates = [];
+  for (const entry of packageEntries) {
+    if (!entry.isDirectory() || !/^Gyan\.FFmpeg/i.test(entry.name)) continue;
+
+    const packageDir = join(packagesDir, entry.name);
+    const directBinary = join(packageDir, 'ffmpeg.exe');
+    if (await fileExists(directBinary, { statImpl })) candidates.push(directBinary);
+
+    let nestedEntries = [];
+    try {
+      nestedEntries = await readdirImpl(packageDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const nestedEntry of nestedEntries) {
+      if (!nestedEntry.isDirectory()) continue;
+      const nestedBinary = join(packageDir, nestedEntry.name, 'bin', 'ffmpeg.exe');
+      if (await fileExists(nestedBinary, { statImpl })) candidates.push(nestedBinary);
+    }
+  }
+
+  return [...new Set(candidates)].sort((left, right) => right.localeCompare(left, undefined, { numeric: true }));
+}
+
+export async function resolveFfmpegCommand(deps = {}) {
+  const {
+    spawnImpl = spawn,
+    env = process.env,
+  } = deps;
+
+  const configuredBinary = String(env.FFMPEG_PATH || env.FFMPEG_BIN || '').trim();
+  const candidates = [configuredBinary, 'ffmpeg', ...(await findWingetFfmpegCandidates(deps))].filter(Boolean);
+  let lastError = null;
+
+  for (const candidate of candidates) {
+    try {
+      await runProcess(candidate, ['-version'], { spawnImpl, captureStdout: false });
+      return candidate;
+    } catch (error) {
+      lastError = error;
+    }
+  }
+
+  const message = lastError instanceof Error ? lastError.message : String(lastError || 'Unknown ffmpeg error');
+  throw new Error(
+    `ffmpeg is required for YouTube publishing. Checked FFMPEG_PATH/FFMPEG_BIN, PATH, and local WinGet installs. `
+    + `On Windows, install the validated full build with 'winget install --id Gyan.FFmpeg --silent --accept-package-agreements --accept-source-agreements'. `
+    + `Original error: ${message}`,
+  );
+}
+
+export async function ensureFfmpegAvailable(deps = {}) {
+  return resolveFfmpegCommand(deps);
+}
+
+export async function findContentPackage(imagePaths) {
+  const candidates = [];
+  
+  // 1. Current working directory
+  candidates.push(resolve(process.cwd(), 'content-package.md'));
+  candidates.push(resolve(process.cwd(), 'output', 'content-package.md'));
+  
+  if (imagePaths && imagePaths.length > 0) {
+    const firstImgDir = dirname(resolve(imagePaths[0]));
+    // 2. Directory of the first image
+    candidates.push(join(firstImgDir, 'content-package.md'));
+    // 3. Parent directory of the first image
+    const parentDir = dirname(firstImgDir);
+    candidates.push(join(parentDir, 'content-package.md'));
+    // 4. v1 directory of the parent directory
+    candidates.push(join(parentDir, 'v1', 'content-package.md'));
+    // 5. Parent's parent directory
+    candidates.push(join(dirname(parentDir), 'content-package.md'));
+  }
+  
+  for (const candidate of candidates) {
+    try {
+      const stats = await stat(candidate);
+      if (stats.isFile()) {
+        return candidate;
+      }
+    } catch {
+      // ignore
+    }
+  }
+  return null;
+}
+
+export async function parseSlideTexts(contentPackagePath) {
+  try {
+    const content = await readFile(contentPackagePath, 'utf-8');
+    const sections = content.split(/(?=^##\s+Slide\s+\d+)/mi);
+    const slideTexts = [];
+
+    const startIdx = sections[0].toLowerCase().includes('## slide') ? 0 : 1;
+
+    for (let i = startIdx; i < sections.length; i++) {
+      const section = sections[i];
+      const numMatch = section.match(/^##\s+Slide\s+(\d+)/i);
+      if (!numMatch) continue;
+      const slideNum = parseInt(numMatch[1], 10);
+
+      const lines = section.split('\n');
+      let text = '';
+      let title = '';
+      // Track which field we are currently accumulating multi-line content for
+      let currentField = null;
+      const textLines = [];
+      const titleLines = [];
+
+      for (const line of lines) {
+        const cleaned = line.trim();
+
+        if (/^\*\*Texto:\*\*/i.test(cleaned)) {
+          currentField = 'text';
+          const inline = cleaned.replace(/^\*\*Texto:\*\*\s*/i, '').trim();
+          if (inline) textLines.push(inline);
+        } else if (/^\*Texto:\*/i.test(cleaned)) {
+          currentField = 'text';
+          const inline = cleaned.replace(/^\*Texto:\*\s*/i, '').trim();
+          if (inline) textLines.push(inline);
+        } else if (/^Texto:\s*/i.test(cleaned)) {
+          currentField = 'text';
+          const inline = cleaned.replace(/^Texto:\s*/i, '').trim();
+          if (inline) textLines.push(inline);
+        } else if (/^\*\*T[íi]tulo:\*\*/i.test(cleaned)) {
+          currentField = 'title';
+          const inline = cleaned.replace(/^\*\*T[íi]tulo:\*\*\s*/i, '').trim();
+          if (inline) titleLines.push(inline);
+        } else if (/^\*T[íi]tulo:\*/i.test(cleaned)) {
+          currentField = 'title';
+          const inline = cleaned.replace(/^\*T[íi]tulo:\*\s*/i, '').trim();
+          if (inline) titleLines.push(inline);
+        } else if (/^T[íi]tulo:\s*/i.test(cleaned)) {
+          currentField = 'title';
+          const inline = cleaned.replace(/^T[íi]tulo:\s*/i, '').trim();
+          if (inline) titleLines.push(inline);
+        } else if (/^#{1,6}\s+/.test(cleaned)) {
+          // Stop when a new markdown section begins (e.g. ## Legenda after the final slide)
+          currentField = null;
+        } else if (/^\*\*[A-Za-zÀ-ÿ].*:\*\*/.test(cleaned) || /^---/.test(cleaned)) {
+          // New labeled field or section separator — stop accumulating
+          currentField = null;
+        } else if (currentField === 'text' && cleaned) {
+          // Continuation line for text (skip empty lines that just separate paragraphs)
+          textLines.push(cleaned);
+        } else if (currentField === 'title' && cleaned) {
+          titleLines.push(cleaned);
+        }
+      }
+
+      text = textLines.join(' ');
+      title = titleLines.join(' ');
+
+      const cleanMarkdown = (str) => {
+        return str
+          .replace(/\*\*/g, '')
+          .replace(/\*/g, '')
+          .replace(/`/g, '')
+          .replace(/_/g, '')
+          .trim();
+      };
+
+      text = cleanMarkdown(text);
+      title = cleanMarkdown(title);
+
+      if (title || text) {
+        slideTexts.push({
+          slideNum,
+          // text holds only the body copy (may be empty); synthesis path uses title-only when empty
+          text: text,
+          title: title,
+        });
+      }
+    }
+
+    slideTexts.sort((a, b) => a.slideNum - b.slideNum);
+    return slideTexts;
+  } catch {
+    return [];
+  }
+}
+
+export async function generateSlideAudio(text, apiKey, voiceId, tempDir, slideNum, voiceSettings = { stability: 0.5, similarity_boost: 0.75 }) {
+  const response = await globalThis.fetch(`https://api.elevenlabs.io/v1/text-to-speech/${voiceId}`, {
+    method: 'POST',
+    headers: {
+      'xi-api-key': apiKey,
+      'Content-Type': 'application/json',
+      'accept': 'audio/mpeg',
+    },
+    body: JSON.stringify({
+      text,
+      model_id: 'eleven_multilingual_v2',
+      voice_settings: voiceSettings,
+    }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Eleven Labs TTS request failed [${response.status}]: ${await response.text()}`);
+  }
+
+  const arrayBuffer = await response.arrayBuffer();
+  const buffer = Buffer.from(arrayBuffer);
+  const outputPath = join(tempDir, `slide_${slideNum}_raw.mp3`);
+  await writeFile(outputPath, buffer);
+  return outputPath;
+}
+
+export async function getAudioDuration(filePath, ffprobeCommand = 'ffprobe', spawnImpl = spawn) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const child = spawnImpl(ffprobeCommand, [
+      '-v', 'error',
+      '-show_entries', 'format=duration',
+      '-of', 'default=noprint_wrappers=1:nokey=1',
+      resolve(filePath),
+    ]);
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on('close', (code) => {
+      if (code === 0) {
+        const val = parseFloat(stdout.trim());
+        if (!Number.isNaN(val)) {
+          resolvePromise(val);
+          return;
+        }
+      }
+      rejectPromise(new Error(stderr.trim() || `Exit code ${code}`));
+    });
+    child.on('error', rejectPromise);
+  });
+}
+
+export async function padAudioFile(inputPath, outputPath, duration, ffmpegCommand, spawnImpl) {
+  await runProcess(
+    ffmpegCommand,
+    [
+      '-y',
+      '-i', resolve(inputPath),
+      '-filter_complex', '[0:a]adelay=2000|2000,apad[a]',
+      '-map', '[a]',
+      '-t', String(duration),
+      '-c:a', 'libmp3lame',
+      '-ar', '44100',
+      '-ac', '2',
+      resolve(outputPath),
+    ],
+    { spawnImpl, captureStdout: false }
+  );
+}
+
+export async function generateSilence(outputPath, duration, ffmpegCommand, spawnImpl) {
+  await runProcess(
+    ffmpegCommand,
+    [
+      '-y',
+      '-f', 'lavfi',
+      '-i', 'anullsrc=r=44100:cl=stereo',
+      '-t', String(duration),
+      '-c:a', 'libmp3lame',
+      '-ar', '44100',
+      '-ac', '2',
+      resolve(outputPath),
+    ],
+    { spawnImpl, captureStdout: false }
+  );
+}
+
+export async function buildNarrationTrack(images, contentPackagePath, slideDurationSeconds, apiKey, ffmpegCommand, tempDir, logger, spawnImpl = spawn, voiceId = ELEVEN_LABS_VOICE_ID, titleVoiceId = DEFAULT_TITLE_VOICE_ID, artifactsDir = null) {
+  const ffprobeCommand = ffmpegCommand.replace(/\bffmpeg(\.exe)?$/i, 'ffprobe$1');
+  const slideTexts = await parseSlideTexts(contentPackagePath);
+  logger.log(`🎙️ Parsed ${slideTexts.length} slide text(s) from content-package.md`);
+
+  if (artifactsDir) {
+    await mkdir(resolve(artifactsDir), { recursive: true });
+  }
+
+  // Pre-generate silence files
+  const silence3sPath = join(tempDir, 'silence_3s.mp3');
+  await generateSilence(silence3sPath, 3, ffmpegCommand, spawnImpl);
+  const silence2sPath = join(tempDir, 'silence_2s.mp3');
+  await generateSilence(silence2sPath, 2, ffmpegCommand, spawnImpl);
+  const silence1sPath = join(tempDir, 'silence_1s.mp3');
+  await generateSilence(silence1sPath, 1, ffmpegCommand, spawnImpl);
+
+  const paddedFiles = [];
+  const slideDurations = [];
+
+  for (let i = 0; i < images.length; i++) {
+    const imagePath = images[i];
+    const base = imagePath.split(/[/\\]/).pop() || '';
+    const numMatch = base.match(/slide-(\d+)/i);
+    const slideNum = numMatch ? parseInt(numMatch[1], 10) : (i + 1);
+
+    const paddedPath = join(tempDir, `slide_${slideNum}_padded.mp3`);
+    const slideTextEntry = slideTexts.find(entry => entry.slideNum === slideNum);
+
+    if (slideTextEntry && apiKey) {
+      const hasTitle = Boolean(slideTextEntry.title);
+      const hasText = Boolean(slideTextEntry.text);
+
+      if (!hasTitle && !hasText) {
+        logger.log(`🔇 Slide ${slideNum} has no title or text. Using silence.`);
+        await generateSilence(paddedPath, slideDurationSeconds, ffmpegCommand, spawnImpl);
+        paddedFiles.push(paddedPath);
+        slideDurations.push(slideDurationSeconds);
+        continue;
+      }
+
+      try {
+        let titleRawPath = null;
+        let titleDuration = 0;
+        if (hasTitle) {
+          logger.log(`🗣️ Synthesizing slide ${slideNum} title with Eleven Labs (voice: ${titleVoiceId}): "${slideTextEntry.title}"`);
+          const titleSettings = {
+            stability: 0.35,
+            similarity_boost: 0.8,
+            style: 0.55,
+            use_speaker_boost: true
+          };
+          titleRawPath = await generateSlideAudio(slideTextEntry.title, apiKey, titleVoiceId, tempDir, `title_${slideNum}`, titleSettings);
+          try {
+            titleDuration = await getAudioDuration(titleRawPath, ffprobeCommand, spawnImpl);
+          } catch (durErr) {
+            logger.log(`⚠️ Failed to measure title duration for slide ${slideNum}: ${durErr.message}. Using fallback.`);
+            titleDuration = 3.0; // fallback default
+          }
+        }
+
+        let textRawPath = null;
+        let textDuration = 0;
+        if (hasText) {
+          logger.log(`🗣️ Synthesizing slide ${slideNum} text with Eleven Labs (voice: ${voiceId}): "${slideTextEntry.text.substring(0, 50)}..."`);
+          const textSettings = {
+            stability: 0.5,
+            similarity_boost: 0.75,
+            style: 0.0,
+            use_speaker_boost: true
+          };
+          textRawPath = await generateSlideAudio(slideTextEntry.text, apiKey, voiceId, tempDir, `text_${slideNum}`, textSettings);
+          try {
+            textDuration = await getAudioDuration(textRawPath, ffprobeCommand, spawnImpl);
+          } catch (durErr) {
+            logger.log(`⚠️ Failed to measure text duration for slide ${slideNum}: ${durErr.message}. Using fallback.`);
+            textDuration = 6.0; // fallback default
+          }
+        }
+
+        // Build slide-specific concat list to combine silence, title, and text
+        const slideConcatListPath = join(tempDir, `slide_${slideNum}_concat.txt`);
+        const slideLines = [];
+        let totalDuration = 0;
+
+        // 3s silence at the start of the first slide, 1s for the rest
+        if (i === 0) {
+          slideLines.push(`file '${escapeConcatPath(resolve(silence3sPath))}'`);
+          totalDuration += 3;
+        } else {
+          slideLines.push(`file '${escapeConcatPath(resolve(silence1sPath))}'`);
+          totalDuration += SLIDE_NARRATION_LEAD_IN_SECONDS;
+        }
+
+        if (hasTitle) {
+          slideLines.push(`file '${escapeConcatPath(resolve(titleRawPath))}'`);
+          totalDuration += titleDuration;
+          if (hasText) {
+            // 1s pause between title and text
+            slideLines.push(`file '${escapeConcatPath(resolve(silence1sPath))}'`);
+            totalDuration += SLIDE_NARRATION_TITLE_TO_TEXT_PAUSE_SECONDS;
+          }
+        }
+
+        if (hasText) {
+          slideLines.push(`file '${escapeConcatPath(resolve(textRawPath))}'`);
+          totalDuration += textDuration;
+        }
+
+        // 2s silence at the end
+        slideLines.push(`file '${escapeConcatPath(resolve(silence2sPath))}'`);
+        totalDuration += SLIDE_NARRATION_TAIL_SECONDS;
+
+        await writeFile(slideConcatListPath, `${slideLines.join('\n')}\n`, 'utf-8');
+
+        const tempMergedPath = join(tempDir, `slide_${slideNum}_merged_raw.mp3`);
+        await runProcess(
+          ffmpegCommand,
+          [
+            '-y',
+            '-f', 'concat',
+            '-safe', '0',
+            '-i', slideConcatListPath,
+            '-c:a', 'libmp3lame',
+            '-ar', '44100',
+            '-ac', '2',
+            resolve(tempMergedPath),
+          ],
+          { spawnImpl, captureStdout: false }
+        );
+
+        const finalDuration = totalDuration + SLIDE_TRANSITION_BUFFER_SECONDS;
+
+        // Pad the merged audio to the final slide duration (ensures audio and video slide transitions stay in perfect sync)
+        await runProcess(
+          ffmpegCommand,
+          [
+            '-y',
+            '-i', resolve(tempMergedPath),
+            '-filter_complex', '[0:a]apad[a]',
+            '-map', '[a]',
+            '-t', String(finalDuration),
+            '-c:a', 'libmp3lame',
+            '-ar', '44100',
+            '-ac', '2',
+            resolve(paddedPath),
+          ],
+          { spawnImpl, captureStdout: false }
+        );
+
+        paddedFiles.push(paddedPath);
+        slideDurations.push(finalDuration);
+        if (artifactsDir) {
+          const artifactPath = join(resolve(artifactsDir), `slide-${String(slideNum).padStart(2, '0')}.mp3`);
+          await copyFile(resolve(paddedPath), artifactPath);
+        }
+      } catch (error) {
+        logger.log(`⚠️ Eleven Labs TTS or merge failed for slide ${slideNum}: ${error.message}. Falling back to silence.`);
+        await generateSilence(paddedPath, slideDurationSeconds, ffmpegCommand, spawnImpl);
+        paddedFiles.push(paddedPath);
+        slideDurations.push(slideDurationSeconds);
+        if (artifactsDir) {
+          const artifactPath = join(resolve(artifactsDir), `slide-${String(slideNum).padStart(2, '0')}.mp3`);
+          await copyFile(resolve(paddedPath), artifactPath);
+        }
+      }
+    } else {
+      if (!apiKey && slideTextEntry) {
+        logger.log(`⚠️ Eleven Labs API key not available for slide ${slideNum}. Using silence.`);
+      } else {
+        logger.log(`🔇 No text for slide ${slideNum}. Using silence.`);
+      }
+      await generateSilence(paddedPath, slideDurationSeconds, ffmpegCommand, spawnImpl);
+      paddedFiles.push(paddedPath);
+      slideDurations.push(slideDurationSeconds);
+      if (artifactsDir) {
+        const artifactPath = join(resolve(artifactsDir), `slide-${String(slideNum).padStart(2, '0')}.mp3`);
+        await copyFile(resolve(paddedPath), artifactPath);
+      }
+    }
+  }
+
+  const audioListPath = join(tempDir, 'audio_concat.txt');
+  const lines = [];
+  for (let index = 0; index < paddedFiles.length; index += 1) {
+    lines.push(`file '${escapeConcatPath(resolve(paddedFiles[index]))}'`);
+    if (index < paddedFiles.length - 1) {
+      lines.push(`file '${escapeConcatPath(resolve(silence2sPath))}'`);
+    }
+  }
+  await writeFile(audioListPath, `${lines.join('\n')}\n`, 'utf-8');
+
+  const narrationPath = join(tempDir, 'narration.mp3');
+  logger.log(`🧩 Concatenating slide audio files into narration track...`);
+  await runProcess(
+    ffmpegCommand,
+    [
+      '-y',
+      '-f', 'concat',
+      '-safe', '0',
+      '-i', audioListPath,
+      '-c', 'copy',
+      narrationPath,
+    ],
+    { spawnImpl, captureStdout: false }
+  );
+
+  let persistedNarrationPath = null;
+  if (artifactsDir) {
+    persistedNarrationPath = join(resolve(artifactsDir), 'narration.mp3');
+    await copyFile(resolve(narrationPath), persistedNarrationPath);
+  }
+
+  return {
+    narrationPath,
+    persistedNarrationPath,
+    slideDurations
+  };
+}
+
+function resolveNarrationArtifactsDir(images) {
+  if (!images?.length) return null;
+
+  const imagesDir = dirname(resolve(images[0]));
+  const runDir = dirname(imagesDir);
+  return join(runDir, 'audio');
+}
+
+export async function resolveBundledTransitionSoundAssetPath(statImpl = stat) {
+  try {
+    const assetStats = await statImpl(DEFAULT_TRANSITION_SOUND_ASSET_PATH);
+    if (assetStats.isFile()) {
+      return DEFAULT_TRANSITION_SOUND_ASSET_PATH;
+    }
+  } catch {
+    return null;
+  }
+
+  return null;
+}
+
+export async function generateTransitionSoundEffect(options, deps = {}) {
+  const {
+    apiKey,
+    tempDir,
+    logger = console,
+    durationSeconds = SLIDE_TRANSITION_DURATION_SECONDS,
+    artifactsDir = null,
+    prompt = TRANSITION_SOUND_EFFECT_PROMPT,
+  } = options;
+  const {
+    fetchImpl = globalThis.fetch,
+    writeFileImpl = writeFile,
+    mkdirImpl = mkdir,
+  } = deps;
+
+  if (!apiKey) {
+    throw new Error('ELEVEN_LABS_API key is required to generate transition sound effects.');
+  }
+
+  const outputPath = join(tempDir, 'slide-transition-sfx.mp3');
+  logger.log('🎵 Generating slide transition sound effect...');
+
+  const response = await fetchImpl('https://api.elevenlabs.io/v1/sound-generation', {
+    method: 'POST',
+    headers: {
+      'xi-api-key': apiKey,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      text: prompt,
+      duration_seconds: durationSeconds,
+      prompt_influence: 0.45,
+      model_id: 'eleven_text_to_sound_v2',
+    }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Eleven Labs sound-generation failed [${response.status}]: ${await response.text()}`);
+  }
+
+  const arrayBuffer = await response.arrayBuffer();
+  await writeFileImpl(outputPath, Buffer.from(arrayBuffer));
+
+  let persistedSoundPath = null;
+  if (artifactsDir) {
+    await mkdirImpl(resolve(artifactsDir), { recursive: true });
+    persistedSoundPath = join(resolve(artifactsDir), 'slide-transition-sfx.mp3');
+    await copyFile(resolve(outputPath), persistedSoundPath);
+  }
+
+  return {
+    soundPath: outputPath,
+    persistedSoundPath,
+  };
+}
+
+function buildTransitionPrimarySlideshowFilter({ imageCount, slideDurations, transitionDurationSeconds }) {
+  const filterParts = [];
+
+  for (let index = 0; index < imageCount; index += 1) {
+    filterParts.push(
+      `[${index}:v]split=2[bg${index}][fg${index}]`,
+      `[bg${index}]scale=${TARGET_VIDEO_WIDTH}:${TARGET_VIDEO_HEIGHT}:force_original_aspect_ratio=increase,crop=${TARGET_VIDEO_WIDTH}:${TARGET_VIDEO_HEIGHT},boxblur=20:10[bgblur${index}]`,
+      `[fg${index}]scale=${TARGET_VIDEO_HEIGHT}:${TARGET_VIDEO_HEIGHT}:force_original_aspect_ratio=decrease[fgscaled${index}]`,
+      `[bgblur${index}][fgscaled${index}]overlay=(W-w)/2:(H-h)/2,fps=${TARGET_VIDEO_FPS},setsar=1[slide${index}]`,
+    );
+  }
+
+  let currentLabel = '[slide0]';
+  let currentOffset = slideDurations[0] || SLIDE_DURATION_SECONDS;
+  for (let index = 1; index < imageCount; index += 1) {
+    const outputLabel = index === imageCount - 1 ? '[vout]' : `[xfade${index}]`;
+    filterParts.push(`${currentLabel}[slide${index}]xfade=transition=${DEFAULT_SLIDE_TRANSITION}:duration=${transitionDurationSeconds}:offset=${currentOffset}${outputLabel}`);
+    currentLabel = outputLabel;
+    currentOffset += (slideDurations[index] || SLIDE_DURATION_SECONDS) + transitionDurationSeconds;
+  }
+
+  return filterParts.join(';');
+}
+
+function buildTransitionFallbackSlideshowFilter({ imageCount, slideDurations, transitionDurationSeconds }) {
+  const filterParts = [];
+
+  for (let index = 0; index < imageCount; index += 1) {
+    filterParts.push(
+      `[${index}:v]scale=${TARGET_VIDEO_HEIGHT}:${TARGET_VIDEO_HEIGHT}:force_original_aspect_ratio=decrease,pad=w=${TARGET_VIDEO_WIDTH}:h=${TARGET_VIDEO_HEIGHT}:x=(ow-iw)/2:y=(oh-ih)/2:color=0x1A2B45,fps=${TARGET_VIDEO_FPS},setsar=1[slide${index}]`,
+    );
+  }
+
+  let currentLabel = '[slide0]';
+  let currentOffset = slideDurations[0] || SLIDE_DURATION_SECONDS;
+  for (let index = 1; index < imageCount; index += 1) {
+    const outputLabel = index === imageCount - 1 ? '[vout]' : `[xfade${index}]`;
+    filterParts.push(`${currentLabel}[slide${index}]xfade=transition=${DEFAULT_SLIDE_TRANSITION}:duration=${transitionDurationSeconds}:offset=${currentOffset}${outputLabel}`);
+    currentLabel = outputLabel;
+    currentOffset += (slideDurations[index] || SLIDE_DURATION_SECONDS) + transitionDurationSeconds;
+  }
+
+  return filterParts.join(';');
+}
+
+export async function buildSlideshowVideo(options, deps = {}) {
+  const {
+    images,
+    videoOutput,
+    slideDurationSeconds = SLIDE_DURATION_SECONDS,
+    backgroundAudioPath = null,
+    narrationAudioPath = null,
+    slideDurations = null,
+    transitionDurationSeconds = 0,
+    transitionSoundPath = null,
+  } = options;
+  const {
+    spawnImpl = spawn,
+    writeFileImpl = writeFile,
+    mkdirImpl = mkdir,
+    mkdtempImpl = mkdtemp,
+    rmImpl = rm,
+    ffmpegCommand = 'ffmpeg',
+  } = deps;
+
+  const tempDir = await mkdtempImpl(join(tmpdir(), 'opensquad-youtube-'));
+  const outputPath = resolve(videoOutput || join(tempDir, 'youtube-slideshow.mp4'));
+  const concatFilePath = join(tempDir, 'slides.txt');
+  const useTransitions = transitionDurationSeconds > 0 && images.length > 1;
+  const effectiveSlideDurations = slideDurations && slideDurations.length > 0
+    ? slideDurations
+    : images.map(() => slideDurationSeconds);
+  const effectiveInputDurations = useTransitions
+    ? effectiveSlideDurations.map((duration, index) => {
+      const isFirst = index === 0;
+      const isLast = index === images.length - 1;
+      const transitionPadding = isFirst || isLast
+        ? transitionDurationSeconds
+        : transitionDurationSeconds * 2;
+      return duration + transitionPadding;
+    })
+    : effectiveSlideDurations;
+  const totalVideoDurationSeconds = effectiveSlideDurations.reduce((sum, duration, index) => (
+    sum + duration + (useTransitions && index < images.length - 1 ? transitionDurationSeconds : 0)
+  ), 0);
+    
+  const fadeOutStartSeconds = Math.max(totalVideoDurationSeconds - AUDIO_FADE_OUT_SECONDS, 0);
+
+  await mkdirImpl(dirname(outputPath), { recursive: true });
+  if (!useTransitions) {
+    const lines = [];
+    for (let index = 0; index < images.length; index += 1) {
+      lines.push(`file '${escapeConcatPath(resolve(images[index]))}'`);
+      lines.push(`duration ${effectiveSlideDurations[index]}`);
+    }
+    lines.push(`file '${escapeConcatPath(resolve(images[images.length - 1]))}'`);
+    await writeFileImpl(concatFilePath, `${lines.join('\n')}\n`, 'utf-8');
+  }
+
+  try {
+    const buildFfmpegArgs = (filterComplexBuilder) => {
+      const args = ['-y'];
+
+      if (useTransitions) {
+        for (let index = 0; index < images.length; index += 1) {
+          args.push('-loop', '1', '-t', String(effectiveInputDurations[index]), '-i', resolve(images[index]));
+        }
+      } else {
+        args.push('-f', 'concat', '-safe', '0', '-i', concatFilePath);
+      }
+
+      let narrationInputIdx = -1;
+      let bgInputIdx = -1;
+      let transitionSoundInputIdx = -1;
+      let inputCount = useTransitions ? images.length : 1;
+
+      if (narrationAudioPath) {
+        args.push('-i', resolve(narrationAudioPath));
+        narrationInputIdx = inputCount++;
+      }
+
+      if (backgroundAudioPath) {
+        args.push('-stream_loop', '-1', '-i', resolve(backgroundAudioPath));
+        bgInputIdx = inputCount++;
+      }
+
+      if (transitionSoundPath) {
+        args.push('-i', resolve(transitionSoundPath));
+        transitionSoundInputIdx = inputCount++;
+      }
+
+      const effectiveOverlayDuration = (slideDurations && slideDurations.length > 0)
+        ? (totalVideoDurationSeconds / images.length)
+        : slideDurationSeconds;
+
+      const isFixedTiming = (!slideDurations || slideDurations.length === 0) && !useTransitions;
+      const videoFilter = filterComplexBuilder({
+        imageCount: images.length,
+        slideDurations: effectiveSlideDurations,
+        transitionDurationSeconds,
+        slideDurationSeconds: effectiveOverlayDuration,
+        totalVideoDurationSeconds,
+        showProgressOverlay: isFixedTiming,
+      });
+      
+      let audioFilter = '';
+      const mixLabels = [];
+      if (narrationInputIdx !== -1) {
+        audioFilter += `;[${narrationInputIdx}:a]volume=${NARRATION_AUDIO_VOLUME},apad,atrim=0:${totalVideoDurationSeconds}[narr]`;
+        mixLabels.push('[narr]');
+      }
+      if (bgInputIdx !== -1) {
+        const bgVolume = narrationInputIdx !== -1 ? BACKGROUND_AUDIO_VOLUME_WITH_VOICE : BACKGROUND_AUDIO_VOLUME;
+        audioFilter += `;[${bgInputIdx}:a]volume=${bgVolume},atrim=0:${totalVideoDurationSeconds},afade=t=in:st=0:d=${AUDIO_FADE_IN_SECONDS},afade=t=out:st=${fadeOutStartSeconds}:d=${AUDIO_FADE_OUT_SECONDS}[bg]`;
+        mixLabels.push('[bg]');
+      }
+      if (transitionSoundInputIdx !== -1 && useTransitions) {
+        const transitionOffsets = [];
+        let currentOffset = effectiveSlideDurations[0];
+        for (let index = 1; index < images.length; index += 1) {
+          transitionOffsets.push(currentOffset);
+          currentOffset += effectiveSlideDurations[index] + transitionDurationSeconds;
+        }
+
+        if (transitionOffsets.length === 1) {
+          const delayMs = Math.max(Math.round(transitionOffsets[0] * 1000), 0);
+          audioFilter += `;[${transitionSoundInputIdx}:a]atrim=0:${transitionDurationSeconds},volume=${TRANSITION_SOUND_EFFECT_VOLUME},adelay=${delayMs}|${delayMs}[sfx0]`;
+          mixLabels.push('[sfx0]');
+        } else if (transitionOffsets.length > 1) {
+          const splitLabels = transitionOffsets.map((_, index) => `[sfxsrc${index}]`);
+          audioFilter += `;[${transitionSoundInputIdx}:a]asplit=${splitLabels.length}${splitLabels.join('')}`;
+          transitionOffsets.forEach((offsetSeconds, index) => {
+            const delayMs = Math.max(Math.round(offsetSeconds * 1000), 0);
+            audioFilter += `;[sfxsrc${index}]atrim=0:${transitionDurationSeconds},volume=${TRANSITION_SOUND_EFFECT_VOLUME},adelay=${delayMs}|${delayMs}[sfx${index}]`;
+            mixLabels.push(`[sfx${index}]`);
+          });
+        }
+      }
+
+      if (mixLabels.length === 1) {
+        audioFilter += `;${mixLabels[0]}anull[aout]`;
+      } else if (mixLabels.length > 1) {
+        audioFilter += `;${mixLabels.join('')}amix=inputs=${mixLabels.length}:duration=first:dropout_transition=0:normalize=0[aout]`;
+      }
+
+      const fadedVideoFilter = `${videoFilter};[vout]fade=t=in:st=0:d=0.666[vout_faded]`;
+      args.push('-filter_complex', `${fadedVideoFilter}${audioFilter}`);
+      args.push('-map', '[vout_faded]');
+      
+      if (mixLabels.length > 0) {
+        args.push('-map', '[aout]', '-c:a', 'aac', '-b:a', '192k');
+        if (bgInputIdx !== -1 && narrationInputIdx === -1) {
+          args.push('-shortest');
+        }
+      }
+
+      args.push('-r', String(TARGET_VIDEO_FPS));
+      args.push('-pix_fmt', 'yuv420p');
+      args.push('-c:v', 'libx264');
+      args.push(outputPath);
+
+      return args;
+    };
+
+    try {
+      await runProcess(
+        ffmpegCommand,
+        buildFfmpegArgs(useTransitions ? buildTransitionPrimarySlideshowFilter : buildPrimarySlideshowFilter),
+        { spawnImpl, captureStdout: false }
+      );
+    } catch (primaryError) {
+      await runProcess(
+        ffmpegCommand,
+        buildFfmpegArgs(useTransitions ? buildTransitionFallbackSlideshowFilter : buildFallbackSlideshowFilter),
+        { spawnImpl, captureStdout: false }
+      );
+    }
+    return outputPath;
+  } finally {
+    await rmImpl(tempDir, { recursive: true, force: true });
+  }
+}
+
+export async function buildGeneratedThumbnail(options, deps = {}) {
+  const {
+    sourceImagePath,
+    videoOutput,
+  } = options;
+  const {
+    spawnImpl = spawn,
+    mkdirImpl = mkdir,
+    ffmpegCommand = 'ffmpeg',
+  } = deps;
+
+  const sourcePath = resolve(sourceImagePath);
+  const imageDir = dirname(sourcePath);
+  const thumbnailDir = videoOutput
+    ? resolve(dirname(videoOutput), '..', 'thumbs')
+    : resolve(imageDir, '..', 'thumbs');
+  const outputPath = resolve(thumbnailDir, 'youtube-thumb-16x9.jpg');
+
+  await mkdirImpl(thumbnailDir, { recursive: true });
+  try {
+    await runProcess(
+      ffmpegCommand,
+      [
+        '-y',
+        '-i', sourcePath,
+        '-filter_complex',
+        '[0:v]split=2[bg][fg];[bg]scale=1280:720:force_original_aspect_ratio=increase,crop=1280:720,boxblur=20:10[bgblur];[fg]scale=720:720:force_original_aspect_ratio=decrease[fgscaled];[bgblur][fgscaled]overlay=(W-w)/2:(H-h)/2',
+        '-frames:v', '1',
+        '-q:v', '2',
+        outputPath,
+      ],
+      { spawnImpl, captureStdout: false },
+    );
+  } catch {
+    // Fallback for ffmpeg builds that lack boxblur or have stricter filter support.
+    await runProcess(
+      ffmpegCommand,
+      [
+        '-y',
+        '-i', sourcePath,
+        '-vf',
+        'scale=720:720:force_original_aspect_ratio=decrease,pad=w=1280:h=720:x=(ow-iw)/2:y=(oh-ih)/2:color=0x1A2B45',
+        '-frames:v', '1',
+        '-q:v', '2',
+        outputPath,
+      ],
+      { spawnImpl, captureStdout: false },
+    );
+  }
+
+  return outputPath;
+}
+
+async function runProcess(command, args, options = {}) {
+  const { spawnImpl = spawn, captureStdout = true } = options;
+
+  await new Promise((resolvePromise, rejectPromise) => {
+    const child = spawnImpl(command, args, { stdio: captureStdout ? ['ignore', 'pipe', 'pipe'] : ['ignore', 'ignore', 'pipe'] });
+    let stderr = '';
+    let stdout = '';
+
+    if (child.stdout) {
+      child.stdout.on('data', (chunk) => {
+        stdout += chunk.toString();
+      });
+    }
+
+    if (child.stderr) {
+      child.stderr.on('data', (chunk) => {
+        stderr += chunk.toString();
+      });
+    }
+
+    child.on('error', rejectPromise);
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolvePromise({ stdout, stderr });
+        return;
+      }
+
+      rejectPromise(new Error(`${command} exited with code ${code}${stderr ? `: ${stderr.trim()}` : ''}`));
+    });
+  });
+}
+
+export async function exchangeRefreshToken(options, deps = {}) {
+  const {
+    clientId,
+    clientSecret,
+    refreshToken,
+    fetchImpl = globalThis.fetch,
+  } = { ...options, ...deps };
+
+  const body = new globalThis.URLSearchParams({
+    client_id: clientId,
+    client_secret: clientSecret,
+    refresh_token: refreshToken,
+    grant_type: 'refresh_token',
+  });
+
+  const response = await fetchImpl('https://oauth2.googleapis.com/token', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body,
+  });
+
+  if (!response.ok) {
+    throw new Error(`OAuth token exchange failed [${response.status}]: ${await response.text()}`);
+  }
+
+  const json = await response.json();
+  if (!json.access_token) {
+    throw new Error('OAuth token exchange succeeded without access_token');
+  }
+
+  return json.access_token;
+}
+
+export async function fetchOwnChannel(accessToken, channelId, deps = {}) {
+  const { fetchImpl = globalThis.fetch } = deps;
+  const url = `${YOUTUBE_API_BASE}/channels?part=snippet&mine=true`;
+  const response = await fetchImpl(url, {
+    headers: { Authorization: `Bearer ${accessToken}` },
+  });
+
+  if (!response.ok) {
+    throw new Error(`Channel lookup failed [${response.status}]: ${await response.text()}`);
+  }
+
+  const json = await response.json();
+  const channel = json.items?.find((entry) => entry.id === channelId);
+  if (!channel) {
+    throw new Error(`Authenticated Google account does not have access to YouTube channel '${channelId}'.`);
+  }
+
+  return channel;
+}
+
+export async function createResumableUploadSession(options, deps = {}) {
+  const {
+    accessToken,
+    metadata,
+    fetchImpl = globalThis.fetch,
+  } = { ...options, ...deps };
+
+  const payload = {
+    snippet: {
+      title: metadata.title,
+      description: metadata.description,
+      categoryId: metadata.categoryId,
+      tags: metadata.tags,
+    },
+    status: {
+      privacyStatus: metadata.privacyStatus,
+      embeddable: metadata.embeddable,
+      publicStatsViewable: metadata.publicStatsViewable,
+      license: metadata.license,
+      selfDeclaredMadeForKids: metadata.madeForKids,
+    },
+  };
+
+  if (metadata.publishAt) {
+    payload.status.publishAt = metadata.publishAt;
+  }
+
+  if (metadata.defaultLanguage) {
+    payload.snippet.defaultLanguage = metadata.defaultLanguage;
+  }
+
+  if (metadata.defaultAudioLanguage) {
+    payload.snippet.defaultAudioLanguage = metadata.defaultAudioLanguage;
+  }
+
+  if (metadata.recordingDate) {
+    payload.recordingDetails = {
+      recordingDate: metadata.recordingDate,
+    };
+  }
+
+  const parts = ['snippet', 'status'];
+  if (payload.recordingDetails) {
+    parts.push('recordingDetails');
+  }
+
+  const url = `${YOUTUBE_UPLOAD_BASE}?uploadType=resumable&part=${parts.join(',')}`;
+  const response = await fetchImpl(url, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+      'Content-Type': 'application/json; charset=UTF-8',
+      'X-Upload-Content-Type': 'video/mp4',
+    },
+    body: JSON.stringify(payload),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Upload session creation failed [${response.status}]: ${await response.text()}`);
+  }
+
+  const uploadUrl = response.headers.get('location');
+  if (!uploadUrl) {
+    throw new Error('Upload session created without resumable location header');
+  }
+
+  return uploadUrl;
+}
+
+export async function uploadVideoBinary(options, deps = {}) {
+  const {
+    uploadUrl,
+    videoPath,
+    fetchImpl = globalThis.fetch,
+    createReadStreamImpl = createReadStream,
+  } = { ...options, ...deps };
+
+  const response = await fetchImpl(uploadUrl, {
+    method: 'PUT',
+    headers: {
+      'Content-Type': 'video/mp4',
+    },
+    body: createReadStreamImpl(videoPath),
+    duplex: 'half',
+  });
+
+  if (!response.ok) {
+    throw new Error(`Video upload failed [${response.status}]: ${await response.text()}`);
+  }
+
+  const json = await response.json();
+  if (!json.id) {
+    throw new Error('Video upload succeeded without a returned video ID');
+  }
+
+  return json;
+}
+
+export async function uploadThumbnail(options, deps = {}) {
+  const {
+    accessToken,
+    videoId,
+    thumbnailPath,
+    fetchImpl = globalThis.fetch,
+    createReadStreamImpl = createReadStream,
+  } = { ...options, ...deps };
+
+  const extension = extname(thumbnailPath).toLowerCase();
+  const contentType = 'image/jpeg';
+  const url = `${YOUTUBE_THUMBNAIL_UPLOAD_BASE}?videoId=${encodeURIComponent(videoId)}`;
+  const response = await fetchImpl(url, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+      'Content-Type': contentType,
+    },
+    body: createReadStreamImpl(thumbnailPath),
+    duplex: 'half',
+  });
+
+  if (!response.ok) {
+    throw new Error(`Thumbnail upload failed [${response.status}]: ${await response.text()}`);
+  }
+
+  return response.json();
+}
+
+export async function ensurePlaylist(options, deps = {}) {
+  const {
+    accessToken,
+    playlistName,
+    playlistPrivacy = 'private',
+    fetchImpl = globalThis.fetch,
+  } = { ...options, ...deps };
+
+  if (!playlistName) return null;
+  if (!['private', 'public'].includes(playlistPrivacy)) {
+    throw new Error(`Unsupported playlist privacy '${playlistPrivacy}'. Use private or public.`);
+  }
+
+  const listResponse = await fetchImpl(`${YOUTUBE_API_BASE}/playlists?part=snippet,status&mine=true&maxResults=50`, {
+    headers: { Authorization: `Bearer ${accessToken}` },
+  });
+
+  if (!listResponse.ok) {
+    throw new Error(`Playlist lookup failed [${listResponse.status}]: ${await listResponse.text()}`);
+  }
+
+  const listJson = await listResponse.json();
+  const existing = listJson.items?.find((entry) => entry.snippet?.title === playlistName);
+  if (existing) return existing;
+
+  const createResponse = await fetchImpl(`${YOUTUBE_API_BASE}/playlists?part=snippet,status`, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+      'Content-Type': 'application/json; charset=UTF-8',
+    },
+    body: JSON.stringify({
+      snippet: {
+        title: playlistName,
+      },
+      status: {
+        privacyStatus: playlistPrivacy,
+      },
+    }),
+  });
+
+  if (!createResponse.ok) {
+    throw new Error(`Playlist creation failed [${createResponse.status}]: ${await createResponse.text()}`);
+  }
+
+  return createResponse.json();
+}
+
+export async function addVideoToPlaylist(options, deps = {}) {
+  const {
+    accessToken,
+    playlistId,
+    videoId,
+    fetchImpl = globalThis.fetch,
+  } = { ...options, ...deps };
+
+  if (!playlistId) return false;
+
+  const existingResponse = await fetchImpl(`${YOUTUBE_API_BASE}/playlistItems?part=snippet&playlistId=${encodeURIComponent(playlistId)}&videoId=${encodeURIComponent(videoId)}&maxResults=50`, {
+    headers: { Authorization: `Bearer ${accessToken}` },
+  });
+
+  if (!existingResponse.ok) {
+    if (existingResponse.status === 404) {
+      // Newly-created playlists may return 404 on items lookup due to propagation delay.
+      // Treat as "not in playlist" and proceed to add.
+    } else {
+      throw new Error(`Playlist item lookup failed [${existingResponse.status}]: ${await existingResponse.text()}`);
+    }
+  } else {
+    const existingJson = await existingResponse.json();
+    if (existingJson.items?.some((entry) => entry.snippet?.resourceId?.videoId === videoId)) {
+      return false;
+    }
+  }
+
+  const insertResponse = await fetchImpl(`${YOUTUBE_API_BASE}/playlistItems?part=snippet`, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+      'Content-Type': 'application/json; charset=UTF-8',
+    },
+    body: JSON.stringify({
+      snippet: {
+        playlistId,
+        resourceId: {
+          kind: 'youtube#video',
+          videoId,
+        },
+      },
+    }),
+  });
+
+  if (!insertResponse.ok) {
+    throw new Error(`Playlist insertion failed [${insertResponse.status}]: ${await insertResponse.text()}`);
+  }
+
+  await insertResponse.json();
+  return true;
+}
+
+export async function publishVideo(options, env = process.env, deps = {}) {
+  const {
+    logger = console,
+    ensureImageFilesImpl = ensureImageFiles,
+    ensureThumbnailFileImpl = ensureThumbnailFile,
+    findContentPackageImpl = findContentPackage,
+    buildYouTubeDescriptionFromContentPackageImpl = buildYouTubeDescriptionFromContentPackage,
+    resolveBackgroundAudioPathImpl = resolveBackgroundAudioPath,
+    ensureFfmpegAvailableImpl = ensureFfmpegAvailable,
+    buildSlideshowVideoImpl = buildSlideshowVideo,
+    buildGeneratedThumbnailImpl = buildGeneratedThumbnail,
+    normalizeVideoMetadataImpl = normalizeVideoMetadata,
+    exchangeRefreshTokenImpl = exchangeRefreshToken,
+    fetchOwnChannelImpl = fetchOwnChannel,
+    createResumableUploadSessionImpl = createResumableUploadSession,
+    uploadVideoBinaryImpl = uploadVideoBinary,
+    uploadThumbnailImpl = uploadThumbnail,
+    ensurePlaylistImpl = ensurePlaylist,
+    addVideoToPlaylistImpl = addVideoToPlaylist,
+    resolveBundledTransitionSoundAssetPathImpl = resolveBundledTransitionSoundAssetPath,
+    generateTransitionSoundEffectImpl = generateTransitionSoundEffect,
+  } = deps;
+
+  const {
+    images,
+    title,
+    description,
+    tags,
+    thumbnailPath,
+    categoryId,
+    privacyStatus,
+    madeForKids,
+    embeddable,
+    publicStatsViewable,
+    license,
+    publishAt,
+    defaultLanguage,
+    defaultAudioLanguage,
+    recordingDate,
+    videoOutput,
+    audioTrackPath,
+    playlistName,
+    playlistPrivacy,
+    dryRun,
+    youtubeClientIdEnv,
+    youtubeClientSecretEnv,
+    youtubeRefreshTokenEnv,
+    youtubeChannelIdEnv,
+    voiceId = ELEVEN_LABS_VOICE_ID,
+    titleVoiceId = DEFAULT_TITLE_VOICE_ID,
+    narration = true,
+    prebuiltNarrationAudioPath = '',
+    prebuiltSlideDurations = null,
+  } = options;
+
+  if (!images.length) throw new Error('--images is required');
+  if (!title) throw new Error('--title is required');
+  if (!['private', 'public', 'unlisted'].includes(privacyStatus)) {
+    throw new Error(`Unsupported privacy status '${privacyStatus}'. Use private, public or unlisted.`);
+  }
+
+  let contentPackagePath = null;
+  let resolvedDescription = String(description || '').trim();
+
+  if (!resolvedDescription || narration !== false) {
+    contentPackagePath = await findContentPackageImpl(images);
+  }
+
+  if (contentPackagePath) {
+    resolvedDescription = await buildYouTubeDescriptionFromContentPackageImpl(contentPackagePath, resolvedDescription);
+  }
+
+  if (!resolvedDescription) {
+    throw new Error('--description is required or content-package.md must provide a usable Legenda section');
+  }
+
+  const metadata = normalizeVideoMetadataImpl({
+    title,
+    description: resolvedDescription,
+    tags,
+    categoryId,
+    privacyStatus,
+    madeForKids,
+    embeddable,
+    publicStatsViewable,
+    license,
+    publishAt,
+    defaultLanguage,
+    defaultAudioLanguage,
+    recordingDate,
+  });
+
+  const configuredEnv = resolveConfiguredEnv(env, {
+    youtubeClientIdEnv,
+    youtubeClientSecretEnv,
+    youtubeRefreshTokenEnv,
+    youtubeChannelIdEnv,
+  });
+
+  const {
+    youtubeClientIdKey,
+    youtubeClientSecretKey,
+    youtubeRefreshTokenKey,
+    youtubeChannelIdKey,
+    youtubeClientId,
+    youtubeClientSecret,
+    youtubeRefreshToken,
+    youtubeChannelId,
+  } = configuredEnv;
+
+  if (!youtubeClientId) throw new Error(`${youtubeClientIdKey} is not set in environment`);
+  if (!youtubeClientSecret) throw new Error(`${youtubeClientSecretKey} is not set in environment`);
+  if (!youtubeRefreshToken) throw new Error(`${youtubeRefreshTokenKey} is not set in environment`);
+  if (!youtubeChannelId) throw new Error(`${youtubeChannelIdKey} is not set in environment`);
+
+  logger.log(`📁 Validating ${images.length} image(s)...`);
+  await ensureImageFilesImpl(images);
+
+  let resolvedThumbnailPath = null;
+  if (thumbnailPath) {
+    logger.log('🖼️ Validating thumbnail...');
+    resolvedThumbnailPath = await ensureThumbnailFileImpl(thumbnailPath);
+  }
+
+  logger.log('🎬 Validating ffmpeg...');
+  const ffmpegCommand = await ensureFfmpegAvailableImpl();
+
+  const resolvedAudioTrackPath = await resolveBackgroundAudioPathImpl(audioTrackPath);
+  if (resolvedAudioTrackPath) {
+    logger.log(`🎵 Using background audio: ${resolvedAudioTrackPath}`);
+  }
+
+  if (!resolvedThumbnailPath) {
+    logger.log('🖼️ Generating thumbnail from the first slide...');
+    const generatedThumbnailPath = await buildGeneratedThumbnailImpl({
+      sourceImagePath: images[Math.min(1, images.length - 1)],
+      videoOutput,
+    }, { ffmpegCommand });
+    resolvedThumbnailPath = await ensureThumbnailFileImpl(generatedThumbnailPath);
+  }
+
+  let tempAudioDir = null;
+  let narrationAudioPath = null;
+  let transitionSoundPath = null;
+  let slideDurations = null;
+  const elevenLabsApiKey = env.ELEVEN_LABS_API;
+  const narrationArtifactsDir = resolveNarrationArtifactsDir(images);
+
+  if (prebuiltNarrationAudioPath) {
+    logger.log(`🎙️ Reusing prebuilt narration: ${prebuiltNarrationAudioPath}`);
+    narrationAudioPath = prebuiltNarrationAudioPath;
+    slideDurations = prebuiltSlideDurations || null;
+    if (!slideDurations) {
+      logger.log('⚠️ --slide-durations not provided with --narration-audio. Slide timing will be auto-computed from the narration file durations via ffprobe.');
+    }
+  } else if (narration !== false) {
+    if (!elevenLabsApiKey) {
+      throw new Error('ELEVEN_LABS_API key is not set in the environment, but narration is enabled by default. Use --no-narration if you want to skip narration.');
+    }
+    logger.log('🎙️ Generating narration track...');
+    try {
+      if (contentPackagePath) {
+        logger.log(`📄 Found content-package: ${contentPackagePath}`);
+        tempAudioDir = await mkdtemp(join(tmpdir(), 'opensquad-tts-'));
+        const narrationResult = await buildNarrationTrack(
+          images,
+          contentPackagePath,
+          SLIDE_DURATION_SECONDS,
+          elevenLabsApiKey,
+          ffmpegCommand,
+          tempAudioDir,
+          logger,
+          spawn,
+          voiceId,
+          titleVoiceId,
+          narrationArtifactsDir
+        );
+        narrationAudioPath = narrationResult.narrationPath;
+        slideDurations = narrationResult.slideDurations;
+        logger.log(`🔊 Narration track generated: ${narrationAudioPath}`);
+        if (narrationResult.persistedNarrationPath) {
+          logger.log(`💾 Narration assets saved to: ${narrationArtifactsDir}`);
+        }
+      } else {
+        logger.log('⚠️ Could not locate content-package.md. Skipping narration.');
+      }
+    } catch (ttsErr) {
+      logger.log(`⚠️ Narration track generation failed: ${ttsErr.message}. Proceeding without narration.`);
+      narrationAudioPath = null;
+      slideDurations = null;
+    }
+  } else {
+    logger.log('ℹ️ Narration disabled via flag. Skipping slide narration.');
+    if (prebuiltSlideDurations) {
+      slideDurations = prebuiltSlideDurations;
+    }
+  }
+
+  if (images.length > 1) {
+    try {
+      const bundledTransitionSoundPath = await resolveBundledTransitionSoundAssetPathImpl();
+      if (bundledTransitionSoundPath) {
+        transitionSoundPath = bundledTransitionSoundPath;
+        logger.log(`🎵 Using bundled slide transition sound: ${bundledTransitionSoundPath}`);
+        if (narrationArtifactsDir) {
+          try {
+            await mkdir(resolve(narrationArtifactsDir), { recursive: true });
+            await copyFile(resolve(bundledTransitionSoundPath), join(resolve(narrationArtifactsDir), 'slide-transition-sfx.mp3'));
+            logger.log(`💾 Slide transition sound saved to: ${narrationArtifactsDir}`);
+          } catch (persistErr) {
+            logger.log(`⚠️ Failed to persist bundled slide transition sound: ${persistErr.message}`);
+          }
+        }
+      } else {
+        if (!elevenLabsApiKey) {
+          throw new Error('ELEVEN_LABS_API key not available and no bundled transition sound asset was found');
+        }
+        if (!tempAudioDir) {
+          tempAudioDir = await mkdtemp(join(tmpdir(), 'opensquad-tts-'));
+        }
+        const transitionSoundResult = await generateTransitionSoundEffectImpl({
+          apiKey: elevenLabsApiKey,
+          tempDir: tempAudioDir,
+          logger,
+          durationSeconds: SLIDE_TRANSITION_DURATION_SECONDS,
+          artifactsDir: narrationArtifactsDir,
+        });
+        transitionSoundPath = transitionSoundResult.soundPath;
+        if (transitionSoundResult.persistedSoundPath) {
+          logger.log(`💾 Slide transition sound saved to: ${narrationArtifactsDir}`);
+        }
+      }
+    } catch (transitionErr) {
+      logger.log(`⚠️ Slide transition sound generation failed: ${transitionErr.message}. Proceeding without transition SFX.`);
+      transitionSoundPath = null;
+    }
+  }
+
+  let generatedVideoPath;
+  try {
+    logger.log('🧱 Building slideshow video...');
+    generatedVideoPath = await buildSlideshowVideoImpl({
+      images,
+      videoOutput,
+      slideDurationSeconds: SLIDE_DURATION_SECONDS,
+      backgroundAudioPath: resolvedAudioTrackPath,
+      narrationAudioPath,
+      slideDurations,
+      transitionDurationSeconds: images.length > 1 ? SLIDE_TRANSITION_DURATION_SECONDS : 0,
+      transitionSoundPath,
+    }, { ffmpegCommand });
+    logger.log(`   Video: ${generatedVideoPath}`);
+  } finally {
+    if (tempAudioDir) {
+      try {
+        await rm(tempAudioDir, { recursive: true, force: true });
+      } catch (rmErr) {
+        logger.log(`⚠️ Failed to clean up temp audio directory: ${rmErr.message}`);
+      }
+    }
+  }
+
+  logger.log('🔐 Refreshing YouTube OAuth token...');
+  const accessToken = await exchangeRefreshTokenImpl({
+    clientId: youtubeClientId,
+    clientSecret: youtubeClientSecret,
+    refreshToken: youtubeRefreshToken,
+  });
+
+  logger.log('📺 Validating channel access...');
+  const channel = await fetchOwnChannelImpl(accessToken, youtubeChannelId);
+
+  const result = {
+    status: dryRun ? 'dry-run' : 'published',
+    youtubeVideoId: null,
+    youtubeUrl: null,
+    generatedVideoPath,
+    thumbnailPath: resolvedThumbnailPath,
+    thumbnailUploaded: false,
+    thumbnailUploadError: null,
+    channelId: channel.id,
+    channelTitle: channel.snippet?.title ?? null,
+    playlistId: null,
+    playlistName: playlistName || null,
+    playlistAssigned: false,
+    metadata,
+    scope: YOUTUBE_OAUTH_SCOPES,
+  };
+
+  if (dryRun) {
+    logger.log('✅ DRY RUN complete — upload skipped intentionally.');
+    return result;
+  }
+
+  logger.log('☁️ Creating resumable upload session...');
+  const uploadUrl = await createResumableUploadSessionImpl({
+    accessToken,
+    metadata,
+  });
+
+  logger.log('🚀 Uploading video to YouTube...');
+  const uploadResult = await uploadVideoBinaryImpl({
+    uploadUrl,
+    videoPath: generatedVideoPath,
+  });
+
+  result.youtubeVideoId = uploadResult.id;
+  result.youtubeUrl = `https://www.youtube.com/watch?v=${uploadResult.id}`;
+
+  if (resolvedThumbnailPath) {
+    logger.log('🖼️ Uploading thumbnail...');
+    try {
+      await uploadThumbnailImpl({
+        accessToken,
+        videoId: uploadResult.id,
+        thumbnailPath: resolvedThumbnailPath,
+      });
+      result.thumbnailUploaded = true;
+    } catch (error) {
+      result.thumbnailUploadError = error.message;
+      logger.log(`⚠️ Thumbnail upload skipped: ${error.message}`);
+    }
+  }
+
+  if (playlistName) {
+    logger.log(`📚 Ensuring playlist '${playlistName}'...`);
+    const playlist = await ensurePlaylistImpl({
+      accessToken,
+      playlistName,
+      playlistPrivacy,
+    });
+    result.playlistId = playlist.id;
+    result.playlistName = playlist.snippet?.title ?? playlistName;
+
+    logger.log('➕ Adding video to playlist...');
+    result.playlistAssigned = await addVideoToPlaylistImpl({
+      accessToken,
+      playlistId: playlist.id,
+      videoId: uploadResult.id,
+    });
+  }
+
+  logger.log(`✅ YouTube: Published successfully (${result.youtubeUrl})`);
+  return result;
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  if (args.deleteOnly || args.deleteVideoId) {
+    await deleteVideo(args);
+    return;
+  }
+
+  await publishVideo(args);
+}
+
+const isMain = process.argv[1] === fileURLToPath(import.meta.url);
+if (isMain) {
+  main().catch((error) => {
+    console.error(`\n❌ ${error.message}`);
+    process.exit(1);
+  });
+}