把视频内嵌字幕拼成 3:4 长图（native-subtitle-quote-image）

做影视、访谈类内容的人常要把一段视频里最有分量的几句话截成图发出去。字幕原本就烧在画面上，OCR 一遍再按识别结果重绘，字形跟原片对不上，还容易出岔子；手抄台词再排版，画面只剩一张摆拍，跟原始视频的关联断了。这个项目处理的是中间那一步：从真实画面里取帧，让字幕保持它本来的样子。

native-subtitle-quote-image 是 Python 写的 Agent Skill，把本地视频或 YouTube 链接里烧录的字幕按时间点取帧，拼成 3:4 社交长图，给需要给影视、访谈内容配图的人用。

仓库在 https://github.com/chengyi-ai/native-subtitle-quote-image ，MIT 许可证，语言是 Python（占比 100%），当前 2634 Star、261 Fork、7 个开放 Issue，最近一次提交在 2026-10-12，仓库体积约 12 MB。

它不做什么

• 原生模式不做 OCR。图里的字只能来自视频像素，不识别、不重绘、不翻译改写。视频如果只有可开关的字幕轨（关掉播放器 CC 就没了），Agent 会先说明限制，经你同意后才改用脚本模式。
• 脚本模式的字不冒充原字幕。成图里的台词来自你审核过的 lines[].text，属于后期字幕，不作为人物的逐字引语。
• 不做语音转写。项目不负责把语音转成文字，脚本模式要你自己准备带时间点的台词内容。
• 不负责选题和文案。仓库主流程只覆盖渲染环节；选题门槛、领域权重、画面对标、发布合规这些规则，有用户在 Issue 里提出散落在外部工作区文档、期望随仓库分发，这条 Issue 标记为已解决。
• 产出是 JPG。输出为逐张图片与总览图，不做视频成片。

用之前先准备好什么

• Python 3 环境，用 pip 安装 skills/native-subtitle-quote-image/requirements.txt。
• 一个支持 Agent Skills 目录格式的 Agent，比如 Codex 或 Claude Code；不走 Agent 也能直接跑脚本。
• 要处理 YouTube 链接，另装 yt-dlp：python3 -m pip install -U "yt-dlp[default]"。
• 画中日韩台词需要系统里有可用字体，用 check_environment.py --script-mode 检查。
• 输入视频：原生模式要求字幕已经烧录在画面里。仓库里也有一位用户提问说，带烧录字幕的视频不太好找，这条 Issue 目前待解决。
• 脚本模式：一份你核对过、带时间点的中文台词。

主要功能

命令行脚本是 skills/native-subtitle-quote-image/scripts/native_subtitle_stitch.py，下面几个子命令各自负责一段。

• 原生字幕拼图 render：按 manifest 渲染一组成品，字幕条直接从画面像素裁切。用法：render VIDEO --manifest manifest.json --out-dir output-v1 --band-top 0.78 --band-bottom 0.96。字幕裁切区域必须先确定，仓库建议先用 band 预览。
• 脚本字幕拼图 render-script：把你审核过的台词画到真实画面上。固定布局的主图约占 70%，台词用 --speaker-prefix 可以加说话人前缀（v2.6.0 新增）。
• 候选帧总览 sample：生成带时间点的候选帧拼图，省得反复试时间点。用法：sample VIDEO --start 30 --end 120 --interval 5 --out candidate-contact-sheet.jpg。不传时间范围时，会在整段视频里均匀抽取最多 24 帧；已经知道大概时间点，可以用 -t 61.2 -t 68.9 --around 0.8 围绕每个点取前、中、后三帧，避开字幕切换的瞬间。
• 字幕区域预览 band：确认字幕的裁切带。用法：band VIDEO -t 61.2 --band-top 0.78 --band-bottom 0.96 --out band-preview.jpg。
• 源视频自检 check-source：检查分辨率并解码前 10 秒，坏流或低清在抽帧前就失败。用法：check-source VIDEO --min-height 720。不传 --min-height 时低于 720p 只警告。
• 环境自检 check_environment.py：用 --url-mode 检查 URL 流程依赖，用 --script-mode 检查字体。这一步是只读的，不会自动安装或修改任何软件。
• 按卡缩放主图 --hero-zoom：v2.8.0 新增，按卡缩放主图，用来缓解固定机位源整组图看起来都一样的问题。
• 抽帧临时目录可配置：通过 --tmp-dir 或环境变量 NSQI_TMP_DIR 指定，避免受限环境下系统 Temp 目录触发权限问题（v2.7.0 新增）。

如果走 Agent，不用记这些命令，直接一句话调用即可，Agent 会先检查来源、字幕类型和候选帧，确定模式后再生成。

安装与最短示例

先把仓库拉下来，把 Skill 目录复制到 Codex 的 Skills 目录，再装依赖并自检。

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/
python3 -m pip install -r skills/native-subtitle-quote-image/requirements.txt
python3 skills/native-subtitle-quote-image/scripts/check_environment.py

Windows PowerShell 的另一套写法，以及 Claude Code、Codex Skill Installer 的安装方式，仓库 README 里都给了单独的命令块。升级时要先删除旧目录再复制，否则新版本已经删掉的文件会残留。用 Claude Code 的话，把路径里的 .codex 换成 .claude。

装好之后重开一个 Agent 任务，说一句话就能跑：

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

不想经过 Agent，直接跑命令行也可以。最短的一条是原生字幕渲染，前提是先用 band 确认裁切区域、用 sample 挑好时间点：

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

关键参数

• --manifest：原生模式要渲染哪些句子、每句取哪个时间点，都写在 manifest JSON 里。
• --out-dir：成品输出目录。
• --band-top / --band-bottom：字幕条在画面里的上下边界，用 0~1 的相对比例表示，0.78 与 0.96 是文档示例值。
• --min-height：源视频的最低高度门槛，示例里用 720。
• --start / --end / --interval：均匀抽帧的起止时间与间隔，单位是秒。
• -t / --around：指定时间点列表，以及围绕每个点取前后多少秒。
• --hero-zoom：按卡缩放主图。
• --speaker-prefix：脚本字幕模式的可选说话人前缀。
• --tmp-dir 与环境变量 NSQI_TMP_DIR：抽帧临时文件目录。

另外 check_environment.py 支持 --url-mode 和 --script-mode 两个开关，分别检查 URL 流程依赖和字体。参数之外的行为约定，仓库里没有说明的部分不要自己推测。

结果在哪里看

渲染完成后，输出目录里会有逐张 JPG，比例符合所选布局。原生模式还会生成 原生字幕时间点.json，记录每张图对应的时间点；脚本模式输出的则是 lines JSON。多图任务会附带一张 final_contact_sheet.jpg 总览图，用来一眼检查整组。抽帧和预览阶段的产物，则分别落在 sample 和 band 命令指定的文件名上，比如 candidate-contact-sheet.jpg 和 band-preview.jpg。

实际使用中的坑

• 双人同框时主图会钉到主持人。选帧按人脸面积占比打分，主持人和嘉宾同框时区分不开。用户复现说双人对谈源六张里 5 张选到主持人，舞台宽景源六张全部选到舞台另一侧的人。期望增加「单人约束」模式，目前这条 Issue 待解决。
• 主图缺构图约束，常见切头顶和贴边。选帧只看人脸面积占比，不校验构图位置，成图会出现头顶被切、下巴贴住条带边缘、脸偏到画面一侧、垂直位置过低或过高。同一套六张里的构图基准也不一致。这条 Issue 同样待解决。
• 简中 Windows 下测试大批失败。在默认编码为 GBK 的 Windows 上，73 项测试里有 17 项 error，原因是文本 I/O 没显式指定 UTF-8。已在 v2.6.1 修复，改成显式使用 UTF-8。
• 下载链会静默降级到低清。1080p 失败时格式回退链会退到 360p 并默默接受，同一源的 AV1/H.264 变体可能返回 403，个别老节目源码流损坏，下载后解码报错、渲染阶段直接崩。这条 Issue 已解决。

同类项目

这两条是同一赛道里能解决部分相同问题的项目。如果你的目标是拿到一个能直接发布的视频成片，或者需要在时间线上手动剪辑，native-subtitle-quote-image 帮不上忙，它只输出静态 JPG 长图，不剪视频也不自动挑高光，这种需求应该去看 ai-video-editor 或 openclip。反过来说，你只需要真实画面配原字幕的社交图，它在字幕来源标识和时间点记录上比通用视频工具更专门。

合规与授权边界

项目用 yt-dlp 抓取带字幕的视频源，这一步只能在自有素材或已获授权的目标上使用。未经许可下载、二次分发他人视频，可能违反平台服务条款，也可能触及著作权；成图里出现的画面、字幕、台标都属于原权利人。仓库示例提到，其中一张原生字幕作品的字幕来自 Bilibili 搬运版，左上角还带着原视频平台水印，这类素材直接商用风险很高。

还有一条与合规直接相关：源片自带电视台角标时，成图默认不处理角标。有用户提出希望增加角标区域模糊或遮盖开关，并默认关闭、由用户自行决定，同时在文档里说明版权与合规提示。取舍责任在使用者这边，不是所有角标都能遮。

适合谁

• 适合用 Codex 或 Claude Code 做内容生产的人：上游 Skill 负责选题写稿，这个 Skill 负责时间点、真实画面、字幕来源标识和质检，两边能接上。
• 适合手上恰好有烧录字幕片源的影视、访谈类账号，尤其是需要画面证据感、不希望字幕被识别重绘的场景。
• 适合只需要静态配图、不需要视频成片的人，命令行五个子命令加一个 manifest 就能对齐整个流程。
• 不适合要剪视频成片的人，做不到。
• 不适合只有可开关字幕轨的视频源，得改用脚本模式，且要自己准备已核对的台词。
• 不适合指望它自动转写、自动挑句的人，选句这一步仍然需要人来做判断。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 9.1 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。