theus-cli-linux-x64 0.2.84

package/vendor/theus-arsenal/skills/videodb/reference/capture-reference.md

@@ -0,0 +1,407 @@
+# Referencia de captura
+
+Detalles a nivel de código para las sesiones de captura de VideoDB. Para la guía de flujo, ver [capture.md](capture.md).
+
+---
+
+## Eventos WebSocket
+
+Eventos en tiempo real de las sesiones de captura y los pipelines de IA. Sin webhooks ni sondeo.
+
+Usa [scripts/ws_listener.py](../scripts/ws_listener.py) para conectarte y volcar los eventos en `${VIDEODB_EVENTS_DIR:-$HOME/.theus/arsenal/videodb}/videodb_events.jsonl`.
+
+### Canales de eventos
+
+| Canal | Origen | Contenido |
+|-------|--------|-----------|
+| `capture_session` | Ciclo de vida de la sesión | Cambios de estado |
+| `transcript` | `start_transcript()` | Voz a texto |
+| `visual_index` / `scene_index` | `index_visuals()` | Análisis visual |
+| `audio_index` | `index_audio()` | Análisis de audio |
+| `alert` | `create_alert()` | Notificaciones de alertas |
+
+### Eventos del ciclo de vida de la sesión
+
+| Evento | Estado | Datos clave |
+|--------|--------|-------------|
+| `capture_session.created` | `created` | — |
+| `capture_session.starting` | `starting` | — |
+| `capture_session.active` | `active` | `rtstreams[]` |
+| `capture_session.stopping` | `stopping` | — |
+| `capture_session.stopped` | `stopped` | — |
+| `capture_session.exported` | `exported` | `exported_video_id`, `stream_url`, `player_url` |
+| `capture_session.failed` | `failed` | `error` |
+
+### Estructuras de eventos
+
+**Evento de transcripción:**
+```json
+{
+  "channel": "transcript",
+  "rtstream_id": "rts-xxx",
+  "rtstream_name": "mic:default",
+  "data": {
+    "text": "Agendemos la reunión para el jueves",
+    "is_final": true,
+    "start": 1710000001234,
+    "end": 1710000002345
+  }
+}
+```
+
+**Evento de índice visual:**
+```json
+{
+  "channel": "visual_index",
+  "rtstream_id": "rts-xxx",
+  "rtstream_name": "display:1",
+  "data": {
+    "text": "El usuario está viendo una conversación de Slack con 3 mensajes sin leer",
+    "start": 1710000012340,
+    "end": 1710000018900
+  }
+}
+```
+
+**Evento de índice de audio:**
+```json
+{
+  "channel": "audio_index",
+  "rtstream_id": "rts-xxx",
+  "rtstream_name": "mic:default",
+  "data": {
+    "text": "Discusión sobre agendar una reunión de equipo",
+    "start": 1710000021500,
+    "end": 1710000029200
+  }
+}
+```
+
+**Evento de sesión activa:**
+```json
+{
+  "event": "capture_session.active",
+  "capture_session_id": "cap-xxx",
+  "status": "active",
+  "data": {
+    "rtstreams": [
+      { "rtstream_id": "rts-1", "name": "mic:default", "media_types": ["audio"] },
+      { "rtstream_id": "rts-2", "name": "system_audio:default", "media_types": ["audio"] },
+      { "rtstream_id": "rts-3", "name": "display:1", "media_types": ["video"] }
+    ]
+  }
+}
+```
+
+**Evento de sesión exportada:**
+```json
+{
+  "event": "capture_session.exported",
+  "capture_session_id": "cap-xxx",
+  "status": "exported",
+  "data": {
+    "exported_video_id": "v_xyz789",
+    "stream_url": "https://stream.videodb.io/...",
+    "player_url": "https://console.videodb.io/player?url=..."
+  }
+}
+```
+
+> Para los detalles más recientes, ver la [documentación de Realtime Context de VideoDB](https://docs.videodb.io/pages/ingest/capture-sdks/realtime-context.md).
+
+---
+
+## Persistencia de eventos
+
+Usa `ws_listener.py` para volcar todos los eventos WebSocket a un archivo JSONL para análisis posterior.
+
+### Iniciar el listener y obtener el ID del WebSocket
+
+```bash
+# Inicia con --clear para limpiar los eventos antiguos (recomendado en sesiones nuevas)
+python scripts/ws_listener.py --clear &
+
+# Añade a los eventos existentes (para reconexiones)
+python scripts/ws_listener.py &
+```
+
+O especifica un directorio de salida propio:
+
+```bash
+python scripts/ws_listener.py --clear /ruta/a/salida &
+# O vía variable de entorno:
+VIDEODB_EVENTS_DIR=/ruta/a/salida python scripts/ws_listener.py --clear &
+```
+
+El script imprime `WS_ID=<connection_id>` en la primera línea y luego escucha indefinidamente.
+
+**Obtener el ws_id:**
+```bash
+cat "${VIDEODB_EVENTS_DIR:-$HOME/.theus/arsenal/videodb}/videodb_ws_id"
+```
+
+**Detener el listener:**
+```bash
+kill "$(cat "${VIDEODB_EVENTS_DIR:-$HOME/.theus/arsenal/videodb}/videodb_ws_pid")"
+```
+
+**Funciones que aceptan `ws_connection_id`:**
+
+| Función | Propósito |
+|---------|-----------|
+| `conn.create_capture_session()` | Eventos del ciclo de vida de la sesión |
+| Métodos de RTStream | Ver [rtstream-reference.md](rtstream-reference.md) |
+
+**Archivos de salida** (en el directorio de salida, por defecto `~/.theus/arsenal/videodb`):
+- `videodb_ws_id` - ID de la conexión WebSocket
+- `videodb_events.jsonl` - Todos los eventos
+- `videodb_ws_pid` - PID del proceso para terminarlo fácilmente
+
+**Características:**
+- Flag `--clear` para limpiar el archivo de eventos al iniciar (úsalo en sesiones nuevas)
+- Reconexión automática con backoff exponencial ante caídas de conexión
+- Apagado limpio con SIGINT/SIGTERM
+- Registro del estado de la conexión
+
+### Formato JSONL
+
+Cada línea es un objeto JSON con marcas de tiempo añadidas:
+
+```json
+{"ts": "2026-03-02T10:15:30.123Z", "unix_ts": 1772446530.123, "channel": "visual_index", "data": {"text": "..."}}
+{"ts": "2026-03-02T10:15:31.456Z", "unix_ts": 1772446531.456, "event": "capture_session.active", "capture_session_id": "cap-xxx"}
+```
+
+### Leer eventos
+
+```python
+import json
+import time
+from pathlib import Path
+
+events_path = Path.home() / ".theus" / "arsenal" / "videodb" / "videodb_events.jsonl"
+transcripts = []
+recent = []
+visual = []
+
+cutoff = time.time() - 600
+with events_path.open(encoding="utf-8") as handle:
+    for line in handle:
+        event = json.loads(line)
+        if event.get("channel") == "transcript":
+            transcripts.append(event)
+        if event.get("unix_ts", 0) > cutoff:
+            recent.append(event)
+        if (
+            event.get("channel") == "visual_index"
+            and "code" in event.get("data", {}).get("text", "").lower()
+        ):
+            visual.append(event)
+```
+
+---
+
+## Conexión WebSocket
+
+Conéctate para recibir resultados de IA en tiempo real de los pipelines de transcripción e indexación.
+
+```python
+ws_wrapper = conn.connect_websocket()
+ws = await ws_wrapper.connect()
+ws_id = ws.connection_id
+```
+
+| Propiedad / Método | Tipo | Descripción |
+|--------------------|------|-------------|
+| `ws.connection_id` | `str` | ID único de la conexión (pásalo a los métodos de pipelines de IA) |
+| `ws.receive()` | `AsyncIterator[dict]` | Iterador asíncrono que produce mensajes en tiempo real |
+
+---
+
+## CaptureSession
+
+### Métodos de Connection
+
+| Método | Devuelve | Descripción |
+|--------|----------|-------------|
+| `conn.create_capture_session(end_user_id, collection_id, ws_connection_id, metadata)` | `CaptureSession` | Crea una sesión de captura nueva |
+| `conn.get_capture_session(capture_session_id)` | `CaptureSession` | Recupera una sesión de captura existente |
+| `conn.generate_client_token()` | `str` | Genera un token de autenticación del lado cliente |
+
+### Crear una sesión de captura
+
+```python
+from pathlib import Path
+
+ws_id = (Path.home() / ".theus" / "arsenal" / "videodb" / "videodb_ws_id").read_text().strip()
+
+session = conn.create_capture_session(
+    end_user_id="usuario-123",  # obligatorio
+    collection_id="default",
+    ws_connection_id=ws_id,
+    metadata={"app": "mi-app"},
+)
+print(f"ID de sesión: {session.id}")
+```
+
+> **Nota:** `end_user_id` es obligatorio e identifica al usuario que inicia la captura. Para pruebas o demos, sirve cualquier identificador único (p. ej. `"demo-user"`, `"test-123"`).
+
+### Propiedades de CaptureSession
+
+| Propiedad | Tipo | Descripción |
+|-----------|------|-------------|
+| `session.id` | `str` | ID único de la sesión de captura |
+
+### Métodos de CaptureSession
+
+| Método | Devuelve | Descripción |
+|--------|----------|-------------|
+| `session.get_rtstream(type)` | `list[RTStream]` | Obtiene los RTStreams por tipo: `"mic"`, `"screen"` o `"system_audio"` |
+
+### Generar un token de cliente
+
+```python
+token = conn.generate_client_token()
+```
+
+---
+
+## CaptureClient
+
+El cliente corre en la máquina del usuario y maneja permisos, descubrimiento de canales y streaming.
+
+```python
+from videodb.capture import CaptureClient
+
+client = CaptureClient(client_token=token)
+```
+
+### Métodos de CaptureClient
+
+| Método | Devuelve | Descripción |
+|--------|----------|-------------|
+| `await client.request_permission(type)` | `None` | Solicita permiso del dispositivo (`"microphone"`, `"screen_capture"`) |
+| `await client.list_channels()` | `Channels` | Descubre los canales de audio/video disponibles |
+| `await client.start_capture_session(capture_session_id, channels, primary_video_channel_id)` | `None` | Inicia el streaming de los canales seleccionados |
+| `await client.stop_capture()` | `None` | Detiene la sesión de captura de forma ordenada |
+| `await client.shutdown()` | `None` | Libera los recursos del cliente |
+
+### Solicitar permisos
+
+```python
+await client.request_permission("microphone")
+await client.request_permission("screen_capture")
+```
+
+### Iniciar una sesión
+
+```python
+selected_channels = [c for c in [mic, display, system_audio] if c]
+await client.start_capture_session(
+    capture_session_id=session.id,
+    channels=selected_channels,
+    primary_video_channel_id=display.id if display else None,
+)
+```
+
+### Detener una sesión
+
+```python
+await client.stop_capture()
+await client.shutdown()
+```
+
+---
+
+## Canales
+
+Devueltos por `client.list_channels()`. Agrupa los dispositivos disponibles por tipo.
+
+```python
+channels = await client.list_channels()
+for ch in channels.all():
+    print(f"  {ch.id} ({ch.type}): {ch.name}")
+
+mic = channels.mics.default
+display = channels.displays.default
+system_audio = channels.system_audio.default
+```
+
+### Grupos de canales
+
+| Propiedad | Tipo | Descripción |
+|-----------|------|-------------|
+| `channels.mics` | `ChannelGroup` | Micrófonos disponibles |
+| `channels.displays` | `ChannelGroup` | Pantallas disponibles |
+| `channels.system_audio` | `ChannelGroup` | Fuentes de audio del sistema disponibles |
+
+### Métodos y propiedades de ChannelGroup
+
+| Miembro | Tipo | Descripción |
+|---------|------|-------------|
+| `group.default` | `Channel` | Canal por defecto del grupo (o `None`) |
+| `group.all()` | `list[Channel]` | Todos los canales del grupo |
+
+### Propiedades de Channel
+
+| Propiedad | Tipo | Descripción |
+|-----------|------|-------------|
+| `ch.id` | `str` | ID único del canal |
+| `ch.type` | `str` | Tipo de canal (`"mic"`, `"display"`, `"system_audio"`) |
+| `ch.name` | `str` | Nombre legible del canal |
+| `ch.store` | `bool` | Si se persiste la grabación (ponlo en `True` para guardarla) |
+
+Sin `store = True`, los streams se procesan en tiempo real pero no se guardan.
+
+---
+
+## RTStreams y pipelines de IA
+
+Con la sesión activa, recupera los objetos RTStream con `session.get_rtstream()`.
+
+Para los métodos de RTStream (indexación, transcripción, alertas, batch config), ver [rtstream-reference.md](rtstream-reference.md).
+
+---
+
+## Ciclo de vida de la sesión
+
+```
+  create_capture_session()
+          │
+          v
+  ┌───────────────┐
+  │    created     │
+  └───────┬───────┘
+          │  client.start_capture_session()
+          v
+  ┌───────────────┐     WebSocket: capture_session.starting
+  │   starting     │ ──> Los canales de captura se conectan
+  └───────┬───────┘
+          │
+          v
+  ┌───────────────┐     WebSocket: capture_session.active
+  │    active      │ ──> Inicia los pipelines de IA
+  └───────┬──────────────┐
+          │              │
+          │              v
+          │      ┌───────────────┐     WebSocket: capture_session.failed
+          │      │    failed      │ ──> Inspecciona el error y reintenta la configuración
+          │      └───────────────┘
+          │      error de captura irrecuperable
+          │
+          │  client.stop_capture()
+          v
+  ┌───────────────┐     WebSocket: capture_session.stopping
+  │   stopping     │ ──> Finaliza los streams
+  └───────┬───────┘
+          │
+          v
+  ┌───────────────┐     WebSocket: capture_session.stopped
+  │   stopped      │ ──> Todos los streams finalizados
+  └───────┬───────┘
+          │  (si store=True)
+          v
+  ┌───────────────┐     WebSocket: capture_session.exported
+  │   exported     │ ──> Accede a video_id, stream_url, player_url
+  └───────────────┘
+```

package/vendor/theus-arsenal/skills/videodb/reference/capture.md

@@ -0,0 +1,101 @@
+# Guía de captura
+
+## Resumen
+
+VideoDB Capture permite grabar pantalla y audio en tiempo real con procesamiento de IA. La captura de escritorio actualmente solo funciona en **macOS**.
+
+Para detalles a nivel de código (métodos del SDK, estructuras de eventos, pipelines de IA), ver [capture-reference.md](capture-reference.md).
+
+## Inicio rápido
+
+1. **Inicia el listener WebSocket**: `python scripts/ws_listener.py --clear &`
+2. **Ejecuta el código de captura** (ver el flujo completo de captura más abajo)
+3. **Los eventos se escriben en**: `${VIDEODB_EVENTS_DIR:-$HOME/.theus/arsenal/videodb}/videodb_events.jsonl`
+
+---
+
+## Flujo de captura completo
+
+No se requieren webhooks ni polling. El WebSocket entrega todos los eventos, incluido el ciclo de vida de la sesión.
+
+> **CRÍTICO:** el `CaptureClient` debe permanecer en ejecución durante toda la captura. Ejecuta el binario grabador local que envía los datos de pantalla/audio a VideoDB. Si el proceso Python que creó el `CaptureClient` termina, el binario grabador muere y la captura se detiene silenciosamente. Ejecuta siempre el código de captura como un **proceso en segundo plano de larga vida** (p. ej. `nohup python capture_script.py &`) y usa manejo de señales (`asyncio.Event` + `SIGINT`/`SIGTERM`) para mantenerlo vivo hasta que lo detengas explícitamente.
+
+1. **Inicia el listener WebSocket** en segundo plano con el flag `--clear` para limpiar eventos antiguos. Espera a que cree el archivo con el ID del WebSocket.
+
+2. **Lee el ID del WebSocket**. Este ID es necesario para la sesión de captura y los pipelines de IA.
+
+3. **Crea una sesión de captura** y genera un token de cliente para el cliente de escritorio.
+
+4. **Inicializa el CaptureClient** con el token. Solicita permisos de micrófono y captura de pantalla.
+
+5. **Lista y selecciona canales** (mic, display, system_audio). Establece `store = True` en los canales que quieras persistir como video.
+
+6. **Inicia la sesión** con los canales seleccionados.
+
+7. **Espera a que la sesión esté activa** leyendo eventos hasta ver `capture_session.active`. Este evento contiene el arreglo `rtstreams`. Guarda la info de la sesión (ID de sesión, IDs de RTStream) en un archivo (p. ej. `~/.theus/arsenal/videodb/videodb_capture_info.json`) para que otros scripts la puedan leer.
+
+8. **Mantén vivo el proceso.** Usa `asyncio.Event` con manejadores de señales para `SIGINT`/`SIGTERM` para bloquear hasta que se detenga explícitamente. Escribe un archivo PID (p. ej. `~/.theus/arsenal/videodb/videodb_capture_pid`) para poder detener el proceso luego con `kill $(cat ~/.theus/arsenal/videodb/videodb_capture_pid)`. El archivo PID debe sobrescribirse en cada ejecución para que las reejecuciones siempre tengan el PID correcto.
+
+9. **Inicia los pipelines de IA** (en un comando/script separado) sobre cada RTStream para indexación de audio e indexación visual. Lee los IDs de RTStream del archivo de info de sesión guardado.
+
+10. **Escribe la lógica de procesamiento de eventos** (en un comando/script separado) para leer eventos en tiempo real según tu caso de uso. Ejemplos:
+    - Registrar actividad de Slack cuando `visual_index` mencione "Slack"
+    - Resumir discusiones cuando lleguen eventos `audio_index`
+    - Disparar alertas cuando aparezcan palabras clave concretas en `transcript`
+    - Rastrear uso de aplicaciones a partir de las descripciones de pantalla
+
+11. **Detén la captura** al terminar — envía SIGTERM al proceso de captura. Este debe llamar a `client.stop_capture()` y `client.shutdown()` en su manejador de señales.
+
+12. **Espera la exportación** leyendo eventos hasta ver `capture_session.exported`. Este evento contiene `exported_video_id`, `stream_url` y `player_url`. Puede tardar varios segundos tras detener la captura.
+
+13. **Detén el listener WebSocket** tras recibir el evento de exportación. Usa `kill $(cat ~/.theus/arsenal/videodb/videodb_ws_pid)` para terminarlo limpiamente.
+
+---
+
+## Secuencia de apagado
+
+El orden correcto de apagado es importante para asegurar que se capturen todos los eventos:
+
+1. **Detén la sesión de captura** — `client.stop_capture()` y luego `client.shutdown()`
+2. **Espera el evento de exportación** — sondea `~/.theus/arsenal/videodb/videodb_events.jsonl` buscando `capture_session.exported`
+3. **Detén el listener WebSocket** — `kill $(cat ~/.theus/arsenal/videodb/videodb_ws_pid)`
+
+NO mates el listener WebSocket antes de recibir el evento de exportación, o perderás las URLs finales del video.
+
+---
+
+## Scripts
+
+| Script | Descripción |
+|--------|-------------|
+| `scripts/ws_listener.py` | Listener de eventos WebSocket (vuelca a JSONL) |
+
+### Uso de ws_listener.py
+
+```bash
+# Iniciar el listener en segundo plano (añade a los eventos existentes)
+python scripts/ws_listener.py &
+
+# Iniciar el listener con limpieza (sesión nueva, borra eventos antiguos)
+python scripts/ws_listener.py --clear &
+
+# Directorio de salida personalizado
+python scripts/ws_listener.py --clear /ruta/a/eventos &
+
+# Detener el listener
+kill $(cat ~/.theus/arsenal/videodb/videodb_ws_pid)
+```
+
+**Opciones:**
+- `--clear`: limpia el archivo de eventos antes de iniciar. Úsalo al empezar una sesión de captura nueva.
+
+**Archivos de salida:**
+- `videodb_events.jsonl` - Todos los eventos WebSocket
+- `videodb_ws_id` - ID de la conexión WebSocket (para el parámetro `ws_connection_id`)
+- `videodb_ws_pid` - PID del proceso (para detener el listener)
+
+**Características:**
+- Reconexión automática con backoff exponencial ante cortes de conexión
+- Apagado limpio con SIGINT/SIGTERM
+- Archivo PID para gestión sencilla del proceso
+- Registro del estado de la conexión