node-av 5.0.4 → 5.2.0-beta.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,6 +35,7 @@ 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)
 - [Examples](#examples)
@@ -426,6 +427,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:
@@ -473,6 +493,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) | |
@@ -562,3 +583,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.
      *