Compétence VideoDB
Perception + mémoire + actions pour la vidéo, les flux en direct et les sessions de bureau.
Quand utiliser
Perception de bureau
- Démarrer/arrêter une session de bureau capturant l'écran, le micro et l'audio système
- Diffuser le contexte en direct et stocker la mémoire de session épisodique
- Exécuter des alertes/déclencheurs en temps réel sur ce qui est dit et ce qui se passe à l'écran
- Produire des résumés de session, une chronologie consultable et des liens de preuve lisibles
Ingestion vidéo + diffusion
- Ingérer un fichier ou une URL et retourner un lien de flux web lisible
- Transcoder/normaliser : codec, débit, fps, résolution, rapport hauteur/largeur
Indexation + recherche (horodatages + preuves)
- Construire des index visuels, vocaux et par mots-clés
- Rechercher et retourner des moments précis avec horodatages et preuves lisibles
- Créer automatiquement des extraits à partir des résultats de recherche
Montage temporel + génération
- Sous-titres : générer, traduire, incruster
- Incrustations : texte/image/branding, légendes animées
- Audio : musique de fond, voix off, doublage
- Composition programmatique et exportations via opérations de chronologie
Flux en direct (RTSP) + surveillance
- Connecter des flux RTSP/en direct
- Exécuter une compréhension visuelle et vocale en temps réel et émettre des événements/alertes pour les workflows de surveillance
Comment ça fonctionne
Entrées courantes
- Chemin de fichier local, URL publique ou URL RTSP
- Demande de capture de bureau : démarrer / arrêter / résumer une session
- Opérations souhaitées : obtenir le contexte pour la compréhension, spécification de transcodage, spécification d'index, requête de recherche, plages d'extraits, montages temporels, règles d'alerte
Sorties courantes
- URL de flux
- Résultats de recherche avec horodatages et liens de preuve
- Contenus générés : sous-titres, audio, images, extraits
- Charges utiles d'événements/alertes pour les flux en direct
- Résumés de session de bureau et entrées de mémoire
Exécution de code Python
Avant d'exécuter du code VideoDB, placez-vous dans le répertoire du projet et chargez les variables d'environnement :
from dotenv import load_dotenv
load_dotenv(".env")
import videodb
conn = videodb.connect()
Ceci lit VIDEO_DB_API_KEY depuis :
- L'environnement (si déjà exporté)
- Le fichier
.envdu projet dans le répertoire courant
Si la clé est manquante, videodb.connect() lève automatiquement AuthenticationError.
N'écrivez PAS un fichier de script lorsqu'une courte commande en ligne suffit.
Lorsque vous écrivez du Python en ligne (python -c "..."), utilisez toujours un code correctement formaté — utilisez des points-virgules pour séparer les instructions et restez lisible. Pour tout ce qui dépasse environ 3 instructions, utilisez plutôt un heredoc :
python << 'EOF'
from dotenv import load_dotenv
load_dotenv(".env")
import videodb
conn = videodb.connect()
coll = conn.get_collection()
print(f"Videos: {len(coll.get_videos())}")
EOF
Configuration
Lorsque l'utilisateur demande de "configurer videodb" ou similaire :
1. Installer le SDK
pip install "videodb[capture]" python-dotenv
Si videodb[capture] échoue sur Linux, installez sans l'extension capture :
pip install videodb python-dotenv
2. Configurer la clé API
L'utilisateur doit définir VIDEO_DB_API_KEY en utilisant l'une ou l'autre des méthodes :
- Exporter dans le terminal (avant de démarrer Claude) :
export VIDEO_DB_API_KEY=ma-clé - Fichier
.envdu projet : EnregistrezVIDEO_DB_API_KEY=ma-clédans le fichier.envdu projet
Obtenez une clé API gratuite sur console.videodb.io (50 téléversements gratuits, pas de carte de crédit).
Ne lisez PAS, n'écrivez PAS et ne gérez PAS vous-même la clé API. Laissez toujours l'utilisateur la définir.
Référence rapide
Téléverser un média
# URL
video = coll.upload(url="https://example.com/video.mp4")
# YouTube
video = coll.upload(url="https://www.youtube.com/watch?v=VIDEO_ID")
# Fichier local
video = coll.upload(file_path="/chemin/vers/video.mp4")
Transcription + sous-titres
# force=True ignore l'erreur si la vidéo est déjà indexée
video.index_spoken_words(force=True)
texte = video.get_transcript_text()
url_flux = video.add_subtitle()
Rechercher dans des vidéos
from videodb.exceptions import InvalidRequestError
video.index_spoken_words(force=True)
# search() lève InvalidRequestError quand aucun résultat n'est trouvé.
# Toujours envelopper dans try/except et traiter "No results found" comme vide.
try:
resultats = video.search("démo produit")
plans = resultats.get_shots()
url_flux = resultats.compile()
except InvalidRequestError as e:
if "No results found" in str(e):
plans = []
else:
raise
Recherche par scène
import re
from videodb import SearchType, IndexType, SceneExtractionType
from videodb.exceptions import InvalidRequestError
# index_scenes() n'a pas de paramètre force — il lève une erreur si un index
# de scène existe déjà. Extrayez l'ID d'index existant de l'erreur.
try:
id_index_scene = video.index_scenes(
extraction_type=SceneExtractionType.shot_based,
prompt="Décrivez le contenu visuel de cette scène.",
)
except Exception as e:
correspondance = re.search(r"id\s+([a-f0-9]+)", str(e))
if correspondance:
id_index_scene = correspondance.group(1)
else:
raise
# Utilisez score_threshold pour filtrer le bruit de faible pertinence (recommandé : 0.3+)
try:
resultats = video.search(
query="personne écrivant sur un tableau blanc",
search_type=SearchType.semantic,
index_type=IndexType.scene,
scene_index_id=id_index_scene,
score_threshold=0.3,
)
plans = resultats.get_shots()
url_flux = resultats.compile()
except InvalidRequestError as e:
if "No results found" in str(e):
plans = []
else:
raise
Montage temporel
Important : validez toujours les horodatages avant de construire une chronologie :
startdoit être >= 0 (les valeurs négatives sont acceptées silencieusement mais produisent un résultat cassé)startdoit être <endenddoit être <=video.length
from videodb.timeline import Timeline
from videodb.asset import VideoAsset, TextAsset, TextStyle
chronologie = Timeline(conn)
chronologie.add_inline(VideoAsset(asset_id=video.id, start=10, end=30))
chronologie.add_overlay(0, TextAsset(text="La Fin", duration=3, style=TextStyle(fontsize=36)))
url_flux = chronologie.generate_stream()
Transcodage vidéo (changement de résolution/qualité)
from videodb import TranscodeMode, VideoConfig, AudioConfig
# Modifier la résolution, la qualité ou le rapport hauteur/largeur côté serveur
id_tache = conn.transcode(
source="https://example.com/video.mp4",
callback_url="https://example.com/webhook",
mode=TranscodeMode.economy,
video_config=VideoConfig(resolution=720, quality=23, aspect_ratio="16:9"),
audio_config=AudioConfig(mute=False),
)
Recadrer le rapport hauteur/largeur (pour les réseaux sociaux)
Attention : reframe() est une opération lente côté serveur. Pour les vidéos longues, elle peut prendre
plusieurs minutes et expirer. Bonnes pratiques :
- Limitez toujours à un court segment avec
start/endlorsque c'est possible - Pour les vidéos de pleine durée, utilisez
callback_urlpour un traitement asynchrone - Rognez d'abord la vidéo sur une
Timeline, puis recadrez le résultat plus court
from videodb import ReframeMode
# Préférez toujours recadrer un court segment :
recadree = video.reframe(start=0, end=60, target="vertical", mode=ReframeMode.smart)
# Recadrage asynchrone pour les vidéos de pleine durée (retourne None, résultat via webhook) :
video.reframe(target="vertical", callback_url="https://example.com/webhook")
# Préréglages : "vertical" (9:16), "square" (1:1), "landscape" (16:9)
recadree = video.reframe(start=0, end=60, target="square")
# Dimensions personnalisées
recadree = video.reframe(start=0, end=60, target={"width": 1280, "height": 720})
Média génératif
image = coll.generate_image(
prompt="un coucher de soleil sur des montagnes",
aspect_ratio="16:9",
)
Gestion des erreurs
from videodb.exceptions import AuthenticationError, InvalidRequestError
try:
conn = videodb.connect()
except AuthenticationError:
print("Vérifiez votre VIDEO_DB_API_KEY")
try:
video = coll.upload(url="https://example.com/video.mp4")
except InvalidRequestError as e:
print(f"Échec du téléversement : {e}")
Pièges courants
| Scénario | Message d'erreur | Solution |
|---|---|---|
| Indexation d'une vidéo déjà indexée | Spoken word index for video already exists | Utilisez video.index_spoken_words(force=True) pour ignorer si déjà indexé |
| Index de scène déjà existant | Scene index with id XXXX already exists | Extrayez l'scene_index_id existant de l'erreur avec re.search(r"id\s+([a-f0-9]+)", str(e)) |
| La recherche ne trouve aucune correspondance | InvalidRequestError: No results found | Attrapez l'exception et traitez comme des résultats vides (plans = []) |
| Recadrage expiré | Bloque indéfiniment sur les vidéos longues | Utilisez start/end pour limiter le segment, ou passez callback_url pour l'asynchrone |
| Horodatages négatifs sur la chronologie | Produit silencieusement un flux cassé | Validez toujours start >= 0 avant de créer VideoAsset |
generate_video() / create_collection() échoue | Operation not allowed ou maximum limit | Fonctionnalités limitées par le plan — informez l'utilisateur des limites du plan |
Exemples
Invites canoniques
- "Démarrer la capture de bureau et alerter lorsqu'un champ de mot de passe apparaît."
- "Enregistrer ma session et produire un résumé exploitable à la fin."
- "Ingérer ce fichier et retourner un lien de flux lisible."
- "Indexer ce dossier et trouver chaque scène avec des personnes, retourner les horodatages."
- "Générer des sous-titres, les incruster, et ajouter une musique de fond légère."
- "Connecter cette URL RTSP et alerter lorsqu'une personne entre dans la zone."
Enregistrement d'écran (capture de bureau)
Utilisez ws_listener.py pour capturer les événements WebSocket pendant les sessions d'enregistrement. La capture de bureau prend en charge macOS uniquement.
Démarrage rapide
- Choisissez le répertoire d'état :
STATE_DIR="${VIDEODB_EVENTS_DIR:-$HOME/.local/state/videodb}" - Démarrez l'écouteur :
VIDEODB_EVENTS_DIR="$STATE_DIR" python scripts/ws_listener.py --clear "$STATE_DIR" & - Obtenez l'ID WebSocket :
cat "$STATE_DIR/videodb_ws_id" - Exécutez le code de capture (voir reference/capture.md pour le workflow complet)
- Événements écrits dans :
$STATE_DIR/videodb_events.jsonl
Utilisez --clear chaque fois que vous démarrez une nouvelle session de capture afin que les événements de transcription et visuels obsolètes ne fuient pas dans la nouvelle session.
Interroger les événements
import json
import os
import time
from pathlib import Path
repertoire_evenements = Path(os.environ.get("VIDEODB_EVENTS_DIR", Path.home() / ".local" / "state" / "videodb"))
fichier_evenements = repertoire_evenements / "videodb_events.jsonl"
evenements = []
if fichier_evenements.exists():
with fichier_evenements.open(encoding="utf-8") as handle:
for ligne in handle:
try:
evenements.append(json.loads(ligne))
except json.JSONDecodeError:
continue
transcriptions = [e["data"]["text"] for e in evenements if e.get("channel") == "transcript"]
seuil = time.time() - 300
recent_visuel = [
e for e in evenements
if e.get("channel") == "visual_index" and e["unix_ts"] > seuil
]
Documentation supplémentaire
La documentation de référence se trouve dans le répertoire reference/ adjacent à ce fichier SKILL.md. Utilisez l'outil Glob pour le localiser si nécessaire.
- reference/api-reference.md - Référence complète de l'API Python SDK VideoDB
- reference/search.md - Guide approfondi de la recherche vidéo (parole et basée sur les scènes)
- reference/editor.md - Montage temporel, assets et composition
- reference/streaming.md - Streaming HLS et lecture instantanée
- reference/generative.md - Génération de médias par IA (images, vidéo, audio)
- reference/rtstream.md - Workflow d'ingestion de flux en direct (RTSP/RTMP)
- reference/rtstream-reference.md - Méthodes du SDK RTStream et pipelines IA
- reference/capture.md - Workflow de capture de bureau
- reference/capture-reference.md - SDK de capture et événements WebSocket
- reference/use-cases.md - Modèles et exemples courants de traitement vidéo
N'utilisez pas ffmpeg, moviepy ou des outils d'encodage locaux lorsque VideoDB prend en charge l'opération. Les opérations suivantes sont toutes gérées côté serveur par VideoDB — rognage, combinaison d'extraits, incrustation audio ou musicale, ajout de sous-titres, incrustations texte/image, transcodage, changements de résolution, conversion de rapport hauteur/largeur, redimensionnement pour les exigences de plateforme, transcription et génération de médias. Revenez aux outils locaux uniquement pour les opérations listées dans Limitations dans reference/editor.md (transitions, changements de vitesse, recadrage/zoom, étalonnage des couleurs, mixage de volume).
Quand utiliser quoi
| Problème | Solution VideoDB |
|---|---|
| La plateforme rejette le rapport hauteur/largeur ou la résolution de la vidéo | video.reframe() ou conn.transcode() avec VideoConfig |
| Besoin de redimensionner une vidéo pour Twitter/Instagram/TikTok | video.reframe(target="vertical") ou target="square" |
| Besoin de changer la résolution (ex. 1080p → 720p) | conn.transcode() avec VideoConfig(resolution=720) |
| Besoin d'incruster de l'audio/de la musique sur une vidéo | AudioAsset sur une Timeline |
| Besoin d'ajouter des sous-titres | video.add_subtitle() ou CaptionAsset |
| Besoin de combiner/rogner des extraits | VideoAsset sur une Timeline |
| Besoin de générer une voix off, de la musique ou des effets sonores | coll.generate_voice(), generate_music(), generate_sound_effect() |
Provenance
Le matériel de référence de cette compétence est fourni localement sous skills/videodb/reference/.
Utilisez les copies locales ci-dessus au lieu de suivre des liens de dépôt externes au moment de l'exécution.