Initial MaterialSub release

Derived from pengchujin/jzsub at 222a90265d2a8797ca258eb1a980cee0863a8311; preserve the upstream MIT license and attribution.
2026-08-25 13:07:03 +08:00
commit e27cc22cfb
24 changed files with 7620 additions and 0 deletions
@@ -0,0 +1,56 @@
+# Citation watermark
+
+Use this only when a delivered MP4 will be hard-burned and the user has approved a citation watermark.
+
+## Citation decision
+
+Before any preflight, download, translation, or burn, ask `是否添加引用水印？` Do not infer consent from the presence of a paper or journal URL.
+
+If declined, continue without a citation watermark. If approved, ask `请提供这个视频需要显示的完整引用文本，并确认是否使用“内容引自网络，仅供内部交流”。` Stop the workflow and wait for the answer. Use the notice only when the user confirms internal circulation. Treat the user-provided citation as authoritative: preserve its author order, title, venue, issue or article number, DOI and year.
+
+Structure the citation into exactly three semantic lines—authors; article title; journal, DOI and other publication details—and repeat the final layout for confirmation. Do not change the wording or punctuation while splitting it. If the boundaries are ambiguous, ask the user instead of guessing. When the original request already contains the citation, structure and repeat it rather than asking for it again.
+
+Do not independently replace, complete, or rewrite user-provided citation text. If the user asks for help finding or formatting it, obtain the citation from the publisher's Cite metadata or a persistent-identifier record, present the proposed complete text, and wait for explicit approval. Never guess missing bibliographic fields.
+
+The default internal layout is:
+
+```text
+内容引自网络，仅供内部交流
+
+<authors>
+<article title>
+<journal, DOI, and other publication details>
+```
+
+The notice is 4 px smaller and light gray; the citation is white. All lines are left aligned on one rectangular 50%-opaque black panel with proportional padding at the top left. Preserve the explicit three citation lines; wrap within a line only when it cannot fit the panel. Do not use per-line backgrounds.
+
+A DOI, PMID, arXiv ID or other persistent identifier already supplies a stable route to the source, so do not add a webpage URL. If there is no persistent identifier, offer the canonical public article or video page URL as an optional final line. Add it only with user approval. Never include player manifests, CDN media URLs, signed URLs, authentication parameters or redirect URLs.
+
+## Bind and burn
+
+After `download-manifest.json` exists and before burning, bind the approved text:
+
+```bash
+python3 <skill-dir>/scripts/citation_watermark.py \
+  "<job-dir>/download-manifest.json" \
+  --authors "<authors>" \
+  --title "<article title>" \
+  --publication "<journal, DOI, and other publication details>" \
+  --notice
+```
+
+Omit `--notice` unless the internal-use statement was confirmed. Use `--notice "<approved custom notice>"` for different approved wording. Use `--include-source-url` only for the approved canonical-URL exception above. The command writes `citation-watermark.txt`, preserves the semantic line structure, records its checksum and fixes the position to `top-left` in the download manifest. Legacy `--citation` and `--citation-file` remain available for user-specified layouts.
+
+Pass that exact file to the one final encode:
+
+```bash
+python3 <skill-dir>/scripts/burn_subtitles.py \
+  "<source-master>" \
+  "<job-dir>/subtitles/rendered/bilingual.ass" \
+  "<burn-output>" \
+  --citation-file "<job-dir>/citation-watermark.txt"
+```
+
+The burn writes `<burn-output>.citation.json`. `verify_delivery.py` checks the final MP4 checksum, citation checksum and top-left position against that receipt. A declared watermark without a matching receipt is not complete.
+
+For `video`, `subs`, or `bilingual-subs` delivery, explain that adding a visual watermark requires an encoded MP4 and confirm changing the deliverable to `full` before proceeding.