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
- 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).
- Inicializar:
beatcut.py init <pasta dos clipes> --music <arquivo de música>. Ele imprimecreated: <pasta>e copia a música para dentro do projeto. Se disserproject.json already exists, o projeto existe; use-o e não reinicialize. Editeproject.jsonse tamanhos,fill,fps,encoder,exclude_prefixouprofilespersonalizados precisarem ser alterados (veja as regras abaixo). - Batidas:
beatcut.py beats <projeto>. Ele imprimeperiod,t0ebpme os escreve emshots.json. A detecção assume um andamento constante e pode errar por alguns centésimos de segundo emt0. Se sair com código 1 e a mensagemfewer than 4 beats were detected, definaperiodet0manualmente (period = 60 / BPM; t0 = segundo da primeira batida). Informe os números ao usuário; eles podem corrigi-los no seletor. - 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 leiashots.json. Não editeshots.jsonenquanto 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.
- Seletor (padrão). Inicie
- Verificar:
beatcut.py check <projeto>. Saída com código 0 eok: <n> shots, <s> ssignifica nenhum erro; leia também os avisos (stderr). Corrija todos os erros antes de renderizar. - Rascunho:
beatcut.py draft <projeto>. Ele imprimeencoder: ...,segment i/ne finalmente o caminho deout/<nome_saida>_draft.mp4. - 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--outfora da pasta de clipes, por exemplo uma pasta temporária. - 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": ""}comb > 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 emclips_dire corresponder aextensions.in(0 ou mais) eout(maior quein): segundos no clipe de origem.beats: número inteiro de 1 a 512.- Opcionais, com valores padrão:
fit(fitoucut; padrãofit),interp(oflow,blend,none; deixe de fora para automático),prof(um nome embutidoneutral,warm,cool,contrast,golden, ou um nome definido emproject.jsonprofiles; padrãoneutral),tin(cut,fade,fadewhite; padrãocut),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
beatsbatidas na grade começando emt0 + period * (soma das batidas anteriores). O primeiro take começa no quadro de vídeo 0 em seu pontoin, portanto também cobre o tempo antes da primeira batida e avança além de seuout. fit: velocidade =(out - in) / (beats * period). Velocidade dentro de 0,015 de 1 é considerada 1.checkrejeita velocidades fora de 0,1x a 8x. Para manter um take na velocidade normal comfit, definaout = in + beats * period.cut: reproduz a 1x;outnão é usado para velocidade (o seletor escreveout = in + beats * period). Faça o mesmo.- O último take é estendido por
tailsegundos e a imagem desaparece (fade-out) ao longo detail. 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
taile a liderança do primeiro take) com 0,1 s de margem antes do final do clipe. Uma transiçãofadeoufadewhitetoma emprestada metade de sua duração de cada vizinho, portanto o take anterior precisa de origem além de seuoute o posterior precisa de origem antes de seuin. - 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 (
blendem rascunhos,oflowem finais). Não definainterpa menos que o usuário peça. - Escolha
in/outpara que o intervalo não sobreponha um intervalobad;checkavisa se sobrepor.
Regras do project.json (quando você o altera):
- Chaves desconhecidas são erro.
musicé relativo à pasta do projeto, sem.., não absoluto.draftefinalsão{"width": n, "height": n}com inteiros pares positivos.fpsé uma string como"25"ou"30000/1001".fill:coveroublur.encoder:auto,cpuounvenc.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.
| Mensagem | Significado 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 shots | shots está vazio. Adicione takes (seletor ou manualmente). |
shot N (clip): clip not found in the clips folder | O 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 long | O 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 later | Uma 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.0x | Intervalo 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 s | Remova 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 chain | Um perfil personalizado está errado. Corrija sua cadeia em project.json. |
too many shots to assemble in one pass (N); split the edit | A 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 again | A 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
beatcutque oinitcria. Tudo que a ferramenta escreve fica dentro da pasta do projeto. - Não exclua
project.json,shots.jsonou o arquivo de música. Não executeinitnovamente sobre um projeto existente. - Não execute
finalsem 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.1e não é protegido contra outros programas no mesmo computador. - Não coloque cadeias de filtro em
shots.json, e não editeshots.jsonenquanto 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.