Habilidade de Edição de Vídeo
Visão Geral
Esta habilidade implementa um pipeline de 6 camadas onde a IA lida com tarefas de julgamento (o que manter, o que cortar, seleção de destaques) e o FFmpeg/Remotion lidam com a execução mecânica de forma determinística.
| Camada | Nome | Mecanismo | Ferramenta Principal |
|---|---|---|---|
| 1 | CAPTURA | Inventário de filmagens de origem | Bash + Glob |
| 2 | ESTRUTURA IA | Transcrição para EDL | Julgamento LLM |
| 3 | CORTES FFMPEG | EDL para arquivos de segmento | FFmpeg (determinístico) |
| 4 | COMPOSIÇÃO REMOTION | Segmentos para composição TSX | Remotion + TypeScript |
| 5 | GERAÇÃO IA | Preencher lacunas com assets gerados | ElevenLabs / fal.ai (condicional) |
| 6 | POLIMENTO FINAL | Camada de gosto humano | Humano + NLE |
Referências Detalhadas
| Sinal | Carregar | Conteúdo |
|---|---|---|
| Comandos de shell para cada fase, verificações de portão | references/phase-commands.md | Blocos de comando completos para Fases 1-6 |
| Receitas FFmpeg: corte, concat, proxy, detecção | references/ffmpeg-commands.md | Extração de timestamps, corte em lote, normalização de áudio, detecção de cena/silêncio |
| Scaffold de composição Remotion | references/remotion-scaffold.md | Template de composição TSX, comando de render, padrões de reuso |
| Pipeline de imagem para vídeo | references/image-to-video.md | Fluxo de trabalho: validar, preparar, codificar, verificar |
| Grafos de filtro FFmpeg para visualização | references/ffmpeg-filters.md | Scale/pad, showwaves, showspectrum, overlay, grafos de filtro completos |
Instruções
Pré-voo (Executar antes da Fase 1)
Requisitos obrigatórios (BLOQUEAR se ausentes): ffmpeg (todas as fases), node (Remotion / npx).
Requisitos opcionais (AVISAR se ausentes): remotion (obrigatório apenas para a Fase 4).
which ffmpeg >/dev/null 2>&1 || { echo "ERRO: ffmpeg não encontrado. Instale: brew install ffmpeg (macOS) | apt install ffmpeg (Linux)"; exit 1; }
which node >/dev/null 2>&1 || { echo "ERRO: node não encontrado. Instale: https://nodejs.org ou via nvm"; exit 1; }
npx remotion --version >/dev/null 2>&1 || echo "AVISO: CLI remotion não encontrado. Fase 4 indisponível. Instale: npm install @remotion/cli"
Fase 1: CAPTURA
Objetivo: Inventariar todas as filmagens de origem e confirmar que os arquivos existem no disco antes de qualquer processamento.
Restrição: Arquivos de origem são somente leitura. Todos os comandos FFmpeg escrevem apenas em novos arquivos. Nunca sobrescreva filmagens de origem.
Passos: localizar arquivos de origem (find), inspecionar cada um com ffprobe, gerar proxies para arquivos >10 min (veja references/ffmpeg-commands.md -> Geração de Proxy), criar diretórios de trabalho (segments/, assembled/). Bloco de comando completo: references/phase-commands.md -> Fase 1.
Portão: Arquivos de origem confirmados no disco. Lista de arquivos escrita em source-inventory.txt. Prossiga somente quando o portão passar.
Fase 2: ESTRUTURA IA
Objetivo: Analisar o conteúdo e produzir uma EDL escrita (cuts.txt) que direciona todos os cortes a jusante.
Restrição: cuts.txt é o contrato. O arquivo EDL é a única fonte da verdade para as fases a jusante. Não edite manualmente os comandos FFmpeg — gere-os a partir da EDL.
Restrição: Antes de escrever a EDL manualmente, execute a detecção de cena/silêncio do FFmpeg. A saída da detecção informa o julgamento, não o substitui.
Passos: transcrever com whisper/AssemblyAI, executar detecção de cena/silêncio, aplicar julgamento (o que avança a narrativa, o que é preenchimento, duração alvo), escrever cuts.txt no formato EDL START_TIME,END_TIME,LABEL, revisar sobreposições e duração total. Bloco de comando completo e exemplo de formato EDL: references/phase-commands.md -> Fase 2.
Portão: transcript.txt existe. cuts.txt escrito no disco. Prossiga somente quando ambos os arquivos existirem.
Fase 3: CORTES FFMPEG
Objetivo: Executar a EDL deterministicamente — um corte FFmpeg por segmento em cuts.txt.
Restrição: Corte em lote a partir da EDL usando um loop. Não crie comandos FFmpeg individuais por corte. Isso garante reprodutibilidade e capacidade de revisão como lista.
Restrição: Sempre gere concat-list.txt a partir da ordem do cuts.txt, não do glob do shell. O glob do shell (segments/*.mp4) ordena alfabeticamente, não pela ordem da EDL.
Passos: corte em lote a partir da EDL com loop while (libx264/aac, -avoid_negative_ts make_zero), verificar segmentos, gerar concat-list.txt na ordem da EDL, concatenar com -f concat -safe 0 -c copy. Bloco de comando completo: references/phase-commands.md -> Fase 3. Veja também references/ffmpeg-commands.md -> Corte em Lote.
Portão: Todos os arquivos de segmento existem. assembled/rough-cut.mp4 escrito no disco. Prossiga somente quando o portão passar.
Fase 4: COMPOSIÇÃO REMOTION
Objetivo: Envolver segmentos em uma composição TSX do Remotion para sobreposições programáticas, títulos ou transições.
Quando usar: Apenas quando rough-cut.mp4 exigir elementos programáticos (títulos animados, barras inferiores, faixas de legenda, sobreposições de marca). Se rough-cut.mp4 for suficiente, pule para a Fase 6.
Restrição: A Camada 4 requer TypeScript/React. Passe para typescript-frontend-engineer para trabalho TSX; retorne para python-general-engineer para a Fase 5 em diante.
Passos: inicializar Remotion (npm create video@latest na primeira vez; caso contrário npm install @remotion/cli @remotion/player remotion), criar scaffold da composição (veja references/remotion-scaffold.md), renderizar com npx remotion render. Bloco de comando completo: references/phase-commands.md -> Fase 4.
Portão: assembled/remotion-output.mp4 existe. Prossiga somente quando o portão passar.
Fase 5: GERAÇÃO IA
Objetivo: Preencher lacunas genuínas no material de origem com assets gerados — somente quando necessário.
Restrição: Verifique se a filmagem existente cobre a lacuna antes de gerar qualquer coisa. Gere apenas o que não existe.
Árvore de decisão: cortar ao redor da lacuna → atualizar cuts.txt e reexecutar a Fase 3; narração → ElevenLabs (autorização necessária); música → fal.ai (delegar para fal-ai-media); b-roll → fal.ai (delegar para fal-ai-media). Auxiliar Python ElevenLabs, padrão de autorização e fluxo de salvamento em disco: references/phase-commands.md -> Fase 5.
Portão: Todos os assets gerados necessários salvos no diretório assets/ antes de prosseguir.
Fase 6: POLIMENTO FINAL
Objetivo: Entregar a saída montada e passar o trabalho de camada de gosto para o humano.
Restrição: A Camada 6 é território humano. A habilidade monta; o humano finaliza. Os itens a seguir exigem julgamento humano e não devem ser tentados programaticamente:
- Correção de cor e correspondência de cores entre clipes
- Temporização da música e redução de volume
- Estilo, fonte e posicionamento da legenda
- Temporização e estilo da transição
- Níveis finais de mixagem de áudio
Modelo de entrega (handoff-notes.txt com lista de fontes, EDL, caminho do rough-cut, lista de verificação restante para humano): references/phase-commands.md -> Fase 6.
Portão: assembled/rough-cut.mp4 (ou assembled/remotion-output.mp4) existe. handoff-notes.txt escrito no disco.
Extração de Transcrição de Vídeo
Extraia a transcrição de um vídeo como parágrafos legíveis. Prefira legendas do uploader; recorra a geradas automaticamente.
# Caminho 1: legendas do uploader (precisas)
yt-dlp --skip-download --write-subs --sub-langs en --sub-format vtt -o '<work-dir>/%(id)s' '<URL>'
# Caminho 2: geradas automaticamente (fallback quando o caminho 1 não escreve arquivo)
yt-dlp --skip-download --write-auto-subs --sub-langs en --sub-format vtt -o '<work-dir>/%(id)s' '<URL>'
# Limpar VTT para parágrafos
python3 skills/research/video-transcript/scripts/vtt_to_paragraph.py <work-dir>/<id>.en.vtt
Opções: --timestamps para marcadores [mm:ss], --keep-brackets para tags de sinalização, -o FILE para saída em arquivo. Outros idiomas: alterar --sub-langs. Listar disponíveis: yt-dlp --list-subs '<URL>'.
Tratamento de Erros
| Erro | Causa | Solução |
|---|---|---|
| "No such file or directory" na origem | Caminho em cuts.txt não corresponde ao nome do arquivo | Execute cat source-inventory.txt. Coloque caminhos com espaços entre aspas. |
| FFmpeg "Invalid option" ou erros de codec | Codec indisponível ou erro de sintaxe de flag | `ffmpeg -codecs |
| Remotion "Could not find composition" | ID da composição não corresponde | Verifique src/index.ts para o ID registrado. Combine exatamente no comando de render. |
| Segmentos concatenados na ordem errada | O glob do shell ordena alfabeticamente, não pela EDL | Gere concat-list.txt a partir da ordem do cuts.txt, não do glob. |
| ElevenLabs 401 | ELEVENLABS_API_KEY não definida | export ELEVENLABS_API_KEY=your_key antes da Fase 5. |
| Nenhum arquivo .vtt da extração de transcrição | O vídeo não tem legendas no idioma solicitado | yt-dlp --list-subs '<URL>' e escolha um idioma disponível. |