Communitygithub.com

beatcut

Usado quando o usuário deseja cortar um vídeo curto a partir de uma pasta de clipes seguindo a batida de uma faixa musical, criar ou editar uma montagem sincronizada com a batida (shots.json), escolher pontos de entrada/saída dos clipes e contagens de batidas, ou renderizar um rascunho ou vídeo final com ffmpeg usando a ferramenta de linha de comando beatcut. Cobre todo o ciclo: inicializar um projeto, detectar a grade de batidas, permitir que o usuário escolha os takes no seletor local (ou edite shots.json manualmente), verificar, renderizar um rascunho, inspecioná-lo com uma folha de contato e renderizar o final somente após aprovação do usuário.

O que é beatcut?

O beatcut é uma ferramenta de linha de comando especializada em criar vídeos com cortes perfeitamente sincronizados com a batida de uma faixa musical. Ela organiza o estado em dois arquivos dentro de uma pasta de projeto: project.json (configurações) e shots.json (a edição). Suporta todo o fluxo de trabalho, desde a inicialização do projeto, detecção automática da grade de batidas, seleção interativa de takes via navegador (picker) ou edição manual do arquivo JSON, até a renderização de rascunhos e versões finais com ffmpeg. O beatcut é útil para produtores de conteúdo, editores de vídeo e desenvolvedores que desejam automatizar a criação de vídeos rítmicos sem precisar de softwares complexos de edição. A ferramenta funciona nos sistemas Windows (testado), Linux e macOS, e requer Python, ffmpeg e ffprobe no PATH. Ela detecta o andamento da música usando análise de BPM, permite ajustes manuais caso a detecção automática falhe, e oferece opções para transições, perfis de cor, e modos de ajuste (fit vs. cut). O usuário pode inspecionar o rascunho através de uma folha de contato gerada pela ferramenta e aprovar a renderização final, que otimiza a qualidade. O beatcut também gerencia erros e avisos detalhados para garantir que a edição esteja correta antes de renderizar.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/faruk76150/beatcut/tree/main

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que beatcut faz?

beatcut transforma uma pasta de clipes e um arquivo de música em um vídeo cujos cortes caem exatamente nas batidas, com precisão de quadro. O estado fica em dois arquivos na pasta do projeto: project.json (configurações) e shots.json (a edição). A ferramenta de linha de comando é beatcut.py.

Caminhos

Execute comandos com o Python que tem os requisitos instalados (pip install -r requirements.txt; ffmpeg e ffprobe devem estar no PATH). Use a pasta onde esta skill está instalada como pasta do repositório:

python <pasta da skill>/beatcut.py <comando> ...

Abaixo, beatcut.py significa esse caminho completo. Caminhos para clipes e projetos podem estar em qualquer lugar; coloque-os entre aspas se contiverem espaços. Um projeto é sempre <pasta dos clipes>/beatcut; todos os comandos, exceto init e sheet, recebem essa pasta de projeto.

Fluxo de trabalho

  1. Pergunte o que está faltando: a pasta de clipes, o arquivo de música e a forma de saída (padrão 1920x1080 para rascunho, 3840x2160 para final; tamanhos verticais como 1080x1920 são aceitáveis).
  2. Inicializar: beatcut.py init <pasta dos clipes> --music <arquivo de música>. Ele imprime created: <pasta> e copia a música para dentro do projeto. Se disser project.json already exists, o projeto existe; use-o e não reinicialize. Edite project.json se tamanhos, fill, fps, encoder, exclude_prefix ou profiles personalizados precisarem ser alterados (veja as regras abaixo).
  3. Batidas: beatcut.py beats <projeto>. Ele imprime period, t0 e bpm e os escreve em shots.json. A detecção assume um andamento constante e pode errar por alguns centésimos de segundo em t0. Se sair com código 1 e a mensagem fewer than 4 beats were detected, defina period e t0 manualmente (period = 60 / BPM; t0 = segundo da primeira batida). Informe os números ao usuário; eles podem corrigi-los no seletor.
  4. Escolher takes, de uma das formas:
    • Seletor (padrão). Inicie beatcut.py pick <projeto> em segundo plano (ele bloqueia até ser interrompido; abre o navegador a menos que você adicione --no-open; porta padrão 8765, altere com --port N). Informe ao usuário a URL que ele imprimiu, http://127.0.0.1:<port>/, e que a página salva automaticamente. Aguarde o usuário dizer que terminou, então pare o servidor (Ctrl+C ou encerre o processo em segundo plano) e leia shots.json. Não edite shots.json enquanto o seletor estiver aberto: a página sobrescreveria suas alterações.
    • Manualmente, quando o usuário pedir para construir a edição ou fornecer horários exatos. Siga as regras abaixo e execute check.
  5. Verificar: beatcut.py check <projeto>. Saída com código 0 e ok: <n> shots, <s> s significa nenhum erro; leia também os avisos (stderr). Corrija todos os erros antes de renderizar.
  6. Rascunho: beatcut.py draft <projeto>. Ele imprime encoder: ..., segment i/n e finalmente o caminho de out/<nome_saida>_draft.mp4.
  7. Visualizar: beatcut.py sheet <vídeo> --out <caminho .jpg> escreve uma folha de contato 5 por 4; abra essa imagem e descreva o resultado ao usuário (ordem dos takes, cor, fades, quadros pretos, cortes errados). Escolha um caminho --out fora da pasta de clipes, por exemplo uma pasta temporária.
  8. Final, somente com aprovação do usuário: após mostrar o rascunho, pergunte se deve renderizar o final. Execute beatcut.py final <projeto> apenas após um sim claro. O final é mais lento e maior. Informe o caminho de saída.

Se o usuário alterar a edição depois, volte ao passo 4. As renderizações reutilizam segmentos em cache, então um segundo rascunho é mais rápido.

Editando shots.json manualmente

Mantenha o arquivo como JSON válido (UTF-8). O comando check reporta toda violação destas regras.

Nível superior:

  • version: 1. period: número, maior que 0,05 e menor que 10. t0: número, 0 ou mais. tail: 0 a 30 (padrão 1,5). shots: lista, no máximo 2000.
  • Opcionais: bad (nome do clipe para lista de {"a": s, "b": s, "note": ""} com b > a >= 0), clipnotes (nome do clipe para texto), markers ({"beat": int >= 0, "title": texto}; mostrado apenas no seletor). Mantenha chaves que você não conhece; as ferramentas as preservam.

Cada take:

  • clip: nome do arquivo com extensão, como aparece na pasta de clipes. Sem / ou \, sem :. Deve ser um arquivo diretamente em clips_dir e corresponder a extensions.
  • in (0 ou mais) e out (maior que in): segundos no clipe de origem.
  • beats: número inteiro de 1 a 512.
  • Opcionais, com valores padrão: fit (fit ou cut; padrão fit), interp (oflow, blend, none; deixe de fora para automático), prof (um nome embutido neutral, warm, cool, contrast, golden, ou um nome definido em project.json profiles; padrão neutral), tin (cut, fade, fadewhite; padrão cut), tdur (0 a 5 segundos, padrão 0,5), note (texto, no máximo 2000 caracteres).

Como os números são usados:

  • Os takes são reproduzidos em sequência; o take N ocupa beats batidas na grade começando em t0 + period * (soma das batidas anteriores). O primeiro take começa no quadro de vídeo 0 em seu ponto in, portanto também cobre o tempo antes da primeira batida e avança além de seu out.
  • fit: velocidade = (out - in) / (beats * period). Velocidade dentro de 0,015 de 1 é considerada 1. check rejeita velocidades fora de 0,1x a 8x. Para manter um take na velocidade normal com fit, defina out = in + beats * period.
  • cut: reproduz a 1x; out não é usado para velocidade (o seletor escreve out = in + beats * period). Faça o mesmo.
  • O último take é estendido por tail segundos e a imagem desaparece (fade-out) ao longo de tail. Toda a edição não deve ser mais longa que a música.
  • Cada take precisa de material de origem até seu final (incluindo o tail e a liderança do primeiro take) com 0,1 s de margem antes do final do clipe. Uma transição fade ou fadewhite toma emprestada metade de sua duração de cada vizinho, portanto o take anterior precisa de origem além de seu out e o posterior precisa de origem antes de seu in.
  • Uma transição deve ser mais curta que os takes ao redor. tdur é arredondado para um número par de quadros; abaixo de 2 quadros significa um corte seco.
  • Câmera lenta: a interpolação automática ocorre apenas quando o take roda mais devagar que 0,97x e a taxa de quadros de origem vezes a velocidade está abaixo da taxa de quadros de saída (blend em rascunhos, oflow em finais). Não defina interp a menos que o usuário peça.
  • Escolha in/out para que o intervalo não sobreponha um intervalo bad; check avisa se sobrepor.

Regras do project.json (quando você o altera):

  • Chaves desconhecidas são erro. music é relativo à pasta do projeto, sem .., não absoluto. draft e final são {"width": n, "height": n} com inteiros pares positivos. fps é uma string como "25" ou "30000/1001". fill: cover ou blur. encoder: auto, cpu ou nvenc. loudness: -40 a -5.
  • profiles: nome ([a-z0-9_-], de 1 a 32 caracteres) para uma cadeia de filtros ffmpeg, sem ;, [ ou ]. Takes referem-se a perfis apenas pelo nome.

Mensagens e o que fazer

Avisos começam com warning: e não interrompem a renderização. Erros começam com error: e vão para stderr.

MensagemSignificado e ação
ffmpeg was not found on PATH; install FFmpeg and try again (código 2)ffmpeg ou ffprobe não está no PATH. Peça ao usuário para instalar o FFmpeg; não o instale você mesmo a menos que solicitado.
no project.json in <folder> (did you mean <folder>\beatcut?) (código 1)Você passou a pasta de clipes. Use a pasta beatcut dentro dela.
unknown key(s): ..., <field>: must be ...Um campo de project.json é inválido. Corrija esse campo.
<path>: invalid JSON (...) (<path> é o caminho completo de shots.json)Erro de sintaxe no arquivo. Corrija-o; a versão anterior pode estar em shots.json.bak.
shots[i].<field>: must be ...Um take quebra as regras acima (i conta a partir de 0). Corrija-o.
no shotsshots está vazio. Adicione takes (seletor ou manualmente).
shot N (clip): clip not found in the clips folderO nome do arquivo está errado ou o arquivo está faltando ou excluído por extensions ou exclude_prefix. Verifique a ortografia; nunca crie ou copie arquivos na pasta de clipes para corrigir isso.
shot N (clip): needs source up to X s but the clip is Y s longO intervalo mais liderança, cauda ou transição ultrapassa o clipe. Mova in para mais cedo, use menos batidas, use fit com um out mais curto, ou encurte a transição.
shot N (clip): needs X s before the start of the clip; move in laterUma liderança do primeiro take ou uma transição atinge antes de 0. Aumente in ou encurte a transição.
shot N (clip): shorter than its transitions; ...Transição mais longa que o take. Reduza tdur ou adicione batidas.
shot N (clip): speed X is outside 0.1x-8.0xIntervalo e contagem de batidas não se encaixam. Altere beats ou o intervalo.
the edit is X s long but the music is only Y sRemova batidas ou takes, reduza tail, ou use um arquivo de música mais longo.
warning: shot N (clip): uses a range marked bad (...)O take sobrepõe um intervalo bad. Mova-o ou informe o usuário.
warning: <clip>: HDR source (...); colours will look washed out ...Clipe HDR; beatcut não faz mapeamento de tom. Informe o usuário; sugira clipes SDR.
warning: <clip>: cannot be read (...)ffprobe não consegue ler o clipe. Informe o usuário.
music file not found: <name>O arquivo music está faltando na pasta do projeto.
profile <name>: ffmpeg rejects the filter chainUm perfil personalizado está errado. Corrija sua cadeia em project.json.
too many shots to assemble in one pass (N); split the editA edição é muito longa para uma renderização única. Informe o usuário; divida em vários projetos ou menos takes.
another render is already running for this project (código 2)Uma renderização (talvez iniciada pelo seletor) está em execução. Aguarde; não exclua work/.
cannot write <file>; close it in any player and try againA saída está aberta em outro lugar. Peça ao usuário para fechá-la.
fewer than 4 beats were detected; set period and t0 by hand (código 1)Veja o passo 3.

Códigos de saída: 0 sucesso, 1 problema com a entrada do usuário (corrija e reexecute), 2 falha de ambiente ou execução.

Não faça

  • Não modifique, mova, renomeie ou exclua os clipes de origem, e não escreva na pasta de clipes a não ser na pasta de projeto beatcut que o init cria. Tudo que a ferramenta escreve fica dentro da pasta do projeto.
  • Não exclua project.json, shots.json ou o arquivo de música. Não execute init novamente sobre um projeto existente.
  • Não execute final sem a aprovação do usuário após ele ter visto o rascunho.
  • Não exponha o seletor a uma rede: sem redirecionamento de porta, túneis, proxies reversos, e não tente vinculá-lo a outro endereço. Ele escuta apenas em 127.0.0.1 e não é protegido contra outros programas no mesmo computador.
  • Não coloque cadeias de filtro em shots.json, e não edite shots.json enquanto o seletor estiver em execução.
  • Não afirme que o resultado é bom sem olhar o rascunho (folha de contato ou o próprio vídeo).
  • Não prometa recursos que a ferramenta não possui: sem mapeamento de tom HDR, sem detecção facial, sem exportação para CapCut, sem efeitos sonoros. Linux e macOS não foram testados; Windows é a plataforma testada.

Habilidades Relacionadas