Merge storytold main 3c59a2aa5 (sync 13 Nov)

This commit is contained in:
aiongg
2026-11-13 17:19:17 +00:00
325 changed files with 45433 additions and 1064 deletions
+2
View File
@@ -0,0 +1,2 @@
[lints]
cargo.unused_workspace_dependencies = "allow"
+14
View File
@@ -1,2 +1,16 @@
# Font-build test fixtures are compared byte for byte: a checkout must not convert them.
crates/fonts-build/tests/fixture/** -text
# The pinned font index is hashed and compiled in as committed: a checkout must not convert its
# line endings, or `Index::bundled` fails its checksum on Windows.
crates/font-store/index/sources.json -text
crates/font-store/index/indexes/*.gz binary
# Copies of the vendored krilla source diff, one per patch (see vendor/krilla/README.craft.md).
vendor/krilla/patches/*.patch linguist-generated=true
# Has a pinned digest and is embedded as bytes by craft-font-store.
crates/font-store/index/sources.json -text
# The build fixture verifies these license files are copied byte-for-byte.
crates/fonts-build/tests/fixture/craft-fonts/fonts/**/OFL.txt -text
+11
View File
@@ -50,3 +50,14 @@ jobs:
- name: Check inherited Linux ACLs
if: runner.os == 'Linux'
run: cargo test -p craft-atomic --locked -- --ignored --nocapture
wasm:
name: Atomic WASM
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@stable
with:
targets: wasm32-unknown-unknown
- run: cargo check -p craft-atomic --target wasm32-unknown-unknown
+26
View File
@@ -0,0 +1,26 @@
name: Colour management
on:
workflow_dispatch:
push:
branches: [main]
paths: ['crates/cms/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/cms.yml']
pull_request:
paths: ['crates/cms/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/cms.yml']
permissions:
contents: read
jobs:
cms:
timeout-minutes: 20
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@stable
with:
components: clippy
- run: cargo clippy -p craft-cms --all-targets --all-features --locked -- -D warnings
# Release: the FOGRA39 fit and ink-limit tests take about 35 s in debug and 4 s here. Tests that need
# installed system profiles print "skipped:" when none are present.
- run: cargo test -p craft-cms --all-features --release --locked -- --nocapture
+39
View File
@@ -0,0 +1,39 @@
name: Menu
on:
push:
branches: [main]
paths: ["crates/menu/**", "crates/keymap/**", "crates/quit/**", "Cargo.toml", "Cargo.lock", ".github/workflows/menu.yml"]
pull_request:
paths: ["crates/menu/**", "crates/keymap/**", "crates/quit/**", "Cargo.toml", "Cargo.lock", ".github/workflows/menu.yml"]
workflow_dispatch:
permissions:
contents: read
concurrency:
group: menu-${{ github.ref }}
cancel-in-progress: true
jobs:
linux:
timeout-minutes: 15
name: Menu (Linux)
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
with:
persist-credentials: false
- uses: dtolnay/rust-toolchain@b725eda525362e7cf34af9a7243cac1e3f01a7ec # stable
with:
components: rustfmt, clippy
targets: aarch64-apple-darwin, wasm32-unknown-unknown
- uses: Swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3
with:
key: craft-menu-linux
- run: cargo fmt -p craft-menu --check
- run: cargo clippy -p craft-menu --all-targets --locked -- -D warnings
# The macOS backend type-checks from Linux; it needs no linker or SDK.
- run: cargo clippy -p craft-menu --lib --locked --target aarch64-apple-darwin -- -D warnings
- run: cargo clippy -p craft-menu --lib --locked --target wasm32-unknown-unknown -- -D warnings
- run: cargo test -p craft-menu --locked
+2 -2
View File
@@ -3,9 +3,9 @@ name: Shared PDF
on:
push:
branches: [main]
paths: ["crates/pdf/**", "crates/plate-test/**", "crates/prepress/**", "crates/cms/**", "vendor/hayro*/**", "vendor/krilla/**", "scripts/test-pdf-backends.sh", "scripts/*fetch-pdf-test-fonts.py", "Cargo.toml", "Cargo.lock", ".github/workflows/pdf.yml"]
paths: ["crates/pdf/**", "crates/plate-test/**", "crates/prepress/**", "crates/cms/**", "vendor/hayro*/**", "vendor/krilla/**", "vendor/linesweeper/**","scripts/test-pdf-backends.sh", "scripts/*fetch-pdf-test-fonts.py", "Cargo.toml", "Cargo.lock", ".github/workflows/pdf.yml"]
pull_request:
paths: ["crates/pdf/**", "crates/plate-test/**", "crates/prepress/**", "crates/cms/**", "vendor/hayro*/**", "vendor/krilla/**", "scripts/test-pdf-backends.sh", "scripts/*fetch-pdf-test-fonts.py", "Cargo.toml", "Cargo.lock", ".github/workflows/pdf.yml"]
paths: ["crates/pdf/**", "crates/plate-test/**", "crates/prepress/**", "crates/cms/**", "vendor/hayro*/**", "vendor/krilla/**", "vendor/linesweeper/**","scripts/test-pdf-backends.sh", "scripts/*fetch-pdf-test-fonts.py", "Cargo.toml", "Cargo.lock", ".github/workflows/pdf.yml"]
workflow_dispatch:
permissions:
+77
View File
@@ -0,0 +1,77 @@
name: Workspace
on:
push:
branches: [main]
tags: ["v*"]
pull_request:
workflow_dispatch:
permissions:
contents: read
jobs:
native:
name: Workspace
uses: storytold/craft-common-actions/.github/workflows/gate.yml@main
with:
os: '["ubuntu-latest","windows-latest","macos-latest"]'
timeout-minutes: 120
tools: ""
packages: mesa-vulkan-drivers libvulkan1
craft-fonts-ref: b076417b5880bd4154bd22f00695b1d28c6bea83
linux-env: WGPU_BACKEND=vulkan
windows-env: CRAFT_PRINT_REQUIRE_QUEUE=1
env: CRAFT_PRINT_REQUIRE_QUEUE=0
setup-command: |
set -euo pipefail
corpus_fetcher=.test-inputs/photocraft
mkdir -p "$corpus_fetcher"
git -C "$corpus_fetcher" init
git -C "$corpus_fetcher" remote add origin https://github.com/storytold/PhotoCraft.git
git -C "$corpus_fetcher" fetch --quiet --depth=1 origin 74330157cb601573ae4523a95bb9132822fc3918
git -C "$corpus_fetcher" checkout --quiet --detach FETCH_HEAD
(cd "$corpus_fetcher" && cargo xtask corpus --psd --psd-tools --atn)
python scripts/test-fetch-pdf-test-fonts.py
python scripts/fetch-pdf-test-fonts.py "$RUNNER_TEMP/craft-pdf-test-fonts"
printf 'CRAFT_PSD_CORPUS=%s\n' "$GITHUB_WORKSPACE/$corpus_fetcher/corpus" >> "$GITHUB_ENV"
printf 'CRAFT_PDF_TEST_FONT_DIR=%s\n' "$RUNNER_TEMP/craft-pdf-test-fonts" >> "$GITHUB_ENV"
command: |
cargo fmt --check
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
cargo test --workspace --locked
cargo test --workspace --all-features --locked
windows-command: |
powershell.exe -NoProfile -Command '$ErrorActionPreference = "Stop"; Start-Service Spooler; Add-PrinterDriver -Name "Generic / Text Only"'
cargo fmt --check
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
cargo test --workspace --locked
cargo test --workspace --all-features --locked
msrv:
name: Rust 1.95
uses: storytold/craft-common-actions/.github/workflows/gate.yml@main
with:
os: '["ubuntu-latest"]'
toolchain: 1.95.0
targets: ""
tools: ""
craft-fonts-ref: ""
require-craft-fonts: false
timeout-minutes: 15
dev-debug: ""
command: cargo check --workspace --lib --all-features --locked
wasm:
name: UI and settings WASM
uses: storytold/craft-common-actions/.github/workflows/gate.yml@main
with:
os: '["ubuntu-latest"]'
targets: wasm32-unknown-unknown
tools: ""
craft-fonts-ref: ""
require-craft-fonts: false
timeout-minutes: 15
command: cargo check -p craft-ui -p craft-settings --all-features --locked --target wasm32-unknown-unknown
+3
View File
@@ -2,6 +2,9 @@
plan/
plans/
/target
# Also a sub-crate's own build directory: `crates/pdf/read-only-contract/target/` is not covered
# by the anchored `/target` above, and 803 of its files reached a commit once (#185 review).
target/
.DS_Store
/.claude/
.idea/
+1
View File
@@ -88,6 +88,7 @@ and the exact transfer revision are recorded in each vendored crate's SOURCE.jso
| `crates/raster-codecs/src/xpm/x11_colors.rs` | X.Org Foundation and X11 contributors (X11 `rgb.txt` colour names and values, normalised into a lookup table) | <https://cgit.freedesktop.org/xorg/app/rgb/tree/rgb.txt>, via [PhotoCraft `crates/codecs`](https://github.com/storytold/photocraft/tree/63b641b55e54bf8f5c83efd977fdb16a2c255431/crates/codecs/src/codecs/xpm) | MIT (X.Org app/rgb) |
| `crates/psd/tests/fixtures/atn/*.atn` (seven synthetic action sets, encoded field by field; `crates/psd/tests/fixtures/atn/README.md`) | PhotoCraft contributors | [PhotoCraft `crates/psd/tests/fixtures/atn`](https://github.com/storytold/photocraft/tree/63b641b55e54bf8f5c83efd977fdb16a2c255431/crates/psd/tests/fixtures/atn) | MIT OR Apache-2.0 |
| `crates/lottie/tests/fixtures/` | EffectCraft contributors (original work: four hand-written Lottie JSON documents, written from the public Lottie format description; not exported from any Adobe product or third-party file) | [EffectCraft `crates/lottie/tests/fixtures`](https://github.com/storytold/effectcraft/tree/e18f48fb/crates/lottie/tests/fixtures) | MIT OR Apache-2.0 |
| `crates/pkcs7/tests/data/` | PdfCraft contributors (original work: throw-away test keys and certificates made with OpenSSL 3 for these tests, as seven PKCS #12 files with the password `test` and two PEM certificates; they protect nothing; commands in `crates/pkcs7/tests/data/README.md`) | [PdfCraft `crates/sign/tests/data`](https://github.com/storytold/pdfcraft/tree/1d7a9f9f/crates/sign/tests/data) | MIT OR Apache-2.0 |
| `crates/affinity/tests/support/corpus.tsv`, `crates/affinity/tests/support/affinity3-signatures.txt` (manifest and measured signatures only; the 51 documents are not bundled, `scripts/fetch-affinity-corpus.sh` downloads them outside the checkout) | The authors of each document: samuel-etver (vector-art), Seth A. Robinson (Patchy fixtures), Nick Beeuwsaert (AFDesignLoad), Jeremy Cantu (Branding), eviltwo (AssetStoreTemplate), Square (leakcanary) | each file's pinned upstream URL and SHA-256 in the manifest; list carried over from [VectorCraft `xtask/src/affinity_corpus.rs`](https://github.com/storytold/vectorcraft/blob/6e873b806c9d5b3f2b55f651df57bd97933b579a/xtask/src/affinity_corpus.rs) | CC0-1.0, MIT or Apache-2.0 (per file, in the manifest) |
| `crates/raw/docs/coverage/adobe-cameras.tsv` | Facts (maker, model, extension, profile, minimum Camera Raw version) parsed by LightCraft contributors from Adobe's published list | [Adobe Camera Raw supported cameras](https://helpx.adobe.com/camera-raw/desktop/dng-and-file-formats/camera-raw-plug-supported-cameras.html), Wayback capture 20261003133011; moved from [LightCraft `docs/raw`](https://github.com/storytold/lightcraft/tree/5ff567a4a2e067bef1b6bce152c11e7f727ccbaf/docs/raw) | Facts, not copyrightable expression; the file is MIT OR Apache-2.0 |
| `crates/raw/docs/coverage/{coverage,coverage-sweep,evidence,usage-weights}.tsv`, `coverage.py` | LightCraft contributors | [LightCraft `docs/raw`](https://github.com/storytold/lightcraft/tree/5ff567a4a2e067bef1b6bce152c11e7f727ccbaf/docs/raw) | MIT OR Apache-2.0 |
+65
View File
@@ -0,0 +1,65 @@
# Changelog
All crates share the workspace version. See [the versioning policy](docs/versioning.md).
## v0.1.0 — 2026-10-12
First coordinated Git release of craft-libs. Applications can pin a named baseline instead of
following development commits. This is an initial 0.x release: compatibility is maintained
within `0.1.x`; changes requiring consumer migration use a new minor version.
### Included crates
- **craft-atomic:** same-directory staged file replacement, exclusive creation, streaming
writes, transient rename retries and fault-injection support, extracted from PhotoCraft.
- **craft-settings:** app-owned TOML settings with platform/portable paths, atomic saves,
backups, damaged-file recovery, schema migrations and preservation of unknown fields.
- **craft-quit:** native macOS termination, optional egui close handling and an optional
application menu. Save decisions and prompts stay with the app.
- **craft-print:** CUPS and native Windows PDF submission, printer discovery, copies, duplex,
colour and scaling options. Includes bounded PDF sheet handling and the pinned Windows
completion fix. PDF generation stays with the app.
- **craft-ui:** egui icon buttons, tabs, splits, resize handles, toolbar overflow, transactional
docking, theme helpers and print-settings controls. Commands, content, localization and
application state stay with the consumer. Docking serialization is opt-in through `serde`.
### Requirements and adoption
- Rust **1.95+**, edition 2024. Public UI integrations use **egui 0.36**.
- Use `git = "https://github.com/storytold/craft-libs", tag = "v0.1.0"` for each required crate;
use the same tag everywhere. The [README](README.md#use-a-released-version) has a complete
manifest example and a commit-pin alternative. Commit application lockfiles.
- No automatic migration from an arbitrary earlier Git revision is implied. Compare the API
you used with this release and test affected workflows before changing pins.
- For `craft-quit`, run the close hook last in `eframe::App::logic`, after the app's unsaved-work
decision. Finish asynchronous saves before requesting close; termination does not execute
code after `run_native`. See the crate's API documentation before adoption.
- This release is distributed through Git only. No crates.io packages are published by it.
### Platform coverage and known limits
The release gate checks the workspace on Linux, macOS and Windows with default and all features,
plus Linux minimum-compiler and UI/settings WASM checks. UI tests include offscreen visual
regressions. Windows print tests exercise a temporary paused spooler queue; those checks do
not establish physical printer fidelity or every application's native GUI behavior.
- `craft-ui` supports native and WASM use. Font coverage, bidirectional text and screen-reader
behavior still depend on the application and upstream stack; see [#17](https://github.com/storytold/craft-libs/issues/17).
- `craft-settings` persistence is native-only. WASM exposes settings traits, document helpers
and error types. Concurrent writers are best-effort, last-writer-wins; strict coordination
needs an application-owned lock.
- `craft-atomic` does not preserve all filesystem metadata during replacement. Directory sync
is best effort; tests do not prove physical power-loss durability. See its README's contract.
- `craft-quit`'s native behavior is macOS-specific; other platforms keep their normal close
path. Earlier hardware testing of the close hook is recorded in
[#3](https://github.com/storytold/craft-libs/issues/3); it does not qualify every consuming app.
- `craft-print` requires CUPS command-line tools on Linux/macOS or the native Windows spooler.
Browser submission is unsupported. Windows accepts a bounded subset of print-ready PDFs;
unsupported inputs and driver paper/scaling mismatches return errors. Printing is synchronous,
so call it from a worker. Physical output needs hardware testing.
- Windows printing retains a pinned Git dependency on the maintained `winprint` fork. Its
build dependencies require the license/advisory policy exceptions documented in
[craft-print's README](crates/print/README.md). Registry publication is deferred.
Planned crates and open feature PRs are not part of this release. Existing commit pins remain
valid, and consumers do not need to update simply because `main` changes.
Generated
+2028 -34
View File
File diff suppressed because it is too large Load Diff
+21
View File
@@ -46,9 +46,17 @@ craft-design-lint = { path = "crates/design-lint" }
craft-dialogs = { path = "crates/dialogs" }
craft-doc-binary = { path = "crates/doc-binary" }
craft-docx = { path = "crates/docx" }
craft-document-bundle = { path = "crates/document-bundle" }
craft-designcraft-format = { path = "crates/designcraft-format" }
craft-dxf = { path = "crates/dxf" }
craft-drawingml = { path = "crates/drawingml" }
craft-eps = { path = "crates/eps" }
craft-file-formats = { path = "crates/file-formats" }
craft-file-import = { path = "crates/file-import" }
vectorcraft-doc = { git = "https://github.com/storytold/vectorcraft.git", rev = "6b3a6b8788ebcb420d69449199cbdf323888d27e" }
vectorcraft-eps = { git = "https://github.com/storytold/vectorcraft.git", rev = "6b3a6b8788ebcb420d69449199cbdf323888d27e" }
vectorcraft-geom = { git = "https://github.com/storytold/vectorcraft.git", rev = "6b3a6b8788ebcb420d69449199cbdf323888d27e" }
vectorcraft-pathops = { git = "https://github.com/storytold/vectorcraft.git", rev = "6b3a6b8788ebcb420d69449199cbdf323888d27e" }
craft-doc = { path = "crates/doc" }
craft-docpath = { path = "crates/docpath" }
craft-dpx = { path = "crates/dpx" }
@@ -56,6 +64,7 @@ craft-draw = { path = "crates/draw" }
craft-ecproj-format = { path = "crates/ecproj-format" }
craft-figma-rest = { path = "crates/figma-rest" }
craft-exr = { path = "crates/exr" }
craft-flags = { path = "crates/flags" }
craft-font-catalog = { path = "crates/font-catalog" }
craft-font-manager = { path = "crates/font-manager" }
craft-font-store = { path = "crates/font-store" }
@@ -75,6 +84,7 @@ harfbuzz-subset-sys = { git = "https://github.com/storytold/harfbuzz.git", rev =
craft-host = { path = "crates/host" }
craft-i18n = { path = "crates/i18n" }
craft-idml = { path = "crates/idml" }
craft-indd = { path = "crates/indd" }
craft-jmap = { path = "crates/jmap" }
craft-ical = { path = "crates/ical" }
craft-imaging = { path = "crates/imaging" }
@@ -90,6 +100,7 @@ craft-latex = { path = "crates/latex" }
craft-markdown = { path = "crates/markdown" }
craft-math = { path = "crates/math" }
craft-media = { path = "crates/media", default-features = false }
craft-materialx = { path = "crates/materialx" }
craft-media-testkit = { path = "crates/media-testkit" }
craft-midi = { path = "crates/midi" }
craft-sf2 = { path = "crates/sf2" }
@@ -102,10 +113,13 @@ craft-menu = { path = "crates/menu" }
craft-metafile = { path = "crates/metafile" }
craft-offcrypto = { path = "crates/offcrypto" }
craft-opc = { path = "crates/opc" }
craft-openpgp = { path = "crates/openpgp" }
craft-ora = { path = "crates/ora" }
craft-pptx = { path = "crates/pptx" }
craft-penpot = { path = "crates/penpot" }
craft-pcraft-format = { path = "crates/pcraft-format" }
craft-pcraft-bundle = { path = "crates/pcraft-bundle" }
craft-pkcs7 = { path = "crates/pkcs7" }
craft-plotter = { path = "crates/plotter" }
craft-prepress = { path = "crates/prepress" }
craft-pages = { path = "crates/pages" }
@@ -121,8 +135,12 @@ craft-sheet = { path = "crates/sheet" }
craft-sketch = { path = "crates/sketch" }
craft-review = { path = "crates/review" }
craft-settings = { path = "crates/settings" }
craft-scraft-format = { path = "crates/scraft-format" }
craft-time = { path = "crates/time" }
craft-silhouette-studio = { path = "crates/silhouette-studio" }
craft-svg = { path = "crates/svg" }
craft-stencilcraft-format = { path = "crates/stencilcraft-format" }
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" }
@@ -149,6 +167,7 @@ craft-vectordrawable = { path = "crates/vectordrawable" }
craft-xls = { path = "crates/xls" }
craft-wordmodel = { path = "crates/wordmodel" }
craft-xlsx = { path = "crates/xlsx" }
indd = { git = "https://github.com/storytold/indd-utils", rev = "7f3060e5bce78d21ea70e0d5eacb96edce15dfbe" }
craft-xcf = { path = "crates/xcf" }
craft-xml = { path = "crates/xml" }
craft-zip = { path = "crates/zip" }
@@ -180,11 +199,13 @@ unsafe_code = "forbid"
# Every public item has a doc comment; a self-evident field or variant carries
# `#[allow(missing_docs)]` instead.
missing_docs = "warn"
unused_workspace_dependencies = "allow"
unexpected_cfgs = { level = "warn", check-cfg = ["cfg(craft_pdf_unicode_fixtures)"] }
[workspace.lints.clippy]
cognitive_complexity = "deny"
too_many_arguments = "deny"
unused_workspace_dependencies = "allow"
wildcard_imports = "deny"
dbg_macro = "warn"
todo = "warn"
+3 -3
View File
@@ -241,10 +241,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
vendor/linesweeper with its upstream license files and one local patch. 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/README.craft.md and vendor/linesweeper/SOURCE.json for provenance, the local patch
and the files left out.
Platform lifecycle source provenance
+43 -2
View File
@@ -17,12 +17,41 @@ A Cargo workspace (edition 2024, resolver 3). Each library is a crate under `cra
(`license.workspace = true`, and so on) and `[lints] workspace = true`. Register each crate in
`[workspace.dependencies]` in the root `Cargo.toml`.
Apps depend on a crate by git:
## Use a released version
The first coordinated release is **[v0.1.0](https://github.com/storytold/craft-libs/releases/tag/v0.1.0)**.
It gives consumers a fixed baseline while development continues on `main`. All five crates
share this version. They require Rust 1.95 or later; the UI integrations use egui 0.36.
Add only the crates you need, using the same tag for every craft-libs dependency:
```toml
craft-<name> = { git = "https://github.com/storytold/craft-libs", rev = "<commit>" }
[dependencies]
craft-ui = { git = "https://github.com/storytold/craft-libs", tag = "v0.1.0" }
craft-settings = { git = "https://github.com/storytold/craft-libs", tag = "v0.1.0" }
# Optional, for egui close handling and the macOS application menu:
craft-quit = { git = "https://github.com/storytold/craft-libs", tag = "v0.1.0", features = ["menu"] }
```
`craft-atomic` and `craft-print` use the same dependency syntax. Enable `craft-ui`'s
`serde` feature if you need to serialize its docking layout. These are Git releases;
crates.io publication is deferred.
Release tags are never moved or reused. For a commit pin, resolve the tag with
`git ls-remote https://github.com/storytold/craft-libs 'refs/tags/v0.1.0^{}'` and replace
`tag = "v0.1.0"` with `rev = "<full commit SHA>"` on every craft-libs dependency.
Use either `tag` or `rev`, not both. An existing commit pin keeps working; switching to this
release may require adapting to changes since that commit.
Commit your application's `Cargo.lock` and build with `cargo build --locked` for reproducible
Rust dependency resolution. A Git pin fixes craft-libs source, not every transitive dependency.
A library's own lockfile does not constrain its downstream consumers. Upgrade deliberately:
read the release notes, update all craft-libs pins together, refresh the lockfile with
`cargo check`, and run your application's tests and affected workflows before committing.
See the [release notes](CHANGELOG.md) for included functionality and known limits, and the
[versioning policy](docs/versioning.md) for compatibility guarantees and release checks.
## Libraries
- [`craft-platform`](crates/platform/README.md): optional native dialog lifecycle, Linux/BSD desktop appearance observation and browser download ownership; application policy stays in the apps.
@@ -123,6 +152,7 @@ craft-<name> = { git = "https://github.com/storytold/craft-libs", rev = "<commit
and channel names, the channels that make a colour picture, and Cryptomatte IDs, metadata keys,
manifests and rank channels. The optional `decode` feature adds bounded part listing, flat
decoding (scan lines, tiles, every compression of the `exr` crate) and writing.
- [`craft-flags`](crates/flags/README.md): Feature flags shared by the Craft apps and the ArtCraft Launcher: one per-user `ArtCraft/flags.toml`, a `CRAFT_FLAGS` override, every flag off by default (`AI-MCP`, `AI-MODELS`).
- [`craft-flow`](crates/flow/README.md): the flow model every text format maps to (paragraphs with a kind, lists and formatted spans; tables; pictures, fields, notes, equations), converted to and from a craft-wordmodel `Document`.
- [`craft-imaging`](crates/imaging/README.md): raster image editing; the scope counting (every
target) and, with the `ui` feature, the warp grid, the levels editor, the Channels panel and the
@@ -187,6 +217,8 @@ craft-<name> = { git = "https://github.com/storytold/craft-libs", rev = "<commit
CCITT Group 3 and 4 decoding and Group 4 encoding, JBIG2 decoding and lossless encoding. Every
decoder is bounded and returns its partial output on damage. From PdfCraft; a PDF filter chain
is built on it in `craft-pdf`.
- [`craft-time`](crates/time/README.md): exact rational ticks and SMPTE time across media, with a `soundcraft` compatibility module retaining SoundCraft's sample-index timebase, tempo maps, grids and session serialization semantics.
- [`craft-scraft-format`](crates/scraft-format/README.md): SoundCraft's typed `.scraft` session schema, versioned reader/writer, hostile-input validation, and `.scraftz` bundle reader/writer. Engine and UI mapping stays in SoundCraft.
- [`craft-tiff`](crates/tiff/README.md): TIFF and BigTIFF IFD reader and writer, from LightCraft:
every field type, the IFD chain, SubIFDs and Exif/GPS/Interop pointer IFDs, maker-note IFDs
(Canon, Nikon, Sony, Fujifilm, Olympus, Panasonic, Pentax), strip and tile layout. Bounded and
@@ -254,6 +286,9 @@ craft-<name> = { git = "https://github.com/storytold/craft-libs", rev = "<commit
header fields, MIME parts and multiparts, encoded-words, RFC 2231 parameters, base64 and
quoted-printable, character sets, address lists, dates, mbox files and the `multipart/related`
lookups of MHT web archives. What a message means (body, attachments, flags) stays in each app.
- [`craft-openpgp`](crates/openpgp/README.md): OpenPGP as mail carries it: PGP/MIME and cleartext
Digital signatures checked, attached Public keys and `Autocrypt:` headers read, a secret key
file inspected without using it. Built on rPGP; no I/O, and every size and count is capped.
- [`craft-odf`](crates/odf/README.md): OpenDocument packages (ODF 1.3 Part 2), read and written: the ZIP container with its `mimetype` and manifest within limits, password protection (AES-256-CBC with PBKDF2, as LibreOffice writes it) and flat single-file documents. With the `text` feature, OpenDocument Text documents read into and written from the craft-flow model.
- [`craft-prc`](crates/prc/README.md): a reader for PRC (ISO 14739-1), the 3D model format of PDF 3D
annotations: container, bit-level primitives, schema, tessellations and the product tree as
@@ -271,6 +306,10 @@ craft-<name> = { git = "https://github.com/storytold/craft-libs", rev = "<commit
- [`craft-pcraft-format`](crates/pcraft-format/README.md): the envelope of PhotoCraft's `.pcraft`
bundle: `Manifest<D>` with the document as a type parameter, `TileRef`, the entry paths, the
manifest decode limits and the migration runner. The document model stays in PhotoCraft.
- [`craft-pkcs7`](crates/pkcs7/README.md): the formats of digital signatures, read, verified and
written: ASN.1 DER, X.509 certificates and chains, CMS SignedData (PKCS #7), PKCS #12 identity
files, RFC 3161 timestamps, and CRL / OCSP revocation evidence. What a signature means for a
document or a message stays in each app.
- [`craft-penpot`](crates/penpot/README.md): clean-room reader and writer for the Penpot 2.x export
container (`.penpot`): the ZIP archive, its manifest, the per-file, per-page and per-shape JSON
members and media objects, as the JSON the file holds. Bounded on hostile input. Carved from
@@ -308,6 +347,8 @@ craft-<name> = { git = "https://github.com/storytold/craft-libs", rev = "<commit
- [`craft-sheet`](crates/sheet/README.md): spreadsheet vocabulary shared by `craft-xls`, `craft-xlsx` and `craft-ods`: cell positions and A1 text, cell values and error values, sheet-name quoting, Excel's built-in number formats and indexed colour palette. Not a file format; no dependencies.
- [`craft-sf2`](crates/sf2/README.md): SoundFont 2 (`.sf2`) reader: the sample pool and, per preset, the key and velocity regions a note sounds, with tuning, loop points, pan, level and volume envelope resolved from the preset and instrument zones. Bounded on hostile input. From LoopCraft.
- [`craft-silhouette-studio`](crates/silhouette-studio/src/lib.rs): bounded, fail-closed reader for Silhouette Studio `.studio` and `.studio3` documents: outlines, line colours and page size in millimetres. Protected designs are refused.
- [`craft-stencilcraft-format`](crates/stencilcraft-format/README.md): the versioned `.stencilcraft` JSON wire schema and envelope: required members, version 1 defaults, optional fields, and header checks.
- `craft-stencilcraft-document`: StencilCraft's typed document model, geometry helpers, validation, and native `.stencilcraft` codec.
- [`craft-sketch`](crates/sketch/README.md): clean-room reader for the `.sketch` container (Sketch 48 and newer): the ZIP archive, the version cut, `document.json`, the pages in document order and images, as the JSON the file holds. Bounded on hostile input. Carved from FigCraft.
- [`craft-svg`](crates/svg/src/lib.rs): SVG. `sniff` recognises SVG and SVGZ data; `svgz` unpacks
SVGZ within a byte limit, decodes UTF-8, UTF-16 and ISO 8859-1, and compresses; `guard` bounds
+5 -1
View File
@@ -558,7 +558,11 @@ pub fn temp_name(file: &str) -> String {
static COUNTER: AtomicU64 = AtomicU64::new(0);
let n = COUNTER.fetch_add(1, Ordering::Relaxed);
let stem: String = file.chars().take(64).collect();
format!(".{stem}.{}-{n}.craft_tmp", std::process::id())
#[cfg(not(target_arch = "wasm32"))]
let pid = std::process::id();
#[cfg(target_arch = "wasm32")]
let pid = 0;
format!(".{stem}.{pid}-{n}.craft_tmp")
}
/// The end of an error message: whether an original file was left as it was.
+19 -1
View File
@@ -7,7 +7,11 @@ struct TempDir(PathBuf);
impl TempDir {
fn new(tag: &str) -> Self {
static N: AtomicU64 = AtomicU64::new(0);
let d = std::env::temp_dir().join(format!("craft-atomic-{tag}-{}-{}", std::process::id(), N.fetch_add(1, Ordering::Relaxed)));
#[cfg(not(target_arch = "wasm32"))]
let pid = std::process::id();
#[cfg(target_arch = "wasm32")]
let pid = 0;
let d = std::env::temp_dir().join(format!("craft-atomic-{tag}-{pid}-{}", N.fetch_add(1, Ordering::Relaxed)));
let _ = std::fs::remove_dir_all(&d);
std::fs::create_dir_all(&d).ok();
Self(d)
@@ -188,3 +192,17 @@ fn distinguishes_atomicity_and_durability_order() {
);
}
}
#[test]
fn temp_name_format_is_valid() {
let name = temp_name("document.craft");
assert!(name.starts_with(".document.craft."));
assert!(name.ends_with(".craft_tmp"));
}
#[cfg(target_arch = "wasm32")]
#[test]
fn wasm_atomic_write_returns_unsupported() {
let err = atomic_write(Path::new("dummy.craft"), b"data").unwrap_err();
assert_eq!(err.kind(), io::ErrorKind::Unsupported);
}
+7 -5
View File
@@ -1,7 +1,7 @@
[package]
autotests = false
name = "craft-audio"
description = "Audio file I/O and codecs: WAV/AIFF read and write, FLAC encoder, AAC and ALAC decoders and encoders, AC-3/E-AC-3 decoder and encoder, MP3 encoder, Opus and MP1/MP2 decoders."
description = "Audio file I/O and codecs: WAV/AIFF read and write, FLAC encoder, AAC and ALAC decoders and encoders, AC-3/E-AC-3 decoder and encoder, MP3 decoder and encoder, Opus and MP1/MP2 decoders."
version.workspace = true
edition.workspace = true
license.workspace = true
@@ -15,12 +15,12 @@ all-features = true
workspace = true
[features]
# Probe and decode files: WAV and AIFF natively; AAC, ALAC, Opus, AC-3/E-AC-3, MP1/MP2 and PCM
# through craft-media's demuxers and this crate's decoders; MP3, FLAC, Vorbis, CAF, ADPCM, A-law
# and µ-law through symphonia.
# Probe and decode files: WAV and AIFF natively; AAC, ALAC, Opus, AC-3/E-AC-3, MP1/MP2/MP3 and
# PCM through craft-media's demuxers and this crate's decoders; FLAC, Vorbis, CAF, ADPCM, A-law,
# µ-law and free-format MP3 through symphonia.
decode = ["decode-native", "symphonia"]
# `decode` without symphonia: only the formats with a native decoder (others are Unsupported).
decode-native = ["aac-decode", "alac-decode", "opus-decode", "ac3-decode", "mpa-decode", "craft-media/isobmff", "craft-media/matroska", "craft-media/ogg", "dep:log"]
decode-native = ["aac-decode", "alac-decode", "opus-decode", "ac3-decode", "mpa-decode", "mp3-decode", "craft-media/isobmff", "craft-media/matroska", "craft-media/ogg", "dep:log"]
# 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 and MP3 encoders.
@@ -37,6 +37,8 @@ aac-encode = ["craft-media/bitstream"]
opus-decode = []
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-decode = []
alac-encode = []
+19 -14
View File
@@ -1,7 +1,7 @@
# craft-audio
Audio file I/O and codecs for the Craft apps. Native implementations: WAV and AIFF read/write,
FLAC encoder, AAC and ALAC decoders/encoders, AC-3/E-AC-3 decoder/encoder, MP3 encoder, Opus and MP1/MP2 decoders.
FLAC encoder, AAC and ALAC decoders/encoders, AC-3/E-AC-3 decoder/encoder, MP3 decoder/encoder, Opus and MP1/MP2 decoders.
Formats without a native decoder are decoded by [symphonia](#symphonia), which is to be replaced
by native decoders.
@@ -26,7 +26,7 @@ No default features. The shared types (`AudioBuffer`, `AudioInfo`, `ChannelLayou
| Feature | Provides | Pulls in |
|---|---|---|
| `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 five decoders below, craft-media `isobmff`/`matroska`/`ogg`, `log` |
| `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 and MP3 encoders | `lossless-encode`, `aac-encode`, `alac-encode`, `ac3-encode`, `eac3-encode`, `mp3-encode` |
| `lossless-encode` | WAV, AIFF and FLAC writing | `pcm-encode`, `flac-encode` |
@@ -39,12 +39,14 @@ No default features. The shared types (`AudioBuffer`, `AudioInfo`, `ChannelLayou
| `ac3-decode` | `ac3::Decoder`, `ac3::ProgrammeDecoder` | craft-media `bitstream` |
| `ac3-encode`, `eac3-encode` | `ac3::encoder::Encoder` | 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` |
| `peaks` | `peaks::Peaks` | none |
| `rayon` | parallel AAC encoding (with `aac-encode`) | `rayon` |
| `serde` | `Serialize`/`Deserialize` on the shared types | `serde` |
Any one decoder feature (`aac-decode`, `alac-decode`, `opus-decode`, `ac3-decode`, `mpa-decode`)
Any one decoder feature (`aac-decode`, `alac-decode`, `opus-decode`, `ac3-decode`, `mpa-decode`,
`mp3-decode`)
also gives `TrackDecoder`, for that codec and PCM.
An app that decodes 32-bit FLAC with `decode` needs a profile override in its workspace; see
@@ -307,30 +309,31 @@ match craft_audio::decode(&bytes, None) {
| AIFF, AIFF-C | native | native |
| FLAC | symphonia | native |
| AAC-LC | native | native |
| HE-AAC v1/v2 | native, core only (see [Limits](#limits)) | — |
| HE-AAC v1 | native (SBR) | — |
| HE-AAC v2 | native, without parametric stereo (see [Limits](#limits)) | — |
| ALAC | native | native, packets (`alac::Encoder`; no file writer) |
| MP1, MP2 (MPEG audio Layer I/II) | native | — |
| MP3 (Layer III) | symphonia | native, frames (`mp3::Encoder`; the frames in a row are an `.mp3` file) |
| MP3 (Layer III) | native | native, frames (`mp3::Encoder`; the frames in a row are an `.mp3` file) |
| Opus | native | — |
| AC-3, E-AC-3 | native | native packet encoder |
| Vorbis, ADPCM, A-law, µ-law | symphonia | — |
| Container | Demuxer | Timing |
|---|---|---|
| MP4, M4A, MOV | `craft_media::isobmff` for native codecs; symphonia for the others (MP3, FLAC) | edit lists (AAC priming, Opus pre-skip) |
| Matroska, WebM | `craft_media::matroska` for native codecs; symphonia for the others (Vorbis, FLAC, MP3) | `CodecDelay`, `DiscardPadding` |
| MP4, M4A, MOV | `craft_media::isobmff` for native codecs; symphonia for the others (FLAC) | edit lists (AAC priming, Opus pre-skip) |
| Matroska, WebM | `craft_media::matroska` for native codecs; symphonia for the others (Vorbis, FLAC) | `CodecDelay`, `DiscardPadding` |
| Ogg | `craft_media::ogg` (Opus); symphonia (Vorbis, FLAC) | pre-skip, end trimming |
| Raw ADTS AAC, AC-3, E-AC-3, MP1/MP2 | native frame sync | — |
| Raw MP3 | symphonia | — |
| Raw MP3 | native frame sync; symphonia for the free format | Xing / Info / VBRI frame skipped; LAME tag encoder delay and padding |
| FLAC | symphonia | — |
| CAF | symphonia | — |
## Limits
- HE-AAC: the AAC-LC core is decoded. `decode`, `Decoder` and `TrackDecoder` upsample it 2×;
`aac::Decoder` alone outputs the core rate. SBR is not reconstructed, so there is no content
above the core's Nyquist frequency.
- HE-AAC v2: parametric stereo is not reconstructed either, so the mono core decodes as mono.
- HE-AAC: `decode`, `Decoder` and `TrackDecoder` decode SBR at twice the core rate.
`aac::Decoder` outputs the core rate unless `set_sbr(true)` is called. Downsampled SBR (an
output rate equal to the core rate) plays the core alone.
- HE-AAC v2: parametric stereo is not reconstructed, so the mono core decodes as mono, with SBR.
- AAC: Main, SSR and LTP profiles, coupling channels and 960-sample frames are unsupported.
- Raw ADTS: frames with several raw data blocks are unsupported: a stream of them is refused, and
one among other frames decodes as silence of its length and counts as damaged, as does a frame
@@ -369,7 +372,7 @@ match craft_audio::decode(&bytes, None) {
- `ChannelLayout::unordered` is written to FLAC as mask `0x0000`, as RFC 9639 §8.6.2 allows, but
ffmpeg and `flac -d` ignore that mask and use their default layout for the channel count.
- Not decoded at all: Speex.
- `TrackDecoder` returns `Unsupported` for MP3, FLAC and Vorbis; `decode` and `Decoder` read
- `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,
@@ -411,10 +414,11 @@ Each codec module's rustdoc lists the coding tools it implements.
|---|---|---|---|
| WAV, AIFF | Microsoft RIFF, Apple AIFF/AIFF-C | read: integer 8–32-bit, float 32/64-bit, `WAVE_FORMAT_EXTENSIBLE` masks, RF64/BW64, BWF `bext`, truncated files; write: 16/24/32-bit integer and 32-bit float, RF64 above 4 GiB, any layout, TPDF dither | round trips; hostile-input tests |
| FLAC encoder | RFC 9639 | 16, 24, 32 bits; 1–8 channels, layouts decoders would not assume for the count as a `WAVEFORMATEXTENSIBLE_CHANNEL_MASK` comment; up to 655,350 Hz; LPC, stereo decorrelation, wasted bits, STREAMINFO MD5 | bit-exact through ffmpeg, STREAMINFO MD5 checked against ffmpeg |
| AAC (`aac`) | ISO/IEC 14496-3 | AAC-LC decode and encode (CBR, VBR, ADTS), 1–8 channels; HE-AAC: see [Limits](#limits) | ffmpeg: ~135 dB SNR; PNS noise differs per sample at equal band energy |
| AAC (`aac`) | ISO/IEC 14496-3; SBR tables from ETSI ES 201 980 Annex I | AAC-LC decode and encode (CBR, VBR, ADTS), 1–8 channels; HE-AAC (SBR) decode, see [Limits](#limits) | ffmpeg: ~135 dB SNR; PNS noise differs per sample at equal band energy. HE-AAC from AudioToolbox, 1–6 channels: same 962-sample delay as ffmpeg, ~54 dB SNR, high band level within 0.01 dB |
| Opus (`opus`) | RFC 6716, 8251, 7845 | decoder: SILK, hybrid, CELT, all frame sizes, PLC and FEC, multistream (`Decoder`) and single stream (`StreamDecoder`), 8–48 kHz output | all 36 RFC 8251 conformance cases |
| AC-3/E-AC-3 (`ac3`) | decoder: ATSC A/52:2012; encoder/programme API: ETSI TS 102 366 V1.4.1 | single-syncframe and complete-programme decoding; packet encoding through discrete 7.1 (see below) | decoder comparisons and encoder output through ffmpeg, CRC/channel/timing/bit-budget regressions; synthetic quality limitations below |
| MP1/MP2 (`mpa`) | ISO/IEC 11172-3, 13818-3 | Layer I and II, MPEG-1/2/2.5, 8–48 kHz; also the Layer II rate/mode pairs the spec disallows (ffmpeg's default mono 384 kbit/s); no free format | ffmpeg-encoded streams, 73–84 dB SNR |
| MP3 decoder (`mp3`) | ISO/IEC 11172-3, 13818-3 | Layer III, MPEG-1/2/2.5, 8–48 kHz, every bit rate, CBR and VBR; mono, stereo, dual channel, joint stereo (mid/side and intensity); long, short and mixed blocks; bit reservoir; CRC read, not checked; Xing / Info / VBRI and LAME tags; no free format (read through symphonia) | ffmpeg's float decoder: 127–131 dB SNR on LAME streams of every sampling frequency (CBR, VBR, CRC, no reservoir, transients with short blocks) and on this crate's encoder's; intensity stereo and mixed blocks through LAME frames edited to use them (112–131 dB) |
| MP3 encoder (`mp3`) | ISO/IEC 11172-3, 13818-3 | Layer III, constant bit rate: 32–320 kbit/s at 32/44.1/48 kHz, 8–160 kbit/s at 16/22.05/24 kHz; mono, stereo, joint stereo (mid/side); bit reservoir; long blocks only; no Xing/Info tag, VBR, CRC or free format | ffmpeg decodes every Huffman code as intended; full encodes at every sampling frequency checked with ffprobe and by SNR of ffmpeg's decode |
| ALAC (`alac`) | Apple's reference implementation | decode and encode, 1–8 channels, 16/20/24/32 bits (decode: any depth 1–32), fast mode, magic cookie in MP4/Matroska and CAF form | Apple's reference: same packets from the encoder, same samples from both decoders on 766 configurations; ffmpeg: bit-exact both ways |
@@ -576,6 +580,7 @@ the full tests with ffmpeg and the vectors required.
|---|---|
| WAV, AIFF, `decode`/`probe`, peaks | SoundCraft `soundcraft-audio-io` [7dc56a4](https://github.com/storytold/soundcraft/commit/7dc56a4dbeebf57eacece09536726c57844fc59d) |
| FLAC encoder, AAC, Opus decoder, AC-3, MP1/MP2, Ogg | FilmCraft [8fda2f2](https://github.com/storytold/filmcraft/commit/8fda2f232198c4c79ff9cfe5b6a347bb1375fa9e) |
| MP3 decoder | written here, from ISO/IEC 11172-3 and 13818-3; shares the encoder's tables and the MP1/MP2 synthesis filter |
| MP3 encoder | FilmCraft `filmcraft-mp3enc` [4bec22b](https://github.com/storytold/filmcraft/commit/4bec22bd03bd1d995c9cf72e02a284f96d3d72cd) |
| ALAC | Apple's reference implementation [macosforge/alac@c38887c](https://github.com/macosforge/alac/tree/c38887c5c5e64a4b31108733bd79ca9b2496d987/codec), Copyright © 2011 Apple Inc., Apache-2.0; ported to Rust and modified (see the `alac` module docs and [NOTICE](../../NOTICE)) |
+157 -15
View File
@@ -6,6 +6,7 @@ use crate::aac::config::{AudioSpecificConfig, ElementType, ProgramConfig};
use crate::aac::huffman::{self, INTENSITY_HCB, INTENSITY_HCB2, NOISE_HCB, ZERO_HCB};
use crate::aac::ics::{IcsInfo, WindowSequence};
use crate::aac::mdct::{MdctScratch, WindowShape, mdct_long, mdct_short, window};
use crate::aac::sbr;
use crate::aac::tables::{pow43, pow43_table, sf_gain};
use crate::aac::tns::{self, TnsData};
use crate::aac::{Error, Result};
@@ -63,7 +64,14 @@ impl Scratch {
}
}
/// AAC-LC decoder.
/// Where the SBR data of a channel element sits in its access unit: the bit range of the fill
/// element's payload after its extension type, and whether a CRC leads it.
type SbrRef = (usize, usize, bool);
/// An access unit's core output, and the SBR data of each layout entry.
type Decoded = (Vec<Vec<f32>>, Vec<Option<SbrRef>>);
/// AAC-LC decoder, with the SBR tool of HE-AAC when [`Decoder::set_sbr`] turns it on.
#[derive(Clone)]
pub struct Decoder {
asc: AudioSpecificConfig,
@@ -75,6 +83,11 @@ pub struct Decoder {
scratch: Scratch,
/// A fill element carried SBR data (implicitly signalled HE-AAC).
sbr_seen: bool,
/// The SBR decoder of each layout entry, when output is at twice the core rate.
sbr_out: Option<Vec<sbr::Element>>,
/// The layout `sbr_out` was built for. Kept apart from `layout`, so that an access unit whose
/// new program config fails (and whose layout is put back) leaves the SBR history alone.
sbr_layout: Vec<(ElementType, u8)>,
}
impl Decoder {
@@ -110,6 +123,8 @@ impl Decoder {
noise_state: NOISE_SEED,
scratch: Scratch::new(),
sbr_seen: false,
sbr_out: None,
sbr_layout: Vec::new(),
};
d.set_layout(layout);
Ok(d)
@@ -131,16 +146,27 @@ impl Decoder {
pub fn config(&self) -> &AudioSpecificConfig {
&self.asc
}
/// Output sampling rate in Hz: the AAC-LC core rate.
/// Output sampling rate in Hz: the AAC-LC core rate, or twice it with [`Self::set_sbr`] on.
pub fn sample_rate(&self) -> u32 {
self.asc.sample_rate
if self.sbr_out.is_some() { self.asc.sample_rate.saturating_mul(2) } else { self.asc.sample_rate }
}
/// Whether the stream is HE-AAC: SBR signalled in the `AudioSpecificConfig` (explicit) or SBR
/// data seen in a fill element of a decoded access unit (implicit). Only the AAC-LC core is
/// decoded, at [`Self::sample_rate`]; the SBR high band is not reconstructed.
/// data seen in a fill element of a decoded access unit (implicit). Without [`Self::set_sbr`],
/// only the AAC-LC core is decoded.
pub fn sbr(&self) -> bool {
self.asc.sbr || self.sbr_seen
}
/// Decode HE-AAC at twice the core rate (`true`) or the AAC-LC core alone (`false`, the
/// default). With SBR on, [`Self::decode`] returns 2048 samples per channel: the core through
/// the SBR filter banks, delayed by [`SBR_DELAY`](crate::aac::SBR_DELAY) samples, with the high
/// band rebuilt from each frame's SBR data. Until the stream's first SBR header, and for a
/// frame whose SBR data is missing or damaged, the high band is empty. Parametric stereo
/// (HE-AAC v2) is not decoded: its mono core stays mono.
pub fn set_sbr(&mut self, on: bool) {
if on != self.sbr_out.is_some() {
self.sbr_out = on.then(Vec::new);
}
}
/// Output channels of the current element layout.
pub fn channels(&self) -> usize {
self.channels.len()
@@ -158,30 +184,61 @@ impl Decoder {
c.overlap.fill(0.0);
c.prev_shape = WindowShape::Sine;
}
for e in self.sbr_out.iter_mut().flatten() {
e.reset();
}
}
fn sf_index(&self) -> u8 {
self.asc.sf_index
}
/// Decode one access unit (one `raw_data_block`) into 1024 samples per channel. An access unit
/// that fails leaves the decoder as it was, but for [`Self::sbr`]: its damage, including a damaged
/// program config element, does not reach the access units after it.
/// Decode one access unit (one `raw_data_block`) into 1024 samples per channel (2048 with
/// [`Self::set_sbr`] on). An access unit that fails leaves the decoder as it was, but for
/// [`Self::sbr`]: its damage, including a damaged program config element, does not reach the
/// access units after it. Damaged SBR data alone does not fail it.
pub fn decode(&mut self, au: &[u8]) -> Result<Vec<Vec<f32>>> {
let before = (self.asc.pce.clone(), self.layout.clone(), self.offsets.clone(), self.channels.clone(), self.noise_state);
let decoded = self.decode_block(au, true);
if decoded.is_err() {
(self.asc.pce, self.layout, self.offsets, self.channels, self.noise_state) = before;
match self.decode_block(au, true) {
Ok((pcm, sbr_refs)) => Ok(self.apply_sbr(au, pcm, &sbr_refs)),
Err(e) => {
(self.asc.pce, self.layout, self.offsets, self.channels, self.noise_state) = before;
Err(e)
}
}
decoded
}
fn decode_block(&mut self, au: &[u8], allow_reconfig: bool) -> Result<Vec<Vec<f32>>> {
/// Run each layout entry's channels through its SBR decoder, when SBR is on.
fn apply_sbr(&mut self, au: &[u8], pcm: Vec<Vec<f32>>, refs: &[Option<SbrRef>]) -> Vec<Vec<f32>> {
let rate = self.sample_rate();
let Some(elements) = self.sbr_out.as_mut() else {
return pcm;
};
// a new layout (a program config element) starts the SBR decoders afresh: their history
// belongs to the old element order, even where the channel counts match
if elements.len() != self.layout.len() || self.sbr_layout != self.layout {
*elements = self.layout.iter().map(|l| sbr::Element::new(l.0.channels(), rate)).collect();
self.sbr_layout.clone_from(&self.layout);
}
let mut out = Vec::with_capacity(pcm.len());
for (i, e) in elements.iter_mut().enumerate() {
let first = self.offsets.get(i).copied().unwrap_or(0);
let core = pcm.get(first..first + e.channels()).unwrap_or_default();
let payload = refs.get(i).copied().flatten().map(|(start, end, crc)| sbr::Payload { data: au, start, end, crc });
out.extend(e.process(core, payload));
}
out
}
fn decode_block(&mut self, au: &[u8], allow_reconfig: bool) -> Result<Decoded> {
let mut br = BitReader::new(au);
let nch = self.channels.len();
let mut saw_element = false;
let mut out: Vec<Option<Vec<f32>>> = vec![None; nch];
let mut used = vec![false; self.layout.len()];
// SBR data belongs to the single channel or pair element before its fill element
let mut sbr_refs: Vec<Option<SbrRef>> = vec![None; self.layout.len()];
let mut last_slot = None;
loop {
let id = br.read_bits(3)?;
saw_element |= matches!(id, ID_SCE | ID_CPE | ID_LFE);
@@ -191,6 +248,7 @@ impl Decoder {
let ty = if id == ID_SCE { ElementType::Sce } else { ElementType::Lfe };
let slot = self.find_slot(ty, tag, &used)?;
used[slot] = true;
last_slot = (id == ID_SCE).then_some(slot);
let mut ics = self.decode_ics(&mut br, None)?;
let ch = self.offsets[slot];
self.fill_noise(&mut ics, None);
@@ -200,6 +258,7 @@ impl Decoder {
let tag = br.read_bits(4)? as u8;
let slot = self.find_slot(ElementType::Cpe, tag, &used)?;
used[slot] = true;
last_slot = Some(slot);
let ch = self.offsets[slot];
let [a, b] = self.decode_cpe(&mut br, ch)?;
out[ch] = Some(a);
@@ -237,8 +296,13 @@ impl Decoder {
}
if count > 0 {
let ext = br.read_bits(4)?;
self.sbr_seen |= matches!(ext, EXT_SBR_DATA | EXT_SBR_DATA_CRC);
let is_sbr = matches!(ext, EXT_SBR_DATA | EXT_SBR_DATA_CRC);
self.sbr_seen |= is_sbr;
let start = br.position();
br.skip(count * 8 - 4)?;
if let (true, Some(slot)) = (is_sbr, last_slot.take()) {
sbr_refs[slot] = Some((start, br.position(), ext == EXT_SBR_DATA_CRC));
}
}
}
_ => break, // ID_END
@@ -251,7 +315,7 @@ impl Decoder {
for o in out {
res.push(o.ok_or(Error::Bitstream("access unit is missing a channel element"))?);
}
Ok(res)
Ok((res, sbr_refs))
}
fn find_slot(&self, ty: ElementType, tag: u8, used: &[bool]) -> Result<usize> {
@@ -618,6 +682,84 @@ mod tests {
use super::*;
use craft_media::bitstream::BitWriter;
/// With SBR on, an access unit decodes to 2048 samples, and over a silent core the high band
/// its SBR fill element describes is there; with SBR off, the core alone (silence).
#[test]
fn sbr_fill_elements_rebuild_the_high_band() {
let au = sbr_au(0);
// AAC-LC, 22.05 kHz, mono
let asc = AudioSpecificConfig::lc(7, 1);
let mut dec = Decoder::from_config(asc.clone()).unwrap();
let core = dec.decode(&au).unwrap();
assert_eq!((core[0].len(), dec.sample_rate()), (1024, 22_050));
assert!(dec.sbr() && core[0].iter().all(|&s| s == 0.0));
let mut dec = Decoder::from_config(asc).unwrap();
dec.set_sbr(true);
assert_eq!(dec.sample_rate(), 44_100);
let mut out = Vec::new();
for _ in 0..4 {
out.extend(dec.decode(&au).unwrap().remove(0));
}
assert_eq!(out.len(), 4 * 2048);
let rms = (out[2048..].iter().map(|s| s * s).sum::<f32>() / (out.len() - 2048) as f32).sqrt();
assert!(rms > 1e-4, "{rms}");
}
/// A program config that changes the layout restarts the SBR decoders, even where the
/// channel counts match, and one in an access unit that fails leaves their history alone: the
/// access units after it decode as if it had not been there.
#[test]
fn a_new_layout_restarts_sbr_and_a_failed_one_keeps_it() {
let au = sbr_au(0);
let one = ProgramConfig { front: vec![(false, 0)], ..Default::default() };
let six = ProgramConfig { front: vec![(false, 0), (true, 0)], back: vec![(true, 1)], lfe: vec![0], ..Default::default() };
let decoder = || {
let mut d = Decoder::from_config(AudioSpecificConfig { pce: Some(one.clone()), ..AudioSpecificConfig::lc(7, 0) }).unwrap();
d.set_sbr(true);
d
};
let (mut kept, mut failed) = (decoder(), decoder());
for _ in 0..3 {
assert_eq!(kept.decode(&au).unwrap(), failed.decode(&au).unwrap());
}
// the new layout's elements are missing from this access unit
assert!(failed.decode(&silent_au(Some(&six), &[(ID_SCE, 0)])).is_err());
for _ in 0..2 {
assert_eq!(kept.decode(&au).unwrap(), failed.decode(&au).unwrap());
}
// the same channel count under another tag is a new layout: the SBR decoder starts over,
// as in a decoder that had that layout from the start
let tag1 = ProgramConfig { front: vec![(false, 1)], ..Default::default() };
let mut fresh = Decoder::from_config(AudioSpecificConfig { pce: Some(tag1.clone()), ..AudioSpecificConfig::lc(7, 0) }).unwrap();
fresh.set_sbr(true);
kept.set_layout(tag1.layout());
assert_eq!(kept.decode(&sbr_au(1)).unwrap(), fresh.decode(&sbr_au(1)).unwrap());
}
/// One access unit of SCE `tag` with an SBR fill element of [`sbr::test_payload`] (44.1 kHz
/// output).
fn sbr_au(tag: u32) -> Vec<u8> {
let payload = sbr::test_payload(44_100, |_| 40, |_| 0).unwrap();
let mut bw = BitWriter::new();
bw.write_bits(ID_SCE, 3);
bw.write_bits(tag, 4);
bw.write_bits(0, 8 + 11 + 3); // global_gain, ics_info (max_sfb 0), no pulse/TNS/gain control
bw.write_bits(ID_FIL, 3);
let count = (4 + 8 * payload.len()).div_ceil(8);
if count < 15 {
bw.write_bits(count as u32, 4);
} else {
bw.write_bits(15, 4);
bw.write_bits((count - 14) as u32, 8);
}
bw.write_bits(EXT_SBR_DATA, 4);
for &b in &payload {
bw.write_bits(u32::from(b), 8);
}
bw.write_bits(0, 4);
bw.write_bits(ID_END, 3);
bw.finish()
}
/// An access unit whose elements are all empty: `elements` are (id, tag), then ID_END.
fn silent_au(pce: Option<&ProgramConfig>, elements: &[(u32, u32)]) -> Vec<u8> {
let mut bw = BitWriter::new();
+3 -3
View File
@@ -62,12 +62,12 @@ const SUB: u32 = 1 << 31;
/// entry with `SUB` set is `SUB | offset << 5 | width` and selects a sub-table of `1 << width`
/// leaves indexed by the next `width` bits. An entry of 0 is a bit pattern that no codeword starts
/// with (the codebooks are complete, so this does not occur).
struct Lut {
pub(crate) struct Lut {
t: Vec<u32>,
}
impl Lut {
fn build(codes: &[(u32, u8)]) -> Lut {
pub(crate) fn build(codes: &[(u32, u8)]) -> Lut {
let mut t = vec![0u32; 1 << L1];
// sub-table width per first-level prefix
let mut width = vec![0u32; 1 << L1];
@@ -103,7 +103,7 @@ impl Lut {
/// The symbol of the codeword at the reader position; `Eof` if the codeword is cut off.
#[inline]
fn decode(&self, br: &mut BitReader) -> Result<u32> {
pub(crate) fn decode(&self, br: &mut BitReader) -> Result<u32> {
let bits = br.peek(32);
let mut e = self.t[(bits >> (32 - L1)) as usize];
if e & SUB != 0 {
+15 -7
View File
@@ -5,13 +5,13 @@
//! model, window switching, M/S, TNS, bit reservoir, CBR/VBR, 1–8 channels.
//! - [`Decoder`] (feature `aac-decode`): `AudioSpecificConfig` + raw access units → planar f32.
//! Supports M/S, intensity stereo, PNS, TNS, pulse data, both window shapes and every window
//! sequence.
//! sequence, and the SBR tool of HE-AAC ([`Decoder::set_sbr`]).
//! - [`latm_config`] / [`latm_split`] (feature `aac-decode`): the configuration and payload of
//! LOAS / LATM frames (AAC in MPEG transport streams), for the decoder.
//!
//! HE-AAC (SBR/PS), Main/SSR/LTP profiles, coupling channels and 960-sample frames are not
//! supported; for HE-AAC only the AAC-LC core is decoded (at the core rate; [`Decoder::sbr`] says
//! when).
//! Parametric stereo (HE-AAC v2), Main/SSR/LTP profiles, coupling channels and 960-sample frames
//! are not supported. HE-AAC decodes at twice the core rate with [`Decoder::set_sbr`] on
//! ([`Decoder::sbr`] says when a stream uses SBR), and as its AAC-LC core otherwise.
//!
//! From FilmCraft's `filmcraft-aac` (storytold/filmcraft@8fda2f2). Public items keep their names,
//! so FilmCraft can re-export this module.
@@ -53,6 +53,8 @@ mod ics;
#[cfg(feature = "aac-decode")]
mod latm;
mod mdct;
#[cfg(feature = "aac-decode")]
mod sbr;
mod tables;
mod tns;
@@ -68,6 +70,12 @@ pub use latm::{LatmConfig, latm_config, latm_split};
pub use mdct::WindowShape;
pub use tables::{SAMPLE_RATES, sample_rate_index};
/// Output samples by which [`Decoder`] with [`Decoder::set_sbr`] on delays the core: the SBR filter
/// banks and the SBR frame's lag behind the core frame. HE-AAC encoders count it in the priming the
/// container signals.
#[cfg(feature = "aac-decode")]
pub const SBR_DELAY: usize = sbr::DELAY;
/// Samples per AAC-LC frame (per channel).
pub const FRAME_LEN: usize = 1024;
@@ -197,9 +205,9 @@ const UPSAMPLE_DELAY: usize = 481;
#[cfg(feature = "aac-decode")]
const UPSAMPLE_HISTORY: usize = UPSAMPLE_DELAY + UPSAMPLE_HALF;
/// 2× upsampler for HE-AAC. The decoder reconstructs the AAC-LC core at half the output rate and
/// not yet the SBR high band, so the core is interpolated to the output rate: timing and pitch are
/// right and the band above the core's Nyquist stays empty. Even outputs are the input samples,
/// 2× upsampler: interpolates an AAC-LC core to twice its rate, leaving the band above the core's
/// Nyquist empty. [`Decoder::set_sbr`] decodes HE-AAC with its high band instead; this stays for
/// callers that want the core alone at the output rate. Even outputs are the input samples,
/// odd ones a Blackman-windowed sinc half-band interpolation over 2 × `UPSAMPLE_HALF` inputs.
/// The output is delayed by `UPSAMPLE_DELAY` input samples, as an SBR decoder's is; the state
/// carries across packets, so a seek primed with the preceding packet gives the same samples as
+493
View File
@@ -0,0 +1,493 @@
//! The SBR bitstream (ISO/IEC 14496-3 §4.4.2.8 syntax, §4.5.2.8 semantics): the header and the
//! single and channel pair elements of an `EXT_SBR_DATA` fill element.
use std::sync::OnceLock;
use craft_media::bitstream::BitReader;
use super::freq::FreqTables;
use super::tables::{
F_ENV_1_5DB, F_ENV_3_0DB, F_ENV_BAL_1_5DB, F_ENV_BAL_3_0DB, T_ENV_1_5DB, T_ENV_3_0DB, T_ENV_BAL_1_5DB, T_ENV_BAL_3_0DB, T_NOISE_3_0DB,
T_NOISE_BAL_3_0DB,
};
use super::{Header, MAX_ENV};
use crate::aac::huffman::Lut;
use crate::aac::{Error, Result};
/// `bs_frame_class`: fixed leading and trailing frame borders.
pub(crate) const FIXFIX: u8 = 0;
/// Fixed leading border, variable trailing border.
pub(crate) const FIXVAR: u8 = 1;
/// Variable leading border, fixed trailing border.
pub(crate) const VARFIX: u8 = 2;
/// Variable leading and trailing borders.
pub(crate) const VARVAR: u8 = 3;
/// SBR time slots per frame (`numTimeSlots`; two QMF slots each).
const TIME_SLOTS: usize = 16;
/// Decoding tables for the SBR Huffman codes, in [`Book`] order.
fn luts() -> &'static [Lut; 10] {
static LUTS: OnceLock<[Lut; 10]> = OnceLock::new();
LUTS.get_or_init(|| {
[
Lut::build(&T_ENV_1_5DB),
Lut::build(&F_ENV_1_5DB),
Lut::build(&T_ENV_BAL_1_5DB),
Lut::build(&F_ENV_BAL_1_5DB),
Lut::build(&T_ENV_3_0DB),
Lut::build(&F_ENV_3_0DB),
Lut::build(&T_ENV_BAL_3_0DB),
Lut::build(&F_ENV_BAL_3_0DB),
Lut::build(&T_NOISE_3_0DB),
Lut::build(&T_NOISE_BAL_3_0DB),
]
})
}
/// One of the SBR Huffman codes, and its largest absolute value.
#[derive(Clone, Copy)]
struct Book(usize, i32);
const T_ENV_15: Book = Book(0, 60);
const F_ENV_15: Book = Book(1, 60);
const T_BAL_15: Book = Book(2, 24);
const F_BAL_15: Book = Book(3, 24);
const T_ENV_30: Book = Book(4, 31);
const F_ENV_30: Book = Book(5, 31);
const T_BAL_30: Book = Book(6, 12);
const F_BAL_30: Book = Book(7, 12);
const T_NOISE: Book = Book(8, 31);
const T_NOISE_BAL: Book = Book(9, 12);
fn huff(br: &mut BitReader, book: Book) -> Result<i32> {
Ok(luts()[book.0].decode(br)? as i32 - book.1)
}
fn bits(br: &mut BitReader, n: u32) -> Result<usize> {
Ok(br.read_bits(n)? as usize)
}
impl Header {
/// `sbr_header()`, with the defaults of the fields its extra parts leave out.
pub(crate) fn read(br: &mut BitReader) -> Result<Header> {
let amp_res = br.read_flag()?;
let start_freq = br.read_bits(4)? as u8;
let stop_freq = br.read_bits(4)? as u8;
let xover_band = br.read_bits(3)? as u8;
br.skip(2)?; // bs_reserved
let (extra_1, extra_2) = (br.read_flag()?, br.read_flag()?);
let mut h = Header {
amp_res,
start_freq,
stop_freq,
xover_band,
freq_scale: 2,
alter_scale: true,
noise_bands: 2,
limiter_bands: 2,
limiter_gains: 2,
interpol_freq: true,
smoothing_mode: true,
};
if extra_1 {
h.freq_scale = br.read_bits(2)? as u8;
h.alter_scale = br.read_flag()?;
h.noise_bands = br.read_bits(2)? as u8;
}
if extra_2 {
h.limiter_bands = br.read_bits(2)? as u8;
h.limiter_gains = br.read_bits(2)? as u8;
h.interpol_freq = br.read_flag()?;
h.smoothing_mode = br.read_flag()?;
}
Ok(h)
}
}
/// The time/frequency grid of one channel in one frame (`sbr_grid()`, §4.6.18.3.3).
#[derive(Clone, Debug, PartialEq, Eq)]
pub(crate) struct Grid {
pub(crate) class: u8,
/// Envelopes (1 to 5).
pub(crate) num_env: usize,
/// Envelope borders in time slots; `t_env[num_env]` may reach past the frame (up to 19).
pub(crate) t_env: [usize; MAX_ENV + 1],
/// Noise floors (1 or 2).
pub(crate) num_noise: usize,
/// Noise floor borders.
pub(crate) t_noise: [usize; 3],
/// High frequency resolution per envelope.
pub(crate) freq_res: [bool; MAX_ENV],
/// The transient envelope `l_A`, if any (it may be `num_env`: the next frame's first).
pub(crate) la: Option<usize>,
/// 3 dB envelope steps (the header's choice, but 1.5 dB for a single FIXFIX envelope).
pub(crate) amp_res: bool,
}
/// `ceil(log2(num_env + 1))`: the width of `bs_pointer`.
fn pointer_bits(num_env: usize) -> u32 {
usize::BITS - num_env.leading_zeros()
}
fn read_rel(br: &mut BitReader, n: usize) -> Result<[usize; 3]> {
let mut rel = [0; 3];
for r in rel.iter_mut().take(n) {
*r = 2 * bits(br, 2)? + 2;
}
Ok(rel)
}
impl Grid {
fn read(br: &mut BitReader, amp_res: bool) -> Result<Grid> {
let bad = || Error::Bitstream("invalid SBR time grid");
let class = br.read_bits(2)? as u8;
let mut t = [0i64; MAX_ENV + 1];
let mut freq_res = [false; MAX_ENV];
let (n, pointer) = match class {
FIXFIX => {
let n = 1usize << br.read_bits(2)?;
if n > 4 {
return Err(bad());
}
freq_res = [br.read_flag()?; MAX_ENV];
for (l, t) in t.iter_mut().enumerate().take(n + 1) {
*t = (l * TIME_SLOTS / n) as i64;
}
(n, 0)
}
FIXVAR | VARFIX => {
let abs = bits(br, 2)?;
let rels = bits(br, 2)?;
let n = rels + 1;
let rel = read_rel(br, rels)?;
let pointer = bits(br, pointer_bits(n))?;
for l in 0..n {
freq_res[if class == FIXVAR { n - 1 - l } else { l }] = br.read_flag()?;
}
if class == FIXVAR {
t[n] = (abs + TIME_SLOTS) as i64;
for l in (1..n).rev() {
t[l] = t[l + 1] - rel[n - 1 - l] as i64;
}
} else {
(t[0], t[n]) = (abs as i64, TIME_SLOTS as i64);
for l in 1..n {
t[l] = t[l - 1] + rel[l - 1] as i64;
}
}
(n, pointer)
}
_ => {
let abs0 = bits(br, 2)?;
let abs1 = bits(br, 2)? + TIME_SLOTS;
let (rels0, rels1) = (bits(br, 2)?, bits(br, 2)?);
let n = rels0 + rels1 + 1;
if n > MAX_ENV {
return Err(bad());
}
let (rel0, rel1) = (read_rel(br, rels0)?, read_rel(br, rels1)?);
let pointer = bits(br, pointer_bits(n))?;
for r in freq_res.iter_mut().take(n) {
*r = br.read_flag()?;
}
(t[0], t[n]) = (abs0 as i64, abs1 as i64);
for l in 1..=rels0 {
t[l] = t[l - 1] + rel0[l - 1] as i64;
}
for l in (rels0 + 1..n).rev() {
t[l] = t[l + 1] - rel1[n - 1 - l] as i64;
}
(n, pointer)
}
};
if t[0] < 0 || t[..=n].windows(2).any(|w| w[0] >= w[1]) {
return Err(bad());
}
// l_A: in ISO/IEC 14496-3 a VARFIX pointer of 1, like 0, marks no transient envelope
let la = match (pointer, class) {
(0, _) | (1, VARFIX) => None,
(p, FIXVAR | VARVAR) => Some((n + 1).checked_sub(p).ok_or_else(bad)?),
(p, _) => Some(p - 1),
};
if la.is_some_and(|la| la > n) {
return Err(bad());
}
let t_env: [usize; MAX_ENV + 1] = std::array::from_fn(|i| t[i] as usize);
let (num_noise, t_noise) = if n == 1 {
(1, [t_env[0], t_env[1], 0])
} else {
let middle = match (class, pointer) {
(FIXFIX, _) => n / 2,
(VARFIX, 0) => 1,
(VARFIX, 1) => n - 1,
(VARFIX, p) => p - 1,
(_, 0 | 1) => n - 1,
(_, p) => (n + 1).checked_sub(p).ok_or_else(bad)?,
};
if middle == 0 || middle >= n {
return Err(bad());
}
(2, [t_env[0], t_env[middle], t_env[n]])
};
Ok(Grid { class, num_env: n, t_env, num_noise, t_noise, freq_res, la, amp_res: amp_res && !(class == FIXFIX && n == 1) })
}
}
/// The data of one channel as transmitted: delta-coded envelope and noise floor values (the
/// first frequency-coded value of each is absolute), not yet scaled for a balance channel.
#[derive(Clone, Debug)]
pub(crate) struct ChannelData {
pub(crate) grid: Grid,
pub(crate) df_env: [bool; MAX_ENV],
pub(crate) df_noise: [bool; 2],
pub(crate) invf: [u8; 5],
pub(crate) env: [[i32; 64]; MAX_ENV],
pub(crate) noise: [[i32; 5]; 2],
/// `bs_add_harmonic` per high-resolution band, when `bs_add_harmonic_flag` is set.
pub(crate) harmonic: Option<[bool; 64]>,
}
impl ChannelData {
fn new(grid: Grid) -> ChannelData {
ChannelData {
grid,
df_env: [false; MAX_ENV],
df_noise: [false; 2],
invf: [0; 5],
env: [[0; 64]; MAX_ENV],
noise: [[0; 5]; 2],
harmonic: None,
}
}
fn read_dtdf(&mut self, br: &mut BitReader) -> Result<()> {
for d in self.df_env.iter_mut().take(self.grid.num_env) {
*d = br.read_flag()?;
}
for d in self.df_noise.iter_mut().take(self.grid.num_noise) {
*d = br.read_flag()?;
}
Ok(())
}
fn read_invf(&mut self, br: &mut BitReader, t: &FreqTables) -> Result<()> {
for m in self.invf.iter_mut().take(t.n_q()) {
*m = br.read_bits(2)? as u8;
}
Ok(())
}
/// `sbr_envelope()`; `balance` for the second channel of a coupled pair.
fn read_envelope(&mut self, br: &mut BitReader, t: &FreqTables, balance: bool) -> Result<()> {
let (t_book, f_book, start_bits) = match (self.grid.amp_res, balance) {
(false, false) => (T_ENV_15, F_ENV_15, 7),
(false, true) => (T_BAL_15, F_BAL_15, 6),
(true, false) => (T_ENV_30, F_ENV_30, 6),
(true, true) => (T_BAL_30, F_BAL_30, 5),
};
for l in 0..self.grid.num_env {
let n = t.bands(self.grid.freq_res[l]).len() - 1;
let row = &mut self.env[l];
if self.df_env[l] {
for v in row.iter_mut().take(n) {
*v = huff(br, t_book)?;
}
} else {
row[0] = br.read_bits(start_bits)? as i32;
for v in row.iter_mut().take(n).skip(1) {
*v = huff(br, f_book)?;
}
}
}
Ok(())
}
/// `sbr_noise()`.
fn read_noise(&mut self, br: &mut BitReader, t: &FreqTables, balance: bool) -> Result<()> {
let (t_book, f_book) = if balance { (T_NOISE_BAL, F_BAL_30) } else { (T_NOISE, F_ENV_30) };
for l in 0..self.grid.num_noise {
let row = &mut self.noise[l];
if self.df_noise[l] {
for v in row.iter_mut().take(t.n_q()) {
*v = huff(br, t_book)?;
}
} else {
row[0] = br.read_bits(5)? as i32;
for v in row.iter_mut().take(t.n_q()).skip(1) {
*v = huff(br, f_book)?;
}
}
}
Ok(())
}
/// `bs_add_harmonic_flag` and `sbr_sinusoidal_coding()`.
fn read_harmonics(&mut self, br: &mut BitReader, t: &FreqTables) -> Result<()> {
if br.read_flag()? {
let mut h = [false; 64];
for v in h.iter_mut().take(t.n_high()) {
*v = br.read_flag()?;
}
self.harmonic = Some(h);
}
Ok(())
}
}
/// Skip `bs_extended_data` (parametric stereo, for one, is not decoded).
fn skip_extended(br: &mut BitReader) -> Result<()> {
if br.read_flag()? {
let mut count = bits(br, 4)?;
if count == 15 {
count += bits(br, 8)?;
}
br.skip(8 * count)?;
}
Ok(())
}
/// The SBR data of one channel element.
#[derive(Clone, Debug)]
pub(crate) struct Frame {
/// The pair codes its second channel as a balance against the first.
pub(crate) coupling: bool,
pub(crate) channels: Vec<ChannelData>,
}
/// `sbr_single_channel_element()` (`channels` 1) or `sbr_channel_pair_element()` (2).
pub(crate) fn read_data(br: &mut BitReader, t: &FreqTables, amp_res: bool, channels: usize) -> Result<Frame> {
if br.read_flag()? {
br.skip(4 * channels)?; // bs_reserved
}
if channels == 1 {
let mut c = ChannelData::new(Grid::read(br, amp_res)?);
c.read_dtdf(br)?;
c.read_invf(br, t)?;
c.read_envelope(br, t, false)?;
c.read_noise(br, t, false)?;
c.read_harmonics(br, t)?;
skip_extended(br)?;
return Ok(Frame { coupling: false, channels: vec![c] });
}
let coupling = br.read_flag()?;
let (mut a, mut b);
if coupling {
a = ChannelData::new(Grid::read(br, amp_res)?);
b = ChannelData::new(a.grid.clone());
a.read_dtdf(br)?;
b.read_dtdf(br)?;
a.read_invf(br, t)?;
b.invf = a.invf;
a.read_envelope(br, t, false)?;
a.read_noise(br, t, false)?;
b.read_envelope(br, t, true)?;
b.read_noise(br, t, true)?;
} else {
a = ChannelData::new(Grid::read(br, amp_res)?);
b = ChannelData::new(Grid::read(br, amp_res)?);
a.read_dtdf(br)?;
b.read_dtdf(br)?;
a.read_invf(br, t)?;
b.read_invf(br, t)?;
a.read_envelope(br, t, false)?;
b.read_envelope(br, t, false)?;
a.read_noise(br, t, false)?;
b.read_noise(br, t, false)?;
}
a.read_harmonics(br, t)?;
b.read_harmonics(br, t)?;
skip_extended(br)?;
Ok(Frame { coupling, channels: vec![a, b] })
}
#[cfg(test)]
mod tests {
use craft_media::bitstream::BitWriter;
use super::*;
/// Every SBR Huffman table is a complete prefix code, with the shortest codeword for a zero
/// delta, and its decoder reads back every codeword.
#[test]
fn huffman_tables_are_complete_prefix_codes() {
let tables: [&[(u32, u8)]; 10] = [
&T_ENV_1_5DB,
&F_ENV_1_5DB,
&T_ENV_BAL_1_5DB,
&F_ENV_BAL_1_5DB,
&T_ENV_3_0DB,
&F_ENV_3_0DB,
&T_ENV_BAL_3_0DB,
&F_ENV_BAL_3_0DB,
&T_NOISE_3_0DB,
&T_NOISE_BAL_3_0DB,
];
let lavs = [60, 60, 24, 24, 31, 31, 12, 12, 31, 12];
for (i, (codes, lav)) in tables.iter().zip(lavs).enumerate() {
assert_eq!(codes.len(), 2 * lav + 1, "table {i}");
let max = u32::from(codes.iter().map(|c| c.1).max().unwrap());
assert_eq!(codes.iter().map(|&(_, l)| 1u64 << (max - u32::from(l))).sum::<u64>(), 1 << max, "table {i}: Kraft sum");
let shortest = codes.iter().map(|c| c.1).min().unwrap();
assert_eq!(codes[lav].1, shortest, "table {i}");
for (sym, &(code, len)) in codes.iter().enumerate() {
let mut bw = BitWriter::new();
bw.write_bits(code, u32::from(len));
bw.write_bits(0x5A5A5A, 24);
let data = bw.finish();
let mut br = BitReader::new(&data);
assert_eq!(huff(&mut br, Book(i, lav as i32)).unwrap(), sym as i32 - lav as i32, "table {i}");
assert_eq!(br.position(), usize::from(len));
}
}
}
fn grid(bits: &[(u32, u32)]) -> Result<Grid> {
let mut bw = BitWriter::new();
for &(v, n) in bits {
bw.write_bits(v, n);
}
bw.write_bits(0, 16);
let data = bw.finish();
Grid::read(&mut BitReader::new(&data), true)
}
/// The four frame classes give the borders, noise floors and transient envelope of
/// §4.6.18.3.3; a FIXFIX frame of one envelope uses 1.5 dB steps.
#[test]
fn grids_of_each_frame_class() {
// FIXFIX, 4 envelopes, high resolution
let g = grid(&[(FIXFIX as u32, 2), (2, 2), (1, 1)]).unwrap();
assert_eq!((g.num_env, &g.t_env[..5], g.num_noise, g.t_noise, g.la, g.amp_res), (4, &[0, 4, 8, 12, 16][..], 2, [0, 8, 16], None, true));
let g = grid(&[(FIXFIX as u32, 2), (0, 2), (0, 1)]).unwrap();
assert_eq!((g.num_env, g.t_noise, g.amp_res), (1, [0, 16, 0], false));
// FIXVAR: trailing border 16 + 2, two relative borders (4, 2) back from it, pointer 1,
// resolutions sent last envelope first
let g = grid(&[(FIXVAR as u32, 2), (2, 2), (2, 2), (1, 2), (0, 2), (1, 2), (0, 1), (1, 1), (1, 1)]).unwrap();
assert_eq!((g.num_env, &g.t_env[..4]), (3, &[0, 12, 14, 18][..]));
assert_eq!((g.la, g.t_noise, g.freq_res[..3].to_vec()), (Some(3), [0, 14, 18], vec![true, true, false]));
// VARFIX: leading border 1, relative 2, pointer 2: l_A = 1
let g = grid(&[(VARFIX as u32, 2), (1, 2), (1, 2), (0, 2), (2, 2), (1, 1), (0, 1)]).unwrap();
assert_eq!((g.num_env, &g.t_env[..3], g.la, g.t_noise), (2, &[1, 3, 16][..], Some(1), [1, 3, 16]));
// the same with pointer 1: no transient envelope, the noise floors still split at 3
let g = grid(&[(VARFIX as u32, 2), (1, 2), (1, 2), (0, 2), (1, 2), (1, 1), (0, 1)]).unwrap();
assert_eq!((g.la, g.t_noise), (None, [1, 3, 16]));
// VARVAR: 1 .. 17 with one border from each end
let g = grid(&[(VARVAR as u32, 2), (1, 2), (1, 2), (1, 2), (1, 2), (0, 2), (0, 2), (0, 2), (0, 1), (0, 1), (0, 1)]).unwrap();
assert_eq!((g.num_env, &g.t_env[..4], g.la), (3, &[1, 3, 15, 17][..], None));
}
/// Grids whose borders do not increase, too many envelopes and a pointer past the envelopes
/// are refused.
#[test]
fn invalid_grids_are_refused() {
// FIXFIX with 8 envelopes
assert!(grid(&[(FIXFIX as u32, 2), (3, 2), (0, 1)]).is_err());
// VARVAR with 7 envelopes
assert!(grid(&[(VARVAR as u32, 2), (0, 2), (0, 2), (3, 2), (3, 2)]).is_err());
// FIXVAR whose relative borders run back past the start: 16 - (8 + 8 + 8)
assert!(grid(&[(FIXVAR as u32, 2), (0, 2), (3, 2), (3, 2), (3, 2), (3, 2), (0, 3), (0, 4)]).is_err());
// VARFIX, 2 envelopes, pointer 3: the middle border would be the trailing one
assert!(grid(&[(VARFIX as u32, 2), (0, 2), (1, 2), (0, 2), (3, 2), (0, 1), (0, 1)]).is_err());
}
}
+372
View File
@@ -0,0 +1,372 @@
//! Frequency band tables (ISO/IEC 14496-3 §4.6.18.3.2) and the patches and limiter bands built on
//! them (§4.6.18.6.3, §4.6.18.7.3). Every table holds QMF channel borders.
use super::Header;
/// The most patches the HF generator may build.
const MAX_PATCHES: usize = 5;
/// The tables of one SBR header at one output rate.
#[derive(Clone, Debug, PartialEq, Eq)]
pub(crate) struct FreqTables {
/// First QMF channel of the master table (the start of the SBR range before the crossover).
pub(crate) k0: usize,
/// First QMF channel of the SBR range.
pub(crate) kx: usize,
/// Channels in the SBR range (`kx + m` is its end).
pub(crate) m: usize,
/// High-resolution envelope bands (`n_high + 1` borders).
pub(crate) high: Vec<usize>,
/// Low-resolution envelope bands.
pub(crate) low: Vec<usize>,
/// Noise floor bands (1 to 5).
pub(crate) noise: Vec<usize>,
/// Limiter bands.
pub(crate) lim: Vec<usize>,
/// `(first source channel, channels)` of each patch, in order from `kx` up.
pub(crate) patches: Vec<(usize, usize)>,
}
/// Round half up, as the specification's `NINT`.
fn nint(x: f64) -> i64 {
(x + 0.5).floor() as i64
}
/// The start channel offsets of `bs_start_freq`, by output rate (§4.6.18.3.2.1).
fn start_offsets(fs: u32) -> &'static [i8; 16] {
match fs {
0..=16_000 => &[-8, -7, -6, -5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5, 6, 7],
16_001..=22_050 => &[-5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5, 6, 7, 9, 11, 13],
22_051..=24_000 => &[-5, -3, -2, -1, 0, 1, 2, 3, 4, 5, 6, 7, 9, 11, 13, 16],
24_001..=32_000 => &[-6, -4, -2, -1, 0, 1, 2, 3, 4, 5, 6, 7, 9, 11, 13, 16],
32_001..=64_000 => &[-4, -2, -1, 0, 1, 2, 3, 4, 5, 6, 7, 9, 11, 13, 16, 20],
_ => &[-2, -1, 0, 1, 2, 3, 4, 5, 6, 7, 9, 11, 13, 16, 20, 24],
}
}
/// `NINT(f · 128 / fs)` for the 3/4/5 kHz (start) or 6/8/10 kHz (stop) minimum at `fs`.
fn min_channel(fs: u32, low: f64, mid: f64, high: f64) -> i64 {
let f = if fs < 32_000 {
low
} else if fs < 64_000 {
mid
} else {
high
};
nint(f * 128.0 / f64::from(fs))
}
/// The start and stop channels `k0`, `k2` of the master table.
fn start_stop(h: &Header, fs: u32) -> Option<(usize, usize)> {
let k0 = min_channel(fs, 3000.0, 4000.0, 5000.0) + i64::from(start_offsets(fs)[usize::from(h.start_freq & 15)]);
let k2 = match h.stop_freq {
14 => 2 * k0,
15 => 3 * k0,
s => {
let stop_min = min_channel(fs, 6000.0, 8000.0, 10_000.0);
if stop_min <= 0 {
return None;
}
let ratio = 64.0 / stop_min as f64;
let at = |p: i64| nint(stop_min as f64 * ratio.powf(p as f64 / 13.0));
let mut dk: Vec<i64> = (0..13).map(|p| at(p + 1) - at(p)).collect();
dk.sort_unstable();
stop_min + dk.iter().take(usize::from(s)).sum::<i64>()
}
}
.min(64);
// the low band reaches only the analysis bank's 32 channels (`kx` is checked against them
// once the crossover is known)
(1..=32).contains(&k0).then_some(())?;
(k2 > k0).then_some((k0 as usize, k2 as usize))
}
/// The master table for `bs_freq_scale` 0: bands of one or two channels.
fn master_linear(k0: usize, k2: usize, alter_scale: bool) -> Option<Vec<usize>> {
let (dk, bands) = if alter_scale { (2, 2 * nint((k2 - k0) as f64 / 4.0) as usize) } else { (1, 2 * ((k2 - k0) / 2)) };
if bands == 0 {
return None;
}
let mut v = vec![dk as i64; bands];
let mut diff = k2 as i64 - (k0 + bands * dk) as i64;
// take the difference from the lowest bands (too wide) or give it to the highest (too narrow)
let mut k = if diff < 0 { 0 } else { bands - 1 };
while diff != 0 {
let step = if diff < 0 { 1 } else { -1 };
*v.get_mut(k)? -= step;
diff += step;
k = if step == 1 { k + 1 } else { k.checked_sub(1)? };
}
cumulative(k0, &v)
}
/// The borders `start, start + d[0], …`; `None` unless every band is at least a channel wide.
fn cumulative(start: usize, d: &[i64]) -> Option<Vec<usize>> {
let mut out = Vec::with_capacity(d.len() + 1);
out.push(start);
let mut at = start as i64;
for &d in d {
if d <= 0 {
return None;
}
at += d;
out.push(at as usize);
}
Some(out)
}
/// The band widths of `2 · NINT(bands · log2(hi / lo) / (2 · warp))` logarithmic bands.
fn log_widths(lo: usize, hi: usize, bands: f64, warp: f64) -> Vec<i64> {
let ratio = hi as f64 / lo as f64;
let n = 2 * nint(bands * ratio.log2() / (2.0 * warp));
let at = |k: i64| nint(lo as f64 * ratio.powf(k as f64 / n as f64));
let mut d: Vec<i64> = (0..n.max(0)).map(|k| at(k + 1) - at(k)).collect();
d.sort_unstable();
d
}
/// The master table for `bs_freq_scale` 1–3: 12, 10 or 8 bands per octave, warped above
/// `2 · k0` by `bs_alter_scale`.
fn master_log(k0: usize, k2: usize, freq_scale: u8, alter_scale: bool) -> Option<Vec<usize>> {
let bands = [12.0, 10.0, 8.0][usize::from(freq_scale.clamp(1, 3) - 1)];
let two_regions = k2 as f64 / k0 as f64 > 2.2449;
let k1 = if two_regions { 2 * k0 } else { k2 };
let d0 = log_widths(k0, k1, bands, 1.0);
let mut table = cumulative(k0, &d0)?;
if table.len() < 2 {
return None;
}
if two_regions {
let mut d1 = log_widths(k1, k2, bands, if alter_scale { 1.3 } else { 1.0 });
let max0 = d0.iter().copied().max()?;
if d1.first().is_some_and(|&d| d < max0) {
// widen the first upper band to the widest lower one, at the cost of the last
let change = max0 - d1[0];
d1[0] = max0;
*d1.last_mut()? -= change;
d1.sort_unstable();
}
table.extend(cumulative(k1, &d1)?.into_iter().skip(1));
}
Some(table)
}
impl FreqTables {
/// The tables of `h` at output rate `fs`, or `None` if the header asks for an invalid layout.
pub(crate) fn new(h: &Header, fs: u32) -> Option<FreqTables> {
let (k0, k2) = start_stop(h, fs)?;
let master = if h.freq_scale == 0 { master_linear(k0, k2, h.alter_scale)? } else { master_log(k0, k2, h.freq_scale, h.alter_scale)? };
let n_master = master.len().checked_sub(1)?;
let xover = usize::from(h.xover_band);
if xover >= n_master {
return None;
}
let high: Vec<usize> = master.get(xover..)?.to_vec();
let n_high = high.len() - 1;
let (kx, end) = (high[0], *high.last()?);
if kx > 32 || end > 64 || end <= kx {
return None;
}
let m = end - kx;
// every other border, keeping the first (and the second when the count is odd)
let n_low = n_high - n_high / 2;
let low: Vec<usize> = (0..=n_low).map(|k| high[if k == 0 { 0 } else { 2 * k - (n_high & 1) }]).collect();
let n_q = if h.noise_bands == 0 { 1 } else { (nint(f64::from(h.noise_bands) * (end as f64 / kx as f64).log2()) as usize).max(1) };
if n_q > 5 || n_q > n_low {
return None;
}
let mut noise = vec![low[0]];
let mut i = 0;
for k in 1..=n_q {
i += (n_low - i) / (n_q + 1 - k);
noise.push(*low.get(i)?);
}
let patches = patches(&master, k0, kx, m, fs)?;
let lim = limiter(&low, &patches, kx, h.limiter_bands);
Some(FreqTables { k0, kx, m, high, low, noise, lim, patches })
}
/// High-resolution envelope bands.
pub(crate) fn n_high(&self) -> usize {
self.high.len() - 1
}
/// Noise floor bands.
pub(crate) fn n_q(&self) -> usize {
self.noise.len() - 1
}
/// The envelope band table of a resolution (`true`: high).
pub(crate) fn bands(&self, high_res: bool) -> &[usize] {
if high_res { &self.high } else { &self.low }
}
}
/// Map the low band onto the SBR range (§4.6.18.6.3): runs of source channels, each ending below
/// `k0`, that together cover `kx .. kx + m`.
fn patches(master: &[usize], k0: usize, kx: usize, m: usize, fs: u32) -> Option<Vec<(usize, usize)>> {
let n_master = master.len() - 1;
let goal = nint(2.048e6 / f64::from(fs)).max(0) as usize;
let mut k = if goal < kx + m { master.iter().position(|&f| f >= goal).unwrap_or(n_master) } else { n_master };
let (mut msb, mut usb) = (k0, kx);
let mut out: Vec<(usize, usize)> = Vec::new();
// each pass either adds a patch or lowers `msb` to `kx`; a stream that does neither twice
// running cannot finish. One patch over the limit may still be a short last one that is
// dropped below.
for _ in 0..2 * (MAX_PATCHES + 2) {
// the highest master border the patch can reach from below k0
let mut j = k + 1;
let (sb, odd) = loop {
j = j.checked_sub(1)?;
let sb = *master.get(j)?;
let odd = (sb + k0) % 2;
if sb + odd < k0 + msb {
break (sb, odd);
}
};
let count = sb.saturating_sub(usb);
if count > 0 {
let start = (k0 - odd).checked_sub(count)?;
out.push((start, count));
if out.len() > MAX_PATCHES + 1 {
return None;
}
(usb, msb) = (sb, sb);
} else {
msb = kx;
}
if master.get(k)?.saturating_sub(sb) < 3 {
k = n_master;
}
if sb == kx + m {
if out.len() > 1 && out.last().is_some_and(|p| p.1 < 3) {
out.pop();
}
return (!out.is_empty() && out.len() <= MAX_PATCHES).then_some(out);
}
}
None
}
/// The limiter band table (§4.6.18.7.3): one band over the range, or about 1.2, 2 or 3 bands per
/// octave on the low-resolution and patch borders.
fn limiter(low: &[usize], patches: &[(usize, usize)], kx: usize, limiter_bands: u8) -> Vec<usize> {
let (Some(&first), Some(&last)) = (low.first(), low.last()) else {
return Vec::new();
};
if limiter_bands == 0 {
return vec![first, last];
}
let per_octave = [1.2, 2.0, 3.0][usize::from(limiter_bands.clamp(1, 3) - 1)];
let mut borders = vec![kx];
for p in patches {
borders.push(borders.last().copied().unwrap_or(kx) + p.1);
}
let mut t: Vec<usize> = low.to_vec();
t.extend(borders.iter().skip(1).take(patches.len().saturating_sub(1)));
t.sort_unstable();
let is_border = |v: usize| borders.contains(&v);
let mut k = 1;
while k < t.len() {
let octaves = if t[k - 1] == 0 { f64::INFINITY } else { (t[k] as f64 / t[k - 1] as f64).log2() };
if octaves * per_octave >= 0.49 {
k += 1;
} else if t[k] == t[k - 1] || !is_border(t[k]) {
t.remove(k);
} else if !is_border(t[k - 1]) {
t.remove(k - 1);
} else {
k += 1;
}
}
if t.len() < 2 {
return vec![first, last];
}
t
}
#[cfg(test)]
mod tests {
use super::*;
fn header(start: u8, stop: u8, xover: u8, freq_scale: u8, alter: bool, noise: u8) -> Header {
Header {
amp_res: true,
start_freq: start,
stop_freq: stop,
xover_band: xover,
freq_scale,
alter_scale: alter,
noise_bands: noise,
limiter_bands: 2,
limiter_gains: 2,
interpol_freq: true,
smoothing_mode: true,
}
}
/// Every header field combination at every output rate gives tables that are strictly
/// increasing, start at `kx`, end at `kx + m`, keep the low band within the analysis bank and
/// patch from below `k0` (or is refused).
#[test]
fn every_header_gives_consistent_tables_or_none() {
let mut valid = 0;
for fs in [16_000, 22_050, 24_000, 32_000, 44_100, 48_000, 64_000, 88_200, 96_000] {
for start in 0..16 {
for stop in 0..16 {
for xover in 0..8 {
for fsc in 0..4 {
for alter in [false, true] {
for noise in 0..4 {
let Some(t) = FreqTables::new(&header(start, stop, xover, fsc, alter, noise), fs) else { continue };
valid += 1;
for v in [&t.high, &t.low, &t.noise, &t.lim] {
assert!(v.windows(2).all(|w| w[0] < w[1]), "{v:?}");
assert_eq!(v[0], t.kx);
}
for v in [&t.high, &t.low, &t.noise] {
assert_eq!(*v.last().unwrap(), t.kx + t.m);
}
assert!(t.kx <= 32 && t.kx + t.m <= 64 && t.n_q() <= 5);
// a last patch of under 3 channels is dropped, and the limiter
// bands may then stop short of the range's end
assert!(t.patches.iter().map(|p| p.1).sum::<usize>() <= t.m);
assert!(t.lim.len() >= 2 && *t.lim.last().unwrap() <= t.kx + t.m);
assert!(t.patches.iter().all(|&(s, n)| s + n <= t.k0));
}
}
}
}
}
}
}
assert!(valid > 10_000, "{valid}");
}
/// The highest start a header can give, 32 at 24 kHz (start 15), is valid: with stop 14
/// (twice the start) and linear bands it covers channels 32 to 64.
#[test]
fn a_start_at_channel_32_is_accepted() {
let t = FreqTables::new(&header(15, 14, 0, 0, false, 2), 24_000).unwrap();
assert_eq!((t.k0, t.kx, t.m), (32, 32, 32));
}
/// At 96 kHz this header builds patches of 6, 6, 6, 6, 5 and 2 channels: the short sixth is
/// dropped, as any short last patch is, and the five left are within the limit.
#[test]
fn a_short_sixth_patch_is_dropped_before_the_limit() {
let t = FreqTables::new(&header(3, 9, 0, 0, false, 2), 96_000).unwrap();
assert_eq!((t.k0, t.kx + t.m), (8, 39));
assert_eq!(t.patches.iter().map(|p| p.1).collect::<Vec<_>>(), [6, 6, 6, 6, 5]);
}
/// A typical 44.1 kHz header: start channel 12 + offset, stop near 64, three noise bands.
#[test]
fn a_44k_header_has_the_expected_layout() {
let t = FreqTables::new(&header(5, 9, 0, 2, true, 2), 44_100).unwrap();
// startMin 12 + offset 2 = 14
assert_eq!((t.k0, t.kx), (14, 14));
assert_eq!(t.low.len() - 1, t.n_high() - t.n_high() / 2);
assert!(t.n_q() >= 1);
}
}
+333
View File
@@ -0,0 +1,333 @@
//! HF generation (ISO/IEC 14496-3 §4.6.18.6) and HF adjustment (§4.6.18.7) of one channel.
use super::bitstream::Grid;
use super::freq::FreqTables;
use super::tables::NOISE;
use super::{Cx, Header, MAX_ENV, T_HF_ADJ, X_SLOTS};
/// Low band subband samples of a frame: slots -8 .. 32 relative to the frame (`X_Low`).
pub(crate) type LowBand = [[Cx; 32]; X_SLOTS];
/// High band subband samples, at slot `l + T_HF_ADJ` for QMF slot `l` of the frame's envelopes.
pub(crate) type HighBand = [[Cx; 64]; X_SLOTS];
/// The per-channel state the HF tools carry from frame to frame.
#[derive(Clone, Debug)]
pub(crate) struct History {
/// `bs_invf_mode` and chirp factor per noise band.
invf: [u8; 5],
bw: [f32; 5],
/// The last frame's transient envelope was its last (`l_A = L_E`): no noise in this frame's
/// first.
la_at_end: bool,
/// Sinusoids present in the last envelope, by channel above `kx`.
sine: [bool; 64],
/// Gains and noise levels of the last four slots, newest first (smoothing).
gains: [[f32; 64]; 4],
noise_levels: [[f32; 64]; 4],
/// The smoothing history holds data of the current tables.
primed: bool,
noise_index: usize,
sine_index: usize,
}
impl History {
pub(crate) fn new() -> History {
History {
invf: [0; 5],
bw: [0.0; 5],
la_at_end: false,
sine: [false; 64],
gains: [[0.0; 64]; 4],
noise_levels: [[0.0; 64]; 4],
primed: false,
noise_index: 0,
sine_index: 0,
}
}
/// Forget what depends on the frequency tables (after a header that changes them).
pub(crate) fn reset_tables(&mut self) {
self.sine = [false; 64];
self.primed = false;
self.noise_index = 0;
}
}
/// The chirp factor of a noise band from its inverse filtering mode and the last frame's.
fn chirp(mode: u8, prev_mode: u8, prev_bw: f32) -> f32 {
let new_bw = match (mode, prev_mode) {
(0, 1) => 0.6,
(0, _) => 0.0,
(1, 0) => 0.6,
(1, _) => 0.75,
(2, _) => 0.9,
_ => 0.98,
};
let bw = if new_bw < prev_bw { 0.75 * new_bw + 0.25 * prev_bw } else { 0.90625 * new_bw + 0.09375 * prev_bw };
if bw < 0.015625 { 0.0 } else { bw }
}
/// Second order linear prediction of one low band channel over the frame and the 6 slots
/// before it (the covariance method, §4.6.18.6.2): `(α0, α1)`.
fn predictor(x: &LowBand, k: usize) -> (Cx, Cx) {
// φ(i, j) = Σ x(n − i + 2) · conj(x(n − j + 2)), n = 0 .. 37
let phi = |i: usize, j: usize| {
let (mut re, mut im) = (0f64, 0f64);
for n in 0..SLOTS_PLUS_6 {
let (a, b) = (x[n + 2 - i][k], x[n + 2 - j][k]);
re += f64::from(a.re) * f64::from(b.re) + f64::from(a.im) * f64::from(b.im);
im += f64::from(a.im) * f64::from(b.re) - f64::from(a.re) * f64::from(b.im);
}
(re, im)
};
let (p01, p02, p11, p12, p22) = (phi(0, 1), phi(0, 2), phi(1, 1).0, phi(1, 2), phi(2, 2).0);
let d = p22 * p11 - (p12.0 * p12.0 + p12.1 * p12.1) / (1.0 + 1e-6);
let a1 = if d != 0.0 {
// (φ01 · φ12 − φ02 · φ11) / d
((p01.0 * p12.0 - p01.1 * p12.1 - p02.0 * p11) / d, (p01.0 * p12.1 + p01.1 * p12.0 - p02.1 * p11) / d)
} else {
(0.0, 0.0)
};
let a0 = if p11 != 0.0 {
// −(φ01 + α1 · conj(φ12)) / φ11
(-(p01.0 + a1.0 * p12.0 + a1.1 * p12.1) / p11, -(p01.1 + a1.1 * p12.0 - a1.0 * p12.1) / p11)
} else {
(0.0, 0.0)
};
let mag = |a: (f64, f64)| (a.0 * a.0 + a.1 * a.1).sqrt();
if mag(a0) >= 4.0 || mag(a1) >= 4.0 {
return (Cx::default(), Cx::default());
}
(Cx { re: a0.0 as f32, im: a0.1 as f32 }, Cx { re: a1.0 as f32, im: a1.1 as f32 })
}
/// Slots of the covariance sums: the frame's 32 and 6 before it.
const SLOTS_PLUS_6: usize = super::SLOTS + 6;
/// The index of the band of `bands` holding channel `k` (bands are increasing borders).
fn band_of(bands: &[usize], k: usize) -> usize {
bands.partition_point(|&b| b <= k).saturating_sub(1).min(bands.len().saturating_sub(2))
}
/// Patch the low band into the SBR range, inverse filtered (§4.6.18.6.3), for QMF slots
/// `from .. to` of the frame.
pub(crate) fn generate(x: &LowBand, t: &FreqTables, invf: &[u8; 5], h: &mut History, (from, to): (usize, usize), out: &mut HighBand) {
let mut bw = [0f32; 5];
for i in 0..t.n_q() {
bw[i] = chirp(invf[i], h.invf[i], h.bw[i]);
}
(h.invf, h.bw) = (*invf, bw);
let mut pred: [Option<(Cx, Cx)>; 32] = [None; 32];
let mut k = t.kx;
for &(start, count) in &t.patches {
for p in start..start + count {
let (a0, a1) = *pred[p].get_or_insert_with(|| predictor(x, p));
let g = bw[band_of(&t.noise, k)];
let (c0, c1) = (a0.scale(g), a1.scale(g * g));
for l in from..to {
let i = l + T_HF_ADJ;
out[i][k] = x[i][p] + c0 * x[i - 1][p] + c1 * x[i - 2][p];
}
k += 1;
}
}
}
/// Dequantised envelope and noise floor values of one channel in one frame.
#[derive(Clone, Debug)]
pub(crate) struct Levels {
/// Envelope energy per envelope and band (of that envelope's resolution).
pub(crate) energy: [[f32; 64]; MAX_ENV],
/// Noise to signal ratio per noise floor and noise band.
pub(crate) noise: [[f32; 5]; 2],
}
/// Gains for one envelope, per channel of the SBR range.
struct EnvelopeGains {
gain: [f32; 64],
noise: [f32; 64],
sine: [f32; 64],
}
const LIMITER_GAINS: [f32; 4] = [0.70795, 1.0, 1.41254, 1e10];
/// `h_smooth`, as the specification gives it.
#[allow(clippy::excessive_precision)]
const SMOOTHING: [f32; 5] = [0.33333333333333, 0.30150283239582, 0.21816949906249, 0.11516383427084, 0.03183050093751];
const EPS: f32 = 1.0;
const EPS0: f32 = 1e-12;
/// What the adjustment of one channel's frame works from.
pub(crate) struct Frame<'a> {
/// The generated high band.
pub(crate) x: &'a HighBand,
pub(crate) t: &'a FreqTables,
pub(crate) hdr: &'a Header,
pub(crate) g: &'a Grid,
pub(crate) lv: &'a Levels,
/// `bs_add_harmonic`, when the frame codes sinusoids.
pub(crate) harmonic: Option<&'a [bool; 64]>,
}
/// The gains of envelope `l` (§4.6.18.7.3–4): `delta` is 0 for a transient envelope, which gets
/// no noise.
fn envelope_gains(f: &Frame, l: usize, sine_index: &[bool; 64], delta: bool) -> EnvelopeGains {
let Frame { x, t, hdr, g, lv, .. } = *f;
let (kx, m) = (t.kx, t.m);
let bands = t.bands(g.freq_res[l]);
let (from, to) = (2 * g.t_env[l] + T_HF_ADJ, 2 * g.t_env[l + 1] + T_HF_ADJ);
let slots = (to - from) as f32;
let floor = usize::from(g.num_noise == 2 && g.t_env[l] >= g.t_noise[1]);
// per channel: original energy, current energy, noise ratio, sinusoid in its band
let mut e_orig = [0f32; 64];
let mut e_curr = [0f32; 64];
let mut q = [0f32; 64];
let mut s_band = [false; 64];
for j in 0..bands.len() - 1 {
let (lo, hi) = (bands[j] - kx, bands[j + 1] - kx);
let any_sine = sine_index[lo..hi].iter().any(|&s| s);
let mut sum = 0f32;
for c in lo..hi {
let ch = c + kx;
let e: f32 = (from..to).map(|i| x[i][ch].norm_sqr()).sum::<f32>() / slots;
e_curr[c] = e;
sum += e;
e_orig[c] = lv.energy[l][j];
q[c] = lv.noise[floor][band_of(&t.noise, ch)];
s_band[c] = any_sine;
}
if !hdr.interpol_freq {
e_curr[lo..hi].fill(sum / (hi - lo) as f32);
}
}
let mut out = EnvelopeGains { gain: [0.0; 64], noise: [0.0; 64], sine: [0.0; 64] };
for c in 0..m {
// `q / (1 + q)` first: energy and noise ratio are each clamped, their product is not
let (eo, ec, q) = (e_orig[c], e_curr[c], q[c]);
let share = q / (1.0 + q);
out.noise[c] = (eo * share).sqrt();
if sine_index[c] {
out.sine[c] = (eo / (1.0 + q)).sqrt();
}
out.gain[c] = if s_band[c] { (eo / (EPS + ec) * share).sqrt() } else { (eo / ((EPS + ec) * (1.0 + if delta { q } else { 0.0 }))).sqrt() };
}
// limit per limiter band, then boost back the energy the limiter took
let lim_gain = LIMITER_GAINS[usize::from(hdr.limiter_gains & 3)];
for w in t.lim.windows(2) {
let (lo, hi) = (w[0] - kx, w[1] - kx);
let (so, sc) = (e_orig[lo..hi].iter().sum::<f32>(), e_curr[lo..hi].iter().sum::<f32>());
let max = (lim_gain * ((EPS0 + so) / (EPS0 + sc)).sqrt()).min(1e5);
let mut den = 0f32;
for c in lo..hi {
if out.gain[c] > max {
out.noise[c] *= max / out.gain[c];
out.gain[c] = max;
}
den += e_curr[c] * out.gain[c] * out.gain[c];
if out.sine[c] != 0.0 {
den += out.sine[c] * out.sine[c];
} else if delta {
den += out.noise[c] * out.noise[c];
}
}
let boost = ((EPS0 + so) / (EPS0 + den)).sqrt().min(1.584_893_2);
for c in lo..hi {
out.gain[c] *= boost;
out.noise[c] *= boost;
out.sine[c] *= boost;
}
}
out
}
/// Adjust the generated high band to the transmitted envelopes and add noise and sinusoids
/// (§4.6.18.7), for the frame's envelopes, into `y`.
pub(crate) fn adjust(f: &Frame, h: &mut History, y: &mut HighBand) {
let Frame { x, t, hdr, g, harmonic, .. } = *f;
let (kx, m) = (t.kx, t.m);
let smooth = !hdr.smoothing_mode;
let prev_la_at_end = h.la_at_end;
for l in 0..g.num_env {
// sinusoids start at the transient envelope, unless one was already playing in the band
let mut sine_index = [false; 64];
if let Some(harm) = harmonic {
for i in 0..t.n_high() {
let c = (t.high[i] + t.high[i + 1]) / 2 - kx;
sine_index[c] = harm[i] && (g.la.is_none_or(|la| l >= la) || h.sine[c]);
}
}
let transient = g.la == Some(l) || (l == 0 && prev_la_at_end);
let e = envelope_gains(f, l, &sine_index, !transient);
if !h.primed {
h.gains = [e.gain; 4];
h.noise_levels = [e.noise; 4];
h.primed = true;
}
for i in 2 * g.t_env[l]..2 * g.t_env[l + 1] {
let (mut gain, mut noise) = (e.gain, e.noise);
if smooth && !transient {
for c in 0..m {
gain[c] = SMOOTHING[0] * e.gain[c] + (0..4).map(|j| SMOOTHING[j + 1] * h.gains[j][c]).sum::<f32>();
noise[c] = SMOOTHING[0] * e.noise[c] + (0..4).map(|j| SMOOTHING[j + 1] * h.noise_levels[j][c]).sum::<f32>();
}
}
h.gains.rotate_right(1);
h.noise_levels.rotate_right(1);
(h.gains[0], h.noise_levels[0]) = (e.gain, e.noise);
let (sin_re, sin_im) = [(1.0, 0.0), (0.0, 1.0), (-1.0, 0.0), (0.0, -1.0)][h.sine_index];
let row = &mut y[i + T_HF_ADJ];
for c in 0..m {
let ch = c + kx;
let mut v = x[i + T_HF_ADJ][ch].scale(gain[c]);
h.noise_index = (h.noise_index + 1) & 511;
if e.sine[c] != 0.0 {
let sign = if ch % 2 == 0 { 1.0 } else { -1.0 };
v.re += e.sine[c] * sin_re;
v.im += e.sine[c] * sin_im * sign;
} else if !transient {
let [nr, ni] = NOISE[h.noise_index];
v.re += noise[c] * nr;
v.im += noise[c] * ni;
}
row[ch] = v;
}
h.sine_index = (h.sine_index + 1) & 3;
}
if l + 1 == g.num_env {
h.sine = sine_index;
}
}
h.la_at_end = g.la == Some(g.num_env);
}
#[cfg(test)]
mod tests {
use super::*;
/// The chirp factor follows §4.6.18.6.2: rising quickly, falling slowly, and zero below 1/64.
#[test]
fn chirp_factors() {
assert!((chirp(3, 3, 0.0) - 0.90625 * 0.98).abs() < 1e-6);
assert!((chirp(0, 3, 0.98) - 0.25 * 0.98).abs() < 1e-6);
assert_eq!(chirp(0, 0, 0.05), 0.0);
assert!((chirp(1, 0, 0.0) - 0.90625 * 0.6).abs() < 1e-6);
}
/// A channel that is a decaying complex exponential is predicted exactly by its first order
/// term.
#[test]
fn prediction_of_a_resonance() {
let mut x: LowBand = [[Cx::default(); 32]; X_SLOTS];
let r = Cx { re: 0.9 * 0.3f32.cos(), im: 0.9 * 0.3f32.sin() };
let mut v = Cx { re: 1.0, im: 0.0 };
for slot in x.iter_mut() {
slot[3] = v;
v = v * r;
}
let (a0, a1) = predictor(&x, 3);
// x(n) + α0·x(n−1) + α1·x(n−2) = 0 with α0 = −r, α1 = 0
assert!((a0.re + r.re).abs() < 1e-3 && (a0.im + r.im).abs() < 1e-3, "{a0:?}");
assert!(a1.re.abs() < 1e-3 && a1.im.abs() < 1e-3, "{a1:?}");
// a silent channel has no predictor
assert_eq!(predictor(&x, 4), (Cx::default(), Cx::default()));
}
}
+544
View File
@@ -0,0 +1,544 @@
//! Spectral band replication (HE-AAC, ISO/IEC 14496-3 §4.6.18): rebuilds the band above the
//! AAC-LC core from the core's own low band and the envelope data of the stream's SBR fill
//! elements, at twice the core rate.
//!
//! Each channel's core output goes through a 32-band QMF analysis bank. The HF generator copies
//! (patches) low band channels into the SBR range, inverse filtered; the HF adjuster scales them
//! to the transmitted envelopes and adds noise and sinusoids; a 64-band QMF synthesis bank merges
//! the delayed low band and the new high band. A frame without usable SBR data (none sent yet, or
//! damaged) still passes through the banks, so the output keeps its rate and delay.
//!
//! Written from the SBR description and tables of ETSI ES 201 980 (DRM, Annex I has the tables it
//! shares with ISO/IEC 14496-3) and the decoder process of ISO/IEC 14496-3. Parametric stereo
//! (HE-AAC v2) is not decoded: its extension is skipped and the mono core is extended alone.
mod bitstream;
mod freq;
mod hf;
mod qmf;
mod tables;
use std::ops::{Add, Mul};
use craft_media::bitstream::BitReader;
use self::bitstream::{ChannelData, Frame};
use self::freq::FreqTables;
use self::hf::{HighBand, History, Levels, LowBand};
use self::qmf::{Analysis, Synthesis};
/// QMF slots per frame: 1024 core samples in slots of 32.
pub(crate) const SLOTS: usize = 32;
/// The most envelopes in a frame.
pub(crate) const MAX_ENV: usize = 5;
/// Slots of the last frame kept ahead of this one's low band (`t_HFGen`).
const T_HF_GEN: usize = 8;
/// The SBR frame lags the core frame by `T_HF_GEN − T_HF_ADJ` slots.
pub(crate) const T_HF_ADJ: usize = 2;
/// Slots in the low and high band buffers: the frame and `T_HF_GEN` before it.
pub(crate) const X_SLOTS: usize = SLOTS + T_HF_GEN;
/// The 16-bit full scale the specification's energies are in.
const PCM_SCALE: f32 = 32768.0;
/// `NOISE_FLOOR_OFFSET`.
const NOISE_OFFSET: i32 = 6;
/// Output samples by which the SBR decoder delays the core: the filter banks, and the SBR frame
/// lagging the core frame by `T_HF_GEN − T_HF_ADJ` slots of 64.
pub const DELAY: usize = qmf::DELAY + 64 * (T_HF_GEN - T_HF_ADJ);
/// A complex subband sample.
#[derive(Clone, Copy, Default, Debug, PartialEq)]
pub(crate) struct Cx {
pub(crate) re: f32,
pub(crate) im: f32,
}
impl Cx {
fn scale(self, g: f32) -> Cx {
Cx { re: self.re * g, im: self.im * g }
}
fn norm_sqr(self) -> f32 {
self.re * self.re + self.im * self.im
}
}
impl Add for Cx {
type Output = Cx;
fn add(self, o: Cx) -> Cx {
Cx { re: self.re + o.re, im: self.im + o.im }
}
}
impl Mul for Cx {
type Output = Cx;
fn mul(self, o: Cx) -> Cx {
Cx { re: self.re * o.re - self.im * o.im, im: self.re * o.im + self.im * o.re }
}
}
/// `sbr_header()` (§4.5.2.8.1).
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) struct Header {
pub(crate) amp_res: bool,
pub(crate) start_freq: u8,
pub(crate) stop_freq: u8,
pub(crate) xover_band: u8,
pub(crate) freq_scale: u8,
pub(crate) alter_scale: bool,
pub(crate) noise_bands: u8,
pub(crate) limiter_bands: u8,
pub(crate) limiter_gains: u8,
pub(crate) interpol_freq: bool,
pub(crate) smoothing_mode: bool,
}
impl Header {
/// Whether `o` keeps the frequency band tables (a change of any of these fields is an SBR
/// reset).
fn same_tables(&self, o: &Header) -> bool {
(self.start_freq, self.stop_freq, self.freq_scale, self.alter_scale, self.xover_band, self.noise_bands)
== (o.start_freq, o.stop_freq, o.freq_scale, o.alter_scale, o.xover_band, o.noise_bands)
}
}
/// Where an element's SBR data is: the access unit, and the bit range of the fill element's
/// payload after its extension type.
#[derive(Clone, Copy, Debug)]
pub(crate) struct Payload<'a> {
pub(crate) data: &'a [u8],
pub(crate) start: usize,
pub(crate) end: usize,
/// `EXT_SBR_DATA_CRC`: a 10-bit CRC leads the data.
pub(crate) crc: bool,
}
/// Quantised envelope values per envelope and band, and noise floor values per floor and band.
type Quantised = ([[i32; 64]; MAX_ENV], [[i32; 5]; 2]);
/// One channel's state across frames.
#[derive(Clone)]
struct Channel {
analysis: Analysis,
synthesis: Synthesis,
/// Low band of the frame, with the last `T_HF_GEN` slots of the frame before ahead of it.
x_low: Box<LowBand>,
/// Adjusted high band of the last frame (its envelopes may reach into this one).
y_prev: Box<HighBand>,
/// Where `y_prev` holds data: QMF channels, and the end of its slots.
y_prev_range: (usize, usize),
y_prev_end: usize,
/// Quantised envelope values of the last envelope, and its resolution; noise floor values of
/// the last noise floor (time-direction delta coding).
env: [i32; 64],
env_high_res: bool,
noise: [i32; 5],
history: History,
}
impl Channel {
fn new() -> Channel {
Channel {
analysis: Analysis::new(),
synthesis: Synthesis::new(),
x_low: Box::new([[Cx::default(); 32]; X_SLOTS]),
y_prev: Box::new([[Cx::default(); 64]; X_SLOTS]),
y_prev_range: (0, 0),
y_prev_end: 0,
env: [0; 64],
env_high_res: false,
noise: [0; 5],
history: History::new(),
}
}
/// Decode the delta-coded envelope and noise floor values (§4.6.18.3.4); `scale` is 2 for a
/// balance channel.
fn absolute(&mut self, d: &ChannelData, t: &FreqTables, scale: i32) -> Quantised {
let mut env = [[0i32; 64]; MAX_ENV];
for l in 0..d.grid.num_env {
let res = d.grid.freq_res[l];
let n = t.bands(res).len() - 1;
if d.df_env[l] {
for k in 0..n {
// the value this band refers to in the last envelope, mapped across resolutions
let reference = if res == self.env_high_res {
k
} else if res {
hf_band_of(t.bands(false), t.high[k])
} else {
t.high.iter().position(|&b| b == t.low[k]).unwrap_or(0)
};
env[l][k] = self.env.get(reference).copied().unwrap_or(0) + scale * d.env[l][k];
}
} else {
env[l][0] = scale * d.env[l][0];
for k in 1..n {
env[l][k] = env[l][k - 1] + scale * d.env[l][k];
}
}
(self.env, self.env_high_res) = (env[l], res);
}
let mut noise = [[0i32; 5]; 2];
for l in 0..d.grid.num_noise {
for k in 0..t.n_q() {
let delta = scale * d.noise[l][k];
noise[l][k] = if d.df_noise[l] {
self.noise[k] + delta
} else if k == 0 {
delta
} else {
noise[l][k - 1] + delta
};
}
self.noise = noise[l];
}
(env, noise)
}
}
/// The index of the band of `bands` holding channel `k`.
fn hf_band_of(bands: &[usize], k: usize) -> usize {
bands.partition_point(|&b| b <= k).saturating_sub(1)
}
/// `2^x`, kept to a range whose energies stay finite.
fn exp2(x: f32) -> f32 {
x.clamp(-64.0, 64.0).exp2()
}
/// Dequantise one channel (§4.6.18.3.5), or a coupled pair from its level and balance channels.
fn dequantise(frame: &Frame, values: &[Quantised], t: &FreqTables) -> Vec<Levels> {
let g = &frame.channels[0].grid;
let amp = if g.amp_res { 1.0 } else { 0.5 };
let mut out = vec![Levels { energy: [[0.0; 64]; MAX_ENV], noise: [[0.0; 5]; 2] }; values.len()];
if frame.coupling && values.len() == 2 {
let pan = if g.amp_res { 12.0 } else { 24.0 };
let ((e0, q0), (e1, q1)) = (&values[0], &values[1]);
for l in 0..g.num_env {
for k in 0..t.bands(g.freq_res[l]).len() - 1 {
let level = 64.0 * exp2(amp * e0[l][k] as f32 + 1.0);
let balance = amp * (pan - e1[l][k] as f32);
out[0].energy[l][k] = level / (1.0 + exp2(balance));
out[1].energy[l][k] = level / (1.0 + exp2(-balance));
}
}
for l in 0..g.num_noise {
for k in 0..t.n_q() {
let level = exp2((NOISE_OFFSET - q0[l][k] + 1) as f32);
let balance = (12 - q1[l][k]) as f32;
out[0].noise[l][k] = level / (1.0 + exp2(balance));
out[1].noise[l][k] = level / (1.0 + exp2(-balance));
}
}
return out;
}
for ((lv, (e, q)), d) in out.iter_mut().zip(values).zip(&frame.channels) {
let g = &d.grid;
let amp = if g.amp_res { 1.0 } else { 0.5 };
for l in 0..g.num_env {
for k in 0..t.bands(g.freq_res[l]).len() - 1 {
lv.energy[l][k] = 64.0 * exp2(amp * e[l][k] as f32);
}
}
for l in 0..g.num_noise {
for k in 0..t.n_q() {
lv.noise[l][k] = exp2((NOISE_OFFSET - q[l][k]) as f32);
}
}
}
out
}
/// The SBR decoder of one channel element: a single channel (SCE, or an LFE, which has no SBR
/// data) or a channel pair (CPE).
#[derive(Clone)]
pub(crate) struct Element {
/// Output sampling rate.
rate: u32,
header: Option<Header>,
tables: Option<FreqTables>,
channels: Vec<Channel>,
}
impl Element {
pub(crate) fn new(channels: usize, rate: u32) -> Element {
Element { rate, header: None, tables: None, channels: (0..channels).map(|_| Channel::new()).collect() }
}
pub(crate) fn channels(&self) -> usize {
self.channels.len()
}
/// Forget the signal (a seek). The header is kept: it holds until the stream sends another.
pub(crate) fn reset(&mut self) {
for c in &mut self.channels {
*c = Channel::new();
}
}
/// Read an element's SBR data: `None` without a header to read it by.
fn read(&mut self, p: Payload) -> Option<Frame> {
let mut br = BitReader::new(p.data);
br.seek_bits(p.start);
if p.crc {
br.skip(10).ok()?;
}
if br.read_flag().ok()? {
let h = Header::read(&mut br).ok()?;
// a header that runs past its fill element is damaged: keep the one in use
(br.position() <= p.end).then_some(())?;
if self.header != Some(h) {
if self.header.is_none_or(|o| !o.same_tables(&h)) {
for c in &mut self.channels {
c.history.reset_tables();
}
}
self.tables = FreqTables::new(&h, self.rate);
self.header = Some(h);
}
}
let (h, t) = (self.header?, self.tables.as_ref()?);
let frame = bitstream::read_data(&mut br, t, h.amp_res, self.channels.len()).ok()?;
(br.position() <= p.end).then_some(frame)
}
/// Decode one frame: 1024 core samples per channel in, 2048 out.
pub(crate) fn process(&mut self, core: &[Vec<f32>], payload: Option<Payload>) -> Vec<Vec<f32>> {
for (c, pcm) in self.channels.iter_mut().zip(core) {
c.x_low.copy_within(SLOTS..X_SLOTS, 0);
let scaled: Vec<f32> = pcm.iter().map(|s| s * PCM_SCALE).collect();
c.analysis.process(&scaled, &mut c.x_low[T_HF_GEN..]);
}
let frame = payload.and_then(|p| self.read(p));
let mut y: Vec<Box<HighBand>> = self.channels.iter().map(|_| Box::new([[Cx::default(); 64]; X_SLOTS])).collect();
// per channel: kx, m, and the first and end slot of `y` this frame fills
let mut current: Vec<Option<(usize, usize, usize, usize)>> = vec![None; self.channels.len()];
if let (Some(frame), Some(h), Some(t)) = (&frame, self.header, self.tables.as_ref()) {
let values: Vec<_> = self
.channels
.iter_mut()
.zip(&frame.channels)
.enumerate()
.map(|(i, (c, d))| c.absolute(d, t, if frame.coupling && i == 1 { 2 } else { 1 }))
.collect();
let levels = dequantise(frame, &values, t);
for (((c, d), (lv, y)), cur) in self.channels.iter_mut().zip(&frame.channels).zip(levels.iter().zip(&mut y)).zip(&mut current) {
let g = &d.grid;
let slots = (2 * g.t_env[0], 2 * g.t_env[g.num_env]);
let mut x_high: Box<HighBand> = Box::new([[Cx::default(); 64]; X_SLOTS]);
hf::generate(&c.x_low, t, &d.invf, &mut c.history, slots, &mut x_high);
let f = hf::Frame { x: &x_high, t, hdr: &h, g, lv, harmonic: d.harmonic.as_ref() };
hf::adjust(&f, &mut c.history, y);
*cur = Some((t.kx, t.m, slots.0 + T_HF_ADJ, slots.1 + T_HF_ADJ));
}
}
let mut out = vec![vec![0f32; 2 * 1024]; self.channels.len()];
for (((c, y), out), current) in self.channels.iter_mut().zip(y).zip(&mut out).zip(current) {
for (l, block) in out.as_chunks_mut::<64>().0.iter_mut().enumerate() {
let i = l + T_HF_ADJ;
let mut x = [Cx::default(); 64];
// the high band of this slot: this frame's envelopes, the last frame's reaching
// into this one, or none
let high = match current {
Some((kx, m, from, to)) if (from..to).contains(&i) => Some((&y[i], kx, m)),
_ if i + SLOTS < c.y_prev_end => Some((&c.y_prev[i + SLOTS], c.y_prev_range.0, c.y_prev_range.1)),
_ => None,
};
let low = high.map_or(current.map_or(32, |cur| cur.0), |h| h.1);
x[..low].copy_from_slice(&c.x_low[i][..low]);
if let Some((row, kx, m)) = high {
x[kx..kx + m].copy_from_slice(&row[kx..kx + m]);
}
c.synthesis.process(&x, 64, block);
}
for s in out.iter_mut() {
*s /= PCM_SCALE;
}
c.y_prev = y;
(c.y_prev_range, c.y_prev_end) = current.map_or(((0, 0), 0), |cur| ((cur.0, cur.1), cur.3));
}
out
}
}
/// The header of [`test_payload`].
#[cfg(test)]
pub(crate) const TEST_HEADER: Header = Header {
amp_res: true,
start_freq: 5,
stop_freq: 9,
xover_band: 0,
freq_scale: 2,
alter_scale: true,
noise_bands: 2,
limiter_bands: 2,
limiter_gains: 2,
interpol_freq: true,
smoothing_mode: true,
};
/// An SBR single channel element for tests at output rate `rate`: [`TEST_HEADER`] (3 dB steps,
/// start 5, stop 9, the default extra fields), then one FIXFIX envelope at high resolution with
/// band `k` at `env(k)` (1.5 dB steps, as a single FIXFIX envelope has) and noise band `k` at
/// `noise(k)`.
#[cfg(test)]
pub(crate) fn test_payload(rate: u32, env: impl Fn(usize) -> i32, noise: impl Fn(usize) -> i32) -> Option<Vec<u8>> {
use craft_media::bitstream::BitWriter;
let t = FreqTables::new(&TEST_HEADER, rate)?;
let (env, noise): (Vec<i32>, Vec<i32>) = ((0..t.n_high()).map(env).collect(), (0..t.n_q()).map(noise).collect());
let mut bw = BitWriter::new();
bw.write_bits(1, 1); // bs_header_flag
for (v, n) in [(1, 1), (5, 4), (9, 4), (0, 3), (0, 2), (0, 1), (0, 1)] {
bw.write_bits(v, n); // amp_res, start, stop, xover, reserved, no extra fields
}
bw.write_bits(0, 1); // bs_data_extra
bw.write_bits(u32::from(bitstream::FIXFIX), 2);
bw.write_bits(0, 2); // one envelope
bw.write_bits(1, 1); // high resolution
bw.write_bits(0, 2); // frequency-direction envelope and noise floor
for _ in &noise {
bw.write_bits(0, 2); // no inverse filtering
}
bw.write_bits(env[0] as u32, 7);
for w in env.windows(2) {
let (code, len) = tables::F_ENV_1_5DB[(w[1] - w[0] + 60) as usize];
bw.write_bits(code, u32::from(len));
}
bw.write_bits(noise[0] as u32, 5);
for w in noise.windows(2) {
let (code, len) = tables::F_ENV_3_0DB[(w[1] - w[0] + 31) as usize];
bw.write_bits(code, u32::from(len));
}
bw.write_bits(0, 2); // no sinusoids, no extended data
Some(bw.finish())
}
#[cfg(test)]
mod tests {
use std::f64::consts::PI;
use super::*;
const RATE: u32 = 44_100;
fn tables() -> FreqTables {
FreqTables::new(&TEST_HEADER, RATE).unwrap()
}
/// Mean energy per DFT bin of `x` between `lo` and `hi` QMF channels (64 per half rate).
fn energy(x: &[f32], lo: usize, hi: usize) -> f64 {
let n = x.len();
let (b0, b1) = (lo * n / 128, hi * n / 128);
let mut e = 0f64;
for b in b0 + 2..b1 - 2 {
let (mut re, mut im) = (0f64, 0f64);
for (i, &s) in x.iter().enumerate() {
let w = 0.5 - 0.5 * (2.0 * PI * i as f64 / n as f64).cos();
let ph = 2.0 * PI * (b * i) as f64 / n as f64;
re += f64::from(s) * w * ph.cos();
im += f64::from(s) * w * ph.sin();
}
e += re * re + im * im;
}
e / (b1 - b0 - 4) as f64
}
fn run(e: &mut Element, data: &[u8], frames: usize) -> Vec<f32> {
let core = vec![vec![0f32; 1024]];
let mut out = Vec::new();
for _ in 0..frames {
let p = Payload { data, start: 0, end: 8 * data.len(), crc: false };
let block = e.process(&core, Some(p));
assert_eq!((block.len(), block[0].len()), (1, 2048));
assert!(block[0].iter().all(|s| s.is_finite()));
out.extend_from_slice(&block[0]);
}
out
}
/// Over a silent core the high band is the noise the envelope asks for: the upper bands,
/// 12 steps of 1.5 dB above the lower ones, come out 18 dB louder, and nothing below `kx`.
#[test]
fn the_high_band_follows_the_envelope() {
let t = tables();
let mid = t.n_high() / 2;
let data = test_payload(RATE, |k| if k < mid { 30 } else { 42 }, |_| 0).unwrap();
let mut e = Element::new(1, RATE);
let out = run(&mut e, &data, 6);
let tail = &out[out.len() - 4096..];
let (lower, upper) = (energy(tail, t.high[0], t.high[mid]), energy(tail, t.high[mid], t.high[t.n_high()]));
let step = 10.0 * (upper / lower).log10();
assert!((step - 18.06).abs() < 1.5, "{step:.2} dB");
let below = energy(tail, 1, t.kx - 1);
assert!(10.0 * (lower / below.max(1e-30)).log10() > 60.0);
// the same envelope without its header is not read: an element that has seen none
// passes the core through alone
let mut fresh = Element::new(1, RATE);
let mut no_header = data.clone();
no_header[0] &= 0x7F;
assert!(run(&mut fresh, &no_header, 3).iter().all(|&s| s == 0.0));
}
/// Damaged SBR data (flipped bits, cut short, or noise) never panics and keeps the output
/// finite and of full length.
#[test]
fn damaged_sbr_data_is_survived() {
let good = test_payload(RATE, |k| 20 + k as i32, |_| 3).unwrap();
let mut seed = 0x1234_5678u32;
let mut next = || {
seed ^= seed << 13;
seed ^= seed >> 17;
seed ^= seed << 5;
seed
};
let mut e = Element::new(1, RATE);
let mut pair = Element::new(2, RATE);
for i in 0..600 {
let mut data = good.clone();
for _ in 0..1 + next() % 6 {
let bit = next() as usize % (8 * data.len());
data[bit / 8] ^= 0x80 >> (bit % 8);
}
if i % 3 == 0 {
data.truncate(1 + next() as usize % data.len());
}
if i % 5 == 0 {
data = (0..1 + next() % 40).map(|_| next() as u8).collect();
data[0] |= 0x80;
}
run(&mut e, &data, 1);
let p = Payload { data: &data, start: 0, end: 8 * data.len(), crc: i % 2 == 0 };
let out = pair.process(&[vec![0.1; 1024], vec![-0.1; 1024]], Some(p));
assert!(out.iter().all(|c| c.len() == 2048 && c.iter().all(|s| s.is_finite())));
}
}
/// The largest envelope (127 steps of 1.5 dB) with the largest noise floor (each band 31
/// steps below the last) keeps the output finite: the gains are formed so that no
/// intermediate product of two clamped levels overflows.
#[test]
fn extreme_levels_stay_finite() {
let rate =
[22_050, 24_000, 32_000, 44_100, 48_000].into_iter().find(|&r| FreqTables::new(&TEST_HEADER, r).is_some_and(|t| t.n_q() >= 3)).unwrap();
let data = test_payload(rate, |_| 127, |k| -31 * k as i32).unwrap();
let mut e = Element::new(1, rate);
run(&mut e, &data, 3);
}
/// A header that runs past the end of its fill element is not taken: the one in use stays,
/// and the frame is dropped.
#[test]
fn a_header_cut_short_is_not_taken() {
let data = test_payload(RATE, |_| 30, |_| 0).unwrap();
let mut e = Element::new(1, RATE);
run(&mut e, &data, 1);
assert_eq!(e.header, Some(TEST_HEADER));
// another start frequency (bits 2..6), in an element that ends 6 bits in
let mut cut = data.clone();
cut[0] ^= 0x04;
assert!(e.read(Payload { data: &cut, start: 0, end: 6, crc: false }).is_none());
assert_eq!(e.header, Some(TEST_HEADER));
assert!(e.read(Payload { data: &cut, start: 0, end: 8 * cut.len(), crc: false }).is_some());
assert_ne!(e.header, Some(TEST_HEADER));
}
}
+155
View File
@@ -0,0 +1,155 @@
//! The SBR filter banks (ISO/IEC 14496-3 §4.6.18.4): a 32-band complex QMF analysis bank at the
//! core rate and a 64-band complex QMF synthesis bank at the output rate, sharing the window `c`.
//!
//! Each bank is a polyphase window followed by a complex modulation: analysis
//! `2·exp(iπ(k + ½)(2n − ½)/64)`, synthesis `exp(iπ(k + ½)(2n − 251)/128)/64`. With the window's
//! indexing, the two phase offsets put the banks' combined response on its centre tap, so the low
//! band comes back unchanged (to about -60 dB, the window's own limit), 576 output samples late.
//! The synthesis bank holds back its last two output samples, which makes it 578: with the SBR
//! frame's lag, the 962 samples by which HE-AAC decoders (ffmpeg's among them) delay the core, and
//! which the priming encoders signal counts on.
use std::f64::consts::PI;
use std::sync::OnceLock;
use super::Cx;
use super::tables::QMF_WINDOW;
/// Output samples by which analysis followed by synthesis delays the low band.
pub(crate) const DELAY: usize = 578;
/// Modulation matrices, computed once.
struct Kernels {
/// Analysis, at `[k][n]`: 32 × 64.
analysis: Vec<[Cx; 64]>,
/// Synthesis, at `[n][k]`: 128 × 64.
synthesis: Vec<[Cx; 64]>,
}
fn kernels() -> &'static Kernels {
static K: OnceLock<Kernels> = OnceLock::new();
K.get_or_init(|| {
let cx = |phase: f64, scale: f64| Cx { re: (phase.cos() * scale) as f32, im: (phase.sin() * scale) as f32 };
let analysis = (0..32).map(|k| std::array::from_fn(|n| cx(PI * (k as f64 + 0.5) * (2.0 * n as f64 - 0.5) / 64.0, 2.0))).collect();
let synthesis = (0..128).map(|n| std::array::from_fn(|k| cx(PI * (k as f64 + 0.5) * (2.0 * n as f64 - 251.0) / 128.0, 1.0 / 64.0))).collect();
Kernels { analysis, synthesis }
})
}
/// The 32-band analysis bank of one channel.
#[derive(Clone)]
pub(crate) struct Analysis {
/// The last 320 input samples, newest first.
x: Box<[f32; 320]>,
}
impl Analysis {
pub(crate) fn new() -> Analysis {
Analysis { x: Box::new([0.0; 320]) }
}
/// Split `32 · out.len()` input samples into `out.len()` slots of 32 subbands.
pub(crate) fn process(&mut self, input: &[f32], out: &mut [[Cx; 32]]) {
let k = kernels();
for (block, slot) in input.as_chunks::<32>().0.iter().zip(out.iter_mut()) {
self.x.copy_within(0..288, 32);
for (n, &s) in block.iter().enumerate() {
self.x[31 - n] = s;
}
let mut u = [0f32; 64];
for (n, u) in u.iter_mut().enumerate() {
*u = (0..5).map(|j| self.x[n + 64 * j] * QMF_WINDOW[2 * (n + 64 * j)]).sum();
}
for (sb, row) in slot.iter_mut().zip(&k.analysis) {
let (mut re, mut im) = (0f32, 0f32);
for (u, m) in u.iter().zip(row) {
re += u * m.re;
im += u * m.im;
}
*sb = Cx { re, im };
}
}
}
}
/// The 64-band synthesis bank of one channel.
#[derive(Clone)]
pub(crate) struct Synthesis {
v: Box<[f32; 1280]>,
/// The last two output samples, which the next slot puts out first.
held: [f32; 2],
}
impl Synthesis {
pub(crate) fn new() -> Synthesis {
Synthesis { v: Box::new([0.0; 1280]), held: [0.0; 2] }
}
/// Merge one slot of 64 subbands into 64 output samples (`out[..64]`, of which it needs 64).
/// Bands from `bands` up are taken as zero.
pub(crate) fn process(&mut self, x: &[Cx; 64], bands: usize, out: &mut [f32]) {
let k = kernels();
let bands = bands.min(64);
self.v.copy_within(0..1152, 128);
for (n, row) in k.synthesis.iter().enumerate() {
self.v[n] = x[..bands].iter().zip(row).map(|(x, m)| x.re * m.re - x.im * m.im).sum();
}
let mut slot = [0f32; 66];
slot[..2].copy_from_slice(&self.held);
for (n, o) in slot[2..].iter_mut().enumerate() {
let mut s = 0f32;
for i in 0..5 {
s += self.v[256 * i + n] * QMF_WINDOW[128 * i + n];
s += self.v[256 * i + 192 + n] * QMF_WINDOW[128 * i + 64 + n];
}
*o = s;
}
self.held = [slot[64], slot[65]];
for (o, s) in out.iter_mut().zip(&slot[..64]) {
*o = *s;
}
}
}
#[cfg(test)]
mod tests {
use super::super::SLOTS;
use super::*;
fn tones(t: f64) -> f64 {
[0.0371, 0.0913, 0.1527, 0.2211, 0.2903, 0.3519, 0.4127].iter().enumerate().map(|(j, f)| (2.0 * PI * f * t + j as f64).sin() * 0.1).sum()
}
/// Tones across the core band through analysis and synthesis (low 32 bands only) come out at
/// twice the rate, [`DELAY`] samples late, with the error 60 dB down.
#[test]
fn analysis_then_synthesis_reconstructs_the_input() {
let input: Vec<f32> = (0..8 * 1024).map(|i| tones(i as f64) as f32).collect();
let (mut a, mut s) = (Analysis::new(), Synthesis::new());
let mut out = Vec::new();
let mut slots = [[Cx::default(); 32]; SLOTS];
for frame in input.as_chunks::<1024>().0 {
a.process(frame, &mut slots);
for slot in &slots {
let mut x = [Cx::default(); 64];
x[..32].copy_from_slice(slot);
let mut o = [0f32; 64];
s.process(&x, 32, &mut o);
out.extend_from_slice(&o);
}
}
assert_eq!(out.len(), 2 * input.len());
let snr_at = |delay: usize| {
let (mut err, mut sig) = (0f64, 0f64);
for (i, &o) in out.iter().enumerate().skip(3000) {
let want = tones((i as f64 - delay as f64) / 2.0);
err += (o as f64 - want).powi(2);
sig += want * want;
}
10.0 * (sig / err).log10()
};
let snr = snr_at(DELAY);
assert!(snr > 60.0, "reconstruction SNR {snr:.1} dB");
assert!(snr_at(DELAY - 1) < 40.0 && snr_at(DELAY + 1) < 40.0);
}
}
+357
View File
@@ -0,0 +1,357 @@
//! SBR tables (ETSI ES 201 980 V1.2.2 Annex I, the SBR tables it shares with ISO/IEC 14496-3 §4.A.6).
//!
//! Transcribed from the specification's tables, which give the window to 14 digits (more than an
//! `f32` holds). Annex I misprints the labels of `c[297]` and `c[305]`; the values are in order.
//! Each Huffman table is a complete prefix code (see the tests in `sbr::bitstream`).
#![allow(clippy::excessive_precision)]
/// The QMF bank window `c` (640 coefficients).
#[rustfmt::skip]
pub(crate) static QMF_WINDOW: [f32; 640] = [
-0.00055252865047, -0.00056176925738, -0.00049475180896, -0.00048752279712, -0.00048937912498, -0.00050407143497, -0.00052265642972, -0.00054665656337,
-0.00056778025613, -0.00058709304852, -0.00061327473938, -0.00063124935319, -0.00065403333621, -0.00067776907764, -0.00069416146273, -0.00071577364744,
-0.00072550431222, -0.00074409418541, -0.00074905980532, -0.00076813719270, -0.00077248485949, -0.00078343322877, -0.00077798694927, -0.00078036647100,
-0.00078014496257, -0.00077579773310, -0.00076307935757, -0.00075300014201, -0.00073193571525, -0.00072153919876, -0.00069179375372, -0.00066504150893,
-0.00063415949025, -0.00059461189330, -0.00055645763906, -0.00051455722108, -0.00046063254803, -0.00040951214522, -0.00035011758756, -0.00028969811748,
-0.00020983373440, -0.00014463809349, -0.00006173344072, 0.00001349497418, 0.00010943831274, 0.00020430170688, 0.00029495311041, 0.00040265402160,
0.00051073884952, 0.00062393761391, 0.00074580258865, 0.00086084433262, 0.00098859883015, 0.00112501551307, 0.00125778846475, 0.00139024948272,
0.00154432198471, 0.00168680832531, 0.00183482654224, 0.00198411407369, 0.00214615835557, 0.00230172547746, 0.00246256169126, 0.00262017586902,
0.00278704643465, 0.00294694477165, 0.00311254206525, 0.00327396134847, 0.00344188741828, 0.00360082681231, 0.00376039229104, 0.00392074323703,
0.00408197531935, 0.00422642692270, 0.00437307196781, 0.00452098527825, 0.00466064606118, 0.00479325608498, 0.00491376035745, 0.00503930226013,
0.00514073539032, 0.00524611661324, 0.00534716811982, 0.00541967759307, 0.00548760401507, 0.00554757145088, 0.00559380230045, 0.00562206432097,
0.00564551969164, 0.00563891995151, 0.00562661141932, 0.00559171286630, 0.00554043639400, 0.00547537830770, 0.00538389758970, 0.00527157587272,
0.00513822754514, 0.00498396877629, 0.00481094690600, 0.00460395301471, 0.00438018617447, 0.00412516423270, 0.00384564081246, 0.00354012465507,
0.00320918858098, 0.00284467578623, 0.00245085400321, 0.00202741761850, 0.00157846825768, 0.00109023290512, 0.00058322642480, 0.00002760451905,
-0.00054642808664, -0.00115681355227, -0.00180394725893, -0.00248267236449, -0.00319337783900, -0.00394011240522, -0.00472225962400, -0.00553372111088,
-0.00637922932685, -0.00726158168517, -0.00817982333726, -0.00913253296085, -0.01011502154986, -0.01113155480321, -0.01218499959508, -0.01327182200351,
0.01439046660792, 0.01554055533423, 0.01673247129989, 0.01794333813443, 0.01918724313698, 0.02045317933555, 0.02174675502535, 0.02306801692862,
0.02441609920285, 0.02578758475467, 0.02718594296329, 0.02860721736385, 0.03005026574279, 0.03150176087389, 0.03297540810337, 0.03446209487686,
0.03596975605542, 0.03748128504252, 0.03900536794745, 0.04053491705584, 0.04206490946367, 0.04360975421304, 0.04514884056413, 0.04668430272642,
0.04821657200672, 0.04973857556014, 0.05125561555216, 0.05276307465207, 0.05424527683589, 0.05571736482138, 0.05716164501299, 0.05859156836260,
0.05998374801761, 0.06134551717207, 0.06268578081172, 0.06397158980681, 0.06522471064380, 0.06643675122104, 0.06760759851228, 0.06870438283512,
0.06976302447127, 0.07076287107266, 0.07170026731102, 0.07256825833083, 0.07336202550803, 0.07410036424342, 0.07474525581194, 0.07531373362019,
0.07580083586584, 0.07619924793396, 0.07649921704119, 0.07670934904245, 0.07681739756964, 0.07682300113923, 0.07672049241746, 0.07650507183194,
0.07617483218536, 0.07573057565061, 0.07515762552870, 0.07446643947564, 0.07364060057620, 0.07267746427299, 0.07158263647903, 0.07035330735093,
0.06896640131951, 0.06745250215166, 0.06576906686508, 0.06394448059633, 0.06196027790387, 0.05981665708090, 0.05751526919867, 0.05504600343009,
0.05240938217366, 0.04959786763445, 0.04663033051701, 0.04347687821958, 0.04014582784127, 0.03664181168133, 0.03295839306691, 0.02908240060125,
0.02503075618909, 0.02079970728622, 0.01637012582228, 0.01176238327857, 0.00696368621617, 0.00197656014503, -0.00320868968304, -0.00857117491366,
-0.01412888273558, -0.01988341292573, -0.02582272888064, -0.03195312745332, -0.03827765720822, -0.04478068215856, -0.05148041767934, -0.05837053268336,
-0.06544098531359, -0.07269433008129, -0.08013729344279, -0.08775475365593, -0.09555333528914, -0.10353295311463, -0.11168269317730, -0.12000779846800,
-0.12850028503878, -0.13715517611934, -0.14597664911870, -0.15496070710605, -0.16409588556669, -0.17338081721706, -0.18281725485142, -0.19239667457267,
-0.20212501768103, -0.21197358538056, -0.22196526964149, -0.23206908706791, -0.24230168845974, -0.25264803095722, -0.26310532994603, -0.27366340405625,
-0.28432141891085, -0.29507167170646, -0.30590985751916, -0.31682789136456, -0.32781137272105, -0.33887226938665, -0.34999141229310, -0.36115899031355,
0.37237955463061, 0.38363500139043, 0.39492117615675, 0.40623176767625, 0.41756968968409, 0.42891199207373, 0.44025537543665, 0.45159965356824,
0.46293080852757, 0.47424532146115, 0.48552530911099, 0.49677082545707, 0.50798175000434, 0.51912349702391, 0.53022408956855, 0.54125534487322,
0.55220512585061, 0.56307891401370, 0.57385241316923, 0.58454032354679, 0.59511230862496, 0.60557835389180, 0.61591099320291, 0.62612426956055,
0.63619801077286, 0.64612696959461, 0.65590163024671, 0.66551398801627, 0.67496631901712, 0.68423532934598, 0.69332823767032, 0.70223887193539,
0.71094104263095, 0.71944626349561, 0.72774489002994, 0.73582117582769, 0.74368278636488, 0.75131374561237, 0.75870807608242, 0.76586748650939,
0.77277808813327, 0.77942875190216, 0.78583531203920, 0.79197358416424, 0.79784664137700, 0.80344857518505, 0.80876950044491, 0.81381912706217,
0.81857760046468, 0.82304198905409, 0.82722753473360, 0.83110384571520, 0.83469373618402, 0.83797173378865, 0.84095413924722, 0.84362382812005,
0.84598184698206, 0.84803157770763, 0.84978051984268, 0.85119715249343, 0.85230470352147, 0.85310209497017, 0.85357205739107, 0.85373856005937,
0.85357205739107, 0.85310209497017, 0.85230470352147, 0.85119715249343, 0.84978051984268, 0.84803157770763, 0.84598184698206, 0.84362382812005,
0.84095413924722, 0.83797173378865, 0.83469373618402, 0.83110384571520, 0.82722753473360, 0.82304198905409, 0.81857760046468, 0.81381912706217,
0.80876950044491, 0.80344857518505, 0.79784664137700, 0.79197358416424, 0.78583531203920, 0.77942875190216, 0.77277808813327, 0.76586748650939,
0.75870807608242, 0.75131374561237, 0.74368278636488, 0.73582117582769, 0.72774489002994, 0.71944626349561, 0.71094104263095, 0.70223887193539,
0.69332823767032, 0.68423532934598, 0.67496631901712, 0.66551398801627, 0.65590163024671, 0.64612696959461, 0.63619801077286, 0.62612426956055,
0.61591099320291, 0.60557835389180, 0.59511230862496, 0.58454032354679, 0.57385241316923, 0.56307891401370, 0.55220512585061, 0.54125534487322,
0.53022408956855, 0.51912349702391, 0.50798175000434, 0.49677082545707, 0.48552530911099, 0.47424532146115, 0.46293080852757, 0.45159965356824,
0.44025537543665, 0.42891199207373, 0.41756968968409, 0.40623176767625, 0.39492117615675, 0.38363500139043, 0.37237955463061, 0.36115899031355,
-0.34999141229310, -0.33887226938665, -0.32781137272105, -0.31682789136456, -0.30590985751916, -0.29507167170646, -0.28432141891085, -0.27366340405625,
-0.26310532994603, -0.25264803095722, -0.24230168845974, -0.23206908706791, -0.22196526964149, -0.21197358538056, -0.20212501768103, -0.19239667457267,
-0.18281725485142, -0.17338081721706, -0.16409588556669, -0.15496070710605, -0.14597664911870, -0.13715517611934, -0.12850028503878, -0.12000779846800,
-0.11168269317730, -0.10353295311463, -0.09555333528914, -0.08775475365593, -0.08013729344279, -0.07269433008129, -0.06544098531359, -0.05837053268336,
-0.05148041767934, -0.04478068215856, -0.03827765720822, -0.03195312745332, -0.02582272888064, -0.01988341292573, -0.01412888273558, -0.00857117491366,
-0.00320868968304, 0.00197656014503, 0.00696368621617, 0.01176238327857, 0.01637012582228, 0.02079970728622, 0.02503075618909, 0.02908240060125,
0.03295839306691, 0.03664181168133, 0.04014582784127, 0.04347687821958, 0.04663033051701, 0.04959786763445, 0.05240938217366, 0.05504600343009,
0.05751526919867, 0.05981665708090, 0.06196027790387, 0.06394448059633, 0.06576906686508, 0.06745250215166, 0.06896640131951, 0.07035330735093,
0.07158263647903, 0.07267746427299, 0.07364060057620, 0.07446643947564, 0.07515762552870, 0.07573057565061, 0.07617483218536, 0.07650507183194,
0.07672049241746, 0.07682300113923, 0.07681739756964, 0.07670934904245, 0.07649921704119, 0.07619924793396, 0.07580083586584, 0.07531373362019,
0.07474525581194, 0.07410036424342, 0.07336202550803, 0.07256825833083, 0.07170026731102, 0.07076287107266, 0.06976302447127, 0.06870438283512,
0.06760759851228, 0.06643675122104, 0.06522471064380, 0.06397158980681, 0.06268578081172, 0.06134551717207, 0.05998374801761, 0.05859156836260,
0.05716164501299, 0.05571736482138, 0.05424527683589, 0.05276307465207, 0.05125561555216, 0.04973857556014, 0.04821657200672, 0.04668430272642,
0.04514884056413, 0.04360975421304, 0.04206490946367, 0.04053491705584, 0.03900536794745, 0.03748128504252, 0.03596975605542, 0.03446209487686,
0.03297540810337, 0.03150176087389, 0.03005026574279, 0.02860721736385, 0.02718594296329, 0.02578758475467, 0.02441609920285, 0.02306801692862,
0.02174675502535, 0.02045317933555, 0.01918724313698, 0.01794333813443, 0.01673247129989, 0.01554055533423, 0.01439046660792, 0.01327182200351,
-0.01218499959508, -0.01113155480321, -0.01011502154986, -0.00913253296085, -0.00817982333726, -0.00726158168517, -0.00637922932685, -0.00553372111088,
-0.00472225962400, -0.00394011240522, -0.00319337783900, -0.00248267236449, -0.00180394725893, -0.00115681355227, -0.00054642808664, 0.00002760451905,
0.00058322642480, 0.00109023290512, 0.00157846825768, 0.00202741761850, 0.00245085400321, 0.00284467578623, 0.00320918858098, 0.00354012465507,
0.00384564081246, 0.00412516423270, 0.00438018617447, 0.00460395301471, 0.00481094690600, 0.00498396877629, 0.00513822754514, 0.00527157587272,
0.00538389758970, 0.00547537830770, 0.00554043639400, 0.00559171286630, 0.00562661141932, 0.00563891995151, 0.00564551969164, 0.00562206432097,
0.00559380230045, 0.00554757145088, 0.00548760401507, 0.00541967759307, 0.00534716811982, 0.00524611661324, 0.00514073539032, 0.00503930226013,
0.00491376035745, 0.00479325608498, 0.00466064606118, 0.00452098527825, 0.00437307196781, 0.00422642692270, 0.00408197531935, 0.00392074323703,
0.00376039229104, 0.00360082681231, 0.00344188741828, 0.00327396134847, 0.00311254206525, 0.00294694477165, 0.00278704643465, 0.00262017586902,
0.00246256169126, 0.00230172547746, 0.00214615835557, 0.00198411407369, 0.00183482654224, 0.00168680832531, 0.00154432198471, 0.00139024948272,
0.00125778846475, 0.00112501551307, 0.00098859883015, 0.00086084433262, 0.00074580258865, 0.00062393761391, 0.00051073884952, 0.00040265402160,
0.00029495311041, 0.00020430170688, 0.00010943831274, 0.00001349497418, -0.00006173344072, -0.00014463809349, -0.00020983373440, -0.00028969811748,
-0.00035011758756, -0.00040951214522, -0.00046063254803, -0.00051455722108, -0.00055645763906, -0.00059461189330, -0.00063415949025, -0.00066504150893,
-0.00069179375372, -0.00072153919876, -0.00073193571525, -0.00075300014201, -0.00076307935757, -0.00077579773310, -0.00078014496257, -0.00078036647100,
-0.00077798694927, -0.00078343322877, -0.00077248485949, -0.00076813719270, -0.00074905980532, -0.00074409418541, -0.00072550431222, -0.00071577364744,
-0.00069416146273, -0.00067776907764, -0.00065403333621, -0.00063124935319, -0.00061327473938, -0.00058709304852, -0.00056778025613, -0.00054665656337,
-0.00052265642972, -0.00050407143497, -0.00048937912498, -0.00048752279712, -0.00049475180896, -0.00056176925738, -0.00055252865047, 0.00000000000000,
];
/// The SBR noise table `V` (Table I.13): 512 unit-variance complex values (re, im).
#[rustfmt::skip]
pub(crate) static NOISE: [[f32; 2]; 512] = [
[-0.99948153278296, -0.59483417516607], [0.97113454393991, -0.67528515225647], [0.14130051758487, -0.95090983575689], [-0.47005496701697, -0.37340549728647],
[0.80705063769351, 0.29653668284408], [-0.38981478896926, 0.89572605717087], [-0.01053049862020, -0.66959058036166], [-0.91266367957293, -0.11522938140034],
[0.54840422910309, 0.75221367176302], [0.40009252867955, -0.98929400334421], [-0.99867974711855, -0.88147068645358], [-0.95531076805040, 0.90908757154593],
[-0.45725933317144, -0.56716323646760], [-0.72929675029275, -0.98008272727324], [0.75622801399036, 0.20950329995549], [0.07069442601050, -0.78247898470706],
[0.74496252926055, -0.91169004445807], [-0.96440182703856, -0.94739918296622], [0.30424629369539, -0.49438267012479], [0.66565033746925, 0.64652935542491],
[0.91697008020594, 0.17514097332009], [-0.70774918760427, 0.52548653416543], [-0.70051415345560, -0.45340028808763], [-0.99496513054797, -0.90071908066973],
[0.98164490790123, -0.77463155528697], [-0.54671580548181, -0.02570928536004], [-0.01689629065389, 0.00287506445732], [-0.86110349531986, 0.42548583726477],
[-0.98892980586032, -0.87881132267556], [0.51756627678691, 0.66926784710139], [-0.99635026409640, -0.58107730574765], [-0.99969370862163, 0.98369989360250],
[0.55266258627194, 0.59449057465591], [0.34581177741673, 0.94879421061866], [0.62664209577999, -0.74402970906471], [-0.77149701404973, -0.33883658042801],
[-0.91592244254432, 0.03687901376713], [-0.76285492357887, -0.91371867919124], [0.79788337195331, -0.93180971199849], [0.54473080610200, -0.11919206037186],
[-0.85639281671058, 0.42429854760451], [-0.92882402971423, 0.27871809078609], [-0.11708371046774, -0.99800843444966], [0.21356749817493, -0.90716295627033],
[-0.76191692573909, 0.99768118356265], [0.98111043100884, -0.95854459734407], [-0.85913269895572, 0.95766566168880], [-0.93307242253692, 0.49431757696466],
[0.30485754879632, -0.70540034357529], [0.85289650925190, 0.46766131791044], [0.91328082618125, -0.99839597361769], [-0.05890199924154, 0.70741827819497],
[0.28398686150148, 0.34633555702188], [0.95258164539612, -0.54893416026939], [-0.78566324168507, -0.75568541079691], [-0.95789495447877, -0.20423194696966],
[0.82411158711197, 0.96654618432562], [-0.65185446735885, -0.88734990773289], [-0.93643603134666, 0.99870790442385], [0.91427159529618, -0.98290505544444],
[-0.70395684036886, 0.58796798221039], [0.00563771969365, 0.61768196727244], [0.89065051931895, 0.52783352697585], [-0.68683707712762, 0.80806944710339],
[0.72165342518718, -0.69259857349564], [-0.62928247730667, 0.13627037407335], [0.29938434065514, -0.46051329682246], [-0.91781958879280, -0.74012716684186],
[0.99298717043688, 0.40816610075661], [0.82368298622748, -0.74036047190173], [-0.98512833386833, -0.99972330709594], [-0.95915368242257, -0.99237800466040],
[-0.21411126572790, -0.93424819052545], [-0.68821476106884, -0.26892306315457], [0.91851997982317, 0.09358228901785], [-0.96062769559127, 0.36099095133739],
[0.51646184922287, -0.71373332873917], [0.61130721139669, 0.46950141175917], [0.47336129371299, -0.27333178296162], [0.90998308703519, 0.96715662938132],
[0.44844799194357, 0.99211574628306], [0.66614891079092, 0.96590176169121], [0.74922239129237, -0.89879858826087], [-0.99571588506485, 0.52785521494349],
[0.97401082477563, -0.16855870075190], [0.72683747733879, -0.48060774432251], [0.95432193457128, 0.68849603408441], [-0.72962208425191, -0.76608443420917],
[-0.85359479233537, 0.88738125901579], [-0.81412430338535, -0.97480768049637], [-0.87930772356786, 0.74748307690436], [-0.71573331064977, -0.98570608178923],
[0.83524300028228, 0.83702537075163], [-0.48086065601423, -0.98848504923531], [0.97139128574778, 0.80093621198236], [0.51992825347895, 0.80247631400510],
[-0.00848591195325, -0.76670128000486], [-0.70294374303036, 0.55359910445577], [-0.95894428168140, -0.43265504344783], [0.97079252950321, 0.09325857238682],
[-0.92404293670797, 0.85507704027855], [-0.69506469500450, 0.98633412625459], [0.26559203620024, 0.73314307966524], [0.28038443336943, 0.14537913654427],
[-0.74138124825523, 0.99310339807762], [-0.01752795995444, -0.82616635284178], [-0.55126773094930, -0.98898543862153], [0.97960898850996, -0.94021446752851],
[-0.99196309146936, 0.67019017358456], [-0.67684928085260, 0.12631491649378], [0.09140039465500, -0.20537731453108], [-0.71658965751996, -0.97788200391224],
[0.81014640078925, 0.53722648362443], [0.40616991671205, -0.26469008598449], [-0.67680188682972, 0.94502052337695], [0.86849774348749, -0.18333598647899],
[-0.99500381284851, -0.02634122068550], [0.84329189340667, 0.10406957462213], [-0.09215968531446, 0.69540012101253], [0.99956173327206, -0.12358542001404],
[-0.79732779473535, -0.91582524736159], [0.96349973642406, 0.96640458041000], [-0.79942778496547, 0.64323902822857], [-0.11566039853896, 0.28587846253726],
[-0.39922954514662, 0.94129601616966], [0.99089197565987, -0.92062625581587], [0.28631285179909, -0.91035047143603], [-0.83302725605608, -0.67330410892084],
[0.95404443402072, 0.49162765398743], [-0.06449863579434, 0.03250560813135], [-0.99575054486311, 0.42389784469507], [-0.65501142790847, 0.82546114655624],
[-0.81254441908887, -0.51627234660629], [-0.99646369485481, 0.84490533520752], [0.00287840603348, 0.64768261158166], [0.70176989408455, -0.20453028573322],
[0.96361882270190, 0.40706967140989], [-0.68883758192426, 0.91338958840772], [-0.34875585502238, 0.71472290693300], [0.91980081243087, 0.66507455644919],
[-0.99009048343881, 0.85868021604848], [0.68865791458395, 0.55660316809678], [-0.99484402129368, -0.20052559254934], [0.94214511408023, -0.99696425367461],
[-0.67414626793544, 0.49548221180078], [-0.47339353684664, -0.85904328834047], [0.14323651387360, -0.94145598222488], [-0.29268293575672, 0.05759224927952],
[0.43793861458754, -0.78904969892724], [-0.36345126374441, 0.64874435357162], [-0.08750604656825, 0.97686944362527], [-0.96495267812511, -0.53960305946511],
[0.55526940659947, 0.78891523734774], [0.73538215752630, 0.96452072373404], [-0.30889773919437, -0.80664389776860], [0.03574995626194, -0.97325616900959],
[0.98720684660488, 0.48409133691962], [-0.81689296271203, -0.90827703628298], [0.67866860118215, 0.81284503870856], [-0.15808569732583, 0.85279555024382],
[0.80723395114371, -0.24717418514605], [0.47788757329038, -0.46333147839295], [0.96367554763201, 0.38486749303242], [-0.99143875716818, -0.24945277239809],
[0.83081876925833, -0.94780851414763], [-0.58753191905341, 0.01290772389163], [0.95538108220960, -0.85557052096538], [-0.96490920476211, -0.64020970923102],
[-0.97327101028521, 0.12378128133110], [0.91400366022124, 0.57972471346930], [-0.99925837363824, 0.71084847864067], [-0.86875903507313, -0.20291699203564],
[-0.26240034795124, -0.68264554369108], [-0.24664412953388, -0.87642273115183], [0.02416275806869, 0.27192914288905], [0.82068619590515, -0.85087787994476],
[0.88547373760759, -0.89636802901469], [-0.18173078152226, -0.26152145156800], [0.09355476558534, 0.54845123045604], [-0.54668414224090, 0.95980774020221],
[0.37050990604091, -0.59910140383171], [-0.70373594262891, 0.91227665827081], [-0.34600785879594, -0.99441426144200], [-0.68774481731008, -0.30238837956299],
[-0.26843291251234, 0.83115668004362], [0.49072334613242, -0.45359708737775], [0.38975993093975, 0.95515358099121], [-0.97757125224150, 0.05305894580606],
[-0.17325552859616, -0.92770672250494], [0.99948035025744, 0.58285545563426], [-0.64946246527458, 0.68645507104960], [-0.12016920576437, -0.57147322153312],
[-0.58947456517751, -0.34847132454388], [-0.41815140454465, 0.16276422358861], [0.99885650204884, 0.11136095490444], [-0.56649614128386, -0.90494866361587],
[0.94138021032330, 0.35281916733018], [-0.75725076534641, 0.53650549640587], [0.20541973692630, -0.94435144369918], [0.99980371023351, 0.79835913565599],
[0.29078277605775, 0.35393777921520], [-0.62858772103030, 0.38765693387102], [0.43440904467688, -0.98546330463232], [-0.98298583762390, 0.21021524625209],
[0.19513029146934, -0.94239832251867], [-0.95476662400101, 0.98364554179143], [0.93379635304810, -0.70881994583682], [-0.85235410573336, -0.08342347966410],
[-0.86425093011245, -0.45795025029466], [0.38879779059045, 0.97274429344593], [0.92045124735495, -0.62433652524220], [0.89162532251878, 0.54950955570563],
[-0.36834336949252, 0.96458298020975], [0.93891760988045, -0.89968353740388], [0.99267657565094, -0.03757034316958], [-0.94063471614176, 0.41332338538963],
[0.99740224117019, -0.16830494996370], [-0.35899413170555, -0.46633226649613], [0.05237237274947, -0.25640361602661], [0.36703583957424, -0.38653265641875],
[0.91653180367913, -0.30587628726597], [0.69000803499316, 0.90952171386132], [-0.38658751133527, 0.99501571208985], [-0.29250814029851, 0.37444994344615],
[-0.60182204677608, 0.86779651036123], [-0.97418588163217, 0.96468523666475], [0.88461574003963, 0.57508405276414], [0.05198933055162, 0.21269661669964],
[-0.53499621979720, 0.97241553731237], [-0.49429560226497, 0.98183865291903], [-0.98935142339139, -0.40249159006933], [-0.98081380091130, -0.72856895534041],
[-0.27338148835532, 0.99950922447209], [0.06310802338302, -0.54539587529618], [-0.20461677199539, -0.14209977628489], [0.66223843141647, 0.72528579940326],
[-0.84764345483665, 0.02372316801261], [-0.89039863483811, 0.88866581484602], [0.95903308477986, 0.76744927173873], [0.73504123909879, -0.03747203173192],
[-0.31744434966056, -0.36834111883652], [-0.34110827591623, 0.40211222807691], [0.47803883714199, -0.39423219786288], [0.98299195879514, 0.01989791390047],
[-0.30963073129751, -0.18076720599336], [0.99992588229018, -0.26281872094289], [-0.93149731080767, -0.98313162570490], [0.99923472302773, -0.80142993767554],
[-0.26024169633417, -0.75999759855752], [-0.35712514743563, 0.19298963768574], [-0.99899084509530, 0.74645156992493], [0.86557171579452, 0.55593866696299],
[0.33408042438752, 0.86185953874709], [0.99010736374716, 0.04602397576623], [-0.66694269691195, -0.91643611810148], [0.64016792079480, 0.15649530836856],
[0.99570534804836, 0.45844586038111], [-0.63431466947340, 0.21079116459234], [-0.07706847005931, -0.89581437101329], [0.98590090577724, 0.88241721133981],
[0.80099335254678, -0.36851896710853], [0.78368131392666, 0.45506999802597], [0.08707806671691, 0.80938994918745], [-0.86811883080712, 0.39347308654705],
[-0.39466529740375, -0.66809432114456], [0.97875325649683, -0.72467840967746], [-0.95038560288864, 0.89563219587625], [0.17005239424212, 0.54683053962658],
[-0.76910792026848, -0.96226617549298], [0.99743281016846, 0.42697157037567], [0.95437383549973, 0.97002324109952], [0.99578905365569, -0.54106826257356],
[0.28058259829990, -0.85361420634036], [0.85256524470573, -0.64567607735589], [-0.50608540105128, -0.65846015480300], [-0.97210735183243, -0.23095213067791],
[0.95424048234441, -0.99240147091219], [-0.96926570524023, 0.73775654896574], [0.30872163214726, 0.41514960556126], [-0.24523839572639, 0.63206633394807],
[-0.33813265086024, -0.38661779441897], [-0.05826828420146, -0.06940774188029], [-0.22898461455054, 0.97054853316316], [-0.18509915019881, 0.47565762892084],
[-0.10488238045009, -0.87769947402394], [-0.71886586182037, 0.78030982480538], [0.99793873738654, 0.90041310491497], [0.57563307626120, -0.91034337352097],
[0.28909646383717, 0.96307783970534], [0.42188998312520, 0.48148651230437], [0.93335049681047, -0.43537023883588], [-0.97087374418267, 0.86636445711364],
[0.36722871286923, 0.65291654172961], [-0.81093025665696, 0.08778370229363], [-0.26240603062237, -0.92774095379098], [0.83996497984604, 0.55839849139647],
[-0.99909615720225, -0.96024605713970], [0.74649464155061, 0.12144893606462], [-0.74774595569805, -0.26898062008959], [0.95781667469567, -0.79047927052628],
[0.95472308713099, -0.08588776019550], [0.48708332746299, 0.99999041579432], [0.46332038247497, 0.10964126185063], [-0.76497004940162, 0.89210929242238],
[0.57397389364339, 0.35289703373760], [0.75374316974495, 0.96705214651335], [-0.59174397685714, -0.89405370422752], [0.75087906691890, -0.29612672982396],
[-0.98607857336230, 0.25034911730023], [-0.40761056640505, -0.90045573444695], [0.66929266740477, 0.98629493401748], [-0.97463695257310, -0.00190223301301],
[0.90145509409859, 0.99781390365446], [-0.87259289048043, 0.99233587353666], [-0.91529461447692, -0.15698707534206], [-0.03305738840705, -0.37205262859764],
[0.07223051368337, -0.88805001733626], [0.99498012188353, 0.97094358113387], [-0.74904939500519, 0.99985483641521], [0.04585228574211, 0.99812337444082],
[-0.89054954257993, -0.31791913188064], [-0.83782144651251, 0.97637632547466], [0.33454804933804, -0.86231516800408], [-0.99707579362824, 0.93237990079441],
[-0.22827527843994, 0.18874759397997], [0.67248046289143, -0.03646211390569], [-0.05146538187944, -0.92599700120679], [0.99947295749905, 0.93625229707912],
[0.66951124390363, 0.98905825623893], [-0.99602956559179, -0.44654715757688], [0.82104905483590, 0.99540741724928], [0.99186510988782, 0.72023001312947],
[-0.65284592392918, 0.52186723253637], [0.93885443798188, -0.74895312615259], [0.96735248738388, 0.90891816978629], [-0.22225968841114, 0.57124029781228],
[-0.44132783753414, -0.92688840659280], [-0.85694974219574, 0.88844532719844], [0.91783042091762, -0.46356892383970], [0.72556974415690, -0.99899555770747],
[-0.99711581834508, 0.58211560180426], [0.77638976371966, 0.94321834873819], [0.07717324253925, 0.58638399856595], [-0.56049829194163, 0.82522301569036],
[0.98398893639988, 0.39467440420569], [0.47546946844938, 0.68613044836811], [0.65675089314631, 0.18331637134880], [0.03273375457980, -0.74933109564108],
[-0.38684144784738, 0.51337349030406], [-0.97346267944545, -0.96549364384098], [-0.53282156061942, -0.91423265091354], [0.99817310731176, 0.61133572482148],
[-0.50254500772635, -0.88829338134294], [0.01995873238855, 0.85223515096765], [0.99930381973804, 0.94578896296649], [0.82907767600783, -0.06323442598128],
[-0.58660709669728, 0.96840773806582], [-0.17573736667267, -0.48166920859485], [0.83434292401346, -0.13023450646997], [0.05946491307025, 0.20511047074866],
[0.81505484574602, -0.94685947861369], [-0.44976380954860, 0.40894572671545], [-0.89746474625671, 0.99846578838537], [0.39677256130792, -0.74854668609359],
[-0.07588948563079, 0.74096214084170], [0.76343198951445, 0.41746629422634], [-0.74490104699626, 0.94725911744610], [0.64880119792759, 0.41336660830571],
[0.62319537462542, -0.93098313552599], [0.42215817594807, -0.07712787385208], [0.02704554141885, -0.05417518053666], [0.80001773566818, 0.91542195141039],
[-0.79351832348816, -0.36208897989136], [0.63872359151636, 0.08128252493444], [0.52890520960295, 0.60048872455592], [0.74238552914587, 0.04491915291044],
[0.99096131449250, -0.19451182854402], [-0.80412329643109, -0.88513818199457], [-0.64612616129736, 0.72198674804544], [0.11657770663191, -0.83662833815041],
[-0.95053182488101, -0.96939905138082], [-0.62228872928622, 0.82767262846661], [0.03004475787316, -0.99738896333384], [-0.97987214341034, 0.36526129686425],
[-0.99986980746200, -0.36021610299715], [0.89110648599879, -0.97894250343044], [0.10407960510582, 0.77357793811619], [0.95964737821728, -0.35435818285502],
[0.50843233159162, 0.96107691266205], [0.17006334670615, -0.76854025314829], [0.25872675063360, 0.99893303933816], [-0.01115998681937, 0.98496019742444],
[-0.79598702973261, 0.97138411318894], [-0.99264708948101, -0.99542822402536], [-0.99829663752818, 0.01877138824311], [-0.70801016548184, 0.33680685948117],
[-0.70467057786826, 0.93272777501857], [0.99846021905254, -0.98725746254433], [-0.63364968534650, -0.16473594423746], [-0.16258217500792, -0.95939125400802],
[-0.43645594360633, -0.94805030113284], [-0.99848471702976, 0.96245166923809], [-0.16796458968998, -0.98987511890470], [-0.87979225745213, -0.71725725041680],
[0.44183099021786, -0.93568974498761], [0.93310180125532, -0.99913308068246], [-0.93941931782002, -0.56409379640356], [-0.88590003188677, 0.47624600491382],
[0.99971463703691, -0.83889954253462], [-0.75376385639978, 0.00814643438625], [0.93887685615875, -0.11284528204636], [0.85126435782309, 0.52349251543547],
[0.39701421446381, 0.81779634174316], [-0.37024464187437, -0.87071656222959], [-0.36024828242896, 0.34655735648287], [-0.93388812549209, -0.84476541096429],
[-0.65298804552119, -0.18439575450921], [0.11960319006843, 0.99899346780168], [0.94292565553160, 0.83163906518293], [0.75081145286948, -0.35533223142265],
[0.56721979748394, -0.24076836414499], [0.46857766746029, -0.30140233457198], [0.97312313923635, -0.99548191630031], [-0.38299976567017, 0.98516909715427],
[0.41025800019463, 0.02116736935734], [0.09638062008048, 0.04411984381457], [-0.85283249275397, 0.91475563922421], [0.88866808958124, -0.99735267083226],
[-0.48202429536989, -0.96805608884164], [0.27572582416567, 0.58634753335832], [-0.65889129659168, 0.58835634138583], [0.98838086953732, 0.99994349600236],
[-0.20651349620689, 0.54593044066355], [-0.62126416356920, -0.59893681700392], [0.20320105410437, -0.86879180355289], [-0.97790548600584, 0.96290806999242],
[0.11112534735126, 0.21484763313301], [-0.41368337314182, 0.28216837680365], [0.24133038992960, 0.51294362630238], [-0.66393410674885, -0.08249679629081],
[-0.53697829178752, -0.97649903936228], [-0.97224737889348, 0.22081333579837], [0.87392477144549, -0.12796173740361], [0.19050361015753, 0.01602615387195],
[-0.46353441212724, -0.95249041539006], [-0.07064096339021, -0.94479803205886], [-0.92444085484466, -0.10457590187436], [-0.83822593578728, -0.01695043208885],
[0.75214681811150, -0.99955681042665], [-0.42102998829339, 0.99720941999394], [-0.72094786237696, -0.35008961934255], [0.78843311019251, 0.52851398958271],
[0.97394027897442, -0.26695944086561], [0.99206463477946, -0.57010120849429], [0.76789609461795, -0.76519356730966], [-0.82002421836409, -0.73530179553767],
[0.81924990025724, 0.99698425250579], [-0.26719850873357, 0.68903369776193], [-0.43311260380975, 0.85321815947490], [0.99194979673836, 0.91876249766422],
[-0.80692001248487, -0.32627540663214], [0.43080003649976, -0.21919095636638], [0.67709491937357, -0.95478075822906], [0.56151770568316, -0.70693811747778],
[0.10831862810749, -0.08628837174592], [0.91229417540436, -0.65987351408410], [-0.48972893932274, 0.56289246362686], [-0.89033658689697, -0.71656563987082],
[0.65269447475094, 0.65916004833932], [0.67439478141121, -0.81684380846796], [-0.47770832416973, -0.16789556203025], [-0.99715979260878, -0.93565784007648],
[-0.90889593602546, 0.62034397054380], [-0.06618622548177, -0.23812217221359], [0.99430266919728, 0.18812555317553], [0.97686402381843, -0.28664534366620],
[0.94813650221268, -0.97506640027128], [-0.95434497492853, -0.79607978501983], [-0.49104783137150, 0.32895214359663], [0.99881175120751, 0.88993983831354],
[0.50449166760303, -0.85995072408434], [0.47162891065108, -0.18680204049569], [-0.62081581361840, 0.75000676218956], [-0.43867015250812, 0.99998069244322],
[0.98630563232075, -0.53578899600662], [-0.61510362277374, -0.89515019899997], [-0.03841517601843, -0.69888815681179], [-0.30102157304644, -0.07667808922205],
[0.41881284182683, 0.02188098922282], [-0.86135454941237, 0.98947480909359], [0.67226861393788, -0.13494389011014], [-0.70737398842068, -0.76547349325992],
[0.94044946687963, 0.09026201157416], [-0.82386352534327, 0.08924768823676], [-0.32070666698656, 0.50143421908753], [0.57593163224487, -0.98966422921509],
[-0.36326018419965, 0.07440243123228], [0.99979044674350, -0.14130287347405], [-0.92366023326932, -0.97979298068180], [-0.44607178518598, -0.54233252016394],
[0.44226800932956, 0.71326756742752], [0.03671907158312, 0.63606389366675], [0.52175424682195, -0.85396826735705], [-0.94701139690956, -0.01826348194255],
[-0.98759606946049, 0.82288714303073], [0.87434794743625, 0.89399495655433], [-0.93412041758744, 0.41374052024363], [0.96063943315511, 0.93116709541280],
[0.97534253457837, 0.86150930812689], [0.99642466504163, 0.70190043427512], [-0.94705089665984, -0.29580042814306], [0.91599807087376, -0.98147830385781],
];
/// `t_huffman_env_1_5dB` (`(codeword, length)` by index): envelope, time direction, 1.5 dB steps (LAV 60).
#[rustfmt::skip]
pub(crate) static T_ENV_1_5DB: [(u32, u8); 121] = [
(0x3ffd6, 18), (0x3ffd7, 18), (0x3ffd8, 18), (0x3ffd9, 18), (0x3ffda, 18), (0x3ffdb, 18), (0x7ffb8, 19), (0x7ffb9, 19),
(0x7ffba, 19), (0x7ffbb, 19), (0x7ffbc, 19), (0x7ffbd, 19), (0x7ffbe, 19), (0x7ffbf, 19), (0x7ffc0, 19), (0x7ffc1, 19),
(0x7ffc2, 19), (0x7ffc3, 19), (0x7ffc4, 19), (0x7ffc5, 19), (0x7ffc6, 19), (0x7ffc7, 19), (0x7ffc8, 19), (0x7ffc9, 19),
(0x7ffca, 19), (0x7ffcb, 19), (0x7ffcc, 19), (0x7ffcd, 19), (0x7ffce, 19), (0x7ffcf, 19), (0x7ffd0, 19), (0x7ffd1, 19),
(0x7ffd2, 19), (0x7ffd3, 19), (0x1ffe6, 17), (0x3ffd4, 18), (0xfff0, 16), (0x1ffe9, 17), (0x3ffd5, 18), (0x1ffe7, 17),
(0xfff1, 16), (0xffec, 16), (0xffed, 16), (0xffee, 16), (0x7ff4, 15), (0x3ff9, 14), (0x3ff7, 14), (0x1ffa, 13),
(0x1ff9, 13), (0xffb, 12), (0x7fc, 11), (0x3fc, 10), (0x1fd, 9), (0xfd, 8), (0x7d, 7), (0x3d, 6),
(0x1d, 5), (0xd, 4), (0x5, 3), (0x1, 2), (0x0, 2), (0x4, 3), (0xc, 4), (0x1c, 5),
(0x3c, 6), (0x7c, 7), (0xfc, 8), (0x1fc, 9), (0x3fd, 10), (0xffa, 12), (0x1ff8, 13), (0x3ff6, 14),
(0x3ff8, 14), (0x7ff5, 15), (0xffef, 16), (0x1ffe8, 17), (0xfff2, 16), (0x7ffd4, 19), (0x7ffd5, 19), (0x7ffd6, 19),
(0x7ffd7, 19), (0x7ffd8, 19), (0x7ffd9, 19), (0x7ffda, 19), (0x7ffdb, 19), (0x7ffdc, 19), (0x7ffdd, 19), (0x7ffde, 19),
(0x7ffdf, 19), (0x7ffe0, 19), (0x7ffe1, 19), (0x7ffe2, 19), (0x7ffe3, 19), (0x7ffe4, 19), (0x7ffe5, 19), (0x7ffe6, 19),
(0x7ffe7, 19), (0x7ffe8, 19), (0x7ffe9, 19), (0x7ffea, 19), (0x7ffeb, 19), (0x7ffec, 19), (0x7ffed, 19), (0x7ffee, 19),
(0x7ffef, 19), (0x7fff0, 19), (0x7fff1, 19), (0x7fff2, 19), (0x7fff3, 19), (0x7fff4, 19), (0x7fff5, 19), (0x7fff6, 19),
(0x7fff7, 19), (0x7fff8, 19), (0x7fff9, 19), (0x7fffa, 19), (0x7fffb, 19), (0x7fffc, 19), (0x7fffd, 19), (0x7fffe, 19),
(0x7ffff, 19),
];
/// `f_huffman_env_1_5dB` (`(codeword, length)` by index): envelope, frequency direction, 1.5 dB steps (LAV 60).
#[rustfmt::skip]
pub(crate) static F_ENV_1_5DB: [(u32, u8); 121] = [
(0x7ffe7, 19), (0x7ffe8, 19), (0xfffd2, 20), (0xfffd3, 20), (0xfffd4, 20), (0xfffd5, 20), (0xfffd6, 20), (0xfffd7, 20),
(0xfffd8, 20), (0x7ffda, 19), (0xfffd9, 20), (0xfffda, 20), (0xfffdb, 20), (0xfffdc, 20), (0x7ffdb, 19), (0xfffdd, 20),
(0x7ffdc, 19), (0x7ffdd, 19), (0xfffde, 20), (0x3ffe4, 18), (0xfffdf, 20), (0xfffe0, 20), (0xfffe1, 20), (0x7ffde, 19),
(0xfffe2, 20), (0xfffe3, 20), (0xfffe4, 20), (0x7ffdf, 19), (0xfffe5, 20), (0x7ffe0, 19), (0x3ffe8, 18), (0x7ffe1, 19),
(0x3ffe0, 18), (0x3ffe9, 18), (0x1ffef, 17), (0x3ffe5, 18), (0x1ffec, 17), (0x1ffed, 17), (0x1ffee, 17), (0xfff4, 16),
(0xfff3, 16), (0xfff0, 16), (0x7ff7, 15), (0x7ff6, 15), (0x3ffa, 14), (0x1ffa, 13), (0x1ff9, 13), (0xffa, 12),
(0xff8, 12), (0x7f9, 11), (0x3fb, 10), (0x1fc, 9), (0x1fa, 9), (0xfb, 8), (0x7c, 7), (0x3c, 6),
(0x1c, 5), (0xc, 4), (0x5, 3), (0x1, 2), (0x0, 2), (0x4, 3), (0xd, 4), (0x1d, 5),
(0x3d, 6), (0xfa, 8), (0xfc, 8), (0x1fb, 9), (0x3fa, 10), (0x7f8, 11), (0x7fa, 11), (0x7fb, 11),
(0xff9, 12), (0xffb, 12), (0x1ff8, 13), (0x1ffb, 13), (0x3ff8, 14), (0x3ff9, 14), (0xfff1, 16), (0xfff2, 16),
(0x1ffea, 17), (0x1ffeb, 17), (0x3ffe1, 18), (0x3ffe2, 18), (0x3ffea, 18), (0x3ffe3, 18), (0x3ffe6, 18), (0x3ffe7, 18),
(0x3ffeb, 18), (0xfffe6, 20), (0x7ffe2, 19), (0xfffe7, 20), (0xfffe8, 20), (0xfffe9, 20), (0xfffea, 20), (0xfffeb, 20),
(0xfffec, 20), (0x7ffe3, 19), (0xfffed, 20), (0xfffee, 20), (0xfffef, 20), (0xffff0, 20), (0x7ffe4, 19), (0xffff1, 20),
(0x3ffec, 18), (0xffff2, 20), (0xffff3, 20), (0x7ffe5, 19), (0x7ffe6, 19), (0xffff4, 20), (0xffff5, 20), (0xffff6, 20),
(0xffff7, 20), (0xffff8, 20), (0xffff9, 20), (0xffffa, 20), (0xffffb, 20), (0xffffc, 20), (0xffffd, 20), (0xffffe, 20),
(0xfffff, 20),
];
/// `t_huffman_env_bal_1_5dB` (`(codeword, length)` by index): envelope balance, time direction, 1.5 dB steps (LAV 24).
#[rustfmt::skip]
pub(crate) static T_ENV_BAL_1_5DB: [(u32, u8); 49] = [
(0xffe4, 16), (0xffe5, 16), (0xffe6, 16), (0xffe7, 16), (0xffe8, 16), (0xffe9, 16), (0xffea, 16), (0xffeb, 16),
(0xffec, 16), (0xffed, 16), (0xffee, 16), (0xffef, 16), (0xfff0, 16), (0xfff1, 16), (0xfff2, 16), (0xfff3, 16),
(0xfff4, 16), (0xffe2, 16), (0xffc, 12), (0x7fc, 11), (0x1fe, 9), (0x7e, 7), (0x1e, 5), (0x6, 3),
(0x0, 1), (0x2, 2), (0xe, 4), (0x3e, 6), (0xfe, 8), (0x7fd, 11), (0xffd, 12), (0x7ff0, 15),
(0xffe3, 16), (0xfff5, 16), (0xfff6, 16), (0xfff7, 16), (0xfff8, 16), (0xfff9, 16), (0xfffa, 16), (0x1fff6, 17),
(0x1fff7, 17), (0x1fff8, 17), (0x1fff9, 17), (0x1fffa, 17), (0x1fffb, 17), (0x1fffc, 17), (0x1fffd, 17), (0x1fffe, 17),
(0x1ffff, 17),
];
/// `f_huffman_env_bal_1_5dB` (`(codeword, length)` by index): envelope balance, frequency direction, 1.5 dB steps (LAV 24).
#[rustfmt::skip]
pub(crate) static F_ENV_BAL_1_5DB: [(u32, u8); 49] = [
(0x3ffe2, 18), (0x3ffe3, 18), (0x3ffe4, 18), (0x3ffe5, 18), (0x3ffe6, 18), (0x3ffe7, 18), (0x3ffe8, 18), (0x3ffe9, 18),
(0x3ffea, 18), (0x3ffeb, 18), (0x3ffec, 18), (0x3ffed, 18), (0x3ffee, 18), (0x3ffef, 18), (0x3fff0, 18), (0xfff7, 16),
(0x1fff0, 17), (0x3ffc, 14), (0x7fe, 11), (0x7fc, 11), (0xfe, 8), (0x7e, 7), (0xe, 4), (0x2, 2),
(0x0, 1), (0x6, 3), (0x1e, 5), (0x3e, 6), (0x1fe, 9), (0x7fd, 11), (0xffe, 12), (0x7ffa, 15),
(0xfff6, 16), (0x3fff1, 18), (0x3fff2, 18), (0x3fff3, 18), (0x3fff4, 18), (0x3fff5, 18), (0x3fff6, 18), (0x3fff7, 18),
(0x3fff8, 18), (0x3fff9, 18), (0x3fffa, 18), (0x3fffb, 18), (0x3fffc, 18), (0x3fffd, 18), (0x3fffe, 18), (0x7fffe, 19),
(0x7ffff, 19),
];
/// `t_huffman_env_3_0dB` (`(codeword, length)` by index): envelope, time direction, 3 dB steps (LAV 31).
#[rustfmt::skip]
pub(crate) static T_ENV_3_0DB: [(u32, u8); 63] = [
(0x3ffed, 18), (0x3ffee, 18), (0x7ffde, 19), (0x7ffdf, 19), (0x7ffe0, 19), (0x7ffe1, 19), (0x7ffe2, 19), (0x7ffe3, 19),
(0x7ffe4, 19), (0x7ffe5, 19), (0x7ffe6, 19), (0x7ffe7, 19), (0x7ffe8, 19), (0x7ffe9, 19), (0x7ffea, 19), (0x7ffeb, 19),
(0x7ffec, 19), (0x1fff4, 17), (0xfff7, 16), (0xfff9, 16), (0xfff8, 16), (0x3ffb, 14), (0x3ffa, 14), (0x3ff8, 14),
(0x1ffa, 13), (0xffc, 12), (0x7fc, 11), (0xfe, 8), (0x3e, 6), (0xe, 4), (0x2, 2), (0x0, 1),
(0x6, 3), (0x1e, 5), (0x7e, 7), (0x1fe, 9), (0x7fd, 11), (0x1ffb, 13), (0x3ff9, 14), (0x3ffc, 14),
(0x7ffa, 15), (0xfff6, 16), (0x1fff5, 17), (0x3ffec, 18), (0x7ffed, 19), (0x7ffee, 19), (0x7ffef, 19), (0x7fff0, 19),
(0x7fff1, 19), (0x7fff2, 19), (0x7fff3, 19), (0x7fff4, 19), (0x7fff5, 19), (0x7fff6, 19), (0x7fff7, 19), (0x7fff8, 19),
(0x7fff9, 19), (0x7fffa, 19), (0x7fffb, 19), (0x7fffc, 19), (0x7fffd, 19), (0x7fffe, 19), (0x7ffff, 19),
];
/// `f_huffman_env_3_0dB` (`(codeword, length)` by index): envelope and noise floor, frequency direction, 3 dB steps (LAV 31).
#[rustfmt::skip]
pub(crate) static F_ENV_3_0DB: [(u32, u8); 63] = [
(0xffff0, 20), (0xffff1, 20), (0xffff2, 20), (0xffff3, 20), (0xffff4, 20), (0xffff5, 20), (0xffff6, 20), (0x3fff3, 18),
(0x7fff5, 19), (0x7ffee, 19), (0x7ffef, 19), (0x7fff6, 19), (0x3fff4, 18), (0x3fff2, 18), (0xffff7, 20), (0x7fff0, 19),
(0x1fff5, 17), (0x3fff0, 18), (0x1fff4, 17), (0xfff7, 16), (0xfff6, 16), (0x7ff8, 15), (0x3ffb, 14), (0xffd, 12),
(0x7fd, 11), (0x3fd, 10), (0x1fd, 9), (0xfd, 8), (0x3e, 6), (0xe, 4), (0x2, 2), (0x0, 1),
(0x6, 3), (0x1e, 5), (0xfc, 8), (0x1fc, 9), (0x3fc, 10), (0x7fc, 11), (0xffc, 12), (0x1ffc, 13),
(0x3ffa, 14), (0x7ff9, 15), (0x7ffa, 15), (0xfff8, 16), (0xfff9, 16), (0x1fff6, 17), (0x1fff7, 17), (0x3fff5, 18),
(0x3fff6, 18), (0x3fff1, 18), (0xffff8, 20), (0x7fff1, 19), (0x7fff2, 19), (0x7fff3, 19), (0xffff9, 20), (0x7fff7, 19),
(0x7fff4, 19), (0xffffa, 20), (0xffffb, 20), (0xffffc, 20), (0xffffd, 20), (0xffffe, 20), (0xfffff, 20),
];
/// `t_huffman_env_bal_3_0dB` (`(codeword, length)` by index): envelope balance, time direction, 3 dB steps (LAV 12).
#[rustfmt::skip]
pub(crate) static T_ENV_BAL_3_0DB: [(u32, u8); 25] = [
(0x1ff2, 13), (0x1ff3, 13), (0x1ff4, 13), (0x1ff5, 13), (0x1ff6, 13), (0x1ff7, 13), (0x1ff8, 13), (0xff8, 12),
(0xfe, 8), (0x7e, 7), (0xe, 4), (0x6, 3), (0x0, 1), (0x2, 2), (0x1e, 5), (0x3e, 6),
(0x1fe, 9), (0x1ff9, 13), (0x1ffa, 13), (0x1ffb, 13), (0x1ffc, 13), (0x1ffd, 13), (0x1ffe, 13), (0x3ffe, 14),
(0x3fff, 14),
];
/// `f_huffman_env_bal_3_0dB` (`(codeword, length)` by index): envelope and noise floor balance, frequency direction, 3 dB steps (LAV 12).
#[rustfmt::skip]
pub(crate) static F_ENV_BAL_3_0DB: [(u32, u8); 25] = [
(0x1ff7, 13), (0x1ff8, 13), (0x1ff9, 13), (0x1ffa, 13), (0x1ffb, 13), (0x3ff8, 14), (0x3ff9, 14), (0x7fc, 11),
(0xfe, 8), (0x7e, 7), (0xe, 4), (0x2, 2), (0x0, 1), (0x6, 3), (0x1e, 5), (0x3e, 6),
(0x1fe, 9), (0xffa, 12), (0x1ff6, 13), (0x3ffa, 14), (0x3ffb, 14), (0x3ffc, 14), (0x3ffd, 14), (0x3ffe, 14),
(0x3fff, 14),
];
/// `t_huffman_noise_3_0dB` (`(codeword, length)` by index): noise floor, time direction (LAV 31).
#[rustfmt::skip]
pub(crate) static T_NOISE_3_0DB: [(u32, u8); 63] = [
(0x1fce, 13), (0x1fcf, 13), (0x1fd0, 13), (0x1fd1, 13), (0x1fd2, 13), (0x1fd3, 13), (0x1fd4, 13), (0x1fd5, 13),
(0x1fd6, 13), (0x1fd7, 13), (0x1fd8, 13), (0x1fd9, 13), (0x1fda, 13), (0x1fdb, 13), (0x1fdc, 13), (0x1fdd, 13),
(0x1fde, 13), (0x1fdf, 13), (0x1fe0, 13), (0x1fe1, 13), (0x1fe2, 13), (0x1fe3, 13), (0x1fe4, 13), (0x1fe5, 13),
(0x1fe6, 13), (0x1fe7, 13), (0x7f2, 11), (0xfd, 8), (0x3e, 6), (0xe, 4), (0x6, 3), (0x0, 1),
(0x2, 2), (0x1e, 5), (0xfc, 8), (0x3f8, 10), (0x1fcc, 13), (0x1fe8, 13), (0x1fe9, 13), (0x1fea, 13),
(0x1feb, 13), (0x1fec, 13), (0x1fcd, 13), (0x1fed, 13), (0x1fee, 13), (0x1fef, 13), (0x1ff0, 13), (0x1ff1, 13),
(0x1ff2, 13), (0x1ff3, 13), (0x1ff4, 13), (0x1ff5, 13), (0x1ff6, 13), (0x1ff7, 13), (0x1ff8, 13), (0x1ff9, 13),
(0x1ffa, 13), (0x1ffb, 13), (0x1ffc, 13), (0x1ffd, 13), (0x1ffe, 13), (0x3ffe, 14), (0x3fff, 14),
];
/// `t_huffman_noise_bal_3_0dB` (`(codeword, length)` by index): noise floor balance, time direction (LAV 12).
#[rustfmt::skip]
pub(crate) static T_NOISE_BAL_3_0DB: [(u32, u8); 25] = [
(0xec, 8), (0xed, 8), (0xee, 8), (0xef, 8), (0xf0, 8), (0xf1, 8), (0xf2, 8), (0xf3, 8),
(0xf4, 8), (0xf5, 8), (0x1c, 5), (0x2, 2), (0x0, 1), (0x6, 3), (0x3a, 6), (0xf6, 8),
(0xf7, 8), (0xf8, 8), (0xf9, 8), (0xfa, 8), (0xfb, 8), (0xfc, 8), (0xfd, 8), (0xfe, 8),
(0xff, 8),
];
+5 -5
View File
@@ -8,9 +8,9 @@
//! `wasm32-unknown-unknown`.
//!
//! - [`decode`], [`probe`], [`Decoder`] (streaming, seekable), [`tracks`], [`detect_container`]
//! (feature `decode`): WAV and AIFF are read natively; AAC, ALAC, Opus, AC-3/E-AC-3, MP1/MP2 and
//! PCM in MP4/MOV, Matroska/WebM, Ogg or raw streams go through craft-media's demuxers and
//! [`TrackDecoder`]; everything else (MP3, FLAC, Vorbis, CAF, ADPCM, A-law, µ-law) through
//! (feature `decode`): WAV and AIFF are read natively; AAC, ALAC, Opus, AC-3/E-AC-3,
//! MP1/MP2/MP3 and PCM in MP4/MOV, Matroska/WebM, Ogg or raw streams go through craft-media's
//! demuxers and [`TrackDecoder`]; everything else (FLAC, Vorbis, CAF, ADPCM, A-law, µ-law) through
//! `symphonia`, which is to be replaced by native decoders. Feature `decode-native` is the
//! same without symphonia.
//! - [`TrackDecoder`] (any decoder feature): one track's packets from any demuxer to planar
@@ -25,7 +25,7 @@
//! - [`peaks`] (feature `peaks`): min/max/RMS pyramid for waveform drawing.
//! - Codec modules for packet-level use, each with its own features: [`aac`] (`aac-decode`,
//! `aac-encode`), [`alac`] (`alac-decode`, `alac-encode`), [`opus`] (`opus-decode`), [`ac3`]
//! (`ac3-decode`), [`mpa`] (`mpa-decode`), [`mp3`] (`mp3-encode`: the Layer III encoder),
//! (`ac3-decode`), [`mpa`] (`mpa-decode`), [`mp3`] (`mp3-decode`, `mp3-encode`),
//! [`flac`] (`flac-encode`: the packet encoder).
//!
//! The shared types below build with no features.
@@ -38,7 +38,7 @@ pub mod ac3;
pub mod alac;
mod buffer;
mod layout;
#[cfg(feature = "mp3-encode")]
#[cfg(any(feature = "mp3-encode", feature = "mp3-decode"))]
pub mod mp3;
#[cfg(feature = "mpa-decode")]
pub mod mpa;
File diff suppressed because it is too large Load Diff
+479
View File
@@ -0,0 +1,479 @@
//! The Layer III encoder; the module docs are in `mp3/mod.rs`.
// Index loops follow the specification's pseudo-code (FilmCraft allows this lint workspace-wide).
#![allow(clippy::needless_range_loop)]
use std::collections::VecDeque;
use craft_media::bitstream::BitWriter;
use super::filterbank::{Analysis, GRANULE};
use super::quantize::{Granule, Model};
use super::tables;
/// Settings an [`Encoder`] refuses.
#[non_exhaustive]
#[derive(Debug, thiserror::Error, PartialEq, Eq)]
pub enum Error {
/// A sample rate outside [`SAMPLE_RATES`].
#[error("MP3: unsupported sample rate {0} Hz (32, 44.1, 48 kHz, or 16, 22.05, 24 kHz)")]
SampleRate(u32),
/// A bit rate that is not one of [`bitrates`] for the sample rate.
#[error("MP3: unsupported bit rate {kbps} kbit/s at {rate} Hz")]
Bitrate {
/// The bit rate asked for, kbit/s.
kbps: u32,
/// The sample rate, Hz.
rate: u32,
},
/// More than two channels, or none.
#[error("MP3: unsupported channel count {0} (1 or 2)")]
Channels(usize),
}
/// Result with this module's [`Error`].
pub type Result<T> = std::result::Result<T, Error>;
/// How two channels are coded.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum StereoMode {
/// Left and right coded independently (`mode` 00).
Stereo,
/// Joint stereo (`mode` 01): each frame chooses left / right or mid / side.
#[default]
JointStereo,
}
/// Encoder settings.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Config {
/// One of [`SAMPLE_RATES`].
pub sample_rate: u32,
/// 1 or 2.
pub channels: usize,
/// One of [`bitrates`] for the sample rate, kbit/s.
pub bitrate_kbps: u32,
/// How two channels are coded (ignored for mono).
pub stereo: StereoMode,
}
impl Config {
/// `channels` at `sample_rate`, constant `bitrate_kbps`, joint stereo.
pub fn cbr(sample_rate: u32, channels: usize, bitrate_kbps: u32) -> Config {
Config { sample_rate, channels, bitrate_kbps, stereo: StereoMode::JointStereo }
}
}
/// Whether the sample rate needs MPEG-2's lower sampling frequencies.
fn is_lsf(rate: u32) -> Option<bool> {
if tables::RATES_MPEG1.contains(&rate) {
Some(false)
} else if tables::RATES_LSF.contains(&rate) {
Some(true)
} else {
None
}
}
/// The sample rates the encoder accepts.
pub const SAMPLE_RATES: [u32; 6] = [32_000, 44_100, 48_000, 16_000, 22_050, 24_000];
/// The bit rates (kbit/s) a stream at `sample_rate` can use; empty for an unsupported rate.
pub fn bitrates(sample_rate: u32) -> &'static [u32] {
match is_lsf(sample_rate) {
Some(false) => &tables::BITRATES_MPEG1,
Some(true) => &tables::BITRATES_LSF,
None => &[],
}
}
/// The highest bit rate at `sample_rate` not above `kbps` (the lowest one when `kbps` is below
/// all of them); `None` for an unsupported rate.
pub fn nearest_bitrate(sample_rate: u32, kbps: u32) -> Option<u32> {
let rates = bitrates(sample_rate);
rates.iter().rev().find(|&&r| r <= kbps).or(rates.first()).copied()
}
/// The supported sample rate an encoder should use for audio at `rate`: `rate` itself when
/// supported, else the closest supported one at or above it (48 kHz above 48 kHz).
pub fn nearest_sample_rate(rate: u32) -> u32 {
let mut sorted = SAMPLE_RATES;
sorted.sort_unstable();
sorted.iter().copied().find(|&r| r >= rate).unwrap_or(48_000)
}
/// Energy of the frequency lines of a full-scale sine (amplitude 1) over one granule.
const FULL_SCALE_TONE_ENERGY: f32 = 1.0;
/// Playback level of a full-scale sine assumed by the threshold in quiet, dB SPL.
const FULL_SCALE_SPL: f64 = 96.0;
/// Samples by which a standard decoder's output lags the input: the polyphase analysis and
/// synthesis filters (481) and the MDCT overlap of one granule (576).
pub const DELAY: u32 = 1057;
/// A Layer III encoder. Feed planar `f32` samples (full scale ±1) to [`Encoder::encode`]; it
/// returns whole frames as they are completed. [`Encoder::flush`] pads the end with silence and
/// returns the rest.
///
/// ```
/// use craft_audio::mp3::{Config, DELAY, Encoder};
///
/// let left: Vec<f32> = (0..48_000).map(|i| (i as f32 * 0.05).sin() * 0.5).collect();
/// let right = left.clone();
/// let mut enc = Encoder::new(Config::cbr(48_000, 2, 192))?;
/// let mut mp3 = enc.encode(&[&left, &right]); // whole frames as they complete
/// mp3.extend(enc.flush()); // pads with silence to the last input sample
/// assert_eq!(mp3.len() % 576, 0); // 192 kbit/s at 48 kHz: 576 bytes per frame
/// assert_eq!(DELAY, 1057); // a decoder's output lags the input by this many samples
/// # Ok::<(), craft_audio::mp3::Error>(())
/// ```
pub struct Encoder {
cfg: Config,
lsf: bool,
sr_index: u32,
br_index: u32,
granules: usize,
analysis: Vec<Analysis>,
model: Model,
/// Buffered input per channel, and how much of it is consumed.
input: Vec<Vec<f32>>,
consumed: usize,
/// Frames whose main-data slot is not yet filled: header + side information, slot bytes.
pending: VecDeque<(Vec<u8>, usize)>,
/// Main data from the first pending frame's slot on.
main: Vec<u8>,
/// Slot bytes of the pending frames.
slot_total: usize,
/// Largest `main_data_begin`, bytes.
max_reservoir: usize,
/// Remainder accumulator for the padding slot (44.1 / 22.05 kHz).
pad_acc: u64,
samples_in: u64,
frames: u64,
}
impl Encoder {
/// An encoder for `cfg`, or the setting it cannot carry.
pub fn new(cfg: Config) -> Result<Encoder> {
let lsf = is_lsf(cfg.sample_rate).ok_or(Error::SampleRate(cfg.sample_rate))?;
if !(1..=2).contains(&cfg.channels) {
return Err(Error::Channels(cfg.channels));
}
let rates = if lsf { &tables::RATES_LSF } else { &tables::RATES_MPEG1 };
let sr_index = rates.iter().position(|&r| r == cfg.sample_rate).ok_or(Error::SampleRate(cfg.sample_rate))?;
let br_index = bitrates(cfg.sample_rate)
.iter()
.position(|&b| b == cfg.bitrate_kbps)
.ok_or(Error::Bitrate { kbps: cfg.bitrate_kbps, rate: cfg.sample_rate })?;
let bands = if lsf { tables::SFB_LSF[sr_index] } else { tables::SFB_MPEG1[sr_index] };
let line_hz = cfg.sample_rate as f64 / 2.0 / GRANULE as f64;
let mut ath = [0f32; 22];
for (b, a) in ath.iter_mut().enumerate() {
let (lo, hi) = (usize::from(bands[b]), usize::from(bands[b + 1]));
let db = (lo..hi).map(|i| tables::ath_db((i as f64 + 0.5) * line_hz)).fold(f64::MAX, f64::min);
*a = (f64::from(FULL_SCALE_TONE_ENERGY) * 10f64.powf((db - FULL_SCALE_SPL) / 10.0)) as f32;
}
let cutoff_hz = cutoff_hz(cfg.bitrate_kbps, cfg.channels).min(cfg.sample_rate as f64 * 0.5);
let cutoff = ((cutoff_hz / line_hz).ceil() as usize).min(GRANULE);
let frame_bits = u64::from(cfg.bitrate_kbps) * 1000 * if lsf { 576 } else { 1152 } / u64::from(cfg.sample_rate);
// reservoir and frame must fit the decoder's 7680-bit input buffer
let max_reservoir = (7680u64.saturating_sub(frame_bits) / 8).min(if lsf { 255 } else { 511 }) as usize;
Ok(Encoder {
cfg,
lsf,
sr_index: sr_index as u32,
br_index: br_index as u32 + 1,
granules: if lsf { 1 } else { 2 },
analysis: vec![Analysis::new(); cfg.channels],
model: Model::new(lsf, bands, ath, cutoff),
input: vec![Vec::new(); cfg.channels],
consumed: 0,
pending: VecDeque::new(),
main: Vec::new(),
slot_total: 0,
max_reservoir,
pad_acc: 0,
samples_in: 0,
frames: 0,
})
}
/// The settings.
pub fn config(&self) -> &Config {
&self.cfg
}
/// Samples per channel in a frame: 1152 (MPEG-1) or 576 (MPEG-2 LSF).
pub fn frame_samples(&self) -> usize {
GRANULE * self.granules
}
/// Samples by which a standard decoder's output lags the input.
pub fn delay(&self) -> u32 {
DELAY
}
/// Frames written so far.
pub fn frames(&self) -> u64 {
self.frames
}
/// Encode planar samples (one slice per channel; a missing channel is silence, extra ones
/// are ignored, every channel takes the first channel's length). Returns the completed frames.
pub fn encode(&mut self, planar: &[&[f32]]) -> Vec<u8> {
let n = planar.first().map_or(0, |p| p.len());
for (c, buf) in self.input.iter_mut().enumerate() {
let src = planar.get(c).copied().unwrap_or(&[]);
buf.extend((0..n).map(|i| src.get(i).copied().filter(|v| v.is_finite()).unwrap_or(0.0).clamp(-4.0, 4.0)));
}
self.samples_in = self.samples_in.saturating_add(n as u64);
let mut out = Vec::new();
self.drain(&mut out);
out
}
/// Encode the buffered rest padded with silence, plus enough silence that a decoder outputs
/// every input sample, and return the remaining frames.
pub fn flush(&mut self) -> Vec<u8> {
let fs = self.frame_samples() as u64;
let needed = if self.samples_in == 0 { self.frames } else { self.samples_in.saturating_add(u64::from(DELAY)).div_ceil(fs) };
let have = self.input.first().map_or(0, |b| b.len().saturating_sub(self.consumed));
let want = (needed.saturating_sub(self.frames) as usize).saturating_mul(fs as usize);
if want > have {
for buf in &mut self.input {
buf.resize(self.consumed + want, 0.0);
}
}
let mut out = Vec::new();
self.drain(&mut out);
// fill the last frames' slots and write them out
self.main.resize(self.slot_total.max(self.main.len()), 0);
self.emit(&mut out);
self.input.iter_mut().for_each(Vec::clear);
self.consumed = 0;
out
}
/// Encode every whole frame of buffered input.
fn drain(&mut self, out: &mut Vec<u8>) {
let fs = self.frame_samples();
let mut pcm = vec![[0f32; GRANULE]; self.cfg.channels * self.granules];
while self.input.first().is_some_and(|b| b.len() - self.consumed >= fs) {
for (c, buf) in self.input.iter().enumerate() {
for gr in 0..self.granules {
let start = self.consumed + gr * GRANULE;
if let (Some(dst), Some(src)) = (pcm.get_mut(gr * self.cfg.channels + c), buf.get(start..start + GRANULE)) {
dst.copy_from_slice(src);
}
}
}
self.consumed += fs;
self.encode_frame(&pcm);
self.emit(out);
}
if self.consumed > 0 {
let k = self.consumed;
self.input.iter_mut().for_each(|b| {
b.drain(..k.min(b.len()));
});
self.consumed = 0;
}
}
/// Bytes of the next frame (with its padding slot).
fn next_frame_len(&mut self) -> usize {
let per = if self.lsf { 72_000 } else { 144_000 };
let num = per * u64::from(self.cfg.bitrate_kbps);
let sr = u64::from(self.cfg.sample_rate);
self.pad_acc += num % sr;
let pad = self.pad_acc >= sr;
if pad {
self.pad_acc -= sr;
}
(num / sr) as usize + usize::from(pad)
}
fn side_info_len(&self) -> usize {
match (self.lsf, self.cfg.channels) {
(false, 1) => 17,
(false, _) => 32,
(true, 1) => 9,
(true, _) => 17,
}
}
/// Analyse, quantize and assemble one frame (`pcm[gr * channels + ch]`).
fn encode_frame(&mut self, pcm: &[[f32; GRANULE]]) {
let nch = self.cfg.channels;
let ngr = self.granules;
let mut xr = vec![[0f32; GRANULE]; nch * ngr];
for gr in 0..ngr {
for ch in 0..nch {
let k = gr * nch + ch;
if let (Some(a), Some(p), Some(x)) = (self.analysis.get_mut(ch), pcm.get(k), xr.get_mut(k)) {
a.granule(p, x);
x.iter_mut().skip(self.model.cutoff).for_each(|v| *v = 0.0);
}
}
}
let mut xmin: Vec<[f32; 22]> = xr.iter().map(|x| self.model.thresholds(x)).collect();
let ms = nch == 2 && self.cfg.stereo == StereoMode::JointStereo && use_mid_side(&xr);
if ms {
for gr in 0..ngr {
let (l, r) = xr.split_at_mut(gr * 2 + 1);
if let (Some(l), Some(r)) = (l.last_mut(), r.first_mut()) {
for (a, b) in l.iter_mut().zip(r.iter_mut()) {
let (m, s) = ((*a + *b) * std::f32::consts::FRAC_1_SQRT_2, (*a - *b) * std::f32::consts::FRAC_1_SQRT_2);
*a = m;
*b = s;
}
}
let t: [f32; 22] = std::array::from_fn(|b| xmin[gr * 2][b].min(xmin[gr * 2 + 1][b]));
xmin[gr * 2] = t;
xmin[gr * 2 + 1] = t;
}
}
// the reservoir: free bytes in the pending frames' slots, stuffed down to the maximum
let free = self.slot_total.saturating_sub(self.main.len());
if free > self.max_reservoir {
self.main.resize(self.slot_total - self.max_reservoir, 0);
}
let main_data_begin = free.min(self.max_reservoir);
let frame_len = self.next_frame_len();
let slot = frame_len.saturating_sub(4 + self.side_info_len());
let budget = 8 * (main_data_begin + slot);
let n = nch * ngr;
let mean = 8 * slot / n;
let max_reservoir_bits = 8 * self.max_reservoir;
let mut used = 0usize;
let mut coded: Vec<Granule> = Vec::with_capacity(n);
for (k, (x, t)) in xr.iter().zip(&xmin).enumerate() {
let left = n - k;
let remaining = budget.saturating_sub(used);
let surplus = remaining.saturating_sub(mean * left);
let max_bits = (mean + surplus * 3 / 5 / left).min(remaining).min(4095);
let room = max_reservoir_bits.saturating_sub(surplus);
let min_bits = mean.saturating_sub(room / left);
let g = self.model.encode(x, t, max_bits, min_bits);
used += g.bits();
coded.push(g);
}
let mut md = BitWriter::new();
for g in &coded {
g.write(&mut md, &self.model);
}
let mut main = md.finish();
if main.len() > main_data_begin + slot || coded.iter().any(|g| g.bits() > 4095) {
// never expected: fall back to silence rather than write a broken frame
coded = (0..n).map(|_| self.model.encode(&[0.0; GRANULE], &[f32::MAX; 22], 0, 0)).collect();
main = Vec::new();
}
let head = self.header_and_side_info(frame_len, ms, main_data_begin, &coded);
self.pending.push_back((head, slot));
self.slot_total += slot;
self.main.extend_from_slice(&main);
self.frames += 1;
}
/// Write out the pending frames whose slots are full.
fn emit(&mut self, out: &mut Vec<u8>) {
while let Some((_, slot)) = self.pending.front() {
let slot = *slot;
if self.main.len() < slot {
break;
}
if let Some((head, _)) = self.pending.pop_front() {
out.extend_from_slice(&head);
out.extend(self.main.drain(..slot));
self.slot_total -= slot;
}
}
}
fn header_and_side_info(&self, frame_len: usize, ms: bool, main_data_begin: usize, coded: &[Granule]) -> Vec<u8> {
let nch = self.cfg.channels;
let padding = frame_len > (if self.lsf { 72_000 } else { 144_000 } * self.cfg.bitrate_kbps / self.cfg.sample_rate) as usize;
let mode = match (nch, self.cfg.stereo) {
(1, _) => 3,
(_, StereoMode::Stereo) => 0,
(_, StereoMode::JointStereo) => 1,
};
let mut w = BitWriter::new();
w.write_bits(0x7FF, 11);
w.write_bits(if self.lsf { 2 } else { 3 }, 2); // ID: MPEG-1 = 11, MPEG-2 = 10
w.write_bits(1, 2); // Layer III
w.write_bit(true); // protection_bit: no CRC
w.write_bits(self.br_index, 4);
w.write_bits(self.sr_index, 2);
w.write_bit(padding);
w.write_bit(false); // private_bit
w.write_bits(mode, 2);
w.write_bits(if ms { 2 } else { 0 }, 2); // mode_extension: mid/side, no intensity
w.write_bit(false); // copyright
w.write_bit(true); // original
w.write_bits(0, 2); // emphasis
if self.lsf {
w.write_bits(main_data_begin as u32, 8);
w.write_bits(0, if nch == 1 { 1 } else { 2 });
} else {
w.write_bits(main_data_begin as u32, 9);
w.write_bits(0, if nch == 1 { 5 } else { 3 });
w.write_bits(0, 4 * nch as u32); // scfsi
}
for g in coded {
let c = &g.coding;
w.write_bits(g.bits() as u32, 12);
w.write_bits(c.big_values as u32, 9);
w.write_bits(g.global_gain, 8);
w.write_bits(g.scalefac_compress, if self.lsf { 9 } else { 4 });
w.write_bit(false); // window_switching_flag
for t in c.table_select {
w.write_bits(t as u32, 5);
}
w.write_bits(c.region0_count as u32, 4);
w.write_bits(c.region1_count as u32, 3);
if !self.lsf {
w.write_bit(false); // preflag
}
w.write_bit(g.scalefac_scale);
w.write_bits(c.count1_table as u32, 1);
}
w.finish()
}
}
/// Mid/side for a frame when the side signal is much weaker than the mid signal.
fn use_mid_side(xr: &[[f32; GRANULE]]) -> bool {
let (mut m, mut s) = (0f64, 0f64);
for pair in xr.as_chunks::<2>().0 {
for (l, r) in pair[0].iter().zip(pair[1].iter()) {
let (a, b) = (f64::from(*l), f64::from(*r));
m += (a + b) * (a + b);
s += (a - b) * (a - b);
}
}
s < 0.25 * m
}
/// The low-pass for a bit rate: the band the bits can carry (joint stereo counted as 1.6
/// channels' worth).
fn cutoff_hz(kbps: u32, channels: usize) -> f64 {
let per = f64::from(kbps) / if channels > 1 { 1.6 } else { 1.0 };
const STEPS: [(f64, f64); 11] = [
(140.0, 20_000.0),
(120.0, 19_000.0),
(100.0, 18_000.0),
(80.0, 16_500.0),
(64.0, 15_000.0),
(56.0, 13_500.0),
(48.0, 12_000.0),
(40.0, 10_000.0),
(32.0, 8_000.0),
(24.0, 6_500.0),
(16.0, 5_000.0),
];
STEPS.iter().find(|(k, _)| per >= *k).map_or(3_500.0, |s| s.1)
}
#[cfg(test)]
#[path = "tests.rs"]
mod tests;
+1
View File
@@ -338,4 +338,5 @@ pub(crate) const LINBITS: [u32; 32] = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
pub(crate) const QUAD_A_CODES: [u8; 16] = [1, 5, 4, 5, 6, 5, 4, 4, 7, 3, 6, 0, 7, 2, 3, 1];
pub(crate) const QUAD_A_LENS: [u8; 16] = [1, 4, 4, 5, 4, 6, 5, 6, 4, 5, 5, 6, 5, 6, 6, 6];
/// Count1 table B: four bits, the inverted quadruple.
#[cfg(feature = "mp3-encode")]
pub(crate) const QUAD_B_CODES: [u8; 16] = [15, 14, 13, 12, 11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0];
+27 -476
View File
@@ -1,4 +1,19 @@
//! Clean-room MPEG-1 / MPEG-2 Audio Layer III (MP3) encoder, written from ISO/IEC 11172-3:1993
//! MPEG-1 / MPEG-2 Audio Layer III (MP3): a clean-room decoder ([`Decoder`], feature
//! `mp3-decode`) and encoder ([`Encoder`], feature `mp3-encode`), written from ISO/IEC 11172-3
//! and ISO/IEC 13818-3. They share the Huffman code tables and scalefactor bands.
//!
//! # Decoder (feature `mp3-decode`)
//!
//! [`Decoder`] decodes Layer III frames one at a time: MPEG-1, the MPEG-2 lower sampling
//! frequencies and MPEG-2.5 (8-48 kHz), every bit rate (CBR or VBR), mono, stereo, dual channel
//! and joint stereo (mid/side and intensity), long, short and mixed blocks, across the bit
//! reservoir. [`InfoTag`] reads the Xing / Info or VBRI frame at the start of a file and the
//! LAME tag's encoder delay and padding. `craft_audio::decode` (feature `decode-native`) reads
//! `.mp3` files and MP3 in MP4 and Matroska through them, gapless.
//!
//! # Encoder (feature `mp3-encode`)
//!
//! A clean-room encoder, written from ISO/IEC 11172-3:1993
//! (MPEG-1 Audio: §2.4.1 bit stream syntax, §2.4.2 semantics, Annex B tables, Annex C encoding
//! process) and ISO/IEC 13818-3:1998 (the lower sampling frequencies).
//!
@@ -13,490 +28,26 @@
//! - Output: a plain stream of frames, no ID3 or Xing / Info tag, no CRC. The frames written one
//! after another are a playable `.mp3` file.
//!
//! No decoder here: [`mpa`](crate::mpa) decodes Layers I and II, and files with Layer III are read
//! through `symphonia` (feature `decode`).
//!
//! ```
//! use craft_audio::mp3::{Config, DELAY, Encoder};
//!
//! let left: Vec<f32> = (0..48_000).map(|i| (i as f32 * 0.05).sin() * 0.5).collect();
//! let right = left.clone();
//! let mut enc = Encoder::new(Config::cbr(48_000, 2, 192))?;
//! let mut mp3 = enc.encode(&[&left, &right]); // whole frames as they complete
//! mp3.extend(enc.flush()); // pads with silence to the last input sample
//! assert_eq!(mp3.len() % 576, 0); // 192 kbit/s at 48 kHz: 576 bytes per frame
//! assert_eq!(DELAY, 1057); // a decoder's output lags the input by this many samples
//! # Ok::<(), craft_audio::mp3::Error>(())
//! ```
//!
//! From FilmCraft's `filmcraft-mp3enc` (storytold/filmcraft@4bec22b). Public items keep their
//! names, so FilmCraft can re-export this module.
// Index loops follow the specification's pseudo-code (FilmCraft allows this lint workspace-wide).
#![allow(clippy::needless_range_loop)]
#[cfg(feature = "mp3-decode")]
mod decoder;
#[cfg(feature = "mp3-encode")]
mod encoder;
#[cfg(feature = "mp3-encode")]
mod filterbank;
#[cfg(feature = "mp3-encode")]
mod huffman;
mod huffman_tables;
#[cfg(feature = "mp3-encode")]
mod quantize;
mod tables;
use std::collections::VecDeque;
use craft_media::bitstream::BitWriter;
use filterbank::{Analysis, GRANULE};
use quantize::{Granule, Model};
/// Settings an [`Encoder`] refuses.
#[non_exhaustive]
#[derive(Debug, thiserror::Error, PartialEq, Eq)]
pub enum Error {
/// A sample rate outside [`SAMPLE_RATES`].
#[error("MP3: unsupported sample rate {0} Hz (32, 44.1, 48 kHz, or 16, 22.05, 24 kHz)")]
SampleRate(u32),
/// A bit rate that is not one of [`bitrates`] for the sample rate.
#[error("MP3: unsupported bit rate {kbps} kbit/s at {rate} Hz")]
Bitrate {
/// The bit rate asked for, kbit/s.
kbps: u32,
/// The sample rate, Hz.
rate: u32,
},
/// More than two channels, or none.
#[error("MP3: unsupported channel count {0} (1 or 2)")]
Channels(usize),
}
/// Result with this module's [`Error`].
pub type Result<T> = std::result::Result<T, Error>;
/// How two channels are coded.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum StereoMode {
/// Left and right coded independently (`mode` 00).
Stereo,
/// Joint stereo (`mode` 01): each frame chooses left / right or mid / side.
#[default]
JointStereo,
}
/// Encoder settings.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Config {
/// One of [`SAMPLE_RATES`].
pub sample_rate: u32,
/// 1 or 2.
pub channels: usize,
/// One of [`bitrates`] for the sample rate, kbit/s.
pub bitrate_kbps: u32,
/// How two channels are coded (ignored for mono).
pub stereo: StereoMode,
}
impl Config {
/// `channels` at `sample_rate`, constant `bitrate_kbps`, joint stereo.
pub fn cbr(sample_rate: u32, channels: usize, bitrate_kbps: u32) -> Config {
Config { sample_rate, channels, bitrate_kbps, stereo: StereoMode::JointStereo }
}
}
/// Whether the sample rate needs MPEG-2's lower sampling frequencies.
fn is_lsf(rate: u32) -> Option<bool> {
if tables::RATES_MPEG1.contains(&rate) {
Some(false)
} else if tables::RATES_LSF.contains(&rate) {
Some(true)
} else {
None
}
}
/// The sample rates the encoder accepts.
pub const SAMPLE_RATES: [u32; 6] = [32_000, 44_100, 48_000, 16_000, 22_050, 24_000];
/// The bit rates (kbit/s) a stream at `sample_rate` can use; empty for an unsupported rate.
pub fn bitrates(sample_rate: u32) -> &'static [u32] {
match is_lsf(sample_rate) {
Some(false) => &tables::BITRATES_MPEG1,
Some(true) => &tables::BITRATES_LSF,
None => &[],
}
}
/// The highest bit rate at `sample_rate` not above `kbps` (the lowest one when `kbps` is below
/// all of them); `None` for an unsupported rate.
pub fn nearest_bitrate(sample_rate: u32, kbps: u32) -> Option<u32> {
let rates = bitrates(sample_rate);
rates.iter().rev().find(|&&r| r <= kbps).or(rates.first()).copied()
}
/// The supported sample rate an encoder should use for audio at `rate`: `rate` itself when
/// supported, else the closest supported one at or above it (48 kHz above 48 kHz).
pub fn nearest_sample_rate(rate: u32) -> u32 {
let mut sorted = SAMPLE_RATES;
sorted.sort_unstable();
sorted.iter().copied().find(|&r| r >= rate).unwrap_or(48_000)
}
/// Energy of the frequency lines of a full-scale sine (amplitude 1) over one granule.
const FULL_SCALE_TONE_ENERGY: f32 = 1.0;
/// Playback level of a full-scale sine assumed by the threshold in quiet, dB SPL.
const FULL_SCALE_SPL: f64 = 96.0;
/// Samples by which a standard decoder's output lags the input: the polyphase analysis and
/// synthesis filters (481) and the MDCT overlap of one granule (576).
pub const DELAY: u32 = 1057;
/// A Layer III encoder. Feed planar `f32` samples (full scale ±1) to [`Encoder::encode`]; it
/// returns whole frames as they are completed. [`Encoder::flush`] pads the end with silence and
/// returns the rest.
pub struct Encoder {
cfg: Config,
lsf: bool,
sr_index: u32,
br_index: u32,
granules: usize,
analysis: Vec<Analysis>,
model: Model,
/// Buffered input per channel, and how much of it is consumed.
input: Vec<Vec<f32>>,
consumed: usize,
/// Frames whose main-data slot is not yet filled: header + side information, slot bytes.
pending: VecDeque<(Vec<u8>, usize)>,
/// Main data from the first pending frame's slot on.
main: Vec<u8>,
/// Slot bytes of the pending frames.
slot_total: usize,
/// Largest `main_data_begin`, bytes.
max_reservoir: usize,
/// Remainder accumulator for the padding slot (44.1 / 22.05 kHz).
pad_acc: u64,
samples_in: u64,
frames: u64,
}
impl Encoder {
/// An encoder for `cfg`, or the setting it cannot carry.
pub fn new(cfg: Config) -> Result<Encoder> {
let lsf = is_lsf(cfg.sample_rate).ok_or(Error::SampleRate(cfg.sample_rate))?;
if !(1..=2).contains(&cfg.channels) {
return Err(Error::Channels(cfg.channels));
}
let rates = if lsf { &tables::RATES_LSF } else { &tables::RATES_MPEG1 };
let sr_index = rates.iter().position(|&r| r == cfg.sample_rate).ok_or(Error::SampleRate(cfg.sample_rate))?;
let br_index = bitrates(cfg.sample_rate)
.iter()
.position(|&b| b == cfg.bitrate_kbps)
.ok_or(Error::Bitrate { kbps: cfg.bitrate_kbps, rate: cfg.sample_rate })?;
let bands = if lsf { tables::SFB_LSF[sr_index] } else { tables::SFB_MPEG1[sr_index] };
let line_hz = cfg.sample_rate as f64 / 2.0 / GRANULE as f64;
let mut ath = [0f32; 22];
for (b, a) in ath.iter_mut().enumerate() {
let (lo, hi) = (usize::from(bands[b]), usize::from(bands[b + 1]));
let db = (lo..hi).map(|i| tables::ath_db((i as f64 + 0.5) * line_hz)).fold(f64::MAX, f64::min);
*a = (f64::from(FULL_SCALE_TONE_ENERGY) * 10f64.powf((db - FULL_SCALE_SPL) / 10.0)) as f32;
}
let cutoff_hz = cutoff_hz(cfg.bitrate_kbps, cfg.channels).min(cfg.sample_rate as f64 * 0.5);
let cutoff = ((cutoff_hz / line_hz).ceil() as usize).min(GRANULE);
let frame_bits = u64::from(cfg.bitrate_kbps) * 1000 * if lsf { 576 } else { 1152 } / u64::from(cfg.sample_rate);
// reservoir and frame must fit the decoder's 7680-bit input buffer
let max_reservoir = (7680u64.saturating_sub(frame_bits) / 8).min(if lsf { 255 } else { 511 }) as usize;
Ok(Encoder {
cfg,
lsf,
sr_index: sr_index as u32,
br_index: br_index as u32 + 1,
granules: if lsf { 1 } else { 2 },
analysis: vec![Analysis::new(); cfg.channels],
model: Model::new(lsf, bands, ath, cutoff),
input: vec![Vec::new(); cfg.channels],
consumed: 0,
pending: VecDeque::new(),
main: Vec::new(),
slot_total: 0,
max_reservoir,
pad_acc: 0,
samples_in: 0,
frames: 0,
})
}
/// The settings.
pub fn config(&self) -> &Config {
&self.cfg
}
/// Samples per channel in a frame: 1152 (MPEG-1) or 576 (MPEG-2 LSF).
pub fn frame_samples(&self) -> usize {
GRANULE * self.granules
}
/// Samples by which a standard decoder's output lags the input.
pub fn delay(&self) -> u32 {
DELAY
}
/// Frames written so far.
pub fn frames(&self) -> u64 {
self.frames
}
/// Encode planar samples (one slice per channel; a missing channel is silence, extra ones
/// are ignored, every channel takes the first channel's length). Returns the completed frames.
pub fn encode(&mut self, planar: &[&[f32]]) -> Vec<u8> {
let n = planar.first().map_or(0, |p| p.len());
for (c, buf) in self.input.iter_mut().enumerate() {
let src = planar.get(c).copied().unwrap_or(&[]);
buf.extend((0..n).map(|i| src.get(i).copied().filter(|v| v.is_finite()).unwrap_or(0.0).clamp(-4.0, 4.0)));
}
self.samples_in = self.samples_in.saturating_add(n as u64);
let mut out = Vec::new();
self.drain(&mut out);
out
}
/// Encode the buffered rest padded with silence, plus enough silence that a decoder outputs
/// every input sample, and return the remaining frames.
pub fn flush(&mut self) -> Vec<u8> {
let fs = self.frame_samples() as u64;
let needed = if self.samples_in == 0 { self.frames } else { self.samples_in.saturating_add(u64::from(DELAY)).div_ceil(fs) };
let have = self.input.first().map_or(0, |b| b.len().saturating_sub(self.consumed));
let want = (needed.saturating_sub(self.frames) as usize).saturating_mul(fs as usize);
if want > have {
for buf in &mut self.input {
buf.resize(self.consumed + want, 0.0);
}
}
let mut out = Vec::new();
self.drain(&mut out);
// fill the last frames' slots and write them out
self.main.resize(self.slot_total.max(self.main.len()), 0);
self.emit(&mut out);
self.input.iter_mut().for_each(Vec::clear);
self.consumed = 0;
out
}
/// Encode every whole frame of buffered input.
fn drain(&mut self, out: &mut Vec<u8>) {
let fs = self.frame_samples();
let mut pcm = vec![[0f32; GRANULE]; self.cfg.channels * self.granules];
while self.input.first().is_some_and(|b| b.len() - self.consumed >= fs) {
for (c, buf) in self.input.iter().enumerate() {
for gr in 0..self.granules {
let start = self.consumed + gr * GRANULE;
if let (Some(dst), Some(src)) = (pcm.get_mut(gr * self.cfg.channels + c), buf.get(start..start + GRANULE)) {
dst.copy_from_slice(src);
}
}
}
self.consumed += fs;
self.encode_frame(&pcm);
self.emit(out);
}
if self.consumed > 0 {
let k = self.consumed;
self.input.iter_mut().for_each(|b| {
b.drain(..k.min(b.len()));
});
self.consumed = 0;
}
}
/// Bytes of the next frame (with its padding slot).
fn next_frame_len(&mut self) -> usize {
let per = if self.lsf { 72_000 } else { 144_000 };
let num = per * u64::from(self.cfg.bitrate_kbps);
let sr = u64::from(self.cfg.sample_rate);
self.pad_acc += num % sr;
let pad = self.pad_acc >= sr;
if pad {
self.pad_acc -= sr;
}
(num / sr) as usize + usize::from(pad)
}
fn side_info_len(&self) -> usize {
match (self.lsf, self.cfg.channels) {
(false, 1) => 17,
(false, _) => 32,
(true, 1) => 9,
(true, _) => 17,
}
}
/// Analyse, quantize and assemble one frame (`pcm[gr * channels + ch]`).
fn encode_frame(&mut self, pcm: &[[f32; GRANULE]]) {
let nch = self.cfg.channels;
let ngr = self.granules;
let mut xr = vec![[0f32; GRANULE]; nch * ngr];
for gr in 0..ngr {
for ch in 0..nch {
let k = gr * nch + ch;
if let (Some(a), Some(p), Some(x)) = (self.analysis.get_mut(ch), pcm.get(k), xr.get_mut(k)) {
a.granule(p, x);
x.iter_mut().skip(self.model.cutoff).for_each(|v| *v = 0.0);
}
}
}
let mut xmin: Vec<[f32; 22]> = xr.iter().map(|x| self.model.thresholds(x)).collect();
let ms = nch == 2 && self.cfg.stereo == StereoMode::JointStereo && use_mid_side(&xr);
if ms {
for gr in 0..ngr {
let (l, r) = xr.split_at_mut(gr * 2 + 1);
if let (Some(l), Some(r)) = (l.last_mut(), r.first_mut()) {
for (a, b) in l.iter_mut().zip(r.iter_mut()) {
let (m, s) = ((*a + *b) * std::f32::consts::FRAC_1_SQRT_2, (*a - *b) * std::f32::consts::FRAC_1_SQRT_2);
*a = m;
*b = s;
}
}
let t: [f32; 22] = std::array::from_fn(|b| xmin[gr * 2][b].min(xmin[gr * 2 + 1][b]));
xmin[gr * 2] = t;
xmin[gr * 2 + 1] = t;
}
}
// the reservoir: free bytes in the pending frames' slots, stuffed down to the maximum
let free = self.slot_total.saturating_sub(self.main.len());
if free > self.max_reservoir {
self.main.resize(self.slot_total - self.max_reservoir, 0);
}
let main_data_begin = free.min(self.max_reservoir);
let frame_len = self.next_frame_len();
let slot = frame_len.saturating_sub(4 + self.side_info_len());
let budget = 8 * (main_data_begin + slot);
let n = nch * ngr;
let mean = 8 * slot / n;
let max_reservoir_bits = 8 * self.max_reservoir;
let mut used = 0usize;
let mut coded: Vec<Granule> = Vec::with_capacity(n);
for (k, (x, t)) in xr.iter().zip(&xmin).enumerate() {
let left = n - k;
let remaining = budget.saturating_sub(used);
let surplus = remaining.saturating_sub(mean * left);
let max_bits = (mean + surplus * 3 / 5 / left).min(remaining).min(4095);
let room = max_reservoir_bits.saturating_sub(surplus);
let min_bits = mean.saturating_sub(room / left);
let g = self.model.encode(x, t, max_bits, min_bits);
used += g.bits();
coded.push(g);
}
let mut md = BitWriter::new();
for g in &coded {
g.write(&mut md, &self.model);
}
let mut main = md.finish();
if main.len() > main_data_begin + slot || coded.iter().any(|g| g.bits() > 4095) {
// never expected: fall back to silence rather than write a broken frame
coded = (0..n).map(|_| self.model.encode(&[0.0; GRANULE], &[f32::MAX; 22], 0, 0)).collect();
main = Vec::new();
}
let head = self.header_and_side_info(frame_len, ms, main_data_begin, &coded);
self.pending.push_back((head, slot));
self.slot_total += slot;
self.main.extend_from_slice(&main);
self.frames += 1;
}
/// Write out the pending frames whose slots are full.
fn emit(&mut self, out: &mut Vec<u8>) {
while let Some((_, slot)) = self.pending.front() {
let slot = *slot;
if self.main.len() < slot {
break;
}
if let Some((head, _)) = self.pending.pop_front() {
out.extend_from_slice(&head);
out.extend(self.main.drain(..slot));
self.slot_total -= slot;
}
}
}
fn header_and_side_info(&self, frame_len: usize, ms: bool, main_data_begin: usize, coded: &[Granule]) -> Vec<u8> {
let nch = self.cfg.channels;
let padding = frame_len > (if self.lsf { 72_000 } else { 144_000 } * self.cfg.bitrate_kbps / self.cfg.sample_rate) as usize;
let mode = match (nch, self.cfg.stereo) {
(1, _) => 3,
(_, StereoMode::Stereo) => 0,
(_, StereoMode::JointStereo) => 1,
};
let mut w = BitWriter::new();
w.write_bits(0x7FF, 11);
w.write_bits(if self.lsf { 2 } else { 3 }, 2); // ID: MPEG-1 = 11, MPEG-2 = 10
w.write_bits(1, 2); // Layer III
w.write_bit(true); // protection_bit: no CRC
w.write_bits(self.br_index, 4);
w.write_bits(self.sr_index, 2);
w.write_bit(padding);
w.write_bit(false); // private_bit
w.write_bits(mode, 2);
w.write_bits(if ms { 2 } else { 0 }, 2); // mode_extension: mid/side, no intensity
w.write_bit(false); // copyright
w.write_bit(true); // original
w.write_bits(0, 2); // emphasis
if self.lsf {
w.write_bits(main_data_begin as u32, 8);
w.write_bits(0, if nch == 1 { 1 } else { 2 });
} else {
w.write_bits(main_data_begin as u32, 9);
w.write_bits(0, if nch == 1 { 5 } else { 3 });
w.write_bits(0, 4 * nch as u32); // scfsi
}
for g in coded {
let c = &g.coding;
w.write_bits(g.bits() as u32, 12);
w.write_bits(c.big_values as u32, 9);
w.write_bits(g.global_gain, 8);
w.write_bits(g.scalefac_compress, if self.lsf { 9 } else { 4 });
w.write_bit(false); // window_switching_flag
for t in c.table_select {
w.write_bits(t as u32, 5);
}
w.write_bits(c.region0_count as u32, 4);
w.write_bits(c.region1_count as u32, 3);
if !self.lsf {
w.write_bit(false); // preflag
}
w.write_bit(g.scalefac_scale);
w.write_bits(c.count1_table as u32, 1);
}
w.finish()
}
}
/// Mid/side for a frame when the side signal is much weaker than the mid signal.
fn use_mid_side(xr: &[[f32; GRANULE]]) -> bool {
let (mut m, mut s) = (0f64, 0f64);
for pair in xr.as_chunks::<2>().0 {
for (l, r) in pair[0].iter().zip(pair[1].iter()) {
let (a, b) = (f64::from(*l), f64::from(*r));
m += (a + b) * (a + b);
s += (a - b) * (a - b);
}
}
s < 0.25 * m
}
/// The low-pass for a bit rate: the band the bits can carry (joint stereo counted as 1.6
/// channels' worth).
fn cutoff_hz(kbps: u32, channels: usize) -> f64 {
let per = f64::from(kbps) / if channels > 1 { 1.6 } else { 1.0 };
const STEPS: [(f64, f64); 11] = [
(140.0, 20_000.0),
(120.0, 19_000.0),
(100.0, 18_000.0),
(80.0, 16_500.0),
(64.0, 15_000.0),
(56.0, 13_500.0),
(48.0, 12_000.0),
(40.0, 10_000.0),
(32.0, 8_000.0),
(24.0, 6_500.0),
(16.0, 5_000.0),
];
STEPS.iter().find(|(k, _)| per >= *k).map_or(3_500.0, |s| s.1)
}
#[cfg(test)]
mod tests;
#[cfg(feature = "mp3-decode")]
pub use decoder::{Decoder, InfoTag};
#[cfg(feature = "mp3-encode")]
pub use encoder::{Config, DELAY, Encoder, Error, Result, SAMPLE_RATES, StereoMode, bitrates, nearest_bitrate, nearest_sample_rate};
+10
View File
@@ -4,12 +4,16 @@ use std::sync::OnceLock;
/// Layer III bit rates in kbit/s by `bitrate_index` 1-14 (§2.4.2.3); index 0 (free format) and
/// 15 (forbidden) are never written.
#[cfg(feature = "mp3-encode")]
pub(crate) const BITRATES_MPEG1: [u32; 14] = [32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320];
/// Layer III bit rates of the lower sampling frequencies (ISO/IEC 13818-3 §2.4.2.3).
#[cfg(feature = "mp3-encode")]
pub(crate) const BITRATES_LSF: [u32; 14] = [8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160];
/// Sampling frequencies by `sampling_frequency` (0-2) of MPEG-1 and of MPEG-2 LSF.
#[cfg(feature = "mp3-encode")]
pub(crate) const RATES_MPEG1: [u32; 3] = [44_100, 48_000, 32_000];
#[cfg(feature = "mp3-encode")]
pub(crate) const RATES_LSF: [u32; 3] = [22_050, 24_000, 16_000];
/// Long-block scalefactor band boundaries (Table 3-B.8 of 11172-3; Table B.2 of 13818-3), by
@@ -31,11 +35,13 @@ pub(crate) const SLEN: [(u32, u32); 16] =
/// Scalefactor bands per partition for long blocks without intensity stereo when MPEG-2
/// `scalefac_compress` < 400 (13818-3 §2.4.3.2, `nr_of_sfb_block[0][0]`).
#[cfg(feature = "mp3-encode")]
pub(crate) const LSF_PARTITIONS: [usize; 4] = [6, 5, 5, 5];
/// Coefficients `D[0..=256]` of the synthesis window (Table 3-B.3), in units of 2⁻¹⁶: the table's
/// nine-decimal values are exact multiples of 1/65536. The analysis window of Table 3-C.1 is the
/// same prototype divided by 32: `C[i] = D[i] / 32`.
#[cfg(feature = "mp3-encode")]
const WINDOW_HALF: [i32; 257] = [
0, -1, -1, -1, -1, -1, -1, -2, -2, -2, -2, -3, -3, -4, -4, -5, //
-5, -6, -7, -7, -8, -9, -10, -11, -13, -14, -16, -17, -19, -21, -24, -26, //
@@ -59,6 +65,7 @@ const WINDOW_HALF: [i32; 257] = [
/// The 512 synthesis window coefficients `D[i]` (Table 3-B.3). The table stores the symmetric
/// prototype `h[i] = h[512 - i]` with every other block of 64 negated, so for `i > 256`
/// `D[i] = -D[512 - i]`, except at multiples of 64 where both halves share the block parity.
#[cfg(feature = "mp3-encode")]
pub(crate) fn synthesis_window() -> &'static [f32; 512] {
static W: OnceLock<[f32; 512]> = OnceLock::new();
W.get_or_init(|| {
@@ -72,6 +79,7 @@ pub(crate) fn synthesis_window() -> &'static [f32; 512] {
}
/// The analysis window `C[i]` (Table 3-C.1): `D[i] / 32`.
#[cfg(feature = "mp3-encode")]
pub(crate) fn analysis_window() -> &'static [f32; 512] {
static C: OnceLock<[f32; 512]> = OnceLock::new();
C.get_or_init(|| {
@@ -83,6 +91,7 @@ pub(crate) fn analysis_window() -> &'static [f32; 512] {
/// The analysis matrixing coefficients `M[i][k] = cos((2i + 1)(k - 16)π / 64)` (Annex C.1.3),
/// `i` in `0..32`, `k` in `0..64`.
#[cfg(feature = "mp3-encode")]
pub(crate) fn analysis_matrix() -> &'static [[f32; 64]; 32] {
static M: OnceLock<[[f32; 64]; 32]> = OnceLock::new();
M.get_or_init(|| {
@@ -119,6 +128,7 @@ pub(crate) fn pow43() -> &'static [f32] {
/// The absolute threshold of hearing in dB SPL at `f` Hz (Terhardt's approximation, as in the
/// psychoacoustic models of 11172-3 Annex D).
#[cfg(feature = "mp3-encode")]
pub(crate) fn ath_db(f: f64) -> f64 {
let k = (f.max(20.0)) / 1000.0;
3.64 * k.powf(-0.8) - 6.5 * (-0.6 * (k - 3.3) * (k - 3.3)).exp() + 0.001 * k.powi(4)
+3 -2
View File
@@ -1,6 +1,7 @@
use super::filterbank::Analysis;
use super::tables::{alias_coefficients, synthesis_window};
use super::*;
use crate::mp3::filterbank::Analysis;
use crate::mp3::tables::{alias_coefficients, synthesis_window};
use crate::mp3::{huffman, huffman_tables};
/// The decoder side of the hybrid filterbank (§2.4.3.4.10: alias butterflies, IMDCT with the
/// normal window and overlap-add, frequency inversion, polyphase synthesis), for checking the
+2 -2
View File
@@ -19,7 +19,7 @@
// Index loops follow the specification's pseudo-code (FilmCraft allows this lint workspace-wide).
#![allow(clippy::needless_range_loop)]
mod tables;
pub(crate) mod tables;
use craft_media::bitstream::BitReader;
use tables::AllocTable;
@@ -418,7 +418,7 @@ fn layer2(r: &mut BitReader, h: &Header, out: &mut Subbands) -> Result<()> {
/// The synthesis subband filter (§2.4.3.2, Figure A.2) for one time slot: 32 subband samples in,
/// 32 PCM samples out.
fn synthesize(v: &mut [f32; 1024], pos: &mut usize, n: &[[f32; 36]; 32], d: &[f32; 512], s: &[f32; 32], out: &mut [f32; 32]) {
pub(crate) fn synthesize(v: &mut [f32; 1024], pos: &mut usize, n: &[[f32; 36]; 32], d: &[f32; 512], s: &[f32; 32], out: &mut [f32; 32]) {
// shift V by 64: move the ring's start back instead of copying 960 values
*pos = (*pos + 1024 - 64) % 1024;
let p = *pos;
+4 -4
View File
@@ -95,7 +95,7 @@ fn detect_by_magic(b: &[u8], depth: u32) -> Option<Container> {
/// The file extensions of the formats [`decode`] reads, lower case and without the dot: what a
/// file picker or a browser filters by. Each is a hint [`detect_container`] knows; a file's
/// contents still decide what it is. Without the `symphonia` feature the formats only symphonia
/// decodes (FLAC, MP3, CAF) are left out.
/// decodes (FLAC, CAF) are left out.
#[cfg(feature = "symphonia")]
pub const DECODE_EXTENSIONS: &[&str] = &[
"wav", "wave", "bwf", "rf64", "aif", "aiff", "aifc", "flac", "mp3", "mp2", "mp1", "mpa", "ogg", "oga", "opus", "m4a", "m4b", "mp4", "mov", "aac",
@@ -104,11 +104,11 @@ pub const DECODE_EXTENSIONS: &[&str] = &[
/// The file extensions of the formats [`decode`] reads, lower case and without the dot: what a
/// file picker or a browser filters by. Each is a hint [`detect_container`] knows; a file's
/// contents still decide what it is. Without the `symphonia` feature the formats only symphonia
/// decodes (FLAC, MP3, CAF) are left out.
/// decodes (FLAC, CAF) are left out.
#[cfg(not(feature = "symphonia"))]
pub const DECODE_EXTENSIONS: &[&str] = &[
"wav", "wave", "bwf", "rf64", "aif", "aiff", "aifc", "mp2", "mp1", "mpa", "ogg", "oga", "opus", "m4a", "m4b", "mp4", "mov", "aac", "adts", "ac3",
"eac3", "ec3", "mkv", "mka", "webm",
"wav", "wave", "bwf", "rf64", "aif", "aiff", "aifc", "mp3", "mp2", "mp1", "mpa", "ogg", "oga", "opus", "m4a", "m4b", "mp4", "mov", "aac", "adts",
"ac3", "eac3", "ec3", "mkv", "mka", "webm",
];
fn detect_by_ext(ext: &str) -> Option<Container> {
+41 -14
View File
@@ -1,12 +1,13 @@
//! The native decode path: craft-media's demuxers (ISO BMFF / QuickTime, Matroska / WebM), raw
//! ADTS, AC-3 and MPEG audio streams, and WAV / AIFF PCM, feeding [`TrackDecoder`].
//! [`Native::open`] answers `None` for a stream with no native codec (MP3, FLAC, ALAC, Vorbis,
//! ...) or a container these demuxers do not read; the caller then uses symphonia.
//! [`Native::open`] answers `None` for a stream with no native codec (FLAC, Vorbis, ...) or a
//! container these demuxers do not read; the caller then uses symphonia.
//!
//! Every container is a [`Packets`] source over a [`Src`], read packet by packet, so a decode
//! streams. Timing follows the containers: MP4 edit lists (AAC priming, Opus pre-skip), Matroska
//! `CodecDelay` and per-block `DiscardPadding`, and Ogg Opus pre-skip and end trimming (RFC 7845
//! §4) are applied, so a file decodes to exactly its presentation length.
//! §4) are applied, and so are an MP3's encoder delay and padding from its LAME tag, so a file
//! decodes to exactly its presentation length.
use super::aiff::{self, AiffParse};
use super::id3v2_len;
@@ -412,7 +413,7 @@ impl<'a> Native<'a> {
let Some(next) = self.packets.next() else {
// A track that declares no frames (an empty WAV or AIFF) is empty, not broken.
let empty = self.frames_known && self.info.frames == 0 && self.errors == 0;
if !self.decoded && !empty && !(self.seeked && self.errors == 0) {
if !(self.decoded || empty || self.seeked && self.errors == 0) {
return Err(self.no_audio("stream contains no audio"));
}
return Ok(None);
@@ -716,15 +717,41 @@ fn open_adts<'a>(src: &Src<'a>, at: u64) -> Option<Result<Native<'a>>> {
Some(Ok(n))
}
/// A raw MPEG audio layer I or II stream.
/// The decoder's own delay that a LAME tag's encoder delay leaves out: decoded audio lags the
/// encoder's input by the delay plus these 528 + 1 samples.
#[cfg(feature = "mp3-decode")]
const MP3_DECODER_DELAY: u64 = 529;
/// A raw MPEG audio stream: layer I or II, and layer III with `mp3-decode`. A Xing / Info or
/// VBRI frame at the start carries no audio and is not a packet; its LAME tag's encoder delay
/// and padding trim the decoded audio to what was encoded.
fn open_mpa<'a>(src: &Src<'a>, at: u64) -> Option<Result<Native<'a>>> {
let frames = match raw_frames(src, at, |rest| {
mpa::parse_header(rest).ok().filter(|h| h.layer == 1 || h.layer == 2).map(|h| (h.frame_bytes, h.samples() as u32))
}) {
Ok(frames) => frames?,
Err(e) => return Some(Err(e)),
let layer_ok = |layer: u8| layer == 1 || layer == 2 || (cfg!(feature = "mp3-decode") && layer == 3);
#[cfg_attr(not(feature = "mp3-decode"), allow(unused_mut))]
let mut frames =
match raw_frames(src, at, |rest| mpa::parse_header(rest).ok().filter(|h| layer_ok(h.layer)).map(|h| (h.frame_bytes, h.samples() as u32))) {
Ok(frames) => frames?,
Err(e) => return Some(Err(e)),
};
#[cfg_attr(not(feature = "mp3-decode"), allow(unused_mut))]
let mut gapless: Option<(u32, u32)> = None;
#[cfg(feature = "mp3-decode")]
if let Some(&(p, n, _)) = frames.first() {
let first = match src.read(p, n as usize) {
Ok(first) => first,
Err(e) => return Some(Err(e)),
};
if let Some(tag) = crate::mp3::InfoTag::parse(&first) {
frames.remove(0);
gapless = tag.delay_padding;
}
}
let total: u64 = frames.iter().map(|&(_, _, f)| u64::from(f)).sum();
let (skip, limit) = match gapless {
#[cfg(feature = "mp3-decode")]
Some((delay, padding)) => (u64::from(delay) + MP3_DECODER_DELAY, Some(total.saturating_sub(u64::from(delay) + u64::from(padding)))),
_ => (0, None),
};
let total = frames.iter().map(|&(_, _, f)| u64::from(f)).sum();
let lookahead = match raw_lookahead(src, &frames, 1) {
Ok(lookahead) => lookahead,
Err(e) => return Some(Err(e)),
@@ -734,9 +761,9 @@ fn open_mpa<'a>(src: &Src<'a>, at: u64) -> Option<Result<Native<'a>>> {
Packets::Raw { frames, src: src.clone(), next: 0 },
&CodecParams::new(CodecId::Mp2),
&lookahead,
0,
None,
Some(total),
skip,
limit,
Some(limit.unwrap_or(total)),
)
.map(Ok)
}
+227 -58
View File
@@ -8,6 +8,8 @@ use crate::aac;
use crate::ac3;
#[cfg(feature = "alac-decode")]
use crate::alac;
#[cfg(feature = "mp3-decode")]
use crate::mp3;
#[cfg(feature = "mpa-decode")]
use crate::mpa;
#[cfg(feature = "opus-decode")]
@@ -22,8 +24,10 @@ pub const LOOKAHEAD_PACKETS: usize = 8;
enum Inner {
#[cfg(feature = "aac-decode")]
Aac {
/// The decoder, with SBR on for HE-AAC.
dec: Box<aac::Decoder>,
up: Option<aac::Upsample2x>,
/// HE-AAC: 2048 samples per access unit, at twice the core rate.
sbr: bool,
order: Option<&'static [usize]>,
/// The format ADTS packets must keep, when their headers gave the configuration.
adts_format: Option<AdtsFormat>,
@@ -43,8 +47,20 @@ enum Inner {
dec: Box<opus::Decoder>,
order: Option<&'static [usize]>,
},
/// The decoder, and whether a packet has held several frames.
#[cfg(feature = "mpa-decode")]
Mpa(Box<mpa::Decoder>),
Mpa {
dec: Box<mpa::Decoder>,
several: bool,
},
/// The Layer III decoder, the samples per channel of a frame (1152, or 576 at the lower
/// sampling frequencies), and whether a packet has held several frames.
#[cfg(feature = "mp3-decode")]
Mp3 {
dec: Box<mp3::Decoder>,
samples: usize,
several: bool,
},
Pcm {
kind: PcmKind,
channels: usize,
@@ -60,8 +76,8 @@ pub(crate) type PacketFrames = fn(&[u8], u64) -> Option<u64>;
///
/// It takes the track's [`CodecParams`] (from `isobmff::Track::codec_params`,
/// `matroska::Track::codec_params`, `ogg::Stream::codec_params`, or built by hand for another
/// container) and decodes AAC (LC; HE-AAC as its upsampled LC core), ALAC, Opus, AC-3/E-AC-3,
/// MP1/MP2 and PCM. Container timing (AAC priming, Opus pre-skip, end trimming) is the caller's:
/// container) and decodes AAC (LC, and HE-AAC with its SBR high band), ALAC, Opus, AC-3/E-AC-3,
/// MP1/MP2, MP3 and PCM. Container timing (AAC priming, Opus pre-skip, end trimming) is the caller's:
/// every decoded sample is returned.
///
/// ```no_run
@@ -116,7 +132,7 @@ impl TrackDecoder {
///
/// ALAC needs its magic cookie in `extradata`.
///
/// Codecs without a native packet decoder yet (MP3, FLAC, Vorbis) are
/// Codecs without a native packet decoder yet (FLAC, Vorbis) are
/// [`AudioError::Unsupported`]; `craft_audio::decode` decodes them through symphonia when the
/// `symphonia` feature is on.
pub fn new(params: &CodecParams, lookahead: &[&[u8]]) -> Result<TrackDecoder> {
@@ -128,6 +144,10 @@ impl TrackDecoder {
// Opus needs none.
#[cfg_attr(not(any(feature = "ac3-decode", feature = "mpa-decode")), allow(unused_variables))]
let first = lookahead.first().copied().unwrap_or_default();
// MP4 and Matroska packets may hold several MPEG audio frames: then they are not all
// one frame long.
#[cfg(feature = "mpa-decode")]
let several = lookahead.iter().any(|p| mpa_packet_frames(p).0 > 1);
let (inner, codec, sample_rate, layout, sample_format) = match params.codec {
#[cfg(feature = "aac-decode")]
CodecId::Aac | CodecId::HeAac => {
@@ -150,17 +170,18 @@ impl TrackDecoder {
params.extradata.clone()
};
let asc = asc.as_slice();
let dec = aac::Decoder::new(asc)?;
let mut dec = aac::Decoder::new(asc)?;
let out = aac::output_rate(asc, payloads.iter().copied()).unwrap_or(dec.sample_rate());
let up = (dec.sample_rate().checked_mul(2) == Some(out)).then(|| aac::Upsample2x::new(dec.channels()));
let codec = if up.is_some() { CodecId::HeAac } else { CodecId::Aac };
// Only twice the core rate is upsampled to; any other signalled rate plays the core.
let out = if up.is_some() { out } else { dec.sample_rate() };
let sbr = dec.sample_rate().checked_mul(2) == Some(out);
let codec = if sbr { CodecId::HeAac } else { CodecId::Aac };
// Only SBR at twice the core rate is decoded; any other signalled rate plays the core.
dec.set_sbr(sbr);
let out = dec.sample_rate();
// a program config element that spells out a configuration has its speakers
let cfg = aac::speaker_config(dec.config());
let layout = aac_layout(cfg, dec.channels());
let order = layout.is_ordered().then(|| aac::wav_order(cfg)).flatten();
(Inner::Aac { dec: Box::new(dec), up, order, adts_format }, codec, out, layout, SampleFormat::Compressed)
(Inner::Aac { dec: Box::new(dec), sbr, order, adts_format }, codec, out, layout, SampleFormat::Compressed)
}
#[cfg(feature = "alac-decode")]
CodecId::Alac => {
@@ -220,15 +241,32 @@ impl TrackDecoder {
}
#[cfg(feature = "mpa-decode")]
CodecId::Mp1 | CodecId::Mp2 | CodecId::Mp3 => match mpa::parse_header(first) {
#[cfg(feature = "mp3-decode")]
Ok(h) if h.layer == 3 => {
let mut dec = Box::<mp3::Decoder>::default();
dec.prime(h);
(Inner::Mp3 { dec, samples: h.samples(), several }, CodecId::Mp3, h.sample_rate, mpa_layout(&h), SampleFormat::Compressed)
}
#[cfg(not(feature = "mp3-decode"))]
Ok(h) if h.layer == 3 => return Err(unsupported(CodecId::Mp3)),
Ok(h) => {
let codec = if h.layer == 1 { CodecId::Mp1 } else { CodecId::Mp2 };
(Inner::Mpa(Box::default()), codec, h.sample_rate, mpa_layout(&h), SampleFormat::Compressed)
(Inner::Mpa { dec: Box::default(), several }, codec, h.sample_rate, mpa_layout(&h), SampleFormat::Compressed)
}
// Without a first frame, a container that names layer III is left to symphonia.
// Without a first frame, the container's rate and channels stand in until the
// first frame is decoded.
#[cfg(feature = "mp3-decode")]
Err(_) if params.codec == CodecId::Mp3 => (
Inner::Mp3 { dec: Box::default(), samples: if rate >= 32_000 { 1152 } else { 576 }, several },
CodecId::Mp3,
rate,
ChannelLayout::default_for(crate::layout::count(channels)),
SampleFormat::Compressed,
),
#[cfg(not(feature = "mp3-decode"))]
Err(_) if params.codec == CodecId::Mp3 => return Err(unsupported(CodecId::Mp3)),
Err(_) => (
Inner::Mpa(Box::default()),
Inner::Mpa { dec: Box::default(), several },
params.codec,
rate,
ChannelLayout::default_for(crate::layout::count(channels)),
@@ -281,11 +319,11 @@ impl TrackDecoder {
/// its timing.
pub fn decode(&mut self, packet: &[u8]) -> Result<AudioBuffer> {
// A packet decoded only in part says nothing of how long packets are.
#[cfg_attr(not(feature = "ac3-decode"), allow(unused_mut))]
#[cfg_attr(not(any(feature = "ac3-decode", feature = "mpa-decode")), allow(unused_mut))]
let mut partial = false;
let channels = match &mut self.inner {
#[cfg(feature = "aac-decode")]
Inner::Aac { dec, up, order, adts_format } => {
Inner::Aac { dec, order, adts_format, .. } => {
let mut out: Vec<Vec<f32>> = Vec::new();
let units = match adts_frames(packet) {
Some(frames) => adts_units(frames, *adts_format)?,
@@ -293,17 +331,11 @@ impl TrackDecoder {
};
// A failed frame leaves the decoder as it was, so the frames before it in the
// packet must too: their audio is replaced by the packet's concealment.
let before = (units.len() > 1).then(|| (dec.clone(), up.clone()));
let decoded = units.into_iter().try_for_each(|unit| {
let mut block = dec.decode(unit)?;
if let Some(up) = up.as_mut() {
block = up.process(block);
}
append(&mut out, block)
});
let before = (units.len() > 1).then(|| dec.clone());
let decoded = units.into_iter().try_for_each(|unit| append(&mut out, dec.decode(unit)?));
if let Err(e) = decoded {
if let Some(before) = before {
(*dec, *up) = before;
*dec = before;
}
return Err(e);
}
@@ -316,21 +348,27 @@ impl TrackDecoder {
reorder(floats, *order)
}
#[cfg(feature = "mpa-decode")]
Inner::Mpa(d) => {
let mut out: Vec<Vec<f32>> = Vec::new();
let mut p = 0;
while let Some(rest) = packet.get(p..).filter(|r| !r.is_empty()) {
let f = match d.decode(rest) {
Ok(f) => f,
Err(e) if out.is_empty() => return Err(e.into()),
Err(_) => break,
};
p += f.header.frame_bytes.max(1);
Inner::Mpa { dec, several } => {
let (out, first, count, cut) = mpa_frames(packet, |f| dec.decode(f))?;
*several |= count > 1;
partial = cut;
if let Some(h) = first.filter(|_| self.last_frames == 0) {
self.sample_rate = h.sample_rate;
self.layout = mpa_layout(&h);
}
out
}
#[cfg(feature = "mp3-decode")]
Inner::Mp3 { dec, samples, several } => {
let (out, first, count, cut) = mpa_frames(packet, |f| dec.decode(f))?;
*several |= count > 1;
partial = cut;
if let Some(h) = first {
*samples = h.samples();
if self.last_frames == 0 {
self.sample_rate = f.header.sample_rate;
self.layout = mpa_layout(&f.header);
self.sample_rate = h.sample_rate;
self.layout = mpa_layout(&h);
}
append(&mut out, f.channels)?;
}
out
}
@@ -399,8 +437,8 @@ impl TrackDecoder {
None
}
#[cfg(feature = "aac-decode")]
Inner::Aac { up, .. } => {
let per_unit = aac::FRAME_LEN * if up.is_some() { 2 } else { 1 };
Inner::Aac { sbr, .. } => {
let per_unit = aac::FRAME_LEN * if *sbr { 2 } else { 1 };
match adts_frames(data) {
Some(f) => Some(f.iter().map(|(h, _)| usize::from(h.raw_data_blocks)).sum::<usize>().min(MAX_ADTS_FRAMES_PER_PACKET) * per_unit),
// A packet lost whole: as long as the last one, in a stream of multi-frame
@@ -418,7 +456,19 @@ impl TrackDecoder {
#[cfg(feature = "ac3-decode")]
Inner::Ac3(..) => Some(ac3_packet_frames(data)),
#[cfg(feature = "mpa-decode")]
Inner::Mpa(_) => mpa::parse_header(data).ok().map(|h| h.samples()),
// a packet lost before any has decoded is a frame
Inner::Mpa { .. } => Some(match mpa_packet_frames(data) {
(0, _) if self.last_frames == 0 && self.codec == CodecId::Mp1 => 384,
(0, _) if self.last_frames == 0 => 1152,
(_, n) => n,
}),
// a packet lost whole is as long as the last one, a frame at the start
#[cfg(feature = "mp3-decode")]
Inner::Mp3 { samples, .. } => Some(match mpa_packet_frames(data) {
(0, _) if self.last_frames > 0 => self.last_frames,
(0, _) => *samples,
(_, n) => n,
}),
Inner::Pcm { kind, channels } => Some(data.len() / (kind.bytes() * *channels).max(1)),
};
let frames = frames.filter(|&n| n > 0).unwrap_or(self.last_frames);
@@ -428,13 +478,14 @@ impl TrackDecoder {
/// The frames every packet decodes to, for codecs whose packets all have one length: AAC
/// (1024, 2048 for HE-AAC; a packet of several ADTS frames decodes to that many times this) and
/// AC-3 / E-AC-3 (the frames of the last decoded packet, else of the first packet's primary
/// syncframes, else 1536) and MP1/MP2 (one frame per packet); `None` for Opus, PCM and ALAC
/// (whose last packet is shorter; the container's timing says), and for AC-3 / E-AC-3 whose
/// packets read so far differ in length.
/// syncframes, else 1536) and MP1/MP2/MP3 (one frame per packet; 576 for MP3 at the lower
/// sampling frequencies); `None` for Opus, PCM and ALAC (whose last packet is shorter; the
/// container's timing says), for AC-3 / E-AC-3 whose packets read so far differ in length,
/// and for MPEG audio once a packet (in the lookahead or decoded) has held several frames.
pub fn frames_per_packet(&self) -> Option<usize> {
match &self.inner {
#[cfg(feature = "aac-decode")]
Inner::Aac { up, .. } => Some(aac::FRAME_LEN * if up.is_some() { 2 } else { 1 }),
Inner::Aac { sbr, .. } => Some(aac::FRAME_LEN * if *sbr { 2 } else { 1 }),
#[cfg(feature = "alac-decode")]
Inner::Alac { .. } => None,
#[cfg(feature = "ac3-decode")]
@@ -447,7 +498,13 @@ impl TrackDecoder {
#[cfg(feature = "opus-decode")]
Inner::Opus { .. } => None,
#[cfg(feature = "mpa-decode")]
Inner::Mpa(_) => Some(if self.codec == CodecId::Mp1 { 384 } else { 1152 }),
Inner::Mpa { several: true, .. } => None,
#[cfg(feature = "mpa-decode")]
Inner::Mpa { .. } => Some(if self.codec == CodecId::Mp1 { 384 } else { 1152 }),
#[cfg(feature = "mp3-decode")]
Inner::Mp3 { several: true, .. } => None,
#[cfg(feature = "mp3-decode")]
Inner::Mp3 { samples, .. } => Some(*samples),
Inner::Pcm { .. } => None,
}
}
@@ -476,14 +533,15 @@ impl TrackDecoder {
}
/// Frames to decode before a seek target and drop, so the decoder has settled when the target
/// is reached: two AAC frames, 80 ms of Opus (RFC 7845 §4.6), one AC-3 or MPEG audio frame
/// (their filter banks overlap one frame), none for ALAC (its packets decode independently)
/// is reached: two AAC frames, 80 ms of Opus (RFC 7845 §4.6), one AC-3 or MP1/MP2 frame
/// (their filter banks overlap one frame), for MP3 the frames its bit reservoir can reach back
/// over and two more, none for ALAC (its packets decode independently)
/// and PCM. E-AC-3 syncframes of fewer than six blocks may reuse exponents from any syncframe
/// before them, so once one has been read the stream decodes from its start (`usize::MAX`).
pub fn preroll(&self) -> usize {
match &self.inner {
#[cfg(feature = "aac-decode")]
Inner::Aac { up, .. } => 2 * aac::FRAME_LEN * if up.is_some() { 2 } else { 1 },
Inner::Aac { sbr, .. } => 2 * aac::FRAME_LEN * if *sbr { 2 } else { 1 },
#[cfg(feature = "alac-decode")]
Inner::Alac { .. } => 0,
#[cfg(feature = "ac3-decode")]
@@ -493,7 +551,10 @@ impl TrackDecoder {
#[cfg(feature = "opus-decode")]
Inner::Opus { .. } => 3840,
#[cfg(feature = "mpa-decode")]
Inner::Mpa(_) => self.last_frames.max(1152),
Inner::Mpa { .. } => self.last_frames.max(1152),
// the bit reservoir reaches up to 511 bytes back: as many frames as that takes
#[cfg(feature = "mp3-decode")]
Inner::Mp3 { dec, samples, .. } => dec.preroll().unwrap_or(MP3_PREROLL_FRAMES * *samples),
Inner::Pcm { .. } => 0,
}
}
@@ -506,12 +567,7 @@ impl TrackDecoder {
self.last_frames = 0;
match &mut self.inner {
#[cfg(feature = "aac-decode")]
Inner::Aac { dec, up, .. } => {
dec.reset();
if let Some(up) = up {
up.reset();
}
}
Inner::Aac { dec, .. } => dec.reset(),
#[cfg(feature = "alac-decode")]
Inner::Alac { .. } => {}
#[cfg(feature = "ac3-decode")]
@@ -519,7 +575,9 @@ impl TrackDecoder {
#[cfg(feature = "opus-decode")]
Inner::Opus { dec, .. } => dec.reset(),
#[cfg(feature = "mpa-decode")]
Inner::Mpa(d) => d.reset(),
Inner::Mpa { dec, .. } => dec.reset(),
#[cfg(feature = "mp3-decode")]
Inner::Mp3 { dec, .. } => dec.reset(),
Inner::Pcm { .. } => {}
}
}
@@ -532,12 +590,13 @@ fn unsupported(codec: CodecId) -> AudioError {
CodecId::Ac3 | CodecId::Eac3 => Some("ac3-decode"),
CodecId::Opus => Some("opus-decode"),
CodecId::Mp1 | CodecId::Mp2 => Some("mpa-decode"),
CodecId::Mp3 => Some("mp3-decode"),
_ => None,
};
match feature {
// A codec this crate decodes, in a build without its feature.
Some(f) => AudioError::Unsupported(format!("decoding {} needs the `{f}` feature", codec.name())),
None if cfg!(feature = "symphonia") && matches!(codec, CodecId::Mp3 | CodecId::Flac | CodecId::Vorbis) => {
None if cfg!(feature = "symphonia") && matches!(codec, CodecId::Flac | CodecId::Vorbis) => {
AudioError::Unsupported(format!("no native {} packet decoder yet (craft_audio::decode reads it through symphonia)", codec.name()))
}
None => AudioError::Unsupported(format!("no native {} packet decoder yet", codec.name())),
@@ -554,6 +613,54 @@ fn reorder(mut channels: Vec<Vec<f32>>, order: Option<&[usize]>) -> Vec<Vec<f32>
}
}
/// Frames of an MP3 stream decoded before a seek target when neither a lookahead nor a decoded
/// frame has said what the stream is: the most any stream needs. The smallest frames (8 kbit/s at
/// 24 kHz, stereo, with CRC) hold 1 byte of main data, so 255 bytes of reservoir span 255 of them,
/// and two more settle the filter banks.
#[cfg(feature = "mp3-decode")]
const MP3_PREROLL_FRAMES: usize = 257;
/// The MPEG audio frames of a packet (an MP4 or Matroska packet may hold several), decoded by
/// `decode`, the first frame's header, how many frames decoded, and whether a frame after the
/// first failed, which ends the packet (then it decoded only in part).
#[cfg(feature = "mpa-decode")]
#[allow(clippy::type_complexity)]
fn mpa_frames(packet: &[u8], mut decode: impl FnMut(&[u8]) -> mpa::Result<mpa::Frame>) -> Result<(Vec<Vec<f32>>, Option<mpa::Header>, usize, bool)> {
let mut out: Vec<Vec<f32>> = Vec::new();
let mut first = None;
let mut count = 0;
let mut p = 0;
while let Some(rest) = packet.get(p..).filter(|r| !r.is_empty()) {
let f = match decode(rest) {
Ok(f) => f,
Err(e) if out.is_empty() => return Err(e.into()),
Err(_) => return Ok((out, first, count, true)),
};
p += f.header.frame_bytes.max(1);
first.get_or_insert(f.header);
count += 1;
append(&mut out, f.channels)?;
}
Ok((out, first, count, false))
}
/// The MPEG audio frames a packet holds by their headers, and the samples per channel they
/// decode to: frames are counted while their headers parse, the last one even when the packet
/// ends inside it.
#[cfg(feature = "mpa-decode")]
fn mpa_packet_frames(packet: &[u8]) -> (usize, usize) {
let (mut frames, mut samples, mut p) = (0, 0, 0);
while let Some(h) = packet.get(p..).and_then(|rest| mpa::parse_header(rest).ok()) {
frames += 1;
samples += h.samples();
if h.frame_bytes == 0 {
break;
}
p += h.frame_bytes;
}
(frames, samples)
}
/// Append `more` to `out` channel by channel. A packet whose frames differ in channel count is
/// malformed: one buffer cannot hold them.
#[cfg(any(feature = "aac-decode", feature = "ac3-decode", feature = "mpa-decode"))]
@@ -779,6 +886,68 @@ pub(crate) fn opus_layout(head: &opus::OpusHead) -> ChannelLayout {
#[cfg(test)]
mod tests {
use super::*;
/// An MP3 frame of silence: MPEG-1 Layer III, 128 kbit/s, 44.1 kHz, stereo, 417 bytes.
#[cfg(feature = "mp3-decode")]
fn mp3_frame() -> Vec<u8> {
let mut f = vec![0u8; 417];
f[..4].copy_from_slice(&[0xFF, 0xFB, 0x90, 0x00]);
f
}
/// An MP2 frame of silence: MPEG-1 Layer II, 192 kbit/s, 48 kHz, stereo, 576 bytes.
#[cfg(feature = "mpa-decode")]
fn mp2_frame() -> Vec<u8> {
let mut f = vec![0u8; 576];
f[..4].copy_from_slice(&[0xFF, 0xFD, 0xA4, 0x00]);
f
}
/// An MP4 or Matroska packet may hold several MPEG audio frames: then packets are not one
/// frame long (an MP4 track's length is not capped at a frame per packet), and a lost packet
/// is as long as the frames it held.
#[cfg(feature = "mp3-decode")]
#[test]
fn mp3_packets_of_several_frames_have_their_length() {
let one = mp3_frame();
let two = [one.clone(), one.clone()].concat();
let params = CodecParams::new(CodecId::Mp3);
let mut dec = TrackDecoder::new(&params, &[&one]).unwrap();
assert_eq!(dec.frames_per_packet(), Some(1152));
assert_eq!(dec.conceal(None).unwrap().frames(), 1152, "a packet lost before any is a frame");
assert_eq!(dec.decode(&two).unwrap().frames(), 2304);
assert_eq!(dec.frames_per_packet(), None);
assert_eq!(dec.conceal(None).unwrap().frames(), 2304, "a packet lost whole is as long as the last");
assert_eq!(dec.conceal(Some(&[two.clone(), one.clone()].concat())).unwrap().frames(), 3456);
// several frames in the lookahead say so before anything is decoded
assert_eq!(TrackDecoder::new(&params, &[&one, &two]).unwrap().frames_per_packet(), None);
// a packet decoded only in part (its second frame is cut short) keeps the length of the
// last whole packet for the next lost one
let cut = [one.clone(), one[..100].to_vec()].concat();
assert_eq!(dec.decode(&cut).unwrap().frames(), 1152);
assert_eq!(dec.conceal(None).unwrap().frames(), 2304);
}
#[cfg(feature = "mpa-decode")]
#[test]
fn mp2_packets_of_several_frames_have_their_length() {
let one = mp2_frame();
let two = [one.clone(), one.clone()].concat();
let params = CodecParams::new(CodecId::Mp2);
let mut dec = TrackDecoder::new(&params, &[&one]).unwrap();
assert_eq!(dec.frames_per_packet(), Some(1152));
assert_eq!(dec.decode(&two).unwrap().frames(), 2304);
assert_eq!(dec.frames_per_packet(), None);
assert_eq!(dec.conceal(Some(&two)).unwrap().frames(), 2304);
assert_eq!(TrackDecoder::new(&params, &[&two]).unwrap().frames_per_packet(), None);
// a packet lost before any has decoded is a frame: 1152 samples, 384 for Layer I
let stereo = |codec| CodecParams::new(codec).with_sample_rate(48_000).with_channels(2);
assert_eq!(TrackDecoder::new(&stereo(CodecId::Mp2), &[]).unwrap().conceal(None).unwrap().frames(), 1152);
assert_eq!(TrackDecoder::new(&stereo(CodecId::Mp1), &[]).unwrap().conceal(None).unwrap().frames(), 384);
let mut dec = TrackDecoder::new(&params, &[&one]).unwrap();
dec.decode(&one).unwrap();
dec.reset();
assert_eq!(dec.conceal(None).unwrap().frames(), 1152, "after a seek");
}
#[cfg(feature = "opus-decode")]
#[test]
+34 -8
View File
@@ -1,6 +1,6 @@
//! Hostile inputs must produce `Err` (or a best-effort `Ok`), never a panic.
use craft_audio::{AudioBuffer, AudioError, BitDepth, EncodeFormat, EncodeOptions, decode, encode, probe};
use craft_audio::{AudioBuffer, AudioError, BitDepth, CodecId, Container, EncodeFormat, EncodeOptions, decode, detect_container, encode, probe};
use proptest::prelude::*;
fn small(format: EncodeFormat, depth: BitDepth, channels: usize) -> Vec<u8> {
@@ -138,6 +138,32 @@ fn mp4(frames: u32, entry: &[u8], swap: impl Fn(&[u8; 4], Vec<u8>) -> Vec<u8>) -
[ftyp, moov(offset), atom(b"mdat", &pcm)].concat()
}
/// MP3 frames are read natively (as MP1 and MP2 are), so a container marker in junk before the
/// first frame does not hide the frames: the stream plays, and the bytes before it never reach
/// symphonia, whose CAF, FLAC and MP4 probes would claim the stream at the marker. A file that
/// starts with the container is read as that container whatever the hint, so its size checks
/// still refuse an oversized CAF cookie.
#[test]
fn a_container_marker_before_the_first_audio_frame_does_not_hide_the_frames() {
let mut frame = vec![0u8; 417];
frame[..4].copy_from_slice(&[0xFF, 0xFB, 0x90, 0x00]); // MPEG-1 Layer III, 128 kbps, 44.1 kHz, stereo
let mp3: Vec<u8> = (0..8).flat_map(|_| frame.clone()).collect();
let malformed = caf(&[caf_desc(b"aac ", 0, 1024, 2, 0), (b"kuki", 1i64 << 50, vec![0; 8])]);
for f in [[vec![0u8], malformed.clone(), mp3.clone()].concat(), [vec![0u8; 32], malformed.clone(), mp3.clone()].concat()] {
assert_eq!(detect_container(&f, Some("mp3")), Some(Container::MpegAudio));
let info = probe(&f, Some("mp3")).expect("MP3 frames behind a container marker");
assert_eq!((info.codec, info.sample_rate, info.channels, info.frames), (CodecId::Mp3, 44_100, 2, 8 * 1152));
assert_eq!(decode(&f, Some("mp3")).expect("decode them").1.frames(), 8 * 1152);
}
let f = [malformed, mp3.clone()].concat();
assert!(matches!(probe(&f, Some("mp3")), Err(AudioError::Malformed(m)) if m.contains("larger than the file")));
assert!(matches!(decode(&f, Some("mp3")), Err(AudioError::Malformed(m)) if m.contains("larger than the file")));
// Plain leading junk without format magic is tolerated, as before.
let f = [vec![0u8; 32], mp3].concat();
assert_eq!(detect_container(&f, Some("mp3")), Some(Container::MpegAudio));
let info = probe(&f, Some("mp3")).expect("junk before a valid MP3");
assert_eq!((info.codec, info.sample_rate, info.channels), (CodecId::Mp3, 44_100, 2));
}
/// A false MPEG sync prefix must not let malformed CAF or MP4 size fields bypass the container preflight.
#[test]
fn a_false_sync_does_not_bypass_container_checks() {
@@ -183,10 +209,10 @@ proptest! {
}
/// MP3 in MP4 is decoded by symphonia (PCM, AAC, ALAC, Opus and AC-3 are native), so it reaches
/// the checks in `read/mp4.rs`.
fn mp3_mp4(frames: u32, swap: impl Fn(&[u8; 4], Vec<u8>) -> Vec<u8>) -> Vec<u8> {
mp4(frames, &sample_entry(b".mp3", 0, &[], &[]), swap)
/// FLAC in MP4 is decoded by symphonia (PCM, AAC, ALAC, Opus, AC-3, MPEG audio are native), so
/// it reaches the checks in `read/mp4.rs`.
fn symphonia_mp4(frames: u32, swap: impl Fn(&[u8; 4], Vec<u8>) -> Vec<u8>) -> Vec<u8> {
mp4(frames, &sample_entry(b"fLaC", 0, &[], &[]), swap)
}
/// An `stts` atom of `n` one-sample runs.
@@ -199,11 +225,11 @@ fn one_sample_runs(n: u32) -> Vec<u8> {
#[test]
fn an_audio_timing_table_with_a_run_per_sample_is_bounded() {
let frames = 200_000;
let hostile = mp3_mp4(frames, |k, a| if k == b"stts" { one_sample_runs(frames) } else { a });
let hostile = symphonia_mp4(frames, |k, a| if k == b"stts" { one_sample_runs(frames) } else { a });
let r = decode(&hostile, None);
assert!(matches!(&r, Err(AudioError::Malformed(m)) if m.contains("timing table")), "{:?}", r.map(|x| x.0));
// a table of many runs over few packets is cheap to scan, so it is not refused for its size
let few = mp3_mp4(100, |k, a| if k == b"stts" { one_sample_runs(100_000) } else { a });
let few = symphonia_mp4(100, |k, a| if k == b"stts" { one_sample_runs(100_000) } else { a });
assert!(!matches!(decode(&few, None), Err(AudioError::Malformed(m)) if m.contains("timing table")));
}
@@ -212,7 +238,7 @@ fn an_audio_timing_table_with_a_run_per_sample_is_bounded() {
fn the_audio_timing_bound_follows_the_sample_entry_not_the_handler() {
let video_handler = atom(b"hdlr", &[0u32, 0, u32::from_be_bytes(*b"vide"), 0, 0, 0, 0].map(u32::to_be_bytes).concat());
let frames = 200_000;
let f = mp3_mp4(frames, |k, a| match k {
let f = symphonia_mp4(frames, |k, a| match k {
b"stts" => one_sample_runs(frames),
b"hdlr" => video_handler.clone(),
_ => a,
@@ -0,0 +1,169 @@
//! HE-AAC (SBR) decoding against ffmpeg's decoder, on streams from ffmpeg's AudioToolbox encoder
//! (oracle only; skipped without ffmpeg or without `aac_at`, which only macOS builds have).
use std::process::Command;
use craft_audio::aac::{Decoder, split_adts};
use super::common::*;
/// ffmpeg, if it has the AudioToolbox AAC encoder.
fn ffmpeg_with_aac_at() -> Option<std::path::PathBuf> {
let ff = ffmpeg()?;
let out = Command::new(&ff).args(["-hide_banner", "-encoders"]).output().ok()?;
if !String::from_utf8_lossy(&out.stdout).contains("aac_at") {
eprintln!("SKIPPED: ffmpeg has no aac_at encoder");
return None;
}
Some(ff)
}
fn input(rate: u32, channels: usize, secs: f32) -> Vec<Vec<f32>> {
let n = (rate as f32 * secs) as usize;
(0..channels)
.map(|c| {
let a = chords(rate, n, 0.004 * c as f32);
let s = speech(rate, n, 11 + c as u64);
let z = noise(n, 0.05, 3 + c as u64);
let k = clicks(rate, n);
a.iter().zip(&s).zip(&z).zip(&k).map(|(((a, s), z), k)| 0.4 * a + 0.4 * s * if c == 1 { -0.7 } else { 1.0 } + z + 0.3 * k).collect()
})
.collect()
}
/// ffmpeg's decode of a stream of `channels` channels. ffmpeg decodes mono HE-AAC as stereo (it
/// allows for parametric stereo the stream may hold), with the same signal in both channels when
/// there is none: of those, the first is taken (a downmix would scale it by -3 dB).
fn ffmpeg_decode_as(ff: &std::path::Path, file: &std::path::Path, channels: usize) -> Vec<Vec<f32>> {
let mut planar = ffmpeg_decode_raw(ff, file, channels.max(2));
planar.truncate(channels);
planar
}
fn ffmpeg_decode_raw(ff: &std::path::Path, file: &std::path::Path, channels: usize) -> Vec<Vec<f32>> {
let out = Command::new(ff).args(["-v", "error", "-i"]).arg(file).args(["-ac", &channels.to_string(), "-f", "f32le", "-"]).output().unwrap();
assert!(out.status.success() && out.stderr.is_empty(), "{}", String::from_utf8_lossy(&out.stderr));
let samples: Vec<f32> = out.stdout.as_chunks::<4>().0.iter().map(|&b| f32::from_le_bytes(b)).collect();
(0..channels).map(|c| samples.iter().skip(c).step_by(channels).copied().collect()).collect()
}
/// Our decode of an ADTS stream, SBR on.
fn decode_sbr(data: &[u8]) -> (Vec<Vec<f32>>, u32) {
let frames = split_adts(data).unwrap();
let mut dec = Decoder::from_adts(&frames[0].0).unwrap();
dec.set_sbr(true);
let mut out: Vec<Vec<f32>> = Vec::new();
for (_, au) in frames {
let pcm = dec.decode(au).unwrap();
out.resize(pcm.len(), Vec::new());
for (o, p) in out.iter_mut().zip(pcm) {
o.extend(p);
}
}
(out, dec.sample_rate())
}
/// The lag of `b` behind `a` (within ±`range`) that correlates best.
fn best_lag(a: &[f32], b: &[f32], range: i64) -> i64 {
let n = a.len().min(b.len()) as i64;
let (from, to) = (range, n - range);
(-range..=range)
.max_by(|&x, &y| {
let c = |lag: i64| (from..to).step_by(3).map(|i| a[i as usize] as f64 * b[(i + lag) as usize] as f64).sum::<f64>();
c(x).total_cmp(&c(y))
})
.unwrap()
}
/// Energy in dB of `x[from..from + 2048]` within `lo..hi` Hz (Hann-windowed DFT).
fn band_db(x: &[f32], from: usize, rate: f32, lo: f32, hi: f32) -> f64 {
let n = 2048;
let seg = &x[from..from + n];
let (b0, b1) = ((lo / rate * n as f32) as usize, (hi / rate * n as f32) as usize);
let mut e = 0f64;
for b in b0..b1.min(n / 2) {
let (mut re, mut im) = (0f64, 0f64);
for (i, &s) in seg.iter().enumerate() {
let w = 0.5 - 0.5 * (2.0 * std::f64::consts::PI * i as f64 / n as f64).cos();
let ph = 2.0 * std::f64::consts::PI * (b * i) as f64 / n as f64;
re += s as f64 * w * ph.cos();
im += s as f64 * w * ph.sin();
}
e += re * re + im * im;
}
10.0 * (e + 1e-12).log10()
}
struct Case {
name: &'static str,
rate: u32,
channels: usize,
bitrate: &'static str,
}
/// HE-AAC streams of 1 to 6 channels at 22.05 to 48 kHz decode as ffmpeg decodes them: the same
/// timing, the low band to 55 dB and the rebuilt high band's level to 0.1 dB.
#[test]
fn matches_ffmpeg_he_aac_decoder() {
let Some(ff) = ffmpeg_with_aac_at() else { return };
let cases = [
Case { name: "he_stereo_44k_48k", rate: 44_100, channels: 2, bitrate: "48k" },
Case { name: "he_mono_44k_32k", rate: 44_100, channels: 1, bitrate: "32k" },
Case { name: "he_stereo_48k_64k", rate: 48_000, channels: 2, bitrate: "64k" },
Case { name: "he_stereo_32k_32k", rate: 32_000, channels: 2, bitrate: "32k" },
Case { name: "he_stereo_44k_24k", rate: 44_100, channels: 2, bitrate: "24k" },
Case { name: "he_stereo_22k_24k", rate: 22_050, channels: 2, bitrate: "24k" },
Case { name: "he_51_48k_160k", rate: 48_000, channels: 6, bitrate: "160k" },
];
for case in &cases {
let path = fixtures().join(format!("{}.aac", case.name));
ffmpeg_encode(&ff, &input(case.rate, case.channels, 3.0), case.rate, &["-c:a", "aac_at", "-profile:a", "4", "-b:a", case.bitrate], &path);
let data = std::fs::read(&path).unwrap();
let refr = ffmpeg_decode_as(&ff, &path, case.channels);
let (ours, rate) = decode_sbr(&data);
// ffmpeg puts surround in WAV order, the decoder in AAC element order
let ours: Vec<Vec<f32>> = match (case.channels == 6).then(|| craft_audio::aac::wav_order(6)).flatten() {
Some(order) => order.iter().map(|&c| ours[c].clone()).collect(),
None => ours,
};
assert_eq!(rate, case.rate, "{}", case.name);
assert_eq!(ours.len(), case.channels);
// the same delay as ffmpeg's decoder: 962 samples
assert_eq!(best_lag(&refr[0], &ours[0], 2100), 0, "{}", case.name);
let core_nyquist = case.rate as f32 / 4.0;
for c in 0..case.channels {
let n = refr[c].len().min(ours[c].len()) - 4096;
let a: Vec<f32> = refr[c][2048..n].to_vec();
let b: Vec<f32> = ours[c][2048..n].to_vec();
let full = snr(&a, &b);
let (la, lb) = (lowpass(&a, core_nyquist * 0.8, case.rate as f32), lowpass(&b, core_nyquist * 0.8, case.rate as f32));
let low = snr(&la, &lb);
let mut diffs = Vec::new();
for from in (4096..a.len() - 4096).step_by(4096) {
for (lo, hi) in
[(core_nyquist * 1.05, core_nyquist * 1.3), (core_nyquist * 1.3, core_nyquist * 1.7), (core_nyquist * 1.7, core_nyquist * 2.0)]
{
let (ea, eb) = (band_db(&a, from, case.rate as f32, lo, hi), band_db(&b, from, case.rate as f32, lo, hi));
if ea > 0.0 {
diffs.push(eb - ea);
}
}
}
// the LFE (WAV channel 3 of 5.1) has no SBR, so no high band; every other channel must
// have one to compare
let lfe = case.channels == 6 && c == 3;
assert!(lfe || !diffs.is_empty(), "{} ch{c}: no high band to compare", case.name);
let mean = diffs.iter().sum::<f64>() / diffs.len() as f64;
let mad = diffs.iter().map(|d| d.abs()).sum::<f64>() / diffs.len() as f64;
println!(
"{} ch{c}: full SNR {full:.1} dB, low band SNR {low:.1} dB, high band level {mean:+.2} dB (mean |Δ| {mad:.2} dB over {})",
case.name,
diffs.len()
);
// The low band differs by the core decoders' rounding; the high band's noise comes
// from the same table, so whole frames match too.
assert!(full > 45.0 && low > 55.0, "{} ch{c}: SNR {full:.1} / {low:.1} dB", case.name);
assert!(lfe || mad < 0.1, "{} ch{c}: high band off by {mad:.2} dB", case.name);
}
}
}
+1
View File
@@ -3,4 +3,5 @@
mod common;
mod decoder_oracle;
mod encoder_oracle;
mod he_aac_oracle;
mod robustness;
+1
View File
@@ -12,6 +12,7 @@ mod ac3_encoder_oracle;
mod ac3_oracle;
mod alac;
mod concealment;
mod mp3_decoder_oracle;
mod mp3_encoder_oracle;
mod mpa_oracle;
mod opus;
@@ -0,0 +1,397 @@
//! The Layer III decoder against ffmpeg's float MP3 decoder as the reference, sample for sample.
//!
//! - LAME through ffmpeg (`libmp3lame`): MPEG-1, MPEG-2 and MPEG-2.5 sampling frequencies, mono,
//! stereo and joint stereo, CBR from 8 to 320 kbit/s and VBR, transients (block switching).
//! - The `lame` command, when installed: CRC-protected frames, forced mid / side and no bit
//! reservoir.
//! - This crate's own encoder.
//! - What no encoder at hand writes, made by editing LAME's frames so that they stay valid:
//! intensity stereo (the `mode_extension` bit turned on, which MPEG-1 scalefactors do not
//! depend on) and mixed blocks (`mixed_block_flag` set on short blocks whose scalefactors take
//! no bits, so the granule's `part2_3_length` still holds).
//!
//! Each stream's side information is read here as well, to prove what it covers (short blocks,
//! mid / side, CRC).
//!
//! Streams are written without a Xing / Info frame, so ffmpeg decodes every frame and trims
//! nothing: both decoders' outputs line up from the first sample.
use std::path::{Path, PathBuf};
use std::process::{Command, Stdio};
use craft_audio::mp3::{Config, Decoder, Encoder, InfoTag, StereoMode};
use craft_audio::mpa::{Mode, parse_header};
const TONES: &str = "aevalsrc=exprs=0.3*sin(2*PI*441*t)+0.1*sin(2*PI*3100*t)|0.25*sin(2*PI*660*t)+0.1*sin(2*PI*(500+4000*t)*t)";
/// Clicks over a quiet tone: an encoder switches to short blocks around each click.
const CLICKS: &str = "aevalsrc=exprs=if(lt(mod(t\\,0.2)\\,0.004)\\,0.9*sin(2*PI*2500*t)\\,0.05*sin(2*PI*330*t))|if(lt(mod(t+0.1\\,0.2)\\,0.004)\\,0.8*sin(2*PI*1800*t)\\,0.04*sin(2*PI*220*t))";
const NOISE: &str = "anoisesrc=color=pink:amplitude=0.4:seed=7";
/// Two nearly equal channels: an encoder codes them as mid / side.
const CORRELATED: &str = "aevalsrc=exprs=0.3*sin(2*PI*441*t)+0.05*sin(2*PI*5000*t)|0.28*sin(2*PI*441*t+0.1)+0.05*sin(2*PI*5000*t)";
/// A stream from ffmpeg's LAME encoder.
struct Lame {
name: &'static str,
input: &'static str,
rate: u32,
channels: usize,
/// Encoder arguments after `-c:a libmp3lame`.
enc: &'static [&'static str],
}
const LAME: &[Lame] = &[
Lame { name: "joint_44k_128k", input: TONES, rate: 44_100, channels: 2, enc: &["-b:a", "128k"] },
Lame { name: "joint_44k_correlated", input: CORRELATED, rate: 44_100, channels: 2, enc: &["-b:a", "96k"] },
Lame { name: "joint_44k_clicks", input: CLICKS, rate: 44_100, channels: 2, enc: &["-b:a", "160k"] },
Lame { name: "stereo_48k_320k", input: NOISE, rate: 48_000, channels: 2, enc: &["-b:a", "320k", "-joint_stereo", "0"] },
Lame { name: "mono_32k_48k", input: CLICKS, rate: 32_000, channels: 1, enc: &["-b:a", "48k"] },
Lame { name: "vbr_44k_noise", input: NOISE, rate: 44_100, channels: 2, enc: &["-q:a", "2"] },
Lame { name: "lsf_22k_64k", input: CLICKS, rate: 22_050, channels: 2, enc: &["-b:a", "64k"] },
Lame { name: "lsf_24k_mono_32k", input: TONES, rate: 24_000, channels: 1, enc: &["-b:a", "32k"] },
Lame { name: "lsf_16k_vbr", input: NOISE, rate: 16_000, channels: 2, enc: &["-q:a", "4"] },
Lame { name: "mpeg25_12k_24k", input: CLICKS, rate: 12_000, channels: 2, enc: &["-b:a", "24k"] },
Lame { name: "mpeg25_11k_mono", input: TONES, rate: 11_025, channels: 1, enc: &["-b:a", "16k"] },
Lame { name: "mpeg25_8k_8k", input: CLICKS, rate: 8_000, channels: 1, enc: &["-b:a", "8k"] },
// Low bit rates: many short blocks with scalefac_compress 0, for the mixed block edits.
Lame { name: "mixed_44k_32k", input: CLICKS, rate: 44_100, channels: 2, enc: &["-b:a", "32k"] },
Lame { name: "mixed_32k_mono_32k", input: CLICKS, rate: 32_000, channels: 1, enc: &["-b:a", "32k"] },
Lame { name: "mixed_lsf_22k_32k", input: CLICKS, rate: 22_050, channels: 2, enc: &["-b:a", "32k"] },
// 16 kHz has the band tables of MPEG-2.5's 11.025 and 12 kHz, whose streams give LAME few
// short blocks to edit.
Lame { name: "mixed_lsf_16k_32k", input: CLICKS, rate: 16_000, channels: 2, enc: &["-b:a", "32k"] },
];
/// The minimum SNR against ffmpeg. Both decoders compute in f32 with different IMDCT and
/// synthesis factorizations: they agree to 125-132 dB on encoded and edited streams. A wrong
/// table entry, band boundary or stereo factor costs far more: the 8 kHz short-block region
/// boundary at 36 lines instead of 72 measured -5 dB.
const MIN_SNR: f64 = 100.0;
fn generate(out: &Path, cmd: impl FnOnce(&Path) -> Command) -> Option<PathBuf> {
crate::integration::codecs::testkit::fixtures::generate(out, |tmp| cmd(tmp).stdin(Stdio::null()).status().is_ok_and(|s| s.success()))
}
/// The LAME stream for `s`, or `None` (after saying so) when this ffmpeg has no `libmp3lame`; a
/// failure with `CRAFT_MEDIA_REQUIRE_ORACLES=1`.
fn lame_stream(ff: &Path, s: &Lame) -> Option<PathBuf> {
let out = crate::integration::codecs::testkit::fixtures_dir("mp3dec").join(format!("{}.mp3", s.name));
generate(&out, |tmp| {
let mut c = Command::new(ff);
c.args(["-hide_banner", "-v", "error", "-y", "-f", "lavfi", "-i"])
.arg(format!("{}:sample_rate={}", s.input, s.rate))
.args(["-t", "2", "-ac", &s.channels.to_string(), "-c:a", "libmp3lame"])
.args(s.enc)
.args(["-write_xing", "0", "-id3v2_version", "0", "-f", "mp3"])
.arg(tmp);
c
})
.or_else(|| {
assert!(!craft_media_testkit::oracles_required(), "could not generate {} (ffmpeg without libmp3lame?)", s.name);
eprintln!("SKIPPED {}: ffmpeg could not encode it (no libmp3lame?)", s.name);
None
})
}
/// The frames of a raw stream.
fn frames(data: &[u8]) -> Vec<&[u8]> {
let mut out = Vec::new();
let mut p = 0;
while let Some(h) = data.get(p..).and_then(|b| parse_header(b).ok()) {
let Some(f) = data.get(p..p + h.frame_bytes).filter(|_| h.frame_bytes > 0) else { break };
out.push(f);
p += h.frame_bytes;
}
out
}
/// ffmpeg's float decode of `file`, interleaved.
fn ffmpeg_decode(ff: &Path, file: &Path) -> Vec<f32> {
let o = Command::new(ff).args(["-v", "error", "-c:a", "mp3float", "-f", "mp3", "-i"]).arg(file).args(["-f", "f32le", "-"]).output().unwrap();
assert!(o.status.success(), "{}: {}", file.display(), String::from_utf8_lossy(&o.stderr));
o.stdout.as_chunks::<4>().0.iter().map(|b| f32::from_le_bytes(*b)).collect()
}
/// Our decode of every frame of `data`, planar.
fn decode_all(data: &[u8], rate: u32, channels: usize) -> Vec<Vec<f32>> {
let mut dec = Decoder::new();
let mut out: Vec<Vec<f32>> = vec![Vec::new(); channels];
for f in frames(data) {
let d = dec.decode(f).unwrap_or_else(|e| panic!("frame {}: {e}", out[0].len()));
assert_eq!((d.header.sample_rate, d.channels.len()), (rate, channels));
for (o, c) in out.iter_mut().zip(d.channels) {
o.extend(c);
}
}
out
}
/// The worst channel's SNR of `ours` against ffmpeg's decode, which must be as long.
fn snr(ours: &[Vec<f32>], want: &[f32], what: &str) -> f64 {
let channels = ours.len();
assert_eq!(want.len() / channels, ours[0].len(), "{what}: sample count");
let mut worst = f64::INFINITY;
for (c, ours) in ours.iter().enumerate() {
let (mut sig, mut err) = (0f64, 0f64);
for (i, &a) in ours.iter().enumerate() {
let b = f64::from(want[i * channels + c]);
sig += b * b;
err += (f64::from(a) - b).powi(2);
}
worst = worst.min(10.0 * (sig / err.max(1e-30)).log10());
}
worst
}
fn check(ff: &Path, file: &Path, rate: u32, channels: usize, what: &str) {
let data = std::fs::read(file).unwrap();
assert!(frames(&data).len() > 10, "{what}: too few frames");
let ours = decode_all(&data, rate, channels);
let snr = snr(&ours, &ffmpeg_decode(ff, file), what);
println!("{what}: SNR vs ffmpeg {snr:.1} dB");
assert!(snr >= MIN_SNR, "{what}: SNR {snr:.1} dB < {MIN_SNR}");
}
#[test]
fn lame_streams_match_ffmpeg() {
let ff = require_ffmpeg!();
for s in LAME {
let Some(f) = lame_stream(&ff, s) else { continue };
check(&ff, &f, s.rate, s.channels, s.name);
}
}
/// The `lame` command's options ffmpeg does not reach: CRC, forced mid / side, no reservoir.
#[test]
fn lame_cli_streams_match_ffmpeg() {
let ff = require_ffmpeg!();
let Some(lame) = crate::integration::codecs::testkit::oracle::find_tool("lame") else {
eprintln!("lame not installed, skipped");
return;
};
let cases: &[(&str, &[&str], u32, usize)] = &[
("crc_48k_mono", &["-p", "-b", "96", "-m", "m"], 48_000, 1),
("nores_32k", &["--nores", "-b", "80"], 32_000, 2),
("forced_ms_44k", &["-m", "f", "-b", "96"], 44_100, 2),
];
for &(name, args, rate, channels) in cases {
let dir = crate::integration::codecs::testkit::fixtures_dir("mp3dec");
let wav = dir.join(format!("{name}.wav"));
let input = if channels == 1 { "aevalsrc=exprs=if(lt(mod(t\\,0.2)\\,0.004)\\,0.9\\,0.05)*sin(2*PI*700*t)" } else { CLICKS };
generate(&wav, |tmp| {
let mut c = Command::new(&ff);
c.args(["-hide_banner", "-v", "error", "-y", "-f", "lavfi", "-i"])
.arg(format!("{input}:sample_rate={rate}"))
.args(["-t", "2", "-c:a", "pcm_s16le", "-f", "wav"])
.arg(tmp);
c
})
.unwrap();
let out = dir.join(format!("{name}.mp3"));
let f = generate(&out, |tmp| {
let mut c = Command::new(&lame);
c.args(["--quiet", "-t", "--resample"]).arg(format!("{}", f64::from(rate) / 1000.0)).args(args).arg(&wav).arg(tmp);
c
})
.unwrap_or_else(|| panic!("lame could not encode {name}"));
if name.starts_with("crc") {
assert!(parse_header(&std::fs::read(&f).unwrap()).unwrap().crc, "{name}: no CRC");
}
check(&ff, &f, rate, channels, name);
}
}
#[test]
fn our_encoder_streams_match_ffmpeg() {
let ff = require_ffmpeg!();
let dir = crate::integration::codecs::testkit::fixtures_dir("mp3dec");
for (rate, channels, kbps, stereo) in [
(44_100, 2, 192, StereoMode::JointStereo),
(48_000, 2, 128, StereoMode::Stereo),
(32_000, 1, 64, StereoMode::Stereo),
(24_000, 2, 64, StereoMode::JointStereo),
] {
let input: Vec<Vec<f32>> = (0..channels)
.map(|c| {
(0..rate as usize).map(|i| 0.4 * (i as f32 * (0.03 + 0.02 * c as f32)).sin() * (1.0 + (i as f32 * 0.0007).sin()) / 2.0).collect()
})
.collect();
let refs: Vec<&[f32]> = input.iter().map(Vec::as_slice).collect();
let mut enc = Encoder::new(Config { stereo, ..Config::cbr(rate, channels, kbps) }).unwrap();
let mut data = enc.encode(&refs);
data.extend(enc.flush());
let path = dir.join(format!("ours_{rate}_{channels}ch_{kbps}k.mp3"));
std::fs::write(&path, &data).unwrap();
check(&ff, &path, rate, channels, &format!("our encoder {rate} Hz {channels} ch {kbps} kbit/s"));
}
}
/// The streams cover what they are meant to: short blocks (LAME switches on the clicks, at
/// every sampling frequency family), mid / side and CRC.
#[test]
fn streams_cover_short_blocks_and_mid_side() {
let ff = require_ffmpeg!();
for s in LAME.iter().filter(|s| s.input == CLICKS) {
let Some(f) = lame_stream(&ff, s) else { continue };
let data = std::fs::read(f).unwrap();
let short = frames(&data).iter().flat_map(|f| granules(f)).filter(|g| g.block_type == 2).count();
assert!(short > 5, "{}: {short} short-block granules", s.name);
}
let s = LAME.iter().find(|s| s.name == "joint_44k_correlated").unwrap();
let Some(f) = lame_stream(&ff, s) else { return };
let data = std::fs::read(f).unwrap();
let ms = frames(&data).iter().filter(|f| parse_header(f).is_ok_and(|h| h.mode == Mode::JointStereo && h.mode_extension & 2 != 0)).count();
assert!(ms > 10, "{ms} mid/side frames");
}
/// What the side information says of one granule of one channel, and where its
/// `mixed_block_flag` is (a bit offset in the frame) when it switches windows.
struct GranuleSide {
block_type: u8,
scalefac_compress: u32,
mixed_bit: Option<usize>,
}
/// Read the side information of a Layer III frame (ISO/IEC 11172-3 §2.4.1.7): each granule and
/// channel is 59 bits in MPEG-1, 63 in MPEG-2.
fn granules(frame: &[u8]) -> Vec<GranuleSide> {
let h = parse_header(frame).unwrap();
let lsf = h.sample_rate < 32_000;
let nch = h.channels();
let bit = |p: usize| (frame[p / 8] >> (7 - p % 8)) & 1;
let field = |p: usize, n: usize| (p..p + n).fold(0u32, |v, q| v << 1 | u32::from(bit(q)));
let mut p = 32 + if h.crc { 16 } else { 0 };
p += if lsf { 8 + if nch == 1 { 1 } else { 2 } } else { 9 + if nch == 1 { 5 } else { 3 } + 4 * nch };
let mut out = Vec::new();
for _ in 0..if lsf { 1 } else { 2 } {
for _ in 0..nch {
let scalefac_compress = field(p + 29, if lsf { 9 } else { 4 });
let ws = p + if lsf { 38 } else { 33 };
let (block_type, mixed_bit) = if bit(ws) == 1 { (field(ws + 1, 2) as u8, Some(ws + 3)) } else { (0, None) };
out.push(GranuleSide { block_type, scalefac_compress, mixed_bit });
p += if lsf { 63 } else { 59 };
}
}
out
}
/// A granule the mixed block test may edit: its frame, where its `mixed_block_flag` is, whether
/// it is a short block, and whether its scalefactors take no bits.
#[derive(Clone, Copy)]
struct Candidate {
frame: usize,
bit: Option<usize>,
short: bool,
editable: bool,
}
/// Write `frames` (edited copies) as a stream and compare it with ffmpeg.
fn check_edited(ff: &Path, frames: Vec<Vec<u8>>, rate: u32, channels: usize, name: &str) {
let path = crate::integration::codecs::testkit::fixtures_dir("mp3dec").join(format!("{name}.mp3"));
std::fs::write(&path, frames.concat()).unwrap();
check(ff, &path, rate, channels, name);
}
/// Intensity stereo: LAME's MPEG-1 joint stereo frames with the intensity bit of
/// `mode_extension` set. The right channel's zero bands above its last non-zero line become
/// intensity coded with the positions its scalefactors give, in long and short blocks.
#[test]
fn intensity_stereo_matches_ffmpeg() {
let ff = require_ffmpeg!();
for name in ["joint_44k_clicks", "joint_44k_correlated", "joint_44k_128k"] {
let s = LAME.iter().find(|s| s.name == name).unwrap();
let Some(f) = lame_stream(&ff, s) else { continue };
let data = std::fs::read(f).unwrap();
let mut edited = 0;
let fr: Vec<Vec<u8>> = frames(&data)
.into_iter()
.map(|f| {
let mut f = f.to_vec();
if parse_header(&f).unwrap().mode == Mode::JointStereo {
f[3] |= 0x10;
edited += 1;
}
f
})
.collect();
assert!(edited > 10, "{name}: {edited} joint stereo frames");
check_edited(&ff, fr, s.rate, s.channels, &format!("{name}_intensity"));
}
}
/// Mixed blocks: LAME's short-block granules with `mixed_block_flag` set, at MPEG-1 and MPEG-2
/// sampling frequencies (16 kHz shares its band tables with MPEG-2.5's 11.025 and 12 kHz).
///
/// - Only granules whose scalefactors take no bits (`scalefac_compress` 0) are edited: the mixed
/// layout reads the same zero bits, so the stream stays valid. Editing others would shift every
/// later field of the granule past its `part2_3_length`, and decoders differ on such damage.
/// - Not a granule whose channel's next granule is a short block that stays unmixed. ffmpeg's
/// short-block IMDCT drops the last 6 overlap values of each subband, which is exact after a
/// start or short window (whose tails are zero) but not after a mixed block's long subbands
/// (the normal window's tail is not); ISO/IEC 11172-3 adds the whole overlap, as this decoder
/// does.
/// - Not at 8 kHz, where ffmpeg does not implement mixed blocks.
#[test]
fn mixed_blocks_match_ffmpeg() {
let ff = require_ffmpeg!();
for name in ["mixed_44k_32k", "mixed_32k_mono_32k", "mixed_lsf_22k_32k", "mixed_lsf_16k_32k"] {
let s = LAME.iter().find(|s| s.name == name).unwrap();
let Some(f) = lame_stream(&ff, s) else { continue };
let data = std::fs::read(f).unwrap();
let mut fr: Vec<Vec<u8>> = frames(&data).into_iter().map(<[u8]>::to_vec).collect();
// each channel's granules in order
let mut channels: Vec<Vec<Candidate>> = vec![Vec::new(); s.channels];
for (frame, f) in fr.iter().enumerate() {
for (i, g) in granules(f).into_iter().enumerate() {
let short = g.block_type == 2;
let editable = short && g.scalefac_compress == 0;
channels[i % s.channels].push(Candidate { frame, bit: g.mixed_bit, short, editable });
}
}
let mut mixed = 0;
for ch in &channels {
// from the last granule back, so whether the next one is mixed is already decided
let mut next_pure_short = false;
for c in ch.iter().rev() {
let edit = c.editable && !next_pure_short;
if let (true, Some(p)) = (edit, c.bit) {
fr[c.frame][p / 8] |= 0x80 >> (p % 8);
mixed += 1;
}
next_pure_short = c.short && !edit;
}
}
println!("{name}: {mixed} granules made mixed");
assert!(mixed > 5, "{name}: {mixed} mixed granules");
check_edited(&ff, fr, s.rate, s.channels, &format!("{name}_mixed"));
}
}
/// A Xing / Info frame with a LAME tag gives the frame count, encoder delay and padding.
#[test]
fn info_tag_of_a_lame_stream() {
let ff = require_ffmpeg!();
let out = crate::integration::codecs::testkit::fixtures_dir("mp3dec").join("tagged_44k.mp3");
let f = generate(&out, |tmp| {
let mut c = Command::new(&ff);
c.args(["-hide_banner", "-v", "error", "-y", "-f", "lavfi", "-i", "sine=frequency=500:sample_rate=44100", "-t", "1"])
.args(["-c:a", "libmp3lame", "-b:a", "128k", "-id3v2_version", "0", "-f", "mp3"])
.arg(tmp);
c
})
.or_else(|| {
assert!(!craft_media_testkit::oracles_required(), "could not write a LAME-tagged stream (ffmpeg without libmp3lame?)");
None
});
let Some(f) = f else {
eprintln!("SKIPPED: ffmpeg could not encode a LAME-tagged stream (no libmp3lame?)");
return;
};
let data = std::fs::read(f).unwrap();
let fr = frames(&data);
let tag = InfoTag::parse(fr[0]).expect("Info frame");
assert_eq!(tag.frames, Some(fr.len() as u32 - 1));
let (delay, padding) = tag.delay_padding.expect("LAME tag");
// 1 s at 44.1 kHz: the frames hold the delay, the audio and the padding
assert_eq!(u64::from(delay) + 44_100 + u64::from(padding), (fr.len() as u64 - 1) * 1152);
assert!(InfoTag::parse(fr[1]).is_none());
}
@@ -267,6 +267,58 @@ const CASES: &[Case] = &[
frames: Some(240_000),
min_snr: 80.0,
},
Case {
name: "mp3.mp3",
surround: false,
mono: false,
rate: 48_000,
args: &["-c:a", "libmp3lame", "-b:a", "192k"],
container: Container::MpegAudio,
codec: CodecId::Mp3,
layout: ChannelLayout::STEREO,
channels: 2,
frames: Some(240_000),
min_snr: 100.0,
},
Case {
name: "mp3-lsf-mono.mp3",
surround: false,
mono: true,
rate: 24_000,
args: &["-c:a", "libmp3lame", "-b:a", "32k"],
container: Container::MpegAudio,
codec: CodecId::Mp3,
layout: ChannelLayout::MONO,
channels: 1,
frames: Some(120_000),
min_snr: 100.0,
},
Case {
name: "mp3.mkv",
surround: false,
mono: false,
rate: 48_000,
args: &["-c:a", "libmp3lame", "-b:a", "128k"],
container: Container::Matroska,
codec: CodecId::Mp3,
layout: ChannelLayout::STEREO,
channels: 2,
frames: Some(240_000),
min_snr: 100.0,
},
Case {
name: "mp3.mp4",
surround: false,
mono: false,
rate: 48_000,
args: &["-c:a", "libmp3lame", "-b:a", "128k"],
container: Container::Mp4,
codec: CodecId::Mp3,
layout: ChannelLayout::STEREO,
channels: 2,
frames: Some(240_000),
min_snr: 100.0,
},
Case {
name: "pcm-s24be.mov",
surround: false,
@@ -342,6 +394,8 @@ fn reference_lead(name: &str) -> usize {
"aac.mkv" => 1024,
"eac3-5.1.mkv" => 256,
"mp2.mkv" => 481,
// LAME's encoder delay and the decoder's, the Matroska CodecDelay
"mp3.mkv" => 1105,
_ => 0,
}
}
+14
View File
@@ -293,6 +293,15 @@ pub enum Action<P> {
/// Width in points.
width: Option<f32>,
},
/// Set the offset in points of the flyout's top from its icons' top, for the dock group holding the panel;
/// `None` aligns the flyout with its icons.
#[non_exhaustive]
MoveFlyoutTop {
/// The panel the action applies to.
panel: P,
/// Offset in points; negative is above the icons.
offset: Option<f32>,
},
/// Set the width in points of the panel's dock column while iconic; `None` clears it.
#[non_exhaustive]
ResizeIconic {
@@ -444,6 +453,11 @@ impl<P> Action<P> {
Self::ResizeFlyoutWidth { panel, width }
}
/// Builds [`Action::MoveFlyoutTop`].
pub fn move_flyout_top(panel: P, offset: Option<f32>) -> Self {
Self::MoveFlyoutTop { panel, offset }
}
/// Builds [`Action::ResizeIconic`].
pub fn resize_iconic(panel: P, width: Option<f32>) -> Self {
Self::ResizeIconic { panel, width }
+10 -2
View File
@@ -349,7 +349,7 @@ impl<P: Clone + Eq + Hash> Layout<P> {
columns: columns
.iter()
.map(|c| Column {
groups: c.groups.iter().map(|g| Group { height: None, flyout_width: None, ..g.clone() }).collect(),
groups: c.groups.iter().map(|g| Group { height: None, flyout_width: None, flyout_offset: None, ..g.clone() }).collect(),
width: None,
iconic: c.iconic,
iconic_width: None,
@@ -491,7 +491,14 @@ impl<P: Clone + Eq + Hash> Layout<P> {
&& let Some(index) = entries.iter().position(|e| &e.panel == panel)
{
let entry = entries.remove(index);
let group = Group { panels: vec![entry.panel], active: 0, minimized: !entry.open, height: entry.height, flyout_width: None };
let group = Group {
panels: vec![entry.panel],
active: 0,
minimized: !entry.open,
height: entry.height,
flyout_width: None,
flyout_offset: None,
};
let moving = whole(Moving::group(group));
return Ok(Moving { id: None, ..moving });
}
@@ -505,6 +512,7 @@ impl<P: Clone + Eq + Hash> Layout<P> {
minimized: !entry.open,
height: entry.height,
flyout_width: None,
flyout_offset: None,
})))
}
_ => Err(DockError::MissingPanel),
+17 -3
View File
@@ -37,12 +37,16 @@ pub struct Group<P> {
/// Width in points of the group's flyout, set when the user resizes it; `None` takes the column's expanded width.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub flyout_width: Option<f32>,
/// Offset in points of the flyout's top from its icons' top (negative is above), set when the user
/// resizes the flyout from its top edge; `None` aligns the flyout with its icons.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub flyout_offset: Option<f32>,
}
impl<P> Group<P> {
/// A group of `panels` with tab `active` selected, expanded and with no preferred height or flyout width.
/// A group of `panels` with tab `active` selected, expanded and with no preferred height or flyout geometry.
pub fn new(panels: Vec<P>, active: usize) -> Self {
Self { panels, active, minimized: false, height: None, flyout_width: None }
Self { panels, active, minimized: false, height: None, flyout_width: None, flyout_offset: None }
}
/// The selected panel, or `None` when `active` is out of range.
@@ -72,7 +76,7 @@ pub struct Column<P> {
impl GroupLocation {
/// A group location with the given state and column.
pub const fn new(minimized: bool, height: Option<f32>, column: Option<ColumnLocation>) -> Self {
Self { minimized, height, flyout_width: None, column }
Self { minimized, height, flyout_width: None, flyout_offset: None, column }
}
/// The location with the group's flyout `width` points wide.
@@ -81,6 +85,13 @@ impl GroupLocation {
self.flyout_width = width;
self
}
/// The location with the group's flyout top `offset` points from its icons' top.
#[must_use]
pub const fn with_flyout_offset(mut self, offset: Option<f32>) -> Self {
self.flyout_offset = offset;
self
}
}
impl ColumnLocation {
@@ -185,6 +196,9 @@ pub struct GroupLocation {
/// The width in points of the group's flyout, if the user had resized it.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub flyout_width: Option<f32>,
/// The offset in points of the group's flyout top from its icons' top, if the user had moved it.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub flyout_offset: Option<f32>,
/// The column, when the group was docked.
pub column: Option<ColumnLocation>,
}
+14 -2
View File
@@ -11,7 +11,7 @@ use super::{
edit::{node_at, split_frame, split_frame_sized},
groups::{Column, DockEdge, Group, Moving, PanelPlace, Target, Unit},
layout::Layout,
limits::{MAX_DEPTH, MAX_PANELS, valid_active, valid_height, valid_rect, valid_size, valid_width},
limits::{MAX_DEPTH, MAX_PANELS, valid_active, valid_height, valid_offset, valid_rect, valid_size, valid_width},
node::{Floating, Node, StackEntry},
policy::{DockError, Permissions},
split::SplitSize,
@@ -201,6 +201,14 @@ impl<P: Clone + Eq + Hash> Layout<P> {
self.group_mut(&place).ok_or(DockError::InvalidPlacement)?.flyout_width = width;
Ok(())
}
Action::MoveFlyoutTop { panel, offset } => {
if offset.is_some_and(|o| !valid_offset(o)) {
return Err(DockError::InvalidGeometry);
}
let place = self.place(&panel).ok_or(DockError::MissingPanel)?;
self.group_mut(&place).ok_or(DockError::InvalidPlacement)?.flyout_offset = offset;
Ok(())
}
Action::SetIconic { panel, iconic } => {
self.column_of(&panel)?.iconic = iconic;
Ok(())
@@ -369,7 +377,11 @@ pub(super) fn check_leaf<'a, P: Eq + Hash>(node: &'a Node<P>, seen: &mut HashSet
}
pub(super) fn check_group<'a, P: Eq + Hash>(group: &'a Group<P>, seen: &mut HashSet<&'a P>) -> Result<(), DockError> {
if group.panels.is_empty() || !valid_height(group.height) || group.flyout_width.is_some_and(|w| !valid_width(w)) {
if group.panels.is_empty()
|| !valid_height(group.height)
|| group.flyout_width.is_some_and(|w| !valid_width(w))
|| group.flyout_offset.is_some_and(|o| !valid_offset(o))
{
return Err(DockError::InvalidGeometry);
}
check_tabs(&group.panels, group.active, seen)
+10 -2
View File
@@ -12,7 +12,7 @@ use super::{
inner::{
check_group, check_leaf, group_location, node_location, restore_around_subtree, restore_parent_size, restore_stack_kind, stack_entry_mut,
},
limits::{MAX_DEPTH, MAX_NODES, MAX_PANELS, valid_height, valid_rect, valid_size, valid_width},
limits::{MAX_DEPTH, MAX_NODES, MAX_PANELS, valid_height, valid_offset, valid_rect, valid_size, valid_width},
node::{Floating, Node},
policy::{DockError, Permissions},
split::SplitSize,
@@ -216,7 +216,13 @@ impl<P: Clone + Eq + Hash> Layout<P> {
};
let own = groups.get(group).ok_or(DockError::MissingPanel)?;
let mut location = group_location(&own.panels, panel).ok_or(DockError::MissingPanel)?;
location.group = Some(GroupLocation { minimized: own.minimized, height: own.height, flyout_width: own.flyout_width, column });
location.group = Some(GroupLocation {
minimized: own.minimized,
height: own.height,
flyout_width: own.flyout_width,
flyout_offset: own.flyout_offset,
column,
});
if location.anchor.is_some() {
return Ok(location);
}
@@ -281,6 +287,7 @@ impl<P: Clone + Eq + Hash> Layout<P> {
if state.is_some_and(|s| {
!valid_height(s.height)
|| s.flyout_width.is_some_and(|w| !valid_width(w))
|| s.flyout_offset.is_some_and(|o| !valid_offset(o))
|| s.column.is_some_and(|c| c.width.is_some_and(|w| !valid_width(w)) || c.iconic_width.is_some_and(|w| !valid_width(w)))
}) {
return Err(DockError::InvalidGeometry);
@@ -293,6 +300,7 @@ impl<P: Clone + Eq + Hash> Layout<P> {
minimized: state.is_some_and(|s| s.minimized),
height: state.and_then(|s| s.height),
flyout_width: state.and_then(|s| s.flyout_width),
flyout_offset: state.and_then(|s| s.flyout_offset),
};
let column = state.and_then(|s| s.column);
Moving {
+5
View File
@@ -20,6 +20,11 @@ pub(super) fn valid_width(width: f32) -> bool {
width.is_finite() && width > 0.0 && width <= MAX_EXTENT
}
/// A flyout's top offset from its icons: finite and within the largest extent either way.
pub(super) fn valid_offset(offset: f32) -> bool {
offset.is_finite() && offset.abs() <= MAX_EXTENT
}
pub(super) fn valid_size(size: SplitSize) -> bool {
match size {
SplitSize::Ratio(r) => r.is_finite() && (0.0..=1.0).contains(&r),
+31
View File
@@ -107,6 +107,37 @@ fn a_flyout_width_is_validated_restored_and_saved_only_when_set() {
assert_eq!(layout, original);
}
/// A flyout's top offset is validated, survives a close and restore (a restore refuses an invalid one), and
/// clearing it gives back the untouched layout.
#[test]
fn flyout_offset_rejects_invalid_geometry_without_mutating_the_layout() {
let mut iconic = Column::new(vec![g(&[1], 0)]);
iconic.iconic = true;
let mut layout = with_column(iconic);
let original = layout.clone();
assert!(!serde_json::to_string(&original).unwrap().contains("flyout_offset"), "an untouched offset is not saved");
for offset in [f32::NAN, f32::INFINITY, f32::NEG_INFINITY, 2_000_000.0, -2_000_000.0] {
assert_eq!(layout.apply(Action::move_flyout_top(1, Some(offset))), Err(DockError::InvalidGeometry), "{offset}");
assert_eq!(layout, original);
}
layout.apply(Action::move_flyout_top(1, Some(-120.0))).unwrap();
let offset = |layout: &Layout<u32>| match layout.root.as_ref() {
Some(Node::Dock { columns, .. }) => columns[0].groups[0].flyout_offset,
root => panic!("{root:?}"),
};
let location = layout.location(&1).unwrap();
layout.apply(Action::close(1)).unwrap();
layout.restore(1, &location).unwrap();
assert_eq!(offset(&layout), Some(-120.0), "a restore gives the group its flyout offset back");
let mut bad = location.clone();
bad.group.as_mut().unwrap().flyout_offset = Some(f32::NAN);
layout.apply(Action::close(1)).unwrap();
assert_eq!(layout.restore(1, &bad), Err(DockError::InvalidGeometry));
layout.restore(1, &location).unwrap();
layout.apply(Action::move_flyout_top(1, None)).unwrap();
assert_eq!(layout, original);
}
/// The layout of `restore_returns_each_panel_to_the_place_it_was_in` with `skip` absent.
fn without(skip: Option<u32>) -> Layout<u32> {
let group = |panels: &[u32], active: usize| {
+4 -4
View File
@@ -116,9 +116,9 @@ impl CmykModel {
// Overprints with black: multiplicative in reflectance above a first-surface floor.
let floor = 0.006;
let mut prim = [[0.0; 3]; 16];
for m in 0..16 {
for (m, slot) in prim.iter_mut().enumerate() {
let p = base[m & 7];
prim[m] = if m & 8 == 0 {
*slot = if m & 8 == 0 {
p
} else {
std::array::from_fn(|i| {
@@ -138,7 +138,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() {
let mut w = 1.0;
for (i, ai) in a.iter().enumerate() {
w *= if m & (1 << i) != 0 { *ai } else { 1.0 - ai };
@@ -146,7 +146,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;
}
}
+2 -1
View File
@@ -74,7 +74,8 @@ impl Value {
}
/// The `crs:` settings of a packet, by name without the prefix (`Exposure2012`). Where a name
/// occurs more than once (in several `rdf:Description`s), the last one is kept.
/// occurs more than once (in several `rdf:Description`s), the first text-bearing value is kept,
/// as [`craft_metadata::parse_xmp`] reads every packet: a blank repeat must not hide it.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct Settings {
pub entries: BTreeMap<String, Value>,
+6 -2
View File
@@ -78,10 +78,14 @@ fn structures_other_prefixes_and_other_namespaces() {
assert_eq!(masks.items().first().and_then(|m| m.field("crs:What")).and_then(XmpValue::text), Some("Correction"));
assert_eq!(s.get("Empty"), Some(&Value::Text(String::new())));
assert_eq!(s.get("format"), None);
// The last value of a repeated name wins.
// A repeated name keeps its first value, as `craft_metadata` reads every packet: an empty
// repeat must not hide what an earlier description said.
let second = format!("/><rdf:Description xmlns:crs=\"{CRS_NS}\" crs:Texture=\"2\"/></rdf:RDF>");
let twice = with("crs:Texture=\"1\"").replace("/></rdf:RDF>", &second);
assert_eq!(Settings::parse(twice.as_bytes()).unwrap().text("Texture"), Some("2"));
assert_eq!(Settings::parse(twice.as_bytes()).unwrap().text("Texture"), Some("1"));
let blank = format!("/><rdf:Description xmlns:crs=\"{CRS_NS}\" crs:Texture=\"\"/></rdf:RDF>");
let hiding = with("crs:Texture=\"1\"").replace("/></rdf:RDF>", &blank);
assert_eq!(Settings::parse(hiding.as_bytes()).unwrap().text("Texture"), Some("1"), "a blank repeat does not win");
}
#[test]
+18
View File
@@ -0,0 +1,18 @@
[package]
name = "craft-designcraft-format"
description = "Versioned DesignCraft document JSON codec and legacy migrations over craft-document-bundle"
version.workspace = true
edition.workspace = true
license.workspace = true
rust-version.workspace = true
repository.workspace = true
[lints]
workspace = true
[dependencies]
craft-document-bundle = { workspace = true }
craft-eps = { workspace = true }
serde = { workspace = true }
serde_json = { workspace = true }
thiserror = { workspace = true }
+251
View File
@@ -0,0 +1,251 @@
//! Versioned JSON and bundle codec for DesignCraft's native document format.
//!
//! The application owns its document model. This crate owns the on-disk schema version,
//! serialization, legacy JSON upgrades, version inference and the shared ZIP envelope.
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
#![forbid(unsafe_code)]
use std::collections::{HashMap, HashSet};
use std::io::{Read, Seek};
pub use craft_document_bundle::Asset;
use craft_document_bundle::Spec;
use serde::{Serialize, de::DeserializeOwned};
use serde_json::Value;
pub const MIME: &str = "application/vnd.designcraft+zip";
pub const VERSION: u32 = 4;
pub const EXTENSION: &str = "designcraft";
pub const PREVIEW: &str = "preview.png";
pub const MAX_PREVIEW_BYTES: u64 = 4 << 20;
const BUNDLE: Spec<'static> = Spec {
mimetype_entry: "mimetype",
mimetype: MIME,
metadata_entry: "meta.json",
document_entry: "document.json",
preview_entry: PREVIEW,
assets_directory: "assets",
format_name: "designcraft",
legacy_assets_field: Some("assetData"),
};
#[derive(Debug, thiserror::Error)]
pub enum Error {
#[error("not a DesignCraft document: {0}")]
NotOurs(String),
#[error("document is from a newer DesignCraft (format {0}); please update")]
TooNew(u64),
#[error("{0}")]
Io(String),
#[error("document cannot be saved: {0}")]
Unsaveable(String),
}
impl From<craft_document_bundle::Error> for Error {
fn from(error: craft_document_bundle::Error) -> Self {
match error {
craft_document_bundle::Error::TooNew(version) => Error::TooNew(version),
craft_document_bundle::Error::NotBundle(message) => Error::NotOurs(message),
craft_document_bundle::Error::Read(message) | craft_document_bundle::Error::Write(message) => Error::Io(message),
}
}
}
/// A decoded native document and the separately stored embedded assets.
#[derive(Clone, Debug, PartialEq)]
pub struct Loaded<T> {
pub document: T,
pub assets: Vec<(String, Vec<u8>)>,
}
/// The reader capability required by `document`, inferred from its neutral JSON schema and
/// embedded assets. Traversal beyond 64 levels conservatively requires version 4.
pub fn required_version(document: &Value, assets: &[Asset<'_>]) -> u32 {
if has_version_four_feature(document) {
return 4;
}
if assets.iter().any(|asset| craft_eps::is_eps(asset.data)) { 3 } else { 2 }
}
/// Serialize a document and its external assets as a `.designcraft` ZIP bundle.
pub fn save<T: Serialize>(document: &T, generator: &str, preview: Option<&[u8]>, assets: &[Asset<'_>]) -> Result<Vec<u8>, Error> {
let value = serde_json::to_value(document).map_err(|error| Error::Io(error.to_string()))?;
let version = required_version(&value, assets);
let json = serde_json::to_vec_pretty(&value).map_err(|error| Error::Io(error.to_string()))?;
craft_document_bundle::write(&json, version, generator, preview, assets, BUNDLE).map_err(Into::into)
}
/// Read a `.designcraft` ZIP or legacy single-file JSON, applying all versioned schema migrations
/// before deserializing the caller's model.
pub fn load<T: DeserializeOwned>(bytes: &[u8]) -> Result<Loaded<T>, Error> {
let mut package = craft_document_bundle::read(bytes, VERSION, BUNDLE)?;
upgrade_legacy_json(&mut package.document, package.version);
let document = serde_json::from_value(package.document).map_err(|error| Error::NotOurs(error.to_string()))?;
Ok(Loaded { document, assets: package.assets })
}
/// Whether `bytes` are a native DesignCraft ZIP package.
pub fn is_designcraft(bytes: &[u8]) -> bool {
craft_document_bundle::has_document(bytes, BUNDLE)
}
/// Whether `prefix` begins with this format's stored mimetype entry.
pub fn starts_designcraft(prefix: &[u8]) -> bool {
craft_document_bundle::starts_with_mimetype(prefix, BUNDLE)
}
/// Read the first-page PNG preview from a ZIP package, with a fixed 4 MiB cap.
pub fn read_preview<R: Read + Seek>(reader: R) -> Option<Vec<u8>> {
craft_document_bundle::read_preview_from(reader, PREVIEW)
}
fn has_version_four_feature(document: &Value) -> bool {
let mut stack = vec![(document, 0usize)];
let mut visited = 0usize;
while let Some((value, depth)) = stack.pop() {
if depth > 64 || visited >= 1_000_000 {
return true;
}
visited += 1;
match value {
Value::Object(object) => {
if object.get("layerOptions").is_some_and(|options| !options.is_null())
|| (object.get("pdfLayerOverride").and_then(Value::as_bool) == Some(true)
&& object.get("pdfHiddenLayers").and_then(Value::as_array).is_none_or(Vec::is_empty))
{
return true;
}
stack.extend(object.values().map(|child| (child, depth + 1)));
}
Value::Array(children) => stack.extend(children.iter().map(|child| (child, depth + 1))),
_ => {}
}
}
false
}
fn upgrade_legacy_json(document: &mut Value, from: u64) {
let mut vertical = HashSet::new();
vertical_frames(document, &mut vertical, 0);
if let Some(stories) = document.get_mut("stories").and_then(Value::as_object_mut) {
for story in stories.values_mut() {
let first = story.get("frames").and_then(|frames| frames.get(0)).and_then(Value::as_u64);
if let (Some(frame), Some(story)) = (first, story.as_object_mut())
&& vertical.contains(&frame)
&& !story.contains_key("vertical")
{
story.insert("vertical".into(), Value::Bool(true));
}
}
}
if from < 2 {
pin_paragraph_defaults(document);
}
}
fn vertical_frames(value: &Value, out: &mut HashSet<u64>, depth: usize) {
if depth > 256 {
return;
}
match value {
Value::Object(object) => {
if let (Some(id), Some(content)) = (object.get("id").and_then(Value::as_u64), object.get("content"))
&& content.get("type").and_then(Value::as_str) == Some("text")
&& content.get("options").and_then(|options| options.get("vertical")).and_then(Value::as_bool) == Some(true)
{
out.insert(id);
}
for child in object.values() {
vertical_frames(child, out, depth + 1);
}
}
Value::Array(children) => {
for child in children {
vertical_frames(child, out, depth + 1);
}
}
_ => {}
}
}
fn pin_paragraph_defaults(document: &mut Value) {
const MAX_STYLE_DEPTH: usize = 64;
let styles = document.pointer("/styles/paragraph").and_then(Value::as_array).cloned().unwrap_or_default();
let mut by_name: HashMap<String, (Option<String>, bool, bool)> = HashMap::new();
for style in &styles {
let Some(name) = style.get("name").and_then(Value::as_str) else { continue };
let based_on = style.get("basedOn").and_then(Value::as_str).map(str::to_string);
let attrs = style.get("para");
let missing_keep = attrs.and_then(|attrs| attrs.get("keepAllLines")).is_none();
let missing_drop_cap = attrs.and_then(|attrs| attrs.get("dropCapAlignLeft")).is_none();
by_name.entry(name.to_string()).or_insert((based_on, missing_keep, missing_drop_cap));
}
let mut roots = HashSet::new();
for name in by_name.keys() {
let mut chain = Vec::new();
let mut seen = HashSet::new();
let mut current = Some(name.as_str());
while let Some(style_name) = current {
let Some((based_on, missing_keep, missing_drop_cap)) = by_name.get(style_name) else { break };
if chain.len() >= MAX_STYLE_DEPTH || !seen.insert(style_name.to_string()) {
break;
}
chain.push((style_name, *missing_keep, *missing_drop_cap));
current = based_on.as_deref();
}
if !chain.is_empty()
&& chain.iter().all(|(_, keep, drop_cap)| *keep && *drop_cap)
&& let Some((root, _, _)) = chain.last()
{
roots.insert((*root).to_string());
}
}
if let Some(styles) = document.pointer_mut("/styles/paragraph").and_then(Value::as_array_mut) {
for style in styles {
if let Some(style) = style.as_object_mut()
&& style.get("name").and_then(Value::as_str).is_some_and(|name| roots.contains(name))
{
let attrs = style.entry("para").or_insert_with(|| Value::Object(Default::default()));
if let Some(attrs) = attrs.as_object_mut() {
attrs.entry("keepAllLines").or_insert(Value::Bool(true));
attrs.entry("dropCapAlignLeft").or_insert(Value::Bool(false));
}
}
}
}
let known_styles: HashSet<String> = by_name.into_keys().collect();
pin_unstyled_paragraphs(document, &known_styles, 0);
}
fn pin_unstyled_paragraphs(value: &mut Value, known_styles: &HashSet<String>, depth: usize) {
if depth > 256 {
return;
}
match value {
Value::Object(object) => {
if let Some(style) = object.get("style").and_then(Value::as_str)
&& !known_styles.contains(style)
{
let attrs = object.entry("para").or_insert_with(|| Value::Object(Default::default()));
if let Some(attrs) = attrs.as_object_mut() {
attrs.entry("keepAllLines").or_insert(Value::Bool(true));
attrs.entry("dropCapAlignLeft").or_insert(Value::Bool(false));
}
}
for child in object.values_mut() {
pin_unstyled_paragraphs(child, known_styles, depth + 1);
}
}
Value::Array(children) => {
for child in children {
pin_unstyled_paragraphs(child, known_styles, depth + 1);
}
}
_ => {}
}
}
#[cfg(test)]
mod tests;
+72
View File
@@ -0,0 +1,72 @@
use super::*;
use serde_json::json;
#[test]
fn native_bundle_roundtrips_document_assets_and_preview() -> Result<(), Box<dyn std::error::Error>> {
let document = json!({"title":"A page", "assets":{"7":{"mime":"image/png"}}});
let image = [1u8, 2, 3, 4];
let assets = [Asset { id: "7", mime: "image/png", data: &image }];
let preview = b"preview png";
let bytes = save(&document, "DesignCraft test", Some(preview), &assets)?;
assert!(is_designcraft(&bytes));
assert!(starts_designcraft(&bytes[..bytes.len().min(80)]));
let loaded = load::<Value>(&bytes)?;
assert_eq!(loaded.document, document);
assert_eq!(loaded.assets, [("7".to_owned(), image.to_vec())]);
assert_eq!(read_preview(std::io::Cursor::new(&bytes)).as_deref(), Some(&preview[..]));
Ok(())
}
#[test]
fn preview_reader_rejects_an_entry_over_its_declared_read_budget() -> Result<(), Box<dyn std::error::Error>> {
let oversized = vec![0u8; usize::try_from(MAX_PREVIEW_BYTES + 1)?];
let bytes = save(&json!({}), "DesignCraft test", Some(&oversized), &[])?;
assert_eq!(read_preview(std::io::Cursor::new(bytes)), None);
Ok(())
}
#[test]
fn required_version_preserves_the_reader_capability_contract() {
assert_eq!(required_version(&json!({"title":"plain"}), &[]), 2);
assert_eq!(required_version(&json!({}), &[Asset { id: "1", mime: "application/postscript", data: b"%!PS-Adobe-3.0 EPSF-3.0" }]), 3);
assert_eq!(required_version(&json!({"layerOptions":{}}), &[]), 4);
assert_eq!(required_version(&json!({"pdfLayerOverride":true,"pdfHiddenLayers":[]}), &[]), 4);
assert_eq!(required_version(&json!({"pdfLayerOverride":true,"pdfHiddenLayers":["guide"]}), &[]), 2);
let mut nested = json!(null);
for _ in 0..65 {
nested = json!([nested]);
}
assert_eq!(required_version(&nested, &[]), 4);
}
#[test]
fn legacy_json_extracts_assets_and_applies_v1_migrations() -> Result<(), Box<dyn std::error::Error>> {
let legacy = json!({
"assetData":{"7":"AQID"},
"frames":[{"id":8,"content":{"type":"text","options":{"vertical":true}}}],
"stories":{"vertical":{"frames":[8]},"explicit":{"frames":[8],"vertical":false}},
"styles":{"paragraph":[{"name":"Base"},{"name":"Child","basedOn":"Base","para":{"keepAllLines":false}}]},
"paragraphs":[{"style":"Missing"}]
});
let loaded = load::<Value>(&serde_json::to_vec(&legacy)?)?;
assert_eq!(loaded.assets, [("7".to_owned(), vec![1, 2, 3])]);
assert_eq!(loaded.document.get("assetData"), None);
assert_eq!(loaded.document["stories"]["vertical"]["vertical"], true);
assert_eq!(loaded.document["stories"]["explicit"]["vertical"], false);
assert_eq!(loaded.document["styles"]["paragraph"][0]["para"]["keepAllLines"], true);
assert_eq!(loaded.document["styles"]["paragraph"][0]["para"]["dropCapAlignLeft"], false);
assert_eq!(loaded.document["styles"]["paragraph"][1]["para"]["keepAllLines"], false);
assert_eq!(loaded.document["paragraphs"][0]["para"]["keepAllLines"], true);
Ok(())
}
#[test]
fn newer_metadata_precedes_malformed_document_json() -> Result<(), Box<dyn std::error::Error>> {
let bytes = craft_document_bundle::write(b"{", VERSION + 1, "future", None, &[], BUNDLE)?;
assert!(matches!(load::<Value>(&bytes), Err(Error::TooNew(version)) if version == u64::from(VERSION + 1)));
assert!(matches!(load::<Value>(b"not a package"), Err(Error::NotOurs(_))));
Ok(())
}
+17
View File
@@ -0,0 +1,17 @@
[package]
name = "craft-document-bundle"
description = "A reusable JSON document bundle envelope over ZIP: metadata, previews, asset entries and legacy inline asset extraction."
version.workspace = true
edition.workspace = true
license.workspace = true
rust-version.workspace = true
repository.workspace = true
[lints]
workspace = true
[dependencies]
craft-zip = { workspace = true }
serde_json = { workspace = true }
thiserror = { workspace = true }
zip = { version = "9", default-features = false, features = ["deflate-flate2"] }
+317
View File
@@ -0,0 +1,317 @@
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
//! A JSON document bundle envelope over ZIP.
//!
//! Applications keep their document models. This crate owns the reusable container mechanics:
//! ordered mimetype, metadata, JSON model, previews, embedded asset paths, compression policy,
//! bounded reads and extraction of legacy base64 asset maps. Entry names and MIME type are
//! supplied by the format using the bundle.
use std::io::{Read, Seek};
use craft_zip::{Archive, Compression, Limits, Writer};
use serde_json::Value;
const MAX_ENTRIES: u64 = 100_000;
const JSON_LIMIT: u64 = 256 << 20;
const ASSET_LIMIT: u64 = 1 << 30;
const EXPANSION_LIMIT: u64 = 4 << 30;
/// Per-entry and total-expansion limits for an untrusted document bundle.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct ReadLimits {
/// Maximum expanded size of metadata and document JSON.
pub json_bytes: u64,
/// Maximum expanded size of one compressed asset. Stored assets are bounded by archive size.
pub compressed_asset_bytes: u64,
/// Maximum expansion beyond the bytes in the source archive.
pub expansion_bytes: u64,
}
impl Default for ReadLimits {
fn default() -> Self {
Self { json_bytes: JSON_LIMIT, compressed_asset_bytes: ASSET_LIMIT, expansion_bytes: EXPANSION_LIMIT }
}
}
/// Names and identity used by one JSON document bundle format.
#[derive(Clone, Copy, Debug)]
pub struct Spec<'a> {
/// Stored first entry and its payload.
pub mimetype_entry: &'a str,
pub mimetype: &'a str,
/// Metadata and document JSON member names.
pub metadata_entry: &'a str,
pub document_entry: &'a str,
/// Optional preview entry name.
pub preview_entry: &'a str,
/// Directory prefix for embedded assets, without a trailing slash.
pub assets_directory: &'a str,
/// Metadata value written in the `format` field.
pub format_name: &'a str,
/// Old single-file JSON field containing base64 assets keyed by decimal id.
pub legacy_assets_field: Option<&'a str>,
}
/// An embedded asset passed to [`write`].
#[derive(Clone, Copy, Debug)]
pub struct Asset<'a> {
/// Decimal asset id used in the archive entry path.
pub id: &'a str,
/// MIME type used to select the extension and compression policy.
pub mime: &'a str,
/// File bytes retained byte-for-byte.
pub data: &'a [u8],
}
/// A document and embedded payloads returned by [`read`].
#[derive(Clone, Debug, PartialEq)]
pub struct Package {
/// Parsed model JSON, after extracting legacy inline assets.
pub document: Value,
/// Format version declared by metadata, or 1 when absent.
pub version: u64,
/// Embedded asset bytes keyed by decimal asset id.
pub assets: Vec<(String, Vec<u8>)>,
}
/// Why a document bundle could not be read or written.
#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
pub enum Error {
/// The bytes are not a bundle or legacy JSON document.
#[error("not a document bundle: {0}")]
NotBundle(String),
/// The bundle requires a newer reader.
#[error("document format {0} is newer than this reader supports")]
TooNew(u64),
/// A member could not be written.
#[error("could not write document bundle: {0}")]
Write(String),
/// A member exceeded a read limit or could not be read.
#[error("could not read document bundle: {0}")]
Read(String),
}
fn extension(mime: &str) -> &'static str {
match mime {
"image/png" => "png",
"image/jpeg" => "jpg",
"image/gif" => "gif",
"image/webp" => "webp",
"image/tiff" => "tif",
"application/pdf" => "pdf",
"application/postscript" => "eps",
"image/svg+xml" => "svg",
_ => "bin",
}
}
/// Whether `bytes` are a ZIP bundle that contains the configured document member.
pub fn has_document(bytes: &[u8], spec: Spec<'_>) -> bool {
let Ok(archive) = Archive::open(bytes, Limits { max_entries: MAX_ENTRIES, max_total_bytes: 0 }) else { return false };
archive.contains(spec.document_entry)
}
/// Whether `prefix` starts with the configured stored mimetype entry.
pub fn starts_with_mimetype(prefix: &[u8], spec: Spec<'_>) -> bool {
craft_zip::stored_mimetype(prefix).is_some_and(|mime| mime == spec.mimetype.as_bytes())
}
/// Write a ZIP document bundle containing the serialized document, metadata, preview and assets.
pub fn write(document: &[u8], version: u32, generator: &str, preview: Option<&[u8]>, assets: &[Asset<'_>], spec: Spec<'_>) -> Result<Vec<u8>, Error> {
let mut writer = Writer::new();
writer.add(spec.mimetype_entry, spec.mimetype.as_bytes(), Compression::Stored).map_err(|e| Error::Write(e.to_string()))?;
let metadata = serde_json::json!({"format":spec.format_name, "version":version, "generator":generator});
let metadata = serde_json::to_vec(&metadata).map_err(|e| Error::Write(e.to_string()))?;
writer.add(spec.metadata_entry, &metadata, Compression::Deflated).map_err(|e| Error::Write(e.to_string()))?;
if let Some(preview) = preview {
writer.add(spec.preview_entry, preview, Compression::Stored).map_err(|e| Error::Write(e.to_string()))?;
}
writer.add(spec.document_entry, document, Compression::Deflated).map_err(|e| Error::Write(e.to_string()))?;
for asset in assets.iter().filter(|asset| !asset.data.is_empty()) {
let path = format!("{}/{}.{}", spec.assets_directory, asset.id, extension(asset.mime));
let compression =
if matches!(asset.mime, "image/png" | "image/jpeg" | "image/gif" | "image/webp") { Compression::Stored } else { Compression::Deflated };
writer.add(&path, asset.data, compression).map_err(|e| Error::Write(e.to_string()))?;
}
writer.finish().map_err(|e| Error::Write(e.to_string()))
}
/// Read a ZIP bundle or legacy JSON document within bounded member sizes.
///
/// Members under the configured assets directory whose id does not occur in the document's
/// `assets` object are never decompressed. Unreferenced data cannot consume the caller's memory.
pub fn read(bytes: &[u8], supported_version: u32, spec: Spec<'_>) -> Result<Package, Error> {
read_with_limits(bytes, supported_version, spec, ReadLimits::default())
}
/// Like [`read`], with caller-selected bounded-read limits.
pub fn read_with_limits(bytes: &[u8], supported_version: u32, spec: Spec<'_>, limits: ReadLimits) -> Result<Package, Error> {
if !bytes.starts_with(b"PK") {
return read_legacy(bytes, spec);
}
let source_size = u64::try_from(bytes.len()).unwrap_or(u64::MAX);
let mut archive = Archive::open(bytes, Limits { max_entries: MAX_ENTRIES, max_total_bytes: source_size.saturating_add(limits.expansion_bytes) })
.map_err(|e| Error::NotBundle(e.to_string()))?;
if archive.has_duplicate_names() {
return Err(Error::NotBundle("the archive has duplicate member names".into()));
}
let version = archive
.read(spec.metadata_entry, limits.json_bytes)
.map_err(|e| Error::Read(e.to_string()))?
.and_then(|metadata| serde_json::from_slice::<Value>(&metadata).ok())
.and_then(|metadata| metadata.get("version").and_then(Value::as_u64))
.unwrap_or(1);
if version > u64::from(supported_version) {
return Err(Error::TooNew(version));
}
let document_bytes = archive
.read(spec.document_entry, limits.json_bytes)
.map_err(|e| Error::Read(e.to_string()))?
.ok_or_else(|| Error::NotBundle(format!("missing {}", spec.document_entry)))?;
let document: Value = serde_json::from_slice(&document_bytes).map_err(|e| Error::NotBundle(e.to_string()))?;
let wanted: std::collections::HashSet<String> =
document.get("assets").and_then(Value::as_object).into_iter().flat_map(|assets| assets.keys().cloned()).collect();
let prefix = format!("{}/", spec.assets_directory);
let mut embedded = Vec::new();
for path in archive.names().map(|name| name.into_owned()).collect::<Vec<_>>() {
let Some(member) = path.strip_prefix(&prefix) else { continue };
let Some(id) = member.split('.').next() else { continue };
if !wanted.contains(id) || id.parse::<u64>().is_err() {
continue;
}
let stored = archive.is_stored(&path).unwrap_or(false);
let limit = if stored { source_size } else { limits.compressed_asset_bytes };
let data = archive.read(&path, limit).map_err(|e| Error::Read(e.to_string()))?;
if let Some(data) = data {
embedded.push((id.to_owned(), data));
}
}
Ok(Package { document, version, assets: embedded })
}
/// Read a preview with a fixed maximum size without decompressing the full bundle.
pub fn read_preview(bytes: &[u8], preview_entry: &str) -> Option<Vec<u8>> {
const PREVIEW_LIMIT: u64 = 4 << 20;
let mut archive = Archive::open(bytes, Limits { max_entries: MAX_ENTRIES, max_total_bytes: PREVIEW_LIMIT }).ok()?;
archive.read(preview_entry, PREVIEW_LIMIT).ok().flatten()
}
/// Read a bounded preview from a seekable file without loading the full bundle into memory.
pub fn read_preview_from<R: Read + Seek>(reader: R, preview_entry: &str) -> Option<Vec<u8>> {
const PREVIEW_LIMIT: u64 = 4 << 20;
let mut zip = zip::ZipArchive::new(reader).ok()?;
let entry = zip.by_name(preview_entry).ok()?;
if entry.size() > PREVIEW_LIMIT {
return None;
}
let mut preview = Vec::new();
entry.take(PREVIEW_LIMIT.saturating_add(1)).read_to_end(&mut preview).ok()?;
(u64::try_from(preview.len()).ok()? <= PREVIEW_LIMIT).then_some(preview)
}
fn read_legacy(bytes: &[u8], spec: Spec<'_>) -> Result<Package, Error> {
let mut document: Value = serde_json::from_slice(bytes).map_err(|e| Error::NotBundle(e.to_string()))?;
let mut assets = Vec::new();
let mut total = 0u64;
if let Some(field) = spec.legacy_assets_field {
if let Some(inline) = document.get(field).and_then(Value::as_object) {
for (id, value) in inline {
if id.parse::<u64>().is_ok()
&& let Some(encoded) = value.as_str()
{
let decoded_size = u64::try_from(encoded.len()).unwrap_or(u64::MAX).saturating_mul(3) / 4;
if decoded_size > ASSET_LIMIT {
return Err(Error::Read(format!("legacy asset {id} exceeds the {ASSET_LIMIT}-byte limit")));
}
total = total.saturating_add(decoded_size);
if total > EXPANSION_LIMIT {
return Err(Error::Read(format!("legacy assets exceed the {EXPANSION_LIMIT}-byte total limit")));
}
assets.push((id.clone(), decode_base64(encoded)));
}
}
}
if let Some(object) = document.as_object_mut() {
object.remove(field);
}
}
Ok(Package { document, version: 1, assets })
}
fn decode_base64(input: &str) -> Vec<u8> {
let mut out = Vec::with_capacity(input.len().saturating_mul(3) / 4);
let (mut buffer, mut bits) = (0u32, 0u32);
for byte in input.bytes() {
let value = match byte {
b'A'..=b'Z' => byte - b'A',
b'a'..=b'z' => byte - b'a' + 26,
b'0'..=b'9' => byte - b'0' + 52,
b'+' | b'-' => 62,
b'/' | b'_' => 63,
_ => continue,
};
buffer = (buffer << 6) | u32::from(value);
bits += 6;
if bits >= 8 {
bits -= 8;
out.push((buffer >> bits) as u8);
}
}
out
}
#[cfg(test)]
mod tests {
use super::*;
const SPEC: Spec<'static> = Spec {
mimetype_entry: "mimetype",
mimetype: "application/vnd.test+zip",
metadata_entry: "meta.json",
document_entry: "document.json",
preview_entry: "preview.png",
assets_directory: "assets",
format_name: "test",
legacy_assets_field: Some("assetData"),
};
#[test]
fn writes_and_reads_bundle_members() {
let payload = [1u8, 2, 3];
let bytes =
write(br#"{"assets":{"7":{}}}"#, 4, "Test 0.1", Some(b"png"), &[Asset { id: "7", mime: "image/png", data: &payload }], SPEC).unwrap();
assert!(has_document(&bytes, SPEC));
assert!(starts_with_mimetype(&bytes, SPEC));
let loaded = read(&bytes, 4, SPEC).unwrap();
assert_eq!(loaded.document, serde_json::json!({"assets":{"7":{}}}));
assert_eq!(loaded.version, 4);
assert_eq!(loaded.assets, [("7".to_owned(), payload.to_vec())]);
assert_eq!(read_preview(&bytes, SPEC.preview_entry).as_deref(), Some(&b"png"[..]));
}
#[test]
fn extracts_legacy_inline_assets() {
let loaded = read(br#"{"assetData":{"7":"AQID"},"name":"x"}"#, 4, SPEC).unwrap();
assert_eq!(loaded.document, serde_json::json!({"name":"x"}));
assert_eq!(loaded.assets, [("7".to_owned(), vec![1, 2, 3])]);
}
#[test]
fn refuses_newer_versions() {
let bytes = write(b"{}", 9, "future", None, &[], SPEC).unwrap();
assert_eq!(read(&bytes, 4, SPEC), Err(Error::TooNew(9)));
}
#[test]
fn stored_assets_use_source_size_and_deflated_assets_use_their_limit() {
let bytes = vec![7u8; 128];
let document = br#"{"assets":{"7":{}}}"#;
let limits = ReadLimits { json_bytes: 1 << 20, compressed_asset_bytes: 8, expansion_bytes: 1 << 20 };
let stored = write(document, 4, "test", None, &[Asset { id: "7", mime: "image/png", data: &bytes }], SPEC).unwrap();
let package = read_with_limits(&stored, 4, SPEC, limits).unwrap();
assert_eq!(package.assets, [("7".to_owned(), bytes.clone())]);
let compressed = write(document, 4, "test", None, &[Asset { id: "7", mime: "application/octet-stream", data: &bytes }], SPEC).unwrap();
assert!(read_with_limits(&compressed, 4, SPEC, limits).is_err());
}
}
+1 -1
View File
@@ -443,7 +443,7 @@ fn read_axes<'a>(c: &mut Chart, pa: &'a El, primary_val: &Option<String>) -> (Op
// A gridline whose `c:spPr/a:ln` has `a:noFill` is not drawn, though the element is there.
let grid = |a: &El, k: &str| {
a.child(Local(k))
.is_some_and(|g| !g.child(Local("spPr")).and_then(|p| p.child(Local("ln"))).is_some_and(|l| l.child(Local("noFill")).is_some()))
.is_some_and(|g| g.child(Local("spPr")).and_then(|p| p.child(Local("ln"))).is_none_or(|l| l.child(Local("noFill")).is_none()))
};
if c.kind == ChartType::Combo && c.series.iter().any(|s| s.secondary_axis) {
let primary_id = val_ax.and_then(|a| a.child(Local("axId")).and_then(|c| c.attr_local("val")));
+36 -9
View File
@@ -764,20 +764,32 @@ mod tests {
/// Sizes the digests were taken at: wide, tall and square.
const GOLD_SIZES: [(f64, f64); 4] = [(120.0, 80.0), (300.0, 50.0), (64.0, 64.0), (50.0, 300.0)];
/// `v` as the digest prints it: a value that prints as zero at 3 decimal places becomes
/// `0.0`, so a residue such as `-1.4e-14` left by a sine or cosine of a right angle prints
/// `0.000` whatever its sign. Its sign depends on the platform's libm, and `{:.3}` prints a
/// negative residue as `-0.000`.
fn digest_coord(v: f64) -> f64 {
if v.abs() < 0.0005 { 0.0 } else { v }
}
/// FNV-1a over each outline's path elements, for every adjust set and size. Coordinates are
/// printed to 3 decimal places so last-bit libm differences between platforms do not change it.
/// printed to 3 decimal places through [`digest_coord`] so last-bit libm differences between
/// platforms do not change it.
fn outline_digest(name: &str) -> u64 {
use std::fmt::Write;
let c = digest_coord;
let mut text = String::new();
for adj in GOLD_ADJ {
for (w, h) in GOLD_SIZES {
let g = build(name, w, h, adj).unwrap_or_else(|| panic!("{name} builds no outline"));
for el in g.outline().elements() {
let _ = match *el {
PathEl::MoveTo(p) => write!(text, "M{:.3},{:.3}", p.x, p.y),
PathEl::LineTo(p) => write!(text, "L{:.3},{:.3}", p.x, p.y),
PathEl::QuadTo(a, p) => write!(text, "Q{:.3},{:.3},{:.3},{:.3}", a.x, a.y, p.x, p.y),
PathEl::CurveTo(a, b, p) => write!(text, "C{:.3},{:.3},{:.3},{:.3},{:.3},{:.3}", a.x, a.y, b.x, b.y, p.x, p.y),
PathEl::MoveTo(p) => write!(text, "M{:.3},{:.3}", c(p.x), c(p.y)),
PathEl::LineTo(p) => write!(text, "L{:.3},{:.3}", c(p.x), c(p.y)),
PathEl::QuadTo(a, p) => write!(text, "Q{:.3},{:.3},{:.3},{:.3}", c(a.x), c(a.y), c(p.x), c(p.y)),
PathEl::CurveTo(a, b, p) => {
write!(text, "C{:.3},{:.3},{:.3},{:.3},{:.3},{:.3}", c(a.x), c(a.y), c(b.x), c(b.y), c(p.x), c(p.y))
}
PathEl::ClosePath => write!(text, "Z"),
};
}
@@ -789,21 +801,23 @@ mod tests {
/// Digests of every name's outlines as the string dispatch built them (craft-libs 2b35d243;
/// DeckCraft's fc35ad67 gave other digests for curvedRightArrow and curvedDownArrow), so
/// this refactor is proven output-identical: any changed outline fails here.
/// this refactor is proven output-identical: any changed outline fails here. pieWedge,
/// curvedRightArrow and curvedDownArrow were taken again when [`digest_coord`] began printing
/// their near-zero residues as `0.000`; their outlines are unchanged.
const GOLDEN: [(&str, u64); 38] = [
("lineInv", 0x4a58a16923e54a4f),
("nonIsoscelesTrapezoid", 0x79eca0b36812e282),
("pieWedge", 0x2a0d3ffe5e9a481d),
("pieWedge", 0x5fb58e0214989f4d),
("leftRightArrowCallout", 0x9cd88f0ab55f76e5),
("upDownArrowCallout", 0x568bc91708855007),
("quadArrowCallout", 0xca59015298b1584b),
("circularArrow", 0x4227aa468cfe990e),
("leftCircularArrow", 0x6fc3779ce4b08914),
("leftRightCircularArrow", 0x9dd43d9ba80e47df),
("curvedRightArrow", 0x83e7dd251401715d),
("curvedRightArrow", 0xf60d53e01a88930c),
("curvedLeftArrow", 0x82472848de4a9fec),
("curvedUpArrow", 0xcfbd88c1aea4bf9d),
("curvedDownArrow", 0xa6f75eaf0ee71d49),
("curvedDownArrow", 0x01b1ac2f13de11b9),
("swooshArrow", 0x63ff193fdf1d0427),
("callout1", 0xe7e0410f96282e8d),
("callout2", 0xcaa7730106a9ee1b),
@@ -831,6 +845,19 @@ mod tests {
("chartPlus", 0x979031aae16250d7),
];
/// A near-zero residue prints the same whichever sign the platform's libm left on it, and
/// values that round away from zero keep their sign.
#[test]
fn digest_prints_near_zero_residues_without_a_sign() {
let print = |v: f64| format!("{:.3}", digest_coord(v));
for v in [-1.4210854715202004e-14, 1.4210854715202004e-14, -7.105427357601002e-15, -0.0, 0.0, -0.00049, 0.00049] {
assert_eq!(print(v), "0.000", "{v:e}");
}
assert_eq!(print(-0.0006), "-0.001");
assert_eq!(print(-12.25), "-12.250");
assert_eq!(print(0.0006), "0.001");
}
/// Every name builds the same outline as before the `Name` enum, and unknown names build nothing.
#[test]
fn outlines_match_the_string_dispatch() {
+6
View File
@@ -166,6 +166,12 @@ pub fn blip_fill(src: &mut dyn Source, bf: &El) -> Option<PictureFill> {
{
pf.artistic = Some(crate::style::Artistic { effect, original });
}
pf.svg = blip.and_then(|b| b.child(Local("extLst"))).and_then(|extensions| {
extensions
.elements()
.filter(|extension| extension.local() == "ext" && extension.attr_local("uri") == Some("{96DAC541-7B7A-43D3-8B79-37D633B846F1}"))
.find_map(|extension| extension.child(Local("svgBlip")).and_then(|svg| media_ref(src, svg)))
});
if let Some(b) = blip {
for e in b.elements() {
match e.local() {
+3
View File
@@ -184,6 +184,9 @@ impl Default for PictureMode {
#[serde(default, rename_all = "camelCase")]
pub struct PictureFill {
pub media: MediaId,
/// Optional vector SVG version of `media`; the regular media remains the bitmap fallback.
#[serde(skip_serializing_if = "Option::is_none")]
pub svg: Option<MediaId>,
/// Source crop as fractions of the image (left, top, right, bottom); negative values pad.
pub crop: [f64; 4],
pub mode: PictureMode,
+8
View File
@@ -107,6 +107,7 @@ pub fn blip_fill(w: &mut Writer, out: &mut dyn Sink, tag: &str, pf: &PictureFill
w.tag(tag).attr("rotWithShape", if pf.upright { "0" } else { "1" }).open();
let adj = &pf.adjust;
let has_kids = pf.alpha.is_some()
|| pf.svg.is_some()
|| adj.brightness != 0.0
|| adj.contrast != 0.0
|| adj.grayscale
@@ -168,6 +169,13 @@ pub fn blip_fill(w: &mut Writer, out: &mut dyn Sink, tag: &str, pf: &PictureFill
w.close();
w.close();
}
if let Some(svg) = pf.svg.and_then(|id| out.media_rel(id, "image")) {
w.open("a:extLst", &[]);
w.tag("a:ext").attr("uri", "{96DAC541-7B7A-43D3-8B79-37D633B846F1}").open();
w.tag("asvg:svgBlip").attr("xmlns:asvg", "http://schemas.microsoft.com/office/drawing/2016/SVG/main").attr("r:embed", &svg).empty();
w.close();
w.close();
}
w.close();
} else {
w.tag("a:blip").list(a).empty();
+1
View File
@@ -15,3 +15,4 @@ craft-codepage = { workspace = true }
thiserror = { workspace = true }
log = "0.4"
encoding_rs = "0.8.35"
kurbo = { workspace = true }
+4 -3
View File
@@ -11,6 +11,7 @@
use std::io::Write as _;
pub mod model;
pub mod paths;
mod version;
pub use version::Version;
@@ -768,7 +769,7 @@ fn ascii(tags: &[Tag], strings: Strings) -> Vec<u8> {
/// Write tags as binary DXF (DXF Reference, "Binary DXF Files", R13+ layout): the sentinel,
/// then per tag a 2-byte little-endian group code and the value in the binary form of the code's
/// [`Kind`]: a zero-terminated string, an 8-byte real, a 2-, 4- or 8-byte integer, a 1-byte
/// boolean, or a binary chunk (one length byte, then up to 255 bytes; longer data is split into
/// boolean, or a binary chunk (one length byte, then up to 127 bytes; longer data is split into
/// several groups of the same code). Strings are UTF-8 when `utf8` (R2007+), otherwise escaped as
/// in [`write_ascii`]. A tag's value is converted to its code's kind, so a number written as text
/// is stored as a number; a code outside the 16-bit range is skipped.
@@ -822,8 +823,8 @@ fn binary(tags: &[Tag], strings: Strings) -> Vec<u8> {
}
Kind::Hex => {
let bytes = hex_bytes(&t.value.as_str());
// An empty chunk is still one group, as in ASCII.
let mut chunks: Vec<&[u8]> = bytes.chunks(255).collect();
// At most 127 bytes per group, as in ASCII; an empty chunk is still one group.
let mut chunks: Vec<&[u8]> = bytes.chunks(127).collect();
if chunks.is_empty() {
chunks.push(&[]);
}
+7
View File
@@ -1478,6 +1478,13 @@ const MODEL: &str = "*Model_Space";
const PAPER: &str = "*Paper_Space";
impl Drawing<'_> {
/// Set `$LUNITS` without making callers construct low-level group tags.
pub fn with_linear_units(mut self, units: i64) -> Self {
self.header.retain(|(name, _)| !name.eq_ignore_ascii_case("$LUNITS"));
self.header.push(("$LUNITS".into(), vec![Tag::i(70, units)]));
self
}
/// The whole file as tags, ending with `0 EOF`, and how many entities were left out
/// ([`EntityKind::Other`], and a MULTILEADER before 2007 or an ACAD_TABLE before 2004, which it has no groups for: pass
/// those in `raw_entities`).
+321
View File
@@ -0,0 +1,321 @@
//! Bounded conversion of common planar DXF entities into neutral Bézier paths.
//!
//! This is geometry extraction, not a full CAD scene renderer: unsupported entities such as
//! text, dimensions, meshes, and block inserts are reported as warnings and omitted.
use kurbo::{BezPath, Point, Rect, Shape as _};
/// Limits on the number of paths returned by [`import`]. Parsing also uses the crate's tag cap.
pub const MAX_PATHS: usize = 200_000;
/// Aggregate number of Bézier elements a drawing may generate during conversion.
pub const MAX_PATH_ELEMENTS: usize = 2_000_000;
#[derive(Debug, thiserror::Error)]
pub enum Error {
#[error("DXF parse failed: {0}")]
Parse(#[from] crate::DxfError),
#[error("DXF contains more than {MAX_PATHS} paths")]
TooManyPaths,
#[error("DXF curve exceeds the subdivision limit")]
TooManySegments,
#[error("DXF contains a non-finite path coordinate")]
NonFinite,
}
/// Geometry in source DXF coordinates. `unit_to_mm` maps a source coordinate to millimetres;
/// unitless drawings use `1.0`, as the coordinates are then interpreted as millimetres.
#[derive(Debug, Clone)]
pub struct Imported {
pub paths: Vec<BezPath>,
pub bounds: Option<Rect>,
pub unit_to_mm: f64,
pub warnings: Vec<String>,
}
/// Parse bounded DXF input and extract visible planar linework.
pub fn import(bytes: &[u8]) -> Result<Imported, Error> {
let tags = crate::parse_with_limit(bytes, crate::max_tags())?;
let drawing = crate::model::Document::read(&tags);
let unit_to_mm = units_to_mm(drawing.header.insunits(), drawing.header.measurement());
let layer_visibility: std::collections::HashMap<_, _> =
drawing.layers().into_iter().map(|layer| (layer.name, layer.on && !layer.frozen)).collect();
let mut paths = Vec::new();
let mut warnings = Vec::new();
let mut unsupported = 0usize;
let mut elements = 0usize;
for record in &drawing.entities {
let entity = crate::model::Entity::read(record);
if !entity.common.visible || record.paper_space() || layer_visibility.get(&entity.common.layer) == Some(&false) {
continue;
}
if excessive_sweep(&entity.kind) {
return Err(Error::TooManySegments);
}
let remaining = MAX_PATH_ELEMENTS.saturating_sub(elements);
if estimated_elements(&entity.kind) > remaining {
return Err(Error::TooManySegments);
}
let converted = entity_paths(&entity.kind, entity.common.extrusion);
if converted.iter().flat_map(|path| path.elements()).any(|element| {
let finite = |p: Point| p.x.is_finite() && p.y.is_finite();
match *element {
kurbo::PathEl::MoveTo(p) | kurbo::PathEl::LineTo(p) => !finite(p),
kurbo::PathEl::QuadTo(a, b) => !finite(a) || !finite(b),
kurbo::PathEl::CurveTo(a, b, c) => !finite(a) || !finite(b) || !finite(c),
kurbo::PathEl::ClosePath => false,
}
}) {
return Err(Error::NonFinite);
}
if converted.is_empty() {
unsupported = unsupported.saturating_add(1);
continue;
}
elements = elements.saturating_add(converted.iter().map(|path| path.elements().len()).sum::<usize>());
if elements > MAX_PATH_ELEMENTS {
return Err(Error::TooManySegments);
}
if paths.len().saturating_add(converted.len()) > MAX_PATHS {
return Err(Error::TooManyPaths);
}
paths.extend(converted);
}
if unsupported > 0 {
warnings.push(format!("{unsupported} visible DXF entities are unsupported and were omitted"));
}
if drawing.skipped.iter().any(|(_, n)| *n > 0) {
warnings.push("some unsupported or stray DXF records were skipped".into());
}
let bounds = paths.iter().map(|path| path.bounding_box()).reduce(|a, b| a.union(b));
Ok(Imported { paths, bounds, unit_to_mm, warnings })
}
fn estimated_elements(kind: &crate::model::EntityKind) -> usize {
use crate::model::EntityKind as E;
let arc_count = |sweep: f64| (sweep.abs() / std::f64::consts::FRAC_PI_2).ceil().max(1.0) as usize;
let bulge_count = |bulge: f64| {
if bulge.is_finite() && bulge.abs() > 1e-12 { arc_count(4.0 * bulge.atan()) } else { 1 }
};
let polyline_count = |vertices: &[(Point, f64)], closed: bool| {
if vertices.is_empty() {
return 0;
}
let mut count = 1usize;
for pair in vertices.windows(2) {
count = count.saturating_add(bulge_count(pair[0].1));
}
if closed && vertices.len() > 1 {
count = count.saturating_add(bulge_count(vertices.last().map_or(0.0, |vertex| vertex.1)));
count = count.saturating_add(1);
}
count
};
match kind {
E::Line { .. } => 2,
E::Circle { .. } => 6,
E::Arc { start_angle, end_angle, .. } => 1usize.saturating_add(arc_count((end_angle - start_angle).to_radians())),
E::LwPolyline(poly) => {
let vertices: Vec<_> = poly.vertices.iter().map(|v| (Point::new(v.x, v.y), v.bulge)).collect();
polyline_count(&vertices, poly.closed)
}
E::Polyline(poly) if !poly.is_mesh() && !poly.is_polyface() => {
let vertices: Vec<_> = poly
.vertices
.iter()
.filter(|vertex| !vertex.is_face())
.map(|vertex| (Point::new(vertex.location[0], vertex.location[1]), vertex.bulge))
.collect();
polyline_count(&vertices, poly.closed())
}
E::Ellipse { start, end, .. } => 1usize.saturating_add(arc_count(end - start)),
_ => 0,
}
}
fn units_to_mm(code: i64, _measurement: Option<i64>) -> f64 {
match code {
0 => 1.0,
1 => 25.4,
2 => 304.8,
3 => 1_609_344.0,
5 => 10.0,
6 => 1_000.0,
7 => 1_000_000.0,
8 => 0.000_025_4,
9 => 0.0254,
10 => 914.4,
11 => 1e-7,
12 => 1e-6,
13 => 0.001,
14 => 100.0,
15 => 10_000.0,
16 => 100_000.0,
17 => 1e12,
18 => 149_597_870_700_000.0,
19 => 9.460_730_472_580_8e18,
20 => 3.085_677_581_491_367e19,
21 => 1200.0 / 3937.0 * 1000.0,
22 => 1200.0 / 3937.0 * 1000.0 / 12.0,
23 => 1200.0 / 3937.0 * 1000.0 * 3.0,
24 => 1200.0 / 3937.0 * 1000.0 * 5280.0,
_ => 1.0,
}
}
fn entity_paths(kind: &crate::model::EntityKind, normal: crate::model::Point) -> Vec<BezPath> {
use crate::model::EntityKind as E;
match kind {
E::Line { start, end } => vec![line(*start, *end)],
E::Circle { center, radius } if radius.is_finite() && *radius > 0.0 => {
vec![map_ocs_path(circle(Point::new(center[0], center[1]), *radius), normal, center[2])]
}
E::Arc { center, radius, start_angle, end_angle }
if radius.is_finite() && *radius > 0.0 && start_angle.is_finite() && end_angle.is_finite() =>
{
vec![map_ocs_path(arc(Point::new(center[0], center[1]), *radius, start_angle.to_radians(), end_angle.to_radians()), normal, center[2])]
}
E::LwPolyline(poly) => {
vec![map_ocs_path(polyline(poly.vertices.iter().map(|v| (Point::new(v.x, v.y), v.bulge)), poly.closed), normal, poly.elevation)]
}
E::Polyline(poly) if !poly.is_mesh() && !poly.is_polyface() => {
let is_3d = poly.flags & 8 != 0;
let z = if is_3d { 0.0 } else { poly.elevation };
let path =
polyline(poly.vertices.iter().filter(|v| !v.is_face()).map(|v| (Point::new(v.location[0], v.location[1]), v.bulge)), poly.closed());
vec![if is_3d { path } else { map_ocs_path(path, normal, z) }]
}
E::Ellipse { center, major, ratio, start, end } if ratio.is_finite() && *ratio > 0.0 => {
vec![ellipse(*center, *major, normal, *ratio, *start, *end)]
}
_ => Vec::new(),
}
}
fn map_ocs_path(path: BezPath, normal: crate::model::Point, z: f64) -> BezPath {
let [x, y, n] = crate::model::ocs_axes(normal);
let transform = kurbo::Affine::new([x[0], x[1], y[0], y[1], n[0] * z, n[1] * z]);
transform * path
}
fn excessive_sweep(kind: &crate::model::EntityKind) -> bool {
let cap = 4096.0 * std::f64::consts::FRAC_PI_2;
let over = |sweep: f64| !sweep.is_finite() || sweep.abs() > cap;
match kind {
crate::model::EntityKind::Arc { start_angle, end_angle, .. } => over((end_angle - start_angle).to_radians()),
crate::model::EntityKind::Ellipse { start, end, .. } => over(end - start),
_ => false,
}
}
fn line(start: crate::model::Point, end: crate::model::Point) -> BezPath {
let mut path = BezPath::new();
path.move_to((start[0], start[1]));
path.line_to((end[0], end[1]));
path
}
fn polyline(vertices: impl IntoIterator<Item = (Point, f64)>, closed: bool) -> BezPath {
let vertices = vertices.into_iter().collect::<Vec<_>>();
let mut path = BezPath::new();
let Some((first, _)) = vertices.first().copied() else { return path };
path.move_to(first);
for i in 1..vertices.len() {
let (a, bulge) = vertices[i - 1];
let (b, _) = vertices[i];
if bulge.is_finite() && bulge.abs() > 1e-12 {
append_bulge(&mut path, a, b, bulge);
} else {
path.line_to(b);
}
}
if closed && vertices.len() > 1 {
let (a, bulge) = *vertices.last().unwrap_or(&(first, 0.0));
if bulge.is_finite() && bulge.abs() > 1e-12 {
append_bulge(&mut path, a, first, bulge);
} else {
path.line_to(first);
}
path.close_path();
}
path
}
fn append_bulge(path: &mut BezPath, a: Point, b: Point, bulge: f64) {
let chord = b - a;
let length = chord.hypot();
if !(length.is_finite() && length > 0.0) {
path.line_to(b);
return;
}
let center = a + chord * 0.5 + kurbo::Vec2::new(-chord.y, chord.x) * ((1.0 - bulge * bulge) / (4.0 * bulge));
let start = (a.y - center.y).atan2(a.x - center.x);
let sweep = 4.0 * bulge.atan();
let radius = length * (1.0 + bulge * bulge) / (4.0 * bulge.abs());
arc_segments(path, center, start, sweep, radius);
}
fn circle(center: Point, radius: f64) -> BezPath {
let mut path = BezPath::new();
path.move_to((center.x + radius, center.y));
arc_segments(&mut path, center, 0.0, std::f64::consts::TAU, radius);
path.close_path();
path
}
fn arc(center: Point, radius: f64, start: f64, end: f64) -> BezPath {
let mut path = BezPath::new();
path.move_to((center.x + radius * start.cos(), center.y + radius * start.sin()));
let sweep = if end >= start { end - start } else { end - start + std::f64::consts::TAU };
arc_segments(&mut path, center, start, sweep, radius);
path
}
fn arc_segments(path: &mut BezPath, center: Point, start: f64, sweep: f64, radius: f64) {
let count = (sweep.abs() / (std::f64::consts::FRAC_PI_2)).ceil().max(1.0) as usize;
if count > 4096 {
return;
}
let step = sweep / count as f64;
for i in 0..count {
let a = start + step * i as f64;
let b = a + step;
let k = 4.0 / 3.0 * (step / 4.0).tan();
let p1 = Point::new(center.x + radius * (a.cos() - k * a.sin()), center.y + radius * (a.sin() + k * a.cos()));
let p2 = Point::new(center.x + radius * (b.cos() + k * b.sin()), center.y + radius * (b.sin() - k * b.cos()));
let p3 = Point::new(center.x + radius * b.cos(), center.y + radius * b.sin());
path.curve_to(p1, p2, p3);
}
}
fn ellipse(center: crate::model::Point, major: crate::model::Point, normal: crate::model::Point, ratio: f64, start: f64, end: f64) -> BezPath {
let minor = cross(normal, major);
let minor_len = minor.iter().map(|v| v * v).sum::<f64>().sqrt();
if !(minor_len.is_finite() && minor_len > 0.0) {
return BezPath::new();
}
let major_len = major.iter().map(|v| v * v).sum::<f64>().sqrt();
let bx = [minor[0] / minor_len * major_len * ratio, minor[1] / minor_len * major_len * ratio, minor[2] / minor_len * major_len * ratio];
let point = |t: f64| Point::new(center[0] + major[0] * t.cos() + bx[0] * t.sin(), center[1] + major[1] * t.cos() + bx[1] * t.sin());
let mut path = BezPath::new();
path.move_to(point(start));
let sweep = if end >= start { end - start } else { end - start + std::f64::consts::TAU };
let count = (sweep.abs() / std::f64::consts::FRAC_PI_2).ceil().max(1.0) as usize;
if count > 4096 {
return path;
}
let step = sweep / count as f64;
for i in 0..count {
let a = start + step * i as f64;
let b = a + step;
let k = 4.0 / 3.0 * (step / 4.0).tan();
let derivative = |t: f64| Point::new(-major[0] * t.sin() + bx[0] * t.cos(), -major[1] * t.sin() + bx[1] * t.cos());
let p1 = point(a) + derivative(a).to_vec2() * k;
let p2 = point(b) - derivative(b).to_vec2() * k;
path.curve_to(p1, p2, point(b));
}
path
}
fn cross(a: crate::model::Point, b: crate::model::Point) -> crate::model::Point {
[a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]]
}
+2 -3
View File
@@ -30,9 +30,8 @@ fn binary_converts_values_to_their_codes_kind() {
let back = parse(&write_binary(&tags, true)).unwrap();
assert_eq!(back[0], Tag::i(70, 12));
assert_eq!(back[1], Tag::i(62, i64::from(i16::MAX)));
assert_eq!(back[2].code, 310);
assert_eq!(back[3].code, 310, "300 bytes are split into chunks of at most 255");
assert_eq!(back[2].str().len() + back[3].str().len(), 600);
let sizes: Vec<usize> = back.iter().filter(|t| t.code == 310).map(|t| t.str().len()).collect();
assert_eq!(sizes, vec![254, 254, 92], "300 bytes are split into chunks of at most 127 (254 hex digits)");
}
#[test]
+11 -2
View File
@@ -2,7 +2,6 @@
//! 1004 specify at most 127 payload bytes per chunk, even though a length byte represents 255.
//! Inspect writer bytes without our parser; accept any compliant partition preserving payload,
//! code and following-record framing. Oversized binary read fixtures test tolerance only.
//! Pending writer regressions extend the chunk-size finding in issue #1025.
//! Public DXF Reference, Group Codes in Numerical Order and Binary DXF Files:
//! <https://help.autodesk.com/cloudhelp/2025/ENU/AutoCAD-DXF/files/GUID-3F0380A5-1C15-464D-BC66-2C5F094BCFB9.htm>
//! <https://help.autodesk.com/cloudhelp/2025/ENU/AutoCAD-DXF/files/GUID-FC1C3C69-DBC2-49E4-893A-000D6538C0FE.htm>
@@ -100,7 +99,17 @@ fn binary_reader_tolerates_the_full_length_byte_domain() {
}
#[test]
#[ignore = "Confirmed binary DXF writer nonconformance: 255-byte partitioning exceeds the documented 127-byte group limit"]
fn ascii_writer_splits_large_payloads_into_conforming_chunks() {
for code in (310..=319).chain([1004]) {
for length in [128, 254, 255, 256, 1024] {
for utf8 in [false, true] {
check_ascii(code, &payload(length), utf8);
}
}
}
}
#[test]
fn binary_writer_splits_large_payloads_into_conforming_chunks() {
for code in (310..=319).chain([1004]) {
for length in [128, 254, 255, 256, 1024] {
+3 -1
View File
@@ -596,7 +596,8 @@ fn the_file_around_the_content() {
raw_objects: vec![Tag::s(0, "DICTIONARY"), Tag::s(5, "901"), Tag::s(330, "A")],
raw_classes: vec![Tag::s(0, "CLASS"), Tag::s(1, "IMAGEDEF")],
..Drawing::default()
};
}
.with_linear_units(2);
let (tags, skipped) = drawing.tags();
assert_eq!(skipped, 1, "the entity with no groups to write");
assert_eq!(tags.last().map(|t| (t.code, t.str())), Some((0, "EOF".to_string())));
@@ -617,6 +618,7 @@ fn the_file_around_the_content() {
assert_eq!((d.header.acadver().as_deref(), d.header.ltscale(), d.header.insunits()), (Some("AC1032"), 2.0, 6));
assert_eq!(d.header.vars.iter().filter(|(n, _)| *n == "$INSUNITS" || *n == "$ACADVER" || *n == "$HANDSEED").count(), 3);
assert_eq!(d.header.point("$EXTMAX"), Some([100.0, 50.0, 0.0]));
assert_eq!(d.header.vars.iter().find(|(name, _)| *name == "$LUNITS").map(|(_, tags)| tags[0].i64()), Some(2));
// Blocks, their records and the layouts that name them.
let names = d.block_names();
let block = d.block("DOOR").expect("the block");
+8
View File
@@ -11,3 +11,11 @@ repository.workspace = true
workspace = true
[dependencies]
kurbo = { workspace = true, optional = true }
vectorcraft-doc = { workspace = true, optional = true }
vectorcraft-eps = { workspace = true, optional = true }
thiserror = { workspace = true, optional = true }
[features]
default = []
paths = ["dep:kurbo", "dep:thiserror", "dep:vectorcraft-doc", "dep:vectorcraft-eps"]
+4
View File
@@ -18,11 +18,15 @@
pub mod ascii85;
mod container;
mod dsc;
#[cfg(feature = "paths")]
pub mod paths;
mod preview;
mod rectangles;
pub use container::{DOS_HEADER, DOS_MAGIC, Sections, sections, wrap};
pub use dsc::{Comments, MAX_HEADER, MAX_TRAILER};
pub use preview::{Bitmap, MAX_EPSI, epsi};
pub use rectangles::{MAX_SIMPLE_RECTANGLE_SAVE_DEPTH, MAX_SIMPLE_RECTANGLE_TOKENS, MAX_SIMPLE_RECTANGLES, Rectangle, simple_rectangles};
use std::fmt;
+108
View File
@@ -0,0 +1,108 @@
//! Neutral path extraction for EPS and PostScript files.
//!
//! This facade keeps the PostScript interpreter and its format decisions in shared dependencies;
//! applications receive Bézier paths, page bounds and warnings for their own document adapters.
use kurbo::{BezPath, Rect};
/// Limits on the extracted geometry. The interpreter has its own execution and allocation caps.
#[derive(Debug, Clone, Copy)]
pub struct Limits {
pub max_input_bytes: usize,
pub max_paths: usize,
pub max_path_elements: usize,
}
impl Default for Limits {
fn default() -> Self {
Self { max_input_bytes: 64 * 1024 * 1024, max_paths: 200_000, max_path_elements: 2_000_000 }
}
}
#[derive(Debug, thiserror::Error)]
pub enum Error {
#[error("PostScript input exceeds {limit} bytes")]
InputLimit { limit: usize },
#[error("PostScript import failed: {0}")]
Parse(String),
#[error("PostScript path output exceeds configured limit")]
OutputLimit,
}
/// First-page path geometry normalized to the top-left origin in PostScript points, plus notes.
#[derive(Debug, Clone)]
pub struct Imported {
pub paths: Vec<BezPath>,
/// Origin-zero page bounds in PostScript points, using the same accepted DSC box as the
/// interpreter.
pub page_bounds: Rect,
pub warnings: Vec<String>,
pub preview_fallback: bool,
}
/// Interpret EPS/PostScript bytes and return their editable vector path geometry.
pub fn import(bytes: &[u8], limits: Limits) -> Result<Imported, Error> {
if bytes.len() > limits.max_input_bytes {
return Err(Error::InputLimit { limit: limits.max_input_bytes });
}
let source = vectorcraft_eps::import(bytes).map_err(Error::Parse)?;
let page_bounds = vectorcraft_eps::page(bytes).map_err(Error::Parse)?;
// Illustrator's editable copy is expressed in its art-box document coordinates. The page
// reader, in contrast, returns a page at the origin. Normalize extracted paths to match it.
let origin = source.document.artboards.first().map(|board| board.rect.origin()).unwrap_or_default();
let to_page = kurbo::Affine::translate((-origin.x, -origin.y));
let mut paths = Vec::new();
let mut total_elements = 0usize;
let mut clipped = false;
let mut omitted = false;
for layer in &source.document.layers {
collect(layer, &mut paths, &mut total_elements, limits, to_page, &mut clipped, &mut omitted)?;
}
let mut warnings = source.warnings;
if clipped {
warnings.push("EPS clipping groups are returned as unclipped artwork".into());
}
if omitted {
warnings.push("visible EPS text or image content is not returned as paths".into());
}
Ok(Imported { paths, page_bounds, warnings, preview_fallback: source.preview })
}
fn collect(
node: &vectorcraft_doc::Node,
paths: &mut Vec<BezPath>,
elements: &mut usize,
limits: Limits,
to_page: kurbo::Affine,
clipped: &mut bool,
omitted: &mut bool,
) -> Result<(), Error> {
if !node.visible {
return Ok(());
}
if let Some(data) = node.path_data() {
if matches!(node.kind, vectorcraft_doc::NodeKind::Path { clipping: true, .. }) {
return Ok(());
}
let path = data.to_bezpath();
if !path.elements().is_empty() {
*elements = elements.saturating_add(path.elements().len());
if paths.len() >= limits.max_paths || *elements > limits.max_path_elements {
return Err(Error::OutputLimit);
}
paths.push(to_page * path);
}
} else if let Some(children) = node.children() {
let is_clip = matches!(node.kind, vectorcraft_doc::NodeKind::Group { clip: true, .. } | vectorcraft_doc::NodeKind::Layer { clip: true, .. });
*clipped |= is_clip;
for (index, child) in children.iter().enumerate() {
if is_clip && index == 0 {
continue;
}
collect(child, paths, elements, limits, to_page, clipped, omitted)?;
}
} else {
*omitted = true;
}
Ok(())
}
+136
View File
@@ -0,0 +1,136 @@
//! A bounded subset of PostScript used for simple EPS previews.
use std::collections::HashMap;
/// A solid rectangle drawn by a simple EPS program.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Rectangle {
/// Left edge in PostScript points.
pub x: f64,
/// Bottom edge in PostScript points.
pub y: f64,
/// Width in PostScript points.
pub width: f64,
/// Height in PostScript points.
pub height: f64,
/// Straight sRGB RGBA.
pub color: [u8; 4],
}
pub const MAX_SIMPLE_RECTANGLES: usize = 200_000;
pub const MAX_SIMPLE_RECTANGLE_TOKENS: usize = 2_000_000;
pub const MAX_SIMPLE_RECTANGLE_SAVE_DEPTH: usize = 64;
/// Simple PostScript tokens without comments, with braces kept as individual tokens.
fn tokens(text: &str) -> impl Iterator<Item = &str> {
text.split(['\n', '\r']).flat_map(|line| {
line.split('%').next().unwrap_or("").split_whitespace().flat_map(|word| word.split_inclusive(['{', '}'])).flat_map(|piece| {
let (body, brace) = match piece.char_indices().last() {
Some((at, '{' | '}')) => (piece.get(..at).unwrap_or(""), piece.get(at..)),
_ => (piece, None),
};
[Some(body).filter(|body| !body.is_empty()), brace].into_iter().flatten()
})
})
}
/// Read solid rectangle fills and their sRGB colours from the restricted PostScript subset used
/// by simple EPS previews. None means the program uses an unsupported operator or exceeds a
/// fixed work bound. The function never executes PostScript.
pub fn simple_rectangles(ps: &[u8]) -> Option<Vec<Rectangle>> {
let text = std::str::from_utf8(ps).ok()?;
let mut aliases: HashMap<String, String> = HashMap::new();
let mut stack: Vec<f64> = Vec::new();
let mut color = [0u8, 0, 0, 255];
let mut saved: Vec<[u8; 4]> = Vec::new();
let mut rectangles = Vec::new();
let mut input = tokens(text);
let mut count = 0usize;
while let Some(token) = input.next() {
count += 1;
if count > MAX_SIMPLE_RECTANGLE_TOKENS {
return None;
}
if let Ok(value) = token.parse::<f64>() {
if !value.is_finite() {
return None;
}
stack.push(value);
continue;
}
if let Some(name) = token.strip_prefix('/') {
let mut body: Vec<&str> = Vec::new();
while body.len() < 5 {
count += 1;
if count > MAX_SIMPLE_RECTANGLE_TOKENS {
return None;
}
match input.next() {
Some("def") | None => break,
Some(token) => body.push(token),
}
}
let op = match body.as_slice() {
["{", op, "}"] | ["{", op, "}", _] => (*op).to_string(),
_ => return None,
};
aliases.insert(name.to_string(), op);
continue;
}
let op = aliases.get(token).map_or(token, String::as_str);
let mut pop = |n: usize| -> Option<Vec<f64>> { (stack.len() >= n).then(|| stack.split_off(stack.len() - n)) };
match op {
"setcmykcolor" => {
let values = pop(4)?;
let black = values[3].clamp(0.0, 1.0);
let channel = |value: f64| ((1.0 - value.clamp(0.0, 1.0)) * (1.0 - black) * 255.0).round() as u8;
color = [channel(values[0]), channel(values[1]), channel(values[2]), 255];
}
"setrgbcolor" => {
let values = pop(3)?;
let channel = |value: f64| (value.clamp(0.0, 1.0) * 255.0).round() as u8;
color = [channel(values[0]), channel(values[1]), channel(values[2]), 255];
}
"setgray" => {
let values = pop(1)?;
let gray = (values[0].clamp(0.0, 1.0) * 255.0).round() as u8;
color = [gray, gray, gray, 255];
}
"rectfill" => {
let values = pop(4)?;
if rectangles.len() >= MAX_SIMPLE_RECTANGLES {
return None;
}
let x1 = values[0] + values[2];
let y1 = values[1] + values[3];
if !x1.is_finite() || !y1.is_finite() {
return None;
}
rectangles.push(Rectangle {
x: values[0].min(x1),
y: values[1].min(y1),
width: (x1 - values[0]).abs(),
height: (y1 - values[1]).abs(),
color,
});
}
"gsave" | "save" => {
if saved.len() >= MAX_SIMPLE_RECTANGLE_SAVE_DEPTH {
return None;
}
saved.push(color);
}
"grestore" | "restore" => {
if let Some(previous) = saved.pop() {
color = previous;
}
}
"pop" => {
pop(1)?;
}
"bind" | "newpath" | "showpage" | "end" | "begin" => {}
_ => return None,
}
}
(!rectangles.is_empty()).then_some(rectangles)
}
+18
View File
@@ -0,0 +1,18 @@
[package]
name = "craft-figcraft-format"
description = "The native FigCraft document JSON and archive contract."
version.workspace = true
edition.workspace = true
license.workspace = true
rust-version.workspace = true
repository.workspace = true
[lints]
workspace = true
[dependencies]
serde = { workspace = true }
serde_json = { workspace = true }
craft-zip = { workspace = true }
zip = { version = "9", default-features = false, features = ["deflate-flate2"] }
thiserror = { workspace = true }
+849
View File
@@ -0,0 +1,849 @@
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
//! The neutral JSON header and version contract for FigCraft's native project format.
//! App-specific document fields remain a generic flattened payload.
pub mod library;
use serde::de::{IgnoredAny, MapAccess, Visitor};
use serde::{Deserialize, Deserializer, Serialize};
use serde_json::Value;
pub const EXTENSION: &str = "figcraft";
pub const FORMAT: &str = "figcraft";
pub const VERSION: u32 = 1;
fn is_false(value: &bool) -> bool {
!value
}
/// One native version-history index entry. Invalid optional values decode to the same defaults as
/// the historical lenient reader; the app applies document-specific validity and issue reporting.
#[derive(Clone, Debug, Default, PartialEq, Serialize)]
pub struct VersionEntry {
pub id: String,
pub name: String,
pub description: String,
pub time: u64,
#[serde(skip_serializing_if = "is_false")]
pub auto: bool,
pub images: Vec<String>,
}
impl<'de> Deserialize<'de> for VersionEntry {
fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
let value = Value::deserialize(deserializer)?;
let string = |key: &str| value.get(key).and_then(Value::as_str).unwrap_or_default().to_owned();
let images = value.get("images").and_then(Value::as_array).into_iter().flatten().filter_map(Value::as_str).map(str::to_owned).collect();
Ok(Self {
id: string("id"),
name: string("name"),
description: string("description"),
time: value.get("time").and_then(Value::as_u64).unwrap_or(0),
auto: value.get("auto").and_then(Value::as_bool).unwrap_or(false),
images,
})
}
}
/// Native version-history index, oldest first.
#[derive(Clone, Debug, Default, PartialEq, Serialize)]
pub struct VersionIndex {
pub versions: Vec<VersionEntry>,
}
/// Encode the native version-history index using the FigCraft wire schema.
pub fn write_version_index(index: &VersionIndex) -> Result<Vec<u8>, serde_json::Error> {
serde_json::to_vec(index)
}
/// Decode the native version-history index using the format's lenient optional-field defaults.
pub fn read_version_index(bytes: &[u8]) -> Result<VersionIndex, serde_json::Error> {
serde_json::from_slice(bytes)
}
impl<'de> Deserialize<'de> for VersionIndex {
fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
let value = Value::deserialize(deserializer)?;
let versions = value
.get("versions")
.and_then(Value::as_array)
.map(|entries| entries.iter().cloned().map(serde_json::from_value).collect::<Result<Vec<_>, _>>())
.transpose()
.map_err(serde::de::Error::custom)?
.unwrap_or_default();
Ok(Self { versions })
}
}
/// State stored on a native branch entry.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum BranchState {
#[default]
Active,
Merged,
Archived,
}
/// One native branch index entry.
#[derive(Clone, Debug, Default, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct BranchEntry {
pub id: String,
pub name: String,
pub time: u64,
pub client: u32,
pub state: BranchState,
pub base_images: Vec<String>,
pub head_images: Vec<String>,
}
impl<'de> Deserialize<'de> for BranchEntry {
fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
let value = Value::deserialize(deserializer)?;
let string = |key: &str| value.get(key).and_then(Value::as_str).unwrap_or_default().to_owned();
let images =
|key: &str| value.get(key).and_then(Value::as_array).into_iter().flatten().filter_map(Value::as_str).map(str::to_owned).collect();
let state = value.get("state").cloned().and_then(|v| serde_json::from_value(v).ok()).unwrap_or_default();
let client = value.get("client").and_then(Value::as_u64).and_then(|v| u32::try_from(v).ok()).unwrap_or(0);
Ok(Self {
id: string("id"),
name: string("name"),
time: value.get("time").and_then(Value::as_u64).unwrap_or(0),
client,
state,
base_images: images("baseImages"),
head_images: images("headImages"),
})
}
}
/// Native branch index.
#[derive(Clone, Debug, Default, PartialEq, Serialize)]
pub struct BranchIndex {
pub branches: Vec<BranchEntry>,
}
/// Encode the native branch index using the FigCraft wire schema.
pub fn write_branch_index(index: &BranchIndex) -> Result<Vec<u8>, serde_json::Error> {
serde_json::to_vec(index)
}
/// Decode the native branch index using the format's lenient optional-field defaults.
pub fn read_branch_index(bytes: &[u8]) -> Result<BranchIndex, serde_json::Error> {
serde_json::from_slice(bytes)
}
impl<'de> Deserialize<'de> for BranchIndex {
fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
let value = Value::deserialize(deserializer)?;
let branches = value
.get("branches")
.and_then(Value::as_array)
.map(|entries| entries.iter().cloned().map(serde_json::from_value).collect::<Result<Vec<_>, _>>())
.transpose()
.map_err(serde::de::Error::custom)?
.unwrap_or_default();
Ok(Self { branches })
}
}
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct Header {
pub version: Option<u64>,
pub images: Option<Vec<String>>,
}
pub fn read_header(text: &str) -> Result<Header, serde_json::Error> {
serde_json::from_str(text)
}
impl<'de> Deserialize<'de> for Header {
fn deserialize<D: serde::Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
struct V;
impl<'de> Visitor<'de> for V {
type Value = Header;
fn expecting(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str("a FigCraft document object")
}
fn visit_map<A: MapAccess<'de>>(self, mut m: A) -> Result<Header, A::Error> {
let mut h = Header::default();
while let Some(k) = m.next_key::<String>()? {
match k.as_str() {
"version" => h.version = m.next_value::<Value>()?.as_u64(),
"imageIndex" => {
h.images = m
.next_value::<Value>()?
.as_array()
.map(|a| a.iter().filter_map(|v| v.get("hash").and_then(Value::as_str).map(str::to_owned)).collect())
}
_ => {
m.next_value::<IgnoredAny>()?;
}
}
}
Ok(h)
}
}
d.deserialize_map(V)
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, thiserror::Error)]
#[error("this file was saved by a newer FigCraft (format version {0})")]
pub struct NewerVersion(pub u32);
/// Failure while reading the native document envelope or its app-supplied payload type.
#[derive(Debug, thiserror::Error)]
pub enum ReadDocumentError {
#[error(transparent)]
Json(#[from] serde_json::Error),
#[error(transparent)]
NewerVersion(#[from] NewerVersion),
}
/// Read a document payload after checking the native header and version first.
///
/// The payload type is supplied by the consumer, keeping app model conversion outside this crate.
pub fn read_document_json<D: serde::de::DeserializeOwned>(text: &str) -> Result<(D, Header), ReadDocumentError> {
let header = read_header(text)?;
check_version(&header)?;
let document = serde_json::from_str(text)?;
Ok((document, header))
}
/// The native document fields needed to render a recent-file preview.
#[derive(Clone, Debug, Default, PartialEq, Deserialize)]
pub struct PreviewDocument {
#[serde(default)]
pub pages: Vec<u64>,
#[serde(default)]
pub nodes: std::collections::BTreeMap<String, PreviewNode>,
#[serde(default)]
pub kind: PreviewKind,
}
/// Preview-relevant fields from one native document node.
#[derive(Clone, Debug, Default, PartialEq, Deserialize)]
pub struct PreviewNode {
#[serde(default)]
pub background: Option<Value>,
}
/// The supported native document kinds as stored on disk.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum PreviewKind {
#[default]
Design,
Board,
}
/// Decode the preview-relevant subset of the native FigCraft document schema.
pub fn read_preview_document(bytes: &[u8]) -> Result<PreviewDocument, serde_json::Error> {
serde_json::from_slice(bytes)
}
/// Largest `thumbnail.png` returned for a recent-file preview.
pub const MAX_PREVIEW_THUMBNAIL_BYTES: u64 = 8 * 1024 * 1024;
/// Largest `document.json` read to build a recent-file preview.
pub const MAX_PREVIEW_DOCUMENT_BYTES: u64 = 64 * 1024 * 1024;
/// Native `.figcraft` members needed by the recent-file preview.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct PreviewArchive {
/// Whether the archive has a `document.json` entry, even if it is damaged or oversized.
/// Consumers use this to distinguish a malformed native archive from other ZIP formats.
pub has_document: bool,
/// The thumbnail bytes, absent when missing, damaged, or above [`MAX_PREVIEW_THUMBNAIL_BYTES`].
pub thumbnail_png: Option<Vec<u8>>,
/// The first-page fields, absent when `document.json` is missing, damaged, or oversized.
pub document: Option<PreviewDocument>,
}
/// Read only the thumbnail member for a native archive-list thumbnail.
///
/// This avoids unpacking the document when a caller needs only the image. Missing, damaged,
/// and oversized entries return None; an unreadable archive is an error.
pub fn read_preview_thumbnail<R: std::io::Read + std::io::Seek>(reader: R) -> Result<Option<Vec<u8>>, FormatError> {
let mut archive = SeekArchive::open(reader, u64::MAX).map_err(|error| FormatError::Corrupt(error.to_string()))?;
Ok(archive.read("thumbnail.png", MAX_PREVIEW_THUMBNAIL_BYTES).ok().flatten())
}
/// Read the bounded native preview members of a `.figcraft` archive.
///
/// An unreadable archive is an error; a missing, damaged, or oversized member is represented by
/// `None`, so the caller can still show the other part of the preview. The thumbnail and document
/// retain the separate limits used by the app's recent-file preview.
pub fn read_preview_archive<R: std::io::Read + std::io::Seek>(reader: R) -> Result<PreviewArchive, FormatError> {
let mut archive = SeekArchive::open(reader, u64::MAX).map_err(|error| FormatError::Corrupt(error.to_string()))?;
Ok(read_preview_archive_from(&mut archive))
}
/// Read bounded native preview members from an already-open shared archive reader.
///
/// This lets callers preserve fallback handling for other ZIP formats without implementing ZIP
/// member access themselves.
pub fn read_preview_archive_from(archive: &mut impl NativeArchive) -> PreviewArchive {
let has_document = archive.contains("document.json");
let thumbnail_png = archive.read_member("thumbnail.png", MAX_PREVIEW_THUMBNAIL_BYTES).ok().flatten();
let document = if has_document {
archive.read_member("document.json", MAX_PREVIEW_DOCUMENT_BYTES).ok().flatten().and_then(|bytes| read_preview_document(&bytes).ok())
} else {
None
};
PreviewArchive { has_document, thumbnail_png, document }
}
pub fn check_version(h: &Header) -> Result<(), NewerVersion> {
if let Some(v) = h.version
&& v > u64::from(VERSION)
{
return Err(NewerVersion(u32::try_from(v).unwrap_or(u32::MAX)));
}
Ok(())
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
pub struct ImageIndexEntry {
pub hash: String,
pub width: u32,
pub height: u32,
}
pub fn write_document_json<D: Serialize, W: std::io::Write>(doc: &D, images: &[ImageIndexEntry], w: W) -> Result<(), serde_json::Error> {
#[derive(Serialize)]
struct Flat<'a, D: ?Sized> {
format: &'static str,
version: u32,
#[serde(rename = "imageIndex")]
images: &'a [ImageIndexEntry],
#[serde(flatten)]
document: &'a D,
}
Flat { format: FORMAT, version: VERSION, images, document: doc }.serialize(&mut serde_json::Serializer::new(w))
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn preview_archive_reads_native_members_and_preserves_document_presence() {
let document = br#"{"pages":[7],"nodes":{"7":{"background":{"r":0.25}}},"kind":"board"}"#;
let bytes = write_archive([
Member { name: "thumbnail.png", bytes: b"png bytes", compression: Compression::Stored },
Member { name: "document.json", bytes: document, compression: Compression::Deflated },
])
.unwrap();
assert_eq!(read_preview_thumbnail(std::io::Cursor::new(bytes.clone())).unwrap().as_deref(), Some(b"png bytes".as_slice()));
let mut archive = SeekArchive::open(std::io::Cursor::new(bytes.clone()), u64::MAX).unwrap();
assert!(read_preview_archive_from(&mut archive).has_document);
let preview = read_preview_archive(std::io::Cursor::new(bytes)).unwrap();
assert!(preview.has_document);
assert_eq!(preview.thumbnail_png.as_deref(), Some(b"png bytes".as_slice()));
let document = preview.document.unwrap();
assert_eq!(document.pages, [7]);
assert_eq!(document.kind, PreviewKind::Board);
assert_eq!(document.nodes["7"].background.as_ref().unwrap()["r"], 0.25);
// A malformed native document still identifies this as a FigCraft archive, allowing the
// app to retain its existing fallback instead of interpreting it as another ZIP format.
let bytes = write_archive([Member { name: "document.json", bytes: b"{", compression: Compression::Stored }]).unwrap();
let preview = read_preview_archive(std::io::Cursor::new(bytes)).unwrap();
assert!(preview.has_document);
assert!(preview.document.is_none());
assert!(preview.thumbnail_png.is_none());
assert!(read_preview_archive(std::io::Cursor::new(b"not a zip".as_slice())).is_err());
}
#[test]
fn preview_archive_keeps_thumbnail_and_document_size_limits_independent() {
let too_large_thumbnail = vec![0; MAX_PREVIEW_THUMBNAIL_BYTES as usize + 1];
let bytes = write_archive([
Member { name: "thumbnail.png", bytes: &too_large_thumbnail, compression: Compression::Deflated },
Member { name: "document.json", bytes: br#"{"pages":[3]}"#, compression: Compression::Stored },
])
.unwrap();
let preview = read_preview_archive(std::io::Cursor::new(bytes)).unwrap();
assert!(preview.thumbnail_png.is_none());
assert_eq!(preview.document.unwrap().pages, [3]);
let too_large_document = vec![b' '; MAX_PREVIEW_DOCUMENT_BYTES as usize + 1];
let bytes = write_archive([Member { name: "document.json", bytes: &too_large_document, compression: Compression::Deflated }]).unwrap();
let preview = read_preview_archive(std::io::Cursor::new(bytes)).unwrap();
assert!(preview.has_document);
assert!(preview.document.is_none());
}
#[test]
fn header_skips_app_fields() {
let h = read_header(r#"{"version":1,"imageIndex":[{"hash":"abc"}],"nested":{"unused":true}}"#).unwrap();
assert_eq!(h.version, Some(1));
assert_eq!(h.images, Some(vec!["abc".into()]));
}
#[test]
fn version_index_preserves_lenient_defaults_and_writes_compact_auto_flag() {
let index = read_version_index(br#"{"extra":true,"versions":[{"id":"v1","time":7,"auto":false,"images":["a",3]},{}]}"#).unwrap();
assert_eq!(index.versions.len(), 2);
assert_eq!(index.versions[0].images, vec!["a"]);
assert_eq!(index.versions[1], VersionEntry::default());
let encoded: Value = serde_json::from_slice(&write_version_index(&index).unwrap()).unwrap();
assert!(encoded["versions"][0].get("auto").is_none());
assert_eq!(encoded["versions"][0]["time"], 7);
}
#[test]
fn branch_index_uses_native_camel_case_and_tolerates_invalid_optional_fields() {
let index =
read_branch_index(br#"{"branches":[{"id":"b1","client":4294967296,"state":"unknown","baseImages":["a",false],"headImages":["b"]},{}]}"#)
.unwrap();
let first = &index.branches[0];
assert_eq!(first.client, 0);
assert_eq!(first.state, BranchState::Active);
assert_eq!(first.base_images, vec!["a"]);
assert_eq!(first.head_images, vec!["b"]);
let encoded = serde_json::to_value(&index).unwrap();
assert_eq!(encoded["branches"][0]["baseImages"][0], "a");
assert!(encoded["branches"][0].get("base_images").is_none());
}
#[test]
fn document_limit_keeps_compressible_files_and_caps_expansion() {
const MB: u64 = 1024 * 1024;
assert_eq!(document_limit(0, 0), MAX_MEMBER);
assert_eq!(document_limit(MB, 2 * MB), MAX_MEMBER);
assert_eq!(document_limit(u64::MAX, MB), MAX_MEMBER);
assert_eq!(document_limit(MAX_DOCUMENT, MAX_DOCUMENT), MAX_DOCUMENT);
assert_eq!(document_limit(244_362_923, 260 * MB), 244_362_923 * DOCUMENT_RATIO);
}
#[test]
fn read_budget_enforces_member_and_archive_totals() {
let bytes = write_archive([
Member { name: "one", bytes: b"12345678", compression: Compression::Stored },
Member { name: "two", bytes: b"abcdefgh", compression: Compression::Stored },
])
.unwrap();
let mut archive = Archive::open(&bytes, ArchiveLimits { max_entries: 4, max_total_bytes: 128 }).unwrap();
let mut budget = ReadBudget::new(10);
assert_eq!(budget.read(&mut archive, "one", 16).unwrap(), b"12345678");
assert!(budget.exceeds_remaining(&mut archive, "two"));
assert!(budget.exhausted_message().contains("contents together pass 10 bytes"));
assert!(budget.read(&mut archive, "two", 16).unwrap_err().to_string().contains("contents together pass 10 bytes"));
let mut member_budget = ReadBudget::new(100);
assert!(member_budget.read(&mut archive, "two", 4).unwrap_err().to_string().contains("two is too large"));
assert_eq!(member_budget.read(&mut archive, "two", 16).unwrap(), b"abcdefgh");
}
#[test]
fn newer_version_is_reported_before_document_decode() {
assert_eq!(check_version(&Header { version: Some(2), images: None }), Err(NewerVersion(2)));
assert_eq!(check_version(&Header { version: Some(u64::MAX), images: None }), Err(NewerVersion(u32::MAX)));
#[derive(Deserialize)]
struct Payload {
document: u32,
}
let text = r#"{"version":2,"document":{"wrong":"type"}}"#;
assert!(matches!(read_document_json::<Payload>(text), Err(ReadDocumentError::NewerVersion(NewerVersion(2)))));
let (payload, header) = read_document_json::<Payload>(r#"{"version":1,"imageIndex":[{"hash":"a"}],"document":5}"#).unwrap();
assert_eq!(payload.document, 5);
assert_eq!(header.images, Some(vec!["a".into()]));
}
#[test]
fn writer_flattens_document_fields() {
let doc = serde_json::json!({"name":"example"});
let mut bytes = Vec::new();
write_document_json(&doc, &[], &mut bytes).unwrap();
let v: Value = serde_json::from_slice(&bytes).unwrap();
assert_eq!(v["format"], FORMAT);
assert_eq!(v["version"], VERSION);
assert_eq!(v["name"], "example");
}
#[test]
fn preview_document_reads_native_page_background_and_kind() {
let doc = read_preview_document(br#"{"pages":[7],"nodes":{"7":{"background":{"r":0.1}}},"kind":"board","unrelated":true}"#).unwrap();
assert_eq!(doc.pages, vec![7]);
assert_eq!(doc.nodes["7"].background.as_ref().and_then(|v| v.get("r")).and_then(Value::as_f64), Some(0.1));
assert_eq!(doc.kind, PreviewKind::Board);
assert_eq!(read_preview_document(b"{}").unwrap(), PreviewDocument::default());
assert!(read_preview_document(br#"{"kind":"unknown"}"#).is_err());
}
}
/// Limits for the native ZIP package reader.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct ArchiveLimits {
pub max_entries: u64,
pub max_total_bytes: u64,
}
/// A bounded reader for a native `.figcraft` ZIP package.
pub struct Archive<'a> {
inner: craft_zip::Archive<'a>,
}
impl<'a> Archive<'a> {
pub fn open(bytes: &'a [u8], limits: ArchiveLimits) -> Result<Self, craft_zip::Error> {
let inner = craft_zip::Archive::open(bytes, craft_zip::Limits { max_entries: limits.max_entries, max_total_bytes: limits.max_total_bytes })?;
Ok(Self { inner })
}
pub fn names(&self) -> impl Iterator<Item = std::borrow::Cow<'_, str>> {
self.inner.names()
}
pub fn has_duplicate_names(&self) -> bool {
self.inner.has_duplicate_names()
}
pub fn contains(&self, name: &str) -> bool {
self.inner.contains(name)
}
pub fn declared_size(&mut self, name: &str) -> Option<u64> {
self.inner.declared_size(name)
}
pub fn compressed_size(&mut self, name: &str) -> Option<u64> {
self.inner.compressed_size(name)
}
pub fn read(&mut self, name: &str, max_bytes: u64) -> Result<Option<Vec<u8>>, craft_zip::Error> {
self.inner.read(name, max_bytes)
}
pub fn budget_used(&self) -> u64 {
self.inner.budget().used()
}
}
/// One member to write into a native ZIP package.
#[derive(Clone, Copy, Debug)]
pub struct Member<'a> {
pub name: &'a str,
pub bytes: &'a [u8],
pub compression: craft_zip::Compression,
}
/// Write a deterministic native ZIP package using the shared ZIP writer.
pub fn write_archive<'a>(members: impl IntoIterator<Item = Member<'a>>) -> Result<Vec<u8>, craft_zip::Error> {
let mut writer = craft_zip::Writer::new();
for member in members {
writer.add(member.name, member.bytes, member.compression)?;
}
writer.finish()
}
#[cfg(test)]
mod archive_tests {
use super::*;
#[test]
fn bounded_archive_reader_and_writer_round_trip_members() {
let bytes =
write_archive([Member { name: "document.json", bytes: br#"{"version":1}"#, compression: craft_zip::Compression::Deflated }]).unwrap();
let mut archive = Archive::open(&bytes, ArchiveLimits { max_entries: 4, max_total_bytes: 128 }).unwrap();
assert!(archive.contains("document.json"));
assert_eq!(archive.read("document.json", 32).unwrap(), Some(br#"{"version":1}"#.to_vec()));
assert_eq!(archive.budget_used(), 13);
}
#[test]
fn archive_reader_enforces_entry_and_total_limits() {
let bytes = write_archive([Member { name: "document.json", bytes: b"123456789", compression: craft_zip::Compression::Deflated }]).unwrap();
let mut small_entry = Archive::open(&bytes, ArchiveLimits { max_entries: 4, max_total_bytes: 100 }).unwrap();
assert!(small_entry.read("document.json", 8).is_err());
let mut small_total = Archive::open(&bytes, ArchiveLimits { max_entries: 4, max_total_bytes: 8 }).unwrap();
assert!(small_total.read("document.json", 100).is_err());
}
}
/// A native archive writer that keeps the streaming document serializer out of the consumer.
pub struct ArchiveWriter {
inner: craft_zip::Writer,
}
impl ArchiveWriter {
pub fn new() -> Self {
Self { inner: craft_zip::Writer::new() }
}
pub fn add(&mut self, name: &str, bytes: &[u8], compression: craft_zip::Compression) -> Result<(), craft_zip::Error> {
self.inner.add(name, bytes, compression)
}
pub fn add_document_json<D: Serialize>(&mut self, name: &str, document: &D, images: &[ImageIndexEntry]) -> Result<(), ArchiveWriteError> {
self.inner
.add_with(name, craft_zip::Compression::Level(3), |w| write_document_json(document, images, w).map_err(std::io::Error::other))
.map_err(ArchiveWriteError::Archive)
}
pub fn finish(self) -> Result<Vec<u8>, craft_zip::Error> {
self.inner.finish()
}
}
impl Default for ArchiveWriter {
fn default() -> Self {
Self::new()
}
}
#[derive(Debug, thiserror::Error)]
pub enum ArchiveWriteError {
#[error("could not serialize native document JSON: {0}")]
Json(#[from] serde_json::Error),
#[error("could not write native archive: {0}")]
Archive(#[from] craft_zip::Error),
}
#[cfg(test)]
mod streaming_writer_tests {
use super::*;
#[test]
fn native_writer_streams_flat_document_into_archive() {
let document = serde_json::json!({"name":"streamed"});
let mut writer = ArchiveWriter::new();
writer.add_document_json("document.json", &document, &[]).unwrap();
let bytes = writer.finish().unwrap();
let mut archive = Archive::open(&bytes, ArchiveLimits { max_entries: 4, max_total_bytes: 4096 }).unwrap();
let json = archive.read("document.json", 1024).unwrap().unwrap();
let value: Value = serde_json::from_slice(&json).unwrap();
assert_eq!(value["name"], "streamed");
assert_eq!(value["format"], FORMAT);
}
}
/// ZIP compression modes for native archive members.
pub use craft_zip::Compression;
/// A native ZIP reader for seekable sources that should not be copied into memory first.
pub struct SeekArchive<R: std::io::Read + std::io::Seek> {
inner: zip::ZipArchive<R>,
}
impl<R: std::io::Read + std::io::Seek> SeekArchive<R> {
pub fn open(reader: R, max_entries: u64) -> Result<Self, craft_zip::Error> {
let inner = zip::ZipArchive::new(reader).map_err(|e| craft_zip::Error::NotZip(e.to_string()))?;
let count = inner.len() as u64;
if count > max_entries {
return Err(craft_zip::Error::TooManyEntries { declared: count, limit: max_entries });
}
Ok(Self { inner })
}
pub fn contains(&self, name: &str) -> bool {
self.inner.index_for_name(name).is_some()
}
pub fn names(&self) -> Vec<String> {
self.inner.file_names().filter_map(Result::ok).map(|n| n.into_owned()).collect()
}
pub fn declared_size(&mut self, name: &str) -> Option<u64> {
self.inner.index_for_name(name).and_then(|i| self.inner.by_index_raw(i).ok().map(|f| f.size()))
}
pub fn read(&mut self, name: &str, max_bytes: u64) -> Result<Option<Vec<u8>>, craft_zip::Error> {
let Some(index) = self.inner.index_for_name(name) else { return Ok(None) };
let mut file = self.inner.by_index(index).map_err(|e| craft_zip::Error::Entry { name: name.to_owned(), msg: e.to_string() })?;
if file.size() > max_bytes {
return Err(craft_zip::Error::EntryTooLarge { name: name.to_owned(), limit: max_bytes });
}
let mut bytes = Vec::new();
let mut limited = std::io::Read::take(&mut file, max_bytes.saturating_add(1));
let read = std::io::Read::read_to_end(&mut limited, &mut bytes);
if let Err(error) = read {
return Err(craft_zip::Error::Entry { name: name.to_owned(), msg: error.to_string() });
}
if bytes.len() as u64 > max_bytes {
return Err(craft_zip::Error::EntryTooLarge { name: name.to_owned(), limit: max_bytes });
}
Ok(Some(bytes))
}
}
/// Shared access contract implemented by in-memory and seekable native archive readers.
pub trait NativeArchive {
fn contains(&self, name: &str) -> bool;
fn names(&self) -> Vec<String>;
fn declared_size(&mut self, name: &str) -> Option<u64>;
fn compressed_size(&mut self, name: &str) -> Option<u64>;
fn read_member(&mut self, name: &str, max_bytes: u64) -> Result<Option<Vec<u8>>, craft_zip::Error>;
}
impl NativeArchive for Archive<'_> {
fn contains(&self, name: &str) -> bool {
Archive::contains(self, name)
}
fn names(&self) -> Vec<String> {
Archive::names(self).map(|n| n.into_owned()).collect()
}
fn declared_size(&mut self, name: &str) -> Option<u64> {
Archive::declared_size(self, name)
}
fn compressed_size(&mut self, name: &str) -> Option<u64> {
Archive::compressed_size(self, name)
}
fn read_member(&mut self, name: &str, max_bytes: u64) -> Result<Option<Vec<u8>>, craft_zip::Error> {
Archive::read(self, name, max_bytes)
}
}
impl<R: std::io::Read + std::io::Seek> NativeArchive for SeekArchive<R> {
fn contains(&self, name: &str) -> bool {
SeekArchive::contains(self, name)
}
fn names(&self) -> Vec<String> {
SeekArchive::names(self)
}
fn declared_size(&mut self, name: &str) -> Option<u64> {
SeekArchive::declared_size(self, name)
}
fn compressed_size(&mut self, name: &str) -> Option<u64> {
self.inner.index_for_name(name).and_then(|i| self.inner.by_index_raw(i).ok().map(|f| f.compressed_size()))
}
fn read_member(&mut self, name: &str, max_bytes: u64) -> Result<Option<Vec<u8>>, craft_zip::Error> {
SeekArchive::read(self, name, max_bytes)
}
}
#[cfg(test)]
mod seek_archive_tests {
use super::*;
#[test]
fn seekable_reader_matches_bounded_in_memory_reader() {
let bytes = write_archive([Member { name: "document.json", bytes: b"payload", compression: Compression::Stored }]).unwrap();
let mut reader = SeekArchive::open(std::io::Cursor::new(bytes), 4).unwrap();
assert!(reader.contains("document.json"));
assert_eq!(reader.read_member("document.json", 16).unwrap(), Some(b"payload".to_vec()));
assert_eq!(reader.declared_size("document.json"), Some(7));
assert!(reader.read_member("document.json", 3).is_err());
}
}
/// Largest individual ZIP member read by the native format.
pub const MAX_MEMBER: u64 = 512 * 1024 * 1024;
/// The document expansion ratio that its compressed size may claim.
pub const DOCUMENT_RATIO: u64 = 16;
#[cfg(not(target_pointer_width = "32"))]
pub const MAX_DOCUMENT: u64 = 4 * 1024 * 1024 * 1024;
#[cfg(target_pointer_width = "32")]
pub const MAX_DOCUMENT: u64 = 1024 * 1024 * 1024;
/// Upper bound for the expanded document member based on both the archive and member policy.
/// The floor preserves support for large but highly compressible documents; the ceiling prevents
/// a tiny archive from claiming an unbounded expansion.
pub fn document_limit(packed: u64, archive_bytes: u64) -> u64 {
packed.min(archive_bytes).saturating_mul(DOCUMENT_RATIO).clamp(MAX_MEMBER, MAX_DOCUMENT)
}
/// Most version snapshots kept on save and read on open.
pub const MAX_VERSIONS: usize = 100;
/// Maximum version and branch name lengths, in Unicode scalar values.
pub const MAX_VERSION_NAME: usize = 200;
pub const MAX_VERSION_DESCRIPTION: usize = 2000;
/// Maximum bytes of an index and all version snapshots read.
pub const MAX_VERSION_INDEX: u64 = 16 * 1024 * 1024;
pub const MAX_VERSION_BYTES: u64 = 1024 * 1024 * 1024;
/// Maximum images read and maximum combined image bytes.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct ImageBudget {
pub images: usize,
pub bytes: u64,
}
pub const IMAGE_BUDGET: ImageBudget = ImageBudget { images: 20_000, bytes: 4 * 1024 * 1024 * 1024 };
/// Maximum branch histories kept.
pub const MAX_BRANCHES: usize = 100;
/// The branch index member.
pub const BRANCH_INDEX: &str = "branches/index.json";
/// Maximum uncompressed bytes read from one native archive in total.
#[cfg(not(target_pointer_width = "32"))]
pub const MAX_UNPACKED: u64 = 6 * 1024 * 1024 * 1024;
#[cfg(target_pointer_width = "32")]
pub const MAX_UNPACKED: u64 = 2 * 1024 * 1024 * 1024;
/// Native-format errors shared with the consumer's document mapping.
#[derive(Debug, PartialEq, Eq)]
pub enum FormatError {
Io(String),
Corrupt(String),
Newer(u32),
}
impl std::fmt::Display for FormatError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::Io(e) => write!(f, "{e}"),
Self::Corrupt(e) => write!(f, "not a valid FigCraft file: {e}"),
Self::Newer(v) => write!(f, "this file was saved by a newer FigCraft (format version {v})"),
}
}
}
impl std::error::Error for FormatError {}
/// Tracks the total bytes unpacked from one native archive across its document, images, library,
/// history, and branch members.
#[derive(Clone, Debug)]
pub struct ReadBudget {
left: u64,
total: u64,
}
impl ReadBudget {
pub fn new(total: u64) -> Self {
Self { left: total, total }
}
fn passed(&self) -> String {
match self.total / (1024 * 1024) {
0 => format!("too large: the file's contents together pass {} bytes", self.total),
mb => format!("too large: the file's contents together pass {mb} MB"),
}
}
/// Whether the member's declared uncompressed size exceeds what remains in this budget.
pub fn exceeds_remaining(&self, archive: &mut impl NativeArchive, name: &str) -> bool {
archive.declared_size(name).is_some_and(|size| size > self.left)
}
/// Human-readable reason for leaving out a member after the archive-wide limit is spent.
pub fn exhausted_message(&self) -> String {
self.passed()
}
/// Read one native member within its own size limit and the remaining archive-wide budget.
/// A failed read that consumed a member is charged at its declared size.
pub fn read(&mut self, archive: &mut impl NativeArchive, name: &str, limit: u64) -> Result<Vec<u8>, FormatError> {
let declared = archive.declared_size(name);
if declared.is_some_and(|size| size > self.left && size <= limit) {
return Err(FormatError::Corrupt(format!("{name}: {}", self.passed())));
}
let cap = limit.min(self.left);
let size = declared.unwrap_or(0);
let result = match archive.read_member(name, cap) {
Ok(Some(bytes)) => Ok(bytes),
Ok(None) => Err(FormatError::Corrupt(format!("{name}: not found"))),
Err(error) if error.is_limit() => Err(FormatError::Corrupt(format!("{name} is too large"))),
Err(error) => Err(FormatError::Corrupt(format!("{name}: {error}"))),
};
if size <= cap {
self.left = self.left.saturating_sub(result.as_ref().map_or(size, |bytes| bytes.len() as u64));
}
result
}
}
/// Whether `id` can name a version or branch: 1–64 ASCII letters, digits, `-` and `_`.
pub fn is_valid_version_id(id: &str) -> bool {
(1..=64).contains(&id.len()) && id.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'-' || b == b'_')
}
/// Clip text to at most `max` Unicode scalar values.
pub fn clip(s: &str, max: usize) -> String {
s.chars().take(max).collect()
}
+205
View File
@@ -0,0 +1,205 @@
//! Wire schema and member limits for published libraries embedded in a native project archive.
use serde::{Deserialize, Serialize};
use std::collections::{BTreeMap, BTreeSet};
pub const MANIFEST: &str = "library/manifest.json";
pub const DOCUMENT: &str = "library/document.json";
pub const IMAGES_PREFIX: &str = "library/images/";
pub const MAX_MANIFEST_BYTES: u64 = 16 * 1024 * 1024;
pub const MAX_IMAGE_BYTES: u64 = 1024 * 1024 * 1024;
pub const MAX_ID_CHARS: usize = 64;
pub const MAX_NAME_CHARS: usize = 200;
pub const MAX_DESCRIPTION_CHARS: usize = 2000;
/// Native library manifest, independent of the consumer's document model.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
#[serde(default)]
pub struct Manifest {
pub id: String,
pub name: String,
pub version: u64,
pub description: String,
pub time: u64,
pub components: Vec<Component>,
pub styles: Vec<Style>,
pub collections: Vec<Collection>,
pub variables: Vec<Variable>,
}
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct Component {
pub id: u64,
#[serde(default)]
pub name: String,
#[serde(default)]
pub set: bool,
#[serde(default)]
pub version: u64,
#[serde(default)]
pub published: bool,
}
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
#[serde(default)]
pub struct Style {
pub id: String,
pub name: String,
#[serde(rename = "type")]
pub kind: String,
pub version: u64,
pub published: bool,
}
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
#[serde(default)]
pub struct Collection {
pub id: String,
pub name: String,
pub version: u64,
pub published: bool,
}
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
#[serde(default)]
pub struct Variable {
pub id: String,
pub name: String,
pub collection: String,
#[serde(rename = "type")]
pub kind: String,
pub version: u64,
pub published: bool,
}
/// Decode the native published-library manifest.
pub fn read_manifest(bytes: &[u8]) -> Result<Manifest, serde_json::Error> {
serde_json::from_slice(bytes)
}
/// Encode the native published-library manifest.
pub fn write_manifest(manifest: &Manifest) -> Result<Vec<u8>, serde_json::Error> {
serde_json::to_vec(manifest)
}
/// Whether `id` is a valid stable library id in the native manifest.
pub fn is_valid_id(id: &str) -> bool {
(1..=MAX_ID_CHARS).contains(&id.len()) && id.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'-' || b == b'_')
}
/// Clip a library display string to its native-format scalar-value limit.
pub fn clip_display(s: &str, max_chars: usize) -> String {
s.chars().take(max_chars).collect()
}
/// Write the complete published-library member group into a native archive. The consumer maps
/// its document to the neutral manifest and image index; path layout, compression, and shared
/// image reuse stay here.
pub fn write_members<'a, D: Serialize>(
writer: &mut super::ArchiveWriter,
manifest: &Manifest,
document: &D,
image_index: &[super::ImageIndexEntry],
already_written: &BTreeSet<String>,
images: impl IntoIterator<Item = (&'a str, &'a [u8])>,
) -> Result<(), super::ArchiveWriteError> {
let manifest_bytes = write_manifest(manifest)?;
writer.add(MANIFEST, &manifest_bytes, super::Compression::Level(3))?;
writer.add_document_json(DOCUMENT, document, image_index)?;
for (hash, bytes) in images {
if already_written.contains(hash) || !valid_image_key(hash) {
continue;
}
writer.add(&format!("{IMAGES_PREFIX}{hash}"), bytes, super::Compression::Stored)?;
}
Ok(())
}
/// Read only published-library image resources selected by the consumer's document model.
/// Missing and oversized images are omitted, leaving the consumer to render its established
/// placeholder. The shared layer handles path choice, safe member names, and byte accounting.
pub fn read_image_resources(
archive: &mut impl super::NativeArchive,
hashes: impl IntoIterator<Item = String>,
already_available: &BTreeSet<String>,
unpacked: &mut super::ReadBudget,
) -> BTreeMap<String, Vec<u8>> {
let mut remaining = MAX_IMAGE_BYTES;
let mut images = BTreeMap::new();
for hash in hashes {
if already_available.contains(&hash) || !valid_image_key(&hash) {
continue;
}
let preferred = format!("{IMAGES_PREFIX}{hash}");
let fallback = format!("images/{hash}");
let Some(name) = [preferred, fallback].into_iter().find(|name| archive.contains(name)) else { continue };
let Ok(bytes) = unpacked.read(archive, &name, remaining.min(super::MAX_MEMBER)) else { continue };
remaining = remaining.saturating_sub(bytes.len() as u64);
images.insert(hash, bytes);
}
images
}
fn valid_image_key(key: &str) -> bool {
(1..=128).contains(&key.len()) && key.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'-' || b == b'_')
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn manifest_wire_names_defaults_and_round_trip_match_native_contract() {
let json = r#"{"id":"lib-1","components":[{"id":12,"set":true}],"styles":[{"id":"s","type":"paint"}],"collections":[{"id":"c"}],"variables":[{"id":"v","collection":"c","type":"color"}]}"#;
let manifest = read_manifest(json.as_bytes()).unwrap();
assert_eq!(manifest.components[0].id, 12);
assert_eq!(manifest.styles[0].kind, "paint");
assert_eq!(manifest.variables[0].kind, "color");
let encoded: serde_json::Value = serde_json::from_slice(&write_manifest(&manifest).unwrap()).unwrap();
assert_eq!(encoded["styles"][0]["type"], "paint");
assert!(encoded["styles"][0].get("kind").is_none());
assert_eq!(encoded["variables"][0]["type"], "color");
}
#[test]
fn library_id_and_display_limits_are_format_level() {
assert!(is_valid_id(&"a".repeat(MAX_ID_CHARS)));
assert!(!is_valid_id(&"a".repeat(MAX_ID_CHARS + 1)));
assert!(!is_valid_id("../bad"));
assert_eq!(clip_display("aé🙂b", 2), "aé");
}
#[test]
fn library_member_writer_and_reader_own_resource_layout_and_budgets() {
let mut writer = super::super::ArchiveWriter::new();
let manifest = Manifest { id: "library-1".into(), ..Manifest::default() };
let already_written = BTreeSet::from(["existing".to_string()]);
write_members(
&mut writer,
&manifest,
&serde_json::json!({"name":"library snapshot"}),
&[],
&already_written,
[("stored", &b"library bytes"[..]), ("existing", &b"duplicate"[..]), ("../bad", &b"hostile"[..])],
)
.unwrap();
writer.add("images/fallback", b"fallback bytes", super::super::Compression::Stored).unwrap();
let bytes = writer.finish().unwrap();
let mut archive = super::super::Archive::open(&bytes, super::super::ArchiveLimits { max_entries: 8, max_total_bytes: 1024 }).unwrap();
assert!(archive.contains(MANIFEST));
assert!(archive.contains(DOCUMENT));
let manifest_bytes = archive.read(MANIFEST, MAX_MANIFEST_BYTES).unwrap().unwrap();
assert_eq!(read_manifest(&manifest_bytes).unwrap(), manifest);
assert!(archive.contains("library/images/stored"));
assert!(!archive.contains("library/images/existing"));
assert!(!archive.contains("library/images/../bad"));
let available = BTreeSet::from(["existing".to_string()]);
let mut budget = super::super::ReadBudget::new(1024);
let images =
read_image_resources(&mut archive, ["stored".into(), "existing".into(), "fallback".into(), "../bad".into()], &available, &mut budget);
assert_eq!(images["stored"], b"library bytes");
assert_eq!(images["fallback"], b"fallback bytes");
assert!(!images.contains_key("existing"));
assert!(!images.contains_key("../bad"));
}
}
+19
View File
@@ -0,0 +1,19 @@
[package]
name = "craft-file-formats"
description = "Shared bounded file signature and extension resolution for Craft applications"
version.workspace = true
edition.workspace = true
license.workspace = true
repository.workspace = true
rust-version.workspace = true
[dependencies]
craft-eps = { workspace = true }
craft-idml = { workspace = true }
craft-svg = { workspace = true }
craft-zip = { workspace = true }
serde = { workspace = true }
serde_json = { workspace = true }
[lints]
workspace = true
+269
View File
@@ -0,0 +1,269 @@
//! Bounded file kind detection and extension resolution shared by Craft applications.
//!
//! This crate identifies a format; it does not parse, validate, or decode the file.
//! Callers remain responsible for choosing which identified formats their product supports.
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
#![forbid(unsafe_code)]
/// A supported file family, independent of the application model that consumes it.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Format {
Pdf,
Eps,
PostScript,
Illustrator,
Dxf,
Svg,
/// Gzip-compressed SVG. Kept distinct so writers do not place plain SVG under `.svgz`.
Svgz,
Png,
Jpeg,
Bmp,
Gif,
Tiff,
WebP,
Heif,
Ase,
Psd,
Affinity,
Ora,
Kra,
Xcf,
Pdn,
Raw,
Pcraft,
Idml,
DesignCraft,
/// Legacy DesignCraft documents serialized as one JSON object.
DesignCraftJson,
Indd,
Docx,
/// Legacy OLE Compound File Word document; identified by its extension only.
LegacyDoc,
Rtf,
Xlsx,
TaggedText,
Pptx,
PlainText,
Csv,
Tsv,
/// Legacy binary Excel workbooks, identified by extension only.
LegacyExcel,
Gcode,
Studio,
StencilCraft,
}
/// Resolve a name and file bytes to a format. Strong signatures take precedence over
/// extension hints. Only format-specific bounded probes and extension tables live here.
pub fn detect(name: &str, bytes: &[u8]) -> Option<Format> {
if craft_idml::is_idml(bytes) {
return Some(Format::Idml);
}
if craft_zip::stored_mimetype(bytes) == Some(b"application/vnd.designcraft+zip") || designcraft_zip_has_document(bytes) {
return Some(Format::DesignCraft);
}
if is_designcraft_json(bytes) {
return Some(Format::DesignCraftJson);
}
if bytes.starts_with(&INDD_SIGNATURE) {
return Some(Format::Indd);
}
if let Some(found) = craft_eps::sniff(bytes) {
return Some(match (found.kind, found.illustrator) {
(_, true) => Format::Illustrator,
(craft_eps::Kind::Pdf, _) => Format::Pdf,
(craft_eps::Kind::Eps, _) => Format::Eps,
(craft_eps::Kind::PostScript, _) => Format::PostScript,
});
}
if bytes.starts_with(b"8BPS") {
return Some(Format::Psd);
}
if bytes.starts_with(b"ASEF") {
return Some(Format::Ase);
}
if bytes.starts_with(b"PDN3") {
return Some(Format::Pdn);
}
if bytes.starts_with(b"gimp xcf ") || gzipped_xcf(name, bytes) {
return Some(Format::Xcf);
}
if bytes.starts_with(b"\0\xffKA") {
return Some(Format::Affinity);
}
if let Some(raster) = raster_signature(bytes) {
return Some(raster);
}
if bytes.starts_with(b"silhouette04;") || bytes.starts_with(b"silhouette05;") {
return Some(Format::Studio);
}
let tagged = bytes.strip_prefix(b"\xef\xbb\xbf").unwrap_or(bytes).trim_ascii_start();
if tagged.starts_with(b"<ASCII-") || tagged.starts_with(b"<UNICODE-") || tagged.starts_with(b"<ANSI-") {
return Some(Format::TaggedText);
}
if bytes.trim_ascii_start().starts_with(b"{\\rtf") {
return Some(Format::Rtf);
}
if craft_svg::sniff::is_svgz(bytes)
&& let Ok(text) = craft_svg::svgz::text(bytes, 64 * 1024 * 1024)
&& craft_svg::sniff::is_svg(text.as_bytes())
{
return Some(Format::Svgz);
}
if craft_svg::sniff::is_svg(bytes) {
return Some(Format::Svg);
}
if let Some(ext) = extension(name)
&& let Some(format) = from_extension(ext)
{
return Some(format);
}
let head = bytes.get(..4096).unwrap_or(bytes);
if dxf_ascii_prefix(head) || head.starts_with(b"AutoCAD Binary DXF\r\n\x1a\0") {
return Some(Format::Dxf);
}
None
}
/// DesignCraft's older ZIPs predate their leading `mimetype`; they are identified by the
/// `document.json` member. The directory is bounded before it is indexed and no entry is inflated.
fn designcraft_zip_has_document(bytes: &[u8]) -> bool {
if !bytes.starts_with(b"PK") {
return false;
}
craft_zip::Archive::open(bytes, craft_zip::Limits { max_entries: 100_000, max_total_bytes: 0 })
.is_ok_and(|archive| archive.contains("document.json"))
}
/// Read only a bounded prefix, stopping as soon as the model's required top-level keys have
/// appeared. This distinguishes legacy DesignCraft JSON from arbitrary JSON without decoding the
/// document or walking its arrays and assets.
fn is_designcraft_json(bytes: &[u8]) -> bool {
const LIMIT: usize = 1 << 20;
const REQUIRED: u16 = (1 << 10) - 1;
const KEYS: [&str; 10] = ["title", "settings", "spreads", "parents", "layers", "stories", "styles", "swatches", "sections", "next_id"];
struct Probe;
impl<'de> serde::de::Visitor<'de> for Probe {
type Value = bool;
fn expecting(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter.write_str("a DesignCraft document object")
}
fn visit_map<A: serde::de::MapAccess<'de>>(self, mut map: A) -> Result<Self::Value, A::Error> {
let mut found = 0u16;
while let Some(key) = map.next_key::<String>()? {
if let Some(index) = KEYS.iter().position(|candidate| *candidate == key) {
found |= 1 << index;
}
map.next_value::<serde::de::IgnoredAny>()?;
if found == REQUIRED {
return Ok(true);
}
}
Ok(false)
}
}
use serde::de::DeserializeSeed;
struct Seed;
impl<'de> DeserializeSeed<'de> for Seed {
type Value = bool;
fn deserialize<D: serde::Deserializer<'de>>(self, deserializer: D) -> Result<Self::Value, D::Error> {
deserializer.deserialize_map(Probe)
}
}
let prefix = bytes.get(..bytes.len().min(LIMIT)).unwrap_or(bytes);
let mut deserializer = serde_json::Deserializer::from_slice(prefix);
Seed.deserialize(&mut deserializer).unwrap_or(false)
}
/// Resolve a file extension to a family, case-insensitively.
pub fn from_extension(ext: &str) -> Option<Format> {
match ext.trim_start_matches('.').to_ascii_lowercase().as_str() {
"pdf" => Some(Format::Pdf),
"eps" => Some(Format::Eps),
"ps" => Some(Format::PostScript),
"ai" => Some(Format::Illustrator),
"dxf" => Some(Format::Dxf),
"svg" => Some(Format::Svg),
"svgz" => Some(Format::Svgz),
"png" => Some(Format::Png),
"jpg" | "jpeg" => Some(Format::Jpeg),
"bmp" => Some(Format::Bmp),
"gif" => Some(Format::Gif),
"tif" | "tiff" => Some(Format::Tiff),
"webp" => Some(Format::WebP),
"heic" | "heif" => Some(Format::Heif),
"ase" => Some(Format::Ase),
"psd" | "psb" => Some(Format::Psd),
"afdesign" | "afphoto" | "afpub" => Some(Format::Affinity),
"ora" => Some(Format::Ora),
"kra" => Some(Format::Kra),
"xcf" => Some(Format::Xcf),
"pdn" => Some(Format::Pdn),
"dng" | "3fr" | "ari" | "arw" | "bay" | "cap" | "cr2" | "cr3" | "dcs" | "dcr" | "drf" | "eip" | "erf" | "fff" | "gpr" | "iiq" | "k25"
| "kdc" | "mdc" | "mef" | "mos" | "mrw" | "nef" | "nrw" | "obm" | "orf" | "pef" | "ptx" | "pxn" | "r3d" | "raf" | "raw" | "rwl" | "rw2"
| "rwz" | "sr2" | "srf" | "sti" | "x3f" => Some(Format::Raw),
"pcraft" => Some(Format::Pcraft),
"idml" => Some(Format::Idml),
"designcraft" | "dcdoc" => Some(Format::DesignCraft),
"indd" | "indt" => Some(Format::Indd),
"docx" => Some(Format::Docx),
"doc" => Some(Format::LegacyDoc),
"rtf" => Some(Format::Rtf),
"xlsx" => Some(Format::Xlsx),
"pptx" => Some(Format::Pptx),
"txt" | "text" | "md" => Some(Format::PlainText),
"csv" => Some(Format::Csv),
"tsv" | "tab" => Some(Format::Tsv),
"xls" | "xlsm" => Some(Format::LegacyExcel),
"studio" | "studio3" => Some(Format::Studio),
"stencilcraft" => Some(Format::StencilCraft),
"gcode" | "nc" => Some(Format::Gcode),
_ => None,
}
}
const INDD_SIGNATURE: [u8; 16] = [0x06, 0x06, 0xED, 0xF5, 0xD8, 0x1D, 0x46, 0xE5, 0xBD, 0x31, 0xEF, 0xE7, 0xFE, 0x74, 0xB7, 0x1D];
fn extension(name: &str) -> Option<&str> {
Some(name.rsplit(['/', '\\']).next()?.rsplit_once('.')?.1)
}
fn gzipped_xcf(name: &str, bytes: &[u8]) -> bool {
let lower = name.rsplit(['/', '\\']).next().unwrap_or(name).to_ascii_lowercase();
bytes.starts_with(&[0x1f, 0x8b]) && (lower.ends_with(".xcf.gz") || lower.ends_with(".xcfgz"))
}
fn dxf_ascii_prefix(bytes: &[u8]) -> bool {
let text = String::from_utf8_lossy(bytes);
let mut lines = text.lines().map(str::trim);
matches!((lines.next(), lines.next(), lines.next(), lines.next()), (Some("0"), Some("SECTION"), Some("2"), Some(section)) if matches!(section, "HEADER" | "CLASSES" | "TABLES" | "BLOCKS" | "ENTITIES" | "OBJECTS"))
}
fn raster_signature(bytes: &[u8]) -> Option<Format> {
let head = bytes.get(..16).unwrap_or(bytes);
if head.starts_with(b"\x89PNG\r\n\x1a\n") {
return Some(Format::Png);
}
if head.starts_with(b"\xff\xd8\xff") {
return Some(Format::Jpeg);
}
if head.starts_with(b"BM") {
return Some(Format::Bmp);
}
if head.starts_with(b"GIF87a") || head.starts_with(b"GIF89a") {
return Some(Format::Gif);
}
if head.starts_with(b"II*\0") || head.starts_with(b"MM\0*") || head.starts_with(b"II+\0") || head.starts_with(b"MM\0+") {
return Some(Format::Tiff);
}
if head.starts_with(b"RIFF") && head.get(8..12) == Some(b"WEBP") {
return Some(Format::WebP);
}
None
}
+22
View File
@@ -0,0 +1,22 @@
[package]
name = "craft-file-import"
description = "Shared format registry and bounded neutral scene import dispatch"
version.workspace = true
edition.workspace = true
license.workspace = true
repository.workspace = true
rust-version.workspace = true
[dependencies]
craft-file-formats = { workspace = true }
craft-raster-codecs = { workspace = true }
craft-svg = { workspace = true }
craft-dxf = { workspace = true }
craft-pdf = { workspace = true, features = ["paths", "write"] }
craft-eps = { workspace = true, features = ["paths"] }
kurbo = { workspace = true }
thiserror = { workspace = true }
vectorcraft-geom = { workspace = true }
[lints]
workspace = true
+405
View File
@@ -0,0 +1,405 @@
//! Shared format selection and bounded decoding into neutral vector scenes or raster pixels.
//!
//! Applications own only the mapping from these generic results into their document models and
//! product-specific placement options. Format detection, supported import capabilities, reader
//! selection, unit normalization, and raster codec dispatch live here.
use kurbo::{Affine, BezPath, PathEl, Point};
pub mod write;
pub use craft_file_formats::Format as DetectedFormat;
/// The maximum encoded input accepted by the import facade.
pub const MAX_INPUT_BYTES: usize = 64 * 1024 * 1024;
pub const MAX_SHAPES: usize = 200_000;
const MM_PER_PT: f64 = 25.4 / 72.0;
/// A product-neutral input family supported by this reader registry.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ImportFormat {
Svg,
Svgz,
Dxf,
Pdf,
Eps,
Raster,
}
/// Reader and writer capabilities for one family in the shared registry.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Capability {
pub format: ImportFormat,
pub detected_formats: &'static [craft_file_formats::Format],
pub extensions: &'static [&'static str],
pub write_extensions: &'static [&'static str],
pub mime_types: &'static [&'static str],
pub raster: bool,
pub vector: bool,
}
/// Format, reader and writer support for callers that build dialogs or query capabilities.
pub const CAPABILITIES: &[Capability] = &[
Capability {
format: ImportFormat::Svg,
detected_formats: &[craft_file_formats::Format::Svg],
extensions: &["svg"],
write_extensions: &["svg"],
mime_types: &["image/svg+xml"],
raster: false,
vector: true,
},
Capability {
format: ImportFormat::Svgz,
detected_formats: &[craft_file_formats::Format::Svgz],
extensions: &["svgz"],
write_extensions: &["svgz"],
mime_types: &["image/svg+xml"],
raster: false,
vector: true,
},
Capability {
format: ImportFormat::Dxf,
detected_formats: &[craft_file_formats::Format::Dxf],
extensions: &["dxf"],
write_extensions: &["dxf"],
mime_types: &["image/vnd.dxf", "application/dxf"],
raster: false,
vector: true,
},
Capability {
format: ImportFormat::Pdf,
detected_formats: &[craft_file_formats::Format::Pdf],
extensions: &["pdf"],
write_extensions: &["pdf"],
mime_types: &["application/pdf"],
raster: false,
vector: true,
},
Capability {
format: ImportFormat::Eps,
detected_formats: &[craft_file_formats::Format::Eps, craft_file_formats::Format::PostScript, craft_file_formats::Format::Illustrator],
extensions: &["eps", "ps", "ai"],
write_extensions: &[],
mime_types: &["application/postscript"],
raster: false,
vector: true,
},
Capability {
format: ImportFormat::Raster,
detected_formats: &[
craft_file_formats::Format::Png,
craft_file_formats::Format::Jpeg,
craft_file_formats::Format::Bmp,
craft_file_formats::Format::Gif,
craft_file_formats::Format::Tiff,
craft_file_formats::Format::WebP,
],
extensions: &["png", "jpg", "jpeg", "bmp", "gif", "tif", "tiff", "webp"],
write_extensions: &["png", "jpg", "jpeg"],
mime_types: &["image/png", "image/jpeg", "image/bmp", "image/gif", "image/tiff", "image/webp"],
raster: true,
vector: false,
},
];
/// A vector path with generic source metadata. `tag` and `layer` are source labels; applications
/// may interpret their own conventions while the geometry and parsing stay shared.
#[derive(Debug, Clone, PartialEq)]
pub struct SceneShape {
pub path: BezPath,
pub tag: Option<String>,
pub class: Option<String>,
pub stroke: Option<String>,
/// Parsed RGB stroke color when the source stroke is a concrete CSS color.
pub stroke_rgb: Option<[u8; 3]>,
pub layer: Option<String>,
}
#[derive(Debug, Clone, PartialEq)]
pub struct VectorScene {
pub format: ImportFormat,
pub width_mm: f64,
pub height_mm: f64,
pub shapes: Vec<SceneShape>,
pub warnings: Vec<String>,
/// Additional warnings omitted by the SVG reader's bounded warning collection.
pub dropped_warnings: usize,
}
#[derive(Debug, Clone)]
pub struct RasterImage {
pub format: ImportFormat,
pub width: u32,
pub height: u32,
/// Straight-alpha RGBA pixels, row-major.
pub rgba: Vec<u8>,
}
#[derive(Debug, Clone)]
pub enum Imported {
Vector(VectorScene),
Raster(RasterImage),
}
#[derive(Debug, Clone, Copy)]
pub struct Limits {
pub max_input_bytes: usize,
pub max_shapes: usize,
pub max_raster_width: u32,
pub max_raster_height: u32,
pub max_raster_pixels: u64,
pub max_raster_alloc_bytes: u64,
}
impl Default for Limits {
fn default() -> Self {
Self {
max_input_bytes: MAX_INPUT_BYTES,
max_shapes: MAX_SHAPES,
max_raster_width: 10_000,
max_raster_height: 10_000,
max_raster_pixels: 16_000_000,
max_raster_alloc_bytes: 256 * 1024 * 1024,
}
}
}
#[derive(Debug, thiserror::Error)]
pub enum Error {
#[error("unrecognized or unsupported import format")]
Unsupported,
#[error("input is {size} bytes; limit is {limit}")]
InputLimit { size: usize, limit: usize },
#[error("{0}")]
Decode(String),
#[error("import produced invalid or non-finite geometry")]
InvalidGeometry,
#[error("import exceeds the configured shape limit")]
ShapeLimit,
#[error("format writer failed: {0}")]
Write(String),
}
impl From<craft_pdf::write::WriteError> for Error {
fn from(error: craft_pdf::write::WriteError) -> Self {
Self::Write(error.to_string())
}
}
/// Resolve detected file kinds to this reader registry. Illustrator files with PDF content use
/// the PDF path reader; PostScript-family files use the EPS/PostScript interpreter.
pub fn format_for(name: &str, bytes: &[u8]) -> Option<ImportFormat> {
use craft_file_formats::Format as F;
match craft_file_formats::detect(name, bytes)? {
F::Svg => Some(ImportFormat::Svg),
F::Svgz => Some(ImportFormat::Svgz),
F::Dxf => Some(ImportFormat::Dxf),
F::Pdf => Some(ImportFormat::Pdf),
F::Illustrator if bytes.starts_with(b"%PDF-") => Some(ImportFormat::Pdf),
F::Eps | F::PostScript | F::Illustrator => Some(ImportFormat::Eps),
F::Png | F::Jpeg | F::Bmp | F::Gif | F::Tiff | F::WebP => Some(ImportFormat::Raster),
_ => None,
}
}
/// Return supported extensions in the same registry used by [`format_for`].
pub fn supported_extensions() -> Vec<&'static str> {
CAPABILITIES.iter().flat_map(|capability| capability.extensions.iter().copied()).collect()
}
/// Raw detected kinds routed to one reader family, for app open-dialog and capability adapters.
pub fn supported_formats(format: ImportFormat) -> &'static [craft_file_formats::Format] {
CAPABILITIES.iter().find(|capability| capability.format == format).map_or(&[], |capability| capability.detected_formats)
}
/// Whether the registry has a writer for an extension.
pub fn supports_write_extension(extension: &str) -> bool {
let extension = extension.trim_start_matches('.');
CAPABILITIES.iter().any(|capability| capability.write_extensions.iter().any(|candidate| candidate.eq_ignore_ascii_case(extension)))
}
/// Whether a family has at least one output writer in the shared registry.
pub fn supports_writer(format: ImportFormat) -> bool {
CAPABILITIES.iter().find(|capability| capability.format == format).is_some_and(|capability| !capability.write_extensions.is_empty())
}
/// Detect, select a reader, and decode the input into a neutral vector scene or RGBA image.
pub fn import(name: &str, bytes: &[u8], limits: Limits) -> Result<Imported, Error> {
if bytes.len() > limits.max_input_bytes {
return Err(Error::InputLimit { size: bytes.len(), limit: limits.max_input_bytes });
}
let format = format_for(name, bytes).ok_or(Error::Unsupported)?;
let imported = match format {
ImportFormat::Svg | ImportFormat::Svgz => import_svg(name, bytes, format, limits),
ImportFormat::Dxf => import_dxf(bytes, format, limits),
ImportFormat::Pdf => import_pdf(bytes, format, limits),
ImportFormat::Eps => import_eps(bytes, format, limits),
ImportFormat::Raster => import_raster(bytes, format, limits),
}?;
if let Imported::Vector(scene) = &imported
&& (!(scene.width_mm.is_finite() && scene.height_mm.is_finite() && scene.width_mm > 0.0 && scene.height_mm > 0.0)
|| scene.shapes.iter().any(|shape| !path_is_finite(&shape.path)))
{
return Err(Error::InvalidGeometry);
}
Ok(imported)
}
#[derive(Debug, Clone, Default)]
struct SvgTag {
data_kind: Option<String>,
class: Option<String>,
}
impl craft_svg::paths::Kind for SvgTag {
const PROPERTIES: &'static [&'static str] = &["data-kind"];
fn of(style: &craft_svg::paths::StyleMap, class: &str) -> Option<Self> {
let data_kind = style.get("data-kind").cloned();
let class = (!class.is_empty()).then(|| class.to_owned());
(data_kind.is_some() || class.is_some()).then_some(Self { data_kind, class })
}
}
fn import_svg(name: &str, bytes: &[u8], format: ImportFormat, limits: Limits) -> Result<Imported, Error> {
let text = craft_svg::svgz::text(bytes, limits.max_input_bytes).map_err(|error| Error::Decode(error.to_string()))?;
let imported = craft_svg::paths::import::<SvgTag>(&text, name).map_err(|error| Error::Decode(error.to_string()))?;
if imported.shapes.len() > limits.max_shapes {
return Err(Error::ShapeLimit);
}
let mut shapes = Vec::with_capacity(imported.shapes.len());
for shape in &imported.shapes {
let path = imported.clipped_path(shape).map_err(|error| Error::Decode(error.to_string()))?;
shapes.push(SceneShape {
path,
tag: shape.kind.data_kind.clone(),
class: shape.kind.class.clone(),
stroke: shape.stroke.clone(),
stroke_rgb: shape.stroke.as_deref().and_then(|value| craft_svg::color::parse_color(value).ok()).map(|color| [color.r, color.g, color.b]),
layer: shape.layer.clone(),
});
}
Ok(Imported::Vector(VectorScene {
format,
width_mm: imported.width_mm,
height_mm: imported.height_mm,
shapes,
warnings: imported.warnings,
dropped_warnings: imported.dropped_warnings,
}))
}
fn import_dxf(bytes: &[u8], format: ImportFormat, limits: Limits) -> Result<Imported, Error> {
let imported = craft_dxf::paths::import(bytes).map_err(|error| Error::Decode(error.to_string()))?;
if imported.paths.len() > limits.max_shapes {
return Err(Error::ShapeLimit);
}
let (width_mm, height_mm, transform) = match imported.bounds {
Some(bounds) => (
(bounds.width() * imported.unit_to_mm).max(1.0),
(bounds.height() * imported.unit_to_mm).max(1.0),
Affine::new([imported.unit_to_mm, 0.0, 0.0, -imported.unit_to_mm, -bounds.x0 * imported.unit_to_mm, bounds.y1 * imported.unit_to_mm]),
),
None => (100.0, 150.0, Affine::IDENTITY),
};
let shapes = imported
.paths
.into_iter()
.map(|path| SceneShape { path: transform * path, tag: None, class: None, stroke: None, stroke_rgb: None, layer: None })
.collect();
Ok(Imported::Vector(VectorScene { format, width_mm, height_mm, shapes, warnings: imported.warnings, dropped_warnings: 0 }))
}
fn import_pdf(bytes: &[u8], format: ImportFormat, limits: Limits) -> Result<Imported, Error> {
let imported = craft_pdf::paths::import_page(
bytes,
0,
craft_pdf::paths::Limits { max_input_bytes: limits.max_input_bytes, max_paths: limits.max_shapes, ..Default::default() },
)
.map_err(|error| Error::Decode(error.to_string()))?;
let page = imported.pages.into_iter().next().ok_or_else(|| Error::Decode("PDF has no pages".into()))?;
let bounds = page.crop_box;
let mut warnings = imported.warnings;
if page.omitted_text > 0 || page.omitted_images > 0 {
warnings.push(format!("PDF omitted {} text and {} image items", page.omitted_text, page.omitted_images));
}
let shapes = page
.paths
.into_iter()
.map(|path| SceneShape { path: Affine::scale(MM_PER_PT) * path, tag: None, class: None, stroke: None, stroke_rgb: None, layer: None })
.collect();
Ok(Imported::Vector(VectorScene {
format,
width_mm: bounds.width() * MM_PER_PT,
height_mm: bounds.height() * MM_PER_PT,
shapes,
warnings,
dropped_warnings: 0,
}))
}
fn import_eps(bytes: &[u8], format: ImportFormat, limits: Limits) -> Result<Imported, Error> {
let imported = craft_eps::paths::import(
bytes,
craft_eps::paths::Limits { max_input_bytes: limits.max_input_bytes, max_paths: limits.max_shapes, ..Default::default() },
)
.map_err(|error| Error::Decode(error.to_string()))?;
let bounds = imported.page_bounds;
let transform = Affine::scale(MM_PER_PT);
let mut warnings = imported.warnings;
if imported.preview_fallback {
warnings.push("embedded raster preview was not imported as paths".into());
}
let shapes = imported
.paths
.into_iter()
.map(|path| SceneShape { path: transform * path, tag: None, class: None, stroke: None, stroke_rgb: None, layer: None })
.collect();
Ok(Imported::Vector(VectorScene {
format,
width_mm: (bounds.width() * MM_PER_PT).max(1.0),
height_mm: (bounds.height() * MM_PER_PT).max(1.0),
shapes,
warnings,
dropped_warnings: 0,
}))
}
fn import_raster(bytes: &[u8], format: ImportFormat, limits: Limits) -> Result<Imported, Error> {
let rgba = craft_raster_codecs::common::decode_rgba(
bytes,
craft_raster_codecs::common::DecodeLimits {
max_file_bytes: limits.max_input_bytes,
max_width: limits.max_raster_width,
max_height: limits.max_raster_height,
max_pixels: limits.max_raster_pixels,
max_alloc_bytes: limits.max_raster_alloc_bytes,
},
)
.map_err(|error| Error::Decode(error.to_string()))?;
let (width, height) = rgba.dimensions();
Ok(Imported::Raster(RasterImage { format, width, height, rgba: rgba.into_raw() }))
}
fn path_is_finite(path: &BezPath) -> bool {
path.elements().iter().all(|element| {
let finite = |point: Point| point.x.is_finite() && point.y.is_finite();
match *element {
PathEl::MoveTo(point) | PathEl::LineTo(point) => finite(point),
PathEl::QuadTo(a, b) => finite(a) && finite(b),
PathEl::CurveTo(a, b, c) => finite(a) && finite(b) && finite(c),
PathEl::ClosePath => true,
}
})
}
#[cfg(test)]
mod format_tests {
use super::*;
#[test]
fn pdf_based_illustrator_is_routed_to_pdf_reader() {
let bytes = b"%PDF-1.7\n/AIPrivateData";
assert_eq!(format_for("illustration.ai", bytes), Some(ImportFormat::Pdf));
}
}
+447
View File
@@ -0,0 +1,447 @@
//! Shared writer selection and serialization for neutral scenes and pixels.
use kurbo::{BezPath, PathEl, Point};
use crate::{CAPABILITIES, Error, ImportFormat};
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum WriteFormat {
Svg,
Svgz,
Dxf,
Pdf,
Png,
Jpeg,
}
#[derive(Debug, Clone, PartialEq)]
pub struct OutputLayer {
/// Product-facing name. SVG stores it as `data-layer`.
pub name: String,
/// Already mapped/sanitized format name, supplied by the application adapter.
pub dxf_name: String,
pub visible: bool,
pub dxf_color_index: u8,
pub class: Option<String>,
pub data_kind: Option<String>,
}
#[derive(Debug, Clone, PartialEq)]
pub struct OutputPath {
pub path: BezPath,
pub layer: usize,
pub color_rgb: [u8; 3],
pub stroke_width_mm: f64,
pub class: Option<String>,
pub data_kind: Option<String>,
/// Close each open contour for formats that require closed cutting operations.
pub close_open_contours: bool,
}
#[derive(Debug, Clone, PartialEq)]
pub struct OutputScene {
pub width_mm: f64,
pub height_mm: f64,
pub view_box: [f64; 4],
pub layers: Vec<OutputLayer>,
pub paths: Vec<OutputPath>,
}
/// One page for the shared PDF path writer. Coordinates and stroke widths are millimetres.
#[derive(Debug, Clone, PartialEq)]
pub struct PdfPage {
pub width_mm: f64,
pub height_mm: f64,
pub view_box: [f64; 4],
pub paths: Vec<PdfPath>,
}
/// A PDF path with either a fill or a stroke. `None` fills the path; `Some(width)` strokes it.
#[derive(Debug, Clone, PartialEq)]
pub struct PdfPath {
pub path: BezPath,
pub color_rgb: [u8; 3],
pub stroke_width_mm: Option<f64>,
}
/// Match a target extension to the centralized writer registry.
pub fn writer_format_for_extension(extension: &str) -> Option<WriteFormat> {
let family = writer_family_for_extension(extension)?;
let extension = extension.trim_start_matches('.');
Some(match family {
ImportFormat::Svg => WriteFormat::Svg,
ImportFormat::Svgz => WriteFormat::Svgz,
ImportFormat::Dxf => WriteFormat::Dxf,
ImportFormat::Pdf => WriteFormat::Pdf,
ImportFormat::Raster if extension.eq_ignore_ascii_case("png") => WriteFormat::Png,
ImportFormat::Raster => WriteFormat::Jpeg,
ImportFormat::Eps => return None,
})
}
/// Product handler family for a writer extension.
pub fn writer_family_for_extension(extension: &str) -> Option<ImportFormat> {
let extension = extension.trim_start_matches('.');
for capability in CAPABILITIES {
if !capability.write_extensions.iter().any(|candidate| candidate.eq_ignore_ascii_case(extension)) {
continue;
}
return Some(capability.format);
}
None
}
/// Vector extensions the writer registry supports.
pub fn supported_vector_write_extensions() -> Vec<&'static str> {
CAPABILITIES.iter().filter(|capability| capability.vector).flat_map(|capability| capability.write_extensions.iter().copied()).collect()
}
/// Serialize a neutral vector scene as SVG, SVGZ, DXF, or PDF according to the extension.
pub fn write_vector(extension: &str, scene: &OutputScene) -> Result<Vec<u8>, Error> {
match writer_format_for_extension(extension).ok_or_else(|| Error::Write(format!("no writer for .{extension}")))? {
WriteFormat::Svg => write_svg(scene).map(String::into_bytes),
WriteFormat::Svgz => write_svg(scene).map(|svg| craft_svg::svgz::compress(svg.as_bytes())),
WriteFormat::Dxf => write_dxf(scene).map(String::into_bytes),
WriteFormat::Pdf => write_pdf(scene),
WriteFormat::Png | WriteFormat::Jpeg => Err(Error::Write("raster output requires pixels".into())),
}
}
/// Encode an RGBA image using the writer selected by its extension.
pub fn write_raster(extension: &str, width: u32, height: u32, rgba: &[u8], jpeg_quality: u8) -> Result<Vec<u8>, Error> {
let pixels = craft_raster_codecs::common::Pixels::from_raw(width, height, rgba.to_vec()).ok_or(Error::InvalidGeometry)?;
match writer_format_for_extension(extension).ok_or_else(|| Error::Write(format!("no writer for .{extension}")))? {
WriteFormat::Png => craft_raster_codecs::common::encode_png(&pixels).map_err(|error| Error::Write(error.to_string())),
WriteFormat::Jpeg => craft_raster_codecs::common::encode_jpeg(&pixels, jpeg_quality).map_err(|error| Error::Write(error.to_string())),
_ => Err(Error::Write("vector output requires paths".into())),
}
}
fn write_svg(scene: &OutputScene) -> Result<String, Error> {
validate_scene(scene)?;
let view_scale = (scene.width_mm / scene.view_box[2]).min(scene.height_mm / scene.view_box[3]);
if !(view_scale.is_finite() && view_scale > 0.0) {
return Err(Error::InvalidGeometry);
}
let paths_by_layer = paths_by_layer(scene);
let elements = scene
.layers
.iter()
.enumerate()
.map(|(layer_index, layer)| {
let paths = paths_by_layer[layer_index]
.iter()
.map(|path| {
let color = path.color_rgb;
let mut attributes = vec![
craft_svg::write::Attribute::text("fill", "none"),
craft_svg::write::Attribute::text("stroke", format!("#{:02x}{:02x}{:02x}", color[0], color[1], color[2])),
craft_svg::write::Attribute::text("stroke-width", format_float(path.stroke_width_mm / view_scale)),
];
if let Some(class) = &path.class {
attributes.push(craft_svg::write::Attribute::text("class", class.clone()));
}
if let Some(data_kind) = &path.data_kind {
attributes.push(craft_svg::write::Attribute::text("data-kind", data_kind.clone()));
}
craft_svg::write::Element::Path { attributes, path: path.path.clone() }
})
.collect::<Vec<_>>();
let mut attributes = vec![
craft_svg::write::Attribute::text("data-layer", layer.name.clone()),
craft_svg::write::Attribute::text("style", if layer.visible { "display:inline" } else { "display:none" }),
];
if let Some(class) = &layer.class {
attributes.push(craft_svg::write::Attribute::text("class", class.clone()));
}
if let Some(data_kind) = &layer.data_kind {
attributes.push(craft_svg::write::Attribute::text("data-kind", data_kind.clone()));
}
craft_svg::write::Element::Group { attributes, children: paths }
})
.collect();
Ok(craft_svg::write::Scene { width_mm: scene.width_mm, height_mm: scene.height_mm, view_box: scene.view_box, elements }.write())
}
fn write_pdf(scene: &OutputScene) -> Result<Vec<u8>, Error> {
validate_scene(scene)?;
let paths_by_layer = paths_by_layer(scene);
// Match SVG's painter order: layers in order, then paths in source order within each layer.
let paths = scene
.layers
.iter()
.enumerate()
.filter(|(_, layer)| layer.visible)
.flat_map(|(layer_index, _)| paths_by_layer[layer_index].iter().copied())
.map(|path| PdfPath { path: path.path.clone(), color_rgb: path.color_rgb, stroke_width_mm: Some(path.stroke_width_mm) })
.collect();
write_pdf_pages(&[PdfPage { width_mm: scene.width_mm, height_mm: scene.height_mm, view_box: scene.view_box, paths }])
}
/// Group the neutral paths once so writing does not rescan all paths for every layer.
fn paths_by_layer(scene: &OutputScene) -> Vec<Vec<&OutputPath>> {
let mut grouped: Vec<Vec<&OutputPath>> = (0..scene.layers.len()).map(|_| Vec::new()).collect();
for path in &scene.paths {
if let Some(layer) = grouped.get_mut(path.layer) {
layer.push(path);
}
}
grouped
}
/// Encode a neutral list of laid-out pages with vector paths as PDF.
pub fn write_pdf_pages(pages: &[PdfPage]) -> Result<Vec<u8>, Error> {
use craft_pdf::write::{Metadata, Writer, backend};
const PT_PER_MM: f64 = 72.0 / 25.4;
craft_pdf::write::guard(|| {
let settings = backend::SerializeSettings {
configuration: craft_pdf::write::configuration(backend::configure::PdfVersion::Pdf14, None)?,
..Default::default()
};
let mut writer = Writer::new(settings, Metadata::default());
for source_page in pages {
let [view_x, view_y, view_width, view_height] = source_page.view_box;
if !(source_page.width_mm.is_finite()
&& source_page.height_mm.is_finite()
&& source_page.width_mm > 0.0
&& source_page.height_mm > 0.0
&& view_x.is_finite()
&& view_y.is_finite()
&& view_width.is_finite()
&& view_height.is_finite()
&& view_width > 0.0
&& view_height > 0.0)
{
return Err(Error::InvalidGeometry);
}
let width = source_page.width_mm * PT_PER_MM;
let height = source_page.height_mm * PT_PER_MM;
if !(width.is_finite()
&& height.is_finite()
&& width > 0.0
&& height > 0.0
&& width <= f64::from(f32::MAX)
&& height <= f64::from(f32::MAX))
{
return Err(Error::Write("page dimensions are outside the PDF range".into()));
}
let page_settings = backend::page::PageSettings::from_wh(width as f32, height as f32)
.ok_or_else(|| Error::Write("page dimensions are not finite or positive".into()))?;
let mut page = writer.document_mut().start_page_with(page_settings);
let mut surface = page.surface();
let view_scale = (source_page.width_mm / view_width).min(source_page.height_mm / view_height);
let offset_x = (source_page.width_mm - view_width * view_scale) / 2.0;
let offset_y = (source_page.height_mm - view_height * view_scale) / 2.0;
if !(view_scale.is_finite() && view_scale > 0.0 && offset_x.is_finite() && offset_y.is_finite()) {
return Err(Error::InvalidGeometry);
}
for source in &source_page.paths {
let mut path = backend::geom::PathBuilder::new();
for element in source.path.elements() {
let point = |p: Point| -> Result<(f32, f32), Error> {
let x = ((p.x - view_x) * view_scale + offset_x) * PT_PER_MM;
let y = ((p.y - view_y) * view_scale + offset_y) * PT_PER_MM;
if !(p.x.is_finite()
&& p.y.is_finite()
&& x.is_finite()
&& y.is_finite()
&& x.abs() <= f64::from(f32::MAX)
&& y.abs() <= f64::from(f32::MAX))
{
return Err(Error::Write("path coordinate is outside the PDF range".into()));
}
Ok((x as f32, y as f32))
};
match *element {
PathEl::MoveTo(p) => {
let (x, y) = point(p)?;
path.move_to(x, y);
}
PathEl::LineTo(p) => {
let (x, y) = point(p)?;
path.line_to(x, y);
}
PathEl::QuadTo(a, b) => {
let (x1, y1) = point(a)?;
let (x, y) = point(b)?;
path.quad_to(x1, y1, x, y);
}
PathEl::CurveTo(a, b, c) => {
let (x1, y1) = point(a)?;
let (x2, y2) = point(b)?;
let (x, y) = point(c)?;
path.cubic_to(x1, y1, x2, y2, x, y);
}
PathEl::ClosePath => path.close(),
}
}
if let Some(path) = path.finish() {
let color = backend::color::rgb::Color::new(source.color_rgb[0], source.color_rgb[1], source.color_rgb[2]);
match source.stroke_width_mm {
Some(width_mm) => {
let width_pt = width_mm * PT_PER_MM;
if !(width_mm.is_finite() && width_mm > 0.0 && width_pt.is_finite() && width_pt <= f64::from(f32::MAX)) {
return Err(Error::Write("stroke width must be finite and positive".into()));
}
surface.set_fill(None);
surface.set_stroke(Some(backend::paint::Stroke { paint: color.into(), width: width_pt as f32, ..Default::default() }));
}
None => {
surface.set_stroke(None);
surface.set_fill(Some(backend::paint::Fill { paint: color.into(), ..Default::default() }));
}
}
surface.draw_path(&path);
}
}
surface.finish();
page.finish();
}
writer.finish().map_err(|error| Error::Write(error.to_string()))
})
}
fn write_dxf(scene: &OutputScene) -> Result<String, Error> {
validate_scene(scene)?;
let mut drawing = craft_dxf::model::write::Drawing::default();
drawing.format = craft_dxf::model::write::Format::R14;
drawing.insunits = 4;
drawing.metric = true;
drawing.extents = [0.0, 0.0, scene.width_mm, scene.height_mm];
drawing.limits = drawing.extents;
for layer in &scene.layers {
drawing.layers.push(craft_dxf::model::Layer {
handle: None,
name: layer.dxf_name.clone(),
color: craft_dxf::model::Color::Index(layer.dxf_color_index),
on: layer.visible,
frozen: false,
vp_freeze_new: false,
locked: false,
plot: true,
linetype: "Continuous".into(),
lineweight: craft_dxf::model::Lineweight::Default,
plot_style: None,
transparency: craft_dxf::model::Transparency::ByLayer,
description: None,
});
}
for output in &scene.paths {
let Some(layer) = scene.layers.get(output.layer) else {
return Err(Error::InvalidGeometry);
};
let view_scale = (scene.width_mm / scene.view_box[2]).min(scene.height_mm / scene.view_box[3]);
let offset_x = (scene.width_mm - scene.view_box[2] * view_scale) / 2.0;
let offset_y = (scene.height_mm - scene.view_box[3] * view_scale) / 2.0;
let mut page_path = output.path.clone();
page_path.apply_affine(kurbo::Affine::new([
view_scale,
0.0,
0.0,
view_scale,
offset_x - scene.view_box[0] * view_scale,
offset_y - scene.view_box[1] * view_scale,
]));
for (points, closed) in flatten(&page_path)? {
if points.len() < 2 {
continue;
}
let mut vertices = Vec::with_capacity(points.len());
for point in points {
if !(point.x.is_finite() && point.y.is_finite()) {
return Err(Error::InvalidGeometry);
}
vertices.push(craft_dxf::model::LwVertex { x: point.x, y: scene.height_mm - point.y, ..Default::default() });
}
drawing.entities.push(craft_dxf::model::Entity {
common: craft_dxf::model::Common {
handle: None,
owner: None,
layer: layer.dxf_name.clone(),
linetype: None,
color: craft_dxf::model::Color::ByLayer,
lineweight: craft_dxf::model::Lineweight::ByLayer,
ltscale: 1.0,
visible: true,
paper_space: false,
transparency: craft_dxf::model::Transparency::ByLayer,
thickness: 0.0,
extrusion: [0.0, 0.0, 1.0],
plot_style: None,
},
kind: craft_dxf::model::EntityKind::LwPolyline(craft_dxf::model::LwPolyline {
vertices,
closed: closed || output.close_open_contours,
plinegen: false,
const_width: 0.0,
elevation: 0.0,
}),
});
}
}
let (tags, skipped) = drawing.tags();
if skipped > 0 {
return Err(Error::Write(format!("DXF writer skipped {skipped} entities")));
}
Ok(craft_dxf::write_ascii(&tags))
}
fn flatten(path: &BezPath) -> Result<Vec<(Vec<Point>, bool)>, Error> {
const MAX_POINTS: usize = 2_000_000;
let mut contours: Vec<(Vec<Point>, bool)> = Vec::new();
let mut count = 0usize;
vectorcraft_geom::flatten(path.iter(), 0.05, |element| {
count = count.saturating_add(1);
if count > MAX_POINTS {
return;
}
match element {
PathEl::MoveTo(point) => contours.push((vec![point], false)),
PathEl::LineTo(point) => {
if let Some((points, _)) = contours.last_mut() {
points.push(point);
}
}
PathEl::ClosePath => {
if let Some((_, closed)) = contours.last_mut() {
*closed = true;
}
}
PathEl::QuadTo(..) | PathEl::CurveTo(..) => {}
}
});
if count > MAX_POINTS {
return Err(Error::Write("path exceeds the DXF flattening limit".into()));
}
Ok(contours)
}
fn validate_scene(scene: &OutputScene) -> Result<(), Error> {
if !(scene.width_mm.is_finite() && scene.height_mm.is_finite() && scene.width_mm > 0.0 && scene.height_mm > 0.0) {
return Err(Error::InvalidGeometry);
}
if !(scene.view_box.iter().all(|value| value.is_finite()) && scene.view_box[2] > 0.0 && scene.view_box[3] > 0.0)
|| scene.paths.len() > crate::MAX_SHAPES
|| scene.paths.iter().any(|path| {
path.layer >= scene.layers.len()
|| !(path.stroke_width_mm.is_finite() && path.stroke_width_mm > 0.0)
|| path.path.elements().iter().any(|element| match *element {
PathEl::MoveTo(point) | PathEl::LineTo(point) => !point_is_finite(point),
PathEl::QuadTo(a, b) => !point_is_finite(a) || !point_is_finite(b),
PathEl::CurveTo(a, b, c) => !point_is_finite(a) || !point_is_finite(b) || !point_is_finite(c),
PathEl::ClosePath => false,
})
})
{
return Err(Error::InvalidGeometry);
}
Ok(())
}
fn point_is_finite(point: Point) -> bool {
point.x.is_finite() && point.y.is_finite()
}
fn format_float(value: f64) -> String {
value.to_string()
}
+21
View File
@@ -0,0 +1,21 @@
[package]
name = "craft-flags"
version.workspace = true
edition.workspace = true
license.workspace = true
rust-version.workspace = true
repository.workspace = true
description = "Feature flags shared by the Craft apps and the ArtCraft Launcher: one per-user file, an environment override, off by default"
[lints]
workspace = true
[dependencies]
toml_edit = { version = "0.25" }
[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
craft-atomic = { workspace = true }
dirs = "7"
[dev-dependencies]
tempfile = "3"
+36
View File
@@ -0,0 +1,36 @@
# Craft Flags
`craft-flags` lets a feature ship in every Craft app and the ArtCraft Launcher while it stays off
until a person turns it on. Every flag is off by default.
- **One file for the suite:** `ArtCraft/flags.toml` in the per-user local configuration folder
(`%LOCALAPPDATA%` on Windows, `~/Library/Application Support` on macOS, `$XDG_CONFIG_HOME` on
Linux), beside the AI layer's `ArtCraft/ai`. `CRAFT_FLAGS_FILE` names another file.
- **One run:** `CRAFT_FLAGS=AI-MCP,-AI-MODELS` overrides the file.
- **Never crashes:** a missing or damaged file means every flag is at its default, with the
reason in `Flags::problems`. `set` changes one flag atomically and keeps everything else in the
file; it refuses to touch a file it cannot read.
- **Browser:** no file, no environment: every flag is at its default.
## Flags
| Constant | Id | What it gates |
|---|---|---|
| `AI_MCP` | `AI-MCP` | AI agents using the Craft apps through MCP: the launcher's AI agents settings, the `craft-ai-mcp` gateway, the apps' agent connection settings |
| `AI_MODELS` | `AI-MODELS` | Choosing AI models and services for AI tools such as Generative Fill |
A new flag is a new constant here and a row in `ALL`, so the launcher can list it and every app
names it the same way.
## Use
```rust
let flags = craft_flags::load();
if flags.enabled(&craft_flags::AI_MCP) {
// show the agent connection settings
}
```
The launcher turns a flag on with `craft_flags::set(&path, craft_flags::AI_MCP.id, true)`, where
`path` is `craft_flags::default_path()`. Apps read the flags when they start; a flag changed
while an app runs takes effect at its next start, unless the app loads them again.
+220
View File
@@ -0,0 +1,220 @@
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
//! Feature flags shared by the Craft apps and the ArtCraft Launcher.
//!
//! A flag lets a feature land on `main` and ship in every app while it stays off until a person
//! (or a release) turns it on. Every flag is **off by default**. One per-user file holds the
//! choices, so the launcher can show a flag once and every app follows it:
//!
//! | Platform | File |
//! |---|---|
//! | Windows | `%LOCALAPPDATA%\ArtCraft\flags.toml` |
//! | macOS | `~/Library/Application Support/ArtCraft/flags.toml` |
//! | Linux | `$XDG_CONFIG_HOME/ArtCraft/flags.toml` (default `~/.config/ArtCraft/flags.toml`) |
//!
//! beside the AI layer's `ArtCraft/ai`. `CRAFT_FLAGS_FILE` names another file (tests, portable
//! installs). The file looks like this; keys and comments the reader does not know are kept when
//! a flag is changed:
//!
//! ```toml
//! [flags]
//! AI-MCP = true
//! ```
//!
//! `CRAFT_FLAGS` overrides the file for one run: `CRAFT_FLAGS=AI-MCP,-AI-MODELS` turns `AI-MCP`
//! on and `AI-MODELS` off (`AI-MCP=1` and `AI-MODELS=0` work too).
//!
//! ```
//! let flags = craft_flags::Flags::from_parts(Some("[flags]\nAI-MCP = true\n"), None);
//! assert!(flags.enabled(&craft_flags::AI_MCP));
//! assert!(!flags.enabled(&craft_flags::AI_MODELS));
//! ```
//!
//! Loading never fails: a missing file means every flag is at its default, and a damaged one is
//! reported in [`Flags::problems`] and read as if it were missing. In the browser (wasm) there is
//! no file and no environment; every flag is at its default.
use std::collections::BTreeMap;
use std::path::PathBuf;
#[cfg(not(target_arch = "wasm32"))]
mod store;
#[cfg(not(target_arch = "wasm32"))]
pub use store::{FlagError, load, set};
/// One feature flag. Declared here, so the launcher can list every flag and each app names the
/// same one by the same constant.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Flag {
/// The key in the file and in `CRAFT_FLAGS` (upper case, digits and `-`).
pub id: &'static str,
/// A short name a person reads.
pub title: &'static str,
/// What turning it on does.
pub description: &'static str,
/// Its value when neither the file nor `CRAFT_FLAGS` names it.
pub default: bool,
}
/// AI agents reach the Craft apps through MCP: the launcher's AI agents settings, the
/// `craft-ai-mcp` gateway and the apps' agent connection settings.
pub const AI_MCP: Flag = Flag {
id: "AI-MCP",
title: "AI agents (MCP)",
description: "Let AI agents such as Claude, Cursor or LM Studio use the Craft apps through MCP.",
default: false,
};
/// AI models and services in the apps: choosing a model or a service for AI tools such as
/// Generative Fill.
pub const AI_MODELS: Flag = Flag {
id: "AI-MODELS",
title: "AI models and services",
description: "Choose AI models and services for AI tools such as Generative Fill.",
default: false,
};
/// Every flag, in the order the launcher lists them.
pub const ALL: &[Flag] = &[AI_MCP, AI_MODELS];
/// The environment variable that overrides the file for one run.
pub const ENV: &str = "CRAFT_FLAGS";
/// The environment variable that names another flags file.
pub const FILE_ENV: &str = "CRAFT_FLAGS_FILE";
/// The file's name in the `ArtCraft` folder.
pub const FILE_NAME: &str = "flags.toml";
/// Largest flags file read; anything bigger is not a flags file.
pub const MAX_FILE_BYTES: u64 = 64 * 1024;
/// Most flags read from the file or the environment.
const MAX_ENTRIES: usize = 256;
/// Longest flag id.
const MAX_ID_LEN: usize = 40;
/// Whether `id` can name a flag: 1 to 40 of `A`-`Z`, `0`-`9` and `-`.
pub fn valid_id(id: &str) -> bool {
!id.is_empty() && id.len() <= MAX_ID_LEN && id.bytes().all(|b| b.is_ascii_uppercase() || b.is_ascii_digit() || b == b'-')
}
/// The flags file: `CRAFT_FLAGS_FILE`, otherwise `ArtCraft/flags.toml` in the per-user local
/// configuration folder. `None` when there is no such folder (and always in the browser).
pub fn default_path() -> Option<PathBuf> {
#[cfg(target_arch = "wasm32")]
{
None
}
#[cfg(not(target_arch = "wasm32"))]
{
match std::env::var_os(FILE_ENV) {
Some(p) if !p.is_empty() => Some(PathBuf::from(p)),
_ => dirs::config_local_dir().map(|d| d.join("ArtCraft").join(FILE_NAME)),
}
}
}
/// The flags as read: what the file says, what `CRAFT_FLAGS` says, and what could not be read.
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct Flags {
file: BTreeMap<String, bool>,
env: BTreeMap<String, bool>,
/// What was left out and why (a damaged file, an entry that is not `true` or `false`, a word
/// in `CRAFT_FLAGS` that is not a flag). For logs; never fatal.
pub problems: Vec<String>,
}
impl Flags {
/// Flags from a file's text and a `CRAFT_FLAGS` value. Either may be absent.
pub fn from_parts(file: Option<&str>, env: Option<&str>) -> Self {
let mut flags = Flags::default();
if let Some(text) = file {
flags.read_file(text);
}
if let Some(value) = env {
flags.read_env(value);
}
flags
}
fn read_file(&mut self, text: &str) {
let doc = match text.parse::<toml_edit::DocumentMut>() {
Ok(d) => d,
Err(e) => {
self.problems.push(format!("the flags file does not parse, so every flag is at its default: {e}"));
return;
}
};
let Some(table) = doc.get("flags").and_then(toml_edit::Item::as_table_like) else {
if doc.get("flags").is_some() {
self.problems.push("`flags` in the flags file is not a table".into());
}
return;
};
for (key, item) in table.iter() {
if self.file.len() >= MAX_ENTRIES {
self.problems.push(format!("more than {MAX_ENTRIES} flags in the file; the rest are left out"));
break;
}
if !valid_id(key) {
self.problems.push(format!("`{}` in the flags file is not a flag name", key.escape_debug()));
continue;
}
match item.as_bool() {
Some(on) => {
self.file.insert(key.to_string(), on);
}
None => self.problems.push(format!("`{key}` in the flags file is not true or false")),
}
}
}
fn read_env(&mut self, value: &str) {
for word in value.split([',', ';', ' ']).map(str::trim).filter(|w| !w.is_empty()).take(MAX_ENTRIES) {
let (id, on) = if let Some(rest) = word.strip_prefix('-') {
(rest, Some(false))
} else if let Some((id, v)) = word.split_once('=') {
(id, parse_bool(v))
} else {
(word, Some(true))
};
match on {
Some(on) if valid_id(id) => {
self.env.insert(id.to_string(), on);
}
_ => self.problems.push(format!("`{}` in {ENV} is not a flag setting", word.escape_debug())),
}
}
}
/// Whether `flag` is on: `CRAFT_FLAGS` first, then the file, then the flag's default.
pub fn enabled(&self, flag: &Flag) -> bool {
self.lookup(flag.id).unwrap_or(flag.default)
}
/// Whether the flag named `id` is on; a name nothing sets is off.
pub fn enabled_id(&self, id: &str) -> bool {
match ALL.iter().find(|f| f.id == id) {
Some(f) => self.enabled(f),
None => self.lookup(id).unwrap_or(false),
}
}
/// Whether `CRAFT_FLAGS` decides `id` for this run, so a switch in a settings page would have
/// no effect until the variable is gone.
pub fn forced(&self, id: &str) -> Option<bool> {
self.env.get(id).copied()
}
fn lookup(&self, id: &str) -> Option<bool> {
self.env.get(id).or_else(|| self.file.get(id)).copied()
}
}
fn parse_bool(v: &str) -> Option<bool> {
match v.trim().to_ascii_lowercase().as_str() {
"1" | "true" | "on" | "yes" => Some(true),
"0" | "false" | "off" | "no" => Some(false),
_ => None,
}
}
#[cfg(test)]
mod tests;
+86
View File
@@ -0,0 +1,86 @@
//! Reading and changing the flags file (desktop only).
use std::fmt;
use std::path::Path;
use crate::{ENV, Flags, MAX_FILE_BYTES, default_path, valid_id};
/// Why a flag could not be changed.
#[derive(Debug)]
pub enum FlagError {
/// Not a flag name (see [`valid_id`]).
BadId(String),
/// The file exists but is not a flags file this crate can change without losing what is in
/// it (it does not parse, is too big, or `flags` is not a table). It is left as it is.
Unreadable(String),
/// Reading or writing the file failed.
Io(std::io::Error),
}
impl fmt::Display for FlagError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
FlagError::BadId(id) => write!(f, "`{}` is not a flag name", id.escape_debug()),
FlagError::Unreadable(why) => write!(f, "the flags file was left unchanged: {why}"),
FlagError::Io(e) => write!(f, "{e}"),
}
}
}
impl std::error::Error for FlagError {}
/// The file's text, `None` when it does not exist. A file that isn't a regular file, is too big
/// or isn't UTF-8 is an error.
fn read_text(path: &Path) -> Result<Option<String>, FlagError> {
let meta = match std::fs::metadata(path) {
Ok(m) => m,
Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),
Err(e) => return Err(FlagError::Io(e)),
};
if !meta.is_file() {
return Err(FlagError::Unreadable(format!("{} is not a regular file", path.display())));
}
if meta.len() > MAX_FILE_BYTES {
return Err(FlagError::Unreadable(format!("{} is larger than {MAX_FILE_BYTES} bytes", path.display())));
}
let bytes = std::fs::read(path).map_err(FlagError::Io)?;
String::from_utf8(bytes).map(Some).map_err(|_| FlagError::Unreadable(format!("{} is not UTF-8 text", path.display())))
}
/// The flags of this run: [`default_path`] and `CRAFT_FLAGS`. Never fails; what could not be
/// read is in [`Flags::problems`].
pub fn load() -> Flags {
let env = std::env::var(ENV).ok();
let Some(path) = default_path() else {
return Flags::from_parts(None, env.as_deref());
};
match read_text(&path) {
Ok(text) => Flags::from_parts(text.as_deref(), env.as_deref()),
Err(e) => {
let mut flags = Flags::from_parts(None, env.as_deref());
flags.problems.insert(0, format!("{}: {e}; every flag is at its default", path.display()));
flags
}
}
}
/// Turn the flag `id` on or off in the file at `path` (made if missing). Everything else in the
/// file, comments included, is kept; the write is atomic.
pub fn set(path: &Path, id: &str, on: bool) -> Result<(), FlagError> {
if !valid_id(id) {
return Err(FlagError::BadId(id.to_string()));
}
let mut doc = match read_text(path)? {
Some(text) => text.parse::<toml_edit::DocumentMut>().map_err(|e| FlagError::Unreadable(e.to_string()))?,
None => toml_edit::DocumentMut::new(),
};
let item = doc.entry("flags").or_insert_with(toml_edit::table);
let Some(table) = item.as_table_like_mut() else {
return Err(FlagError::Unreadable("`flags` is not a table".into()));
};
table.insert(id, toml_edit::value(on));
if let Some(dir) = path.parent() {
std::fs::create_dir_all(dir).map_err(FlagError::Io)?;
}
craft_atomic::atomic_write(path, doc.to_string().as_bytes()).map_err(FlagError::Io)
}
+118
View File
@@ -0,0 +1,118 @@
use super::*;
#[test]
fn every_flag_is_off_by_default_and_has_a_valid_unique_id() {
let flags = Flags::default();
for f in ALL {
assert!(!f.default, "{} must ship off", f.id);
assert!(!flags.enabled(f));
assert!(valid_id(f.id), "{}", f.id);
assert!(!f.title.is_empty() && !f.description.is_empty());
assert_eq!(ALL.iter().filter(|g| g.id == f.id).count(), 1, "{} twice", f.id);
}
}
#[test]
fn the_file_turns_flags_on_and_off() {
let flags = Flags::from_parts(Some("# mine\n[flags]\nAI-MCP = true\nAI-MODELS = false\n"), None);
assert!(flags.enabled(&AI_MCP));
assert!(!flags.enabled(&AI_MODELS));
assert!(flags.problems.is_empty(), "{:?}", flags.problems);
}
#[test]
fn the_environment_wins_over_the_file() {
let file = Some("[flags]\nAI-MCP = true\n");
let flags = Flags::from_parts(file, Some("-AI-MCP, AI-MODELS"));
assert!(!flags.enabled(&AI_MCP));
assert!(flags.enabled(&AI_MODELS));
assert_eq!(flags.forced("AI-MCP"), Some(false));
let flags = Flags::from_parts(None, Some("AI-MCP=1;AI-MODELS=off"));
assert!(flags.enabled(&AI_MCP));
assert!(!flags.enabled(&AI_MODELS));
assert_eq!(flags.forced("OTHER"), None);
}
#[test]
fn bad_entries_are_reported_and_left_out_never_fatal() {
let flags = Flags::from_parts(Some("[flags]\nAI-MCP = \"yes\"\nlower = true\nAI-MODELS = true\n"), Some("AI-MCP=maybe,bad id,"));
assert!(!flags.enabled(&AI_MCP), "a value that is not true or false is not on");
assert!(flags.enabled(&AI_MODELS));
assert_eq!(flags.problems.len(), 5, "{:?}", flags.problems); // "bad id" is two words
for text in ["not toml [[[", "flags = 3", "\u{feff}[flags]\nAI-MCP = true", ""] {
let flags = Flags::from_parts(Some(text), None);
assert!(!flags.enabled(&AI_MCP) || text.contains("AI-MCP = true"), "{text:?}");
}
assert!(!Flags::from_parts(Some("not toml [[["), None).problems.is_empty());
assert!(!Flags::from_parts(Some("flags = 3"), None).problems.is_empty());
}
#[test]
fn many_entries_are_capped() {
let mut text = String::from("[flags]\n");
for i in 0..(MAX_ENTRIES + 10) {
text.push_str(&format!("F{i} = true\n"));
}
let flags = Flags::from_parts(Some(&text), None);
assert_eq!(flags.file.len(), MAX_ENTRIES);
assert!(flags.problems.iter().any(|p| p.contains("more than")));
}
#[test]
fn unknown_ids_are_off_unless_set() {
let flags = Flags::from_parts(Some("[flags]\nNEW-THING = true\n"), None);
assert!(flags.enabled_id("NEW-THING"));
assert!(!flags.enabled_id("OTHER-THING"));
assert!(!flags.enabled_id("AI-MCP"));
}
#[test]
fn ids_are_checked() {
assert!(valid_id("AI-MCP"));
assert!(!valid_id(""));
assert!(!valid_id("ai-mcp"));
assert!(!valid_id("AI MCP"));
assert!(!valid_id(&"A".repeat(MAX_ID_LEN + 1)));
}
#[cfg(not(target_arch = "wasm32"))]
mod file {
use super::super::*;
#[test]
fn set_creates_the_file_and_keeps_what_else_is_in_it() {
let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("ArtCraft").join(FILE_NAME);
set(&path, "AI-MCP", true).unwrap();
let text = std::fs::read_to_string(&path).unwrap();
assert!(Flags::from_parts(Some(&text), None).enabled(&AI_MCP));
std::fs::write(&path, "# keep me\nother = 1\n[flags]\nAI-MCP = true # on for testing\nX-OLD = false\n").unwrap();
set(&path, "AI-MODELS", true).unwrap();
set(&path, "AI-MCP", false).unwrap();
let text = std::fs::read_to_string(&path).unwrap();
assert!(text.contains("# keep me") && text.contains("other = 1") && text.contains("X-OLD = false"), "{text}");
let flags = Flags::from_parts(Some(&text), None);
assert!(!flags.enabled(&AI_MCP));
assert!(flags.enabled(&AI_MODELS));
}
#[test]
fn set_never_overwrites_a_file_it_cannot_read() {
let dir = tempfile::tempdir().unwrap();
for (name, text) in [("broken.toml", "[[[ not toml"), ("scalar.toml", "flags = 3\n")] {
let path = dir.path().join(name);
std::fs::write(&path, text).unwrap();
assert!(matches!(set(&path, "AI-MCP", true), Err(FlagError::Unreadable(_))), "{name}");
assert_eq!(std::fs::read_to_string(&path).unwrap(), text, "{name} changed");
}
let big = dir.path().join("big.toml");
std::fs::write(&big, vec![b'#'; MAX_FILE_BYTES as usize + 1]).unwrap();
assert!(matches!(set(&big, "AI-MCP", true), Err(FlagError::Unreadable(_))));
let folder = dir.path().join("folder.toml");
std::fs::create_dir(&folder).unwrap();
assert!(set(&folder, "AI-MCP", true).is_err());
assert!(matches!(set(&dir.path().join("ok.toml"), "bad id", true), Err(FlagError::BadId(_))));
}
}
+36 -2
View File
@@ -426,10 +426,30 @@ fn recovery_cleanup_does_not_follow_a_replaced_parent_symlink() {
std::fs::remove_dir_all(store.dir()).unwrap();
}
/// The language-packs ancestor must not redirect a committed cleanup outside the store.
#[cfg(unix)]
#[test]
fn committed_cleanup_rejects_a_symlinked_language_packs_ancestor() {
let (store, _server, _pin, _) = setup("remove-symlink-packs");
let outside = temp("remove-symlink-packs-outside");
std::fs::create_dir_all(outside.join(".removing/11-12")).unwrap();
std::fs::write(outside.join(".removing/11-12/keep"), b"untouched").unwrap();
std::fs::create_dir_all(store.dir()).unwrap();
std::os::unix::fs::symlink(&outside, store.language_packs_dir()).unwrap();
let mut record = Installed::default();
record.committed_removals.push("11-12".into());
store.write_installed(&record).unwrap();
drop(store.lock().unwrap());
assert_eq!(std::fs::read(outside.join(".removing/11-12/keep")).unwrap(), b"untouched");
assert!(store.pack_removal_dir().is_err());
std::fs::remove_file(store.language_packs_dir()).unwrap();
std::fs::remove_dir_all(outside).unwrap();
std::fs::remove_dir_all(store.dir()).unwrap();
}
/// A replacement after validation must not redirect recursive deletion to the new target.
#[cfg(unix)]
#[test]
fn residual_cleanup_stays_anchored_after_recovery_parent_replacement() {
fn committed_cleanup_stays_anchored_after_recovery_parent_replacement() {
let (store, _server, _pin, _) = setup("remove-parent-race");
let parent = store.language_packs_dir().join(".removing");
let moved = store.language_packs_dir().join(".removing-old");
@@ -568,7 +588,7 @@ fn recovery_cleanup_locks_all_windows_ancestors_until_removal_finishes() {
/// A malformed optional receipt must not discard valid receipts or installed-pack metadata.
#[test]
fn residual_one_bad_receipt_preserves_valid_metadata_and_cleanup() {
fn one_bad_receipt_preserves_valid_metadata_and_cleanup() {
let (store, _server, pin, _) = setup("remove-mixed-receipts");
let index = store.fetch_pack_index_from(&IndexSource::Pinned(pin), &Cancel::new()).unwrap();
store.install_pack_from(false, &index, index.pack("nl").unwrap(), &Cancel::new(), &mut |_| {}).unwrap();
@@ -587,6 +607,20 @@ fn residual_one_bad_receipt_preserves_valid_metadata_and_cleanup() {
std::fs::remove_dir_all(store.dir()).unwrap();
}
/// Exclusions do not consume filesystem candidates; hostile iterator input remains bounded.
#[test]
fn stage_exclusions_leave_the_filesystem_candidate_budget() {
let parent = temp("stage-excluded-budget");
let excluded: Vec<String> = (0..1000).map(|n| format!("0-{n}")).collect();
let stage = Stage::create_in(&parent, &excluded, excluded.iter().cloned().chain(std::iter::once("0-1000".into())))
.expect("a free name after excluded receipts is still considered");
drop(stage);
assert!(Stage::create_in(&parent, &excluded, std::iter::repeat_with(|| "0-0".into())).is_err());
assert!(Stage::create_in(&parent, &[], std::iter::repeat_with(|| "../invalid".into())).is_err());
std::fs::create_dir(parent.join("0-1001")).unwrap();
assert!(Stage::create_in(&parent, &[], std::iter::repeat_with(|| "0-1001".into())).is_err());
std::fs::remove_dir_all(parent).unwrap();
}
#[test]
fn network_off_pins_and_checksums_are_enforced() {
let (store, server, pin, archive) = setup("pins");
+14
View File
@@ -0,0 +1,14 @@
[package]
name = "craft-indd"
description = "Shared InDesign document to IDML conversion facade for Craft applications"
version.workspace = true
edition.workspace = true
license.workspace = true
repository.workspace = true
rust-version.workspace = true
[dependencies]
indd = { workspace = true }
[lints]
workspace = true
+17
View File
@@ -0,0 +1,17 @@
//! Shared InDesign document conversion boundary.
//!
//! InDesign's binary document model is converted to IDML here. Applications can import the
//! resulting package through [`craft_idml`] while retaining only their own model and UI mapping.
pub use indd::header::SIGNATURE;
pub use indd::{Conversion, Error, Preview, Warning};
/// Whether `bytes` begins with the fixed signature of an InDesign document.
pub fn is_indd(bytes: &[u8]) -> bool {
bytes.starts_with(&SIGNATURE)
}
/// Convert an InDesign document to IDML. `name` is the file name stored in the package.
pub fn convert(bytes: &[u8], name: &str) -> Result<Conversion, Error> {
indd::convert(bytes, name)
}
+123
View File
@@ -1,5 +1,6 @@
//! Huffman entropy decoding: code tables, the bit reader and the Huffman scan decoder.
use super::arith::ArithMode;
use super::scan::*;
use super::*;
@@ -217,3 +218,125 @@ impl ScanDecoder for HuffmanScan<'_> {
Ok(())
}
}
/// Huffman-coded progressive scan state (G.1.2). EOB runs span blocks in a scan.
pub(super) struct ProgressiveHuffmanScan<'a> {
pub(super) bits: Bits<'a>,
pub(super) tables: Vec<(&'a Huffman, &'a Huffman)>,
pub(super) mode: ArithMode,
pub(super) ss: usize,
pub(super) se: usize,
pub(super) al: u8,
pub(super) pred: [i32; 4],
pub(super) eob_run: usize,
}
impl ScanDecoder for ProgressiveHuffmanScan<'_> {
fn restart(&mut self) {
self.bits.restart();
self.pred = [0; 4];
self.eob_run = 0;
}
fn block(&mut self, sc: usize, blk: &mut [i32; 64]) -> Result<(), Error> {
let &(dc, ac) = self.tables.get(sc).ok_or_else(|| err("bad scan component"))?;
let p1 = 1i32.checked_shl(u32::from(self.al)).ok_or_else(|| err("bad successive approximation"))?;
match self.mode {
ArithMode::DcFirst => {
let t = u32::from(dc.decode(&mut self.bits)?);
if t > 15 {
return Err(err("bad DC difference category"));
}
let diff = extend(self.bits.get(t), t);
let pred = self.pred.get_mut(sc).ok_or_else(|| err("bad scan component"))?;
*pred = pred.wrapping_add(diff);
blk[0] = pred.wrapping_mul(p1);
}
ArithMode::DcRefine => {
if self.bits.get(1) != 0 {
blk[0] = if blk[0] < 0 { blk[0].wrapping_sub(p1) } else { blk[0].wrapping_add(p1) };
}
}
ArithMode::AcFirst => {
if self.eob_run != 0 {
self.eob_run -= 1;
} else {
let mut k = self.ss;
while k <= self.se {
let rs = ac.decode(&mut self.bits)?;
let (r, s) = (usize::from(rs >> 4), u32::from(rs & 15));
if s == 0 {
if r == 15 {
k += 16;
continue;
}
self.eob_run = (1usize << r).saturating_add(self.bits.get(r as u32) as usize).saturating_sub(1);
break;
}
k = k.saturating_add(r);
if k > self.se {
return Err(err("AC coefficient past the end of the band"));
}
blk[k] = extend(self.bits.get(s), s).wrapping_mul(p1);
k += 1;
}
}
}
ArithMode::AcRefine => {
let mut k = self.ss;
if self.eob_run == 0 {
while k <= self.se {
let rs = ac.decode(&mut self.bits)?;
let (mut r, s) = (usize::from(rs >> 4), rs & 15);
let mut new_value = 0;
if s == 0 {
if r != 15 {
self.eob_run = (1usize << r).saturating_add(self.bits.get(r as u32) as usize);
break;
}
r = 16;
} else {
if s != 1 {
return Err(err("bad AC refinement category"));
}
new_value = if self.bits.get(1) != 0 { p1 } else { -p1 };
}
while k <= self.se {
if blk[k] != 0 {
if self.bits.get(1) != 0 && (blk[k].unsigned_abs() & p1 as u32) == 0 {
blk[k] = if blk[k] < 0 { blk[k].wrapping_sub(p1) } else { blk[k].wrapping_add(p1) };
}
} else if r == 0 {
break;
} else {
r -= 1;
}
k += 1;
}
if new_value != 0 {
if k > self.se {
return Err(err("AC refinement past the band"));
}
blk[k] = new_value;
}
k += 1;
}
}
if self.eob_run != 0 {
while k <= self.se {
if blk[k] != 0 && self.bits.get(1) != 0 && (blk[k].unsigned_abs() & p1 as u32) == 0 {
blk[k] = if blk[k] < 0 { blk[k].wrapping_sub(p1) } else { blk[k].wrapping_add(p1) };
}
k += 1;
}
self.eob_run -= 1;
}
}
ArithMode::Sequential => return Err(err("invalid progressive scan mode")),
}
if self.bits.exhausted {
return Err(err("entropy-coded data ends before the scan does"));
}
Ok(())
}
}
+62 -3
View File
@@ -7,11 +7,11 @@
//! - sequential DCT, Huffman coded, 8 or 12-bit samples (SOF0 and SOF1; SOF0 files that declare
//! 12 bits are read as SOF1);
//! - extended sequential DCT, arithmetic coded, 8 or 12-bit (SOF9);
//! - progressive DCT, Huffman coded, 8 or 12-bit (SOF2);
//! - progressive DCT, arithmetic coded, 8 or 12-bit (SOF10).
//!
//! Every other frame returns [`Error::Unsupported`]: progressive Huffman (SOF2), lossless (SOF3,
//! SOF11) and hierarchical (SOF5–SOF7, SOF13–SOF15) files, and DCT precisions other than 8 and
//! 12 bits.
//! Every other frame returns [`Error::Unsupported`]: lossless (SOF3, SOF11) and hierarchical
//! (SOF5–SOF7, SOF13–SOF15) files, and DCT precisions other than 8 and 12 bits.
//!
//! [`Bands`] decodes the common case, a sequential Huffman-coded 8-bit frame in one scan, a band
//! of rows at a time, into the samples [`decode`] would give for those rows, so that images too
@@ -69,6 +69,65 @@ fn unsupported(m: impl Into<String>) -> Error {
Error::Unsupported(m.into())
}
/// Annex K Huffman tables used by AVI1 Motion JPEG streams that omit DHT.
const AVI1_DEFAULT_DHT: &[u8] = &[
0xFF, 0xC4, 0x01, 0xA2, 0x00, 0x00, 0x01, 0x05, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x02,
0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x01, 0x00, 0x03, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x10, 0x00, 0x02, 0x01, 0x03, 0x03, 0x02, 0x04, 0x03, 0x05,
0x05, 0x04, 0x04, 0x00, 0x00, 0x01, 0x7D, 0x01, 0x02, 0x03, 0x00, 0x04, 0x11, 0x05, 0x12, 0x21, 0x31, 0x41, 0x06, 0x13, 0x51, 0x61, 0x07, 0x22,
0x71, 0x14, 0x32, 0x81, 0x91, 0xA1, 0x08, 0x23, 0x42, 0xB1, 0xC1, 0x15, 0x52, 0xD1, 0xF0, 0x24, 0x33, 0x62, 0x72, 0x82, 0x09, 0x0A, 0x16, 0x17,
0x18, 0x19, 0x1A, 0x25, 0x26, 0x27, 0x28, 0x29, 0x2A, 0x34, 0x35, 0x36, 0x37, 0x38, 0x39, 0x3A, 0x43, 0x44, 0x45, 0x46, 0x47, 0x48, 0x49, 0x4A,
0x53, 0x54, 0x55, 0x56, 0x57, 0x58, 0x59, 0x5A, 0x63, 0x64, 0x65, 0x66, 0x67, 0x68, 0x69, 0x6A, 0x73, 0x74, 0x75, 0x76, 0x77, 0x78, 0x79, 0x7A,
0x83, 0x84, 0x85, 0x86, 0x87, 0x88, 0x89, 0x8A, 0x92, 0x93, 0x94, 0x95, 0x96, 0x97, 0x98, 0x99, 0x9A, 0xA2, 0xA3, 0xA4, 0xA5, 0xA6, 0xA7, 0xA8,
0xA9, 0xAA, 0xB2, 0xB3, 0xB4, 0xB5, 0xB6, 0xB7, 0xB8, 0xB9, 0xBA, 0xC2, 0xC3, 0xC4, 0xC5, 0xC6, 0xC7, 0xC8, 0xC9, 0xCA, 0xD2, 0xD3, 0xD4, 0xD5,
0xD6, 0xD7, 0xD8, 0xD9, 0xDA, 0xE1, 0xE2, 0xE3, 0xE4, 0xE5, 0xE6, 0xE7, 0xE8, 0xE9, 0xEA, 0xF1, 0xF2, 0xF3, 0xF4, 0xF5, 0xF6, 0xF7, 0xF8, 0xF9,
0xFA, 0x11, 0x00, 0x02, 0x01, 0x02, 0x04, 0x04, 0x03, 0x04, 0x07, 0x05, 0x04, 0x04, 0x00, 0x01, 0x02, 0x77, 0x00, 0x01, 0x02, 0x03, 0x11, 0x04,
0x05, 0x21, 0x31, 0x06, 0x12, 0x41, 0x51, 0x07, 0x61, 0x71, 0x13, 0x22, 0x32, 0x81, 0x08, 0x14, 0x42, 0x91, 0xA1, 0xB1, 0xC1, 0x09, 0x23, 0x33,
0x52, 0xF0, 0x15, 0x62, 0x72, 0xD1, 0x0A, 0x16, 0x24, 0x34, 0xE1, 0x25, 0xF1, 0x17, 0x18, 0x19, 0x1A, 0x26, 0x27, 0x28, 0x29, 0x2A, 0x35, 0x36,
0x37, 0x38, 0x39, 0x3A, 0x43, 0x44, 0x45, 0x46, 0x47, 0x48, 0x49, 0x4A, 0x53, 0x54, 0x55, 0x56, 0x57, 0x58, 0x59, 0x5A, 0x63, 0x64, 0x65, 0x66,
0x67, 0x68, 0x69, 0x6A, 0x73, 0x74, 0x75, 0x76, 0x77, 0x78, 0x79, 0x7A, 0x82, 0x83, 0x84, 0x85, 0x86, 0x87, 0x88, 0x89, 0x8A, 0x92, 0x93, 0x94,
0x95, 0x96, 0x97, 0x98, 0x99, 0x9A, 0xA2, 0xA3, 0xA4, 0xA5, 0xA6, 0xA7, 0xA8, 0xA9, 0xAA, 0xB2, 0xB3, 0xB4, 0xB5, 0xB6, 0xB7, 0xB8, 0xB9, 0xBA,
0xC2, 0xC3, 0xC4, 0xC5, 0xC6, 0xC7, 0xC8, 0xC9, 0xCA, 0xD2, 0xD3, 0xD4, 0xD5, 0xD6, 0xD7, 0xD8, 0xD9, 0xDA, 0xE2, 0xE3, 0xE4, 0xE5, 0xE6, 0xE7,
0xE8, 0xE9, 0xEA, 0xF2, 0xF3, 0xF4, 0xF5, 0xF6, 0xF7, 0xF8, 0xF9, 0xFA,
];
/// Insert Annex K Huffman tables into an AVI1 MJPEG frame that omits DHT.
///
/// Frames that are not JPEG, already define DHT, or do not reach SOS are returned unchanged.
/// The caller should use this only for an AVI1/MJPEG stream, since ordinary JPEG streams must
/// provide their own tables.
pub fn with_avi1_default_huffman(jpeg: &[u8]) -> std::borrow::Cow<'_, [u8]> {
use std::borrow::Cow;
if jpeg.get(..2) != Some(&[0xFF, 0xD8]) {
return Cow::Borrowed(jpeg);
}
let mut at = 2usize;
while at + 1 < jpeg.len() && jpeg[at] == 0xFF {
let marker = jpeg[at + 1];
match marker {
0xC4 => return Cow::Borrowed(jpeg),
0xDA => {
let mut out = Vec::with_capacity(jpeg.len().saturating_add(AVI1_DEFAULT_DHT.len()));
out.extend_from_slice(&jpeg[..at]);
out.extend_from_slice(AVI1_DEFAULT_DHT);
out.extend_from_slice(&jpeg[at..]);
return Cow::Owned(out);
}
0xD0..=0xD9 | 0x01 => at += 2,
0xFF => at += 1,
_ => {
let Some(len) = jpeg.get(at + 2..at + 4).map(|b| usize::from(u16::from_be_bytes([b[0], b[1]]))) else { break };
if len < 2 {
break;
}
let Some(next) = at.checked_add(2 + len).filter(|&n| n <= jpeg.len()) else { break };
at = next;
}
}
}
Cow::Borrowed(jpeg)
}
/// Decompression-bomb guards, checked against the frame header before any image buffer is
/// allocated.
///
+1 -1
View File
@@ -162,7 +162,7 @@ pub(super) fn parse_header(marker: u8, seg: &[u8]) -> Result<Header, Error> {
0xC0 | 0xC1 => (false, false),
0xC9 => (true, false),
0xCA => (true, true),
0xC2 => return Err(unsupported("progressive Huffman-coded JPEG is not supported")),
0xC2 => (false, true),
0xC3 | 0xCB => return Err(unsupported("lossless JPEG is not supported")),
_ => return Err(unsupported("hierarchical JPEG is not supported")),
};
+23 -4
View File
@@ -185,12 +185,31 @@ pub(super) fn decode_scan(frame: &mut Frame, tables: &Tables, scan: &Scan, d: &[
} else {
let mut sel = Vec::with_capacity(scan.comps.len());
for &(_, td, ta) in &scan.comps {
let dc = tables.dc.get(td).and_then(Option::as_ref).ok_or_else(|| err("scan uses an undefined Huffman table"))?;
let ac = tables.ac.get(ta).and_then(Option::as_ref).ok_or_else(|| err("scan uses an undefined Huffman table"))?;
let dc = tables.dc.get(td).and_then(Option::as_ref);
let ac = tables.ac.get(ta).and_then(Option::as_ref);
let (dc, ac) = if frame.progressive && scan.ss != 0 {
let ac = ac.ok_or_else(|| err("scan uses an undefined AC Huffman table"))?;
(dc.unwrap_or(ac), ac)
} else {
let dc = dc.ok_or_else(|| err("scan uses an undefined DC Huffman table"))?;
(dc, ac.unwrap_or(dc))
};
sel.push((dc, ac));
}
let mut dec = HuffmanScan { bits: Bits::new(d), tables: sel, pred: [0; 4] };
walk_scan(frame, scan, tables.restart, &mut dec, done)
if frame.progressive {
let mode = match (scan.ss, scan.ah) {
(0, 0) => ArithMode::DcFirst,
(0, _) => ArithMode::DcRefine,
(_, 0) => ArithMode::AcFirst,
(_, _) => ArithMode::AcRefine,
};
let mut dec =
ProgressiveHuffmanScan { bits: Bits::new(d), tables: sel, mode, ss: scan.ss, se: scan.se, al: scan.al, pred: [0; 4], eob_run: 0 };
walk_scan(frame, scan, tables.restart, &mut dec, done)
} else {
let mut dec = HuffmanScan { bits: Bits::new(d), tables: sel, pred: [0; 4] };
walk_scan(frame, scan, tables.restart, &mut dec, done)
}
}
}
+44
View File
@@ -621,6 +621,50 @@ fn extended_huffman_matches_zune_on_baseline_data() {
}
#[test]
fn progressive_huffman_matches_zune() {
let bytes = include_bytes!("../tests/data/testorig-huffman-progressive.jpg");
let (reference, (w, h)) = zune_decode(bytes);
let ours = decode_default(bytes).unwrap();
assert_eq!((ours.width, ours.height, ours.components), (w, h, 3));
assert!(!ours.damaged);
let Samples::U8(samples) = ours.samples else { panic!("8-bit fixture decoded with another precision") };
let mad = samples.iter().zip(&reference).map(|(&a, &b)| f32::from(a.abs_diff(b))).sum::<f32>() / samples.len() as f32;
assert!(mad < 2.0, "mean absolute difference {mad}");
}
#[test]
fn avi1_default_huffman_tables_restore_a_missing_dht() {
let fixture = include_bytes!("../tests/data/testorig.jpg");
let mut without = fixture[..2].to_vec();
let mut at = 2;
while at + 1 < fixture.len() {
if fixture[at] != 0xFF {
break;
}
let marker = fixture[at + 1];
if marker == 0xDA {
without.extend_from_slice(&fixture[at..]);
break;
}
if marker == 0xC4 {
let len = usize::from(u16::from_be_bytes([fixture[at + 2], fixture[at + 3]]));
at += 2 + len;
} else if (0xD0..=0xD9).contains(&marker) || marker == 0x01 {
without.extend_from_slice(&fixture[at..at + 2]);
at += 2;
} else {
let len = usize::from(u16::from_be_bytes([fixture[at + 2], fixture[at + 3]]));
without.extend_from_slice(&fixture[at..at + 2 + len]);
at += 2 + len;
}
}
assert!(matches!(with_avi1_default_huffman(&without), std::borrow::Cow::Owned(_)));
let restored = with_avi1_default_huffman(&without);
let decoded = decode_default(&restored).unwrap();
let expected = decode_default(fixture).unwrap();
assert_eq!(decoded, expected);
assert!(matches!(with_avi1_default_huffman(fixture), std::borrow::Cow::Borrowed(_)));
}
fn limits_are_checked_before_allocating() {
let mut s = vec![0xFF, 0xD8];
segment(&mut s, 0xC9, &[8, 0xFF, 0xFF, 0xFF, 0xFF, 3, 1, 0x44, 0, 2, 0x11, 0, 3, 0x11, 0]);
+1
View File
@@ -9,3 +9,4 @@ acc6ec555d41d15b368320edaa3b20958ee6fa97cb6e4a18d1213d5ae8bec73b testorig.jpg
cb0a2c60e6a89c68ef8cf48854dc09c77c26ffb27ac62e17d343d98f1424cc77 testorig-ari-progressive-restart.jpg
c4942c4b704d20e27c4cd3e613c6ef975dd7cfe53a756e2c209fa3ad033d8b51 testorig12-ari.jpg
18df0394115d9f8751939fb9f45a0d330df2ca849e9f8b07d0af76c09b90fcdb testorig12-ari-progressive.jpg
5fecfaa2e0f79a52d207b9b13b39f96f5d5bd2958ec80fcf585d82cd93f62bdd testorig-huffman-progressive.jpg
+1
View File
@@ -9,6 +9,7 @@ libjpeg-turbo's tools, as described below.
| File | What it is |
|---|---|
| `testorig.jpg` | 227×149 YCbCr, 2×2 luma sampling, baseline Huffman (SOF0) |
| `testorig-huffman-progressive.jpg` | `testorig.jpg` decoded to PPM with FFmpeg, then re-encoded with libjpeg-turbo `cjpeg -progressive -quality 88` (SOF2) |
| `testimgari.jpg` | the same image, arithmetic coded (SOF9), one interleaved scan |
| `testimgari-huffman.jpg` | `testimgari.jpg` losslessly transcoded to baseline Huffman (SOF0) |
| `testorig12.jpg` | 227×149 YCbCr, 12-bit extended sequential Huffman (SOF1) |
Binary file not shown.

After

Width:  |  Height:  |  Size: 6.6 KiB

+1 -1
View File
@@ -490,7 +490,7 @@ impl Loaded {
/// notes why not otherwise.
fn add(&mut self, name: &str, overrides: Option<Overrides>) {
let shown = || name.chars().take(MAX_SET_NAME).collect::<String>();
if !set_name(name).is_some_and(|n| n == name) {
if set_name(name).is_none_or(|n| n != name) {
self.note(SetProblem::BadName { name: shown() });
} else if self.sets.contains_key(name) {
self.note(SetProblem::Duplicate { name: shown() });

Some files were not shown because too many files have changed in this diff Show More