getlarge/themoltnet

Gravação de Demonstração de Produto

Trate composição, privacidade, narrativa e saída decodificada como portões de liberação separados. Uma execução bem-sucedida do produto não prova que a gravação é segura, legível ou limpidamente composta.

Para mecanismos nativos de captura no macOS ou navegador, leia references/capture-macos.md. Para builders de workflow no navegador com loops de polling ou retry, leia references/browser-workflows.md. Para cartões de título, terços inferiores, diagramas, chamadas e cartões finais, leia references/infographic-style.md.

Estabeleça o quadro de entrega primeiro

Antes de gravar:

1. Escolha o tipo de narrativa antes de escrever a lista de cenas:
   • Uma visão geral ensina a forma do produto: mostre a sequência de nós ou telas mais representativa, use texto genérico e omita explicações específicas do cenário.
   • Uma demonstração de cenário responde a uma pergunta concreta: declare o caso, mostre os estágios reais de execução e termine com o resultado verificado.
   • Prefira vídeos separados e curtos quando ambos forem úteis. Não misture explicação genérica do produto com um caso específico de domínio, a menos que o usuário explicitamente queira um tutorial combinado.
2. Estabeleça uma referência visual:
   • Se existir uma gravação anterior, inspecione-a do início ao fim. Extraia uma folha de contato quando útil e anote seu ritmo, composição, anotações e momentos explicativos mais fortes.
   • Se não houver gravação anterior, use a biblioteca @themoltnet/design-system, a mídia da documentação vizinha e a interface nativa do produto integrado—nessa ordem—para criar um still de cartão de título, o still de interface anotada mais denso e um still de cartão final antes de gravar. Esses stills aprovados tornam-se a linha de base para vídeos posteriores na série.
3. Leia a página onde o vídeo aparecerá. Escreva uma lista curta de cenas que nomeie o resultado do usuário, a configuração necessária, a interação principal, o comportamento de espera ou retry e o resultado bem-sucedido.
4. Escolha a proporção de aspecto e resolução finais antes de organizar o aplicativo. Prefira um quadro 16:9 convencional, como 1440x810 ou 1920x1080.
5. Organize o aplicativo para que a área de conteúdo pretendida caiba inteiramente nesse quadro. Oculte barras laterais opcionais dentro do aplicativo quando necessário; não remova metade de uma barra lateral ou controle com um corte arbitrário de pós-produção.
6. Decida se o chrome do navegador faz parte da composição. Prefira uma captura limpa da viewport do navegador. Se isso não estiver disponível, mantenha a janela completa do navegador ou coloque-a dentro de um quadro deliberado. Uma janela completa é mais limpa do que abas, bordas ou conteúdo de aplicativo recortados.
7. Revise os três stills de estilo representativos no tamanho real de exibição. Não grave o tutorial completo enquanto o sistema de sobreposição, áreas seguras ou hierarquia de informações ainda estão sendo inventados.

Use um limite de captura seguro

• Capture uma janela de aplicativo ou uma viewport de navegador, nunca um retângulo da área de trabalho onde outro aplicativo possa entrar.
• Resolva e trave o identificador exato da janela antes de gravar. Reconfira-o após navegação, pop-outs ou reinicializações do aplicativo.
• Desabilite notificações e use dados de demonstração dedicados, mas não dependa dessas precauções como limite de privacidade.
• Mantenha credenciais, tokens, identificadores pessoais, URLs privadas e dados de conta não relacionados fora da superfície capturada. A ocultação de senhas é necessária, mas não torna o material de entrada de credenciais desejável.
• Faça o ponteiro intencional. Estacione-o longe do texto enquanto um resultado estático está sendo lido.

Grave para compreensão

• Use uma ideia por cena. Segure configurações e resultados importantes por tempo suficiente para serem lidos na velocidade normal de reprodução.
• Mostre a configuração apenas quando ajudar o visualizador a reproduzir o resultado. Em demonstrações de integração, isso geralmente significa instalar, autenticar sem revelar o segredo, importar o workflow, executá-lo e inspecionar o resultado no terminal.
• Prefira zoom nativo do aplicativo e alterações de layout em vez de ampliar um raster recortado posteriormente.
• Capture a execução bem-sucedida real. Cartões de título e anotações reconstruídos podem explicá-la, mas não devem implicar uma ação ou resultado que não foi observado.
• Uma edição baseada em estado pode usar stills limpos capturados de uma execução real quando o movimento em si não é instrutivo. Mantenha os estados na ordem observada, preserve a evidência visível da tarefa e use transições apenas para comunicar progresso.
• Complete a criação de credenciais e o teste de conexão fora da tomada gravada. Inicie a narrativa a partir de um estado autenticado seguro, a menos que a configuração de credenciais seja o próprio assunto documentado.
• Grave tomadas curtas e independentemente utilizáveis quando o fluxo tiver estágios estáveis. Isso limita a regravação e torna a revisão de privacidade mais precisa.
• Para um loop longo de polling ou retry, preserve os estados ordenados reais, mas acelere ou corte a porção ociosa repetida. Segure a ação inicial, o estado final do workflow e o resultado aceito em velocidade legível.

Edite sem esconder o produto

• Preserve todas as bordas intencionais do aplicativo. Redimensione e adicione preenchimento ao quadro de entrega em vez de cortar conteúdo para forçar uma proporção de aspecto.
• Use cartões de título e finais apenas quando melhorarem a orientação ou os próximos passos.
• Mantenha terços inferiores dentro de uma área segura pré-planejada. Eles não devem cobrir controles, status, saída, erros ou identificadores necessários para entender o fluxo.
• Em demonstrações de cenário, deixe as anotações avançarem com a execução. Nomeie o estágio atual e explique sua consequência em uma linha curta, por exemplo INTENÇÃO — Extrair local e período seguido de INTENÇÃO COMPLETA — Buscar a previsão. Use os nomes reais dos estágios do produto e estado observável; não narre raciocínios ocultos.
• Mantenha um vídeo de visão geral visualmente mais silencioso do que sua demonstração de cenário companheira. Rótulos de nós e indicadores de status nativos devem carregar a explicação quando já são suficientes.
• Corresponda à linguagem visual da documentação estabelecida ao substituir um vídeo existente. Não faça uma substituição parecer menos deliberada do que o ativo que substitui.
• Para ampla compatibilidade com navegadores, use como padrão H.264 High, yuv420p, 30 fps constantes, sem áudio a menos que narração seja intencional, e MP4 fast-start.
• Nesta toolchain macOS, prefira libx264 single-threaded para a renderização final quando prático. Use o helper incluído em vez de busca rápida de entrada ao extrair quadros de QA com timestamp exato.
• Se um quadro aparecer corrompido em uma prévia do artefato, reabra o artefato com checksum estável e inspecione o vídeo em um player nativo. O caminho de prévia renderizou intermitentemente bytes de imagem idênticos de forma diferente; não altere um vídeo a menos que o defeito seja reproduzível independentemente.
• Se um quadro permanecer corrompido na reprodução normal e extração repetida, substitua o segmento afetado a partir de uma fonte limpa e recodifique o master final com -threads 1.

Adicione áudio apenas quando merece seu lugar

• Mantenha a reprodução silenciosa como padrão para vídeos incorporados na documentação. Adicione narração quando ela explicar materialmente tempo, causalidade ou contexto que anotações visuais concisas não conseguem.
• Escreva e cronometre a narração contra a imagem travada. Legendas ou uma transcrição de texto devem preservar a mesma informação, e o vídeo deve permanecer compreensível quando mutado.
• Use uma voz clonada ou sintética modelada em uma pessoa identificável apenas com a autorização explícita dessa pessoa. Divulgue que a voz é sintética na página ao redor ou créditos; não a apresente como uma gravação ao vivo autêntica.
• Mantenha amostras de voz, arquivos de modelo e intermediários gerados fora do repositório, a menos que o usuário explicitamente escolha publicá-los. Trate a autorização para criar uma demonstração narrada como limitada a esse entregável, não como consentimento permanente para geração futura de voz.
• Refaça a QA de entrega após multiplexar o áudio. Verifique inteligibilidade, níveis, sincronia, legendas, layout de canais e se o contêiner final ainda atende à especificação de entrega de vídeo.

Revise o entregável decodificado

Execute o helper incluído contra o arquivo final, não um intermediário:

.agents/skills/product-demo-recording/scripts/qa-video.sh \
  path/to/final.mp4 /private/tmp/demo-video-qa --interval 2 4 5 6

O helper escreve metadados de stream, uma folha de contato decodificada sequencialmente e quadros de início/meio/fim mais timestamps solicitados como JPEGs. Use um diretório de saída novo.

Em seguida, realize todas estas verificações:

1. Assista o vídeo final completo na velocidade normal.
2. Inspecione a folha de contato para cada mudança de aplicativo, modal, cena, anotação e estado de resultado.
3. Inspecione quadros exatos imediatamente antes, em e após cada limite de edição. Sempre adicione timestamps nomeados no feedback de revisão; não infira que quadros adjacentes são representativos.
4. Confirme que não há outros aplicativos, áreas da área de trabalho, notificações, credenciais, dados privados, bordas cortadas, chrome parcial do navegador, bordas pretas estranhas ou controles obstruídos.
5. Confirme que o texto é legível, o posicionamento do ponteiro é calmo, as transições são limpas e o resultado visível corresponde à documentação ao redor.
6. Verifique o codec, formato de pixel, dimensões, taxa de quadros, duração, escolha de áudio e requisito fast-start contra a especificação de entrega.

Não descreva a gravação como revisada até que essas verificações tenham sido realizadas no arquivo exato que será commitado.

Entregue e retenha deliberadamente

• Prepare apenas o ativo final e mudanças intencionais na documentação. Não adicione takes brutos, credenciais, perfis de navegador ou exportações de QA.
• Mantenha takes brutos até que o arquivo final seja revisado e commitado ou enviado com segurança. Em seguida, siga a escolha de retenção do operador; remova capturas temporárias sensíveis explicitamente, em vez de com padrões amplos de exclusão.
• Na transferência, declare o que foi mostrado, as propriedades técnicas finais, quais timestamps foram inspecionados e onde o ativo final está localizado.