Communitygithub.com

CacinieP/video2knowledge

Wandeln Sie Videos in zeitgestempelte Untertitel und strukturierte Wissensartefakte um.

Was ist video2knowledge?

Video2Knowledge ist ein KI-Agent, der Videos in strukturierte Wissensartefakte umwandelt. Es bietet drei Pfade zur Videoanalyse: einen multimodalen VLM-Pfad, der Videoframes in Bildunterschriften umwandelt, einen ASR-Pfad zur Transkription der Audiospur und einen Fusions-Pfad, der beide Methoden kombiniert. Die Verarbeitung erfolgt standardmäßig komplett lokal – keine Videodaten, Audiodaten oder Ausgaben verlassen den Host. Cloud-APIs sind optional und müssen explizit aktiviert werden. Aus den generierten Segmenten erstellt das Tool eine strukturierte Wissensdokumentation, eine eigenständige HTML-Seite, Karteikarten-CSV-Dateien, ein Anki-Deck und illustrierte Notizen in zwei Ansichten: einer Vollansicht mit wörtlichen Zitaten und einer reduzierten Ansicht zur Überarbeitung. Das Tool eignet sich ideal zum Transkribieren von Vorlesungen, Erstellen von Lernkarten aus Aufnahmen oder Zusammenfassen von Meetings. Es erfordert Ollama, ffmpeg und Python3 und bietet eine automatische Hardware-Erkennung zur Auswahl des optimalen Modells für die jeweilige GPU- und RAM-Konfiguration.

Funktioniert mit~Claude Code✓Codex CLI~Cursor
npx skills add CacinieP/video2knowledge

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Was macht video2knowledge?

Verwandeln Sie ein Video in: zeitgestempelte Untertitel → Wissensdokument → HTML / Anki-Karten / 图文笔记. Zwei lokale Aufnahmepfade, standardmäßig vollständig lokale Inferenz (keine Cloud-API). Die Verarbeitung bleibt vollständig lokal – Videos, Untertitel und Ausgaben werden nie hochgeladen; sie befinden sich in einem lokalen runs/-Ordner (gitignoriert). Das Repository verfolgt nur Code-/Konfigurationsänderungen.

Die einzige Ausnahme ist optional und nie automatisch: --backend openai-api / mimo-asr (ASR) und --api-base (Wissensdokument, jeder OpenAI-kompatible Endpunkt) senden diese Audio- oder Untertiteltexte an den von Ihnen benannten Drittanbieter. Wenn Sie diese nicht übergeben, bleibt alles auf dem Host. Sagen Sie dies explizit, wenn Sie sie empfehlen.

Voraussetzungen & Ersteinrichtung

Auf dem Host erforderlich: ollama, ffmpeg, python3 (oder uv). Einmalig:

bash scripts/setup_models.sh

Dieses Skript (idempotent) erkennt automatisch das Hardwareprofil Ihres Rechners (RAM / GPU / Apple Silicon / NVIDIA) über scripts/hardware_profile.py, zieht dann das empfohlene VLM, erstellt eine venv unter .venv/ und installiert faster-whisper + genanki. Sehen Sie, was ausgewählt wurde:

python3 scripts/hardware_profile.py

Die Profile reichen von tiny (4 GB Maschinen → whisper-tiny + qwen3.5:0.8b) bis high-gpu (NVIDIA ≥8 GB → whisper-large-v3 + qwen3.5:9b auf CUDA). Vollständige Tabelle und Optimierung in references/hardware-profiles.md. Überschreiben Sie jede Auswahl mit Umgebungsvariablen (VLM_MODEL=, ASR_DEFAULT_MODEL=, ...) oder CLI-Flags.

Aktivieren Sie die venv, bevor Sie einen Python-Schritt ausführen:

source .venv/bin/activate

Wählen Sie einen Aufnahmepfad (Schritt 1)

Entscheidungsbaum:

  • Klare Sprachspur (Vorlesung, Vortrag, Interview, Erzählung) → Pfad 2 (ASR). Schneller, genauere Texte, feinkörnige Zeitstempel. Für Mandarin bevorzugen Sie das FunASR Paraformer-Backend – fragen Sie die Maschine mit python3 scripts/hardware_profile.py --recommend. → references/path2-asr.md
  • Stumm / Nur-Folien / Bildschirmaufnahme oder Sie benötigen Bildschirmtexte & Diagramme → Pfad 1 (multimodal). → references/path1-multimodal.md
  • Folien-/PPT-Video mit Sprachspur (der übliche Online-Kurs-Fall): Der Kerninhalt ist auf dem Bildschirm (Tabellen, Formeln, Beispiele) UND der Redner spricht → Pfad 3 (Zwei-Pfad-Fusion). Führt ASR für die Erzählung + VLM OCR für Folien aus und verschmilzt sie nach Zeitstempel. → references/path3-fusion.md

Pfade 1 & 2 geben dasselbe Segment-Schema aus ({start,end,text}), daher ist Schritt 2 pfadunabhängig. Pfad 3 gibt eine fusionierte merged.json aus, die von Schritt 2 mit --merged verarbeitet wird.

Pfad 1 — Multimodale Bildunterschriften

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

Ausgaben: OUT/captions.srt, OUT/captions.json, OUT/frames/.

Verwenden Sie für Folien-/PPT-Videos Dedup-Sampling (allgemeiner Zweck, keine Schwellenwertanpassung) plus den Tabellen-/Formel-OCR-Prompt:

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

Pfad 2 — ASR-Transkription

Welche Engine? Fragen Sie zuerst die Maschine:

python3 scripts/hardware_profile.py --recommend

Gemessen an einem 61,5-stündigen Mandarin-Kurs, beide Engines auf derselben 30-minütigen Vorlesung mit derselben 39-Begriffe-Hotword-Liste:

Homophone Begriffe korrektGeschwindigkeit
faster-whisper small + Hotwords44%2,5× Echtzeit
Paraformer-zh (FunASR, CPU)94%12–16× Echtzeit

Hotwords können dies nicht beheben: 背谱/被谱 sind in Pinyin und Ton identisch, daher ist das Audio selbst mehrdeutig. Die Empfehlung stützt sich auf RAM, nicht auf VRAM – Paraformers Vorteil liegt in der Mandarin-Genauigkeit und es läuft auf der CPU. Wenn Sie eine GPU haben, lassen Sie sie frei für das VLM: Das gleichzeitige Ausführen von whisper und dem VLM verwandelt eine 8-Token-Anfrage von 3,8 s in über 60 s.

Standard (lokal, faster-whisper):

python3 scripts/asr_caption.py \
  --video VIDEO --out-dir OUT \
  --model small --language zh \
  --hotwords "Begriff eins, Begriff zwei"   # optionales Jargon-Biasing via initial_prompt

Paraformer (empfohlen für Mandarin; benötigt eine eigene venv – die Tokenizer von funasr lassen sich nicht zusammen mit der Hauptumgebung installieren):

bash scripts/setup_models.sh --with-funasr     # erstellt .venv-funasr, gibt den Pfad aus

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

Cloud-Engines existieren für Hosts, die lokal nicht transkribieren können, und sind optional – sie laden das Audio zu einem Drittanbieter hoch. bash scripts/setup_models.sh --with-openai-client fügt das benötigte openai SDK hinzu; --backend openai-api übernimmt jeden OpenAI-kompatiblen Endpunkt und --backend mimo-asr ist für Chat-förmige Gateways, die keine Zeitstempel zurückgeben. Siehe references/path2-asr.md.

Ausgaben: OUT/subtitles.{srt,vtt,json}.

Reparieren Sie dann Homophone. ASR hört Töne, keine Wörter, daher werden Fachbegriffe falsch geschrieben und der Fehler pflanzt sich in jedes nachgelagerte Artefakt fort. Gemessen: 20 Klassen echter Fehler an 46 Stellen, 100 % Präzision.

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

Erfolgt Abgleich auf tonbewusstem Pinyin, nicht auf Bearbeitungsentfernung, und überschreibt subtitles.srt / .vtt entsprechend. Führen Sie es vor Schritt 2 aus. --dry-run zur Vorschau, --block 实度 um ein Fragment zu blockieren, --glossary @terms.txt um eigene Begriffe hinzuzufügen.

Pfad 3 — Zwei-Pfad-Fusion (ASR × VLM)

Führen Sie Pfad 2, dann Pfad 1 (OCR) aus, speisen Sie OCR-Begriffe zurück in ASR-Hotwords ein, fusionieren Sie und bauen Sie aus der zusammengeführten Datei:

# 1a. ASR
python3 scripts/asr_caption.py --video VIDEO --out-dir OUT --language zh
# 1b/1c. Dedup-Frames + VLM OCR
python3 scripts/mm_caption.py --video VIDEO --out-dir OUT --mode dedup --prompt-ocr
# 1d. OCR-Begriffe -> Hotwords + Abdeckungsprüfung (ASR erneut ausführen mit
#     --hotwords @OUT/ocr_hotwords.txt bei schlechter Abdeckung)
python3 scripts/hotwords_from_ocr.py --captions OUT/captions.json \
  --subtitles OUT/subtitles.json --out OUT/ocr_hotwords.txt
# 2. Fusion nach Zeitstempel + semantischer Abgleichsprüfung
python3 scripts/merge_visual.py --subtitles OUT/subtitles.json --visual OUT/captions.json --out OUT/merged.json
# 3. Bauen (Schritt 2 mit --merged)
python3 scripts/build_knowledge.py --subtitles OUT/subtitles.json --merged OUT/merged.json --out-dir OUT --format all

Die Fusionsschleife hat drei Querschnittskomponenten: (1) hotwords_from_ocr.py extrahiert Bildschirmbegriffe (wiederkehrende CJK-n-Gramme, Folientitel, lateinische Akronyme – heuristisch, kein LLM) und meldet, welche das ASR nie gehört hat, die wahrscheinlich falsch gehörten Fachbegriffe; (2) merge_visual.py hängt visuelle Inhalte nach Zeitstempel an, bindet dann konservativ eine Erzählzeile an eine BENACHBARTE Folie um, wenn ihre Wortüberlappung mit der zeitstempelgebundenen Folie nahe Null ist und der Nachbar eindeutig besser passt (Sprecherverzögerung / Zeitstempeldrift), wobei unsichere Fälle als weak markiert werden, anstatt zu raten – außer bei STABILEN Folien (≥60 s auf dem Bildschirm), bei denen verbale Ausführungen die Norm sind und kein Flag gesetzt wird (--no-semantic stellt reine Zeitstempelzuordnung wieder her); (3) build_knowledge.py --merged übergibt dem LLM verschachtelten Audio+Visual-Text (Chunk-Grenzen unterbrechen niemals eine Folientabelle; Prompt-Echo-Zeilen werden aus jedem Listenfeld Fingerabdruck-gefiltert; Feldbegrenzungen skalieren mit der Videodauer, 3× bei 3 h) mit ⚠️-Markierungen bei Swap/Weak-Notizen und ordnet map-reduzierte Listenfelder in einem globalen Durchlauf mit der Zusammenfassung als Kontext neu. LLM-Antworten auf Chunk-Ebene werden in build_cache.json zwischengespeichert, sodass ein unterbrochener 3-Stunden-Build fortgesetzt und nicht neu gestartet wird. In Batches akkumuliert batch_run.py OCR-Begriffe in course_hotwords.txt, sodass spätere Videos besser transkribiert werden, und --asr-verify transkribiert ein Video erneut, dessen OCR-Begriffsabdeckung unter 50 % gefallen ist. Das Standard-Textmodell folgt demselben Hardwareprofil: openbmb/minicpm5-2b (2.5B dicht, 1.6 GB) bei low/low-mac/mid und der Pfad-1-VLM-Pull selbst bei high+ (qwen3.5/qwen3.8 sind einheitlich Vision+Text, daher wird nichts doppelt heruntergeladen). Überschreiben Sie mit --model oder V2K_TEXT_MODEL= um eines für jeden Lauf festzulegen. Qualitätsmessung: scripts/recall_check.py --run-dir <verz> --draft erstellt eine goldene Muss-Liste (Begriffe / beide-Kanal-Zahlen / Zeitleistenabdeckung), die ein Mensch in Minuten kürzt; --golden bewertet dann erstellte Artefakte dagegen (Grundlinien in tests/golden/BASELINE.md) – „fehlender Inhalt“ wird zu einer Zahl, die Sie über Parameteränderungen hinweg verfolgen können.

Verfeinern zu Wissensartefakten (Schritt 2)

Zeigen Sie build_knowledge.py auf die .json-Ausgabe eines Pfades:

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

Erzeugt in OUT/:

ArtefaktDateiAbschnitt
2.1 Wissensdokument (vorlagenbasiert)knowledge.mdverwendet assets/default-template.md oder --template <datei>
2.2 Eigenständiges HTMLknowledge.htmlanklickbare [mm:ss] Zeitleiste
2.2b Büro-/Druckexportknowledge.docx / knowledge.pdf--format docx / --format pdf (automatisch in --format all, wenn python-docx/fpdf2 installiert)
2.3 Wissenskartencards.csvfrage,antwort,tags,zeitstempel,quelle – dedupliziert: eine lange Vorlesung wird map/reduce über Chunks zusammengefasst und das Modell stellt dieselbe Frage in jedem erneut, sodass jede Wiederholung entfernt wird (gemessen: 145 von 1608 Karten, schlimmstenfalls 117 Zeilen → 11)
2.4 Illustrierte Notizen (图文笔记)notes.md + notes.htmlSchlüsselbilder × Erzählung, siehe unten
2.4b Notizen Büro-/Druckexportnotes.docx / notes.pdfbuild_notes.py --docx --pdf (Bilder eingebettet)
2.4c Reduzierte Notizen (纯享版)notes-distilled.md / .docx / .pdfgleiche Knoten und Bilder, keine zitierte Erzählung – 42 % kleiner und kostenlos (aus bereits berechneter Ausgabe gerendert)

Konvertieren Sie dann Karten zu Anki (2.3 final):

python3 scripts/gen_apkg.py --csv OUT/cards.csv --out OUT/cards.apkg --deck "视频知识卡"

Illustrierte Notizen (2.4, 图文笔记)

Eine scrollbare Notiz, die deduplizierte SCHLÜSSELBILDER mit der Erzählung um den jeweiligen Zeitstempel verschachtelt – das Artefakt „Schauen Sie es sich als Lesestoff noch einmal an“. Benötigt frames.json (von extract_frames.py, normalerweise über den Dedup-Modus von Pfad 1) plus die Untertitel jedes Pfades:

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

Die Knotendichte ist automatisch. --max-frames 0 (Standard) skaliert die Notiz auf ~1 Knoten pro 45 Sekunden, begrenzt auf 12–60: Ein 12-minütiger Clip erhält 16 Knoten, eine 41-minütige Vorlesung 55, eine 3-stündige 60. Das alte 1-pro-4min-Budget gab einer 37-minütigen Vorlesung nur 9 Knoten, und das folgende 1-pro-90s lag immer noch bei mindestens 8 – gemessen an einer 306-Video-/61,5h-Bibliothek beträgt der durchschnittliche Clip 12,1 min, daher begrenzte die Untergrenze den Großteil der Bibliothek auf 8 Knoten, egal wie lang das Video lief. Die Untergrenze musste verschoben werden, nicht die Obergrenze. Übergeben Sie eine explizite --max-frames N, um sie festzulegen. Die Auswahl erfolgt cluster-stratified: Jeder Änderungsburst behält sein abschließendes endgültiges Bild, sodass ein Animationsburst keine isolierten Schlüsselfolien ihres eigenen Knotens beraubt.

Pro Schlüsselbild: LLM-Abschnittstitel → Bild → optionale VLM Bildbeschreibung (--describe-frames) → 1-2 Satz-Notiz, kondensiert aus dem Erzählfenster → wörtlicher Originalton-Auszug.

Der Bild-Prompt fragt nach Lehrinformationen, nicht nach Personen: Notizen zu Tonhöhen, Akkordsymbolen, Taktarten, Anmerkungen und Text auf dem Bildschirm – und lehnt es explizit ab, den Darsteller zu beschreiben („女士弹琴“, „手势讲解“ sind nicht das, was eine Überarbeitungsnotiz braucht). Ein Bild ohne lesbaren Lehrinhalt erhält stattdessen einen benannten Betreff („钢琴演奏画面,无字幕“). Diese eine Prompt-Änderung ist der Unterschied zwischen einer Notiz, die Ihnen beim Lernen hilft, und einer, die das Video nacherzählt.

Zwei Ansichten, ein Durchlauf. Jeder Lauf schreibt ein Zwillingpaar aus denselben Abschnitten – kein zusätzlicher Modellaufruf:

DateiEnthältFür
notes.mdBilder + Notizen + zitierter OriginaltonQuercheck der genauen Wortlaut des Lehrers
notes-distilled.mdgleiche Knoten, gleiche Bilder, keine zitierten OriginaltöneÜberarbeiten – gemessen an 295 Knoten machten die Blockzitate 53 % der Zeichen aus

--docx / --pdf exportiert beide Varianten (notes.docx + notes-distilled.docx, und ebenso für PDF). notes.html bettet Bilder als base64 in eine einzelne freigebbare Datei ein – diese ist nur die Vollansicht, kein reduziertes HTML-Zwilling. Zurückfallen auf Bilder + Rohauszüge, wenn kein Modell erreichbar ist.

Geben Sie dem VLM explizit ein sichtfähiges Modell. --describe-frames ohne --vlm-model fällt auf das Textmodell zurück, das nicht sehen kann; der Lauf warnt und verwirft die Beschreibungen, anstatt einmal pro Bild zu fehlschlagen:

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

Siehe references/outputs.md für Schema, Einzelformatläufe und Fehlermodus.

Benutzerdefinierte Vorlagen (2.1)

Standardvorlage: assets/default-template.md. Überschreiben mit --template <datei>:

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

Vorlagen sind einfaches Markdown mit {{platzhaltern}} ({{title}}, {{summary}}, {{bullets}} (音画合并要点速览), {{timeline}}, {{key_points}}, {{qa}}, {{glossary}}, {{source}}, {{duration}}, {{date}}, {{meta}}). Nur die von Ihnen eingefügten Platzhalter werden ausgefüllt; alles andere bleibt wörtlich erhalten. Vollständige Spezifikation + 3 Beispielvorlagen (Vorlesung / Meeting / Tutorial) in references/templates.md.

Lokale Verarbeitung & Änderungsverfolgung

Die gesamte Videoverarbeitung bleibt auf Ihrem Rechner. Videos, extrahierte Bilder, Untertitel, Wissensdokumente und Karten werden in einen lokalen runs/-Ordner geschrieben, der gitignoriert wird – nichts von Ihren Medien wird jemals hochgeladen oder committet.

Das GitHub-Repository verfolgt nur Code- und Konfigurationsänderungen (Skripte, Referenzen, Vorlagen, README). Dies ergibt eine klare Historie der Entwicklung der Fähigkeit, ohne Medien von Benutzern preiszugeben. Verwenden Sie beschreibende feat:/fix:/docs: Commit-Nachrichten.

Wenn Sie einen lokalen Datensatz eines bestimmten Laufs wünschen, schreiben Sie eine manifest.json in diesen Run-Ordner (verwendeter Pfad, Modelle, Argumente, Ausgabeliste) – aber lassen Sie sie lokal:

cat > "$RUN/manifest.json" <<EOF
{"video":"~/Movies/lecture.mp4","pfad":"asr","modelle":[...]}
EOF

Verwandte Skills