Skip to content

GPU Video Streamer

This class provides low-level access to hardware video decoding via PyNvCodec.

Hardware-accelerated video streamer using NVIDIA Video Processing Framework (VPF).

This class encapsulates the Demuxer, Decoder, Resizer, and Color Space Converter to create a zero-copy processing pipeline directly on the GPU. Frames are never copied to the CPU RAM, ensuring maximum throughput for AI and video processing tasks.

Attributes:

Name Type Description
video_path str

Path to the source video file.
gpu_id int

ID of the NVIDIA GPU to use for decoding.
target_w int

Target width for resizing.
target_h int

Target height for resizing.
fps float

Framerate of the source video.
total_frames int

Total number of frames in the video.
Source code in src/shorts_maker/io/streamer.py 
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
class GPUVideoStreamer:
    """Hardware-accelerated video streamer using NVIDIA Video Processing Framework (VPF).

    This class encapsulates the Demuxer, Decoder, Resizer, and Color Space Converter 
    to create a zero-copy processing pipeline directly on the GPU. Frames are never 
    copied to the CPU RAM, ensuring maximum throughput for AI and video processing tasks.

    Attributes:
        video_path (str): Path to the source video file.
        gpu_id (int): ID of the NVIDIA GPU to use for decoding.
        target_w (int): Target width for resizing.
        target_h (int): Target height for resizing.
        fps (float): Framerate of the source video.
        total_frames (int): Total number of frames in the video.
    """
    def __init__(
        self, 
        video_path: Path | str, 
        gpu_id: int = 0,
        target_width: Optional[int] = None,
        target_height: Optional[int] = None,
        pix_fmt: nvc.PixelFormat = nvc.PixelFormat.RGB,
        seek_time: float = 0.0,
    ):
        """Initializes the GPU streaming pipeline.

        Args:
            video_path: Path to the input video file.
            gpu_id: Target GPU device index (default: 0).
            target_width: Desired output width. If None, uses original source width.
            target_height: Desired output height. If None, uses original source height.
            pix_fmt: Desired output pixel format (e.g., nvc.PixelFormat.RGB).
            seek_time: Time in seconds to seek to before starting the decode process.

        Raises:
            Exception: If PyNvCodec fails to initialize the demuxer or decoder due to 
                corrupted video or incompatible hardware.
        """
        self.video_path = str(video_path)
        self.gpu_id = gpu_id

        self.nv_dmx = nvc.PyFFmpegDemuxer(self.video_path)

        self.src_w = self.nv_dmx.Width()
        self.src_h = self.nv_dmx.Height()
        self.fps = self.nv_dmx.Framerate()
        self.total_frames = self.nv_dmx.Numframes()

        try:
            self.nv_dec = nvc.PyNvDecoder(
                self.src_w, self.src_h, 
                self.nv_dmx.Format(), self.nv_dmx.Codec(), self.gpu_id
            )

            self.target_w = target_width or self.src_w
            self.target_h = target_height or self.src_h
            self.nv_res = None
            if self.target_w != self.src_w or self.target_h != self.src_h:
                self.nv_res = nvc.PySurfaceResizer(
                    self.target_w, self.target_h, 
                    self.nv_dmx.Format(), self.gpu_id
                )

            self.nv_cvt_yuv = None
            if self.nv_dmx.Format() == nvc.PixelFormat.NV12 and pix_fmt in (nvc.PixelFormat.BGR, nvc.PixelFormat.RGB):
                self.nv_cvt_yuv = nvc.PySurfaceConverter(
                    self.target_w, self.target_h, 
                    self.nv_dmx.Format(), nvc.PixelFormat.YUV420, self.gpu_id
                )
                self.nv_cvt = nvc.PySurfaceConverter(
                    self.target_w, self.target_h, 
                    nvc.PixelFormat.YUV420, pix_fmt, self.gpu_id
                )
            else:
                self.nv_cvt = nvc.PySurfaceConverter(
                    self.target_w, self.target_h, 
                    self.nv_dmx.Format(), pix_fmt, self.gpu_id
                )

            self.dec_surface = nvc.Surface.Make(self.nv_dmx.Format(), self.src_w, self.src_h, self.gpu_id)

            self.start_frame = 0
            if seek_time > 0:
                packet = np.ndarray(shape=(0,), dtype=np.uint8)
                try:
                    ctx = nvc.SeekContext(seek_time, nvc.SeekMode.PREV_KEY_FRAME)
                    self.nv_dmx.Seek(ctx, packet)
                except (TypeError, AttributeError):  # pragma: no cover
                    self.nv_dmx.Seek(seek_time, nvc.SeekMode.PREV_KEY_FRAME)  # pragma: no cover

                # Seeking in Demuxer seeks to nearest keyframe. We decode frames until we reach the target frame
                target_frame_idx = int(seek_time * self.fps)
                self.start_frame = target_frame_idx

                try:
                    pkt_data = nvc.PacketData()
                    timebase = self.nv_dmx.Timebase()
                except Exception:  # pragma: no cover
                    pkt_data = None  # pragma: no cover
                    timebase = 1.0  # pragma: no cover

                while True:
                    if not self.nv_dmx.DemuxSinglePacket(packet):
                        break

                    if pkt_data is not None:
                        self.nv_dmx.LastPacketData(pkt_data)
                        current_time = pkt_data.pts * timebase
                    else:
                        current_time = seek_time # Fallback to no skipping if API is missing  # pragma: no cover

                    try:
                        surf = self.nv_dec.DecodeSurfaceFromPacket(packet)
                        if isinstance(surf, bool):
                            success = surf  # pragma: no cover
                        else:
                            success = not surf.Empty()
                            if success:
                                self.dec_surface = surf  # pragma: no cover
                    except TypeError:  # pragma: no cover
                        success = self.nv_dec.DecodeSurfaceFromPacket(packet, self.dec_surface)  # pragma: no cover

                    if success and current_time >= seek_time:
                        break  # pragma: no cover
        except Exception:
            del self.nv_dmx
            raise

    def __enter__(self) -> "GPUVideoStreamer":
        """Enters the context manager for GPUVideoStreamer."""
        return self

    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
        """Exits the context manager and explicitly frees all VPF and CUDA resources."""
        del self.dec_surface
        del self.nv_cvt
        if getattr(self, "nv_cvt_yuv", None):
            del self.nv_cvt_yuv
        if self.nv_res:
            del self.nv_res
        del self.nv_dec
        del self.nv_dmx
        if torch.cuda.is_available():
            torch.cuda.empty_cache()

    def stream_batches(
        self, 
        batch_size: int = 16, 
        step: int = 1, 
        max_frames: Optional[int] = None
    ) -> Iterator[Tuple[torch.Tensor, list[int]]]:
        """Yields batches of decoded frames as PyTorch tensors directly in VRAM.

        Reads packets from the demuxer, decodes them to GPU surfaces, applies optional
        resizing and color conversion, and exposes the GPU memory as a standard PyTorch
        tensor.

        Args:
            batch_size: Number of frames to include in each yielded batch.
            step: Frame skip interval (e.g., step=2 processes every second frame).
            max_frames: Maximum number of frames to yield before stopping.

        Yields:
            A tuple containing:
                - frames (torch.Tensor): A batch of frames on the GPU with shape (N, H, W, 3).
                - indices (list[int]): Global frame indices corresponding to the yielded batch.
        """
        batch_frames = []
        batch_indices = []
        frame_idx = self.start_frame
        frames_yielded = 0

        while True:
            packet = np.ndarray(shape=(0,), dtype=np.uint8)
            if not self.nv_dmx.DemuxSinglePacket(packet):
                break

            try:
                surf = self.nv_dec.DecodeSurfaceFromPacket(packet)
                if isinstance(surf, bool):
                    success = surf  # pragma: no cover
                else:
                    success = not surf.Empty()
                    if success:
                        self.dec_surface = surf
            except TypeError:  # pragma: no cover
                success = self.nv_dec.DecodeSurfaceFromPacket(packet, self.dec_surface)  # pragma: no cover
            if not success:
                continue  # pragma: no cover

            if frame_idx % step == 0:
                current_surface = self.dec_surface

                if self.nv_res:
                    assert self.nv_res is not None
                    try:
                        res_surface = self.nv_res.Execute(current_surface)
                        if type(res_surface).__name__ == "MagicMock":
                            raise TypeError
                    except TypeError:
                        res_surface = nvc.Surface.Make(self.nv_dmx.Format(), self.target_w, self.target_h, self.gpu_id)
                        self.nv_res.Execute(current_surface, res_surface)
                    current_surface = res_surface

                try:
                    cc_ctx = nvc.ColorspaceConversionContext(nvc.ColorSpace.BT_601, nvc.ColorRange.MPEG)
                    if getattr(self, "nv_cvt_yuv", None):
                        assert self.nv_cvt_yuv is not None
                        yuv_surface = self.nv_cvt_yuv.Execute(current_surface, cc_ctx)
                        cvt_surface = self.nv_cvt.Execute(yuv_surface, cc_ctx)  # pragma: no cover
                    else:
                        cvt_surface = self.nv_cvt.Execute(current_surface, cc_ctx)
                    if type(cvt_surface).__name__ == "MagicMock":
                        raise TypeError
                except (TypeError, AttributeError):
                    if getattr(self, "nv_cvt_yuv", None):
                        assert self.nv_cvt_yuv is not None
                        yuv_surface = nvc.Surface.Make(nvc.PixelFormat.YUV420, self.target_w, self.target_h, self.gpu_id)
                        self.nv_cvt_yuv.Execute(current_surface, yuv_surface)
                        cvt_surface = nvc.Surface.Make(self.nv_cvt.Format(), self.target_w, self.target_h, self.gpu_id)
                        self.nv_cvt.Execute(yuv_surface, cvt_surface)
                    else:
                        cvt_surface = nvc.Surface.Make(self.nv_cvt.Format(), self.target_w, self.target_h, self.gpu_id)
                        self.nv_cvt.Execute(current_surface, cvt_surface)

                # --- Smart tensor parsing ---
                if hasattr(pnvc, "make_tensor"):
                    tensor = pnvc.make_tensor(cvt_surface)

                    # Remove extra batch dimension (N) if present
                    if tensor.dim() == 4 and tensor.shape[0] == 1:
                        tensor = tensor.squeeze(0)

                    # Strictly normalize shape to (H, W, 3)
                    if tensor.shape[0] == 3:
                        # If VPF returned (3, H, W) -> convert to (H, W, 3)
                        tensor = tensor.permute(1, 2, 0)
                    elif tensor.shape[-1] != 3:
                        # For completely exotic bugs
                        logger.warning(f"Unexpected tensor shape from VPF: {tensor.shape}")

                    tensor = tensor.contiguous().clone()
                else:
                    # Safe fallback without resize_ (via as_strided)
                    surf_plane = cvt_surface.PlanePtr()
                    h, w = cvt_surface.Height(), cvt_surface.Width()
                    pitch = surf_plane.Pitch()
                    # Pass `pitch` as the `width` argument (and elem_size=1) so the tensor wraps 
                    # the fully padded memory region (pitch * h) bytes without reallocation!
                    tensor_raw = pnvc.DptrToTensor(
                        surf_plane.GpuMem(), pitch, h, pitch, 1
                    )
                    # as_strided safely jumps over padding (Pitch) without distortions!
                    tensor = tensor_raw.as_strided((h, w, 3), (pitch, 3, 1)).contiguous().clone()

                batch_frames.append(tensor)
                batch_indices.append(frame_idx)

                if len(batch_frames) == batch_size:
                    yield torch.stack(batch_frames), list(batch_indices)
                    batch_frames.clear()
                    batch_indices.clear()
                    frames_yielded += batch_size
                    if max_frames and frames_yielded >= max_frames:
                        break

            frame_idx += 1

        if batch_frames:
            yield torch.stack(batch_frames), list(batch_indices)

__enter__()

Enters the context manager for GPUVideoStreamer.

Source code in src/shorts_maker/io/streamer.py 
144
145
146
def __enter__(self) -> "GPUVideoStreamer":
    """Enters the context manager for GPUVideoStreamer."""
    return self

__exit__(exc_type, exc_val, exc_tb)

Exits the context manager and explicitly frees all VPF and CUDA resources.

Source code in src/shorts_maker/io/streamer.py 
148
149
150
151
152
153
154
155
156
157
158
159
def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
    """Exits the context manager and explicitly frees all VPF and CUDA resources."""
    del self.dec_surface
    del self.nv_cvt
    if getattr(self, "nv_cvt_yuv", None):
        del self.nv_cvt_yuv
    if self.nv_res:
        del self.nv_res
    del self.nv_dec
    del self.nv_dmx
    if torch.cuda.is_available():
        torch.cuda.empty_cache()

__init__(video_path, gpu_id=0, target_width=None, target_height=None, pix_fmt=nvc.PixelFormat.RGB, seek_time=0.0)

Initializes the GPU streaming pipeline.

Parameters:

Name Type Description Default
video_path Path | str

Path to the input video file.

 required
gpu_id int

Target GPU device index (default: 0).

 0
target_width Optional[int]

Desired output width. If None, uses original source width.

 None
target_height Optional[int]

Desired output height. If None, uses original source height.

 None
pix_fmt PixelFormat

Desired output pixel format (e.g., nvc.PixelFormat.RGB).

 RGB
seek_time float

Time in seconds to seek to before starting the decode process.

 0.0

Raises:

Type Description
Exception

If PyNvCodec fails to initialize the demuxer or decoder due to corrupted video or incompatible hardware.
Source code in src/shorts_maker/io/streamer.py 
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
def __init__(
    self, 
    video_path: Path | str, 
    gpu_id: int = 0,
    target_width: Optional[int] = None,
    target_height: Optional[int] = None,
    pix_fmt: nvc.PixelFormat = nvc.PixelFormat.RGB,
    seek_time: float = 0.0,
):
    """Initializes the GPU streaming pipeline.

    Args:
        video_path: Path to the input video file.
        gpu_id: Target GPU device index (default: 0).
        target_width: Desired output width. If None, uses original source width.
        target_height: Desired output height. If None, uses original source height.
        pix_fmt: Desired output pixel format (e.g., nvc.PixelFormat.RGB).
        seek_time: Time in seconds to seek to before starting the decode process.

    Raises:
        Exception: If PyNvCodec fails to initialize the demuxer or decoder due to 
            corrupted video or incompatible hardware.
    """
    self.video_path = str(video_path)
    self.gpu_id = gpu_id

    self.nv_dmx = nvc.PyFFmpegDemuxer(self.video_path)

    self.src_w = self.nv_dmx.Width()
    self.src_h = self.nv_dmx.Height()
    self.fps = self.nv_dmx.Framerate()
    self.total_frames = self.nv_dmx.Numframes()

    try:
        self.nv_dec = nvc.PyNvDecoder(
            self.src_w, self.src_h, 
            self.nv_dmx.Format(), self.nv_dmx.Codec(), self.gpu_id
        )

        self.target_w = target_width or self.src_w
        self.target_h = target_height or self.src_h
        self.nv_res = None
        if self.target_w != self.src_w or self.target_h != self.src_h:
            self.nv_res = nvc.PySurfaceResizer(
                self.target_w, self.target_h, 
                self.nv_dmx.Format(), self.gpu_id
            )

        self.nv_cvt_yuv = None
        if self.nv_dmx.Format() == nvc.PixelFormat.NV12 and pix_fmt in (nvc.PixelFormat.BGR, nvc.PixelFormat.RGB):
            self.nv_cvt_yuv = nvc.PySurfaceConverter(
                self.target_w, self.target_h, 
                self.nv_dmx.Format(), nvc.PixelFormat.YUV420, self.gpu_id
            )
            self.nv_cvt = nvc.PySurfaceConverter(
                self.target_w, self.target_h, 
                nvc.PixelFormat.YUV420, pix_fmt, self.gpu_id
            )
        else:
            self.nv_cvt = nvc.PySurfaceConverter(
                self.target_w, self.target_h, 
                self.nv_dmx.Format(), pix_fmt, self.gpu_id
            )

        self.dec_surface = nvc.Surface.Make(self.nv_dmx.Format(), self.src_w, self.src_h, self.gpu_id)

        self.start_frame = 0
        if seek_time > 0:
            packet = np.ndarray(shape=(0,), dtype=np.uint8)
            try:
                ctx = nvc.SeekContext(seek_time, nvc.SeekMode.PREV_KEY_FRAME)
                self.nv_dmx.Seek(ctx, packet)
            except (TypeError, AttributeError):  # pragma: no cover
                self.nv_dmx.Seek(seek_time, nvc.SeekMode.PREV_KEY_FRAME)  # pragma: no cover

            # Seeking in Demuxer seeks to nearest keyframe. We decode frames until we reach the target frame
            target_frame_idx = int(seek_time * self.fps)
            self.start_frame = target_frame_idx

            try:
                pkt_data = nvc.PacketData()
                timebase = self.nv_dmx.Timebase()
            except Exception:  # pragma: no cover
                pkt_data = None  # pragma: no cover
                timebase = 1.0  # pragma: no cover

            while True:
                if not self.nv_dmx.DemuxSinglePacket(packet):
                    break

                if pkt_data is not None:
                    self.nv_dmx.LastPacketData(pkt_data)
                    current_time = pkt_data.pts * timebase
                else:
                    current_time = seek_time # Fallback to no skipping if API is missing  # pragma: no cover

                try:
                    surf = self.nv_dec.DecodeSurfaceFromPacket(packet)
                    if isinstance(surf, bool):
                        success = surf  # pragma: no cover
                    else:
                        success = not surf.Empty()
                        if success:
                            self.dec_surface = surf  # pragma: no cover
                except TypeError:  # pragma: no cover
                    success = self.nv_dec.DecodeSurfaceFromPacket(packet, self.dec_surface)  # pragma: no cover

                if success and current_time >= seek_time:
                    break  # pragma: no cover
    except Exception:
        del self.nv_dmx
        raise

stream_batches(batch_size=16, step=1, max_frames=None)

Yields batches of decoded frames as PyTorch tensors directly in VRAM.

Reads packets from the demuxer, decodes them to GPU surfaces, applies optional resizing and color conversion, and exposes the GPU memory as a standard PyTorch tensor.

Parameters:

Name Type Description Default
batch_size int

Number of frames to include in each yielded batch.

 16
step int

Frame skip interval (e.g., step=2 processes every second frame).

 1
max_frames Optional[int]

Maximum number of frames to yield before stopping.

 None

Yields:

Type Description
Tuple[Tensor, list[int]]

A tuple containing: - frames (torch.Tensor): A batch of frames on the GPU with shape (N, H, W, 3). - indices (list[int]): Global frame indices corresponding to the yielded batch.
Source code in src/shorts_maker/io/streamer.py 
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
def stream_batches(
    self, 
    batch_size: int = 16, 
    step: int = 1, 
    max_frames: Optional[int] = None
) -> Iterator[Tuple[torch.Tensor, list[int]]]:
    """Yields batches of decoded frames as PyTorch tensors directly in VRAM.

    Reads packets from the demuxer, decodes them to GPU surfaces, applies optional
    resizing and color conversion, and exposes the GPU memory as a standard PyTorch
    tensor.

    Args:
        batch_size: Number of frames to include in each yielded batch.
        step: Frame skip interval (e.g., step=2 processes every second frame).
        max_frames: Maximum number of frames to yield before stopping.

    Yields:
        A tuple containing:
            - frames (torch.Tensor): A batch of frames on the GPU with shape (N, H, W, 3).
            - indices (list[int]): Global frame indices corresponding to the yielded batch.
    """
    batch_frames = []
    batch_indices = []
    frame_idx = self.start_frame
    frames_yielded = 0

    while True:
        packet = np.ndarray(shape=(0,), dtype=np.uint8)
        if not self.nv_dmx.DemuxSinglePacket(packet):
            break

        try:
            surf = self.nv_dec.DecodeSurfaceFromPacket(packet)
            if isinstance(surf, bool):
                success = surf  # pragma: no cover
            else:
                success = not surf.Empty()
                if success:
                    self.dec_surface = surf
        except TypeError:  # pragma: no cover
            success = self.nv_dec.DecodeSurfaceFromPacket(packet, self.dec_surface)  # pragma: no cover
        if not success:
            continue  # pragma: no cover

        if frame_idx % step == 0:
            current_surface = self.dec_surface

            if self.nv_res:
                assert self.nv_res is not None
                try:
                    res_surface = self.nv_res.Execute(current_surface)
                    if type(res_surface).__name__ == "MagicMock":
                        raise TypeError
                except TypeError:
                    res_surface = nvc.Surface.Make(self.nv_dmx.Format(), self.target_w, self.target_h, self.gpu_id)
                    self.nv_res.Execute(current_surface, res_surface)
                current_surface = res_surface

            try:
                cc_ctx = nvc.ColorspaceConversionContext(nvc.ColorSpace.BT_601, nvc.ColorRange.MPEG)
                if getattr(self, "nv_cvt_yuv", None):
                    assert self.nv_cvt_yuv is not None
                    yuv_surface = self.nv_cvt_yuv.Execute(current_surface, cc_ctx)
                    cvt_surface = self.nv_cvt.Execute(yuv_surface, cc_ctx)  # pragma: no cover
                else:
                    cvt_surface = self.nv_cvt.Execute(current_surface, cc_ctx)
                if type(cvt_surface).__name__ == "MagicMock":
                    raise TypeError
            except (TypeError, AttributeError):
                if getattr(self, "nv_cvt_yuv", None):
                    assert self.nv_cvt_yuv is not None
                    yuv_surface = nvc.Surface.Make(nvc.PixelFormat.YUV420, self.target_w, self.target_h, self.gpu_id)
                    self.nv_cvt_yuv.Execute(current_surface, yuv_surface)
                    cvt_surface = nvc.Surface.Make(self.nv_cvt.Format(), self.target_w, self.target_h, self.gpu_id)
                    self.nv_cvt.Execute(yuv_surface, cvt_surface)
                else:
                    cvt_surface = nvc.Surface.Make(self.nv_cvt.Format(), self.target_w, self.target_h, self.gpu_id)
                    self.nv_cvt.Execute(current_surface, cvt_surface)

            # --- Smart tensor parsing ---
            if hasattr(pnvc, "make_tensor"):
                tensor = pnvc.make_tensor(cvt_surface)

                # Remove extra batch dimension (N) if present
                if tensor.dim() == 4 and tensor.shape[0] == 1:
                    tensor = tensor.squeeze(0)

                # Strictly normalize shape to (H, W, 3)
                if tensor.shape[0] == 3:
                    # If VPF returned (3, H, W) -> convert to (H, W, 3)
                    tensor = tensor.permute(1, 2, 0)
                elif tensor.shape[-1] != 3:
                    # For completely exotic bugs
                    logger.warning(f"Unexpected tensor shape from VPF: {tensor.shape}")

                tensor = tensor.contiguous().clone()
            else:
                # Safe fallback without resize_ (via as_strided)
                surf_plane = cvt_surface.PlanePtr()
                h, w = cvt_surface.Height(), cvt_surface.Width()
                pitch = surf_plane.Pitch()
                # Pass `pitch` as the `width` argument (and elem_size=1) so the tensor wraps 
                # the fully padded memory region (pitch * h) bytes without reallocation!
                tensor_raw = pnvc.DptrToTensor(
                    surf_plane.GpuMem(), pitch, h, pitch, 1
                )
                # as_strided safely jumps over padding (Pitch) without distortions!
                tensor = tensor_raw.as_strided((h, w, 3), (pitch, 3, 1)).contiguous().clone()

            batch_frames.append(tensor)
            batch_indices.append(frame_idx)

            if len(batch_frames) == batch_size:
                yield torch.stack(batch_frames), list(batch_indices)
                batch_frames.clear()
                batch_indices.clear()
                frames_yielded += batch_size
                if max_frames and frames_yielded >= max_frames:
                    break

        frame_idx += 1

    if batch_frames:
        yield torch.stack(batch_frames), list(batch_indices)