Skip to content

anbeime/skill / skills/native-subtitle-quote-image/native-subtitle-quote-image/skills/native-subtitle-quote-image

native-subtitle-quote-image

Verified

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

references/troubleshooting.md

View on GitHub
# 排错手册

按「症状 → 先查什么 → 怎么处理」整理常见失败。下载与字幕轨的细节问题见 [yt-dlp-and-transcripts.md 的常见故障](yt-dlp-and-transcripts.md#常见故障),这里只列和出图直接相关的部分。

处理原则:每次只改一个变量;同一问题连续三轮仍不行时,换片段或向用户说明限制,不无限重试。

## 环境与编码

### 运行前环境不确定

- **先查**:运行 `python3 "<SKILL_DIR>/scripts/check_environment.py"`;脚本模式加 `--script-mode`,URL 任务再加 `--url-mode`。
- **处理**:按输出逐项补齐 FFmpeg、Pillow、CJK 字体等;显示为可选的项目不阻塞出图。

### 中文 Windows 上读写报 `UnicodeDecodeError` 或输出乱码

- **先查**:`check_environment.py` 是否提示「默认编码非 UTF-8」。
- **处理**:本仓库脚本从 v2.6.1 起都显式使用 UTF-8;仍有问题时设置 `PYTHONUTF8=1`(cmd:`set PYTHONUTF8=1`,PowerShell:`$env:PYTHONUTF8="1"`)后重试,并把命令和完整报错反馈到 issue。

## 源视频

### 下载的视频偏低清,或渲染时报解码错误

- **先查**:`native_subtitle_stitch.py check-source VIDEO --min-height 720`。它会检查分辨率并解码前 N 秒(`--seconds`,默认 10)。
- **处理**:自检失败就按 [格式回退表](yt-dlp-and-transcripts.md#4-下载视频) 换下一级变体重新下载,不要拿坏流继续出图。低于 720p 的版本必须先征得用户同意。

### 长视频 AV1 / VP9 源渲染到一半稳定失败

- **先查**:源是否为 1 小时以上的 AV1 / VP9 变体;同一源换 H.264 变体是否会遇到 HTTP 403。
- **处理**:不要反复重试,先把已下载的源转码成 H.264 再渲染,例如 `ffmpeg -i source.mkv -c:v libx264 -preset veryfast -crf 20 -c:a aac -b:a 128k source-h264.mkv`。加 `-vf scale=-2:720` 可以加快转码、降低解码压力,但会把 4K 降到 720p,成品清晰度会跟着下降,需要告诉用户;想保留清晰度可以去掉它或改成 1080。转码后先跑一次 `check-source` 再出图。
- **已知情况**:目前只有两个实测样本,原因还没确认,**可能**在第 2 张起稳定失败(不是必然现象)。

### 报「无法读取视频尺寸或时长」或「取帧失败」

- **先查**:文件是否下载完整、路径是否正确,再跑一次 `check-source`。
- **处理**:文件损坏就重新下载;时间点超出视频时长时,回到文字稿核对时间点。

## 选帧与画面

### 报「所有时间点取到的画面几乎相同」或「字幕条几乎相同」

- **先查**:用 `sample` 看这些时间点的画面。常见原因是静态封面视频、画面冻结、同一句字幕选了两次,或那一段画面本来没有字幕。
- **处理**:换时间点或换片段。只有确认这正是用户要的效果时,才加 `--allow-duplicate-frames`。

### 主图选错了人(双人同框、主持人和嘉宾并排)

渲染器不识别人脸,也不自动选帧:主图就是 manifest(原生模式)或 `lines` JSON 第一句(脚本模式)指定的那个时间点。

- **先查**:用 `sample -t 时间点 --around 0.8` 回看主图前后的画面,确认画面主体就是说这句话的人。
- **处理**:在 manifest 或 JSON 里把主图时间点换成单人近景、构图完整的稳定帧,再重新渲染。「两人并排的宽景对谈」属于高风险素材,见 [SKILL.md 的选帧说明](../SKILL.md#2-选主题与稳定帧)。

### 一套图的主图几乎一模一样(固定机位)

- **先查**:用 `sample` 生成整段候选帧总览,看源视频有没有景别、机位或动作变化。
- **处理**:每张图的主图挑不同景别或不同动作的时间点;源视频本身只有一个机位时,向用户说明这是素材限制。

### 画面里有第三方水印、台标或角标

- **处理**:默认保留,不遮盖、不模糊、不涂抹,交给用户决定。用户在意时,只能换时间点,或在用户同意后调整裁切位置避开;不能用后期手段抹掉来源标识。

## 字幕与排版

### 原生字幕被裁掉一部分

- **先查**:用 `band -t 时间点 --band-top ... --band-bottom ...` 预览裁切区域。
- **处理**:两行字幕或字幕位置偏高时,调整 `--band-top` / `--band-bottom`,例如扩大到 `0.62–0.96`。

### 脚本模式报「找不到可用的中文字体」

- **处理**:安装中文字体,或用 `--font /path/to/font.ttc` 指定已获授权的字体文件。

### 脚本模式报「台词过长,缩小到可读下限后仍放不下」

- **处理**:拆句或删减,不要靠极小字号硬塞。

### 同一张图里各行字号不一致

脚本模式会按每行实际宽度自动缩小放不下的台词,所以长短差距大的台词字号会不一样。

- **处理**:先把过长的句子拆短,让各行长度接近。仍不一致时,用 `--font-size` 指定一个比默认更小、能让最长一行也放下的基础字号。

## 批量渲染与输出

### 报「以下输出已存在」

渲染器默认不覆盖已有成品。

- **处理**:换一个输出目录或文件名;确认要替换时再加 `--overwrite`。

### 一张图失败导致整批中止

以下两个参数仅原生字幕模式的 `render` 支持,脚本模式 `render-script` 没有。

- **处理**:加 `--keep-going`,失败的那张会被跳过,结束时输出失败清单(序号、时间点、原因)并写入输出目录的 `渲染失败报告.json`。修正 manifest 后加 `--resume`,只补渲缺失或损坏的图。
- **注意**:`--resume` 不会重新生成已经正常的图,即使 manifest 改过;要重渲某张,先删掉那张图。

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall