Video Transcript Explainer

Video Transcript Explainer

Goal

Produce a high-quality Chinese lecture handout (notes-body.tex -> notes.tex -> notes.pdf) that is complete enough for a diligent reader to master the video without watching it.

The handout must:

• scale in length with video duration and content density
• proactively teach prerequisite knowledge that the speaker assumes
• preserve the full reasoning chain (not only conclusions)
• cover late-video sections with the same rigor as early sections

When To Use

• The user wants subtitle extraction + deep Chinese lecture notes + PDF.
• The user expects a targeted, teachable handout, not a brief summary.
• The user wants adaptive page count (different videos should produce different lengths).

Procedure

1. Transcript first (do not change acquisition logic)

• Use VIDEO_ROOT=~/Desktop/bilibili-video.
• Keep output under "$VIDEO_ROOT/output".
• Reuse an existing transcript.txt for the same video unless the user explicitly asks for --refresh.
• Run:

UV_CACHE_DIR="$VIDEO_ROOT/.uv-cache" uv run --with yt-dlp --with mlx-whisper python ~/.codex/skills/video-transcript-explainer/scripts/video_transcript.py ""

• This step is network-dependent; prefer escalated execution in sandboxed environments.
• Add --cookies /path/to/cookies.txt only for gated videos.
• Add --save-cookies-from-browser chrome once if the user wants reusable Bilibili login cookies.
• Add --refresh only when explicitly requested.

1. Keep transcript artifacts in one place

• Keep all transcript outputs under ~/Desktop/bilibili-video/output.
• Do not write transcript artifacts outside that folder.

1. Enter the video output directory and inspect inputs

• Read transcript.txt first.
• Read metadata.json when present.
• Typical downstream artifacts:
• notes-body.tex
• note-title.txt
• notes.tex
• notes.pdf

1. Build a coverage plan before drafting

• Identify major topic segments from the transcript.
• For each segment, record internally:
• What question this segment answers
• Which details are easy to miss
• What prerequisite knowledge a reader might lack
• Ensure the plan includes the entire video timeline, including the final third.

1. Decide autonomously whether to use subagents

• Never use subagents for transcript extraction itself.
• Subagents are optional acceleration, not mandatory.
• If runtime/policy blocks subagents, continue locally without blocking.
• Heuristics that favor subagents:
• more than 6000 Chinese characters
• more than 120 timestamped blocks
• multiple dense topic shifts
• high formula/code/comparison density
• If using subagents, split work into 2-4 coherent chunks (time ranges or topic bundles).
• Assign each subagent a concrete task package and require outputs for:
• segment intent and teaching objective
• corrected key statements (ASR repairs)
• LaTeX-ready \section / \subsection draft
• formulas, code, examples, pitfalls worth emphasizing
• prerequisite assumptions that need bridging
• ambiguities requiring main-agent arbitration
• The main agent must unify terminology, resolve contradictions, normalize structure, and produce one consistent notes-body.tex.

1. Draft as a standalone teachable handout (not a thin summary)

• Replace spoken fillers with clear teaching prose.
• Preserve nontrivial details, comparisons, caveats, and speaker intent.
• Fix obvious ASR errors by context.
• Add prerequisite bridges where needed so the text is self-contained.
• Prefer expansion over compression when completeness is at risk.
• Do not use vague placeholders such as "not elaborated here".
• Default teaching shape per major topic:
• one-sentence overview
• detailed explanation
• logical step-by-step flow
• plain-language interpretation of key concepts
• for technical/math content: intuition + example + input/output relationship

1. Enforce adaptive note length

• Never default to a fixed page target.
• Estimate expected depth from:
• metadata.json duration (if available)
• transcript character count
• timestamped block count
• number of topic shifts
• density of formulas/code/comparisons/caveats
• Planning heuristic (not a hard quota):
• 10-20 min: usually 5-9 pages
• 20-35 min: usually 8-14 pages
• 35-50 min: usually 12-20 pages
• 50-70 min: usually 16-28 pages
• 70+ min: usually 22-40+ pages
• Dense technical lectures should land in the upper half or exceed the range.
• If a 60-minute technical video produces roughly the same length as a 20-minute one, treat it as over-compressed and expand before shipping.

1. Minimum depth standard per major topic

• Unless clearly irrelevant, cover:
• what it is
• why it matters
• what problem it solves
• how it connects to previous/next topics
• inputs/outputs or participating entities
• step-by-step mechanism
• why this approach vs alternatives
• at least one intuition, analogy, or concrete scenario
• common pitfalls, boundary conditions, failure modes
• If a technical topic states conclusions without reasoning, that section is incomplete.

1. Clean the title before rendering

• Inspect raw video title.
• If noisy/duplicated/SEO-heavy/too long, write a polished short title to /note-title.txt.
• Prefer clean forms like:
• Course Name Lecture X: Topic
• Course Name: Topic
• Topic Deep Dive
• Remove marketing noise and repetitive tags.

1. Render with the existing template pipeline

• Write /notes-body.tex first.
• Run:

python ~/.codex/skills/video-transcript-explainer/scripts/render_notes_pdf.py --transcript "" --metadata "/metadata.json" --body "/notes-body.tex" --output-dir ""

• The renderer prefers note-title.txt when present.
• After rendering, sanity-check PDF page count when tooling allows; otherwise use notes-body.tex size as a proxy.
• If output is materially shorter than the coverage plan for that video's duration/density, expand and rerender.

1. notes-body.tex writing rules

• Use \section{...} and \subsection{...}.
• Prefer teaching order over strict transcript order.
• Every major section must contain substantive explanation.
• Define specialized terms in Chinese on first use.
• Use importantbox, knowledgebox, warningbox only when they add value.
• Formula rule:
• explain intuitively in Chinese first
• show $$...$$
• define symbols
• explain sensitivity: what changes when key variables change
• Code rule:
• use lstlisting with a short caption
• explain problem, inputs/outputs, and design rationale
• Preserve explicit comparisons and trade-offs when the speaker compares approaches.
• Add prerequisite bridge subsections whenever a careful reader could get stuck.
• For long/dense videos, substantially longer notes are expected and desirable.
• End with a final summary section (use a Chinese heading equivalent to "Summary" in the generated notes).
• Do not append recommendation sections unless explicitly requested.

1. Quality gate before final render

• Read notes-body.tex once as a student who did not watch the video.
• Expand before shipping if any answer is "no":
• Can I reconstruct the full lecture storyline, not just isolated conclusions?
• Are first-time technical terms understandable at first mention?
• Does each formula include intuition, symbol definitions, and practical use?
• Does each code block explain what problem it solves?
• Are important late-video topics covered with equal depth?
• Is reasoning explained, not merely summarized?
• Is the handout length aligned with duration, topic count, and technical density?
• For longer videos, is there clearly more substantive explanation instead of template reuse?
• Could a diligent reader learn the full lesson from this PDF alone?
• If the last answer is not a confident "yes", keep expanding.

1. Delivery

• Return a concise Chinese summary to the user.
• Point to:
• transcript.txt
• notes.tex
• notes.pdf
• If TeX compilation fails, report the error clearly and keep generated .tex artifacts.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: CrysGate
• Source: CrysGate/AgentSkills
• License: MIT

Install and usage instructions live in the source repository linked above.