VirtualDesktop 1.6.3__tar.gz → 1.6.4__tar.gz

{virtualdesktop-1.6.3 → virtualdesktop-1.6.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: VirtualDesktop
-Version: 1.6.3
+Version: 1.6.4
 Summary: win10-win11 虚拟桌面
 Author: VirtualDesktop contributors
 License: MIT License
@@ -572,7 +572,7 @@ with space.record_stream("run.gif", target=window, fps=8, duration=5) as stream:
 
 | 参数 | 含义 |
 |---|---|
-| `fps` | 目标帧率（必填，默认 10）。低于目标会被丢弃并计入 `report().dropped` |
+| `fps` | 目标帧率（默认 10）。**范围 1–90**，超出会被钳制：`report().fps` 报实际使用的值，`report().fps_requested` 只在被钳制时给出原值，`report().fps_clamped` 为布尔。低于目标会被丢弃并计入 `report().dropped`；`report().measured_fps` 是达成帧率（跟不上目标时低于 `fps`） |
 | `duration` | 秒；到点自动停止，`stopped_by="duration"` |
 | `max_frames` | 帧数上限；到点自动停止，`stopped_by="max_frames"` |
 | — | 不传 `duration` 时有一个 **1 小时硬上限**（`MAX_DURATION`）：录制线程持有 `Recorder` 引用，被丢弃且未 `stop()` 的对象无法回收，没有上限就会一直录下去（并带着 ffmpeg 子进程）。正常用法请始终用 `with` |

{virtualdesktop-1.6.3 → virtualdesktop-1.6.4}/README.md

@@ -515,7 +515,7 @@ with space.record_stream("run.gif", target=window, fps=8, duration=5) as stream:
 
 | 参数 | 含义 |
 |---|---|
-| `fps` | 目标帧率（必填，默认 10）。低于目标会被丢弃并计入 `report().dropped` |
+| `fps` | 目标帧率（默认 10）。**范围 1–90**，超出会被钳制：`report().fps` 报实际使用的值，`report().fps_requested` 只在被钳制时给出原值，`report().fps_clamped` 为布尔。低于目标会被丢弃并计入 `report().dropped`；`report().measured_fps` 是达成帧率（跟不上目标时低于 `fps`） |
 | `duration` | 秒；到点自动停止，`stopped_by="duration"` |
 | `max_frames` | 帧数上限；到点自动停止，`stopped_by="max_frames"` |
 | — | 不传 `duration` 时有一个 **1 小时硬上限**（`MAX_DURATION`）：录制线程持有 `Recorder` 引用，被丢弃且未 `stop()` 的对象无法回收，没有上限就会一直录下去（并带着 ffmpeg 子进程）。正常用法请始终用 `with` |

{virtualdesktop-1.6.3 → virtualdesktop-1.6.4}/VirtualDesktop/__init__.py

@@ -72,7 +72,7 @@ from .record import (
     supported_formats,
 )
 
-__version__ = "1.6.3"
+__version__ = "1.6.4"
 
 __all__ = [
     "__version__",

{virtualdesktop-1.6.3 → virtualdesktop-1.6.4}/VirtualDesktop/record.py

@@ -60,6 +60,8 @@ __all__ = [
     "GIF_FORMATS",
     "IMAGE_FORMATS",
     "MAX_DURATION",
+    "MAX_FPS",
+    "MIN_FPS",
     "Recorder",
     "RecordingReport",
     "VIDEO_FORMATS",
@@ -86,6 +88,12 @@ _PIPE_PIXEL_FORMAT = "rgb24"
 #: explicit larger ``duration``.
 MAX_DURATION = 3600.0
 
+#: Frame-rate range a recording is held to.  ``fps`` outside it is clamped (and reported), because
+#: the alternative is either a refusal over a cosmetic parameter or a file whose real rate differs
+#: from the one the caller asked for without saying so.
+MAX_FPS = 90.0
+MIN_FPS = 1.0
+
 
 def supported_formats(ffmpeg: Optional[str] = None) -> Dict[str, str]:
     """Which extensions this machine can write, and what writes them."""
@@ -114,6 +122,7 @@ class RecordingReport:
     path: str
     format: str
     frames: int
+    #: The frame rate actually used (``fps`` after clamping).
     fps: float
     duration: float
     size: Optional[Tuple[int, int]] = None
@@ -122,11 +131,20 @@ class RecordingReport:
     dropped: int = 0
     error: str = ""
     backend: str = ""
+    #: The ``fps`` the caller asked for, when it differed from the one actually used.
+    fps_requested: Optional[float] = None
+    #: Frames per second actually achieved, which is below ``fps`` whenever frames were dropped.
+    measured_fps: float = 0.0
 
     @property
     def ok(self) -> bool:
         return not self.error and self.frames > 0
 
+    @property
+    def fps_clamped(self) -> bool:
+        """Whether ``fps`` was adjusted into ``[MIN_FPS, MAX_FPS]``."""
+        return self.fps_requested is not None and self.fps_requested != self.fps
+
     def to_dict(self) -> dict:
         return {
             "target": self.target,
@@ -135,6 +153,9 @@ class RecordingReport:
             "backend": self.backend,
             "frames": self.frames,
             "fps": round(self.fps, 3),
+            "measured_fps": round(self.measured_fps, 3),
+            "fps_requested": self.fps_requested,
+            "fps_clamped": self.fps_clamped,
             "duration": round(self.duration, 3),
             "size": list(self.size) if self.size else None,
             "bytes": self.bytes_written,
@@ -146,9 +167,11 @@ class RecordingReport:
     def describe(self) -> str:
         if self.error:
             return f"{self.target} -> {self.path}: {self.error}"
+        clamped = f" (asked {self.fps_requested:g})" if self.fps_clamped else ""
         return (
             f"{self.target} -> {self.path} ({self.format}, {self.frames} frames, "
-            f"{self.duration:.1f}s, {self.fps:.1f} fps, {self.bytes_written / 1024:.0f} KB)"
+            f"{self.duration:.1f}s, {self.fps:g} fps{clamped}, "
+            f"{self.bytes_written / 1024:.0f} KB)"
         )
 
 
@@ -325,7 +348,18 @@ class Recorder:
         self.path = Path(path)
         self.source = source
         self.target = target
-        self.fps = float(fps)
+        # Clamp into the supported range rather than refusing or silently producing something else.
+        # Below MIN_FPS a recording is a slideshow; above MAX_FPS the capture path is the bottleneck
+        # anyway (PrintWindow measured at ~23 fps on this class of machine), so a higher number would
+        # only make the recorder drop frames and misrepresent the result.
+        self.fps_requested = float(fps)
+        self.fps = min(max(float(fps), MIN_FPS), MAX_FPS)
+        self.fps_clamped = self.fps != self.fps_requested
+        if self.fps_clamped:
+            log.info(
+                "fps %.3f is outside [%s, %s]; recording at %.3f",
+                self.fps_requested, MIN_FPS, MAX_FPS, self.fps,
+            )
         self.duration = duration
         self.max_frames = max_frames
         self.format = _resolve_format(self.path) if format is None else (
@@ -405,7 +439,8 @@ class Recorder:
             path=str(self.path),
             format=self.format,
             frames=self._frames,
-            fps=self._frames / elapsed if elapsed > 0 else 0.0,
+            fps=self.fps,
+            measured_fps=self._frames / elapsed if elapsed > 0 else 0.0,
             duration=elapsed,
             size=self._size,
             bytes_written=bytes_written,
@@ -413,6 +448,8 @@ class Recorder:
             dropped=self._dropped,
             error=error,
             backend=self._backend,
+            # Only reported when it differed: an absent value means "you got what you asked for".
+            fps_requested=self.fps_requested if self.fps_clamped else None,
         )
 
     def __enter__(self) -> "Recorder":

{virtualdesktop-1.6.3 → virtualdesktop-1.6.4}/VirtualDesktop.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: VirtualDesktop
-Version: 1.6.3
+Version: 1.6.4
 Summary: win10-win11 虚拟桌面
 Author: VirtualDesktop contributors
 License: MIT License
@@ -572,7 +572,7 @@ with space.record_stream("run.gif", target=window, fps=8, duration=5) as stream:
 
 | 参数 | 含义 |
 |---|---|
-| `fps` | 目标帧率（必填，默认 10）。低于目标会被丢弃并计入 `report().dropped` |
+| `fps` | 目标帧率（默认 10）。**范围 1–90**，超出会被钳制：`report().fps` 报实际使用的值，`report().fps_requested` 只在被钳制时给出原值，`report().fps_clamped` 为布尔。低于目标会被丢弃并计入 `report().dropped`；`report().measured_fps` 是达成帧率（跟不上目标时低于 `fps`） |
 | `duration` | 秒；到点自动停止，`stopped_by="duration"` |
 | `max_frames` | 帧数上限；到点自动停止，`stopped_by="max_frames"` |
 | — | 不传 `duration` 时有一个 **1 小时硬上限**（`MAX_DURATION`）：录制线程持有 `Recorder` 引用，被丢弃且未 `stop()` 的对象无法回收，没有上限就会一直录下去（并带着 ffmpeg 子进程）。正常用法请始终用 `with` |

{virtualdesktop-1.6.3 → virtualdesktop-1.6.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "VirtualDesktop"
-version = "1.6.3"
+version = "1.6.4"
 description = "win10-win11 虚拟桌面"
 readme = "README.md"
 requires-python = ">=3.9"

{virtualdesktop-1.6.3 → virtualdesktop-1.6.4}/tests/test_record.py

@@ -115,6 +115,37 @@ def test_fps_must_be_positive():
     assert excinfo.value.code == "bad-fps"
 
 
+def test_fps_is_clamped_into_the_supported_range():
+    """``fps`` outside ``[MIN_FPS, MAX_FPS]`` is clamped, and the request is still reported.
+
+    Clamping rather than refusing keeps a cosmetic parameter from failing a recording, and reporting
+    ``fps_requested`` keeps it from silently producing a file at a rate the caller did not ask for.
+    """
+    from VirtualDesktop.record import MAX_FPS, MIN_FPS
+
+    assert (MIN_FPS, MAX_FPS) == (1.0, 90.0)
+
+    cases = [
+        (0.5, MIN_FPS, True),
+        (MIN_FPS, MIN_FPS, False),
+        (30.0, 30.0, False),
+        (MAX_FPS, MAX_FPS, False),
+        (MAX_FPS * 2, MAX_FPS, True),
+        (1e6, MAX_FPS, True),
+    ]
+    for requested, expected, clamped in cases:
+        recorder = Recorder("unused.gif", lambda: None, fps=requested)
+        assert recorder.fps == expected, (requested, recorder.fps)
+        assert recorder.fps_clamped is clamped, (requested, recorder.fps_clamped)
+        report = recorder.report()
+        assert report.fps == expected
+        assert report.fps_clamped is clamped
+        # The original request is reported only when it was overridden: an absent value means the
+        # caller got exactly what they asked for.
+        assert report.fps_requested == (float(requested) if clamped else None)
+        assert report.to_dict()["fps_clamped"] is clamped
+
+
 # -- window recording -----------------------------------------------------------------