@revizly/node-av 5.2.2-beta.1

package/dist/api/utilities/channel-layout.d.ts

@@ -0,0 +1,76 @@
+import type { ChannelLayout } from '../../lib/types.js';
+/**
+ * Audio channel layout utilities.
+ *
+ * Provides static methods for describing and working with audio channel layouts.
+ * Channel layouts define the arrangement and meaning of audio channels in
+ * multi-channel audio.
+ *
+ * @example
+ * ```typescript
+ * import { ChannelLayoutUtils } from 'node-av';
+ * import { AV_CHANNEL_ORDER_NATIVE } from 'node-av/constants';
+ *
+ * // Describe a stereo layout
+ * const stereo: ChannelLayout = {
+ *   order: AV_CHANNEL_ORDER_NATIVE,
+ *   nb_channels: 2,
+ *   u: { mask: 0x3n } // FL | FR
+ * };
+ *
+ * const description = ChannelLayoutUtils.describe(stereo);
+ * console.log(description); // "stereo"
+ *
+ * // Describe a 5.1 layout
+ * const surround: ChannelLayout = {
+ *   order: AV_CHANNEL_ORDER_NATIVE,
+ *   nb_channels: 6,
+ *   u: { mask: 0x3Fn } // FL | FR | FC | LFE | BL | BR
+ * };
+ *
+ * console.log(ChannelLayoutUtils.describe(surround)); // "5.1"
+ * ```
+ */
+export declare class ChannelLayoutUtils {
+    private constructor();
+    /**
+     * Get string description of channel layout.
+     *
+     * Returns a human-readable string describing the channel layout.
+     * Direct mapping to av_channel_layout_describe()
+     *
+     * @param channelLayout - Channel layout to describe
+     *
+     * @returns String description, or null on error
+     *
+     * @example
+     * ```typescript
+     * import { ChannelLayoutUtils } from 'node-av';
+     * import { AV_CHANNEL_ORDER_NATIVE, AV_CHANNEL_ORDER_CUSTOM } from 'node-av/constants';
+     *
+     * // Standard layouts
+     * const mono: ChannelLayout = {
+     *   order: AV_CHANNEL_ORDER_NATIVE,
+     *   nb_channels: 1,
+     *   u: { mask: 0x4n } // FC
+     * };
+     * console.log(ChannelLayoutUtils.describe(mono)); // "mono"
+     *
+     * const stereo: ChannelLayout = {
+     *   order: AV_CHANNEL_ORDER_NATIVE,
+     *   nb_channels: 2,
+     *   u: { mask: 0x3n } // FL | FR
+     * };
+     * console.log(ChannelLayoutUtils.describe(stereo)); // "stereo"
+     *
+     * // Custom layout
+     * const custom: ChannelLayout = {
+     *   order: AV_CHANNEL_ORDER_CUSTOM,
+     *   nb_channels: 3,
+     *   u: { map: null }
+     * };
+     * console.log(ChannelLayoutUtils.describe(custom)); // "3 channels"
+     * ```
+     */
+    static describe(channelLayout: Partial<ChannelLayout>): string | null;
+}

package/dist/api/utilities/channel-layout.js

@@ -0,0 +1,80 @@
+import { bindings } from '../../lib/binding.js';
+/**
+ * Audio channel layout utilities.
+ *
+ * Provides static methods for describing and working with audio channel layouts.
+ * Channel layouts define the arrangement and meaning of audio channels in
+ * multi-channel audio.
+ *
+ * @example
+ * ```typescript
+ * import { ChannelLayoutUtils } from 'node-av';
+ * import { AV_CHANNEL_ORDER_NATIVE } from 'node-av/constants';
+ *
+ * // Describe a stereo layout
+ * const stereo: ChannelLayout = {
+ *   order: AV_CHANNEL_ORDER_NATIVE,
+ *   nb_channels: 2,
+ *   u: { mask: 0x3n } // FL | FR
+ * };
+ *
+ * const description = ChannelLayoutUtils.describe(stereo);
+ * console.log(description); // "stereo"
+ *
+ * // Describe a 5.1 layout
+ * const surround: ChannelLayout = {
+ *   order: AV_CHANNEL_ORDER_NATIVE,
+ *   nb_channels: 6,
+ *   u: { mask: 0x3Fn } // FL | FR | FC | LFE | BL | BR
+ * };
+ *
+ * console.log(ChannelLayoutUtils.describe(surround)); // "5.1"
+ * ```
+ */
+export class ChannelLayoutUtils {
+    // Private constructor to prevent instantiation
+    constructor() { }
+    /**
+     * Get string description of channel layout.
+     *
+     * Returns a human-readable string describing the channel layout.
+     * Direct mapping to av_channel_layout_describe()
+     *
+     * @param channelLayout - Channel layout to describe
+     *
+     * @returns String description, or null on error
+     *
+     * @example
+     * ```typescript
+     * import { ChannelLayoutUtils } from 'node-av';
+     * import { AV_CHANNEL_ORDER_NATIVE, AV_CHANNEL_ORDER_CUSTOM } from 'node-av/constants';
+     *
+     * // Standard layouts
+     * const mono: ChannelLayout = {
+     *   order: AV_CHANNEL_ORDER_NATIVE,
+     *   nb_channels: 1,
+     *   u: { mask: 0x4n } // FC
+     * };
+     * console.log(ChannelLayoutUtils.describe(mono)); // "mono"
+     *
+     * const stereo: ChannelLayout = {
+     *   order: AV_CHANNEL_ORDER_NATIVE,
+     *   nb_channels: 2,
+     *   u: { mask: 0x3n } // FL | FR
+     * };
+     * console.log(ChannelLayoutUtils.describe(stereo)); // "stereo"
+     *
+     * // Custom layout
+     * const custom: ChannelLayout = {
+     *   order: AV_CHANNEL_ORDER_CUSTOM,
+     *   nb_channels: 3,
+     *   u: { map: null }
+     * };
+     * console.log(ChannelLayoutUtils.describe(custom)); // "3 channels"
+     * ```
+     */
+    static describe(channelLayout) {
+        return bindings.avChannelLayoutDescribe(channelLayout);
+    }
+}
+//# sourceMappingURL=channel-layout.js.map

package/dist/api/utilities/channel-layout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-layout.js","sourceRoot":"","sources":["../../../src/api/utilities/channel-layout.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAIhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,OAAO,kBAAkB;IAC7B,+CAA+C;IAC/C,gBAAuB,CAAC;IAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IACH,MAAM,CAAC,QAAQ,CAAC,aAAqC;QACnD,OAAO,QAAQ,CAAC,uBAAuB,CAAC,aAAa,CAAC,CAAC;IACzD,CAAC;CACF"}

package/dist/api/utilities/electron-shared-texture.d.ts

@@ -0,0 +1,328 @@
+import { Frame } from '../../lib/frame.js';
+import type { AVPixelFormat } from '../../constants/constants.js';
+import type { IRational } from '../../lib/types.js';
+import type { HardwareContext } from '../hardware.js';
+/**
+ * Electron SharedTextureHandle (textureInfo.handle).
+ *
+ * Platform-specific GPU texture handles provided by Electron's offscreen rendering
+ * with shared textures enabled.
+ */
+export interface SharedTextureHandle {
+    ioSurface?: Buffer;
+    ntHandle?: Buffer;
+    nativePixmap?: {
+        planes: {
+            fd: number;
+            stride: number;
+            offset: number;
+            size: number;
+        }[];
+        modifier: string;
+    };
+}
+/**
+ * Electron color space descriptor from textureInfo.colorSpace.
+ */
+export interface TextureColorSpace {
+    range?: 'limited' | 'full' | 'derived' | 'invalid';
+    primaries?: string;
+    transfer?: string;
+    matrix?: string;
+}
+/**
+ * Electron textureInfo object.
+ *
+ * Contains GPU texture metadata and platform-specific handle for zero-copy frame import.
+ */
+export interface TextureInfo {
+    pixelFormat: string;
+    codedSize: {
+        width: number;
+        height: number;
+    };
+    colorSpace?: TextureColorSpace;
+    handle: SharedTextureHandle;
+}
+/**
+ * Options for each frame import via {@link SharedTexture.importTexture} or {@link SharedTexture.importHandle}.
+ */
+export interface TextureFrameOptions {
+    pts?: bigint;
+    timeBase?: IRational;
+}
+/**
+ * Options for {@link SharedTexture.create}.
+ */
+export interface SharedTextureOptions {
+    width?: number;
+    height?: number;
+    swFormat?: AVPixelFormat;
+}
+/**
+ * Properties for importing a raw GPU texture handle via {@link SharedTexture.importHandle}.
+ */
+export interface ImportHandleProps {
+    width: number;
+    height: number;
+    pixelFormat?: string | AVPixelFormat;
+    pts?: bigint;
+    timeBase?: IRational;
+}
+/**
+ * High-level GPU texture import for Electron shared textures.
+ *
+ * Handles platform detection (macOS IOSurface, Windows D3D11,
+ * Linux DMA-BUF), HardwareFramesContext lifecycle, and format mapping automatically.
+ *
+ * @example
+ * ```typescript
+ * import { HardwareContext, SharedTexture } from 'node-av/api';
+ *
+ * const hw = HardwareContext.auto();
+ * using sharedTexture = SharedTexture.create(hw);
+ *
+ * // In Electron paint event:
+ * offscreen.webContents.on('paint', (event) => {
+ *   const texture = event.texture;
+ *   if (!texture?.textureInfo) return;
+ *
+ *   using frame = sharedTexture.importTexture(texture.textureInfo, { pts: 0n });
+ *   // frame is a hardware Frame ready for encoding/filtering
+ *
+ *   texture.release();
+ * });
+ * ```
+ *
+ * @see {@link HardwareContext} For hardware acceleration setup
+ * @see {@link Frame} For frame operations
+ */
+export declare class SharedTexture implements Disposable {
+    private _hardware;
+    private _framesCtx;
+    private _currentWidth;
+    private _currentHeight;
+    private _swFormat;
+    private _isDisposed;
+    private _mappingCtx;
+    private _mappingHw;
+    private constructor();
+    /**
+     * Create a SharedTexture.
+     *
+     * @param hardware - Initialized hardware context (from HardwareContext.auto() or HardwareContext.create())
+     *
+     * @param options - Optional configuration overrides
+     *
+     * @returns SharedTexture instance
+     *
+     * @example
+     * ```typescript
+     * const hw = HardwareContext.auto();
+     * using sharedTexture = SharedTexture.create(hw);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // With explicit software format
+     * import { AV_PIX_FMT_NV12 } from 'node-av/constants';
+     *
+     * using sharedTexture = SharedTexture.create(hw, { swFormat: AV_PIX_FMT_NV12 });
+     * ```
+     */
+    static create(hardware: HardwareContext, options?: SharedTextureOptions): SharedTexture;
+    /**
+     * The hardware context used by this sharedTexture.
+     */
+    get hardware(): HardwareContext;
+    /**
+     * Current width of the cached HardwareFramesContext.
+     */
+    get width(): number;
+    /**
+     * Current height of the cached HardwareFramesContext.
+     */
+    get height(): number;
+    /**
+     * Whether this sharedTexture has been disposed.
+     */
+    get isDisposed(): boolean;
+    /**
+     * Import an Electron textureInfo as a hardware Frame.
+     *
+     * Automatically detects the platform from the handle contents,
+     * manages the HardwareFramesContext, and creates a zero-copy hardware frame.
+     *
+     * @param textureInfo - Electron's textureInfo object from paint event
+     *
+     * @param options - Per-frame options (pts, timeBase)
+     *
+     * @returns Hardware Frame referencing the GPU texture
+     *
+     * @throws {Error} If disposed, no valid handle found, or import fails
+     *
+     * @example
+     * ```typescript
+     * offscreen.webContents.on('paint', (event) => {
+     *   const texture = event.texture;
+     *   if (!texture?.textureInfo) return;
+     *
+     *   using frame = sharedTexture.importTexture(texture.textureInfo, {
+     *     pts: BigInt(Date.now()) * 1000n,
+     *     timeBase: { num: 1, den: 1000000 },
+     *   });
+     *
+     *   texture.release();
+     * });
+     * ```
+     */
+    importTexture(textureInfo: TextureInfo, options?: TextureFrameOptions): Frame;
+    /**
+     * Import a raw SharedTextureHandle as a hardware Frame.
+     *
+     * Use this when you have the handle directly without the full textureInfo wrapper.
+     *
+     * @param handle - Platform-specific GPU texture handle
+     *
+     * @param props - Dimensions, format, and timing options
+     *
+     * @returns Hardware Frame referencing the GPU texture
+     *
+     * @throws {Error} If disposed, no valid handle found, or import fails
+     *
+     * @example
+     * ```typescript
+     * const frame = sharedTexture.importHandle(handle, {
+     *   width: 1920,
+     *   height: 1080,
+     *   pixelFormat: 'BGRA',
+     *   pts: 0n,
+     * });
+     * ```
+     */
+    importHandle(handle: SharedTextureHandle, props: ImportHandleProps): Frame;
+    /**
+     * Map a frame to a different hardware format.
+     *
+     * Handles HardwareFramesContext creation and caching automatically.
+     * The mapping context is cached and reused for subsequent calls with the
+     * same target hardware and frame dimensions.
+     *
+     * @param srcFrame - Source frame (e.g., DRM PRIME from importTexture on Linux)
+     *
+     * @param targetHw - Target hardware context (e.g., VAAPI, Vulkan)
+     *
+     * @param flags - Mapping flags
+     *
+     * @returns Mapped frame in target hardware format
+     *
+     * @throws {FFmpegError} If mapping fails (e.g., unsupported mapping, invalid frames)
+     *
+     * @example
+     * ```typescript
+     * import { HardwareContext, SharedTexture } from 'node-av/api';
+     * import { AV_HWDEVICE_TYPE_VAAPI } from 'node-av/constants';
+     *
+     * // Import DRM PRIME frame from Electron shared texture
+     * const drmFrame = sharedTexture.importTexture(textureInfo, { pts: 0n });
+     *
+     * // Map to VAAPI for encoding
+     * const vaapiHw = HardwareContext.create(AV_HWDEVICE_TYPE_VAAPI);
+     * const vaapiFrame = sharedTexture.mapTo(drmFrame, vaapiHw);
+     *
+     * // Encode with VAAPI encoder
+     * encoder.encode(vaapiFrame);
+     * ```
+     */
+    mapTo(srcFrame: Frame, targetHw: HardwareContext, flags?: number): Frame;
+    /**
+     * Ensure mapping context exists and matches the target hardware and frame dimensions.
+     *
+     * Re-creates the context if target hardware changes or dimensions change.
+     *
+     * @param srcFrame - Source frame to get dimensions from
+     *
+     * @param targetHw - Target hardware context
+     *
+     * @internal
+     */
+    private ensureMappingContext;
+    /**
+     * Release the cached HardwareFramesContext and mapping context.
+     *
+     * The HardwareContext is NOT disposed — it belongs to the caller.
+     * Safe to call multiple times.
+     *
+     * @example
+     * ```typescript
+     * sharedTexture.dispose();
+     * ```
+     */
+    dispose(): void;
+    /**
+     * Core import logic — dispatches to the correct Frame factory based on handle type.
+     *
+     * @param handle - Platform-specific GPU texture handle
+     *
+     * @param width - Texture width in pixels
+     *
+     * @param height - Texture height in pixels
+     *
+     * @param swFormat - Software pixel format for HardwareFramesContext
+     *
+     * @param options - Per-frame timing options
+     *
+     * @param colorSpace - Electron color space descriptor for mapping to FFmpeg color properties
+     *
+     * @returns Hardware Frame referencing the GPU texture
+     *
+     * @internal
+     */
+    private importFromHandle;
+    /**
+     * Ensure HardwareFramesContext is created and matches the requested dimensions/format.
+     *
+     * Re-creates the context only when dimensions or format change.
+     * Windows D3D11 does not use this — it passes HardwareDeviceContext directly.
+     *
+     * @param width - Frame width in pixels
+     *
+     * @param height - Frame height in pixels
+     *
+     * @param swFormat - Software pixel format
+     *
+     * @returns Initialized HardwareFramesContext matching the requested parameters
+     *
+     * @internal
+     */
+    private ensureFramesContext;
+    /**
+     * Resolve a pixel format string (e.g., 'BGRA') to an AVPixelFormat enum value.
+     *
+     * Falls back to the configured swFormat if the name is not recognized.
+     *
+     * @param name - Pixel format name string from Electron
+     *
+     * @returns Resolved AVPixelFormat enum value
+     *
+     * @internal
+     */
+    private resolvePixelFormat;
+    /**
+     * Dispose of the SharedTexture.
+     *
+     * Implements the Disposable interface for automatic cleanup.
+     * Equivalent to calling dispose().
+     *
+     * @example
+     * ```typescript
+     * {
+     *   using sharedTexture = SharedTexture.create(hw);
+     *   // Use sharedTexture...
+     * } // Automatically disposed
+     * ```
+     *
+     * @see {@link dispose} For manual cleanup
+     */
+    [Symbol.dispose](): void;
+}