node-av 5.0.4 → 5.1.1

package/BENCHMARK.md

@@ -0,0 +1,113 @@
+# node-av Benchmark Results
+
+> Generated: 2026-01-27T18:12:31.045Z
+
+## System Information
+
+| Property | Value |
+|----------|-------|
+| **OS** | darwin 25.1.0 |
+| **Architecture** | arm64 |
+| **CPU** | Apple M3 Max |
+| **CPU Cores** | 16 |
+| **RAM** | 48.0 GB |
+| **GPU** | Apple M3 Max |
+| **Node.js** | v24.8.0 |
+| **FFmpeg** | 8.0-Jellyfin |
+| **node-av** | 5.0.4 |
+
+
+## Test Inputs
+
+| File | Codec | Resolution | FPS | Duration |
+|------|-------|------------|-----|----------|
+| bbb-4k-av1.mp4 | av1 | 3840x2160 | 60 | 30.0s |
+| bbb-4k-h264.mp4 | h264 | 3840x2160 | 60 | 30.0s |
+| bbb-4k-hevc.mp4 | hevc | 3840x2160 | 60 | 30.0s |
+| bbb-4k-vp9.webm | vp9 | 3840x2160 | 60 | 30.0s |
+
+
+## Transcode Speed
+
+### Input: bbb-4k-av1.mp4
+
+| Test | FFmpeg CLI (FPS) | node-av (FPS) | FFmpeg CLI (Time) | node-av (Time) | Diff |
+|------|------------------|---------------|-------------------|----------------|------|
+| SW H.264 Transcode | 95.1 fps | 94.5 fps | 18.93s | 19.06s | -0.6% |
+| SW H.265 Transcode | 38.9 fps | 40.1 fps | 46.31s | 44.93s | +3.2% |
+| HW H.264 Transcode | 54.6 fps | 54.9 fps | 32.98s | 32.79s | +0.6% |
+| Stream Copy (Remux) | 50307.7 fps | 29472.5 fps | 36ms | 109ms | -41.4% |
+
+### Input: bbb-4k-h264.mp4
+
+| Test | FFmpeg CLI (FPS) | node-av (FPS) | FFmpeg CLI (Time) | node-av (Time) | Diff |
+|------|------------------|---------------|-------------------|----------------|------|
+| SW H.264 Transcode | 96.5 fps | 97.2 fps | 18.65s | 18.52s | +0.7% |
+| SW H.265 Transcode | 40.0 fps | 39.9 fps | 45.00s | 45.12s | -0.2% |
+| HW H.264 Transcode | 54.6 fps | 54.9 fps | 32.98s | 32.83s | +0.5% |
+| Stream Copy (Remux) | 38235.1 fps | 30884.8 fps | 48ms | 104ms | -19.2% |
+
+### Input: bbb-4k-hevc.mp4
+
+| Test | FFmpeg CLI (FPS) | node-av (FPS) | FFmpeg CLI (Time) | node-av (Time) | Diff |
+|------|------------------|---------------|-------------------|----------------|------|
+| SW H.264 Transcode | 96.3 fps | 95.9 fps | 18.70s | 18.78s | -0.4% |
+| SW H.265 Transcode | 41.4 fps | 41.8 fps | 43.49s | 43.06s | +1.0% |
+| HW H.264 Transcode | 54.5 fps | 54.9 fps | 33.00s | 32.82s | +0.6% |
+| Stream Copy (Remux) | 55110.3 fps | 30395.4 fps | 33ms | 106ms | -44.8% |
+
+### Input: bbb-4k-vp9.webm
+
+| Test | FFmpeg CLI (FPS) | node-av (FPS) | FFmpeg CLI (Time) | node-av (Time) | Diff |
+|------|------------------|---------------|-------------------|----------------|------|
+| SW H.264 Transcode | 96.5 fps | 96.1 fps | 18.66s | 18.75s | -0.4% |
+| SW H.265 Transcode | 41.6 fps | 42.0 fps | 43.23s | 42.90s | +0.8% |
+| HW H.264 Transcode | 54.6 fps | 54.8 fps | 32.98s | 32.85s | +0.4% |
+| Stream Copy (Remux) | 48635.3 fps | 31617.3 fps | 37ms | 105ms | -35.0% |
+
+
+## Memory Usage
+
+### Input: bbb-4k-av1.mp4
+
+| Test | FFmpeg CLI Peak | node-av Peak | Difference |
+|------|----------------|--------------|------------|
+| Memory: H.264 Transcode | 3.5 GB | 3.5 GB | -2.0% |
+| Memory: Stream Copy | 19.9 MB | 1.1 MB | -94.6% |
+
+### Input: bbb-4k-h264.mp4
+
+| Test | FFmpeg CLI Peak | node-av Peak | Difference |
+|------|----------------|--------------|------------|
+| Memory: H.264 Transcode | 3.7 GB | 3.4 GB | -6.0% |
+| Memory: Stream Copy | 40.7 MB | 1.9 MB | -95.2% |
+
+### Input: bbb-4k-hevc.mp4
+
+| Test | FFmpeg CLI Peak | node-av Peak | Difference |
+|------|----------------|--------------|------------|
+| Memory: H.264 Transcode | 3.8 GB | 3.5 GB | -5.4% |
+| Memory: Stream Copy | 20.5 MB | 320.0 KB | -98.5% |
+
+### Input: bbb-4k-vp9.webm
+
+| Test | FFmpeg CLI Peak | node-av Peak | Difference |
+|------|----------------|--------------|------------|
+| Memory: H.264 Transcode | 3.5 GB | 3.3 GB | -4.7% |
+| Memory: Stream Copy | 30.6 MB | 378.7 KB | -98.8% |
+
+*Note: FFmpeg CLI memory is measured via `/usr/bin/time` (macOS: `-l`, Linux: `-v`).
+
+
+## Latency
+
+| Metric | Mean | Min | Max | StdDev |
+|--------|------|-----|-----|--------|
+| Demuxer Open | 466µs | 430µs | 561µs | 41µs |
+| First Packet | 530µs | 491µs | 575µs | 30µs |
+| First Frame | 11.7ms | 7.2ms | 15.2ms | 2.7ms |
+| First Encoded Packet | 25.2ms | 23.9ms | 26.9ms | 856µs |
+| Pipeline Total | 25.8ms | 22.5ms | 27.3ms | 1.4ms |
+
+*Note: Each metric is measured independently. "First Encoded Packet" uses default encoder settings while "Pipeline Total" uses `tune=zerolatency` for low-latency output.*
+

package/README.md

@@ -35,8 +35,10 @@ Native Node.js bindings for FFmpeg with full TypeScript support. Provides direct
 - [Resource Management](#resource-management)
 - [FFmpeg Binary Access](#ffmpeg-binary-access)
 - [Performance](#performance)
+  - [Benchmarks](#benchmarks)
   - [Sync vs Async Operations](#sync-vs-async-operations)
 - [Memory Safety Considerations](#memory-safety-considerations)
+- [Electron](#electron)
 - [Examples](#examples)
 - [Prebuilt Binaries](#prebuilt-binaries)
 - [Troubleshooting](#troubleshooting)
@@ -426,6 +428,25 @@ The FFmpeg binary is automatically downloaded during installation from GitHub re
 
 NodeAV executes all media operations directly through FFmpeg's native C libraries. The Node.js bindings add minimal overhead - mostly just the JavaScript-to-C boundary crossings. During typical operations like transcoding or filtering, most processing time is spent in FFmpeg's optimized C code.
 
+### Benchmarks
+
+Performance comparison with FFmpeg CLI (4K 60fps, 30s test files on Apple M3 Max):
+
+| Operation | FFmpeg CLI (FPS) | node-av (FPS) | FFmpeg CLI (Time) | node-av (Time) | Diff |
+|-----------|------------------|---------------|-------------------|----------------|------|
+| SW H.264 Transcode | 96 fps | 96 fps | 18.7s | 18.7s | ≈0% |
+| SW H.265 Transcode | 40 fps | 41 fps | 44.5s | 43.7s | **+1.5%** |
+| HW H.264 Transcode | 55 fps | 55 fps | 33.0s | 32.8s | **+0.5%** |
+| Stream Copy (Remux) | 48k fps | 31k fps | 38ms | 106ms | -35% |
+
+**Memory Usage:**
+| Operation | FFmpeg CLI | node-av | Difference |
+|-----------|-----------|---------|------------|
+| H.264 Transcode (4K) | 3.6 GB | 3.4 GB | **-5%** |
+| Stream Copy | 28 MB | 1 MB | **-96%** |
+
+📊 **[Full benchmark results](https://github.com/seydx/node-av/tree/main/BENCHMARK.md)**
+
 ### Sync vs Async Operations
 
 Every async method in NodeAV has a corresponding synchronous variant with the `Sync` suffix:
@@ -440,6 +461,22 @@ The key difference: Async methods don't block the Node.js event loop, allowing o
 
 NodeAV provides direct bindings to FFmpeg's C APIs, which work with raw memory pointers. The high-level API adds safety abstractions and automatic resource management, but incorrect usage can still cause crashes. Common issues include mismatched video dimensions, incompatible pixel formats, or improper frame buffer handling. The library validates parameters where possible, but can't guarantee complete memory safety without limiting functionality. When using the low-level API, pay attention to parameter consistency, resource cleanup, and format compatibility. Following the documented patterns helps avoid memory-related issues.
 
+## Electron
+
+NodeAV fully supports Electron applications. The prebuilt binaries are ABI-compatible with Electron, so no native rebuild is required during packaging. Both the native bindings and the bundled FFmpeg CLI binaries work seamlessly within Electron's main process.
+
+Two complete examples are available: one using [Electron Forge](https://github.com/seydx/node-av/tree/main/examples/electron/forge) and one using [Electron Builder](https://github.com/seydx/node-av/tree/main/examples/electron/builder).
+
+If you encounter module resolution errors like `Cannot find module 'lib/binary-stream'`, add this override to your project's `package.json`:
+
+```json
+{
+  "overrides": {
+    "@shinyoshiaki/binary-data": "npm:@seydx/binary-data@0.6.2"
+  }
+}
+```
+
 ## Examples
 
 | Example | FFmpeg | Low-Level API | High-Level API |
@@ -473,6 +510,7 @@ NodeAV provides direct bindings to FFmpeg's C APIs, which work with raw memory p
 | `api-whisper-transcribe` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-whisper-transcribe.ts) |
 | `frame-utils` | | [✓](https://github.com/seydx/node-av/tree/main/examples/frame-utils.ts) | |
 | `avio-read-callback` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/avio_read_callback.c) | [✓](https://github.com/seydx/node-av/tree/main/examples/avio-read-callback.ts) | |
+| `avio-async-read-callback` | | [✓](https://github.com/seydx/node-av/tree/main/examples/avio-async-read-callback.ts) | |
 | `decode-audio` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/decode_audio.c) | [✓](https://github.com/seydx/node-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/node-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/node-av/tree/main/examples/decode-filter-video.ts) | |
@@ -498,7 +536,6 @@ NodeAV provides direct bindings to FFmpeg's C APIs, which work with raw memory p
 | `transcode-aac` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/transcode_aac.c) | [✓](https://github.com/seydx/node-av/tree/main/examples/transcode-aac.ts) | |
 | `transcode` | [✓](https://github.com/FFmpeg/FFmpeg/tree/master/doc/examples/transcode.c) | [✓](https://github.com/seydx/node-av/tree/main/examples/transcode.ts) | |
 
-
 ## Prebuilt Binaries
 
 Prebuilt binaries are available for multiple platforms:
@@ -562,3 +599,24 @@ For issues and questions, please use the GitHub issue tracker.
 - [FFmpeg Doxygen](https://ffmpeg.org/doxygen/trunk/)
 - [Jellyfin FFmpeg](https://github.com/seydx/jellyfin-ffmpeg)
 - [FFmpeg MSVC](https://github.com/seydx/ffmpeg-msvc-prebuilt)
+
+## Star History
+
+<picture>
+  <source
+    media="(prefers-color-scheme: dark)"
+    srcset="
+      https://api.star-history.com/svg?repos=seydx/node-av&type=Date&theme=dark
+    "
+  />
+  <source
+    media="(prefers-color-scheme: light)"
+    srcset="
+      https://api.star-history.com/svg?repos=seydx/node-av&type=Date
+    "
+  />
+  <img
+    alt="Star History Chart"
+    src="https://api.star-history.com/svg?repos=seydx/node-av&type=Date"
+  />
+</picture>

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

@@ -2,6 +2,7 @@ import { Packet } from '../lib/packet.js';
 import { Muxer } from './muxer.js';
 import { Scheduler, SchedulerControl } from './utilities/scheduler.js';
 import type { Stream } from '../lib/stream.js';
+import type { BitstreamFilterOptions } from './types.js';
 /**
  * High-level bitstream filter for packet processing.
  *
@@ -74,6 +75,8 @@ export declare class BitStreamFilterAPI implements Disposable {
      *
      * @param stream - Stream to apply filter to
      *
+     * @param filterOptions - Optional filter-specific options
+     *
      * @returns Configured bitstream filter
      *
      * @throws {Error} If initialization fails
@@ -94,13 +97,24 @@ export declare class BitStreamFilterAPI implements Disposable {
      *
      * @example
      * ```typescript
-     * // Remove metadata
-     * const filter = BitStreamFilterAPI.create('filter_units', stream);
+     * // 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 }
+     * });
      * ```
      *
      * @see {@link BitStreamFilter.getByName} For filter discovery
+     * @see {@link BitstreamFilterOptions} For available options
      */
-    static create(filterName: string, stream: Stream): BitStreamFilterAPI;
+    static create(filterName: string, stream: Stream, filterOptions?: BitstreamFilterOptions): BitStreamFilterAPI;
     /**
      * Get filter name.
      *
@@ -147,74 +161,112 @@ export declare class BitStreamFilterAPI implements Disposable {
      */
     get isBitstreamFilterOpen(): boolean;
     /**
-     * Filter a packet.
-     *
-     * Sends a packet to the filter and attempts to receive a filtered packet.
-     * Handles internal buffering - may return null if more packets needed.
+     * Send a packet to the filter.
      *
-     * **Note**: This method receives only ONE packet per call.
-     * A single packet can produce multiple output packets (e.g., codec buffering).
-     * To receive all packets from a packet, use {@link filterAll} or {@link packets} instead.
+     * Sends a packet to the filter for processing.
+     * Does not return filtered packets - use {@link receive} to retrieve packets.
+     * A single packet can produce zero, one, or multiple packets depending on filter.
      *
-     * Direct mapping to av_bsf_send_packet() and av_bsf_receive_packet().
+     * **Important**: This method only SENDS the packet to the filter.
+     * You must call {@link receive} separately (potentially multiple times) to get filtered packets.
      *
-     * @param packet - Packet to filter
+     * Direct mapping to av_bsf_send_packet().
      *
-     * @returns Filtered packet, null if more data needed, or null if filter is closed
+     * @param packet - Packet to send to filter, or null to flush
      *
-     * @throws {FFmpegError} If filtering fails
+     * @throws {FFmpegError} If sending fails
      *
      * @example
      * ```typescript
-     * const outPacket = await filter.filter(inputPacket);
-     * if (outPacket) {
-     *   console.log(`Filtered packet: pts=${outPacket.pts}`);
+     * // Send packet and receive filtered packets
+     * await filter.filter(inputPacket);
+     *
+     * // Receive all available filtered packets
+     * while (true) {
+     *   const outPacket = await filter.receive();
+     *   if (!outPacket) break;
+     *   console.log(`Filtered packet with PTS: ${outPacket.pts}`);
      *   await output.writePacket(outPacket);
      *   outPacket.free();
      * }
      * ```
      *
-     * @see {@link filterAll} For multiple packet filtering
-     * @see {@link packets} For stream processing
+     * @example
+     * ```typescript
+     * for await (const packet of input.packets()) {
+     *   // packet is null at end of stream - automatically flushes filter
+     *   await filter.filter(packet);
+     *
+     *   // Receive available filtered packets
+     *   let outPacket;
+     *   while ((outPacket = await filter.receive())) {
+     *     await output.writePacket(outPacket);
+     *     outPacket.free();
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link receive} For receiving filtered packets
+     * @see {@link filterAll} For combined send+receive operation
+     * @see {@link packets} For automatic packet iteration
      * @see {@link flush} For end-of-stream handling
      * @see {@link filterSync} For synchronous version
      */
-    filter(packet: Packet): Promise<Packet | null>;
+    filter(packet: Packet | null): Promise<void>;
     /**
-     * Filter a packet synchronously.
+     * Send a packet to the filter synchronously.
      * Synchronous version of filter.
      *
-     * Sends a packet to the filter and attempts to receive a filtered packet.
-     * Handles internal buffering - may return null if more packets needed.
+     * Sends a packet to the filter for processing.
+     * Does not return filtered packets - use {@link receiveSync} to retrieve packets.
+     * A single packet can produce zero, one, or multiple packets depending on filter.
      *
-     * **Note**: This method receives only ONE packet per call.
-     * A single packet can produce multiple output packets (e.g., codec buffering).
-     * To receive all packets from a packet, use {@link filterAllSync} or {@link packetsSync} instead.
+     * **Important**: This method only SENDS the packet to the filter.
+     * You must call {@link receiveSync} separately (potentially multiple times) to get filtered packets.
      *
-     * Direct mapping to av_bsf_send_packet() and av_bsf_receive_packet().
+     * Direct mapping to av_bsf_send_packet().
      *
-     * @param packet - Packet to filter
+     * @param packet - Packet to send to filter, or null to flush
      *
-     * @returns Filtered packet, null if more data needed, or null if filter is closed
-     *
-     * @throws {FFmpegError} If filtering fails
+     * @throws {FFmpegError} If sending fails
      *
      * @example
      * ```typescript
-     * const outPacket = filter.filterSync(inputPacket);
-     * if (outPacket) {
-     *   console.log(`Filtered packet: pts=${outPacket.pts}`);
+     * // Send packet and receive filtered packets
+     * filter.filterSync(inputPacket);
+     *
+     * // Receive all available filtered packets
+     * while (true) {
+     *   const outPacket = filter.receiveSync();
+     *   if (!outPacket) break;
+     *   console.log(`Filtered packet with PTS: ${outPacket.pts}`);
      *   output.writePacketSync(outPacket);
      *   outPacket.free();
      * }
      * ```
      *
-     * @see {@link filterAllSync} For multiple packet filtering
-     * @see {@link packetsSync} For stream processing
+     * @example
+     * ```typescript
+     * for (const packet of packets) {
+     *   // packet is null at end of stream - automatically flushes filter
+     *   filter.filterSync(packet);
+     *
+     *   // Receive available filtered packets
+     *   let outPacket;
+     *   while ((outPacket = filter.receiveSync())) {
+     *     output.writePacketSync(outPacket);
+     *     outPacket.free();
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link receiveSync} For receiving filtered packets
+     * @see {@link filterAllSync} For combined send+receive operation
+     * @see {@link packetsSync} For automatic packet iteration
      * @see {@link flushSync} For end-of-stream handling
      * @see {@link filter} For async version
      */
-    filterSync(packet: Packet): Packet | null;
+    filterSync(packet: Packet | null): void;
     /**
      * Filter a packet to packets.
      *
@@ -224,7 +276,7 @@ export declare class BitStreamFilterAPI implements Disposable {
      *
      * Direct mapping to av_bsf_send_packet() and av_bsf_receive_packet().
      *
-     * @param packet - Packet to filter
+     * @param packet - Packet to filter, or null to flush
      *
      * @returns Array of filtered packets (empty if more data needed or filter is closed)
      *
@@ -240,12 +292,22 @@ export declare class BitStreamFilterAPI implements Disposable {
      * }
      * ```
      *
+     * @example
+     * ```typescript
+     * // Flush remaining packets at end of stream
+     * const remaining = await filter.filterAll(null);
+     * for (const packet of remaining) {
+     *   await output.writePacket(packet);
+     *   packet.free();
+     * }
+     * ```
+     *
      * @see {@link filter} For single packet filtering
      * @see {@link packets} For stream processing
      * @see {@link flush} For end-of-stream handling
      * @see {@link filterAllSync} For synchronous version
      */
-    filterAll(packet: Packet): Promise<Packet[]>;
+    filterAll(packet: Packet | null): Promise<Packet[]>;
     /**
      * Filter a packet to packets synchronously.
      * Synchronous version of filterAll.
@@ -256,7 +318,7 @@ export declare class BitStreamFilterAPI implements Disposable {
      *
      * Direct mapping to av_bsf_send_packet() and av_bsf_receive_packet().
      *
-     * @param packet - Packet to filter
+     * @param packet - Packet to filter, or null to flush
      *
      * @returns Array of filtered packets (empty if more data needed or filter is closed)
      *
@@ -272,88 +334,142 @@ export declare class BitStreamFilterAPI implements Disposable {
      * }
      * ```
      *
+     * @example
+     * ```typescript
+     * // Flush remaining packets at end of stream
+     * const remaining = filter.filterAllSync(null);
+     * for (const packet of remaining) {
+     *   output.writePacketSync(packet);
+     *   packet.free();
+     * }
+     * ```
+     *
      * @see {@link filterSync} For single packet filtering
      * @see {@link packetsSync} For stream processing
      * @see {@link flushSync} For end-of-stream handling
      * @see {@link filterAll} For async version
      */
-    filterAllSync(packet: Packet): Packet[];
+    filterAllSync(packet: Packet | null): Packet[];
     /**
-     * Process packet stream through filter.
+     * Filter packet stream to filtered packet stream.
      *
-     * High-level async generator for filtering packet streams.
-     * Automatically handles flushing at end of stream.
-     * Yields filtered packets ready for output.
+     * High-level async generator for complete filtering pipeline.
+     * Filter is only flushed when EOF (null) signal is explicitly received.
+     * Primary interface for stream-based filtering.
      *
-     * @param packets - Async iterable of packets
+     * **EOF Handling:**
+     * - Send null to flush filter and get remaining buffered packets
+     * - Generator yields null after flushing when null is received
+     * - No automatic flushing - filter stays open until EOF or close()
      *
-     * @yields {Packet} Filtered packets
+     * @param packets - Async iterable of packets, single packet, or null to flush
+     *
+     * @yields {Packet | null} Filtered packets, followed by null when explicitly flushed
      *
      * @throws {FFmpegError} If filtering fails
      *
      * @example
      * ```typescript
-     * // Filter entire stream
+     * // Stream of packets with automatic EOF propagation
      * for await (const packet of filter.packets(input.packets())) {
+     *   if (packet === null) {
+     *     console.log('Filter flushed');
+     *     break;
+     *   }
      *   await output.writePacket(packet);
-     *   packet.free();
+     *   packet.free(); // Must free output packets
      * }
      * ```
      *
      * @example
      * ```typescript
-     * // Chain with decoder
-     * const decoder = await Decoder.create(stream);
-     * const filter = BitStreamFilterAPI.create('h264_mp4toannexb', stream);
+     * // Single packet - no automatic flush
+     * for await (const packet of filter.packets(singlePacket)) {
+     *   await output.writePacket(packet);
+     *   packet.free();
+     * }
+     * // Filter remains open, buffered packets not flushed
+     * ```
      *
-     * for await (const frame of decoder.frames(filter.packets(input.packets()))) {
-     *   // Process frames
-     *   frame.free();
+     * @example
+     * ```typescript
+     * // Explicit flush with EOF
+     * for await (const packet of filter.packets(null)) {
+     *   if (packet === null) {
+     *     console.log('All buffered packets flushed');
+     *     break;
+     *   }
+     *   console.log('Buffered packet:', packet.pts);
+     *   await output.writePacket(packet);
+     *   packet.free();
      * }
      * ```
      *
-     * @see {@link filterAll} For filtering single packets
-     * @see {@link flush} For end-of-stream handling
+     * @see {@link filter} For single packet filtering
+     * @see {@link Demuxer.packets} For packet source
+     * @see {@link packetsSync} For sync version
      */
-    packets(packets: AsyncIterable<Packet | null>): AsyncGenerator<Packet | null>;
+    packets(packets: AsyncIterable<Packet | null> | Packet | null): AsyncGenerator<Packet | null>;
     /**
-     * Process packet stream through filter synchronously.
+     * Filter packet stream to filtered packet stream synchronously.
      * Synchronous version of packets.
      *
-     * High-level sync generator for filtering packet streams.
-     * Automatically handles flushing at end of stream.
-     * Yields filtered packets ready for output.
+     * High-level sync generator for complete filtering pipeline.
+     * Filter is only flushed when EOF (null) signal is explicitly received.
+     * Primary interface for stream-based filtering.
+     *
+     * **EOF Handling:**
+     * - Send null to flush filter and get remaining buffered packets
+     * - Generator yields null after flushing when null is received
+     * - No automatic flushing - filter stays open until EOF or close()
      *
-     * @param packets - Iterable of packets
+     * @param packets - Iterable of packets, single packet, or null to flush
      *
-     * @yields {Packet} Filtered packets
+     * @yields {Packet | null} Filtered packets, followed by null when explicitly flushed
      *
      * @throws {FFmpegError} If filtering fails
      *
      * @example
      * ```typescript
-     * // Filter entire stream
-     * for (const packet of filter.packetsSync(packets)) {
+     * // Stream of packets with automatic EOF propagation
+     * for (const packet of filter.packetsSync(inputPackets)) {
+     *   if (packet === null) {
+     *     console.log('Filter flushed');
+     *     break;
+     *   }
      *   output.writePacketSync(packet);
-     *   packet.free();
+     *   packet.free(); // Must free output packets
      * }
      * ```
      *
      * @example
      * ```typescript
-     * // Chain with decoder
-     * const decoder = await Decoder.create(stream);
-     * const filter = BitStreamFilterAPI.create('h264_mp4toannexb', stream);
+     * // Single packet - no automatic flush
+     * for (const packet of filter.packetsSync(singlePacket)) {
+     *   output.writePacketSync(packet);
+     *   packet.free();
+     * }
+     * // Filter remains open, buffered packets not flushed
+     * ```
      *
-     * for (const frame of decoder.framesSync(filter.packetsSync(packets))) {
-     *   // Process frames
-     *   frame.free();
+     * @example
+     * ```typescript
+     * // Explicit flush with EOF
+     * for (const packet of filter.packetsSync(null)) {
+     *   if (packet === null) {
+     *     console.log('All buffered packets flushed');
+     *     break;
+     *   }
+     *   console.log('Buffered packet:', packet.pts);
+     *   output.writePacketSync(packet);
+     *   packet.free();
      * }
      * ```
      *
+     * @see {@link filterSync} For single packet filtering
      * @see {@link packets} For async version
      */
-    packetsSync(packets: Iterable<Packet | null>): Generator<Packet | null>;
+    packetsSync(packets: Iterable<Packet | null> | Packet | null): Generator<Packet | null>;
     /**
      * Flush filter and signal end-of-stream.
      *