theus-cli 0.2.83 → 0.2.85

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

@@ -1,443 +0,0 @@
-# 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.