npm - theus-cli - Versions diffs - 0.2.83 → 0.2.85 - Mend

theus-cli 0.2.83 → 0.2.85

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (738) hide show

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

@@ -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 |