lecture-transcribe

name: lecture-transcribe description: Produce a lecture transcript plus a final expert-level lecture_notes.md from a YouTube link or local audio/video file. Use when the user wants subtitles and a real study note, not a transcript dump. disable-model-invocation: true argument-hint: [source] allowed-tools: Bash Read Edit

Lecture Transcribe

Run this skill manually:

/lecture-transcribe "https://www.youtube.com/watch?v=..."
/lecture-transcribe "/path/to/lecture.mp4"
/lecture-transcribe "/path/to/audio.mp3"

The goal is always:

produce lecture.srt
produce lecture.txt
produce lecture_notes.md

The final markdown note must be written by you, the calling agent, after the pipeline finishes. Do not delegate the final note-writing to a helper script.

Non-negotiable output rules

Never claim transcription succeeded without checking that the output files exist.
Never make up transcript content. Read the actual .srt or lecture_data.json.
Never describe a screenshot from metadata alone when the image itself matters. View the actual image if it looks important or ambiguous.
Always verify each major step completed before moving to the next.
If a step fails, surface the error and stop. Do not continue blindly.
Never paste large chunks of transcript into lecture_notes.md.
Never add a full-transcript appendix or subtitle dump.
Use timestamps only for major key moments.
Put timestamps in section headings or short inline references, not on every paragraph.
Explain the lecture at an expert teaching level: clarify terminology, supply missing connective tissue, and make the ideas easier to study.
Stay grounded in the actual lecture artifacts. Do not invent claims, examples, or references not supported by the lecture.
If screenshots exist, integrate their information into the explanation instead of dumping raw OCR output.
If the lecture is technical and would benefit from extra context, you may fetch relevant authoritative resources to improve the explanation.
Use external resources only to clarify or deepen the lecture's ideas, not to replace the lecture with unrelated material.
Prefer primary or high-signal sources: official documentation, textbooks, lecture notes, reputable mathematical references, or papers when clearly relevant.
Do not pad the note with generic background. Only include external context that materially improves the student's understanding of the lecture.

Workflow

1. Bootstrap if needed

If ffmpeg, claude, or Whisper is missing:

bash ~/.claude/skills/lecture-transcribe/scripts/setup.sh
source ~/.claude/.venv

2. Run the pipeline

Use the argument string as the source. If no source was passed, ask the user for one.

source ~/.claude/.venv
OUTPUT_DIR="./lecture_$(date +%Y%m%d_%H%M%S)"

~/.claude/venv/bin/python ~/.claude/skills/lecture-transcribe/scripts/run_pipeline.py \
  "$ARGUMENTS" \
  --output-dir "$OUTPUT_DIR" \
  --title "Lecture"

This produces the grounded artifacts:

lecture.srt
lecture.txt
key_moments.json
lecture_data.json
screenshots/screenshots_metadata.json for video inputs

3. Verify artifacts

Before writing notes, confirm:

lecture.srt exists and is non-empty
lecture_data.json exists and is non-empty
for video inputs, screenshot metadata exists when slide extraction was enabled

4. Write the final `lecture_notes.md` yourself

Read:

lecture_data.json
screenshots/screenshots_metadata.json if present
references/notes_template.md

Then create lecture_notes.md in the same output directory.

5. Expand context when it actually helps

You are allowed to gather additional context with the available tools when the lecture assumes background knowledge or compresses important reasoning.

Good use cases:

define a theorem, construction, or technical term the lecturer uses without explaining
verify standard notation or the conventional statement of a known result
connect a diagram or visual construction to its standard mathematical interpretation

Rules for using external context:

keep the lecture as the primary source of truth
use external resources to clarify, not to overwrite
prefer a small number of high-quality sources over broad searching
avoid speculative claims, fake references, or padded “further reading”
only include external material in the final note if it directly improves understanding of the lecture

6. Interpret both transcript and visuals

Do not rely on transcript text alone.

If screenshots exist, inspect them as part of the reasoning process:

detect whether they contain a slide, board work, formula, diagram, code, labels, or a geometric construction
use the screenshot metadata and the actual images to understand what the lecturer is showing
incorporate genuinely useful visual information into the note in prose
if a frame is blank or uninformative, ignore it instead of mentioning it just to fill space
when useful, connect the screenshot to what the lecturer was saying at that timestamp
if there is board writing or notation, convert the meaningful mathematics into clean prose or LaTeX when helpful

Use screenshots especially when:

the lecture refers to “as you can see”, “this diagram”, “this formula”, or “this construction”
the visual carries structure that the subtitles only describe partially
notation or labels in the figure help disambiguate the explanation

Required note shape

Your lecture_notes.md should look like this:

# [Lecture Title]

## Overview
[2-4 sentences: what the lecture is about and why it matters]

## Key Ideas
- ...
- ...
- ...

## [00:12:34] [Major Concept]
[Expert explanation of the concept in clean prose]

## [00:27:10] [Major Result or Transition]
[Explain what changes here and why it matters]

## Conclusion
[Short synthesis]

What good notes look like

concise enough to study from quickly
rich enough to capture the mathematical or conceptual structure
organized around the lecture’s real turning points
written as a clean note, not as post-processed subtitles

What to avoid

### Transcript
blockquotes with multi-sentence subtitle excerpts
Appendix: Full Transcript
one heading per every tiny timestamp
raw OCR pasted without interpretation

Fallback tools

Only use the individual helper scripts for debugging:

download.py
transcribe.py
find_moments.py
extract_slides.py
build_reading.py

See README.md for low-level CLI details.