docs: state what conversion actually does to assets at transfer - #39
Merged
antoinevalentinHA merged 1 commit intoAug 21, 2026
Merged
Conversation
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 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01TkkVuQpm7gwzfT43tyoPR3
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The regression
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 — the list then read
MP3\*\*,OGG/Vorbis \*\*, and on the image sidePNG\*\*,JPEG\*\*. The rewrite readme commit of 24 May 2021 removed the markers and kept the sentence.All four lists are affected — images and audio, in
README.mdand inREADME_fr.md. Since then the text points at marks that are not there: a reader cannot tell which formats are converted and which the device consumes as they are. The information is not badly presented, it is absent.Why not just put the asterisks back
Restoring them would restore an approximation. In
PackAssetsCompression, what triggers a conversion depends on the pack format being written, and BMP is not exempt:Raw(firmware v1.x,withUncompressedAssets) — PNG/JPEG become 24-bit BMP, OGG/MP3 become WAVE. A BMP or a WAVE is written out as it stands; its bit depth and sample parameters are never checked.FS(firmware v2.x,withPreparedAssetsFirmware2dot4) — everything becomes 4-bit RLE BMP and MP3. A 24-bit BMP is re-encoded here, and an MP3 that is not mono/44100 Hz is re-encoded too; an MP3 kept as it is has its ID3 tags removed.So "BMP = no conversion" is false in general, and the honest form is a sentence, not a mark.
What this changes
Conversion when transferringsubsection (both languages) states what each pack format carries, that anything else is converted while the transfer is prepared, and that theRawpath enforces nothing — meeting the listed constraints is the user's job, not something the conversion will fix.Documentation only — no code touched.
Generated by Claude Code