PyNvVideoCodec 2.2.1__cp312-cp312-win_arm64.whl

samples/advanced/encode_perf.py

@@ -0,0 +1,338 @@
+# This copyright notice applies to this file only
+#
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: MIT
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the "Software"),
+# to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense,
+# and/or sell copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+# DEALINGS IN THE SOFTWARE.
+
+'''
+This sample demonstrates advanced parallel video encoding using multiple threads or processes.
+It shows how to:
+1. Maximize GPU utilization using multiple encoder instances
+2. Measure encoding performance (FPS) accurately for different modes
+3. Scale encoding across available NVENC engines
+4. Use either threading or multiprocessing for parallelization
+5. Manage shared resources and cleanup
+6. Track and report performance metrics
+
+The sample implements two parallel execution modes:
+- Thread Mode:
+  * Multiple encoders in the same process
+  * Shared memory access
+  * Lower overhead, simpler synchronization
+  * Best for CPU-bound workloads
+
+- Process Mode:
+  * Multiple encoders in separate processes
+  * IPC memory sharing
+  * Better isolation and stability
+  * Best for GPU-bound workloads
+
+
+Usage:
+    python encode_perf.py -m <mode> -i <input_file> -s <size> [options]
+
+Example:
+    python encode_perf.py -m threads -i input.yuv -s 1920x1080 -n 4
+
+Arguments:
+    -m: Execution mode ('threads' or 'processes')
+    -i: Raw input video file
+    -s: Frame size (e.g., 1920x1080)
+    -if: Input format (default: NV12)
+    -n: Number of workers (default: 1)
+    -f: Frames per worker (default: all)
+    -g: GPU ID (default: 0)
+    -c: Output codec (h264/hevc/av1); overrides codec in JSON config
+    -json: Encoder config file (controls codec, fps, gop, preset, rc, bitrate, etc.)
+
+Note: This performance testing app does not write output files.
+      It only measures encoding throughput.
+
+Note: For optimal performance:
+- Use thread mode for smaller workloads or when CPU is the bottleneck
+- Use process mode for larger workloads or when GPU is the bottleneck
+- Adjust worker count based on available CPU cores and GPU resources
+'''
+
+import gc
+import sys
+import atexit
+import os
+import time
+import queue
+import threading
+import multiprocessing
+from multiprocessing import Process
+import pycuda.driver as cuda
+import PyNvVideoCodec as nvc
+from os.path import dirname, abspath
+
+
+# Add the parent directory to Python path in a way that works from any working directory
+current_dir = dirname(abspath(__file__))
+parent_dir = dirname(current_dir)
+if parent_dir not in sys.path:
+    sys.path.append(parent_dir)
+
+# Import utilities for encoding
+from utils.Utils import AppFramePerf
+from utils.encode_parser import parse_perf_args, PERF_MAX_FRAMES
+from utils.frame_utils import get_frame_size, create_memory_map, allocate_device_memory
+from utils.encode_parallel_utils import (
+    print_performance_summary,
+    encode_thread_worker,
+    encode_process_worker
+)
+
+
+# Global variables to track resources for cleanup
+g_devicedata = None
+g_mmap = None
+g_context = None
+
+
+def cleanup_resources():
+    """Clean up global resources including memory map, GPU memory, and CUDA context."""
+    global g_devicedata, g_mmap, g_context
+    
+    gc.collect()
+    
+    if g_mmap:
+        try:
+            g_mmap.close()
+            g_mmap = None
+        except:
+            pass
+    
+    if g_devicedata:
+        try:
+            g_devicedata.free()
+            g_devicedata = None
+        except:
+            pass
+    
+    if g_context:
+        try:
+            g_context.detach()
+            g_context = None
+        except:
+            pass
+
+
+atexit.register(cleanup_resources)
+
+
+def run_threaded_encode(args):
+    """Run encoding with multiple threads using shared device memory."""
+    print(f"Initializing {args.num_workers} encode thread{'s' if args.num_workers > 1 else ''}")
+    
+    # Calculate total frames and show warning if needed
+    framesize = get_frame_size(args.width, args.height, args.format)
+    file_size = os.path.getsize(args.raw_file_path)
+    available_frames = file_size // framesize
+    
+    if available_frames > PERF_MAX_FRAMES and args.frame_count == 0:
+        print(f"\nWarning: File contains {available_frames} frames. Limiting to {PERF_MAX_FRAMES} frames for performance testing.")
+    elif args.frame_count > PERF_MAX_FRAMES:
+        print(f"\nWarning: Requested {args.frame_count} frames. Limiting to {PERF_MAX_FRAMES} frames for performance testing.")
+    
+    global g_devicedata, g_mmap, g_context
+    
+    try:
+        # Initialize CUDA
+        cuda.init()
+        cuda_device = cuda.Device(args.gpu_id)
+        g_context = cuda_device.make_context()
+        shared_stream = cuda.Stream()
+        
+        # Open input file and prepare data
+        with open(args.raw_file_path, "rb") as input_file:
+            framesize = get_frame_size(args.width, args.height, args.format)
+            g_mmap = create_memory_map(input_file)
+            
+            # Calculate frames to process
+            frames_to_process = args.frame_count if args.frame_count > 0 else available_frames
+            frames_to_process = min(frames_to_process, available_frames, PERF_MAX_FRAMES)
+            bytes_to_read = frames_to_process * framesize
+            
+            print(f"File contains {available_frames} frames, processing {frames_to_process} frames")
+            
+            # Read and copy data to GPU
+            hostdata = g_mmap.read(bytes_to_read)
+            g_devicedata = allocate_device_memory(hostdata)
+            
+            # Create encoders
+            encoders = []
+            for _ in range(args.num_workers):
+                config = args.config.copy()
+                encoder = nvc.CreateEncoder(
+                    args.width, args.height, args.format, False,
+                    cudacontext=g_context.handle,
+                    cudastream=shared_stream.handle,
+                    **config
+                )
+                encoders.append(encoder)
+            
+            # Run encoding threads
+            result_queue = queue.Queue()
+            begin = time.perf_counter()
+            
+            threads = []
+            for i in range(args.num_workers):
+                t = threading.Thread(
+                    target=encode_thread_worker,
+                    args=(
+                        i, args.raw_file_path, encoders[i], g_devicedata,
+                        framesize, args.width, args.height, args.format,
+                        args.frame_count, result_queue
+                    )
+                )
+                threads.append(t)
+                t.start()
+            
+            total_frames = sum(result_queue.get() for _ in range(args.num_workers))
+            duration = time.perf_counter() - begin
+            for t in threads:
+                t.join()
+
+            print_performance_summary("threads", args.num_workers, total_frames, duration)
+            
+            # Cleanup
+            for encoder in encoders:
+                del encoder
+            encoders.clear()
+    
+    except Exception as e:
+        print(f"An error occurred: {e}")
+    finally:
+        if g_context is not None:
+            g_context.pop()
+
+
+def run_multiprocess_encode(args):
+    """Run encoding with multiple processes using IPC memory sharing."""
+    print(f"Initializing {args.num_workers} encode process{'es' if args.num_workers > 1 else ''}")
+    
+    # Calculate total frames and show warning if needed
+    framesize = get_frame_size(args.width, args.height, args.format)
+    file_size = os.path.getsize(args.raw_file_path)
+    available_frames = file_size // framesize
+    
+    if available_frames > PERF_MAX_FRAMES and args.frame_count == 0:
+        print(f"\nWarning: File contains {available_frames} frames. Limiting to {PERF_MAX_FRAMES} frames for performance testing.")
+    elif args.frame_count > PERF_MAX_FRAMES:
+        print(f"\nWarning: Requested {args.frame_count} frames. Limiting to {PERF_MAX_FRAMES} frames for performance testing.")
+    
+    framesize = get_frame_size(args.width, args.height, args.format)
+    
+    with open(args.raw_file_path, "rb") as input_file:
+        # Calculate frames to process
+        file_size = os.path.getsize(args.raw_file_path)
+        total_frames = file_size // framesize
+        frames_to_process = args.frame_count if args.frame_count > 0 else total_frames
+        frames_to_process = min(frames_to_process, total_frames, PERF_MAX_FRAMES)
+        bytes_to_read = frames_to_process * framesize
+        
+        print(f"File contains {total_frames} frames, processing {frames_to_process} frames")
+        
+        cuda.init()
+        parent_ctx = cuda.Device(args.gpu_id).make_context()
+        m = None
+        devicedata = None
+        ctx_popped_for_workers = False
+        try:
+            m = create_memory_map(input_file)
+            hostdata = m.read(bytes_to_read)
+            devicedata = allocate_device_memory(hostdata)
+            devptrhandle = cuda.mem_get_ipc_handle(devicedata)
+            # Drop parent's CUDA context while workers run. Otherwise the parent and
+            # children keep separate contexts resident on the same GPU and Nsight
+            # shows heavy GPU_CONTEXT_SWITCH_EVENTS (order-of-magnitude vs thread mode).
+            parent_ctx.pop()
+            ctx_popped_for_workers = True
+            
+            result_queue = multiprocessing.Queue()
+            ready_queue = multiprocessing.Queue()
+            go_event = multiprocessing.Event()
+            
+            processes = []
+            for i in range(args.num_workers):
+                config = args.config.copy()
+                p = Process(
+                    target=encode_process_worker,
+                    args=(
+                        i, args.raw_file_path, args.width, args.height,
+                        args.format, devptrhandle, framesize, config,
+                        frames_to_process, result_queue, ready_queue, go_event
+                    )
+                )
+                processes.append(p)
+                p.start()
+            
+            readies = [ready_queue.get() for _ in range(args.num_workers)]
+            if not all(ok for _pid, ok in readies):
+                for p in processes:
+                    if p.is_alive():
+                        p.terminate()
+                    p.join()
+                print("Encoding aborted: setup failed in one or more workers.")
+            else:
+                begin = time.perf_counter()
+                go_event.set()
+                # Stop the timer when workers report frame counts, not when processes exit.
+                # The child still runs finally (encoder destructor, CUDA context teardown) after
+                # result_queue.put; Process.join() waits for that too (~0.3–0.5s+), unlike
+                # Thread.join() after put (see thread path above—same get-then-join pattern).
+                total_frames = sum(result_queue.get() for _ in range(args.num_workers))
+                duration = time.perf_counter() - begin
+                for p in processes:
+                    p.join()
+                print_performance_summary("processes", args.num_workers, total_frames, duration)
+        finally:
+            if ctx_popped_for_workers:
+                parent_ctx.push()
+            if devicedata is not None:
+                devicedata.free()
+            if m is not None:
+                m.close()
+            parent_ctx.pop()
+            parent_ctx.detach()
+    
+    print("All encoding processes completed")
+
+
+if __name__ == "__main__":
+    args = parse_perf_args(
+        "Parallel video encoding application supporting both multithreading and multiprocessing for performance testing."
+    )
+    
+    # Set multiprocessing start method for compatibility
+    if args.mode == "process":
+        multiprocessing.set_start_method('spawn')
+    
+    try:
+        if args.mode == "thread":
+            run_threaded_encode(args)
+        else:  # processes
+            run_multiprocess_encode(args)
+    except Exception as e:
+        print(f"An error occurred: {e}")
+    finally:
+        cleanup_resources()

samples/advanced/encode_reconfigure.py

@@ -0,0 +1,211 @@
+# This copyright notice applies to this file only
+#
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: MIT
+#
+# Permission is hereby granted, free of charge, to any person obtaining a
+# copy of this software and associated documentation files (the "Software"),
+# to deal in the Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish, distribute, sublicense,
+# and/or sell copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+# THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+# DEALINGS IN THE SOFTWARE.
+
+'''
+This sample demonstrates dynamic encoder reconfiguration for bitrate control.
+It shows how to:
+1. Change encoder parameters at runtime
+2. Modify bitrate without resetting the encoder
+3. Handle VBV (Video Buffer Verifier) parameters
+4. Maintain encoding quality during changes
+
+Note: Bitrate changes occur every 100 frames:
+- Frame 0: Original bitrate
+- Frame 100: Half bitrate
+- Frame 200: Original bitrate
+- And so on...
+
+Usage:
+    python encode_reconfigure.py -i <input_file> -s <size> [options]
+
+Example:
+    python encode_reconfigure.py -i input.yuv -s 1920x1080
+
+Arguments:
+    -i: Raw input video file
+    -s: Frame size (e.g., 1920x1080)
+    -if: Input format (default: NV12)
+    -f: Number of frames (default: all)
+    -g: GPU ID (default: 0)
+    -c: Output codec (h264/hevc/av1); overrides codec in JSON config
+    -json: Encoder config file (controls codec, fps, gop, preset, rc, bitrate, etc.)
+
+
+'''
+
+import PyNvVideoCodec as nvc
+import numpy as np
+import sys
+import os
+from os.path import dirname, abspath
+
+# Add the parent directory to Python path in a way that works from any working directory
+current_dir = dirname(abspath(__file__))
+parent_dir = dirname(current_dir)
+if parent_dir not in sys.path:
+    sys.path.append(parent_dir)
+
+# Import utilities for GPU buffer mode
+try:
+    from utils.Utils import AppFrame, FetchCPUFrame, FetchGPUFrame
+    GPU_UTILS_AVAILABLE = True
+except ImportError:
+    GPU_UTILS_AVAILABLE = False
+    print("Warning: Utils module not found. GPU buffer mode will be disabled.")
+
+from utils.encode_parser import parse_reconfigure_encode_args
+
+
+# Constants
+BITRATE_CHANGE_INTERVAL = 100
+BITRATE_REDUCTION_FACTOR = 2
+
+
+def encode(gpu_id, dec_file_path, enc_file_path, width, height, fmt, config_params, frame_count=0):
+    """
+    Encode video with dynamic bitrate reconfiguration.
+
+    This function demonstrates bitrate change at runtime without the need to reset the encoder session.
+    The application reduces the bitrate by half and then restores it to the original value after
+    every 100 frames.
+
+    Parameters:
+        gpu_id (int): Ordinal of GPU to use [Parameter not in use]
+        dec_file_path (str): Path to file to be decoded
+        enc_file_path (str): Path to output file for encoded frames
+        width (int): Width of encoded frame
+        height (int): Height of encoded frame
+        fmt (str): Surface format string in uppercase (e.g., "NV12")
+        config_params (dict): Key-value pairs providing fine-grained control on encoding
+
+    Returns:
+        None
+
+    Example:
+        >>> encode(0, "input.yuv", "output.h264", 1920, 1080, "NV12", {"codec": "h264"})
+        Encode 1080p NV12 raw YUV into elementary bitstream using H.264 codec
+    """
+    try:
+        with open(dec_file_path, "rb") as decFile, open(enc_file_path, "wb") as encFile:
+            # Create encoder object
+            config_params["gpu_id"] = gpu_id
+            
+            if "tuning_info" in config_params:
+                tuning_info_val = config_params['tuning_info']
+                if tuning_info_val == "low_latency":
+                    config_params['bf'] = 0
+            
+            nvenc = nvc.CreateEncoder(width, height, fmt, False, **config_params)
+            # Create input frame list
+            input_frame_list = [AppFrame(width, height, fmt) for _ in range(1, 5)]
+            
+            # Get initial encoder parameters
+            reconf_params = nvenc.GetEncodeReconfigureParams()
+            original_avgbitrate = reconf_params.averageBitrate
+            if "vbvbufsize" in config_params:
+                original_vbvbuffersize = config_params['vbvbufsize']
+            else:
+                original_vbvbuffersize = int(original_avgbitrate * reconf_params.frameRateDen / reconf_params.frameRateNum)
+            
+            original_vbvinitdelay = original_vbvbuffersize
+            
+            
+            # Process frames
+            # Calculate total available frames from file size
+            file_size = os.path.getsize(dec_file_path)
+            available_frames = file_size // input_frame_list[0].frameSize
+            
+            # Determine frames to process
+            frames_to_process = frame_count if frame_count > 0 else available_frames
+            frames_to_process = min(frames_to_process, available_frames)
+            
+            print(f"File contains {available_frames} frames, processing {frames_to_process} frames")
+            
+            for i, input_gpu_frame in enumerate(
+                FetchGPUFrame(
+                    input_frame_list,
+                    FetchCPUFrame(decFile, input_frame_list[0].frameSize),
+                    frames_to_process
+                )
+            ):
+                # Reconfigure bitrate every 100 frames
+                if i % BITRATE_CHANGE_INTERVAL == 0:
+                    if i % (BITRATE_CHANGE_INTERVAL * 2) != 0:
+                        # Reduce bitrate by half
+                        reconf_params.averageBitrate = int(original_avgbitrate / BITRATE_REDUCTION_FACTOR)
+                        reconf_params.vbvBufferSize = int(original_vbvbuffersize / BITRATE_REDUCTION_FACTOR)
+                        reconf_params.vbvInitialDelay = int(original_vbvinitdelay / BITRATE_REDUCTION_FACTOR)
+                    else:
+                        # Restore original bitrate
+                        reconf_params.averageBitrate = original_avgbitrate
+                        reconf_params.vbvBufferSize = original_vbvbuffersize
+                        reconf_params.vbvInitialDelay = original_vbvinitdelay
+                    
+                    nvenc.Reconfigure(reconf_params)
+                
+                # Encode frame
+                pic_params = nvc.NV_ENC_PIC_PARAMS()
+                pic_params.inputTimeStamp = i
+                packets = nvenc.Encode(input_gpu_frame, pic_params)
+                encFile.write(
+                    bytearray(b"".join(bytes(p["data"]) for p in packets))
+                )
+            
+            # Flush encoder queue
+            flush_packets = nvenc.EndEncode()
+            encFile.write(bytearray(b"".join(bytes(p["data"]) for p in flush_packets)))
+            print(f"Completed encoding {frames_to_process} frames using CPU buffers")
+            print(f"Output file: {enc_file_path}")
+            
+    except nvc.PyNvVCExceptionUnsupported as e:
+        print(f"CreateEncoder failure: {e}")
+    except Exception as e:
+        print(f"An unexpected error occurred: {e}")
+
+
+if __name__ == "__main__":
+    args = parse_reconfigure_encode_args(
+        "This sample application demonstrates bitrate change at runtime without resetting the encoder session."
+    )
+
+    print("=" * 60)
+    print("Configuration:")
+    print(f"Input: {args.raw_file_path}")
+    print(f"Output: {args.encoded_file_path}")
+    print(f"Size: {args.width}x{args.height}")
+    print(f"Format: {args.format}")
+    print(f"Codec: {args.codec}")
+    print(f"GPU ID: {args.gpu_id}")
+    print(f"Frame count: {args.frame_count if args.frame_count > 0 else 'All frames'}")
+    print("=" * 60)
+
+    encode(
+        args.gpu_id,
+        args.raw_file_path.as_posix(),
+        args.encoded_file_path.as_posix(),
+        args.width,
+        args.height,
+        args.format,
+        args.config,
+        args.frame_count
+    )