¿Qué hace HyperFrames CLI?
Ejecuta 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 superior 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 de 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 generales anotados y encontrar recortes. - Inspecciona subcomposiciones: cuando
index.htmlmontadata-composition-src, captura fotogramas intermedios e inspecciona cada escena montada. - Abre la vista previa final del Studio: ejecuta
npx hyperframes preview, entrega la URL del proyecto de 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 iteraciones y alta calidad para la entrega final.
- Verifica la salida: confirma que el archivo existe, no está vacío y tiene una duración plausible.
# Iteración rápida de verificación; repite según sea necesario durante la autoría.
npx hyperframes lint
# Puerta final obligatoria; 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 ejecución, solicitudes fallidas, diseño, afirmaciones de *.motion.json y contraste WCAG. Los hallazgos persistentes condicionan el código de salida; los hallazgos transitorios de entrada o salida son informativos. Usa --strict para condicionar las 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 estructura. Abre ?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. Abre #project/<nombre>. |
El tablero temprano no es 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 visible intermedio para cada ranura anfitriona:
npx hyperframes snapshot --at <t1>,<t2>,<t3>
Trata el contenido pequeño sin estilo, los iconos de tamaño de lienzo, los elementos de héroe faltantes o los tiempos de espera de registro de línea de tiempo como defectos de montaje que bloquean el renderizado. Consulta hyperframes-core/references/sub-compositions.md para las correcciones correspondientes.
Convenciones de agente
-
Prefiere
--jsonpara llamadas de agente y CI. El modo servidorrender,previewyplayno proporcionan salida JSON ordinaria;preview --selection --jsonypreview --context --jsonson excepciones del modo de consulta. -
doctor --jsonsiempre sale con código 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 un 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 condicionar 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. Haz una pausa en la vista previa final y espera la aprobación.
Ediciones dirigidas por Studio
Cuando el usuario se refiere a "este elemento" o a la selección actual, consulta a Studio 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, pídele al usuario que haga clic en el elemento y vuelve a ejecutar. Solicita solo los segmentos 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 están 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 en la nube de HeyGen sin infraestructura | npx hyperframes cloud render |
| Renderizado distribuido AWS autogestionado | npx hyperframes lambda render <proyecto> --width 1920 --height 1080 --wait |
| Renderizado distribuido GCP autogestionado | npx hyperframes cloudrun render <proyecto> --width 1920 --height 1080 --wait |
Usa 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 en la 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 concisa la retroalimentación de ejecución limpia. 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, comportamiento esperado versus real, error exacto, si la salida se completó/recurrió/falló, solución alternativa y estado del proyecto de reproducción. Si el problema no se reprodujo de nuevo, dilo e incluye el último comando y registros fallidos. Usa --file-issue solo con consentimiento: publica una reproducción mínima en una URL pública. El formato de paquete requerido y la advertencia de privacidad están 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 lecturas de fondo opcionales. Antes de ejecutar un comando en la tabla, lee su fila correspondiente.
| Necesidad | Referencia |
|---|---|
init, capture, skills | references/init-and-scaffold.md |
lint, check, archivos laterales de movimiento, snapshot | references/lint-validate-inspect.md |
compare, grade-compare, render --batch basado en variables | references/compare-and-batch.md |
beats para la parrilla de ritmo del Studio de un proyecto existente | references/beats.md |
preview, play, render, publish, contexto de Studio, retroalimentación | references/preview-render.md |
doctor, gestión del navegador | references/doctor-browser.md |
auth, renderizado en la nube de HeyGen y variables de plantilla | references/cloud.md |
| Implementación y renderizado en AWS Lambda | references/lambda.md |
| Implementación y renderizado en Google Cloud Run | references/cloudrun.md |
info, upgrade, compositions, docs, benchmark, telemetría, preprocesamiento de medios | 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 eliminación de fondo, usa /media-use.
Los comandos especializados están documentados deliberadamente por sus flujos de trabajo propietarios:
npx hyperframes present <dir-proyecto> --port 3004 --no-open
npx hyperframes beats <dir-proyecto> --json
npx hyperframes keyframes <dir-proyecto> --json
present sirve una presentación navegable con sincronización de presentador y audiencia. beats es la utilidad independiente de parrilla de ritmo del Studio definida en references/beats.md. keyframes descubre diagnósticos de animación y trayectoria de movimiento seguros para la búsqueda.