O que llvideo faz?
Você não consegue assistir a um vídeo. Um modelo nativo para vídeo consegue. Este skill coloca um desses modelos atrás de uma CLI, faz com que ele retorne evidências estruturadas em vez de prosa, e então entrega a você quadros reais para que forme seu próprio julgamento.
Essa distinção é o ponto central. Se você retransmitir o resumo de um modelo, você é um intermediário. Se você raciocinar sobre um índice tipado e confirmá-lo contra pixels que você mesmo olhou, você é o analista.
Verificação de configuração
llvideo providers
Requer ffmpeg no PATH e uma chave de API. GEMINI_API_KEY lida com tudo. OPENROUTER_API_KEY custa cerca de metade do preço, mas não tem endpoint de upload, então funciona apenas com URLs e clipes pequenos — e o OpenRouter exige $1,00 em crédito comprado antes de aceitar qualquer requisição de vídeo, inclusive em modelos :free.
As chaves são lidas primeiro do ambiente. Como fallback, ele também lê um arquivo KEY=valor em ~/.itachi-api-keys, que é apenas uma conveniência para manter chaves fora do seu perfil de shell — as variáveis de ambiente são suficientes.
O ciclo que você deve seguir
1. Sempre comece de graça
llvideo probe VIDEO # duração, codec, resolução, estimativa de tokens — não custa nada
llvideo plan VIDEO # quanto vai custar e como será tratado — não custa nada
plan informa a taxa de amostragem, se uma transcodificação é necessária, a contagem de tokens e a estimativa em dólares. Leia antes de gastar.
2. Indexe o vídeo
llvideo index VIDEO
llvideo index VIDEO --json # para processamento
llvideo index VIDEO --verify 3 # quando o texto na tela for importante — veja abaixo
Retorna cenas com timestamps, texto na tela, ações, fala, momentos-chave e uma lista explícita de incertezas. Também escreve uma folha de contato.
3. OLHE A FOLHA DE CONTATO. Esta etapa não é opcional.
A saída do index termina com um caminho. Leia essa imagem com sua própria visão antes de responder ao usuário. É uma imagem cobrindo toda a linha do tempo por aproximadamente 600–1.600 tokens. Você é barato para se fundamentar e caro para estar errado.
Tudo que você afirmar deve ser uma destas coisas:
- algo que você mesmo viu em um quadro,
- uma medição do ffmpeg, ou
- uma citação da transcrição.
Qualquer outra coisa deve ser atribuída: "o índice informa…". Nunca lave um palpite de modelo como se fosse sua própria voz.
4. Aprofunde-se onde for necessário
llvideo clip VIDEO --start 02:10 --end 02:40 --fps 4 -q "o logotipo anima suavemente?"
llvideo stills VIDEO --at 02:14,02:19 --width 1920 # resolução total, olhe você mesmo
llvideo sheet VIDEO --at 01:00,01:05,01:10 --tile 768 --cols 2 # texto de UI denso
O corte é exato ao quadro e custa algumas centenas de tokens. Use-o livremente.
A melhor visão para compreensão — timeline
llvideo timeline VIDEO
llvideo timeline VIDEO --transcribe # temporização exata das palavras
index retorna scenes, speech e audio_events como três arrays separados. Cada um é preciso, mas nada os conecta — então "um close-up do painel" e "ele diz que o alcance está errado" estão em listas diferentes, e o fato de acontecerem ao mesmo momento fica para você reconstruir.
Essa coocorrência é o contexto. Um plano significa algo diferente dependendo do que está sendo dito sobre ele. timeline entrelaça tudo em uma única trilha:
00:10-00:18 (8.0s) *KEY*
shot close-up de frente para o motorista
see A câmera retorna ao motorista enquanto um posto de gasolina iluminado desliza pela janela
does O veículo passa sob a cobertura iluminada
says "O posto de gasolina aparece aos nove segundos do clipe."
hear Zumbido ambiente baixo do interior do carro
why A cobertura do posto de gasolina passa diretamente atrás do motorista
Use isto em vez de index sempre que a pergunta for sobre significado, e não sobre inventário.
--transcribe funde uma transcrição local no nível de palavras em vez da fala do modelo. Os timestamps de áudio do modelo flutuam cerca de um segundo, o que é suficiente para atribuir uma linha ao plano errado em um corte rápido. A fala é atribuída ao trecho de tempo que ela mais sobrepõe, não ao primeiro que toca, então uma linha que atravessa um corte cai onde foi mais falada.
Ele informa a cobertura e nomeia qualquer trecho de tempo sobre o qual nada foi dito. Uma linha do tempo com buracos perdeu algo, e dizer isso é melhor do que apresentar um relato parcial como completo.
Perguntas de acompanhamento são gratuitas
O índice é armazenado em cache por 48 horas, baseado na identidade do conteúdo e nas configurações de amostragem. Medido: uma segunda timeline no mesmo vídeo foi de 12,5s e $0,02 para 0,4s e nada. Faça quantas perguntas precisar — iterar é como a compreensão é construída, e não deve custar nada após a primeira passagem. --no-cache força uma execução nova.
Reparando o que você encontrou — fix
A maioria dos achados de auditoria não precisa de nada regenerado. Loudness incorreta, um pico cortado, um quadro preto no início ou no final — são operações determinísticas do ffmpeg que não custam nada e não podem alucinar.
llvideo audit render.mp4 # encontre
llvideo fix render.mp4 # repare -> render_fixed.mp4
Reparados automaticamente: loudness integrada (dois passos loudnorm para −14 LUFS), clipe de pico verdadeiro (limitado a −1,0 dBFS), e quadros pretos ou brancos no primeiro/último — aparados medindo onde o preto realmente termina, não assumindo uma contagem de quadros.
Deliberadamente NÃO reparados, cada um com uma razão declarada:
| achado | por que não |
|---|---|
| lacuna preta no meio da linha do tempo | uma decisão de edição, não um defeito a ser silenciosamente deletado |
| congelamento | um quadro fixo pode ser intencional — encurte-o na linha do tempo |
| baixa resolução | upscaling inventa detalhes que nunca foram capturados |
| margem de segurança | layout é uma escolha de composição; mova o elemento, não corte |
| duração / aspecto | definido no momento da renderização; cortar para caber cortaria conteúdo |
fix refaz a auditoria depois e informa contagens antes/depois, porque afirmar que um reparo funcionou sem remedir é o hábito que esta ferramenta existe para quebrar. Medido em um render deliberadamente quebrado: 5 principais + 1 menor tornaram-se 1 principal + 1 menor, e os dois que sobraram foram os dois que precisam de uma decisão humana.
Ele nunca sobrescreve a fonte. A saída vai para <nome>_fixed.mp4 a menos que você passe --out.
Gerando clipes suplementares — gen
Clipes curtos que se encaixam em uma linha do tempo construída em outro lugar: um plano de estabelecimento, b-roll, textura, um logotipo. Não filmes completos.
llvideo gen "aproximação aérea lenta sobre uma floresta de pinheiros coberta de névoa ao amanhecer" --seconds 5
llvideo gen "logotipo se acomoda no quadro" --image logo.png --seconds 3 # imagem para vídeo
llvideo gen "mesma cena, tom mais frio" --video clip.mp4 --seconds 5 # vídeo para vídeo
llvideo gen-image "cartão de título de madeira envelhecida" --out title.png
Roda no Grok Imagine através da sua chave XAI_API_KEY existente. Observe que é o Grok da xAI, não o Groq — empresas diferentes. 1 a 15 segundos em passos de um segundo, o que é mais flexível do que os 4/6/8 fixos do Veo.
| resolução | custo medido |
|---|---|
| 480p | $0,05/s |
| 720p | $0,07/s |
| 1080p | ~$0,11/s (extrapolado, não medido) |
Essas taxas vieram do campo de uso da própria API em trabalhos reais, não da documentação. Qualquer coisa acima de $1,00 precisa de --yes.
Cada clipe é auditado na chegada, e isso não é decoração. Os próprios padrões do Grok produzem 848x480 a cerca de -21 LUFS — ambos sinalizados pelo auditor. gen padroniza para 720p por esse motivo. Depois, olhe você mesmo:
llvideo sheet clip.mp4
--audio alterna para grok-imagine-video-1.5, que gera uma trilha sonora. O áudio gerado tende a vir baixo; espere um achado de loudness e normalize na pós-produção se o clipe for ficar junto de outro material.
Auditando um vídeo que você FEZ — spec + --from-project
Este é o ciclo completo. HyperFrames, brag e Remotion já sabem o que pretendiam construir, então ninguém deve escrever uma especificação de intenção manualmente:
llvideo audit render.mp4 --from-project ./meu-projeto-hyperframes
llvideo audit brag-output/brag.mp4 --from-project ./brag-output
llvideo audit out.mp4 --from-project ./meu-projeto-remotion
Ou extraia a especificação sozinha para inspecioná-la ou editá-la:
llvideo spec ./project --out intent.json
De onde vem a intenção, e o quanto confiar nela:
| Fonte | O que é extraído | Confiança |
|---|---|---|
index.html do HyperFrames | início/fim de cena de data-start / data-duration, texto na tela do DOM | exata |
STORYBOARD.md do HyperFrames | tipo e duração da transição por quadro (transition_in) | intenção autoral |
| brag | lê o projeto HyperFrames que ele constrói em composition/; verifica a contagem de cenas e total do brag-plan.md | exata + verificação cruzada |
Remotion .tsx | <Sequence from= durationInFrames=> ÷ fps; <TransitionSeries.Transition presentation=> | exata para literais e N * fps; valores computados são pulados, não adivinhados |
Qualquer coisa que não possa ser lida estaticamente é relatada como uma nota, não assumida — uma duração springTiming ou um from={computeIt()} é sinalizado e excluído.
Por que isso existe. O check do HyperFrames valida a linha do tempo de composição buscada no Chrome headless. O portão de entrega do brag para em capturas de tela pré-renderização. Remotion não tem nenhum portão equivalente. Nenhum deles olha para o MP4 exportado, então um bug de codificador, um render desatualizado ou quadros perdidos na exportação são enviados despercebidos. Essa lacuna é o que isto preenche — e é por isso que audit vale a pena ser executado mesmo quando as verificações próprias do projeto passam.
Um fade para preto que a especificação pediu não é relatado como um defeito de quadro preto. Apenas preto não declarado é um achado.
Transições, câmera e ritmo — craft
Para "como é este corte", "que transições são usadas", "analise a edição", "o que a câmera está fazendo", "por que isso parece rápido" — use craft, não index.
llvideo craft VIDEO
llvideo craft VIDEO -q "o corte aos 00:14 cai no ritmo?"
index amostra o vídeo inteiro a 1 fps, o que é bom para o que acontece e inútil para como é editado: um corte seco ocupa um único quadro, então a 1 fps você vê os planos de cada lado e nunca a transição. craft funciona de forma diferente:
- Uma passagem local gratuita pontua cada quadro e encontra transições candidatas. Isso capta mesclas suaves que um detector normal não consegue — um crossfade de 1 segundo pica em torno de 0,025, enquanto a detecção de cena dispara em 0,12.
- Cada candidato é então reexaminado a 8 fps em uma janela estreita, para que o modelo veja a transição acontecer quadro a quadro.
- O brilho através de cada janela é medido com ffmpeg, que é o que separa um fade-through-black de um crossfade. Sem isso, o modelo chama um fade-to-black de crossfade; com isso, correto.
Retorna lista de planos (tamanho, movimento de câmera, composição), lista de transições (tipo, duração exata, por que o corte funciona ali), estatísticas de ritmo, cor e iluminação.
Verificado contra um vídeo com transições conhecidas — 4/4 tipos corretos, durações dentro de 0,2s:
| construído | detectado |
|---|---|
| corte seco, instantâneo | hard_cut, instantâneo |
| crossfade, 1,0s | crossfade, 1,0s |
| fade-to-black, 0,6s | fade_to_black, 0,5s |
| wipe para a esquerda, 0,8s | wipe, 0,63s |
E em uma tomada contínua de mão contendo um whip pan, ele reportou corretamente um plano e zero transições, em vez de inventar um corte.
Um movimento de câmera não é um corte. Um whip pan, tilt rápido ou rack focus parecem exatamente com uma edição em baixas taxas de quadros. craft é construído para distingui-los; index não. Se a pergunta é sobre edição, use craft.
Bandeiras: --zoom-fps 12 para cortes muito rápidos · --max-windows 12 para edições mais movimentadas · --no-zoom para pular a passagem fechada (mais barata, muito menos precisa).
Texto na tela é o modo de falha. Leve-o a sério.
Um modelo lerá texto borrado com confiança e errará. Medido em filmagem real — o mesmo painel de carro com desfoque de movimento, perguntado três vezes:
chamada 1: "642" "55 F" "330 mi"
chamada 2: "23.9" "65 F" "330"
chamada 3: "6:42" "55 F" "330 mi"
Nada em nenhuma resposta única sinaliza o problema. Portanto, não confie em uma única resposta:
llvideo index VIDEO --verify 3
Isso executa a consulta três vezes e relata quais leituras são estáveis (idênticas a cada execução) e quais são INSTÁVEIS. Trate leituras instáveis como "um display está presente, mas não legível". Se uma leitura instável for importante, exporte um quadro estático em resolução total e leia você mesmo:
llvideo stills VIDEO --at 00:11 --width 1920
Use --verify 3 sempre que a resposta for usada para ação: mensagens de erro em uma gravação de tela, números em um painel, código na tela, preços, nomes. Cada execução extra custa aproximadamente o mesmo que a primeira — centavos.
Auditando um render — audit
Depois de fazer um vídeo (Remotion, HyperFrames, brag, ffmpeg, Veo), você nunca o viu. Verifique antes de enviar:
llvideo audit out.mp4 # apenas verificações gratuitas medidas
llvideo audit out.mp4 --craft # mais transições e câmera
llvideo audit out.mp4 --spec intent.json # mais um diff contra o que foi pedido
As verificações gratuitas capturam os bugs que realmente são enviados. Sem modelo, sem tokens, sem rede:
- quadro preto ou branco no primeiro/último — o defeito de exportação mais comum, um erro de um para mais ou para menos na linha do tempo
- lacunas pretas e trechos congelados dentro do corpo
- loudness EBU R128 e corte de pico verdadeiro, contra o alvo de -14 LUFS da plataforma
- lacunas de silêncio, e "a trilha de áudio está efetivamente vazia"
- taxa de quadros, resolução, bitrate declarados vs. implícitos
- detalhes claros pressionados contra a borda do quadro (dica de margem de segurança)
Verificado: captura 5 de 5 defeitos plantados deliberadamente, e retorna LIMPO com zero achados em filmagem profissional real. Não chama o lobo.
Cada achado diz se é medido (ffmpeg disse, com o número) ou julgado (um modelo acha). Nunca apresente um achado julgado como fato.
O código de saída é 1 apenas quando há um bloqueador, então funciona como um portão de CI.
Diferenciando contra a intenção
Escreva o que o vídeo deveria ser, depois diferencie:
{
"duration_seconds": 30,
"duration_tolerance": 0.5,
"aspect": "16:9",
"transitions": [
…
[truncado para tradução]