Skill VideoDB

Percepção + memória + ações para vídeo, streams ao vivo e sessões de desktop.

Quando usar

Percepção de Desktop

Iniciar/parar uma sessão de desktop capturando tela, microfone e áudio do sistema
Transmitir contexto ao vivo e armazenar memória episódica da sessão
Executar alertas/gatilhos em tempo real sobre o que é falado e o que acontece na tela
Produzir resumos de sessão, uma linha do tempo pesquisável e links de evidência reproduzíveis

Ingestão de vídeo + stream

Ingerir um arquivo ou URL e retornar um link de stream web reproduzível
Transcodificar/normalizar: codec, bitrate, fps, resolução, proporção

Indexar + pesquisar (timestamps + evidência)

Construir índices visual, falado e de palavras-chave
Pesquisar e retornar momentos exatos com timestamps e evidência reproduzível
Criar clipes automaticamente a partir dos resultados da pesquisa

Edição de linha do tempo + geração

Legendas: gerar, traduzir, queimar
Sobreposições: texto/imagem/marca, legendas animadas
Áudio: música de fundo, narração, dublagem
Composição programática e exportações via operações de linha do tempo

Streams ao vivo (RTSP) + monitoramento

Conectar feeds RTSP/ao vivo
Executar compreensão visual e falada em tempo real e emitir eventos/alertas para fluxos de monitoramento

Como funciona

Entradas comuns

Caminho de arquivo local, URL pública ou URL RTSP
Solicitação de captura de desktop: iniciar / parar / resumir sessão
Operações desejadas: obter contexto para compreensão, especificação de transcodificação, especificação de índice, consulta de pesquisa, intervalos de clipe, edições de linha do tempo, regras de alerta

Saídas comuns

URL do stream
Resultados de pesquisa com timestamps e links de evidência
Assets gerados: legendas, áudio, imagens, clipes
Payloads de evento/alerta para streams ao vivo
Resumos de sessão de desktop e entradas de memória

Executando código Python

Antes de executar qualquer código do VideoDB, mude para o diretório do projeto e carregue as variáveis de ambiente:

from dotenv import load_dotenv
load_dotenv(".env")

import videodb
conn = videodb.connect()

Isso lê VIDEO_DB_API_KEY de:

Ambiente (se já exportado)
Arquivo .env do projeto no diretório atual

Se a chave estiver faltando, videodb.connect() gera automaticamente AuthenticationError.

Não escreva um arquivo de script quando um comando inline curto funcionar.

Ao escrever Python inline (python -c "..."), sempre use código formatado corretamente — use ponto e vírgula para separar instruções e mantenha legível. Para qualquer coisa com mais de ~3 instruções, use um heredoc:

python << 'EOF'
from dotenv import load_dotenv
load_dotenv(".env")

import videodb
conn = videodb.connect()
coll = conn.get_collection()
print(f"Vídeos: {len(coll.get_videos())}")
EOF

Configuração

Quando o usuário pedir para "configurar videodb" ou similar:

1. Instalar SDK

pip install "videodb[capture]" python-dotenv

Se videodb[capture] falhar no Linux, instale sem o extra capture:

pip install videodb python-dotenv

2. Configurar chave de API

O usuário deve definir VIDEO_DB_API_KEY usando um dos métodos:

Exportar no terminal (antes de iniciar o Gemini): export VIDEO_DB_API_KEY=sua-chave
Arquivo .env do projeto: Salve VIDEO_DB_API_KEY=sua-chave no arquivo .env do projeto

Obtenha uma chave de API gratuita em console.videodb.io (50 uploads gratuitos, sem cartão de crédito).

NÃO leia, escreva ou manipule a chave de API você mesmo. Sempre deixe o usuário defini-la.

Referência Rápida

Upload de mídia

# URL
video = coll.upload(url="https://exemplo.com/video.mp4")

# YouTube
video = coll.upload(url="https://www.youtube.com/watch?v=VIDEO_ID")

# Arquivo local
video = coll.upload(file_path="/caminho/para/video.mp4")

Transcrição + legenda

# force=True ignora o erro se o vídeo já estiver indexado
video.index_spoken_words(force=True)
text = video.get_transcript_text()
stream_url = video.add_subtitle()

Pesquisar dentro de vídeos

from videodb.exceptions import InvalidRequestError

video.index_spoken_words(force=True)

# search() gera InvalidRequestError quando nenhum resultado é encontrado.
# Sempre envolva em try/except e trate "Nenhum resultado encontrado" como vazio.
try:
    results = video.search("demonstração do produto")
    shots = results.get_shots()
    stream_url = results.compile()
except InvalidRequestError as e:
    if "No results found" in str(e):
        shots = []
    else:
        raise

Pesquisa de cena

import re
from videodb import SearchType, IndexType, SceneExtractionType
from videodb.exceptions import InvalidRequestError

# index_scenes() não tem parâmetro force — ele gera um erro se um índice
# de cena já existir. Extraia o ID do índice existente do erro.
try:
    scene_index_id = video.index_scenes(
        extraction_type=SceneExtractionType.shot_based,
        prompt="Descreva o conteúdo visual nesta cena.",
    )
except Exception as e:
    match = re.search(r"id\s+([a-f0-9]+)", str(e))
    if match:
        scene_index_id = match.group(1)
    else:
        raise

# Use score_threshold para filtrar ruído de baixa relevância (recomendado: 0.3+)
try:
    results = video.search(
        query="pessoa escrevendo em um quadro branco",
        search_type=SearchType.semantic,
        index_type=IndexType.scene,
        scene_index_id=scene_index_id,
        score_threshold=0.3,
    )
    shots = results.get_shots()
    stream_url = results.compile()
except InvalidRequestError as e:
    if "No results found" in str(e):
        shots = []
    else:
        raise

Edição de linha do tempo

Importante: Sempre valide timestamps antes de construir uma linha do tempo:

start deve ser >= 0 (valores negativos são aceitos silenciosamente, mas produzem saída corrompida)
start deve ser < end
end deve ser <= video.length

from videodb.timeline import Timeline
from videodb.asset import VideoAsset, TextAsset, TextStyle

timeline = Timeline(conn)
timeline.add_inline(VideoAsset(asset_id=video.id, start=10, end=30))
timeline.add_overlay(0, TextAsset(text="Fim", duration=3, style=TextStyle(fontsize=36)))
stream_url = timeline.generate_stream()

Transcodificar vídeo (mudança de resolução/qualidade)

from videodb import TranscodeMode, VideoConfig, AudioConfig

# Mude resolução, qualidade ou proporção no lado do servidor
job_id = conn.transcode(
    source="https://exemplo.com/video.mp4",
    callback_url="https://exemplo.com/webhook",
    mode=TranscodeMode.economy,
    video_config=VideoConfig(resolution=720, quality=23, aspect_ratio="16:9"),
    audio_config=AudioConfig(mute=False),
)

Reenquadrar proporção (para plataformas sociais)

Aviso: reframe() é uma operação lenta no servidor. Para vídeos longos, pode levar vários minutos e pode expirar. Boas práticas:

Sempre limite a um segmento curto usando start/end quando possível
Para vídeos completos, use callback_url para processamento assíncrono
Apare o vídeo em uma Timeline primeiro, depois reenquadre o resultado mais curto

from videodb import ReframeMode

# Sempre prefira reenquadrar um segmento curto:
reframed = video.reframe(start=0, end=60, target="vertical", mode=ReframeMode.smart)

# Reenquadramento assíncrono para vídeos completos (retorna None, resultado via webhook):
video.reframe(target="vertical", callback_url="https://exemplo.com/webhook")

# Predefinições: "vertical" (9:16), "square" (1:1), "landscape" (16:9)
reframed = video.reframe(start=0, end=60, target="square")

# Dimensões personalizadas
reframed = video.reframe(start=0, end=60, target={"width": 1280, "height": 720})

Mídia generativa

image = coll.generate_image(
    prompt="um pôr do sol sobre montanhas",
    aspect_ratio="16:9",
)

Tratamento de erros

from videodb.exceptions import AuthenticationError, InvalidRequestError

try:
    conn = videodb.connect()
except AuthenticationError:
    print("Verifique sua VIDEO_DB_API_KEY")

try:
    video = coll.upload(url="https://exemplo.com/video.mp4")
except InvalidRequestError as e:
    print(f"Falha no upload: {e}")

Armadilhas comuns

Cenário	Mensagem de erro	Solução
Indexar um vídeo já indexado	`Spoken word index for video already exists`	Use `video.index_spoken_words(force=True)` para pular se já indexado
Índice de cena já existe	`Scene index with id XXXX already exists`	Extraia o `scene_index_id` existente do erro com `re.search(r"id\s+([a-f0-9]+)", str(e))`
Pesquisa não encontra correspondências	`InvalidRequestError: No results found`	Capture a exceção e trate como resultados vazios (`shots = []`)
Reenquadramento expira	Bloqueia indefinidamente em vídeos longos	Use `start`/`end` para limitar o segmento, ou passe `callback_url` para assíncrono
Timestamps negativos na linha do tempo	Produz silenciosamente um stream quebrado	Sempre valide `start >= 0` antes de criar `VideoAsset`
`generate_video()` / `create_collection()` falha	`Operation not allowed` ou `maximum limit`	Recursos limitados por plano — informe o usuário sobre os limites do plano

Exemplos

Prompts canônicos

"Inicie a captura de desktop e alerte quando um campo de senha aparecer."
"Grave minha sessão e produza um resumo acionável quando ela terminar."
"Ingira este arquivo e retorne um link de stream reproduzível."
"Indexe esta pasta e encontre cada cena com pessoas, retorne timestamps."
"Gere legendas, queime-as e adicione música de fundo suave."
"Conecte esta URL RTSP e alerte quando uma pessoa entrar na zona."

Gravação de Tela (Captura de Desktop)

Use ws_listener.py para capturar eventos WebSocket durante sessões de gravação. A captura de desktop suporta apenas macOS.

Início Rápido

Escolha o diretório de estado: STATE_DIR="${VIDEODB_EVENTS_DIR:-$HOME/.local/state/videodb}"
Inicie o listener: VIDEODB_EVENTS_DIR="$STATE_DIR" python scripts/ws_listener.py --clear "$STATE_DIR" &
Obtenha o ID WebSocket: cat "$STATE_DIR/videodb_ws_id"
Execute o código de captura (consulte reference/capture.md para o fluxo de trabalho completo)
Eventos gravados em: $STATE_DIR/videodb_events.jsonl

Use --clear sempre que iniciar uma nova execução de captura para que eventos de transcrição e visuais antigos não vazem para a nova sessão.

Consultar Eventos

import json
import os
import time
from pathlib import Path

events_dir = Path(os.environ.get("VIDEODB_EVENTS_DIR", Path.home() / ".local" / "state" / "videodb"))
events_file = events_dir / "videodb_events.jsonl"
events = []

if events_file.exists():
    with events_file.open(encoding="utf-8") as handle:
        for line in handle:
            try:
                events.append(json.loads(line))
            except json.JSONDecodeError:
                continue

transcripts = [e["data"]["text"] for e in events if e.get("channel") == "transcript"]
cutoff = time.time() - 300
recent_visual = [
    e for e in events
    if e.get("channel") == "visual_index" and e["unix_ts"] > cutoff
]

Documentação adicional

A documentação de referência está no diretório reference/ adjacente a este arquivo SKILL.md. Use a ferramenta Glob para localizá-la, se necessário.

reference/api-reference.md - Referência completa da API do Python SDK do VideoDB
reference/search.md - Guia aprofundado de pesquisa de vídeo (palavra falada e baseada em cena)
reference/editor.md - Edição de linha do tempo, assets e composição
reference/streaming.md - Streaming HLS e reprodução instantânea
reference/generative.md - Geração de mídia com IA (imagens, vídeo, áudio)
reference/rtstream.md - Fluxo de trabalho de ingestão de stream ao vivo (RTSP/RTMP)
reference/rtstream-reference.md - Métodos do SDK RTStream e pipelines de IA
reference/capture.md - Fluxo de trabalho de captura de desktop
reference/capture-reference.md - SDK de captura e eventos WebSocket
reference/use-cases.md - Padrões e exemplos comuns de processamento de vídeo

Não use ffmpeg, moviepy ou ferramentas de codificação locais quando o VideoDB suportar a operação. Todos os seguintes são tratados no lado do servidor pelo VideoDB: corte, combinação de clipes, sobreposição de áudio ou música, adição de legendas, sobreposições de texto/imagem, transcodificação, mudanças de resolução, conversão de proporção, redimensionamento para requisitos de plataforma, transcrição e geração de mídia. Recorra a ferramentas locais apenas para operações listadas em Limitações em reference/editor.md (transições, mudanças de velocidade, corte/zoom, correção de cor, mixagem de volume).

Quando usar o quê

Problema	Solução VideoDB
A plataforma rejeita a proporção ou resolução do vídeo	`video.reframe()` ou `conn.transcode()` com `VideoConfig`
Precisa redimensionar vídeo para Twitter/Instagram/TikTok	`video.reframe(target="vertical")` ou `target="square"`
Precisa mudar a resolução (ex: 1080p → 720p)	`conn.transcode()` com `VideoConfig(resolution=720)`
Precisa sobrepor áudio/música no vídeo	`AudioAsset` em uma `Timeline`
Precisa adicionar legendas	`video.add_subtitle()` ou `CaptionAsset`
Precisa combinar/cortar clipes	`VideoAsset` em uma `Timeline`
Precisa gerar narração, música ou efeitos sonoros	`coll.generate_voice()`, `generate_music()`, `generate_sound_effect()`

Procedência

O material de referência para esta skill é armazenado localmente em skills/videodb/reference/. Use as cópias locais acima em vez de seguir links de repositórios externos em tempo de execução.

Perguntar na sua IA favorita

Documentação