video-sampler 1.0.0

package/src/frames/extraction.js

@@ -0,0 +1,279 @@
+import { createRequire } from 'module';
+import { resolveBinaryPaths, runCommand } from '../shared/ffmpeg.js';
+import {
+  deleteFileQuietly,
+  fs,
+  getAvailableFilePath,
+  path,
+  uuidv4,
+} from '../shared/files.js';
+import { formatTimestamp } from '../shared/numbers.js';
+import { MIN_FRAME_BYTES } from './defaults.js';
+
+const require = createRequire(import.meta.url);
+const sharp = require('sharp');
+
+sharp.cache(false);
+
+export const extractCandidateFrames = async ({
+  videoPath,
+  timestamps,
+  outputDirectory,
+  imageFormat,
+  jpegQuality,
+  debug,
+  warnings,
+  createdFramePaths,
+  ffmpegPath,
+  videoDurationMs,
+}) => {
+  const candidates = [];
+  const timestampWarnings = [];
+  const naming = createCandidateNaming(timestamps.length, videoDurationMs);
+
+  for (let index = 0; index < timestamps.length; index += 1) {
+    const candidate = await extractCandidateFrame({
+      videoPath,
+      timestamp: timestamps[index],
+      outputDirectory,
+      imageFormat,
+      jpegQuality,
+      index,
+      debug,
+      warnings: timestampWarnings,
+      createdFramePaths,
+      ffmpegPath,
+      naming,
+    });
+
+    if (candidate) candidates.push(candidate);
+  }
+
+  if (candidates.length > 0) {
+    if (timestampWarnings.length > 0) {
+      warnings.push(
+        `Timestamp-based extraction skipped ${timestampWarnings.length} candidate frames that produced no image.`,
+      );
+    }
+
+    return candidates;
+  }
+
+  warnings.push(
+    `Timestamp-based frame extraction failed for all ${timestamps.length} candidates; retrying with sequential FPS extraction.`,
+  );
+
+  return extractSequentialCandidateFrames({
+    videoPath,
+    timestamps,
+    outputDirectory,
+    imageFormat,
+    jpegQuality,
+    debug,
+    warnings,
+    createdFramePaths,
+    ffmpegPath,
+    naming,
+  });
+};
+
+const extractCandidateFrame = async ({
+  videoPath,
+  timestamp,
+  outputDirectory,
+  imageFormat,
+  jpegQuality,
+  index,
+  debug,
+  warnings,
+  createdFramePaths,
+  ffmpegPath,
+  naming,
+}) => {
+  const outputPath = await getAvailableCandidatePath(
+    outputDirectory,
+    index,
+    timestamp,
+    imageFormat,
+    naming,
+  );
+  createdFramePaths.add(outputPath);
+
+  try {
+    await extractFrame(
+      videoPath,
+      timestamp,
+      outputPath,
+      imageFormat,
+      jpegQuality,
+      true,
+      debug,
+      ffmpegPath,
+    );
+    await validateImageFile(outputPath);
+    return { path: outputPath, timestamp, index };
+  } catch (fastSeekError) {
+    await deleteFileQuietly(outputPath);
+
+    try {
+      await extractFrame(
+        videoPath,
+        timestamp,
+        outputPath,
+        imageFormat,
+        jpegQuality,
+        false,
+        debug,
+        ffmpegPath,
+      );
+      await validateImageFile(outputPath);
+      return { path: outputPath, timestamp, index };
+    } catch (accurateSeekError) {
+      await deleteFileQuietly(outputPath);
+      warnings.push(
+        `Could not extract candidate frame at ${timestamp.toFixed(3)}s: ${accurateSeekError.message || fastSeekError.message}`,
+      );
+      return null;
+    }
+  }
+};
+
+const extractFrame = async (
+  videoPath,
+  timestamp,
+  outputPath,
+  imageFormat,
+  jpegQuality,
+  fastSeek,
+  debug,
+  ffmpegPath,
+) => {
+  const qualityArgs = imageFormat === 'jpg' ? ['-q:v', String(jpegQuality)] : [];
+  const outputArgs = ['-frames:v', '1', '-an', ...qualityArgs, outputPath];
+  const timestampText = formatTimestamp(timestamp);
+  const args = fastSeek
+    ? ['-hide_banner', '-y', '-ss', timestampText, '-i', videoPath, ...outputArgs]
+    : ['-hide_banner', '-y', '-i', videoPath, '-ss', timestampText, ...outputArgs];
+
+  const binaries = resolveBinaryPaths({ ffmpegPath });
+  const { stderr } = await runCommand(binaries.ffmpegPath, args);
+  if (debug && stderr.trim()) console.log('[ffmpeg]', stderr.trim());
+};
+
+const extractSequentialCandidateFrames = async ({
+  videoPath,
+  timestamps,
+  outputDirectory,
+  imageFormat,
+  jpegQuality,
+  debug,
+  warnings,
+  createdFramePaths,
+  ffmpegPath,
+  naming,
+}) => {
+  const tempPattern = path.join(outputDirectory, `candidate-${uuidv4()}-%04d.${imageFormat}`);
+  const fps = Math.max(1, Math.min(12, timestamps.length));
+  const qualityArgs = imageFormat === 'jpg' ? ['-q:v', String(jpegQuality)] : [];
+  const args = [
+    '-hide_banner',
+    '-y',
+    '-i',
+    videoPath,
+    '-map',
+    '0:v:0',
+    '-vf',
+    `fps=${fps}`,
+    '-frames:v',
+    String(timestamps.length),
+    ...qualityArgs,
+    tempPattern,
+  ];
+
+  const binaries = resolveBinaryPaths({ ffmpegPath });
+  const { stderr } = await runCommand(binaries.ffmpegPath, args);
+  if (debug && stderr.trim()) console.log('[ffmpeg sequential]', stderr.trim());
+
+  const extractedPaths = await findSequentialOutputs(tempPattern);
+  const candidates = [];
+
+  for (let index = 0; index < extractedPaths.length; index += 1) {
+    const originalPath = extractedPaths[index];
+    const timestamp = timestamps[Math.min(index, timestamps.length - 1)];
+    const outputPath = await getAvailableCandidatePath(
+      outputDirectory,
+      index,
+      timestamp,
+      imageFormat,
+      naming,
+    );
+    createdFramePaths.add(outputPath);
+
+    try {
+      await fs.promises.rename(originalPath, outputPath);
+      await validateImageFile(outputPath);
+      candidates.push({
+        path: outputPath,
+        timestamp,
+        index,
+      });
+    } catch (error) {
+      await deleteFileQuietly(originalPath);
+      await deleteFileQuietly(outputPath);
+      warnings.push(`Could not validate sequential fallback frame ${originalPath}: ${error.message}`);
+    }
+  }
+
+  if (candidates.length > 0 && candidates.length < timestamps.length) {
+    warnings.push(
+      `Sequential FPS fallback extracted ${candidates.length} of ${timestamps.length} requested candidate frames.`,
+    );
+  }
+
+  return candidates;
+};
+
+const findSequentialOutputs = async (tempPattern) => {
+  const directory = path.dirname(tempPattern);
+  const basename = path.basename(tempPattern);
+  const [prefix, suffix] = basename.split('%04d');
+  const entries = await fs.promises.readdir(directory);
+
+  return entries
+    .filter((entry) => entry.startsWith(prefix) && entry.endsWith(suffix))
+    .sort()
+    .map((entry) => path.join(directory, entry));
+};
+
+const createCandidateNaming = (candidateCount, videoDurationMs) => ({
+  indexDigits: Math.max(3, String(Math.max(1, candidateCount)).length),
+  timestampDigits: Math.max(6, String(Math.max(0, Math.round(videoDurationMs || 0))).length),
+});
+
+const getAvailableCandidatePath = async (
+  outputDirectory,
+  index,
+  timestamp,
+  imageFormat,
+  naming,
+) => {
+  const candidateNumber = String(index + 1).padStart(naming.indexDigits, '0');
+  const timestampMs = String(toTimestampMs(timestamp)).padStart(naming.timestampDigits, '0');
+
+  return getAvailableFilePath(
+    outputDirectory,
+    `candidate-${candidateNumber}-t${timestampMs}ms.${imageFormat}`,
+  );
+};
+
+const toTimestampMs = (timestampSeconds) => Math.max(0, Math.round(timestampSeconds * 1000));
+
+export const validateImageFile = async (imagePath) => {
+  const stat = await fs.promises.stat(imagePath);
+
+  if (!stat.isFile() || stat.size < MIN_FRAME_BYTES) {
+    throw new Error(`Extracted frame is missing or too small: ${imagePath}`);
+  }
+
+  await sharp(imagePath).metadata();
+};

package/src/frames/frameSampler.js

@@ -0,0 +1,190 @@
+import {
+  fs,
+  getAvailableFilePath,
+  path,
+  resolveOutputDirectory,
+} from '../shared/files.js';
+import { cleanupErroredFrames, cleanupRejectedCandidates } from './cleanup.js';
+import { extractCandidateFrames } from './extraction.js';
+import { rejectLowInformationFrames } from './lowInformation.js';
+import {
+  resolveOptions,
+  resolveSamplingCounts,
+  resolveSamplingWindow,
+} from './options.js';
+import { probeVideo } from './probe.js';
+import {
+  addFallbackFrames,
+  selectRepresentativeFrames,
+  toPublicFrame,
+} from './selection.js';
+import { generateCandidateTimestamps } from './timestamps.js';
+
+export const sampleFrames = async (videoPath, options = {}) => {
+  const warnings = [];
+  const resolved = resolveOptions(options, warnings);
+  const createdFramePaths = new Set();
+  const acceptedFramePaths = new Set();
+
+  try {
+    const video = await probeVideo(videoPath, { ffprobePath: resolved.ffprobePath });
+    const window = resolveSamplingWindow(video.durationSeconds, resolved, warnings);
+    const sampling = resolveSamplingCounts(window.durationSeconds, resolved);
+    const timestamps = generateCandidateTimestamps(window, sampling.candidateCount);
+    const outputDirectory = await resolveOutputDirectory(resolved.outputDir || process.cwd());
+    const candidates = await extractCandidateFrames({
+      videoPath,
+      timestamps,
+      outputDirectory,
+      imageFormat: resolved.imageFormat,
+      jpegQuality: resolved.jpegQuality,
+      debug: resolved.debug,
+      warnings,
+      createdFramePaths,
+      ffmpegPath: resolved.ffmpegPath,
+      videoDurationMs: window.videoDurationMs,
+    });
+
+    if (candidates.length === 0) {
+      throw new Error(`FFmpeg frame extraction failed completely for video: ${videoPath}`);
+    }
+
+    const lowInformation = await rejectLowInformationFrames(candidates, warnings);
+    const selection = await selectRepresentativeFrames(
+      lowInformation.usableCandidates,
+      sampling,
+      resolved,
+      warnings,
+    );
+
+    ensureSelectionSucceeded(selection, videoPath);
+
+    const fallback = await addFallbackIfNeeded({
+      accepted: selection.accepted,
+      candidates: lowInformation.usableCandidates,
+      sampling,
+      resolved,
+      warnings,
+    });
+    const accepted = fallback.accepted.sort((a, b) => a.timestamp - b.timestamp);
+    await renameAcceptedFrames(accepted, outputDirectory, resolved.imageFormat);
+
+    for (const frame of accepted) acceptedFramePaths.add(frame.path);
+    await cleanupRejectedCandidates(candidates, acceptedFramePaths, resolved.cleanupRejected);
+
+    return buildSamplerResult({
+      videoPath,
+      video,
+      outputDirectory,
+      sampling,
+      window,
+      resolved,
+      timestamps,
+      accepted,
+      selection,
+      lowInformation,
+      fallbackFramesAdded: fallback.added,
+      warnings,
+    });
+  } catch (error) {
+    await cleanupErroredFrames(createdFramePaths, acceptedFramePaths);
+    throw error;
+  }
+};
+
+const ensureSelectionSucceeded = (selection, videoPath) => {
+  if (selection.hashesAttempted > 0 && selection.hashesSucceeded === 0) {
+    throw new Error(`Image hash generation failed completely for extracted frames from: ${videoPath}`);
+  }
+
+  if (selection.accepted.length === 0) {
+    throw new Error(`No usable representative frames could be selected from video: ${videoPath}`);
+  }
+};
+
+const addFallbackIfNeeded = async ({ accepted, candidates, sampling, resolved, warnings }) => {
+  if (!resolved.includeFallbackFrames || accepted.length >= sampling.resolvedMinFrames) {
+    return { accepted, added: 0 };
+  }
+
+  return addFallbackFrames({
+    accepted,
+    candidates,
+    sampling,
+    resolved,
+    warnings,
+  });
+};
+
+const buildSamplerResult = ({
+  videoPath,
+  video,
+  outputDirectory,
+  sampling,
+  window,
+  resolved,
+  timestamps,
+  accepted,
+  selection,
+  lowInformation,
+  fallbackFramesAdded,
+  warnings,
+}) => ({
+  video: {
+    path: videoPath,
+    durationSeconds: video.durationSeconds,
+    width: video.width,
+    height: video.height,
+    fps: video.fps,
+  },
+  output: {
+    directory: outputDirectory,
+  },
+  options: {
+    resolvedTargetFrames: sampling.resolvedTargetFrames,
+    maxFrames: resolved.maxFrames,
+    minFrames: sampling.resolvedMinFrames,
+    minGapMs: resolved.minGapMs,
+    startTimeMs: Math.round(window.startTimeMs),
+    endBeforeMs: Math.round(window.endBeforeMs),
+    candidateCount: timestamps.length,
+    similarityThreshold: resolved.similarityThreshold,
+  },
+  frames: accepted.map(toPublicFrame),
+  stats: {
+    candidatesExtracted: lowInformation.usableCandidates.length + lowInformation.rejectedLowInformation,
+    candidatesRejectedAsSimilar: selection.candidatesRejectedAsSimilar,
+    candidatesRejectedForSpacing: selection.candidatesRejectedForSpacing,
+    candidatesRejectedAsLowInformation: lowInformation.rejectedLowInformation,
+    fallbackFramesAdded,
+    returnedFrames: accepted.length,
+  },
+  warnings,
+});
+
+const renameAcceptedFrames = async (frames, outputDirectory, imageFormat) => {
+  const frameDigits = Math.max(3, String(frames.length).length);
+  const timestampDigits = Math.max(
+    6,
+    ...frames.map((frame) => String(toTimestampMs(frame.timestamp)).length),
+  );
+
+  for (let index = 0; index < frames.length; index += 1) {
+    const frame = frames[index];
+    const frameNumber = String(index + 1).padStart(frameDigits, '0');
+    const timestampMs = String(toTimestampMs(frame.timestamp)).padStart(timestampDigits, '0');
+    const destination = await getAvailableFilePath(
+      outputDirectory,
+      `frame-${frameNumber}-t${timestampMs}ms.${imageFormat}`,
+    );
+
+    if (path.resolve(frame.path) === destination) continue;
+
+    await fs.promises.rename(frame.path, destination);
+    frame.path = destination;
+  }
+};
+
+const toTimestampMs = (timestampSeconds) => Math.max(0, Math.round(timestampSeconds * 1000));
+
+export const sampleRepresentativeFrames = sampleFrames;

package/src/frames/hash.js

@@ -0,0 +1,46 @@
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+const sharp = require('sharp');
+const phash = require('sharp-phash');
+
+sharp.cache(false);
+
+export const getImageHash = async (imagePath) => {
+  const hash = await phash(imagePath);
+
+  if (typeof hash === 'string') return hash;
+  if (typeof hash === 'bigint') return hash.toString(2).padStart(64, '0');
+
+  throw new Error(`Unsupported perceptual hash return type: ${typeof hash}`);
+};
+
+export const hammingDistance = (hashA, hashB) => {
+  if (typeof hashA !== 'string' || typeof hashB !== 'string') {
+    throw new Error('Cannot compare non-string perceptual hashes.');
+  }
+
+  const binaryA = normalizeHashToBinary(hashA);
+  const binaryB = normalizeHashToBinary(hashB);
+  const length = Math.min(binaryA.length, binaryB.length);
+  let distance = Math.abs(binaryA.length - binaryB.length);
+
+  for (let index = 0; index < length; index += 1) {
+    if (binaryA[index] !== binaryB[index]) distance += 1;
+  }
+
+  return distance;
+};
+
+const normalizeHashToBinary = (hash) => {
+  if (/^[01]+$/.test(hash)) return hash;
+
+  if (/^[a-f0-9]+$/i.test(hash)) {
+    return hash
+      .split('')
+      .map((char) => parseInt(char, 16).toString(2).padStart(4, '0'))
+      .join('');
+  }
+
+  return hash;
+};

package/src/frames/lowInformation.js

@@ -0,0 +1,52 @@
+import { createRequire } from 'module';
+import { average } from '../shared/numbers.js';
+
+const require = createRequire(import.meta.url);
+const sharp = require('sharp');
+
+sharp.cache(false);
+
+export const rejectLowInformationFrames = async (candidates, warnings) => {
+  const usableCandidates = [];
+  let rejectedLowInformation = 0;
+
+  for (const candidate of candidates) {
+    try {
+      const lowInfo = await getLowInformationReason(candidate.path);
+
+      if (lowInfo) {
+        candidate.lowInformationReason = lowInfo;
+        rejectedLowInformation += 1;
+      } else {
+        usableCandidates.push(candidate);
+      }
+    } catch (error) {
+      candidate.lowInformationReason = 'stats_failed';
+      rejectedLowInformation += 1;
+      warnings.push(`Could not inspect candidate frame ${candidate.path}: ${error.message}`);
+    }
+  }
+
+  if (rejectedLowInformation > 0 && rejectedLowInformation >= Math.ceil(candidates.length / 2)) {
+    warnings.push(`${rejectedLowInformation} candidate frames were rejected as low-information.`);
+  }
+
+  if (usableCandidates.length === 0) {
+    throw new Error('No usable frames could be extracted; all candidates were low-information or unreadable.');
+  }
+
+  return { usableCandidates, rejectedLowInformation };
+};
+
+const getLowInformationReason = async (imagePath) => {
+  const stats = await sharp(imagePath).stats();
+  const channels = stats.channels.slice(0, 3);
+  const mean = average(channels.map((channel) => channel.mean));
+  const stdev = average(channels.map((channel) => channel.stdev));
+
+  if (mean <= 8 && stdev <= 12) return 'mostly_black';
+  if (mean >= 247 && stdev <= 12) return 'mostly_white';
+  if (stdev <= 2.5) return 'extremely_low_variance';
+
+  return null;
+};