theus-cli-linux-x64 1.2.2 → 1.4.0

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

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