Communitygithub.com

TVideo — votre app web en tutoriels vidéo 1080p sous-titrés

Plugin Claude Code qui filme votre vraie app web avec Playwright et un curseur visible, puis monte avec Hyperframes : sous-titres d'étapes dans toute langue, zoom et anneau sur chaque contrôle, sons de clic, musique, TTS optionnel, un MP4 1080p par tâche.

Qu'est-ce que TVideo — votre app web en tutoriels vidéo 1080p sous-titrés ?

Étape 1 de la recette Tutoriel vidéo (le pas-à-pas), tirée de JiramedFirst/TVideo (publié le 2026-10-08, MIT, GIF de démo de 33 s et captures dans le README). Demandez un tutoriel sur une app de préproduction : Claude découpe la demande en un clip par tâche et valide la liste avec vous, écrit un script Playwright par clip et le répète sans enregistrer pour prouver chaque sélecteur, puis enregistre video.webm avec timeline.json et clicks.json. Le monteur Hyperframes pose les images sur un canevas à vos couleurs, fige l'image quand il faut le temps de lire, zoome et entoure le contrôle à presser, ajoute un son par clic, de la musique et une voix HeyGen optionnelle, puis rend en 1080p. Le montage est généré depuis plan.json et la timeline des étapes : après un changement d'interface, il suffit d'enregistrer, importer, construire, rendre. Identifiants uniquement via variables d'environnement, demande avant tout environnement partagé, jamais de vrai paiement.

Compatible avec~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/JiramedFirst/TVideo/tree/HEAD/plugin/skills/tvideo

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

TVideo — tutoriels vidéo à partir d'une véritable application web

Vous produisez des courtes vidéos qui apprennent aux utilisateurs finaux à effectuer une tâche dans une application web. Les spectateurs ne sont pas techniques : chaque image doit être calme, lisible et réelle. Le pipeline se compose de deux parties qui se rencontrent en trois fichiers :

recorder (Playwright)  ──►  video.webm + timeline.json + clicks.json  ──►  éditeur (Hyperframes)  ──►  MP4
  • Recorder (templates/recorder/) pilote l'application réelle, affiche un curseur visible, et enregistre quand chaque étape commence/se termine et quand chaque clic se produit.
  • Éditeur (templates/editor/build.mjs) place les séquences sur un canevas de marque, maintient une image fixe là où le spectateur a besoin de temps pour lire, zoome + entoure le contrôle à presser, ajoute un son de clic sur chaque clic, et rend.

Comme le montage est généré à partir de ces fichiers, un ré-enregistrement après un changement d'UI est simplement : enregistrer → importer → builder → rendre. Gardez-le ainsi — ne modifiez jamais index.html à la main ; changez plan.json / tvideo.config.json et reconstruisez.

Phase 0 — Pré-vol

Effectuez ces vérifications au début de chaque session — en même temps que votre première réponse si vous posez des questions brèves, pour que l'utilisateur n'attende pas — et corrigez les lacunes avant l'enregistrement ; un outil manquant trouvé en cours d'enregistrement gâche une prise.

BesoinVérificationCorrectif
Node ≥ 20node -vinstaller Node
ffmpeg / ffprobeffmpeg -versionbrew install ffmpeg / apt
Hyperframes CLI + compétencesnpx hyperframes --versionnpx hyperframes skills update general-video (installe aussi media-use, hyperframes-audio)
Chromium pour Playwrightdans le dossier recorder : npx playwright install chromium—

Lisez references/hyperframes-notes.md une fois si vous n'avez pas utilisé Hyperframes dans cette session (règles de composition que le script de build suit déjà, et pourquoi).

Phase 1 — Brief (demander, ne pas supposer)

Collectez, en un seul tour court, ce qui change le travail :

  1. URL de l'application et environnement. Préférez un environnement de staging/UAT/démo. L'enregistrement pilote l'application pour de vrai : les formulaires sont soumis, des enregistrements sont créés, des e-mails sont envoyés. Dites-le clairement et obtenez un oui avant d'enregistrer contre quelque chose de partagé.
  2. Connexion : un compte démo dédié (nom d'utilisateur/mot de passe via variables d'environnement — jamais collé dans le chat ou écrit dans des fichiers). Si la connexion nécessite OTP/2FA, prévoyez que l'utilisateur colle le code pendant l'exécution (voir references/recording.md).
  3. Les flux : une vidéo par tâche. Divisez « comment utiliser le système » en clips de 30 à 120 s chacun (connexion, créer X, modifier/annuler X, télécharger Y…). Demandez l'ordre dans lequel le spectateur doit les regarder.
  4. Langue de l'interface utilisateur et des légendes (TV_LOCALE, lang).
  5. Marque : fichier logo, 1–2 couleurs, police si la langue en nécessite une (la police IBM Plex Sans Thai incluse couvre le thaï + le latin). Les valeurs par défaut sont un bleu marine/vert neutre.
  6. Audio : légendes + effets sonores de clic sont la valeur par défaut. Musique : piste CC BY incluse ou aucune. La narration est optionnelle et coûte du quota TTS — voir references/narration.md.

Décisions de sécurité (à régler dans le brief, avant tout enregistrement)

Ces vidéos sont distribuées, et l'enregistrement effectue des actions réelles. Expliquez le compromis, recommandez l'option sécurisée, et laissez l'utilisateur décider — puis suivez-la.

  • Quelles données sont à l'écran. Rien que le public ne doit pas voir : noms d'autres clients, commandes réelles, e-mails/adresses/numéros de téléphone personnels, étiquettes de test internes. Recommandez un compte démo fictif. Si l'utilisateur insiste pour un compte personnel ou réel, dites exactement ce qui sera visible, obtenez un OK explicite, et planifiez des mask pour chaque valeur personnelle (vérifiez-les sur les captures d'écran). Si vous n'êtes pas sûr qu'une valeur soit réelle, demandez.
  • Étapes irréversibles ou financières (payer, transférer, envoyer à un tiers réel, supprimer, publier). Ne terminez jamais un paiement réel ou une autre action irréversible juste pour le filmer. Préférez un mode sandbox/test (carte de test, passerelle de staging) ; s'il n'y en a pas, enregistrez jusqu'à l'écran de confirmation final, arrêtez-vous là, et laissez la dernière légende expliquer le clic final. Dites-le dans le brief.
  • Production vs staging. L'enregistrement sur un site de production en direct nécessite un oui explicite après avoir listé ce qu'il va créer (commandes, e-mails, changements de stock) et comment il sera nettoyé. Préférez les flux qui sont en lecture seule ou réversibles là-bas.
  • Identifiants. Les mots de passe et OTP vont dans les variables d'environnement / un fichier local que l'utilisateur contrôle, jamais dans le chat ou dans des fichiers que vous créez. Un nom d'utilisateur/e-mail que l'utilisateur a déjà tapé n'est pas un secret, mais ne le répétez pas dans des fichiers au-delà de TV_USERNAME.
  • Connexion tierce (Google, Microsoft, SSO, captcha). La connexion automatisée là-bas rencontre généralement des vérifications anti-bot ou 2FA. Demandez à l'utilisateur de se connecter une fois à la main dans un navigateur avec interface graphique (npx playwright codegen --save-storage=.auth/state.json <URL de connexion>), puis enregistrez avec cette session sauvegardée et laissez TV_USERNAME non défini.
  • Publication. Avant de livrer, revoyez pour des données personnelles, et gardez le crédit musical sur l'outro (CC BY nécessite attribution). Les pages publiques sont un public plus strict que la formation interne — appliquez strictement les règles de confidentialité.

Phase 2 — Découvrir et répéter

  1. Créez un dossier de travail par projet, par ex. tvideo-work/<app>/, puis copiez templates/recorder/ → recorder/ et npm i là.
  2. Découvrir : ouvrez chaque page d'un flux (Playwright MCP / outils de navigateur, ou un script jetable) et choisissez des sélecteurs stables — préférez les rôles/étiquettes/test-ids aux classes CSS. Notez les choses qui ne filment pas bien (voir recording.md : les popups natives <select>, les sélecteurs de date, les sauts de défilement instantanés, les fenêtres de réservation).
  3. Écrivez une spécification par clip dans recorder/clips/NN-name.spec.ts, en suivant clips/01-example.spec.ts : createTimeline d'abord ; chaque étape visible par le spectateur est tl.step('<texte de légende>', …) se terminant par un expect ; clics via tap()/typeInto() ; glideTo() avant tout ce qui est en dessous de la ligne de flottaison ; hold() après les moments clés ; await tl.save() en dernier. Choisissez les valeurs comme le ferait un utilisateur — choisissez dans les listes déroulantes/calendriers plutôt que de taper des codes.
  4. Répéter : TV_REHEARSE=1 npx playwright test — pas de vidéo, pas de pauses. Corrigez chaque échec ici ; cela coûte des secondes au lieu d'une prise gâchée.

Phase 3 — Enregistrer

npx playwright test (ou un seul clip : npx playwright test clips/02-). Chaque clip écrit video.webm, timeline.json, clicks.json sous test-results/<clip>/. Copiez-les immédiatement (l'étape suivante le fait) — Playwright efface test-results/ à l'exécution suivante.

Un échec d'étape signifie que l'application a fait quelque chose d'inattendu (validation, règle métier, chargement lent). Lisez la capture d'écran d'échec, corrigez la spécification ou les données, relancez ce clip. Ne relâchez jamais une assertion juste pour obtenir une prise ; une prise verte d'un flux cassé apprend aux utilisateurs la mauvaise chose.

Phase 4 — Configurer le montage

Un projet Hyperframes par clip, à côté du recorder (par ex. tvideo-work/<app>/clip-02/). hyperframes init écrit ses propres fichiers de démarrage ; copier le template par-dessus est intentionnel (build.mjs régénère index.html). Exécutez depuis le dossier de travail :

npx hyperframes init clip-02 --non-interactive --example=blank
cp -R <skill>/templates/editor/. clip-02/
cp clip-02/tvideo.config.example.json clip-02/tvideo.config.json   # marque, police, logo, musique, langue
cp clip-02/plan.example.json clip-02/plan.json                     # titre, outro, une étape par tl.step
ls recorder/test-results/                                          # le dossier du clip a un nom long — trouvez-le ici
bash <skill>/scripts/import.sh recorder/test-results/<ce-dossier> clip-02
bash <skill>/scripts/sfx.sh clip-02                                # click-doux, whoosh-court, carillon, étincelle

Dans tvideo.config.json : définissez lang et readingCharsPerSec (≈15 anglais, ≈12 thaï — les scripts plus lents se lisent plus lentement), les couleurs de marque, et logo (un chemin, ou null pour des cartes textuelles uniquement). Gardez music.credit — la piste incluse est CC BY.

Les étapes de plan.json correspondent 1:1, dans l'ordre aux tl.step du recorder (le build refuse une discordance). Les légendes dans plan.json sont ce que le spectateur lit — gardez-les comme des instructions courtes ("Cliquez sur « Enregistrer »"), pas une narration. Habituellement, les étiquettes tl.step sont déjà de bonnes légendes ; copiez-les.

Phase 5 — Mesurer, builder, vérifier

  1. Extrayez des images pour trouver les coordonnées : bash <skill>/scripts/frames.sh assets/footage.mp4 frames <t1> <t2> …. Bons moments : chaque clic dans clicks.json moins ~0,3 s (le curseur est déjà sur le contrôle — c'est sa position), et endMs de chaque étape moins 0,3 s (le résultat stable). Lisez les PNG en taille réelle. Les coordonnées sont en pixels de l'enregistrement (par ex. 1280×800).
  2. Ajoutez par étape si nécessaire (détails dans references/editing.md) :
    • zoom {scale,at} + ring {x,y,w,h} sur le contrôle à presser — le zoom se centre sur le ring (le point fixe d'un zoom doit être sur le contrôle, sinon le contrôle glisse vers le bord et est recadré) ;
    • holdFirst: true lorsque le contrôle disparaît une fois cliqué (un bouton qui navigue ailleurs) — affiche d'abord l'image avant le clic ;
    • mask {x,y,w,h,text,after} pour couvrir une valeur qui ne doit pas être diffusée ;
    • chimeAfter: <s> pour un moment de succès.
  3. node build.mjs puis npx hyperframes check. Corrigez chaque erreur ; les avertissements concernant le contraste pendant un fondu d'une légende sont attendus et inoffensifs.
  4. Vérifiez de vos propres yeux : build.mjs imprime où chaque étape se trouve dans la timeline OUTPUT (le temps de sortie ≠ le temps d'enregistrement — l'intro et les arrêts le décalent). Faites des captures dans ces fenêtres — npx hyperframes snapshot --at <t…> --no-end, une à l'intérieur de chaque image fixe qui a un ring, chaque masque, chaque étape intermédiaire — et lisez la planche contact. Les rings doivent être sur le contrôle, les masques doivent couvrir exactement, les légendes doivent correspondre à ce qui est à l'écran.

Phase 6 — Réviser et rendre

  1. Ouvrez un aperçu : npx hyperframes render --quality draft -o renders/draft.mp4 et open (l'aperçu Studio npx hyperframes preview --background fonctionne aussi, mais sa recherche peut saccader sur les longs clips ; le rendu ne le fait jamais).
  2. Itérez sur les retours en éditant le plan/config et en reconstruisant — ou en ré-enregistrant lorsque les séquences elles-mêmes sont mauvaises (rythme, un saut, mauvaises données). Corrigez les problèmes de séquences à la source, pas avec des superpositions.
  3. Final : npx hyperframes render --quality delivery -o renders/<nom-du-clip>.mp4. Rapportez le chemin, la durée et la taille.
  4. Nettoyez ce que l'enregistrement a créé dans l'application (commandes/réservations démo) si l'environnement est partagé, et dites ce que vous avez nettoyé.

Quand quelque chose ne va pas

references/troubleshooting.md liste les échecs que ce pipeline a déjà rencontrés et leurs causes réelles (dérive de séquences/timeline, selects natifs, fenêtres de réservation, résultats de test écrasés, lint de chevauchement SFX, saccade dans l'aperçu). Vérifiez-le avant le débogage à partir de zéro.

Fichiers dans cette compétence

  • templates/recorder/ — Projet Playwright : cursor.ts, timeline.ts, auth.setup.ts, playwright.config.ts, clips/01-example.spec.ts (écrit pour le examples/demo-app du dépôt du plugin, associé à plan.example.json)
  • templates/editor/ — build.mjs, plan.example.json, tvideo.config.example.json, assets/fonts (OFL), assets/music (CC BY)
  • scripts/ — import.sh, frames.sh, sfx.sh, voice.mjs (TTS optionnel)
  • references/ — recording.md, editing.md, narration.md, hyperframes-notes.md, troubleshooting.md

Skills associés