Communitygithub.com

CacinieP/video2knowledge

Convertit des vidéos en sous-titres horodatés et en artefacts de connaissance structurés, avec deux voies d'ingestion locale.

Qu'est-ce que video2knowledge ?

Video2Knowledge est un outil puissant pour transformer des vidéos en ressources d'étude structurées, entièrement en local par défaut. Il offre deux voies d'ingestion : (1) un VLM multimodal natif (jusqu'à 4B paramètres via Ollama) lit les trames vidéo échantillonnées pour générer des légendes horodatées ; (2) la transcription ASR via faster-whisper localement, ou FunASR Paraformer pour le mandarin (amélioration mesurée de 44% à 94% sur les homophones), avec un correctif de pinyin tenant compte du ton. L'outil affine ensuite le tout en un document de connaissance structuré (modèle personnalisable), une page HTML autonome, un CSV de fiches de connaissances dédoublonnées, un paquet Anki APKG, et des notes illustrées en deux vues : la version complète avec narration citée et une version distillée pour la révision. Le traitement reste entièrement local par défaut – aucune vidéo, audio ou sortie ne quitte l'hôte ; les endpoints ASR/LLM cloud sont facultatifs et explicitement signalés comme tiers. Idéal pour sous-titrer ou résumer une vidéo, créer des fiches d'étude à partir d'un cours ou d'un enregistrement, ou transformer un screencast en documentation technique.

Compatible avec~Claude Code✓Codex CLI~Cursor
npx skills add CacinieP/video2knowledge

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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 correctsvitesse
faster-whisper small + mots-clés44%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éfactFichierSection
2.1 Document de connaissance (modèle)knowledge.mdutilise assets/default-template.md ou --template <fichier>
2.2 Page HTML autonomeknowledge.htmlchronologie cliquable [mm:ss]
2.2b Export bureau/impressionknowledge.docx / knowledge.pdf--format docx / --format pdf (automatique dans --format all si python-docx/fpdf2 installé)
2.3 Fiches de connaissancescards.csvquestion,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.htmltrames clés × narration, voir ci-dessous
2.4b Notes bureau/impressionnotes.docx / notes.pdfbuild_notes.py --docx --pdf (trames intégrées)
2.4c Notes distillées (纯享版)notes-distilled.md / .docx / .pdfmê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 :

FichierContientPour
notes.mdtrames + notes + 原声 citérecouper les mots exacts de l'enseignant
notes-distilled.mdmêmes nœuds, mêmes trames, pas de narration citéeré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).

Skills associés