app-preview-video

Vídeo de Prévia do App

Crie um vídeo de prévia para a loja de aplicativos de um aplicativo móvel. Produza duas coisas:

1. Um projeto Remotion (o próprio vídeo é código React, pode ser modificado e exportado repetidamente).
2. Um console web em português, para que usuários sem conhecimento técnico possam ajustar: texto, assets, adicionar/remover/reordenar páginas, transições, efeitos, volume e exportação.

Este skill geralmente é usado por pessoas que não sabem programar. Portanto, o objetivo não é "você terminar o vídeo", mas "você montar a estrutura e o conteúdo, e entregar o console nas mãos do usuário". Fale com o usuário em linguagem clara e simples, sem exigir que ele veja código ou digite comandos.

Estrutura do Vídeo

Abertura (Ícone do App) → Quantas páginas desejar → Encerramento (Logo + Slogan)

Existem dois tipos de página:

• Página de funcionalidade: Duas linhas de texto grande + um celular, com captura de tela ou gravação de tela do aplicativo dentro do celular. É possível desenhar algumas "áreas de destaque" na captura de tela; no vídeo, um dedo toca essas áreas, que são ampliadas com uma breve descrição.
• Página de cartões: Duas linhas de texto grande + um conjunto de cartões, ideal para listar vários benefícios de uma só vez.

Todo o conteúdo ajustável fica no arquivo src/settings.json do projeto, que é lido e escrito pelo console. Consulte references/settings.md para a descrição dos campos. Leia antes de modificar o JSON.

Fluxo de Trabalho

1. Esclareça Antes de Agir

Pergunte tudo que falta de uma só vez:

• Qual é o aplicativo? Link do site ou da loja (se houver link, leia você mesmo as funcionalidades e os benefícios, não peça para o usuário repetir).
• Quais funcionalidades deseja destacar? Para qual mercado e em qual idioma?
• Assets: Ícone do aplicativo, logotipo com texto, capturas de tela ou gravações de cada funcionalidade.
• Há algum vídeo de referência? Se sim, veja o ritmo e as transições do vídeo de referência primeiro.

Mesmo que os assets ainda não estejam prontos, você pode começar a montar a estrutura, deixando espaços reservados nas páginas de funcionalidade.

2. Planeje as Páginas

Primeiro, apresente ao usuário um storyboard (cada página: duração, o que aparece na tela do celular, o texto das duas linhas, qual transição usar). Só crie o projeto após o usuário aprovar. Algumas dicas:

• Os vídeos na loja são reproduzidos automaticamente sem som. A informação é transmitida principalmente pelo texto grande. O produto deve aparecer nos primeiros 3 segundos.
• Cada página destaca um benefício. O texto deve ter no máximo duas linhas, cada linha com no máximo 4 palavras em inglês (ou equivalente no idioma alvo), senão ficará muito largo.
• Use números concretos em vez de termos superlativos não verificáveis como "#1" ou "melhor". A Apple é sensível a esses termos em sua revisão.
• Duração total: 15 a 30 segundos. Uma página de funcionalidade com explicação dura cerca de 4 a 5,5 segundos; uma página comum dura 3 a 4 segundos.

3. Crie o Projeto

Mac / Linux:

<caminho_do_skill>/scripts/create_project.sh <pasta_destino>

Windows:

powershell -ExecutionPolicy Bypass -File <caminho_do_skill>\scripts\create_project.ps1 -Target <pasta_destino>

O script copia o modelo e instala as dependências (requer internet na primeira execução, leva um ou dois minutos). Escolha uma pasta que o usuário consiga encontrar; se a sessão não tiver uma pasta de projeto, crie no diretório de trabalho atual. Não modifique diretamente o modelo dentro da pasta do skill.

Se o computador não tiver Node.js (necessário versão 18 ou superior), o script não fará a instalação automática, mas imprimirá NEED_NODE, encerrará com código de saída 3 e explicará o que baixar. Neste caso:

1. Diga ao usuário em linguagem clara: é necessário um ambiente de execução chamado Node.js. Você pode baixar automaticamente uma versão portátil do site oficial (Mac ~45 MB, Windows ~30 MB), colocá-la em uma pasta própria do usuário, usada apenas por esta ferramenta, sem modificar o sistema ou exigir senha de administrador.
2. Após o usuário concordar, execute novamente com --install-node (Windows: -InstallNode).
3. Se o usuário não concordar ou o download for bloqueado pela rede corporativa, peça para ele (ou o TI) instalar manualmente a partir de https://nodejs.org e tentar novamente.

Perguntar antes de instalar é proposital: baixar e executar programas da internet não deve acontecer silenciosamente. O script contém hashes de verificação oficiais embutidos; se o arquivo baixado não corresponder, ele será excluído e um erro será exibido. Nesse caso, não ignore a verificação; peça ao usuário para tentar novamente ou instalar manualmente.

Todos os comandos subsequentes devem ser executados através do lançador do projeto: Mac/Linux use ./run.sh <comando>, Windows use run.cmd <comando>. Ele automaticamente incluirá a versão baixada do Node.js; se estiver usando o Node.js do sistema, ele não altera nada. Portanto, é mais simples padronizar assim. Os comandos abaixo omitem este prefixo.

4. Preencha o Conteúdo

• Copie os assets para a pasta public/ do projeto e preencha os nomes dos arquivos em src/settings.json.
• Modifique o array páginas de acordo com o storyboard: texto de cada página, duração, transição, cores.
• Extraia a cor da marca do logotipo e preencha em marca.corPrimaria / marca.corEscura. Informe ao usuário: "Esta é uma estimativa baseada no logotipo".
• Após preencher, copie o mesmo conteúdo para src/settings.default.json, para que a opção "Restaurar padrões" no console retorne à sua versão montada, não ao modelo vazio.

5. Verifique os Quadros

Antes de exportar, extraia alguns quadros para verificação visual. Não confie apenas na verificação de tipos:

npx remotion still src/index.ts AppPreview /tmp/f.jpg --frame=<número_do_quadro> --scale=0.3 --image-format=jpeg

Verifique pelo menos um quadro de cada página (30 quadros = 1 segundo). Pontos importantes: o texto grande não está ultrapassando a largura; as descrições das áreas de destaque não estão encostando nas bordas; não há flashes brancos nas transições entre páginas.

6. Inicie o Console e Entregue ao Usuário

Na pasta do projeto, execute ./run.sh npm run panel (Windows: run.cmd npm run panel). É um servidor Vite, por padrão em http://127.0.0.1:5173. No Claude Desktop, configure-o no arquivo .claude/launch.json da raiz da sessão e abra-o no painel de visualização para que o usuário possa operar diretamente à direita:

{"name": "control-panel", "runtimeExecutable": "<pasta_do_projeto>/run.sh", "runtimeArgs": ["npm", "run", "panel"], "port": 5173}

No Windows, substitua runtimeExecutable por <pasta_do_projeto>\run.cmd. Em ambientes sem painel de visualização, informe a URL ao usuário para que ele abra no navegador.

Em seguida, explique em poucas palavras como usar o console:

• A aba no topo indica qual página está ativa; à esquerda, o vídeo pula para essa página; à direita, os controles editáveis da página.
• "+ Adicionar página" permite adicionar uma página de funcionalidade ou de cartões; em cada página, é possível renomear, mover para cima/baixo, duplicar ou excluir.
• Arraste as capturas de tela ou gravações diretamente para a área pontilhada. Segure e arraste para desenhar um retângulo sobre a captura de tela; isso cria uma área de destaque.
• As alterações são salvas automaticamente. Clicar em uma opção de efeito reproduz automaticamente a página.
• "Exportar vídeo" leva cerca de um minuto; o arquivo final é salvo na área de trabalho.

O console só funciona enquanto este servidor estiver em execução. Se o usuário voltar depois e não conseguir abrir, basta reiniciá-lo.

7. Exportação

O usuário pode clicar em "Exportar vídeo" no console. Para exportar você mesmo:

npx remotion render src/index.ts AppPreview out/preview.mp4 --props=src/settings.json

Após a exportação, informe claramente: especificações (886×1920, 30fps, duração), quais páginas ainda são placeholders, quais você realmente verificou visualmente. Você não pode ouvir o áudio; peça ao usuário para ouvir.

Regras Obrigatórias

Estas são lições aprendidas com experiência. As razões estão explicadas a seguir.

• Interface real. A Apple exige que os vídeos de prévia mostrem principalmente a interface real do aplicativo. Páginas de funcionalidade sem captura de tela devem exibir apenas placeholders; não desenhe uma interface "parecida com o app" e a entregue como produto final. O modelo inclui um ponto de entrada para animações ilustrativas (MOCKS), que só deve ser usado quando o usuário solicitar explicitamente um placeholder temporário, e sempre com o aviso: "Esta não é a interface real do aplicativo e não pode ser usada para submissão".
• Use apenas os efeitos sonoros inclusos. Os 8 efeitos sonoros em public/sfx/ são gerados por tools/make_sfx.py usando ondas senoidais e ruído. Não há assets de terceiros, sem problemas de licenciamento comercial. Para alterar o tom, modifique este script e regenere. Para usar efeitos ou músicas externos, confirme a origem e a licença com o usuário primeiro.
• Não modifique as configurações já ajustadas pelo usuário. O usuário altera src/settings.json pelo console. Ao modificar código ou adicionar campos, apenas "complete os campos ausentes" neste arquivo; não sobrescreva o arquivo inteiro. Ao testar, não clique em "Deletar" ou "Restaurar padrões" nas configurações reais do usuário; faça backup primeiro ou use um arquivo --props temporário.
• Tamanho e duração. O modelo é 886×1920 (iPhone 6,9 polegadas), 30fps. A App Store exige 15 a 30 segundos; o console fica vermelho no topo se o tempo exceder. Outros modelos de dispositivo ou requisitos de tamanho do Google Play podem ser diferentes; peça ao usuário para verificar as especificações oficiais antes de enviar.
• Informe honestamente o que foi verificado. Diga quais quadros você realmente viu; para opções que não foram clicadas uma a uma, diga que não foram verificadas.

Funcionalidades Não Presentes no Console

O console cobre os ajustes mais comuns. Se o usuário quiser um efeito que não está disponível (nova transição, novo layout de página, outro efeito), modifique src/AppPreview.tsx. Este arquivo é organizado em seções, cada uma com comentários em português no início. Para adicionar um efeito opcional, siga três passos:

1. Adicione um nome de opção no z.enum([...]) correspondente no início do arquivo.
2. Implemente-o no componente apropriado (transições em useEnterStyle, animação de título em Title, entrada e movimento do celular em Phone, efeitos de destaque em SpotPop / SpotRing / Phone com zoom).
3. Os botões de opção no console são gerados automaticamente a partir de OPTIONS; geralmente não é necessário modificar control/main.tsx. Apenas se novos campos forem adicionados, será necessário adicionar controles lá e preencher valores padrão em settings.json e settings.default.json.

Após a modificação, execute npx tsc --noEmit -p . e verifique os quadros novamente.

Perguntas Frequentes

• O vídeo no console fica preto ou mostra um ícone de aviso: Provavelmente muitos áudios estão montados ao mesmo tempo. Cada Sequence de efeito sonoro deve ter durationInFrames, e o numberOfSharedAudioTags no Player deve ser grande o suficiente (o modelo usa 16).
• Imagens recém-carregadas não aparecem: Os arquivos enviados são lidos diretamente do disco pelo middleware /uploads em control/vite.config.mts. Não o remova (o Vite só reconhece arquivos public que existiam no início).
• As áreas de destaque estão desalinhadas: A proporção da tela dentro do celular no modelo é baseada em capturas de tela do iPhone (aproximadamente 1:2,17). Capturas com outras proporções serão cortadas, deslocando as áreas de destaque. Peça ao usuário para usar capturas de tela do iPhone no modo retrato.
• "Fazer o carro andar" (recortar o ícone do veículo de uma captura de tela e movê-lo ao longo de uma rota) funciona apenas em trechos retos; o retângulo deve ajustar-se ao veículo. É adequado apenas para capturas de tela de aplicativos de navegação; outros aplicativos não precisam se preocupar.
• Não encontro o vídeo após a exportação: Quando a exportação é concluída pelo console, o local completo do arquivo é exibido. Se houver uma área de trabalho, o arquivo é salvo lá (incluindo no Windows, onde a área de trabalho pode ser gerenciada pelo OneDrive); caso contrário, fica na pasta out do projeto.
• Windows: O script de instalação e o lançador seguem as regras do Windows, mas este skill foi desenvolvido e testado no Mac. Ainda não foi testado no Windows. Na primeira execução no Windows, verifique cada saída; se houver problemas, corrija o script antes de continuar e informe o usuário. As fontes padrão diferem entre os sistemas (Mac: SF, Windows: Segoe UI); o mesmo conjunto de configurações pode produzir diferenças sutis na tipografia do vídeo exportado.
• A porta 5173 está ocupada: O Vite automaticamente tentará a próxima porta disponível. Use o endereço exibido no log de inicialização.