RobinSp5/講義影片解說工具

講義影片解說工具 是做什麼的？

目標：讓學生能夠無需實際聽課就能理解一堂課，並能在考試前快速複習。因此，這支影片是學習工具，而非展示品：忠於講義內容、解說清楚、易於記憶、並且隨時可讀。

三項原則指導每個決策：

1. 不憑空創造。 每一項陳述、數字、定義和圖形都必須有講義材料作為依據。可以簡化，但不能添加事實。考試時看過影片的人必須能信賴，內容就是這樣忠實呈現於講義中。
2. 一切可讀，無內容被裁切。 沒有半隱藏的文字、沒有溢出、沒有小字型。一個被剪掉的句子就會破壞整支影片的可信度。
3. 流暢的語音，平穩的畫面。 旁白沒有長時間停頓。在需要呈現大量資訊的地方，畫面會短暫停留後再繼續——就像一場好的簡報。

最終交付成果就是完成的影片，可直接在 Claude 中以單一 MP4 下載。 使用者無需執行任何程式碼、指令或貼上 API 金鑰——所有技術環節由你這端處理，使用此環境提供的工具。不包含播放器或其他額外檔案，除非使用者明確要求（例如字幕檔、逐字稿、大綱表格）。

以使用者寫入的語言與其對話。影片語言是獨立選擇（第一階段，第一步驟）。

有兩種模式，在第一個問題中選擇：配音式（透過 OpenRouter 的 AI 語音，為預設）和純視覺式（無語音——所有解說顯示於畫面上，請參閱下方「純視覺模式」）。只要本文件提及旁白、TTS 或音訊，僅適用於配音模式。

工作流程

依序執行各階段。第一階段是強制性停頓：在使用者確認模式、語言、模型和長度之前，不會產生任何費用（TTS）。

第零階段 – 讀取教材

0. 默默檢視此環境提供的工具：OpenRouter MCP 連接器（用於語音）、內建的影片/動畫輸出（含 MP4 匯出或下載，例如在 Claude Design 中），以及/或可使用 ffmpeg + Chromium 的程式碼執行（用於 scripts/render.py）。第七階段會從中選擇輸出路徑。絕不讓使用者安裝或執行任何東西。
1. 使用 scripts/extract_pdf.py 提取 PDF：

   python3 scripts/extract_pdf.py <pdf> <workdir> [--images]
   

   這會產生 pages.json（每頁的文字、字數、圖片數量）、每頁的 PNG 預覽，以及（若加上 --images）嵌入的圖片。如果缺少 pymupdf：pip install pymupdf --break-system-packages。
2. 檢視頁面預覽（不僅是文字）：圖表、表格和流程圖通常僅以圖片存在。 掃描頁面（輸出「SCANNED/no text」）：重新執行並加上 --ocr（Tesseract，使用教材的語言套件，例如 --ocr-lang deu+eng）。如果缺少 Tesseract 或語言套件，請查看預覽圖片並自行閱讀文字。在使用技術術語或數字於腳本中之前，務必將 OCR 文字與圖片比對校正。
3. 從教材中確定：課程名稱、本次單元的主題、講師/教授、教材的語言、是否有摘要投影片，以及哪些投影片沒有內容（標題、議程、參考文獻、「有問題嗎？」）。不在教材中的內容不要猜測——在第一階段詢問。
4. 投影片中的開放式問題： pages.json 會列出每頁的 questions——向聽眾提問的句子（「Was meinen Sie: …?」、「Welche Vorteile hat …?」、「Diskussion: …」、「Frage an Sie」、「Why could …?」）。所有這些問題都會在影片中得到解答（請參閱第二階段的「開放式問題」）。也要親自閱讀投影片：圖形或對話框內的問題不一定總能被捕捉到。
5. 講課還是習題？ pages.json 包含 exercise_guess（如「Übung」、「Aufgabe」、「Übungsblatt」、「Exercise」、「Task」、「Assignment」等字詞，以及 a) b) c) 等編號任務）。透過閱讀確認：習題要求學習者動手做。如果是習題（或包含習題投影片的講課），影片會解答習題——請參閱下方的「習題模式」。也要檢查是否同時提供了解答卷或解答投影片。

第零階段靜默執行：在第一次提問（第一階段，步驟 1）之前，你不問使用者其他任何問題，也不摘要教材內容。提取僅是為了讓「與投影片相同」選項能命名檢測到的語言。

第一階段 – 詢問使用者（強制，在任何生成之前）

步驟 1 – 影片類型、配音和語言（始終是第一則訊息）

第一則訊息只包含這三個問題，沒有其他內容（如果有的話，以三個可點擊的問題形式呈現），使用使用者的語言，影片類型永遠在最前面。德語使用者的範例：

1. 要製作什麼類型的影片？

• 簡短摘要 – 僅涵蓋重點：核心詞彙、主要關聯、考試相關內容；適合快速複習
• 完整摘要 – 涵蓋教材中的所有主題，包含解釋和範例；可取代上課

2. 影片需要配音嗎？

• 需要，有講者（AI 語音） – 像在課堂上解釋一樣；需要花費幾美分
• 不需要，僅視覺呈現 – 解釋以文字和圖形顯示在畫面上，無聲音，免費

3. 影片要用哪種語言？

• 與教材相同（德語） ← 檢測到的語言在括號中
• 德語
• 英語
• 其他語言（自由輸入）

影片類型優先，因為它決定影片內容以及合理的長度：

• 簡短摘要： 僅核心內容——關鍵詞彙與定義、主要關聯、所有標記為考試重點的部分，加上摘要投影片。範例、推導和次要主題會被省略。每個章節可能以一兩句話帶過，但深度僅限於核心。
• 完整摘要： 涵蓋教材中的每個主題——每個有內容的頁面至少會出現在一個場景中（在第六階段透過 scripts/coverage.py 檢查），按講課順序，包含講課中提供的解釋和範例。不跳過任何內容，只進行濃縮。
• 對於習題：簡短摘要 = 每個任務以一兩句話說明解題方法及結果；完整摘要 = 逐步的完整解題過程。

配音緊接著出現，因為它影響後續所有環節：使用「純視覺」模式時，沒有模型問題、沒有成本，且影片建構方式不同。

即使檢測到的語言是德語或英語，也保留「與教材相同」選項——這是預設值。對於混合語言的教材，請標明主要語言（「與教材相同（主要為英語）」）。

所選語言適用於所有項目：旁白、畫面上文字、開場、摘要、標籤（如「請看」）、TTS 傳送指令。它也決定哪些 TTS 模型符合資格，以及如何計算字數預算和成本——這就是為什麼語言先決定的原因。

如果影片語言與投影片語言不同，請套用 references/didactics-and-script.md 中的翻譯規則（講義的技術術語需保持可見，因為考試會用到）。對於配音模式下的「其他語言」：首先快速檢查是否有 TTS 模型能很好地支援該語言；如果沒有，請坦率告知並提供替代方案（包括純視覺模式）。

步驟 2 – 長度、模型、關鍵資料、大綱、測驗（一則訊息）

僅在步驟 1 的回答之後。在純視覺模式下，跳過 b)（模型）且不報價；此時也沒有步驟 4（語音）。

如果教材是習題，請在該訊息頂端用一行說明（「這是一份有 4 個任務的練習卷——我會在影片中逐步解答每個任務。」）——無需額外提問；此時長度建議以任務數量計算，而非頁數（每個任務約 45–90 秒，依任務規模而定）。

a) 影片長度。 根據步驟 1 的影片類型，從內容頁數 (n) 推算出合適的長度 – 使用 estimate.py lengths --content-pages n --type short|comprehensive：

影片類型	選項（經驗法則）	30 頁範例
簡短摘要	非常短 n × 4 秒 · 短 n × 6 秒（預設）	~2 / ~3 分鐘
完整摘要	精簡 n × 10 秒 · 標準 n × 14 秒（預設） · 詳細 n × 18 秒	~5 / ~7 / ~9 分鐘

四捨五入到半分鐘。對於「完整摘要」，如果使用者選擇的長度低於 n × 8 秒，請用一句話提出警告：所有主題仍會被涵蓋，但會非常簡短。由使用者決定；自訂長度始終允許。

b) TTS 模型及此影片的價格（僅限配音模式）。程序和成本公式在 references/tts-models.md 中 – 在詢問前請先閱讀。簡短說明：

• 透過 OpenRouter MCP 即時擷取當前 TTS 模型（list-models 加上 output_modalities: "speech"，按價格排序）。價格和模型會變動——切勿憑記憶回答。
• 篩選出支援所選影片語言的模型。
• 提供 3–4 個模型，最便宜且較好的優先（最好是 Google Gemini Flash TTS 變體），每個模型附上所選長度的預估價格 – 使用 scripts/estimate.py 計算。
• 如果長度尚未決定：請提供三種長度選項的價格。
• 選擇具有約束力。 當使用者選定一個 OpenRouter 模型後，此影片的每個音訊檔案必須使用該確切模型（相同的 model ID，透過 OpenRouter MCP）——請參閱第四階段的「具有約束力的模型選擇」。

c) 缺失的關鍵資料。 僅在未於第零階段找到時：教授姓名、課程名稱。提供「不顯示名稱」作為選項，而不是猜測。

d) 可選： 直接顯示 PDF 中的投影片圖片/圖形（預設：是，如果它們能解釋某些內容）。

e) 影片開頭顯示大綱？ 是 / 否。用一句話說明：緊接在開場之後，一個簡短的目錄顯示每個章節及其時間範圍（「0:18–1:30 Inner Join」）和投影片編號，讓學習者能看清結構並跳轉到所需部分。大約花費 10 秒鐘。MP4 始終包含章節標記，因此播放器無論如何都可以在章節間跳轉。

f) 結尾加入自測問題？ 是 / 否。用一句話說明：提供自我測驗的問題，附上短暫思考停頓後再給出答案——比重新觀看更有助於記憶。

步驟 3 – 外觀（+ 問題數量）

一則訊息包含兩個關於外觀的問題——並且，僅在步驟 2 f) 選擇了自測問題時，才包含第三個關於數量的問題（如果有的話，以可點擊的問題形式呈現；預設值會先列出）：

淺色還是深色？

• 淺色 (標準) · 深色

哪種風格？

• 現代 (標準) – 彩色強調、柔和漸層、帶陰影的卡片、章節標題卡
• 簡約 – 沉穩，大量白色或黑色，僅使用一個強調色
• 與投影片相同 – 使用講義投影片中的顏色（例如大學藍），以配合講課內容
• 配合主題：… – 根據內容提出的具體建議，例如「資料庫風格：藍色/青綠色搭配簡潔的表格網格」、「永續發展：綠色調搭配葉子圖案」、「金融：深藍色/金色搭配圖表線條」

要多少個自我測驗問題？ (僅在被選中時)

• 3 · 5 · 8 · 自訂數字 – 每個問題都會增加時長和成本（請參閱下方）

將「主題」選項撰寫為針對這堂課的具體建議，而非通用標籤。如果 scripts/palette.py 找不到顯著顏色（純黑/白投影片），則跳過「與投影片相同」選項。每個答案的建構方式：references/visual-rules.md，「外觀」。

問題數量： 選項 3 / 5 / 8 / 自訂。每個選項提供額外的時長和額外成本（使用 estimate.py quiz --questions N --prompt … --completion …；對於總計含大綱：estimate.py cost … --quiz N --toc），例如「5 個問題 · +1:45 分鐘 · +$0.02」。問題是在所選的解說部分長度之上增加的；一旦陳述新的總長度。如果教材中可提問的重點少於要求數量，請提供較少的選項並簡短說明原因。

步驟 4 – 語音（僅限配音模式）

在模型選定後，一則訊息中提出三個簡短的問題（如果有的話，以三個可點擊的問題形式呈現）；預設值會預先選定並先列出：

希望語聽起來如何？

• 女性 (標準) · 男性

哪種性格？

• 激勵且友善 (標準) · 沉穩與專業 · 果斷與清晰 · 輕鬆與隨意

語速？

• 緩慢 · 正常 · 快速 (標準) · 非常快

當使用者跳過或說「隨便」時的預設值：一個好的女性、輕快、具激勵性的解說聲音。 將答案對應到所選模型的具體語音以及傳送指令/速度，使用 references/tts-models.md（「語音選擇」）；用一句話說明你選擇的語音（「語音：Laomedeia – 女性、激勵、快速」）。語速會改變字數預算：將其傳遞給 estimate.py --pace。在開場測試（第四階段）之後，使用者仍可以說「換個語音」或「慢一點」——然後僅重新製作開場部分。

第二階段 – 腳本

閱讀 references/didactics-and-script.md。然後將腳本寫成 script.json（結構如該文件所示），一個場景接一個場景。所需的結構：

1. 開場（約 8–12 秒）：「這個影片是關於……來自……課程，由……教授授課」+ 用 3–5 個重點概述即將呈現的內容（先行組織者）。 大綱（僅在被選擇時，約 10 秒）： 緊接在開場之後的一個場景，使用 <ol class="toc" data-toc>。場景檔案會根據最終的時間自動填入每個章節及其時間範圍和投影片編號——切勿手動輸入時間，它們會隨著每次音訊重新生成而改變。旁白以一兩句話介紹章節（「首先……，然後……，最後是摘要和自測」），並且不要讀出時間。標記場景為 data-dense，並設定 data-hold 約 3 秒，以便閱讀大綱。當選擇了大綱時，開場本身的議程可以更短（一句話），以避免重複。
2. 主要部分： 按講課順序排列的章節。解釋……

[後續內容因篇幅限制已截斷，但已完整翻譯至此處中斷的部分]