node-av-light 0.0.0 → 7.1.0-beta.1

package/dist/api/utilities/timestamp.js

@@ -0,0 +1,206 @@
+import { bindings } from '../../lib/binding.js';
+/**
+ * Timestamp and time base utilities.
+ *
+ * Provides static methods for converting, rescaling, and comparing timestamps.
+ * These utilities are essential for working with different time bases in
+ * multimedia streams.
+ *
+ * @example
+ * ```typescript
+ * import { TimestampUtils } from 'node-av';
+ * import { AV_ROUND_NEAR_INF } from 'node-av/constants';
+ *
+ * // Convert timestamp to string representations
+ * const pts = 450000n;
+ * console.log(TimestampUtils.toString(pts));                    // "450000"
+ *
+ * const timebase = { num: 1, den: 90000 };
+ * console.log(TimestampUtils.toTimeString(pts, timebase));      // "5.000000"
+ *
+ * // Rescale between time bases
+ * const srcTb = { num: 1, den: 90000 };
+ * const dstTb = { num: 1, den: 1000 };
+ * const rescaled = TimestampUtils.rescale(pts, srcTb, dstTb);
+ * console.log(rescaled);                                         // 5000n
+ * ```
+ */
+export class TimestampUtils {
+    // Private constructor to prevent instantiation
+    constructor() { }
+    /**
+     * Convert timestamp to string.
+     *
+     * Converts a timestamp value to its string representation.
+     * Handles special values like AV_NOPTS_VALUE.
+     * Direct mapping to av_ts2str()
+     *
+     * @param ts - Timestamp value (bigint or number), or null
+     *
+     * @returns String representation
+     *
+     * @example
+     * ```typescript
+     * import { TimestampUtils } from 'node-av';
+     * import { AV_NOPTS_VALUE } from 'node-av/constants';
+     *
+     * console.log(TimestampUtils.toString(12345n));        // "12345"
+     * console.log(TimestampUtils.toString(AV_NOPTS_VALUE)); // "NOPTS"
+     * console.log(TimestampUtils.toString(null));          // "NOPTS"
+     * ```
+     */
+    static toString(ts) {
+        return bindings.avTs2Str(ts);
+    }
+    /**
+     * Convert timestamp to time string.
+     *
+     * Converts a timestamp to a time string in seconds using the provided time base.
+     * Direct mapping to av_ts2timestr()
+     *
+     * @param ts - Timestamp value
+     *
+     * @param timeBase - Time base for conversion
+     *
+     * @returns Time string in seconds with decimal places
+     *
+     * @example
+     * ```typescript
+     * import { TimestampUtils } from 'node-av';
+     *
+     * const pts = 450000n;
+     * const timebase = { num: 1, den: 90000 }; // 90kHz
+     *
+     * console.log(TimestampUtils.toTimeString(pts, timebase));     // "5.000000"
+     * console.log(TimestampUtils.toTimeString(90000n, timebase));  // "1.000000"
+     * ```
+     */
+    static toTimeString(ts, timeBase) {
+        return bindings.avTs2TimeStr(ts, timeBase);
+    }
+    /**
+     * Compare timestamps from different time bases.
+     *
+     * Compares two timestamps that may have different time bases.
+     * Direct mapping to av_compare_ts()
+     *
+     * @param tsA - First timestamp
+     *
+     * @param tbA - Time base of first timestamp
+     *
+     * @param tsB - Second timestamp
+     *
+     * @param tbB - Time base of second timestamp
+     *
+     * @returns -1 if tsA < tsB, 0 if equal, 1 if tsA > tsB
+     *
+     * @example
+     * ```typescript
+     * import { TimestampUtils } from 'node-av';
+     *
+     * // Compare timestamps from different time bases
+     * const pts1 = 90000n;
+     * const tb1 = { num: 1, den: 90000 };  // 1 second in 90kHz
+     *
+     * const pts2 = 1000n;
+     * const tb2 = { num: 1, den: 1000 };   // 1 second in 1kHz
+     *
+     * const result = TimestampUtils.compare(pts1, tb1, pts2, tb2);
+     * console.log(result); // 0 (equal - both represent 1 second)
+     * ```
+     */
+    static compare(tsA, tbA, tsB, tbB) {
+        return bindings.avCompareTs(tsA, tbA, tsB, tbB);
+    }
+    /**
+     * Rescale timestamp from one time base to another.
+     *
+     * Converts a timestamp from source time base to destination time base.
+     * Uses AV_ROUND_NEAR_INF rounding.
+     * 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
+     * import { TimestampUtils } from 'node-av';
+     *
+     * // Convert from 90kHz to milliseconds
+     * const pts = 450000n;
+     * const srcTb = { num: 1, den: 90000 };
+     * const dstTb = { num: 1, den: 1000 };
+     *
+     * const rescaled = TimestampUtils.rescale(pts, srcTb, dstTb);
+     * console.log(rescaled); // 5000n (5000 milliseconds = 5 seconds)
+     * ```
+     */
+    static rescale(a, bq, cq) {
+        return bindings.avRescaleQ(a, bq, cq);
+    }
+    /**
+     * Rescale with specified rounding.
+     *
+     * Rescales a value with explicit rounding mode.
+     * More general than rescale() as it doesn't use time bases.
+     * Direct mapping to av_rescale_rnd()
+     *
+     * @param a - Value to rescale
+     *
+     * @param b - Multiplier
+     *
+     * @param c - Divisor
+     *
+     * @param rnd - Rounding mode
+     *
+     * @returns Rescaled value: a * b / c
+     *
+     * @example
+     * ```typescript
+     * import { TimestampUtils } from 'node-av';
+     * import { AV_ROUND_UP, AV_ROUND_DOWN } from 'node-av/constants';
+     *
+     * // Scale with different rounding modes
+     * const value = 100n;
+     * const mul = 3n;
+     * const div = 7n;
+     *
+     * const roundUp = TimestampUtils.rescaleRounded(value, mul, div, AV_ROUND_UP);
+     * const roundDown = TimestampUtils.rescaleRounded(value, mul, div, AV_ROUND_DOWN);
+     *
+     * console.log(roundUp);   // 43n (rounds up)
+     * console.log(roundDown); // 42n (rounds down)
+     * ```
+     */
+    static rescaleRounded(a, b, c, rnd) {
+        return bindings.avRescaleRnd(a, b, c, rnd);
+    }
+    /**
+     * Sleep for specified microseconds.
+     *
+     * Sleeps for the specified number of microseconds.
+     * Direct mapping to av_usleep()
+     *
+     * @param usec - Microseconds to sleep
+     *
+     * @example
+     * ```typescript
+     * import { TimestampUtils } from 'node-av';
+     *
+     * // Sleep for 100 milliseconds
+     * TimestampUtils.sleep(100000);
+     *
+     * // Sleep for 1 second
+     * TimestampUtils.sleep(1000000);
+     * ```
+     */
+    static sleep(usec) {
+        bindings.avUsleep(usec);
+    }
+}
+//# sourceMappingURL=timestamp.js.map

package/dist/api/utilities/timestamp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timestamp.js","sourceRoot":"","sources":["../../../src/api/utilities/timestamp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAKhD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,OAAO,cAAc;IACzB,+CAA+C;IAC/C,gBAAuB,CAAC;IAExB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,QAAQ,CAAC,EAA0B;QACxC,OAAO,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IAC/B,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,YAAY,CAAC,EAA0B,EAAE,QAAmB;QACjE,OAAO,QAAQ,CAAC,YAAY,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;IAC7C,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,MAAM,CAAC,OAAO,CAAC,GAA2B,EAAE,GAAc,EAAE,GAA2B,EAAE,GAAc;QACrG,OAAO,QAAQ,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IAClD,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,MAAM,CAAC,OAAO,CAAC,CAAyB,EAAE,EAAa,EAAE,EAAa;QACpE,OAAO,QAAQ,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IACxC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,MAAM,CAAC,cAAc,CAAC,CAAkB,EAAE,CAAkB,EAAE,CAAkB,EAAE,GAAe;QAC/F,OAAO,QAAQ,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC;IAC7C,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,KAAK,CAAC,IAAY;QACvB,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;CACF"}

package/dist/api/utilities/video-transcode.d.ts

@@ -0,0 +1,218 @@
+import { Codec } from '../../lib/codec.js';
+import { Frame } from '../../lib/frame.js';
+import { Decoder } from '../decoder.js';
+import { FilterAPI } from '../filter.js';
+import type { AVCodecID, AVPixelFormat } from '../../constants/index.js';
+import type { CodecContext } from '../../lib/codec-context.js';
+import type { Stream } from '../../lib/stream.js';
+import type { DecoderOptions } from '../decoder.js';
+import type { EncoderOptions } from '../encoder.js';
+import type { BaseCodecName, HardwareContext } from '../hardware.js';
+/**
+ * What the video encoder of a transcode has to receive.
+ *
+ * @internal
+ */
+export interface VideoTranscodeTarget {
+    /** Output width, -1 to keep the source width or follow the height */
+    width: number;
+    /** Output height, -1 to keep the source height or follow the width */
+    height: number;
+    /** Output frame rate, when it changes */
+    fps?: number;
+    /** The encoder */
+    encoder: Codec;
+    /** The device the frames are decoded and filtered on */
+    hardware?: HardwareContext | null;
+}
+/**
+ * A frame as the transcode graph sees it.
+ *
+ * @internal
+ */
+export interface VideoGraphInput {
+    /** The frame lives on a device */
+    hw: boolean;
+    /** The frame lives on the transcode's device */
+    onDevice: boolean;
+    /** Pixel format, the software format of device frames */
+    format: AVPixelFormat;
+    width: number;
+    height: number;
+}
+/**
+ * Filters a device has for a transcode.
+ *
+ * @internal
+ */
+export interface DeviceFilters {
+    /** Scales and converts the pixel format on the device */
+    scaler: boolean;
+    /** Uploads software frames well enough to scale them there instead of on the CPU */
+    upload: boolean;
+}
+/**
+ * Build the filter graph that brings a decoded frame to the video encoder of a transcode.
+ *
+ * Frames stay on the device whenever the encoder takes them there, and scaling
+ * and format conversion run on the device whenever it has a scaler. Hardware
+ * encoders get 8-bit 4:2:0 in NV12: VAAPI decodes JPEG into planar or 4:2:2
+ * surfaces and 10-bit sources come as P010, which H.264 hardware encoders reject.
+ * Software encoders get yuv420p when the frames have to be converted anyway, it
+ * is the layout every browser and HomeKit decodes (unlike the 4:2:2 profile x264
+ * picks for a 4:2:2 JPEG camera). Packed sources such as yuyv422 are converted
+ * too, swscale cannot scale them in place.
+ *
+ * Decided per frame, not per stream: a hardware decoder falls back to software
+ * frames for input it cannot handle, e.g. 4:2:2 JPEG on NVDEC.
+ *
+ * @param input - The frame
+ *
+ * @param target - The encoder's needs
+ *
+ * @param filters - What the target's device has, see {@link findDeviceFilters}
+ *
+ * @returns The filter description, `null` when the frame can go to the encoder as it is
+ *
+ * @internal
+ */
+export declare function videoTranscodeGraph(input: VideoGraphInput, target: VideoTranscodeTarget, filters: DeviceFilters): string;
+/**
+ * Describe a decoded frame for {@link videoTranscodeGraph}.
+ *
+ * @param frame - The frame
+ *
+ * @param hardware - The transcode's device, if any
+ *
+ * @returns Where the frame lives, its format and size
+ *
+ * @internal
+ */
+export declare function describeVideoFrame(frame: Frame, hardware?: HardwareContext | null): VideoGraphInput;
+/**
+ * Create the filter between the video decoder (or frame source) and the encoder of a transcode.
+ *
+ * The graph is built by {@link videoTranscodeGraph} from the first frame and
+ * again whenever the frames change, e.g. when the decoder falls back to software.
+ * A graph whose device filters fail to configure is replaced by one that
+ * converts in software.
+ *
+ * @param target - The encoder's needs
+ *
+ * @param filters - The device's filters, found by default
+ *
+ * @returns The filter
+ *
+ * @internal
+ */
+export declare function createVideoTranscodeFilter(target: VideoTranscodeTarget, filters?: DeviceFilters): FilterAPI;
+/**
+ * Open the video decoder of a transcode, on the device unless it fails to open there.
+ *
+ * A device decoder that opens but then produces nothing moves to software on
+ * its own ({@link DecoderOptions.hardwareFallback}).
+ *
+ * @param stream - The video stream
+ *
+ * @param hardware - The device to decode on, if any
+ *
+ * @param options - Decoder options besides the device
+ *
+ * @returns The decoder
+ *
+ * @throws {FFmpegError} If no software decoder opens either
+ *
+ * @internal
+ */
+export declare function openTranscodeDecoder(stream: Stream, hardware: HardwareContext | null | undefined, options: DecoderOptions): Promise<Decoder>;
+/**
+ * Set the video bitrate on the encoder context.
+ *
+ * Sets the target bitrate together with a VBV cap (maxrate + a 1s buffer).
+ * Encoder.create() always seeds a default target bitrate (1 Mbps for video),
+ * so the target MUST be set along with the cap, a cap above the seeded target
+ * changes nothing. Without a bitrate the target follows the picture size and
+ * frame rate, see {@link defaultVideoBitrate}.
+ *
+ * @param ctx - Encoder codec context
+ *
+ * @param bitrate - Maximum bitrate in bits per second, or undefined
+ *
+ * @internal
+ */
+export declare function applyVideoBitrate(ctx: CodecContext, bitrate: number | undefined): void;
+/**
+ * Find the software encoder for a codec.
+ *
+ * FFmpeg picks the first encoder registered for a codec. The Linux arm64
+ * builds register the Rockchip MPP encoders ahead of libx264 and libx265, and
+ * those fail to open on every other arm64 machine, e.g. a Raspberry Pi.
+ *
+ * @param codecId - The codec to encode
+ *
+ * @returns The first encoder for the codec that is no hardware encoder, FFmpeg's pick when there is none
+ *
+ * @internal
+ */
+export declare function findSoftwareEncoder(codecId: AVCodecID): Codec | null;
+/**
+ * Find the device's encoder for a codec, if it works on this machine.
+ *
+ * @param hardware - The device, if any
+ *
+ * @param codec - The codec to encode
+ *
+ * @param options - Encoder options the encoder will get, some drivers need them to open (e.g. `low_power`)
+ *
+ * @param size - The size it will encode, hardware encoders have a maximum that differs per GPU
+ *
+ * @param size.width - Width
+ *
+ * @param size.height - Height
+ *
+ * @returns The hardware encoder, or null to encode in software
+ *
+ * @internal
+ */
+export declare function findUsableHardwareEncoder(hardware: HardwareContext | null | undefined, codec: BaseCodecName | AVCodecID, options?: EncoderOptions['options'], size?: {
+    width: number;
+    height: number;
+}): Promise<Codec | null>;
+/**
+ * Check whether a hardware encoder works on this machine, by encoding a test frame once.
+ *
+ * Finding an encoder says nothing about the driver: NVENC refuses to open
+ * when the driver is older than the API it was built against, many GPUs have
+ * no encoder at all. A failed encoder is passed over for a minute, then tried
+ * again. Concurrent callers share one test.
+ *
+ * @param encoder - The hardware encoder
+ *
+ * @param hardware - The device it encodes on
+ *
+ * @param options - Encoder options the encoder will get
+ *
+ * @param size - Size of the test frame
+ *
+ * @param size.width - Width
+ *
+ * @param size.height - Height
+ *
+ * @returns Whether it encoded the frame
+ *
+ * @internal
+ */
+export declare function canEncodeOnDevice(encoder: Codec, hardware: HardwareContext, options?: EncoderOptions['options'], size?: {
+    width: number;
+    height: number;
+}): Promise<boolean>;
+/**
+ * Find out which transcode filters a device has in this FFmpeg build.
+ *
+ * @param hardware - The device, if any
+ *
+ * @returns Its filters, none without a device
+ *
+ * @internal
+ */
+export declare function findDeviceFilters(hardware: HardwareContext | null | undefined): DeviceFilters;