..
  # SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
  # SPDX-License-Identifier: Apache-2.0
  #
  # Licensed under the Apache License, Version 2.0 (the "License");
  # you may not use this file except in compliance with the License.
  # You may obtain a copy of the License at
  #
  # http://www.apache.org/licenses/LICENSE-2.0
  #
  # Unless required by applicable law or agreed to in writing, software
  # distributed under the License is distributed on an "AS IS" BASIS,
  # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  # See the License for the specific language governing permissions and
  # limitations under the License.

PyNvVideoCodec
--------------

PyNvVideoCodec provides Python bindings to NVIDIA's hardware-accelerated video codec APIs (NVDEC/NVENC).
It enables efficient video decoding and encoding directly on GPU, perfect for video processing pipelines
with CV-CUDA.

**Key Points:**

* Hardware-accelerated video decoding (H.264, NV12, etc.)
* Decodes directly to GPU memory
* Batch frame decoding for better throughput
* Hardware-accelerated encoding for output
* Minimal CPU involvement in the entire pipeline

**Required Imports:**

.. literalinclude:: ../../../../samples/interoperability/pynvvideocodec_interop.py
   :language: python
   :start-after: docs_tag: begin_imports
   :end-before: docs_tag: end_imports

**Setup PyNvVideoCodec:**

.. literalinclude:: ../../../../samples/interoperability/pynvvideocodec_interop.py
   :language: python
   :start-after: docs_tag: begin_init_pynvvideocodec
   :end-before: docs_tag: end_init_pynvvideocodec
   :dedent: 4

The decoder is configured to output RGB frames directly to device memory

**Read video frames into CV-CUDA tensors and process:**

.. literalinclude:: ../../../../samples/interoperability/pynvvideocodec_interop.py
   :language: python
   :start-after: docs_tag: begin_read_and_process_video
   :end-before: docs_tag: end_read_and_process_video
   :dedent: 4

Frames are decoded in batches for efficiency. Each frame is converted to a CV-CUDA tensor with HWC
(Height × Width × Channels) layout.

CV-CUDA operations can be applied to each frame. Here we resize from 1920×1080 to 640×480 and convert
from BGR to NV12 (YUV 4:2:0 planar) to match the encoder's expected format.
Alternatively, you could use :py:func:`cvcuda.stack` to stack the frames into a single tensor and
apply operations on the stacked tensor. For clarity, we process each frame individually here.

**Encode processed frames:**

.. literalinclude:: ../../../../samples/interoperability/pynvvideocodec_interop.py
   :language: python
   :start-after: docs_tag: begin_encode_frames
   :end-before: docs_tag: end_encode_frames
   :dedent: 4

The encoder is set up to accept NV12 pixel format frames at the target resolution (640×480).
If a hardware video encoder (NVENC) is not available, the creation of the encoder object will raise an exception and the encoding step is skipped.

The processed frames are encoded back to video. The encoder produces compressed bitstreams that are
written to the output file. Note that ``EndEncode()`` must be called to flush any remaining frames.

**Typical Use Cases:**

* Video analytics preprocessing
* Real-time video transformation
* Video transcoding pipelines
* Video quality enhancement
* Object detection/segmentation on video

**Complete Example:** See ``samples/interoperability/pynvvideocodec_interop.py``