theus-cli-linux-x64 0.2.84

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

@@ -0,0 +1,331 @@
+# 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"`.