捕获指南¶

概述¶

VideoDB Capture 支持具备 AI 处理功能的实时屏幕和音频录制。桌面捕获目前仅支持 macOS。

有关代码级细节（SDK 方法、事件结构、AI 流水线），请参阅 capture-reference.md。

快速开始¶

1. 启动 WebSocket 监听器：python scripts/ws_listener.py --clear &
2. 运行捕获代码（参见下文完整捕获工作流）
3. 事件写入位置：/tmp/videodb_events.jsonl

完整捕获工作流¶

无需 Webhook 或轮询 LiveEvent。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. 保持进程存活。为了在明确停止之前阻塞进程，在 SIGINT/SIGTERM 信号处理程序中使用 asyncio.Event。写入 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。

脚本¶

ws_listener.py 的使用方法¶

# 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 文件
• 记录连接状态