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

package/src/actions/replace-background.js

@@ -0,0 +1,192 @@
+import ffmpeg from 'fluent-ffmpeg';
+import ffmpegStatic from 'ffmpeg-static';
+import ffprobeStatic from 'ffprobe-static';
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  searchMedia,
+  selectBest,
+  downloadAsset,
+  composeVideo,
+  deriveSearchQuery,
+  getMediaDuration,
+} from '../index.js';
+
+if (ffmpegStatic && fs.existsSync(ffmpegStatic)) {
+  ffmpeg.setFfmpegPath(ffmpegStatic);
+}
+if (ffprobeStatic?.path && fs.existsSync(ffprobeStatic.path)) {
+  ffmpeg.setFfprobePath(ffprobeStatic.path);
+}
+
+/**
+ * Find companion file with matching stem and target extension.
+ *
+ * @param {string} sourcePath
+ * @param {string} ext
+ * @returns {string | null}
+ */
+export function findCompanionFile(sourcePath, ext) {
+  if (!sourcePath) return null;
+  const dir = path.dirname(sourcePath);
+  const stem = path.basename(sourcePath, path.extname(sourcePath)).trim().toLowerCase();
+  const direct = path.join(dir, `${path.basename(sourcePath, path.extname(sourcePath))}.${ext}`);
+  if (fs.existsSync(direct)) return direct;
+  if (fs.existsSync(dir)) {
+    try {
+      const files = fs.readdirSync(dir);
+      const match = files.find(f => f.toLowerCase().endsWith('.' + ext.toLowerCase()) && path.basename(f, path.extname(f)).trim().toLowerCase() === stem);
+      if (match) return path.join(dir, match);
+    } catch {
+      // ignore
+    }
+  }
+  return null;
+}
+
+/**
+ * Extract audio track from a video file.
+ *
+ * @param {string} inputVideoPath
+ * @param {string} outputAudioPath
+ * @returns {Promise<string>}
+ */
+export function extractAudio(inputVideoPath, outputAudioPath) {
+  if (!fs.existsSync(inputVideoPath)) {
+    throw new Error(`Input video file not found: ${inputVideoPath}`);
+  }
+
+  fs.mkdirSync(path.dirname(path.resolve(outputAudioPath)), { recursive: true });
+
+  return new Promise((resolve, reject) => {
+    ffmpeg(inputVideoPath)
+      .noVideo()
+      .audioCodec('copy')
+      .outputOptions(['-movflags', '+faststart'])
+      .output(outputAudioPath)
+      .on('end', () => resolve(outputAudioPath))
+      .on('error', () => {
+        // Fallback to high-bitrate AAC if copy is not container-compatible
+        ffmpeg(inputVideoPath)
+          .noVideo()
+          .audioCodec('aac')
+          .audioBitrate('320k')
+          .outputOptions(['-ar', '48000', '-movflags', '+faststart'])
+          .output(outputAudioPath)
+          .on('end', () => resolve(outputAudioPath))
+          .on('error', (err) => reject(new Error(`Failed to extract audio from ${inputVideoPath}: ${err.message}`)))
+          .run();
+      })
+      .run();
+  });
+}
+
+/**
+ * Replace the background visuals of a video while preserving its audio.
+ *
+ * @param {object} params
+ * @param {string} params.inputPath - Source video path
+ * @param {string} params.outputPath - Output video path
+ * @param {object} params.action - Action definition
+ * @param {object} [params.entry] - Entry metadata object
+ * @param {object} [params.context] - Pipeline context (keys, cacheDir, tempDir, etc.)
+ * @param {boolean} [params.dryRun=false]
+ * @returns {Promise<{ outputPath: string, duration?: number, dryRun?: boolean, command?: string, asset?: object }>}
+ */
+export async function replaceBackground(params) {
+  const {
+    inputPath,
+    outputPath,
+    action = {},
+    entry = {},
+    context = {},
+    dryRun = false,
+  } = params;
+
+  const query = action.query || entry.media?.query || entry.mediaQuery || deriveSearchQuery(entry);
+  const mediaType = action.mediaType || action.assetType || entry.media?.type || 'video';
+  const provider = action.provider || entry.media?.provider || 'auto';
+  const orientation = action.orientation || entry.media?.orientation || 'landscape';
+  const mode = action.mode || entry.media?.mode || 'video-loop';
+  const assPath = action.assPath || entry.assPath || findCompanionFile(entry.sourcePath || inputPath, 'ass');
+
+  if (dryRun) {
+    const subsNote = assPath ? ` + subtitles (${path.basename(assPath)})` : '';
+    const plan = `Replace background: query="${query}" (${provider}, ${orientation}, mode: ${mode}) + audio from ${inputPath}${subsNote} -> ${outputPath}`;
+    return {
+      outputPath,
+      dryRun: true,
+      command: plan,
+    };
+  }
+
+  const tempDir = context.tempDir || path.dirname(path.resolve(outputPath));
+  fs.mkdirSync(tempDir, { recursive: true });
+
+  const audioExt = '.m4a';
+  const extractedAudioPath = path.join(
+    tempDir,
+    `extracted_audio_${path.basename(inputPath, path.extname(inputPath))}_${Date.now()}${audioExt}`
+  );
+
+  // 1. Extract audio
+  await extractAudio(inputPath, extractedAudioPath);
+  const audioDuration = await getMediaDuration(extractedAudioPath);
+
+  // 2. Search stock media
+  const searchResults = await searchMedia({
+    query,
+    type: mediaType,
+    provider,
+    orientation,
+    safeSearch: action.safeSearch !== false,
+    pexelsKey: context.pexelsKey,
+    pixabayKey: context.pixabayKey,
+    cacheDir: context.cacheDir,
+    fetchFn: context.fetchFn,
+  });
+
+  // 3. Select best candidate
+  const winningAsset = selectBest(searchResults, {
+    targetDuration: audioDuration,
+    orientation,
+    avoidReuse: action.avoidReuse !== false,
+    cacheDir: context.cacheDir,
+  });
+
+  if (!winningAsset) {
+    throw new Error(`No suitable stock media found for query: "${query}" (provider: ${provider})`);
+  }
+
+  // 4. Download asset
+  const downloaded = await downloadAsset(winningAsset, {
+    cacheDir: context.cacheDir,
+    fetchFn: context.fetchFn,
+  });
+
+  // 5. Compose video
+  const composeResult = await composeVideo({
+    backgroundPath: downloaded.localPath,
+    audioPath: extractedAudioPath,
+    outputPath,
+    mode,
+    targetWidth: action.width || 1920,
+    targetHeight: action.height || 1080,
+    fps: action.fps || 30,
+    assPath,
+    dryRun: false,
+  });
+
+  // Clean up temporary extracted audio file
+  if (fs.existsSync(extractedAudioPath)) {
+    try {
+      fs.unlinkSync(extractedAudioPath);
+    } catch {}
+  }
+
+  return {
+    outputPath,
+    duration: composeResult.duration,
+    asset: winningAsset,
+  };
+}

package/src/actions/shorten.js

@@ -0,0 +1,310 @@
+import ffmpeg from 'fluent-ffmpeg';
+import ffmpegStatic from 'ffmpeg-static';
+import ffprobeStatic from 'ffprobe-static';
+import fs from 'node:fs';
+import path from 'node:path';
+
+if (ffmpegStatic && fs.existsSync(ffmpegStatic)) {
+  ffmpeg.setFfmpegPath(ffmpegStatic);
+}
+if (ffprobeStatic?.path && fs.existsSync(ffprobeStatic.path)) {
+  ffmpeg.setFfprobePath(ffprobeStatic.path);
+}
+
+/**
+ * Find companion file with matching stem and target extension.
+ *
+ * @param {string} sourcePath
+ * @param {string} ext
+ * @returns {string | null}
+ */
+export function findCompanionFile(sourcePath, ext) {
+  if (!sourcePath) return null;
+  const dir = path.dirname(sourcePath);
+  const stem = path.basename(sourcePath, path.extname(sourcePath)).trim().toLowerCase();
+  const direct = path.join(dir, `${path.basename(sourcePath, path.extname(sourcePath))}.${ext}`);
+  if (fs.existsSync(direct)) return direct;
+  if (fs.existsSync(dir)) {
+    try {
+      const files = fs.readdirSync(dir);
+      const match = files.find(f => f.toLowerCase().endsWith('.' + ext.toLowerCase()) && path.basename(f, path.extname(f)).trim().toLowerCase() === stem);
+      if (match) return path.join(dir, match);
+    } catch {
+      // ignore
+    }
+  }
+  return null;
+}
+
+/**
+ * Parse time expression to seconds.
+ * Supports: 'mm:ss', 'hh:mm:ss', seconds as string or number.
+ *
+ * @param {string | number} time
+ * @returns {number}
+ */
+export function parseTimeSeconds(time) {
+  if (typeof time === 'number') {
+    if (isNaN(time) || time < 0) {
+      throw new Error(`Invalid time duration: ${time}`);
+    }
+    return time;
+  }
+
+  if (typeof time !== 'string') {
+    throw new Error(`Invalid time format: ${time}`);
+  }
+
+  const trimmed = time.trim();
+  if (!trimmed) {
+    throw new Error('Empty time value provided.');
+  }
+
+  if (trimmed.includes(':')) {
+    const parts = trimmed.split(':').map(p => parseFloat(p.trim()));
+    if (parts.some(p => isNaN(p) || p < 0)) {
+      throw new Error(`Invalid time format: "${time}"`);
+    }
+    if (parts.length === 2) {
+      // mm:ss
+      return parts[0] * 60 + parts[1];
+    }
+    if (parts.length === 3) {
+      // hh:mm:ss
+      return parts[0] * 3600 + parts[1] * 60 + parts[2];
+    }
+    throw new Error(`Invalid time format: "${time}"`);
+  }
+
+  const parsed = parseFloat(trimmed);
+  if (isNaN(parsed) || parsed < 0) {
+    throw new Error(`Invalid time format: "${time}"`);
+  }
+  return parsed;
+}
+
+/**
+ * Probe video metadata using ffprobe.
+ *
+ * @param {string} filePath
+ * @returns {Promise<{ duration: number, width: number, height: number, fps: number, sampleRate: number }>}
+ */
+export function getVideoMetadata(filePath) {
+  return new Promise((resolve, reject) => {
+    if (!fs.existsSync(filePath)) {
+      return reject(new Error(`File not found: ${filePath}`));
+    }
+
+    ffmpeg.ffprobe(filePath, (err, metadata) => {
+      if (err) {
+        return reject(new Error(`FFprobe error for ${filePath}: ${err.message}`));
+      }
+
+      const videoStream = metadata.streams?.find(s => s.codec_type === 'video');
+      const audioStream = metadata.streams?.find(s => s.codec_type === 'audio');
+
+      let duration = metadata.format?.duration;
+      if (typeof duration === 'string') duration = parseFloat(duration);
+      if (!duration && videoStream?.duration) {
+        duration = parseFloat(videoStream.duration);
+      }
+      if (!duration && audioStream?.duration) {
+        duration = parseFloat(audioStream.duration);
+      }
+
+      let fps = 30;
+      if (videoStream?.r_frame_rate) {
+        const [num, den] = videoStream.r_frame_rate.split('/').map(Number);
+        if (num && den) {
+          fps = Math.round(num / den);
+        }
+      }
+
+      resolve({
+        duration: duration || 0,
+        width: videoStream?.width || 1920,
+        height: videoStream?.height || 1080,
+        fps: fps || 30,
+        sampleRate: parseInt(audioStream?.sample_rate, 10) || 44100,
+      });
+    });
+  });
+}
+
+/**
+ * Shorten a video by cutting at cutPoint, applying a fade-out before the cutPoint,
+ * and appending silent padding buffer after the cut.
+ *
+ * @param {object} params
+ * @param {string} params.inputPath - Source video path
+ * @param {string} params.outputPath - Output video path
+ * @param {string | number} params.cutPoint - Cut timestamp/seconds
+ * @param {number} [params.fadeDuration=3] - Duration of fade out in seconds
+ * @param {number} [params.paddingDuration=2] - Duration of silent buffer in seconds
+ * @param {'black' | 'freeze-frame'} [params.paddingFill='black']
+ * @param {Array<'audio' | 'video'>} [params.fadeTargets=['audio', 'video']]
+ * @param {boolean} [params.dryRun=false]
+ * @param {(msg: string) => void} [params.onWarn]
+ * @returns {Promise<{ outputPath: string, duration: number, dryRun?: boolean, command?: string }>}
+ */
+export async function shortenVideo(params) {
+  const {
+    inputPath,
+    outputPath,
+    cutPoint,
+    fadeDuration = 3,
+    paddingDuration = 2,
+    paddingFill = 'black',
+    fadeTargets = ['audio', 'video'],
+    dryRun = false,
+    entry = {},
+    onWarn,
+  } = params;
+
+  if (cutPoint === undefined || cutPoint === null) {
+    throw new Error('Action "shorten" requires "cutPoint" parameter.');
+  }
+
+  const cutSeconds = parseTimeSeconds(cutPoint);
+  if (cutSeconds <= 0) {
+    throw new Error(`Action "shorten" cutPoint must be greater than 0 (received: ${cutPoint}).`);
+  }
+
+  const audioSourcePath = params.audioSourcePath || entry.sourceWav || findCompanionFile(entry.sourcePath || inputPath, 'wav');
+  const hasSeparateAudio = Boolean(audioSourcePath && fs.existsSync(audioSourcePath) && audioSourcePath !== inputPath);
+
+  let videoMeta = { duration: 0, width: 1920, height: 1080, fps: 30, sampleRate: 48000 };
+  if (fs.existsSync(inputPath)) {
+    try {
+      videoMeta = await getVideoMetadata(inputPath);
+    } catch (err) {
+      if (!dryRun) {
+        throw err;
+      }
+    }
+  }
+
+  if (videoMeta.duration > 0 && cutSeconds >= videoMeta.duration) {
+    throw new Error(
+      `cutPoint (${cutSeconds}s) is greater than or equal to source video duration (${videoMeta.duration.toFixed(1)}s).`
+    );
+  }
+
+  let effectiveFadeDuration = Math.max(0, fadeDuration);
+  let fadeStart = cutSeconds - effectiveFadeDuration;
+  if (fadeStart < 0) {
+    if (onWarn) {
+      onWarn(`fadeDuration (${fadeDuration}s) exceeds cutPoint (${cutSeconds}s); clamping fade start to 0s.`);
+    }
+    fadeStart = 0;
+    effectiveFadeDuration = cutSeconds;
+  }
+
+  const totalDuration = cutSeconds + paddingDuration;
+  const width = videoMeta.width || 1920;
+  const height = videoMeta.height || 1080;
+  const fps = videoMeta.fps || 30;
+  const sampleRate = hasSeparateAudio ? 48000 : (videoMeta.sampleRate || 48000);
+
+  const shouldFadeVideo = fadeTargets.includes('video');
+  const shouldFadeAudio = fadeTargets.includes('audio');
+
+  if (dryRun) {
+    const videoFadePart = shouldFadeVideo ? `, fade out at ${fadeStart.toFixed(1)}s for ${effectiveFadeDuration.toFixed(1)}s` : '';
+    const audioFadePart = shouldFadeAudio ? `, audio fade out at ${fadeStart.toFixed(1)}s for ${effectiveFadeDuration.toFixed(1)}s` : '';
+    const wavNote = hasSeparateAudio ? ` [audio from ${path.basename(audioSourcePath)}]` : '';
+    const plan = `Shorten: trim to ${cutSeconds.toFixed(1)}s${videoFadePart}${audioFadePart}${wavNote} + ${paddingDuration}s silent padding (${paddingFill}) -> ${outputPath}`;
+    return {
+      outputPath,
+      duration: totalDuration,
+      dryRun: true,
+      command: plan,
+    };
+  }
+
+  fs.mkdirSync(path.dirname(path.resolve(outputPath)), { recursive: true });
+
+  return new Promise((resolve, reject) => {
+    const command = ffmpeg();
+
+    // Input 0: source video
+    command.input(inputPath);
+
+    let audioInputIndex = 0;
+    if (hasSeparateAudio) {
+      command.input(audioSourcePath);
+      audioInputIndex = 1;
+    }
+
+    const complexFilters = [];
+
+    // Filter video 0
+    let v0Filter = `trim=0:${cutSeconds},setpts=PTS-STARTPTS`;
+    if (shouldFadeVideo && effectiveFadeDuration > 0) {
+      v0Filter += `,fade=t=out:st=${fadeStart}:d=${effectiveFadeDuration}`;
+    }
+    complexFilters.push(`[0:v]${v0Filter}[v0]`);
+
+    // Filter audio
+    let a0Filter = `atrim=0:${cutSeconds},asetpts=PTS-STARTPTS`;
+    if (shouldFadeAudio && effectiveFadeDuration > 0) {
+      a0Filter += `,afade=t=out:st=${fadeStart}:d=${effectiveFadeDuration}`;
+    }
+    complexFilters.push(`[${audioInputIndex}:a]${a0Filter}[a0]`);
+
+    if (paddingDuration > 0) {
+      // Audio silence input
+      const silenceIndex = audioInputIndex + 1;
+      command.input(`anullsrc=r=${sampleRate}:cl=stereo`).inputOptions(['-f', 'lavfi', '-t', `${paddingDuration}`]);
+
+      if (paddingFill === 'freeze-frame') {
+        // Use the last frame of the trimmed portion as padding
+        complexFilters.push(`[v0]split=2[v0_out][v0_last]`);
+        complexFilters.push(`[v0_last]trim=${Math.max(0, cutSeconds - 0.04)}:${cutSeconds},setpts=PTS-STARTPTS,loop=loop=-1:size=1:start=0,trim=0:${paddingDuration},setpts=PTS-STARTPTS[vpad]`);
+        complexFilters.push(`[v0_out][a0][vpad][${silenceIndex}:a]concat=n=2:v=1:a=1[outv][outa]`);
+      } else {
+        // Plain black padding via lavfi color, forced to match the trimmed video
+        const colorIndex = silenceIndex + 1;
+        command.input(`color=c=black:s=${width}x${height}:r=${fps}:d=${paddingDuration}`).inputOptions(['-f', 'lavfi']);
+        complexFilters.push(`[v0]format=yuv420p,setsar=1[v0f]`);
+        complexFilters.push(`[${colorIndex}:v]scale=${width}:${height}:flags=neighbor,setsar=1,fps=${fps},format=yuv420p[vpad]`);
+        complexFilters.push(`[v0f][a0][vpad][${silenceIndex}:a]concat=n=2:v=1:a=1[outv][outa]`);
+      }
+    } else {
+      complexFilters.push(`[v0]copy[outv]`);
+      complexFilters.push(`[a0]copy[outa]`);
+    }
+
+    command
+      .complexFilter(complexFilters)
+      .outputOptions([
+        '-map', '[outv]',
+        '-map', '[outa]',
+        '-c:v', 'libx264',
+        '-crf', '18',
+        '-preset', 'veryfast',
+        '-c:a', 'aac',
+        '-b:a', '320k',
+        '-ar', '48000',
+        '-pix_fmt', 'yuv420p',
+        '-movflags', '+faststart',
+        `-t`, `${totalDuration}`,
+      ])
+      .output(outputPath)
+      .on('end', () => {
+        resolve({
+          outputPath,
+          duration: totalDuration,
+        });
+      })
+      .on('error', (err) => {
+        if (fs.existsSync(outputPath)) {
+          try {
+            fs.unlinkSync(outputPath);
+          } catch {}
+        }
+        reject(new Error(`Shorten video failed: ${err.message}`));
+      })
+      .run();
+  });
+}

package/src/batch/clone-metadata.js

@@ -0,0 +1,51 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Deep clone and update metadata for the output directory.
+ *
+ * @param {object} rawMetadata - Original raw metadata object
+ * @param {string} outputDir - Path to output directory
+ * @param {Array<object>} results - Array of action pipeline results per entry
+ * @returns {object} Cloned metadata object that was written
+ */
+export function cloneMetadataForOutput(rawMetadata, outputDir, results = []) {
+  if (!outputDir) {
+    throw new Error('outputDir is required to clone metadata.');
+  }
+
+  const cloned = JSON.parse(JSON.stringify(rawMetadata || {}));
+  const resultMap = new Map(results.map(r => [r.songKey || r.filename, r]));
+
+  if (cloned.songs && typeof cloned.songs === 'object' && !Array.isArray(cloned.songs)) {
+    for (const [songKey, songData] of Object.entries(cloned.songs)) {
+      const res = resultMap.get(songKey);
+      if (res) {
+        if (res.actionsApplied && res.actionsApplied.length > 0) {
+          songData.actionsApplied = res.actionsApplied;
+        }
+        if (res.generatedFilename) {
+          songData.filename = res.generatedFilename;
+        }
+      }
+    }
+  } else if (Array.isArray(cloned.videos)) {
+    for (const video of cloned.videos) {
+      const res = resultMap.get(video.filename);
+      if (res) {
+        if (res.actionsApplied && res.actionsApplied.length > 0) {
+          video.actionsApplied = res.actionsApplied;
+        }
+        if (res.generatedFilename) {
+          video.filename = res.generatedFilename;
+        }
+      }
+    }
+  }
+
+  fs.mkdirSync(outputDir, { recursive: true });
+  const outputMetadataPath = path.join(outputDir, 'metadata.json');
+  fs.writeFileSync(outputMetadataPath, JSON.stringify(cloned, null, 2) + '\n', 'utf-8');
+
+  return cloned;
+}