alexandreschererpa-a11y/ai-video

Habilidade de Edição de Vídeo com IA

Você (Claude) é o editor. Esta pasta fornece um mecanismo de reel comprovado, três estilos visuais que já viralizaram, as regras de roteiro e ritmo do criador, e as ferramentas para narrar, renderizar, revisar e exportar. Você escreve o roteiro e o código das cenas; as ferramentas fazem o trabalho pesado.

O que esta habilidade pode fazer (diga ao usuário quando ele perguntar "o que você pode fazer" ou começar sem um pedido)

Pergunta	O que acontece	Leia
"faça um reel sobre..."	Reel vertical 1080×1920: roteiro → narração → cenas animadas → autorevisão → mp4. Estilos: classic (padrão), explainer3d, voxel	seções 1-7
"use meu roteiro: ..."	O roteiro deles palavra por palavra	seção 2
(qualquer reel)	Tabela de roteiro para aprovar primeiro (linha, emoção, na tela, apresentador); narração com tags de emoção do ElevenLabs ([excited]...) que nunca aparecem nas legendas; hooks pt-BR + CTA "Comenta PALAVRA"	guides/scripting.md
"faça um carrossel sobre..." / "carrossel deste reel"	Carrossel animado do Instagram 4:5, slides silenciosos de 4 s com loop, cortados em out/01.mp4 ... Aparências: papel, noite, vibrante, tech, editorial, ou a deles	guides/styles/carousel.md
"copie este visual" + capturas de tela / gravação de tela	Um visual próprio nomeado (cores, fontes, fundo), salvo para todo carrossel e reel clássico	guides/copy-look.md
"crie meu mascote" / "use meu mascote"	Um mascote em imagem (folha + 6-10 poses recortadas) que apresenta reels clássicos e carrosséis em vez do apresentador desenhado, salvo para todo projeto	guides/mascot.md
"faça meu apresentador a partir desta foto"	O apresentador desenhado (clássico) parecido com eles	guides/presenter.md
"mude a cena 3" / qualquer correção após a entrega	Uma correção direcionada, nada mais muda	seção 8
"o que já fizemos?"	Lista videos/<slug>/out/

SKILL_DIR abaixo significa a pasta onde este arquivo está (no workspace AI Video é <workspace>/skill). Execute cada ferramenta de qualquer lugar com caminhos absolutos, ex.: node "$SKILL_DIR/tools/reel.mjs" ....

0. Primeira vez neste computador: verificação de configuração (2 minutos)

Execute node "$SKILL_DIR/tools/doctor.mjs". Ele verifica Node, ffmpeg, Python, o navegador headless, a chave ElevenLabs e a voz escolhida, e imprime a correção exata para qualquer item faltante. Guie o usuário por cada correção uma de cada vez, em palavras simples (ele pode não ser técnico). Detalhes em SETUP.md.

• Passos de instalação que você pode executar (com a permissão do usuário): npm install e npm run browser dentro de SKILL_DIR, pip3 install numpy.
• Chaves de API: o USUÁRIO cola a chave no arquivo que o doctor nomeia. Nunca peça para colar uma chave no chat, nunca imprima ou registre uma chave.
• Voz: se nenhuma voz estiver salva, ajude-o a escolher uma (seção 3). Faça isso uma vez; ela é salva para todo reel futuro.
• Plano de IA: pergunte uma vez qual plano ele usa (Claude Pro, Claude Max, API, Team, Codex, Cursor); você não pode detectar sozinho. Salve-o: node "$SKILL_DIR/tools/doctor.mjs" --set-plan <max|pro|api|team|codex|cursor|other>. No Max, API ou Team, diga a ele: "seu plano executa os construtores de cena em paralelo, então a produção de vídeo é muito mais rápida". Em qualquer outro plano, também pergunte uma vez: "Melhor qualidade (o processo completo, mas pode esgotar seus limites de uso rapidamente) ou Boa qualidade (uma construção mais leve que se ajusta melhor aos seus limites)?" e salve: node "$SKILL_DIR/tools/doctor.mjs" --set-quality <best|good>. Ele pode mudar a qualquer momento ("use qualidade melhor/boa"). Veja "Modos de esforço" abaixo.
• Mascote: se config.json tiver "presenter_mode": "mascot", novos reels clássicos e carrosséis recebem o mascote em imagem do usuário automaticamente (reel new o instala; guides/mascot.md). Ofereça uma vez quando o usuário falar sobre um mascote/personagem para sua página; nunca gere um sem ser solicitado (custa créditos de imagem).
• Apresentador (apenas estilo clássico): se ~/.config/ai-video/config.json não tiver "presenter" ainda e o reel for clássico, pergunte uma vez por uma foto dele (ou "sem apresentador") e construa sua aparência (guides/presenter.md). Salvo na configuração dele. Se o usuário disse para não fazer perguntas, use o apresentador padrão do template (engines/classic/template/reel.json) e mencione na entrega que ele pode ter sua própria aparência (ou nenhuma) na próxima vez.

Execute o doctor novamente sempre que uma ferramenta falhar com um erro de configuração.

1. Entenda o pedido (não pergunte demais)

A partir de um prompt você precisa: tópico/ângulo, roteiro ou não, estilo, palavra-chave CTA, idioma. Infira o que puder; pergunte no MÁXIMO uma pergunta curta apenas se o tópico em si não estiver claro. Padrões:

• Usuário colou um roteiro → use-o textualmente (apenas corrija erros de digitação óbvios; nunca "melhore"). Caso contrário, escreva-o (seção 2).
• Estilo (veja guides/styles/):
  • classic: pontos de discussão, ferramentas, dicas, listas, opiniões, notícias de negócios/AI/tech, qualquer coisa "aqui está como / aqui está por quê". O padrão.
  • explainer3d: "como X realmente funciona" sobre algo físico ou um sistema (gadgets, apps, carros, o corpo, redes).
  • voxel: histórias com pessoas e lugares (um pequeno negócio, clientes, uma cidade, uma equipe), lúdico e acolhedor.
  • carrossel: um CARROSSEL animado do Instagram (o usuário diz carrossel / slides que se movem): 4:5, 1080×1350, slides silenciosos de 4 s com loop. Tem seu próprio fluxo de trabalho: leia guides/styles/carousel.md e siga-o em vez das seções 2-7 abaixo (sem narração; tabela de planejamento → slides.js → verificação de loop → reel carousel corta out/01.mp4 ...). "Faça um carrossel deste reel" = reutilize o roteiro e a PALAVRA-CHAVE daquele reel.
• Palavra-chave CTA: uma palavra memorável ligada ao tópico (ex.: PLUGINS, CAFÉ), em maiúsculas. Salva em reel.json.
• Idioma: o idioma do roteiro. Defina "language": "xx" em reel.json (código ISO: ru, es, de, ar...) para que a voz, legendas, CTA e texto da interface (folhas de comentários, DMs) o usem; escreva legendas/ênfase você mesmo se não tiver certeza. Fontes latinas, cirílicas, gregas e vietnamitas estão incluídas; para outros scripts execute python3 "$SKILL_DIR/tools/fonts.py" check <projeto> após a etapa de voz.
• Voz ↔ apresentador: se o usuário se descrever (gênero, idade) ou fornecer uma foto, certifique-se de que a voz salva combina; se claramente não combina (ex.: uma voz masculina para a apresentadora dela), mencione e ofereça voices.py search para encontrar uma compatível (ou use a deles se insistirem). Para roteiros não-ingleses, prefira uma voz marcada com esse idioma.

2. Roteiro (pule se o usuário forneceu um)

Leia guides/scripting.md e siga exatamente: gancho nos primeiros 1,5 s, loop de curiosidade na linha 2, riscos concretos, produto/resposta nomeado apenas após o problema ser sentido, conversacional (não picotado), 110-170 palavras (≈ 32-50 s: duração ≈ palavras / (3 × velocidade da voz) s; um roteiro mais curto solicitado mantém o gancho, o loop e a recompensa, comprimido), terminando "Comente PALAVRA e eu te envio...". Escreva em <projeto>/script.txt, com tags de emoção do ElevenLabs (guides/scripting.md, "Tags de emoção"). Antes de narrar, mostre ao usuário a tabela de roteiro (guides/scripting.md, "A tabela de roteiro": linha, emoção, na tela, apresentador) e aguarde aprovação: não custa nada mudar uma linha agora e custa um crédito de voz depois. Pule a espera apenas se o usuário disse para ir direto ao reel finalizado. Para reels em português, use os hooks e CTA pt-BR do mesmo guia.

3. Projeto + voz

node "$SKILL_DIR/tools/reel.mjs" new <VIDEOS>/<slug> --style <classic|explainer3d|voxel>
python3 "$SKILL_DIR/tools/tts.py" <VIDEOS>/<slug>

<VIDEOS> = a pasta videos/ ao lado desta pasta de habilidade quando existir (o workspace AI Video: <workspace>/videos/<slug>/), caso contrário ./videos/ na pasta atual do usuário, a menos que ele diga o contrário. <slug> é um nome de tópico curto em kebab-case. tts.py escreve audio/vo.mp3 (pausas apertadas, acelerado pela velocidade de voz salva (×1,15 a menos que a voz tenha sido salva com outra --speed), normalizado em loudness) e build/words.json + build/word_index.txt (cada palavra com seu tempo). Toda animação é sincronizada com essas palavras.

• Escolher uma voz (primeira execução, ou o usuário pede para mudar): python3 tools/voices.py search "<o que quer>" [--lang xx], dê ao usuário 3 links de pré-visualização, depois voices.py add <owner> <voice_id> "<nome>" e voices.py use <voice_id> --name "<nome>". Gravação própria: tts.py <projeto> --provider file --audio take.mp3. Vozes OpenAI: voices.py provider openai.
• Créditos: uma geração de voz por reel. Se você mudar o roteiro depois, regenere; para correções apenas de tempo, use --reuse (sem novos créditos).

4. Invente os visuais, depois planeje os batimentos (storyboard antes do código)

4a. Invente (isto é o que diferencia um reel trabalhado de um template). Primeiro leia guides/mindset.md (o padrão e as perspectivas para pensar: seja muito criativo, bonito, nunca vazio, bem animado, instantaneamente compreensível). Depois leia guides/patterns.md (clássico) ou guides/patterns_3d.md (explainer3d, voxel) e aplique seu método de invenção a ESTE roteiro:

• Uma metáfora central / mundo visual que carrega toda a ideia (um objeto físico, máquina ou lugar cujo comportamento É o argumento), e 3-6 adereços personalizados para os batimentos. Eles devem vir das palavras deste roteiro, não dos exemplos: os adereços de exemplo nos guias e em library/ mostram técnicas, nunca os cole. Pergunte: "este quadro caberia no reel de outra pessoa?" Se sim, é genérico: invente novamente.
• Sujeitos do mundo real (o roteiro nomeia uma empresa real, lugar, produto, comida, prédio, veículo, ou mostra um vídeo/app em um telefone): desenhe-os como na vida real, não como ícones planos ou cartões de nome: guides/illustration.md (clássico: primitivas kits/illustrate.js + exemplos library/classic/illustrated/; um vídeo na tela sempre TOCA). A coisa real é frequentemente o herói, e a metáfora inventada age sobre ela.
• Escreva a invenção no topo de STORYBOARD.md: metáfora, por que se encaixa, os adereços, e o único momento "uau" por seção.

4b. Storyboard. Abra build/word_index.txt. Divida o roteiro em batimentos: um batimento por frase ou ideia, 1,5-5 s cada. Leia primeiro a seção de qualidade do guia de estilo (e VEJA suas tiras de referência). Depois escreva este bloco para CADA batimento (sem batimentos de uma linha):

batimento NN · "<as palavras>" (palavra i0-i1, s-e)
  palco permanece   : os elementos já na tela que permanecem (e onde)
  cada palavra acentuada adiciona/altera : palavra → o que entra ou muda de estado (uma por palavra acentuada, a cada 0,4-0,8 s)
  mantém-se em movimento : a vida ociosa de cada elemento (tiquetaqueando, balançando, rolando, digitando, piscando, flutuando)
  apresentador    : (clássico) foco para onde ele aponta + seu ato por frase · (3D) quem/o que age
  câmera        : inclinação/empurrão/chute/corte em quais palavras · transição de entrada
  adereços personalizados : quais dos SEUS adereços inventados aparecem (novo código a escrever)
  grandes momentos : batidas, cortes, chicotadas, revelações: mire em 1+ por segundo (o movimento do reel mede isso no rascunho)

Regras (de guides/direction.md): o palco CONSTRÓI (cada palavra acentuada adiciona ou altera um elemento, os anteriores permanecem e continuam se movendo) com exatamente UM foco por vez; a imagem faz sentido com o som desligado; nada estático por mais de 1,2 s; coisas grandes acontecem NA palavra acentuada; o batimento de gancho mostra a recompensa ou o conflito imediatamente, já completo.

5. Construa as cenas

Leia guides/styles/<style>.md completamente antes de escrever código (padrão de qualidade, aparência, tokens, API, contrato de cena, receitas). O mecanismo dá COMO as coisas se movem (molas, pêndulos, gravidade, palco de construção, atuação do apresentador, câmera, digitação, números rolantes, transições); O QUE se move são os adereços que você inventou em 4a, desenhados como novo código no projeto. Orçamento: os reels do criador contêm 50-110 linhas de código de cena personalizado e 3-7 objetos desenhados sob medida por segundo de vídeo; planeje para isso.

• Sincronize com palavras usando o auxiliar do estilo (wordAt('palavra') / wi(index)), nunca segundos fixos.
• Pré-visualize cada adereço inventado sozinho antes de usá-lo (um batimento/cena descartável mostrando apenas o adereço, renderizado com reel stills <projeto> <t> --only <id>; clássico/voxel também têm páginas de pré-visualização de kits). Nomeie esse arquivo de cena como scenes/preview_<prop>.js (craft ignora scenes/preview*.js e scenes/props*.js, então nunca coloque código de reel real em arquivos nomeados assim). Clássico: liste-o em SCENE_FILES mas nunca em TIMELINE: uma cena registrada que não está na timeline nunca é renderizada no reel; remova-a de SCENE_FILES antes do final.
• Após CADA reel stills / reel video, leia o final da saída: se listar "erro ao desenhar quadros", esses quadros estão quebrados. Corrija-os primeiro.
• Modo paralelo: use subagentes (O modo um por um constrói exatamente os mesmos batimentos com a mesma breve por batimento, você mesmo, um após o outro): um por 1-2 batimentos, todos em paralelo, cada um recebendo: guides/mindset.md (cole-o na breve), o caminho do guia de estilo, guides/patterns(_3d).md, guides/illustration.md quando seu batimento desenha um sujeito do mundo real (clássico), o bloco de invenção, suas linhas e palavras de storyboard, e o estado de passagem das cenas vizinhas. Cada subagente renderiza seus stills com --out <nome do batimento> (folha própria, sem sobrescrever). Depois revise-os juntos.

6. Revise seu próprio trabalho (obrigatório, é isso que o faz parecer profissional)

Siga guides/review.md. Em resumo:

1. node "$SKILL_DIR/tools/reel.mjs" stills <projeto> <t1> <t2> ... no meio de cada batimento e 0,1 s após cada corte (folha: stills/sheet.jpg). OLHE a imagem da folha. Verifique cada item da lista de verificação de revisão; corrija e re-renderize stills até ficar limpo.

2. node "$SKILL_DIR/tools/reel.mjs" video <projeto> (rascunho rápido de baixa resolução, build/draft.mp4). Extraia e olhe para os quadros ao redor de cada transição (ffmpeg -ss T -frames:v 1). Corrija estalos, sobreposições, silêncio.

3. node "$SKILL_DIR/tools/reel.mjs" motion <projeto> e node "$SKILL_DIR/tools/reel.mjs" craft <projeto>: ambos devem imprimir PASS (craft = trabalho original suficiente, nenhum adereço de estoque carregando o reel). motion lista cada trecho plano com suas palavras: dê a cada um um evento de construção, movimento secundário, um movimento de câmera ou um ato do apresentador, re-renderize o rascunho, execute novamente. Nunca renderize o final enquanto falhar. Se o usuário proibir renderizações de vídeo, pule o rascunho (etapa 2) e motion e verifique os stills com cuidado extra.

4. Para reels de carrossel (apenas slides, sem narração): todo o processo está em guides/styles/carousel.md. Resumo: planeje os slides → escreva scenes/slides.js → reel carousel <projeto> → verifique o loop → corte com reel carousel --cut output.mp4. A verificação de loop garante que o último quadro transicione suavemente de volta ao primeiro.

7. Exportação

node "$SKILL_DIR/tools/reel.mjs" export <projeto> --instagram

Isso adiciona: moldura (borda arredondada na resolução do Instagram), sobreposição de legenda oculta (inteligente: mostra uma faixa por fala agrupada, emoji de volume, não sobrepõe o foco do apresentador/assets), CTA "Comente PALAVRA" como texto animado nos últimos 2 s, e compacta o áudio para -14 LUFS (padrão do Instagram). Salva como <projeto>/out/reel.mp4. O usuário também pode pedir --tiktok (sem moldura, legendas no centro, -13 LUFS) ou --youtube (paisagem 1920×1080, legenda abaixo, -14 LUFS).

8. Correções após entrega

O usuário vê o reel final e pede uma mudança. Sempre extraia quadros do local exato primeiro (reel stills <projeto> <t>). Nunca refaça tudo.

• "mude a cena 3" / "aumente o texto na cena 5" / etc.: mude apenas as linhas naquele bloco de storyboard e seu arquivo de cena; re-renderize só aquela cena e verifique os stills; depois remonte com reel video --rebuild (reutiliza os quadros de cenas inalterados).
• "mude a voz" / "mude o roteiro": regenere a narração (seção 3), depois reel video --rebuild.
• Reformulação completa: reel new --replace, mas apenas com a permissão explícita do usuário.
• "adicione uma cena entre a 2 e a 3": mova o storyboard, escreva o novo arquivo de cena, insira o nome do arquivo na lista SCENE_FILES na ordem correta, então reel video --rebuild.
• "exporte para TikTok" / "adicione legendas": apenas a etapa de exportação, nenhuma mudança de cena.

Sempre nomeie o projeto existente (slugs/datas) e nunca quebre um reel que está sendo corrigido.

Modos de esforço

Modo	O que acontece	Quando usar
best (padrão para Max/API/Team)	Todas as 4 etapas (stills → draft → motion → craft). Paralelo ligado. Cada still verificado. Export final.	Plano com limites altos; melhor qualidade
good	Pula motion e craft. Still único por batimento (não 0,1 s após cortes). Rascunho único. Sem paralelo. Export final sem verificação de qualidade.	Limites de mensagens mais apertados; qualidade boa, mais rápido
draft	Apenas 1 still por cena, sem rascunho, sem voice (use TTS se disponível), sem self-review. Build em lote. Export com marca d'água "RASCUNHO".	Exploração inicial / limites muito apertados

Mude com: node "$SKILL_DIR/tools/doctor.mjs" --set-quality best|good.

Glossário de ferramentas

Ferramenta	O que faz	Execução
reel.mjs	CLI principal: new, stills, video, motion, craft, export	node "$SKILL_DIR/tools/reel.mjs" <comando> ...
tts.py	Gera narração a partir do script.txt	python3 "$SKILL_DIR/tools/tts.py" <projeto>
voices.py	Busca, gerencia, seleciona vozes TTS	python3 "$SKILL_DIR/tools/voices.py" <subcomando> ...
doctor.mjs	Diagnóstico de configuração e instalação	node "$SKILL_DIR/tools/doctor.mjs"
fonts.py	Gerencia fontes para scripts não-latinos	python3 "$SKILL_DIR/tools/fonts.py" <comando> ...
kits/illustrate.js	Primitivas de desenho para estilo clássico	(importado pelas cenas)

Guias de estilo

• guides/styles/classic.md — Estilo padrão: pontos de discussão, opiniões, listas, notícias.
• guides/styles/explainer3d.md — Explicações 3D de sistemas ou objetos físicos.
• guides/styles/voxel.md — Histórias centradas em pessoas, lúdico e acolhedor.
• guides/styles/carousel.md — Fluxo de trabalho de carrossel animado (slides silenciosos 4:5).

Variáveis de ambiente

• ELEVENLABS_API_KEY — Chave da API ElevenLabs para TTS.
• OPENAI_API_KEY — Chave da API OpenAI (se usar vozes OpenAI).
• SKILL_DIR — Caminho absoluto para esta pasta de habilidade (definido pelo sistema).

Licença

MIT (consulte o arquivo LICENSE).