browser-use/video-use

Video Use

Princípio

1. O LLM raciocina a partir da transcrição bruta + elementos visuais sob demanda. O único artefato derivado que realmente se justifica é uma transcrição compactada em nível de frase (takes_packed.md). Todo o resto — marcação de preenchimentos, detecção de retomadas, classificação de tomadas, pontuação de ênfase — você deriva no momento da decisão.
2. O áudio é primário, o visual segue. Os candidatos a corte vêm de limites de fala e lacunas de silêncio. Aprofunde-se no visual apenas nos pontos de decisão.
3. Pergunte → confirme → execute → itere → persista. Nunca toque no corte até que o usuário tenha confirmado a estratégia em inglês simples.
4. Generalize. Não presuma que tipo de vídeo é este. Observe o material, pergunte ao usuário e então edite.
5. Liberdade artística é o padrão. Cada valor específico, predefinição, fonte, cor, duração, estrutura de tom e técnica neste documento é um exemplo prático 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, 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.
6. Inove livremente. Se o material exigir uma técnica não descrita aqui — tela dividida, picture-in-picture, cartões de identificação de terço inferior, cortes de reação, rampas de velocidade, congelamento de quadro, crossfades, match cuts, L-cuts, J-cuts, rampas de velocidade sobre a respiração, o que for — construa-a. Os ajudantes são ffmpeg e PIL. Eles podem fazer tudo o que o formato suportar. Não espere permissão.
7. Verifique seu próprio resultado antes de mostrá-lo ao usuário. Se você não o enviaria, não o 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. Não são gosto, são correção. Memorize-as.

1. As legendas são aplicadas por ÚLTIMO na cadeia de filtros, após cada sobreposição. Caso contrário, as sobreposições ocultam as legendas. Falha silenciosa.
2. Extração por segmento → concatenação com -c copy sem perdas, não um único filtergraph. Caso contrário, você codifica novamente cada segmento quando as sobreposições são adicionadas.
3. Fades 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.
4. As sobreposições usam setpts=PTS-STARTPTS+T/TB para 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.
5. 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 desalinharão após a concatenação do segmento.
6. Nunca corte dentro de uma palavra. Ajuste cada borda de corte para um limite de palavra da transcrição do Scribe.
7. Acolchoamento de cada borda de corte. Janela de trabalho: 30–200ms. Os carimbos de data/hora do Scribe têm deriva de 50–100ms — o acolchoamento absorve a deriva. Mais apertado para ritmo acelerado, mais folgado para cinematográfico.
8. Apenas ASR literal em nível de palavra. Nunca modo SRT/frase (perde dados de lacuna de submilissegundo). Nunca preenchimentos normalizados (perde sinal editorial).
9. Armazene em cache as transcrições por fonte. Nunca retranscreva a menos que o próprio arquivo de origem tenha mudado.
10. Subagentes paralelos para múltiplas animações. Nunca sequencial. Gere N de uma vez através da ferramenta Agent; o tempo total de parede ≈ o mais lento.
11. 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.
12. Todas as saídas da sessão em <videos_dir>/edit/. Nunca escreva dentro do diretório do projeto video-use/.

Todo o resto neste documento é um exemplo prático. Desvie sempre que o material assim o exigir.

Layout do diretório

A 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, intocados>
└── 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/<name>.json ← JSON Scribe bruto em cache
    ├── 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 da linha do tempo de saída
    ├── downloads/              ← saídas 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 da skill, chave de API). Não a execute novamente a cada sessão; na inicialização a frio, apenas verifique:

• ELEVENLABS_API_KEY resolve — seja no ambiente ou no .env na 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 + ffprobe no PATH.
• Dependências Python instaladas (uv sync ou pip 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 da 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 estruturado com npx create-video@latest ou instalado como uma dependência local do projeto antes de usar seu comando remotion render.
• Esta skill fornece skills/manim-video/. Leia seu SKILL.md ao construir um slot Manim.

Ajudantes (helpers/transcribe.py, helpers/render.py, etc.) residem junto a este SKILL.md. Resolva seus caminhos relativos ao diretório que contém este arquivo — a skill é tipicamente um link simbólico em ~/.claude/skills/video-use/ ou ~/.codex/skills/video-use/.

Ajudantes

• transcribe.py <video> — chamada Scribe de arquivo único. --num-speakers N opcional. 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 (nível de frase, quebra em silêncio ≥ 0,5s).
• timeline_view.py <video> <start> <end> — 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 <out> — extração por segmento → concatenação → sobreposições (deslocadas por PTS) → legendas por ÚLTIMO. --preview para 720p rápido. --build-subtitles para gerar master.srt inline.
• grade.py <in> -o <out> — cadeia de filtros ffmpeg para correção de cor. Predefinições + --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

1. Inventário. ffprobe em cada fonte. transcribe_batch.py no diretório. pack_transcripts.py para produzir takes_packed.md. Amostre uma ou duas timeline_views para uma primeira impressão visual.

2. Pré-varredura para problemas. Uma passagem por takes_packed.md para notar escorregões verbais, erros de fala óbvios ou frases a evitar. Lista simples, alimente o briefing do editor.

3. Conversa. Descreva o que você vê em linguagem simples. Faça perguntas moldadas pelo material. Colete: tipo de conteúdo, comprimento/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.

4. Proponha estratégia. 4–8 frases: forma, escolhas de tomada, direção de corte, plano de animação, direção de cor, estilo de legenda, estimativa de duração. Aguarde confirmação.

5. Execute. Produza edl.json através do briefing do subagente editor. Aprofunde-se em timeline_view em momentos ambíguos. Construa animações em subagentes paralelos. Aplique a correção de cor por segmento. Componha via render.py.

6. Pré-visualização. render.py --preview.

7. Autoavaliação (antes de mostrar ao usuário). Execute timeline_view no resultado renderizado (não nas fontes) em cada limite de corte (janela de ±1,5s). Verifique cada imagem para:

   • Descontinuidade visual / flash / salto no corte
   • Pico na forma de onda no limite (estalo de áudio que passou pelo fade de 30ms)
   • Legenda oculta 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 médios — verifique consistência da correção de cor, legibilidade da legenda, coerência geral. Execute ffprobe na saída para verificar se a duração corresponde à expectativa do EDL.

   Meça o áudio, não presuma: ffmpeg -i out.mp4 -af ebur128=peak=true -f null - para sonoridade integrada e pico verdadeiro, além de RMS por seção (diálogo, apenas música, cartão final). Um cartão final 15 dB abaixo do diálogo, ou efeitos mais altos que a fala, é um bug. Você não pode ouvir: diga isso e relate os números.

   Para qualquer coisa que o usuário publicará (lançamento, promoção, anúncio), também gere um subagente crítico com o arquivo renderizado, o EDL e quaisquer vídeos de referência que o usuário forneceu. Dê a ele a tarefa de criticar, não de elogiar: um veredito, problemas classificados com timecodes e evidências (quadros, níveis) e as 5 correções a fazer primeiro. Olhos novos captam o que o autor parou de ver — linhas de payoff cortadas, memes de 0,5s, texto de 28px ilegível no tamanho de um telefone.

   Se algo falhar: corrija → re-renderize → reavalie. Limite a 3 passagens de autoavaliação — se os problemas persistirem após 3, sinalize-os ao usuário em vez de loop infinito. Apresente a pré-visualização apenas quando a autoavaliação passar.

8. Itere + persista. Feedback em linguagem natural, replaneje, re-renderize. Nunca retranscreva. Renderização final na confirmação. Anexe a project.md.

Arte do corte (técnicas)

• Primeiro o áudio. Cortes candidatos a partir de limites de palavra e lacunas de silêncio.
• Preserve os picos. Risadas, piadas, batidas de ênfase. Estenda para além das piadas para incluir reações — a risada É a batida.
• As transições entre 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 para 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 acolchoamento 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 solto para documentário. Permaneça 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 faixas.

A transcrição compactada (principal visão de leitura)

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 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 Ninety percent of what a web agent does is completely wasted.
  [006.08-006.74] S0 We fixed this.

Briefing do subagente editor (para seleção de múltiplas tomadas)

Quando a tarefa é "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 não é.

Você está editando um vídeo <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 passagem de pré-varredura>
  - Tempo de execução alvo: <segundos>

Arquétipos estruturais comuns (escolha, adapte ou invente):
  - Lançamento de tecnologia / demonstração: GANCHO → PROBLEMA → SOLUÇÃO → BENEFÍCIO → EXEMPLO → CTA
  - Tutorial: INTRODUÇÃO → CONFIGURAÇÃO → PASSOS → PEGADINHAS → RECAPITULAÇÃO
  - 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 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 "razão".
  - Se acima do orçamento, revise: remova uma batida ou apare as caudas. Relate o total e autocorrija-se.

SAÍDA (array JSON, sem prosa):
  [{"source": "C0103", "start": 2.42, "end": 6.85, "beat": "GANCHO",
    "quote": "...", "reason": "..."}, ...]

Retorne o EDL final e uma verificação de tempo de execução total de uma linha.

Correção de cor (quando solicitada)

Seu trabalho é raciocinar sobre a imagem, não aplicar uma predefinição. 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-as como pontos de partida ou misture as suas próprias):

• warm_cinematic — retrô/técnico, divisão sutil de teal/laranja, 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 solicitou.

Para qualquer outra coisa — retrato, 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 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/… [truncado na tradução para manter a consistência com o original truncado])