theus-cli-linux-arm64 0.2.84

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

@@ -0,0 +1,443 @@
+# Guía de edición en línea de tiempo
+
+VideoDB ofrece un editor de línea de tiempo no destructivo para componer videos a partir de múltiples assets, añadir superposiciones de texto e imagen, mezclar pistas de audio y recortar clips — todo del lado del servidor, sin recodificar ni herramientas locales. Úsalo para recortar, combinar clips, superponer audio/música sobre video, añadir subtítulos y superponer texto o imágenes.
+
+## Requisitos previos
+
+Los videos, audios e imágenes **deben estar subidos** a una colección antes de poder usarse como assets de la línea de tiempo. Para superposiciones de captions, el video además debe estar **indexado por palabra hablada**.
+
+## Conceptos clave
+
+### Timeline
+
+Una `Timeline` es una capa de composición virtual. Los assets se colocan en ella **en línea** (secuencialmente en la pista principal) o como **superposiciones** (en capas, en una marca de tiempo concreta). Nada modifica el medio original; el stream final se compila bajo demanda.
+
+```python
+from videodb.timeline import Timeline
+
+timeline = Timeline(conn)
+```
+
+### Assets
+
+Cada elemento de una línea de tiempo es un **asset**. VideoDB provee cinco tipos:
+
+| Asset | Import | Uso principal |
+|-------|--------|---------------|
+| `VideoAsset` | `from videodb.asset import VideoAsset` | Clips de video (recorte, secuenciación) |
+| `AudioAsset` | `from videodb.asset import AudioAsset` | Música, SFX, narración |
+| `ImageAsset` | `from videodb.asset import ImageAsset` | Logos, miniaturas, superposiciones |
+| `TextAsset` | `from videodb.asset import TextAsset, TextStyle` | Títulos, captions, rótulos (lower-thirds) |
+| `CaptionAsset` | `from videodb.editor import CaptionAsset` | Subtítulos autogenerados (Editor API) |
+
+## Construir una línea de tiempo
+
+### Añadir clips de video en línea
+
+Los assets en línea se reproducen uno tras otro en la pista principal de video. El método `add_inline` solo acepta `VideoAsset`:
+
+```python
+from videodb.asset import VideoAsset
+
+video_a = coll.get_video(video_id_a)
+video_b = coll.get_video(video_id_b)
+
+timeline = Timeline(conn)
+timeline.add_inline(VideoAsset(asset_id=video_a.id))
+timeline.add_inline(VideoAsset(asset_id=video_b.id))
+
+stream_url = timeline.generate_stream()
+```
+
+### Recortar / sub-clip
+
+Usa `start` y `end` en un `VideoAsset` para extraer una porción:
+
+```python
+# Toma solo los segundos 10–30 del video de origen
+clip = VideoAsset(asset_id=video.id, start=10, end=30)
+timeline.add_inline(clip)
+```
+
+### Parámetros de VideoAsset
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-----------|------|-------------|-------------|
+| `asset_id` | `str` | requerido | ID del medio de video |
+| `start` | `float` | `0` | Inicio del recorte (segundos) |
+| `end` | `float\|None` | `None` | Fin del recorte (`None` = completo) |
+
+> **Advertencia:** el SDK no valida marcas de tiempo negativas. Pasar `start=-5` se acepta silenciosamente pero produce salida rota o inesperada. Asegura siempre `start >= 0`, `start < end` y `end <= video.length` antes de crear un `VideoAsset`.
+
+## Superposiciones de texto
+
+Añade títulos, rótulos o captions en cualquier punto de la línea de tiempo:
+
+```python
+from videodb.asset import TextAsset, TextStyle
+
+title = TextAsset(
+    text="Bienvenidos a la demo",
+    duration=5,
+    style=TextStyle(
+        fontsize=36,
+        fontcolor="white",
+        boxcolor="black",
+        alpha=0.8,
+        font="Sans",
+    ),
+)
+
+# Superpone el título justo al inicio (t=0)
+timeline.add_overlay(0, title)
+```
+
+### Parámetros de TextStyle
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-----------|------|-------------|-------------|
+| `fontsize` | `int` | `24` | Tamaño de fuente en píxeles |
+| `fontcolor` | `str` | `"black"` | Nombre de color CSS o hex |
+| `fontcolor_expr` | `str` | `""` | Expresión de color de fuente dinámico |
+| `alpha` | `float` | `1.0` | Opacidad del texto (0.0–1.0) |
+| `font` | `str` | `"Sans"` | Familia de fuente |
+| `box` | `bool` | `True` | Habilita la caja de fondo |
+| `boxcolor` | `str` | `"white"` | Color de la caja de fondo |
+| `boxborderw` | `str` | `"10"` | Ancho del borde de la caja |
+| `boxw` | `int` | `0` | Ancho de caja forzado |
+| `boxh` | `int` | `0` | Alto de caja forzado |
+| `line_spacing` | `int` | `0` | Interlineado |
+| `text_align` | `str` | `"T"` | Alineación del texto dentro de la caja |
+| `y_align` | `str` | `"text"` | Referencia de alineación vertical |
+| `borderw` | `int` | `0` | Ancho del borde del texto |
+| `bordercolor` | `str` | `"black"` | Color del borde del texto |
+| `expansion` | `str` | `"normal"` | Modo de expansión del texto |
+| `basetime` | `int` | `0` | Tiempo base para expresiones temporales |
+| `fix_bounds` | `bool` | `False` | Fija los límites del texto |
+| `text_shaping` | `bool` | `True` | Habilita el text shaping |
+| `shadowcolor` | `str` | `"black"` | Color de la sombra |
+| `shadowx` | `int` | `0` | Desplazamiento X de la sombra |
+| `shadowy` | `int` | `0` | Desplazamiento Y de la sombra |
+| `tabsize` | `int` | `4` | Tamaño de tabulación en espacios |
+| `x` | `str` | `"(main_w-text_w)/2"` | Expresión de posición horizontal |
+| `y` | `str` | `"(main_h-text_h)/2"` | Expresión de posición vertical |
+
+## Superposiciones de audio
+
+Superpón música de fondo, efectos de sonido o locución sobre la pista de video:
+
+```python
+from videodb.asset import AudioAsset
+
+music = coll.get_audio(music_id)
+
+audio_layer = AudioAsset(
+    asset_id=music.id,
+    disable_other_tracks=False,
+    fade_in_duration=2,
+    fade_out_duration=2,
+)
+
+# Inicia la música en t=0, superpuesta sobre la pista de video
+timeline.add_overlay(0, audio_layer)
+```
+
+### Parámetros de AudioAsset
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-----------|------|-------------|-------------|
+| `asset_id` | `str` | requerido | ID del medio de audio |
+| `start` | `float` | `0` | Inicio del recorte (segundos) |
+| `end` | `float\|None` | `None` | Fin del recorte (`None` = completo) |
+| `disable_other_tracks` | `bool` | `True` | Si es True, silencia las demás pistas de audio |
+| `fade_in_duration` | `float` | `0` | Segundos de fade-in (máx. 5) |
+| `fade_out_duration` | `float` | `0` | Segundos de fade-out (máx. 5) |
+
+## Superposiciones de imagen
+
+Añade logos, marcas de agua o imágenes generadas como superposiciones:
+
+```python
+from videodb.asset import ImageAsset
+
+logo = coll.get_image(logo_id)
+
+logo_overlay = ImageAsset(
+    asset_id=logo.id,
+    duration=10,
+    width=120,
+    height=60,
+    x=20,
+    y=20,
+)
+
+timeline.add_overlay(0, logo_overlay)
+```
+
+### Parámetros de ImageAsset
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-----------|------|-------------|-------------|
+| `asset_id` | `str` | requerido | ID del medio de imagen |
+| `width` | `int\|str` | `100` | Ancho de visualización |
+| `height` | `int\|str` | `100` | Alto de visualización |
+| `x` | `int` | `80` | Posición horizontal (px desde la izquierda) |
+| `y` | `int` | `20` | Posición vertical (px desde arriba) |
+| `duration` | `float\|None` | `None` | Duración en pantalla (segundos) |
+
+## Superposiciones de captions
+
+Hay dos formas de añadir captions a un video.
+
+### Método 1: flujo de subtítulos (el más simple)
+
+Usa `video.add_subtitle()` para incrustar subtítulos directamente en un stream de video. Internamente usa la `videodb.timeline.Timeline`:
+
+```python
+from videodb import SubtitleStyle
+
+# El video debe tener las palabras habladas indexadas primero (force=True omite si ya está hecho)
+video.index_spoken_words(force=True)
+
+# Añade subtítulos con estilo por defecto
+stream_url = video.add_subtitle()
+
+# O personaliza el estilo de los subtítulos
+stream_url = video.add_subtitle(style=SubtitleStyle(
+    font_name="Arial",
+    font_size=22,
+    primary_colour="&H00FFFFFF",
+    bold=True,
+))
+```
+
+### Método 2: Editor API (avanzado)
+
+La Editor API (`videodb.editor`) provee un sistema de composición basado en pistas con `CaptionAsset`, `Clip`, `Track` y su propia `Timeline`. Es una API separada de la `videodb.timeline.Timeline` usada arriba.
+
+```python
+from videodb.editor import (
+    CaptionAsset,
+    Clip,
+    Track,
+    Timeline as EditorTimeline,
+    FontStyling,
+    BorderAndShadow,
+    Positioning,
+    CaptionAnimation,
+)
+
+# El video debe tener las palabras habladas indexadas primero (force=True omite si ya está hecho)
+video.index_spoken_words(force=True)
+
+# Crea un asset de captions
+caption = CaptionAsset(
+    src="auto",
+    font=FontStyling(name="Clear Sans", size=30),
+    primary_color="&H00FFFFFF",
+    back_color="&H00000000",
+    border=BorderAndShadow(outline=1),
+    position=Positioning(margin_v=30),
+    animation=CaptionAnimation.box_highlight,
+)
+
+# Construye una línea de tiempo del editor con pistas y clips
+editor_tl = EditorTimeline(conn)
+track = Track()
+track.add_clip(start=0, clip=Clip(asset=caption, duration=video.length))
+editor_tl.add_track(track)
+stream_url = editor_tl.generate_stream()
+```
+
+### Parámetros de CaptionAsset
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-----------|------|-------------|-------------|
+| `src` | `str` | `"auto"` | Fuente de los captions (`"auto"` o cadena ASS en base64) |
+| `font` | `FontStyling\|None` | `FontStyling()` | Estilo de fuente (nombre, tamaño, negrita, cursiva, etc.) |
+| `primary_color` | `str` | `"&H00FFFFFF"` | Color primario del texto (formato ASS) |
+| `secondary_color` | `str` | `"&H000000FF"` | Color secundario del texto (formato ASS) |
+| `back_color` | `str` | `"&H00000000"` | Color de fondo (formato ASS) |
+| `border` | `BorderAndShadow\|None` | `BorderAndShadow()` | Estilo de borde y sombra |
+| `position` | `Positioning\|None` | `Positioning()` | Alineación y márgenes de los captions |
+| `animation` | `CaptionAnimation\|None` | `None` | Efecto de animación (p. ej. `box_highlight`, `reveal`, `karaoke`) |
+
+## Compilar y transmitir
+
+Tras montar la línea de tiempo, compílala en una URL transmitible. Los streams se generan al instante — sin tiempos de renderizado.
+
+```python
+stream_url = timeline.generate_stream()
+print(f"Stream: {stream_url}")
+```
+
+Para más opciones de streaming (streams de segmentos, búsqueda-a-stream, reproducción de audio), ver [streaming.md](streaming.md).
+
+## Ejemplos de flujos completos
+
+### Reel de momentos destacados con tarjeta de título
+
+```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")
+
+# 1. Busca los momentos clave
+video.index_spoken_words(force=True)
+try:
+    results = video.search("anuncio del producto", search_type=SearchType.semantic)
+    shots = results.get_shots()
+except InvalidRequestError as exc:
+    if "No results found" in str(exc):
+        shots = []
+    else:
+        raise
+
+# 2. Construye la línea de tiempo
+timeline = Timeline(conn)
+
+# Tarjeta de título
+title = TextAsset(
+    text="Momentos destacados del lanzamiento",
+    duration=4,
+    style=TextStyle(fontsize=48, fontcolor="white", boxcolor="#1a1a2e", alpha=0.95),
+)
+timeline.add_overlay(0, title)
+
+# Añade cada clip coincidente
+for shot in shots:
+    asset = VideoAsset(asset_id=shot.video_id, start=shot.start, end=shot.end)
+    timeline.add_inline(asset)
+
+# 3. Genera el stream
+stream_url = timeline.generate_stream()
+print(f"Reel de destacados: {stream_url}")
+```
+
+### Superposición de logo con música de fondo
+
+```python
+import videodb
+from videodb.timeline import Timeline
+from videodb.asset import VideoAsset, AudioAsset, ImageAsset
+
+conn = videodb.connect()
+coll = conn.get_collection()
+
+main_video = coll.get_video(main_video_id)
+music = coll.get_audio(music_id)
+logo = coll.get_image(logo_id)
+
+timeline = Timeline(conn)
+
+# Pista de video principal
+timeline.add_inline(VideoAsset(asset_id=main_video.id))
+
+# Música de fondo — disable_other_tracks=False para mezclarla con el audio del video
+timeline.add_overlay(
+    0,
+    AudioAsset(asset_id=music.id, disable_other_tracks=False, fade_in_duration=3),
+)
+
+# Logo en la esquina superior derecha durante los primeros 10 segundos
+timeline.add_overlay(
+    0,
+    ImageAsset(asset_id=logo.id, duration=10, x=1140, y=20, width=120, height=60),
+)
+
+stream_url = timeline.generate_stream()
+print(f"Video final: {stream_url}")
+```
+
+### Montaje multi-clip a partir de varios videos
+
+```python
+import videodb
+from videodb.timeline import Timeline
+from videodb.asset import VideoAsset, TextAsset, TextStyle
+
+conn = videodb.connect()
+coll = conn.get_collection()
+
+clips = [
+    {"video_id": "vid_001", "start": 5, "end": 15, "label": "Escena 1"},
+    {"video_id": "vid_002", "start": 0, "end": 20, "label": "Escena 2"},
+    {"video_id": "vid_003", "start": 30, "end": 45, "label": "Escena 3"},
+]
+
+timeline = Timeline(conn)
+timeline_offset = 0.0
+
+for clip in clips:
+    # Añade una etiqueta como superposición sobre cada clip
+    label = TextAsset(
+        text=clip["label"],
+        duration=2,
+        style=TextStyle(fontsize=32, fontcolor="white", boxcolor="#333333"),
+    )
+    timeline.add_inline(
+        VideoAsset(asset_id=clip["video_id"], start=clip["start"], end=clip["end"])
+    )
+    timeline.add_overlay(timeline_offset, label)
+    timeline_offset += clip["end"] - clip["start"]
+
+stream_url = timeline.generate_stream()
+print(f"Montaje: {stream_url}")
+```
+
+## Dos APIs de línea de tiempo
+
+VideoDB tiene dos sistemas de línea de tiempo separados. **No son intercambiables**:
+
+| | `videodb.timeline.Timeline` | `videodb.editor.Timeline` (Editor API) |
+|---|---|---|
+| **Import** | `from videodb.timeline import Timeline` | `from videodb.editor import Timeline as EditorTimeline` |
+| **Assets** | `VideoAsset`, `AudioAsset`, `ImageAsset`, `TextAsset` | `CaptionAsset`, `Clip`, `Track` |
+| **Métodos** | `add_inline()`, `add_overlay()` | `add_track()` con `Track` / `Clip` |
+| **Ideal para** | Composición de video, superposiciones, edición multi-clip | Estilo de captions/subtítulos con animaciones |
+
+No mezcles assets de una API en la otra. `CaptionAsset` solo funciona con la Editor API. `VideoAsset` / `AudioAsset` / `ImageAsset` / `TextAsset` solo funcionan con `videodb.timeline.Timeline`.
+
+## Limitaciones y restricciones
+
+El editor de línea de tiempo está diseñado para **composición lineal no destructiva**. Las siguientes operaciones **no están soportadas**:
+
+### No es posible
+
+| Limitación | Detalle |
+|---|---|
+| **Sin transiciones ni efectos** | No hay crossfades, cortinillas, disoluciones ni transiciones entre clips. Todos los cortes son cortes duros. |
+| **Sin video-sobre-video (picture-in-picture)** | `add_inline()` solo acepta `VideoAsset`. No puedes superponer un stream de video sobre otro. Las superposiciones de imagen pueden aproximar un PiP estático, pero no video en vivo. |
+| **Sin control de velocidad** | No hay cámara lenta, avance rápido, reproducción inversa ni remapeo temporal. `VideoAsset` no tiene parámetro `speed`. |
+| **Sin crop, zoom ni paneo** | No se puede recortar una región del cuadro, aplicar zoom ni panear. `video.reframe()` es solo para conversión de relación de aspecto. |
+| **Sin filtros de video ni gradación de color** | No hay ajustes de brillo, contraste, saturación, matiz ni corrección de color. |
+| **Sin texto animado** | `TextAsset` es estático durante toda su duración. Sin fade-in/out, movimiento ni animación. Para captions animados, usa `CaptionAsset` con la Editor API. |
+| **Sin estilos de texto mixtos** | Un `TextAsset` tiene un único `TextStyle`. No se puede mezclar negrita, cursiva o colores dentro de un mismo bloque de texto. |
+| **Sin clips en blanco ni de color sólido** | No se puede crear un cuadro de color sólido, pantalla en negro ni tarjeta de título independiente. Las superposiciones de texto e imagen requieren un `VideoAsset` debajo en la pista en línea. |
+| **Sin control de volumen de audio** | `AudioAsset` no tiene parámetro `volume`. El audio va a volumen completo o silenciado vía `disable_other_tracks`. No se puede mezclar a nivel reducido. |
+| **Sin animación por keyframes** | No se pueden cambiar propiedades de una superposición en el tiempo (p. ej. mover una imagen de la posición A a la B). |
+
+### Restricciones
+
+| Restricción | Detalle |
+|---|---|
+| **Fade de audio máx. 5 segundos** | `fade_in_duration` y `fade_out_duration` están limitados a 5 segundos cada uno. |
+| **El posicionamiento de superposiciones es absoluto** | Las superposiciones usan marcas de tiempo absolutas desde el inicio de la línea de tiempo. Reordenar los clips en línea no mueve sus superposiciones. |
+| **La pista en línea es solo de video** | `add_inline()` solo acepta `VideoAsset`. Audio, imagen y texto deben usar `add_overlay()`. |
+| **Sin anclaje de superposición a clip** | Las superposiciones se colocan en una marca de tiempo fija. No hay forma de anclar una superposición a un clip en línea concreto para que se mueva con él. |
+
+## Consejos
+
+- **No destructivo**: las líneas de tiempo nunca modifican el medio de origen. Puedes crear varias líneas de tiempo con los mismos assets.
+- **Apilado de superposiciones**: varias superposiciones pueden empezar en la misma marca de tiempo. Las de audio se mezclan entre sí; las de imagen/texto se apilan en orden de adición.
+- **En línea solo VideoAsset**: `add_inline()` solo acepta `VideoAsset`. Usa `add_overlay()` para `AudioAsset`, `ImageAsset` y `TextAsset`.
+- **Precisión de recorte**: `start`/`end` en `VideoAsset` y `AudioAsset` están en segundos.
+- **Silenciar el audio del video**: pon `disable_other_tracks=True` en `AudioAsset` para silenciar el audio original al superponer música o narración.
+- **Límites de fade**: `fade_in_duration` y `fade_out_duration` en `AudioAsset` tienen un máximo de 5 segundos.
+- **Medios generados**: usa `coll.generate_music()`, `coll.generate_sound_effect()`, `coll.generate_voice()` y `coll.generate_image()` para crear medios usables como assets de línea de tiempo de inmediato.