# 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.

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.

## Install

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

Then invoke it in a new Codex task:

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

## Requirements

- 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

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).

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).

MaterialSub adds and extends behavior including delivery modes, dependency/font preflight, authorized embedded-HLS ingestion, structured citation watermarks, and checksum-bound delivery verification.

## License

MIT. See [LICENSE](LICENSE). Platform logos, media, publications, and trademarks remain the property of their respective owners.

Only download, transform, and distribute material you are authorized to use. MaterialSub does not bypass DRM, paywalls, CAPTCHAs, or platform safety controls.