/lecture-to-notes

name: lecture-to-notes
description: Use when users provide YouTube, Bilibili, or X/Twitter lecture URLs and want reader-first Chinese LaTeX/PDF notes with source-faithful claims, fluent authored prose, and verified teaching figures, especially requests phrased as lecture notes, 视频转PDF, 课程笔记, 讲义, YouTube笔记, B站笔记, X/Twitter lecture notes, or BV号; do not produce transcript dumps, quota-padded prose, or screenshot galleries.

Lecture to Notes

Turn a YouTube, Bilibili, or X/Twitter lecture video into a complete, compilable `.tex` note set and a rendered PDF.

Dependencies

Check before starting (use `which`). Prompt the user to install any missing tools.

| Tool | Required | Purpose | |------|----------|---------| | `yt-dlp` | Always | Video/subtitle/metadata download (supports YouTube + Bilibili + X/Twitter). Check `yt-dlp --version`: a build older than ~90 days fails on current Bilibili and YouTube pages | | `ffmpeg` | Always | Frame extraction, audio extraction | | `xelatex` | Always | LaTeX compilation (TeX Live + CTeX for Chinese) | | `magick` | Always | Frame montage and contact sheets | | `ffprobe` | Always | Duration and frame height (ships with ffmpeg) | | `pdftotext` | Always | Rendered-page checks in `verify_notes.py` (poppler) | | `python3` | Always | Installed helper scripts and local ASR support | | `sherpa-onnx` + X ASR model | Optional zh/en ASR | Fast local Chinese/English transcription with token timestamps | | Whisper backend | ASR fallback / non-zh-en / no-CC | `transcribe_whisper.py` picks `mlx-whisper` (macOS arm64) → `faster-whisper` → `openai-whisper` | | `rapidocr-onnxruntime` | Bilibili / any burned-in subtitles | `ocr_hardsubs.py` reads the subtitle band and overlay geometry | | `Pillow` + `numpy` | Always | `frame_filter.py` overlay and composite-panel crops, talking-head scores |

Install the Python side with `pip install rapidocr-onnxruntime Pillow numpy` plus one transcription backend: `pip install mlx-whisper` on Apple silicon, otherwise `pip install faster-whisper` (or `openai-whisper` as the slowest fallback). `/ABSOLUTE/PATH/TO/lecture-to-notes/assets/smart_crop.py` remains an optional experiment.

LaTeX package check (do NOT skip — `which xelatex` alone is insufficient)

`which xelatex` passing does **not** mean the required LaTeX packages are installed. On minimal TeX installs (e.g. MacTeX Basic, TeX Live `scheme-basic`), the binary exists but `ctex`, `tcolorbox`, and other packages are missing. This causes silent failures: long Chinese lines overflow `\textwidth` (no CJK line breaking) or compilation aborts with `File '...' not found`.

Check required packages before starting:

MISSING=0
for pkg in ctex tcolorbox environ trimspaces listings hyperref booktabs float subcaption etoolbox; do
  if ! kpsewhich "$pkg.sty" >/dev/null 2>&1; then
    echo "❌ Missing LaTeX package: $pkg"
    MISSING=1
  fi
done
if [ "$MISSING" -ne 0 ]; then
  echo "Install missing packages:"
  echo "  tlmgr install ctex tcolorbox environ trimspaces etoolbox"
  echo "Or install full TeX distribution:"
  echo "  macOS:  https://www.tug.org/mactex/  (~4 GB, includes everything)"
  echo "  Linux:  sudo apt install texlive-full"
fi

If `ctex` cannot be installed (e.g. due to `l3kernel` version conflicts on minimal installs), the `notes-template.tex` includes a fallback that uses XeTeX's built-in CJK line breaking (`\XeTeXlinebreaklocale "zh"`) with system fonts — no `ctex` or `xeCJK` needed.

Cookies and yt-dlp freshness

Every supported platform can reject an unauthenticated download, and the two failures look different:

| Symptom | Platform | Meaning | |---------|----------|---------| | `Sign in to confirm you're not a bot` | YouTube | bot detection | | `HTTP Error 412` on probe or download | Bilibili | anti-scraping check | | `WARNING: Your yt-dlp version (...) is older than 90 days` | any | extractors predate the site's current markup |

Fix the version first, because a stale extractor produces the same errors that cookies fix: `brew upgrade yt-dlp`, `pipx upgrade yt-dlp`, or `pip install -U yt-dlp`, then confirm with `yt-dlp --version`. Homebrew disables the self-updater, so `yt-dlp -U` reports success without changing anything.

Then supply cookies. `video_source.py probe` takes them directly:

python3 "/ABSOLUTE/PATH/TO/lecture-to-notes/assets/video_source.py" probe \
  --cookies-from-browser chrome "<URL>" > metadata.json

Use `--cookies FILE` instead when the browser profile is unavailable, for example on a headless host. A probe that fails for an authentication reason now names the flag to retry with, so treat that message as the next action rather than a dead end.

The rest of the workflow calls `yt-dlp` directly. Rather than editing every command, write a yt-dlp config file once and point `XDG_CONFIG_HOME` at it, so downloads, subtitle fetches, and thumbnail fetches all pick the cookies up:

mkdir -p "$WORKDIR/.xdg/yt-dlp"
printf -- '--cookies-from-browser chrome\n' > "$WORKDIR/.xdg/yt-dlp/config"
# then prefix every later yt-dlp call in this lecture's workdir:
XDG_CONFIG_HOME="$WORKDIR/.xdg" yt-dlp --no-playlist ... "<URL>"

Browser cookies also unlock Bilibili 1080P+ for logged-in accounts, so the same setup improves frame quality.

Goal

Produce a professional Chinese lecture note from a YouTube, Bilibili, or X/Twitter video URL. The output must:

• use the video's actual teaching content, not just subtitle transcription
• place the video's original cover image on the front page
• include selected full-frame teaching figures chosen by contact-sheet review; when the video

places a camera feed and slides side by side, each figure keeps one measured panel so the slide text stays readable

• let a capable first-time reader understand the question, mechanism, evidence, consequence, and boundary without decoding the transcript
• achieve source-fit information density — every figure, box, formula, and paragraph earns