PyNvVideoCodec 2.0.4__cp314-cp314-win_amd64.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)
+    -c: Codec (H264, HEVC, AV1)
+    -f: Number of frames (default: all)
+    -g: GPU ID (default: 0)
+    -json: Encoder config file
+
+'''
+
+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_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
+    )

samples/advanced/transcode.py

@@ -0,0 +1,288 @@
+# This copyright notice applies to this file only
+#
+# SPDX-FileCopyrightText: Copyright (c) 2025 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.
+
+"""
+Transcode video files using NVIDIA's GPU zero-copy pipeline -- demux ->
+NVDEC -> NVENC -> mux, with audio passthrough.
+
+It shows how to:
+1. Create a runtime CUDA context and stream and pass them to decoder + encoder
+2. Decode an input video file to GPU memory
+3. Re-encode the decoded frames in-place (no host round-trip) to a different
+   codec / container
+4. Demux video + audio in lockstep (DemuxNoSkipAudio) and mux both to the
+   output container, preserving the source's A/V interleave + bit-exact PTS
+
+CLI is provided by samples/utils/transcode_parser.py
+(parse_advanced_transcode_args).  Run with `--help` for the flag list.
+
+Example:
+    # Transcode H264 -> HEVC, mux to MP4 (video + audio in order)
+    python transcode.py -i input.mp4 -o output.mp4 -c HEVC
+
+    # Same, with diagnostic YUV + raw bitstream dump
+    python transcode.py -i input.mp4 -o output.mp4 -c HEVC --dump
+
+    # Override encoder bitrate / preset / etc. via JSON
+    python transcode.py -i input.mp4 -o output.mp4 -c H264 -json my_config.json
+"""
+
+import sys
+from pathlib import Path
+from os.path import dirname, abspath
+
+import pycuda.driver as cuda
+
+# Add the parent directory to Python path so `utils.*` imports resolve
+current_dir = dirname(abspath(__file__))
+parent_dir = dirname(current_dir)
+if parent_dir not in sys.path:
+    sys.path.append(parent_dir)
+
+import PyNvVideoCodec as nvc
+
+from utils.Utils import get_frame_data, GetChromaFormat, GetVideoCodec
+from utils.transcode_parser import parse_advanced_transcode_args
+
+
+def transcode(gpu_id, input_path, output_path, encoder_config,
+              dump_diagnostics=False):
+    """Decode + encode + mux a single video file end-to-end on the GPU.
+
+    Parameters:
+        gpu_id (int): GPU ordinal.
+        input_path (str): Path to the input video file (any container or
+            elementary bitstream FFmpeg can demux).
+        output_path (str): Path to the output video file.  A container
+            extension (.mp4 / .mov / .mkv / ...) triggers muxing of both
+            video and audio.
+        encoder_config (dict): Encoder kwargs (codec, preset, bf, fps, ...)
+            as produced by load_advanced_transcode_config().  This dict is
+            mutated in-place with the GPU/CUDA/source-context handles
+            before being splatted into nvc.CreateEncoder.
+        dump_diagnostics (bool): If True, dump decoded YUV +
+            encoded bitstream to <output_stem>_decoded.yuv /
+            <output_stem>_encoded.<ext> for offline inspection.
+    """
+    print("Using GPU buffer mode for transcoding")
+
+    cuda_ctx = None
+    cuda_stream = None
+    nv_dmx = None
+    nv_dec = None
+    nv_enc = None
+    muxer = None
+    dec_dump_file = None
+    enc_dump_file = None
+
+    try:
+        # CUDA context + stream shared by decoder and encoder.
+        cuda.init()
+        cuda_device = cuda.Device(gpu_id)
+        cuda_ctx = cuda_device.retain_primary_context()
+        cuda_ctx.push()
+        cuda_stream = cuda.Stream()
+        print(f"Created CUDA context and stream for GPU {gpu_id}")
+
+        # Demuxer + input-stream metadata.
+        nv_dmx = nvc.CreateDemuxer(filename=input_path)
+        width = nv_dmx.Width()
+        height = nv_dmx.Height()
+        input_codec = nv_dmx.GetNvCodecId()
+        print(f"Input video: {width}x{height} @ {nv_dmx.FrameRate()} FPS "
+              f"({nv_dmx.GetContainerName()})")
+        print(f"Input codec: {input_codec}")
+
+        # Codec / preset defaults (only used if JSON / CLI didn't set them).
+        encoder_config.setdefault("codec", GetVideoCodec(nv_dmx).lower())
+        encoder_config.setdefault("preset", "P4")
+
+        output_format = GetChromaFormat(nv_dmx)
+
+        nv_dec = nvc.CreateDecoder(
+            gpuid=gpu_id,
+            codec=input_codec,
+            cudacontext=cuda_ctx.handle,
+            cudastream=cuda_stream.handle,
+            usedevicememory=1,
+        )
+
+        # Hand the source AVFormatContext to the encoder.  This single
+        # handle drives three pieces of bit-exactness automatically
+        # (see NvEncoderClInterface.cpp):
+        #   * ExtractSourceFrameRate   -> NVENC frameRateNum/Den (VFR)
+        #   * ExtractSourceColorMeta   -> NVENC SPS VUI color signals
+        #   * HasSourceAVFormatContext -> global_header (container-mode)
+        # Callers without a source context (encode.py + raw YUV, matrix
+        # tests) skip all three paths and keep their existing elementary-
+        # stream defaults.
+        encoder_config["gpu_id"] = gpu_id
+        encoder_config["cudacontext"] = cuda_ctx.handle
+        encoder_config["cudastream"] = cuda_stream.handle
+        encoder_config["source_av_format_context"] = int(
+            nv_dmx.GetAVFormatInputContext()
+        )
+
+        nv_enc = nvc.CreateEncoder(
+            width, height, output_format, False, **encoder_config,
+        )
+
+        print(f"Output codec: {encoder_config['codec']}")
+        print(f"Output format: {output_format}")
+        print(f"B-frames (encoder): {nv_enc.GetNumBFrames()}")
+        print(f"Output timebase: {nv_dmx.GetTimebaseNum()}/"
+              f"{nv_dmx.GetTimebaseDen()} (matches input)")
+
+        # Diagnostic dump files (decoded frames, encoded bitstream).
+        if dump_diagnostics:
+            enc_stem = Path(output_path).stem
+            codec_ext = {"h264": "h264", "hevc": "hevc", "av1": "av1"}.get(
+                encoder_config["codec"].lower(), "bin")
+            dec_dump_path = Path(output_path).parent / f"{enc_stem}_decoded.yuv"
+            enc_dump_path = Path(output_path).parent / f"{enc_stem}_encoded.{codec_ext}"
+            dec_dump_file = open(dec_dump_path, "wb")
+            enc_dump_file = open(enc_dump_path, "wb")
+            print(f"Diagnostic dump: decoded -> {dec_dump_path}, "
+                  f"encoded -> {enc_dump_path}")
+
+        muxer = nvc.FFmpegMuxer(
+            file_path=output_path,
+            media_format=nvc.GetMediaFormat(output_path),
+            in_format_context=nv_dmx.GetAVFormatInputContext(),
+            codec=encoder_config["codec"].lower(),
+            width=width,
+            height=height,
+            extradata=nv_enc.GetSequenceParams(),
+        )
+
+        # All A/V interleave bookkeeping, B-frame DTS slack, and VFR PTS
+        # correction live inside FFmpegMuxer (see RecordSourceVideoPacket /
+        # MuxVideoPacket / MuxPassthroughPacket / Finalize).  This loop is
+        # the canonical "decode -> encode -> mux" reference and stays short
+        # enough that a user can copy it into their own app.
+        input_frame_idx = 0
+        while True:
+            pkt = nv_dmx.DemuxNoSkipAudio()
+
+            if pkt.is_video or pkt.bsl == 0:
+                muxer.RecordSourceVideoPacket(pkt)
+
+                for decoded_frame in nv_dec.Decode(pkt):
+                    pic_params = nvc.NV_ENC_PIC_PARAMS()
+                    pic_params.inputTimeStamp = input_frame_idx
+                    input_frame_idx += 1
+
+                    if dump_diagnostics:
+                        frame_data = get_frame_data(decoded_frame, use_device_memory=1)
+                        dec_dump_file.write(bytearray(frame_data))
+
+                    for enc_pkt in nv_enc.Encode(decoded_frame, pic_params):
+                        if dump_diagnostics:
+                            enc_dump_file.write(bytes(enc_pkt['data']))
+                        muxer.MuxVideoPacket(
+                            bytes(enc_pkt['data']),
+                            enc_pkt['picture_type'],
+                            enc_pkt['timestamp'],
+                        )
+
+                if pkt.bsl == 0:
+                    break
+            else:
+                muxer.MuxPassthroughPacket(pkt)
+
+        for enc_pkt in nv_enc.EndEncode():
+            if dump_diagnostics:
+                enc_dump_file.write(bytes(enc_pkt['data']))
+            muxer.MuxVideoPacket(
+                bytes(enc_pkt['data']),
+                enc_pkt['picture_type'],
+                enc_pkt['timestamp'],
+            )
+
+        muxer.Finalize()
+
+        print(f"Output file: {output_path}")
+
+    except nvc.PyNvVCExceptionUnsupported as e:
+        print(f"Unsupported operation: {e}")
+        raise
+    except cuda.Error as e:
+        print(f"CUDA error (context/stream): {e}")
+        raise
+    except Exception as e:
+        print(f"Error during transcoding: {e}")
+        raise
+    finally:
+        # Close diagnostic dump files
+        if dec_dump_file is not None:
+            dec_dump_file.close()
+        if enc_dump_file is not None:
+            enc_dump_file.close()
+        # Cleanup resources in reverse order of creation
+        if muxer is not None:
+            del muxer
+        if nv_enc is not None:
+            del nv_enc
+        if nv_dec is not None:
+            del nv_dec
+        if nv_dmx is not None:
+            del nv_dmx
+        if cuda_stream is not None:
+            cuda_stream.synchronize()
+            del cuda_stream
+        if cuda_ctx is not None:
+            cuda_ctx.pop()
+            del cuda_ctx
+
+
+if __name__ == "__main__":
+    args = parse_advanced_transcode_args(
+        "Transcode video files using GPU zero-copy pipeline -- convert "
+        "from one codec/format to another."
+    )
+
+    print("=" * 60)
+    print("TRANSCODER CONFIGURATION")
+    print("=" * 60)
+    print(f"Input file:       {args.input}")
+    print(f"Output file:      {args.output}")
+    print(f"Codec:            {args.codec if args.codec else 'from input'}")
+    print(f"GPU ID:           {args.gpu_id}")
+    print(f"FPS override:     {args.fps if args.fps else 'auto (from input)'}")
+    print(f"Dump diagnostics: {args.dump}")
+    print(f"B-frames (CLI):   "
+          f"{args.bframes if args.bframes is not None else 'config default'}")
+    print("Resolution / format: from input")
+    print("=" * 60)
+
+    transcode(
+        args.gpu_id,
+        args.input.as_posix(),
+        args.output.as_posix(),
+        args.config,
+        dump_diagnostics=args.dump,
+    )
+
+    print("=" * 60)
+    print("TRANSCODE COMPLETE")
+    print("=" * 60)