theus-cli-darwin-x64 0.2.84

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

@@ -0,0 +1,550 @@
+# Referencia completa de la API
+
+Material de referencia de la skill de VideoDB. Para orientación de uso y selección de flujos, empieza por [../SKILL.md](../SKILL.md).
+
+## Conexión
+
+```python
+import videodb
+
+conn = videodb.connect(
+    api_key="tu-api-key",        # o define la variable de entorno VIDEO_DB_API_KEY
+    base_url=None,                # endpoint de API personalizado (opcional)
+)
+```
+
+**Devuelve:** objeto `Connection`
+
+### Métodos de Connection
+
+| Método | Devuelve | Descripción |
+|--------|---------|-------------|
+| `conn.get_collection(collection_id="default")` | `Collection` | Obtiene la colección (default si no hay ID) |
+| `conn.get_collections()` | `list[Collection]` | Lista todas las colecciones |
+| `conn.create_collection(name, description, is_public=False)` | `Collection` | Crea una colección nueva |
+| `conn.update_collection(id, name, description)` | `Collection` | Actualiza una colección |
+| `conn.check_usage()` | `dict` | Estadísticas de uso de la cuenta |
+| `conn.upload(source, media_type, name, ...)` | `Video\|Audio\|Image` | Sube a la colección por defecto |
+| `conn.record_meeting(meeting_url, bot_name, ...)` | `Meeting` | Graba una reunión |
+| `conn.create_capture_session(...)` | `CaptureSession` | Crea una sesión de captura (ver [capture-reference.md](capture-reference.md)) |
+| `conn.youtube_search(query, result_threshold, duration)` | `list[dict]` | Busca en YouTube |
+| `conn.transcode(source, callback_url, mode, ...)` | `str` | Transcodifica un video (devuelve ID de trabajo) |
+| `conn.get_transcode_details(job_id)` | `dict` | Estado y detalles del trabajo de transcodificación |
+| `conn.connect_websocket(collection_id)` | `WebSocketConnection` | Conecta al WebSocket (ver [capture-reference.md](capture-reference.md)) |
+
+### Transcodificación
+
+Transcodifica un video desde una URL con resolución, calidad y ajustes de audio personalizados. El procesamiento ocurre del lado del servidor — no se necesita ffmpeg local.
+
+```python
+from videodb import TranscodeMode, VideoConfig, AudioConfig
+
+job_id = conn.transcode(
+    source="https://example.com/video.mp4",
+    callback_url="https://example.com/webhook",
+    mode=TranscodeMode.economy,
+    video_config=VideoConfig(resolution=720, quality=23),
+    audio_config=AudioConfig(mute=False),
+)
+```
+
+#### Parámetros de transcode
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-----------|------|-------------|-------------|
+| `source` | `str` | requerido | URL del video a transcodificar (preferiblemente una URL descargable) |
+| `callback_url` | `str` | requerido | URL que recibirá el callback al terminar la transcodificación |
+| `mode` | `TranscodeMode` | `TranscodeMode.economy` | Velocidad de transcodificación: `economy` o `lightning` |
+| `video_config` | `VideoConfig` | `VideoConfig()` | Ajustes de codificación de video |
+| `audio_config` | `AudioConfig` | `AudioConfig()` | Ajustes de codificación de audio |
+
+Devuelve un ID de trabajo (`str`). Usa `conn.get_transcode_details(job_id)` para consultar el estado.
+
+```python
+details = conn.get_transcode_details(job_id)
+```
+
+#### VideoConfig
+
+```python
+from videodb import VideoConfig, ResizeMode
+
+config = VideoConfig(
+    resolution=720,              # Altura de resolución objetivo (p. ej. 480, 720, 1080)
+    quality=23,                  # Calidad de codificación (menor = mejor, por defecto 23)
+    framerate=30,                # Framerate objetivo
+    aspect_ratio="16:9",         # Relación de aspecto objetivo
+    resize_mode=ResizeMode.crop, # Cómo ajustar: crop, fit o pad
+)
+```
+
+| Campo | Tipo | Por defecto | Descripción |
+|-------|------|-------------|-------------|
+| `resolution` | `int\|None` | `None` | Altura de resolución objetivo en píxeles |
+| `quality` | `int` | `23` | Calidad de codificación (menor = mayor calidad) |
+| `framerate` | `int\|None` | `None` | Framerate objetivo |
+| `aspect_ratio` | `str\|None` | `None` | Relación de aspecto objetivo (p. ej. `"16:9"`, `"9:16"`) |
+| `resize_mode` | `str` | `ResizeMode.crop` | Estrategia de redimensionado: `crop`, `fit` o `pad` |
+
+#### AudioConfig
+
+```python
+from videodb import AudioConfig
+
+config = AudioConfig(mute=False)
+```
+
+| Campo | Tipo | Por defecto | Descripción |
+|-------|------|-------------|-------------|
+| `mute` | `bool` | `False` | Silencia la pista de audio |
+
+## Colecciones
+
+```python
+coll = conn.get_collection()
+```
+
+### Métodos de Collection
+
+| Método | Devuelve | Descripción |
+|--------|---------|-------------|
+| `coll.get_videos()` | `list[Video]` | Lista todos los videos |
+| `coll.get_video(video_id)` | `Video` | Obtiene un video concreto |
+| `coll.get_audios()` | `list[Audio]` | Lista todos los audios |
+| `coll.get_audio(audio_id)` | `Audio` | Obtiene un audio concreto |
+| `coll.get_images()` | `list[Image]` | Lista todas las imágenes |
+| `coll.get_image(image_id)` | `Image` | Obtiene una imagen concreta |
+| `coll.upload(url=None, file_path=None, media_type=None, name=None)` | `Video\|Audio\|Image` | Sube un medio |
+| `coll.search(query, search_type, index_type, score_threshold, namespace, scene_index_id, ...)` | `SearchResult` | Busca en toda la colección (solo semántica; keyword y scene lanzan `NotImplementedError`) |
+| `coll.generate_image(prompt, aspect_ratio="1:1")` | `Image` | Genera una imagen con IA |
+| `coll.generate_video(prompt, duration=5)` | `Video` | Genera un video con IA |
+| `coll.generate_music(prompt, duration=5)` | `Audio` | Genera música con IA |
+| `coll.generate_sound_effect(prompt, duration=2)` | `Audio` | Genera un efecto de sonido |
+| `coll.generate_voice(text, voice_name="Default")` | `Audio` | Genera voz a partir de texto |
+| `coll.generate_text(prompt, model_name="basic", response_type="text")` | `dict` | Generación de texto con el modelo — accede al resultado con `["output"]` |
+| `coll.dub_video(video_id, language_code)` | `Video` | Dobla un video a otro idioma |
+| `coll.record_meeting(meeting_url, bot_name, ...)` | `Meeting` | Graba una reunión en vivo |
+| `coll.create_capture_session(...)` | `CaptureSession` | Crea una sesión de captura (ver [capture-reference.md](capture-reference.md)) |
+| `coll.get_capture_session(...)` | `CaptureSession` | Recupera una sesión de captura (ver [capture-reference.md](capture-reference.md)) |
+| `coll.connect_rtstream(url, name, ...)` | `RTStream` | Conecta a un stream en vivo (ver [rtstream-reference.md](rtstream-reference.md)) |
+| `coll.make_public()` | `None` | Hace pública la colección |
+| `coll.make_private()` | `None` | Hace privada la colección |
+| `coll.delete_video(video_id)` | `None` | Elimina un video |
+| `coll.delete_audio(audio_id)` | `None` | Elimina un audio |
+| `coll.delete_image(image_id)` | `None` | Elimina una imagen |
+| `coll.delete()` | `None` | Elimina la colección |
+
+### Parámetros de upload
+
+```python
+video = coll.upload(
+    url=None,            # URL remota (HTTP, YouTube)
+    file_path=None,      # Ruta de archivo local
+    media_type=None,     # "video", "audio" o "image" (autodetectado si se omite)
+    name=None,           # Nombre personalizado del medio
+    description=None,    # Descripción
+    callback_url=None,   # URL de webhook para notificación asíncrona
+)
+```
+
+## Objeto Video
+
+```python
+video = coll.get_video(video_id)
+```
+
+### Propiedades de Video
+
+| Propiedad | Tipo | Descripción |
+|----------|------|-------------|
+| `video.id` | `str` | ID único del video |
+| `video.collection_id` | `str` | ID de la colección padre |
+| `video.name` | `str` | Nombre del video |
+| `video.description` | `str` | Descripción del video |
+| `video.length` | `float` | Duración en segundos |
+| `video.stream_url` | `str` | URL de stream por defecto |
+| `video.player_url` | `str` | URL de embed del reproductor |
+| `video.thumbnail_url` | `str` | URL de la miniatura |
+
+### Métodos de Video
+
+| Método | Devuelve | Descripción |
+|--------|---------|-------------|
+| `video.generate_stream(timeline=None)` | `str` | Genera URL de stream (línea de tiempo opcional de tuplas `[(inicio, fin)]`) |
+| `video.play()` | `str` | Abre el stream en el navegador, devuelve la URL del reproductor |
+| `video.index_spoken_words(language_code=None, force=False)` | `None` | Indexa el habla para búsqueda. Usa `force=True` para omitir si ya está indexado. |
+| `video.index_scenes(extraction_type, prompt, extraction_config, metadata, model_name, name, scenes, callback_url)` | `str` | Indexa escenas visuales (devuelve scene_index_id) |
+| `video.index_visuals(prompt, batch_config, ...)` | `str` | Indexa visuales (devuelve scene_index_id) |
+| `video.index_audio(prompt, model_name, ...)` | `str` | Indexa audio con el modelo (devuelve scene_index_id) |
+| `video.get_transcript(start=None, end=None)` | `list[dict]` | Transcripción con marcas de tiempo |
+| `video.get_transcript_text(start=None, end=None)` | `str` | Texto completo de la transcripción |
+| `video.generate_transcript(force=None)` | `dict` | Genera la transcripción |
+| `video.translate_transcript(language, additional_notes)` | `list[dict]` | Traduce la transcripción |
+| `video.search(query, search_type, index_type, filter, **kwargs)` | `SearchResult` | Busca dentro del video |
+| `video.add_subtitle(style=SubtitleStyle())` | `str` | Añade subtítulos (devuelve URL de stream) |
+| `video.generate_thumbnail(time=None)` | `str\|Image` | Genera una miniatura |
+| `video.get_thumbnails()` | `list[Image]` | Obtiene todas las miniaturas |
+| `video.extract_scenes(extraction_type, extraction_config)` | `SceneCollection` | Extrae escenas |
+| `video.reframe(start, end, target, mode, callback_url)` | `Video\|None` | Reencuadra la relación de aspecto |
+| `video.clip(prompt, content_type, model_name)` | `str` | Genera un clip a partir de un prompt (devuelve URL de stream) |
+| `video.insert_video(video, timestamp)` | `str` | Inserta un video en una marca de tiempo |
+| `video.download(name=None)` | `dict` | Descarga el video |
+| `video.delete()` | `None` | Elimina el video |
+
+### Reframe
+
+Convierte un video a otra relación de aspecto con seguimiento inteligente de objetos opcional. El procesamiento es del lado del servidor.
+
+> **Advertencia:** el reframe es una operación lenta del lado del servidor. Puede tardar varios minutos con videos largos y agotar el tiempo de espera. Usa siempre `start`/`end` para limitar el segmento, o pasa `callback_url` para procesamiento asíncrono.
+
+```python
+from videodb import ReframeMode
+
+# Prefiere siempre segmentos cortos para evitar timeouts:
+reframed = video.reframe(start=0, end=60, target="vertical", mode=ReframeMode.smart)
+
+# Reframe asíncrono para videos completos (devuelve None, resultado vía webhook):
+video.reframe(target="vertical", callback_url="https://example.com/webhook")
+
+# Dimensiones personalizadas
+reframed = video.reframe(start=0, end=60, target={"width": 1080, "height": 1080})
+```
+
+#### Parámetros de reframe
+
+| Parámetro | Tipo | Por defecto | Descripción |
+|-----------|------|-------------|-------------|
+| `start` | `float\|None` | `None` | Tiempo de inicio en segundos (None = principio) |
+| `end` | `float\|None` | `None` | Tiempo de fin en segundos (None = final del video) |
+| `target` | `str\|dict` | `"vertical"` | Preset (`"vertical"`, `"square"`, `"landscape"`) o `{"width": int, "height": int}` |
+| `mode` | `str` | `ReframeMode.smart` | `"simple"` (recorte centrado) o `"smart"` (seguimiento de objetos) |
+| `callback_url` | `str\|None` | `None` | URL de webhook para notificación asíncrona |
+
+Devuelve un objeto `Video` si no se pasa `callback_url`; `None` en caso contrario.
+
+## Objeto Audio
+
+```python
+audio = coll.get_audio(audio_id)
+```
+
+### Propiedades de Audio
+
+| Propiedad | Tipo | Descripción |
+|----------|------|-------------|
+| `audio.id` | `str` | ID único del audio |
+| `audio.collection_id` | `str` | ID de la colección padre |
+| `audio.name` | `str` | Nombre del audio |
+| `audio.length` | `float` | Duración en segundos |
+
+### Métodos de Audio
+
+| Método | Devuelve | Descripción |
+|--------|---------|-------------|
+| `audio.generate_url()` | `str` | Genera una URL firmada para reproducción |
+| `audio.get_transcript(start=None, end=None)` | `list[dict]` | Transcripción con marcas de tiempo |
+| `audio.get_transcript_text(start=None, end=None)` | `str` | Texto completo de la transcripción |
+| `audio.generate_transcript(force=None)` | `dict` | Genera la transcripción |
+| `audio.delete()` | `None` | Elimina el audio |
+
+## Objeto Image
+
+```python
+image = coll.get_image(image_id)
+```
+
+### Propiedades de Image
+
+| Propiedad | Tipo | Descripción |
+|----------|------|-------------|
+| `image.id` | `str` | ID único de la imagen |
+| `image.collection_id` | `str` | ID de la colección padre |
+| `image.name` | `str` | Nombre de la imagen |
+| `image.url` | `str\|None` | URL de la imagen (puede ser `None` para imágenes generadas — usa `generate_url()` en su lugar) |
+
+### Métodos de Image
+
+| Método | Devuelve | Descripción |
+|--------|---------|-------------|
+| `image.generate_url()` | `str` | Genera una URL firmada |
+| `image.delete()` | `None` | Elimina la imagen |
+
+## Timeline y editor
+
+### Timeline
+
+```python
+from videodb.timeline import Timeline
+
+timeline = Timeline(conn)
+```
+
+| Método | Devuelve | Descripción |
+|--------|---------|-------------|
+| `timeline.add_inline(asset)` | `None` | Añade `VideoAsset` secuencialmente en la pista principal |
+| `timeline.add_overlay(start, asset)` | `None` | Superpone `AudioAsset`, `ImageAsset` o `TextAsset` en una marca de tiempo |
+| `timeline.generate_stream()` | `str` | Compila y obtiene la URL de stream |
+
+### Tipos de asset
+
+#### VideoAsset
+
+```python
+from videodb.asset import VideoAsset
+
+asset = VideoAsset(
+    asset_id=video.id,
+    start=0,              # inicio del recorte (segundos)
+    end=None,             # fin del recorte (segundos, None = completo)
+)
+```
+
+#### AudioAsset
+
+```python
+from videodb.asset import AudioAsset
+
+asset = AudioAsset(
+    asset_id=audio.id,
+    start=0,
+    end=None,
+    disable_other_tracks=True,   # silencia el audio original cuando es True
+    fade_in_duration=0,          # segundos (máx. 5)
+    fade_out_duration=0,         # segundos (máx. 5)
+)
+```
+
+#### ImageAsset
+
+```python
+from videodb.asset import ImageAsset
+
+asset = ImageAsset(
+    asset_id=image.id,
+    duration=None,        # duración de visualización (segundos)
+    width=100,            # ancho de visualización
+    height=100,           # alto de visualización
+    x=80,                 # posición horizontal (px desde la izquierda)
+    y=20,                 # posición vertical (px desde arriba)
+)
+```
+
+#### TextAsset
+
+```python
+from videodb.asset import TextAsset, TextStyle
+
+asset = TextAsset(
+    text="Hola mundo",
+    duration=5,
+    style=TextStyle(
+        fontsize=24,
+        fontcolor="black",
+        boxcolor="white",       # color de la caja de fondo
+        alpha=1.0,
+        font="Sans",
+        text_align="T",         # alineación del texto dentro de la caja
+    ),
+)
+```
+
+#### CaptionAsset (Editor API)
+
+CaptionAsset pertenece a la Editor API, que tiene su propio sistema de Timeline, Track y Clip:
+
+```python
+from videodb.editor import CaptionAsset, FontStyling
+
+asset = CaptionAsset(
+    src="auto",                    # "auto" o cadena ASS en base64
+    font=FontStyling(name="Clear Sans", size=30),
+    primary_color="&H00FFFFFF",
+)
+```
+
+Ver [editor.md](editor.md#superposiciones-de-subtítulos-captions) para el uso completo de CaptionAsset con la Editor API.
+
+## Parámetros de búsqueda en video
+
+```python
+results = video.search(
+    query="tu consulta",
+    search_type=SearchType.semantic,       # semantic, keyword o scene
+    index_type=IndexType.spoken_word,      # spoken_word o scene
+    result_threshold=None,                 # máximo de resultados
+    score_threshold=None,                  # puntuación mínima de relevancia
+    dynamic_score_percentage=None,         # porcentaje de puntuación dinámica
+    scene_index_id=None,                   # apunta a un índice de escenas concreto (se pasa vía **kwargs)
+    filter=[],                             # filtros de metadatos para búsqueda de escenas
+)
+```
+
+> **Nota:** `filter` es un parámetro nombrado explícito en `video.search()`. `scene_index_id` se pasa a la API a través de `**kwargs`.
+>
+> **Importante:** `video.search()` lanza `InvalidRequestError` con el mensaje `"No results found"` cuando no hay coincidencias. Envuelve siempre las búsquedas en try/except. Para búsqueda de escenas, usa `score_threshold=0.3` o mayor para filtrar ruido de baja relevancia.
+
+Para búsqueda de escenas, usa `search_type=SearchType.semantic` con `index_type=IndexType.scene`. Pasa `scene_index_id` para apuntar a un índice de escenas concreto. Ver [search.md](search.md) para más detalles.
+
+## Objeto SearchResult
+
+```python
+results = video.search("consulta", search_type=SearchType.semantic)
+```
+
+| Método | Devuelve | Descripción |
+|--------|---------|-------------|
+| `results.get_shots()` | `list[Shot]` | Lista de segmentos coincidentes |
+| `results.compile()` | `str` | Compila todos los shots en una URL de stream |
+| `results.play()` | `str` | Abre el stream compilado en el navegador |
+
+### Propiedades de Shot
+
+| Propiedad | Tipo | Descripción |
+|----------|------|-------------|
+| `shot.video_id` | `str` | ID del video de origen |
+| `shot.video_length` | `float` | Duración del video de origen |
+| `shot.video_title` | `str` | Título del video de origen |
+| `shot.start` | `float` | Tiempo de inicio (segundos) |
+| `shot.end` | `float` | Tiempo de fin (segundos) |
+| `shot.text` | `str` | Contenido de texto coincidente |
+| `shot.search_score` | `float` | Puntuación de relevancia |
+
+| Método | Devuelve | Descripción |
+|--------|---------|-------------|
+| `shot.generate_stream()` | `str` | Stream de este shot concreto |
+| `shot.play()` | `str` | Abre el stream del shot en el navegador |
+
+## Objeto Meeting
+
+```python
+meeting = coll.record_meeting(
+    meeting_url="https://meet.google.com/...",
+    bot_name="Bot",
+    callback_url=None,          # URL de webhook para actualizaciones de estado
+    callback_data=None,         # dict opcional que se pasa a los callbacks
+    time_zone="UTC",            # Zona horaria de la reunión
+)
+```
+
+### Propiedades de Meeting
+
+| Propiedad | Tipo | Descripción |
+|----------|------|-------------|
+| `meeting.id` | `str` | ID único de la reunión |
+| `meeting.collection_id` | `str` | ID de la colección padre |
+| `meeting.status` | `str` | Estado actual |
+| `meeting.video_id` | `str` | ID del video grabado (al completarse) |
+| `meeting.bot_name` | `str` | Nombre del bot |
+| `meeting.meeting_title` | `str` | Título de la reunión |
+| `meeting.meeting_url` | `str` | URL de la reunión |
+| `meeting.speaker_timeline` | `dict` | Datos de la línea de tiempo de hablantes |
+| `meeting.is_active` | `bool` | True si está inicializando o procesando |
+| `meeting.is_completed` | `bool` | True si terminó |
+
+### Métodos de Meeting
+
+| Método | Devuelve | Descripción |
+|--------|---------|-------------|
+| `meeting.refresh()` | `Meeting` | Refresca los datos desde el servidor |
+| `meeting.wait_for_status(target_status, timeout=14400, interval=120)` | `bool` | Sondea hasta alcanzar el estado |
+
+## RTStream y captura
+
+Para RTStream (ingesta en vivo, indexación, transcripción), ver [rtstream-reference.md](rtstream-reference.md).
+
+Para sesiones de captura (grabación de escritorio, CaptureClient, canales), ver [capture-reference.md](capture-reference.md).
+
+## Enums y constantes
+
+### SearchType
+
+```python
+from videodb import SearchType
+
+SearchType.semantic    # Búsqueda semántica en lenguaje natural
+SearchType.keyword     # Coincidencia exacta de palabras clave
+SearchType.scene       # Búsqueda visual de escenas (puede requerir plan de pago)
+SearchType.llm         # Búsqueda potenciada por el modelo
+```
+
+### SceneExtractionType
+
+```python
+from videodb import SceneExtractionType
+
+SceneExtractionType.shot_based   # Detección automática de límites de plano
+SceneExtractionType.time_based   # Extracción a intervalos fijos de tiempo
+SceneExtractionType.transcript   # Extracción de escenas basada en la transcripción
+```
+
+### SubtitleStyle
+
+```python
+from videodb import SubtitleStyle
+
+style = SubtitleStyle(
+    font_name="Arial",
+    font_size=18,
+    primary_colour="&H00FFFFFF",
+    bold=False,
+    # ... ver SubtitleStyle para todas las opciones
+)
+video.add_subtitle(style=style)
+```
+
+### SubtitleAlignment y SubtitleBorderStyle
+
+```python
+from videodb import SubtitleAlignment, SubtitleBorderStyle
+```
+
+### TextStyle
+
+```python
+from videodb import TextStyle
+# o: from videodb.asset import TextStyle
+
+style = TextStyle(
+    fontsize=24,
+    fontcolor="black",
+    boxcolor="white",
+    font="Sans",
+    text_align="T",
+    alpha=1.0,
+)
+```
+
+### Otras constantes
+
+```python
+from videodb import (
+    IndexType,          # spoken_word, scene
+    MediaType,          # video, audio, image
+    Segmenter,          # word, sentence, time
+    SegmentationType,   # sentence, llm
+    TranscodeMode,      # economy, lightning
+    ResizeMode,         # crop, fit, pad
+    ReframeMode,        # simple, smart
+    RTStreamChannelType,
+)
+```
+
+## Excepciones
+
+```python
+from videodb.exceptions import (
+    AuthenticationError,     # API key inválida o ausente
+    InvalidRequestError,     # Parámetros incorrectos o solicitud mal formada
+    RequestTimeoutError,     # La solicitud agotó el tiempo de espera
+    SearchError,             # Fallo en la operación de búsqueda (p. ej. sin indexar)
+    VideodbError,            # Excepción base de todos los errores de VideoDB
+)
+```
+
+| Excepción | Causa común |
+|-----------|-------------|
+| `AuthenticationError` | `VIDEO_DB_API_KEY` ausente o inválida |
+| `InvalidRequestError` | URL inválida, formato no soportado, parámetros incorrectos |
+| `RequestTimeoutError` | El servidor tardó demasiado en responder |
+| `SearchError` | Buscar antes de indexar, tipo de búsqueda inválido |
+| `VideodbError` | Errores del servidor, problemas de red, fallos genéricos |