mk-video-editing

O que mk-video-editing faz?

Transforme as filmagens fornecidas em um corte assistível e consistente: as palavras certas na ordem certa, uma câmera que enquadra bem o assunto, uma imagem consistente, som limpo e nivelado, e títulos de bom gosto. A estrutura vem das próprias filmagens e do que é dito nelas.

O que o skill pode fazer

Necessidade	Ferramentas	Custo	Referência
Transcrições de palavras, detecção de vícios de linguagem/falsos começos/pausas	edit:transcribe (mlx-whisper), speech:flow	gratuito, local	footage-editing.md
Estabilizar, rastrear o orador, reenquadrar grandes planos 4K (aproximações, zoom, panorâmicas), HDR→SDR, remoção de flicker, correspondência de cores, dissolves, jump cuts	edit:analyze, edit:track, EDL + medit (edit:render)	gratuito, local	footage-editing.md
Limpeza de diálogo, mixagem, ducking, loudness	speech:clean (ISOLATE=1 Demucs), speech:mix, speech:measure	gratuito, local	footage-editing.md
Narração	voice:tts (ElevenLabs via Fal)	pago, aprovado	credentials.md
Títulos, lower thirds, cartões finais (ProRes 4444 alpha)	mgraphics cenas JSON, graphics:render, modelos em scripts/tools/graphics/examples/	gratuito, local	graphics README
Trilha sonora sob a edição	EDL music (com ducking), music:score (ElevenLabs Music via Fal), audio:analyze para batida	pago apenas se gerada	finishing.md
Efeitos sonoros em títulos/transições	SoundSynth (synth: whoosh, riser, impact, tick…), sfx:gen/sfx:mix ou EDL sounds	gratuito (Stable Audio prompt: pago)	finishing.md
Efeitos de imagem (flash, dip, punch, glow, lens, streaks…)	mvfx folhas de cues, vfx:stills/vfx:render	gratuito, local	finishing.md
Codificações de entrega	media:twitter, media:youtube, media:faststart	gratuito, local	tasks.md
Subagentes paralelos em tarefas independentes	work:next/work:accept/work:log/work:watch	gratuito	tasks.md

Cada tarefa com seus argumentos e opções está em tasks.md. Perfis de teste estão em testing.md.

Contrato de execução

Projetado para Claude Code no macOS 14+ em Apple Silicon (Swift 5.9+, Ruby 3.2+, Bundler, FFmpeg, ImageMagick, uv para Whisper local). Execute doctor primeiro quando uma tarefa falhar por falta de ferramenta; setup compila as ferramentas Swift. Ruby é a única camada de entrada de execução: execute ruby "${CLAUDE_SKILL_DIR}/scripts/mv.rb" --project /abs/project 'tarefa[args]'. As tarefas delegam para serviços Ruby (lib/media/edit.rb, speech.rb, guard.rb, …) que acionam as ferramentas Swift nativas medit (scripts/tools/edit), mgraphics (scripts/tools/graphics) e mvfx (scripts/tools/vfx). Adicione um método Ruby e uma tarefa pequena quando uma capacidade estiver faltando. Um projeto executa sua própria cópia de lib/ e tools/: após alterar o skill, use rsync para copiar os arquivos alterados para o projeto.

Segurança de memória (obrigatório)

A decodificação de hardware 4K/HDR mantém os frames no VTDecoderXPCService, fora da pegada de memória do processo. Em uma máquina de 16 GB sem swap, esgotar a memória congela o computador em vez de apenas desacelerá-lo. Portanto:

• Execute uma tarefa pesada por vez (medit analyze/render/stills, codificações mgraphics, Demucs, grandes codificações ffmpeg). Nunca lance várias em paralelo ou em segundo plano junto com outras; encadeie-as sequencialmente em um único comando em segundo plano, se necessário. JOBS permanece 1 a menos que a RAM ≥ 32 GB.
• Cada chamada de renderização medit/mgraphics/mvfx passa por Media::Guard (automático nos serviços Ruby): ele amostra a pegada do processo + decodificador e a porcentagem de memória livre do kernel a cada 0,3 s e envia SIGKILL antes de MEDIT_MAX_FOOTPRINT_MB (padrão 3500) ou abaixo de MEDIT_MIN_FREE_PCT (padrão 30). Ele se recusa a iniciar quando a memória livre já está baixa. Todos os três renderizadores usam JOBS=1 como padrão; blocos paralelos exigem uma configuração explícita de JOBS.
• Valide qualquer novo caminho de código de decodificação/renderização em um intervalo curto com limites apertados primeiro (TO=15 MEDIT_MAX_FOOTPRINT_MB=1500 MEDIT_GUARD_LOG=/caminho/log), verifique se o log está estável e então execute o comprimento total.
• Em loops de mídia Swift, envolva cada copyNextSampleBuffer e renderização Core Image em autoreleasepool (código assíncrono nunca drena o pool padrão: frames vazam a ~1,5 GB/s).

Estado estacionário medido: análise ≈ 1,0 GB (processo + decodificador) por fonte 4K HLG; uma renderização com dissolve abre duas fontes.

1. Recepção

Pergunte apenas o que está faltando: caminhos das filmagens, o que é a edição (trecho de palestra, resumo…), texto de títulos/ créditos, duração desejada, desejo de narração. Inicialize com a mídia (criando links simbólicos, nunca copiados ou modificados):

ruby "${CLAUDE_SKILL_DIR}/scripts/mv.rb" init --project /abs/projeto --media /abs/clipe1.MOV --media /abs/clipe2.MOV --prompt-file /abs/brief.md
ruby "${CLAUDE_SKILL_DIR}/scripts/mv.rb" --project /abs/projeto setup

Analise cada fonte (ffprobe: tamanho, fps, duração, transferência HDR). Extraia áudio (audio/raw/*.wav, 48 kHz) e transcreva localmente: edit:transcribe[analysis/transcripts,source/...] (mlx-whisper large-v3-turbo, tempos de palavras; gratuito). Leia cada transcrição e escreva o que cada clipe diz, com timestamps, em docs/BRIEF.md. Pesquise na web fatos do evento usados nos títulos e registre as fontes.

2. Analisar (sequencialmente)

REGION=0,0,1,0.62 DETECT_REGION=0.15,0.3,0.85,0.8 mv 'edit:analyze[fonte/A.MOV,analise/A.json]'   # um de cada vez
mv 'edit:track[analise/A.json,analise/A.track.json]'      # SEED=x,y quando o orador não é encontrado no início; SPACE=frame para estabilizar: 0
mv 'edit:stats[analise/A.json,de,para]'

• REGION limita a estabilização (correlação de fase) ao cenário estático (palco, telas), excluindo o público.
• DETECT_REGION recorta o palco para detecção de pessoas Vision com resolução ~2× — essencial para um orador distante (a detecção passou de 2 % para 40–90 % das amostras).
• Os rastreamentos são travados no mundo (estabilização removida), selecionados por continuidade e descartam caixas de primeiro plano largas (cabeças) via max_aspect.
• Filmagens de celular (iPhone etc.) já estão estabilizadas na câmera: renderize-as com stabilize: 0 e SPACE=frame nos rastreamentos. Nosso estabilizador pode confundir conteúdo de slides em movimento com movimento de câmera e adicionar saltos horizontais repentinos. Verifique: conte quadros com |Δshift| > 8 px na análise; tremor residual em iPhone 4K medido ≈ 0,9 px RMS, não vale a pena corrigir.

Fluxo de fala (vícios de linguagem, falsos começos, repetições, pausas não naturais)

VERBATIM=1 mv 'edit:transcribe[analysis/transcripts_verbatim,source/A.MOV]'   # prepara Whisper para escrever um/uh
mv 'speech:flow[analysis/transcripts_verbatim/A.json,audio/clean/A.wav,analysis/flow/A.json]'   # leia analysis/flow/A.txt

O detector mede pausas acusticamente (energia + sonorização, não tempos de palavras do Whisper), classifica-as (sentença/vírgula/frase) e sinaliza vícios de linguagem, hums não transcritos, repetições e possíveis falsos começos, cada um com um cut proposto. Decida cada um pelo significado e, em seguida, aplique os cortes com Media::Cuts no gerador (passo 4). Procure autocorreções e frases abandonadas ("para ser—", uma última frase inacabada antes de aplausos) lendo o .txt; o detector apenas propõe candidatos.

• As estatísticas de cor do quadro inteiro são dominadas por telas de projeção; ajuste a exposição na área do orador (blocos ao redor do rastreamento) e julgue o balanço de branco em stills.

3. Planejar e aprovar

Escreva docs/PLAN.md: tabela de seleções (fonte, entrada/saída em limites de sentença, conteúdo, união: dissolve/jump cut), títulos, texto de narração, linguagem de câmera, tratamento de imagem e áudio. Resuma no chat; registre a aprovação com NOTE='...' plan:approve (também necessário antes de chamadas pagas, por exemplo, narração ElevenLabs via voice:tts; veja credentials.md — em sessões de plugin, tarefas pagas são executadas através do servidor MCP mk-video-editing).

4. Construir o EDL com um script gerador

Escreva edit/build_edl.rb (veja footage-editing.md para o esquema EDL completo e um exemplo prático). Defina um vocabulário de planos (ABERTO zoom≈1.2–1.4, MÉDIO-ABERTO fit≈0.4, MÉDIO fit≈0.56, APROXIMAÇÃO fit≈0.72 limitado por max_zoom 3.6) e escreva batidas de câmera em segundos da fonte retirados da transcrição: aproximações lentas com 6–12 s, zoom cortado em linhas de ênfase, corte para aberto em mudanças de tópico/slide, reenquadramento a cada jump cut. Por clipe: área safe (manter primeiro plano distrativo fora), deflicker, grade de correspondência; um look compartilhado. Overlays são títulos ProRes 4444 alpha (veja Títulos abaixo).

Remova palavras e pausas dentro de uma seleção com lib/media/cuts.rb: Media::Cuts.pause_cuts (encurtar automaticamente pausas não naturais), Media::Cuts.segments (dividir a seleção em segmentos de jump cut, ajustar os limites para o ponto mais silencioso entre palavras, abrir cada segmento com um enquadramento contrastante, manter cada zoom com ≥ 4,5 s), Media::Cuts.text (registrar o que cada corte remove em edit/cuts.txt). Comece e termine cada seleção em silêncio e longe do manuseio da câmera (verifique a velocidade de deslocamento perto das bordas). Exemplo prático em footage-editing.md.

5. Áudio

speech:clean[audio/raw/A.wav,audio/clean/A.wav] (PRESET=room: corte de ruído grave, FFT denoise, corte de lama, presença, de-ess, expansor suave, nivelador; ISOLATE=1 para vocais Demucs local). Adicione narração com voice:tts quando solicitado (MODEL=v4 para Eleven v4). Adicione uma trilha sonora apenas quando o briefing pedir uma: uma faixa fornecida ou music:score, colocada como EDL music (finishing.md). Em seguida, execute speech:mix[edit/edl.json,audio/mix.wav]. Ele mixa o áudio do clipe com crossfades em dissolves (audio_xfade: 0.15 mantém a última palavra antes de um dissolve de 0,6 s), audio_duck sob narração, sounds e music com ducking sidechain, então aplica loudnorm de dois passos para −16 LUFS / −1.5 dBTP.

6. Revisar, renderizar, entregar

• DEBUG=1 edit:stills[edit/edl.json,edit/review/vN,t1,t2,...] — cada still mais o quadro completo da fonte com recorte (vermelho), assunto (verde) e área segura (amarelo). Verifique enquadramento, espaço acima da cabeça, intrusões de primeiro plano, continuidade de exposição/WB entre cortes.
• edit:sheet folhas de contato; edit:preview[edl,out.mp4,from,to] rascunhos em meia resolução de intervalos alterados.
• edit:render[edit/edl.json,output/final.mp4] (JOBS=1). Nunca sobrescreva um mestre entregue.
• QA antes de renderizar o vídeo: speech:mix, então edit:transcribe a mixagem e leia as palavras ao redor de cada at do clipe (barato; capta palavras cortadas e flashes de palavra única). Após a renderização, retranscreva o final; registre versões e problemas em docs/REVIEW.md.

Entregue o vídeo, os documentos de plano/brief/revisão e um breve resumo das escolhas e problemas conhecidos. Execute perfis RSpec de testing.md após alterar o toolkit e swift test em tools/graphics após alterações no renderizador.

Títulos

Comece pelos modelos em scripts/tools/graphics/examples/: opening_title.json, lower_third.json e end_card.json (1920×1080, AvenirNext, uma cor de destaque). Copie-os para edit/titles/, altere o texto e o tempo, ou gere-os a partir de edit/make_titles.rb quando houver vários. Verifique na web nomes, funções e fatos do evento.

1. Renderize stills com ONLY= sobre um quadro do plano (PLATE=) e verifique a legibilidade, margem segura e destaques.
2. Renderize CODEC=prores4444 SUPERSAMPLE=2 graphics:render[edit/titles/x.json,edit/titles/x.mov,quadros,1920,1080,fps] no fps da edição.
3. Coloque-o como uma entrada EDL overlays, escurecendo ou desfocando o plano de fundo sob um cartão de abertura com dim/blur da câmera.

O formato da cena (nós, trilhas, easing, brilho, fontes) está no graphics README. Após alterações no renderizador, execute swift test em scripts/tools/graphics e compare renderizações de títulos antigas e novas byte a byte.

Finalização (opcional)

Uma trilha sonora, efeitos sonoros e efeitos de imagem são passagens opcionais, descritos em finishing.md:

• a trilha vai para speech:mix antes da renderização;
• SFX (sfx.yml) e VFX (cues.yml) são executados no mestre renderizado e sempre escrevem um novo arquivo.

Use-os quando o briefing pedir uma sensação de promo ou resumo. Edições de palestras limpas raramente precisam deles.

Trabalho paralelo

Para edições longas, divida tarefas independentes (títulos, linhas de narração, stills de revisão por seção, transcrições de QA) em config/production.json com suas depends. Entregue-as a subagentes através de work:next, peça que relatem com work:log e aceite cada uma após a revisão (work:accept). Subagentes podem escrever cenas, scripts e docs em paralelo. Tarefas pesadas de mídia (medit, codificações mgraphics/mvfx, Demucs) ainda são executadas uma de cada vez (segurança de memória acima).