---
## What it does
This open Agent Skill starts with a local video or an online video the user has the right to process. It handles source acquisition, transcript-assisted discovery, topic and quote selection, exact frame calibration, compact collage rendering, and per-image QA.
It supports two explicitly separated subtitle modes. Native mode preserves the video pixels unchanged. Scripted mode draws reviewed timestamped copy onto real video frames and identifies that text as post-produced subtitles.
The repository includes:
- a standalone Skill for compatible agents;
- a Codex-compatible plugin package;
- a URL workflow covering `yt-dlp`, Deno/Node, and auxiliary subtitle tracks;
- a transcript-to-topic method that always returns to real video frames and timestamps;
- candidate-frame contact sheets with timestamps;
- local tools for focused frame candidates, subtitle-band previews, native or scripted 3:4 JPGs, timestamp manifests, and contact sheets;
- a compact visual style guide that fixes oversized subtitle strips, excessive spacing, and weak hero-frame hierarchy;
- a read-only environment checker for local, URL, and CJK scripted-subtitle modes.
## Two subtitle modes
| Mode | Use it when | Text source in the output | CLI |
|---|---|---|---|
| **Native subtitles** | Subtitles remain in screenshots after the player's CC control is disabled, and the user wants the original subtitles | Video pixels only; no OCR redraw, translation, or rewriting | `render` |
| **Scripted subtitles** | Reviewed quotes, translations, or points should be drawn onto real frames using the demo layout | Reviewed `lines[].text`, explicitly identified as post-produced copy | `render-script` |
If a user requests native subtitles but the video only has a switchable track, the agent must explain the limitation. It may switch to scripted mode only after the user agrees.
## Complete workflow
```text
Local video / YouTube URL
↓
yt-dlp obtains video, metadata, and auxiliary subtitle tracks (URL mode)
↓
Inspect real frames and distinguish burned-in subtitles from separate tracks
↓
Subtitle track or Whisper builds a timestamped content index (optional)
↓
Video analysis / topic / writing Skills propose themes (optional)
↓
Lock native or scripted subtitle mode
↓
Return to real frames and calibrate timestamps and hero frames
↓
Manifest / lines JSON → compact 3:4 render → per-image QA
```
The central rule is: **native-mode text comes only from video pixels; scripted-mode text comes only from reviewed JSON and must never be presented as native.**
Three modes are supported:
1. **Local finished-video mode**: select quotes, extract frames, and render from a local video. `yt-dlp` is unnecessary.
2. **Full URL mode**: use `yt-dlp` to obtain a video, metadata, and auxiliary timeline the user has the right to process, then choose a subtitle mode.
3. **Content-production mode**: read the video, select topics, write an article or post, and create subtitle visuals. Upstream content Skills help with analysis; this Skill remains the source of truth for timestamps, real frames, subtitle-source labels, and QA.
URL mode starts with a public request. If YouTube responds with “Sign in to confirm you’re not a bot,” an age check, or an access check for the user’s own non-public video, the agent must not misdiagnose the Skill as local-only. It should explain the error and ask whether `yt-dlp` may temporarily read the signed-in Chrome session. After approval, metadata, subtitle, and video commands for that URL all keep `--cookies-from-browser chrome`. Cookies are never exported, saved, uploaded, or committed.
### Component layers
| Component | Local mode | URL mode | Role |
|---|---:|---:|---|
| `native-subtitle-quote-image` | Required | Required | Frame selection, cropping, collage rendering, and final QA |
| Python 3.10+ | Required | Required | Runs the Skill scripts |
| Pillow | Required | Required | Cropping, collage composition, and JPG export |
| `imageio-ffmpeg` or FFmpeg | Required | Required | Video decoding and exact frame extraction |
| `yt-dlp` | Not needed | Required | Online video, metadata, and subtitle-track acquisition |
| Deno, or explicitly enabled Node.js | Not needed | Required for full YouTube support | Full YouTube format extraction |
| Whisper / speech-to-text Skill | Optional | Optional | Builds a timeline when no subtitle track is available |
| CJK font | Required for CJK scripted copy | Required for CJK scripted copy | Draws Chinese, Japanese, or Korean copy; not needed in native mode |
| Topic, writing, or video-understanding Skill | Optional | Optional | Proposes themes and produces companion content from the transcript |
Detailed implementation guides (Chinese; the commands are language-independent):
- [URL acquisition, yt-dlp, Deno/Node, and timelines](skills/native-subtitle-quote-image/references/yt-dlp-and-transcripts.md)
- [End-to-end topic selection, frame calibration, rendering, and QA](skills/native-subtitle-quote-image/references/end-to-end-workflow.md)
- [Compact hero, subtitle-strip density, and visual QA rules](skills/native-subtitle-quote-image/references/visual-style.md)
## Demo
All images below are **scripted-subtitle mode** examples made from real video frames and reviewed Chinese copy. They demonstrate frame selection, hero height, strip density, and visual QA; they do not imply that the source frames originally contained these Chinese subtitles.
### Single scripted-subtitle collage
