Skill VideoDB
Percepção + memória + ações para vídeo, streams ao vivo e sessões de área de trabalho.
Use esta skill quando precisar de:
Quando usar
- Você precisa de percepção de vídeo ou áudio, indexação, pesquisa ou edição de linha do tempo a partir de arquivos, URLs, sessões de área de trabalho ou streams ao vivo.
- A tarefa envolve timestamps, evidências pesquisáveis, legendas, clips, sobreposições ou alertas de monitoramento em tempo real.
- Você deseja um único fluxo de trabalho que combine ingestão, compreensão, recuperação e ações de mídia.
1) Percepção de área de trabalho
- Iniciar/parar uma sessão de área de trabalho capturando tela, microfone e áudio do sistema
- Transmitir contexto ao vivo e armazenar memória de sessão episódica
- 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
2) 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 de aspecto
3) Indexar + pesquisar (timestamps + evidências)
- Construir índices visual, falado e de palavras-chave
- Pesquisar e retornar momentos exatos com timestamps e evidência reproduzível
- Criar automaticamente clips a partir dos resultados da pesquisa
4) Edição de linha do tempo + geração
- Legendas: gerar, traduzir, incorporar
- Sobreposições: texto/imagem/marca, legendas animadas
- Áudio: música de fundo, locução, dublagem
- Composição programática e exportações via operações de linha do tempo
5) 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
Entradas comuns
- Caminho de arquivo local, URL pública ou URL RTSP
- Solicitação de captura de área de trabalho: 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 clip, edições de linha do tempo, regras de alerta
Saídas comuns
- URL do stream
- Resultados da pesquisa com timestamps e links de evidência
- Ativos gerados: legendas, áudio, imagens, clips
- Payloads de evento/alerta para streams ao vivo
- Resumos de sessão de área de trabalho e entradas de memória
Prompts canônicos (exemplos)
- "Inicie a captura de área de trabalho e alerte quando um campo de senha aparecer."
- "Grave minha sessão e produza um resumo acionável quando terminar."
- "Ingira este arquivo e retorne um link de stream reproduzível."
- "Indexe esta pasta e encontre todas as cenas com pessoas, retorne os timestamps."
- "Gere legendas, incorpore-as e adicione música de fundo leve."
- "Conecte esta URL RTSP e alerte quando uma pessoa entrar na zona."
Executando código Python
Antes de executar qualquer código 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á exportada)
- Arquivo
.envdo projeto no diretório atual
Se a chave estiver faltando, videodb.connect() levanta AuthenticationError automaticamente.
NÃO escreva um arquivo de script quando um comando inline curto funcionar.
Ao escrever Python inline (python -c "..."), use sempre código formatado corretamente — use ponto e vírgula para separar declarações e mantenha legível. Para qualquer coisa com mais de ~3 declaraçõ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 Claude):
export VIDEO_DB_API_KEY=sua-chave - Arquivo
.envdo projeto: SalveVIDEO_DB_API_KEY=sua-chaveno arquivo.envdo projeto
Obtenha uma chave de API gratuita em https://console.videodb.io (50 uploads gratuitos, sem cartão de crédito).
NÃO leia, escreva ou manuseie 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 pula 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() levanta 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 — levanta 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:
startdeve ser >= 0 (valores negativos são aceitos silenciosamente, mas produzem saída quebrada)startdeve ser <endenddeve 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="O 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 de aspecto no 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),
)
Reformatar proporção de aspecto (para plataformas sociais)
Aviso: reframe() é uma operação lenta no servidor. Para vídeos longos, pode levar
vários minutos e pode expirar. Melhores práticas:
- Sempre limite a um segmento curto usando
start/endquando possível - Para vídeos de duração completa, use
callback_urlpara processamento assíncrono - Apare o vídeo em um
Timelineprimeiro, depois reformate o resultado mais curto
from videodb import ReframeMode
# Sempre prefira reformatar um segmento curto:
reframed = video.reframe(start=0, end=60, target="vertical", mode=ReframeMode.smart)
# Reformatação assíncrona para vídeos de duração completa (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"Upload falhou: {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 = []) |
| Reformatação expira | Bloqueia indefinidamente em vídeos longos | Use start/end para limitar o segmento, ou passe callback_url para async |
| Timestamps negativos na Timeline | Produz silenciosamente um stream quebrado | Sempre valide start >= 0 antes de criar VideoAsset |
generate_video() / create_collection() falham | Operation not allowed ou maximum limit | Recursos limitados por plano — informe o usuário sobre os limites do plano |
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 SDK Python VideoDB
- reference/search.md - Guia aprofundado de pesquisa em vídeo (palavra falada e baseada em cena)
- reference/editor.md - Edição de linha do tempo, ativos 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 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 captura de área de trabalho
- reference/capture-reference.md - SDK de captura e eventos WebSocket
- reference/use-cases.md - Padrões e exemplos comuns de processamento de vídeo
Gravação de tela (captura de área de trabalho)
Use ws_listener.py para capturar eventos WebSocket durante sessões de gravação. A captura de área de trabalho suporta apenas macOS.
Início rápido
- Iniciar listener:
python scripts/ws_listener.py & - Obter ID WebSocket:
cat /tmp/videodb_ws_id - Executar código de captura (veja reference/capture.md para o fluxo completo)
- Eventos escritos em:
/tmp/videodb_events.jsonl
Consultar eventos
import json
events = [json.loads(l) for l in open("/tmp/videodb_events.jsonl")]
# Obter todas as transcrições
transcripts = [e["data"]["text"] for e in events if e.get("channel") == "transcript"]
# Obter descrições visuais dos últimos 5 minutos
import time
cutoff = time.time() - 300
recent_visual = [e for e in events
if e.get("channel") == "visual_index" and e["unix_ts"] > cutoff]
Scripts utilitários
- scripts/ws_listener.py - Listener de eventos WebSocket (despeja em JSONL)
Para o fluxo completo de captura, veja reference/capture.md.
Não use ffmpeg, moviepy ou ferramentas de codificação local quando o VideoDB suportar a operação. Os seguintes são todos tratados no servidor pelo VideoDB — corte, combinação de clips, 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 de aspecto, 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 |
|---|---|
| Plataforma rejeita proporção de aspecto 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 resolução (ex.: 1080p → 720p) | conn.transcode() com VideoConfig(resolution=720) |
| Precisa sobrepor áudio/música no vídeo | AudioAsset em um Timeline |
| Precisa adicionar legendas | video.add_subtitle() ou CaptionAsset |
| Precisa combinar/cortar clips | VideoAsset em um Timeline |
| Precisa gerar locução, música ou SFX | coll.generate_voice(), generate_music(), generate_sound_effect() |
Repositório
https://github.com/video-db/skills
Mantido por: VideoDB
Limitações
- Use esta skill apenas quando a tarefa corresponder claramente ao escopo descrito acima.
- Não trate a saída como substituta para validação específica de ambiente, testes ou revisão especializada.
- Pare e peça esclarecimentos se entradas necessárias, permissões, limites de segurança ou critérios de sucesso estiverem faltando.