/native-subtitle-quote-image

name: native-subtitle-quote-image
description: 将本地视频或用户有权处理的在线视频，经过来源获取、文字稿定位、选题选句、精确取帧、紧凑裁切、拼图和逐张质检，制作成 3:4 或保留画面原比例的视频字幕长图。支持两种明确分开的输出：保留画面内已烧录字幕的原生字幕模式，以及把已审核的时间点与台词绘制到真实视频帧上的脚本字幕模式。用户要求原生字幕截图、字幕帧拼图、YouTube 金句长图、台词截图、不重绘字幕、自定义中文台词，或调整主图比例、字幕区域、台词间隔和美感时使用。

视频字幕拼图

先确认用户想要的字幕模式，再判断素材是否支持。不要把两种模式混为一种，也不要默默从原生字幕切到绘制字幕。

开始时确认模式

如果用户没有明确指定模式，先用用户当前使用的语言询问，并简短说明两种选择。中文提问可直接使用：

> 您当前是选择原生字幕还是脚本字幕？原生字幕会保留视频画面里已有的字幕，不重绘文字；脚本字幕会把您确认过的台词或翻译后期绘制到真实视频帧上，并标明是后期字幕。

用户已明确说“原生字幕”“保留画面原字幕”“不重绘字幕”，或“脚本字幕”“把指定台词/翻译绘制到画面上”时，按其选择继续，不重复询问。用户尚未选择时，可以只读检查素材以说明哪种模式可行，但不要执行模式专属的渲染；等用户选择后再继续。若所选模式与素材不匹配，说明具体原因并征求用户是否改选，不能自行切换。

非阻塞版本检查

每个新任务开始、处理素材之前运行一次：

python3 "<SKILL_DIR>/scripts/check_update.py" --json

• 脚本从 Skill 内的 `VERSION` 读取本地版本，只访问本项目的 GitHub Latest Release；默认 24 小时内复用一次缓存。
• 结果为 `update_available` 时，用一句话告诉用户当前版本、最新版本和 Release 链接，然后继续当前任务。只提醒，不自动更新、不覆盖本地 Skill。
• 结果为 `up_to_date` 时无需打扰用户。结果为 `unavailable` 时也不要阻塞当前任务；若只是运行环境禁止联网，可申请对 GitHub API 的只读访问并用 `--force` 重试一次，未获授权就继续任务。
• 缓存只包含检查时间、最新版本号和 Release 链接，不写入仓库，也不记录账号、素材或使用行为。

模式路由

| 条件 | 模式 | 成品文字来源 | 命令 | |---|---|---|---| | 关闭播放器 CC 后，截图里仍有字幕；用户要求保留原字幕 | **原生字幕模式** | 视频画面像素 | `render` | | 视频没有需要的烧录字幕，但用户要求把经确认的台词、翻译或观点排成案例风格 | **脚本字幕模式** | 已审核 JSON 中的 `text` | `render-script` |

• 原生模式不得 OCR 后重绘、翻译、改写或覆盖字幕。
• 脚本模式必须明确称为“脚本字幕”或“后期绘制字幕”，不得宣称文字是画面原字幕。
• 脚本台词必须能回到原视频、用户稿件或其他明确来源复核；不编造人名、数据、引语或翻译含义。
• 用户只说“保留原字幕”时，不能因为原字幕难处理就转脚本模式。

按任务读参考文件

• **YouTube 等 URL**：先读 [references/yt-dlp-and-transcripts.md](references/yt-dlp-and-transcripts.md)，获取用户有权处理的视频、元数据和辅助时间轴。URL 任务不能在一次公开请求失败后直接退回“只支持本地视频”：若 YouTube 返回机器人登录验证、年龄验证或用户自己的非公开视频限制，先说明原因并取得授权，再按参考文件用 `yt-dlp --cookies-from-browser chrome` 继续。字幕和视频分两条命令下载；下载前用 `yt-dlp -F` 枚举变体并按 AV1 → VP9 → H.264 择优，下载后必须运行 `native_subtitle_stitch.py check-source VIDEO --min-height 720`（解码前 N 秒无错误、分辨率达标）才能继续；视频报 HTTP 403 或自检失败时按参考文件的格式回退表逐级换变体，低于 720p 的级别须先征得用户确认，每次尝试记入 `download-attempts.log`；字幕报 429 时缩减语言并放慢请求，都不要无限重试。
• **读长视频 → 选题 → 写文章/帖子 → 配图**：读 [references/end-to-end-workflow.md](references/end-to-end-workflow.md)。
• **台词条太高、间隔太宽、缺少美感**：读 [references/visual-style.md](references/visual-style.md)。
• **报错、出图异常或结果不对**：先查 [references/troubleshooting.md](references/troubleshooting.md)，按「症状 → 先查什么 → 怎么处理」逐项排查。
• **本地短视频且时间点已确定**：直接执行下面的核心流程。

环境与路径

将 `<SKILL_DIR>` 解析为当前 `SKILL.md` 所在目录的绝对路径；不要假设 Agent 的工作目录就是 Skill 目录。

# 本地原生字幕
python3 "<SKILL_DIR>/scripts/check_environment.py"

# 中日韩脚本字幕
python3 "<SKILL_DIR>/scripts/check_environment.py" --script-mode

# URL + 脚本字幕
python3 "<SKILL_DIR>/scripts/check_environment.py" --url-mode --script-mode

核心依赖为 Python 3.10+、Pillow，以及 FFmpeg 或 `imageio-ffmpeg`。URL 模式另需 `yt-dlp` 和 YouTube 完整解析所需的 JavaScript runtime。环境检查只报告状态；缺失时先说明用途并取得授权，再运行：

python3 -m pip install -r "<SKILL_DIR>/requirements.txt"

不擅自修改系统 Python、shell 配置、浏览器 Cookies 或包管理器。Chrome Cookie 只是在无 Cookie 请求被 YouTube 登录验证拦截后的受控恢复路径；首次读取前必须说明用途并取得用户授权。

共同的默认版式

• 原生字幕默认使用内容自适应布局：保留源宽度，高度为主图和字幕条之和，整图统一等比缩放。用户未指定比例时，不主动添加 `--aspect 3:4`。
• 脚本字幕默认输出 3:4、1440×1920。
• 默认使用 5 个严格递增的时间点：第一帧是主画面，其余四帧是字幕条。
• 两种模式每张图最多 7 个时间点（1 个主画面 + 6 个字幕条）；台词更多时拆成多张图，不压缩字幕条。
• 脚本固定布局的 4 个字幕条时，主画面约占 70%，每条约占 7.5%。原生模式不强制这个比例，第一句和后续字幕必须保持同一缩放倍数；原视频字号不同则保留差异，不重绘文字。两种模式条间距都为 0。
• 可选 `render-script --six-line-card` 使用 6 个严格递增的时间点：首句画在主画面底部，其余 5 句各占连续字幕条；固定 3:4 布局，1080×1440 时主画面 870px、每条 114px，六句行距一致。原版默认布局不变。
• 原生模式显式 `--aspect 3:4` 或 `--layout fixed` 时，默认 `--fit crop`：自动识别每句字幕左右边界，对整张拼图统一裁去两侧，最多裁到字幕安全边界，剩余差额留黑边；任一句识别不到字幕边界时不裁切、整图留边。人物偏离中心时用 `--crop-center`（0–1）移动裁切窗口；用户要求不裁画面时用 `--fit pad`。不得单独放大主图来填满。`--hero-fraction` 只调整源主图裁切高度，受真实帧高度限制，不保证占最终含边画布的该比例。脚本模式只有自动布局确实不适用时才传它。
• 不覆盖已有成品。只有用户明确要替换时才添加 `--overwrite`。
• 受限环境（沙箱、企业策略）下系统 Temp 不可写时，给 `sample` / `band` / `render` / `render-script` 加 `--tmp-dir <可写目录>`，或设置环境变量 `NSQI_TMP_DIR`（参数优先）；默认仍用系统临时目录。目录不存在或不可写会直接报错，抽帧临时文件用完即删。
• 批量 `render` 默认遇到失败就中止。需要容错时加 `--keep-going`：单张失败不影响其余，结束时输出失败清单（序号、时间点、原因）并写入 `渲染失败报告.json`，退出码非零且不生成总览图。向用户报告失败清单，修正 manifest 后加 `--resume` 只补渲缺失或损坏的卡；已有效的图即使 manifest 改了也不会重渲（要重渲先删掉对应图），总览图和时间点文件会重新生成。
• 渲染器遇到重复画面会中止：所有时间点画面几乎相同（疑似静态封面视频或画面冻结），或原生模式相邻字幕条几乎相同。先用 `sample` 核对画面并向用户说明；不要为了出图直接加 `--allow-duplicate-frames`，只有用户确认确实需要时才加。
• 源视频低清时可输出 1440×1920 版面，但必须说明这不等于真实清晰度提升。

保留画面原比例

“人物原比例 / 不裁横屏 / 原生尺寸”是画面几何要求，不等于选择原生字幕模式。字幕来源仍按用户的选择处理。

• 用户要求保留完整横屏构图时使用 `--layout natural`：保留源宽度，高度按主画面与字幕条相加；不再强制 3:4。
• 不传 `--width` 时保留源宽度；传入宽度时仅等比缩放。裁切后禁止把画面 resize 回原来的宽高，也禁止把成品直接拉成 1440×1920。
• 原生字幕模式保留从画面顶部到 `--band-bottom` 的主图和完整字幕条；不重绘文字。
• 脚本字幕模式可用 `--frame-top` / `--frame-bottom` 仅裁去不需要的源画面区域，默认保留全帧。先预览边界，不能裁掉人物关键部位；`--band-center` 相对裁切后的画面。
• `natural` 不与 `--aspect` / `--hero-fraction` 合用；70% 主图验收只适用于脚本固定布局。两种布局都不得非等比拉伸。
• 选源优先多机位、景别有变化的视频；固定单机位（大师课、网课式录制）是高风险素材，六张主图容易几乎一样。确需使用时可传 `--hero-zoom 1.0,0.9,0.95`（`render` 与 `render-script`）：逗号分隔的每卡主图缩放系数，范围 0.8–1.0，按卡循环，默认不启用且输出不变。它只裁掉更多主图画面再放大，不改字幕条、文字、条间距和 `--six-line-card` 几何；原生模式的裁切窗口不进入字幕条。源清晰度不足时主图会更模糊，不等于真实清晰度提升。`render-script` 只出一张图，取第一个系数。
• 缓解手机上的拥挤感可选 `--strip-gap N`（条间黑色呼吸缝，0–8px，默认 0）与 `--hero-divider line`（主图与字幕条之间插入 2px 细分隔线，默认 none），`render` 与 `render-script` 均支持。二者只新增背景像素，不覆盖或重绘任何画面，原生字幕仍只经历整图统一缩放；脚本固定画布总尺寸不变，字幕条相应变矮；与 `--six-line-card` 不兼容（固定几何）。

python3 "<SKILL_DIR>/scripts/native_subtitle_stitch.py" render-script VIDEO \
  --script script.json --out natural.jpg --layout natural \
  --frame-bottom 0.72

上例 `0.72` 只是裁切示例，不是所有视频的默认值。

共同前半流程

1. 检查来源与字幕类型

确认本地视频或 URL，素材使用权，视频时长、语言和目标图片数。用真实截图判断字幕是烧录字幕还是独立字幕轨，不能只看是否下载到 VTT/SRT。

时间点不明时，先生成候选帧总览：

python3 "<SKILL_DIR>/scripts/native_subtitle_stitch.py" sample VIDEO \
  --out candidate-contact-sheet.jpg

已有文字稿候选时间点时，围绕每个点生成前、中、后三帧：

python3 "<SKILL_DIR>/scripts/native_subtitle_stitch.py" sample VIDEO \
  -t 61.2 -t 68.9 -t 74.5 -t 82.0 -t 88.4 \
  --around 0.8 --out focused-candidates.jpg

2. 选主题与稳定帧

一张图只表达一个连贯观点。候选句需要语义递进，并且每个时间点都能回到视频验证。避免空字幕、同句重复、字幕切换残影、转场、黑帧、广告贴片、播放器 UI 和人物闭眼。

主图（每张图的第一个时间点）由你来选，渲染器不识别人脸、也不自动挑帧，manifest 或 `lines` JSON 写的是哪个时间