Communitygithub.com

notque/vexjoy-agent

Pipeline de edição de vídeo: corte de cenas, montagem de clipes via FFmpeg e Remotion.

O que é vexjoy-agent?

Esta skill implementa um pipeline de 6 camadas para edição de vídeo, onde a IA lida com tarefas de julgamento (o que manter, o que cortar, seleção de destaques) e o FFmpeg/Remotion executam tarefas mecânicas de forma determinística. As camadas incluem captura de inventário, transcrição para EDL, cortes via FFmpeg, composição com Remotion, geração de assets com ElevenLabs/fal.ai, e polimento final humano. A skill é projetada para agentes como Claude Code e suporta fluxos de trabalho com TypeScript e Python, garantindo que o código gerado seja reproduzível e revisável. Ela também oferece referências detalhadas para comandos FFmpeg, scaffolding do Remotion e pipelines de imagem para vídeo, além de instruções claras para extração de transcrições de vídeo.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/notque/vexjoy-agent/tree/HEAD/skills/content/video-editing

Perguntar na sua IA favorita

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

Documentação

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.

CamadaNomeMecanismoFerramenta Principal
1CAPTURAInventário de filmagens de origemBash + Glob
2ESTRUTURA IATranscrição para EDLJulgamento LLM
3CORTES FFMPEGEDL para arquivos de segmentoFFmpeg (determinístico)
4COMPOSIÇÃO REMOTIONSegmentos para composição TSXRemotion + TypeScript
5GERAÇÃO IAPreencher lacunas com assets geradosElevenLabs / fal.ai (condicional)
6POLIMENTO FINALCamada de gosto humanoHumano + NLE

Referências Detalhadas

SinalCarregarConteúdo
Comandos de shell para cada fase, verificações de portãoreferences/phase-commands.mdBlocos de comando completos para Fases 1-6
Receitas FFmpeg: corte, concat, proxy, detecçãoreferences/ffmpeg-commands.mdExtração de timestamps, corte em lote, normalização de áudio, detecção de cena/silêncio
Scaffold de composição Remotionreferences/remotion-scaffold.mdTemplate de composição TSX, comando de render, padrões de reuso
Pipeline de imagem para vídeoreferences/image-to-video.mdFluxo de trabalho: validar, preparar, codificar, verificar
Grafos de filtro FFmpeg para visualizaçãoreferences/ffmpeg-filters.mdScale/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

ErroCausaSolução
"No such file or directory" na origemCaminho em cuts.txt não corresponde ao nome do arquivoExecute cat source-inventory.txt. Coloque caminhos com espaços entre aspas.
FFmpeg "Invalid option" ou erros de codecCodec indisponível ou erro de sintaxe de flag`ffmpeg -codecs
Remotion "Could not find composition"ID da composição não correspondeVerifique src/index.ts para o ID registrado. Combine exatamente no comando de render.
Segmentos concatenados na ordem erradaO glob do shell ordena alfabeticamente, não pela EDLGere concat-list.txt a partir da ordem do cuts.txt, não do glob.
ElevenLabs 401ELEVENLABS_API_KEY não definidaexport ELEVENLABS_API_KEY=your_key antes da Fase 5.
Nenhum arquivo .vtt da extração de transcriçãoO vídeo não tem legendas no idioma solicitadoyt-dlp --list-subs '<URL>' e escolha um idioma disponível.

Habilidades Relacionadas