Video subtitle snapshot

视频字幕截图

把本地、B站或抖音视频的指定片段制作成一张 PNG：顶部是开始时刻的完整画面，下方按时间顺序拼接去重后的字幕条。内置 CLI 负责确定性媒体处理，Agent 负责定位字幕和 OCR。支持 macOS、Windows，并兼容常见 Linux。

安全要求

处理网络链接、安装依赖、使用 Cookie 或读取不熟悉的本地文件前，先阅读 references/permissions.md。

• 只处理用户有权使用的内容。
• 本地视频模式保持离线，不得访问网络，也不得要求 yt-dlp 或浏览器。
• B站模式默认匿名访问。
• 抖音通过移动分享页解析临时播放地址；抖音不需要浏览器，不得保存或输出临时 CDN 地址。
• 向 yt-dlp 传递浏览器名称或 Cookie 文件前，必须获得用户单独的明确授权。不得查看、复制、打印、上传或保留 Cookie 值。
• Cookie 参数只适用于 B站；本地或抖音输入不得使用 Cookie 参数。
• 不得绕过会员、DRM、地域、登录、版权或其他访问限制。

处理流程

在本 Skill 目录中运行命令。下列 <PYTHON> 在 macOS/Linux 替换为 .venv/bin/python，在 Windows 替换为 .venv\Scripts\python。

1. 按输入来源检查依赖：

   <PYTHON> scripts/video_subtitle_snapshot.py doctor \
     --input "VIDEO_PATH_OR_SHARE_TEXT_OR_URL" --json
   

   doctor --json 检查全部依赖，doctor --input ... --json 只检查当前来源。B站额外需要 yt-dlp，本地和抖音不需要。缺少依赖时阅读 references/environment.md，向用户说明安装内容、用途和命令；安装前必须获得用户同意。安装后重新检查。

2. 只获取指定区间。省略 --work-dir 以创建独立任务目录，并从 JSON 中读取 work_dir：

   <PYTHON> scripts/video_subtitle_snapshot.py acquire \
     --input "VIDEO_PATH_OR_SHARE_TEXT_OR_URL" --start "01:15:55" \
     --duration 13 --json
   

   支持本地路径、B站完整链接或 b23 分享文本、抖音完整链接或 App 分享文本。只有 B站且获得单独授权后，才能添加 --cookies-from-browser chrome 或 --cookies-file PATH。不得猜测浏览器；认证失败不得静默降级；区间下载失败不得下载整部视频。

3. 提取候选帧：

   <PYTHON> scripts/video_subtitle_snapshot.py prepare \
     --work-dir "TASK_DIR" --step 0.5 --pixel-threshold 10 --json
   

4. 读取 manifest.json。按 diff 从高到低选择两到三张完整候选帧，不要机械选择首、中、尾帧。让视觉模型返回字幕文字及文字像素的上下边缘 y 坐标，取有效结果中最小的上边缘和最大的下边缘：

   <PYTHON> scripts/video_subtitle_snapshot.py crop \
     --work-dir "TASK_DIR" --text-top TOP --text-bottom BOTTOM \
     --padding 24 --json
   

5. 对 main_sub.png 和 cropped/ 执行 OCR，每批最多五张。保持时间顺序，跳过空结果、“无字幕”、与主画面相同的文字及后续完全重复项；不得改写或翻译。只使用已知文件名：

   {"main_text":"","keep":[{"file":"strip_01_2.0s.png","text":"字幕"}]}
   

   保存为 TASK_DIR/ocr_results.json。

6. 拼接图片，不得覆盖已有输出：

   <PYTHON> scripts/video_subtitle_snapshot.py stitch \
     --work-dir "TASK_DIR" --output "/path/result.png" --json
   

交付 PNG，并根据 manifest 报告实际分辨率、格式 ID 和认证模式。可以询问是否清理，但只能删除本次返回的精确任务目录。

错误处理

错误代码	处理方式
DEPENDENCY_MISSING	说明缺少的依赖并请求安装许可。
AUTHORIZATION_REQUIRED	询问用户等待后重试，或明确授权一种 Cookie 来源。
SECTION_DOWNLOAD_UNAVAILABLE	报告失败，不得改为获取整部视频。
DOUYIN_PARSE_FAILED	内置短重试后仍失败，报告抖音页面结构或作品类型不受支持，不得改用浏览器抓取。
DOUYIN_DOWNLOAD_FAILED	内置短重试后仍失败，重新执行 acquire 以刷新临时地址；仍失败则报告，不得输出签名 URL。
INVALID_CROP	重新识别文字边缘，不得猜测或手动钳制坐标。
INVALID_OCR_RESULTS	修正 JSON 或文件名，不得静默跳过。
OUTPUT_EXISTS	请用户提供新路径，或明确要求覆盖。

项目链接

• 免安装 Web 版：https://shot.o9k.cn
• 开源源码：https://github.com/CoderAha/video-subtitle-snapshot

开源许可

采用 Apache-2.0，发布 ZIP 内包含 LICENSE。