[build] Enable NVIDIA Video Codec SDK support for hardware video decode/encode

Add NVCUVID and NVCUVENC support using the Video Codec SDK from the deps
repository. This enables hardware-accelerated video decoding and encoding
via NVIDIA GPUs.

Author: Breakthrough

.github/workflows/build_wheels_windows.yml

@@ -43,12 +43,16 @@ jobs:
         cuda-version: ['12']
         include:
           # CUDA 12: Supports Maxwell (5.0) through Blackwell (10.0)
+          # TODO(@Breakthrough): Expand PTX legacy support back to 5.0, it doesn't make the final
+          # distribution that much larger and may help users with older GPUs.
           - cuda-version: '12'
             runs-on: 'windows-2025'
             cuda-installer: 'cuda_12.9.1_windows_network.exe'
             cuda-path-version: 'v12.9'
             cudnn-archive: 'cudnn-windows-x86_64-9.18.1.3_cuda12-archive.zip'
             cudnn-folder: 'cudnn-windows-x86_64-9.18.1.3_cuda12-archive'
+            video-codec-sdk-archive: 'Video_Codec_SDK_13.0.37.zip'
+            video-codec-sdk-folder: 'Video_Codec_SDK_13.0.37'
             cuda-arch-bin: '5.0;5.2;6.0;6.1;7.0;7.5;8.0;8.6;8.9;9.0;10.0'
             cuda-arch-ptx: '10.0'
             cache-key: 'nvidia-deps-cuda-12.9.1-cudnn-9.18.1.3'
@@ -60,6 +64,8 @@ jobs:
           #   cuda-path-version: 'v13.1'
           #   cudnn-archive: 'cudnn-windows-x86_64-9.18.1.3_cuda13-archive.zip'
           #   cudnn-folder: 'cudnn-windows-x86_64-9.18.1.3_cuda13-archive'
+          #   video-codec-sdk-archive: 'Video_Codec_SDK_13.0.37.zip'
+          #   video-codec-sdk-folder: 'Video_Codec_SDK_13.0.37'
           #   cuda-arch-bin: '7.5;8.0;8.6;8.9;9.0;10.0;12.0'
           #   cuda-arch-ptx: '12.0'
           #   cache-key: 'nvidia-deps-cuda-13.1.1-cudnn-9.18.1.3'
@@ -133,7 +139,20 @@ jobs:
         $CUDNN_PATH = "D:/a/opencv-python-cuda/opencv-python-cuda/${{ matrix.cudnn-folder }}"
         echo "CUDNN_LIBRARY=$CUDNN_PATH/lib/x64/cudnn.lib" | Out-File -FilePath $env:GITHUB_ENV -Append
         echo "CUDNN_INCLUDE_DIR=$CUDNN_PATH/include" | Out-File -FilePath $env:GITHUB_ENV -Append
-        Copy-Item -Path "$CUDNN_PATH/bin/*" -Destination .  -Include "*.dll"
+        Copy-Item -Path "$CUDNN_PATH/bin/x64/*" -Destination .  -Include "*.dll"
+      shell: pwsh
+    - name: 🔧 Install NVIDIA Video Codec SDK
+      run: |
+        $sdk_path = ".deps/Nvidia/${{ matrix.video-codec-sdk-archive }}"
+        if (-not (Test-Path $sdk_path)) {
+          throw "Video Codec SDK archive not found at $sdk_path"
+        }
+        echo "Installing Video Codec SDK..."
+        7z x $sdk_path
+        $SDK_PATH = "D:/a/opencv-python-cuda/opencv-python-cuda/${{ matrix.video-codec-sdk-folder }}"
+        echo "CUDA_nvcuvid_LIBRARY=$SDK_PATH/Lib/win/x64/nvcuvid.lib" | Out-File -FilePath $env:GITHUB_ENV -Append
+        echo "CUDA_nvencodeapi_LIBRARY=$SDK_PATH/Lib/win/x64/nvencodeapi.lib" | Out-File -FilePath $env:GITHUB_ENV -Append
+        echo "NVCUVID_INCLUDE_DIR=$SDK_PATH/Interface" | Out-File -FilePath $env:GITHUB_ENV -Append
       shell: pwsh
 
     - name: Restore build artifacts

README.md

@@ -4,7 +4,7 @@ Download: [Latest Release (4.12.0-dev0)](https://github.com/Breakthrough/opencv-
 
 ## What is `opencv-python-cuda`?
 
-Pre-built NVIDIA® CUDA™ enabled OpenCV packages for Python that come with all batteries included. This is a fork of [the official opencv-python project](https://github.com/opencv/opencv-python). Right now packages are only produced for Windows x64, and devices must be Maxwell class (GeForce 900 series) or newer.  Once installed via `pip` (or another Python package manager like `uv`), the following should *just work*:
+Pre-built NVIDIA® CUDA™ enabled OpenCV packages for Python that come with all batteries included. This is a fork of [the official opencv-python project](https://github.com/opencv/opencv-python). Right now packages are only produced for Windows x64, and devices must be Turing class (GeForce 2000 series) or newer.  Once installed via `pip` (or another Python package manager like `uv`), the following should *just work*:
 
 ```
 import cv2

WORKFLOW.md

@@ -0,0 +1,123 @@
+# Workflow Guide
+
+## Repository Setup
+
+### Cloning the Repository
+
+```bash
+git clone https://github.com/Breakthrough/opencv-python-cuda.git
+cd opencv-python-cuda
+```
+
+### Adding Upstream Remote
+
+To sync with the main `opencv/opencv-python` repository, add it as a remote:
+
+```bash
+git remote add upstream https://github.com/opencv/opencv-python.git
+```
+
+### Preventing Tag Pollution
+
+The upstream `opencv/opencv-python` repo has numeric tags (0, 1, 2, ... 90) that will pollute your local repo during fetches. To prevent this, configure the remote to exclude tags:
+
+```bash
+git config remote.upstream.tagOpt --no-tags
+git config --add remote.upstream.fetch '^refs/tags/*'
+```
+
+The `tagOpt` setting alone is sometimes not respected, so the negative refspec (`^refs/tags/*`) explicitly excludes all tags.
+
+### Syncing with Upstream
+
+After configuring the remote, you can sync without getting unwanted tags:
+
+```bash
+git fetch upstream
+git pull --rebase upstream 4.x
+```
+
+### Removing Accidentally Fetched Tags
+
+If you already fetched the numeric tags, remove them with:
+
+```bash
+git tag -d 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 68 70 72 74 76 78 80 82 84 86 88 90
+```
+
+---
+
+## Triggering Builds
+
+To trigger the Windows CUDA build workflow:
+
+```bash
+gh workflow run build_wheels_windows.yml --ref 4.x-cuda -R Breakthrough/opencv-python-cuda
+```
+
+**Important:** Always specify `-R Breakthrough/opencv-python-cuda` when using `gh` commands. This repo is a fork of `opencv/opencv-python`, and `gh` will default to the parent repository without the explicit `-R` flag.
+
+### Build Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `restore_build_cache` | Restore build cache from previous runs | `true` |
+| `save_build_cache` | Save build cache after completion | `true` |
+| `rolling_build` | Use latest commit from upstream OpenCV | `false` |
+
+Example with options:
+
+```bash
+gh workflow run build_wheels_windows.yml --ref 4.x-cuda -R Breakthrough/opencv-python-cuda \
+  -f restore_build_cache=false \
+  -f save_build_cache=true
+```
+
+### Force Rebuild (No Cache)
+
+To force a complete rebuild without using cached artifacts:
+
+```bash
+gh workflow run build_wheels_windows.yml --ref 4.x-cuda -R Breakthrough/opencv-python-cuda \
+  -f restore_build_cache=false
+```
+
+---
+
+## Monitoring Builds
+
+List recent runs:
+
+```bash
+gh run list -R Breakthrough/opencv-python-cuda --limit 5
+```
+
+Watch a running build:
+
+```bash
+gh run watch <run-id> -R Breakthrough/opencv-python-cuda
+```
+
+View build details:
+
+```bash
+gh run view <run-id> -R Breakthrough/opencv-python-cuda
+```
+
+---
+
+## Reference: Git Config for Remotes
+
+After setup, your `.git/config` remote sections should look like:
+
+```ini
+[remote "origin"]
+    url = https://github.com/Breakthrough/opencv-python-cuda.git
+    fetch = +refs/heads/*:refs/remotes/origin/*
+
+[remote "upstream"]
+    url = https://github.com/opencv/opencv-python.git
+    fetch = +refs/heads/*:refs/remotes/upstream/*
+    fetch = ^refs/tags/*
+    tagOpt = --no-tags
+```

setup.py

@@ -162,6 +162,11 @@ def main():
     cudnn_library = os.environ["CUDNN_LIBRARY"]
     cudnn_include_dir = os.environ["CUDNN_INCLUDE_DIR"]
 
+    # Video Codec SDK paths for NVCUVID/NVCUVENC (optional, enables hardware video decode/encode)
+    nvcuvid_library = os.environ.get("CUDA_nvcuvid_LIBRARY", "")
+    nvencodeapi_library = os.environ.get("CUDA_nvencodeapi_LIBRARY", "")
+    nvcuvid_include_dir = os.environ.get("NVCUVID_INCLUDE_DIR", "")
+
     cmake_args = (
         (ci_cmake_generator if is_CI_build else [])
         + [
@@ -191,13 +196,23 @@ def main():
             "-DPYTHON3_LIMITED_API=ON",
             "-DBUILD_OPENEXR=ON",
             "-DWITH_CUDA=ON",
-            # TODO(@Breakthrough): Download and install the required dependencies to enable this in build_wheels_windows.yml.
-            "-DWITH_NVCUVID=OFF",
+            "-DWITH_NVCUVID=ON",
+            "-DWITH_NVCUVENC=ON",
             f"-DCUDA_ARCH_BIN={cuda_arch_bin}",
             f"-DCUDA_ARCH_PTX={cuda_arch_ptx}",
             f"-DCUDNN_LIBRARY={cudnn_library}",
             f"-DCUDNN_INCLUDE_DIR={cudnn_include_dir}",
         ]
+        + (
+            # Video Codec SDK paths for hardware video decode/encode support
+            [
+                f"-DCUDA_nvcuvid_LIBRARY={nvcuvid_library}",
+                f"-DCUDA_nvencodeapi_LIBRARY={nvencodeapi_library}",
+                f"-DCMAKE_INCLUDE_PATH={nvcuvid_include_dir}",
+            ]
+            if nvcuvid_library and nvcuvid_include_dir
+            else []
+        )
         + (
             # CUDA 12.9+ requires MSVC's conformant preprocessor for CCCL headers.
             # -Xcompiler passes the flag from nvcc to the host compiler (MSVC).