SentrySearch, un outil de recherche vidéo sémantique à l’échelle sub-seconde exploitant l’embedding vidéo de Gemini

• Système de recherche sémantique qui permet de rechercher des scènes en langage naturel dans des fichiers vidéo, comme des vidéos de dashcam, puis de découper automatiquement la portion correspondante
• Utilise le modèle Google Gemini Embedding 2 pour encoder directement la vidéo en vecteurs, stockés dans ChromaDB afin de les comparer directement à des requêtes textuelles
• Les vidéos sont encodées via ffmpeg en chunks qui se chevauchent, et la recherche renvoie les passages les plus proches à une vitesse sub-seconde
• Des fonctions de prétraitement et de saut des images fixes réduisent le coût des appels API, avec un coût d’environ 2,84 $ pour indexer 1 heure de vidéo
• Exploite la fonction d’embedding vidéo direct de Gemini Embedding 2 pour permettre une recherche sémantique rapide dans des vidéos de plusieurs heures sans génération de sous-titres

---

Aperçu

• SentrySearch est un outil de recherche sémantique dans des vidéos de dashcam qui renvoie un clip découpé (trimmed clip) contenant la scène recherchée lorsqu’un utilisateur saisit une requête en langage naturel
• Il utilise le modèle Google Gemini Embedding 2 pour encoder directement la vidéo en vecteurs, puis les stocke dans la base locale ChromaDB
• La requête textuelle est encodée dans le même espace vectoriel afin de retrouver les fragments vidéo les plus similaires
• Le résultat de la recherche est automatiquement découpé depuis le fichier source et enregistré, avec une vitesse de recherche sub-seconde

Fonctionnement

• Les vidéos sont divisées en segments qui se chevauchent (overlapping chunks), chacun étant directement encodé via le modèle Gemini Embedding
• Chaque vecteur d’embedding est stocké dans ChromaDB, et lors d’une recherche, la requête textuelle est convertie dans le même espace vectoriel pour le matching
• Le segment avec le score de similarité le plus élevé est automatiquement découpé du fichier d’origine et enregistré comme clip
• ffmpeg est utilisé pour le découpage et le trimming des vidéos ; s’il n’est pas installé sur le système, imageio-ffmpeg est utilisé automatiquement

Installation et configuration initiale

• Installation possible sous Python 3.10 ou supérieur avec la commande suivante
  • après git clone, exécuter pip install -e .
• La commande sentrysearch init permet de configurer la clé API Gemini et de l’enregistrer dans le fichier .env
  • un embedding de test est effectué pour valider la clé
• En configuration manuelle, il est possible de copier .env.example puis d’ajouter directement la clé API

Commandes et options principales

• index

  • lance l’indexation en analysant récursivement les fichiers .mp4 dans le dossier indiqué
  • chaque fichier est découpé en plusieurs chunks avant encodage
  • options
    • --chunk-duration : durée d’un chunk (en secondes)
    • --overlap : durée de chevauchement entre les chunks
    • --no-preprocess : désactive la réduction de résolution et de fréquence d’images
    • --target-resolution : résolution cible du prétraitement (480p par défaut)
    • --target-fps : fréquence d’images cible du prétraitement (5 fps par défaut)
    • --no-skip-still : encode aussi tous les segments d’images fixes

• search

  • exemple : sentrysearch search "red truck running a stop sign"
  • les résultats sont affichés avec leur score de similarité, et le meilleur résultat est automatiquement découpé et enregistré
  • si le score de similarité est inférieur ou égal au seuil par défaut (0.35), une invite de confirmation s’affiche
  • options
    • --results N : nombre de résultats à afficher
    • --output-dir DIR : chemin d’enregistrement des clips
    • --no-trim : désactive le découpage automatique
    • --threshold : ajuste le seuil de similarité

• stats

  • affiche le nombre total de chunks indexés et le nombre de fichiers source

• --verbose

  • affiche des informations de debug comme la dimension des embeddings, le temps de réponse de l’API et les scores de similarité

Contexte technique

• Gemini Embedding 2 peut encoder directement la vidéo et la comparer à des requêtes textuelles dans le même espace vectoriel à 768 dimensions
• Aucun génération de sous-titres ni captioning de frames séparé n’est nécessaire
• Par exemple, une requête textuelle comme “red truck at a stop sign” peut être comparée directement à un clip vidéo de 30 secondes
• Cette capacité permet une recherche sémantique sub-seconde même dans des vidéos de plusieurs heures

Structure des coûts

• Avec les réglages par défaut (chunks de 30 secondes, chevauchement de 5 secondes), l’indexation d’une heure de vidéo coûte environ 2,84 $
  • l’API Gemini ne traite qu’1 frame par seconde dans la vidéo envoyée
  • le prétraitement réduit la vidéo à 480p et 5 fps afin d’optimiser la vitesse de transfert et d’éviter les timeouts

• Optimisations pour réduire les coûts

  • prétraitement (preprocessing) : réduit la taille des données envoyées et le temps de transfert
  • saut des images fixes (still-frame skipping) : évite d’encoder les segments sans changement visuel
    • particulièrement utile pour les longues vidéos enregistrées pendant le stationnement
  • les requêtes de recherche n’effectuent qu’un embedding texte, donc le coût est presque nul
  • options d’ajustement supplémentaires
  • --chunk-duration, --overlap : ajustent le nombre d’appels API
  • --no-skip-still : encode tous les chunks
  • --target-resolution, --target-fps : ajustent la qualité du prétraitement
  • --no-preprocess : envoie les chunks d’origine tels quels

Limites et améliorations futures

• La détection des images fixes repose sur une heuristique fondée sur la comparaison de taille de fichiers JPEG, ce qui peut rater des mouvements subtils ou inclure à tort des segments statiques
• La qualité de recherche dépend des frontières de chunks ; si un événement s’étend sur deux segments, il peut ne pas être capturé parfaitement
  • une amélioration future pourrait passer par un découpage basé sur la détection de scènes (scene detection)
• Gemini Embedding 2 est actuellement en phase preview, et le comportement de l’API ainsi que la tarification peuvent évoluer

Compatibilité et prérequis

• Fonctionne avec tous les fichiers vidéo au format .mp4 et n’est pas limité aux vidéos Tesla Sentry Mode
• Explore récursivement tous les fichiers .mp4 quelle que soit l’arborescence des dossiers
• Prérequis
  • Python 3.10 ou supérieur
  • ffmpeg installé (ou utilisation automatique de imageio-ffmpeg)
  • clé API Gemini requise (clé gratuite disponible : aistudio.google.com/apikey)