clip-builder

Clip builder

Construisez une courte vidéo à partir de trois éléments : une page HTML qui affiche l'image (la scène), une liste de lignes de script dans clip.json (les répliques), et un outil en ligne de commande qui capture la page image par image et encode un MP4.

La page de scène définit draw(s), qui positionne la page à l'état correspondant à la seconde s, calculé uniquement à partir de s. La capture appelle cette fonction pour chaque image (seconde 0, puis 1/30, etc.) et prend une capture d'écran. Ainsi, la sortie ne dépend pas de la vitesse de la machine, n'importe quelle image peut être rendue individuellement pour révision, et une modification d'une partie de la clip peut être recapturée avec --from et --to.

Le CLI est scripts/clip.mjs dans le répertoire de ce skill. Dans ce document, clip signifie node "<répertoire_skill>/scripts/clip.mjs", où <répertoire_skill> est le chemin absolu du répertoire contenant ce fichier. (Claude Code remplace ce chemin ici : ${CLAUDE_SKILL_DIR}. Dans d'autres agents, utilisez le répertoire depuis lequel ce fichier a été lu.) Exécutez les commandes depuis le répertoire du projet clip, qui contient clip.json. clip help liste toutes les commandes et options.

Prérequis

Node 20 ou ultérieur, ffmpeg, et Playwright avec Chromium. clip doctor les vérifie et affiche les commandes d'installation pour tout élément manquant. Installez Playwright dans le répertoire où les clips sont construites (npm install --save-dev playwright, puis npx playwright install chromium), pas dans le répertoire de ce skill. La narration et la musique générée sont optionnelles. Ce sont les seules étapes qui coûtent de l'argent ou nécessitent une clé API.

Commandes sandboxées (par défaut dans Codex) : clip stills, clip capture et clip serve démarrent un serveur HTTP sur 127.0.0.1, et les deux premières démarrent également Chromium. Un sandbox de commande bloque les deux. La commande se termine alors avec le statut 1 et un message qui nomme le sandbox. Demandez l'autorisation d'exécuter ces trois commandes en dehors du sandbox, et précisez la raison. Ne substituez pas une autre méthode de capture. Les autres commandes n'ont besoin ni d'un serveur ni d'un navigateur et s'exécutent à l'intérieur du sandbox ; tts --generate et music --generate nécessitent également un accès réseau.

Résumé

Établissez les éléments suivants avant de commencer. Ne demandez que ce qui manque. Pour tout ce que l'utilisateur n'a pas spécifié, utilisez la valeur par défaut et indiquez-la en une ligne.

• Objectif et public : promotion, démo produit, tutoriel pour le personnel, leçon. Cela détermine le rythme. Les clips promotionnels sont rapides ; les clips de formation laissent le temps de suivre chaque étape.
• Durée. Par défaut : 20 à 45 secondes pour une promotion ou une démo, 60 à 120 pour une formation.
• Destination, qui détermine les formats. Par défaut : wide 1920×1080, plus tall 1080×1350 pour les flux sociaux. Voir references/delivery.md.
• Approche visuelle : nouveaux graphiques ou écran d'application. Pour une application : quels écrans, et si son code source ou son système de design est disponible comme source pour les couleurs, la typographie et l'espacement.
• Son. Par défaut : silencieux avec légendes. C'est gratuit, et la plupart des vidéos de flux sont lues en mode muet. La narration et la musique sont facultatives.
• Script. Utilisez le script de l'utilisateur s'il en a un. Sinon, rédigez-en un et obtenez son approbation avant de construire la scène.

Flux de travail

1. Vérifiez les outils : clip doctor.
2. Créez le projet : clip init <dir> --template graphics ou --template app-ui. Cela écrit clip.json, un répertoire scene/ avec un exemple fonctionnel, et audio/. Les deux templates s'affichent sans modification.
3. Rédigez les répliques dans clip.json, une par moment clé. Un moment clé est un segment de la clip avec une ligne et un état visuel. Écrivez d'abord le script : la scène est chronométrée en fonction de celui-ci, et tout changement de formulation après l'enregistrement est une nouvelle requête payante. references/narration.md couvre l'écriture pour la parole.
4. Construisez la scène : éditez scene/index.html et scene/scene.js. Lisez d'abord references/scenes.md. Il énumère les contraintes qui maintiennent une scène déterministe : pas de Math.random(), pas d'horloges ou de minuteurs, pas d'animations CSS, tout état calculé à partir de s. Pour un écran d'application, lisez également references/app-ui.md.
5. Révision des images fixes : clip stills écrit les images à des secondes sélectionnées et une planche contact dans out/review/. Ouvrez la planche contact en tant qu'image et inspectez-la. Vérifiez que le texte est lisible, que rien ne se chevauche, et que chaque moment clé est à l'écran pendant que sa légende est affichée. Répétez pour chaque taille de format (--frame tall). Effectuez la majeure partie de l'itération à cette étape : les images fixes sont rapides et ne coûtent rien. clip serve sert un aperçu en direct pour l'utilisateur.
6. Capturez un brouillon : clip capture --draft rend aux deux tiers de la taille pour vérifier le mouvement et le rythme. Donnez à l'utilisateur le chemin du fichier et demandez-lui de le regarder.
7. Ajoutez du son, si demandé. Narration : references/narration.md. Musique et mixage : references/sound.md. Exécutez d'abord clip tts sans indicateurs ; il liste les demandes prévues et le nombre de caractères. Obtenez l'approbation de l'utilisateur, puis exécutez clip tts --generate. Après tout nouvel enregistrement, exécutez clip timing, qui place les répliques et les légendes et, si configuré, étire la scène pour correspondre à la narration. Ensuite, révisez à nouveau les images fixes.
8. Capturez la version finale : clip capture --final pour chaque format, puis clip mix s'il y a du son, puis clip web <fichier> pour une copie plus petite à télécharger.
9. Vérifiez et rapportez : révisez les images fixes de la version finale, lisez le volume dans le rapport de mixage, et exécutez clip scan out. Rapportez ce qui a été produit, les chemins des fichiers, ce qui a été vérifié et ce qui ne l'a pas été.

Un clip silencieux saute l'étape 7. Ses légendes proviennent des valeurs at et until de chaque réplique, et clip timing les écrit pour la page.

Règles de sécurité

Un travail de clip implique l'argent de l'utilisateur, ses clés API et son identité publiée.

• Les demandes payantes nécessitent une approbation explicite de l'utilisateur. Le fournisseur facture la narration et la musique. Le CLI n'envoie rien sans --generate ; ne passez cet indicateur qu'après que l'utilisateur a approuvé cette prise spécifique. L'approbation pour une prise ne couvre pas la suivante. Affichez la sortie de l'exécution à sec (lignes et nombre de caractères) lorsque vous demandez. Si une demande est interrompue, son reçu reste attempted. Ne réessayez pas avant que l'utilisateur ait vérifié l'historique d'utilisation du fournisseur, car la demande peut avoir été facturée.
• Les clés API proviennent uniquement de l'environnement. Le CLI lit ELEVENLABS_API_KEY ou OPENAI_API_KEY et aucune autre source. Passez une clé en ligne pour une seule commande à partir du stockage secret de l'utilisateur (references/keys-and-paid-calls.md contient les commandes). Ne demandez pas à l'utilisateur de coller une clé dans la conversation, n'en imprimez pas (echo, env, cat), et n'en écrivez pas dans un fichier. Pour confirmer qu'une clé est définie, vérifiez sa longueur ; clip doctor fait cela.
• Livrez les fichiers ; ne publiez pas. La publication ou le téléchargement d'un clip est l'action de l'utilisateur, sauf s'il demande cette action spécifique.
• Utilisez uniquement du matériel que l'utilisateur a le droit d'utiliser. La musique, les polices, les logos et les séquences nécessitent une licence ou la propriété de l'utilisateur. Montrez uniquement une application que l'utilisateur possède ou pour laquelle il a l'autorisation de montrer, et ne stylisez pas une maquette comme le produit d'une autre entreprise. Les conditions des deux fournisseurs couvrent l'utilisation commerciale et la divulgation des voix générées ; dirigez l'utilisateur vers elles avant la publication d'un clip narré.
• Gardez les données privées hors de l'image et des fichiers. Utilisez des noms et numéros fictifs dans les écrans d'application. Les chiffres et les citations présentés comme réels doivent être réels, et les exemples doivent être identifiables comme des exemples. Exécutez clip scan sur tout ce qui est partagé. Il vérifie les clés API, le nom d'utilisateur local et les chemins, les adresses e-mail, la liste des termes privés de l'utilisateur, et les métadonnées intégrées dans les fichiers multimédias.

Directives éditoriales

• Couvrez un seul sujet par clip. Divisez un script qui en couvre deux.
• Commencez la narration ou la première légende dans les premières secondes.
• Utilisez une réplique par moment clé, et maintenez le visuel d'un moment clé à l'écran pendant que sa ligne est prononcée.
• Incluez toujours des légendes. La plupart des vidéos de flux sont lues en mode muet.
• Révisez les formats verticaux à la taille d'un téléphone. L'unité de scène est plus grande dans les formats verticaux pour cette raison.
• Utilisez le mouvement pour marquer un changement d'état ou pour attirer l'attention. Évitez le mouvement continu.
• Maintenez la carte de fin pendant au moins 2,5 secondes.
• Pour la formation : montrez l'action, puis son résultat, à un rythme que le spectateur peut suivre tout en l'exécutant. Numérotez les étapes à l'écran et indiquez au début ce que le spectateur sera capable de faire.

Commandes

Commande	Fonction
clip doctor	Vérifie Node, ffmpeg et Playwright, et signale quelles clés sont définies (longueur uniquement)
clip init <dir> --template graphics|app-ui	Crée un projet à partir d'un exemple fonctionnel
clip serve	Sert un aperçu en direct ; ?t=5 dans l'URL maintient à 5 s
clip stills [--at 2,5,9] [--frame tall] [--final]	Affiche les images de révision et une planche contact
clip capture [--frame wide] [--draft] [--final] [--from s --to s] [--web]	Affiche chaque image et encode un MP4
clip capture --mode clock --url … --seconds N [--actions file.mjs]	Capture une application en cours d'exécution (expérimental ; voir references/app-ui.md)
clip tts [--generate]	Liste les narrations encore à enregistrer ; avec --generate, les enregistre (payant)
clip music [--generate]	Idem pour une partition générée (payant)
clip timing	Calcule les temps des répliques et des légendes ; écrit scene/timing.json et un fichier .srt
clip mix	Construit la bande sonore à un volume standard et la muxe dans chaque vidéo capturée
clip web <video>	Écrit une copie plus petite pour le téléchargement
clip scan <dir> [--terms-file mots.txt]	Signale les données privées avant le partage de fichiers
clip strip <fichier multimédia>	Écrit une copie avec toutes les métadonnées intégrées supprimées

La sortie va dans out/, nommée <nom>-<prise>-<format>.mp4, avec les suffixes -draft, -part (une plage capturée avec --from/--to), -sound et -web ajoutés selon le cas. Pour conserver une version antérieure à côté d'une nouvelle, incrémentez "take" dans clip.json (a, b, c, …).

Fichiers de référence

Lisez le fichier nécessaire à l'étape en cours.

Fichier	Lisez-le quand
references/scenes.md	Écrire ou modifier une scène : le contrat de la page, la bibliothèque d'aide, les unités, les formats verticaux, les polices et les contraintes qui rendent une capture déterministe
references/app-ui.md	La clip montre un écran d'application : le reconstruire à partir des jetons de design, le pointeur, la saisie, les mouvements de caméra et la capture d'une application en cours d'exécution
references/narration.md	Écrire les lignes, choisir un fournisseur et une voix, la prononciation, ré-enregistrer une ligne, adapter la scène à la narration, les légendes
references/sound.md	Musique et mixage : niveaux, ducking, adapter une piste à la clip, volume, corriger un mixage
references/keys-and-paid-calls.md	Avant toute demande payante : passer une clé en toute sécurité, ce qui est envoyé, les reçus, les demandes interrompues
references/project-file.md	Tout champ de clip.json
references/delivery.md	Tailles de format, rendu final, vérifications avant livraison, ce qu'il faut rapporter
references/cookbook.md	La demande correspond à un travail courant. Douze recettes éprouvées : un clip silencieux, un écran d'application à partir de jetons de design, plusieurs rapports d'aspect, un clip de formation pas à pas, un diagramme à barres à partir de JSON, une narration avec chaque fournisseur, ré-enregistrer une ligne, une musique de fond, une police et un logo personnalisés, une application en cours d'exécution, les vérifications finales. Également des extraits de draw()

Dépannage

Symptôme	Cause probable
"This looks like a command sandbox", listen EPERM, ou le navigateur ne démarre pas	Le sandbox de l'agent bloque le serveur HTTP ou le navigateur. Exécutez stills, capture et serve en dehors de celui-ci, avec l'approbation de l'utilisateur
"The page never set window.ready"	Une erreur de script dans la scène (le message liste les erreurs de la page), ou la page n'appelle pas le clip() du kit
Deux captures de la même scène diffèrent	Un état de la scène n'est pas calculé à partir de s : Math.random(), Date, une animation ou transition CSS, une <video>, un minuteur
Le texte s'affiche dans une police différente sur une autre machine	La scène utilise des polices système. Placez les fichiers de police dans le répertoire de la scène (references/scenes.md)
L'image est en avance ou en retard sur la narration	clip timing n'a pas été exécuté après un nouvel enregistrement, ou la vidéo a été capturée avant. clip mix refuse de s'exécuter dans le premier cas et prévient dans le second
attempted dans la liste tts	Une demande précédente ne s'est pas terminée. Vérifiez l'historique d'utilisation du fournisseur avant d'utiliser --retry-attempted
Le niveau de la musique monte et descend entre les mots	Définissez "mix": { "master": "limit" } (references/sound.md)