Communitygithub.com

VideoDB Skill – Ver, Comprender y Actuar sobre Video y Audio

Permite ver (ingesta desde archivos locales, URLs, transmisiones RTSP/en vivo o grabación de escritorio), comprender (extraer fotogramas, construir índices visuales/semánticos/temporales y buscar momentos con marcas de tiempo y fragmentos automáticos) y actuar (transcodificar, normalizar, editar líneas de tiempo, generar subtítulos, superposiciones, audio, video y alertas en tiempo real).

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

VideoDB Skill proporciona una capa de inteligencia artificial para procesamiento completo de video y audio. Su funcionalidad principal se divide en tres ejes: **Ver** – ingiere contenido desde archivos locales, URLs públicas, transmisiones RTSP/en vivo o captura de escritorio, y retorna contexto en tiempo real junto con enlaces de transmisión reproducibles. **Comprender** – indexa habla (transcripción), escenas (búsqueda semántica y visual) y palabras clave, permitiendo búsqueda exacta de momentos con marcas de tiempo y enlaces de evidencia, además de crear fragmentos automáticos. **Actuar** – transcodifica y normaliza video (códec, fps, resolución, relación de aspecto), edita líneas de tiempo (subtítulos, superposiciones de texto/imagen/marca de agua, audio, doblaje, traducción), genera activos multimedia (imagen, audio, video) y emite alertas en tiempo real para eventos en transmisiones en vivo o captura de escritorio. Es compatible con plataformas como Claude Code, Cursor y Codex, y se integra mediante el SDK de Python `videodb`. La configuración requiere una clave API gratuita de console.videodb.io, que se carga desde variables de entorno o archivo `.env`. Para operaciones de edición y generación, VideoDB maneja todo del lado del servidor, evitando el uso de herramientas locales como ffmpeg. Los casos de uso incluyen grabación de escritorio con alertas, búsqueda semántica en videos, generación de subtítulos y doblaje, y monitoreo de transmisiones en vivo con eventos personalizados.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/503496348-ops/mischief-production/tree/HEAD/skills/ecc-videodb

Preguntar en tu IA favorita

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

Documentación

Skill de 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 capturando pantalla, micrófono y audio del sistema
  • Transmitir contexto en vivo y almacenar memoria episódica de la sesión
  • Ejecutar alertas/activaciones 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 de video + transmisión

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

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

  • Construir índices visual, hablado y de palabras clave
  • Buscar y devolver momentos exactos con marcas de tiempo y evidencia reproducible
  • Crear automáticamente fragmentos a partir de los resultados de búsqueda

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

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

Transmisiones en vivo (RTSP) + monitoreo

  • Conectar transmisiones en vivo/RTSP
  • Ejecutar comprensión visual y hablada 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 índice, consulta de búsqueda, rangos de fragmentos, 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, fragmentos
  • Cargas 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. Entorno (si ya está exportado)
  2. Archivo .env del proyecto en el directorio actual

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

NO escriba un archivo de script cuando un comando en línea corto funcione.

Al escribir Python en línea (python -c "..."), use siempre código formateado correctamente — use puntos y comas para separar instrucciones y manténgalo legible. Para algo más de ~3 instrucciones, 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 establecer VIDEO_DB_API_KEY usando cualquier método:

  • Exportar en 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 cargas gratuitas, sin tarjeta de crédito).

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

Referencia rápida

Cargar 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="/ruta/al/video.mp4")

Transcripción + subtítulos

# 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()

Búsqueda dentro de videos

from videodb.exceptions import InvalidRequestError

video.index_spoken_words(force=True)

# search() lanza InvalidRequestError cuando no se encuentran resultados.
# Siempre envuélvalo 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 de escenas

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

# index_scenes() no tiene parámetro force — lanza un error si ya existe un
# índice de escena. 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 en 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 silenciosamente pero producen salida dañada)
  • 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),
)

Reencuadrar relación de aspecto (para redes sociales)

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

  • Siempre limite a un segmento corto usando start/end cuando sea posible
  • Para videos de longitud completa, use callback_url para procesamiento asíncrono
  • Primero recorte el video en una Timeline, luego reencuadre el resultado más corto
from videodb import ReframeMode

# Siempre prefiera reencuadrar un segmento corto:
reframed = video.reframe(start=0, end=60, target="vertical", mode=ReframeMode.smart)

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

# Valores predefinidos: "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="un atardecer sobre las 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"Carga fallida: {e}")

Problemas 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
El índice de escena 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))
La búsqueda no encuentra coincidenciasInvalidRequestError: No results foundCapture la excepción y trate como resultados vacíos (shots = [])
Reencuadre agota tiempo de esperaBloquea indefinidamente en videos largosUse start/end para limitar el segmento, o pase callback_url para asíncrono
Marcas de tiempo negativas en línea de tiempoProduce silenciosamente una transmisión dañadaSiempre valide start >= 0 antes de crear VideoAsset
generate_video() / create_collection() fallaOperation not allowed o maximum limitCaracterísticas limitadas por plan — informe al usuario sobre los límites del plan

Ejemplos

Indicaciones canónicas

  • "Iniciar captura de escritorio y alertar cuando aparezca un campo de contraseña."
  • "Grabar mi sesión y producir un resumen accionable cuando termine."
  • "Ingerir este archivo y devolver un enlace de transmisión reproducible."
  • "Indexar esta carpeta y encontrar cada escena con personas, devolver marcas de tiempo."
  • "Generar subtítulos, incrustarlos y agregar música de fondo ligera."
  • "Conectar esta URL RTSP y alertar cuando una persona entre en la zona."

Grabación de pantalla (Captura de escritorio)

Use ws_listener.py para capturar eventos WebSocket durante las 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 el ID de WebSocket: cat "$STATE_DIR/videodb_ws_id"
  4. Ejecute el 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 obsoletos no se filtren en 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 local cuando VideoDB soporte la operación. Todo lo siguiente es manejado del lado del servidor por VideoDB: recortar, combinar fragmentos, 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 listadas bajo Limitaciones en reference/editor.md (transiciones, cambios de velocidad, recorte/zoom, corrección de color, mezcla de volumen).

Cuándo usar qué

ProblemaSolución de 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 la 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 fragmentosVideoAsset en una Timeline
Necesita generar narración, música o efectos de sonidocoll.generate_voice(), generate_music(), generate_sound_effect()

Procedencia

El material de referencia para esta skill se encuentra localmente bajo 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 7 individual skills — each has its own dedicated page.

503496348-ops/mischief-production

Use this skill when inspecting Blender characters, rigs, poses, animation retargeting, ground contact, facing direction, or model-vs-motion alignment where screenshots alone are not enough.

503496348-ops/mischief-production

Build reusable Manim explainers for technical concepts, graphs, system diagrams, and product walkthroughs, then hand off to the wider HCP video stack if needed. Use when the user wants a clean animated explainer rather than a generic talking-head script.

503496348-ops/mischief-production

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.

503496348-ops/mischief-production

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.

503496348-ops/mischief-production

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.

503496348-ops/mischief-production

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

503496348-ops/mischief-production

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

Skills relacionados