VirtualDesktop 1.4.1__tar.gz → 1.6.0__tar.gz

{virtualdesktop-1.4.1 → virtualdesktop-1.6.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: VirtualDesktop
-Version: 1.4.1
-Summary: Multi-window virtual-display workspaces on Windows: one pip install bootstraps the virtual display driver, hosts programs on a virtual or private desktop, keeps them off the physical screens, and hands out real window handles for automation and PrintWindow capture.
+Version: 1.6.0
+Summary: win10-win11 虚拟桌面
 Author: VirtualDesktop contributors
 License: MIT License
         
@@ -57,7 +57,9 @@ Dynamic: license-file
 
 # VirtualDesktop
 
-在 Windows 上把程序的窗口放到**你看不到的地方**去运行，并读取、操作它。窗口不出现在你的屏幕上，
+win10-win11 虚拟桌面
+
+把程序的窗口放到**你看不到的地方**去运行，并读取、操作它。窗口不出现在你的屏幕上，
 退出时自动还原。
 
 ```python
@@ -89,40 +91,46 @@ uv add VirtualDesktop             # uv（写入 pyproject.toml 并锁定）
 | 底层 | 内核**对象**（`CreateDesktopW`），独立窗口命名空间 + DACL | 显示**设备**（IddCx 驱动），系统多出一块 `\\.\DISPLAYn` |
 | 需要权限 | **零**：不需要驱动、不弹 UAC | 装一次驱动，弹**一次 UAC** |
 | 系统要求 | Win10 / 11 任意 | Win10 1809 (17763) 起 |
-| 程序窗口截图 | **不能** | **能** |
-| 桌面截图 | **不能** | **能** |
+| **程序窗口截图** | **能**（窗口需已显示） | **能** |
+| **桌面截图** | **不能**（没有屏幕 DC） | **能** |
 | 读窗口属性 / 枚举子控件 | 能（桌面内代理） | 能（外部进程直接） |
 | 点击控件 / 送入字符 | 能（窗口消息） | 能（消息 + 真实输入） |
 | 真实鼠标 / 滚轮 / 键盘 | **不能** | **能** |
 | 外部 pywinauto / pyautogui 直接驱动 | **不能** | **能** |
 | 窗口跨桌面搬运 | **不能**（Windows 限制） | 能（在显示器之间移动） |
-| 推荐场景 | 多实例并行、强隔离、不要截图 | UI 自动化、截图 OCR、无人值守抓界面 |
+| 推荐场景 | 多实例并行、强隔离、不需要桌面截图 | UI 自动化、截图 OCR、无人值守抓界面 |
 
 ### 隔离强度分级
 
-两套方案的隔离**不是"强/弱"两档，而是三个层面各不相同**，按你需要防住什么来选：
+两套方案的隔离**不是"强/弱"两档，而是几个层面各不相同**，按你需要防住什么来选：
 
 | 隔离层面 | 私有桌面 | 虚拟显示器 | 说明 |
 |---|---|---|---|
 | 窗口**发现**（能否枚举到） | **隔离** | 不隔离 | 私有桌面：`EnumWindows`/`FindWindow` 从外部看不到 |
 | 窗口**输入**（真实鼠标键盘） | **隔离** | 不隔离 | 私有桌面：没有活动指针与键盘焦点 |
-| 窗口**截图**（像素可读性） | **隔离** | 不隔离 | 私有桌面：从不参与系统合成，没有像素 |
+| 窗口**像素**（能否截图） | **不隔离** | 不隔离 | `PrintWindow` 让**应用自己绘制**，不需要屏幕，所以私有桌面同样能截 |
 | 窗口**消息**（`SendMessage` 等） | **不隔离** | 不隔离 | 拿到句柄即可投递消息，DACL 保护的是桌面对象而不是窗口消息 |
 | 进程**生命周期** | **隔离** | 不隔离 | 私有桌面关闭时其上进程一并结束；虚拟显示器上的程序由你负责 |
 
-> 关键提醒：私有桌面**不等于**"完全无法访问"。它挡的是**发现**、**输入**和**截图**，
-> 挡不住"已知句柄后投递消息"。所以不要把私有桌面当作进程级安全沙箱使用——它没有降低
-> 目标进程的权限，只是把它挪到了另一个窗口命名空间。
+> 关键提醒：私有桌面**不等于**"完全无法访问"。它挡的是**发现**和**真实输入**，
+> 挡不住"已知句柄后投递消息"，也挡不住窗口自己绘制出来的像素。所以不要把私有桌面当作
+> 进程级安全沙箱使用——它没有降低目标进程的权限，只是把它挪到了另一个窗口命名空间。
+>
+> 反过来，**"私有桌面截不了图"是个流传很广的误解**。真正的限制只有两条：
+> ①**桌面截图**（拍整块屏幕）不行，因为那块桌面没有被合成到任何输出上；
+> ②被 `SW_HIDE` 隐藏的窗口拍出来是纯色块，因为它压根不绘制。窗口只要**显示着**
+> （本库默认如此），私有桌面上的窗口截图与共享模式**逐字节一致**。
 
 ### 推荐怎么选
 
 ```
-要截图（窗口截图或桌面截图）              → 虚拟显示器
+要桌面截图（拍整块屏幕/虚拟屏）            → 虚拟显示器
 要用真实鼠标 / 滚轮 / 键盘，或 pyautogui    → 虚拟显示器
 要用 pywinauto / UIA 从外部直接驱动窗口     → 虚拟显示器
 只处理一个窗口、要截图，越省事越好          → OffscreenSession（虚拟显示器侧）
+要窗口截图、但连驱动都不想装               → 私有桌面
 ─────────────────────────────────────────────────────────────
-要多个实例互不干扰、且不需要截图            → 私有桌面
+要多个实例互不干扰                        → 私有桌面
 不能弹 UAC、不能装驱动                     → 私有桌面
 要"退出后什么都不留"（进程随桌面一起结束）   → 私有桌面
 需要窗口完全不出现在任何可见位置          → 私有桌面
@@ -131,7 +139,7 @@ uv add VirtualDesktop             # uv（写入 pyproject.toml 并锁定）
 两条常用组合：
 
 - **只是想安静地跑一个窗口并抓图** → `OffscreenSession` + `virtual_screen`
-- **想并行跑很多互不干扰的实例** → 每个实例一个 `VirtualWorkspace("名字")`
+- **想并行跑很多互不干扰的实例，同时要窗口截图** → 每个实例一个 `VirtualWorkspace("名字")`
 
 ---
 
@@ -218,17 +226,27 @@ with VirtualWorkspace("lab") as space, space.agent() as agent:
 `exec` 是逃生舱：里面的代码能 `import VirtualDesktop`、能用 `list_windows()`、`CaptureEngine`，
 也能用你自己装的任何库。代理本身只依赖 ctypes 与 comtypes。
 
-### 私有桌面不能截图
+### 私有桌面的截图能力
 
-两种截图都不行，且原因不同：
+**程序窗口能截，桌面不能截**，原因是两条不同的路：
 
 | 类型 | 结果 | 原因 |
 |---|---|---|
-| 程序窗口截图 | **不能** | 该桌面的窗口从不被系统合成，没有像素可读 |
-| 桌面截图 | **不能** | 拿不到该桌面的屏幕 DC（`BitBlt` 返回拒绝访问） |
+| 程序窗口截图 | **能** | `PrintWindow` 让**窗口自己绘制**到调用方给的 DC，不需要屏幕，也不需要合成 |
+| 桌面截图 | **不能** | 拍整块屏幕需要该桌面的屏幕 DC，拿不到（`BitBlt` 返回拒绝访问） |
+
+```python
+with VirtualWorkspace("lab") as space, space.agent() as agent:
+    window = agent.launch(["charmap.exe"])
+    frame = agent.screenshot(window, r"C:\绝对路径\window.png")   # 路径必须绝对
+    print(frame.method, frame.size, frame.analysis.blank)
+```
 
-`agent.screenshot()` 会**明确报错**（`code="capture-needs-shared-workspace"`）而不是产出空白图。
-要读状态用 `agent.info()` / `agent.text()`；要像素请改用虚拟显示器。
+路径必须**绝对**：截图由桌面内的进程执行，它的工作目录不是调用者的。省略 `path` 则只返回
+内存中的帧、不落盘。
+
+> 窗口必须是**显示状态**。被 `SW_HIDE` 隐藏的窗口会返回纯色块（`code="capture-blank-window"`），
+> 因为它压根不绘制——本库启动程序时会由放置流程负责在目标位置恢复显示。
 
 ## 能力边界
 
@@ -241,15 +259,15 @@ with VirtualWorkspace("lab") as space, space.agent() as agent:
 | 用外部进程的 pywinauto 连上并读属性 | **能** | 拿得到句柄就能读 |
 | 点击控件（`BM_CLICK` 等窗口消息） | **能** | 消息直接投递给窗口，不需要指针 |
 | 送入字符（`WM_CHAR` 消息） | **能** | 同上 |
-| **程序窗口截图** | **不能** | 桌面从不被系统合成，窗口没有像素 |
+| **程序窗口截图** | **能** | `PrintWindow` 让窗口自己绘制，不需要屏幕或合成 |
 | **桌面截图** | **不能** | 拿不到该桌面的屏幕 DC（`BitBlt` 返回拒绝访问） |
 | 移动真实鼠标来点击 | **不能** | 该桌面不是活动桌面，没有指针 |
 | 滚轮（真实滚轮事件） | **不能** | 同"移动真实鼠标" |
 | 发送真实键盘输入（`SendInput`） | **不能** | 键盘只发给活动桌面 |
 | `pywinauto` 的 `click_input()` / `type_keys()` | **不能** | 依赖真实输入与前台焦点 |
 
-要点：**能用消息驱动的都能用，需要真实输入设备的都不能用，两种截图都不能用**。需要截图或需要
-真实鼠标/滚轮的应用，请改用下面的虚拟显示器方案。
+要点：**能用消息驱动的都能用，需要真实输入设备的都不能用；程序窗口截图可以，桌面截图不行**。
+需要桌面截图或真实鼠标/滚轮的应用，请改用下面的虚拟显示器方案。
 
 ## 支持的能力与调用方式
 
@@ -263,7 +281,9 @@ with VirtualWorkspace("lab") as space, space.agent() as agent:
 | 完整 UIA 树 | **支持** | `agent.uia_tree(window)` |
 | 点击控件 / 送入字符 | **支持** | `agent.click(window, text=...)` / `agent.keys(window, "...")` |
 | 在桌面内跑任意 Python | **支持** | `agent.exec("...")`（可用 comtypes、pywinauto） |
-| 程序窗口截图 / 桌面截图 | **不支持** | 见上方原因；改用虚拟显示器 |
+| 程序窗口截图 | **支持** | `agent.screenshot(window, "绝对路径")` |
+| **窗口录制** | **支持** | `space.record_window(window, "out.mp4", fps=10)`（走代理，上限约 20 fps） |
+| 桌面截图 / 桌面录制 | **不支持** | 拿不到该桌面的屏幕 DC；需要拍屏幕请用虚拟显示器 |
 | 跨桌面搬运窗口、移到主屏 | **不支持** | `move_to` 一律报 `cannot-cross-desktop`；只能在目标桌面重新 `launch` |
 
 `agent.uia_tree()` 在**桌面内**遍历 UIA，这是私有桌面唯一可用的取树方式：
@@ -479,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 |
@@ -489,6 +594,8 @@ print(current_primary_size())                            # (1920, 1080)
 | 送入字符（窗口消息） | 能 | 能 |
 | **程序窗口截图** | **能** | **能** |
 | **桌面截图** | **能**（拍到窗口） | **不能**（窗口在所有显示器之外） |
+| **窗口录制** | **能** | **能** |
+| **桌面录制** | **能**（录工作区自己的虚拟屏） | **不能**（没有属于自己的屏幕区域） |
 | 外部 pywinauto / UIA 直接连上 | 能 | 能 |
 | 移动真实鼠标来点击 | 能 | **不能**（窗口在屏幕之外） |
 | 滚轮 | 能 | **不能** |
@@ -509,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` 退出自动还原；异常退出同样还原 |
@@ -556,7 +665,7 @@ VIRTUALDESKTOP_LOG_FILE=<path>
 | `DriverNotFoundError` | 未装虚拟显示器且不允许安装 | 去掉限制，或先跑 `VirtualDesktop install-driver` |
 | `ElevationDenied` | UAC 被取消或被策略阻止 | 在管理员终端执行一次 `VirtualDesktop install-driver` |
 | `unsupported-windows-build` | 系统低于 Win10 1809，没有 IddCx | 换系统，或用私有桌面（不需要驱动） |
-| `capture-needs-shared-workspace` | 想截私有桌面里的窗口 | 私有桌面不支持截图，改用虚拟显示器 |
+| `capture-blank-window` | 窗口被 `SW_HIDE` 隐藏，不绘制，只能拍到纯色块 | 让它处于显示状态；本库启动程序时会自动在目标位置恢复显示 |
 | `SetThreadDesktop ... error 170` | 你自己在绑定线程，而该线程已有窗口或已初始化 COM | 直接调用 `bind_thread()` 时才会遇到；库内部的枚举不再绑定调用者线程 |
 | 某程序在私有桌面上找不到窗口 | 控制台类程序（`cmd.exe`、`ping.exe`）的窗口属于 `conhost.exe`，不在自己 pid 下 | 报错会提示；用 `agent.exec()` 在桌面内驱动它，或换 GUI 程序 |
 | 安装后没出现新的虚拟屏 | 驱动已注册但显示器未启用 | 设备管理器启用；`report.requires_reboot` 为真时重启 |
@@ -564,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` 的
@@ -573,9 +684,13 @@ VIRTUALDESKTOP_LOG_FILE=<path>
 
 ## 已知限制
 
-- **私有桌面不能截图**：程序窗口截图和桌面截图都不行。窗口没有被系统合成、没有像素可读；
-  而该桌面的屏幕 DC 也拿不到（`BitBlt` 返回拒绝访问）。用 `agent.info()` / `agent.text()` 读状态，
-  需要像素请改用虚拟显示器。
+- **私有桌面不能做桌面截图**：拍整块屏幕不行，因为该桌面没有被合成到任何输出上，屏幕 DC 也
+  拿不到。**但程序窗口截图可以**——`PrintWindow` 让窗口自己绘制到调用方给的 DC，不需要屏幕，
+  所以私有桌面上的窗口截图与共享模式逐字节一致。
+- **窗口必须是显示状态才可截图**：被 `SW_HIDE` 隐藏的窗口会返回纯色块（它压根不绘制）。
+  本库启动程序时按此处理，由放置流程负责在正确位置恢复显示。
+- **共享模式下程序启动瞬间可能极短暂可见**：程序自己显示窗口，库随即隐藏并移走它。这个间隙在
+  私有桌面上不存在（窗口创建在另一块桌面上，从不经过你的屏幕）；需要完全杜绝请用私有桌面。
 - **私有桌面不能用真实鼠标 / 滚轮 / 真实键盘**：那里没有活动指针和键盘焦点；消息驱动可用。
 - **窗口无法在私有桌面之间搬运**：Windows 不允许跨桌面移动窗口。
 - 部分应用（UWP、硬件叠加层、DRM 受保护内容）任何离屏方式都抓不到——系统限制。

{virtualdesktop-1.4.1 → virtualdesktop-1.6.0}/README.md

@@ -1,6 +1,8 @@
 # VirtualDesktop
 
-在 Windows 上把程序的窗口放到**你看不到的地方**去运行，并读取、操作它。窗口不出现在你的屏幕上，
+win10-win11 虚拟桌面
+
+把程序的窗口放到**你看不到的地方**去运行，并读取、操作它。窗口不出现在你的屏幕上，
 退出时自动还原。
 
 ```python
@@ -32,40 +34,46 @@ uv add VirtualDesktop             # uv（写入 pyproject.toml 并锁定）
 | 底层 | 内核**对象**（`CreateDesktopW`），独立窗口命名空间 + DACL | 显示**设备**（IddCx 驱动），系统多出一块 `\\.\DISPLAYn` |
 | 需要权限 | **零**：不需要驱动、不弹 UAC | 装一次驱动，弹**一次 UAC** |
 | 系统要求 | Win10 / 11 任意 | Win10 1809 (17763) 起 |
-| 程序窗口截图 | **不能** | **能** |
-| 桌面截图 | **不能** | **能** |
+| **程序窗口截图** | **能**（窗口需已显示） | **能** |
+| **桌面截图** | **不能**（没有屏幕 DC） | **能** |
 | 读窗口属性 / 枚举子控件 | 能（桌面内代理） | 能（外部进程直接） |
 | 点击控件 / 送入字符 | 能（窗口消息） | 能（消息 + 真实输入） |
 | 真实鼠标 / 滚轮 / 键盘 | **不能** | **能** |
 | 外部 pywinauto / pyautogui 直接驱动 | **不能** | **能** |
 | 窗口跨桌面搬运 | **不能**（Windows 限制） | 能（在显示器之间移动） |
-| 推荐场景 | 多实例并行、强隔离、不要截图 | UI 自动化、截图 OCR、无人值守抓界面 |
+| 推荐场景 | 多实例并行、强隔离、不需要桌面截图 | UI 自动化、截图 OCR、无人值守抓界面 |
 
 ### 隔离强度分级
 
-两套方案的隔离**不是"强/弱"两档，而是三个层面各不相同**，按你需要防住什么来选：
+两套方案的隔离**不是"强/弱"两档，而是几个层面各不相同**，按你需要防住什么来选：
 
 | 隔离层面 | 私有桌面 | 虚拟显示器 | 说明 |
 |---|---|---|---|
 | 窗口**发现**（能否枚举到） | **隔离** | 不隔离 | 私有桌面：`EnumWindows`/`FindWindow` 从外部看不到 |
 | 窗口**输入**（真实鼠标键盘） | **隔离** | 不隔离 | 私有桌面：没有活动指针与键盘焦点 |
-| 窗口**截图**（像素可读性） | **隔离** | 不隔离 | 私有桌面：从不参与系统合成，没有像素 |
+| 窗口**像素**（能否截图） | **不隔离** | 不隔离 | `PrintWindow` 让**应用自己绘制**，不需要屏幕，所以私有桌面同样能截 |
 | 窗口**消息**（`SendMessage` 等） | **不隔离** | 不隔离 | 拿到句柄即可投递消息，DACL 保护的是桌面对象而不是窗口消息 |
 | 进程**生命周期** | **隔离** | 不隔离 | 私有桌面关闭时其上进程一并结束；虚拟显示器上的程序由你负责 |
 
-> 关键提醒：私有桌面**不等于**"完全无法访问"。它挡的是**发现**、**输入**和**截图**，
-> 挡不住"已知句柄后投递消息"。所以不要把私有桌面当作进程级安全沙箱使用——它没有降低
-> 目标进程的权限，只是把它挪到了另一个窗口命名空间。
+> 关键提醒：私有桌面**不等于**"完全无法访问"。它挡的是**发现**和**真实输入**，
+> 挡不住"已知句柄后投递消息"，也挡不住窗口自己绘制出来的像素。所以不要把私有桌面当作
+> 进程级安全沙箱使用——它没有降低目标进程的权限，只是把它挪到了另一个窗口命名空间。
+>
+> 反过来，**"私有桌面截不了图"是个流传很广的误解**。真正的限制只有两条：
+> ①**桌面截图**（拍整块屏幕）不行，因为那块桌面没有被合成到任何输出上；
+> ②被 `SW_HIDE` 隐藏的窗口拍出来是纯色块，因为它压根不绘制。窗口只要**显示着**
+> （本库默认如此），私有桌面上的窗口截图与共享模式**逐字节一致**。
 
 ### 推荐怎么选
 
 ```
-要截图（窗口截图或桌面截图）              → 虚拟显示器
+要桌面截图（拍整块屏幕/虚拟屏）            → 虚拟显示器
 要用真实鼠标 / 滚轮 / 键盘，或 pyautogui    → 虚拟显示器
 要用 pywinauto / UIA 从外部直接驱动窗口     → 虚拟显示器
 只处理一个窗口、要截图，越省事越好          → OffscreenSession（虚拟显示器侧）
+要窗口截图、但连驱动都不想装               → 私有桌面
 ─────────────────────────────────────────────────────────────
-要多个实例互不干扰、且不需要截图            → 私有桌面
+要多个实例互不干扰                        → 私有桌面
 不能弹 UAC、不能装驱动                     → 私有桌面
 要"退出后什么都不留"（进程随桌面一起结束）   → 私有桌面
 需要窗口完全不出现在任何可见位置          → 私有桌面
@@ -74,7 +82,7 @@ uv add VirtualDesktop             # uv（写入 pyproject.toml 并锁定）
 两条常用组合：
 
 - **只是想安静地跑一个窗口并抓图** → `OffscreenSession` + `virtual_screen`
-- **想并行跑很多互不干扰的实例** → 每个实例一个 `VirtualWorkspace("名字")`
+- **想并行跑很多互不干扰的实例，同时要窗口截图** → 每个实例一个 `VirtualWorkspace("名字")`
 
 ---
 
@@ -161,17 +169,27 @@ with VirtualWorkspace("lab") as space, space.agent() as agent:
 `exec` 是逃生舱：里面的代码能 `import VirtualDesktop`、能用 `list_windows()`、`CaptureEngine`，
 也能用你自己装的任何库。代理本身只依赖 ctypes 与 comtypes。
 
-### 私有桌面不能截图
+### 私有桌面的截图能力
 
-两种截图都不行，且原因不同：
+**程序窗口能截，桌面不能截**，原因是两条不同的路：
 
 | 类型 | 结果 | 原因 |
 |---|---|---|
-| 程序窗口截图 | **不能** | 该桌面的窗口从不被系统合成，没有像素可读 |
-| 桌面截图 | **不能** | 拿不到该桌面的屏幕 DC（`BitBlt` 返回拒绝访问） |
+| 程序窗口截图 | **能** | `PrintWindow` 让**窗口自己绘制**到调用方给的 DC，不需要屏幕，也不需要合成 |
+| 桌面截图 | **不能** | 拍整块屏幕需要该桌面的屏幕 DC，拿不到（`BitBlt` 返回拒绝访问） |
+
+```python
+with VirtualWorkspace("lab") as space, space.agent() as agent:
+    window = agent.launch(["charmap.exe"])
+    frame = agent.screenshot(window, r"C:\绝对路径\window.png")   # 路径必须绝对
+    print(frame.method, frame.size, frame.analysis.blank)
+```
 
-`agent.screenshot()` 会**明确报错**（`code="capture-needs-shared-workspace"`）而不是产出空白图。
-要读状态用 `agent.info()` / `agent.text()`；要像素请改用虚拟显示器。
+路径必须**绝对**：截图由桌面内的进程执行，它的工作目录不是调用者的。省略 `path` 则只返回
+内存中的帧、不落盘。
+
+> 窗口必须是**显示状态**。被 `SW_HIDE` 隐藏的窗口会返回纯色块（`code="capture-blank-window"`），
+> 因为它压根不绘制——本库启动程序时会由放置流程负责在目标位置恢复显示。
 
 ## 能力边界
 
@@ -184,15 +202,15 @@ with VirtualWorkspace("lab") as space, space.agent() as agent:
 | 用外部进程的 pywinauto 连上并读属性 | **能** | 拿得到句柄就能读 |
 | 点击控件（`BM_CLICK` 等窗口消息） | **能** | 消息直接投递给窗口，不需要指针 |
 | 送入字符（`WM_CHAR` 消息） | **能** | 同上 |
-| **程序窗口截图** | **不能** | 桌面从不被系统合成，窗口没有像素 |
+| **程序窗口截图** | **能** | `PrintWindow` 让窗口自己绘制，不需要屏幕或合成 |
 | **桌面截图** | **不能** | 拿不到该桌面的屏幕 DC（`BitBlt` 返回拒绝访问） |
 | 移动真实鼠标来点击 | **不能** | 该桌面不是活动桌面，没有指针 |
 | 滚轮（真实滚轮事件） | **不能** | 同"移动真实鼠标" |
 | 发送真实键盘输入（`SendInput`） | **不能** | 键盘只发给活动桌面 |
 | `pywinauto` 的 `click_input()` / `type_keys()` | **不能** | 依赖真实输入与前台焦点 |
 
-要点：**能用消息驱动的都能用，需要真实输入设备的都不能用，两种截图都不能用**。需要截图或需要
-真实鼠标/滚轮的应用，请改用下面的虚拟显示器方案。
+要点：**能用消息驱动的都能用，需要真实输入设备的都不能用；程序窗口截图可以，桌面截图不行**。
+需要桌面截图或真实鼠标/滚轮的应用，请改用下面的虚拟显示器方案。
 
 ## 支持的能力与调用方式
 
@@ -206,7 +224,9 @@ with VirtualWorkspace("lab") as space, space.agent() as agent:
 | 完整 UIA 树 | **支持** | `agent.uia_tree(window)` |
 | 点击控件 / 送入字符 | **支持** | `agent.click(window, text=...)` / `agent.keys(window, "...")` |
 | 在桌面内跑任意 Python | **支持** | `agent.exec("...")`（可用 comtypes、pywinauto） |
-| 程序窗口截图 / 桌面截图 | **不支持** | 见上方原因；改用虚拟显示器 |
+| 程序窗口截图 | **支持** | `agent.screenshot(window, "绝对路径")` |
+| **窗口录制** | **支持** | `space.record_window(window, "out.mp4", fps=10)`（走代理，上限约 20 fps） |
+| 桌面截图 / 桌面录制 | **不支持** | 拿不到该桌面的屏幕 DC；需要拍屏幕请用虚拟显示器 |
 | 跨桌面搬运窗口、移到主屏 | **不支持** | `move_to` 一律报 `cannot-cross-desktop`；只能在目标桌面重新 `launch` |
 
 `agent.uia_tree()` 在**桌面内**遍历 UIA，这是私有桌面唯一可用的取树方式：
@@ -422,6 +442,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 |
@@ -432,6 +537,8 @@ print(current_primary_size())                            # (1920, 1080)
 | 送入字符（窗口消息） | 能 | 能 |
 | **程序窗口截图** | **能** | **能** |
 | **桌面截图** | **能**（拍到窗口） | **不能**（窗口在所有显示器之外） |
+| **窗口录制** | **能** | **能** |
+| **桌面录制** | **能**（录工作区自己的虚拟屏） | **不能**（没有属于自己的屏幕区域） |
 | 外部 pywinauto / UIA 直接连上 | 能 | 能 |
 | 移动真实鼠标来点击 | 能 | **不能**（窗口在屏幕之外） |
 | 滚轮 | 能 | **不能** |
@@ -452,6 +559,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` 退出自动还原；异常退出同样还原 |
@@ -499,7 +608,7 @@ VIRTUALDESKTOP_LOG_FILE=<path>
 | `DriverNotFoundError` | 未装虚拟显示器且不允许安装 | 去掉限制，或先跑 `VirtualDesktop install-driver` |
 | `ElevationDenied` | UAC 被取消或被策略阻止 | 在管理员终端执行一次 `VirtualDesktop install-driver` |
 | `unsupported-windows-build` | 系统低于 Win10 1809，没有 IddCx | 换系统，或用私有桌面（不需要驱动） |
-| `capture-needs-shared-workspace` | 想截私有桌面里的窗口 | 私有桌面不支持截图，改用虚拟显示器 |
+| `capture-blank-window` | 窗口被 `SW_HIDE` 隐藏，不绘制，只能拍到纯色块 | 让它处于显示状态；本库启动程序时会自动在目标位置恢复显示 |
 | `SetThreadDesktop ... error 170` | 你自己在绑定线程，而该线程已有窗口或已初始化 COM | 直接调用 `bind_thread()` 时才会遇到；库内部的枚举不再绑定调用者线程 |
 | 某程序在私有桌面上找不到窗口 | 控制台类程序（`cmd.exe`、`ping.exe`）的窗口属于 `conhost.exe`，不在自己 pid 下 | 报错会提示；用 `agent.exec()` 在桌面内驱动它，或换 GUI 程序 |
 | 安装后没出现新的虚拟屏 | 驱动已注册但显示器未启用 | 设备管理器启用；`report.requires_reboot` 为真时重启 |
@@ -507,7 +616,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` 的
@@ -516,9 +627,13 @@ VIRTUALDESKTOP_LOG_FILE=<path>
 
 ## 已知限制
 
-- **私有桌面不能截图**：程序窗口截图和桌面截图都不行。窗口没有被系统合成、没有像素可读；
-  而该桌面的屏幕 DC 也拿不到（`BitBlt` 返回拒绝访问）。用 `agent.info()` / `agent.text()` 读状态，
-  需要像素请改用虚拟显示器。
+- **私有桌面不能做桌面截图**：拍整块屏幕不行，因为该桌面没有被合成到任何输出上，屏幕 DC 也
+  拿不到。**但程序窗口截图可以**——`PrintWindow` 让窗口自己绘制到调用方给的 DC，不需要屏幕，
+  所以私有桌面上的窗口截图与共享模式逐字节一致。
+- **窗口必须是显示状态才可截图**：被 `SW_HIDE` 隐藏的窗口会返回纯色块（它压根不绘制）。
+  本库启动程序时按此处理，由放置流程负责在正确位置恢复显示。
+- **共享模式下程序启动瞬间可能极短暂可见**：程序自己显示窗口，库随即隐藏并移走它。这个间隙在
+  私有桌面上不存在（窗口创建在另一块桌面上，从不经过你的屏幕）；需要完全杜绝请用私有桌面。
 - **私有桌面不能用真实鼠标 / 滚轮 / 真实键盘**：那里没有活动指针和键盘焦点；消息驱动可用。
 - **窗口无法在私有桌面之间搬运**：Windows 不允许跨桌面移动窗口。
 - 部分应用（UWP、硬件叠加层、DRM 受保护内容）任何离屏方式都抓不到——系统限制。

{virtualdesktop-1.4.1 → virtualdesktop-1.6.0}/VirtualDesktop/__init__.py

@@ -62,8 +62,17 @@ from .window import WindowMounter, WindowRecord, find_window, window_diagnostics
 from .workspace import SHARED, VirtualWorkspace, WorkspaceWindow
 from .agent import AgentProcess, AgentSession
 from .display_setup import configure_virtual_display, current_primary_dpi, current_primary_size
+from .record import (
+    GIF_FORMATS,
+    IMAGE_FORMATS,
+    VIDEO_FORMATS,
+    Recorder,
+    RecordingReport,
+    record_stream,
+    supported_formats,
+)
 
-__version__ = "1.4.1"
+__version__ = "1.6.0"
 
 __all__ = [
     "__version__",
@@ -106,6 +115,14 @@ __all__ = [
     "Frame",
     "analyze_image",
     "DEFAULT_METHODS",
+    # recording
+    "Recorder",
+    "RecordingReport",
+    "record_stream",
+    "supported_formats",
+    "VIDEO_FORMATS",
+    "GIF_FORMATS",
+    "IMAGE_FORMATS",
     # configuration
     "DriverConfig",
     "SessionConfig",