@suaveplan/video - Universal video metadata extraction, format detection, resolution math, transform pipeline planning, and a fluent pipeline builder

Universal video metadata extraction, magic-byte format detection, resolution math, transform-pipeline planning, and a fluent pipeline builder. Zero browser-only or Node-only imports — runs identically in Bun, Node, and modern browsers.

The package owns the planning half of the video stack: it sniffs container format from header bytes, validates user-supplied VideoMetadata, walks a VideoTransformPipeline and projects the output shape (dimensions, duration, format, audio presence). Actual codec work (transcoding, frame extraction, thumbnail render) is delegated to siblings — @suaveplan/video-thumbnails (ffmpeg) and @suaveplan/react-video (browser playback).

Documentation tree

detection — detectVideoFormat is a zero-dependency byte-pattern sniffer that returns the container format of a video buffer based…
- detection — detectVideoFormat is a zero-dependency byte-pattern sniffer that returns the container format of a video buffer based…
duration — This module owns the two-way conversion between a "seconds" number and a human-readable HH:MM:SS string. The pair is…
- duration — This module owns the two-way conversion between a "seconds" number and a human-readable HH:MM:SS string. The pair is…
error-codes — This module owns the stable, namespaced error-code registry for @suaveplan/video. Every failure thrown by the package…
- error-codes — This module owns the stable, namespaced error-code registry for @suaveplan/video. Every failure thrown by the package…
errors — This module exposes the typed VideoError class and the 16 factory functions every consumer of @suaveplan/video uses…
- errors — This module exposes the typed VideoError class and the 16 factory functions every consumer of @suaveplan/video uses…
format — videoFormatToExtension is a pure lookup that returns the canonical file-extension (including the leading dot) for a s…
- format — videoFormatToExtension is a pure lookup that returns the canonical file-extension (including the leading dot) for a s…
instruments — This module owns the OpenTelemetry instruments that VideoProcessor emits on every invocation. The instruments are laz…
- instruments — This module owns the OpenTelemetry instruments that VideoProcessor emits on every invocation. The instruments are laz…
pipeline-builder — VideoPipelineBuilder is the fluent surface for assembling a VideoTransformPipeline without having to construct the…
- pipeline-builder — VideoPipelineBuilder is the fluent surface for assembling a VideoTransformPipeline without having to construct the…
processor — VideoProcessor is the orchestration class for @suaveplan/video. It owns two operations — extractMetadata (read a…
- processor — VideoProcessor is the orchestration class for @suaveplan/video. It owns two operations — extractMetadata (read a…
resize — calculateVideoResize is the pure-math helper used by VideoProcessor.planTransform to project a resize operation o…
- resize — calculateVideoResize is the pure-math helper used by VideoProcessor.planTransform to project a resize operation o…
trim — validateTrimRange is the single source of truth for "does this trim range make sense for a video of length duration…
- trim — validateTrimRange is the single source of truth for "does this trim range make sense for a video of length duration…
video-types — This module is the type foundation for the entire @suaveplan/video package. Every public surface — VideoProcessor,…
- video-types — This module is the type foundation for the entire @suaveplan/video package. Every public surface — VideoProcessor,…

Install

bun add @suaveplan/video

Quick start

import { VideoProcessor } from "@suaveplan/video";

const proc = new VideoProcessor();
const meta = proc.extractMetadata(headerBytes, {
    width: 1920,
    height: 1080,
    duration: 60,
    frameRate: 30,
});

const result = proc
    .createPipeline()
    .resize({ preset: "720p" })
    .toFormat("webm")
    .codec("vp9")
    .apply(meta, proc);

console.log(result); // { width: 1280, height: 720, format: "webm", duration: 60, ... }

Features

8-format magic-byte sniffer (MP4 / MOV / MKV / AVI / FLV / OGG plus caller-hint paths for WMV / WEBM).
6-preset RESOLUTION_PRESETS and 8-entry VIDEO_MIME_TYPES lookup.
9-variant VideoTransformOp Zod discriminated union.
Even-dimension-rounded calculateVideoResize math.
Trim-range validator + duration round-trip string helpers.
VideoProcessor + VideoPipelineBuilder with EventBus-backed on / once / off.
16-code stable VIDEO_CODES registry plus VIDEO_ERROR_METADATA HTTP/severity/retry table.
OpenTelemetry counters + histograms + spans on every public method.
AbortSignal propagation on every public method.

Modules

error-codes — VIDEO_CODES, VIDEO_ERROR_METADATA, registerVideoErrorCodes.
errors — VideoError + 16 factory functions.
types/video-types — Zod schemas, inferred types, lookup tables.
detection — detectVideoFormat.
resize — calculateVideoResize.
trim — validateTrimRange.
duration — formatDuration, parseDuration.
format — videoFormatToExtension.
instruments — OTel counters, histograms, tracer.
processor — VideoProcessor.
pipeline-builder — VideoPipelineBuilder.

License

MIT