chengyi-ai/native-subtitle-quote-image

把真实视频帧，做成保留原字幕或绘制台词的长图
_{原生字幕不重绘 · 脚本字幕不冒充原字幕}

快速开始  ·  了解能力  ·  成品案例  ·  两种模式  ·  English  ·  한국어

• 从视频直接出图：本地文件或 YouTube 链接进来，经过找句子、精确取帧、拼图、逐张质检，输出原生或脚本字幕 JPG，可按内容布局或指定比例。
• 两种字幕，从不混用：原生模式只裁切画面里本来就有的字幕；脚本模式把你审核过的台词画到真实画面上，并标明是后期字幕。
• 版式紧凑：原生字幕先拼源像素，再统一缩放，第一句不会被单独放大；脚本固定布局的主图约占 70%。字幕条之间没有空隙。
• Agent 能用，脚本也能单独跑：在 Codex、Claude Code 等 Agent 里用一句话调用；也可以直接运行 Python 脚本。

本页只展示中文字幕作品，均为 3:4、5 句。英文和韩文作品分别在 English 与 한국어 README 中。点击图片查看原图。

《大巴上的女孩》 原生字幕 · 生命属于你自己

里克·鲁宾 脚本字幕 · 创意像一片变化的云

陈数 脚本字幕 · 工作投入，生活简单

• 原生字幕：第一张的字幕是视频里已烧录的非官方中英双语字幕（随 Bilibili 搬运版烧录在画面里），直接从画面像素裁切，未识别、未重绘；左上角是原视频平台的水印。
• 脚本字幕：后两张的中文是后期绘制的整理或翻译台词，不是视频原字幕，也不作为人物的逐字引语。

查看来源、台词与时间点

1. 安装 Skill

git clone https://github.com/chengyi-ai/native-subtitle-quote-image.git
cd native-subtitle-quote-image
mkdir -p ~/.codex/skills && cp -R skills/native-subtitle-quote-image ~/.codex/skills/

Windows PowerShell：

New-Item -ItemType Directory -Force "$HOME\.codex\skills" | Out-Null
Copy-Item -Recurse skills\native-subtitle-quote-image "$HOME\.codex\skills\"

升级时请先删除旧目录再复制，否则新版本已删除的旧文件会残留（Claude Code 把 .codex 换成 .claude）：

rm -rf ~/.codex/skills/native-subtitle-quote-image

Remove-Item -Recurse -Force "$HOME\.codex\skills\native-subtitle-quote-image"

mkdir -p ~/.claude/skills && cp -R skills/native-subtitle-quote-image ~/.claude/skills/

New-Item -ItemType Directory -Force "$HOME\.claude\skills" | Out-Null
Copy-Item -Recurse skills\native-subtitle-quote-image "$HOME\.claude\skills\"

https://github.com/chengyi-ai/native-subtitle-quote-image/tree/main/skills/native-subtitle-quote-image

2. 安装依赖并自检

python3 -m pip install -r skills/native-subtitle-quote-image/requirements.txt
python3 skills/native-subtitle-quote-image/scripts/check_environment.py

要处理 YouTube 链接，再装 yt-dlp：

python3 -m pip install -U "yt-dlp[default]"
python3 skills/native-subtitle-quote-image/scripts/check_environment.py --url-mode

要画中日韩台词，用 --script-mode 检查字体。环境自检是只读的，不会自动安装或修改任何软件；缺组件时，Agent 会先说明用途，征得你同意再装。

3. 重开一个 Agent 任务，说一句话

使用 $native-subtitle-quote-image，把这个带内嵌中文字幕的视频做成原生字幕拼图。

如果你没有指定模式，Agent 会先问“您当前是选择原生字幕还是脚本字幕？”，并用一句话解释两者区别，再按你的选择处理。

flowchart LR
  A[本地视频<br>或 YouTube 链接] --> B[获取视频<br>与字幕轨]
  B --> C[检查真实帧<br>区分烧录字幕]
  C --> D[按文字稿<br>选题选句]
  D --> E{锁定模式}
  E -->|原生| F[裁切画面<br>里的字幕条]
  E -->|脚本| G[绘制已<br>审核台词]
  F --> H[按模式渲染<br>逐张质检]
  G --> H

Skill 支持三种工作方式：

1. 本地成片：直接从本地视频选句、取帧、出图，不需要 yt-dlp。
2. URL 完整流程：用 yt-dlp 获取你有权处理的视频、元数据和辅助字幕轨，再决定字幕模式。
3. 内容生产：读视频、选题、写文章或帖子，最后配字幕截图。其他内容类 Skill 负责上游，本 Skill 负责时间点、真实画面、字幕来源标识和质检。

Agent 会先检查来源、字幕类型和候选帧，确定模式后再生成：

• 逐张 JPG，比例符合所选布局；
• 原生模式的 原生字幕时间点.json，或脚本模式的 lines JSON；
• 多图任务的 final_contact_sheet.jpg 总览图。

不经过 Agent 也可以直接跑脚本。下面的 VIDEO 换成你的视频路径。

自检来源：下载后先检查分辨率并解码前 10 秒，坏流或低清在抽帧前就失败（不传 --min-height 时低于 720p 只警告）。

python3 skills/native-subtitle-quote-image/scripts/native_subtitle_stitch.py check-source VIDEO --min-height 720

挑帧：生成带时间点的候选帧总览，不用反复试时间点。

python3 skills/native-subtitle-quote-image/scripts/native_subtitle_stitch.py sample VIDEO \
  --start 30 --end 120 --interval 5 --out candidate-contact-sheet.jpg

不传 --start、--end 和 --interval 时，会在整段视频里均匀抽取最多 24 帧。已经知道大概时间点时，可以围绕每个点取前、中、后三帧，避开字幕切换的瞬间：

python3 skills/native-subtitle-quote-image/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

原生字幕：先用 band 确认字幕的裁切区域，再按 manifest 渲染一组成品。

python3 skills/native-subtitle-quote-image/scripts/native_subtitle_stitch.py band VIDEO \
  -t 61.2 --band-top 0.78 --band-bottom 0.96 --out band-preview.jpg

python3 skills/native-subtitle-quote-image/scripts/native_subtitle_stitch.py render VIDEO \
  --manifest manifest.json --out-dir output-v1 \
  --band-top 0.78 --band-bottom 0.96

脚本字幕：准备 script.json，然后渲染。

python3 skills/native-subtitle-quote-image/scripts/native_subtitle_stitch.py render-script VIDEO \
  --script script.json --out output.jpg --aspect 3:4 --width 1440

可选六句卡：script.json 中放 6 句已核对、时间点严格递增的台词。此预设在 1080×1440 画布上使用 870px 主画面和下方 5 条各 114px 的连续字幕条，首句与后五句等距；默认脚本布局不变。

python3 skills/native-subtitle-quote-image/scripts/native_subtitle_stitch.py render-script VIDEO \
  --script script.json --out six-line.jpg --six-line-card --aspect 3:4 --width 1080

--six-line-card 仅用于后期绘制的脚本字幕，不接受 --layout natural 或 --hero-fraction。字幕条默认从源画面高度的 60% 处取样，可用 --band-center 调整；仍须逐句核对来源和逐张检查画面。

固定机位源与 --hero-zoom：优先选多机位、景别有变化的视频；固定机位视频（大师课、网课式录制）是高风险素材，六张主图容易几乎一样。render 与 render-script 支持可选的 --hero-zoom 1.0,0.9,0.95：逗号分隔的每卡主图缩放系数，范围 0.8–1.0，按卡循环，默认不启用且输出不变。它只裁掉更多主图画面再放大，字幕条、文字、条间距和六句卡几何不变，原生模式的裁切窗口不会进入字幕条。因为是裁切后放大，源视频清晰度不足时主图会更模糊，不等于真实清晰度提升。render-script 只输出一张图，取第一个系数。

呼吸缝 --strip-gap 与分隔线 --hero-divider：render 与 render-script 支持可选的 --strip-gap N（字幕条之间插入 N 像素黑色缝隙，0–8，默认 0）和 --hero-divider line（主图与字幕条之间插入 2px 细分隔线，默认 none）。二者只新增背景像素，不覆盖、不重绘原画面，原生字幕仍只经历整图统一缩放；固定画布总尺寸不变，字幕条相应变矮；与 --six-line-card 不兼容。

可选说话人前缀：问答、对谈类脚本字幕图，可以在 script.json 每句加 "speaker": "主持人"，再加 --speaker-prefix on-change，只在换人时画出「主持人：」这类前缀；every 每句都画，none（默认）不画。前缀比台词小一号、用强调色，台词字号不会因为前缀而变小。说话人写在 speaker 字段里，不写进 text。

python3 skills/native-subtitle-quote-image/scripts/native_subtitle_stitch.py render-script VIDEO \
  --script script.json --out qa.jpg --speaker-prefix on-change

可选金句强调：脚本字幕图可用 --emphasize-line last（最后一句）或 --emphasize-line 3（第 3 句，从 1 起算）给一句台词加暖色、加粗描边和轻微半透明底衬，方便截图搬走；也可在 script.json 的某句写 "emphasis": true。默认不启用，输出不变；行号越界会报错。只用于脚本模式，原生字幕模式不会重绘任何字幕。

保留人物原比例与横屏构图（v2.2.0）：两种字幕模式都支持 --layout natural。不指定宽度时保留源宽度，图片高度按实际内容计算，不强制 3:4；指定 --width 也只做等比缩放。

# 原生字幕：保留画面像素，不重绘文字
python3 skills/native-subtitle-quote-image/scripts/native_subtitle_stitch.py render VIDEO \
  --manifest manifest.json --out-dir output-natural --layout natural

# 脚本字幕：仅裁去不需要的底部区域，不把剩余画面拉高
python3 skills/native-subtitle-quote-image/scripts/native_subtitle_stitch.py render-script VIDEO \
  --script script.json --out natural.jpg --layout natural --frame-bottom 0.72

0.72 是示例裁切边界，需按视频实测；默认 --frame-top 0 --frame-bottom 1 保留全帧。--band-center 相对裁切后的画面。原比例布局不与 --aspect / --hero-fraction 合用。“原比例”只描述画面几何，脚本字幕仍是后期绘制。

默认原生布局修正（v2.2.2）：render 不传布局或比例时，默认按内容计算高度、保留源宽度。明确加 --aspect 3:4 --width 1440 时仍输出 1440×1920，但对整张拼图统一等比缩放，保留完整字幕，不分别填满主图和字幕条（v2.2.2 用留黑边适配画布，v2.3.0 起默认先统一裁两侧，见下）。原生模式的 --hero-fraction 仅调整源主图裁切高度，受源帧限制；脚本字幕仍默认固定 3:4。输出比例不匹配时，不能用非等比 resize 硬改。

横屏视频出 3:4 少留黑边（v2.3.0）：原生 render 的固定画布默认 --fit crop：先自动识别每句字幕的左右边界，再对整张拼图统一裁去两侧，最多裁到字幕安全边界，剩余差额才留黑边。所有字幕仍是同一缩放倍数；任何一句识别不到字幕边界时不裁切，退回整图留边。人物偏左或偏右时，用 --crop-center 0.4 这类数值移动裁切窗口，窗口始终包含全部字幕。想要 v2.2.2 的纯留边效果，加 --fit pad。裁切后仍要逐张检查字幕两端是否完整。

{
  "lines": [
    {"t": 61.6, "text": "第一句已核对台词"},
    {"t": 69.3, "text": "第二句已核对台词"},
    {"t": 75.0, "text": "第三句已核对台词"},
    {"t": 82.4, "text": "第四句已核对台词"},
    {"t": 88.8, "text": "第五句已核对台词"}
  ]
}

几条默认行为：

• 两种渲染器都会根据字幕条数自动调整主图比例，详见紧凑型视觉规范。
• 原生单行字幕默认从视频高度的 0.78–0.96 区域开始预览。
• 每张图最多 7 个时间点（1 个主画面 + 6 个字幕条），两种模式相同；台词更多时拆成多张图。
• 默认不覆盖已有图片；确实要替换时加 --overwrite。
• 受限环境下系统临时目录没有写权限时，加 --tmp-dir <可写目录>（或设置环境变量 NSQI_TMP_DIR，参数优先）指定抽帧临时文件位置；不指定则沿用系统临时目录，目录不存在或不可写会明确报错。
• 批量 render 默认遇到失败就中止；加 --keep-going 则单张失败不影响其余，结束时输出失败清单（第几张、时间点、原因）并写入输出目录的 渲染失败报告.json，退出码非零。修正后加 --resume 只补渲缺失或损坏的图；已有效的图即使 manifest 改了也不会重渲，总览图和时间点文件会重新生成。
• 出图前会检查重复画面：所有时间点画面几乎相同（例如源视频只是一张静态封面图），或原生模式相邻两条字幕条几乎相同时，直接报错、不出图。确认无误时加 --allow-duplicate-frames。
• 完整参数用 --help 查看。

素材优先用自己拍摄并加过字幕的视频、已获授权的素材，或明确允许再利用的公开视频。公开发布前，请再确认一遍素材使用权。

yt-dlp --cookies-from-browser chrome --js-runtimes node \
  --no-playlist --skip-download \
  --print "%(id)s | %(title)s | %(duration_string)s" \
  "URL"

python3 skills/native-subtitle-quote-image/scripts/check_update.py --json

python3 skills/native-subtitle-quote-image/scripts/check_update.py --force --verbose

python3 scripts/render_banners.py

python3 scripts/validate_repo.py
python3 -m unittest discover -s tests -v
python3 skills/native-subtitle-quote-image/scripts/check_environment.py
python3 skills/native-subtitle-quote-image/scripts/native_subtitle_stitch.py --help
python3 skills/native-subtitle-quote-image/scripts/native_subtitle_stitch.py render-script --help

深入文档

• URL 获取、yt-dlp、Deno/Node 与文字时间轴
• 从读视频、选题到交付的完整工作流
• 紧凑型主图、字幕条密度与视觉质检
• 排错手册：常见报错与出图问题的排查

欢迎在 Issues 提问题或建议，渲染问题请附上出问题那一页的截图；也可以在社交媒体上直接找作者反馈。新 issue 会由 Agent 自动评估可行性，符合条件的需求由 Agent 编码、测试并提交 PR，维护者审查合并后自动发版。完整流程见 Agent 工作流说明。

代码与 Skill 指令采用 MIT License。示例图片只用于展示输出效果；输入视频、生成图片及其中出现的第三方内容，不因本许可证获得额外授权。