native-subtitle-quote-image
将本地视频或用户有权处理的在线视频,经过来源获取、文字稿定位、选题选句、精确取帧、紧凑裁切、拼图和逐张质检,制作成 3:4 或保留画面原比例的视频字幕长图。支持两种明确分开的输出:保留画面内已烧录字幕的原生字幕模式,以及把已审核的时间点与台词绘制到真实视频帧上的脚本字幕模式。用户要求原生字幕截图、字幕帧拼图、YouTube 金句长图、台词截图、不重绘字幕、自定义中文台词,或调整主图比例、字幕区域、台词间隔和美感时使用。
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
Not yet listed on ClawHub or SkillsMP
// README
能做什么
- 从视频直接出图:本地文件或 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-imageRemove-Item -Recurse -Force "$HOME\.codex\skills\native-subtitle-quote-image"
Claude Code:复制到 Claude Code 的 Skills 目录。
mkdir -p ~/.claude/skills && cp -R skills/native-subtitle-quote-image ~/.claude/skills/
Windows PowerShell:
New-Item -ItemType Directory -Force "$HOME\.claude\skills" | Out-Null
Copy-Item -Recurse skills\native-subtitle-quote-image "$HOME\.claude\skills\"
Codex Skill Installer:在 Codex 中调用 $skill-installer,让它安装这个目录:
https://github.com/chengyi-ai/native-subtitle-quote-image/tree/main/skills/native-subtitle-quote-image
其他 Agent:本项目使用开放的 Agent Skills 目录格式。把 skills/native-subtitle-quote-image/ 复制到目标 Agent 的 Skills 目录即可,具体位置以该 Agent 的文档为准。
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 会先问“您当前是选择原生字幕还是脚本字幕?”,并用一句话解释两者区别,再按你的选择处理。
| 原生字幕 | 脚本字幕 | |
|---|---|---|
| 什么时候用 | 关掉播放器的 CC 后,字幕仍然烧在画面里 | 要把已核对的台词、翻译或观点画到真实画面上 |
| 图里的字从哪来 | 视频像素本身,不 OCR 重绘,不翻译改写 | 你审核过的 lines[].text,明确属于后期字幕 |
| 命令 | render | render-script |
[!IMPORTANT] 原生模式的字只能来自视频像素;脚本模式的字只能来自已审核的 JSON,不能冒充原字幕。 如果你要原生字幕,但视频只有可开关的字幕轨,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 支持三种工作方式:
- 本地成片:直接从本地视频选句、取帧、出图,不需要
yt-dlp。 - URL 完整流程:用
yt-dlp获取你有权处理的视频、元数据和辅助字幕轨,再决定字幕模式。 - 内容生产:读视频、选题、写文章或帖子,最后配字幕截图。其他内容类 Skill 负责上游,本 Skill 负责时间点、真实画面、字幕来源标识和质检。
用一句话调用
| 场景 | 对 Agent 说 |
|---|---|
| 视频自带烧录字幕 | 使用 $native-subtitle-quote-image,把这个带内嵌中文字幕的视频做成原生字幕拼图。 |
| 给的是链接 | 使用 $native-subtitle-quote-image,读取这个 YouTube 链接,先检查下载权限和烧录字幕,再选 3 个适合传播的主题,做成原生字幕拼图并逐张质检。 |
| 写稿配图一起做 | 先根据视频文字稿提炼选题并写文章,再用 $native-subtitle-quote-image 为每个核心观点选真实视频帧并出图;先判断原生或脚本字幕模式,不要混用。 |
| 用自己核对过的台词 | 使用 $native-subtitle-quote-image 的脚本字幕模式,把这份带时间点的中文台词画到真实视频帧上,做成紧凑 3:4 长图并逐张质检。 |
[!TIP]
$native-subtitle-quote-image是 Codex 的写法。在 Claude Code 里可以用/native-subtitle-quote-image,或者直接描述需求。
Agent 会先检查来源、字幕类型和候选帧,确定模式后再生成:
- 逐张 JPG,比例符合所选布局;
- 原生模式的
原生字幕时间点.json,或脚本模式的linesJSON; - 多图任务的
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
// HOW IT'S BUILT
// FILES
13 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
skills/native-subtitle-quote-image/SKILL.md24 KB3a97a8c4e5faupstream ↗
--- name: native-subtitle-quote-image description: 将本地视频或用户有权处理的在线视频,经过来源获取、文字稿定位、选题选句、精确取帧、紧凑裁切、拼图和逐张质检,制作成 3:4 或保留画面原比例的视频字幕长图。支持两种明确分开的输出:保留画面内已烧录字幕的原生字幕模式,以及把已审核的时间点与台词绘制到真实视频帧上的脚本字幕模式。用户要求原生字幕截图、字幕帧拼图、YouTube 金句长图、台词截图、不重绘字幕、自定义中文台词,或调整主图比例、字幕区域、台词间隔和美感时使用。 --- # 视频字幕拼图 先确认用户想要的字幕模式,再判断素材是否支持。不要把两种模式混为一种,也不要默默从原生字幕切到绘制字幕。 ## 开始时确认模式 如果用户没有明确指定模式,先用用户当前使用的语言询问,并简短说明两种选择。中文提问可直接使用: > 您当前是选择原生字幕还是脚本字幕?原生字幕会保留视频画面里已有的字幕,不重绘文字;脚本字幕会把您确认过的台词或翻译后期绘制到真实视频帧上,并标明是后期字幕。 用户已明确说“原生字幕”“保留画面原字幕”“不重绘字幕”,或“脚本字幕”“把指定台词/翻译绘制到画面上”时,按其选择继续,不重复询问。用户尚未选择时,可以只读检查素材以说明哪种模式可行,但不要执行模式专属的渲染;等用户选择后再继续。若所选模式与素材不匹配,说明具体原因并征求用户是否改选,不能自行切换。 ## 非阻塞版本检查 每个新任务开始、处理素材之前运行一次: ```bash 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 时缩减语言并放慢请求,都不要无限重试。调 yt-dlp 优先用 `scripts/fetch_source.py`:它会识别 403/429 并按类型做有上限的退避重试,自动写 `download-attempts.log`,不静默失败。 - **读长视频 → 选题 → 写文章/帖子 → 配图**:读 [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 目录。 URL 模式的下载入口(包装 yt-dlp,带 403/429 退避重试与尝试日志): ```bash # 元数据自检(不带 Cookie 的第一步) python3 "<SKILL_DIR>/scripts/fetch_source.py" "URL" --mode metadata # 字幕:先 yt-dlp --list-subs 看真实标签,再只请求需要的一两个 python3 "<SKILL_DIR>/scripts/fetch_source.py" "URL" --mode subs \ --sub-langs zh-Hans,en-orig -o "source/%(id)s/%(id)s.%(ext)s" # 视频:格式回退表每级换一次 -f python3 "<SKILL_DIR>/scripts/fetch_source.py" "URL" --mode video \ -f "bv*[height<=1080][vcodec^=av01]+ba" -o "source/%(id)s/%(id)s.%(ext)s" ``` - 429(请求过密)按 `--backoff`×2^n 退避重试,最多 `--retries` 次(默认 3,上限 6,单次等待封顶 600s)。 - 403 始终最多重试 1 次;它通常是 yt-dlp 版本落后或该格式签名失效,要靠升级和换 `-f` 解决,而不是多试几次。 - 登录验证、年龄验证类报错**不重试**,直接停下并要求先取得用户授权;授权后用 `--extra --cookies-from-browser chrome` 透传,脚本不自行添加 Cookie 参数。 - 每次尝试(含成功)记入 `download-attempts.log`,失败时把 yt-dlp 原始报错和处理建议一起输出到 stderr,退出码非零。 - 它不绕过 DRM、付费墙、地区限制或平台风控;重试耗尽就停下汇报,不换 IP、不换账号、不遍历浏览器配置。 ```bash # 本地原生字幕 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。环境检查只报告状态;缺失时先说明用途并取得授权,再运行: ```bash 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`,只有用户确认确实需要时才加。 - 重复判定阈值可调:`--duplicate-ratio`(`render` 与 `render-script` 均支持)是缩略图上明显变化像素的占比下限,范围 0–0.2,默认 0.005。调高更严(连景别相近的帧也拦),调低更宽松,0 等于只拦完全一致的帧。不要和 `--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` 不兼容(固定几何)。 ```bash 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。 时间点不明时,先生成候选帧总览: ```bash python3 "<SKILL_DIR>/scripts/native_subtitle_stitch.py" sample VIDEO \ --out candidate-contact-sheet.jpg ``` 已有文字稿候选时间点时,围绕每个点生成前、中、后三帧: ```bash 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 写的是哪个时间点就用哪一帧: - **固定主图时间点**:选定后把时间点直接写进 manifest 或 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` 看整段有没有景别或动作变化,尽量为每张图挑不同的画面;源视频只有一个机位时,向用户说明这是素材限制。 - **第三方水印、台标、角标**:默认保留,不遮盖、不模糊、不涂抹,交给用户决定。用户在意时只能换时间点,或在用户同意后调整裁切位置避开。 ### 多人对话与访谈 渲染器只按时间点顺序拼图,不识别谁在说话;字幕条只裁画面底部,读者会默认整张图都是主画面人物说的。访谈、播客、对谈、辩论等多人素材必须先做说话人区分,再选句: 1. **先标说话人**:YouTube 字幕轨和普通 Whisper 文字稿都不带说话人。有说话人分离(diarization)的转写就使用它;没有时,在文字稿里逐句写上说话人,并用 `sample -t ... --around 0.8` 回看画面(口型、机位、画面内名牌)确认。无法确认归属的句子不用。 2. **默认一张图只放一个人的话**:同一说话人连续表达一个观点;主画面必须是这个人在说话的稳定帧。 3. **问答结构要明确**:用户要“一问一答”时,先向用户确认结构;问与答必须在原视频中相邻,不得跳过对方插话后把两人的句子拼成一个人的观点。原生模式无法在画面上补标说话人,问答图要在交付说明里逐句写明说话人;脚本模式可在每句写 `speaker` 并用 `--speaker-prefix on-change` 在画面上标出(见 4B)。 4. **核对每个时间点的说话人**:两人交替快或抢话时,同一时间点画面里的字幕可能是对方的话。逐个时间点回看完整画面,而不是只看裁出的字幕条。 ## 原生字幕模式 ### 3A. 预览字幕区域 单行字幕从 `0.78–0.96` 开始;两行字幕或位置偏高时,先预览再扩大到例如 `0.62–0.96`。 ```bash 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 ``` ### 4A. 建立 manifest 并渲染 ```json { "images": [ { "title": "模型独立工作时长正在快速增长", "times": [61.6, 69.3, 75.0, 82.4, 88.8] } ] } ``` ```bash 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`。 ## 脚本字幕模式 ### 3B. 建立已审核的时间点 + 台词 JSON ```json { "lines": [ {"t": 61.6, "text": "第一句已核对台词"}, {"t": 69.3, "text": "第二句已核对台词"}, {"t": 75.0, "text": "第三句已核对台词"}, {"t": 82.4, "text": "第四句已核对台词"}, {"t": 88.8, "text": "第五句已核对台词"} ] } ``` - `t` 必须严格递增且小于视频时长。 - `text` 必须是已核对的单行台词;过长时拆句,不靠极小字号硬塞。 - 翻译台词要先核对含义、人名、数字和专有名词。 - 第一帧优先表情、手势和构图,其余帧优先台词连贯与背景可读性。 ### 4B. 渲染脚本字幕 ```bash 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`,然后运行: ```bash 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`: ```json {"lines": [ {"t": 37.2, "speaker": "主持人", "text": "在这么竞争激烈的行业里,"}, {"t": 38.8, "speaker": "主持人", "text": "你觉得是什么让你脱颖而出?"}, {"t": 44.0, "speaker": "王薇薇", "text": "说实话,我觉得是运气。"} ]} ``` ```bash 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` 一致,并且台词字号没有因前缀明显变小。 - 原生模式没有改字;脚本模式的文字与已审核 JSON 一致。 - 主体完整,没有异常切脸、巨大空白、无关 UI 或变形;主图逐张过一遍「主图构图检查清单」(头顶留白、下巴不贴字幕条、脸位不偏),不达标的已重找或已在交付中说明。 - 原生模式检查第一句与后续字幕是否使用同一缩放倍数、没有横向裁字;固定画布允许外侧留边。`--fit crop` 的成品要逐张确认每句字幕两端完整、人物没有被两侧裁切切脸,并在交付中说明渲染输出的裁切或留边结果。脚本固定布局默认四条时主图约占 68–72%;内容块之间没有额外间距。 - 脚本模式的字号、描边、对比度在原尺寸与手机缩略图中都可读。 - 文件数量、尺寸、比例、JSON 和总览一致。 发现问题时只调整对应变量:时间点通常移动 `0.3–1.5` 秒;原生字幕被裁时调整 `band` 边界;台词条太高时先恢复自动布局;文字过长时先拆句。连续三轮仍找不到稳定画面时,换片段或报告限制,不无限微调。 ## 与其他工具或 Skill 协作 - `yt-dlp`:获取用户有权处理的在线视频、元数据和字幕轨;不负责最终渲染。 - 字幕轨或 Whisper:生成带时间戳的内容索引。原生模式只用它定位;脚本模式可把已复核文字写入 JSON。 - 视频理解、选题或内容分析 Skill:提名主题、时间范围和句子顺序。 - 写作 Skill:产生配套文章或帖子;它不能在原生模式中改变画面字幕。 - 本 Skill:管理最终时间点、真实视频帧、字幕来源标识、拼图和视觉 QA。 复用上游已经下载的视频、文字稿和缓存,不重复消耗网络或转写成本。不假设用户一定安装了某个命名 Skill;缺少上游 Skill 时,自行完成最低限度的文字稿阅读和主题选择。 ## 停止条件 - 用户没有下载、处理或发布来源素材的权限。 - 链接需要绕过 DRM、付费墙、地区限制或其他访问控制。 - 用户要求原生字幕,但画面没有烧录字幕;此时先说明,只有用户同意才转脚本模式。 - 原生模式找不到字幕完整稳定的帧。 - 脚本模式的台词或翻译尚未核对,或没有可用 CJK 字体。 - 源画质、遮挡或 UI 严重到无法达到可读交付。 登录、年龄验证、机器人验证或用户自己的非公开视频需要 Cookies 时,必须先取得授权;授权后优先让 `yt-dlp` 通过 `--cookies-from-browser chrome` 临时读取用户自己的已登录会话,而不是让用户粘贴密码或导出 Cookie 文件。不得把浏览器数据写入仓库。 ## 交付 提供输出路径、逐张成品、时间点/`lines` JSON、总览图与已完成的视觉和技术检查。明确标记使用的字幕模式。只有用户需要分享包时再生成 ZIP;不得把未逐张打开检查的图片报告为完成。skills/native-subtitle-quote-image/scripts/check_environment.py8.9 KBbdba00199798upstream ↗
#!/usr/bin/env python3 """检查视频字幕拼图的原生、脚本与 URL 模式所需组件,不执行安装。""" import argparse import importlib import importlib.util import json import locale import shutil import subprocess import sys from pathlib import Path CJK_FONT_CANDIDATES = [ "/System/Library/Fonts/PingFang.ttc", "/System/Library/Fonts/STHeiti Medium.ttc", "/System/Library/Fonts/Hiragino Sans GB.ttc", "C:/Windows/Fonts/msyh.ttc", "C:/Windows/Fonts/simhei.ttf", "/System/Library/Fonts/AppleSDGothicNeo.ttc", "C:/Windows/Fonts/malgun.ttf", "/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc", "/usr/share/fonts/opentype/noto/NotoSansCJKsc-Regular.otf", "/usr/share/fonts/truetype/wqy/wqy-zenhei.ttc", ] def command_version(command, args=("--version",)): path = shutil.which(command) if not path: return None, None try: proc = subprocess.run( [path, *args], capture_output=True, encoding="utf-8", errors="replace", timeout=10, check=False, ) except (OSError, subprocess.SubprocessError): return path, "无法读取版本" output = (proc.stdout or proc.stderr or "").strip().splitlines() return path, output[0] if output else "版本未知" def module_version(name): if importlib.util.find_spec(name) is None: return None module = importlib.import_module(name) return getattr(module, "__version__", "已安装") def add(rows, component, status, purpose, detail="", required="core"): rows.append( { "component": component, "status": status, "purpose": purpose, "detail": detail, "required": required, } ) def utf8_default(): if sys.flags.utf8_mode: return True return locale.getpreferredencoding(False).lower().replace("-", "") == "utf8" def inspect_environment(): rows = [] python_ok = sys.version_info >= (3, 10) add( rows, "Python 3.10+", "ok" if python_ok else "missing", "运行 Skill 脚本", sys.version.split()[0], ) if not utf8_default(): add( rows, "UTF-8 encoding", "optional", "文本读写:默认编码非 UTF-8 时中文路径与输出可能乱码", f"当前默认编码 {locale.getpreferredencoding(False)};" "建议设置 PYTHONUTF8=1(cmd: set PYTHONUTF8=1)", required="optional", ) pillow = module_version("PIL") add( rows, "Pillow", "ok" if pillow else "missing", "裁图、拼图、导出 JPG", str(pillow or "未安装"), ) ffmpeg_detail = "" imageio = module_version("imageio_ffmpeg") if imageio: try: imageio_module = importlib.import_module("imageio_ffmpeg") ffmpeg_detail = f"imageio-ffmpeg {imageio}: {imageio_module.get_ffmpeg_exe()}" except Exception as exc: # pragma: no cover - platform-specific failure ffmpeg_detail = f"imageio-ffmpeg 已安装但不可用: {exc}" imageio = None system_ffmpeg, ffmpeg_version = command_version("ffmpeg", ("-version",)) ffmpeg_ok = bool(imageio or system_ffmpeg) if system_ffmpeg: system_detail = f"system: {system_ffmpeg} ({ffmpeg_version})" ffmpeg_detail = f"{ffmpeg_detail}; {system_detail}" if ffmpeg_detail else system_detail add( rows, "FFmpeg provider", "ok" if ffmpeg_ok else "missing", "读取视频并精确取帧", ffmpeg_detail or "请安装 imageio-ffmpeg 或 FFmpeg 可执行文件", ) cjk_font = next( (candidate for candidate in CJK_FONT_CANDIDATES if Path(candidate).is_file()), None, ) add( rows, "CJK font", "ok" if cjk_font else "missing", "脚本字幕模式:绘制中文、日文或韩文台词", cjk_font or "未找到常见 CJK 字体;可安装 Noto Sans CJK 或用 --font 指定", required="script", ) ytdlp_path, ytdlp_version = command_version("yt-dlp") add( rows, "yt-dlp", "ok" if ytdlp_path else "missing", "URL 模式:读取元数据、字幕轨和下载视频", f"{ytdlp_version} ({ytdlp_path})" if ytdlp_path else "本地视频模式不需要", required="url", ) runtimes = [] for label, command in ( ("Deno", "deno"), ("Node.js", "node"), ("QuickJS", "qjs"), ("Bun (deprecated)", "bun"), ): path, version = command_version(command) if path: runtimes.append((label, command, path, version)) if runtimes: label, command, path, version = runtimes[0] if command == "deno": detail = f"{label} {version} ({path});yt-dlp 默认启用" elif command == "bun": detail = ( f"{label} {version} ({path});调用 yt-dlp 时添加 " "--js-runtimes bun;官方已将 Bun 支持标记为弃用" ) else: detail = ( f"{label} {version} ({path});调用 yt-dlp 时添加 " f"--js-runtimes {command}" ) add( rows, "JavaScript runtime", "ok", "URL 模式:完整解析 YouTube", detail, required="url", ) else: add( rows, "JavaScript runtime", "missing", "URL 模式:完整解析 YouTube", "推荐 Deno;也可使用 Node.js 或 QuickJS;Bun 支持已弃用", required="url", ) whisper_cli, whisper_version = command_version("whisper") whisper_module = module_version("faster_whisper") or module_version("whisper") whisper_ok = bool(whisper_cli or whisper_module) whisper_detail = "未安装;只有来源没有可用时间轴时才需要" if whisper_cli: whisper_detail = f"CLI {whisper_version} ({whisper_cli})" elif whisper_module: whisper_detail = f"Python module {whisper_module}" add( rows, "Whisper / speech-to-text", "optional" if not whisper_ok else "ok", "可选:没有字幕轨时生成带时间戳文字稿", whisper_detail, required="optional", ) return rows def is_blocking(row, url_mode, script_mode): if row["status"] != "missing": return False return ( row["required"] == "core" or (url_mode and row["required"] == "url") or (script_mode and row["required"] == "script") ) def print_human(rows, url_mode, script_mode): labels = {"ok": "可用", "missing": "缺失", "optional": "可选"} widths = (26, 8, 38) print(f"{'组件':<{widths[0]}} {'状态':<{widths[1]}} 用途") print("-" * 92) for row in rows: print( f"{row['component']:<{widths[0]}} " f"{labels[row['status']]:<{widths[1]}} " f"{row['purpose']}" ) if row["detail"]: print(f" {row['detail']}") blocking = [row for row in rows if is_blocking(row, url_mode, script_mode)] source = "URL" if url_mode else "本地视频" subtitle = "脚本字幕" if script_mode else "原生字幕" mode = f"{source} + {subtitle}模式" if blocking: print(f"\n{mode}尚不可用,缺少: " + ", ".join(row["component"] for row in blocking)) else: print(f"\n{mode}环境检查通过。") if url_mode: print( "提示:若 YouTube 返回登录或机器人验证,不要退回本地模式;" "先取得用户授权,再在该 URL 的 yt-dlp 命令中添加 " "--cookies-from-browser chrome。" ) def main(): parser = argparse.ArgumentParser(description=__doc__) parser.add_argument( "--url-mode", action="store_true", help="把 yt-dlp 和 JavaScript runtime 也作为必需组件检查", ) parser.add_argument( "--script-mode", action="store_true", help="把绘制中文台词所需的 CJK 字体也作为必需组件检查", ) parser.add_argument("--json", action="store_true", help="输出机器可读 JSON") args = parser.parse_args() rows = inspect_environment() blocking = [ row for row in rows if is_blocking(row, args.url_mode, args.script_mode) ] if args.json: print( json.dumps( { "mode": "url" if args.url_mode else "local", "script_mode": args.script_mode, "ok": not blocking, "components": rows, }, ensure_ascii=False, indent=2, ) ) else: print_human(rows, args.url_mode, args.script_mode) raise SystemExit(1 if blocking else 0) if __name__ == "__main__": main()skills/native-subtitle-quote-image/scripts/check_update.py8.0 KB9e6f6806c938upstream ↗
#!/usr/bin/env python3 """Check GitHub Releases for a newer Skill version without auto-updating.""" import argparse import json import os import platform import re import subprocess import urllib.error import urllib.request from datetime import datetime, timedelta, timezone from pathlib import Path REPOSITORY = "chengyi-ai/native-subtitle-quote-image" LATEST_API = f"https://api.github.com/repos/{REPOSITORY}/releases/latest" RELEASES_URL = f"https://github.com/{REPOSITORY}/releases" CACHE_TTL = timedelta(hours=24) VERSION_FILE = Path(__file__).resolve().parents[1] / "VERSION" def parse_version(value): match = re.fullmatch(r"\s*v?(\d+)\.(\d+)\.(\d+)(?:[-+][0-9A-Za-z.-]+)?\s*", value) if not match: raise ValueError(f"无法识别版本号: {value!r}") return tuple(int(part) for part in match.groups()) def normalize_version(value): return ".".join(str(part) for part in parse_version(value)) def read_current_version(): return normalize_version(VERSION_FILE.read_text(encoding="utf-8")) def default_cache_path(): override = os.environ.get("NATIVE_SUBTITLE_UPDATE_CACHE") if override: return Path(override).expanduser() system = platform.system() if system == "Darwin": root = Path.home() / "Library" / "Caches" elif system == "Windows": root = Path(os.environ.get("LOCALAPPDATA", Path.home() / "AppData" / "Local")) else: root = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache")) return root / "native-subtitle-quote-image" / "update-check.json" def utc_now(): return datetime.now(timezone.utc) def format_timestamp(value): return value.astimezone(timezone.utc).isoformat().replace("+00:00", "Z") def parse_timestamp(value): return datetime.fromisoformat(value.replace("Z", "+00:00")).astimezone(timezone.utc) def read_cache(path): try: payload = json.loads(path.read_text(encoding="utf-8")) latest_version = normalize_version(payload["latest_version"]) checked_at = parse_timestamp(payload["checked_at"]) release_url = payload.get("release_url") or RELEASES_URL except (OSError, KeyError, TypeError, ValueError, json.JSONDecodeError): return None return { "latest_version": latest_version, "release_url": release_url, "checked_at": checked_at, } def cache_is_fresh(cache, now): if not cache: return False age = now - cache["checked_at"] return timedelta(0) <= age < CACHE_TTL def write_cache(path, payload): path.parent.mkdir(parents=True, exist_ok=True) temporary = path.with_name(f".{path.name}.tmp") temporary.write_text( json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8", ) temporary.replace(path) def release_from_payload(payload): latest_version = normalize_version(payload["tag_name"]) return { "latest_version": latest_version, "release_url": payload.get("html_url") or RELEASES_URL, } def fetch_latest_release(timeout=4): request = urllib.request.Request( LATEST_API, headers={ "Accept": "application/vnd.github+json", "User-Agent": "native-subtitle-quote-image-update-check", }, ) try: with urllib.request.urlopen(request, timeout=timeout) as response: return release_from_payload(json.load(response)) except (OSError, urllib.error.URLError) as urllib_error: # Python.org builds on macOS can lack a configured CA bundle. Use the # operating system's curl as a verified-HTTPS fallback; never disable TLS. try: proc = subprocess.run( [ "curl", "-fsSL", "--connect-timeout", str(timeout), "--max-time", str(timeout), "-H", "Accept: application/vnd.github+json", "-A", "native-subtitle-quote-image-update-check", LATEST_API, ], capture_output=True, encoding="utf-8", errors="replace", check=False, timeout=timeout + 1, ) except (OSError, subprocess.SubprocessError) as curl_error: raise OSError( f"Python HTTPS 失败: {urllib_error}; curl 回退失败: {curl_error}" ) from curl_error if proc.returncode != 0: detail = proc.stderr.strip() or f"退出码 {proc.returncode}" raise OSError( f"Python HTTPS 失败: {urllib_error}; curl 回退失败: {detail}" ) return release_from_payload(json.loads(proc.stdout)) def check_for_update(force=False, now=None, cache_path=None, fetcher=None): now = now or utc_now() cache_path = cache_path or default_cache_path() fetcher = fetcher or fetch_latest_release current_version = read_current_version() cache = read_cache(cache_path) error = None if cache_is_fresh(cache, now) and not force: release = cache from_cache = True else: try: release = fetcher() release = { "latest_version": normalize_version(release["latest_version"]), "release_url": release.get("release_url") or RELEASES_URL, "checked_at": now, } from_cache = False try: write_cache( cache_path, { "checked_at": format_timestamp(now), "latest_version": release["latest_version"], "release_url": release["release_url"], }, ) except OSError as exc: error = f"无法写入更新缓存: {exc}" except (OSError, KeyError, TypeError, ValueError, json.JSONDecodeError, urllib.error.URLError) as exc: error = f"无法检查更新: {exc}" if cache: release = cache from_cache = True else: return { "status": "unavailable", "current_version": current_version, "latest_version": None, "release_url": RELEASES_URL, "checked_at": None, "from_cache": False, "error": error, } latest_version = release["latest_version"] status = ( "update_available" if parse_version(latest_version) > parse_version(current_version) else "up_to_date" ) return { "status": status, "current_version": current_version, "latest_version": latest_version, "release_url": release.get("release_url") or RELEASES_URL, "checked_at": format_timestamp(release["checked_at"]), "from_cache": from_cache, "error": error, } def main(): parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("--force", action="store_true", help="忽略 24 小时缓存并立即检查") parser.add_argument("--json", action="store_true", help="输出机器可读 JSON") parser.add_argument("--verbose", action="store_true", help="没有更新或检查失败时也显示状态") args = parser.parse_args() result = check_for_update(force=args.force) if args.json: print(json.dumps(result, ensure_ascii=False, indent=2)) elif result["status"] == "update_available": print( f"发现 Skill 新版本 v{result['latest_version']} " f"(当前 v{result['current_version']}):{result['release_url']}" ) elif args.verbose and result["status"] == "up_to_date": print(f"当前已是最新版 v{result['current_version']}。") elif args.verbose: print(result["error"] or "暂时无法检查更新。") # 更新检查永远不阻断主要任务。 return 0 if __name__ == "__main__": raise SystemExit(main())skills/native-subtitle-quote-image/scripts/fetch_source.py8.4 KB7d97b10412d0upstream ↗
#!/usr/bin/env python3 """包装 yt-dlp 的下载入口:识别 HTTP 403 / 429 并做有上限的退避重试。 设计边界(与 SKILL.md 一致): - 不绕过 DRM、付费墙、地区限制或平台风控;403/429 只做有限重试和清楚报错。 - 429 是请求过密,退避等待后重试;403 大多是 yt-dlp 版本或该格式的签名失效,只重试一次。 - 任何失败都显式报错并记入 download-attempts.log,不静默失败、不无限重试。 - 不自行添加 Cookie 参数;Cookie 仅在用户授权后由调用方传入 --extra。 """ import argparse import datetime as _datetime import os import re import shutil import subprocess import sys import time from pathlib import Path ATTEMPT_LOG = "download-attempts.log" # 429 默认最多重试 3 次;再多就是在硬冲平台速率限制。 DEFAULT_RETRIES = 3 MAX_RETRIES = 6 # 退避基数(秒):等待为 base * 2**n,并封顶在 MAX_BACKOFF。 DEFAULT_BACKOFF = 30.0 MAX_BACKOFF = 600.0 # 403 通常不是速率问题,重试再多也没意义。 FORBIDDEN_RETRIES = 1 FORBIDDEN_BACKOFF = 5.0 RATE_LIMITED = "rate_limited" FORBIDDEN = "forbidden" BOT_CHECK = "bot_check" OTHER = "other" _PATTERNS = ( (RATE_LIMITED, re.compile(r"HTTP Error 429|Too Many Requests", re.IGNORECASE)), (FORBIDDEN, re.compile(r"HTTP Error 403|\bForbidden\b", re.IGNORECASE)), ( BOT_CHECK, re.compile( r"Sign in to confirm|confirm you’?re not a bot|not a bot" r"|age[- ]restricted|cookies", re.IGNORECASE, ), ), ) _ADVICE = { RATE_LIMITED: ( "HTTP 429:请求过于频繁,常见于一次请求多条自动翻译字幕轨。" "缩减 --sub-langs 只留需要的一两个标签,加 --sleep-subtitles 5,并改成串行单个视频;" "不要换 IP 或缩短间隔硬冲。" ), FORBIDDEN: ( "HTTP 403:通常是 yt-dlp 版本落后于站点改动,或该格品的签名 URL 已失效。" "先 python3 -m pip install -U 'yt-dlp[default]' 升级并确认 JavaScript runtime 生效," "再按 references/yt-dlp-and-transcripts.md 的格式回退表逐级换 -f,每级只试一次。" ), BOT_CHECK: ( "平台要求登录态(机器人验证、年龄验证或非公开视频)。不要重试:" "先向用户复述真实报错并取得授权,再用 --extra 传入 --cookies-from-browser chrome。" ), OTHER: "yt-dlp 未按 403/429 分类失败,请看下方原始报错。", } def classify(text): """把 yt-dlp 的 stderr 归类;顺序重要,429 优先于 403。""" for kind, pattern in _PATTERNS: if pattern.search(text or ""): return kind return OTHER def retry_plan(kind, retries, backoff): """返回(该类错误还能重试几次,退避基数)。""" if kind == RATE_LIMITED: return retries, backoff if kind == FORBIDDEN: return min(FORBIDDEN_RETRIES, retries), FORBIDDEN_BACKOFF # 登录验证和其他错误重试没有意义。 return 0, backoff def wait_seconds(backoff, attempt): return min(MAX_BACKOFF, backoff * (2 ** attempt)) def log_attempt(log_path, attempt, kind, detail): stamp = _datetime.datetime.now().astimezone().isoformat(timespec="seconds") line = f"{stamp}\t第 {attempt} 次\t{kind}\t{detail}\n" try: with open(log_path, "a", encoding="utf-8") as handle: handle.write(line) except OSError as exc: print(f"警告: 无法写入 {log_path}({exc})", file=sys.stderr) def last_lines(text, count=4): lines = [line.strip() for line in (text or "").splitlines() if line.strip()] return "\n".join(lines[-count:]) or "没有返回错误详情" def run_once(command): proc = subprocess.run( command, capture_output=True, encoding="utf-8", errors="replace" ) return proc.returncode, proc.stdout or "", proc.stderr or "" def fetch(command, retries, backoff, log_path, sleeper=time.sleep, runner=run_once): """执行 yt-dlp 并按错误类型退避重试;成功返回 0,否则非零。""" attempt = 0 while True: attempt += 1 code, stdout, stderr = runner(command) if stdout: print(stdout, end="" if stdout.endswith("\n") else "\n") if code == 0: log_attempt(log_path, attempt, "成功", " ".join(command[1:]) or "-") print(f"下载成功(第 {attempt} 次尝试),尝试记录: {log_path}") return 0 kind = classify(stderr) detail = last_lines(stderr, 1) log_attempt(log_path, attempt, kind, detail) allowed, base = retry_plan(kind, retries, backoff) remaining = allowed - (attempt - 1) if remaining <= 0: print( f"下载失败({kind},共 {attempt} 次尝试)。\n{_ADVICE[kind]}\n" f"yt-dlp 原始报错:\n{last_lines(stderr)}\n尝试记录: {log_path}", file=sys.stderr, ) return 1 delay = wait_seconds(base, attempt - 1) print( f"第 {attempt} 次失败({kind}),{delay:.0f}s 后重试,还剩 {remaining} 次。\n" f"{_ADVICE[kind]}", file=sys.stderr, ) sleeper(delay) def build_command(args, ytdlp): command = [ytdlp, "--no-playlist"] if args.mode == "metadata": command += [ "--skip-download", "--print", "%(id)s | %(title)s | %(channel)s | %(duration_string)s", ] elif args.mode == "subs": command += ["--skip-download", "--write-subs", "--write-auto-subs", "--sub-format", "vtt", "--sub-langs", args.sub_langs, "--sleep-subtitles", str(args.sleep_subtitles)] else: command += ["-f", args.format] if args.output: command += ["-o", args.output] command += list(args.extra) command.append(args.url) return command def main(argv=None): parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("url") parser.add_argument( "--mode", choices=("metadata", "subs", "video"), default="video", help="metadata 只读元数据;subs 只下字幕;video 下视频(默认)", ) parser.add_argument( "-f", "--format", default="bv*[height<=1080]+ba/b[height<=1080]", help="video 模式的 yt-dlp -f 参数", ) parser.add_argument("-o", "--output", help="yt-dlp -o 输出模板") parser.add_argument( "--sub-langs", default="zh-Hans,en-orig", help="subs 模式的字幕语言标签;先用 --list-subs 看真实标签,不要用 zh.* 这类泛匹配", ) parser.add_argument( "--sleep-subtitles", type=float, default=5.0, help="subs 模式每条字幕轨之间的等待秒数,默认 5,降低 429 概率", ) parser.add_argument( "--retries", type=int, default=DEFAULT_RETRIES, help=f"429 最多重试次数,0–{MAX_RETRIES},默认 {DEFAULT_RETRIES};403 始终最多重试 1 次", ) parser.add_argument( "--backoff", type=float, default=DEFAULT_BACKOFF, help=f"退避基数秒,等待为 base×2^n 并封顶 {MAX_BACKOFF:.0f}s,默认 {DEFAULT_BACKOFF:.0f}", ) parser.add_argument( "--log", help=f"尝试日志路径,默认当前工作目录的 {ATTEMPT_LOG}", ) parser.add_argument( "--extra", nargs=argparse.REMAINDER, default=[], help="透传给 yt-dlp 的其余参数,必须放在最后(例如 --extra --cookies-from-browser chrome)", ) args = parser.parse_args(argv) if not 0 <= args.retries <= MAX_RETRIES: parser.error(f"--retries 必须在 0–{MAX_RETRIES} 之间") if not 0 < args.backoff <= MAX_BACKOFF: parser.error(f"--backoff 必须大于 0 且不超过 {MAX_BACKOFF:.0f}") if args.sleep_subtitles < 0: parser.error("--sleep-subtitles 不能为负数") ytdlp = shutil.which("yt-dlp") if not ytdlp: raise SystemExit( "找不到 yt-dlp;先说明用途并取得授权后运行" ' python3 -m pip install -U "yt-dlp[default]"' ) log_path = Path(args.log).expanduser() if args.log else Path(os.getcwd()) / ATTEMPT_LOG command = build_command(args, ytdlp) print("执行: " + " ".join(["yt-dlp", *command[1:]])) return fetch(command, args.retries, args.backoff, log_path) if __name__ == "__main__": sys.exit(main())skills/native-subtitle-quote-image/scripts/native_subtitle_stitch.py61 KB52a05411242bupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
skills/native-subtitle-quote-image/references/end-to-end-workflow.md17 KBdd1053a8d740upstream ↗
# 从读视频到字幕长图的完整工作流 本文件用于多阶段任务:链接获取、长视频理解、选题、选句、精确取帧、原生/脚本字幕分流、拼图、质检和返工。只有本地短视频且时间点已经明确时,可以不读本文件,直接使用 `SKILL.md` 的核心流程。 ## 交付标准 一次完整交付至少包含: - 一个独立输出目录,并明确标注原生字幕或脚本字幕模式; - 逐张 JPG,比例符合所选布局或用户明确要求; - 原生模式的 `原生字幕时间点.json`,或脚本模式的 `lines` JSON; - 多图任务的 `final_contact_sheet.jpg`; - 对来源、字幕类型、画质限制和素材权限的简短说明; - 逐张视觉检查结论,而不是只报告脚本退出码。 ## 来源模式与字幕模式 这是两个独立维度:来源可以是本地或 URL,字幕可以是原生或脚本。例如,YouTube URL 既可用原生字幕模式,也可在用户需要已审核中文台词时用脚本字幕模式。 ### A. 字幕模式 - **原生字幕**:文字已经烧录在画面像素中;只取帧、裁切和拼接,不改字。 - **脚本字幕**:文字来自已审核的时间点 + 台词 JSON;在真实视频帧上后期绘制。 用户要求原生字幕时,只能使用原生模式。画面没有对应烧录字幕时,先报告限制;只有用户同意,才改用脚本模式。 ### B. 来源与任务模式 #### 本地成片模式 用户提供本地视频。完成环境检查、候选帧、选句、模式判断、渲染和质检。`yt-dlp` 不是必需项;文字稿或 Whisper 只在需要语义定位时使用。 #### URL 完整模式 用户提供 YouTube 等链接。先按 [yt-dlp-and-transcripts.md](yt-dlp-and-transcripts.md) 获取视频与辅助时间轴,再选择原生字幕或脚本字幕模式。 #### 内容生产模式 用户想完成“读视频 → 选题 → 写文章/帖子 → 生成字幕截图”。先让视频理解、转写、选题或写作 Skill 处理文字稿;再把每个主题对应的时间范围交回本 Skill,从真实视频帧选择最终画面。原生模式不改字;脚本模式只绘制已复核台词。 ## 推荐目录 每个来源使用独立目录,避免缓存、成品和其他视频混在一起: ```text 任务目录/ ├── source/ # 下载或用户提供的视频、字幕轨、元数据 ├── analysis/ │ ├── transcript.vtt # 可选,仅用于理解和定位 │ ├── candidate-topics.md # 可选,候选主题与时间范围 │ └── candidate-frames.jpg # 带时间点候选帧 ├── manifest.json # 原生模式的最终时间点 ├── script.json # 脚本模式的时间点 + 已审核台词 ├── previews/ │ └── band-preview.jpg └── output-v1/ ├── 01_主题.jpg ├── 原生字幕时间点.json # 原生模式 └── final_contact_sheet.jpg ``` 不要把原视频、Cookie、个人账号信息、临时字幕或成品图提交进 Skill 仓库。输出目录已存在时创建 `output-v2`;只有用户明确要求覆盖时才使用 `--overwrite`。 ## 阶段 0:确认任务 开始前确认四件事: 1. 输入是本地文件还是 URL; 2. 用户想要几张图、发布比例和目标受众; 3. 是否需要先理解长视频、选题或写文章; 4. 用户是否有权下载、处理并发布来源素材。 缺少图片数量时,可以先做 2–3 个候选主题,但不要把推测当作用户已经确认的发布方案。 ## 阶段 1:环境诊断 本地模式: ```bash python3 "<SKILL_DIR>/scripts/check_environment.py" ``` URL 模式: ```bash python3 "<SKILL_DIR>/scripts/check_environment.py" --url-mode ``` 脚本字幕中含中日韩文字时增加 `--script-mode`;URL 来源可以同时传 `--url-mode --script-mode`。 核心依赖缺失时先取得安装授权。URL 模式缺少 Deno,但已有 Node.js 时,不需要强制再装 Deno;在 yt-dlp 命令里显式使用 `--js-runtimes node` 即可。Deno 仍是官方推荐和默认启用的选择。 ## 阶段 2:获得来源并建立来源记录 URL 模式按专门参考文件执行。至少保留: - 原始 URL; - 视频标题、作者/频道、视频 ID、时长; - 实际下载的视频文件; - 使用了人工字幕、自动字幕还是语音识别; - 下载日期与 yt-dlp 版本; - `download-attempts.log`:每次下载尝试的格式、结果和错误摘要。 下载后必须运行 `check-source VIDEO --min-height 720`,通过才能进入抽帧;失败则按参考文件换下一级变体重试。低于 720p 的变体须先征得用户确认。 来源记录用于复核,不要把账号凭据、Cookie 内容或本机绝对路径写进去。 ## 阶段 3:判断字幕类型并锁定模式 字幕类型是硬门槛。不能只看播放器是否显示字幕,也不能只看是否下载到了 VTT。必须在出图前记录使用哪种字幕模式。 先生成整段候选帧总览: ```bash python3 "<SKILL_DIR>/scripts/native_subtitle_stitch.py" sample VIDEO \ --out analysis/candidate-frames.jpg ``` 逐格检查: - 字幕是否直接存在于画面像素; - 字幕语言和用户需求是否一致; - 字幕位置是否稳定; - 是否有节目 Logo、标题条、广告贴片遮住字幕; - 视频画质是否足够。 若大多数帧没有字幕,不要马上判定失败;可能抽到了停顿或转场。结合文字稿选 2–3 个明确说话的时间点,再使用聚焦采样。 最终分流: - 用户要求保留原字幕,且稳定帧里能直接看到文字:原生字幕模式。 - 用户要求中文翻译、提炼台词或统一字体,并理解文字会后期绘制:脚本字幕模式。 - 用户要求原生字幕,但只找到独立字幕轨:先停止并说明,取得同意后才可转脚本模式。 ## 阶段 4:用文字稿选题,再核对文字用途 字幕轨或 Whisper 文字稿首先用来快速回答: - 视频有哪些值得传播的独立观点; - 每个观点在哪个时间范围; - 哪段能组成 4–6 句连续表达; - 哪些句子是提问、结论、反常识或行动建议。 ### 多人对话与访谈:先标说话人 访谈、播客、对谈、圆桌和辩论里,文字稿是多个人交替说话的结果,而 YouTube 字幕轨与普通 Whisper 文字稿都不标说话人。直接按“4–6 句连续表达”选句,会把主持人的提问和嘉宾的回答拼成一个人的观点,读起来像串线或乱序。选题前先做三件事: 1. **建立说话人索引**:有带说话人分离(diarization)的转写时使用它;没有时,在 `analysis/` 下另存一份带说话人标注的文字稿,例如 `[61.2] 主持人:……`、`[68.9] 嘉宾 A:……`。不确定的句子用 `sample -t ... --around 0.8` 回看画面,依据口型、机位和画面内名牌判断;仍无法确认的句子不入选。 2. **按说话人切分主题**:默认一张图只放同一个人围绕一个观点的连续表达。主持人的提问只在用户需要“问答”结构时入选。 3. **问答结构单独确认**:用户要一问一答时,先确认结构;问与答必须在原视频中相邻,不跳过对方插话,也不把两人的句子改写成一人的观点。原生模式无法在画面上补标说话人,交付说明里要逐句写明说话人。 不标说话人就选句,是多人素材“分不清谁说的、顺序乱”的主要原因;不要靠后期换帧补救。 ### 候选主题评分 每个候选主题按以下维度判断,不需要机械打分,但应明确取舍: | 维度 | 判断问题 | |---|---| | 独立性 | 脱离上下文后还能看懂吗? | | 连续性 | 4–6 句能构成完整的小论证吗? | | 画面可用性 | 对应时间段是否有人物清楚、字幕稳定的帧? | | 信息密度 | 是否每一句都在推进,而不是重复铺垫? | | 真实性 | 是否能回到原视频验证,没有改写成另一层意思? | | 说话人一致 | 多人素材中,句子是否都属于同一说话人,或是经用户确认、在原视频中相邻的问答? | | 发布价值 | 是否符合用户正在做的文章、帖子或栏目? | 为每个主题记录:标题、起止时间、一句话价值、候选时间点。标题是文件名和内部导航,不会被画进图片。 文字稿在两种模式中的边界不同: - **原生模式**:文字稿只是检索索引,最终字幕以画面像素为准。 - **脚本模式**:文字稿可以进入 `text`,但必须先核对原语义、人名、数字、专有名词和时间点。翻译或压缩过的句子需明确属于后期台词,不能冒充原字幕。 ### 与其他 Skill 协作 - **视频理解/语音转写 Skill**:生成带时间戳文字稿,作为检索索引。 - **选题/内容分析 Skill**:从文字稿提名主题、判断受众价值。 - **写作 Skill**:围绕已选主题写文章或帖子,并引用来源事实。 - **本 Skill**:掌管最终画面、真实时间点、字幕来源标识、裁切/绘制和视觉 QA。 如果某个上游 Skill 未安装,就直接完成必要的文字稿阅读与主题提炼;不要假设一个不存在的 Skill。用户只要求做图时,不要擅自扩展成写文章或发布内容。 ## 阶段 5:把语义时间点校准成可用画面 文字稿时间戳通常落在一句话开始处,容易截到字幕刚出现、上一句残留或无字幕帧。对每个候选时间点生成前、中、后三帧: ```bash 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 analysis/focused-candidates.jpg ``` 选择规则: - 取字幕完整稳定显示后的中间帧,不取切换瞬间; - 相邻时间点必须是不同句,且严格递增; - 同一张图的句子应组成连续表达,允许跳过无信息过渡句; - 第一帧是主画面,优先人物表情、动作或场景完整;多人素材的主画面必须是这些台词的说话人在说话; - 多人素材逐个时间点回看完整画面,确认说话人与字幕都对应文字稿标注;两人交替快或抢话时,字幕可能已切到对方的话; - 避免转场、黑帧、广告贴片、人物闭眼、Logo 穿脸; - 原生模式的字幕文字以画面为准;脚本模式的台词以已审核 JSON 为准。 如果 0.8 秒范围仍找不到稳定字幕,把 `--around` 改为 0.4 或 1.2;不要一次偏移太大,否则可能跳到另一句话。 ## 阶段 6:校准视觉采样区域 原生模式需要完整包住画面已有字幕;脚本模式则需要为后期台词找到背景简洁、对比足够的水平画面条。 在典型时间点预览上下边界: ```bash python3 "<SKILL_DIR>/scripts/native_subtitle_stitch.py" band VIDEO -t 61.2 \ --band-top 0.78 --band-bottom 0.96 \ --out previews/band-preview.jpg ``` 检查两条红线: - 上边界要包含完整的第一行字幕和描边; - 下边界要包含字幕底部,但避免大块黑边; - 单行字幕优先保持约 `0.78–0.96` 的紧凑裁切; - 两行字幕、字幕位置偏高时可尝试 `0.62–0.96` 或 `0.68–0.97`; - 同一期节目字幕位置变化时,至少抽查开头、中段、结尾三个时间点。 脚本模式不使用 `band`,而是用 `render-script --band-center`设定字幕条在原帧中的垂直中心。默认 `0.88`;背景杂乱或与原有字幕重叠时,先从候选帧换画面,再小范围调整中心。 ## 阶段 7:建立最终时间点文件 每张图默认使用 5 个严格递增的时间点:第一帧做主画面,其余四帧做字幕条。 ### 原生字幕 manifest ```json { "images": [ { "title": "模型独立工作时长正在快速增长", "times": [61.6, 69.3, 75.0, 82.4, 88.8] }, { "title": "衡量趋势时不要忽略任务成功率", "times": [104.2, 109.0, 114.7, 121.3, 127.0] } ] } ``` manifest 只记录最终确认的时间点,不把文字稿改写后的句子放进去,避免让人误以为渲染器会重绘文字。 ### 脚本字幕 JSON ```json { "lines": [ {"t": 61.6, "text": "第一句已核对台词"}, {"t": 69.3, "text": "第二句已核对台词"}, {"t": 75.0, "text": "第三句已核对台词"}, {"t": 82.4, "text": "第四句已核对台词"}, {"t": 88.8, "text": "第五句已核对台词"} ] } ``` `text` 必须是单行已审核文字。过长台词先拆句,不依靠极小字号填满一条。翻译时把人名、数字、专有名词和否定关系单独复核。 ## 阶段 8:渲染 ### 原生字幕 ```bash python3 "<SKILL_DIR>/scripts/native_subtitle_stitch.py" render VIDEO \ --manifest manifest.json --out-dir output-v1 \ --band-top 0.78 --band-bottom 0.96 ``` ### 脚本字幕 ```bash python3 "<SKILL_DIR>/scripts/native_subtitle_stitch.py" render-script VIDEO \ --script script.json --out output-v1/01_主题.jpg \ --aspect 3:4 --width 1440 ``` 中日韩文绘制需要 CJK 字体。脚本会先尝试常见系统字体;无法自动找到时,使用 `--font /path/to/font.ttc`。对字体文件同样要遵守其授权条款,不将未授权字体提交到公开仓库。 原生模式默认保留源宽度,先拼源像素、再整图统一等比缩放,高度按真实内容计算。用户未指定比例时不要添加 `--aspect 3:4`;显式指定时,默认对整张拼图统一裁去两侧、最多裁到字幕安全边界,剩余差额才留边;不单独放大主图、不横向裁掉字幕。脚本固定布局仍默认 1440×1920,五个时间点时主画面约占 70%、四条各约占 7.5%。两者条间距为 0。任何输出放大都不等于真实画质提升,应在交付中说明。 用户明确要求调整视觉密度时,读取 [visual-style.md](visual-style.md)。只有确有需要才显式传 `--hero-fraction` 覆盖自动布局。 ## 阶段 9:逐张质检 多图任务先看 `final_contact_sheet.jpg` 发现整体问题,再逐张打开原尺寸 JPG;单图脚本模式直接打开原尺寸成品。 ### 视觉检查 - 主画面主体完整,没有异常切脸、切头或巨大空白; - 每条字幕完整,没有切掉描边、标点或第二行; - 没有同句重复、空字幕、字幕切换残影; - 原生字幕第一句与后续字幕使用同一缩放倍数,保留全部文字;脚本固定布局四条时主画面约占 68–72%,字幕条紧凑相接; - 各条之间没有黑边、白缝、额外间距或缩放变形;原生固定画布两侧统一裁切后的剩余留边是保留字幕的取舍,不是条间距; - 没有广告贴片、进度条、鼠标、通知或无关 UI; - 画面内已有来源标识时保持原样,不自行新增或删除。 - 脚本模式的文字水平居中,白字黑边清晰,不压主体,不与原有 UI 或字幕叠在一起; - 脚本模式的字号不应因为台词过长缩到手机上不可读;此时拆句。 ### 技术检查 - 每张图可正常解码; - 尺寸与目标比例一致; - 文件数量与 manifest 的 `images` 数量一致; - 原生模式的 `原生字幕时间点.json`,或脚本模式的 `lines` JSON 与实际渲染版本一致; - 总览图包含全部成品; - 不同成品不是重复文件。 ### 语义检查 - 一张图只表达一个中心观点; - 五句顺序与原视频一致; - 多人素材每句的说话人与文字稿标注一致;没有把不同人的话拼成一个人的观点; - 原生模式没有用标题或文章文案替换原字幕; - 脚本模式的台词与已审核 JSON 完全一致,而且交付中没有把它误标为原生字幕; - 如果配套写文章,文章观点能够回到视频或其他来源核验。 ## 阶段 10:有界返工 发现问题时只改对应变量: | 问题 | 优先修改 | |---|---| | 字幕刚出现或残留 | 对应时间点 ±0.3–1.5 秒 | | 同句重复 | 换到下一句稳定帧 | | 字幕被裁 | `--band-top` / `--band-bottom` | | 主图不好 | 只换该组第一个时间点 | | 台词少但字幕条很高 | 使用默认自适应布局,移除过小的 `--hero-fraction` | | 主图太矮或太高 | 确认默认自适应仍不合适后,再调整 `--hero-fraction` | | 脚本台词过长 | 先拆句或重选连贯的简短表达,不先压缩字号 | | 脚本文字与背景混在一起 | 换稳定帧,再小幅调整 `--band-center` | | 全组主题不连贯 | 回到文字稿重新选段,不靠换帧硬救 | | 多人素材分不清谁说的 | 回到带说话人标注的文字稿,按说话人重新选段 | | 字幕条是对方的话或上一句 | 对照说话人标注重新回看该时间点,必要时换句 | 每轮改动后重新逐张检查。连续三轮仍找不到稳定画面时,说明该段不适合做原生字幕拼图,换主题或向用户报告限制;不要无限微调。 ## 阶段 11:交付 向用户提供: 1. 输出目录; 2. 成品直接预览,多图任务另提供 `final_contact_sheet.jpg`; 3. 每张成品的标题或用途; 4. 对应模式的时间点 manifest 或 `lines` JSON; 5. 已完成的视觉与技术检查; 6. 明确的字幕模式和文字来源说明; 7. 仍存在的源画质、版权或字幕限制。 只有用户需要分享打包时再生成 ZIP。不要把未经打开检查的图片报告为完成。skills/native-subtitle-quote-image/references/troubleshooting.md5.9 KBf33155c5171bupstream ↗
# 排错手册 按「症状 → 先查什么 → 怎么处理」整理常见失败。下载与字幕轨的细节问题见 [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` 看这些时间点的画面。常见原因是静态封面视频、画面冻结、同一句字幕选了两次,或那一段画面本来没有字幕。 - **处理**:换时间点或换片段;固定机位源可配 `--hero-zoom` 缓解。报错点名两个时间点时,只换那一张卡的时间点就行。觉得判得太严或太松先调 `--duplicate-ratio`(0–0.2,默认 0.005,调高更严);只有确认这正是用户要的效果时,才加 `--allow-duplicate-frames`(与 `--duplicate-ratio` 互斥)。 ### 主图选错了人(双人同框、主持人和嘉宾并排) 渲染器不识别人脸,也不自动选帧:主图就是 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 改过;要重渲某张,先删掉那张图。skills/native-subtitle-quote-image/references/visual-style.md10 KB077051d91d66upstream ↗
# 紧凑型视频字幕拼图视觉规范 当用户强调“好看、紧凑、有节奏、不要台词间隔太宽”,或准备最终视觉质检时读取本文件。规则同时适用于原生字幕和脚本字幕模式;只有脚本模式会绘制字体和描边,原生模式始终保留视频像素。本规范来自对高质量成品的版式测量与视觉归纳;参考原图不随 Skill 分发。 ## 核心判断 3:4 拼图的视觉中心应是主画面,而不是平均分配的五块视频截图。字幕条只承担连续阅读,不应因为台词少而被拉成大块画面。 默认目标: - 原生字幕默认按源画面和字幕条计算高度,不强制 3:4;显式要求固定比例时,默认对整张拼图统一裁去两侧(`--fit crop`),最多裁到字幕安全边界,剩余差额再留边;不分别填满主图和字幕条。 - 脚本字幕固定画布为 3:4;推荐输出 1440×1920,1080×1440 也符合比例。 - 一张图使用 5 个时间点:1 个主画面 + 4 个字幕条。 - 脚本固定布局的 4 个字幕条时,主画面约占总高度 70%,每个字幕条约占 7.5%。原生模式优先保证所有字幕同一缩放倍数,不套用此比例。 - 字幕条首尾直接相接,条间距为 0,不增加边框、留白或装饰分隔线。 - 原生模式的单行字幕默认从源画面的 `0.78–0.96` 高度范围裁切;字幕偏高或两行时再扩大。 ## 原比例布局 用户要求保留横屏构图或原始画面尺寸时,用 `--layout natural`,而不是强制把画面填进 3:4。主图与字幕条只裁切、等比缩放,最终高度为各块实际高度之和;不传 `--width` 时保留源宽度。原生字幕保留到 `--band-bottom` 的主图;脚本字幕默认保留全帧,可按实测边界用 `--frame-top` / `--frame-bottom` 裁去源字幕等区域。`--band-center` 相对裁切后的画面。 裁去底部 28% 后,剩余画面高度就是原高的 72%,不能再拉回原高。最后也不能用直接 resize 强制输出 3:4;确实需要固定比例时回到固定布局重新渲染。画面原比例与“原生字幕”是不同概念,不改变字幕模式。 下面的密度计算和 68–72% 验收仅适用于脚本固定布局;原生模式及原比例布局检查主体几何、文字完整及紧凑拼接,不追求同一个高度比例。 ## 自适应密度 脚本固定布局默认按字幕条数量自动计算主画面比例: ```text 主画面比例 = clamp(1 - 字幕条数量 × 0.075, 0.48, 0.82) ``` 常见结果: | 时间点 | 字幕条 | 主画面比例 | 视觉效果 | |---:|---:|---:|---| | 3 | 2 | 82% | 少量台词时保留大主图,不拉高字幕条 | | 4 | 3 | 77.5% | 适合短观点 | | 5 | 4 | 70% | 默认、最均衡 | | 6 | 5 | 62.5% | 信息较多,仍保持紧凑 | | 7 | 6 | 55% | 接近密度上限,需要重点检查字号与可读性 | 用户明确传入 `--hero-fraction` 时尊重用户值。只有实际版式需要时才覆盖自动值,不要为了“更满”而把主图压得过小。 原生固定布局的此参数仅调整源主图的裁切高度,受可用源像素限制;不能分别缩放主图和字幕条以达成目标比例。原生字幕不重绘、不人为统一原视频中本就不同的字号。 ## 固定机位源与 `--hero-zoom` 优先选多机位、景别有变化的视频。固定单机位源(大学大师课、网课式录制)是高风险素材:六张主图只差表情,整组看起来像同一张图。 确需使用时,用 `--hero-zoom` 给每张卡设不同的主图缩放,例如 `--hero-zoom 1.0,0.9,0.95`,按卡循环,范围 0.8–1.0,默认不启用。它只裁掉更多主图画面再放大,字幕条、文字、条间距和六句卡几何不变;原生模式下裁切窗口不会进入字幕条。注意:这是裁切后放大,源视频清晰度不足时主图会更模糊,不等于真实清晰度提升。 ## 呼吸缝与分隔线 版式默认主图与字幕条硬边相接、条间距为 0。手机上觉得拥挤时可用 `--strip-gap 2`–`4`(条间黑色缝隙)和 `--hero-divider line`(2px 分隔线)。它们是插入的背景像素,不叠加在画面上,所以不会盖住原生字幕;渐变会改动主图下缘的字幕像素,因此不提供。与 `--six-line-card` 不兼容。 ## 字幕区域 ### 单行字幕 从 `--band-top 0.78 --band-bottom 0.96` 开始预览。目标是: - 保留完整文字、描边和标点; - 字幕上下有少量呼吸空间,但不会出现大块无文字背景; - 缩放到最终条高后仍然清楚; - 不切进播放器进度条或画面底部黑边。 ### 两行字幕或位置偏高 不要继续使用窄裁切硬切第二行。先通过 `band` 预览,再按实际位置扩大,例如 `0.62–0.96` 或 `0.68–0.97`。两行字幕会提高字幕条本身的信息密度,需要检查是否仍适合 4 条拼接。 ### 字幕位置变化 同一视频至少抽查开头、中段、结尾。若节目在不同段落改变字幕位置,不能只用一张预览推断整期;换片段或为不同组分别渲染。 ## 主画面选择 主画面承担第一眼吸引力,优先级高于第一句文字是否最完整: 1. 主体面部、手势或关键物体清楚; 2. 人物不闭眼、不处于口型或动作的尴尬过渡; 3. 麦克风、前景物体和画面边缘不异常切断主体; 4. 背景明暗和主体分离,字幕描边能够读清; 5. 第一条字幕位于画面下部,不压脸、不贴底; 6. 避免转场、黑帧、广告、播放器控件、通知和无关 UI。 主画面可以与后续字幕条来自同一场景,但帧本身必须比普通字幕条更完整、更有表现力。 ### 主图构图检查清单 渲染器不识别人脸,也不校验构图;以下由 Agent 在渲染后逐张目测成品主图(固定比例 `--fit crop` 时看裁切后的画面),比例都是近似参考值: | 检查项 | 参考值 | 常见问题 | |---|---|---| | 头顶留白 | 头顶到主图上缘约 ≥8% 主图高度 | 切掉头顶或发际线 | | 下巴与下缘 | 下巴到主图下缘(第一条字幕条上沿)约 ≥5% 主图高度 | 下巴贴着字幕条,像被字幕压住 | | 脸中心垂直位置 | 主图高度约 35–60% | 脸太低像在往下掉,太高顶住上缘 | | 脸中心水平位置 | 主图宽度约 35–65% | 脸挤在一侧,另一侧大片空背景 | 不适用:主体不是人脸(产品、手势、屏幕演示)时,按同样思路检查关键物体是否完整、不贴边。用户明确要特写、侧脸或刻意偏置构图时以用户要求为准。 不达标时按顺序处理: 1. 只换主图时间点:用 `sample 视频 --start T-1.5 --end T+1.5 --interval 0.3`(T 为原时间点秒数,start 不小于 0、end 不超过视频时长)在原时间点前后约 1.5 秒内重找,挑满足清单且不闭眼、不模糊的帧; 2. 固定比例裁切切到人物两侧时,调整 `--crop-center`;它只移动水平裁切窗口,解决不了头顶留白、下巴贴条这类垂直问题,垂直问题只能靠换时间点; 3. 仍找不到时用最接近的一帧出图,在交付说明中写明第几张主图哪一项不达标,不无限微调。 ## 字幕条节奏 - 四条字幕应像连续段落,而不是四张独立海报。 - 每条只保留一个稳定字幕单位;不要在一条里留下上一句残影。 - 相邻字幕语义递进,避免同义重复和长铺垫。 - 背景变化可以增加节奏,但不能以字幕难读、人物异常或画面杂乱为代价。 - 明暗差异很大的条可以保留,这是原视频真实画面;不要额外加纯色背景统一它们。 - 原生模式不重新绘字、不改字体、不人为增加行距,不用文章标题替换视频字幕。 - 脚本模式使用已审核单行台词,白字黑边、水平居中;字号过小时拆句,不通过放大字幕条来补救。 ## 常见失败及修正 | 现象 | 原因 | 修正 | |---|---|---| | 台词之间像隔着大段空白 | 主图比例固定过小,少量字幕条被平均拉高 | 使用自动主图比例,不显式传过小的 `--hero-fraction` | | 每条字幕上下背景太多 | 字幕裁切区域过高 | 单行字幕从 `0.78–0.96` 重新预览 | | 第一条字幕很大,后续字幕很小 | 主图与字幕条分别填满不同形状的区域 | 先拼源像素,再整图统一缩放;原生模式不用 70% 硬填主图 | | 字幕条之间有黑缝或白缝 | 额外边距、画布未贴合或源黑边被裁入 | 条间距保持 0,并收紧字幕区域 | | 文字被切边 | 为追求紧凑直接套用窄裁切 | 以完整字幕为硬条件,扩大 `band` 后重新预览 | | 固定 3:4 上下黑边很厚 | 横屏拼图比 3:4 宽,又用了纯留边 | 保持默认 `--fit crop`;字幕太宽裁不动时,减少过宽的句子或接受部分留边 | | 两侧裁切切到人物 | 主体偏离画面中心 | 用 `--crop-center` 把裁切窗口移向人物;仍不行时改用 `--fit pad` | | 五句话不连贯 | 只按画面挑帧,没有先做语义选段 | 回到文字稿重选连续表达,不靠换帧硬拼 | | 主图人物被切脸 | 时间点或裁切窗口不合适 | 只换第一时间点,必要时调整主图比例 | | 切头顶、下巴贴字幕条或脸偏一侧 | 选帧只看表情,没看构图 | 按「主图构图检查清单」在前后约 1.5 秒内重找;找不到就在交付中说明 | ## 最终视觉验收 交付前在原尺寸和缩略总览两个尺度检查: - 缩略图中主画面明显占主导,四条字幕形成紧凑节奏; - 原尺寸中每个字、描边和标点完整; - 每张主图都过了「主图构图检查清单」,不达标的已在交付中说明; - 脚本固定布局主画面约 68–72%、字幕条合计约 28–32%(默认 4 条时);原生模式检查同源字号没有因各块缩放而变大变小; - 条与条之间没有额外像素间距;原生固定画布为保留完整内容而出现的外侧留边不算条间距; - 没有一条因为无文字背景过多而显得“松”; - 没有为了紧凑牺牲两行字幕完整性; - 原生模式的台词都来自真实视频像素;脚本模式的台词与已审核 JSON 一致;两者时间顺序都正确; - 若成品仍显得松散,先收紧 `band`,再检查时间点数量,最后才手动调整主图比例。skills/native-subtitle-quote-image/references/yt-dlp-and-transcripts.md16 KBa470acbd5449upstream ↗
# URL 获取与时间轴 当输入是 YouTube 等在线视频链接,而不是本地视频时,读取本文件。`yt-dlp` 只负责获取用户有权处理的视频、元数据和字幕时间轴;最终图片仍由 `native_subtitle_stitch.py` 从真实视频帧生成。 不要因为第一次公开请求被 YouTube 拒绝,就告诉用户“这个 Skill 只能读取本地视频”。URL 获取本来就是此 Skill 的正式入口:先尝试无 Cookie 公开访问;若命中登录或机器人验证,再走本文的 Chrome Cookie 授权流程。 ## 先区分两种“字幕” | 内容 | 用途 | 原生字幕模式 | 脚本字幕模式 | |---|---|---|---| | 画面内烧录字幕 | 保留原字幕 | 必须从真实视频帧保留 | 如与后期文字重叠,应换帧或换模式 | | YouTube 字幕轨、VTT/SRT、Whisper 文字稿 | 理解内容、选题、定位时间点 | 只做索引,不能画进成品 | 经复核后可写入 `lines[].text`,必须标记为后期台词 | 有字幕轨不等于视频画面有字幕。下载后必须实际取帧检查。若用户要求原生字幕,但画面没有烧录字幕,停止并说明;只有用户同意后,才使用本 Skill 的 `render-script` 模式,不要偷偷切换。 ## 官方依据 - [yt-dlp 官方 README](https://github.com/yt-dlp/yt-dlp#readme) - [安装说明](https://github.com/yt-dlp/yt-dlp/wiki/Installation) - [External JavaScript 指南](https://github.com/yt-dlp/yt-dlp/wiki/EJS) yt-dlp 当前支持 CPython 3.10+ 和 PyPy 3.11+。完整 YouTube 支持强烈建议 FFmpeg、`yt-dlp-ejs` 和 JavaScript runtime。官方优先推荐 Deno,并默认启用它;Node.js 或 QuickJS 需要通过 `--js-runtimes` 显式启用。Bun 目前仍可用,但官方已将其支持标记为弃用,不应作为新环境首选。 ## 环境检查 先运行 Skill 自带的只读诊断: ```bash python3 "<SKILL_DIR>/scripts/check_environment.py" --url-mode ``` 如果要绘制中日韩台词,同时检查 CJK 字体: ```bash python3 "<SKILL_DIR>/scripts/check_environment.py" --url-mode --script-mode ``` 它不会安装软件,只报告: - Python、Pillow、FFmpeg provider 是否可用; - `yt-dlp` 版本; - Deno 或其他 JavaScript runtime; - 脚本模式所需的 CJK 字体(使用 `--script-mode` 时); - 可选的 Whisper/语音识别能力。 缺少组件时先向用户说明,再取得安装授权。不要擅自修改系统 Python、包管理器或 shell 配置。 ### 安装与更新原则 - 核心渲染依赖:`python3 -m pip install -r "<SKILL_DIR>/requirements.txt"`。 - yt-dlp 可使用官方独立可执行文件,或安装 PyPI 的 `yt-dlp[default]`;`default` extra 会带上官方推荐的 Python 依赖。 - 官方文档当前建议普通用户使用 nightly;若稳定版遇到站点解析问题,先按官方说明更新 nightly,再判断是不是命令或权限问题。 - Deno 使用官方安装方式,当前最低支持 2.3.0;若环境已有 Node.js 22+,可保留 Node,并在每条 yt-dlp 命令中加入 `--js-runtimes node`。 示例(使用 pip 的环境): ```bash python3 -m pip install -U "yt-dlp[default]" ``` 稳定版出现站点解析错误、且用户同意更新时: ```bash python3 -m pip install -U --pre "yt-dlp[default]" ``` 不要把“安装成功”和“能解析当前链接”混为一谈;安装后至少运行: ```bash yt-dlp --version yt-dlp --no-playlist --skip-download --print "%(id)s | %(title)s | %(duration_string)s" "URL" ``` ## 获取顺序 ### 1. 只读检查元数据 ```bash yt-dlp --no-playlist --skip-download \ --print "%(id)s | %(title)s | %(channel)s | %(duration_string)s" \ "URL" ``` 使用 Node.js 时: ```bash yt-dlp --js-runtimes node --no-playlist --skip-download \ --print "%(id)s | %(title)s | %(channel)s | %(duration_string)s" \ "URL" ``` 先确认链接指向单个目标视频。默认添加 `--no-playlist`,避免一个播放列表被意外整批下载。 ### 2. 列出字幕轨 ```bash yt-dlp --no-playlist --list-subs "URL" ``` 记录可用语言标签,不要假设一定叫 `zh`、`en` 或 `en-orig`。 ### 3. 只下载文字时间轴 优先人工字幕,同时允许自动字幕作为备选: ```bash yt-dlp --no-playlist --skip-download \ --write-subs --write-auto-subs \ --sub-langs "zh.*,en.*" --sub-format vtt \ -o "source/%(id)s/%(id)s.%(ext)s" \ "URL" ``` 字幕和视频始终分两条命令下载:字幕命令带 `--skip-download`,视频命令不带任何 `--write-*subs` 参数。这样字幕请求失败(例如 429)不会中止视频下载,视频格式出错也不会白白重复请求字幕。 `zh.*` 这类正则会同时匹配 YouTube 的自动翻译轨(标签形如 `zh-Hans-en`),这类轨道最容易触发 HTTP 429。先看 `--list-subs` 的真实标签,只请求需要的一两个,例如人工字幕 `zh-Hans` 和原声自动字幕 `en-orig`;请求多个语言时加 `--sleep-subtitles 5`。 字幕轨先用来建立“内容—时间点”索引。原生模式不把 VTT 画回图片,也不因为文字稿里有一句话,就假设该时刻画面内烧录字幕完全相同。脚本模式可以使用已复核的 VTT/SRT/Whisper 文字,但必须标明为后期绘制,并将人名、数字、专有名词和翻译含义单独核对。 #### 自动字幕的滚动重复 YouTube 自动字幕(含 `en-orig` 等原声轨)是滚动显示的:VTT 里相邻条目常重复上一行文字,同一句话会出现在两三个条目里,条目开始时间也早于该句在画面上完整显示的时刻。直接拿条目开始时间取帧,容易截到上一句或对方的话,看起来像顺序错乱。使用前先: 1. 去重:合并文字相同或前缀包含关系的相邻条目,每句只保留一条,开始时间取该句首次出现的时间,结束时间取最后一次出现的时间; 2. 用去重后条目的中段而不是开始时间作为候选时间点,再用 `sample -t ... --around 0.8` 回看确认; 3. 自动字幕不分说话人,多人对话素材还要按 [end-to-end-workflow.md](end-to-end-workflow.md#多人对话与访谈先标说话人) 补标说话人。 人工字幕一般没有滚动重复,但同样不带说话人。 ### 4. 下载视频 通常不需要 4K。1080p 足以做 1440×1920 的社交图;输出尺寸可能放大,但不应宣称提升了真实清晰度。 ```bash yt-dlp --no-playlist \ -f "bv*[height<=1080]+ba/b[height<=1080]" \ -o "source/%(id)s/%(id)s.%(ext)s" \ "URL" ``` 用 `scripts/fetch_source.py` 代替直接调 yt-dlp,它把 403/429 的识别、退避重试和尝试日志固定下来(详见下文「用 fetch_source.py 处理 403/429」): ```bash python3 "<SKILL_DIR>/scripts/fetch_source.py" "URL" --mode video \ -f "bv*[height<=1080]+ba/b[height<=1080]" \ -o "source/%(id)s/%(id)s.%(ext)s" ``` `/` 只在格式**不存在**时生效;某个格式存在但下载时返回 HTTP 403,yt-dlp 不会自动改用下一项。遇到 403 时先更新 yt-dlp 并重试一次(`fetch_source.py` 会自动重试这一次),仍失败就按下表逐级换一条 `-f` 重新下载,每级只试一次: | 级别 | `-f` 参数 | 说明 | | --- | --- | --- | | 1 | `bv*[height<=1080][vcodec^=av01]+ba` | 1080p AV1,优先 | | 2 | `bv*[height<=1080][vcodec^=vp09]+ba` | 1080p VP9 | | 3 | `bv*[height<=1080][vcodec^=avc1]+ba[ext=m4a]` | 1080p H.264 + AAC,兼容性最好 | | 4 | `bv*[height<=1080]+ba` | 1080p 任意编码 | | 5 | `bv*[height<=720]+ba` | 降到 720p 的分离流 | | 6 | `b[height<=1080]` | 已合并的单文件;YouTube 上通常只剩 360p | | 7 | `b` | 任意可用的单文件,最后手段 | 下载前先运行 `yt-dlp --no-playlist -F "URL"` 枚举变体,按 AV1 → VP9 → H.264 的顺序择优,并确认列表里有不低于 720p 的视频流。第 5~7 级实际分辨率可能低于 720p:**必须先向用户说明实际分辨率并取得确认,不得静默接受**;用户不接受就停止并报告。 每次下载后立刻自检,通过后才能抽帧、渲染: ```bash python3 "<SKILL_DIR>/scripts/native_subtitle_stitch.py" check-source VIDEO --min-height 720 ``` `check-source` 读取分辨率,并用 FFmpeg 解码前 N 秒(`--seconds`,默认 10),出现任何解码错误(例如 h264 mmco 报错)或低于 `--min-height` 就以非零状态退出。不传 `--min-height` 时,低于 720p 只警告。自检失败的文件删除后,换下一级变体重试,每级只试一次。 每次尝试(含 403、自检失败)都追加一行到工作目录的 `download-attempts.log`,记录级别、`-f` 参数、结果(成功 / HTTP 403 / 自检失败 / 用户拒绝低清)和错误摘要。所有级别用尽就停止,把日志内容报告给用户,不要继续尝试 extractor 参数。 分离的视频和音频需要 FFmpeg 合并。原生字幕取帧不依赖音频,但保留带音频的完整源文件方便复核内容。重复执行时复用已有文件,不要无理由重新下载。 ## 用 fetch_source.py 处理 403/429 `scripts/fetch_source.py` 是 yt-dlp 的调用包装:把错误分类、重试上限和尝试日志固定下来,避免每次凭印象决定重试几次。三种模式对应上面三步:`--mode metadata`、`--mode subs`、`--mode video`。 | 错误类型 | 识别依据 | 重试策略 | | --- | --- | --- | | `rate_limited` | `HTTP Error 429` / `Too Many Requests` | 最多 `--retries` 次(默认 3,上限 6),等待 `--backoff`×2^n,单次封顶 600s | | `forbidden` | `HTTP Error 403` / `Forbidden` | 始终最多 1 次,间隔 5s | | `bot_check` | 要求登录、年龄验证、Cookie | 不重试,直接停下要求授权 | | `other` | 其余失败 | 不重试,原样报出 yt-dlp 报错 | 为什么 403 和 429 策略不同:429 是速率问题,等待本身就是解法;403 多是 yt-dlp 版本落后或该格式的签名 URL 已失效,重试再多也不会变,要靠升级 yt-dlp、装好 JavaScript runtime 或换 `-f`。 行为约定: - 每次尝试(含成功)记一行到 `download-attempts.log`,四列制表符分隔:时间、第几次、错误类型、摘要。`--log` 可改路径。 - 失败时 stderr 同时给出错误类型、具体处理建议和 yt-dlp 原始报错尾部,退出码非零;不静默失败、不把失败当成“只能处理本地视频”。 - 不自行添加 Cookie 参数。用户授权后用 `--extra --cookies-from-browser chrome` 透传,`--extra` 必须放在最后。 - 不绕过 DRM、付费墙、地区限制或平台风控;重试耗尽就停下汇报,不换 IP、不换账号、不遍历浏览器配置。 - 格式回退表仍由调用方逐级执行:脚本只负责单条命令的 403/429 重试,不自己换 `-f`。 ## 没有可用字幕轨 按以下顺序处理: 1. 检查视频描述、章节和人工字幕轨; 2. 检查自动字幕轨; 3. 如果画面本身有烧录字幕,可先用候选帧总览人工选句; 4. 用户确实需要长视频的语义选段时,再询问是否允许使用本地 Whisper 或环境中已有的语音转写 Skill。 Whisper 是可选上游,用来生成带时间戳文字稿。它的识别文本不能替代画面内原生字幕;脚本模式需要使用它时,也必须先校对文本,并回到视频帧验证时间点。 ## 登录、Cookies 与访问限制 - 只处理用户有权访问、下载和再利用的内容。 - 先执行一次不带 Cookie 的元数据检查。不要把 Cookie 作为所有公开视频的默认参数。 - 遇到 `Sign in to confirm you’re not a bot`、登录、年龄验证或用户自己的非公开视频时,不要退回“只能处理本地视频”;先说明原因并取得授权,再使用 `--cookies-from-browser chrome`。 - 不要求用户粘贴账号密码,不导出或提交 Cookie 文件,不把浏览器配置、访问令牌或绝对路径写入仓库。 - 不绕过 DRM、付费墙、地区限制或其他访问控制。 - Cookie 命令只用于当前来源获取,不得显示 Cookie 内容,也不得把 Cookie 写入日志、来源记录或交付物。 - Cookies 失败时停止并报告,不要遍历或反复尝试多个浏览器账户。 ### Chrome Cookie 授权流程 只在无 Cookie 请求明确被访问验证拦截后执行: 1. 向用户复述真实错误,例如 YouTube 要求“登录以确认不是机器人”。 2. 询问:`是否允许我让 yt-dlp 临时读取 Chrome 中已登录的 YouTube Cookie?它只用于获取这个链接的视频和字幕,不会导出、保存或上传 Cookie。` 3. 用户明确同意后,把 `--cookies-from-browser chrome` 加到这个 URL 后续所有 yt-dlp 命令,而不是只加在第一次探测命令上。 4. 默认只读 Chrome 当前默认配置。若机器上有多个 Chrome 配置且默认配置无效,停止并询问用户要使用哪个配置;不要自行扫描所有配置。 5. 若用户拒绝,提供两种清晰选择:让用户自行下载视频后按本地模式继续,或结束 URL 任务。不要把这种受限后的备选说成 Skill 的固有限制。 授权后的元数据检查: ```bash yt-dlp --cookies-from-browser chrome --js-runtimes node \ --no-playlist --skip-download \ --print "%(id)s | %(title)s | %(channel)s | %(duration_string)s" \ "URL" ``` 授权后的字幕轨检查与下载: ```bash yt-dlp --cookies-from-browser chrome --js-runtimes node \ --no-playlist --list-subs "URL" yt-dlp --cookies-from-browser chrome --js-runtimes node \ --no-playlist --skip-download \ --write-subs --write-auto-subs \ --sub-langs "zh.*,en.*" --sub-format vtt \ -o "source/%(id)s/%(id)s.%(ext)s" \ "URL" ``` 授权后的视频下载: ```bash yt-dlp --cookies-from-browser chrome --js-runtimes node \ --no-playlist \ -f "bv*[height<=1080]+ba/b[height<=1080]" \ -o "source/%(id)s/%(id)s.%(ext)s" \ "URL" ``` 如果环境使用 Deno,删除 `--js-runtimes node` 即可,Cookie 规则不变。若默认 Chrome 配置不含有效 YouTube 会话,可在用户明确指定配置后使用 yt-dlp 支持的 `chrome:PROFILE` 形式;不要猜测配置名。读取失败、系统钥匙串拒绝访问或站点仍拒绝请求时,只重试一次经过用户确认的同一配置,然后停止并报告具体错误。 ## 常见故障 ### `yt-dlp` 有版本但 YouTube 格式不完整 先看诊断里是否存在 JavaScript runtime。Deno 默认启用;Node.js 环境必须显式添加: ```bash yt-dlp --js-runtimes node ... ``` 随后更新 yt-dlp。不要先改一串实验性 extractor 参数,因为这会让工作流难以复现。 ### YouTube 要求登录以确认不是机器人 这是来源访问验证,不代表 Skill 只能处理本地视频。按“Chrome Cookie 授权流程”先取得用户授权,再让同一 URL 的元数据、字幕和视频命令都带上 `--cookies-from-browser chrome`。用户没有授权时才停止联网获取,并给出本地文件备选。 ### 字幕语言下载不到 先运行 `--list-subs`,按真实语言标签修改 `--sub-langs`。不要把自动翻译字幕当成人工原字幕。 ### 视频下载报 HTTP 403 403 通常只针对某个具体格式,或说明 yt-dlp 版本已落后于站点改动。`fetch_source.py` 会自动重试一次并把这次记入日志;仍失败时先更新 yt-dlp 并确认 JavaScript runtime 生效,再按“下载视频”一节的格式回退表逐级重试。若所有格式都返回 403,且无 Cookie 的元数据请求也被拒,转到“登录、Cookies 与访问限制”处理,不要循环重试。 ### 字幕下载报 HTTP 429 429 表示请求过于频繁,多见于自动翻译字幕轨。处理顺序: 1. 确认字幕命令与视频命令是分开的,视频下载不受影响。 2. 改用 `--list-subs` 中的具体标签,去掉自动翻译轨,只请求一两个语言。 3. 加 `--sleep-requests 1 --sleep-subtitles 5`,等待几分钟后重试一次;用 `fetch_source.py --mode subs` 时这步的退避等待已内置,按 `--retries` / `--backoff` 调整即可。 4. 仍失败时,用已拿到的其他语言字幕定位时间点,或在用户同意后用 Whisper 转写;不要反复请求同一字幕轨。 ### 视频下载成功,但图片里没有字幕 这不是取帧失败,而是原生字幕条件不成立。说明该视频只有独立字幕轨;若用户同意后期绘制,转用 `render-script`,否则停止。 ### 下载很慢或中断 保留工作目录和分片,重试同一条命令以复用缓存。连续失败后报告网络或站点限制,不要无限重试。skills/native-subtitle-quote-image/agents/openai.yaml467 B1d68fb0801adupstream ↗
interface: display_name: "原生字幕拼图" short_description: "读取视频,选句取帧,生成 3:4 或保留原比例的字幕拼图" default_prompt: "使用 $native-subtitle-quote-image 把这个视频或链接做成紧凑字幕拼图;若用户未指定模式,先问‘您当前是选择原生字幕还是脚本字幕?’,简述两者区别并等待选择;随后检查来源、字幕类型和环境,再选句、取帧、渲染并质检。"skills/native-subtitle-quote-image/requirements.txt33 Bb47f6bd94a71upstream ↗
imageio-ffmpeg>=0.5 Pillow>=10.0skills/native-subtitle-quote-image/VERSION7 B46b81d815a23upstream ↗
2.11.0README.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/chengyi-ai-native-subtitle-quote-image-skills-native-subtitle-quote-image.md