Montrer plutôt qu'écrire : captures annotées, terminal enregistré, alt

Une image n'est utile que si elle montre ce que le texte ne sait pas dire : où cliquer dans une interface, ou comment une session évolue dans le temps. Pour une commande et sa sortie, un bloc de code reste meilleur qu'une capture : il se copie, se cherche et se lit à voix haute. Cette leçon donne une grille pour choisir, apprend à réaliser une capture annotée et un terminal enregistré sans fuiter de secret, puis à écrire le texte alternatif qui rend l'image utile à tous les lecteurs.

Ce que vous allez apprendre

• Choisir entre bloc de code, capture annotée et enregistrement
• Réaliser une capture cadrée, annotée, allégée et sans secret
• Enregistrer une session de terminal avec asciinema et la convertir en GIF
• Écrire un texte alternatif pour une capture, un GIF et une image décorative
• Diagnostiquer les défauts fréquents : capture périmée, illisible, secret visible

Les prérequis sont ceux du niveau : savoir éditer un fichier texte, faire un commit et une pull request. La syntaxe d'insertion d'une image est dans le guide Markdown.

Quand faut-il une image, et quand vaut-il mieux du texte ?

Une image ne sert que lorsque le lecteur a besoin d'un repère visuel : repérer un bouton dans une console, suivre une session qui évolue. Sinon le texte gagne : il est copiable, cherchable et lisible par un lecteur d'écran, le logiciel qui lit une page à voix haute aux personnes malvoyantes.

Le schéma ci-dessous pose trois questions dans l'ordre. Suivez-le de haut en bas : la première décide si le contenu doit être copié, la deuxième si le déroulement dans le temps compte, la troisième si le lecteur doit repérer un élément à l'écran.

Montrer ou écrire : trois questions, du plus copiable au plus visuel. Source · SVG

Échap pour fermer, + et − pour zoomer, défilement pour se déplacer. 100 % − Ajuster + Fermer

Le même verdict en tableau, avec ce que chaque support coûte :

Besoin du lecteur	Meilleur support	Coût de maintenance
Copier une commande, comparer une sortie	Bloc de code	Très faible
Repérer un bouton ou un menu dans une interface	Capture annotée	Élevé : à refaire quand l'interface change
Voir une installation interactive ou une interface en mode texte	Enregistrement de terminal	Moyen : à rejouer quand les versions changent
Comprendre une architecture ou un flux	Schéma écrit en code	Faible : le source se relit en diff

Glissez pour voir

Voici un exemple concret. Pour montrer git --version et uname -s, un GIF (une image animée) pèse environ 7,8 Ko et ne se copie pas, alors que le bloc de code ci-dessous pèse quelques dizaines d'octets, se copie et se cherche. La mesure vient d'un essai réel du 2026-10-13, sur un GIF de 790 x 560 pixels.

git --version
# git version 2.43.0
uname -s
# Linux

Gardez le texte pour ce qui se tape ou se lit, réservez l'image à ce qui se voit. Un schéma d'architecture s'écrit en code : c'est le sujet d'une autre leçon.

Comment réaliser une bonne capture d'écran annotée ?

Une bonne capture répond à une seule question : où le lecteur doit-il regarder ? Quatre gestes y suffisent : cadrer, masquer, annoter, alléger. L'outil de capture de votre système (touche Impression d'écran sous Windows et Linux, Maj+Commande+4 sous macOS) convient très bien : la méthode compte plus que l'outil.

Cadrer la zone utile. Capturer la fenêtre entière noie le détail dans les pixels inutiles et rend le texte minuscule sur un téléphone. Recadrez autour de la zone concernée avec une petite marge. Dans l'essai, passer d'une page de 1000 x 700 pixels à la seule zone utile a réduit le fichier de 36 629 à 9 910 octets (-73 %).

Masquer les secrets avant la capture. Un jeton, un mot de passe, une clé d'API, une adresse interne ou un nom de client ne doivent jamais figurer dans les pixels. Remplacez-les par des valeurs factices (un faux jeton de type tok_FAKE_0123456789abcdef) ou masquez-les avant de prendre la capture. Flouter après coup est risqué : un flou léger laisse parfois le texte lisible, et la version non floutée peut rester dans l'historique Git si elle a été commitée.

Annoter avec parcimonie. Un encadré rouge autour de l'élément, une flèche, un numéro par étape, reliés à une liste dans le texte : « 1. Cliquer sur Créer un jeton ». Pas plus de trois ou quatre repères par image, tous retrouvés dans le texte : l'image aide à trouver, le texte dit quoi faire.

Nommer, ranger, alléger. Nommez le fichier d'après son contenu (creer-un-jeton.png, pas Capture d'écran 2026-10-13.png) et rangez-le à côté de la page qui l'utilise, pour qu'un déplacement de la page déplace aussi ses images. Une capture à aplats de couleur gagne à être allégée : dans l'essai, une capture annotée de 9 566 octets est tombée à 4 063 octets (-58 %) en PNG limité à 32 couleurs, et à 5 194 octets (-46 %) en WebP avec perte. Ces images étaient très simples : n'extrapolez pas ces chiffres à une vraie console web.

Peut-on automatiser les captures ?

Oui, et c'est le meilleur remède au vieillissement. Une capture faite à la main se refait à la main à chaque changement d'interface ; une capture produite par un script se régénère d'un geste. C'est une option pour les équipes qui maintiennent beaucoup de captures : si vous capturez à la main avec l'outil de votre système, vous avez déjà tout ce qu'il faut, et cette section peut attendre.

Playwright, une bibliothèque qui pilote un navigateur par programme, sait capturer une zone et masquer des éléments. L'essai a été fait avec Playwright 1.62.0 et Chromium 151, dans un fichier capture.mjs lancé par node capture.mjs. Le script ouvre une page HTML locale, désigne la zone par un sélecteur (#cle), désigne le secret (#jeton, un faux jeton) puis capture. Remplacez le chemin et les deux sélecteurs par ceux de votre propre page :

import { chromium } from 'playwright-core';

const browser = await chromium.launch();
const page = await browser.newPage({ viewport: { width: 1000, height: 700 } });
await page.goto('file:///chemin/vers/page.html');

// Capture limitée à la zone « #cle », jeton noirci dans l'image
await page.locator('#cle').screenshot({
  path: 'creer-un-jeton.png',
  mask: [page.locator('#jeton')],
  maskColor: '#000000',
});

await browser.close();

Le script, rejoué avec le paquet playwright-core et le Chromium déjà présent dans le cache de la machine d'essai, a produit creer-un-jeton.png (554 x 176 pixels, environ 6 Ko). Si chromium.launch() ne trouve aucun navigateur, installez-en un (npx playwright install chromium, non rejoué ici) ou passez executablePath avec le chemin d'un Chromium local.

Le masque est appliqué dans l'image au moment de la capture : le texte du jeton n'est pas dans les pixels. Sans maskColor, le masque est magenta (#FF00FF). Limite à connaître : il ne couvre que des éléments désignés dans la page, pas un secret affiché dans un canvas ou dans un terminal.

Pour les annotations (encadré, flèche, légende), ImageMagick les dessine après la capture. La commande ci-dessous a été jouée avec ImageMagick 6.9, dont l'exécutable s'appelle convert (avec la version 7 ce serait magick, non testé). Elle produit creer-un-jeton-annote.png.

Les nombres de cette commande ne valent que pour la capture d'essai (un bouton à cet endroit précis de l'image). Sur votre capture, ils seront faux : à vous de les remplacer. Chaque couple x,y est une position en pixels depuis le coin supérieur gauche de l'image recadrée. Pour les relever, ouvrez votre image dans n'importe quel éditeur ou visionneuse qui affiche la position du pointeur, ou demandez la taille de l'élément à Playwright (boundingBox()) :

convert creer-un-jeton.png -fill none -stroke '#e11' -strokewidth 4 \
  -draw "rectangle 13,116 164,162" \
  -draw "line 300,150 170,140" \
  -fill '#e11' -draw "polygon 168,140 184,132 184,148" \
  -stroke none -pointsize 16 -draw "text 305,155 '1. Cliquer ici'" creer-un-jeton-annote.png

Ici, rectangle encadre le bouton (coin haut gauche puis coin bas droit), line et polygon dessinent la flèche, text pose le repère numéroté. Pour des enregistrements de terminal scriptés, le site a aussi un guide sur VHS.

Comment enregistrer un terminal avec asciinema ?

Quand la démonstration se déroule dans le temps (une installation interactive, une interface en mode texte, une sortie qui évolue), asciinema enregistre la session non pas comme une vidéo, mais comme un fichier texte qui note chaque affichage avec son horaire. Le résultat est léger et rejouable. La version relevée à la source le 2026-10-13 est asciinema 3.2.1 (publiée le 2026-06-16), réécrite en Rust. L'ancienne branche 2.x en Python reste disponible sur PyPI mais n'est plus la voie principale.

La chaîne complète tient en quelques fichiers et deux outils. Suivez-la de gauche à droite : un script que l'on enregistre, un fichier .cast en texte clair, puis deux sorties possibles, le GIF produit par agg ou le lecteur web. Dans les deux cas, la page garde un bloc de code en transcription à côté de l'image.

Source · SVG

Échap pour fermer, + et − pour zoomer, défilement pour se déplacer. 100 % − Ajuster + Fermer

Comment l'installer sans curl | sh ?

Le plus sûr est le gestionnaire de paquets de votre distribution. À défaut, téléchargez le binaire de la release et vérifiez sa somme SHA-256, une empreinte de 64 caractères hexadécimaux qui change si le fichier est altéré, avant de l'exécuter : GitHub publie ce digest pour chaque fichier de release. Les commandes ci-dessous ont été jouées sur Linux x86_64, sans droits administrateur.

curl -sSL -o asciinema https://github.com/asciinema/asciinema/releases/download/v3.2.1/asciinema-x86_64-unknown-linux-gnu
sha256sum asciinema
# 1b405bbda565b33c3c4718de67fedc3535580603c0694b1ff3fb04f363430a20  asciinema
chmod +x asciinema
./asciinema --version
# asciinema 3.2.1

La somme affichée doit être identique au digest de l'asset sur la page de la release v3.2.1. Si elle diffère, supprimez le fichier. Le binaire est statique : il s'exécute tel quel, sans dépendance à installer. Les commandes suivantes écrivent asciinema et agg sans ./. Pour cela, placez les binaires dans un dossier du PATH, la liste des dossiers où le shell cherche les commandes (par exemple install -m 755 asciinema ~/.local/bin/, si ce dossier y figure). Sinon, préfixez chaque appel par ./.

Comment enregistrer une session ?

La commande asciinema rec lance l'enregistrement. Pour une documentation reproductible, on enregistre une commande précise plutôt qu'un shell libre : le lecteur voit exactement ce que vous avez prévu, sans faute de frappe ni secret oublié. Créez d'abord le petit script demo.sh à enregistrer et rendez-le exécutable (sans cela, la commande échoue avec Permission denied, visible dans le .cast et par le code de sortie 126 avec --return) :

cat > demo.sh <<'EOF'
#!/usr/bin/env bash
echo '$ git --version'
git --version
sleep 0.5
echo '$ uname -s'
uname -s
sleep 0.5
echo 'Terminé'
EOF
chmod +x demo.sh

Voici ensuite l'appel joué, qui l'enregistre dans un terminal de 80 colonnes sur 24 lignes. Il crée le fichier demo.cast.

asciinema rec --headless --overwrite --window-size 80x24 \
  --title "Demo lab" --return -c ./demo.sh demo.cast

Les options utilisées : -c (la commande à enregistrer), --headless (pas de terminal réel requis, utile en script ou en CI, l'exécution automatique sur un serveur), --overwrite (sans lui, un fichier existant fait échouer la commande avec file exists), --window-size (taille fixe, donc rendu stable), --title et --return. Cette dernière renvoie le code de sortie de la commande enregistrée ; sans elle, asciinema termine toujours avec 0, même si la commande a échoué.

Le fichier produit est au format asciicast v3 (le format d'enregistrement d'asciinema, extension .cast), du JSON ligne par ligne. La première ligne est un en-tête, puis chaque ligne est un événement [intervalle, code, données]. En v3, le premier nombre est l'intervalle depuis l'événement précédent (en v2, c'était le temps écoulé depuis le début). Le code o désigne la sortie affichée.

{"version":3,"term":{"cols":80,"rows":24},"timestamp":1791889056,"command":"./demo.sh","title":"Demo lab","env":{"SHELL":"/usr/bin/zsh"}}
[0.003, "o", "$ git --version\r\n"]
[0.002, "o", "git version 2.43.0\r\n"]
[0.502, "o", "$ uname -s\r\n"]

Comment rejouer, et attention aux secrets ?

asciinema play demo.cast rejoue la session en respectant le rythme, avec -s pour la vitesse et -i pour plafonner les silences. Il exige un vrai terminal : sans terminal (script, CI), il échoue avec No such device or address. Ouvrez alors le fichier avec un éditeur : c'est du texte.

C'est justement le piège principal : un .cast contient tout en clair. Le lab l'a vérifié en enregistrant echo tok_FAKE_0123456789abcdef : la chaîne apparaît à la fois dans l'en-tête (champ command) et dans l'événement de sortie. L'option --capture-input enregistre en plus la frappe, mots de passe compris. Il n'existe pas de « flou » pour un .cast : il faut ne jamais afficher le secret (variables factices, script dédié) ou éditer le fichier texte avant de le publier. Relisez toujours le .cast avant de le commiter.

Comment obtenir un GIF, et que permet le lecteur web ?

L'outil agg (version 1.9.0, publiée le 2026-05-29) convertit un .cast en GIF animé, que l'on insère comme n'importe quelle image. Il s'installe de la même façon que asciinema : binaire de release, somme vérifiée (f111e315cd71056b116302342553dd765b7297579ed511f111d0cedb442aeda6 pour la version 1.9.0 sous Linux x86_64).

agg demo.cast demo.gif

Sur l'exemple de deux commandes, le GIF obtenu pèse 7 799 octets (790 x 560 pixels, 3 images). agg ne produit que du GIF : demander demo.svg écrit un GIF mal nommé, un piège réel constaté. Ses options (--theme, --font-size, --speed, --idle-time-limit, --fps-cap) règlent le rendu, et la doc d'agg propose gifsicle pour alléger le résultat (non testé ici). Les rendus dépendent des polices installées sur la machine.

Un GIF est une image de texte : il ne se copie pas et n'a aucun équivalent textuel. Si le site peut embarquer du JavaScript, asciinema-player (version npm 3.17.0 relevée le 2026-10-13) lit le .cast directement dans la page, avec du vrai texte sélectionnable. Il n'a pas été intégré dans l'essai : c'est un choix de site, avec du JavaScript tiers à accepter, pas un défaut.

Que fait asciinema upload ?

La commande asciinema upload envoie le .cast à asciinema.org (ou à une instance auto-hébergée avec --server-url) et renvoie un lien. Elle n'a pas été exécutée pour cette leçon : ce qui suit vient de l'aide et de la documentation officielle. Le point à retenir est que tout le contenu du .cast quitte votre machine : sortie, commande, variable SHELL, et frappe si --capture-input était actif. Selon --visibility, l'enregistrement est public (listé et cherchable), unlisted (accessible par l'URL seule) ou private. Cette étape est facultative : un fichier dans le dépôt et un lecteur auto-hébergé suffisent.

Comment écrire un bon texte alternatif ?

Le texte alternatif (attribut alt) est l'équivalent textuel d'une image : un lecteur d'écran le lit, et il s'affiche si l'image ne charge pas. Le critère 1.1.1 « Non-text Content » des WCAG 2.2 (niveau A) exige que tout contenu non textuel ait une alternative textuelle qui remplit le même rôle, sauf exceptions listées, dont la décoration pure. La leçon Écrire clair a posé la règle de base (dire ce que l'image apprend) ; voici les cas particuliers.

Le W3C WAI, dans son tutoriel sur les images, distingue plusieurs catégories selon la fonction de l'image :

Catégorie	Que mettre dans alt
Informative	Une courte description qui donne l'information essentielle
Décorative	alt="" : l'image est ignorée par les lecteurs d'écran
Fonctionnelle (lien, bouton)	La fonction ou la destination, pas l'apparence
Image de texte	Le même texte que l'image (hors logo, éviter)
Complexe (graphique, diagramme)	Une description courte, plus une description longue ailleurs dans la page

Glissez pour voir

L'arbre de décision du W3C WAI (mis à jour le 13 mai 2024) se résume à des questions dans cet ordre : l'image contient-elle du texte, est-elle dans un lien ou un bouton, apporte-t-elle du sens, est-elle purement décorative ? Pour le décoratif, retenez une règle précise de cette page : ne jamais omettre l'attribut. S'il manque, certains lecteurs d'écran lisent le nom du fichier. On écrit donc alt="".

En Markdown, le texte entre crochets est l'alt :

![Page Jeton d'accès avec le bouton Créer un jeton entouré en rouge ; le jeton est masqué.](./creer-un-jeton.png)

Cet exemple est une proposition, pas une formule du W3C. Il dit ce que l'image apporte (où est le bouton, que le jeton est masqué), sans répéter les mots « capture d'écran » que le lecteur d'écran annonce déjà. Le geste à accomplir reste écrit dans le texte voisin.

Pour un GIF de terminal, l'alt décrit ce que la session montre, par exemple « Terminal : git --version affiche git version 2.43.0, puis uname -s affiche Linux ». Comme un GIF n'a pas d'équivalent copiable, doublez l'enregistrement d'une transcription : le bloc de code de la commande et de sa sortie, juste à côté. C'est ce bloc qui sera copié, cherché et lu, le GIF ne sert qu'à montrer le déroulé.

Ces textes n'ont pas été éprouvés avec un lecteur d'écran réel : relisez les vôtres en les écoutant, ou en cachant l'image pour vérifier que la page reste compréhensible.

Quels défauts fréquents faut-il traquer ?

Le tableau donne, pour les défauts les plus fréquents, le symptôme vu par le lecteur, la cause probable et la correction à appliquer avant de fusionner la pull request.

Symptôme	Cause probable	Correction
Texte de la capture illisible sur téléphone	Fenêtre entière capturée, zoom trop petit	Recadrer sur la zone utile, agrandir la police avant de capturer
Un jeton ou une adresse interne est visible	Secret non masqué avant la capture, ou dans un .cast	Valeurs factices, masque à la capture, relire le .cast, régénérer
La capture ne correspond plus à l'écran	Interface modifiée depuis	Refaire la capture, ou l'automatiser et la dater
GIF de plusieurs mégaoctets	Session longue, grande fenêtre, nombreuses images	Réduire la zone, plafonner les silences, gifsicle, ou le lecteur web
alt valant « image » ou « capture d'écran »	Texte alternatif écrit pour cocher la case	Décrire le sens, ou alt="" si l'image est décorative
Le fichier est introuvable après déplacement de la page	Image rangée dans un dossier global	La ranger à côté de la page

Glissez pour voir

Un test simple pour finir : relisez votre page en désactivant les images. Si vous comprenez encore où cliquer et quoi taper, la page est bonne. Sinon, l'image portait seule une information qui aurait dû être écrite.

À retenir

• Texte d'abord : une commande et sa sortie vont dans un bloc de code, copiable, cherchable et lisible par un lecteur d'écran.
• Image quand il faut voir : une capture annotée pour repérer un élément d'interface, un enregistrement pour un déroulé dans le temps.
• Cadrer, masquer, annoter, alléger : la zone utile, les secrets masqués avant la prise, trois ou quatre repères numérotés, un fichier léger rangé à côté de la page.
• Une capture coûte cher à maintenir : l'automatiser, ou accepter de la refaire à chaque changement d'interface.
• Un .cast asciinema est du texte en clair : secrets et frappe compris ; asciinema upload envoie tout cela hors de la machine.
• agg ne produit que du GIF, qui n'a aucun équivalent textuel : doubler d'un bloc de code ou passer au lecteur web.
• Alt utile : décrire le sens (WCAG 1.1.1), alt="" pour le décor, jamais d'attribut absent, jamais « image » ou « capture d'écran ».

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

×

📖 Voir la documentation →