theus-cli-linux-x64 0.2.84

package/vendor/theus-arsenal/skills/videodb/SKILL.md

@@ -0,0 +1,374 @@
+---
+name: videodb
+description: Ver, entender y actuar sobre video y audio con VideoDB. Ver- ingesta desde archivos locales, URLs, feeds RTSP/en vivo o grabación de escritorio; devuelve contexto en tiempo real y enlaces de stream reproducibles. Entender- extrae frames, construye índices visuales/semánticos/temporales y busca momentos con marcas de tiempo y clips automáticos. Actuar- transcodifica y normaliza (códec, fps, resolución, relación de aspecto), edita en línea de tiempo (subtítulos, superposiciones de texto/imagen, branding, pistas de audio, doblaje, traducción), genera medios (imagen, audio, video) y crea alertas en tiempo real sobre streams en vivo o captura de escritorio.
+allowed-tools: Read, Grep, Glob, Bash(python:*)
+---
+
+# Skill de VideoDB
+
+**Percepción + memoria + acciones para video, streams en vivo y sesiones de escritorio.**
+
+> **Requisito:** esta skill es un integrador del servicio externo **VideoDB** ([videodb.io](https://videodb.io)). Necesitas una cuenta propia y tu propia API key (`VIDEO_DB_API_KEY`) de ese servicio. VideoDB **no forma parte de la suscripción de Theus** y su consumo se factura aparte según los planes de VideoDB.
+
+## Cuándo usarla
+
+### 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/disparadores en tiempo real** sobre lo que se dice y lo que ocurre en pantalla
+- Producir **resúmenes de sesión**, una línea de tiempo buscable y **enlaces de evidencia reproducibles**
+
+### Ingesta de video + streaming
+- Ingerir un **archivo o URL** y devolver un **enlace de stream web reproducible**
+- Transcodificar/normalizar: **códec, bitrate, fps, resolución, relación de aspecto**
+
+### Índice + búsqueda (marcas de tiempo + evidencia)
+- Construir índices **visuales**, **de palabra hablada** y **de palabras clave**
+- Buscar y devolver momentos exactos con **marcas de tiempo** y **evidencia reproducible**
+- Crear **clips** automáticamente a partir de los resultados de búsqueda
+
+### Edición en línea de tiempo + generación
+- Subtítulos: **generar**, **traducir**, **incrustar (burn-in)**
+- Superposiciones: **texto/imagen/branding**, captions con movimiento
+- Audio: **música de fondo**, **locución (voiceover)**, **doblaje**
+- Composición programática y exportaciones mediante **operaciones de línea de tiempo**
+
+### Streams en vivo (RTSP) + monitoreo
+- Conectar **feeds RTSP/en vivo**
+- 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, spec de transcodificación, spec de índice, consulta de búsqueda, rangos de clips, ediciones de línea de tiempo, reglas de alerta
+
+### Salidas comunes
+- **URL de stream**
+- Resultados de búsqueda con **marcas de tiempo** y **enlaces de evidencia**
+- Recursos generados: subtítulos, audio, imágenes, clips
+- **Payloads de eventos/alertas** para streams 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, cámbiate al directorio del proyecto y carga las variables de entorno:
+
+```python
+from dotenv import load_dotenv
+load_dotenv(".env")
+
+import videodb
+conn = videodb.connect()
+```
+
+Esto lee `VIDEO_DB_API_KEY` desde:
+1. El entorno (si ya está exportada)
+2. El archivo `.env` del proyecto en el directorio actual
+
+Si la key falta, `videodb.connect()` lanza `AuthenticationError` automáticamente.
+
+NO escribas un archivo de script cuando baste un comando corto en línea.
+
+Al escribir Python en línea (`python -c "..."`), usa siempre código bien formateado — separa sentencias con punto y coma y mantenlo legible. Para cualquier cosa mayor a ~3 sentencias, usa un heredoc:
+
+```bash
+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 inicial
+
+Cuando el usuario pida "configurar videodb" o similar:
+
+### 1. Instala el SDK
+
+```bash
+pip install "videodb[capture]" python-dotenv
+```
+
+Si `videodb[capture]` falla en Linux, instala sin el extra de captura:
+
+```bash
+pip install videodb python-dotenv
+```
+
+### 2. Configura la API key
+
+El usuario debe establecer `VIDEO_DB_API_KEY` con **cualquiera** de estos métodos:
+
+- **Exportarla en la terminal** (antes de iniciar el CLI): `export VIDEO_DB_API_KEY=tu-key`
+- **Archivo `.env` del proyecto**: guardar `VIDEO_DB_API_KEY=tu-key` en el `.env` del proyecto
+
+Se puede obtener una API key gratuita en [console.videodb.io](https://console.videodb.io) (50 subidas gratis, sin tarjeta de crédito).
+
+**NO** leas, escribas ni manipules la API key tú mismo. Deja siempre que el usuario la configure.
+
+### Referencia rápida
+
+### Subir medios
+
+```python
+# 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
+
+```python
+# 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
+
+```python
+from videodb.exceptions import InvalidRequestError
+
+video.index_spoken_words(force=True)
+
+# search() lanza InvalidRequestError cuando no hay resultados.
+# Envuélvelo siempre en try/except y trata "No results found" como vacío.
+try:
+    results = video.search("demo del 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
+
+```python
+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 escenas. Extrae el ID del índice existente desde el 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
+
+# Usa 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 en línea de tiempo
+
+**Importante:** valida siempre 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 rota)
+- `start` debe ser < `end`
+- `end` debe ser <= `video.length`
+
+```python
+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="Fin", duration=3, style=TextStyle(fontsize=36)))
+stream_url = timeline.generate_stream()
+```
+
+### Transcodificar video (cambio de resolución / calidad)
+
+```python
+from videodb import TranscodeMode, VideoConfig, AudioConfig
+
+# Cambia resolución, calidad o relación de aspecto en el 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 plataformas sociales)
+
+**Advertencia:** `reframe()` es una operación lenta del lado del servidor. Para videos largos
+puede tardar varios minutos y expirar. Buenas prácticas:
+- Limita siempre a un segmento corto con `start`/`end` cuando sea posible
+- Para videos completos, usa `callback_url` para procesamiento asíncrono
+- Recorta primero el video en una `Timeline` y luego reencuadra el resultado más corto
+
+```python
+from videodb import ReframeMode
+
+# Prefiere siempre reencuadrar un segmento corto:
+reframed = video.reframe(start=0, end=60, target="vertical", mode=ReframeMode.smart)
+
+# Reencuadre asíncrono para videos completos (devuelve None, resultado vía webhook):
+video.reframe(target="vertical", callback_url="https://example.com/webhook")
+
+# Presets: "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
+
+```python
+image = coll.generate_image(
+    prompt="un atardecer sobre montañas",
+    aspect_ratio="16:9",
+)
+```
+
+## Manejo de errores
+
+```python
+from videodb.exceptions import AuthenticationError, InvalidRequestError
+
+try:
+    conn = videodb.connect()
+except AuthenticationError:
+    print("Revisa tu VIDEO_DB_API_KEY")
+
+try:
+    video = coll.upload(url="https://example.com/video.mp4")
+except InvalidRequestError as e:
+    print(f"Falló la subida: {e}")
+```
+
+### Errores comunes
+
+| Escenario | Mensaje de error | Solución |
+|-----------|------------------|----------|
+| Indexar un video ya indexado | `Spoken word index for video already exists` | Usa `video.index_spoken_words(force=True)` para omitir si ya está indexado |
+| El índice de escenas ya existe | `Scene index with id XXXX already exists` | Extrae el `scene_index_id` existente del error con `re.search(r"id\s+([a-f0-9]+)", str(e))` |
+| La búsqueda no encuentra coincidencias | `InvalidRequestError: No results found` | Captura la excepción y trátala como resultados vacíos (`shots = []`) |
+| Reframe expira | Se bloquea indefinidamente en videos largos | Usa `start`/`end` para limitar el segmento, o pasa `callback_url` para modo asíncrono |
+| Marcas de tiempo negativas en Timeline | Produce silenciosamente un stream roto | Valida siempre `start >= 0` antes de crear un `VideoAsset` |
+| Falla `generate_video()` / `create_collection()` | `Operation not allowed` o `maximum limit` | Funciones limitadas por plan de VideoDB — informa al usuario sobre los límites de su plan |
+
+## Ejemplos
+
+### Peticiones canónicas
+- "Inicia la captura de escritorio y avísame cuando aparezca un campo de contraseña."
+- "Graba mi sesión y produce un resumen accionable cuando termine."
+- "Ingiere este archivo y devuélveme un enlace de stream reproducible."
+- "Indexa esta carpeta y encuentra cada escena con personas; devuelve marcas de tiempo."
+- "Genera subtítulos, incrústalos y añade música de fondo suave."
+- "Conecta esta URL RTSP y alértame cuando una persona entre a la zona."
+
+### Grabación de pantalla (captura de escritorio)
+
+Usa `ws_listener.py` para capturar los eventos WebSocket durante las sesiones de grabación. La captura de escritorio solo funciona en **macOS**.
+
+#### Inicio rápido
+
+1. **Elige el directorio de estado**: `STATE_DIR="${VIDEODB_EVENTS_DIR:-$HOME/.theus/arsenal/videodb}"`
+2. **Inicia el listener**: `VIDEODB_EVENTS_DIR="$STATE_DIR" python scripts/ws_listener.py --clear "$STATE_DIR" &`
+3. **Obtén el ID del WebSocket**: `cat "$STATE_DIR/videodb_ws_id"`
+4. **Ejecuta el código de captura** (ver reference/capture.md para el flujo completo)
+5. **Los eventos se escriben en**: `$STATE_DIR/videodb_events.jsonl`
+
+Usa `--clear` cada vez que inicies una captura nueva para que los eventos de transcripción y visuales antiguos no se filtren en la nueva sesión.
+
+#### Consultar eventos
+
+```python
+import json
+import os
+import time
+from pathlib import Path
+
+events_dir = Path(os.environ.get("VIDEODB_EVENTS_DIR", Path.home() / ".theus" / "arsenal" / "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/` junto a este SKILL.md. Usa la herramienta Glob para localizarla si hace falta.
+
+- [reference/api-reference.md](reference/api-reference.md) - Referencia completa del SDK de Python de VideoDB
+- [reference/search.md](reference/search.md) - Guía a fondo de búsqueda en video (palabra hablada y escenas)
+- [reference/editor.md](reference/editor.md) - Edición en línea de tiempo, assets y composición
+- [reference/streaming.md](reference/streaming.md) - Streaming HLS y reproducción instantánea
+- [reference/generative.md](reference/generative.md) - Generación de medios con IA (imágenes, video, audio)
+- [reference/rtstream.md](reference/rtstream.md) - Flujo de ingesta de streams en vivo (RTSP/RTMP)
+- [reference/rtstream-reference.md](reference/rtstream-reference.md) - Métodos del SDK de RTStream y pipelines de IA
+- [reference/capture.md](reference/capture.md) - Flujo de captura de escritorio
+- [reference/capture-reference.md](reference/capture-reference.md) - SDK de captura y eventos WebSocket
+- [reference/use-cases.md](reference/use-cases.md) - Patrones y ejemplos comunes de procesamiento de video
+
+**No uses ffmpeg, moviepy ni herramientas de codificación locales** cuando VideoDB soporte la operación. Todo lo siguiente se procesa en los servidores de VideoDB — recorte, combinación de clips, superposición de audio o música, subtítulos, superposiciones de texto/imagen, transcodificación, cambios de resolución, conversión de relación de aspecto, redimensionado para requisitos de plataforma, transcripción y generación de medios. Recurre a herramientas locales solo para las operaciones listadas en Limitaciones de reference/editor.md (transiciones, cambios de velocidad, crop/zoom, gradación de color, mezcla de volumen).
+
+### Qué usar según el problema
+
+| Problema | Solución con VideoDB |
+|----------|----------------------|
+| La plataforma rechaza la relación de aspecto o resolución del video | `video.reframe()` o `conn.transcode()` con `VideoConfig` |
+| Necesitas redimensionar video para X/Instagram/TikTok | `video.reframe(target="vertical")` o `target="square"` |
+| Necesitas cambiar la resolución (p. ej. 1080p → 720p) | `conn.transcode()` con `VideoConfig(resolution=720)` |
+| Necesitas superponer audio/música sobre un video | `AudioAsset` en una `Timeline` |
+| Necesitas añadir subtítulos | `video.add_subtitle()` o `CaptionAsset` |
+| Necesitas combinar/recortar clips | `VideoAsset` en una `Timeline` |
+| Necesitas generar locución, música o efectos de sonido | `coll.generate_voice()`, `generate_music()`, `generate_sound_effect()` |
+
+## Procedencia
+
+El material de referencia de esta skill está vendorizado localmente bajo `skills/videodb/reference/`.
+Usa las copias locales anteriores en lugar de seguir enlaces a repositorios externos en tiempo de ejecución.