node-av 1.1.0 → 1.2.0

package/dist/lib/codec-context.js

@@ -4,11 +4,12 @@ import { HardwareFramesContext } from './hardware-frames-context.js';
 import { OptionMember } from './option.js';
 import { Rational } from './rational.js';
 /**
- * Codec context for encoding and decoding media.
+ * Codec context for encoding and decoding.
  *
- * Central structure for media encoding and decoding operations.
- * Manages codec state, parameters, and threading.
- * Supports both software and hardware acceleration.
+ * Main structure for codec operations, containing all codec parameters and state.
+ * Handles encoding raw frames to packets and decoding packets to frames.
+ * Supports both software and hardware-accelerated codecs.
+ * Must be configured and opened before use.
  *
  * Direct mapping to FFmpeg's AVCodecContext.
  *
@@ -17,64 +18,45 @@ import { Rational } from './rational.js';
  * import { CodecContext, Codec, FFmpegError } from 'node-av';
  * import { AV_CODEC_ID_H264, AV_PIX_FMT_YUV420P } from 'node-av/constants';
  *
- * // Create and configure decoder context
+ * // Create decoder
+ * const decoder = new CodecContext();
  * const codec = Codec.findDecoder(AV_CODEC_ID_H264);
- * const ctx = new CodecContext();
- * ctx.allocContext3(codec);
+ * decoder.allocContext3(codec);
  *
- * // Configure parameters
- * ctx.width = 1920;
- * ctx.height = 1080;
- * ctx.pixelFormat = AV_PIX_FMT_YUV420P;
+ * // Configure from stream parameters
+ * decoder.parametersToContext(stream.codecpar);
  *
- * // Open codec
- * const ret = await ctx.open2(codec, null);
+ * // Open decoder
+ * let ret = await decoder.open2(codec);
  * FFmpegError.throwIfError(ret, 'open2');
  *
  * // Decode packets
- * const sendRet = await ctx.sendPacket(packet);
- * FFmpegError.throwIfError(sendRet, 'sendPacket');
- *
- * while (true) {
- *   const ret = await ctx.receiveFrame(frame);
- *   if (ret === AVERROR_EOF || ret === AVERROR(EAGAIN)) break;
- *   FFmpegError.throwIfError(ret, 'receiveFrame');
- *   // Process frame
+ * ret = await decoder.sendPacket(packet);
+ * if (ret >= 0) {
+ *   ret = await decoder.receiveFrame(frame);
+ *   if (ret >= 0) {
+ *     // Process decoded frame
+ *   }
  * }
  *
  * // Cleanup
- * ctx.freeContext();
+ * decoder.freeContext();
  * ```
+ *
+ * @see [AVCodecContext](https://ffmpeg.org/doxygen/trunk/structAVCodecContext.html) - FFmpeg Doxygen
+ * @see {@link Codec} For finding codecs
+ * @see {@link CodecParameters} For stream parameters
  */
 export class CodecContext extends OptionMember {
     _hwDeviceCtx; // Cache for hardware device context wrapper
     _hwFramesCtx; // Cache for hardware frames context wrapper
-    /**
-     * Create a new codec context.
-     *
-     * The context is uninitialized - you must call allocContext3() before use.
-     * No FFmpeg resources are allocated until initialization.
-     *
-     * Direct wrapper around AVCodecContext.
-     *
-     * @example
-     * ```typescript
-     * import { CodecContext, Codec } from 'node-av';
-     *
-     * const ctx = new CodecContext();
-     * ctx.allocContext3(codec);
-     * // Context is now ready for configuration
-     * ```
-     */
     constructor() {
         super(new bindings.CodecContext());
     }
     /**
-     * Codec type.
-     *
-     * Identifies whether this is a video, audio, subtitle, or data codec.
+     * Type of codec (video/audio/subtitle).
      *
-     * Direct mapping to AVCodecContext->codec_type
+     * Direct mapping to AVCodecContext->codec_type.
      */
     get codecType() {
         return this.native.codecType;
@@ -83,11 +65,9 @@ export class CodecContext extends OptionMember {
         this.native.codecType = value;
     }
     /**
-     * Codec ID.
+     * Codec identifier.
      *
-     * Identifies the specific codec (e.g., AV_CODEC_ID_H264, AV_CODEC_ID_AAC).
-     *
-     * Direct mapping to AVCodecContext->codec_id
+     * Direct mapping to AVCodecContext->codec_id.
      */
     get codecId() {
         return this.native.codecId;
@@ -96,12 +76,12 @@ export class CodecContext extends OptionMember {
         this.native.codecId = value;
     }
     /**
-     * The average bitrate.
+     * Average bitrate.
      *
-     * Direct mapping to AVCodecContext->bit_rate
+     * Target bitrate for encoding, detected bitrate for decoding.
+     * In bits per second.
      *
-     * - encoding: Set by user, unused for constant quantizer encoding.
-     * - decoding: Set by user, may be overwritten by libavcodec if this info is available in the stream.
+     * Direct mapping to AVCodecContext->bit_rate.
      */
     get bitRate() {
         return this.native.bitRate;
@@ -112,12 +92,9 @@ export class CodecContext extends OptionMember {
     /**
      * Time base for timestamps.
      *
-     * The fundamental unit of time (in seconds) for frame timestamps.
-     *
-     * Direct mapping to AVCodecContext->time_base
+     * Fundamental unit of time in seconds for this context.
      *
-     * - encoding: MUST be set by user.
-     * - decoding: the use of this field for decoding is deprecated. Use framerate instead.
+     * Direct mapping to AVCodecContext->time_base.
      */
     get timeBase() {
         const tb = this.native.timeBase;
@@ -127,9 +104,11 @@ export class CodecContext extends OptionMember {
         this.native.timeBase = { num: value.num, den: value.den };
     }
     /**
-     * Timebase in which pkt_dts/pts and AVPacket.dts/pts are.
-     * This is the fundamental unit of time (in seconds) in terms
-     * of which frame timestamps are represented.
+     * Packet time base.
+     *
+     * Time base of the packets from/to the demuxer/muxer.
+     *
+     * Direct mapping to AVCodecContext->pkt_timebase.
      */
     get pktTimebase() {
         const tb = this.native.pktTimebase;
@@ -140,19 +119,20 @@ export class CodecContext extends OptionMember {
     }
     /**
      * Codec delay.
-     * - encoding: Number of frames delay there will be from the encoder input to
-     *             the decoder output. (we assume the decoder matches the spec)
-     * - decoding: Number of frames delay in addition to what a standard decoder
-     *             as specified in the spec would produce.
-     * @readonly
+     *
+     * Number of frames the decoder needs to output before first frame.
+     *
+     * Direct mapping to AVCodecContext->delay.
      */
     get delay() {
         return this.native.delay;
     }
     /**
-     * AV_CODEC_FLAG_* flags.
-     * - encoding: Set by user.
-     * - decoding: Set by user.
+     * Codec flags.
+     *
+     * Combination of AV_CODEC_FLAG_* values.
+     *
+     * Direct mapping to AVCodecContext->flags.
      */
     get flags() {
         return this.native.flags;
@@ -161,9 +141,11 @@ export class CodecContext extends OptionMember {
         this.native.flags = value;
     }
     /**
-     * AV_CODEC_FLAG2_* flags.
-     * - encoding: Set by user.
-     * - decoding: Set by user.
+     * Additional codec flags.
+     *
+     * Combination of AV_CODEC_FLAG2_* values.
+     *
+     * Direct mapping to AVCodecContext->flags2.
      */
     get flags2() {
         return this.native.flags2;
@@ -172,16 +154,11 @@ export class CodecContext extends OptionMember {
         this.native.flags2 = value;
     }
     /**
-     * Some codecs need / can use extradata like Huffman tables.
-     * MJPEG: Huffman tables
-     * rv10: additional flags
-     * MPEG-4: global headers (they can be in the bitstream or here)
-     * The allocated memory should be AV_INPUT_BUFFER_PADDING_SIZE bytes larger
-     * than extradata_size to avoid problems if it is read with the bitstream reader.
-     * The bytewise contents of extradata must not depend on the architecture or CPU endianness.
-     * Must be allocated with the av_malloc() family of functions.
-     * - encoding: Set/allocated/freed by libavcodec.
-     * - decoding: Set/allocated/freed by user.
+     * Extra binary data for codec.
+     *
+     * Contains codec-specific initialization data.
+     *
+     * Direct mapping to AVCodecContext->extradata.
      */
     get extraData() {
         return this.native.extraData;
@@ -190,9 +167,11 @@ export class CodecContext extends OptionMember {
         this.native.extraData = value;
     }
     /**
-     * Profile (FF_PROFILE_H264_BASELINE, FF_PROFILE_H264_MAIN, etc.)
-     * - encoding: Set by user.
-     * - decoding: Set by libavcodec.
+     * Codec profile.
+     *
+     * FF_PROFILE_* value indicating codec profile.
+     *
+     * Direct mapping to AVCodecContext->profile.
      */
     get profile() {
         return this.native.profile;
@@ -201,9 +180,11 @@ export class CodecContext extends OptionMember {
         this.native.profile = value;
     }
     /**
-     * Level (FF_LEVEL_UNKNOWN, or codec-specific values)
-     * - encoding: Set by user.
-     * - decoding: Set by libavcodec.
+     * Codec level.
+     *
+     * Level within the specified profile.
+     *
+     * Direct mapping to AVCodecContext->level.
      */
     get level() {
         return this.native.level;
@@ -212,10 +193,12 @@ export class CodecContext extends OptionMember {
         this.native.level = value;
     }
     /**
-     * Thread count.
-     * Is used to decide how many independent tasks should be passed to execute().
-     * - encoding: Set by user.
-     * - decoding: Set by user.
+     * Thread count for codec.
+     *
+     * Number of threads to use for decoding/encoding.
+     * 0 for automatic selection.
+     *
+     * Direct mapping to AVCodecContext->thread_count.
      */
     get threadCount() {
         return this.native.threadCount;
@@ -224,12 +207,9 @@ export class CodecContext extends OptionMember {
         this.native.threadCount = value;
     }
     /**
-     * Picture width.
-     * - encoding: MUST be set by user.
-     * - decoding: May be set by the user before opening the decoder if known e.g.
-     *             from the container. Some decoders will require the dimensions
-     *             to be set by the caller. During decoding, the decoder may
-     *             overwrite those values as required while parsing the data.
+     * Picture width in pixels.
+     *
+     * Direct mapping to AVCodecContext->width.
      */
     get width() {
         return this.native.width;
@@ -238,12 +218,9 @@ export class CodecContext extends OptionMember {
         this.native.width = value;
     }
     /**
-     * Picture height.
-     * - encoding: MUST be set by user.
-     * - decoding: May be set by the user before opening the decoder if known e.g.
-     *             from the container. Some decoders will require the dimensions
-     *             to be set by the caller. During decoding, the decoder may
-     *             overwrite those values as required while parsing the data.
+     * Picture height in pixels.
+     *
+     * Direct mapping to AVCodecContext->height.
      */
     get height() {
         return this.native.height;
@@ -252,9 +229,11 @@ export class CodecContext extends OptionMember {
         this.native.height = value;
     }
     /**
-     * The number of pictures in a group of pictures, or 0 for intra_only.
-     * - encoding: Set by user.
-     * - decoding: unused
+     * Group of pictures size.
+     *
+     * Maximum number of frames between keyframes.
+     *
+     * Direct mapping to AVCodecContext->gop_size.
      */
     get gopSize() {
         return this.native.gopSize;
@@ -264,9 +243,10 @@ export class CodecContext extends OptionMember {
     }
     /**
      * Pixel format.
-     * - encoding: Set by user.
-     * - decoding: Set by user if known, overridden by libavcodec while
-     *             parsing the data.
+     *
+     * Format of the video frames.
+     *
+     * Direct mapping to AVCodecContext->pix_fmt.
      */
     get pixelFormat() {
         return this.native.pixelFormat;
@@ -275,10 +255,11 @@ export class CodecContext extends OptionMember {
         this.native.pixelFormat = value;
     }
     /**
-     * Maximum number of B-frames between non-B-frames.
-     * Note: The output will be delayed by max_b_frames+1 relative to the input.
-     * - encoding: Set by user.
-     * - decoding: unused
+     * Maximum number of B-frames.
+     *
+     * B-frames between non-B-frames.
+     *
+     * Direct mapping to AVCodecContext->max_b_frames.
      */
     get maxBFrames() {
         return this.native.maxBFrames;
@@ -289,15 +270,9 @@ export class CodecContext extends OptionMember {
     /**
      * Macroblock decision mode.
      *
-     * Direct mapping to AVCodecContext->mb_decision
+     * Algorithm for macroblock decision.
      *
-     * - encoding: Set by user.
-     * - decoding: unused
-     *
-     * Values:
-     * - 0 (FF_MB_DECISION_SIMPLE): uses mb_cmp
-     * - 1 (FF_MB_DECISION_BITS): chooses the one which needs the fewest bits
-     * - 2 (FF_MB_DECISION_RD): rate distortion
+     * Direct mapping to AVCodecContext->mb_decision.
      */
     get mbDecision() {
         return this.native.mbDecision;
@@ -306,21 +281,21 @@ export class CodecContext extends OptionMember {
         this.native.mbDecision = value;
     }
     /**
-     * Size of the frame reordering buffer in the decoder.
-     * For MPEG-2 it is 1 IPB or 0 low delay IP.
-     * - encoding: Set by libavcodec.
-     * - decoding: Set by libavcodec.
-     * @readonly
+     * Number of frames delay in decoder.
+     *
+     * For codecs with B-frames.
+     *
+     * Direct mapping to AVCodecContext->has_b_frames.
      */
     get hasBFrames() {
         return this.native.hasBFrames;
     }
     /**
-     * Sample aspect ratio (0 if unknown).
-     * That is the width of a pixel divided by the height of the pixel.
-     * Numerator and denominator must be relatively prime and smaller than 256 for some video standards.
-     * - encoding: Set by user.
-     * - decoding: Set by libavcodec.
+     * Sample aspect ratio.
+     *
+     * Pixel width/height ratio.
+     *
+     * Direct mapping to AVCodecContext->sample_aspect_ratio.
      */
     get sampleAspectRatio() {
         const sar = this.native.sampleAspectRatio;
@@ -330,11 +305,11 @@ export class CodecContext extends OptionMember {
         this.native.sampleAspectRatio = { num: value.num, den: value.den };
     }
     /**
-     * Framerate.
-     * - encoding: May be used to signal the framerate of CFR content to an encoder.
-     * - decoding: For codecs that store a framerate value in the compressed
-     *             bitstream, the decoder may export it here. { 0, 1} when
-     *             unknown.
+     * Frame rate.
+     *
+     * Frames per second for encoding.
+     *
+     * Direct mapping to AVCodecContext->framerate.
      */
     get framerate() {
         const fr = this.native.framerate;
@@ -344,9 +319,11 @@ export class CodecContext extends OptionMember {
         this.native.framerate = { num: value.num, den: value.den };
     }
     /**
-     * Color range (AVCOL_RANGE_MPEG, AVCOL_RANGE_JPEG, etc.)
-     * - encoding: Set by user
-     * - decoding: Set by libavcodec
+     * Color range.
+     *
+     * MPEG (limited) or JPEG (full) range.
+     *
+     * Direct mapping to AVCodecContext->color_range.
      */
     get colorRange() {
         return this.native.colorRange;
@@ -355,9 +332,11 @@ export class CodecContext extends OptionMember {
         this.native.colorRange = value;
     }
     /**
-     * Chromaticity coordinates of the source primaries.
-     * - encoding: Set by user
-     * - decoding: Set by libavcodec
+     * Color primaries.
+     *
+     * Chromaticity coordinates of source primaries.
+     *
+     * Direct mapping to AVCodecContext->color_primaries.
      */
     get colorPrimaries() {
         return this.native.colorPrimaries;
@@ -366,9 +345,11 @@ export class CodecContext extends OptionMember {
         this.native.colorPrimaries = value;
     }
     /**
-     * Color Transfer Characteristic.
-     * - encoding: Set by user
-     * - decoding: Set by libavcodec
+     * Color transfer characteristic.
+     *
+     * Transfer function (gamma).
+     *
+     * Direct mapping to AVCodecContext->color_trc.
      */
     get colorTrc() {
         return this.native.colorTrc;
@@ -377,9 +358,11 @@ export class CodecContext extends OptionMember {
         this.native.colorTrc = value;
     }
     /**
-     * YUV colorspace type.
-     * - encoding: Set by user
-     * - decoding: Set by libavcodec
+     * YUV color space.
+     *
+     * Color space for YUV content.
+     *
+     * Direct mapping to AVCodecContext->colorspace.
      */
     get colorSpace() {
         return this.native.colorSpace;
@@ -388,9 +371,11 @@ export class CodecContext extends OptionMember {
         this.native.colorSpace = value;
     }
     /**
-     * Location of chroma samples.
-     * - encoding: Set by user
-     * - decoding: Set by libavcodec
+     * Chroma sample location.
+     *
+     * Position of chroma samples.
+     *
+     * Direct mapping to AVCodecContext->chroma_sample_location.
      */
     get chromaLocation() {
         return this.native.chromaLocation;
@@ -399,10 +384,11 @@ export class CodecContext extends OptionMember {
         this.native.chromaLocation = value;
     }
     /**
-     * Sample rate of the audio data.
-     * - encoding: MUST be set by user.
-     * - decoding: May be set by the user before opening the decoder if known e.g.
-     *             from the container. The decoder can change this value.
+     * Audio sample rate.
+     *
+     * Samples per second.
+     *
+     * Direct mapping to AVCodecContext->sample_rate.
      */
     get sampleRate() {
         return this.native.sampleRate;
@@ -412,7 +398,8 @@ export class CodecContext extends OptionMember {
     }
     /**
      * Number of audio channels.
-     * @deprecated use ch_layout.nb_channels
+     *
+     * Direct mapping to AVCodecContext->channels.
      */
     get channels() {
         return this.native.channels;
@@ -422,8 +409,10 @@ export class CodecContext extends OptionMember {
     }
     /**
      * Audio sample format.
-     * - encoding: Set by user.
-     * - decoding: Set by libavcodec.
+     *
+     * Format of audio samples.
+     *
+     * Direct mapping to AVCodecContext->sample_fmt.
      */
     get sampleFormat() {
         return this.native.sampleFormat;
@@ -432,12 +421,9 @@ export class CodecContext extends OptionMember {
         this.native.sampleFormat = value;
     }
     /**
-     * Number of samples per channel in an audio frame.
-     * - encoding: Set by libavcodec in avcodec_open2(). Each submitted frame
-     *   except the last must contain exactly frame_size samples per channel.
-     *   May be 0 when the codec has AV_CODEC_CAP_VARIABLE_FRAME_SIZE set, then the
-     *   frame size is not restricted.
-     * - decoding: May be set by some decoders to indicate constant frame size.
+     * Number of samples per audio frame.
+     *
+     * Direct mapping to AVCodecContext->frame_size.
      */
     get frameSize() {
         return this.native.frameSize;
@@ -446,19 +432,21 @@ export class CodecContext extends OptionMember {
         this.native.frameSize = value;
     }
     /**
-     * Frame counter, set by libavcodec.
-     * - decoding: Total number of frames returned from the decoder so far.
-     * - encoding: Total number of frames passed to the encoder so far.
-     * @readonly
+     * Current frame number.
+     *
+     * Frame counter for debugging.
+     *
+     * Direct mapping to AVCodecContext->frame_number.
      */
     get frameNumber() {
         return this.native.frameNumber;
     }
     /**
      * Audio channel layout.
-     * - encoding: Set by user.
-     * - decoding: Set by user, may be overwritten by libavcodec.
-     * @deprecated use ch_layout
+     *
+     * Describes channel configuration.
+     *
+     * Direct mapping to AVCodecContext->ch_layout.
      */
     get channelLayout() {
         return this.native.channelLayout;
@@ -468,8 +456,10 @@ export class CodecContext extends OptionMember {
     }
     /**
      * Minimum quantizer.
-     * - encoding: Set by user.
-     * - decoding: unused
+     *
+     * Minimum quantization parameter.
+     *
+     * Direct mapping to AVCodecContext->qmin.
      */
     get qMin() {
         return this.native.qMin;
@@ -479,8 +469,10 @@ export class CodecContext extends OptionMember {
     }
     /**
      * Maximum quantizer.
-     * - encoding: Set by user.
-     * - decoding: unused
+     *
+     * Maximum quantization parameter.
+     *
+     * Direct mapping to AVCodecContext->qmax.
      */
     get qMax() {
         return this.native.qMax;
@@ -489,9 +481,11 @@ export class CodecContext extends OptionMember {
         this.native.qMax = value;
     }
     /**
+     * Rate control buffer size.
+     *
      * Decoder bitstream buffer size.
-     * - encoding: Set by user.
-     * - decoding: unused
+     *
+     * Direct mapping to AVCodecContext->rc_buffer_size.
      */
     get rcBufferSize() {
         return this.native.rcBufferSize;
@@ -501,8 +495,10 @@ export class CodecContext extends OptionMember {
     }
     /**
      * Maximum bitrate.
-     * - encoding: Set by user.
-     * - decoding: Set by user, may be overwritten by libavcodec.
+     *
+     * Maximum bitrate in bits per second.
+     *
+     * Direct mapping to AVCodecContext->rc_max_rate.
      */
     get rcMaxRate() {
         return this.native.rcMaxRate;
@@ -512,8 +508,10 @@ export class CodecContext extends OptionMember {
     }
     /**
      * Minimum bitrate.
-     * - encoding: Set by user.
-     * - decoding: unused
+     *
+     * Minimum bitrate in bits per second.
+     *
+     * Direct mapping to AVCodecContext->rc_min_rate.
      */
     get rcMinRate() {
         return this.native.rcMinRate;
@@ -521,14 +519,12 @@ export class CodecContext extends OptionMember {
     set rcMinRate(value) {
         this.native.rcMinRate = value;
     }
-    // Hardware Acceleration
     /**
-     * Hardware device context for hardware acceleration.
+     * Hardware device context.
      *
-     * Direct mapping to AVCodecContext->hw_device_ctx
+     * Reference to hardware device for acceleration.
      *
-     * If the codec supports hardware acceleration, this should be set
-     * to the hardware device context before opening the codec.
+     * Direct mapping to AVCodecContext->hw_device_ctx.
      */
     get hwDeviceCtx() {
         const native = this.native.hwDeviceCtx;
@@ -553,13 +549,11 @@ export class CodecContext extends OptionMember {
         this._hwDeviceCtx = undefined;
     }
     /**
-     * Hardware frames context for hardware acceleration.
+     * Hardware frames context.
      *
-     * Direct mapping to AVCodecContext->hw_frames_ctx
+     * Reference to hardware frames for GPU memory.
      *
-     * For decoders, this is an optional field that the decoder can set
-     * to provide the caller with hardware frames. For encoders, this
-     * must be set by the caller before opening the encoder.
+     * Direct mapping to AVCodecContext->hw_frames_ctx.
      */
     get hwFramesCtx() {
         const native = this.native.hwFramesCtx;
@@ -584,38 +578,29 @@ export class CodecContext extends OptionMember {
         this._hwFramesCtx = undefined;
     }
     /**
-     * Check if the codec context is open.
-     *
-     * Direct mapping to avcodec_is_open()
+     * Check if codec is open.
      *
-     * @returns true if the codec is open and ready for encoding/decoding
+     * True if the codec has been opened.
      */
     get isOpen() {
         return this.native.isOpen;
     }
     /**
-     * Allocate an AVCodecContext and set its fields to default values.
-     *
-     * Allocates the codec context and initializes with codec-specific defaults.
-     * Must be called before using the context.
+     * Allocate codec context.
      *
-     * Direct mapping to avcodec_alloc_context3()
+     * Allocates and initializes the context for the given codec.
      *
-     * @param codec - If non-NULL, allocate private data and initialize defaults
-     *                for the given codec. It is illegal to then call open2()
-     *                with a different codec.
+     * Direct mapping to avcodec_alloc_context3().
      *
-     * @throws {Error} Memory allocation failure (ENOMEM)
+     * @param codec - Codec to use (null for default)
      *
      * @example
      * ```typescript
-     * import { CodecContext, Codec } from 'node-av';
+     * import { Codec } from 'node-av';
      * import { AV_CODEC_ID_H264 } from 'node-av/constants';
      *
      * const codec = Codec.findDecoder(AV_CODEC_ID_H264);
-     * const ctx = new CodecContext();
      * ctx.allocContext3(codec);
-     * // Context is now allocated with H264 defaults
      * ```
      *
      * @see {@link open2} To open the codec
@@ -625,329 +610,278 @@ export class CodecContext extends OptionMember {
         this.native.allocContext3(codec?.getNative() ?? null);
     }
     /**
-     * Free the codec context and everything associated with it.
+     * Free the codec context.
      *
-     * Releases all resources associated with the codec context.
-     * The context becomes invalid after this call.
+     * Releases all resources. The context becomes invalid.
      *
-     * Direct mapping to avcodec_free_context()
+     * Direct mapping to avcodec_free_context().
      *
      * @example
      * ```typescript
      * ctx.freeContext();
-     * // ctx is now invalid and should not be used
+     * // Context is now invalid
      * ```
+     *
+     * @see {@link Symbol.dispose} For automatic cleanup
+     * @see {@link allocContext3} To allocate a new context
      */
     freeContext() {
         this.native.freeContext();
     }
     /**
-     * Initialize the AVCodecContext to use the given AVCodec.
-     *
-     * Opens the codec and prepares it for encoding or decoding.
-     * Prior to using this function the context has to be allocated with allocContext3().
+     * Open the codec.
      *
-     * Direct mapping to avcodec_open2()
+     * Initializes the codec for encoding/decoding.
+     * Must be called before processing frames/packets.
      *
-     * @param codec - The codec to open this context for. If a non-NULL codec has been
-     *                previously passed to allocContext3() for this context, then this
-     *                parameter MUST be either NULL or equal to the previously passed codec.
-     * @param options - A dictionary filled with AVCodecContext and codec-private options.
+     * Direct mapping to avcodec_open2().
      *
+     * @param codec - Codec to open with (null to use already set)
+     * @param options - Codec-specific options
      * @returns 0 on success, negative AVERROR on error:
-     *   - 0: Success
-     *   - AVERROR(EINVAL): Invalid parameters or codec not found
-     *   - AVERROR(ENOMEM): Memory allocation failure
-     *   - <0: Other codec-specific errors
+     *   - AVERROR_EINVAL: Invalid parameters
+     *   - AVERROR_ENOMEM: Memory allocation failure
      *
      * @example
      * ```typescript
      * import { FFmpegError } from 'node-av';
      *
-     * const ret = await ctx.open2(codec, null);
+     * const ret = await ctx.open2(codec);
      * FFmpegError.throwIfError(ret, 'open2');
+     * // Codec is now open and ready
      * ```
      *
-     * @see {@link close} To close the codec context
-     * @see {@link allocContext3} Must be called before open2()
+     * @see {@link allocContext3} Must be called first
+     * @see {@link isOpen} To check if open
      */
     async open2(codec = null, options = null) {
         return await this.native.open2(codec?.getNative() ?? null, options?.getNative() ?? null);
     }
     /**
-     * Fill the codec context based on the values from the supplied codec parameters.
+     * Fill codec context from parameters.
      *
-     * Direct mapping to avcodec_parameters_to_context()
+     * Copies codec parameters from stream to context.
+     * Used when setting up decoders.
      *
-     * @param params - Codec parameters to copy from
+     * Direct mapping to avcodec_parameters_to_context().
      *
+     * @param params - Source codec parameters
      * @returns 0 on success, negative AVERROR on error:
-     *   - 0: Success
-     *   - AVERROR(EINVAL): Invalid parameters
-     *   - <0: Other errors
+     *   - AVERROR_EINVAL: Invalid parameters
      *
      * @example
      * ```typescript
-     * // Copy parameters from stream to codec context
+     * import { FFmpegError } from 'node-av';
+     *
      * const ret = ctx.parametersToContext(stream.codecpar);
-     * if (ret < 0) {
-     *   throw new FFmpegError(ret);
-     * }
+     * FFmpegError.throwIfError(ret, 'parametersToContext');
      * ```
      *
-     * @see parametersFromContext() - To copy in the opposite direction
+     * @see {@link parametersFromContext} For the reverse
      */
     parametersToContext(params) {
         return this.native.parametersToContext(params.getNative());
     }
     /**
-     * Fill the parameters struct based on the values from the supplied codec context.
+     * Fill parameters from codec context.
      *
-     * Direct mapping to avcodec_parameters_from_context()
+     * Copies codec parameters from context to stream.
+     * Used when setting up encoders.
      *
-     * @param params - Codec parameters to fill
+     * Direct mapping to avcodec_parameters_from_context().
      *
+     * @param params - Destination codec parameters
      * @returns 0 on success, negative AVERROR on error:
-     *   - 0: Success
-     *   - AVERROR(EINVAL): Invalid parameters
-     *   - <0: Other errors
+     *   - AVERROR_EINVAL: Invalid parameters
      *
      * @example
      * ```typescript
-     * // Copy parameters from codec context to stream
-     * const ret = ctx.parametersFromContext(outputStream.codecpar);
-     * if (ret < 0) {
-     *   throw new FFmpegError(ret);
-     * }
+     * import { FFmpegError } from 'node-av';
+     *
+     * const ret = ctx.parametersFromContext(stream.codecpar);
+     * FFmpegError.throwIfError(ret, 'parametersFromContext');
      * ```
      *
-     * @see parametersToContext() - To copy in the opposite direction
+     * @see {@link parametersToContext} For the reverse
      */
     parametersFromContext(params) {
         return this.native.parametersFromContext(params.getNative());
     }
     /**
-     * Reset the internal codec state / flush internal buffers.
-     * Should be called when seeking or switching to a different stream.
+     * Flush codec buffers.
+     *
+     * Resets the internal codec state.
+     * Used when seeking or switching streams.
      *
-     * Direct mapping to avcodec_flush_buffers()
+     * Direct mapping to avcodec_flush_buffers().
      *
      * @example
      * ```typescript
-     * // Flush buffers when seeking
-     * formatContext.seekFrame(streamIndex, timestamp, flags);
-     * codecContext.flushBuffers();
+     * // Flush when seeking
+     * ctx.flushBuffers();
+     * // Codec is now ready for new data
      * ```
      */
     flushBuffers() {
         this.native.flushBuffers();
     }
     /**
-     * Supply raw packet data as input to a decoder.
-     *
-     * Sends compressed data to the decoder for processing.
-     * The decoder may buffer the packet internally.
+     * Send packet to decoder.
      *
-     * Direct mapping to avcodec_send_packet()
+     * Submits encoded data for decoding.
+     * Call receiveFrame() to get decoded frames.
      *
-     * @param packet - The input packet. May be NULL to signal end of stream (flush).
+     * Direct mapping to avcodec_send_packet().
      *
+     * @param packet - Packet to decode (null to flush)
      * @returns 0 on success, negative AVERROR on error:
-     *   - 0: Success
-     *   - AVERROR(EAGAIN): Input not accepted - must read output with receiveFrame() first
-     *   - AVERROR_EOF: Decoder has been flushed, no new packets can be sent
-     *   - AVERROR(EINVAL): Codec not opened, is an encoder, or requires flush
-     *   - AVERROR(ENOMEM): Failed to add packet to internal queue
-     *   - <0: Other legitimate decoding errors
+     *   - AVERROR_EAGAIN: Must receive frames first
+     *   - AVERROR_EOF: Decoder has been flushed
+     *   - AVERROR_EINVAL: Invalid decoder state
+     *   - AVERROR_ENOMEM: Memory allocation failure
      *
      * @example
      * ```typescript
-     * import { FFmpegError, Frame } from 'node-av';
-     * import { AVERROR_EAGAIN } from 'node-av/constants';
+     * import { FFmpegError } from 'node-av';
+     * import { AVERROR_EAGAIN } from 'node-av';
      *
-     * // Decode packet
-     * const ret = await decoder.sendPacket(packet);
+     * const ret = await ctx.sendPacket(packet);
      * if (ret === AVERROR_EAGAIN) {
-     *   // Need to read output first
-     *   const frame = new Frame();
-     *   frame.alloc();
-     *   const recvRet = await decoder.receiveFrame(frame);
-     *   FFmpegError.throwIfError(recvRet, 'receiveFrame');
+     *   // Need to receive frames first
      * } else {
      *   FFmpegError.throwIfError(ret, 'sendPacket');
      * }
      * ```
      *
-     * @see {@link receiveFrame} To retrieve decoded frames
+     * @see {@link receiveFrame} To get decoded frames
      */
     async sendPacket(packet) {
         return await this.native.sendPacket(packet?.getNative() ?? null);
     }
     /**
-     * Return decoded output data from a decoder.
-     *
-     * Retrieves decoded frames from the decoder.
-     * The frame must be allocated before calling this function.
+     * Receive decoded frame.
      *
-     * Direct mapping to avcodec_receive_frame()
+     * Gets a decoded frame from the decoder.
+     * Call after sendPacket().
      *
-     * @param frame - Frame to receive decoded data. Must be allocated.
+     * Direct mapping to avcodec_receive_frame().
      *
+     * @param frame - Frame to receive into
      * @returns 0 on success, negative AVERROR on error:
-     *   - 0: Success, a frame was returned
-     *   - AVERROR(EAGAIN): Output not available, must send new input
-     *   - AVERROR_EOF: Decoder fully flushed, no more frames
-     *   - AVERROR(EINVAL): Codec not opened or is an encoder
-     *   - <0: Other legitimate decoding errors
+     *   - AVERROR_EAGAIN: Need more input
+     *   - AVERROR_EOF: All frames have been output
+     *   - AVERROR_EINVAL: Invalid decoder state
      *
      * @example
      * ```typescript
-     * import { Frame, FFmpegError } from 'node-av';
-     * import { AVERROR_EAGAIN, AVERROR_EOF } from 'node-av/constants';
-     *
-     * // Receive all frames from decoder
-     * const frame = new Frame();
-     * frame.alloc();
-     *
-     * while (true) {
-     *   const ret = await decoder.receiveFrame(frame);
-     *   if (ret === AVERROR_EAGAIN || ret === AVERROR_EOF) {
-     *     break;
-     *   }
-     *   FFmpegError.throwIfError(ret, 'receiveFrame');
+     * import { FFmpegError } from 'node-av';
+     * import { AVERROR_EAGAIN, AVERROR_EOF } from 'node-av';
      *
-     *   // Process frame
-     *   processFrame(frame);
-     *   frame.unref();
+     * const ret = await ctx.receiveFrame(frame);
+     * if (ret === AVERROR_EAGAIN || ret === AVERROR_EOF) {
+     *   // No frame available
+     * } else {
+     *   FFmpegError.throwIfError(ret, 'receiveFrame');
+     *   // Process decoded frame
      * }
      * ```
      *
-     * @see {@link sendPacket} To send input packets
+     * @see {@link sendPacket} To send packets for decoding
      */
     async receiveFrame(frame) {
         return await this.native.receiveFrame(frame.getNative());
     }
     /**
-     * Supply a raw video or audio frame to the encoder.
+     * Send frame to encoder.
      *
-     * Sends uncompressed frame data to the encoder.
-     * Use receivePacket() to retrieve buffered output packets.
+     * Submits raw frame for encoding.
+     * Call receivePacket() to get encoded packets.
      *
-     * Direct mapping to avcodec_send_frame()
-     *
-     * @param frame - AVFrame containing the raw audio or video frame to be encoded.
-     *                Can be NULL for flush packet (signals end of stream).
+     * Direct mapping to avcodec_send_frame().
      *
+     * @param frame - Frame to encode (null to flush)
      * @returns 0 on success, negative AVERROR on error:
-     *   - 0: Success
-     *   - AVERROR(EAGAIN): Input not accepted - must read output with receivePacket()
-     *   - AVERROR_EOF: Encoder has been flushed, no new frames can be sent
-     *   - AVERROR(EINVAL): Codec not opened, is a decoder, or requires flush
-     *   - AVERROR(ENOMEM): Failed to add packet to internal queue
-     *   - <0: Other legitimate encoding errors
+     *   - AVERROR_EAGAIN: Must receive packets first
+     *   - AVERROR_EOF: Encoder has been flushed
+     *   - AVERROR_EINVAL: Invalid encoder state
+     *   - AVERROR_ENOMEM: Memory allocation failure
      *
      * @example
      * ```typescript
-     * import { Packet, FFmpegError } from 'node-av';
-     * import { AVERROR_EAGAIN } from 'node-av/constants';
+     * import { FFmpegError } from 'node-av';
+     * import { AVERROR_EAGAIN } from 'node-av';
      *
-     * // Send frame to encoder
-     * const ret = await encoder.sendFrame(frame);
+     * const ret = await ctx.sendFrame(frame);
      * if (ret === AVERROR_EAGAIN) {
-     *   // Need to read output first
-     *   const packet = new Packet();
-     *   packet.alloc();
-     *   const recvRet = await encoder.receivePacket(packet);
-     *   FFmpegError.throwIfError(recvRet, 'receivePacket');
+     *   // Need to receive packets first
      * } else {
      *   FFmpegError.throwIfError(ret, 'sendFrame');
      * }
      * ```
      *
-     * @see {@link receivePacket} To retrieve encoded packets
-     *
-     * @note For audio: If AV_CODEC_CAP_VARIABLE_FRAME_SIZE is set, then each frame
-     * can have any number of samples. If not set, frame.nbSamples must equal
-     * avctx.frameSize for all frames except the last.
+     * @see {@link receivePacket} To get encoded packets
      */
     async sendFrame(frame) {
         return await this.native.sendFrame(frame?.getNative() ?? null);
     }
     /**
-     * Read encoded data from the encoder.
+     * Receive encoded packet.
      *
-     * Retrieves compressed packets from the encoder.
-     * The packet must be allocated before calling.
+     * Gets an encoded packet from the encoder.
+     * Call after sendFrame().
      *
-     * Direct mapping to avcodec_receive_packet()
-     *
-     * @param packet - Packet to receive encoded data. Must be allocated.
+     * Direct mapping to avcodec_receive_packet().
      *
+     * @param packet - Packet to receive into
      * @returns 0 on success, negative AVERROR on error:
-     *   - 0: Success, a packet was returned
-     *   - AVERROR(EAGAIN): Output not available, must send new input
-     *   - AVERROR_EOF: Encoder fully flushed, no more packets
-     *   - AVERROR(EINVAL): Codec not opened or is a decoder
-     *   - <0: Other legitimate encoding errors
+     *   - AVERROR_EAGAIN: Need more input
+     *   - AVERROR_EOF: All packets have been output
+     *   - AVERROR_EINVAL: Invalid encoder state
      *
      * @example
      * ```typescript
-     * import { Packet, FFmpegError } from 'node-av';
-     * import { AVERROR_EAGAIN, AVERROR_EOF } from 'node-av/constants';
-     *
-     * // Receive all packets from encoder
-     * const packet = new Packet();
-     * packet.alloc();
-     *
-     * while (true) {
-     *   const ret = await encoder.receivePacket(packet);
-     *   if (ret === AVERROR_EAGAIN || ret === AVERROR_EOF) {
-     *     break;
-     *   }
-     *   if (ret < 0) {
-     *     throw new FFmpegError(ret);
-     *   }
-     *   // Write packet to output
-     *   await formatContext.writeFrame(packet);
-     *   packet.unref();
+     * import { FFmpegError } from 'node-av';
+     * import { AVERROR_EAGAIN, AVERROR_EOF } from 'node-av';
+     *
+     * const ret = await ctx.receivePacket(packet);
+     * if (ret === AVERROR_EAGAIN || ret === AVERROR_EOF) {
+     *   // No packet available
+     * } else {
+     *   FFmpegError.throwIfError(ret, 'receivePacket');
+     *   // Process encoded packet
      * }
      * ```
      *
-     * @see sendFrame() - To send input frames
+     * @see {@link sendFrame} To send frames for encoding
      */
     async receivePacket(packet) {
         return await this.native.receivePacket(packet.getNative());
     }
     /**
-     * Set the hardware pixel format for hardware acceleration.
+     * Set hardware pixel format.
      *
-     * This configures the codec context to prefer a specific hardware pixel format
-     * when negotiating formats with FFmpeg. Optionally, a software fallback format
-     * can be specified.
+     * Configures hardware acceleration pixel formats.
+     * Used in get_format callback for hardware decoding.
      *
-     * @param hwFormat - The preferred hardware pixel format (e.g., AV_PIX_FMT_VIDEOTOOLBOX)
-     * @param swFormat - Optional software fallback format if hardware format is not available
+     * @param hwFormat - Hardware pixel format
+     * @param swFormat - Software pixel format (optional)
      *
      * @example
      * ```typescript
-     * // For VideoToolbox hardware decoding on macOS
-     * codecContext.setHardwarePixelFormat(AV_PIX_FMT_VIDEOTOOLBOX);
-     *
-     * // With software fallback
-     * codecContext.setHardwarePixelFormat(
-     *   AV_PIX_FMT_VIDEOTOOLBOX,
-     *   AV_PIX_FMT_YUV420P // Fallback to YUV420P if hardware not available
-     * );
+     * import { AV_PIX_FMT_CUDA, AV_PIX_FMT_NV12 } from 'node-av/constants';
+     *
+     * ctx.setHardwarePixelFormat(AV_PIX_FMT_CUDA, AV_PIX_FMT_NV12);
      * ```
      */
     setHardwarePixelFormat(hwFormat, swFormat) {
         this.native.setHardwarePixelFormat(hwFormat, swFormat);
     }
     /**
-     * Get the native FFmpeg AVCodecContext pointer.
+     * Get the underlying native CodecContext object.
+     *
+     * @returns The native CodecContext binding object
      *
-     * @internal For use by other wrapper classes
-     * @returns The underlying native codec context object
+     * @internal
      */
     getNative() {
         return this.native;
@@ -963,7 +897,8 @@ export class CodecContext extends OptionMember {
      * {
      *   using ctx = new CodecContext();
      *   ctx.allocContext3(codec);
-     *   // ... use context
+     *   await ctx.open2();
+     *   // Use context...
      * } // Automatically freed when leaving scope
      * ```
      */