Que fait video2knowledge ?
Transformez une vidéo en : sous-titres horodatés → document de connaissance → HTML / cartes Anki / notes illustrées.
Deux voies d'ingestion locale, inférence entièrement locale par défaut (pas d'API cloud).
Le traitement reste entièrement local — les vidéos, sous-titres et sorties ne sont jamais
téléchargés ; ils résident dans un dossier local runs/ (ignoré par git). Le dépôt ne suit que les modifications
de code/config.
La seule exception est optionnelle et jamais automatique :
--backend openai-api/mimo-asr(ASR) et--api-base(document de connaissance, tout endpoint compatible OpenAI) envoient l'audio ou le texte des sous-titres au tiers que vous avez nommé. Ne pas les utiliser garde tout sur l'hôte. Dites-le explicitement lorsque vous les recommandez.
Prérequis & Configuration Initiale
Requis sur l'hôte : ollama, ffmpeg, python3 (ou uv). Une seule fois :
bash scripts/setup_models.sh
Ce script (idempotent) détecte automatiquement le profil matériel de votre machine (RAM / GPU /
Apple Silicon / NVIDIA) via scripts/hardware_profile.py, puis télécharge le
VLM recommandé, crée un environnement virtuel dans .venv/, et installe faster-whisper +
genanki. Voyez ce qu'il a choisi :
python3 scripts/hardware_profile.py
Les profils vont de tiny (machines 4 Go → whisper-tiny + qwen3.5:0.8b) jusqu'à
high-gpu (NVIDIA ≥8 Go → whisper-large-v3 + qwen3.5:9b sur CUDA). Tableau complet et réglages
dans references/hardware-profiles.md. Remplacez tout choix avec des variables d'environnement
(VLM_MODEL=, ASR_DEFAULT_MODEL=, ...) ou des indicateurs CLI.
Activez l'environnement virtuel avant d'exécuter toute étape Python :
source .venv/bin/activate
Choisir une Voie d'Ingestion (Étape 1)
Arbre de décision :
- Piste audio claire (cours, discours, interview, narration) → Voie 2 (ASR).
Plus rapide, texte plus précis, horodatages fins. Pour le mandarin, préférez le moteur
FunASR Paraformer — demandez à la machine avec
python3 scripts/hardware_profile.py --recommend. →references/path2-asr.md - Vidéo silencieuse / diapos uniquement / enregistrement d'écran, ou besoin de texte affiché à l'écran et de diagrammes
→ Voie 1 (multimodale). →
references/path1-multimodal.md - Vidéo de diaporama avec piste audio (le cas courant des cours en ligne) : le contenu principal
est à l'écran (tableaux, formules, exemples) ET le conférencier parle →
Voie 3 (fusion double-voie). Exécute l'ASR pour la narration + le VLM OCR pour les diapositives et
les fusionne par horodatage. →
references/path3-fusion.md
Les Voies 1 et 2 produisent le même schéma de segments ({start,end,text}), donc l'Étape 2 est
indépendante du chemin. La Voie 3 produit un fichier merged.json fusionné, consommé par l'Étape 2 avec --merged.
Voie 1 — Légendes multimodales
python3 scripts/mm_caption.py \
--video VIDEO --out-dir OUT \
--model openbmb/minicpm-v4.6:latest --interval 2.0
Produit : OUT/captions.srt, OUT/captions.json, OUT/frames/.
Pour les vidéos de diaporama, utilisez l'échantillonnage dédoublonné (générique, sans réglage de seuil) et l'invite OCR tableau/formule :
python3 scripts/mm_caption.py \
--video VIDEO --out-dir OUT \
--mode dedup --prompt-ocr
Voie 2 — Transcription ASR
Quel moteur ? Demandez d'abord à la machine :
python3 scripts/hardware_profile.py --recommend
Mesuré sur un cours de mandarin de 61,5 h, les deux moteurs sur le même cours de 30 minutes avec la même liste de mots-clés de 39 termes :
| termes homophones corrects | vitesse | |
|---|---|---|
faster-whisper small + mots-clés | 44% | 2,5× temps réel |
| Paraformer-zh (FunASR, CPU) | 94% | 12–16× temps réel |
Les mots-clés ne peuvent pas corriger cela : 背谱/被谱 sont identiques en pinyin et en ton, donc l'audio lui-même est ambigu. La recommandation se base sur la RAM, pas la VRAM — l'avantage du Paraformer est la précision en mandarin et il fonctionne sur CPU. Si vous avez un GPU, laissez-le libre pour le VLM : exécuter whisper et le VLM ensemble transforme une requête de 8 tokens de 3,8 s en plus de 60 s.
Par défaut (local, faster-whisper) :
python3 scripts/asr_caption.py \
--video VIDEO --out-dir OUT \
--model small --language zh \
--hotwords "terme1, terme2" # biais de jargon optionnel via initial_prompt
Paraformer (recommandé pour le mandarin ; nécessite son propre environnement — les dépendances de tokenizers de funasr ne cohabitent pas avec l'environnement principal) :
bash scripts/setup_models.sh --with-funasr # construit .venv-funasr, affiche le chemin
python3 .venv-funasr/bin/python scripts/asr_funasr.py \
--video VIDEO --out-dir OUT --language zh --hotwords "背谱,视谱,音阶"
Des moteurs cloud existent pour les hôtes qui ne peuvent pas transcrire localement, et sont
optionnels — ils téléchargent l'audio vers un tiers. bash scripts/setup_models.sh --with-openai-client ajoute le SDK openai nécessaire ; --backend openai-api
prend tout endpoint compatible OpenAI et --backend mimo-asr est pour les
passerelles en forme de chat qui ne renvoient pas d'horodatages. Voir references/path2-asr.md.
Produit : OUT/subtitles.{srt,vtt,json}.
Ensuite, corrigez les homophones. L'ASR entend des sons, pas des mots, donc les termes spécialisés sont mal orthographiés et l'erreur se propage dans tous les artefacts en aval. Mesuré : 20 classes d'erreurs réelles à 46 endroits, précision 100%.
python3 scripts/fix_homophones.py --subtitles OUT/subtitles.json
Correspond sur le pinyin tenant compte du ton, pas sur la distance d'édition, et réécrit
subtitles.srt / .vtt pour correspondre. Exécutez-le avant l'Étape 2. --dry-run pour prévisualiser, --block 实度
pour blacklister un fragment, --glossary @terms.txt pour ajouter les vôtres.
Voie 3 — Fusion double-voie (ASR × VLM)
Exécutez la Voie 2 puis la Voie 1 (OCR), réinjectez les termes OCR dans les mots-clés ASR, fusionnez et construisez à partir du fichier fusionné :
# 1a. ASR
python3 scripts/asr_caption.py --video VIDEO --out-dir OUT --language zh
# 1b/1c. trames dédoublonnées + VLM OCR
python3 scripts/mm_caption.py --video VIDEO --out-dir OUT --mode dedup --prompt-ocr
# 1d. Termes OCR -> mots-clés + vérification de couverture (relancer ASR avec
# --hotwords @OUT/ocr_hotwords.txt lorsque la couverture est faible)
python3 scripts/hotwords_from_ocr.py --captions OUT/captions.json \
--subtitles OUT/subtitles.json --out OUT/ocr_hotwords.txt
# 2. fusion par horodatage + vérification d'alignement sémantique
python3 scripts/merge_visual.py --subtitles OUT/subtitles.json --visual OUT/captions.json --out OUT/merged.json
# 3. construire (Étape 2 avec --merged)
python3 scripts/build_knowledge.py --subtitles OUT/subtitles.json --merged OUT/merged.json --out-dir OUT --format all
La boucle de fusion comporte trois éléments inter-voies : (1) hotwords_from_ocr.py
extrait les termes à l'écran (n-grammes CJK récurrents, titres de diapositives, acronymes latins —
heuristique, sans LLM) et signale ceux que l'ASR n'a jamais entendus,
le jargon probablement mal entendu ; (2) merge_visual.py attache les visuels par
horodatage, puis reassocie de manière conservatrice une ligne de narration à une diapositive ADJACENTE
lorsque son chevauchement de mots avec la diapositive attachée par horodatage est proche de zéro et que le
voisin correspond clairement mieux (décalage du conférencier / dérive d'horodatage), en marquant les cas
incertains comme faible au lieu de deviner — sauf sur les diapositives STABLES
(≥60 s à l'écran), où l'élaboration verbale est la norme et aucun indicateur n'est levé
(--no-semantic rétablit la correspondance pure par horodatage) ; (3) build_knowledge.py --merged alimente le LLM avec du texte audio+visuel entrelacé (les limites de bloc ne coupent jamais un tableau de diapositive ; les lignes d'écho d'invite sont filtrées par empreinte numérique de chaque champ de liste ; les limites de champ sont augmentées avec la durée de la vidéo, 3× à 3 h) avec des marqueurs ⚠️ sur les notes d'échange/faible, et re-classe les champs de liste réduits par map en un seul passage global avec le résumé comme contexte. Les réponses LLM au niveau des blocs sont mises en cache dans
build_cache.json, donc une construction interrompue de 3 heures reprend au lieu de
recommencer. En lots, batch_run.py accumule les termes OCR dans
course_hotwords.txt afin que les vidéos ultérieures soient mieux transcrites, et --asr-verify
retranscrit une vidéo dont la couverture des termes OCR est tombée en dessous de 50%.
Le modèle de texte par défaut suit le même profil matériel : openbmb/minicpm5-2b
(2,5B dense, 1,6 Go) sur low/low-mac/mid, et le VLM de la Voie 1 lui-même sur
high+ (qwen3.5/qwen3.8 sont unifiés vision+texte, donc rien n'est téléchargé
deux fois). Remplacez avec --model, ou V2K_TEXT_MODEL= pour en fixer un pour chaque exécution.
Mesure de qualité : scripts/recall_check.py --run-dir <dir> --draft émet une
liste dorée des éléments indispensables (termes / nombres sur les deux canaux / couverture temporelle) qu'un
humain élimine en quelques minutes ; --golden évalue ensuite les artefacts produits par rapport à celle-ci
(références dans tests/golden/BASELINE.md) — le « contenu manquant » devient un nombre
que vous pouvez suivre à travers les changements de paramètres.
Affiner en Artéfacts de Connaissance (Étape 2)
Pointez build_knowledge.py vers la sortie .json de l'un ou l'autre chemin :
python3 scripts/build_knowledge.py \
--subtitles OUT/subtitles.json \
--out-dir OUT --format all
Produit, dans OUT/ :
| Artéfact | Fichier | Section |
|---|---|---|
| 2.1 Document de connaissance (modèle) | knowledge.md | utilise assets/default-template.md ou --template <fichier> |
| 2.2 Page HTML autonome | knowledge.html | chronologie cliquable [mm:ss] |
| 2.2b Export bureau/impression | knowledge.docx / knowledge.pdf | --format docx / --format pdf (automatique dans --format all si python-docx/fpdf2 installé) |
| 2.3 Fiches de connaissances | cards.csv | question,answer,tags,timestamp,source — dédoublonnées : un long cours est résumé par map/réduction sur les blocs et le modèle repose la même question dans chacun, donc chaque répétition est supprimée (mesuré : 145 sur 1608 cartes, pire cas 117 lignes → 11) |
| 2.4 Notes illustrées (图文笔记) | notes.md + notes.html | trames clés × narration, voir ci-dessous |
| 2.4b Notes bureau/impression | notes.docx / notes.pdf | build_notes.py --docx --pdf (trames intégrées) |
| 2.4c Notes distillées (纯享版) | notes-distilled.md / .docx / .pdf | mêmes nœuds et trames, sans narration citée — 42% plus léger, et gratuit (généré à partir de la sortie déjà calculée) |
Convertissez ensuite les fiches en Anki (2.3 final) :
python3 scripts/gen_apkg.py --csv OUT/cards.csv --out OUT/cards.apkg --deck "Cartes de Connaissances Vidéo"
Notes illustrées (2.4, 图文笔记)
Une note défilante qui entrelace les TRAMES CLÉS dédoublonnées avec la narration autour
de chaque horodatage — l'artefact « revoir la vidéo comme une lecture ». Nécessite frames.json
(depuis extract_frames.py, généralement via le mode dédoublonnage de la Voie 1) plus les sous-titres
de l'un ou l'autre chemin :
python3 scripts/build_notes.py \
--subtitles OUT/subtitles.json \
--frames OUT/frames/frames.json \
--out-dir OUT --describe-frames
La densité des nœuds est automatique. --max-frames 0 (la valeur par défaut) dimensionne la note à
~1 nœud par 45 secondes, plafonné entre 12 et 60 : un clip de 12 minutes obtient 16 nœuds, un
cours de 41 minutes 55, un de 3 heures 60. L'ancien budget 1-par-4min donnait à un
cours de 37 minutes seulement 9 nœuds, et le 1-par-90s qui a suivi plafonnait encore à 8
— mesuré sur une bibliothèque de 306 vidéos / 61,5 h, le clip moyen est de 12,1 min, donc
le plancher limitait la plupart de la bibliothèque à 8 nœuds, quelle que soit la durée de la
vidéo. C'est le plancher qui devait bouger, pas le plafond. Passez un
--max-frames N explicite pour le fixer. La sélection est stratifiée par grappe : chaque
salve de changement conserve sa dernière trame stable, donc une salve d'animation n'affame plus les diapositives clés isolées de leur propre nœud.
Par trame clé : titre de section LLM → image de la trame → description facultative VLM 画面
(--describe-frames) → note de 1 à 2 phrases condensée de la fenêtre de narration →
extrait textuel de l'原声.
L'invite 画面 demande des informations pédagogiques, pas des personnes : notes, symboles d'accords, indications de mesure, annotations et texte à l'écran — et refuse explicitement de décrire l'interprète (« une dame joue du piano », « explication gestuelle » ne sont pas ce dont une note de révision a besoin). Une trame sans contenu pédagogique lisible fait nommer son sujet à la place (« image de piano, sans sous-titres »). Ce seul changement d'invite fait la différence entre une note qui vous aide à étudier et une qui raconte la vidéo.
Deux vues, un seul passage. Chaque exécution écrit une paire jumelle à partir des mêmes sections — aucun appel de modèle supplémentaire :
| Fichier | Contient | Pour |
|---|---|---|
notes.md | trames + notes + 原声 cité | recouper les mots exacts de l'enseignant |
notes-distilled.md | mêmes nœuds, mêmes trames, pas de narration citée | réviser — mesuré sur 295 nœuds, les citations représentaient 53% des caractères |
--docx / --pdf exporte les deux variantes (notes.docx + notes-distilled.docx,
et de même pour le PDF). notes.html intègre les trames en base64 dans un seul
fichier partageable — celui-ci est uniquement la vue complète, pas de jumelle HTML distillée.
Dégrade en trames + extraits bruts lorsqu'aucun modèle n'est joignable.
Donnez explicitement un modèle capable de vision au VLM. --describe-frames sans
--vlm-model revient au modèle de texte, qui ne peut pas voir ; l'exécution émet un avertissement et
supprime les descriptions au lieu d'échouer à chaque trame :
python3 scripts/build_notes.py ... --describe-frames \
--model openbmb/minicpm5-2b --vlm-model openbmb/minicpm-v4.6:latest
Voir references/outputs.md pour le schéma, les exécutions en format unique et le mode dégradé.
Modèles Personnalisés (2.1)
Modèle par défaut : assets/default-template.md. Remplacez avec --template <fichier> :
python3 scripts/build_knowledge.py --subtitles s.json --out-dir o \
--template ./mon-modele-de-cours.md --format knowledge
Les modèles sont en Markdown simple utilisant des {{placeholders}} ({{title}},
{{summary}}, {{bullets}} (aperçu rapide des points clés audio+vidéo), {{timeline}}, {{key_points}}, {{qa}}, {{glossary}},
{{source}}, {{duration}}, {{date}}, {{meta}}). Seuls les espaces réservés que vous incluez sont remplis ;
tout le reste reste textuel. Spécification complète + 3 exemples de modèles
(cours / réunion / tutoriel) dans references/templates.md.
Traitement Local-Only & Suivi des Modifications
Tout le traitement vidéo reste sur votre machine. Les vidéos, trames extraites,
sous-titres, documents de connaissance et fiches sont écrits dans un dossier local runs/ qui est
ignoré par git — rien de vos médias n'est jamais téléchargé ou validé.
Le dépôt GitHub ne suit que les modifications de code et de configuration (scripts, références,
modèles, README). Cela donne un historique clair de l'évolution de la compétence, sans
exposer les médias d'aucun utilisateur. Utilisez des messages de commit descriptifs feat:/fix:/docs:.
Si vous souhaitez un enregistrement local d'une exécution spécifique, écrivez un manifest.json dans ce
dossier d'exécution (chemin emprunté, modèles, arguments, liste des sorties) — mais gardez-le local :
cat > "$RUN/manifest.json" <<EOF
{"video":"~/Movies/lecture.mp4","path":"multimodal","models":{"vlm":"openbmb/minicpm-v4.6:latest"},"duration_seconds":1860,"segments":26}
EOF
Utilisation Par Lots
Pour traiter plusieurs vidéos avec des paramètres cohérents :
python3 scripts/batch_run.py --videos "*.mp4" --out-dir ./batches \
--path asr --language zh --format all
Voir references/batch.md pour la configuration avancée (parallélisation, reprise sur panne,
accumulation de glossaire inter-vidéos).