node-av-light 0.0.0 → 7.1.0-beta.1

package/dist/lib/frame.d.ts

@@ -0,0 +1,1315 @@
+import { HardwareFramesContext } from './hardware-frames-context.js';
+import { Rational } from './rational.js';
+import type { AVAlphaMode, AVChromaLocation, AVColorPrimaries, AVColorRange, AVColorSpace, AVColorTransferCharacteristic, AVFrameSideDataType, AVMediaType, AVPictureType, AVPixelFormat, AVSampleFormat } from '../constants/constants.js';
+import { Dictionary } from './dictionary.js';
+import type { HardwareDeviceContext } from './hardware-device-context.js';
+import type { NativeFrame, NativeWrapper } from './native-types.js';
+import type { ChannelLayout, IRational } from './types.js';
+/**
+ * Video Frame
+ */
+export interface VideoFrame {
+    width: number;
+    height: number;
+    format: AVPixelFormat;
+    timeBase?: IRational;
+    sampleAspectRatio?: IRational;
+    pts?: bigint;
+    alphaMode?: AVAlphaMode;
+}
+/**
+ * Audio Frame
+ */
+export interface AudioFrame {
+    nbSamples: number;
+    format: AVSampleFormat;
+    sampleRate: number;
+    channelLayout: ChannelLayout;
+    timeBase?: IRational;
+    pts?: bigint;
+}
+/**
+ * Options for {@link Frame.fromIOSurface} (macOS only).
+ *
+ * Creates a zero-copy hardware frame from an IOSurface handle.
+ * Width and height are auto-detected from the IOSurface.
+ */
+export interface IOSurfaceFrame {
+    hwFramesCtx: HardwareFramesContext;
+    timeBase?: IRational;
+    pts?: bigint;
+}
+/**
+ * Options for {@link Frame.fromD3D11Texture} (Windows only).
+ *
+ * Creates a zero-copy hardware frame from a D3D11 shared texture handle.
+ * Width and height are auto-detected from the texture descriptor.
+ */
+export interface D3D11TextureFrame {
+    hwDeviceCtx: HardwareDeviceContext;
+    timeBase?: IRational;
+    pts?: bigint;
+}
+/**
+ * Options for {@link Frame.fromNSImage} (macOS only).
+ *
+ * Creates a zero-copy software frame from an NSImage native handle.
+ * Width, height, and pixel format are auto-detected from NSBitmapImageRep.
+ */
+export interface NSImageFrame {
+    timeBase?: IRational;
+    pts?: bigint;
+}
+/**
+ * DMA-BUF plane descriptors for Linux GPU buffer sharing.
+ */
+export interface DmaBufPlanes {
+    planes: {
+        fd: number;
+        stride: number;
+        offset: number;
+        size: number;
+    }[];
+    modifier: string;
+}
+/**
+ * Options for {@link Frame.fromDmaBuf} (Linux only).
+ *
+ * Creates a zero-copy DRM PRIME frame from DMA-BUF file descriptors.
+ */
+export interface DmaBufFrame {
+    width: number;
+    height: number;
+    swFormat?: AVPixelFormat;
+    timeBase?: IRational;
+    pts?: bigint;
+}
+/**
+ * Container for uncompressed audio/video data.
+ *
+ * Stores decoded audio samples or video pixels. Each frame contains raw data
+ * for a single video frame or a set of audio samples. Includes format information,
+ * timing data, and metadata. Supports both software and hardware (GPU) frames.
+ * Essential for decoding, encoding, and filter operations.
+ *
+ * Direct mapping to FFmpeg's AVFrame.
+ *
+ * @example
+ * ```typescript
+ * import { Frame, FFmpegError } from 'node-av';
+ * import { AV_PIX_FMT_YUV420P } from 'node-av/constants';
+ *
+ * // Create and allocate frame
+ * const frame = new Frame();
+ * frame.alloc();
+ *
+ * // Configure video frame
+ * frame.format = AV_PIX_FMT_YUV420P;
+ * frame.width = 1920;
+ * frame.height = 1080;
+ * const ret = frame.allocBuffer();
+ * FFmpegError.throwIfError(ret, 'allocBuffer');
+ *
+ * // Receive decoded frame
+ * const ret2 = await codecContext.receiveFrame(frame);
+ * if (ret2 >= 0) {
+ *   console.log(`Frame PTS: ${frame.pts}`);
+ *   console.log(`Frame type: ${frame.pictType}`);
+ *   console.log(`Keyframe: ${frame.keyFrame}`);
+ * }
+ *
+ * // Cleanup
+ * frame.unref();
+ * ```
+ *
+ * @see [AVFrame](https://ffmpeg.org/doxygen/trunk/structAVFrame.html) - FFmpeg Doxygen
+ * @see {@link CodecContext} For encoding/decoding frames
+ * @see {@link FilterContext} For filtering frames
+ */
+export declare class Frame implements Disposable, NativeWrapper<NativeFrame> {
+    private native;
+    constructor();
+    /**
+     * Create a video frame from a buffer with pixel data.
+     *
+     * Allocates frame buffers, sets properties, and copies buffer data.
+     * Convenience factory method that combines frame allocation and data copy.
+     *
+     * @param buffer - Buffer containing raw pixel data
+     *
+     * @param props - Video Frame properties
+     *
+     * @returns Allocated frame with data from buffer
+     *
+     * @throws {FFmpegError} If allocation or buffer copy fails
+     *
+     * @example
+     * ```typescript
+     * import { Frame, AV_PIX_FMT_RGBA, FFmpegError } from 'node-av';
+     *
+     * const rawPixels = Buffer.alloc(1920 * 1080 * 4); // RGBA data
+     * using frame = Frame.fromVideoBuffer(rawPixels, {
+     *   width: 1920,
+     *   height: 1080,
+     *   format: AV_PIX_FMT_RGBA,
+     *   timeBase: { num: 1, den: 30 }
+     * });
+     * ```
+     */
+    static fromVideoBuffer(buffer: Buffer, props: VideoFrame): Frame;
+    /**
+     * Create an audio frame from a buffer with sample data.
+     *
+     * Allocates frame buffers, sets properties, and copies buffer data.
+     * Convenience factory method that combines frame allocation and data copy.
+     *
+     * @param buffer - Buffer containing raw audio samples
+     *
+     * @param props - Frame properties
+     *
+     * @returns Allocated frame with data from buffer
+     *
+     * @throws {FFmpegError} If allocation or buffer copy fails
+     *
+     * @example
+     * ```typescript
+     * import { Frame, AV_SAMPLE_FMT_FLT, AV_CH_LAYOUT_STEREO, FFmpegError } from 'node-av';
+     *
+     * const samples = Buffer.alloc(960 * 2 * 4); // 960 samples, stereo, float32
+     * using frame = Frame.fromAudioBuffer(samples, {
+     *   nbSamples: 960,
+     *   format: AV_SAMPLE_FMT_FLT,
+     *   sampleRate: 48000,
+     *   channelLayout: AV_CH_LAYOUT_STEREO,
+     *   timeBase: { num: 1, den: 48000 }
+     * });
+     * ```
+     */
+    static fromAudioBuffer(buffer: Buffer, props: AudioFrame): Frame;
+    /**
+     * Create a hardware frame from an IOSurface handle (macOS only).
+     *
+     * Zero-copy: the frame references the same GPU memory as the IOSurface.
+     * Width and height are auto-detected from the IOSurface.
+     *
+     * @param ioSurface - IOSurfaceRef pointer as Buffer
+     *
+     * @param props - Hardware context and timing options
+     *
+     * @returns Hardware frame referencing the IOSurface GPU memory
+     *
+     * @throws {FFmpegError} If the import fails (e.g., invalid handle, wrong platform)
+     *
+     * @example
+     * ```typescript
+     * import { Frame, HardwareFramesContext } from 'node-av/lib';
+     *
+     * const frame = Frame.fromIOSurface(ioSurfaceBuffer, {
+     *   hwFramesCtx,
+     *   pts: 0n,
+     *   timeBase: { num: 1, den: 90000 },
+     * });
+     * ```
+     */
+    static fromIOSurface(ioSurface: Buffer, props: IOSurfaceFrame): Frame;
+    /**
+     * Create a software frame from an NSImage native handle (macOS only).
+     *
+     * Zero-copy: the frame references the NSBitmapImageRep pixel data directly.
+     * Width, height, and pixel format are auto-detected.
+     *
+     * @param nsImageHandle - NSImage pointer as Buffer
+     *
+     * @param props - Timing options
+     *
+     * @returns Software frame referencing the NSImage pixel data
+     *
+     * @throws {FFmpegError} If the import fails (e.g., no NSBitmapImageRep, wrong platform)
+     *
+     * @example
+     * ```typescript
+     * import { Frame } from 'node-av/lib';
+     *
+     * // Electron: nativeImage.getNativeHandle() returns 8-byte NSImage* pointer
+     * const frame = Frame.fromNSImage(nativeImage.getNativeHandle(), {
+     *   pts: 0n,
+     *   timeBase: { num: 1, den: 30 },
+     * });
+     * ```
+     */
+    static fromNSImage(nsImageHandle: Buffer, props?: NSImageFrame): Frame;
+    /**
+     * Create a hardware frame from a D3D11 shared texture (Windows only).
+     *
+     * Zero-copy: the frame references the shared GPU texture.
+     * Width and height are auto-detected from the texture descriptor.
+     *
+     * @param handle - D3D11 shared texture handle as Buffer
+     *
+     * @param props - Hardware context and timing options
+     *
+     * @returns Hardware frame referencing the D3D11 texture
+     *
+     * @throws {FFmpegError} If the import fails (e.g., invalid handle, wrong platform)
+     *
+     * @example
+     * ```typescript
+     * import { Frame, HardwareDeviceContext } from 'node-av/lib';
+     *
+     * const frame = Frame.fromD3D11Texture(sharedTextureHandle, {
+     *   hwDeviceCtx,
+     *   pts: 0n,
+     *   timeBase: { num: 1, den: 90000 },
+     * });
+     * ```
+     */
+    static fromD3D11Texture(handle: Buffer, props: D3D11TextureFrame): Frame;
+    /**
+     * Create a DRM PRIME frame from DMA-BUF file descriptors (Linux only).
+     *
+     * Zero-copy: the frame references the DMA-BUF GPU memory.
+     *
+     * @param dmaBuf - DMA-BUF plane descriptors
+     *
+     * @param props - Dimensions and timing options
+     *
+     * @returns Hardware frame referencing the DMA-BUF memory
+     *
+     * @throws {FFmpegError} If the import fails (e.g., invalid descriptors, wrong platform)
+     *
+     * @example
+     * ```typescript
+     * import { Frame } from 'node-av/lib';
+     *
+     * // Create DRM PRIME frame from DMA-BUF
+     * const drmFrame = Frame.fromDmaBuf(dmaBufPlanes, {
+     *   width: 1920,
+     *   height: 1080,
+     *   pts: 0n,
+     *   timeBase: { num: 1, den: 90000 },
+     * });
+     * ```
+     */
+    static fromDmaBuf(dmaBuf: DmaBufPlanes, props: DmaBufFrame): Frame;
+    /**
+     * Pixel format for video frames or sample format for audio.
+     *
+     * Direct mapping to AVFrame->format.
+     */
+    get format(): AVPixelFormat | AVSampleFormat;
+    set format(value: AVPixelFormat | AVSampleFormat);
+    /**
+     * Width of video frame in pixels.
+     *
+     * Direct mapping to AVFrame->width.
+     */
+    get width(): number;
+    set width(value: number);
+    /**
+     * Height of video frame in pixels.
+     *
+     * Direct mapping to AVFrame->height.
+     */
+    get height(): number;
+    set height(value: number);
+    /**
+     * Number of audio samples per channel.
+     *
+     * Direct mapping to AVFrame->nb_samples.
+     */
+    get nbSamples(): number;
+    set nbSamples(value: number);
+    /**
+     * Presentation timestamp.
+     *
+     * Time when the frame should be presented.
+     * In time base units. AV_NOPTS_VALUE if unknown.
+     *
+     * Direct mapping to AVFrame->pts.
+     */
+    get pts(): bigint;
+    set pts(value: bigint);
+    /**
+     * DTS from the packet that produced this frame.
+     *
+     * Copy of packet DTS for reference.
+     * In time base units. AV_NOPTS_VALUE if unknown.
+     *
+     * Direct mapping to AVFrame->pkt_dts.
+     */
+    get pktDts(): bigint;
+    set pktDts(value: bigint);
+    /**
+     * Best effort timestamp.
+     *
+     * Frame timestamp estimated using various heuristics.
+     * In time base units.
+     *
+     * Direct mapping to AVFrame->best_effort_timestamp.
+     */
+    get bestEffortTimestamp(): bigint;
+    set bestEffortTimestamp(value: bigint);
+    /**
+     * Time base for timestamps.
+     *
+     * Defines the unit of the timestamps (seconds per tick).
+     *
+     * Direct mapping to AVFrame->time_base.
+     */
+    get timeBase(): Rational;
+    set timeBase(value: IRational);
+    /**
+     * Whether this frame is a keyframe.
+     *
+     * 1 if keyframe, 0 otherwise.
+     *
+     * Direct mapping to AVFrame->key_frame.
+     */
+    get keyFrame(): number;
+    set keyFrame(value: number);
+    /**
+     * Picture type of the frame.
+     *
+     * Type of frame (I, P, B, etc.).
+     *
+     * Direct mapping to AVFrame->pict_type.
+     */
+    get pictType(): AVPictureType;
+    set pictType(value: AVPictureType);
+    /**
+     * Quality (between 1 (good) and FF_LAMBDA_MAX (bad)).
+     *
+     * Set by libavcodec for some coded frames.
+     * Can be set before encoding to specify desired quality for encoders that support it.
+     * Used by FFmpeg CLI's frame_encode() to propagate encoder's global_quality setting.
+     *
+     * Direct mapping to AVFrame->quality.
+     */
+    get quality(): number;
+    set quality(value: number);
+    /**
+     * Sample aspect ratio.
+     *
+     * Pixel width/height ratio. 0/1 if unknown.
+     *
+     * Direct mapping to AVFrame->sample_aspect_ratio.
+     */
+    get sampleAspectRatio(): Rational;
+    set sampleAspectRatio(value: Rational);
+    /**
+     * Audio sample rate.
+     *
+     * Number of samples per second.
+     *
+     * Direct mapping to AVFrame->sample_rate.
+     */
+    get sampleRate(): number;
+    set sampleRate(value: number);
+    /**
+     * Audio channel layout.
+     *
+     * Describes the channel configuration.
+     *
+     * Direct mapping to AVFrame->ch_layout.
+     */
+    get channelLayout(): ChannelLayout;
+    set channelLayout(value: ChannelLayout);
+    /**
+     * Number of audio channels.
+     *
+     * Derived from channel layout.
+     */
+    get channels(): number;
+    /**
+     * Line sizes for each plane.
+     *
+     * Number of bytes per line for each data plane.
+     *
+     * Direct mapping to AVFrame->linesize.
+     */
+    get linesize(): number[];
+    /**
+     * Color range.
+     *
+     * MPEG (limited) or JPEG (full) range.
+     *
+     * Direct mapping to AVFrame->color_range.
+     */
+    get colorRange(): AVColorRange;
+    set colorRange(value: AVColorRange);
+    /**
+     * Color primaries.
+     *
+     * Chromaticity coordinates of the source primaries.
+     *
+     * Direct mapping to AVFrame->color_primaries.
+     */
+    get colorPrimaries(): AVColorPrimaries;
+    set colorPrimaries(value: AVColorPrimaries);
+    /**
+     * Color transfer characteristic.
+     *
+     * Transfer function (gamma).
+     *
+     * Direct mapping to AVFrame->color_trc.
+     */
+    get colorTrc(): AVColorTransferCharacteristic;
+    set colorTrc(value: AVColorTransferCharacteristic);
+    /**
+     * YUV color space.
+     *
+     * Color space type for YUV content.
+     *
+     * Direct mapping to AVFrame->colorspace.
+     */
+    get colorSpace(): AVColorSpace;
+    set colorSpace(value: AVColorSpace);
+    /**
+     * Chroma sample location.
+     *
+     * Position of chroma samples.
+     *
+     * Direct mapping to AVFrame->chroma_location.
+     */
+    get chromaLocation(): AVChromaLocation;
+    set chromaLocation(value: AVChromaLocation);
+    /**
+     * Alpha channel mode.
+     *
+     * Specifies how the alpha channel relates to color values.
+     *
+     * Direct mapping to AVFrame->alpha_mode.
+     */
+    get alphaMode(): AVAlphaMode;
+    set alphaMode(value: AVAlphaMode);
+    /**
+     * Raw frame data planes.
+     *
+     * Array of buffers containing the frame data.
+     * One buffer per plane (e.g., Y, U, V for YUV420P).
+     *
+     * Direct mapping to AVFrame->data.
+     */
+    get data(): Buffer[] | null;
+    /**
+     * Extended data planes.
+     *
+     * For audio with >8 channels or planar audio.
+     * Points to data planes beyond the first 8.
+     *
+     * Direct mapping to AVFrame->extended_data.
+     */
+    get extendedData(): Buffer[] | null;
+    /**
+     * Check if frame data is writable.
+     *
+     * True if the frame data can be modified.
+     */
+    get isWritable(): boolean;
+    /**
+     * Bytes of native buffer memory this frame currently reports to V8's GC via
+     * `napi_adjust_external_memory`. Exposed only so the accounting can be
+     * asserted in tests; the value is not observable through V8 heap statistics.
+     *
+     * @internal
+     */
+    get reportedExternalMemory(): number;
+    /**
+     * Hardware frames context.
+     *
+     * Reference to hardware frames context for GPU frames.
+     * Null for software frames.
+     *
+     * Direct mapping to AVFrame->hw_frames_ctx.
+     */
+    get hwFramesCtx(): HardwareFramesContext | null;
+    set hwFramesCtx(value: HardwareFramesContext | null);
+    /**
+     * Frame flags.
+     *
+     * Combination of AVFrameFlags (e.g., AV_FRAME_FLAG_CORRUPT, AV_FRAME_FLAG_KEY).
+     *
+     * Direct mapping to AVFrame->flags.
+     */
+    get flags(): number;
+    set flags(value: number);
+    /**
+     * Decode error flags.
+     *
+     * Indicates errors detected during decoding.
+     * Non-zero value means the frame may be corrupted.
+     *
+     * Direct mapping to AVFrame->decode_error_flags.
+     */
+    get decodeErrorFlags(): number;
+    set decodeErrorFlags(value: number);
+    /**
+     * Frame duration.
+     *
+     * Duration of this frame in units of time_base.
+     * This is FFmpeg's best guess for how long the frame should be displayed.
+     * May be 0 if unknown or unavailable.
+     *
+     * Direct mapping to AVFrame->duration.
+     */
+    get duration(): bigint;
+    set duration(value: bigint);
+    /**
+     * Number of fields in this frame that should be repeated.
+     *
+     * For interlaced video, indicates how many times the frame should be repeated
+     * when displayed. For progressive video, this is typically 0.
+     * Formula: display_time = (repeat_pict / (2*fps))
+     *
+     * Direct mapping to AVFrame->repeat_pict.
+     */
+    get repeatPict(): number;
+    set repeatPict(value: number);
+    /**
+     * Set frame flags.
+     *
+     * Sets one or more flags using bitwise OR. Allows setting multiple flags
+     * without manually performing bitwise operations.
+     *
+     * @param flags - One or more flag values to set
+     *
+     * @example
+     * ```typescript
+     * import { AV_FRAME_FLAG_KEY } from 'node-av/constants';
+     *
+     * // Mark frame as key frame
+     * frame.setFlags(AV_FRAME_FLAG_KEY);
+     * ```
+     *
+     * @see {@link clearFlags} To unset flags
+     * @see {@link hasFlags} To check flags
+     * @see {@link flags} For direct flag access
+     */
+    setFlags(...flags: number[]): void;
+    /**
+     * Clear frame flags.
+     *
+     * Clears one or more flags using bitwise AND NOT. Allows clearing multiple
+     * flags without manually performing bitwise operations.
+     *
+     * @param flags - One or more flag values to clear
+     *
+     * @example
+     * ```typescript
+     * import { AV_FRAME_FLAG_CORRUPT } from 'node-av/constants';
+     *
+     * // Clear corrupt flag
+     * frame.clearFlags(AV_FRAME_FLAG_CORRUPT);
+     * ```
+     *
+     * @see {@link setFlags} To set flags
+     * @see {@link hasFlags} To check flags
+     * @see {@link flags} For direct flag access
+     */
+    clearFlags(...flags: number[]): void;
+    /**
+     * Check if frame has specific flags.
+     *
+     * Tests whether all specified flags are set using bitwise AND.
+     *
+     * @param flags - One or more flag values to check
+     *
+     * @returns true if all specified flags are set, false otherwise
+     *
+     * @example
+     * ```typescript
+     * import { AV_FRAME_FLAG_CORRUPT } from 'node-av/constants';
+     *
+     * if (frame.hasFlags(AV_FRAME_FLAG_CORRUPT)) {
+     *   console.log('Frame is corrupted');
+     * }
+     * ```
+     *
+     * @see {@link setFlags} To set flags
+     * @see {@link clearFlags} To unset flags
+     * @see {@link flags} For direct flag access
+     */
+    hasFlags(...flags: number[]): boolean;
+    /**
+     * Check if frame has decode errors.
+     *
+     * Tests whether all specified decode error flags are set using bitwise AND.
+     *
+     * @param flags - One or more decode error flag values to check
+     *
+     * @returns true if all specified error flags are set, false otherwise
+     *
+     * @example
+     * ```typescript
+     * import { FF_DECODE_ERROR_INVALID_BITSTREAM } from 'node-av/constants';
+     *
+     * if (frame.hasDecodeErrorFlags(FF_DECODE_ERROR_INVALID_BITSTREAM)) {
+     *   console.log('Frame has invalid bitstream error');
+     * }
+     * ```
+     *
+     * @see {@link decodeErrorFlags} For direct error flag access
+     */
+    hasDecodeErrorFlags(...flags: number[]): boolean;
+    /**
+     * Check if this is a video frame.
+     *
+     * Video frames have width and height > 0.
+     *
+     * @returns true if this is a video frame
+     *
+     * @example
+     * ```typescript
+     * if (frame.isVideo()) {
+     *   console.log(`Video frame: ${frame.width}x${frame.height}`);
+     * }
+     * ```
+     */
+    isVideo(): boolean;
+    /**
+     * Check if this is an audio frame.
+     *
+     * Audio frames have sampleRate > 0 and nbSamples > 0.
+     *
+     * @returns true if this is an audio frame
+     *
+     * @example
+     * ```typescript
+     * if (frame.isAudio()) {
+     *   console.log(`Audio frame: ${frame.sampleRate}Hz, ${frame.nbSamples} samples`);
+     * }
+     * ```
+     */
+    isAudio(): boolean;
+    /**
+     * Get the media type of this frame.
+     *
+     * @returns AVMEDIA_TYPE_VIDEO for video frames, AVMEDIA_TYPE_AUDIO for audio frames, or AVMEDIA_TYPE_UNKNOWN
+     *
+     * @example
+     * ```typescript
+     * const type = frame.getMediaType();
+     * console.log(`Frame type: ${type}`);
+     * ```
+     */
+    getMediaType(): AVMediaType;
+    /**
+     * Allocate a new frame.
+     *
+     * Allocates the frame structure. Must be called before using the frame
+     * unless it was created by another function (e.g., clone()).
+     *
+     * Direct mapping to av_frame_alloc().
+     *
+     * @throws {Error} If allocation fails (ENOMEM)
+     *
+     * @example
+     * ```typescript
+     * const frame = new Frame();
+     * frame.alloc();
+     * // Frame structure is now ready
+     * ```
+     *
+     * @see {@link allocBuffer} To allocate data buffers
+     * @see {@link free} To deallocate the frame
+     */
+    alloc(): void;
+    /**
+     * Free the frame.
+     *
+     * Deallocates the frame and its data. The frame becomes invalid after this.
+     *
+     * Direct mapping to av_frame_free().
+     *
+     * @example
+     * ```typescript
+     * frame.free();
+     * // Frame is now invalid
+     * ```
+     *
+     * @see {@link unref} To only free data, keeping structure
+     */
+    free(): void;
+    /**
+     * Create a reference to another frame.
+     *
+     * Sets up this frame as a reference to the source frame's data.
+     * Both frames will share the same data buffers.
+     *
+     * Direct mapping to av_frame_ref().
+     *
+     * IMPORTANT: per FFmpeg's contract, this frame (the destination) MUST be
+     * unreferenced or freshly allocated before calling. Re-using a frame as the
+     * destination without {@link unref} first leaks its previous buffers (the old
+     * references are overwritten, not freed). When reusing one frame across a loop,
+     * call `frame.unref()` before each `frame.ref(src)`.
+     *
+     * @param src - Source frame to reference
+     *
+     * @returns 0 on success, negative AVERROR on error:
+     *   - AVERROR_ENOMEM: Memory allocation failure
+     *   - AVERROR_EINVAL: Invalid parameters
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError } from 'node-av';
+     *
+     * // Reusing one frame across a loop: unref before re-referencing.
+     * frame2.unref();
+     * const ret = frame2.ref(frame1);
+     * FFmpegError.throwIfError(ret, 'ref');
+     * // frame2 now references frame1's data
+     * ```
+     *
+     * @see {@link unref} To remove reference (call before re-referencing a reused frame)
+     * @see {@link clone} To create independent copy
+     */
+    ref(src: Frame): number;
+    /**
+     * Unreference the frame.
+     *
+     * Frees the frame data if this was the last reference.
+     * The frame structure remains allocated and can be reused.
+     *
+     * Direct mapping to av_frame_unref().
+     *
+     * @example
+     * ```typescript
+     * frame.unref();
+     * // Frame data is freed, structure can be reused
+     * ```
+     *
+     * @see {@link ref} To create reference
+     * @see {@link free} To free everything
+     */
+    unref(): void;
+    /**
+     * Clone the frame.
+     *
+     * Creates an independent copy of the frame with its own data buffers.
+     * The new frame has the same content but can be modified independently.
+     *
+     * Direct mapping to av_frame_clone().
+     *
+     * @returns New frame instance, or null on allocation failure
+     *
+     * @example
+     * ```typescript
+     * const copy = frame.clone();
+     * if (copy) {
+     *   // Modify copy without affecting original
+     *   copy.pts = frame.pts + 1000n;
+     * }
+     * ```
+     *
+     * @see {@link ref} To create reference instead of copy
+     * @see {@link copy} To copy into existing frame
+     */
+    clone(): Frame | null;
+    /**
+     * Allocate data buffers for the frame.
+     *
+     * Allocates buffers based on frame parameters.
+     * Must set format, width/height (video) or format, nb_samples, channel_layout (audio) first.
+     *
+     * Direct mapping to av_frame_get_buffer().
+     *
+     * @param align - Buffer size alignment (0 for default)
+     *
+     * @returns 0 on success, negative AVERROR on error:
+     *   - AVERROR_EINVAL: Invalid frame parameters
+     *   - AVERROR_ENOMEM: Memory allocation failure
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError } from 'node-av';
+     *
+     * const ret = frame.getBuffer();
+     * FFmpegError.throwIfError(ret, 'getBuffer');
+     * ```
+     *
+     * @see {@link allocBuffer} Equivalent without alignment parameter
+     */
+    getBuffer(align?: number): number;
+    /**
+     * Allocate data buffers for the frame.
+     *
+     * Allocates buffers based on frame format and dimensions.
+     * Frame parameters must be set before calling.
+     *
+     * Direct mapping to av_frame_get_buffer().
+     *
+     * @returns 0 on success, negative AVERROR on error:
+     *   - AVERROR_EINVAL: Invalid frame parameters
+     *   - AVERROR_ENOMEM: Memory allocation failure
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError } from 'node-av';
+     * import { AV_PIX_FMT_YUV420P } from 'node-av/constants';
+     *
+     * frame.format = AV_PIX_FMT_YUV420P;
+     * frame.width = 1920;
+     * frame.height = 1080;
+     * const ret = frame.allocBuffer();
+     * FFmpegError.throwIfError(ret, 'allocBuffer');
+     * ```
+     *
+     * @see {@link getBuffer} Equivalent with an alignment parameter
+     */
+    allocBuffer(): number;
+    /**
+     * Ensure frame data is writable.
+     *
+     * Creates a private copy of the data if it's shared with other frames.
+     * Call before modifying frame data to avoid affecting other references.
+     *
+     * Direct mapping to av_frame_make_writable().
+     *
+     * @returns 0 on success, negative AVERROR on error:
+     *   - AVERROR_ENOMEM: Memory allocation failure
+     *   - AVERROR_EINVAL: Invalid frame
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError } from 'node-av';
+     *
+     * // Ensure we can safely modify data
+     * const ret = frame.makeWritable();
+     * FFmpegError.throwIfError(ret, 'makeWritable');
+     * // Now safe to modify frame.data
+     * ```
+     */
+    makeWritable(): number;
+    /**
+     * Copy non-layout frame properties without copying data.
+     *
+     * Copies metadata like timestamp, duration, etc., but not the actual data.
+     * Layout-defining properties, such as width, height, channel count, format, etc., are not copied.
+     * Useful for preparing output frames with same properties.
+     *
+     * Direct mapping to av_frame_copy_props().
+     *
+     * @param src - Source frame to copy properties from
+     *
+     * @returns 0 on success, negative AVERROR on error:
+     *   - AVERROR_ENOMEM: Memory allocation failure
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError } from 'node-av';
+     *
+     * const ret = dstFrame.copyProps(srcFrame);
+     * FFmpegError.throwIfError(ret, 'copyProps');
+     * // dstFrame now has same non-layout properties as srcFrame
+     * ```
+     *
+     * @see {@link copy} To copy data
+     */
+    copyProps(src: Frame): number;
+    /**
+     * Copy frame data.
+     *
+     * Copies only data (but not metadata) from source frame.
+     * Destination must have allocated buffers of correct size.
+     *
+     * Direct mapping to av_frame_copy().
+     *
+     * @param src - Source frame to copy from
+     *
+     * @returns 0 on success, negative AVERROR on error:
+     *   - AVERROR_EINVAL: Incompatible frames
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError } from 'node-av';
+     *
+     * // Allocate destination with same format
+     * dstFrame.format = srcFrame.format;
+     * dstFrame.width = srcFrame.width;
+     * dstFrame.height = srcFrame.height;
+     * dstFrame.allocBuffer();
+     *
+     * const ret = dstFrame.copy(srcFrame);
+     * FFmpegError.throwIfError(ret, 'copy');
+     * ```
+     *
+     * @see {@link copyProps} To copy non-format metadata
+     * @see {@link clone} To create new frame with copy
+     */
+    copy(src: Frame): number;
+    /**
+     * Fill frame data from buffer.
+     *
+     * Copies data from buffer into frame-owned data planes; the frame never
+     * references the source buffer, so it may be reused or garbage collected
+     * afterwards. Allocates the frame's buffers if not already allocated.
+     *
+     * @param buffer - Source buffer with frame data
+     *
+     * @returns 0 on success, negative AVERROR on error:
+     *   - AVERROR_EINVAL: Invalid parameters
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError } from 'node-av';
+     *
+     * const buffer = Buffer.from(rawVideoData);
+     * const ret = frame.fromBuffer(buffer);
+     * FFmpegError.throwIfError(ret, 'fromBuffer');
+     * ```
+     */
+    fromBuffer(buffer: Buffer): number;
+    /**
+     * Convert frame data to buffer.
+     *
+     * Copies frame data into a single contiguous buffer.
+     * For video frames, converts all planes into packed format.
+     * For audio frames, handles both planar and interleaved formats.
+     * Cannot be used with hardware frames - use hwframeTransferData first.
+     *
+     * @param output - Optional Buffer to copy into instead of allocating one; it must hold at least the frame's size and must not overlap the frame's data
+     *
+     * @returns Buffer containing frame data (a view of `output` when given)
+     *
+     * @throws {Error} If frame is not allocated, has no data, or is a hardware frame
+     *
+     * @throws {TypeError} If `output` is not a Buffer or is smaller than the frame data
+     *
+     * @example Video frame to buffer
+     * ```typescript
+     * // Get YUV420P video frame as buffer
+     * const buffer = frame.toBuffer();
+     * console.log(`Frame buffer size: ${buffer.length} bytes`);
+     * // Buffer contains Y plane, then U plane, then V plane
+     * ```
+     *
+     * @example Audio frame to buffer
+     * ```typescript
+     * // Get audio samples as buffer
+     * const audioBuffer = frame.toBuffer();
+     * console.log(`Audio buffer size: ${audioBuffer.length} bytes`);
+     * // For planar audio: channel 0 samples, then channel 1 samples, etc.
+     * // For interleaved audio: sample0_ch0, sample0_ch1, sample1_ch0, sample1_ch1, etc.
+     * ```
+     *
+     * @example Error handling
+     * ```typescript
+     * try {
+     *   const buffer = frame.toBuffer();
+     *   // Process buffer...
+     * } catch (error) {
+     *   if (frame.isHwFrame()) {
+     *     // Transfer to software first
+     *     const swFrame = new Frame();
+     *     swFrame.alloc();
+     *     await frame.hwframeTransferData(swFrame);
+     *     const buffer = swFrame.toBuffer();
+     *   }
+     * }
+     * ```
+     *
+     * @see {@link fromBuffer} To create frame from buffer
+     * @see {@link hwframeTransferData} To transfer hardware frames to software
+     * @see {@link isHwFrame} To check if frame is hardware
+     * @see {@link data} To access individual planes
+     */
+    toBuffer(output?: Buffer): Buffer;
+    /**
+     * Transfer data between hardware and software frames.
+     *
+     * Copies frame data between GPU and system memory.
+     * Direction depends on source and destination frame types.
+     *
+     * Direct mapping to av_hwframe_transfer_data().
+     *
+     * @param dst - Destination frame (software or hardware)
+     *
+     * @param flags - Transfer flags (0 for default)
+     *
+     * @returns 0 on success, negative AVERROR on error:
+     *   - AVERROR_EINVAL: Invalid parameters
+     *   - AVERROR_ENOMEM: Memory allocation failure
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError } from 'node-av';
+     *
+     * // Download from GPU to CPU
+     * const swFrame = new Frame();
+     * swFrame.alloc();
+     * const ret = await hwFrame.hwframeTransferData(swFrame);
+     * FFmpegError.throwIfError(ret, 'hwframeTransferData');
+     * ```
+     *
+     * @see {@link isHwFrame} To check if frame is hardware
+     * @see {@link isSwFrame} To check if frame is software
+     */
+    hwframeTransferData(dst: Frame, flags?: number): Promise<number>;
+    /**
+     * Transfer data between hardware and software frames synchronously.
+     * Synchronous version of hwframeTransferData.
+     *
+     * Copies frame data between GPU and system memory.
+     * Direction depends on source and destination frame types.
+     *
+     * Direct mapping to av_hwframe_transfer_data().
+     *
+     * @param dst - Destination frame (software or hardware)
+     *
+     * @param flags - Transfer flags (0 for default)
+     *
+     * @returns 0 on success, negative AVERROR on error:
+     *   - AVERROR_EINVAL: Invalid parameters
+     *   - AVERROR_ENOMEM: Memory allocation failure
+     *
+     * @example
+     * ```typescript
+     * import { FFmpegError } from 'node-av';
+     *
+     * // Download from GPU to CPU
+     * const swFrame = new Frame();
+     * swFrame.alloc();
+     * const ret = hwFrame.hwframeTransferData(swFrame);
+     * FFmpegError.throwIfError(ret, 'hwframeTransferData');
+     * ```
+     *
+     * @see {@link hwframeTransferData} For async version
+     */
+    hwframeTransferDataSync(dst: Frame, flags?: number): number;
+    /**
+     * Check if this is a hardware frame.
+     *
+     * Returns true if frame data is in GPU memory.
+     *
+     * @returns True if hardware frame, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (frame.isHwFrame()) {
+     *   console.log('Frame is in GPU memory');
+     * }
+     * ```
+     *
+     * @see {@link isSwFrame} To check for software frame
+     * @see {@link hwframeTransferData} To transfer between GPU/CPU
+     */
+    isHwFrame(): boolean;
+    /**
+     * Check if this is a software frame.
+     *
+     * Returns true if frame data is in system memory.
+     *
+     * @returns True if software frame, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (frame.isSwFrame()) {
+     *   console.log('Frame is in system memory');
+     * }
+     * ```
+     *
+     * @see {@link isHwFrame} To check for hardware frame
+     * @see {@link hwframeTransferData} To transfer between GPU/CPU
+     */
+    isSwFrame(): boolean;
+    /**
+     * Export the IOSurface backing a decoded VideoToolbox frame (macOS only).
+     *
+     * Returns the `IOSurfaceRef` carried by an `AV_PIX_FMT_VIDEOTOOLBOX` frame as
+     * an 8-byte pointer Buffer — the same handle format accepted by
+     * {@link Frame.fromIOSurface}. This enables zero-copy interop with Metal /
+     * CoreVideo (e.g. feeding a hardware-decoded frame into a GPU compositor)
+     * without a GPU→CPU readback.
+     *
+     * Returns `null` when the frame is not a decoded VideoToolbox hardware frame,
+     * has no backing IOSurface, or on non-macOS platforms.
+     *
+     * **Lifetime:** the IOSurface stays owned by the frame's `CVPixelBuffer`.
+     * Keep this `Frame` alive while using the handle. If the surface must outlive
+     * the frame, retain it separately (e.g. `IOSurfaceIncrementUseCount`).
+     *
+     * @returns IOSurfaceRef pointer as Buffer, or null if not available
+     *
+     * @example
+     * ```typescript
+     * const handle = frame.exportIOSurface();
+     * if (handle) {
+     *   // Pass to a Metal-based compositor; keep `frame` alive while in use.
+     * }
+     * ```
+     *
+     * @see {@link fromIOSurface} For the inverse (import) direction
+     */
+    exportIOSurface(): Buffer | null;
+    /**
+     * Get frame side data.
+     *
+     * Retrieves additional data associated with the frame
+     * (e.g., motion vectors, film grain, HDR metadata).
+     *
+     * Direct mapping to av_frame_get_side_data().
+     *
+     * @param type - Type of side data to retrieve
+     *
+     * @returns Side data buffer, or null if not present
+     *
+     * @example
+     * ```typescript
+     * import { AV_FRAME_DATA_MOTION_VECTORS } from 'node-av/constants';
+     *
+     * const motionVectors = frame.getSideData(AV_FRAME_DATA_MOTION_VECTORS);
+     * if (motionVectors) {
+     *   console.log(`Motion data size: ${motionVectors.length} bytes`);
+     * }
+     * ```
+     *
+     * @see {@link newSideData} To add side data
+     * @see {@link removeSideData} To remove side data
+     */
+    getSideData(type: AVFrameSideDataType): Buffer | null;
+    /**
+     * Allocate new side data.
+     *
+     * Allocates side data buffer attached to the frame.
+     * Returns buffer that can be written to directly.
+     *
+     * Direct mapping to av_frame_new_side_data().
+     *
+     * @param type - Type of side data
+     *
+     * @param size - Size in bytes to allocate
+     *
+     * @returns Allocated buffer for writing
+     *
+     * @throws {Error} If allocation fails
+     *
+     * @example
+     * ```typescript
+     * import { AV_FRAME_DATA_MASTERING_DISPLAY_METADATA } from 'node-av/constants';
+     *
+     * // Allocate and write HDR metadata
+     * const hdrData = frame.newSideData(
+     *   AV_FRAME_DATA_MASTERING_DISPLAY_METADATA,
+     *   40
+     * );
+     * // Write metadata to buffer...
+     * ```
+     *
+     * @see {@link getSideData} To retrieve side data
+     * @see {@link removeSideData} To remove side data
+     */
+    newSideData(type: AVFrameSideDataType, size: number): Buffer;
+    /**
+     * Remove side data from frame.
+     *
+     * Removes specific type of side data.
+     *
+     * Direct mapping to av_frame_remove_side_data().
+     *
+     * @param type - Type of side data to remove
+     *
+     * @example
+     * ```typescript
+     * import { AV_FRAME_DATA_MOTION_VECTORS } from 'node-av/constants';
+     *
+     * frame.removeSideData(AV_FRAME_DATA_MOTION_VECTORS);
+     * // Motion vectors removed
+     * ```
+     *
+     * @see {@link getSideData} To retrieve side data
+     * @see {@link newSideData} To add side data
+     */
+    removeSideData(type: AVFrameSideDataType): void;
+    /**
+     * Get frame metadata dictionary.
+     *
+     * Returns metadata attached to the frame by filters or demuxers.
+     * Metadata is stored as key-value pairs in a Dictionary.
+     * Useful for reading filter-generated metadata (e.g., whisper transcription).
+     *
+     * Direct mapping to AVFrame->metadata.
+     *
+     * @returns Dictionary containing frame metadata
+     *
+     * @example
+     * ```typescript
+     * // Read whisper filter metadata
+     * const metadata = frame.getMetadata();
+     * const text = metadata.get('lavfi.whisper.text');
+     * const duration = metadata.get('lavfi.whisper.duration');
+     *
+     * if (text) {
+     *   console.log(`Transcribed: ${text}`);
+     *   console.log(`Duration: ${duration}s`);
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Read scene detection metadata
+     * const metadata = frame.getMetadata();
+     * const score = metadata.get('lavfi.scene_score');
+     * if (score) {
+     *   console.log(`Scene change score: ${score}`);
+     * }
+     * ```
+     *
+     * @see {@link Dictionary} For metadata dictionary operations
+     */
+    getMetadata(): Dictionary;
+    /**
+     * Apply cropping to the frame.
+     *
+     * Crops the frame according to its crop metadata (AVFrame crop fields).
+     * This adjusts the frame dimensions and data pointers to reflect the cropped region.
+     * The cropped-out area is discarded, reducing frame size.
+     *
+     * Direct mapping to av_frame_apply_cropping().
+     *
+     * @param flags - Cropping flags (default: AV_FRAME_CROP_UNALIGNED = 1)
+     *                AV_FRAME_CROP_UNALIGNED allows unaligned cropping for lavfi compatibility
+     *
+     * @returns 0 on success, negative error code on failure
+     *
+     * @example
+     * ```typescript
+     * import { Frame, FFmpegError } from 'node-av';
+     *
+     * const frame = new Frame();
+     * // ... decode frame with crop metadata ...
+     *
+     * // Apply cropping based on metadata
+     * const ret = frame.applyCropping();
+     * FFmpegError.throwIfError(ret, 'Failed to apply cropping');
+     *
+     * // Frame dimensions are now updated to cropped size
+     * console.log(`Cropped to ${frame.width}x${frame.height}`);
+     * ```
+     */
+    applyCropping(flags?: number): number;
+    /**
+     * Get the underlying native Frame object.
+     *
+     * @returns The native Frame binding object
+     *
+     * @internal
+     */
+    getNative(): NativeFrame;
+    /**
+     * Dispose of the frame.
+     *
+     * Implements the Disposable interface for automatic cleanup.
+     * Equivalent to calling free().
+     *
+     * @example
+     * ```typescript
+     * {
+     *   using frame = new Frame();
+     *   frame.alloc();
+     *   // Use frame...
+     * } // Automatically freed when leaving scope
+     * ```
+     */
+    [Symbol.dispose](): void;
+}