# Lire documents et médias

> tokenade read transforme PDF, fichiers Office, images, audio et vidéo en texte exploitable, et répond à vos questions sans charger tout le fichier.

Source: https://tokenade.net/fr/docs/read-documents-media · Updated: 2026-10-07

`tokenade read` est le point d'entrée unique pour le contenu : donnez-lui un fichier (ou `-` pour l'entrée standard), il détecte le format et renvoie un texte exploitable par votre agent. Pour les documents et les médias, cela veut dire texte extrait, OCR ou transcription au lieu d'octets bruts. Ajoutez `--prompt` et vous n'obtenez que les passages qui répondent à vos questions.

## Utilisation

```text
tokenade read <file|-> [--prompt "q1, q2"] [--lines A-B] [--cmd <command>] [--frames [N]]
```

| Option | Effet |
| --- | --- |
| `--prompt "q1, q2"` | Ne renvoie que les passages qui répondent. Plusieurs questions séparées par des virgules en un seul appel. Aussi `--question`, `-q` |
| `--lines A-B` | Ne lit que cette plage, numérotée à partir de 1, bornes incluses. `A-` va jusqu'à la fin, `-B` part du début, `A` désigne une ligne. Une plage au-delà de la fin est refusée |
| `--cmd <command>` | Indique la commande qui a produit le texte, pour utiliser le bon compacteur |
| `--frames [N]` | Vidéo uniquement : ajoute des images fixes dédupliquées (8 par défaut, 32 au maximum) |

L'entrée standard demande `-` : `curl -s https://api.example.com/x | tokenade read -`.

## Documents pris en charge

| Famille | Extensions |
| --- | --- |
| PDF | `.pdf` (les pages scannées passent par l'OCR quand c'est possible) |
| Word | `.docx` `.docm` `.dotx` `.dotm` `.doc` `.dot` `.rtf` |
| Excel | `.xlsx` `.xlsm` `.xltx` `.xltm` `.xls` `.xlsb` |
| PowerPoint | `.pptx` `.pptm` `.potx` `.potm` `.ppsx` `.ppsm` `.ppt` `.pps` `.pot` |
| OpenDocument | `.odt` `.ott` `.ods` `.ots` `.odp` `.otp` `.odg` `.otg`, versions XML plates `.fodt` `.fods` `.fodp` `.fodg` |
| Livres et e-mails | `.epub` `.fb2` `.msg` |
| Images | `.png` `.jpg` `.jpeg` `.gif` `.webp` `.bmp` `.tif` `.tiff` `.ico` et autres formats courants |
| Audio | `.mp3` `.wav` `.m4a` `.flac` `.ogg` `.opus` `.aac` et autres conteneurs courants |
| Vidéo | `.mp4` `.mkv` `.mov` `.webm` `.avi` et autres conteneurs courants |

Le texte structuré (JSON, YAML, CSV, logs, diffs, traces de pile, notebooks…) passe par la même commande et est compacté selon son format. Un fichier source que vous allez probablement modifier (moins de 20 000 tokens environ, dans un dépôt git) est renvoyé tel quel ; les autres fichiers source de plus de 3 Ko reviennent sans leurs commentaires, sous un bandeau `[tokenade:read-code-strip …]`, et le fichier sur disque n'est jamais modifié. `TOKENADE_NO_CODE_STRIP=1` désactive ce retrait.

## Interroger plutôt que lire

Un document court est renvoyé en entier. Un document long gagne à être interrogé :

```bash
tokenade read contract.pdf --prompt "termination notice period, governing law, liability cap"
```

Chaque réponse arrive sous son propre titre, en un seul aller-retour. Plusieurs questions dans un même appel, c'est l'option la moins chère en tokens.

Chaque partie séparée par une virgule doit compter au moins 3 mots. Une partie plus courte est fusionnée avec sa voisine, et la sortie vous le signale :

```text
[tokenade] "due date" is too short to stand on its own as a question (1 of the 2 comma-separated parts fall under 3 words), so it was folded into its neighbour …
```

Pour parcourir un gros fichier texte morceau par morceau, utilisez `--lines` :

```text
$ tokenade read --lines 1-3 PATCHNOTES.md
[tokenade: lines 1-3 of 2108]
# Tokenade — what's new
## 2.0.1
```

## Images

Si `tesseract` est installé, `read` renvoie le texte visible sur l'image :

```text
$ tokenade read dashboard.png
[tokenade:image 890x817] text read by OCR (tesseract) — recognition can misread characters; the image itself is at dashboard.png:
…
```

Choisissez la langue de l'OCR avec `TOKENADE_OCR_LANG` (`eng` par défaut ; tout pack de langue tesseract installé, par exemple `fra`). Les pages scannées d'un PDF passent aussi par l'OCR quand `pdftoppm` et `tesseract` sont tous deux installés (20 premières pages marquées).

Quand votre agent lit lui-même une image dans Claude Code, le hook Read lui sert une copie réduite si le grand côté dépasse 1024 px (la valeur par défaut). Mettez `TOKENADE_IMAGE_MAX_EDGE=0` pour garder la pleine résolution.

## Audio et vidéo

Un fichier média n'est jamais décodé comme du texte. `read` renvoie ce qu'est le fichier (durée, codecs, pistes, via `ffprobe`) et ce qui s'y dit, à partir de la source la moins coûteuse disponible :

1. un fichier de sous-titres à côté du média (`talk.mp4` → `talk.srt`, `.vtt`, `.ass`, `.ssa`) ;
2. une piste de sous-titres intégrée au conteneur (nécessite `ffmpeg`) ;
3. une transcription locale avec `whisper`, ou `whisper-cli` avec `ffmpeg`.

La transcription n'est lancée que par la commande `tokenade read`, jamais dans un hook d'agent : un hook ne renvoie que la courte description. Les transcriptions sont mises en cache selon le contenu ; un fichier renommé ou copié n'est donc pas retranscrit.

| Variable | Défaut | Effet |
| --- | --- | --- |
| `TOKENADE_WHISPER_MODEL` | `base` | Modèle Whisper : `tiny` pour la vitesse, `small` ou `medium` pour la précision |
| `TOKENADE_WHISPER_TIMEOUT_SECS` | `900` | Durée maximale d'une transcription |

`--frames` extrait des images fixes réparties sur la durée (dédupliquées) dans le stash, pour que l'agent puisse les regarder. Chaque image coûte des tokens de vision à la lecture, d'où un défaut de 8.

## Outils optionnels

Aucun n'est obligatoire. Sans eux, `read` identifie quand même le fichier, refuse de le gonfler et indique quel binaire débloquerait davantage.

| Outil | Débloque |
| --- | --- |
| `tesseract` | OCR des images et des pages PDF scannées |
| `pdftoppm` | Rendu des pages PDF scannées pour l'OCR |
| `ffprobe` | Durée, codecs et pistes des fichiers média |
| `ffmpeg` | Sous-titres intégrés, images fixes, entrée de `whisper-cli` |
| `whisper` ou `whisper-cli` | Transcriptions locales |

## Codes de sortie et pièges

- Sortie `0` en cas de succès ; `2` pour une erreur d'utilisation, par exemple une plage `--lines` au-delà de la fin du fichier.
- Les secrets sont masqués dans toute sortie (par exemple `Routing: <redacted>`), quel que soit le compacteur choisi.
- Si la compaction rendait la sortie plus grosse que l'entrée, les octets bruts reviennent avec l'étiquette `passthrough_inflated`.
- Pour imposer le compacteur d'une commande à une sortie déjà capturée, utilisez `--cmd`, ou lancez la commande d'origine via [`tokenade wrap`](https://tokenade.net/fr/docs/wrap-raw-filter).

## Voir aussi

- [web et search](https://tokenade.net/fr/docs/web-search)
- [Récupérer une sortie repliée](https://tokenade.net/fr/docs/expand-ref-disclose)
- [Compaction des sorties et stash](https://tokenade.net/fr/docs/compaction)
- [map, skeleton, query, impact, semantic](https://tokenade.net/fr/docs/code-intelligence)
