PyNvVideoCodec 2.0.4__cp314-cp314-win_amd64.whl

samples/basic/create_video_segments.py

@@ -0,0 +1,187 @@
+# 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 video segmentation which can be useful for creating training data for machine learning models.
+It shows how to:
+1. Extract segments from a video file based on timestamp ranges
+2. Use the SimpleDecoder to get video metadata
+3. Configure and use the Transcoder for segment extraction
+4. Handle multiple output segments with proper naming
+
+Usage:
+    python create_video_segments.py -i <input_file> [options]
+
+Example:
+    python create_video_segments.py -i input.mp4 -s segments.txt -c config.json
+
+Arguments:
+    -i: Input video file
+    -s: Segments file (default: segments.txt)
+    -c: Transcoder config file (default: transcode_config.json)
+    -o: Output filename template
+    -g: GPU ID (default: 0)
+
+Segments File Format:
+    start_time end_time
+    Example:
+        0.0 10.5
+        15.0 30.0
+        45.5 60.0
+
+Output file format:
+    This is the default output template. The file name can be customized using the -o argument. Time stamp is appended to the file name.
+    {input_file_name}_segment_{start_time}_{end_time}.mp4
+    Example:
+        input_file_name_segment_0.0_10.5.mp4
+        input_file_name_segment_15.0_30.0.mp4
+        input_file_name_segment_45.5_60.0.mp4
+
+Note: Times are in seconds. Each segment is validated against video duration.
+'''
+
+import json
+import os
+import sys
+from os.path import dirname, abspath
+import PyNvVideoCodec as nvc
+
+
+# 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)
+
+from utils.transcode_parser import parse_transcode_args
+
+
+def get_video_duration(input_file_path: str, gpu_id: int) -> float:
+    """Get video duration in seconds."""
+    try:
+        decoder = nvc.SimpleDecoder(input_file_path, gpu_id=gpu_id)
+        duration = decoder.get_stream_metadata().duration
+        print(f"Video duration: {duration:.2f} seconds")
+        return duration
+    except Exception as e:
+        print(f"Error getting video duration: {e}")
+        return 0.0
+
+
+def create_video_segments(input_file_path: str, segments_file_path: str,
+                         config_file_path: str, output_template: str, gpu_id: int):
+    """Create video segments from input file based on segments text file."""
+    
+    # Get video duration for validation
+    duration = get_video_duration(input_file_path, gpu_id)
+    if duration <= 0:
+        print("Error: Could not determine video duration")
+        return
+    
+    # Load transcoder configuration
+    with open(config_file_path) as json_file:
+        config = json.load(json_file)
+    
+    input_file_name_base = os.path.splitext(os.path.basename(input_file_path))[0]
+    successful_segments = 0
+    
+    # Process segments file
+    with open(segments_file_path, 'r') as file:
+        for line_num, line in enumerate(file, 1):
+            line = line.strip()
+            if not line:  # Skip empty lines
+                continue
+                
+            try:
+                start_ts_str, end_ts_str = line.split()
+                start_time = float(start_ts_str)
+                end_time = float(end_ts_str)
+                
+                # Error check: end timestamp should not exceed media duration
+                if end_time > duration:
+                    print(f"Warning: Line {line_num}: End time {end_time:.2f}s exceeds video duration {duration:.2f}s - clipping to duration")
+                    end_time = duration
+                
+                if start_time >= end_time:
+                    print(f"Error: Line {line_num}: Invalid time range {start_time}-{end_time}")
+                    continue
+                
+                # Generate output path
+                base_output_path = output_template.format(input_file_name=input_file_name_base)
+                base_output_name, base_output_ext = os.path.splitext(base_output_path)
+                if not base_output_ext:
+                    base_output_ext = '.mp4'
+                    base_output_path = base_output_name + base_output_ext
+                
+                start_time = round(start_time, 2)
+                end_time = round(end_time, 2)
+                print(f"Creating segment: {start_time:g}s - {end_time:g}s")
+                
+                # Create transcoder and generate segment
+                transcoder = nvc.Transcoder(input_file_path, base_output_path, gpu_id, 0, 0, **config)
+                transcoder.segmented_transcode(start_time, end_time)
+                
+                # Expected output filename (API appends timestamps)
+                final_output = f"{base_output_name}_{start_time:g}_{end_time:g}{base_output_ext}"
+                print(f"✓ Created: {final_output}")
+                successful_segments += 1
+                
+            except ValueError as e:
+                print(f"Error: Line {line_num}: Invalid format '{line}' - {e}")
+            except Exception as e:
+                print(f"Error: Line {line_num}: Failed to create segment - {e}")
+    
+    print(f"\nSummary: {successful_segments} segments created successfully")
+
+
+def main():
+    args = parse_transcode_args("Create video segments from text file input")
+    
+    # Display configuration
+    print("=" * 60)
+    print("VIDEO SEGMENTATION CONFIGURATION")
+    print("=" * 60)
+    print(f"Input: {args.input_file_path}")
+    print(f"Segments File: {args.segments_file_path}")
+    print(f"Config File: {args.config_file_path}")
+    print(f"GPU ID: {args.gpu_id}")
+    print("=" * 60)
+    
+    # Validate files exist
+    for file_path, name in [(args.input_file_path, "Input video"), 
+                           (args.segments_file_path, "Segments file"), 
+                           (args.config_file_path, "Config file")]:
+        if not os.path.exists(file_path):
+            print(f"Error: {name} not found: {file_path}")
+            return
+    
+    create_video_segments(args.input_file_path, args.segments_file_path, args.config_file_path, 
+                         args.output_template, args.gpu_id)
+    
+    print("=" * 60)
+    print("SEGMENTATION COMPLETE")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

samples/basic/encode.py

@@ -0,0 +1,347 @@
+# 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 unified video encoding with support for both CPU and GPU buffer modes.
+
+It shows how to:
+1. Configure and use different buffer modes for encoding
+2. Handle both host (CPU) and device (GPU) memory efficiently
+3. Manage encoder resources and states
+4. Process frames with optimal memory handling
+5. Write encoded elementary streams to a file
+
+The sample supports two buffer modes:
+- CPU Buffer Mode:
+  * Uses host memory for frame data
+
+- GPU Buffer Mode:
+  * Uses device memory for frame data
+
+Usage:
+    python encode.py -i <input_file> -s <size> -m <mode> [options]
+
+Examples:
+    # Encode to raw H.264 bitstream
+    python encode.py -i input.yuv -s 1920x1080 -m gpu -o output.h264
+
+    # AV1 elementary (.av1): IVF container + patched frame count (AppEncCuda-compatible)
+    python encode.py -i input.yuv -s 1920x1080 -m cpu -c AV1 -o output.av1
+
+Arguments:
+    -i: Raw input video file
+    -s: Frame size (e.g., 1920x1080)
+    -m: Buffer mode (cpu/gpu)
+    -if: Input format (default: NV12)
+    -c: Codec (H264, HEVC, AV1)
+    -f: Number of frames (default: all)
+    -g: GPU ID (default: 0)
+    -json: Encoder config file
+    -o: Output file
+
+'''
+
+import PyNvVideoCodec as nvc
+import numpy as np
+import os
+import sys
+from os.path import join, 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.")
+
+
+# Import utilities for frame handling
+from utils.frame_utils import get_frame_size
+from utils.encode_parser import parse_unified_args
+
+
+
+
+def _concat_encode_packets(packets) -> bytes:
+    """Join Encode / EndEncode output into one bitstream blob."""
+    return b"".join(bytes(p["data"]) for p in packets)
+
+
+def _av1_ivf_elementary_enabled(config_params: dict) -> bool:
+    """True when output is AV1 in IVF (elementary), matching VideoCodecSDK AppEncCuda."""
+    if config_params.get("codec", "h264").lower() != "av1":
+        return False
+    v = str(config_params.get("use_ivf_container", "1")).lower()
+    return v not in ("0", "false", "no")
+
+
+def _patch_ivf_output_file(output_file_path: str, ivf_packet_count: int) -> None:
+    """Match FFmpeg ivf_write_trailer: frame count at IVF global header offset 24 (LE32)."""
+    if ivf_packet_count <= 0:
+        return
+    with open(output_file_path, "r+b") as out_f:
+        if out_f.read(4) != b"DKIF":
+            return
+        out_f.seek(24)
+        out_f.write(ivf_packet_count.to_bytes(4, "little"))
+
+
+def encode_cpu_buffer(gpu_id, dec_file_path, enc_file_path, width, height, fmt, config_params, frame_count):
+    """
+    Encode frames using host memory buffers as input.
+
+    This function reads image data from a file and copies it to CUDA buffers for encoding.
+    The encoder submits the data to NVENC hardware for encoding. Video memory buffer is
+    allocated to get the NVENC hardware output. The output is copied from video memory
+    to host memory for file storage.
+
+    Parameters:
+        gpu_id (int): Ordinal of GPU to 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
+        frame_count (int): Number of frames to encode
+
+    Returns:
+        None
+    """
+    print("Using CPU buffer mode")
+
+    codec = config_params.get("codec", "h264").lower()
+    if codec == "av1":
+        config_params.setdefault("use_ivf_container", "1")
+
+    frame_size = get_frame_size(width, height, fmt)
+
+    with open(dec_file_path, "rb") as dec_file:
+        config_params["gpu_id"] = gpu_id
+        nvenc = nvc.CreateEncoder(width, height, fmt, True, **config_params)  # True = use CPU buffers
+        
+        # Calculate total available frames from file size
+        file_size = os.path.getsize(dec_file_path)
+        available_frames = file_size // frame_size
+        
+        # Determine frames to process with limit
+        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 using CPU buffers...")
+
+        enc_file = open(enc_file_path, "wb")
+        frames_encoded = 0
+        ivf_packets = 0
+
+        for i in range(frames_to_process):
+            chunk = np.fromfile(dec_file, np.uint8, count=frame_size)
+            if chunk.size != 0:
+                pic_params = nvc.NV_ENC_PIC_PARAMS()
+                pic_params.inputTimeStamp = frames_encoded
+                enc_list = nvenc.Encode(chunk, pic_params)
+                ivf_packets += len(enc_list)
+                enc_file.write(bytearray(_concat_encode_packets(enc_list)))
+                frames_encoded += 1
+            else:
+                print(f"Warning: Could not read frame {i+1}")
+                break
+
+        # Flush encoder queue
+        flush_list = nvenc.EndEncode()
+        ivf_packets += len(flush_list)
+        enc_file.write(bytearray(_concat_encode_packets(flush_list)))
+        if _av1_ivf_elementary_enabled(config_params):
+            enc_file.flush()
+            _patch_ivf_output_file(enc_file_path, ivf_packets)
+        enc_file.close()
+
+        print(f"Completed encoding {frames_encoded} frames using CPU buffers")
+        print(f"Output file: {enc_file_path}")
+
+
+def encode_gpu_buffer(gpu_id, dec_file_path, enc_file_path, width, height, fmt, config_params, frame_count):
+    """
+    Encode frames using CUDA device buffers as input.
+
+    This function reads image data from a file and loads it to CUDA input buffers using
+    FetchGPUFrame(). The encoder copies the CUDA buffers and submits them to NVENC hardware
+    for encoding. Video memory buffer is allocated to get the NVENC hardware output.
+    The output is copied from video memory to host memory for file storage.
+
+    Parameters:
+        gpu_id (int): Ordinal of GPU to 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
+        frame_count (int): Number of frames to encode
+
+    Returns:
+        None
+    """
+    print("Using GPU buffer mode")
+
+    if not GPU_UTILS_AVAILABLE:
+        raise RuntimeError("GPU buffer mode requires Utils module (AppFrame, FetchCPUFrame, FetchGPUFrame)")
+
+    codec = config_params.get("codec", "h264").lower()
+    if codec == "av1":
+        config_params.setdefault("use_ivf_container", "1")
+
+    # Show encoder capabilities
+    caps = nvc.GetEncoderCaps(codec=config_params.get("codec", "h264"))
+    if "num_encoder_engines" in caps:
+        print(f"Number of NVENCs: {caps['num_encoder_engines']}")
+
+    with open(dec_file_path, "rb") as decFile:
+        config_params["gpu_id"] = gpu_id
+        nvenc = nvc.CreateEncoder(width, height, fmt, False, **config_params)  # False = use GPU buffers
+        input_frame_list = [AppFrame(width, height, fmt) for _ in range(1, 5)]
+        
+        # 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 with limit
+        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 using GPU buffers...")
+
+        encFile = open(enc_file_path, "wb")
+        frames_encoded = 0
+        ivf_packets = 0
+
+        for input_gpu_frame in FetchGPUFrame(
+            input_frame_list,
+            FetchCPUFrame(decFile, input_frame_list[0].frameSize),
+            frames_to_process
+        ):
+            pic_params = nvc.NV_ENC_PIC_PARAMS()
+            pic_params.inputTimeStamp = frames_encoded
+            enc_list = nvenc.Encode(input_gpu_frame, pic_params)
+            ivf_packets += len(enc_list)
+            encFile.write(bytearray(_concat_encode_packets(enc_list)))
+            frames_encoded += 1
+
+        # Flush encoder queue
+        flush_list = nvenc.EndEncode()
+        ivf_packets += len(flush_list)
+        encFile.write(bytearray(_concat_encode_packets(flush_list)))
+        if _av1_ivf_elementary_enabled(config_params):
+            encFile.flush()
+            _patch_ivf_output_file(enc_file_path, ivf_packets)
+        encFile.close()
+
+    print(f"Completed encoding {frames_to_process} frames using GPU buffers")
+    print(f"Output file: {enc_file_path}")
+
+
+def encode_unified(gpu_id, dec_file_path, enc_file_path, width, height, fmt, config_params, frame_count, buffer_mode):
+    """
+    Unified encoding function that supports both CPU and GPU buffer modes.
+
+    Parameters:
+        gpu_id (int): Ordinal of GPU to 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
+        frame_count (int): Number of frames to encode
+        buffer_mode (str): Buffer mode - "cpu" or "gpu"
+
+    Returns:
+        None
+    """
+    try:
+        if buffer_mode.lower() == "cpu":
+            encode_cpu_buffer(gpu_id, dec_file_path, enc_file_path, width, height, fmt, config_params, frame_count)
+        elif buffer_mode.lower() == "gpu":
+            encode_gpu_buffer(gpu_id, dec_file_path, enc_file_path, width, height, fmt, config_params, frame_count)
+        else:
+            raise ValueError(f"Invalid buffer mode: {buffer_mode}. Must be 'cpu' or 'gpu'")
+            
+    except nvc.PyNvVCExceptionUnsupported as e:
+        print(f"CreateEncoder failure: {e}")
+    except Exception as e:
+        print(f"An unexpected error occurred: {e}")
+
+
+def validate_gpu_mode(args) -> None:
+    """Validate GPU buffer mode requirements."""
+    if args.buffer_mode == "gpu" and not GPU_UTILS_AVAILABLE:
+        print("Error: GPU buffer mode requires Utils module, but it's not available.")
+        print("Please use CPU buffer mode (-m cpu) or ensure Utils module is accessible.")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    args = parse_unified_args(
+        "Unified encoding application supporting both CPU and GPU buffer modes."
+    )
+
+    # Display configuration
+    print("=" * 60)
+    print("ENCODER CONFIGURATION")
+    print("=" * 60)
+    print(f"Buffer mode: {args.buffer_mode.upper()}")
+    print(f"Input file: {args.raw_file_path}")
+    print(f"Output file: {args.encoded_file_path}")
+    print(f"Resolution: {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)
+
+    # Validate GPU mode requirements
+    validate_gpu_mode(args)
+    
+    # Run encoding
+    encode_unified(
+        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,
+        args.buffer_mode,
+    )
+
+    print("=" * 60)
+    print("ENCODING COMPLETE")
+    print("=" * 60)

samples/basic/encode_config.json

@@ -0,0 +1,9 @@
+{
+    "preset" : "p3",
+    "tuning_info" : "high_quality",
+    "rc": "vbr",
+    "fps"  : 30,
+    "bitrate" : 10000000,
+    "maxbitrate" : 10000000,
+    "vbvbufsize" : 10000000
+}

samples/basic/segments.txt

@@ -0,0 +1,3 @@
+0.3 0.8
+2 4
+3 8