Uso de Vídeo
Princípio
- O LLM raciocina a partir da transcrição bruta + imagens sob demanda. O único artefato derivado que vale a pena é uma transcrição compactada em nível de frase (
takes_packed.md). Todo o resto — marcação de vícios de linguagem, detecção de retakes, classificação de planos, pontuação de ênfase — você deriva no momento da decisão. - O áudio é primário, as imagens seguem. Os candidatos a corte vêm de limites de fala e lacunas de silêncio. Aprofunde-se nas imagens 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 linguagem simples.
- Generalize. Não presuma que tipo de vídeo é este. Olhe para o material, pergunte ao usuário, depois edite.
- Liberdade artística é o padrão. Todo valor específico, preset, fonte, cor, duração, estrutura de tom e técnica neste documento é um exemplo trabalhado de um vídeo comprovado — não uma obrigação. Leia-os para entender o que é possível e por que cada um funcionou. Depois, faça suas próprias escolhas 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 exigir uma técnica não descrita aqui — tela dividida, quadro em quadro, cartões de identidade no terço inferior, cortes de reação, rampas de velocidade, congelamento de quadro, crossfades, match cuts, L-cuts, J-cuts, rampas de velocidade sobre respiração, etc. — construa-a. Os auxiliares são ffmpeg e PIL. Eles podem fazer tudo o que o formato suporta. Não espere permissão.
- Verifique sua própria saída antes de mostrá-la ao usuário. Se você não enviaria, não apresente.
Regras Rígidas (correção de produção — inegociável)
Estas são as coisas onde o desvio produz falhas silenciosas ou saída quebrada. Não são questão de gosto, são de correção. Memorize-as.
- As legendas são aplicadas por ÚLTIMO na cadeia de filtros, após cada sobreposição. Caso contrário, as sobreposições escondem as legendas. Falha silenciosa.
- Extraia por segmento → concatenação com
-c copysem perdas, não um filtergraph de passagem única. Caso contrário, você codifica cada segmento duas vezes quando as sobreposições são adicionadas. - Fades de áudio de 30ms em cada borda 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. - As sobreposições usam
setpts=PTS-STARTPTS+T/TBpara deslocar o quadro 0 da sobreposição para o início de 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 desalinhadas após a concatenação dos segmentos. - Nunca corte dentro de uma palavra. Ajuste cada borda de corte para um limite de palavra da transcrição do Scribe.
- Acolchoamento em cada borda de corte. Janela de trabalho: 30–200ms. Os timestamps do Scribe desviam 50–100ms — o acolchoamento absorve o desvio. Mais apertado para ritmo acelerado, mais solto para cinematográfico.
- ASR palavra por palavra, apenas. Nunca modo SRT/frase (perde dados de lacunas submilissegundo). Nunca normalize vícios de linguagem (perde sinal editorial).
- Cache de 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. Gere N de uma vez através da ferramenta
Agent; o tempo total de parede ≈ 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 linguagem simples.
- 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 trabalhado. Desvie sempre que o material exigir.
Layout do diretório
A skill reside em video-use/. O material do usuário fica onde ele o 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 principal visão de leitura do LLM
├── edl.json ← decisões de corte
├── transcripts/<nome>.json ← cache do JSON bruto do Scribe
├── animations/slot_<id>/ ← fonte + render + raciocínio por animação
├── clips_graded/ ← extrações por segmento com correção de cor + fades
├── master.srt ← legendas na 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 está em install.md (clone, deps, ffmpeg, registro da skill, chave de API). Nã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 ausente, 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 no 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 configurado comnpx create-video@latestou instalado como dependência local do projeto antes de usar o comandoremotion render. - Esta skill fornece
skills/manim-video/. Leia seu SKILL.md ao construir um slot Manim.
Auxiliares (helpers/transcribe.py, helpers/render.py, etc.) ficam ao lado deste SKILL.md. Resolva seus caminhos relativos ao diretório que contém este arquivo — a skill é geralmente um link simbólico em ~/.claude/skills/video-use/ ou ~/.codex/skills/video-use/.
Auxiliares
transcribe.py <vídeo>— chamada Scribe de arquivo único.--num-speakers Nopcional. Em cache.transcribe_batch.py <diretório_videos>— transcrição paralela com 4 workers. Use para múltiplas tomadas.pack_transcripts.py --edit-dir <dir>—transcripts/*.json→takes_packed.md(nível de frase, quebra em silêncio ≥ 0.5s).timeline_view.py <vídeo> <início> <fim>— filmstrip + waveform PNG. Aprofundamento visual sob demanda. Não é uma ferramenta de varredura — use-a nos pontos de decisão, não constantemente.render.py <edl.json> -o <saída>— extração por segmento → concatenação → sobreposições (deslocadas PTS) → legendas por ÚLTIMO.--previewpara 720p rápido.--build-subtitlespara gerar master.srt inline.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 gere um subagente através da 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 de problemas. Uma passada sobre
takes_packed.mdpara anotar escorregões verbais, erros de fala óbvios ou frases a evitar. Lista simples, alimente o briefing do editor. -
Converse. Descreva o que vê em linguagem simples. Faça perguntas moldadas pelo material. Colete: tipo de conteúdo, duração/proporção alvo, direção estética/marca, sensação de ritmo, momentos a preservar, momentos a cortar, preferências de animação e correção de cor, necessidades de legendas. Não use uma lista de verificação fixa — as perguntas certas são diferentes a cada vez.
-
Proponha estratégia. 4–8 frases: formato, 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.jsonatravés do briefing do subagente editor. Aprofunde-se notimeline_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 borda 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)
Também amostre: primeiros 2s, últimos 2s e 2–3 pontos intermediários — verifique consistência da correção de cor, legibilidade da legenda, coerência geral. Execute
ffprobena saída para verificar se a duração corresponde à expectativa da EDL.Se algo falhar: corrija → re-renderize → reavalie. Limite-se a 3 passadas de autoavaliação — se problemas persistirem após 3, sinalize-os ao usuário em vez de entrar em loop infinito. Apresente a pré-visualização apenas quando a autoavaliação for aprovada.
-
Itere + persista. Feedback em linguagem natural, replaneje, re-renderize. Nunca retranscreva. Renderização final após confirmação. Anexe a
project.md.
Técnicas de corte
- Áudio primeiro. Candidatos a corte a partir de limites de palavra e lacunas de silêncio.
- Preserve picos. Risadas, punchlines, batidas de ênfase. Estenda após punchlines para incluir reações — a risada É a batida.
- Transições de falante 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 após eles. - Lacunas de silêncio são candidatos a corte. Silêncios ≥400ms são geralmente os mais limpos. Limites de frase entre 150–400ms são utilizáveis com verificação visual. <150ms é inseguro (meio de frase).
- Exemplo de acolchoamento de corte (o vídeo de lançamento que acompanhou isto): 50ms antes da primeira palavra mantida, 80ms após a última. Mais apertado para energia de montagem, mais solto para documentário. Mantenha-se na janela de trabalho de 30–200ms (Regra Rígida 7).
- Nunca raciocine áudio e vídeo independentemente. Todo corte deve funcionar em ambas as trilhas.
A transcrição compactada (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 — fornece precisão de limite de palavra apenas a partir 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", gere um subagente dedicado com um briefing moldado como este. A estrutura é importante; o exemplo de formato de tom é apenas um exemplo.
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 com anotação de tempo de todas as tomadas)
- Contexto do produto/narrativa: <2 frases do usuário>
- Falante(s): <nome, função, nota sobre estilo de entrega>
- Estrutura esperada: <escolha um arquétipo ou invente um>
- Escorregões verbais a evitar: <lista da passada de pré-varredura>
- Duração alvo: <segundos>
Arquétipos estruturais comuns (escolha, adapte ou invente):
- Lançamento técnico / demo: GANCHO → PROBLEMA → SOLUÇÃO → BENEFÍCIO → EXEMPLO → CTA
- Tutorial: INTRODUÇÃO → CONFIGURAÇÃO → PASSOS → PEGADINHAS → RECAP
- Entrevista: (PERGUNTA → RESPOSTA → COMPLEMENTO) repita
- 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 horários de início/fim devem cair em limites de palavra da transcrição.
- Acolchoamento das bordas 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: remova uma batida ou apare as caudas. Relate o total e autocorrija.
SAÍDA (array JSON, sem prosa):
[{"source": "C0103", "start": 2.42, "end": 6.85, "beat": "GANCHO",
"quote": "...", "reason": "..."}, ...]
Retorne a EDL final e uma verificação de duração total de 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: out = (in * slope + offset) ** power, depois saturação global. slope → realces, offset → sombras, power → tons médios.
Exemplos de cadeias de filtros (grade.py tem --list-presets; use-os como pontos de partida ou misture os seus):
warm_cinematic— retro/técnico, divisão sutil teal/laranja, dessaturado. Enviado em um vídeo de lançamento real. Seguro para cabeças falantes.neutral_punch— corretivo mínimo: aumento de contraste + curva S suave. Sem alterações de matiz.none— cópia direta. Padrão quando o usuário não solicitou.
Para qualquer outra coisa — retratos, natureza, produto, videoclipe, documentário — invente sua própria cadeia. grade.py --filter '<raw ffmpeg>' aceita qualquer string de filtro.
Regras rígidas: aplique por segmento durante a extração (não pós-concatenação, que re-codifica duas vezes). Nunca seja agressivo sem testar tons de pele.
Legendas (quando solicitadas)
As legendas têm três dimensões sobre as quais vale a pena raciocinar: agrupamento (1/2/3/frase por linha), caixa (UPPER/Title/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 de formato curto, social de ritmo acelerado. Agrupamento de 2 palavras, MAIÚSCULAS, quebra em pontuação, Helvetica 18 Negrito, branco com contorno, MarginV=35. render.py já inclui este 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.