motionhub-dev/motionhub

Réaliser un film dans un motion

Un motion est un look pour une vidéo narrative et explicative, décrit par écrit : comment un film a l'air (arrière-plan, couleur, typographie) et comment il bouge (comment les éléments arrivent, changent et partent). Il ne contient aucun film : ni histoire, script, scènes ou minutage. Vous apportez l'histoire ; le motion décide de son apparence et de son mouvement. Le format est SPEC.md (motion/0.5). Un motion est identifié par son id, le nom GitHub de son créateur et son slug : @iamsuosi/lab-notebook. Sur motionhub, chaque id possède les deux.

Un motion est un répertoire :

Fichier	Ce que vous en tirez
motion.json	Sa portée et son slug (ensemble son id), version, nom, ligne, auteurs et licence ; lang est la langue de MOTION.md ; fit indique à quoi il est destiné
MOTION.md	Le look en mots. Cinq sections toujours : Essence, Couleur, Typographie, Mouvement, Éviter. La définition du format : https://github.com/motionhub-dev/motions/blob/main/SPEC.md#5-motionmd
tokens.json	Les valeurs exactes, en tant que jetons de design W3C : color, font, et souvent duration et cubicBezier
poster.jpg	Une image d'un film réalisé avec ce motion
CREDITS.md	Chaque police et élément nécessaire, avec sa licence et sa source
react/	Les composants du motion, pour tout moteur React (section 5) : parts/, les fichiers qu'ils importent dans assets/, et une image de chacun dans previews/
<tool>/	Éléments prêts à l'emploi pour un autre outil. Ignorez les répertoires des outils que vous n'utilisez pas

Un motion peut aussi être un seul fichier : un MOTION.md qui commence par un en-tête contenant son spec, name et tokens, sous une forme courte (floor: "#E8D5B7"). Il dit la même chose que tokens.json mais n'a pas de composants, d'affiche ou de crédits.

1. Choisir le motion

• La personne en a nommé un (un nom, un id, ou un lien motionhub.dev/m/<id>) : utilisez-le.
• Le projet en a un : MOTION.md à la racine du projet, ou motion/MOTION.md : utilisez-le, puis passez à la section 3. Un projet peut en contenir plusieurs dans motions/ : des copies de motionhub dans motions/@<scope>/<slug>/, et les siens dans motions/<name>/. Utilisez celui qui est prévu pour chaque scène ; si le plan ne le précise pas, demandez lequel. Un projet peut également contenir d'autres fichiers de design, comme frame.md ou design.md. Le motion décide de l'apparence et du mouvement du film ; suivez les autres fichiers pour ce qu'il ne dit pas, et informez la personne lorsqu'ils divergent.
• Sinon cherchez : npx @motionhub/cli search <mots> (sans mots, les liste tous), ou lisez l'index https://motionhub.dev/api/motions.json, dont les lignes contiennent slug (l'id), name, line, fit, catalogs, tags, lang, poster et package, avec des chemins relatifs à https://motionhub.dev. Commencez par la forme du film : catalogs nomme les catalogues dans lesquels se trouve un motion (explainers, data, stories, tutorials, breakdowns, et footage pour un dessin par-dessus une vidéo apportée par la personne, donc proposez-le seulement si elle en a). Ensuite, faites correspondre le sujet et le support avec fit, lorsque le motion en a : fit.for indique à quoi il sert et fit.not ce qu'il gère mal. Un motion fait pour le sujet du film est un meilleur choix qu'un motion générique. Proposez-en deux ou trois avec leurs affiches, et laissez la personne choisir. Choisissez vous-même seulement si on vous le demande.

2. L'obtenir

Copiez l'intégralité du motion dans le projet, afin que le film conserve la version dans laquelle il a été réalisé :

npx @motionhub/cli get <id>            # dans ./motions/<id>/, vérifié par rapport au SHA-256 de l'index, enregistré dans motions.lock.json
npx @motionhub/cli get                 # tous les motions enregistrés dans motions.lock.json, lorsque le projet en a un et qu'ils sont manquants

Un film peut être réalisé dans plusieurs motions, un pour chaque partie ou chaque type de scène : récupérez chacun, et ils cohabitent dans ./motions/. Ne modifiez jamais une copie dans ./motions/@<scope>/ : pour en adapter un, copiez-le dans ./motions/<name>/ et modifiez cette copie.

Sans Node : téléchargez https://motionhub.dev/m/<id>/<version>.tgz, vérifiez-le par rapport au package.sha256 de la ligne, puis décompressez-le. Sans shell, récupérez https://motionhub.dev/m/<id>/MOTION.md, tokens.json, motion.json et CREDITS.md un par un.

3. Lire entièrement

Lisez l'intégralité de MOTION.md avant de dessiner quoi que ce soit, et tokens.json à côté, ou les tokens dans son en-tête. Si un MOTION.<lang>.md correspond à la langue dans laquelle vous travaillez, vous pouvez le lire ; il ne dit rien que MOTION.md ne dise pas.

4. Réaliser le film

• Les valeurs sont exactes. Chaque couleur, police, durée et easing provient des tokens du motion, par leur nom, dans les termes de votre moteur. Un token de police est une pile : utilisez ses polices dans l'ordre. N'approchez jamais une couleur à l'œil.
• L'Essence décide de chaque image. Chaque image doit avoir les caractéristiques qu'elle nomme, et ne doit pas dériver vers ce qu'elle dit que le motion n'est pas.
• Couleur et Typographie sont des rôles, pas une palette. Utilisez chaque token uniquement pour ce que sa section dit qu'il sert ; ce qu'elle dit ne pas être coloré reste non coloré.
• Le Mouvement est le minutage. Les éléments arrivent, changent et partent comme il le dit, sur la narration ou la musique comme il le dit. Ce qu'il dit ne bouge jamais reste immobile.
• Éviter est contraignant. Avant de terminer, vérifiez le film sur chaque point de la section Éviter.
• N'inventez jamais un nombre. Chaque chiffre, date et compte dans le film provient de l'histoire de la personne ou d'une source qu'elle vous a donnée. Si l'un manque, laissez un espace réservé visible et prévenez-la.
• L'histoire est vôtre. Disposez chaque scène pour ce que ce film raconte. Ne copiez pas le sujet, les mots ou la disposition de l'affiche ou d'un exemple.
• Les composants sont un raccourci. Si le motion a react/ ou un répertoire pour l'outil que vous utilisez, utilisez ses pièces (section 5). Les mots et les tokens restent directeurs.

5. Dans votre moteur

Lorsque le motion a react/, utilisez ses composants plutôt que de redessiner le look. Ce sont des composants React qui n'importent que @motionhub/runtime, et une liaison leur donne leur temps et leurs tokens dans votre moteur :

Moteur	Liaison	Comment faire
Remotion	npm i @motionhub/remotion	Enveloppez la composition dans <MotionProvider tokens={tokens}> (import tokens from '../motions/<id>/tokens.json'), ajoutez <MotionFonts />, et importez les composants depuis ../motions/<id>/react/parts/<file>.tsx. Avec plusieurs motions, enveloppez chaque scène dans <MotionScope tokens> depuis @motionhub/runtime
HyperFrames	npm i @motionhub/hyperframes, puis npx motionhub-hyperframes --out assets/motion (pour chaque motion dans ./motions/)	Chargez assets/motion/motion.css et motion.js ; Motion.mount(el, (t) => [...]) dessine Motion.components depuis votre timeline GSAP. Avec plusieurs motions, Motions[<id>] correspond à chacun

Lisez d'abord le README de la liaison. Le meta de chaque composant indique à quoi il sert (purpose, line, fits) et ce que chaque paramètre signifie, et react/previews/<file>.jpg le montre ; lisez le code d'un composant uniquement lorsque vous l'utilisez. Un paramètre de type progress varie de 0 à 1 : animez-le dans votre moteur, sur les mots qui le demandent. Un composant qui dessine en 3D importe three, que vous installez. Caption (depuis @motionhub/runtime) dessine une ligne parlée dans l'apparence de sous-titres du motion. Disposez chaque scène pour votre histoire ; les composants sont le look, pas le film.

Sinon, ou pour tout ce que les composants ne dessinent pas : les tokens sont des valeurs DTCG, et npx @motionhub/cli tokens --out tokens.json les écrit depuis un motion en un seul fichier, pour une liaison ou un thème ; transformez chacun dans les termes de votre moteur une fois, à un seul endroit (un module de thème), et utilisez-le partout par son nom :

• Couleur : $value.hex.
• Police : $value est une pile : la font-family CSS est ses noms dans l'ordre, chacun entre guillemets, le générique en dernier.
• Durée : $value est {value, unit} en s ou ms. Un moteur qui compte les images multiplie les secondes par son taux d'images et arrondit.
• Easing (cubicBezier) : $value est [x1, y1, x2, y2], la même courbe que CSS cubic-bezier(x1, y1, x2, y2). Un moteur sans easing l'échantillonne.

Moteur	Thème	Minutage
Remotion	useMotion() depuis @motionhub/remotion ; sinon un theme.ts exportant les couleurs et les piles de polices. Chargez les polices avec @remotion/google-fonts ou @remotion/fonts avant la première image	const {fps} = useVideoConfig() ; une durée est Math.round(seconds * fps) images ; interpolate(frame, [start, start + frames], [0, 1], {easing: Easing.bezier(x1, y1, x2, y2), extrapolateLeft: 'clamp', extrapolateRight: 'clamp'}). Préférez interpolate avec la courbe du motion à spring(), dont le dépassement n'est pas demandé par le motion
HTML et CSS	Propriétés personnalisées sur :root (--color-ink: #1B2A47)	transition ou animation avec la durée et cubic-bezier(...) ; l'API Web Animations accepte la même chaîne easing
GSAP	Les mêmes propriétés personnalisées	duration en secondes ; la courbe via CustomEase.create('arrive', 'M0,0 C x1,y1 x2,y2 1,1')

Si le motion a également un répertoire pour votre moteur (remotion/), ses pièces s'ajoutent aux composants : lisez d'abord son README.

6. Polices et crédits

• Installez les polices nommées dans CREDITS.md, depuis leurs sources et sous leurs licences. Si l'une est indisponible, utilisez la police libre la plus proche dans le même rôle et informez la personne laquelle.
• Les éléments nommés dans CREDITS.md sont utilisés sous leurs licences, avec le crédit qu'ils demandent.
• license.text couvre les mots, tokens et images du motion ; CC-BY-4.0 et CC-BY-SA-4.0 demandent un crédit. Ajoutez une ligne comme celle-ci dans la description ou les crédits de fin du film : Look : Ink Scroll par SuoSi, motionhub.dev/m/@iamsuosi/ink-scroll, CC BY 4.0. license.code couvre le code dans les répertoires d'outils.

7. Le modifier et partager votre propre look

Adaptez librement un motion pour un seul film, dans une copie personnelle (./motions/<name>/). Une copie modifiée n'est plus cette version : ne la publiez pas sous le même id et la même version.

Pour publier un look que la personne a créé (seulement si elle le demande) :

1. npx @motionhub/cli init <slug> --github <son login GitHub> crée ./motions/<slug>/ avec tous les fichiers requis à remplir, en tant que motion @<son login>/<slug> (demandez-lui son login ; avec gh connecté, --github peut être omis).
2. Prenez le look depuis son projet, jamais le film : les couleurs et polices du thème dans tokens.json (avec les durées et courbes utilisées par le projet) ; MOTION.md dans les cinq sections, disant ce que tout film dans ce look partage et rien de l'histoire de ce film ; CREDITS.md nommant chaque police et élément avec sa licence ; fit dans motion.json, honnêtement : general seulement s'il porterait trois sujets sans rapport, sinon topic avec le sujet pour lequel il est fait, ou overlay lorsqu'il dessine par-dessus leurs propres séquences.
3. poster.jpg : une image de leur film, un JPEG de 960 à 3840 pixels de large et au maximum 500 Ko (Remotion : npx remotion still <composition> poster.jpg --frame=<n> --image-format=jpeg).
4. Optionnellement les composants réutilisables, dans react/parts/ comme décrit dans CONTRIBUTING.md : des composants React qui n'importent que react et @motionhub/runtime (dans Remotion, useTime() et useVideoConfig() depuis celui-ci au lieu de Remotion), prennent ce qui change comme props, et ne contiennent rien de l'histoire de ce film.
5. Avec son accord, npx @motionhub/cli share motions/<slug> --wait exécute les vérifications que sa pull request exécutera et le télécharge sur motionhub.dev. Aucun jeton git, gh ou GitHub n'est nécessaire. Donnez à la personne le lien et le code qu'il imprime, exactement comme imprimés. Elle ouvre le lien, se connecte avec GitHub, vérifie le motion, tape le code et certifie le DCO, et motionhub ouvre la pull request sous son nom. La commande imprime alors l'adresse de la pull request : donnez-la aussi. Ne tapez jamais le code et ne soumettez jamais à sa place. Si elle préfère utiliser son propre fork avec gh, npx @motionhub/cli share motions/<slug> --pr le fait.

Un motion en un seul fichier se publie de la même manière, à partir de l'étape 1. Ensuite npx @motionhub/cli tokens --out motions/<slug>/tokens.json écrit ses valeurs, son name et lang vont dans motion.json, et son corps va dans motions/<slug>/MOTION.md sans l'en-tête. Le reste de motion.json, CREDITS.md et poster.jpg sont remplis comme ci-dessous.

Pour publier une nouvelle version d'un motion que la personne a publié (seulement si elle le demande, comme dans « publie une nouvelle version de @/ depuis ce projet ») :

1. Ayez le motion sous la main : sa propre copie dans ./motions/<name>/, ou npx @motionhub/cli get @<scope>/<slug> et copiez ./motions/@<scope>/<slug>/ dans ./motions/<slug>/ pour le modifier là.
2. Faites la modification qu'elle souhaite, depuis son projet, en respectant ce que MOTION.md dit que le look est ; un nouveau look est un nouveau motion.
3. Augmentez version dans motion.json au-dessus de la version publiée : un patch pour une correction, un mineur pour quelque chose d'ajouté (un composant, une section), un majeur pour un changement que les films déjà réalisés avec ne pourraient pas supporter. Une version publiée ne change jamais.
4. npx @motionhub/cli share <dir> --wait, comme ci-dessus : elle ouvre le lien et soumet ; si sa pull request pour ce motion est déjà ouverte, la nouvelle version y est ajoutée. Seul un des auteurs du motion peut le modifier ; le partage d'un autre auteur ouvre sa propre pull request. --wait attend jusqu'à 30 minutes.

Pour modifier un motion après des commentaires de révision sur sa pull request, lisez les commentaires (https://api.github.com/repos/motionhub-dev/motions/issues/<n>/comments et .../pulls/<n>/comments, aucun jeton nécessaire), faites les modifications demandées, et partagez à nouveau de la même manière.

Pour construire sur le motion de quelqu'un d'autre, publiez le vôtre sous votre propre scope, nommez le leur dans motion.json's basedOn ([{"id": "@iamsuosi/lab-notebook", "version": "1.0.2"}]) et dites dans CREDITS.md ce que vous avez pris et modifié ; seuls ses auteurs modifient l'original.

8. Vérifier avant de remettre

Placez une image de votre film à côté de poster.jpg, si le motion en a une : le même arrière-plan, les mêmes couleurs dans les mêmes rôles, les mêmes polices. Relisez ensuite Essence et Éviter une fois de plus par rapport au film, et corrigez ce qui ne tient pas.