learnaiwithhugo/video-editor-skills

/kallaway-edit

Clipes brutos entram, reel vertical finalizado sai (1080x1920, 30 fps, -14 LUFS), no estilo Kallaway. Tudo roda no Mac do usuário com ferramentas gratuitas. A pessoa usando geralmente NÃO é técnica: fale com ela em português claro, uma mensagem curta por etapa, e nunca a faça mexer em código.

SK = ${CLAUDE_SKILL_DIR}, a pasta desta skill (nunca escreva nela: uma atualização a substitui). DATA = $HOME/.claude-video-editor, a pasta própria do editor, mantida entre atualizações: as configurações do usuário (DATA/config.json), o Python do editor (DATA/venv), os efeitos sonoros (DATA/sfx). ROOT = a pasta do projeto (tem raw/, exports/): o projectRoot em DATA/config.json, salvo pelo assistente de configuração (etapa 0). WORK = ROOT/work/<slug>/ (uma pasta por reel; o slug é curto em kebab-case, ex. dicas-opus). Coloque cada caminho entre aspas: eles frequentemente contêm espaços. Execute cada script através de um destes dois, exatamente como escrito, para que ele encontre as configurações do usuário: PY = VIDEO_EDITOR_DATA="$HOME/.claude-video-editor" "$HOME/.claude-video-editor/venv/bin/python" -I (após a configuração) SETUP = VIDEO_EDITOR_DATA="$HOME/.claude-video-editor" python3 -I "${CLAUDE_SKILL_DIR}/scripts/setup.py" Leia estes antes de construir: references/style-rules.md (a aparência, em números), references/graphics-recipes.md (como uma ideia falada se torna um diagrama), references/gotchas.md.

Regras rígidas

• Apenas ferramentas gratuitas. ffmpeg, Node 22+, Python, HyperFrames (npx hyperframes@<pinned>), faster-whisper, remoção de fundo local do HyperFrames, as fontes OFL incluídas, os efeitos sonoros gravados do HyperFrames media-use (baixados na configuração, nunca incluídos: licença Pixabay) e música CC0/CC BY do Openverse ou faixa própria do usuário. Sem APIs pagas, sem login no HeyGen, sem geração de música, nada com direitos autorais.
• Opções que o usuário pode dar: music: on|off (padrão: a escolha salva na configuração), music: <caminho para a faixa própria deles>, setup (re-executar o assistente de configuração).
• Nunca execute npx hyperframes init ou npx hyperframes skills (eles instalam skills em ~/.claude/skills). Toda chamada ao HyperFrames: HYPERFRAMES_SKIP_SKILLS=1 HYPERFRAMES_NO_TELEMETRY=1. Sempre snapshot ... --describe false (caso contrário, os quadros são enviados para o Gemini).
• Nunca toque na filmagem original do usuário. Trabalhe a partir de cópias em raw/. Arquivos de trabalho vão em WORK; apenas os reels finalizados vão em exports/. Nunca exclua os arquivos do usuário.
• As legendas mostram o que foi realmente dito, escritas corretamente ("Claude", "Opus 5.5"), dígitos para números.
• Os gráficos nunca cobrem o rosto; o texto nunca abaixo de y 1470 ou nos 100 px à direita abaixo de y 1155.
• Nada anima para fora. Vermelho #C41514 é o único acento. Uma palavra em itálico serifado por título e por seção.
• Mostre seu trabalho: coloque um PNG numerado em WORK/progress/ a cada etapa (01-takes-selecionados.png, ...).
• Verifique a renderização FINAL com qa.py, em tamanho real, antes de dizer que está pronto. Seja honesto sobre o que não corresponde.

O fluxo de trabalho

0. Assistente de configuração (apenas na primeira vez, ~5-10 min)

Leia DATA/config.json. Se tiver "setupComplete": true e a pasta projectRoot existir, execute SETUP --check (segundos, não instala nada); se PRONTO, vá para a etapa 1; se NÃO PRONTO, corrija o que ele nomear (após uma atualização que precise de uma nova versão de ferramenta, basta executar SETUP novamente: as pastas e escolhas do usuário são mantidas). Caso contrário (primeira execução, ou o usuário disser "/kallaway-edit setup") execute o assistente. Diga em qual etapa você está em uma linha curta ("Etapa 2 de 5: verificando suas ferramentas").

1. Bem-vindo. "Bem-vindo ao editor Kallaway! Vamos configurar tudo. Isso leva cerca de 5 a 10 minutos e acontece apenas uma vez."
2. Estamos no Claude Code? Isso precisa do Claude Code (o aplicativo de terminal, a aba Code no aplicativo de desktop do Claude, ou uma extensão de IDE), aberto em uma pasta local, porque edita arquivos de vídeo reais. Se você consegue executar comandos de shell e ler arquivos locais, você está. Se não consegue (um chat comum), diga: "Abra o aplicativo de desktop do Claude, clique em Code, escolha Local, selecione uma pasta (ou crie uma chamada Editor de vídeo AI), depois digite /kallaway-edit novamente." Então pare.
3. Verificação de ferramentas. SETUP --check. Mostre o resultado como uma tabela curta: ferramenta, encontrada sim/não, para que serve (ffmpeg corta e mixa som; Node.js executa HyperFrames; HyperFrames transforma a edição em vídeo; faster-whisper ouve cada palavra; Python executa os scripts auxiliares; yt-dlp é opcional aqui, baixa reels de links, e /new-edit-style precisa dele). Para qualquer coisa que o usuário precise instalar por conta própria (ffmpeg, Node.js, Python), dê a linha única com os nomes da correção e diga onde colá-la: o aplicativo Terminal (Mac: Command + Espaço, digite Terminal). Se pedir a senha do Mac, eles a digitam lá mesmos, nunca neste chat. Espere até que digam que está pronto, então verifique novamente. Itens marcados como "a configuração completa instala" não precisam de nada deles.
4. Onde as coisas ficam. Pergunte em uma mensagem, cada uma com uma resposta sugerida:
   • "Onde devo fazer seus vídeos?" Sugira a pasta atual se estiver vazia ou já for uma pasta de vídeo (mostre o caminho completo), caso contrário ~/Desktop/Editor de vídeo AI.
   • "Onde sua filmagem normalmente cai?" Sugira ~/Downloads (onde o AirDrop coloca clipes do celular), ou "Eu mesmo colocarei os clipes na pasta raw".
   • "Música de fundo por baixo da sua voz: ligada ou desligada?" Sugira ligada (eles podem mudar por vídeo). Então ofereça as pastas: "Quer que eu configure sua pasta de projeto? Vou criar raw/ (seus clipes), references/ (vídeos cujo estilo você gosta), exports/ (reels finalizados), work/ (meus arquivos de trabalho) e archive/ (versões antigas). Qualquer coisa já existente permanece intocada." Se sim: SETUP --project "<pasta>" --clips-from "<pasta ou omitir>" --music on|off. Ele apenas cria as pastas faltantes e salva as respostas em DATA/config.json.
5. Instalação. "Instalando as ferramentas de edição gratuitas agora (uma vez, cerca de 5 minutos: um mecanismo de transcrição, o renderizador de vídeo, efeitos sonoros e um modelo de fala)." Execute SETUP em segundo plano e repasse suas linhas de progresso em palavras simples. Ele instala apenas em DATA (nada global, nada na pasta da skill, então as atualizações nunca desfazem) e marca a configuração como concluída quando terminar.
6. Pronto. Dê as 4 dicas de filmagem de references/filming-guide.md (câmera fixa, plano aberto, cômodo escuro com uma luz quente no rosto, repita uma linha até funcionar), então: "Pronto. Coloque seus clipes em raw/ (ou me diga quais arquivos em ) e diga /kallaway-edit." Se eles já forneceram clipes, vá direto para a etapa 1.

Entrada em toda execução: clipes são os arquivos que o usuário nomeia; caso contrário, pergunte, oferecendo os arquivos de vídeo mais recentes em clipsFrom. Copie-os para ROOT/raw/ (nunca mova ou altere os originais). A música segue a escolha music salva, a menos que o usuário diga o contrário.

1. Encontrar cada take (~1 min por minuto de filmagem)

PY "SK/scripts/takes.py" "WORK" "ROOT/raw/clip1.MOV" "ROOT/raw/clip2.MOV" (adicione --fast para uma passagem mais rápida, menos precisa). Leia WORK/takes/*.takes.txt: cada tentativa com seu intervalo de tempo, retakes marcados. Pergunte (ou encontre nos clipes) pelo roteiro, se houver. Diga: "Ouvindo seus clipes e encontrando o melhor take de cada linha."

2. Selecionar takes e cortar (~1 min)

Escreva WORK/edl.json (formato: SK/template/examples/edl.json): um segmento por linha, na ordem do roteiro, geralmente o ÚLTIMO take completo e limpo. Use {"clip","chunk"} ou {"clip","start","end"} (para pular um tropeço dentro de um chunk; verifique os tempos das palavras com transcribe.py --range a-b --model medium.en --no-vad). Alvo de 20 a 30 s; passar um pouco (até ~38 s) é melhor do que quebrar uma promessa que o gancho faz. Pule CTAs a menos que seja pedido. Então PY "SK/scripts/assemble.py" "WORK": cut.mp4 (CFR, justo na voz, comprimido, -14 LUFS), segments.json, words.json, words.txt. Leia words.txt: cada linha deve dizer o que foi significado. PY "SK/scripts/qa.py" "WORK" --takes escreve progress/01-takes-selecionados.png. Diga: "Aqui está o corte: . segundos." Trave o corte antes de construir os gráficos. Se recortar depois: PY "SK/scripts/reindex.py" "WORK" "WORK/.prev/words.json" mantém cada gráfico em sua palavra.

3. Recortar o palestrante (~3-4 min, execute em segundo plano)

PY "SK/scripts/cutout.py" "WORK": cutout.webm (combinado ao quadro, borda limpa) + headtrack.json. Enquanto executa, planeje a edição (etapa 4). Então veja um quadro composto sobre preto para halos e salve-o como progress/02-verificacao-cutout.png.

3b. Música (a menos que music: off; ~2-6 min, execute em segundo plano)

PY "SK/scripts/music.py" "WORK" (ou --file "<música deles>", ou --off). Ele escolhe um instrumental CC0/CC BY gratuito do Openverse, rejeita vocais e escreve WORK/music-credit.txt. Diga ao usuário o que escolheu e, para CC BY, que a linha de crédito vai na legenda.

4. Planejar a edição, linha por linha

Escreva WORK/plan.json (formato: SK/template/examples/plan.json):

• shots: onde cada layout começa (0, "line:N" = primeiro quadro da linha N da EDL, "w:N" = início da palavra N). Palco para tudo que pode ser mostrado; tela cheia para linhas de conexão/pessoais e a recompensa (16-29% do tempo de execução). Corte seco entre cenas de palco também. Primeiro corte em ~3,5 s.
• scenes: qual gráfico toca quando (id, from, to, opcional src + vars para montar um arquivo de cena várias vezes, ex. um gráfico "início" numerado recorrente). Uma cena pode rodar sob um take de tela cheia e voltar (uma revisita adiciona uma coisa nova em 0,6 s).
• punch: zoom snap (x1,19, com crescendo) em uma frase de fechamento, no máximo um ou dois.
• captions: fix (índice da palavra -> texto correto), emphasis (uma palavra serifada por seção), keep_together (pares de índices de palavras, ex. "Número" + "1,"). Use graphics-recipes.md: cada ideia ganha uma forma, um título (negrito + um acento serifado, a afirmação em uma caixa vermelha) e batidas em suas palavras, algo novo a cada ~1 s. Diga o plano de volta em uma linha por take.

5. Construir as cenas (~15-25 min)

Cada cena é WORK/scenes/<nome>.html, iniciada a partir de SK/template/scene-starter.html ou do arquivo mais próximo em SK/template/examples/ (seis cenas reais). O kit (template/kit/kw.css, kw.js) fornece a aparência do palco e auxiliares de movimento (KW.title, blurIn, pill, pulse, draw, cam, type, strike, count, scramble; at(i) = início da palavra i). TODA animação recebe sua dica sonora no comentário <!--KW:SFX [...] --> da cena, ex. {"t": "w:24-0.02", "s": "whoosh"}, seguindo references/sound-map.md (movimento de câmera = whoosh, pill = pop, snap/tick = click, texto digitado = typing, grande momento = impact, recompensa = sparkle). Se você tiver a ferramenta Agent e mais de ~3 cenas, entregue cenas para até 2 agentes paralelos com: a lista exata de palavras e tempos da cena, a ideia, as referências desta skill e build.py ... --project WORK/project-<letra> para que nunca colidam. PY "SK/scripts/build.py" "WORK" escreve WORK/project/ (raiz: palco pontilhado, cartão de rosto, camada pop-out, trilha de legenda, hosts de cena, faixa SFX, tudo gerado). Então em WORK/project: npx -y hyperframes@<pin> lint (0 erros) e snapshot --at <tempos> --no-end --describe false -o snaps/x, leia os PNGs, corrija, repita. Salve a folha de cada cena como progress/03-cena-.png.

6. Renderizar (~1 min) e verificar (~1 min)

PY "SK/scripts/render.py" "WORK" --name draft (rápido), então PY "SK/scripts/qa.py" "WORK" "WORK/renders/draft.mp4" e OLHE para qa/cuts.png (quadro antes/depois de cada corte), qa/beats.png (cada bloco de legenda), qa/report.txt (lacunas corte-fala, volume). Verifique: pop-out não tem halo ou desvio após cortes; o cartão mostra cabeça E ombros (nunca um corte de rosto); nenhuma legenda ou gráfico sobre o rosto; legendas correspondem às palavras; cada corte de linha cai 0-80 ms antes da fala; nada nas zonas proibidas do Instagram. Então PY "SK/scripts/audiomap.py" "WORK" --out progress/NN-mapa-audio.png: música 18-24 dB abaixo da voz, efeitos ~10-16 dB abaixo do pico local, sem golpes duplos; corrija qualquer dica sinalizada com "db": -3. Correspondência de estilo: PY "SK/scripts/match/fingerprint.py" score "SK/references/style-spec.json" "WORK/renders/draft.mp4" --out "WORK/progress/NN-correspondencia-estilo.md" mede a edição da mesma forma que os 3 reels Kallaway foram medidos (taxa de corte, mudanças visuais por segundo, participações de layout, posição do cartão e da legenda, tamanho e ritmo da legenda, participação da cor de acento, volume, efeitos sonoros estéreo) e diz o que corrigir para cada FALHA. Corrija o que a edição controla; uma FALHA causada pela filmagem (uma selfie próxima) vai para o usuário como uma nota de filmagem. O relatório em WORK/progress/ é o registro (SK/references/lock-log.md contém o histórico medido do estilo; deixe-o como está). Corrija e re-renderize (uma reconstrução + re-renderização leva ~1,5 min).

7. Entregar

PY "SK/scripts/render.py" "WORK" --final -> exports/<slug>-kallaway-vN.mp4 (1080x1920) mais -720p.mp4 cópia para celular. Execute qa.py na exportação. Se o usuário tiver um reel Kallaway próprio salvo em ROOT/references/ (nenhum vem com esta skill), adicione uma comparação lado a lado (--ref <esse reel> --ref-at <t> --at <t>) e salve como progress/NN-lado-a-lado.png. Diga: onde o arquivo está, quanto tempo tem, o que contém cena por cena e o que ainda não parece com Kallaway (seja específico e honesto).

Temporizações (em um Mac M4 Pro, reel de 35 s a partir de ~8 min de filmagem bruta)

configuração 5 min (primeira vez) · takes 7 min (modelo médio; --fast ~3) · corte 1 min · cut-out 3,5 min · música 2-6 min (em segundo plano; Openverse/Freesound pode ser lento) · cenas 15-25 min · renderização draft 50 s · renderização final 70 s · re-renderização após edição ~1,5 min.

Filmagem

Dê references/filming-guide.md para qualquer um que for filmar: plano aberto fixo (4K horizontal é o melhor), cômodo escuro com uma luz principal quente, top escuro, fundo simples atrás da cabeça, repita uma linha até funcionar.