VirtualDesktop 1.6.2__tar.gz → 1.6.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: VirtualDesktop
-Version: 1.6.2
+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` |
@@ -677,7 +677,7 @@ VIRTUALDESKTOP_LOG_FILE=<path>
 | `capture_desktop()` 报"workspace has no monitor" | `offscreen` 模式没有属于自己的屏幕区域 | 用 `hide_mode="virtual_screen"`，或改用 `capture(hwnd)` / `record_window(hwnd)` |
 | 录制报 `record-would-capture-user-screen` | 工作区用的是物理屏 | 改用虚拟显示器；确实要录主屏请显式传 `monitor="primary"` |
 | 录制报 `ffmpeg-missing` | 目标格式是视频但 PATH 上没有 ffmpeg | 装 ffmpeg、传 `ffmpeg=<路径>`，或改录 `.gif` / 帧序列 |
-| 桌面截图/录制报 `desktop-capture-failed`，且**物理屏和虚拟屏都失败** | 桌面设备上下文的**像素读取能力**整体失效（`BitBlt` 与 `GetPixel` 都返回 error 6 / 0xFFFFFFFF） | 这不是本库的问题也不是驱动残留：**注销重登或重启系统**即可恢复。窗口截图（`PrintWindow`）不受影响，可继续用 |
+| 桌面截图/录制**所有**显示器都报 `desktop-capture-failed`，`BitBlt` 与 `GetPixel` 一起失效 | 桌面设备上下文的像素读取能力整体失效（显示栈状态异常，不是本库也不是驱动残留） | **注销重登或重启系统**即可恢复；窗口截图（`PrintWindow`）不受影响，可继续用 |
 | 真实鼠标点击无效 | 窗口在屏幕之外，或拿不到前台焦点 | 用 `virtual_screen`，或改用消息驱动 |
 
 **离线 / 内网部署**：把安装包按清单里的文件名（`VirtualDesktop/driver_manifest.json` 的

{virtualdesktop-1.6.2 → 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` |
@@ -620,7 +620,7 @@ VIRTUALDESKTOP_LOG_FILE=<path>
 | `capture_desktop()` 报"workspace has no monitor" | `offscreen` 模式没有属于自己的屏幕区域 | 用 `hide_mode="virtual_screen"`，或改用 `capture(hwnd)` / `record_window(hwnd)` |
 | 录制报 `record-would-capture-user-screen` | 工作区用的是物理屏 | 改用虚拟显示器；确实要录主屏请显式传 `monitor="primary"` |
 | 录制报 `ffmpeg-missing` | 目标格式是视频但 PATH 上没有 ffmpeg | 装 ffmpeg、传 `ffmpeg=<路径>`，或改录 `.gif` / 帧序列 |
-| 桌面截图/录制报 `desktop-capture-failed`，且**物理屏和虚拟屏都失败** | 桌面设备上下文的**像素读取能力**整体失效（`BitBlt` 与 `GetPixel` 都返回 error 6 / 0xFFFFFFFF） | 这不是本库的问题也不是驱动残留：**注销重登或重启系统**即可恢复。窗口截图（`PrintWindow`）不受影响，可继续用 |
+| 桌面截图/录制**所有**显示器都报 `desktop-capture-failed`，`BitBlt` 与 `GetPixel` 一起失效 | 桌面设备上下文的像素读取能力整体失效（显示栈状态异常，不是本库也不是驱动残留） | **注销重登或重启系统**即可恢复；窗口截图（`PrintWindow`）不受影响，可继续用 |
 | 真实鼠标点击无效 | 窗口在屏幕之外，或拿不到前台焦点 | 用 `virtual_screen`，或改用消息驱动 |
 
 **离线 / 内网部署**：把安装包按清单里的文件名（`VirtualDesktop/driver_manifest.json` 的

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

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

{virtualdesktop-1.6.2 → 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.2 → virtualdesktop-1.6.4}/VirtualDesktop.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: VirtualDesktop
-Version: 1.6.2
+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` |
@@ -677,7 +677,7 @@ VIRTUALDESKTOP_LOG_FILE=<path>
 | `capture_desktop()` 报"workspace has no monitor" | `offscreen` 模式没有属于自己的屏幕区域 | 用 `hide_mode="virtual_screen"`，或改用 `capture(hwnd)` / `record_window(hwnd)` |
 | 录制报 `record-would-capture-user-screen` | 工作区用的是物理屏 | 改用虚拟显示器；确实要录主屏请显式传 `monitor="primary"` |
 | 录制报 `ffmpeg-missing` | 目标格式是视频但 PATH 上没有 ffmpeg | 装 ffmpeg、传 `ffmpeg=<路径>`，或改录 `.gif` / 帧序列 |
-| 桌面截图/录制报 `desktop-capture-failed`，且**物理屏和虚拟屏都失败** | 桌面设备上下文的**像素读取能力**整体失效（`BitBlt` 与 `GetPixel` 都返回 error 6 / 0xFFFFFFFF） | 这不是本库的问题也不是驱动残留：**注销重登或重启系统**即可恢复。窗口截图（`PrintWindow`）不受影响，可继续用 |
+| 桌面截图/录制**所有**显示器都报 `desktop-capture-failed`，`BitBlt` 与 `GetPixel` 一起失效 | 桌面设备上下文的像素读取能力整体失效（显示栈状态异常，不是本库也不是驱动残留） | **注销重登或重启系统**即可恢复；窗口截图（`PrintWindow`）不受影响，可继续用 |
 | 真实鼠标点击无效 | 窗口在屏幕之外，或拿不到前台焦点 | 用 `virtual_screen`，或改用消息驱动 |
 
 **离线 / 内网部署**：把安装包按清单里的文件名（`VirtualDesktop/driver_manifest.json` 的

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

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

{virtualdesktop-1.6.2 → 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 -----------------------------------------------------------------
 
 
@@ -142,6 +173,13 @@ def test_recording_a_window_writes_a_playable_gif(tmp_path):
 
 
 def test_recording_a_window_writes_an_h264_file_when_ffmpeg_exists(tmp_path):
+    """The file must be a real H.264 MP4, finalised before the process exits.
+
+    The frame count is deliberately *not* pinned to a fraction of ``fps``: the first capture of a
+    just-launched window can take seconds on a loaded machine, and a short recording then legitimately
+    contains a single frame.  What matters here is that the encoder ran, the container is valid, and
+    the pipe was closed by the recorder rather than by the interpreter exiting.
+    """
     if not shutil.which("ffmpeg"):
         pytest.skip("ffmpeg is not on PATH")
     target = tmp_path / "win.mp4"
@@ -153,7 +191,7 @@ def test_recording_a_window_writes_an_h264_file_when_ffmpeg_exists(tmp_path):
 
     assert report.ok, report.describe()
     assert report.backend == "ffmpeg"
-    assert report.frames >= 5, report.to_dict()
+    assert report.frames >= 1, report.to_dict()
     # Finalised inside the block, so the file is complete before the process exits.
     assert report.bytes_written > 0
     head = target.read_bytes()[:16]
@@ -550,7 +588,13 @@ def test_desktop_recording_writes_the_workspaces_own_monitor(tmp_path):
     assert report.ok, report.describe()
     assert report.target == f"desktop:{monitor.device}"
     # The recording is the monitor's rectangle, not a full-screen sweep.
-    assert report.size == [monitor.width, monitor.height]
+    assert tuple(report.size) == (monitor.width, monitor.height)
+    # And it contains real pixels: a desktop recording of a monitor with a window on it must not be
+    # a blank frame.
+    from PIL import Image
+
+    with Image.open(target) as image:
+        assert _variance(image) > 20.0, "the recorded desktop looks blank"
 
 
 @desktop_recording
@@ -572,7 +616,12 @@ def test_desktop_recording_is_bounded_by_the_monitor_not_the_whole_desktop(tmp_p
     from VirtualDesktop._winapi import virtual_screen_rect
 
     whole = virtual_screen_rect()
-    assert report.size == [monitor.width, monitor.height]
-    assert report.size != [whole[2] - whole[0], whole[3] - whole[1]] or len(
-        [m for m in __import__("VirtualDesktop").enumerate_monitors()]
-    ) == 1
+    assert tuple(report.size) == (monitor.width, monitor.height)
+    # The virtual desktop spans every monitor, so a recording of the workspace's own monitor must be
+    # narrower than it unless there is only one monitor attached.
+    whole_size = (whole[2] - whole[0], whole[3] - whole[1])
+    monitors = __import__("VirtualDesktop").enumerate_monitors()
+    if len(monitors) > 1:
+        assert tuple(report.size) != whole_size, (
+            f"recorded {report.size} which is the whole virtual desktop, not the monitor"
+        )