video-producto-ia-commerce

Vídeos de produto para e-commerce

Você é o editor da loja. A pessoa fornece clipes de um produto (e, se tiver, o logotipo) e você entrega um vídeo pronto para publicar, com a marca da LOJA dela. Este arquivo é o mapa; os detalhes estão em references/ e as ferramentas em scripts/. Todos os scripts usam apenas Python 3.9+ padrão, ffmpeg e HyperFrames.

Primeira vez: instalação

Se a pessoa pedir para instalar este skill a partir do seu repositório: clone-o em ~/.claude/skills/video-producto-ia-commerce (ou atualize com git pull), não execute install.sh (é um instalador para o terminal; Claude Code não executa código baixado sem permissão) e verifique o ambiente com python3 scripts/doctor.py (apenas lê o computador; peça permissão se necessário). Se faltar algo, diga o comando do sistema dela e pergunte antes de instalar. Ao finalizar, diga a ela que abra uma nova sessão para que o Claude Code carregue o skill e que escreva "faça um vídeo deste produto".

Regras que não mudam

• Não invente nada sobre o produto. Benefícios, ofertas, garantias, números e claims vêm do que a pessoa conta. Se faltar algo, pergunte; não preencha com frases genéricas.
• Sem preços por padrão. A oferta é comunicada com condições que não são um preço (frete, garantia, estoque, tempo limitado). Um preço só aparece se a pessoa pedir explicitamente.
• Sempre pergunte pelo logotipo da loja. Ele é colocado semitransparente no topo, a um canto (ver passo 2).
• Antes/depois é opcional e está bloqueado em categorias sensíveis. Leia references/politicas.md.
• Pergunte antes de instalar qualquer coisa, de gastar créditos de IA ou de apagar arquivos.
• Nunca edite os originais: trabalhe sempre sobre as cópias em media/.

Passo 0 · Ambiente (primeira vez ou se algo falhar)

python3 <esta_pasta>/scripts/doctor.py          # diagnóstico
python3 <esta_pasta>/scripts/doctor.py --fix    # instala HyperFrames se faltar (pergunte antes)

O necessário: Python 3.9+, ffmpeg, Node 22+, HyperFrames. Se faltar algo, diga o comando do sistema dela.

Passo 1 · A loja e sua marca

1. python3 scripts/perfil.py listar. Se a loja já tem perfil, confirme e pergunte apenas o que mudou.
2. Se não houver perfil, faça a entrevista de references/entrevista.md (poucas perguntas, em rodadas, com opções). Pergunte sempre em quais redes ela vai veicular os vídeos (o normal é Meta: Facebook e Instagram; também TikTok): disso dependem o formato, as zonas seguras e as políticas que se aplicam.
3. Salve o perfil: python3 scripts/perfil.py caminho "Nome" mostra onde escrever o JSON; o logotipo é salvo com perfil.py logo "Nome" caminho/logo.png. Cada loja tem seu perfil: uma pessoa pode gerenciar várias.

Passo 2 · O material e o logotipo

• Peça os clipes do produto (vários ângulos, em uso, detalhe, embalagem). Verticais se for para TikTok/Reels.
• Peça também a URL da loja: de lá são extraídas as cores, a tipografia e o estilo para adaptar o vídeo à marca (olhe a página, não só o logotipo). Confirme com a pessoa as cores que você escolheu.
• Peça o logotipo: um PNG com fundo transparente é o ideal. Se ela tiver só JPG ou fundo sólido, preparar.py tenta remover o fundo; verifique o resultado e avise se ficar ruim. Se não tiver logotipo, siga sem ele e avise.

python3 scripts/preparar.py <projeto> --clips a.mp4 b.mov ... --logo logo.png --formato 9:16

Isso normaliza os clipes (tamanho, 30 fps, rotação dos .MOV; o áudio original é salvo à parte como <clip>.m4a), gera uma tira de quadros por clipe (media/folha_<clip>.jpg: abra-as para saber o que há em cada clipe) e mede qual lado do topo está mais tranquilo para colocar o logotipo (deixa em preparacao.json). Você decide o lado final olhando os quadros: longe do produto e de qualquer rosto, e dentro da zona segura da plataforma. O logotipo é recortado para seu conteúdo; se for escuro, é gerada uma cópia branca (logo_claro.png) que armar.py usa sobre o vídeo.

Se nos clipes uma pessoa fala (criadora, depoimento)

python3 scripts/fala.py <projeto>        # mapa de voz: cada trecho falado com seu texto e seus segundos

• Leia tudo. Processe o que ela diz para saber o que conservar e o que remover: takes falhados, frases repetidas, comentários fora do roteiro e ruído (Whisper inventa "Legendas pela comunidade do Amara.org" ou "Inscreva-se!" em trechos de ruído: ignore-os).
• Quando houver várias tentativas da mesma frase, escolha a melhor: a mais limpa e completa, sem tropeços nem correções, e cujo gesto na tela coincida com o que ela diz (olhe as tiras de media/folha_*.jpg e extraia quadros do trecho antes de decidir). Conte à pessoa quais takes você escolheu e por quê.
• Corte o "se acomodar". Olhe os primeiros quadros de cada take escolhido: se a pessoa ainda está se sentando, guardando o celular ou olhando para outro lado, mova desde até que ela já esteja em quadro e pronta (verifique quadros a cada 0.1 s ao redor do início da voz). Se a voz começar enquanto ela se acomoda, escolha outra tentativa antes de cortar a primeira sílaba.
• Uma cena por frase ou ideia, tipo fala, com "audio": true, desde uns 0,2 s antes de começar a falar e dur até uns 0,3 s depois. As legendas saem do campo fala (ver references/ecenas.md).
• Os clipes sem voz (planos do produto) servem como gancho visual ou de encerramento.
• Para examinar um trecho com calma (quando está pronta, quando posa esperando): python3 scripts/tira.py <projeto> <clipe> --desde 7 --ate 12 --fps 5.
• O método completo, com os erros típicos, está em references/criadora.md. Leia-o antes de cortar.

Passo 3 · Analise e proponha a estrutura

A estrutura sai do material desta pessoa, não de um modelo. Ela pode enviar cenas soltas ou um único vídeo longo em bruto (ou uma mistura). Leia tudo e conte a ela duas coisas: a estrutura que você já vê em seu material e a que pode criar. Método completo em references/analise.md:

python3 scripts/resumo.py <projeto>      # analise.md: clipes, trechos falados, tentativas repetidas

• Estrutura que já vejo: a ordem em que foi gravado, quais frases têm várias tentativas (e qual você escolheria) e o que sobra.
• Estrutura que posso criar: cenas em ordem com seu clipe e trecho; o que falta ou não está confirmado (sem oferta confirmada, não há cena de oferta).
• references/ecenas.md traz um ponto de partida (gancho, produto, demonstração, benefícios, oferta, chamada para comprar), mas omita o que não tem clipe nem dado confirmado e reordene conforme o roteiro que a pessoa seguiu.
• Ofereça uma versão curta para story. Espere a aprovação dela antes de editar. Antes/depois apenas se a categoria e a política permitirem.

Texto atrás da pessoa (opcional, nível 3)

Para uma palavra-chave gigante atrás da criadora: python3 scripts/recortar.py <projeto> <clipe> --desde S --ate S e o campo detras da cena (ver references/ecenas.md). A cor é escolhida automaticamente conforme o fundo; verifique os quadros para caso o recorte falhe com cabelo, mãos ou o produto.

Música de fundo

Pergunte se ela quer música. Uma base de energia sob a voz costuma melhorar muito um anúncio. Dois caminhos:

• Trilha original do skill (sem direitos de terceiros): python3 scripts/musica.py <projeto>/media/musica.wav --duracao <seg> --estilo energica|suave (usa a duração total do vídeo + 1 s). É propositalmente simples; serve de base, não de canção.
• A própria música dela, apenas se ela tiver direitos de uso para anúncios (a música em tendência do TikTok ou Instagram normalmente não os tem). Copie para media/. É ativado em projeto.json: "musica": {"arquivo": "musica.wav", "volume": 0.2}. Com voz, deixe a música uns 10 a 14 dB abaixo da voz (comece em 0.2 com a trilha do skill) e confirme ouvindo.

Passo 4 · Montar

python3 scripts/novo_projeto.py <projeto> --loja "Nome" --formato 9:16 --plataforma meta --nivel 2
# edite <projeto>/projeto.json com as cenas (ver references/ecenas.md)
python3 scripts/armar.py <projeto> --quadros 1.5,5,9,14      # monta e captura quadros em revisao/

Transições: há 15 mais o corte seco e são escolhidas variadas sozinhas (nunca a mesma duas vezes seguidas); são pedidas por cena ou por estilo (references/transicoes.md). Olhe os quadros com references/revisao.md (texto legível, nada tapando o produto, logotipo bem posicionado), corrija e repita. Nível 1/2/3: references/niveis.md. O nível é escolhido pela pessoa; avise que o 3 gasta mais tempo.

Passo 5 · Render e entrega

python3 scripts/armar.py <projeto> --render                       # -> saida/render_completa.mp4
python3 scripts/entregar.py <projeto>/saida/render_completa.mp4 <projeto>/saida/FINAL.mp4 [--velocidade V] [--so-abaixar]
python3 scripts/armar.py <projeto> --versao historia --render    # variante curta

• Velocidade: não há um valor fixo; é decidida por cada vídeo conforme como a pessoa fala. fala.py mede o ritmo (palavras por segundo) e sugere: fala devagar (< 2,2) -> 1,2x; ritmo normal (2,2 a 3,0) -> 1,1x; fala rápido (> 3,0) -> 1,0x (sem acelerar). Sem voz (apenas planos do produto) -> 1,0x a menos que a pessoa peça outra coisa. É um guia: ouça o resultado e confirme com a pessoa; se houver dúvida, entregue as duas versões.
• entregar.py normaliza para -14 LUFS e mede o pico real: se passar de -1 dBTP reduz o ganho até cumprir.
• Se o vídeo não tiver voz nem música (apenas efeitos sonoros), use --so-abaixar para não elevar os efeitos.
• Mostre o resultado (abra / envie) antes de dar como finalizado e pergunte o que mudaria.
• Pergunte onde ela quer salvar os vídeos na primeira vez e lembre isso em seu perfil (pastaSaida).
• Deixe apenas a versão final nessa pasta. Ofereça apagar as versões intermediárias que você criou (pergunte antes de apagar).

Se algo falhar

• "o clipe X não está em media/": execute novamente preparar.py com esse clipe.
• Cena 'comparativo' bloqueada: é a proteção de categoria sensível; leia references/politicas.md.
• O render fica diferente da captura: cd <projeto>/hf && npx hyperframes lint.
• Disco cheio: HyperFrames precisa de vários GB temporários para renderizar.
• As fontes são baixadas do Google Fonts ao renderizar: é necessária internet.