node-av 3.1.3 → 5.0.0

package/README.md

@@ -22,6 +22,7 @@ Native Node.js bindings for FFmpeg with full TypeScript support. Provides direct
   - [Low-Level API](#low-level-api)
   - [High-Level API](#high-level-api)
   - [Pipeline API](#pipeline-api)
+- [Key Features](#key-features)
 - [Hardware Acceleration](#hardware-acceleration)
   - [Auto-Detection](#auto-detection)
   - [Specific Hardware](#specific-hardware)
@@ -90,10 +91,6 @@ decoderCtx.allocContext3(codec);
 ret = decoderCtx.parametersToContext(videoStream.codecpar);
 FFmpegError.throwIfError(ret, 'Could not copy codec parameters to decoder context');
 
-// Inform the decoder about the timebase for packet timestamps and the frame rate
-decoderCtx.pktTimebase = videoStream.timeBase;
-decoderCtx.framerate = videoStream.rFrameRate || videoStream.avgFrameRate || new Rational(25, 1);
-
 // Open decoder context
 ret = await decoderCtx.open2(codec, null);
 FFmpegError.throwIfError(ret, 'Could not open codec');
@@ -140,49 +137,45 @@ while (true) {
 Higher-level abstractions for common tasks like decoding, encoding, filtering, and transcoding. Easier to use while still providing access to low-level details when needed.
 
 ```typescript
-import { Decoder, Encoder, MediaInput, MediaOutput } from 'node-av/api';
+import { Decoder, Demuxer, Encoder, HardwareContext, Muxer } from 'node-av/api';
 import { FF_ENCODER_LIBX264 } from 'node-av/constants';
 
-// Open media
-await using input = await MediaInput.open('input.mp4');
-await using output = await MediaOutput.open('output.mp4');
+// Open Demuxer
+await using input = await Demuxer.open('input.mp4');
 
 // Get video stream
 const videoStream = input.video()!;
 
+// Optional, setup hardware acceleration
+using hw = HardwareContext.auto();
+
 // Create decoder
-using decoder = await Decoder.create(videoStream);
+using decoder = await Decoder.create(videoStream, {
+  hardware: hw, // Optional, use hardware acceleration if available
+});
 
 // Create encoder
 using encoder = await Encoder.create(FF_ENCODER_LIBX264, {
-  timeBase: videoStream.timeBase,
-  frameRate: videoStream.avgFrameRate,
+  decoder, // Optional, copy settings from decoder
 });
 
-// Add stream to output
-const outputIndex = output.addStream(encoder);
+// Open Muxer
+await using output = await Muxer.open('output.mp4', {
+  input, // Optional, used to copy global headers and metadata
+});
 
-// Process packets
-for await (using packet of input.packets(videoStream.index)) {
-  using frame = await decoder.decode(packet);
-  if (frame) {
-    using encoded = await encoder.encode(frame);
-    if (encoded) {
-      await output.writePacket(encoded, outputIndex);
-    }
-  }
-}
+// Add stream to output
+const outputIndex = output.addStream(encoder, {
+  inputStream: videoStream, // Optional, copy settings from input stream
+});
 
-// Flush decoder
-for await (using frame of decoder.flushFrames()) {
-  using encoded = await encoder.encode(frame);
-  if (encoded) {
-    await output.writePacket(encoded, outputIndex);
-  }
-}
+// Create processing generators
+const inputGenerator = input.packets(videoStream.index);
+const decoderGenerator = decoder.frames(inputGenerator);
+const encoderGenerator = encoder.packets(decoderGenerator);
 
-// Flush encoder
-for await (using packet of encoder.flushPackets()) {
+// Process packets
+for await (using packet of encoderGenerator) {
   await output.writePacket(packet, outputIndex);
 }
 
@@ -194,21 +187,57 @@ for await (using packet of encoder.flushPackets()) {
 A simple way to chain together multiple processing steps like decoding, filtering, encoding, and muxing.
 
 ```typescript
-import { pipeline, MediaInput, MediaOutput, Decoder, Encoder } from 'node-av/api';
+import { Decoder, Demuxer, Encoder, HardwareContext, Muxer, pipeline } from 'node-av/api';
+import { FF_ENCODER_LIBX264 } from 'node-av/constants';
 
 // Simple transcode pipeline: input → decoder → encoder → output
-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(FF_ENCODER_LIBX264, {
-  timeBase: videoStream.timeBase,
-  frameRate: videoStream.avgFrameRate,
+
+// Open Demuxer
+await using input = await Demuxer.open('input.mp4');
+
+// Get video stream
+const videoStream = input.video()!;
+
+// Optional, setup hardware acceleration
+using hw = HardwareContext.auto();
+
+// Create decoder
+using decoder = await Decoder.create(videoStream, {
+  hardware: hw, // Optional, use hardware acceleration if available
+});
+
+// Create encoder
+using encoder = await Encoder.create(FF_ENCODER_LIBX264, {
+  decoder, // Optional, copy settings from decoder
+});
+
+// Open Muxer
+await using output = await Muxer.open('output.mp4', {
+  input, // Optional, used to copy global headers and metadata
 });
 
 const control = pipeline(input, decoder, encoder, output);
 await control.completion;
 ```
 
+## Key Features
+
+Beyond basic transcoding, NodeAV provides advanced media processing capabilities:
+
+**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.
+
+**Advanced Video Filtering with FilterComplexAPI**
+Build sophisticated video processing pipelines using FFmpeg's complete filter ecosystem. The FilterComplexAPI provides direct access to complex filtergraphs with multiple inputs and outputs, enabling advanced operations like picture-in-picture overlays, multi-stream composition (side-by-side, grid layouts), real-time video effects, and custom processing chains. All filters support hardware acceleration where available, and filter configurations can be dynamically constructed based on runtime requirements.
+
+**Browser Streaming**
+Stream any media source directly to web browsers through fragmented MP4 (fMP4) or WebRTC protocols. The library can process inputs from RTSP cameras, local files, network streams, or custom sources and package them for browser consumption with minimal latency. Complete examples demonstrate both Media Source Extensions (MSE) based playback for on-demand content and WebRTC integration for real-time streaming scenarios.
+
+**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.
+
+See the [Examples](#examples) section for complete implementations.
+
 ## Hardware Acceleration
 
 The library supports all hardware acceleration methods available in FFmpeg. The specific hardware types available depend on your FFmpeg build and system configuration.
@@ -231,8 +260,7 @@ const decoder = await Decoder.create(stream, {
 // Use with encoder (use hardware-specific codec)
 const encoderCodec = hw?.getEncoderCodec('h264') ?? FF_ENCODER_LIBX264;
 const encoder = await Encoder.create(encoderCodec, {
-  timeBase: videoStream.timeBase,
-  frameRate: videoStream.avgFrameRate,
+  decoder,
 });
 ```
 
@@ -252,7 +280,7 @@ The library provides multiple entry points for optimal tree shaking:
 
 ```typescript
 // High-Level API only - Recommended for most use cases
-import { MediaInput, MediaOutput, Decoder, Encoder } from 'node-av/api';
+import { Muxer, Muxer, Decoder, Encoder } from 'node-av/api';
 
 // Low-Level API only - Direct FFmpeg bindings
 import { FormatContext, CodecContext, Frame, Packet } from 'node-av/lib';
@@ -272,11 +300,11 @@ import * as ffmpeg from 'node-av';
 ### From Files or Network
 
 ```typescript
-const media = await MediaInput.open('input.mp4');
+const media = await Muxer.open('input.mp4');
 
 // or
 
-const media = await MediaInput.open('rtsp://example.com/stream');
+const media = await Muxer.open('rtsp://example.com/stream');
 ```
 
 ### From Buffers
@@ -285,7 +313,7 @@ const media = await MediaInput.open('rtsp://example.com/stream');
 import { readFile } from 'fs/promises';
 
 const buffer = await readFile('input.mp4');
-const media = await MediaInput.open(buffer);
+const media = await Muxer.open(buffer);
 ```
 
 ### Custom I/O Callbacks
@@ -305,7 +333,7 @@ const inputCallbacks: IOInputCallbacks = {
   }
 };
 
-await using input = await MediaInput.open(inputCallbacks, {
+await using input = await Muxer.open(inputCallbacks, {
   format: 'mp4'
 });
 ```
@@ -314,7 +342,7 @@ await using input = await MediaInput.open(inputCallbacks, {
 
 ```typescript
 // Raw video input
-const rawVideo = await MediaInput.open({
+const rawVideo = await Muxer.open({
   type: 'video',
   input: 'input.yuv',
   width: 1280,
@@ -324,7 +352,7 @@ const rawVideo = await MediaInput.open({
 });
 
 // Raw audio input
-const rawAudio = await MediaInput.open({
+const rawAudio = await Muxer.open({
   type: 'audio',
   input: 'input.pcm',
   sampleRate: 48000,
@@ -342,13 +370,13 @@ The library supports automatic resource cleanup using the Disposable pattern:
 ```typescript
 // Automatic cleanup with 'using'
 {
-  await using media = await MediaInput.open('input.mp4');
+  await using media = await Muxer.open('input.mp4');
   using decoder = await Decoder.create(media.video());
   // Resources automatically cleaned up at end of scope
 }
 
 // Manual cleanup
-const media = await MediaInput.open('input.mp4');
+const media = await Muxer.open('input.mp4');
 try {
   // Process media
 } finally {
@@ -420,21 +448,29 @@ NodeAV provides direct bindings to FFmpeg's C APIs, which work with raw memory p
 | `browser-webrtc` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/browser/webrtc) |
 | `api-dash` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-dash.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-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) |
 | `api-hw-decode-sw-encode` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-hw-decode-sw-encode.ts) |
 | `api-hw-raw` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-hw-raw.ts) |
 | `api-hw-raw-output` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-hw-raw-output.ts) |
-| `api-hw-rtsp-custom-io` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-hw-rtsp-custom-io.ts) |
 | `api-hw-rtsp` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-hw-rtsp.ts) |
+| `api-hw-stream-custom-io` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-hw-stream-custom-io.ts) |
 | `api-hw-transcode` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-hw-transcode.ts) |
 | `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-raw-muxing` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-pipeline-raw-muxing.ts) |
-| `api-sdp` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-sdp.ts) |
+| `api-rtp` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-rtp.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-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) |
+| `api-whisper-subtitles` | | | [✓](https://github.com/seydx/node-av/tree/main/examples/api-whisper-subtitles.ts) |
+| `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) | |
 | `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) | |

package/binding.gyp

@@ -51,17 +51,23 @@
                 "src/bindings/audio_fifo.cc",
                 "src/bindings/audio_fifo_async.cc",
                 "src/bindings/audio_fifo_sync.cc",
+                "src/bindings/fifo.cc",
+                "src/bindings/fifo_async.cc",
+                "src/bindings/fifo_sync.cc",
                 "src/bindings/frame_utils.cc",
                 "src/bindings/bitstream_filter.cc",
                 "src/bindings/bitstream_filter_context.cc",
                 "src/bindings/bitstream_filter_context_async.cc",
                 "src/bindings/bitstream_filter_context_sync.cc",
                 "src/bindings/option.cc",
+                "src/bindings/sync_queue.cc",
+                "externals/jellyfin-ffmpeg/fftools/sync_queue.c",
             ],
             "include_dirs": [
                 "<!@(node -p \"require('node-addon-api').include\")",
                 "/opt/ffbuild/prefix/include",
                 "<(module_root_dir)/externals/jellyfin-ffmpeg",
+                "<(module_root_dir)/externals/jellyfin-ffmpeg/libavcodec",
             ],
             "library_dirs": ["/opt/ffbuild/prefix/lib"],
             "dependencies": ["<!(node -p \"require('node-addon-api').gyp\")"],
@@ -102,17 +108,21 @@
                 "/opt/ffbuild/prefix/lib/libudfread.a",
                 "/opt/ffbuild/prefix/lib/libz.a",
                 "/opt/ffbuild/prefix/lib/liblzma.a",
-                "<!@(ls /opt/ffbuild/prefix/lib/libNE10.a 2>/dev/null || echo '')",
-                "<!@(ls /opt/ffbuild/prefix/lib/libwebpdemux.a 2>/dev/null || echo '')",
-                "<!@(ls /opt/ffbuild/prefix/lib/libchromaprint.a 2>/dev/null || echo '')",
-                "<!@(ls /opt/ffbuild/prefix/lib/libopenmpt.a 2>/dev/null || echo '')",
-                "<!@(ls /opt/ffbuild/prefix/lib/libxml2.a 2>/dev/null || echo '')",
-                "<!@(ls /opt/ffbuild/prefix/lib/libbz2.a 2>/dev/null || echo '')",
-                "<!@(ls /opt/ffbuild/prefix/lib/libzvbi.a 2>/dev/null || echo '')",
-                "<!@(ls /opt/ffbuild/prefix/lib/libzimg.a 2>/dev/null || echo '')",
-                "<!@(ls /opt/ffbuild/prefix/lib/libgmp.a 2>/dev/null || echo '')",
-                "<!@(ls /opt/ffbuild/prefix/lib/libssl.a 2>/dev/null || echo '')",
-                "<!@(ls /opt/ffbuild/prefix/lib/libcrypto.a 2>/dev/null || echo '')",
+                "/opt/ffbuild/prefix/lib/libfdk-aac.a",
+                "/opt/ffbuild/prefix/lib/libNE10.a",
+                "/opt/ffbuild/prefix/lib/libchromaprint.a",
+                "/opt/ffbuild/prefix/lib/libopenmpt.a",
+                "/opt/ffbuild/prefix/lib/libzvbi.a",
+                "/opt/ffbuild/prefix/lib/libzimg.a",
+                "/opt/ffbuild/prefix/lib/libgmp.a",
+                "/opt/ffbuild/prefix/lib/libssl.a",
+                "/opt/ffbuild/prefix/lib/libcrypto.a",
+                "/opt/ffbuild/prefix/lib/libwhisper.a",
+                "/opt/ffbuild/prefix/lib/libggml.a",
+                "/opt/ffbuild/prefix/lib/libggml-base.a",
+                "/opt/ffbuild/prefix/lib/libggml-cpu.a",
+                "/opt/ffbuild/prefix/lib/libggml-blas.a",
+                "/opt/ffbuild/prefix/lib/libggml-metal.a",
                 "-liconv",
                 "-lxml2",
                 "-lbz2",
@@ -129,6 +139,8 @@
                 "-framework IOKit",
                 "-framework OpenGL",
                 "-framework Metal",
+                "-framework MetalKit",
+                "-framework Foundation",
                 "-framework OpenCL",
             ],
             "xcode_settings": {

package/dist/api/audio-frame-buffer.d.ts

@@ -0,0 +1,201 @@
+import { Frame } from '../lib/frame.js';
+import type { AVSampleFormat } from '../constants/index.js';
+import type { ChannelLayout } from '../lib/types.js';
+/**
+ * Audio frame buffering utility for encoders with fixed frame size requirements.
+ *
+ * Many audio encoders (Opus, AAC, MP3, etc.) require frames with a specific number
+ * of samples (frame_size). This class buffers incoming frames and outputs frames
+ * with exactly the required size.
+ *
+ * Uses FFmpeg's AVAudioFifo internally for efficient sample buffering.
+ *
+ * @example
+ * ```typescript
+ * import { AudioFrameBuffer } from 'node-av/api';
+ *
+ * // Create buffer for 480-sample frames (e.g., Opus at 24kHz)
+ * using buffer = AudioFrameBuffer.create(480, AV_SAMPLE_FMT_FLT, 48000, 'mono', 1);
+ *
+ * // Push variable-sized frames from filter
+ * for await (const frame of filterOutput) {
+ *   await buffer.push(frame);
+ *
+ *   // Pull fixed-size frames for encoder
+ *   let outputFrame;
+ *   while ((outputFrame = await buffer.pull()) !== null) {
+ *     await encoder.encode(outputFrame);
+ *     outputFrame.free();
+ *   }
+ * }
+ *
+ * // Flush remaining samples
+ * let outputFrame;
+ * while ((outputFrame = await buffer.pull()) !== null) {
+ *   await encoder.encode(outputFrame);
+ *   outputFrame.free();
+ * }
+ * ```
+ */
+export declare class AudioFrameBuffer implements Disposable {
+    private fifo;
+    private frame;
+    private frameSize;
+    private nextPts;
+    private firstFramePts;
+    /**
+     * @param fifo - Underlying AudioFifo instance
+     *
+     * @param frameSize - Number of samples per output frame
+     *
+     * @param sampleFormat - Audio sample format
+     *
+     * @param sampleRate - Sample rate in Hz
+     *
+     * @param channelLayout - Channel layout
+     *
+     * @internal
+     */
+    private constructor();
+    /**
+     * Create an audio frame buffer.
+     *
+     * @param frameSize - Required frame size in samples
+     *
+     * @param sampleFormat - Audio sample format
+     *
+     * @param sampleRate - Sample rate in Hz
+     *
+     * @param channelLayout - Channel layout (e.g., 'mono', 'stereo')
+     *
+     * @param channels - Number of audio channels
+     *
+     * @returns Configured audio frame buffer
+     *
+     * @example
+     * ```typescript
+     * // For Opus encoder at 48kHz with 20ms frames
+     * const buffer = AudioFrameBuffer.create(960, AV_SAMPLE_FMT_FLT, 48000, 'mono', 1);
+     * ```
+     */
+    static create(frameSize: number, sampleFormat: AVSampleFormat, sampleRate: number, channelLayout: ChannelLayout, channels: number): AudioFrameBuffer;
+    /**
+     * Get number of samples currently in buffer.
+     *
+     * @returns Number of buffered samples
+     *
+     * @example
+     * ```typescript
+     * console.log(`Buffer contains ${buffer.size} samples`);
+     * ```
+     */
+    get size(): number;
+    /**
+     * Check if a complete frame is available.
+     *
+     * Returns true if the FIFO contains at least frameSize samples.
+     *
+     * @returns True if a full frame can be pulled
+     *
+     * @example
+     * ```typescript
+     * while (buffer.hasFrame()) {
+     *   const frame = buffer.pull();
+     *   // Process frame...
+     * }
+     * ```
+     */
+    hasFrame(): boolean;
+    /**
+     * Push an audio frame into the buffer asynchronously.
+     *
+     * The frame's samples are added to the internal FIFO.
+     * Call hasFrame() and pull() to retrieve fixed-size output frames.
+     *
+     * @param frame - Audio frame to buffer
+     *
+     * @example
+     * ```typescript
+     * await buffer.push(filterFrame);
+     * ```
+     *
+     * @see {@link pushSync} For synchronous version
+     */
+    push(frame: Frame): Promise<void>;
+    /**
+     * Push an audio frame into the buffer synchronously.
+     * Synchronous version of push.
+     *
+     * The frame's samples are added to the internal FIFO.
+     * Call hasFrame() and pullSync() to retrieve fixed-size output frames.
+     *
+     * @param frame - Audio frame to buffer
+     *
+     * @example
+     * ```typescript
+     * buffer.pushSync(filterFrame);
+     * ```
+     *
+     * @see {@link push} For async version
+     */
+    pushSync(frame: Frame): void;
+    /**
+     * Pull a fixed-size audio frame from the buffer asynchronously.
+     *
+     * Reads exactly frameSize samples from the FIFO and returns a cloned Frame.
+     * Returns null if not enough samples are available.
+     * Reuses internal frame buffer for efficiency (like Decoder does).
+     *
+     * @returns Audio frame with exactly frameSize samples, or null if insufficient samples
+     *
+     * @example
+     * ```typescript
+     * using frame = await buffer.pull();
+     * if (frame) {
+     *   await encoder.encode(frame);
+     * }
+     * ```
+     *
+     * @see {@link pullSync} For synchronous version
+     */
+    pull(): Promise<Frame | null>;
+    /**
+     * Pull a fixed-size audio frame from the buffer synchronously.
+     * Synchronous version of pull.
+     *
+     * Reads exactly frameSize samples from the FIFO and returns a cloned Frame.
+     * Returns null if not enough samples are available.
+     * Reuses internal frame buffer for efficiency (like Decoder does).
+     *
+     * @returns Audio frame with exactly frameSize samples, or null if insufficient samples
+     *
+     * @example
+     * ```typescript
+     * using frame = buffer.pullSync();
+     * if (frame) {
+     *   encoder.encodeSync(frame);
+     * }
+     * ```
+     *
+     * @see {@link pull} For async version
+     */
+    pullSync(): Frame | null;
+    /**
+     * Reset the buffer, discarding all buffered samples.
+     *
+     * @example
+     * ```typescript
+     * buffer.reset();
+     * ```
+     */
+    reset(): void;
+    /**
+     * Free the buffer and all resources.
+     *
+     * @example
+     * ```typescript
+     * buffer.free();
+     * ```
+     */
+    [Symbol.dispose](): void;
+}