@better-media/plugin-video-streaming 0.6.0

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,138 @@
+import { PipelineContext, DatabaseAdapter, StorageAdapter, PipelinePlugin } from '@better-media/core';
+
+type StreamingFormat = "hls" | "dash";
+interface StreamingProgressEvent {
+    /** Which streaming format is being transcoded. */
+    format: StreamingFormat;
+    /** For HLS: the preset currently being transcoded (one pass per preset). Absent for DASH. */
+    preset?: string;
+    /** Estimated completion percentage (0–100). */
+    percent?: number;
+    /** How far into the source video ffmpeg has processed, in seconds. */
+    currentTimeSecs?: number;
+}
+interface StreamingPreset {
+    /** Used in storage path, e.g. "360p", "720p". Must be stable for idempotent keys. */
+    name: string;
+    /** Output width (px). Aspect ratio preserved if only height is set. */
+    width?: number;
+    /** Output height (px). Aspect ratio preserved if only width is set. */
+    height?: number;
+    /** Video bitrate, e.g. "1000k". */
+    videoBitrate?: string;
+    /** Audio bitrate, e.g. "128k". */
+    audioBitrate?: string;
+    /** Video codec. Default: "libx264". */
+    videoCodec?: string;
+    /** Audio codec. Default: "aac". */
+    audioCodec?: string;
+}
+interface VideoStreamingPluginOptions {
+    /**
+     * Streaming formats to generate. Default: ["hls"].
+     * Add "dash" to also produce a DASH manifest.
+     */
+    formats?: StreamingFormat[];
+    /** Quality presets to transcode. Default: 360p / 720p / 1080p. */
+    presets?: StreamingPreset[];
+    /**
+     * Adjust each preset at runtime from context.metadata (e.g. restrict max quality
+     * based on subscription tier).
+     */
+    resolvePreset?: (context: PipelineContext, preset: StreamingPreset, index: number) => StreamingPreset | Promise<StreamingPreset>;
+    /** Only process files whose mimeType is in this list. Default: common video types. */
+    allowedMimeTypes?: string[];
+    /** Prefix for streaming storage keys. Default: "streaming". */
+    derivativePrefix?: string;
+    /** HLS/DASH segment duration in seconds. Default: 6. */
+    segmentDuration?: number;
+    /**
+     * Insert rows into media_versions for master playlists and variant playlists.
+     * Individual segments are never persisted. Default: true.
+     */
+    persistMediaVersions?: boolean;
+    /**
+     * Skip transcoding if the master playlist already exists in storage. Default: true.
+     */
+    skipExistingDerivatives?: boolean;
+    /** Timeout for the full transcoding pass (ms). Default: 600_000 (10 min). */
+    timeoutMs?: number;
+    /**
+     * Called periodically during transcoding with ffmpeg progress information.
+     * For HLS each preset runs as a separate pass, so events include the preset name.
+     * For DASH all presets run in a single pass, so `preset` is absent.
+     */
+    onProgress?: (event: StreamingProgressEvent) => void;
+}
+
+declare const DEFAULT_STREAMING_PRESETS: StreamingPreset[];
+declare const DEFAULT_VIDEO_MIME_TYPES: string[];
+
+interface StreamingUrlResult {
+    /** Master HLS playlist URL, if HLS was generated for this record. */
+    hls?: string;
+    /** Master DASH manifest URL, if DASH was generated for this record. */
+    dash?: string;
+}
+interface ResolveStreamingUrlsOptions {
+    database: DatabaseAdapter;
+    storage: StorageAdapter;
+    /** When set, generates a signed URL expiring in this many seconds. */
+    expiresIn?: number;
+    /** Storage key prefix used at transcode time. Default: "streaming". */
+    derivativePrefix?: string;
+}
+declare function resolveStreamingUrls(recordId: string, options: ResolveStreamingUrlsOptions): Promise<StreamingUrlResult>;
+
+interface StreamingStatus {
+    /** Whether the HLS master playlist is ready in storage. */
+    hls: boolean;
+    /** Whether the DASH master manifest is ready in storage. */
+    dash: boolean;
+    /** True when at least one format is ready for playback. */
+    ready: boolean;
+}
+interface ResolveStreamingStatusOptions {
+    storage: StorageAdapter;
+    /** Storage key prefix used at transcode time. Default: "streaming". */
+    derivativePrefix?: string;
+}
+declare function resolveStreamingStatus(recordId: string, options: ResolveStreamingStatusOptions): Promise<StreamingStatus>;
+
+interface StreamingProxyOptions {
+    storage: StorageAdapter;
+    authenticate?: (req: unknown, context: {
+        recordId: string;
+        storageKey: string;
+    }) => Promise<void>;
+    cacheControl?: {
+        playlist?: string;
+        segment?: string;
+    };
+    /** CORS origin to allow. Default: "*". */
+    corsOrigin?: string;
+    /** Storage key prefix used at transcode time. Default: "streaming". */
+    derivativePrefix?: string;
+}
+interface ProxyHandleOptions {
+    recordId: string;
+    /** Relative path within the record, e.g. "hls/master.m3u8" or "hls/720p/seg001.ts". */
+    filePath: string;
+    /** Original request object — passed through to authenticate if provided. */
+    req?: unknown;
+    /** HTTP method. Default: "GET". HEAD returns headers only (no body). */
+    method?: string;
+}
+interface StreamingProxy {
+    handle(options: ProxyHandleOptions): Promise<Response>;
+}
+declare function createStreamingProxy(options: StreamingProxyOptions): StreamingProxy;
+
+/**
+ * Video streaming plugin: adaptive-bitrate HLS (and optionally DASH) transcoding via ffmpeg.
+ *
+ * Requires `fluent-ffmpeg` peer dependency and the `ffmpeg` binary in PATH.
+ */
+declare function videoStreamingPlugin(opts?: VideoStreamingPluginOptions): PipelinePlugin;
+
+export { DEFAULT_STREAMING_PRESETS, DEFAULT_VIDEO_MIME_TYPES, type ProxyHandleOptions, type ResolveStreamingStatusOptions, type ResolveStreamingUrlsOptions, type StreamingFormat, type StreamingPreset, type StreamingProgressEvent, type StreamingProxy, type StreamingProxyOptions, type StreamingStatus, type StreamingUrlResult, type VideoStreamingPluginOptions, createStreamingProxy, resolveStreamingStatus, resolveStreamingUrls, videoStreamingPlugin };

package/dist/index.d.ts

@@ -0,0 +1,138 @@
+import { PipelineContext, DatabaseAdapter, StorageAdapter, PipelinePlugin } from '@better-media/core';
+
+type StreamingFormat = "hls" | "dash";
+interface StreamingProgressEvent {
+    /** Which streaming format is being transcoded. */
+    format: StreamingFormat;
+    /** For HLS: the preset currently being transcoded (one pass per preset). Absent for DASH. */
+    preset?: string;
+    /** Estimated completion percentage (0–100). */
+    percent?: number;
+    /** How far into the source video ffmpeg has processed, in seconds. */
+    currentTimeSecs?: number;
+}
+interface StreamingPreset {
+    /** Used in storage path, e.g. "360p", "720p". Must be stable for idempotent keys. */
+    name: string;
+    /** Output width (px). Aspect ratio preserved if only height is set. */
+    width?: number;
+    /** Output height (px). Aspect ratio preserved if only width is set. */
+    height?: number;
+    /** Video bitrate, e.g. "1000k". */
+    videoBitrate?: string;
+    /** Audio bitrate, e.g. "128k". */
+    audioBitrate?: string;
+    /** Video codec. Default: "libx264". */
+    videoCodec?: string;
+    /** Audio codec. Default: "aac". */
+    audioCodec?: string;
+}
+interface VideoStreamingPluginOptions {
+    /**
+     * Streaming formats to generate. Default: ["hls"].
+     * Add "dash" to also produce a DASH manifest.
+     */
+    formats?: StreamingFormat[];
+    /** Quality presets to transcode. Default: 360p / 720p / 1080p. */
+    presets?: StreamingPreset[];
+    /**
+     * Adjust each preset at runtime from context.metadata (e.g. restrict max quality
+     * based on subscription tier).
+     */
+    resolvePreset?: (context: PipelineContext, preset: StreamingPreset, index: number) => StreamingPreset | Promise<StreamingPreset>;
+    /** Only process files whose mimeType is in this list. Default: common video types. */
+    allowedMimeTypes?: string[];
+    /** Prefix for streaming storage keys. Default: "streaming". */
+    derivativePrefix?: string;
+    /** HLS/DASH segment duration in seconds. Default: 6. */
+    segmentDuration?: number;
+    /**
+     * Insert rows into media_versions for master playlists and variant playlists.
+     * Individual segments are never persisted. Default: true.
+     */
+    persistMediaVersions?: boolean;
+    /**
+     * Skip transcoding if the master playlist already exists in storage. Default: true.
+     */
+    skipExistingDerivatives?: boolean;
+    /** Timeout for the full transcoding pass (ms). Default: 600_000 (10 min). */
+    timeoutMs?: number;
+    /**
+     * Called periodically during transcoding with ffmpeg progress information.
+     * For HLS each preset runs as a separate pass, so events include the preset name.
+     * For DASH all presets run in a single pass, so `preset` is absent.
+     */
+    onProgress?: (event: StreamingProgressEvent) => void;
+}
+
+declare const DEFAULT_STREAMING_PRESETS: StreamingPreset[];
+declare const DEFAULT_VIDEO_MIME_TYPES: string[];
+
+interface StreamingUrlResult {
+    /** Master HLS playlist URL, if HLS was generated for this record. */
+    hls?: string;
+    /** Master DASH manifest URL, if DASH was generated for this record. */
+    dash?: string;
+}
+interface ResolveStreamingUrlsOptions {
+    database: DatabaseAdapter;
+    storage: StorageAdapter;
+    /** When set, generates a signed URL expiring in this many seconds. */
+    expiresIn?: number;
+    /** Storage key prefix used at transcode time. Default: "streaming". */
+    derivativePrefix?: string;
+}
+declare function resolveStreamingUrls(recordId: string, options: ResolveStreamingUrlsOptions): Promise<StreamingUrlResult>;
+
+interface StreamingStatus {
+    /** Whether the HLS master playlist is ready in storage. */
+    hls: boolean;
+    /** Whether the DASH master manifest is ready in storage. */
+    dash: boolean;
+    /** True when at least one format is ready for playback. */
+    ready: boolean;
+}
+interface ResolveStreamingStatusOptions {
+    storage: StorageAdapter;
+    /** Storage key prefix used at transcode time. Default: "streaming". */
+    derivativePrefix?: string;
+}
+declare function resolveStreamingStatus(recordId: string, options: ResolveStreamingStatusOptions): Promise<StreamingStatus>;
+
+interface StreamingProxyOptions {
+    storage: StorageAdapter;
+    authenticate?: (req: unknown, context: {
+        recordId: string;
+        storageKey: string;
+    }) => Promise<void>;
+    cacheControl?: {
+        playlist?: string;
+        segment?: string;
+    };
+    /** CORS origin to allow. Default: "*". */
+    corsOrigin?: string;
+    /** Storage key prefix used at transcode time. Default: "streaming". */
+    derivativePrefix?: string;
+}
+interface ProxyHandleOptions {
+    recordId: string;
+    /** Relative path within the record, e.g. "hls/master.m3u8" or "hls/720p/seg001.ts". */
+    filePath: string;
+    /** Original request object — passed through to authenticate if provided. */
+    req?: unknown;
+    /** HTTP method. Default: "GET". HEAD returns headers only (no body). */
+    method?: string;
+}
+interface StreamingProxy {
+    handle(options: ProxyHandleOptions): Promise<Response>;
+}
+declare function createStreamingProxy(options: StreamingProxyOptions): StreamingProxy;
+
+/**
+ * Video streaming plugin: adaptive-bitrate HLS (and optionally DASH) transcoding via ffmpeg.
+ *
+ * Requires `fluent-ffmpeg` peer dependency and the `ffmpeg` binary in PATH.
+ */
+declare function videoStreamingPlugin(opts?: VideoStreamingPluginOptions): PipelinePlugin;
+
+export { DEFAULT_STREAMING_PRESETS, DEFAULT_VIDEO_MIME_TYPES, type ProxyHandleOptions, type ResolveStreamingStatusOptions, type ResolveStreamingUrlsOptions, type StreamingFormat, type StreamingPreset, type StreamingProgressEvent, type StreamingProxy, type StreamingProxyOptions, type StreamingStatus, type StreamingUrlResult, type VideoStreamingPluginOptions, createStreamingProxy, resolveStreamingStatus, resolveStreamingUrls, videoStreamingPlugin };