chensiyuan040-hash/skill

HyperFrames 中文视频实战

En HTML se escribe el video, el motor renderiza fotograma a fotograma a MP4. Este skill es la acumulación práctica de un video completo de divulgación científica en chino de 6.5 minutos (con datos reales, locución y capturas de pantalla) de octubre de 2026. El enfoque está en los problemas que la documentación oficial no menciona y que solo se descubren tras haberlos sufrido.

Flujo completo (cinco pasos)

1. Inicialización: npx hyperframes init <dir> → Node22+, FFmpeg como prerrequisito; en la máquina local se necesita HYPERFRAMES_BROWSER_PATH=/usr/bin/google-chrome (el motor intenta descargar chrome-headless-shell automáticamente, pero puede fallar por problemas de red, ver pitfalls#1)
2. Estructura y contenido: El index.html principal encadena las sub-composiciones de las escenas; el material del contenido (datos reales/capturas de pantalla) se archiva primero en scripts/sources.md y luego se lleva a la pantalla — la densidad de información es lo primero en un video explicativo
3. Animación: Una timeline de GSAP en pausa por escena; sistema de subtítulos frase por frase + resaltado de ritmo (receta en references/scene-recipe.md)
4. Validación: npx hyperframes check todo en verde es requisito previo para renderizar; las estrategias de reparación están en references/pitfalls.md (el 90% de los errores tienen solución ya documentada)
5. Locución (opcional): edge-tts genera el audio → adaptar la velocidad según la duración real medida → el audio debe colocarse dentro de la raíz del index principal (no funciona dentro de sub-composiciones, ver pitfalls#6) → re-renderizar
6. Control de calidad y entrega: Tras renderizar, npx hyperframes snapshot extrae fotogramas clave para revisarlos uno por uno (bucle de autoevaluación visual: renderizar → ver fotogramas → mejorar → re-renderizar); la imagen de portada se genera directamente con snapshot, sin usar otra herramienta.

Comandos clave: vista previa con --background (recarga en caliente); renderizar 365s@1080p toma unos 9-10 minutos (modo de captura de 5 workers, sin GPU en la máquina local).

Cuándo consultar cada referencia

• Cualquier error/anomalía de renderizado → consultar primero references/pitfalls.md (buscar por síntoma, incluye la conclusión de un bug no resuelto en la cadena de transformación de la cámara)
• Escribir una nueva escena → references/scene-recipe.md (incluye plantilla JS para subtítulos frase por frase, modos de animación con marcado)
• Añadir locución → references/voice-pipeline.md
• Analizar videos de referencia (TikTok, etc.) → sección final de pitfalls.md "Descomposición cuantitativa de videos de referencia"
• Buscar bloques de efectos ya listos, skills del mismo ámbito, mejoras de locución, integración con Jianying, etc. → references/ecosystem.md (lista del ecosistema de código abierto, incluye réplica 1:1 con capture --video oficial)

Scripts incluidos

• scripts/inject_subtitles.py — Inyección masiva de subtítulos frase por frase (HTML/CSS/JS de una sola vez, evita errores manuales)
• scripts/gen_voice.py — Generación masiva de voz con edge-tts + adaptación automática de la velocidad a la duración de la escena (ejecutar con uv run)
• scripts/frame_audit.py — Auditoría de centroide de fotogramas renderizados (detección automática de desplazamientos/fotogramas en blanco, esencial para solucionar problemas de encuadre)

Tres reglas de oro

1. Antes de modificar cualquier archivo de escena, hacer grep: Studio puede insertar data-hf-id en los elementos, y el reemplazo de cadenas falla silenciosamente (pitfalls#2)
2. No tocar el esquema de cámara en el lienzo grande: La tubería de renderizado del motor provoca desajustes en cadenas continuas de transformación, verificado sin solución con múltiples enfoques (pitfalls#8); las animaciones deben hacerse solo a nivel de elementos
3. Primero la línea de tiempo narrativa: El tiempo de las frases de subtítulos + la duración de la locución determinan todo el ritmo de la animación; fijar la línea de tiempo antes de hacer la animación minimiza el retrabajo.