Enregistrement de démonstration produit

Que fait Enregistrement de démonstration produit ?

Traitez le cadrage, la confidentialité, le récit et la sortie décodée comme des jalons de release distincts. Une exécution produit réussie ne prouve pas que l'enregistrement est sûr, lisible ou proprement composé.

Pour les mécanismes de capture natifs macOS ou navigateur, lisez références/capture-macos.md. Pour les constructeurs de workflows navigateur avec sondage ou boucles de réessai, lisez références/workflows-navigateur.md. Pour les cartes titres, tiers inférieurs, diagrammes, légendes et cartes de fin, lisez références/style-infographique.md.

Établir d'abord le cadre de livraison

Avant d'enregistrer :

1. Choisissez le type de récit avant d'écrire la liste des plans :
   • Une vue d'ensemble enseigne la forme du produit : montrez la séquence de nœuds ou d'écrans la plus représentative, utilisez un contenu générique, et omettez toute explication spécifique au scénario.
   • Une démo de scénario répond à une question concrète : énoncez le cas, montrez les étapes d'exécution réelles, et terminez par le résultat vérifié.
   • Privilégiez des vidéos courtes séparées lorsque les deux sont utiles. Ne mélangez pas une explication produit générique avec un cas spécifique à un domaine, sauf si l'utilisateur souhaite explicitement un tutoriel combiné.
2. Établissez une référence visuelle :
   • Si un enregistrement précédent existe, inspectez-le du début à la fin. Extrayez une planche contact si utile, et notez son rythme, son cadrage, ses annotations et ses moments explicatifs les plus forts.
   • S'il n'y a pas d'enregistrement précédent, utilisez la bibliothèque @themoltnet/design-system, les médias de documentation voisins, et l'interface native du produit intégré—dans cet ordre—pour créer une vignette de carte titre, la vignette d'interface annotée la plus dense, et une vignette de carte de fin avant d'enregistrer. Ces vignettes approuvées deviennent la base des vidéos ultérieures de la série.
3. Lisez la page où la vidéo apparaîtra. Écrivez une courte liste de plans qui nomme le résultat pour l'utilisateur, la configuration requise, l'interaction principale, le comportement d'attente ou de réessai, et le résultat réussi.
4. Choisissez le rapport hauteur/largeur et la résolution finaux avant de disposer l'application. Privilégiez un cadre 16:9 conventionnel tel que 1440×810 ou 1920×1080.
5. Disposez l'application de manière à ce que la zone de contenu prévue complète s'adapte à ce cadre. Masquez les barres latérales optionnelles dans l'application si nécessaire ; ne retirez pas la moitié d'une barre latérale ou d'un contrôle avec un recadrage arbitraire en post-production.
6. Décidez si le chrome du navigateur fait partie de la composition. Privilégiez une capture propre du viewport du navigateur. Si cela n'est pas possible, gardez la fenêtre complète du navigateur ou placez-la dans un cadre délibéré. Une fenêtre complète est plus propre que des onglets, bords ou contenu d'application rognés.
7. Révisez les trois images de style représentatives à leur taille d'affichage réelle. N'enregistrez pas le tutoriel complet tant que le système de superposition, les zones de sécurité ou la hiérarchie de l'information sont encore en cours d'invention.

Utiliser une limite de capture sécurisée

• Capturez une fenêtre d'application ou un viewport de navigateur, jamais un rectangle de bureau dans lequel une autre application peut entrer.
• Résolvez et verrouillez l'identifiant exact de la fenêtre avant d'enregistrer. Revérifiez-le après la navigation, les pop-outs ou les redémarrages d'application.
• Désactivez les notifications et utilisez des données de démo dédiées, mais ne comptez pas sur ces précautions comme limite de confidentialité.
• Gardez les identifiants, jetons, identifiants personnels, URL privés et données de compte non liées en dehors de la surface capturée. Le masquage des mots de passe est nécessaire mais ne rend pas les images de saisie d'identifiants souhaitables.
• Rendez le pointeur intentionnel. Placez-le loin du texte pendant qu'un résultat statique est en cours de lecture.

Enregistrer pour la compréhension

• Utilisez une idée par plan. Maintenez les configurations et résultats importants assez longtemps pour être lus à vitesse de lecture normale.
• Montrez la configuration uniquement si elle aide le spectateur à reproduire le résultat. Pour les démos d'intégration, cela signifie souvent installer, authentifier sans révéler le secret, importer le workflow, l'exécuter et inspecter le résultat terminal.
• Privilégiez le zoom natif de l'application et les modifications de disposition plutôt que l'agrandissement ultérieur d'un raster recadré.
• Capturez l'exécution réussie réelle. Les cartes titres reconstruites et les annotations peuvent l'expliquer, mais ne doivent pas suggérer une action ou un résultat qui n'a pas été observé.
• Un montage dirigé par l'état peut utiliser des images propres capturées à partir d'une seule exécution réelle lorsque le mouvement lui-même n'est pas pédagogique. Conservez les états dans l'ordre observé, préservez les preuves de tâche visibles, et utilisez des transitions uniquement pour communiquer la progression.
• Effectuez la création des identifiants et les tests de connexion en dehors de la prise enregistrée. Commencez le récit à partir d'un état authentifié sécurisé, sauf si la configuration des identifiants est le sujet documenté.
• Enregistrez des prises courtes et indépendamment utilisables lorsque le flux comporte des étapes stables. Cela limite les réenregistrements et rend la revue de confidentialité plus précise.
• Pour une boucle de sondage ou de réessai longue, conservez les états ordonnés réels mais accélérez ou rognez la partie inactive répétée. Maintenez l'action initiale, l'état du workflow terminal et le résultat accepté à une vitesse lisible.

Éditer sans cacher le produit

• Conservez chaque bord intentionnel de l'application. Réduisez et rembourrez jusqu'au cadre de livraison plutôt que de recadrer le contenu pour forcer un rapport hauteur/largeur.
• Utilisez des cartes titres et de fin uniquement lorsqu'elles améliorent l'orientation ou les prochaines étapes.
• Gardez les tiers inférieurs à l'intérieur d'une zone de sécurité préplanifiée. Ils ne doivent pas couvrir les contrôles, le statut, la sortie, les erreurs ou les identifiants nécessaires pour comprendre le flux.
• Pour les démos de scénario, laissez les annotations avancer avec l'exécution. Nommez l'étape actuelle et expliquez sa conséquence en une ligne courte, par exemple INTENTION — Extraire le lieu et la période suivi de INTENTION TERMINÉE — Récupérer les prévisions. Utilisez les noms d'étape réels du produit et l'état observable ; ne racontez pas un raisonnement caché.
• Gardez une vidéo de vue d'ensemble visuellement plus calme que sa démo de scénario compagnon. Les étiquettes de nœuds et les indicateurs de statut natifs devraient porter l'explication lorsqu'ils sont déjà suffisants.
• Adaptez le langage visuel de la documentation établi lors du remplacement d'une vidéo existante. Ne rendez pas un remplacement moins délibéré que l'actif qu'il remplace.
• Pour une large compatibilité navigateur, utilisez par défaut H.264 High, yuv420p, constant 30 ips, pas d'audio sauf si la narration est intentionnelle, et MP4 fast-start.
• Sur cette chaîne d'outils macOS, privilégiez le libx264 monothread pour le rendu final lorsque c'est pratique. Utilisez le helper fourni au lieu de la recherche d'entrée rapide pour extraire des images de QA à horodatage exact.
• Si une image semble corrompue dans un aperçu d'artefact, rouvrez l'artefact stable par somme de contrôle et inspectez la vidéo dans un lecteur natif. Le chemin d'aperçu a parfois rendu des octets d'image identiques différemment ; ne modifiez pas une vidéo à moins que le défaut ne soit reproductible indépendamment.
• Si une image reste corrompue en lecture normale et après extraction répétée, remplacez le segment affecté à partir d'une source propre et ré-encodez le maître final avec -threads 1.

Ajouter de l'audio uniquement lorsqu'il mérite sa place

• Gardez la lecture silencieuse comme valeur par défaut pour les vidéos intégrées dans la documentation. Ajoutez une narration lorsqu'elle explique matériellement le timing, la causalité ou le contexte que des annotations visuelles concises ne peuvent pas.
• Écrivez et synchronisez la narration avec l'image verrouillée. Les sous-titres ou une transcription textuelle doivent préserver la même information, et la vidéo doit rester compréhensible lorsqu'elle est muette.
• Utilisez une voix clonée ou synthétique modelée sur une personne identifiable uniquement avec l'autorisation explicite de cette personne. Divulguez que la voix est synthétique dans la page environnante ou les crédits ; ne la présentez pas comme un enregistrement authentique en direct.
• Gardez les échantillons vocaux, les fichiers de modèle et les intermédiaires générés en dehors du dépôt sauf si l'utilisateur choisit explicitement de les publier. Considérez l'autorisation de créer une démo narrée comme limitée à ce livrable, et non comme un consentement permanent pour une future génération vocale.
• Ré-exécutez la QA de livraison après le multiplexage de l'audio. Vérifiez l'intelligibilité, les niveaux, la synchronisation, les sous-titres, la disposition des canaux, et que le conteneur final respecte toujours la spécification de livraison vidéo.

Examiner le livrable décodé

Exécutez le helper fourni sur le fichier final, pas sur un intermédiaire :

.agents/skills/product-demo-recording/scripts/qa-video.sh \
  chemin/vers/final.mp4 /tmp/qa-video-demo --interval 2 4 5 6

Le helper écrit les métadonnées du flux, une planche contact décodée séquentiellement, et les images de début/milieu/fin ainsi que les horodatages demandés au format JPEG. Utilisez un répertoire de sortie frais.

Effectuez ensuite toutes ces vérifications :

1. Regardez la vidéo finale entière à vitesse normale.
2. Inspectez la planche contact pour chaque changement d'application, modal, plan, annotation et état de résultat.
3. Inspectez les images exactes immédiatement avant, à et après chaque limite de montage. Ajoutez toujours les horodatages nommés dans les retours de revue ; ne supposez pas que les images adjacentes sont représentatives.
4. Confirmez qu'il n'y a pas d'autres applications, zones de bureau, notifications, identifiants, données privées, bords rognés, chrome de navigateur partiel, bordures noires bizarres ou contrôles obstrués.
5. Confirmez que le texte est lisible, le placement du pointeur calme, les transitions propres, et que le résultat visible correspond à la documentation environnante.
6. Vérifiez le codec, le format de pixel, les dimensions, la fréquence d'images, la durée, le choix audio et l'exigence fast-start par rapport à la spécification de livraison.

Ne décrivez pas l'enregistrement comme examiné tant que ces vérifications n'ont pas été effectuées sur le fichier exact qui sera commité.

Livrer et conserver délibérément

• Stagiez uniquement l'actif final et les modifications de documentation intentionnelles. N'ajoutez pas de prises brutes, d'identifiants, de profils navigateur ou d'exports QA.
• Conservez les prises brutes jusqu'à ce que le fichier final soit examiné et commité ou téléchargé en toute sécurité. Suivez ensuite le choix de conservation de l'opérateur ; supprimez les captures temporaires sensibles explicitement plutôt qu'avec des motifs de suppression larges.
• Dans la transition, indiquez ce qui a été montré, les propriétés techniques finales, les horodatages qui ont été inspectés et où se trouve l'actif final.