Communitygithub.com

VideoDB: Ver, Comprender y Actuar sobre Video y Audio

Permite ingerir, indexar, buscar, editar y generar contenido de video y audio desde archivos locales, URLs, fuentes RTSP/en vivo o captura de escritorio; devuelve contexto en tiempo real, enlaces de transmisión reproducibles y alertas.

¿Qué es VideoDB: Ver, Comprender y Actuar sobre Video y Audio?

Esta habilidad otorga a agentes de IA (como Claude Code, Cursor o Codex) capacidades completas de percepción, memoria y acción sobre video y audio. El agente puede ingerir medios desde archivos locales, URLs, transmisiones RTSP/en vivo o captura de escritorio (macOS) y devolver enlaces de transmisión web reproducibles. También puede indexar visual, semántica y temporalmente el contenido para buscar momentos exactos con marcas de tiempo, clips automáticos y transcripciones. Además, permite transcodificar y normalizar (códec, FPS, resolución, relación de aspecto), editar líneas de tiempo (subtítulos, superposiciones de texto/imagen/marca, superposiciones de audio, doblaje, traducción), generar activos multimedia (imagen, audio, video) y crear alertas en tiempo real para eventos en transmisiones en vivo o captura de escritorio. Toda la funcionalidad se maneja del lado del servidor a través del SDK de Python de VideoDB, por lo que no se debe recurrir a herramientas locales como ffmpeg a menos que sea explícitamente necesario. La habilidad incluye manejo de errores detallado y ejemplos de código para casos de uso comunes.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Cody-W-Tucker/skills/tree/HEAD/skills/videodb

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Habilidad VideoDB

Percepción + memoria + acciones para video, transmisiones en vivo y sesiones de escritorio.

Cuándo usarlo

Percepción de escritorio

  • Iniciar/detener una sesión de escritorio que captura pantalla, micrófono y audio del sistema
  • Transmitir contexto en vivo y almacenar memoria de sesión episódica
  • Ejecutar alertas/desencadenadores en tiempo real sobre lo que se dice y lo que sucede en pantalla
  • Producir resúmenes de sesión, una línea de tiempo buscable y enlaces de evidencia reproducibles

Ingesta y transmisión de video

  • Ingerir un archivo o URL y devolver un enlace de transmisión web reproducible
  • Transcodificar/normalizar: códec, bitrate, FPS, resolución, relación de aspecto

Indexación y búsqueda (marcas de tiempo + evidencia)

  • Construir índices visuales, de voz y de palabras clave
  • Buscar y devolver momentos exactos con marcas de tiempo y evidencia reproducible
  • Crear clips automáticos a partir de resultados de búsqueda

Edición y generación de línea de tiempo

  • Subtítulos: generar, traducir, incrustar
  • Superposiciones: texto/imagen/marca, subtítulos animados
  • Audio: música de fondo, locución, doblaje
  • Composición programática y exportaciones mediante operaciones de línea de tiempo

Transmisiones en vivo (RTSP) y monitoreo

  • Conectar fuentes RTSP/en vivo
  • Ejecutar comprensión visual y de voz en tiempo real y emitir eventos/alertas para flujos de monitoreo

Cómo funciona

Entradas comunes

  • Ruta de archivo local, URL pública o URL RTSP
  • Solicitud de captura de escritorio: iniciar / detener / resumir sesión
  • Operaciones deseadas: obtener contexto para comprensión, especificación de transcodificación, especificación de indexación, consulta de búsqueda, rangos de clip, ediciones de línea de tiempo, reglas de alerta

Salidas comunes

  • URL de transmisión
  • Resultados de búsqueda con marcas de tiempo y enlaces de evidencia
  • Activos generados: subtítulos, audio, imágenes, clips
  • Cargas útiles de eventos/alertas para transmisiones en vivo
  • Resúmenes de sesión de escritorio y entradas de memoria

Ejecutar código Python

Antes de ejecutar cualquier código de VideoDB, cambie al directorio del proyecto y cargue las variables de entorno:

from dotenv import load_dotenv
load_dotenv(".env")

import videodb
conn = videodb.connect()

Esto lee VIDEO_DB_API_KEY de:

  1. Variables de entorno (si ya se exportó)
  2. Archivo .env del proyecto en el directorio actual

Si la clave falta, videodb.connect() genera automáticamente AuthenticationError.

NO escriba un archivo de script cuando un comando inline corto sea suficiente.

Al escribir Python inline (python -c "..."), use siempre código con formato adecuado — use puntos y coma para separar declaraciones y manténgalo legible. Para cualquier cosa de más de ~3 declaraciones, use un heredoc en su lugar:

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

Configuración

Cuando el usuario pida "configurar videodb" o similar:

1. Instalar SDK

pip install "videodb[capture]" python-dotenv

Si videodb[capture] falla en Linux, instale sin el extra de captura:

pip install videodb python-dotenv

2. Configurar clave API

El usuario debe configurar VIDEO_DB_API_KEY usando cualquier método:

  • Exportar en la terminal (antes de iniciar Claude): export VIDEO_DB_API_KEY=su-clave
  • Archivo .env del proyecto: Guarde VIDEO_DB_API_KEY=su-clave en el archivo .env del proyecto

Obtenga una clave API gratuita en console.videodb.io (50 subidas gratuitas, sin tarjeta de crédito).

NO lea, escriba o maneje la clave API usted mismo. Deje siempre que el usuario la configure.

Referencia rápida

Subir medios

# URL
video = coll.upload(url="https://example.com/video.mp4")

# YouTube
video = coll.upload(url="https://www.youtube.com/watch?v=VIDEO_ID")

# Archivo local
video = coll.upload(file_path="/path/to/video.mp4")

Transcripción + subtítulo

# force=True omite el error si el video ya está indexado
video.index_spoken_words(force=True)
text = video.get_transcript_text()
stream_url = video.add_subtitle()

Buscar dentro de videos

from videodb.exceptions import InvalidRequestError

video.index_spoken_words(force=True)

# search() genera InvalidRequestError cuando no encuentra resultados.
# Envuélvalo siempre en try/except y trate "No results found" como vacío.
try:
    results = video.search("demostración de producto")
    shots = results.get_shots()
    stream_url = results.compile()
except InvalidRequestError as e:
    if "No results found" in str(e):
        shots = []
    else:
        raise

Búsqueda por escenas

import re
from videodb import SearchType, IndexType, SceneExtractionType
from videodb.exceptions import InvalidRequestError

# index_scenes() no tiene parámetro force — genera un error si ya existe un
# índice de escenas. Extraiga el ID del índice existente del error.
try:
    scene_index_id = video.index_scenes(
        extraction_type=SceneExtractionType.shot_based,
        prompt="Describe el contenido visual de esta escena.",
    )
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

# Use score_threshold para filtrar ruido de baja relevancia (recomendado: 0.3+)
try:
    results = video.search(
        query="persona escribiendo en una pizarra",
        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

Edición de línea de tiempo

Importante: Siempre valide las marcas de tiempo antes de construir una línea de tiempo:

  • start debe ser >= 0 (los valores negativos se aceptan en silencio pero producen salida corrupta)
  • start debe ser < end
  • end debe ser <= video.length
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()

Transcodificar video (cambio de resolución/calidad)

from videodb import TranscodeMode, VideoConfig, AudioConfig

# Cambiar resolución, calidad o relación de aspecto del lado del servidor
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),
)

Cambiar relación de aspecto (para plataformas sociales)

Advertencia: reframe() es una operación lenta del lado del servidor. Para videos largos puede tardar varios minutos y puede agotar el tiempo de espera. Mejores prácticas:

  • Siempre limite a un segmento corto usando start/end cuando sea posible
  • Para videos de duración completa, use callback_url para procesamiento asíncrono
  • Recorte el video en una Timeline primero, luego cambie la relación de aspecto del resultado más corto
from videodb import ReframeMode

# Siempre prefiera cambiar la relación de aspecto de un segmento corto:
reframed = video.reframe(start=0, end=60, target="vertical", mode=ReframeMode.smart)

# Cambio asíncrono para videos completos (devuelve None, resultado vía webhook):
video.reframe(target="vertical", callback_url="https://example.com/webhook")

# Preajustes: "vertical" (9:16), "square" (1:1), "landscape" (16:9)
reframed = video.reframe(start=0, end=60, target="square")

# Dimensiones personalizadas
reframed = video.reframe(start=0, end=60, target={"width": 1280, "height": 720})

Medios generativos

image = coll.generate_image(
    prompt="una puesta de sol sobre montañas",
    aspect_ratio="16:9",
)

Manejo de errores

from videodb.exceptions import AuthenticationError, InvalidRequestError

try:
    conn = videodb.connect()
except AuthenticationError:
    print("Verifique su VIDEO_DB_API_KEY")

try:
    video = coll.upload(url="https://example.com/video.mp4")
except InvalidRequestError as e:
    print(f"Error de subida: {e}")

Errores comunes

EscenarioMensaje de errorSolución
Indexar un video ya indexadoSpoken word index for video already existsUse video.index_spoken_words(force=True) para omitir si ya está indexado
Índice de escenas ya existeScene index with id XXXX already existsExtraiga el scene_index_id existente del error con re.search(r"id\s+([a-f0-9]+)", str(e))
Búsqueda sin coincidenciasInvalidRequestError: No results foundCapture la excepción y trate como resultados vacíos (shots = [])
Cambio de aspecto agota tiempo de esperaBloquea indefinidamente en videos largosUse start/end para limitar segmento, o pase callback_url para async
Marcas de tiempo negativas en TimelineProduce silenciosamente transmisión corruptaSiempre valide start >= 0 antes de crear VideoAsset
generate_video() / create_collection() fallaOperation not allowed o maximum limitFunciones limitadas por plan — informe al usuario sobre límites del plan

Ejemplos

Indicaciones canónicas

  • "Inicia captura de escritorio y alerta cuando aparezca un campo de contraseña."
  • "Graba mi sesión y produce un resumen procesable cuando termine."
  • "Ingiere este archivo y devuelve un enlace de transmisión reproducible."
  • "Indexa esta carpeta y encuentra cada escena con personas, devuelve marcas de tiempo."
  • "Genera subtítulos, incrústalos y agrega música de fondo suave."
  • "Conecta esta URL RTSP y alerta cuando una persona entre en la zona."

Grabación de pantalla (captura de escritorio)

Use ws_listener.py para capturar eventos WebSocket durante sesiones de grabación. La captura de escritorio solo es compatible con macOS.

Inicio rápido

  1. Elija directorio de estado: STATE_DIR="${VIDEODB_EVENTS_DIR:-$HOME/.local/state/videodb}"
  2. Inicie el listener: VIDEODB_EVENTS_DIR="$STATE_DIR" python scripts/ws_listener.py --clear "$STATE_DIR" &
  3. Obtenga ID WebSocket: cat "$STATE_DIR/videodb_ws_id"
  4. Ejecute código de captura (consulte reference/capture.md para el flujo completo)
  5. Eventos escritos en: $STATE_DIR/videodb_events.jsonl

Use --clear cada vez que inicie una ejecución de captura nueva para que eventos de transcripción y visuales antiguos no se filtren a la nueva sesión.

Consultar eventos

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
]

Documentación adicional

La documentación de referencia está en el directorio reference/ adyacente a este archivo SKILL.md. Use la herramienta Glob para localizarla si es necesario.

No use ffmpeg, moviepy o herramientas de codificación locales cuando VideoDB admita la operación. Todo lo siguiente se maneja del lado del servidor por VideoDB: recortar, combinar clips, superponer audio o música, agregar subtítulos, superposiciones de texto/imagen, transcodificación, cambios de resolución, conversión de relación de aspecto, redimensionamiento para requisitos de plataforma, transcripción y generación de medios. Solo recurra a herramientas locales para operaciones enumeradas en Limitaciones en reference/editor.md (transiciones, cambios de velocidad, recorte/zoom, corrección de color, mezcla de volumen).

Cuándo usar qué

ProblemaSolución VideoDB
La plataforma rechaza la relación de aspecto o resolución del videovideo.reframe() o conn.transcode() con VideoConfig
Necesita redimensionar video para Twitter/Instagram/TikTokvideo.reframe(target="vertical") o target="square"
Necesita cambiar resolución (ej. 1080p → 720p)conn.transcode() con VideoConfig(resolution=720)
Necesita superponer audio/música en videoAudioAsset en una Timeline
Necesita agregar subtítulosvideo.add_subtitle() o CaptionAsset
Necesita combinar/recortar clipsVideoAsset en una Timeline
Necesita generar locución, música o efectos de sonidocoll.generate_voice(), generate_music(), generate_sound_effect()

Procedencia

El material de referencia para esta habilidad está disponible localmente en skills/videodb/reference/. Use las copias locales anteriores en lugar de seguir enlaces de repositorios externos en tiempo de ejecución.

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

Cody-W-Tucker/skills

Advanced motion patterns for React / Next.js — drag & drop, gestures, text animations, SVG path drawing, custom hooks, imperative sequences (useAnimate), loaders, and the full API decision tree. Requires motion-foundations.

Cody-W-Tucker/skills

Process video files with ffmpeg automation. Use when: compressing videos for upload; extracting audio from video; resizing for social formats; clipping segments; merging multiple videos; generating thumbnails

Cody-W-Tucker/skills

Best practices for Remotion - Video creation in React. 29 domain-specific rules covering 3D, animations, audio, captions, charts, transitions, and more.

Cody-W-Tucker/skills

A single-frame motion-design composition with looping CSS animations — rotating type ring, animated globe, ticking timer, parallax labels. Renders as a hero video poster you can hand straight to HyperFrames or any keyframe-based exporter. Use when the brief asks for "motion design", "animated hero", "loop", "video poster", "title card", or pairs Open Claude Design with HyperFrames for a kinetic export.

Cody-W-Tucker/skills

Swiss-style user-research narrative template in warm-paper editorial aesthetics. Use when users ask for a premium research deck or story-first live artifact with minimalist typography, high-clarity layout, subtle motion, donut breakdowns, and keyboard/click navigation across slides in a single HTML file.

Cody-W-Tucker/skills

Master April Dunford's 8-step sales narrative from \"Sales Pitch\" (2023). Transform your positioning into a compelling story that wins enterprise deals. Use when: Structuring B2B sales presentations and demos; Creating pitch decks for complex products; Training sales teams on narrative-driven selling; Converting positioning strategy into sales conversations; Winning against entrenched competitors

Cody-W-Tucker/skills

Draft and refine prompts for video generation models (text-to-video and image-to-video), and create character-sheet prompts for image models when the goal is character consistency before image-to-video. Use when a user asks for a "video prompt", a model-specific prompt such as Seedance 2.0, Ovi, Sora, Veo 3, Wan 2.2, LTX-2, or LTX-2.3, or a consistent-character prompt such as "character sheet prompt", "character turnaround", "character reference sheet", or "photographic identity sheet".

Cody-W-Tucker/skills

Short-form video generation skill — 3-10 second clips for product reveals, motion teasers, ambient loops. Defaults to Seedance 2 but works the same with Kling 3 / 4, Veo 3 or Sora 2. Output is one MP4 saved to the project folder. When the workspace also ships an interactive-video / hyperframes skill, prefer composing several short shots into a single timeline rather than one long monolithic clip.

Cody-W-Tucker/skills

AI-assisted video editing workflows for cutting, structuring, and augmenting real footage. Covers the full pipeline from raw capture through FFmpeg, Remotion, ElevenLabs, fal.ai, and final polish in Descript or CapCut. Use when the user wants to edit video, cut footage, create vlogs, or build video content.

Cody-W-Tucker/skills

Production-ready UI motion system for React/Next.js. Use when implementing animations, transitions, or motion patterns.

Cody-W-Tucker/skills

When the user wants to create developer YouTube content, technical screencasts, or video tutorials. Trigger phrases include "YouTube," "developer video," "screencast," "video tutorial," "live coding," "YouTube for developers," "tech YouTube," or "YouTube thumbnails.

Cody-W-Tucker/skills

Scale your brand voice across multiple languages using AI voice synthesis, maintaining consistent character and quality for global content. Use when: Expanding video content to new language markets; Creating multilingual courses or training; Localizing ads and marketing videos; Dubbing existing content for international audiences; Building consistent global brand voice

Cody-W-Tucker/skills

YouTube Ads specific analysis covering campaign types, creative quality, audience targeting, and measurement. Evaluates video ad performance across skippable, non-skippable, bumper, Shorts, Demand Gen, and Connected TV formats. Covers VAC→Demand Gen migration, Shorts creative requirements, and CTV shoppable ads. Use when user says YouTube Ads, video ads, pre-roll, bumper ads, YouTube campaign, Shorts ads, or CTV ads.

Cody-W-Tucker/skills

Motion tokens, spring presets, performance rules, device adaptation, accessibility enforcement, and SSR safety for React / Next.js using motion/react. Foundation layer — all other motion skills depend on this.

Cody-W-Tucker/skills

Identify the best GTM motions and tools across 7 motion types: Inbound, Outbound, Paid Digital, Community, Partners, ABM, and PLG. Use when selecting marketing channels, choosing between inbound and outbound strategy, or planning cross-channel campaigns.

Cody-W-Tucker/skills

TikTok Ads deep analysis covering creative quality, tracking, bidding, campaign structure, and TikTok Shop. Evaluates 28 checks with emphasis on creative-first strategy, safe zone compliance, and Smart+ campaigns. Use when user says TikTok Ads, TikTok marketing, TikTok Shop, Spark Ads, Smart+, or TikTok campaign.

Cody-W-Tucker/skills

Craft the story that makes investors say \"I want in.\" Master the narrative structure that Reid Hoffman, Sequoia, and top founders use to raise capital. Use when: **Preparing to fundraise** to develop your story before the deck; **Investor meetings** to structure conversations that convert; **Pitch practice** to refine your narrative arc; **Cold outreach** to write compelling investor emails; **Pivoting** to reframe your story after a change

Cody-W-Tucker/skills

Production-ready animation patterns for React / Next.js — button, modal, toast, stagger, page transitions, exit animations, scroll, and layout — built on motion-foundations tokens and springs.

Cody-W-Tucker/skills

Download YouTube videos with customizable quality and format options. Use this skill when the user asks to download, save, or grab YouTube videos. Supports various quality settings (best, 1080p, 720p, 480p, 360p), multiple formats (mp4, webm, mkv), and audio-only downloads as MP3.

Cody-W-Tucker/skills

Capture authentic customer testimonials through guided self-recording workflows, from outreach and briefing to recording and publishing. Use when: Building social proof for marketing campaigns; Creating customer success stories; Gathering testimonials for website and ads; Producing case study videos; Collecting user-generated content

Skills relacionados