From 7390d36b884cea0c0878f0fd5db866ed9f5c3582 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 21 Aug 2026 19:05:16 +0000 Subject: [PATCH] docs: state what conversion actually does to assets at transfer The sentence "formats marked with asterisks are automatically converted when transferring to the device" was added upstream in November 2019 together with the markers it explains (MP3**, OGG/Vorbis**, PNG**, JPEG**). The "rewrite readme" commit of 24 May 2021 removed the markers and kept the sentence, so all four lists -- images and audio, in both READMEs -- have since pointed at marks that are not there. The reader could no longer tell which formats are converted and which are not. Restoring the asterisks would restore an approximation. What triggers a conversion in PackAssetsCompression depends on the pack format being written, and BMP is not exempt: on the FS path a 24-bit BMP is re-encoded into 4-bit/RLE, and an MP3 that is not mono/44100 Hz is re-encoded too. Conversely the Raw path writes a BMP or a WAVE out as it stands, without checking bit depth or sample parameters. So state it as a paragraph rather than a mark: what each pack format carries, that anything else is converted while the transfer is prepared, and that the Raw path enforces nothing -- meeting the listed constraints is the user's job. The format lists themselves are left as they were, minus the dangling parenthetical. The upstream-README inventory in "Relationship to upstream" gains this divergence, so the file keeps telling the truth about itself. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01TkkVuQpm7gwzfT43tyoPR3 --- README.md | 30 ++++++++++++++++++++++++------ README_fr.md | 31 +++++++++++++++++++++++++------ 2 files changed, 49 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index d493ad34..8af0671b 100644 --- a/README.md +++ b/README.md @@ -141,8 +141,10 @@ maintained here. The rest of this file is the upstream README, kept as it was except where it would say something untrue of this fork. What is annotated: the release badge and the download link, which refer to -upstream builds; the clone URL, which is upstream's repository and not this one; and the rule -deciding which file is transferred, which this fork changed. Nothing else in it is edited. +upstream builds; the clone URL, which is upstream's repository and not this one; the rule deciding +which file is transferred, which this fork changed; and the asset format lists, whose asterisk +markers were dropped in an upstream rewrite while the sentence explaining them stayed, so that the +text described markers no longer present. Nothing else in it is edited. --- @@ -242,8 +244,7 @@ The editor supports several file formats for audio and image assets. ##### Images -Image files may use the following formats (formats marked with asterisks are automatically converted when transferring -to the device) : +Image files may use the following formats: * PNG * JPEG * BMP (24-bits) @@ -253,14 +254,31 @@ the screen being behind the plastic cover. Bear in mind that the color of the co ##### Audio -Audio files may use the following formats (formats marked with asterisks are automatically converted when transferring -to the device) : +Audio files may use the following formats: * MP3 * OGG/Vorbis * WAVE (signed 16-bits, mono, 32000 Hz) MP3 and OGG files are expected to be sampled at 44100Hz. +##### Conversion when transferring + +The formats above are what the **editor** accepts. What reaches the **device** is narrower, and +depends on the pack format being transferred: + +* a `Raw` pack (firmware v1.x) carries 24-bit BMP images and WAVE audio (signed 16-bits, mono, + 32000 Hz); +* an `FS` pack (firmware v2.x) carries 4-bit RLE-encoded BMP images and MP3 audio (mono, 44100 Hz). + +Assets not already in the target form are converted while the transfer is prepared. This is not +limited to the compressed formats: transferring to an `FS` pack re-encodes a 24-bit BMP into a +4-bit RLE BMP, and re-encodes an MP3 that is not mono/44100 Hz (an MP3 kept as it is has its ID3 +tags removed). + +Conversely, on the `Raw` path a BMP or a WAVE file is written out as it stands, its bit depth and +its sample parameters unchecked. Meeting the constraints listed above is therefore yours to do, not +something the conversion will fix. + #### Wiki More information, including an illustrated usage guide courtesy of [@appenzellois](https://github.com/appenzellois), diff --git a/README_fr.md b/README_fr.md index 3fb7c593..c83ee611 100644 --- a/README_fr.md +++ b/README_fr.md @@ -156,8 +156,10 @@ redevient actif ; d'ici là, les changements ci-dessus sont maintenus ici. La suite de ce fichier est le README amont, conservé tel quel sauf là où il dirait quelque chose de faux pour ce fork. Ce qui est annoté : le badge de release et le lien de téléchargement, qui -désignent des constructions amont ; l'URL de clonage, qui est le dépôt amont et non celui-ci ; et la -règle déterminant quel fichier est transféré, que ce fork a changée. Rien d'autre n'y est modifié. +désignent des constructions amont ; l'URL de clonage, qui est le dépôt amont et non celui-ci ; la +règle déterminant quel fichier est transféré, que ce fork a changée ; et les listes de formats +d'assets, dont les astérisques ont disparu lors d'une réécriture amont alors que la phrase qui les +expliquait est restée, décrivant ainsi des marqueurs absents. Rien d'autre n'y est modifié. --- @@ -258,8 +260,7 @@ L'éditeur supporte plusieurs formats de fichiers pour l'audio et les images. ##### Images -Les fichiers image peuvent utiliser les formats suivants (les formats marqués d'astérisques sont automatiquement -convertis lors du transfert vers l'appareil) : +Les fichiers image peuvent utiliser les formats suivants : * PNG * JPEG * BMP (24-bits) @@ -270,14 +271,32 @@ couleur du boîtier peut changer. ##### Audio -Les fichiers audio peuvent utiliser les formats suivants (les formats marqués d'astérisques sont automatiquement -convertis lors du transfert vers l'appareil) : +Les fichiers audio peuvent utiliser les formats suivants : * MP3 * OGG/Vorbis * WAVE (16-bits signés, mono, 32000 Hz) Les fichiers MP3 et OGG doivent, eux, être échantillonnés à 44100Hz. +##### Conversion lors du transfert + +Les formats ci-dessus sont ceux qu'accepte l'**éditeur**. Ce qui arrive sur l'**appareil** est plus +restreint, et dépend du format de pack transféré : + +* un pack `Raw` (firmware v1.x) contient des images BMP 24 bits et de l'audio WAVE (16 bits signés, + mono, 32000 Hz) ; +* un pack `FS` (firmware v2.x) contient des images BMP 4 bits encodées en RLE et de l'audio MP3 + (mono, 44100 Hz). + +Les fichiers qui ne sont pas déjà dans la forme attendue sont convertis au moment de préparer le +transfert. Cela ne concerne pas que les formats compressés : vers un pack `FS`, un BMP 24 bits est +ré-encodé en BMP 4 bits/RLE, et un MP3 qui n'est pas mono/44100 Hz est ré-encodé lui aussi (un MP3 +conservé tel quel voit ses tags ID3 retirés). + +À l'inverse, sur le chemin `Raw`, un BMP ou un WAVE est écrit tel qu'il se présente, sans que sa +profondeur de bits ni ses paramètres d'échantillonnage soient vérifiés. Respecter les contraintes +listées plus haut vous revient donc ; ce n'est pas la conversion qui le fera. + #### Wiki Pour plus d'informations, y compris un guide d'utilisation illustré (merci à