Communitygithub.com

Video2Knowledge

動画をタイムスタンプ付き字幕と構造化された知識成果物に変換します。2 つの入力パス(マルチモーダル VLM によるフレームキャプションと ASR による音声文字起こし)を提供し、デフォルトですべてをローカルで処理します。

Video2Knowledge とは?

Video2Knowledge は、動画からタイムスタンプ付きの字幕を生成し、それを知識文書、HTML ページ、Anki デッキ、図解ノート(図文筆記)などの構造化された知識成果物に変換するスキルです。2 つの主要な入力パスがあります。1 つは、サンプリングされた動画フレームをタイムスタンプ付きキャプションに変換するマルチモーダル VLM (最大 4B パラメータ、Ollama 経由) を使用するパス、もう 1 つは、faster-whisper (ローカル) または FunASR Paraformer (中国語に最適化、同一音声の同音異義語で 44% → 94% に改善) を使用して音声を文字起こしする ASR パスです。オプションで 3 つ目のデュアルパスフュージョンが ASR と VLM を組み合わせ、スライド上のテキストとナレーションを統合します。すべての処理はデフォルトで完全にローカルで行われ、動画、音声、出力がホストから外部に送信されることはありません。クラウドベースの ASR または LLM エンドポイントはオプトインであり、データをサードパーティにアップロードすることを明示的に示します。このスキルは、講義や録画からの学習カードの作成、動画の書き起こしや要約、画面録画やスライドベースの動画からのテキスト抽出に特に役立ちます。また、カスタムテンプレートをサポートし、処理の進行状況と品質を追跡するためのツール(ホットワードの追加、同音異義語の修正、リコールチェックなど)を提供します。

対応~Claude Code✓Codex CLI~Cursor
npx skills add CacinieP/video2knowledge

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

Video2Knowledge は何をしますか?

動画を次のものに変換: タイムスタンプ付き字幕 → 知識文書 → HTML / Anki カード / 図文筆記。 2 つのローカル入力パス、デフォルトですべてローカル推論(クラウド API 不要)。 処理は完全にローカルに留まります — 動画、字幕、出力は決してアップロードされず、ローカルの runs/ フォルダ(gitignore 済み)に保存されます。リポジトリはコード/設定の変更のみを追跡します。

唯一の例外はオプトインであり、自動的には行われません: --backend openai-api / mimo-asr (ASR) と --api-base (知識文書、任意の OpenAI 互換エンドポイント) は、その音声または字幕テキストを指定したサードパーティに送信します。 これらを指定しない限り、すべてがホスト上に保持されます。推奨する際は明示的に伝えてください。

前提条件と初回セットアップ

ホストに必要なもの: ollama、ffmpeg、python3 (または uv)。一度だけ:

bash scripts/setup_models.sh

これは(べき等に)マシンのハードウェアプロファイル(RAM/GPU/Apple Silicon/NVIDIA)を scripts/hardware_profile.py 経由で自動検出し、推奨される 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 は、ステップ 2 で --merged によって消費される融合された merged.json を出力します。

パス 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 倍速

ホットワードでは修正できません: 背譜/被譜はピンインでも声調でも同一であるため、音声自体があいまいです。推奨は VRAM ではなく RAM に基づきます — Paraformer の利点は中国語の精度であり、CPU で動作します。GPU がある場合は、VLM のために空けておいてください: whisper と VLM を同時に実行すると、8 トークンのリクエストが 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 はメイン環境と共存できません):

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. ビルド (--merged を指定したステップ 2)
python3 scripts/build_knowledge.py --subtitles OUT/subtitles.json --merged OUT/merged.json --out-dir OUT --format all

融合ループには 3 つのクロスパスコンポーネントがあります: (1) hotwords_from_ocr.py は画面上の用語(繰り返し出現する CJK n-gram、スライドタイトル、ラテン語の略語 — ヒューリスティック、LLM 不要)を抽出し、ASR が聞き取れなかったもの、つまり誤って聞き取られた可能性が高い専門用語を報告します; (2) merge_visual.py はタイムスタンプでビジュアルをアタッチし、ナレーション行とタイムスタンプでアタッチしたスライドとの単語オーバーラップがほぼゼロで、隣接するスライドとのマッチングが明らかに優れている場合(話者の遅延/タイムスタンプのずれ)、ナレーション行を隣接するスライドに控えめに再バインドし、不確かなケースは推測ではなく weak としてフラグ付けします — ただし、SETTLED スライド(画面に 60 秒以上表示)の場合は例外で、口頭での説明が標準であるため、フラグは立てられません(--no-semantic は純粋なタイムスタンプマッチングに戻します); (3) build_knowledge.py --merged は LLM にインターリーブされた音声+視覚テキスト(チャンク境界がスライド表を分割することはありません; プロンプトエコー行はすべてのリストフィールドからフィンガープリントフィルタリングされます; フィールドの上限は動画の長さに応じてスケーリングされ、3 時間で 3 倍)を、スワップ/ウィークノートに ⚠️ マーカーを付けて供給し、マップリデュースされたリストフィールドを要約をコンテキストとして 1 回のグローバルパスで再ランク付けします。チャンクレベルの LLM 応答は build_cache.json にキャッシュされるため、中断された 3 時間のビルドは再起動ではなく再開されます。バッチでは、batch_run.py が OCR 用語を course_hotwords.txt に蓄積するため、後の動画の文字起こしが向上し、--asr-verify は OCR 用語のカバレッジが 50% を下回った動画を再文字起こしします。デフォルトのテキストモデルは同じハードウェアプロファイルに従います: low/low-mac/mid では openbmb/minicpm5-2b (2.5B デンス、1.6 GB)、high+ ではパス 1 の VLM プル自体 (qwen3.5/qwen3.8 は統合ビジョン+テキストであるため、何も 2 回ダウンロードされません)。--model または V2K_TEXT_MODEL= でオーバーライドして、すべての実行で 1 つに固定します。品質測定: 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.mdassets/default-template.md または --template <file> を使用
2.2 自己完結型 HTMLknowledge.htmlクリック可能な [mm:ss] タイムライン
2.2b Office/印刷用エクスポートknowledge.docx / knowledge.pdf--format docx / --format pdf (--format all で python-docx/fpdf2 がインストールされている場合に自動)
2.3 知識カードcards.csvquestion,answer,tags,timestamp,source — 重複除去: 長い講義はチャンクをマップ/リデュースして要約され、モデルは各チャンクで同じ質問を再度行うため、すべての繰り返しは削除されます (測定値: 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, 図文筆記)

各タイムスタンプ周辺の重複除去された KEY FRAMES とナレーションをインターリーブするスクロール可能なノート — 「読み物として見返す」ための成果物。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 秒あたり 1 ノードに調整し、12 から 60 にクランプします: 12 分のクリップは 16 ノード、41 分の講義は 55 ノード、3 時間のものは 60 ノードになります。以前の 1-per-4min バジェットでは 37 分の講義で 9 ノードしか得られず、その後の 1-per-90s でも 8 ノードが下限でした — 306 動画 / 61.5 時間のライブラリで測定した平均クリップ長は 12.1 分であるため、下限がライブラリのほとんどを動画の長さに関係なく 8 ノードに制限していました。動かす必要があったのは天井ではなく下限でした。明示的な --max-frames N を渡して固定します。選択はクラスター層別化されます: すべての変化バーストは、その落ち着いた最終フレームを保持するため、アニメーションバーストによって孤立したキースライドが独自ノードを失うことはなくなりました。

キーフレームごと: LLM セクションタイトル → フレーム画像 → オプションの VLM 画面説明 (--describe-frames) → ナレーションウィンドウから凝縮された 1-2 文のノート → 逐語的な原声の抜粋。

画面プロンプトは 人物ではなく、教育情報 を求めます: 音符、コード記号、拍子記号、注釈、画面上のテキスト — そして演奏者を説明することを明示的に拒否します (「女性がピアノを弾いている」、「手の動きの説明」は復習ノートに必要なものではありません)。読み取り可能な教育コンテンツのないフレームについては、代わりにトピック名が付けられます (「ピアノ演奏画面、字幕なし」)。この 1 つのプロンプトの変更が、学習に役立つノートと動画をナレーションするだけのノートの違いです。

2 つのビュー、1 回のパス。 すべての実行は、同じセクションから双子のペアを書き込みます — 追加のモデル呼び出しはありません:

ファイル内容用途
notes.mdフレーム + ノート + 引用原声教師の正確な言い回しをクロスチェック
notes-distilled.md同じノード、同じフレーム、引用ナレーションなし復習用 — 295 ノードで測定したところ、引用ブロックは文字数の 53% を占めていました

--docx / --pdf は両方のバリアントをエクスポートします (notes.docx + notes-distilled.docx、PDF も同様)。notes.html はフレームを base64 として 1 つの共有可能なファイルに埋め込みます — これはフルビューのみで、ダイジェスト版の HTML 双子はありません。モデルに到達できない場合は、フレーム + 生の抜粋に縮退します。

VLM に視覚認識可能なモデルを明示的に指定します。 --describe-frames を --vlm-model なしで使用すると、テキスト モデルにフォールバックします。これは見ることができません; 実行は警告を発し、フレームごとに失敗する代わりに説明をドロップします:

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}} ({{title}}、{{summary}}、{{bullets}} (音画併合要点速覧)、{{timeline}}、{{key_points}}、{{qa}}、{{glossary}}、{{source}}、{{duration}}、{{date}}、{{meta}}) を使用するプレーンマークダウンです。含めたプレースホルダーのみが埋められます; その他はすべてそのまま残ります。完全な仕様と 3 つのサンプルテンプレート (講義/ミーティング/チュートリアル) は references/templates.md にあります。

ローカル専用処理と変更追跡

すべての動画処理はマシン上に留まります。 動画、抽出されたフレーム、字幕、知識文書、カードは、gitignore されている ローカルの runs/ フォルダに書き込まれます — メディアに関するものは決してアップロードまたはコミットされません。

GitHub リポジトリは コードと設定の変更のみを追跡します (scripts、references、templates、README)。これにより、ユーザーのメディアを公開することなく、スキルがどのように進化したかの明確な履歴が得られます。説明的な feat:/fix:/docs: コミットメッセージを使用してください。

特定の実行のローカル記録が必要な場合は、その実行フォルダに manifest.json を書き込みます (使用したパス、モデル、引数、出力リスト) — ただし、ローカルに保持してください:

cat > "$RUN/manifest.json" <<EOF
{"video":"~/Movies/lecture.mp4","path":"path3-fusion","models":{"vlm":"openbmb/minicpm-v4.6:latest","asr":"paraformer","text":"openbmb/minicpm5-2b"},"args":"...","outputs":[...]}
EOF

この manifest は他のスクリプトでは使用されません。単に参照用です。

関連スキル