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

package/src/media/resolve.js

@@ -0,0 +1,476 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import pc from 'picocolors';
+import { searchMedia } from '../providers/index.js';
+import { rankCandidates, selectBest } from './select.js';
+import { downloadAsset } from './download.js';
+import { composeVideo, getMediaDuration } from './compose.js';
+import {
+  readUsedAssetsLedger,
+  recordUsedAsset,
+  DEFAULT_MEDIA_CACHE_DIR,
+} from './cache.js';
+
+/**
+ * Derive a clean, concise search query from metadata fields.
+ *
+ * @param {object} item
+ * @param {string} [item.title]
+ * @param {string[]} [item.tags]
+ * @param {string} [item.artist]
+ * @param {object} [item.album]
+ * @param {string} [item.filename]
+ * @returns {string}
+ */
+export function deriveSearchQuery(item = {}) {
+  let combined = '';
+  if (item.title) combined += ' ' + item.title;
+  if (Array.isArray(item.tags)) combined += ' ' + item.tags.join(' ');
+  if (item.album?.title) combined += ' ' + item.album.title;
+  if (item.artist) combined += ' ' + item.artist;
+  if (!combined.trim() && item.filename) {
+    combined = path.basename(item.filename, path.extname(item.filename));
+  }
+
+  const stopWords = new Set(['the', 'and', 'for', 'with', 'feat', 'ft', 'official', 'audio', 'video', 'music', 'track', 'version', 'mix']);
+  const words = combined
+    .toLowerCase()
+    .replace(/[^\w\s-]/g, ' ')
+    .split(/\s+/)
+    .filter(w => w.length > 2 && !/^\d+$/.test(w) && !stopWords.has(w));
+
+  const uniqueWords = [...new Set(words)];
+  return uniqueWords.slice(0, 8).join(' ') || (item.title || 'ambient nature');
+}
+
+/**
+ * Generate human-readable credit line for an asset.
+ *
+ * @param {import('../providers/index.js').UnifiedResult} asset
+ * @returns {string}
+ */
+export function formatMediaCredit(asset) {
+  const creatorName = asset.creator?.name || 'Creator';
+  const providerName = asset.provider === 'pexels' ? 'Pexels' : 'Pixabay';
+  const mediaType = asset.type === 'video' ? 'Video' : 'Photo';
+  return `${mediaType} by ${creatorName} on ${providerName}`;
+}
+
+/**
+ * Generate or update ATTRIBUTIONS.md in the target folder.
+ *
+ * @param {string} targetDir
+ * @param {Array<{ songKey: string, resolvedMedia: object }>} resolvedItems
+ */
+export function writeAttributionsFile(targetDir, resolvedItems) {
+  if (!resolvedItems || resolvedItems.length === 0) return;
+
+  const attributionsPath = path.join(targetDir, 'ATTRIBUTIONS.md');
+  const lines = [
+    '# Stock Media Attributions',
+    '',
+    'This project uses stock media from Pexels and Pixabay under their respective licenses.',
+    '',
+    '| Song / Item | Provider | Asset ID | Creator | License | Link |',
+    '|---|---|---|---|---|---|',
+  ];
+
+  for (const item of resolvedItems) {
+    const rm = item.resolvedMedia;
+    if (!rm) continue;
+    const songName = item.songKey || 'Item';
+    const creator = rm.creator?.name || (rm.credit ? rm.credit.replace(/^.* by (.*) on .*$/, '$1') : 'Creator');
+    lines.push(
+      `| \`${songName}\` | ${rm.provider} | ${rm.assetId} | ${creator} | ${rm.license} | [View Asset](${rm.pageUrl}) |`
+    );
+  }
+
+  lines.push('');
+  fs.writeFileSync(attributionsPath, lines.join('\n'), 'utf-8');
+}
+
+/**
+ * Find local audio file for a given song key or file entry.
+ *
+ * @param {string} targetDir
+ * @param {string} key
+ * @returns {string | null}
+ */
+function findAudioFile(targetDir, key) {
+  const directPath = path.isAbsolute(key) ? key : path.join(targetDir, key);
+  const ext = path.extname(directPath).toLowerCase();
+  if (['.wav', '.mp3', '.m4a', '.flac', '.aac', '.ogg'].includes(ext) && fs.existsSync(directPath)) {
+    return directPath;
+  }
+
+  // Check same basename with audio extensions
+  const baseName = path.basename(key, ext);
+  const audioExtensions = ['.wav', '.mp3', '.m4a', '.flac', '.aac', '.ogg'];
+  for (const aExt of audioExtensions) {
+    const candidate = path.join(targetDir, baseName + aExt);
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Orchestrate media resolution for a metadata.json file.
+ *
+ * @param {string} metadataFilePathOrDir
+ * @param {object} [options]
+ * @param {boolean} [options.compose=false]
+ * @param {boolean} [options.force=false]
+ * @param {boolean} [options.dryRun=false]
+ * @param {boolean} [options.allowRepeatMedia=false]
+ * @param {string} [options.provider]
+ * @param {'video' | 'photo'} [options.type]
+ * @param {'landscape' | 'portrait' | 'square'} [options.orientation]
+ * @param {string} [options.cacheDir]
+ * @param {string} [options.pexelsKey]
+ * @param {string} [options.pixabayKey]
+ * @param {(event: object) => void} [options.onEvent]
+ * @returns {Promise<{
+ *   resolved: Array<{ songKey: string, resolvedMedia: object, generatedVideoPath?: string }>,
+ *   skipped: Array<{ songKey: string, reason: string }>,
+ *   errors: Array<{ songKey: string, error: string }>
+ * }>}
+ */
+export async function resolveMediaForMetadata(metadataFilePathOrDir, options = {}) {
+  const inputPath = path.resolve(metadataFilePathOrDir || process.cwd());
+  const stat = fs.existsSync(inputPath) ? fs.statSync(inputPath) : null;
+
+  let metadataPath = inputPath;
+  let targetDir = inputPath;
+
+  if (stat && stat.isDirectory()) {
+    metadataPath = path.join(inputPath, 'metadata.json');
+    targetDir = inputPath;
+  } else {
+    targetDir = path.dirname(inputPath);
+  }
+
+  if (!fs.existsSync(metadataPath)) {
+    throw new Error(`Metadata file not found: ${metadataPath}`);
+  }
+
+  const rawConfig = JSON.parse(fs.readFileSync(metadataPath, 'utf-8'));
+  const mediaPolicy = rawConfig.mediaPolicy || {};
+  const cacheDir = path.resolve(targetDir, options.cacheDir || mediaPolicy.cacheDir || DEFAULT_MEDIA_CACHE_DIR);
+
+  const defaultProvider = options.provider || mediaPolicy.provider || 'auto';
+  const defaultType = options.type || mediaPolicy.type || 'video';
+  const defaultOrientation = options.orientation || mediaPolicy.orientation || 'landscape';
+  const defaultAvoidReuse = options.allowRepeatMedia ? false : (mediaPolicy.avoidReuse !== false);
+  const defaultMergeStrategy = mediaPolicy.mergeStrategy || 'fallback';
+  const defaultProviderOrder = mediaPolicy.providerOrder || ['pexels', 'pixabay'];
+  const minWidth = mediaPolicy.minWidth || 1280;
+  const minHeight = mediaPolicy.minHeight || 720;
+  const safeSearch = mediaPolicy.safeSearch !== false;
+  const composeMode = mediaPolicy.composeMode || 'video-loop';
+
+  const usedLedger = readUsedAssetsLedger(cacheDir);
+  const inMemoryUsedSet = new Set(Object.keys(usedLedger));
+
+  const resolved = [];
+  const skipped = [];
+  const errors = [];
+  const allResolvedForAttributions = [];
+
+  const emit = (event) => {
+    if (typeof options.onEvent === 'function') {
+      options.onEvent(event);
+    }
+  };
+
+  // Determine items to process: rich `songs` schema or flat `videos` array
+  const isSongsSchema = Boolean(rawConfig.songs && typeof rawConfig.songs === 'object' && !Array.isArray(rawConfig.songs));
+  const itemsToProcess = [];
+
+  if (isSongsSchema) {
+    const keys = Array.isArray(rawConfig.playlist?.orderedSongKeys)
+      ? rawConfig.playlist.orderedSongKeys
+      : Object.keys(rawConfig.songs);
+    for (const key of keys) {
+      if (rawConfig.songs[key]) {
+        itemsToProcess.push({ key, data: rawConfig.songs[key], isSong: true });
+      }
+    }
+    // Any remaining songs
+    for (const [key, data] of Object.entries(rawConfig.songs)) {
+      if (!itemsToProcess.some(i => i.key === key)) {
+        itemsToProcess.push({ key, data, isSong: true });
+      }
+    }
+  } else if (Array.isArray(rawConfig.videos)) {
+    rawConfig.videos.forEach((vid, idx) => {
+      itemsToProcess.push({ key: vid.filename || `video_${idx}`, data: vid, isSong: false, index: idx });
+    });
+  }
+
+  for (const item of itemsToProcess) {
+    const songKey = item.key;
+    const songData = item.data;
+    const existingResolved = songData.resolvedMedia;
+
+    // Check if existing file is already a valid .mp4 on disk
+    const filename = songData.filename || songKey;
+    const absoluteVideoPath = path.isAbsolute(filename) ? filename : path.join(targetDir, filename);
+    const hasExistingVideo = fs.existsSync(absoluteVideoPath) && absoluteVideoPath.endsWith('.mp4');
+
+    if (existingResolved && !options.force) {
+      skipped.push({ songKey, reason: 'Already has resolvedMedia' });
+      emit({ type: 'item_skipped', songKey, reason: 'Already resolved' });
+      allResolvedForAttributions.push({ songKey, resolvedMedia: existingResolved });
+      continue;
+    }
+
+    if (hasExistingVideo && !songData.media?.autoResolve && !options.force && !songData.autoResolve) {
+      skipped.push({ songKey, reason: 'Existing local video file already present' });
+      emit({ type: 'item_skipped', songKey, reason: 'Existing video on disk' });
+      continue;
+    }
+
+    const itemMediaConfig = songData.media || {};
+    const itemQuery = itemMediaConfig.query || deriveSearchQuery({
+      title: songData.youtube?.snippet?.title || songData.title || songKey,
+      tags: songData.youtube?.snippet?.tags || songData.tags,
+      artist: rawConfig.album?.artist || rawConfig.artist,
+      album: rawConfig.album,
+      filename: songKey,
+    });
+
+    const itemType = itemMediaConfig.type || defaultType;
+    const itemOrientation = itemMediaConfig.orientation || defaultOrientation;
+    const itemProvider = itemMediaConfig.provider || defaultProvider;
+
+    // Check audio duration if local audio file exists
+    let audioDuration = undefined;
+    const audioFilePath = findAudioFile(targetDir, songKey);
+    if (audioFilePath) {
+      try {
+        audioDuration = await getMediaDuration(audioFilePath);
+      } catch {}
+    }
+
+    emit({
+      type: 'search_start',
+      songKey,
+      query: itemQuery,
+      provider: itemProvider,
+      mediaType: itemType,
+    });
+
+    let searchResults = [];
+    try {
+      searchResults = await searchMedia({
+        query: itemQuery,
+        type: itemType,
+        orientation: itemOrientation,
+        provider: itemProvider,
+        mergeStrategy: defaultMergeStrategy,
+        providerOrder: defaultProviderOrder,
+        safeSearch,
+        cacheDir,
+        pexelsKey: options.pexelsKey,
+        pixabayKey: options.pixabayKey,
+      });
+
+      // If no results, retry with broadened query (drop last word)
+      if (searchResults.length === 0 && itemQuery.includes(' ')) {
+        const shortened = itemQuery.split(' ').slice(0, -1).join(' ');
+        if (shortened.trim()) {
+          searchResults = await searchMedia({
+            query: shortened,
+            type: itemType,
+            orientation: itemOrientation,
+            provider: itemProvider,
+            mergeStrategy: defaultMergeStrategy,
+            providerOrder: defaultProviderOrder,
+            safeSearch,
+            cacheDir,
+            pexelsKey: options.pexelsKey,
+            pixabayKey: options.pixabayKey,
+          });
+        }
+      }
+    } catch (err) {
+      errors.push({ songKey, error: `Search failed: ${err.message}` });
+      emit({ type: 'item_error', songKey, error: err.message });
+      songData.needsManualReview = true;
+      continue;
+    }
+
+    if (searchResults.length === 0) {
+      errors.push({ songKey, error: `No stock media found for query: "${itemQuery}"` });
+      emit({ type: 'item_error', songKey, error: `No results for "${itemQuery}"` });
+      songData.needsManualReview = true;
+      continue;
+    }
+
+    const rankingCriteria = {
+      orientation: itemOrientation,
+      targetDuration: audioDuration,
+      minWidth,
+      minHeight,
+      avoidReuse: defaultAvoidReuse,
+      cacheDir,
+      usedAssetSet: inMemoryUsedSet,
+      providerOrder: defaultProviderOrder,
+    };
+
+    const ranked = rankCandidates(searchResults, rankingCriteria);
+    if (ranked.length === 0) {
+      errors.push({ songKey, error: 'All search candidates were filtered out by criteria or reuse policy.' });
+      emit({ type: 'item_error', songKey, error: 'All candidates excluded' });
+      songData.needsManualReview = true;
+      continue;
+    }
+
+    emit({
+      type: 'search_results',
+      songKey,
+      totalFound: searchResults.length,
+      topCandidate: ranked[0].candidate,
+      score: ranked[0].score,
+    });
+
+    if (options.dryRun) {
+      const top = ranked[0].candidate;
+      const credit = formatMediaCredit(top);
+      resolved.push({
+        songKey,
+        resolvedMedia: {
+          provider: top.provider,
+          assetId: top.id,
+          type: top.type,
+          pageUrl: top.pageUrl,
+          localPath: `.media-cache/assets/${top.provider}-${top.id}.${top.type === 'video' ? 'mp4' : 'jpg'}`,
+          width: top.width,
+          height: top.height,
+          duration: top.duration,
+          license: top.license,
+          credit,
+          resolvedAt: new Date().toISOString(),
+        },
+      });
+      continue;
+    }
+
+    // Try downloading candidates in ranked order until one succeeds
+    let downloadedAsset = null;
+    let winner = null;
+    for (const itemRanked of ranked) {
+      const candidate = itemRanked.candidate;
+      try {
+        emit({ type: 'download_start', songKey, assetId: candidate.id, provider: candidate.provider });
+        const downloadRes = await downloadAsset(candidate, { cacheDir });
+        downloadedAsset = downloadRes;
+        winner = candidate;
+        emit({ type: 'download_success', songKey, localPath: downloadRes.localPath });
+        break;
+      } catch (dlErr) {
+        // Try next candidate
+      }
+    }
+
+    if (!downloadedAsset || !winner) {
+      errors.push({ songKey, error: 'Failed to download any candidate asset.' });
+      emit({ type: 'item_error', songKey, error: 'Download failed for all candidates' });
+      songData.needsManualReview = true;
+      continue;
+    }
+
+    // Mark asset used in memory & ledger
+    const assetKey = `${winner.provider}:${winner.id}`;
+    inMemoryUsedSet.add(assetKey);
+    recordUsedAsset(cacheDir, {
+      provider: winner.provider,
+      assetId: winner.id,
+      songKey,
+    });
+
+    const credit = formatMediaCredit(winner);
+    const resolvedRecord = {
+      provider: winner.provider,
+      assetId: winner.id,
+      type: winner.type,
+      pageUrl: winner.pageUrl,
+      localPath: path.relative(targetDir, downloadedAsset.localPath),
+      width: winner.width,
+      height: winner.height,
+      duration: winner.duration,
+      license: winner.license,
+      credit,
+      resolvedAt: new Date().toISOString(),
+    };
+
+    let generatedVideoPath = undefined;
+    const shouldCompose = options.compose || Boolean(options.autoMedia);
+
+    if (shouldCompose) {
+      if (!audioFilePath) {
+        errors.push({ songKey, error: `Cannot compose video: audio file not found for ${songKey}` });
+        emit({ type: 'item_error', songKey, error: `Audio file not found for ${songKey}` });
+      } else {
+        const baseName = path.basename(songKey, path.extname(songKey));
+        const outName = `${baseName}.generated.mp4`;
+        const outputPath = path.join(targetDir, outName);
+
+        emit({ type: 'compose_start', songKey, audioFile: audioFilePath, background: downloadedAsset.localPath });
+        try {
+          const compResult = await composeVideo({
+            backgroundPath: downloadedAsset.localPath,
+            audioPath: audioFilePath,
+            outputPath,
+            mode: winner.type === 'photo' ? 'ken-burns' : composeMode,
+            targetWidth: 1920,
+            targetHeight: 1080,
+          });
+          generatedVideoPath = compResult.outputPath;
+          emit({ type: 'compose_success', songKey, outputPath });
+
+          // Update song filename in metadata to point to generated video
+          if (item.isSong) {
+            // Update filename if present or store generated path
+            songData.filename = outName;
+          } else {
+            songData.filename = outName;
+          }
+        } catch (composeErr) {
+          errors.push({ songKey, error: `Composition failed: ${composeErr.message}` });
+          emit({ type: 'item_error', songKey, error: `Composition failed: ${composeErr.message}` });
+        }
+      }
+    }
+
+    songData.resolvedMedia = resolvedRecord;
+    delete songData.needsManualReview;
+
+    resolved.push({
+      songKey,
+      resolvedMedia: resolvedRecord,
+      generatedVideoPath,
+    });
+    allResolvedForAttributions.push({
+      songKey,
+      resolvedMedia: resolvedRecord,
+    });
+
+    emit({ type: 'item_resolved', songKey, resolvedMedia: resolvedRecord });
+  }
+
+  // Save metadata.json if not dryRun
+  if (!options.dryRun && resolved.length > 0) {
+    fs.writeFileSync(metadataPath, JSON.stringify(rawConfig, null, 2), 'utf-8');
+    writeAttributionsFile(targetDir, allResolvedForAttributions);
+  }
+
+  return {
+    resolved,
+    skipped,
+    errors,
+  };
+}

package/src/media/select.js

@@ -0,0 +1,176 @@
+import { isAssetUsed, DEFAULT_MEDIA_CACHE_DIR } from './cache.js';
+
+/**
+ * Calculate candidate score breakdown and weighted total score.
+ *
+ * @param {import('../providers/index.js').UnifiedResult} candidate
+ * @param {object} criteria
+ * @returns {{ score: number, breakdown: { rank: number, resolution: number, orientation: number, duration: number, novelty: number } }}
+ */
+export function scoreCandidate(candidate, criteria = {}) {
+  const {
+    preferredWidth = 1920,
+    preferredHeight = 1080,
+    minWidth = 1280,
+    minHeight = 720,
+    orientation = 'landscape',
+    targetDuration,
+    cacheDir = DEFAULT_MEDIA_CACHE_DIR,
+    usedAssetSet,
+  } = criteria;
+
+  // 1. Provider Relevance Rank (weight 0.40)
+  const rank = typeof candidate.rank === 'number' ? candidate.rank : 0;
+  const rankScore = 1 / (1 + rank);
+
+  // 2. Resolution (weight 0.20)
+  const preferredArea = preferredWidth * preferredHeight;
+  const minArea = minWidth * minHeight;
+  const candidateArea = (candidate.width || 0) * (candidate.height || 0);
+
+  let resolutionScore = 1.0;
+  if (candidateArea >= preferredArea) {
+    resolutionScore = 1.0;
+  } else if (candidateArea <= minArea) {
+    resolutionScore = 0.0;
+  } else if (preferredArea > minArea) {
+    resolutionScore = (candidateArea - minArea) / (preferredArea - minArea);
+  }
+
+  // 3. Orientation Match (weight 0.15)
+  let orientationScore = 0.0;
+  if (candidate.orientation === orientation) {
+    orientationScore = 1.0;
+  } else if (candidate.orientation === 'square' || orientation === 'square') {
+    orientationScore = 0.3;
+  } else {
+    orientationScore = 0.0;
+  }
+
+  // 4. Duration Fit (weight 0.20) - Video only
+  let durationScore = 1.0;
+  if (candidate.type === 'video' && targetDuration && typeof candidate.duration === 'number') {
+    const dur = candidate.duration;
+    if (dur >= targetDuration && dur <= targetDuration * 1.5) {
+      durationScore = 1.0;
+    } else if (dur < targetDuration) {
+      durationScore = Math.max(0, dur / targetDuration);
+    } else {
+      // dur > targetDuration * 1.5
+      const overflow = dur - (targetDuration * 1.5);
+      durationScore = Math.max(0, 1 - (overflow / (targetDuration * 3)));
+    }
+  }
+
+  // 5. Novelty (weight 0.05)
+  let noveltyScore = 1.0;
+  const isUsed = usedAssetSet
+    ? usedAssetSet.has(`${candidate.provider}:${candidate.id}`)
+    : isAssetUsed(cacheDir, candidate.provider, candidate.id);
+
+  if (isUsed) {
+    noveltyScore = 0.0;
+  }
+
+  const totalScore = Math.round((
+    0.40 * rankScore +
+    0.20 * resolutionScore +
+    0.15 * orientationScore +
+    0.20 * durationScore +
+    0.05 * noveltyScore
+  ) * 1e6) / 1e6;
+
+  return {
+    score: totalScore,
+    breakdown: {
+      rank: Math.round(rankScore * 1e6) / 1e6,
+      resolution: Math.round(resolutionScore * 1e6) / 1e6,
+      orientation: Math.round(orientationScore * 1e6) / 1e6,
+      duration: Math.round(durationScore * 1e6) / 1e6,
+      novelty: Math.round(noveltyScore * 1e6) / 1e6,
+    },
+  };
+}
+
+/**
+ * Filter and rank all candidate media results.
+ *
+ * @param {import('../providers/index.js').UnifiedResult[]} results
+ * @param {object} criteria
+ * @returns {Array<{ candidate: import('../providers/index.js').UnifiedResult, score: number, breakdown: any }>}
+ */
+export function rankCandidates(results = [], criteria = {}) {
+  const {
+    avoidReuse = true,
+    cacheDir = DEFAULT_MEDIA_CACHE_DIR,
+    usedAssetSet,
+    minDuration,
+    maxDuration,
+    minWidth,
+    minHeight,
+    providerOrder = ['pexels', 'pixabay'],
+  } = criteria;
+
+  // Filter candidates
+  const filtered = results.filter((candidate) => {
+    if (!candidate || !candidate.id) return false;
+
+    // Novelty hard exclusion
+    if (avoidReuse) {
+      const isUsed = usedAssetSet
+        ? usedAssetSet.has(`${candidate.provider}:${candidate.id}`)
+        : isAssetUsed(cacheDir, candidate.provider, candidate.id);
+      if (isUsed) return false;
+    }
+
+    // Min dimensions check
+    if (minWidth && candidate.width && candidate.width < minWidth) return false;
+    if (minHeight && candidate.height && candidate.height < minHeight) return false;
+
+    // Min/Max duration check for video
+    if (candidate.type === 'video' && typeof candidate.duration === 'number') {
+      if (minDuration && candidate.duration < minDuration) return false;
+      if (maxDuration && candidate.duration > maxDuration) return false;
+    }
+
+    return true;
+  });
+
+  const scored = filtered.map((candidate) => {
+    const { score, breakdown } = scoreCandidate(candidate, criteria);
+    return { candidate, score, breakdown };
+  });
+
+  // Sort descending by score, tie-break with providerOrder and original rank
+  scored.sort((a, b) => {
+    const scoreDiff = b.score - a.score;
+    if (Math.abs(scoreDiff) > 0.0001) {
+      return scoreDiff;
+    }
+
+    const provIndexA = providerOrder.indexOf(a.candidate.provider);
+    const provIndexB = providerOrder.indexOf(b.candidate.provider);
+    const resolvedProvA = provIndexA === -1 ? 99 : provIndexA;
+    const resolvedProvB = provIndexB === -1 ? 99 : provIndexB;
+
+    if (resolvedProvA !== resolvedProvB) {
+      return resolvedProvA - resolvedProvB;
+    }
+
+    return (a.candidate.rank ?? 0) - (b.candidate.rank ?? 0);
+  });
+
+  return scored;
+}
+
+/**
+ * Select the single best matching candidate.
+ *
+ * @param {import('../providers/index.js').UnifiedResult[]} results
+ * @param {object} criteria
+ * @returns {import('../providers/index.js').UnifiedResult | null}
+ */
+export function selectBest(results = [], criteria = {}) {
+  const ranked = rankCandidates(results, criteria);
+  return ranked.length > 0 ? ranked[0].candidate : null;
+}