theus-cli-linux-x64 0.2.84

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

@@ -0,0 +1,564 @@
+# Referencia de RTStream
+
+Detalles a nivel de código para las operaciones de RTStream. Para la guía de flujo, ver [rtstream.md](rtstream.md).
+Para orientación de uso y elección de flujo, empieza por [../SKILL.md](../SKILL.md).
+
+Basado en [docs.videodb.io](https://docs.videodb.io/pages/ingest/live-streams/realtime-apis.md).
+
+---
+
+## Métodos RTStream de Collection
+
+Métodos de `Collection` para gestionar RTStreams:
+
+| Método | Devuelve | Descripción |
+|--------|----------|-------------|
+| `coll.connect_rtstream(url, name, ...)` | `RTStream` | Crea un RTStream nuevo desde una URL RTSP/RTMP |
+| `coll.get_rtstream(id)` | `RTStream` | Obtiene un RTStream existente por ID |
+| `coll.list_rtstreams(limit, offset, status, name, ordering)` | `List[RTStream]` | Lista todos los RTStreams de la colección |
+| `coll.search(query, namespace="rtstream")` | `RTStreamSearchResult` | Busca en todos los RTStreams |
+
+### Conectar un RTStream
+
+```python
+import videodb
+
+conn = videodb.connect()
+coll = conn.get_collection()
+
+rtstream = coll.connect_rtstream(
+    url="rtmp://tu-servidor-de-stream/live/stream-key",
+    name="Mi stream en vivo",
+    media_types=["video"],  # o ["audio", "video"]
+    sample_rate=30,         # opcional
+    store=True,             # habilita el almacenamiento de la grabación para exportar
+    enable_transcript=True, # opcional
+    ws_connection_id=ws_id, # opcional, para eventos en tiempo real
+)
+```
+
+### Obtener un RTStream existente
+
+```python
+rtstream = coll.get_rtstream("rts-xxx")
+```
+
+### Listar RTStreams
+
+```python
+rtstreams = coll.list_rtstreams(
+    limit=10,
+    offset=0,
+    status="connected",  # filtro opcional
+    name="reunion",      # filtro opcional
+    ordering="-created_at",
+)
+
+for rts in rtstreams:
+    print(f"{rts.id}: {rts.name} - {rts.status}")
+```
+
+### Desde una sesión de captura
+
+Con la sesión de captura activa, recupera los objetos RTStream:
+
+```python
+session = conn.get_capture_session(session_id)
+
+mics = session.get_rtstream("mic")
+displays = session.get_rtstream("screen")
+system_audios = session.get_rtstream("system_audio")
+```
+
+O usa los datos `rtstreams` del evento WebSocket `capture_session.active`:
+
+```python
+for rts in rtstreams:
+    rtstream = coll.get_rtstream(rts["rtstream_id"])
+```
+
+---
+
+## Métodos de RTStream
+
+| Método | Devuelve | Descripción |
+|--------|----------|-------------|
+| `rtstream.start()` | `None` | Inicia la ingesta |
+| `rtstream.stop()` | `None` | Detiene la ingesta |
+| `rtstream.generate_stream(start, end)` | `str` | Transmite un segmento grabado (timestamps Unix) |
+| `rtstream.export(name=None)` | `RTStreamExportResult` | Exporta a un video permanente |
+| `rtstream.index_visuals(prompt, ...)` | `RTStreamSceneIndex` | Crea un índice visual con análisis de IA |
+| `rtstream.index_audio(prompt, ...)` | `RTStreamSceneIndex` | Crea un índice de audio con resúmenes del LLM |
+| `rtstream.list_scene_indexes()` | `List[RTStreamSceneIndex]` | Lista todos los índices de escenas del stream |
+| `rtstream.get_scene_index(index_id)` | `RTStreamSceneIndex` | Obtiene un índice de escenas concreto |
+| `rtstream.search(query, ...)` | `RTStreamSearchResult` | Busca en el contenido indexado |
+| `rtstream.start_transcript(ws_connection_id, engine)` | `dict` | Inicia la transcripción en vivo |
+| `rtstream.get_transcript(page, page_size, start, end, since)` | `dict` | Obtiene páginas de la transcripción |
+| `rtstream.stop_transcript(engine)` | `dict` | Detiene la transcripción |
+
+---
+
+## Iniciar y detener
+
+```python
+# Inicia la ingesta
+rtstream.start()
+
+# ... el stream se está grabando ...
+
+# Detiene la ingesta
+rtstream.stop()
+```
+
+---
+
+## Generar streams
+
+Usa timestamps Unix (no offsets en segundos) para generar un stream de reproducción del contenido grabado:
+
+```python
+import time
+
+start_ts = time.time()
+rtstream.start()
+
+# Deja que grabe un rato...
+time.sleep(60)
+
+end_ts = time.time()
+rtstream.stop()
+
+# Genera una URL de stream para el segmento grabado
+stream_url = rtstream.generate_stream(start=start_ts, end=end_ts)
+print(f"Stream grabado: {stream_url}")
+```
+
+---
+
+## Exportar a video
+
+Exporta el stream grabado a un video permanente en la colección:
+
+```python
+export_result = rtstream.export(name="Grabación de reunión 2024-01-15")
+
+print(f"ID del video: {export_result.video_id}")
+print(f"URL del stream: {export_result.stream_url}")
+print(f"URL del reproductor: {export_result.player_url}")
+print(f"Duración: {export_result.duration}s")
+```
+
+### Propiedades de RTStreamExportResult
+
+| Propiedad | Tipo | Descripción |
+|-----------|------|-------------|
+| `video_id` | `str` | ID del video exportado |
+| `stream_url` | `str` | URL del stream HLS |
+| `player_url` | `str` | URL del reproductor web |
+| `name` | `str` | Nombre del video |
+| `duration` | `float` | Duración en segundos |
+
+---
+
+## Pipelines de IA
+
+Los pipelines de IA procesan los streams en vivo y envían los resultados vía WebSocket.
+
+### Métodos de pipelines de IA de RTStream
+
+| Método | Devuelve | Descripción |
+|--------|----------|-------------|
+| `rtstream.index_audio(prompt, batch_config, ...)` | `RTStreamSceneIndex` | Inicia la indexación de audio con resúmenes del LLM |
+| `rtstream.index_visuals(prompt, batch_config, ...)` | `RTStreamSceneIndex` | Inicia la indexación visual del contenido en pantalla |
+
+### Indexación de audio
+
+Genera resúmenes del LLM sobre el contenido de audio a intervalos:
+
+```python
+audio_index = rtstream.index_audio(
+    prompt="Resume lo que se está discutiendo",
+    batch_config={"type": "word", "value": 50},
+    model_name=None,       # opcional
+    name="audio_reunion",  # opcional
+    ws_connection_id=ws_id,
+)
+```
+
+**Opciones de batch_config para audio:**
+
+| Tipo | Valor | Descripción |
+|------|-------|-------------|
+| `"word"` | cantidad | Segmenta cada N palabras |
+| `"sentence"` | cantidad | Segmenta cada N oraciones |
+| `"time"` | segundos | Segmenta cada N segundos |
+
+Ejemplos:
+```python
+{"type": "word", "value": 50}      # cada 50 palabras
+{"type": "sentence", "value": 5}   # cada 5 oraciones
+{"type": "time", "value": 30}      # cada 30 segundos
+```
+
+Los resultados llegan por el canal WebSocket `audio_index`.
+
+### Indexación visual
+
+Genera descripciones de IA del contenido visual:
+
+```python
+scene_index = rtstream.index_visuals(
+    prompt="Describe lo que está pasando en pantalla",
+    batch_config={"type": "time", "value": 2, "frame_count": 5},
+    model_name="basic",
+    name="monitor_pantalla",  # opcional
+    ws_connection_id=ws_id,
+)
+```
+
+**Parámetros:**
+
+| Parámetro | Tipo | Descripción |
+|-----------|------|-------------|
+| `prompt` | `str` | Instrucciones para el modelo de IA (admite salida JSON estructurada) |
+| `batch_config` | `dict` | Controla el muestreo de frames (ver abajo) |
+| `model_name` | `str` | Nivel de modelo: `"mini"`, `"basic"`, `"pro"`, `"ultra"` |
+| `name` | `str` | Nombre del índice (opcional) |
+| `ws_connection_id` | `str` | ID de conexión WebSocket para recibir resultados |
+
+**batch_config visual:**
+
+| Clave | Tipo | Descripción |
+|-------|------|-------------|
+| `type` | `str` | Solo se soporta `"time"` para visuales |
+| `value` | `int` | Tamaño de la ventana en segundos |
+| `frame_count` | `int` | Número de frames a extraer por ventana |
+
+Ejemplo: `{"type": "time", "value": 2, "frame_count": 5}` muestrea 5 frames cada 2 segundos y los envía al modelo.
+
+**Salida JSON estructurada:**
+
+Usa un prompt que solicite formato JSON para respuestas estructuradas:
+
+```python
+scene_index = rtstream.index_visuals(
+    prompt="""Analiza la pantalla y devuelve un objeto JSON con:
+{
+  "app_name": "nombre de la aplicación activa",
+  "activity": "qué está haciendo el usuario",
+  "ui_elements": ["lista de elementos de UI visibles"],
+  "contains_text": true/false,
+  "dominant_colors": ["lista de colores principales"]
+}
+Devuelve solo JSON válido.""",
+    batch_config={"type": "time", "value": 3, "frame_count": 3},
+    model_name="pro",
+    ws_connection_id=ws_id,
+)
+```
+
+Los resultados llegan por el canal WebSocket `scene_index`.
+
+---
+
+## Resumen de batch_config
+
+| Tipo de indexación | Opciones de `type` | `value` | Claves extra |
+|--------------------|--------------------|---------|--------------|
+| **Audio** | `"word"`, `"sentence"`, `"time"` | palabras/oraciones/segundos | - |
+| **Visual** | solo `"time"` | segundos | `frame_count` |
+
+Ejemplos:
+```python
+# Audio: cada 50 palabras
+{"type": "word", "value": 50}
+
+# Audio: cada 30 segundos
+{"type": "time", "value": 30}
+
+# Visual: 5 frames cada 2 segundos
+{"type": "time", "value": 2, "frame_count": 5}
+```
+
+---
+
+## Transcripción
+
+Transcripción en tiempo real vía WebSocket:
+
+```python
+# Inicia la transcripción en vivo
+rtstream.start_transcript(
+    ws_connection_id=ws_id,
+    engine=None,  # opcional, por defecto "assemblyai"
+)
+
+# Obtiene páginas de la transcripción (con filtros opcionales)
+transcript = rtstream.get_transcript(
+    page=1,
+    page_size=100,
+    start=None,   # opcional: filtro de timestamp inicial
+    end=None,     # opcional: filtro de timestamp final
+    since=None,   # opcional: para sondeo, obtiene transcripciones posteriores a este timestamp
+    engine=None,
+)
+
+# Detiene la transcripción
+rtstream.stop_transcript(engine=None)
+```
+
+Los resultados de transcripción llegan por el canal WebSocket `transcript`.
+
+---
+
+## RTStreamSceneIndex
+
+Al llamar a `index_audio()` o `index_visuals()`, el método devuelve un objeto `RTStreamSceneIndex`. Este objeto representa el índice en ejecución y provee métodos para gestionar escenas y alertas.
+
+```python
+# index_visuals devuelve un RTStreamSceneIndex
+scene_index = rtstream.index_visuals(
+    prompt="Describe lo que hay en pantalla",
+    ws_connection_id=ws_id,
+)
+
+# index_audio también devuelve un RTStreamSceneIndex
+audio_index = rtstream.index_audio(
+    prompt="Resume la discusión",
+    ws_connection_id=ws_id,
+)
+```
+
+### Propiedades de RTStreamSceneIndex
+
+| Propiedad | Tipo | Descripción |
+|-----------|------|-------------|
+| `rtstream_index_id` | `str` | ID único del índice |
+| `rtstream_id` | `str` | ID del RTStream padre |
+| `extraction_type` | `str` | Tipo de extracción (`time` o `transcript`) |
+| `extraction_config` | `dict` | Configuración de la extracción |
+| `prompt` | `str` | El prompt usado para el análisis |
+| `name` | `str` | Nombre del índice |
+| `status` | `str` | Estado (`connected`, `stopped`) |
+
+### Métodos de RTStreamSceneIndex
+
+| Método | Devuelve | Descripción |
+|--------|----------|-------------|
+| `index.get_scenes(start, end, page, page_size)` | `dict` | Obtiene las escenas indexadas |
+| `index.start()` | `None` | Inicia/reanuda el índice |
+| `index.stop()` | `None` | Detiene el índice |
+| `index.create_alert(event_id, callback_url, ws_connection_id)` | `str` | Crea una alerta para detección de eventos |
+| `index.list_alerts()` | `list` | Lista todas las alertas de este índice |
+| `index.enable_alert(alert_id)` | `None` | Habilita una alerta |
+| `index.disable_alert(alert_id)` | `None` | Deshabilita una alerta |
+
+### Obtener escenas
+
+Sondea las escenas indexadas desde el índice:
+
+```python
+result = scene_index.get_scenes(
+    start=None,      # opcional: timestamp inicial
+    end=None,        # opcional: timestamp final
+    page=1,
+    page_size=100,
+)
+
+for scene in result["scenes"]:
+    print(f"[{scene['start']}-{scene['end']}] {scene['text']}")
+
+if result["next_page"]:
+    # obtener la siguiente página
+    pass
+```
+
+### Gestionar índices de escenas
+
+```python
+# Lista todos los índices del stream
+indexes = rtstream.list_scene_indexes()
+
+# Obtiene un índice concreto por ID
+scene_index = rtstream.get_scene_index(index_id)
+
+# Detiene un índice
+scene_index.stop()
+
+# Reinicia un índice
+scene_index.start()
+```
+
+---
+
+## Eventos
+
+Los eventos son reglas de detección reutilizables. Créalos una vez y adjúntalos a cualquier índice mediante alertas.
+
+### Métodos de eventos de Connection
+
+| Método | Devuelve | Descripción |
+|--------|----------|-------------|
+| `conn.create_event(event_prompt, label)` | `str` (event_id) | Crea un evento de detección |
+| `conn.list_events()` | `list` | Lista todos los eventos |
+
+### Crear un evento
+
+```python
+event_id = conn.create_event(
+    event_prompt="El usuario abrió la aplicación Slack",
+    label="slack_abierto",
+)
+```
+
+### Listar eventos
+
+```python
+events = conn.list_events()
+for event in events:
+    print(f"{event['event_id']}: {event['label']}")
+```
+
+---
+
+## Alertas
+
+Las alertas conectan eventos con índices para recibir notificaciones en tiempo real. Cuando la IA detecta contenido que coincide con la descripción del evento, se envía una alerta.
+
+### Crear una alerta
+
+```python
+# Obtén el RTStreamSceneIndex desde index_visuals
+scene_index = rtstream.index_visuals(
+    prompt="Describe qué aplicación está abierta en pantalla",
+    ws_connection_id=ws_id,
+)
+
+# Crea una alerta sobre el índice
+alert_id = scene_index.create_alert(
+    event_id=event_id,
+    callback_url="https://tu-backend.com/alerts",  # para entrega por webhook
+    ws_connection_id=ws_id,  # para entrega por WebSocket (opcional)
+)
+```
+
+**Nota:** `callback_url` es obligatorio. Pasa una cadena vacía `""` si solo usas entrega por WebSocket.
+
+### Gestionar alertas
+
+```python
+# Lista todas las alertas de un índice
+alerts = scene_index.list_alerts()
+
+# Habilita/deshabilita alertas
+scene_index.disable_alert(alert_id)
+scene_index.enable_alert(alert_id)
+```
+
+### Entrega de alertas
+
+| Método | Latencia | Caso de uso |
+|--------|----------|-------------|
+| WebSocket | Tiempo real | Paneles, UI en vivo |
+| Webhook | < 1 segundo | Servidor-a-servidor, automatización |
+
+### Evento de alerta por WebSocket
+
+```json
+{
+  "channel": "alert",
+  "rtstream_id": "rts-xxx",
+  "data": {
+    "event_label": "slack_abierto",
+    "timestamp": 1710000012340,
+    "text": "El usuario abrió la aplicación Slack"
+  }
+}
+```
+
+### Payload del webhook
+
+```json
+{
+  "event_id": "event-xxx",
+  "label": "slack_abierto",
+  "confidence": 0.95,
+  "explanation": "El usuario abrió la aplicación Slack",
+  "timestamp": "2024-01-15T10:30:45Z",
+  "start_time": 1234.5,
+  "end_time": 1238.0,
+  "stream_url": "https://stream.videodb.io/v3/...",
+  "player_url": "https://console.videodb.io/player?url=..."
+}
+```
+
+---
+
+## Integración con WebSocket
+
+Todos los resultados de IA en tiempo real se entregan vía WebSocket. Pasa `ws_connection_id` a:
+- `rtstream.start_transcript()`
+- `rtstream.index_audio()`
+- `rtstream.index_visuals()`
+- `scene_index.create_alert()`
+
+### Canales WebSocket
+
+| Canal | Origen | Contenido |
+|-------|--------|-----------|
+| `transcript` | `start_transcript()` | Voz a texto en tiempo real |
+| `scene_index` | `index_visuals()` | Resultados de análisis visual |
+| `audio_index` | `index_audio()` | Resultados de análisis de audio |
+| `alert` | `create_alert()` | Notificaciones de alertas |
+
+Para las estructuras de eventos WebSocket y el uso de ws_listener, ver [capture-reference.md](capture-reference.md).
+
+---
+
+## Flujo completo
+
+```python
+import time
+import videodb
+from videodb.exceptions import InvalidRequestError
+
+conn = videodb.connect()
+coll = conn.get_collection()
+
+# 1. Conecta e inicia la grabación
+rtstream = coll.connect_rtstream(
+    url="rtmp://tu-servidor-de-stream/live/stream-key",
+    name="Standup semanal",
+    store=True,
+)
+rtstream.start()
+
+# 2. Graba durante la duración de la reunión
+start_ts = time.time()
+time.sleep(1800)  # 30 minutos
+end_ts = time.time()
+rtstream.stop()
+
+# Genera una URL de reproducción inmediata para la ventana capturada
+stream_url = rtstream.generate_stream(start=start_ts, end=end_ts)
+print(f"Stream grabado: {stream_url}")
+
+# 3. Exporta a un video permanente
+export_result = rtstream.export(name="Grabación del standup semanal")
+print(f"Video exportado: {export_result.video_id}")
+
+# 4. Indexa el video exportado para búsqueda
+video = coll.get_video(export_result.video_id)
+video.index_spoken_words(force=True)
+
+# 5. Busca los puntos de acción
+try:
+    results = video.search("puntos de acción y próximos pasos")
+    stream_url = results.compile()
+    print(f"Clip de puntos de acción: {stream_url}")
+except InvalidRequestError as exc:
+    if "No results found" in str(exc):
+        print("No se detectaron puntos de acción en la grabación.")
+    else:
+        raise
+```

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

@@ -0,0 +1,65 @@
+# Guía de RTStream
+
+## Resumen
+
+RTStream permite la ingesta en tiempo real de streams de video en vivo (RTSP/RTMP) y de sesiones de captura de escritorio. Una vez conectado, puedes grabar, indexar, buscar y exportar contenido de fuentes en vivo.
+
+Para los detalles a nivel de código (métodos del SDK, parámetros, ejemplos), ver [rtstream-reference.md](rtstream-reference.md).
+
+## Casos de uso
+
+- **Seguridad y monitoreo**: conectar cámaras RTSP, detectar eventos, disparar alertas
+- **Transmisiones en vivo**: ingerir streams RTMP, indexar en tiempo real, habilitar búsqueda instantánea
+- **Grabación de reuniones**: capturar pantalla y audio del escritorio, transcribir en vivo, exportar grabaciones
+- **Procesamiento de eventos**: monitorear feeds en vivo, ejecutar análisis con IA, responder al contenido detectado
+
+## Inicio rápido
+
+1. **Conéctate a un stream en vivo** (URL RTSP/RTMP) u obtén el RTStream desde una sesión de captura
+
+2. **Inicia la ingesta** para empezar a grabar el contenido en vivo
+
+3. **Inicia los pipelines de IA** para indexación en tiempo real (audio, visual, transcripción)
+
+4. **Monitorea los eventos** vía WebSocket para resultados de IA y alertas en vivo
+
+5. **Detén la ingesta** al terminar
+
+6. **Exporta a video** para almacenamiento permanente y procesamiento posterior
+
+7. **Busca en la grabación** para encontrar momentos específicos
+
+## Fuentes de RTStream
+
+### Desde streams RTSP/RTMP
+
+Conéctate directamente a una fuente de video en vivo:
+
+```python
+rtstream = coll.connect_rtstream(
+    url="rtmp://tu-servidor-de-stream/live/stream-key",
+    name="Mi stream en vivo",
+)
+```
+
+### Desde sesiones de captura
+
+Obtén los RTStreams de una captura de escritorio (micrófono, pantalla, audio del sistema):
+
+```python
+session = conn.get_capture_session(session_id)
+
+mics = session.get_rtstream("mic")
+displays = session.get_rtstream("screen")
+system_audios = session.get_rtstream("system_audio")
+```
+
+Para el flujo de sesiones de captura, ver [capture.md](capture.md).
+
+---
+
+## Scripts
+
+| Script | Descripción |
+|--------|-------------|
+| `scripts/ws_listener.py` | Listener de eventos WebSocket para resultados de IA en tiempo real |