node-av 3.1.2 → 4.0.0

package/dist/lib/utilities.d.ts

@@ -1,4 +1,5 @@
-import type { AVCodecID, AVMediaType, AVPixelFormat, AVSampleFormat } from '../constants/constants.js';
+import type { AVCodecID, AVHWDeviceType, AVMediaType, AVPixelFormat, AVSampleFormat } from '../constants/constants.js';
+import type { FFHWDeviceType } from '../constants/hardware.js';
 import type { FormatContext } from './format-context.js';
 import type { NativeCodecParameters, NativeWrapper } from './native-types.js';
 import type { ChannelLayout, IRational } from './types.js';
@@ -197,78 +198,49 @@ export declare function avSampleFmtIsPlanar(sampleFmt: AVSampleFormat): boolean;
  */
 export declare function avGetCodecName(codecId: AVCodecID): string | null;
 /**
- * Get DASH/RFC 6381 codec string from codec parameters.
+ * Get RFC 6381 codec string from codec parameters.
  *
- * Generates codec strings for MPEG-DASH manifests following RFC 6381.
- * Uses FFmpeg's dashenc.c implementation for accurate codec strings.
- *
- * Supported codecs:
- * - **WebM codecs**: VP8, VP9 (detailed), Vorbis, Opus, FLAC
- * - **H.264** (avc1): `avc1.PPCCLL` (profile, constraints, level)
- * - **HEVC** (hvc1/hev1): Base tag only (`hvc1` or `hev1`) - no profile details
- * - **AV1** (av01): `av01.P.LLT.BB...` (profile, level, tier, bitdepth, etc.)
- * - **AAC** (mp4a): `mp4a.OT.AOT` (object type, audio object type)
- *
- * Note: For HLS with detailed HEVC codec strings, use {@link avGetCodecStringHls}.
- *
- * @param codecpar - Codec parameters
- *
- * @returns DASH codec string, or null if cannot be determined
- *
- * @example
- * ```typescript
- * import { avGetCodecStringDash } from 'node-av/lib';
- *
- * // Get codec string from DASH output stream
- * const stream = dashOutput.video();
- * const codecString = avGetCodecStringDash(stream.codecpar);
- * console.log(codecString); // "hev1" for HEVC, "avc1.42c01e" for H.264
- *
- * // Use for DASH manifest
- * const mimeType = `video/mp4; codecs="${codecString}"`;
- * ```
- *
- * @see [RFC 6381](https://tools.ietf.org/html/rfc6381) - RFC 6381: Codecs Parameter Specification
- * @see [dashenc](https://ffmpeg.org/doxygen/trunk/dashenc_8c_source.html#l00345) - FFmpeg dashenc.c implementation
- */
-export declare function avGetCodecStringDash(codecpar: NativeWrapper<NativeCodecParameters>): string | null;
-/**
- * Get HLS codec string from codec parameters.
- *
- * Generates codec strings for HLS playlists. Uses FFmpeg's hlsenc.c implementation.
- * Provides detailed HEVC codec strings with profile, tier, level, and constraints.
+ * Generates codec strings for MPEG-DASH and HLS manifests following RFC 6381.
+ * Uses FFmpeg's centralized ff_make_codec_str() implementation (libavformat/codecstring.c).
  *
  * Supported codecs:
+ * - **WebM codecs**: VP8, VP9 (with detailed profile/level), Vorbis, Opus, FLAC
  * - **H.264** (avc1): `avc1.PPCCLL` (profile, constraints, level)
  * - **HEVC** (hvc1): `hvc1.P.PC.TL.C` (profile, profile_compatibility, tier+level, constraints)
- * - **AAC**: `mp4a.40.AOT` (audio object type based on profile)
+ * - **AV1** (av01): `av01.P.LLT.BB...` (profile, level, tier, bitdepth, color info)
+ * - **AAC**: `mp4a.40.AOT` (audio object type)
  * - **MP2**: `mp4a.40.33`
  * - **MP3**: `mp4a.40.34`
  * - **AC-3**: `ac-3`
  * - **E-AC-3**: `ec-3`
- *
- * Note: For DASH manifests, use {@link avGetCodecStringDash} instead.
+ * - **MPEG-4 Visual**: `mp4v.20` (profile/level not implemented)
  *
  * @param codecpar - Codec parameters
  *
- * @returns HLS codec string, or null if cannot be determined
+ * @param frameRate - Optional frame rate for VP9 level calculation (only used for VP9)
+ *
+ * @returns RFC 6381 codec string, or null if codec not supported
  *
  * @example
  * ```typescript
- * import { avGetCodecStringHls } from 'node-av/lib';
+ * import { avGetCodecString } from 'node-av/lib';
+ *
+ * // Get codec string for DASH/HLS manifest
+ * const stream = output.video();
+ * const codecString = avGetCodecString(stream.codecpar);
+ * console.log(codecString); // "hvc1.1.6.L93.B0" for HEVC, "avc1.42c01e" for H.264
  *
- * // Get detailed HEVC codec string for HLS
- * const stream = hlsOutput.video();
- * const codecString = avGetCodecStringHls(stream.codecpar);
- * console.log(codecString); // "hvc1.1.6.L93.B0" - detailed HEVC profile info
+ * // VP9 with frame rate for accurate level
+ * const codecStringVP9 = avGetCodecString(stream.codecpar, { num: 30, den: 1 });
+ * console.log(codecStringVP9); // "vp09.00.30.08" - detailed VP9 string
  *
- * // Use for HLS playlist
- * const codecsAttr = `CODECS="${codecString}"`;
+ * // Use for DASH/HLS manifest
+ * const mimeType = `video/mp4; codecs="${codecString}"`;
  * ```
  *
- * @see [hlsenc](https://ffmpeg.org/doxygen/trunk/hlsenc_8c_source.html#l00351) - FFmpeg hlsenc.c implementation
+ * @see [codecstring.c](https://github.com/FFmpeg/FFmpeg/blob/master/libavformat/codecstring.c) - FFmpeg implementation
  */
-export declare function avGetCodecStringHls(codecpar: NativeWrapper<NativeCodecParameters>): string | null;
+export declare function avGetCodecString(codecpar: NativeWrapper<NativeCodecParameters>, frameRate?: IRational): string | null;
 /**
  * Get DASH MIME type for codec parameters.
  *
@@ -363,6 +335,52 @@ export declare function avGetPixFmtFromName(name: string): AVPixelFormat;
  * @see [av_pix_fmt_desc_get](https://ffmpeg.org/doxygen/7.1/pixdesc_8c.html#afe0c3e8aef5173de28bbdaea4298f5f0) - FFmpeg Doxygen
  */
 export declare function avIsHardwarePixelFormat(pixFmt: AVPixelFormat): boolean;
+/**
+ * Get hardware device type name.
+ *
+ * Returns the string name for a hardware device type enum value.
+ *
+ * Direct mapping to av_hwdevice_get_type_name().
+ *
+ * @param type - Hardware device type enum
+ *
+ * @returns Device type name (e.g. "videotoolbox", "cuda"), or null if unknown
+ *
+ * @example
+ * ```typescript
+ * import { AV_HWDEVICE_TYPE_VIDEOTOOLBOX, AV_HWDEVICE_TYPE_CUDA } from 'node-av/constants';
+ *
+ * const name1 = avGetHardwareDeviceTypeName(AV_HWDEVICE_TYPE_VIDEOTOOLBOX); // Returns "videotoolbox"
+ * const name2 = avGetHardwareDeviceTypeName(AV_HWDEVICE_TYPE_CUDA);         // Returns "cuda"
+ * ```
+ *
+ * @see [av_hwdevice_get_type_name](https://ffmpeg.org/doxygen/7.1/hwcontext_8h.html#afb2b99a15f3fdde25a2fd19353ac5a67) - FFmpeg Doxygen
+ */
+export declare function avGetHardwareDeviceTypeName(type: AVHWDeviceType): FFHWDeviceType;
+/**
+ * Get hardware device type from name.
+ *
+ * Looks up the hardware device type enum from its string name.
+ * Returns AV_HWDEVICE_TYPE_NONE if the name is not recognized.
+ *
+ * Direct mapping to av_hwdevice_find_type_by_name().
+ *
+ * @param name - Hardware device type name (e.g. "videotoolbox", "cuda")
+ *
+ * @returns Hardware device type enum, or AV_HWDEVICE_TYPE_NONE if not found
+ *
+ * @example
+ * ```typescript
+ * import { avGetHardwareDeviceTypeFromName } from 'node-av/lib';
+ *
+ * const type1 = avGetHardwareDeviceTypeFromName("videotoolbox"); // Returns AV_HWDEVICE_TYPE_VIDEOTOOLBOX
+ * const type2 = avGetHardwareDeviceTypeFromName("cuda");         // Returns AV_HWDEVICE_TYPE_CUDA
+ * const none = avGetHardwareDeviceTypeFromName("invalid");       // Returns AV_HWDEVICE_TYPE_NONE
+ * ```
+ *
+ * @see [av_hwdevice_find_type_by_name](https://ffmpeg.org/doxygen/7.1/hwcontext_8h.html#a541943ddced791765349645a30adfa4d) - FFmpeg Doxygen
+ */
+export declare function avGetHardwareDeviceTypeFromName(name: FFHWDeviceType): AVHWDeviceType;
 /**
  * Get media type string.
  *
@@ -698,6 +716,216 @@ export declare function avUsleep(usec: number): void;
  * @see [av_rescale_rnd](https://ffmpeg.org/doxygen/7.1/group__lavu__math.html#ga82d40664213508918093822461cc597e) - FFmpeg Doxygen
  */
 export declare function avRescaleRnd(a: bigint | number, b: bigint | number, c: bigint | number, rnd: number): bigint;
+/**
+ * Rescale a timestamp while preserving accuracy with coarse input timebases.
+ *
+ * Used for audio streamcopy to maintain accuracy when input timebase is coarse.
+ * Direct mapping to av_rescale_delta().
+ *
+ * @param inTb - Input timebase
+ *
+ * @param inTs - Input timestamp
+ *
+ * @param fsTb - Duration timebase (e.g., {1, sampleRate})
+ *
+ * @param duration - Duration in fsTb units
+ *
+ * @param lastRef - Reference object with `value` property (modified by function)
+ *
+ * @param lastRef.value - Last output timestamp (bigint)
+ *
+ * @param outTb - Output timebase
+ *
+ * @returns Rescaled timestamp
+ *
+ * @example
+ * ```typescript
+ * const inTb = { num: 1, den: 48000 };
+ * const inTs = 1000000n;
+ * const fsTb = { num: 1, den: 44100 };
+ * const duration = 1024;
+ * const lastRef = { value: 0n };
+ * const outTb = { num: 1, den: 96000 };
+ *
+ * const rescaled = avRescaleDelta(inTb, inTs, fsTb, duration, lastRef, outTb);
+ * ```
+ *
+ * @see [av_rescale_delta](https://ffmpeg.org/doxygen/7.1/group__lavu__math.html) - FFmpeg Doxygen
+ */
+export declare function avRescaleDelta(inTb: IRational, inTs: bigint | number, fsTb: IRational, duration: number, lastRef: {
+    value: bigint;
+}, outTb: IRational): bigint;
+/**
+ * Multiply two rational numbers.
+ *
+ * Multiplies two rational numbers using FFmpeg's av_mul_q() which normalizes the result.
+ * This is more accurate than manual multiplication as it reduces the fraction.
+ *
+ * Direct mapping to av_mul_q().
+ *
+ * @param a - First rational number
+ *
+ * @param b - Second rational number
+ *
+ * @returns Product of a and b as a normalized rational
+ *
+ * @example
+ * ```typescript
+ * // Multiply framerate by 2
+ * const framerate = { num: 25, den: 1 };
+ * const doubled = avMulQ(framerate, { num: 2, den: 1 });
+ * // Returns { num: 50, den: 1 }
+ *
+ * // Calculate field rate for interlaced video
+ * const fieldRate = avMulQ(framerate, { num: 2, den: 1 });
+ * ```
+ *
+ * @see [av_mul_q](https://ffmpeg.org/doxygen/trunk/group__lavu__math__rational.html#ga89c0e84e30e2f90196e11fc254e4fc3f) - FFmpeg Doxygen
+ */
+export declare function avMulQ(a: IRational, b: IRational): IRational;
+/**
+ * Invert a rational number.
+ *
+ * Returns the reciprocal of a rational number using FFmpeg's av_inv_q().
+ * Swaps numerator and denominator: (a/b) becomes (b/a).
+ *
+ * Direct mapping to av_inv_q().
+ *
+ * @param q - Rational number to invert
+ *
+ * @returns Inverted rational (reciprocal)
+ *
+ * @example
+ * ```typescript
+ * // Convert framerate to frame duration
+ * const framerate = { num: 25, den: 1 };  // 25 fps
+ * const frameDuration = avInvQ(framerate); // 1/25 seconds
+ * // Returns { num: 1, den: 25 }
+ *
+ * // Get timebase from framerate
+ * const timebase = avInvQ({ num: 30000, den: 1001 }); // NTSC
+ * // Returns { num: 1001, den: 30000 }
+ * ```
+ *
+ * @see [av_inv_q](https://ffmpeg.org/doxygen/trunk/group__lavu__math__rational.html#ga587a784cb48299feea51d7dbbc6cc38c) - FFmpeg Doxygen
+ */
+export declare function avInvQ(q: IRational): IRational;
+/**
+ * Add two rational numbers.
+ *
+ * Adds two rational numbers using FFmpeg's av_add_q() which normalizes the result.
+ * This is more accurate than manual addition as it reduces the fraction.
+ *
+ * Direct mapping to av_add_q().
+ *
+ * @param a - First rational number
+ *
+ * @param b - Second rational number
+ *
+ * @returns Sum of a and b as a normalized rational
+ *
+ * @example
+ * ```typescript
+ * // Add two fractions
+ * const a = { num: 1, den: 2 };  // 1/2
+ * const b = { num: 1, den: 4 };  // 1/4
+ * const sum = avAddQ(a, b);      // 3/4
+ * // Returns { num: 3, den: 4 }
+ *
+ * // Add timestamps with different timebases
+ * const ts1 = { num: 1000, den: 30000 };
+ * const ts2 = { num: 500, den: 30000 };
+ * const total = avAddQ(ts1, ts2);
+ * // Returns { num: 1, den: 20 } (normalized from 1500/30000)
+ * ```
+ *
+ * @see [av_add_q](https://ffmpeg.org/doxygen/trunk/group__lavu__math__rational.html#gac4af1feb227bd1095fc2cab42d933f52) - FFmpeg Doxygen
+ */
+export declare function avAddQ(a: IRational, b: IRational): IRational;
+/**
+ * Calculate greatest common divisor.
+ *
+ * Computes the GCD of two integers using FFmpeg's av_gcd().
+ * Uses the Euclidean algorithm for efficient computation.
+ *
+ * Direct mapping to av_gcd().
+ *
+ * @param a - First integer
+ *
+ * @param b - Second integer
+ *
+ * @returns Greatest common divisor of a and b
+ *
+ * @example
+ * ```typescript
+ * const gcd = avGcd(48000, 44100);
+ * console.log(gcd); // 300
+ *
+ * // Used for calculating LCM
+ * const lcm = (a * b) / avGcd(a, b);
+ * ```
+ *
+ * @see [av_gcd](https://ffmpeg.org/doxygen/trunk/group__lavu__math.html#ga0e8419780352de538c1c15098cb1a587) - FFmpeg Doxygen
+ */
+export declare function avGcd(a: bigint | number, b: bigint | number): bigint;
+/**
+ * Rescale timestamp with specified rounding mode.
+ *
+ * Rescales a timestamp from one time base to another with specific rounding behavior.
+ * More control than avRescaleQ() which uses default rounding.
+ *
+ * Direct mapping to av_rescale_q_rnd().
+ *
+ * @param a - Timestamp to rescale
+ *
+ * @param bq - Source time base
+ *
+ * @param cq - Destination time base
+ *
+ * @param rnd - Rounding mode (AV_ROUND_ZERO, AV_ROUND_INF, AV_ROUND_DOWN, AV_ROUND_UP, AV_ROUND_NEAR_INF)
+ *
+ * @returns Rescaled timestamp
+ *
+ * @example
+ * ```typescript
+ * import { AV_ROUND_UP, AV_ROUND_DOWN } from 'node-av/constants';
+ *
+ * const pts = 1000n;
+ * const srcTb = { num: 1, den: 48000 };
+ * const dstTb = { num: 1, den: 90000 };
+ *
+ * // Round up for safer comparisons
+ * const ptsUp = avRescaleQRnd(pts, srcTb, dstTb, AV_ROUND_UP);
+ *
+ * // Round down for conservative timestamps
+ * const ptsDown = avRescaleQRnd(pts, srcTb, dstTb, AV_ROUND_DOWN);
+ * ```
+ *
+ * @see [av_rescale_q_rnd](https://ffmpeg.org/doxygen/trunk/group__lavu__math.html#ga60044a302e86b5c2d8b19a81c8179f30) - FFmpeg Doxygen
+ */
+export declare function avRescaleQRnd(a: bigint | number | null, bq: IRational, cq: IRational, rnd: number): bigint;
+/**
+ * Get the duration of a single audio frame in samples.
+ *
+ * Returns the number of samples per audio frame for codecs with constant frame size,
+ * or calculates it based on frame bytes for variable frame size codecs.
+ *
+ * Direct mapping to av_get_audio_frame_duration2().
+ *
+ * @param codecpar - Codec parameters
+ *
+ * @param frameBytes - Size of the frame in bytes
+ *
+ * @returns Number of samples in the frame, or 0 if unknown
+ *
+ * @example
+ * ```typescript
+ * const frameDuration = avGetAudioFrameDuration2(codecpar, frameBytes);
+ * ```
+ *
+ * @see [av_get_audio_frame_duration2](https://ffmpeg.org/doxygen/7.1/group__lavc__misc.html) - FFmpeg Doxygen
+ */
+export declare function avGetAudioFrameDuration2(codecpar: NativeWrapper<NativeCodecParameters>, frameBytes: number): number;
 /**
  * Allocate audio samples buffer.
  *