WeCut

O que WeCut faz?

wecut renderiza um projeto JSON em MP4 (ou GIF) usando o FFmpeg instalado nesta máquina. Você descreve a edição; WeCut faz o trabalho de vídeo. Nunca chama um serviço de rede.

Se wecut não estiver no PATH, use npx -y wecut (Node 16+) no lugar em todos os comandos abaixo. Se WeCut estiver conectado como um servidor MCP, os mesmos passos são as ferramentas wecut_doctor, wecut_probe, wecut_validate, wecut_preview (retorna os quadros como imagens), wecut_render, wecut_list, wecut_schema, wecut_example, wecut_analyze (retorna a folha de quadros como uma imagem), wecut_recipe_list, wecut_recipe_show, wecut_recipe_apply e wecut_recipe_from_project; passe um projeto como project (objeto) ou projectFile (caminho).

Fluxo de trabalho

1. Verifique a máquina uma vez: wecut doctor. Se relatar FFmpeg ausente, siga sua dica (por exemplo, sudo apt-get install -y ffmpeg).
2. Coloque a mídia no diretório de trabalho. Cada caminho em um projeto é relativo à pasta de onde você executa wecut (ou --root DIR). URLs são recusados: baixe os arquivos primeiro.
3. Examine a mídia: wecut probe media/fala.mp4 media/musica.mp3 fornece duração, tamanho, fps e se há áudio. Use esses números para from/to.
4. Escreva projeto.json (formato abaixo). wecut example podcast-clip imprime um exemplo completo; wecut schema imprime o Esquema JSON; wecut list mostra todos os estilos, fontes, transições e nomes de filtros.
5. Valide: wecut validate projeto.json. Erros retornam com um ponteiro JSON (/clipes/0/to) e uma dica. Corrija e repita.
6. Veja antes de renderizar: wecut preview projeto.json --at 0.5,3,10 escreve pequenos quadros JPG em out/preview/. Abra-os e verifique enquadramento, tamanho do texto e posição da legenda.
7. Renderize: wecut render projeto.json. Use --preset draft para uma verificação rápida em 540p, o padrão final para entrega.

Cada comando imprime um objeto JSON. Códigos de saída: 0 ok, 2 entrada inválida, 3 dependência ausente, 4 falha na renderização, 5 acima de um limite. Você pode canalizar um projeto com wecut render -.

Formato do projeto

{
  "wecut": "1",
  "output": { "file": "out/clipe-01.mp4", "ratio": "9:16", "res": 1080, "fps": 30 },
  "clipes": [
    { "src": "media/fala.mp4", "from": 754.2, "to": 781.0, "focus": { "x": 0.42, "y": 0.5 } },
    { "src": "media/fala.mp4", "from": 795.5, "to": 812.0, "zoom": 1.15 }
  ],
  "textos": [
    { "text": "Como fiz meus primeiros $10k", "start": 0, "end": 3, "style": "hook", "y": 0.2, "in": { "type": "pop" } }
  ],
  "legendas": { "words": "media/fala.words.json", "src": "media/fala.mp4", "style": "karaoke" },
  "audio": [ { "src": "media/musica.mp3", "volume": 25, "loop": true, "duck": true, "fadeOut": 1.5 } ]
}

Regras importantes:

• Dois relógios. from/to do clipe são segundos do arquivo de origem. Todo o resto (textos, overlays, audio.at, filtros, efeitos) são segundos do vídeo finalizado. wecut validate imprime a duração finalizada.
• Transições sobrepõem. Uma transição no clipe N mescla no clipe N+1 e encurta o vídeo pela sua duração.
• Enquadramento. O fit padrão é cover (preencher e cortar). Direcione o corte com focus (0..1; x 0.3 mantém o lado esquerdo) e zoom. Use "fit": "contain" com "background": "blur" para mostrar o quadro inteiro.
• Posições são frações da tela, 0.5 é o centro. O size da fonte é em pixels em 1080p.
• Imagens usam duração (padrão 3) e podem ter movimento: in, out, left, right, up, down.
• Emoji não são desenhados em texto. Coloque-os em um PNG e use overlays.

Legendas

Forneça ao WeCut uma transcrição com tempos de palavras e ele constrói legendas:

• words: um caminho .json, .srt ou .vtt, ou uma matriz inline [{"word": "oi", "start": 0.1, "end": 0.4}]. verbose_json do OpenAI/Groq e JSON do whisper.cpp são lidos como estão.
• src: defina isso para o vídeo ao qual a transcrição pertence. Então a transcrição mantém os tempos próprios do arquivo de origem, e o WeCut move cada palavra para a linha do tempo de saída através de cada clipe cortado desse arquivo (velocidade incluída). Sem src, os tempos já devem ser tempos de saída.
• style: classic, yellow, box-black, box-white, bold, comic, shadow (uma frase por vez), karaoke, karaoke-green (palavra falada acende), pop (uma palavra grande por vez).

Se precisar de uma transcrição: wecut doctor relata local_transcription: true quando este FFmpeg tem o filtro Whisper. Caso contrário, use qualquer conversão de fala para texto que você já tenha e salve seus tempos de palavras como JSON.

Modelos: copie o que funciona

Uma receita é a forma de uma edição sem seu conteúdo: seções (por exemplo, um gancho de 5 s com um cartão de título, depois a fala), slots de texto, estilo de legenda e música, efeitos. Aplicá-la a novos clipes, palavras e música gera um projeto.

1. Analise um vídeo que funcionou: wecut analyze media/viral.mp4 retorna tomadas e ritmo, cortes nos primeiros 3 s, flashes, andamento, pausas, um final de plataforma silencioso (deixe-o de fora), e sheet: um quadro por tomada em uma única imagem. Olhe a folha para o cartão de título, estilo de texto, enquadramento e estilo de legenda.
2. Escolha ou escreva uma receita: wecut recipe list (embutidas: news-headline, news-headline-blur, quote-hook, vlog-phrases, podcast-punch, photo-slideshow, além de recipes/*.json do diretório de trabalho). wecut recipe show <nome> lista seus papéis e slots de texto. Para escrever uma, siga wecut recipe schema.
3. Aplique-a:

{
  "recipe": "news-headline",
  "clipes": [
    { "src": "media/broll.mp4", "role": "hook" },
    { "src": "media/fala.mp4", "from": 120, "to": 165 }
  ],
  "textos": { "label": { "text": "Nome da página" }, "headline": { "text": "A alegação em uma linha", "emphasis": ["alegação"] } },
  "transcript": "media/fala.words.json",
  "write": "projetos/clipe-01.json"
}

wecut recipe apply --input requisicao.json (ou --input - com o JSON em stdin) verifica tudo e salva o projeto; então preview e renderize ele. Clipes sem papel alimentam body; uma seção sem clipes pega emprestado o início da filmagem da próxima.

4. Salve sua própria: wecut recipe from-project projetos/clipe-01.json --name meu-estilo --write recipes/meu-estilo.json mantém seções, transições, slots de texto, estilo de legenda, efeitos e a música como faixa padrão.

Música: uma receita pode carregar sua própria faixa (music.src), usada por padrão como a música em um modelo CapCut. Passe "music": "media/musica.mp3" (ou um vídeo, cujo som é usado) para substituí-la, ou "none". Uma música tirada de um vídeo de outra pessoa pode ser silenciada pela plataforma após o upload; adicionar um som trend no aplicativo ao postar evita isso.

Copie a estrutura, não o conteúdo: filmagem, palavras exatas e música de outros criadores permanecem deles.

Criando vários clipes de um vídeo longo

1. wecut probe na origem e obtenha uma transcrição com tempos de palavras.
2. Leia a transcrição e escolha os momentos (você decide; WeCut não julga conteúdo).
3. Escreva um projeto por clipe, cada um com captions.src apontando para a origem para que uma transcrição sirva a todos os clipes.
4. wecut preview em um deles, ajuste focus, então wecut render em cada um.

Solução de problemas

• E_RANGE: to está além do final do arquivo. Use wecut probe para a duração real.
• E_PATH: o caminho está fora do diretório de trabalho ou é uma URL.
• E_MEDIA: o arquivo não é um vídeo, imagem ou áudio legível, ou o tipo errado para aquele campo (música em clipes, vídeo em overlays).
• E_DEPENDENCY: FFmpeg ausente, mais antigo que 6, ou compilado sem libass. Execute wecut doctor.
• Renderização muito lenta: --preset draft, um output.res menor, ou menos clipes por projeto. render_seconds e realtime_factor no resultado informam a velocidade nesta máquina.
• Para ver exatamente o que o FFmpeg executará: wecut render projeto.json --dry-run.