Lire documents et médias

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

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

Documents pris en charge

Le texte structuré (JSON, YAML, CSV, logs, diffs, traces de pile, notebooks…) passe par la même commande et est compacté selon son format. Le code source est renvoyé tel quel.

Interroger plutôt que lire

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

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 :

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

Images

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

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.

--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.

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.

Voir aussi

• web et search
• Récupérer une sortie repliée
• Compaction des sorties et stash
• map, skeleton, query, impact, semantic