app-store-header-video

Video de encabezado de App Store

Construye los dos videos de activos creativos de la App Store: el encabezado de la página de producto que se repite sobre el ícono de la app, y el encabezado de resultados de búsqueda que se reproduce en la tarjeta de la app en los resultados de búsqueda. Ambos se reproducen automáticamente sin sonido y en bucle infinito, por lo que cada fotograma debe funcionar sin audio y el último fotograma debe fluir hacia el primero.

Este skill prepara el archivo. Nunca lo sube ni lo envía — el usuario publica en App Store Connect.

Entradas a recopilar

Pregunta solo por lo que falta; la conversación generalmente ya proporciona algunos datos.

1. Ubicación(es) — encabezado (21:9), resultados de búsqueda (3:2) o ambos. Cada uno tiene dimensiones diferentes, por lo que un renderizado de encabezado no se puede reutilizar como está para búsqueda.
2. La única idea — una frase que el video debe transmitir. La guía de Apple: "Concéntrate en una sola idea clara." Dos ideas significa que ninguna se transmite.
3. Identidad de la app — nombre de la app, propuesta de valor en una línea, colores de marca, archivo de logotipo, PNG del ícono de la app.
4. Material real del producto — capturas de pantalla o material de archivo de la app real, si el concepto muestra la app. Los activos creativos pueden resaltar la marca o el contenido en lugar de la app en uso, por lo que esto es opcional, pero cuando se muestra la app debe ser capturas reales.
5. Duración — 8 segundos por defecto. Apple acepta de 5 a 30 s.
6. Ocasión — perpetuo, lanzamiento estacional, lanzamiento de funciones, cambio de marca. Afecta si el activo se puede reutilizar más adelante.

Procedimiento

Los scripts de este skill se encuentran en scripts/ junto a este archivo. Resuelve esa ruta contra el directorio propio de este SKILL.md cada vez que los ejecutes — el directorio de trabajo del usuario no es el directorio del skill.

1. Bloquea la ubicación y lee las especificaciones

Lee references/specs.md antes de construir. Contiene las tablas exactas de Apple, la distinción entre vista previa de la app y activo creativo, y las reglas del área segura.

Si la CLI asc está en el PATH, asc asset-library specs devuelve los datos de referencia en vivo de Apple; úsalos para confirmar que los números no han cambiado desde que se escribió este skill. references/publishing.md tiene la consulta.

Las dos ubicaciones no son intercambiables:

Ubicación	Relación de aspecto	Tamaño	Uso típico
Encabezado de página de producto	21:9	exactamente 3840x1646	Banner de ancho completo sobre el ícono
Resultados de búsqueda	3:2	1920x1280 a 3840x2560	La tarjeta en los resultados de búsqueda

2. Elige una idea y nombra el fotograma de póster

Escribe la única idea y el fotograma de póster — la imagen fija que un usuario ve antes de que comience la reproducción, y el fotograma que Apple muestra cuando la reproducción automática está desactivada. El fotograma de póster debe funcionar por sí solo como una imagen estática. "Comienza con tu propuesta de valor o la característica más convincente" (Apple). Si el fotograma de póster necesita un título para tener sentido, la idea aún no está terminada.

3. Diseña el empalme, no un clip

El video se repite continuamente y la gente lo ve repetidamente, por lo que el estado en t=0 y t=D debe coincidir. Planifica esto antes de animar cualquier cosa:

• Movimiento continuo: una rotación completa de 360° o un campo de traducción interminable se adapta perfectamente sin trabajo adicional.
• Regreso a la base: la escala o la posición se animan de vuelta a su valor inicial, y el último pulso cae exactamente en el fotograma inicial.
• Transición suave: aparece gradualmente durante el pulso de apertura, se mantiene, desaparece gradualmente de vuelta al estado base durante el pulso de cierre, de modo que el bucle sea una disolución suave.

Un clip se muestra durante [inicio, inicio + duración) y un estado final que cae exactamente en su final nunca se renderiza. Termina la interpolación de cierre un fotograma antes (inicio + duración - 1/fps) para que el último fotograma visible sea realmente el estado base; de lo contrario, el bucle está un fotograma corto para cerrar.

Un clip que termina en un fotograma diferente al que comienza se percibe como un error, no como un bucle.

4. Construye en HyperFrames

npx hyperframes init <directorio-del-proyecto>

El index.html raíz declara el lienzo. Configúralo con el tamaño de píxel exacto de la ubicación: HyperFrames renderiza en las dimensiones creadas de la composición e ignora cualquier tamaño que asumas:

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

Reglas que hacen o deshacen este paso:

• No codifiques 1920px/1080px en #root; estilízalo con width:100%; height:100%.
• No hay un preajuste --resolution para 21:9 o 3:2 — --resolution landscape-4k es 3840x2160, que tiene la forma incorrecta y será rechazado.
• Dale al div anfitrión, la raíz de la escena y la clave de la línea de tiempo el mismo id. Un desajuste hace que cada renderizado espere 45 s por escena y luego muestre fotogramas estáticos.
• Usa fromTo, no from, dentro de una escena: el anfitrión reubica la escena y from se desplaza al rebobinar, que es exactamente lo que rompe un bucle.
• Las fuentes deben incluirse como archivos en assets/fonts/ con @font-face; solo las familias incluidas se resuelven por nombre.
• Coloca el texto y las copias en la composición como variables (data-var-text), nunca integradas en una imagen.
• Mantén cada escena en compositions/ como su propia subcomposición para que un solo pulso pueda ser re-renderizado.

references/hyperframes-build.md contiene los fragmentos de técnica de bucle, los comandos de verificación e instantánea, las banderas de renderizado y una canalización de lienzo a ffmpeg para recurrir a ella cuando un renderizado del navegador 3840x1646 es demasiado lento para iterar. Las especificaciones y la verificación son las mismas de cualquier manera.

5. Genera imágenes de apoyo solo cuando el concepto lo necesite

Las fotos, ilustraciones y fondos atmosféricos provienen de la generación de imágenes. Nunca generes la interfaz de usuario de la app con un modelo de imagen — alucina interfaces y una interfaz de usuario falsa en una lista de la tienda es peor que ninguna interfaz de usuario. Usa capturas de pantalla reales para la app; usa generación para todo lo demás.

mcode-tools connector tools --keyword image
mcode-tools connector tool <nombre_herramienta>          # lee el input_schema primero
mcode-tools connector call <nombre_herramienta> --args '{"prompt":"...","aspect_ratio":"21:9"}'

references/asset-generation.md tiene el flujo completo de descubrimiento y llamada, además de cómo solicitar una relación de aspecto específica.

6. Verifica, captura, previsualiza — luego renderiza

npx hyperframes check --json                                  # debe estar limpio
npx hyperframes snapshot --at 0,4,8                            # lee los PNG
npx hyperframes preview --background                           # dale al usuario la URL

Mira las instantáneas antes de mostrar la vista previa. Las comprobaciones aprobadas por sí solas no significan que el fotograma se vea bien.

Renderiza solo después de que el usuario haya visto la vista previa y la haya aprobado, o cuando haya solicitado el archivo sin paradas:

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

Agrega --video-frame-format png cuando la fuente sea una grabación de pantalla de la app, para que el texto de la interfaz de usuario y los colores planos sobrevivan a la extracción de fotogramas.

Itera en instantáneas, renderiza una vez. Una instantánea de un solo fotograma es casi instantánea, así que evalúa la composición con npx hyperframes snapshot --at 0,4,7.9 y lee los PNG. Un renderizado de entrega completo de 3840x1646 de 8 segundos lleva aproximadamente 9 segundos en un Mac con chip M: el renderizado no es la parte lenta, la iteración sí lo es. Renderiza una vez que los fotogramas se vean bien.

Renderiza la prueba en calidad de entrega, o recodifícala antes de confiar en el veredicto del empalme. Un renderizado de calidad de borrador lleva ruido de cuantificación, y el ruido del codificador en el fotograma final difiere del ruido en el primer fotograma. Eso se manifiesta como una diferencia de bucle que no es geométrica, y terminarás persiguiendo un error que no existe. Si una prueba pequeña provino de --quality draft, recodifícala de la misma manera que lo haría el script de conformidad (libx264 -crf 18 -pix_fmt yuv420p) y verifícala.

7. Conforma el archivo a las especificaciones

Ejecuta esto incluso después de un renderizado de HyperFrames. La frecuencia de fotogramas incorrecta y el tamaño de píxel incorrecto son las dos razones de rechazo que la gente encuentra primero.

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

Cada ubicación necesita su propia composición y su propio renderizado. El lienzo del encabezado es 21:9 y el lienzo de búsqueda es 3:2; recortar uno en el otro descarta la composición y coloca el sujeto fuera del encuadre. La conformidad corrige la resolución, la frecuencia de fotogramas y el códec; no puede corregir una composición construida para la forma incorrecta. Configura la raíz de la composición de búsqueda en data-width="3840" data-height="2560".

Una raíz de proyecto por ubicación. La composición raíz declara el lienzo, por lo que las dos ubicaciones no pueden compartir una raíz. Dale a cada una su propia carpeta de proyecto con su propio index.html y una copia de los activos: check y snapshotsolo miran la raíz, y render --composition <archivo> renderiza un archivo de composición independiente.

El script escala y recorta al lienzo exacto, fuerza una velocidad de fotogramas constante de 30 o 60 fps, codifica H.264 yuv420p (sin alfa), elimina el audio y establece faststart. Se niega a escalar hacia arriba silenciosamente y lo dice cuando la fuente es demasiado pequeña.

8. Verifica antes de entregar

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

El script verifica dimensiones, relación de aspecto, velocidad de fotogramas (constante, exactamente 30 o 60), duración, códec, formato de píxel y audio. También evalúa el empalme del bucle: compara el primer fotograma con el último fotograma en relación con el movimiento típico de fotograma a fotograma del clip, de modo que un bucle que es más disruptivo que un paso de fotograma ordinario se informa como un salto visible. Escribe una tira *-seam.png de ambos fotogramas para su inspección visual. Debe salir con código 0. Corrige la composición y re-renderiza si no lo hace.

Luego, extrae el fotograma de póster y míralo por sí solo: esta es la imagen fija que la tienda muestra antes de que comience la reproducción, por lo que si necesita un título para tener sentido, el video necesita trabajo. Elige el fotograma más fuerte, que no es necesariamente el primero:

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

Informa el código de tiempo que elegiste. Los fotogramas de póster se establecen en el activo en la Biblioteca de Activos y no se pueden editar después de que el activo sea aprobado, por lo que la elección debe hacerse antes de enviar.

9. Entrega

Proporciona al usuario:

• la(s) ruta(s) del archivo final, una por ubicación
• el informe de verificación
• el fotograma de póster y qué fotograma es
• los pasos de publicación

Un activo creativo debe pasar tres puertas separadas: cargado, aprobado y colocado, y la aprobación por sí sola no lo publica. references/publishing.md tiene ambas rutas con los comandos asc exactos:

asc asset-library view --app APP_ID                     # find the library id
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                     # find the localization id
asc localizations placements create --localization-id LOC --video-id VID \
  --placement-type PRODUCT_PAGE_HEADER_ASSET           # or APP_STORE_SEARCH_RESULTS_ASSET

Para una aplicación que ya está en vivo, la versión corta en App Store Connect es: Apps → tu aplicación → barra lateral → Biblioteca de Activos → + → Cargar Activos Creativos → sube ambos archivos → establece un fotograma de póster → Agregar para Revisión → Enviar para Revisión → espera APROBADO → la versión en vivo → Información de la Página de Producto → "Encabezado y Resultados de Búsqueda" → Examinar Activos → elige el activo → Siguiente → Publicar. Eso se publica sin una nueva versión y sin una nueva revisión. Si la aplicación aún no tiene una versión en vivo, adjunta los activos a la próxima versión y envíala.

Indica al usuario que verifique el resultado con Vista Previa en la pestaña Encabezado y Resultados de Búsqueda: muestra el activo en iPhone y iPad, en todas las orientaciones, idiomas y Modo Oscuro, y el recorte difiere por ubicación. Los fotogramas de póster no se pueden editar después de que el activo sea aprobado, así que elige uno antes de enviar.

Detente ahí. No ejecutes la carga, el envío de revisión o la publicación tú mismo. La carga y publicación son pasos del usuario.

Contrato de salida

• out/<app>-header.mp4 — 3840x1646, H.264 yuv420p, 30 o 60 fps constante, 5–30 s, sin alfa, sin audio, menos de 500 MB
• out/<app>-search.mp4 — 3:2 dentro de 1920x1280–3840x2560, mismas reglas de codificación
• un informe de verificación con cada verificación APROBADA
• un fotograma de póster y su código de tiempo
• una nota de entrega breve con los pasos de publicación de references/publishing.md

Ambas ubicaciones obtienen su propio archivo. No entregues un solo archivo para ambas.

Manejo de fallos

Síntoma	Qué hacer
ffprobe / ffmpeg no encontrado	brew install ffmpeg (macOS) o choco install ffmpeg (Windows); los scripts los necesitan para verificar y conformar
HyperFrames no puede iniciar Chrome	npx hyperframes browser ensure, luego npx hyperframes doctor --json y verifica .ok
El renderizado se siente lento	Por lo general no lo es. Un renderizado de entrega de 3840x1646, 8 s mide alrededor de 9 s en un Mac con chip M. Si realmente es lento, verifica que el renderizador tenga trabajadores de GPU e itera en fotogramas de hyperframes snapshot en lugar de re-renderizar. --quality looks es más rápido que --quality delivery si solo necesitas un vistazo
El codificador etiqueta el archivo con nivel 4.1	Ambos lienzos exceden el límite de macrobloques del nivel 4.1: 3840x1646 son 24720 macrobloques y 1920x1280 son 9600, frente a un límite de 8192. Recodifica con -level 5.1
La verificación del empalme falla	Corrige el último pulso para que el estado regrese al estado base. Una transición suave (--seam-crossfade) es un recurso alternativo, no una solución, porque consume C segundos de contenido
El texto es ilegible en tamaño de miniatura	Agrándalo. Apple señala que los activos aparecen de manera diferente en la tienda, por lo que la representación más pequeña es la prueba real
Carga rechazada en App Store Connect	Vuelve a ejecutar verify-video.mjs en el archivo que realmente se cargó, no en el original local. asc asset-library videos upload también valida el archivo contra las especificaciones en vivo de Apple antes de cargarlo, por lo que su error nombra la regla que omitiste
Apple rechaza la ubicación	La ranura ya puede estar ocupada: la creación de una ubicación no reemplaza una existente. Usa asc localizations placements list para ver las ubicaciones actuales y asc localizations placements delete para eliminar la anterior antes de crear la nueva