motionhub-dev/motionhub

Hacer una película en un motion

Un motion es una apariencia para video narrado y explicativo, escrita: cómo se ve una película (fondo, color, tipografía) y cómo se mueve (cómo llegan, cambian y se van las cosas). No contiene ninguna película: no tiene historia, guion, escenas ni tiempos. Tú traes la historia; el motion decide cómo se ve y se mueve. El formato es SPEC.md (motion/0.5). Un motion se nombra por su id, el nombre de GitHub de su creador y su slug: @iamsuosi/lab-notebook. En motionhub cada id tiene ambos.

Un motion es un directorio:

Archivo	Lo que tomas de él
motion.json	Su alcance y slug (juntos su id), versión, nombre, descripción breve, autores y licencia; lang es el idioma de MOTION.md; fit es para qué sirve
MOTION.md	La apariencia en palabras. Siempre cinco secciones: Esencia, Color, Tipografía, Movimiento, Evitar. La definición del formato: https://github.com/motionhub-dev/motions/blob/main/SPEC.md#5-motionmd
tokens.json	Los valores exactos, como tokens de diseño W3C: color, font, y a menudo duration y cubicBezier
poster.jpg	Un fotograma de una película hecha con él
CREDITS.md	Cada fuente y recurso que necesita, con su licencia y origen
react/	Los componentes del motion, para cualquier motor React (sección 5): parts/, los archivos que importan en assets/, y una imagen de cada uno en previews/
<tool>/	Piezas listas para una herramienta específica. Ignora los directorios de herramientas que no estés usando

Un motion también puede ser un solo archivo: un MOTION.md que comienza con front matter que contiene su spec, name y tokens, en forma abreviada (floor: "#E8D5B7"). Dice lo mismo que diría tokens.json, y no tiene componentes, póster ni créditos.

1. Elegir el motion

• La persona nombró uno (un nombre, un id o un enlace motionhub.dev/m/<id>): úsalo.
• El proyecto tiene uno: MOTION.md en la raíz del proyecto, o bien motion/MOTION.md: úsalo y ve a la sección 3. Un proyecto puede contener varios en motions/: copias de motionhub en motions/@<scope>/<slug>/, y propios en motions/<name>/. Usa el que esté planeado para cada escena; si el plan no lo dice, pregunta cuál. Un proyecto también puede tener otros archivos de diseño, como frame.md o design.md. El motion decide cómo se ve y se mueve la película; sigue los otros para lo que no dice, y dile a la persona dónde discrepan.
• De lo contrario busca: npx @motionhub/cli search <palabras> (sin palabras los lista todos), o lee el índice, https://motionhub.dev/api/motions.json, cuyas filas tienen slug (el id), name, line, fit, catalogs, tags, lang, poster y package, con rutas relativas a https://motionhub.dev. Empieza por la forma de la película: catalogs nombra los catálogos en los que está un motion (explainers, data, stories, tutorials, breakdowns, y footage para uno dibujado sobre un video que la persona trae, así que ofrécelo solo cuando ella lo tenga; https://motionhub.dev/api/catalogs.json los lista). Luego compara el tema y el medio con fit, donde un motion lo tenga: fit.for dice para qué sirve y fit.not qué maneja mal. Un motion hecho para el tema de la película es mejor elección que uno que abarca muchos. Ofrece dos o tres con sus pósters, y deja que la persona elija. Elige tú mismo solo cuando te lo pidan.

2. Obtenerlo

Copia todo el motion en el proyecto, para que la película conserve la versión en la que se hizo:

npx @motionhub/cli get <id>            # en ./motions/<id>/, verificado contra el SHA-256 del índice, registrado en motions.lock.json
npx @motionhub/cli get                 # cada motion registrado en motions.lock.json, cuando el proyecto tiene uno y faltan

Una película puede hacerse en varios motions, uno para cada parte o cada tipo de escena: obtén cada uno y se colocan uno al lado del otro en ./motions/. Nunca modifiques una copia en ./motions/@<scope>/: para adaptar uno, cópialo a ./motions/<name>/ y cámbialo allí.

Sin Node: descarga https://motionhub.dev/m/<id>/<version>.tgz, verifícalo contra el package.sha256 de la fila, y descomprímelo. Sin shell, obtén https://motionhub.dev/m/<id>/MOTION.md, tokens.json, motion.json y CREDITS.md uno por uno.

3. Leerlo completo

Lee todo MOTION.md antes de dibujar nada, y tokens.json junto a él, o los tokens en su front matter. Si existe un MOTION.<lang>.md que coincida con el idioma en el que trabajas, puedes leerlo; no dice nada que MOTION.md no diga.

4. Hacer la película

• Los valores son exactos. Cada color, tipo de letra, duración y easing proviene de los tokens del motion, por nombre, en los términos de tu motor. Un token de fuente es una pila: usa sus tipos de letra en orden. Nunca aproximes un color a ojo.
• La esencia decide cada fotograma. Cada fotograma debe tener las características que nombra, y no debe derivar hacia lo que dice que el motion no es.
• Color y Tipografía son roles, no una paleta. Usa cada token solo para lo que dice su sección; lo que no dice que se coloree, se queda sin color.
• El movimiento es tiempo. Las cosas llegan, cambian y se van como dice, sobre la narración o la música como dice. Lo que dice que nunca se mueve, se queda quieto.
• Evitar es vinculante. Antes de terminar, revisa la película contra cada punto de Evitar.
• Nunca inventes un número. Cada figura, fecha y cuenta en la película proviene de la historia de la persona o de una fuente que te dieron. Si falta uno, deja un marcador visible y diles.
• La historia es tuya. Diseña cada escena para lo que esta película dice. No copies el tema, palabras o diseño del póster ni de ninguna muestra.
• Los componentes son un atajo. Si el motion tiene react/ o un directorio para la herramienta que estás usando, usa sus piezas (sección 5). Las palabras y los tokens aún gobiernan.

5. En tu motor

Cuando el motion tiene react/, usa sus componentes en lugar de dibujar la apariencia de nuevo. Son componentes React que importan solo @motionhub/runtime, y un binding les da su tiempo y tokens en tu motor:

Motor	Binding	Cómo
Remotion	npm i @motionhub/remotion	Envuelve la composición en <MotionProvider tokens={tokens}> (import tokens from '../motions/<id>/tokens.json'), añade <MotionFonts />, e importa componentes desde ../motions/<id>/react/parts/<file>.tsx. En varios motions, envuelve cada escena en <MotionScope tokens> de @motionhub/runtime
HyperFrames	npm i @motionhub/hyperframes, luego npx motionhub-hyperframes --out assets/motion (cada motion en ./motions/)	Carga assets/motion/motion.css y motion.js; Motion.mount(el, (t) => [...]) dibuja Motion.components desde tu línea de tiempo GSAP. En varios motions, Motions[<id>] es cada uno

Lee primero el README del binding. El meta de cada componente dice para qué sirve (purpose, line, fits) y qué significa cada parámetro, y react/previews/<file>.jpg lo muestra; lee el código de un componente solo cuando lo uses. Un parámetro de tipo progress va de 0 a 1: anímalo en tu motor, sobre las palabras que lo requieran. Un componente que dibuja en 3D importa three, que instalas. Caption (de @motionhub/runtime) dibuja una línea hablada en la piel de subtítulos del motion. Diseña cada escena para tu historia; los componentes son la apariencia, no la película.

De lo contrario, o para cualquier cosa que los componentes no dibujen: los tokens son valores DTCG, y npx @motionhub/cli tokens --out tokens.json los escribe desde un motion en un archivo, para un binding o un tema; convierte cada uno al de tu motor una vez, en un solo lugar (un módulo de tema), y úsalo por nombre en todas partes:

• Color: $value.hex.
• Fuente: $value es una pila: el CSS font-family son sus nombres en orden, cada uno entre comillas, el genérico al final.
• Duración: $value es {value, unit} en s o ms. Un motor que cuenta fotogramas multiplica los segundos por su velocidad de fotogramas y redondea.
• Easing (cubicBezier): $value es [x1, y1, x2, y2], la misma curva que CSS cubic-bezier(x1, y1, x2, y2). Un motor sin uno lo muestrea.

Motor	Tema	Tiempo
Remotion	useMotion() de @motionhub/remotion; de otro modo un theme.ts exportando los colores y pilas de fuentes. Carga las caras con @remotion/google-fonts o @remotion/fonts antes del primer fotograma	const {fps} = useVideoConfig(); una duración es Math.round(seconds * fps) fotogramas; interpolate(frame, [start, start + frames], [0, 1], {easing: Easing.bezier(x1, y1, x2, y2), extrapolateLeft: 'clamp', extrapolateRight: 'clamp'}). Prefiere interpolate con la curva del motion a spring(), cuyo rebasamiento el motion no pidió
HTML y CSS	Propiedades personalizadas en :root (--color-ink: #1B2A47)	transition o animation con la duración y cubic-bezier(...); la API de Animaciones Web acepta la misma cadena easing
GSAP	Las mismas propiedades personalizadas	duration en segundos; la curva mediante CustomEase.create('arrive', 'M0,0 C x1,y1 x2,y2 1,1')

Si el motion también tiene un directorio para tu motor (remotion/), sus piezas se añaden a los componentes: lee primero su README.

6. Fuentes y créditos

• Instala las caras que nombra CREDITS.md, desde sus fuentes y bajo sus licencias. Si una no está disponible, usa la cara abierta más cercana en el mismo rol y dile a la persona cuál.
• Los recursos nombrados en CREDITS.md se usan bajo sus licencias, con el crédito que piden.
• license.text cubre las palabras, tokens e imágenes del motion; CC-BY-4.0 y CC-BY-SA-4.0 piden crédito. Pon una línea como esta en la descripción o créditos finales de la película: Apariencia: Ink Scroll de SuoSi, motionhub.dev/m/@iamsuosi/ink-scroll, CC BY 4.0. license.code cubre el código en los directorios de herramientas.

7. Cambiarlo y compartir una apariencia propia

Adapta un motion libremente para una película, en una copia propia (./motions/<name>/). Una copia modificada ya no es esa versión: no la publiques bajo el mismo id y versión.

Para publicar una apariencia que la persona hizo (solo cuando te lo pidan):

1. npx @motionhub/cli init <slug> --github <su inicio de sesión de GitHub> escribe ./motions/<slug>/ con todos los archivos requeridos para completar, como el motion @<su login>/<slug> (pregúntales su inicio de sesión; con gh iniciado sesión, --github puede omitirse).
2. Toma la apariencia de su proyecto, nunca de la película: los colores y caras del tema en tokens.json (con las duraciones y curvas que el proyecto usa); MOTION.md en las cinco secciones, diciendo qué comparte cualquier película en esta apariencia y nada de la historia de esta película; CREDITS.md nombrando cada cara y recurso con su licencia; fit en motion.json, honestamente: general solo si abarcaría tres temas no relacionados, de lo contrario topic con el tema para el que está hecho, o overlay cuando se dibuja sobre su propio metraje.
3. poster.jpg: un fotograma de su película, un JPEG de 960 a 3840 píxeles de ancho y de máximo 500 KB (Remotion: npx remotion still <composition> poster.jpg --frame=<n> --image-format=jpeg).
4. Opcionalmente los componentes reutilizables, en react/parts/ como describe CONTRIBUTING.md: componentes React que importan solo react y @motionhub/runtime (en Remotion, useTime() y useVideoConfig() de este en lugar de los de Remotion), toman lo que cambia como props y no contienen nada de la historia de esta película.
5. Con su sí, npx @motionhub/cli share motions/<slug> --wait ejecuta las comprobaciones que su pull request ejecutará y lo sube a motionhub.dev. No se necesita git, gh ni token de GitHub. Dale a la persona el enlace y el código que imprime, exactamente como se imprime. Ellos abren el enlace, inician sesión con GitHub, revisan el motion, escriben el código y certifican el DCO, y motionhub abre el pull request bajo su nombre. El comando luego imprime la dirección del pull request: dásela también. Nunca escribas el código ni lo envíes en su nombre. Si prefieren usar su propio fork con gh, npx @motionhub/cli share motions/<slug> --pr lo hace.

Un motion en un solo archivo se publica de la misma manera, desde el paso 1. Luego npx @motionhub/cli tokens --out motions/<slug>/tokens.json escribe sus valores, su name y lang van a motion.json, y su cuerpo va a motions/<slug>/MOTION.md sin el front matter. El resto de motion.json, CREDITS.md y poster.jpg se completan como a continuación.

Para publicar una nueva versión de un motion que la persona publicó (solo cuando te lo pidan, como en "publica una nueva versión de @/ desde este proyecto"):

1. Ten el motion a mano: su propia copia en ./motions/<name>/, o npx @motionhub/cli get @<scope>/<slug> y copia ./motions/@<scope>/<slug>/ a ./motions/<slug>/ para cambiarlo allí.
2. Haz el cambio que quieran, desde su proyecto, manteniendo lo que MOTION.md dice que es la apariencia; una nueva apariencia es un nuevo motion.
3. Aumenta version en motion.json por encima de la publicada: el parche para una corrección, el menor para algo añadido (un componente, una sección), el mayor para un cambio que las películas ya hechas con él no sobrevivirían. Una versión publicada nunca cambia.
4. npx @motionhub/cli share <dir> --wait, como antes: ellos abren el enlace y envían; si su pull request para ello ya está abierto, la nueva versión se añade a él. Solo uno de los autores del motion puede cambiarlo; el envío de otro autor abre un pull request propio. --wait espera hasta 30 minutos.

Para cambiar un motion después de notas de revisión en su pull request, lee las notas (https://api.github.com/repos/motionhub-dev/motions/issues/<n>/comments y .../pulls/<n>/comments, no se necesita token), haz los cambios que piden, y envía de nuevo de la misma manera.

Para construir sobre el motion de otra persona, publica el tuyo bajo tu propio alcance, nombra el suyo en motion.json's basedOn ([{"id": "@iamsuosi/lab-notebook", "version": "1.0.2"}]) y di en CREDITS.md qué tomaste y cambiaste; solo sus autores cambian el original.

8. Verificar antes de entregar

Pon un fotograma de tu película junto a poster.jpg, si el motion tiene uno: el mismo fondo, los mismos colores en los mismos roles, las mismas caras. Luego lee Esencia y Evitar una vez más contra la película, y corrige lo que no se cumpla.