Bruto para Shorts: edite seus takes em final.mp4

freecut

Princípio

1. O LLM raciocina a partir da transcrição bruta + recursos visuais sob demanda. O único artefato derivado que vale a pena manter é uma transcrição compactada no nível da frase (takes_packed.md). Todo o resto — marcação de preenchimento, detecção de retomada, classificação de tomadas, pontuação de ênfase — você deriva no momento da decisão.
2. O áudio é primário, os recursos visuais seguem. Os candidatos a corte vêm de fronteiras de fala e lacunas de silêncio. Aprofunde-se nos recursos visuais 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 claro.
4. Generalize. Não presuma que tipo de vídeo é este. Observe o material, pergunte ao usuário e então edite.
5. A 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, faça suas próprias escolhas de gosto com base no que o material realmente é e no que o usuário realmente deseja. As únicas coisas que você DEVE fazer estão na seção Regras Rígidas abaixo. Todo o resto é seu.
6. Invente livremente. Se o material exigir uma técnica não descrita aqui — tela dividida, imagem sobre imagem, cartões de identidade no terço inferior, cortes de reação, rampas de velocidade, quadros congelados, crossfades, cortes de correspondência, L-cuts, J-cuts, rampas de velocidade sobre a respiração, seja o que for — construa-a. Os ajudantes são ffmpeg e PIL. Eles podem fazer qualquer coisa que o formato suporte. Não espere permissão.
7. Verifique sua própria saída antes de mostrá-la ao usuário. Se você não a publicaria, 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. Não são gosto, são correção. Memorize-as.

1. 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.
2. Extração por segmento → concatenação lossless -c copy, não filtergraph de passe único. Caso contrário, você codifica duas vezes 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 ficam desalinhadas 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.
7. Acrescente margem a cada borda de corte. Janela de trabalho: 30–200ms. Os carimbos de data/hora do ASR variam 50–100ms — a margem absorve a variação. Mais apertada para ritmo acelerado, mais solta para cinematográfico.
8. ASR palavra por palavra apenas. 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 sido alterado.
10. Subagentes paralelos para múltiplas animações. Nunca sequenciais. Crie 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 inglês claro.
12. Todas as saídas da sessão em <videos_dir>/edit/. Nunca escreva dentro do diretório do projeto freecut/.

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

Layout do diretório

A habilidade reside em freecut/. A filmagem do usuário reside onde ele a 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 no nível da frase, a principal visão de leitura do LLM
    ├── edl.json                 ← decisões de corte
    ├── transcripts/<nome>.json  ← JSON ASR normalizado em cache
    ├── animations/slot_<id>/    ← por animação: fonte + renderização + raciocínio
    ├── clips_graded/            ← extrações por segmento com gradação + 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, deps, ffmpeg, registro de habilidade, chave de API). Não a execute novamente a cada sessão; na inicialização a frio, apenas verifique:

• O backend de transcrição está disponível. O padrão é whisper (grátis, local) — verifique se mlx-whisper (Apple Silicon) ou faster-whisper é importável. Se nenhum estiver instalado, diga ao usuário para pip install mlx-whisper (ou faster-whisper) em vez de cair silenciosamente em um backend pago. Para os backends opcionais vibevoice / elevenlabs, verifique VIBEVOICE_ASR_URL / ELEVENLABS_API_KEY no ambiente ou .env na raiz do repositório freecut.
• 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 de animação no primeiro uso acontece dentro do diretório do slot, nunca na raiz do repositório freecut. HyperFrames pode ser invocado com npx --yes hyperframes ...; Remotion pode ser scaffolded com npx create-video@latest ou instalado como uma dependência local do projeto antes de usar seu comando remotion render.
• Esta habilidade fornece skills/manim-video/. Leia seu SKILL.md ao construir um slot Manim.

Ajudantes (helpers/transcribe.py, helpers/render.py, etc.) vivem ao lado deste SKILL.md. Resolva seus caminhos relativos ao diretório que contém este arquivo — a habilidade é tipicamente um link simbólico em ~/.claude/skills/freecut/ ou ~/.codex/skills/freecut/.

Ajudantes

• transcribe.py <vídeo> — transcrição de arquivo único. Backend plugável via --backend {whisper,vibevoice,elevenlabs} (padrão whisper, local + grátis, falante único). vibevoice usa VIBEVOICE_ASR_URL para diarização real; elevenlabs usa ELEVENLABS_API_KEY e suporta --num-speakers. Em cache.
• transcribe_batch.py <videos_dir> — transcrição paralela com 4 trabalhadores. Mesmo sinalizador --backend. 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 ou mudança de falante). Funciona de forma idêntica entre backends porque a forma do JSON é normalizada.
• 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 (deslocadas por PTS) → legendas por ÚLTIMO. --preview para 720p rápido. --build-subtitles para gerar master.srt embutido.
• grade.py <entrada> -o <saída> — cadeia de filtros ffmpeg de gradação. Predefinições + --filter '<bruto>' para personalizado.

Para animações, crie <edit>/animations/slot_<id>/ com Bash e crie 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 um ou dois timeline_views para uma primeira impressão visual.

2. Pré-varredura de problemas. Uma passada sobre takes_packed.md para observar lapsos verbais, erros de fala óbvios ou frases a evitar. Lista simples, alimente o resumo do editor.

3. 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/marca, sensação de ritmo, momentos a preservar, momentos a cortar, preferências de animação e gradação, 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 gradação, estilo de legenda, estimativa de duração. Aguarde confirmação.

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

6. Visualização. render.py --preview.

7. Autoavaliação (antes de mostrar ao usuário). Execute timeline_view na saída renderizada (não nas fontes) em cada limite de corte (janela de ±1,5s). Verifique cada imagem quanto a:

   • Descontinuidade visual / flash / salto no corte
   • Pico de forma de onda no limite (estalo de áudio que escapou do 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 de gradação, legibilidade de legenda, coerência geral. Execute ffprobe na saída para verificar se a duração corresponde à expectativa da EDL.

   Se algo falhar: corrija → renderize novamente → reavalie. Limite a 3 passadas de autoavaliação — se os problemas persistirem após 3, sinalize-os ao usuário em vez de fazer um loop infinito. Apenas apresente a visualização depois que a autoavaliação passar.

8. Itere + persista. Feedback em linguagem natural, replaneje, renderize novamente. Nunca retranscreva. Renderização final após confirmação. Anexe a project.md.

Arte do corte (técnicas)

• Áudio primeiro. Candidatos a corte de limites de palavra e lacunas de silêncio.
• Preserve picos. Riso, frases de efeito, batidas de ênfase. Estenda além das frases de efeito para incluir reações — o riso É a batida.
• Transferências 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 além delas.
• Lacunas de silêncio são candidatos 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 isso): 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. Cada corte deve funcionar em ambas as faixas.

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 no nível da 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 do texto sozinho 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.

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

Quando a tarefa é "escolher a melhor tomada de cada batida em vários clipes", crie um subagente dedicado com um resumo moldado assim. A estrutura é importante; o exemplo de forma de arremesso não é.

Você está editando um vídeo de <tipo>. Escolha a melhor tomada de cada batida e
disponha-as cronologicamente por batida, não pela ordem do clipe de origem.

ENTRADAS:
  - takes_packed.md (transcrições no nível da frase com anotações de tempo de todas as tomadas)
  - Contexto do produto/narrativa: <2 frases do usuário>
  - Falante(s): <nome, função, nota de estilo de entrega>
  - Estrutura esperada: <escolha um arquétipo ou invente um>
  - Erros de fala 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 / demo:   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 CALMOS → 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.
  - Acolchoar limites de corte (janela de trabalho 30–200ms).
  - Preferir silêncios ≥ 400ms como alvos de corte.
  - Erros 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 a EDL final e uma verificação de tempo de execução de uma linha.

Correção de cor (quando solicitado)

Seu trabalho é raciocinar sobre a imagem, não aplicar uma predefinição. Observe um quadro (via timeline_view), decida o que está errado, ajuste uma coisa, observe novamente.

O modelo mental é ASC CDL. Por canal: saída = (entrada * inclinação + deslocamento) ** potência, depois saturação global. inclinação → realces, deslocamento → sombras, potência → tons médios.

Cadeias de filtros de exemplo (grade.py tem --list-presets; use-as como pontos de partida ou misture as suas próprias):

• warm_cinematic — retrô/técnico, separação teal/laranja sutil, 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 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 '<ffmpeg bruto>' 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 solicitado)

As legendas têm três dimensões que valem a pena considerar: divisão em blocos (1/2/3/frase por linha), caixa (MAIÚSCULAS/Título/Natural) e posicionamento (margem a partir da base). A combinação certa depende do conteúdo.

Estilos testados — escolha, adapte ou invente:

• Tutorial (SHA/claro): 1–2 linhas, quebra de frase curta, maiúsculas naturais, margem de 8%. Limpo, baixo contraste, fácil de digitalizar. O conjunto de legendas do vídeo de lançamento foi fornecido.
• Entrevista (biográfico/macio): 1 linha por quadro, sem ancoragem (centralizado e com cerca de 10% de largura), caso natural. Cada fala é um slide — a borda mais suave é a melhor.
• Montagem (energética/compacta): 1–2 palavras por explosão, MAIÚSCULAS, margem inferior de 5%. Palavras piscam com as batidas. Efêmeras, estilizadas. A forma de onda de áudio é a grade de edição.
• Filme (cinematográfico): linhas longas, quebra de sentença inteira, caso natural, margem de 12%. As legendas são uma baliza inferior — não tentam chamar a atenção.

Regras de renderização: --build-subtitles e sempre último na cadeia (Regra Rígida 1). Para estilos personalizados, construa seu próprio pipeline de queima de legendas.

Animação (quando solicitado)

Padrão: sem animação por sobreposição. O processamento base do freecut é limpo e funcional, assim como cortar filme em uma moviola — não há animação embutida para estragar. A animação é um slot de sobreposição opcional que você cria explicitamente.

Cada slot de animação vive em seu próprio diretório slot_<id>/ com seu próprio agente, seu próprio diretório de trabalho e total liberdade para escolher sua estrutura. O agente principal fornece apenas: a janela de tempo (em segundos) que a animação deve preencher, o resumo do segmento que está anotando e qualquer orientação de estilo do usuário.

Ferramentas de animação disponíveis:

• HyperFrames (recomendado para animação generativa baseada em quadros-chave) — ferramenta de animação por código que renderiza esferas, gradientes deslizantes, logotipos girando e qualquer animação keyframed que você possa scriptar. npx --yes hyperframes <dir>.
• Remotion (quadros do React como vídeos) — use para animação pesada em UI, gráficos de barras, rolagem de código, telas de produtos. npx create-video@latest e remotion render.
• Manim (animação matemática) — para whiteboards explicativos, transformações geométricas, gráficos. Vendido com skills/manim-video/.
• ffmpeg — sobreposições manuais de imagem/texto com drawtext, overlay, zoompan, fade. Não requer dependências além do ffmpeg.

Invista alguns segundos em brainstorming de animação no início de um slot. Antes de se comprometer com uma estrutura, pegue uma imagem de amostra do segmento, descreva o que ela mostra e corresponda-a a uma técnica. Sempre:

1. Capturar um quadro de amostra do intervalo do segmento
2. Descrever a geometria da tela (horizontal, vertical, assento da janela?)
3. Decidir onde a animação deve viver (inferior, lateral, tela cheia)
4. Escolher a ferramenta com base na resposta

Regras de composição: se o segmento de vídeo subjacente for mais brilhante que um fundo de animação, a animação precisa de um fundo escuro ou borda de sombra. Se o vídeo for escuro, a animação precisa de texto claro ou arestas brilhantes. A sobreposição deve funcionar tanto no quadro estático quanto durante toda a sua duração.

Linkagem PTS: toda saída de slot deve ser um clipe de filme sem áudio, exatamente na duração da janela de tempo, codificado para corresponder ao codec de vídeo de origem (mesma resolução, taxa de quadros, pixel format, espaço de cor). O script de composição aplica setpts=PTS-STARTPTS+T/TB (onde T é o segundo de início do segmento) para colocar o quadro 0 da animação exatamente no início da janela. A saída do slot é então fornecida como uma entrada de sobreposição para render.py, que a mescla.

Gerenciamento de contexto e persistência

Limites de contexto são reais. Edições de vídeo podem produzir mais dados do que um LLM pode conter. Estratégias:

• project.md é o único estado persistente. Anexe a cada sessão. Se o contexto estiver cheio, leia o project.md existente e resuma a última sessão em ~500 tokens.
• Slots de animação são subagentes independentes. Cada um gerencia seus próprios ativos, compila e produz uma única saída de vídeo. O agente principal nunca precisa manter o estado de animação interno.
• HL = Histórico Longo. Em plataformas que suportam (Claude Code, Cursor), note-o como uma alternativa quando o contexto ficar cheio.
• transcrições em cache. Uma vez transcrito, nunca retranscreva a menos que o arquivo de origem mude. Os backends de ASR são a parte mais lenta do pipeline.
• EDL é um arquivo. Se o contexto estiver cheio, escreva edl.json, diga ao modelo para carregá-lo e continue.
• Intervalos de ferramentas grandes (Gemini 2M, GPT-4o 128K, Claude 200K). Se sua plataforma tiver um grande contexto, as animações ainda devem ser delegadas a subagentes, mas você pode manter mais transcrições e histórico de edição em linha.

Verificação e correção de bugs

• Use timeline_view para inspecionar limites de corte tanto nas fontes quanto na saída renderizada. Imagens mostram saltos de quadro e picos de forma de onda que o olho humano vê.
• Compare o tempo de execução da saída (de ffprobe) com a soma da EDL. Uma incompatibilidade >200ms significa um problema de concatenação.
• Verifique se as legendas SRT estão presentes e alinhadas: a última legenda deve terminar antes do fim do vídeo. Nenhuma legenda deve cruzar um limite de segmento.
• As animações devem ser renderizadas na mesma resolução/taxa de quadros da origem. Use ffprobe para verificar a compatibilidade.
• As sobreposições nunca devem cobrir a área de segurança de legendas (os 15% inferiores da altura do quadro para legendas posicionadas na base).
• Se a saída renderizada tiver um quadro preto no início: verifique se o primeiro segmento da EDL não tem um deslocamento de corte negativo que confunda o concatenador.
• Se a saída parecer congelada: verifique se setpts=PTS-STARTPTS+T/TB está sendo aplicado em todas as sobreposições. Uma sobreposição sem linkagem PTS aparecerá em um quadro em vez de durar toda a janela.
• Se o áudio falhar: verifique se os fades de 30ms não estão sobrepostos (se dois segmentos consecutivos têm fades de 30ms cada, o intervalo de silêncio total pode ser de 60ms, criando um clique audível). O render.py lida com isso; não ajuste manualmente.

---

Versão 1.0. Licenciado sob MIT.