From 555ed525f69059fb7f4a28373f459031d3ffe8ab Mon Sep 17 00:00:00 2001 From: Hugo-YH Date: Tue, 25 Aug 2026 13:11:33 +0800 Subject: [PATCH] docs: provide Chinese README --- README.md | 67 +++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 45 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 902ccc6..d18bd7d 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,30 @@ # MaterialSub -MaterialSub is a Codex skill for authorized video acquisition and bilingual subtitle delivery. It downloads the highest available quality, preserves source subtitles, translates with the active Codex session model, renders bilingual captions, and produces a verified hard-burned MP4. +MaterialSub 是一个面向 Codex 的视频下载与双语字幕交付 Skill。它可以在用户有权访问和保存视频的前提下，下载平台可用的最高画质视频与封面，保留原始字幕，使用当前 Codex 会话模型翻译字幕，并生成经过校验的双语硬字幕 MP4。 -It also supports browser-confirmed authorized embedded HLS sources and an optional citation watermark workflow with: +## 主要功能 -- explicit user approval before processing; -- structured author, article-title, and publication/DOI lines; -- an optional approved internal-use notice; -- one clean translucent panel at the top left; -- checksum-bound citation and final-video receipts. +- **最高画质下载**：优先获取最佳视频与音频，尽可能保留源编码，只在最终烧录时重新编码视频。 +- **多种交付模式**：支持完整成片、仅视频、仅原始字幕、双语字幕文件。 +- **双语字幕**：锁定原文、分批翻译、保持批间上下文，并生成双语 SRT/ASS。 +- **授权嵌入式 HLS**：当 yt-dlp 不支持页面，但浏览器能在用户现有权限下正常播放时，可处理经过浏览器确认的媒体播放列表。 +- **Chrome 登录态**：需要身份验证时可在本地静默读取浏览器登录态，不导出或显示 Cookie 内容。 +- **引用水印**：任务开始前询问是否添加引用，支持作者、论文标题、期刊/DOI 三行结构及经确认的内部交流说明。 +- **一次烧录**：双语字幕与引用水印在同一次 FFmpeg 编码中完成。 +- **交付校验**：通过清单、SHA-256 和烧录回执核对最终成片、字幕和引用水印。 -## Install +## 引用水印工作流 + +如果用户选择添加引用水印，MaterialSub 会先收集并确认： + +1. 作者； +2. 文章标题； +3. 期刊、DOI 及其他出版信息； +4. 是否使用默认说明：`内容引自网络，仅供内部交流`。 + +默认样式为左上角整体半透明底板：第一行使用较小的浅灰色说明，后三行使用白色完整引用。只有用户确认视频用于内部交流时，才会添加默认说明。 + +## 安装 ```bash git clone https://git.cellnucle.us/hugo/materialsub.git @@ -18,43 +32,52 @@ mkdir -p ~/.codex/skills cp -R materialsub/skills/materialsub ~/.codex/skills/ ``` -Then invoke it in a new Codex task: +然后在新的 Codex 任务中调用： ```text $materialsub https://example.com/authorized-video ``` -## Requirements +## 交付模式 + +| 模式 | 说明 | 主要产物 | +|---|---|---| +| `full`（默认） | 完整下载、翻译、渲染和烧录流程 | 视频、封面、字幕、双语硬字幕 MP4 | +| `video` | 仅下载视频，不翻译、不烧录 | 视频、封面及平台提供的原始字幕 | +| `subs` | 仅获取原始字幕，不下载视频流 | 原始字幕及衍生 SRT | +| `bilingual-subs` | 翻译并生成字幕文件，不烧录视频 | 原始字幕、双语 SRT/ASS | + +## 运行依赖 - Python 3.10+ - yt-dlp -- FFmpeg/ffprobe with libass -- Deno 2.3+ for YouTube extraction when required -- MiSans Bold for exact subtitle rendering; font substitution can be explicitly accepted +- 带 libass 的 FFmpeg/ffprobe +- YouTube 提取需要时使用 Deno 2.3+ +- MiSans Bold，用于精确还原默认字幕样式；也可以明确接受字体替代 -Run the preflight before a long download: +长时间下载前可以先运行预检： ```bash python3 skills/materialsub/scripts/preflight.py ``` -## Verify +## 开发验证 ```bash python3 skills/materialsub/scripts/fetch_video.py --self-test python3 -m unittest discover -s skills/materialsub/tests -p 'test_*.py' ``` -## Upstream and attribution +## 上游项目与致谢 -MaterialSub is a derivative work based on [JZSub by pengchujin](https://github.com/pengchujin/jzsub), referenced at upstream commit [`222a90265d2a8797ca258eb1a980cee0863a8311`](https://github.com/pengchujin/jzsub/commit/222a90265d2a8797ca258eb1a980cee0863a8311). +MaterialSub 是基于 [pengchujin/JZSub](https://github.com/pengchujin/jzsub) 开发的衍生项目，当前注明参考的上游提交为 [`222a90265d2a8797ca258eb1a980cee0863a8311`](https://github.com/pengchujin/jzsub/commit/222a90265d2a8797ca258eb1a980cee0863a8311)。 -The original project is licensed under the MIT License and carries `Copyright (c) 2026 pengchujin`. The original copyright and license terms are preserved in [LICENSE](LICENSE), with additional provenance recorded in [NOTICE.md](NOTICE.md). +原项目采用 MIT License，并保留 `Copyright (c) 2026 pengchujin`。本仓库在 [LICENSE](LICENSE) 中完整保留原版权与许可条款，并在 [NOTICE.md](NOTICE.md) 中记录项目来源和修改关系。 -MaterialSub adds and extends behavior including delivery modes, dependency/font preflight, authorized embedded-HLS ingestion, structured citation watermarks, and checksum-bound delivery verification. +MaterialSub 在原项目基础上扩展了交付模式、依赖与字体预检、授权嵌入式 HLS、结构化引用水印以及校验回执等功能。 -## License +## 许可证与使用边界 -MIT. See [LICENSE](LICENSE). Platform logos, media, publications, and trademarks remain the property of their respective owners. +本项目采用 [MIT License](LICENSE)。平台标识、视频、论文和商标归各自权利人所有。 -Only download, transform, and distribute material you are authorized to use. MaterialSub does not bypass DRM, paywalls, CAPTCHAs, or platform safety controls. +请只下载、处理和传播你有权使用的内容。MaterialSub 不绕过 DRM、付费墙、验证码或平台安全机制；免责声明和引用水印也不会自动赋予转载或公开传播权限。