Changelog → Video de Marca
Entrada: un changelog .md (temas + elementos, como el digest semanal de HyperFrames).
Salida: un proyecto HyperFrames limpio, listo para revisión, en
projects/active/weekly-changelog-<rango>/. Renderizar solo cuando se pida.
Cargar primero, no negociable: motion-doctrine (+ cut-the-curve,
oversized-cursor si aparece un cursor, seam-craft) y captions-overlay.
Esta skill provee el pipeline específico del changelog; el doctrine provee la
ley de movimiento.
La directriz principal: visualiza, no enumres
Cada tema se ilustra con un mock animado de la interfaz real o un análogo fiel que represente visualmente el cambio en la experiencia — nunca viñetas de texto. Enruta cada tema/elemento a través de references/visualization-registry.md ANTES de escribir el guión; el registro decide ui-recreate / ui-analog / terminal / checklist. La checklist de texto es el ÚLTIMO recurso, reservado para elementos genuinamente no visuales (listas de correcciones de fiabilidad).
Pipeline
0 · Inicializar el proyecto desde los assets de ESTA skill — no negociable
Haz esto antes de escribir cualquier composición HTML. Omitirlo siempre produce un video que se parece a un proyecto similar que construiste antes, NO a la marca de esta skill — esa es la forma más común de que esta skill se salga de la marca. Los assets, fuentes y andamio de la skill SON la skill; el prompt SKILL.md es un enrutador.
mkdir -p project/assets/fonts
cp <SKILL_DIR>/assets/fonts/*.woff2 project/assets/fonts/
cp <SKILL_DIR>/assets/bgm.mp3 project/bgm.mp3
ffmpeg -y -stream_loop 15 -i <SKILL_DIR>/assets/bg-pattern.mp4 -t <TOTAL> \
-vf "scale=1080:1080,fps=30,eq=saturation=0.72,[email protected]:t=fill" \
-an -c:v libx264 -crf 20 -pix_fmt yuv420p project/assets/bg-pattern-<TOTAL>s.mp4
cp <SKILL_DIR>/examples/master-skeleton.html project/index.html
Luego lee references/build-spec.md de principio a fin (no hojeado) — define los tokens de marca (TT Norms Pro + ABC Solar Display + TT Norms Mono, crema #f5f6f4, verde racionado #5ef17c, tarjetas de vidrio con bordes de tinte verde, forma de pastilla para kicker/sec-chip, carril de subtítulos de 32px en top: 990) que cada escena hereda del andamio.
Solo ENTONCES comienza los pasos 1-6 a continuación. Los pasos 1-4 (analizar, enrutar, guionizar, VO) planifican lo que va en el andamio; el paso 5 completa los marcadores de posición (<RANGE>, <TOTAL>, <CUT_N>, <DUR_N>, cuerpos de escena) dentro del ya copiado project/index.html — NO reescribes el cromo, las fuentes, la paleta o la carcasa del andamio.
Si te ves a punto de usar cp en el index.html de un video anterior, o escribir tus propias declaraciones @font-face, o diseñar un fondo de shader WebGL en lugar de usar el MP4 de patrón de fondo codificado arriba: DETENTE. Borra el index.html actual y reinicia desde el cp del andamio maestro. Reconstruir el contenido de la escena sobre el andamio correcto es más barato que adaptar la marca a posteriori sobre un andamio incorrecto.
1 · Analizar + corte editorial
- Extraer: rango de semana, estadísticas del titular (lanzamientos, commits), temas, elementos.
- Presupuesto: 45-60s total. Título ≤2s, outro ≤3.5s, 4 temas ≈ 9-12s cada uno.
- Por tema, mantener UNA visualización héroe + como máximo 3 elementos hablados. Todo lo demás existe solo como puntero al "digest completo" del outro. Cortar es el trabajo: un changelog con 30 elementos aún produce ≤14 compases hablados.
- Ordenar temas por historia: función destacada → superficie del producto → rendimiento → fiabilidad (el digest ya suele leerse así).
2 · Enrutamiento de visualización
Para cada tema, elegir la superficie de references/visualization-registry.md y escribir una línea: tema → superficie → las 2-4 acciones secuenciadas que realiza el mock, cada una vinculada a una frase del guión. Si ninguna superficie del registro encaja y no existe un análogo fiel, es una escena de checklist — no inventes una UI falsa para algo que no podemos representar honestamente.
3 · Guión de dos capas (oral vs display)
Escribir el guión como líneas token según references/script-voice.md:
registro conversacional, cada término técnico lleva una forma spoken
fonética de references/lexicon.json, mientras que display mantiene la
ortografía estándar. Los subtítulos muestran display; el VO lee spoken.
Cualquier término que no esté en el léxico: DETENTE y pregunta al usuario
cómo se pronuncia, luego agrégalo al léxico.
Guardar como script-tokens.json en el proyecto.
4 · VO — Annie (HeyGen, fija)
# texto de la capa oral solamente; words JSON = marcas de tiempo de referencia del texto HABLADO
# Ruta nativa del repositorio: la skill changelog-video se ejecuta desde la raíz del repositorio hyperframes,
# por lo que usa el asistente TTS de hyperframes-media directamente (sin paso de instalación `npx hyperframes`
# skills). Si has copiado la skill en otro repositorio, reemplaza con tu propia ruta a
# la herramienta heygen-tts.mjs de media-use / hyperframes-media.
node skills/hyperframes-media/scripts/heygen-tts.mjs ./vo-spoken.txt \
-o voiceover.mp3 --words vo-words.json \
--voice 330290724a1b470fb63153f34d4c0183 # Annie — realista (no sustituir)
Requiere CLI heygen ≥0.3.0 autenticado (heygen auth login --oauth).
Luego alinear las marcas de tiempo habladas de vuelta a los tokens de display:
node <SKILL_DIR>/scripts/align-captions.mjs \
--tokens script-tokens.json --words vo-words.json --out captions.json
captions.json es la entrada del carril de subtítulos (ortografía de display, temporización hablada).
El alineador imprime advertencias MISMATCH — resuelve cada una antes de construir
(generalmente una ortografía del léxico que el TTS renderiza como múltiples palabras). El audio
es el reloj: todos los tiempos de compás provienen de vo-words.json; una regeneración de VO reabre
cada costura.
Las temporizaciones de palabras son una compuerta estricta. Antes de pasar al paso 5, verifica
que vo-words.json no esté vacío y tenga un array words: [...] con start/end
por palabra. Si está vacío (0 bytes) o falta el array — un modo de fallo conocido
cuando el proveedor TTS devuelve audio pero sin carga útil de marcas de tiempo — NO CONTINÚES
sin ellas. Plan de contingencia: alinear forzadamente el audio producido contra el guión
de display usando whisper local:
uvx --from openai-whisper whisper voiceover.mp3 \
--model base.en --language en --word_timestamps True \
--output_format json --output_dir .
# luego ejecutar align-captions.mjs con --words voiceover.json (misma forma)
Whisper malinterpreta las representaciones TTS ("gee-sap" → "gsap", "heyjen" → "hey Jen",
etc.) — los subtítulos siguen usando la ortografía DISPLAY de script-tokens.json;
whisper solo proporciona las marcas de tiempo. align-captions.mjs maneja la unión.
Este plan de contingencia es la diferencia entre una compilación subtitulada y una
silenciosamente sin subtítulos.
5 · Construir
Seguir references/build-spec.md exactamente: tokens de marca + fuentes (incluidas
en <SKILL_DIR>/assets/), la codificación del fondo animado, andamio de escena,
cromo, carril de subtítulos, un momento de verde racionado por escena. Luego el orden
del doctrine: ledger.json (todas las costuras ordinarias cut-the-curve LEFT) → seam-stamp →
compases internos en palabras de VO → verificación seam-gate.
Los subtítulos no son opcionales. El esqueleto maestro incluye un IIFE de carril de subtítulos
que lee un array LINES — dejar ese array vacío es un error de envío, no una
elección de estilo. Poblarlo desde captions.json antes de pasar al paso 6:
// pegar en lugar de "const LINES = /* … */ []" en el IIFE del carril de subtítulos:
const LINES = /* contenido de captions.json */ [
{ id: 0, end: 2.74, w: [["Esta", 0.0], ["semana,", 0.30], …] },
…
];
Si align-captions.mjs se omitió o LINES está [], la verificación de fotogramas en el
paso 6 fallará — no lo ocultes eliminando #cap-line del
andamio.
6 · Compuertas (todas en verde antes de presentar)
bun run --cwd packages/cli hyperframes check(o el CLIhyperframesinstalado desde la skillskills/hyperframes-cli/local del repositorio) — 0 errores (contraste: texto tenue ≥ .66 alpha). NO usarnpx hyperframes@latest; el CLI local rastreado del repositorio es la fuente de verdad para el contrato de composición que esta skill produce.seam-gate.mjs verify— 0 fallos.- Reiniciar el servidor de vista previa (almacena en caché el paquete), revisar 3-4 compases
mediante
__player.seeken la página de composición sin procesar. - NO renderizar a menos que el usuario lo pida. Después de un render solicitado, verificar
fotogramas del MP4 (
ffmpeg -ss <t> … -frames:v 1): subtítulos presentes, video de fondo no negro, sin fotogramas pequeños/congelados. - Comprobación de presencia de subtítulos — fallo estricto. Muestrear 3-4 fotogramas distribuidos
en la ventana hablada del VO (por ejemplo,
t=3,t=15,t=30,t=42para un VO de 48s) y confirmar que el carril de subtítulos entop: 990renderiza texto visible en cada uno. Si algún fotograma en un intervalo hablado carece de subtítulos, la compilación se envía sin subtítulos — tratarlo como una compuerta roja y volver a verificar la población deLINESdel paso 5. Esto es exactamente lo que salió mal en la compilación v4 del 13-20 de julio.
Estructura del proyecto
projects/active/weekly-changelog-<rango>/
├── index.html # maestro de documento único (escenas como diapositivas, costuras selladas)
├── ledger.json # vector ledger (entrada seam-stamp)
├── script-tokens.json # guión de dos capas (fuente de verdad para VO + subtítulos)
├── vo-spoken.txt # generado: capa oral, una línea
├── voiceover.mp3 + vo-words.json + captions.json
├── bgm.mp3 # copia de <SKILL_DIR>/assets/bgm.mp3 (la pista base) a menos que el usuario proporcione una
└── assets/fonts/ + assets/bg-pattern-<dur>s.mp4
Antipatrones
| No hacer | En su lugar |
|---|---|
| Diapositivas con viñetas para cambios de UI | Mock de la superficie representando el cambio |
| UI falsa para elementos no representables | Escena de checklist honesta |
| "JSON"/"CLI" simple en el texto TTS | Formas habladas del léxico; display permanece estándar |
| Ortografías fonéticas en subtítulos | Los subtítulos siempre renderizan la capa de display |
| Adivinar la pronunciación de un término desconocido | Preguntar, luego ampliar el léxico |
| Hablar cada elemento del changelog | ≤3 por tema; el enlace del digest lleva el resto |
| Acentos verdes en todas partes | Un momento verde por escena (#5ef17c) |
| Empezar desde el index.html de un video anterior | Paso 0 — copiar examples/master-skeleton.html de esta skill en project/index.html, siempre |
@font-face / shader WebGL / BGM personalizado hecho a mano | Paso 0 — copiar los assets/ de esta skill textualmente; los assets de la skill SON la marca |
| Entregar sin invalidación de CloudFront | Ejecutar aws cloudfront create-invalidation en la distribución E2BSLVSZ7FG3U0 para la ruta exacta después de cualquier reemplazo en S3 — de lo contrario, el CDN almacena en caché el archivo antiguo |
Enviar con el array LINES vacío en el andamio | El paso 4 debe producir un captions.json poblado; el paso 5 debe pegarlo en el IIFE; la compuerta 6 del paso 6 debe confirmar subtítulos en los fotogramas renderizados. Un LINES vacío = envío sin subtítulos = repetir |
No tener vo-words.json → omitir subtítulos y enviar igual | Recurrir a la alineación forzada con whisper sobre el audio producido; los subtítulos no son opcionales |