node-av 1.0.3 → 1.2.0

package/README.md

@@ -1,7 +1,20 @@
+<p align="center">
+  <img src="https://github.com/seydx/av/blob/main/docs/logo.png?raw=true" width="250px">
+</p>
+
 # NodeAV
 
+[![npm version](https://img.shields.io/npm/v/node-av.svg)](https://www.npmjs.com/package/node-av)
+[![npm downloads](https://img.shields.io/npm/dm/node-av.svg)](https://www.npmjs.com/package/node-av)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+[![FFmpeg](https://img.shields.io/badge/FFmpeg-7.1+-green.svg)](https://ffmpeg.org)
+[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)](https://github.com/seydx/av/tree/main/INSTALLATION.md)
+
 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.
 
+📚 **[Documentation](https://seydx.github.io/av)**
+
 ## Installation
 
 ```bash
@@ -14,6 +27,7 @@ npm install node-av
 
 ```typescript
 import { Decoder, Encoder, MediaInput, MediaOutput } from 'node-av/api';
+import { FF_ENCODER_LIBX264 } from 'node-av/constants';
 
 // Open media
 await using input = await MediaInput.open('input.mp4');
@@ -24,7 +38,7 @@ const videoStream = input.video();
 
 // Create decoder/encoder
 using decoder = await Decoder.create(videoStream!);
-using encoder = await Encoder.create('libx264', videoStream!, {
+using encoder = await Encoder.create(FF_ENCODER_LIBX264, decoder.getOutputStreamInfo(), {
   bitrate: '2M',
   gopSize: 60,
 });
@@ -71,7 +85,7 @@ import { pipeline, MediaInput, MediaOutput, Decoder, Encoder } from 'node-av/api
 const input = await MediaInput.open('input.mp4');
 const output = await MediaOutput.open('output.mp4');
 const decoder = await Decoder.create(input.video());
-const encoder = await Encoder.create('libx264', input.video(), {
+const encoder = await Encoder.create(FF_ENCODER_LIBX264, decoder.getOutputStreamInfo(), {
   bitrate: '2M',
   gopSize: 60
 });
@@ -109,9 +123,10 @@ The library supports all hardware acceleration methods available in FFmpeg. The
 
 ```typescript
 import { HardwareContext } from 'node-av/api';
+import { FF_ENCODER_H264_VIDEOTOOLBOX } from 'node-av/constants';
 
 // Automatically detect best available hardware
-const hw = await HardwareContext.auto();
+const hw = HardwareContext.auto();
 if (hw) {
   console.log(`Using hardware: ${hw.deviceTypeName}`);
   
@@ -121,7 +136,7 @@ if (hw) {
   });
   
   // Use with encoder (use hardware-specific codec)
-  const encoder = await Encoder.create('h264_videotoolbox', videoStream, {
+  const encoder = await Encoder.create(FF_ENCODER_H264_VIDEOTOOLBOX, decoder.getOutputStreamInfo(), {
     hardware: hw
   });
 }
@@ -133,8 +148,8 @@ if (hw) {
 import { AV_HWDEVICE_TYPE_CUDA, AV_HWDEVICE_TYPE_VAAPI } from 'node-av/constants';
 
 // Use specific hardware type
-const cuda = await HardwareContext.create(AV_HWDEVICE_TYPE_CUDA);
-const vaapi = await HardwareContext.create(AV_HWDEVICE_TYPE_VAAPI, '/dev/dri/renderD128');
+const cuda = HardwareContext.create(AV_HWDEVICE_TYPE_CUDA);
+const vaapi = HardwareContext.create(AV_HWDEVICE_TYPE_VAAPI, '/dev/dri/renderD128');
 ```
 
 ## Imports and Tree Shaking
@@ -241,50 +256,50 @@ NodeAV provides direct bindings to FFmpeg's C APIs, which work with raw memory p
 
 | Example | FFmpeg | Low-Level API | High-Level API |
 |---------|--------|---------------|----------------|
-| `api-encode-decode` | | | [✓](examples/api-encode-decode.ts) |
-| `api-frame-extract` | | | [✓](examples/api-frame-extract.ts) |
-| `api-hw-decode-sw-encode` | | | [✓](examples/api-hw-decode-sw-encode.ts) |
-| `api-hw-raw` | | | [✓](examples/api-hw-raw.ts) |
-| `api-hw-rtsp-custom-io` | | | [✓](examples/api-hw-rtsp-custom-io.ts) |
-| `api-hw-rtsp` | | | [✓](examples/api-hw-rtsp.ts) |
-| `api-hw-transcode` | | | [✓](examples/api-hw-transcode.ts) |
-| `api-muxing` | | | [✓](examples/api-muxing.ts) |
-| `api-pipeline-hw-rtsp` | | | [✓](examples/api-pipeline-hw-rtsp.ts) |
-| `api-pipeline-raw-muxing` | | | [✓](examples/api-pipeline-raw-muxing.ts) |
-| `api-stream-input` | | | [✓](examples/api-stream-input.ts) |
-| `api-sw-decode-hw-encode` | | | [✓](examples/api-sw-decode-hw-encode.ts) |
-| `api-sw-transcode` | | | [✓](examples/api-sw-transcode.ts) |
-| `avio-read-callback` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/avio_read_callback.c) | [✓](examples/avio-read-callback.ts) | |
-| `decode-audio` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/decode_audio.c) | [✓](examples/decode-audio.ts) | |
-| `decode-filter-audio` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/decode_filter_audio.c) | [✓](examples/decode-filter-audio.ts) | |
-| `decode-filter-video` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/decode_filter_video.c) | [✓](examples/decode-filter-video.ts) | |
-| `decode-video` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/decode_video.c) | [✓](examples/decode-video.ts) | |
-| `demux-decode` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/demux_decode.c) | [✓](examples/demux-decode.ts) | |
-| `encode-audio` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/encode_audio.c) | [✓](examples/encode-audio.ts) | |
-| `encode-video` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/encode_video.c) | [✓](examples/encode-video.ts) | |
-| `ffprobe-metadata` | | [✓](examples/ffprobe-metadata.ts) | |
-| `filter-audio` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/filter_audio.c) | [✓](examples/filter-audio.ts) | |
-| `hw-decode` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/hw_decode.c) | [✓](examples/hw-decode.ts) | |
-| `hw-encode` | | [✓](examples/hw-encode.ts) | |
-| `hw-transcode` | | [✓](examples/hw-transcode.ts) | |
+| `api-encode-decode` | | | [✓](https://github.com/seydx/av/tree/main/examples/api-encode-decode.ts) |
+| `api-frame-extract` | | | [✓](https://github.com/seydx/av/tree/main/examples/api-frame-extract.ts) |
+| `api-hw-decode-sw-encode` | | | [✓](https://github.com/seydx/av/tree/main/examples/api-hw-decode-sw-encode.ts) |
+| `api-hw-raw` | | | [✓](https://github.com/seydx/av/tree/main/examples/api-hw-raw.ts) |
+| `api-hw-rtsp-custom-io` | | | [✓](https://github.com/seydx/av/tree/main/examples/api-hw-rtsp-custom-io.ts) |
+| `api-hw-rtsp` | | | [✓](https://github.com/seydx/av/tree/main/examples/api-hw-rtsp.ts) |
+| `api-hw-transcode` | | | [✓](https://github.com/seydx/av/tree/main/examples/api-hw-transcode.ts) |
+| `api-muxing` | | | [✓](https://github.com/seydx/av/tree/main/examples/api-muxing.ts) |
+| `api-pipeline-hw-rtsp` | | | [✓](https://github.com/seydx/av/tree/main/examples/api-pipeline-hw-rtsp.ts) |
+| `api-pipeline-raw-muxing` | | | [✓](https://github.com/seydx/av/tree/main/examples/api-pipeline-raw-muxing.ts) |
+| `api-stream-input` | | | [✓](https://github.com/seydx/av/tree/main/examples/api-stream-input.ts) |
+| `api-sw-decode-hw-encode` | | | [✓](https://github.com/seydx/av/tree/main/examples/api-sw-decode-hw-encode.ts) |
+| `api-sw-transcode` | | | [✓](https://github.com/seydx/av/tree/main/examples/api-sw-transcode.ts) |
+| `avio-read-callback` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/avio_read_callback.c) | [✓](https://github.com/seydx/av/tree/main/examples/avio-read-callback.ts) | |
+| `decode-audio` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/decode_audio.c) | [✓](https://github.com/seydx/av/tree/main/examples/decode-audio.ts) | |
+| `decode-filter-audio` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/decode_filter_audio.c) | [✓](https://github.com/seydx/av/tree/main/examples/decode-filter-audio.ts) | |
+| `decode-filter-video` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/decode_filter_video.c) | [✓](https://github.com/seydx/av/tree/main/examples/decode-filter-video.ts) | |
+| `decode-video` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/decode_video.c) | [✓](https://github.com/seydx/av/tree/main/examples/decode-video.ts) | |
+| `demux-decode` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/demux_decode.c) | [✓](https://github.com/seydx/av/tree/main/examples/demux-decode.ts) | |
+| `encode-audio` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/encode_audio.c) | [✓](https://github.com/seydx/av/tree/main/examples/encode-audio.ts) | |
+| `encode-video` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/encode_video.c) | [✓](https://github.com/seydx/av/tree/main/examples/encode-video.ts) | |
+| `ffprobe-metadata` | | [✓](https://github.com/seydx/av/tree/main/examples/ffprobe-metadata.ts) | |
+| `filter-audio` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/filter_audio.c) | [✓](https://github.com/seydx/av/tree/main/examples/filter-audio.ts) | |
+| `hw-decode` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/hw_decode.c) | [✓](https://github.com/seydx/av/tree/main/examples/hw-decode.ts) | |
+| `hw-encode` | | [✓](https://github.com/seydx/av/tree/main/examples/hw-encode.ts) | |
+| `hw-transcode` | | [✓](https://github.com/seydx/av/tree/main/examples/hw-transcode.ts) | |
 | `qsv-decode` | [✓](https://github.com/FFmpeg/FFmpeg/blob/master/doc/examples/qsv_decode.c) | | |
 | `qsv-transcode` | [✓](https://github.com/FFmpeg/FFmpeg/blob/master/doc/examples/qsv_transcode.c) | | |
 | `vaapi-encode` | [✓](https://github.com/FFmpeg/FFmpeg/blob/master/doc/examples/vaapi_encode.c) | | |
 | `vaapi-transcode` | [✓](https://github.com/FFmpeg/FFmpeg/blob/master/doc/examples/vaapi_transcode.c) | | |
-| `mux` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/mux.c) | [✓](examples/mux.ts) | |
-| `remux` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/remux.c) | [✓](examples/remux.ts) | |
-| `resample-audio` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/resample_audio.c) | [✓](examples/resample-audio.ts) | |
-| `scale-video` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/scale_video.c) | [✓](examples/scale-video.ts) | |
-| `show-metadata` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/show_metadata.c) | [✓](examples/show-metadata.ts) | |
-| `transcode-aac` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/transcode_aac.c) | [✓](examples/transcode-aac.ts) | |
-| `transcode` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/transcode.c) | [✓](examples/transcode.ts) | |
+| `mux` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/mux.c) | [✓](https://github.com/seydx/av/tree/main/examples/mux.ts) | |
+| `remux` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/remux.c) | [✓](https://github.com/seydx/av/tree/main/examples/remux.ts) | |
+| `resample-audio` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/resample_audio.c) | [✓](https://github.com/seydx/av/tree/main/examples/resample-audio.ts) | |
+| `scale-video` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/scale_video.c) | [✓](https://github.com/seydx/av/tree/main/examples/scale-video.ts) | |
+| `show-metadata` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/show_metadata.c) | [✓](https://github.com/seydx/av/tree/main/examples/show-metadata.ts) | |
+| `transcode-aac` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/transcode_aac.c) | [✓](https://github.com/seydx/av/tree/main/examples/transcode-aac.ts) | |
+| `transcode` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/transcode.c) | [✓](https://github.com/seydx/av/tree/main/examples/transcode.ts) | |
 
 
 ## Prebuilt Binaries
 
 Prebuilt binaries are available for macOS, Linux, and Windows (x64/arm64). The package will automatically build from source if needed.
 
-For detailed installation instructions, build requirements, and troubleshooting, see the **[Installation Guide](INSTALLATION.md)**.
+For detailed installation instructions, build requirements, and troubleshooting, see the **[Installation Guide](https://github.com/seydx/av/tree/main/INSTALLATION.md)**.
 
 ## License
 
@@ -294,7 +309,7 @@ This project is licensed under the MIT License. See the LICENSE file for details
 
 ## Contributing
 
-Contributions are welcome! Please read [CONTRIBUTION.md](CONTRIBUTION.md) for development setup, code standards, and contribution guidelines before submitting pull requests.
+Contributions are welcome! Please read [CONTRIBUTION.md](https://github.com/seydx/av/tree/main/CONTRIBUTION.md) for development setup, code standards, and contribution guidelines before submitting pull requests.
 
 ## Support
 

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

@@ -1,58 +1,42 @@
-/**
- * BitStreamFilterAPI - High-level wrapper for bitstream filtering
- *
- * Simplifies FFmpeg's bitstream filter API with automatic initialization,
- * parameter configuration, and packet processing.
- *
- * Handles filter context lifecycle, packet buffering, and flushing.
- * Useful for format conversion, metadata extraction, and stream modifications.
- *
- * @module api/bitstream-filter
- */
 import { Packet } from '../lib/index.js';
 import type { Stream } from '../lib/index.js';
 /**
  * High-level bitstream filter for packet processing.
  *
- * Handles filter initialization, packet processing, and cleanup.
- * Designed for simple, efficient packet filtering workflows.
- *
- * Manages filter context lifecycle and provides automatic cleanup.
- * Supports packet-by-packet and stream processing modes.
+ * Provides simplified interface for applying bitstream filters to packets.
+ * Handles filter initialization, packet processing, and memory management.
+ * Supports filters like h264_mp4toannexb, hevc_mp4toannexb, aac_adtstoasc.
+ * Essential for format conversion and stream compatibility in transcoding pipelines.
  *
  * @example
  * ```typescript
- * // Create filter for H.264 stream
- * const media = await MediaInput.open('video.mp4');
- * const stream = media.video();
- * const bsf = await BitStreamFilterAPI.create('h264_mp4toannexb', stream);
+ * import { BitStreamFilterAPI } from 'node-av/api';
  *
- * // Process packets
- * for await (const packet of media.packets()) {
- *   if (packet.streamIndex === stream.index) {
- *     const filtered = await bsf.process(packet);
- *     for (const outPacket of filtered) {
- *       // Write to output or process further
- *       await output.writePacket(outPacket);
- *     }
- *   }
- * }
+ * // Create H.264 Annex B converter
+ * const filter = BitStreamFilterAPI.create('h264_mp4toannexb', stream);
  *
- * // Flush and cleanup
- * const remaining = await bsf.flush();
- * bsf.dispose();
+ * // Process packet
+ * const outputPackets = await filter.process(inputPacket);
+ * for (const packet of outputPackets) {
+ *   await output.writePacket(packet);
+ *   packet.free();
+ * }
  * ```
  *
  * @example
  * ```typescript
  * // Process packet stream
- * const bsf = await BitStreamFilterAPI.create('extract_extradata', stream);
+ * const filter = BitStreamFilterAPI.create('hevc_mp4toannexb', videoStream);
  *
- * for await (const filtered of bsf.packets(media.packets())) {
- *   // Filtered packets are automatically processed
- *   await output.writePacket(filtered);
+ * for await (const packet of filter.packets(input.packets())) {
+ *   await output.writePacket(packet);
+ *   packet.free();
  * }
  * ```
+ *
+ * @see {@link BitStreamFilter} For available filters
+ * @see {@link BitStreamFilterContext} For low-level API
+ * @see {@link MediaOutput} For writing filtered packets
  */
 export declare class BitStreamFilterAPI implements Disposable {
     private ctx;
@@ -60,187 +44,260 @@ export declare class BitStreamFilterAPI implements Disposable {
     private stream;
     private isDisposed;
     /**
-     * Private constructor - use BitStreamFilterAPI.create() instead.
-     *
-     * @param filter - The bitstream filter
-     * @param ctx - Initialized filter context
-     * @param stream - The stream this filter is for
+     * @param filter - Bitstream filter instance
+     * @param ctx - Filter context
+     * @param stream - Associated stream
+     * @internal
      */
     private constructor();
     /**
-     * Create a bitstream filter for a specific stream.
+     * Create a bitstream filter for a stream.
      *
-     * Factory method that handles filter discovery, context setup,
-     * and initialization.
+     * Initializes filter with stream codec parameters.
+     * Configures time base and prepares for packet processing.
      *
-     * @param filterName - Name of the bitstream filter (e.g., 'h264_mp4toannexb')
-     * @param stream - Stream to filter
+     * Direct mapping to av_bsf_get_by_name() and av_bsf_alloc().
      *
-     * @returns Promise resolving to configured BitStreamFilterAPI
+     * @param filterName - Name of the bitstream filter
+     * @param stream - Stream to apply filter to
+     * @returns Configured bitstream filter
      *
-     * @throws {Error} If filter unavailable or initialization fails
+     * @throws {Error} If filter not found or initialization fails
+     * @throws {FFmpegError} If allocation or initialization fails
      *
      * @example
      * ```typescript
-     * const media = await MediaInput.open('video.mp4');
-     * const stream = media.video();
-     * const bsf = await BitStreamFilterAPI.create('h264_mp4toannexb', stream);
+     * // H.264 MP4 to Annex B conversion
+     * const filter = BitStreamFilterAPI.create('h264_mp4toannexb', videoStream);
      * ```
-     */
-    static create(filterName: string, stream: Stream): Promise<BitStreamFilterAPI>;
-    /**
-     * Get the filter name.
      *
-     * @returns The name of the bitstream filter
+     * @example
+     * ```typescript
+     * // AAC ADTS to ASC conversion
+     * const filter = BitStreamFilterAPI.create('aac_adtstoasc', audioStream);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Remove metadata
+     * const filter = BitStreamFilterAPI.create('filter_units', stream);
+     * ```
+     *
+     * @see {@link BitStreamFilter.getByName} For filter discovery
      */
-    get name(): string;
+    static create(filterName: string, stream: Stream): BitStreamFilterAPI;
     /**
-     * Get the associated stream.
+     * Get filter name.
      *
-     * @returns The stream this filter was created for
+     * @example
+     * ```typescript
+     * console.log(`Using filter: ${filter.name}`);
+     * ```
      */
-    get streamInfo(): Stream;
+    get name(): string;
     /**
      * Get output codec parameters.
      *
-     * Returns the output codec parameters after filter initialization.
-     * These may differ from input parameters depending on the filter.
+     * Parameters after filter processing.
+     * May differ from input parameters.
      *
-     * @returns Output codec parameters, or null if not available
+     * @example
+     * ```typescript
+     * const outputParams = filter.outputCodecParameters;
+     * console.log(`Output codec: ${outputParams?.codecId}`);
+     * ```
      */
     get outputCodecParameters(): import("../lib/codec-parameters.js").CodecParameters | null;
     /**
      * Get output time base.
      *
-     * Returns the output time base after filter initialization.
+     * Time base after filter processing.
      *
-     * @returns Output time base, or null if not available
+     * @example
+     * ```typescript
+     * const tb = filter.outputTimeBase;
+     * console.log(`Output timebase: ${tb?.num}/${tb?.den}`);
+     * ```
      */
     get outputTimeBase(): import("../lib/rational.js").Rational | null;
     /**
-     * Process a single packet through the filter.
+     * Process a packet through the filter.
      *
-     * Sends a packet to the filter and retrieves all output packets.
-     * One input packet may produce zero, one, or multiple output packets.
+     * Applies bitstream filter to packet.
+     * May produce zero, one, or multiple output packets.
+     * Pass null to signal end-of-stream.
      *
-     * @param packet - Packet to filter, or null to signal EOF
+     * Direct mapping to av_bsf_send_packet() and av_bsf_receive_packet().
      *
-     * @returns Array of filtered packets (may be empty)
+     * @param packet - Packet to filter or null for EOF
+     * @returns Array of filtered packets
+     *
+     * @throws {Error} If filter is disposed
+     * @throws {FFmpegError} If filtering fails
      *
      * @example
      * ```typescript
-     * const inputPacket = await media.readPacket();
-     * const filtered = await bsf.process(inputPacket);
-     *
-     * for (const packet of filtered) {
-     *   console.log(`Filtered packet: size=${packet.size}`);
-     *   await output.writePacket(packet);
+     * const outputPackets = await filter.process(inputPacket);
+     * for (const packet of outputPackets) {
+     *   console.log(`Filtered packet: pts=${packet.pts}`);
+     *   packet.free();
      * }
      * ```
+     *
+     * @example
+     * ```typescript
+     * // Flush filter
+     * const remaining = await filter.process(null);
+     * ```
+     *
+     * @see {@link flush} For explicit flushing
+     * @see {@link packets} For stream processing
      */
     process(packet: Packet | null): Promise<Packet[]>;
     /**
-     * Process a stream of packets through the filter.
-     *
-     * Async generator that processes packets lazily and yields filtered results.
-     * Automatically handles EOF and cleanup.
+     * Process packet stream through filter.
      *
-     * @param packets - Async iterable of packets to filter
+     * High-level async generator for filtering packet streams.
+     * Automatically handles flushing at end of stream.
+     * Yields filtered packets ready for output.
      *
+     * @param packets - Async iterable of packets
      * @yields Filtered packets
+     * @throws {Error} If filter is disposed
+     * @throws {FFmpegError} If filtering fails
      *
      * @example
      * ```typescript
-     * const bsf = await BitStreamFilterAPI.create('h264_mp4toannexb', stream);
-     *
-     * // Filter only video packets
-     * async function* videoPackets() {
-     *   for await (const packet of media.packets()) {
-     *     if (packet.streamIndex === stream.index) {
-     *       yield packet;
-     *     }
-     *   }
+     * // Filter entire stream
+     * for await (const packet of filter.packets(input.packets())) {
+     *   await output.writePacket(packet);
+     *   packet.free();
      * }
+     * ```
      *
-     * for await (const filtered of bsf.packets(videoPackets())) {
-     *   await output.writePacket(filtered);
+     * @example
+     * ```typescript
+     * // Chain with decoder
+     * const decoder = await Decoder.create(stream);
+     * const filter = BitStreamFilterAPI.create('h264_mp4toannexb', stream);
+     *
+     * for await (const frame of decoder.frames(filter.packets(input.packets()))) {
+     *   // Process frames
+     *   frame.free();
      * }
      * ```
+     *
+     * @see {@link process} For single packet filtering
+     * @see {@link flush} For end-of-stream handling
      */
     packets(packets: AsyncIterable<Packet>): AsyncGenerator<Packet>;
     /**
-     * Flush the filter and retrieve remaining packets.
+     * Flush filter and get remaining packets.
+     *
+     * Signals end-of-stream and retrieves buffered packets.
+     * Also resets internal filter state.
      *
-     * Sends EOF to the filter and retrieves any buffered packets.
-     * Should be called when all input packets have been processed.
+     * Direct mapping to av_bsf_flush().
      *
-     * @returns Array of remaining packets (may be empty)
+     * @returns Array of remaining packets
+     *
+     * @throws {Error} If filter is disposed
      *
      * @example
      * ```typescript
-     * // After processing all packets
-     * const remaining = await bsf.flush();
+     * const remaining = await filter.flush();
      * for (const packet of remaining) {
      *   await output.writePacket(packet);
+     *   packet.free();
      * }
      * ```
+     *
+     * @see {@link flushPackets} For async iteration
+     * @see {@link reset} For state reset only
      */
     flush(): Promise<Packet[]>;
     /**
-     * Flush the filter and yield remaining packets.
+     * Flush filter as async generator.
      *
-     * Async generator that sends EOF to the filter and yields any buffered packets.
-     * Provides a convenient way to process all remaining packets after input is complete.
+     * Convenient async iteration over remaining packets.
+     * Combines flush and iteration.
      *
-     * @yields Remaining packets from the filter
+     * @yields Remaining packets
+     * @throws {Error} If filter is disposed
      *
      * @example
      * ```typescript
-     * // Process all remaining packets with generator
-     * for await (const packet of bsf.flushPackets()) {
+     * for await (const packet of filter.flushPackets()) {
      *   await output.writePacket(packet);
-     *   using _ = packet; // Auto cleanup
+     *   packet.free();
      * }
      * ```
+     *
+     * @see {@link flush} For array return
      */
     flushPackets(): AsyncGenerator<Packet>;
     /**
-     * Get the stream this filter was created for.
-     * Used for determining stream configuration in pipeline.
+     * 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 the filter state.
+     * Reset filter state.
      *
-     * Clears internal buffers and resets the filter to initial state.
-     * Useful when seeking or switching between streams.
+     * Clears internal buffers and resets filter.
+     * Does not dispose resources.
+     *
+     * Direct mapping to av_bsf_flush().
+     *
+     * @throws {Error} If filter is disposed
      *
      * @example
      * ```typescript
-     * // When seeking in the input
-     * await media.seek(timestamp);
-     * bsf.reset(); // Clear filter state
-     * // Continue processing from new position
+     * // Reset for new segment
+     * filter.reset();
      * ```
+     *
+     * @see {@link flush} For reset with packet retrieval
      */
     reset(): void;
     /**
-     * Dispose of the filter resources.
+     * Dispose of filter and free resources.
      *
-     * Automatically called when using the `using` statement.
-     * Frees all associated FFmpeg resources.
+     * Releases filter context and marks as disposed.
+     * Safe to call multiple times.
      *
      * @example
      * ```typescript
-     * {
-     *   using bsf = await BitStreamFilterAPI.create('h264_mp4toannexb', stream);
-     *   // ... use filter
-     * } // Automatically disposed when leaving scope
+     * filter.dispose();
      * ```
+     *
+     * @see {@link Symbol.dispose} For automatic cleanup
      */
     dispose(): void;
     /**
-     * Symbol.dispose implementation for using statement.
+     * Dispose of filter.
+     *
+     * Implements Disposable interface for automatic cleanup.
+     * Equivalent to calling dispose().
+     *
+     * @example
+     * ```typescript
+     * {
+     *   using filter = BitStreamFilterAPI.create('h264_mp4toannexb', stream);
+     *   // Use filter...
+     * } // Automatically disposed
+     * ```
+     *
+     * @see {@link dispose} For manual cleanup
      */
     [Symbol.dispose](): void;
 }