video-understand
Comprenez le contenu vidéo localement à l'aide de ffmpeg pour l'extraction d'images et de Whisper pour la transcription. Entièrement hors ligne, aucune clé API requise.
Prérequis
ffmpeg+ffprobe(obligatoire) :brew install ffmpegopenai-whisper(optionnel, pour la transcription) :pip install openai-whisper
Commandes
# Détection de scènes + transcription (par défaut)
python3 skills/video-understand/scripts/understand_video.py video.mp4
# Extraction d'images clés
python3 skills/video-understand/scripts/understand_video.py video.mp4 -m keyframe
# Extraction à intervalle régulier
python3 skills/video-understand/scripts/understand_video.py video.mp4 -m interval
# Limiter le nombre d'images extraites
python3 skills/video-understand/scripts/understand_video.py video.mp4 --max-frames 10
# Utiliser un modèle Whisper plus grand
python3 skills/video-understand/scripts/understand_video.py video.mp4 --whisper-model small
# Images uniquement, ignorer la transcription
python3 skills/video-understand/scripts/understand_video.py video.mp4 --no-transcribe
# Mode silencieux (JSON uniquement, sans progression)
python3 skills/video-understand/scripts/understand_video.py video.mp4 -q
# Écrire la sortie dans un fichier
python3 skills/video-understand/scripts/understand_video.py video.mp4 -o result.json
Options CLI
| Option | Description |
|---|---|
video | Fichier vidéo d'entrée (positionnel, obligatoire) |
-m, --mode | Mode d'extraction : scene (par défaut), keyframe, interval |
--max-frames | Nombre maximal d'images à conserver (défaut : 20) |
--whisper-model | Taille du modèle Whisper : tiny, base, small, medium, large (défaut : base) |
--no-transcribe | Ignorer la transcription audio, extraire uniquement les images |
-o, --output | Écrire le résultat JSON dans un fichier au lieu de la sortie standard |
-q, --quiet | Supprimer les messages de progression, afficher uniquement le JSON |
Modes d'extraction
| Mode | Fonctionnement | Idéal pour |
|---|---|---|
scene | Détecte les changements de scène via ffmpeg select='gt(scene,0.3)' | La plupart des vidéos, contenu varié |
keyframe | Extrait les images I (images clés du codec) | Vidéo encodée avec placement naturel des images clés |
interval | Images espacées uniformément selon la durée et max-frames | Échantillonnage fixe, sortie prévisible |
Si le mode scene ne détecte aucun changement de scène, il bascule automatiquement en mode interval.
Sortie
Le script génère un JSON sur la sortie standard (ou dans un fichier avec -o). Voir references/output-format.md pour le schéma complet.
{
"video": "video.mp4",
"duration": 18.076,
"resolution": {"width": 1224, "height": 1080},
"mode": "scene",
"frames": [
{"path": "/abs/path/frame_0001.jpg", "timestamp": 0.0, "timestamp_formatted": "00:00"}
],
"frame_count": 12,
"transcript": [
{"start": 0.0, "end": 2.5, "text": "Bonjour et bienvenue..."}
],
"text": "Transcription complète...",
"note": "Utilisez l'outil Read pour visualiser les images des frames pour une compréhension visuelle."
}
Utilisez l'outil Read sur les chemins des images pour inspecter visuellement les images extraites.
Références
references/output-format.md-- Documentation complète du schéma de sortie JSON