VideoDB 技能定位为视频、直播流与桌面会话的「感知 + 记忆 + 操作」层，核心以 VideoDB Python SDK 实现。
【主要用途】
- 视频接入与直播流：上传本地文件、公开 URL 或 YouTube 链接，或连接 RTSP/RTMP 直播源，返回可播放的网页流链接。
- 转码与归一化：服务端处理编码、码率、帧率、分辨率、宽高比，例如把 1080p 转 720p，或用 reframe 适配竖屏/方形等平台要求。
- 索引与搜索：建立语音索引、场景索引和关键词索引，进行语义或关键词搜索，返回带时间戳与可播放证据的精确片段，并可从搜索结果自动创建剪辑。
- 时间线编辑与生成：字幕生成、翻译、烧录；文字/图片/品牌叠加与动态字幕；背景音乐、配音、译制；通过时间线操作进行程序化合成与导出。
- 直播流监控：对 RTSP 直播源进行实时视觉与语音理解，发出事件与告警。
- 桌面感知（仅 macOS）：启动/停止捕获屏幕、麦克风与系统音频，流式输出实时上下文，保存会话情景记忆，运行实时告警，生成会话摘要、可搜索时间线与可播放证据链接。
【使用方式】 安装：pip install "videodb[capture]" python-dotenv（Linux 上若 capture extra 失败，改用 pip install videodb python-dotenv）。 配置：用户自行设置 VIDEO_DB_API_KEY，可导出到终端或写入项目 .env 文件；免费密钥在 console.videodb.io 获取，含 50 次免费上传且无需信用卡。不要代为读写 API 密钥。 运行前加载环境变量并连接： from dotenv import load_dotenv load_dotenv(".env") import videodb conn = videodb.connect() 连接会读取 VIDEO_DB_API_KEY，缺失时抛出 AuthenticationError。
常见操作示例：上传 coll.upload(url=...) 或 coll.upload(file_path=...)；语音转写与字幕 video.index_spoken_words(force=True)、video.get_transcript_text()、video.add_subtitle()；视频内搜索 video.search(...) 并 results.get_shots()、results.compile()；场景搜索使用 index_scenes(extraction_type=SceneExtractionType.shot_based, prompt=...)，搜索时用 SearchType.semantic、IndexType.scene、scene_index_id 与 score_threshold（建议 0.3 以上）；时间线编辑用 Timeline、VideoAsset、TextAsset、TextStyle，再 timeline.generate_stream()；转码用 conn.transcode(...) 配 VideoConfig/AudioConfig；reframe 用 video.reframe(start=0, end=60, target="vertical", mode=ReframeMode.smart)。 桌面捕获：使用 ws_listener.py 监听 WebSocket 事件，事件写入 $STATE_DIR/videodb_events.jsonl，启动新捕获时用 --clear 避免旧事件混入。
【适用场景】 平台对视频宽高比或分辨率有要求时重新构图或转码；为 Twitter/Instagram/TikTok 调整尺寸；在视频上叠加音频或音乐；添加字幕；合并或裁剪片段；生成配音、音乐或音效；视频内精确检索与生成剪辑；直播流实时监控告警；桌面会话录制与摘要。
【已知限制与注意事项】
- 桌面捕获仅支持 macOS。
- reframe() 是较慢的服务端操作，长视频可能耗时数分钟甚至超时；建议用 start/end 限定片段，或传 callback_url 异步处理，也可先裁短再 reframe。
- Scene 索引没有 force 参数，重复索引会报错，需从错误信息中提取已有 scene_index_id。
- 搜索无结果会抛出 InvalidRequestError: No results found，应捕获并视为空结果。
- 时间线时间戳必须校验：start >= 0、start < end、end <= video.length，负值会被静默接受但产生损坏输出。
- generate_video()、create_collection() 等可能因套餐限制失败，需告知用户套餐限制。
- 当 VideoDB 支持某操作时，不应使用 ffmpeg、moviepy 或本地编码工具；仅对 reference/editor.md 限制项（转场、变速、裁剪/缩放、调色、音量混合）回退到本地工具。
- API 密钥应由用户自行设置，不要代为读取或写入。
- 官方文档中的补充参考资料位于本地 reference/ 目录，覆盖 API 参考、搜索、编辑器、流媒体、生成式、RTStream、桌面捕获、捕获参考与用例。