VideoDB Skill
Wahrnehmung + Gedächtnis + Aktionen für Videos, Livestreams und Desktop-Sitzungen.
Verwende dieses Skill, wenn du folgende Aufgaben hast:
Verwendungszweck
- Du benötigst Video- oder Audio-Wahrnehmung, Indexierung, Suche oder Zeitachsenbearbeitung aus Dateien, URLs, Desktop-Sitzungen oder Livestreams.
- Die Aufgabe umfasst Zeitstempel, durchsuchbare Beweise, Untertitel, Clips, Overlays oder Echtzeit-Überwachungsalarme.
- Du möchtest einen einzigen Workflow, der Erfassung, Verständnis, Abruf und Medienaktionen kombiniert.
1) Desktop-Wahrnehmung
- Starten/Stoppen einer Desktop-Sitzung mit Bildschirm-, Mikrofon- und Systemaudio-Aufnahme
- Streamen von Live-Kontext und Speichern von episodischem Sitzungsgedächtnis
- Ausführen von Echtzeit-Warnungen/Triggern basierend auf Gesprochenem und dem, was auf dem Bildschirm passiert
- Erstellen von Sitzungszusammenfassungen, einer durchsuchbaren Zeitleiste und abspielbaren Beweislinks
2) Video-Erfassung + Stream
- Erfassen einer Datei oder URL und Rückgabe eines abspielbaren Web-Stream-Links
- Transkodieren/Normalisieren: Codec, Bitrate, fps, Auflösung, Seitenverhältnis
3) Indexierung + Suche (Zeitstempel + Beweise)
- Erstellen von visuellen, gesprochenen und Schlüsselwort-Indizes
- Suchen und Rückgabe exakter Momente mit Zeitstempeln und abspielbaren Beweisen
- Automatisches Erstellen von Clips aus Suchergebnissen
4) Zeitachsenbearbeitung + Generierung
- Untertitel: generieren, übersetzen, einbrennen
- Overlays: Text/Bild/Branding, bewegte Untertitel
- Audio: Hintergrundmusik, Voiceover, Dubben
- Programmatische Komposition und Exporte über Zeitachsenoperationen
5) Livestreams (RTSP) + Überwachung
- Verbinden von RTSP/Live-Feeds
- Ausführen von Echtzeit-Visual- und Spracherkennung und Auslösen von Ereignissen/Warnungen für Überwachungs-Workflows
Häufige Eingaben
- Lokaler Dateipfad, öffentliche URL oder RTSP-URL
- Desktop-Erfassungsanfrage: starten / stoppen / Sitzung zusammenfassen
- Gewünschte Operationen: Kontext für Verständnis abrufen, Transkodierspezifikation, Index-Spezifikation, Suchanfrage, Clip-Bereiche, Zeitachsenbearbeitung, Alarmregeln
Häufige Ausgaben
- Stream-URL
- Suchergebnisse mit Zeitstempeln und Beweislinks
- Generierte Assets: Untertitel, Audio, Bilder, Clips
- Ereignis-/Alarm-Payloads für Livestreams
- Sitzungszusammenfassungen und Gedächtniseinträge
Beispielhafte Prompt-Formulierungen
- "Starte die Desktop-Erfassung und alarmiere, wenn ein Passwortfeld erscheint."
- "Zeichne meine Sitzung auf und erstelle eine umsetzbare Zusammenfassung, wenn sie endet."
- "Erfasse diese Datei und gib einen abspielbaren Stream-Link zurück."
- "Indiziere diesen Ordner und finde jede Szene mit Personen, gib die Zeitstempel zurück."
- "Generiere Untertitel, brenne sie ein und füge leichte Hintergrundmusik hinzu."
- "Verbinde diese RTSP-URL und alarmiere, wenn eine Person die Zone betritt."
Python-Code ausführen
Bevor du einen VideoDB-Code ausführst, wechsle in das Projektverzeichnis und lade die Umgebungsvariablen:
from dotenv import load_dotenv
load_dotenv(".env")
import videodb
conn = videodb.connect()
Dies liest VIDEO_DB_API_KEY aus:
- Umgebung (falls bereits exportiert)
.env-Datei des Projekts im aktuellen Verzeichnis
Fehlt der Schlüssel, löst videodb.connect() automatisch einen AuthenticationError aus.
Schreibe KEINE Skriptdatei, wenn ein kurzer Inline-Befehl ausreicht.
Verwende bei Inline-Python (python -c "...") immer korrekt formatierten Code – verwende Semikolons, um Anweisungen zu trennen, und halte es lesbar. Für mehr als ~3 Anweisungen verwende stattdessen einen 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
Einrichtung
Wenn der Benutzer "videodb einrichten" oder ähnliches sagt:
1. SDK installieren
pip install "videodb[capture]" python-dotenv
Wenn videodb[capture] unter Linux fehlschlägt, installiere ohne das capture-Extra:
pip install videodb python-dotenv
2. API-Schlüssel konfigurieren
Der Benutzer muss VIDEO_DB_API_KEY mit einer der folgenden Methoden setzen:
- In der Terminal-Umgebung exportieren (vor dem Start von Claude):
export VIDEO_DB_API_KEY=dein-key - Projekt-.env-Datei: Speichere
VIDEO_DB_API_KEY=dein-keyin der.env-Datei des Projekts
Einen kostenlosen API-Schlüssel erhältst du unter https://console.videodb.io (50 kostenlose Uploads, keine Kreditkarte erforderlich).
Verwalte den API-Schlüssel NICHT selbst. Lass den Benutzer ihn immer selbst setzen.
Kurzreferenz
Medien hochladen
# URL
video = coll.upload(url="https://example.com/video.mp4")
# YouTube
video = coll.upload(url="https://www.youtube.com/watch?v=VIDEO_ID")
# Lokale Datei
video = coll.upload(file_path="/path/to/video.mp4")
Transkript + Untertitel
# force=True überspringt den Fehler, falls das Video bereits indiziert ist
video.index_spoken_words(force=True)
text = video.get_transcript_text()
stream_url = video.add_subtitle()
In Videos suchen
from videodb.exceptions import InvalidRequestError
video.index_spoken_words(force=True)
# search() löst InvalidRequestError aus, wenn keine Ergebnisse gefunden werden.
# Immer in try/except einwickeln und "No results found" als leeres Ergebnis behandeln.
try:
results = video.search("product demo")
shots = results.get_shots()
stream_url = results.compile()
except InvalidRequestError as e:
if "No results found" in str(e):
shots = []
else:
raise
Szenensuche
import re
from videodb import SearchType, IndexType, SceneExtractionType
from videodb.exceptions import InvalidRequestError
# index_scenes() hat keinen force-Parameter – es löst einen Fehler aus, falls ein Szenenindex
# bereits existiert. Extrahiere die vorhandene Index-ID aus dem Fehler.
try:
scene_index_id = video.index_scenes(
extraction_type=SceneExtractionType.shot_based,
prompt="Beschreibe den visuellen Inhalt dieser Szene.",
)
except Exception as e:
match = re.search(r"id\s+([a-f0-9]+)", str(e))
if match:
scene_index_id = match.group(1)
else:
raise
# Verwende score_threshold, um Rauschen mit geringer Relevanz herauszufiltern (empfohlen: 0.3+)
try:
results = video.search(
query="Person, die auf einem Whiteboard schreibt",
search_type=SearchType.semantic,
index_type=IndexType.scene,
scene_index_id=scene_index_id,
score_threshold=0.3,
)
shots = results.get_shots()
stream_url = results.compile()
except InvalidRequestError as e:
if "No results found" in str(e):
shots = []
else:
raise
Zeitachsenbearbeitung
Wichtig: Validiere immer die Zeitstempel, bevor du eine Zeitachse erstellst:
startmuss >= 0 sein (negative Werte werden stillschweigend akzeptiert, erzeugen aber defekte Ausgaben)startmuss <endseinendmuss <=video.lengthsein
from videodb.timeline import Timeline
from videodb.asset import VideoAsset, TextAsset, TextStyle
timeline = Timeline(conn)
timeline.add_inline(VideoAsset(asset_id=video.id, start=10, end=30))
timeline.add_overlay(0, TextAsset(text="The End", duration=3, style=TextStyle(fontsize=36)))
stream_url = timeline.generate_stream()
Video transkodieren (Auflösungs-/Qualitätsänderung)
from videodb import TranscodeMode, VideoConfig, AudioConfig
# Server-seitige Änderung von Auflösung, Qualität oder Seitenverhältnis
job_id = 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),
)
Seitenverhältnis anpassen (für soziale Plattformen)
Warnung: reframe() ist eine langsame Server-Operation. Bei langen Videos kann es mehrere Minuten dauern und zu Zeitüberschreitungen führen. Best Practices:
- Beschränke den Vorgang nach Möglichkeit immer auf ein kurzes Segment mit
start/end - Verwende für vollständige Videos
callback_urlfür die asynchrone Verarbeitung - Schneide das Video zuerst auf einer
Timelinezurecht und passe dann das Seitenverhältnis des kürzeren Ergebnisses an
from videodb import ReframeMode
# Bevorzugt ein kurzes Segment anpassen:
reframed = video.reframe(start=0, end=60, target="vertical", mode=ReframeMode.smart)
# Asynchrone Anpassung für vollständige Videos (gibt None zurück, Ergebnis per Webhook):
video.reframe(target="vertical", callback_url="https://example.com/webhook")
# Voreinstellungen: "vertical" (9:16), "square" (1:1), "landscape" (16:9)
reframed = video.reframe(start=0, end=60, target="square")
# Benutzerdefinierte Abmessungen
reframed = video.reframe(start=0, end=60, target={"width": 1280, "height": 720})
Generative Medien
image = coll.generate_image(
prompt="ein Sonnenuntergang über Bergen",
aspect_ratio="16:9",
)
Fehlerbehandlung
from videodb.exceptions import AuthenticationError, InvalidRequestError
try:
conn = videodb.connect()
except AuthenticationError:
print("Überprüfe deinen VIDEO_DB_API_KEY")
try:
video = coll.upload(url="https://example.com/video.mp4")
except InvalidRequestError as e:
print(f"Upload fehlgeschlagen: {e}")
Häufige Fallstricke
| Szenario | Fehlermeldung | Lösung |
|---|---|---|
| Indizieren eines bereits indizierten Videos | Spoken word index for video already exists | Verwende video.index_spoken_words(force=True), um zu überspringen, falls bereits indiziert |
| Szenenindex existiert bereits | Scene index with id XXXX already exists | Extrahiere die vorhandene scene_index_id aus dem Fehler mit re.search(r"id\s+([a-f0-9]+)", str(e)) |
| Suche findet keine Übereinstimmungen | InvalidRequestError: No results found | Fange die Ausnahme ab und behandle sie als leeres Ergebnis (shots = []) |
| Zeitüberschreitung bei reframe | Blockiert unbegrenzt bei langen Videos | Verwende start/end, um das Segment zu begrenzen, oder übergib callback_url für asynchrone Verarbeitung |
| Negative Zeitstempel auf der Timeline | Erzeugt stillschweigend einen defekten Stream | Validiere immer start >= 0, bevor du VideoAsset erstellst |
generate_video() / create_collection() schlägt fehl | Operation not allowed oder maximum limit | Funktionen mit Tarifbeschränkung – informiere den Benutzer über die Tarifgrenzen |
Zusätzliche Dokumentation
Die Referenzdokumentation befindet sich im Ordner reference/ neben dieser SKILL.md-Datei. Verwende das Glob-Tool, um sie bei Bedarf zu finden.
- reference/api-reference.md - Vollständige VideoDB Python SDK API-Referenz
- reference/search.md - Ausführlicher Leitfaden zur Videosuche (gesprochene Wörter und szenenbasiert)
- reference/editor.md - Zeitachsenbearbeitung, Assets und Komposition
- reference/streaming.md - HLS-Streaming und sofortige Wiedergabe
- reference/generative.md - KI-gestützte Mediengenerierung (Bilder, Video, Audio)
- reference/rtstream.md - Live-Stream-Erfassungs-Workflow (RTSP/RTMP)
- reference/rtstream-reference.md - RTStream SDK-Methoden und KI-Pipelines
- reference/capture.md - Desktop-Erfassungs-Workflow
- reference/capture-reference.md - Capture SDK und WebSocket-Ereignisse
- reference/use-cases.md - Häufige Videoverarbeitungsmuster und Beispiele
Bildschirmaufnahme (Desktop-Erfassung)
Verwende ws_listener.py, um WebSocket-Ereignisse während Aufnahmesitzungen zu erfassen. Die Desktop-Erfassung unterstützt nur macOS.
Kurzanleitung
- Listener starten:
python scripts/ws_listener.py & - WebSocket-ID abrufen:
cat /tmp/videodb_ws_id - Erfassungscode ausführen (siehe reference/capture.md für den vollständigen Workflow)
- Ereignisse werden geschrieben nach:
/tmp/videodb_events.jsonl
Ereignisse abfragen
import json
events = [json.loads(l) for l in open("/tmp/videodb_events.jsonl")]
# Alle Transkripte abrufen
transcripts = [e["data"]["text"] for e in events if e.get("channel") == "transcript"]
# Visuelle Beschreibungen der letzten 5 Minuten abrufen
import time
cutoff = time.time() - 300
recent_visual = [e for e in events
if e.get("channel") == "visual_index" and e["unix_ts"] > cutoff]
Hilfsskripte
- scripts/ws_listener.py - WebSocket-Ereignis-Listener (schreibt in JSONL)
Den vollständigen Erfassungs-Workflow findest du unter reference/capture.md.
Verwende ffmpeg, moviepy oder lokale Codierungstools NICHT, wenn VideoDB die Operation unterstützt. Die folgenden werden alle server-seitig von VideoDB erledigt: Trimmen, Zusammenfügen von Clips, Überlagern von Audio oder Musik, Hinzufügen von Untertiteln, Text-/Bild-Overlays, Transkodieren, Auflösungsänderungen, Konvertierung des Seitenverhältnisses, Größenänderung für Plattformanforderungen, Transkription und Medienerzeugung. Verwende lokale Tools nur für Operationen, die unter „Einschränkungen“ in reference/editor.md aufgeführt sind (Übergänge, Geschwindigkeitsänderungen, Zuschneiden/Zoomen, Farbkorrektur, Lautstärkemischung).
Wann was verwenden
| Problem | VideoDB-Lösung |
|---|---|
| Plattform lehnt das Seitenverhältnis oder die Auflösung des Videos ab | video.reframe() oder conn.transcode() mit VideoConfig |
| Video für Twitter/Instagram/TikTok zuschneiden | video.reframe(target="vertical") oder target="square" |
| Auflösung ändern (z.B. 1080p → 720p) | conn.transcode() mit VideoConfig(resolution=720) |
| Audio/Musik über Video legen | AudioAsset auf einer Timeline |
| Untertitel hinzufügen | video.add_subtitle() oder CaptionAsset |
| Clips kombinieren/trimmen | VideoAsset auf einer Timeline |
| Voiceover, Musik oder Soundeffekte generieren | coll.generate_voice(), generate_music(), generate_sound_effect() |
Repository
https://github.com/video-db/skills
Gepflegt von: VideoDB
Einschränkungen
- Verwende dieses Skill nur, wenn die Aufgabe eindeutig dem oben beschriebenen Umfang entspricht.
- Behandle die Ausgabe nicht als Ersatz für umgebungsspezifische Validierung, Tests oder Expertenüberprüfung.
- Frage nach und bitte um Klärung, wenn erforderliche Eingaben, Berechtigungen, Sicherheitsgrenzen oder Erfolgskriterien fehlen.