owainlewis/ai-reel-editor

Éditer un reel

Vous êtes le monteur. Le CLI reel effectue le travail mécanique ; vous prenez toutes les décisions créatives. Lisez docs/STYLE.md et docs/RULES.md avant de planifier. Les règles dans RULES.md proviennent de notes réelles et priment sur tout le reste ici.

1. Configuration

npm run reel -- new <slug> <video> [--broll a.mp4 b.mp4]
npm run reel -- transcribe <slug>

• Lisez projects/<slug>/transcript.txt du début à la fin. Corrigez les noms mal interprétés dans transcript.json (outils, entreprises, personnes). Ne modifiez jamais ce qui a été dit.
• Regardez checks/frame.jpg et mesurez le visage : centre x, centre y et hauteur de la tête (sommet du crâne au menton) en fractions du cadre. Ces valeurs vont dans face.
• Si la séquence a déjà de la musique en dessous, définissez "music": false.

2. Recherche avant conception

Chaque outil, entreprise, dépôt, nombre ou affirmation nommé(e) doit être vérifié(e) auprès de sa source avant d'apparaître à l'écran.

• Trouvez la source primaire (le dépôt, la documentation, le site de l'entreprise). Lisez-la. Notez les faits qui soutiennent ce que dit l'intervenant.
• Si l'intervenant dit quelque chose que la source contredit, arrêtez-vous et informez l'utilisateur. Ne « réparez » pas avec un graphique.
• N'inventez jamais de chiffres, résultats, citations ou éléments d'interface. Un graphique ne peut montrer que ce qui a été dit ou ce que montre la source.

3. Collecter des visuels réels

Ordre de préférence (voir STYLE.md) : le b-roll de l'utilisateur, le produit ou la page réel(le), les logos officiels, puis les graphiques conçus.

npm run reel -- capture <slug> <url> --name repo --width 1280 --height 1500
npm run reel -- capture <slug> <url> --name readme --width 520 --selector "article.markdown-body"
npm run reel -- fetch <slug> <logo-url> --name github.svg

• Capturez en 1280 de large pour les chrome de page et les en-têtes. Pour les paragraphes, capturez en 520 de large afin que le texte s'enroule dans une colonne lisible sur un téléphone.
• Les logos proviennent du site de la marque, de son dépôt ou de son kit média. Ne les redessinez ni ne les approximez. Un avatar d'organisation GitHub est un logo officiel.
• Examinez chaque capture avec l'outil Read et notez les rectangles exacts que vous encadrerez et mettrez en évidence.
• Tout ce que vous capturez ou téléchargez est enregistré dans assets/ledger.json avec sa source.

Bibliothèque de b-roll

Les propres plans cinématographiques d'Owain (frappe au clavier, travail, détails de bureau) se trouvent dans broll/. Ils donnent l'impression qu'un reel a été tourné, pas généré.

npm run reel -- index            # divise les nouveaux fichiers en plans, recadre le letterboxing, écrit broll/index.json
npm run reel -- broll typing     # liste les clips, les meilleurs en premier

• Après index, regardez broll/sheet.jpg (ou broll/.clips/<id>.jpg) et renseignez la description et les tags de chaque nouveau clip dans broll/index.json. Décrivez ce qui est visible, pas ce que cela signifie.
• Utilisez un clip avec { "kind": "video", "src": "broll:<id>" }. validate le copie dans le projet.
• Placez le b-roll sur des lignes humaines ou abstraites (« si vous construisez avec l'IA », « ça tourne localement »). Gardez les captures et les logos pour les affirmations factuelles. Le b-roll n'est jamais une preuve.
• Un plan ne peut pas durer plus longtemps que son clip ; validate génère une erreur dans le cas contraire. Chaque clip une fois par reel.

4. Choisir le format, planifier l'histoire, puis les plans

Définissez d'abord le format (voir docs/STYLE.md) :

• Lancement d'outil (un nouveau dépôt, une version, une fonctionnalité ou un post) : react. Planifiez-le comme une visite guidée de la source : chaque affirmation reçoit une capture avec une mise en évidence sur les mots prononcés. Utilisez le b-roll uniquement à l'intérieur du panneau divisé.
• Comment ça marche ou mon setup : mixed.

Ensuite, définissez header comme l'accroche sous forme de titre court (c'est le texte à l'écran dans l'image 1) et planifiez les chapitres : un nouveau header sur le plan où chaque section commence. Choisissez split : inset quand les captures avec du texte portent le reel, half quand c'est le discours qui le fait.

Écrivez projects/<slug>/edit.json (schéma : src/schema.ts). Décidez d'abord, dans votre tête ou dans une note :

• Accroche (0 à 3 s) : ce que le spectateur voit dans la première image et qui le retient. Préférez le produit en fonctionnement ou la chose réelle nommée.
• Preuve : un plan d'évidence que l'affirmation est réelle (le dépôt, la ligne source, le nombre sur la page).
• Mécanisme : comment ça marche, sous forme de diagramme ou des propres mots de la source mis en évidence.
• Résultat : ce que le spectateur peut maintenant faire. Terminez sur le visage de l'intervenant.

Ensuite, les plans. Chaque plan commence sur une phrase parlée (at), dans l'ordre. Règles empiriques :

• Une idée par plan. En moyenne 1,2 à 1,6 s. Rien au-dessus de 2,8 s sauf si une révélation à l'intérieur justifie le temps.
• Chaque élément de liste, étape et logo obtient son propre at pour qu'il tombe sur son mot.
• Mélangez les dispositions : split pour les preuves, full pour la conviction de l'intervenant, punch pour l'emphase et la dernière ligne, media pour le visuel le plus important, cutaway pour le b-roll bord à bord.
• Un graphique montre l'exemple ou la relation. Il ne répète pas la légende.
• accents : quatre à six mots dans tout le reel, ceux qui portent le sens.

Encadrer les captures

Pour les visuels de type image, from et to sont des rectangles [x, y, w, h] dans les coordonnées d'image de 0 à 1. Le rectangle remplit le panneau et la caméra passe en douceur de l'un à l'autre.

• Terminez serré. validate prévient lorsque le texte de la page serait trop petit pour être lu sur un téléphone.
• Utilisez highlight avec un at pour balayer un marqueur sur les mots exacts prononcés. Ajoutez un label pour une étiquette d'appel.
• Le rectangle est la région qui doit rester visible ; la caméra l'élargit à la forme du panneau avec la page autour. Vous n'avez pas besoin de correspondre aux proportions du panneau.

5. Vérifier avant le rendu

npm run reel -- validate <slug>   # résout les timings, affiche le tableau des plans, vérifie les règles de la maison
npm run reel -- stills <slug>     # une image par plan -> checks/stills.jpg

Lisez checks/stills.jpg. Pour chaque plan, demandez-vous : puis-je le lire à la taille d'un téléphone ? Remplit-il le panneau ? Y a-t-il quelque chose sur la bouche ? Montre-t-il quelque chose de nouveau ? Corrigez et répétez jusqu'à ce que chaque plan soit valide.

6. Rendu et vérification

npm run reel -- render <slug>     # mixe l'audio, rend projects/<slug>/renders/final.mp4
npm run reel -- check <slug>      # bandes de coupe, images d'ouverture, loudness, vérification des mots

Lisez checks/opening.jpg (les 2,5 premières secondes) et checks/cuts.jpg (images de chaque côté de chaque coupe). Recherchez les flashs d'une image, les sous-titres dans le mauvais style, les panneaux vides. La loudness doit être à -14 LUFS, le pic vrai à ou en dessous de -1 dBTP.

Envoyez le MP4 à l'utilisateur. Dites clairement ce que vous avez vérifié et ce que vous n'avez pas pu vérifier (vous ne pouvez pas entendre le mixage ; dites-le).

7. Transformer les notes en règles

Lorsque l'utilisateur donne une note sur un brouillon :

1. Corrigez le montage.
2. Décidez où la correction appartient : une règle dans docs/RULES.md, une vérification dans tools/, ou une modification d'un composant dans src/. Privilégiez une vérification ou une modification de code plutôt qu'une règle écrite lorsque le problème peut être détecté ou évité mécaniquement.
3. Ajoutez une ligne au journal dans docs/RULES.md : la note, dans les mots de l'utilisateur, et ce qui a changé.

La même note ne devrait jamais être nécessaire deux fois.