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 korrekt | Geschwindigkeit | |
|---|---|---|
faster-whisper small + Hotwords | 44% | 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/:
| Artefakt | Datei | Abschnitt |
|---|---|---|
| 2.1 Wissensdokument (vorlagenbasiert) | knowledge.md | verwendet assets/default-template.md oder --template <datei> |
| 2.2 Eigenständiges HTML | knowledge.html | anklickbare [mm:ss] Zeitleiste |
| 2.2b Büro-/Druckexport | knowledge.docx / knowledge.pdf | --format docx / --format pdf (automatisch in --format all, wenn python-docx/fpdf2 installiert) |
| 2.3 Wissenskarten | cards.csv | frage,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.html | Schlüsselbilder × Erzählung, siehe unten |
| 2.4b Notizen Büro-/Druckexport | notes.docx / notes.pdf | build_notes.py --docx --pdf (Bilder eingebettet) |
| 2.4c Reduzierte Notizen (纯享版) | notes-distilled.md / .docx / .pdf | gleiche 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:
| Datei | Enthält | Für |
|---|---|---|
notes.md | Bilder + Notizen + zitierter Originalton | Quercheck der genauen Wortlaut des Lehrers |
notes-distilled.md | gleiche 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