LawrenceHua/ai-ugc-video-pipeline

O que ai-ugc-video-pipeline faz?

Vídeos curtos de marketing com apresentador gerado por IA (cabeça falante + imagens reais do produto + legendas) têm um conjunto específico de modos de falha que só aparecem quando você realmente reproduz o arquivo final em um dispositivo real — não no ffprobe, nem em um script que busca posições na linha do tempo. Este é um pipeline com portões de verificação que os captura antes da entrega, além dos dois bugs de áudio que são fáceis de reintroduzir mesmo quando você já sabe da existência deles.

Quando usar

• Produzir um vídeo curto (vertical, 9:16) de marketing/produto com apresentador gerado por IA.
• Re-cortar ou iterar sobre um vídeo existente.
• Qualquer pipeline que monte imagens de cabeça falante geradas por IA + captura de tela real + legendas geradas via ffmpeg.

Ordem de fases não negociável — cada fase é um portão para a próxima

1. PREP (não gaste nada até que esta fase esteja verde). Pesquise o panorama atual de modelos para seu apresentador/geração de voz (preços e endpoints dessas APIs mudam mensalmente — verifique contra a documentação ao vivo do provedor antes de comprometer gastos). Escreva algumas variantes de roteiro, peça a um avaliador de texto para escolher uma, prepare seu material de referência de rosto/voz (com consentimento real e documentado para a identidade usada), capture as imagens reais do produto que você vai compor e escreva uma rubrica, além de um limite de orçamento rígido antes de gastar um centavo.
2. CALIBRAR. Gere primeiro um clipe curto e barato para validar o enquadramento e a aceitação da identidade antes de se comprometer com takes de tamanho completo. Se o enquadramento estiver errado, corrija a imagem de referência que você está alimentando o modelo, não a escolha do modelo.
3. GERAR. Takes mínimos e deliberados. Só faça A/B entre provedores/modelos quando tiver evidências de que um está com baixo desempenho — não faça solicitações aleatórias. Pare de gerar quando as pontuações estabilizarem; limite as iterações pagas (por exemplo, pare após 2, a menos que as pontuações ainda estejam subindo).
4. MONTAR. Use o filtro concat do ffmpeg, não o demuxer, para a montagem final (veja os bugs de áudio abaixo para entender o porquê). Cada reconstrução recebe um novo nome de arquivo — nunca sobrescreva no lugar, para que você possa sempre comparar com a última versão boa.
5. VERIFICAR. Execute seus portões de validação de mídia (abaixo) e uma pré-verificação de texto/honestidade em cada ativo de roteiro/legenda/cópia. Nenhuma entrega em caso de falha em qualquer portão.
6. ENTREGAR. Entregue o arquivo a um humano para aprovação final, com um breve documento de avaliações/notas. Publicar em qualquer plataforma é sempre uma decisão com portão humano — nunca publique automaticamente. Se o apresentador for uma semelhança sintética realista, use a opção de divulgação de conteúdo gerado por IA da plataforma, mesmo quando a divulgação no vídeo for uma escolha deliberada que você fez separadamente.

Os dois bugs de áudio que serão enviados silenciosamente se você não se proteger contra eles

1. A trilha de áudio de um segmento é mais curta que sua trilha de vídeo (narração termina antes do clipe de vídeo). Em uma concatenação com stream copy, a linha do tempo do áudio escorrega e efetivamente morre antes do final do arquivo final. Correção: preencha o áudio de cada segmento para corresponder à duração do vídeo e normalize cada segmento para a mesma taxa de amostragem/número de canais antes de concatenar.
2. Mesmo com preenchimento, o demuxer de concatenação pode deixar pequenas lacunas de temporização de pacotes (~0,1s) devido ao arredondamento da duração do áudio. Ferramentas que decodificam diretamente (ffmpeg, uma ferramenta de transcrição) passam por essas lacunas sem problemas e não sinalizam nada — mas alguns players reais param o áudio imediatamente na primeira lacuna, então um arquivo que "passa" em sua verificação automatizada ainda pode estar quebrado para um visualizador real. Correção: faça a montagem final como um filtro concat de passagem única (não o demuxer) com reamostragem de áudio forçada para uma linha do tempo contínua e sem lacunas.

A verificação que captura ambos: escaneie os timestamps dos pacotes de áudio do arquivo final em busca de qualquer lacuna maior que ~50ms. Valide a mídia da forma como um player real a consome — uma decodificação contínua + uma transcrição completa do arquivo — não buscando posições e amostrando, o que pode silenciosamente auto-ressincronizar exatamente em torno da lacuna que você está tentando capturar.

Protocolo do avaliador — avaliadores LLM alucinam sobre mídia, faça validação cruzada

• Avalie contra um proxy de compressão fixo e moderado (compressão muito agressiva exagera artefatos e distorce as pontuações contra o formato, não o conteúdo).
• Faça validação cruzada de cada alegação do avaliador sobre áudio com uma verificação determinística (uma transcrição + a varredura de lacunas de pacotes acima) antes de agir com base nela. Um avaliador chamando algo de "falha" pode estar certo OU errado pelo motivo errado — não confie nem descarte com base em intuição; execute a verificação determinística primeiro, depois decida.
• Para comparações A/B: mesma trilha de áudio, critérios fixos/pinados, ordenação consistente e force saída estruturada estrita — opiniões de avaliadores em texto livre são mais difíceis de agir e mais fáceis de racionalizar.
• Espere que um avaliador seja rigoroso. Publique com base em evidências (cada portão determinístico verde + aprovação de um humano real), nunca apenas no veredito de um avaliador.

Portões de honestidade e segurança — codifique-os como código, não como uma verificação de intuição

Execute uma pré-verificação automatizada em cada ativo de roteiro/legenda/cópia antes do envio:

• Nenhuma alegação fabricada sobre as capacidades ou resultados do produto.
• Nenhum uso não consentido do rosto ou voz de ninguém — obtenha e documente consentimento real antes de gerar com a semelhança de qualquer pessoa real e verifique a política de uso do provedor de geração para geração baseada em identidade.
• Nenhuma alegação apresentada como resultados reais de usuários que foram na verdade gerados/simulados.
• Quaisquer marcas ou nomes de produtos que não devam ser públicos permaneçam fora de roteiros, legendas e notas de publicação.
• A publicação em si é sempre uma etapa separada, com portão humano — o trabalho do pipeline termina em "pronto para revisão", nunca "publicado".

Disciplina de orçamento

Mantenha um livro-caixa contínuo (estimativa vs. real por geração) contra um limite rígido que você definiu no PREP, e pare de gerar quando as pontuações estabilizarem, em vez de continuar gastando além dos retornos decrescentes. Orçar antecipadamente e parar com base em evidências, em vez de "só mais um take", é o que mantém este pipeline acessível.

Como usar

Instalação: copie esta pasta para ~/.claude/skills/ai-ugc-video-pipeline/ para uso pessoal, ou .claude/skills/ai-ugc-video-pipeline/ dentro de um repositório de projeto. Você vai conectar sua própria escolha de provedor de geração de apresentador/voz e ferramentas de captura de tela — este skill é a metodologia de portões e as correções de modos de falha conquistadas com esforço, não uma integração de fornecedor específico.

Invocação:

Guie-me pela fase PREP do ai-ugc-video-pipeline para um vídeo de demonstração de
produto de 30 segundos — ajude-me a escrever as variantes de roteiro e o
livro-caixa de orçamento antes de gerarmos qualquer coisa.

Meu vídeo montado tem áudio que corta no meio em alguns players, mas funciona
normalmente no ffplay. Use a seção de bugs de áudio do ai-ugc-video-pipeline
para diagnosticar e corrigir.