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-onnxruntime | Bilibili / 任何嵌入字幕 | 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 bot | YouTube | 機器人偵測 |
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.json | frame_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.txt | verify_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.txt | verify_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 頁。)
-
中文字元數 在
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 指令或僅是圖說。這些是完整性的下限,而非邀請重複相同想法。
-
圖表:包含每個能實質提升理解、且不同的視覺教學原子,最多到技術目標 $\max(20,\ \mathrm{round}(T/3.5))$。一個有四個真實視覺原子的
conceptual-talk應包含四個經過驗證的圖表,而非二十個 talking-head 影格。一個以投影片為主、有三十個不同機制的講座則不應止於二十個。 -
小節 當 $T\ge 60$:
technical-slide至少使用 8 個,mixed至少 6 個,conceptual-talk至少 5 個,除非較少的讀者問題能產生一個明顯更清晰的結構。每個主要小節回答一個讀者問題,並以\subsection{本章小结}結尾,該小節陳述答案並為下一個問題做準備。 -
判斷方塊:僅在方塊能將定義、背景依賴、決策規則或失敗邊界與主要流程分開時使用。技術預設值為 $T\ge60$ 時 12 個;
mixed和conceptual-talk沒有方塊配額。切勿僅為了提高計數而將連續的推理分割成方塊。 -
教學原子形狀(適應,不要壓印模板):
- 陳述讀者需要理解什麼以及為何重要;
- 按照需要的順序解釋機制或推理;
- 附上來源證據:適當的數字、範例、引用級別的改寫、公式、程式碼、表格或經過驗證的圖表;
- 當其改變解釋時,陳述後果或邊界。 僅使用來源和讀者需要的元件。在每個包含至少兩個符號的顯示公式之後,添加一個即時符號解釋列表。
-
無僅有大綱的小節。 如果講座中某個 5 分鐘的段落引入了一個不同的機制、數字或設計選擇,它必須以自己的一個子章節或一個帶有證據的明確標籤段落出現,而不是摘要列表中的一個項目符號。
-
編譯前的覆蓋率審計(時間軸): 使用 SRT 以 3–5 分鐘的步長走過時間軸;列出任何缺少對應 prose 或圖表的間隙;在
xelatex之前填補間隙。 -
教學原子檢查清單(主題覆蓋率,對技術講座來說是嚴格要求): 在交付之前,從 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)。 -
機制密度(嚴格 — 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),每個都附有即時符號
- 顯示數學:對於來源公式原子,保留至少
$\min(N_{\mathrm{formula\ atoms}},\ \max(10,\ \mathrm{round}(T/4)))$ 個區塊
(
…
[為翻譯而截斷]