video-sampler 1.0.0

package/src/frames/options.js

@@ -0,0 +1,221 @@
+import {
+  finiteNumberOrDefault,
+  positiveIntegerOrDefault,
+} from '../shared/numbers.js';
+import { DEFAULT_FRAME_OPTIONS } from './defaults.js';
+
+export const resolveOptions = (options, warnings) => {
+  const merged = { ...DEFAULT_FRAME_OPTIONS, ...options };
+
+  const maxFrames = positiveIntegerOrDefault(merged.maxFrames, DEFAULT_FRAME_OPTIONS.maxFrames);
+  const targetFrames = positiveIntegerOrDefault(merged.targetFrames, DEFAULT_FRAME_OPTIONS.targetFrames);
+  const minFrames = Math.min(
+    positiveIntegerOrDefault(merged.minFrames, DEFAULT_FRAME_OPTIONS.minFrames),
+    maxFrames,
+  );
+
+  const minGapMs = resolveMinGapMs(merged, options, warnings);
+  const minGapSeconds = minGapMs / 1000;
+  const startTimeMs = resolveStartTimeMs(merged.startTimeMs, warnings);
+  const endBeforeMs = resolveEndBeforeMs(merged.endBeforeMs, warnings);
+
+  let imageFormat = String(merged.imageFormat || DEFAULT_FRAME_OPTIONS.imageFormat).toLowerCase();
+  if (imageFormat === 'jpeg') imageFormat = 'jpg';
+
+  if (!['jpg', 'png', 'webp'].includes(imageFormat)) {
+    warnings.push(`Unsupported imageFormat "${merged.imageFormat}" was replaced with jpg.`);
+    imageFormat = 'jpg';
+  }
+
+  return {
+    targetFrames,
+    maxFrames,
+    minFrames,
+    minGapMs,
+    minGapSeconds,
+    startTimeMs,
+    endBeforeMs,
+    candidateMultiplier: Math.max(
+      1,
+      positiveIntegerOrDefault(
+        merged.candidateMultiplier,
+        DEFAULT_FRAME_OPTIONS.candidateMultiplier,
+      ),
+    ),
+    maxCandidates: Math.max(
+      1,
+      positiveIntegerOrDefault(merged.maxCandidates, DEFAULT_FRAME_OPTIONS.maxCandidates),
+    ),
+    similarityThreshold: Math.max(
+      0,
+      positiveIntegerOrDefault(
+        merged.similarityThreshold,
+        DEFAULT_FRAME_OPTIONS.similarityThreshold,
+      ),
+    ),
+    compareRecentCount: Math.max(
+      1,
+      positiveIntegerOrDefault(
+        merged.compareRecentCount,
+        DEFAULT_FRAME_OPTIONS.compareRecentCount,
+      ),
+    ),
+    outputDir: merged.outputDir,
+    ffmpegPath: merged.ffmpegPath,
+    ffprobePath: merged.ffprobePath,
+    imageFormat,
+    jpegQuality: positiveIntegerOrDefault(
+      merged.jpegQuality,
+      DEFAULT_FRAME_OPTIONS.jpegQuality,
+    ),
+    cleanupRejected: merged.cleanupRejected !== false,
+    includeFallbackFrames: merged.includeFallbackFrames !== false,
+    debug: Boolean(merged.debug),
+  };
+};
+
+const resolveStartTimeMs = (value, warnings) => {
+  let startTimeMs = finiteNumberOrDefault(value, DEFAULT_FRAME_OPTIONS.startTimeMs);
+
+  if (value !== undefined && !Number.isFinite(Number(value))) {
+    warnings.push(`Invalid startTimeMs "${value}" was replaced with 0.`);
+    startTimeMs = 0;
+  }
+
+  if (startTimeMs < 0) {
+    warnings.push(`Invalid startTimeMs "${value}" was replaced with 0.`);
+    startTimeMs = 0;
+  }
+
+  return startTimeMs;
+};
+
+const resolveEndBeforeMs = (value, warnings) => {
+  let endBeforeMs = finiteNumberOrDefault(value, DEFAULT_FRAME_OPTIONS.endBeforeMs);
+
+  if (value !== undefined && !Number.isFinite(Number(value))) {
+    warnings.push(`Invalid endBeforeMs "${value}" was replaced with 0.`);
+    endBeforeMs = 0;
+  }
+
+  if (endBeforeMs < 0) {
+    warnings.push(`Invalid endBeforeMs "${value}" was replaced with 0.`);
+    endBeforeMs = 0;
+  }
+
+  return endBeforeMs;
+};
+
+const resolveMinGapMs = (options, rawOptions, warnings) => {
+  if (rawOptions.minGapSeconds !== undefined && rawOptions.minGapMs === undefined) {
+    warnings.push(
+      'minGapSeconds is deprecated. Use minGapMs instead.',
+    );
+    return validateMinGapMs(options.minGapSeconds * 1000, options.minGapSeconds, warnings);
+  }
+
+  return validateMinGapMs(options.minGapMs, options.minGapMs, warnings);
+};
+
+const validateMinGapMs = (value, originalValue, warnings) => {
+  let minGapMs = finiteNumberOrDefault(value, DEFAULT_FRAME_OPTIONS.minGapMs);
+
+  if (minGapMs <= 0) {
+    warnings.push(
+      `Invalid minGapMs "${originalValue}" was replaced with ${DEFAULT_FRAME_OPTIONS.minGapMs}.`,
+    );
+    minGapMs = DEFAULT_FRAME_OPTIONS.minGapMs;
+  }
+
+  return minGapMs;
+};
+
+export const resolveSamplingWindow = (durationSeconds, options, warnings) => {
+  if (!Number.isFinite(durationSeconds) || durationSeconds <= 0) {
+    throw new Error(`Invalid video duration: ${durationSeconds}`);
+  }
+
+  const durationMs = durationSeconds * 1000;
+  let startTimeMs = Math.min(options.startTimeMs, durationMs);
+  let endBeforeMs = options.endBeforeMs;
+  let endTimeMs = durationMs - endBeforeMs;
+  let trimEndForEof = endBeforeMs === 0;
+
+  if (options.startTimeMs >= durationMs) {
+    warnings.push(
+      `startTimeMs "${options.startTimeMs}" is beyond the video duration; using the full video instead.`,
+    );
+    startTimeMs = 0;
+    endTimeMs = durationMs;
+    endBeforeMs = 0;
+    trimEndForEof = true;
+  } else if (endTimeMs <= startTimeMs) {
+    warnings.push(
+      `endBeforeMs "${options.endBeforeMs}" leaves no sampling window after startTimeMs "${options.startTimeMs}"; using the full video instead.`,
+    );
+    startTimeMs = 0;
+    endTimeMs = durationMs;
+    endBeforeMs = 0;
+    trimEndForEof = true;
+  }
+
+  return {
+    startTimeMs,
+    endTimeMs,
+    endBeforeMs,
+    trimEndForEof,
+    startSeconds: startTimeMs / 1000,
+    endSeconds: endTimeMs / 1000,
+    durationSeconds: Math.max(0.001, (endTimeMs - startTimeMs) / 1000),
+    videoDurationMs: durationMs,
+  };
+};
+
+export const resolveSamplingCounts = (durationSeconds, options) => {
+  if (!Number.isFinite(durationSeconds) || durationSeconds <= 0) {
+    throw new Error(`Invalid sampling duration: ${durationSeconds}`);
+  }
+
+  const theoreticalMaxByGap = Math.max(
+    1,
+    Math.floor(durationSeconds / options.minGapSeconds),
+  );
+  const absoluteMaxByDuration = Math.max(
+    1,
+    Math.min(options.maxFrames, Math.floor(durationSeconds * 2)),
+  );
+
+  const primaryTargetFrames = Math.max(
+    1,
+    Math.min(options.targetFrames, options.maxFrames, theoreticalMaxByGap),
+  );
+  const minimumCoverageFrames = Math.max(
+    1,
+    Math.min(options.minFrames, options.maxFrames, absoluteMaxByDuration),
+  );
+  const resolvedTargetFrames = Math.max(
+    1,
+    Math.min(
+      options.maxFrames,
+      absoluteMaxByDuration,
+      Math.max(primaryTargetFrames, minimumCoverageFrames),
+    ),
+  );
+
+  const resolvedMinFrames = Math.max(
+    1,
+    Math.min(options.minFrames, resolvedTargetFrames),
+  );
+
+  const candidateCount = Math.min(
+    options.maxCandidates,
+    Math.max(resolvedTargetFrames * options.candidateMultiplier, resolvedTargetFrames),
+  );
+
+  return {
+    theoreticalMaxByGap,
+    resolvedTargetFrames,
+    resolvedMinFrames,
+    candidateCount,
+  };
+};

package/src/frames/probe.js

@@ -0,0 +1,60 @@
+import { resolveBinaryPaths, runCommand } from '../shared/ffmpeg.js';
+import { assertFileExists } from '../shared/files.js';
+import {
+  firstFiniteNumber,
+  parseFps,
+  toPositiveInteger,
+} from '../shared/numbers.js';
+
+export const probeVideo = async (videoPath, options = {}) => {
+  if (!videoPath || typeof videoPath !== 'string') {
+    throw new Error('Input video path is required.');
+  }
+
+  await assertFileExists(
+    videoPath,
+    `Input video file does not exist: ${videoPath}`,
+    `Input video path is not a file: ${videoPath}`,
+  );
+
+  const binaries = resolveBinaryPaths(options);
+  const { stdout, stderr } = await runCommand(binaries.ffprobePath, [
+    '-v',
+    'error',
+    '-print_format',
+    'json',
+    '-show_format',
+    '-show_streams',
+    videoPath,
+  ]);
+
+  const metadata = parseProbeMetadata(stdout, videoPath);
+  const videoStream = Array.isArray(metadata.streams)
+    ? metadata.streams.find((stream) => stream.codec_type === 'video')
+    : null;
+
+  const durationSeconds = firstFiniteNumber(
+    videoStream?.duration,
+    metadata.format?.duration,
+  );
+
+  if (!Number.isFinite(durationSeconds) || durationSeconds <= 0) {
+    const detail = stderr ? ` ffprobe stderr: ${stderr.trim()}` : '';
+    throw new Error(`Video duration could not be determined for ${videoPath}.${detail}`);
+  }
+
+  return {
+    durationSeconds,
+    width: toPositiveInteger(videoStream?.width, null),
+    height: toPositiveInteger(videoStream?.height, null),
+    fps: parseFps(videoStream?.avg_frame_rate || videoStream?.r_frame_rate),
+  };
+};
+
+const parseProbeMetadata = (stdout, videoPath) => {
+  try {
+    return JSON.parse(stdout);
+  } catch (error) {
+    throw new Error(`Could not parse ffprobe metadata for ${videoPath}: ${error.message}`);
+  }
+};

package/src/frames/selection.js

@@ -0,0 +1,160 @@
+import { getImageHash, hammingDistance } from './hash.js';
+
+export const selectRepresentativeFrames = async (candidates, sampling, options, warnings) => {
+  const accepted = [];
+  let candidatesRejectedAsSimilar = 0;
+  let candidatesRejectedForSpacing = 0;
+  let hashesAttempted = 0;
+  let hashesSucceeded = 0;
+
+  for (const candidate of candidates) {
+    if (accepted.length >= sampling.resolvedTargetFrames) break;
+
+    if (accepted.length > 0 && violatesMinGap(candidate, accepted, options.minGapSeconds)) {
+      candidatesRejectedForSpacing += 1;
+      continue;
+    }
+
+    hashesAttempted += 1;
+
+    try {
+      candidate.hash = await getImageHash(candidate.path);
+      hashesSucceeded += 1;
+    } catch (error) {
+      warnings.push(`Could not hash candidate frame ${candidate.path}: ${error.message}`);
+      continue;
+    }
+
+    if (accepted.length === 0) {
+      accepted.push(toAcceptedFrame(candidate, null, 'first_frame'));
+      continue;
+    }
+
+    const minDistance = getMinimumDistanceToAccepted(
+      candidate.hash,
+      accepted,
+      options.compareRecentCount,
+    );
+
+    if (minDistance >= options.similarityThreshold) {
+      accepted.push(toAcceptedFrame(candidate, minDistance, 'visually_distinct'));
+    } else {
+      candidatesRejectedAsSimilar += 1;
+    }
+  }
+
+  return {
+    accepted,
+    candidatesRejectedAsSimilar,
+    candidatesRejectedForSpacing,
+    hashesAttempted,
+    hashesSucceeded,
+  };
+};
+
+export const addFallbackFrames = async ({ accepted, candidates, sampling, resolved, warnings }) => {
+  const selected = [...accepted];
+  const acceptedPaths = new Set(selected.map((frame) => frame.path));
+  const targetCount = Math.min(sampling.resolvedTargetFrames, resolved.maxFrames);
+  const needed = Math.min(sampling.resolvedMinFrames, targetCount);
+  let added = 0;
+
+  for (const minGapSeconds of getFallbackGapAttempts(resolved.minGapSeconds)) {
+    if (selected.length >= needed || selected.length >= targetCount) break;
+
+    const pool = candidates.filter((candidate) => !acceptedPaths.has(candidate.path));
+    const ordered = orderCandidatesForEvenCoverage(pool, selected, targetCount);
+
+    for (const candidate of ordered) {
+      if (selected.length >= needed || selected.length >= targetCount) break;
+      if (minGapSeconds > 0 && violatesMinGap(candidate, selected, minGapSeconds)) continue;
+
+      const fallbackFrame = await buildFallbackFrame(candidate, selected, resolved, warnings);
+      if (!fallbackFrame) continue;
+
+      selected.push(fallbackFrame);
+      acceptedPaths.add(candidate.path);
+      added += 1;
+    }
+  }
+
+  return { accepted: selected, added };
+};
+
+export const toPublicFrame = (frame) => ({
+  path: frame.path,
+  timestamp: frame.timestamp,
+  hash: frame.hash,
+  score: {
+    minDistanceToRecentAccepted: frame.score.minDistanceToRecentAccepted,
+    acceptedReason: frame.score.acceptedReason,
+  },
+});
+
+export const violatesMinGap = (candidate, accepted, minGapSeconds) =>
+  accepted.some((frame) => Math.abs(candidate.timestamp - frame.timestamp) < minGapSeconds);
+
+const buildFallbackFrame = async (candidate, selected, resolved, warnings) => {
+  try {
+    if (!candidate.hash) candidate.hash = await getImageHash(candidate.path);
+  } catch (error) {
+    warnings.push(`Could not hash fallback frame ${candidate.path}: ${error.message}`);
+    return null;
+  }
+
+  const minDistance = selected.length > 0
+    ? getMinimumDistanceToAccepted(candidate.hash, selected, resolved.compareRecentCount)
+    : null;
+
+  return toAcceptedFrame(candidate, minDistance, 'fallback_even_coverage');
+};
+
+const toAcceptedFrame = (candidate, minDistanceToRecentAccepted, acceptedReason) => ({
+  path: candidate.path,
+  timestamp: candidate.timestamp,
+  hash: candidate.hash,
+  score: {
+    minDistanceToRecentAccepted,
+    acceptedReason,
+  },
+});
+
+const getMinimumDistanceToAccepted = (hash, accepted, compareRecentCount) => {
+  const comparisonSet = accepted.length <= compareRecentCount
+    ? accepted
+    : accepted.slice(-compareRecentCount);
+
+  return Math.min(...comparisonSet.map((frame) => hammingDistance(hash, frame.hash)));
+};
+
+const getFallbackGapAttempts = (minGapSeconds) => [
+  minGapSeconds,
+  minGapSeconds / 2,
+  minGapSeconds / 4,
+  0,
+];
+
+const orderCandidatesForEvenCoverage = (candidates, accepted, targetCount) => {
+  if (candidates.length <= 1) return candidates;
+
+  const acceptedTimestamps = accepted.map((frame) => frame.timestamp);
+
+  return [...candidates].sort((a, b) => {
+    const aDistance = distanceFromNearestTimestamp(a.timestamp, acceptedTimestamps);
+    const bDistance = distanceFromNearestTimestamp(b.timestamp, acceptedTimestamps);
+
+    if (bDistance !== aDistance) return bDistance - aDistance;
+
+    const aBucket = Math.floor((a.index / Math.max(1, candidates.length - 1)) * targetCount);
+    const bBucket = Math.floor((b.index / Math.max(1, candidates.length - 1)) * targetCount);
+
+    if (aBucket !== bBucket) return aBucket - bBucket;
+    return a.timestamp - b.timestamp;
+  });
+};
+
+const distanceFromNearestTimestamp = (timestamp, timestamps) => {
+  if (timestamps.length === 0) return Number.POSITIVE_INFINITY;
+
+  return Math.min(...timestamps.map((otherTimestamp) => Math.abs(timestamp - otherTimestamp)));
+};

package/src/frames/timestamps.js

@@ -0,0 +1,33 @@
+import { roundTimestamp } from '../shared/numbers.js';
+
+const EOF_MARGIN_MS = 50;
+const VERY_SHORT_WINDOW_MS = 100;
+
+export const generateCandidateTimestamps = (window, candidateCount) => {
+  const count = Math.max(1, Math.floor(candidateCount));
+  const startMs = Math.max(0, Math.round(window.startTimeMs));
+  const endMs = Math.max(startMs, Math.round(window.endTimeMs));
+  const windowDurationMs = endMs - startMs;
+
+  if (windowDurationMs <= VERY_SHORT_WINDOW_MS || count <= 1) {
+    return [roundTimestamp((startMs + windowDurationMs / 2) / 1000)];
+  }
+
+  const usableEndMs = Math.max(
+    startMs,
+    window.trimEndForEof ? endMs - EOF_MARGIN_MS : endMs,
+  );
+
+  if (usableEndMs <= startMs) {
+    return [roundTimestamp((startMs + windowDurationMs / 2) / 1000)];
+  }
+
+  const interval = (usableEndMs - startMs) / (count - 1);
+  const timestamps = [];
+
+  for (let index = 0; index < count; index += 1) {
+    timestamps.push(roundTimestamp((startMs + interval * index) / 1000));
+  }
+
+  return timestamps;
+};

package/src/index.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { main } from './cli/main.js';
+
+main().catch((error) => {
+  console.error(error.message || error);
+  process.exit(1);
+});