FFmpeg Hardware Codec Detect Script(HwCodecDetect)

中文版

Today's hardware-accelerated video codec landscape is a "field of a hundred schools of thought." To leverage the immense power of GPUs, hardware manufacturers have introduced their own acceleration frameworks and encoding standards, such as NVIDIA's NVEnc/NVDec, Intel's QSV, and AMD's AMF. Additionally, operating systems provide universal APIs like Microsoft's Media Foundation, DXVA2, and D3D12VA, while the open-source community has developed cross-platform standards like VAAPI and Vulkan.

While this diversity drives technological progress, it also presents a challenge for users and developers. Due to historical issues and compatibility quirks, a single piece of hardware might support multiple encoders, but they can differ significantly in performance, supported formats, and resolutions. As a result, when using FFmpeg for hardware acceleration, it's not always clear which encoder is best suited for a specific device.

This project was created to solve this very problem. It's a convenient tool for automatically detecting the hardware video encoder capabilities of your system. Using FFmpeg, it generates single-frame video files at various resolutions (from 240p to 8K) and attempts to process them with different hardware encoders. This allows it to quickly determine which hardware encoders are available on your system and what resolutions they support.

Key Features

Encoders

The script automatically detect and reports on the following major hardware encoders and their supported formats:

Decoders

The script automatically detect and reports on the following major hardware decoders and their supported formats:

Bit-depth and Chroma Subsampling Detection

In addition to resolution-based testing, the tool now includes comprehensive bit-depth and chroma subsampling detection. This feature tests hardware codec support for different pixel formats, helping you understand the full capabilities of your hardware encoders and decoders.

The detection covers the following pixel formats:

This feature uses a fixed resolution of 1280x720 for all tests and follows the encode-then-decode workflow. If hardware encoding fails, the tool automatically falls back to software encoding to ensure decoder tests can still be performed.

Note: This feature is enabled by default. You can disable it using the --no-bitdepth-chroma command-line parameter.

How to Use

HwCodecDetect provides both a command-line (CLI) and a graphical user interface (GUI). You can install and use it in 3 ways.

Tip: Add the --ui flag (or set the environment variable HWCODECDETECT_GUI=1) to launch the GUI mode instead of the default CLI.

Method 1: Install via PyPI (Recommended)

This is the easiest method if you just want to use the tool quickly.

1. Install: Use pip to install hwcodecdetect from the official PyPI repository.

   pip install hwcodecdetect -U
   

2. Run: After installation, run the hwcodecdetect command directly from your terminal.

   # CLI mode (default)
   hwcodecdetect
   
   # GUI mode
   hwcodecdetect --ui
   

Method 2: Download and Run Executable (Standalone)

Use this method if you prefer to run the tool without installing Python dependencies, or if the PyPI installation fails.

Both CLI and GUI executables are available on the Releases page:

1. Download: Go to the project's Releases page and download the executable file corresponding to your operating system and preferred mode (CLI or GUI).

2. (Linux/macOS only) Add Execute Permission: If you are on Linux or macOS, you need to grant the downloaded file execute permission.

   # Replace 'HwCodecDetect-Linux-x64' with the actual downloaded filename
   chmod +x HwCodecDetect-Linux-x64
   

3. Run: Execute the file directly from your terminal.

   # CLI - For Linux
   ./HwCodecDetect-Linux-x64
   # CLI - For MacOS
   ./HwCodecDetect-macOS-ARM64
   # CLI - For Windows (e.g., in PowerShell or Command Prompt)
   .\HwCodecDetect-Windows-x64.exe
   
   # GUI - For Linux
   ./HwCodecDetect-GUI-Linux-x64
   # CLI - For MacOS
   ./HwCodecDetect-GUI-macOS-ARM64
   # GUI - For Windows
   .\HwCodecDetect-GUI-Windows-x64.exe
   

Method 3: Install from Source

Use this method if you have cloned the project source code from GitHub and want to run it locally.

1. Clone the repository: First, clone the project source code to your local machine.

   git clone https://github.com/whyb/HwCodecDetect.git ./HwCodecDetect
   

2. Install dependencies: Navigate into the project's root directory and use pip to install the required dependencies.

   cd HwCodecDetect
   pip install .
   

3. Run: After the installation is complete, run the hwcodecdetect command directly.

   # CLI mode (default)
   hwcodecdetect
   
   # GUI mode
   hwcodecdetect --ui
   

Final effect

Here are some possible results from a local test run:

Command-line tool

GUI tool

Star History