nvidia-codec 0.0.22__tar.gz → 0.0.24__tar.gz

{nvidia_codec-0.0.22/src/nvidia_codec.egg-info → nvidia_codec-0.0.24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nvidia-codec
-Version: 0.0.22
+Version: 0.0.24
 Summary: Pythonic interface to Nvidia Codec
 Home-page: https://github.com/riaqn/python-nvidia-codec
 Author: Zesen Qian
@@ -124,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
@@ -133,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.22 → nvidia_codec-0.0.24}/README.md

@@ -107,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
@@ -116,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.22 → nvidia_codec-0.0.24}/setup.cfg

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

{nvidia_codec-0.0.22 → nvidia_codec-0.0.24}/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.22 → nvidia_codec-0.0.24}/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.22 → nvidia_codec-0.0.24}/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 *
@@ -104,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.22 → nvidia_codec-0.0.24}/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,6 +10,7 @@ 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,
@@ -180,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)
@@ -247,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:
@@ -258,6 +264,48 @@ class Decoder(BaseDecoder):
         self.with_callbacks(lambda: self.send(None), post_decode=lambda pic: None)
         self._recent.clear()
 
+    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 — OR it is one but
+        its PTS is past the target (dts-space seek with B-frames: a keyframe's
+        dts precedes its pts by video_delay frames, so for a target inside
+        that window the seek picks a keyframe whose first displayed frame is
+        already too late; the on-screen frame belongs to the previous GOP) —
+        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).
+        """
+        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:
+                break                                # EOF — nothing to fix
+            pts_ok = first.av.pts == AV_NOPTS_VALUE or first.av.pts <= target_pts
+            if first.av.flags & AV_PKT_FLAG_KEY and pts_ok:
+                break                                # keyframe that displays at/before target
+            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.
         Returns (timedelta, frame) on success, (timedelta, exception) on error.

{nvidia_codec-0.0.22 → nvidia_codec-0.0.24}/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):
@@ -231,7 +246,12 @@ class VideoTrack:
         return default if r == AVColorRange.UNSPECIFIED else r
 
     def time2pts(self, time: timedelta):
-        return int(time.total_seconds() / self._time_base) + self._start_time
+        """timedelta -> track pts (floor). Exact rational arithmetic: timedelta has
+        microsecond resolution, so 1.16 s is 1160000 us and lands on pts 14848 in a
+        1/12800 base; via float it is 14847.999... and int() would floor to the
+        PREVIOUS frame for any target exactly on a frame boundary."""
+        us = time // timedelta(microseconds=1)
+        return int(Fraction(us, 1_000_000) / self._time_base) + self._start_time
 
     def pts2time(self, pts: int):
         if pts == AV_NOPTS_VALUE:

{nvidia_codec-0.0.22 → nvidia_codec-0.0.24}/src/nvidia_codec/utils/player.py

@@ -22,7 +22,10 @@ class Player(Decoder):
         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:

{nvidia_codec-0.0.22 → nvidia_codec-0.0.24/src/nvidia_codec.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nvidia-codec
-Version: 0.0.22
+Version: 0.0.24
 Summary: Pythonic interface to Nvidia Codec
 Home-page: https://github.com/riaqn/python-nvidia-codec
 Author: Zesen Qian
@@ -124,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
@@ -133,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.22 → nvidia_codec-0.0.24}/tests/test_smoke.py

@@ -86,6 +86,86 @@ def test_screenshots(clip):
         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
+            # DTS-vs-PTS window: with B-frames the GOP-2 keyframe (pts 0.96 s) has
+            # dts ~0.88 s. A target in between must still yield the previous GOP's
+            # frame, not the keyframe (which displays after the target).
+            for target in (0.90, 0.94):
+                expect = int(target * FPS + 1e-6) / FPS
+                t, _ = p.screenshot(timedelta(seconds=target), torch.uint8, accurate=True)
+                assert abs(t.total_seconds() - expect) < 1e-3, (target, t)
+                pts0, _ = next(iter(p.frames(torch.uint8, start=timedelta(seconds=target))))
+                assert abs(p.track.pts2time(pts0).total_seconds() - expect) < 1e-3, (target, pts0)
+    finally:
+        shutil.rmtree(d, ignore_errors=True)
+
+
+def test_time2pts_exact_on_frame_boundaries(clip):
+    """time2pts must not floor a target that is exactly on a frame boundary to
+    the previous frame (float 1.16 * 12800 = 14847.999...)."""
+    with Player(clip) as p:
+        tb = p.track._time_base
+        for i in range(FPS * SECONDS):
+            td = timedelta(seconds=i / FPS)
+            expect = int(round(float(td.total_seconds() / tb))) + p.track._start_time
+            assert p.track.time2pts(td) == expect, i
+        # between two frames the pts lands strictly between their pts values
+        a, b = p.track.time2pts(timedelta(seconds=1.16)), p.track.time2pts(timedelta(seconds=1.20))
+        assert a < p.track.time2pts(timedelta(seconds=1.17)) < b
+
+
+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