video-sampler 1.0.0

package/src/audio/extractAudioBuffer.js

@@ -0,0 +1,144 @@
+import {
+  COMMON_INPUT_OPTS,
+  runFfmpegCLI,
+  runFfmpegPipe,
+  runFfmpegPipeToFile,
+} from '../shared/ffmpeg.js';
+import {
+  createTempPath,
+  deleteFilesQuietly,
+  fs,
+  moveFile,
+  path,
+} from '../shared/files.js';
+
+const WAV_TOO_SMALL_MESSAGE = 'WAV too small - conversion failed';
+
+export { COMMON_INPUT_OPTS, runFfmpegPipe, runFfmpegPipeToFile };
+
+export const isMp4ByHeader = async (filePath) => {
+  const fileHandle = await fs.promises.open(filePath, 'r');
+
+  try {
+    const buffer = Buffer.alloc(8);
+    await fileHandle.read(buffer, 0, 8, 0);
+    return buffer.slice(4, 8).toString() === 'ftyp';
+  } finally {
+    await fileHandle.close();
+  }
+};
+
+export const extractAudio = async (videoPath, options = {}) => {
+  const outputPath = await resolveAudioOutputPath(videoPath, options);
+  const extracted = await extractAudioWavPath(videoPath, options);
+
+  await moveFile(extracted.wavPath, outputPath);
+
+  return {
+    path: outputPath,
+    mime: extracted.mime,
+    ext: extracted.ext,
+  };
+};
+
+export const extractAudioWavPath = async (videoPath, options = {}) => {
+  const tmpIn = createTempPath('.in');
+  await fs.promises.copyFile(videoPath, tmpIn);
+
+  const isMp4 = await isMp4ByHeader(tmpIn);
+  const tmpRemux = isMp4 ? createTempPath('.remux.mp4') : null;
+  const tmpOut = createTempPath('.wav');
+
+  try {
+    const wavPath = await convertTempInputToWavPath({
+      tmpIn,
+      tmpOut,
+      tmpRemux,
+      isMp4,
+      ffmpegPath: options.ffmpegPath,
+    });
+    return { wavPath, mime: 'audio/wav', ext: 'wav' };
+  } catch (error) {
+    await deleteFilesQuietly([tmpOut, tmpIn, tmpRemux]);
+    throw error;
+  } finally {
+    await deleteFilesQuietly([tmpIn, tmpRemux]);
+  }
+};
+
+const extractAudioBuffer = async (videoBuffer, options = {}) => {
+  const tmpIn = createTempPath('.in');
+  await fs.promises.writeFile(tmpIn, videoBuffer);
+
+  const isMp4 = videoBuffer.slice(4, 8).toString() === 'ftyp';
+  const tmpRemux = isMp4 ? createTempPath('.remux.mp4') : null;
+  const tmpOut = createTempPath('.wav');
+
+  try {
+    await convertTempInputToWavPath({
+      tmpIn,
+      tmpOut,
+      tmpRemux,
+      isMp4,
+      ffmpegPath: options.ffmpegPath,
+    });
+
+    const wav = await fs.promises.readFile(tmpOut);
+    if (wav.length < 1024) throw new Error(WAV_TOO_SMALL_MESSAGE);
+
+    return { buffer: wav, mime: 'audio/wav', ext: 'wav' };
+  } finally {
+    await deleteFilesQuietly([tmpIn, tmpRemux, tmpOut]);
+  }
+};
+
+const convertTempInputToWavPath = async ({ tmpIn, tmpOut, tmpRemux, isMp4, ffmpegPath }) => {
+  if (isMp4) {
+    await runFfmpegCLI(
+      ['-y', '-i', tmpIn, '-c', 'copy', '-movflags', '+faststart', tmpRemux],
+      { ffmpegPath },
+    );
+  }
+
+  const decodeInput = isMp4 ? tmpRemux : tmpIn;
+
+  await runFfmpegCLI(
+    [
+      '-y',
+      ...COMMON_INPUT_OPTS,
+      '-i',
+      decodeInput,
+      '-map',
+      '0:a:0',
+      '-vn',
+      '-c:a',
+      'pcm_s16le',
+      '-ar',
+      '16000',
+      '-ac',
+      '1',
+      tmpOut,
+    ],
+    { ffmpegPath },
+  );
+
+  const stat = await fs.promises.stat(tmpOut);
+  if (stat.size < 1024) throw new Error(WAV_TOO_SMALL_MESSAGE);
+
+  return tmpOut;
+};
+
+const resolveAudioOutputPath = async (videoPath, options) => {
+  if (options.outputPath) {
+    const outputPath = path.resolve(options.outputPath);
+    await fs.promises.mkdir(path.dirname(outputPath), { recursive: true });
+    return outputPath;
+  }
+
+  const outputDir = path.resolve(options.outputDir || process.cwd());
+  await fs.promises.mkdir(outputDir, { recursive: true });
+
+  return path.join(outputDir, `${path.parse(videoPath).name}.wav`);
+};
+
+export default extractAudioBuffer;

package/src/cli/args.js

@@ -0,0 +1,102 @@
+import {
+  DEFAULT_FRAME_OPTIONS,
+  applyFrameOption,
+  isBooleanOption,
+} from './frameOptions.js';
+
+export const parseArgs = (argv) => {
+  const args = {
+    videoPath: null,
+    framesDir: null,
+    audioDir: null,
+    ffmpegPath: null,
+    ffprobePath: null,
+    frameOptions: { ...DEFAULT_FRAME_OPTIONS },
+    help: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === '--help' || arg === '-h') {
+      args.help = true;
+      continue;
+    }
+
+    if (!arg.startsWith('--')) {
+      applyPositionalArg(args, arg);
+      continue;
+    }
+
+    const option = readOption(arg, argv[index + 1]);
+    if (option.consumedNext) index += 1;
+
+    applyOption(args, option.key, option.value);
+  }
+
+  return args;
+};
+
+const applyPositionalArg = (args, arg) => {
+  if (!args.videoPath) {
+    args.videoPath = arg;
+    return;
+  }
+
+  throw new Error(`Unexpected positional argument: ${arg}`);
+};
+
+const readOption = (arg, nextArg) => {
+  const equalsIndex = arg.indexOf('=');
+
+  if (equalsIndex !== -1) {
+    return {
+      key: arg.slice(2, equalsIndex),
+      value: arg.slice(equalsIndex + 1),
+      consumedNext: false,
+    };
+  }
+
+  const key = arg.slice(2);
+
+  if (isBooleanOption(key)) {
+    return { key, value: 'true', consumedNext: false };
+  }
+
+  if (!nextArg || nextArg.startsWith('--')) {
+    throw new Error(`Missing value for --${key}`);
+  }
+
+  return { key, value: nextArg, consumedNext: true };
+};
+
+const applyOption = (args, key, value) => {
+  switch (key) {
+    case 'video':
+      args.videoPath = value;
+      return;
+    case 'frames-dir':
+    case 'framesDir':
+    case 'output-dir':
+    case 'outputDir':
+      args.framesDir = value;
+      return;
+    case 'audio-dir':
+    case 'audioDir':
+      args.audioDir = value;
+      return;
+    case 'ffmpeg-path':
+    case 'ffmpegPath':
+      args.ffmpegPath = value;
+      args.frameOptions.ffmpegPath = value;
+      return;
+    case 'ffprobe-path':
+    case 'ffprobePath':
+      args.ffprobePath = value;
+      args.frameOptions.ffprobePath = value;
+      return;
+    default:
+      if (applyFrameOption(args.frameOptions, key, value)) return;
+      throw new Error(`Unknown option: --${key}`);
+  }
+};

package/src/cli/frameOptions.js

@@ -0,0 +1,121 @@
+import { DEFAULT_FRAME_OPTIONS } from '../frames/defaults.js';
+
+export { DEFAULT_FRAME_OPTIONS };
+
+export const applyFrameOption = (frameOptions, key, value) => {
+  switch (key) {
+    case 'target-frames':
+    case 'targetFrames':
+    case 'frames':
+      frameOptions.targetFrames = parsePositiveIntegerOption(key, value);
+      return true;
+    case 'max-frames':
+    case 'maxFrames':
+      frameOptions.maxFrames = parsePositiveIntegerOption(key, value);
+      return true;
+    case 'min-frames':
+    case 'minFrames':
+      frameOptions.minFrames = parsePositiveIntegerOption(key, value);
+      return true;
+    case 'min-gap':
+    case 'min-gap-ms':
+    case 'min-gap-milliseconds':
+    case 'minGapMs':
+      frameOptions.minGapMs = parsePositiveNumberOption(key, value);
+      return true;
+    case 'min-gap-seconds':
+    case 'minGapSeconds':
+      frameOptions.minGapSeconds = parsePositiveNumberOption(key, value);
+      return true;
+    case 'start-time-ms':
+    case 'startTimeMs':
+      frameOptions.startTimeMs = parseNumberOption(key, value);
+      return true;
+    case 'end-before-ms':
+    case 'endBeforeMs':
+      frameOptions.endBeforeMs = parseNumberOption(key, value);
+      return true;
+    case 'candidate-multiplier':
+    case 'candidateMultiplier':
+      frameOptions.candidateMultiplier = parsePositiveIntegerOption(key, value);
+      return true;
+    case 'max-candidates':
+    case 'maxCandidates':
+      frameOptions.maxCandidates = parsePositiveIntegerOption(key, value);
+      return true;
+    case 'similarity-threshold':
+    case 'similarityThreshold':
+      frameOptions.similarityThreshold = parseNonNegativeIntegerOption(key, value);
+      return true;
+    case 'compare-recent':
+    case 'compare-recent-count':
+    case 'compareRecentCount':
+      frameOptions.compareRecentCount = parsePositiveIntegerOption(key, value);
+      return true;
+    case 'format':
+    case 'image-format':
+    case 'imageFormat':
+      frameOptions.imageFormat = value;
+      return true;
+    case 'jpeg-quality':
+    case 'jpegQuality':
+      frameOptions.jpegQuality = parsePositiveIntegerOption(key, value);
+      return true;
+    case 'debug':
+      frameOptions.debug = parseBooleanOption(key, value);
+      return true;
+    case 'no-fallback':
+      frameOptions.includeFallbackFrames = false;
+      return true;
+    case 'keep-rejected':
+      frameOptions.cleanupRejected = false;
+      return true;
+    default:
+      return false;
+  }
+};
+
+export const isBooleanOption = (key) =>
+  ['debug', 'no-fallback', 'keep-rejected'].includes(key);
+
+const parsePositiveIntegerOption = (key, value) => {
+  const number = Number(value);
+  if (!Number.isInteger(number) || number <= 0) {
+    throw new Error(`--${key} must be a positive integer.`);
+  }
+
+  return number;
+};
+
+const parseNonNegativeIntegerOption = (key, value) => {
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < 0) {
+    throw new Error(`--${key} must be a non-negative integer.`);
+  }
+
+  return number;
+};
+
+const parseNumberOption = (key, value) => {
+  const number = Number(value);
+  if (!Number.isFinite(number)) {
+    throw new Error(`--${key} must be a number.`);
+  }
+
+  return number;
+};
+
+const parsePositiveNumberOption = (key, value) => {
+  const number = Number(value);
+  if (!Number.isFinite(number) || number <= 0) {
+    throw new Error(`--${key} must be a positive number.`);
+  }
+
+  return number;
+};
+
+const parseBooleanOption = (key, value) => {
+  if (value === true || value === 'true') return true;
+  if (value === false || value === 'false') return false;
+  throw new Error(`--${key} must be true or false.`);
+};

package/src/cli/main.js

@@ -0,0 +1,46 @@
+import { parseArgs } from './args.js';
+import { printSummary, printUsage } from './print.js';
+import { processAudio, processFrames } from './processors.js';
+import { resolveVideoPath } from './videoFiles.js';
+import { fs, path } from '../shared/files.js';
+
+export const main = async (argv = process.argv.slice(2), cwd = process.cwd()) => {
+  const args = parseArgs(argv);
+
+  if (args.help) {
+    printUsage();
+    return;
+  }
+
+  const videoPath = await resolveVideoPath(args.videoPath, cwd);
+  const framesDir = path.resolve(cwd, args.framesDir || 'frames');
+  const audioDir = path.resolve(cwd, args.audioDir || 'audio');
+
+  await fs.promises.mkdir(framesDir, { recursive: true });
+  await fs.promises.mkdir(audioDir, { recursive: true });
+
+  console.log('Input video:', videoPath);
+  console.log('Frames directory:', framesDir);
+  console.log('Audio directory:', audioDir);
+
+  const audio = await processAudio(videoPath, audioDir, {
+    ffmpegPath: args.ffmpegPath,
+  });
+  const frameResult = await processFrames(videoPath, framesDir, args.frameOptions);
+  const result = buildResult(frameResult, audio, audioDir);
+
+  printSummary(result);
+};
+
+const buildResult = (frameResult, audio, audioDir) => ({
+  video: frameResult.video,
+  audio,
+  frames: frameResult.frames,
+  output: {
+    audioDirectory: audioDir,
+    framesDirectory: frameResult.output.directory,
+  },
+  options: frameResult.options,
+  stats: frameResult.stats,
+  warnings: frameResult.warnings,
+});

package/src/cli/print.js

@@ -0,0 +1,56 @@
+export const printSummary = (result) => {
+  console.log('');
+  console.log('Processing complete.');
+  console.log('Duration seconds:', result.video.durationSeconds);
+  console.log('Audio file:', result.audio.path);
+  console.log('Frames returned:', result.frames.length);
+  console.log('Frame timestamps:', result.frames.map((frame) => frame.timestamp));
+  console.log('Frame paths:');
+
+  for (const frame of result.frames) {
+    console.log(`- ${frame.path}`);
+  }
+
+  if (result.warnings.length > 0) {
+    console.log('Warnings:');
+    for (const warning of result.warnings) {
+      console.log(`- ${warning}`);
+    }
+  }
+
+  console.log('Stats:', result.stats);
+};
+
+export const printUsage = () => {
+  console.log(`
+Usage:
+  video-sampler [videoPath] [options]
+  video-sampler --video "./interview.webm" --frames 12 --max-frames 24
+
+If videoPath or --video is omitted, the CLI uses the only supported video file in the project root.
+
+Options:
+  --video <path>                    Video file to process
+  --frames <n>                      Target number of frames
+  --target-frames <n>               Same as --frames
+  --max-frames <n>                  Maximum returned frames
+  --min-frames <n>                  Minimum frames to try to return
+  --min-gap <ms>                    Soft minimum gap between selected frames, default 1000
+  --min-gap-ms <ms>                 Same as --min-gap
+  --start-time-ms <ms>              Start sampling at this timestamp, default 0
+  --end-before-ms <ms>              Stop sampling this many ms before the video ends
+  --candidate-multiplier <n>        Candidate count multiplier
+  --max-candidates <n>              Maximum candidate frames to inspect
+  --similarity-threshold <n>        pHash Hamming distance threshold
+  --compare-recent <n>              Recent accepted frames to compare after early selection
+  --frames-dir <path>               Output folder for accepted frames, default ./frames
+  --audio-dir <path>                Output folder for WAV audio, default ./audio
+  --ffmpeg-path <path>              Custom FFmpeg binary path
+  --ffprobe-path <path>             Custom FFprobe binary path
+  --format <jpg|png|webp>           Frame image format, default jpg
+  --jpeg-quality <n>                FFmpeg q:v value for JPG, lower is better
+  --debug                           Print FFmpeg debug output from frame extraction
+  --no-fallback                     Disable fallback frame coverage
+  --keep-rejected                   Keep rejected candidate frame files
+`);
+};

package/src/cli/processors.js

@@ -0,0 +1,14 @@
+import { extractAudio } from '../audio/extractAudioBuffer.js';
+import { sampleFrames } from '../frames/frameSampler.js';
+
+export const processAudio = async (videoPath, audioDir, options = {}) =>
+  extractAudio(videoPath, {
+    outputDir: audioDir,
+    ffmpegPath: options.ffmpegPath,
+  });
+
+export const processFrames = async (videoPath, framesDir, frameOptions) =>
+  sampleFrames(videoPath, {
+    ...frameOptions,
+    outputDir: framesDir,
+  });

package/src/cli/videoFiles.js

@@ -0,0 +1,48 @@
+import { fs, path } from '../shared/files.js';
+
+const VIDEO_EXTENSIONS = new Set([
+  '.mp4',
+  '.mov',
+  '.m4v',
+  '.webm',
+  '.mkv',
+  '.avi',
+]);
+
+export const resolveVideoPath = async (videoPath, cwd) => {
+  const resolved = videoPath
+    ? path.resolve(cwd, videoPath)
+    : await findSingleVideoInDirectory(cwd);
+
+  let stat;
+  try {
+    stat = await fs.promises.stat(resolved);
+  } catch {
+    throw new Error(`Video file does not exist: ${resolved}`);
+  }
+
+  if (!stat.isFile()) {
+    throw new Error(`Video path is not a file: ${resolved}`);
+  }
+
+  return resolved;
+};
+
+const findSingleVideoInDirectory = async (directory) => {
+  const entries = await fs.promises.readdir(directory, { withFileTypes: true });
+  const videos = entries
+    .filter((entry) => entry.isFile() && VIDEO_EXTENSIONS.has(path.extname(entry.name).toLowerCase()))
+    .map((entry) => path.join(directory, entry.name));
+
+  if (videos.length === 0) {
+    throw new Error('No video path was provided and no supported video file was found in this directory.');
+  }
+
+  if (videos.length > 1) {
+    throw new Error(
+      `Multiple video files were found. Pass one explicitly with --video. Found: ${videos.map((file) => path.basename(file)).join(', ')}`,
+    );
+  }
+
+  return videos[0];
+};

package/src/frames/cleanup.js

@@ -0,0 +1,19 @@
+import { deleteFileQuietly } from '../shared/files.js';
+
+export const cleanupRejectedCandidates = async (candidates, acceptedPaths, cleanupRejected) => {
+  if (!cleanupRejected) return;
+
+  await Promise.all(
+    candidates
+      .filter((candidate) => !acceptedPaths.has(candidate.path))
+      .map((candidate) => deleteFileQuietly(candidate.path)),
+  );
+};
+
+export const cleanupErroredFrames = async (createdFramePaths, acceptedFramePaths) => {
+  await Promise.all(
+    [...createdFramePaths]
+      .filter((framePath) => !acceptedFramePaths.has(framePath))
+      .map(deleteFileQuietly),
+  );
+};

package/src/frames/defaults.js

@@ -0,0 +1,20 @@
+export const DEFAULT_FRAME_OPTIONS = {
+  targetFrames: 12,
+  maxFrames: 24,
+  minFrames: 3,
+  minGapMs: 1000,
+  startTimeMs: 0,
+  endBeforeMs: 0,
+  candidateMultiplier: 4,
+  maxCandidates: 160,
+  similarityThreshold: 10,
+  compareRecentCount: 5,
+  outputDir: null,
+  imageFormat: 'jpg',
+  jpegQuality: 2,
+  cleanupRejected: true,
+  includeFallbackFrames: true,
+  debug: false,
+};
+
+export const MIN_FRAME_BYTES = 100;