bluemountain1231/cinematic-web-promo

video-shotcraft：Criação de Vídeos com Estilo Cinematográfico para Produtos

Uma biblioteca de produção autossuficiente: 152 cartas de lentes cinematográficas (com código-fonte de demonstração e galeria de amostras dinâmicas), um modelo de vídeo promocional completo e verificado, componentes reutilizáveis e ativos de áudio, e um fluxo de trabalho em seis etapas. O foco atual são vídeos promocionais para web/produtos de desktop, mas as cartas de lentes são um vocabulário de efeitos universais — você pode usá-las individualmente para criar cenas avulsas em qualquer vídeo.

Ao Chamar, Primeiro Julgue o Modo

O vídeo promocional completo tem três modos que não se misturam. Antes de iniciar a coleta de material, storyboard ou implementação, determine se o usuário já escolheu um modo explicitamente; se já escolheu, execute diretamente sem perguntar novamente ou mudar para outro modo.

1. Usar o Template Diretamente: Mantenha o fluxo de substituição original do Ink Press. Leia template/TEMPLATE.md e substitua as capturas de tela, textos e informações de marca do produto alvo de acordo com a estrutura de cenas existente.
2. Criação Autônoma e Livre: Leia references/pipeline.md. O agente decide autonomamente a direção visual, mapeamento de lentes, storyboard, materiais e áudio com base nos requisitos e conteúdo do projeto fornecidos pelo usuário, progredindo continuamente até o vídeo final; não pause para confirmação do usuário nas fases de briefing do produto, styleframe, mapeamento de lentes ou storyboard.
3. Cocriação: Leia references/guided-free-creation.md. O agente primeiro apresenta julgamentos e propostas fundamentadas, e o usuário confirma sequencialmente o briefing do produto, decisões de requisitos, direção visual, mapeamento de lentes e storyboard final; após a aprovação do storyboard, siga para a fase final de coleta de materiais e produção no references/pipeline.md.

Quando o usuário fornecer o caminho do projeto, URL, gravação de tela ou capturas de página, mas ainda não escolheu o modo, faça primeiro uma verificação mínima e somente leitura do produto: entenda o posicionamento do produto, funcionalidades principais, visuais da página, estado exibível e riscos de material; não modifique o projeto de negócios, não colete dados sensíveis e não escreva código de vídeo. Após a verificação, apresente os três modos e explique:

• Se o Ink Press é adequado para o produto, com justificativas específicas para adequação ou não adequação;
• Se a criação autônoma e a cocriação são adequadas e quais pistas visuais do produto serão mantidas;
• Qual modo o agente recomenda, com justificativas e trade-offs.

Em seguida, pergunte explicitamente: "Com base na verificação do produto acima, recomendo usar o modo ××. Devemos continuar com este modo?" Ao mesmo tempo, informe ao usuário que ele pode visitar https://vincentwei1021.github.io/video-shotcraft/ para navegar pelas amostras dinâmicas e escolher os efeitos de movimento que deseja usar no vídeo.

Quando o usuário ainda não forneceu um projeto ou página para verificação, apresente brevemente os três modos e pergunte; não recomende o Ink Press como padrão apenas porque é um template pronto.

• Usuário escolhe template: Leia template/TEMPLATE.md completamente e execute conforme o fluxo do template original.
• Usuário escolhe criação autônoma: Leia references/pipeline.md completamente. O agente avança autonomamente, sem esperar confirmação por etapa.
• Usuário escolhe cocriação: Leia references/guided-free-creation.md completamente e colabore seguindo os pontos de confirmação.
• Usuário ainda não decidiu: Pare aqui e aguarde a escolha; não escolha pelo usuário nem comece a produção.

Exceção 1: Quando o usuário já mencionou o template Ink Press, considere o modo template como selecionado. Por exemplo: "Faça um vídeo promocional para meu produto usando o template Ink Press." Nesse caso, não pergunte novamente; leia template/TEMPLATE.md completamente e execute conforme a rota do template.

Exceção 2: Quando o usuário especificou explicitamente o uso ou referência a certas cartas de lentes, as restrições de lentes já estão definidas. Por exemplo: "Use deck-deal-flyin e row-embed para este vídeo" ou "Refira-se ao efeito de spotlight-hero-card". Nesse caso, não apresente o template nem pergunte se deve usá-lo; confirme as cartas especificadas de acordo com as regras de resolução de nomes da Galeria, leia cada carta completamente e localize o código-fonte de demonstração preciso com base na "Implementação de Referência". Cenas avulsas podem ser executadas após o material alvo estar claro; se o vídeo promocional completo ainda não especificou se adota criação autônoma ou cocriação, pergunte apenas esses dois modos, com as cartas especificadas como restrições de produção subsequentes, sem equivaler automaticamente à cocriação.

Quatro Usos

1. Vídeo Promocional Completo (Rota de Template): Deseja um efeito muito semelhante ao vídeo de template → Leia template/TEMPLATE.md, siga o "Guia de Reprodução com Substituição de Produto" para substituir os materiais e adaptar cena por cena.
2. Vídeo Promocional Completo (Criação Autônoma): Deseja um novo estilo e autoriza o agente a decidir autonomamente → Leia references/pipeline.md, progrida continuamente da compreensão do produto até a inspeção final, sem pausar por etapa no meio.
3. Vídeo Promocional Completo (Cocriação): Deseja participar das decisões principais → Leia references/guided-free-creation.md, confirme o briefing do produto, decisões de requisitos, direção visual, mapeamento de lentes e storyboard final; após a aprovação, continue a partir da coleta final de materiais no pipeline.
4. Cena Avulsa / Efeito Único: Selecione uma carta de references/shots/ (ou deixe o usuário escolher na galeria gallery/), leia a carta completamente e localize o código-fonte de demonstração preciso com base na "Implementação de Referência", adaptando-o ao material alvo.

Limites entre Criação Autônoma e Cocriação

Criação Autônoma entrega decisões criativas e de engenharia ao agente. O agente deriva dinamicamente o foco do produto, direção visual, mapeamento de lentes, storyboard, processamento de material e plano de áudio a partir do conteúdo do projeto, registra os julgamentos principais e executa diretamente; a menos que faltem informações de entrada necessárias que não podem ser inferidas com segurança, não pergunta, não pausa por etapa e não exige que o usuário confirme produtos intermediários. Os requisitos explícitos do usuário são sempre restrições e não podem ser substituídos pela escolha padrão do agente.

Cocriação usa confirmação por etapa. Por padrão, leia references/guided-free-creation.md, faça apenas 1–3 perguntas por rodada que mais reduzem retrabalho, e pause para confirmação do usuário no briefing do produto, decisões de requisitos, direção visual, mapeamento de lentes e storyboard final. O usuário confirma a direção de negócios e criativa; o agente executa autonomamente a coleta de material, parâmetros de implementação, fixação de SFX, engenharia Remotion, renderização e QA técnica.

Na cocriação, quando o usuário disser explicitamente "você decide tudo" ou "pule a confirmação e faça", mude para criação autônoma e registre essa escolha; não afirme que está avançando autonomamente enquanto continua exigindo confirmação por etapa.

O mapeamento de funcionalidades para lentes é apenas "quais sintaxes de movimento usar", não um storyboard completo. Após a confirmação do mapeamento na cocriação, o agente deve continuar a fornecer a ordem das cenas, duração, conteúdo visual específico, estado da página, fonte do material, legendas, transições e SFX; somente após a confirmação do storyboard completo é que a coleta final de material começa. Quando o usuário copiar o nome da carta da Galeria, basta fornecer o nome da carta ou "nome da carta · nome do estilo"; o agente lê a carta de receita local e o código-fonte de demonstração.

Princípios Centrais

1. Para recriar páginas existentes, use capturas de tela reais; UI feita à mão é permitida apenas em cenários sem recriação, e a qualidade e clareza de expressão são limites rígidos. Ao exibir a página real do produto, inicie um dev server local imediatamente, use um headless browser para capturar texturas 2x da página inteira + recorte de elementos + tabela de coordenadas layout.json. Em cenários sem recriação (abertura abstrata / segmento de marca / componentes de exibição independentes), é permitido fazer UI à mão, mas se não atingir qualidade de nível de publicação ou o espectador não entender o que está sendo expresso, volte para a rota de capturas de tela. Dados de página são tratados de acordo com o risco: dados de demonstração pública só podem ser mantidos após confirmação explícita no briefing do produto; dados de clientes, pessoais, internos, chaves, em tempo real ou outros dados sensíveis devem usar conteúdo fictício ou desidentificado, e ser congelados antes da coleta.

2. A linguagem visual de todo o vídeo deve crescer a partir do próprio produto, não criar uma "pele de vídeo promocional" irrelevante. Antes de fazer o styleframe, extraia do sistema de design, código-fonte ou estilos computados do produto/site e escreva uma especificação de design: família e peso da fonte, hierarquia de tamanhos de fonte, altura da linha / espaçamento entre letras, grade, espaçamento, alinhamento, densidade de informação e cantos arredondados, bem como cores de fundo / superfície / corpo / ênfase / estado, gradientes e texturas. Todas as cores de títulos, legendas, números, cartões de texto, tipografia, transições, partículas, efeitos de luz e outros efeitos de movimento no vídeo devem reutilizar ou estender esses tokens de forma contida, enquanto combinam com o tom, gosto e textura do produto. Ao seguir a rota de template ou cartas de lentes, herde apenas a estrutura de cenas, sintaxe de movimento, ritmo e parâmetros ajustados; fontes, tipografia, cores e texturas devem ser reestilizadas para o produto alvo. Se for necessário desviar da estética do produto por razões narrativas, na cocriação, explique o motivo e peça confirmação ao usuário; na criação autônoma, escreva o motivo e os trade-offs na especificação de design e continue.

3. A sensação cinematográfica vem da coordenação entre enquadramento, iluminação, ritmo e som, não de animações chamativas. O que foi repetidamente aprovado: arco de ação completo de um protagonista (foco → aproximação → flutuação → retorno), aceleração impulsionada por metáfora física (distribuição de cartas), close-up em órbita com câmera em ângulo inclinado, frases de som como riser → impact → sparkle. A entrada de elementos em lote depende do movimento em si, não de brilhos individuais — glints decorativos / brilhos em massa são baratos; efeitos de luz pontuais de alta qualidade são aceitáveis.

4. Cada cena conta apenas um efeito; após a informação principal se estabelecer, deve haver respiração. Uma técnica de animação (voar para dentro / empilhar / virar página) só pode ser protagonista uma vez no vídeo inteiro; cenas repetidas e taglines repetidas são removidas. A preferência de ritmo é unilateral: o feedback histórico aponta todo para "desacelerar / pausar", nunca houve "muito devagar" — a marca registrada deve segurar por ≥1s, o final de efeitos em lote deve deixar 0,5s de estática, e a ação principal da abertura deve ter 3s completos. Ao planejar a linha do tempo, reserve orçamento de frames para hold/rest antecipadamente.

5. Em vídeos com BGM de ritmo forte, todas as transições e efeitos devem estar na batida. O usuário já escolheu a música → antes de começar, faça uma análise de ritmo (ajuste de grade com librosa para BPM/phase real + localização de batidas de kick/snare/hihat em três categorias), a grade só é aprovada após verificação de cobertura de transientes; a linha do tempo é escrita com beatF(n), os acentos esparsos fixam transientes reais em vez de pontos interpolados da grade. Após a renderização, extraia a faixa de áudio do vídeo final e verifique se o erro de ponto de corte é ≤3 frames. Metodologia em references/music-beat-sync.md. Vídeos com BGM são renderizados em duas versões: com BGM e sem BGM (mantendo SFX), usando o inputProp bgm a partir da mesma linha do tempo, facilitando a edição musical posterior pelo usuário.

6. Para usar efeitos de cartas de lentes, primeiro analise o índice da Galeria e leia o código de implementação de demonstração preciso. Use gallery/api/library.json para verificar o nome da carta e style-key, então localize o TSX específico com base na "Implementação de Referência" da documentação da carta. As cartas de receita fornecem semântica e tabelas de parâmetros; o código-fonte de demonstração preciso é a verdade dos parâmetros ajustados (easing, proporção de duração, momento de mascaramento, redação de armadilhas conhecidas). Adaptações são permitidas, mas os parâmetros marcados como "armadilhas conhecidas / pontos críticos" não podem ser rebaixados — os padrões de qualidade só sobem, não descem. Escrever do zero com base no nome da carta e compreensão = abandonar todo o acúmulo de ajustes.

7. Na cocriação, coloque as confirmações baratas na frente; na criação autônoma, mantenha os mesmos julgamentos como registro de execução. A ordem de briefing do produto → tabela de decisões de requisitos para execução → direção textual → styleframe → mapeamento de lentes → storyboard não muda; na cocriação, são entregues ao usuário para confirmação em etapas; na criação autônoma, o agente decide autonomamente e avança continuamente. Nenhum dos modos deve entrar na implementação cena por cena quando a direção não está definida.

8. Inspeção ao longo de todo o processo + revisão independente antes da entrega. A partir da fase 5, cada cena é autoinspecionada com npx remotion still para gerar quadros estáticos; após cada rodada de modificações, renderize o vídeo inteiro + use ffmpeg para extrair quadros e revisar; antes da entrega, um subagente com contexto limpo deve fazer uma inspeção final independente. A entrada da revisão inclui o vídeo final, quadros-chave, briefing do produto, tabela de decisões de requisitos para execução, direção visual / styleframe confirmada ou registrada no modo atual, mapeamento de funcionalidades para lentes, nomes / variantes de cartas da Galeria, TSX de demonstração preciso, amostras / quadros extraídos da Galeria, storyboard final, cartas de lentes selecionadas e princípios estéticos; siga references/final-review.md para verificar consistência do plano, integridade funcional, fidelidade das cenas, qualidade técnica visual / de áudio e segurança de dados, gerando um relatório com evidências de números de quadro item por item. O produtor tem viés de confirmação em relação à sua própria produção; a primeira inspeção nunca deve ser entregue ao usuário.

9. Renderização Determinística: Proibir Date.now() / Math.random(), fixar uma semente para toda aleatoriedade (mulberry32 / hash, seed derivado do índice); cada frame é reproduzível.

Fluxo de Trabalho

Na criação autônoma, siga references/pipeline.md da fase 0 continuamente, sem esperar confirmação do usuário por fase. Na cocriação, primeiro complete as fases 0–3 de compreensão do produto, direção visual, mapeamento de lentes e confirmação do storyboard de acordo com references/guided-free-creation.md, depois continue a partir da fase 4 de coleta final de material no pipeline; não repita perguntas ou redesenhe. Nas fases 2–3, escaneie o frontmatter de cada carta em references/shots/ e selecione lentes pela curva de energia; nas fases 5–7, compare continuamente com references/aesthetic-rules.md para autoinspeção; na fase 6, leia references/sound-design.md; em vídeos com sincronização de batida, siga references/music-beat-sync.md durante todo o processo.

Quando Ler Qual Arquivo

Momento	Leia
Início do projeto e modo não definido	Verificação mínima somente leitura, depois ofereça três modos de vídeo promocional completo e recomende
Criação autônoma	pipeline.md (agente completa fases 0–7 autonomamente, sem esperar confirmação por fase)
Cocriação	guided-free-creation.md (confirma fases 0–3), depois continue da fase 4 do pipeline.md
Usuário já escolheu BGM	music-beat-sync.md (analise antes de fazer storyboard)
Rota de template	template/TEMPLATE.md completo
Design de storyboard	Modelos de sequência em sequences/ (preencha o esqueleto do vídeo inteiro primeiro); frontmatter completo de shots/; leia a carta selecionada completamente
Implementação cena por cena	Carta de lente completa + código-fonte de demonstração preciso localizado pela "Implementação de Referência" + componente correspondente em assets/lib/
Design de som	sound-design.md + assets/audio/
Inspeção final	final-review.md + checklist completo de aesthetic-rules.md (executado por subagente independente)

Como Usar os Ativos

• Componentes em assets/lib/ copie para o novo projeto e modifique livremente (não importe esta biblioteca). Lista: PageCam (câmera de página 2.5D — base para todas as cenas de "página real"), DigitRoll, FlashCut, Caption, FlatPanel, VerticalTicker (parede de rolagem infinita 3D), helpers (rand / shake / camera / motion). FlatPanel e helpers/camera exigem dependências three + @react-three/fiber + @remotion/three; o restante requer apenas remotion.
• assets/scripts/capture-template.mjs copie e altere o CONFIG (BASE / rota / seletor) no topo.
• assets/audio/ efeitos sonoros podem ser copiados diretamente (licença gratuita para uso comercial, veja audio/ATTRIBUTION.md): audio/bgm/ contém opções de BGM com ritmo forte; audio/sfx/<categoria>/ 149 efeitos sonoros em 16 categorias (transition impact riser camera ui text paper film light data scifi mech glass fluid crowd counter). Para encontrar um som, vá direto ao diretório da categoria; a lista completa está em sound-design.md. O nome do diretório para sparkle é light/ (não há sparkle/); S1 proíbe timbre, não ação — se a cena tiver cliques / interruptores, eles devem ser sonorizados, mas metade dos sons em ui/ são feedbacks sintéticos (tone / bleep / notification) que precisam ser ouvidos individualmente, não podem ser aprovados em bloco (lista em sound-design 3.3); amostras longas e materiais leves têm listas específicas que requerem tratamento especial (sound-design 4.1).
• demos/ código-fonte de implementação de cada carta: a maioria são demos em escala de cinza autossuficientes (alguns importam componentes de UI falsa demos/_fixtures/Fixtures.tsx, alguns importam texturas de página real demos/_textures/). Copie para um projeto Remotion e execute; algumas demos usam @remotion/motion-blur (CameraMotionBlur), exigindo npm i @remotion/motion-blur; lista em demos/README.md.
• template/ projeto renderizável completo: npm install && npx remotion render src/index.ts AiflPromo out/promo.mp4.
• gallery/ galeria estática: dê prioridade à versão online https://vincentwei1021.github.io/video-shotcraft/library.html ; para executar localmente, primeiro execute gallery/fetch-media.sh para baixar amostras (mp4 não está no git), depois cd gallery && python3 -m http.server 4178. 152 cartas com 209 amostras dinâmicas podem ser navegadas / pesquisadas / copiadas com seleção múltipla — ideal para o usuário escolher lentes enquanto vê as amostras.