node-av 5.2.4 → 6.0.0-beta.10

package/README.md

@@ -11,7 +11,7 @@
 [![FFmpeg](https://img.shields.io/badge/FFmpeg-8.1-green.svg)](https://ffmpeg.org)
 [![Platform](https://img.shields.io/badge/platform-Windows%20(MSVC%20%7C%20MinGW)%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)](https://github.com/seydx/node-av)
 
-Native Node.js bindings for FFmpeg with full TypeScript support. Provides direct access to FFmpeg's C APIs through N-API. Includes both raw FFmpeg bindings for full control and higher-level abstractions. Automatic resource management via Disposable pattern, hardware acceleration support and prebuilt binaries for Windows, Linux, and macOS.
+Native Node.js bindings for FFmpeg with full TypeScript support - including type-safe options (autocomplete + validation) for every codec, format, filter, and bitstream filter, generated from FFmpeg's own metadata. Provides direct access to FFmpeg's C APIs through N-API. Includes both raw FFmpeg bindings for full control and higher-level abstractions. Automatic resource management via Disposable pattern, hardware acceleration support and prebuilt binaries for Windows, Linux, and macOS.
 
 📚 **[Documentation](https://seydx.github.io/node-av)**
 
@@ -446,6 +446,9 @@ import * as ffmpeg from 'node-av';
 
 Beyond basic transcoding, NodeAV provides advanced media processing capabilities:
 
+**Fully Typed FFmpeg Options**
+Every FFmpeg option is typed - across codecs, formats, ~580 filters, and bitstream filters. Keys autocomplete, enum values are validated, and typos become compile-time errors, all generated directly from FFmpeg's `AVOption` metadata (including each option's description and a link to the FFmpeg docs as JSDoc). No more grepping the FFmpeg docs for flag names.
+
 **Speech Recognition with Whisper**
 Integrate automatic speech-to-text transcription using OpenAI's Whisper model through the whisper.cpp implementation. The library handles automatic model downloading from HuggingFace, supports multiple model sizes (tiny, base, small, medium, large) for different accuracy/performance tradeoffs, and provides hardware-accelerated inference through Metal (macOS), Vulkan (cross-platform), or OpenCL backends. Transcription results include precise timestamps and can be processed in real-time from any audio source.
 
@@ -458,6 +461,9 @@ Stream any media source directly to web browsers through fragmented MP4 (fMP4) o
 **RTSP Backchannel / Talkback**
 Implements bidirectional RTSP communication for IP camera integration. The library provides native support for RTSP backchannel streams, enabling audio transmission to camera devices. Transport is handled automatically with support for both TCP (interleaved mode) and UDP protocols, with proper RTP packet formatting and stream synchronization.
 
+**Image Scaling & Snapshots**
+The `Scaler` turns decoded frames into raw pixel buffers (`rgb`/`rgba`/`gray`/`nv12`/`yuv420p`) or JPEG/PNG images for detection, thumbnail, and snapshot workloads. One reusable instance pools its swscale contexts, GPU filter graphs, and encoders for zero per-frame allocation; hardware frames are cropped/scaled on the GPU with only the small result downloaded. Recurring resolutions can also be served directly by `EncoderPool`.
+
 See the [Examples](#examples) section for complete implementations.
 
 ## Performance
@@ -522,11 +528,14 @@ If you encounter module resolution errors like `Cannot find module 'lib/binary-s
 | `electron-builder` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/electron/builder) |
 | `electron-forge` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/electron/forge) |
 | `api-abort-signal` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-abort-signal.ts) |
+| `api-bitstream-filter` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-bitstream-filter.ts) |
 | `api-dash` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-dash.ts) |
+| `api-decoder-resample` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-decoder-resample.ts) |
 | `api-device-capture` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-device-capture.ts) |
 | `api-encode-decode` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-encode-decode.ts) |
 | `api-filter-complex` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-filter-complex.ts) |
 | `api-filter-complex-grid` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-filter-complex-grid.ts) |
+| `api-filter-complex-typed` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-filter-complex-typed.ts) |
 | `api-fmp4` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-fmp4.ts) |
 | `api-frame-extract` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-frame-extract.ts) |
 | `api-hw-codecs` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-hw-codecs.ts) |
@@ -539,10 +548,15 @@ If you encounter module resolution errors like `Cannot find module 'lib/binary-s
 | `api-hw-filter-sync` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-hw-filter-sync.ts) |
 | `api-muxing` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-muxing.ts) |
 | `api-pipeline-hw-rtsp` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-pipeline-hw-rtsp.ts) |
+| `api-pipeline-progress` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-pipeline-progress.ts) |
 | `api-pipeline-raw-muxing` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-pipeline-raw-muxing.ts) |
+| `api-probe` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-probe.ts) |
 | `api-rtp` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-rtp.ts) |
+| `api-rtsp-backchannel` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-rtsp-backchannel.ts) |
+| `api-scaler` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-scaler.ts) |
 | `api-sdp-custom` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-sdp-custom.ts) |
 | `api-sdp-input` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-sdp-input.ts) |
+| `api-snapshot` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-snapshot.ts) |
 | `api-stream-input` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-stream-input.ts) |
 | `api-sw-decode-hw-encode` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-sw-decode-hw-encode.ts) |
 | `api-sw-transcode` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-sw-transcode.ts) |

package/dist/api/bitstream-filter.d.ts

@@ -1,19 +1,25 @@
 import { Packet } from '../lib/packet.js';
+import { Stream } from '../lib/stream.js';
+import { Encoder } from './encoder.js';
 import { Muxer } from './muxer.js';
 import { Scheduler, SchedulerControl } from './utilities/scheduler.js';
-import type { Stream } from '../lib/stream.js';
+import type { BsfName, BsfOptionsFor } from '../constants/index.js';
 /**
  * Options for bitstream filter creation.
+ *
+ * @template N - The bitstream filter name; when a literal name is given,
+ * `options` is strongly typed to that filter's known options.
  */
-export interface BitstreamFilterOptions {
+export interface BitstreamFilterOptions<N extends string = string> {
     /**
      * Filter-specific options.
      *
-     * Key-value pairs of FFmpeg bitstream filter options.
-     * These are passed directly to the filter via av_opt_set().
-     * Available options depend on the specific filter being used.
+     * Key-value pairs of FFmpeg bitstream filter options, passed directly to the
+     * filter via av_opt_set(). When created from a known filter name, these are
+     * strongly typed to that filter's options (autocomplete + validation);
+     * otherwise any string/number/boolean values are accepted.
      */
-    options?: Record<string, string | number | boolean | bigint | undefined | null>;
+    options?: BsfOptionsFor<N>;
     /**
      * AbortSignal for cancellation.
      *
@@ -63,7 +69,8 @@ export interface BitstreamFilterOptions {
 export declare class BitStreamFilterAPI implements Disposable {
     private ctx;
     private bsf;
-    private stream;
+    private source;
+    private initialized;
     private packet;
     private isClosed;
     private inputQueue;
@@ -77,63 +84,55 @@ export declare class BitStreamFilterAPI implements Disposable {
      *
      * @param ctx - Filter context
      *
-     * @param stream - Associated stream
+     * @param source - Input source for lazy parameter resolution
      *
      * @internal
      */
     private constructor();
     /**
-     * Create a bitstream filter for a stream.
+     * Create a bitstream filter.
+     *
+     * The input source provides the codec parameters the filter is configured with.
+     * Pass a {@link Stream} to filter its packets directly (stream copy), or an
+     * {@link Encoder} to filter that encoder's output (transcode) - parameters are
+     * derived from the encoder once it is open. Another {@link BitStreamFilterAPI}
+     * may be passed to chain filters.
      *
-     * Initializes filter with stream codec parameters.
-     * Configures time base and prepares for packet processing.
+     * Initialization is lazy: filter options are validated immediately, but the
+     * input parameters are bound and the filter is initialized on the first packet,
+     * so an `Encoder` source (opened lazily on its first frame) is ready in time.
      *
      * Direct mapping to av_bsf_get_by_name() and av_bsf_alloc().
      *
      * @param filterName - Name of the bitstream filter
      *
-     * @param stream - Stream to apply filter to
+     * @param source - Input source: a `Stream` (copy), `Encoder` (transcode), or upstream filter (chain)
      *
      * @param filterOptions - Optional filter-specific options
      *
      * @returns Configured bitstream filter
      *
-     * @throws {Error} If initialization fails
-     *
-     * @throws {FFmpegError} If allocation or initialization fails
+     * @throws {FFmpegError} If the filter is not found, allocation fails, or an option is invalid
      *
      * @example
      * ```typescript
-     * // H.264 MP4 to Annex B conversion
+     * // Stream copy: H.264 MP4 to Annex B conversion
      * const filter = BitStreamFilterAPI.create('h264_mp4toannexb', videoStream);
      * ```
      *
      * @example
      * ```typescript
-     * // AAC ADTS to ASC conversion
-     * const filter = BitStreamFilterAPI.create('aac_adtstoasc', audioStream);
-     * ```
-     *
-     * @example
-     * ```typescript
-     * // Remove AUDs from H.264 stream
-     * const filter = BitStreamFilterAPI.create('h264_metadata', stream, {
-     *   options: { aud: 'remove' }
-     * });
-     * ```
-     *
-     * @example
-     * ```typescript
-     * // Set H.264 level
-     * const filter = BitStreamFilterAPI.create('h264_metadata', stream, {
-     *   options: { level: 51 }
+     * // Transcode: derive parameters from the encoder's output
+     * const filter = BitStreamFilterAPI.create('h264_metadata', encoder, {
+     *   options: { aud: 'remove', level: '4.1' },
      * });
+     * pipeline(input, decoder, encoder, filter, output);
      * ```
      *
      * @see {@link BitStreamFilter.getByName} For filter discovery
      * @see {@link BitstreamFilterOptions} For available options
      */
-    static create(filterName: string, stream: Stream, filterOptions?: BitstreamFilterOptions): BitStreamFilterAPI;
+    static create<const N extends BsfName | (string & {}) = BsfName | (string & {})>(filterName: N, source: Stream | Encoder | BitStreamFilterAPI, filterOptions?: BitstreamFilterOptions<N>): BitStreamFilterAPI;
     /**
      * Get filter name.
      *
@@ -179,6 +178,38 @@ export declare class BitStreamFilterAPI implements Disposable {
      * ```
      */
     get isBitstreamFilterOpen(): boolean;
+    /**
+     * Check if the filter has been initialized.
+     *
+     * Initialization is lazy and happens on the first processed packet, after
+     * which {@link outputCodecParameters} reflect the filter's output.
+     *
+     * @example
+     * ```typescript
+     * if (filter.isInitialized) {
+     *   const params = filter.outputCodecParameters;
+     * }
+     * ```
+     */
+    get isInitialized(): boolean;
+    /**
+     * Get associated stream.
+     *
+     * Returns the stream this filter was created for. Only available when the
+     * filter was created from a {@link Stream}; filters created from an `Encoder`
+     * derive their parameters from the encoder's output instead.
+     *
+     * @returns Associated stream
+     *
+     * @throws {Error} If the filter was not created from a stream
+     *
+     * @example
+     * ```typescript
+     * const stream = filter.getStream();
+     * console.log(`Filtering stream ${stream.index}`);
+     * ```
+     */
+    getStream(): Stream;
     /**
      * Send a packet to the filter.
      *
@@ -637,6 +668,43 @@ export declare class BitStreamFilterAPI implements Disposable {
      * @see {@link receive} For async version
      */
     receiveSync(): Packet | null;
+    /**
+     * Pipe output to another bitstream filter.
+     *
+     * Starts background worker for packet processing.
+     * Packets flow through: input → this filter → target filter.
+     *
+     * @param target - Target bitstream filter
+     *
+     * @returns Scheduler for continued chaining
+     *
+     * @example
+     * ```typescript
+     * const filter1 = BitStreamFilterAPI.create('h264_mp4toannexb', stream);
+     * const filter2 = BitStreamFilterAPI.create('dump_extra', stream);
+     * filter1.pipeTo(filter2).pipeTo(output, 0);
+     * ```
+     */
+    pipeTo(target: BitStreamFilterAPI): Scheduler<Packet>;
+    /**
+     * Pipe output to muxer.
+     *
+     * Terminal stage - writes filtered packets to output file.
+     *
+     * @param output - Muxer to write to
+     *
+     * @param streamIndex - Stream index in output
+     *
+     * @returns Control interface for pipeline
+     *
+     * @example
+     * ```typescript
+     * const filter = BitStreamFilterAPI.create('h264_mp4toannexb', stream);
+     * const control = filter.pipeTo(output, 0);
+     * await control.send(packet);
+     * ```
+     */
+    pipeTo(output: Muxer, streamIndex: number): SchedulerControl<Packet>;
     /**
      * Flush all buffered packets as async generator.
      *
@@ -686,20 +754,6 @@ export declare class BitStreamFilterAPI implements Disposable {
      * @see {@link flushPackets} For async version
      */
     flushPacketsSync(): Generator<Packet>;
-    /**
-     * Get associated stream.
-     *
-     * Returns the stream this filter was created for.
-     *
-     * @returns Associated stream
-     *
-     * @example
-     * ```typescript
-     * const stream = filter.getStream();
-     * console.log(`Filtering stream ${stream.index}`);
-     * ```
-     */
-    getStream(): Stream;
     /**
      * Reset filter state.
      *
@@ -748,6 +802,12 @@ export declare class BitStreamFilterAPI implements Disposable {
      * @see {@link close} For manual cleanup
      */
     [Symbol.dispose](): void;
+    /**
+     * Bind input parameters from the source and initialize the filter.
+     *
+     * @internal
+     */
+    private ensureInitialized;
     /**
      * Send packet to input queue or flush the pipeline.
      *
@@ -765,7 +825,7 @@ export declare class BitStreamFilterAPI implements Disposable {
      *
      * @internal
      */
-    sendToQueue(packet: Packet | null): Promise<void>;
+    private sendToQueue;
     /**
      * Receive packet from output queue.
      *
@@ -773,48 +833,11 @@ export declare class BitStreamFilterAPI implements Disposable {
      *
      * @internal
      */
-    receiveFromQueue(): Promise<Packet | null>;
+    private receiveFromQueue;
     /**
      * Worker loop for push-based processing.
      *
      * @internal
      */
     private runWorker;
-    /**
-     * Pipe output to another bitstream filter.
-     *
-     * Starts background worker for packet processing.
-     * Packets flow through: input → this filter → target filter.
-     *
-     * @param target - Target bitstream filter
-     *
-     * @returns Scheduler for continued chaining
-     *
-     * @example
-     * ```typescript
-     * const filter1 = BitStreamFilterAPI.create('h264_mp4toannexb', stream);
-     * const filter2 = BitStreamFilterAPI.create('dump_extra', stream);
-     * filter1.pipeTo(filter2).pipeTo(output, 0);
-     * ```
-     */
-    pipeTo(target: BitStreamFilterAPI): Scheduler<Packet>;
-    /**
-     * Pipe output to muxer.
-     *
-     * Terminal stage - writes filtered packets to output file.
-     *
-     * @param output - Muxer to write to
-     *
-     * @param streamIndex - Stream index in output
-     *
-     * @returns Control interface for pipeline
-     *
-     * @example
-     * ```typescript
-     * const filter = BitStreamFilterAPI.create('h264_mp4toannexb', stream);
-     * const control = filter.pipeTo(output, 0);
-     * await control.send(packet);
-     * ```
-     */
-    pipeTo(output: Muxer, streamIndex: number): SchedulerControl<Packet>;
 }