PyNvVideoCodec 2.2.1__cp313-cp313-win_arm64.whl

samples/advanced/encode_sei_msg.py

@@ -0,0 +1,188 @@
+# 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 SEI (Supplemental Enhancement Information) message insertion during encoding.
+It shows how to:
+1. Create and format SEI messages
+2. Insert SEI data into the encoded bitstream
+3. Handle codec-specific SEI types
+4. Manage message timing and placement
+
+SEI messages are additional data embedded in video streams that provide supplementary information:
+- HDR/Display Metadata: Color volume, light levels, and transfer characteristics for HDR content
+- Timecode Data: Frame timing and sequence information
+- Custom Metadata: User-defined data for application-specific needs
+
+Common Use Cases:
+- Video Playback: HDR display configuration and color management
+- Content Creation: Frame accurate editing and post-processing
+- Broadcast: Timing synchronization and content identification
+- Custom Applications: Embedding application-specific metadata in the video stream
+
+Usage:
+    python encode_sei_msg.py -i <input_file> -s <size> [options]
+
+Example:
+    python encode_sei_msg.py -i input.yuv -o output.h264 -s 1920x1080
+
+Arguments:
+    -i: Raw input video file
+    -o: Output encoded file (optional, default: <input_name>.<codec>)
+    -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 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_sei_encode_args
+SEI_MESSAGE_1 = [0xdc, 0x45, 0xe9, 0xbd, 0xe6, 0xd9, 0x48, 0xb7, 0x96, 0x2c, 0xd8, 0x20, 0xd9, 0x23, 0xee, 0xef]
+SEI_MESSAGE_2 = [0x12, 0x67, 0x56, 0xda, 0xef, 0x99, 0x00, 0xbb, 0x6a, 0xc4, 0xd8, 0x10, 0xf9, 0xe3, 0x3e, 0x8f]
+
+
+def encode_with_sei_msg(gpu_id, dec_file_path, enc_file_path, width, height, fmt, config_params, frame_count=0):
+    """
+    Encode frames with SEI message insertion into the bitstream 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 SEI message data and submits them to NVENC hardware for encoding.
+    Video memory buffer is allocated to get the NVENC hardware output, which is then copied to host memory
+    for file storage.
+
+    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 with SEI messages
+    """
+    try:
+        # Determine SEI type based on codec
+        if config_params["codec"] in ["hevc", "h264"]:
+            sei_info = {"sei_type": 5}
+        elif config_params["codec"] == "av1":
+            sei_info = {"sei_type": 6}
+        else:
+            raise ValueError(f"Unsupported codec: {config_params['codec']}")
+
+        # Create SEI messages list
+        sei_messages = [(sei_info, SEI_MESSAGE_1), (sei_info, SEI_MESSAGE_2)]
+
+        with open(dec_file_path, "rb") as decFile, open(enc_file_path, "wb") as encFile:
+            # Create encoder object
+            config_params["gpu_id"] = gpu_id
+            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)]
+            
+            # 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 input_gpu_frame in FetchGPUFrame(
+                input_frame_list,
+                FetchCPUFrame(decFile, input_frame_list[0].frameSize),
+                frames_to_process
+            ):
+                packets = nvenc.Encode(input_gpu_frame, 0, sei_messages)
+                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"Encoded frames written to {enc_file_path} with SEI messages")
+
+    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_sei_encode_args(
+        "This sample application illustrates encoding of frames with SEI message insertion."
+    )
+
+    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_with_sei_msg(
+        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
+    )

samples/advanced/simple_decode_from_memory.py

@@ -0,0 +1,151 @@
+# 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 that SimpleDecoder can decode directly from in-memory
+sources -- no temporary file required. It showcases every supported in-memory
+input type in one place:
+
+  1. bytes        -- an immutable in-memory buffer
+  2. bytearray    -- a mutable in-memory buffer
+  3. memoryview   -- a zero-copy view over a buffer
+  4. BinaryIO     -- any seekable file-like object (file handle, io.BytesIO,
+                     tarfile member, S3/HTTP range-reader, etc.)
+
+There are two distinct mechanisms under the hood:
+
+  * bytes / bytearray / memoryview ("bytestream"):
+      The entire buffer is copied once into native memory, then FFmpeg reads
+      from it. Fast per-read (no Python callbacks), uses memory proportional
+      to the file size. Best when the whole clip is already in RAM.
+
+  * BinaryIO stream:
+      The data stays in the source; FFmpeg pulls only the bytes it needs
+      (container headers + the packets for the requested frames) on demand by
+      calling the object's read()/seek() methods. No full-file copy. Best for
+      large videos or remote/archived sources (tar, S3, HTTP).
+
+All input types are fully SEEKABLE and support the complete SimpleDecoder API:
+len(), random access (decoder[i]), slicing, out-of-order batch access
+(get_batch_frames_by_index), seek_to_index, and stream metadata.
+
+This is the key difference from decode_from_memory_buffer.py, which uses the
+older streaming (non-seekable) callback demuxer and only supports sequential
+decode.
+
+Usage: python simple_decode_from_memory.py -i <input_file>
+Example: python simple_decode_from_memory.py -i input.mp4
+
+Arguments:
+  -i: Input video file (container format such as MP4, MKV, etc.)
+  -g: GPU ID to use (default: 0)
+'''
+
+import argparse
+import io
+
+import PyNvVideoCodec as nvc
+
+
+def exercise_decoder(decoder, source_label):
+    """Run the full seekable SimpleDecoder contract against any in-memory source."""
+    total_frames = len(decoder)
+    metadata = decoder.get_stream_metadata()
+
+    print(f"  Source type      : {source_label}")
+    print(f"  Total frames     : {total_frames}")
+    print(f"  Resolution       : {metadata.width}x{metadata.height}")
+    print(f"  Codec            : {metadata.codec_name}")
+    print(f"  Average FPS      : {metadata.average_fps:.2f}")
+    print(f"  Duration         : {metadata.duration:.3f}s")
+
+    # Random access via decoder[i]: fetch the first and last frame from the
+    # in-memory source.
+    # NOTE: the default output is NATIVE (NV12 for 8-bit 4:2:0). An NV12 frame is
+    # returned as a single 2D buffer of shape (height * 3 / 2, width): the luma
+    # plane (height x width) stacked on top of the interleaved chroma plane
+    # (height/2 x width). So a 1920x1080 picture has buffer shape (1620, 1920) --
+    # that is the NV12 layout, not a different resolution. Use
+    # output_color_type=nvc.OutputColorType.RGB for a (height, width, 3) image shape.
+    for idx in [0, total_frames - 1]:
+        frame = decoder[idx]
+        print(f"  decoder[{idx:>3}]     : NV12 buffer shape={tuple(frame.shape)} "
+              f"(picture {metadata.width}x{metadata.height})")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Demonstrates SimpleDecoder decoding from bytes, bytearray, "
+                    "memoryview, and BinaryIO stream inputs."
+    )
+    parser.add_argument("-i", "--input", required=True, help="Input video file path")
+    parser.add_argument("-g", "--gpu_id", type=int, default=0, help="GPU ID (default: 0)")
+    args = parser.parse_args()
+
+    # Read the file once; we reuse the raw bytes to build each input type.
+    print(f"Reading {args.input} into memory...")
+    with open(args.input, "rb") as f:
+        raw = f.read()
+    print(f"  Buffer size: {len(raw) / (1024 * 1024):.2f} MiB\n")
+
+    # ------------------------------------------------------------------
+    # Group 1: bytestream inputs (full buffer copied into native memory)
+    # ------------------------------------------------------------------
+    print("=" * 64)
+    print("bytestream inputs (whole buffer copied into native memory)")
+    print("=" * 64)
+
+    print("\n--- bytes ---")
+    exercise_decoder(nvc.SimpleDecoder(raw, gpu_id=args.gpu_id), "bytes")
+
+    print("\n--- bytearray ---")
+    exercise_decoder(nvc.SimpleDecoder(bytearray(raw), gpu_id=args.gpu_id), "bytearray")
+
+    print("\n--- memoryview ---")
+    exercise_decoder(nvc.SimpleDecoder(memoryview(raw), gpu_id=args.gpu_id), "memoryview")
+
+    # ------------------------------------------------------------------
+    # Group 2: BinaryIO stream inputs (bytes pulled on demand, no copy)
+    # ------------------------------------------------------------------
+    print("\n" + "=" * 64)
+    print("BinaryIO stream inputs (bytes pulled on demand, no full copy)")
+    print("=" * 64)
+
+    # A file handle is itself a BinaryIO object -- decode straight from it.
+    print("\n--- open(path, 'rb') file stream ---")
+    with open(args.input, "rb") as file_stream:
+        exercise_decoder(nvc.SimpleDecoder(file_stream, gpu_id=args.gpu_id),
+                         "file handle (BinaryIO)")
+
+    # io.BytesIO wraps an in-memory buffer as a seekable stream.
+    print("\n--- io.BytesIO stream ---")
+    exercise_decoder(nvc.SimpleDecoder(io.BytesIO(raw), gpu_id=args.gpu_id),
+                     "io.BytesIO (BinaryIO)")
+
+    print("\nDone. SimpleDecoder decoded the same video from "
+          "bytes, bytearray, memoryview, and BinaryIO streams.")
+
+
+if __name__ == "__main__":
+    main()

samples/advanced/simple_decode_stats.py

@@ -0,0 +1,179 @@
+# 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 how to extract and analyze decode statistics using SimpleDecoder
+in PyNvVideoCodec. It shows how to:
+1. Enable statistics collection with SimpleDecoder
+2. Extract statistics from decoded frames
+3. Parse and analyze the statistics
+4. Write formatted results to a file
+
+
+Core module for handling decode statistics.
+
+This module provides functionality for extracting and analyzing low-level video decoding 
+statistics from H.264/H.265 streams. The following statistics are collected and analyzed:
+
+1. QP (Quantization Parameter) Analysis:
+   - Average, min, max QP values per frame
+   - Indicates compression level and quality trade-offs
+   - Higher QP = more compression, potentially lower quality
+
+2. CU (Coding Unit) Type Distribution:
+   - INTRA: Spatial prediction (current frame only)
+   - INTER: Temporal prediction (motion compensation)
+   - SKIP: Copy from reference without residual
+   - PCM: Uncompressed raw pixel values
+
+3. Motion Vector Statistics:
+   - MV0: Primary motion vectors (L0 reference)
+   - MV1: Secondary motion vectors (L1 reference, B-frames)
+   - Magnitude analysis for temporal complexity assessment
+
+4. Macroblock Details:
+   - Per-block encoding decisions and parameters
+   - Motion vector coordinates and directions
+   - QP values and prediction types for debugging
+
+These statistics are valuable for:
+- Video quality analysis
+- Encoder behavior understanding
+- Performance optimization
+- Debugging encoding/decoding issues
+
+Usage: python single_decode_stats.py -i <input_video_file> -p <output_stats_file> -d <use_device_memory>
+Example: python single_decode_stats.py -i test_video.mp4 -p test_video_stats.txt -d 0
+
+Arguments:
+  -i: Input video file
+  -p: Output file for statistics (default: <input_name>_stats.txt)
+  -d: Use device memory (1) or host memory (0) (default: 1)
+  -g: GPU ID to use (default: 0)
+
+Note: For large videos, consider processing in segments to manage memory usage.
+'''
+
+import sys
+import argparse
+from pathlib import Path
+import PyNvVideoCodec as nvc
+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 decoding
+from utils.decode_parser import parse_stats_args
+from utils.Utils import get_frame_data
+from utils.decode_stats_writer import DecodeStatsWriter
+
+    
+def decode(gpu_id, enc_file_path, stats_file_path, use_device_memory, need_scanned_stream_metadata):
+    """
+    Function to decode media file, write decode statistics into output file.    
+
+    Parameters:
+        gpu_id (int): Ordinal of GPU to use
+        enc_file_path (str): Path to file to be decoded
+        stats_file_path (str): Path to output file for decode statistics
+        use_device_memory (int): If set to 1, output decoded frame is CUDeviceptr wrapped in CUDA Array Interface
+        need_scanned_stream_metadata (bool): If True, scan stream for detailed metadata (keyframe locations, etc.)
+
+    Returns:
+        None
+    """
+
+    with open(stats_file_path, "w", newline='\n') as stats_file:
+        try:
+            # Initialize decoder
+            simple_decoder = nvc.SimpleDecoder(
+                enc_file_path, 
+                need_scanned_stream_metadata=need_scanned_stream_metadata,
+                use_device_memory=use_device_memory, 
+                gpu_id=gpu_id,
+                enableDecodeStats=True
+            )
+
+            # Get metadata and initialize stats writer
+            metadata = simple_decoder.get_stream_metadata()
+            stats_writer = DecodeStatsWriter(stats_file)
+
+            stats_count = 0
+            decoded_frame_count = 0
+
+            # Process frames
+            for decoded_frame in simple_decoder:
+                if hasattr(decoded_frame, 'decode_stats_size') and decoded_frame.decode_stats_size > 0:
+                    try:
+                        parsed_stats = decoded_frame.ParseDecodeStats()
+                        if len(parsed_stats.get("qp_luma", [])) > 0:
+                            stats_count += 1
+                            stats_writer.write_frame_stats(
+                                decoded_frame_count,
+                                parsed_stats
+                            )
+                    except Exception as e:
+                        print(f"Frame {decoded_frame_count}: API parsing failed: {e}")
+
+                decoded_frame_count += 1
+
+            # Print summary
+            print(f"Decoded {decoded_frame_count} frames")
+            if stats_count == 0:
+                print(f"Decode statistics not found")
+            else:
+                print(f"Decode statistics of {stats_count} frames written to: {stats_file_path}\n")
+
+        except nvc.PyNvVCExceptionUnsupported as e:
+            print(f"CreateDecoder failure: {e}")
+        except Exception as e:
+            print(f"An unexpected error occurred: {e}")
+
+if __name__ == "__main__":
+    args = parse_stats_args(
+        "This sample application demonstrates decoding media files and extracting decode statistics. "
+        "Use -p to enable parsing and text output."
+    )
+    
+    print("=" * 60)
+    print("Configuration:")
+    print(f"Input: {args.encoded_file_path}")
+    print(f"Stats Output: {args.stats_file_path}")
+    print(f"GPU ID: {args.gpu_id}")
+    print(f"Use Device Memory: {args.use_device_memory}")
+    print(f"Need Scanned Stream Metadata: {args.need_scanned_stream_metadata}")
+    print("=" * 60)
+
+    decode(
+        args.gpu_id,
+        args.encoded_file_path,
+        args.stats_file_path,
+        args.use_device_memory,
+        args.need_scanned_stream_metadata
+    )