Communitygithub.com

CacinieP/video2knowledge

將影片轉換為帶時間戳的字幕與結構化知識產出。提供兩種本地處理路徑:多模態 VLM 捕捉畫面字幕,或 ASR 轉錄音訊字幕,最終生成知識文件、HTML、Anki 卡片與圖文筆記。

video2knowledge 是什麼?

Video2Knowledge 是一款專為開發者與 AI 代理設計的本地化影片知識萃取工具。它支援兩種主要的輸入路徑:**Path 1** 使用多模態 VLM(最大 4B 參數,透過 Ollama)對抽樣影片幀進行時間戳標註;**Path 2** 使用 ASR(語音轉文字)引擎,本機支援 faster-whisper,或針對中文優化的 FunASR Paraformer,後者在領域同音詞測試中將正確率從 44% 提升至 94%。工具還能將內容精煉成多種結構化產出,包括自訂範本的知識文件、自包含 HTML 頁面、去重知識卡片 CSV、Anki 抽認卡牌組,以及兩種版本的圖文筆記(完整版與純享版)。預設一切處理均在本地完成,不會將任何影片、音訊或輸出資料上傳至外部伺服器;雲端 ASR/LLM 端點是可選的,且使用時會明確標示為上傳至第三方。此工具特別適合用於轉錄或總結教學影片、將課堂錄影轉換為學習卡片,或將螢幕錄製內容提煉為結構化的參考文件。

相容平台~Claude Code✓Codex CLI~Cursor
npx skills add CacinieP/video2knowledge

在你喜歡的 AI 中提問

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

說明文件

video2knowledge 是做什麼的?

將影片轉換為:帶時間戳的字幕 → 知識文件 → HTML / Anki 卡片 / 圖文筆記。 提供兩種本地處理路徑,預設使用全本機推理(無需雲端 API)。 所有處理過程均保持完全本地化 — 影片、字幕及輸出結果從不進行上傳;它們儲存在本地的 runs/ 目錄中(已加入 .gitignore)。此儲存庫僅追蹤程式碼與設定檔的變更。

唯一的例外是選擇性的功能,絕非預設:--backend openai-api / mimo-asr(ASR)以及 --api-base(知識文件,任何相容 OpenAI 的端點)會將該音訊或字幕文字傳送至您指定的第三方。不傳遞這些參數即可讓一切保留在主機上。當您推薦使用這些功能時,請明確說明。

先決條件與首次設定

主機需要安裝:ollama、ffmpeg、python3(或 uv)。一次性設定:

bash scripts/setup_models.sh

此腳本(可重複執行)會透過 scripts/hardware_profile.py 自動偵測您的機器硬體規格(RAM / GPU / Apple Silicon / NVIDIA),然後拉取建議的 VLM、在 .venv/ 建立虛擬環境,並安裝 faster-whisper 與 genanki。查看其選擇:

python3 scripts/hardware_profile.py

設定檔範圍從 tiny(4 GB 機器 → whisper-tiny + qwen3.5:0.8b)到 high-gpu(NVIDIA ≥8 GB → whisper-large-v3 + qwen3.5:9b on CUDA)。完整表格與調校說明請參閱 references/hardware-profiles.md。您也可以透過環境變數(VLM_MODEL=、ASR_DEFAULT_MODEL=、……)或 CLI 標誌覆寫任何選擇。

在執行任何 Python 步驟前,請先啟動虛擬環境:

source .venv/bin/activate

選擇輸入路徑(步驟 1)

決策樹:

  • 清晰的語音軌(講座、訪談、旁白) → 路徑 2(ASR)。 速度更快,文字更準確,時間戳更精細。對於中文,建議使用 FunASR Paraformer 後端 — 請透過以下指令詢問機器 python3 scripts/hardware_profile.py --recommend。 → references/path2-asr.md
  • 靜音 / 僅投影片 / 螢幕錄製,或您需要螢幕上的文字與圖表 → 路徑 1(多模態)。→ references/path1-multimodal.md
  • 附有語音軌的投影片 / PPT 影片(常見的線上課程案例):核心內容在螢幕上(表格、公式、範例),同時講者進行旁白 → 路徑 3(雙路徑融合)。執行 ASR 取得旁白 + VLM OCR 取得投影片內容,並根據時間戳進行融合。→ references/path3-fusion.md

路徑 1 與 2 會輸出相同的區段架構({start,end,text}),因此步驟 2 與路徑無關。路徑 3 會輸出一個融合後的 merged.json,由步驟 2 的 --merged 參數使用。

路徑 1 — 多模態字幕

python3 scripts/mm_caption.py \
  --video VIDEO --out-dir OUT \
  --model openbmb/minicpm-v4.6:latest --interval 2.0

輸出:OUT/captions.srt、OUT/captions.json、OUT/frames/。

對於投影片 / PPT 影片,請使用去重取樣(通用目的,無需調整閾值)以及表格 / 公式 OCR 提示詞:

python3 scripts/mm_caption.py \
  --video VIDEO --out-dir OUT \
  --mode dedup --prompt-ocr

路徑 2 — ASR 轉錄

使用哪個引擎? 首先詢問機器:

python3 scripts/hardware_profile.py --recommend

在一個 61.5 小時的普通話課程上實測,兩個引擎對同一段 30 分鐘的講座使用相同的 39 個術語熱詞列表,結果如下:

同音詞正確率速度
faster-whisper small + 熱詞44%2.5× 即時
Paraformer-zh (FunASR, CPU)94%12–16× 即時

熱詞無法解決此問題:背譜/被譜在拼音和聲調上完全相同,因此音訊本身就有歧義。建議的關鍵在於 RAM 而非 VRAM — Paraformer 的優勢在於普通話準確性,且可在 CPU 上執行。如果您有 GPU,請將其保留給 VLM 使用:同時執行 whisper 和 VLM 會使一個 8 token 的請求從 3.8 秒延長至超過 60 秒。

預設(本地,faster-whisper):

python3 scripts/asr_caption.py \
  --video VIDEO --out-dir OUT \
  --model small --language zh \
  --hotwords "術語一, 術語二"   # 透過 initial_prompt 進行選擇性的術語偏差

Paraformer(普通話建議使用;需要自己的虛擬環境 — funasr 的 tokenizers pin 無法與主環境共存):

bash scripts/setup_models.sh --with-funasr     # 建立 .venv-funasr,並輸出路徑

python3 .venv-funasr/bin/python scripts/asr_funasr.py \
  --video VIDEO --out-dir OUT --language zh --hotwords "背譜,視譜,音階"

對於無法在本地進行轉錄的主機,存在雲端引擎可供選擇 — 它們會將音訊上傳至第三方。bash scripts/setup_models.sh --with-openai-client 會新增所需的 openai SDK;--backend openai-api 接受任何相容 OpenAI 的端點,而 --backend mimo-asr 則適用於不返回時間戳的聊天型閘道。請參閱 references/path2-asr.md。

輸出:OUT/subtitles.{srt,vtt,json}。

然後修復同音詞。 ASR 聽到的是聲音,而非詞彙,因此領域術語可能會拼寫錯誤,而這個錯誤會傳播至所有下游產出。實測:46 處有 20 類真正的錯誤,100% 精準率。

python3 scripts/fix_homophones.py --subtitles OUT/subtitles.json

比對依據是聲調感知拼音,而非編輯距離,並會改寫 subtitles.srt / .vtt 以保持一致。請在步驟 2 之前執行。--dry-run 可預覽,--block 實度 可將某個片段加入黑名單,--glossary @terms.txt 可新增您自己的詞彙。

路徑 3 — 雙路徑融合(ASR × VLM)

先執行路徑 2,再執行路徑 1(OCR),將 OCR 術語回饋至 ASR 熱詞,進行融合,並從合併檔案構建:

# 1a. ASR
python3 scripts/asr_caption.py --video VIDEO --out-dir OUT --language zh
# 1b/1c. 去重幀 + VLM OCR
python3 scripts/mm_caption.py --video VIDEO --out-dir OUT --mode dedup --prompt-ocr
# 1d. OCR 術語 -> 熱詞 + 覆蓋率檢查(當覆蓋率不佳時,使用
#     --hotwords @OUT/ocr_hotwords.txt 重新執行 ASR)
python3 scripts/hotwords_from_ocr.py --captions OUT/captions.json \
  --subtitles OUT/subtitles.json --out OUT/ocr_hotwords.txt
# 2. 按時間戳融合 + 語義對齊檢查
python3 scripts/merge_visual.py --subtitles OUT/subtitles.json --visual OUT/captions.json --out OUT/merged.json
# 3. 構建(步驟 2 搭配 --merged)
python3 scripts/build_knowledge.py --subtitles OUT/subtitles.json --merged OUT/merged.json --out-dir OUT --format all

融合迴圈包含三個跨路徑組件:(1) hotwords_from_ocr.py 提取螢幕上的術語(重複出現的中日韓 N-gram、投影片標題、拉丁縮寫 — 啟發式,無需 LLM),並報告 ASR 從未聽到的術語,即可能被誤聽的術語;(2) merge_visual.py 按時間戳附加視覺內容,然後在旁白行與時間戳附加投影片的詞彙重疊接近零,且鄰近投影片明顯更匹配時,保守地將該旁白行重新綁定到相鄰的投影片(講師延遲 / 時間戳漂移),並將不確定的情況標記為 weak 而非猜測 — 除非在固定投影片(停留在螢幕上 ≥60 秒)上,在這種情況下,口頭闡述是常態,不會觸發標記(--no-semantic 還原純時間戳匹配);(3) build_knowledge.py --merged 將交錯的音訊+視覺文字(區塊邊界絕不切斷投影片表格;提示回顯行從所有列表欄位中經過指紋過濾;欄位上限隨影片時長縮放,3 小時時為 3 倍)餵入 LLM,並在交換 / 弱匹配筆記上標記 ⚠️ 標記,然後在一次全域傳遞中對地圖縮減的列表欄位進行重新排序,並以摘要作為上下文。區塊級 LLM 響應會快取在 build_cache.json 中,因此中斷的 3 小時構建可以恢復而非重新開始。在批次處理中,batch_run.py 會將 OCR 術語累積到 course_hotwords.txt,以便後續影片的轉錄效果更好,而 --asr-verify 會對 OCR 術語覆蓋率低於 50% 的影片進行重新轉錄。 預設的文字模型遵循相同的硬體設定:openbmb/minicpm5-2b(2.5B 密集,1.6 GB)用於 low/low-mac/mid,而路徑 1 的 VLM 則在 high+ 上自行拉取(qwen3.5/qwen3.8 是統一的視覺+文字模型,因此無需下載兩次)。使用 --model 或 V2K_TEXT_MODEL= 進行覆寫,以固定一個模型用於每次執行。 品質測量:scripts/recall_check.py --run-dir <dir> --draft 會輸出一個必備的黃金列表(術語 / 雙通道數字 / 時間軸覆蓋率),人類可以在幾分鐘內精簡該列表;--golden 接著會根據該列表對產出的產物進行評分(基準線在 tests/golden/BASELINE.md 中)— 「遺漏的內容」變成一個您可以跨參數變更追蹤的數字。

精煉為知識產出(步驟 2)

將 build_knowledge.py 指向任一路徑的 .json 輸出:

python3 scripts/build_knowledge.py \
  --subtitles OUT/subtitles.json \
  --out-dir OUT --format all

在 OUT/ 中產生:

產出檔案章節
2.1 知識文件(模板化)knowledge.md使用 assets/default-template.md 或 --template <file>
2.2 自包含 HTMLknowledge.html可點擊的 [mm:ss] 時間軸
2.2b Office/列印匯出knowledge.docx / knowledge.pdf--format docx / --format pdf(在安裝了 python-docx/fpdf2 時,--format all 中自動包含)
2.3 知識卡片cards.csvquestion,answer,tags,timestamp,source — 去重:長篇講座的內容會透過區塊的 map/reduce 進行摘要,且模型會在每個區塊中重複詢問相同的問題,因此每個重複項都會被丟棄(實測:1608 張卡片中有 145 張重複,最壞情況下 117 行 → 11 行)
2.4 圖文筆記notes.md + notes.html關鍵幀 × 旁白,請參閱下文
2.4b 筆記 Office/列印notes.docx / notes.pdfbuild_notes.py --docx --pdf(嵌入式幀)
2.4c 純享版筆記notes-distilled.md / .docx / .pdf相同節點與幀,無引述旁白 — 體積小 42%,且免費(從已計算的輸出渲染)

然後將卡片轉換為 Anki(2.3 最終步驟):

python3 scripts/gen_apkg.py --csv OUT/cards.csv --out OUT/cards.apkg --deck "影片知識卡"

圖文筆記(2.4)

一份可捲動的筆記,將去重後的關鍵幀與每個時間戳附近的旁白交錯排列 — 作為「像閱讀一樣回看影片」的產出。需要 frames.json(來自 extract_frames.py,通常透過路徑 1 的去重模式)以及任一路徑的字幕:

python3 scripts/build_notes.py \
  --subtitles OUT/subtitles.json \
  --frames OUT/frames/frames.json \
  --out-dir OUT --describe-frames

節點密度是自動的。 --max-frames 0(預設值)會將筆記大小調整為約每 45 秒一個節點,並限制在 12–60 個:一個 12 分鐘的片段得到 16 個節點,一個 41 分鐘的講座得到 55 個,一個 3 小時的講座得到 60 個。舊的「每 4 分鐘一個」預算讓一個 37 分鐘的講座只有 9 個節點,而後續的「每 90 秒一個」預算在最小值時仍然只有 8 個 — 根據一個包含 306 部影片 / 61.5 小時的函式庫,平均片段長度為 12.1 分鐘,因此最小值限制了大部分函式庫的節點數,無論影片多長。必須移動的是最小值,而非最大值。傳遞明確的 --max-frames N 以固定節點數。選擇是分層分層的:每個變更爆發都會保留其穩定下來的最終幀,因此動畫爆發不會再讓孤立的關鍵投影片無法擁有自己的節點。

每個關鍵幀:LLM 章節標題 → 幀圖像 → 可選的 VLM 畫面描述(--describe-frames) → 從旁白視窗濃縮的 1-2 句筆記 → 逐字原聲摘錄。

畫面提示詞要求的是教學資訊,而非人物:請注意音高、和弦符號、拍號、註解和螢幕上的文字 — 並明確拒絕描述表演者(「女士彈琴」、「手勢講解」不是複習筆記所需要的)。一個沒有可讀教學內容的幀會以其主題命名(「鋼琴演奏畫面,無字幕」)。這一個提示詞的改變,就是區分一個幫助您學習的筆記和一個敘述影片的筆記的關鍵。

兩種檢視,一次處理。 每次執行都會從相同的章節寫出一對孿生檔案 — 無需額外的模型調用:

檔案包含用途
notes.md幀 + 筆記 + 引述原聲交叉比對老師的確切措辭
notes-distilled.md相同節點、相同幀,無引述旁白複習 — 在 295 個節點上的實測中,引述區塊佔了 53% 的字元

--docx / --pdf 會匯出兩種變體(notes.docx + notes-distilled.docx,PDF 同理)。notes.html 會將幀嵌入為 base64 到一個單一的、可分享的檔案中 — 該檔案僅包含完整檢視,沒有純享版 HTML 孿生檔。當無法連線到模型時,會降級為僅顯示幀和原始摘錄。

明確為 VLM 提供一個具備視覺能力的模型。 未指定 --vlm-model 的 --describe-frames 會回退到 文字 模型,該模型無法「看見」;執行會發出警告,並在每個幀上跳過描述,而非失敗:

python3 scripts/build_notes.py ... --describe-frames \
  --model openbmb/minicpm5-2b --vlm-model openbmb/minicpm-v4.6:latest

請參閱 references/outputs.md 以了解架構、單一格式執行以及降級模式。

自訂範本(2.1)

預設範本:assets/default-template.md。使用 --template <file> 覆寫:

python3 scripts/build_knowledge.py --subtitles s.json --out-dir o \
  --template ./my-lecture-template.md --format knowledge

範本是使用 {{placeholders}} 的純 Markdown({{title}}、{{summary}}、{{bullets}}(音畫合併要點速覽)、{{timeline}}、{{key_points}}、{{qa}}、{{glossary}}、{{source}}、{{duration}}、{{date}}、{{meta}})。只有您包含的佔位符會被填寫;其餘內容保持不變。完整規格 + 3 個範例範本(講座 / 會議 / 教學)請參閱 references/templates.md。

本地處理與變更追蹤

所有影片處理均在您的機器上進行。 影片、提取的幀、字幕、知識文件和卡片都會寫入本地的 runs/ 目錄,該目錄已加入 .gitignore — 關於您媒體的任何內容都不會被上傳或提交。

GitHub 儲存庫僅追蹤程式碼與設定的變更(腳本、參考資料、範本、README)。這提供了技能演進的清晰歷史,同時不會暴露任何使用者的媒體。請使用描述性的 feat:/fix:/docs: 提交訊息。

如果您想要特定執行的本地記錄,請在該執行目錄中寫入一個 manifest.json(使用的路徑、模型、參數、輸出列表)— 但請將其保留在本地:

cat > "$RUN/manifest.json" <<EOF
{"video":"~/Movies/lecture.mp4","pa"

相關技能