promo-video

O que promo-video faz?

Monte vídeos promocionais curtos a partir de clipes brutos. Retrato, quadrado ou paisagem. Introdução/encerramento opcionais renderizados no Blender, música opcional gerada por IA.

A skill é agnóstica em relação ao agente hospedeiro: ela DEVE funcionar de forma idêntica em qualquer runtime que implemente o padrão Agent Skills (https://agentskills.io) — Claude, Claude Code, OpenAI Codex, Gemini CLI, Cursor, GitHub Copilot, Cline, OpenCode, OpenHands, Goose, Kiro, Junie, e outros. Nunca dependa de ferramentas específicas do hospedeiro (sem AskUserQuestion, sem comandos de barra, sem MCP a menos que explicitamente disponível). Conduza toda interação com o usuário como mensagens de chat normais.

Quando usar

• "Corte esses clipes juntos em um reel de 30 segundos."
• "Monte um vídeo promocional de hackathon no formato retrato."
• "Tenho uma pasta de vídeos de celular — faça um clipe social 1080x1920 com música."
• "Gere um promo com logo de introdução + encerramento com coração + trilha de fundo."
• O usuário referencia um diretório de arquivos .mov/.mp4 e quer um entregável.

Pré-requisitos

• ffmpeg no PATH, compilado com libx264, aac e prores_ks (o último só é necessário para MOVs de introdução/encerramento com canal alfa).
• Python 3.9+.
• Instale as dependências Python uma vez: pip install -r requirements.txt de dentro do diretório da skill.
• Opcional: um .env na raiz do projeto contendo SUNO_API_KEY para habilitar geração de música. A skill detecta automaticamente se a chave está definida e só oferece geração de música se estiver.
• Opcional: Blender MCP disponível no agente hospedeiro para produzir renderizações de introdução/encerramento. Veja references/blender_mcp.md.

Fluxo padrão (baseado em diálogo)

Passo 0 — Detectar se os clipes mudaram desde a última execução

Antes de fazer qualquer pergunta, verifique se o usuário está retomando de uma sessão anterior. Se gallery/.clips_snapshot.json existir (ou se o usuário apontar para uma pasta de clipes usada anteriormente), execute:

python scripts/clip_diff.py <clips_dir>

• Código de saída 0 — a pasta de clipes corresponde ao último snapshot. Continue.
• Código de saída 1 — houve alteração. O relatório lista clipes novos / removidos / modificados. Mostre-o ao usuário e ofereça executar novamente scripts/gallery.py para que a galeria capte os novos clipes. As seleções existentes para clipes que ainda estão presentes sobrevivem intactas.
• Código de saída 2 — nenhum snapshot ainda. Primeira execução normal, continue.

NÃO pule esta etapa ao retomar um projeto existente — trabalhar silenciosamente com uma galeria/selection.json desatualizada é o clássico bug "onde foram parar meus novos clipes?".

Perguntas

No início, faça as perguntas abaixo ao usuário, em ordem. Aceite respostas naturais; não apresente uma interface de múltipla escolha a menos que o hospedeiro suporte. Para cada pergunta, também aceite "você decide" e aplique o padrão sensato.

1. Formato alvo. 1080x1920 retrato (padrão), 1920x1080 paisagem ou 1080x1080 quadrado. Tamanhos personalizados são permitidos.
2. Fonte de clipes. Caminho absoluto ou relativo para um diretório contendo os clipes brutos. .mov, .mp4, .m4v são suportados.
3. Duração alvo em segundos. (Típico: 20–45 s.)
4. Música. Uma de: (a) arquivo de áudio existente, (b) gerar via Suno (só oferecer se SUNO_API_KEY estiver definida), (c) sem música.
5. Introdução. Uma de: nenhuma, imagem estática (caminho), gerada por Blender MCP.
6. Encerramento. Mesmas opções da introdução.
7. Modo diretor. Sim ou não. Se sim, siga references/director_mode.md em vez de continuar linearmente aqui.

Em seguida, lide com a seleção de clipes. Ofereça dois caminhos:

A) Galeria visual (recomendado para >10 clipes ou quando o usuário quiser ver quadros antes de escolher cortes). Execute scripts/gallery.py <clips_dir> --resolution WxH --fps 30 --target-length N — ele gera gallery/gallery.html com miniaturas, controles IN/OUT, controle de velocidade e pré-visualização de intervalo. Diga ao usuário para abri-lo em um navegador, escolher clipes, definir cortes e clicar em "Exportar selection.json". O arquivo baixado está pronto para build.py.

B) Diálogo inline (adequado para lotes pequenos ou quando não há navegador disponível). Passe por cada clipe você mesmo:

• cue_in e cue_out em segundos (intervalo de corte)
• speed multiplicador (1.0 = original)
• fixed: true se o tempo/velocidade foi curado manualmente, false para preenchimentos livres (padrão: 0.6 s do meio, velocidade 1.0)

Ofereça "Apenas use os padrões" — pegue cada clipe em ordem alfabética, padrões livres, até a duração alvo.

De qualquer forma, o resultado é um selection.json correspondente a templates/selection.schema.json. Valide antes de prosseguir.

Construção

Assim que selection.json for válido, execute:

python <skill>/scripts/build.py <selection.json> --out output/<nome>.mp4

build.py escreve artefatos intermediários em build/ (relativo ao diretório de trabalho atual): build/normalized/, build/trimmed/, build/montage.mp4, build/composed.mp4. Exclua build/ para forçar uma re-renderização completa.

Todo submódulo em scripts/ também pode ser executado independentemente — útil para iterar em uma etapa sem reconstruir todo o pipeline. Cada um aceita um argumento --help.

Modo diretor (opcional)

Opt-in. Veja references/director_mode.md para os prompts de papel. A skill aciona quatro papéis sequenciais — Narrador → Editor → Compositor → Supervisor — que compartilham selection.json como estado. Cada papel lê o JSON atual e escreve suas atualizações de volta. Use isso quando o usuário pedir "um processo mais guiado" ou "me guie como um produtor".

Geração de música (opcional)

Se o usuário escolheu "gerar via Suno", delegue a etapa de música ao subagente Song-Builder definido em references/song_builder_agent.md. Esse subagente:

1. Pergunta ao usuário sobre gênero, clima, faixa de BPM, estrutura de seções, instrumental ligado/desligado e usa a duração do vídeo como tempo.
2. Formula um prompt Suno + tags de estilo.
3. Chama scripts/music.generate_song(spec) — forneça takes > 1 se o usuário quiser opções para comparar.
4. Corta e faz fade no take escolhido para a duração do vídeo.
5. Escreve o caminho final do mp3 em selection.json como audio.

Se o hospedeiro fornecer um mecanismo de subagente (por exemplo, a ferramenta Agent do Claude Code), use-o. Caso contrário, desempenhe o papel inline na mesma thread.

Integração com Blender MCP (opcional)

Apenas assistência — esta skill não inclui uma cena do Blender.

Se o usuário quiser uma introdução ou encerramento renderizados no Blender, delegue ao subagente Blender-Builder definido em references/blender_builder_agent.md. Ele é responsável por todo o fluxo: pré-verificação (verificar se Blender + MCP estão realmente acessíveis neste hospedeiro), entrevista de design (direção visual, cores, duração), construção da cena, pré-visualização iterativa, renderização para ProRes 4444 com canal alfa MOV e entrega do caminho do MOV em selection.json.

Se o hospedeiro fornecer um mecanismo de subagente (por exemplo, a ferramenta Agent do Claude Code), ative-o. Caso contrário, desempenhe o papel inline. O fluxo de diálogo principal deve invocar o Blender-Builder sempre que o usuário escolher "gerado por Blender MCP" para introdução ou encerramento na etapa 5 do questionário.

A documentação de configuração (instalar Blender, instalar o servidor MCP, registrá-lo com o hospedeiro) está em references/blender_mcp.md. O subagente Blender-Builder usa esse documento quando o usuário precisa configurar a pilha pela primeira vez.

Recuperação de erros

• Se um clipe falhar na normalização (caso extremo de codec / resolução), build.py sai com um código diferente de zero e uma mensagem clara em stderr apontando para o arquivo problemático. Pergunte ao usuário se deseja pular o clipe ou investigar.
• Se Suno retornar um erro 4xx ou exceder o tempo limite, ofereça ao usuário tentar novamente, mudar para "arquivo existente" ou prosseguir sem música.
• Nunca descarte clipes silenciosamente. Nunca sobrescreva um arquivo de saída existente sem confirmação, a menos que --force seja passado.

Notas de estilo para esta skill

• Nunca assuma ferramentas específicas do hospedeiro. Todo diálogo é chat simples.
• Mostre seu trabalho. Ao cortar, informe ao usuário quais pontos de corte você escolheu antes de construir.
• Falhe alto. Se ffmpeg estiver faltando, diga isso e mostre o comando de instalação para a plataforma do usuário.