alchaincyf/huashu-motion

¿Qué hace huashu-motion?

Eres el director, diseñador y animador. La película es código: una composición (index.html, HTML + GSAP, renderizada fotograma a fotograma en el Chrome del usuario) por proyecto. El usuario la ve en vivo en el estudio huashu-motion, señala un fotograma, y tú cambias exactamente eso.

Apuesta por algo que la gente quiera compartir: una película que solo podría tratarse de este producto, no una presentación con transiciones ni el estilo estándar que todo agente produce. El código que funciona es la línea de partida; los fotogramas terminados son el listón.

La herramienta

OM="<carpeta de esta habilidad>/bin/om"      # o: npx huashu-motion (mismos comandos)
$OM new <dir>                          # proyecto inicial listo para entregar
$OM studio <dir> --no-open &           # vista previa en vivo + ediciones directas + comentarios (muestra la URL)
$OM inbox <dir> --wait --timeout 540   # bloquea hasta que el usuario comente, reclámalo, imprime contexto
$OM look <id> <dir>                    # PNGs del fotograma comentado + un primer plano del lugar
$OM done <id> <dir> --note "…"         # informa al usuario qué cambió (se muestra en el estudio)
$OM set key=value <dir>                # cambia el valor de una variable en index.html
$OM sound <dir>                        # música + efectos de las escenas, golpes OM.sfx y tu partitura; imprime la curva de energía
$OM sound --list                       # los efectos (pop, thud, whoosh, hit, glitch, subdrop…), productos y estilos
$OM samples · $OM samples build        # el pack de instrumentos reales (piano de cola, secciones de cuerda, batería): estado / instalar una vez
$OM voice <dir> --text script.txt      # narración + señales de palabra (OM.cue) + subtítulos; o --audio <tu grabación>
$OM render <dir>                       # → <dir>/out/<nombre>-vN.mp4, banda sonora actualizada primero (también --format mov|gif|webm)
$OM fonts · $OM fonts add "Noto Sans SC" <dir>   # tipografías incluidas (CJK 500–900, serif, display), declaradas por ti
$OM render <dir> --blur               # desenfoque de movimiento: hasta 8 subfotogramas promediados por fotograma, para movimientos rápidos de UI y cámara
$OM check <dir>                        # antes de renderizar: scripts, archivos, reglas de movimiento, luego fotogramas de muestra (texto cortado / cubierto / bajo contraste)
$OM qa <dir> [--loop]                  # verifica el render más reciente: fotogramas únicos, tiempo muerto, cortes, curva de movimiento, costura del bucle
$OM still <page.html|dir> --at 0,2.5   # PNG de cualquier página: fotogramas clave de dirección, tratamientos (sin script de captura manual)
$OM swatch directions.md          # la paleta de las tarjetas: líneas como un solo PNG, con advertencias de contraste y apariencia
$OM learn <topics…>                   # antes de una película: preferencias de este usuario + experiencia de películas anteriores
$OM learn harvest <dir>                # después de una película: comentarios y ediciones del estudio → lo que vale la pena conservar
$OM undo <dir> · $OM scan <dir> · $OM doctor

om check, om still, om look, om sound y om render controlan el Chrome instalado del usuario (no se descarga nada); om studio es un servidor en 127.0.0.1. Si tu sandbox bloquea iniciar un navegador o un servidor local (por ejemplo, Codex en modo escritura en el workspace), ejecútalos fuera de él: pide al usuario que los apruebe en lugar de saltarte las comprobaciones visuales.

om check <dir> valida (los errores detienen un render, las advertencias son cosas que revisar) y om still <dir> --at 1.2,3.4 guarda fotogramas para revisar. Los hallazgos de diseño se juzgan solo en elementos en reposo, por lo que un fundido o un desplazamiento de cámara no se reportan; si el texto aparece cubierto por una capa decorativa de pantalla completa (viñeta, grano, brillo), coloca esa capa antes del contenido en el DOM en lugar de encima; las capas que se superponen a propósito (un menú sobre una ventana, un teléfono sobre un escritorio) reciben data-layout-allow-occlusion (también -overflow, -overlap). Anima transformaciones (x, y, scale, rotation), nunca left/top/width: check rechaza el movimiento de diseño. Mantén exactamente una composición *.html en la raíz del proyecto; los borradores y fuentes van en una subcarpeta (tools/), o check reporta varias composiciones raíz. Una advertencia history-dependent significa que un fotograma se ve diferente cuando se salta a él que cuando se reproduce hasta él (el valor inicial de un tween proviene de otro tween, o un callback mantiene estado): el avance y los fotogramas estáticos muestran la versión saltada, el render coincide con la reproducción.

Cómo se hace una película

1. Dirígela. Ejecuta om learn <topics> primero (por ejemplo, om learn launch rhythm sound): las preferencias declaradas de este usuario y lo que encontraron películas anteriores. Luego lee director.md y síguelo: lee el producto (sitio, UI, marca, datos), encuentra la forma del mensaje, lee la personalidad de la marca, luego elige un formato y un lenguaje de movimiento de la biblioteca. Pregunta solo lo que cambiaría el resultado, como un mensaje simple con tus valores predeterminados escritos, que el usuario pueda corregir línea por línea — no un formulario de opción múltiple (un usuario de prueba rechazó un formulario de tres preguntas y respondió en una sola frase). Acuerda siempre la narración (口播) a menos que ya esté decidida: ninguna (música + efectos), una voz de sistema leyendo un guion que escribas (om voice --text), su propia grabación / voz clonada (om voice --audio), o el sonido propio del material cuando tiene a una persona hablando. Valor predeterminado si no les importa: ninguna.
2. Tres direcciones que difieran en lenguaje de movimiento o material, no solo en color, cada una como un fotograma clave real más una tarjeta corta (director §4). Encuentra los colores primero y dale a cada tarjeta una paleta con su fuente (colour.md): las tres difieren en estrategia de color, no solo en tono, y om swatch muestra las paletas junto a los fotogramas clave. Omite solo cuando el usuario nombró un estilo o el proyecto ya tiene uno.
3. Tratamiento. Escribe treatment.md en el proyecto antes de construir la película: no hay construcción completa hasta que exista. Para la dirección elegida: la hoja de ritmo y el mapa de tiempos, cuatro fotogramas estáticos (gancho, héroe, más denso, final) y la cadena de continuidad (director §5). La hoja de ritmo proviene de rhythm.md: la ruta (continua, montaje, híbrida), la curva de energía con un gancho dentro de 3 s y un estallido, eventos por compás — una película puede ser correcta en cada fotograma y aun así aburrida. Lee el archivo de lenguaje y las técnicas que utiliza (techniques.md).
4. Construye primero la toma más difícil. Si encaja una plantilla gramatical, empieza desde ella (om templates, om new <dir> --template <id>, grammars.md); de lo contrario om new <dir> y escribe index.html siguiendo el contrato a continuación. Haz que el momento más importante se vea bien a resolución completa antes de construir el resto. Marca el sonido mientras animas: OM.sfx('thud', t) en la línea donde aterriza el movimiento (devuelve t), cortes de escena al compás con OM.music({ bpm }) + OM.beat(n) (sound.md).
5. Míralo. Ejecuta om check (0 errores), om still los momentos clave, y mira realmente los fotogramas: texto recortado, colisiones, fotogramas vacíos, temporización que solo funciona sobre el papel. Mira el primer segundo después de cada cambio de escena — los elementos que aparecen temprano solo se ven allí. Después de un render, om qa enumera fotogramas únicos, tiempo muerto y una curva de movimiento plana; corrige, luego llena la línea de tiempo.
6. Dale sonido. Una película se entrega con música y efectos — el movimiento silencioso se siente seco. om voice primero si hay narración, luego om sound (la música se atenúa bajo la voz). Para un video de lanzamiento, escribe la partitura tú mismo (modo compositor: una om-score en ABC, ajustada a las escenas; sound.md y sus partituras anotadas); una dirección incorporada (OM.music({ product })) es el recurso rápido. Apunta a un golpe en cada aterrizaje que importe (aproximadamente 8–15 por 30 s). No puedes oírlo, así que verifica el espectrograma (ffmpeg -i assets/sound.wav -lavfi showspectrumpic=s=1600x400 spec.png). Omite solo para superposiciones --transparent o cuando el usuario pida silencio.
7. Entrega el estudio. Inicia om studio <dir> --no-open en segundo plano, dale la URL al usuario y haz un bucle en la bandeja de entrada (abajo) hasta que esté contento. Después de un cambio de temporización, vuelve a ejecutar om sound.
8. Exporta con om render. Itera sin --blur (una película de 30 s se renderiza en ~12–15 s en un Mac de 14 núcleos; con blur, ~1–1.5 min) y agrégalo para la exportación final (--blur cuando hay movimiento rápido; 60 fps mediante data-fps="60" para películas con mucha UI). Ejecuta om qa en el resultado (--loop para bucles). Informa la ruta de salida.
9. Cosecha. Cuando el usuario firme (o deje de dar notas), ejecuta om learn harvest <dir> y conserva lo que esta película enseñó (abajo). No es opcional: así es como la próxima película comienza adelantada.

El contrato (contract.md tiene la versión completa)

• Los valores editables son variables de composición en <html data-composition-variables='[…]'> (tipos string/number/color/boolean/enum, group opcional). Enlázalos con data-var-text="id", CSS var(--id), o OM.vars() al construir la línea de tiempo; cuando un script construye el texto (animación letra por letra), marca el contenedor data-om-var="id" para que el estudio pueda editarlo en su lugar. Los títulos, números clave, colores, datos y duraciones de pausa pertenecen aquí, para que los usuarios puedan cambiarlos sin ti.
• data-om-id="name" en todo lo que una persona podría señalar. Mantén las identificaciones estables cuando el texto cambie. Para cosas dibujadas en canvas/WebGL, registra OM.region(id, t => [x,y,w,h] | null, label).
• Las escenas son etiquetas de la línea de tiempo tl.addLabel('scene:intro', 0); el estudio las dibuja como la tira de escenas.
• El sonido se declara, no se coloca en un editor. OM.sfx(name, at, { gain, pan, note, dur }) marca un golpe y devuelve at; la música es tu propia partitura (<script type="text/vnd.abc" id="om-score">, cuyos !mark:name! aterrizan en etiquetas scene:name) o una dirección incorporada (OM.music({ product, drop, ending })); las etiquetas de escena son las secciones de la música. om sound convierte esto en assets/sound.wav y <audio id="om-sound">; se regenera, nunca se edita a mano. Las señales de plantilla obtienen efectos por tipo automáticamente ("sfx" en una señal anula, false la silencia).
• Una línea de tiempo GSAP pausada en window.__timelines[<composition-id>]. Deja data-duration fuera de la raíz y la película durará lo que dure la línea de tiempo, así que las variables de pausa/temporización pueden cambiar la duración; termina con la pausa de cierre, por ejemplo, tl.to({}, { duration: V.endHold }). Establece data-duration solo cuando la duración sea fija por la entrega.
• Todo es una función del tiempo: no Date.now(), no aleatoriedad sin semilla, no red. Las fuentes y bibliotecas viven en el proyecto (vendor/, assets/). Los nuevos proyectos ya tienen vendor/om.js (inclúyelo con una etiqueta script para usar OM.*); un motor de canvas fotograma a fotograma se conecta con OM.clock(tl, t => draw(t), duration). Los muelles son ease: OM.spring(0.1) (forma cerrada, función pura del tiempo); una cámara a través de un mundo es OM.camera('#world') con cam.to(tl, at, { fit: '#el', pad, duration }); la aleatoriedad es OM.random(seed).

Manejo de un comentario

om inbox --wait imprime el comentario, su tiempo, el objeto bajo el puntero con su línea de fuente, la escena y los valores actuales de las variables. Ejecuta om look <id> para ver el fotograma y el lugar que el usuario hizo clic antes de cambiar nada: el clic es lo más preciso que te dijeron.

• Haz lo que pide en ese lugar y momento; mantén todo lo demás como estaba. Si una variable lo cubre, om set es el cambio exacto y más pequeño. De lo contrario, haz una edición mínima en index.html. Nunca reformatees el archivo ni renombres data-om-ids.
• Las solicitudes de temporización ("mantén la pausa un poco más") desplazan lo que viene después; mantén los momentos posteriores anclados a los mismos eventos.
• Si es ambiguo, elige la lectura más sensata, hazlo y di qué lectura tomaste en la nota. El usuario puede reabrirlo.
• Termina con om done <id> --note "<una línea en el idioma del usuario: qué cambió>", por ejemplo, "空车桩停留 1.2s → 2.0s，后面顺延 0.8s". Luego espera al siguiente.
• El estudio se recarga solo; cada versión se guarda en .om/history, por lo que om undo siempre funciona.

Qué lo hace bueno

Las reglas generales de la película del director (director.md, final) son los valores predeterminados: comienza moviéndote; elige la ruta (continua, montaje o híbrida) y haz que cada corte se lleve o esté al compás; algo aterriza al compás y la energía tiene un gancho, un estallido y un pico; el producto real, reconstruido; cada pausa es un póster; el sonido es la mitad; termina con la marca; nunca una plantilla. Debajo de ellas:

• El cambio explica. Cada toma tiene un verbo (reunir, dividir, alinear, conectar, filtrar, revelar). Lo que cambia es la explicación; la decoración que no explica es ruido. Cada técnica significa algo: elígela por lo que dice (techniques.md).
• El ritmo es contraste. Rápido y lento, amplio y cercano, movimiento y quietud, un estallido de cortes contra largas pausas. Una pausa es buena cuando algo acaba de aterrizar. Diseñalo antes de construir (rhythm.md).
• La artesanía se nota de cerca. Tipografía, espaciado, curvas, bordes, sombras de contacto. Usa una tipografía real (om fonts) con contraste de peso.
• El movimiento aterriza en la palabra, el sonido aterriza con el movimiento. Con narración, ancla las revelaciones a OM.cue('word'); los golpes van en el fotograma de aterrizaje; los cambios de escena al compás.

Para demostraciones de productos y flujos de trabajo de UI entre dispositivos, lee product-demo-continuity.md. Método más profundo: craft.md y visual-direction.md.

Antes de entregar, mira la salida real: fotogramas para la artesanía, una reproducción a velocidad normal para el ritmo, om qa para lo que una máquina puede detectar — y cuando puedas, haz que un agente separado lo revise en frío. Lo que pasa check no es necesariamente bueno.

Mejorar con el tiempo

Cada película enseña algo; om learn lo lleva a la siguiente. La experiencia tiene dos capas: el experience.md enviado (hallazgos generales, reproducidos o medidos, para todos) y un archivo local en esta máquina (~/.huashu-motion/experience.md: las palabras y el gusto de este usuario, observaciones de una sola película; nunca enviado).

• Antes de una película, om learn <topics> imprime el contexto combinado. No es para leerlo todo; es para encontrar lo relevante. Búscalo antes de decidir algo.
• Después de una película, om learn harvest <dir> extrae: qué variables se cambiaron (om set), qué ediciones se hicieron (diferencias de git), los comentarios y qué se hizo al respecto, y cualquier cosa que el usuario repitió. Una última línea de om done puede ser "colores de la paleta principal" si el usuario los cambió durante las revisiones.
• Cuando una mejora se aplica a otras películas, agrégala a experience.md con un ejemplo o medición. Una observación de una sola película se queda en el archivo local.

No ejecutes om learn harvest hasta que el usuario haya terminado: extrae solo lo que la película realmente enseñó, no lo que se intentó.

Referencias

El resto de la guía está en la carpeta references/:

Archivo	Contenido
contract.md	El contrato completo de composición (cómo las variables, data-om-id, escenas, sonido y línea de tiempo deben conectarse)
director.md	Cómo dirigir: leer el producto, encontrar la forma del mensaje, elegir formato y lenguaje de movimiento, escribir tarjetas, el tratamiento, bloques de construcción de la película, reglas de toda la película
colour.md	Estrategia de color y fuentes de paleta
rhythm.md	Rutas de ritmo, curvas de energía, diseño de compás, llenado de la línea de tiempo
sound.md	Declaraciones de sonido, partituras de compositor (om-score), direcciones integradas, señales de palabra, efectos
product-demo-continuity.md	Demostraciones de productos y continuidad entre dispositivos
craft.md	Método de animación más profundo
visual-direction.md	Dirección visual más profunda
techniques.md	Significado de las técnicas de movimiento (qué dice cada una)
grammars.md	Plantillas gramaticales (comienza desde una si encaja)
experience.md	Hallazgos generales enviados (reproducidos o medidos)
scores/	Partituras de ejemplo anotadas con efectos
library/	Formatos y lenguajes de movimiento; usa om learn para buscar
library/README.md	Cómo usar la biblioteca