@better-media/plugin-video-processing 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 abenezeratnafu
+
+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, NEGLIGENCE OR OTHER TORTIOUS
+ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE
+SOFTWARE.

package/dist/index.d.mts

@@ -0,0 +1,88 @@
+import { PipelinePlugin } from '@better-media/core';
+
+/** A single thumbnail to extract from the video. */
+interface ThumbnailPreset {
+    /**
+     * Position to extract.
+     * - number: seconds from start (e.g. 5 = 5s)
+     * - string ending with "%": percentage of total duration (e.g. "10%")
+     * - other string: parsed as seconds (e.g. "5.5")
+     */
+    at: number | string;
+    /** Output image format. Default: "jpeg". */
+    format?: "jpeg" | "png" | "webp";
+    /** Output width in pixels. Aspect ratio preserved when only one dimension is set. */
+    width?: number;
+    /** Output height in pixels. */
+    height?: number;
+}
+/** A single transcode target. */
+interface TranscodePreset {
+    /** Identifier used in storage key and media_versions. Must be stable. */
+    name: string;
+    /** Output container format. */
+    format: "mp4" | "webm";
+    /** Video codec. Defaults: libx264 (mp4), libvpx-vp9 (webm). */
+    videoCodec?: string;
+    /** Audio codec. Defaults: aac (mp4), libopus (webm). */
+    audioCodec?: string;
+    /** Video bitrate, e.g. "1000k". */
+    videoBitrate?: string;
+    /** Audio bitrate, e.g. "128k". */
+    audioBitrate?: string;
+    /** Resolution as "WxH", e.g. "1280x720". Omit to keep source resolution. */
+    resolution?: string;
+}
+interface VideoProcessingPluginOptions {
+    /** Execution mode. Default: "background". */
+    executionMode?: "sync" | "background";
+    /**
+     * Thumbnail presets to extract.
+     * Pass `false` to disable thumbnail extraction entirely.
+     * Default: one JPEG at 10% of duration, 640px wide.
+     */
+    thumbnails?: ThumbnailPreset[] | false;
+    /**
+     * Transcode presets to produce. Omit or pass an empty array for no transcoding.
+     * Each preset produces one output file stored as a media_versions row.
+     */
+    transcode?: TranscodePreset[];
+    /** Only process files whose mimeType is in this list. Default: common video types. */
+    allowedMimeTypes?: string[];
+    /**
+     * Skip the plugin if the source file is larger than this (bytes).
+     * Useful for very large uploads that shouldn't block the sync path.
+     * Default: no limit.
+     */
+    maxInputBytes?: number;
+    /** Override the ffmpeg binary path. Default: resolved from PATH. */
+    ffmpegPath?: string;
+    /** Override the ffprobe binary path. Default: resolved from PATH. */
+    ffprobePath?: string;
+    /** Storage key prefix for derivative files. Default: "processing". */
+    derivativePrefix?: string;
+    /**
+     * Insert rows into media_versions for thumbnails and transcoded outputs.
+     * Default: true.
+     */
+    persistMediaVersions?: boolean;
+    /**
+     * Skip a thumbnail or transcode if the storage key already exists.
+     * Default: true.
+     */
+    skipExistingDerivatives?: boolean;
+    /** Timeout for the full processing run in milliseconds. Default: 300_000 (5 min). */
+    timeoutMs?: number;
+}
+
+declare const DEFAULT_THUMBNAIL_PRESETS: ThumbnailPreset[];
+declare const DEFAULT_VIDEO_MIME_TYPES: string[];
+
+/**
+ * Video processing plugin: thumbnail extraction, transcoding, and metadata via ffmpeg.
+ *
+ * Requires `fluent-ffmpeg` peer dependency and the `ffmpeg`/`ffprobe` binaries in PATH.
+ */
+declare function videoProcessingPlugin(opts?: VideoProcessingPluginOptions): PipelinePlugin;
+
+export { DEFAULT_THUMBNAIL_PRESETS, DEFAULT_VIDEO_MIME_TYPES, type ThumbnailPreset, type TranscodePreset, type VideoProcessingPluginOptions, videoProcessingPlugin };

package/dist/index.d.ts

@@ -0,0 +1,88 @@
+import { PipelinePlugin } from '@better-media/core';
+
+/** A single thumbnail to extract from the video. */
+interface ThumbnailPreset {
+    /**
+     * Position to extract.
+     * - number: seconds from start (e.g. 5 = 5s)
+     * - string ending with "%": percentage of total duration (e.g. "10%")
+     * - other string: parsed as seconds (e.g. "5.5")
+     */
+    at: number | string;
+    /** Output image format. Default: "jpeg". */
+    format?: "jpeg" | "png" | "webp";
+    /** Output width in pixels. Aspect ratio preserved when only one dimension is set. */
+    width?: number;
+    /** Output height in pixels. */
+    height?: number;
+}
+/** A single transcode target. */
+interface TranscodePreset {
+    /** Identifier used in storage key and media_versions. Must be stable. */
+    name: string;
+    /** Output container format. */
+    format: "mp4" | "webm";
+    /** Video codec. Defaults: libx264 (mp4), libvpx-vp9 (webm). */
+    videoCodec?: string;
+    /** Audio codec. Defaults: aac (mp4), libopus (webm). */
+    audioCodec?: string;
+    /** Video bitrate, e.g. "1000k". */
+    videoBitrate?: string;
+    /** Audio bitrate, e.g. "128k". */
+    audioBitrate?: string;
+    /** Resolution as "WxH", e.g. "1280x720". Omit to keep source resolution. */
+    resolution?: string;
+}
+interface VideoProcessingPluginOptions {
+    /** Execution mode. Default: "background". */
+    executionMode?: "sync" | "background";
+    /**
+     * Thumbnail presets to extract.
+     * Pass `false` to disable thumbnail extraction entirely.
+     * Default: one JPEG at 10% of duration, 640px wide.
+     */
+    thumbnails?: ThumbnailPreset[] | false;
+    /**
+     * Transcode presets to produce. Omit or pass an empty array for no transcoding.
+     * Each preset produces one output file stored as a media_versions row.
+     */
+    transcode?: TranscodePreset[];
+    /** Only process files whose mimeType is in this list. Default: common video types. */
+    allowedMimeTypes?: string[];
+    /**
+     * Skip the plugin if the source file is larger than this (bytes).
+     * Useful for very large uploads that shouldn't block the sync path.
+     * Default: no limit.
+     */
+    maxInputBytes?: number;
+    /** Override the ffmpeg binary path. Default: resolved from PATH. */
+    ffmpegPath?: string;
+    /** Override the ffprobe binary path. Default: resolved from PATH. */
+    ffprobePath?: string;
+    /** Storage key prefix for derivative files. Default: "processing". */
+    derivativePrefix?: string;
+    /**
+     * Insert rows into media_versions for thumbnails and transcoded outputs.
+     * Default: true.
+     */
+    persistMediaVersions?: boolean;
+    /**
+     * Skip a thumbnail or transcode if the storage key already exists.
+     * Default: true.
+     */
+    skipExistingDerivatives?: boolean;
+    /** Timeout for the full processing run in milliseconds. Default: 300_000 (5 min). */
+    timeoutMs?: number;
+}
+
+declare const DEFAULT_THUMBNAIL_PRESETS: ThumbnailPreset[];
+declare const DEFAULT_VIDEO_MIME_TYPES: string[];
+
+/**
+ * Video processing plugin: thumbnail extraction, transcoding, and metadata via ffmpeg.
+ *
+ * Requires `fluent-ffmpeg` peer dependency and the `ffmpeg`/`ffprobe` binaries in PATH.
+ */
+declare function videoProcessingPlugin(opts?: VideoProcessingPluginOptions): PipelinePlugin;
+
+export { DEFAULT_THUMBNAIL_PRESETS, DEFAULT_VIDEO_MIME_TYPES, type ThumbnailPreset, type TranscodePreset, type VideoProcessingPluginOptions, videoProcessingPlugin };