Instalación del plugin: Antes de los comandos de configuración o actualización, sigue las reglas de ejecución del plugin cuando este skill esté dentro de un plugin de HyperFrames. Las instalaciones independientes conservan las instrucciones de actualización a continuación.
CLI de HyperFrames
Ejecuta los comandos como npx hyperframes ... a menos que las instrucciones del proyecto proporcionen un envoltorio. Obedece al envoltorio cuando esté presente. La CLI requiere Node.js 22 o superior y FFmpeg.
Bucle de desarrollo
- Andamio:
npx hyperframes init <proyecto>(en blanco centrado). O captura un sitio. Pasa--example=<nombre>solo para empezar 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 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 connpx hyperframes add <nombre>(ver/hyperframes-registry). Crea a mano solo si nada se ajusta. - Autoría: escribe la composición usando
/hyperframes-core. Para saber qué hay en la línea de tiempo de un proyecto (pistas, clips, inicios, fines, qué se reproduce), ejecutanpx hyperframes timeline --jsonen lugar de leerindex.htmly cada archivo de sub-composición: las filas anidadas llevanabsStart/absEndabsolutos de la línea de tiempo principal y sufilepropietario, no solo su tiempo local por sub-composición. Prefiere--jsonsobre la forma de texto; cuesta menos tokens para la misma o mejor corrección. Consultareferences/upgrade-info-misc.mdpara consultas de una línea que responden preguntas comunes sin leer toda la salida. - Obtén retroalimentación rápida mientras editas: ejecuta
npx hyperframes lintdespués de la primera pasada de HTML y después de cambios estructurales. - Ejecuta la compuerta 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 resumen anotados y encontrar recortes. - Inspecciona sub-composiciones: cuando
index.htmlmontedata-composition-src, captura fotogramas intermedios e inspecciona cada escena montada. - 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 la línea de tiempo al usuario y pregunta si quiere revisar o renderizar. Mantenlo activo hasta que termine la revisión. - Renderiza solo después de la aprobación: usa
--quality draftmientras iteras,--quality lookspara la primera codificación real (el valor predeterminado de la CLI) y--quality deliverypara la entrega final. - Entrega el proyecto a la aplicación de escritorio (cuando esté disponible): cuando la línea de Framey del render termine en
hyperframes open …, ofrecenpx hyperframes open [dir]. Abre el proyecto en la aplicación de escritorio de HyperFrames y lo añade a Inicio; bajo Claude Code, Codex o Grok, su chat retoma esta conversación. Sin la aplicación, sale con código 1 e imprime el enlace de descarga.--jsonpara agentes. Cuandoopendiga que ejecutescatch-upuna vez que la persona haya vuelto, o cualquier comando termine con una línea que lo nombre, ejecutanpx hyperframes catch-up [dir]antes de tu siguiente cambio: lista lo que se pidió y cambió en la aplicación desde la entrega. Una CLI antigua no tienecatch-up. - Verifica la salida: confirma que el archivo existe y no está vacío. Lee la segunda línea del resumen del render (
beginframevsscreenshot, GPU, tiempos de etapa).screenshot+software gpuen Linux es la ruta lenta.ffprobe -v error -show_format -show_streamsy compara la duración (y fps si el resumen lo estableció) condata-durationraí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 estás a punto de hacer>", luegonpx hyperframes history --since mine --who <tu-nombre>para ver lo que la persona cambió 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 a mano 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 ha terminado solo.
Referencias cruzadas obligatorias de creación-edición
- Antes de crear o diagnosticar un zoom, entrada/salida de encuadre, reencuadre, movimiento de cámara o cualquier movimiento de fotograma 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 clips. - 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, encadenado, ganancia de pista, automatización de volumen, ducking, tallado de voz en off o FX en audio colocado, lee
/hyperframes-audio. Carga core junto con él cuando la colocación del clip o el tiempo de la imagen también cambien. - Una solicitud que nombre un activo, sonido, imagen, voz o edición visual rápida se resuelve a través de
/media-useantes de que se proponga un plan. Copia el marcado de creación-edición de/hyperframes-core→references/creator-editing-recipes.md.
# Iteración rápida de comprobació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 una pasada de búsqueda para auditar errores 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 render
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 sub-composición
Las auditorías estáticas no pueden detectar todos los fallos de montaje. Cuando el proyecto use sub-composiciones, 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 de tamaño de 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 render. Consulta hyperframes-core/references/sub-compositions.md para las correcciones correspondientes.
Convenciones para agentes
-
Busca en el catálogo antes de escribir movimiento a mano.
npx hyperframes catalog --query "<el ritmo, en inglés sencillo>". La búsqueda es completamente local: no hay un nivel alojado, ninguna cuenta y el texto de la consulta nunca se envía a ningún sitio. 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 propio catálogo. Añade--on-devicepara clasificar por significado en su lugar (ver el nivel offline 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 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 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 resultados. Con
--json, el 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 nivel mejor aún está esperando el consentimiento de alguien. Un resultado débil enwordses esperado; el mismo resultado enon-devicees un error.top_scorees solo del nivel on-device y no tiene un umbral detrás: el clasificador devuelve el catálogo completo en algún orden para cada consulta, así que léelo como evidencia en lugar de como aprobación o rechazo. -
droppedyunindexedson sesgos opuestos entre el registro y el índice on-device, 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 son las que se pierden.unindexedcuenta los 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 24 horas y se cura solo, mientras que los vectores son un artefacto publicado por separado que se descarga 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 debes dar al usuario. Un sesgo puro de sobre-cobertura (droppedmayor que cero mientrasunindexedes cero) no desencadena la recuperación; borrar~/.hyperframes/catalog/es la única salida de ese caso. Ambos recuentos son de nombres en lugar de resultados, por lo que cualquiera de ellos puede excedertotal. -
Cuando una búsqueda vuelve sin 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 imprime precompletada, y cada sobre de búsqueda--jsonla lleva comoreport_gapcon la consulta y el nivel ya correctos — completa--wantedy envíala. Este es el único camino que envía una consulta a algún lugar, y es un comando deliberado separado precisamente para que el simplecatalog --querymantenga su promesa de no enviar nada. Informa en cualquier nivel, siempre que los resultados no hagan lo que necesitas; no esperes al nivel on-device, que necesita una descarga consentida de ~33 MB y, por lo tanto, está desactivado en la mayoría de las ejecuciones de agentes: esperarlo significa no informar nunca. El nivel viaja en el informe, por lo que un fallo de vocabulario se distingue de un fallo de significado sin que tengas que juzgar cuál de los dos encontraste. Lo que vuelve 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 que importa es el efecto que deseabas, 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 offline; nunca lo actives 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é 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-ypara omitir la solicitud) una vez que acepte. La oferta interactiva solo se activa en una TTY. Bajo--jsonno hay solicitud, pero una búsqueda que no encontró nada pone la misma pregunta enwarnings, así que lee ese array 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.render,previewyplayen modo servidor no proporcionan salida JSON ordinaria;preview --selection --jsonypreview --context --jsonson excepciones en modo consulta. -
doctor --jsonsiempre sale con cero. Condiciónalo en 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 empezar 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. -
Cuando el disco esté ajustado, ejecuta
npx hyperframes clean(--dry-runpara 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 un render en ejecución use. Escribe los fotogramas de control de calidad en un directorio temporal, no en el proyecto. -
Usa
--strict,--strict-ally--strict-variablescuando las advertencias, variables o condiciones de CI correspondientes deban bloquear el render. -
Las rutas JSON redactan el directorio principal como
$HOME; no intentes revertir la redacción. -
Cuando un proyecto de nube alojada se acerque o supere 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 solo porque sea 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 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, 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 editable. El comportamiento completo y los códigos de error se encuentran en references/preview-render.md.
Opciones de render
| Necesidad | Comando |
|---|---|
| Iteración local rápida | npx hyperframes render --quality draft |
| Primera codificación real | npx hyperframes render --quality looks |
| Entrega final | npx hyperframes render --quality delivery |
| Render por lotes (todos los proyectos) | npx hyperframes render --batch |
| Render en la nube | npx hyperframes cloud render |
| Render en AWS Lambda | npx hyperframes lambda render |
| Render en Google Cloud Run | npx hyperframes cloudrun render |
| Ver salida con FFprobe | ffprobe -v error -show_format -show_streams out.mp4 |
Comandos de diagnóstico
# Diagnóstico general del proyecto
npx hyperframes doctor
# Información del proyecto
npx hyperframes info
# Estadísticas de rendimiento
npx hyperframes benchmark
# Telemetría del render (si está habilitada)
npx hyperframes telemetry
Gestión de activos y medios
# Añadir un activo multimedia
npx hyperframes add <ruta-al-activo>
# Capturar una imagen de un sitio web
npx hyperframes capture <url>
# Transcribir audio
npx hyperframes transcribe <archivo-de-audio>
# Texto a voz
npx hyperframes tts --text "<texto>" --voice <voz>
# Eliminar fondo de una imagen/video
npx hyperframes remove-background <archivo>
Autenticación y publicación
# Autenticarse en HyperFrames cloud
npx hyperframes auth login
# Publicar una composición
npx hyperframes publish
Referencias y notas adicionales
- Para obtener una lista completa de comandos y opciones, ejecuta
npx hyperframes --help. - Los archivos de configuración y las dependencias del proyecto se gestionan automáticamente; consulta
hyperframes/references/para documentación detallada sobre temas específicos. - El historial de cambios del proyecto se almacena localmente y puede gestionarse con
history.