Demo reel para Flutter
Construye un breve video promocional en bucle de una app Flutter como una app Flutter independiente para macOS en
<flutter app>/demo, lo renderiza offline fotograma a fotograma y lo codifica. El reel
utiliza las pantallas reales de la app, su arte, fuentes y contenido, una capa 3D sobre
flutter_scene (Flutter GPU sobre Metal), un kit 2D de partículas y títulos, y cortes
sincronizados con la música.
Las rutas a continuación son relativas a la carpeta de este skill (la carpeta que contiene este
SKILL.md). En Claude Code, esa carpeta es ${CLAUDE_SKILL_DIR}.
Reglas básicas
- Nunca modifiques la app. Copia lo que necesites (arte, fuentes, capturas de pantalla,
datos de contenido, colores del tema) dentro de
demo/. El andamio solo añadedemo/**a las exclusiones del analizador del paquete padre. - Cada fotograma es una función pura de
t. Sin estado entre fotogramas, sinRandom(), sin relojes, sin simulación: movimiento de forma cerrada, aleatoriedad con semilla. Esto es lo que hace posible el desplazamiento, la exportación por bloques, el desenfoque de movimiento y un bucle sin costuras. Lee references/kit.md antes de escribir los shots. - Sigue las reglas de voz del proyecto (AGENTS.md, CLAUDE.md o similar): palabras que la app nunca usa, cómo se nombra a sí misma el producto, tono.
- Acuerda antes de construir. Entrevista al usuario, luego escribe un guion que ellos aprueben.
- Solo macOS. Necesita Flutter con escritorio macOS, ffmpeg (
brew install ffmpeg), y Python 3 con Pillow (hojas de contacto) y numpy (análisis de audio).
Flujo de trabajo
1. Entrevista
Pregunta antes de empezar, ofreciendo un valor predeterminado para cada punto para que el usuario pueda responder rápido:
- Duración y bucle (por defecto 30 s, bucle sin costuras), formatos (horizontal 1920x1080 y vertical 1080x1920, vertical diseñado para Reels, TikTok y Shorts), 60 fps.
- Banda sonora: un archivo (¿con letra?) o ninguna, y quién posee los derechos.
- El mensaje: las 3–5 cosas que mostrar, la llamada a la acción (URL, insignias de la tienda), afirmaciones que hacer (¿gratis? ¿calificaciones? ¿contadores?).
- Apariencia y tono: qué tan exagerado, la marca de la app, referencias.
- Pantallas reales: cuáles, y ¿puedes ejecutar la app para capturarlas (cuenta de prueba, datos con semilla)? ¿También tomas atmosféricas inventadas?
- Texto en pantalla: solo palabras clave (por defecto) o subtítulos completos, ortografía del nombre del producto, palabras a evitar.
- Algo especial: huevos de pascua, personajes, cosas que nunca mostrar.
2. Estudia la app
Lee el tema de la app (colores, fuentes), activos (logotipos, personajes, iconos), contenido (nombres reales, números, datos a mostrar) y sus pantallas principales. Anota lo que la hace distintiva. Planifica las capturas de pantalla y tómalas, o pídeselas al usuario (consulta "Capturas de pantalla reales" en references/craft.md).
3. Analiza la banda sonora
python3 scripts/analyze_audio.py <track>
Convierte su tempo, fase de beat, secciones y líneas vocales en cues con nombre, como en references/audio-sync.md. Sin banda sonora, aún así elige un tempo y corta en su cuadrícula.
4. Escribe el guion
Crea una tabla temporizada con, para cada shot: la música o letra, la imagen horizontal, la imagen vertical y el texto en pantalla (plantilla en references/craft.md). Marca el gancho, el drop, la tarjeta final y la costura del bucle. Obtén la aprobación del usuario e itera hasta que diga adelante.
5. Andamio
zsh scripts/scaffold.sh <flutter app dir>
Ejecútalo con la ruta completa a la carpeta scripts/ de este skill; funciona desde
cualquier directorio. Crea:
<app>/democonflutter create --platforms macos;- añade flutter_scene, vector_math y audioplayers, y ejecuta
flutter_scene:init; - habilita Flutter GPU (
FLTEnableFlutterGPU) y desactiva el sandbox de la app (el exportador ejecuta ffmpeg); - copia el kit de inicio desde
assets/template/, creaart/,art/screens/,audio/yfonts/, e ignoraout/; - excluye
demo/**del analizador del paquete padre.
Funciona dentro de pub workspaces (el demo sigue siendo un paquete independiente), y se niega a sobrescribir una carpeta existente.
Luego configura:
lib/core/timeline.dart:kDuration,kBpm,kBeatPhasey losCues.lib/core/format.dart:Palettea partir del tema de la app, yFonts(copia los archivos de fuente endemo/fonts/y decláralos enpubspec.yaml).- Activos:
art/(enumera las subcarpetas enpubspec.yaml) yaudio/track.wav(48 kHz PCM).
Construye una vez y renderiza las imágenes fijas del ejemplo para probar que la configuración funciona:
cd <app>/demo && flutter build macos --profile && tool/run.sh stills "0.3,2.3,9" both
6. Construye el reel
Reemplaza lib/shots/example.dart con una sección por cada parte del guion, enuméralas
en Director.sections, y establece los golpes de cámara en Director._hits. Trabaja
sección por sección:
- Escribe la sección (marco 3D y capas 2D debajo y encima) usando el kit (references/kit.md) y flutter_scene (references/flutter-scene.md).
- Ejecuta
flutter build macos --profile, luego renderiza imágenes fijas en los momentos clave de la sección en ambos formatos:tool/run.sh stills "t1,t2,..." both. - Crea una hoja de contacto por formato e inspecciónala, además de imágenes fijas individuales
de cerca donde los detalles importen:
python3 tool/sheet.py out/l.png 4 480 out/stills/landscape_*.png. Si no puedes ver imágenes, dile al usuario qué imágenes fijas revisar y qué buscar. Corrige y repite.
Ejecuta la lista de verificación de revisión en references/craft.md sobre todo el
reel antes de exportar. El usuario puede verlo con la música en la
app de vista previa (open build/macos/Build/Products/Profile/*.app); las imágenes fijas no
pueden mostrar la sincronización.
7. Exportar
tool/export.sh draft both # 1x, sin desenfoque de movimiento: una verificación rápida completa
tool/export.sh final both # 2x súper muestreado, desenfoque de movimiento de 4 muestras
Una exportación final toma aproximadamente 10–15 minutos por formato para 30 s. Ejecútala en segundo plano
si tu entorno lo permite, y no la sondees. Después, verifica los archivos con ffprobe: el recuento de fotogramas es kDuration * kFps, la
duración es correcta y hay un flujo de audio. Extrae algunos fotogramas de los
MP4, incluidos el último fotograma y el fotograma 0 (la costura del bucle).
8. Entrega e itera
Dale al usuario las rutas (demo/out/final/<format>.mp4 para subir,
<format>_master.mov ProRes para edición), los tamaños de archivo y qué verificar.
Espera comentarios. Los típicos, con correcciones, están en
references/craft.md: texto mostrado demasiado breve, texto
cubierto, subtítulos no deseados, costuras en contornos, rayos de luz dura, un conjunto de elementos
que se ven igual, redacción en vertical. Corrige todos los comentarios en una ronda antes de
volver a renderizar.
Archivos
- references/kit.md: la arquitectura y las API del kit de inicio.
- references/flutter-scene.md: configuración, apariencia y problemas de flutter_scene sin conexión.
- references/audio-sync.md: tempo, fase, letra y cues de una pista.
- references/craft.md: plantilla de guion, reglas de texto, recetas de efectos, capturas de pantalla, la lista de verificación de revisión.
scripts/scaffold.sh: crea la app demo.scripts/analyze_audio.py: tempo, fase de beat, volumen por compás, onsets.assets/template/: el kit de inicio que el andamio copia.