node-av 1.0.3 → 1.2.0

package/dist/api/hardware.js

@@ -1,101 +1,108 @@
+import { AV_CODEC_HW_CONFIG_METHOD_HW_DEVICE_CTX, AV_CODEC_HW_CONFIG_METHOD_HW_FRAMES_CTX, AV_HWDEVICE_TYPE_CUDA, AV_HWDEVICE_TYPE_D3D11VA, AV_HWDEVICE_TYPE_D3D12VA, AV_HWDEVICE_TYPE_DRM, AV_HWDEVICE_TYPE_DXVA2, AV_HWDEVICE_TYPE_MEDIACODEC, AV_HWDEVICE_TYPE_NONE, AV_HWDEVICE_TYPE_OPENCL, AV_HWDEVICE_TYPE_QSV, AV_HWDEVICE_TYPE_RKMPP, AV_HWDEVICE_TYPE_VAAPI, AV_HWDEVICE_TYPE_VDPAU, AV_HWDEVICE_TYPE_VIDEOTOOLBOX, AV_HWDEVICE_TYPE_VULKAN, AV_PIX_FMT_CUDA, AV_PIX_FMT_D3D11, AV_PIX_FMT_D3D12, AV_PIX_FMT_DRM_PRIME, AV_PIX_FMT_DXVA2_VLD, AV_PIX_FMT_MEDIACODEC, AV_PIX_FMT_NV12, AV_PIX_FMT_OPENCL, AV_PIX_FMT_QSV, AV_PIX_FMT_VAAPI, AV_PIX_FMT_VIDEOTOOLBOX, AV_PIX_FMT_VULKAN, } from '../constants/constants.js';
+import { Codec, CodecContext, Dictionary, HardwareDeviceContext, Rational } from '../lib/index.js';
+import { HardwareFilterPresets } from './filter-presets.js';
 /**
- * HardwareContext - High-level Hardware Acceleration API
+ * High-level hardware acceleration management.
  *
- * Provides simplified access to hardware acceleration features.
- * Automatically detects and configures hardware devices for encoding/decoding.
- *
- * Wraps the low-level HardwareDeviceContext and HardwareFramesContext.
- * Manages lifecycle of hardware resources with automatic cleanup.
- *
- * @module api/hardware
- */
-import { AV_CODEC_HW_CONFIG_METHOD_HW_DEVICE_CTX, AV_CODEC_HW_CONFIG_METHOD_HW_FRAMES_CTX, AV_HWDEVICE_TYPE_CUDA, AV_HWDEVICE_TYPE_D3D11VA, AV_HWDEVICE_TYPE_D3D12VA, AV_HWDEVICE_TYPE_DRM, AV_HWDEVICE_TYPE_DXVA2, AV_HWDEVICE_TYPE_MEDIACODEC, AV_HWDEVICE_TYPE_NONE, AV_HWDEVICE_TYPE_OPENCL, AV_HWDEVICE_TYPE_QSV, AV_HWDEVICE_TYPE_VAAPI, AV_HWDEVICE_TYPE_VDPAU, AV_HWDEVICE_TYPE_VIDEOTOOLBOX, AV_HWDEVICE_TYPE_VULKAN, AV_PIX_FMT_CUDA, AV_PIX_FMT_D3D11, AV_PIX_FMT_D3D12, AV_PIX_FMT_DRM_PRIME, AV_PIX_FMT_DXVA2_VLD, AV_PIX_FMT_MEDIACODEC, AV_PIX_FMT_NV12, AV_PIX_FMT_OPENCL, AV_PIX_FMT_QSV, AV_PIX_FMT_VAAPI, AV_PIX_FMT_VIDEOTOOLBOX, AV_PIX_FMT_VULKAN, Codec, Dictionary, FFmpegError, HardwareDeviceContext, HardwareFramesContext, } from '../lib/index.js';
-/**
- * HardwareContext - Simplified hardware acceleration management.
- *
- * Provides automatic detection and configuration of hardware acceleration.
- * Manages device contexts and frame contexts for hardware encoding/decoding.
- *
- * Supports various hardware types including VideoToolbox (macOS), CUDA,
- * VAAPI (Linux), D3D11VA/D3D12VA (Windows), and more.
+ * Provides automatic detection and configuration of hardware acceleration for media processing.
+ * Manages device contexts for GPU-accelerated encoding and decoding operations.
+ * Supports various hardware types including VideoToolbox, CUDA, VAAPI, D3D11VA, and more.
+ * Essential for high-performance video processing with reduced CPU usage.
  *
  * @example
  * ```typescript
  * import { HardwareContext } from 'node-av/api';
+ * import { AV_HWDEVICE_TYPE_CUDA } from 'node-av/constants';
  *
  * // Auto-detect best available hardware
- * const hw = await HardwareContext.auto();
+ * const hw = HardwareContext.auto();
  * if (hw) {
- *   console.log(`Using hardware: ${hw.deviceType}`);
- *   decoder.hwDeviceCtx = hw.deviceContext;
+ *   console.log(`Using hardware: ${hw.deviceTypeName}`);
+ *   const decoder = await Decoder.create(stream, { hardware: hw });
  * }
+ * ```
  *
- * // Use specific hardware
- * const cuda = await HardwareContext.create(AV_HWDEVICE_TYPE_CUDA);
- * encoder.hwDeviceCtx = cuda.deviceContext;
- *
- * // Clean up when done
- * hw?.dispose();
+ * @example
+ * ```typescript
+ * // Use specific hardware type
+ * const cuda = HardwareContext.create(AV_HWDEVICE_TYPE_CUDA);
+ * const encoder = await Encoder.create('h264_nvenc', streamInfo, {
+ *   hardware: cuda
+ * });
  * cuda.dispose();
  * ```
+ *
+ * @see {@link Decoder} For hardware-accelerated decoding
+ * @see {@link Encoder} For hardware-accelerated encoding
+ * @see {@link HardwareFilterPresets} For hardware filter operations
  */
 export class HardwareContext {
+    /**
+     * Hardware-specific filter presets for this device.
+     * Provides convenient filter builders for hardware-accelerated operations.
+     */
+    filterPresets;
     _deviceContext;
-    _framesContext;
     _deviceType;
-    _deviceName;
+    _deviceTypeName;
     _devicePixelFormat;
     _isDisposed = false;
-    waitingComponents = new Set();
     /**
-     * Create a new HardwareContext instance.
-     *
-     * Private constructor - use HardwareContext.create() or HardwareContext.auto() to create instances.
-     *
-     * Stores the device context and type for later use.
-     *
      * @param deviceContext - Initialized hardware device context
-     * @param deviceType - Hardware device type
-     * @param deviceName - Optional device name/identifier
+     * @param deviceType - Hardware device type enum
+     * @param deviceTypeName - Human-readable device type name
+     * @internal
      */
-    constructor(deviceContext, deviceType, deviceName) {
+    constructor(deviceContext, deviceType, deviceTypeName) {
         this._deviceContext = deviceContext;
         this._deviceType = deviceType;
-        this._deviceName = deviceName;
-        this._devicePixelFormat = this.getHardwarePixelFormat();
+        this._deviceTypeName = deviceTypeName;
+        this._devicePixelFormat = this.getHardwareDecoderPixelFormat();
+        this.filterPresets = new HardwareFilterPresets(deviceType, deviceTypeName);
     }
     /**
      * Auto-detect and create the best available hardware context.
      *
      * Tries hardware types in order of preference based on platform.
      * Returns null if no hardware acceleration is available.
-     *
-     * Platform-specific preferences:
-     * - macOS: VideoToolbox
-     * - Windows: D3D12VA, D3D11VA, DXVA2, QSV, CUDA
-     * - Linux: VAAPI, VDPAU, CUDA, Vulkan, DRM
+     * Platform-specific preference order ensures optimal performance.
      *
      * @param options - Optional hardware configuration
-     *
-     * @returns Promise resolving to HardwareContext or null
+     * @returns Hardware context or null if unavailable
      *
      * @example
      * ```typescript
-     * const hw = await HardwareContext.auto();
+     * const hw = HardwareContext.auto();
      * if (hw) {
      *   console.log(`Auto-detected: ${hw.deviceTypeName}`);
+     *   // Use for decoder/encoder
      * }
      * ```
+     *
+     * @example
+     * ```typescript
+     * // With specific device
+     * const hw = HardwareContext.auto({
+     *   deviceName: '/dev/dri/renderD128'
+     * });
+     * ```
+     *
+     * @see {@link create} For specific hardware type
+     * @see {@link listAvailable} To check available types
      */
-    static async auto(options = {}) {
+    static auto(options = {}) {
         // Platform-specific preference order
         const preferenceOrder = this.getPreferenceOrder();
         for (const deviceType of preferenceOrder) {
             try {
-                const hw = await this.createFromType(deviceType, options.deviceName, options.options);
+                const hw = this.createFromType(deviceType, options.device, options.options);
                 if (hw) {
                     return hw;
                 }
+                else {
+                    // Try next device type
+                    continue;
+                }
             }
             catch {
                 // Try next device type
@@ -107,41 +114,57 @@ export class HardwareContext {
     /**
      * Create a hardware context for a specific device type.
      *
-     * Creates and initializes a hardware device context using FFmpeg's
-     * av_hwdevice_ctx_create() internally.
+     * Creates and initializes a hardware device context.
+     * Throws if the device type is not supported or initialization fails.
+     *
+     * Direct mapping to av_hwdevice_ctx_create().
      *
-     * @param device - Device type name (e.g., AV_HWDEVICE_TYPE_CUDA, AV_HWDEVICE_TYPE_VAAPI, AV_HWDEVICE_TYPE_VIDEOTOOLBOX)
-     * @param deviceName - Optional device name/index
+     * @param deviceType - Hardware device type from AVHWDeviceType
+     * @param device - Optional device specifier (e.g., GPU index, device path)
      * @param options - Optional device initialization options
+     * @returns Initialized hardware context
      *
-     * @returns Promise resolving to HardwareContext
+     * @throws {Error} If device type unsupported or initialization fails
      *
-     * @throws {Error} If device type is not supported or initialization fails
+     * @example
+     * ```typescript
+     * import { AV_HWDEVICE_TYPE_CUDA } from 'node-av/constants';
+     *
+     * // CUDA with specific GPU
+     * const cuda = HardwareContext.create(AV_HWDEVICE_TYPE_CUDA, '0');
+     * ```
      *
      * @example
      * ```typescript
-     * // Create CUDA context
-     * const cuda = await HardwareContext.create(AV_HWDEVICE_TYPE_CUDA, '0');
+     * import { AV_HWDEVICE_TYPE_VAAPI } from 'node-av/constants';
      *
-     * // Create VAAPI context
-     * const vaapi = await HardwareContext.create(AV_HWDEVICE_TYPE_VAAPI, '/dev/dri/renderD128');
+     * // VAAPI with render device
+     * const vaapi = HardwareContext.create(
+     *   AV_HWDEVICE_TYPE_VAAPI,
+     *   '/dev/dri/renderD128'
+     * );
      * ```
+     *
+     * @see {@link auto} For automatic detection
+     * @see {@link HardwareDeviceContext} For low-level API
      */
-    static async create(device, deviceName, options) {
-        if (device === AV_HWDEVICE_TYPE_NONE) {
-            throw new Error(`Unknown hardware device type: ${device}`);
+    static create(deviceType, device, options) {
+        if (deviceType === AV_HWDEVICE_TYPE_NONE) {
+            throw new Error('Cannot create hardware context for unknown hardware device type');
         }
-        const hw = await this.createFromType(device, deviceName, options);
+        const hw = this.createFromType(deviceType, device, options);
         if (!hw) {
-            throw new Error(`Failed to create hardware context for ${device}`);
+            throw new Error(`Failed to create hardware context for ${HardwareDeviceContext.getTypeName(deviceType) ?? 'unknown'} hardware`);
         }
         return hw;
     }
     /**
      * List all available hardware device types.
      *
-     * Uses av_hwdevice_iterate_types() internally to enumerate
-     * all hardware types supported by the FFmpeg build.
+     * Enumerates all hardware types supported by the FFmpeg build.
+     * Useful for checking hardware capabilities at runtime.
+     *
+     * Direct mapping to av_hwdevice_iterate_types().
      *
      * @returns Array of available device type names
      *
@@ -149,7 +172,10 @@ export class HardwareContext {
      * ```typescript
      * const available = HardwareContext.listAvailable();
      * console.log('Available hardware:', available.join(', '));
+     * // Output: "cuda, vaapi, videotoolbox"
      * ```
+     *
+     * @see {@link auto} For automatic selection
      */
     static listAvailable() {
         const types = HardwareDeviceContext.iterateTypes();
@@ -165,47 +191,26 @@ export class HardwareContext {
     /**
      * Get the hardware device context.
      *
-     * This can be assigned to CodecContext.hwDeviceCtx for hardware acceleration.
+     * Used internally by encoders and decoders for hardware acceleration.
+     * Can be assigned to CodecContext.hwDeviceCtx.
      *
-     * @returns Hardware device context
+     * @example
+     * ```typescript
+     * codecContext.hwDeviceCtx = hw.deviceContext;
+     * ```
      */
     get deviceContext() {
         return this._deviceContext;
     }
-    /**
-     * Get the hardware frames context.
-     *
-     * Created on-demand when needed for frame allocation.
-     *
-     * @returns Hardware frames context or undefined
-     */
-    get framesContext() {
-        return this._framesContext;
-    }
-    /**
-     * Set the hardware frames context.
-     *
-     * First component to set it "wins" - subsequent sets are ignored.
-     * This is typically called by the decoder after decoding the first frame,
-     * allowing other components (encoder, filters) to share the same frames context.
-     *
-     * @param framesContext - The hardware frames context to set
-     */
-    set framesContext(framesContext) {
-        // Only set if we don't have one yet (first wins)
-        if (framesContext && !this._framesContext) {
-            this._framesContext = framesContext;
-            // Notify all waiting components
-            for (const waiter of this.waitingComponents) {
-                waiter.resolve(this._framesContext);
-            }
-            this.waitingComponents.clear();
-        }
-    }
     /**
      * Get the device type enum value.
      *
-     * @returns AVHWDeviceType enum value
+     * @example
+     * ```typescript
+     * if (hw.deviceType === AV_HWDEVICE_TYPE_CUDA) {
+     *   console.log('Using NVIDIA GPU');
+     * }
+     * ```
      */
     get deviceType() {
         return this._deviceType;
@@ -213,25 +218,26 @@ export class HardwareContext {
     /**
      * Get the hardware device type name.
      *
-     * Uses FFmpeg's native av_hwdevice_get_type_name() function.
+     * Human-readable device type string.
      *
-     * @returns Device type name as string (e.g., 'cuda', 'videotoolbox')
+     * @example
+     * ```typescript
+     * console.log(`Hardware type: ${hw.deviceTypeName}`);
+     * // Output: "cuda" or "videotoolbox" etc.
+     * ```
      */
     get deviceTypeName() {
-        return HardwareDeviceContext.getTypeName(this._deviceType) ?? 'unknown';
-    }
-    /**
-     * Get the device name/identifier.
-     *
-     * @returns Device name or undefined
-     */
-    get deviceName() {
-        return this._deviceName;
+        return this._deviceTypeName;
     }
     /**
      * Get the device pixel format.
      *
-     * @returns Device pixel format
+     * Hardware-specific pixel format for frame allocation.
+     *
+     * @example
+     * ```typescript
+     * frame.format = hw.devicePixelFormat;
+     * ```
      */
     get devicePixelFormat() {
         return this._devicePixelFormat;
@@ -239,191 +245,201 @@ export class HardwareContext {
     /**
      * Check if this hardware context has been disposed.
      *
-     * @returns True if disposed
+     * @example
+     * ```typescript
+     * if (!hw.isDisposed) {
+     *   hw.dispose();
+     * }
+     * ```
      */
     get isDisposed() {
         return this._isDisposed;
     }
     /**
-     * Create or ensure a frames context exists for this hardware device.
-     *
-     * If a frames context already exists with different dimensions, throws an error.
-     * This is used for raw/generated frames that need hardware processing.
+     * Check if this hardware type supports a specific codec.
      *
-     * @param width - Frame width
-     * @param height - Frame height
-     * @param swFormat - Software pixel format (default: AV_PIX_FMT_NV12)
-     * @param initialPoolSize - Initial frame pool size (default: 20)
+     * Queries FFmpeg's codec configurations to verify hardware support.
+     * Checks both decoder and encoder support based on parameters.
      *
-     * @returns HardwareFramesContext - Either existing or newly created
+     * Direct mapping to avcodec_get_hw_config().
      *
-     * @throws {Error} If frames context exists with incompatible dimensions
+     * @param codecId - Codec ID from AVCodecID enum
+     * @param isEncoder - Check for encoder support (default: decoder)
+     * @returns true if codec is supported
      *
      * @example
      * ```typescript
-     * // For raw frames
-     * hw.ensureFramesContext(1920, 1080, AV_PIX_FMT_YUV420P);
+     * import { AV_CODEC_ID_H264 } from 'node-av/constants';
+     *
+     * if (hw.supportsCodec(AV_CODEC_ID_H264, true)) {
+     *   // Can use hardware H.264 encoder
+     * }
      * ```
+     *
+     * @see {@link findSupportedCodecs} For all supported codecs
      */
-    ensureFramesContext(width, height, swFormat = AV_PIX_FMT_NV12, initialPoolSize = 20) {
-        if (this._framesContext) {
-            // Validate compatibility
-            if (this._framesContext.width !== width || this._framesContext.height !== height) {
-                // prettier-ignore
-                throw new Error(`Incompatible frames context: existing ${this._framesContext.width}x${this._framesContext.height} ` +
-                    `vs requested ${width}x${height}. Use separate HardwareContext instances for different sizes.`);
-            }
-            return this._framesContext;
+    supportsCodec(codecId, isEncoder = false) {
+        // Try to find the codec
+        const codec = isEncoder ? Codec.findEncoder(codecId) : Codec.findDecoder(codecId);
+        if (!codec) {
+            return false;
+        }
+        if (isEncoder) {
+            return codec.isHardwareAcceleratedEncoder(this._deviceType);
         }
-        // Create new frames context on our device
-        const frames = new HardwareFramesContext();
-        frames.alloc(this._deviceContext);
-        frames.format = this.getHardwarePixelFormat();
-        frames.swFormat = swFormat;
-        frames.width = width;
-        frames.height = height;
-        frames.initialPoolSize = initialPoolSize;
-        const ret = frames.init();
-        FFmpegError.throwIfError(ret, 'Failed to initialize hardware frames context');
-        this._framesContext = frames;
-        // Notify waiting components
-        for (const waiter of this.waitingComponents) {
-            waiter.resolve(this._framesContext);
+        else {
+            return codec.isHardwareAcceleratedDecoder(this._deviceType);
         }
-        this.waitingComponents.clear();
-        return frames;
     }
     /**
-     * Wait for frames context to become available.
-     *
-     * Used by components that need hw_frames_ctx but don't have it yet.
-     * Resolves when another component (typically decoder) sets the frames context.
+     * Check if this hardware supports a specific pixel format for a codec.
      *
-     * @param timeout - Maximum time to wait in milliseconds (default: 5000)
+     * Verifies pixel format compatibility with hardware codec.
+     * Important for ensuring format compatibility in pipelines.
      *
-     * @returns Promise that resolves with the frames context
-     *
-     * @throws {Error} If timeout expires or HardwareContext is disposed
+     * @param codecId - Codec ID from AVCodecID enum
+     * @param pixelFormat - Pixel format to check
+     * @param isEncoder - Check for encoder (default: decoder)
+     * @returns true if pixel format is supported
      *
      * @example
      * ```typescript
-     * // Wait up to 3 seconds for frames context
-     * const framesCtx = await hw.waitForFramesContext(3000);
+     * import { AV_CODEC_ID_H264, AV_PIX_FMT_NV12 } from 'node-av/constants';
+     *
+     * if (hw.supportsPixelFormat(AV_CODEC_ID_H264, AV_PIX_FMT_NV12)) {
+     *   // Can use NV12 format with H.264
+     * }
      * ```
+     *
+     * @see {@link supportsCodec} For basic codec support
      */
-    async waitForFramesContext(timeout = 5000) {
-        if (this._framesContext) {
-            return Promise.resolve(this._framesContext);
+    supportsPixelFormat(codecId, pixelFormat, isEncoder = false) {
+        const codec = isEncoder ? Codec.findEncoder(codecId) : Codec.findDecoder(codecId);
+        if (!codec) {
+            return false;
+        }
+        const pixelFormats = codec.pixelFormats ?? [];
+        if (pixelFormats.length === 0) {
+            return false;
         }
-        return Promise.race([
-            new Promise((resolve, reject) => {
-                this.waitingComponents.add({ resolve, reject });
-            }),
-            new Promise((_, reject) => setTimeout(() => reject(new Error('Timeout waiting for frames context')), timeout)),
-        ]);
+        return pixelFormats.some((fmt) => fmt === pixelFormat);
     }
     /**
-     * Get the hardware pixel format for this device type.
+     * Get the appropriate encoder codec for a given base codec name.
      *
-     * Maps device types to their corresponding pixel formats.
+     * Maps generic codec names to hardware-specific encoder implementations.
+     * Returns null if no hardware encoder is available for the codec.
+     * Automatically tests encoder viability before returning.
+     *
+     * @param codecName - Generic codec name (e.g., 'h264', 'hevc', 'av1')
+     * @returns Hardware encoder codec or null if unsupported
      *
-     * Returns the appropriate AV_PIX_FMT_* constant for the hardware type.
+     * @example
+     * ```typescript
+     * const encoderCodec = await hw.getEncoderCodec('h264');
+     * if (encoderCodec) {
+     *   console.log(`Using encoder: ${encoderCodec.name}`);
+     *   // e.g., "h264_nvenc" for CUDA
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Use with Encoder.create
+     * const codec = await hw.getEncoderCodec('hevc');
+     * if (codec) {
+     *   const encoder = await Encoder.create(codec, streamInfo, {
+     *     hardware: hw
+     *   });
+     * }
+     * ```
      *
-     * @returns Hardware pixel format
+     * @see {@link Encoder.create} For using the codec
      */
-    getHardwarePixelFormat() {
+    async getEncoderCodec(codecName) {
+        // Build the encoder name
+        let encoderSuffix = '';
+        // We might only have hardware decode capabilities (d3d11va, d3d12va etc)
+        // So we need to check for other hardware encoders
+        const getAlternativeEncoder = () => {
+            const nvencCodecName = `${codecName}_nvenc`;
+            const qsvCodecName = `${codecName}_qsv`;
+            const amfCodecName = `${codecName}_amf`;
+            const codecNames = [nvencCodecName, qsvCodecName, amfCodecName];
+            let suffix = '';
+            for (const name of codecNames) {
+                const encoderCodec = Codec.findEncoderByName(name);
+                if (!encoderCodec) {
+                    continue;
+                }
+                suffix = name.split('_')[1]; // Get suffix after underscore
+            }
+            if (!suffix) {
+                return null;
+            }
+            return suffix;
+        };
         switch (this._deviceType) {
-            case AV_HWDEVICE_TYPE_VIDEOTOOLBOX:
-                return AV_PIX_FMT_VIDEOTOOLBOX;
-            case AV_HWDEVICE_TYPE_VAAPI:
-                return AV_PIX_FMT_VAAPI;
             case AV_HWDEVICE_TYPE_CUDA:
-                return AV_PIX_FMT_CUDA;
-            case AV_HWDEVICE_TYPE_QSV:
-                return AV_PIX_FMT_QSV;
+                // CUDA uses NVENC for encoding
+                encoderSuffix = 'nvenc';
+                break;
             case AV_HWDEVICE_TYPE_D3D11VA:
-                return AV_PIX_FMT_D3D11;
             case AV_HWDEVICE_TYPE_DXVA2:
-                return AV_PIX_FMT_DXVA2_VLD;
-            case AV_HWDEVICE_TYPE_DRM:
-                return AV_PIX_FMT_DRM_PRIME;
-            case AV_HWDEVICE_TYPE_OPENCL:
-                return AV_PIX_FMT_OPENCL;
-            case AV_HWDEVICE_TYPE_MEDIACODEC:
-                return AV_PIX_FMT_MEDIACODEC;
-            case AV_HWDEVICE_TYPE_VULKAN:
-                return AV_PIX_FMT_VULKAN;
+                encoderSuffix = getAlternativeEncoder() ?? '';
+                break;
             case AV_HWDEVICE_TYPE_D3D12VA:
-                return AV_PIX_FMT_D3D12;
+                // D3D12VA currently only supports HEVC encoding
+                if (codecName === 'hevc') {
+                    encoderSuffix = 'd3d12va';
+                }
+                else {
+                    encoderSuffix = getAlternativeEncoder() ?? '';
+                }
+                break;
+            case AV_HWDEVICE_TYPE_OPENCL:
+            case AV_HWDEVICE_TYPE_VDPAU:
+            case AV_HWDEVICE_TYPE_DRM:
+                encoderSuffix = getAlternativeEncoder() ?? '';
+                break;
             default:
-                return AV_PIX_FMT_NV12; // Common hardware format
-        }
-    }
-    /**
-     * Check if this hardware type supports a specific codec.
-     *
-     * Checks both decoder and encoder support by querying FFmpeg's codec configurations.
-     *
-     * Uses avcodec_get_hw_config() internally to check hardware support.
-     *
-     * @param codecId - Codec ID from AVCodecID enum
-     * @param isEncoder - Check for encoder support (default: false for decoder)
-     *
-     * @returns True if codec is supported by this hardware
-     */
-    supportsCodec(codecId, isEncoder = false) {
-        // Try to find the codec
-        const codec = isEncoder ? Codec.findEncoder(codecId) : Codec.findDecoder(codecId);
-        if (!codec) {
-            return false;
-        }
-        // Check hardware configurations
-        for (let i = 0;; i++) {
-            const config = codec.getHwConfig(i);
-            if (!config) {
-                break; // No more configurations
-            }
-            // Check if this hardware device type is supported
-            // Accept both HW_DEVICE_CTX and HW_FRAMES_CTX methods
-            const supportsDeviceCtx = (config.methods & AV_CODEC_HW_CONFIG_METHOD_HW_DEVICE_CTX) !== 0;
-            const supportsFramesCtx = (config.methods & AV_CODEC_HW_CONFIG_METHOD_HW_FRAMES_CTX) !== 0;
-            if ((supportsDeviceCtx || supportsFramesCtx) && config.deviceType === this._deviceType) {
-                return true;
-            }
+                // Use the device type name as suffix
+                encoderSuffix = this._deviceTypeName;
         }
-        return false;
-    }
-    /**
-     * Check if this hardware device type supports a specific pixel format.
-     *
-     * @param codecId - Codec ID from AVCodecID enum
-     * @param pixelFormat - Pixel format to check
-     * @param isEncoder - Check for encoder support (default: false for decoder)
-     *
-     * @returns True if pixel format is supported by this hardware
-     */
-    supportsPixelFormat(codecId, pixelFormat, isEncoder = false) {
-        const codec = isEncoder ? Codec.findEncoder(codecId) : Codec.findDecoder(codecId);
-        if (!codec) {
-            return false;
+        if (!encoderSuffix) {
+            return null;
         }
-        const pixelFormats = codec.pixelFormats ?? [];
-        if (pixelFormats.length === 0) {
-            return false;
+        // Construct the encoder name
+        const encoderName = `${codecName}_${encoderSuffix}`;
+        const encoderCodec = Codec.findEncoderByName(encoderName);
+        if (!encoderCodec || !(await this.testHardwareEncoder(encoderName))) {
+            return null;
         }
-        return pixelFormats.some((fmt) => fmt === pixelFormat);
+        return encoderCodec;
     }
     /**
      * Find all codecs that support this hardware device.
      *
-     * Uses FFmpeg's native codec list to find compatible codecs.
+     * Iterates through all available codecs and checks hardware compatibility.
+     * Useful for discovering available hardware acceleration options.
      *
-     * Iterates through all codecs using av_codec_iterate() and checks
-     * their hardware configurations.
+     * Direct mapping to av_codec_iterate() with hardware config checks.
      *
      * @param isEncoder - Find encoders (true) or decoders (false)
-     *
      * @returns Array of codec names that support this hardware
+     *
+     * @example
+     * ```typescript
+     * const decoders = hw.findSupportedCodecs(false);
+     * console.log('Hardware decoders:', decoders);
+     * // ["h264_cuvid", "hevc_cuvid", ...]
+     *
+     * const encoders = hw.findSupportedCodecs(true);
+     * console.log('Hardware encoders:', encoders);
+     * // ["h264_nvenc", "hevc_nvenc", ...]
+     * ```
+     *
+     * @see {@link supportsCodec} For checking specific codec
      */
     findSupportedCodecs(isEncoder = false) {
         const supportedCodecs = [];
@@ -455,101 +471,203 @@ export class HardwareContext {
     /**
      * Clean up and free hardware resources.
      *
-     * Safe to call multiple times - subsequent calls are no-ops.
-     * Called automatically by Decoder/Encoder on close.
+     * Releases the hardware device context.
+     * Safe to call multiple times.
+     * Automatically called by Symbol.dispose.
+     *
+     * @example
+     * ```typescript
+     * const hw = HardwareContext.auto();
+     * try {
+     *   // Use hardware
+     * } finally {
+     *   hw?.dispose();
+     * }
+     * ```
      *
-     * Frees both frames context (if created) and device context.
-     * Notifies any waiting components that disposal occurred.
+     * @see {@link Symbol.dispose} For automatic cleanup
      */
     dispose() {
         if (this._isDisposed) {
-            return; // Already disposed, safe to return
-        }
-        // Notify waiting components that we're disposing
-        for (const waiter of this.waitingComponents) {
-            waiter.reject(new Error('HardwareContext disposed'));
-        }
-        this.waitingComponents.clear();
-        if (this._framesContext) {
-            this._framesContext.free();
-            this._framesContext = undefined;
+            return;
         }
         this._deviceContext.free();
         this._isDisposed = true;
     }
+    /**
+     * Get the hardware decoder pixel format for this device type.
+     *
+     * Maps device types to their corresponding pixel formats.
+     * Used internally for frame format configuration.
+     *
+     * @returns Hardware-specific pixel format
+     */
+    getHardwareDecoderPixelFormat() {
+        switch (this._deviceType) {
+            case AV_HWDEVICE_TYPE_VIDEOTOOLBOX:
+                return AV_PIX_FMT_VIDEOTOOLBOX;
+            case AV_HWDEVICE_TYPE_VAAPI:
+                return AV_PIX_FMT_VAAPI;
+            case AV_HWDEVICE_TYPE_CUDA:
+                return AV_PIX_FMT_CUDA;
+            case AV_HWDEVICE_TYPE_QSV:
+                return AV_PIX_FMT_QSV;
+            case AV_HWDEVICE_TYPE_D3D11VA:
+                return AV_PIX_FMT_D3D11;
+            case AV_HWDEVICE_TYPE_DXVA2:
+                return AV_PIX_FMT_DXVA2_VLD;
+            case AV_HWDEVICE_TYPE_DRM:
+                return AV_PIX_FMT_DRM_PRIME;
+            case AV_HWDEVICE_TYPE_OPENCL:
+                return AV_PIX_FMT_OPENCL;
+            case AV_HWDEVICE_TYPE_MEDIACODEC:
+                return AV_PIX_FMT_MEDIACODEC;
+            case AV_HWDEVICE_TYPE_VULKAN:
+                return AV_PIX_FMT_VULKAN;
+            case AV_HWDEVICE_TYPE_D3D12VA:
+                return AV_PIX_FMT_D3D12;
+            case AV_HWDEVICE_TYPE_RKMPP:
+                return AV_PIX_FMT_DRM_PRIME; // RKMPP uses DRM Prime buffers
+            default:
+                return AV_PIX_FMT_NV12; // Common hardware format
+        }
+    }
+    /**
+     * Test if a hardware encoder can be created.
+     *
+     * Attempts to initialize the encoder to verify support.
+     * Used internally by getEncoderCodec.
+     *
+     * @param encoderCodec - Encoder to test
+     * @returns true if encoder can be initialized
+     */
+    async testHardwareEncoder(encoderCodec) {
+        let codec = null;
+        if (encoderCodec instanceof Codec) {
+            codec = encoderCodec;
+        }
+        else if (typeof encoderCodec === 'string') {
+            codec = Codec.findEncoderByName(encoderCodec);
+        }
+        else {
+            codec = Codec.findEncoder(encoderCodec);
+        }
+        if (!codec?.pixelFormats || !codec.isHardwareAcceleratedEncoder()) {
+            return false;
+        }
+        const codecContext = new CodecContext();
+        codecContext.allocContext3(codec);
+        codecContext.hwDeviceCtx = this._deviceContext;
+        codecContext.timeBase = new Rational(1, 30);
+        codecContext.pixelFormat = codec.pixelFormats[0];
+        codecContext.width = 100;
+        codecContext.height = 100;
+        const ret = await codecContext.open2(codec);
+        codecContext.freeContext();
+        return ret >= 0;
+    }
     /**
      * Create hardware context from device type.
      *
      * Internal factory method using av_hwdevice_ctx_create().
      *
      * @param deviceType - AVHWDeviceType enum value
-     * @param deviceName - Optional device name/index
+     * @param device - Optional device specifier
      * @param options - Optional device options
-     *
-     * @returns HardwareContext or null if creation fails
+     * @returns Hardware context or null if creation fails
      */
-    static async createFromType(deviceType, deviceName, options) {
-        const device = new HardwareDeviceContext();
+    static createFromType(deviceType, device, options) {
+        const deviceCtx = new HardwareDeviceContext();
         // Convert options to Dictionary if provided
         let optionsDict = null;
         if (options && Object.keys(options).length > 0) {
             optionsDict = Dictionary.fromObject(options);
         }
-        const ret = device.create(deviceType, deviceName ?? null, optionsDict);
+        const ret = deviceCtx.create(deviceType, device, optionsDict);
         // Clean up dictionary if used
         if (optionsDict) {
             optionsDict.free();
         }
-        if (ret < 0) {
-            device.free();
+        const deviceTypeName = HardwareDeviceContext.getTypeName(deviceType);
+        if (ret < 0 || !deviceTypeName) {
+            deviceCtx.free();
             return null;
         }
-        return new HardwareContext(device, deviceType, deviceName);
+        return new HardwareContext(deviceCtx, deviceType, deviceTypeName);
     }
     /**
      * Get platform-specific preference order for hardware types.
      *
-     * Returns the optimal hardware types for the current platform.
+     * Returns available hardware types sorted by platform preference.
+     * Ensures optimal hardware selection for each platform.
      *
      * @returns Array of AVHWDeviceType values in preference order
      */
     static getPreferenceOrder() {
+        // Get all available hardware types on this system
+        const available = HardwareDeviceContext.iterateTypes();
+        if (available.length === 0) {
+            return [];
+        }
         const platform = process.platform;
+        let preferenceOrder;
         if (platform === 'darwin') {
             // macOS: VideoToolbox is preferred
-            return [AV_HWDEVICE_TYPE_VIDEOTOOLBOX, AV_HWDEVICE_TYPE_VULKAN, AV_HWDEVICE_TYPE_OPENCL];
+            preferenceOrder = [AV_HWDEVICE_TYPE_VIDEOTOOLBOX];
         }
         else if (platform === 'win32') {
-            // Windows: D3D12VA (newest), D3D11VA, DXVA2, QSV, CUDA
-            return [
-                AV_HWDEVICE_TYPE_D3D12VA,
-                AV_HWDEVICE_TYPE_D3D11VA,
+            // Windows: Match FFmpeg's hw_configs order
+            // DXVA2 → D3D11VA → D3D12VA → NVDEC (CUDA)
+            preferenceOrder = [
                 AV_HWDEVICE_TYPE_DXVA2,
-                AV_HWDEVICE_TYPE_QSV,
+                AV_HWDEVICE_TYPE_D3D11VA,
+                AV_HWDEVICE_TYPE_D3D12VA,
                 AV_HWDEVICE_TYPE_CUDA,
+                AV_HWDEVICE_TYPE_QSV,
                 AV_HWDEVICE_TYPE_VULKAN,
                 AV_HWDEVICE_TYPE_OPENCL,
             ];
         }
         else {
-            // Linux: VAAPI, VDPAU, CUDA, Vulkan, DRM
-            return [AV_HWDEVICE_TYPE_VAAPI, AV_HWDEVICE_TYPE_VDPAU, AV_HWDEVICE_TYPE_CUDA, AV_HWDEVICE_TYPE_VULKAN, AV_HWDEVICE_TYPE_DRM, AV_HWDEVICE_TYPE_OPENCL];
+            // Linux: Match FFmpeg's hw_configs order
+            // NVDEC (CUDA) → VAAPI → VDPAU → Vulkan
+            // RKMPP is platform-specific for ARM/Rockchip
+            const isARM = process.arch === 'arm64' || process.arch === 'arm';
+            if (isARM) {
+                // ARM platforms: Prioritize RKMPP for Rockchip SoCs
+                preferenceOrder = [AV_HWDEVICE_TYPE_RKMPP, AV_HWDEVICE_TYPE_VAAPI, AV_HWDEVICE_TYPE_VULKAN, AV_HWDEVICE_TYPE_DRM, AV_HWDEVICE_TYPE_OPENCL];
+            }
+            else {
+                // x86_64 Linux: CUDA → VAAPI → VDPAU → Vulkan
+                preferenceOrder = [AV_HWDEVICE_TYPE_CUDA, AV_HWDEVICE_TYPE_VAAPI, AV_HWDEVICE_TYPE_VDPAU, AV_HWDEVICE_TYPE_VULKAN, AV_HWDEVICE_TYPE_DRM, AV_HWDEVICE_TYPE_OPENCL];
+            }
         }
+        // Filter preference order to only include available types
+        const availableSet = new Set(available);
+        const sortedAvailable = preferenceOrder.filter((type) => availableSet.has(type));
+        // Add any available types not in our preference list at the end
+        for (const type of available) {
+            if (!preferenceOrder.includes(type)) {
+                sortedAvailable.push(type);
+            }
+        }
+        return sortedAvailable;
     }
     /**
-     * Automatic cleanup when using 'using' statement.
-     *
-     * Implements the Disposable interface for automatic cleanup.
+     * Dispose of hardware context.
      *
-     * Calls dispose() to free hardware resources.
+     * Implements Disposable interface for automatic cleanup.
+     * Equivalent to calling dispose().
      *
      * @example
      * ```typescript
      * {
-     *   using hw = await HardwareContext.auto();
+     *   using hw = HardwareContext.auto();
      *   // Use hardware context...
      * } // Automatically disposed
      * ```
+     *
+     * @see {@link dispose} For manual cleanup
      */
     [Symbol.dispose]() {
         this.dispose();