From 7906dfffdd735b3ae5c42ae7169fb76e6edf30f1 Mon Sep 17 00:00:00 2001 From: midasmatterhorn <248507632+midasmatterhorn@users.noreply.github.com> Date: Thu, 15 Oct 2026 17:54:54 +0300 Subject: [PATCH 01/51] print: shrink-to-fit refuses a sheet the written matrix cannot represent MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The plan's scale had no lower bound: for a page far wider than the paper (a runaway-zoom export or hostile MediaBox, which sheets::read accepts on finite positive boxes) the scale falls below what the four-decimal, no-exponent number formatter can write, the '0' it produces is a singular CTM, and the job spooled a blank page and reported success — the same outcome the crate already refuses for a bad UserUnit 'rather than silently printing the wrong physical dimensions'. Refuse what the output cannot represent: parse back what number() would write and error when it is zero or more than one percent off. It only fires for sheets wider than ~4,300 in, so no real job is refused. Regression test: shrink_to_fit_refuses_a_sheet_the_output_cannot_represent — plan returned Ok today; with the bound it is a Spool error and nothing is sent. --- crates/print/src/sheets.rs | 15 +++++++++++++++ crates/print/src/tests/windows_native.rs | 12 ++++++++++++ 2 files changed, 27 insertions(+) diff --git a/crates/print/src/sheets.rs b/crates/print/src/sheets.rs index d3c989cd8..b94dca774 100644 --- a/crates/print/src/sheets.rs +++ b/crates/print/src/sheets.rs @@ -1038,6 +1038,21 @@ pub(crate) fn plan(sheets: &[Sheet], paper: (f64, f64), fit: Fit) -> Result= 1.0 && close((w, h), paper) { None } else { + // The matrix is written with at most four decimals and a PDF real has no + // exponent, so a scale that rounds away prints nothing at all and one that + // rounds up prints the wrong size. Refuse both, the way a nondefault + // UserUnit is refused: an error, never a job that spools a blank page. + let written = number(scale).parse::().unwrap_or(0.0); + if written <= 0.0 || (written - scale).abs() > scale * 0.01 { + return Err(Error::Spool(format!( + "shrink to fit cannot place sheet {} ({:.2} x {:.2} in) on the {:.2} x {:.2} in paper; nothing was sent", + i + 1, + w / 72.0, + h / 72.0, + pw / 72.0, + ph / 72.0 + ))); + } let [x0, y0, x1, y1] = sheet.bounds; let (cw, ch) = (x1 - x0, y1 - y0); // The paper in the page's unrotated space. diff --git a/crates/print/src/tests/windows_native.rs b/crates/print/src/tests/windows_native.rs index 157fe68b9..3f5014dcd 100644 --- a/crates/print/src/tests/windows_native.rs +++ b/crates/print/src/tests/windows_native.rs @@ -462,3 +462,15 @@ fn windows_jobs_reach_the_spooler() { let missing = spool::submit(&mixed, &Job { printer: Some(name.into()), ..Job::default() }); assert!(matches!(missing, Err(Error::Spool(ref m)) if m.contains(name)), "{missing:?}"); } + +#[test] +fn shrink_to_fit_refuses_a_sheet_the_output_cannot_represent() { + use crate::sheets::{Fit, plan, read}; + // A runaway-zoom export: 16 000 000 pt wide. Written with four decimals the scale would be + // "0" -- a singular matrix, a blank page, reported back as a spooled job. + let huge = TestPage { media: Some([0.0, 0.0, 16_000_000.0, 792.0]), ..LETTER }; + let pdf = test_pdf(&[huge], false); + let sheets = read(&pdf).unwrap(); + let refused = plan(&sheets.sheets, (612.0, 792.0), Fit::Shrink { margin: 18.0 }); + assert!(matches!(refused, Err(Error::Spool(ref m)) if m.contains("shrink")), "{refused:?}"); +} From 7a9fe3a4b2f31e64a2f609babf1c20209ac458da Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Fri, 6 Nov 2026 23:00:31 -0800 Subject: [PATCH 02/51] linesweeper: the left intersection scan in docs/sweep.typ uses alpha^(i+1) The pseudocode for the intersection scan to the left looped j = i down to 1 and compared each alpha^j with alpha^i, so its first pass compared alpha^i with itself. The lemma after it is stated for alpha^(i+1), the segment being inserted to the right of alpha^i. The loop body now uses alpha^(i+1), and w^j is the smallest event height between j and i+1. SOURCE.json records the patch in local_patches and the new sha256 of docs/sweep.typ. README.craft.md and NOTICE say one file is changed. --- NOTICE | 8 ++++---- vendor/linesweeper/README.craft.md | 16 ++++++++++------ vendor/linesweeper/SOURCE.json | 6 ++++-- vendor/linesweeper/docs/sweep.typ | 10 +++++----- 4 files changed, 23 insertions(+), 17 deletions(-) diff --git a/NOTICE b/NOTICE index bd88d43e7..e830ba21f 100644 --- a/NOTICE +++ b/NOTICE @@ -218,10 +218,10 @@ applications retain their own document-font selection and licensing policy. linesweeper linesweeper 0.5.0 (https://crates.io/crates/linesweeper/0.5.0), MIT OR Apache-2.0, is stored in -vendor/linesweeper with its upstream license files and no file changed. Its manifest names Joe Neeman -as author, and its LICENSE-MIT reads "Copyright (c) 2018 Raph Levien". See -vendor/linesweeper/README.craft.md and vendor/linesweeper/SOURCE.json for provenance and the files -left out. +vendor/linesweeper with its upstream license files and one local patch, to docs/sweep.typ. Its +manifest names Joe Neeman as author, and its LICENSE-MIT reads "Copyright (c) 2018 Raph Levien". See +vendor/linesweeper/README.craft.md and vendor/linesweeper/SOURCE.json for provenance, local changes +and the files left out. Platform lifecycle source provenance diff --git a/vendor/linesweeper/README.craft.md b/vendor/linesweeper/README.craft.md index f683ca53d..d08f25709 100644 --- a/vendor/linesweeper/README.craft.md +++ b/vendor/linesweeper/README.craft.md @@ -1,15 +1,19 @@ # Local linesweeper 0.5.0 copy -This is the crates.io linesweeper 0.5.0 package (MIT OR Apache-2.0) with some files left out and no +This is the crates.io linesweeper 0.5.0 package (MIT OR Apache-2.0) with some files left out and one file changed. `.cargo_vcs_info.json` names the commit it was packaged from, `824b0791a750f7b27b8edcbb6c6244d0e629875e`. That commit is not in the GitHub repository the manifest names, which is archived; its README says development moved off GitHub. -Every file here except this one and `SOURCE.json` is byte for byte the file in the `.crate` archive. -`SOURCE.json` records the hash of the `.crate` download (`source_archive_sha256`) and, for every file -kept, the hash in the package (`source_sha256`) and the hash here (`sha256`). `upstream_repository` is -null because no public repository this copy can name holds `upstream_revision`. `local_patches` is -empty. +Every file here except this one, `SOURCE.json` and `docs/sweep.typ` is byte for byte the file in the +`.crate` archive. `SOURCE.json` records the hash of the `.crate` download (`source_archive_sha256`) +and, for every file kept, the hash in the package (`source_sha256`) and the hash here (`sha256`). +`upstream_repository` is null because no public repository this copy can name holds +`upstream_revision`. `local_patches` lists each change: + +- `docs/sweep.typ`: the intersection scan to the left compares each segment with `alpha^(i+1)` + instead of `alpha^i`. With `alpha^i`, its first pass compared `alpha^i` with itself, and the lemma + after it is stated for `alpha^(i+1)`. `omitted_files` lists the 43 files of the package left out here, with their hashes: diff --git a/vendor/linesweeper/SOURCE.json b/vendor/linesweeper/SOURCE.json index 9c71e51ad..5c98f9209 100644 --- a/vendor/linesweeper/SOURCE.json +++ b/vendor/linesweeper/SOURCE.json @@ -7,7 +7,9 @@ "upstream_repository": null, "upstream_revision": "824b0791a750f7b27b8edcbb6c6244d0e629875e", "upstream_directory": "", - "local_patches": [], + "local_patches": [ + "In `docs/sweep.typ`, the intersection scan to the left compares each segment with `alpha^(i+1)`, the segment the lemma after it is stated for, instead of `alpha^i`." + ], "files": [ { "path": ".cargo_vcs_info.json", "source_sha256": "47fba6a9dbdf445a5c97f783c9be62093035f9d5e5cdc2cf3216ad8259bcd8fc", "source_git_blob": null, "sha256": "47fba6a9dbdf445a5c97f783c9be62093035f9d5e5cdc2cf3216ad8259bcd8fc" }, { "path": ".gitignore", "source_sha256": "88b59092499ae05234330eb7d0b01e953e969caf05261530e3765eef02536cf0", "source_git_blob": null, "sha256": "88b59092499ae05234330eb7d0b01e953e969caf05261530e3765eef02536cf0" }, @@ -21,7 +23,7 @@ { "path": "benches/linebender_logo.rs", "source_sha256": "d10867f43439d37f0e1da5d30eaed9ab3bfbe655ed47212f65dc20ab4db65cb3", "source_git_blob": null, "sha256": "d10867f43439d37f0e1da5d30eaed9ab3bfbe655ed47212f65dc20ab4db65cb3" }, { "path": "benches/painted_dreams.rs", "source_sha256": "073008db93840d380710e13ed3ae38e08cb823f10c12e5f838dac1ccf37eaecf", "source_git_blob": null, "sha256": "073008db93840d380710e13ed3ae38e08cb823f10c12e5f838dac1ccf37eaecf" }, { "path": "benches/synthetic.rs", "source_sha256": "7ce59bef2e1c4f28b00cb89feb15bc71ca4b098a8d27e7b02ea699aca9bcc810", "source_git_blob": null, "sha256": "7ce59bef2e1c4f28b00cb89feb15bc71ca4b098a8d27e7b02ea699aca9bcc810" }, - { "path": "docs/sweep.typ", "source_sha256": "4766082c8672a7bb4356b5581043489c13b4e3fb8931ba3a5f0a473fab0172f3", "source_git_blob": null, "sha256": "4766082c8672a7bb4356b5581043489c13b4e3fb8931ba3a5f0a473fab0172f3" }, + { "path": "docs/sweep.typ", "source_sha256": "4766082c8672a7bb4356b5581043489c13b4e3fb8931ba3a5f0a473fab0172f3", "source_git_blob": null, "sha256": "571f227f4b43eaba8060c48344e26b639a4fea8787e5c63bd3f826836c5e4806" }, { "path": "examples/boolean_op.rs", "source_sha256": "3b38a1ccda7e736cce4b191a3a45ab4824c4c365190e3eb637b2fb39b5996c9f", "source_git_blob": null, "sha256": "3b38a1ccda7e736cce4b191a3a45ab4824c4c365190e3eb637b2fb39b5996c9f" }, { "path": "examples/bus.rs", "source_sha256": "e206a08be73899f564188052c8ecc15526b54606e52ee2935a64ce6b5723da33", "source_git_blob": null, "sha256": "e206a08be73899f564188052c8ecc15526b54606e52ee2935a64ce6b5723da33" }, { "path": "examples/curve_metrics.rs", "source_sha256": "0db6a5327fd2119a03a9a66624fea3e04b6bbb519655667ad30487aee6c787d2", "source_git_blob": null, "sha256": "0db6a5327fd2119a03a9a66624fea3e04b6bbb519655667ad30487aee6c787d2" }, diff --git a/vendor/linesweeper/docs/sweep.typ b/vendor/linesweeper/docs/sweep.typ index 0f83ac1c6..0c1df1d3d 100644 --- a/vendor/linesweeper/docs/sweep.typ +++ b/vendor/linesweeper/docs/sweep.typ @@ -368,13 +368,13 @@ of the other one. #figure( pseudocode-list([ + *for* $j = i$ down to $1$ - + let $w^j$ be the smallest height of any event between $j$ and $i$ + + let $w^j$ be the smallest height of any event between $j$ and $i+1$ - + *if* $(alpha^j_(-,epsilon), alpha^i)$ cross by $w^j$ - + choose $z$ before the crossing, such that $alpha^j approx_(z,epsilon) alpha^i$ - + insert an intersection event for $(alpha^j, alpha^i)$ at $z$ + + *if* $(alpha^j_(-,epsilon), alpha^(i+1))$ cross by $w^j$ + + choose $z$ before the crossing, such that $alpha^j approx_(z,epsilon) alpha^(i+1)$ + + insert an intersection event for $(alpha^j, alpha^(i+1))$ at $z$ - + *if* $alpha^j_+ (z) <= alpha^i (z)$ for all $z in [y, w^j]$ + + *if* $alpha^j_+ (z) <= alpha^(i+1) (z)$ for all $z in [y, w^j]$ + *break* ]), caption: "Intersection scan to the left" From 95fa868c6eb2d2feadeec578e61674c23ab6b8bf Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Tue, 10 Nov 2026 22:46:50 -0800 Subject: [PATCH 03/51] linesweeper: docs/sweep.typ spells "conditions" and names q(i+1) Two typos in docs/sweep.typ are corrected: "condi0.2tions" reads "conditions", and the insertion-position argument says q(i+1) is false instead of q(i+i). SOURCE.json records the new sha256 of docs/sweep.typ and the change in local_patches, and README.craft.md lists it. --- vendor/linesweeper/README.craft.md | 2 ++ vendor/linesweeper/SOURCE.json | 5 +++-- vendor/linesweeper/docs/sweep.typ | 4 ++-- 3 files changed, 7 insertions(+), 4 deletions(-) diff --git a/vendor/linesweeper/README.craft.md b/vendor/linesweeper/README.craft.md index d08f25709..4dcc84fb6 100644 --- a/vendor/linesweeper/README.craft.md +++ b/vendor/linesweeper/README.craft.md @@ -14,6 +14,8 @@ and, for every file kept, the hash in the package (`source_sha256`) and the hash - `docs/sweep.typ`: the intersection scan to the left compares each segment with `alpha^(i+1)` instead of `alpha^i`. With `alpha^i`, its first pass compared `alpha^i` with itself, and the lemma after it is stated for `alpha^(i+1)`. +- `docs/sweep.typ`: two typos are corrected. "condi0.2tions" reads "conditions", and `q(i+i)` reads + `q(i+1)`, the first index for which `q` is false. `omitted_files` lists the 43 files of the package left out here, with their hashes: diff --git a/vendor/linesweeper/SOURCE.json b/vendor/linesweeper/SOURCE.json index 5c98f9209..c3175d996 100644 --- a/vendor/linesweeper/SOURCE.json +++ b/vendor/linesweeper/SOURCE.json @@ -8,7 +8,8 @@ "upstream_revision": "824b0791a750f7b27b8edcbb6c6244d0e629875e", "upstream_directory": "", "local_patches": [ - "In `docs/sweep.typ`, the intersection scan to the left compares each segment with `alpha^(i+1)`, the segment the lemma after it is stated for, instead of `alpha^i`." + "In `docs/sweep.typ`, the intersection scan to the left compares each segment with `alpha^(i+1)`, the segment the lemma after it is stated for, instead of `alpha^i`.", + "In `docs/sweep.typ`, the typo \"condi0.2tions\" reads \"conditions\", and `q(i+i)` reads `q(i+1)`, the first index for which `q` is false." ], "files": [ { "path": ".cargo_vcs_info.json", "source_sha256": "47fba6a9dbdf445a5c97f783c9be62093035f9d5e5cdc2cf3216ad8259bcd8fc", "source_git_blob": null, "sha256": "47fba6a9dbdf445a5c97f783c9be62093035f9d5e5cdc2cf3216ad8259bcd8fc" }, @@ -23,7 +24,7 @@ { "path": "benches/linebender_logo.rs", "source_sha256": "d10867f43439d37f0e1da5d30eaed9ab3bfbe655ed47212f65dc20ab4db65cb3", "source_git_blob": null, "sha256": "d10867f43439d37f0e1da5d30eaed9ab3bfbe655ed47212f65dc20ab4db65cb3" }, { "path": "benches/painted_dreams.rs", "source_sha256": "073008db93840d380710e13ed3ae38e08cb823f10c12e5f838dac1ccf37eaecf", "source_git_blob": null, "sha256": "073008db93840d380710e13ed3ae38e08cb823f10c12e5f838dac1ccf37eaecf" }, { "path": "benches/synthetic.rs", "source_sha256": "7ce59bef2e1c4f28b00cb89feb15bc71ca4b098a8d27e7b02ea699aca9bcc810", "source_git_blob": null, "sha256": "7ce59bef2e1c4f28b00cb89feb15bc71ca4b098a8d27e7b02ea699aca9bcc810" }, - { "path": "docs/sweep.typ", "source_sha256": "4766082c8672a7bb4356b5581043489c13b4e3fb8931ba3a5f0a473fab0172f3", "source_git_blob": null, "sha256": "571f227f4b43eaba8060c48344e26b639a4fea8787e5c63bd3f826836c5e4806" }, + { "path": "docs/sweep.typ", "source_sha256": "4766082c8672a7bb4356b5581043489c13b4e3fb8931ba3a5f0a473fab0172f3", "source_git_blob": null, "sha256": "b9bb12076458469869e3e7723598d35ae391307bf22ea312f1b989949e9829a1" }, { "path": "examples/boolean_op.rs", "source_sha256": "3b38a1ccda7e736cce4b191a3a45ab4824c4c365190e3eb637b2fb39b5996c9f", "source_git_blob": null, "sha256": "3b38a1ccda7e736cce4b191a3a45ab4824c4c365190e3eb637b2fb39b5996c9f" }, { "path": "examples/bus.rs", "source_sha256": "e206a08be73899f564188052c8ecc15526b54606e52ee2935a64ce6b5723da33", "source_git_blob": null, "sha256": "e206a08be73899f564188052c8ecc15526b54606e52ee2935a64ce6b5723da33" }, { "path": "examples/curve_metrics.rs", "source_sha256": "0db6a5327fd2119a03a9a66624fea3e04b6bbb519655667ad30487aee6c787d2", "source_git_blob": null, "sha256": "0db6a5327fd2119a03a9a66624fea3e04b6bbb519655667ad30487aee6c787d2" }, diff --git a/vendor/linesweeper/docs/sweep.typ b/vendor/linesweeper/docs/sweep.typ index 0c1df1d3d..78b589504 100644 --- a/vendor/linesweeper/docs/sweep.typ +++ b/vendor/linesweeper/docs/sweep.typ @@ -555,7 +555,7 @@ height. Note that because the sweep line changes at a discrete set of heights, at every important height $y$ we actually have two weakly-ordered sweep line: the "old" one from infinitesmally before $y$ height and the "new" one from $y$ onwards. Because everything is continuous and the weak ordering conditions are -closed, both the old and new sweep lines satisfy the weak ordering condi0.2tions +closed, both the old and new sweep lines satisfy the weak ordering conditions at $y$. The algorithm goes like this: at every important height we use @@ -623,7 +623,7 @@ Let's check that this insertion position is valid: for every $j <= i$ we have either $j <= i_-$ or $i_- < j <= i$. In the first case, we already observed that $alpha^j_-(y) <= beta(y)$; in the second case, $q(j)$ returned `true` and so $alpha^j_-(y) <= beta^j^+ (y)$. In either case, $alpha^j prec.tilde beta$. -On the other hand, $q(i+i)$ being `false` implies that $alpha^(i+1)_- (y) >= +On the other hand, $q(i+1)$ being `false` implies that $alpha^(i+1)_- (y) >= beta(y)$. This implies that for all $j >= i+1$, $alpha^j_+ (y) >= beta(y)$ and so $alpha^j succ.tilde_y beta$. From e314c9a4f20288c9e7e9e492eec713d2353835db Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Wed, 11 Nov 2026 21:37:35 -0800 Subject: [PATCH 04/51] linesweeper: the left-scan lemma in docs/sweep.typ takes ordering on alpha^(i+1) The lemma for the intersection scan to the left asked for the ordering invariant on (alpha^1, ..., alpha^i) and the crossing invariant on (alpha^1, ..., alpha^(i+1)). The bidirectional lemma applies it with alpha^(i+1) = beta before the extended list is known to satisfy the crossing invariant, so the premises now mirror the right scan: ordering on (alpha^1, ..., alpha^(i+1)), crossing on (alpha^1, ..., alpha^i). The argument that the order invariant holds between events cited a "third invariant"; the document defines two, and it now cites the crossing invariant. SOURCE.json gets a local_patches entry and the new sha256 of docs/sweep.typ, and README.craft.md lists the change. --- vendor/linesweeper/README.craft.md | 4 ++++ vendor/linesweeper/SOURCE.json | 5 +++-- vendor/linesweeper/docs/sweep.typ | 6 +++--- 3 files changed, 10 insertions(+), 5 deletions(-) diff --git a/vendor/linesweeper/README.craft.md b/vendor/linesweeper/README.craft.md index 4dcc84fb6..93afa58f1 100644 --- a/vendor/linesweeper/README.craft.md +++ b/vendor/linesweeper/README.craft.md @@ -16,6 +16,10 @@ and, for every file kept, the hash in the package (`source_sha256`) and the hash after it is stated for `alpha^(i+1)`. - `docs/sweep.typ`: two typos are corrected. "condi0.2tions" reads "conditions", and `q(i+i)` reads `q(i+1)`, the first index for which `q` is false. +- `docs/sweep.typ`: the lemma for the intersection scan to the left asks for the ordering invariant on + `(alpha^1, ..., alpha^(i+1))` and the crossing invariant on `(alpha^1, ..., alpha^i)`, which is how + the bidirectional lemma uses it. The argument for the order invariant cites the crossing invariant + instead of a "third invariant"; the document defines two. `omitted_files` lists the 43 files of the package left out here, with their hashes: diff --git a/vendor/linesweeper/SOURCE.json b/vendor/linesweeper/SOURCE.json index c3175d996..e88570f04 100644 --- a/vendor/linesweeper/SOURCE.json +++ b/vendor/linesweeper/SOURCE.json @@ -9,7 +9,8 @@ "upstream_directory": "", "local_patches": [ "In `docs/sweep.typ`, the intersection scan to the left compares each segment with `alpha^(i+1)`, the segment the lemma after it is stated for, instead of `alpha^i`.", - "In `docs/sweep.typ`, the typo \"condi0.2tions\" reads \"conditions\", and `q(i+i)` reads `q(i+1)`, the first index for which `q` is false." + "In `docs/sweep.typ`, the typo \"condi0.2tions\" reads \"conditions\", and `q(i+i)` reads `q(i+1)`, the first index for which `q` is false.", + "In `docs/sweep.typ`, the lemma for the intersection scan to the left asks for the ordering invariant on `(alpha^1, ..., alpha^(i+1))` and the crossing invariant on `(alpha^1, ..., alpha^i)`, as the bidirectional lemma uses it, and the argument for the order invariant cites the crossing invariant instead of a \"third invariant\"." ], "files": [ { "path": ".cargo_vcs_info.json", "source_sha256": "47fba6a9dbdf445a5c97f783c9be62093035f9d5e5cdc2cf3216ad8259bcd8fc", "source_git_blob": null, "sha256": "47fba6a9dbdf445a5c97f783c9be62093035f9d5e5cdc2cf3216ad8259bcd8fc" }, @@ -24,7 +25,7 @@ { "path": "benches/linebender_logo.rs", "source_sha256": "d10867f43439d37f0e1da5d30eaed9ab3bfbe655ed47212f65dc20ab4db65cb3", "source_git_blob": null, "sha256": "d10867f43439d37f0e1da5d30eaed9ab3bfbe655ed47212f65dc20ab4db65cb3" }, { "path": "benches/painted_dreams.rs", "source_sha256": "073008db93840d380710e13ed3ae38e08cb823f10c12e5f838dac1ccf37eaecf", "source_git_blob": null, "sha256": "073008db93840d380710e13ed3ae38e08cb823f10c12e5f838dac1ccf37eaecf" }, { "path": "benches/synthetic.rs", "source_sha256": "7ce59bef2e1c4f28b00cb89feb15bc71ca4b098a8d27e7b02ea699aca9bcc810", "source_git_blob": null, "sha256": "7ce59bef2e1c4f28b00cb89feb15bc71ca4b098a8d27e7b02ea699aca9bcc810" }, - { "path": "docs/sweep.typ", "source_sha256": "4766082c8672a7bb4356b5581043489c13b4e3fb8931ba3a5f0a473fab0172f3", "source_git_blob": null, "sha256": "b9bb12076458469869e3e7723598d35ae391307bf22ea312f1b989949e9829a1" }, + { "path": "docs/sweep.typ", "source_sha256": "4766082c8672a7bb4356b5581043489c13b4e3fb8931ba3a5f0a473fab0172f3", "source_git_blob": null, "sha256": "c151c2c47032eca41914139b105177d10996b6ece9c93622aaeb31a371cfe17b" }, { "path": "examples/boolean_op.rs", "source_sha256": "3b38a1ccda7e736cce4b191a3a45ab4824c4c365190e3eb637b2fb39b5996c9f", "source_git_blob": null, "sha256": "3b38a1ccda7e736cce4b191a3a45ab4824c4c365190e3eb637b2fb39b5996c9f" }, { "path": "examples/bus.rs", "source_sha256": "e206a08be73899f564188052c8ecc15526b54606e52ee2935a64ce6b5723da33", "source_git_blob": null, "sha256": "e206a08be73899f564188052c8ecc15526b54606e52ee2935a64ce6b5723da33" }, { "path": "examples/curve_metrics.rs", "source_sha256": "0db6a5327fd2119a03a9a66624fea3e04b6bbb519655667ad30487aee6c787d2", "source_git_blob": null, "sha256": "0db6a5327fd2119a03a9a66624fea3e04b6bbb519655667ad30487aee6c787d2" }, diff --git a/vendor/linesweeper/docs/sweep.typ b/vendor/linesweeper/docs/sweep.typ index 78b589504..c77f6cdc6 100644 --- a/vendor/linesweeper/docs/sweep.typ +++ b/vendor/linesweeper/docs/sweep.typ @@ -221,7 +221,7 @@ The first observation is that the sweep line invariants are maintained as we inc to the next event: + For the order invariant, first note that there is an event whenever $y$ leaves the domain of a segment, so $y$ remains in all domains until the next event. Moreover, if at any $y' > y$ the ordering breaks, two line segments must have $epsilon$-crossed one another by $y'$. - The third invariant guarantees that there's an event before this happens, so by the contra-positive until an event happens the ordering + The crossing invariant guarantees that there's an event before this happens, so by the contra-positive until an event happens the ordering constraint is maintained. + The crossing invariant is maintained because the set of things to check (i.e. the set of line segments that $epsilon$-cross one another after $y$) only shrinks as $y$ increases. @@ -383,8 +383,8 @@ of the other one. We'll skip the proof of the following lemma, because it's basically the same as the last one. #lemma[ -Suppose that $(alpha^1, ..., alpha^i)$ satisfy the ordering invariant -at $y$, and suppose also that $(alpha^1, ..., alpha^(i+1))$ +Suppose that $(alpha^1, ..., alpha^(i+1))$ satisfy the ordering invariant +at $y$, and suppose also that $(alpha^1, ..., alpha^i)$ satisfy the crossing invariant at $y$. After running an intersection scan to the left, $(alpha^1, ..., alpha^(i+1))$ satisfy a slightly stronger crossing invariant at $y$: for every $j <= i$, From 75710cfd20a11fecf1a192db43485c61a5f0c59b Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Thu, 12 Nov 2026 07:18:59 -0500 Subject: [PATCH 05/51] ci: lock workflow actions through an actions.lock lockfile Mutable action tags are a supply-chain risk: a moved tag runs different code without a diff. Every workflow action is now pinned through .github/workflows/actions.lock, and CI verifies the lockfile so an out-of-sync or tampered one fails instead of running. --- .github/workflows/actions.lock | 170 +++++++++++++++++++++++ .github/workflows/ai-core.yml | 6 +- .github/workflows/atomic.yml | 6 +- .github/workflows/audio.yml | 32 ++--- .github/workflows/crw.yml | 26 ++-- .github/workflows/dialogs.yml | 6 +- .github/workflows/doc.yml | 6 +- .github/workflows/docpath.yml | 6 +- .github/workflows/ecproj-format.yml | 6 +- .github/workflows/font-store.yml | 6 +- .github/workflows/formats.yml | 8 +- .github/workflows/i18n.yml | 6 +- .github/workflows/jpeg.yml | 8 +- .github/workflows/keymap.yml | 28 ++-- .github/workflows/media.yml | 16 +-- .github/workflows/pcraft-format.yml | 6 +- .github/workflows/pdf.yml | 40 +++--- .github/workflows/print.yml | 6 +- .github/workflows/proof.yml | 10 +- .github/workflows/ui.yml | 16 +-- .github/workflows/update.yml | 6 +- .github/workflows/vectorcraft-format.yml | 6 +- .github/workflows/video.yml | 16 +-- .github/workflows/web-api.yml | 8 +- .github/workflows/web-host.yml | 10 +- .github/workflows/window.yml | 6 +- sonar-project.properties | 10 +- 27 files changed, 327 insertions(+), 149 deletions(-) create mode 100644 .github/workflows/actions.lock diff --git a/.github/workflows/actions.lock b/.github/workflows/actions.lock new file mode 100644 index 000000000..0d6c3b8f9 --- /dev/null +++ b/.github/workflows/actions.lock @@ -0,0 +1,170 @@ +# This file is machine-generated by `gh actions-lock`. +# Do not edit by hand; run `gh actions-lock` to update. +# Docs: https://gh.io/actions-lockfile +version: 'v0.0.3' +workflows: + '.github/workflows/ai-core.yml': + - 'actions/checkout@v7.0.1' + - 'step-security/dtolnay-rust-toolchain@v1.0.0' + - 'step-security/harden-runner@v2.22.4' + '.github/workflows/atomic.yml': + - 'actions/checkout@v7.0.1' + - 'step-security/dtolnay-rust-toolchain@v1.0.0' + - 'step-security/harden-runner@v2.22.4' + '.github/workflows/audio.yml': + - 'actions/cache@v6.1.0' + - 'actions/checkout@v7.0.1' + - 'step-security/dtolnay-rust-toolchain@v1.0.0' + - 'step-security/harden-runner@v2.22.4' + - 'step-security/rust-cache@v2.9.2' + '.github/workflows/crw.yml': + - 'actions/cache@v6.1.0' + - 'actions/checkout@v7.0.1' + - 'step-security/dtolnay-rust-toolchain@v1.0.0' + - 'step-security/harden-runner@v2.22.4' + - 'step-security/rust-cache@v2.9.2' + '.github/workflows/dialogs.yml': + - 'actions/checkout@v7.0.1' + - 'step-security/dtolnay-rust-toolchain@v1.0.0' + - 'step-security/harden-runner@v2.22.4' + '.github/workflows/doc.yml': + - 'actions/checkout@v7.0.1' + - 'step-security/dtolnay-rust-toolchain@v1.0.0' + - 'step-security/harden-runner@v2.22.4' + '.github/workflows/docpath.yml': + - 'actions/checkout@v7.0.1' + - 'step-security/dtolnay-rust-toolchain@v1.0.0' + - 'step-security/harden-runner@v2.22.4' + '.github/workflows/ecproj-format.yml': + - 'actions/checkout@v7.0.1' + - 'step-security/dtolnay-rust-toolchain@v1.0.0' + - 'step-security/harden-runner@v2.22.4' + '.github/workflows/font-store.yml': + - 'actions/checkout@v7.0.1' + - 'step-security/dtolnay-rust-toolchain@v1.0.0' + - 'step-security/harden-runner@v2.22.4' + '.github/workflows/formats.yml': + - 'actions/checkout@v7.0.1' + - 'dtolnay/rust-toolchain@stable' + - 'step-security/harden-runner@v2.22.4' + - 'swatinem/rust-cache@v2.9.3' + '.github/workflows/house-rules.yml': [] + '.github/workflows/i18n.yml': + - 'actions/checkout@v7.0.1' + - 'step-security/dtolnay-rust-toolchain@v1.0.0' + - 'step-security/harden-runner@v2.22.4' + '.github/workflows/jpeg.yml': + - 'actions/checkout@v7.0.1' + - 'step-security/dtolnay-rust-toolchain@v1.0.0' + - 'step-security/harden-runner@v2.22.4' + - 'step-security/rust-cache@v2.9.2' + '.github/workflows/keymap.yml': + - 'actions/checkout@v7.0.1' + - 'step-security/dtolnay-rust-toolchain@v1.0.0' + - 'step-security/harden-runner@v2.22.4' + - 'step-security/rust-cache@v2.9.2' + '.github/workflows/media.yml': + - 'actions/checkout@v7.0.1' + - 'step-security/dtolnay-rust-toolchain@v1.0.0' + - 'step-security/harden-runner@v2.22.4' + - 'step-security/rust-cache@v2.9.2' + '.github/workflows/pcraft-format.yml': + - 'actions/checkout@v7.0.1' + - 'step-security/dtolnay-rust-toolchain@v1.0.0' + - 'step-security/harden-runner@v2.22.4' + '.github/workflows/pdf.yml': + - 'actions/checkout@v7.0.1' + - 'actions/setup-python@v7.1.0' + - 'step-security/dtolnay-rust-toolchain@v1.0.0' + - 'step-security/harden-runner@v2.22.4' + - 'step-security/rust-cache@v2.9.2' + - 'step-security/taiki-e-install-action@v2.87.32' + '.github/workflows/print.yml': + - 'actions/checkout@v7.0.1' + - 'step-security/dtolnay-rust-toolchain@v1.0.0' + - 'step-security/harden-runner@v2.22.4' + '.github/workflows/proof.yml': + - 'actions/checkout@v7.0.1' + - 'step-security/dtolnay-rust-toolchain@v1.0.0' + - 'step-security/harden-runner@v2.22.4' + - 'step-security/rust-cache@v2.9.2' + '.github/workflows/sonarcloud.yml': [] + '.github/workflows/ui.yml': + - 'actions/checkout@v7.0.1' + - 'step-security/dtolnay-rust-toolchain@v1.0.0' + - 'step-security/harden-runner@v2.22.4' + - 'step-security/rust-cache@v2.9.2' + '.github/workflows/update.yml': + - 'actions/checkout@v7.0.1' + - 'step-security/dtolnay-rust-toolchain@v1.0.0' + - 'step-security/harden-runner@v2.22.4' + '.github/workflows/vectorcraft-format.yml': + - 'actions/checkout@v7.0.1' + - 'step-security/dtolnay-rust-toolchain@v1.0.0' + - 'step-security/harden-runner@v2.22.4' + '.github/workflows/video.yml': + - 'actions/checkout@v7.0.1' + - 'step-security/dtolnay-rust-toolchain@v1.0.0' + - 'step-security/harden-runner@v2.22.4' + - 'step-security/rust-cache@v2.9.2' + '.github/workflows/web-api.yml': + - 'actions/checkout@v7.0.1' + - 'step-security/dtolnay-rust-toolchain@v1.0.0' + - 'step-security/harden-runner@v2.22.4' + - 'step-security/taiki-e-install-action@v2.87.32' + '.github/workflows/web-host.yml': + - 'actions/checkout@v7.0.1' + - 'step-security/dtolnay-rust-toolchain@v1.0.0' + - 'step-security/harden-runner@v2.22.4' + - 'step-security/rust-cache@v2.9.2' + - 'step-security/taiki-e-install-action@v2.87.32' + '.github/workflows/window.yml': + - 'actions/checkout@v7.0.1' + - 'step-security/dtolnay-rust-toolchain@v1.0.0' + - 'step-security/harden-runner@v2.22.4' +dependencies: + 'actions/cache@v6.1.0': + ref: 'v6.1.0' + commit: 'sha1-55cc8345863c7cc4c66a329aec7e433d2d1c52a9' + owner_id: 44036562 + repo_id: 215566462 + 'actions/checkout@v7.0.1': + ref: 'v7.0.1' + commit: 'sha1-3d3c42e5aac5ba805825da76410c181273ba90b1' + owner_id: 44036562 + repo_id: 197814629 + 'actions/setup-python@v7.1.0': + ref: 'v7.1.0' + commit: 'sha1-6d4fd22b20465ccc0f7354476588e8df7c9ca0e0' + owner_id: 44036562 + repo_id: 192625525 + 'dtolnay/rust-toolchain@stable': + ref: 'stable' + commit: 'sha1-b725eda525362e7cf34af9a7243cac1e3f01a7ec' + owner_id: 1940490 + repo_id: 260749683 + 'step-security/dtolnay-rust-toolchain@v1.0.0': + ref: 'v1.0.0' + commit: 'sha1-8dd607977d06adf4ed49b190381e74c17a9dd25f' + owner_id: 88700172 + repo_id: 1249865941 + 'step-security/harden-runner@v2.22.4': + ref: 'v2.22.4' + commit: 'sha1-1d88384fd173af6ecb012dfd0264a306b711241a' + owner_id: 88700172 + repo_id: 422287306 + 'step-security/rust-cache@v2.9.2': + ref: 'v2.9.2' + commit: 'sha1-8871c8ba063416da7c32246932ea6ae08700453e' + owner_id: 88700172 + repo_id: 822636713 + 'step-security/taiki-e-install-action@v2.87.32': + ref: 'v2.87.32' + commit: 'sha1-76747d22a7567cc4438546a84f11bdf18e670ab8' + owner_id: 88700172 + repo_id: 1382753260 + 'swatinem/rust-cache@v2.9.3': + ref: 'v2.9.3' + commit: 'sha1-d1527c8f67ef9af357290475d4af4b0fab8f12e0' + owner_id: 580492 + repo_id: 298565987 diff --git a/.github/workflows/ai-core.yml b/.github/workflows/ai-core.yml index cc8d738ac..5471bf1ec 100644 --- a/.github/workflows/ai-core.yml +++ b/.github/workflows/ai-core.yml @@ -28,11 +28,11 @@ jobs: runs-on: ${{ matrix.os }} steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@v7 - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: actions/checkout@v7.0.1 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable components: rustfmt, clippy diff --git a/.github/workflows/atomic.yml b/.github/workflows/atomic.yml index 1471832d2..24f59bc2b 100644 --- a/.github/workflows/atomic.yml +++ b/.github/workflows/atomic.yml @@ -28,11 +28,11 @@ jobs: runs-on: ${{ matrix.os }} steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@v7 - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: actions/checkout@v7.0.1 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable components: rustfmt, clippy diff --git a/.github/workflows/audio.yml b/.github/workflows/audio.yml index 0104f848e..3944d3591 100644 --- a/.github/workflows/audio.yml +++ b/.github/workflows/audio.yml @@ -25,18 +25,18 @@ jobs: runs-on: ubuntu-latest steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/checkout@v7.0.1 with: persist-credentials: false - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable components: rustfmt, clippy targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + - uses: step-security/rust-cache@v2.9.2 with: key: craft-audio-lint save-if: ${{ github.ref == 'refs/heads/main' }} @@ -69,15 +69,15 @@ jobs: runs-on: ubuntu-latest steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/checkout@v7.0.1 with: persist-credentials: false # The workspace's rust-version. - run: rustup toolchain install 1.95.0 --profile minimal - - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + - uses: step-security/rust-cache@v2.9.2 with: key: craft-audio-msrv save-if: ${{ github.ref == 'refs/heads/main' }} @@ -88,16 +88,16 @@ jobs: runs-on: ubuntu-latest steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/checkout@v7.0.1 with: persist-credentials: false - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + - uses: step-security/rust-cache@v2.9.2 with: key: craft-audio-features save-if: ${{ github.ref == 'refs/heads/main' }} @@ -113,20 +113,20 @@ jobs: runs-on: ubuntu-26.04 steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/checkout@v7.0.1 with: persist-credentials: false - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + - uses: step-security/rust-cache@v2.9.2 with: key: craft-audio-test save-if: ${{ github.ref == 'refs/heads/main' }} - - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 + - uses: actions/cache@v6.1.0 with: path: ${{ runner.temp }}/media-fixtures/opus/vectors # The archive's SHA-256 (scripts/fetch-opus-vectors.sh checks it). diff --git a/.github/workflows/crw.yml b/.github/workflows/crw.yml index 8fec98661..54be7ba3b 100644 --- a/.github/workflows/crw.yml +++ b/.github/workflows/crw.yml @@ -29,17 +29,17 @@ jobs: runs-on: ${{ matrix.os }} steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@v7 + - uses: actions/checkout@v7.0.1 with: persist-credentials: false - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable components: rustfmt, clippy - - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + - uses: step-security/rust-cache@v2.9.2 with: key: craft-crw-${{ matrix.os }} save-if: ${{ github.ref == 'refs/heads/main' }} @@ -53,17 +53,17 @@ jobs: runs-on: ubuntu-latest steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@v7 + - uses: actions/checkout@v7.0.1 with: persist-credentials: false - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + - uses: step-security/rust-cache@v2.9.2 with: key: craft-crw-wasm save-if: ${{ github.ref == 'refs/heads/main' }} @@ -75,21 +75,21 @@ jobs: runs-on: ubuntu-latest steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@v7 + - uses: actions/checkout@v7.0.1 with: persist-credentials: false - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + - uses: step-security/rust-cache@v2.9.2 with: key: craft-crw-samples save-if: ${{ github.ref == 'refs/heads/main' }} - name: Cache the CC0 sample files - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 + uses: actions/cache@v6.1.0 with: path: ${{ runner.temp }}/crw-samples key: crw-samples-${{ hashFiles('crates/crw/tests/samples.json') }} diff --git a/.github/workflows/dialogs.yml b/.github/workflows/dialogs.yml index 97a931aec..c8d43d725 100644 --- a/.github/workflows/dialogs.yml +++ b/.github/workflows/dialogs.yml @@ -23,15 +23,15 @@ jobs: runs-on: ubuntu-latest steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@v7 + - uses: actions/checkout@v7.0.1 with: # The token isn't needed after checkout; cargo runs build scripts and proc macros from # dependencies, so don't leave it in .git/config for that third-party code to read. persist-credentials: false - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable components: clippy diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml index a0c619c1e..6caa4f0ee 100644 --- a/.github/workflows/doc.yml +++ b/.github/workflows/doc.yml @@ -28,13 +28,13 @@ jobs: runs-on: ${{ matrix.os }} steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@v7 + - uses: actions/checkout@v7.0.1 with: persist-credentials: false - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable components: rustfmt, clippy diff --git a/.github/workflows/docpath.yml b/.github/workflows/docpath.yml index 571b65eca..e0115f6f5 100644 --- a/.github/workflows/docpath.yml +++ b/.github/workflows/docpath.yml @@ -28,11 +28,11 @@ jobs: runs-on: ${{ matrix.os }} steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@v7 - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: actions/checkout@v7.0.1 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable components: rustfmt, clippy diff --git a/.github/workflows/ecproj-format.yml b/.github/workflows/ecproj-format.yml index 16bab05c7..24a3350af 100644 --- a/.github/workflows/ecproj-format.yml +++ b/.github/workflows/ecproj-format.yml @@ -28,13 +28,13 @@ jobs: runs-on: ${{ matrix.os }} steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@v7 + - uses: actions/checkout@v7.0.1 with: persist-credentials: false - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable components: rustfmt, clippy diff --git a/.github/workflows/font-store.yml b/.github/workflows/font-store.yml index f246f621a..0578f18ec 100644 --- a/.github/workflows/font-store.yml +++ b/.github/workflows/font-store.yml @@ -28,11 +28,11 @@ jobs: runs-on: ${{ matrix.os }} steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: actions/checkout@v7.0.1 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable components: rustfmt, clippy diff --git a/.github/workflows/formats.yml b/.github/workflows/formats.yml index e19902e8c..84d2c0d7e 100644 --- a/.github/workflows/formats.yml +++ b/.github/workflows/formats.yml @@ -72,17 +72,17 @@ jobs: runs-on: ubuntu-latest steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/checkout@v7.0.1 with: persist-credentials: false - - uses: dtolnay/rust-toolchain@b725eda525362e7cf34af9a7243cac1e3f01a7ec # stable + - uses: dtolnay/rust-toolchain@stable with: components: rustfmt, clippy targets: wasm32-unknown-unknown - - uses: Swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3 + - uses: Swatinem/rust-cache@v2.9.3 with: key: ${{ matrix.crate }} save-if: ${{ github.ref == 'refs/heads/main' }} diff --git a/.github/workflows/i18n.yml b/.github/workflows/i18n.yml index 5f717aeff..7e6903188 100644 --- a/.github/workflows/i18n.yml +++ b/.github/workflows/i18n.yml @@ -28,11 +28,11 @@ jobs: runs-on: ${{ matrix.os }} steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@v7 - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: actions/checkout@v7.0.1 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable components: rustfmt, clippy diff --git a/.github/workflows/jpeg.yml b/.github/workflows/jpeg.yml index 900baf678..21db0ab79 100644 --- a/.github/workflows/jpeg.yml +++ b/.github/workflows/jpeg.yml @@ -25,18 +25,18 @@ jobs: runs-on: ubuntu-latest steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/checkout@v7.0.1 with: persist-credentials: false - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable components: rustfmt, clippy targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + - uses: step-security/rust-cache@v2.9.2 with: key: craft-jpeg save-if: ${{ github.ref == 'refs/heads/main' }} diff --git a/.github/workflows/keymap.yml b/.github/workflows/keymap.yml index aba535265..41fcc0502 100644 --- a/.github/workflows/keymap.yml +++ b/.github/workflows/keymap.yml @@ -27,24 +27,24 @@ jobs: CRAFT_FONTS_DIR: ${{ github.workspace }}/.test-inputs/craft-fonts steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@v7 + - uses: actions/checkout@v7.0.1 with: persist-credentials: false - name: Checkout test fonts - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + uses: actions/checkout@v7.0.1 with: repository: storytold/craft-fonts ref: b076417b5880bd4154bd22f00695b1d28c6bea83 path: .test-inputs/craft-fonts persist-credentials: false - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable components: rustfmt, clippy - - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + - uses: step-security/rust-cache@v2.9.2 with: key: craft-keymap-linux save-if: ${{ github.ref == 'refs/heads/main' }} @@ -71,23 +71,23 @@ jobs: CRAFT_FONTS_DIR: ${{ github.workspace }}/.test-inputs/craft-fonts steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@v7 + - uses: actions/checkout@v7.0.1 with: persist-credentials: false - name: Checkout test fonts - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + uses: actions/checkout@v7.0.1 with: repository: storytold/craft-fonts ref: b076417b5880bd4154bd22f00695b1d28c6bea83 path: .test-inputs/craft-fonts persist-credentials: false - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + - uses: step-security/rust-cache@v2.9.2 with: key: craft-keymap-${{ matrix.os }} save-if: ${{ github.ref == 'refs/heads/main' }} @@ -98,17 +98,17 @@ jobs: runs-on: ubuntu-latest steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@v7 + - uses: actions/checkout@v7.0.1 with: persist-credentials: false - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + - uses: step-security/rust-cache@v2.9.2 with: key: craft-keymap-wasm save-if: ${{ github.ref == 'refs/heads/main' }} diff --git a/.github/workflows/media.yml b/.github/workflows/media.yml index cb3912d54..4814e35ca 100644 --- a/.github/workflows/media.yml +++ b/.github/workflows/media.yml @@ -25,18 +25,18 @@ jobs: runs-on: ubuntu-latest steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@v7 + - uses: actions/checkout@v7.0.1 with: persist-credentials: false - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable components: rustfmt, clippy targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + - uses: step-security/rust-cache@v2.9.2 with: key: craft-media-lint save-if: ${{ github.ref == 'refs/heads/main' }} @@ -56,16 +56,16 @@ jobs: runs-on: ubuntu-latest steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@v7 + - uses: actions/checkout@v7.0.1 with: persist-credentials: false - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + - uses: step-security/rust-cache@v2.9.2 with: key: craft-media-test save-if: ${{ github.ref == 'refs/heads/main' }} diff --git a/.github/workflows/pcraft-format.yml b/.github/workflows/pcraft-format.yml index 177bb4593..9c66b5a10 100644 --- a/.github/workflows/pcraft-format.yml +++ b/.github/workflows/pcraft-format.yml @@ -28,13 +28,13 @@ jobs: runs-on: ${{ matrix.os }} steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/checkout@v7.0.1 with: persist-credentials: false - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: "1.95" components: rustfmt, clippy diff --git a/.github/workflows/pdf.yml b/.github/workflows/pdf.yml index c72ac7f72..25cf71d4e 100644 --- a/.github/workflows/pdf.yml +++ b/.github/workflows/pdf.yml @@ -31,19 +31,19 @@ jobs: RUSTFLAGS: --cfg craft_pdf_unicode_fixtures steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@v7 - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: actions/checkout@v7.0.1 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable components: rustfmt, clippy - - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + - uses: step-security/rust-cache@v2.9.2 with: key: craft-pdf save-if: ${{ github.ref == 'refs/heads/main' }} - - uses: actions/setup-python@v7 + - uses: actions/setup-python@v7.1.0 with: python-version: "3.12" - name: Provision licensed PDF test fonts @@ -61,14 +61,14 @@ jobs: runs-on: ubuntu-latest steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@v7 - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: actions/checkout@v7.0.1 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + - uses: step-security/rust-cache@v2.9.2 with: key: craft-pdf-backends save-if: ${{ github.ref == 'refs/heads/main' }} @@ -81,19 +81,19 @@ jobs: CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUNNER: wasm-bindgen-test-runner steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@v7 - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: actions/checkout@v7.0.1 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + - uses: step-security/rust-cache@v2.9.2 with: key: craft-pdf-wasm save-if: ${{ github.ref == 'refs/heads/main' }} - - uses: actions/setup-python@v7 + - uses: actions/setup-python@v7.1.0 with: python-version: "3.12" - name: Provision licensed PDF test fonts @@ -111,7 +111,7 @@ jobs: - name: Install the matching WASM test runner # A prebuilt, checksum-verified binary instead of building it from source on every run. # A version the pinned action does not list yet falls back to `cargo install --locked`. - uses: step-security/taiki-e-install-action@76747d22a7567cc4438546a84f11bdf18e670ab8 # v2.87.32 + uses: step-security/taiki-e-install-action@v2.87.32 with: tool: wasm-bindgen@${{ steps.wasm-bindgen.outputs.version }} fallback: cargo-install @@ -122,19 +122,19 @@ jobs: runs-on: ubuntu-latest steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@v7 - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: actions/checkout@v7.0.1 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable components: clippy - - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + - uses: step-security/rust-cache@v2.9.2 with: key: craft-plate-test save-if: ${{ github.ref == 'refs/heads/main' }} - - uses: actions/setup-python@v7 + - uses: actions/setup-python@v7.1.0 with: python-version: "3.12" - name: Provision licensed PDF test fonts diff --git a/.github/workflows/print.yml b/.github/workflows/print.yml index 3838e6c42..8e2108e09 100644 --- a/.github/workflows/print.yml +++ b/.github/workflows/print.yml @@ -24,11 +24,11 @@ jobs: runs-on: ${{ matrix.os }} steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@v7 - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: actions/checkout@v7.0.1 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable components: rustfmt, clippy diff --git a/.github/workflows/proof.yml b/.github/workflows/proof.yml index 0035b1c04..10365a230 100644 --- a/.github/workflows/proof.yml +++ b/.github/workflows/proof.yml @@ -25,27 +25,27 @@ jobs: runs-on: ubuntu-latest steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/checkout@v7.0.1 with: persist-credentials: false # The Language data (craft-i18n `language-data/`), embedded by crates/proof/build.rs. # Pinned to storytold/craft-i18n#114's head (#109's SCOWL dictionaries + judgment/judgement, # CP2.1); TODO(CP2.1): move to #114's merge commit once it merges. - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/checkout@v7.0.1 with: repository: storytold/craft-i18n ref: c239f934ace90b7939afaceb23b472ceeafd6b8a path: craft-i18n persist-credentials: false - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable components: rustfmt, clippy targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + - uses: step-security/rust-cache@v2.9.2 with: key: craft-proof save-if: ${{ github.ref == 'refs/heads/main' }} diff --git a/.github/workflows/ui.yml b/.github/workflows/ui.yml index 0892f5a2c..f15ef6ddc 100644 --- a/.github/workflows/ui.yml +++ b/.github/workflows/ui.yml @@ -30,21 +30,21 @@ jobs: runs-on: ${{ matrix.os }} steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@v7 + - uses: actions/checkout@v7.0.1 - name: Install software Vulkan renderer if: runner.os == 'Linux' run: | sudo apt-get update sudo apt-get install -y mesa-vulkan-drivers libvulkan1 echo 'WGPU_BACKEND=vulkan' >> "$GITHUB_ENV" - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable components: rustfmt, clippy - - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + - uses: step-security/rust-cache@v2.9.2 with: key: craft-ui save-if: ${{ github.ref == 'refs/heads/main' }} @@ -59,15 +59,15 @@ jobs: runs-on: ubuntu-latest steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@v7 - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: actions/checkout@v7.0.1 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + - uses: step-security/rust-cache@v2.9.2 with: key: craft-ui-wasm save-if: ${{ github.ref == 'refs/heads/main' }} diff --git a/.github/workflows/update.yml b/.github/workflows/update.yml index f9c8e1498..9a7139026 100644 --- a/.github/workflows/update.yml +++ b/.github/workflows/update.yml @@ -28,15 +28,15 @@ jobs: runs-on: ${{ matrix.os }} steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/checkout@v7.0.1 with: # The token isn't needed after checkout; cargo runs build scripts and proc macros from # dependencies, so don't leave it in .git/config for that third-party code to read. persist-credentials: false - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable components: rustfmt, clippy diff --git a/.github/workflows/vectorcraft-format.yml b/.github/workflows/vectorcraft-format.yml index b2b20463a..74144f30f 100644 --- a/.github/workflows/vectorcraft-format.yml +++ b/.github/workflows/vectorcraft-format.yml @@ -28,13 +28,13 @@ jobs: runs-on: ${{ matrix.os }} steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/checkout@v7.0.1 with: persist-credentials: false - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: "1.95" components: rustfmt, clippy diff --git a/.github/workflows/video.yml b/.github/workflows/video.yml index ec1c16eda..fa667bdfc 100644 --- a/.github/workflows/video.yml +++ b/.github/workflows/video.yml @@ -22,18 +22,18 @@ jobs: runs-on: ubuntu-latest steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/checkout@v7.0.1 with: persist-credentials: false - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: "1.95" components: rustfmt, clippy targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + - uses: step-security/rust-cache@v2.9.2 with: key: craft-video-lint - run: cargo fmt -p craft-video --check @@ -60,16 +60,16 @@ jobs: name: Video tests (${{ matrix.os }}) steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/checkout@v7.0.1 with: persist-credentials: false - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: "1.95" - - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + - uses: step-security/rust-cache@v2.9.2 with: key: craft-video-${{ matrix.os }} - name: Install ffmpeg (Linux) diff --git a/.github/workflows/web-api.yml b/.github/workflows/web-api.yml index 2460fb569..4bf1a30fe 100644 --- a/.github/workflows/web-api.yml +++ b/.github/workflows/web-api.yml @@ -26,13 +26,13 @@ jobs: CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUNNER: wasm-bindgen-test-runner steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/checkout@v7.0.1 with: persist-credentials: false - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable components: rustfmt, clippy @@ -46,7 +46,7 @@ jobs: - name: Install the matching WASM test runner # A prebuilt, checksum-verified binary instead of building it from source on every run. # A version the pinned action does not list yet falls back to `cargo install --locked`. - uses: step-security/taiki-e-install-action@76747d22a7567cc4438546a84f11bdf18e670ab8 # v2.87.32 + uses: step-security/taiki-e-install-action@v2.87.32 with: tool: wasm-bindgen@${{ steps.wasm-bindgen.outputs.version }} fallback: cargo-install diff --git a/.github/workflows/web-host.yml b/.github/workflows/web-host.yml index b780ee76b..76e6701e5 100644 --- a/.github/workflows/web-host.yml +++ b/.github/workflows/web-host.yml @@ -27,18 +27,18 @@ jobs: CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUNNER: wasm-bindgen-test-runner steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: actions/checkout@v7.0.1 with: persist-credentials: false - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable components: rustfmt, clippy targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + - uses: step-security/rust-cache@v2.9.2 with: key: craft-web-host save-if: ${{ github.ref == 'refs/heads/main' }} @@ -55,7 +55,7 @@ jobs: - name: Install the matching WASM test runner # A prebuilt, checksum-verified binary instead of building it from source on every run. # A version the pinned action does not list yet falls back to `cargo install --locked`. - uses: step-security/taiki-e-install-action@76747d22a7567cc4438546a84f11bdf18e670ab8 # v2.87.32 + uses: step-security/taiki-e-install-action@v2.87.32 with: tool: wasm-bindgen@${{ steps.wasm-bindgen.outputs.version }} fallback: cargo-install diff --git a/.github/workflows/window.yml b/.github/workflows/window.yml index b07bce384..f14b24038 100644 --- a/.github/workflows/window.yml +++ b/.github/workflows/window.yml @@ -28,15 +28,15 @@ jobs: runs-on: ${{ matrix.os }} steps: - name: Harden runner - uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + uses: step-security/harden-runner@v2.22.4 with: egress-policy: audit - - uses: actions/checkout@v7 + - uses: actions/checkout@v7.0.1 with: # The token isn't needed after checkout; cargo runs build scripts and proc macros from # dependencies, so don't leave it in .git/config for that third-party code to read. persist-credentials: false - - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable components: rustfmt, clippy diff --git a/sonar-project.properties b/sonar-project.properties index d08c71698..516e4d5cc 100644 --- a/sonar-project.properties +++ b/sonar-project.properties @@ -15,6 +15,14 @@ sonar.cpd.exclusions=**/*tables.rs # S4790 (weak hash): the ICC specification defines the profile ID as the MD5 of the profile, so # no other algorithm produces an ID other software accepts. It identifies, it does not protect. -sonar.issue.ignore.multicriteria=icc_profile_id +sonar.issue.ignore.multicriteria=icc_profile_id,gha-lockfile sonar.issue.ignore.multicriteria.icc_profile_id.ruleKey=rust:S4790 sonar.issue.ignore.multicriteria.icc_profile_id.resourceKey=crates/cms/src/write.rs + +# githubactions:S7637 asks for every action to be pinned to a commit SHA. A workflow covered by +# .github/workflows/actions.lock runs the commit the lockfile records, so its tag refs are pinned +# and the lockfile covers the actions those actions use too. Sonar does not read lockfiles yet, so +# the rule flags the tag refs anyway: +# https://community.sonarsource.com/t/githubactions-s7637-false-positives-for-actions-pinned-through-native-actions-lock/190814 +sonar.issue.ignore.multicriteria.gha-lockfile.ruleKey=githubactions:S7637 +sonar.issue.ignore.multicriteria.gha-lockfile.resourceKey=.github/workflows/** From 5ba5b82fad19ac0baa1058e0cb1535af656a34a8 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Thu, 12 Nov 2026 07:22:55 -0500 Subject: [PATCH 06/51] ci: verify the actions lockfile in CI Fails the build when .github/workflows/actions.lock stops matching the workflows, or when a locked pin no longer verifies upstream, so a stale or tampered lockfile cannot go unnoticed between dependency updates. --- .github/workflows/actions.lock | 3 +++ .github/workflows/lockfile.yml | 34 ++++++++++++++++++++++++++++++++++ 2 files changed, 37 insertions(+) create mode 100644 .github/workflows/lockfile.yml diff --git a/.github/workflows/actions.lock b/.github/workflows/actions.lock index 0d6c3b8f9..c2e897943 100644 --- a/.github/workflows/actions.lock +++ b/.github/workflows/actions.lock @@ -63,6 +63,9 @@ workflows: - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' - 'step-security/rust-cache@v2.9.2' + '.github/workflows/lockfile.yml': + - 'actions/checkout@v7.0.1' + - 'step-security/harden-runner@v2.22.4' '.github/workflows/media.yml': - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' diff --git a/.github/workflows/lockfile.yml b/.github/workflows/lockfile.yml new file mode 100644 index 000000000..e630c9a8f --- /dev/null +++ b/.github/workflows/lockfile.yml @@ -0,0 +1,34 @@ +name: Lockfile + +# Fails when .github/workflows/actions.lock is out of sync with the workflows, or when a locked pin +# no longer verifies upstream, so a moved tag cannot slip a different commit into a run. +# Docs: https://gh.io/actions-lockfile +on: + pull_request: + push: + branches: [main] + workflow_dispatch: + +permissions: + contents: read + +env: + GH_TOKEN: ${{ github.token }} + +jobs: + lockfile: + name: Lockfile is in sync + runs-on: ubuntu-24.04 + timeout-minutes: 10 + steps: + - name: Harden runner + uses: step-security/harden-runner@v2.22.4 + with: + egress-policy: audit + - uses: actions/checkout@v7.0.1 + with: + persist-credentials: false + - name: Install gh-actions-lock + run: gh extension install github/gh-actions-lock --pin v0.4.1 + - name: Verify the lockfile + run: gh actions-lock --verify From 88271c006c375551f58cce8ed773eb31e83eddfb Mon Sep 17 00:00:00 2001 From: midasmatterhorn <248507632+midasmatterhorn@users.noreply.github.com> Date: Thu, 12 Nov 2026 23:43:32 +0300 Subject: [PATCH 07/51] print: cover the 1% scale tolerance boundary in shrink-to-fit The bound had only the zero-scale side tested. Add the other edge: a scale whose four-decimal serialization is more than 1% off. A 118 750 pt wide sheet on Letter with an 18 pt margin scales by 576 / 118 750 = 0.00485053, written 0.0049 -- 1.02% off -- and the plan refuses as an error before anything is sent. Just inside the bound (118 700 pt: 0.98% off) still prints, its matrix carrying the written 0.0049. --- crates/print/src/tests/windows_native.rs | 27 ++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/crates/print/src/tests/windows_native.rs b/crates/print/src/tests/windows_native.rs index 3f5014dcd..bf4335093 100644 --- a/crates/print/src/tests/windows_native.rs +++ b/crates/print/src/tests/windows_native.rs @@ -474,3 +474,30 @@ fn shrink_to_fit_refuses_a_sheet_the_output_cannot_represent() { let refused = plan(&sheets.sheets, (612.0, 792.0), Fit::Shrink { margin: 18.0 }); assert!(matches!(refused, Err(Error::Spool(ref m)) if m.contains("shrink")), "{refused:?}"); } + +#[test] +fn shrink_to_fit_holds_the_one_percent_scale_boundary() { + use crate::sheets::{Fit, plan, read}; + // The matrix carries the scale through the four-decimal formatter, so the plan refuses when + // what would be written is more than 1% off the real scale. Letter with an 18 pt margin gives + // 576 pt of printable width: a 118 700 pt wide, 120 000 pt tall sheet (no quarter turn) scales + // by 576 / 118 700 = 0.00485257, written 0.0049 -- 0.98% short, inside the bound, so it + // prints. + let inside = TestPage { media: Some([0.0, 0.0, 118_700.0, 120_000.0]), ..LETTER }; + let pdf = test_pdf(&[inside], false); + let sheets = read(&pdf).unwrap(); + let edits = plan(&sheets.sheets, (612.0, 792.0), Fit::Shrink { margin: 18.0 }).unwrap(); + let updated = sheets.update(&edits).unwrap(); + let frame = frame_of(&updated, pdf.len()); + let written: f64 = frame.split_whitespace().nth(1).unwrap().parse().unwrap(); + let real = edits[0].frame.as_ref().unwrap().matrix[0]; + assert!(written != real && (written - real).abs() < real * 0.01, "just inside the 1% bound the written scale is accepted: {frame}"); + + // A 118 750 pt wide sheet: 576 / 118 750 = 0.00485053, written 0.0049, 1.02% off -- refused as + // an error before anything is sent, rather than printed a percent too small. + let outside = TestPage { media: Some([0.0, 0.0, 118_750.0, 120_000.0]), ..LETTER }; + let pdf = test_pdf(&[outside], false); + let sheets = read(&pdf).unwrap(); + let refused = plan(&sheets.sheets, (612.0, 792.0), Fit::Shrink { margin: 18.0 }); + assert!(matches!(refused, Err(Error::Spool(ref m)) if m.contains("shrink") && m.contains("nothing was sent")), "{refused:?}"); +} From 714b1f8b3fa9d7d3b4aea5a361a40f8ddc0f9811 Mon Sep 17 00:00:00 2001 From: midasmatterhorn <248507632+midasmatterhorn@users.noreply.github.com> Date: Fri, 13 Nov 2026 00:16:46 +0300 Subject: [PATCH 08/51] cms: index the primaries with an iterator in the 16-way sum clippy's needless_range_loop (stable) flags the loop variable indexing self.prim_n; the offset is still the bit mask. --- crates/cms/src/synth.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/cms/src/synth.rs b/crates/cms/src/synth.rs index e52deb6aa..a9799195c 100644 --- a/crates/cms/src/synth.rs +++ b/crates/cms/src/synth.rs @@ -133,7 +133,7 @@ impl CmykModel { (v + 4.0 * self.tvi[i] * v * (1.0 - v)).clamp(0.0, 1.0) }); let mut s = [0.0; 3]; - for m in 0..16 { + for (m, prim) in self.prim_n.iter().enumerate().take(16) { let mut w = 1.0; for (i, ai) in a.iter().enumerate() { w *= if m & (1 << i) != 0 { *ai } else { 1.0 - ai }; @@ -141,7 +141,7 @@ impl CmykModel { if w == 0.0 { continue; } - for (acc, p) in s.iter_mut().zip(&self.prim_n[m]) { + for (acc, p) in s.iter_mut().zip(prim) { *acc += w * p; } } From 72b6005033e09b8ea2f48943493510cbcdbd8cb6 Mon Sep 17 00:00:00 2001 From: midasmatterhorn <248507632+midasmatterhorn@users.noreply.github.com> Date: Fri, 13 Nov 2026 00:23:49 +0300 Subject: [PATCH 09/51] Revert "cms: index the primaries with an iterator in the 16-way sum" This reverts commit 714b1f8b3fa9d7d3b4aea5a361a40f8ddc0f9811. --- crates/cms/src/synth.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/cms/src/synth.rs b/crates/cms/src/synth.rs index a9799195c..e52deb6aa 100644 --- a/crates/cms/src/synth.rs +++ b/crates/cms/src/synth.rs @@ -133,7 +133,7 @@ impl CmykModel { (v + 4.0 * self.tvi[i] * v * (1.0 - v)).clamp(0.0, 1.0) }); let mut s = [0.0; 3]; - for (m, prim) in self.prim_n.iter().enumerate().take(16) { + for m in 0..16 { let mut w = 1.0; for (i, ai) in a.iter().enumerate() { w *= if m & (1 << i) != 0 { *ai } else { 1.0 - ai }; @@ -141,7 +141,7 @@ impl CmykModel { if w == 0.0 { continue; } - for (acc, p) in s.iter_mut().zip(prim) { + for (acc, p) in s.iter_mut().zip(&self.prim_n[m]) { *acc += w * p; } } From 3c3a83151d380392f61d542ac0560ba65ca69df5 Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Fri, 13 Nov 2026 13:09:56 -0800 Subject: [PATCH 10/51] craft-texture: add bounded float image planes and texture sampling Adds crates/texture (craft-texture), the first step of RFC-0032 (storytold/craft-contrib#50). The code comes from MaterialCraft crates/image/src/lib.rs at 31330629, with its six tests unchanged. No app uses the crate yet. Changes from the source: - Image fields are private; from_data checks the size and the buffer length, so a zero side can no longer reach a panic and a short buffer is rejected instead of read with defaults. - Limits caps the side, pixels and bytes; the try_ constructors and try_map, try_to_kind, try_resize and try_to_rgba8_display reserve memory first and return an error. - Repeat sampling reduces the coordinate to its fractional part, so the period holds at large coordinates. - Bilinear sampling sums the four weighted texels and skips zero weights; box shrinking sums in f64. - generate_uv clamps the size before computing pixel centers. - linear_to_srgb(NaN) returns NaN. - rayon is behind the parallel feature. --- Cargo.lock | 8 + Cargo.toml | 1 + README.md | 3 + crates/texture/Cargo.toml | 19 + crates/texture/README.md | 71 ++++ crates/texture/src/lib.rs | 793 ++++++++++++++++++++++++++++++++++++++ 6 files changed, 895 insertions(+) create mode 100644 crates/texture/Cargo.toml create mode 100644 crates/texture/README.md create mode 100644 crates/texture/src/lib.rs diff --git a/Cargo.lock b/Cargo.lock index f2fbe2d03..669eaf46e 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2380,6 +2380,14 @@ dependencies = [ "unicode-segmentation", ] +[[package]] +name = "craft-texture" +version = "0.1.0" +dependencies = [ + "rayon", + "thiserror 2.0.21", +] + [[package]] name = "craft-tga" version = "0.1.0" diff --git a/Cargo.toml b/Cargo.toml index ac6f09673..8859598f5 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -128,6 +128,7 @@ craft-stencilcraft-document = { path = "crates/stencilcraft-document" } craft-svg-paths = { path = "crates/svg-paths" } craft-stream-codecs = { path = "crates/stream-codecs" } craft-text = { path = "crates/text" } +craft-texture = { path = "crates/texture" } craft-tga = { path = "crates/tga" } craft-timeline = { path = "crates/timeline" } craft-tiff = { path = "crates/tiff" } diff --git a/README.md b/README.md index f6e0a4443..44f7a11c0 100644 --- a/README.md +++ b/README.md @@ -344,6 +344,9 @@ See the [release notes](CHANGELOG.md) for included functionality and known limit - [`craft-text`](crates/text/README.md): text processing below the composer. Its `hyphen` module finds hyphenation points, with a bundled US English dictionary and patterns and optional hypher patterns for 47 more languages (one cargo feature each). +- [`craft-texture`](crates/texture/README.md): linear float image planes, gray or RGBA, with + nearest and bilinear sampling that repeats or clamps, resizing and display conversion. Sizes are + bounded by `Limits`. From MaterialCraft. - [`craft-ui`](crates/ui/README.md): SVG catalogs, icon buttons, tabs, pane controls, transactional docking, print settings and theme helpers for egui frontends; assets, themes, localization and command handling stay in each app. Requires Rust 1.95 or later. - [`craft-vcard`](crates/vcard/README.md): vCard contacts, from MailCraft: vCard 2.1, 3.0 and 4.0 read diff --git a/crates/texture/Cargo.toml b/crates/texture/Cargo.toml new file mode 100644 index 000000000..78868dd87 --- /dev/null +++ b/crates/texture/Cargo.toml @@ -0,0 +1,19 @@ +[package] +name = "craft-texture" +description = "Bounded linear float image planes and texture sampling" +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +repository.workspace = true + +[features] +default = [] +parallel = ["dep:rayon"] + +[lints] +workspace = true + +[dependencies] +rayon = { workspace = true, optional = true } +thiserror = { workspace = true } diff --git a/crates/texture/README.md b/crates/texture/README.md new file mode 100644 index 000000000..877732671 --- /dev/null +++ b/crates/texture/README.md @@ -0,0 +1,71 @@ +# craft-texture + +Linear float image planes and texture sampling. An `Image` is a gray (1 channel) or RGBA plane of +`f32`, row-major with the top row first, shared copy-on-write through an `Arc`. Values are stored +as given, so HDR values above 1 and negative values are kept. The crate has no UI, does no file or +network I/O and has no `unsafe` code. + +- **Construction.** `try_filled`, `try_generate`, `try_generate_uv` and `from_data` check the size + against `Limits` (longest side, pixel count, bytes) before allocating and return an + `ImageError`. `from_data` also checks that the buffer holds width × height × channels floats. + `filled`, `generate`, `generate_uv` and `gray` clamp each side to `1..=MAX_SIDE` (8192). + `try_map`, `try_to_kind`, `try_resize` and `try_to_rgba8_display` reserve their memory first + and return `ImageError::OutOfMemory` when that fails. The forms without `try_` allocate like + `Vec`, which ends the process when memory runs out. +- **Sampling.** `sample` (bilinear) and `sample_nearest` take normalized `(u, v)` with `(0, 0)` at + the upper-left corner and `v` increasing downward, as glTF 2.0 section 3.8.3 defines them + (). `tile` picks repeat (glTF + `REPEAT`) or clamp to edge (`CLAMP_TO_EDGE`) for both axes. The texel coordinate, the wrapping + and the bilinear weights follow the Vulkan specification, sections 20.4.1, 20.6.1 and 20.6.3 + (). + Repeat keeps its period at any finite coordinate. A NaN or infinite coordinate gives + `[0, 0, 0, 1]`. +- **Other operations.** `get` reads one texel, `map`, `to_gray`, `to_color` and `to_kind` convert, + `resize` box-averages whole-factor shrinks and samples bilinearly otherwise, and + `to_rgba8_display` encodes 8-bit sRGB RGBA. `linear_to_srgb`, `srgb_to_linear` and `luminance` + (Rec. 709) are scalar helpers. `resource_key` and `split_resource_key` tag a bitmap name with + its color space. + +Mirrored repeat, mip chains, height to normal, channel packing, decoding and texture-set +recognition are not in the crate yet. + +## Cargo features + +No default features. + +| Feature | Provides | Pulls in | +|---|---|---| +| `parallel` | generated images and display conversion fill rows on several threads; the results are the same | `rayon` | + +Without `parallel` the crate builds for `wasm32-unknown-unknown`. + +## Limits + +| Field | Default | Checked by | +|---|---|---| +| `max_side` | 8192 | every `try_` constructor and `from_data` | +| `max_pixels` | 2^26 (8192 × 8192) | the same | +| `max_bytes` | 1 GiB (an 8192 × 8192 RGBA plane) | the same | + +## Origin + +| Part | Source | +|---|---| +| `Image`, `Kind`, sampling, resizing, conversions, sRGB helpers, resource keys and the six tests `sample_survives_huge_coordinates`, `resource_keys_round_trip`, `sample_wraps_and_clamps`, `resize_box_and_bilinear`, `hostile_sizes_are_clamped`, `conversions` | MaterialCraft `crates/image/src/lib.rs` at [3133062](https://github.com/storytold/materialcraft/commit/3133062968b8a1566eda12a357cb06062db16687) | +| `Limits`, the `try_` constructors, `from_data`, private fields with getters, the `parallel` feature | written here | + +## Migration + +| App | Status | +|---|---| +| MaterialCraft | `materialcraft-image` is the source. The app switches to this crate in its own pull request. | +| EffectCraft | Its texture sampling moves into this crate later, with mirrored repeat. | + +For MaterialCraft: + +| `materialcraft-image` | craft-texture | +| --- | --- | +| `image.w`, `image.h`, `image.kind`, `image.data` | `width()`, `height()`, `kind()`, `data()` and `shared_data()` | +| `Image { w, h, kind, data }` built by hand | `Image::from_data(w, h, kind, data, &Limits::default())` | +| `rayon` always on | the `parallel` feature | +| `linear_to_srgb(NaN)` returned −0.055 | it returns NaN | diff --git a/crates/texture/src/lib.rs b/crates/texture/src/lib.rs new file mode 100644 index 000000000..272ce1c22 --- /dev/null +++ b/crates/texture/src/lib.rs @@ -0,0 +1,793 @@ +//! # craft-texture +//! +//! Linear float image planes and texture sampling. An [`Image`] is a grayscale (1 channel) or +//! color (RGBA) plane of `f32`, row-major with the top row first, shared copy-on-write through an +//! `Arc` so a copy costs a reference count. Values are stored as given: HDR values above 1, +//! negative values and non-finite values are kept. +//! +//! Sampling takes normalized `(u, v)` with `(0, 0)` at the upper-left corner and `v` increasing +//! downward, as glTF 2.0 section 3.8.3 defines texture coordinates +//! (). The `tile` argument picks the +//! wrap mode of both axes: repeat (glTF `REPEAT`, 10497) or clamp to edge (`CLAMP_TO_EDGE`, 33071). +//! [`Image::sample_nearest`] and [`Image::sample`] (bilinear) use the texel coordinates, wrapping +//! and weights of the Vulkan specification, sections 20.4.1, 20.6.1 and 20.6.3 +//! (). +//! +//! Sizes are bounded. [`Limits`] caps the side, the pixel count and the bytes, and the `try_` +//! constructors return an [`ImageError`] before allocating anything over them. The constructors +//! without `try_` clamp each side to `1..=MAX_SIDE`. Every operation that allocates has a `try_` +//! form that reserves its memory first and returns [`ImageError::OutOfMemory`] when that fails; the +//! forms without `try_` allocate like `Vec`, which ends the process when memory runs out. Rows are +//! generated on several threads only with the `parallel` feature. +#![forbid(unsafe_code)] +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] + +use std::sync::Arc; + +#[cfg(feature = "parallel")] +use rayon::prelude::*; + +/// Largest side the clamping constructors make, and the default [`Limits::max_side`]. +pub const MAX_SIDE: u32 = 8192; + +/// Whether an image holds one channel or four. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] +pub enum Kind { + Gray, + Color, +} + +impl Kind { + pub fn channels(self) -> usize { + match self { + Kind::Gray => 1, + Kind::Color => 4, + } + } +} + +/// Why an image could not be made. +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +#[non_exhaustive] +pub enum ImageError { + /// A side is zero or longer than [`Limits::max_side`]. + #[error("image size {0}x{1} has a zero side or a side over the limit")] + BadSize(u32, u32), + /// The pixel count or the byte count is over [`Limits`]. + #[error("image size {0}x{1} needs more pixels or bytes than the limits allow")] + TooLarge(u32, u32), + /// The float buffer does not hold width × height × channels values. + #[error("image data holds {found} floats where {expected} are needed")] + BadDataLength { expected: usize, found: usize }, + /// Memory for the pixels could not be reserved. + #[error("not enough memory for a {0}x{1} image")] + OutOfMemory(u32, u32), +} + +/// Caps on the size of an image, checked before anything is allocated. +/// `#[non_exhaustive]`: start from [`Limits::default`] and set the fields you change. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +#[non_exhaustive] +pub struct Limits { + /// Longest side in pixels. Default [`MAX_SIDE`]. + pub max_side: u32, + /// Most pixels (width × height). Default 2^26, which is 8192 × 8192. + pub max_pixels: u64, + /// Most bytes of float data (pixels × channels × 4). Default 1 GiB, an 8192 × 8192 color plane. + pub max_bytes: u64, +} + +impl Default for Limits { + fn default() -> Self { + Self { max_side: MAX_SIDE, max_pixels: 1 << 26, max_bytes: 1 << 30 } + } +} + +impl Limits { + /// The number of floats a `w × h` image of `kind` holds, or the error the limits give for that + /// size. Nothing is allocated. + pub fn check(&self, w: u32, h: u32, kind: Kind) -> Result { + if w == 0 || h == 0 || w > self.max_side || h > self.max_side { + return Err(ImageError::BadSize(w, h)); + } + let too_large = ImageError::TooLarge(w, h); + let pixels = u64::from(w).checked_mul(u64::from(h)).ok_or_else(|| too_large.clone())?; + let floats = pixels.checked_mul(kind.channels() as u64).ok_or_else(|| too_large.clone())?; + let bytes = floats.checked_mul(size_of::() as u64).ok_or_else(|| too_large.clone())?; + if pixels > self.max_pixels || bytes > self.max_bytes { + return Err(too_large); + } + usize::try_from(floats).map_err(|_| too_large) + } +} + +/// A gray or RGBA plane of linear `f32`. Width and height are at least 1, and the data holds +/// exactly width × height × channels floats. +#[derive(Clone, Debug)] +pub struct Image { + w: u32, + h: u32, + kind: Kind, + /// Row-major, `kind.channels()` floats per pixel. + data: Arc>, +} + +impl PartialEq for Image { + fn eq(&self, o: &Image) -> bool { + self.w == o.w && self.h == o.h && self.kind == o.kind && (Arc::ptr_eq(&self.data, &o.data) || self.data == o.data) + } +} + +/// Clamp a requested size into `1..=MAX_SIDE` on each side. +pub fn clamp_size(w: u32, h: u32) -> (u32, u32) { + (w.clamp(1, MAX_SIDE), h.clamp(1, MAX_SIDE)) +} + +/// Integer texel index `i` on an axis of `n >= 1` texels: `i mod n` when repeating, otherwise +/// clamped to `0..=n - 1`. +#[inline] +fn wrap(i: i64, n: u32, tile: bool) -> usize { + let n = i64::from(n.max(1)); + if tile { i.rem_euclid(n) as usize } else { i.clamp(0, n - 1) as usize } +} + +/// The largest `f32` below 1. +const BELOW_ONE: f32 = 1.0 - f32::EPSILON / 2.0; + +/// A normalized coordinate brought into a range whose texel indices fit in `i64`: its fractional +/// part, below 1, when repeating, since the repeat period is 1, and `-1..=2` when clamping, where +/// every value outside `0..=1` already selects an edge texel. `None` for NaN and infinity. +#[inline] +fn reduce(t: f32, tile: bool) -> Option { + if !t.is_finite() { + return None; + } + Some(if tile { t.rem_euclid(1.0).min(BELOW_ONE) } else { t.clamp(-1.0, 2.0) }) +} + +/// Fill `data` row by row with `f(x, y)`, keeping the first `c` channels of each result. +fn fill [f32; 4] + Sync>(data: &mut [f32], w: u32, c: usize, f: &F) { + let row_len = (w as usize).max(1) * c; + let fill_row = |(y, row): (usize, &mut [f32])| { + for (x, px) in row.chunks_exact_mut(c).enumerate() { + let p = f(x as u32, y as u32); + px.copy_from_slice(&p[..c]); + } + }; + #[cfg(feature = "parallel")] + data.par_chunks_mut(row_len).enumerate().for_each(fill_row); + #[cfg(not(feature = "parallel"))] + data.chunks_mut(row_len).enumerate().for_each(fill_row); +} + +impl Image { + /// An image of a size already inside `1..=MAX_SIDE` or taken from an existing image. + fn build [f32; 4] + Sync>(w: u32, h: u32, kind: Kind, f: F) -> Image { + let len = (w as usize).saturating_mul(h as usize).saturating_mul(kind.channels()); + let mut data = vec![0.0f32; len]; + fill(&mut data, w, kind.channels(), &f); + Image { w, h, kind, data: Arc::new(data) } + } + + /// An image checked against `limits`, with its memory reserved before any pixel is generated. + fn try_build [f32; 4] + Sync>(w: u32, h: u32, kind: Kind, limits: &Limits, f: F) -> Result { + let len = limits.check(w, h, kind)?; + let mut data = Vec::new(); + data.try_reserve_exact(len).map_err(|_| ImageError::OutOfMemory(w, h))?; + data.resize(len, 0.0); + fill(&mut data, w, kind.channels(), &f); + Ok(Image { w, h, kind, data: Arc::new(data) }) + } + + /// A constant image, each side clamped to `1..=MAX_SIDE`. + pub fn filled(w: u32, h: u32, kind: Kind, v: [f32; 4]) -> Image { + let (w, h) = clamp_size(w, h); + Image::build(w, h, kind, |_, _| v) + } + + /// A constant image, or an error when the size is outside `limits` or memory runs out. + pub fn try_filled(w: u32, h: u32, kind: Kind, v: [f32; 4], limits: &Limits) -> Result { + Image::try_build(w, h, kind, limits, |_, _| v) + } + + /// Generate every pixel with `f(x, y)` (pixel indices), each side clamped to `1..=MAX_SIDE`. + pub fn generate(w: u32, h: u32, kind: Kind, f: impl Fn(u32, u32) -> [f32; 4] + Sync) -> Image { + let (w, h) = clamp_size(w, h); + Image::build(w, h, kind, f) + } + + /// Generate every pixel with `f(x, y)`, or return an error when the size is outside `limits` + /// or memory runs out. + pub fn try_generate(w: u32, h: u32, kind: Kind, limits: &Limits, f: impl Fn(u32, u32) -> [f32; 4] + Sync) -> Result { + Image::try_build(w, h, kind, limits, f) + } + + /// Generate from normalized coordinates at the pixel centers, `(x + 0.5) / w` and + /// `(y + 0.5) / h`, each side clamped to `1..=MAX_SIDE` first. + pub fn generate_uv(w: u32, h: u32, kind: Kind, f: impl Fn(f32, f32) -> [f32; 4] + Sync) -> Image { + let (w, h) = clamp_size(w, h); + let (iw, ih) = (1.0 / w as f32, 1.0 / h as f32); + Image::build(w, h, kind, |x, y| f((x as f32 + 0.5) * iw, (y as f32 + 0.5) * ih)) + } + + /// [`Image::generate_uv`] for a size checked against `limits`. + pub fn try_generate_uv(w: u32, h: u32, kind: Kind, limits: &Limits, f: impl Fn(f32, f32) -> [f32; 4] + Sync) -> Result { + let (iw, ih) = (1.0 / w.max(1) as f32, 1.0 / h.max(1) as f32); + Image::try_build(w, h, kind, limits, |x, y| f((x as f32 + 0.5) * iw, (y as f32 + 0.5) * ih)) + } + + pub fn gray(w: u32, h: u32, f: impl Fn(u32, u32) -> f32 + Sync) -> Image { + Image::generate(w, h, Kind::Gray, |x, y| [f(x, y), 0.0, 0.0, 0.0]) + } + + /// An image over existing row-major data, checked against `limits` and against the length + /// width × height × channels. The data is not copied. + pub fn from_data(w: u32, h: u32, kind: Kind, data: impl Into>>, limits: &Limits) -> Result { + let expected = limits.check(w, h, kind)?; + let data = data.into(); + if data.len() != expected { + return Err(ImageError::BadDataLength { expected, found: data.len() }); + } + Ok(Image { w, h, kind, data }) + } + + pub fn width(&self) -> u32 { + self.w + } + + pub fn height(&self) -> u32 { + self.h + } + + pub fn kind(&self) -> Kind { + self.kind + } + + /// The row-major floats, `channels()` per pixel. + pub fn data(&self) -> &[f32] { + self.data.as_slice() + } + + /// The shared buffer behind [`Image::data`]. + pub fn shared_data(&self) -> &Arc> { + &self.data + } + + pub fn channels(&self) -> usize { + self.kind.channels() + } + + pub fn is_gray(&self) -> bool { + self.kind == Kind::Gray + } + + /// The pixel at integer coordinates (wrapped or clamped), as RGBA (gray → `[v, v, v, 1]`). + #[inline] + pub fn get(&self, x: i64, y: i64, tile: bool) -> [f32; 4] { + let (x, y) = (wrap(x, self.w, tile), wrap(y, self.h, tile)); + let i = y * self.w as usize + x; + match self.kind { + Kind::Gray => { + let v = self.data.get(i).copied().unwrap_or(0.0); + [v, v, v, 1.0] + } + Kind::Color => { + let s = self.data.get(i * 4..i * 4 + 4).unwrap_or(&[0.0, 0.0, 0.0, 1.0]); + [s[0], s[1], s[2], s[3]] + } + } + } + + /// The gray value, or the Rec. 709 luminance of a color image. + #[inline] + pub fn get_gray(&self, x: i64, y: i64, tile: bool) -> f32 { + let p = self.get(x, y, tile); + match self.kind { + Kind::Gray => p[0], + Kind::Color => luminance(p), + } + } + + /// Bilinear sample at normalized `(u, v)`; pixel centers sit at `(i + 0.5) / w`. The texel + /// coordinate is `u × w − 0.5`; its floor and the next index are wrapped or clamped, and the + /// four texels are weighted `(1 − α)(1 − β)`, `α(1 − β)`, `(1 − α)β` and `αβ` by the fractional + /// parts `α` and `β`. A texel with weight 0 does not enter the sum, so an infinite neighbor + /// leaves a sample at a texel center unchanged. NaN or infinite coordinates give `[0, 0, 0, 1]`. + #[inline] + pub fn sample(&self, u: f32, v: f32, tile: bool) -> [f32; 4] { + let (Some(u), Some(v)) = (reduce(u, tile), reduce(v, tile)) else { + return [0.0, 0.0, 0.0, 1.0]; + }; + let fx = u * self.w as f32 - 0.5; + let fy = v * self.h as f32 - 0.5; + let (x0, y0) = (fx.floor(), fy.floor()); + let (tx, ty) = (fx - x0, fy - y0); + let (x0, y0) = (x0 as i64, y0 as i64); + let taps = [((1.0 - tx) * (1.0 - ty), x0, y0), (tx * (1.0 - ty), x0 + 1, y0), ((1.0 - tx) * ty, x0, y0 + 1), (tx * ty, x0 + 1, y0 + 1)]; + let mut o = [0.0; 4]; + for (weight, x, y) in taps { + if weight == 0.0 { + continue; + } + let p = self.get(x, y, tile); + for (o, p) in o.iter_mut().zip(p) { + *o += weight * p; + } + } + o + } + + #[inline] + pub fn sample_gray(&self, u: f32, v: f32, tile: bool) -> f32 { + let p = self.sample(u, v, tile); + match self.kind { + Kind::Gray => p[0], + Kind::Color => luminance(p), + } + } + + /// Nearest sample at normalized `(u, v)`: the texel `floor(u × w)`, wrapped or clamped. NaN or + /// infinite coordinates give `[0, 0, 0, 1]`. + #[inline] + pub fn sample_nearest(&self, u: f32, v: f32, tile: bool) -> [f32; 4] { + let (Some(u), Some(v)) = (reduce(u, tile), reduce(v, tile)) else { + return [0.0, 0.0, 0.0, 1.0]; + }; + let (x, y) = ((u * self.w as f32).floor() as i64, (v * self.h as f32).floor() as i64); + // A repeated coordinate is below 1, so its texel is below the size even where `u × w` + // rounds up to it. + let (x, y) = if tile { (x.min(i64::from(self.w) - 1), y.min(i64::from(self.h) - 1)) } else { (x, y) }; + self.get(x, y, tile) + } + + /// Map every pixel (as RGBA) to a new image of `kind`, same size. + pub fn map(&self, kind: Kind, f: impl Fn([f32; 4]) -> [f32; 4] + Sync) -> Image { + Image::build(self.w, self.h, kind, |x, y| f(self.get(i64::from(x), i64::from(y), false))) + } + + /// [`Image::map`] with the new image checked against `limits` and its memory reserved first. + pub fn try_map(&self, kind: Kind, limits: &Limits, f: impl Fn([f32; 4]) -> [f32; 4] + Sync) -> Result { + Image::try_build(self.w, self.h, kind, limits, |x, y| f(self.get(i64::from(x), i64::from(y), false))) + } + + /// [`Image::to_kind`] with the result checked against `limits`, also when the kind is + /// unchanged, and the memory of a new image reserved first. + pub fn try_to_kind(&self, kind: Kind, limits: &Limits) -> Result { + limits.check(self.w, self.h, kind)?; + match (self.kind, kind) { + (Kind::Gray, Kind::Gray) | (Kind::Color, Kind::Color) => Ok(self.clone()), + (Kind::Color, Kind::Gray) => self.try_map(Kind::Gray, limits, |p| [luminance(p), 0.0, 0.0, 0.0]), + (Kind::Gray, Kind::Color) => self.try_map(Kind::Color, limits, |p| p), + } + } + + /// This image as grayscale (luminance of a color image). + pub fn to_gray(&self) -> Image { + match self.kind { + Kind::Gray => self.clone(), + Kind::Color => self.map(Kind::Gray, |p| [luminance(p), 0.0, 0.0, 0.0]), + } + } + + /// This image as RGBA (gray copied to RGB, alpha 1). + pub fn to_color(&self) -> Image { + match self.kind { + Kind::Color => self.clone(), + Kind::Gray => self.map(Kind::Color, |p| p), + } + } + + pub fn to_kind(&self, kind: Kind) -> Image { + match kind { + Kind::Gray => self.to_gray(), + Kind::Color => self.to_color(), + } + } + + /// Resample to `w × h`, each side clamped to `1..=MAX_SIDE`: a box average when both sides + /// shrink by whole factors, otherwise bilinear samples at the new pixel centers. + pub fn resize(&self, w: u32, h: u32, tile: bool) -> Image { + let (w, h) = clamp_size(w, h); + if w == self.w && h == self.h { + return self.clone(); + } + Image::build(w, h, self.kind, self.resampler(w, h, tile)) + } + + /// [`Image::resize`] without the clamp: the new size is checked against `limits`, also when it + /// equals the current size, and its memory reserved first. + pub fn try_resize(&self, w: u32, h: u32, tile: bool, limits: &Limits) -> Result { + limits.check(w, h, self.kind)?; + if w == self.w && h == self.h { + return Ok(self.clone()); + } + Image::try_build(w, h, self.kind, limits, self.resampler(w, h, tile)) + } + + /// The pixel function of a resample to `w × h`, both at least 1. + fn resampler(&self, w: u32, h: u32, tile: bool) -> Box [f32; 4] + Sync + '_> { + let (w, h) = (w.max(1), h.max(1)); + if w <= self.w && h <= self.h && self.w.is_multiple_of(w) && self.h.is_multiple_of(h) { + let (fx, fy) = (i64::from(self.w / w), i64::from(self.h / h)); + let inv = 1.0 / (fx * fy) as f64; + return Box::new(move |x, y| { + // Summed in f64, so finite HDR values near `f32::MAX` average without overflow. + let mut s = [0.0f64; 4]; + for j in 0..fy { + for i in 0..fx { + let p = self.get(i64::from(x) * fx + i, i64::from(y) * fy + j, tile); + for (s, p) in s.iter_mut().zip(p) { + *s += f64::from(p); + } + } + } + s.map(|v| (v * inv) as f32) + }); + } + let (iw, ih) = (1.0 / w as f32, 1.0 / h as f32); + Box::new(move |x, y| self.sample((x as f32 + 0.5) * iw, (y as f32 + 0.5) * ih, tile)) + } + + /// Raw float access for gray images (`None` for color). + pub fn gray_data(&self) -> Option<&[f32]> { + (self.kind == Kind::Gray).then_some(self.data.as_slice()) + } + + /// 8-bit sRGB-encoded RGBA for display (gray shown as is; color through the sRGB curve). + /// Values are clamped to `0..=1` first; NaN becomes 0. + pub fn to_rgba8_display(&self) -> Vec { + let mut out = vec![0u8; self.display_len()]; + self.fill_display(&mut out); + out + } + + /// [`Image::to_rgba8_display`] with its memory reserved first. + pub fn try_to_rgba8_display(&self) -> Result, ImageError> { + let len = self.display_len(); + let mut out = Vec::new(); + out.try_reserve_exact(len).map_err(|_| ImageError::OutOfMemory(self.w, self.h))?; + out.resize(len, 0); + self.fill_display(&mut out); + Ok(out) + } + + /// Bytes of the display copy: 4 per pixel, never more than the float data's own bytes. + fn display_len(&self) -> usize { + self.data.len() / self.channels() * 4 + } + + fn fill_display(&self, out: &mut [u8]) { + let q = |v: f32| (v.clamp(0.0, 1.0) * 255.0 + 0.5) as u8; + let pixel = |(i, px): (usize, &mut [u8])| match self.kind { + Kind::Gray => { + let v = q(self.data.get(i).copied().unwrap_or(0.0)); + px.copy_from_slice(&[v, v, v, 255]); + } + Kind::Color => { + let s = self.data.get(i * 4..i * 4 + 4).unwrap_or(&[0.0, 0.0, 0.0, 1.0]); + px.copy_from_slice(&[q(linear_to_srgb(s[0])), q(linear_to_srgb(s[1])), q(linear_to_srgb(s[2])), q(s[3])]); + } + }; + #[cfg(feature = "parallel")] + out.par_chunks_mut(4).enumerate().for_each(pixel); + #[cfg(not(feature = "parallel"))] + out.chunks_mut(4).enumerate().for_each(pixel); + } + + /// Mean of each channel (as RGBA), e.g. for tests and auto levels. A NaN or infinite pixel + /// makes its channel's mean non-finite. + pub fn mean(&self) -> [f32; 4] { + let c = self.channels(); + let n = f64::from(self.w) * f64::from(self.h); + let mut s = [0f64; 4]; + for px in self.data.chunks(c) { + for (k, v) in px.iter().enumerate() { + s[k] += f64::from(*v); + } + } + if c == 1 { + let m = (s[0] / n) as f32; + return [m, m, m, 1.0]; + } + s.map(|v| (v / n) as f32) + } + + /// Minimum and maximum over all channels (alpha excluded). NaN values are skipped; `(0, 0)` + /// when every value is NaN. + pub fn range(&self) -> (f32, f32) { + let c = self.channels(); + let mut lo = f32::INFINITY; + let mut hi = f32::NEG_INFINITY; + for px in self.data.chunks(c) { + for v in px.iter().take(c.min(3)) { + lo = lo.min(*v); + hi = hi.max(*v); + } + } + if lo > hi { (0.0, 0.0) } else { (lo, hi) } + } +} + +/// Rec. 709 luminance of a linear RGB(A) pixel. +#[inline] +pub fn luminance(p: [f32; 4]) -> f32 { + 0.2126 * p[0] + 0.7152 * p[1] + 0.0722 * p[2] +} + +/// The sRGB encoding of a linear value. NaN stays NaN. +#[inline] +pub fn linear_to_srgb(v: f32) -> f32 { + if v.is_nan() || v <= 0.003_130_8 { v * 12.92 } else { 1.055 * v.powf(1.0 / 2.4) - 0.055 } +} + +/// The linear value of an sRGB-encoded value. NaN stays NaN. +#[inline] +pub fn srgb_to_linear(v: f32) -> f32 { + if v <= 0.04045 { v / 12.92 } else { ((v + 0.055) / 1.055).powf(2.4) } +} + +/// Encode the bitmap name and its requested color space without ambiguity. +/// Plain sRGB names remain readable by simple resource callbacks. +pub fn resource_key(name: &str, linear: bool) -> String { + if linear { + format!("\u{1}L{name}") + } else if name.starts_with('\u{1}') { + format!("\u{1}S{name}") + } else { + name.to_string() + } +} + +/// Split a key made by [`resource_key`] into its name and data-map flag. +pub fn split_resource_key(key: &str) -> (&str, bool) { + if let Some(name) = key.strip_prefix("\u{1}L") { + (name, true) + } else if let Some(name) = key.strip_prefix("\u{1}S") { + (name, false) + } else { + (key, false) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn sample_survives_huge_coordinates() { + let img = Image::gray(8, 8, |x, _| x as f32); + for u in [1.0e30_f32, -1.0e30, f32::MAX, f32::MIN] { + for tile in [true, false] { + let p = img.sample(u, u, tile); + assert!(p.iter().all(|c| c.is_finite())); + } + } + } + + #[test] + fn resource_keys_round_trip() { + for name in ["n", "", "\u{1}Lnormal", "\u{1}Sn", "n\u{1}linear"] { + for linear in [false, true] { + assert_eq!(split_resource_key(&resource_key(name, linear)), (name, linear)); + } + } + } + + #[test] + fn sample_wraps_and_clamps() { + let img = Image::gray(4, 1, |x, _| x as f32); + assert_eq!(img.get(-1, 0, true)[0], 3.0); + assert_eq!(img.get(-1, 0, false)[0], 0.0); + // Halfway between the last and the (wrapped) first pixel. + assert!((img.sample(1.0, 0.5, true)[0] - 1.5).abs() < 1e-5); + } + + #[test] + fn resize_box_and_bilinear() { + let img = Image::gray(4, 4, |x, _| if x < 2 { 0.0 } else { 1.0 }); + let small = img.resize(2, 2, true); + assert_eq!(small.data.as_slice(), &[0.0, 1.0, 0.0, 1.0]); + let big = small.resize(8, 8, false); + assert_eq!(big.w, 8); + assert!(big.data[0] < big.data[7]); + } + + #[test] + fn hostile_sizes_are_clamped() { + let img = Image::filled(0, u32::MAX, Kind::Gray, [0.5; 4]); + assert_eq!((img.w, img.h), (1, MAX_SIDE)); + assert_eq!(img.sample(f32::NAN, 0.0, true), [0.0, 0.0, 0.0, 1.0]); + } + + #[test] + fn conversions() { + let c = Image::filled(2, 2, Kind::Color, [1.0, 1.0, 1.0, 1.0]); + assert!((c.to_gray().data[0] - 1.0).abs() < 1e-5); + assert_eq!(c.to_rgba8_display()[0], 255); + } + + /// Texel values 0, 5 and 1: the blend of the last and first texels (0.5) differs from the + /// middle texel (5), so a wrong repeat period shows. + fn stripe() -> Image { + Image::gray(3, 1, |x, _| [0.0, 5.0, 1.0][x as usize]) + } + + #[test] + fn repeat_keeps_its_period_at_large_coordinates() { + let img = stripe(); + // Every whole number repeats u = 0, which falls halfway between the last and first texels. + let at_zero = img.sample(0.0, 0.5, true)[0]; + assert!((at_zero - 0.5).abs() < 1e-6); + for u in [1.0e9_f32, -1.0e9, 4.0e9, 3.0e12] { + assert_eq!(img.sample(u, 0.5, true)[0], at_zero, "bilinear u = {u}"); + assert_eq!(img.sample_nearest(u, 0.5, true)[0], 0.0, "nearest u = {u}"); + } + assert_eq!(img.sample_nearest(1.0e19, 0.5, true)[0], 0.0); + assert_eq!(img.sample_nearest(-1.0e19, 0.5, true)[0], 0.0); + } + + #[test] + fn clamp_selects_the_edges_at_large_coordinates() { + let img = stripe(); + for u in [2.0_f32, 1.0e9, 1.0e19, f32::MAX] { + assert_eq!(img.sample(u, 0.5, false)[0], 1.0); + assert_eq!(img.sample_nearest(u, 0.5, false)[0], 1.0); + } + for u in [-1.0_f32, -1.0e9, -1.0e19, f32::MIN] { + assert_eq!(img.sample(u, 0.5, false)[0], 0.0); + assert_eq!(img.sample_nearest(u, 0.5, false)[0], 0.0); + } + } + + #[test] + fn nearest_follows_the_texel_floor() { + let img = Image::gray(4, 1, |x, _| x as f32); + // floor(u × 4): u = 1.0 repeats to texel 0 and clamps to texel 3. + assert_eq!(img.sample_nearest(0.24, 0.5, true)[0], 0.0); + assert_eq!(img.sample_nearest(0.25, 0.5, true)[0], 1.0); + assert_eq!(img.sample_nearest(1.0, 0.5, true)[0], 0.0); + assert_eq!(img.sample_nearest(1.0, 0.5, false)[0], 3.0); + assert_eq!(img.sample_nearest(-0.01, 0.5, true)[0], 3.0); + } + + #[test] + fn bilinear_weights_follow_the_fractional_texel_coordinate() { + // u × 4 − 0.5 = 1.25: texel 1 weighted 0.75 and texel 2 weighted 0.25. + let img = Image::gray(4, 1, |x, _| [0.0, 2.0, 6.0, 0.0][x as usize]); + assert!((img.sample(1.75 / 4.0, 0.5, false)[0] - 3.0).abs() < 1e-6); + // Two axes: the four texels of a 2 × 2 image at the image center weigh a quarter each. + let sq = Image::gray(2, 2, |x, y| [1.0, 3.0, 5.0, 11.0][(y * 2 + x) as usize]); + assert!((sq.sample(0.5, 0.5, false)[0] - 5.0).abs() < 1e-6); + } + + #[test] + fn small_negative_coordinates_repeat_to_the_last_texel() { + let img = Image::gray(4, 1, |x, _| x as f32); + for u in [-1.0e-8_f32, -1.0e-30, -f32::MIN_POSITIVE] { + assert_eq!(img.sample_nearest(u, 0.5, true)[0], 3.0, "u = {u}"); + assert!((img.sample(u, 0.5, true)[0] - 1.5).abs() < 1e-5, "u = {u}"); + } + let wide = Image::gray(MAX_SIDE, 1, |x, _| x as f32); + assert_eq!(wide.sample_nearest(-1.0e-8, 0.5, true)[0], (MAX_SIDE - 1) as f32); + } + + #[test] + fn bilinear_ignores_zero_weight_texels_and_does_not_overflow() { + let l = Limits::default(); + let Ok(img) = Image::from_data(2, 1, Kind::Gray, vec![1.0, f32::INFINITY], &l) else { panic!("valid 2 x 1 image") }; + // The center of texel 0 gives texel 0, though its neighbor is infinite. + assert_eq!(img.sample(0.25, 0.5, false)[0], 1.0); + let Ok(hdr) = Image::from_data(2, 1, Kind::Gray, vec![f32::MAX, -f32::MAX], &l) else { panic!("valid 2 x 1 image") }; + assert_eq!(hdr.sample(0.5, 0.5, false)[0], 0.0); + } + + #[test] + fn box_shrink_averages_large_hdr_values() { + let img = Image::filled(2, 2, Kind::Color, [f32::MAX, -f32::MAX, 1.0, 1.0]); + assert_eq!(img.resize(1, 1, false).data(), &[f32::MAX, -f32::MAX, 1.0, 1.0]); + } + + #[test] + fn fallible_operations_check_the_limits() { + let img = Image::gray(4, 4, |x, y| (x + 4 * y) as f32); + let l = Limits::default(); + assert_eq!(img.try_resize(2, 2, true, &l), Ok(img.resize(2, 2, true))); + assert_eq!(img.try_resize(7, 3, false, &l), Ok(img.resize(7, 3, false))); + assert_eq!(img.try_resize(0, 2, false, &l), Err(ImageError::BadSize(0, 2))); + let small = Limits { max_bytes: 100, ..Limits::default() }; + assert_eq!(img.try_resize(8, 8, false, &small), Err(ImageError::TooLarge(8, 8))); + assert_eq!(img.try_to_kind(Kind::Color, &small), Err(ImageError::TooLarge(4, 4))); + assert_eq!(img.try_to_kind(Kind::Color, &l), Ok(img.to_color())); + assert_eq!(img.try_to_kind(Kind::Gray, &small), Ok(img.clone())); + assert_eq!(img.try_map(Kind::Gray, &l, |p| [p[0] * 2.0; 4]), Ok(img.map(Kind::Gray, |p| [p[0] * 2.0; 4]))); + assert_eq!(img.try_to_rgba8_display(), Ok(img.to_rgba8_display())); + } + + #[test] + fn unchanged_results_are_checked_against_the_limits() { + let img = Image::gray(4, 4, |x, y| (x + 4 * y) as f32); + let tiny = Limits { max_pixels: 8, ..Limits::default() }; + assert_eq!(img.try_resize(4, 4, false, &tiny), Err(ImageError::TooLarge(4, 4))); + assert_eq!(img.try_to_kind(Kind::Gray, &tiny), Err(ImageError::TooLarge(4, 4))); + let narrow = Limits { max_side: 3, ..Limits::default() }; + assert_eq!(img.try_resize(4, 4, false, &narrow), Err(ImageError::BadSize(4, 4))); + } + + #[test] + fn generate_uv_spans_the_clamped_size() { + let img = Image::generate_uv(MAX_SIDE + 100, 1, Kind::Gray, |u, _| [u, 0.0, 0.0, 0.0]); + assert_eq!(img.w, MAX_SIDE); + let last = img.data[MAX_SIDE as usize - 1]; + assert!((last - (MAX_SIDE as f32 - 0.5) / MAX_SIDE as f32).abs() < 1e-6, "{last}"); + } + + #[test] + fn checked_sizes_reject_zero_and_long_sides() { + let l = Limits::default(); + assert_eq!(Image::try_filled(0, 4, Kind::Gray, [0.0; 4], &l), Err(ImageError::BadSize(0, 4))); + assert_eq!(Image::try_filled(4, 0, Kind::Color, [0.0; 4], &l), Err(ImageError::BadSize(4, 0))); + assert_eq!(Image::from_data(0, 1, Kind::Gray, Vec::new(), &l), Err(ImageError::BadSize(0, 1))); + assert_eq!(Image::try_generate(MAX_SIDE + 1, 1, Kind::Gray, &l, |_, _| [0.0; 4]), Err(ImageError::BadSize(MAX_SIDE + 1, 1))); + assert!(Image::try_filled(3, 2, Kind::Color, [0.25; 4], &l).is_ok_and(|i| i.data().len() == 24 && i.width() == 3)); + } + + #[test] + fn checked_sizes_respect_the_pixel_and_byte_limits() { + let l = Limits { max_bytes: 1000, ..Limits::default() }; + assert_eq!(l.check(15, 16, Kind::Gray), Ok(240)); + assert_eq!(l.check(16, 16, Kind::Gray), Err(ImageError::TooLarge(16, 16))); + assert_eq!(Image::try_filled(8, 8, Kind::Color, [0.0; 4], &l), Err(ImageError::TooLarge(8, 8))); + let l = Limits { max_pixels: 100, ..Limits::default() }; + assert_eq!(l.check(10, 10, Kind::Color), Ok(400)); + assert_eq!(l.check(10, 11, Kind::Gray), Err(ImageError::TooLarge(10, 11))); + // The default limits accept a full 8192 × 8192 color plane and nothing longer. + assert_eq!(Limits::default().check(MAX_SIDE, MAX_SIDE, Kind::Color), Ok(1 << 28)); + } + + #[test] + fn checked_sizes_do_not_overflow() { + let open = Limits { max_side: u32::MAX, max_pixels: u64::MAX, max_bytes: u64::MAX }; + assert_eq!(open.check(u32::MAX, u32::MAX, Kind::Color), Err(ImageError::TooLarge(u32::MAX, u32::MAX))); + assert_eq!(open.check(u32::MAX, u32::MAX, Kind::Gray), Err(ImageError::TooLarge(u32::MAX, u32::MAX))); + } + + #[test] + fn from_data_checks_the_length() { + let l = Limits::default(); + assert_eq!(Image::from_data(2, 2, Kind::Color, vec![0.0], &l), Err(ImageError::BadDataLength { expected: 16, found: 1 })); + assert_eq!(Image::from_data(2, 2, Kind::Color, vec![0.0; 17], &l), Err(ImageError::BadDataLength { expected: 16, found: 17 })); + let img = Image::from_data(2, 1, Kind::Gray, vec![-2.0, 3.5], &l); + assert!(img.is_ok_and(|i| i.get(0, 0, false)[0] == -2.0 && i.get(1, 0, false)[0] == 3.5)); + } + + #[test] + fn non_finite_pixels_have_defined_results() { + let l = Limits::default(); + let img = Image::from_data(1, 1, Kind::Color, vec![f32::NAN, f32::INFINITY, -1.0, 2.0], &l); + let Ok(img) = img else { panic!("valid 1 x 1 image") }; + assert_eq!(img.to_rgba8_display(), vec![0, 255, 0, 255]); + let g = Image::from_data(3, 1, Kind::Gray, vec![f32::NAN, -4.0, 8.0], &l); + let Ok(g) = g else { panic!("valid 3 x 1 image") }; + assert_eq!(g.range(), (-4.0, 8.0)); + assert!(g.mean()[0].is_nan()); + } + + #[test] + fn srgb_encoding_keeps_nan() { + assert!(linear_to_srgb(f32::NAN).is_nan()); + assert!(srgb_to_linear(f32::NAN).is_nan()); + assert_eq!(linear_to_srgb(0.0), 0.0); + assert!((linear_to_srgb(1.0) - 1.0).abs() < 1e-6); + assert!((srgb_to_linear(linear_to_srgb(0.5)) - 0.5).abs() < 1e-6); + } + + #[test] + fn whole_factor_shrink_stays_exact_with_custom_limits() { + let l = Limits { max_side: 16, ..Limits::default() }; + let img = Image::try_generate(4, 2, Kind::Color, &l, |x, y| [x as f32, y as f32, 0.0, 1.0]); + let Ok(img) = img else { panic!("valid 4 x 2 image") }; + let half = img.resize(2, 1, false); + assert_eq!(half.data(), &[0.5, 0.5, 0.0, 1.0, 2.5, 0.5, 0.0, 1.0]); + assert_eq!(img.to_gray().width(), 4); + } +} From 261e7a4c5c37e833fcd62aa611196a999be36393 Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Fri, 13 Nov 2026 13:28:35 -0800 Subject: [PATCH 11/51] craft-texture: keep image planes within isize::MAX bytes when limits are raised With raised Limits, a gray image over 512 MiB could be converted to color on wasm32, where the color plane needs more than isize::MAX bytes and vec! panics with capacity overflow. - Limits::check returns TooLarge when the byte count is over isize::MAX, so the try_ forms report the size instead of OutOfMemory. - map, to_color and to_kind clamp each side to 1..=MAX_SIDE when the result would be over isize::MAX bytes, and map the top-left part. - The size checks are pure functions that take the bound as a value, and three tests check them against the 32-bit bound without allocating. --- crates/texture/README.md | 3 ++ crates/texture/src/lib.rs | 105 ++++++++++++++++++++++++++++++++------ 2 files changed, 93 insertions(+), 15 deletions(-) diff --git a/crates/texture/README.md b/crates/texture/README.md index 877732671..19e58de22 100644 --- a/crates/texture/README.md +++ b/crates/texture/README.md @@ -9,6 +9,9 @@ network I/O and has no `unsafe` code. against `Limits` (longest side, pixel count, bytes) before allocating and return an `ImageError`. `from_data` also checks that the buffer holds width × height × channels floats. `filled`, `generate`, `generate_uv` and `gray` clamp each side to `1..=MAX_SIDE` (8192). + A plane is never larger than `isize::MAX` bytes (2 GiB minus one byte on `wasm32`), even with + raised limits: the `try_` forms return `ImageError::TooLarge` for a larger one, and `map`, + `to_color` and `to_kind` clamp each side to `1..=MAX_SIDE` and map the top-left part instead. `try_map`, `try_to_kind`, `try_resize` and `try_to_rgba8_display` reserve their memory first and return `ImageError::OutOfMemory` when that fails. The forms without `try_` allocate like `Vec`, which ends the process when memory runs out. diff --git a/crates/texture/src/lib.rs b/crates/texture/src/lib.rs index 272ce1c22..02ad65ae8 100644 --- a/crates/texture/src/lib.rs +++ b/crates/texture/src/lib.rs @@ -14,11 +14,15 @@ //! (). //! //! Sizes are bounded. [`Limits`] caps the side, the pixel count and the bytes, and the `try_` -//! constructors return an [`ImageError`] before allocating anything over them. The constructors -//! without `try_` clamp each side to `1..=MAX_SIDE`. Every operation that allocates has a `try_` -//! form that reserves its memory first and returns [`ImageError::OutOfMemory`] when that fails; the -//! forms without `try_` allocate like `Vec`, which ends the process when memory runs out. Rows are -//! generated on several threads only with the `parallel` feature. +//! constructors return an [`ImageError`] before allocating anything over them. A plane is also +//! never larger than `isize::MAX` bytes, the most a `Vec` can hold on the target: `isize::MAX` is +//! 2 GiB minus one byte on 32-bit targets such as `wasm32`. The `try_` forms return +//! [`ImageError::TooLarge`] for a plane over that bound, also when the caller raised the limits +//! past it. The constructors without `try_` clamp each side to `1..=MAX_SIDE`, and [`Image::map`] +//! clamps the same way when its result would be over the bound. Every operation that allocates has +//! a `try_` form that reserves its memory first and returns [`ImageError::OutOfMemory`] when that +//! fails; the forms without `try_` allocate like `Vec`, which ends the process when memory runs +//! out. Rows are generated on several threads only with the `parallel` feature. #![forbid(unsafe_code)] #![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] @@ -53,8 +57,9 @@ pub enum ImageError { /// A side is zero or longer than [`Limits::max_side`]. #[error("image size {0}x{1} has a zero side or a side over the limit")] BadSize(u32, u32), - /// The pixel count or the byte count is over [`Limits`]. - #[error("image size {0}x{1} needs more pixels or bytes than the limits allow")] + /// The pixel count or the byte count is over [`Limits`], or the byte count is over + /// `isize::MAX`, the largest allocation the target allows. + #[error("image size {0}x{1} needs more pixels or bytes than the limits or the target allow")] TooLarge(u32, u32), /// The float buffer does not hold width × height × channels values. #[error("image data holds {found} floats where {expected} are needed")] @@ -83,10 +88,24 @@ impl Default for Limits { } } +/// The largest allocation in bytes that a `Vec` can make on the target. +const MAX_ALLOC_BYTES: u64 = isize::MAX as u64; + +/// Bytes of float data in a `w × h` image of `kind`, or `None` when the count overflows `u64`. +fn checked_byte_len(w: u32, h: u32, kind: Kind) -> Option { + u64::from(w).checked_mul(u64::from(h))?.checked_mul(kind.channels() as u64)?.checked_mul(size_of::() as u64) +} + impl Limits { /// The number of floats a `w × h` image of `kind` holds, or the error the limits give for that - /// size. Nothing is allocated. + /// size. A size whose bytes are over `isize::MAX` is [`ImageError::TooLarge`] whatever the + /// limits are. Nothing is allocated. pub fn check(&self, w: u32, h: u32, kind: Kind) -> Result { + self.check_within(w, h, kind, MAX_ALLOC_BYTES) + } + + /// [`Limits::check`] with `max_alloc_bytes` as the largest allocation the target allows. + fn check_within(&self, w: u32, h: u32, kind: Kind, max_alloc_bytes: u64) -> Result { if w == 0 || h == 0 || w > self.max_side || h > self.max_side { return Err(ImageError::BadSize(w, h)); } @@ -94,7 +113,7 @@ impl Limits { let pixels = u64::from(w).checked_mul(u64::from(h)).ok_or_else(|| too_large.clone())?; let floats = pixels.checked_mul(kind.channels() as u64).ok_or_else(|| too_large.clone())?; let bytes = floats.checked_mul(size_of::() as u64).ok_or_else(|| too_large.clone())?; - if pixels > self.max_pixels || bytes > self.max_bytes { + if pixels > self.max_pixels || bytes > self.max_bytes || bytes > max_alloc_bytes { return Err(too_large); } usize::try_from(floats).map_err(|_| too_large) @@ -123,6 +142,24 @@ pub fn clamp_size(w: u32, h: u32) -> (u32, u32) { (w.clamp(1, MAX_SIDE), h.clamp(1, MAX_SIDE)) } +/// The size and float count of an image of `kind` requested at `w × h` without a limit check: +/// `w × h` when its bytes fit in `max_alloc_bytes`, otherwise each side clamped to +/// `1..=MAX_SIDE`, and 1 × 1 when even the clamped size does not fit. Nothing is allocated. +fn bounded_size(w: u32, h: u32, kind: Kind, max_alloc_bytes: u64) -> (u32, u32, usize) { + let floats = |w: u32, h: u32| { + let bytes = checked_byte_len(w, h, kind).filter(|&bytes| bytes <= max_alloc_bytes)?; + usize::try_from(bytes / size_of::() as u64).ok() + }; + if let Some(len) = floats(w, h) { + return (w, h, len); + } + let (w, h) = clamp_size(w, h); + match floats(w, h) { + Some(len) => (w, h, len), + None => (1, 1, kind.channels()), + } +} + /// Integer texel index `i` on an axis of `n >= 1` texels: `i mod n` when repeating, otherwise /// clamped to `0..=n - 1`. #[inline] @@ -161,9 +198,10 @@ fn fill [f32; 4] + Sync>(data: &mut [f32], w: u32, c: usize, } impl Image { - /// An image of a size already inside `1..=MAX_SIDE` or taken from an existing image. + /// An image of `w × h`, or of the clamped size [`bounded_size`] gives when its bytes would be + /// over `isize::MAX`. `f` is called only for pixels inside the size that was made. fn build [f32; 4] + Sync>(w: u32, h: u32, kind: Kind, f: F) -> Image { - let len = (w as usize).saturating_mul(h as usize).saturating_mul(kind.channels()); + let (w, h, len) = bounded_size(w, h, kind, MAX_ALLOC_BYTES); let mut data = vec![0.0f32; len]; fill(&mut data, w, kind.channels(), &f); Image { w, h, kind, data: Arc::new(data) } @@ -216,6 +254,7 @@ impl Image { Image::try_build(w, h, kind, limits, |x, y| f((x as f32 + 0.5) * iw, (y as f32 + 0.5) * ih)) } + /// A gray image generated with `f(x, y)`, each side clamped to `1..=MAX_SIDE`. pub fn gray(w: u32, h: u32, f: impl Fn(u32, u32) -> f32 + Sync) -> Image { Image::generate(w, h, Kind::Gray, |x, y| [f(x, y), 0.0, 0.0, 0.0]) } @@ -340,7 +379,10 @@ impl Image { self.get(x, y, tile) } - /// Map every pixel (as RGBA) to a new image of `kind`, same size. + /// Map every pixel (as RGBA) to a new image of `kind`, same size. When a result of that size + /// would be over `isize::MAX` bytes, which only an image allowed by raised [`Limits`] can + /// reach, each side is clamped to `1..=MAX_SIDE` and the result maps the top-left part of this + /// image. [`Image::try_map`] returns [`ImageError::TooLarge`] instead. pub fn map(&self, kind: Kind, f: impl Fn([f32; 4]) -> [f32; 4] + Sync) -> Image { Image::build(self.w, self.h, kind, |x, y| f(self.get(i64::from(x), i64::from(y), false))) } @@ -361,7 +403,7 @@ impl Image { } } - /// This image as grayscale (luminance of a color image). + /// This image as grayscale (luminance of a color image), same size. pub fn to_gray(&self) -> Image { match self.kind { Kind::Gray => self.clone(), @@ -369,7 +411,8 @@ impl Image { } } - /// This image as RGBA (gray copied to RGB, alpha 1). + /// This image as RGBA (gray copied to RGB, alpha 1). A gray image goes through + /// [`Image::map`], so a result over `isize::MAX` bytes is clamped as `map` describes. pub fn to_color(&self) -> Image { match self.kind { Kind::Color => self.clone(), @@ -377,6 +420,7 @@ impl Image { } } + /// [`Image::to_gray`] or [`Image::to_color`]. pub fn to_kind(&self, kind: Kind) -> Image { match kind { Kind::Gray => self.to_gray(), @@ -434,7 +478,8 @@ impl Image { } /// 8-bit sRGB-encoded RGBA for display (gray shown as is; color through the sRGB curve). - /// Values are clamped to `0..=1` first; NaN becomes 0. + /// Values are clamped to `0..=1` first; NaN becomes 0. The result has 4 bytes per pixel, never + /// more than the float data's own bytes. pub fn to_rgba8_display(&self) -> Vec { let mut out = vec![0u8; self.display_len()]; self.fill_display(&mut out); @@ -751,6 +796,36 @@ mod tests { assert_eq!(open.check(u32::MAX, u32::MAX, Kind::Gray), Err(ImageError::TooLarge(u32::MAX, u32::MAX))); } + /// `isize::MAX` on a 32-bit target such as `wasm32`. + const BOUND_32: u64 = i32::MAX as u64; + + #[test] + fn checked_sizes_respect_target_isize_bound() { + let open = Limits { max_side: u32::MAX, max_pixels: u64::MAX, max_bytes: u64::MAX }; + // 16,385 × 8,192 gray is 512 MiB and 16 KiB; its color form is over 2 GiB. + assert_eq!(open.check_within(16_385, 8_192, Kind::Gray, BOUND_32), Ok(16_385 * 8_192)); + assert_eq!(open.check_within(16_385, 8_192, Kind::Color, BOUND_32), Err(ImageError::TooLarge(16_385, 8_192))); + assert_eq!(open.check_within(MAX_SIDE, MAX_SIDE, Kind::Color, BOUND_32), Ok(1 << 28)); + } + + #[test] + fn infallible_expansion_clamps_at_target_bound() { + assert_eq!(bounded_size(16_385, 8_192, Kind::Gray, BOUND_32), (16_385, 8_192, 16_385 * 8_192)); + assert_eq!(bounded_size(16_385, 8_192, Kind::Color, BOUND_32), (MAX_SIDE, MAX_SIDE, 1 << 28)); + assert_eq!(bounded_size(MAX_SIDE, MAX_SIDE, Kind::Color, BOUND_32), (MAX_SIDE, MAX_SIDE, 1 << 28)); + assert_eq!(bounded_size(3, 2, Kind::Color, BOUND_32), (3, 2, 24)); + // A bound below even the clamped size gives one pixel. + assert_eq!(bounded_size(16_385, 8_192, Kind::Color, 64), (1, 1, 4)); + assert_eq!(bounded_size(u32::MAX, u32::MAX, Kind::Gray, MAX_ALLOC_BYTES), (MAX_SIDE, MAX_SIDE, 1 << 26)); + } + + #[test] + fn checked_byte_len_rejects_arithmetic_overflow() { + assert_eq!(checked_byte_len(u32::MAX, u32::MAX, Kind::Color), None); + assert_eq!(checked_byte_len(u32::MAX, u32::MAX, Kind::Gray), None); + assert_eq!(checked_byte_len(MAX_SIDE, MAX_SIDE, Kind::Color), Some(1 << 30)); + } + #[test] fn from_data_checks_the_length() { let l = Limits::default(); From 8a2c27ee2dac8073a83d63f1c3f4ce798f287a3b Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Fri, 13 Nov 2026 13:43:35 -0800 Subject: [PATCH 12/51] craft-hdr: refuse buffers past isize::MAX bytes when limits are raised With a raised max_pixels on wasm32, a picture could pass every check and then ask vec! for more than isize::MAX bytes for its scan line or its float picture, which panics with a capacity overflow instead of returning an error. - decode checks the byte count of the scan line and of the float picture against isize::MAX before allocating either, and returns LimitExceeded("pixel count") when one is over. - Each header line is measured as text after invalid bytes become U+FFFD, and a line over isize::MAX bytes is LimitExceeded("header length"). - The resolution line reads its first four tokens without collecting the rest. - The size checks take the bound as a value, and tests check them against the 32-bit bound without allocating. --- crates/hdr/src/lib.rs | 49 ++++++++++++++++++++++++++++++++----- crates/hdr/src/tests.rs | 54 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 97 insertions(+), 6 deletions(-) diff --git a/crates/hdr/src/lib.rs b/crates/hdr/src/lib.rs index 9d7d3272c..d46232306 100644 --- a/crates/hdr/src/lib.rs +++ b/crates/hdr/src/lib.rs @@ -11,7 +11,9 @@ //! //! Input is treated as hostile: the header length and the picture size are capped by [`Limits`], //! and every scan line is validated before the float picture is allocated, so a short file cannot -//! ask for a large allocation. +//! ask for a large allocation. Whatever the limits, no buffer is requested past the target's +//! largest allocation (`isize::MAX` bytes), so raised limits on a 32-bit target such as `wasm32` +//! give [`Error::LimitExceeded`] instead of a panic. #[cfg(test)] mod tests; @@ -42,6 +44,7 @@ pub type Result = std::result::Result; #[non_exhaustive] pub struct Limits { /// Most pixels (width × height) a picture may have; each takes 12 bytes decoded. Default 2^26. + /// A picture over the target's largest allocation is refused at any setting. pub max_pixels: u64, /// Longest header read, in bytes (real ones are a few hundred). Default 64 KiB. pub max_header: usize, @@ -62,6 +65,27 @@ pub struct Picture { pub rgb: Vec, } +/// The largest allocation in bytes that a `Vec` or `String` can make on the target. +const MAX_ALLOC_BYTES: u64 = isize::MAX as u64; + +/// Bytes taken by `count` elements of `element_bytes` each, or `None` when the count overflows `u64`. +fn checked_byte_len(count: u64, element_bytes: usize) -> Option { + count.checked_mul(element_bytes as u64) +} + +/// `count` as a length when `count` elements of `element_bytes` each fit in `max_alloc_bytes`. +fn alloc_len(count: u64, element_bytes: usize, max_alloc_bytes: u64) -> Option { + checked_byte_len(count, element_bytes).filter(|&bytes| bytes <= max_alloc_bytes).and_then(|_| usize::try_from(count).ok()) +} + +/// Bytes of `String::from_utf8_lossy(bytes)`: each invalid sequence becomes one U+FFFD (3 bytes). +fn lossy_len(bytes: &[u8]) -> Option { + bytes.utf8_chunks().try_fold(0u64, |n, chunk| { + let invalid = if chunk.invalid().is_empty() { 0 } else { '\u{FFFD}'.len_utf8() }; + n.checked_add(chunk.valid().len() as u64)?.checked_add(invalid as u64) + }) +} + /// Whether `bytes` starts like a Radiance picture. pub fn sniff(bytes: &[u8]) -> bool { bytes.starts_with(b"#?RADIANCE") || bytes.starts_with(b"#?RGBE") @@ -158,6 +182,11 @@ fn scanline(b: &[u8], pos: &mut usize, line: &mut [[u8; 4]]) -> Result<()> { /// Decodes a Radiance picture to linear float RGB, top row first. pub fn decode(b: &[u8], limits: &Limits) -> Result { + decode_within(b, limits, MAX_ALLOC_BYTES) +} + +/// [`decode`] with `max_alloc_bytes` as the largest allocation the target allows. +fn decode_within(b: &[u8], limits: &Limits, max_alloc_bytes: u64) -> Result { if !sniff(b) { return Err(Error::NotHdr); } @@ -166,7 +195,11 @@ pub fn decode(b: &[u8], limits: &Limits) -> Result { let line = |pos: &mut usize| -> Result { let rest = b.get(*pos..).ok_or(Error::Malformed("truncated header"))?; let end = rest.iter().take(limits.max_header).position(|&c| c == b'\n').ok_or(Error::Malformed("truncated header"))?; - let s = String::from_utf8_lossy(rest.get(..end).unwrap_or_default()).trim_end_matches('\r').to_string(); + let raw = rest.get(..end).unwrap_or_default(); + if lossy_len(raw).is_none_or(|n| n > max_alloc_bytes) { + return Err(Error::LimitExceeded("header length")); + } + let s = String::from_utf8_lossy(raw).trim_end_matches('\r').to_string(); *pos += end + 1; Ok(s) }; @@ -188,8 +221,9 @@ pub fn decode(b: &[u8], limits: &Limits) -> Result { } let res = line(&mut pos)?; let bad = Error::Malformed("bad resolution line"); - let t: Vec<&str> = res.split_whitespace().collect(); - let &[a1, n1, a2, n2] = t.as_slice().first_chunk::<4>().ok_or(bad.clone())?; + // Tokens after the fourth are ignored, so they are not collected. + let mut t = res.split_whitespace(); + let (Some(a1), Some(n1), Some(a2), Some(n2)) = (t.next(), t.next(), t.next(), t.next()) else { return Err(bad) }; let ((x1, p1), (x2, p2)) = (axis(a1).ok_or(bad.clone())?, axis(a2).ok_or(bad.clone())?); if x1 == x2 { return Err(Error::Malformed("resolution line names one axis twice")); @@ -205,6 +239,10 @@ pub fn decode(b: &[u8], limits: &Limits) -> Result { if pixels > limits.max_pixels { return Err(Error::LimitExceeded("pixel count")); } + // One scan line of RGBE pixels and the float picture, each within the target's largest allocation. + let scan_len = alloc_len(u64::from(if x1 { height } else { width }), size_of::<[u8; 4]>(), max_alloc_bytes); + let rgb_len = pixels.checked_mul(3).and_then(|floats| alloc_len(floats, size_of::(), max_alloc_bytes)); + let (Some(scan_len), Some(total)) = (scan_len, rgb_len) else { return Err(Error::LimitExceeded("pixel count")) }; // A scan line takes at least a few bits of file, so a header cannot ask for more than the data has. if (b.len().saturating_sub(pos) as u64).saturating_mul(4096) < pixels { return Err(Error::Malformed("truncated pixel data")); @@ -212,12 +250,11 @@ pub fn decode(b: &[u8], limits: &Limits) -> Result { // Validate every encoded scan line before allocating the float picture: a short file could // otherwise ask for the whole limit of zeroed pixels and only then fail on its first line. let pixel_data = pos; - let mut scan = vec![[0u8; 4]; n2]; + let mut scan = vec![[0u8; 4]; scan_len]; for _ in 0..n1 { scanline(b, &mut pos, &mut scan)?; } - let total = w.checked_mul(h).and_then(|n| n.checked_mul(3)).ok_or(Error::LimitExceeded("pixel count"))?; let mut rgb = vec![0f32; total]; pos = pixel_data; for i in 0..n1 { diff --git a/crates/hdr/src/tests.rs b/crates/hdr/src/tests.rs index 7e40454b1..576a8db3f 100644 --- a/crates/hdr/src/tests.rs +++ b/crates/hdr/src/tests.rs @@ -142,3 +142,57 @@ fn limits_are_checked_before_allocating() { assert_eq!(decode(&long, &Limits { max_header: 8, ..Limits::default() }), Err(Error::Malformed("truncated header"))); assert_eq!((Limits::default().max_pixels, Limits::default().max_header), (1 << 26, 64 << 10)); } + +/// `isize::MAX` on a 32-bit target such as `wasm32`. +const BOUND_32: u64 = i32::MAX as u64; + +#[test] +fn buffer_lengths_respect_target_isize_bound() { + // A scan line of RGBE pixels, 4 bytes each. + assert_eq!(alloc_len(536_870_911, 4, BOUND_32), Some(536_870_911)); + assert_eq!(alloc_len(536_870_912, 4, BOUND_32), None); + assert_eq!(alloc_len(u64::from(u32::MAX), 4, BOUND_32), None); + // The float picture: 3 floats of 4 bytes a pixel. + assert_eq!(alloc_len(178_956_970 * 3, 4, BOUND_32), Some(178_956_970 * 3)); + assert_eq!(alloc_len(178_956_971 * 3, 4, BOUND_32), None); + // The default pixel limit fits a 32-bit target. + assert_eq!(alloc_len(Limits::default().max_pixels * 3, 4, BOUND_32), Some(3 << 26)); + assert_eq!(checked_byte_len(u64::MAX, 4), None); + assert_eq!(alloc_len(u64::MAX, 1, MAX_ALLOC_BYTES), None); +} + +#[test] +fn raised_pixel_limit_stops_at_the_target_bound() { + let open = Limits { max_pixels: u64::MAX, ..Limits::default() }; + // 2 × 2 needs an 8-byte scan line and a 48-byte float picture. + let ok = file("-Y 2 +X 2", &[0; 16]); + assert!(decode_within(&ok, &open, 48).is_ok()); + assert_eq!(decode_within(&ok, &open, 47), Err(Error::LimitExceeded("pixel count"))); + // A 1 × 536,870,912 picture is past the 32-bit bound in both buffers; refused before + // anything is allocated, ahead of the scan-line validation. + let wide = file("-Y 1 +X 536870912", &[0; 131_072]); + assert_eq!(decode_within(&wide, &open, BOUND_32), Err(Error::LimitExceeded("pixel count"))); + // 178,956,971 one-pixel scan lines fit the scan buffer but not the float picture. + let tall = file("-Y 178956971 +X 1", &[0; 43_692]); + assert_eq!(decode_within(&tall, &open, BOUND_32), Err(Error::LimitExceeded("pixel count"))); +} + +#[test] +fn header_lines_are_measured_after_lossy_conversion() { + // `#` and ten bytes that are not UTF-8: 11 bytes in the file, 31 as text. + let mut f = b"#?RADIANCE\n#".to_vec(); + f.extend_from_slice(&[0xff; 10]); + f.extend_from_slice(b"\n\n-Y 1 +X 1\n\0\0\0\0"); + assert_eq!(lossy_len(&f[11..22]), Some(31)); + assert!(decode_within(&f, &Limits::default(), 31).is_ok()); + assert_eq!(decode_within(&f, &Limits::default(), 30), Err(Error::LimitExceeded("header length"))); + assert_eq!(lossy_len(b"ok \xe2\x82"), Some(6)); + assert_eq!(lossy_len(b""), Some(0)); +} + +#[test] +fn resolution_tokens_after_the_fourth_are_ignored() { + let f = dec(&file("-Y 1 +X 1 a b c d e f", &[0; 4])).unwrap(); + assert_eq!((f.width, f.height), (1, 1)); + assert_eq!(dec(&file("-Y 1 +X", &[0; 4])), Err(Error::Malformed("bad resolution line"))); +} From ef03e1b1dfd30d299e52d3079c49cae534d5799f Mon Sep 17 00:00:00 2001 From: Bra1nZ <95569966+Bra1nZ@users.noreply.github.com> Date: Sat, 14 Nov 2026 01:19:29 +0300 Subject: [PATCH 13/51] fix(print): trust one side of a legacy V3 driver's paper metric Legacy V3 GDI drivers (HP LaserJet P1102) keep the paper metric in their DEVMODE extension and report MediaSizeWidth = 0 while the height is right, so verify_ticket refused with "a paper without a size (a roll?)" and nothing was sent (storytold/craft-libs#7230). verify_ticket now fails closed only when neither side is known or the request itself names no sheet; otherwise it goes on with the requested size, but only while the side the driver did report agrees with the request to a quarter of a millimetre. matching_paper gains a partial record as a candidate of last resort, and driver_ticket takes the wanted size from the sheet the job asked for, not from the zero record. The fallback is logged; log moves to the common dependencies so the warning compiles on Windows too (caught by the windows-gnu check). --- crates/print/Cargo.toml | 8 +-- crates/print/src/ticket.rs | 111 ++++++++++++++++++++++++++++++++++-- crates/print/src/windows.rs | 23 +++++++- 3 files changed, 132 insertions(+), 10 deletions(-) diff --git a/crates/print/Cargo.toml b/crates/print/Cargo.toml index 50fbb43d6..485fc8a93 100644 --- a/crates/print/Cargo.toml +++ b/crates/print/Cargo.toml @@ -13,14 +13,14 @@ description = "System PDF print spooler for the Craft apps: CUPS and Windows" # downstream GDI values a different Rust type identity even when the code is unchanged. # PDF loader updates below are independent of this public transport API. craft-winprint-gdi = { git = "https://github.com/storytold/winprint.rs", rev = "64e7afd4d1483512385012c340ecaaaf0f3beb7f" } +# Says why the printer list is empty when lpstat can't run (e.g. a Flatpak without CUPS tools), +# and why a job went on with the paper the request names while the driver reported only one side +# of it (storytold/craft-libs#7230). +log = "0.4" [lints] workspace = true -[target.'cfg(unix)'.dependencies] -# Says why the printer list is empty when lpstat can't run (e.g. a Flatpak without CUPS tools). -log = "0.4" - [target.'cfg(windows)'.dependencies] # Printing without starting anything (storytold/pdfcraft#1107): the printer list (EnumPrinters) # and the job (Windows.Data.Pdf drawn with Direct2D into the XPS print API, options as a diff --git a/crates/print/src/ticket.rs b/crates/print/src/ticket.rs index ddf2c3955..55a9c50ae 100644 --- a/crates/print/src/ticket.rs +++ b/crates/print/src/ticket.rs @@ -218,6 +218,11 @@ pub(crate) struct Paper<'a> { /// The driver paper for a sheet of `width` × `height` points (either way round): within a /// quarter of a millimetre, preferring the one named like the standard size, then a Print Schema /// keyword, then the closest; on a tie the driver's own order. Its index in `papers`. +/// +/// An entry the driver keeps only one side of (the other reads zero, a legacy host-based driver's +/// DEVMODE metric, storytold/craft-libs#7230) is a candidate of last resort (INV-4): only when no +/// full entry matched, only a Print Schema keyword entry, and only while its known side agrees +/// with the sheet, either way round. pub(crate) fn matching_paper(papers: &[Paper<'_>], width: f64, height: f64) -> Option { let (w, h) = (micrometres(width.min(height))?, micrometres(width.max(height))?); let names = paper_names(width, height); @@ -231,7 +236,13 @@ pub(crate) fn matching_paper(papers: &[Paper<'_>], width: f64, height: f64) -> O }) .collect(); candidates.sort_by_key(|(_, p, off)| (!names.iter().any(|n| names_paper(p.name, n)), !p.keyword, *off)); - candidates.first().map(|(i, _, _)| *i) + if let Some(index) = candidates.first().map(|(i, _, _)| *i) { + return Some(index); + } + let agrees = |side: u32| side.abs_diff(w) <= PAPER_TOLERANCE || side.abs_diff(h) <= PAPER_TOLERANCE; + papers + .iter() + .position(|p| p.keyword && (p.width == 0) != (p.height == 0) && (p.width == 0 || agrees(p.width)) && (p.height == 0 || agrees(p.height))) } fn named(node: roxmltree::Node<'_, '_>, local: &str) -> bool { @@ -287,14 +298,35 @@ fn integer(node: roxmltree::Node<'_, '_>, tag: &str, name: &str) -> Option /// paper (when `paper` is given, that one, to a quarter of a millimetre). Returns the paper's /// width and height in micrometres as the driver lists it. Only those schema fields are read: /// some drivers return empty vendor parameters that a stricter parser would refuse. +/// +/// A zero or unreadable side (`MediaSizeWidth` gone) is roll-like only while the request itself +/// names no sheet (INV-2): a legacy host-based driver keeps the paper metric in its DEVMODE +/// extension and reads back a zero side for a real sheet (HP LaserJet P1102, storytold/craft-libs#7230), so +/// with a sheet named the job falls back to the size the request asked for (INV-1, +/// fail-closed: every refusal here is before anything reaches the spooler). A side the driver +/// did report must agree with the sheet asked for, either way round (INV-3); both sides gone is +/// refused whatever the request names (INV-5). The fallback is logged (INV-7). pub(crate) fn verify_ticket(xml: &str, paper: Option<(u32, u32)>, landscape: bool) -> Result<(u32, u32), Error> { let document = crate::xml::parse(xml).map_err(spool_error)?; let feature = |name: &str| document.root_element().children().find(|n| n.has_tag_name((NS_PSF, "Feature")) && named(*n, name)); let media = feature("PageMediaSize").ok_or_else(|| spool_error("the printer's driver did not confirm the paper size; nothing was sent"))?; - let size = integer(media, "ScoredProperty", "MediaSizeWidth") - .zip(integer(media, "ScoredProperty", "MediaSizeHeight")) - .filter(|(w, h)| *w > 0 && *h > 0) - .ok_or_else(|| spool_error("the printer's driver gave a paper without a size (a roll?); nothing was sent"))?; + let width = integer(media, "ScoredProperty", "MediaSizeWidth").filter(|w| *w > 0); + let height = integer(media, "ScoredProperty", "MediaSizeHeight").filter(|h| *h > 0); + let without_a_size = spool_error("the printer's driver gave a paper without a size (a roll?); nothing was sent"); + let size = match (width, height, paper) { + (Some(w), Some(h), _) => (w, h), + (None, None, _) | (_, _, None) => return Err(without_a_size), + (Some(reported), None, Some(wanted)) | (None, Some(reported), Some(wanted)) => { + let (w, h) = wanted; + // Either way round: the one side the driver did report against the sheet's width or height. + let agrees = |other: u32| reported.abs_diff(other) <= PAPER_TOLERANCE; + if !agrees(w) && !agrees(h) { + return Err(spool_error("the printer's driver changed the paper size; nothing was sent (choose a paper size it has)")); + } + log::warn!("the printer's driver reported only {reported} µm of the paper; going on with the requested {w} × {h} µm"); + (w, h) + } + }; if let Some((w, h)) = paper { let same = |a: (u32, u32), b: (u32, u32)| a.0.abs_diff(b.0) <= PAPER_TOLERANCE && a.1.abs_diff(b.1) <= PAPER_TOLERANCE; if !same(size, (w, h)) && !same(size, (h, w)) { @@ -1058,6 +1090,55 @@ mod tests { assert!(verify_ticket(", height: Option) -> String { + let side = |name: &str, value: Option| { + value.map_or(String::new(), |v| { + format!(r#"{v}"#) + }) + }; + format!( + r#" +{}{} + + +"#, + side("MediaSizeWidth", width), + side("MediaSizeHeight", height) + ) + } + + /// storytold/craft-libs#7230: the driver reports one side of the paper as zero for a real + /// sheet. With the sheet the request names, the job goes on with the size it asked for; a + /// side the driver did report must still agree with it, and a request that names no sheet is + /// refused as before. + #[test] + fn a_legacy_v3_drivers_zero_side_falls_back_to_the_requested_paper() { + let a4 = (210_000, 297_000); + assert_eq!(verify_ticket(&validated_partial(None, Some(297_000)), Some(a4), false), Ok(a4)); + assert_eq!(verify_ticket(&validated_partial(Some(0), Some(297_000)), Some(a4), false), Ok(a4), "a zero side is a missing one"); + assert_eq!(verify_ticket(&validated_partial(Some(297_000), None), Some(a4), false), Ok(a4), "either way round"); + // 0.5 pt (176 µm) inside the tolerance still agrees. + assert_eq!(verify_ticket(&validated_partial(Some(0), Some(297_176)), Some(a4), false), Ok(a4)); + assert_eq!(verify_ticket(&validated_partial(Some(0), Some(297_250)), Some(a4), false), Ok(a4), "exactly the tolerance"); + // A side that disagrees means the driver changed the paper, not that it has a roll. + let changed = verify_ticket(&validated_partial(Some(0), Some(279_400)), Some(a4), false).unwrap_err(); + assert!(changed.to_string().contains("changed the paper size"), "{changed}"); + assert!(!changed.to_string().contains("roll"), "{changed}"); + assert!(verify_ticket(&validated_partial(Some(0), Some(297_251)), Some(a4), false).is_err(), "one µm past the tolerance"); + // Without a sheet named the zero side stays roll-like. + assert!(verify_ticket(&validated_partial(Some(0), Some(297_000)), None, false).is_err()); + assert!(verify_ticket(&validated_partial(None, Some(297_000)), None, false).is_err()); + // Both sides gone is refused whatever the request names. + for wanted in [Some(a4), None] { + for (width, height) in [(None, None), (Some(0), Some(0))] { + let refused = verify_ticket(&validated_partial(width, height), wanted, false).unwrap_err(); + assert!(refused.to_string().contains("roll"), "{refused}"); + } + } + } + /// The namespace of the Brother driver's own keywords. const BROTHER: &str = "http://schemas.brother.info/mfc/printing/2006/11/printschemakeywords"; @@ -1548,6 +1629,26 @@ mod tests { assert!(!names_paper(None, "A4")); } + /// A paper the driver keeps one side of (storytold/craft-libs#7230) is a candidate of last + /// resort only: no full entry matched, a Print Schema keyword entry, and its known side + /// agrees with the sheet. + #[test] + fn a_partially_known_paper_is_a_candidate_of_last_resort_only() { + let paper = |width, height, name, keyword| Paper { width, height, name, keyword }; + let partial = paper(0, 297_000, Some("A4"), true); + let alone = [partial.clone()]; + assert_eq!(matching_paper(&alone, 595.28, 841.89), Some(0), "no full entry: the partial one is taken"); + // A full candidate, however it spells its option, wins over the partial one. + let with_full = [partial, paper(210_100, 297_000, Some("A4"), false)]; + assert_eq!(matching_paper(&with_full, 595.28, 841.89), Some(1), "the full entry wins"); + // A vendor's own entry is no partial candidate. + assert_eq!(matching_paper(&[paper(0, 297_000, Some("A4"), false)], 595.28, 841.89), None); + // A partial entry whose known side disagrees is no candidate. + assert_eq!(matching_paper(&[paper(0, 279_400, Some("Letter"), true)], 595.28, 841.89), None); + // Both sides gone: nothing known to agree with. + assert_eq!(matching_paper(&[paper(0, 0, Some("A4"), true)], 595.28, 841.89), None); + } + #[test] fn the_unprintable_margin_comes_from_the_capabilities() { let caps = |x: u32, y: u32, w: u32, h: u32| { diff --git a/crates/print/src/windows.rs b/crates/print/src/windows.rs index d43e3981a..7ba238808 100644 --- a/crates/print/src/windows.rs +++ b/crates/print/src/windows.rs @@ -224,7 +224,28 @@ fn driver_ticket(device: &PrinterDevice, job: &Job, sheet: (f64, f64), landscape .collect(); let media = ticket::matching_paper(&papers, sheet.0, sheet.1).and_then(|i| medias.get(i)); let wanted = match (media, job.scaling) { - (Some(m), _) => Some((m.size().width_in_micron(), m.size().height_in_micron())), + (Some(m), _) => { + let size = (m.size().width_in_micron(), m.size().height_in_micron()); + // INV-6: a driver that keeps one side of the paper metric in its DEVMODE extension + // (storytold/craft-libs#7230) reports a zero side; the wanted size then is the sheet + // the job asked for, not the zero record, which would poison the cross-check and hand + // `sheets::plan` a width of zero. + if size.0 == 0 || size.1 == 0 { + match (ticket::micrometres(sheet.0), ticket::micrometres(sheet.1)) { + (Some(w), Some(h)) => Some((w, h)), + _ => { + return Err(spool_error(format!( + "{} has no {:.2} × {:.2} inch paper; choose a paper size it has, or add this one in its driver", + device.name(), + sheet.0 / 72.0, + sheet.1 / 72.0 + ))); + } + } + } else { + Some(size) + } + } (None, Scaling::ShrinkToFit) => None, (None, Scaling::Exact) => { return Err(spool_error(format!( From eee76c3fc2034e91372407ca3858f32a660338ef Mon Sep 17 00:00:00 2001 From: alehel Date: Sat, 14 Nov 2026 01:28:23 +0100 Subject: [PATCH 14/51] craft-audio: AAC, ALAC, MP3, AC-3 and E-AC-3 as formats of encode and FileEncoder EncodeFormat gains Aac and Alac (M4A through craft-media's MP4 muxer) and Mp3, Ac3 and Eac3 (raw streams), so one call writes any of them from WAV-order f32 audio and EncodeOptions. - EncodeOptions::rate_control (with_bitrate, with_quality): a bit rate is moved to the nearest one the stream can carry; quality is AAC's VBR. - Channels are mapped onto the codec's order by speaker, from EncodeOptions::layout. A layout the format has not is Unsupported instead of reaching the wrong speakers. - M4A: the edit list skips the AAC priming, and the last sample's duration is cut so the track ends at the last frame written. - encode_format_for, ENCODE_EXTENSIONS and EncodeFormat::ALL list the new formats; aac-encode and alac-encode now turn on craft-media's isobmff. Refs #1230 --- Cargo.toml | 2 +- crates/audio/Cargo.toml | 9 +- crates/audio/README.md | 80 ++- crates/audio/examples/encode.rs | 8 +- crates/audio/src/aac/encoder/mod.rs | 10 + crates/audio/src/aac/mod.rs | 2 + crates/audio/src/ac3/mod.rs | 2 +- crates/audio/src/lib.rs | 132 +++- crates/audio/src/write/coded.rs | 581 ++++++++++++++++++ crates/audio/src/write/coded/tests.rs | 115 ++++ crates/audio/src/write/mod.rs | 138 +++-- crates/audio/src/write/pcm.rs | 3 + crates/audio/tests/audio/decode_extensions.rs | 14 +- crates/audio/tests/audio/encode_format.rs | 2 +- crates/audio/tests/codecs/file_formats.rs | 420 +++++++++++++ crates/audio/tests/codecs/main.rs | 1 + 16 files changed, 1440 insertions(+), 79 deletions(-) create mode 100644 crates/audio/src/write/coded.rs create mode 100644 crates/audio/src/write/coded/tests.rs create mode 100644 crates/audio/tests/codecs/file_formats.rs diff --git a/Cargo.toml b/Cargo.toml index 033e961b3..fc251abe0 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -85,7 +85,7 @@ craft-keymap = { path = "crates/keymap" } craft-assuan = { path = "crates/assuan" } craft-kra = { path = "crates/kra" } craft-audio = { path = "crates/audio" } -# No default features, so craft-audio's `encode` builds craft-media without `isobmff`. +# No default features: craft-audio turns on the craft-media modules each of its features needs. craft-latex = { path = "crates/latex" } craft-markdown = { path = "crates/markdown" } craft-math = { path = "crates/math" } diff --git a/crates/audio/Cargo.toml b/crates/audio/Cargo.toml index 9b6200198..d132f23da 100644 --- a/crates/audio/Cargo.toml +++ b/crates/audio/Cargo.toml @@ -23,6 +23,7 @@ decode-native = ["aac-decode", "alac-decode", "opus-decode", "ac3-decode", "mpa- # The symphonia fallback for the formats with no native decoder yet. symphonia = ["decode-native", "dep:symphonia"] # Every encoder: the lossless file writers and the AAC, ALAC, AC-3/E-AC-3, MP3 and Opus encoders. +# All but Opus are also file formats of `encode` and `FileEncoder`. encode = ["lossless-encode", "aac-encode", "alac-encode", "ac3-encode", "eac3-encode", "mp3-encode", "opus-encode"] # Encode WAV/BWF/RF64, AIFF/AIFF-C and FLAC files. lossless-encode = ["pcm-encode", "flac-encode"] @@ -32,16 +33,18 @@ pcm-encode = [] flac-encode = ["craft-media/bitstream"] # Codec modules on their own, for packet-level use. aac-decode = ["craft-media/bitstream"] -aac-encode = ["craft-media/bitstream"] +# The AAC encoder (`aac::Encoder`), and AAC in M4A through `encode` and `FileEncoder`. +aac-encode = ["craft-media/bitstream", "craft-media/isobmff"] opus-decode = [] opus-encode = [] ac3-decode = ["craft-media/bitstream"] mpa-decode = ["craft-media/bitstream"] # MPEG-1/2 Layer III (MP3) decoder (`mp3::Decoder`). mp3-decode = ["mpa-decode"] -# ALAC packet decoder and encoder (`alac`), ported from Apple's reference implementation. +# ALAC packet decoder and encoder (`alac`), ported from Apple's reference implementation. The +# encoder also writes ALAC in M4A through `encode` and `FileEncoder`. alac-decode = [] -alac-encode = [] +alac-encode = ["craft-media/isobmff"] ac3-encode = ["craft-media/bitstream"] eac3-encode = ["craft-media/bitstream"] # MPEG-1/2 Layer III (MP3) encoder (`mp3`). diff --git a/crates/audio/README.md b/crates/audio/README.md index 518dbeb4c..79f0efd46 100644 --- a/crates/audio/README.md +++ b/crates/audio/README.md @@ -29,19 +29,19 @@ No default features. The shared types (`AudioBuffer`, `AudioInfo`, `ChannelLayou | `decode` | `decode`, `probe`, `Decoder`, `tracks`, `TrackDecoder`; every format in [Format support](#format-support) | `decode-native`, `symphonia` | | `decode-native` | the same, native formats only (others are `Unsupported`); `wav_pcm`, `aiff_pcm` (a file's integer PCM bit for bit, as `RawPcm`) | the six decoders below, craft-media `isobmff`/`matroska`/`ogg`, `log` | | `symphonia` | the fallback for formats with no native decoder; turning it on is the same as `decode` | `decode-native`, symphonia | -| `encode` | every encoder: the WAV, AIFF and FLAC file writers, and the AAC, ALAC, AC-3/E-AC-3, MP3 and Opus encoders | `lossless-encode`, `aac-encode`, `alac-encode`, `ac3-encode`, `eac3-encode`, `mp3-encode`, `opus-encode` | +| `encode` | every encoder, and every format of `encode` and `FileEncoder` | `lossless-encode`, `aac-encode`, `alac-encode`, `ac3-encode`, `eac3-encode`, `mp3-encode`, `opus-encode` | | `lossless-encode` | WAV, AIFF and FLAC writing | `pcm-encode`, `flac-encode` | | `pcm-encode` | `encode`, `FileEncoder` for WAV and AIFF; `wav_float_header`; `pcm_wav_file`, `pcm_wav_header`, `pcm_aiff_file`, `pcm_aiff_header` (minimal files around integer PCM bytes, for essence embedded in AAF / OMF) | none | | `flac-encode` | `encode`, `FileEncoder` for FLAC; `flac::Encoder`, the packet encoder for callers that mux FLAC themselves | craft-media `bitstream` | -| `aac-decode`, `aac-encode` | `aac::Decoder`, `aac::Encoder`; with `aac-decode`, `aac::latm_config` / `latm_split` for LOAS / LATM frames (AAC in MPEG transport streams) | craft-media `bitstream` | +| `aac-decode`, `aac-encode` | `aac::Decoder`, `aac::Encoder`; with `aac-decode`, `aac::latm_config` / `latm_split` for LOAS / LATM frames (AAC in MPEG transport streams); with `aac-encode`, `encode`, `FileEncoder` for AAC in M4A | craft-media `bitstream`; `aac-encode` also `isobmff` | | `alac-decode` | `alac::Decoder` | none | -| `alac-encode` | `alac::Encoder` | none | +| `alac-encode` | `alac::Encoder`; `encode`, `FileEncoder` for ALAC in M4A | craft-media `isobmff` | | `opus-decode`, `opus-encode` | `opus::Decoder`/`StreamDecoder`, `opus::Encoder` | none | | `ac3-decode` | `ac3::Decoder`, `ac3::ProgrammeDecoder` | craft-media `bitstream` | -| `ac3-encode`, `eac3-encode` | `ac3::encoder::Encoder` | craft-media `bitstream` | +| `ac3-encode`, `eac3-encode` | `ac3::encoder::Encoder`; `encode`, `FileEncoder` for AC-3 and E-AC-3 streams | craft-media `bitstream` | | `mpa-decode` | `mpa::Decoder` | craft-media `bitstream` | | `mp3-decode` | `mp3::Decoder`, `mp3::InfoTag` | `mpa-decode` | -| `mp3-encode` | `mp3::Encoder` | craft-media `bitstream` | +| `mp3-encode` | `mp3::Encoder`; `encode`, `FileEncoder` for MP3 | craft-media `bitstream` | | `peaks` | `peaks::Peaks` | none | | `rayon` | parallel AAC encoding (with `aac-encode`) | `rayon` | | `serde` | `Serialize`/`Deserialize` on the shared types | `serde` | @@ -230,6 +230,11 @@ let wav = encode(&surround, &EncodeOptions::default().with_layout(ChannelLayout: let mut enc = FileEncoder::new(std::fs::File::create("take.wav")?, &EncodeOptions::default(), 48_000, 2)?; enc.write(&buf.channels, buf.frames())?; // one slice (or Vec) per channel enc.finish()?; + +// The coded formats go the same way: AAC in M4A at 192 kbit/s, 5.1 as E-AC-3, 16-bit ALAC. +let m4a = encode(&buf, &EncodeOptions::new(EncodeFormat::Aac).with_bitrate(192_000))?; +let eac3 = encode(&surround, &EncodeOptions::new(EncodeFormat::Eac3).with_layout(ChannelLayout::SURROUND_5_1_SIDE))?; +let alac = encode(&buf, &EncodeOptions::new(EncodeFormat::Alac).with_bit_depth(BitDepth::Int16))?; ``` `EncodeOptions::default()` is 24-bit WAV. `with_bwf` adds a BWF `bext` chunk and @@ -240,7 +245,43 @@ file gets and `mime_type()` its media type. `write` refuses a block without one shorter than `frames`, and writes nothing. After a write fails for another reason, every later `write` and `finish` returns an error. -### Encode AAC +| `EncodeFormat` | File | Audio | Options used | +|---|---|---|---| +| `Wav`, `Aiff`, `Flac` | WAV / BWF / RF64, AIFF / AIFF-C, FLAC | any rate; FLAC up to 8 channels | `bit_depth`, `dither`, `layout` (WAV, FLAC), `bwf`, `force_rf64` (WAV) | +| `Alac` | M4A | 1–8 channels, any rate | `bit_depth` (16, 24, 32), `dither`, `layout` | +| `Aac` | M4A | AAC-LC, 1–8 channels, the 13 AAC rates (7350–96000 Hz) | `rate_control`, `layout` | +| `Mp3` | `.mp3` stream | mono or stereo; 32, 44.1, 48 kHz or 16, 22.05, 24 kHz | `rate_control` (bit rate), `layout` | +| `Ac3`, `Eac3` | `.ac3` / `.eac3` stream | up to 5.1 (E-AC-3: 7.1); 32, 44.1, 48 kHz | `rate_control` (bit rate), `layout` | + +`with_bitrate(bits_per_second)` sets a constant bit rate for all channels together. A rate the +stream cannot carry is moved to the nearest one it can: MP3 and AC-3 use the highest rate of their +tables not above it, AAC and E-AC-3 keep it inside their range. `with_quality(0.0..=1.0)` is AAC's +constant quality (VBR); the other lossy formats return `Unsupported` for it. Without either, AAC +is written at 64 kbit/s per channel, MP3 at 96 kbit/s per channel, and AC-3 and E-AC-3 at +96 kbit/s per full-bandwidth channel (the LFE not counted). + +The audio is in WAV channel order for every format; `layout` (the usual layout for the channel +count when unset) names the speakers, and the channels are reordered into the codec's own order. +Each coded format has a fixed set of layouts, and audio with other speakers is `Unsupported` +rather than written to the wrong ones: + +- AAC: C; L R; L R C; L R C Cs; L R C Ls Rs; 5.1; 6.1; and for 8 channels L R C LFE Ls Rs Lc Rc + (a front pair left and right of centre, mask `0xFF`). ALAC: the same, with 6.1's back centre last. + WAV 7.1 (backs and sides) is not that 7.1, and quad (the usual 4-channel layout) has no centre: + both need another format. +- AC-3 and E-AC-3: the layout picks the coding mode (1/0 to 3/2, with or without LFE; E-AC-3 also + 7.1 with backs and sides). +- A surround pair is a surround pair: side and back surrounds are interchangeable where the format + has one pair. + +An M4A's edit list skips the AAC encoder's priming (1024 frames) and ends at the last frame +written, so the file decodes to the length that went in. An MP3, AC-3 or E-AC-3 stream has no +place for that (see [Limits](#limits)). For a container of your own, use the codec modules below. + +### Encode AAC packets + +For an `.m4a` file, use `EncodeFormat::Aac` above. `aac::Encoder` is the packet encoder behind it, +for muxing into a container of your own: ```rust use craft_audio::AudioError; @@ -343,14 +384,14 @@ match craft_audio::decode(&bytes, None) { | WAV, BWF, RF64/BW64 | native | native | | AIFF, AIFF-C | native | native | | FLAC | symphonia | native | -| AAC-LC | native | native | +| AAC-LC | native | native; M4A through `encode` / `FileEncoder`, packets through `aac::Encoder` | | HE-AAC v1 | native (SBR) | — | | HE-AAC v2 | native, without parametric stereo (see [Limits](#limits)) | — | -| ALAC | native | native, packets (`alac::Encoder`; no file writer) | +| ALAC | native | native; M4A through `encode` / `FileEncoder`, packets through `alac::Encoder` | | MP1, MP2 (MPEG audio Layer I/II) | native | — | -| MP3 (Layer III) | native | native, frames (`mp3::Encoder`; the frames in a row are an `.mp3` file) | -| Opus | native | native | -| AC-3, E-AC-3 | native | native packet encoder | +| MP3 (Layer III) | native | native; `.mp3` through `encode` / `FileEncoder`, frames through `mp3::Encoder` | +| Opus | native | native, packets (`opus::Encoder`; no file writer) | +| AC-3, E-AC-3 | native | native; `.ac3` / `.eac3` through `encode` / `FileEncoder`, packets through `ac3::encoder::Encoder` | | Vorbis, ADPCM, A-law, µ-law | symphonia | — | | Container | Demuxer | Timing | @@ -410,10 +451,17 @@ match craft_audio::decode(&bytes, None) { - `TrackDecoder` returns `Unsupported` for FLAC and Vorbis; `decode` and `Decoder` read those through symphonia. ALAC in CAF still goes through symphonia (craft-media has no CAF demuxer). -- ALAC: `EncodeFormat` has no ALAC entry; `alac::Encoder` writes packets and the configuration, - and the caller muxes them (MP4 `alac` box, Matroska `A_ALAC`). craft-media's MP4 muxer writes no - `chan` box, so an MP4 of more than two channels carries no explicit layout; decoders then use the - standard ALAC layout for the count. +- ALAC: craft-media's MP4 muxer writes no `chan` box, so an M4A of more than two channels (from + `EncodeFormat::Alac` or muxed from `alac::Encoder` packets) carries no explicit layout; decoders + then use the standard ALAC layout for the count, which is the one written. +- `EncodeFormat::Mp3`, `Ac3` and `Eac3` write raw streams, which cannot signal the codec's delay or + the length: the file decodes with 1057 (MP3) or 256 (AC-3, E-AC-3) frames of delay in front and + padded to whole frames at the end. MP3 gets no Xing / Info frame. `EncodeFormat::Aac` and `Alac` + (M4A) decode to the length written. +- `EncodeFormat::Aac` and `Alac` write the `moov` box after the audio (no fast start), and no + metadata. Raw ADTS AAC is not a file format of `encode`; `aac::EncoderConfig::with_adts` gives + the frames. +- This crate's file reader plays a raw E-AC-3 7.1 stream as its 5.1 independent substream. - ALAC 32-bit streams: ffmpeg does not decode their uncompressed (escaped) stereo frames, which Apple's encoder and this one write for audio that does not compress; Apple's decoder and this one do. @@ -481,7 +529,7 @@ finite count as silence and the rest are clamped to ±4, so no input makes an in decoder's 7680-bit input buffer. - Not yet: block switching (short blocks; transients pre-echo), `scfsi` and `preflag`, intensity stereo, a tonality-aware model, VBR/ABR, the Xing/Info and LAME gapless tags (the delay is not - signalled), CRC, free format, and an `EncodeFormat` entry for `encode`/`FileEncoder`. + signalled), CRC and free format. ### AC-3 and E-AC-3 encoding diff --git a/crates/audio/examples/encode.rs b/crates/audio/examples/encode.rs index 28de0f5ad..51cdecc84 100644 --- a/crates/audio/examples/encode.rs +++ b/crates/audio/examples/encode.rs @@ -1,4 +1,4 @@ -//! Write a tone as WAV and FLAC, whole and streamed, and as AAC packets. +//! Write a tone as WAV, FLAC and AAC in M4A, whole and streamed, and as AAC packets. //! //! `cargo run -p craft-audio --example encode --features lossless-encode,aac-encode -- out` @@ -28,7 +28,11 @@ fn main() -> Result<(), Box> { } enc.finish()?; - // AAC packets for an MP4 or Matroska muxer, with the configuration its sample entry needs. + // AAC in M4A at 160 kbit/s: the same call, with a bit rate in place of a bit depth. + let m4a = encode(&stereo, &EncodeOptions::new(EncodeFormat::Aac).with_bitrate(160_000))?; + std::fs::write(dir.join("tone.m4a"), m4a)?; + + // AAC packets for a muxer of your own, with the configuration its sample entry needs. let mut aac = craft_audio::aac::Encoder::new(craft_audio::aac::EncoderConfig::cbr(rate as u32, 2, 128_000))?; let mut units = aac.encode(&[&tone, &tone]); units.extend(aac.flush()); diff --git a/crates/audio/src/aac/encoder/mod.rs b/crates/audio/src/aac/encoder/mod.rs index 5a0ea5ac8..c641b790b 100644 --- a/crates/audio/src/aac/encoder/mod.rs +++ b/crates/audio/src/aac/encoder/mod.rs @@ -162,6 +162,16 @@ const HISTORY: usize = 2048; /// Bits per channel in a silent frame, rounded up: the smallest frame the encoder writes. const MIN_FRAME_BITS_PER_CHANNEL: u64 = 48; +/// The lowest and highest constant bit rate (bits per second) [`Encoder::new`] accepts for a +/// stream without ADTS headers: at least 1 kbit/s per channel and a silent frame, at most the +/// 6144 bits per channel and frame of the decoder buffer. +pub(crate) fn cbr_range(sample_rate: u32, channels: usize) -> (u32, u32) { + let (rate, channels) = (u64::from(sample_rate), channels as u64); + let silent = (MIN_FRAME_BITS_PER_CHANNEL * channels * rate).div_ceil(FRAME_LEN as u64); + let most = 6144 * channels * rate / FRAME_LEN as u64; + (u32::try_from(silent.max(1000 * channels)).unwrap_or(u32::MAX), u32::try_from(most).unwrap_or(u32::MAX)) +} + /// AAC-LC encoder. pub struct Encoder { cfg: EncoderConfig, diff --git a/crates/audio/src/aac/mod.rs b/crates/audio/src/aac/mod.rs index 297aa7972..f423a4e22 100644 --- a/crates/audio/src/aac/mod.rs +++ b/crates/audio/src/aac/mod.rs @@ -64,6 +64,8 @@ pub use config::{AdtsHeader, AudioSpecificConfig, ElementType, ProgramConfig, co #[cfg(feature = "aac-decode")] pub use decoder::Decoder; #[cfg(feature = "aac-encode")] +pub(crate) use encoder::cbr_range; +#[cfg(feature = "aac-encode")] pub use encoder::{BitrateMode, Encoder, EncoderConfig, EncoderStats}; #[cfg(feature = "aac-decode")] pub use latm::{LatmConfig, latm_config, latm_split}; diff --git a/crates/audio/src/ac3/mod.rs b/crates/audio/src/ac3/mod.rs index a8e8920d2..6bb19df8d 100644 --- a/crates/audio/src/ac3/mod.rs +++ b/crates/audio/src/ac3/mod.rs @@ -61,7 +61,7 @@ pub enum Error { pub type Result = std::result::Result; /// Data rate in kb/s by frmsizecod / 2 (Table 5.18). -const BITRATES: [u32; 19] = [32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320, 384, 448, 512, 576, 640]; +pub(crate) const BITRATES: [u32; 19] = [32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320, 384, 448, 512, 576, 640]; /// Full-bandwidth channels per acmod (Table 5.8). const NFCHANS: [usize; 8] = [2, 1, 2, 3, 3, 4, 4, 5]; diff --git a/crates/audio/src/lib.rs b/crates/audio/src/lib.rs index f8441a51d..f6be431dc 100644 --- a/crates/audio/src/lib.rs +++ b/crates/audio/src/lib.rs @@ -16,9 +16,10 @@ //! - [`TrackDecoder`] (any decoder feature): one track's packets from any demuxer to planar //! `f32` in WAV channel order. //! - [`encode`], [`FileEncoder`]: WAV/BWF/RF64 and AIFF/AIFF-C (feature `pcm-encode`, which also -//! gives [`wav_float_header`]) and FLAC (feature `flac-encode`), whole-buffer or incremental into -//! any `Write + Seek`. Feature `lossless-encode` turns on both; feature `encode` turns on -//! `lossless-encode` and every codec's encoder. +//! gives [`wav_float_header`]), FLAC (feature `flac-encode`), AAC-LC and ALAC in M4A +//! (`aac-encode`, `alac-encode`) and MP3, AC-3 and E-AC-3 streams (`mp3-encode`, `ac3-encode`, +//! `eac3-encode`), whole-buffer or incremental into any `Write + Seek`. Feature +//! `lossless-encode` turns on WAV, AIFF and FLAC; feature `encode` turns on every format. //! - [`wav_pcm`], [`aiff_pcm`] (feature `decode-native`) and [`pcm_wav_file`], [`pcm_wav_header`], //! [`pcm_aiff_file`], [`pcm_aiff_header`] (feature `pcm-encode`): the integer PCM of a WAV or AIFF //! file bit for bit, and minimal files around such PCM, for essence embedded in other containers. @@ -54,7 +55,15 @@ mod read; mod track; #[cfg(any(feature = "decode-native", feature = "pcm-encode"))] mod wav; -#[cfg(any(feature = "pcm-encode", feature = "flac-encode"))] +#[cfg(any( + feature = "pcm-encode", + feature = "flac-encode", + feature = "aac-encode", + feature = "alac-encode", + feature = "mp3-encode", + feature = "ac3-encode", + feature = "eac3-encode" +))] mod write; /// The FLAC packet encoder (RFC 9639), for a caller that muxes FLAC itself (into MP4, Matroska or @@ -100,7 +109,15 @@ pub use read::{RawPcm, aiff_pcm, wav_pcm}; pub use track::{LOOKAHEAD_PACKETS, TrackDecoder}; #[cfg(feature = "pcm-encode")] pub use write::wav_float_header; -#[cfg(any(feature = "pcm-encode", feature = "flac-encode"))] +#[cfg(any( + feature = "pcm-encode", + feature = "flac-encode", + feature = "aac-encode", + feature = "alac-encode", + feature = "mp3-encode", + feature = "ac3-encode", + feature = "eac3-encode" +))] pub use write::{ENCODE_EXTENSIONS, FileEncoder, encode, encode_format_for}; #[cfg(feature = "pcm-encode")] pub use write::{pcm_aiff_file, pcm_aiff_header, pcm_wav_file, pcm_wav_header}; @@ -215,7 +232,8 @@ impl From for AudioError { } /// The file formats [`encode`] writes. Each needs its feature: WAV and AIFF `pcm-encode`, FLAC -/// `flac-encode`; asking for one that is not built returns [`AudioError::Unsupported`]. +/// `flac-encode`, AAC `aac-encode`, ALAC `alac-encode`, MP3 `mp3-encode`, AC-3 `ac3-encode` and +/// E-AC-3 `eac3-encode`; asking for one that is not built returns [`AudioError::Unsupported`]. #[non_exhaustive] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] @@ -226,20 +244,46 @@ pub enum EncodeFormat { Aiff, /// FLAC (integer depths). Flac, + /// AAC-LC in an M4A (MP4) file, 1–8 channels at one of the 13 AAC sample rates. The edit list + /// skips the encoder's priming and ends at the last frame, so the file decodes to the length + /// that was written. + Aac, + /// Apple Lossless in an M4A (MP4) file (integer depths), 1–8 channels. + Alac, + /// An MP3 stream: mono or stereo at 32, 44.1 or 48 kHz, or 16, 22.05 or 24 kHz. + Mp3, + /// An AC-3 stream: up to 5.1 at 32, 44.1 or 48 kHz. + Ac3, + /// An E-AC-3 stream: up to 7.1 at 32, 44.1 or 48 kHz. + Eac3, } impl EncodeFormat { /// Every format, in the order menus list them. Whether [`encode`] writes one depends on its /// feature. - pub const ALL: &[EncodeFormat] = &[EncodeFormat::Wav, EncodeFormat::Aiff, EncodeFormat::Flac]; + pub const ALL: &[EncodeFormat] = &[ + EncodeFormat::Wav, + EncodeFormat::Aiff, + EncodeFormat::Flac, + EncodeFormat::Alac, + EncodeFormat::Aac, + EncodeFormat::Mp3, + EncodeFormat::Ac3, + EncodeFormat::Eac3, + ]; /// The extension a new file of this format gets, lower case and without the dot: `"wav"`, - /// `"aif"`, `"flac"`. [`encode_format_for`] maps it back. + /// `"aif"`, `"flac"`, `"m4a"` (AAC and ALAC), `"mp3"`, `"ac3"`, `"eac3"`. + /// [`encode_format_for`] maps it back, `"m4a"` to AAC. pub fn extension(self) -> &'static str { match self { EncodeFormat::Wav => "wav", EncodeFormat::Aiff => "aif", EncodeFormat::Flac => "flac", + EncodeFormat::Aac | EncodeFormat::Alac => "m4a", + EncodeFormat::Mp3 => "mp3", + EncodeFormat::Ac3 => "ac3", + EncodeFormat::Eac3 => "eac3", } } @@ -249,6 +293,10 @@ impl EncodeFormat { EncodeFormat::Wav => "audio/wav", EncodeFormat::Aiff => "audio/aiff", EncodeFormat::Flac => "audio/flac", + EncodeFormat::Aac | EncodeFormat::Alac => "audio/mp4", + EncodeFormat::Mp3 => "audio/mpeg", + EncodeFormat::Ac3 => "audio/ac3", + EncodeFormat::Eac3 => "audio/eac3", } } @@ -258,8 +306,44 @@ impl EncodeFormat { EncodeFormat::Wav => Container::Wav, EncodeFormat::Aiff => Container::Aiff, EncodeFormat::Flac => Container::Flac, + EncodeFormat::Aac | EncodeFormat::Alac => Container::Mp4, + EncodeFormat::Mp3 => Container::MpegAudio, + EncodeFormat::Ac3 | EncodeFormat::Eac3 => Container::Ac3, } } + + /// The codec of the audio this format writes. + pub fn codec(self) -> CodecId { + match self { + EncodeFormat::Wav | EncodeFormat::Aiff => CodecId::Pcm, + EncodeFormat::Flac => CodecId::Flac, + EncodeFormat::Aac => CodecId::Aac, + EncodeFormat::Alac => CodecId::Alac, + EncodeFormat::Mp3 => CodecId::Mp3, + EncodeFormat::Ac3 => CodecId::Ac3, + EncodeFormat::Eac3 => CodecId::Eac3, + } + } + + /// Whether the format loses audio: AAC, MP3, AC-3 and E-AC-3. These take + /// [`EncodeOptions::rate_control`] and ignore the bit depth and dither. + pub fn is_lossy(self) -> bool { + matches!(self, EncodeFormat::Aac | EncodeFormat::Mp3 | EncodeFormat::Ac3 | EncodeFormat::Eac3) + } +} + +/// How a lossy format spends bits ([`EncodeOptions::rate_control`]). +#[non_exhaustive] +#[derive(Debug, Clone, Copy, PartialEq)] +#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] +pub enum RateControl { + /// A constant bit rate in bits per second, for all channels together. A format with a fixed + /// set of rates (MP3, AC-3) uses the highest one not above it; a rate outside what the + /// stream can carry is moved to the nearest one inside. + Bitrate(u32), + /// A constant quality from 0.0 (smallest) to 1.0 (best), at whatever bit rate each frame + /// needs. AAC only; values outside the range are clamped, and NaN is an error. + Quality(f32), } /// Stored sample representation. @@ -418,9 +502,9 @@ pub enum BitDepth { pub struct EncodeOptions { /// Output file format. pub format: EncodeFormat, - /// Sample depth to write. + /// Sample depth to write (ignored by the lossy formats). pub bit_depth: BitDepth, - /// Add TPDF dither when quantizing to an integer depth. + /// Add TPDF dither when quantizing to an integer depth (ignored by the lossy formats). pub dither: bool, /// Write a BWF `bext` chunk (WAV only; ignored for other formats). pub bwf: Option, @@ -431,15 +515,27 @@ pub struct EncodeOptions { /// the count (they read 5 and 6 channels with side surrounds and 7 as 6.1 with sides, so the /// usual layouts for those counts get one; see the README's limits); AIFF has a fixed channel /// order and ignores it. It must have as many channels as the audio. + /// + /// AAC, ALAC, MP3, AC-3 and E-AC-3 store channels in their own order, so here the layout says + /// which speaker each channel of the audio (in WAV order) is, and the channels are reordered + /// to match. Each of these formats has a fixed set of layouts (AAC and ALAC one per channel + /// count, AC-3 one per coding mode); a layout outside it is [`AudioError::Unsupported`]. Side + /// and back surrounds are taken as the same pair where the format has only one. pub layout: Option, /// Write WAV in the RF64 layout even below 4 GiB (WAV only; ignored for other formats). pub force_rf64: bool, + /// The bit rate or quality of a lossy format (ignored by the others). `None` is a constant + /// 64 kbit/s per channel for AAC, 96 kbit/s per channel for MP3, and 96 kbit/s per + /// full-bandwidth channel (the LFE not counted) for AC-3 and E-AC-3, moved to the nearest rate + /// the stream can carry. + pub rate_control: Option, } impl EncodeOptions { - /// Options for `format`: 24-bit, no dither, no BWF chunk, the usual layout. + /// Options for `format`: 24-bit, no dither, no BWF chunk, the usual layout, the format's + /// default bit rate. pub fn new(format: EncodeFormat) -> Self { - Self { format, bit_depth: BitDepth::Int24, dither: false, bwf: None, layout: None, force_rf64: false } + Self { format, bit_depth: BitDepth::Int24, dither: false, bwf: None, layout: None, force_rf64: false, rate_control: None } } /// Sets `format`. @@ -477,6 +573,18 @@ impl EncodeOptions { self.force_rf64 = force_rf64; self } + + /// Sets `rate_control` to a constant bit rate in bits per second ([`RateControl::Bitrate`]). + pub fn with_bitrate(mut self, bits_per_second: u32) -> Self { + self.rate_control = Some(RateControl::Bitrate(bits_per_second)); + self + } + + /// Sets `rate_control` to a constant quality from 0.0 to 1.0 ([`RateControl::Quality`]). + pub fn with_quality(mut self, quality: f32) -> Self { + self.rate_control = Some(RateControl::Quality(quality)); + self + } } impl Default for EncodeOptions { diff --git a/crates/audio/src/write/coded.rs b/crates/audio/src/write/coded.rs new file mode 100644 index 000000000..415d309fc --- /dev/null +++ b/crates/audio/src/write/coded.rs @@ -0,0 +1,581 @@ +//! The coded formats of [`FileEncoder`](crate::FileEncoder): AAC-LC and ALAC in M4A (through +//! craft-media's MP4 muxer) and MP3, AC-3 and E-AC-3 as raw streams. [`Writer`] maps the caller's +//! WAV-order channels onto the encoder's order, drives the packet encoder, and for M4A records the +//! encoder's priming and the exact length in the edit list. + +// Each codec is its own feature, and so are the two sinks: with only some of them built, the +// other halves of the shared code are unused. +#![cfg_attr( + not(all(feature = "aac-encode", feature = "alac-encode", feature = "mp3-encode", feature = "ac3-encode", feature = "eac3-encode")), + allow(dead_code, unused_imports, unused_variables, unused_mut) +)] + +use super::failed_write_error; +use super::pcm::validate_layout; +use crate::{AudioBuffer, AudioError, ChannelLayout, EncodeFormat, EncodeOptions, RateControl, Result, Speaker}; +use std::io::{Cursor, Seek, SeekFrom, Write}; + +/// Frames handed to the encoder at a time, so its buffers and the packets waiting to be written +/// stay small however long a block is. Also the frames of an ALAC packet. +const CHUNK: usize = 4096; + +/// Bits per second per channel when no rate is asked for: AAC. +const AAC_DEFAULT_BPS_PER_CHANNEL: u32 = 64_000; +/// Kilobits per second per channel when no rate is asked for: MP3, and AC-3 and E-AC-3 (per +/// full-bandwidth channel). +const DEFAULT_KBPS_PER_CHANNEL: u32 = 96; + +/// The surround speaker a layout may name in place of `speaker`: formats with one surround pair +/// do not tell side from back, so a pair of either kind feeds it. +fn twin(speaker: Speaker) -> Option { + Some(match speaker { + Speaker::SideLeft => Speaker::BackLeft, + Speaker::SideRight => Speaker::BackRight, + Speaker::BackLeft => Speaker::SideLeft, + Speaker::BackRight => Speaker::SideRight, + _ => return None, + }) +} + +/// The speakers of `mask` as labels: `"L R C LFE Ls Rs"`. +fn labels(mask: u32) -> String { + ChannelLayout::from_mask(mask).speakers().iter().map(|s| s.label()).collect::>().join(" ") +} + +/// For each channel the encoder takes, the channel of the caller's audio that feeds it. `mask` is +/// the layout the format has for the channel count, and `order` the encoder's channel order over +/// it (for each encoder channel, the WAV-order channel of `mask`; `None` when the encoder takes +/// WAV order). `layout` names the speakers of the caller's channels. `None` when `layout` is not +/// the format's layout: it is unordered, or has a speaker the format has not. +fn channel_map(mask: u32, order: Option<&[usize]>, layout: &ChannelLayout) -> Option> { + let speakers = ChannelLayout::from_mask(mask).speakers(); + if speakers.len() != usize::from(layout.channels()) { + return None; + } + let mut map = Vec::with_capacity(speakers.len()); + for j in 0..speakers.len() { + let speaker = *speakers.get(order.and_then(|o| o.get(j).copied()).unwrap_or(j))?; + let at = layout.index_of(speaker).or_else(|| twin(speaker).and_then(|t| layout.index_of(t)))?; + if map.contains(&at) { + return None; + } + map.push(at); + } + Some(map) +} + +/// [`channel_map`] for a format with one layout per channel count, or why the audio does not fit. +fn fixed_map(name: &str, mask: u32, order: Option<&[usize]>, layout: &ChannelLayout) -> Result> { + if mask == 0 { + return Err(AudioError::Unsupported(format!("{name} cannot hold {} channels", layout.channels()))); + } + channel_map(mask, order, layout).ok_or_else(|| { + let given = match layout.mask() { + Some(m) => labels(m), + None => "no speaker assignment".into(), + }; + AudioError::Unsupported(format!("{name} holds {} channels as {}, not {given}; set `EncodeOptions::layout`", layout.channels(), labels(mask))) + }) +} + +/// The WAV mask of the speakers an AAC stream of `channels` channels has, as this crate's encoder +/// writes it and its decoder reports it: channel configurations 1–6, the 6.1 program config +/// element for 7, and configuration 7 (7.1 with a front pair left and right of centre) for 8. +#[cfg(feature = "aac-encode")] +fn aac_mask(channels: usize) -> u32 { + match channels { + 1 => 0x4, + 2 => 0x3, + 3 => 0x7, + 4 => 0x107, + 5 => 0x607, + 6 => 0x60F, + 7 => 0x70F, + 8 => 0xFF, + _ => 0, + } +} + +/// The encoder's channel order over [`aac_mask`]: [`crate::aac::aac_order`], and for 8 channels +/// configuration 7's C, Lc Rc, L R, Ls Rs, LFE over the WAV order L R C LFE Ls Rs Lc Rc. +#[cfg(feature = "aac-encode")] +fn aac_order(channels: usize) -> Option<&'static [usize]> { + if channels == 8 { Some(&[2, 6, 7, 0, 1, 4, 5, 3]) } else { crate::aac::aac_order(channels) } +} + +/// The AAC rate control for `rate`: a bit rate is kept within what the stream can carry, a +/// quality of 0–1 spans the encoder's VBR range. +#[cfg(feature = "aac-encode")] +fn aac_mode(rate: Option, sample_rate: u32, channels: usize) -> crate::aac::BitrateMode { + use crate::aac::BitrateMode; + let (lo, hi) = crate::aac::cbr_range(sample_rate, channels); + // An empty range (a rate or channel count the encoder refuses anyway) leaves the rate alone. + let fit = |bps: u32| if lo <= hi { bps.clamp(lo, hi) } else { bps }; + match rate { + None => BitrateMode::Cbr(fit(AAC_DEFAULT_BPS_PER_CHANNEL.saturating_mul(channels as u32))), + Some(RateControl::Bitrate(bps)) => BitrateMode::Cbr(fit(bps)), + // NaN stays NaN, which the encoder refuses. + Some(RateControl::Quality(q)) => BitrateMode::Vbr(1.0 + 4.0 * q.clamp(0.0, 1.0)), + } +} + +/// The bit rate in kbit/s for a codec with constant bit rates only. +fn constant_kbps(name: &str, rate: Option, default: u32) -> Result { + match rate { + None => Ok(default), + Some(RateControl::Bitrate(bps)) => Ok(bps / 1000), + Some(RateControl::Quality(_)) => { + Err(AudioError::Unsupported(format!("{name} is encoded at a constant bit rate; set a bit rate, not a quality"))) + } + } +} + +/// The AC-3 or E-AC-3 settings for audio with `layout`, and the channel map onto them: the coding +/// mode whose speakers the layout names, at the nearest bit rate the stream can carry. +#[cfg(any(feature = "ac3-encode", feature = "eac3-encode"))] +fn ac3_config( + codec: crate::ac3::encoder::Codec, + sample_rate: u32, + layout: &ChannelLayout, + rate: Option, +) -> Result<(crate::ac3::encoder::Config, Vec)> { + use crate::ac3::encoder::{Codec, CodingMode, Config}; + use CodingMode::*; + let name = if codec == Codec::Ac3 { "AC-3" } else { "E-AC-3" }; + let modes = [Mono, Stereo, ThreeFront, StereoSurround, ThreeFrontSurround, StereoTwoSurround, ThreeFrontTwoSurround, Surround71]; + let found = modes.iter().flat_map(|&mode| [false, true].map(|lfe| (mode, lfe))).find_map(|(mode, lfe)| { + // 7.1 is an E-AC-3 programme with an LFE; the encoder has no other. + if mode == Surround71 && (codec != Codec::Eac3 || !lfe) { + return None; + } + let config = Config { codec, sample_rate, bitrate_kbps: 0, mode, lfe }; + let map = channel_map(config.channel_layout().mask()?, None, layout)?; + Some((config, map)) + }); + let Some((mut config, map)) = found else { + let given = match layout.mask() { + Some(m) => labels(m), + None => "no speaker assignment".into(), + }; + return Err(AudioError::Unsupported(format!("{name} has no layout of {} channels as {given}", layout.channels()))); + }; + let full = config.mode.channels() as u32; + let want = constant_kbps(name, rate, DEFAULT_KBPS_PER_CHANNEL * full)?; + // What `Config::validate` asks of the rate: enough for the channels, and for AC-3 an entry of + // the frame size table, for E-AC-3 a syncframe its 11-bit word count can hold. + let least = if config.mode == Surround71 { 384 } else { 32 * full }; + config.bitrate_kbps = match codec { + Codec::Ac3 => { + let floor = crate::ac3::BITRATES.iter().copied().find(|&r| r >= least).unwrap_or(least); + crate::ac3::BITRATES.iter().rev().copied().find(|&r| r <= want).filter(|&r| r >= floor).unwrap_or(floor) + } + Codec::Eac3 => { + let most = if config.mode == Surround71 { 1024 } else { (2048 * u64::from(sample_rate) / 96_000).min(1024) as u32 }; + want.clamp(least, most.max(least)) + } + }; + Ok((config, map)) +} + +/// One encoded packet and the frames it decodes to. +struct Packet { + data: Vec, + frames: u32, +} + +/// A packet encoder of any of the codecs, taking planar `f32` in its own channel order. +enum Codec { + #[cfg(feature = "aac-encode")] + Aac(Box), + #[cfg(feature = "alac-encode")] + Alac { + enc: Box, + quantizers: Vec, + /// Quantized samples of the packet being filled, per channel. + pending: Vec>, + }, + #[cfg(feature = "mp3-encode")] + Mp3(Box), + #[cfg(any(feature = "ac3-encode", feature = "eac3-encode"))] + Ac3 { + enc: Box, + /// The block with every sample finite and within ±1, as the encoder requires. + planes: Vec>, + }, +} + +impl Codec { + /// Encodes `planes` (one slice per encoder channel, equally long, at most [`CHUNK`] frames) + /// and appends the packets completed. + fn push(&mut self, planes: &[&[f32]], out: &mut Vec) -> Result<()> { + match self { + #[cfg(feature = "aac-encode")] + Codec::Aac(enc) => out.extend(enc.encode(planes).into_iter().map(|data| Packet { data, frames: crate::aac::FRAME_LEN as u32 })), + #[cfg(feature = "alac-encode")] + Codec::Alac { enc, quantizers, pending } => { + let frames = planes.first().map_or(0, |p| p.len()); + let mut at = 0; + while at < frames { + let filled = pending.first().map_or(0, Vec::len); + let end = frames.min(at + CHUNK.saturating_sub(filled).max(1)); + for ((dst, q), src) in pending.iter_mut().zip(quantizers.iter_mut()).zip(planes) { + dst.extend(src.get(at..end).unwrap_or_default().iter().map(|&s| q.quantize(s))); + } + at = end; + if pending.first().is_some_and(|p| p.len() >= CHUNK) { + alac_packet(enc, pending, out)?; + } + } + } + #[cfg(feature = "mp3-encode")] + Codec::Mp3(enc) => { + let data = enc.encode(planes); + if !data.is_empty() { + out.push(Packet { data, frames: 0 }); + } + } + #[cfg(any(feature = "ac3-encode", feature = "eac3-encode"))] + Codec::Ac3 { enc, planes: clean } => { + for (dst, src) in clean.iter_mut().zip(planes) { + dst.clear(); + dst.extend(src.iter().map(|&s| if s.is_nan() { 0.0 } else { s.clamp(-1.0, 1.0) })); + } + let refs: Vec<&[f32]> = clean.iter().map(Vec::as_slice).collect(); + out.extend(enc.push(&refs)?.into_iter().map(|p| Packet { data: p.data, frames: p.samples })); + } + } + Ok(()) + } + + /// Encodes what the encoder still holds and appends the last packets. + fn finish(&mut self, out: &mut Vec) -> Result<()> { + match self { + #[cfg(feature = "aac-encode")] + Codec::Aac(enc) => out.extend(enc.flush().into_iter().map(|data| Packet { data, frames: crate::aac::FRAME_LEN as u32 })), + #[cfg(feature = "alac-encode")] + Codec::Alac { enc, pending, .. } => { + if pending.first().is_some_and(|p| !p.is_empty()) { + alac_packet(enc, pending, out)?; + } + } + #[cfg(feature = "mp3-encode")] + Codec::Mp3(enc) => { + let data = enc.flush(); + if !data.is_empty() { + out.push(Packet { data, frames: 0 }); + } + } + #[cfg(any(feature = "ac3-encode", feature = "eac3-encode"))] + Codec::Ac3 { enc, .. } => out.extend(enc.finish()?.packets.into_iter().map(|p| Packet { data: p.data, frames: p.samples })), + } + Ok(()) + } + + /// Decoded frames before the first frame of the audio. + fn priming(&self) -> u32 { + match self { + #[cfg(feature = "aac-encode")] + Codec::Aac(enc) => enc.priming_samples(), + #[allow(unreachable_patterns)] + _ => 0, + } + } + + /// The MP4 sample entry of the stream as encoded so far (`bytes` in packets of `frames` + /// frames in all): the configuration a decoder needs, with the average bit rate. + #[cfg(any(feature = "aac-encode", feature = "alac-encode"))] + fn sample_entry(&self, sample_rate: u32, channels: u32, bytes: u64, frames: u64) -> Option { + use craft_media::isobmff::{CodecConfig, FourCc, SampleEntry}; + match self { + #[cfg(feature = "aac-encode")] + Codec::Aac(enc) => { + let mut entry = SampleEntry::aac(enc.audio_specific_config(), channels, sample_rate); + if let CodecConfig::Aac(config) = &mut entry.codec + && frames > 0 + { + let bps = u128::from(bytes) * 8 * u128::from(sample_rate) / u128::from(frames); + config.avg_bitrate = u32::try_from(bps).unwrap_or(u32::MAX); + } + Some(entry) + } + #[cfg(feature = "alac-encode")] + Codec::Alac { enc, .. } => { + let bits = u16::from(enc.encoder_config().bit_depth); + Some(SampleEntry::audio(FourCc(*b"alac"), CodecConfig::Alac { cookie: enc.cookie() }, channels, f64::from(sample_rate), bits)) + } + #[allow(unreachable_patterns)] + _ => None, + } + } +} + +/// Encodes the pending samples as one ALAC packet and empties them. +#[cfg(feature = "alac-encode")] +fn alac_packet(enc: &mut crate::alac::Encoder, pending: &mut [Vec], out: &mut Vec) -> Result<()> { + let refs: Vec<&[i32]> = pending.iter().map(Vec::as_slice).collect(); + let frames = refs.first().map_or(0, |p| p.len()) as u32; + let data = enc.encode(&refs)?; + pending.iter_mut().for_each(Vec::clear); + out.push(Packet { data, frames }); + Ok(()) +} + +/// A muxer's error as this crate's: a failed write stays an I/O error. +#[cfg(any(feature = "aac-encode", feature = "alac-encode"))] +fn mux_error(e: craft_media::isobmff::Error) -> AudioError { + match e { + craft_media::isobmff::Error::Io(e) => AudioError::Io(e), + e => AudioError::Encode(format!("M4A: {e}")), + } +} + +/// A sink seen from where the file starts: position 0 is the sink's position when the file was +/// begun. The MP4 muxer writes chunk offsets as stream positions, and they count from the first +/// byte of the file, which need not be the first byte of the sink. +#[cfg(any(feature = "aac-encode", feature = "alac-encode"))] +struct FromStart { + out: W, + start: u64, +} + +#[cfg(any(feature = "aac-encode", feature = "alac-encode"))] +impl Write for FromStart { + fn write(&mut self, data: &[u8]) -> std::io::Result { + self.out.write(data) + } + + fn write_all(&mut self, data: &[u8]) -> std::io::Result<()> { + self.out.write_all(data) + } + + fn flush(&mut self) -> std::io::Result<()> { + self.out.flush() + } +} + +#[cfg(any(feature = "aac-encode", feature = "alac-encode"))] +impl Seek for FromStart { + fn seek(&mut self, to: SeekFrom) -> std::io::Result { + let to = match to { + SeekFrom::Start(at) => SeekFrom::Start( + self.start.checked_add(at).ok_or_else(|| std::io::Error::new(std::io::ErrorKind::InvalidInput, "seek past the end of the sink"))?, + ), + relative => relative, + }; + let at = self.out.seek(to)?; + at.checked_sub(self.start).ok_or_else(|| std::io::Error::new(std::io::ErrorKind::InvalidInput, "seek to before the start of the file")) + } +} + +/// An M4A file being written: one audio track whose samples are the packets. +/// +/// The last packet is held back until the length is known: its duration is cut to the audio's +/// last frame, so the sample durations add up to the priming plus the audio, and the edit that +/// skips the priming ends where the audio does. The movie timescale is the sample rate, which +/// keeps that edit exact. +#[cfg(any(feature = "aac-encode", feature = "alac-encode"))] +struct M4a { + mux: craft_media::isobmff::Mp4Writer>, + /// The track, added with the first packet: a file with no audio gets a track without an edit. + track: Option, + entry: craft_media::isobmff::SampleEntry, + sample_rate: u32, + channels: u32, + priming: u32, + held: Option, + /// Frames and bytes of the packets written, the held one not counted. + frames: u64, + bytes: u64, +} + +#[cfg(any(feature = "aac-encode", feature = "alac-encode"))] +impl M4a { + fn new(mut out: W, codec: &Codec, sample_rate: u32, channels: u32) -> Result { + use craft_media::isobmff::{Brand, Mp4Writer, WriterOptions}; + let start = out.stream_position()?; + let out = FromStart { out, start }; + let entry = codec.sample_entry(sample_rate, channels, 0, 0).ok_or_else(|| AudioError::Unsupported("M4A holds AAC and ALAC".into()))?; + let mut options = WriterOptions::new(Brand::Mp4); + options.movie_timescale = sample_rate; + let mux = Mp4Writer::new(out, options).map_err(mux_error)?; + Ok(M4a { mux, track: None, entry, sample_rate, channels, priming: codec.priming(), held: None, frames: 0, bytes: 0 }) + } + + fn track(&mut self, has_audio: bool) -> Result { + if let Some(track) = self.track { + return Ok(track); + } + let mut config = craft_media::isobmff::TrackConfig::new(self.entry.clone(), self.sample_rate); + if has_audio && self.priming > 0 { + config.media_start = Some(i64::from(self.priming)); + } + let track = self.mux.add_track(config).map_err(mux_error)?; + self.track = Some(track); + Ok(track) + } + + fn sample(&mut self, packet: &Packet, duration: u32) -> Result<()> { + let track = self.track(true)?; + let sample = craft_media::isobmff::WriteSample { data: &packet.data, duration, composition_offset: 0, is_sync: true }; + self.mux.write_sample(track, sample).map_err(mux_error)?; + self.frames += u64::from(duration); + self.bytes += packet.data.len() as u64; + Ok(()) + } + + fn write(&mut self, packet: Packet) -> Result<()> { + if let Some(held) = self.held.replace(packet) { + self.sample(&held, held.frames)?; + } + Ok(()) + } + + /// Writes the last packet, cut to the end of `audio_frames` frames of audio, and the `moov`. + fn finish(mut self, codec: &Codec, audio_frames: u64) -> Result { + if let Some(held) = self.held.take() { + let rest = (u64::from(self.priming) + audio_frames).saturating_sub(self.frames); + self.sample(&held, rest.min(u64::from(held.frames)) as u32)?; + } + let track = self.track(false)?; + // The configuration is complete only now: the bit rate, and ALAC's largest packet. + if let Some(entry) = codec.sample_entry(self.sample_rate, self.channels, self.bytes, self.frames) { + self.mux.set_sample_entry(track, entry).map_err(mux_error)?; + } + Ok(self.mux.finish().map_err(mux_error)?.out) + } +} + +/// Where the packets go. +enum Sink { + #[cfg(any(feature = "aac-encode", feature = "alac-encode"))] + M4a(Box>), + /// The packets in a row are the file. + Raw(W), +} + +/// A file of one of the coded formats written block by block. +pub(crate) struct Writer { + codec: Codec, + sink: Sink, + /// For each encoder channel, the caller's channel that feeds it. + map: Vec, + frames: u64, + packets: Vec, + /// Set when a write has failed: the encoder and the sink no longer agree, so the writer + /// refuses every later call. + failed: bool, +} + +impl Writer { + pub(crate) fn new(out: W, opts: &EncodeOptions, sample_rate: u32, channels: usize) -> Result { + validate_layout(channels, sample_rate)?; + let layout = opts.layout.unwrap_or_else(|| ChannelLayout::default_for(channels as u16)); + let (codec, map) = match opts.format { + #[cfg(feature = "aac-encode")] + EncodeFormat::Aac => { + let map = fixed_map("AAC", aac_mask(channels), aac_order(channels), &layout)?; + let config = crate::aac::EncoderConfig { + mode: aac_mode(opts.rate_control, sample_rate, channels), + ..crate::aac::EncoderConfig::cbr(sample_rate, channels, 0) + }; + (Codec::Aac(Box::new(crate::aac::Encoder::new(config)?)), map) + } + #[cfg(feature = "alac-encode")] + EncodeFormat::Alac => { + let count = u8::try_from(channels).unwrap_or(u8::MAX); + let map = fixed_map("ALAC", crate::alac::channel_mask(count), crate::alac::alac_order(count), &layout)?; + let bits = match opts.bit_depth { + crate::BitDepth::Int16 => 16, + crate::BitDepth::Int24 => 24, + crate::BitDepth::Int32 => 32, + crate::BitDepth::Float32 => return Err(AudioError::Unsupported("ALAC cannot store 32-bit float samples".into())), + }; + let enc = crate::alac::Encoder::new(crate::alac::EncoderConfig::new(sample_rate, count, bits).with_frame_length(CHUNK as u32))?; + let quantizers = super::pcm::Quantizer::per_channel(u32::from(bits), opts.dither, channels); + (Codec::Alac { enc: Box::new(enc), quantizers, pending: vec![Vec::with_capacity(CHUNK); channels] }, map) + } + #[cfg(feature = "mp3-encode")] + EncodeFormat::Mp3 => { + let mask = match channels { + 1 => 0x4, + 2 => 0x3, + _ => 0, + }; + let map = fixed_map("MP3", mask, None, &layout)?; + let want = constant_kbps("MP3", opts.rate_control, DEFAULT_KBPS_PER_CHANNEL * channels as u32)?; + // A sample rate MP3 has not is the encoder's to refuse. + let kbps = crate::mp3::nearest_bitrate(sample_rate, want).unwrap_or(want); + (Codec::Mp3(Box::new(crate::mp3::Encoder::new(crate::mp3::Config::cbr(sample_rate, channels, kbps))?)), map) + } + #[cfg(any(feature = "ac3-encode", feature = "eac3-encode"))] + EncodeFormat::Ac3 | EncodeFormat::Eac3 => { + let codec = if opts.format == EncodeFormat::Ac3 { crate::ac3::encoder::Codec::Ac3 } else { crate::ac3::encoder::Codec::Eac3 }; + let (config, map) = ac3_config(codec, sample_rate, &layout, opts.rate_control)?; + (Codec::Ac3 { enc: Box::new(crate::ac3::encoder::Encoder::new(config)?), planes: vec![Vec::with_capacity(CHUNK); channels] }, map) + } + #[allow(unreachable_patterns)] + f => return Err(AudioError::Unsupported(format!("writing {f:?}"))), + }; + let sink = match opts.format { + #[cfg(any(feature = "aac-encode", feature = "alac-encode"))] + EncodeFormat::Aac | EncodeFormat::Alac => Sink::M4a(Box::new(M4a::new(out, &codec, sample_rate, channels as u32)?)), + _ => Sink::Raw(out), + }; + Ok(Writer { codec, sink, map, frames: 0, packets: Vec::new(), failed: false }) + } + + /// Hands the packets waiting to the sink. + fn drain(&mut self) -> Result<()> { + for packet in self.packets.drain(..) { + match &mut self.sink { + #[cfg(any(feature = "aac-encode", feature = "alac-encode"))] + Sink::M4a(m4a) => m4a.write(packet)?, + Sink::Raw(out) => out.write_all(&packet.data)?, + } + } + Ok(()) + } + + /// Appends `frames` frames of `block`, which holds every channel at least that long. + pub(crate) fn write>(&mut self, block: &[C], frames: usize) -> Result<()> { + if self.failed { + return Err(failed_write_error()); + } + for at in (0..frames).step_by(CHUNK) { + let end = frames.min(at + CHUNK); + let planes: Vec<&[f32]> = self.map.iter().map(|&c| block.get(c).and_then(|p| p.as_ref().get(at..end)).unwrap_or_default()).collect(); + let written = self.codec.push(&planes, &mut self.packets).and_then(|()| self.drain()); + if let Err(e) = written { + self.failed = true; + return Err(e); + } + } + self.frames = self.frames.saturating_add(frames as u64); + Ok(()) + } + + pub(crate) fn finish(mut self) -> Result { + if self.failed { + return Err(failed_write_error()); + } + self.codec.finish(&mut self.packets)?; + self.drain()?; + match self.sink { + #[cfg(any(feature = "aac-encode", feature = "alac-encode"))] + Sink::M4a(m4a) => m4a.finish(&self.codec, self.frames), + Sink::Raw(mut out) => { + out.flush()?; + Ok(out) + } + } + } +} + +pub(crate) fn encode(buf: &AudioBuffer, opts: &EncodeOptions) -> Result> { + let mut w = Writer::new(Cursor::new(Vec::new()), opts, buf.sample_rate, buf.channels.len())?; + w.write(&buf.channels, buf.frames())?; + Ok(w.finish()?.into_inner()) +} + +#[cfg(test)] +mod tests; diff --git a/crates/audio/src/write/coded/tests.rs b/crates/audio/src/write/coded/tests.rs new file mode 100644 index 000000000..4aeaac66e --- /dev/null +++ b/crates/audio/src/write/coded/tests.rs @@ -0,0 +1,115 @@ +use super::*; + +fn map(mask: u32, order: Option<&[usize]>, layout: u32) -> Option> { + channel_map(mask, order, &ChannelLayout::from_mask(layout)) +} + +/// Channels are matched by speaker, not by position: a layout that lists the same speakers in +/// another WAV order is reordered, and one with other speakers is refused. +#[test] +fn channels_are_mapped_by_speaker() { + // L R C LFE Ls Rs onto itself, and onto an encoder order C L R Ls Rs LFE. + assert_eq!(map(0x60F, None, 0x60F), Some(vec![0, 1, 2, 3, 4, 5])); + assert_eq!(map(0x60F, Some(&[2, 0, 1, 4, 5, 3]), 0x60F), Some(vec![2, 0, 1, 4, 5, 3])); + // Back surrounds feed a format that has one surround pair, and the other way round. + assert_eq!(map(0x60F, None, 0x3F), Some(vec![0, 1, 2, 3, 4, 5])); + assert_eq!(map(0x3F, None, 0x60F), Some(vec![0, 1, 2, 3, 4, 5])); + // 6.1 with the back centre after the pair (L R C LFE Lb Rb Cb) onto L R C LFE Cb Ls Rs. + assert_eq!(map(0x70F, None, 0x13F), Some(vec![0, 1, 2, 3, 6, 4, 5])); + // Quad has no centre; 7.1 with sides and backs has no front pair left and right of centre. + assert_eq!(map(0x107, None, 0x33), None); + assert_eq!(map(0xFF, None, 0x63F), None); + // With both pairs in the format, one pair cannot feed both. + assert_eq!(map(0x63F, None, 0xFF), None); + assert_eq!(channel_map(0x3, None, &ChannelLayout::unordered(2)), None); + assert_eq!(map(0x3, None, 0x7), None); +} + +#[cfg(feature = "aac-encode")] +#[test] +fn every_aac_channel_count_has_a_layout_and_an_order() { + for channels in 1..=8 { + let mask = aac_mask(channels); + assert_eq!(mask.count_ones() as usize, channels); + let mut order = map(mask, aac_order(channels), mask).unwrap(); + order.sort_unstable(); + assert_eq!(order, (0..channels).collect::>()); + } + assert_eq!(aac_mask(9), 0); + // Configuration 7: C, Lc Rc, L R, Ls Rs, LFE. + let wide: Vec = ChannelLayout::from_mask(0xFF).speakers(); + let named: Vec = aac_order(8).unwrap().iter().map(|&c| wide[c]).collect(); + use Speaker::*; + assert_eq!(named, [FrontCenter, FrontLeftOfCenter, FrontRightOfCenter, FrontLeft, FrontRight, BackLeft, BackRight, Lfe]); +} + +/// The range the writer keeps a bit rate in is the one the encoder accepts. +#[cfg(feature = "aac-encode")] +#[test] +fn the_aac_bit_rate_range_is_the_encoders() { + use crate::aac::{Encoder, EncoderConfig, SAMPLE_RATES}; + for &rate in &SAMPLE_RATES { + for channels in 1..=8 { + let (lo, hi) = crate::aac::cbr_range(rate, channels); + assert!(lo <= hi, "{rate} Hz, {channels} channels"); + let accepts = |bps| Encoder::new(EncoderConfig::cbr(rate, channels, bps)).is_ok(); + assert!(accepts(lo) && accepts(hi), "{rate} Hz, {channels} channels: {lo}..={hi}"); + assert!(!accepts(lo - 1) && !accepts(hi + 1), "{rate} Hz, {channels} channels: {lo}..={hi}"); + for want in [None, Some(RateControl::Bitrate(0)), Some(RateControl::Bitrate(u32::MAX))] { + let mode = aac_mode(want, rate, channels); + assert!( + Encoder::new(EncoderConfig { mode, ..EncoderConfig::cbr(rate, channels, 0) }).is_ok(), + "{rate} Hz, {channels} channels, {want:?}" + ); + } + } + } +} + +/// Every layout the AC-3 encoders have is found from its speakers, at a bit rate the encoder +/// accepts whatever rate was asked for. +#[cfg(all(feature = "ac3-encode", feature = "eac3-encode"))] +#[test] +fn ac3_settings_follow_the_layout_and_validate() { + use crate::ac3::encoder::{Codec, CodingMode}; + let layouts = [ + (0x4, CodingMode::Mono, false), + (0x3, CodingMode::Stereo, false), + (0xB, CodingMode::Stereo, true), + (0x7, CodingMode::ThreeFront, false), + (0x103, CodingMode::StereoSurround, false), + (0x107, CodingMode::ThreeFrontSurround, false), + (0x33, CodingMode::StereoTwoSurround, false), + (0x603, CodingMode::StereoTwoSurround, false), + (0x37, CodingMode::ThreeFrontTwoSurround, false), + (0x3F, CodingMode::ThreeFrontTwoSurround, true), + (0x60F, CodingMode::ThreeFrontTwoSurround, true), + ]; + for codec in [Codec::Ac3, Codec::Eac3] { + for sample_rate in [32_000, 44_100, 48_000] { + for (mask, mode, lfe) in layouts { + for want in [None, Some(RateControl::Bitrate(0)), Some(RateControl::Bitrate(200_000)), Some(RateControl::Bitrate(u32::MAX))] { + let layout = ChannelLayout::from_mask(mask); + let (config, map) = ac3_config(codec, sample_rate, &layout, want).unwrap(); + assert_eq!((config.mode, config.lfe), (mode, lfe), "{mask:#x}"); + assert_eq!(map, (0..usize::from(layout.channels())).collect::>()); + assert_eq!(config.validate(), Ok(()), "{codec:?} {sample_rate} {mask:#x} {want:?}: {} kbit/s", config.bitrate_kbps); + } + } + let seven_one = ac3_config(codec, sample_rate, &ChannelLayout::SURROUND_7_1, Some(RateControl::Bitrate(u32::MAX))); + match codec { + Codec::Ac3 => assert!(matches!(seven_one, Err(AudioError::Unsupported(_)))), + Codec::Eac3 => assert_eq!(seven_one.unwrap().0.validate(), Ok(())), + } + } + } + // The highest table rate not above the one asked for; the default is 96 kbit/s per channel. + let rate = |codec, mask, want| ac3_config(codec, 48_000, &ChannelLayout::from_mask(mask), want).unwrap().0.bitrate_kbps; + assert_eq!(rate(Codec::Ac3, 0x3, Some(RateControl::Bitrate(200_000))), 192); + assert_eq!(rate(Codec::Ac3, 0x3, None), 192); + assert_eq!(rate(Codec::Ac3, 0x60F, None), 448); + assert_eq!(rate(Codec::Ac3, 0x60F, Some(RateControl::Bitrate(1))), 160); + assert_eq!(rate(Codec::Eac3, 0x3, Some(RateControl::Bitrate(200_500))), 200); + assert!(matches!(ac3_config(Codec::Ac3, 48_000, &ChannelLayout::STEREO, Some(RateControl::Quality(0.5))), Err(AudioError::Unsupported(_)))); + assert!(matches!(ac3_config(Codec::Ac3, 48_000, &ChannelLayout::unordered(2), None), Err(AudioError::Unsupported(_)))); +} diff --git a/crates/audio/src/write/mod.rs b/crates/audio/src/write/mod.rs index 2355a7b05..c743965cb 100644 --- a/crates/audio/src/write/mod.rs +++ b/crates/audio/src/write/mod.rs @@ -1,8 +1,11 @@ -//! Encoding: WAV/BWF/RF64 and AIFF/AIFF-C writers (`pcm-encode`) and the FLAC encoder -//! (`flac-encode`), whole-buffer and streaming. +//! Encoding: WAV/BWF/RF64 and AIFF/AIFF-C writers (`pcm-encode`), the FLAC encoder +//! (`flac-encode`) and the coded formats (AAC and ALAC in M4A, MP3, AC-3 and E-AC-3 streams, each +//! with its codec's feature), whole-buffer and streaming. #[cfg(feature = "pcm-encode")] mod aiff; +#[cfg(any(feature = "aac-encode", feature = "alac-encode", feature = "mp3-encode", feature = "ac3-encode", feature = "eac3-encode"))] +mod coded; #[cfg(feature = "flac-encode")] pub(crate) mod flac; mod pcm; @@ -16,9 +19,13 @@ use crate::{AudioBuffer, AudioError, ChannelLayout, EncodeFormat, EncodeOptions, pub use raw::{pcm_aiff_file, pcm_aiff_header, pcm_wav_file, pcm_wav_header}; use std::io::{Seek, Write}; -/// Encode `buf` as WAV/BWF, AIFF/AIFF-C or FLAC. Integer depths clamp samples to [-1, 1]; float +/// Encode `buf` as the file `opts.format` names. Integer depths clamp samples to [-1, 1]; float /// keeps values above full scale. `opts.layout`, when set, must have `buf`'s channel count. /// +/// The lossy formats take `opts.rate_control`. AAC and ALAC are written as M4A, whose edit list +/// makes the file decode to exactly `buf`'s frames. MP3, AC-3 and E-AC-3 are raw streams, which +/// have no place for that: they decode with the codec's delay in front and padded to whole frames. +/// /// ``` /// # #[cfg(feature = "pcm-encode")] { /// use craft_audio::{AudioBuffer, BitDepth, EncodeFormat, EncodeOptions, encode}; @@ -32,6 +39,7 @@ use std::io::{Seek, Write}; pub fn encode(buf: &AudioBuffer, opts: &EncodeOptions) -> Result> { check_built(opts.format)?; // Checked for every format; WAV and FLAC record it. + #[cfg_attr(not(any(feature = "pcm-encode", feature = "flac-encode")), allow(unused_variables))] let mask = opts.layout.map(|l| wav_mask(&l, buf.channels.len())).transpose()?; match opts.format { #[cfg(feature = "pcm-encode")] @@ -40,6 +48,8 @@ pub fn encode(buf: &AudioBuffer, opts: &EncodeOptions) -> Result> { EncodeFormat::Aiff => aiff::encode(buf, opts.bit_depth, opts.dither), #[cfg(feature = "flac-encode")] EncodeFormat::Flac => flac::encode(buf, opts.bit_depth, opts.dither, mask), + #[cfg(any(feature = "aac-encode", feature = "alac-encode", feature = "mp3-encode", feature = "ac3-encode", feature = "eac3-encode"))] + EncodeFormat::Aac | EncodeFormat::Alac | EncodeFormat::Mp3 | EncodeFormat::Ac3 | EncodeFormat::Eac3 => coded::encode(buf, opts), #[allow(unreachable_patterns)] f => Err(AudioError::Unsupported(format!("writing {f:?}"))), } @@ -47,31 +57,57 @@ pub fn encode(buf: &AudioBuffer, opts: &EncodeOptions) -> Result> { /// Refuses a format whose writer is not built, before anything else about the request is checked. fn check_built(format: EncodeFormat) -> Result<()> { - let (built, feature) = - if format == EncodeFormat::Flac { (cfg!(feature = "flac-encode"), "flac-encode") } else { (cfg!(feature = "pcm-encode"), "pcm-encode") }; + let (built, feature) = match format { + EncodeFormat::Wav | EncodeFormat::Aiff => (cfg!(feature = "pcm-encode"), "pcm-encode"), + EncodeFormat::Flac => (cfg!(feature = "flac-encode"), "flac-encode"), + EncodeFormat::Aac => (cfg!(feature = "aac-encode"), "aac-encode"), + EncodeFormat::Alac => (cfg!(feature = "alac-encode"), "alac-encode"), + EncodeFormat::Mp3 => (cfg!(feature = "mp3-encode"), "mp3-encode"), + EncodeFormat::Ac3 => (cfg!(feature = "ac3-encode"), "ac3-encode"), + EncodeFormat::Eac3 => (cfg!(feature = "eac3-encode"), "eac3-encode"), + }; if built { Ok(()) } else { Err(AudioError::Unsupported(format!("writing {format:?} needs the `{feature}` feature"))) } } -/// The file extensions of the formats [`encode`] can write (those whose features are on). -#[cfg(all(feature = "pcm-encode", feature = "flac-encode"))] -pub const ENCODE_EXTENSIONS: &[&str] = &["wav", "wave", "bwf", "aif", "aiff", "aifc", "flac"]; -/// The file extensions of the formats [`encode`] can write (those whose features are on). -#[cfg(all(feature = "pcm-encode", not(feature = "flac-encode")))] -pub const ENCODE_EXTENSIONS: &[&str] = &["wav", "wave", "bwf", "aif", "aiff", "aifc"]; -/// The file extensions of the formats [`encode`] can write (those whose features are on). -#[cfg(all(feature = "flac-encode", not(feature = "pcm-encode")))] -pub const ENCODE_EXTENSIONS: &[&str] = &["flac"]; +/// Every extension [`ENCODE_EXTENSIONS`] can list, and how many of them the features built give. +const fn extensions() -> ([&'static str; 12], usize) { + let mut all = [""; 12]; + let mut n = 0; + macro_rules! add { + ($built:expr, $($extension:literal),+) => { + if $built { + $( + all[n] = $extension; + n += 1; + )+ + } + }; + } + add!(cfg!(feature = "pcm-encode"), "wav", "wave", "bwf", "aif", "aiff", "aifc"); + add!(cfg!(feature = "flac-encode"), "flac"); + add!(cfg!(any(feature = "aac-encode", feature = "alac-encode")), "m4a"); + add!(cfg!(feature = "mp3-encode"), "mp3"); + add!(cfg!(feature = "ac3-encode"), "ac3"); + add!(cfg!(feature = "eac3-encode"), "eac3", "ec3"); + (all, n) +} -/// The format [`encode`] writes for a file extension or format name (`wav`, `aiff`, `flac`, -/// case-insensitive, with or without the dot), or `None` when it cannot write it. `aifc` is -/// AIFF: float AIFF is written as AIFF-C. +const EXTENSIONS: ([&str; 12], usize) = extensions(); + +/// The file extensions of the formats [`encode`] can write (those whose features are on). +pub const ENCODE_EXTENSIONS: &[&str] = EXTENSIONS.0.split_at(EXTENSIONS.1).0; + +/// The format [`encode`] writes for a file extension or format name (`wav`, `aiff`, `flac`, `m4a`, +/// `mp3`, `ac3`, `eac3`, case-insensitive, with or without the dot), or `None` when it cannot +/// write it. `aifc` is AIFF: float AIFF is written as AIFF-C. `m4a` is AAC when the AAC encoder +/// is built and ALAC otherwise; `alac` always names ALAC. /// /// ``` /// # #[cfg(feature = "pcm-encode")] { /// use craft_audio::{EncodeFormat, encode_format_for}; /// /// assert_eq!(encode_format_for(".AIFF"), Some(EncodeFormat::Aiff)); -/// assert_eq!(encode_format_for("mp3"), None); +/// assert_eq!(encode_format_for("ogg"), None); /// # } /// ``` pub fn encode_format_for(name: &str) -> Option { @@ -82,6 +118,18 @@ pub fn encode_format_for(name: &str) -> Option { "aif" | "aiff" | "aifc" => Some(EncodeFormat::Aiff), #[cfg(feature = "flac-encode")] "flac" => Some(EncodeFormat::Flac), + #[cfg(feature = "aac-encode")] + "m4a" => Some(EncodeFormat::Aac), + #[cfg(all(feature = "alac-encode", not(feature = "aac-encode")))] + "m4a" => Some(EncodeFormat::Alac), + #[cfg(feature = "alac-encode")] + "alac" => Some(EncodeFormat::Alac), + #[cfg(feature = "mp3-encode")] + "mp3" => Some(EncodeFormat::Mp3), + #[cfg(feature = "ac3-encode")] + "ac3" => Some(EncodeFormat::Ac3), + #[cfg(feature = "eac3-encode")] + "eac3" | "ec3" => Some(EncodeFormat::Eac3), _ => None, } } @@ -102,9 +150,8 @@ fn failed_write_error() -> AudioError { AudioError::Encode("the stream encoder already failed on an earlier write; its output is incomplete".into()) } -/// Writes WAV/BWF (RF64 above 4 GiB), AIFF / AIFF-C `fl32` or FLAC block by block, producing -/// the same bytes [`encode`] would for the whole buffer: a file of any length never -/// has to fit in memory. The file starts at the sink's position, and nothing may follow that +/// Writes a file of any [`EncodeFormat`] block by block, producing the same bytes [`encode`] +/// would for the whole buffer: a file of any length never has to fit in memory. The file starts at the sink's position, and nothing may follow that /// position (a new file, or one truncated there): the encoder cannot truncate a `Write + Seek`, /// so the bytes of a longer file already there would stay after the new one. /// @@ -125,30 +172,25 @@ fn failed_write_error() -> AudioError { /// ``` pub struct FileEncoder { writer: Writer, + format: EncodeFormat, channels: usize, } impl std::fmt::Debug for FileEncoder { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { - let format = match &self.writer { - #[cfg(feature = "pcm-encode")] - Writer::Wav(_) => EncodeFormat::Wav, - #[cfg(feature = "pcm-encode")] - Writer::Aiff(_) => EncodeFormat::Aiff, - #[cfg(feature = "flac-encode")] - Writer::Flac(_) => EncodeFormat::Flac, - }; - f.debug_struct("FileEncoder").field("format", &format).finish_non_exhaustive() + f.debug_struct("FileEncoder").field("format", &self.format).finish_non_exhaustive() } } -enum Writer { +enum Writer { #[cfg(feature = "pcm-encode")] Wav(wav::Writer), #[cfg(feature = "pcm-encode")] Aiff(aiff::Writer), #[cfg(feature = "flac-encode")] Flac(flac::Writer), + #[cfg(any(feature = "aac-encode", feature = "alac-encode", feature = "mp3-encode", feature = "ac3-encode", feature = "eac3-encode"))] + Coded(Box>), } impl FileEncoder { @@ -156,7 +198,10 @@ impl FileEncoder { /// `opts.layout`, when set, must have `channels` channels. pub fn new(out: W, opts: &EncodeOptions, sample_rate: u32, channels: u16) -> Result { check_built(opts.format)?; - let (depth, dither, channels) = (opts.bit_depth, opts.dither, usize::from(channels)); + let channels = usize::from(channels); + #[cfg_attr(not(any(feature = "pcm-encode", feature = "flac-encode")), allow(unused_variables))] + let (depth, dither) = (opts.bit_depth, opts.dither); + #[cfg_attr(not(any(feature = "pcm-encode", feature = "flac-encode")), allow(unused_variables))] let mask = opts.layout.map(|l| wav_mask(&l, channels)).transpose()?; let writer = match opts.format { #[cfg(feature = "pcm-encode")] @@ -172,24 +217,32 @@ impl FileEncoder { EncodeFormat::Aiff => Writer::Aiff(aiff::Writer::new(out, channels, sample_rate, depth, dither)?), #[cfg(feature = "flac-encode")] EncodeFormat::Flac => Writer::Flac(flac::Writer::new(out, channels, sample_rate, depth, dither, mask)?), + #[cfg(any(feature = "aac-encode", feature = "alac-encode", feature = "mp3-encode", feature = "ac3-encode", feature = "eac3-encode"))] + EncodeFormat::Aac | EncodeFormat::Alac | EncodeFormat::Mp3 | EncodeFormat::Ac3 | EncodeFormat::Eac3 => { + Writer::Coded(Box::new(coded::Writer::new(out, opts, sample_rate, channels)?)) + } #[allow(unreachable_patterns)] f => return Err(AudioError::Unsupported(format!("writing {f:?}"))), }; - Ok(FileEncoder { writer, channels }) + Ok(FileEncoder { writer, format: opts.format, channels }) } /// Fails, without writing anything, when `frames` more frames would not fit the format (an - /// AIFF holds 4 GiB, a FLAC 2^36 - 1 frames). + /// AIFF holds 4 GiB, a FLAC 2^36 - 1 frames). The coded formats have no limit a file reaches. pub fn check_room(&self, frames: u64) -> Result<()> { match &self.writer { #[cfg(feature = "pcm-encode")] - Writer::Wav(w) => w.check_room(frames), + Writer::Wav(w) => w.check_room(frames).map(drop), #[cfg(feature = "pcm-encode")] - Writer::Aiff(w) => w.check_room(frames), + Writer::Aiff(w) => w.check_room(frames).map(drop), #[cfg(feature = "flac-encode")] - Writer::Flac(w) => w.check_room(frames), + Writer::Flac(w) => w.check_room(frames).map(drop), + #[cfg(any(feature = "aac-encode", feature = "alac-encode", feature = "mp3-encode", feature = "ac3-encode", feature = "eac3-encode"))] + Writer::Coded(_) => { + let _ = frames; + Ok(()) + } } - .map(drop) } /// Appends the first `frames` frames of `block`, one slice per channel (`&[Vec]`, @@ -212,10 +265,13 @@ impl FileEncoder { Writer::Aiff(w) => w.write(block, frames), #[cfg(feature = "flac-encode")] Writer::Flac(w) => w.write(block, frames), + #[cfg(any(feature = "aac-encode", feature = "alac-encode", feature = "mp3-encode", feature = "ac3-encode", feature = "eac3-encode"))] + Writer::Coded(w) => w.write(block, frames), } } - /// Completes the headers and hands back `out`, positioned at the end of the file. + /// Encodes what is still buffered, completes the headers and hands back `out`, positioned at + /// the end of the file. pub fn finish(self) -> Result { match self.writer { #[cfg(feature = "pcm-encode")] @@ -224,6 +280,8 @@ impl FileEncoder { Writer::Aiff(w) => w.finish(), #[cfg(feature = "flac-encode")] Writer::Flac(w) => w.finish(), + #[cfg(any(feature = "aac-encode", feature = "alac-encode", feature = "mp3-encode", feature = "ac3-encode", feature = "eac3-encode"))] + Writer::Coded(w) => w.finish(), } } } @@ -252,7 +310,7 @@ pub fn wav_float_header(sample_rate: u32, channels: u16, frames: u64) -> Result< // With only one of `pcm-encode` and `flac-encode`, the other's formats are refused, not silently // written as something else. -#[cfg(all(test, not(all(feature = "pcm-encode", feature = "flac-encode"))))] +#[cfg(all(test, any(feature = "pcm-encode", feature = "flac-encode"), not(all(feature = "pcm-encode", feature = "flac-encode"))))] mod tests { use super::*; diff --git a/crates/audio/src/write/pcm.rs b/crates/audio/src/write/pcm.rs index 614d5a4a7..402b9bebc 100644 --- a/crates/audio/src/write/pcm.rs +++ b/crates/audio/src/write/pcm.rs @@ -1,6 +1,9 @@ //! PCM helpers shared by the WAV, AIFF and FLAC writers: quantization (with optional TPDF //! dither), interleaving and layout checks. +// The coded formats use the layout check, and of those only ALAC the quantizer. +#![cfg_attr(not(any(feature = "pcm-encode", feature = "flac-encode")), allow(dead_code))] + use crate::{AudioBuffer, AudioError, Result}; #[cfg(feature = "pcm-encode")] use {crate::BitDepth, std::io::Write}; diff --git a/crates/audio/tests/audio/decode_extensions.rs b/crates/audio/tests/audio/decode_extensions.rs index e8fe22d58..f6f021c65 100644 --- a/crates/audio/tests/audio/decode_extensions.rs +++ b/crates/audio/tests/audio/decode_extensions.rs @@ -62,11 +62,19 @@ fn every_decode_extension_probes_and_decodes() { fn every_encode_format_has_an_extension_it_is_written_and_read_under() { for &format in EncodeFormat::ALL { let ext = format.extension(); - assert_eq!(craft_audio::encode_format_for(ext), Some(format), "{ext}"); - assert!(craft_audio::ENCODE_EXTENSIONS.contains(&ext), "{ext}"); + // The extension names the format, or for `m4a`, which two formats share, AAC before ALAC. + // A format whose feature is off has no name. + match craft_audio::encode_format_for(ext) { + Some(named) => { + assert!(named == format || (named, format) == (EncodeFormat::Aac, EncodeFormat::Alac), "{ext}"); + assert!(craft_audio::ENCODE_EXTENSIONS.contains(&ext), "{ext}"); + } + None => assert!(!matches!(format, EncodeFormat::Wav | EncodeFormat::Aiff | EncodeFormat::Flac), "{ext}"), + } assert!(DECODE_EXTENSIONS.contains(&ext), "{ext}: what is written reads back"); assert!(format.mime_type().starts_with("audio/"), "{format:?}"); } - assert_eq!(EncodeFormat::ALL.iter().map(|f| f.extension()).collect::>(), ["wav", "aif", "flac"]); + let extensions: Vec<_> = EncodeFormat::ALL.iter().map(|f| f.extension()).collect(); + assert_eq!(extensions, ["wav", "aif", "flac", "m4a", "m4a", "mp3", "ac3", "eac3"]); assert_eq!(EncodeFormat::Aiff.mime_type(), "audio/aiff"); } diff --git a/crates/audio/tests/audio/encode_format.rs b/crates/audio/tests/audio/encode_format.rs index 30b992685..7713f37a5 100644 --- a/crates/audio/tests/audio/encode_format.rs +++ b/crates/audio/tests/audio/encode_format.rs @@ -14,7 +14,7 @@ fn only_formats_the_encoder_writes_are_named() { for name in craft_audio::ENCODE_EXTENSIONS { assert!(encode_format_for(name).is_some(), "{name}"); } - for other in ["mp3", "ogg", "m4a", "xyz", ""] { + for other in ["ogg", "opus", "aac", "mp4", "xyz", ""] { assert_eq!(encode_format_for(other), None, "{other}"); } } diff --git a/crates/audio/tests/codecs/file_formats.rs b/crates/audio/tests/codecs/file_formats.rs new file mode 100644 index 000000000..9affab350 --- /dev/null +++ b/crates/audio/tests/codecs/file_formats.rs @@ -0,0 +1,420 @@ +//! The coded formats of `encode` and `FileEncoder` (AAC and ALAC in M4A; MP3, AC-3 and E-AC-3 +//! streams), read back with this crate's decoder and, where ffmpeg is installed, with ffmpeg. + +use std::io::{Cursor, Seek, SeekFrom, Write}; +use std::process::Command; + +use craft_audio::{ + AudioBuffer, AudioError, BitDepth, ChannelLayout, CodecId, Container, ENCODE_EXTENSIONS, EncodeFormat, EncodeOptions, FileEncoder, RateControl, + decode, encode, encode_format_for, +}; + +const CODED: [EncodeFormat; 5] = [EncodeFormat::Aac, EncodeFormat::Alac, EncodeFormat::Mp3, EncodeFormat::Ac3, EncodeFormat::Eac3]; + +/// `channels` channels of `frames` frames, each channel a tone of its own frequency, on the +/// 16-bit grid (so a lossless 16-bit format returns it exactly). +fn tones(sample_rate: u32, channels: usize, frames: usize) -> AudioBuffer { + let channel = |c: usize| { + let step = (60.0 + 17.0 * c as f32) * std::f32::consts::TAU / sample_rate as f32; + (0..frames).map(|i| ((i as f32 * step).sin() * 0.4 * 32768.0).round() / 32768.0).collect() + }; + AudioBuffer { sample_rate, channels: (0..channels).map(channel).collect() } +} + +/// Signal-to-noise ratio in dB of `got` against `want`, over the frames both have. +fn snr(want: &[f32], got: &[f32]) -> f64 { + let (signal, noise) = + want.iter().zip(got).fold((0f64, 0f64), |(s, n), (&w, &g)| (s + f64::from(w).powi(2), n + (f64::from(w) - f64::from(g)).powi(2))); + 10.0 * (signal / noise.max(1e-30)).log10() +} + +fn is_unsupported(r: Result) -> bool { + matches!(r, Err(AudioError::Unsupported(_))) +} + +/// An AAC file decodes to the frames that were written, in place: the edit list skips the +/// encoder's priming and cuts the padding of the last packet. +#[test] +fn aac_decodes_to_the_frames_written() { + for frames in [1, 1000, 1024, 1025, 5000, 48_017] { + let buf = tones(48_000, 2, frames); + let file = encode(&buf, &EncodeOptions::new(EncodeFormat::Aac)).unwrap(); + let (info, out) = decode(&file, Some("m4a")).unwrap(); + assert_eq!((info.container, info.codec, info.sample_rate, info.damaged), (Container::Mp4, CodecId::Aac, 48_000, 0)); + assert_eq!((info.frames, out.frames(), info.layout), (frames as u64, frames, ChannelLayout::STEREO), "{frames} frames"); + if frames >= 5000 { + for (want, got) in buf.channels.iter().zip(&out.channels) { + assert!(snr(want, got) > 30.0, "{frames} frames: {} dB", snr(want, got)); + } + } + } +} + +/// The M4A track's durations add up to the priming and the audio, and its one edit skips the +/// priming and lasts as long as the audio, in a movie timescale that is the sample rate. +#[test] +fn aac_timing_is_in_the_sample_table_and_the_edit_list() { + use craft_audio::craft_media::isobmff; + let file = encode(&tones(44_100, 1, 3000), &EncodeOptions::new(EncodeFormat::Aac)).unwrap(); + let mp4 = isobmff::open(file.as_slice()).unwrap(); + let track = &mp4.tracks[0]; + assert_eq!((mp4.timescale, track.timescale), (44_100, 44_100)); + assert_eq!(track.samples.iter().map(|s| u64::from(s.duration)).sum::(), 1024 + 3000); + assert_eq!(track.edits.len(), 1); + assert_eq!((track.edits[0].media_time, track.edits[0].segment_duration), (1024, 3000)); +} + +/// ALAC returns the quantized samples exactly, for every channel count, with each channel where +/// its speaker is. +#[test] +fn alac_is_lossless_in_every_layout() { + for channels in 1..=8u8 { + let layout = ChannelLayout::from_mask(craft_audio::alac::channel_mask(channels)); + let buf = tones(44_100, usize::from(channels), 10_000); + let opts = EncodeOptions::new(EncodeFormat::Alac).with_bit_depth(BitDepth::Int16).with_layout(layout); + let file = encode(&buf, &opts).unwrap(); + let (info, out) = decode(&file, Some("m4a")).unwrap(); + assert_eq!((info.container, info.codec, info.frames, info.layout), (Container::Mp4, CodecId::Alac, 10_000, layout), "{channels} channels"); + assert_eq!(out, buf, "{channels} channels"); + } + // 24 bits, and a length that is no whole number of packets. + let buf = tones(96_000, 2, 4096 * 2 + 1); + let (_, out) = decode(&encode(&buf, &EncodeOptions::new(EncodeFormat::Alac)).unwrap(), Some("m4a")).unwrap(); + assert_eq!(out, buf); +} + +/// Channels go to the encoder by speaker. ALAC's 6.1 has the back centre last and AAC's has it +/// before the surround pair; 5.1 with side surrounds is the format's one 5.1. +#[test] +fn channels_reach_their_speakers() { + // WAV 6.1 with a back pair (L R C LFE Lb Rb Cb), the usual 7-channel layout, into ALAC: the same. + let buf = tones(48_000, 7, 8000); + let (info, out) = decode(&encode(&buf, &EncodeOptions::new(EncodeFormat::Alac).with_bit_depth(BitDepth::Int16)).unwrap(), Some("m4a")).unwrap(); + assert_eq!(info.layout, ChannelLayout::from_mask(0x13F)); + assert_eq!(out, buf); + // 5.1 with side surrounds decodes from ALAC as 5.1 with back surrounds, channel for channel. + let buf = tones(48_000, 6, 8000); + let opts = EncodeOptions::new(EncodeFormat::Alac).with_bit_depth(BitDepth::Int16).with_layout(ChannelLayout::SURROUND_5_1_SIDE); + assert_eq!(decode(&encode(&buf, &opts).unwrap(), Some("m4a")).unwrap().1, buf); + + // AAC: the decoded channel each input channel comes back as. 5.1 decodes in WAV order; the + // 6.1 and 7.1 streams have no speaker assignment and decode in AAC order (C L R Ls Rs Cs LFE + // and C Lc Rc L R Ls Rs LFE). + let wide = ChannelLayout::from_mask(0xFF); + let cases: [(usize, Option, &[usize]); 3] = + [(6, None, &[0, 1, 2, 3, 4, 5]), (7, None, &[2, 0, 1, 4, 5, 6, 3]), (8, Some(wide), &[2, 6, 7, 0, 1, 4, 5, 3])]; + for (channels, layout, decoded_from) in cases { + let buf = tones(48_000, channels, 48_000); + let mut opts = EncodeOptions::new(EncodeFormat::Aac); + opts.layout = layout; + let (info, out) = decode(&encode(&buf, &opts).unwrap(), Some("m4a")).unwrap(); + assert_eq!((usize::from(info.channels), out.frames()), (channels, 48_000)); + for (decoded, &input) in decoded_from.iter().enumerate() { + let db = snr(&buf.channels[input], &out.channels[decoded]); + assert!(db > 20.0, "{channels} channels: decoded {decoded} is not input {input} ({db} dB)"); + } + } +} + +/// MP3, AC-3 and E-AC-3 are raw streams: the audio comes back behind the codec's delay. +#[test] +fn raw_streams_decode_behind_the_codec_delay() { + let buf = tones(48_000, 2, 48_000); + for (format, codec, container, delay, floor) in [ + (EncodeFormat::Mp3, CodecId::Mp3, Container::MpegAudio, craft_audio::mp3::DELAY as usize, 25.0), + (EncodeFormat::Ac3, CodecId::Ac3, Container::Ac3, 256, 15.0), + (EncodeFormat::Eac3, CodecId::Eac3, Container::Ac3, 256, 15.0), + ] { + let file = encode(&buf, &EncodeOptions::new(format)).unwrap(); + let (info, out) = decode(&file, Some(format.extension())).unwrap(); + assert_eq!((info.codec, info.container, info.sample_rate, info.layout, info.damaged), (codec, container, 48_000, ChannelLayout::STEREO, 0)); + assert_eq!((format.codec(), format.container()), (codec, container)); + assert!(out.frames() >= 48_000 + delay, "{format:?}: {} frames", out.frames()); + for (want, got) in buf.channels.iter().zip(&out.channels) { + let db = snr(want, &got[delay..]); + assert!(db > floor, "{format:?}: {db} dB"); + } + } + // 5.1 with back surrounds is AC-3's 3/2 mode with an LFE, channel for channel. + let buf = tones(48_000, 6, 48_000); + let (info, out) = decode(&encode(&buf, &EncodeOptions::new(EncodeFormat::Ac3)).unwrap(), Some("ac3")).unwrap(); + assert_eq!(info.layout, ChannelLayout::SURROUND_5_1_SIDE); + for (c, (want, got)) in buf.channels.iter().zip(&out.channels).enumerate() { + // The encoder low-pass filters the LFE, which shifts its phase: it is compared by level. + if c == 3 { + let rms = |x: &[f32]| (x.iter().map(|&s| f64::from(s).powi(2)).sum::() / x.len() as f64).sqrt(); + let level = rms(&got[4800..]) / rms(want); + assert!((0.5..1.5).contains(&level), "LFE at {level} of its level"); + } else { + assert!(snr(want, &got[256..]) > 12.0, "channel {c}: {} dB", snr(want, &got[256..])); + } + } + // 7.1 is an E-AC-3 programme. + let buf = tones(48_000, 8, 4800); + assert!(is_unsupported(encode(&buf, &EncodeOptions::new(EncodeFormat::Ac3)))); + // (Read back by ffmpeg in `ffmpeg_reads_the_files`: this crate's file reader plays the 5.1 + // independent substream of a raw 7.1 stream.) + assert!(!encode(&buf, &EncodeOptions::new(EncodeFormat::Eac3)).unwrap().is_empty()); +} + +/// Blocks of any sizes give the bytes `encode` gives. +#[test] +fn streaming_writes_the_bytes_of_encode() { + let buf = tones(44_100, 2, 30_000); + for format in CODED { + let opts = EncodeOptions::new(format); + let whole = encode(&buf, &opts).unwrap(); + let mut enc = FileEncoder::new(Cursor::new(Vec::new()), &opts, 44_100, 2).unwrap(); + assert!(format!("{enc:?}").contains(&format!("{format:?}"))); + let mut at = 0; + for n in [1, 4095, 4097, 0, 9000, 12_807] { + let block: Vec<&[f32]> = buf.channels.iter().map(|c| &c[at..]).collect(); + enc.check_room(n as u64).unwrap(); + enc.write(&block, n).unwrap(); + at += n; + } + assert_eq!(at, buf.frames()); + assert!(enc.finish().unwrap().into_inner() == whole, "{format:?}"); + } +} + +/// A file starts at the sink's position. +#[test] +fn a_file_starts_at_the_sinks_position() { + let buf = tones(48_000, 1, 6000); + for format in CODED { + let opts = EncodeOptions::new(format); + let mut sink = Cursor::new(b"junk".to_vec()); + sink.seek(SeekFrom::End(0)).unwrap(); + let mut enc = FileEncoder::new(sink, &opts, 48_000, 1).unwrap(); + enc.write(&buf.channels, 6000).unwrap(); + let mut sink = enc.finish().unwrap(); + let end = sink.stream_position().unwrap(); + let bytes = sink.into_inner(); + assert_eq!(end, bytes.len() as u64, "{format:?}"); + assert!(bytes[4..] == encode(&buf, &opts).unwrap(), "{format:?}"); + } +} + +/// A file with no audio is still a file of its format. +#[test] +fn no_audio_gives_an_empty_file() { + let buf = AudioBuffer::new(48_000, 2, 0); + for format in CODED { + let file = encode(&buf, &EncodeOptions::new(format)).unwrap(); + if format.container() == Container::Mp4 { + let mp4 = craft_audio::craft_media::isobmff::open(file.as_slice()).unwrap(); + assert_eq!((mp4.tracks.len(), mp4.tracks[0].samples.len(), mp4.tracks[0].edits.len()), (1, 0, 0), "{format:?}"); + } else { + assert!(file.is_empty(), "{format:?}"); + } + } +} + +/// The bit rate asked for is the one written, moved to the nearest the format has. +#[test] +fn the_bit_rate_is_followed() { + let buf = tones(48_000, 2, 48_000); + let size = |opts: &EncodeOptions| encode(&buf, opts).unwrap().len(); + // MP3 at 48 kHz: 24 bytes per frame and kbit/s, 43 frames for a second and the delay. + assert_eq!(size(&EncodeOptions::new(EncodeFormat::Mp3)), 43 * 192 * 3); + assert_eq!(size(&EncodeOptions::new(EncodeFormat::Mp3).with_bitrate(130_000)), 43 * 128 * 3); + assert_eq!(size(&EncodeOptions::new(EncodeFormat::Mp3).with_bitrate(1)), 43 * 32 * 3); + assert_eq!(size(&EncodeOptions::new(EncodeFormat::Mp3).with_bitrate(u32::MAX)), 43 * 320 * 3); + // AC-3: 32 packets of 1536 frames, 4 bytes per packet and kbit/s. + assert_eq!(size(&EncodeOptions::new(EncodeFormat::Ac3)), 32 * 192 * 4); + assert_eq!(size(&EncodeOptions::new(EncodeFormat::Ac3).with_bitrate(100_000)), 32 * 96 * 4); + assert_eq!(size(&EncodeOptions::new(EncodeFormat::Eac3).with_bitrate(100_000)), 32 * 100 * 4); + // AAC: a second of audio at about the rate asked for, around the 128 kbit/s default. + let (low, default, high) = ( + size(&EncodeOptions::new(EncodeFormat::Aac).with_bitrate(64_000)), + size(&EncodeOptions::new(EncodeFormat::Aac)), + size(&EncodeOptions::new(EncodeFormat::Aac).with_bitrate(256_000)), + ); + assert!((7000..10_000).contains(&low) && (15_000..18_500).contains(&default) && (30_000..35_000).contains(&high), "{low} {default} {high}"); + // A rate no stream can carry is moved into range, not refused. + encode(&buf, &EncodeOptions::new(EncodeFormat::Aac).with_bitrate(1)).unwrap(); + encode(&buf, &EncodeOptions::new(EncodeFormat::Aac).with_bitrate(u32::MAX)).unwrap(); + // Quality is AAC's; ALAC has no rate to control. + let (small, large) = + (size(&EncodeOptions::new(EncodeFormat::Aac).with_quality(0.0)), size(&EncodeOptions::new(EncodeFormat::Aac).with_quality(1.0))); + assert!(small < large, "{small} {large}"); + assert!(matches!(encode(&buf, &EncodeOptions::new(EncodeFormat::Aac).with_quality(f32::NAN)), Err(AudioError::Encode(_)))); + for format in [EncodeFormat::Mp3, EncodeFormat::Ac3, EncodeFormat::Eac3] { + assert!(is_unsupported(encode(&buf, &EncodeOptions::new(format).with_quality(0.5))), "{format:?}"); + } + let alac = EncodeOptions::new(EncodeFormat::Alac); + assert_eq!(size(&alac), size(&alac.clone().with_bitrate(64_000))); + assert_eq!(alac.rate_control, None); + assert_eq!(alac.with_quality(0.5).rate_control, Some(RateControl::Quality(0.5))); +} + +/// What a format cannot hold is refused before anything is written. +#[test] +fn what_a_format_cannot_hold_is_refused() { + let refused = |format, sample_rate, channels: u16, layout: Option| { + let mut opts = EncodeOptions::new(format); + opts.layout = layout; + let mut sink = Cursor::new(Vec::new()); + let r = FileEncoder::new(&mut sink, &opts, sample_rate, channels).map(drop); + assert!(r.is_ok() || sink.into_inner().is_empty(), "{format:?}: bytes written for a refused file"); + assert_eq!(r.is_err(), encode(&AudioBuffer::new(sample_rate, channels, 100), &opts).is_err()); + r + }; + // Quad has no centre, which AAC's and ALAC's four channels have. + assert!(is_unsupported(refused(EncodeFormat::Aac, 48_000, 4, None))); + assert!(is_unsupported(refused(EncodeFormat::Alac, 48_000, 4, None))); + refused(EncodeFormat::Aac, 48_000, 4, Some(ChannelLayout::from_mask(0x107))).unwrap(); + // WAV 7.1 (backs and sides) is not the 7.1 of AAC and ALAC (a front pair left and right of centre). + assert!(is_unsupported(refused(EncodeFormat::Aac, 48_000, 8, None))); + assert!(is_unsupported(refused(EncodeFormat::Alac, 48_000, 8, Some(ChannelLayout::SURROUND_7_1)))); + assert!(is_unsupported(refused(EncodeFormat::Aac, 48_000, 2, Some(ChannelLayout::unordered(2))))); + for format in CODED { + assert!(is_unsupported(refused(format, 48_000, 9, None)), "{format:?}"); + assert!(matches!(refused(format, 48_000, 2, Some(ChannelLayout::MONO)), Err(AudioError::Encode(_))), "{format:?}"); + assert!(matches!(refused(format, 0, 2, None), Err(AudioError::Encode(_))), "{format:?}"); + assert!(matches!(refused(format, 48_000, 0, None), Err(AudioError::Encode(_))), "{format:?}"); + } + assert!(is_unsupported(refused(EncodeFormat::Mp3, 48_000, 3, None))); + assert!(is_unsupported(refused(EncodeFormat::Ac3, 48_000, 7, None))); + // Sample rates the codec has not. + for format in [EncodeFormat::Aac, EncodeFormat::Mp3, EncodeFormat::Ac3, EncodeFormat::Eac3] { + assert!(matches!(refused(format, 44_000, 2, None), Err(AudioError::Encode(_))), "{format:?}"); + } + refused(EncodeFormat::Alac, 44_000, 2, None).unwrap(); + let float = EncodeOptions::new(EncodeFormat::Alac).with_bit_depth(BitDepth::Float32); + assert!(is_unsupported(encode(&AudioBuffer::new(48_000, 2, 100), &float))); +} + +/// Samples no encoder should see: NaN is silence, and values past full scale do not fail a +/// write (AC-3, whose encoder refuses them, gets them clamped). +#[test] +fn non_finite_and_loud_samples_are_written() { + let mut buf = tones(48_000, 2, 6000); + buf.channels[0][100] = f32::NAN; + buf.channels[0][200] = f32::INFINITY; + buf.channels[1][300] = -7.5; + for format in CODED { + let file = encode(&buf, &EncodeOptions::new(format)).unwrap(); + let (_, out) = decode(&file, Some(format.extension())).unwrap(); + assert!(out.channels.iter().flatten().all(|s| s.is_finite()), "{format:?}"); + } +} + +/// A sink that fails once `room` bytes are written. +struct Full { + inner: Cursor>, + room: usize, +} + +impl Write for Full { + fn write(&mut self, data: &[u8]) -> std::io::Result { + if self.inner.get_ref().len() + data.len() > self.room { + return Err(std::io::Error::other("disk full")); + } + self.inner.write(data) + } + fn flush(&mut self) -> std::io::Result<()> { + Ok(()) + } +} + +impl Seek for Full { + fn seek(&mut self, pos: SeekFrom) -> std::io::Result { + self.inner.seek(pos) + } +} + +/// After a failed write the encoder is unusable: later writes and `finish` fail too. +#[test] +fn a_failed_write_ends_the_encoder() { + let buf = tones(48_000, 2, 48_000); + for format in CODED { + let mut enc = FileEncoder::new(Full { inner: Cursor::new(Vec::new()), room: 2000 }, &EncodeOptions::new(format), 48_000, 2).unwrap(); + assert!(matches!(enc.write(&buf.channels, 48_000), Err(AudioError::Io(_))), "{format:?}"); + assert!(matches!(enc.write(&buf.channels, 1), Err(AudioError::Encode(_))), "{format:?}"); + assert!(matches!(enc.finish(), Err(AudioError::Encode(_))), "{format:?}"); + } +} + +#[test] +fn the_formats_are_named() { + assert_eq!(encode_format_for("m4a"), Some(EncodeFormat::Aac)); + assert_eq!(encode_format_for(".ALAC"), Some(EncodeFormat::Alac)); + assert_eq!(encode_format_for("mp3"), Some(EncodeFormat::Mp3)); + assert_eq!(encode_format_for("ac3"), Some(EncodeFormat::Ac3)); + assert_eq!(encode_format_for("eac3"), Some(EncodeFormat::Eac3)); + assert_eq!(encode_format_for("ec3"), Some(EncodeFormat::Eac3)); + for &format in EncodeFormat::ALL { + assert!(ENCODE_EXTENSIONS.contains(&format.extension()), "{format:?}"); + let named = encode_format_for(format.extension()).unwrap(); + assert_eq!((named.extension(), named.mime_type()), (format.extension(), format.mime_type())); + assert_eq!(format.is_lossy(), !matches!(format.codec(), CodecId::Pcm | CodecId::Flac | CodecId::Alac)); + } + for name in ENCODE_EXTENSIONS { + assert!(encode_format_for(name).is_some(), "{name}"); + } + assert_eq!(ENCODE_EXTENSIONS.len(), 12); + for format in CODED { + assert!(EncodeFormat::ALL.contains(&format)); + } +} + +/// ffmpeg's decode of `file` as interleaved `f32`, split into `channels` channels. +fn ffmpeg_decode(ff: &std::path::Path, file: &[u8], name: &str, channels: usize) -> Vec> { + let path = crate::testkit::fixtures_dir("file_formats").join(name); + std::fs::write(&path, file).unwrap(); + let out = Command::new(ff).args(["-v", "error", "-i"]).arg(&path).args(["-f", "f32le", "-"]).output().unwrap(); + assert!(out.status.success() && out.stderr.is_empty(), "{name}: {}", String::from_utf8_lossy(&out.stderr)); + let mut planar = vec![Vec::new(); channels]; + for (i, s) in out.stdout.as_chunks::<4>().0.iter().enumerate() { + planar[i % channels].push(f32::from_le_bytes(*s)); + } + planar +} + +/// ffmpeg reads every format: the M4A files at the length written (it applies the edit list), +/// ALAC exactly, the raw streams behind their delay. +#[test] +fn ffmpeg_reads_the_files() { + let ff = require_ffmpeg!(); + for (channels, layout) in [(1, None), (2, None), (6, None), (8, Some(ChannelLayout::from_mask(0xFF)))] { + let buf = tones(48_000, channels, 20_000); + let mut opts = EncodeOptions::new(EncodeFormat::Aac); + opts.layout = layout; + let out = ffmpeg_decode(&ff, &encode(&buf, &opts).unwrap(), &format!("aac_{channels}.m4a"), channels); + assert_eq!(out[0].len(), 20_000, "AAC, {channels} channels"); + if channels <= 6 { + // ffmpeg also returns 5.1 in WAV order. + for (c, (want, got)) in buf.channels.iter().zip(&out).enumerate() { + assert!(snr(want, got) > 20.0, "AAC, {channels} channels, channel {c}: {} dB", snr(want, got)); + } + } + let opts = opts.with_format(EncodeFormat::Alac).with_bit_depth(BitDepth::Int16); + let opts = if channels == 6 { opts.with_layout(ChannelLayout::SURROUND_5_1) } else { opts }; + let out = ffmpeg_decode(&ff, &encode(&buf, &opts).unwrap(), &format!("alac_{channels}.m4a"), channels); + assert!(out == buf.channels, "ALAC, {channels} channels"); + } + let buf = tones(44_100, 2, 20_000); + for (format, delay, floor) in + [(EncodeFormat::Mp3, craft_audio::mp3::DELAY as usize, 25.0), (EncodeFormat::Ac3, 256, 15.0), (EncodeFormat::Eac3, 256, 15.0)] + { + let name = format!("stream.{}", format.extension()); + let out = ffmpeg_decode(&ff, &encode(&buf, &EncodeOptions::new(format)).unwrap(), &name, 2); + for (want, got) in buf.channels.iter().zip(&out) { + assert!( + got.len() >= 20_000 + delay && snr(want, &got[delay..]) > floor, + "{format:?}: {} frames, {} dB", + got.len(), + snr(want, &got[delay..]) + ); + } + } + // E-AC-3 7.1: the front channels, which the 5.1 downmix leaves as they are. + let buf = tones(48_000, 8, 20_000); + let out = ffmpeg_decode(&ff, &encode(&buf, &EncodeOptions::new(EncodeFormat::Eac3)).unwrap(), "stream_7_1.eac3", 8); + assert!(out[7].len() >= 20_256); + for c in 0..3 { + assert!(snr(&buf.channels[c], &out[c][256..]) > 12.0, "E-AC-3 7.1, channel {c}: {} dB", snr(&buf.channels[c], &out[c][256..])); + } +} diff --git a/crates/audio/tests/codecs/main.rs b/crates/audio/tests/codecs/main.rs index 279246dc6..c1c9e2131 100644 --- a/crates/audio/tests/codecs/main.rs +++ b/crates/audio/tests/codecs/main.rs @@ -12,6 +12,7 @@ mod ac3_encoder_oracle; mod ac3_oracle; mod alac; mod concealment; +mod file_formats; mod mp3_decoder_oracle; mod mp3_encoder_oracle; mod mpa_oracle; From 3dadce4d7c8840386acd9e1a455c56034b4daecd Mon Sep 17 00:00:00 2001 From: alehel Date: Sat, 14 Nov 2026 02:12:54 +0100 Subject: [PATCH 15/51] craft-audio: review round 1 for the coded formats - craft-media: TrackConfig::roll_distance writes a `roll` sample group (sgpd + sbgp) over every sample. The AAC M4A track sets -1: Apple's decoders took 2112 frames of priming and dropped the start of the audio without it (afinfo now reports the frames written and 1024 priming). - EncodeFormat::is_built and feature: which formats this build writes. - Clippy: the writer enum's variants differ in size with flac-encode and a codec feature but no pcm-encode. - Tests for the finished sample entry (AAC bit rate, ALAC cookie), ALAC dither and afinfo's reading of the priming. - README: ffmpeg's reading of 8-channel AAC, and files with no audio. Refs #1230 --- crates/audio/README.md | 9 +++- crates/audio/src/lib.rs | 29 ++++++++++++- crates/audio/src/write/coded.rs | 3 ++ crates/audio/src/write/mod.rs | 13 ++---- crates/audio/tests/codecs/file_formats.rs | 51 ++++++++++++++++++++++- crates/media/src/isobmff/mux.rs | 51 ++++++++++++++++++++++- 6 files changed, 141 insertions(+), 15 deletions(-) diff --git a/crates/audio/README.md b/crates/audio/README.md index 79f0efd46..5be0a3b23 100644 --- a/crates/audio/README.md +++ b/crates/audio/README.md @@ -240,8 +240,8 @@ let alac = encode(&buf, &EncodeOptions::new(EncodeFormat::Alac).with_bit_depth(B `EncodeOptions::default()` is 24-bit WAV. `with_bwf` adds a BWF `bext` chunk and `with_force_rf64` writes RF64 below 4 GiB; both apply to WAV only. `encode_format_for("aiff")` maps an extension to an `EncodeFormat`, and `ENCODE_EXTENSIONS` lists the extensions the enabled -features can write. `EncodeFormat::ALL` lists the formats; `extension()` is the extension a new -file gets and `mime_type()` its media type. `write` refuses a block without one slice per channel, or with a slice +features can write. `EncodeFormat::ALL` lists the formats and `is_built()` says whether this build +writes one; `extension()` is the extension a new file gets and `mime_type()` its media type. `write` refuses a block without one slice per channel, or with a slice shorter than `frames`, and writes nothing. After a write fails for another reason, every later `write` and `finish` returns an error. @@ -462,6 +462,11 @@ match craft_audio::decode(&bytes, None) { metadata. Raw ADTS AAC is not a file format of `encode`; `aac::EncoderConfig::with_adts` gives the frames. - This crate's file reader plays a raw E-AC-3 7.1 stream as its 5.1 independent substream. +- `EncodeFormat::Aac` with 8 channels is AAC channel configuration 7 (C, Lc Rc, L R, Ls Rs, LFE), + which Apple's decoders read as written. ffmpeg assumes such a stream is a mislabelled 7.1 with + backs and sides and moves the channels accordingly, unless run with `-strict 1`. +- A file with no audio: MP3, AC-3 and E-AC-3 are then zero bytes, which nothing can probe, and an + empty AAC M4A (a track with no samples) is read by ffmpeg but not by this crate's decoder. - ALAC 32-bit streams: ffmpeg does not decode their uncompressed (escaped) stereo frames, which Apple's encoder and this one write for audio that does not compress; Apple's decoder and this one do. diff --git a/crates/audio/src/lib.rs b/crates/audio/src/lib.rs index f6be431dc..326426b2a 100644 --- a/crates/audio/src/lib.rs +++ b/crates/audio/src/lib.rs @@ -260,7 +260,7 @@ pub enum EncodeFormat { impl EncodeFormat { /// Every format, in the order menus list them. Whether [`encode`] writes one depends on its - /// feature. + /// feature ([`EncodeFormat::is_built`]). pub const ALL: &[EncodeFormat] = &[ EncodeFormat::Wav, EncodeFormat::Aiff, @@ -325,6 +325,33 @@ impl EncodeFormat { } } + /// The feature that builds this format's writer. + pub fn feature(self) -> &'static str { + match self { + EncodeFormat::Wav | EncodeFormat::Aiff => "pcm-encode", + EncodeFormat::Flac => "flac-encode", + EncodeFormat::Aac => "aac-encode", + EncodeFormat::Alac => "alac-encode", + EncodeFormat::Mp3 => "mp3-encode", + EncodeFormat::Ac3 => "ac3-encode", + EncodeFormat::Eac3 => "eac3-encode", + } + } + + /// Whether [`encode`] and [`FileEncoder`] write this format in this build (its + /// [`feature`](Self::feature) is on): what to filter [`EncodeFormat::ALL`] by for a menu. + pub fn is_built(self) -> bool { + match self { + EncodeFormat::Wav | EncodeFormat::Aiff => cfg!(feature = "pcm-encode"), + EncodeFormat::Flac => cfg!(feature = "flac-encode"), + EncodeFormat::Aac => cfg!(feature = "aac-encode"), + EncodeFormat::Alac => cfg!(feature = "alac-encode"), + EncodeFormat::Mp3 => cfg!(feature = "mp3-encode"), + EncodeFormat::Ac3 => cfg!(feature = "ac3-encode"), + EncodeFormat::Eac3 => cfg!(feature = "eac3-encode"), + } + } + /// Whether the format loses audio: AAC, MP3, AC-3 and E-AC-3. These take /// [`EncodeOptions::rate_control`] and ignore the bit depth and dither. pub fn is_lossy(self) -> bool { diff --git a/crates/audio/src/write/coded.rs b/crates/audio/src/write/coded.rs index 415d309fc..84507bb44 100644 --- a/crates/audio/src/write/coded.rs +++ b/crates/audio/src/write/coded.rs @@ -408,6 +408,9 @@ impl M4a { let mut config = craft_media::isobmff::TrackConfig::new(self.entry.clone(), self.sample_rate); if has_audio && self.priming > 0 { config.media_start = Some(i64::from(self.priming)); + // AAC's overlap: a packet decodes right only after the one before it. Apple's + // decoders take the priming from the edit only when the track says so. + config.roll_distance = Some(-1); } let track = self.mux.add_track(config).map_err(mux_error)?; self.track = Some(track); diff --git a/crates/audio/src/write/mod.rs b/crates/audio/src/write/mod.rs index c743965cb..d7dcbd5f2 100644 --- a/crates/audio/src/write/mod.rs +++ b/crates/audio/src/write/mod.rs @@ -57,16 +57,7 @@ pub fn encode(buf: &AudioBuffer, opts: &EncodeOptions) -> Result> { /// Refuses a format whose writer is not built, before anything else about the request is checked. fn check_built(format: EncodeFormat) -> Result<()> { - let (built, feature) = match format { - EncodeFormat::Wav | EncodeFormat::Aiff => (cfg!(feature = "pcm-encode"), "pcm-encode"), - EncodeFormat::Flac => (cfg!(feature = "flac-encode"), "flac-encode"), - EncodeFormat::Aac => (cfg!(feature = "aac-encode"), "aac-encode"), - EncodeFormat::Alac => (cfg!(feature = "alac-encode"), "alac-encode"), - EncodeFormat::Mp3 => (cfg!(feature = "mp3-encode"), "mp3-encode"), - EncodeFormat::Ac3 => (cfg!(feature = "ac3-encode"), "ac3-encode"), - EncodeFormat::Eac3 => (cfg!(feature = "eac3-encode"), "eac3-encode"), - }; - if built { Ok(()) } else { Err(AudioError::Unsupported(format!("writing {format:?} needs the `{feature}` feature"))) } + if format.is_built() { Ok(()) } else { Err(AudioError::Unsupported(format!("writing {format:?} needs the `{}` feature", format.feature()))) } } /// Every extension [`ENCODE_EXTENSIONS`] can list, and how many of them the features built give. @@ -182,6 +173,8 @@ impl std::fmt::Debug for FileEncoder { } } +// The writers differ in size with the features built; the coded one is boxed for its encoder. +#[allow(clippy::large_enum_variant)] enum Writer { #[cfg(feature = "pcm-encode")] Wav(wav::Writer), diff --git a/crates/audio/tests/codecs/file_formats.rs b/crates/audio/tests/codecs/file_formats.rs index 9affab350..49caea243 100644 --- a/crates/audio/tests/codecs/file_formats.rs +++ b/crates/audio/tests/codecs/file_formats.rs @@ -62,6 +62,41 @@ fn aac_timing_is_in_the_sample_table_and_the_edit_list() { assert_eq!(track.samples.iter().map(|s| u64::from(s.duration)).sum::(), 1024 + 3000); assert_eq!(track.edits.len(), 1); assert_eq!((track.edits[0].media_time, track.edits[0].segment_duration), (1024, 3000)); + // Every packet is in a `roll` group of distance -1, which Apple's decoders need to apply the edit. + let groups = &track.sample_groups; + assert_eq!((groups.len(), groups[0].grouping_type), (1, isobmff::FourCc(*b"roll"))); + assert_eq!((groups[0].runs.as_slice(), &groups[0].descriptions), ([(track.samples.len() as u32, 1)].as_slice(), &vec![vec![0xFF, 0xFF]])); +} + +/// The sample entry is completed when the file is: AAC's average bit rate, and the largest packet +/// and average bit rate in ALAC's cookie. +#[test] +fn the_sample_entry_describes_the_finished_stream() { + use craft_audio::craft_media::isobmff::{self, CodecConfig}; + let buf = tones(48_000, 2, 48_000); + let file = encode(&buf, &EncodeOptions::new(EncodeFormat::Aac).with_bitrate(96_000)).unwrap(); + let mp4 = isobmff::open(file.as_slice()).unwrap(); + let CodecConfig::Aac(aac) = &mp4.tracks[0].entries[0].codec else { panic!("not AAC") }; + assert!((90_000..100_000).contains(&aac.avg_bitrate), "{} bit/s", aac.avg_bitrate); + + let file = encode(&buf, &EncodeOptions::new(EncodeFormat::Alac).with_bit_depth(BitDepth::Int16)).unwrap(); + let mp4 = isobmff::open(file.as_slice()).unwrap(); + let CodecConfig::Alac { cookie } = &mp4.tracks[0].entries[0].codec else { panic!("not ALAC") }; + let config = craft_audio::alac::SpecificConfig::parse(cookie).unwrap(); + let largest = mp4.tracks[0].samples.iter().map(|s| s.size).max().unwrap(); + assert_eq!((config.max_frame_bytes, config.bit_depth, config.frame_length), (largest, 16, 4096)); + assert!(config.avg_bit_rate > 0); +} + +/// Dither reaches ALAC's quantizer: a level below one 16-bit step is silence without it. +#[test] +fn alac_dithers_when_asked() { + let buf = AudioBuffer { sample_rate: 48_000, channels: vec![vec![0.3 / 32768.0; 4096]] }; + let opts = EncodeOptions::new(EncodeFormat::Alac).with_bit_depth(BitDepth::Int16); + let (_, plain) = decode(&encode(&buf, &opts).unwrap(), Some("m4a")).unwrap(); + let (_, dithered) = decode(&encode(&buf, &opts.with_dither(true)).unwrap(), Some("m4a")).unwrap(); + assert!(plain.channels[0].iter().all(|&s| s == 0.0)); + assert!(dithered.channels[0].iter().any(|&s| s != 0.0)); } /// ALAC returns the quantized samples exactly, for every channel count, with each channel where @@ -356,7 +391,7 @@ fn the_formats_are_named() { } assert_eq!(ENCODE_EXTENSIONS.len(), 12); for format in CODED { - assert!(EncodeFormat::ALL.contains(&format)); + assert!(EncodeFormat::ALL.contains(&format) && format.is_built() && format.feature().ends_with("-encode")); } } @@ -418,3 +453,17 @@ fn ffmpeg_reads_the_files() { assert!(snr(&buf.channels[c], &out[c][256..]) > 12.0, "E-AC-3 7.1, channel {c}: {} dB", snr(&buf.channels[c], &out[c][256..])); } } + +/// Apple's decoder (macOS `afinfo`; skipped elsewhere) takes the priming and the length of an AAC +/// file from the edit list, which it does only for a track with a `roll` sample group. +#[test] +fn apple_reads_the_aac_priming_and_length() { + let Some(afinfo) = crate::testkit::oracle::find_tool("afinfo") else { return }; + for (frames, remainder) in [(20_000, 480), (1, 1023), (4096, 0)] { + let path = crate::testkit::fixtures_dir("file_formats").join(format!("apple_{frames}.m4a")); + std::fs::write(&path, encode(&tones(48_000, 2, frames), &EncodeOptions::new(EncodeFormat::Aac)).unwrap()).unwrap(); + let out = Command::new(&afinfo).arg(&path).output().unwrap(); + let text = String::from_utf8_lossy(&out.stdout); + assert!(text.contains(&format!("{frames} valid frames + 1024 priming + {remainder} remainder")), "{frames} frames: {text}"); + } +} diff --git a/crates/media/src/isobmff/mux.rs b/crates/media/src/isobmff/mux.rs index e38186e9f..730675db1 100644 --- a/crates/media/src/isobmff/mux.rs +++ b/crates/media/src/isobmff/mux.rs @@ -51,11 +51,17 @@ pub struct TrackConfig { pub media_start: Option, /// `hdlr` name; a sensible default is used when `None`. pub handler_name: Option, + /// Audio pre-roll: puts every sample in a `roll` sample group (`sgpd` + `sbgp`, ISO/IEC + /// 14496-12 §10.1) with this roll distance, the number of samples a decoder must decode before + /// (negative) a sample for its output to be correct; -1 for AAC. Apple's decoders take an AAC + /// track's priming from the edit list only when the track has this group. Written by + /// [`Mp4Writer`]; [`FragmentedWriter`] ignores it. + pub roll_distance: Option, } impl TrackConfig { pub fn new(entry: SampleEntry, timescale: u32) -> Self { - TrackConfig { entry, timescale, language: "und".into(), edits: Vec::new(), media_start: None, handler_name: None } + TrackConfig { entry, timescale, language: "und".into(), edits: Vec::new(), media_start: None, handler_name: None, roll_distance: None } } } @@ -543,6 +549,23 @@ fn write_stbl(b: &mut BoxBuf, t: &WTrack, qt: bool, shift: u64, force_co64: bool } } b.end(m); + if let Some(distance) = t.cfg.roll_distance + && sample_count > 0 + { + // One description, which every sample maps to. + let m = b.start_full(b"sgpd", 1, 0); + b.bytes(b"roll"); + b.u32(2); + b.u32(1); + b.i16(distance); + b.end(m); + let m = b.start_full(b"sbgp", 0, 0); + b.bytes(b"roll"); + b.u32(1); + b.u32(sample_count); + b.u32(1); + b.end(m); + } b.end(stbl); Ok(()) } @@ -1341,4 +1364,30 @@ mod tests { } assert_eq!(t.sync_sample_before(5), 3); } + + /// `roll_distance` puts every sample in one `roll` group; without it, or without samples, + /// the track has no sample group. + #[test] + fn roll_distance_is_a_sample_group_over_every_sample() { + let file = |roll: Option, samples: u32| { + let mut w = Mp4Writer::new(Cursor::new(Vec::new()), WriterOptions::new(Brand::Mp4)).unwrap(); + let mut cfg = TrackConfig::new(SampleEntry::aac(vec![0x11, 0x90], 2, 48_000), 48_000); + cfg.roll_distance = roll; + let t = w.add_track(cfg).unwrap(); + for _ in 0..samples { + w.write_sample(t, WriteSample { data: &[0; 8], duration: 1024, composition_offset: 0, is_sync: true }).unwrap(); + } + w.finish().unwrap().into_inner() + }; + let out = file(Some(-1), 5); + let f = crate::isobmff::open(out.as_slice()).unwrap(); + let groups = &f.tracks[0].sample_groups; + assert_eq!(groups.len(), 1); + assert_eq!((groups[0].grouping_type, groups[0].runs.as_slice()), (crate::isobmff::FourCc(*b"roll"), [(5, 1)].as_slice())); + assert_eq!(groups[0].descriptions, [(-1i16).to_be_bytes().to_vec()]); + assert_eq!(f.tracks[0].samples.len(), 5); + for out in [file(None, 5), file(Some(-1), 0)] { + assert!(crate::isobmff::open(out.as_slice()).unwrap().tracks[0].sample_groups.is_empty()); + } + } } From 63712c33e655e46cf3b8a6794e8a27c5f53a67c6 Mon Sep 17 00:00:00 2001 From: alehel Date: Sat, 14 Nov 2026 02:34:43 +0100 Subject: [PATCH 16/51] craft-audio: review round 2 for the coded formats - craft-media: Mp4Writer counts chunk offsets from the first byte of the file, not from position 0 of the writer, so a file begun mid-writer is valid. This replaces the seek adapter the M4A writer wrapped its sink in. - Tests pin the bytes of the roll sample group and each format's feature. - Docs: ALAC's length comes from the sample durations, not an edit list; which readers take an empty AAC file; speaker names as the errors print them; craft-media's README lists roll_distance. - Error messages for a layout a format has not no longer suggest setting a layout that was set. Refs #1230 --- Cargo.toml | 2 +- crates/audio/README.md | 12 ++-- crates/audio/src/write/coded.rs | 71 +++++------------------ crates/audio/src/write/mod.rs | 15 +++-- crates/audio/tests/codecs/file_formats.rs | 4 +- crates/media/README.md | 4 ++ crates/media/src/isobmff/mux.rs | 53 +++++++++++++++-- 7 files changed, 86 insertions(+), 75 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index fc251abe0..c996c1d43 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -85,10 +85,10 @@ craft-keymap = { path = "crates/keymap" } craft-assuan = { path = "crates/assuan" } craft-kra = { path = "crates/kra" } craft-audio = { path = "crates/audio" } -# No default features: craft-audio turns on the craft-media modules each of its features needs. craft-latex = { path = "crates/latex" } craft-markdown = { path = "crates/markdown" } craft-math = { path = "crates/math" } +# No default features: craft-audio turns on the craft-media modules each of its features needs. craft-media = { path = "crates/media", default-features = false } craft-materialx = { path = "crates/materialx" } craft-media-testkit = { path = "crates/media-testkit" } diff --git a/crates/audio/README.md b/crates/audio/README.md index 5be0a3b23..3acb44de7 100644 --- a/crates/audio/README.md +++ b/crates/audio/README.md @@ -241,8 +241,9 @@ let alac = encode(&buf, &EncodeOptions::new(EncodeFormat::Alac).with_bit_depth(B `with_force_rf64` writes RF64 below 4 GiB; both apply to WAV only. `encode_format_for("aiff")` maps an extension to an `EncodeFormat`, and `ENCODE_EXTENSIONS` lists the extensions the enabled features can write. `EncodeFormat::ALL` lists the formats and `is_built()` says whether this build -writes one; `extension()` is the extension a new file gets and `mime_type()` its media type. `write` refuses a block without one slice per channel, or with a slice -shorter than `frames`, and writes nothing. After a write fails for another reason, every later +writes one; `extension()` is the extension a new file gets and `mime_type()` its media type. +`write` refuses a block without one slice per channel, or with a slice shorter than `frames`, and +writes nothing. After a write fails for another reason, every later `write` and `finish` returns an error. | `EncodeFormat` | File | Audio | Options used | @@ -265,7 +266,7 @@ count when unset) names the speakers, and the channels are reordered into the co Each coded format has a fixed set of layouts, and audio with other speakers is `Unsupported` rather than written to the wrong ones: -- AAC: C; L R; L R C; L R C Cs; L R C Ls Rs; 5.1; 6.1; and for 8 channels L R C LFE Ls Rs Lc Rc +- AAC: C; L R; L R C; L R C Cb; L R C Ls Rs; 5.1; 6.1; and for 8 channels L R C LFE Lb Rb Lc Rc (a front pair left and right of centre, mask `0xFF`). ALAC: the same, with 6.1's back centre last. WAV 7.1 (backs and sides) is not that 7.1, and quad (the usual 4-channel layout) has no centre: both need another format. @@ -465,8 +466,9 @@ match craft_audio::decode(&bytes, None) { - `EncodeFormat::Aac` with 8 channels is AAC channel configuration 7 (C, Lc Rc, L R, Ls Rs, LFE), which Apple's decoders read as written. ffmpeg assumes such a stream is a mislabelled 7.1 with backs and sides and moves the channels accordingly, unless run with `-strict 1`. -- A file with no audio: MP3, AC-3 and E-AC-3 are then zero bytes, which nothing can probe, and an - empty AAC M4A (a track with no samples) is read by ffmpeg but not by this crate's decoder. +- A file with no audio: MP3, AC-3 and E-AC-3 are then zero bytes, which nothing can probe. An + empty AAC M4A (a track with no samples) is read by ffmpeg; this crate's native reader passes it + on, so `decode-native` alone refuses it and symphonia reads only some as zero frames. - ALAC 32-bit streams: ffmpeg does not decode their uncompressed (escaped) stereo frames, which Apple's encoder and this one write for audio that does not compress; Apple's decoder and this one do. diff --git a/crates/audio/src/write/coded.rs b/crates/audio/src/write/coded.rs index 84507bb44..8999171a2 100644 --- a/crates/audio/src/write/coded.rs +++ b/crates/audio/src/write/coded.rs @@ -7,13 +7,13 @@ // other halves of the shared code are unused. #![cfg_attr( not(all(feature = "aac-encode", feature = "alac-encode", feature = "mp3-encode", feature = "ac3-encode", feature = "eac3-encode")), - allow(dead_code, unused_imports, unused_variables, unused_mut) + allow(dead_code, unused_imports, unused_variables) )] use super::failed_write_error; use super::pcm::validate_layout; use crate::{AudioBuffer, AudioError, ChannelLayout, EncodeFormat, EncodeOptions, RateControl, Result, Speaker}; -use std::io::{Cursor, Seek, SeekFrom, Write}; +use std::io::{Cursor, Seek, Write}; /// Frames handed to the encoder at a time, so its buffers and the packets waiting to be written /// stay small however long a block is. Also the frames of an ALAC packet. @@ -70,14 +70,15 @@ fn fixed_map(name: &str, mask: u32, order: Option<&[usize]>, layout: &ChannelLay return Err(AudioError::Unsupported(format!("{name} cannot hold {} channels", layout.channels()))); } channel_map(mask, order, layout).ok_or_else(|| { - let given = match layout.mask() { - Some(m) => labels(m), - None => "no speaker assignment".into(), - }; - AudioError::Unsupported(format!("{name} holds {} channels as {}, not {given}; set `EncodeOptions::layout`", layout.channels(), labels(mask))) + AudioError::Unsupported(format!("{name} holds {} channels as {}; the audio is {}", layout.channels(), labels(mask), given(layout))) }) } +/// The speakers of the caller's layout, for an error message. +fn given(layout: &ChannelLayout) -> String { + layout.mask().map_or_else(|| "without speaker assignment".into(), labels) +} + /// The WAV mask of the speakers an AAC stream of `channels` channels has, as this crate's encoder /// writes it and its decoder reports it: channel configurations 1–6, the 6.1 program config /// element for 7, and configuration 7 (7.1 with a front pair left and right of centre) for 8. @@ -153,11 +154,7 @@ fn ac3_config( Some((config, map)) }); let Some((mut config, map)) = found else { - let given = match layout.mask() { - Some(m) => labels(m), - None => "no speaker assignment".into(), - }; - return Err(AudioError::Unsupported(format!("{name} has no layout of {} channels as {given}", layout.channels()))); + return Err(AudioError::Unsupported(format!("{name} has no coding mode for {} channels that are {}", layout.channels(), given(layout)))); }; let full = config.mode.channels() as u32; let want = constant_kbps(name, rate, DEFAULT_KBPS_PER_CHANNEL * full)?; @@ -329,44 +326,6 @@ fn mux_error(e: craft_media::isobmff::Error) -> AudioError { } } -/// A sink seen from where the file starts: position 0 is the sink's position when the file was -/// begun. The MP4 muxer writes chunk offsets as stream positions, and they count from the first -/// byte of the file, which need not be the first byte of the sink. -#[cfg(any(feature = "aac-encode", feature = "alac-encode"))] -struct FromStart { - out: W, - start: u64, -} - -#[cfg(any(feature = "aac-encode", feature = "alac-encode"))] -impl Write for FromStart { - fn write(&mut self, data: &[u8]) -> std::io::Result { - self.out.write(data) - } - - fn write_all(&mut self, data: &[u8]) -> std::io::Result<()> { - self.out.write_all(data) - } - - fn flush(&mut self) -> std::io::Result<()> { - self.out.flush() - } -} - -#[cfg(any(feature = "aac-encode", feature = "alac-encode"))] -impl Seek for FromStart { - fn seek(&mut self, to: SeekFrom) -> std::io::Result { - let to = match to { - SeekFrom::Start(at) => SeekFrom::Start( - self.start.checked_add(at).ok_or_else(|| std::io::Error::new(std::io::ErrorKind::InvalidInput, "seek past the end of the sink"))?, - ), - relative => relative, - }; - let at = self.out.seek(to)?; - at.checked_sub(self.start).ok_or_else(|| std::io::Error::new(std::io::ErrorKind::InvalidInput, "seek to before the start of the file")) - } -} - /// An M4A file being written: one audio track whose samples are the packets. /// /// The last packet is held back until the length is known: its duration is cut to the audio's @@ -375,7 +334,7 @@ impl Seek for FromStart { /// keeps that edit exact. #[cfg(any(feature = "aac-encode", feature = "alac-encode"))] struct M4a { - mux: craft_media::isobmff::Mp4Writer>, + mux: craft_media::isobmff::Mp4Writer, /// The track, added with the first packet: a file with no audio gets a track without an edit. track: Option, entry: craft_media::isobmff::SampleEntry, @@ -390,10 +349,8 @@ struct M4a { #[cfg(any(feature = "aac-encode", feature = "alac-encode"))] impl M4a { - fn new(mut out: W, codec: &Codec, sample_rate: u32, channels: u32) -> Result { + fn new(out: W, codec: &Codec, sample_rate: u32, channels: u32) -> Result { use craft_media::isobmff::{Brand, Mp4Writer, WriterOptions}; - let start = out.stream_position()?; - let out = FromStart { out, start }; let entry = codec.sample_entry(sample_rate, channels, 0, 0).ok_or_else(|| AudioError::Unsupported("M4A holds AAC and ALAC".into()))?; let mut options = WriterOptions::new(Brand::Mp4); options.movie_timescale = sample_rate; @@ -444,7 +401,7 @@ impl M4a { if let Some(entry) = codec.sample_entry(self.sample_rate, self.channels, self.bytes, self.frames) { self.mux.set_sample_entry(track, entry).map_err(mux_error)?; } - Ok(self.mux.finish().map_err(mux_error)?.out) + self.mux.finish().map_err(mux_error) } } @@ -495,7 +452,7 @@ impl Writer { }; let enc = crate::alac::Encoder::new(crate::alac::EncoderConfig::new(sample_rate, count, bits).with_frame_length(CHUNK as u32))?; let quantizers = super::pcm::Quantizer::per_channel(u32::from(bits), opts.dither, channels); - (Codec::Alac { enc: Box::new(enc), quantizers, pending: vec![Vec::with_capacity(CHUNK); channels] }, map) + (Codec::Alac { enc: Box::new(enc), quantizers, pending: vec![Vec::new(); channels] }, map) } #[cfg(feature = "mp3-encode")] EncodeFormat::Mp3 => { @@ -514,7 +471,7 @@ impl Writer { EncodeFormat::Ac3 | EncodeFormat::Eac3 => { let codec = if opts.format == EncodeFormat::Ac3 { crate::ac3::encoder::Codec::Ac3 } else { crate::ac3::encoder::Codec::Eac3 }; let (config, map) = ac3_config(codec, sample_rate, &layout, opts.rate_control)?; - (Codec::Ac3 { enc: Box::new(crate::ac3::encoder::Encoder::new(config)?), planes: vec![Vec::with_capacity(CHUNK); channels] }, map) + (Codec::Ac3 { enc: Box::new(crate::ac3::encoder::Encoder::new(config)?), planes: vec![Vec::new(); channels] }, map) } #[allow(unreachable_patterns)] f => return Err(AudioError::Unsupported(format!("writing {f:?}"))), diff --git a/crates/audio/src/write/mod.rs b/crates/audio/src/write/mod.rs index d7dcbd5f2..2d8e8d9db 100644 --- a/crates/audio/src/write/mod.rs +++ b/crates/audio/src/write/mod.rs @@ -22,9 +22,10 @@ use std::io::{Seek, Write}; /// Encode `buf` as the file `opts.format` names. Integer depths clamp samples to [-1, 1]; float /// keeps values above full scale. `opts.layout`, when set, must have `buf`'s channel count. /// -/// The lossy formats take `opts.rate_control`. AAC and ALAC are written as M4A, whose edit list -/// makes the file decode to exactly `buf`'s frames. MP3, AC-3 and E-AC-3 are raw streams, which -/// have no place for that: they decode with the codec's delay in front and padded to whole frames. +/// The lossy formats take `opts.rate_control`. AAC and ALAC are written as M4A, which records the +/// encoder's priming and the exact length, so the file decodes to `buf`'s frames. MP3, AC-3 and +/// E-AC-3 are raw streams, which have no place for that: they decode with the codec's delay in +/// front and padded to whole frames. /// /// ``` /// # #[cfg(feature = "pcm-encode")] { @@ -142,9 +143,10 @@ fn failed_write_error() -> AudioError { } /// Writes a file of any [`EncodeFormat`] block by block, producing the same bytes [`encode`] -/// would for the whole buffer: a file of any length never has to fit in memory. The file starts at the sink's position, and nothing may follow that -/// position (a new file, or one truncated there): the encoder cannot truncate a `Write + Seek`, -/// so the bytes of a longer file already there would stay after the new one. +/// would for the whole buffer: a file of any length never has to fit in memory. The file starts +/// at the sink's position, and nothing may follow that position (a new file, or one truncated +/// there): the encoder cannot truncate a `Write + Seek`, so the bytes of a longer file already +/// there would stay after the new one. /// /// ``` /// # #[cfg(feature = "flac-encode")] { @@ -316,6 +318,7 @@ mod tests { let enc = FileEncoder::new(std::io::Cursor::new(Vec::new()), &opts, 48_000, 1); assert!(matches!(enc, Err(AudioError::Unsupported(_)))); assert_eq!(encode_format_for(name), None); + assert!(!format.is_built() && EncodeFormat::ALL.iter().any(|f| f.is_built())); // Also with a layout it could not use. let opts = opts.with_layout(ChannelLayout::STEREO); assert!(matches!(encode(&buf, &opts), Err(AudioError::Unsupported(_)))); diff --git a/crates/audio/tests/codecs/file_formats.rs b/crates/audio/tests/codecs/file_formats.rs index 49caea243..83679cbd5 100644 --- a/crates/audio/tests/codecs/file_formats.rs +++ b/crates/audio/tests/codecs/file_formats.rs @@ -391,8 +391,10 @@ fn the_formats_are_named() { } assert_eq!(ENCODE_EXTENSIONS.len(), 12); for format in CODED { - assert!(EncodeFormat::ALL.contains(&format) && format.is_built() && format.feature().ends_with("-encode")); + assert!(EncodeFormat::ALL.contains(&format) && format.is_built()); } + let features: Vec<_> = EncodeFormat::ALL.iter().map(|f| f.feature()).collect(); + assert_eq!(features, ["pcm-encode", "pcm-encode", "flac-encode", "alac-encode", "aac-encode", "mp3-encode", "ac3-encode", "eac3-encode"]); } /// ffmpeg's decode of `file` as interleaved `f32`, split into `channels` channels. diff --git a/crates/media/README.md b/crates/media/README.md index 8eca6ecb5..b7ad5be7a 100644 --- a/crates/media/README.md +++ b/crates/media/README.md @@ -243,6 +243,10 @@ let bytes = w.finish_faststart()?.into_inner(); // or finish() for moov-at-end `ipcm`/`fpcm` + `pcmC` in MP4. A PCM `write_sample` call can hold any whole number of frames, and the track timescale must equal the sample rate. - Edit lists: set `TrackConfig::edits` explicitly, or use `media_start` to get a single edit. +- Audio pre-roll: `TrackConfig::roll_distance` puts every sample in a `roll` sample group (`sgpd` + + `sbgp`). Set -1 for AAC with `media_start` at the priming: Apple's decoders apply that edit only + when the track has the group. +- A file starts at the writer's position: chunk offsets count from there. - Timecode: `add_timecode_track(video, TimecodeConfig, start_frame)` adds a `tmcd` track (with `gmhd`) and a `tref/tmcd` link from the video track. - `WriterOptions::metadata` writes `©xxx` text atoms to `udta`. diff --git a/crates/media/src/isobmff/mux.rs b/crates/media/src/isobmff/mux.rs index 730675db1..b37fbf724 100644 --- a/crates/media/src/isobmff/mux.rs +++ b/crates/media/src/isobmff/mux.rs @@ -621,6 +621,9 @@ pub struct Mp4Writer { w: W, opts: WriterOptions, tracks: Vec, + /// The writer's position when the file was begun: chunk offsets count from here, the first + /// byte of the file, wherever in the writer that is. + start: u64, /// Offset of the placeholder box (8 bytes) preceding the mdat header. pad_pos: u64, mdat_pos: u64, @@ -631,7 +634,8 @@ pub struct Mp4Writer { } impl Mp4Writer { - /// Start a file: writes `ftyp`, a placeholder box and the `mdat` header. + /// Start a file at the writer's current position: writes `ftyp`, a placeholder box and the + /// `mdat` header. pub fn new(mut w: W, opts: WriterOptions) -> Result { let start = w.stream_position()?; let mut b = BoxBuf::new(); @@ -642,7 +646,7 @@ impl Mp4Writer { b.leaf(b"mdat", &[]); w.write_all(&b.buf)?; let pos = start + b.len() as u64; - Ok(Mp4Writer { w, opts, tracks: Vec::new(), pad_pos, mdat_pos, pos, last_track: None, chapters: Vec::new() }) + Ok(Mp4Writer { w, opts, tracks: Vec::new(), start, pad_pos, mdat_pos, pos, last_track: None, chapters: Vec::new() }) } /// Add a track; returns its index (track ids are index + 1). @@ -731,7 +735,7 @@ impl Mp4Writer { return Err(too_many_samples()); } self.w.write_all(s.data)?; - let offset = self.pos; + let offset = self.pos - self.start; self.pos += s.data.len() as u64; let contiguous = self.last_track == Some(track); self.last_track = Some(track); @@ -772,7 +776,7 @@ impl Mp4Writer { }; let d = rescale(vd, vts, tts).max(tc_dur as u64).min(u32::MAX as u64) as u32; self.w.write_all(&start.to_be_bytes())?; - let off = self.pos; + let off = self.pos - self.start; self.pos += 4; self.last_track = None; let t = &mut self.tracks[i].t; @@ -830,7 +834,7 @@ impl Mp4Writer { } let id = self.tracks.len() as u32 + 1; let mut t = Tables::new(); - let off = self.pos; + let off = self.pos - self.start; for (i, c) in self.chapters.iter().enumerate() { let end = self.chapters.get(i + 1).map_or(duration, |n| n.start); let d = u32::try_from(end.saturating_sub(c.start)).map_err(|_| Error::Mux("chapter longer than 2^32 movie ticks".into()))?; @@ -1389,5 +1393,44 @@ mod tests { for out in [file(None, 5), file(Some(-1), 0)] { assert!(crate::isobmff::open(out.as_slice()).unwrap().tracks[0].sample_groups.is_empty()); } + // The boxes as ISO/IEC 14496-12 §8.9 has them (and ffmpeg writes them): `sgpd` version 1 + // with a default description length of 2, one description; `sbgp` version 0, one run. + let sgpd = [&26u32.to_be_bytes()[..], b"sgpd", &[1, 0, 0, 0], b"roll", &[0, 0, 0, 2, 0, 0, 0, 1, 0xFF, 0xFF]].concat(); + let sbgp = [&28u32.to_be_bytes()[..], b"sbgp", &[0, 0, 0, 0], b"roll", &[0, 0, 0, 1, 0, 0, 0, 5, 0, 0, 0, 1]].concat(); + let both = [sgpd, sbgp].concat(); + assert!(out.windows(both.len()).any(|w| w == both)); + } + + /// A file begun in the middle of a writer is a file from there: its chunk offsets count from + /// its own first byte, with `moov` at the end or in front, a timecode track and chapters. + #[test] + fn a_file_begun_mid_writer_has_offsets_from_its_start() { + let file = |prefix: usize, faststart: bool| { + let mut sink = Cursor::new(vec![0xAA; prefix]); + sink.set_position(prefix as u64); + let mut opts = WriterOptions::new(Brand::Mov); + opts.chapters = vec![Chapter { start: 0, title: "one".into() }]; + let mut w = Mp4Writer::new(sink, opts).unwrap(); + let v = w.add_track(TrackConfig::new(avc_entry(), 1000)).unwrap(); + let tc = TimecodeConfig { timescale: 1000, frame_duration: 40, frames_per_second: 25, ..Default::default() }; + w.add_timecode_track(v, tc, 7).unwrap(); + for i in 0..4u8 { + w.write_sample(v, WriteSample { data: &[i + 1; 10], duration: 40, composition_offset: 0, is_sync: true }).unwrap(); + } + let out = if faststart { w.finish_faststart() } else { w.finish() }.unwrap(); + assert_eq!(out.position(), out.get_ref().len() as u64); + out.into_inner() + }; + for faststart in [false, true] { + let (plain, offset) = (file(0, faststart), file(100, faststart)); + assert!(offset[..100].iter().all(|&b| b == 0xAA)); + assert!(offset[100..] == plain, "faststart {faststart}"); + let f = crate::isobmff::open(plain.as_slice()).unwrap(); + assert_eq!(f.tracks.len(), 3); + for i in 0..4 { + assert_eq!(f.read_sample(plain.as_slice(), 0, i).unwrap(), vec![i as u8 + 1; 10]); + } + assert_eq!(f.read_sample(plain.as_slice(), 1, 0).unwrap(), 7u32.to_be_bytes()); + } } } From 098eb2e43a0e8c1fb14b7b668bf5fe88da8641c5 Mon Sep 17 00:00:00 2001 From: alehel Date: Sat, 14 Nov 2026 03:02:37 +0100 Subject: [PATCH 17/51] craft-audio: review round 3 for the coded formats - craft-media: Mp4Writer::new refuses a writer positioned where the header would end past u64::MAX instead of overflowing the sum (correction to round 2, which let the M4A writer reach that addition). - AAC is written at 6 kbit/s or a quarter of the sample rate per channel at least: the encoder accepts lower rates but codes only silence at them, so with_bitrate(128) gave a silent file. - README: what to do with a layout a coded format refuses, and the names encode_format_for takes for M4A. Refs #1230 --- crates/audio/README.md | 12 ++++++++++-- crates/audio/src/lib.rs | 3 ++- crates/audio/src/write/coded.rs | 9 +++++++++ crates/audio/tests/codecs/file_formats.rs | 10 +++++++++- crates/media/src/isobmff/mux.rs | 20 +++++++++++++++++--- 5 files changed, 47 insertions(+), 7 deletions(-) diff --git a/crates/audio/README.md b/crates/audio/README.md index 3acb44de7..29cc4816f 100644 --- a/crates/audio/README.md +++ b/crates/audio/README.md @@ -239,7 +239,7 @@ let alac = encode(&buf, &EncodeOptions::new(EncodeFormat::Alac).with_bit_depth(B `EncodeOptions::default()` is 24-bit WAV. `with_bwf` adds a BWF `bext` chunk and `with_force_rf64` writes RF64 below 4 GiB; both apply to WAV only. `encode_format_for("aiff")` -maps an extension to an `EncodeFormat`, and `ENCODE_EXTENSIONS` lists the extensions the enabled +maps an extension to an `EncodeFormat` (`"m4a"` to AAC; `"alac"` names ALAC), and `ENCODE_EXTENSIONS` lists the extensions the enabled features can write. `EncodeFormat::ALL` lists the formats and `is_built()` says whether this build writes one; `extension()` is the extension a new file gets and `mime_type()` its media type. `write` refuses a block without one slice per channel, or with a slice shorter than `frames`, and @@ -256,7 +256,8 @@ writes nothing. After a write fails for another reason, every later `with_bitrate(bits_per_second)` sets a constant bit rate for all channels together. A rate the stream cannot carry is moved to the nearest one it can: MP3 and AC-3 use the highest rate of their -tables not above it, AAC and E-AC-3 keep it inside their range. `with_quality(0.0..=1.0)` is AAC's +tables not above it, AAC and E-AC-3 keep it inside their range (AAC from 6 kbit/s or a quarter of +the sample rate per channel, whichever is more: below that the encoder has bits for silence only). `with_quality(0.0..=1.0)` is AAC's constant quality (VBR); the other lossy formats return `Unsupported` for it. Without either, AAC is written at 64 kbit/s per channel, MP3 at 96 kbit/s per channel, and AC-3 and E-AC-3 at 96 kbit/s per full-bandwidth channel (the LFE not counted). @@ -275,6 +276,13 @@ rather than written to the wrong ones: - A surround pair is a surround pair: side and back surrounds are interchangeable where the format has one pair. +The layout `decode` reports (`AudioInfo::layout`) can be passed to `with_layout` as it is. When a +coded format refuses it (2.1 or quad into AAC, a single channel tagged as left, channels with no +speaker assignment), the choices are another format, or audio rearranged into one of the layouts +above with that layout set; leaving `layout` unset declares the usual layout for the count. This +crate's decoder returns 7- and 8-channel AAC without a speaker assignment, in AAC order, so such a +file needs that step before it is written again. + An M4A's edit list skips the AAC encoder's priming (1024 frames) and ends at the last frame written, so the file decodes to the length that went in. An MP3, AC-3 or E-AC-3 stream has no place for that (see [Limits](#limits)). For a container of your own, use the codec modules below. diff --git a/crates/audio/src/lib.rs b/crates/audio/src/lib.rs index 326426b2a..52d630a84 100644 --- a/crates/audio/src/lib.rs +++ b/crates/audio/src/lib.rs @@ -366,7 +366,8 @@ impl EncodeFormat { pub enum RateControl { /// A constant bit rate in bits per second, for all channels together. A format with a fixed /// set of rates (MP3, AC-3) uses the highest one not above it; a rate outside what the - /// stream can carry is moved to the nearest one inside. + /// stream can carry is moved to the nearest one inside. AAC is written at 6 kbit/s or a + /// quarter of the sample rate per channel at least, where its encoder starts to code audio. Bitrate(u32), /// A constant quality from 0.0 (smallest) to 1.0 (best), at whatever bit rate each frame /// needs. AAC only; values outside the range are clamped, and NaN is an error. diff --git a/crates/audio/src/write/coded.rs b/crates/audio/src/write/coded.rs index 8999171a2..c173b502e 100644 --- a/crates/audio/src/write/coded.rs +++ b/crates/audio/src/write/coded.rs @@ -104,12 +104,21 @@ fn aac_order(channels: usize) -> Option<&'static [usize]> { if channels == 8 { Some(&[2, 6, 7, 0, 1, 4, 5, 3]) } else { crate::aac::aac_order(channels) } } +/// The lowest AAC bit rate the writer uses, per channel: 6 kbit/s, and a quarter of the sample +/// rate (256 bits a frame). The encoder accepts less, but then has too few bits for anything but +/// silence, and a file of silence is no answer to a low bit rate (or to kbit/s given as bit/s). +#[cfg(feature = "aac-encode")] +fn aac_floor_per_channel(sample_rate: u32) -> u32 { + (sample_rate / 4).max(6000) +} + /// The AAC rate control for `rate`: a bit rate is kept within what the stream can carry, a /// quality of 0–1 spans the encoder's VBR range. #[cfg(feature = "aac-encode")] fn aac_mode(rate: Option, sample_rate: u32, channels: usize) -> crate::aac::BitrateMode { use crate::aac::BitrateMode; let (lo, hi) = crate::aac::cbr_range(sample_rate, channels); + let lo = lo.max(aac_floor_per_channel(sample_rate).saturating_mul(channels as u32)).min(hi.max(lo)); // An empty range (a rate or channel count the encoder refuses anyway) leaves the rate alone. let fit = |bps: u32| if lo <= hi { bps.clamp(lo, hi) } else { bps }; match rate { diff --git a/crates/audio/tests/codecs/file_formats.rs b/crates/audio/tests/codecs/file_formats.rs index 83679cbd5..46ed901ff 100644 --- a/crates/audio/tests/codecs/file_formats.rs +++ b/crates/audio/tests/codecs/file_formats.rs @@ -268,8 +268,16 @@ fn the_bit_rate_is_followed() { ); assert!((7000..10_000).contains(&low) && (15_000..18_500).contains(&default) && (30_000..35_000).contains(&high), "{low} {default} {high}"); // A rate no stream can carry is moved into range, not refused. - encode(&buf, &EncodeOptions::new(EncodeFormat::Aac).with_bitrate(1)).unwrap(); encode(&buf, &EncodeOptions::new(EncodeFormat::Aac).with_bitrate(u32::MAX)).unwrap(); + // The lowest rate still codes the audio: the encoder accepts rates that leave only silence + // (128 for 128 kbit/s is one), and the writer does not go that low. + for (sample_rate, channels) in [(8000, 1), (16_000, 2), (44_100, 2), (48_000, 6), (96_000, 2)] { + let buf = tones(sample_rate, channels, sample_rate as usize); + let (_, out) = decode(&encode(&buf, &EncodeOptions::new(EncodeFormat::Aac).with_bitrate(128)).unwrap(), Some("m4a")).unwrap(); + let rms = |x: &[f32]| (x.iter().map(|&s| f64::from(s).powi(2)).sum::() / x.len() as f64).sqrt(); + let level = rms(&out.channels[0]) / rms(&buf.channels[0]); + assert!(level > 0.5, "{sample_rate} Hz, {channels} channels: {level} of the level"); + } // Quality is AAC's; ALAC has no rate to control. let (small, large) = (size(&EncodeOptions::new(EncodeFormat::Aac).with_quality(0.0)), size(&EncodeOptions::new(EncodeFormat::Aac).with_quality(1.0))); diff --git a/crates/media/src/isobmff/mux.rs b/crates/media/src/isobmff/mux.rs index b37fbf724..159a9b5ba 100644 --- a/crates/media/src/isobmff/mux.rs +++ b/crates/media/src/isobmff/mux.rs @@ -640,12 +640,15 @@ impl Mp4Writer { let start = w.stream_position()?; let mut b = BoxBuf::new(); write_ftyp(&mut b, opts.brand); - let pad_pos = start + b.len() as u64; + let pad = b.len() as u64; b.leaf(if opts.brand == Brand::Mov { b"wide" } else { b"free" }, &[]); - let mdat_pos = start + b.len() as u64; + let mdat = b.len() as u64; b.leaf(b"mdat", &[]); + // A writer positioned at the very end of what a position can count has no room for the + // header; the positions below are sums that would overflow. + let pos = start.checked_add(b.len() as u64).ok_or_else(|| Error::Mux("the writer's position leaves no room for a file".into()))?; + let (pad_pos, mdat_pos) = (start + pad, start + mdat); w.write_all(&b.buf)?; - let pos = start + b.len() as u64; Ok(Mp4Writer { w, opts, tracks: Vec::new(), start, pad_pos, mdat_pos, pos, last_track: None, chapters: Vec::new() }) } @@ -1401,6 +1404,17 @@ mod tests { assert!(out.windows(both.len()).any(|w| w == both)); } + /// A writer positioned where the header's end would pass `u64::MAX` is refused, not overflowed. + #[test] + fn a_writer_at_the_end_of_the_position_range_is_refused() { + for back in [0, 1, 10, 27] { + let mut bytes = [0u8; 8]; + let mut sink = Cursor::new(&mut bytes[..]); + sink.set_position(u64::MAX - back); + assert!(matches!(Mp4Writer::new(sink, WriterOptions::new(Brand::Mp4)), Err(Error::Mux(_))), "{back} before the end"); + } + } + /// A file begun in the middle of a writer is a file from there: its chunk offsets count from /// its own first byte, with `moov` at the end or in front, a timecode track and chapters. #[test] From e5fa1ac2f9dc27055b000f3a1124c360adad0871 Mon Sep 17 00:00:00 2001 From: alehel Date: Sat, 14 Nov 2026 03:16:32 +0100 Subject: [PATCH 18/51] craft-audio: review round 4 for the coded formats - craft-media: Mp4Writer counts written bytes with a checked sum, so a writer that takes bytes past the last position gets an error, not an overflow (correction to round 3, which checked only the header). - Docs: the AAC bit-rate floor keeps a margin above where the encoder codes silence, about half of it. Refs #1230 --- crates/audio/README.md | 3 ++- crates/audio/src/lib.rs | 5 +++-- crates/audio/src/write/coded.rs | 4 ++-- crates/media/src/isobmff/mux.rs | 37 ++++++++++++++++++++++++++++++--- 4 files changed, 41 insertions(+), 8 deletions(-) diff --git a/crates/audio/README.md b/crates/audio/README.md index 29cc4816f..aae1703ec 100644 --- a/crates/audio/README.md +++ b/crates/audio/README.md @@ -257,7 +257,8 @@ writes nothing. After a write fails for another reason, every later `with_bitrate(bits_per_second)` sets a constant bit rate for all channels together. A rate the stream cannot carry is moved to the nearest one it can: MP3 and AC-3 use the highest rate of their tables not above it, AAC and E-AC-3 keep it inside their range (AAC from 6 kbit/s or a quarter of -the sample rate per channel, whichever is more: below that the encoder has bits for silence only). `with_quality(0.0..=1.0)` is AAC's +the sample rate per channel, whichever is more: from about half of that down the encoder codes +silence). `with_quality(0.0..=1.0)` is AAC's constant quality (VBR); the other lossy formats return `Unsupported` for it. Without either, AAC is written at 64 kbit/s per channel, MP3 at 96 kbit/s per channel, and AC-3 and E-AC-3 at 96 kbit/s per full-bandwidth channel (the LFE not counted). diff --git a/crates/audio/src/lib.rs b/crates/audio/src/lib.rs index 52d630a84..6418f3a99 100644 --- a/crates/audio/src/lib.rs +++ b/crates/audio/src/lib.rs @@ -19,7 +19,7 @@ //! gives [`wav_float_header`]), FLAC (feature `flac-encode`), AAC-LC and ALAC in M4A //! (`aac-encode`, `alac-encode`) and MP3, AC-3 and E-AC-3 streams (`mp3-encode`, `ac3-encode`, //! `eac3-encode`), whole-buffer or incremental into any `Write + Seek`. Feature -//! `lossless-encode` turns on WAV, AIFF and FLAC; feature `encode` turns on every format. +//! `lossless-encode` turns on WAV, AIFF and FLAC; feature `encode` turns on every format and encoder. //! - [`wav_pcm`], [`aiff_pcm`] (feature `decode-native`) and [`pcm_wav_file`], [`pcm_wav_header`], //! [`pcm_aiff_file`], [`pcm_aiff_header`] (feature `pcm-encode`): the integer PCM of a WAV or AIFF //! file bit for bit, and minimal files around such PCM, for essence embedded in other containers. @@ -367,7 +367,8 @@ pub enum RateControl { /// A constant bit rate in bits per second, for all channels together. A format with a fixed /// set of rates (MP3, AC-3) uses the highest one not above it; a rate outside what the /// stream can carry is moved to the nearest one inside. AAC is written at 6 kbit/s or a - /// quarter of the sample rate per channel at least, where its encoder starts to code audio. + /// quarter of the sample rate per channel at least: from about half of that down its encoder + /// codes silence. Bitrate(u32), /// A constant quality from 0.0 (smallest) to 1.0 (best), at whatever bit rate each frame /// needs. AAC only; values outside the range are clamped, and NaN is an error. diff --git a/crates/audio/src/write/coded.rs b/crates/audio/src/write/coded.rs index c173b502e..ef33168a8 100644 --- a/crates/audio/src/write/coded.rs +++ b/crates/audio/src/write/coded.rs @@ -105,8 +105,8 @@ fn aac_order(channels: usize) -> Option<&'static [usize]> { } /// The lowest AAC bit rate the writer uses, per channel: 6 kbit/s, and a quarter of the sample -/// rate (256 bits a frame). The encoder accepts less, but then has too few bits for anything but -/// silence, and a file of silence is no answer to a low bit rate (or to kbit/s given as bit/s). +/// rate (256 bits a frame). The encoder accepts less, and from about half of this down codes +/// silence; a file of silence is no answer to a low bit rate (or to kbit/s given as bit/s). #[cfg(feature = "aac-encode")] fn aac_floor_per_channel(sample_rate: u32) -> u32 { (sample_rate / 4).max(6000) diff --git a/crates/media/src/isobmff/mux.rs b/crates/media/src/isobmff/mux.rs index 159a9b5ba..bcadfbaeb 100644 --- a/crates/media/src/isobmff/mux.rs +++ b/crates/media/src/isobmff/mux.rs @@ -615,6 +615,12 @@ fn validate_track(entry: &SampleEntry, timescale: u32) -> Result> { Ok(None) } +/// The position after `bytes` more. A writer that takes bytes past the last position a file can +/// have is an error here, not an overflow. +fn advance(pos: u64, bytes: usize) -> Result { + pos.checked_add(bytes as u64).ok_or_else(|| Error::Mux("the file would end past the last position".into())) +} + /// Progressive MP4/MOV writer: `ftyp`, then one `mdat` streamed to `W`, then `moov` at [`finish`](Self::finish) /// (or moved in front of `mdat` by [`finish_faststart`](Self::finish_faststart)). pub struct Mp4Writer { @@ -739,7 +745,7 @@ impl Mp4Writer { } self.w.write_all(s.data)?; let offset = self.pos - self.start; - self.pos += s.data.len() as u64; + self.pos = advance(self.pos, s.data.len())?; let contiguous = self.last_track == Some(track); self.last_track = Some(track); let tr = &mut self.tracks[track]; @@ -780,7 +786,7 @@ impl Mp4Writer { let d = rescale(vd, vts, tts).max(tc_dur as u64).min(u32::MAX as u64) as u32; self.w.write_all(&start.to_be_bytes())?; let off = self.pos - self.start; - self.pos += 4; + self.pos = advance(self.pos, 4)?; self.last_track = None; let t = &mut self.tracks[i].t; t.stts.push((1, d)); @@ -843,7 +849,7 @@ impl Mp4Writer { let d = u32::try_from(end.saturating_sub(c.start)).map_err(|_| Error::Mux("chapter longer than 2^32 movie ticks".into()))?; let data = text_sample(&c.title); self.w.write_all(&data)?; - self.pos += data.len() as u64; + self.pos = advance(self.pos, data.len())?; Tables::push_run(&mut t.stts, 1, d); Tables::push_run(&mut t.ctts, 1, 0); t.sizes.push(data.len() as u32); @@ -1415,6 +1421,31 @@ mod tests { } } + /// A writer that keeps taking bytes where positions end makes writing fail, not overflow. + #[test] + fn samples_past_the_last_position_are_refused() { + struct Endless(u64); + impl Write for Endless { + fn write(&mut self, data: &[u8]) -> std::io::Result { + self.0 = self.0.wrapping_add(data.len() as u64); + Ok(data.len()) + } + fn flush(&mut self) -> std::io::Result<()> { + Ok(()) + } + } + impl Seek for Endless { + fn seek(&mut self, _: SeekFrom) -> std::io::Result { + Ok(self.0) + } + } + let mut w = Mp4Writer::new(Endless(u64::MAX - 100), WriterOptions::new(Brand::Mp4)).unwrap(); + let v = w.add_track(TrackConfig::new(avc_entry(), 1000)).unwrap(); + let sample = WriteSample { data: &[0; 40], duration: 40, composition_offset: 0, is_sync: true }; + w.write_sample(v, sample).unwrap(); + assert!(matches!(w.write_sample(v, sample), Err(Error::Mux(_)))); + } + /// A file begun in the middle of a writer is a file from there: its chunk offsets count from /// its own first byte, with `moov` at the end or in front, a timecode track and chapters. #[test] From 316db970528678312418d6f0bb369d720c3c9838 Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Fri, 13 Nov 2026 19:52:40 -0800 Subject: [PATCH 19/51] craft-texture: keep bilinear samples of finite texels finite The four weighted texels are summed in f64 and a finite sum is clamped to the f32 range. Rounded weights can add up to slightly more than 1, which made a constant image of f32::MAX sample to infinity at some coordinates. Infinite texels still give an infinite or NaN sample. The crate docs and README now limit the OutOfMemory guarantee of the try_ forms to the pixel buffer, and name the Arc and the try_resize resampler as allocations that are not fallible. --- crates/texture/README.md | 11 +++++++---- crates/texture/src/lib.rs | 27 ++++++++++++++++++++------- 2 files changed, 27 insertions(+), 11 deletions(-) diff --git a/crates/texture/README.md b/crates/texture/README.md index 19e58de22..a41b42666 100644 --- a/crates/texture/README.md +++ b/crates/texture/README.md @@ -12,9 +12,11 @@ network I/O and has no `unsafe` code. A plane is never larger than `isize::MAX` bytes (2 GiB minus one byte on `wasm32`), even with raised limits: the `try_` forms return `ImageError::TooLarge` for a larger one, and `map`, `to_color` and `to_kind` clamp each side to `1..=MAX_SIDE` and map the top-left part instead. - `try_map`, `try_to_kind`, `try_resize` and `try_to_rgba8_display` reserve their memory first - and return `ImageError::OutOfMemory` when that fails. The forms without `try_` allocate like - `Vec`, which ends the process when memory runs out. + `try_map`, `try_to_kind`, `try_resize` and `try_to_rgba8_display` reserve their pixel buffer + first and return `ImageError::OutOfMemory` when that reservation fails. They still make small + allocations that are not fallible: the `Arc` around a new image's buffer, and the boxed + resampler of `try_resize`. The forms without `try_` allocate like `Vec`. A failed infallible + allocation ends the process. - **Sampling.** `sample` (bilinear) and `sample_nearest` take normalized `(u, v)` with `(0, 0)` at the upper-left corner and `v` increasing downward, as glTF 2.0 section 3.8.3 defines them (). `tile` picks repeat (glTF @@ -22,7 +24,8 @@ network I/O and has no `unsafe` code. and the bilinear weights follow the Vulkan specification, sections 20.4.1, 20.6.1 and 20.6.3 (). Repeat keeps its period at any finite coordinate. A NaN or infinite coordinate gives - `[0, 0, 0, 1]`. + `[0, 0, 0, 1]`. Bilinear sums are taken in `f64` and clamped to the `f32` range, so finite + texels give a finite sample. - **Other operations.** `get` reads one texel, `map`, `to_gray`, `to_color` and `to_kind` convert, `resize` box-averages whole-factor shrinks and samples bilinearly otherwise, and `to_rgba8_display` encodes 8-bit sRGB RGBA. `linear_to_srgb`, `srgb_to_linear` and `luminance` diff --git a/crates/texture/src/lib.rs b/crates/texture/src/lib.rs index 02ad65ae8..78966f6ff 100644 --- a/crates/texture/src/lib.rs +++ b/crates/texture/src/lib.rs @@ -19,10 +19,13 @@ //! 2 GiB minus one byte on 32-bit targets such as `wasm32`. The `try_` forms return //! [`ImageError::TooLarge`] for a plane over that bound, also when the caller raised the limits //! past it. The constructors without `try_` clamp each side to `1..=MAX_SIDE`, and [`Image::map`] -//! clamps the same way when its result would be over the bound. Every operation that allocates has -//! a `try_` form that reserves its memory first and returns [`ImageError::OutOfMemory`] when that -//! fails; the forms without `try_` allocate like `Vec`, which ends the process when memory runs -//! out. Rows are generated on several threads only with the `parallel` feature. +//! clamps the same way when its result would be over the bound. Every operation that allocates a +//! pixel buffer has a `try_` form that reserves that buffer first and returns +//! [`ImageError::OutOfMemory`] when the reservation fails. The `try_` forms still make small +//! allocations that are not fallible: the `Arc` that holds a new image's buffer, and the boxed +//! resampler of [`Image::try_resize`]. The forms without `try_` allocate like `Vec`. A failed +//! infallible allocation ends the process. Rows are generated on several threads only with the +//! `parallel` feature. #![forbid(unsafe_code)] #![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] @@ -343,17 +346,20 @@ impl Image { let (tx, ty) = (fx - x0, fy - y0); let (x0, y0) = (x0 as i64, y0 as i64); let taps = [((1.0 - tx) * (1.0 - ty), x0, y0), (tx * (1.0 - ty), x0 + 1, y0), ((1.0 - tx) * ty, x0, y0 + 1), (tx * ty, x0 + 1, y0 + 1)]; - let mut o = [0.0; 4]; + // Summed in f64: the rounded weights can add up to slightly more than 1, which would + // overflow a finite HDR value near `f32::MAX` in f32. A finite sum is clamped to the f32 + // range; an infinite texel still gives an infinite or NaN sample. + let mut o = [0.0f64; 4]; for (weight, x, y) in taps { if weight == 0.0 { continue; } let p = self.get(x, y, tile); for (o, p) in o.iter_mut().zip(p) { - *o += weight * p; + *o += f64::from(weight) * f64::from(p); } } - o + o.map(|v| if v.is_finite() { v.clamp(f64::from(f32::MIN), f64::from(f32::MAX)) as f32 } else { v as f32 }) } #[inline] @@ -724,6 +730,13 @@ mod tests { assert_eq!(img.sample(0.25, 0.5, false)[0], 1.0); let Ok(hdr) = Image::from_data(2, 1, Kind::Gray, vec![f32::MAX, -f32::MAX], &l) else { panic!("valid 2 x 1 image") }; assert_eq!(hdr.sample(0.5, 0.5, false)[0], 0.0); + // Rounded weights can sum past 1; a constant image of the largest float stays finite. + let max = Image::filled(2, 2, Kind::Gray, [f32::MAX; 4]); + let t = 0.5 + 2.0_f32.powi(-24); + for tile in [false, true] { + assert!(max.sample(0.250_012_5, t, tile)[0].is_finite(), "tile = {tile}"); + assert_eq!(max.sample(t, t, tile)[0], f32::MAX, "tile = {tile}"); + } } #[test] From 47baffee9d7f74c061103a1ab79176dcf08a1cb8 Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Fri, 13 Nov 2026 19:55:39 -0800 Subject: [PATCH 20/51] craft-texture: compare images by value whether or not the buffer is shared Image equality no longer short-cuts on a shared buffer. An image holding NaN compared equal to its clone but unequal to the same image built again; it is now unequal to both, as f32 comparison gives. --- crates/texture/src/lib.rs | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/crates/texture/src/lib.rs b/crates/texture/src/lib.rs index 78966f6ff..2aaef3e8b 100644 --- a/crates/texture/src/lib.rs +++ b/crates/texture/src/lib.rs @@ -134,9 +134,11 @@ pub struct Image { data: Arc>, } +/// Images are equal when their size, kind and floats are equal. Floats compare as `f32` does, so +/// an image holding NaN is unequal to every image, its clones included. impl PartialEq for Image { fn eq(&self, o: &Image) -> bool { - self.w == o.w && self.h == o.h && self.kind == o.kind && (Arc::ptr_eq(&self.data, &o.data) || self.data == o.data) + self.w == o.w && self.h == o.h && self.kind == o.kind && self.data == o.data } } @@ -739,6 +741,18 @@ mod tests { } } + #[test] + fn equality_does_not_depend_on_buffer_sharing() { + let img = Image::filled(2, 1, Kind::Gray, [f32::NAN; 4]); + let rebuilt = Image::filled(2, 1, Kind::Gray, [f32::NAN; 4]); + // NaN pixels compare unequal as floats do, whether or not the buffer is shared. + assert_ne!(img, rebuilt); + assert_ne!(img, img.clone()); + let finite = Image::filled(2, 1, Kind::Gray, [0.5; 4]); + assert_eq!(finite, finite.clone()); + assert_eq!(finite, Image::filled(2, 1, Kind::Gray, [0.5; 4])); + } + #[test] fn box_shrink_averages_large_hdr_values() { let img = Image::filled(2, 2, Kind::Color, [f32::MAX, -f32::MAX, 1.0, 1.0]); From 6f7c041a09ae6a38c1ea7be5328b4a6c73b07c5d Mon Sep 17 00:00:00 2001 From: alehel Date: Sat, 14 Nov 2026 08:31:05 +0100 Subject: [PATCH 21/51] craft-audio: tests of the coded formats hold on ffmpeg 8 and without AAC - ffmpeg 8 skips an AAC M4A's priming but plays the last packet's padding (ffmpeg 9 cuts it): the ffmpeg oracle test takes either length, and the README says which readers end the audio where. - With alac-encode and no aac-encode, `m4a` names ALAC: the extension test compared it with AAC. Refs #1230 --- crates/audio/README.md | 3 +++ crates/audio/tests/audio/decode_extensions.rs | 4 +++- crates/audio/tests/codecs/file_formats.rs | 8 +++++--- 3 files changed, 11 insertions(+), 4 deletions(-) diff --git a/crates/audio/README.md b/crates/audio/README.md index aae1703ec..2edc4bb13 100644 --- a/crates/audio/README.md +++ b/crates/audio/README.md @@ -468,6 +468,9 @@ match craft_audio::decode(&bytes, None) { the length: the file decodes with 1057 (MP3) or 256 (AC-3, E-AC-3) frames of delay in front and padded to whole frames at the end. MP3 gets no Xing / Info frame. `EncodeFormat::Aac` and `Alac` (M4A) decode to the length written. +- An AAC M4A's length is in the edit list and the last packet's duration. This crate, Apple's + decoders and ffmpeg 9 end the audio there; ffmpeg 8 skips the priming but plays the last + packet's padding (under 1024 frames of near silence). - `EncodeFormat::Aac` and `Alac` write the `moov` box after the audio (no fast start), and no metadata. Raw ADTS AAC is not a file format of `encode`; `aac::EncoderConfig::with_adts` gives the frames. diff --git a/crates/audio/tests/audio/decode_extensions.rs b/crates/audio/tests/audio/decode_extensions.rs index f6f021c65..27a5573de 100644 --- a/crates/audio/tests/audio/decode_extensions.rs +++ b/crates/audio/tests/audio/decode_extensions.rs @@ -66,7 +66,9 @@ fn every_encode_format_has_an_extension_it_is_written_and_read_under() { // A format whose feature is off has no name. match craft_audio::encode_format_for(ext) { Some(named) => { - assert!(named == format || (named, format) == (EncodeFormat::Aac, EncodeFormat::Alac), "{ext}"); + let shares_m4a = |f| matches!(f, EncodeFormat::Aac | EncodeFormat::Alac); + assert!(named == format || (shares_m4a(named) && shares_m4a(format)), "{ext}"); + assert!(named.is_built(), "{ext}"); assert!(craft_audio::ENCODE_EXTENSIONS.contains(&ext), "{ext}"); } None => assert!(!matches!(format, EncodeFormat::Wav | EncodeFormat::Aiff | EncodeFormat::Flac), "{ext}"), diff --git a/crates/audio/tests/codecs/file_formats.rs b/crates/audio/tests/codecs/file_formats.rs index 46ed901ff..deac5714d 100644 --- a/crates/audio/tests/codecs/file_formats.rs +++ b/crates/audio/tests/codecs/file_formats.rs @@ -418,8 +418,8 @@ fn ffmpeg_decode(ff: &std::path::Path, file: &[u8], name: &str, channels: usize) planar } -/// ffmpeg reads every format: the M4A files at the length written (it applies the edit list), -/// ALAC exactly, the raw streams behind their delay. +/// ffmpeg reads every format: the M4A files without their priming (it applies the edit list) and, +/// from ffmpeg 9, at the length written; ALAC exactly; the raw streams behind their delay. #[test] fn ffmpeg_reads_the_files() { let ff = require_ffmpeg!(); @@ -428,7 +428,9 @@ fn ffmpeg_reads_the_files() { let mut opts = EncodeOptions::new(EncodeFormat::Aac); opts.layout = layout; let out = ffmpeg_decode(&ff, &encode(&buf, &opts).unwrap(), &format!("aac_{channels}.m4a"), channels); - assert_eq!(out[0].len(), 20_000, "AAC, {channels} channels"); + // The priming is skipped by every ffmpeg (the channels below line up). The padding of the + // last packet is cut by ffmpeg 9; ffmpeg 8 plays it, to the end of the 20th packet. + assert!([20_000, 20_480].contains(&out[0].len()), "AAC, {channels} channels: {} frames", out[0].len()); if channels <= 6 { // ffmpeg also returns 5.1 in WAV order. for (c, (want, got)) in buf.channels.iter().zip(&out).enumerate() { From 1570d6a29aa7d6e4112591c1d04402c4e167b318 Mon Sep 17 00:00:00 2001 From: alehel Date: Sat, 14 Nov 2026 08:48:19 +0100 Subject: [PATCH 22/51] craft-audio: ask what a format takes before writing a file - EncodeOptions::check says whether a file can be begun, with the error FileEncoder::new would return and nothing written. - EncodeOptions::bitrate and FileEncoder::bitrate give the constant bit rate actually used, after it is moved to one the stream can carry. - EncodeFormat::sample_rates, max_channels, fixed_layouts, supports_layout and supports_quality say what a format takes, also when its feature is off. The writer reads its layouts from the same table, and tests hold the tables to the encoders and to what the writer accepts. Refs #1230 --- crates/audio/README.md | 17 ++++ crates/audio/src/layout.rs | 34 +++++++ crates/audio/src/lib.rs | 79 ++++++++++++++++ crates/audio/src/write/coded.rs | 106 +++++++--------------- crates/audio/src/write/coded/tests.rs | 48 +++++++++- crates/audio/src/write/mod.rs | 42 +++++++++ crates/audio/tests/codecs/file_formats.rs | 71 +++++++++++++++ 7 files changed, 320 insertions(+), 77 deletions(-) diff --git a/crates/audio/README.md b/crates/audio/README.md index 2edc4bb13..31c58568b 100644 --- a/crates/audio/README.md +++ b/crates/audio/README.md @@ -277,6 +277,23 @@ rather than written to the wrong ones: - A surround pair is a surround pair: side and back surrounds are interchangeable where the format has one pair. +Before a file is created, the options and the format say what will happen: + +```rust +let opts = EncodeOptions::new(EncodeFormat::Ac3).with_layout(info.layout).with_bitrate(200_000); +opts.check(info.sample_rate, info.channels)?; // the error FileEncoder::new would return, nothing written +let bps = opts.bitrate(info.sample_rate, info.channels)?; // Some(192_000): the rate actually used; None when lossless or by quality + +EncodeFormat::Ac3.sample_rates(); // Some(&[32_000, 44_100, 48_000]); None when any rate will do +EncodeFormat::Ac3.max_channels(); // 6 +EncodeFormat::Ac3.fixed_layouts(3); // L R C, L R Cb, L R LFE; None for WAV, AIFF and FLAC (any layout) +EncodeFormat::Ac3.supports_layout(&info.layout); // one of those, sides and backs standing for each other +EncodeFormat::Ac3.supports_quality(); // false: AAC only +``` + +`FileEncoder::bitrate()` gives the rate of a file being written. These answer for a format whose +feature is off too, except `check` and `EncodeOptions::bitrate`, which return its `Unsupported`. + The layout `decode` reports (`AudioInfo::layout`) can be passed to `with_layout` as it is. When a coded format refuses it (2.1 or quad into AAC, a single channel tagged as left, channels with no speaker assignment), the choices are another format, or audio rearranged into one of the layouts diff --git a/crates/audio/src/layout.rs b/crates/audio/src/layout.rs index f3cab1b7f..d0c5ae39e 100644 --- a/crates/audio/src/layout.rs +++ b/crates/audio/src/layout.rs @@ -283,6 +283,40 @@ pub(crate) fn flac_assumed_mask(channels: usize) -> u32 { } } +/// The surround speaker a layout may name in place of `speaker`: formats with one surround pair +/// do not tell side from back, so a pair of either kind feeds it. +fn surround_twin(speaker: Speaker) -> Option { + Some(match speaker { + Speaker::SideLeft => Speaker::BackLeft, + Speaker::SideRight => Speaker::BackRight, + Speaker::BackLeft => Speaker::SideLeft, + Speaker::BackRight => Speaker::SideRight, + _ => return None, + }) +} + +/// How audio with `layout` feeds a format whose layout for the channel count is `mask`: for each +/// channel the format takes, the channel of the audio that feeds it. `order` is the format's +/// channel order over `mask` (for each of its channels, the WAV-order channel of `mask`; `None` +/// when it takes WAV order). `None` when `layout` is not the format's layout: it is unordered, or +/// has a speaker the format has not. +pub(crate) fn channel_map(mask: u32, order: Option<&[usize]>, layout: &ChannelLayout) -> Option> { + let speakers = ChannelLayout::from_mask(mask).speakers(); + if speakers.len() != usize::from(layout.channels()) { + return None; + } + let mut map = Vec::with_capacity(speakers.len()); + for j in 0..speakers.len() { + let speaker = *speakers.get(order.and_then(|o| o.get(j).copied()).unwrap_or(j))?; + let at = layout.index_of(speaker).or_else(|| surround_twin(speaker).and_then(|t| layout.index_of(t)))?; + if map.contains(&at) { + return None; + } + map.push(at); + } + Some(map) +} + #[cfg(test)] mod tests { use super::*; diff --git a/crates/audio/src/lib.rs b/crates/audio/src/lib.rs index 6418f3a99..4fa7f41b8 100644 --- a/crates/audio/src/lib.rs +++ b/crates/audio/src/lib.rs @@ -352,6 +352,85 @@ impl EncodeFormat { } } + /// The sample rates the format takes, ascending, or `None` when it has no fixed list (WAV, + /// AIFF, FLAC and ALAC take any rate their headers can hold). + pub fn sample_rates(self) -> Option<&'static [u32]> { + match self { + EncodeFormat::Aac => Some(&[7350, 8000, 11_025, 12_000, 16_000, 22_050, 24_000, 32_000, 44_100, 48_000, 64_000, 88_200, 96_000]), + EncodeFormat::Mp3 => Some(&[16_000, 22_050, 24_000, 32_000, 44_100, 48_000]), + EncodeFormat::Ac3 | EncodeFormat::Eac3 => Some(&[32_000, 44_100, 48_000]), + EncodeFormat::Wav | EncodeFormat::Aiff | EncodeFormat::Flac | EncodeFormat::Alac => None, + } + } + + /// The most channels a file of this format holds. + pub fn max_channels(self) -> u16 { + match self { + EncodeFormat::Wav | EncodeFormat::Aiff => u16::MAX, + EncodeFormat::Flac | EncodeFormat::Aac | EncodeFormat::Alac | EncodeFormat::Eac3 => 8, + EncodeFormat::Ac3 => 6, + EncodeFormat::Mp3 => 2, + } + } + + /// The speaker layouts of a format that has a fixed set of them, as WAV masks, for a channel + /// count: one each for AAC, ALAC and MP3, one per coding mode for AC-3 and E-AC-3. Empty for a + /// count the format has not, and for WAV, AIFF and FLAC, which have no such set. + pub(crate) fn layout_masks(self, channels: u16) -> &'static [u32] { + let per_count: &[&[u32]] = match self { + // Channel configurations 1–6, the 6.1 program config element, and configuration 7 + // (7.1 with a front pair left and right of centre). + EncodeFormat::Aac => &[&[0x4], &[0x3], &[0x7], &[0x107], &[0x607], &[0x60F], &[0x70F], &[0xFF]], + // Apple's layout tags for 1–8 channels, surrounds as back speakers. + EncodeFormat::Alac => &[&[0x4], &[0x3], &[0x7], &[0x107], &[0x37], &[0x3F], &[0x13F], &[0xFF]], + EncodeFormat::Mp3 => &[&[0x4], &[0x3]], + // The coding modes 1/0 to 3/2 with and without an LFE, by channel count. + EncodeFormat::Ac3 => &[&[0x4], &[0x3, 0xC], &[0x7, 0x103, 0xB], &[0x107, 0x603, 0xF, 0x10B], &[0x607, 0x10F, 0x60B], &[0x60F]], + // The same, and 7.1 with backs and sides. + EncodeFormat::Eac3 => { + &[&[0x4], &[0x3, 0xC], &[0x7, 0x103, 0xB], &[0x107, 0x603, 0xF, 0x10B], &[0x607, 0x10F, 0x60B], &[0x60F], &[], &[0x63F]] + } + EncodeFormat::Wav | EncodeFormat::Aiff | EncodeFormat::Flac => &[], + }; + usize::from(channels).checked_sub(1).and_then(|i| per_count.get(i)).copied().unwrap_or_default() + } + + /// The speaker layouts a format with a fixed set of them has for `channels` channels: one for + /// AAC, ALAC and MP3, one per coding mode for AC-3 and E-AC-3; empty when the format cannot + /// hold that many channels. `None` for WAV, AIFF and FLAC, which take any layout. Audio in + /// another layout has to be rearranged into one of these before it is written. + /// + /// ``` + /// use craft_audio::{ChannelLayout, EncodeFormat}; + /// + /// assert_eq!(EncodeFormat::Aac.fixed_layouts(6), Some(vec![ChannelLayout::SURROUND_5_1_SIDE])); + /// assert_eq!(EncodeFormat::Mp3.fixed_layouts(6), Some(vec![])); + /// assert_eq!(EncodeFormat::Wav.fixed_layouts(6), None); + /// ``` + pub fn fixed_layouts(self, channels: u16) -> Option> { + match self { + EncodeFormat::Wav | EncodeFormat::Aiff | EncodeFormat::Flac => None, + _ => Some(self.layout_masks(channels).iter().map(|&mask| ChannelLayout::from_mask(mask)).collect()), + } + } + + /// Whether the format holds audio with `layout`: for WAV, AIFF and FLAC any layout of up to + /// [`max_channels`](Self::max_channels) channels, for the others one of + /// [`fixed_layouts`](Self::fixed_layouts), where side and back surrounds stand for each other + /// in a layout with one surround pair. + pub fn supports_layout(self, layout: &ChannelLayout) -> bool { + match self { + EncodeFormat::Wav | EncodeFormat::Aiff | EncodeFormat::Flac => (1..=self.max_channels()).contains(&layout.channels()), + _ => self.layout_masks(layout.channels()).iter().any(|&mask| layout::channel_map(mask, None, layout).is_some()), + } + } + + /// Whether the format takes [`RateControl::Quality`]: AAC. The other lossy formats are + /// written at a constant bit rate only. + pub fn supports_quality(self) -> bool { + self == EncodeFormat::Aac + } + /// Whether the format loses audio: AAC, MP3, AC-3 and E-AC-3. These take /// [`EncodeOptions::rate_control`] and ignore the bit depth and dither. pub fn is_lossy(self) -> bool { diff --git a/crates/audio/src/write/coded.rs b/crates/audio/src/write/coded.rs index ef33168a8..0d0dd626f 100644 --- a/crates/audio/src/write/coded.rs +++ b/crates/audio/src/write/coded.rs @@ -12,7 +12,8 @@ use super::failed_write_error; use super::pcm::validate_layout; -use crate::{AudioBuffer, AudioError, ChannelLayout, EncodeFormat, EncodeOptions, RateControl, Result, Speaker}; +use crate::layout::channel_map; +use crate::{AudioBuffer, AudioError, ChannelLayout, EncodeFormat, EncodeOptions, RateControl, Result}; use std::io::{Cursor, Seek, Write}; /// Frames handed to the encoder at a time, so its buffers and the packets waiting to be written @@ -25,50 +26,17 @@ const AAC_DEFAULT_BPS_PER_CHANNEL: u32 = 64_000; /// full-bandwidth channel). const DEFAULT_KBPS_PER_CHANNEL: u32 = 96; -/// The surround speaker a layout may name in place of `speaker`: formats with one surround pair -/// do not tell side from back, so a pair of either kind feeds it. -fn twin(speaker: Speaker) -> Option { - Some(match speaker { - Speaker::SideLeft => Speaker::BackLeft, - Speaker::SideRight => Speaker::BackRight, - Speaker::BackLeft => Speaker::SideLeft, - Speaker::BackRight => Speaker::SideRight, - _ => return None, - }) -} - /// The speakers of `mask` as labels: `"L R C LFE Ls Rs"`. fn labels(mask: u32) -> String { ChannelLayout::from_mask(mask).speakers().iter().map(|s| s.label()).collect::>().join(" ") } -/// For each channel the encoder takes, the channel of the caller's audio that feeds it. `mask` is -/// the layout the format has for the channel count, and `order` the encoder's channel order over -/// it (for each encoder channel, the WAV-order channel of `mask`; `None` when the encoder takes -/// WAV order). `layout` names the speakers of the caller's channels. `None` when `layout` is not -/// the format's layout: it is unordered, or has a speaker the format has not. -fn channel_map(mask: u32, order: Option<&[usize]>, layout: &ChannelLayout) -> Option> { - let speakers = ChannelLayout::from_mask(mask).speakers(); - if speakers.len() != usize::from(layout.channels()) { - return None; - } - let mut map = Vec::with_capacity(speakers.len()); - for j in 0..speakers.len() { - let speaker = *speakers.get(order.and_then(|o| o.get(j).copied()).unwrap_or(j))?; - let at = layout.index_of(speaker).or_else(|| twin(speaker).and_then(|t| layout.index_of(t)))?; - if map.contains(&at) { - return None; - } - map.push(at); - } - Some(map) -} - -/// [`channel_map`] for a format with one layout per channel count, or why the audio does not fit. -fn fixed_map(name: &str, mask: u32, order: Option<&[usize]>, layout: &ChannelLayout) -> Result> { - if mask == 0 { +/// [`channel_map`] for a format with one layout per channel count ([`EncodeFormat::layout_masks`]), +/// or why the audio does not fit. +fn fixed_map(format: EncodeFormat, name: &str, order: Option<&[usize]>, layout: &ChannelLayout) -> Result> { + let Some(&mask) = format.layout_masks(layout.channels()).first() else { return Err(AudioError::Unsupported(format!("{name} cannot hold {} channels", layout.channels()))); - } + }; channel_map(mask, order, layout).ok_or_else(|| { AudioError::Unsupported(format!("{name} holds {} channels as {}; the audio is {}", layout.channels(), labels(mask), given(layout))) }) @@ -79,25 +47,7 @@ fn given(layout: &ChannelLayout) -> String { layout.mask().map_or_else(|| "without speaker assignment".into(), labels) } -/// The WAV mask of the speakers an AAC stream of `channels` channels has, as this crate's encoder -/// writes it and its decoder reports it: channel configurations 1–6, the 6.1 program config -/// element for 7, and configuration 7 (7.1 with a front pair left and right of centre) for 8. -#[cfg(feature = "aac-encode")] -fn aac_mask(channels: usize) -> u32 { - match channels { - 1 => 0x4, - 2 => 0x3, - 3 => 0x7, - 4 => 0x107, - 5 => 0x607, - 6 => 0x60F, - 7 => 0x70F, - 8 => 0xFF, - _ => 0, - } -} - -/// The encoder's channel order over [`aac_mask`]: [`crate::aac::aac_order`], and for 8 channels +/// The encoder's channel order over AAC's layout for the count: [`crate::aac::aac_order`], and for 8 channels /// configuration 7's C, Lc Rc, L R, Ls Rs, LFE over the WAV order L R C LFE Ls Rs Lc Rc. #[cfg(feature = "aac-encode")] fn aac_order(channels: usize) -> Option<&'static [usize]> { @@ -428,6 +378,9 @@ pub(crate) struct Writer { sink: Sink, /// For each encoder channel, the caller's channel that feeds it. map: Vec, + /// The constant bit rate the encoder was set to, bits per second; `None` for ALAC and for + /// AAC at a constant quality. + bitrate: Option, frames: u64, packets: Vec, /// Set when a write has failed: the encoder and the sink no longer agree, so the writer @@ -439,20 +392,22 @@ impl Writer { pub(crate) fn new(out: W, opts: &EncodeOptions, sample_rate: u32, channels: usize) -> Result { validate_layout(channels, sample_rate)?; let layout = opts.layout.unwrap_or_else(|| ChannelLayout::default_for(channels as u16)); - let (codec, map) = match opts.format { + let (codec, map, bitrate) = match opts.format { #[cfg(feature = "aac-encode")] EncodeFormat::Aac => { - let map = fixed_map("AAC", aac_mask(channels), aac_order(channels), &layout)?; - let config = crate::aac::EncoderConfig { - mode: aac_mode(opts.rate_control, sample_rate, channels), - ..crate::aac::EncoderConfig::cbr(sample_rate, channels, 0) + let map = fixed_map(EncodeFormat::Aac, "AAC", aac_order(channels), &layout)?; + let mode = aac_mode(opts.rate_control, sample_rate, channels); + let config = crate::aac::EncoderConfig { mode, ..crate::aac::EncoderConfig::cbr(sample_rate, channels, 0) }; + let bitrate = match mode { + crate::aac::BitrateMode::Cbr(bps) => Some(bps), + crate::aac::BitrateMode::Vbr(_) => None, }; - (Codec::Aac(Box::new(crate::aac::Encoder::new(config)?)), map) + (Codec::Aac(Box::new(crate::aac::Encoder::new(config)?)), map, bitrate) } #[cfg(feature = "alac-encode")] EncodeFormat::Alac => { let count = u8::try_from(channels).unwrap_or(u8::MAX); - let map = fixed_map("ALAC", crate::alac::channel_mask(count), crate::alac::alac_order(count), &layout)?; + let map = fixed_map(EncodeFormat::Alac, "ALAC", crate::alac::alac_order(count), &layout)?; let bits = match opts.bit_depth { crate::BitDepth::Int16 => 16, crate::BitDepth::Int24 => 24, @@ -461,26 +416,23 @@ impl Writer { }; let enc = crate::alac::Encoder::new(crate::alac::EncoderConfig::new(sample_rate, count, bits).with_frame_length(CHUNK as u32))?; let quantizers = super::pcm::Quantizer::per_channel(u32::from(bits), opts.dither, channels); - (Codec::Alac { enc: Box::new(enc), quantizers, pending: vec![Vec::new(); channels] }, map) + (Codec::Alac { enc: Box::new(enc), quantizers, pending: vec![Vec::new(); channels] }, map, None) } #[cfg(feature = "mp3-encode")] EncodeFormat::Mp3 => { - let mask = match channels { - 1 => 0x4, - 2 => 0x3, - _ => 0, - }; - let map = fixed_map("MP3", mask, None, &layout)?; + let map = fixed_map(EncodeFormat::Mp3, "MP3", None, &layout)?; let want = constant_kbps("MP3", opts.rate_control, DEFAULT_KBPS_PER_CHANNEL * channels as u32)?; // A sample rate MP3 has not is the encoder's to refuse. let kbps = crate::mp3::nearest_bitrate(sample_rate, want).unwrap_or(want); - (Codec::Mp3(Box::new(crate::mp3::Encoder::new(crate::mp3::Config::cbr(sample_rate, channels, kbps))?)), map) + let enc = crate::mp3::Encoder::new(crate::mp3::Config::cbr(sample_rate, channels, kbps))?; + (Codec::Mp3(Box::new(enc)), map, Some(kbps.saturating_mul(1000))) } #[cfg(any(feature = "ac3-encode", feature = "eac3-encode"))] EncodeFormat::Ac3 | EncodeFormat::Eac3 => { let codec = if opts.format == EncodeFormat::Ac3 { crate::ac3::encoder::Codec::Ac3 } else { crate::ac3::encoder::Codec::Eac3 }; let (config, map) = ac3_config(codec, sample_rate, &layout, opts.rate_control)?; - (Codec::Ac3 { enc: Box::new(crate::ac3::encoder::Encoder::new(config)?), planes: vec![Vec::new(); channels] }, map) + let enc = crate::ac3::encoder::Encoder::new(config)?; + (Codec::Ac3 { enc: Box::new(enc), planes: vec![Vec::new(); channels] }, map, Some(config.bitrate_kbps.saturating_mul(1000))) } #[allow(unreachable_patterns)] f => return Err(AudioError::Unsupported(format!("writing {f:?}"))), @@ -490,7 +442,11 @@ impl Writer { EncodeFormat::Aac | EncodeFormat::Alac => Sink::M4a(Box::new(M4a::new(out, &codec, sample_rate, channels as u32)?)), _ => Sink::Raw(out), }; - Ok(Writer { codec, sink, map, frames: 0, packets: Vec::new(), failed: false }) + Ok(Writer { codec, sink, map, bitrate, frames: 0, packets: Vec::new(), failed: false }) + } + + pub(crate) fn bitrate(&self) -> Option { + self.bitrate } /// Hands the packets waiting to the sink. diff --git a/crates/audio/src/write/coded/tests.rs b/crates/audio/src/write/coded/tests.rs index 4aeaac66e..9c80c8ab5 100644 --- a/crates/audio/src/write/coded/tests.rs +++ b/crates/audio/src/write/coded/tests.rs @@ -1,5 +1,7 @@ use super::*; +use crate::Speaker; + fn map(mask: u32, order: Option<&[usize]>, layout: u32) -> Option> { channel_map(mask, order, &ChannelLayout::from_mask(layout)) } @@ -29,13 +31,13 @@ fn channels_are_mapped_by_speaker() { #[test] fn every_aac_channel_count_has_a_layout_and_an_order() { for channels in 1..=8 { - let mask = aac_mask(channels); + let mask = EncodeFormat::Aac.layout_masks(channels as u16)[0]; assert_eq!(mask.count_ones() as usize, channels); let mut order = map(mask, aac_order(channels), mask).unwrap(); order.sort_unstable(); assert_eq!(order, (0..channels).collect::>()); } - assert_eq!(aac_mask(9), 0); + assert!(EncodeFormat::Aac.layout_masks(9).is_empty() && EncodeFormat::Aac.layout_masks(0).is_empty()); // Configuration 7: C, Lc Rc, L R, Ls Rs, LFE. let wide: Vec = ChannelLayout::from_mask(0xFF).speakers(); let named: Vec = aac_order(8).unwrap().iter().map(|&c| wide[c]).collect(); @@ -113,3 +115,45 @@ fn ac3_settings_follow_the_layout_and_validate() { assert!(matches!(ac3_config(Codec::Ac3, 48_000, &ChannelLayout::STEREO, Some(RateControl::Quality(0.5))), Err(AudioError::Unsupported(_)))); assert!(matches!(ac3_config(Codec::Ac3, 48_000, &ChannelLayout::unordered(2), None), Err(AudioError::Unsupported(_)))); } + +/// The layouts `EncodeFormat` lists are the encoders' own: ALAC's layout per channel count, and +/// the speakers of every AC-3 and E-AC-3 coding mode the encoder has. +#[cfg(all(feature = "alac-encode", feature = "ac3-encode", feature = "eac3-encode"))] +#[test] +fn the_listed_layouts_are_the_encoders() { + use crate::ac3::encoder::{Codec, CodingMode::*, Config}; + for channels in 0..=10u16 { + let alac = crate::alac::channel_mask(channels as u8); + assert_eq!(EncodeFormat::Alac.layout_masks(channels), if alac == 0 { &[][..] } else { std::slice::from_ref(&alac) }, "ALAC, {channels}"); + for (format, codec) in [(EncodeFormat::Ac3, Codec::Ac3), (EncodeFormat::Eac3, Codec::Eac3)] { + let modes = [Mono, Stereo, ThreeFront, StereoSurround, ThreeFrontSurround, StereoTwoSurround, ThreeFrontTwoSurround, Surround71]; + let mut encoder: Vec = modes + .iter() + .flat_map(|&mode| [false, true].map(|lfe| Config { codec, sample_rate: 48_000, bitrate_kbps: 640, mode, lfe })) + .filter(|config| config.validate().is_ok() && config.channels() == usize::from(channels)) + .filter_map(|config| config.channel_layout().mask()) + .collect(); + let mut listed = format.layout_masks(channels).to_vec(); + encoder.sort_unstable(); + listed.sort_unstable(); + assert_eq!(listed, encoder, "{format:?}, {channels} channels"); + for &mask in &listed { + let layout = ChannelLayout::from_mask(mask); + assert_eq!(ac3_config(codec, 48_000, &layout, None).unwrap().0.channel_layout(), layout); + } + } + } +} + +/// The sample rates `EncodeFormat` lists are the encoders'. +#[cfg(all(feature = "aac-encode", feature = "mp3-encode"))] +#[test] +fn the_listed_sample_rates_are_the_encoders() { + let sorted = |rates: &[u32]| { + let mut rates = rates.to_vec(); + rates.sort_unstable(); + rates + }; + assert_eq!(EncodeFormat::Aac.sample_rates().unwrap(), sorted(&crate::aac::SAMPLE_RATES)); + assert_eq!(EncodeFormat::Mp3.sample_rates().unwrap(), sorted(&crate::mp3::SAMPLE_RATES)); +} diff --git a/crates/audio/src/write/mod.rs b/crates/audio/src/write/mod.rs index 2d8e8d9db..a96042f12 100644 --- a/crates/audio/src/write/mod.rs +++ b/crates/audio/src/write/mod.rs @@ -222,6 +222,19 @@ impl FileEncoder { Ok(FileEncoder { writer, format: opts.format, channels }) } + /// The constant bit rate the file is written at, in bits per second for all channels + /// together: the rate asked for ([`RateControl::Bitrate`](crate::RateControl::Bitrate)) or the + /// format's default, moved to the nearest one the stream can carry. `None` for the lossless + /// formats and for AAC at a constant quality. + pub fn bitrate(&self) -> Option { + match &self.writer { + #[cfg(any(feature = "aac-encode", feature = "alac-encode", feature = "mp3-encode", feature = "ac3-encode", feature = "eac3-encode"))] + Writer::Coded(w) => w.bitrate(), + #[allow(unreachable_patterns)] + _ => None, + } + } + /// Fails, without writing anything, when `frames` more frames would not fit the format (an /// AIFF holds 4 GiB, a FLAC 2^36 - 1 frames). The coded formats have no limit a file reaches. pub fn check_room(&self, frames: u64) -> Result<()> { @@ -281,6 +294,35 @@ impl FileEncoder { } } +impl EncodeOptions { + /// Whether a file of `channels` channels at `sample_rate` can be written with these options: + /// `Ok`, or the error [`FileEncoder::new`] and [`encode`] would return, with nothing written. + /// For choosing a format before a file is created; [`EncodeFormat::sample_rates`], + /// [`EncodeFormat::max_channels`] and [`EncodeFormat::supports_layout`] say what a format takes. + /// + /// ``` + /// # #[cfg(feature = "mp3-encode")] { + /// use craft_audio::{EncodeFormat, EncodeOptions}; + /// + /// let mp3 = EncodeOptions::new(EncodeFormat::Mp3).with_bitrate(200_000); + /// assert!(mp3.check(48_000, 2).is_ok()); + /// assert!(mp3.check(96_000, 2).is_err()); // not an MP3 sample rate + /// assert_eq!(mp3.bitrate(48_000, 2).unwrap(), Some(192_000)); // the table rate below 200 kbit/s + /// # } + /// ``` + pub fn check(&self, sample_rate: u32, channels: u16) -> Result<()> { + self.bitrate(sample_rate, channels).map(drop) + } + + /// The constant bit rate such a file would be written at ([`FileEncoder::bitrate`]), or the + /// error [`EncodeOptions::check`] returns. + pub fn bitrate(&self, sample_rate: u32, channels: u16) -> Result> { + // The encoder a file would get, on a sink that is thrown away: what it accepts and the + // rate it settles on are then the writer's by construction. + Ok(FileEncoder::new(std::io::Cursor::new(Vec::new()), self, sample_rate, channels)?.bitrate()) + } +} + /// The header of a 32-bit float WAV holding `frames` frames (little-endian samples follow it). Its /// length doesn't depend on `frames`, so a recorder can rewrite it in place as the file grows; it /// switches to RF64 above 4 GiB. diff --git a/crates/audio/tests/codecs/file_formats.rs b/crates/audio/tests/codecs/file_formats.rs index deac5714d..aa09d3d03 100644 --- a/crates/audio/tests/codecs/file_formats.rs +++ b/crates/audio/tests/codecs/file_formats.rs @@ -479,3 +479,74 @@ fn apple_reads_the_aac_priming_and_length() { assert!(text.contains(&format!("{frames} valid frames + 1024 priming + {remainder} remainder")), "{frames} frames: {text}"); } } + +/// What `EncodeFormat` says a format takes is what the writer accepts: for every format, a file +/// can be begun exactly when the sample rate, the channel count and the layout are listed. +#[test] +fn the_format_queries_agree_with_the_writer() { + let rates = [7350, 8000, 16_000, 22_050, 32_000, 44_000, 44_100, 48_000, 88_200, 96_000, 192_000]; + let masks = [ + 0x4, 0x1, 0x3, 0xC, 0x600, 0x7, 0xB, 0x103, 0x33, 0x107, 0x603, 0xF, 0x10B, 0x37, 0x607, 0x10F, 0x60B, 0x3F, 0x60F, 0x13F, 0x70F, 0x63F, 0xFF, + ]; + let layouts = masks.iter().map(|&mask| ChannelLayout::from_mask(mask)).chain((1..=9).map(ChannelLayout::unordered)); + for layout in layouts { + for &format in EncodeFormat::ALL { + // 24 bits is a depth every format has. + let opts = EncodeOptions::new(format).with_layout(layout); + for sample_rate in rates { + let listed = format.sample_rates().is_none_or(|r| r.contains(&sample_rate)) + && layout.channels() <= format.max_channels() + && format.supports_layout(&layout); + let checked = opts.check(sample_rate, layout.channels()); + assert_eq!(checked.is_ok(), listed, "{format:?}, {sample_rate} Hz, {layout:?}: {checked:?}"); + let begun = FileEncoder::new(Cursor::new(Vec::new()), &opts, sample_rate, layout.channels()); + assert_eq!(begun.is_ok(), listed, "{format:?}, {sample_rate} Hz, {layout:?}"); + } + if let Some(fixed) = format.fixed_layouts(layout.channels()) { + assert!(fixed.iter().all(|l| format.supports_layout(l) && l.channels() == layout.channels())); + assert_eq!(format.supports_layout(&layout), fixed.iter().any(|l| same_speakers(l, &layout)), "{format:?}, {layout:?}"); + } + } + } + for &format in EncodeFormat::ALL { + assert!(!format.supports_layout(&ChannelLayout::unordered(0))); + assert_eq!(format.supports_quality(), EncodeOptions::new(format).with_quality(0.5).check(48_000, 2).is_ok() && format.is_lossy()); + assert_eq!(format.fixed_layouts(2).is_none(), matches!(format, EncodeFormat::Wav | EncodeFormat::Aiff | EncodeFormat::Flac)); + } + assert_eq!(EncodeFormat::Ac3.fixed_layouts(3).unwrap().len(), 3); + assert!(EncodeFormat::Aac.fixed_layouts(9).unwrap().is_empty()); +} + +/// Whether two layouts name the same speakers, a surround pair being either sides or backs. +fn same_speakers(a: &ChannelLayout, b: &ChannelLayout) -> bool { + let one_pair = |mask: u32| if mask & 0x630 == 0x30 { mask & !0x30 | 0x600 } else { mask }; + matches!((a.mask(), b.mask()), (Some(a), Some(b)) if one_pair(a) == one_pair(b)) +} + +/// `bitrate` is the rate the file is written at, for the options and for the encoder they give. +#[test] +fn the_bit_rate_used_can_be_asked_for() { + let rate = |opts: EncodeOptions, sample_rate, channels| { + let asked = opts.bitrate(sample_rate, channels).unwrap(); + assert_eq!(FileEncoder::new(Cursor::new(Vec::new()), &opts, sample_rate, channels).unwrap().bitrate(), asked); + asked + }; + assert_eq!(rate(EncodeOptions::new(EncodeFormat::Mp3), 48_000, 2), Some(192_000)); + assert_eq!(rate(EncodeOptions::new(EncodeFormat::Mp3).with_bitrate(130_000), 48_000, 2), Some(128_000)); + assert_eq!(rate(EncodeOptions::new(EncodeFormat::Mp3).with_bitrate(u32::MAX), 22_050, 1), Some(160_000)); + assert_eq!(rate(EncodeOptions::new(EncodeFormat::Ac3).with_bitrate(191_999), 48_000, 2), Some(160_000)); + assert_eq!(rate(EncodeOptions::new(EncodeFormat::Ac3), 48_000, 6), Some(448_000)); + assert_eq!(rate(EncodeOptions::new(EncodeFormat::Eac3).with_bitrate(100_999), 48_000, 2), Some(100_000)); + assert_eq!(rate(EncodeOptions::new(EncodeFormat::Aac), 48_000, 2), Some(128_000)); + assert_eq!(rate(EncodeOptions::new(EncodeFormat::Aac).with_bitrate(128), 48_000, 2), Some(24_000)); + assert_eq!(rate(EncodeOptions::new(EncodeFormat::Aac).with_bitrate(u32::MAX), 8000, 1), Some(48_000)); + assert_eq!(rate(EncodeOptions::new(EncodeFormat::Aac).with_quality(0.5), 48_000, 2), None); + for format in [EncodeFormat::Wav, EncodeFormat::Aiff, EncodeFormat::Flac, EncodeFormat::Alac] { + assert_eq!(rate(EncodeOptions::new(format).with_bitrate(96_000), 48_000, 2), None, "{format:?}"); + } + // The size of a second of MP3 is the rate reported. + let buf = tones(48_000, 2, 48_000); + let opts = EncodeOptions::new(EncodeFormat::Mp3).with_bitrate(130_000); + assert_eq!(encode(&buf, &opts).unwrap().len() as u32, 43 * 1152 / 8 * opts.bitrate(48_000, 2).unwrap().unwrap() / 48_000); + assert!(is_unsupported(EncodeOptions::new(EncodeFormat::Mp3).bitrate(48_000, 6))); +} From 4732a89b0292367df8b12173a65b2b0e3de5c939 Mon Sep 17 00:00:00 2001 From: alehel Date: Sat, 14 Nov 2026 09:37:54 +0100 Subject: [PATCH 23/51] craft-audio: review of the format queries - EncodeFormat::max_channels gave 65535 for WAV and AIFF, whose headers hold 32767 (a WAV fewer at wider samples, which the doc now says). - Tests pin the AAC and MP3 layouts, each format's channel limit with the count above it, and every listed sample rate with its neighbours: the agreement test alone compared the tables with a writer that reads them. - Docs: FileEncoder::bitrate points at the rule RateControl::Bitrate states; the README says when check exists. Refs #1230 --- crates/audio/README.md | 5 +++-- crates/audio/src/lib.rs | 6 ++++-- crates/audio/src/write/coded/tests.rs | 8 ++++++++ crates/audio/src/write/mod.rs | 4 ++-- crates/audio/tests/codecs/file_formats.rs | 23 +++++++++++++++++++++-- 5 files changed, 38 insertions(+), 8 deletions(-) diff --git a/crates/audio/README.md b/crates/audio/README.md index 31c58568b..5a5df4f2f 100644 --- a/crates/audio/README.md +++ b/crates/audio/README.md @@ -291,8 +291,9 @@ EncodeFormat::Ac3.supports_layout(&info.layout); // one of those, sides and bac EncodeFormat::Ac3.supports_quality(); // false: AAC only ``` -`FileEncoder::bitrate()` gives the rate of a file being written. These answer for a format whose -feature is off too, except `check` and `EncodeOptions::bitrate`, which return its `Unsupported`. +`FileEncoder::bitrate()` gives the rate of a file being written. The `EncodeFormat` queries answer +for a format whose feature is off too; `check` and `EncodeOptions::bitrate` (there with any +encoder feature) return `Unsupported` for it. The layout `decode` reports (`AudioInfo::layout`) can be passed to `with_layout` as it is. When a coded format refuses it (2.1 or quad into AAC, a single channel tagged as left, channels with no diff --git a/crates/audio/src/lib.rs b/crates/audio/src/lib.rs index 4fa7f41b8..1c6c73dcf 100644 --- a/crates/audio/src/lib.rs +++ b/crates/audio/src/lib.rs @@ -363,10 +363,12 @@ impl EncodeFormat { } } - /// The most channels a file of this format holds. + /// The most channels a file of this format holds. A WAV's frame size is a 16-bit field, so it + /// holds 65535 / bytes per sample: 32767 at 16 bits (the count given here), 21845 at 24 and + /// 16383 at 32; [`EncodeOptions::check`] answers for the depth chosen. pub fn max_channels(self) -> u16 { match self { - EncodeFormat::Wav | EncodeFormat::Aiff => u16::MAX, + EncodeFormat::Wav | EncodeFormat::Aiff => 32_767, EncodeFormat::Flac | EncodeFormat::Aac | EncodeFormat::Alac | EncodeFormat::Eac3 => 8, EncodeFormat::Ac3 => 6, EncodeFormat::Mp3 => 2, diff --git a/crates/audio/src/write/coded/tests.rs b/crates/audio/src/write/coded/tests.rs index 9c80c8ab5..cbdbd3375 100644 --- a/crates/audio/src/write/coded/tests.rs +++ b/crates/audio/src/write/coded/tests.rs @@ -38,6 +38,14 @@ fn every_aac_channel_count_has_a_layout_and_an_order() { assert_eq!(order, (0..channels).collect::>()); } assert!(EncodeFormat::Aac.layout_masks(9).is_empty() && EncodeFormat::Aac.layout_masks(0).is_empty()); + // The layouts this crate's decoder reports for what the encoder writes (`track::aac_layout`), + // and configuration 7's speakers for 8 channels. + let masks: Vec = (1..=8).map(|channels| EncodeFormat::Aac.layout_masks(channels)[0]).collect(); + assert_eq!(masks, [0x4, 0x3, 0x7, 0x107, 0x607, 0x60F, 0x70F, 0xFF]); + assert_eq!( + (EncodeFormat::Mp3.layout_masks(1), EncodeFormat::Mp3.layout_masks(2), EncodeFormat::Mp3.layout_masks(3)), + (&[0x4][..], &[0x3][..], &[][..]) + ); // Configuration 7: C, Lc Rc, L R, Ls Rs, LFE. let wide: Vec = ChannelLayout::from_mask(0xFF).speakers(); let named: Vec = aac_order(8).unwrap().iter().map(|&c| wide[c]).collect(); diff --git a/crates/audio/src/write/mod.rs b/crates/audio/src/write/mod.rs index a96042f12..0de55c394 100644 --- a/crates/audio/src/write/mod.rs +++ b/crates/audio/src/write/mod.rs @@ -223,8 +223,8 @@ impl FileEncoder { } /// The constant bit rate the file is written at, in bits per second for all channels - /// together: the rate asked for ([`RateControl::Bitrate`](crate::RateControl::Bitrate)) or the - /// format's default, moved to the nearest one the stream can carry. `None` for the lossless + /// together: the rate asked for or the format's default, moved to one the stream + /// can carry as [`RateControl::Bitrate`](crate::RateControl::Bitrate) describes. `None` for the lossless /// formats and for AAC at a constant quality. pub fn bitrate(&self) -> Option { match &self.writer { diff --git a/crates/audio/tests/codecs/file_formats.rs b/crates/audio/tests/codecs/file_formats.rs index aa09d3d03..53947df12 100644 --- a/crates/audio/tests/codecs/file_formats.rs +++ b/crates/audio/tests/codecs/file_formats.rs @@ -484,7 +484,11 @@ fn apple_reads_the_aac_priming_and_length() { /// can be begun exactly when the sample rate, the channel count and the layout are listed. #[test] fn the_format_queries_agree_with_the_writer() { - let rates = [7350, 8000, 16_000, 22_050, 32_000, 44_000, 44_100, 48_000, 88_200, 96_000, 192_000]; + // Every rate a format lists, each with its neighbours, and some that none lists. + let mut rates: Vec = EncodeFormat::ALL.iter().filter_map(|f| f.sample_rates()).flatten().flat_map(|&r| [r - 1, r, r + 1]).collect(); + rates.extend([44_000, 176_400, 192_000]); + rates.sort_unstable(); + rates.dedup(); let masks = [ 0x4, 0x1, 0x3, 0xC, 0x600, 0x7, 0xB, 0x103, 0x33, 0x107, 0x603, 0xF, 0x10B, 0x37, 0x607, 0x10F, 0x60B, 0x3F, 0x60F, 0x13F, 0x70F, 0x63F, 0xFF, ]; @@ -493,7 +497,7 @@ fn the_format_queries_agree_with_the_writer() { for &format in EncodeFormat::ALL { // 24 bits is a depth every format has. let opts = EncodeOptions::new(format).with_layout(layout); - for sample_rate in rates { + for &sample_rate in &rates { let listed = format.sample_rates().is_none_or(|r| r.contains(&sample_rate)) && layout.channels() <= format.max_channels() && format.supports_layout(&layout); @@ -513,6 +517,21 @@ fn the_format_queries_agree_with_the_writer() { assert_eq!(format.supports_quality(), EncodeOptions::new(format).with_quality(0.5).check(48_000, 2).is_ok() && format.is_lossy()); assert_eq!(format.fixed_layouts(2).is_none(), matches!(format, EncodeFormat::Wav | EncodeFormat::Aiff | EncodeFormat::Flac)); } + // The most channels is the most: one more is refused, by the layouts of a format that has + // a fixed set and by the writer of one that has not. + let most: Vec = EncodeFormat::ALL.iter().map(|f| f.max_channels()).collect(); + assert_eq!(most, [32_767, 32_767, 8, 8, 8, 2, 6, 8]); + for &format in EncodeFormat::ALL { + let most = format.max_channels(); + match format.fixed_layouts(most) { + Some(layouts) => assert!(!layouts.is_empty() && format.fixed_layouts(most + 1).unwrap().is_empty(), "{format:?}"), + None => { + let opts = EncodeOptions::new(format).with_bit_depth(BitDepth::Int16); + assert!(opts.check(48_000, most).is_ok() && opts.check(48_000, most + 1).is_err(), "{format:?}"); + assert!(format.supports_layout(&ChannelLayout::unordered(most)) && !format.supports_layout(&ChannelLayout::unordered(most + 1))); + } + } + } assert_eq!(EncodeFormat::Ac3.fixed_layouts(3).unwrap().len(), 3); assert!(EncodeFormat::Aac.fixed_layouts(9).unwrap().is_empty()); } From 0e83ef6d5173be33fd78376922e49b699db501b2 Mon Sep 17 00:00:00 2001 From: pakiat <49967840+pakiat@users.noreply.github.com> Date: Sat, 14 Nov 2026 09:33:37 +0000 Subject: [PATCH 24/51] craft-docx: Thai text outside a complex-script run takes the run's own font and size, as in Word Moved from the DOCX part of storytold/wordcraft#6244. Runs are marked with what Word counts as complex script (the run, its paragraph style chain, its table style and the run defaults, not a character style). StyleSheet::table_cells_chr works out a table's cell run formatting once; ResolvedChar gains cs_off. Co-Authored-By: Claude Opus 5.5 --- crates/docx/src/read/story.rs | 2 + crates/docx/src/read/story/blocks.rs | 59 ++++++++++++++ crates/docx/tests/it/bidi.rs | 115 +++++++++++++++++++++++++++ crates/wordmodel/src/resolve.rs | 12 ++- crates/wordmodel/src/styles.rs | 36 +++++++++ 5 files changed, 222 insertions(+), 2 deletions(-) diff --git a/crates/docx/src/read/story.rs b/crates/docx/src/read/story.rs index 0550557f1..770375365 100644 --- a/crates/docx/src/read/story.rs +++ b/crates/docx/src/read/story.rs @@ -113,6 +113,8 @@ pub struct StoryCtx { pub story_depth: usize, /// Reading a header or footer (not a text box inside one): where Word keeps its watermark. pub in_hf: bool, + /// Reading a table cell's paragraphs (not a text box inside one). + in_cell: bool, } /// Paragraph content under construction. diff --git a/crates/docx/src/read/story/blocks.rs b/crates/docx/src/read/story/blocks.rs index e72f16bf6..8a378bce8 100644 --- a/crates/docx/src/read/story/blocks.rs +++ b/crates/docx/src/read/story/blocks.rs @@ -4,6 +4,45 @@ use super::{ placeholder_of, sectpr, tcpr, trpr, }; +/// Word draws a run's text with the complex-script font, size, bold and italic only when the run +/// is complex script or right to left (`w:cs`, `w:rtl`) by its own properties, its paragraph +/// style, its table style or the run defaults; a character style saying so, or saying not, +/// doesn't count (nor does its `w:rtl` change the order of the text). Anywhere else the text takes the run's other font and `w:sz`, Thai included, +/// whatever its language or `w:hint` (measured in Word for Windows: Thai text at `w:sz` 22 pt, +/// `w:szCs` 11 pt is drawn at 22 pt). WordCraft draws Thai, Lao and Indic characters with the +/// complex-script formatting unless the run says it is not complex script, and counts a character +/// style's `w:cs`; so a run it would draw otherwise says on itself whether it is complex script +/// (`w:cs`, which Word reads the same way). `table` is the run formatting the table style gives +/// the paragraph's cell. Runs with right-to-left text are left as they are: they are written +/// right to left. +fn mark_runs_as_word_draws_them(styles: &craft_wordmodel::StyleSheet, para: &mut Paragraph, table: Option<&CharProps>) { + use craft_wordmodel::bidi::{is_complex_script, is_rtl_script}; + let style = para.props.style.as_deref(); + let mut at = 0; + for run in &mut para.runs { + let text = para.text.get(at..at + run.len).unwrap_or(""); + at += run.len; + if text.is_empty() || text.chars().any(is_rtl_script) { + continue; + } + let word = styles.resolve_char_in(style, table, &CharProps { style: None, ..run.props.clone() }); + let mut ours = styles.resolve_char_in(style, table, &run.props); + // Right to left only by its character style: Word draws and orders the run as it does + // one that says nothing (measured, Latin and Thai text). + if ours.rtl && !word.rtl { + run.props.rtl = Some(false); + ours = styles.resolve_char_in(style, table, &run.props); + } + if word.cs || word.rtl { + if !ours.cs && !ours.rtl { + run.props.cs = Some(true); + } + } else if !ours.rtl && (ours.cs || (!ours.cs_off && text.chars().any(is_complex_script))) { + run.props.cs = Some(false); + } + } +} + impl Reader<'_> { /// Read a story's blocks from a container element (`w:body`, `w:hdr`, `w:tc`, `w:txbxContent`…). pub fn read_blocks(&mut self, sc: &mut StoryCtx, parent: &El, rels: &Rels, out: &mut Blocks, depth: usize) { @@ -276,6 +315,10 @@ impl Reader<'_> { if sc.fields.iter().any(|f| f.phase == Phase::Instr) && para.plain_text().is_empty() { para.mark.hidden = Some(true); } + // A cell's paragraphs are marked once their table is read: its style counts. + if !sc.in_cell { + mark_runs_as_word_draws_them(&self.doc.styles, &mut para, None); + } para.normalize(); para } @@ -355,8 +398,10 @@ impl Reader<'_> { continue; } let mut blocks = Blocks::new(); + let outer = std::mem::replace(&mut sc.in_cell, true); self.read_blocks(sc, tc, rels, &mut blocks, depth + 4); self.flush_pending(sc, &mut blocks); + sc.in_cell = outer; row.cells.push(Cell { props, blocks, controls: cell_controls }); } if !row.cells.is_empty() { @@ -370,6 +415,20 @@ impl Reader<'_> { let cols = table.cols().clamp(1, MAX_COLS); table.grid = vec![72.0; cols]; } + // The cells' paragraphs, with the run formatting the table style gives each cell (a + // table inside has marked its own). + let chrs = self.doc.styles.table_cells_chr(&table); + for (ri, row) in table.rows.iter_mut().enumerate() { + for (ci, cell) in row.cells.iter_mut().enumerate() { + let chr = chrs.as_ref().and_then(|c| c.get(ri)?.get(ci)); + for b in &mut cell.blocks { + if let Block::Para(p) = Arc::make_mut(b) { + mark_runs_as_word_draws_them(&self.doc.styles, p, chr); + p.normalize(); + } + } + } + } Some(table) } } diff --git a/crates/docx/tests/it/bidi.rs b/crates/docx/tests/it/bidi.rs index 3df1c04c9..6dae963aa 100644 --- a/crates/docx/tests/it/bidi.rs +++ b/crates/docx/tests/it/bidi.rs @@ -175,3 +175,118 @@ fn rtl_tables_and_sections_round_trip() { assert_eq!(again, vec![true, false]); assert!(r.last_section.rtl && r.last_section.columns.count == 2); } + +/// A package whose body is `body` and whose styles part holds `styles`. +fn docx_with_styles(body: &str, styles: &str) -> Vec { + let ns = r#"xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main""#; + let root = r#""#; + let rels = r#""#; + let doc = format!(r#"{body}"#); + let st = format!(r#"{styles}"#); + zip(&[ + ("_rels/.rels", root.as_bytes()), + ("word/_rels/document.xml.rels", rels.as_bytes()), + ("word/document.xml", doc.as_bytes()), + ("word/styles.xml", st.as_bytes()), + ]) +} + +/// Thai text draws in the complex-script formatting only where Word draws it so (measured in Word +/// for Windows; run defaults Angsana New 22 pt, complex script Tahoma 11 pt bold). Without +/// `w:cs` or `w:rtl` on the run, its paragraph style or the run defaults, Thai text measures as +/// Angsana New 22 pt, whatever its language, `w:hint` or character style. +#[test] +fn thai_text_takes_the_complex_script_formatting_only_in_a_complex_script_run() { + let thai = "ทดสอบ ภาษาไทย"; + let defaults = |extra: &str| { + format!( + r#"{extra} + + + + + + +"# + ) + }; + let latin = ("Angsana New", 22.0, false); + let complex = ("Tahoma", 11.0, true); + let run = |rpr: &str| format!(r#"{rpr}{thai}"#); + let styled = |p: &str, rpr: &str| { + format!(r#"{rpr}{thai}"#) + }; + let in_table = |style: &str| { + format!( + r#"{}"#, + run("") + ) + }; + let cs_off = r#""#; + let cases: Vec<(&str, String, String, (&str, f32, bool))> = vec![ + ("plain", defaults(""), run(""), latin), + ("bidi language", defaults(""), run(r#""#), latin), + ("hint", defaults(""), run(r#""#), latin), + ("character style", defaults(""), run(r#""#), latin), + ("character style rtl", defaults(""), run(r#""#), latin), + ("run cs", defaults(""), run(""), complex), + ("run rtl", defaults(""), run(""), complex), + ("paragraph style", defaults(""), styled("CsPara", ""), complex), + ("paragraph style, run cs off", defaults(""), styled("CsPara", r#""#), latin), + ("run defaults", defaults(""), run(""), complex), + // A character style's `w:cs w:val="0"` doesn't turn the paragraph style's or the run + // defaults' off either. + ("paragraph style, character style cs off", defaults(""), styled("CsPara", cs_off), complex), + ("run defaults, character style cs off", defaults(""), run(cs_off), complex), + // A table style's `w:cs` counts, and its sizes are the run's. + ("table style", defaults(""), in_table("CsTable"), complex), + ("table style sizes", defaults(""), in_table("SizeTable"), ("Angsana New", 15.0, false)), + ]; + let check = |d: &Document, name: &str, want: (&str, f32, bool), when: &str| { + let (p, table) = match &*d.body[0] { + craft_wordmodel::Block::Table(t) => { + (t.rows[0].cells[0].blocks[0].as_para().unwrap(), d.styles.table_cells_chr(t).map(|c| c[0][0].clone())) + } + b => (b.as_para().unwrap(), None), + }; + let rc = d.styles.resolve_char_in(p.props.style.as_deref(), table.as_ref(), &p.runs[0].props); + for ch in p.text.chars() { + let drawn = if rc.uses_complex(ch) { rc.complex() } else { rc.clone() }; + assert_eq!((drawn.font.as_str(), drawn.size, drawn.bold), want, "{name} {when}: {ch:?}"); + } + let c = &p.runs[0].props; + assert_eq!((c.font_cs.as_deref(), c.size_cs, c.bold_cs), (None, None, None), "{name} {when}: nothing is pinned"); + }; + for (name, styles, body, want) in &cases { + let d = craft_docx::read(&docx_with_styles(body, styles)).unwrap(); + check(&d, name, *want, "read"); + let again = craft_docx::read(&craft_docx::write(&d).unwrap()).unwrap(); + check(&again, name, *want, "after a save"); + } + // Latin text and right-to-left text are left as they were. + let body = r#"Latin onlyسلام"#; + let d = craft_docx::read(&docx_with_styles(body, &defaults(""))).unwrap(); + for p in paras(&d) { + assert_eq!(p.runs[0].props.cs, None, "{}", p.text); + } + // Latin text follows the same rule (measured): a character style's `w:cs` or `w:rtl` leaves it in the + // run's own formatting, a character style's `w:cs w:val="0"` under a paragraph style's + // `w:cs` in the complex-script formatting. + let latin_in = + |p: &str, rpr: &str| format!(r#"{rpr}Latin"#); + let body = + latin_in("Normal", r#""#) + &latin_in("CsPara", cs_off) + &latin_in("Normal", r#""#); + let d = craft_docx::read(&docx_with_styles(&body, &defaults(""))).unwrap(); + let again = craft_docx::read(&craft_docx::write(&d).unwrap()).unwrap(); + for (d, when) in [(&d, "read"), (&again, "after a save")] { + let drawn: Vec<_> = paras(d) + .iter() + .map(|p| { + let rc = d.styles.resolve_char(p.props.style.as_deref(), &p.runs[0].props); + let c = if rc.uses_complex('L') { rc.complex() } else { rc }; + (c.font, c.size) + }) + .collect(); + assert_eq!(drawn, [("Angsana New".to_string(), 22.0), ("Tahoma".to_string(), 11.0), ("Angsana New".to_string(), 22.0)], "{when}"); + } +} diff --git a/crates/wordmodel/src/resolve.rs b/crates/wordmodel/src/resolve.rs index 40449e82c..7ef12ccdc 100644 --- a/crates/wordmodel/src/resolve.rs +++ b/crates/wordmodel/src/resolve.rs @@ -66,6 +66,11 @@ pub struct ResolvedChar { pub rtl: bool, /// The whole run uses the complex-script properties (`w:cs`). pub cs: bool, + /// The run says it is not complex script (`w:cs w:val="0"`): its Thai, Indic, Arabic or + /// Hebrew characters take its other font, size, bold and italic, as Word draws them in a run + /// that isn't complex script or right to left. + #[serde(default, skip_serializing_if = "std::ops::Not::not")] + pub cs_off: bool, /// Complex-script font, size, bold and italic (Arabic, Persian, Hebrew… text). pub font_cs: String, /// East Asian font (Chinese, Japanese and Korean text), when one is set. @@ -115,6 +120,7 @@ impl ResolvedChar { lang: c.lang.clone(), rtl: c.rtl.unwrap_or(false), cs: c.cs.unwrap_or(false), + cs_off: c.cs == Some(false), font_cs: c.font_cs.clone().or_else(|| c.font.clone()).unwrap_or_else(|| crate::styles::BODY_FONT.to_string()), font_ea: c.font_ea.clone(), size_cs: c.size_cs.or(c.size).unwrap_or(crate::props::DEFAULT_FONT_SIZE).clamp(1.0, 1638.0), @@ -133,9 +139,11 @@ impl ResolvedChar { pub fn kerned(&self) -> bool { self.kern > 0.0 && self.size >= self.kern } - /// Does a character of this run use the complex-script properties? + /// Does a character of this run use the complex-script properties? Every character of a + /// right-to-left or complex-script run does; otherwise a complex-script character does, + /// unless the run says it is not complex script. pub fn uses_complex(&self, c: char) -> bool { - self.rtl || self.cs || crate::bidi::is_complex_script(c) + self.rtl || self.cs || (!self.cs_off && crate::bidi::is_complex_script(c)) } /// The size glyphs are drawn and measured at. Word sets superscript and subscript text at /// 0.65 of the run's size rounded to the half point, a font size the format can store diff --git a/crates/wordmodel/src/styles.rs b/crates/wordmodel/src/styles.rs index 5383c1510..eea1659c2 100644 --- a/crates/wordmodel/src/styles.rs +++ b/crates/wordmodel/src/styles.rs @@ -828,6 +828,42 @@ impl StyleSheet { out.chr.style = None; Some(out) } + /// The run formatting `t`'s table style gives the text of each of its cells, by row and then + /// cell: each of a cell's parts' over the last, lowest precedence first (ECMA-376 §17.7.6), as + /// layout applies it between document defaults and the paragraph's style. `None` when the + /// table has no style. The style and the table's size are worked out once for the whole table, + /// and each set of parts is put together once. + pub fn table_cells_chr(&self, t: &crate::table::Table) -> Option>> { + let st = self.table_style(t.props.style.as_deref()?)?; + let sizes = (st.parts.band_size.unwrap_or(0), st.parts.col_band_size.unwrap_or(0)); + let ncols = t.cols().clamp(1, crate::table::MAX_COLS); + let nrows = t.rows.len(); + let mut made: Vec<(PartSet, CharProps)> = Vec::new(); + let mut out = Vec::with_capacity(nrows); + for (r, row) in t.rows.iter().enumerate() { + let mut g = row.first_grid(); + let mut cells = Vec::with_capacity(row.cells.len()); + for cell in &row.cells { + let span = cell.span(); + let parts = PartSet::of_cell(&t.props.look, sizes, (r, nrows), (g, span, ncols)); + g = g.saturating_add(span); + let chr = match made.iter().find(|(p, _)| *p == parts) { + Some((_, chr)) => chr.clone(), + None => { + let mut chr = CharProps::default(); + for part in parts.iter() { + chr.overlay(&st.part(part).chr); + } + made.push((parts, chr.clone())); + chr + } + }; + cells.push(chr); + } + out.push(cells); + } + Some(out) + } /// Add or replace a style. pub fn upsert(&mut self, st: Style) { match self.styles.iter_mut().find(|s| s.id == st.id) { From 82e3341018c65aeb1370cb6b6411148e69c96676 Mon Sep 17 00:00:00 2001 From: Bra1nZ <95569966+Bra1nZ@users.noreply.github.com> Date: Sat, 14 Nov 2026 12:55:59 +0300 Subject: [PATCH 25/51] fix(print): match the requested paper identity among partial records and resolve parameter references Two review findings on #1225: A partial paper record was accepted as a candidate of last resort on its known side alone, so a partial Letter and a partial Legal sharing a width both agreed with a Legal request and the first one in the driver's order won - the ticket could select Letter while the layout assumed Legal. Partial candidates now resolve ambiguity the way full ones do: one whose name matches the requested standard sheet wins; an ambiguity that leaves more than one (or none) is not resolved and nothing is selected. integer() read only a direct Value, so a paper dimension supplied through a ParameterRef read as missing and the fallback silently substituted the requested size for a ticket that named a different one. The resolution logic the driver's ticket reader already had moves into a shared resolved_value() helper, and integer() uses it: a referenced dimension now either agrees or refuses. --- crates/print/src/ticket.rs | 141 +++++++++++++++++++++++++++++-------- 1 file changed, 113 insertions(+), 28 deletions(-) diff --git a/crates/print/src/ticket.rs b/crates/print/src/ticket.rs index 55a9c50ae..8e1171f71 100644 --- a/crates/print/src/ticket.rs +++ b/crates/print/src/ticket.rs @@ -222,7 +222,10 @@ pub(crate) struct Paper<'a> { /// An entry the driver keeps only one side of (the other reads zero, a legacy host-based driver's /// DEVMODE metric, storytold/craft-libs#7230) is a candidate of last resort (INV-4): only when no /// full entry matched, only a Print Schema keyword entry, and only while its known side agrees -/// with the sheet, either way round. +/// with the sheet, either way round. Several such entries that all agree (a Letter and a Legal +/// option share a width) are told apart by name, as full candidates are: the one named like the +/// requested standard sheet wins, and when that leaves more than one, or none, nothing is chosen — +/// a guess here would lay the sheets out for the wrong paper. pub(crate) fn matching_paper(papers: &[Paper<'_>], width: f64, height: f64) -> Option { let (w, h) = (micrometres(width.min(height))?, micrometres(width.max(height))?); let names = paper_names(width, height); @@ -240,9 +243,23 @@ pub(crate) fn matching_paper(papers: &[Paper<'_>], width: f64, height: f64) -> O return Some(index); } let agrees = |side: u32| side.abs_diff(w) <= PAPER_TOLERANCE || side.abs_diff(h) <= PAPER_TOLERANCE; - papers + let partials: Vec = papers .iter() - .position(|p| p.keyword && (p.width == 0) != (p.height == 0) && (p.width == 0 || agrees(p.width)) && (p.height == 0 || agrees(p.height))) + .enumerate() + .filter(|(_, p)| p.keyword && (p.width == 0) != (p.height == 0) && (p.width == 0 || agrees(p.width)) && (p.height == 0 || agrees(p.height))) + .map(|(i, _)| i) + .collect(); + match partials.as_slice() { + [only] => Some(*only), + // Ambiguous by agreement alone: a partial named like the requested standard sheet wins. + _ => { + let named: Vec = partials.iter().copied().filter(|i| names.iter().any(|n| names_paper(papers[*i].name, n))).collect(); + match named.as_slice() { + [only] => Some(*only), + _ => None, + } + } + } } fn named(node: roxmltree::Node<'_, '_>, local: &str) -> bool { @@ -285,12 +302,32 @@ pub(crate) fn two_sided(xml: &str) -> Option { ) } -/// The integer value of the Print Schema element under `node` with this keyword name. -fn integer(node: roxmltree::Node<'_, '_>, tag: &str, name: &str) -> Option { +/// The `Value` of the Print Schema element `element`: its own, or one a `ParameterRef` names +/// through the `ParameterInit` under the document's root that sets it (a driver may keep a paper +/// side or a resolution this way). `None` when the element has neither, or names a parameter the +/// ticket does not set. +fn resolved_value<'a>(document: &'a roxmltree::Document<'a>, element: roxmltree::Node<'a, 'a>) -> Option> { + let value = element.children().find(|v| v.has_tag_name((NS_PSF, "Value")) || v.has_tag_name((NS_PSF, "ParameterRef")))?; + if value.has_tag_name((NS_PSF, "Value")) { + return Some(value); + } + let parameter = expanded(value, value.attribute("name")?); + document + .root_element() + .children() + .filter(|p| p.has_tag_name((NS_PSF, "ParameterInit"))) + .find(|p| p.attribute("name").is_some_and(|name| expanded(*p, name) == parameter))? + .children() + .find(|v| v.has_tag_name((NS_PSF, "Value"))) +} + +/// The integer value of the Print Schema element under `node` with this keyword name, direct or +/// through a `ParameterRef` the ticket resolves ([`resolved_value`]). +fn integer(document: &roxmltree::Document<'_>, node: roxmltree::Node<'_, '_>, tag: &str, name: &str) -> Option { node.descendants() .find(|n| n.has_tag_name((NS_PSF, tag)) && named(*n, name)) - .and_then(|n| n.children().find(|v| v.has_tag_name((NS_PSF, "Value")))) - .and_then(|n| n.text()) + .and_then(|element| resolved_value(document, element)) + .and_then(|value| value.text()) .and_then(|v| v.trim().parse::().ok()) } @@ -310,8 +347,8 @@ pub(crate) fn verify_ticket(xml: &str, paper: Option<(u32, u32)>, landscape: boo let document = crate::xml::parse(xml).map_err(spool_error)?; let feature = |name: &str| document.root_element().children().find(|n| n.has_tag_name((NS_PSF, "Feature")) && named(*n, name)); let media = feature("PageMediaSize").ok_or_else(|| spool_error("the printer's driver did not confirm the paper size; nothing was sent"))?; - let width = integer(media, "ScoredProperty", "MediaSizeWidth").filter(|w| *w > 0); - let height = integer(media, "ScoredProperty", "MediaSizeHeight").filter(|h| *h > 0); + let width = integer(&document, media, "ScoredProperty", "MediaSizeWidth").filter(|w| *w > 0); + let height = integer(&document, media, "ScoredProperty", "MediaSizeHeight").filter(|h| *h > 0); let without_a_size = spool_error("the printer's driver gave a paper without a size (a roll?); nothing was sent"); let size = match (width, height, paper) { (Some(w), Some(h), _) => (w, h), @@ -416,7 +453,9 @@ pub(crate) fn one_job_sides(xml: &str) -> Option { _ => return None, } } - if features(&["JobNUpAllDocumentsContiguously", "DocumentNUp"]).any(|f| integer(f, "ScoredProperty", "PagesPerSheet").is_some_and(|n| n > 1)) { + if features(&["JobNUpAllDocumentsContiguously", "DocumentNUp"]) + .any(|f| integer(&document, f, "ScoredProperty", "PagesPerSheet").is_some_and(|n| n > 1)) + { return None; } if features(&["JobBindAllDocuments", "DocumentBinding", "JobStapleAllDocuments", "DocumentStaple"]) @@ -453,7 +492,7 @@ pub(crate) fn verify_job_options(xml: &str, job: &Job, pages: usize, offered: Of }; let refused = |field: &str| spool_error(format!("the printer's driver did not retain the requested {field}; nothing was sent")); let copies = job.copies.clamp(1, 999); - if integer(root, "ParameterInit", "JobCopiesAllDocuments") != Some(copies) { + if integer(&document, root, "ParameterInit", "JobCopiesAllDocuments") != Some(copies) { return Err(refused("copy count")); } if copies > 1 && pages > 1 && !option("DocumentCollate").is_some_and(|n| named(n, if job.collate { "Collated" } else { "Uncollated" })) { @@ -529,19 +568,7 @@ fn feature_option(document: &roxmltree::Document<'_>, feature: &str) -> Option value, - reference => { - let parameter = expanded(reference, reference.attribute("name")?); - document - .root_element() - .children() - .filter(|p| p.has_tag_name((NS_PSF, "ParameterInit"))) - .find(|p| p.attribute("name").is_some_and(|name| expanded(*p, name) == parameter))? - .children() - .find(|v| v.has_tag_name((NS_PSF, "Value")))? - } - }; + let value = resolved_value(document, n)?; let text = value.text()?.trim(); let value = match text.parse::() { _ if is_qname_value(value) => expanded(value, text), @@ -798,11 +825,11 @@ pub(crate) fn prefixes_unlike_the_drivers(ticket: &str, driver: &str) -> Option< pub(crate) fn imageable_margin(capabilities_xml: &str) -> Option { let document = crate::xml::parse(capabilities_xml).ok()?; let imageable = document.root_element().children().find(|n| n.has_tag_name((NS_PSF, "Property")) && named(*n, "PageImageableSize"))?; - let width = integer(imageable, "Property", "ImageableSizeWidth")?; - let height = integer(imageable, "Property", "ImageableSizeHeight")?; + let width = integer(&document, imageable, "Property", "ImageableSizeWidth")?; + let height = integer(&document, imageable, "Property", "ImageableSizeHeight")?; let area = imageable.children().find(|n| n.has_tag_name((NS_PSF, "Property")) && named(*n, "ImageableArea"))?; - let (x, y) = (integer(area, "Property", "OriginWidth")?, integer(area, "Property", "OriginHeight")?); - let (w, h) = (integer(area, "Property", "ExtentWidth")?, integer(area, "Property", "ExtentHeight")?); + let (x, y) = (integer(&document, area, "Property", "OriginWidth")?, integer(&document, area, "Property", "OriginHeight")?); + let (w, h) = (integer(&document, area, "Property", "ExtentWidth")?, integer(&document, area, "Property", "ExtentHeight")?); let right = width.checked_sub(x)?.checked_sub(w)?; let bottom = height.checked_sub(y)?.checked_sub(h)?; Some(x.max(y).max(right).max(bottom)) @@ -1139,6 +1166,40 @@ mod tests { } } + /// A validated ticket whose width the option refers to a parameter the ticket sets + /// (`MediaSizeWidth` a `ParameterRef`, storytold/craft-libs#1225), as a driver writes one. + fn validated_referenced(width: u32, height: u32) -> String { + format!( + r#" +{width} + + +{height} + + + +"# + ) + } + + /// A paper side a driver keeps in a `ParameterRef` is resolved through the `ParameterInit` + /// the ticket sets, and checked like a direct one: a referenced width that disagrees with the + /// sheet the request names is refused, one that agrees is taken. + #[test] + fn a_referenced_paper_side_is_resolved_through_the_parameter_it_names() { + let a4 = (210_000, 297_000); + assert_eq!(verify_ticket(&validated_referenced(210_000, 297_000), Some(a4), false), Ok(a4)); + assert_eq!(verify_ticket(&validated_referenced(209_750, 297_000), Some(a4), false), Ok((209_750, 297_000)), "exactly the tolerance"); + // A referenced size that disagrees is refused, not rewritten from the request. + let changed = verify_ticket(&validated_referenced(400_000, 297_000), Some(a4), false).unwrap_err(); + assert!(changed.to_string().contains("changed the paper size"), "{changed}"); + // A reference to a parameter the ticket does not set is a missing side, which falls back + // to the requested paper like any unreadable one. + let unset = + validated_referenced(400_000, 297_000).replace(r#"name="psk:PageMediaSizeWidth"> Date: Sat, 14 Nov 2026 13:16:41 +0300 Subject: [PATCH 26/51] fix(print): reject a partial record whose known name contradicts the sheet A review finding on #1225: a single agreeing partial record was taken on its known side alone, so a Legal request could take a keyword entry named Letter reporting (215_900, 0) - the ticket then selects Letter while the layout assumes Legal. A single partial record now refuses when its known name doesn't match the requested standard sheet; an unnamed one is still taken on agreement alone. The name check exposed names_paper accepting a word modifier as a dimension: "A4 Extra" matched "A4" because the suffix rule only looked at the first character, a space. The rule now reads the word after the separator: a letter is a modifier ("A4 Extra" is another paper), a digit is the sheet's dimensions ("A4 210 x 297 mm"), a digit or letter right against the name is a different name ("ARCH E1", "A4Extra"). --- crates/print/src/ticket.rs | 69 +++++++++++++++++++++++++++++++++----- 1 file changed, 60 insertions(+), 9 deletions(-) diff --git a/crates/print/src/ticket.rs b/crates/print/src/ticket.rs index 8e1171f71..e6224df69 100644 --- a/crates/print/src/ticket.rs +++ b/crates/print/src/ticket.rs @@ -197,11 +197,24 @@ pub(crate) fn paper_names(width: f64, height: f64) -> &'static [&'static str] { } /// Whether a driver's paper name is `name`: it starts with it, ignoring case, and the name ends -/// there ("A4 210 x 297 mm", not "A4 Extra" for "A4" or "ARCH E1" for "ARCH E"). +/// there — either nothing follows ("arch d"), or a separator and the sheet's dimensions ("A4 +/// 210 x 297 mm"). After a separator, dimensions are a digit: a word is a modifier, another +/// paper ("A4 Extra", "A4 (Extra)"), and anything joined to the name without a separator is +/// another paper too ("A4Extra", "ARCH E1" for "ARCH E"). pub(crate) fn names_paper(display: Option<&str>, name: &str) -> bool { let Some(display) = display else { return false }; - display.get(..name.len()).is_some_and(|start| start.eq_ignore_ascii_case(name)) - && display.get(name.len()..).is_some_and(|rest| rest.chars().next().is_none_or(|c| !c.is_alphanumeric())) + let Some(rest) = display.get(name.len()..) else { return false }; + if !display.get(..name.len()).is_some_and(|start| start.eq_ignore_ascii_case(name)) { + return false; + } + let after = rest.trim_start_matches(|c: char| !c.is_alphanumeric()); + match after.chars().next() { + // The name ends here, or a separator introduces the sheet's dimensions. + None => true, + Some(c) if !c.is_alphabetic() => after.len() < rest.len(), + // A word, directly after the name or after a separator, is a modifier: another paper. + Some(_) => false, + } } /// A driver paper offered for the job: its size in micrometres (as the driver lists it), its @@ -222,10 +235,13 @@ pub(crate) struct Paper<'a> { /// An entry the driver keeps only one side of (the other reads zero, a legacy host-based driver's /// DEVMODE metric, storytold/craft-libs#7230) is a candidate of last resort (INV-4): only when no /// full entry matched, only a Print Schema keyword entry, and only while its known side agrees -/// with the sheet, either way round. Several such entries that all agree (a Letter and a Legal -/// option share a width) are told apart by name, as full candidates are: the one named like the -/// requested standard sheet wins, and when that leaves more than one, or none, nothing is chosen — -/// a guess here would lay the sheets out for the wrong paper. +/// with the sheet, either way round. A single such entry is still refused when its own name is +/// known and contradicts the requested standard sheet (INV-4): a known conflicting name is +/// evidence against the choice, and failing closed is safer than a guess. Without a name there is +/// nothing contradicting, so the agreement alone is enough. Several such entries that all agree +/// (a Letter and a Legal option share a width) are told apart by name, as full candidates are: +/// the one named like the requested standard sheet wins, and when that leaves more than one, or +/// none, nothing is chosen — a guess here would lay the sheets out for the wrong paper. pub(crate) fn matching_paper(papers: &[Paper<'_>], width: f64, height: f64) -> Option { let (w, h) = (micrometres(width.min(height))?, micrometres(width.max(height))?); let names = paper_names(width, height); @@ -250,7 +266,13 @@ pub(crate) fn matching_paper(papers: &[Paper<'_>], width: f64, height: f64) -> O .map(|(i, _)| i) .collect(); match partials.as_slice() { - [only] => Some(*only), + [only] => { + // INV-4: a known name that contradicts the requested standard sheet is evidence + // against this single partial record — refuse it; without a name, the known side's + // agreement is all the evidence there is, and the record stands. + let contradicts = papers[*only].name.is_some_and(|name| !names.iter().any(|n| names_paper(Some(name), n))); + (!contradicts).then_some(*only) + } // Ambiguous by agreement alone: a partial named like the requested standard sheet wins. _ => { let named: Vec = partials.iter().copied().filter(|i| names.iter().any(|n| names_paper(papers[*i].name, n))).collect(); @@ -1686,6 +1708,10 @@ mod tests { assert!(!names_paper(Some("ANSI D"), "ARCH D")); assert!(!names_paper(Some("ARCH E1"), "ARCH E")); assert!(!names_paper(Some("A4Extra"), "A4")); + // storytold/craft-libs#1225: a word after a separator is a modifier, not dimensions. + assert!(!names_paper(Some("A4 Extra"), "A4")); + assert!(!names_paper(Some("A4 (Extra)"), "A4")); + assert!(names_paper(Some("A4 210 x 297 mm"), "A4")); assert!(!names_paper(Some("Ä"), "A4"), "never slices inside a character"); assert!(!names_paper(None, "A4")); } @@ -1711,12 +1737,37 @@ mod tests { } /// One partial paper whose known side agrees is still taken, named like the requested - /// standard sheet or not. + /// standard sheet or not. The known side agrees only to a quarter of a millimetre: exactly + /// the tolerance is taken, one micrometre past it is another paper. #[test] fn a_single_partially_known_paper_that_agrees_is_still_taken() { let paper = |width, height, name, keyword| Paper { width, height, name, keyword }; assert_eq!(matching_paper(&[paper(215_900, 0, Some("Legal 215.9 x 355.6 mm"), true)], 612.0, 1008.0), Some(0), "named like the sheet"); assert_eq!(matching_paper(&[paper(215_900, 0, None, true)], 612.0, 1008.0), Some(0), "or without a name at all"); + assert_eq!(matching_paper(&[paper(0, 297_250, None, true)], 595.28, 841.89), Some(0), "exactly the tolerance"); + assert_eq!(matching_paper(&[paper(0, 297_251, None, true)], 595.28, 841.89), None, "one µm past the tolerance"); + } + + /// storytold/craft-libs#1225 (Code Rabbit, second round): a single partial paper whose known + /// side agrees is still refused when its own name is known and contradicts the requested + /// standard sheet — the width the driver kept is shared by Letter and Legal, and a known + /// Letter name is evidence against choosing it for a Legal sheet (INV-4). "Extra" is a + /// modifier word, another paper: a known "Letter Extra" name contradicts a Letter sheet too. + /// Without a name there is nothing contradicting, and the agreeing entry is taken as before. + #[test] + fn a_single_partially_known_paper_whose_known_name_contradicts_the_sheet_is_refused() { + let paper = |width, height, name, keyword| Paper { width, height, name, keyword }; + assert_eq!( + matching_paper(&[paper(215_900, 0, Some("Letter 215.9 x 279.4 mm"), true)], 612.0, 1008.0), + None, + "a known Letter name is not a Legal sheet" + ); + assert_eq!( + matching_paper(&[paper(215_900, 0, Some("Letter Extra 215.9 x 431.8 mm"), true)], 612.0, 792.0), + None, + "a known \"Letter Extra\" name is not a Letter sheet" + ); + assert_eq!(matching_paper(&[paper(215_900, 0, None, true)], 612.0, 1008.0), Some(0), "an unnamed twin stands, the agreement alone"); } /// storytold/craft-libs#1225: two partial papers that both agree (Letter and Legal share a From 24907cbd7a0d96fe90be6921286036a140c4655c Mon Sep 17 00:00:00 2001 From: pakiat <49967840+pakiat@users.noreply.github.com> Date: Sat, 14 Nov 2026 10:41:38 +0000 Subject: [PATCH 27/51] craft-wordmodel: mark runs as Word draws them in the model, for every reader StyleSheet::mark_runs_as_word_draws_them moves from the DOCX reader into the model, unchanged, so the .doc reader can apply the same rule. Co-Authored-By: Claude Opus 5.5 --- crates/docx/src/read/story/blocks.rs | 43 ++-------------------------- crates/wordmodel/src/styles.rs | 38 ++++++++++++++++++++++++ 2 files changed, 40 insertions(+), 41 deletions(-) diff --git a/crates/docx/src/read/story/blocks.rs b/crates/docx/src/read/story/blocks.rs index 8a378bce8..5d7d3711e 100644 --- a/crates/docx/src/read/story/blocks.rs +++ b/crates/docx/src/read/story/blocks.rs @@ -4,45 +4,6 @@ use super::{ placeholder_of, sectpr, tcpr, trpr, }; -/// Word draws a run's text with the complex-script font, size, bold and italic only when the run -/// is complex script or right to left (`w:cs`, `w:rtl`) by its own properties, its paragraph -/// style, its table style or the run defaults; a character style saying so, or saying not, -/// doesn't count (nor does its `w:rtl` change the order of the text). Anywhere else the text takes the run's other font and `w:sz`, Thai included, -/// whatever its language or `w:hint` (measured in Word for Windows: Thai text at `w:sz` 22 pt, -/// `w:szCs` 11 pt is drawn at 22 pt). WordCraft draws Thai, Lao and Indic characters with the -/// complex-script formatting unless the run says it is not complex script, and counts a character -/// style's `w:cs`; so a run it would draw otherwise says on itself whether it is complex script -/// (`w:cs`, which Word reads the same way). `table` is the run formatting the table style gives -/// the paragraph's cell. Runs with right-to-left text are left as they are: they are written -/// right to left. -fn mark_runs_as_word_draws_them(styles: &craft_wordmodel::StyleSheet, para: &mut Paragraph, table: Option<&CharProps>) { - use craft_wordmodel::bidi::{is_complex_script, is_rtl_script}; - let style = para.props.style.as_deref(); - let mut at = 0; - for run in &mut para.runs { - let text = para.text.get(at..at + run.len).unwrap_or(""); - at += run.len; - if text.is_empty() || text.chars().any(is_rtl_script) { - continue; - } - let word = styles.resolve_char_in(style, table, &CharProps { style: None, ..run.props.clone() }); - let mut ours = styles.resolve_char_in(style, table, &run.props); - // Right to left only by its character style: Word draws and orders the run as it does - // one that says nothing (measured, Latin and Thai text). - if ours.rtl && !word.rtl { - run.props.rtl = Some(false); - ours = styles.resolve_char_in(style, table, &run.props); - } - if word.cs || word.rtl { - if !ours.cs && !ours.rtl { - run.props.cs = Some(true); - } - } else if !ours.rtl && (ours.cs || (!ours.cs_off && text.chars().any(is_complex_script))) { - run.props.cs = Some(false); - } - } -} - impl Reader<'_> { /// Read a story's blocks from a container element (`w:body`, `w:hdr`, `w:tc`, `w:txbxContent`…). pub fn read_blocks(&mut self, sc: &mut StoryCtx, parent: &El, rels: &Rels, out: &mut Blocks, depth: usize) { @@ -317,7 +278,7 @@ impl Reader<'_> { } // A cell's paragraphs are marked once their table is read: its style counts. if !sc.in_cell { - mark_runs_as_word_draws_them(&self.doc.styles, &mut para, None); + self.doc.styles.mark_runs_as_word_draws_them(&mut para, None); } para.normalize(); para @@ -423,7 +384,7 @@ impl Reader<'_> { let chr = chrs.as_ref().and_then(|c| c.get(ri)?.get(ci)); for b in &mut cell.blocks { if let Block::Para(p) = Arc::make_mut(b) { - mark_runs_as_word_draws_them(&self.doc.styles, p, chr); + self.doc.styles.mark_runs_as_word_draws_them(p, chr); p.normalize(); } } diff --git a/crates/wordmodel/src/styles.rs b/crates/wordmodel/src/styles.rs index eea1659c2..81d8cd272 100644 --- a/crates/wordmodel/src/styles.rs +++ b/crates/wordmodel/src/styles.rs @@ -828,6 +828,44 @@ impl StyleSheet { out.chr.style = None; Some(out) } + /// Word draws a run's text with the complex-script font, size, bold and italic only when the run + /// is complex script or right to left (`w:cs`, `w:rtl`) by its own properties, its paragraph + /// style, its table style or the run defaults; a character style saying so, or saying not, + /// doesn't count (nor does its `w:rtl` change the order of the text). Anywhere else the text takes the run's other font and `w:sz`, Thai included, + /// whatever its language or `w:hint` (measured in Word for Windows: Thai text at `w:sz` 22 pt, + /// `w:szCs` 11 pt is drawn at 22 pt), and the same in a `.doc`. WordCraft draws Thai, Lao and Indic characters with the + /// complex-script formatting unless the run says it is not complex script, and counts a character + /// style's `w:cs`; so a run it would draw otherwise says on itself whether it is complex script + /// (`w:cs`, which Word reads the same way). A reader calls this on each paragraph it has read. `table` is the run formatting the table style gives + /// the paragraph's cell. Runs with right-to-left text are left as they are: they are written + /// right to left. + pub fn mark_runs_as_word_draws_them(&self, para: &mut crate::para::Paragraph, table: Option<&CharProps>) { + use crate::bidi::{is_complex_script, is_rtl_script}; + let style = para.props.style.as_deref(); + let mut at = 0; + for run in &mut para.runs { + let text = para.text.get(at..at + run.len).unwrap_or(""); + at += run.len; + if text.is_empty() || text.chars().any(is_rtl_script) { + continue; + } + let word = self.resolve_char_in(style, table, &CharProps { style: None, ..run.props.clone() }); + let mut ours = self.resolve_char_in(style, table, &run.props); + // Right to left only by its character style: Word draws and orders the run as it does + // one that says nothing (measured, Latin and Thai text). + if ours.rtl && !word.rtl { + run.props.rtl = Some(false); + ours = self.resolve_char_in(style, table, &run.props); + } + if word.cs || word.rtl { + if !ours.cs && !ours.rtl { + run.props.cs = Some(true); + } + } else if !ours.rtl && (ours.cs || (!ours.cs_off && text.chars().any(is_complex_script))) { + run.props.cs = Some(false); + } + } + } /// The run formatting `t`'s table style gives the text of each of its cells, by row and then /// cell: each of a cell's parts' over the last, lowest precedence first (ECMA-376 §17.7.6), as /// layout applies it between document defaults and the paragraph's style. `None` when the From a2722537fc060aacdd8b2bd461f78bbd5f6cb6e5 Mon Sep 17 00:00:00 2001 From: Trevor Brown Date: Sat, 14 Nov 2026 06:43:36 -0500 Subject: [PATCH 28/51] image-codecs: the web JPEG encoder trims or leaves out an XMP packet past one segment encode_jpeg_rgb8 wrote the XMP packet straight into an APP1 segment, so a packet past the limit failed the whole encode. It now builds the segment with the shared jpeg::xmp_segment, as the other JPEG paths do, and jpeg_xmp_fits tells callers whether the XMP will be written. --- crates/image-codecs/src/web.rs | 39 ++++++++++++++++++++++++++++------ 1 file changed, 33 insertions(+), 6 deletions(-) diff --git a/crates/image-codecs/src/web.rs b/crates/image-codecs/src/web.rs index dfd0cd9b9..8e6f6af81 100644 --- a/crates/image-codecs/src/web.rs +++ b/crates/image-codecs/src/web.rs @@ -286,7 +286,8 @@ pub fn decode_wbmp(bytes: &[u8]) -> Result<(u32, u32, Vec), CodecError> { /// JPEG from 8-bit RGB (`rgb.len() == 3·w·h`): quality 1..=100, optional progressive scans and /// optimised Huffman tables (Save for Web's "Optimized"), optional ICC profile, density, EXIF and -/// XMP. EXIF that doesn't fit in one segment is left out (see [`jpeg_exif_fits`]). +/// XMP. EXIF that doesn't fit in one segment is left out (see [`jpeg_exif_fits`]); XMP that doesn't fit loses its layered-document properties, +/// else is left out too (see [`jpeg_xmp_fits`]). #[allow(clippy::too_many_arguments)] pub fn encode_jpeg_rgb8( width: u32, @@ -326,11 +327,10 @@ pub fn encode_jpeg_rgb8( if let Some(seg) = exif.and_then(|x| crate::codecs::jpeg::exif_segment(x, ppi)) { enc.add_app_segment(1, &seg).map_err(e)?; } - if let Some(x) = xmp { - // Its `tiff:` resolution, if any, says what the JFIF density says (#1691). - let x = crate::resolution::export_xmp(x, ppi); - let mut seg = b"http://ns.adobe.com/xap/1.0/\0".to_vec(); - seg.extend_from_slice(x.as_bytes()); + // Its `tiff:` resolution, if any, says what the JFIF density says. A packet past one segment + // loses its layered-document properties, else is left out, as the other JPEG paths do; see + // [`jpeg_xmp_fits`]. + if let Some(seg) = xmp.and_then(|x| crate::codecs::jpeg::xmp_segment(x, ppi)) { enc.add_app_segment(1, &seg).map_err(e)?; } if let Some(icc) = icc { @@ -345,6 +345,12 @@ pub fn jpeg_exif_fits(exif: &[u8], dpi: Option) -> bool { crate::codecs::jpeg::exif_segment(exif, dpi.filter(|d| *d >= 1.0).map(|d| (d, d))).is_some() } +/// Whether [`encode_jpeg_rgb8`] writes `xmp` at `dpi`: it must fit in one APP1 segment, if need +/// be without its layered-document properties. +pub fn jpeg_xmp_fits(xmp: &str, dpi: Option) -> bool { + crate::codecs::jpeg::xmp_segment(xmp, dpi.filter(|d| *d >= 1.0).map(|d| (d, d))).is_some() +} + #[cfg(test)] mod tests { use super::*; @@ -355,6 +361,27 @@ mod tests { (w, h, img.convert(crate::ChannelLayout::Rgba, crate::SampleType::U8).data().to_vec()) } + /// XMP past one APP1 segment loses its layered-document properties, and a packet still too + /// large is left out; the JPEG is written either way. + #[test] + fn web_jpeg_oversized_xmp_is_trimmed_or_left_out() { + let rgb = vec![100u8; 8 * 8 * 3]; + let ancestors = format!( + "{}", + "id".repeat(5_000) + ); + assert!(ancestors.len() > 70_000); + assert!(jpeg_xmp_fits(&ancestors, Some(72.0)), "trimmed, it fits"); + let out = encode_jpeg_rgb8(8, 8, &rgb, 80, false, false, None, Some(72.0), None, Some(&ancestors)).unwrap(); + let xmp = crate::decode(&out).unwrap().meta.xmp.unwrap_or_default(); + assert!(xmp.contains("dc:title=\"kept\"") && !xmp.contains("DocumentAncestors"), "{xmp}"); + let big = format!("", "x".repeat(70_000)); + assert!(!jpeg_xmp_fits(&big, Some(72.0))); + let out = encode_jpeg_rgb8(8, 8, &rgb, 80, false, false, None, Some(72.0), None, Some(&big)).unwrap(); + let img = crate::decode(&out).unwrap(); + assert_eq!((img.dimensions(), img.meta.xmp), ((8, 8), None), "written without the XMP"); + } + fn pattern(w: usize, h: usize, n: usize) -> Vec { (0..w * h).map(|i| (((i % w) * 7 + (i / w) * 13 + (i * i) % 5) % n) as u8).collect() } From db474747d05fea717709d66e99b589b37524f103 Mon Sep 17 00:00:00 2001 From: Trevor Brown Date: Sat, 14 Nov 2026 06:44:08 -0500 Subject: [PATCH 29/51] image-codecs: wrap the encode_jpeg_rgb8 doc comment like the rest of the file --- crates/image-codecs/src/web.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/image-codecs/src/web.rs b/crates/image-codecs/src/web.rs index 8e6f6af81..098462ad7 100644 --- a/crates/image-codecs/src/web.rs +++ b/crates/image-codecs/src/web.rs @@ -286,8 +286,8 @@ pub fn decode_wbmp(bytes: &[u8]) -> Result<(u32, u32, Vec), CodecError> { /// JPEG from 8-bit RGB (`rgb.len() == 3·w·h`): quality 1..=100, optional progressive scans and /// optimised Huffman tables (Save for Web's "Optimized"), optional ICC profile, density, EXIF and -/// XMP. EXIF that doesn't fit in one segment is left out (see [`jpeg_exif_fits`]); XMP that doesn't fit loses its layered-document properties, -/// else is left out too (see [`jpeg_xmp_fits`]). +/// XMP. EXIF that doesn't fit in one segment is left out (see [`jpeg_exif_fits`]); XMP that +/// doesn't fit loses its layered-document properties, else is left out too (see [`jpeg_xmp_fits`]). #[allow(clippy::too_many_arguments)] pub fn encode_jpeg_rgb8( width: u32, From 9a5a35334a05ce86a28b22479eddbfc4742d238e Mon Sep 17 00:00:00 2001 From: pakiat <49967840+pakiat@users.noreply.github.com> Date: Sat, 14 Nov 2026 11:52:27 +0000 Subject: [PATCH 30/51] craft-docx: a field's Thai result takes the complex-script formatting only where Word does Measured in Word for Windows: Thai text as a field's result follows the rule ordinary text does. mark_runs_as_word_draws_them counts the result of a field kept as one object as the text of its run. Co-Authored-By: Claude Opus 5.5 --- crates/docx/tests/it/bidi.rs | 37 ++++++++++++++++++++++++++++++++++ crates/wordmodel/src/styles.rs | 22 ++++++++++++++++---- 2 files changed, 55 insertions(+), 4 deletions(-) diff --git a/crates/docx/tests/it/bidi.rs b/crates/docx/tests/it/bidi.rs index 6dae963aa..bea7e2131 100644 --- a/crates/docx/tests/it/bidi.rs +++ b/crates/docx/tests/it/bidi.rs @@ -290,3 +290,40 @@ fn thai_text_takes_the_complex_script_formatting_only_in_a_complex_script_run() assert_eq!(drawn, [("Angsana New".to_string(), 22.0), ("Tahoma".to_string(), 11.0), ("Angsana New".to_string(), 22.0)], "{when}"); } } + +/// Measured in Word for Windows: Thai text as a field's result follows the same rule as ordinary +/// text, also when the reader keeps the field as one object with its result. +#[test] +fn a_fields_thai_result_takes_the_complex_script_formatting_only_in_a_complex_script_run() { + let styles = r#" +"#; + let field = |rpr: &str| { + let r = |inner: &str| format!("{rpr}{inner}"); + format!( + "{}{}{}{}{}", + r(r#""#), + r(r#" QUOTE "x" "#), + r(r#""#), + r("ทดสอบ"), + r(r#""#) + ) + }; + let drawn = |d: &Document| { + let p = paras(d)[0]; + let at = p.text.find(craft_wordmodel::para::OBJ).expect("the field is one object"); + let run = p.runs.iter().scan(0, |end, r| { + let start = *end; + *end += r.len; + Some((start, r)) + }); + let (_, run) = run.into_iter().find(|(start, r)| *start <= at && at < start + r.len).unwrap(); + let rc = d.styles.resolve_char(p.props.style.as_deref(), &run.props); + if rc.uses_complex('ท') { (rc.font_cs.clone(), rc.size_cs) } else { (rc.font.clone(), rc.size) } + }; + for (what, rpr, want) in [("nothing", "", ("Angsana New", 10.0)), ("w:cs", "", ("Tahoma", 20.0))] { + let d = craft_docx::read(&docx_with_styles(&field(rpr), styles)).unwrap(); + assert_eq!(drawn(&d), (want.0.to_string(), want.1), "a run with {what}: read"); + let again = craft_docx::read(&craft_docx::write(&d).unwrap()).unwrap(); + assert_eq!(drawn(&again), (want.0.to_string(), want.1), "a run with {what}: after a save"); + } +} diff --git a/crates/wordmodel/src/styles.rs b/crates/wordmodel/src/styles.rs index 81d8cd272..1d725efa2 100644 --- a/crates/wordmodel/src/styles.rs +++ b/crates/wordmodel/src/styles.rs @@ -841,11 +841,25 @@ impl StyleSheet { /// right to left. pub fn mark_runs_as_word_draws_them(&self, para: &mut crate::para::Paragraph, table: Option<&CharProps>) { use crate::bidi::{is_complex_script, is_rtl_script}; - let style = para.props.style.as_deref(); - let mut at = 0; - for run in &mut para.runs { - let text = para.text.get(at..at + run.len).unwrap_or(""); + use crate::para::{InlineObject, OBJ}; + // What each run draws: its text, a field kept as one object standing for its result + // (drawn in the run's formatting, and measured in Word to follow the same rule). + let mut drawn = Vec::with_capacity(para.runs.len()); + let (mut at, mut objects) = (0, para.objects.iter()); + for run in ¶.runs { + let mut text = String::new(); + for c in para.text.get(at..at + run.len).unwrap_or("").chars() { + if c != OBJ { + text.push(c); + } else if let Some(InlineObject::Field { result, code: false, .. }) = objects.next() { + text.push_str(result); + } + } at += run.len; + drawn.push(text); + } + let style = para.props.style.as_deref(); + for (run, text) in para.runs.iter_mut().zip(&drawn) { if text.is_empty() || text.chars().any(is_rtl_script) { continue; } From 3400dbc4d76b73ccee1eb98f90384a6126243b3f Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sat, 14 Nov 2026 08:19:09 -0500 Subject: [PATCH 31/51] scripts: test with [[ in fetch-opus-vectors.sh SonarCloud S7688 counts the POSIX [ tests in the Opus vector fetcher. The script already needs bash for arrays and ${!ranges[@]}, so the tests use [[ ... ]], which neither word-splits nor globs its operands. --- scripts/fetch-opus-vectors.sh | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/scripts/fetch-opus-vectors.sh b/scripts/fetch-opus-vectors.sh index d9f92befc..cce3d1489 100755 --- a/scripts/fetch-opus-vectors.sh +++ b/scripts/fetch-opus-vectors.sh @@ -11,7 +11,7 @@ URL=https://opus-codec.org/static/testvectors/opus_testvectors-rfc8251.tar.gz SHA256=6b26a22f9ba87b2b836906a9bb7afec5f8e54d49553b1200382520ee6fedfa55 DEST=${1:-target/fixtures/opus/vectors} -if [ -f "$DEST/testvector01.bit" ] && [ -f "$DEST/testvector12m.dec" ]; then +if [[ -f "$DEST/testvector01.bit" && -f "$DEST/testvector12m.dec" ]]; then echo "Opus vectors already in $DEST" exit 0 fi @@ -20,7 +20,7 @@ tmp=$(mktemp -d) trap 'rm -rf "$tmp"' EXIT len=$(curl -fsSIL --proto '=https' --proto-redir '=https' --retry 10 --retry-delay 2 --retry-all-errors --connect-timeout 20 --max-time 60 "$URL" | tr -d '\r' | awk 'tolower($1) == "content-length:" { n = $2 } END { print n }') -[ -n "$len" ] || { echo "could not read the archive size" >&2; exit 1; } +[[ -n "$len" ]] || { echo "could not read the archive size" >&2; exit 1; } # Small ranges, eight at a time: a range whose connection drops below 50 KB/s for 15 s is # abandoned and fetched again, which costs little for a 2 MB range. @@ -46,12 +46,12 @@ for attempt in 1 2 3 4 5; do range=${ranges[$i]} want=$((${range#*-} - ${range%-*} + 1)) part=$(printf '%s/part.%04d' "$tmp" "$i") - if [ "$(wc -c < "$part" 2> /dev/null || echo 0)" -ne "$want" ]; then + if [[ "$(wc -c < "$part" 2> /dev/null || echo 0)" -ne "$want" ]]; then short=1 fetch "$range" "$part" || true fi done - [ "$short" -eq 0 ] && break + [[ "$short" -eq 0 ]] && break done cat "$tmp"/part.* > "$tmp/vectors.tar.gz" From 5f67d91eeed1f99b77d4359b025a314eb50b53f9 Mon Sep 17 00:00:00 2001 From: Naxvog <4963183+naxvog@users.noreply.github.com> Date: Sat, 14 Nov 2026 15:27:22 +0100 Subject: [PATCH 32/51] craft-docx: a file with no default table style gives its tables no cell margins Port of storytold/wordcraft#3821, whose reader code moved here with storytold/wordcraft#6603. Word's 0.08" cell margin comes from the Normal Table default table style; without a default table style a table that sets no margins (and whose style sets none) has zero margins. The zeros are kept as the table's own, also for the old properties of a tblPrChange, so they survive saving. w:default="on" now marks a default style too. --- crates/docx/src/read.rs | 5 ++ crates/docx/src/read/story/blocks.rs | 19 ++++- crates/docx/src/read/styles.rs | 15 ++++ .../docx/tests/it/cell_margin_inheritance.rs | 70 +++++++++++++++++++ 4 files changed, 108 insertions(+), 1 deletion(-) diff --git a/crates/docx/src/read.rs b/crates/docx/src/read.rs index 5ea11dbd8..0f95b4f76 100644 --- a/crates/docx/src/read.rs +++ b/crates/docx/src/read.rs @@ -119,6 +119,10 @@ pub(crate) struct Reader<'p> { pub theme_fills: shape_style::ThemeFills, /// The fill of the group being read (what its members' `a:grpFill` stands for). pub group_fill: Option, + /// The package has no default table style (no styles part, or none marked `w:default`): + /// Word then gives tables no cell margins rather than its Normal Table's 0.08". Set by + /// `read_styles`, which runs before any story with tables is read. + pub no_default_table_style: bool, } /// The package path that internal relationship `id` points at, if it has type `kind` (an `rt` @@ -193,6 +197,7 @@ fn read_opened_in(pkg: &Package, chunks: ChunkState) -> Result<(Document, usize, theme_fills: Default::default(), group_fill: None, chunks, + no_default_table_style: true, }; r.doc.missing_pictures.main = main.clone(); r.pc.major_font = r.doc.settings.major_font.clone(); diff --git a/crates/docx/src/read/story/blocks.rs b/crates/docx/src/read/story/blocks.rs index e72f16bf6..5efd87068 100644 --- a/crates/docx/src/read/story/blocks.rs +++ b/crates/docx/src/read/story/blocks.rs @@ -314,15 +314,32 @@ impl Reader<'_> { // ---- tables ---- + /// Word gives a table no cell margins when the file has no default table style and neither the + /// table nor its style sets them; saving may write a default Normal Table, so the zeros are + /// kept as the table's own. shortcut: they stay direct formatting (a table style applied later + /// keeps them), until the model knows the file's default table style. A `w:tblCellMar` that sets + /// only some sides keeps them: only the sides it omits become 0. + fn no_default_margins(&self, props: &mut craft_wordmodel::props::TableProps) { + if self.no_default_table_style + && props.cell_margins.is_none() + && props.style.as_deref().and_then(|id| self.doc.styles.table_style(id)).is_none_or(|s| s.parts.cell_margins.is_none()) + { + props.cell_margins = Some([0.0; 4]); + } + } + fn read_table(&mut self, sc: &mut StoryCtx, t: &El, rels: &Rels, depth: usize) -> Option { let mut table = Table::default(); if let Some(p) = t.child("w:tblPr") { table.props = self.pc.tblpr(p); if let Some(ch) = p.child("w:tblPrChange") { - let old = ch.child("w:tblPr").map(|o| self.pc.tblpr(o)).unwrap_or_default(); + let mut old = ch.child("w:tblPr").map(|o| self.pc.tblpr(o)).unwrap_or_default(); + // Rejecting the change brings back these properties: with the same margins. + self.no_default_margins(&mut old); table.props.fmt_change = PropChange::boxed(self.revision(RevisionKind::Format, ch), old); } } + self.no_default_margins(&mut table.props); if let Some(g) = t.child("w:tblGrid") { table.grid = g .children("w:gridCol") diff --git a/crates/docx/src/read/styles.rs b/crates/docx/src/read/styles.rs index 080eaff21..1fa9caeb4 100644 --- a/crates/docx/src/read/styles.rs +++ b/crates/docx/src/read/styles.rs @@ -64,6 +64,20 @@ fn builtin_heading_level(name: &str) -> Option { } impl Reader<'_> { + /// Whether a style's kept (last) definition is a default table style. + fn has_default_table_style(&self, root: &El) -> bool { + let mut defaults: Vec = Vec::new(); + for s in root.children("w:style").take(10_000) { + let Some(raw_id) = s.attr("w:styleId").filter(|i| !i.is_empty()) else { continue }; + let id = self.pc.style_id(raw_id); + defaults.retain(|d| *d != id); + if s.attr("w:type") == Some("table") && style_is_default(s) { + defaults.push(id); + } + } + !defaults.is_empty() + } + pub(super) fn read_styles(&mut self, path: &str) -> Result<(), DocxError> { /// Largest `w:latentStyles` kept (Word's has ~380 exceptions, ~40 KB). const MAX_LATENT_STYLES_XML: usize = 1 << 20; @@ -207,6 +221,7 @@ impl Reader<'_> { None => sheet.styles.push(st), } } + self.no_default_table_style = !self.has_default_table_style(&root); // Styles that give only a list level take the list from the style they are based on // (Heading 3: level 3 of Heading 2's outline list). let fixed: Vec> = sheet diff --git a/crates/docx/tests/it/cell_margin_inheritance.rs b/crates/docx/tests/it/cell_margin_inheritance.rs index f4d8de5a5..83aafc7d0 100644 --- a/crates/docx/tests/it/cell_margin_inheritance.rs +++ b/crates/docx/tests/it/cell_margin_inheritance.rs @@ -28,3 +28,73 @@ fn partial_margin_stays_partial() { assert!(!margins.contains(") -> Vec { + const W: &str = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"; + let mut zip = zip::ZipWriter::new(Cursor::new(Vec::new())); + let mut add = |name: &str, xml: &str| { + zip.start_file(name, zip::write::SimpleFileOptions::default()).unwrap(); + zip.write_all(xml.as_bytes()).unwrap(); + }; + add("word/document.xml", &format!(r#"{body}"#)); + if let Some(styles) = styles { + add("word/styles.xml", &format!(r#"{styles}"#)); + add( + "word/_rels/document.xml.rels", + r#""#, + ); + } + zip.finish().unwrap().into_inner() +} + +/// Without a default table style (no styles part, or none marked `w:default`) Word gives a table +/// no cell margins: a cell that sets only its right margin has none on its other sides. +#[test] +fn no_default_table_style_means_no_cell_margins() { + let body = r#""#; + let normal_table = r#""#; + let margins = |styles: Option<&str>| { + let doc = craft_docx::read(&package(body, styles)).unwrap(); + let table = doc.body[0].as_table().unwrap(); + (table.props.cell_margins, table.rows[0].cells[0].props.resolved_margins(table.props.cell_margins.unwrap_or([0.0, 5.4, 0.0, 5.4]))) + }; + assert_eq!(margins(None), (Some([0.0; 4]), [0.0, 0.0, 0.0, 5.4])); + assert_eq!(margins(Some(r#""#)), (Some([0.0; 4]), [0.0, 0.0, 0.0, 5.4])); + // With Word's usual Normal Table the table keeps no margins of its own (the defaults apply). + assert_eq!(margins(Some(normal_table)).0, None); + // A style defined twice is its last definition: a default one redefined as not default leaves none. + let redefined = format!(r#"{normal_table}"#); + assert_eq!(margins(Some(&redefined)).0, Some([0.0; 4])); + // A custom default table style marked `on` is a default too, also after saving and reopening. + let plain = r#""#; + let doc = craft_docx::read(&package(body, Some(plain))).unwrap(); + assert_eq!(doc.body[0].as_table().unwrap().props.cell_margins, None); + let reopened = craft_docx::read(&craft_docx::write(&doc).unwrap()).unwrap(); + assert_eq!(reopened.body[0].as_table().unwrap().props.cell_margins, None); + // A table that sets only some sides keeps them; the sides it omits are 0. + let partial = body.replace("", r#""#); + let doc = craft_docx::read(&package(&partial, None)).unwrap(); + assert_eq!(doc.body[0].as_table().unwrap().props.cell_margins, Some([0.0, 7.2, 0.0, 0.0])); + // Rejecting a tracked change to the table's properties brings back the same zero margins. + let tracked = body.replace( + "", + r#""#, + ); + let doc = craft_docx::read(&package(&tracked, None)).unwrap(); + let change = doc.body[0].as_table().unwrap().props.fmt_change.as_deref().expect("a tracked table change"); + assert_eq!(change.old.cell_margins, Some([0.0; 4])); + // A table whose own style gives margins keeps them. + let styled = body.replace("", r#""#); + let boxed = r#""#; + let doc = craft_docx::read(&package(&styled, Some(boxed))).unwrap(); + assert_eq!(doc.body[0].as_table().unwrap().props.cell_margins, None); + // The zeros survive saving, which writes a default Normal Table. + let doc = craft_docx::read(&package(body, None)).unwrap(); + let bytes = craft_docx::write(&doc).unwrap(); + let mut xml = String::new(); + zip::ZipArchive::new(Cursor::new(bytes.clone())).unwrap().by_name("word/document.xml").unwrap().read_to_string(&mut xml).unwrap(); + assert!(xml.contains(""), "{xml}"); + let reopened = craft_docx::read(&bytes).unwrap(); + assert_eq!(reopened.body[0].as_table().unwrap().props.cell_margins, Some([0.0; 4])); +} From ebece3ff5c0d5bdc382dd3e03d78ab17f538d6f4 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sat, 14 Nov 2026 10:05:44 -0500 Subject: [PATCH 33/51] ci: lock the actions main added while this branch was open Merging main in brought cms.yml, menu.yml and the wasm job back, and their action refs had no lockfile entries, so `gh actions-lock --verify` failed. Regenerated with `gh actions-lock`; the four refs it normalized resolve to the commits already in use. --- .github/workflows/actions.lock | 15 +++++++++++++++ .github/workflows/atomic.yml | 2 +- .github/workflows/cms.yml | 2 +- .github/workflows/menu.yml | 6 +++--- 4 files changed, 20 insertions(+), 5 deletions(-) diff --git a/.github/workflows/actions.lock b/.github/workflows/actions.lock index c2e897943..acbdeff60 100644 --- a/.github/workflows/actions.lock +++ b/.github/workflows/actions.lock @@ -8,7 +8,9 @@ workflows: - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' '.github/workflows/atomic.yml': + - 'actions/checkout@v4.4.0' - 'actions/checkout@v7.0.1' + - 'dtolnay/rust-toolchain@stable' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' '.github/workflows/audio.yml': @@ -17,6 +19,9 @@ workflows: - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' - 'step-security/rust-cache@v2.9.2' + '.github/workflows/cms.yml': + - 'actions/checkout@v4.4.0' + - 'dtolnay/rust-toolchain@stable' '.github/workflows/crw.yml': - 'actions/cache@v6.1.0' - 'actions/checkout@v7.0.1' @@ -71,6 +76,10 @@ workflows: - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' - 'step-security/rust-cache@v2.9.2' + '.github/workflows/menu.yml': + - 'actions/checkout@v7.0.1' + - 'dtolnay/rust-toolchain@stable' + - 'swatinem/rust-cache@v2.9.3' '.github/workflows/pcraft-format.yml': - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' @@ -125,12 +134,18 @@ workflows: - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' + '.github/workflows/workspace.yml': [] dependencies: 'actions/cache@v6.1.0': ref: 'v6.1.0' commit: 'sha1-55cc8345863c7cc4c66a329aec7e433d2d1c52a9' owner_id: 44036562 repo_id: 215566462 + 'actions/checkout@v4.4.0': + ref: 'v4.4.0' + commit: 'sha1-11d5960a326750d5838078e36cf38b85af677262' + owner_id: 44036562 + repo_id: 197814629 'actions/checkout@v7.0.1': ref: 'v7.0.1' commit: 'sha1-3d3c42e5aac5ba805825da76410c181273ba90b1' diff --git a/.github/workflows/atomic.yml b/.github/workflows/atomic.yml index 9caf6c17c..f72a64f1e 100644 --- a/.github/workflows/atomic.yml +++ b/.github/workflows/atomic.yml @@ -50,7 +50,7 @@ jobs: name: Atomic WASM runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v4.4.0 - uses: dtolnay/rust-toolchain@stable with: targets: wasm32-unknown-unknown diff --git a/.github/workflows/cms.yml b/.github/workflows/cms.yml index a15a48c9d..74ce0815f 100644 --- a/.github/workflows/cms.yml +++ b/.github/workflows/cms.yml @@ -16,7 +16,7 @@ jobs: timeout-minutes: 20 runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v4.4.0 - uses: dtolnay/rust-toolchain@stable with: components: clippy diff --git a/.github/workflows/menu.yml b/.github/workflows/menu.yml index 6d0e082cb..8d1058731 100644 --- a/.github/workflows/menu.yml +++ b/.github/workflows/menu.yml @@ -21,14 +21,14 @@ jobs: name: Menu (Linux) runs-on: ubuntu-latest steps: - - uses: actions/checkout@v7 + - uses: actions/checkout@v7.0.1 with: persist-credentials: false - - uses: dtolnay/rust-toolchain@b725eda525362e7cf34af9a7243cac1e3f01a7ec # stable + - uses: dtolnay/rust-toolchain@stable with: components: rustfmt, clippy targets: aarch64-apple-darwin, wasm32-unknown-unknown - - uses: Swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3 + - uses: Swatinem/rust-cache@v2.9.3 with: key: craft-menu-linux - run: cargo fmt -p craft-menu --check From bcd09376d0e14a8231827a2d580682f3a9ae7885 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sat, 14 Nov 2026 08:27:34 -0500 Subject: [PATCH 34/51] sonar: ignore the weak hashes the encrypted formats require S4790 reports the MD5 and SHA-1 in the xls, pdf and odf cryptography modules. Each hash is the one the format specifies: a workbook's FilePass verifier, a PDF revision 2-4 file key, and an OpenDocument start key or file checksum. A stronger hash derives a different value, so the files would no longer open. The three files are excluded with the reason recorded, as the ICC profile ID already is. --- sonar-project.properties | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/sonar-project.properties b/sonar-project.properties index 516e4d5cc..f30f3ae5f 100644 --- a/sonar-project.properties +++ b/sonar-project.properties @@ -15,9 +15,24 @@ sonar.cpd.exclusions=**/*tables.rs # S4790 (weak hash): the ICC specification defines the profile ID as the MD5 of the profile, so # no other algorithm produces an ID other software accepts. It identifies, it does not protect. -sonar.issue.ignore.multicriteria=icc_profile_id,gha-lockfile +# +# The encrypted packages below are the same case: each format derives its keys from MD5 or SHA-1, +# so substituting a stronger hash stops the files the module reads and writes from opening. +sonar.issue.ignore.multicriteria=icc_profile_id,xls_filepass_hash,pdf_standard_security_hash,odf_package_hash,gha-lockfile sonar.issue.ignore.multicriteria.icc_profile_id.ruleKey=rust:S4790 sonar.issue.ignore.multicriteria.icc_profile_id.resourceKey=crates/cms/src/write.rs +# xls: [MS-OFFCRYPTO] 2.3.6.1-2.3.6.2, where RC4 1.1 takes its key and verifier from MD5, and +# 2.3.5.1-2.3.5.2, where RC4 CryptoAPI takes them from SHA-1. +sonar.issue.ignore.multicriteria.xls_filepass_hash.ruleKey=rust:S4790 +sonar.issue.ignore.multicriteria.xls_filepass_hash.resourceKey=crates/xls/src/crypt.rs +# pdf: ISO 32000-1 7.6.3.3, Algorithms 2-7. Revisions 2-4 derive the file key and the /O and /U +# values from MD5; revisions 5 and 6 use SHA-256 and SHA-512 (Algorithm 2.B). +sonar.issue.ignore.multicriteria.pdf_standard_security_hash.ruleKey=rust:S4790 +sonar.issue.ignore.multicriteria.pdf_standard_security_hash.resourceKey=crates/pdf/src/crypt.rs +# odf: OpenDocument 4.16.6 and 4.16.3, a start key and a file checksum made with SHA-1, each used +# only where the package's manifest names it. +sonar.issue.ignore.multicriteria.odf_package_hash.ruleKey=rust:S4790 +sonar.issue.ignore.multicriteria.odf_package_hash.resourceKey=crates/odf/src/crypt.rs # githubactions:S7637 asks for every action to be pinned to a commit SHA. A workflow covered by # .github/workflows/actions.lock runs the commit the lockfile records, so its tag refs are pinned From 5c8e1b0d829d8fdc25d900019b9488e041fb7e91 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sat, 14 Nov 2026 15:10:43 +0000 Subject: [PATCH 35/51] docx: retain explicit numbering level presence --- crates/docx/src/read/styles.rs | 11 +++++-- crates/docx/tests/it/passthrough.rs | 3 ++ crates/wordmodel/src/numbering.rs | 48 +++++++++++++++++++++++++++++ 3 files changed, 60 insertions(+), 2 deletions(-) diff --git a/crates/docx/src/read/styles.rs b/crates/docx/src/read/styles.rs index 080eaff21..b393df4d2 100644 --- a/crates/docx/src/read/styles.rs +++ b/crates/docx/src/read/styles.rs @@ -316,9 +316,11 @@ impl Reader<'_> { for a in root.children("w:abstractNum").take(10_000) { let Some(id) = a.attr("w:abstractNumId").and_then(u32_of) else { continue }; let mut levels: Vec = (0..9).map(default_level).collect(); + let mut explicit_levels = [false; 9]; for l in a.children("w:lvl") { let Some(i) = numbering_level_index(l.attr("w:ilvl")) else { continue }; levels[i] = self.level(l, i); + explicit_levels[i] = true; } if let Some(link) = a.child_val("w:numStyleLink") { links.push((id, link.to_string())); @@ -328,6 +330,7 @@ impl Reader<'_> { id, name: a.child_val("w:name").map(str::to_string), levels, + explicit_levels: Some(explicit_levels), nsid: a.child_val("w:nsid").filter(|v| hex(v)).map(str::to_ascii_uppercase), tmpl: a.child_val("w:tmpl").filter(|v| hex(v)).map(str::to_ascii_uppercase), multi_level_type: a @@ -361,9 +364,13 @@ impl Reader<'_> { for (aid, style) in links { let num = self.doc.styles.get(&self.pc.style_id(&style)).and_then(|s| s.para.numbering).map(|n| n.num); let src = num.and_then(|n| nums.iter().find(|x: &&Num| x.id == n)).map(|x| x.abstract_id); - let levels = src.filter(|s| *s != aid).and_then(|s| abstracts.iter().find(|a: &&AbstractNum| a.id == s)).map(|a| a.levels.clone()); - if let (Some(levels), Some(a)) = (levels, abstracts.iter_mut().find(|a| a.id == aid)) { + let source = src + .filter(|s| *s != aid) + .and_then(|s| abstracts.iter().find(|a: &&AbstractNum| a.id == s)) + .map(|a| (a.levels.clone(), a.explicit_levels)); + if let (Some((levels, explicit_levels)), Some(a)) = (source, abstracts.iter_mut().find(|a| a.id == aid)) { a.levels = levels; + a.explicit_levels = explicit_levels; } } Arc::make_mut(&mut self.doc.numbering).abstracts = abstracts; diff --git a/crates/docx/tests/it/passthrough.rs b/crates/docx/tests/it/passthrough.rs index 9e5f35a9f..9d3176a76 100644 --- a/crates/docx/tests/it/passthrough.rs +++ b/crates/docx/tests/it/passthrough.rs @@ -335,6 +335,9 @@ fn malformed_numbering_levels_are_skipped_instead_of_becoming_level_zero() { }) .collect(); assert_eq!(paragraphs.len(), 5); + assert!(doc.numbering.level_is_defined(1, 0)); + assert!(!doc.numbering.level_is_defined(1, 2), "effective defaults remain distinguishable from source definitions"); + assert!(doc.numbering.level(1, 2).is_some(), "Word's effective default level remains available"); assert_eq!(paragraphs[0].props.numbering.map(|n| (n.num, n.level)), Some((1, 0)), "an omitted level defaults to zero"); assert_eq!(paragraphs[1].props.numbering.map(|n| (n.num, n.level)), Some((1, 2)), "a valid level is preserved"); for p in ¶graphs[2..] { diff --git a/crates/wordmodel/src/numbering.rs b/crates/wordmodel/src/numbering.rs index 5ab94ea87..dc2c69a23 100644 --- a/crates/wordmodel/src/numbering.rs +++ b/crates/wordmodel/src/numbering.rs @@ -76,6 +76,12 @@ pub struct AbstractNum { pub id: u32, pub name: Option, pub levels: Vec, + /// Which levels were defined in the source file. `None` is used by model-created definitions, + /// where the populated `levels` vector is authoritative. DOCX readers set this when they fill + /// unspecified Word levels with their effective defaults. This reader-only provenance is not + /// serialized as part of the document model. + #[serde(skip)] + pub explicit_levels: Option<[bool; 9]>, /// Word's list identity (`w:nsid`, 8 hex digits), which it uses to match lists across /// documents (paste, compare); kept from the file. #[serde(skip_serializing_if = "Option::is_none")] @@ -236,6 +242,20 @@ impl Numbering { } self.abstract_of(num)?.levels.get(level as usize) } + /// Whether the source definition supplied this level, or a per-numbering override defines it. + /// + /// [`Self::level`] also exposes Word's effective default for omitted levels. This method lets + /// importers preserve formats whose historical behavior distinguishes an explicit level from + /// that effective fallback. Older serialized and model-created definitions have no source + /// presence metadata, so their populated levels count as defined. + pub fn level_is_defined(&self, num: u32, level: u8) -> bool { + let Some(n) = self.num(num) else { return false }; + if n.level_overrides.iter().any(|(i, _)| *i == level) { + return true; + } + let Some(a) = self.abstract_of(num) else { return false }; + a.explicit_levels.map_or_else(|| a.levels.get(level as usize).is_some(), |levels| levels.get(level as usize).copied().unwrap_or(false)) + } /// Create a new list of `kind`; returns the `num` id. List ids run out only past `u32::MAX` /// lists, more than memory holds; then nothing is added and the id is 0, "no list". pub fn add_list(&mut self, kind: ListKind) -> u32 { @@ -485,6 +505,34 @@ const MAX_LABEL_BYTES: usize = 256; mod tests { use super::*; + #[test] + fn explicit_level_metadata_preserves_effective_defaults_and_old_models() { + let mut numbering = Numbering::default(); + let id = numbering.add_list(ListKind::Numbered); + assert!(numbering.level_is_defined(id, 0)); + assert!(numbering.level_is_defined(id, 8)); + + let abstract_id = numbering.num(id).unwrap().abstract_id; + let mut explicit = [false; 9]; + explicit[0] = true; + numbering.abstracts.iter_mut().find(|a| a.id == abstract_id).unwrap().explicit_levels = Some(explicit); + + // Effective Word defaults remain available to existing model callers, while importers can + // tell that this source file supplied only level zero. + assert!(numbering.level(id, 1).is_some()); + assert!(!numbering.level_is_defined(id, 1)); + assert!(numbering.level_is_defined(id, 0)); + + // Old serialized definitions have no presence marker; populated levels remain valid. + numbering.abstracts.iter_mut().find(|a| a.id == abstract_id).unwrap().explicit_levels = None; + assert!(numbering.level_is_defined(id, 8)); + + // A per-numbering level definition takes precedence over the abstract's missing level. + numbering.abstracts.iter_mut().find(|a| a.id == abstract_id).unwrap().explicit_levels = Some(explicit); + numbering.nums.iter_mut().find(|n| n.id == id).unwrap().level_overrides.push((1, Level::default())); + assert!(numbering.level_is_defined(id, 1)); + } + /// Read-only counter APIs retain the renderer's bounds and never advance a list. #[test] fn reference_labels_are_bounded_and_do_not_advance_counters() { From a5ac3aa05cf3ec013961a85599ddd9e0b5c03813 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sat, 14 Nov 2026 10:14:26 -0500 Subject: [PATCH 36/51] Merge pull request #1322 from storytold/codex/craft-xml-dtd prepress: share PDF/X-1a finalization and checks (official replacement) --- Cargo.lock | 81 ++- crates/pdf/Cargo.toml | 4 + crates/pdf/README.md | 4 + crates/pdf/src/write.rs | 2 + crates/pdf/src/write/svg.rs | 163 +++++ crates/prepress/src/lib.rs | 2 + crates/prepress/src/pdfx1a.rs | 772 ++++++++++++++++++++++ crates/prepress/tests/flatten_document.rs | 1 - crates/xml/Cargo.toml | 1 + crates/xml/src/dtd.rs | 748 +++++++++++++++++++++ crates/xml/src/lib.rs | 1 + 11 files changed, 1777 insertions(+), 2 deletions(-) create mode 100644 crates/pdf/src/write/svg.rs create mode 100644 crates/prepress/src/pdfx1a.rs create mode 100644 crates/xml/src/dtd.rs diff --git a/Cargo.lock b/Cargo.lock index a1b1ccab3..bef3f51da 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2181,6 +2181,7 @@ dependencies = [ "bytemuck", "chrono", "craft-stream-codecs", + "craft-svg", "flate2", "hayro", "hayro-cmap", @@ -2188,6 +2189,7 @@ dependencies = [ "hayro-syntax", "js-sys", "krilla", + "krilla-svg", "kurbo 0.13.1", "md-5 0.11.0", "proptest", @@ -2197,6 +2199,7 @@ dependencies = [ "stringprep", "thiserror 2.0.21", "ttf-parser", + "usvg 0.47.0", "wasm-bindgen", "wasm-bindgen-test", "zeroize", @@ -2820,6 +2823,7 @@ name = "craft-xml" version = "0.1.0" dependencies = [ "quick-xml 0.41.0", + "serde", "thiserror 2.0.21", ] @@ -4053,6 +4057,20 @@ dependencies = [ "roxmltree 0.20.0", ] +[[package]] +name = "fontdb" +version = "0.23.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "457e789b3d1202543297a350643cf459f836cade38934e7a4cf6a39e7cde2905" +dependencies = [ + "fontconfig-parser", + "log", + "memmap2", + "slotmap", + "tinyvec", + "ttf-parser", +] + [[package]] name = "fontdb" version = "0.24.0" @@ -5648,6 +5666,22 @@ dependencies = [ "zune-jpeg", ] +[[package]] +name = "krilla-svg" +version = "0.8.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1237d7c37b16ca9fbc2e72dde13a10d321f9a44aceee35c062bc0a43bfc7ce16" +dependencies = [ + "flate2", + "fontdb 0.23.0", + "krilla", + "resvg 0.47.0", + "skrifa 0.42.1", + "smallvec", + "tiny-skia 0.12.0", + "usvg 0.47.0", +] + [[package]] name = "kurbo" version = "0.11.3" @@ -7855,6 +7889,23 @@ dependencies = [ "usvg 0.45.1", ] +[[package]] +name = "resvg" +version = "0.47.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9be183ad6a216aa96f33e4c8033b0988b8b3ea6fd2359d19af5bac4643fd8e81" +dependencies = [ + "gif", + "image-webp", + "log", + "pico-args", + "rgb", + "svgtypes 0.16.2", + "tiny-skia 0.12.0", + "usvg 0.47.0", + "zune-jpeg", +] + [[package]] name = "resvg" version = "0.48.1" @@ -9901,6 +9952,34 @@ dependencies = [ "xmlwriter", ] +[[package]] +name = "usvg" +version = "0.47.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d46cf96c5f498d36b7a9693bc6a7075c0bb9303189d61b2249b0dc3d309c07de" +dependencies = [ + "base64 0.22.1", + "data-url", + "flate2", + "fontdb 0.23.0", + "imagesize 0.14.0", + "kurbo 0.13.1", + "log", + "pico-args", + "roxmltree 0.21.2", + "rustybuzz", + "simplecss", + "siphasher", + "strict-num", + "svgtypes 0.16.2", + "tiny-skia-path 0.12.0", + "ttf-parser", + "unicode-bidi", + "unicode-script", + "unicode-vo", + "xmlwriter", +] + [[package]] name = "usvg" version = "0.48.1" @@ -9909,7 +9988,7 @@ checksum = "977d0a4abdef933f424a99fe09f95576e089b90aebc6f016a3bc813762493e91" dependencies = [ "base64 0.23.1", "data-url", - "fontdb", + "fontdb 0.24.0", "harfrust 0.12.0", "imagesize 0.15.0", "kurbo 0.13.1", diff --git a/crates/pdf/Cargo.toml b/crates/pdf/Cargo.toml index ff94c6d8e..266297f42 100644 --- a/crates/pdf/Cargo.toml +++ b/crates/pdf/Cargo.toml @@ -17,6 +17,7 @@ interpret = ["read", "dep:hayro-interpret"] paths = ["interpret", "dep:kurbo"] raster = ["interpret", "dep:hayro", "dep:bytemuck"] write = ["dep:krilla", "dep:thiserror"] +write-svg = ["write", "dep:craft-svg", "dep:krilla-svg", "dep:usvg", "craft-svg/tree-text"] write-pdf = ["write", "krilla/pdf"] write-raster = ["dep:flate2", "dep:roxmltree"] write-simple-text = ["write", "krilla/simple-text"] @@ -30,6 +31,9 @@ hayro-interpret = { workspace = true, optional = true } hayro = { workspace = true, optional = true } bytemuck = { workspace = true, optional = true } krilla = { workspace = true, optional = true } +craft-svg = { workspace = true, optional = true } +krilla-svg = { version = "=0.8.1", optional = true } +usvg = { version = "=0.47.0", features = ["text"], optional = true } thiserror = { workspace = true, optional = true } flate2 = { version = "1.1", default-features = false, features = ["zlib-rs"], optional = true } roxmltree = { version = "0.21", optional = true } diff --git a/crates/pdf/README.md b/crates/pdf/README.md index 18d3d25a9..8cd2c3f25 100644 --- a/crates/pdf/README.md +++ b/crates/pdf/README.md @@ -10,6 +10,7 @@ No feature is enabled by default. | `interpret` | `read` plus an app-owned Device interpreter, fonts and CMaps | | `raster` | `interpret` plus premultiplied RGBA8 rendering | | `write` | Guarded Krilla authoring; no shared reader dependency | +| `write-svg` | `write` plus bounded SVG-to-PDF vector drawing | | `write-pdf` | `write` plus Krilla's embedded-PDF support | | `write-simple-text` | `write` plus Krilla's optional text shaper and `draw_text` | | `filters` | The `/Filter` chain for editing and writing PDF files: decode and encode, with limits and accounting. No reader or writer dependency | @@ -240,6 +241,9 @@ serialization uses the same backend version as before extraction. It provides: refuses it. Apps build URI links with it instead of `backend::action::LinkAction`, so a link target from someone else's document becomes a PDF link only when it is an `http`/`https` URL with a host or a `mailto` address. A refused target writes no link annotation. +- `write::svg` (feature `write-svg`): bounded SVG/SVGZ text preflight, data-only image + resolution, and vector drawing through krilla-svg. Callers provide font and fallback options; + the adapter enforces input, nesting, embedded-image, destination-area and filter budgets. - `safe_url` (crate root, any feature): the same rule, for apps that open links themselves, such as a slide show. diff --git a/crates/pdf/src/write.rs b/crates/pdf/src/write.rs index 8114327d4..924910e25 100644 --- a/crates/pdf/src/write.rs +++ b/crates/pdf/src/write.rs @@ -15,6 +15,8 @@ const _: bool = backend::CRAFT_PRINT_COLOR; const _: bool = backend::CRAFT_OPTIONAL_CONTENT; pub mod print; +#[cfg(feature = "write-svg")] +pub mod svg; use backend::configure::{Archival, Configuration, ConfigurationBuilder, ConfigurationError, PdfVersion}; use backend::text::{Font, Tag}; diff --git a/crates/pdf/src/write/svg.rs b/crates/pdf/src/write/svg.rs new file mode 100644 index 000000000..2eaf055ec --- /dev/null +++ b/crates/pdf/src/write/svg.rs @@ -0,0 +1,163 @@ +//! Bounded SVG parsing and vector drawing on a PDF surface. +//! +//! This adapter owns the usvg version required by krilla-svg. Callers pass their font and +//! fallback options, while this module checks input, embedded SVGs, and output/filter budgets +//! before converting SVG to PDF drawing operations. + +use std::sync::Arc; +use std::sync::atomic::{AtomicUsize, Ordering}; + +use krilla_svg::SurfaceExt; + +pub use krilla_svg::SvgSettings; +pub use usvg; + +/// Resource limits for parsing SVG and drawing it to PDF. +#[derive(Clone, Copy, Debug)] +pub struct Limits { + /// Maximum decoded bytes in one SVG document. + pub input_bytes: usize, + /// Maximum SVG element and reference depth. + pub depth: usize, + /// Maximum XML nodes in one document. + pub xml_nodes: u32, + /// Maximum total decoded bytes of embedded SVGs. + pub embedded_svg_bytes: usize, + /// Maximum number of embedded SVG documents nested within one another. + pub embedded_svg_depth: usize, + /// Maximum encoded bytes retained for embedded raster images. + pub embedded_image_bytes: usize, + /// Maximum PDF surface area, measured in 96 dpi pixels. + pub vector_pixels: u64, + /// Maximum raster pixels used by filters after `filter_scale` is applied. + pub filter_pixels: u64, +} + +impl Default for Limits { + fn default() -> Self { + Self { + input_bytes: 16 * 1024 * 1024, + depth: 64, + xml_nodes: 100_000, + embedded_svg_bytes: 32 * 1024 * 1024, + embedded_svg_depth: 4, + embedded_image_bytes: 32 * 1024 * 1024, + vector_pixels: 256_000_000, + filter_pixels: 256_000_000, + } + } +} + +/// Why an SVG could not be parsed or drawn within its limits. +#[derive(Debug, thiserror::Error)] +pub enum Error { + /// The bounded SVG text/XML preflight refused the input. + #[error("SVG preflight failed: {0}")] + Preflight(String), + /// usvg could not construct the SVG tree. + #[error("SVG parsing failed: {0}")] + Parse(String), + /// The requested PDF area or filter raster exceeds its budget. + #[error("SVG drawing exceeds the PDF area or filter budget")] + DrawLimit, + /// krilla-svg refused to draw the parsed tree. + #[error("krilla-svg could not draw the parsed tree")] + Draw, +} + +/// An SVG tree parsed within [`Limits`], ready to draw as PDF vectors. +pub struct Document { + tree: usvg::Tree, + limits: Limits, +} + +impl Document { + /// Parse SVG/SVGZ bytes after bounded shared preflight. `options` controls the caller's font + /// database, family selection, and fallback policy; its file-reading and image resolvers are + /// replaced with a data-only resolver governed by `limits`. + pub fn parse<'a>(bytes: &[u8], limits: Limits, mut options: usvg::Options<'a>) -> Result { + let text = bounded_text(bytes, limits.input_bytes, limits).map_err(|e| Error::Preflight(e.to_string()))?; + options.image_href_resolver = image_resolver(limits); + let tree = usvg::Tree::from_str(&text, &options).map_err(|e| Error::Parse(e.to_string()))?; + Ok(Self { tree, limits }) + } + + /// Draw the parsed tree as PDF vectors. The limits account for the destination size and the + /// renderer's filter scale before krilla-svg allocates filter rasters. + pub fn draw(&self, surface: &mut krilla::surface::Surface<'_>, size: krilla::geom::Size, settings: SvgSettings) -> Result<(), Error> { + let width = f64::from(size.width()); + let height = f64::from(size.height()); + let scale = f64::from(settings.filter_scale); + if !width.is_finite() || !height.is_finite() || !scale.is_finite() || width <= 0.0 || height <= 0.0 || scale <= 0.0 { + return Err(Error::DrawLimit); + } + let area = width * height * (96.0_f64 / 72.0).powi(2); + let filter_area = area * scale * scale; + if !area.is_finite() || !filter_area.is_finite() || area > self.limits.vector_pixels as f64 || filter_area > self.limits.filter_pixels as f64 + { + return Err(Error::DrawLimit); + } + surface.draw_svg(&self.tree, size, settings).ok_or(Error::Draw) + } +} + +#[derive(Default)] +struct Usage { + svg_bytes: AtomicUsize, + svg_depth: AtomicUsize, + image_bytes: AtomicUsize, +} + +fn shared_limits(bytes: usize, limits: Limits) -> craft_svg::tree::Limits { + craft_svg::tree::Limits { + bytes, + depth: limits.depth, + refuse_entity_markup: true, + xml_nodes: limits.xml_nodes, + embedded_bytes: limits.embedded_svg_bytes, + embedded_depth: limits.embedded_svg_depth, + ..Default::default() + } +} + +fn bounded_text(bytes: &[u8], byte_limit: usize, limits: Limits) -> Result, craft_svg::tree::Error> { + craft_svg::tree::text(bytes, &shared_limits(byte_limit, limits)) +} + +fn reserve(counter: &AtomicUsize, amount: usize, limit: usize) -> bool { + counter.try_update(Ordering::Relaxed, Ordering::Relaxed, |used| used.checked_add(amount).filter(|next| *next <= limit)).is_ok() +} + +fn embedded_svg(usage: &Usage, limits: Limits, bytes: &[u8], options: &usvg::Options<'_>) -> Option { + let used = usage.svg_bytes.load(Ordering::Relaxed); + let remaining = limits.embedded_svg_bytes.saturating_sub(used); + let text = bounded_text(bytes, remaining.min(limits.input_bytes), limits).ok()?; + if !reserve(&usage.svg_bytes, text.len(), limits.embedded_svg_bytes) { + return None; + } + let depth = usage.svg_depth.fetch_add(1, Ordering::Relaxed); + if depth >= limits.embedded_svg_depth { + usage.svg_depth.fetch_sub(1, Ordering::Relaxed); + return None; + } + let parsed = usvg::Tree::from_str(&text, options).ok(); + usage.svg_depth.fetch_sub(1, Ordering::Relaxed); + parsed.map(usvg::ImageKind::SVG) +} + +fn image_resolver(limits: Limits) -> usvg::ImageHrefResolver<'static> { + let usage = Arc::new(Usage::default()); + let default_data = usvg::ImageHrefResolver::default_data_resolver(); + usvg::ImageHrefResolver { + resolve_data: Box::new(move |mime, bytes, options| { + if mime == "image/svg+xml" || (mime == "text/plain" && (craft_svg::sniff::is_svg(&bytes) || craft_svg::sniff::is_svgz(&bytes))) { + return embedded_svg(&usage, limits, &bytes, options); + } + if !reserve(&usage.image_bytes, bytes.len(), limits.embedded_image_bytes) { + return None; + } + default_data(mime, bytes, options) + }), + resolve_string: Box::new(|_, _| None), + } +} diff --git a/crates/prepress/src/lib.rs b/crates/prepress/src/lib.rs index 3fa4f472e..1afc7cf6f 100644 --- a/crates/prepress/src/lib.rs +++ b/crates/prepress/src/lib.rs @@ -12,6 +12,8 @@ pub mod flatten; pub mod ink; pub mod marks; pub mod output; +#[cfg(feature = "flatten")] +pub mod pdfx1a; pub mod plates; pub use cms::{CmsConversion, ProfileError}; diff --git a/crates/prepress/src/pdfx1a.rs b/crates/prepress/src/pdfx1a.rs new file mode 100644 index 000000000..0755424be --- /dev/null +++ b/crates/prepress/src/pdfx1a.rs @@ -0,0 +1,772 @@ +//! PDF/X-1a:2003: the PDF/X-4 print file flattened by craft-prepress (no transparency left; RGB +//! and ICC color converted into the output intent's CMYK; inks, overprint and live text kept), +//! written by krilla as PDF 1.4, given the PDF/X-1a identification and output intent, then +//! checked. Apps use [`flatten_x1a`] to flatten and finalize in one step, and [`check_pdfx1a`] +//! to inspect an existing file. + +use std::collections::{HashMap, HashSet}; + +use crate::flatten::pdf::ReadOptions; +use crate::flatten::{FlattenDocumentOptions, FlattenOptions, FlattenTotals, flatten_document}; +use craft_pdf::syntax::content::UntypedIter; +use craft_pdf::syntax::object::{Array, Dict, Name, Object, ObjectIdentifier, Stream}; +use craft_pdf::syntax::page::Resources; +use craft_pdf::write::backend::configure::PdfVersion; + +const MAX_DEPTH: usize = 16; + +/// `GTS_PDFXVersion` of PDF/X-1a:2003 (ISO 15930-4): the base level, PDF/X-1:2003. +const VERSION: &str = "PDF/X-1:2003"; + +/// `GTS_PDFXConformance` of PDF/X-1a:2003 (ISO 15930-4): with [`VERSION`], it names the +/// conformance level. +const CONFORMANCE: &str = "PDF/X-1a:2003"; + +/// `/RegistryName` of the ICC's registry of characterized printing conditions. An output intent +/// naming one of them needs no `/DestOutputProfile` in PDF/X. +const ICC_REGISTRY: &str = "http://www.color.org"; + +/// The graphics placed on one output page, to name in errors: the page's name and the graphics' +/// names. +#[derive(Clone, Debug, Default)] +pub struct PageGraphics { + pub label: String, + pub graphics: Vec, +} + +/// The PDF/X-1a file for `pdf`, the PDF/X-4 print file: flattened at `dpi`, written at PDF 1.4, +/// identified, checked. `pages` names each output page and its graphics for errors. Fails when +/// the flattener fails or leaves an image out, when the output intent's profile can't go into a +/// PDF 1.4 file, or when the result still has transparency or color outside DeviceCMYK, +/// DeviceGray, Separation and DeviceN; other check findings become warnings. +pub fn flatten_x1a(pdf: &[u8], dpi: f32, pages: &[PageGraphics]) -> Result<(Vec, Vec), String> { + let dpi = if dpi.is_finite() { dpi.clamp(36.0, 2400.0) } else { 300.0 }; + let opts = FlattenDocumentOptions { + read: ReadOptions { raster_dpi: dpi, ..ReadOptions::default() }, + flatten: FlattenOptions { raster_dpi: dpi, ..FlattenOptions::default() }, + producer: "DesignCraft".into(), + version: PdfVersion::Pdf14, + pdfx_version: Some(VERSION.into()), + ..FlattenDocumentOptions::default() + }; + let (bytes, report) = flatten_document(pdf, &opts).map_err(|e| format!("PDF/X-1a: the transparency flattener failed: {e}"))?; + let unread: Vec = report + .pages + .iter() + .filter(|(_, r)| r.read.unreadable_images > 0) + .map(|(page, r)| { + let n = r.read.unreadable_images; + let images = if n == 1 { "1 image".to_string() } else { format!("{n} images") }; + let fallback = PageGraphics { label: page.saturating_add(1).to_string(), graphics: Vec::new() }; + let at = pages.get(*page).unwrap_or(&fallback); + let names: Vec = at.graphics.iter().take(5).map(|g| format!("`{g}`")).collect(); + let more = if at.graphics.len() > 5 { ", …" } else { "" }; + let placed = if names.is_empty() { String::new() } else { format!(" (graphics on it: {}{more})", names.join(", ")) }; + format!("{images} on page {}{placed}", at.label) + }) + .collect(); + if !unread.is_empty() { + return Err(format!( + "PDF/X-1a: the transparency flattener couldn't read {}, and a PDF/X file can't leave images out: replace the graphic, or export without PDF/X-1a", + unread.join("; ") + )); + } + let mut warnings = flatten_warnings(&report.totals, dpi); + let bytes = finish_x1a(&bytes)?; + let (fatal, other) = checks(&bytes); + if !fatal.is_empty() { + return Err(format!("PDF/X-1a: after flattening, {}", fatal.join("; "))); + } + warnings.extend(other.into_iter().map(|issue| format!("PDF/X-1a: {issue}"))); + Ok((bytes, warnings)) +} + +/// What the flattener's `t` (at `dpi`) tells the user: rasterized transparency, and spot inks past +/// the ink set's capacity, whose tints the flattener drops. +pub fn flatten_warnings(t: &FlattenTotals, dpi: f32) -> Vec { + let mut out = Vec::new(); + if t.complex_regions > 0 || t.complex_groups > 0 { + let at = t.lowest_dpi.map(|d| format!(", some below {dpi:.0} ppi (lowest {d:.0} ppi)")).unwrap_or_default(); + out.push(format!("PDF/X-1a: transparency flattened: {} region(s) rasterized at {dpi:.0} ppi{at}", t.complex_regions + t.complex_groups)); + } + if t.dropped_inks > 0 { + out.push(format!( + "PDF/X-1a: the document has more spot inks than the flattener can separate: {} tint(s) in the inks past its limit were dropped and won't print", + t.dropped_inks + )); + } + out +} + +/// PDF/X-1a:2003 checks on an exported file (empty = passes them): PDF 1.4 or lower, the +/// identification (`GTS_PDFXVersion` and `GTS_PDFXConformance`), a CMYK `GTS_PDFX` output intent +/// whose profile, when it has one, is ICC v2 (and without one, names a registered printing +/// condition), `/Trapped` True or False, trim boxes, no encryption or interpolation; no +/// transparency (soft masks, transparency groups, constant opacity below 1, blend modes other +/// than Normal); only DeviceCMYK, DeviceGray, Separation and DeviceN (and Indexed and Pattern +/// spaces over them), a spot's alternate space process; every font embedded. +pub fn check_pdfx1a(pdf: &[u8]) -> Vec { + let (mut issues, other) = checks(pdf); + issues.extend(other); + issues +} + +/// [`check_pdfx1a`]'s findings: transparency and color spaces first, then the rest. +fn checks(pdf: &[u8]) -> (Vec, Vec) { + let mut issues = Vec::new(); + let text = String::from_utf8_lossy(pdf); + let file = craft_pdf::syntax::Pdf::new(pdf.to_vec()).ok(); + if !pdf.starts_with(b"%PDF-1.") || pdf.get(7).is_none_or(|v| *v > b'4') { + issues.push("the PDF version must be 1.4 or lower".into()); + } + if file.as_ref().is_none_or(|f| pdfx_intents(f).is_empty()) { + issues.push("no PDF/X output intent".into()); + } + let info = |key: &[u8]| file.as_ref().and_then(|f| info_text(pdf, f, key)); + if info(b"GTS_PDFXVersion").as_deref() != Some(VERSION) { + issues.push(format!("the document information doesn't name {VERSION}")); + } + if info(b"GTS_PDFXConformance").as_deref() != Some(CONFORMANCE) { + issues.push(format!("the document information doesn't name the conformance level {CONFORMANCE}")); + } + if !text.contains("/Trapped/False") && !text.contains("/Trapped/True") && !text.contains("/Trapped /False") && !text.contains("/Trapped /True") { + issues.push("the document information needs /Trapped True or False".into()); + } + if text.contains("/Interpolate true") { + issues.push("an image asks for interpolation".into()); + } + if text.contains("/Encrypt") { + issues.push("the file is encrypted".into()); + } + let pages = text.matches("/Type/Page/").count() + text.matches("/Type/Page>").count(); + let trims = text.matches("/TrimBox").count(); + if pages > 0 && trims < pages { + issues.push("every page needs a trim box".into()); + } + let (content, fonts) = content(file.as_ref()); + issues.extend(fonts); + (content, issues) +} + +/// Transparency and color spaces, then the output intent and fonts, walked through every page's +/// content and what it uses. +fn content(file: Option<&craft_pdf::syntax::Pdf>) -> (Vec, Vec) { + let Some(file) = file else { + return (vec!["the file couldn't be read to check its transparency and color spaces".into()], Vec::new()); + }; + let mut fonts = intent_issues(file); + let mut found: Vec<(String, Vec)> = Vec::new(); + let mut font_found: Vec<(String, Vec)> = Vec::new(); + for (i, page) in file.pages().iter().enumerate() { + let mut scan = Scan::default(); + let res = page.resources(); + if let Some(group) = page.raw().get::>(b"Group") { + scan.group(&group); + } + if let Some(content) = page.page_stream() { + scan.content(content, res, 0); + } + for (list, items) in [(&mut found, scan.found), (&mut font_found, scan.font_issues)] { + for what in items { + match list.iter_mut().find(|(w, _)| *w == what) { + Some((_, pages)) => pages.push(i + 1), + None => list.push((what, vec![i + 1])), + } + } + } + } + let on_pages = |(what, pages): (String, Vec)| { + let list: Vec = pages.iter().take(10).map(|p| p.to_string()).collect(); + let more = if pages.len() > 10 { ", …" } else { "" }; + let s = if pages.len() == 1 { "" } else { "s" }; + format!("{what} on page{s} {}{more}", list.join(", ")) + }; + fonts.extend(font_found.into_iter().map(on_pages)); + (found.into_iter().map(on_pages).collect(), fonts) +} + +/// A `GTS_PDFX` output intent, as PDF/X-1a judges it. +struct Intent { + /// Its object number, when it is an indirect object. + obj: Option, + /// `/OutputCondition`, else `/OutputConditionIdentifier`, for messages. + name: String, + /// An `/OutputConditionIdentifier` other than `Custom` in the ICC registry. + registered: bool, + /// Whether it has a `/DestOutputProfile`, and the profile's object number. + has_profile: bool, + profile_obj: Option, + /// The profile's `/N` and decoded bytes. + channels: Option, + profile: Option>, +} + +impl Intent { + /// The profile's ICC major version (byte 8 of its header). + fn major(&self) -> Option { + self.profile.as_deref()?.get(8).copied() + } + + /// "ICC v4", or what keeps the version from being read. + fn version(&self) -> String { + self.major().map_or_else(|| "unreadable".to_string(), |v| format!("ICC v{v}")) + } +} + +/// The catalog's `GTS_PDFX` output intents. +fn pdfx_intents(file: &craft_pdf::syntax::Pdf) -> Vec { + let number = |n: i32| usize::try_from(n).ok(); + raw_pdfx_intents(file) + .into_iter() + .map(|oi| { + let text = |key: &[u8]| { + oi.get::>(key) + .map(|s| String::from_utf8_lossy(s.as_bytes()).trim().to_string()) + .filter(|s| !s.is_empty()) + }; + let identifier = text(b"OutputConditionIdentifier"); + let registry = text(b"RegistryName"); + let profile = oi.get::>(b"DestOutputProfile"); + Intent { + obj: oi.obj_id().and_then(|id| number(id.obj_number)), + name: text(b"OutputCondition").or_else(|| identifier.clone()).unwrap_or_else(|| "?".into()), + registered: registry.is_some_and(|r| r.trim_end_matches('/') == ICC_REGISTRY) && identifier.as_deref().is_some_and(|i| i != "Custom"), + has_profile: oi.contains_key(b"DestOutputProfile"), + profile_obj: oi.get_ref(b"DestOutputProfile").and_then(|r| number(r.obj_number)), + channels: profile.as_ref().and_then(|p| p.dict().get::(b"N")), + profile: profile.and_then(|p| p.decoded().ok()).map(|b| b.into_owned()), + } + }) + .collect() +} + +fn raw_pdfx_intents<'a>(file: &'a craft_pdf::syntax::Pdf) -> Vec> { + let xref = file.xref(); + let Some(catalog) = xref.get::>(xref.root_id()) else { return Vec::new() }; + let Some(intents) = catalog.get::>(b"OutputIntents") else { return Vec::new() }; + intents.iter::>().filter(|oi| oi.get::>(b"S").is_some_and(|s| s.as_ref() == b"GTS_PDFX")).collect() +} + +fn info_text(pdf: &[u8], file: &craft_pdf::syntax::Pdf, key: &[u8]) -> Option { + let layout = Layout::read(pdf)?; + let at = layout.trailer.find("/Info")? + "/Info".len(); + let tail = layout.trailer.get(at..)?.trim_start(); + let (number, _) = tail.split_once(' ')?; + let id = number.parse::().ok()?; + let dict = file.xref().get::>(craft_pdf::syntax::object::ObjectIdentifier { obj_number: id, gen_number: 0 })?; + dict.get::>(key).map(|s| String::from_utf8_lossy(s.as_bytes()).trim().to_string()) +} + +/// What PDF/X-1a finds wrong with the file's output intent: a CMYK profile, ICC v2 (PDF 1.4 +/// allows no later version), or none for a registered printing condition. +fn intent_issues(file: &craft_pdf::syntax::Pdf) -> Vec { + let Some(oi) = pdfx_intents(file).into_iter().next() else { return Vec::new() }; + let mut issues = Vec::new(); + if oi.has_profile { + if oi.channels != Some(4) { + issues.push("the output intent has no CMYK destination profile".into()); + } + if oi.major() != Some(2) { + issues.push(format!("the output intent's profile is {}, and PDF/X-1a (PDF 1.4) allows only ICC v2 profiles", oi.version())); + } + } else if !oi.registered { + issues + .push(format!("the output intent has no destination profile and doesn't name a printing condition in the ICC registry ({ICC_REGISTRY})")); + } + issues +} + +/// krilla's PDF 1.4 file with what PDF/X-1a needs and krilla doesn't write, rewritten as one +/// revision: `GTS_PDFXConformance` in the document information and the XMP, and the output intent +/// of a registered printing condition without `/DestOutputProfile` (its profile is left out of +/// the file). An unregistered condition keeps its profile, which must then be ICC v2. +pub fn finish_x1a(pdf: &[u8]) -> Result, String> { + let unreadable = || "the flattened file couldn't be read to add the PDF/X-1a identification".to_string(); + let layout = Layout::read(pdf).ok_or_else(unreadable)?; + let file = craft_pdf::syntax::Pdf::new(pdf.to_vec()).map_err(|_| unreadable())?; + let mut bodies: HashMap> = HashMap::new(); + let info = int_after(&layout.trailer, "/Info").ok_or_else(unreadable)?; + let body = layout.body(pdf, info).ok_or_else(unreadable)?; + let (head, close) = body.split_at_checked(rfind(body, b">>").ok_or_else(unreadable)?).ok_or_else(unreadable)?; + bodies.insert(info, [head, format!("/GTS_PDFXConformance({CONFORMANCE})").as_bytes(), close].concat()); + let xref = file.xref(); + if let Some(meta) = xref.get::>(xref.root_id()).and_then(|c| c.get_ref(b"Metadata")).and_then(|r| usize::try_from(r.obj_number).ok()) + && let Some(xmp) = layout.body(pdf, meta).and_then(xmp_with_conformance) + { + bodies.insert(meta, xmp); + } + let mut stripped: Vec = Vec::new(); + for oi in pdfx_intents(&file) { + if !oi.has_profile { + continue; + } + if !oi.registered { + if oi.major() != Some(2) { + return Err(format!( + "the output intent's profile `{}` is {}, and PDF/X-1a (PDF 1.4) allows only ICC v2 profiles: choose a CMYK working space with an ICC v2 profile, or Coated FOGRA39", + oi.name, + oi.version() + )); + } + continue; + } + let (Some(obj), Some(profile)) = (oi.obj, oi.profile_obj) else { return Err(unreadable()) }; + let body = match bodies.get(&obj) { + Some(b) => b.clone(), + None => layout.body(pdf, obj).ok_or_else(unreadable)?.to_vec(), + }; + let key = format!("/DestOutputProfile {profile} 0 R"); + let at = find(&body, key.as_bytes(), 0).ok_or_else(unreadable)?; + let (before, rest) = body.split_at_checked(at).ok_or_else(unreadable)?; + let after = rest.get(key.len()..).ok_or_else(unreadable)?; + bodies.insert(obj, [before, after].concat()); + stripped.push(profile); + } + // A profile only the stripped intents named goes too. + let dropped: HashSet = stripped.iter().copied().filter(|p| references(pdf, *p) == stripped.iter().filter(|q| *q == p).count()).collect(); + layout.write(pdf, &bodies, &dropped).ok_or_else(unreadable) +} + +/// How often `n 0 R` appears in `pdf` (a stream that happens to hold those bytes counts too, which +/// only ever keeps an object). +fn references(pdf: &[u8], n: usize) -> usize { + let needle = format!("{n} 0 R"); + let mut count = 0; + let mut from = 0; + while let Some(at) = find(pdf, needle.as_bytes(), from) { + let before = at.checked_sub(1).and_then(|i| pdf.get(i)).is_none_or(|c| !c.is_ascii_digit()); + let after = pdf.get(at + needle.len()).is_none_or(|c| !c.is_ascii_alphanumeric()); + if before && after { + count += 1; + } + from = at + needle.len(); + } + count +} + +/// The body of an uncompressed XMP metadata stream object with the Adobe `pdfx` properties of +/// the identification (`GTS_PDFXVersion`, `GTS_PDFXConformance`) added and its `/Length` updated; +/// `None` when the stream is filtered or isn't XMP. +fn xmp_with_conformance(body: &[u8]) -> Option> { + let s0 = find(body, b"stream", 0)?; + let dict = String::from_utf8_lossy(body.get(..s0)?).to_string(); + let s0 = s0 + b"stream".len(); + let s0 = s0 + body.get(s0..)?.iter().take_while(|c| **c == b'\r' || **c == b'\n').count(); + let s1 = rfind(body, b"endstream")?; + let xml = String::from_utf8_lossy(body.get(s0..s1)?).trim_end().to_string(); + if dict.contains("/Filter") || !xml.contains("") { + return None; + } + let ids = format!( + "{VERSION}\ + {CONFORMANCE}" + ); + let xml = xml.replacen("", &format!("{ids}"), 1); + let i = dict.find("/Length")?; + let rest = dict.get(i + 7..)?.trim_start(); + let end = rest.find(|c: char| !c.is_ascii_digit()).unwrap_or(rest.len()); + let dict = format!("{}/Length {}{}", dict.get(..i)?, xml.len(), rest.get(end..)?); + Some(format!("\n{}\nstream\n{xml}\nendstream\n", dict.trim()).into_bytes()) +} + +fn find(bytes: &[u8], needle: &[u8], from: usize) -> Option { + (from <= bytes.len()).then(|| bytes.get(from..)?.windows(needle.len()).position(|w| w == needle).map(|at| at + from))? +} + +fn rfind(bytes: &[u8], needle: &[u8]) -> Option { + bytes.windows(needle.len()).rposition(|w| w == needle) +} + +fn int_after(text: &str, key: &str) -> Option { + let at = text.find(key)? + key.len(); + text.get(at..)?.trim_start().split(|c: char| !c.is_ascii_digit()).next()?.parse().ok() +} + +/// Where the objects of a single-revision file with a classic cross-reference table are. +struct Layout { + /// (object number, start, end), by start: from `n 0 obj` up to the next object or the table. + objects: Vec<(usize, usize, usize)>, + /// Where the cross-reference table starts. + table: usize, + /// The trailer dictionary. + trailer: String, + size: usize, +} + +impl Layout { + fn read(pdf: &[u8]) -> Option { + let sx = rfind(pdf, b"startxref")?; + let table: usize = std::str::from_utf8(pdf.get(sx + b"startxref".len()..)?).ok()?.split_whitespace().next()?.parse().ok()?; + let section = pdf.get(table..sx)?; + let t = find(section, b"trailer", 0)?; + let trailer = String::from_utf8_lossy(section.get(t + b"trailer".len()..)?).trim().to_string(); + if trailer.contains("/Prev") || trailer.contains("/XRefStm") { + return None; + } + let size = int_after(&trailer, "/Size")?; + let mut tokens = std::str::from_utf8(section.get(..t)?).ok()?.split_whitespace(); + if tokens.next()? != "xref" { + return None; + } + let mut starts: Vec<(usize, usize)> = Vec::new(); + let mut seen = HashSet::new(); + while let Some(first) = tokens.next() { + let first: usize = first.parse().ok()?; + let count: usize = tokens.next()?.parse().ok()?; + for i in 0..count { + let (offset, generation, kind) = (tokens.next()?, tokens.next()?, tokens.next()?); + if kind != "n" { + continue; + } + let n = first.checked_add(i)?; + let offset: usize = offset.parse().ok()?; + if generation != "00000" || offset >= table || n >= size || !seen.insert(n) { + return None; + } + starts.push((n, offset)); + } + } + // Free entries past the objects would only make the rewritten table longer. + let max = starts.iter().map(|(n, _)| *n).max().unwrap_or(0); + if size > max.saturating_mul(2).saturating_add(16) { + return None; + } + starts.sort_by_key(|(_, offset)| *offset); + let mut objects = Vec::with_capacity(starts.len()); + for (i, &(n, start)) in starts.iter().enumerate() { + let end = starts.get(i + 1).map_or(table, |(_, s)| *s); + if !pdf.get(start..end)?.starts_with(format!("{n} 0 obj").as_bytes()) { + return None; + } + objects.push((n, start, end)); + } + Some(Layout { objects, table, trailer, size }) + } + + /// Object `n` between `n 0 obj` and `endobj`. + fn body<'p>(&self, pdf: &'p [u8], n: usize) -> Option<&'p [u8]> { + let &(_, start, end) = self.objects.iter().find(|(m, _, _)| *m == n)?; + let obj = pdf.get(start..end)?; + obj.get(format!("{n} 0 obj").len()..rfind(obj, b"endobj")?) + } + + /// The file with the objects in `bodies` replaced and those in `dropped` left out, and a new + /// cross-reference table. + fn write(&self, pdf: &[u8], bodies: &HashMap>, dropped: &HashSet) -> Option> { + let first = self.objects.first().map_or(self.table, |o| o.1); + let mut out = pdf.get(..first)?.to_vec(); + let mut offsets = HashMap::new(); + for &(n, start, end) in &self.objects { + if dropped.contains(&n) { + continue; + } + offsets.insert(n, out.len()); + match bodies.get(&n) { + Some(body) => { + out.extend_from_slice(format!("{n} 0 obj").as_bytes()); + out.extend_from_slice(body); + out.extend_from_slice(b"endobj\n"); + } + None => out.extend_from_slice(pdf.get(start..end)?), + } + } + if !out.ends_with(b"\n") { + out.push(b'\n'); + } + let table = out.len(); + // The free entries, each pointing at the next. + let free: Vec = (1..self.size).filter(|n| !offsets.contains_key(n)).collect(); + let next: HashMap = free.iter().copied().zip(free.iter().skip(1).copied().chain([0])).collect(); + out.extend_from_slice(format!("xref\n0 {}\n{:010} 65535 f\r\n", self.size, free.first().copied().unwrap_or(0)).as_bytes()); + for n in 1..self.size { + let next = next.get(&n).copied().unwrap_or(0); + let entry = match offsets.get(&n) { + Some(offset) => format!("{offset:010} 00000 n\r\n"), + // A dropped object's number could be used again, at the next generation. + None if dropped.contains(&n) => format!("{next:010} 00001 f\r\n"), + None => format!("{next:010} 65535 f\r\n"), + }; + out.extend_from_slice(entry.as_bytes()); + } + out.extend_from_slice(format!("trailer\n{}\nstartxref\n{table}\n%%EOF\n", self.trailer).as_bytes()); + Some(out) + } +} + +/// Why a color space isn't allowed in PDF/X-1a, or `None` when it is. +fn disallowed(cs: &Object<'_>, res: &Resources<'_>, depth: usize) -> Option { + if depth > 4 { + return Some("a color space nested too deeply".into()); + } + match cs { + Object::Name(n) => match n.as_ref() { + b"DeviceCMYK" | b"CMYK" | b"DeviceGray" | b"G" | b"Pattern" => None, + b"DeviceRGB" | b"RGB" => Some("DeviceRGB color".into()), + b"Indexed" | b"I" => None, + other => match res.get_color_space(&Name::new_unescaped(other)) { + Some(named) if !matches!(named, Object::Name(_)) => disallowed(&named, res, depth + 1), + Some(Object::Name(m)) if m.as_ref() != other => disallowed(&Object::Name(m), res, depth + 1), + _ => Some(format!("the color space /{}", String::from_utf8_lossy(other))), + }, + }, + Object::Array(a) => { + let mut items = a.iter::>(); + let family = match items.next() { + Some(Object::Name(n)) => n, + _ => return Some("an unreadable color space".into()), + }; + match family.as_ref() { + b"ICCBased" => Some("ICC-based color".into()), + b"CalRGB" | b"CalGray" => Some("CIE-based (CalRGB/CalGray) color".into()), + b"Lab" => Some("Lab color".into()), + b"DeviceRGB" | b"RGB" => Some("DeviceRGB color".into()), + b"DeviceCMYK" | b"CMYK" | b"DeviceGray" | b"G" => None, + b"Indexed" | b"I" => items.next().and_then(|base| disallowed(&base, res, depth + 1)), + b"Pattern" => items.next().and_then(|base| disallowed(&base, res, depth + 1)), + b"Separation" | b"DeviceN" => { + let _names = items.next(); + let alt = items.next()?; + if let Some(why) = disallowed(&alt, res, depth + 1) { + return Some(format!("a spot color whose alternate space is {why}")); + } + let _tint = items.next(); + // NChannel attributes are PDF 1.6, past the 1.4 that PDF/X-1a:2003 allows. + let attrs = items.next().and_then(|o| match o { + Object::Dict(d) => Some(d), + _ => None, + }); + attrs + .filter(|a| a.get::>(b"Subtype").is_some_and(|n| n.as_ref() == b"NChannel") || a.contains_key(b"Process")) + .map(|_| "a DeviceN space with NChannel attributes (PDF 1.6)".into()) + } + other => Some(format!("the color space /{}", String::from_utf8_lossy(other))), + } + } + _ => Some("an unreadable color space".into()), + } +} + +/// What one page has that PDF/X-1a doesn't allow, in the order found. +#[derive(Default)] +struct Scan { + /// What was found, in the order found; `known` is the same as a set. + found: Vec, + known: HashSet, + font_issues: Vec, + seen: HashSet, + fonts: HashSet, +} + +impl Scan { + fn add(&mut self, what: String) { + if self.known.insert(what.clone()) { + self.found.push(what); + } + } + + fn space(&mut self, cs: &Object<'_>, res: &Resources<'_>) { + if let Some(why) = disallowed(cs, res, 0) { + self.add(why); + } + } + + fn content(&mut self, data: &[u8], res: &Resources<'_>, depth: usize) { + if depth > MAX_DEPTH { + return; + } + let mut ops = UntypedIter::new(data); + while let Some(op) = ops.next() { + let operator: &[u8] = op.operator; + let last = op.operands().last().cloned(); + let name = || last.clone().and_then(Object::into_name); + match operator { + b"rg" | b"RG" => self.add("DeviceRGB color".into()), + b"cs" | b"CS" => { + if let Some(n) = name() { + self.space(&Object::Name(n), res); + } + } + b"sh" => { + if let Some(sh) = name().and_then(|n| res.get_shading(&n)) { + self.shading(sh, res); + } + } + b"scn" | b"SCN" => { + if let Some(p) = name().and_then(|n| res.get_pattern(&n)) { + self.pattern(p, res, depth); + } + } + b"gs" => { + if let Some(gs) = name().and_then(|n| res.get_ext_g_state(&n)) { + self.ext_g_state(&gs, res, depth); + } + } + b"Tf" => { + let font = op.operands().next().cloned().and_then(Object::into_name).and_then(|n| res.get_font(&n)); + if let Some(font) = font { + self.font(&font, res, depth); + } + } + b"Do" => { + if let Some(xo) = name().and_then(|n| res.get_x_object(&n)) { + match xo.dict().get::>(b"Subtype").as_deref() { + Some(b"Image") => self.image(&xo, res), + Some(b"Form") => self.form(&xo, res, depth), + _ => {} + } + } + } + b"BI" | b"EI" => { + if let Some(Object::Stream(img)) = last + && let Some(cs) = img.dict().get::>(b"CS").or_else(|| img.dict().get::>(b"ColorSpace")) + { + self.space(&cs, res); + } + } + _ => {} + } + } + } + + fn ext_g_state(&mut self, gs: &Dict<'_>, res: &Resources<'_>, depth: usize) { + match gs.get::>(b"SMask") { + None => {} + Some(Object::Name(n)) if n.as_ref() == b"None" => {} + Some(mask) => { + self.add("a soft mask (transparency)".into()); + if let Some(form) = match mask { + Object::Dict(d) => d.get::>(b"G"), + _ => None, + } { + self.form(&form, res, depth); + } + } + } + for key in [&b"CA"[..], b"ca"] { + if gs.get::(key).is_some_and(|a| a < 1.0) { + self.add("constant opacity below 100% (transparency)".into()); + } + } + let normal = |n: &[u8]| matches!(n, b"Normal" | b"Compatible"); + match gs.get::>(b"BM") { + Some(Object::Name(n)) if !normal(n.as_ref()) => { + self.add(format!("the blend mode /{} (transparency)", String::from_utf8_lossy(n.as_ref()))) + } + Some(Object::Array(a)) if a.iter::>().any(|n| !normal(n.as_ref())) => { + self.add("a blend mode other than Normal (transparency)".into()) + } + _ => {} + } + } + + fn image(&mut self, img: &Stream<'_>, res: &Resources<'_>) { + if !self.seen.insert(img.obj_id()) { + return; + } + let d = img.dict(); + if d.get::>(b"SMask").is_some() { + self.add(format!("an image with a soft mask (object {}, transparency)", img.obj_id().obj_number)); + } + if d.get::(b"SMaskInData").is_some_and(|v| v != 0) { + self.add(format!("an image with transparency in its data (object {})", img.obj_id().obj_number)); + } + if d.get::(b"ImageMask") == Some(true) { + return; + } + match d.get::>(b"ColorSpace") { + Some(cs) => { + if let Some(why) = disallowed(&cs, res, 0) { + let (w, h) = (d.get::(b"Width").unwrap_or(0), d.get::(b"Height").unwrap_or(0)); + self.add(format!("{why} in an image (object {}, {w} × {h} px)", img.obj_id().obj_number)); + } + } + // JPX images may carry their own space; X-1a doesn't allow them. + None => self.add(format!("an image without a color space (object {})", img.obj_id().obj_number)), + } + } + + fn form(&mut self, form: &Stream<'_>, parent: &Resources<'_>, depth: usize) { + if depth >= MAX_DEPTH || !self.seen.insert(form.obj_id()) { + return; + } + let res = Resources::from_parent(form.dict().get::>(b"Resources").unwrap_or_default(), parent.clone()); + if let Some(group) = form.dict().get::>(b"Group") { + self.group(&group); + } + if let Ok(data) = form.decoded() { + self.content(&data, &res, depth + 1); + } + } + + fn group(&mut self, group: &Dict<'_>) { + if group.get::>(b"S").is_some_and(|s| s.as_ref() == b"Transparency") { + self.add("a transparency group".into()); + } + } + + fn shading(&mut self, sh: Object<'_>, res: &Resources<'_>) { + let dict = match sh { + Object::Dict(d) => d, + Object::Stream(s) => s.dict().clone(), + _ => return, + }; + if let Some(cs) = dict.get::>(b"ColorSpace") { + self.space(&cs, res); + } + } + + fn pattern(&mut self, p: Object<'_>, res: &Resources<'_>, depth: usize) { + match p { + Object::Dict(d) => { + if let Some(sh) = d.get::>(b"Shading") { + self.shading(sh, res); + } + if let Some(gs) = d.get::>(b"ExtGState") { + self.ext_g_state(&gs, res, depth); + } + } + Object::Stream(s) => self.form(&s, res, depth), + _ => {} + } + } + + /// Embedded: a simple font's descriptor, or a Type 0 font's descendant's, has a font file. A + /// Type 3 font's glyphs are content streams in the file, scanned like the page's. + fn font(&mut self, font: &Dict<'_>, parent: &Resources<'_>, depth: usize) { + if let Some(id) = font.obj_id() + && !self.fonts.insert(id) + { + return; + } + let name = font.get::>(b"BaseFont").map(|n| String::from_utf8_lossy(n.as_ref()).to_string()).unwrap_or_else(|| "?".into()); + let subtype = font.get::>(b"Subtype"); + let descriptor = match subtype.as_deref() { + Some(b"Type3") => return self.type3(font, parent, depth), + Some(b"Type0") => { + font.get::>(b"DescendantFonts").and_then(|a| a.iter::>().next()).and_then(|d| d.get::>(b"FontDescriptor")) + } + _ => font.get::>(b"FontDescriptor"), + }; + let embedded = descriptor.is_some_and(|d| [&b"FontFile"[..], b"FontFile2", b"FontFile3"].iter().any(|k| d.get::>(k).is_some())); + if !embedded { + self.font_issues.push(format!("the font {name} isn't embedded")); + } + } + + /// A Type 3 font's glyph procedures, with the font's resources over `parent`'s. + fn type3(&mut self, font: &Dict<'_>, parent: &Resources<'_>, depth: usize) { + if depth >= MAX_DEPTH { + return; + } + let res = Resources::from_parent(font.get::>(b"Resources").unwrap_or_default(), parent.clone()); + let Some(procs) = font.get::>(b"CharProcs") else { return }; + for key in procs.keys() { + if let Some(glyph) = procs.get::>(key.as_ref()) + && self.seen.insert(glyph.obj_id()) + && let Ok(data) = glyph.decoded() + { + self.content(&data, &res, depth + 1); + } + } + } +} diff --git a/crates/prepress/tests/flatten_document.rs b/crates/prepress/tests/flatten_document.rs index 165a80e9a..a24f5dfea 100644 --- a/crates/prepress/tests/flatten_document.rs +++ b/crates/prepress/tests/flatten_document.rs @@ -116,7 +116,6 @@ fn three_pages(font_bytes: &[u8]) -> Vec { s.pop(); text(s, &font, &face, (20.0, 110.0), 12.0, "World"); }); - drop(page); writer.finish().unwrap() } diff --git a/crates/xml/Cargo.toml b/crates/xml/Cargo.toml index f957fa625..02d68985b 100644 --- a/crates/xml/Cargo.toml +++ b/crates/xml/Cargo.toml @@ -13,3 +13,4 @@ workspace = true [dependencies] quick-xml = { version = "0.41", default-features = false } thiserror = { workspace = true } +serde = { workspace = true, features = ["derive"] } diff --git a/crates/xml/src/dtd.rs b/crates/xml/src/dtd.rs new file mode 100644 index 000000000..6bbca3554 --- /dev/null +++ b/crates/xml/src/dtd.rs @@ -0,0 +1,748 @@ +//! DTD content-model parsing and XML validation. + +//! Document Type Definitions: element declarations (content models) and required attributes, and +//! validation of an XML document against them (Structure ▸ Validate). + +use std::collections::HashMap; + +/// How much text parameter entities may add during expansion (a pass count is not an output +/// bound: each pass replaces whole strings, so references can inflate multiplicatively). +const MAX_EXPANDED_BYTES: usize = 1024 * 1024; + +/// A content particle: a name, a sequence, a choice, or one of those repeated (`?`, `*`, `+`). +#[derive(Clone, Debug, PartialEq)] +enum Cp { + Name(String), + Seq(Vec), + Choice(Vec), + Rep(Box, char), +} + +#[derive(Clone, Debug, PartialEq)] +enum Model { + Empty, + Any, + /// `(#PCDATA | a | b)*`: text and these elements in any order. + Mixed(Vec), + Children(Cp), +} + +/// A parsed DTD. +#[derive(Clone, Debug, Default)] +pub struct Dtd { + elements: Vec<(String, Model)>, + /// Element → its `#REQUIRED` attributes. + required: HashMap>, +} + +/// A problem found by validation: where (an element path such as `Root/story[2]`) and what. +#[derive(Clone, Debug, PartialEq, serde::Serialize)] +pub struct Problem { + pub path: String, + pub message: String, +} + +impl Dtd { + /// Declared element names, in order. + pub fn element_names(&self) -> impl Iterator { + self.elements.iter().map(|(n, _)| n.as_str()) + } + + fn model(&self, name: &str) -> Option<&Model> { + self.elements.iter().find(|(n, _)| n == name).map(|(_, m)| m) + } +} + +/// Markup declarations (``) with comments removed and quoted strings kept whole. +fn declarations(src: &str) -> Vec { + let mut out = Vec::new(); + let mut rest = src; + while let Some(i) = rest.find("").map_or("", |j| &rest[j + 3..]); + continue; + } + let mut quote = None; + let mut end = rest.len(); + for (k, c) in rest.char_indices().skip(2) { + match (quote, c) { + (Some(q), c) if c == q => quote = None, + (None, '"' | '\'') => quote = Some(c), + (None, '>') => { + end = k; + break; + } + _ => {} + } + } + out.push(rest[2..end].to_string()); + rest = rest.get(end + 1..).unwrap_or(""); + } + out +} + +fn tokens(s: &str) -> Vec { + let mut out = Vec::new(); + let mut cur = String::new(); + for c in s.chars() { + if c.is_whitespace() || "(),|?*+".contains(c) { + if !cur.is_empty() { + out.push(std::mem::take(&mut cur)); + } + if !c.is_whitespace() { + out.push(c.to_string()); + } + } else { + cur.push(c); + } + } + if !cur.is_empty() { + out.push(cur); + } + out +} + +/// How deeply groups may nest in a content model; parsing, matching (`ends`) and printing (`show`) +/// recurse once per level. +const MAX_CONTENT_MODEL_DEPTH: usize = 64; + +/// Parse a content particle from `t[*i..]`, inside `depth` enclosing groups. +fn particle(t: &[String], i: &mut usize, depth: usize) -> Result { + let base = match t.get(*i).map(String::as_str) { + Some("(") => { + if depth >= MAX_CONTENT_MODEL_DEPTH { + return Err(format!("content model nested more than {MAX_CONTENT_MODEL_DEPTH} levels")); + } + *i += 1; + let mut items = vec![particle(t, i, depth + 1)?]; + let mut sep = None; + loop { + match t.get(*i).map(String::as_str) { + Some(")") => { + *i += 1; + break; + } + Some(s @ ("," | "|")) => { + if sep.is_some_and(|p| p != s) { + return Err("mixed `,` and `|` in one group".into()); + } + sep = Some(if s == "," { "," } else { "|" }); + *i += 1; + items.push(particle(t, i, depth + 1)?); + } + other => return Err(format!("unexpected `{}` in a content model", other.unwrap_or("end"))), + } + } + if sep == Some("|") { Cp::Choice(items) } else { Cp::Seq(items) } + } + Some(n) if !"),|?*+".contains(n) => { + *i += 1; + Cp::Name(n.to_string()) + } + other => return Err(format!("unexpected `{}` in a content model", other.unwrap_or("end"))), + }; + Ok(match t.get(*i).map(String::as_str) { + Some(r @ ("?" | "*" | "+")) => { + *i += 1; + Cp::Rep(Box::new(base), r.chars().next().unwrap_or('*')) + } + _ => base, + }) +} + +fn parse_model(s: &str) -> Result { + let s = s.trim(); + match s { + "EMPTY" => return Ok(Model::Empty), + "ANY" => return Ok(Model::Any), + _ => {} + } + if s.contains("#PCDATA") { + let t = tokens(&s.replace("#PCDATA", " #PCDATA ")); + return Ok(Model::Mixed(t.into_iter().filter(|x| !"()|*".contains(x.as_str()) && x != "#PCDATA").collect())); + } + let t = tokens(s); + let mut i = 0; + let cp = particle(&t, &mut i, 0)?; + if i != t.len() { + return Err(format!("unexpected `{}` after the content model", t[i])); + } + Ok(Model::Children(cp)) +} + +/// How deeply parameter entities may nest: a reference in the DTD is level 1, a reference in its +/// value level 2, and so on. +const MAX_PARAMETER_ENTITY_DEPTH: usize = 64; + +/// Expand `%name;` references, one level per round, until a round changes nothing. +fn expand_parameter_entities(src: &str, ents: &[(String, String)]) -> Result { + let mut entities = HashMap::new(); + for (name, value) in ents { + entities.entry(name.as_str()).or_insert(value.as_str()); + } + let limit = src.len().saturating_add(MAX_EXPANDED_BYTES); + let append = |out: &mut String, value: &str| -> Result<(), String> { + if value.len() > limit.saturating_sub(out.len()) { + return Err(format!("parameter entities expand the DTD beyond {limit} bytes")); + } + out.push_str(value); + Ok(()) + }; + let too_deep = || format!("parameter entities refer to themselves or nest deeper than {MAX_PARAMETER_ENTITY_DEPTH} levels"); + let mut text = src.to_string(); + // The round after the deepest level changes nothing, hence one more round than levels. + for _ in 0..=MAX_PARAMETER_ENTITY_DEPTH { + let mut out = String::with_capacity(text.len()); + let mut rest = text.as_str(); + let mut changed = false; + while let Some(i) = rest.find('%') { + let (prefix, reference) = rest.split_at(i); + append(&mut out, prefix)?; + // `find` points to an ASCII `%`, so both split positions are UTF-8 boundaries. + rest = reference.split_at(1).1; + // A name has no whitespace and no `%` (`parse` ends a name at whitespace), whatever its + // length: the search for the closing `;` stops at the first of those, so the searches of + // a round never overlap and a round stays linear in the text. + let end = + rest.bytes().position(|b| matches!(b, b';' | b'%') || b.is_ascii_whitespace()).filter(|&k| rest.as_bytes().get(k) == Some(&b';')); + if let Some(end) = end + && let Some(value) = rest.get(..end).and_then(|name| entities.get(name)) + { + // A value that is its own reference (``) never gets anywhere. + if reference.get(..end + 2) == Some(*value) { + return Err(too_deep()); + } + append(&mut out, value)?; + changed = true; + rest = rest.split_at(end + 1).1; + continue; + } + append(&mut out, "%")?; + } + append(&mut out, rest)?; + text = out; + if !changed { + return Ok(text); + } + } + Err(too_deep()) +} + +/// Parse a DTD (its element and attribute-list declarations; parameter entities are expanded). +pub fn parse(src: &str) -> Result { + // Parameter entities first, then expand references and read the declarations again. + let mut ents: Vec<(String, String)> = Vec::new(); + for d in declarations(src) { + if let Some(rest) = d.strip_prefix("ENTITY") { + let rest = rest.trim_start(); + if let Some(rest) = rest.strip_prefix('%') { + let rest = rest.trim_start(); + let name: String = rest.chars().take_while(|c| !c.is_whitespace()).collect(); + let val = rest[name.len()..].trim(); + let q = val.chars().next().unwrap_or('"'); + if let Some(v) = val.strip_prefix(q).and_then(|v| v.find(q).map(|e| &v[..e])) { + ents.push((name, v.to_string())); + } + } + } + } + let text = expand_parameter_entities(src, &ents)?; + let mut dtd = Dtd::default(); + for d in declarations(&text) { + if let Some(rest) = d.strip_prefix("ELEMENT") { + let rest = rest.trim_start(); + let name: String = rest.chars().take_while(|c| !c.is_whitespace()).collect(); + let model = parse_model(&rest[name.len()..]).map_err(|e| format!(": {e}"))?; + dtd.elements.push((name, model)); + } else if let Some(rest) = d.strip_prefix("ATTLIST") { + // name (attr type default)*; only `#REQUIRED` matters here. + let mut words = Vec::new(); + let mut cur = String::new(); + let mut quote = None; + let mut group = 0; + for c in rest.chars() { + match (quote, c) { + (Some(q), c) if c == q => { + quote = None; + cur.push(c); + } + (Some(_), c) => cur.push(c), + (None, '"' | '\'') => { + quote = Some(c); + cur.push(c); + } + (None, '(') => { + group += 1; + cur.push(c); + } + (None, ')') => { + group -= 1; + cur.push(c); + } + (None, c) if c.is_whitespace() && group == 0 => { + if !cur.is_empty() { + words.push(std::mem::take(&mut cur)); + } + } + (None, c) => cur.push(c), + } + } + if !cur.is_empty() { + words.push(cur); + } + let Some((el, attrs)) = words.split_first() else { continue }; + let mut k = 0; + while k + 2 < attrs.len() { + let name = &attrs[k]; + let default = attrs.get(k + 2).map(String::as_str).unwrap_or(""); + if default == "#REQUIRED" { + dtd.required.entry(el.clone()).or_default().push(name.clone()); + } + k += if default == "#FIXED" { 4 } else { 3 }; + } + } + } + if dtd.elements.is_empty() { + return Err("no element declarations".into()); + } + Ok(dtd) +} + +/// What `ends` has worked out for one sequence of children: the end positions of a group (by the +/// address of its node, which lives as long as the model) from a position. +type EndsMemo = HashMap<(usize, usize), Vec>; + +/// End positions after `cp` matches a prefix of `seq[i..]`. +/// +/// The positions of each group are worked out once per start position (`memo`): nested repetitions +/// such as `((a*)*)*` ask the inner group for the same positions again and again, which is +/// exponential in their depth without it. +fn ends(cp: &Cp, seq: &[&str], i: usize, memo: &mut EndsMemo) -> Vec { + if let Cp::Name(n) = cp { + return if seq.get(i) == Some(&n.as_str()) { vec![i + 1] } else { vec![] }; + } + let key = (std::ptr::from_ref(cp) as usize, i); + if let Some(done) = memo.get(&key) { + return done.clone(); + } + let mut out: Vec = match cp { + Cp::Name(_) => vec![], + // Keep the positions after each item a set: as a list of every path, `(a?, a?, …)` doubles per item. + Cp::Seq(items) => { + let mut at = vec![i]; + for c in items { + let mut next = Vec::new(); + for p in at { + next.extend(ends(c, seq, p, memo)); + } + next.sort_unstable(); + next.dedup(); + at = next; + } + at + } + Cp::Choice(items) => { + let mut all = Vec::new(); + for c in items { + all.extend(ends(c, seq, i, memo)); + } + all + } + Cp::Rep(c, r) => { + let mut all = if *r == '+' { vec![] } else { vec![i] }; + let mut frontier = ends(c, seq, i, memo); + if *r == '?' { + all.extend(frontier); + } else { + while !frontier.is_empty() { + let new: Vec = frontier.iter().copied().filter(|p| !all.contains(p)).collect(); + all.extend(&new); + let mut next = Vec::new(); + for p in new.into_iter().filter(|&p| p > i) { + next.extend(ends(c, seq, p, memo).into_iter().filter(|p| !all.contains(p))); + } + // Two paths to one position are one position: kept apart they multiply per round. + next.sort_unstable(); + next.dedup(); + frontier = next; + } + } + all + } + }; + out.sort_unstable(); + out.dedup(); + memo.insert(key, out.clone()); + out +} + +fn show(cp: &Cp) -> String { + match cp { + Cp::Name(n) => n.clone(), + Cp::Seq(v) => format!("({})", v.iter().map(show).collect::>().join(", ")), + Cp::Choice(v) => format!("({})", v.iter().map(show).collect::>().join(" | ")), + Cp::Rep(c, r) => format!("{}{r}", show(c)), + } +} + +/// An element of the document being validated. +struct Node { + name: String, + attrs: Vec, + children: Vec, + text: bool, +} + +fn read_tree(xml: &str) -> Result { + use quick_xml::events::Event; + let mut r = quick_xml::Reader::from_str(xml); + let mut stack: Vec = Vec::new(); + let node = |e: &quick_xml::events::BytesStart| Node { + name: String::from_utf8_lossy(e.name().as_ref()).to_string(), + attrs: e.attributes().flatten().map(|a| String::from_utf8_lossy(a.key.as_ref()).to_string()).collect(), + children: vec![], + text: false, + }; + loop { + match r.read_event().map_err(|e| e.to_string())? { + Event::Start(e) => stack.push(node(&e)), + Event::Empty(e) => { + let n = node(&e); + match stack.last_mut() { + Some(p) => p.children.push(n), + None => return Ok(n), + } + } + Event::End(_) => { + let n = stack.pop().ok_or("unbalanced end tag")?; + match stack.last_mut() { + Some(p) => p.children.push(n), + None => return Ok(n), + } + } + Event::Text(t) => { + if let Some(p) = stack.last_mut() + && !t.iter().all(u8::is_ascii_whitespace) + { + p.text = true; + } + } + Event::CData(_) | Event::GeneralRef(_) => { + if let Some(p) = stack.last_mut() { + p.text = true; + } + } + Event::Eof => return Err("no root element".into()), + _ => {} + } + } +} + +fn check(dtd: &Dtd, n: &Node, path: &str, out: &mut Vec) { + let mut problem = |m: String| out.push(Problem { path: path.to_string(), message: m }); + match dtd.model(&n.name) { + None => problem(format!("`{}` isn't declared in the DTD", n.name)), + Some(Model::Any) => {} + Some(Model::Empty) => { + if n.text || !n.children.is_empty() { + problem(format!("`{}` should be empty", n.name)); + } + } + Some(Model::Mixed(allowed)) => { + for c in &n.children { + if !allowed.contains(&c.name) { + problem(format!("`{}` isn't allowed in `{}`", c.name, n.name)); + } + } + } + Some(Model::Children(cp)) => { + if n.text { + problem(format!("`{}` can't contain text", n.name)); + } + let seq: Vec<&str> = n.children.iter().map(|c| c.name.as_str()).collect(); + if !ends(cp, &seq, 0, &mut EndsMemo::new()).contains(&seq.len()) { + let got = if seq.is_empty() { "nothing".to_string() } else { seq.join(", ") }; + problem(format!("`{}` contains {got}; the DTD asks for {}", n.name, show(cp))); + } + } + } + for a in dtd.required.get(&n.name).into_iter().flatten() { + if !n.attrs.contains(a) { + problem(format!("`{}` is missing the required attribute `{a}`", n.name)); + } + } + let mut seen: HashMap<&str, usize> = HashMap::new(); + for c in &n.children { + let k = seen.entry(c.name.as_str()).or_default(); + *k += 1; + check(dtd, c, &format!("{path}/{}[{k}]", c.name), out); + } +} + +/// Validate `xml` against `dtd`; an empty list when it's valid. +pub fn validate(dtd: &Dtd, xml: &str) -> Vec { + match read_tree(xml) { + Ok(root) => { + let mut out = Vec::new(); + let path = root.name.clone(); + check(dtd, &root, &path, &mut out); + out + } + Err(e) => vec![Problem { path: String::new(), message: format!("not well-formed XML: {e}") }], + } +} + +#[cfg(test)] +mod tests { + use super::*; + + const DTD: &str = r##" + + + + + + + + + + b" kind (photo|chart) "photo">"##; + + #[test] + fn content_models_and_required_attributes() { + let dtd = parse(DTD).unwrap(); + assert_eq!(dtd.element_names().count(), 8); + let ok = r#"T <em>x</em>ab
"#; + assert_eq!(validate(&dtd, ok), vec![]); + let bad = r#"no title
x