将本地视频或用户有权处理的在线视频，经过来源获取、文字稿定位、选题选句、精确取帧、紧凑裁切、拼图和逐张质检，制作成 3:4 或保留画面原比例的视频字幕长图。支持两种明确分开的输出：保留画面内已烧录字幕的原生字幕模式，以及把已审核的时间点与台词绘制到真实视频帧上的脚本字幕模式。用户要求原生字幕截图、字幕帧拼图、YouTube 金句长图、台词截图、不重绘字幕、自定义中文台词，或调整主图比例、字幕区域、
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add chengyi-ai/native-subtitle-quote-image --skill native-subtitle-quote-image -a cursor -y
将本地视频或用户有权处理的在线视频，经过来源获取、文字稿定位、选题选句、精确取帧、紧凑裁切、拼图和逐张质检，制作成 3:4 或保留画面原比例的视频字幕长图。支持两种明确分开的输出：保留画面内已烧录字幕的原生字幕模式，以及把已审核的时间点与台词绘制到真实视频帧上的脚本字幕模式。用户要求原生字幕截图、字幕帧拼图、YouTube 金句长图、台词截图、不重绘字幕、自定义中文台词，或调整主图比例、字幕区域、台词间隔和美感时使用。
将本地视频或用户有权处理的在线视频，经过来源获取、文字稿定位、选题选句、精确取帧、紧凑裁切、拼图和逐张质检，制作成 3:4 或保留画面原比例的视频字幕长图。支持两种明确分开的输出：保留画面内已烧录字幕的原生字幕模式，以及把已审核的时间点与台词绘制到真实视频帧上的脚本字幕模式。用户要求原生字幕截图、字幕帧拼图、YouTube 金句长图、台词截图、不重绘字幕、自定义中文台词，或调整主图比例、字幕区域、台词间隔和美感时使用。
先确认用户想要的字幕模式，再判断素材是否支持。不要把两种模式混为一种，也不要默默从原生字幕切到绘制字幕。
如果用户没有明确指定模式，先用用户当前使用的语言询问，并简短说明两种选择。中文提问可直接使用：
您当前是选择原生字幕还是脚本字幕？原生字幕会保留视频画面里已有的字幕，不重绘文字；脚本字幕会把您确认过的台词或翻译后期绘制到真实视频帧上，并标明是后期字幕。
用户已明确说“原生字幕”“保留画面原字幕”“不重绘字幕”，或“脚本字幕”“把指定台词/翻译绘制到画面上”时，按其选择继续，不重复询问。用户尚未选择时，可以只读检查素材以说明哪种模式可行，但不要执行模式专属的渲染；等用户选择后再继续。若所选模式与素材不匹配，说明具体原因并征求用户是否改选，不能自行切换。
每个新任务开始、处理素材之前运行一次：
python3 "<SKILL_DIR>/scripts/check_update.py" --json
VERSION 读取本地版本，只访问本项目的 GitHub Latest Release；默认 24 小时内复用一次缓存。update_available 时，用一句话告诉用户当前版本、最新版本和 Release 链接，然后继续当前任务。只提醒，不自动更新、不覆盖本地 Skill。up_to_date 时无需打扰用户。结果为 unavailable 时也不要阻塞当前任务；若只是运行环境禁止联网，可申请对 GitHub API 的只读访问并用 --force 重试一次，未获授权就继续任务。| 条件 | 模式 | 成品文字来源 | 命令 |
|---|---|---|---|
| 关闭播放器 CC 后，截图里仍有字幕；用户要求保留原字幕 | 原生字幕模式 | 视频画面像素 | render |
| 视频没有需要的烧录字幕，但用户要求把经确认的台词、翻译或观点排成案例风格 | 脚本字幕模式 | 已审核 JSON 中的 text | render-script |
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 时缩减语言并放慢请求，都不要无限重试。将 <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。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。sample / band / render / render-script 加 --tmp-dir <可写目录>，或设置环境变量 NSQI_TMP_DIR（参数优先）；默认仍用系统临时目录。目录不存在或不可写会直接报错，抽帧临时文件用完即删。render 默认遇到失败就中止。需要容错时加 --keep-going：单张失败不影响其余，结束时输出失败清单（序号、时间点、原因）并写入 渲染失败报告.json，退出码非零且不生成总览图。向用户报告失败清单，修正 manifest 后加 --resume 只补渲缺失或损坏的卡；已有效的图即使 manifest 改了也不会重渲（要重渲先删掉对应图），总览图和时间点文件会重新生成。sample 核对画面并向用户说明；不要为了出图直接加 --allow-duplicate-frames，只有用户确认确实需要时才加。“人物原比例 / 不裁横屏 / 原生尺寸”是画面几何要求，不等于选择原生字幕模式。字幕来源仍按用户的选择处理。
--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 只是裁切示例，不是所有视频的默认值。
确认本地视频或 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
一张图只表达一个连贯观点。候选句需要语义递进，并且每个时间点都能回到视频验证。避免空字幕、同句重复、字幕切换残影、转场、黑帧、广告贴片、播放器 UI 和人物闭眼。
主图（每张图的第一个时间点）由你来选，渲染器不识别人脸、也不自动挑帧，manifest 或 lines JSON 写的是哪个时间点就用哪一帧：
sample -t 时间点 --around 0.8 回看前后画面，确认主体是说这句话的人、构图完整、没有闭眼或动作模糊。references/visual-style.md 的「主图构图检查清单」逐张目测：头顶不被切、上方留白约 ≥8%；下巴离主图下缘（第一条字幕条上沿）约 ≥5%；脸中心大致在主图高度 35–60%、宽度 35–65%。固定比例 --fit crop 时按裁切后的成品判断。不达标先用 sample 视频 --start T-1.5 --end T+1.5 --interval 0.3（T 为原时间点秒数，start 不小于 0、end 不超过视频时长）在前后约 1.5 秒内重找；仍找不到时用最好的一帧，并在交付时写明哪张主图构图不达标、差在哪里。这些比例是目测参考，不是渲染器校验。sample 看整段有没有景别或动作变化，尽量为每张图挑不同的画面；源视频只有一个机位时，向用户说明这是素材限制。渲染器只按时间点顺序拼图，不识别谁在说话；字幕条只裁画面底部，读者会默认整张图都是主画面人物说的。访谈、播客、对谈、辩论等多人素材必须先做说话人区分，再选句：
sample -t ... --around 0.8 回看画面（口型、机位、画面内名牌）确认。无法确认归属的句子不用。speaker 并用 --speaker-prefix on-change 在画面上标出（见 4B）。单行字幕从 0.78–0.96 开始；两行字幕或位置偏高时，先预览再扩大到例如 0.62–0.96。
python3 "<SKILL_DIR>/scripts/native_subtitle_stitch.py" band VIDEO -t 61.2 \
--band-top 0.78 --band-bottom 0.96 --out band-preview.jpg
{
"images": [
{
"title": "模型独立工作时长正在快速增长",
"times": [61.6, 69.3, 75.0, 82.4, 88.8]
}
]
}
python3 "<SKILL_DIR>/scripts/native_subtitle_stitch.py" render VIDEO \
--manifest manifest.json --out-dir OUTPUT_DIR \
--band-top 0.78 --band-bottom 0.96
title 只用于文件名，不画进图片。times 必须来自已回看的稳定帧。输出包含逐张 JPG、原生字幕时间点.json 和 final_contact_sheet.jpg。
{
"lines": [
{"t": 61.6, "text": "第一句已核对台词"},
{"t": 69.3, "text": "第二句已核对台词"},
{"t": 75.0, "text": "第三句已核对台词"},
{"t": 82.4, "text": "第四句已核对台词"},
{"t": 88.8, "text": "第五句已核对台词"}
]
}
t 必须严格递增且小于视频时长。text 必须是已核对的单行台词；过长时拆句，不靠极小字号硬塞。python3 "<SKILL_DIR>/scripts/native_subtitle_stitch.py" render-script VIDEO \
--script script.json --out OUTPUT.jpg \
--aspect 3:4 --width 1440
可选六句卡（脚本字幕）：准备 6 句已核对、时间点严格递增的 script.json，然后运行：
python3 "<SKILL_DIR>/scripts/native_subtitle_stitch.py" render-script VIDEO \
--script script.json --out six-line.jpg \
--six-line-card --aspect 3:4 --width 1080
此预设默认在源画面高度的 60% 处取字幕条；必要时仍可用 --band-center 调整。它不接受 --hero-fraction，因为主画面高度由五条连续字幕条反推。--six-line-card 仅影响后期绘制的脚本字幕，不改变原生字幕模式。
可选说话人前缀（仅脚本字幕）：经用户确认的问答、对谈图，在每句加 speaker，说话人写在这里，不写进 text：
{"lines": [
{"t": 37.2, "speaker": "主持人", "text": "在这么竞争激烈的行业里，"},
{"t": 38.8, "speaker": "主持人", "text": "你觉得是什么让你脱颖而出？"},
{"t": 44.0, "speaker": "王薇薇", "text": "说实话，我觉得是运气。"}
]}
python3 "<SKILL_DIR>/scripts/native_subtitle_stitch.py" render-script VIDEO \
--script script.json --out qa.jpg --speaker-prefix on-change
--speaker-prefix none（默认）不画前缀；on-change 只在换人时画，推荐用于问答；every 每句都画，画面较挤，只在用户要求时用。speaker；前缀比台词小一号、用强调色，字号不随台词缩小，台词放不下时只缩台词。可选金句强调（仅脚本模式）：--emphasize-line last（最后一句）或 --emphasize-line N（从 1 起算）给一句台词加暖色、加粗描边和轻微半透明底衬；也可在 script.json 某句写 "emphasis": true。默认不启用，输出不变；行号越界会报错。仍属后期绘制，需按脚本模式标注；原生模式不支持，不得重绘原字幕。图内不绘制卡片小标题，本 Skill 无此功能。
脚本会尝试 macOS、Windows 和 Linux 常见 CJK 字体；台词含谚文时优先尝试韩文字体（macOS AppleSDGothicNeo、Windows Malgun Gothic），--font 始终最优先。无法自动找到时，用 --font /path/to/font.ttc 指定已获授权的字体。需要调整字幕条在原帧中的垂直采样位置时，使用 --band-center；不要把它当作行距参数。
先看缩略总览，再打开每张原尺寸 JPG。
--speaker-prefix 时，画面前缀与 JSON 的 speaker 一致，并且台词字号没有因前缀明显变小。--fit crop 的成品要逐张确认每句字幕两端完整、人物没有被两侧裁切切脸，并在交付中说明渲染输出的裁切或留边结果。脚本固定布局默认四条时主图约占 68–72%；内容块之间没有额外间距。发现问题时只调整对应变量：时间点通常移动 0.3–1.5 秒；原生字幕被裁时调整 band 边界；台词条太高时先恢复自动布局；文字过长时先拆句。连续三轮仍找不到稳定画面时，换片段或报告限制，不无限微调。
yt-dlp：获取用户有权处理的在线视频、元数据和字幕轨；不负责最终渲染。复用上游已经下载的视频、文字稿和缓存，不重复消耗网络或转写成本。不假设用户一定安装了某个命名 Skill；缺少上游 Skill 时，自行完成最低限度的文字稿阅读和主题选择。
登录、年龄验证、机器人验证或用户自己的非公开视频需要 Cookies 时，必须先取得授权；授权后优先让 yt-dlp 通过 --cookies-from-browser chrome 临时读取用户自己的已登录会话，而不是让用户粘贴密码或导出 Cookie 文件。不得把浏览器数据写入仓库。
提供输出路径、逐张成品、时间点/lines JSON、总览图与已完成的视觉和技术检查。明确标记使用的字幕模式。只有用户需要分享包时再生成 ZIP；不得把未逐张打开检查的图片报告为完成。