VirtualDesktop 1.5.0__tar.gz → 1.6.0__tar.gz

{virtualdesktop-1.5.0/VirtualDesktop.egg-info → virtualdesktop-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: VirtualDesktop
-Version: 1.5.0
+Version: 1.6.0
 Summary: win10-win11 虚拟桌面
 Author: VirtualDesktop contributors
 License: MIT License
@@ -282,7 +282,8 @@ with VirtualWorkspace("lab") as space, space.agent() as agent:
 | 点击控件 / 送入字符 | **支持** | `agent.click(window, text=...)` / `agent.keys(window, "...")` |
 | 在桌面内跑任意 Python | **支持** | `agent.exec("...")`（可用 comtypes、pywinauto） |
 | 程序窗口截图 | **支持** | `agent.screenshot(window, "绝对路径")` |
-| 桌面截图 | **不支持** | 拿不到该桌面的屏幕 DC；需要拍屏幕请用虚拟显示器 |
+| **窗口录制** | **支持** | `space.record_window(window, "out.mp4", fps=10)`（走代理，上限约 20 fps） |
+| 桌面截图 / 桌面录制 | **不支持** | 拿不到该桌面的屏幕 DC；需要拍屏幕请用虚拟显示器 |
 | 跨桌面搬运窗口、移到主屏 | **不支持** | `move_to` 一律报 `cannot-cross-desktop`；只能在目标桌面重新 `launch` |
 
 `agent.uia_tree()` 在**桌面内**遍历 UIA，这是私有桌面唯一可用的取树方式：
@@ -498,6 +499,91 @@ configure_virtual_display(size="1920x1080", dpi="125%")   # 传 None 表示跟
 print(current_primary_size())                            # (1920, 1080)
 ```
 
+## 录制
+
+录制**只作用于本实例自己的桌面或窗口**，从不拍主屏、也不会去拍"所有屏幕"——需要那种行为的
+请直接用系统截图工具。
+
+两种录制目标，用同一个 `Recorder`：
+
+```python
+from VirtualDesktop import VirtualWorkspace
+
+with VirtualWorkspace(VirtualWorkspace.SHARED) as space:      # hide_mode 默认 virtual_screen
+    space.launch(["charmap.exe"])
+
+    # ① 录整个虚拟桌面（工作区自己的那块虚拟屏）
+    with space.record_desktop("desktop.mp4", fps=15, duration=10) as rec:
+        ...                                                    # 这期间发生的一切都被录下
+    print(rec.report().describe())
+
+    # ② 只录指定窗口（任何 hide_mode 都可以，包括私有桌面）
+    window = space.windows()[0]
+    with space.record_window(window, "window.gif", fps=10, duration=5) as rec2:
+        ...
+```
+
+窗口录制还有**私有桌面**版本（走代理进程，帧率上限约 20 fps）：
+
+```python
+with VirtualWorkspace("lab") as space, space.agent() as agent:
+    window = agent.launch(["charmap.exe"])
+    with space.record_window(window, r"C:\绝对路径\window.mp4", fps=10, duration=5):
+        ...
+```
+
+### 输出格式
+
+扩展名决定格式。**视频需要 ffmpeg 在 PATH 上**；其余只依赖 Pillow，没装 ffmpeg 也能用：
+
+| 扩展名 | 写入方 | 说明 |
+|---|---|---|
+| `.mp4` `.mkv` `.mov` `.avi` `.webm` | ffmpeg | H.264 + `yuv420p`；`quality` 映射到 CRF（0–51，默认 23） |
+| `.gif` | Pillow | 动画 GIF；`quality` 映射到调色板颜色数（8–256） |
+| `.png` `.jpg` `.webp` … | Pillow | 写成**目录下的编号帧**，另附 `frames.json` |
+
+查当前环境支持情况：
+
+```python
+from VirtualDesktop import supported_formats
+print(supported_formats())      # {'.mp4': 'ffmpeg', '.gif': 'pillow', ...}
+```
+
+> 内容完全相同的连续帧会被 GIF 优化合并成一个条目（延迟累加），所以 GIF 的**帧数可能少于
+> 录制帧数**，但总时长不变。`report().frames` 报的是实际**采集**帧数。
+
+### 流式输出
+
+需要边录边处理（送编码器、推到 socket、实时 OCR）时用 `record_stream()`：文件照常写，
+同时逐帧交给你：
+
+```python
+with space.record_stream("run.gif", target=window, fps=8, duration=5) as stream:
+    for frame in stream:
+        ...                     # frame.image 是刚采集到的 PIL 图像
+```
+
+它是个**有界**队列（默认最多缓存 240 帧）：消费端跟不上时丢最旧的帧，不会无限吃内存。
+录制到时限后迭代会**自动结束**，不会挂起。
+
+### 参数
+
+`record_desktop()` / `record_window()` 都接受：
+
+| 参数 | 含义 |
+|---|---|
+| `fps` | 目标帧率（必填，默认 10）。低于目标会被丢弃并计入 `report().dropped` |
+| `duration` | 秒；到点自动停止，`stopped_by="duration"` |
+| `max_frames` | 帧数上限；到点自动停止，`stopped_by="max_frames"` |
+| `quality` | 见上方格式表；不同后端含义不同 |
+| `format` | 覆盖扩展名推断 |
+| `on_frame` | `(frame, index)` 回调，每帧一次；回调抛异常不会中断录制 |
+| `ffmpeg` | 指定 ffmpeg 可执行文件路径 |
+
+`report()` 返回 `RecordingReport`，含 `frames` / `fps` / `duration` / `size` / `bytes`
+/ `dropped` / `stopped_by` / `error`。**在 `with` 块内调用也是安全的**——它会先收尾再统计，
+所以报的大小是成品文件的大小。
+
 ## 能力边界
 
 | 想做的事 | 虚拟显示器 | offscreen |
@@ -508,6 +594,8 @@ print(current_primary_size())                            # (1920, 1080)
 | 送入字符（窗口消息） | 能 | 能 |
 | **程序窗口截图** | **能** | **能** |
 | **桌面截图** | **能**（拍到窗口） | **不能**（窗口在所有显示器之外） |
+| **窗口录制** | **能** | **能** |
+| **桌面录制** | **能**（录工作区自己的虚拟屏） | **不能**（没有属于自己的屏幕区域） |
 | 外部 pywinauto / UIA 直接连上 | 能 | 能 |
 | 移动真实鼠标来点击 | 能 | **不能**（窗口在屏幕之外） |
 | 滚轮 | 能 | **不能** |
@@ -528,6 +616,8 @@ print(current_primary_size())                            # (1920, 1080)
 | 完整 UIA 树 | **支持** | 外部 UIA，或 `--ui-tree DIR` |
 | 程序窗口截图 | **支持** | `ws.capture(hwnd, save_to=...)` / `CaptureEngine.capture(hwnd)` |
 | 桌面截图 | **支持**（`virtual_screen`） | `ws.capture_desktop()` / `capture_monitor()` / `capture_all_screens()` |
+| **窗口录制** | **支持** | `ws.record_window(hwnd, "out.mp4", fps=15, duration=10)` |
+| **桌面录制** | **支持**（`virtual_screen`） | `ws.record_desktop("out.mp4", fps=15)` |
 | 真实鼠标 / 滚轮 / 键盘 | **支持**（`virtual_screen`） | pywinauto `click_input()` / `type_keys()`，或 pyautogui |
 | 在显示器之间移动窗口 | **支持** | `move_to("\\\\.\\DISPLAY2")` / `move_all_to(...)` / `move_to_primary()` |
 | 退出时还原窗口 | **支持** | `with` 退出自动还原；异常退出同样还原 |
@@ -583,7 +673,9 @@ VIRTUALDESKTOP_LOG_FILE=<path>
 | 窗口截图是黑帧 | 应用为硬件加速 / 受保护内容 | 系统限制；换 `bitblt` 试试，或确认窗口有内容 |
 | 桌面截图少了右下角 | 进程不感知 DPI，矩形按逻辑坐标算 | 先调 `CaptureEngine().ensure_dpi_aware()` |
 | 桌面截图拍不到工作区窗口 | 用了 `offscreen`，窗口在所有显示器之外 | 改用 `hide_mode="virtual_screen"` |
-| `capture_desktop()` 报"workspace is not open" | offscreen 模式下没有绑定显示器 | 改用 `capture_all_screens()`，或用 `virtual_screen` |
+| `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` / 帧序列 |
 | 真实鼠标点击无效 | 窗口在屏幕之外，或拿不到前台焦点 | 用 `virtual_screen`，或改用消息驱动 |
 
 **离线 / 内网部署**：把安装包按清单里的文件名（`VirtualDesktop/driver_manifest.json` 的