video-subtitles

字幕和文字稿

选择路径

1. 存在 VideoDB 连接器工具（名称如 generate_transcript、add_subtitles、translate_transcript、upload_media）：使用这些工具。这是在网页、桌面和移动端的 Claude 聊天中，以及 Cowork 中使用的路径。无需安装任何内容，也不要询问 API 密钥。
2. 没有 VideoDB 工具，但可以使用 shell（Claude Code、Cowork，或任何能运行 Python 的 Agent）：用一句友好的话询问 VideoDB API 密钥（可在 https://console.videodb.io 免费获取，含 $20 额度，无需银行卡）。用户通过聊天或其他方式提供密钥后，自行将其保存到项目的 .env 中，变量名为 VIDEO_DB_API_KEY，绝不要打印密钥，然后继续使用本文件末尾的 Python SDK 路径。在 Claude Code 中，也可以使用 /mcp，然后授权 videodb。
3. 没有 VideoDB 工具，也无法使用 shell：你正在使用 Claude 聊天。只回复以下内容，并根据请求调整：“尚未连接 VideoDB。请打开「设置」→「连接器」，找到 VideoDB，点击「连接」并登录（免费，无需银行卡）。然后再次发送此请求，我会接手处理。”不要在此处提及 API 密钥、.env、shell、Claude Code 或 /mcp；这些都不适用于聊天，而且粘贴到聊天中的密钥无法使用，因为这里不会运行代码。

与用户沟通时：回复中绝不要写「index」「indexed」或「indexing」。请说「可搜索」（「现在可以根据说过的话和画面内容进行搜索」），并使用「转录」，而不要提及任务名称。一次只发送一行状态信息，然后给出结果。

长时间运行的任务会返回 status: processing。回复中会包含 output_url，并指出要轮询的工具（poll_with；较旧的服务端使用 retry_with）。使用该工具并传入 output_url，直到状态变为 done；连续收到多次 processing 回复是正常的（上传 10 分钟的 YouTube 视频大约需要五分钟），如果 done 回复中的结果为空，再轮询一次。绝不要重新运行写入操作，否则会启动第二个任务。

使用连接器工具

获取视频。 首先调用 search_videos_by_title(query)；如果视频已在账户中，则重复使用 m- ID。否则，对于 YouTube 链接或公开 URL，调用 upload_media(url) 并轮询，直到状态变为 done；记下 m- ID。连接器无法处理本地文件；用户需在 https://console.videodb.io 上传文件并分享 m- ID。

转录。 调用 generate_transcript(media_id)（如果语音不是英语，则添加 language_code），并轮询，直到状态变为 done；然后调用 get_transcript(media_id, timestamped=true, segmenter="sentence") 获取句子级时间戳，或设置 timestamped=false 获取纯文本。默认分段器按每个词生成一个片段，带时间戳的输出最多包含 2000 个片段，因此处理较长的媒体时，请传入 segmenter="sentence"，或指定 start 和 end。转录任务结果还包含文本和词列表，但该列表会被截断；请使用 get_transcript 读取转录内容。

将字幕嵌入视频。

1. 调用 generate_transcript(media_id) 并轮询，直到状态变为 done（如果视频已有转录，则会立即完成）。add_subtitles 会读取视频的转录内容；通过 understand_video 运行 spoken_words 分析器也可以。旧版 v1 调用 index_spoken_words，无需使用。
2. 调用 add_subtitles(video_id, ...)。该调用会立即返回 stream_url 和 player_url；它不是一个任务。
3. 获取 MP4 文件：调用 download_stream(stream_url, name="...")，并轮询，然后分享下载链接。

add_subtitles 的样式选项：font_name、font_size（8 到 72，默认值为 18）、bold、italic、alignment（默认值为 bottom_center，还可选 top_center、middle_center 等）、border_style（outline、opaque_box 或 no_border）、outline、outline_colour、shadow、margin_l、margin_r、margin_v。颜色使用 ASS 格式 &HAABBGGRR：不透明白色 &H00FFFFFF、黑色 &H00000000、黄色 &H0000FFFF。“黑底白字”设置为 primary_colour="&H00FFFFFF", back_colour="&H00000000", border_style="opaque_box"。

动画字幕、卡拉 OK 字幕，或合成视频中的字幕。 使用 video-edit 技能中的 render_timeline，并添加 caption 资源（src: "auto"、animation: "karaoke"）。视频必须已完成转录（调用 generate_transcript，或运行 spoken_words 分析器），否则渲染结果将没有字幕，也不会报错。

翻译。 调用 translate_transcript(video_id, language="Spanish")，即可返回翻译后的带时间戳片段。将这些片段以文本或 SRT 风格列表的形式提供给用户。

配音和翻译配音。 连接器不支持此功能。在 Claude Code 中，SDK 可以实现此功能（${CLAUDE_PLUGIN_ROOT}/python/reference/editor.md 的配音部分）。在聊天中，请提供翻译后的转录文本，并说明配音需要使用 SDK。

使用 Python SDK（Claude Code）

如果 import videodb 失败，请先运行 /videodb:setup 完成设置。完整参考文档：${CLAUDE_PLUGIN_ROOT}/python/SKILL.md。

from dotenv import load_dotenv; load_dotenv(".env")
import videodb
from videodb import SubtitleStyle, SubtitleAlignment, SubtitleBorderStyle
conn = videodb.connect(); coll = conn.get_collection()
video = coll.upload(url="https://www.youtube.com/watch?v=VIDEO_ID")
video.generate_transcript()
print(video.get_transcript_text())
stream_url = video.add_subtitle(SubtitleStyle(font_size=20, primary_colour="&H00FFFFFF",
                                              back_colour="&H00000000", border_style=SubtitleBorderStyle.opaque_box,
                                              alignment=SubtitleAlignment.bottom_center))
print(f"https://console.videodb.io/player?url={stream_url}")