Was macht VideoDB Skill?
Wahrnehmung + Gedächtnis + Aktionen für Video, Live-Streams und Desktop-Sitzungen.
Verwendung
Desktop-Wahrnehmung
- Desktop-Sitzung starten/stoppen, die Bildschirm, Mikrofon und Systemaudio erfasst
- Live-Kontext streamen und episodisches Sitzungsgedächtnis speichern
- Echtzeit-Warnungen/Trigger auslösen bei Gesprochenem und Geschehenem auf dem Bildschirm
- Sitzungszusammenfassungen, eine durchsuchbare Zeitleiste und abspielbare Beweislinks erstellen
Video-Import + Stream
- Datei oder URL importieren und einen abspielbaren Web-Stream-Link zurückgeben
- Transkodieren/normalisieren: Codec, Bitrate, fps, Auflösung, Seitenverhältnis
Indizierung + Suche (Zeitstempel + Beweise)
- Visuelle, gesprochene und Stichwort-Indizes erstellen
- Suchen und exakte Momente mit Zeitstempeln und abspielbaren Beweisen zurückgeben
- Automatisch Clips aus Suchergebnissen erstellen
Timeline-Bearbeitung + Generierung
- Untertitel: generieren, übersetzen, einbrennen
- Overlays: Text/Bild/Branding, Bewegungsuntertitel
- Audio: Hintergrundmusik, Voiceover, Dubbing
- Programmatische Komposition und Export via Timeline-Operationen
Live-Streams (RTSP) + Überwachung
- RTSP-/Live-Feeds verbinden
- Echtzeit-Visual- und Spracherkennung ausführen und Ereignisse/Warnungen für Überwachungs-Workflows ausgeben
Funktionsweise
Übliche Eingaben
- Lokaler Dateipfad, öffentliche URL oder RTSP-URL
- Desktop-Aufzeichnungsanfrage: Sitzung starten / stoppen / zusammenfassen
- Gewünschte Operationen: Kontext zum Verständnis, Transkodierspezifikation, Indexspezifikation, Suchabfrage, Clip-Bereiche, Timeline-Bearbeitungen, Alarmregeln
Übliche Ausgaben
- Stream-URL
- Suchergebnisse mit Zeitstempeln und Beweislinks
- Generierte Assets: Untertitel, Audio, Bilder, Clips
- Ereignis-/Alarm-Payloads für Live-Streams
- Desktop-Sitzungszusammenfassungen und Gedächtniseinträge
Python-Code ausführen
Vor dem Ausführen von VideoDB-Code in das Projektverzeichnis wechseln und Umgebungsvariablen laden:
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.
Schreiben Sie KEINE Skriptdatei, wenn ein kurzer Inline-Befehl genügt.
Bei Inline-Python (python -c "...") immer korrekt formatierten Code verwenden – Semikolons zur Trennung von Anweisungen und lesbar halten. Bei mehr als ~3 Anweisungen stattdessen einen Heredoc verwenden:
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 ähnlich sagt:
1. SDK installieren
pip install "videodb[capture]" python-dotenv
Falls videodb[capture] unter Linux fehlschlägt, ohne das capture-Extra installieren:
pip install videodb python-dotenv
2. API-Key konfigurieren
Der Benutzer muss VIDEO_DB_API_KEY mit einer dieser Methoden setzen:
- Im Terminal exportieren (vor dem Start von Claude):
export VIDEO_DB_API_KEY=ihr-key - Projekt-
.env-Datei:VIDEO_DB_API_KEY=ihr-keyin der.env-Datei des Projekts speichern
Einen kostenlosen API-Key unter console.videodb.io holen (50 kostenlose Uploads, keine Kreditkarte).
Den API-Key NICHT selbst lesen, schreiben oder verarbeiten. Immer den Benutzer einstellen lassen.
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="/pfad/zu/video.mp4")
Transkript + Untertitel
# force=True überspringt den Fehler, wenn 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 packen und „No results found“ als leeres Ergebnis behandeln.
try:
results = video.search("Produktdemo")
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. Die vorhandene Index-ID aus dem Fehler extrahieren.
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
# score_threshold verwenden, um Rauschen mit niedriger Relevanz zu filtern (empfohlen: 0,3+)
try:
results = video.search(
query="Person, die auf ein 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
Timeline-Bearbeitung
Wichtig: Vor dem Erstellen einer Timeline immer Zeitstempel validieren:
startmuss >= 0 sein (negative Werte werden still akzeptiert, erzeugen aber fehlerhafte Ausgabe)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="Ende", duration=3, style=TextStyle(fontsize=36)))
stream_url = timeline.generate_stream()
Video transkodieren (Auflösung/Qualität ändern)
from videodb import TranscodeMode, VideoConfig, AudioConfig
# Auflösung, Qualität oder Seitenverhältnis serverseitig ändern
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 ändern (für soziale Plattformen)
Warnung: reframe() ist eine langsame serverseitige Operation. Bei langen Videos kann es
mehrere Minuten dauern und ein Timeout verursachen. Best Practices:
- Wenn möglich, immer auf ein kurzes Segment mit
start/endbeschränken - Bei vollständigen Videos
callback_urlfür asynchrone Verarbeitung verwenden - Video zuerst auf einer
Timelinezuschneiden, dann das kürzere Ergebnis reframen
from videodb import ReframeMode
# Immer ein kurzes Segment reframen:
reframed = video.reframe(start=0, end=60, target="vertical", mode=ReframeMode.smart)
# Asynchrones Reframe für vollständige Videos (gibt None zurück, Ergebnis via 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üfen Sie Ihren 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 | video.index_spoken_words(force=True) verwenden, um zu überspringen |
| Szenenindex existiert bereits | Scene index with id XXXX already exists | Vorhandene scene_index_id aus dem Fehler extrahieren mit re.search(r"id\s+([a-f0-9]+)", str(e)) |
| Suche findet keine Treffer | InvalidRequestError: No results found | Exception abfangen und als leeres Ergebnis behandeln (shots = []) |
| Reframe-Zeitüberschreitung | Blockiert bei langen Videos unbegrenzt | Segment mit start/end eingrenzen oder callback_url für asynchrone Verarbeitung |
| Negative Zeitstempel auf Timeline | Erzeugt stillschweigend defekten Stream | Vor Erstellung von VideoAsset immer start >= 0 validieren |
generate_video() / create_collection() schlägt fehl | Operation not allowed oder maximum limit | Planabhängige Funktionen – Benutzer über Planlimits informieren |
Beispiele
Kanonische Aufforderungen
- „Desktop-Aufzeichnung starten und warnen, wenn ein Passwortfeld erscheint.“
- „Meine Sitzung aufzeichnen und eine umsetzbare Zusammenfassung erstellen, wenn sie endet.“
- „Diese Datei importieren und einen abspielbaren Stream-Link zurückgeben.“
- „Diesen Ordner indizieren und jede Szene mit Personen finden, Zeitstempel zurückgeben.“
- „Untertitel generieren, einbrennen und leichte Hintergrundmusik hinzufügen.“
- „Diese RTSP-URL verbinden und warnen, wenn eine Person den Bereich betritt.“
Bildschirmaufnahme (Desktop-Aufzeichnung)
Verwenden Sie ws_listener.py, um WebSocket-Ereignisse während Aufzeichnungssitzungen zu erfassen. Desktop-Aufzeichnung wird nur unter macOS unterstützt.
Schnellstart
- State-Verzeichnis wählen:
STATE_DIR="${VIDEODB_EVENTS_DIR:-$HOME/.local/state/videodb}" - Listener starten:
VIDEODB_EVENTS_DIR="$STATE_DIR" python scripts/ws_listener.py --clear "$STATE_DIR" & - WebSocket-ID holen:
cat "$STATE_DIR/videodb_ws_id" - Capture-Code ausführen (vollständiger Workflow in reference/capture.md)
- Ereignisse geschrieben nach:
$STATE_DIR/videodb_events.jsonl
Verwenden Sie --clear immer beim Start einer neuen Aufzeichnungssitzung, damit veraltete Transkript- und Visuell-Ereignisse nicht in die neue Sitzung gelangen.
Ereignisse abfragen
import json
import os
import time
from pathlib import Path
events_dir = Path(os.environ.get("VIDEODB_EVENTS_DIR", Path.home() / ".local" / "state" / "videodb"))
events_file = events_dir / "videodb_events.jsonl"
events = []
if events_file.exists():
with events_file.open(encoding="utf-8") as handle:
for line in handle:
try:
events.append(json.loads(line))
except json.JSONDecodeError:
continue
transcripts = [e["data"]["text"] for e in events if e.get("channel") == "transcript"]
cutoff = time.time() - 300
recent_visual = [
e for e in events
if e.get("channel") == "visual_index" and e["unix_ts"] > cutoff
]
Zusätzliche Dokumentation
Die Referenzdokumentation befindet sich im Verzeichnis reference/ neben dieser SKILL.md-Datei. Bei Bedarf das Glob-Tool verwenden, um sie zu finden.
- reference/api-reference.md - Vollständige VideoDB Python SDK API-Referenz
- reference/search.md - Ausführlicher Leitfaden zur Videosuche (gesprochenes Wort und szenenbasiert)
- reference/editor.md - Timeline-Bearbeitung, 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-Import-Workflow (RTSP/RTMP)
- reference/rtstream-reference.md - RTStream SDK-Methoden und KI-Pipelines
- reference/capture.md - Desktop-Aufzeichnungs-Workflow
- reference/capture-reference.md - Capture SDK und WebSocket-Ereignisse
- reference/use-cases.md - Häufige Videoverarbeitungsmuster und Beispiele
ffmpeg, moviepy oder lokale Codierungswerkzeuge NICHT verwenden, wenn VideoDB die Operation unterstützt. Folgendes wird alles serverseitig von VideoDB erledigt: Trimmen, Kombinieren von Clips, Überlagern von Audio oder Musik, Hinzufügen von Untertiteln, Text-/Bild-Overlays, Transkodierung, Auflösungsänderungen, Seitenverhältnisumwandlungen, Größenänderung für Plattformanforderungen, Transkription und Mediengenerierung. Lokale Tools nur für Operationen verwenden, die unter „Einschränkungen“ in reference/editor.md aufgeführt sind (Übergänge, Geschwindigkeitsänderungen, Zuschneiden/Zoom, Farbkorrektur, Lautstärkemischung).
Was wann verwenden
| Problem | VideoDB-Lösung |
|---|---|
| Plattform lehnt Video-Seitenverhältnis oder Auflösung ab | video.reframe() oder conn.transcode() mit VideoConfig |
| Video für Twitter/Instagram/TikTok skalieren | video.reframe(target="vertical") oder target="square" |
| Auflösung ändern (z. B. 1080p → 720p) | conn.transcode() mit VideoConfig(resolution=720) |
| Audio/Musik auf 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() |
Herkunft
Referenzmaterial für dieses Skill befindet sich lokal unter skills/videodb/reference/.
Die lokalen Kopien oben verwenden, anstatt zur Laufzeit externe Repository-Links zu folgen.