agens-no/app-promo

Vídeo promocional de app (Remotion + iPhone real + UI real)

Este método se desarrolló en cuatro apps iOS pequeñas (Unblock, Talljakt, Georama y Quiz) y está escrito para que se pueda repetir en cualquier app. Todo lo específico de la app vive en examples/. Las partes reutilizables viven en templates/. Las técnicas detalladas, los problemas y las variables ajustables están en references/techniques.md. Léelo antes de construir.

Idioma: habla al usuario en el idioma que use. Si empieza en noruego, responde en noruego. El idioma del texto en el vídeo es una elección separada (pregunta 3 a continuación).

0. Entrevista primero (breve)

Pregunta todo junto (AskUserQuestion o un mensaje). Sugiere valores por defecto para que el usuario pueda responder simplemente "por defecto":

1. Duración: 20–60 s. Por defecto ~30 s.
2. Formato: 9:16 vertical 1080×1920. Por defecto 60 fps. ¿También 1:1 o 16:9?
3. Idioma del texto en pantalla.
4. Uso: uso privado, redes sociales (Reels/TikTok, zonas seguras) o vista previa de App Store. Las vistas previas de App Store deben ser grabaciones reales, máximo 30 s, sin efectos 3D inventados, por lo que este método se adapta mal a ellas.
5. Cuánto de la UI sale de la pantalla: ninguno (discreto: grabaciones reales, solo zooms de enfoque y transiciones propias de la app, ver examples/kjop), sutil (uno o dos momentos destacados), medio o completo (todo sale de la pantalla). El valor por defecto es sutil a medio; ninguno es adecuado para apps cotidianas simples (listas, formularios, ajustes). Completo es para apps cuyas piezas son objetos físicos naturales (fichas de juego); para apps ordinarias (listas, formularios, tarjetas), solo saca 1–3 elementos clave y mantén el resto en pantalla.
6. Libertad creativa: ¿debería el agente inventar el concepto?
7. Música: generada en código (por defecto, sin licencia necesaria) o con su propia pista. Dale a cada app su propia paleta sonora para que dos vídeos nunca suenen igual (ver references/techniques.md#sound).
8. Qué funciones mostrar (3–5), y ¿cuál es el elemento o momento "héroe" de la app?
9. Final: dos opciones probadas; elige según la app y pregunta si no está claro. (a) Un bloque de logotipo construido a partir de los propios elementos de la app (Unblock: el logotipo se ensambla con fichas 3D, la ficha de bronce aterriza al final). (b) La pantalla de inicio en el teléfono con un eslogan encima, donde el icono + el nombre son la última línea (Talljakt: "Seis números. / Un objetivo. / [icono] Talljakt.").
10. Color del teléfono: naranja cósmico, azul profundo o plateado. Elige el que coincida con el color de acento de la app.

Las respuestas guían principalmente el concepto, cuánto sale de la pantalla, el tempo (bpm) y los colores.

0a. Verificación previa: comprobar las herramientas

Antes de construir nada, comprueba qué está instalado e infórmalo en una lista breve. Ofrece instalar lo que falte, e instala solo después de que el usuario diga que sí (son cambios en el sistema). Omite todo lo que ya esté presente.

Herramienta	Verificación	Instalación
Xcode + herramientas de línea de comandos	xcodebuild -version, xcode-select -p	App Store (Xcode), luego xcode-select --install
Tiempo de ejecución del simulador de iOS con un tipo de dispositivo iPhone 17 Pro	xcrun simctl list runtimes, `xcrun simctl list devicetypes	grep "iPhone 17 Pro"`
baguette	baguette --version	brew install baguette
Blender	ls /Applications/Blender.app	brew install --cask blender
Node 22	node --version	nvm install 22 (o brew install node@22)
ffmpeg	ffmpeg -version	brew install ffmpeg
Python 3 + Pillow	python3 -c "import PIL"	python3 -m pip install --user pillow
Homebrew (para lo anterior)	brew --version	el script de instalación oficial de brew.sh, ejecutado por el usuario

Luego configura el proyecto Remotion (references/techniques.md#setup) y convierte el modelo de iPhone una vez (paso 6 a continuación). Ambos son locales al proyecto y no necesitan permisos adicionales más allá de trabajar en el repositorio.

0b. Carpeta de entrega (una vez por Mac)

Los vídeos terminados se entregan en una carpeta fija en la máquina, no solo en el out/ del proyecto. La elección se almacena por Mac en ~/.config/app-promo/destination (una línea, ruta completa).

• Lee el archivo al inicio. Si existe, usa la carpeta sin preguntar.
• Si falta, pregunta una vez (AskUserQuestion): ~/Movies/App Promos (recomendado), la carpeta out/ del proyecto, el Escritorio o una ruta personalizada. Crea la carpeta y escribe la ruta en ~/.config/app-promo/destination.
• El usuario puede cambiarla en cualquier momento si lo pide; actualiza el archivo.

1. Flujo de trabajo

1. Lee la app. README, tokens de color (busca Color(, hex, structs de tema), fuentes, copia. Usa la copia de la propia app en el vídeo cuando sea buena.
2. Busca puntos de entrada de depuración para mostrar estados sin jugar: argumentos de lanzamiento (--design-*), esquemas de URL (myapp://design-home?state=…) o fixtures. Si no hay ninguno, pregunta antes de añadir hooks solo de DEBUG a la app.
3. Compila e instala en un simulador dedicado de iPhone 17 Pro. Las capturas de pantalla deben ser de 1206×2622 o no coincidirán con la pantalla del modelo de teléfono. Ver references/techniques.md#simulator. 3b. Para grabaciones de pantalla reales: lee references/recording.md. Prepara primero la escena y los puntos de pulsación, graba tomas cortas sin inspección de UI, compilaciones ni análisis de vídeo durante la grabación, y comprueba el tiempo bruto antes de Remotion. Una sola toma continua de todo un flujo (como en examples/quiz) mantiene coherentes todos los números, barras de progreso e historiales.
4. Toma capturas de pantalla de cada estado. Para secuencias fijas/recortadas, reprodúcelas con pulsaciones reales y captura después de cada pulsación (ver references/consistency.md). Para vídeo, haz esa inspección en un ensayo separado, nunca durante la toma final. Bloquea la barra de estado (9:41, 100 %, descargando, o un indicador de carga verde). Obtén los marcos de los elementos con baguette describe-ui.
5. Recorta elementos de UI con un tools/prep_<app>.py específico de la app que usa templates/tools/prep_helpers.py: sprites, fondos vacíos y un JSON de rectángulos. Verifica cada conjunto visualmente (compuesto sobre magenta).
6. Convierte el modelo de iPhone de baguette (USDZ) a GLB con Blender (templates/tools/convert_model.py).
7. Configura el proyecto Remotion, o reutiliza uno: copia templates/src/three/*, Title.tsx, brand.ts, remotion.config.ts, tools/sheet.sh y tools/prep_helpers.py.
8. Escribe una guía de ritmo (timeline.json) en fotogramas sobre una cuadrícula de bpm (120 bpm a 60 fps = 30 fotogramas por pulso). Tanto la imagen como el sonido leen este archivo.
9. Construye las escenas como un único "plano secuencia" continuo: la cámara se queda quieta y el soporte del teléfono se mueve. Los cambios de pantalla se ocultan con una transición: un giro, la navegación propia de la app, un zoom o un barrido desde un elemento, un empuje, un volteo, un paneo de látigo, un corte por coincidencia o un avance rápido. Varíalos, máximo dos giros por vídeo. Ver references/techniques.md#transitions.
10. Itera con hojas de contactos (tools/sheet.sh f1 f2 …) de fotogramas clave. Míralos. Renderiza el vídeo completo (rápido: ~1–2 min para 30 s).
11. Punto de control: muestra al usuario los primeros ~12 s antes de construir el resto.
12. Genera la banda sonora (tools/<app>_audio.mjs, copiado de un ejemplo) a partir de la misma línea de tiempo. Renderiza, mide el volumen (ffmpeg -af ebur128, apunta a −14 a −16 LUFS) y abre el archivo para el usuario.

12b. Verificación de consistencia (obligatoria antes de la entrega). Una discrepancia entre lo que se ve en la pantalla del teléfono y lo que se destaca fuera de ella parece un artefacto de IA. Revisa references/consistency.md y renderiza hojas de contactos ±2 fotogramas alrededor de cada transición, cambio de pantalla y elevación. 13. Texto para compartir: escribe un texto corto para pegar donde se comparta el vídeo (formato a continuación). Cópialo al portapapeles (pbcopy) y muéstralo en la respuesta dentro de un bloque de código. No lo guardes como archivo. 14. Entrega: copia el render más reciente aprobado a la carpeta de entrega (0b) como <App> promo.mp4. Sobrescribe la entrega anterior para la misma app; el historial de versiones (-v2, -v3 …) se queda en out/. Proporciona la ruta del archivo entregado en la respuesta.

Formato de texto para compartir

El texto normalmente se publica en Slack, así que usa el formato de Slack (mrkdwn): un título en negrita con asteriscos simples y viñetas con "• " (un "- " pegado no se convierte en lista). Escríbelo en el idioma del vídeo.

*<App> – <Eslogan en 2–4 frases cortas/palabras, idealmente el del vídeo>.*
<Una frase: qué es la app, para quién o qué.>

• <Punto: la acción principal, concreta y activa>
• <Punto: las opciones que da la app (temas, modos, área, ritmo …)>
• <Punto: …>
• <Punto: recompensa/compartir/qué la hace especial>

Reglas: 4–5 puntos, sin punto final al final de los puntos, dirígete directamente al lector, verbos concretos, sin clichés de marketing. Empieza por cómo se usa realmente la app: los primeros 2–3 puntos explican el mecanismo concretamente antes de opciones y extras. Luego describe lo que la app te permite hacer, no solo lo que muestra el vídeo: agrupa las opciones por punto ("Practica países, capitales o banderas") para que el lector vea el rango. Usa los nombres propios de la app para las cosas, y comprueba en el código lo que realmente hace cada modo (los README se quedan obsoletos). Ver examples/*/share.txt.

2. Una plantilla de concepto que funcionó

Un héroe, un movimiento que lo une todo, la copia de la propia app:

Parte	Unblock	General
Gancho 0–2.5 s	Las fichas caen sobre un tablero flotando en la oscuridad, sin teléfono. "Atascado."	El problema que resuelve la app, mostrado con los elementos de la app, sin el teléfono
Revelación	El teléfono se construye alrededor del tablero mientras la cámara se aleja	El mismo elemento resulta estar dentro de la app
Bucle principal	4 movimientos al ritmo, un contador fuera de la pantalla	La acción principal en 3–4 pulsos
Momento héroe	El héroe sale de la pantalla y vuela hacia la cámara, destello bronce	UN gran momento (un efecto fuera de pantalla, o la mejor animación propia de la app en cámara lenta)
Recompensa	Pantalla de resultados, estrellas 3D que rebotan	La recompensa o el resultado
Funciones (transiciones variadas entre ellas)	Selector de nivel, tarjeta diaria, puntuación	2–3 funciones, cada una con un elemento destacado
Final	Logotipo construido a partir de fichas 3D, eslogan	Bloque de logotipo a partir de elementos de la app, o la pantalla de inicio con eslogan + nombre

Si la app tiene una animación propia genuinamente buena (Quiz: el botón "Mostrar respuesta" se rasga en Correcto/Incorrecto), conviértela en el héroe: acércate mucho, ralentízala con una rampa de velocidad, dale su propio sonido y no le pongas título.

2b. Recursos visuales de buenas promos de apps

Las buenas referencias usan la pantalla y el contenido, no solo la disposición. Planifica al menos 3–4 de estos por vídeo:

• Recorta la pantalla: acércate lo suficiente para que solo se vea una parte (un temporizador, una fila de botones, una ecuación). El teléfono queda cortado por el borde del encuadre. Usa poses de focus.
• Tarjetas de contenido al lado o delante del teléfono: tarjetas o pósters reales de la app (tarjeta de compartir, tarjeta de resultados, sugerencia) como planos planos ligeramente rotados detrás o delante del teléfono.
• Varias tarjetas de contenido a la vez: despliega 3–5 variantes (páginas, soluciones, pósters).
• Varios dispositivos: dos teléfonos lado a lado cuando la historia trata de compartir o "lo mismo para todos", con etiquetas de nombre encima. Teléfono + Watch/iPad si la app lo admite (baguette tiene modelos de iPad y Watch).
• Los elementos de la app como decoración: fichas, botones, chips o iconos reales flotando en el fondo (desenfocados = lejanos), o ampliados como tipografía encima del teléfono. Un motivo temático (línea de pulso, trazo de crayón, papel cuadriculado).
• Lo que la app crea, como objeto: la impresión, el póster, la tarjeta, idealmente sin el teléfono.
• Burbujas de diálogo o pensamiento para cosas que ocurren fuera del teléfono (Quiz: la respuesta hablada sale al lado de la tarjeta, luego cae sobre el botón Correcto/Incorrecto para "presionarlo").

2c. Texto y encuadre

• Los títulos grandes centrados en la parte superior llevan el mensaje: 2–4 palabras por línea, máximo dos líneas, la segunda línea o palabra clave en el color de acento.
• Subtítulos pequeños en la parte inferior, con moderación, solo cuando el título necesite aclaración (2–3 veces en un vídeo de 30 s). Deben ser legibles: al menos ~50 px, en un chip con fondo claro y sombra (no texto suelto), colocados abajo para que nunca crucen el marco del teléfono, visibles durante al menos 2 s.
• Afirma solo lo que la app realmente hace. Verifica qué es realmente una función antes de escribir sobre ella.
• Las tarjetas de texto a pantalla completa son compatibles: una superficie de color (el color primario de la app) con un título grande centrado de dos líneas, que entra barriendo desde el elemento que estaba en foco y sale deslizándose hacia la siguiente escena. Úsala como respiro o puente antes del final, idealmente una pregunta que desafíe al espectador ("¿Puedes encontrarlo a tiempo?"). No saltes directamente de la acción intensa a la pantalla final. Ver QuestionCard en examples/talljakt y examples/quiz.
• Sin icono fijo de la app ni nombre en una esquina. Muestra el nombre solo al final, en el logotipo o como la última línea del eslogan.
• Mantén el encuadre limpio: una idea por escena. Si una función tiene poco que mostrar (un ajuste), intégrala como título o un enfoque breve en otra escena en lugar de darle una escena propia. Evita título + teléfono con zoom + una fila de elementos + título al mismo tiempo.
• Tempo: sin tiempo muerto. Cada escena tiene un evento en ~1 s de empezar, y ningún título se queda sobre una pantalla estática más de ~1.5 s. Los pasos que se repiten (preguntas 2–13 de un cuestionario) se pueden avanzar rápidamente.
• Muestra las opciones como acción, no como texto. Si la app tiene modos o ajustes, muestra la selección del valor por defecto (la tarjeta se levanta un poco), una pulsación en la alternativa (se levanta, la pantalla cambia de estado), luego una pulsación en "Iniciar" que lleva a ese modo.
• Las interacciones que de otro modo no quedarían claras (abrir un menú, elegir una opción) reciben un indicador de pulsación (un círculo que presiona y se ondula hacia fuera) sobre lo que la app realmente responde.

3. Principios

• La UI real es mejor que la UI recreada. Usa capturas de pantalla, grabaciones y recortes, no copias HTML de la app. El texto que debe cambiar (contadores, puntuaciones) se dibuja en la fuente de la app con PIL y se verifica contra el original.
• Dosifica lo "fuera de pantalla". Es condimento. El valor por defecto es un momento héroe y 1–2 funciones elevadas.
• El zoom y el enfoque son la herramienta principal para enfatizar. Mueve la cámara a la parte de la pantalla que importa.

4. Referencia: ejemplos

• examples/unblock: juego de puzles, fichas 3D, mucho fuera de pantalla.
• examples/quiz: app educativa, animaciones de tarjetas, burbujas de diálogo.
• examples/talljakt: juego de números, pantalla de inicio con eslogan.
• examples/kjop: app de compras, estilo discreto sin fuera de pantalla.

5. Archivos de técnicas y configuración

• references/techniques.md – técnicas detalladas, variables de configuración, resolución de problemas.
• references/consistency.md – verificación de consistencia visual.
• references/recording.md – guía para grabaciones de pantalla reales.

6. Dependencias del sistema

Ver la sección 0a para la lista completa de herramientas necesarias y comandos de instalación.