theus-cli-darwin-x64 0.2.84

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

@@ -0,0 +1,230 @@
+# Guía de búsqueda e indexación
+
+La búsqueda permite encontrar momentos concretos dentro de videos usando consultas en lenguaje natural, palabras clave exactas o descripciones visuales de escenas.
+
+## Requisitos previos
+
+Los videos **deben estar indexados** antes de poder buscarse. La indexación es una operación única por video y por tipo de índice.
+
+## Indexación
+
+### Índice de habla (spoken word)
+
+Indexa el contenido de habla transcrito de un video para búsqueda semántica y de palabras clave:
+
+```python
+video = coll.get_video(video_id)
+
+# force=True hace la indexación idempotente — la omite si ya está indexado
+video.index_spoken_words(force=True)
+```
+
+Esto transcribe la pista de audio y construye un índice buscable sobre el contenido hablado. Requerido para la búsqueda semántica y la de palabras clave.
+
+**Parámetros:**
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-----------|------|-------------|-------------|
+| `language_code` | `str\|None` | `None` | Código de idioma del video |
+| `segmentation_type` | `SegmentationType` | `SegmentationType.sentence` | Tipo de segmentación (`sentence` o `llm`) |
+| `force` | `bool` | `False` | Ponlo en `True` para omitir si ya está indexado (evita el error "already exists") |
+| `callback_url` | `str\|None` | `None` | URL de webhook para notificación asíncrona |
+
+### Índice de escenas
+
+Indexa el contenido visual generando descripciones de IA de las escenas. Igual que la indexación de habla, lanza un error si ya existe un índice de escenas. Extrae el `scene_index_id` existente del mensaje de error.
+
+```python
+import re
+from videodb import SceneExtractionType
+
+try:
+    scene_index_id = video.index_scenes(
+        extraction_type=SceneExtractionType.shot_based,
+        prompt="Describe el contenido visual, los objetos, las acciones y el entorno 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
+```
+
+**Tipos de extracción:**
+
+| Tipo | Descripción | Ideal para |
+|------|-------------|----------|
+| `SceneExtractionType.shot_based` | Divide por límites de plano visual | Uso general, contenido con acción |
+| `SceneExtractionType.time_based` | Divide a intervalos fijos | Muestreo uniforme, contenido largo estático |
+| `SceneExtractionType.transcript` | Divide según segmentos de la transcripción | Límites de escena guiados por el habla |
+
+**Parámetros para `time_based`:**
+
+```python
+video.index_scenes(
+    extraction_type=SceneExtractionType.time_based,
+    extraction_config={"time": 5, "select_frames": ["first", "last"]},
+    prompt="Describe qué está pasando en esta escena.",
+)
+```
+
+## Tipos de búsqueda
+
+### Búsqueda semántica
+
+Consultas en lenguaje natural contrastadas con el contenido hablado:
+
+```python
+from videodb import SearchType
+
+results = video.search(
+    query="explicando los beneficios del machine learning",
+    search_type=SearchType.semantic,
+)
+```
+
+Devuelve segmentos ordenados por relevancia donde el contenido hablado coincide semánticamente con la consulta.
+
+### Búsqueda por palabra clave
+
+Coincidencia exacta de términos en el habla transcrita:
+
+```python
+results = video.search(
+    query="inteligencia artificial",
+    search_type=SearchType.keyword,
+)
+```
+
+Devuelve segmentos que contienen exactamente la palabra clave o frase.
+
+### Búsqueda de escenas
+
+Consultas de contenido visual contrastadas con las descripciones de escenas indexadas. Requiere una llamada previa a `index_scenes()`.
+
+`index_scenes()` devuelve un `scene_index_id`. Pásalo a `video.search()` para apuntar a un índice de escenas concreto (especialmente importante cuando un video tiene varios índices de escenas):
+
+```python
+from videodb import SearchType, IndexType
+from videodb.exceptions import InvalidRequestError
+
+# Busca usando búsqueda semántica contra el índice de escenas.
+# 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()
+except InvalidRequestError as e:
+    if "No results found" in str(e):
+        shots = []
+    else:
+        raise
+```
+
+**Notas importantes:**
+
+- Usa `SearchType.semantic` con `index_type=IndexType.scene` — es la combinación más fiable y funciona en todos los planes.
+- `SearchType.scene` existe pero puede no estar disponible en todos los planes (p. ej. el gratuito). Prefiere `SearchType.semantic` con `IndexType.scene`.
+- El parámetro `scene_index_id` es opcional. Si se omite, la búsqueda corre contra todos los índices de escenas del video. Pásalo para apuntar a un índice concreto.
+- Puedes crear varios índices de escenas por video (con distintos prompts o tipos de extracción) y buscarlos de forma independiente usando `scene_index_id`.
+
+### Búsqueda de escenas con filtrado por metadatos
+
+Al indexar escenas con metadatos personalizados, puedes combinar la búsqueda semántica con filtros de metadatos:
+
+```python
+from videodb import SearchType, IndexType
+
+results = video.search(
+    query="una escena de persecución hábil",
+    search_type=SearchType.semantic,
+    index_type=IndexType.scene,
+    scene_index_id=scene_index_id,
+    filter=[{"camera_view": "road_ahead"}, {"action_type": "chasing"}],
+)
+```
+
+Ver el [cookbook de scene_level_metadata_indexing](https://github.com/video-db/videodb-cookbook/blob/main/quickstart/scene_level_metadata_indexing.ipynb) para un ejemplo completo de indexación con metadatos personalizados y búsqueda filtrada.
+
+## Trabajar con los resultados
+
+### Obtener shots
+
+Accede a los segmentos de resultado individuales:
+
+```python
+results = video.search("tu consulta")
+
+for shot in results.get_shots():
+    print(f"Video: {shot.video_id}")
+    print(f"Inicio: {shot.start:.2f}s")
+    print(f"Fin: {shot.end:.2f}s")
+    print(f"Texto: {shot.text}")
+    print("---")
+```
+
+### Reproducir los resultados compilados
+
+Transmite todos los segmentos coincidentes como un único video compilado:
+
+```python
+results = video.search("tu consulta")
+stream_url = results.compile()
+results.play()  # abre el stream compilado en el navegador
+```
+
+### Extraer clips
+
+Descarga o transmite segmentos concretos del resultado:
+
+```python
+for shot in results.get_shots():
+    stream_url = shot.generate_stream()
+    print(f"Clip: {stream_url}")
+```
+
+## Búsqueda entre colecciones
+
+Busca en todos los videos de una colección:
+
+```python
+coll = conn.get_collection()
+
+# Busca en todos los videos de la colección
+results = coll.search(
+    query="demo del producto",
+    search_type=SearchType.semantic,
+)
+
+for shot in results.get_shots():
+    print(f"Video: {shot.video_id} [{shot.start:.1f}s - {shot.end:.1f}s]")
+```
+
+> **Nota:** la búsqueda a nivel de colección solo soporta `SearchType.semantic`. Usar `SearchType.keyword` o `SearchType.scene` con `coll.search()` lanza `NotImplementedError`. Para búsqueda por palabra clave o de escenas, usa `video.search()` en videos individuales.
+
+## Búsqueda + compilación
+
+Indexa, busca y compila los segmentos coincidentes en un único stream reproducible:
+
+```python
+video.index_spoken_words(force=True)
+results = video.search(query="tu consulta", search_type=SearchType.semantic)
+stream_url = results.compile()
+print(stream_url)
+```
+
+## Consejos
+
+- **Indexa una vez, busca muchas**: la indexación es la operación cara. Una vez indexado, las búsquedas son rápidas.
+- **Combina tipos de índice**: indexa habla y escenas para habilitar todos los tipos de búsqueda sobre el mismo video.
+- **Refina las consultas**: la búsqueda semántica funciona mejor con frases descriptivas en lenguaje natural que con palabras sueltas.
+- **Usa palabra clave para precisión**: cuando necesites coincidencias exactas, la búsqueda por palabra clave evita la deriva semántica.
+- **Maneja "No results found"**: `video.search()` lanza `InvalidRequestError` cuando no hay coincidencias. Envuelve siempre las búsquedas en try/except y trata `"No results found"` como un conjunto vacío.
+- **Filtra el ruido en escenas**: la búsqueda semántica de escenas puede devolver resultados poco relevantes con consultas vagas. Usa `score_threshold=0.3` (o mayor) para filtrar ruido.
+- **Indexación idempotente**: usa `index_spoken_words(force=True)` para reindexar con seguridad. `index_scenes()` no tiene parámetro `force` — envuélvelo en try/except y extrae el `scene_index_id` existente del error con `re.search(r"id\s+([a-f0-9]+)", str(e))`.

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

@@ -0,0 +1,406 @@
+# Streaming y reproducción
+
+VideoDB genera streams bajo demanda y devuelve URLs compatibles con HLS que se reproducen al instante en cualquier reproductor de video estándar. Sin tiempos de renderizado ni esperas de exportación: ediciones, búsquedas y composiciones se transmiten de inmediato.
+
+## Requisitos previos
+
+Los videos **deben estar subidos** a una colección antes de generar streams. Para streams basados en búsqueda, el video además debe estar **indexado** (palabras habladas y/o escenas). Ver [search.md](search.md) para los detalles de indexación.
+
+## Conceptos clave
+
+### Generación de streams
+
+Cada video, resultado de búsqueda y línea de tiempo en VideoDB puede producir una **URL de stream**. Esa URL apunta a un manifiesto HLS (HTTP Live Streaming) que se compila bajo demanda.
+
+```python
+# Desde un video
+stream_url = video.generate_stream()
+
+# Desde una línea de tiempo
+stream_url = timeline.generate_stream()
+
+# Desde resultados de búsqueda
+stream_url = results.compile()
+```
+
+## Transmitir un solo video
+
+### Reproducción básica
+
+```python
+import videodb
+
+conn = videodb.connect()
+coll = conn.get_collection()
+video = coll.get_video("tu-video-id")
+
+# Genera la URL del stream
+stream_url = video.generate_stream()
+print(f"Stream: {stream_url}")
+
+# Abre en el navegador por defecto
+video.play()
+```
+
+### Con subtítulos
+
+```python
+# Indexa y añade subtítulos primero
+video.index_spoken_words(force=True)
+stream_url = video.add_subtitle()
+
+# La URL devuelta ya incluye los subtítulos
+print(f"Stream con subtítulos: {stream_url}")
+```
+
+### Segmentos específicos
+
+Transmite solo una porción de un video pasando una línea de tiempo de rangos de marcas de tiempo:
+
+```python
+# Transmite los segundos 10-30 y 60-90
+stream_url = video.generate_stream(timeline=[(10, 30), (60, 90)])
+print(f"Stream de segmentos: {stream_url}")
+```
+
+## Transmitir composiciones de línea de tiempo
+
+Construye una composición multi-asset y transmítela en tiempo real:
+
+```python
+import videodb
+from videodb.timeline import Timeline
+from videodb.asset import VideoAsset, AudioAsset, ImageAsset, TextAsset, TextStyle
+
+conn = videodb.connect()
+coll = conn.get_collection()
+
+video = coll.get_video(video_id)
+music = coll.get_audio(music_id)
+
+timeline = Timeline(conn)
+
+# Contenido de video principal
+timeline.add_inline(VideoAsset(asset_id=video.id))
+
+# Superposición de música de fondo (empieza en el segundo 0)
+timeline.add_overlay(0, AudioAsset(asset_id=music.id))
+
+# Superposición de texto al inicio
+timeline.add_overlay(0, TextAsset(
+    text="Demo en vivo",
+    duration=3,
+    style=TextStyle(fontsize=48, fontcolor="white", boxcolor="#000000"),
+))
+
+# Genera el stream compuesto
+stream_url = timeline.generate_stream()
+print(f"Stream compuesto: {stream_url}")
+```
+
+**Importante:** `add_inline()` solo acepta `VideoAsset`. Usa `add_overlay()` para `AudioAsset`, `ImageAsset` y `TextAsset`.
+
+Para edición de línea de tiempo en detalle, ver [editor.md](editor.md).
+
+## Transmitir resultados de búsqueda
+
+Compila los resultados de búsqueda en un único stream con todos los segmentos coincidentes:
+
+```python
+from videodb import SearchType
+from videodb.exceptions import InvalidRequestError
+
+video.index_spoken_words(force=True)
+try:
+    results = video.search("anuncio clave", search_type=SearchType.semantic)
+
+    # Compila todos los shots coincidentes en un solo stream
+    stream_url = results.compile()
+    print(f"Stream de resultados: {stream_url}")
+
+    # O reprodúcelo directamente
+    results.play()
+except InvalidRequestError as exc:
+    if "No results found" in str(exc):
+        print("No se encontraron segmentos de anuncio coincidentes.")
+    else:
+        raise
+```
+
+### Transmitir coincidencias individuales
+
+```python
+from videodb.exceptions import InvalidRequestError
+
+try:
+    results = video.search("demo del producto", search_type=SearchType.semantic)
+    for i, shot in enumerate(results.get_shots()):
+        stream_url = shot.generate_stream()
+        print(f"Coincidencia {i+1} [{shot.start:.1f}s-{shot.end:.1f}s]: {stream_url}")
+except InvalidRequestError as exc:
+    if "No results found" in str(exc):
+        print("Ningún segmento de demo del producto coincidió con la consulta.")
+    else:
+        raise
+```
+
+## Reproducción de audio
+
+Obtén una URL de reproducción firmada para contenido de audio:
+
+```python
+audio = coll.get_audio(audio_id)
+playback_url = audio.generate_url()
+print(f"URL de audio: {playback_url}")
+```
+
+## Ejemplos de flujos completos
+
+### Pipeline búsqueda-a-stream
+
+Combina búsqueda, composición de línea de tiempo y streaming en un solo flujo:
+
+```python
+import videodb
+from videodb import SearchType
+from videodb.exceptions import InvalidRequestError
+from videodb.timeline import Timeline
+from videodb.asset import VideoAsset, TextAsset, TextStyle
+
+conn = videodb.connect()
+coll = conn.get_collection()
+video = coll.get_video("tu-video-id")
+
+video.index_spoken_words(force=True)
+
+# Busca los momentos clave
+queries = ["introducción", "demo principal", "preguntas y respuestas"]
+timeline = Timeline(conn)
+timeline_offset = 0.0
+
+for query in queries:
+    try:
+        results = video.search(query, search_type=SearchType.semantic)
+        shots = results.get_shots()
+    except InvalidRequestError as exc:
+        if "No results found" in str(exc):
+            shots = []
+        else:
+            raise
+
+    if not shots:
+        continue
+
+    # Añade la etiqueta de sección donde empieza este bloque en la línea de tiempo compilada
+    timeline.add_overlay(timeline_offset, TextAsset(
+        text=query.title(),
+        duration=2,
+        style=TextStyle(fontsize=36, fontcolor="white", boxcolor="#222222"),
+    ))
+
+    for shot in shots:
+        timeline.add_inline(
+            VideoAsset(asset_id=shot.video_id, start=shot.start, end=shot.end)
+        )
+        timeline_offset += shot.end - shot.start
+
+stream_url = timeline.generate_stream()
+print(f"Compilación dinámica: {stream_url}")
+```
+
+### Stream multi-video
+
+Combina clips de distintos videos en un solo stream:
+
+```python
+import videodb
+from videodb.timeline import Timeline
+from videodb.asset import VideoAsset
+
+conn = videodb.connect()
+coll = conn.get_collection()
+
+video_clips = [
+    {"id": "vid_001", "start": 0, "end": 15},
+    {"id": "vid_002", "start": 10, "end": 30},
+    {"id": "vid_003", "start": 5, "end": 25},
+]
+
+timeline = Timeline(conn)
+for clip in video_clips:
+    timeline.add_inline(
+        VideoAsset(asset_id=clip["id"], start=clip["start"], end=clip["end"])
+    )
+
+stream_url = timeline.generate_stream()
+print(f"Stream multi-video: {stream_url}")
+```
+
+### Ensamblado condicional de stream
+
+Construye un stream dinámicamente según la disponibilidad de resultados:
+
+```python
+import videodb
+from videodb import SearchType
+from videodb.exceptions import InvalidRequestError
+from videodb.timeline import Timeline
+from videodb.asset import VideoAsset, TextAsset, TextStyle
+
+conn = videodb.connect()
+coll = conn.get_collection()
+video = coll.get_video("tu-video-id")
+
+video.index_spoken_words(force=True)
+
+timeline = Timeline(conn)
+
+# Intenta encontrar contenido específico; si no, usa el video completo
+topics = ["palabras de apertura", "análisis técnico a fondo", "cierre"]
+
+found_any = False
+timeline_offset = 0.0
+for topic in topics:
+    try:
+        results = video.search(topic, search_type=SearchType.semantic)
+        shots = results.get_shots()
+    except InvalidRequestError as exc:
+        if "No results found" in str(exc):
+            shots = []
+        else:
+            raise
+
+    if shots:
+        found_any = True
+        timeline.add_overlay(timeline_offset, TextAsset(
+            text=topic.title(),
+            duration=2,
+            style=TextStyle(fontsize=32, fontcolor="white", boxcolor="#1a1a2e"),
+        ))
+        for shot in shots:
+            timeline.add_inline(
+                VideoAsset(asset_id=shot.video_id, start=shot.start, end=shot.end)
+            )
+            timeline_offset += shot.end - shot.start
+
+if found_any:
+    stream_url = timeline.generate_stream()
+    print(f"Stream curado: {stream_url}")
+else:
+    # Recurre al stream del video completo
+    stream_url = video.generate_stream()
+    print(f"Stream del video completo: {stream_url}")
+```
+
+### Resumen de un evento en vivo
+
+Procesa la grabación de un evento en un resumen transmitible con varias secciones:
+
+```python
+import videodb
+from videodb import SearchType
+from videodb.exceptions import InvalidRequestError
+from videodb.timeline import Timeline
+from videodb.asset import VideoAsset, AudioAsset, ImageAsset, TextAsset, TextStyle
+
+conn = videodb.connect()
+coll = conn.get_collection()
+
+# Sube la grabación del evento
+event = coll.upload(url="https://example.com/event-recording.mp4")
+event.index_spoken_words(force=True)
+
+# Genera música de fondo
+music = coll.generate_music(
+    prompt="música corporativa de fondo animada",
+    duration=120,
+)
+
+# Genera la imagen del título
+title_img = coll.generate_image(
+    prompt="tarjeta de título moderna para resumen de evento, fondo oscuro, profesional",
+    aspect_ratio="16:9",
+)
+
+# Construye la línea de tiempo del resumen
+timeline = Timeline(conn)
+timeline_offset = 0.0
+
+# Segmentos de video principales a partir de búsquedas
+try:
+    keynote = event.search("anuncio de la keynote", search_type=SearchType.semantic)
+    keynote_shots = keynote.get_shots()[:5]
+except InvalidRequestError as exc:
+    if "No results found" in str(exc):
+        keynote_shots = []
+    else:
+        raise
+if keynote_shots:
+    keynote_start = timeline_offset
+    for shot in keynote_shots:
+        timeline.add_inline(
+            VideoAsset(asset_id=shot.video_id, start=shot.start, end=shot.end)
+        )
+        timeline_offset += shot.end - shot.start
+else:
+    keynote_start = None
+
+try:
+    demo = event.search("demo del producto", search_type=SearchType.semantic)
+    demo_shots = demo.get_shots()[:5]
+except InvalidRequestError as exc:
+    if "No results found" in str(exc):
+        demo_shots = []
+    else:
+        raise
+if demo_shots:
+    demo_start = timeline_offset
+    for shot in demo_shots:
+        timeline.add_inline(
+            VideoAsset(asset_id=shot.video_id, start=shot.start, end=shot.end)
+        )
+        timeline_offset += shot.end - shot.start
+else:
+    demo_start = None
+
+# Superpone la imagen de la tarjeta de título
+timeline.add_overlay(0, ImageAsset(
+    asset_id=title_img.id, width=100, height=100, x=80, y=20, duration=5
+))
+
+# Superpone las etiquetas de sección en los offsets correctos
+if keynote_start is not None:
+    timeline.add_overlay(max(5, keynote_start), TextAsset(
+        text="Momentos clave de la keynote",
+        duration=3,
+        style=TextStyle(fontsize=40, fontcolor="white", boxcolor="#0d1117"),
+    ))
+if demo_start is not None:
+    timeline.add_overlay(max(5, demo_start), TextAsset(
+        text="Momentos clave de la demo",
+        duration=3,
+        style=TextStyle(fontsize=36, fontcolor="white", boxcolor="#0d1117"),
+    ))
+
+# Superpone la música de fondo
+timeline.add_overlay(0, AudioAsset(
+    asset_id=music.id, fade_in_duration=3
+))
+
+# Transmite el resumen final
+stream_url = timeline.generate_stream()
+print(f"Resumen del evento: {stream_url}")
+```
+
+---
+
+## Consejos
+
+- **Compatibilidad HLS**: las URLs de stream devuelven manifiestos HLS (`.m3u8`). Funcionan nativamente en Safari, y en otros navegadores vía hls.js o librerías similares.
+- **Compilación bajo demanda**: los streams se compilan en el servidor al solicitarlos. La primera reproducción puede tener una breve demora de compilación; las siguientes reproducciones de la misma composición se cachean.
+- **Caché**: llamar a `video.generate_stream()` una segunda vez sin argumentos devuelve la URL de stream cacheada en lugar de recompilar.
+- **Streams de segmentos**: `video.generate_stream(timeline=[(start, end)])` es la forma más rápida de transmitir un clip específico sin construir un objeto `Timeline` completo.
+- **En línea vs superposición**: `add_inline()` solo acepta `VideoAsset` y coloca los assets secuencialmente en la pista principal. `add_overlay()` acepta `AudioAsset`, `ImageAsset` y `TextAsset` y los apila encima a partir de un tiempo de inicio dado.
+- **Valores por defecto de TextStyle**: `TextStyle` usa por defecto `font='Sans'`, `fontcolor='black'`. Usa `boxcolor` (no `bgcolor`) para el color de fondo del texto.
+- **Combina con generación**: usa `coll.generate_music(prompt, duration)` y `coll.generate_image(prompt, aspect_ratio)` para crear assets para composiciones de línea de tiempo.
+- **Reproducción**: `.play()` abre la URL del stream en el navegador por defecto del sistema. Para uso programático, trabaja directamente con la cadena de la URL.