Communitygithub.com

ysyecust/lecture-to-notes

將 YouTube、Bilibili 或 X/Twitter 的講座影片轉換為以讀者為優先的中文 LaTeX/PDF 筆記,包含忠於來源的論點、流暢的原創 prose,以及經過驗證的教學圖表。

lecture-to-notes 是什麼?

此技能可將 YouTube、Bilibili 或 X/Twitter 上的講座影片,自動轉換成一份完整的、可編譯的 .tex 筆記檔與 PDF 檔案。它不僅僅是字幕轉錄,而是透過分析影片素材、提取關鍵教學圖表、結合本地 OCR 與 ASR 技術,生成結構化、資訊密度高的中文筆記。支援多種平台,並能處理驗證碼、反爬蟲機制等問題。輸出內容需符合嚴格的品質標準,包括來源忠實度、教學原子覆蓋率、數值聲明可追溯性,以及清晰的讀者路徑,特別適合用於技術講座與學術課程。

相容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/ysyecust/lecture-to-notes/tree/HEAD/skills/lecture-to-notes

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Lecture to Notes (課程轉筆記)

將 YouTube、Bilibili 或 X/Twitter 的講座影片,轉換為一份完整、可編譯的 .tex 筆記檔與一份渲染後的 PDF。

依賴項目

開始前請先檢查(使用 which)。若缺少任何工具,請提示使用者安裝。

工具必要?用途
yt-dlp總是必須影片/字幕/中繼資料下載(支援 YouTube + Bilibili + X/Twitter)。請檢查 yt-dlp --version:若版本超過 ~90 天未更新,在目前的 Bilibili 和 YouTube 頁面上會失敗
ffmpeg總是必須影格提取、音訊提取
xelatex總是必須LaTeX 編譯(需有 TeX Live + CTeX 以支援中文)
magick總是必須影格拼貼與聯絡表單
ffprobe總是必須時長與影格高度(隨 ffmpeg 提供)
pdftotext總是必須在 verify_notes.py 中進行渲染頁面檢查(poppler)
python3總是必須內建輔助腳本與本機 ASR 支援
sherpa-onnx + X ASR 模型選用(zh/en ASR)快速本機中文/英文轉錄,附帶時間戳記
Whisper 後端ASR 備用 / 非 zh-en / 無 CC 字幕transcribe_whisper.py 會優先選用 mlx-whisper(macOS arm64)→ faster-whisper → openai-whisper
rapidocr-onnxruntimeBilibili / 任何嵌入字幕ocr_hardsubs.py 讀取字幕條與疊加幾何資訊
Pillow + numpy總是必須frame_filter.py 疊加層與合成面板裁切、頭像評分

使用以下指令安裝 Python 端:pip install rapidocr-onnxruntime Pillow numpy 再加上一個轉錄後端:在 Apple Silicon 上安裝 pip install mlx-whisper,否則安裝 pip install faster-whisper(或 openai-whisper 作為最慢的備用方案)。 /ABSOLUTE/PATH/TO/lecture-to-notes/assets/smart_crop.py 仍為選用實驗功能。

LaTeX 套件檢查(不可略過 — 僅執行 which xelatex 是不夠的)

which xelatex 通過不代表所需的 LaTeX 套件已安裝。在最小化 TeX 安裝(例如 MacTeX Basic、TeX Live scheme-basic)中,二進位檔案存在,但 ctex、tcolorbox 等套件可能缺失。這會導致靜默失敗:中文長行超出 \textwidth(無 CJK 斷行)或編譯因 File '...' not found 而中止。

開始前請檢查必要套件:

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 "❌ 缺少 LaTeX 套件:$pkg"
    MISSING=1
  fi
done
if [ "$MISSING" -ne 0 ]; then
  echo "安裝缺失的套件:"
  echo "  tlmgr install ctex tcolorbox environ trimspaces etoolbox"
  echo "或安裝完整的 TeX 發行版:"
  echo "  macOS:  https://www.tug.org/mactex/  (約 4 GB,包含所有內容)"
  echo "  Linux:  sudo apt install texlive-full"
fi

如果 ctex 無法安裝(例如因為最小化安裝上的 l3kernel 版本衝突),notes-template.tex 包含一個備用方案,使用 XeTeX 內建的 CJK 斷行功能(\XeTeXlinebreaklocale "zh")搭配系統字型 — 不需要 ctex 或 xeCJK。

Cookies 與 yt-dlp 版本新鮮度

每個支援的平台都可能拒絕未經驗證的下載,且這兩種失敗情況看起來不同:

症狀平台含義
Sign in to confirm you're not a botYouTube機器人偵測
HTTP Error 412 在探測或下載時Bilibili反爬蟲檢查
WARNING: Your yt-dlp version (...) is older than 90 days任何平台擷取器早於網站目前的標記

請先修正版本,因為過時的擷取器會產生與 cookies 修正相同的錯誤:brew upgrade yt-dlp、pipx upgrade yt-dlp 或 pip install -U yt-dlp,然後用 yt-dlp --version 確認。Homebrew 會停用自動更新,因此 yt-dlp -U 會報告成功但實際上並未更改任何內容。

然後提供 cookies。video_source.py probe 可以直接接受它們:

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

當瀏覽器設定檔不可用時(例如在無頭主機上),請改用 --cookies FILE。因驗證原因而失敗的探測現在會指定要重試的旗標,因此請將該訊息視為下一步行動,而非死胡同。

工作流程的其餘部分會直接呼叫 yt-dlp。與其編輯每個指令,不如一次性編寫一個 yt-dlp 設定檔,並將 XDG_CONFIG_HOME 指向它,這樣下載、字幕擷取和縮圖擷取都會自動使用 cookies:

mkdir -p "$WORKDIR/.xdg/yt-dlp"
printf -- '--cookies-from-browser chrome\n' > "$WORKDIR/.xdg/yt-dlp/config"
# 然後在此講座的 workdir 中,對後續的每個 yt-dlp 呼叫加上前綴:
XDG_CONFIG_HOME="$WORKDIR/.xdg" yt-dlp --no-playlist ... "<URL>"

瀏覽器 cookies 還能為已登入的帳戶解鎖 Bilibili 1080P+,因此相同的設定可以改善影格品質。

目標

從 YouTube、Bilibili 或 X/Twitter 的影片網址,產出一份專業的中文講座筆記。輸出必須:

  • 使用影片的實際教學內容,而非僅是字幕轉錄
  • 將影片的原始封面圖片放在首頁
  • 包含透過聯絡表單審查選出的全幀教學圖表;當影片將攝影機畫面與投影片並排放置時,每個圖表只保留一個量測後的面板,以便投影片文字保持可讀性
  • 讓有能力的初次讀者能夠理解問題、機制、證據、後果與邊界,無需解讀轉錄稿
  • 達到符合來源的資訊密度 — 每個圖表、方塊、公式和段落都值得其空間
  • 在結構上使用 \section{} / \subsection{} 進行組織
  • 以一個結合演講者結論與您自己歸納的「綜合討論」小節結尾
  • 是一個從 \documentclass 到 \end{document} 的完整 .tex 檔案
  • 成功編譯成 PDF

不可妥協的品質標準(Codex / 生產模式)

除非以下每一項都為真,否則請 STOP 且不得聲稱完成。 僅有大綱、以圖片為主的 PDF 卻 prose 薄弱,或缺少中間產出物,都會被視為自動失敗。

必備工作目錄產出物(在說「完成」之前,必須存在於磁碟上)

檔案必要內容
metadata.json來自 video_source.py probe(或同等完整的傾印)
audio.srt用於編寫筆記的最終字幕軌(手動 CC、清理後的自動字幕、硬字幕 OCR、X ASR 或 Whisper)
audio_corrected.srt最終字幕軌的複本,或在使用本機 ASR 時的詞彙表/LLM 修正軌
hardsub_ocr.srt當 ocr_hardsubs.py detect 報告有嵌入字幕時,ocr_hardsubs.py extract 的輸出;否則不應存在
bands.json來自 ocr_hardsubs.py detect --geometry 或 frame_filter.py bands 的疊加幾何資訊(導覽條、字幕條)
layout.json來自 frame_filter.py layout 在密集樣本上的面板佈局;始終必須量測,composite: false 記錄為單圖片影片
cover.jpg首頁封面
video.mp4用於影格的來源(僅在使用者禁止下載並提供影格時可省略)
frames/密集樣本,預設為每 15 秒 1 個影格
frame_scores.jsonframe_filter.py score 在密集樣本上的輸出;當主機無法顯示圖片時為必須
figures/選定的圖表資產,附帶語意名稱(fig_01_topic.jpg、...),透過 bands.json 裁切疊加層,透過 layout.json 裁切合成內容至一個面板
figure_manifest.tsv表頭 figure\tframe\tstart\tend\ttopic\tpanel — 每個圖表圖片一行;panel 指定了它保留的 layout.json 面板(main、left、...)或 full
figure_verification.txtverify_figures.py 在所有 manifest 時間戳記上的完整 stdout
lecture_profile.json讀者與來源契合設定檔;必要欄位如下所述
teaching_atoms.tsv表頭 atom\tstatus\tevidence — 每個教學原子都對應到筆記中
numerical_claims.tsv由 extract_claims.py extract 產生,由 extract_claims.py check --write 填寫;當講座不包含數值聲明時,僅有表頭是有效的
notes.tex完整的中文講座筆記
notes.pdf兩次 xelatex 編譯的輸出
verify_notes.txtverify_notes.py 的完整 stdout,結尾為 OVERALL PASS

來源契合設定檔與讀者合約(嚴格)

在字幕修正和聯絡表單審查之後,在擬定筆記大綱之前,建立 lecture_profile.json:

{
  "mode": "technical-slide",
  "audience": "capable first-time reader",
  "central_question": "What should the reader be able to explain after reading?",
  "reader_outcome": "A concrete capability, decision, or mental model",
  "visual_teaching_atoms": 24,
  "formula_teaching_atoms": 18
}

選擇一個模式:

  • technical-slide:投影片、黑板內容、公式、程式碼或圖表承載了大部分教學內容;
  • conceptual-talk:演講、訪談或討論透過論點、範例和推理而非視覺機制承載了大部分內容;
  • mixed:兩種模式都貢獻了相當的教學內容。

從來源計算 visual_teaching_atoms 和 formula_teaching_atoms,而非從草稿。視覺原子是來源中一個有助於說明某個觀點的獨特視覺元素。公式原子是值得保留的來源方程式或推導。請勿為了證明更多資產的合理性而誇大這些計數,也不要為了觸發配額而將概念性演講歸類為技術性。

對於所有模式,嚴格的關卡是來源忠實度、完整的教學原子涵蓋率、可追溯的數值聲明、清晰的來源歸屬,以及連貫的讀者路徑。以下的數值密度關卡是基於來源的防護措施。它們絕不會授權編造方程式、低價值的 talking-head 截圖、重複的方塊或同義詞填充。

密度與結構關卡(來源自適應)

對於時長為 $T$ 分鐘(來自 metadata)的講座:

關卡 vs 目標(不要混淆): 以下數字是嚴格關卡(未通過 = 不交付)。高品質的 Codex 級筆記通常落在 CJK 關卡的 ~25–40% 以上;這是目標,而非第二個硬性下限。將硬性下限提高到量測到的黃金標準值會鼓勵填充,而非增加更多教學原子。(已在 CS336 L3 上驗證:$T\approx 89$ → 關卡 CJK 6246 / 圖表 25;黃金標準約 ~8035 CJK / 27 圖表 / 31 頁。)

  1. 中文字元數 在 notes.tex 主體中(僅 CJK 統一表意文字):

    • technical-slide:至少 $\max(5000,\ \mathrm{round}(70\times T))$;
    • mixed:至少 $\max(3500,\ \mathrm{round}(55\times T))$;
    • conceptual-talk:至少 $\max(2500,\ \mathrm{round}(45\times T))$。 不要計算英文術語、LaTeX 指令或僅是圖說。這些是完整性的下限,而非邀請重複相同想法。
  2. 圖表:包含每個能實質提升理解、且不同的視覺教學原子,最多到技術目標 $\max(20,\ \mathrm{round}(T/3.5))$。一個有四個真實視覺原子的 conceptual-talk 應包含四個經過驗證的圖表,而非二十個 talking-head 影格。一個以投影片為主、有三十個不同機制的講座則不應止於二十個。

  3. 小節 當 $T\ge 60$:technical-slide 至少使用 8 個,mixed 至少 6 個,conceptual-talk 至少 5 個,除非較少的讀者問題能產生一個明顯更清晰的結構。每個主要小節回答一個讀者問題,並以 \subsection{本章小结} 結尾,該小節陳述答案並為下一個問題做準備。

  4. 判斷方塊:僅在方塊能將定義、背景依賴、決策規則或失敗邊界與主要流程分開時使用。技術預設值為 $T\ge60$ 時 12 個;mixed 和 conceptual-talk 沒有方塊配額。切勿僅為了提高計數而將連續的推理分割成方塊。

  5. 教學原子形狀(適應,不要壓印模板):

    • 陳述讀者需要理解什麼以及為何重要;
    • 按照需要的順序解釋機制或推理;
    • 附上來源證據:適當的數字、範例、引用級別的改寫、公式、程式碼、表格或經過驗證的圖表;
    • 當其改變解釋時,陳述後果或邊界。 僅使用來源和讀者需要的元件。在每個包含至少兩個符號的顯示公式之後,添加一個即時符號解釋列表。
  6. 無僅有大綱的小節。 如果講座中某個 5 分鐘的段落引入了一個不同的機制、數字或設計選擇,它必須以自己的一個子章節或一個帶有證據的明確標籤段落出現,而不是摘要列表中的一個項目符號。

  7. 編譯前的覆蓋率審計(時間軸): 使用 SRT 以 3–5 分鐘的步長走過時間軸;列出任何缺少對應 prose 或圖表的間隙;在 xelatex 之前填補間隙。

  8. 教學原子檢查清單(主題覆蓋率,對技術講座來說是嚴格要求): 在交付之前,從 SRT + 投影片中提取一個特定於講座的原子列表(15–40 個原子)。每個原子必須對應到 notes.tex 中的一個子章節、一個標籤段落或一個圖表+圖說。缺少原子 → 擴展 prose;不要僅因為 CJK 達標就「通過」。 例如 LLM 架構講座的原子:Pre/Post-Norm、LN vs RMSNorm、FLOPs≠runtime、SwiGLU、串行 vs 並行區塊、RoPE、FFN 比例、head dim、寬度/深度、詞彙大小、dropout vs weight decay、z-loss、QK-Norm、Prefill vs Decode、MQA/GQA、滑動視窗 / 交錯 / 混合注意力。 將檢查清單存放為 teaching_atoms.tsv(atom\tstatus\tevidence)。

  9. 機制密度(嚴格 — L2 黃金標準比較 2026-07-12): 僅 CJK/圖表/方塊關卡是不夠的。CS336 L2 第一次 Grok 傳遞:5463 CJK / 8 公式 / 0 程式碼(關卡 PASS,黃金標準不完整);在聲明驅動補全後:~6450 CJK / 31 公式 / 3 程式碼 / 33 頁(與 Codex 匹配)。也需要:

    • 顯示數學:對於來源公式原子,保留至少 $\min(N_{\mathrm{formula\ atoms}},\ \max(10,\ \mathrm{round}(T/4)))$ 個區塊 (\[ ... \] 或 equation),每個都附有即時符號

…

[為翻譯而截斷]

相關技能