theus-cli 0.2.82 → 0.2.84

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

@@ -1,331 +0,0 @@
-# Guía de medios generativos
-
-VideoDB ofrece generación con IA de imágenes, videos, música, efectos de sonido, voz y texto. Todos los métodos de generación están en el objeto **Collection**.
-
-## Requisitos previos
-
-Necesitas una conexión y una referencia a la colección antes de llamar a cualquier método de generación:
-
-```python
-import videodb
-
-conn = videodb.connect()
-coll = conn.get_collection()
-```
-
-## Generación de imágenes
-
-Genera imágenes a partir de prompts de texto:
-
-```python
-image = coll.generate_image(
-    prompt="una ciudad futurista al atardecer con autos voladores",
-    aspect_ratio="16:9",
-)
-
-# Accede a la imagen generada
-print(image.id)
-print(image.generate_url())  # devuelve una URL de descarga firmada
-```
-
-### Parámetros de generate_image
-
-| Parámetro | Tipo | Por defecto | Descripción |
-|-----------|------|-------------|-------------|
-| `prompt` | `str` | requerido | Descripción textual de la imagen a generar |
-| `aspect_ratio` | `str` | `"1:1"` | Relación de aspecto: `"1:1"`, `"9:16"`, `"16:9"`, `"4:3"` o `"3:4"` |
-| `callback_url` | `str\|None` | `None` | URL para recibir el callback asíncrono |
-
-Devuelve un objeto `Image` con `.id`, `.name` y `.collection_id`. La propiedad `.url` puede ser `None` en imágenes generadas — usa siempre `image.generate_url()` para obtener una URL de descarga firmada confiable.
-
-> **Nota:** a diferencia de los objetos `Video` (que usan `.generate_stream()`), los objetos `Image` usan `.generate_url()` para obtener la URL. La propiedad `.url` solo se llena en algunos tipos de imagen (p. ej. miniaturas).
-
-## Generación de video
-
-Genera clips de video cortos a partir de prompts de texto:
-
-```python
-video = coll.generate_video(
-    prompt="un timelapse de una flor abriéndose en un jardín",
-    duration=5,
-)
-
-stream_url = video.generate_stream()
-video.play()
-```
-
-### Parámetros de generate_video
-
-| Parámetro | Tipo | Por defecto | Descripción |
-|-----------|------|-------------|-------------|
-| `prompt` | `str` | requerido | Descripción textual del video a generar |
-| `duration` | `int` | `5` | Duración en segundos (debe ser un entero, 5-8) |
-| `callback_url` | `str\|None` | `None` | URL para recibir el callback asíncrono |
-
-Devuelve un objeto `Video`. Los videos generados se añaden automáticamente a la colección y pueden usarse en líneas de tiempo, búsquedas y compilaciones como cualquier video subido.
-
-## Generación de audio
-
-VideoDB provee tres métodos separados para distintos tipos de audio.
-
-### Música
-
-Genera música de fondo a partir de descripciones textuales:
-
-```python
-music = coll.generate_music(
-    prompt="música electrónica animada con ritmo constante, apta para una demo tecnológica",
-    duration=30,
-)
-
-print(music.id)
-```
-
-| Parámetro | Tipo | Por defecto | Descripción |
-|-----------|------|-------------|-------------|
-| `prompt` | `str` | requerido | Descripción textual de la música |
-| `duration` | `int` | `5` | Duración en segundos |
-| `callback_url` | `str\|None` | `None` | URL para recibir el callback asíncrono |
-
-### Efectos de sonido
-
-Genera efectos de sonido específicos:
-
-```python
-sfx = coll.generate_sound_effect(
-    prompt="tormenta eléctrica con lluvia intensa y truenos lejanos",
-    duration=10,
-)
-```
-
-| Parámetro | Tipo | Por defecto | Descripción |
-|-----------|------|-------------|-------------|
-| `prompt` | `str` | requerido | Descripción textual del efecto de sonido |
-| `duration` | `int` | `2` | Duración en segundos |
-| `config` | `dict` | `{}` | Configuración adicional |
-| `callback_url` | `str\|None` | `None` | URL para recibir el callback asíncrono |
-
-### Voz (texto a voz)
-
-Genera voz a partir de texto:
-
-```python
-voice = coll.generate_voice(
-    text="Bienvenidos a la demo de nuestro producto. Hoy recorreremos las funciones clave.",
-    voice_name="Default",
-)
-```
-
-| Parámetro | Tipo | Por defecto | Descripción |
-|-----------|------|-------------|-------------|
-| `text` | `str` | requerido | Texto a convertir en voz |
-| `voice_name` | `str` | `"Default"` | Voz a utilizar |
-| `config` | `dict` | `{}` | Configuración adicional |
-| `callback_url` | `str\|None` | `None` | URL para recibir el callback asíncrono |
-
-Los tres métodos de audio devuelven un objeto `Audio` con `.id`, `.name`, `.length` y `.collection_id`.
-
-## Generación de texto (LLM de VideoDB)
-
-Usa `coll.generate_text()` para ejecutar análisis con el LLM del propio servicio. Es un método a **nivel de colección** — pasa cualquier contexto (transcripciones, descripciones) directamente en la cadena del prompt.
-
-```python
-# Obtén primero la transcripción de un video
-transcript_text = video.get_transcript_text()
-
-# Genera el análisis con el LLM de la colección
-result = coll.generate_text(
-    prompt=f"Resume los puntos clave tratados en este video:\n{transcript_text}",
-    model_name="pro",
-)
-
-print(result["output"])
-```
-
-### Parámetros de generate_text
-
-| Parámetro | Tipo | Por defecto | Descripción |
-|-----------|------|-------------|-------------|
-| `prompt` | `str` | requerido | Prompt con contexto para el LLM |
-| `model_name` | `str` | `"basic"` | Nivel de modelo: `"basic"`, `"pro"` o `"ultra"` |
-| `response_type` | `str` | `"text"` | Formato de respuesta: `"text"` o `"json"` |
-
-Devuelve un `dict` con la clave `output`. Cuando `response_type="text"`, `output` es un `str`. Cuando `response_type="json"`, `output` es un `dict`.
-
-```python
-result = coll.generate_text(prompt="Resume esto", model_name="pro")
-print(result["output"])  # accede al texto/dict real
-```
-
-### Analizar escenas con el LLM
-
-Combina extracción de escenas con generación de texto:
-
-```python
-from videodb import SceneExtractionType
-
-# Primero indexa las escenas
-scenes = video.index_scenes(
-    extraction_type=SceneExtractionType.time_based,
-    extraction_config={"time": 10},
-    prompt="Describe el contenido visual de esta escena.",
-)
-
-# Obtén la transcripción para el contexto hablado
-transcript_text = video.get_transcript_text()
-scene_descriptions = []
-for scene in scenes:
-    if isinstance(scene, dict):
-        description = scene.get("description") or scene.get("summary")
-    else:
-        description = getattr(scene, "description", None) or getattr(scene, "summary", None)
-    scene_descriptions.append(description or str(scene))
-
-scenes_text = "\n".join(scene_descriptions)
-
-# Analiza con el LLM de la colección
-result = coll.generate_text(
-    prompt=(
-        f"Dada esta transcripción del video:\n{transcript_text}\n\n"
-        f"Y estas descripciones visuales de las escenas:\n{scenes_text}\n\n"
-        "Con base en el contenido hablado y visual, describe los temas principales tratados."
-    ),
-    model_name="pro",
-)
-print(result["output"])
-```
-
-## Doblaje y traducción
-
-### Doblar un video
-
-Dobla un video a otro idioma con el método de la colección:
-
-```python
-dubbed_video = coll.dub_video(
-    video_id=video.id,
-    language_code="es",  # español
-)
-
-dubbed_video.play()
-```
-
-### Parámetros de dub_video
-
-| Parámetro | Tipo | Por defecto | Descripción |
-|-----------|------|-------------|-------------|
-| `video_id` | `str` | requerido | ID del video a doblar |
-| `language_code` | `str` | requerido | Código del idioma destino (p. ej. `"es"`, `"fr"`, `"de"`) |
-| `callback_url` | `str\|None` | `None` | URL para recibir el callback asíncrono |
-
-Devuelve un objeto `Video` con el contenido doblado.
-
-### Traducir transcripción
-
-Traduce la transcripción de un video sin doblarlo:
-
-```python
-translated = video.translate_transcript(
-    language="Spanish",
-    additional_notes="Usa un tono formal",
-)
-
-for entry in translated:
-    print(entry)
-```
-
-**Idiomas soportados**, entre otros: `en`, `es`, `fr`, `de`, `it`, `pt`, `ja`, `ko`, `zh`, `hi`, `ar`.
-
-## Ejemplos de flujos completos
-
-### Generar narración para un video
-
-```python
-import videodb
-
-conn = videodb.connect()
-coll = conn.get_collection()
-video = coll.get_video("tu-video-id")
-
-# Obtén la transcripción
-transcript_text = video.get_transcript_text()
-
-# Genera el guion de narración con el LLM de la colección
-result = coll.generate_text(
-    prompt=(
-        f"Escribe un guion de narración profesional para este contenido de video:\n"
-        f"{transcript_text[:2000]}"
-    ),
-    model_name="pro",
-)
-script = result["output"]
-
-# Convierte el guion en voz
-narration = coll.generate_voice(text=script)
-print(f"Audio de narración: {narration.id}")
-```
-
-### Generar una miniatura desde un prompt
-
-```python
-thumbnail = coll.generate_image(
-    prompt="miniatura de video profesional mostrando un panel de analítica de datos, diseño moderno",
-    aspect_ratio="16:9",
-)
-print(f"URL de la miniatura: {thumbnail.generate_url()}")
-```
-
-### Añadir música generada a un video
-
-```python
-import videodb
-from videodb.timeline import Timeline
-from videodb.asset import VideoAsset, AudioAsset
-
-conn = videodb.connect()
-coll = conn.get_collection()
-video = coll.get_video("tu-video-id")
-
-# Genera música de fondo
-music = coll.generate_music(
-    prompt="música ambiental tranquila de fondo para un video tutorial",
-    duration=60,
-)
-
-# Construye la línea de tiempo con video + superposición de música
-timeline = Timeline(conn)
-timeline.add_inline(VideoAsset(asset_id=video.id))
-timeline.add_overlay(0, AudioAsset(asset_id=music.id, disable_other_tracks=False))
-
-stream_url = timeline.generate_stream()
-print(f"Video con música: {stream_url}")
-```
-
-### Salida JSON estructurada
-
-```python
-transcript_text = video.get_transcript_text()
-
-result = coll.generate_text(
-    prompt=(
-        f"Dada esta transcripción:\n{transcript_text}\n\n"
-        "Devuelve un objeto JSON con las claves: summary, topics (arreglo), action_items (arreglo)."
-    ),
-    model_name="pro",
-    response_type="json",
-)
-
-# result["output"] es un dict cuando response_type="json"
-print(result["output"]["summary"])
-print(result["output"]["topics"])
-```
-
-## Consejos
-
-- **Los medios generados son persistentes**: todo el contenido generado se guarda en tu colección y puede reutilizarse.
-- **Tres métodos de audio**: usa `generate_music()` para música de fondo, `generate_sound_effect()` para SFX y `generate_voice()` para texto a voz. No existe un método unificado `generate_audio()`.
-- **La generación de texto es a nivel de colección**: `coll.generate_text()` no accede automáticamente al contenido del video. Obtén la transcripción con `video.get_transcript_text()` y pásala en el prompt.
-- **Niveles de modelo**: `"basic"` es el más rápido, `"pro"` es equilibrado, `"ultra"` da la mayor calidad. Usa `"pro"` para la mayoría de tareas de análisis.
-- **Combina tipos de generación**: genera imágenes para superposiciones, música para fondos y voz para narración, y luego compón con líneas de tiempo (ver [editor.md](editor.md)).
-- **La calidad del prompt importa**: prompts descriptivos y específicos producen mejores resultados en todos los tipos de generación.
-- **Relaciones de aspecto para imágenes**: elige entre `"1:1"`, `"9:16"`, `"16:9"`, `"4:3"` o `"3:4"`.