node-av 1.1.0 → 1.3.0

package/dist/lib/utilities.js

@@ -1,155 +1,272 @@
-/**
- * FFmpeg utility functions collection.
- *
- * Provides direct mappings to various FFmpeg utility functions from libavutil.
- * These functions handle common operations like timestamp conversion, image buffer
- * allocation, sample format queries, and more.
- *
- * @example
- * ```typescript
- * import { avImageAlloc, avTs2TimeStr, avRescaleQ, FFmpegError } from 'node-av';
- * import { AV_PIX_FMT_YUV420P, IRational } from 'node-av';
- *
- * // Allocate image buffer
- * const image = avImageAlloc(1920, 1080, AV_PIX_FMT_YUV420P, 32);
- * console.log(`Allocated ${image.size} bytes`);
- *
- * // Convert timestamp to readable time
- * const timebase: IRational = { num: 1, den: 90000 };
- * const pts = 450000n;
- * console.log(avTs2TimeStr(pts, timebase)); // "5.000000"
- * ```
- */
 import { bindings } from './binding.js';
 import { FFmpegError } from './error.js';
 /**
- * Get bytes per sample for a sample format.
+ * Get bytes per audio sample.
  *
- * Returns the number of bytes required to store one sample in the given format.
+ * Returns the number of bytes required to store a single audio sample
+ * in the specified format.
  *
- * Direct mapping to av_get_bytes_per_sample()
+ * Direct mapping to av_get_bytes_per_sample().
  *
  * @param sampleFmt - Audio sample format
- *
- * @returns Number of bytes per sample, or 0 for invalid format
+ * @returns Number of bytes per sample, or 0 if unknown format
  *
  * @example
  * ```typescript
- * import { avGetBytesPerSample, AV_SAMPLE_FMT_S16, AV_SAMPLE_FMT_FLT } from 'node-av';
+ * import { AV_SAMPLE_FMT_S16, AV_SAMPLE_FMT_FLTP } from 'node-av/constants';
  *
- * console.log(avGetBytesPerSample(AV_SAMPLE_FMT_S16)); // 2
- * console.log(avGetBytesPerSample(AV_SAMPLE_FMT_FLT)); // 4
+ * const bytesS16 = avGetBytesPerSample(AV_SAMPLE_FMT_S16);  // Returns 2
+ * const bytesFloat = avGetBytesPerSample(AV_SAMPLE_FMT_FLTP); // Returns 4
  * ```
+ *
+ * @see [av_get_bytes_per_sample](https://ffmpeg.org/doxygen/7.1/group__lavu__sampfmts.html#ga0c3c218e1dd570ad4917c69a35a6c77d) - FFmpeg Doxygen
  */
 export function avGetBytesPerSample(sampleFmt) {
     return bindings.avGetBytesPerSample(sampleFmt);
 }
 /**
- * Get the name of a sample format.
+ * Get sample format name.
  *
- * Returns a string describing the sample format.
+ * Returns the name of the audio sample format as a string.
  *
- * Direct mapping to av_get_sample_fmt_name()
+ * Direct mapping to av_get_sample_fmt_name().
  *
  * @param sampleFmt - Audio sample format
- *
- * @returns Format name string, or null for invalid format
+ * @returns Format name, or null if unknown
  *
  * @example
  * ```typescript
- * import { avGetSampleFmtName, AV_SAMPLE_FMT_S16, AV_SAMPLE_FMT_FLTP } from 'node-av';
+ * import { AV_SAMPLE_FMT_S16, AV_SAMPLE_FMT_FLTP } from 'node-av/constants';
  *
- * console.log(avGetSampleFmtName(AV_SAMPLE_FMT_S16)); // "s16"
- * console.log(avGetSampleFmtName(AV_SAMPLE_FMT_FLTP)); // "fltp"
+ * const name1 = avGetSampleFmtName(AV_SAMPLE_FMT_S16);  // Returns "s16"
+ * const name2 = avGetSampleFmtName(AV_SAMPLE_FMT_FLTP); // Returns "fltp"
  * ```
+ *
+ * @see [av_get_sample_fmt_name](https://ffmpeg.org/doxygen/7.1/group__lavu__sampfmts.html#ga31b9d149b2de9821a65f4f5612970838) - FFmpeg Doxygen
  */
 export function avGetSampleFmtName(sampleFmt) {
     return bindings.avGetSampleFmtName(sampleFmt);
 }
 /**
- * Get packed sample format
- * Direct mapping to av_get_packed_sample_fmt()
+ * Get packed sample format.
+ *
+ * Returns the packed (interleaved) version of a planar sample format,
+ * or the format itself if already packed.
+ *
+ * Direct mapping to av_get_packed_sample_fmt().
+ *
+ * @param sampleFmt - Audio sample format
+ * @returns Packed version of the format
+ *
+ * @example
+ * ```typescript
+ * import { AV_SAMPLE_FMT_FLTP, AV_SAMPLE_FMT_FLT } from 'node-av/constants';
+ *
+ * const packed = avGetPackedSampleFmt(AV_SAMPLE_FMT_FLTP); // Returns AV_SAMPLE_FMT_FLT
+ * const same = avGetPackedSampleFmt(AV_SAMPLE_FMT_FLT);    // Returns AV_SAMPLE_FMT_FLT
+ * ```
+ *
+ * @see [av_get_packed_sample_fmt](https://ffmpeg.org/doxygen/7.1/group__lavu__sampfmts.html#ga7817ec0eff4dc6fc0962f31e6d138bca) - FFmpeg Doxygen
+ * @see {@link avGetPlanarSampleFmt} For getting planar version
  */
 export function avGetPackedSampleFmt(sampleFmt) {
     return bindings.avGetPackedSampleFmt(sampleFmt);
 }
 /**
- * Get planar sample format
- * Direct mapping to av_get_planar_sample_fmt()
+ * Get planar sample format.
+ *
+ * Returns the planar (non-interleaved) version of a packed sample format,
+ * or the format itself if already planar.
+ *
+ * Direct mapping to av_get_planar_sample_fmt().
+ *
+ * @param sampleFmt - Audio sample format
+ * @returns Planar version of the format
+ *
+ * @example
+ * ```typescript
+ * import { AV_SAMPLE_FMT_FLT, AV_SAMPLE_FMT_FLTP } from 'node-av/constants';
+ *
+ * const planar = avGetPlanarSampleFmt(AV_SAMPLE_FMT_FLT);   // Returns AV_SAMPLE_FMT_FLTP
+ * const same = avGetPlanarSampleFmt(AV_SAMPLE_FMT_FLTP);    // Returns AV_SAMPLE_FMT_FLTP
+ * ```
+ *
+ * @see [av_get_planar_sample_fmt](https://ffmpeg.org/doxygen/7.1/group__lavu__sampfmts.html#ga82caf838259d95cc6c4fd87633bb0e19) - FFmpeg Doxygen
+ * @see {@link avGetPackedSampleFmt} For getting packed version
  */
 export function avGetPlanarSampleFmt(sampleFmt) {
     return bindings.avGetPlanarSampleFmt(sampleFmt);
 }
 /**
- * Check if sample format is planar
- * Direct mapping to av_sample_fmt_is_planar()
+ * Check if sample format is planar.
+ *
+ * Returns whether the audio sample format stores channels in separate planes
+ * (planar) rather than interleaved.
+ *
+ * Direct mapping to av_sample_fmt_is_planar().
+ *
+ * @param sampleFmt - Audio sample format to check
+ * @returns True if planar, false if packed/interleaved
+ *
+ * @example
+ * ```typescript
+ * import { AV_SAMPLE_FMT_S16, AV_SAMPLE_FMT_S16P } from 'node-av/constants';
+ *
+ * const isPacked = avSampleFmtIsPlanar(AV_SAMPLE_FMT_S16);  // Returns false
+ * const isPlanar = avSampleFmtIsPlanar(AV_SAMPLE_FMT_S16P); // Returns true
+ * ```
+ *
+ * @see [av_sample_fmt_is_planar](https://ffmpeg.org/doxygen/7.1/group__lavu__sampfmts.html#ga06ba8a64dc4382c422789a5d0b6bf592) - FFmpeg Doxygen
  */
 export function avSampleFmtIsPlanar(sampleFmt) {
     return bindings.avSampleFmtIsPlanar(sampleFmt);
 }
 /**
- * Get pixel format name
- * Direct mapping to av_get_pix_fmt_name()
+ * Get codec name from codec ID.
+ *
+ * Returns the canonical codec name corresponding to the codec ID.
+ *
+ * Direct mapping to avcodec_get_name().
+ *
+ * @param codecId - Codec ID from AVCodecID enum
+ * @returns Codec name string or null
+ *
+ * @example
+ * ```typescript
+ * import { AV_CODEC_ID_H264, AV_CODEC_ID_HEVC } from 'node-av/constants';
+ * import { avGetCodecName } from 'node-av/lib';
+ *
+ * const h264Name = avGetCodecName(AV_CODEC_ID_H264);  // Returns "h264"
+ * const hevcName = avGetCodecName(AV_CODEC_ID_HEVC);  // Returns "hevc"
+ * const unknownName = avGetCodecName(99999);          // Returns null
+ * ```
+ *
+ * @see [avcodec_get_name](https://ffmpeg.org/doxygen/7.1/group__lavc__core.html#ga2016a52e94f867ebe5113bdf448e182d) - FFmpeg Doxygen
+ */
+export function avGetCodecName(codecId) {
+    return bindings.avGetCodecName(codecId);
+}
+/**
+ * Get pixel format name.
+ *
+ * Returns the name of the pixel format as a string.
+ *
+ * Direct mapping to av_get_pix_fmt_name().
+ *
+ * @param pixFmt - Pixel format
+ * @returns Format name, or null if unknown
+ *
+ * @example
+ * ```typescript
+ * import { AV_PIX_FMT_YUV420P, AV_PIX_FMT_RGB24 } from 'node-av/constants';
+ *
+ * const name1 = avGetPixFmtName(AV_PIX_FMT_YUV420P); // Returns "yuv420p"
+ * const name2 = avGetPixFmtName(AV_PIX_FMT_RGB24);   // Returns "rgb24"
+ * ```
+ *
+ * @see [av_get_pix_fmt_name](https://ffmpeg.org/doxygen/7.1/pixdesc_8c.html#ab92e2a8a9b58c982560c49df9f01e47e) - FFmpeg Doxygen
  */
 export function avGetPixFmtName(pixFmt) {
     return bindings.avGetPixFmtName(pixFmt);
 }
 /**
- * Get pixel format from name
- * Direct mapping to av_get_pix_fmt()
+ * Get pixel format from name.
+ *
+ * Returns the pixel format enum value from its string name.
+ *
+ * Direct mapping to av_get_pix_fmt().
+ *
+ * @param name - Pixel format name
+ * @returns Pixel format enum, or AV_PIX_FMT_NONE if unknown
+ *
+ * @example
+ * ```typescript
+ * const fmt1 = avGetPixFmtFromName("yuv420p"); // Returns AV_PIX_FMT_YUV420P
+ * const fmt2 = avGetPixFmtFromName("rgb24");   // Returns AV_PIX_FMT_RGB24
+ * const none = avGetPixFmtFromName("invalid"); // Returns AV_PIX_FMT_NONE
+ * ```
+ *
+ * @see [av_get_pix_fmt](https://ffmpeg.org/doxygen/7.1/pixdesc_8h.html#a925ef18d69c24c3be8c53d5a7dc0660e) - FFmpeg Doxygen
  */
 export function avGetPixFmtFromName(name) {
     return bindings.avGetPixFmtFromName(name);
 }
 /**
- * Check if a pixel format is hardware-accelerated
- * Direct mapping using av_pix_fmt_desc_get() and AV_PIX_FMT_FLAG_HWACCEL
+ * Check if pixel format is hardware accelerated.
+ *
+ * Returns whether the pixel format represents hardware-accelerated frames
+ * (GPU memory) rather than software frames (system memory).
+ *
+ * Direct mapping to av_pix_fmt_desc_get() with hwaccel check.
+ *
+ * @param pixFmt - Pixel format to check
+ * @returns True if hardware format, false if software format
+ *
+ * @example
+ * ```typescript
+ * import { AV_PIX_FMT_YUV420P, AV_PIX_FMT_CUDA } from 'node-av/constants';
+ *
+ * const isSoftware = avIsHardwarePixelFormat(AV_PIX_FMT_YUV420P); // Returns false
+ * const isHardware = avIsHardwarePixelFormat(AV_PIX_FMT_CUDA);    // Returns true
+ * ```
+ *
+ * @see [av_pix_fmt_desc_get](https://ffmpeg.org/doxygen/7.1/pixdesc_8c.html#afe0c3e8aef5173de28bbdaea4298f5f0) - FFmpeg Doxygen
  */
 export function avIsHardwarePixelFormat(pixFmt) {
     return bindings.avIsHardwarePixelFormat(pixFmt);
 }
 /**
- * Get media type string
- * Direct mapping to av_get_media_type_string()
+ * Get media type string.
+ *
+ * Returns a human-readable string for the media type.
+ *
+ * Direct mapping to av_get_media_type_string().
+ *
+ * @param mediaType - Media type enum
+ * @returns Media type name, or null if unknown
+ *
+ * @example
+ * ```typescript
+ * import { AVMEDIA_TYPE_VIDEO, AVMEDIA_TYPE_AUDIO } from 'node-av/constants';
+ *
+ * const video = avGetMediaTypeString(AVMEDIA_TYPE_VIDEO); // Returns "video"
+ * const audio = avGetMediaTypeString(AVMEDIA_TYPE_AUDIO); // Returns "audio"
+ * ```
+ *
+ * @see [av_get_media_type_string](https://ffmpeg.org/doxygen/7.1/group__lavu__misc.html#gaf21645cfa855b2caf9699d7dc7b2d08e) - FFmpeg Doxygen
  */
 export function avGetMediaTypeString(mediaType) {
     return bindings.avGetMediaTypeString(mediaType);
 }
 /**
- * Allocate an image with size, pixel format and alignment.
+ * Allocate image buffer.
  *
- * Allocates a buffer large enough to hold an image with the given parameters.
- * The allocated buffer is properly aligned for optimal performance.
+ * Allocates a buffer large enough to hold an image with the specified dimensions
+ * and pixel format. Returns buffer and layout information.
  *
- * Direct mapping to av_image_alloc()
+ * Direct mapping to av_image_alloc().
  *
  * @param width - Image width in pixels
  * @param height - Image height in pixels
  * @param pixFmt - Pixel format
- * @param align - Buffer alignment (1 for no alignment, 32 for SIMD)
+ * @param align - Buffer alignment (typically 1 or 32)
+ * @returns Object with buffer, size, and line sizes
  *
- * @returns Object containing:
- *   - buffer: Allocated image buffer
- *   - size: Total size in bytes
- *   - linesizes: Array of line sizes for each plane
- *
- * @throws {Error} If allocation fails
+ * @throws {FFmpegError} If allocation fails
  *
  * @example
  * ```typescript
- * import { avImageAlloc, AV_PIX_FMT_YUV420P, FFmpegError } from 'node-av';
- *
- * try {
- *   const result = avImageAlloc(1920, 1080, AV_PIX_FMT_YUV420P, 32);
- *   console.log(`Allocated ${result.size} bytes`);
- *   console.log(`Y linesize: ${result.linesizes[0]}`);
- *   // Use result.buffer for image data
- * } catch (error) {
- *   console.error('Failed to allocate image buffer');
- * }
+ * import { AV_PIX_FMT_YUV420P } from 'node-av/constants';
+ *
+ * const { buffer, size, linesizes } = avImageAlloc(
+ *   1920, 1080, AV_PIX_FMT_YUV420P, 32
+ * );
+ * console.log(`Allocated ${size} bytes`);
+ * console.log(`Line sizes: ${linesizes}`);
  * ```
  *
- * @see {@link avImageGetBufferSize} To calculate required size without allocating
+ * @see [av_image_alloc](https://ffmpeg.org/doxygen/7.1/group__lavu__picture.html#ga841e0a89a642e24141af1918a2c10448) - FFmpeg Doxygen
+ * @see {@link avImageGetBufferSize} To calculate size without allocating
  */
 export function avImageAlloc(width, height, pixFmt, align) {
     const result = bindings.avImageAlloc(width, height, pixFmt, align);
@@ -160,86 +277,132 @@ export function avImageAlloc(width, height, pixFmt, align) {
     return result;
 }
 /**
- * Copy image data from src to dst
- * Direct mapping to av_image_copy2()
+ * Copy image data.
+ *
+ * Copies image data from source to destination buffers.
  *
- * @param dstData - Destination data buffers (one per plane)
- * @param dstLinesizes - Destination line sizes
- * @param srcData - Source data buffers (one per plane)
- * @param srcLinesizes - Source line sizes
+ * Direct mapping to av_image_copy2().
+ *
+ * @param dstData - Destination data planes
+ * @param dstLinesizes - Destination bytes per line
+ * @param srcData - Source data planes
+ * @param srcLinesizes - Source bytes per line
  * @param pixFmt - Pixel format
  * @param width - Image width
  * @param height - Image height
+ *
+ * @example
+ * ```typescript
+ * avImageCopy2(
+ *   dstPlanes, dstStrides,
+ *   srcPlanes, srcStrides,
+ *   AV_PIX_FMT_YUV420P, 1920, 1080
+ * );
+ * ```
+ *
+ * @see [av_image_copy2](https://ffmpeg.org/doxygen/7.1/group__lavu__picture.html#ga911cb7d723163b88bdbbdacbeeaacf2d) - FFmpeg Doxygen
  */
 export function avImageCopy2(dstData, dstLinesizes, srcData, srcLinesizes, pixFmt, width, height) {
     bindings.avImageCopy2(dstData, dstLinesizes, srcData, srcLinesizes, pixFmt, width, height);
 }
 /**
- * Get the required buffer size for an image
- * Direct mapping to av_image_get_buffer_size()
+ * Get image buffer size.
+ *
+ * Calculates the required buffer size for an image without allocating.
+ *
+ * Direct mapping to av_image_get_buffer_size().
+ *
+ * @param pixFmt - Pixel format
+ * @param width - Image width
+ * @param height - Image height
+ * @param align - Buffer alignment
+ * @returns Required buffer size in bytes
+ *
+ * @example
+ * ```typescript
+ * import { AV_PIX_FMT_RGB24 } from 'node-av/constants';
  *
- * @returns The required buffer size in bytes, or negative on error
+ * const size = avImageGetBufferSize(AV_PIX_FMT_RGB24, 1920, 1080, 1);
+ * console.log(`Need ${size} bytes for Full HD RGB24`);
+ * ```
+ *
+ * @see [av_image_get_buffer_size](https://ffmpeg.org/doxygen/7.1/group__lavu__picture.html#ga24a67963c3ae0054a2a4bab35930e694) - FFmpeg Doxygen
+ * @see {@link avImageAlloc} To allocate the buffer
  */
 export function avImageGetBufferSize(pixFmt, width, height, align) {
     return bindings.avImageGetBufferSize(pixFmt, width, height, align);
 }
 /**
- * Copy image data to a single buffer.
+ * Copy image to buffer.
  *
- * Copies image data from separate planes into a single continuous buffer.
- * Useful for serialization or when a single buffer is required.
+ * Copies image data from separate planes to a single contiguous buffer.
  *
- * Direct mapping to av_image_copy_to_buffer()
+ * Direct mapping to av_image_copy_to_buffer().
  *
  * @param dst - Destination buffer
- * @param dstSize - Size of destination buffer in bytes
- * @param srcData - Array of source data planes
- * @param srcLinesize - Array of source linesizes
+ * @param dstSize - Destination buffer size
+ * @param srcData - Source data planes
+ * @param srcLinesize - Source bytes per line
  * @param pixFmt - Pixel format
- * @param width - Image width in pixels
- * @param height - Image height in pixels
+ * @param width - Image width
+ * @param height - Image height
  * @param align - Buffer alignment
- *
- * @returns Number of bytes written to dst, or negative AVERROR on error:
- *   - >0: Number of bytes written
- *   - AVERROR(EINVAL): Invalid parameters
- *   - AVERROR(ENOMEM): Destination buffer too small
+ * @returns Bytes written, or negative AVERROR
  *
  * @example
  * ```typescript
- * import { avImageCopyToBuffer, avImageGetBufferSize, FFmpegError } from 'node-av';
- * import { AV_PIX_FMT_RGB24 } from 'node-av';
- *
- * const width = 640, height = 480;
- * const pixFmt = AV_PIX_FMT_RGB24;
- *
- * // Calculate required buffer size
- * const dstSize = avImageGetBufferSize(pixFmt, width, height, 1);
- * const dst = Buffer.alloc(dstSize);
- *
- * const ret = avImageCopyToBuffer(
- *   dst, dstSize,
- *   srcData, srcLinesize,
- *   pixFmt, width, height, 1
+ * const buffer = Buffer.alloc(bufferSize);
+ * const written = avImageCopyToBuffer(
+ *   buffer, bufferSize,
+ *   srcPlanes, srcStrides,
+ *   AV_PIX_FMT_YUV420P, 1920, 1080, 1
  * );
- *
- * FFmpegError.throwIfError(ret, 'avImageCopyToBuffer');
- * console.log(`Copied ${ret} bytes to buffer`);
  * ```
+ *
+ * @see [av_image_copy_to_buffer](https://ffmpeg.org/doxygen/7.1/group__lavu__picture.html#ga6f8576f1ef0c2d9a9f7c5ac7f9a28c52) - FFmpeg Doxygen
  */
 export function avImageCopyToBuffer(dst, dstSize, srcData, srcLinesize, pixFmt, width, height, align) {
     return bindings.avImageCopyToBuffer(dst, dstSize, srcData, srcLinesize, pixFmt, width, height, align);
 }
 /**
- * Convert timestamp to string
- * Direct mapping to av_ts2str()
+ * Convert timestamp to string.
+ *
+ * Converts a timestamp to a string representation.
+ *
+ * Direct mapping to av_ts2str().
+ *
+ * @param ts - Timestamp value
+ * @returns String representation
+ *
+ * @example
+ * ```typescript
+ * const str1 = avTs2Str(1234567n);  // Returns "1234567"
+ * const str2 = avTs2Str(null);      // Returns "NOPTS"
+ * ```
+ *
+ * @see [av_ts2str](https://ffmpeg.org/doxygen/7.1/timestamp_8h.html#a86d797e907fa454ed5fd34bfb0bcd747) - FFmpeg Doxygen
  */
 export function avTs2Str(ts) {
     return bindings.avTs2Str(ts);
 }
 /**
- * Convert timestamp to time string
- * Direct mapping to av_ts2timestr()
+ * Convert timestamp to time string.
+ *
+ * Converts a timestamp to a time string using the specified time base.
+ *
+ * Direct mapping to av_ts2timestr().
+ *
+ * @param ts - Timestamp value
+ * @param timeBase - Time base for conversion
+ * @returns Time string representation
+ *
+ * @example
+ * ```typescript
+ * const timeStr = avTs2TimeStr(90000n, { num: 1, den: 90000 }); // Returns "1.000000"
+ * const nopts = avTs2TimeStr(null, { num: 1, den: 1000 });      // Returns "NOPTS"
+ * ```
+ *
+ * @see [av_ts2timestr](https://ffmpeg.org/doxygen/7.1/timestamp_8h.html#ad344b91ede6b86fc0a530611293f42da) - FFmpeg Doxygen
  */
 export function avTs2TimeStr(ts, timeBase) {
     if (!timeBase) {
@@ -248,8 +411,23 @@ export function avTs2TimeStr(ts, timeBase) {
     return bindings.avTs2TimeStr(ts, timeBase);
 }
 /**
- * Helper to separate image allocation result into separate arrays
- * This is useful when you need separate data and linesize arrays
+ * Allocate image arrays.
+ *
+ * Allocates image data as separate plane arrays.
+ *
+ * @param width - Image width
+ * @param height - Image height
+ * @param pixFmt - Pixel format
+ * @param align - Buffer alignment
+ * @returns Object with data planes, line sizes, and total size
+ *
+ * @example
+ * ```typescript
+ * const { data, linesizes, size } = avImageAllocArrays(
+ *   1920, 1080, AV_PIX_FMT_YUV420P, 32
+ * );
+ * console.log(`Allocated ${data.length} planes, total ${size} bytes`);
+ * ```
  */
 export function avImageAllocArrays(width, height, pixFmt, align) {
     const result = avImageAlloc(width, height, pixFmt, align);
@@ -266,71 +444,133 @@ export function avImageAllocArrays(width, height, pixFmt, align) {
     };
 }
 /**
- * Compare two timestamps
- * Direct mapping to av_compare_ts()
+ * Compare timestamps.
+ *
+ * Compares two timestamps with different time bases.
+ *
+ * Direct mapping to av_compare_ts().
  *
- * @returns -1 if tsA < tsB, 0 if tsA == tsB, 1 if tsA > tsB
+ * @param tsA - First timestamp
+ * @param tbA - First time base
+ * @param tsB - Second timestamp
+ * @param tbB - Second time base
+ * @returns -1 if A < B, 0 if A == B, 1 if A > B
+ *
+ * @example
+ * ```typescript
+ * const cmp = avCompareTs(
+ *   1000n, { num: 1, den: 1000 },  // 1 second
+ *   900n, { num: 1, den: 900 }      // 1 second
+ * );
+ * // Returns 0 (equal)
+ * ```
+ *
+ * @see [av_compare_ts](https://ffmpeg.org/doxygen/7.1/group__lavu__math.html#ga151744358fff630942b926e67e67c415) - FFmpeg Doxygen
  */
 export function avCompareTs(tsA, tbA, tsB, tbB) {
     return bindings.avCompareTs(tsA, tbA, tsB, tbB);
 }
 /**
- * Rescale a timestamp from one timebase to another
- * Direct mapping to av_rescale_q()
+ * Rescale timestamp.
+ *
+ * Rescales a timestamp from one time base to another.
+ *
+ * Direct mapping to av_rescale_q().
+ *
+ * @param a - Timestamp to rescale
+ * @param bq - Source time base
+ * @param cq - Destination time base
+ * @returns Rescaled timestamp
+ *
+ * @example
+ * ```typescript
+ * // Convert 1 second from 1000Hz to 90kHz
+ * const rescaled = avRescaleQ(
+ *   1000n,
+ *   { num: 1, den: 1000 },   // 1000 Hz
+ *   { num: 1, den: 90000 }   // 90 kHz
+ * );
+ * // Returns 90000n
+ * ```
+ *
+ * @see [av_rescale_q](https://ffmpeg.org/doxygen/7.1/group__lavu__math.html#gaf02994a8bbeaa91d4757df179cbe567f) - FFmpeg Doxygen
  */
 export function avRescaleQ(a, bq, cq) {
     return bindings.avRescaleQ(a, bq, cq);
 }
 /**
- * Sleep for a specified number of microseconds.
+ * Sleep for microseconds.
  *
- * Provides a cross-platform microsecond sleep function.
- * Useful for timing operations or frame pacing.
+ * Suspends execution for the specified number of microseconds.
  *
- * Direct mapping to av_usleep()
+ * Direct mapping to av_usleep().
  *
- * @param usec - Number of microseconds to sleep
+ * @param usec - Microseconds to sleep
  *
  * @example
  * ```typescript
- * import { avUsleep } from 'node-av';
- *
- * // Sleep for 100ms (100,000 microseconds)
- * avUsleep(100000);
- *
- * // Sleep for 1 second
- * avUsleep(1000000);
- *
- * // Frame pacing for 30fps (33.33ms per frame)
- * const frameTime = 1000000 / 30;
- * avUsleep(frameTime);
+ * avUsleep(1000000); // Sleep for 1 second
+ * avUsleep(16667);   // Sleep for ~16.67ms (60fps frame time)
  * ```
+ *
+ * @see [av_usleep](https://ffmpeg.org/doxygen/7.1/time_8c.html#a4eee9c65835652a808973f4bc1641a51) - FFmpeg Doxygen
  */
 export function avUsleep(usec) {
     bindings.avUsleep(usec);
 }
 /**
- * Rescale a timestamp with rounding
- * Direct mapping to av_rescale_rnd()
+ * Rescale with rounding.
+ *
+ * Rescales a value with specified rounding behavior.
+ *
+ * Direct mapping to av_rescale_rnd().
  *
  * @param a - Value to rescale
- * @param b - Numerator of scale factor
- * @param c - Denominator of scale factor
- * @param rnd - Rounding mode (AVRounding enum)
+ * @param b - Multiplier
+ * @param c - Divisor
+ * @param rnd - Rounding mode (AV_ROUND_*)
  * @returns Rescaled value
+ *
+ * @example
+ * ```typescript
+ * import { AV_ROUND_NEAR_INF } from 'node-av/constants';
+ *
+ * const rescaled = avRescaleRnd(1000n, 90000n, 1000n, AV_ROUND_NEAR_INF);
+ * // Returns 90000n
+ * ```
+ *
+ * @see [av_rescale_rnd](https://ffmpeg.org/doxygen/7.1/group__lavu__math.html#ga82d40664213508918093822461cc597e) - FFmpeg Doxygen
  */
 export function avRescaleRnd(a, b, c, rnd) {
     return bindings.avRescaleRnd(a, b, c, rnd);
 }
 /**
- * Allocate audio sample buffers
- * Direct mapping to av_samples_alloc()
+ * Allocate audio samples buffer.
  *
- * @param nbChannels - Number of channels
+ * Allocates buffers for audio samples with the specified format.
+ *
+ * Direct mapping to av_samples_alloc().
+ *
+ * @param nbChannels - Number of audio channels
  * @param nbSamples - Number of samples per channel
  * @param sampleFmt - Sample format
- * @param align - Buffer alignment (0 for default)
- * @returns Object with allocated data buffers, linesize and total size, or error code
+ * @param align - Buffer alignment
+ * @returns Object with data buffers, line size, and total size
+ *
+ * @throws {FFmpegError} If allocation fails
+ *
+ * @example
+ * ```typescript
+ * import { AV_SAMPLE_FMT_FLTP } from 'node-av/constants';
+ *
+ * const { data, linesize, size } = avSamplesAlloc(
+ *   2, 1024, AV_SAMPLE_FMT_FLTP, 0
+ * );
+ * console.log(`Allocated ${data.length} buffers, ${size} bytes total`);
+ * ```
+ *
+ * @see [av_samples_alloc](https://ffmpeg.org/doxygen/7.1/group__lavu__sampmanip.html#ga4db4c77f928d32c7d8854732f50b8c04) - FFmpeg Doxygen
+ * @see {@link avSamplesGetBufferSize} To calculate size without allocating
  */
 export function avSamplesAlloc(nbChannels, nbSamples, sampleFmt, align) {
     const result = bindings.avSamplesAlloc(nbChannels, nbSamples, sampleFmt, align);
@@ -340,14 +580,32 @@ export function avSamplesAlloc(nbChannels, nbSamples, sampleFmt, align) {
     return result;
 }
 /**
- * Get the required buffer size for audio samples
- * Direct mapping to av_samples_get_buffer_size()
+ * Get audio samples buffer size.
+ *
+ * Calculates the required buffer size for audio samples.
+ *
+ * Direct mapping to av_samples_get_buffer_size().
  *
  * @param nbChannels - Number of channels
  * @param nbSamples - Number of samples per channel
  * @param sampleFmt - Sample format
- * @param align - Buffer alignment (0 for default)
- * @returns Object with size and linesize, or error code
+ * @param align - Buffer alignment
+ * @returns Object with size and line size
+ *
+ * @throws {FFmpegError} If parameters are invalid
+ *
+ * @example
+ * ```typescript
+ * import { AV_SAMPLE_FMT_S16 } from 'node-av/constants';
+ *
+ * const { size, linesize } = avSamplesGetBufferSize(
+ *   2, 1024, AV_SAMPLE_FMT_S16, 0
+ * );
+ * console.log(`Need ${size} bytes, ${linesize} per channel`);
+ * ```
+ *
+ * @see [av_samples_get_buffer_size](https://ffmpeg.org/doxygen/7.1/group__lavu__sampfmts.html#gaa7368bc4e3a366b688e81938ed55eb06) - FFmpeg Doxygen
+ * @see {@link avSamplesAlloc} To allocate the buffer
  */
 export function avSamplesGetBufferSize(nbChannels, nbSamples, sampleFmt, align) {
     const result = bindings.avSamplesGetBufferSize(nbChannels, nbSamples, sampleFmt, align);
@@ -357,48 +615,46 @@ export function avSamplesGetBufferSize(nbChannels, nbSamples, sampleFmt, align)
     return result;
 }
 /**
- * Get a string description of a channel layout.
- * Direct mapping to av_channel_layout_describe()
+ * Describe channel layout.
  *
- * @param channelLayout - The channel layout object with order, nbChannels, and mask
- * @returns String description of the channel layout, or null if invalid
+ * Returns a human-readable description of a channel layout.
+ *
+ * Direct mapping to av_channel_layout_describe().
+ *
+ * @param channelLayout - Channel layout to describe
+ * @returns Layout description string, or null
+ *
+ * @example
+ * ```typescript
+ * const stereo = { nbChannels: 2, order: 1, u: { mask: 3n } };
+ * const desc = avChannelLayoutDescribe(stereo); // Returns "stereo"
+ * ```
+ *
+ * @see [av_channel_layout_describe](https://ffmpeg.org/doxygen/7.1/group__lavu__audio__channels.html#gacc7d7d1a280248aafb8f9196c9d4e24f) - FFmpeg Doxygen
  */
 export function avChannelLayoutDescribe(channelLayout) {
     return bindings.avChannelLayoutDescribe(channelLayout);
 }
 /**
- * Create an SDP (Session Description Protocol) string for RTP/RTSP streaming.
+ * Create SDP from format contexts.
  *
- * Generates an SDP description from one or more FormatContext objects.
- * Useful for RTP/RTSP streaming scenarios where you need to describe
- * the media streams to clients.
+ * Creates an SDP (Session Description Protocol) string from format contexts.
+ * Used for RTP/RTSP streaming.
  *
- * Direct mapping to av_sdp_create()
+ * Direct mapping to av_sdp_create().
  *
- * @param contexts - Array of FormatContext objects to describe
- * @returns SDP string on success, or null on failure
- *
- * @throws {FFmpegError} On invalid parameters or SDP creation failure
+ * @param contexts - Array of format contexts
+ * @returns SDP string, or null on error
  *
  * @example
  * ```typescript
- * import { avSdpCreate, FormatContext, FFmpegError } from 'node-av';
- *
- * // Create format contexts for RTP output
- * const contexts: FormatContext[] = [];
- *
- * const ctx = new FormatContext();
- * // ... configure context for RTP output ...
- * contexts.push(ctx);
- *
- * // Generate SDP
- * const sdp = avSdpCreate(contexts);
+ * const sdp = avSdpCreate([outputContext]);
  * if (sdp) {
- *   console.log('SDP:', result);
+ *   console.log('SDP:\n' + sdp);
  * }
- *
- * // Use the SDP string for RTSP server or save to .sdp file
  * ```
+ *
+ * @see [av_sdp_create](https://ffmpeg.org/doxygen/7.1/group__lavf__misc.html#gaa2a7353a6bb0c8726797abd56b176af0) - FFmpeg Doxygen
  */
 export function avSdpCreate(contexts) {
     if (!Array.isArray(contexts) || contexts.length === 0) {