skill-materialsub/README.md

MaterialSub

MaterialSub 是一个面向 Codex 的视频下载与双语字幕交付 Skill。它可以在用户有权访问和保存视频的前提下，下载平台可用的最高画质视频与封面，保留原始字幕，使用当前 Codex 会话模型翻译字幕，并生成经过校验的双语硬字幕 MP4。

主要功能

• 最高画质下载：优先获取最佳视频与音频，尽可能保留源编码，只在最终烧录时重新编码视频。
• 多种交付模式：支持完整成片、仅视频、仅原始字幕、双语字幕文件。
• 双语字幕：锁定原文、分批翻译、保持批间上下文，并生成双语 SRT/ASS。
• 授权嵌入式 HLS：当 yt-dlp 不支持页面，但浏览器能在用户现有权限下正常播放时，可处理经过浏览器确认的媒体播放列表。
• Chrome 登录态：需要身份验证时可在本地静默读取浏览器登录态，不导出或显示 Cookie 内容。
• 引用水印：任务开始前询问是否添加引用，支持作者、论文标题、期刊/DOI 三行结构及经确认的内部交流说明。
• 一次烧录：双语字幕与引用水印在同一次 FFmpeg 编码中完成。
• 交付校验：通过清单、SHA-256 和烧录回执核对最终成片、字幕和引用水印。

引用水印工作流

如果用户选择添加引用水印，MaterialSub 会先收集并确认：

1. 作者；
2. 文章标题；
3. 期刊、DOI 及其他出版信息；
4. 是否使用默认说明：内容引自网络，仅供内部交流。

默认样式为左上角整体半透明底板：第一行使用较小的浅灰色说明，后三行使用白色完整引用。只有用户确认视频用于内部交流时，才会添加默认说明。

安装

git clone https://git.cellnucle.us/hugo/materialsub.git
mkdir -p ~/.codex/skills
cp -R materialsub/skills/materialsub ~/.codex/skills/

然后在新的 Codex 任务中调用：

$materialsub https://example.com/authorized-video

交付模式

模式	说明	主要产物
full（默认）	完整下载、翻译、渲染和烧录流程	视频、封面、字幕、双语硬字幕 MP4
video	仅下载视频，不翻译、不烧录	视频、封面及平台提供的原始字幕
subs	仅获取原始字幕，不下载视频流	原始字幕及衍生 SRT
bilingual-subs	翻译并生成字幕文件，不烧录视频	原始字幕、双语 SRT/ASS

运行依赖

• Python 3.10+
• yt-dlp
• 带 libass 的 FFmpeg/ffprobe
• YouTube 提取需要时使用 Deno 2.3+
• MiSans Bold，用于精确还原默认字幕样式；也可以明确接受字体替代

长时间下载前可以先运行预检：

python3 skills/materialsub/scripts/preflight.py

开发验证

python3 skills/materialsub/scripts/fetch_video.py --self-test
python3 -m unittest discover -s skills/materialsub/tests -p 'test_*.py'

上游项目与致谢

MaterialSub 是基于 pengchujin/JZSub 开发的衍生项目，当前注明参考的上游提交为 222a90265d2a8797ca258eb1a980cee0863a8311。

原项目采用 MIT License，并保留 Copyright (c) 2026 pengchujin。本仓库在 LICENSE 中完整保留原版权与许可条款，并在 NOTICE.md 中记录项目来源和修改关系。

MaterialSub 在原项目基础上扩展了交付模式、依赖与字体预检、授权嵌入式 HLS、结构化引用水印以及校验回执等功能。

许可证与使用边界

本项目采用 MIT License。平台标识、视频、论文和商标归各自权利人所有。

请只下载、处理和传播你有权使用的内容。MaterialSub 不绕过 DRM、付费墙、验证码或平台安全机制；免责声明和引用水印也不会自动赋予转载或公开传播权限。