Vídeo de Cabeçalho da App Store

O que Vídeo de Cabeçalho da App Store faz?

Crie os dois vídeos de ativos criativos da App Store: o cabeçalho da página do produto que faz loop acima do ícone do app, e o cabeçalho dos resultados de pesquisa que toca no cartão do app na pesquisa. Ambos são reproduzidos automaticamente, sem áudio e em loop infinito, portanto, cada quadro precisa funcionar sem som e o último quadro precisa fluir para o primeiro.

Esta skill prepara o arquivo. Ela nunca faz upload ou submete nada — o usuário publica no App Store Connect.

Entradas a Coletar

Pergunte apenas pelo que está faltando; a conversa geralmente já fornece algumas informações.

1. Posicionamento(s) — cabeçalho (21:9), resultados de pesquisa (3:2), ou ambos. Cada um tem dimensões diferentes, portanto uma renderização de cabeçalho não pode ser reutilizada como está para pesquisa.
2. A única ideia — uma frase que o vídeo deve transmitir. A própria orientação da Apple: "Foque em uma ideia única e clara." Duas ideias significa que nenhuma será transmitida.
3. Identidade do app — nome do app, proposta de valor em uma linha, cores da marca, arquivo do logotipo, PNG do ícone do app.
4. Material real do produto — screenshots ou filmagens do app real, se o conceito mostrar o app. Ativos criativos podem destacar a marca ou o conteúdo em vez do app em uso, então isso é opcional, mas quando o app é mostrado, devem ser capturas reais.
5. Duração — padrão de 8 segundos. A Apple aceita de 5 a 30s.
6. Ocasião — perene, lançamento sazonal, lançamento de recurso, rebranding. Afeta se o ativo pode ser reutilizado posteriormente.

Procedimento

Os scripts desta skill ficam em scripts/ próximo a este arquivo. Resolva esse caminho em relação ao diretório deste próprio SKILL.md sempre que executá-los — o diretório de trabalho do usuário não é o diretório da skill.

1. Fixe o posicionamento e leia a especificação

Leia references/specs.md antes de construir. Ele contém as tabelas exatas da Apple, a distinção entre pré-visualização do app e ativo criativo, e as regras de área segura.

Se o CLI asc estiver no PATH, asc asset-library specs retorna os dados de referência ao vivo da Apple — use-o para confirmar que os números não mudaram desde que esta skill foi escrita. references/publishing.md tem a consulta.

Os dois posicionamentos não são intercambiáveis:

Posicionamento	Proporção	Tamanho	Uso típico
Cabeçalho da página do produto	21:9	exatamente 3840x1646	Banner de largura total acima do ícone
Resultados de pesquisa	3:2	1920x1280 a 3840x2560	O cartão nos resultados de pesquisa

2. Escolha uma ideia e nomeie o quadro de pôster

Anote a única ideia e o quadro de pôster — a imagem estática que o usuário vê antes da reprodução começar, e o quadro que a Apple mostra quando a reprodução automática está desligada. O quadro de pôster deve funcionar sozinho como uma imagem estática. "Lide com sua proposta de valor ou recurso mais atraente" (Apple). Se o quadro de pôster precisar de uma legenda para fazer sentido, a ideia ainda não está finalizada.

3. Projete a costura, não um clipe

O vídeo faz loop continuamente e as pessoas o assistem repetidamente, portanto, o estado em t=0 e t=D deve corresponder. Planeje isso antes de animar qualquer coisa:

• Movimento contínuo — uma rotação completa de 360° ou um campo em translação infinita faz o loop perfeitamente sem trabalho extra.
• Retorno à base — a escala ou posição anima de volta ao seu valor inicial, e o último quadro termina exatamente no quadro inicial.
• Transição por fade — fade in no quadro de abertura, segura, fade de volta para o estado base no quadro de fechamento, de modo que a emenda seja uma dissolução suave.

Um clipe mostra o intervalo [início, início + duração) e um estado final que termina exatamente no seu fim nunca é renderizado. Termine o tween de fechamento um quadro antes (início + duração - 1/fps) para que o último quadro visível seja realmente o estado base — caso contrário, o loop fica um quadro aquém do fechamento.

Um clipe que termina em um quadro diferente do que começou é lido como um bug, não um loop.

4. Construa no HyperFrames

npx hyperframes init <project-dir>

O index.html raiz declara a tela. Defina-a para o tamanho exato em pixels do posicionamento — o HyperFrames renderiza nas dimensões autoradas da composição e ignora qualquer tamanho que você assuma:

<div id="root"
     data-composition-id="main"
     data-width="3840" data-height="1646"
     data-duration="8" data-fps="30">

Regras que fazem ou quebram esta etapa:

• Não codifique 1920px/1080px no #root; estilize com width:100%; height:100%.
• Não há predefinição --resolution para 21:9 ou 3:2 — --resolution landscape-4k é 3840x2160, que é a forma errada e será rejeitado.
• Dê ao div hospedeiro, à raiz da cena e à chave da linha do tempo o mesmo id. Uma incompatibilidade faz cada renderização esperar 45 s por cena e depois mostra quadros estáticos.
• Use fromTo, não from, dentro de uma cena — o hospedeiro rebusca a cena e from deriva na rebusca, que é exatamente o que quebra um loop.
• Fontes devem ser empacotadas como arquivos em assets/fonts/ com @font-face; apenas famílias empacotadas são resolvidas pelo nome.
• Coloque texto e cópia na composição como variáveis (data-var-text), nunca incorporadas em uma imagem.
• Mantenha cada cena em compositions/ como sua própria subcomposição para que um único quadro possa ser re-renderizado.

references/hyperframes-build.md contém os trechos de técnica de loop, os comandos de verificação e snapshot, os sinalizadores de renderização e um pipeline de tela para ffmpeg para usar como fallback quando uma renderização de navegador 3840x1646 for muito lenta para iterar. A especificação e a verificação são as mesmas de qualquer forma.

5. Gere imagens de suporte apenas quando o conceito precisar

Fotos, ilustrações e fundos atmosféricos vêm da geração de imagens. Nunca gere UI do app com um modelo de imagem — ele alucina interfaces, e uma UI falsa em uma listagem da loja é pior do que nenhuma UI. Use screenshots reais para o app; use geração para tudo ao redor.

mcode-tools connector tools --keyword image
mcode-tools connector tool <nome_da_ferramenta>          # leia o input_schema primeiro
mcode-tools connector call <nome_da_ferramenta> --args '{"prompt":"...","aspect_ratio":"21:9"}'

references/asset-generation.md tem o fluxo completo de descoberta e chamada, além de como criar prompts para uma proporção de aspecto específica.

6. Verifique, snapshot, pré-visualize — depois renderize

npx hyperframes check --json                                  # deve estar limpo
npx hyperframes snapshot --at 0,4,8                            # leia os PNGs
npx hyperframes preview --background                           # forneça a URL ao usuário

Olhe os snapshots antes de mostrar a pré-visualização. Verificações aprovadas sozinhas não significam que o quadro parece correto.

Renderize apenas após o usuário ter visto a pré-visualização e aprovado, ou quando ele pediu o arquivo sem paradas:

npx hyperframes render --quality delivery --fps 30 --format mp4 --output out/<nome>.mp4

Adicione --video-frame-format png quando a fonte for uma gravação de tela do app, para que o texto da UI e as cores planas sobrevivam à extração de quadros.

Itere nos snapshots, renderize uma vez. Um snapshot de quadro único é quase instantâneo, então julgue a composição com npx hyperframes snapshot --at 0,4,7.9 e leia os PNGs. Uma renderização de entrega completa de 3840x1646 de 8 segundos leva cerca de 9 segundos em um Mac com chip M-series — a renderização não é a parte lenta, a iteração é. Renderize uma vez que os quadros pareçam corretos.

Renderize o teste na qualidade de entrega, ou recodifique-o antes de confiar no veredito da costura. Uma renderização de qualidade de rascunho carrega ruído de quantização, e o ruído do codificador no quadro final difere do ruído no primeiro quadro. Isso aparece como uma diferença de emenda que não é geométrica, e você acabará perseguindo um bug que não existe. Se um teste pequeno veio de --quality draft, recodifique-o da mesma forma que o script de conformidade faria (libx264 -crf 18 -pix_fmt yuv420p) e verifique isso.

7. Conforme o arquivo à especificação

Execute isso mesmo após uma renderização do HyperFrames. Taxa de quadros errada e tamanho de pixel errado são os dois motivos de rejeição que as pessoas enfrentam primeiro.

node <caminho-da-skill>/scripts/conform-video.mjs --in out/header.mp4 --out out/<app>-header.mp4 --placement header
node <caminho-da-skill>/scripts/conform-video.mjs --in out/search.mp4 --out out/<app>-search.mp4 --placement search

Cada posicionamento precisa de sua própria composição e sua própria renderização. A tela do cabeçalho é 21:9 e a tela de pesquisa é 3:2 — cortar um no outro joga a composição fora e coloca o assunto fora do enquadramento. Conformidade corrige resolução, taxa de quadros e codec; não pode corrigir uma composição construída para a forma errada. Configure a raiz da composição de pesquisa para data-width="3840" data-height="2560".

Uma raiz de projeto por posicionamento. A composição raiz declara a tela, portanto os dois posicionamentos não podem compartilhar uma raiz. Dê a cada um sua própria pasta de projeto com seu próprio index.html e uma cópia dos ativos — check e snapshot só olham para a raiz, e render --composition <arquivo> renderiza um arquivo de composição independente.

O script escala e corta para a tela exata, força uma taxa de quadros constante de 30 ou 60 fps, codifica H.264 yuv420p (sem alfa), remove áudio e define faststart. Ele se recusa a aumentar a escala silenciosamente e avisa quando a origem é muito pequena.

8. Verifique antes de entregar

node <caminho-da-skill>/scripts/verify-video.mjs out/<app>-header.mp4 --placement header
node <caminho-da-skill>/scripts/verify-video.mjs out/<app>-search.mp4 --placement search

O script verifica dimensões, proporção, taxa de quadros (constante, exatamente 30 ou 60), duração, codec, formato de pixel e áudio. Ele também julga a costura do loop: compara o primeiro quadro com o último quadro em relação ao movimento típico de quadro a quadro do próprio clipe, para que uma emenda mais disruptiva do que um passo de quadro comum seja relatada como um salto visível. Ele escreve uma tira *-seam.png de ambos os quadros para inspeção visual. Deve sair com 0. Corrija a composição e re-renderize se não sair.

Em seguida, extraia o quadro de pôster e observe-o sozinho — esta é a imagem estática que a loja mostra antes da reprodução começar, portanto, se precisar de uma legenda para fazer sentido, o vídeo precisa de trabalho. Escolha o quadro mais forte, que não é necessariamente o primeiro:

ffmpeg -v error -y -ss 00:00:04.000 -i out/<app>-header.mp4 -frames:v 1 out/<app>-poster.png

Relate o timecode que você escolheu. Os quadros de pôster são definidos no ativo na Asset Library e não podem ser editados após o ativo ser aprovado, portanto a escolha tem que ser feita antes de submeter.

9. Entregue

Forneça ao usuário:

• o(s) caminho(s) do(s) arquivo(s) final(is), um por posicionamento
• o relatório de verificação
• o quadro de pôster e qual quadro é
• as etapas de publicação

Um ativo criativo precisa passar por três portões separados — enviado, aprovado e colocado — e a aprovação sozinha não o publica. references/publishing.md tem ambas as rotas com os comandos asc exatos:

asc asset-library view --app APP_ID                     # encontre o ID da biblioteca
asc asset-library videos upload --library-id ID --file ./header.mp4
asc asset-library videos set-poster-frame --id VIDEO_ID --time-code 00:00:04:00
asc localizations list --app APP_ID                     # encontre o ID da localização
asc localizations placements create --localization-id LOC --video-id VID \
  --placement-type PRODUCT_PAGE_HEADER_ASSET           # ou APP_STORE_SEARCH_RESULTS_ASSET

Para um app que já está ao vivo, a versão curta no App Store Connect é: Apps → seu app → barra lateral → Asset Library → + → Upload Creative Assets → faça upload de ambos os arquivos → defina um quadro de pôster → Add for Review → Submit for Review → aguarde APPROVED → a versão ao vivo → Product Page Information → "Header and Search Results" → Browse Assets → escolha o ativo → Next → Publish. Isso vai ao vivo sem nova versão e sem nova revisão. Se o app ainda não tiver uma versão ao vivo, anexe os ativos à próxima versão e submeta essa.

Diga ao usuário para verificar o resultado com Preview na aba Header and Search Results — mostra o ativo no iPhone e iPad, em orientações, idiomas e Modo Escuro diferentes, e o corte difere por posicionamento. Os quadros de pôster não podem ser editados após o ativo ser aprovado, então escolha um antes de submeter.

Pare por aí. Não execute o upload, a submissão para revisão ou a publicação você mesmo. Upload e publicação são etapas do usuário.

Contrato de saída

• out/<app>-header.mp4 — 3840x1646, H.264 yuv420p, taxa de quadros constante 30 ou 60 fps, 5–30s, sem alfa, sem áudio, abaixo de 500 MB
• out/<app>-search.mp4 — 3:2 dentro de 1920x1280–3840x2560, mesmas regras de codificação
• um relatório de verificação com todas as verificações PASS
• um quadro de pôster e seu timecode
• uma nota de entrega curta com as etapas de publicação de references/publishing.md

Ambos os posicionamentos recebem seu próprio arquivo. Não entregue um arquivo para ambos.

Tratamento de falhas

Sintoma	O que fazer
ffprobe / ffmpeg não encontrado	brew install ffmpeg (macOS) ou choco install ffmpeg (Windows); os scripts precisam deles para verificar e conformar
HyperFrames não consegue iniciar o Chrome	npx hyperframes browser ensure, depois npx hyperframes doctor --json e verifique .ok
Renderização parece lenta	Normalmente não é. Uma renderização de entrega de 3840x1646, 8 s leva cerca de 9 s em um Mac com chip M-series. Se realmente estiver lenta, verifique se o renderizador tem workers de GPU e itere nos quadros hyperframes snapshot em vez de re-renderizar. --quality looks é mais rápido que --quality delivery se você só precisa de uma olhada
O codificador marca o arquivo com o nível 4.1	Ambas as telas excedem o limite de macroblocos do nível 4.1 — 3840x1646 é 24720 macroblocos e 1920x1280 é 9600, contra um limite de 8192. Recodifique com -level 5.1
Verificação de costura falha	Corrija o último quadro para que o estado retorne ao estado base. Um crossfade (--seam-crossfade) é um fallback, não uma correção, porque consome C segundos de conteúdo
Texto ilegível no tamanho de miniatura	Aumente-o. A Apple observa que os ativos aparecem de forma diferente na loja, portanto a renderização menor é o teste real
Upload rejeitado no App Store Connect	Re-execute verify-video.mjs no arquivo que foi realmente enviado, não no original local. asc asset-library videos upload também valida o arquivo contra a especificação ao vivo da Apple antes de fazer o upload, portanto seu erro nomeia a regra que você perdeu
Apple rejeita o posicionamento	O slot pode já estar ocupado — criar um posicionamento não substitui um existente. Use asc localizat…

[truncado para tradução]