# MaterialSub

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

## 主要功能

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

## 引用水印工作流

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

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

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

## 安装

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

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

```text
$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，用于精确还原默认字幕样式；也可以明确接受字体替代

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

```bash
python3 skills/materialsub/scripts/preflight.py
```

## 开发验证

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

## 上游项目与致谢

MaterialSub 是基于 [pengchujin/JZSub](https://github.com/pengchujin/jzsub) 开发的衍生项目，当前注明参考的上游提交为 [`222a90265d2a8797ca258eb1a980cee0863a8311`](https://github.com/pengchujin/jzsub/commit/222a90265d2a8797ca258eb1a980cee0863a8311)。

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

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

## 许可证与使用边界

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

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