Uso de Vídeo
Princípios
- O LLM raciocina a partir da transcrição bruta + visuais sob demanda. O único artefato derivado que merece ser mantido é uma transcrição compacta em nível de frase (
takes_packed.md). Todo o resto — marcação de hesitações, detecção de retakes, classificação de cenas, pontuação de ênfase — você deriva no momento da decisão. - Áudio é primário, visuais seguem. Candidatos a corte vêm de limites de fala e lacunas de silêncio. Aprofunde-se nos visuais apenas nos pontos de decisão.
- Pergunte → confirme → execute → itere → persista. Nunca toque no corte até que o usuário tenha confirmado a estratégia em inglês claro.
- Generalize. Não presuma que tipo de vídeo é este. Olhe para o material, pergunte ao usuário, então edite.
- Liberdade artística é o padrão. Cada valor, preset, fonte, cor, duração, estrutura de tom e técnica específicos neste documento são um exemplo prático de um vídeo comprovado — não uma ordem. Leia-os para entender o que é possível e por que cada um funcionou. Então tome suas próprias decisões de gosto com base no que o material realmente é e no que o usuário realmente quer. As únicas coisas que VOCÊ DEVE fazer estão na seção Regras Rígidas abaixo. Todo o resto é seu.
- Invente livremente. Se o material pedir uma técnica não descrita aqui — tela dividida, picture-in-picture, cartões de identidade de terço inferior, cortes de reação, rampas de velocidade, congelamento de quadros, crossfades, match cuts, L-cuts, J-cuts, rampas de velocidade sobre respirações, o que quer que seja — crie. Os ajudantes são ffmpeg e PIL. Eles podem fazer qualquer coisa que o formato suporte. Não espere permissão.
- Verifique sua própria saída antes de mostrá-la ao usuário. Se você não a enviaria, não a apresente.
Regras Rígidas (correção de produção — inegociáveis)
Estas são as coisas onde o desvio produz falhas silenciosas ou saída quebrada. Elas não são gosto, são correção. Memorize-as.
- As legendas são aplicadas por ÚLTIMO na cadeia de filtros, depois de cada sobreposição. Caso contrário, as sobreposições escondem as legendas. Falha silenciosa.
- Extração por segmento → concatenação com
-c copysem perdas, não filtro de passagem única. Caso contrário, você codifica cada segmento duas vezes quando as sobreposições são adicionadas. - Fade de áudio de 30ms em cada limite de segmento (
afade=t=in:st=0:d=0.03,afade=t=out:st={dur-0.03}:d=0.03). Caso contrário, estalos audíveis em cada corte. - Sobreposições usam
setpts=PTS-STARTPTS+T/TBpara deslocar o quadro 0 da sobreposição para o início da sua janela. Caso contrário, você vê o meio da animação durante a janela de sobreposição. - O SRT mestre usa deslocamentos da linha do tempo de saída:
output_time = word.start - segment_start + segment_offset. Caso contrário, as legendas desalinham após a concatenação do segmento. - Nunca corte dentro de uma palavra. Encaixe cada borda de corte em um limite de palavra da transcrição Scribe.
- Acrescente margem a cada borda de corte. Janela de trabalho: 30–200ms. Os timestamps do Scribe variam 50–100ms — a margem absorve a variação. Mais apertado para ritmo acelerado, mais folgado para cinematográfico.
- Apenas ASR literal em nível de palavra. Nunca modo SRT/frase (perde dados de lacuna de submilissegundo). Nunca hesitações normalizadas (perde sinal editorial).
- Armazene em cache as transcrições por fonte. Nunca retranscreva a menos que o próprio arquivo de origem tenha mudado.
- Subagentes paralelos para múltiplas animações. Nunca sequenciais. Crie N de uma vez via ferramenta
Agent; o tempo total de parede é aproximadamente o mais lento. - Confirmação da estratégia antes da execução. Nunca toque no corte até que o usuário tenha aprovado o plano em inglês claro.
- Todas as saídas da sessão em
<videos_dir>/edit/. Nunca escreva dentro do diretório do projetovideo-use/.
Todo o resto neste documento é um exemplo prático. Desvie sempre que o material pedir.
Estrutura de Diretórios
O skill reside em video-use/. As filmagens do usuário ficam onde ele as colocar. Todas as saídas da sessão vão para <videos_dir>/edit/.
<videos_dir>/
├── <arquivos de origem, intactos>
└── edit/
├── project.md ← memória; anexado a cada sessão
├── takes_packed.md ← transcrições em nível de frase, a visão de leitura primária do LLM
├── edl.json ← decisões de corte
├── transcripts/<nome>.json ← JSON Scribe bruto em cache
├── animations/slot_<id>/ ← fonte + renderização + raciocínio por animação
├── clips_graded/ ← extratos por segmento com correção de cor + fades
├── master.srt ← legendas da linha do tempo de saída
├── downloads/ ← saídas do yt-dlp
├── verify/ ← quadros de depuração / PNGs da linha do tempo
├── preview.mp4
└── final.mp4
Configuração
A instalação inicial reside em install.md (clone, dependências, ffmpeg, registro do skill, chave da API). Não o execute novamente a cada sessão; na inicialização a frio, apenas verifique:
ELEVENLABS_API_KEYresolve — seja no ambiente ou em.envna raiz do repositório video-use. Se estiver faltando, peça ao usuário para colar uma e escreva-a em.env(nunca no<videos_dir>do usuário).ffmpeg+ffprobeno PATH.- Dependências Python instaladas (
uv syncoupip install -e .dentro do repositório). - Node.js + npm disponíveis se a sessão precisar de slots HyperFrames ou Remotion. HyperFrames atualmente requer Node.js 22+
yt-dlp, HyperFrames, Remotion, Manim instalados apenas no primeiro uso.- A configuração de animação de primeiro uso acontece dentro do diretório do slot, nunca na raiz do repositório video-use. HyperFrames pode ser invocado com
npx --yes hyperframes ...; Remotion pode ser esboçado comnpx create-video@latestou instalado como uma dependência local do projeto antes de usar seu comandoremotion render. - Este skill fornece
skills/manim-video/. Leia seu SKILL.md ao construir um slot Manim.
Ajudantes (helpers/transcribe.py, helpers/render.py, etc.) residem ao lado deste SKILL.md. Resolva seus caminhos relativos ao diretório que contém este arquivo — o skill é tipicamente vinculado simbolicamente em ~/.claude/skills/video-use/ ou ~/.codex/skills/video-use/.
Ajudantes
transcribe.py <vídeo>— chamada Scribe de arquivo único.--num-speakers Nopcional. Em cache.transcribe_batch.py <videos_dir>— transcrição paralela com 4 trabalhadores. Use para múltiplas tomadas.pack_transcripts.py --edit-dir <dir>—transcripts/*.json→takes_packed.md(em nível de frase, quebra em silêncio ≥ 0.5s).timeline_view.py <vídeo> <início> <fim>— tira de filme + PNG de forma de onda. Aprofundamento visual sob demanda. Não é uma ferramenta de varredura — use-a em pontos de decisão, não constantemente.render.py <edl.json> -o <saída>— extração por segmento → concatenação → sobreposições (PTS-deslocadas) → legendas POR ÚLTIMO.--previewpara 720p rápido.--build-subtitlespara gerar master.srt embutido.grade.py <entrada> -o <saída>— cadeia de filtros ffmpeg para correção de cor. Presets +--filter '<raw>'para personalizado.
Para animações, crie <edit>/animations/slot_<id>/ com Bash e crie um subagente via ferramenta Agent.
O Processo
-
Inventário.
ffprobeem cada fonte.transcribe_batch.pyno diretório.pack_transcripts.pypara produzirtakes_packed.md. Amostre um ou doistimeline_views para uma primeira impressão visual. -
Pré-varredura para problemas. Uma passada sobre
takes_packed.mdpara notar escorregões verbais, erros de fala óbvios ou frases a evitar. Lista simples, alimente o briefing do editor. -
Converse. Descreva o que você vê em inglês claro. Faça perguntas moldadas pelo material. Colete: tipo de conteúdo, duração/proporção alvo, direção estética/de marca, sensação de ritmo, momentos a preservar, momentos a cortar, preferências de animação e correção de cor, necessidades de legenda. Não use uma lista de verificação fixa — as perguntas certas são diferentes a cada vez.
-
Proponha estratégia. 4–8 frases: forma, escolhas de tomada, direção de corte, plano de animação, direção de correção de cor, estilo de legenda, estimativa de duração. Aguarde confirmação.
-
Execute. Produza
edl.jsonvia o briefing do subagente editor. Aprofunde-se emtimeline_viewem momentos ambíguos. Construa animações em subagentes paralelos. Aplique correção de cor por segmento. Componha viarender.py. -
Pré-visualização.
render.py --preview. -
Autoavaliação (antes de mostrar ao usuário). Execute
timeline_viewna saída renderizada (não nas fontes) em cada limite de corte (janela de ±1.5s). Verifique cada imagem para:- Descontinuidade visual / flash / salto no corte
- Pico de forma de onda no limite (estalo de áudio que escapou do fade de 30ms)
- Legenda escondida atrás de uma sobreposição (violação da Regra 1)
- Sobreposição desalinhada ou mostrando quadros errados (violação da Regra 4)
Amostre também: primeiros 2s, últimos 2s e 2–3 pontos médios — verifique consistência da correção de cor, legibilidade das legendas, coerência geral. Execute
ffprobena saída para verificar se a duração corresponde à expectativa do EDL.Se algo falhar: corrija → re-renderize → reavalie. Limite a 3 passadas de autoavaliação — se problemas persistirem após 3, sinalize-os ao usuário em vez de loop infinito. Apresente a pré-visualização apenas se a autoavaliação for aprovada.
-
Itere e persista. Feedback em linguagem natural, replaneje, re-renderize. Nunca retranscreva. Renderização final na confirmação. Acrescente a
project.md.
Técnicas de Corte
- Áudio primeiro. Cortes candidatos de limites de palavra e lacunas de silêncio.
- Preserve picos. Risadas, punchlines, batidas de ênfase. Estenda além das punchlines para incluir reações — a risada É a batida.
- Transições de falantes se beneficiam de ar entre as falas. Valores comuns: 400–600ms. Menos para ritmo acelerado, mais para cinematográfico. Decisão de gosto.
- Eventos de áudio como sinais.
(risos),(suspiros),(aplausos)marcam batidas. Estenda além deles. - Lacunas de silêncio são candidatas a corte. Silêncios ≥400ms são geralmente os mais limpos. Limites de frase de 150–400ms são utilizáveis com uma verificação visual. <150ms é inseguro (meio da frase).
- Exemplo de margem de corte (o vídeo de lançamento enviado com este): 50ms antes da primeira palavra mantida, 80ms após a última. Mais apertado para energia de montagem, mais folgado para documentário. Fique na janela de trabalho de 30–200ms (Regra Rígida 7).
- Nunca raciocine áudio e vídeo independentemente. Cada corte deve funcionar em ambas as faixas.
A Transcrição Compacta (visão de leitura primária)
pack_transcripts.py lê todos os transcripts/*.json e produz um arquivo markdown onde cada tomada é uma lista de linhas em nível de frase, cada uma prefixada com seu intervalo de tempo [início-fim]. As frases quebram em qualquer silêncio ≥ 0.5s OU mudança de falante. Este é o artefato que o subagente editor lê para escolher cortes — ele dá precisão de limite de palavra a partir apenas do texto com 1/10 dos tokens do JSON bruto.
Exemplo de linha:
## C0103 (duração: 43.0s, 8 frases)
[002.52-005.36] S0 Noventa por cento do que um agente web faz é completamente desperdiçado.
[006.08-006.74] S0 Nós corrigimos isso.
Briefing do Subagente Editor (para seleção de múltiplas tomadas)
Quando a tarefa for "escolher a melhor tomada de cada batida em vários clipes", crie um subagente dedicado com um briefing moldado assim. A estrutura é fundamental; o exemplo de formato de tom não é.
Você está editando um vídeo de <tipo>. Escolha a melhor tomada de cada batida e
monte-as cronologicamente por batida, não pela ordem do clipe de origem.
ENTRADAS:
- takes_packed.md (transcrições em nível de frase anotadas com tempo de todas as tomadas)
- Contexto do produto/narrativa: <2 frases do usuário>
- Falante(s): <nome, papel, nota de estilo de entrega>
- Estrutura esperada: <escolha um arquétipo ou invente um>
- Escorregões verbais a evitar: <lista da passada de pré-varredura>
- Tempo de execução alvo: <segundos>
Arquétipos estruturais comuns (escolha, adapte ou invente):
- Lançamento técnico / demonstração: GANCHO → PROBLEMA → SOLUÇÃO → BENEFÍCIO → EXEMPLO → CTA
- Tutorial: INTRODUÇÃO → CONFIGURAÇÃO → PASSOS → ARMADILHAS → RECAP
- Entrevista: (PERGUNTA → RESPOSTA → ACOMPANHAMENTO) repetir
- Viagem / evento: CHEGADA → DESTAQUES → MOMENTOS TRANQUILOS → PARTIDA
- Documentário: TESE → EVIDÊNCIA → CONTRAPONTO → CONCLUSÃO
- Música / performance: INTRODUÇÃO → VERSO → REFRÃO → PONTE → FINAL
- Ou invente o seu próprio.
REGRAS:
- Os tempos de início/fim devem cair em limites de palavra da transcrição.
- Adicione margem aos limites de corte (janela de trabalho 30–200ms).
- Prefira silêncios ≥ 400ms como alvos de corte.
- Escorregões inevitáveis são mantidos se não houver tomada melhor. Anote-os em "motivo".
- Se acima do orçamento, revise: descarte uma batida ou apare caudas. Relate o total e autocorrija-se.
SAÍDA (array JSON, sem prosa):
[{"source": "C0103", "start": 2.42, "end": 6.85, "beat": "GANCHO",
"quote": "...", "motivo": "..."}, ...]
Retorne o EDL final e uma verificação de tempo de execução total em uma linha.
Correção de Cor (quando solicitada)
Seu trabalho é raciocinar sobre a imagem, não aplicar um preset. Olhe para um quadro (via timeline_view), decida o que está errado, ajuste uma coisa, olhe novamente.
O modelo mental é ASC CDL. Por canal: saída = (entrada * inclinação + deslocamento) ^ potência, então saturação global. inclinação → realces, deslocamento → sombras, potência → meios-tons.
Exemplos de cadeias de filtros (grade.py tem --list-presets; use-os como pontos de partida ou misture os seus próprios):
warm_cinematic— retrô/técnico, divisão teal/laranja sutil, dessaturado. Enviado em um vídeo de lançamento real. Seguro para talking heads.neutral_punch— corretivo mínimo: aumento de contraste + curva S suave. Sem mudanças de matiz.none— cópia direta. Padrão quando o usuário não pediu.
Para qualquer outra coisa — retratos, natureza, produto, videoclipe, documentário — invente sua própria cadeia. grade.py --filter '<ffmpeg bruto>' aceita qualquer string de filtro.
Regras rígidas: aplique por segmento durante a extração (não após a concatenação, que recodifica duas vezes). Nunca seja agressivo sem testar tons de pele.
Legendas (quando solicitadas)
As legendas têm três dimensões que valem a pena raciocinar: agrupamento (1/2/3/frase por linha), caixa (MAIÚSCULO/Título/Natural) e posicionamento (margem do fundo). A combinação certa depende do conteúdo.
Estilos trabalhados — escolha, adapte ou invente:
bold-overlay — lançamento técnico curto, redes sociais de ritmo acelerado. Agrupamentos de 2 palavras, MAIÚSCULO, quebra em pontuação, Helvetica 18 Negrito, branco com contorno, MarginV=35. render.py vem com isso como SUB_FORCE_STYLE.
FontName=Helvetica,FontSize=18,Bold=1,
PrimaryColour=&H00FFFFFF,OutlineColour=&H00000000,BackColour=&H00000000,
BorderStyle=1,Outline=2,Shadow=0,
Alignment=2,MarginV=35
natural-sentence (se você inventar este modo) — narrativa, documentário, educação. Agrupamentos de 4–7 palavras, caixa de frase, quebra em pausas naturais, MarginV=60–80, fonte maior
...
[truncado para tradução]