CLI de HyperFrames
Ejecuta los comandos como npx hyperframes ... a menos que las instrucciones del proyecto proporcionen un envoltorio. Obedece el envoltorio cuando esté presente. La CLI requiere Node.js 22 o más reciente y FFmpeg.
Ciclo de desarrollo
- Andamio:
npx hyperframes init <proyecto>o captura un sitio. En modo no TTY, pasa--non-interactive --example=<nombre>. - Autor: escribe la composición usando
/hyperframes-core. - Obtén retroalimentación rápida mientras editas: ejecuta
npx hyperframes lintdespués del primer pase HTML y después de cambios estructurales. - Ejecuta la puerta final: ejecuta
npx hyperframes check; vuelve a ejecutar lint antes de abrir el navegador. No antepongas una invocación redundante de lint independiente. Añade--snapshotspara fotogramas de visión general anotados y para encontrar recortes. - Inspecciona subcomposiciones: cuando
index.htmlmontadata-composition-src, captura instantáneas intermedias e inspecciona cada escena montada. - Abre la vista previa final del Estudio: ejecuta
npx hyperframes preview, pasa la URL del proyecto de la línea de tiempo al usuario y pregunta si desea revisar o renderizar. - Renderiza solo después de la aprobación: usa calidad de borrador para la iteración y alta calidad para la entrega.
- Verifica la salida: confirma que el archivo existe, no está vacío y tiene una duración plausible.
# Comprobación de iteración rápida; repite mientras sea necesario durante la autoría.
npx hyperframes lint
# Puerta final requerida; incluye lint.
npx hyperframes check
npx hyperframes preview
npx hyperframes render --quality high --output out.mp4
test -s out.mp4
ffprobe -v error -show_format out.mp4
check ejecuta lint primero, luego usa una sesión de navegador y un pase de búsqueda para auditar errores de tiempo de ejecución, solicitudes fallidas, diseño, aserciones de *.motion.json y contraste WCAG. Los hallazgos persistentes marcan el código de salida; los hallazgos transitorios de entrada o salida son informativos. Usa --strict para marcar advertencias. validate, inspect y layout siguen siendo alias por compatibilidad, pero no deben aparecer en nuevas instrucciones o scripts.
Dos superficies de vista previa diferentes
No confundas estos estados:
| Superficie | Cuándo puede abrirse | Propósito |
|---|---|---|
| Tablero de guion gráfico | Antes de las comprobaciones de composición, solo si storyboard: yes | Revisar tarjetas de plan y bocetos de wireframe. Abrir ?view=storyboard#project/<nombre>. |
| Vista previa de composición final | Después de que check pase | Revisar la línea de tiempo ensamblada antes de renderizar. Abrir #project/<nombre>. |
El tablero temprano no es una aprobación del video final. El renderizado siempre requiere la aprobación final definida por hyperframes-core/references/review-loop.md.
Prueba de humo de subcomposición
Las auditorías estáticas no pueden detectar todas las fallas de montaje. Cuando el proyecto usa subcomposiciones, captura al menos un punto medio visible para cada ranura de host:
npx hyperframes snapshot --at <t1>,<t2>,<t3>
Trata el contenido pequeño sin estilo, los íconos del tamaño del lienzo, los elementos de héroe faltantes o los tiempos de espera de registro en la línea de tiempo como defectos de montaje que bloquean el renderizado. Consulta hyperframes-core/references/sub-compositions.md para las correcciones correspondientes.
Convenciones para agentes
-
Prefiere
--jsonpara llamadas de agente y CI. El modo servidor derender,previewyplayno proporciona salida JSON ordinaria;preview --selection --jsonypreview --context --jsonson excepciones del modo de consulta. -
doctor --jsonsiempre sale con cero. Filtra en su carga útil:npx hyperframes doctor --json | jq -e '.ok' >/dev/null -
El modo no TTY es automático.
initrequiere--exampleallí; usa--non-interactivepara forzar un comportamiento determinista en una TTY. -
Usa un solo
HYPERFRAMES_RUN_IDpara todos los comandos en el mismo bucle de verificación. -
Usa
--strict,--strict-ally--strict-variablescuando las advertencias, variables o condiciones de CI correspondientes deban marcar el renderizado. -
Las rutas JSON redactan el directorio de inicio como
$HOME; no intentes revertir la redacción. -
Nunca renderices solo porque las comprobaciones pasen. Pausa en la vista previa final y espera la aprobación.
Ediciones dirigidas desde el Estudio
Cuando el usuario se refiera a "este elemento" o a la selección actual, consulta al Estudio en lugar de adivinar:
npx hyperframes preview --context --json --context-fields selection
Usa selection.target.hfId cuando esté disponible, de lo contrario su selector y archivo fuente. Si el resultado informa no-selection, pide al usuario que haga clic en el elemento y vuelve a ejecutar. Solicita solo las porciones de contexto que necesites; usa --context-detail full solo para estilos calculados o metadatos de texto editables. El comportamiento completo y los códigos de falla se encuentran en references/preview-render.md.
Opciones de renderizado
| Necesidad | Comando |
|---|---|
| Iteración local rápida | npx hyperframes render --quality draft |
| Entrega local final | npx hyperframes render --quality high --output out.mp4 |
| Renderizado reproducible en contenedor | npx hyperframes render --docker --strict --output out.mp4 |
| Renderizado por lotes basado en variables locales | npx hyperframes render --batch rows.json --output "renders/{name}.mp4" |
| Renderizado sin infraestructura alojado por HeyGen | npx hyperframes cloud render |
| Renderizado distribuido autogestionado en AWS | npx hyperframes lambda render <proyecto> --width 1920 --height 1080 --wait |
| Renderizado distribuido autogestionado en GCP | npx hyperframes cloudrun render <proyecto> --width 1920 --height 1080 --wait |
Usa el renderizado en la nube cuando el usuario quiera renderizado alojado sin Chrome local, FFmpeg o AWS. Usa Lambda solo cuando la propiedad de AWS sea un requisito. Usa Cloud Run solo cuando la propiedad de GCP sea un requisito. Lee la referencia correspondiente antes de ejecutar cualquier ruta de nube.
Después de verificar un renderizado exitoso, envía un informe de retroalimentación a menos que la telemetría esté deshabilitada o el usuario haya optado por no participar:
npx hyperframes feedback --rating <0-10> --comment "<resultado específico o fricción>"
Mantén la retroalimentación de ejecución limpia concisa. Para cualquier error o fricción, captura un paquete de reproducción antes de enviar; no envíes solo un resumen de síntomas. Incluye el comando reejecutable y el directorio de trabajo, el comportamiento esperado versus el real, el error exacto, si la salida se completó/falló/falló, la solución alternativa y el estado del proyecto de reproducción. Para una calificación ≤ 7 que describa un defecto visual (fotograma negro, parpadeo, salida corrupta, fotograma incorrecto, salida en blanco u otra anomalía visual), incluye también un bloque COMPOSITION_STRUCTURE: — una anatomía estructural que preserve la privacidad (censo de elementos + presencia de atributos + forma de la línea de tiempo) para que los mantenedores puedan buscar patrones entre familias de errores conocidas sin el ZIP de la composición. Los agentes completan esto automáticamente mediante el ayudante de censo de composición; el usuario humano no lo completa manualmente. Si el problema no se reprodujo de nuevo, indícalo y sigue incluyendo el último comando fallido y los registros. Usa --file-issue solo con consentimiento: publica una reproducción mínima en una URL pública. El formato requerido del paquete y la advertencia de privacidad se encuentran en references/preview-render.md.
Lee la referencia correspondiente antes de ejecutar un comando
Las siguientes referencias y habilidades propietarias son contratos de comando obligatorios, no lectura de fondo opcional. Antes de ejecutar un comando en la tabla, lee su fila correspondiente.
| Necesidad | Referencia |
|---|---|
init, capture, skills | references/init-and-scaffold.md |
lint, check, sidecars de movimiento, snapshot | references/lint-validate-inspect.md |
compare, grade-compare, render --batch basado en variables | references/compare-and-batch.md |
beats para la cuadrícula de ritmos del Estudio de un proyecto existente | references/beats.md |
preview, play, render, publish, contexto del Estudio, retroalimentación | references/preview-render.md |
doctor, gestión del navegador | references/doctor-browser.md |
auth, renderizado en la nube alojado por HeyGen y variables de plantilla | references/cloud.md |
| Despliegue y renderizado en AWS Lambda | references/lambda.md |
| Despliegue y renderizado en Google Cloud Run | references/cloudrun.md |
info, upgrade, compositions, docs, benchmark, telemetría, preprocesamiento multimedia | references/upgrade-info-misc.md |
Para variables de composición, lee también /hyperframes-core → references/variables-and-media.md. Para hyperframes add y hyperframes catalog, usa /hyperframes-registry. Antes de hyperframes present, lee /slideshow; antes de hyperframes keyframes, lee /hyperframes-keyframes. Para TTS, transcripción, subtítulos o decisiones de eliminación de fondo, usa /media-use.
Los comandos especializados están documentados deliberadamente por sus flujos de trabajo propietarios:
npx hyperframes present <directorio-del-proyecto> --port 3004 --no-open
npx hyperframes beats <directorio-del-proyecto> --json
npx hyperframes keyframes <directorio-del-proyecto> --json
present sirve una presentación navegable con sincronización del presentador y la audiencia. beats es la utilidad independiente de la cuadrícula de ritmos del Estudio definida en references/beats.md. keyframes expone diagnósticos de animación seguros para la búsqueda y de trayectoria de movimiento.