vidpeek 0.1.0

package/License

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Piero Alessandro Postigo Rocchetti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# VidPeek
+
+Generate previews. Not FFmpeg headaches.
+
+Modern typed video preview generation for Node and CLI. VidPeek turns videos into lightweight animated previews using FFmpeg, with clean presets, safe temp handling, typed options, and a CLI designed for media apps.
+
+## Installation
+
+```bash
+pnpm add vidpeek
+```
+
+```bash
+npm install vidpeek
+```
+
+## FFmpeg Requirement
+
+VidPeek uses FFmpeg and FFprobe under the hood. Install both and make sure `ffmpeg` and `ffprobe` are available on your `PATH`, or pass custom binary paths with `--ffmpeg-path`, `--ffprobe-path`, `ffmpegPath`, and `ffprobePath`.
+
+## CLI Usage
+
+```bash
+vidpeek input.mp4 --out preview.webp
+```
+
+```bash
+vidpeek input.mp4 \
+  --out preview.webp \
+  --preset web \
+  --strategy evenly-spaced \
+  --clips 5 \
+  --clip-duration 2 \
+  --width 320 \
+  --fps 10
+```
+
+Print JSON for application workflows:
+
+```bash
+vidpeek input.mp4 --out preview.webp --json
+```
+
+## Node API
+
+```ts
+import { generatePreview } from "vidpeek";
+
+await generatePreview({
+  input: "video.mp4",
+  output: "preview.webp",
+  preset: "web",
+  strategy: "evenly-spaced",
+  clips: {
+    count: 5,
+    duration: 2,
+  },
+  width: 320,
+  fps: 10,
+});
+```
+
+## Presets
+
+| Preset | Format | Width | FPS | Clips | Clip duration |
+| --- | --- | ---: | ---: | ---: | ---: |
+| `tiny` | `webp` | 240 | 8 | 4 | 1.5s |
+| `web` | `webp` | 320 | 10 | 5 | 2s |
+| `discord` | `webp` | 360 | 12 | 4 | 2s |
+| `high-quality` | `webp` | 480 | 15 | 6 | 2s |
+
+## Options
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `input` | `string` | Input video path. |
+| `output` | `string` | Output preview path. |
+| `format` | `"webp" \| "gif" \| "mp4"` | Output format. Defaults from the selected preset. |
+| `preset` | `"tiny" \| "web" \| "discord" \| "high-quality"` | Preview preset. Defaults to `web`. |
+| `strategy` | `"evenly-spaced" \| "random" \| "manual"` | Segment selection strategy. Defaults to `evenly-spaced`. |
+| `clips.count` | `number` | Number of clips to sample. |
+| `clips.duration` | `number` | Duration of each sampled clip in seconds. |
+| `clips.range` | `[number, number]` | Normalized sampling range. Defaults to `[0.05, 0.95]`. |
+| `clips.segments` | `{ start: number; duration: number }[]` | Required for manual segment selection. |
+| `width` | `number` | Output width. |
+| `height` | `number` | Output height. |
+| `fps` | `number` | Output frames per second. |
+| `speed` | `number` | Preview speed multiplier. |
+| `overwrite` | `boolean` | Replace an existing output file. |
+| `keepTemp` | `boolean` | Keep the temporary work directory for debugging. |
+| `ffmpegPath` | `string` | Custom FFmpeg binary path. |
+| `ffprobePath` | `string` | Custom FFprobe binary path. |
+
+## Benchmark
+
+Place a sample video at `benchmarks/fixtures/sample.mp4`, then run:
+
+```bash
+pnpm bench
+```
+
+The benchmark generates `tiny`, `web`, and `high-quality` previews and prints elapsed time plus output file size.
+
+## Why VidPeek
+
+- Typed API for Node apps.
+- CLI and library from the same core pipeline.
+- Safe per-run temp directories.
+- No shell command strings.
+- Readable FFmpeg and FFprobe errors.
+- Useful presets for real media product workflows.
+
+## Roadmap
+
+- Scene-change strategy.
+- Contact sheets.
+- Sprites.
+- AVIF previews.
+- Worker and concurrency options.
+
+## License
+
+MIT

package/dist/chunk-KVP6XIDZ.js

@@ -0,0 +1,457 @@
+// src/core/generate-preview.ts
+import { access, mkdir, stat, writeFile } from "fs/promises";
+import path2 from "path";
+
+// src/core/errors.ts
+var VidPeekError = class extends Error {
+  code;
+  command;
+  exitCode;
+  stderr;
+  constructor(message, options = {}) {
+    super(message);
+    this.name = "VidPeekError";
+    this.code = options.code;
+    this.command = options.command;
+    this.exitCode = options.exitCode;
+    this.stderr = options.stderr;
+    if (options.cause) {
+      this.cause = options.cause;
+    }
+  }
+};
+function toVidPeekError(error) {
+  if (error instanceof VidPeekError) {
+    return error;
+  }
+  if (error instanceof Error) {
+    return new VidPeekError(error.message, { cause: error });
+  }
+  return new VidPeekError(String(error));
+}
+
+// src/core/ffmpeg.ts
+import { spawn } from "child_process";
+function quoteArg(arg) {
+  if (/^[a-zA-Z0-9_./:=+-]+$/.test(arg)) {
+    return arg;
+  }
+  return JSON.stringify(arg);
+}
+function formatCommand(binary, args) {
+  return [binary, ...args].map(quoteArg).join(" ");
+}
+async function runProcess({
+  binary,
+  args,
+  label = binary
+}) {
+  const command = formatCommand(binary, args);
+  return new Promise((resolve, reject) => {
+    const child = spawn(binary, args, {
+      windowsHide: true,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on("error", (error) => {
+      reject(
+        new VidPeekError(
+          `${label} could not be started. Is it installed and available on PATH?`,
+          {
+            code: error.code ?? "PROCESS_START_FAILED",
+            command,
+            stderr,
+            cause: error
+          }
+        )
+      );
+    });
+    child.on("close", (exitCode) => {
+      if (exitCode === 0) {
+        resolve({ stdout, stderr });
+        return;
+      }
+      const stderrText = stderr.trim();
+      reject(
+        new VidPeekError(
+          `${label} failed with exit code ${exitCode}.
+Command: ${command}${stderrText ? `
+
+${stderrText}` : ""}`,
+          {
+            code: "PROCESS_FAILED",
+            command,
+            exitCode,
+            stderr
+          }
+        )
+      );
+    });
+  });
+}
+function runFfmpeg(args, ffmpegPath = "ffmpeg") {
+  return runProcess({ binary: ffmpegPath, args, label: "FFmpeg" });
+}
+
+// src/core/ffprobe.ts
+function parseDuration(value) {
+  if (!value) {
+    return void 0;
+  }
+  const duration = Number(value);
+  return Number.isFinite(duration) && duration > 0 ? duration : void 0;
+}
+async function probeVideo(input, ffprobePath = "ffprobe") {
+  const { stdout } = await runProcess({
+    binary: ffprobePath,
+    label: "FFprobe",
+    args: ["-v", "error", "-show_format", "-show_streams", "-of", "json", input]
+  });
+  let data;
+  try {
+    data = JSON.parse(stdout);
+  } catch (error) {
+    throw new VidPeekError("FFprobe returned invalid JSON.", {
+      code: "INVALID_FFPROBE_JSON",
+      cause: error
+    });
+  }
+  const duration = parseDuration(data.format?.duration) ?? parseDuration(data.streams?.find((stream) => stream.codec_type === "video")?.duration);
+  if (!duration) {
+    throw new VidPeekError("Could not read video duration from FFprobe output.", {
+      code: "MISSING_DURATION"
+    });
+  }
+  return { duration };
+}
+
+// src/core/presets.ts
+import { z } from "zod";
+var PRESETS = {
+  tiny: {
+    format: "webp",
+    width: 240,
+    fps: 8,
+    clips: { count: 4, duration: 1.5 }
+  },
+  web: {
+    format: "webp",
+    width: 320,
+    fps: 10,
+    clips: { count: 5, duration: 2 }
+  },
+  discord: {
+    format: "webp",
+    width: 360,
+    fps: 12,
+    clips: { count: 4, duration: 2 }
+  },
+  "high-quality": {
+    format: "webp",
+    width: 480,
+    fps: 15,
+    clips: { count: 6, duration: 2 }
+  }
+};
+var manualSegmentSchema = z.object({
+  start: z.number().finite().min(0),
+  duration: z.number().finite().positive()
+});
+var optionsSchema = z.object({
+  input: z.string().min(1, "input is required"),
+  output: z.string().min(1, "output is required"),
+  format: z.enum(["webp", "gif", "mp4"]).optional(),
+  preset: z.enum(["tiny", "web", "discord", "high-quality"]).optional(),
+  strategy: z.enum(["evenly-spaced", "random", "manual"]).optional(),
+  clips: z.object({
+    count: z.number().int().positive().optional(),
+    duration: z.number().finite().positive().optional(),
+    range: z.tuple([z.number().finite(), z.number().finite()]).refine(([start, end]) => start >= 0 && end <= 1 && start < end, {
+      message: "range must be [start,end] normalized between 0 and 1 with start < end"
+    }).optional(),
+    segments: z.array(manualSegmentSchema).nonempty().optional()
+  }).optional(),
+  width: z.number().int().positive().optional(),
+  height: z.number().int().positive().optional(),
+  fps: z.number().finite().positive().optional(),
+  speed: z.number().finite().positive().optional(),
+  overwrite: z.boolean().optional(),
+  keepTemp: z.boolean().optional(),
+  ffmpegPath: z.string().min(1).optional(),
+  ffprobePath: z.string().min(1).optional()
+});
+function resolveOptions(options) {
+  const parsed = optionsSchema.safeParse(options);
+  if (!parsed.success) {
+    const message = parsed.error.issues.map((issue) => issue.message).join("; ");
+    throw new VidPeekError(`Invalid VidPeek options: ${message}`, {
+      code: "INVALID_OPTIONS"
+    });
+  }
+  const presetName = parsed.data.preset ?? "web";
+  const preset = PRESETS[presetName];
+  const clips = {
+    count: parsed.data.clips?.count ?? preset.clips.count,
+    duration: parsed.data.clips?.duration ?? preset.clips.duration,
+    range: parsed.data.clips?.range ?? [0.05, 0.95],
+    segments: parsed.data.clips?.segments
+  };
+  const strategy = parsed.data.strategy ?? "evenly-spaced";
+  if (strategy === "manual" && !clips.segments?.length) {
+    throw new VidPeekError("Manual strategy requires clips.segments.", {
+      code: "MISSING_MANUAL_SEGMENTS"
+    });
+  }
+  return {
+    ...parsed.data,
+    format: parsed.data.format ?? preset.format,
+    preset: presetName,
+    strategy,
+    clips,
+    width: parsed.data.width ?? preset.width,
+    fps: parsed.data.fps ?? preset.fps,
+    speed: parsed.data.speed ?? 1,
+    overwrite: parsed.data.overwrite ?? false,
+    keepTemp: parsed.data.keepTemp ?? false,
+    ffmpegPath: parsed.data.ffmpegPath ?? "ffmpeg",
+    ffprobePath: parsed.data.ffprobePath ?? "ffprobe"
+  };
+}
+
+// src/core/segments.ts
+function clamp(value, min, max) {
+  return Math.min(Math.max(value, min), max);
+}
+function clampSegment(segment, duration, index) {
+  if (segment.duration <= 0) {
+    throw new VidPeekError("Segment duration must be greater than zero.", {
+      code: "INVALID_SEGMENT"
+    });
+  }
+  if (segment.start < 0) {
+    throw new VidPeekError("Segment start must be zero or greater.", {
+      code: "INVALID_SEGMENT"
+    });
+  }
+  if (segment.start >= duration) {
+    throw new VidPeekError("Segment start must be before the end of the video.", {
+      code: "INVALID_SEGMENT"
+    });
+  }
+  const start = clamp(segment.start, 0, Math.max(duration - 1e-3, 0));
+  const availableDuration = Math.max(duration - start, 1e-3);
+  return {
+    index,
+    start,
+    duration: Math.min(segment.duration, availableDuration)
+  };
+}
+function selectEvenlySpaced(duration, count, clipDuration, range) {
+  const maxStart = Math.max(duration - Math.min(clipDuration, duration), 0);
+  const rangeStart = clamp(duration * range[0], 0, maxStart);
+  const rangeEnd = clamp(duration * range[1], rangeStart, maxStart);
+  const window = rangeEnd - rangeStart;
+  return Array.from({ length: count }, (_, index) => {
+    const start = count === 1 ? rangeStart + window / 2 : rangeStart + window * index / (count - 1);
+    return clampSegment({ start, duration: clipDuration }, duration, index);
+  });
+}
+function selectRandom(duration, count, clipDuration, range) {
+  const maxStart = Math.max(duration - Math.min(clipDuration, duration), 0);
+  const rangeStart = clamp(duration * range[0], 0, maxStart);
+  const rangeEnd = clamp(duration * range[1], rangeStart, maxStart);
+  return Array.from({ length: count }, (_, index) => {
+    const start = rangeStart + Math.random() * (rangeEnd - rangeStart);
+    return clampSegment({ start, duration: clipDuration }, duration, index);
+  }).sort((a, b) => a.start - b.start);
+}
+function selectSegments(duration, options) {
+  if (!Number.isFinite(duration) || duration <= 0) {
+    throw new VidPeekError("Video duration must be greater than zero.", {
+      code: "INVALID_DURATION"
+    });
+  }
+  if (options.strategy === "manual") {
+    if (!options.clips.segments?.length) {
+      throw new VidPeekError("Manual strategy requires clips.segments.", {
+        code: "MISSING_MANUAL_SEGMENTS"
+      });
+    }
+    return options.clips.segments.map(
+      (segment, index) => clampSegment(segment, duration, index)
+    );
+  }
+  if (options.strategy === "random") {
+    return selectRandom(
+      duration,
+      options.clips.count,
+      options.clips.duration,
+      options.clips.range
+    );
+  }
+  return selectEvenlySpaced(
+    duration,
+    options.clips.count,
+    options.clips.duration,
+    options.clips.range
+  );
+}
+
+// src/core/temp.ts
+import { mkdtemp, rm } from "fs/promises";
+import { tmpdir } from "os";
+import path from "path";
+async function createTempDir() {
+  return mkdtemp(path.join(tmpdir(), "vidpeek-"));
+}
+async function cleanupTempDir(tempDir) {
+  await rm(tempDir, { recursive: true, force: true });
+}
+
+// src/core/generate-preview.ts
+function formatSeconds(value) {
+  return value.toFixed(3);
+}
+function buildVideoFilters(options) {
+  const filters = [];
+  if (options.fps) {
+    filters.push(`fps=${options.fps}`);
+  }
+  if (options.width && options.height) {
+    filters.push(`scale=${options.width}:${options.height}`);
+  } else if (options.width) {
+    filters.push(`scale=${options.width}:-2`);
+  } else if (options.height) {
+    filters.push(`scale=-2:${options.height}`);
+  }
+  if (options.speed && options.speed !== 1) {
+    filters.push(`setpts=${1 / options.speed}*PTS`);
+  }
+  return filters;
+}
+function overwriteArgs(overwrite) {
+  return [overwrite ? "-y" : "-n"];
+}
+function concatFilePath(filePath) {
+  const normalized = filePath.replace(/\\/g, "/");
+  return `file '${normalized.replace(/'/g, "'\\''")}'`;
+}
+async function assertCanWriteOutput(output, overwrite) {
+  if (overwrite) {
+    return;
+  }
+  try {
+    await access(output);
+  } catch {
+    return;
+  }
+  throw new VidPeekError(`Output already exists: ${output}. Pass overwrite: true to replace it.`, {
+    code: "OUTPUT_EXISTS"
+  });
+}
+async function fileSize(filePath) {
+  return (await stat(filePath)).size;
+}
+async function transcodeFinal(options) {
+  const args = [...overwriteArgs(options.overwrite), "-i", options.input, "-an"];
+  if (options.filters.length > 0) {
+    args.push("-vf", options.filters.join(","));
+  }
+  if (options.format === "webp") {
+    args.push("-loop", "0", "-c:v", "libwebp", "-quality", "80", options.output);
+  } else if (options.format === "gif") {
+    args.push("-f", "gif", options.output);
+  } else {
+    args.push(
+      "-c:v",
+      "libx264",
+      "-pix_fmt",
+      "yuv420p",
+      "-movflags",
+      "+faststart",
+      options.output
+    );
+  }
+  await runFfmpeg(args, options.ffmpegPath);
+}
+async function generatePreview(options) {
+  const startedAt = performance.now();
+  const resolved = resolveOptions(options);
+  const tempDir = await createTempDir();
+  try {
+    await assertCanWriteOutput(resolved.output, resolved.overwrite);
+    await mkdir(path2.dirname(resolved.output), { recursive: true });
+    const metadata = await probeVideo(resolved.input, resolved.ffprobePath);
+    const segments = selectSegments(metadata.duration, resolved);
+    const clipPaths = [];
+    for (const segment of segments) {
+      const clipPath = path2.join(tempDir, `clip-${String(segment.index + 1).padStart(3, "0")}.mp4`);
+      await runFfmpeg(
+        [
+          "-y",
+          "-ss",
+          formatSeconds(segment.start),
+          "-t",
+          formatSeconds(segment.duration),
+          "-i",
+          resolved.input,
+          "-an",
+          "-c:v",
+          "libx264",
+          "-preset",
+          "veryfast",
+          "-pix_fmt",
+          "yuv420p",
+          clipPath
+        ],
+        resolved.ffmpegPath
+      );
+      clipPaths.push(clipPath);
+    }
+    const fileListPath = path2.join(tempDir, "filelist.txt");
+    await writeFile(fileListPath, `${clipPaths.map(concatFilePath).join("\n")}
+`, "utf8");
+    const mergedPath = path2.join(tempDir, "merged.mp4");
+    await runFfmpeg(
+      ["-y", "-f", "concat", "-safe", "0", "-i", fileListPath, "-c", "copy", mergedPath],
+      resolved.ffmpegPath
+    );
+    await transcodeFinal({
+      input: mergedPath,
+      output: resolved.output,
+      format: resolved.format,
+      filters: buildVideoFilters(resolved),
+      overwrite: resolved.overwrite,
+      ffmpegPath: resolved.ffmpegPath
+    });
+    await fileSize(resolved.output);
+    return {
+      output: resolved.output,
+      format: resolved.format,
+      duration: metadata.duration,
+      segments,
+      elapsedMs: Math.round(performance.now() - startedAt)
+    };
+  } catch (error) {
+    throw toVidPeekError(error);
+  } finally {
+    if (!resolved.keepTemp) {
+      await cleanupTempDir(tempDir);
+    }
+  }
+}
+
+export {
+  VidPeekError,
+  toVidPeekError,
+  generatePreview
+};

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import {
+  generatePreview,
+  toVidPeekError
+} from "./chunk-KVP6XIDZ.js";
+
+// src/cli.ts
+import { Command } from "commander";
+function parsePositiveNumber(value, name) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`${name} must be a positive number.`);
+  }
+  return parsed;
+}
+function parsePositiveInteger(value, name) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`${name} must be a positive integer.`);
+  }
+  return parsed;
+}
+function parseRange(value) {
+  const parts = value.split(",").map((part) => Number(part.trim()));
+  if (parts.length !== 2 || parts.some((part) => !Number.isFinite(part)) || parts[0] < 0 || parts[1] > 1 || parts[0] >= parts[1]) {
+    throw new Error("--range must be formatted as start,end with values from 0 to 1.");
+  }
+  return [parts[0], parts[1]];
+}
+function toGenerateOptions(input, cli) {
+  if (!cli.out) {
+    throw new Error("--out is required.");
+  }
+  return {
+    input,
+    output: cli.out,
+    preset: cli.preset,
+    strategy: cli.strategy,
+    format: cli.format,
+    clips: {
+      count: cli.clips ? parsePositiveInteger(cli.clips, "--clips") : void 0,
+      duration: cli.clipDuration ? parsePositiveNumber(cli.clipDuration, "--clip-duration") : void 0,
+      range: cli.range ? parseRange(cli.range) : void 0
+    },
+    width: cli.width ? parsePositiveInteger(cli.width, "--width") : void 0,
+    height: cli.height ? parsePositiveInteger(cli.height, "--height") : void 0,
+    fps: cli.fps ? parsePositiveNumber(cli.fps, "--fps") : void 0,
+    speed: cli.speed ? parsePositiveNumber(cli.speed, "--speed") : void 0,
+    overwrite: cli.overwrite,
+    keepTemp: cli.keepTemp,
+    ffmpegPath: cli.ffmpegPath,
+    ffprobePath: cli.ffprobePath
+  };
+}
+var program = new Command();
+program.name("vidpeek").description("A modern typed FFmpeg preview generator for Node and CLI.").argument("<input>", "input video path").requiredOption("--out <path>", "output preview path").option("--preset <preset>", "tiny, web, discord, or high-quality").option("--strategy <strategy>", "evenly-spaced, random, or manual").option("--clips <number>", "number of clips to sample").option("--clip-duration <seconds>", "duration of each sampled clip").option("--range <start,end>", "normalized sampling range, for example 0.05,0.95").option("--width <number>", "output width").option("--height <number>", "output height").option("--fps <number>", "output frames per second").option("--speed <number>", "preview speed multiplier").option("--format <format>", "webp, gif, or mp4").option("--overwrite", "replace output if it already exists").option("--keep-temp", "keep temporary working directory").option("--ffmpeg-path <path>", "custom ffmpeg binary path").option("--ffprobe-path <path>", "custom ffprobe binary path").option("--json", "print machine-readable result JSON").action(async (input, cli) => {
+  try {
+    const result = await generatePreview(toGenerateOptions(input, cli));
+    if (cli.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    console.log(`VidPeek generated ${result.format} preview: ${result.output}`);
+    console.log(`Duration: ${result.duration.toFixed(2)}s`);
+    console.log(`Segments: ${result.segments.length}`);
+    console.log(`Elapsed: ${result.elapsedMs}ms`);
+  } catch (error) {
+    const vidPeekError = toVidPeekError(error);
+    if (cli.json) {
+      console.error(
+        JSON.stringify(
+          {
+            error: vidPeekError.message,
+            code: vidPeekError.code,
+            command: vidPeekError.command,
+            exitCode: vidPeekError.exitCode
+          },
+          null,
+          2
+        )
+      );
+    } else {
+      console.error(`VidPeek error: ${vidPeekError.message}`);
+    }
+    process.exitCode = 1;
+  }
+});
+await program.parseAsync();

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+type PreviewFormat = "webp" | "gif" | "mp4";
+type SegmentStrategy = "evenly-spaced" | "random" | "manual";
+type VidPeekPreset = "tiny" | "web" | "discord" | "high-quality";
+interface ManualSegment {
+    start: number;
+    duration: number;
+}
+interface GeneratePreviewOptions {
+    input: string;
+    output: string;
+    format?: PreviewFormat;
+    preset?: VidPeekPreset;
+    strategy?: SegmentStrategy;
+    clips?: {
+        count?: number;
+        duration?: number;
+        range?: [number, number];
+        segments?: ManualSegment[];
+    };
+    width?: number;
+    height?: number;
+    fps?: number;
+    speed?: number;
+    overwrite?: boolean;
+    keepTemp?: boolean;
+    ffmpegPath?: string;
+    ffprobePath?: string;
+}
+interface SelectedSegment extends ManualSegment {
+    index: number;
+}
+interface GeneratePreviewResult {
+    output: string;
+    format: PreviewFormat;
+    duration: number;
+    segments: SelectedSegment[];
+    elapsedMs: number;
+}
+
+declare function generatePreview(options: GeneratePreviewOptions): Promise<GeneratePreviewResult>;
+
+interface VidPeekErrorOptions {
+    code?: string;
+    command?: string;
+    exitCode?: number | null;
+    stderr?: string;
+    cause?: unknown;
+}
+declare class VidPeekError extends Error {
+    readonly code?: string;
+    readonly command?: string;
+    readonly exitCode?: number | null;
+    readonly stderr?: string;
+    constructor(message: string, options?: VidPeekErrorOptions);
+}
+
+export { type GeneratePreviewOptions, type GeneratePreviewResult, type ManualSegment, type PreviewFormat, type SegmentStrategy, type SelectedSegment, VidPeekError, type VidPeekPreset, generatePreview };

package/dist/index.js

@@ -0,0 +1,8 @@
+import {
+  VidPeekError,
+  generatePreview
+} from "./chunk-KVP6XIDZ.js";
+export {
+  VidPeekError,
+  generatePreview
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "vidpeek",
+  "version": "0.1.0",
+  "description": "A modern typed FFmpeg preview generator for Node and CLI.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "vidpeek": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/postigodev/vidpeek.git"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/cli.ts --format esm --dts --clean",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "bench": "tsx benchmarks/run.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "ffmpeg",
+    "video",
+    "preview",
+    "webp",
+    "gif",
+    "cli"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "packageManager": "pnpm@9.15.0",
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12.1.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.1.0",
+    "tsx": "^4.16.5",
+    "tsup": "^8.2.4",
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5"
+  }
+}