nvidia-codec 0.0.21__tar.gz → 0.0.23__tar.gz

{nvidia_codec-0.0.21/src/nvidia_codec.egg-info → nvidia_codec-0.0.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nvidia-codec
-Version: 0.0.21
+Version: 0.0.23
 Summary: Pythonic interface to Nvidia Codec
 Home-page: https://github.com/riaqn/python-nvidia-codec
 Author: Zesen Qian
@@ -26,7 +26,7 @@ A Pythonic library for NVIDIA Video Codec (NVDEC).
 - Python 3.10+
 - NVIDIA GPU with NVDEC support
 - NVIDIA driver with `libnvcuvid.so`
-- FFmpeg 8.x (for demuxing)
+- FFmpeg 9.x (for demuxing)
 
 ## Installation
 
@@ -57,6 +57,11 @@ for timestamp, frame in player.frames(torch.uint8):
     print(f'{timestamp}: {frame.shape}')
 ```
 
+`frames()` without `start` continues from the demuxer's current position; it
+only begins at the first frame on a freshly opened player. After a
+`screenshot()` or a previous `frames()` pass, pass `start=timedelta(0)` to
+decode from the beginning again.
+
 ### Screenshot (single frame extraction)
 
 ```python
@@ -119,6 +124,23 @@ Codec support depends on your GPU:
 - VPF allocates the bare minimum of resources needed for most decoding tasks. PNC allows the user to specify the amount of resources to be allocated for advanced applications. Users own the resources and decide when and whether to deal with them.
 - Managing resources is not painful: similar to `pycuda`, we shift the burden of managing host/device resources to the Python garbage collector. Resources (such as `Picture` and `Surface`) are automatically freed when the user drops the reference.
 
+## Limitations
+
+- **One consumer per `Decoder`.** A `Decoder`/`Player` instance serves one
+  `frames()`, `screenshots()` or `screenshot()` call at a time. Use separate
+  instances (from any threads) for concurrent decodes of the same or different
+  files.
+- **No mid-stream resolution or codec changes.** The NVDEC decoder is created
+  from the first sequence header; a later sequence with a different coded
+  size, chroma format or bit depth raises `decoder already initialized with
+  different format`. Split such files per segment.
+- **Timestamp-less elementary streams** (e.g. raw Annex-B `.h264`/`.hevc`)
+  carry no pts: `frames()` yields `AV_NOPTS_VALUE` for every frame,
+  `pts2time` returns `None`, and `screenshot()` cannot locate a time. Mux
+  into a container first.
+- **Embedded cover art** (`attached_pic` streams) is skipped by `Player`
+  and reported by `VideoTrack.attached_pic` from `parse()`.
+
 ## Roadmap
 
 - [x] Decoding
@@ -128,7 +150,7 @@ Codec support depends on your GPU:
   - Color Ranges: MPEG (limited), JPEG (full)
   - Color Space: BT.601, BT.709, BT.2020
 - [x] Built-in cropping and scaling via NV decoder
-- [x] Thread-safe and thread-friendly
+- [x] Thread-friendly (one consumer per decoder; decoders are independent)
 - [ ] Encoder
 - [x] PyTorch integration
 

{nvidia_codec-0.0.21 → nvidia_codec-0.0.23}/README.md

@@ -9,7 +9,7 @@ A Pythonic library for NVIDIA Video Codec (NVDEC).
 - Python 3.10+
 - NVIDIA GPU with NVDEC support
 - NVIDIA driver with `libnvcuvid.so`
-- FFmpeg 8.x (for demuxing)
+- FFmpeg 9.x (for demuxing)
 
 ## Installation
 
@@ -40,6 +40,11 @@ for timestamp, frame in player.frames(torch.uint8):
     print(f'{timestamp}: {frame.shape}')
 ```
 
+`frames()` without `start` continues from the demuxer's current position; it
+only begins at the first frame on a freshly opened player. After a
+`screenshot()` or a previous `frames()` pass, pass `start=timedelta(0)` to
+decode from the beginning again.
+
 ### Screenshot (single frame extraction)
 
 ```python
@@ -102,6 +107,23 @@ Codec support depends on your GPU:
 - VPF allocates the bare minimum of resources needed for most decoding tasks. PNC allows the user to specify the amount of resources to be allocated for advanced applications. Users own the resources and decide when and whether to deal with them.
 - Managing resources is not painful: similar to `pycuda`, we shift the burden of managing host/device resources to the Python garbage collector. Resources (such as `Picture` and `Surface`) are automatically freed when the user drops the reference.
 
+## Limitations
+
+- **One consumer per `Decoder`.** A `Decoder`/`Player` instance serves one
+  `frames()`, `screenshots()` or `screenshot()` call at a time. Use separate
+  instances (from any threads) for concurrent decodes of the same or different
+  files.
+- **No mid-stream resolution or codec changes.** The NVDEC decoder is created
+  from the first sequence header; a later sequence with a different coded
+  size, chroma format or bit depth raises `decoder already initialized with
+  different format`. Split such files per segment.
+- **Timestamp-less elementary streams** (e.g. raw Annex-B `.h264`/`.hevc`)
+  carry no pts: `frames()` yields `AV_NOPTS_VALUE` for every frame,
+  `pts2time` returns `None`, and `screenshot()` cannot locate a time. Mux
+  into a container first.
+- **Embedded cover art** (`attached_pic` streams) is skipped by `Player`
+  and reported by `VideoTrack.attached_pic` from `parse()`.
+
 ## Roadmap
 
 - [x] Decoding
@@ -111,7 +133,7 @@ Codec support depends on your GPU:
   - Color Ranges: MPEG (limited), JPEG (full)
   - Color Space: BT.601, BT.709, BT.2020
 - [x] Built-in cropping and scaling via NV decoder
-- [x] Thread-safe and thread-friendly
+- [x] Thread-friendly (one consumer per decoder; decoders are independent)
 - [ ] Encoder
 - [x] PyTorch integration
 

{nvidia_codec-0.0.21 → nvidia_codec-0.0.23}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = nvidia-codec
-version = 0.0.21
+version = 0.0.23
 author = Zesen Qian
 author_email = nvidia-codec@riaqn.org
 description = Pythonic interface to Nvidia Codec

{nvidia_codec-0.0.21 → nvidia_codec-0.0.23}/src/nvidia_codec/__init__.py

@@ -19,7 +19,7 @@ Quick Start:
 Requirements:
     - NVIDIA GPU with NVDEC support
     - NVIDIA driver with libnvcuvid.so
-    - FFmpeg 8.x (for demuxing)
+    - FFmpeg 9.x (for demuxing)
     - PyTorch with CUDA support
 
 Supported Codecs:

{nvidia_codec-0.0.21 → nvidia_codec-0.0.23}/src/nvidia_codec/core/cuda.py

@@ -8,7 +8,7 @@ CUcontext = c_void_p
 CUresult = c_int
 cudaError = c_int
 
-CUdeviceptr = c_uint
+CUdeviceptr = c_ulonglong  # CUdeviceptr_v2: unsigned long long
 
 lib = cdll.LoadLibrary('libcuda.so')
 librt = cdll.LoadLibrary('libcudart.so')

{nvidia_codec-0.0.21 → nvidia_codec-0.0.23}/src/nvidia_codec/core/decode.py

@@ -37,7 +37,7 @@ class Surface:
         self.pts = pts
 
         self.params = CUVIDPROCPARAMS()
-        memmove(byref(self.params), byref(params), sizeof(CUVIDEOFORMAT))
+        memmove(byref(self.params), byref(params), sizeof(CUVIDPROCPARAMS))
 
         self.params.output_stream = stream
 
@@ -117,7 +117,9 @@ class Surface:
             "strides": strides,
             "version": 3,
             "data": (self.c_devptr.value, False),
-            "stream": self.params.output_stream,
+            # CAI v3 forbids stream 0; CUDA's stream 0 is the legacy
+            # default stream, which the protocol spells as 1.
+            "stream": self.params.output_stream or 1,
         }
 
 

{nvidia_codec-0.0.21 → nvidia_codec-0.0.23}/src/nvidia_codec/core/nvcuvid.py

@@ -120,23 +120,6 @@ class CUVIDPARSERPARAMS(Structure):
     ]
 CUstream = c_void_p # according to /opt/cuda/include/cuda.h
 CUvideoparser = c_void_p # according to nvcuvid.h
-class CUVIDPROCPARAMS(Structure):
-    _fields_ = [('progressive_frame', c_int),
-                ('second_field', c_int),
-                ('top_field_first', c_int),
-                ('unpaired_field', c_int),
-                ('reserved_flags', c_uint),
-                ('reserved_zero', c_uint),
-                ('raw_input_dptr', c_ulonglong),
-                ('raw_input_pitch', c_uint),
-                ('raw_input_format', c_uint),
-                ('raw_output_dptr', c_ulonglong),
-                ('raw_output_pitch', c_uint),
-                ('Reserved1', c_uint),
-                ('output_stream', CUstream),
-                ('Reserved', c_uint * 46),
-                ('histogram_dptr', POINTER(c_ulonglong)),
-                ('Reserved2', c_void_p*1) ]
 class CUvideopacketflags(Flag):
     ENDOFSTREAM = 1
     TIMESTAMP = auto()

{nvidia_codec-0.0.21 → nvidia_codec-0.0.23}/src/nvidia_codec/ffmpeg/include/libavformat.py

@@ -19,6 +19,7 @@ class AVIndexEntry(Structure):
         return (self.flags_size >> 2) & 0x3FFFFFFF
 
 AVINDEX_KEYFRAME = 0x0001
+AV_DISPOSITION_ATTACHED_PIC = 0x0400
 
 class AVStream(Structure):
     _fields_ = [

{nvidia_codec-0.0.21 → nvidia_codec-0.0.23}/src/nvidia_codec/ffmpeg/include/libavutil.py

@@ -63,10 +63,12 @@ class AVColorRange(TypedCEnumeration(c_int)):
     # NB = 3
 
 class AVPixelFormat(TypedCEnumeration(c_int)):
-    NONE = -1,
-    RGB24 = 0,
-    YUV420P = 1,
-    YUV444P = 5,
-    YUV420P16LE = 45,
+    # values per libavutil/pixfmt.h (ffmpeg 9); no trailing commas — they
+    # would make the members 1-tuples, not ints
+    NONE = -1
+    YUV420P = 0
+    RGB24 = 2
+    YUV444P = 5
+    YUV420P16LE = 45
     YUV444P16LE = 49
     # other omitted

{nvidia_codec-0.0.21 → nvidia_codec-0.0.23}/src/nvidia_codec/ffmpeg/libavformat.py

@@ -3,7 +3,6 @@
 # not pyav
 
 from ctypes import *
-from fractions import Fraction
 
 from .include.libavutil import *
 from .include.libavcodec import *
@@ -17,14 +16,16 @@ import logging
 
 log = logging.getLogger(__name__)
 
-lib = cdll.LoadLibrary("libavformat.so")
+# Pin the ABI major to ffmpeg 9 (libavformat 63), matching the libavcodec.so.63
+# pin in ffmpeg/libavcodec.py: struct layouts + enum values in include/ track
+# ffmpeg 9, so a system upgrade fails loudly at load instead of mis-reading.
+lib = cdll.LoadLibrary("libavformat.so.63")
 
-# Check FFmpeg version compatibility (requires FFmpeg 8.x / libavformat 62+)
 _version = lib.avformat_version()
 _major = _version >> 16
-if _major < 62:
+if _major != 63:
     raise ImportError(
-        f"nvidia-codec requires FFmpeg 8.x (libavformat 62+), "
+        f"nvidia-codec requires FFmpeg 9.x (libavformat 63), "
         f"but found libavformat {_major}.{(_version >> 8) & 0xff}.{_version & 0xff}"
     )
 
@@ -102,15 +103,6 @@ class FormatContext:
             return result.contents
         return None
 
-    def infer_start_time(self):
-        # log.warning('infering start time from first packet')
-        # in this case, we get the first packet
-        pkt = Packet()
-        self.read_packet(pkt)
-        start_time = pkt.av.pts
-        time_base = pkt.av.time_base
-        return start_time * Fraction(time_base.num, time_base.den)
-
     @property
     def streams(self):
         for i in range(self.av.nb_streams):

{nvidia_codec-0.0.21 → nvidia_codec-0.0.23}/src/nvidia_codec/utils/color.py

@@ -103,7 +103,6 @@ def convert(surface : Surface,
         assert height % 2 == 0
         assert width % 2 == 0
         assert height // 2 * 3 == h
-        assert YUV.dtype == torch.uint8
 
         Y = YUV[:height,:]
         UV = YUV[height:,:]
@@ -134,8 +133,8 @@ def convert(surface : Surface,
     #normalize
     if source_range == AVColorRange.MPEG:
         y = (Y.type(torch.float) - (16 << bit8)) / (220 << bit8)
-        u = (U.type(torch.float) - (128 << bit8)) / (225 << bit8)
-        v = (V.type(torch.float) - (128 << bit8)) / (225 << bit8)
+        u = (U.type(torch.float) - (128 << bit8)) / (224 << bit8)
+        v = (V.type(torch.float) - (128 << bit8)) / (224 << bit8)
     elif source_range == AVColorRange.JPEG:
         y = Y.type(torch.float) / (256 << bit8)
         u = (U.type(torch.float) - (128 << bit8)) / (256 << bit8)

{nvidia_codec-0.0.21 → nvidia_codec-0.0.23}/src/nvidia_codec/utils/decode.py

@@ -2,6 +2,7 @@
 
 import collections
 from datetime import timedelta
+from fractions import Fraction
 import numpy as np
 from queue import Queue, ShutDown
 import threading
@@ -9,15 +10,14 @@ import weakref
 
 from ..ffmpeg.libavcodec import BSFContext
 from ..ffmpeg.libavformat import FormatContext, AVCodecID
+from ..ffmpeg.include.libavcodec import AV_PKT_FLAG_KEY
 from ..ffmpeg.include.libavutil import (
     AV_NOPTS_VALUE,
     AVColorRange,
     AVColorSpace,
-    AVDISCARD_NONE,
-    AVDISCARD_NONKEY,
 )
 from .compat import av2cuda, extract_stream_ptr
-from ..core.decode import BaseDecoder, Picture, Surface
+from ..core.decode import BaseDecoder, Picture, Surface, decide_surface_format
 from ..ffmpeg.common import AVException
 from .color import convert, to_yuv420p
 from .demux import VideoTrack
@@ -33,11 +33,21 @@ log = logging.getLogger(__name__)
 
 
 class OwnedSurface:
-    """Wraps a Surface with semaphore ownership. Releases on free."""
+    """Maps a Picture under the decoder's output-surface semaphore.
 
-    def __init__(self, surface):
-        surface.decoder._surface_sem.acquire()
-        self._surface = surface
+    The semaphore (sized to ulNumOutputSurfaces) must be held BEFORE
+    cuvidMapVideoFrame64 runs — two concurrent maps with one output
+    surface would overwrite each other — so the map happens here, not
+    in the caller. free() unmaps and releases.
+    """
+
+    def __init__(self, decoder, pic, stream):
+        decoder._surface_sem.acquire()
+        try:
+            self._surface = decoder.map(pic, stream)
+        except BaseException:
+            decoder._surface_sem.release()
+            raise
 
     def __getattr__(self, name):
         return getattr(self._surface, name)
@@ -83,7 +93,7 @@ class OwnedPicture:
 
     def map(self, stream=0):
         assert self._pic is not None, "Picture already freed"
-        return OwnedSurface(self._decoder.map(self._pic, stream))
+        return OwnedSurface(self._decoder, self._pic, stream)
 
 
 class Decoder(BaseDecoder):
@@ -100,7 +110,10 @@ class Decoder(BaseDecoder):
         num_pictures: Callable(min_pics) -> int, returns the total number of
             picture slots (must be >= min_pics and <= 32). Higher values allow
             better pipelining between decode and consumer threads.
-            Default: lambda min_pics: min_pics * 2 (double the minimum).
+            Default: lambda min_pics: min_pics + 4.
+        allow_high: Keep >8-bit sources at 16 bits (P016 / YUV444_16Bit
+            surfaces) instead of letting NVDEC round them to 8-bit NV12 /
+            YUV444. convert() handles both; to_yuv420p() is 8-bit only.
     """
 
     def __init__(
@@ -111,6 +124,7 @@ class Decoder(BaseDecoder):
         cropping=None,
         target_rect=None,
         device=None,
+        allow_high=False,
     ):
         self.track = track
         self._slot_locks = None  # initialized in decide(), after we know num_pictures
@@ -147,6 +161,10 @@ class Decoder(BaseDecoder):
                 "num_pictures": num_pics,
                 "num_surfaces": 1,
             }
+            if allow_high:
+                d["surface_format"] = decide_surface_format(
+                    p["chroma_format"], p["bit_depth"],
+                    p["supported_surface_formats"], allow_high=True)
             if target_size is not None:
                 d["target_size"] = target_size
             if cropping is not None:
@@ -164,6 +182,11 @@ class Decoder(BaseDecoder):
             coded_height=track.height,
         )
 
+    @property
+    def duration(self):
+        """Track duration as a timedelta, or None if the container doesn't say."""
+        return self.track.duration
+
     def pre_decode(self, idx):
         """NVDEC reclaims slot idx. Clear tracking, wait for consumer if held."""
         self._slots.pop(idx, None)
@@ -231,8 +254,7 @@ class Decoder(BaseDecoder):
         packet/frame traversal. Only if avformat cannot seek the container at all do we
         fall back to the in-memory-index path (then BOF)."""
         try:
-            self.track.fc.seek_file(self.track.stream, target_pts,
-                                    min_ts=-(2**63), max_ts=target_pts)
+            self._native_seek_to_keyframe(target_pts)
         except AVException:
             kts = self._keyframe_before(target_pts)
             if kts is None:
@@ -242,24 +264,39 @@ class Decoder(BaseDecoder):
         self.with_callbacks(lambda: self.send(None), post_decode=lambda pic: None)
         self._recent.clear()
 
-    def _decode_packets(self, keyframes_only=False):
-        """Read packets from current position, filter, decode.
-
-        Calls self.post_decode(pic) for each frame.
+    def _native_seek_to_keyframe(self, target_pts, max_tries=16):
+        """avformat_seek_file(max_ts=target) positions on the last packet with
+        dts <= target. Indexed containers (MP4 / MKV) snap that to a keyframe.
+        Index-less ones (MPEG-TS / M2TS) use the generic dts bisection — which
+        is NOT keyframe-aware ("FIXME keyframe?" in mpegts.c) — and land
+        mid-GOP; NVDEC then discards everything up to the NEXT IDR, so the
+        frame we hand back is up to a GOP late. (ffmpeg's CLI papers over this
+        with a fixed 3/23 s dts heuristic.)
+
+        Peek at the landing packet; if it isn't a keyframe, back off by a
+        growing number of frame-durations and retry. Landing on an earlier
+        keyframe than strictly needed only costs decode-forward time, so
+        overshooting backwards is safe. The peek consumes a packet, so the
+        final seek re-runs to restore the position. Raises AVException if the
+        container can't seek at all (caller falls back to the in-memory index).
         """
-        self.track.stream.discard = AVDISCARD_NONKEY if keyframes_only else AVDISCARD_NONE
-        packets = self.track.fc.read_packets(self.track.stream)
-        it = self.bsf.filter(packets, flush=True, reuse=True)
-        self.with_callbacks(lambda: self.send(None), post_decode=lambda pic: None)
-
-        for pkt in it:
-            pts = pkt.av.pts if pkt.av.pts != AV_NOPTS_VALUE else pkt.av.dts
-            arr = np.ctypeslib.as_array(pkt.av.data, (pkt.av.size,))
-            self.send((pts, arr))
-            if keyframes_only:
-                self.bsf.flush()
-                self.send(None)
-        self.send(None)
+        fc, stream = self.track.fc, self.track.stream
+        tb = self.track._time_base
+        afr = stream.avg_frame_rate
+        fps = Fraction(afr.num, afr.den) if afr.num > 0 and afr.den > 0 else Fraction(25)
+        step = max(1, int(1 / (fps * tb)))          # one frame, in pts units
+        ts = target_pts
+        for _ in range(max_tries):
+            fc.seek_file(stream, ts, min_ts=-(2**63), max_ts=ts)
+            first = next(fc.read_packets(stream), None)
+            if first is None or first.av.flags & AV_PKT_FLAG_KEY:
+                break                                # keyframe (or EOF — nothing to fix)
+            landed = first.av.dts if first.av.dts != AV_NOPTS_VALUE else first.av.pts
+            if landed == AV_NOPTS_VALUE:
+                break                                # can't reason about position
+            ts = min(ts, landed) - step
+            step *= 2
+        fc.seek_file(stream, ts, min_ts=-(2**63), max_ts=ts)
 
     def _map_and_convert(self, pic, dtype, pixel_format='rgb'):
         """Map a Picture (or OwnedPicture) to a tensor. Frees pic and surface.
@@ -268,16 +305,16 @@ class Decoder(BaseDecoder):
         pixel_format='rgb' (default) → (3,H,W) RGB via convert() (color matrix).
         pixel_format='yuv420p' → 1D planar I420 uint8 via to_yuv420p() (no color
         math, half the bytes) — for piping straight to an encoder."""
+        t = None
         try:
             t = self.track.pts2time(pic.pts)
             stream = extract_stream_ptr(torch.cuda.current_stream(self.device))
-            # OwnedPicture carries its own slot+surface ownership (→
-            # OwnedSurface); a bare Picture maps via the decoder (→ plain
-            # Surface). Both expose .free().
+            # Both OwnedPicture (owns its slot) and bare Picture map under
+            # the output-surface semaphore; .free() on either is safe.
             if isinstance(pic, OwnedPicture):
                 surface = pic.map(stream)
             else:
-                surface = self.map(pic, stream)
+                surface = OwnedSurface(self, pic, stream)
         except Exception as e:
             return (t, e)
         finally:
@@ -683,6 +720,13 @@ class Decoder(BaseDecoder):
         """Yield (int_pts, frame_or_exception) for every decoded frame in
         display order. Decodes ALL frames (B-frames included).
 
+        POSITION: without `start` / `start_pts` this does NOT rewind. It
+        decodes from wherever the demuxer currently is — the beginning on
+        a fresh Decoder, but after a `screenshot()`, `screenshots()` or an
+        exhausted `frames()` it resumes from there (and yields nothing if
+        that was EOF). Pass `start=timedelta(0)` to decode from the start
+        of the file regardless of what ran before.
+
         The yielded `int_pts` is the raw track pts (same units as
         `pic.pts`, including the demuxer's `start_time` offset). Pass
         through `track.pts2time(pts)` if you need a `timedelta`. Yielding

{nvidia_codec-0.0.21 → nvidia_codec-0.0.23}/src/nvidia_codec/utils/demux.py

@@ -10,6 +10,7 @@ from fractions import Fraction
 import functools
 
 from ..ffmpeg.libavformat import FormatContext, AVMediaType, AVCodecID
+from ..ffmpeg.include.libavformat import AV_DISPOSITION_ATTACHED_PIC
 from ..ffmpeg.include.libavutil import (
     AV_NOPTS_VALUE,
     AV_TIME_BASE,
@@ -36,6 +37,7 @@ class VideoTrack:
         extradata: Codec extradata bytes, or None.
         color_space: AVColorSpace enum value.
         color_range: AVColorRange enum value.
+        attached_pic: True if this is embedded cover art, not real video.
     """
 
     def __init__(self, fc, stream):
@@ -51,20 +53,33 @@ class VideoTrack:
         # Time base
         self._time_base = Fraction(stream.time_base.num, stream.time_base.den)
 
-        # Start time
+        # Start time. Lazy containers (MPEG-TS, raw elementary streams) leave
+        # both the stream and the format start_time unset until probed;
+        # probing buffers the packets it reads, so nothing is lost. (The old
+        # path read the first packet directly — which both computed 0 via the
+        # packet's unset 0/1 time_base AND swallowed the IDR, dropping the
+        # whole first GOP from decode.)
         self._start_time = stream.start_time
         if self._start_time == AV_NOPTS_VALUE:
-            self._start_time = fc.av.start_time
-            if self._start_time == AV_NOPTS_VALUE:
-                start_time = fc.infer_start_time()
-                self._start_time = int(start_time / self._time_base)
-            else:
+            fc.probe()
+            self._start_time = stream.start_time
+        if self._start_time == AV_NOPTS_VALUE:
+            if fc.av.start_time != AV_NOPTS_VALUE:
                 self._start_time = int(
-                    self._start_time / AV_TIME_BASE / self._time_base
+                    fc.av.start_time / AV_TIME_BASE / self._time_base
                 )
+            else:
+                # Timestamp-less stream (e.g. raw Annex-B .h264): packets carry
+                # no pts at all; frames() yields AV_NOPTS_VALUE and pts2time
+                # returns None. Anchor at 0 so time2pts is at least defined.
+                self._start_time = 0
 
-        # Duration (lazy — probes only if needed)
 
+    @property
+    def attached_pic(self):
+        """True for cover-art / thumbnail "video" streams (AV_DISPOSITION_ATTACHED_PIC):
+        a single still image, not a decodable video track."""
+        return bool(self.stream.disposition & AV_DISPOSITION_ATTACHED_PIC)
 
     @functools.cached_property
     def width(self):

{nvidia_codec-0.0.21 → nvidia_codec-0.0.23}/src/nvidia_codec/utils/player.py

@@ -20,8 +20,12 @@ class Player(Decoder):
         target_rect=None,
         device=None,
         track_idx=None,
+        **decoder_kwargs,
     ):
-        tracks = [t for t in parse(url) if isinstance(t, VideoTrack)]
+        # Cover art (attached_pic) is a "video" stream to ffmpeg but a single
+        # still image; never pick it, and don't count it as ambiguity.
+        tracks = [t for t in parse(url)
+                  if isinstance(t, VideoTrack) and not t.attached_pic]
         if not tracks:
             raise ValueError(f"{url} has no video stream")
         if track_idx is not None:
@@ -38,5 +42,6 @@ class Player(Decoder):
             cropping=cropping,
             target_rect=target_rect,
             device=device,
+            **decoder_kwargs,
         )
         self.url = url

{nvidia_codec-0.0.21 → nvidia_codec-0.0.23/src/nvidia_codec.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nvidia-codec
-Version: 0.0.21
+Version: 0.0.23
 Summary: Pythonic interface to Nvidia Codec
 Home-page: https://github.com/riaqn/python-nvidia-codec
 Author: Zesen Qian
@@ -26,7 +26,7 @@ A Pythonic library for NVIDIA Video Codec (NVDEC).
 - Python 3.10+
 - NVIDIA GPU with NVDEC support
 - NVIDIA driver with `libnvcuvid.so`
-- FFmpeg 8.x (for demuxing)
+- FFmpeg 9.x (for demuxing)
 
 ## Installation
 
@@ -57,6 +57,11 @@ for timestamp, frame in player.frames(torch.uint8):
     print(f'{timestamp}: {frame.shape}')
 ```
 
+`frames()` without `start` continues from the demuxer's current position; it
+only begins at the first frame on a freshly opened player. After a
+`screenshot()` or a previous `frames()` pass, pass `start=timedelta(0)` to
+decode from the beginning again.
+
 ### Screenshot (single frame extraction)
 
 ```python
@@ -119,6 +124,23 @@ Codec support depends on your GPU:
 - VPF allocates the bare minimum of resources needed for most decoding tasks. PNC allows the user to specify the amount of resources to be allocated for advanced applications. Users own the resources and decide when and whether to deal with them.
 - Managing resources is not painful: similar to `pycuda`, we shift the burden of managing host/device resources to the Python garbage collector. Resources (such as `Picture` and `Surface`) are automatically freed when the user drops the reference.
 
+## Limitations
+
+- **One consumer per `Decoder`.** A `Decoder`/`Player` instance serves one
+  `frames()`, `screenshots()` or `screenshot()` call at a time. Use separate
+  instances (from any threads) for concurrent decodes of the same or different
+  files.
+- **No mid-stream resolution or codec changes.** The NVDEC decoder is created
+  from the first sequence header; a later sequence with a different coded
+  size, chroma format or bit depth raises `decoder already initialized with
+  different format`. Split such files per segment.
+- **Timestamp-less elementary streams** (e.g. raw Annex-B `.h264`/`.hevc`)
+  carry no pts: `frames()` yields `AV_NOPTS_VALUE` for every frame,
+  `pts2time` returns `None`, and `screenshot()` cannot locate a time. Mux
+  into a container first.
+- **Embedded cover art** (`attached_pic` streams) is skipped by `Player`
+  and reported by `VideoTrack.attached_pic` from `parse()`.
+
 ## Roadmap
 
 - [x] Decoding
@@ -128,7 +150,7 @@ Codec support depends on your GPU:
   - Color Ranges: MPEG (limited), JPEG (full)
   - Color Space: BT.601, BT.709, BT.2020
 - [x] Built-in cropping and scaling via NV decoder
-- [x] Thread-safe and thread-friendly
+- [x] Thread-friendly (one consumer per decoder; decoders are independent)
 - [ ] Encoder
 - [x] PyTorch integration
 

{nvidia_codec-0.0.21 → nvidia_codec-0.0.23}/src/nvidia_codec.egg-info/SOURCES.txt

@@ -31,4 +31,5 @@ src/nvidia_codec/utils/color.py
 src/nvidia_codec/utils/compat.py
 src/nvidia_codec/utils/decode.py
 src/nvidia_codec/utils/demux.py
-src/nvidia_codec/utils/player.py
+src/nvidia_codec/utils/player.py
+tests/test_smoke.py

nvidia_codec-0.0.23/tests/test_smoke.py

@@ -0,0 +1,188 @@
+"""Smoke test: synthesize a short H.264 clip with ffmpeg, decode it with NVDEC.
+
+Requires an NVIDIA GPU, libnvcuvid, FFmpeg 9 libraries and the `ffmpeg` CLI.
+Run with:  python -m pytest tests/  (or simply: python tests/test_smoke.py)
+"""
+from datetime import timedelta
+import os
+import shutil
+import subprocess
+import tempfile
+
+import pytest
+import torch
+
+from nvidia_codec.core.cuviddec import cudaVideoSurfaceFormat
+from nvidia_codec.utils import Player, parse, VideoTrack
+
+W, H, FPS, SECONDS = 320, 240, 25, 2
+
+pytestmark = pytest.mark.skipif(
+    not (shutil.which("ffmpeg") and torch.cuda.is_available()),
+    reason="needs ffmpeg CLI and a CUDA GPU",
+)
+
+
+@pytest.fixture(scope="module")
+def clip():
+    d = tempfile.mkdtemp(prefix="nvc-smoke-")
+    path = os.path.join(d, "clip.mp4")
+    subprocess.run(
+        ["ffmpeg", "-v", "error", "-y", "-f", "lavfi",
+         f"-i", f"testsrc=size={W}x{H}:rate={FPS}:duration={SECONDS}",
+         "-pix_fmt", "yuv420p", "-c:v", "libx264", "-g", "12", path],
+        check=True, timeout=60,
+    )
+    yield path
+    shutil.rmtree(d, ignore_errors=True)
+
+
+def test_parse(clip):
+    tracks = [t for t in parse(clip) if isinstance(t, VideoTrack)]
+    assert len(tracks) == 1
+    t = tracks[0]
+    assert (t.width, t.height) == (W, H)
+    assert t.mime_codec.startswith("avc1.")
+    assert abs(t.duration.total_seconds() - SECONDS) < 0.2
+
+
+def test_frames_rgb(clip):
+    with Player(clip) as p:
+        n = 0
+        last = -1
+        for pts, frame in p.frames(torch.uint8):
+            assert not isinstance(frame, Exception), frame
+            assert frame.shape == (3, H, W) and frame.dtype == torch.uint8
+            assert frame.is_cuda
+            assert pts > last
+            last = pts
+            n += 1
+    assert n == FPS * SECONDS
+
+
+def test_frames_yuv420p_window(clip):
+    with Player(clip) as p:
+        out = list(p.frames(torch.uint8, start=timedelta(seconds=0.5),
+                            end=timedelta(seconds=1.0), pixel_format="yuv420p"))
+    assert 0 < len(out) <= FPS // 2 + 2
+    for _, frame in out:
+        assert frame.shape == (H * W * 3 // 2,)
+
+
+def test_screenshot(clip):
+    with Player(clip, target_size=lambda h, w: (h // 2, w // 2)) as p:
+        t, frame = p.screenshot(timedelta(seconds=1), torch.float32, accurate=True)
+        assert frame.shape == (3, H // 2, W // 2)
+        assert abs(t.total_seconds() - 1.0) < 1 / FPS + 1e-3
+        assert 0.0 <= frame.min() and frame.max() <= 1.0
+
+
+def test_screenshots(clip):
+    with Player(clip) as p:
+        shots = [s for s in p.screenshots(torch.uint8, timedelta(seconds=0.5))]
+    assert len(shots) >= 3
+    for _, frame, _ in shots:
+        assert not isinstance(frame, Exception), frame
+        assert frame.shape == (3, H, W)
+
+
+def test_duration_property(clip):
+    with Player(clip) as p:
+        assert abs(p.duration.total_seconds() - SECONDS) < 0.2
+
+
+def test_cover_art_skipped(clip):
+    """A PNG attached_pic stream must not be selected or count as ambiguity."""
+    d = tempfile.mkdtemp(prefix="nvc-smoke-cover-")
+    try:
+        png = os.path.join(d, "cover.png")
+        out = os.path.join(d, "cover.mp4")
+        subprocess.run(["ffmpeg", "-v", "error", "-y", "-f", "lavfi",
+                        "-i", "color=c=red:size=64x64:duration=1", "-frames:v", "1", png],
+                       check=True, timeout=60)
+        subprocess.run(["ffmpeg", "-v", "error", "-y", "-i", clip, "-i", png,
+                        "-map", "0", "-map", "1", "-c", "copy",
+                        "-disposition:v:1", "attached_pic", out], check=True, timeout=60)
+        vids = [t for t in parse(out) if isinstance(t, VideoTrack)]
+        assert [t.attached_pic for t in vids] == [False, True]
+        with Player(out) as p:
+            assert p.track.index == 0
+            n = sum(1 for _ in p.frames(torch.uint8))
+        assert n == FPS * SECONDS
+    finally:
+        shutil.rmtree(d, ignore_errors=True)
+
+
+def test_mpegts_start_time_and_first_gop(clip):
+    """MPEG-TS leaves start_time unset until probed. Probing must not swallow
+    the IDR (which used to drop the first GOP) and start_time must be real."""
+    d = tempfile.mkdtemp(prefix="nvc-smoke-ts-")
+    try:
+        out = os.path.join(d, "clip.ts")
+        subprocess.run(["ffmpeg", "-v", "error", "-y", "-i", clip, "-c", "copy", out],
+                       check=True, timeout=60)
+        with Player(out) as p:
+            assert p.track._start_time > 0           # ffmpeg's TS muxer starts at 1.4 s
+            frames = list(p.frames(torch.uint8))
+            assert len(frames) == FPS * SECONDS
+            first_t = p.track.pts2time(frames[0][0])
+            assert abs(first_t.total_seconds()) < 1 / FPS
+            # TS seeks by dts with no keyframe awareness; the decoder must still
+            # produce the frame actually on screen at 1.0 s, not the next IDR.
+            t, _ = p.screenshot(timedelta(seconds=1), torch.uint8, accurate=True)
+            assert abs(t.total_seconds() - 1.0) < 1 / FPS + 1e-3
+            pts0, _ = next(iter(p.frames(torch.uint8, start=timedelta(seconds=1))))
+            assert abs(p.track.pts2time(pts0).total_seconds() - 1.0) < 1 / FPS + 1e-3
+    finally:
+        shutil.rmtree(d, ignore_errors=True)
+
+
+def test_pixel_format_enum_values():
+    from nvidia_codec.ffmpeg.include.libavutil import AVPixelFormat
+    assert AVPixelFormat.YUV420P == 0 and AVPixelFormat.RGB24 == 2
+    assert isinstance(AVPixelFormat.YUV444P, int)
+
+
+def _has_encoder(name):
+    out = subprocess.run(["ffmpeg", "-hide_banner", "-encoders"],
+                         capture_output=True, text=True, timeout=30).stdout
+    return f" {name} " in out
+
+
+@pytest.fixture(scope="module")
+def clip10():
+    if not _has_encoder("libx265"):
+        pytest.skip("ffmpeg lacks libx265")
+    d = tempfile.mkdtemp(prefix="nvc-smoke10-")
+    path = os.path.join(d, "clip10.mp4")
+    subprocess.run(
+        ["ffmpeg", "-v", "error", "-y", "-f", "lavfi",
+         "-i", f"testsrc=size={W}x{H}:rate={FPS}:duration=1",
+         "-pix_fmt", "yuv420p10le", "-c:v", "libx265",
+         "-x265-params", "log-level=none", "-g", "12", path],
+        check=True, timeout=120,
+    )
+    yield path
+    shutil.rmtree(d, ignore_errors=True)
+
+
+def test_10bit_allow_high_matches_8bit(clip10):
+    """P016 (allow_high) and NV12 paths must agree on the same 10-bit source."""
+    with Player(clip10) as p:
+        _, lo = p.screenshot(timedelta(seconds=0.5), torch.float32, accurate=True)
+        assert p.surface_format == cudaVideoSurfaceFormat.NV12
+    with Player(clip10, allow_high=True) as p:
+        _, hi = p.screenshot(timedelta(seconds=0.5), torch.float32, accurate=True)
+        assert p.surface_format == cudaVideoSurfaceFormat.P016
+        assert hi.shape == (3, H, W)
+        assert 0.0 <= hi.min() and hi.max() <= 1.0
+        # yuv420p export is 8-bit only: the error is reported in-band
+        _, r = next(iter(p.frames(torch.uint8, start=timedelta(0),
+                                  pixel_format="yuv420p")))
+        assert isinstance(r, ValueError)
+    # 10-bit rounds to 8-bit at most 1/255 off, plus matrix rounding
+    assert (hi - lo).abs().max() < 0.02
+
+
+if __name__ == "__main__":
+    raise SystemExit(pytest.main([__file__, "-v"]))