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