node-av 6.2.0-beta.9 → 7.0.0-beta.1

package/dist/api/utilities/scale-size.js

@@ -0,0 +1,55 @@
+/**
+ * Resolve a scale target where -1 keeps the source aspect ratio.
+ *
+ * Like the scale filter's -2: the derived side is rounded to an even number so
+ * 4:2:0 encoders accept it. Both sides -1 keeps the source size.
+ *
+ * @param srcWidth - Source width
+ *
+ * @param srcHeight - Source height
+ *
+ * @param width - Target width, or -1 to derive it from the height
+ *
+ * @param height - Target height, or -1 to derive it from the width
+ *
+ * @returns The target size
+ *
+ * @internal
+ */
+export function resolveScaleSize(srcWidth, srcHeight, width, height) {
+    if (width < 0 && height < 0) {
+        return { width: srcWidth, height: srcHeight };
+    }
+    if (width < 0) {
+        return { width: Math.max(2, Math.round((height * srcWidth) / srcHeight / 2) * 2), height };
+    }
+    if (height < 0) {
+        return { width, height: Math.max(2, Math.round((width * srcHeight) / srcWidth / 2) * 2) };
+    }
+    return { width, height };
+}
+/**
+ * Scale target and output size of a transcode, never larger than the source.
+ *
+ * A requested width or height above the source keeps the source size, since a
+ * bigger picture only raises the bitrate.
+ *
+ * @param srcWidth - Source width, 0 when unknown before the first frame
+ *
+ * @param srcHeight - Source height, 0 when unknown before the first frame
+ *
+ * @param width - Requested width, or -1 to derive it from the height
+ *
+ * @param height - Requested height, or -1 to derive it from the width
+ *
+ * @returns The target for the scale filter (-1 follows the source) and the
+ * resolved output size, undefined while the source size is unknown
+ *
+ * @internal
+ */
+export function transcodeScale(srcWidth, srcHeight, width = -1, height = -1) {
+    const known = srcWidth > 0 && srcHeight > 0;
+    const target = known && (width > srcWidth || height > srcHeight) ? { width: -1, height: -1 } : { width, height };
+    return { target, output: known ? resolveScaleSize(srcWidth, srcHeight, target.width, target.height) : undefined };
+}
+//# sourceMappingURL=scale-size.js.map

package/dist/api/utilities/scale-size.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scale-size.js","sourceRoot":"","sources":["../../../src/api/utilities/scale-size.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB,EAAE,SAAiB,EAAE,KAAa,EAAE,MAAc;IACjG,IAAI,KAAK,GAAG,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAChD,CAAC;IACD,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACd,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,QAAQ,CAAC,GAAG,SAAS,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7F,CAAC;IACD,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;QACf,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,GAAG,SAAS,CAAC,GAAG,QAAQ,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;IAC5F,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,cAAc,CAC5B,QAAgB,EAChB,SAAiB,EACjB,KAAK,GAAG,CAAC,CAAC,EACV,MAAM,GAAG,CAAC,CAAC;IAEX,MAAM,KAAK,GAAG,QAAQ,GAAG,CAAC,IAAI,SAAS,GAAG,CAAC,CAAC;IAC5C,MAAM,MAAM,GAAG,KAAK,IAAI,CAAC,KAAK,GAAG,QAAQ,IAAI,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IACjH,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,gBAAgB,CAAC,QAAQ,EAAE,SAAS,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC;AACpH,CAAC"}

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;