JustinChenzeting/講義筆記轉影片

講義筆記 → 附旁白教學影片

您只需編寫一個檔案：一個 beamer lecture.tex，其中包含投影片、圖表和旁白。隨附的腳本會處理其他所有事情（安裝、LaTeX → PNG 頁面 → 文字轉語音 → ffmpeg → MP4），因此成本大約相當於每堂講座的一個長篇回答，而後續編輯只會重新合成已更改的行。

快速開始：整個管道

每個步驟都是一個指令：python3 <skill-dir>/scripts/lv.py <command>，其中 <skill-dir> 是包含此檔案的資料夾的絕對路徑（在 Windows 上使用 py -3 而非 python3）。以下用 lv 作為該完整指令的簡稱；每次請完整寫出，因為 shell 變數通常不會在您的指令之間保留。

lv setup                           # 0. 一次性安裝；給它 10 分鐘超時或在背景執行
lv init PHYS101-L05                # 1. 列印工作資料夾 (WORK) 並將範本複製到其中
lv ingest notes.pdf --out WORK     #    任何 .pdf .png .jpg .heic .md .txt 的混合；多個檔案也可以
#                                       閱讀筆記 (§1)、規劃 (§2)、編寫 WORK/lecture.tex (§3-4)
lv check WORK/lecture.tex          # 2. 編譯 + 編號聯絡表 + 版面配置警告，無音訊
lv render WORK/lecture.tex         # 3. -> WORK/PHYS101-L05.mp4 (或指定輸出路徑)

• 步驟 0 安裝所有內容（uv、私有 Python 3.12、TinyTeX（僅在沒有可用 LaTeX 時）、ffmpeg、Kokoro 語音）到每個使用者的快取中：在快速連線上約需 3 分鐘，在慢速連線上最多 10 分鐘，無需管理員權限。這是冪等的：如果已經完成，則會在幾秒鐘內完成；如果中斷，再次執行會繼續。告訴使用者這是一次性安裝。它以一行以 [setup] READY 開頭的內容結束；任何其他結尾都是錯誤，訊息中或 references/troubleshooting.md 中提供了修復方法。lv doctor 顯示已安裝的內容，而不進行任何更改。如果缺少設定，其他指令也會執行 setup。
• 端到端執行管道，無需在每個步驟要求確認。 僅在遇到真正的障礙時才停止：無法開啟或閱讀的筆記、需要管理員密碼的設定步驟，或者會改變影片的模糊請求。
• WORK 預設為 ./lecture-videos/<name>（或使用者設定的 work_root）。將 MP4 放在使用者要求的位置；否則 WORK 中的預設位置即可。保留 WORK：.tex、轉錄稿和音訊快取使得後續編輯成本低廉。

1. 首先自行閱讀筆記

ingest 會寫入 WORK/source.txt（含有文字圖層的頁面）、WORK/manifest.tsv（每頁的讀取方式）、需要目視檢查的頁面的全尺寸影像（WORK/pages/），以及 概覽表（WORK/glance-*.jpg，每頁六頁）。

• 查看每一張概覽表。 它們可以捕捉到文字提取遺漏的邊緣註釋、標記的段落和圖形，其代幣成本大約相當於每張表一頁。如果某個表格顯示打字頁面上有手寫或註釋，請使用 --visual 3,7-9 重新執行，以獲取這些頁面的全尺寸影像。
• 手寫或掃描頁面（[handwritten/scanned]、[image]）必須以全尺寸閱讀：開啟每個此類影像，並按順序將內容寫入 WORK/transcript.md，方程式使用 LaTeX，並為每個圖形提供一行描述（軸、標籤、關鍵數字）。將任何難以辨認的內容標記為 [illegible]，而不是自行編造。手寫筆記通常是用戶自己的課堂筆記，因此請將它們視為主要來源。如果您無法檢視影像，請說出來並要求提供打字版本，而不是猜測。
• 帶有圖形的打字頁面（[has figure]）：僅當需要從概覽表上無法讀取的數值或標籤時，才開啟全尺寸影像。
• 之後僅根據 source.txt + transcript.md 進行規劃；不要重新閱讀影像。
• .docx、.pptx 或 .key 筆記：先將它們匯出為 PDF（例如使用 LibreOffice soffice --headless --convert-to pdf），然後攝入 PDF。

在閱讀時，請注意筆記中的錯誤或不一致之處（數字錯字、標籤互換）。在影片中使用正確的值，並在最終報告中列出每個更正。

1b. 從可靠來源填補空白

筆記通常很簡潔：跳過的推導步驟、在定義之前使用的術語、沒有說明的圖形。當某些內容會讓學生感到困惑，並且您可以上網時，請簡短搜尋（2-5 個目標明確的查詢，而非文獻回顧），以找到在合適層級（大學課程筆記和 OCW、LibreTexts、標準教科書，研究生層級的要點則參考評論文章）的清晰說明。優先選擇與筆記符號一致的來源；當它們衝突時，請遵循筆記並提及差異。保持新增內容簡短並服務於筆記的內容，首先針對大學部學生設定，可選擇加入研究生層級的評論，並在最終報告中列出您使用的來源。不要新增講座未涵蓋的主題。

2. 在寫作前規劃（在腦中或寫幾行）

• 長度：目標約為 10 分鐘（9-11），除非使用者指定其他長度。深度勝過廣度：如果筆記的內容超過 10 分鐘可以解釋且不跳過步驟，則徹底涵蓋核心內容，然後告訴使用者遺漏了哪些內容，並提供第 2 部分。旁白預算約為 每分鐘目標長度 155 字，減去每個檢查點 15 秒（預設語速約 165 wpm；暫停間隔使用其餘時間）。一個 10 分鐘的影片 ≈ 1,350 字 + 4 個檢查點（實測：1,481 字 + 4 個檢查點 = 9.9 分鐘）。
• 架構：標題 → 動機 → 依筆記順序的概念 → 範例 → 總結。每一幀一個想法，每幀 1-5 個疊加步驟，總共約 40-70 頁。
• 邏輯鏈：將推理鏈列為編號步驟（假設了什麼、推導出什麼、以及為什麼）。每個推導都從其起始原則到結果，不能跳過任何步驟：每個代數運算都應佔用一行，每個假設都應在使用它的地方說明，每個新符號在出現之前都應定義。如果筆記跳躍（「可以證明…」），請填補空白（§1b）。學生永遠不應該問「那是從哪裡來的？」
• 視覺效果承載著講座：先規劃圖像再規劃文字。每個概念幀都需要一個視覺效果：圖表、繪圖或 物理模型（原子、晶格、質量平衡的儲槽和管道圖、槓桿規則的槓桿）。顯示符號在物理上代表什麼，而不僅僅是方程式。將每個圖形重新繪製為原創的 TikZ/pgfplots（切勿貼上講義的圖片）。使用疊加逐步建構圖表，並在需要表現運動時使用 3-6 個短動畫（冷卻路徑、掃過的連線、滑移的差排）。模式：references/visual-cookbook.md。

如何解釋（這是使影片值得觀看的原因）

• 像個好老師一樣說話，而不是像教科書。 日常用語（「所以基本上」、「這裡的技巧是」、「把它想像成…」）、簡短的句子，以及先說 為什麼 再說 是什麼。預測會發生混淆的地方（「這乍看之下是相反的，而這就是為什麼不是」）。
• 每個重要的方程式解釋兩次：
  1. 數學上：它從哪裡來，一步一步，以及每個項的含義。
  2. 物理/直覺上：它在真實系統中意味著什麼，使用一個類比或極限情況（「如果 c 正好在 c′，合金全是液體，而公式給出的正是這個結果」）。 兩者都在螢幕上顯示：數學行，然後是一行「物理上：」的註釋或圖片。
• 每次推導後，大聲進行一個快速合理性檢查：單位、極限情況或圖表中的一個數字。
• 檢查點：每 10 分鐘 3-5 個，放在它們測試的概念之後（§4）。

3. 編寫 WORK/lecture.tex

init 已經將 assets/template.tex 複製到 WORK/lecture.tex；它展示了每種結構。將其範例幀替換為講座內容。重要的規則：

• \usepackage{lecturevideo} 載入主題（象牙紙、深色墨水、一個紅色強調色，或使用者設定自己的品牌）、調色板（accent、ink、mute、blu、grn、gold）、圖形樣式（pd 軸、dot、lab、note、tie、atom、atomA、atomB）以及旁白指令。不要在講座內重新設定主題樣式。
• 旁白：每疊加頁面 n 一個 \say<n>{...}，放在幀的頂部。\say<2-13>{...} 用於動畫範圍。\wait<n>{2} 靜態維持一個頁面。每個頁面都需要一個；渲染器會命名任何缺失的頁面。
• 口語文字是簡單的英文：數字和符號用文字表達（「forty six percent」、「T three」、「seven hundred seventy nine degrees」、「alpha plus beta」）。在 \say 內部沒有 LaTeX 以及 %、&、#、$。說出要看什麼（「注意那個點」、「注意那條連線」），然後說為什麼重要。展開投影片文字，而不是逐字閱讀。
• 投影片承載真實的解釋。 一個暫停、倒帶或從 PDF 複習的觀看者應該能夠僅從投影片就理解。在每個視覺效果旁邊，放置 3-5 個項目符號，每個最多約 15 個字（關鍵事實、條件、結果、物理意義）。對於推導，將每個步驟顯示為自己的行，旁邊有簡短的原因（「B 的質量平衡」、「除以 W」），當旁白到達時揭示，以強調色的一行「物理上：」結束。如果一個推導需要超過約 6 行，則在下一幀繼續（在頂部重複最後一行），而不是硬塞。
• 版面配置：視覺效果在一側（約 55%），文字在另一側（columns），或者視覺效果在上方，下方有 2-3 行文字。學術且整潔：每幀一個想法，強調色僅用於強調、結果和狀態標記。
• 接受 #1 的圖形巨集放在前置區（框架主體內的 # 會破壞 beamer）。
• 講座所需的任何 LaTeX 套件（siunitx、chemfig、…）都可以使用；當使用私有的 TinyTeX 時，缺少的套件會在首次編譯時自動安裝。

4. 考試式檢查點

\examq[5]{檢查點：槓桿規則}
  {投影片問題}{口語問題}{投影片答案}{口語答案}

這會產生 1 個問題頁面（有旁白，然後是「您有 5 秒鐘。」）、5 個無聲的每秒倒數頁面（帶有縮小的環），以及 1 個有旁白的答案頁面。

像 這節課 的實際考試一樣編寫問題：具體的給定數字、一個明確的任務、一個跟著影片看的人可以在約 30 秒內回答的問題，並附有簡短的解答過程。混合類型：

• 計算：「一個 35 wt.% B 的合金，在 T₃ 時 c′ = 20, c″ = 85：液體的比例是多少？」
• 讀圖：「一個 20 wt.% Ag 的合金在 900 °C。有哪些相，以及大致成分為何？」
• 預測：「一個 5 wt.% Ag 的合金從 800 °C 緩慢冷卻到 500 °C。會形成什麼，在哪裡？」
• 識別／分類：「在一個溫度下液體 → α + β：這是哪種不變反應？」
• 找出錯誤：「一個學生使用 c″ − c 作為連線上的固體分率。哪裡錯了？」

避免模糊的提示（「什麼是相？」）、筆記中未教授的瑣事，以及多部分問題。答案必須顯示推理步驟，而不僅僅是結果。從影片剛剛顯示的圖表或方程式中取得數字，以便問題、圖形和答案保持一致。建立在常見誤解上的問題效果很好（「將銷釘間距減半會使源應力加倍：是真是假？」）。保留 5 秒倒數（投影片上說「如果需要更長時間，請暫停」）；只有當使用者要求更長的暫停時，才使用 \examq[8]。

5. 檢查，然後渲染

lv check WORK/lecture.tex

它會編譯、列印頁數、旁白字數、估計持續時間以及 layout: 警告（內容太高或行太寬，附帶原始碼行號），並寫入編號聯絡表 WORK/lecture_build/sheet-*.png。查看這些表格，檢查是否有重疊、裁切標籤、偏離曲線的標記或空白幀；修正它們並重新執行（成本低廉）。如果您無法檢視影像，請修正每個 layout: 警告並保持圖形簡單。如果估計與目標長度相差超過約 10%，請現在修剪或擴充旁白（而非檢查點）。然後：

lv render WORK/lecture.tex ["OUT/Lecture title.mp4"]

旁白者：Microsoft Edge 神經語音 en-GB-SoniaNeural（免費，需要網路）以 +10%、720p 輸出。離線或如果 Edge 失敗，會自動回退到隨附的 Kokoro 語音 bf_emma。選項：--tts edge|kokoro|say、--voice <id or profile>、--rate、--height。當使用者指定語音或想要自己的語音（包括克隆語音）時，請閱讀 references/voices.md。

字幕免費附帶。 每次渲染也會在 MP4 旁邊寫入 OUT.srt 和 OUT.vtt，並嵌入一個可選擇的字幕軌道，該軌道是根據 \say 文字並根據合成的音訊進行時間安排而建立的，因此它們不消耗代幣，並且在編輯後保持同步。切勿手動轉錄影片或編寫字幕。它們會按照編寫的內容顯示旁白（在 lexicon.tsv 重新拼寫之前）。--no-subs 將其關閉。

發音修正放在 WORK/lexicon.tsv（寫法<TAB>發音）中，僅應用於音訊。編輯後重新渲染只需幾秒鐘，因為未更改的行來自音訊快取。

6. 回報

提供影片路徑（及其 .srt/.vtt 字幕）、持續時間、頁數和檢查點數量、對筆記的任何更正、用於填補空白的來源、哪些圖形是示意性重繪，以及遺漏了哪些內容（提供第 2 部分）。保留 WORK 以供編輯。

個人設定

品牌（標誌、顏色、機構的 beamer 主題）、預設語音、工作資料夾和輸出資料夾都存在技能外部，位於使用者的設定資料夾中，以便技能保持可攜性：references/customization.md。切勿為單一使用者的偏好編輯技能本身的資產。

為什麼這樣建構

• 一個來源檔案保持投影片和旁白對齊；LaTeX 自行寫入頁面精確的旁白對應圖 (.narr)

…

[為便於翻譯而截斷]