node-av 3.1.3 → 5.0.0

package/dist/lib/frame.d.ts

@@ -1,8 +1,9 @@
 import { HardwareFramesContext } from './hardware-frames-context.js';
 import { Rational } from './rational.js';
 import type { AVChromaLocation, AVColorPrimaries, AVColorRange, AVColorSpace, AVColorTransferCharacteristic, AVFrameSideDataType, AVMediaType, AVPictureType, AVPixelFormat, AVSampleFormat } from '../constants/constants.js';
+import { Dictionary } from './dictionary.js';
 import type { NativeFrame, NativeWrapper } from './native-types.js';
-import type { ChannelLayout } from './types.js';
+import type { AudioFrame, ChannelLayout, VideoFrame } from './types.js';
 /**
  * Container for uncompressed audio/video data.
  *
@@ -49,6 +50,63 @@ export declare class Frame implements Disposable, NativeWrapper<NativeFrame> {
     private native;
     private _hwFramesCtx?;
     constructor();
+    /**
+     * Create a video frame from a buffer with pixel data.
+     *
+     * Allocates frame buffers, sets properties, and copies buffer data.
+     * Convenience factory method that combines frame allocation and data copy.
+     *
+     * @param buffer - Buffer containing raw pixel data
+     *
+     * @param props - Video Frame properties
+     *
+     * @returns Allocated frame with data from buffer
+     *
+     * @throws {FFmpegError} If allocation or buffer copy fails
+     *
+     * @example
+     * ```typescript
+     * import { Frame, AV_PIX_FMT_RGBA, FFmpegError } from 'node-av';
+     *
+     * const rawPixels = Buffer.alloc(1920 * 1080 * 4); // RGBA data
+     * using frame = Frame.fromVideoBuffer(rawPixels, {
+     *   width: 1920,
+     *   height: 1080,
+     *   format: AV_PIX_FMT_RGBA,
+     *   timeBase: { num: 1, den: 30 }
+     * });
+     * ```
+     */
+    static fromVideoBuffer(buffer: Buffer, props: VideoFrame): Frame;
+    /**
+     * Create an audio frame from a buffer with sample data.
+     *
+     * Allocates frame buffers, sets properties, and copies buffer data.
+     * Convenience factory method that combines frame allocation and data copy.
+     *
+     * @param buffer - Buffer containing raw audio samples
+     *
+     * @param props - Frame properties
+     *
+     * @returns Allocated frame with data from buffer
+     *
+     * @throws {FFmpegError} If allocation or buffer copy fails
+     *
+     * @example
+     * ```typescript
+     * import { Frame, AV_SAMPLE_FMT_FLT, AV_CH_LAYOUT_STEREO, FFmpegError } from 'node-av';
+     *
+     * const samples = Buffer.alloc(960 * 2 * 4); // 960 samples, stereo, float32
+     * using frame = Frame.fromAudioBuffer(samples, {
+     *   nbSamples: 960,
+     *   format: AV_SAMPLE_FMT_FLT,
+     *   sampleRate: 48000,
+     *   channelLayout: AV_CH_LAYOUT_STEREO,
+     *   timeBase: { num: 1, den: 48000 }
+     * });
+     * ```
+     */
+    static fromAudioBuffer(buffer: Buffer, props: AudioFrame): Frame;
     /**
      * Pixel format for video frames or sample format for audio.
      *
@@ -134,6 +192,17 @@ export declare class Frame implements Disposable, NativeWrapper<NativeFrame> {
      */
     get pictType(): AVPictureType;
     set pictType(value: AVPictureType);
+    /**
+     * Quality (between 1 (good) and FF_LAMBDA_MAX (bad)).
+     *
+     * Set by libavcodec for some coded frames.
+     * Can be set before encoding to specify desired quality for encoders that support it.
+     * Used by FFmpeg CLI's frame_encode() to propagate encoder's global_quality setting.
+     *
+     * Direct mapping to AVFrame->quality.
+     */
+    get quality(): number;
+    set quality(value: number);
     /**
      * Sample aspect ratio.
      *
@@ -254,6 +323,133 @@ export declare class Frame implements Disposable, NativeWrapper<NativeFrame> {
      */
     get hwFramesCtx(): HardwareFramesContext | null;
     set hwFramesCtx(value: HardwareFramesContext | null);
+    /**
+     * Frame flags.
+     *
+     * Combination of AVFrameFlags (e.g., AV_FRAME_FLAG_CORRUPT, AV_FRAME_FLAG_KEY).
+     *
+     * Direct mapping to AVFrame->flags.
+     */
+    get flags(): number;
+    set flags(value: number);
+    /**
+     * Decode error flags.
+     *
+     * Indicates errors detected during decoding.
+     * Non-zero value means the frame may be corrupted.
+     *
+     * Direct mapping to AVFrame->decode_error_flags.
+     */
+    get decodeErrorFlags(): number;
+    set decodeErrorFlags(value: number);
+    /**
+     * Frame duration.
+     *
+     * Duration of this frame in units of time_base.
+     * This is FFmpeg's best guess for how long the frame should be displayed.
+     * May be 0 if unknown or unavailable.
+     *
+     * Direct mapping to AVFrame->duration.
+     */
+    get duration(): bigint;
+    set duration(value: bigint);
+    /**
+     * Number of fields in this frame that should be repeated.
+     *
+     * For interlaced video, indicates how many times the frame should be repeated
+     * when displayed. For progressive video, this is typically 0.
+     * Formula: display_time = (repeat_pict / (2*fps))
+     *
+     * Direct mapping to AVFrame->repeat_pict.
+     */
+    get repeatPict(): number;
+    set repeatPict(value: number);
+    /**
+     * Set frame flags.
+     *
+     * Sets one or more flags using bitwise OR. Allows setting multiple flags
+     * without manually performing bitwise operations.
+     *
+     * @param flags - One or more flag values to set
+     *
+     * @example
+     * ```typescript
+     * import { AV_FRAME_FLAG_KEY } from 'node-av/constants';
+     *
+     * // Mark frame as key frame
+     * frame.setFlags(AV_FRAME_FLAG_KEY);
+     * ```
+     *
+     * @see {@link clearFlags} To unset flags
+     * @see {@link hasFlags} To check flags
+     * @see {@link flags} For direct flag access
+     */
+    setFlags(...flags: number[]): void;
+    /**
+     * Clear frame flags.
+     *
+     * Clears one or more flags using bitwise AND NOT. Allows clearing multiple
+     * flags without manually performing bitwise operations.
+     *
+     * @param flags - One or more flag values to clear
+     *
+     * @example
+     * ```typescript
+     * import { AV_FRAME_FLAG_CORRUPT } from 'node-av/constants';
+     *
+     * // Clear corrupt flag
+     * frame.clearFlags(AV_FRAME_FLAG_CORRUPT);
+     * ```
+     *
+     * @see {@link setFlags} To set flags
+     * @see {@link hasFlags} To check flags
+     * @see {@link flags} For direct flag access
+     */
+    clearFlags(...flags: number[]): void;
+    /**
+     * Check if frame has specific flags.
+     *
+     * Tests whether all specified flags are set using bitwise AND.
+     *
+     * @param flags - One or more flag values to check
+     *
+     * @returns true if all specified flags are set, false otherwise
+     *
+     * @example
+     * ```typescript
+     * import { AV_FRAME_FLAG_CORRUPT } from 'node-av/constants';
+     *
+     * if (frame.hasFlags(AV_FRAME_FLAG_CORRUPT)) {
+     *   console.log('Frame is corrupted');
+     * }
+     * ```
+     *
+     * @see {@link setFlags} To set flags
+     * @see {@link clearFlags} To unset flags
+     * @see {@link flags} For direct flag access
+     */
+    hasFlags(...flags: number[]): boolean;
+    /**
+     * Check if frame has decode errors.
+     *
+     * Tests whether all specified decode error flags are set using bitwise AND.
+     *
+     * @param flags - One or more decode error flag values to check
+     *
+     * @returns true if all specified error flags are set, false otherwise
+     *
+     * @example
+     * ```typescript
+     * import { FF_DECODE_ERROR_INVALID_BITSTREAM } from 'node-av/constants';
+     *
+     * if (frame.hasDecodeErrorFlags(FF_DECODE_ERROR_INVALID_BITSTREAM)) {
+     *   console.log('Frame has invalid bitstream error');
+     * }
+     * ```
+     *
+     * @see {@link decodeErrorFlags} For direct error flag access
+     */
+    hasDecodeErrorFlags(...flags: number[]): boolean;
     /**
      * Check if this is a video frame.
      *
@@ -783,6 +979,73 @@ export declare class Frame implements Disposable, NativeWrapper<NativeFrame> {
      * @see {@link newSideData} To add side data
      */
     removeSideData(type: AVFrameSideDataType): void;
+    /**
+     * Get frame metadata dictionary.
+     *
+     * Returns metadata attached to the frame by filters or demuxers.
+     * Metadata is stored as key-value pairs in a Dictionary.
+     * Useful for reading filter-generated metadata (e.g., whisper transcription).
+     *
+     * Direct mapping to AVFrame->metadata.
+     *
+     * @returns Dictionary containing frame metadata
+     *
+     * @example
+     * ```typescript
+     * // Read whisper filter metadata
+     * const metadata = frame.getMetadata();
+     * const text = metadata.get('lavfi.whisper.text');
+     * const duration = metadata.get('lavfi.whisper.duration');
+     *
+     * if (text) {
+     *   console.log(`Transcribed: ${text}`);
+     *   console.log(`Duration: ${duration}s`);
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Read scene detection metadata
+     * const metadata = frame.getMetadata();
+     * const score = metadata.get('lavfi.scene_score');
+     * if (score) {
+     *   console.log(`Scene change score: ${score}`);
+     * }
+     * ```
+     *
+     * @see {@link Dictionary} For metadata dictionary operations
+     */
+    getMetadata(): Dictionary;
+    /**
+     * Apply cropping to the frame.
+     *
+     * Crops the frame according to its crop metadata (AVFrame crop fields).
+     * This adjusts the frame dimensions and data pointers to reflect the cropped region.
+     * The cropped-out area is discarded, reducing frame size.
+     *
+     * Direct mapping to av_frame_apply_cropping().
+     *
+     * @param flags - Cropping flags (default: AV_FRAME_CROP_UNALIGNED = 1)
+     *                AV_FRAME_CROP_UNALIGNED allows unaligned cropping for lavfi compatibility
+     *
+     * @returns 0 on success, negative error code on failure
+     *
+     * @example
+     * ```typescript
+     * import { Frame, FFmpegError } from 'node-av';
+     *
+     * const frame = new Frame();
+     * // ... decode frame with crop metadata ...
+     *
+     * // Apply cropping based on metadata
+     * const ret = frame.applyCropping();
+     * FFmpegError.throwIfError(ret, 'Failed to apply cropping');
+     *
+     * // Frame dimensions are now updated to cropped size
+     * console.log(`Cropped to ${frame.width}x${frame.height}`);
+     * ```
+     */
+    applyCropping(flags?: number): number;
     /**
      * Get the underlying native Frame object.
      *

package/dist/lib/frame.js

@@ -1,7 +1,9 @@
-import { AVMEDIA_TYPE_AUDIO, AVMEDIA_TYPE_UNKNOWN, AVMEDIA_TYPE_VIDEO } from '../constants/constants.js';
+import { AV_NOPTS_VALUE, AV_TIME_BASE_Q, AVMEDIA_TYPE_AUDIO, AVMEDIA_TYPE_UNKNOWN, AVMEDIA_TYPE_VIDEO } from '../constants/constants.js';
 import { bindings } from './binding.js';
+import { FFmpegError } from './error.js';
 import { HardwareFramesContext } from './hardware-frames-context.js';
 import { Rational } from './rational.js';
+import { Dictionary } from './dictionary.js';
 /**
  * Container for uncompressed audio/video data.
  *
@@ -50,6 +52,103 @@ export class Frame {
     constructor() {
         this.native = new bindings.Frame();
     }
+    /**
+     * Create a video frame from a buffer with pixel data.
+     *
+     * Allocates frame buffers, sets properties, and copies buffer data.
+     * Convenience factory method that combines frame allocation and data copy.
+     *
+     * @param buffer - Buffer containing raw pixel data
+     *
+     * @param props - Video Frame properties
+     *
+     * @returns Allocated frame with data from buffer
+     *
+     * @throws {FFmpegError} If allocation or buffer copy fails
+     *
+     * @example
+     * ```typescript
+     * import { Frame, AV_PIX_FMT_RGBA, FFmpegError } from 'node-av';
+     *
+     * const rawPixels = Buffer.alloc(1920 * 1080 * 4); // RGBA data
+     * using frame = Frame.fromVideoBuffer(rawPixels, {
+     *   width: 1920,
+     *   height: 1080,
+     *   format: AV_PIX_FMT_RGBA,
+     *   timeBase: { num: 1, den: 30 }
+     * });
+     * ```
+     */
+    static fromVideoBuffer(buffer, props) {
+        const frame = new Frame();
+        frame.alloc();
+        frame.width = props.width;
+        frame.height = props.height;
+        frame.format = props.format;
+        frame.pts = props.pts ?? AV_NOPTS_VALUE;
+        if (props.timeBase) {
+            frame.timeBase = new Rational(props.timeBase.num, props.timeBase.den);
+        }
+        else {
+            frame.timeBase = Rational.fromObject(AV_TIME_BASE_Q);
+        }
+        if (props.sampleAspectRatio) {
+            frame.sampleAspectRatio = new Rational(props.sampleAspectRatio.num, props.sampleAspectRatio.den);
+        }
+        const ret = frame.getBuffer();
+        FFmpegError.throwIfError(ret, 'Failed to allocate frame buffers');
+        const copyRet = frame.fromBuffer(buffer);
+        FFmpegError.throwIfError(copyRet, 'Failed to copy buffer to frame');
+        return frame;
+    }
+    /**
+     * Create an audio frame from a buffer with sample data.
+     *
+     * Allocates frame buffers, sets properties, and copies buffer data.
+     * Convenience factory method that combines frame allocation and data copy.
+     *
+     * @param buffer - Buffer containing raw audio samples
+     *
+     * @param props - Frame properties
+     *
+     * @returns Allocated frame with data from buffer
+     *
+     * @throws {FFmpegError} If allocation or buffer copy fails
+     *
+     * @example
+     * ```typescript
+     * import { Frame, AV_SAMPLE_FMT_FLT, AV_CH_LAYOUT_STEREO, FFmpegError } from 'node-av';
+     *
+     * const samples = Buffer.alloc(960 * 2 * 4); // 960 samples, stereo, float32
+     * using frame = Frame.fromAudioBuffer(samples, {
+     *   nbSamples: 960,
+     *   format: AV_SAMPLE_FMT_FLT,
+     *   sampleRate: 48000,
+     *   channelLayout: AV_CH_LAYOUT_STEREO,
+     *   timeBase: { num: 1, den: 48000 }
+     * });
+     * ```
+     */
+    static fromAudioBuffer(buffer, props) {
+        const frame = new Frame();
+        frame.alloc();
+        frame.nbSamples = props.nbSamples;
+        frame.format = props.format;
+        frame.sampleRate = props.sampleRate;
+        frame.channelLayout = props.channelLayout;
+        frame.pts = props.pts ?? AV_NOPTS_VALUE;
+        if (props.timeBase) {
+            frame.timeBase = new Rational(props.timeBase.num, props.timeBase.den);
+        }
+        else {
+            frame.timeBase = Rational.fromObject(AV_TIME_BASE_Q);
+        }
+        const ret = frame.getBuffer();
+        FFmpegError.throwIfError(ret, 'Failed to allocate frame buffers');
+        const copyRet = frame.fromBuffer(buffer);
+        FFmpegError.throwIfError(copyRet, 'Failed to copy buffer to frame');
+        return frame;
+    }
     /**
      * Pixel format for video frames or sample format for audio.
      *
@@ -176,6 +275,21 @@ export class Frame {
     set pictType(value) {
         this.native.pictType = value;
     }
+    /**
+     * Quality (between 1 (good) and FF_LAMBDA_MAX (bad)).
+     *
+     * Set by libavcodec for some coded frames.
+     * Can be set before encoding to specify desired quality for encoders that support it.
+     * Used by FFmpeg CLI's frame_encode() to propagate encoder's global_quality setting.
+     *
+     * Direct mapping to AVFrame->quality.
+     */
+    get quality() {
+        return this.native.quality;
+    }
+    set quality(value) {
+        this.native.quality = value;
+    }
     /**
      * Sample aspect ratio.
      *
@@ -358,6 +472,171 @@ export class Frame {
         // Clear the cache as the underlying context has changed
         this._hwFramesCtx = undefined;
     }
+    /**
+     * Frame flags.
+     *
+     * Combination of AVFrameFlags (e.g., AV_FRAME_FLAG_CORRUPT, AV_FRAME_FLAG_KEY).
+     *
+     * Direct mapping to AVFrame->flags.
+     */
+    get flags() {
+        return this.native.flags;
+    }
+    set flags(value) {
+        this.native.flags = value;
+    }
+    /**
+     * Decode error flags.
+     *
+     * Indicates errors detected during decoding.
+     * Non-zero value means the frame may be corrupted.
+     *
+     * Direct mapping to AVFrame->decode_error_flags.
+     */
+    get decodeErrorFlags() {
+        return this.native.decodeErrorFlags;
+    }
+    set decodeErrorFlags(value) {
+        this.native.decodeErrorFlags = value;
+    }
+    /**
+     * Frame duration.
+     *
+     * Duration of this frame in units of time_base.
+     * This is FFmpeg's best guess for how long the frame should be displayed.
+     * May be 0 if unknown or unavailable.
+     *
+     * Direct mapping to AVFrame->duration.
+     */
+    get duration() {
+        return this.native.duration;
+    }
+    set duration(value) {
+        this.native.duration = value;
+    }
+    /**
+     * Number of fields in this frame that should be repeated.
+     *
+     * For interlaced video, indicates how many times the frame should be repeated
+     * when displayed. For progressive video, this is typically 0.
+     * Formula: display_time = (repeat_pict / (2*fps))
+     *
+     * Direct mapping to AVFrame->repeat_pict.
+     */
+    get repeatPict() {
+        return this.native.repeatPict;
+    }
+    set repeatPict(value) {
+        this.native.repeatPict = value;
+    }
+    /**
+     * Set frame flags.
+     *
+     * Sets one or more flags using bitwise OR. Allows setting multiple flags
+     * without manually performing bitwise operations.
+     *
+     * @param flags - One or more flag values to set
+     *
+     * @example
+     * ```typescript
+     * import { AV_FRAME_FLAG_KEY } from 'node-av/constants';
+     *
+     * // Mark frame as key frame
+     * frame.setFlags(AV_FRAME_FLAG_KEY);
+     * ```
+     *
+     * @see {@link clearFlags} To unset flags
+     * @see {@link hasFlags} To check flags
+     * @see {@link flags} For direct flag access
+     */
+    setFlags(...flags) {
+        for (const flag of flags) {
+            this.native.flags |= flag;
+        }
+    }
+    /**
+     * Clear frame flags.
+     *
+     * Clears one or more flags using bitwise AND NOT. Allows clearing multiple
+     * flags without manually performing bitwise operations.
+     *
+     * @param flags - One or more flag values to clear
+     *
+     * @example
+     * ```typescript
+     * import { AV_FRAME_FLAG_CORRUPT } from 'node-av/constants';
+     *
+     * // Clear corrupt flag
+     * frame.clearFlags(AV_FRAME_FLAG_CORRUPT);
+     * ```
+     *
+     * @see {@link setFlags} To set flags
+     * @see {@link hasFlags} To check flags
+     * @see {@link flags} For direct flag access
+     */
+    clearFlags(...flags) {
+        for (const flag of flags) {
+            this.native.flags &= ~flag;
+        }
+    }
+    /**
+     * Check if frame has specific flags.
+     *
+     * Tests whether all specified flags are set using bitwise AND.
+     *
+     * @param flags - One or more flag values to check
+     *
+     * @returns true if all specified flags are set, false otherwise
+     *
+     * @example
+     * ```typescript
+     * import { AV_FRAME_FLAG_CORRUPT } from 'node-av/constants';
+     *
+     * if (frame.hasFlags(AV_FRAME_FLAG_CORRUPT)) {
+     *   console.log('Frame is corrupted');
+     * }
+     * ```
+     *
+     * @see {@link setFlags} To set flags
+     * @see {@link clearFlags} To unset flags
+     * @see {@link flags} For direct flag access
+     */
+    hasFlags(...flags) {
+        for (const flag of flags) {
+            if ((this.native.flags & flag) !== flag) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Check if frame has decode errors.
+     *
+     * Tests whether all specified decode error flags are set using bitwise AND.
+     *
+     * @param flags - One or more decode error flag values to check
+     *
+     * @returns true if all specified error flags are set, false otherwise
+     *
+     * @example
+     * ```typescript
+     * import { FF_DECODE_ERROR_INVALID_BITSTREAM } from 'node-av/constants';
+     *
+     * if (frame.hasDecodeErrorFlags(FF_DECODE_ERROR_INVALID_BITSTREAM)) {
+     *   console.log('Frame has invalid bitstream error');
+     * }
+     * ```
+     *
+     * @see {@link decodeErrorFlags} For direct error flag access
+     */
+    hasDecodeErrorFlags(...flags) {
+        for (const flag of flags) {
+            if ((this.native.decodeErrorFlags & flag) !== flag) {
+                return false;
+            }
+        }
+        return true;
+    }
     /**
      * Check if this is a video frame.
      *
@@ -942,6 +1221,77 @@ export class Frame {
     removeSideData(type) {
         this.native.removeSideData(type);
     }
+    /**
+     * Get frame metadata dictionary.
+     *
+     * Returns metadata attached to the frame by filters or demuxers.
+     * Metadata is stored as key-value pairs in a Dictionary.
+     * Useful for reading filter-generated metadata (e.g., whisper transcription).
+     *
+     * Direct mapping to AVFrame->metadata.
+     *
+     * @returns Dictionary containing frame metadata
+     *
+     * @example
+     * ```typescript
+     * // Read whisper filter metadata
+     * const metadata = frame.getMetadata();
+     * const text = metadata.get('lavfi.whisper.text');
+     * const duration = metadata.get('lavfi.whisper.duration');
+     *
+     * if (text) {
+     *   console.log(`Transcribed: ${text}`);
+     *   console.log(`Duration: ${duration}s`);
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Read scene detection metadata
+     * const metadata = frame.getMetadata();
+     * const score = metadata.get('lavfi.scene_score');
+     * if (score) {
+     *   console.log(`Scene change score: ${score}`);
+     * }
+     * ```
+     *
+     * @see {@link Dictionary} For metadata dictionary operations
+     */
+    getMetadata() {
+        return Dictionary.fromNative(this.native.getMetadata());
+    }
+    /**
+     * Apply cropping to the frame.
+     *
+     * Crops the frame according to its crop metadata (AVFrame crop fields).
+     * This adjusts the frame dimensions and data pointers to reflect the cropped region.
+     * The cropped-out area is discarded, reducing frame size.
+     *
+     * Direct mapping to av_frame_apply_cropping().
+     *
+     * @param flags - Cropping flags (default: AV_FRAME_CROP_UNALIGNED = 1)
+     *                AV_FRAME_CROP_UNALIGNED allows unaligned cropping for lavfi compatibility
+     *
+     * @returns 0 on success, negative error code on failure
+     *
+     * @example
+     * ```typescript
+     * import { Frame, FFmpegError } from 'node-av';
+     *
+     * const frame = new Frame();
+     * // ... decode frame with crop metadata ...
+     *
+     * // Apply cropping based on metadata
+     * const ret = frame.applyCropping();
+     * FFmpegError.throwIfError(ret, 'Failed to apply cropping');
+     *
+     * // Frame dimensions are now updated to cropped size
+     * console.log(`Cropped to ${frame.width}x${frame.height}`);
+     * ```
+     */
+    applyCropping(flags) {
+        return this.native.applyCropping(flags);
+    }
     /**
      * Get the underlying native Frame object.
      *