node-av 1.1.0 → 1.2.0

package/dist/lib/frame.js

@@ -2,20 +2,21 @@ import { bindings } from './binding.js';
 import { HardwareFramesContext } from './hardware-frames-context.js';
 import { Rational } from './rational.js';
 /**
- * Frame for uncompressed audio/video data.
+ * Container for uncompressed audio/video data.
  *
- * Contains raw audio samples or video pixels after decoding or before encoding.
- * Provides full control over allocation, configuration and lifecycle.
- * Supports both planar and packed data layouts for audio and video.
+ * 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, AV_SAMPLE_FMT_FLTP } from 'node-av/constants';
+ * import { AV_PIX_FMT_YUV420P } from 'node-av/constants';
  *
- * // Create and allocate frame - full control
+ * // Create and allocate frame
  * const frame = new Frame();
  * frame.alloc();
  *
@@ -23,64 +24,35 @@ import { Rational } from './rational.js';
  * frame.format = AV_PIX_FMT_YUV420P;
  * frame.width = 1920;
  * frame.height = 1080;
- * const videoRet = frame.getBuffer(); // Allocate buffers
- * FFmpegError.throwIfError(videoRet, 'getBuffer');
+ * const ret = frame.allocBuffer();
+ * FFmpegError.throwIfError(ret, 'allocBuffer');
  *
- * // Configure audio frame
- * const audioFrame = new Frame();
- * audioFrame.alloc();
- * audioFrame.format = AV_SAMPLE_FMT_FLTP;
- * audioFrame.sampleRate = 48000;
- * audioFrame.nbSamples = 1024;
- * audioFrame.channelLayout = { nbChannels: 2, order: 0, mask: 3n };
- * const audioRet = audioFrame.getBuffer(); // Allocate buffers
- * FFmpegError.throwIfError(audioRet, 'getBuffer');
- *
- * // Receive decoded data
- * const ret = await codecContext.receiveFrame(frame);
- * FFmpegError.throwIfError(ret, 'receiveFrame');
- * console.log(`Frame PTS: ${frame.pts}`);
+ * // 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(); // Clear data but keep frame allocated
- * frame.free();  // Free frame completely
+ * 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 class Frame {
     native;
     _hwFramesCtx; // Cache for hardware frames context wrapper
-    /**
-     * Create a new frame.
-     *
-     * The frame is uninitialized - you must call alloc() before use.
-     * No FFmpeg resources are allocated until alloc() is called.
-     *
-     * Direct wrapper around AVFrame.
-     *
-     * @example
-     * ```typescript
-     * import { Frame } from 'node-av';
-     *
-     * const frame = new Frame();
-     * frame.alloc();
-     * // Frame is now ready for use
-     * ```
-     */
     constructor() {
         this.native = new bindings.Frame();
     }
     /**
-     * Format of the frame.
-     *
-     * For video: AVPixelFormat (-1 if unknown or unset).
-     * For audio: AVSampleFormat (-1 if unknown or unset).
-     *
-     * Direct mapping to AVFrame->format
+     * Pixel format for video frames or sample format for audio.
      *
-     * Must be set before calling getBuffer() or allocBuffer().
+     * Direct mapping to AVFrame->format.
      */
     get format() {
         return this.native.format;
@@ -89,12 +61,9 @@ export class Frame {
         this.native.format = value;
     }
     /**
-     * Width of the video frame in pixels.
+     * Width of video frame in pixels.
      *
-     * Direct mapping to AVFrame->width
-     *
-     * For video: MUST be set before calling getBuffer() or allocBuffer().
-     * For audio: unused (0).
+     * Direct mapping to AVFrame->width.
      */
     get width() {
         return this.native.width;
@@ -103,12 +72,9 @@ export class Frame {
         this.native.width = value;
     }
     /**
-     * Height of the video frame in pixels.
-     *
-     * Direct mapping to AVFrame->height
+     * Height of video frame in pixels.
      *
-     * For video: MUST be set before calling getBuffer() or allocBuffer().
-     * For audio: unused (0).
+     * Direct mapping to AVFrame->height.
      */
     get height() {
         return this.native.height;
@@ -117,12 +83,9 @@ export class Frame {
         this.native.height = value;
     }
     /**
-     * Number of audio samples (per channel) described by this frame.
+     * Number of audio samples per channel.
      *
-     * Direct mapping to AVFrame->nb_samples
-     *
-     * For audio: MUST be set before calling getBuffer() or allocBuffer().
-     * For video: unused (0).
+     * Direct mapping to AVFrame->nb_samples.
      */
     get nbSamples() {
         return this.native.nbSamples;
@@ -131,13 +94,12 @@ export class Frame {
         this.native.nbSamples = value;
     }
     /**
-     * Presentation timestamp in time_base units.
-     *
-     * Time when frame should be shown to user.
+     * Presentation timestamp.
      *
-     * Direct mapping to AVFrame->pts
+     * Time when the frame should be presented.
+     * In time base units. AV_NOPTS_VALUE if unknown.
      *
-     * Can be AV_NOPTS_VALUE if unknown.
+     * Direct mapping to AVFrame->pts.
      */
     get pts() {
         return this.native.pts;
@@ -146,12 +108,12 @@ export class Frame {
         this.native.pts = value;
     }
     /**
-     * DTS copied from the AVPacket that triggered returning this frame.
+     * DTS from the packet that produced this frame.
      *
-     * If frame threading isn't used, this is also the presentation time
-     * calculated from only AVPacket.dts values without pts values.
+     * Copy of packet DTS for reference.
+     * In time base units. AV_NOPTS_VALUE if unknown.
      *
-     * Direct mapping to AVFrame->pkt_dts
+     * Direct mapping to AVFrame->pkt_dts.
      */
     get pktDts() {
         return this.native.pktDts;
@@ -162,10 +124,10 @@ export class Frame {
     /**
      * Best effort timestamp.
      *
-     * Direct mapping to AVFrame->best_effort_timestamp (computed value)
+     * Frame timestamp estimated using various heuristics.
+     * In time base units.
      *
-     * Attempts to provide the most accurate timestamp for the frame.
-     * Uses pts if available, otherwise falls back to pkt_dts.
+     * Direct mapping to AVFrame->best_effort_timestamp.
      */
     get bestEffortTimestamp() {
         return this.native.bestEffortTimestamp;
@@ -174,12 +136,11 @@ export class Frame {
         this.native.bestEffortTimestamp = value;
     }
     /**
-     * Time base for pts/dts timestamps.
+     * Time base for timestamps.
      *
-     * Direct mapping to AVFrame->time_base
+     * Defines the unit of the timestamps (seconds per tick).
      *
-     * This is the fundamental unit of time (in seconds) in terms
-     * of which frame timestamps are represented.
+     * Direct mapping to AVFrame->time_base.
      */
     get timeBase() {
         const tb = this.native.timeBase;
@@ -191,12 +152,9 @@ export class Frame {
     /**
      * Whether this frame is a keyframe.
      *
-     * Direct mapping to AVFrame->key_frame
+     * 1 if keyframe, 0 otherwise.
      *
-     * 1 -> keyframe, 0 -> not a keyframe.
-     * It is set to 1 for all frames in intra-only codecs.
-     * - encoding: Set by libavcodec.
-     * - decoding: Set by libavcodec.
+     * Direct mapping to AVFrame->key_frame.
      */
     get keyFrame() {
         return this.native.keyFrame;
@@ -207,12 +165,9 @@ export class Frame {
     /**
      * Picture type of the frame.
      *
-     * Direct mapping to AVFrame->pict_type
+     * Type of frame (I, P, B, etc.).
      *
-     * AV_PICTURE_TYPE_I for intra frames, AV_PICTURE_TYPE_P for predicted frames,
-     * AV_PICTURE_TYPE_B for bi-directionally predicted frames, etc.
-     * - encoding: Set by libavcodec. for coded_picture (and set by user for input).
-     * - decoding: Set by libavcodec.
+     * Direct mapping to AVFrame->pict_type.
      */
     get pictType() {
         return this.native.pictType;
@@ -221,13 +176,11 @@ export class Frame {
         this.native.pictType = value;
     }
     /**
-     * Sample aspect ratio for the video frame.
+     * Sample aspect ratio.
      *
-     * Direct mapping to AVFrame->sample_aspect_ratio
+     * Pixel width/height ratio. 0/1 if unknown.
      *
-     * 0/1 if unknown/unspecified.
-     * This is the aspect ratio of a single pixel (width/height).
-     * For anamorphic video, this differs from the display aspect ratio.
+     * Direct mapping to AVFrame->sample_aspect_ratio.
      */
     get sampleAspectRatio() {
         const sar = this.native.sampleAspectRatio;
@@ -237,13 +190,11 @@ export class Frame {
         this.native.sampleAspectRatio = { num: value.num, den: value.den };
     }
     /**
-     * Sample rate of the audio data.
+     * Audio sample rate.
      *
-     * Direct mapping to AVFrame->sample_rate
+     * Number of samples per second.
      *
-     * In samples per second.
-     * - encoding: MUST be set by user.
-     * - decoding: MAY be set by libavcodec.
+     * Direct mapping to AVFrame->sample_rate.
      */
     get sampleRate() {
         return this.native.sampleRate;
@@ -252,12 +203,11 @@ export class Frame {
         this.native.sampleRate = value;
     }
     /**
-     * Channel layout of the audio data.
+     * Audio channel layout.
      *
-     * Direct mapping to AVFrame->ch_layout
+     * Describes the channel configuration.
      *
-     * Describes the number and order of audio channels.
-     * Must be set before calling getBuffer() for audio frames.
+     * Direct mapping to AVFrame->ch_layout.
      */
     get channelLayout() {
         return this.native.channelLayout;
@@ -268,40 +218,27 @@ export class Frame {
     /**
      * Number of audio channels.
      *
-     * Direct mapping to AVFrame->channels
-     *
      * Derived from channel layout.
-     * @readonly
      */
     get channels() {
         return this.native.channels;
     }
     /**
-     * Line size (stride) for each plane.
-     *
-     * Direct mapping to AVFrame->linesize
-     *
-     * For video, the size in bytes of each picture line.
-     * For audio, the size in bytes of each plane.
+     * Line sizes for each plane.
      *
-     * For audio, only linesize[0] may be set. For planar audio, each channel
-     * plane must be the same size.
+     * Number of bytes per line for each data plane.
      *
-     * For video the linesizes should be multiples of the CPUs alignment preference,
-     * this is 16 or 32 for modern desktop CPUs.
-     * @readonly
+     * Direct mapping to AVFrame->linesize.
      */
     get linesize() {
         return this.native.linesize;
     }
     /**
-     * MPEG vs JPEG YUV color range.
+     * Color range.
      *
-     * Direct mapping to AVFrame->color_range
+     * MPEG (limited) or JPEG (full) range.
      *
-     * AVCOL_RANGE_MPEG (limited/tv/16-235), AVCOL_RANGE_JPEG (full/pc/0-255)
-     * - encoding: Set by user
-     * - decoding: Set by libavcodec
+     * Direct mapping to AVFrame->color_range.
      */
     get colorRange() {
         return this.native.colorRange;
@@ -310,13 +247,11 @@ export class Frame {
         this.native.colorRange = value;
     }
     /**
-     * Chromaticity coordinates of the source primaries.
+     * Color primaries.
      *
-     * Direct mapping to AVFrame->color_primaries
+     * Chromaticity coordinates of the source primaries.
      *
-     * AVCOL_PRI_BT709, AVCOL_PRI_BT2020, etc.
-     * - encoding: Set by user
-     * - decoding: Set by libavcodec
+     * Direct mapping to AVFrame->color_primaries.
      */
     get colorPrimaries() {
         return this.native.colorPrimaries;
@@ -325,13 +260,11 @@ export class Frame {
         this.native.colorPrimaries = value;
     }
     /**
-     * Color Transfer Characteristic.
+     * Color transfer characteristic.
      *
-     * Direct mapping to AVFrame->color_trc
+     * Transfer function (gamma).
      *
-     * AVCOL_TRC_BT709, AVCOL_TRC_SMPTE2084 (PQ), AVCOL_TRC_ARIB_STD_B67 (HLG), etc.
-     * - encoding: Set by user
-     * - decoding: Set by libavcodec
+     * Direct mapping to AVFrame->color_trc.
      */
     get colorTrc() {
         return this.native.colorTrc;
@@ -340,13 +273,11 @@ export class Frame {
         this.native.colorTrc = value;
     }
     /**
-     * YUV colorspace type.
+     * YUV color space.
      *
-     * Direct mapping to AVFrame->colorspace
+     * Color space type for YUV content.
      *
-     * AVCOL_SPC_BT709, AVCOL_SPC_BT2020_NCL, etc.
-     * - encoding: Set by user
-     * - decoding: Set by libavcodec
+     * Direct mapping to AVFrame->colorspace.
      */
     get colorSpace() {
         return this.native.colorSpace;
@@ -355,13 +286,11 @@ export class Frame {
         this.native.colorSpace = value;
     }
     /**
-     * Location of chroma samples.
+     * Chroma sample location.
      *
-     * Direct mapping to AVFrame->chroma_location
+     * Position of chroma samples.
      *
-     * AVCHROMA_LOC_LEFT (MPEG-1/2/4, H.264 default), AVCHROMA_LOC_CENTER (MPEG-2), etc.
-     * - encoding: Set by user
-     * - decoding: Set by libavcodec
+     * Direct mapping to AVFrame->chroma_location.
      */
     get chromaLocation() {
         return this.native.chromaLocation;
@@ -370,52 +299,42 @@ export class Frame {
         this.native.chromaLocation = value;
     }
     /**
-     * Pointers to the data planes/channels.
+     * Raw frame data planes.
      *
-     * Direct mapping to AVFrame->data
+     * Array of buffers containing the frame data.
+     * One buffer per plane (e.g., Y, U, V for YUV420P).
      *
-     * For video, this is an array of pointers to picture planes.
-     * For packed audio, this is a single pointer to all audio data.
-     * For planar audio, each channel has a separate data pointer.
-     *
-     * AVFrame.data pointers must point to the first element of an AVFrame.buf array.
-     * @readonly
+     * Direct mapping to AVFrame->data.
      */
     get data() {
         return this.native.data;
     }
     /**
-     * Pointers to the data planes/channels for frames with more than 8 channels.
+     * Extended data planes.
      *
-     * Direct mapping to AVFrame->extended_data
+     * For audio with >8 channels or planar audio.
+     * Points to data planes beyond the first 8.
      *
-     * For audio, if the number of channels is greater than 8, this must be used
-     * to access channels beyond the first 8. Otherwise, data[] should be used.
-     * @readonly
+     * Direct mapping to AVFrame->extended_data.
      */
     get extendedData() {
         return this.native.extendedData;
     }
     /**
-     * Check if the frame data is writable.
-     *
-     * Direct mapping to av_frame_is_writable()
+     * Check if frame data is writable.
      *
-     * A frame is writable if all its underlying buffers are writable and there's
-     * only one reference to each buffer. Use makeWritable() to ensure writability.
-     * @readonly
+     * True if the frame data can be modified.
      */
     get isWritable() {
         return this.native.isWritable;
     }
-    // Hardware Acceleration
     /**
      * Hardware frames context.
      *
-     * Direct mapping to AVFrame->hw_frames_ctx
+     * Reference to hardware frames context for GPU frames.
+     * Null for software frames.
      *
-     * For hwaccel-format frames, this should be a reference to the
-     * AVHWFramesContext describing the frame.
+     * Direct mapping to AVFrame->hw_frames_ctx.
      */
     get hwFramesCtx() {
         // Return cached wrapper if we already have one
@@ -439,134 +358,117 @@ export class Frame {
         this._hwFramesCtx = undefined;
     }
     /**
-     * Allocate an AVFrame and set its fields to default values.
+     * Allocate a new frame.
      *
-     * Allocates the AVFrame structure and initializes all fields to default values.
-     * This only allocates the frame structure itself, not the data buffers.
+     * 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()
+     * Direct mapping to av_frame_alloc().
      *
-     * @throws {Error} Memory allocation failure (ENOMEM)
+     * @throws {Error} If allocation fails (ENOMEM)
      *
      * @example
      * ```typescript
-     * import { Frame } from 'node-av';
-     *
      * const frame = new Frame();
      * frame.alloc();
-     * // Frame structure is now allocated
-     * // Still need to allocate data buffers with getBuffer()
+     * // Frame structure is now ready
      * ```
      *
-     * @see {@link getBuffer} To allocate data buffers
-     * @see {@link free} To free the frame
+     * @see {@link allocBuffer} To allocate data buffers
+     * @see {@link free} To deallocate the frame
      */
     alloc() {
         this.native.alloc();
     }
     /**
-     * Free the frame and any dynamically allocated objects in it.
-     *
-     * Frees the frame structure and all associated data buffers.
-     * If the frame is reference counted, it will be unreferenced first.
+     * Free the frame.
      *
-     * Direct mapping to av_frame_free()
+     * Deallocates the frame and its data. The frame becomes invalid after this.
      *
-     * @note
-     * Calling this multiple times is safe, because we check the freed state
+     * Direct mapping to av_frame_free().
      *
      * @example
      * ```typescript
-     * import { Frame } from 'node-av';
-     *
      * frame.free();
-     * // frame is now invalid and should not be used
+     * // Frame is now invalid
      * ```
      *
-     * @see {@link unref} To clear data but keep frame allocated
+     * @see {@link unref} To only free data, keeping structure
      */
     free() {
         this.native.free();
     }
     /**
-     * Set up a new reference to the data described by the source frame.
+     * Create a reference to another frame.
      *
-     * Creates a reference to the source frame's data buffers.
-     * Both frames will share the same data through reference counting.
-     * This function does not copy side data.
+     * 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()
+     * Direct mapping to av_frame_ref().
      *
      * @param src - Source frame to reference
-     *
      * @returns 0 on success, negative AVERROR on error:
-     *   - 0: Success (frame now references src data)
-     *   - AVERROR(ENOMEM): Memory allocation failure
-     *   - AVERROR(EINVAL): Invalid parameters (null frame)
-     *   - <0: Other errors
+     *   - AVERROR_ENOMEM: Memory allocation failure
+     *   - AVERROR_EINVAL: Invalid parameters
      *
      * @example
      * ```typescript
-     * import { Frame, FFmpegError } from 'node-av';
+     * import { FFmpegError } from 'node-av';
      *
-     * const ret = frame.ref(sourceFrame);
-     * FFmpegError.throwIfError(ret, 'frame.ref');
-     * // frame now references the same data as sourceFrame
+     * const frame2 = new Frame();
+     * frame2.alloc();
+     * const ret = frame2.ref(frame1);
+     * FFmpegError.throwIfError(ret, 'ref');
+     * // frame2 now references frame1's data
      * ```
      *
-     * @see {@link unref} To remove references
-     * @see {@link clone} To create a new frame with same data
+     * @see {@link unref} To remove reference
+     * @see {@link clone} To create independent copy
      */
     ref(src) {
         return this.native.ref(src.getNative());
     }
     /**
-     * Unreference all the buffers referenced by frame and reset the frame fields.
+     * Unreference the frame.
      *
-     * Clears all data from the frame but keeps the frame structure allocated.
-     * The frame can be reused for the next decode/encode operation.
+     * 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()
+     * Direct mapping to av_frame_unref().
      *
      * @example
      * ```typescript
-     * import { Frame } from 'node-av';
-     *
      * frame.unref();
-     * // Frame is now empty but still allocated
-     * // Can be reused for next decode/encode
+     * // Frame data is freed, structure can be reused
      * ```
      *
-     * @see {@link free} To completely free the frame
+     * @see {@link ref} To create reference
+     * @see {@link free} To free everything
      */
     unref() {
         this.native.unref();
     }
     /**
-     * Create a new frame that references the same data as this frame.
+     * Clone the frame.
      *
-     * Creates a new frame and sets it up as a reference to this frame's data.
-     * This is a shortcut for av_frame_alloc() + av_frame_ref().
+     * 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()
+     * Direct mapping to av_frame_clone().
      *
-     * @returns New frame referencing the same data, or null on error:
-     *   - Frame object: Success (new frame references this frame's data)
-     *   - null: Memory allocation failure (ENOMEM)
+     * @returns New frame instance, or null on allocation failure
      *
      * @example
      * ```typescript
-     * import { Frame } from 'node-av';
-     *
-     * const clonedFrame = frame.clone();
-     * if (!clonedFrame) {
-     *   throw new Error('Failed to clone frame: Out of memory');
+     * const copy = frame.clone();
+     * if (copy) {
+     *   // Modify copy without affecting original
+     *   copy.pts = frame.pts + 1000n;
      * }
-     * // clonedFrame references the same data as frame
-     * // Both frames must be freed independently
      * ```
      *
-     * @see {@link ref} To reference into existing frame
+     * @see {@link ref} To create reference instead of copy
+     * @see {@link copy} To copy into existing frame
      */
     clone() {
         const cloned = this.native.clone();
@@ -575,266 +477,216 @@ export class Frame {
         }
         // Wrap the native cloned frame
         const frame = Object.create(Frame.prototype);
-        // Need to set private property - this is safe since we control the implementation
         frame.native = cloned;
         return frame;
     }
     /**
-     * Allocate new buffer(s) for audio or video data.
+     * Get required buffer size for the frame.
      *
-     * Allocates data buffers for the frame based on its parameters.
-     * Frame parameters must be set before calling this function.
+     * Calculates the required buffer size 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()
+     * Direct mapping to av_frame_get_buffer().
      *
-     * @param align - Required buffer size alignment. 0 for automatic.
-     *
-     * @returns 0 on success, negative AVERROR on error:
-     *   - 0: Success (buffers allocated)
-     *   - AVERROR(EINVAL): Invalid frame parameters (format/size not set)
-     *   - AVERROR(ENOMEM): Memory allocation failure
-     *   - <0: Other errors
+     * @param align - Buffer size alignment (0 for default)
+     * @returns Required buffer size in bytes, or negative AVERROR:
+     *   - AVERROR_EINVAL: Invalid frame parameters
      *
      * @example
      * ```typescript
-     * import { Frame, FFmpegError, AV_PIX_FMT_YUV420P } from 'node-av';
+     * import { FFmpegError } from 'node-av';
      *
-     * // Video frame
-     * frame.format = AV_PIX_FMT_YUV420P;
-     * frame.width = 1920;
-     * frame.height = 1080;
-     * const ret = frame.getBuffer(0);
-     * FFmpegError.throwIfError(ret, 'getBuffer');
-     * // Frame data buffers are now allocated
+     * const size = frame.getBuffer();
+     * FFmpegError.throwIfError(size, 'getBuffer');
+     * console.log(`Buffer size: ${size} bytes`);
      * ```
      *
-     * @see {@link allocBuffer} Convenience wrapper with default alignment
-     * @see {@link makeWritable} Ensure buffer is writable
-     *
-     * Required fields before calling:
-     * - format (pixel format for video, sample format for audio)
-     * - width and height for video
-     * - nb_samples and channel_layout for audio
+     * @see {@link allocBuffer} To allocate the buffer
      */
     getBuffer(align = 0) {
         return this.native.getBuffer(align);
     }
     /**
-     * Allocate buffer(s) for frame according to its parameters.
+     * Allocate data buffers for the frame.
      *
-     * Convenience wrapper for getBuffer() with default alignment.
+     * Allocates buffers based on frame format and dimensions.
      * Frame parameters must be set before calling.
      *
-     * Direct mapping to av_frame_get_buffer() with align=0
+     * Direct mapping to av_frame_get_buffer().
      *
      * @returns 0 on success, negative AVERROR on error:
-     *   - 0: Success (buffers allocated)
-     *   - AVERROR(EINVAL): Invalid frame parameters
-     *   - AVERROR(ENOMEM): Memory allocation failure
-     *   - <0: Other errors
+     *   - AVERROR_EINVAL: Invalid frame parameters
+     *   - AVERROR_ENOMEM: Memory allocation failure
      *
      * @example
      * ```typescript
-     * import { Frame, FFmpegError } from 'node-av';
+     * 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');
-     * // Frame data buffers are now allocated
      * ```
      *
-     * @see {@link getBuffer} With custom alignment
+     * @see {@link getBuffer} To get required size
      */
     allocBuffer() {
         return this.native.allocBuffer();
     }
     /**
-     * Ensure that the frame data is writable.
+     * Ensure frame data is writable.
      *
-     * Makes a private copy of the frame data if it's currently shared.
-     * Does nothing if frame is already 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()
+     * Direct mapping to av_frame_make_writable().
      *
      * @returns 0 on success, negative AVERROR on error:
-     *   - 0: Success (frame is now writable)
-     *   - AVERROR(ENOMEM): Memory allocation failure
-     *   - AVERROR(EINVAL): Invalid parameters
-     *   - <0: Other errors
+     *   - AVERROR_ENOMEM: Memory allocation failure
+     *   - AVERROR_EINVAL: Invalid frame
      *
      * @example
      * ```typescript
-     * import { Frame, FFmpegError } from 'node-av';
+     * import { FFmpegError } from 'node-av';
      *
-     * if (!frame.isWritable) {
-     *   const ret = frame.makeWritable();
-     *   FFmpegError.throwIfError(ret, 'makeWritable');
-     * }
-     * // Frame data can now be modified safely
+     * // Ensure we can safely modify data
+     * const ret = frame.makeWritable();
+     * FFmpegError.throwIfError(ret, 'makeWritable');
+     * // Now safe to modify frame.data
      * ```
-     *
-     * @see {@link isWritable} Check if writable
      */
     makeWritable() {
         return this.native.makeWritable();
     }
     /**
-     * Copy only "metadata" fields from src to this frame.
+     * Copy frame properties without copying data.
      *
-     * Copies all frame properties except the actual data buffers.
-     * This includes timestamps, format, dimensions, side data, etc.
+     * Copies metadata, timestamps, format info, etc. but not the actual data.
+     * Useful for preparing output frames with same properties.
      *
-     * Direct mapping to av_frame_copy_props()
+     * Direct mapping to av_frame_copy_props().
      *
      * @param src - Source frame to copy properties from
-     *
-     * @returns >=0 on success, negative AVERROR on error:
-     *   - >=0: Success (properties copied)
-     *   - AVERROR(ENOMEM): Memory allocation failure
-     *   - <0: Other errors
+     * @returns 0 on success, negative AVERROR on error:
+     *   - AVERROR_ENOMEM: Memory allocation failure
      *
      * @example
      * ```typescript
-     * import { Frame, FFmpegError } from 'node-av';
+     * import { FFmpegError } from 'node-av';
      *
      * const ret = dstFrame.copyProps(srcFrame);
      * FFmpegError.throwIfError(ret, 'copyProps');
-     * // dstFrame now has same properties as srcFrame (but not data)
+     * // dstFrame now has same properties as srcFrame
      * ```
      *
-     * @see {@link copy} To copy data as well
+     * @see {@link copy} To copy both properties and data
      */
     copyProps(src) {
         return this.native.copyProps(src.getNative());
     }
     /**
-     * Copy the frame data from src to this frame.
-     *
-     * Copies the actual data buffers from source to destination.
-     * Destination must be pre-allocated with same parameters.
+     * Copy frame data and properties.
      *
-     * Direct mapping to av_frame_copy()
+     * Copies both data and metadata from source frame.
+     * Destination must have allocated buffers of correct size.
      *
-     * @param src - Source frame to copy data from
+     * Direct mapping to av_frame_copy().
      *
-     * @returns >=0 on success, negative AVERROR on error:
-     *   - >=0: Success (data copied)
-     *   - AVERROR(EINVAL): Frames have different parameters (format, size, etc.)
-     *   - <0: Other errors
+     * @param src - Source frame to copy from
+     * @returns 0 on success, negative AVERROR on error:
+     *   - AVERROR_EINVAL: Incompatible frames
      *
      * @example
      * ```typescript
-     * import { Frame, FFmpegError } from 'node-av';
+     * import { FFmpegError } from 'node-av';
      *
-     * // Destination must be allocated with same parameters
+     * // Allocate destination with same format
      * dstFrame.format = srcFrame.format;
      * dstFrame.width = srcFrame.width;
      * dstFrame.height = srcFrame.height;
-     * const allocRet = dstFrame.allocBuffer();
-     * FFmpegError.throwIfError(allocRet, 'allocBuffer');
+     * dstFrame.allocBuffer();
      *
      * const ret = dstFrame.copy(srcFrame);
      * FFmpegError.throwIfError(ret, 'copy');
-     * // Data has been copied to dstFrame
      * ```
      *
-     * @see {@link copyProps} To copy metadata only
+     * @see {@link copyProps} To copy only properties
+     * @see {@link clone} To create new frame with copy
      */
     copy(src) {
         return this.native.copy(src.getNative());
     }
     /**
-     * Fill frame data from a buffer.
-     *
-     * Copies raw frame data from a Buffer into this frame's data planes.
-     * The frame must be allocated with the correct format, width/height (for video),
-     * or nb_samples (for audio) before calling this method.
+     * Fill frame data from buffer.
      *
-     * For video frames, the buffer should contain raw pixel data in the frame's pixel format.
-     * For audio frames, the buffer should contain raw audio samples in the frame's sample format.
+     * Copies data from buffer into frame data planes.
+     * Frame must have allocated buffers.
      *
-     * @param buffer - Buffer containing raw frame data
-     * @returns 0 on success, negative AVERROR on failure
+     * @param buffer - Source buffer with frame data
+     * @returns 0 on success, negative AVERROR on error:
+     *   - AVERROR_EINVAL: Invalid parameters
      *
      * @example
      * ```typescript
-     * // Video frame from raw YUV420p data
-     * const frame = new Frame();
-     * frame.alloc();
-     * frame.format = AV_PIX_FMT_YUV420P;
-     * frame.width = 1920;
-     * frame.height = 1080;
-     * frame.allocBuffer();
-     * frame.fromBuffer(rawYuvBuffer);
-     *
-     * // Audio frame from raw PCM data
-     * const audioFrame = new Frame();
-     * audioFrame.alloc();
-     * audioFrame.format = AV_SAMPLE_FMT_FLTP;
-     * audioFrame.nbSamples = 1024;
-     * audioFrame.channelLayout = { order: 0, nb_channels: 2, u: { mask: 3n } };
-     * audioFrame.allocBuffer();
-     * audioFrame.fromBuffer(rawPcmBuffer);
+     * import { FFmpegError } from 'node-av';
+     *
+     * const buffer = Buffer.from(rawVideoData);
+     * const ret = frame.fromBuffer(buffer);
+     * FFmpegError.throwIfError(ret, 'fromBuffer');
      * ```
      */
     fromBuffer(buffer) {
         return this.native.fromBuffer(buffer);
     }
     /**
-     * Transfer data to or from hardware surfaces.
+     * Transfer data between hardware and software frames.
      *
-     * Transfers frame data between hardware (GPU) and software (CPU) memory.
-     * Can be used for both upload and download operations.
+     * Copies frame data between GPU and system memory.
+     * Direction depends on source and destination frame types.
      *
-     * Direct mapping to av_hwframe_transfer_data()
+     * Direct mapping to av_hwframe_transfer_data().
      *
-     * @param dst - Destination frame
-     * @param flags - Transfer flags (currently unused, should be set to zero)
-     *
-     * @returns Promise resolving to 0 on success, negative AVERROR on error:
-     *   - 0: Success (data transferred)
-     *   - AVERROR(ENOSYS): Operation not supported
-     *   - AVERROR(EINVAL): Invalid parameters
-     *   - AVERROR(ENOMEM): Memory allocation failure
-     *   - <0: Other hardware-specific errors
+     * @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 { Frame, FFmpegError } from 'node-av';
+     * import { FFmpegError } from 'node-av';
      *
-     * // Transfer from hardware to software frame
+     * // Download from GPU to CPU
      * const swFrame = new Frame();
      * swFrame.alloc();
-     * const ret = await hwFrame.hwframeTransferData(swFrame, 0);
+     * const ret = await hwFrame.hwframeTransferData(swFrame);
      * FFmpegError.throwIfError(ret, 'hwframeTransferData');
-     * // Data is now in CPU memory
      * ```
      *
-     * @see {@link isHwFrame} Check if frame is hardware frame
+     * @see {@link isHwFrame} To check if frame is hardware
+     * @see {@link isSwFrame} To check if frame is software
      */
     async hwframeTransferData(dst, flags) {
-        return this.native.hwframeTransferData(dst.getNative(), flags ?? 0);
+        return await this.native.hwframeTransferData(dst.getNative(), flags ?? 0);
     }
     /**
      * Check if this is a hardware frame.
      *
-     * A frame is considered a hardware frame if it has a hw_frames_ctx set.
-     *
-     * Direct check of AVFrame->hw_frames_ctx
+     * Returns true if frame data is in GPU memory.
      *
-     * @returns True if this is a hardware frame, false otherwise
+     * @returns True if hardware frame, false otherwise
      *
      * @example
      * ```typescript
-     * import { Frame } from 'node-av';
-     *
      * if (frame.isHwFrame()) {
      *   console.log('Frame is in GPU memory');
-     * } else {
-     *   console.log('Frame is in CPU memory');
      * }
      * ```
      *
-     * @see {@link hwframeTransferData} To transfer between CPU and GPU
+     * @see {@link isSwFrame} To check for software frame
+     * @see {@link hwframeTransferData} To transfer between GPU/CPU
      */
     isHwFrame() {
         return this.native.isHwFrame();
@@ -842,104 +694,111 @@ export class Frame {
     /**
      * Check if this is a software frame.
      *
-     * A frame is considered a software frame if it doesn't have hw_frames_ctx
-     * but has actual data pointers.
-     *
-     * Direct check of AVFrame->data[0] && !AVFrame->hw_frames_ctx
+     * Returns true if frame data is in system memory.
      *
-     * @returns True if this is a software frame, false otherwise
+     * @returns True if software frame, false otherwise
      *
      * @example
      * ```typescript
-     * import { Frame } from 'node-av';
-     *
      * if (frame.isSwFrame()) {
-     *   console.log('Frame is in CPU memory');
-     *   // Safe to access frame.data
+     *   console.log('Frame is in system memory');
      * }
      * ```
      *
-     * @see {@link isHwFrame} To check for hardware frames
+     * @see {@link isHwFrame} To check for hardware frame
+     * @see {@link hwframeTransferData} To transfer between GPU/CPU
      */
     isSwFrame() {
         return this.native.isSwFrame();
     }
     /**
-     * Get side data from the frame.
+     * 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()
+     * Direct mapping to av_frame_get_side_data().
      *
-     * @param type - The type of side data to retrieve
-     * @returns Buffer containing the side data, or null if not found
+     * @param type - Type of side data to retrieve
+     * @returns Side data buffer, or null if not present
      *
      * @example
      * ```typescript
-     * import { Frame } from 'node-av';
-     * import { AV_FRAME_DATA_A53_CC } from 'node-av/constants';
+     * import { AV_FRAME_DATA_MOTION_VECTORS } from 'node-av/constants';
      *
-     * // Check for closed captions
-     * const ccData = frame.getSideData(AV_FRAME_DATA_A53_CC);
-     * if (ccData) {
-     *   console.log('Found closed caption data:', ccData.length, 'bytes');
+     * 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) {
         return this.native.getSideData(type);
     }
     /**
-     * Allocate new side data for the frame.
+     * Allocate new side data.
      *
-     * Allocates a new side data buffer of the specified size.
-     * Returns a Buffer that references the allocated memory.
-     * Direct mapping to av_frame_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
      *
-     * @param type - The type of side data to allocate
-     * @param size - Size of the side data buffer to allocate
-     * @returns Buffer referencing the allocated side data
      * @throws {Error} If allocation fails
      *
      * @example
      * ```typescript
-     * import { Frame } from 'node-av';
      * import { AV_FRAME_DATA_MASTERING_DISPLAY_METADATA } from 'node-av/constants';
      *
-     * // Allocate HDR metadata
-     * const hdrBuffer = frame.newSideData(
+     * // Allocate and write HDR metadata
+     * const hdrData = frame.newSideData(
      *   AV_FRAME_DATA_MASTERING_DISPLAY_METADATA,
-     *   24 // Size of mastering display metadata structure
+     *   40
      * );
-     * // Write HDR metadata to the buffer
+     * // Write metadata to buffer...
      * ```
+     *
+     * @see {@link getSideData} To retrieve side data
+     * @see {@link removeSideData} To remove side data
      */
     newSideData(type, size) {
         return this.native.newSideData(type, size);
     }
     /**
-     * Remove side data from the frame.
+     * Remove side data from frame.
+     *
+     * Removes specific type of side data.
      *
-     * Removes and frees the specified type of side data from the frame.
-     * Direct mapping to av_frame_remove_side_data()
+     * Direct mapping to av_frame_remove_side_data().
      *
-     * @param type - The type of side data to remove
+     * @param type - Type of side data to remove
      *
      * @example
      * ```typescript
-     * import { Frame } from 'node-av';
      * import { AV_FRAME_DATA_MOTION_VECTORS } from 'node-av/constants';
      *
-     * // Remove motion vectors data
      * 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) {
         this.native.removeSideData(type);
     }
     /**
-     * Get the native FFmpeg AVFrame pointer.
+     * Get the underlying native Frame object.
+     *
+     * @returns The native Frame binding object
      *
-     * @internal For use by other wrapper classes
-     * @returns The underlying native frame object
+     * @internal
      */
     getNative() {
         return this.native;
@@ -952,16 +811,12 @@ export class Frame {
      *
      * @example
      * ```typescript
-     * import { Frame } from 'node-av';
-     *
      * {
      *   using frame = new Frame();
      *   frame.alloc();
-     *   // ... use frame
+     *   // Use frame...
      * } // Automatically freed when leaving scope
      * ```
-     *
-     * @see {@link free} For manual cleanup
      */
     [Symbol.dispose]() {
         this.native[Symbol.dispose]();