hyperframes-cli

Instalación de complementos: Antes de ejecutar los comandos de configuración o frescura, sigue las reglas de ejecución de complementos cuando esta habilidad esté dentro de un complemento de HyperFrames. Las instalaciones independientes conservan las instrucciones de actualización a continuación.

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

1. Andamiaje: npx hyperframes init <proyecto> (en blanco centrado). O captura un sitio. Pasa --example=<nombre> solo para comenzar desde un ejemplo con nombre.
2. 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-use antes de proponer un plan. De lo contrario, antes de crear movimiento a mano, 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 con npx hyperframes add <nombre> (ver /hyperframes-registry). Crea a mano solo si nada encaja.
3. Crear: 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), ejecuta npx hyperframes timeline --json en lugar de leer index.html y cada archivo de subcomposición: las filas anidadas llevan absStart/absEnd absolutos de la línea de tiempo principal y su file propietario, no solo su tiempo local por subcomposición. Prefiere --json sobre la forma de texto; cuesta menos tokens para la misma o mejor corrección. Consulta references/upgrade-info-misc.md para obtener frases cortas que responden preguntas comunes sin leer toda la salida.
4. Obtén retroalimentación rápida mientras editas: ejecuta npx hyperframes lint después del primer pase de HTML y después de cambios estructurales.
5. Ejecuta la compuerta final: ejecuta npx hyperframes check; vuelve a ejecutar lint antes de abrir el navegador. No añadas una invocación redundante de lint independiente. Añade --snapshots para obtener fotogramas de visión general anotados y encontrar recortes.
6. Inspecciona subcomposiciones: cuando index.html monta data-composition-src, captura fotogramas intermedios e inspecciona cada escena montada.
7. Abre la vista previa final del Studio: 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. Mantenlo activo hasta que termine la revisión.
8. Renderiza solo después de la aprobación: usa --quality draft mientras iteras, --quality looks para la primera codificación real (el valor predeterminado de la CLI) y --quality delivery para la entrega final.
9. Verifica la salida: confirma que el archivo existe y no está vacío. Lee la segunda línea del resumen del render (beginframe vs screenshot, GPU, tiempos de etapa). screenshot + software gpu en Linux es la ruta lenta. ffprobe -v error -show_format -show_streams y compara la duración (y fps si el resumen lo estableció) con el data-duration raíz.

Historial del proyecto en tu turno

Cada escritura en el proyecto se guarda como una entrada que se puede deshacer. Úsalo solo en dos momentos, nunca en cada paso:

• Inicio de un turno: npx hyperframes history begin --who <tu-nombre> --label "<lo que vas a hacer>", luego npx hyperframes history --since mine --who <tu-nombre> para ver qué cambió la persona desde tu último turno. Construye sobre sus ediciones; nunca las sobrescribas.
• Una comprobación falló, o la persona dice que empeoró: npx hyperframes history undo --who <tu-nombre> deshace tu turno más reciente y deja las ediciones de la persona intactas. No edites manualmente hacia atrás. En caso de conflicto, sale con código 2 e imprime ambas opciones.

Termina cada turno con npx hyperframes history end, para que tus escrituras se lean como tuyas, no como "Cambiado fuera de la aplicación". Mientras un turno está abierto, cada escritura en el proyecto cuenta como tuya hasta que pasen 10 minutos sin una; después de eso, el turno termina solo.

Referencias cruzadas obligatorias de creación-edición

• Antes de crear o diagnosticar un zoom, entrada/salida, reencuadre, movimiento de cámara o cualquier movimiento con fotogramas clave, lee primero /hyperframes-keyframes.
• 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-core y usa su contrato de clip/línea de tiempo.
• Para fundido de entrada/salida, encadenado, ganancia de pista, automatización de volumen, ducking, grabación de voz o FX en audio colocado, lee /hyperframes-audio. Carga core junto con él cuando también cambien 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-use antes de proponer un plan. Copia el marcado de edición del creador desde /hyperframes-core → references/creator-editing-recipes.md.

# Comprobación rápida de iteración; repite mientras creas según sea necesario.
npx hyperframes lint

# Compuerta 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 en 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 de renderizar

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 todos los fallos 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 iconos del tamaño del lienzo, los elementos principales 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 del agente

• Busca en el catálogo antes de escribir movimiento a mano. npx hyperframes catalog --query "<el momento, en inglés simple>". La búsqueda es totalmente local: no hay un nivel alojado, ni 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 el vocabulario propio del catálogo. Añade --on-device para 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 otro script no produce términos buscables 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 query significa exactamente esto y no es un componente faltante, así que no lo informes como una brecha en el catálogo.

• Lee qué nivel respondió; nunca lo infieras de la aparición de resultados. Con --json, el sobre lleva query, tier (on-device o words), tier_detail, dropped, unindexed, shown, total y results, además de top_score cuando el nivel que responde lo produce y warnings cuando 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 en words es esperado; el mismo resultado en on-device es un error. top_score es solo para on-device y no tiene un umbral detrás: el clasificador devuelve todo el catálogo en algún orden para cada consulta, así que léelo como evidencia en lugar de como aprobación o fallo.

• dropped y unindexed son sesgos opuestos entre el registro y el índice del dispositivo, y reformular la consulta no soluciona ninguno. dropped cuenta nombres clasificados que este registro no puede instalar, por lo que las coincidencias más fuertes son las que se pierden. unindexed cuenta movimientos del registro que el índice no puede ver en absoluto, que ninguna consulta puede devolver nunca. Actualizar el registro no es la respuesta para ninguno de los dos: su manifiesto tiene un TTL de 24h y se auto-repara, mientras que los vectores son un artefacto publicado por separado que se obtiene en ~/.hyperframes/catalog/. Volver a ejecutar con --on-device recupera ese índice cuando unindexed es mayor que cero, por lo que ese es el remedio que se le da al usuario. Un sesgo puro de sobrecobertura (dropped mayor que cero mientras unindexed es cero) no activa la recuperación; borrar ~/.hyperframes/catalog/ es la única salida. Ambos recuentos son de nombres en lugar de resultados, por lo que cualquiera puede exceder total.

• 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 --query la imprime prellenada, y cada sobre de búsqueda --json la lleva como report_gap con la consulta y el nivel ya correctos — completa --wanted y 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 simple catalog --query cumpla su promesa de no enviar nada. Informa en cualquier nivel, siempre que los resultados no hagan lo que se necesita; no esperes al nivel en el dispositivo, que necesita una descarga consentida de 33 MB 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 sigue siendo distinguible de un error de significado sin que tengas que juzgar cuál obtuviste. Lo que se devuelve es una lista de movimientos que el catálogo aún no tiene, leída directamente en lugar de adivinada a partir de recuentos de instalación, por lo que la redacción que importa es el efecto que deseabas, no el nombre del elemento que imaginaste. No lleva calificación y nunca llega a la métrica de calificación.

• Ofrece el nivel sin conexión; nunca lo actives en silencio. Una descarga única de ~33 MB (una compilación ONNX cuantizada de bge-small-en-v1.5 más su tokenizador, fijada a una revisión fija) y los vectores del catálogo del registro, ambos almacenados en caché bajo ~/.hyperframes/, sin añadirse 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 -y para omitir el aviso) una vez que acepten. La oferta interactiva solo se activa en una TTY. Bajo --json no hay aviso, pero una búsqueda que no encontró nada pone la misma solicitud en warnings, así que lee ese arreglo 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 --json para llamadas de agente y CI. Los modos de servidor render, preview y play no proporcionan salida JSON ordinaria; preview --selection --json y preview --context --json son excepciones del modo de consulta.

• doctor --json siempre sale con cero. Filtra por su carga útil:

  npx hyperframes doctor --json | jq -e '.ok' >/dev/null
  

• El modo no TTY es automático y andamia el centro en blanco. Pasa --example solo para comenzar desde un ejemplo con nombre. Usa --non-interactive para forzar el modo solo de banderas en una TTY.

• Usa un HYPERFRAMES_RUN_ID para todos los comandos en el mismo bucle de verificación.

• Cuando el disco esté apretado, ejecuta npx hyperframes clean (--dry-run para listar primero); elimina lo que dejaron los renders muertos y las cachés inactivas que se reconstruyen solas, nunca las salidas, fuentes ni nada que use un render en ejecución. Escribe los fotogramas de control de calidad en un directorio temporal, no en el proyecto.

• Usa --strict, --strict-all y --strict-variables cuando las advertencias, variables o condiciones de CI correspondientes deban bloquear el render.

• Las rutas JSON redactan el directorio de inicio como $HOME; no intentes revertir la redacción.

• Cuando un proyecto alojado en la nube se acerca o supera el límite de carga de 200 MB, usa cloud render --dry-run --json y sigue la investigación de .hyperframesignore en references/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 Studio

Cuando el usuario se refiera a "este elemento" o la selección actual, consulta 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 de origen. Si el resultado informa no-selection, pide al usuario que haga clic en el elemento y vuelva 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 fallo viven 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
Render reproducible en contenedor	npx hyperframes render --docker --strict --output out.mp4
Render por lotes basado en variables locales	npx hyperframes render --batch rows.json --output "renders/{name}.mp4"
Render sin infraestructura alojado por HeyGen	npx hyperframes cloud render
Render distribuido AWS autogestionado	npx hyperframes l

…

[truncado para traducción]