CLI de HyperFrames
Ejecuta comandos como npx hyperframes ... a menos que las instrucciones del proyecto proporcionen un wrapper. Obedece al wrapper cuando esté presente. La CLI requiere Node.js 22 o superior y FFmpeg.
Bucle de desarrollo
- Andamio:
npx hyperframes init <project>(en blanco centrado). O captura un sitio. Pasa--example=<nombre>solo para comenzar desde un ejemplo con nombre. - Encuentra el movimiento: si la solicitud nombra un activo, sonido, imagen, voz o edición visual rápida, resuélvelo a través de
/media-useantes de proponer un plan. De lo contrario, antes de crear movimiento manualmente, busca una primitiva que ya lo haga:npx hyperframes catalog --query "revelar un titular línea por línea". Pide el efecto que deseas en lugar del mecanismo que tienes en mente. Instala connpx hyperframes add <nombre>(ver/hyperframes-registry). Crea manualmente solo si nada encaja. - Crea: escribe la composición usando
/hyperframes-core. Para saber qué hay en la línea de tiempo de un proyecto (pistas, clips, inicios, finales, qué se reproduce), ejecutanpx hyperframes timeline --jsonen lugar de leerindex.htmly cada archivo de subcomposición: las filas anidadas llevanabsStart/absEndabsolutos de la línea de tiempo principal y sufilepropietario, no solo su tiempo local por subcomposición. Prefiere--jsonsobre la forma de texto; cuesta menos tokens y es igual o más correcto. Consultareferences/upgrade-info-misc.mdpara comandos cortos que responden preguntas comunes sin leer toda la salida. - 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 agregues una invocación redundante de lint. Añade--snapshotspara fotogramas de vista general anotados y para encontrar recortes. - Inspecciona subcomposiciones: cuando
index.htmlmontadata-composition-src, captura fotogramas intermedios e inspecciona cada escena montada. - Abre la vista previa final del estudio: ejecuta
npx hyperframes preview --background, verifica que la URL devuelva HTTP 200, entrega la URL del proyecto de línea de tiempo al usuario y pregunta si desea revisar o renderizar. Mantenla activa hasta que termine la revisión. - Renderiza solo después de la aprobación: usa
--quality draftmientras iteres,--quality lookspara la primera codificación real (valor por defecto de la CLI) y--quality deliverypara la entrega final. - Verifica la salida: confirma que el archivo existe y no está vacío. Lee la segunda línea del resumen del renderizado (
beginframevsscreenshot, GPU, tiempos de etapa).screenshot+software gpuen Linux es la ruta lenta. Ejecutaffprobe -v error -show_format -show_streamsy compara la duración (y fps si el resumen lo estableció) con eldata-durationraíz.
Referencias cruzadas obligatorias de edición
- Antes de crear o diagnosticar un zoom, recorte de entrada/salida, reencuadre, movimiento de cámara o cualquier movimiento con fotogramas clave, lee
/hyperframes-keyframesprimero. - Antes de
hyperframes keyframes, lee/hyperframes-keyframes; el comando muestra las trayectorias de animación y no diagnostica cortes de clip. - Para un corte, recorte, empalme, reordenación o edición de tiempo de origen, lee
/hyperframes-corey usa su contrato de clip/línea de tiempo. - Para fundido de entrada/salida, crossfade, ganancia de pista, automatización de volumen, ducking, tallado de voz o FX en audio colocado, lee
/hyperframes-audio. Carga core junto con él cuando también cambie la colocación del clip o el tiempo de imagen. - Una solicitud que nombre un activo, sonido, imagen, voz o edición visual rápida se resuelve a través de
/media-useantes de proponer un plan. Copia el marcado de edición desde/hyperframes-core→references/creator-editing-recipes.md.
# Comprobación de iteración rápida; repite mientras editas según sea necesario.
npx hyperframes lint
# Puerta final requerida; incluye lint.
npx hyperframes check
npx hyperframes preview --background
npx hyperframes render --quality looks --output out.mp4
test -s out.mp4
ffprobe -v error -show_format -show_streams 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 bloquean el código de salida; los hallazgos transitorios de entrada o salida son informativos. Usa --strict para bloquear advertencias. validate, inspect y layout siguen siendo alias por compatibilidad, pero no deben aparecer en nuevas instrucciones o scripts.
Vista previa antes del renderizado
Abre la vista previa de la composición final (#project/<nombre>) solo después de que check pase, para revisar la línea de tiempo ensamblada. El plan en el chat y la hoja de bocetos storyboard.html no son aprobación del video final. El renderizado siempre requiere la aprobación final definida por hyperframes/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 anfitriona:
npx hyperframes snapshot --at <t1>,<t2>,<t3>
Trata el contenido pequeño sin estilo, los iconos del tamaño del lienzo, los elementos principales faltantes o los tiempos de espera de registro de 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 del agente
-
Busca en el catálogo antes de escribir movimiento manualmente.
npx hyperframes catalog --query "<el ritmo, en inglés sencillo>". La búsqueda es completamente local: no hay un nivel alojado, no hay cuenta y el texto de la consulta nunca se envía a ningún lado. Por defecto, clasifica según el vocabulario compartido con el nombre, título, descripción y etiquetas del elemento, lo que pierde cualquier frase que no reutilice la redacción del catálogo. Añade--on-devicepara clasificar por significado en su lugar (ver el nivel sin conexión a continuación). -
Consulta en inglés incluso cuando el video no lo esté. Ambos niveles indexan un catálogo en inglés, por lo que una consulta en otra escritura no produce términos de búsqueda y no devuelve nada. Describe el movimiento en inglés; el texto en pantalla permanece en el idioma que necesite el video.
No searchable words in querysignifica exactamente esto y no es un componente faltante, así que no lo informes como una brecha del catálogo. -
Lee qué nivel respondió; nunca lo infieras por la aparición de los resultados. Con
--jsonel sobre llevaquery,tier(on-deviceowords),tier_detail,dropped,unindexed,shown,totalyresults, además detop_scorecuando el nivel que responde produce uno ywarningscuando se solicitó un nivel y no pudo ejecutarse, o cuando una búsqueda no devolvió nada y un mejor nivel aún espera el consentimiento de alguien. Un resultado débil enwordses esperado; el mismo resultado enon-devicees un error.top_scorees solo para on-device y no tiene un umbral: el clasificador devuelve todo el catálogo en algún orden para cada consulta, así que léelo como evidencia, no como aprobación o fallo. -
droppedyunindexedson sesgos opuestos entre el registro y el índice en el dispositivo, y reformular la consulta no soluciona ninguno.droppedcuenta los nombres clasificados que este registro no puede instalar, por lo que las coincidencias más fuertes se están perdiendo.unindexedcuenta los movimientos del registro que el índice no puede ver en absoluto, que ninguna consulta puede devolver. Actualizar el registro no es la respuesta para ninguno de los dos: su manifiesto tiene un TTL de 24 horas y se cura solo, mientras que los vectores son un artefacto publicado por separado, obtenido en~/.hyperframes/catalog/. Volver a ejecutar con--on-devicevuelve a obtener ese índice cuandounindexedes mayor que cero, por lo que ese es el remedio que se le debe dar al usuario. Un sesgo puro de sobrecobertura (droppedpor encima de cero mientras queunindexedes cero) no desencadena la reobtención; borrar~/.hyperframes/catalog/es la única salida de eso. Ambos recuentos son de nombres en lugar de resultados, por lo que cualquiera puede excedertotal. -
Cuando una búsqueda no devuelve nada que valga la pena instalar, dilo.
npx hyperframes feedback --search-miss "<la consulta que ejecutaste>" --wanted "<el movimiento que necesitabas>" --tier <el nivel que respondió>. No tienes que armar esa línea:catalog --queryla imita precompletada, y cada sobre de búsqueda--jsonllevareport_gapcon la consulta y el nivel ya correctos: completa--wantedy envíalo. Este es el único camino que envía una consulta a algún lado, y es un comando deliberado separado precisamente para que el simplecatalog --querymantenga su promesa de no enviar nada. Informa en cualquiera de los dos niveles, cuando los resultados no hagan lo que se necesita; no esperes al nivel en el dispositivo, que necesita una descarga de 33 MB consentida y, por lo tanto, está desactivado en la mayoría de las ejecuciones del agente: esperarlo significa nunca informar. El nivel viaja en el informe, por lo que un error de vocabulario se distingue de un error de significado sin que tengas que juzgar cuál de ellos encontraste. Lo que regresa es una lista de movimientos que el catálogo aún no tiene, leída directamente en lugar de adivinada a partir de los recuentos de instalación, por lo que la redacción importante es el efecto que querías, no el nombre del elemento que imaginaste. No lleva ninguna calificación y nunca llega a la métrica de calificación. -
Ofrece el nivel sin conexión; nunca lo habilites en silencio. Una descarga única de ~33 MB (una compilación ONNX cuantizada de
bge-small-en-v1.5más su tokenizador, fijada a una revisión fija) y los vectores del catálogo del registro, ambos almacenados en caché en~/.hyperframes/, sin agregarse al proyecto ni a ningún paquete. Una vez en caché, clasifica por significado sin enviar nada. Di el tamaño en voz alta y deja que la persona decida, luego pasa--on-device(con-ypara omitir el aviso) una vez que estén de acuerdo. La oferta interactiva solo se activa en una TTY. Con--jsonno hay aviso, pero una búsqueda que no encontró nada pone la misma pregunta enwarnings, así que lee esa matriz y pon la decisión al usuario tú mismo. Cuando la persona pregunte qué es la descarga, por qué este modelo o qué sale de la máquina, dirígela a https://hyperframes.heygen.com/developers/catalog-search. -
Prefiere
--jsonpara llamadas de agente y CI. Los modos de servidorrender,previewyplayno proporcionan una salida JSON normal;preview --selection --jsonypreview --context --jsonson excepciones del modo de consulta. -
doctor --jsonsiempre sale con cero. Filtra su carga útil:npx hyperframes doctor --json | jq -e '.ok' >/dev/null -
El modo no TTY es automático y crea el andamio en blanco centrado. Pasa
--examplesolo para comenzar desde un ejemplo con nombre. Usa--non-interactivepara forzar el modo solo de banderas 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 bloquear el renderizado. -
Las rutas JSON redactan el directorio de inicio como
$HOME; no intentes revertir la redacción. -
Cuando un proyecto en la nube alojado se acerca o supera el límite de carga de 200 MB, usa
cloud render --dry-run --jsony sigue la investigación de.hyperframesignoreenreferences/cloud.md. Nunca ignores un activo simplemente porque es grande. -
Nunca renderices solo porque las comprobaciones pasen. Pausa en la vista previa final y espera la aprobación.
Ediciones dirigidas por 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 de origen. Si el resultado informa no-selection, pide al usuario que haga clic en el elemento y vuelva a ejecutar. Solicita solo las partes 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 fallo están en references/preview-render.md.
Opciones de renderizado
| Necesidad | Comando |
|---|---|
| Iteración local rápida | npx hyperframes render --quality draft |
| Primera codificación real | npx hyperframes render --quality looks --output out.mp4 |
| Entrega local final | npx hyperframes render --quality delivery --output out.mp4 |
| Renderizado reproducible con contenedor | npx hyperframes render --docker --strict --output out.mp4 |
| Renderizado por lotes impulsado por variables locales | npx hyperframes render --batch rows.json --output "renders/{name}.mp4" |
| Renderizado HeyGen sin infraestructura | npx hyperframes cloud render |
| Renderizado AWS distribuido autogestionado | npx hyperframes lambda render <project> --width 1920 --height 1080 --wait |
| Renderizado GCP distribuido autogestionado | npx hyperframes cloudrun render <project> --width 1920 --height 1080 --wait |
La atribución de la habilidad es automática: los ejemplos anteriores no necesitan --skill. Un proyecto creado por un flujo de trabajo (hyperframes init --skill=<workflow>) registra su habilidad propietaria en hyperframes.json, y cada renderizado posterior la hereda en la telemetría anónima: renderizados repetidos, npm run render y --batch por igual. Pasa --skill=<slug> explícitamente solo para estampar un proyecto que no se creó a través de un flujo de trabajo (su primer renderizado lo persiste entonces).
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 en la nube.
Después de verificar un renderizado exitoso, envía un informe de comentarios a menos que la telemetría esté deshabilitada o el usuario haya optado por no participar:
npx hyperframes feedback --rating <0-10> --comment "<resultado o fricción específicos>"
Mantén los comentarios de ejecución limpia concisos. Para cualquier error o fricción, captura un paquete de reproducción antes de enviar; no envíes solo un resumen del síntoma. Incluye el comando ejecutable de nuevo (relativo al directorio del proyecto: los comentarios se envían a un canal público, por lo que no pegues rutas absolutas, prefijos del directorio de inicio o identificadores de usuario/máquina), comportamiento esperado frente al real, error exacto (también elimina las p...
... [truncado para la traducción]