node-av 6.2.0-beta.31 → 6.2.0-beta.33

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

@@ -0,0 +1,183 @@
+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 { 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>;
+/**
+ * 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`)
+ *
+ * @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']): 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
+ *
+ * @returns Whether it encoded the frame
+ *
+ * @internal
+ */
+export declare function canEncodeOnDevice(encoder: Codec, hardware: HardwareContext, options?: EncoderOptions['options']): 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;