mirror of
https://github.com/affaan-m/everything-claude-code.git
synced 2026-04-03 23:53:29 +08:00
105 lines
4.7 KiB
Markdown
105 lines
4.7 KiB
Markdown
# Capture 指南
|
||
|
||
## 概述
|
||
|
||
VideoDB Capture 支持实时屏幕和音频录制，并具备 AI 处理能力。桌面捕获目前仅支持 **macOS**。
|
||
|
||
关于代码层面的详细信息（SDK 方法、事件结构、AI 管道），请参阅 [capture-reference.md](capture-reference.md)。
|
||
|
||
## 快速开始
|
||
|
||
1. **启动 WebSocket 监听器**：`python scripts/ws_listener.py --clear &`
|
||
2. **运行捕获代码**（见下方完整捕获工作流）
|
||
3. **事件写入到**：`/tmp/videodb_events.jsonl`
|
||
|
||
***
|
||
|
||
## 完整捕获工作流
|
||
|
||
无需 webhook 或轮询。WebSocket 会传递所有事件，包括会话生命周期事件。
|
||
|
||
> **关键提示：** `CaptureClient` 必须在整个捕获期间持续运行。它运行本地录制器二进制文件，将屏幕/音频数据流式传输到 VideoDB。如果创建 `CaptureClient` 的 Python 进程退出，录制器二进制文件将被终止，捕获会静默停止。请始终将捕获代码作为**长期运行的后台进程**运行（例如 `nohup python capture_script.py &`），并使用信号处理（`asyncio.Event` + `SIGINT`/`SIGTERM`）来保持其存活，直到您明确停止它。
|
||
|
||
1. 在后台**启动 WebSocket 监听器**，使用 `--clear` 标志来清除旧事件。等待其创建 WebSocket ID 文件。
|
||
|
||
2. **读取 WebSocket ID**。此 ID 是捕获会话和 AI 管道所必需的。
|
||
|
||
3. **创建捕获会话**，并为桌面客户端生成客户端令牌。
|
||
|
||
4. 使用令牌**初始化 CaptureClient**。请求麦克风和屏幕捕获权限。
|
||
|
||
5. **列出并选择通道**（麦克风、显示器、系统音频）。在您希望持久化为视频的通道上设置 `store = True`。
|
||
|
||
6. 使用选定的通道**启动会话**。
|
||
|
||
7. 通过读取事件直到看到 `capture_session.active` 来**等待会话激活**。此事件包含 `rtstreams` 数组。将会话信息（会话 ID、RTStream ID）保存到文件（例如 `/tmp/videodb_capture_info.json`），以便其他脚本可以读取。
|
||
|
||
8. **保持进程存活**。使用 `asyncio.Event` 配合 `SIGINT`/`SIGTERM` 的信号处理器来阻塞进程，直到显式停止。写入一个 PID 文件（例如 `/tmp/videodb_capture_pid`），以便稍后可以使用 `kill $(cat /tmp/videodb_capture_pid)` 停止该进程。PID 文件应在每次运行时被覆盖，以便重新运行时始终具有正确的 PID。
|
||
|
||
9. **启动 AI 管道**（在单独的命令/脚本中）对每个 RTStream 进行音频索引和视觉索引。从保存的会话信息文件中读取 RTStream ID。
|
||
|
||
10. **编写自定义事件处理逻辑**（在单独的命令/脚本中），根据您的用例读取实时事件。示例：
|
||
* 当 `visual_index` 提到 "Slack" 时记录 Slack 活动
|
||
* 当 `audio_index` 事件到达时总结讨论
|
||
* 当 `transcript` 中出现特定关键词时触发警报
|
||
* 从屏幕描述中跟踪应用程序使用情况
|
||
|
||
11. **停止捕获** - 完成后，向捕获进程发送 SIGTERM。它应在信号处理器中调用 `client.stop_capture()` 和 `client.shutdown()`。
|
||
|
||
12. **等待导出** - 通过读取事件直到看到 `capture_session.exported`。此事件包含 `exported_video_id`、`stream_url` 和 `player_url`。这可能在停止捕获后需要几秒钟。
|
||
|
||
13. **停止 WebSocket 监听器** - 收到导出事件后，使用 `kill $(cat /tmp/videodb_ws_pid)` 来干净地终止它。
|
||
|
||
***
|
||
|
||
## 关机顺序
|
||
|
||
正确的关机顺序对于确保捕获所有事件非常重要：
|
||
|
||
1. **停止捕获会话** — `client.stop_capture()` 然后 `client.shutdown()`
|
||
2. **等待导出事件** — 轮询 `/tmp/videodb_events.jsonl` 以查找 `capture_session.exported`
|
||
3. **停止 WebSocket 监听器** — `kill $(cat /tmp/videodb_ws_pid)`
|
||
|
||
在收到导出事件之前，请**不要**杀死 WebSocket 监听器，否则您将错过最终的视频 URL。
|
||
|
||
***
|
||
|
||
## 脚本
|
||
|
||
| 脚本 | 描述 |
|
||
|--------|-------------|
|
||
| `scripts/ws_listener.py` | WebSocket 事件监听器（转储为 JSONL） |
|
||
|
||
### ws\_listener.py 用法
|
||
|
||
```bash
|
||
# Start listener in background (append to existing events)
|
||
python scripts/ws_listener.py &
|
||
|
||
# Start listener with clear (new session, clears old events)
|
||
python scripts/ws_listener.py --clear &
|
||
|
||
# Custom output directory
|
||
python scripts/ws_listener.py --clear /path/to/events &
|
||
|
||
# Stop the listener
|
||
kill $(cat /tmp/videodb_ws_pid)
|
||
```
|
||
|
||
**选项：**
|
||
|
||
* `--clear`：在启动前清除事件文件。启动新捕获会话时使用。
|
||
|
||
**输出文件：**
|
||
|
||
* `videodb_events.jsonl` - 所有 WebSocket 事件
|
||
* `videodb_ws_id` - WebSocket 连接 ID（用于 `ws_connection_id` 参数）
|
||
* `videodb_ws_pid` - 进程 ID（用于停止监听器）
|
||
|
||
**功能：**
|
||
|
||
* 连接断开时自动重连，并采用指数退避
|
||
* 收到 SIGINT/SIGTERM 时优雅关机
|
||
* PID 文件，便于进程管理
|
||
* 连接状态日志记录
|