Que fait évidence-narrée ?
Contrat d'activation
Charger lorsque l'utilisateur souhaite une vidéo avec voix expliquant une fonctionnalité ou reproduisant un bug, ou lorsque les captures d'écran seules ne peuvent pas montrer un flux (timing, séquence, état qui change). Pour un seul état statique, une capture d'écran suffit : ne pas enregistrer.
La CLI se trouve dans C:\Users\DESARROLLADORES\Documents\personal\ai-video-evidence (node bin/narrate.mjs). Elle nécessite Node 22+, ffmpeg/ffprobe dans le PATH, Google Chrome, et pip install edge-tts.
Règles strictes
- Écrire d'abord le script (
narration.json), le valider, puis enregistrer. Ne jamais enregistrer et narrer à la main. - Une scène = une idée et une ou deux phrases. La voix doit décrire ce qui est à l'écran dans cette scène, jamais ce qui vient après.
- La langue de la narration correspond au public (Espagnol pour les PR Trip2). Voix par défaut
es-CO-SalomeNeural; masculin :es-CO-GonzaloNeural. - Ne jamais taper de mots de passe. Pour les applications authentifiées, l'utilisateur exécute
narrate login <url>et se connecte ; pointerbrowser.storageStatevers le fichier sauvegardé. Supprimer ce fichier après l'enregistrement et le garder hors de git. - Utiliser uniquement les données de test confirmées par l'utilisateur. Les nouveaux enregistrements reçoivent un préfixe
QA_; ne jamais modifier ou supprimer les enregistrements existants. - Garder les sorties hors de git (
out/,pr-assets/). - Flux non déterministes (LLM, tâches asynchrones) : vérifier le résultat dans les images enregistrées. Si l'application a fait autre chose que ce que dit la narration, enregistrer à nouveau ; ne jamais livrer une vidéo dont la voix contredit l'écran.
Portes de décision
| Situation | Action |
|---|---|
| Rapport de bug | assets/bug-template.json : contexte → étapes → actuel (appel rouge) → attendu (vert) → évidence → impact |
| Démo de fonctionnalité / PR | assets/feature-template.json : ce qui est résolu → parcours → cas limites |
| Attente backend ou chargement lent | Mettre dans sa propre scène avec "speedup": 4 ; seule la partie après la narration est accélérée |
Popup natif <select>, boîte de dialogue OS, ou l'application nécessite la session ego réelle de l'utilisateur (Trip2 connecté) | "recorder": "gdigrab" (Windows uniquement). Avant d'exécuter : l'utilisateur se connecte à l'application dans ego, garde le moniteur 1 libre, et est prêt à basculer ego vers l'espace de tâche narrate-<nom> lorsque le runner le demande (ego garde les fenêtres Agent cachées ; le runner les affiche avec Win32 mais ego ne peint que l'espace sélectionné). Exécution non supervisée = utiliser playwright |
Le script gdigrab utilise call/actionsModule ou waitForResponse | Non pris en charge (erreur de validation) : utiliser un vrai backend ou un serveur local (examples/bug-demo/server.mjs) et waitFor sur le résultat UI |
| L'exécution gdigrab échoue avec "never became visible on screen" | La fenêtre de l'espace de tâche était cachée ou couverte. Demander à l'utilisateur de sélectionner l'espace dans ego et de relancer ; ne pas revendiquer ni réutiliser l'espace ou les onglets de l'utilisateur |
| Besoin de simulation ou d'étapes complexes | actionsModule avec des fonctions exportées async (page, ctx), appelées avec { "call": "nom" } |
| Étape d'évidence d'un bug | Lire out/<nom>/evidence.json (réponses échouées, erreurs console) d'une première exécution et mettre la vraie requête/statut dans l'appel evidencia |
Étapes d'exécution
- Copier le modèle correspondant à côté du travail (Trip2 :
pr-assets/<nom>.json) et remplirtitle,baseUrl, scènes, sélecteurs. node bin/narrate.mjs validate <fichier>; corriger chaque chemin rapporté.- Si l'application a besoin d'une session : avec
playwright, demander à l'utilisateur d'exécuternode bin/narrate.mjs login <url> --save pr-assets/state.json, puis définirbrowser.storageState. Avecgdigrab, l'utilisateur se connecte à l'application dans ego au préalable (chemin Trip2 :baseUrl= l'URL Trip2 locale,recorder: "gdigrab", scènes courtes, pas decall). node bin/narrate.mjs run <fichier>(outts,record,assembleséparément ;assembleseul re-rend sans enregistrer à nouveau).- Vérifier le résultat : extraire les images au début des scènes (
scenes.json) avecffmpeg -ss <t> -frames:v 1et les examiner ; confirmer l'audio avecvolumedetect; lireevidence.json(vide avec gdigrab). Avec gdigrab, confirmer que les images montrent uniquement la page (pas de bureau, barre des tâches ou autre fenêtre au-dessus). - Livrer
<nom>.mp4(H.264 + AAC + sous-titres doux) et<nom>.srt. Pour les PR Trip2 suivretrip2-pr-delivery: artefacts danspr-assets/, attachés à la PR, listés dans la description.
Référence des actions
goto (relatif à baseUrl), click, hover, check (sélecteur), fill/select {selector, value}, press {key, selector?}, scroll {selector? | y?}, wait (ms), waitFor (sélecteur ou {selector, state, timeoutMs}), waitForResponse (sous-chaîne d'URL, accepte aussi une réponse déjà vue dans la scène), overlay {kind: actual|expected|info, title?, text | html, durationMs?}, screenshot (nom), call (export de actionsModule). Les sélecteurs sont des localisateurs Playwright (#id, text=Guardar, role=button[name="Guardar"]). Avec recorder: "gdigrab", les sélecteurs sont passés tels quels à ego : CSS bruts, text=..., loc=role:button[name='Guardar'], @ref ; call et waitForResponse sont rejetés ; check, scroll {selector} et waitFor utilisent page.evaluate/waitForFunction pour les sélecteurs CSS bruts.
Champs de scène : id (slug), say, chapter {title, description?, durationMs?}, actions, speedup. Niveau supérieur : title, baseUrl, recorder (playwright | gdigrab), gdigrab {framerate: 25, drawMouse: true, tab: "new"}, viewport (Playwright uniquement), tts {engine: edge|deepgram|sapi, voice, rate, fallback}, browser {channel, headless, locale, storageState}, captions, showActions, gapMs, actionsModule, output.
Contrat de sortie
Retourner : chemin de la vidéo et durée, chemin du SRT, moteur TTS utilisé (et tout fallback), scènes avec leurs heures de début, ce que evidence.json a capturé, et tout ce qui n'a pas pu être montré (popups natifs, étapes instables).
Références
assets/bug-template.json,assets/feature-template.json— squelettes de script.README.mddu dépôt — installation, commandes, fonctionnement de la synchronisation.examples/bug-demo/— exemple complet avec un backend simulé (narration.json, Playwright) et la variante gdigrab (narration-ego.json+server.mjs).