theus-cli 0.2.83 → 0.2.85

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

@@ -1,374 +0,0 @@
----
-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.