Merge main and reconcile Vorbis encoding with current audio APIs

This commit is contained in:
Dylan M. Taylor
2026-11-14 18:12:03 -05:00
133 changed files with 9613 additions and 474 deletions
+188
View File
@@ -0,0 +1,188 @@
# This file is machine-generated by `gh actions-lock`.
# Do not edit by hand; run `gh actions-lock` to update.
# Docs: https://gh.io/actions-lockfile
version: 'v0.0.3'
workflows:
'.github/workflows/ai-core.yml':
- 'actions/checkout@v7.0.1'
- 'step-security/dtolnay-rust-toolchain@v1.0.0'
- 'step-security/harden-runner@v2.22.4'
'.github/workflows/atomic.yml':
- 'actions/checkout@v4.4.0'
- 'actions/checkout@v7.0.1'
- 'dtolnay/rust-toolchain@stable'
- 'step-security/dtolnay-rust-toolchain@v1.0.0'
- 'step-security/harden-runner@v2.22.4'
'.github/workflows/audio.yml':
- 'actions/cache@v6.1.0'
- 'actions/checkout@v7.0.1'
- 'step-security/dtolnay-rust-toolchain@v1.0.0'
- 'step-security/harden-runner@v2.22.4'
- 'step-security/rust-cache@v2.9.2'
'.github/workflows/cms.yml':
- 'actions/checkout@v4.4.0'
- 'dtolnay/rust-toolchain@stable'
'.github/workflows/crw.yml':
- 'actions/cache@v6.1.0'
- 'actions/checkout@v7.0.1'
- 'step-security/dtolnay-rust-toolchain@v1.0.0'
- 'step-security/harden-runner@v2.22.4'
- 'step-security/rust-cache@v2.9.2'
'.github/workflows/dialogs.yml':
- 'actions/checkout@v7.0.1'
- 'step-security/dtolnay-rust-toolchain@v1.0.0'
- 'step-security/harden-runner@v2.22.4'
'.github/workflows/doc.yml':
- 'actions/checkout@v7.0.1'
- 'step-security/dtolnay-rust-toolchain@v1.0.0'
- 'step-security/harden-runner@v2.22.4'
'.github/workflows/docpath.yml':
- 'actions/checkout@v7.0.1'
- 'step-security/dtolnay-rust-toolchain@v1.0.0'
- 'step-security/harden-runner@v2.22.4'
'.github/workflows/ecproj-format.yml':
- 'actions/checkout@v7.0.1'
- 'step-security/dtolnay-rust-toolchain@v1.0.0'
- 'step-security/harden-runner@v2.22.4'
'.github/workflows/font-store.yml':
- 'actions/checkout@v7.0.1'
- 'step-security/dtolnay-rust-toolchain@v1.0.0'
- 'step-security/harden-runner@v2.22.4'
'.github/workflows/formats.yml':
- 'actions/checkout@v7.0.1'
- 'dtolnay/rust-toolchain@stable'
- 'step-security/harden-runner@v2.22.4'
- 'swatinem/rust-cache@v2.9.3'
'.github/workflows/house-rules.yml': []
'.github/workflows/i18n.yml':
- 'actions/checkout@v7.0.1'
- 'step-security/dtolnay-rust-toolchain@v1.0.0'
- 'step-security/harden-runner@v2.22.4'
'.github/workflows/jpeg.yml':
- 'actions/checkout@v7.0.1'
- 'step-security/dtolnay-rust-toolchain@v1.0.0'
- 'step-security/harden-runner@v2.22.4'
- 'step-security/rust-cache@v2.9.2'
'.github/workflows/keymap.yml':
- 'actions/checkout@v7.0.1'
- 'step-security/dtolnay-rust-toolchain@v1.0.0'
- 'step-security/harden-runner@v2.22.4'
- 'step-security/rust-cache@v2.9.2'
'.github/workflows/lockfile.yml':
- 'actions/checkout@v7.0.1'
- 'step-security/harden-runner@v2.22.4'
'.github/workflows/media.yml':
- 'actions/checkout@v7.0.1'
- 'step-security/dtolnay-rust-toolchain@v1.0.0'
- 'step-security/harden-runner@v2.22.4'
- 'step-security/rust-cache@v2.9.2'
'.github/workflows/menu.yml':
- 'actions/checkout@v7.0.1'
- 'dtolnay/rust-toolchain@stable'
- 'swatinem/rust-cache@v2.9.3'
'.github/workflows/pcraft-format.yml':
- 'actions/checkout@v7.0.1'
- 'step-security/dtolnay-rust-toolchain@v1.0.0'
- 'step-security/harden-runner@v2.22.4'
'.github/workflows/pdf.yml':
- 'actions/checkout@v7.0.1'
- 'actions/setup-python@v7.1.0'
- 'step-security/dtolnay-rust-toolchain@v1.0.0'
- 'step-security/harden-runner@v2.22.4'
- 'step-security/rust-cache@v2.9.2'
- 'step-security/taiki-e-install-action@v2.87.32'
'.github/workflows/print.yml':
- 'actions/checkout@v7.0.1'
- 'step-security/dtolnay-rust-toolchain@v1.0.0'
- 'step-security/harden-runner@v2.22.4'
'.github/workflows/proof.yml':
- 'actions/checkout@v7.0.1'
- 'step-security/dtolnay-rust-toolchain@v1.0.0'
- 'step-security/harden-runner@v2.22.4'
- 'step-security/rust-cache@v2.9.2'
'.github/workflows/sonarcloud.yml': []
'.github/workflows/ui.yml':
- 'actions/checkout@v7.0.1'
- 'step-security/dtolnay-rust-toolchain@v1.0.0'
- 'step-security/harden-runner@v2.22.4'
- 'step-security/rust-cache@v2.9.2'
'.github/workflows/update.yml':
- 'actions/checkout@v7.0.1'
- 'step-security/dtolnay-rust-toolchain@v1.0.0'
- 'step-security/harden-runner@v2.22.4'
'.github/workflows/vectorcraft-format.yml':
- 'actions/checkout@v7.0.1'
- 'step-security/dtolnay-rust-toolchain@v1.0.0'
- 'step-security/harden-runner@v2.22.4'
'.github/workflows/video.yml':
- 'actions/checkout@v7.0.1'
- 'step-security/dtolnay-rust-toolchain@v1.0.0'
- 'step-security/harden-runner@v2.22.4'
- 'step-security/rust-cache@v2.9.2'
'.github/workflows/web-api.yml':
- 'actions/checkout@v7.0.1'
- 'step-security/dtolnay-rust-toolchain@v1.0.0'
- 'step-security/harden-runner@v2.22.4'
- 'step-security/taiki-e-install-action@v2.87.32'
'.github/workflows/web-host.yml':
- 'actions/checkout@v7.0.1'
- 'step-security/dtolnay-rust-toolchain@v1.0.0'
- 'step-security/harden-runner@v2.22.4'
- 'step-security/rust-cache@v2.9.2'
- 'step-security/taiki-e-install-action@v2.87.32'
'.github/workflows/window.yml':
- 'actions/checkout@v7.0.1'
- 'step-security/dtolnay-rust-toolchain@v1.0.0'
- 'step-security/harden-runner@v2.22.4'
'.github/workflows/workspace.yml': []
dependencies:
'actions/cache@v6.1.0':
ref: 'v6.1.0'
commit: 'sha1-55cc8345863c7cc4c66a329aec7e433d2d1c52a9'
owner_id: 44036562
repo_id: 215566462
'actions/checkout@v4.4.0':
ref: 'v4.4.0'
commit: 'sha1-11d5960a326750d5838078e36cf38b85af677262'
owner_id: 44036562
repo_id: 197814629
'actions/checkout@v7.0.1':
ref: 'v7.0.1'
commit: 'sha1-3d3c42e5aac5ba805825da76410c181273ba90b1'
owner_id: 44036562
repo_id: 197814629
'actions/setup-python@v7.1.0':
ref: 'v7.1.0'
commit: 'sha1-6d4fd22b20465ccc0f7354476588e8df7c9ca0e0'
owner_id: 44036562
repo_id: 192625525
'dtolnay/rust-toolchain@stable':
ref: 'stable'
commit: 'sha1-b725eda525362e7cf34af9a7243cac1e3f01a7ec'
owner_id: 1940490
repo_id: 260749683
'step-security/dtolnay-rust-toolchain@v1.0.0':
ref: 'v1.0.0'
commit: 'sha1-8dd607977d06adf4ed49b190381e74c17a9dd25f'
owner_id: 88700172
repo_id: 1249865941
'step-security/harden-runner@v2.22.4':
ref: 'v2.22.4'
commit: 'sha1-1d88384fd173af6ecb012dfd0264a306b711241a'
owner_id: 88700172
repo_id: 422287306
'step-security/rust-cache@v2.9.2':
ref: 'v2.9.2'
commit: 'sha1-8871c8ba063416da7c32246932ea6ae08700453e'
owner_id: 88700172
repo_id: 822636713
'step-security/taiki-e-install-action@v2.87.32':
ref: 'v2.87.32'
commit: 'sha1-76747d22a7567cc4438546a84f11bdf18e670ab8'
owner_id: 88700172
repo_id: 1382753260
'swatinem/rust-cache@v2.9.3':
ref: 'v2.9.3'
commit: 'sha1-d1527c8f67ef9af357290475d4af4b0fab8f12e0'
owner_id: 580492
repo_id: 298565987
+3 -3
View File
@@ -28,11 +28,11 @@ jobs:
runs-on: ${{ matrix.os }}
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@v7
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: actions/checkout@v7.0.1
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: stable
components: rustfmt, clippy
+4 -4
View File
@@ -28,11 +28,11 @@ jobs:
runs-on: ${{ matrix.os }}
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@v7
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: actions/checkout@v7.0.1
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: stable
components: rustfmt, clippy
@@ -50,7 +50,7 @@ jobs:
name: Atomic WASM
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/checkout@v4.4.0
- uses: dtolnay/rust-toolchain@stable
with:
targets: wasm32-unknown-unknown
+16 -16
View File
@@ -25,18 +25,18 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/checkout@v7.0.1
with:
persist-credentials: false
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: stable
components: rustfmt, clippy
targets: wasm32-unknown-unknown
- uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2
- uses: step-security/rust-cache@v2.9.2
with:
key: craft-audio-lint
save-if: ${{ github.ref == 'refs/heads/main' }}
@@ -69,15 +69,15 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/checkout@v7.0.1
with:
persist-credentials: false
# The workspace's rust-version.
- run: rustup toolchain install 1.95.0 --profile minimal
- uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2
- uses: step-security/rust-cache@v2.9.2
with:
key: craft-audio-msrv
save-if: ${{ github.ref == 'refs/heads/main' }}
@@ -88,16 +88,16 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/checkout@v7.0.1
with:
persist-credentials: false
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: stable
- uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2
- uses: step-security/rust-cache@v2.9.2
with:
key: craft-audio-features
save-if: ${{ github.ref == 'refs/heads/main' }}
@@ -113,20 +113,20 @@ jobs:
runs-on: ubuntu-26.04
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/checkout@v7.0.1
with:
persist-credentials: false
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: stable
- uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2
- uses: step-security/rust-cache@v2.9.2
with:
key: craft-audio-test
save-if: ${{ github.ref == 'refs/heads/main' }}
- uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
- uses: actions/cache@v6.1.0
with:
path: ${{ runner.temp }}/media-fixtures/opus/vectors
# The archive's SHA-256 (scripts/fetch-opus-vectors.sh checks it).
+1 -1
View File
@@ -16,7 +16,7 @@ jobs:
timeout-minutes: 20
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/checkout@v4.4.0
- uses: dtolnay/rust-toolchain@stable
with:
components: clippy
+13 -13
View File
@@ -29,17 +29,17 @@ jobs:
runs-on: ${{ matrix.os }}
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@v7
- uses: actions/checkout@v7.0.1
with:
persist-credentials: false
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: stable
components: rustfmt, clippy
- uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2
- uses: step-security/rust-cache@v2.9.2
with:
key: craft-crw-${{ matrix.os }}
save-if: ${{ github.ref == 'refs/heads/main' }}
@@ -53,17 +53,17 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@v7
- uses: actions/checkout@v7.0.1
with:
persist-credentials: false
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: stable
targets: wasm32-unknown-unknown
- uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2
- uses: step-security/rust-cache@v2.9.2
with:
key: craft-crw-wasm
save-if: ${{ github.ref == 'refs/heads/main' }}
@@ -75,21 +75,21 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@v7
- uses: actions/checkout@v7.0.1
with:
persist-credentials: false
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: stable
- uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2
- uses: step-security/rust-cache@v2.9.2
with:
key: craft-crw-samples
save-if: ${{ github.ref == 'refs/heads/main' }}
- name: Cache the CC0 sample files
uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
uses: actions/cache@v6.1.0
with:
path: ${{ runner.temp }}/crw-samples
key: crw-samples-${{ hashFiles('crates/crw/tests/samples.json') }}
+3 -3
View File
@@ -23,15 +23,15 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@v7
- uses: actions/checkout@v7.0.1
with:
# The token isn't needed after checkout; cargo runs build scripts and proc macros from
# dependencies, so don't leave it in .git/config for that third-party code to read.
persist-credentials: false
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: stable
components: clippy
+3 -3
View File
@@ -28,13 +28,13 @@ jobs:
runs-on: ${{ matrix.os }}
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@v7
- uses: actions/checkout@v7.0.1
with:
persist-credentials: false
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: stable
components: rustfmt, clippy
+3 -3
View File
@@ -28,11 +28,11 @@ jobs:
runs-on: ${{ matrix.os }}
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@v7
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: actions/checkout@v7.0.1
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: stable
components: rustfmt, clippy
+3 -3
View File
@@ -28,13 +28,13 @@ jobs:
runs-on: ${{ matrix.os }}
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@v7
- uses: actions/checkout@v7.0.1
with:
persist-credentials: false
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: stable
components: rustfmt, clippy
+3 -3
View File
@@ -28,11 +28,11 @@ jobs:
runs-on: ${{ matrix.os }}
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: actions/checkout@v7.0.1
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: stable
components: rustfmt, clippy
+4 -4
View File
@@ -72,17 +72,17 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/checkout@v7.0.1
with:
persist-credentials: false
- uses: dtolnay/rust-toolchain@b725eda525362e7cf34af9a7243cac1e3f01a7ec # stable
- uses: dtolnay/rust-toolchain@stable
with:
components: rustfmt, clippy
targets: wasm32-unknown-unknown
- uses: Swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3
- uses: Swatinem/rust-cache@v2.9.3
with:
key: ${{ matrix.crate }}
save-if: ${{ github.ref == 'refs/heads/main' }}
+3 -3
View File
@@ -28,11 +28,11 @@ jobs:
runs-on: ${{ matrix.os }}
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@v7
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: actions/checkout@v7.0.1
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: stable
components: rustfmt, clippy
+4 -4
View File
@@ -25,18 +25,18 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/checkout@v7.0.1
with:
persist-credentials: false
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: stable
components: rustfmt, clippy
targets: wasm32-unknown-unknown
- uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2
- uses: step-security/rust-cache@v2.9.2
with:
key: craft-jpeg
save-if: ${{ github.ref == 'refs/heads/main' }}
+14 -14
View File
@@ -27,24 +27,24 @@ jobs:
CRAFT_FONTS_DIR: ${{ github.workspace }}/.test-inputs/craft-fonts
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@v7
- uses: actions/checkout@v7.0.1
with:
persist-credentials: false
- name: Checkout test fonts
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
uses: actions/checkout@v7.0.1
with:
repository: storytold/craft-fonts
ref: b076417b5880bd4154bd22f00695b1d28c6bea83
path: .test-inputs/craft-fonts
persist-credentials: false
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: stable
components: rustfmt, clippy
- uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2
- uses: step-security/rust-cache@v2.9.2
with:
key: craft-keymap-linux
save-if: ${{ github.ref == 'refs/heads/main' }}
@@ -71,23 +71,23 @@ jobs:
CRAFT_FONTS_DIR: ${{ github.workspace }}/.test-inputs/craft-fonts
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@v7
- uses: actions/checkout@v7.0.1
with:
persist-credentials: false
- name: Checkout test fonts
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
uses: actions/checkout@v7.0.1
with:
repository: storytold/craft-fonts
ref: b076417b5880bd4154bd22f00695b1d28c6bea83
path: .test-inputs/craft-fonts
persist-credentials: false
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: stable
- uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2
- uses: step-security/rust-cache@v2.9.2
with:
key: craft-keymap-${{ matrix.os }}
save-if: ${{ github.ref == 'refs/heads/main' }}
@@ -98,17 +98,17 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@v7
- uses: actions/checkout@v7.0.1
with:
persist-credentials: false
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: stable
targets: wasm32-unknown-unknown
- uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2
- uses: step-security/rust-cache@v2.9.2
with:
key: craft-keymap-wasm
save-if: ${{ github.ref == 'refs/heads/main' }}
+34
View File
@@ -0,0 +1,34 @@
name: Lockfile
# Fails when .github/workflows/actions.lock is out of sync with the workflows, or when a locked pin
# no longer verifies upstream, so a moved tag cannot slip a different commit into a run.
# Docs: https://gh.io/actions-lockfile
on:
pull_request:
push:
branches: [main]
workflow_dispatch:
permissions:
contents: read
env:
GH_TOKEN: ${{ github.token }}
jobs:
lockfile:
name: Lockfile is in sync
runs-on: ubuntu-24.04
timeout-minutes: 10
steps:
- name: Harden runner
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@v7.0.1
with:
persist-credentials: false
- name: Install gh-actions-lock
run: gh extension install github/gh-actions-lock --pin v0.4.1
- name: Verify the lockfile
run: gh actions-lock --verify
+8 -8
View File
@@ -25,18 +25,18 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@v7
- uses: actions/checkout@v7.0.1
with:
persist-credentials: false
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: stable
components: rustfmt, clippy
targets: wasm32-unknown-unknown
- uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2
- uses: step-security/rust-cache@v2.9.2
with:
key: craft-media-lint
save-if: ${{ github.ref == 'refs/heads/main' }}
@@ -56,16 +56,16 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@v7
- uses: actions/checkout@v7.0.1
with:
persist-credentials: false
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: stable
- uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2
- uses: step-security/rust-cache@v2.9.2
with:
key: craft-media-test
save-if: ${{ github.ref == 'refs/heads/main' }}
+3 -3
View File
@@ -21,14 +21,14 @@ jobs:
name: Menu (Linux)
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: actions/checkout@v7.0.1
with:
persist-credentials: false
- uses: dtolnay/rust-toolchain@b725eda525362e7cf34af9a7243cac1e3f01a7ec # stable
- uses: dtolnay/rust-toolchain@stable
with:
components: rustfmt, clippy
targets: aarch64-apple-darwin, wasm32-unknown-unknown
- uses: Swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3
- uses: Swatinem/rust-cache@v2.9.3
with:
key: craft-menu-linux
- run: cargo fmt -p craft-menu --check
+3 -3
View File
@@ -28,13 +28,13 @@ jobs:
runs-on: ${{ matrix.os }}
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/checkout@v7.0.1
with:
persist-credentials: false
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: "1.95"
components: rustfmt, clippy
+20 -20
View File
@@ -31,19 +31,19 @@ jobs:
RUSTFLAGS: --cfg craft_pdf_unicode_fixtures
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@v7
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: actions/checkout@v7.0.1
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: stable
components: rustfmt, clippy
- uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2
- uses: step-security/rust-cache@v2.9.2
with:
key: craft-pdf
save-if: ${{ github.ref == 'refs/heads/main' }}
- uses: actions/setup-python@v7
- uses: actions/setup-python@v7.1.0
with:
python-version: "3.12"
- name: Provision licensed PDF test fonts
@@ -61,14 +61,14 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@v7
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: actions/checkout@v7.0.1
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: stable
- uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2
- uses: step-security/rust-cache@v2.9.2
with:
key: craft-pdf-backends
save-if: ${{ github.ref == 'refs/heads/main' }}
@@ -81,19 +81,19 @@ jobs:
CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUNNER: wasm-bindgen-test-runner
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@v7
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: actions/checkout@v7.0.1
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: stable
targets: wasm32-unknown-unknown
- uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2
- uses: step-security/rust-cache@v2.9.2
with:
key: craft-pdf-wasm
save-if: ${{ github.ref == 'refs/heads/main' }}
- uses: actions/setup-python@v7
- uses: actions/setup-python@v7.1.0
with:
python-version: "3.12"
- name: Provision licensed PDF test fonts
@@ -111,7 +111,7 @@ jobs:
- name: Install the matching WASM test runner
# A prebuilt, checksum-verified binary instead of building it from source on every run.
# A version the pinned action does not list yet falls back to `cargo install --locked`.
uses: step-security/taiki-e-install-action@76747d22a7567cc4438546a84f11bdf18e670ab8 # v2.87.32
uses: step-security/taiki-e-install-action@v2.87.32
with:
tool: wasm-bindgen@${{ steps.wasm-bindgen.outputs.version }}
fallback: cargo-install
@@ -122,19 +122,19 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@v7
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: actions/checkout@v7.0.1
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: stable
components: clippy
- uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2
- uses: step-security/rust-cache@v2.9.2
with:
key: craft-plate-test
save-if: ${{ github.ref == 'refs/heads/main' }}
- uses: actions/setup-python@v7
- uses: actions/setup-python@v7.1.0
with:
python-version: "3.12"
- name: Provision licensed PDF test fonts
+3 -3
View File
@@ -24,11 +24,11 @@ jobs:
runs-on: ${{ matrix.os }}
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@v7
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: actions/checkout@v7.0.1
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: stable
components: rustfmt, clippy
+5 -5
View File
@@ -25,27 +25,27 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/checkout@v7.0.1
with:
persist-credentials: false
# The Language data (craft-i18n `language-data/`), embedded by crates/proof/build.rs.
# Pinned to storytold/craft-i18n#114's head (#109's SCOWL dictionaries + judgment/judgement,
# CP2.1); TODO(CP2.1): move to #114's merge commit once it merges.
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/checkout@v7.0.1
with:
repository: storytold/craft-i18n
ref: c239f934ace90b7939afaceb23b472ceeafd6b8a
path: craft-i18n
persist-credentials: false
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: stable
components: rustfmt, clippy
targets: wasm32-unknown-unknown
- uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2
- uses: step-security/rust-cache@v2.9.2
with:
key: craft-proof
save-if: ${{ github.ref == 'refs/heads/main' }}
+8 -8
View File
@@ -30,21 +30,21 @@ jobs:
runs-on: ${{ matrix.os }}
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@v7
- uses: actions/checkout@v7.0.1
- name: Install software Vulkan renderer
if: runner.os == 'Linux'
run: |
sudo apt-get update
sudo apt-get install -y mesa-vulkan-drivers libvulkan1
echo 'WGPU_BACKEND=vulkan' >> "$GITHUB_ENV"
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: stable
components: rustfmt, clippy
- uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2
- uses: step-security/rust-cache@v2.9.2
with:
key: craft-ui
save-if: ${{ github.ref == 'refs/heads/main' }}
@@ -59,15 +59,15 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@v7
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: actions/checkout@v7.0.1
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: stable
targets: wasm32-unknown-unknown
- uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2
- uses: step-security/rust-cache@v2.9.2
with:
key: craft-ui-wasm
save-if: ${{ github.ref == 'refs/heads/main' }}
+3 -3
View File
@@ -28,15 +28,15 @@ jobs:
runs-on: ${{ matrix.os }}
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/checkout@v7.0.1
with:
# The token isn't needed after checkout; cargo runs build scripts and proc macros from
# dependencies, so don't leave it in .git/config for that third-party code to read.
persist-credentials: false
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: stable
components: rustfmt, clippy
+3 -3
View File
@@ -28,13 +28,13 @@ jobs:
runs-on: ${{ matrix.os }}
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/checkout@v7.0.1
with:
persist-credentials: false
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: "1.95"
components: rustfmt, clippy
+8 -8
View File
@@ -22,18 +22,18 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/checkout@v7.0.1
with:
persist-credentials: false
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: "1.95"
components: rustfmt, clippy
targets: wasm32-unknown-unknown
- uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2
- uses: step-security/rust-cache@v2.9.2
with:
key: craft-video-lint
- run: cargo fmt -p craft-video --check
@@ -60,16 +60,16 @@ jobs:
name: Video tests (${{ matrix.os }})
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/checkout@v7.0.1
with:
persist-credentials: false
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: "1.95"
- uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2
- uses: step-security/rust-cache@v2.9.2
with:
key: craft-video-${{ matrix.os }}
- name: Install ffmpeg (Linux)
+4 -4
View File
@@ -26,13 +26,13 @@ jobs:
CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUNNER: wasm-bindgen-test-runner
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/checkout@v7.0.1
with:
persist-credentials: false
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: stable
components: rustfmt, clippy
@@ -46,7 +46,7 @@ jobs:
- name: Install the matching WASM test runner
# A prebuilt, checksum-verified binary instead of building it from source on every run.
# A version the pinned action does not list yet falls back to `cargo install --locked`.
uses: step-security/taiki-e-install-action@76747d22a7567cc4438546a84f11bdf18e670ab8 # v2.87.32
uses: step-security/taiki-e-install-action@v2.87.32
with:
tool: wasm-bindgen@${{ steps.wasm-bindgen.outputs.version }}
fallback: cargo-install
+5 -5
View File
@@ -27,18 +27,18 @@ jobs:
CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUNNER: wasm-bindgen-test-runner
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- uses: actions/checkout@v7.0.1
with:
persist-credentials: false
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: stable
components: rustfmt, clippy
targets: wasm32-unknown-unknown
- uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2
- uses: step-security/rust-cache@v2.9.2
with:
key: craft-web-host
save-if: ${{ github.ref == 'refs/heads/main' }}
@@ -55,7 +55,7 @@ jobs:
- name: Install the matching WASM test runner
# A prebuilt, checksum-verified binary instead of building it from source on every run.
# A version the pinned action does not list yet falls back to `cargo install --locked`.
uses: step-security/taiki-e-install-action@76747d22a7567cc4438546a84f11bdf18e670ab8 # v2.87.32
uses: step-security/taiki-e-install-action@v2.87.32
with:
tool: wasm-bindgen@${{ steps.wasm-bindgen.outputs.version }}
fallback: cargo-install
+3 -3
View File
@@ -28,15 +28,15 @@ jobs:
runs-on: ${{ matrix.os }}
steps:
- name: Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
uses: step-security/harden-runner@v2.22.4
with:
egress-policy: audit
- uses: actions/checkout@v7
- uses: actions/checkout@v7.0.1
with:
# The token isn't needed after checkout; cargo runs build scripts and proc macros from
# dependencies, so don't leave it in .git/config for that third-party code to read.
persist-credentials: false
- uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0
- uses: step-security/dtolnay-rust-toolchain@v1.0.0
with:
toolchain: stable
components: rustfmt, clippy
Generated
+92 -1
View File
@@ -1857,18 +1857,22 @@ dependencies = [
name = "craft-image-codecs"
version = "0.1.0"
dependencies = [
"avif-serialize",
"craft-heif",
"craft-jpeg",
"craft-metadata",
"exr",
"flate2",
"half",
"hayro-jpeg2000",
"image",
"image-webp",
"jpeg-encoder 0.6.1",
"jxl-oxide",
"png 0.18.1",
"proptest",
"rav1e",
"ravif",
"rayon",
"serde_json",
"thiserror 2.0.21",
@@ -2192,6 +2196,7 @@ dependencies = [
"bytemuck",
"chrono",
"craft-stream-codecs",
"craft-svg",
"flate2",
"hayro",
"hayro-cmap",
@@ -2199,6 +2204,7 @@ dependencies = [
"hayro-syntax",
"js-sys",
"krilla",
"krilla-svg",
"kurbo 0.13.1",
"md-5 0.11.0",
"proptest",
@@ -2208,6 +2214,7 @@ dependencies = [
"stringprep",
"thiserror 2.0.21",
"ttf-parser",
"usvg 0.47.0",
"wasm-bindgen",
"wasm-bindgen-test",
"zeroize",
@@ -2591,6 +2598,14 @@ dependencies = [
"unicode-segmentation",
]
[[package]]
name = "craft-texture"
version = "0.1.0"
dependencies = [
"rayon",
"thiserror 2.0.21",
]
[[package]]
name = "craft-tga"
version = "0.1.0"
@@ -2831,6 +2846,7 @@ name = "craft-xml"
version = "0.1.0"
dependencies = [
"quick-xml 0.41.0",
"serde",
"thiserror 2.0.21",
]
@@ -4064,6 +4080,20 @@ dependencies = [
"roxmltree 0.20.0",
]
[[package]]
name = "fontdb"
version = "0.23.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "457e789b3d1202543297a350643cf459f836cade38934e7a4cf6a39e7cde2905"
dependencies = [
"fontconfig-parser",
"log",
"memmap2",
"slotmap",
"tinyvec",
"ttf-parser",
]
[[package]]
name = "fontdb"
version = "0.24.0"
@@ -5659,6 +5689,22 @@ dependencies = [
"zune-jpeg",
]
[[package]]
name = "krilla-svg"
version = "0.8.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1237d7c37b16ca9fbc2e72dde13a10d321f9a44aceee35c062bc0a43bfc7ce16"
dependencies = [
"flate2",
"fontdb 0.23.0",
"krilla",
"resvg 0.47.0",
"skrifa 0.42.1",
"smallvec",
"tiny-skia 0.12.0",
"usvg 0.47.0",
]
[[package]]
name = "kurbo"
version = "0.11.3"
@@ -7875,6 +7921,23 @@ dependencies = [
"usvg 0.45.1",
]
[[package]]
name = "resvg"
version = "0.47.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9be183ad6a216aa96f33e4c8033b0988b8b3ea6fd2359d19af5bac4643fd8e81"
dependencies = [
"gif",
"image-webp",
"log",
"pico-args",
"rgb",
"svgtypes 0.16.2",
"tiny-skia 0.12.0",
"usvg 0.47.0",
"zune-jpeg",
]
[[package]]
name = "resvg"
version = "0.48.1"
@@ -9921,6 +9984,34 @@ dependencies = [
"xmlwriter",
]
[[package]]
name = "usvg"
version = "0.47.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d46cf96c5f498d36b7a9693bc6a7075c0bb9303189d61b2249b0dc3d309c07de"
dependencies = [
"base64 0.22.1",
"data-url",
"flate2",
"fontdb 0.23.0",
"imagesize 0.14.0",
"kurbo 0.13.1",
"log",
"pico-args",
"roxmltree 0.21.2",
"rustybuzz",
"simplecss",
"siphasher",
"strict-num",
"svgtypes 0.16.2",
"tiny-skia-path 0.12.0",
"ttf-parser",
"unicode-bidi",
"unicode-script",
"unicode-vo",
"xmlwriter",
]
[[package]]
name = "usvg"
version = "0.48.1"
@@ -9929,7 +10020,7 @@ checksum = "977d0a4abdef933f424a99fe09f95576e089b90aebc6f016a3bc813762493e91"
dependencies = [
"base64 0.23.1",
"data-url",
"fontdb",
"fontdb 0.24.0",
"harfrust 0.12.0",
"imagesize 0.15.0",
"kurbo 0.13.1",
+2 -1
View File
@@ -91,10 +91,10 @@ craft-keymap = { path = "crates/keymap" }
craft-assuan = { path = "crates/assuan" }
craft-kra = { path = "crates/kra" }
craft-audio = { path = "crates/audio" }
# No default features, so craft-audio's `encode` builds craft-media without `isobmff`.
craft-latex = { path = "crates/latex" }
craft-markdown = { path = "crates/markdown" }
craft-math = { path = "crates/math" }
# No default features: craft-audio turns on the craft-media modules each of its features needs.
craft-media = { path = "crates/media", default-features = false }
craft-materialx = { path = "crates/materialx" }
craft-media-testkit = { path = "crates/media-testkit" }
@@ -139,6 +139,7 @@ craft-stencilcraft-document = { path = "crates/stencilcraft-document" }
craft-svg-paths = { path = "crates/svg-paths" }
craft-stream-codecs = { path = "crates/stream-codecs" }
craft-text = { path = "crates/text" }
craft-texture = { path = "crates/texture" }
craft-tga = { path = "crates/tga" }
craft-timeline = { path = "crates/timeline" }
craft-tiff = { path = "crates/tiff" }
+4 -3
View File
@@ -254,9 +254,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 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, the local patch
vendor/linesweeper with its upstream license files and local patches, to src/sweep/sweep_line.rs and
docs/sweep.typ. Its manifest names Joe Neeman as author, and its LICENSE-MIT reads "Copyright (c) 2018
Raph Levien". See vendor/linesweeper/README.craft.md and vendor/linesweeper/SOURCE.json for
provenance, the local patches
and the files left out.
Platform lifecycle source provenance
+3
View File
@@ -348,6 +348,9 @@ See the [release notes](CHANGELOG.md) for included functionality and known limit
- [`craft-text`](crates/text/README.md): text processing below the composer. Its `hyphen` module finds
hyphenation points, with a bundled US English dictionary and patterns and optional hypher patterns
for 47 more languages (one cargo feature each).
- [`craft-texture`](crates/texture/README.md): linear float image planes, gray or RGBA, with
nearest and bilinear sampling that repeats or clamps, resizing and display conversion. Sizes are
bounded by `Limits`. From MaterialCraft.
- [`craft-ui`](crates/ui/README.md): SVG catalogs, icon buttons, tabs, pane controls, transactional docking, print settings and theme helpers for egui frontends;
assets, themes, localization and command handling stay in each app. Requires Rust 1.95 or later.
- [`craft-vcard`](crates/vcard/README.md): vCard contacts, from MailCraft: vCard 2.1, 3.0 and 4.0 read
+9 -4
View File
@@ -23,6 +23,7 @@ decode-native = ["aac-decode", "alac-decode", "opus-decode", "ac3-decode", "mpa-
# The symphonia fallback for the formats with no native decoder yet.
symphonia = ["decode-native", "dep:symphonia"]
# Every encoder: the lossless file writers and the AAC, ALAC, AC-3/E-AC-3, MP3 and Opus encoders.
# All but Opus are also file formats of `encode` and `FileEncoder`.
encode = ["lossless-encode", "aac-encode", "alac-encode", "ac3-encode", "eac3-encode", "mp3-encode", "opus-encode"]
# Encode WAV/BWF/RF64, AIFF/AIFF-C and FLAC files.
lossless-encode = ["pcm-encode", "flac-encode"]
@@ -34,16 +35,18 @@ flac-encode = ["craft-media/bitstream"]
vorbis-encode = ["dep:vorbis_rs"]
# Codec modules on their own, for packet-level use.
aac-decode = ["craft-media/bitstream"]
aac-encode = ["craft-media/bitstream"]
# The AAC encoder (`aac::Encoder`), and AAC in M4A through `encode` and `FileEncoder`.
aac-encode = ["craft-media/bitstream", "craft-media/isobmff"]
opus-decode = []
opus-encode = []
ac3-decode = ["craft-media/bitstream"]
mpa-decode = ["craft-media/bitstream"]
# MPEG-1/2 Layer III (MP3) decoder (`mp3::Decoder`).
mp3-decode = ["mpa-decode"]
# ALAC packet decoder and encoder (`alac`), ported from Apple's reference implementation.
# ALAC packet decoder and encoder (`alac`), ported from Apple's reference implementation. The
# encoder also writes ALAC in M4A through `encode` and `FileEncoder`.
alac-decode = []
alac-encode = []
alac-encode = ["craft-media/isobmff"]
ac3-encode = ["craft-media/bitstream"]
eac3-encode = ["craft-media/bitstream"]
# MPEG-1/2 Layer III (MP3) encoder (`mp3`).
@@ -61,10 +64,12 @@ thiserror = { workspace = true }
serde = { workspace = true, optional = true }
log = { version = "0.4", optional = true }
rayon = { workspace = true, optional = true }
vorbis_rs = { version = "0.5", optional = true }
# symphonia keeps its AAC decoder for AAC in CAF, a container craft-media does not read.
symphonia = { version = "0.6.1", optional = true, default-features = false, features = ["mp3", "flac", "vorbis", "ogg", "wav", "pcm", "aiff", "isomp4", "aac", "alac", "adpcm", "caf", "mkv"] }
[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
vorbis_rs = { version = "0.5", optional = true }
[dev-dependencies]
craft-media-testkit = { workspace = true }
proptest = { workspace = true }
+105 -20
View File
@@ -29,19 +29,19 @@ No default features. The shared types (`AudioBuffer`, `AudioInfo`, `ChannelLayou
| `decode` | `decode`, `probe`, `Decoder`, `tracks`, `TrackDecoder`; every format in [Format support](#format-support) | `decode-native`, `symphonia` |
| `decode-native` | the same, native formats only (others are `Unsupported`); `wav_pcm`, `aiff_pcm` (a file's integer PCM bit for bit, as `RawPcm`) | the six decoders below, craft-media `isobmff`/`matroska`/`ogg`, `log` |
| `symphonia` | the fallback for formats with no native decoder; turning it on is the same as `decode` | `decode-native`, symphonia |
| `encode` | every encoder: the WAV, AIFF and FLAC file writers, and the AAC, ALAC, AC-3/E-AC-3, MP3 and Opus encoders | `lossless-encode`, `aac-encode`, `alac-encode`, `ac3-encode`, `eac3-encode`, `mp3-encode`, `opus-encode` |
| `encode` | every encoder, and every format of `encode` and `FileEncoder` | `lossless-encode`, `aac-encode`, `alac-encode`, `ac3-encode`, `eac3-encode`, `mp3-encode`, `opus-encode` |
| `lossless-encode` | WAV, AIFF and FLAC writing | `pcm-encode`, `flac-encode` |
| `pcm-encode` | `encode`, `FileEncoder` for WAV and AIFF; `wav_float_header`; `pcm_wav_file`, `pcm_wav_header`, `pcm_aiff_file`, `pcm_aiff_header` (minimal files around integer PCM bytes, for essence embedded in AAF / OMF) | none |
| `flac-encode` | `encode`, `FileEncoder` for FLAC; `flac::Encoder`, the packet encoder for callers that mux FLAC themselves | craft-media `bitstream` |
| `aac-decode`, `aac-encode` | `aac::Decoder`, `aac::Encoder`; with `aac-decode`, `aac::latm_config` / `latm_split` for LOAS / LATM frames (AAC in MPEG transport streams) | craft-media `bitstream` |
| `aac-decode`, `aac-encode` | `aac::Decoder`, `aac::Encoder`; with `aac-decode`, `aac::latm_config` / `latm_split` for LOAS / LATM frames (AAC in MPEG transport streams); with `aac-encode`, `encode`, `FileEncoder` for AAC in M4A | craft-media `bitstream`; `aac-encode` also `isobmff` |
| `alac-decode` | `alac::Decoder` | none |
| `alac-encode` | `alac::Encoder` | none |
| `alac-encode` | `alac::Encoder`; `encode`, `FileEncoder` for ALAC in M4A | craft-media `isobmff` |
| `opus-decode`, `opus-encode` | `opus::Decoder`/`StreamDecoder`, `opus::Encoder` | none |
| `ac3-decode` | `ac3::Decoder`, `ac3::ProgrammeDecoder` | craft-media `bitstream` |
| `ac3-encode`, `eac3-encode` | `ac3::encoder::Encoder` | craft-media `bitstream` |
| `ac3-encode`, `eac3-encode` | `ac3::encoder::Encoder`; `encode`, `FileEncoder` for AC-3 and E-AC-3 streams | craft-media `bitstream` |
| `mpa-decode` | `mpa::Decoder` | craft-media `bitstream` |
| `mp3-decode` | `mp3::Decoder`, `mp3::InfoTag` | `mpa-decode` |
| `mp3-encode` | `mp3::Encoder` | craft-media `bitstream` |
| `mp3-encode` | `mp3::Encoder`; `encode`, `FileEncoder` for MP3 | craft-media `bitstream` |
| `peaks` | `peaks::Peaks` | none |
| `rayon` | parallel AAC encoding (with `aac-encode`) | `rayon` |
| `serde` | `Serialize`/`Deserialize` on the shared types | `serde` |
@@ -230,17 +230,86 @@ let wav = encode(&surround, &EncodeOptions::default().with_layout(ChannelLayout:
let mut enc = FileEncoder::new(std::fs::File::create("take.wav")?, &EncodeOptions::default(), 48_000, 2)?;
enc.write(&buf.channels, buf.frames())?; // one slice (or Vec) per channel
enc.finish()?;
// The coded formats go the same way: AAC in M4A at 192 kbit/s, 5.1 as E-AC-3, 16-bit ALAC.
let m4a = encode(&buf, &EncodeOptions::new(EncodeFormat::Aac).with_bitrate(192_000))?;
let eac3 = encode(&surround, &EncodeOptions::new(EncodeFormat::Eac3).with_layout(ChannelLayout::SURROUND_5_1_SIDE))?;
let alac = encode(&buf, &EncodeOptions::new(EncodeFormat::Alac).with_bit_depth(BitDepth::Int16))?;
```
`EncodeOptions::default()` is 24-bit WAV. `with_bwf` adds a BWF `bext` chunk and
`with_force_rf64` writes RF64 below 4 GiB; both apply to WAV only. `encode_format_for("aiff")`
maps an extension to an `EncodeFormat`, and `ENCODE_EXTENSIONS` lists the extensions the enabled
features can write. `EncodeFormat::ALL` lists the formats; `extension()` is the extension a new
file gets and `mime_type()` its media type. `write` refuses a block without one slice per channel, or with a slice
shorter than `frames`, and writes nothing. After a write fails for another reason, every later
maps an extension to an `EncodeFormat` (`"m4a"` to AAC; `"alac"` names ALAC), and `ENCODE_EXTENSIONS` lists the extensions the enabled
features can write. `EncodeFormat::ALL` lists the formats and `is_built()` says whether this build
writes one; `extension()` is the extension a new file gets and `mime_type()` its media type.
`write` refuses a block without one slice per channel, or with a slice shorter than `frames`, and
writes nothing. After a write fails for another reason, every later
`write` and `finish` returns an error.
### Encode AAC
| `EncodeFormat` | File | Audio | Options used |
|---|---|---|---|
| `Wav`, `Aiff`, `Flac` | WAV / BWF / RF64, AIFF / AIFF-C, FLAC | any rate; FLAC up to 8 channels | `bit_depth`, `dither`, `layout` (WAV, FLAC), `bwf`, `force_rf64` (WAV) |
| `Alac` | M4A | 1–8 channels, any rate | `bit_depth` (16, 24, 32), `dither`, `layout` |
| `Aac` | M4A | AAC-LC, 1–8 channels, the 13 AAC rates (7350–96000 Hz) | `rate_control`, `layout` |
| `Mp3` | `.mp3` stream | mono or stereo; 32, 44.1, 48 kHz or 16, 22.05, 24 kHz | `rate_control` (bit rate), `layout` |
| `Ac3`, `Eac3` | `.ac3` / `.eac3` stream | up to 5.1 (E-AC-3: 7.1); 32, 44.1, 48 kHz | `rate_control` (bit rate), `layout` |
`with_bitrate(bits_per_second)` sets a constant bit rate for all channels together. A rate the
stream cannot carry is moved to the nearest one it can: MP3 and AC-3 use the highest rate of their
tables not above it, AAC and E-AC-3 keep it inside their range (AAC from 6 kbit/s or a quarter of
the sample rate per channel, whichever is more: from about half of that down the encoder codes
silence). `with_quality(0.0..=1.0)` is AAC's
constant quality (VBR); the other lossy formats return `Unsupported` for it. Without either, AAC
is written at 64 kbit/s per channel, MP3 at 96 kbit/s per channel, and AC-3 and E-AC-3 at
96 kbit/s per full-bandwidth channel (the LFE not counted).
The audio is in WAV channel order for every format; `layout` (the usual layout for the channel
count when unset) names the speakers, and the channels are reordered into the codec's own order.
Each coded format has a fixed set of layouts, and audio with other speakers is `Unsupported`
rather than written to the wrong ones:
- AAC: C; L R; L R C; L R C Cb; L R C Ls Rs; 5.1; 6.1; and for 8 channels L R C LFE Lb Rb Lc Rc
(a front pair left and right of centre, mask `0xFF`). ALAC: the same, with 6.1's back centre last.
WAV 7.1 (backs and sides) is not that 7.1, and quad (the usual 4-channel layout) has no centre:
both need another format.
- AC-3 and E-AC-3: the layout picks the coding mode (1/0 to 3/2, with or without LFE; E-AC-3 also
7.1 with backs and sides).
- A surround pair is a surround pair: side and back surrounds are interchangeable where the format
has one pair.
Before a file is created, the options and the format say what will happen:
```rust
let opts = EncodeOptions::new(EncodeFormat::Ac3).with_layout(info.layout).with_bitrate(200_000);
opts.check(info.sample_rate, info.channels)?; // the error FileEncoder::new would return, nothing written
let bps = opts.bitrate(info.sample_rate, info.channels)?; // Some(192_000): the rate actually used; None when lossless or by quality
EncodeFormat::Ac3.sample_rates(); // Some(&[32_000, 44_100, 48_000]); None when any rate will do
EncodeFormat::Ac3.max_channels(); // 6
EncodeFormat::Ac3.fixed_layouts(3); // L R C, L R Cb, L R LFE; None for WAV, AIFF and FLAC (any layout)
EncodeFormat::Ac3.supports_layout(&info.layout); // one of those, sides and backs standing for each other
EncodeFormat::Ac3.supports_quality(); // false: AAC only
```
`FileEncoder::bitrate()` gives the rate of a file being written. The `EncodeFormat` queries answer
for a format whose feature is off too; `check` and `EncodeOptions::bitrate` (there with any
encoder feature) return `Unsupported` for it.
The layout `decode` reports (`AudioInfo::layout`) can be passed to `with_layout` as it is. When a
coded format refuses it (2.1 or quad into AAC, a single channel tagged as left, channels with no
speaker assignment), the choices are another format, or audio rearranged into one of the layouts
above with that layout set; leaving `layout` unset declares the usual layout for the count. This
crate's decoder returns 7- and 8-channel AAC without a speaker assignment, in AAC order, so such a
file needs that step before it is written again.
An M4A's edit list skips the AAC encoder's priming (1024 frames) and ends at the last frame
written, so the file decodes to the length that went in. An MP3, AC-3 or E-AC-3 stream has no
place for that (see [Limits](#limits)). For a container of your own, use the codec modules below.
### Encode AAC packets
For an `.m4a` file, use `EncodeFormat::Aac` above. `aac::Encoder` is the packet encoder behind it,
for muxing into a container of your own:
```rust
use craft_audio::AudioError;
@@ -343,14 +412,14 @@ match craft_audio::decode(&bytes, None) {
| WAV, BWF, RF64/BW64 | native | native |
| AIFF, AIFF-C | native | native |
| FLAC | symphonia | native |
| AAC-LC | native | native |
| AAC-LC | native | native; M4A through `encode` / `FileEncoder`, packets through `aac::Encoder` |
| HE-AAC v1 | native (SBR) | — |
| HE-AAC v2 | native, without parametric stereo (see [Limits](#limits)) | — |
| ALAC | native | native, packets (`alac::Encoder`; no file writer) |
| ALAC | native | native; M4A through `encode` / `FileEncoder`, packets through `alac::Encoder` |
| MP1, MP2 (MPEG audio Layer I/II) | native | — |
| MP3 (Layer III) | native | native, frames (`mp3::Encoder`; the frames in a row are an `.mp3` file) |
| Opus | native | native |
| AC-3, E-AC-3 | native | native packet encoder |
| MP3 (Layer III) | native | native; `.mp3` through `encode` / `FileEncoder`, frames through `mp3::Encoder` |
| Opus | native | native, packets (`opus::Encoder`; no file writer) |
| AC-3, E-AC-3 | native | native; `.ac3` / `.eac3` through `encode` / `FileEncoder`, packets through `ac3::encoder::Encoder` |
| Vorbis, ADPCM, A-law, µ-law | symphonia | — |
| Container | Demuxer | Timing |
@@ -410,10 +479,26 @@ match craft_audio::decode(&bytes, None) {
- `TrackDecoder` returns `Unsupported` for FLAC and Vorbis; `decode` and `Decoder` read
those through symphonia. ALAC in CAF still goes through symphonia (craft-media has no CAF
demuxer).
- ALAC: `EncodeFormat` has no ALAC entry; `alac::Encoder` writes packets and the configuration,
and the caller muxes them (MP4 `alac` box, Matroska `A_ALAC`). craft-media's MP4 muxer writes no
`chan` box, so an MP4 of more than two channels carries no explicit layout; decoders then use the
standard ALAC layout for the count.
- ALAC: craft-media's MP4 muxer writes no `chan` box, so an M4A of more than two channels (from
`EncodeFormat::Alac` or muxed from `alac::Encoder` packets) carries no explicit layout; decoders
then use the standard ALAC layout for the count, which is the one written.
- `EncodeFormat::Mp3`, `Ac3` and `Eac3` write raw streams, which cannot signal the codec's delay or
the length: the file decodes with 1057 (MP3) or 256 (AC-3, E-AC-3) frames of delay in front and
padded to whole frames at the end. MP3 gets no Xing / Info frame. `EncodeFormat::Aac` and `Alac`
(M4A) decode to the length written.
- An AAC M4A's length is in the edit list and the last packet's duration. This crate, Apple's
decoders and ffmpeg 9 end the audio there; ffmpeg 8 skips the priming but plays the last
packet's padding (under 1024 frames of near silence).
- `EncodeFormat::Aac` and `Alac` write the `moov` box after the audio (no fast start), and no
metadata. Raw ADTS AAC is not a file format of `encode`; `aac::EncoderConfig::with_adts` gives
the frames.
- This crate's file reader plays a raw E-AC-3 7.1 stream as its 5.1 independent substream.
- `EncodeFormat::Aac` with 8 channels is AAC channel configuration 7 (C, Lc Rc, L R, Ls Rs, LFE),
which Apple's decoders read as written. ffmpeg assumes such a stream is a mislabelled 7.1 with
backs and sides and moves the channels accordingly, unless run with `-strict 1`.
- A file with no audio: MP3, AC-3 and E-AC-3 are then zero bytes, which nothing can probe. An
empty AAC M4A (a track with no samples) is read by ffmpeg; this crate's native reader passes it
on, so `decode-native` alone refuses it and symphonia reads only some as zero frames.
- ALAC 32-bit streams: ffmpeg does not decode their uncompressed (escaped) stereo frames, which
Apple's encoder and this one write for audio that does not compress; Apple's decoder and this
one do.
@@ -481,7 +566,7 @@ finite count as silence and the rest are clamped to ±4, so no input makes an in
decoder's 7680-bit input buffer.
- Not yet: block switching (short blocks; transients pre-echo), `scfsi` and `preflag`, intensity
stereo, a tonality-aware model, VBR/ABR, the Xing/Info and LAME gapless tags (the delay is not
signalled), CRC, free format, and an `EncodeFormat` entry for `encode`/`FileEncoder`.
signalled), CRC and free format.
### AC-3 and E-AC-3 encoding
+6 -2
View File
@@ -1,4 +1,4 @@
//! Write a tone as WAV and FLAC, whole and streamed, and as AAC packets.
//! Write a tone as WAV, FLAC and AAC in M4A, whole and streamed, and as AAC packets.
//!
//! `cargo run -p craft-audio --example encode --features lossless-encode,aac-encode -- out`
@@ -28,7 +28,11 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
}
enc.finish()?;
// AAC packets for an MP4 or Matroska muxer, with the configuration its sample entry needs.
// AAC in M4A at 160 kbit/s: the same call, with a bit rate in place of a bit depth.
let m4a = encode(&stereo, &EncodeOptions::new(EncodeFormat::Aac).with_bitrate(160_000))?;
std::fs::write(dir.join("tone.m4a"), m4a)?;
// AAC packets for a muxer of your own, with the configuration its sample entry needs.
let mut aac = craft_audio::aac::Encoder::new(craft_audio::aac::EncoderConfig::cbr(rate as u32, 2, 128_000))?;
let mut units = aac.encode(&[&tone, &tone]);
units.extend(aac.flush());
+10
View File
@@ -162,6 +162,16 @@ const HISTORY: usize = 2048;
/// Bits per channel in a silent frame, rounded up: the smallest frame the encoder writes.
const MIN_FRAME_BITS_PER_CHANNEL: u64 = 48;
/// The lowest and highest constant bit rate (bits per second) [`Encoder::new`] accepts for a
/// stream without ADTS headers: at least 1 kbit/s per channel and a silent frame, at most the
/// 6144 bits per channel and frame of the decoder buffer.
pub(crate) fn cbr_range(sample_rate: u32, channels: usize) -> (u32, u32) {
let (rate, channels) = (u64::from(sample_rate), channels as u64);
let silent = (MIN_FRAME_BITS_PER_CHANNEL * channels * rate).div_ceil(FRAME_LEN as u64);
let most = 6144 * channels * rate / FRAME_LEN as u64;
(u32::try_from(silent.max(1000 * channels)).unwrap_or(u32::MAX), u32::try_from(most).unwrap_or(u32::MAX))
}
/// AAC-LC encoder.
pub struct Encoder {
cfg: EncoderConfig,
+2
View File
@@ -64,6 +64,8 @@ pub use config::{AdtsHeader, AudioSpecificConfig, ElementType, ProgramConfig, co
#[cfg(feature = "aac-decode")]
pub use decoder::Decoder;
#[cfg(feature = "aac-encode")]
pub(crate) use encoder::cbr_range;
#[cfg(feature = "aac-encode")]
pub use encoder::{BitrateMode, Encoder, EncoderConfig, EncoderStats};
#[cfg(feature = "aac-decode")]
pub use latm::{LatmConfig, latm_config, latm_split};
+1 -1
View File
@@ -61,7 +61,7 @@ pub enum Error {
pub type Result<T> = std::result::Result<T, Error>;
/// Data rate in kb/s by frmsizecod / 2 (Table 5.18).
const BITRATES: [u32; 19] = [32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320, 384, 448, 512, 576, 640];
pub(crate) const BITRATES: [u32; 19] = [32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320, 384, 448, 512, 576, 640];
/// Full-bandwidth channels per acmod (Table 5.8).
const NFCHANS: [usize; 8] = [2, 1, 2, 3, 3, 4, 4, 5];
+34
View File
@@ -283,6 +283,40 @@ pub(crate) fn flac_assumed_mask(channels: usize) -> u32 {
}
}
/// The surround speaker a layout may name in place of `speaker`: formats with one surround pair
/// do not tell side from back, so a pair of either kind feeds it.
fn surround_twin(speaker: Speaker) -> Option<Speaker> {
Some(match speaker {
Speaker::SideLeft => Speaker::BackLeft,
Speaker::SideRight => Speaker::BackRight,
Speaker::BackLeft => Speaker::SideLeft,
Speaker::BackRight => Speaker::SideRight,
_ => return None,
})
}
/// How audio with `layout` feeds a format whose layout for the channel count is `mask`: for each
/// channel the format takes, the channel of the audio that feeds it. `order` is the format's
/// channel order over `mask` (for each of its channels, the WAV-order channel of `mask`; `None`
/// when it takes WAV order). `None` when `layout` is not the format's layout: it is unordered, or
/// has a speaker the format has not.
pub(crate) fn channel_map(mask: u32, order: Option<&[usize]>, layout: &ChannelLayout) -> Option<Vec<usize>> {
let speakers = ChannelLayout::from_mask(mask).speakers();
if speakers.len() != usize::from(layout.channels()) {
return None;
}
let mut map = Vec::with_capacity(speakers.len());
for j in 0..speakers.len() {
let speaker = *speakers.get(order.and_then(|o| o.get(j).copied()).unwrap_or(j))?;
let at = layout.index_of(speaker).or_else(|| surround_twin(speaker).and_then(|t| layout.index_of(t)))?;
if map.contains(&at) {
return None;
}
map.push(at);
}
Some(map)
}
#[cfg(test)]
mod tests {
use super::*;
+250 -27
View File
@@ -16,9 +16,10 @@
//! - [`TrackDecoder`] (any decoder feature): one track's packets from any demuxer to planar
//! `f32` in WAV channel order.
//! - [`encode`], [`FileEncoder`]: WAV/BWF/RF64 and AIFF/AIFF-C (feature `pcm-encode`, which also
//! gives [`wav_float_header`]) and FLAC (feature `flac-encode`), whole-buffer or incremental into
//! any `Write + Seek`. Feature `lossless-encode` turns on both; feature `encode` turns on
//! `lossless-encode` and every codec's encoder.
//! gives [`wav_float_header`]), FLAC (feature `flac-encode`), AAC-LC and ALAC in M4A
//! (`aac-encode`, `alac-encode`) and MP3, AC-3 and E-AC-3 streams (`mp3-encode`, `ac3-encode`,
//! `eac3-encode`), whole-buffer or incremental into any `Write + Seek`. Feature
//! `lossless-encode` turns on WAV, AIFF and FLAC; feature `encode` turns on every format and encoder.
//! - [`wav_pcm`], [`aiff_pcm`] (feature `decode-native`) and [`pcm_wav_file`], [`pcm_wav_header`],
//! [`pcm_aiff_file`], [`pcm_aiff_header`] (feature `pcm-encode`): the integer PCM of a WAV or AIFF
//! file bit for bit, and minimal files around such PCM, for essence embedded in other containers.
@@ -54,12 +55,19 @@ mod read;
mod track;
#[cfg(any(feature = "decode-native", feature = "pcm-encode"))]
mod wav;
#[cfg(any(feature = "pcm-encode", feature = "flac-encode", feature = "vorbis-encode"))]
#[cfg(any(
feature = "pcm-encode",
feature = "flac-encode",
feature = "aac-encode",
feature = "alac-encode",
feature = "mp3-encode",
feature = "ac3-encode",
feature = "eac3-encode",
feature = "vorbis-encode"
))]
mod write;
#[cfg(feature = "vorbis-encode")]
pub use write::OGG_BITRATES;
#[cfg(feature = "vorbis-encode")]
pub use write::encode_ogg;
pub use write::{OGG_BITRATES, encode_ogg};
/// The FLAC packet encoder (RFC 9639), for a caller that muxes FLAC itself (into MP4, Matroska or
/// its own `.flac` writer): planar integer samples in, frames out, and the STREAMINFO to patch in
@@ -102,10 +110,29 @@ pub use read::{
pub use read::{RawPcm, aiff_pcm, wav_pcm};
#[cfg(any(feature = "aac-decode", feature = "alac-decode", feature = "opus-decode", feature = "ac3-decode", feature = "mpa-decode"))]
pub use track::{LOOKAHEAD_PACKETS, TrackDecoder};
#[cfg(any(
feature = "pcm-encode",
feature = "flac-encode",
feature = "aac-encode",
feature = "alac-encode",
feature = "mp3-encode",
feature = "ac3-encode",
feature = "eac3-encode"
))]
pub use write::FileEncoder;
#[cfg(feature = "pcm-encode")]
pub use write::wav_float_header;
#[cfg(any(feature = "pcm-encode", feature = "flac-encode"))]
pub use write::{ENCODE_EXTENSIONS, FileEncoder, encode, encode_format_for};
#[cfg(any(
feature = "pcm-encode",
feature = "flac-encode",
feature = "aac-encode",
feature = "alac-encode",
feature = "mp3-encode",
feature = "ac3-encode",
feature = "eac3-encode",
feature = "vorbis-encode"
))]
pub use write::{ENCODE_EXTENSIONS, encode, encode_format_for};
#[cfg(feature = "pcm-encode")]
pub use write::{pcm_aiff_file, pcm_aiff_header, pcm_wav_file, pcm_wav_header};
@@ -219,7 +246,8 @@ impl From<opus::encoder::Error> for AudioError {
}
/// The file formats [`encode`] writes. Each needs its feature: WAV and AIFF `pcm-encode`, FLAC
/// `flac-encode`; asking for one that is not built returns [`AudioError::Unsupported`].
/// `flac-encode`, AAC `aac-encode`, ALAC `alac-encode`, MP3 `mp3-encode`, AC-3 `ac3-encode` and
/// E-AC-3 `eac3-encode`; asking for one that is not built returns [`AudioError::Unsupported`].
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
@@ -230,29 +258,49 @@ pub enum EncodeFormat {
Aiff,
/// FLAC (integer depths).
Flac,
/// Ogg Vorbis (variable bitrate). Whole-buffer only: use [`encode_ogg`] directly.
#[cfg(feature = "vorbis-encode")]
/// AAC-LC in an M4A (MP4) file, 1–8 channels at one of the 13 AAC sample rates. The edit list
/// skips the encoder's priming and ends at the last frame, so the file decodes to the length
/// that was written.
Aac,
/// Apple Lossless in an M4A (MP4) file (integer depths), 1–8 channels.
Alac,
/// An MP3 stream: mono or stereo at 32, 44.1 or 48 kHz, or 16, 22.05 or 24 kHz.
Mp3,
/// An AC-3 stream: up to 5.1 at 32, 44.1 or 48 kHz.
Ac3,
/// An E-AC-3 stream: up to 7.1 at 32, 44.1 or 48 kHz.
Eac3,
/// Ogg Vorbis, whole-buffer encoding only.
Ogg,
}
impl EncodeFormat {
/// Every format, in the order menus list them. Whether [`encode`] writes one depends on its
/// feature.
#[cfg(not(feature = "vorbis-encode"))]
pub const ALL: &[EncodeFormat] = &[EncodeFormat::Wav, EncodeFormat::Aiff, EncodeFormat::Flac];
/// Every format, in the order menus list them. Whether [`encode`] writes one depends on its
/// feature.
#[cfg(feature = "vorbis-encode")]
pub const ALL: &[EncodeFormat] = &[EncodeFormat::Wav, EncodeFormat::Aiff, EncodeFormat::Flac, EncodeFormat::Ogg];
/// feature ([`EncodeFormat::is_built`]).
pub const ALL: &[EncodeFormat] = &[
EncodeFormat::Wav,
EncodeFormat::Aiff,
EncodeFormat::Flac,
EncodeFormat::Alac,
EncodeFormat::Aac,
EncodeFormat::Mp3,
EncodeFormat::Ac3,
EncodeFormat::Eac3,
EncodeFormat::Ogg,
];
/// The extension a new file of this format gets, lower case and without the dot: `"wav"`,
/// `"aif"`, `"flac"`. [`encode_format_for`] maps it back.
/// `"aif"`, `"flac"`, `"m4a"` (AAC and ALAC), `"mp3"`, `"ac3"`, `"eac3"`.
/// [`encode_format_for`] maps it back, `"m4a"` to AAC.
pub fn extension(self) -> &'static str {
match self {
EncodeFormat::Wav => "wav",
EncodeFormat::Aiff => "aif",
EncodeFormat::Flac => "flac",
#[cfg(feature = "vorbis-encode")]
EncodeFormat::Aac | EncodeFormat::Alac => "m4a",
EncodeFormat::Mp3 => "mp3",
EncodeFormat::Ac3 => "ac3",
EncodeFormat::Eac3 => "eac3",
EncodeFormat::Ogg => "ogg",
}
}
@@ -263,7 +311,10 @@ impl EncodeFormat {
EncodeFormat::Wav => "audio/wav",
EncodeFormat::Aiff => "audio/aiff",
EncodeFormat::Flac => "audio/flac",
#[cfg(feature = "vorbis-encode")]
EncodeFormat::Aac | EncodeFormat::Alac => "audio/mp4",
EncodeFormat::Mp3 => "audio/mpeg",
EncodeFormat::Ac3 => "audio/ac3",
EncodeFormat::Eac3 => "audio/eac3",
EncodeFormat::Ogg => "audio/ogg",
}
}
@@ -274,10 +325,158 @@ impl EncodeFormat {
EncodeFormat::Wav => Container::Wav,
EncodeFormat::Aiff => Container::Aiff,
EncodeFormat::Flac => Container::Flac,
#[cfg(feature = "vorbis-encode")]
EncodeFormat::Aac | EncodeFormat::Alac => Container::Mp4,
EncodeFormat::Mp3 => Container::MpegAudio,
EncodeFormat::Ac3 | EncodeFormat::Eac3 => Container::Ac3,
EncodeFormat::Ogg => Container::Ogg,
}
}
/// The codec of the audio this format writes.
pub fn codec(self) -> CodecId {
match self {
EncodeFormat::Wav | EncodeFormat::Aiff => CodecId::Pcm,
EncodeFormat::Flac => CodecId::Flac,
EncodeFormat::Aac => CodecId::Aac,
EncodeFormat::Alac => CodecId::Alac,
EncodeFormat::Mp3 => CodecId::Mp3,
EncodeFormat::Ac3 => CodecId::Ac3,
EncodeFormat::Eac3 => CodecId::Eac3,
EncodeFormat::Ogg => CodecId::Vorbis,
}
}
/// The feature that builds this format's writer.
pub fn feature(self) -> &'static str {
match self {
EncodeFormat::Wav | EncodeFormat::Aiff => "pcm-encode",
EncodeFormat::Flac => "flac-encode",
EncodeFormat::Aac => "aac-encode",
EncodeFormat::Alac => "alac-encode",
EncodeFormat::Mp3 => "mp3-encode",
EncodeFormat::Ac3 => "ac3-encode",
EncodeFormat::Eac3 => "eac3-encode",
EncodeFormat::Ogg => "vorbis-encode",
}
}
/// Whether [`encode`] writes this format in this build (its
/// [`feature`](Self::feature) is on): what to filter [`EncodeFormat::ALL`] by for a menu.
pub fn is_built(self) -> bool {
match self {
EncodeFormat::Wav | EncodeFormat::Aiff => cfg!(feature = "pcm-encode"),
EncodeFormat::Flac => cfg!(feature = "flac-encode"),
EncodeFormat::Aac => cfg!(feature = "aac-encode"),
EncodeFormat::Alac => cfg!(feature = "alac-encode"),
EncodeFormat::Mp3 => cfg!(feature = "mp3-encode"),
EncodeFormat::Ac3 => cfg!(feature = "ac3-encode"),
EncodeFormat::Eac3 => cfg!(feature = "eac3-encode"),
EncodeFormat::Ogg => cfg!(all(feature = "vorbis-encode", not(target_arch = "wasm32"))),
}
}
/// The sample rates the format takes, ascending, or `None` when it has no fixed list (WAV,
/// AIFF, FLAC and ALAC take any rate their headers can hold).
pub fn sample_rates(self) -> Option<&'static [u32]> {
match self {
EncodeFormat::Aac => Some(&[7350, 8000, 11_025, 12_000, 16_000, 22_050, 24_000, 32_000, 44_100, 48_000, 64_000, 88_200, 96_000]),
EncodeFormat::Mp3 => Some(&[16_000, 22_050, 24_000, 32_000, 44_100, 48_000]),
EncodeFormat::Ac3 | EncodeFormat::Eac3 => Some(&[32_000, 44_100, 48_000]),
EncodeFormat::Wav | EncodeFormat::Aiff | EncodeFormat::Flac | EncodeFormat::Alac | EncodeFormat::Ogg => None,
}
}
/// The most channels a file of this format holds. A WAV's frame size is a 16-bit field, so it
/// holds 65535 / bytes per sample: 32767 at 16 bits (the count given here), 21845 at 24 and
/// 16383 at 32; [`EncodeOptions::check`] answers for the depth chosen.
pub fn max_channels(self) -> u16 {
match self {
EncodeFormat::Wav | EncodeFormat::Aiff => 32_767,
EncodeFormat::Flac | EncodeFormat::Aac | EncodeFormat::Alac | EncodeFormat::Eac3 => 8,
EncodeFormat::Ac3 => 6,
EncodeFormat::Mp3 | EncodeFormat::Ogg => 2,
}
}
/// The speaker layouts of a format that has a fixed set of them, as WAV masks, for a channel
/// count: one each for AAC, ALAC and MP3, one per coding mode for AC-3 and E-AC-3. Empty for a
/// count the format has not, and for WAV, AIFF and FLAC, which have no such set.
pub(crate) fn layout_masks(self, channels: u16) -> &'static [u32] {
let per_count: &[&[u32]] = match self {
// Channel configurations 1–6, the 6.1 program config element, and configuration 7
// (7.1 with a front pair left and right of centre).
EncodeFormat::Aac => &[&[0x4], &[0x3], &[0x7], &[0x107], &[0x607], &[0x60F], &[0x70F], &[0xFF]],
// Apple's layout tags for 1–8 channels, surrounds as back speakers.
EncodeFormat::Alac => &[&[0x4], &[0x3], &[0x7], &[0x107], &[0x37], &[0x3F], &[0x13F], &[0xFF]],
EncodeFormat::Mp3 | EncodeFormat::Ogg => &[&[0x4], &[0x3]],
// The coding modes 1/0 to 3/2 with and without an LFE, by channel count.
EncodeFormat::Ac3 => &[&[0x4], &[0x3, 0xC], &[0x7, 0x103, 0xB], &[0x107, 0x603, 0xF, 0x10B], &[0x607, 0x10F, 0x60B], &[0x60F]],
// The same, and 7.1 with backs and sides.
EncodeFormat::Eac3 => {
&[&[0x4], &[0x3, 0xC], &[0x7, 0x103, 0xB], &[0x107, 0x603, 0xF, 0x10B], &[0x607, 0x10F, 0x60B], &[0x60F], &[], &[0x63F]]
}
EncodeFormat::Wav | EncodeFormat::Aiff | EncodeFormat::Flac => &[],
};
usize::from(channels).checked_sub(1).and_then(|i| per_count.get(i)).copied().unwrap_or_default()
}
/// The speaker layouts a format with a fixed set of them has for `channels` channels: one for
/// AAC, ALAC and MP3, one per coding mode for AC-3 and E-AC-3; empty when the format cannot
/// hold that many channels. `None` for WAV, AIFF and FLAC, which take any layout. Audio in
/// another layout has to be rearranged into one of these before it is written.
///
/// ```
/// use craft_audio::{ChannelLayout, EncodeFormat};
///
/// assert_eq!(EncodeFormat::Aac.fixed_layouts(6), Some(vec![ChannelLayout::SURROUND_5_1_SIDE]));
/// assert_eq!(EncodeFormat::Mp3.fixed_layouts(6), Some(vec![]));
/// assert_eq!(EncodeFormat::Wav.fixed_layouts(6), None);
/// ```
pub fn fixed_layouts(self, channels: u16) -> Option<Vec<ChannelLayout>> {
match self {
EncodeFormat::Wav | EncodeFormat::Aiff | EncodeFormat::Flac => None,
_ => Some(self.layout_masks(channels).iter().map(|&mask| ChannelLayout::from_mask(mask)).collect()),
}
}
/// Whether the format holds audio with `layout`: for WAV, AIFF and FLAC any layout of up to
/// [`max_channels`](Self::max_channels) channels, for the others one of
/// [`fixed_layouts`](Self::fixed_layouts), where side and back surrounds stand for each other
/// in a layout with one surround pair.
pub fn supports_layout(self, layout: &ChannelLayout) -> bool {
match self {
EncodeFormat::Wav | EncodeFormat::Aiff | EncodeFormat::Flac => (1..=self.max_channels()).contains(&layout.channels()),
_ => self.layout_masks(layout.channels()).iter().any(|&mask| layout::channel_map(mask, None, layout).is_some()),
}
}
/// Whether the format takes [`RateControl::Quality`]: AAC. The other lossy formats are
/// written at a constant bit rate only.
pub fn supports_quality(self) -> bool {
self == EncodeFormat::Aac
}
/// Whether the format loses audio: AAC, MP3, AC-3 and E-AC-3. These take
/// [`EncodeOptions::rate_control`] and ignore the bit depth and dither.
pub fn is_lossy(self) -> bool {
matches!(self, EncodeFormat::Aac | EncodeFormat::Mp3 | EncodeFormat::Ac3 | EncodeFormat::Eac3 | EncodeFormat::Ogg)
}
}
/// How a lossy format spends bits ([`EncodeOptions::rate_control`]).
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum RateControl {
/// A constant bit rate in bits per second, for all channels together. A format with a fixed
/// set of rates (MP3, AC-3) uses the highest one not above it; a rate outside what the
/// stream can carry is moved to the nearest one inside. AAC is written at 6 kbit/s or a
/// quarter of the sample rate per channel at least: from about half of that down its encoder
/// codes silence.
Bitrate(u32),
/// A constant quality from 0.0 (smallest) to 1.0 (best), at whatever bit rate each frame
/// needs. AAC only; values outside the range are clamped, and NaN is an error.
Quality(f32),
}
/// Stored sample representation.
@@ -436,9 +635,9 @@ pub enum BitDepth {
pub struct EncodeOptions {
/// Output file format.
pub format: EncodeFormat,
/// Sample depth to write.
/// Sample depth to write (ignored by the lossy formats).
pub bit_depth: BitDepth,
/// Add TPDF dither when quantizing to an integer depth.
/// Add TPDF dither when quantizing to an integer depth (ignored by the lossy formats).
pub dither: bool,
/// Write a BWF `bext` chunk (WAV only; ignored for other formats).
pub bwf: Option<BwfInfo>,
@@ -449,15 +648,27 @@ pub struct EncodeOptions {
/// the count (they read 5 and 6 channels with side surrounds and 7 as 6.1 with sides, so the
/// usual layouts for those counts get one; see the README's limits); AIFF has a fixed channel
/// order and ignores it. It must have as many channels as the audio.
///
/// AAC, ALAC, MP3, AC-3 and E-AC-3 store channels in their own order, so here the layout says
/// which speaker each channel of the audio (in WAV order) is, and the channels are reordered
/// to match. Each of these formats has a fixed set of layouts (AAC and ALAC one per channel
/// count, AC-3 one per coding mode); a layout outside it is [`AudioError::Unsupported`]. Side
/// and back surrounds are taken as the same pair where the format has only one.
pub layout: Option<ChannelLayout>,
/// Write WAV in the RF64 layout even below 4 GiB (WAV only; ignored for other formats).
pub force_rf64: bool,
/// The bit rate or quality of a lossy format (ignored by the others). `None` is a constant
/// 64 kbit/s per channel for AAC, 96 kbit/s per channel for MP3, and 96 kbit/s per
/// full-bandwidth channel (the LFE not counted) for AC-3 and E-AC-3, moved to the nearest rate
/// the stream can carry.
pub rate_control: Option<RateControl>,
}
impl EncodeOptions {
/// Options for `format`: 24-bit, no dither, no BWF chunk, the usual layout.
/// Options for `format`: 24-bit, no dither, no BWF chunk, the usual layout, the format's
/// default bit rate.
pub fn new(format: EncodeFormat) -> Self {
Self { format, bit_depth: BitDepth::Int24, dither: false, bwf: None, layout: None, force_rf64: false }
Self { format, bit_depth: BitDepth::Int24, dither: false, bwf: None, layout: None, force_rf64: false, rate_control: None }
}
/// Sets `format`.
@@ -495,6 +706,18 @@ impl EncodeOptions {
self.force_rf64 = force_rf64;
self
}
/// Sets `rate_control` to a constant bit rate in bits per second ([`RateControl::Bitrate`]).
pub fn with_bitrate(mut self, bits_per_second: u32) -> Self {
self.rate_control = Some(RateControl::Bitrate(bits_per_second));
self
}
/// Sets `rate_control` to a constant quality from 0.0 to 1.0 ([`RateControl::Quality`]).
pub fn with_quality(mut self, quality: f32) -> Self {
self.rate_control = Some(RateControl::Quality(quality));
self
}
}
impl Default for EncodeOptions {
+506
View File
@@ -0,0 +1,506 @@
//! The coded formats of [`FileEncoder`](crate::FileEncoder): AAC-LC and ALAC in M4A (through
//! craft-media's MP4 muxer) and MP3, AC-3 and E-AC-3 as raw streams. [`Writer`] maps the caller's
//! WAV-order channels onto the encoder's order, drives the packet encoder, and for M4A records the
//! encoder's priming and the exact length in the edit list.
// Each codec is its own feature, and so are the two sinks: with only some of them built, the
// other halves of the shared code are unused.
#![cfg_attr(
not(all(feature = "aac-encode", feature = "alac-encode", feature = "mp3-encode", feature = "ac3-encode", feature = "eac3-encode")),
allow(dead_code, unused_imports, unused_variables)
)]
use super::failed_write_error;
use super::pcm::validate_layout;
use crate::layout::channel_map;
use crate::{AudioBuffer, AudioError, ChannelLayout, EncodeFormat, EncodeOptions, RateControl, Result};
use std::io::{Cursor, Seek, Write};
/// Frames handed to the encoder at a time, so its buffers and the packets waiting to be written
/// stay small however long a block is. Also the frames of an ALAC packet.
const CHUNK: usize = 4096;
/// Bits per second per channel when no rate is asked for: AAC.
const AAC_DEFAULT_BPS_PER_CHANNEL: u32 = 64_000;
/// Kilobits per second per channel when no rate is asked for: MP3, and AC-3 and E-AC-3 (per
/// full-bandwidth channel).
const DEFAULT_KBPS_PER_CHANNEL: u32 = 96;
/// The speakers of `mask` as labels: `"L R C LFE Ls Rs"`.
fn labels(mask: u32) -> String {
ChannelLayout::from_mask(mask).speakers().iter().map(|s| s.label()).collect::<Vec<_>>().join(" ")
}
/// [`channel_map`] for a format with one layout per channel count ([`EncodeFormat::layout_masks`]),
/// or why the audio does not fit.
fn fixed_map(format: EncodeFormat, name: &str, order: Option<&[usize]>, layout: &ChannelLayout) -> Result<Vec<usize>> {
let Some(&mask) = format.layout_masks(layout.channels()).first() else {
return Err(AudioError::Unsupported(format!("{name} cannot hold {} channels", layout.channels())));
};
channel_map(mask, order, layout).ok_or_else(|| {
AudioError::Unsupported(format!("{name} holds {} channels as {}; the audio is {}", layout.channels(), labels(mask), given(layout)))
})
}
/// The speakers of the caller's layout, for an error message.
fn given(layout: &ChannelLayout) -> String {
layout.mask().map_or_else(|| "without speaker assignment".into(), labels)
}
/// The encoder's channel order over AAC's layout for the count: [`crate::aac::aac_order`], and for 8 channels
/// configuration 7's C, Lc Rc, L R, Ls Rs, LFE over the WAV order L R C LFE Ls Rs Lc Rc.
#[cfg(feature = "aac-encode")]
fn aac_order(channels: usize) -> Option<&'static [usize]> {
if channels == 8 { Some(&[2, 6, 7, 0, 1, 4, 5, 3]) } else { crate::aac::aac_order(channels) }
}
/// The lowest AAC bit rate the writer uses, per channel: 6 kbit/s, and a quarter of the sample
/// rate (256 bits a frame). The encoder accepts less, and from about half of this down codes
/// silence; a file of silence is no answer to a low bit rate (or to kbit/s given as bit/s).
#[cfg(feature = "aac-encode")]
fn aac_floor_per_channel(sample_rate: u32) -> u32 {
(sample_rate / 4).max(6000)
}
/// The AAC rate control for `rate`: a bit rate is kept within what the stream can carry, a
/// quality of 0–1 spans the encoder's VBR range.
#[cfg(feature = "aac-encode")]
fn aac_mode(rate: Option<RateControl>, sample_rate: u32, channels: usize) -> crate::aac::BitrateMode {
use crate::aac::BitrateMode;
let (lo, hi) = crate::aac::cbr_range(sample_rate, channels);
let lo = lo.max(aac_floor_per_channel(sample_rate).saturating_mul(channels as u32)).min(hi.max(lo));
// An empty range (a rate or channel count the encoder refuses anyway) leaves the rate alone.
let fit = |bps: u32| if lo <= hi { bps.clamp(lo, hi) } else { bps };
match rate {
None => BitrateMode::Cbr(fit(AAC_DEFAULT_BPS_PER_CHANNEL.saturating_mul(channels as u32))),
Some(RateControl::Bitrate(bps)) => BitrateMode::Cbr(fit(bps)),
// NaN stays NaN, which the encoder refuses.
Some(RateControl::Quality(q)) => BitrateMode::Vbr(1.0 + 4.0 * q.clamp(0.0, 1.0)),
}
}
/// The bit rate in kbit/s for a codec with constant bit rates only.
fn constant_kbps(name: &str, rate: Option<RateControl>, default: u32) -> Result<u32> {
match rate {
None => Ok(default),
Some(RateControl::Bitrate(bps)) => Ok(bps / 1000),
Some(RateControl::Quality(_)) => {
Err(AudioError::Unsupported(format!("{name} is encoded at a constant bit rate; set a bit rate, not a quality")))
}
}
}
/// The AC-3 or E-AC-3 settings for audio with `layout`, and the channel map onto them: the coding
/// mode whose speakers the layout names, at the nearest bit rate the stream can carry.
#[cfg(any(feature = "ac3-encode", feature = "eac3-encode"))]
fn ac3_config(
codec: crate::ac3::encoder::Codec,
sample_rate: u32,
layout: &ChannelLayout,
rate: Option<RateControl>,
) -> Result<(crate::ac3::encoder::Config, Vec<usize>)> {
use crate::ac3::encoder::{Codec, CodingMode, Config};
use CodingMode::*;
let name = if codec == Codec::Ac3 { "AC-3" } else { "E-AC-3" };
let modes = [Mono, Stereo, ThreeFront, StereoSurround, ThreeFrontSurround, StereoTwoSurround, ThreeFrontTwoSurround, Surround71];
let found = modes.iter().flat_map(|&mode| [false, true].map(|lfe| (mode, lfe))).find_map(|(mode, lfe)| {
// 7.1 is an E-AC-3 programme with an LFE; the encoder has no other.
if mode == Surround71 && (codec != Codec::Eac3 || !lfe) {
return None;
}
let config = Config { codec, sample_rate, bitrate_kbps: 0, mode, lfe };
let map = channel_map(config.channel_layout().mask()?, None, layout)?;
Some((config, map))
});
let Some((mut config, map)) = found else {
return Err(AudioError::Unsupported(format!("{name} has no coding mode for {} channels that are {}", layout.channels(), given(layout))));
};
let full = config.mode.channels() as u32;
let want = constant_kbps(name, rate, DEFAULT_KBPS_PER_CHANNEL * full)?;
// What `Config::validate` asks of the rate: enough for the channels, and for AC-3 an entry of
// the frame size table, for E-AC-3 a syncframe its 11-bit word count can hold.
let least = if config.mode == Surround71 { 384 } else { 32 * full };
config.bitrate_kbps = match codec {
Codec::Ac3 => {
let floor = crate::ac3::BITRATES.iter().copied().find(|&r| r >= least).unwrap_or(least);
crate::ac3::BITRATES.iter().rev().copied().find(|&r| r <= want).filter(|&r| r >= floor).unwrap_or(floor)
}
Codec::Eac3 => {
let most = if config.mode == Surround71 { 1024 } else { (2048 * u64::from(sample_rate) / 96_000).min(1024) as u32 };
want.clamp(least, most.max(least))
}
};
Ok((config, map))
}
/// One encoded packet and the frames it decodes to.
struct Packet {
data: Vec<u8>,
frames: u32,
}
/// A packet encoder of any of the codecs, taking planar `f32` in its own channel order.
enum Codec {
#[cfg(feature = "aac-encode")]
Aac(Box<crate::aac::Encoder>),
#[cfg(feature = "alac-encode")]
Alac {
enc: Box<crate::alac::Encoder>,
quantizers: Vec<super::pcm::Quantizer>,
/// Quantized samples of the packet being filled, per channel.
pending: Vec<Vec<i32>>,
},
#[cfg(feature = "mp3-encode")]
Mp3(Box<crate::mp3::Encoder>),
#[cfg(any(feature = "ac3-encode", feature = "eac3-encode"))]
Ac3 {
enc: Box<crate::ac3::encoder::Encoder>,
/// The block with every sample finite and within ±1, as the encoder requires.
planes: Vec<Vec<f32>>,
},
}
impl Codec {
/// Encodes `planes` (one slice per encoder channel, equally long, at most [`CHUNK`] frames)
/// and appends the packets completed.
fn push(&mut self, planes: &[&[f32]], out: &mut Vec<Packet>) -> Result<()> {
match self {
#[cfg(feature = "aac-encode")]
Codec::Aac(enc) => out.extend(enc.encode(planes).into_iter().map(|data| Packet { data, frames: crate::aac::FRAME_LEN as u32 })),
#[cfg(feature = "alac-encode")]
Codec::Alac { enc, quantizers, pending } => {
let frames = planes.first().map_or(0, |p| p.len());
let mut at = 0;
while at < frames {
let filled = pending.first().map_or(0, Vec::len);
let end = frames.min(at + CHUNK.saturating_sub(filled).max(1));
for ((dst, q), src) in pending.iter_mut().zip(quantizers.iter_mut()).zip(planes) {
dst.extend(src.get(at..end).unwrap_or_default().iter().map(|&s| q.quantize(s)));
}
at = end;
if pending.first().is_some_and(|p| p.len() >= CHUNK) {
alac_packet(enc, pending, out)?;
}
}
}
#[cfg(feature = "mp3-encode")]
Codec::Mp3(enc) => {
let data = enc.encode(planes);
if !data.is_empty() {
out.push(Packet { data, frames: 0 });
}
}
#[cfg(any(feature = "ac3-encode", feature = "eac3-encode"))]
Codec::Ac3 { enc, planes: clean } => {
for (dst, src) in clean.iter_mut().zip(planes) {
dst.clear();
dst.extend(src.iter().map(|&s| if s.is_nan() { 0.0 } else { s.clamp(-1.0, 1.0) }));
}
let refs: Vec<&[f32]> = clean.iter().map(Vec::as_slice).collect();
out.extend(enc.push(&refs)?.into_iter().map(|p| Packet { data: p.data, frames: p.samples }));
}
}
Ok(())
}
/// Encodes what the encoder still holds and appends the last packets.
fn finish(&mut self, out: &mut Vec<Packet>) -> Result<()> {
match self {
#[cfg(feature = "aac-encode")]
Codec::Aac(enc) => out.extend(enc.flush().into_iter().map(|data| Packet { data, frames: crate::aac::FRAME_LEN as u32 })),
#[cfg(feature = "alac-encode")]
Codec::Alac { enc, pending, .. } => {
if pending.first().is_some_and(|p| !p.is_empty()) {
alac_packet(enc, pending, out)?;
}
}
#[cfg(feature = "mp3-encode")]
Codec::Mp3(enc) => {
let data = enc.flush();
if !data.is_empty() {
out.push(Packet { data, frames: 0 });
}
}
#[cfg(any(feature = "ac3-encode", feature = "eac3-encode"))]
Codec::Ac3 { enc, .. } => out.extend(enc.finish()?.packets.into_iter().map(|p| Packet { data: p.data, frames: p.samples })),
}
Ok(())
}
/// Decoded frames before the first frame of the audio.
fn priming(&self) -> u32 {
match self {
#[cfg(feature = "aac-encode")]
Codec::Aac(enc) => enc.priming_samples(),
#[allow(unreachable_patterns)]
_ => 0,
}
}
/// The MP4 sample entry of the stream as encoded so far (`bytes` in packets of `frames`
/// frames in all): the configuration a decoder needs, with the average bit rate.
#[cfg(any(feature = "aac-encode", feature = "alac-encode"))]
fn sample_entry(&self, sample_rate: u32, channels: u32, bytes: u64, frames: u64) -> Option<craft_media::isobmff::SampleEntry> {
use craft_media::isobmff::{CodecConfig, FourCc, SampleEntry};
match self {
#[cfg(feature = "aac-encode")]
Codec::Aac(enc) => {
let mut entry = SampleEntry::aac(enc.audio_specific_config(), channels, sample_rate);
if let CodecConfig::Aac(config) = &mut entry.codec
&& frames > 0
{
let bps = u128::from(bytes) * 8 * u128::from(sample_rate) / u128::from(frames);
config.avg_bitrate = u32::try_from(bps).unwrap_or(u32::MAX);
}
Some(entry)
}
#[cfg(feature = "alac-encode")]
Codec::Alac { enc, .. } => {
let bits = u16::from(enc.encoder_config().bit_depth);
Some(SampleEntry::audio(FourCc(*b"alac"), CodecConfig::Alac { cookie: enc.cookie() }, channels, f64::from(sample_rate), bits))
}
#[allow(unreachable_patterns)]
_ => None,
}
}
}
/// Encodes the pending samples as one ALAC packet and empties them.
#[cfg(feature = "alac-encode")]
fn alac_packet(enc: &mut crate::alac::Encoder, pending: &mut [Vec<i32>], out: &mut Vec<Packet>) -> Result<()> {
let refs: Vec<&[i32]> = pending.iter().map(Vec::as_slice).collect();
let frames = refs.first().map_or(0, |p| p.len()) as u32;
let data = enc.encode(&refs)?;
pending.iter_mut().for_each(Vec::clear);
out.push(Packet { data, frames });
Ok(())
}
/// A muxer's error as this crate's: a failed write stays an I/O error.
#[cfg(any(feature = "aac-encode", feature = "alac-encode"))]
fn mux_error(e: craft_media::isobmff::Error) -> AudioError {
match e {
craft_media::isobmff::Error::Io(e) => AudioError::Io(e),
e => AudioError::Encode(format!("M4A: {e}")),
}
}
/// An M4A file being written: one audio track whose samples are the packets.
///
/// The last packet is held back until the length is known: its duration is cut to the audio's
/// last frame, so the sample durations add up to the priming plus the audio, and the edit that
/// skips the priming ends where the audio does. The movie timescale is the sample rate, which
/// keeps that edit exact.
#[cfg(any(feature = "aac-encode", feature = "alac-encode"))]
struct M4a<W: Write + Seek> {
mux: craft_media::isobmff::Mp4Writer<W>,
/// The track, added with the first packet: a file with no audio gets a track without an edit.
track: Option<usize>,
entry: craft_media::isobmff::SampleEntry,
sample_rate: u32,
channels: u32,
priming: u32,
held: Option<Packet>,
/// Frames and bytes of the packets written, the held one not counted.
frames: u64,
bytes: u64,
}
#[cfg(any(feature = "aac-encode", feature = "alac-encode"))]
impl<W: Write + Seek> M4a<W> {
fn new(out: W, codec: &Codec, sample_rate: u32, channels: u32) -> Result<Self> {
use craft_media::isobmff::{Brand, Mp4Writer, WriterOptions};
let entry = codec.sample_entry(sample_rate, channels, 0, 0).ok_or_else(|| AudioError::Unsupported("M4A holds AAC and ALAC".into()))?;
let mut options = WriterOptions::new(Brand::Mp4);
options.movie_timescale = sample_rate;
let mux = Mp4Writer::new(out, options).map_err(mux_error)?;
Ok(M4a { mux, track: None, entry, sample_rate, channels, priming: codec.priming(), held: None, frames: 0, bytes: 0 })
}
fn track(&mut self, has_audio: bool) -> Result<usize> {
if let Some(track) = self.track {
return Ok(track);
}
let mut config = craft_media::isobmff::TrackConfig::new(self.entry.clone(), self.sample_rate);
if has_audio && self.priming > 0 {
config.media_start = Some(i64::from(self.priming));
// AAC's overlap: a packet decodes right only after the one before it. Apple's
// decoders take the priming from the edit only when the track says so.
config.roll_distance = Some(-1);
}
let track = self.mux.add_track(config).map_err(mux_error)?;
self.track = Some(track);
Ok(track)
}
fn sample(&mut self, packet: &Packet, duration: u32) -> Result<()> {
let track = self.track(true)?;
let sample = craft_media::isobmff::WriteSample { data: &packet.data, duration, composition_offset: 0, is_sync: true };
self.mux.write_sample(track, sample).map_err(mux_error)?;
self.frames += u64::from(duration);
self.bytes += packet.data.len() as u64;
Ok(())
}
fn write(&mut self, packet: Packet) -> Result<()> {
if let Some(held) = self.held.replace(packet) {
self.sample(&held, held.frames)?;
}
Ok(())
}
/// Writes the last packet, cut to the end of `audio_frames` frames of audio, and the `moov`.
fn finish(mut self, codec: &Codec, audio_frames: u64) -> Result<W> {
if let Some(held) = self.held.take() {
let rest = (u64::from(self.priming) + audio_frames).saturating_sub(self.frames);
self.sample(&held, rest.min(u64::from(held.frames)) as u32)?;
}
let track = self.track(false)?;
// The configuration is complete only now: the bit rate, and ALAC's largest packet.
if let Some(entry) = codec.sample_entry(self.sample_rate, self.channels, self.bytes, self.frames) {
self.mux.set_sample_entry(track, entry).map_err(mux_error)?;
}
self.mux.finish().map_err(mux_error)
}
}
/// Where the packets go.
enum Sink<W: Write + Seek> {
#[cfg(any(feature = "aac-encode", feature = "alac-encode"))]
M4a(Box<M4a<W>>),
/// The packets in a row are the file.
Raw(W),
}
/// A file of one of the coded formats written block by block.
pub(crate) struct Writer<W: Write + Seek> {
codec: Codec,
sink: Sink<W>,
/// For each encoder channel, the caller's channel that feeds it.
map: Vec<usize>,
/// The constant bit rate the encoder was set to, bits per second; `None` for ALAC and for
/// AAC at a constant quality.
bitrate: Option<u32>,
frames: u64,
packets: Vec<Packet>,
/// Set when a write has failed: the encoder and the sink no longer agree, so the writer
/// refuses every later call.
failed: bool,
}
impl<W: Write + Seek> Writer<W> {
pub(crate) fn new(out: W, opts: &EncodeOptions, sample_rate: u32, channels: usize) -> Result<Self> {
validate_layout(channels, sample_rate)?;
let layout = opts.layout.unwrap_or_else(|| ChannelLayout::default_for(channels as u16));
let (codec, map, bitrate) = match opts.format {
#[cfg(feature = "aac-encode")]
EncodeFormat::Aac => {
let map = fixed_map(EncodeFormat::Aac, "AAC", aac_order(channels), &layout)?;
let mode = aac_mode(opts.rate_control, sample_rate, channels);
let config = crate::aac::EncoderConfig { mode, ..crate::aac::EncoderConfig::cbr(sample_rate, channels, 0) };
let bitrate = match mode {
crate::aac::BitrateMode::Cbr(bps) => Some(bps),
crate::aac::BitrateMode::Vbr(_) => None,
};
(Codec::Aac(Box::new(crate::aac::Encoder::new(config)?)), map, bitrate)
}
#[cfg(feature = "alac-encode")]
EncodeFormat::Alac => {
let count = u8::try_from(channels).unwrap_or(u8::MAX);
let map = fixed_map(EncodeFormat::Alac, "ALAC", crate::alac::alac_order(count), &layout)?;
let bits = match opts.bit_depth {
crate::BitDepth::Int16 => 16,
crate::BitDepth::Int24 => 24,
crate::BitDepth::Int32 => 32,
crate::BitDepth::Float32 => return Err(AudioError::Unsupported("ALAC cannot store 32-bit float samples".into())),
};
let enc = crate::alac::Encoder::new(crate::alac::EncoderConfig::new(sample_rate, count, bits).with_frame_length(CHUNK as u32))?;
let quantizers = super::pcm::Quantizer::per_channel(u32::from(bits), opts.dither, channels);
(Codec::Alac { enc: Box::new(enc), quantizers, pending: vec![Vec::new(); channels] }, map, None)
}
#[cfg(feature = "mp3-encode")]
EncodeFormat::Mp3 => {
let map = fixed_map(EncodeFormat::Mp3, "MP3", None, &layout)?;
let want = constant_kbps("MP3", opts.rate_control, DEFAULT_KBPS_PER_CHANNEL * channels as u32)?;
// A sample rate MP3 has not is the encoder's to refuse.
let kbps = crate::mp3::nearest_bitrate(sample_rate, want).unwrap_or(want);
let enc = crate::mp3::Encoder::new(crate::mp3::Config::cbr(sample_rate, channels, kbps))?;
(Codec::Mp3(Box::new(enc)), map, Some(kbps.saturating_mul(1000)))
}
#[cfg(any(feature = "ac3-encode", feature = "eac3-encode"))]
EncodeFormat::Ac3 | EncodeFormat::Eac3 => {
let codec = if opts.format == EncodeFormat::Ac3 { crate::ac3::encoder::Codec::Ac3 } else { crate::ac3::encoder::Codec::Eac3 };
let (config, map) = ac3_config(codec, sample_rate, &layout, opts.rate_control)?;
let enc = crate::ac3::encoder::Encoder::new(config)?;
(Codec::Ac3 { enc: Box::new(enc), planes: vec![Vec::new(); channels] }, map, Some(config.bitrate_kbps.saturating_mul(1000)))
}
#[allow(unreachable_patterns)]
f => return Err(AudioError::Unsupported(format!("writing {f:?}"))),
};
let sink = match opts.format {
#[cfg(any(feature = "aac-encode", feature = "alac-encode"))]
EncodeFormat::Aac | EncodeFormat::Alac => Sink::M4a(Box::new(M4a::new(out, &codec, sample_rate, channels as u32)?)),
_ => Sink::Raw(out),
};
Ok(Writer { codec, sink, map, bitrate, frames: 0, packets: Vec::new(), failed: false })
}
pub(crate) fn bitrate(&self) -> Option<u32> {
self.bitrate
}
/// Hands the packets waiting to the sink.
fn drain(&mut self) -> Result<()> {
for packet in self.packets.drain(..) {
match &mut self.sink {
#[cfg(any(feature = "aac-encode", feature = "alac-encode"))]
Sink::M4a(m4a) => m4a.write(packet)?,
Sink::Raw(out) => out.write_all(&packet.data)?,
}
}
Ok(())
}
/// Appends `frames` frames of `block`, which holds every channel at least that long.
pub(crate) fn write<C: AsRef<[f32]>>(&mut self, block: &[C], frames: usize) -> Result<()> {
if self.failed {
return Err(failed_write_error());
}
for at in (0..frames).step_by(CHUNK) {
let end = frames.min(at + CHUNK);
let planes: Vec<&[f32]> = self.map.iter().map(|&c| block.get(c).and_then(|p| p.as_ref().get(at..end)).unwrap_or_default()).collect();
let written = self.codec.push(&planes, &mut self.packets).and_then(|()| self.drain());
if let Err(e) = written {
self.failed = true;
return Err(e);
}
}
self.frames = self.frames.saturating_add(frames as u64);
Ok(())
}
pub(crate) fn finish(mut self) -> Result<W> {
if self.failed {
return Err(failed_write_error());
}
self.codec.finish(&mut self.packets)?;
self.drain()?;
match self.sink {
#[cfg(any(feature = "aac-encode", feature = "alac-encode"))]
Sink::M4a(m4a) => m4a.finish(&self.codec, self.frames),
Sink::Raw(mut out) => {
out.flush()?;
Ok(out)
}
}
}
}
pub(crate) fn encode(buf: &AudioBuffer, opts: &EncodeOptions) -> Result<Vec<u8>> {
let mut w = Writer::new(Cursor::new(Vec::new()), opts, buf.sample_rate, buf.channels.len())?;
w.write(&buf.channels, buf.frames())?;
Ok(w.finish()?.into_inner())
}
#[cfg(test)]
mod tests;
+167
View File
@@ -0,0 +1,167 @@
use super::*;
use crate::Speaker;
fn map(mask: u32, order: Option<&[usize]>, layout: u32) -> Option<Vec<usize>> {
channel_map(mask, order, &ChannelLayout::from_mask(layout))
}
/// Channels are matched by speaker, not by position: a layout that lists the same speakers in
/// another WAV order is reordered, and one with other speakers is refused.
#[test]
fn channels_are_mapped_by_speaker() {
// L R C LFE Ls Rs onto itself, and onto an encoder order C L R Ls Rs LFE.
assert_eq!(map(0x60F, None, 0x60F), Some(vec![0, 1, 2, 3, 4, 5]));
assert_eq!(map(0x60F, Some(&[2, 0, 1, 4, 5, 3]), 0x60F), Some(vec![2, 0, 1, 4, 5, 3]));
// Back surrounds feed a format that has one surround pair, and the other way round.
assert_eq!(map(0x60F, None, 0x3F), Some(vec![0, 1, 2, 3, 4, 5]));
assert_eq!(map(0x3F, None, 0x60F), Some(vec![0, 1, 2, 3, 4, 5]));
// 6.1 with the back centre after the pair (L R C LFE Lb Rb Cb) onto L R C LFE Cb Ls Rs.
assert_eq!(map(0x70F, None, 0x13F), Some(vec![0, 1, 2, 3, 6, 4, 5]));
// Quad has no centre; 7.1 with sides and backs has no front pair left and right of centre.
assert_eq!(map(0x107, None, 0x33), None);
assert_eq!(map(0xFF, None, 0x63F), None);
// With both pairs in the format, one pair cannot feed both.
assert_eq!(map(0x63F, None, 0xFF), None);
assert_eq!(channel_map(0x3, None, &ChannelLayout::unordered(2)), None);
assert_eq!(map(0x3, None, 0x7), None);
}
#[cfg(feature = "aac-encode")]
#[test]
fn every_aac_channel_count_has_a_layout_and_an_order() {
for channels in 1..=8 {
let mask = EncodeFormat::Aac.layout_masks(channels as u16)[0];
assert_eq!(mask.count_ones() as usize, channels);
let mut order = map(mask, aac_order(channels), mask).unwrap();
order.sort_unstable();
assert_eq!(order, (0..channels).collect::<Vec<_>>());
}
assert!(EncodeFormat::Aac.layout_masks(9).is_empty() && EncodeFormat::Aac.layout_masks(0).is_empty());
// The layouts this crate's decoder reports for what the encoder writes (`track::aac_layout`),
// and configuration 7's speakers for 8 channels.
let masks: Vec<u32> = (1..=8).map(|channels| EncodeFormat::Aac.layout_masks(channels)[0]).collect();
assert_eq!(masks, [0x4, 0x3, 0x7, 0x107, 0x607, 0x60F, 0x70F, 0xFF]);
assert_eq!(
(EncodeFormat::Mp3.layout_masks(1), EncodeFormat::Mp3.layout_masks(2), EncodeFormat::Mp3.layout_masks(3)),
(&[0x4][..], &[0x3][..], &[][..])
);
// Configuration 7: C, Lc Rc, L R, Ls Rs, LFE.
let wide: Vec<Speaker> = ChannelLayout::from_mask(0xFF).speakers();
let named: Vec<Speaker> = aac_order(8).unwrap().iter().map(|&c| wide[c]).collect();
use Speaker::*;
assert_eq!(named, [FrontCenter, FrontLeftOfCenter, FrontRightOfCenter, FrontLeft, FrontRight, BackLeft, BackRight, Lfe]);
}
/// The range the writer keeps a bit rate in is the one the encoder accepts.
#[cfg(feature = "aac-encode")]
#[test]
fn the_aac_bit_rate_range_is_the_encoders() {
use crate::aac::{Encoder, EncoderConfig, SAMPLE_RATES};
for &rate in &SAMPLE_RATES {
for channels in 1..=8 {
let (lo, hi) = crate::aac::cbr_range(rate, channels);
assert!(lo <= hi, "{rate} Hz, {channels} channels");
let accepts = |bps| Encoder::new(EncoderConfig::cbr(rate, channels, bps)).is_ok();
assert!(accepts(lo) && accepts(hi), "{rate} Hz, {channels} channels: {lo}..={hi}");
assert!(!accepts(lo - 1) && !accepts(hi + 1), "{rate} Hz, {channels} channels: {lo}..={hi}");
for want in [None, Some(RateControl::Bitrate(0)), Some(RateControl::Bitrate(u32::MAX))] {
let mode = aac_mode(want, rate, channels);
assert!(
Encoder::new(EncoderConfig { mode, ..EncoderConfig::cbr(rate, channels, 0) }).is_ok(),
"{rate} Hz, {channels} channels, {want:?}"
);
}
}
}
}
/// Every layout the AC-3 encoders have is found from its speakers, at a bit rate the encoder
/// accepts whatever rate was asked for.
#[cfg(all(feature = "ac3-encode", feature = "eac3-encode"))]
#[test]
fn ac3_settings_follow_the_layout_and_validate() {
use crate::ac3::encoder::{Codec, CodingMode};
let layouts = [
(0x4, CodingMode::Mono, false),
(0x3, CodingMode::Stereo, false),
(0xB, CodingMode::Stereo, true),
(0x7, CodingMode::ThreeFront, false),
(0x103, CodingMode::StereoSurround, false),
(0x107, CodingMode::ThreeFrontSurround, false),
(0x33, CodingMode::StereoTwoSurround, false),
(0x603, CodingMode::StereoTwoSurround, false),
(0x37, CodingMode::ThreeFrontTwoSurround, false),
(0x3F, CodingMode::ThreeFrontTwoSurround, true),
(0x60F, CodingMode::ThreeFrontTwoSurround, true),
];
for codec in [Codec::Ac3, Codec::Eac3] {
for sample_rate in [32_000, 44_100, 48_000] {
for (mask, mode, lfe) in layouts {
for want in [None, Some(RateControl::Bitrate(0)), Some(RateControl::Bitrate(200_000)), Some(RateControl::Bitrate(u32::MAX))] {
let layout = ChannelLayout::from_mask(mask);
let (config, map) = ac3_config(codec, sample_rate, &layout, want).unwrap();
assert_eq!((config.mode, config.lfe), (mode, lfe), "{mask:#x}");
assert_eq!(map, (0..usize::from(layout.channels())).collect::<Vec<_>>());
assert_eq!(config.validate(), Ok(()), "{codec:?} {sample_rate} {mask:#x} {want:?}: {} kbit/s", config.bitrate_kbps);
}
}
let seven_one = ac3_config(codec, sample_rate, &ChannelLayout::SURROUND_7_1, Some(RateControl::Bitrate(u32::MAX)));
match codec {
Codec::Ac3 => assert!(matches!(seven_one, Err(AudioError::Unsupported(_)))),
Codec::Eac3 => assert_eq!(seven_one.unwrap().0.validate(), Ok(())),
}
}
}
// The highest table rate not above the one asked for; the default is 96 kbit/s per channel.
let rate = |codec, mask, want| ac3_config(codec, 48_000, &ChannelLayout::from_mask(mask), want).unwrap().0.bitrate_kbps;
assert_eq!(rate(Codec::Ac3, 0x3, Some(RateControl::Bitrate(200_000))), 192);
assert_eq!(rate(Codec::Ac3, 0x3, None), 192);
assert_eq!(rate(Codec::Ac3, 0x60F, None), 448);
assert_eq!(rate(Codec::Ac3, 0x60F, Some(RateControl::Bitrate(1))), 160);
assert_eq!(rate(Codec::Eac3, 0x3, Some(RateControl::Bitrate(200_500))), 200);
assert!(matches!(ac3_config(Codec::Ac3, 48_000, &ChannelLayout::STEREO, Some(RateControl::Quality(0.5))), Err(AudioError::Unsupported(_))));
assert!(matches!(ac3_config(Codec::Ac3, 48_000, &ChannelLayout::unordered(2), None), Err(AudioError::Unsupported(_))));
}
/// The layouts `EncodeFormat` lists are the encoders' own: ALAC's layout per channel count, and
/// the speakers of every AC-3 and E-AC-3 coding mode the encoder has.
#[cfg(all(feature = "alac-encode", feature = "ac3-encode", feature = "eac3-encode"))]
#[test]
fn the_listed_layouts_are_the_encoders() {
use crate::ac3::encoder::{Codec, CodingMode::*, Config};
for channels in 0..=10u16 {
let alac = crate::alac::channel_mask(channels as u8);
assert_eq!(EncodeFormat::Alac.layout_masks(channels), if alac == 0 { &[][..] } else { std::slice::from_ref(&alac) }, "ALAC, {channels}");
for (format, codec) in [(EncodeFormat::Ac3, Codec::Ac3), (EncodeFormat::Eac3, Codec::Eac3)] {
let modes = [Mono, Stereo, ThreeFront, StereoSurround, ThreeFrontSurround, StereoTwoSurround, ThreeFrontTwoSurround, Surround71];
let mut encoder: Vec<u32> = modes
.iter()
.flat_map(|&mode| [false, true].map(|lfe| Config { codec, sample_rate: 48_000, bitrate_kbps: 640, mode, lfe }))
.filter(|config| config.validate().is_ok() && config.channels() == usize::from(channels))
.filter_map(|config| config.channel_layout().mask())
.collect();
let mut listed = format.layout_masks(channels).to_vec();
encoder.sort_unstable();
listed.sort_unstable();
assert_eq!(listed, encoder, "{format:?}, {channels} channels");
for &mask in &listed {
let layout = ChannelLayout::from_mask(mask);
assert_eq!(ac3_config(codec, 48_000, &layout, None).unwrap().0.channel_layout(), layout);
}
}
}
}
/// The sample rates `EncodeFormat` lists are the encoders'.
#[cfg(all(feature = "aac-encode", feature = "mp3-encode"))]
#[test]
fn the_listed_sample_rates_are_the_encoders() {
let sorted = |rates: &[u32]| {
let mut rates = rates.to_vec();
rates.sort_unstable();
rates
};
assert_eq!(EncodeFormat::Aac.sample_rates().unwrap(), sorted(&crate::aac::SAMPLE_RATES));
assert_eq!(EncodeFormat::Mp3.sample_rates().unwrap(), sorted(&crate::mp3::SAMPLE_RATES));
}
+209 -84
View File
@@ -1,28 +1,45 @@
//! Encoding: WAV/BWF/RF64 and AIFF/AIFF-C writers (`pcm-encode`) and the FLAC encoder
//! (`flac-encode`), whole-buffer and streaming.
//! Encoding: WAV/BWF/RF64 and AIFF/AIFF-C writers (`pcm-encode`), the FLAC encoder
//! (`flac-encode`) and the coded formats (AAC and ALAC in M4A, MP3, AC-3 and E-AC-3 streams, each
//! with its codec's feature), whole-buffer and streaming.
#[cfg(feature = "pcm-encode")]
mod aiff;
#[cfg(any(feature = "aac-encode", feature = "alac-encode", feature = "mp3-encode", feature = "ac3-encode", feature = "eac3-encode"))]
mod coded;
#[cfg(feature = "flac-encode")]
pub(crate) mod flac;
mod pcm;
#[cfg(feature = "vorbis-encode")]
mod vorbis;
#[cfg(feature = "vorbis-encode")]
pub use vorbis::{OGG_BITRATES, encode as encode_ogg};
#[cfg(feature = "pcm-encode")]
mod raw;
#[cfg(feature = "vorbis-encode")]
pub(crate) mod vorbis;
#[cfg(feature = "pcm-encode")]
mod wav;
#[cfg(feature = "vorbis-encode")]
pub use vorbis::OGG_BITRATES;
use crate::{AudioBuffer, AudioError, ChannelLayout, EncodeFormat, EncodeOptions, Result};
#[cfg(feature = "pcm-encode")]
pub use raw::{pcm_aiff_file, pcm_aiff_header, pcm_wav_file, pcm_wav_header};
#[cfg(any(
feature = "pcm-encode",
feature = "flac-encode",
feature = "aac-encode",
feature = "alac-encode",
feature = "mp3-encode",
feature = "ac3-encode",
feature = "eac3-encode"
))]
use std::io::{Seek, Write};
/// Encode `buf` as WAV/BWF, AIFF/AIFF-C or FLAC. Integer depths clamp samples to [-1, 1]; float
/// Encode `buf` as the file `opts.format` names. Integer depths clamp samples to [-1, 1]; float
/// keeps values above full scale. `opts.layout`, when set, must have `buf`'s channel count.
///
/// The lossy formats take `opts.rate_control`. AAC and ALAC are written as M4A, which records the
/// encoder's priming and the exact length, so the file decodes to `buf`'s frames. MP3, AC-3 and
/// E-AC-3 are raw streams, which have no place for that: they decode with the codec's delay in
/// front and padded to whole frames.
///
/// ```
/// # #[cfg(feature = "pcm-encode")] {
/// use craft_audio::{AudioBuffer, BitDepth, EncodeFormat, EncodeOptions, encode};
@@ -36,6 +53,7 @@ use std::io::{Seek, Write};
pub fn encode(buf: &AudioBuffer, opts: &EncodeOptions) -> Result<Vec<u8>> {
check_built(opts.format)?;
// Checked for every format; WAV and FLAC record it.
#[cfg_attr(not(any(feature = "pcm-encode", feature = "flac-encode")), allow(unused_variables))]
let mask = opts.layout.map(|l| wav_mask(&l, buf.channels.len())).transpose()?;
match opts.format {
#[cfg(feature = "pcm-encode")]
@@ -44,6 +62,20 @@ pub fn encode(buf: &AudioBuffer, opts: &EncodeOptions) -> Result<Vec<u8>> {
EncodeFormat::Aiff => aiff::encode(buf, opts.bit_depth, opts.dither),
#[cfg(feature = "flac-encode")]
EncodeFormat::Flac => flac::encode(buf, opts.bit_depth, opts.dither, mask),
#[cfg(any(feature = "aac-encode", feature = "alac-encode", feature = "mp3-encode", feature = "ac3-encode", feature = "eac3-encode"))]
EncodeFormat::Aac | EncodeFormat::Alac | EncodeFormat::Mp3 | EncodeFormat::Ac3 | EncodeFormat::Eac3 => coded::encode(buf, opts),
#[cfg(feature = "vorbis-encode")]
EncodeFormat::Ogg => {
if opts.layout.is_some_and(|layout| !EncodeFormat::Ogg.supports_layout(&layout)) {
return Err(AudioError::Unsupported("Vorbis requires a mono or stereo speaker layout".into()));
}
let kbps = match opts.rate_control {
None => 192,
Some(crate::RateControl::Bitrate(bps)) => bps / 1000,
Some(crate::RateControl::Quality(_)) => return Err(AudioError::Unsupported("Ogg export takes a target bitrate".into())),
};
vorbis::encode(buf, kbps)
}
#[allow(unreachable_patterns)]
f => Err(AudioError::Unsupported(format!("writing {f:?}"))),
}
@@ -51,65 +83,49 @@ pub fn encode(buf: &AudioBuffer, opts: &EncodeOptions) -> Result<Vec<u8>> {
/// Refuses a format whose writer is not built, before anything else about the request is checked.
fn check_built(format: EncodeFormat) -> Result<()> {
let (built, feature) = match format {
EncodeFormat::Flac => (cfg!(feature = "flac-encode"), "flac-encode"),
#[cfg(feature = "vorbis-encode")]
EncodeFormat::Ogg => (cfg!(feature = "vorbis-encode"), "vorbis-encode"),
_ => (cfg!(feature = "pcm-encode"), "pcm-encode"),
};
if built { Ok(()) } else { Err(AudioError::Unsupported(format!("writing {format:?} needs the `{feature}` feature"))) }
if format.is_built() { Ok(()) } else { Err(AudioError::Unsupported(format!("writing {format:?} needs the `{}` feature", format.feature()))) }
}
/// The file extensions of the formats [`encode`] can write (those whose features are on).
#[cfg(all(feature = "pcm-encode", feature = "flac-encode", feature = "vorbis-encode"))]
pub const ENCODE_EXTENSIONS: &[&str] = &["wav", "wave", "bwf", "aif", "aiff", "aifc", "flac", "ogg"];
/// The file extensions of the formats [`encode`] can write (those whose features are on).
#[cfg(all(feature = "pcm-encode", feature = "flac-encode", not(feature = "vorbis-encode")))]
pub const ENCODE_EXTENSIONS: &[&str] = &["wav", "wave", "bwf", "aif", "aiff", "aifc", "flac"];
/// The file extensions of the formats [`encode`] can write (those whose features are on).
#[cfg(all(feature = "pcm-encode", feature = "vorbis-encode", not(feature = "flac-encode")))]
pub const ENCODE_EXTENSIONS: &[&str] = &["wav", "wave", "bwf", "aif", "aiff", "aifc", "ogg"];
/// The file extensions of the formats [`encode`] can write (those whose features are on).
#[cfg(all(feature = "pcm-encode", not(feature = "flac-encode"), not(feature = "vorbis-encode")))]
pub const ENCODE_EXTENSIONS: &[&str] = &["wav", "wave", "bwf", "aif", "aiff", "aifc"];
/// The file extensions of the formats [`encode`] can write (those whose features are on).
#[cfg(all(feature = "flac-encode", feature = "vorbis-encode", not(feature = "pcm-encode")))]
pub const ENCODE_EXTENSIONS: &[&str] = &["flac", "ogg"];
/// The file extensions of the formats [`encode`] can write (those whose features are on).
#[cfg(all(feature = "flac-encode", not(feature = "pcm-encode"), not(feature = "vorbis-encode")))]
pub const ENCODE_EXTENSIONS: &[&str] = &["flac"];
/// The file extensions of the formats [`encode`] can write (those whose features are on).
#[cfg(all(feature = "vorbis-encode", not(feature = "pcm-encode"), not(feature = "flac-encode")))]
pub const ENCODE_EXTENSIONS: &[&str] = &["ogg"];
/// Encode `buf` as an Ogg Vorbis stream at about `kbps` (variable, as Vorbis is): stereo, or mono
/// for a mono buffer. A bitrate the encoder has no setup for at that rate and channel count falls
/// back to a quality that suits it. Whole-buffer only: no streaming encoder is provided for Vorbis.
///
/// ```
/// # #[cfg(feature = "vorbis-encode")] {
/// use craft_audio::{AudioBuffer, encode_ogg};
///
/// let buf = AudioBuffer::new(48_000, 2, 48_000); // one second of stereo silence
/// let ogg = encode_ogg(&buf, 192).unwrap();
/// assert_eq!(&ogg[..4], b"OggS");
/// # }
/// ```
#[cfg(feature = "vorbis-encode")]
pub fn encode_ogg(buf: &AudioBuffer, kbps: u32) -> Result<Vec<u8>> {
vorbis::encode(buf, kbps)
/// Every extension [`ENCODE_EXTENSIONS`] can list, and how many of them the features built give.
const fn extensions() -> ([&'static str; 13], usize) {
let mut all = [""; 13];
let mut n = 0;
macro_rules! add {
($built:expr, $($extension:literal),+) => {
if $built {
$(
all[n] = $extension;
n += 1;
)+
}
};
}
add!(cfg!(feature = "pcm-encode"), "wav", "wave", "bwf", "aif", "aiff", "aifc");
add!(cfg!(feature = "flac-encode"), "flac");
add!(cfg!(any(feature = "aac-encode", feature = "alac-encode")), "m4a");
add!(cfg!(feature = "mp3-encode"), "mp3");
add!(cfg!(feature = "ac3-encode"), "ac3");
add!(cfg!(feature = "eac3-encode"), "eac3", "ec3");
add!(cfg!(all(feature = "vorbis-encode", not(target_arch = "wasm32"))), "ogg");
(all, n)
}
/// The format [`encode`] writes for a file extension or format name (`wav`, `aiff`, `flac`,
/// case-insensitive, with or without the dot), or `None` when it cannot write it. `aifc` is
/// AIFF: float AIFF is written as AIFF-C.
const EXTENSIONS: ([&str; 13], usize) = extensions();
/// The file extensions of the formats [`encode`] can write (those whose features are on).
pub const ENCODE_EXTENSIONS: &[&str] = EXTENSIONS.0.split_at(EXTENSIONS.1).0;
/// The format [`encode`] writes for a file extension or format name (`wav`, `aiff`, `flac`, `m4a`,
/// `mp3`, `ac3`, `eac3`, case-insensitive, with or without the dot), or `None` when it cannot
/// write it. `aifc` is AIFF: float AIFF is written as AIFF-C. `m4a` is AAC when the AAC encoder
/// is built and ALAC otherwise; `alac` always names ALAC.
///
/// ```
/// # #[cfg(feature = "pcm-encode")] {
/// use craft_audio::{EncodeFormat, encode_format_for};
///
/// assert_eq!(encode_format_for(".AIFF"), Some(EncodeFormat::Aiff));
/// assert_eq!(encode_format_for("mp3"), None);
/// assert_eq!(encode_format_for("unknown"), None);
/// # }
/// ```
pub fn encode_format_for(name: &str) -> Option<EncodeFormat> {
@@ -120,7 +136,19 @@ pub fn encode_format_for(name: &str) -> Option<EncodeFormat> {
"aif" | "aiff" | "aifc" => Some(EncodeFormat::Aiff),
#[cfg(feature = "flac-encode")]
"flac" => Some(EncodeFormat::Flac),
#[cfg(feature = "vorbis-encode")]
#[cfg(feature = "aac-encode")]
"m4a" => Some(EncodeFormat::Aac),
#[cfg(all(feature = "alac-encode", not(feature = "aac-encode")))]
"m4a" => Some(EncodeFormat::Alac),
#[cfg(feature = "alac-encode")]
"alac" => Some(EncodeFormat::Alac),
#[cfg(feature = "mp3-encode")]
"mp3" => Some(EncodeFormat::Mp3),
#[cfg(feature = "ac3-encode")]
"ac3" => Some(EncodeFormat::Ac3),
#[cfg(feature = "eac3-encode")]
"eac3" | "ec3" => Some(EncodeFormat::Eac3),
#[cfg(all(feature = "vorbis-encode", not(target_arch = "wasm32")))]
"ogg" => Some(EncodeFormat::Ogg),
_ => None,
}
@@ -138,15 +166,24 @@ fn wav_mask(layout: &ChannelLayout, channels: usize) -> Result<u32> {
/// The error a stream encoder returns for every call after one of its writes has failed: the
/// sink may already hold a prefix of the failed block, so the encoder's counters can no longer
/// describe the bytes on the sink, and later writes or `finish` must not claim success.
#[cfg(any(
feature = "pcm-encode",
feature = "flac-encode",
feature = "aac-encode",
feature = "alac-encode",
feature = "mp3-encode",
feature = "ac3-encode",
feature = "eac3-encode"
))]
fn failed_write_error() -> AudioError {
AudioError::Encode("the stream encoder already failed on an earlier write; its output is incomplete".into())
}
/// Writes WAV/BWF (RF64 above 4 GiB), AIFF / AIFF-C `fl32` or FLAC block by block, producing
/// the same bytes [`encode`] would for the whole buffer: a file of any length never
/// has to fit in memory. The file starts at the sink's position, and nothing may follow that
/// position (a new file, or one truncated there): the encoder cannot truncate a `Write + Seek`,
/// so the bytes of a longer file already there would stay after the new one.
/// Writes a file of any [`EncodeFormat`] block by block, producing the same bytes [`encode`]
/// would for the whole buffer: a file of any length never has to fit in memory. The file starts
/// at the sink's position, and nothing may follow that position (a new file, or one truncated
/// there): the encoder cannot truncate a `Write + Seek`, so the bytes of a longer file already
/// there would stay after the new one.
///
/// ```
/// # #[cfg(feature = "flac-encode")] {
@@ -163,44 +200,67 @@ fn failed_write_error() -> AudioError {
/// assert_eq!(&flac[..4], b"fLaC");
/// # }
/// ```
#[cfg(any(feature = "pcm-encode", feature = "flac-encode"))]
#[cfg(any(
feature = "pcm-encode",
feature = "flac-encode",
feature = "aac-encode",
feature = "alac-encode",
feature = "mp3-encode",
feature = "ac3-encode",
feature = "eac3-encode"
))]
pub struct FileEncoder<W: Write + Seek> {
writer: Writer<W>,
format: EncodeFormat,
channels: usize,
}
#[cfg(any(feature = "pcm-encode", feature = "flac-encode"))]
#[cfg(any(
feature = "pcm-encode",
feature = "flac-encode",
feature = "aac-encode",
feature = "alac-encode",
feature = "mp3-encode",
feature = "ac3-encode",
feature = "eac3-encode"
))]
impl<W: Write + Seek> std::fmt::Debug for FileEncoder<W> {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
let format = match &self.writer {
#[cfg(feature = "pcm-encode")]
Writer::Wav(_) => EncodeFormat::Wav,
#[cfg(feature = "pcm-encode")]
Writer::Aiff(_) => EncodeFormat::Aiff,
#[cfg(feature = "flac-encode")]
Writer::Flac(_) => EncodeFormat::Flac,
};
f.debug_struct("FileEncoder").field("format", &format).finish_non_exhaustive()
f.debug_struct("FileEncoder").field("format", &self.format).finish_non_exhaustive()
}
}
#[cfg(any(feature = "pcm-encode", feature = "flac-encode"))]
enum Writer<W> {
// The writers differ in size with the features built; the coded one is boxed for its encoder.
#[allow(clippy::large_enum_variant)]
enum Writer<W: Write + Seek> {
#[cfg(feature = "pcm-encode")]
Wav(wav::Writer<W>),
#[cfg(feature = "pcm-encode")]
Aiff(aiff::Writer<W>),
#[cfg(feature = "flac-encode")]
Flac(flac::Writer<W>),
#[cfg(any(feature = "aac-encode", feature = "alac-encode", feature = "mp3-encode", feature = "ac3-encode", feature = "eac3-encode"))]
Coded(Box<coded::Writer<W>>),
}
#[cfg(any(feature = "pcm-encode", feature = "flac-encode"))]
#[cfg(any(
feature = "pcm-encode",
feature = "flac-encode",
feature = "aac-encode",
feature = "alac-encode",
feature = "mp3-encode",
feature = "ac3-encode",
feature = "eac3-encode"
))]
impl<W: Write + Seek> FileEncoder<W> {
/// Starts a file of `channels` channels at `sample_rate` at the current position of `out`.
/// `opts.layout`, when set, must have `channels` channels.
pub fn new(out: W, opts: &EncodeOptions, sample_rate: u32, channels: u16) -> Result<Self> {
check_built(opts.format)?;
let (depth, dither, channels) = (opts.bit_depth, opts.dither, usize::from(channels));
let channels = usize::from(channels);
#[cfg_attr(not(any(feature = "pcm-encode", feature = "flac-encode")), allow(unused_variables))]
let (depth, dither) = (opts.bit_depth, opts.dither);
#[cfg_attr(not(any(feature = "pcm-encode", feature = "flac-encode")), allow(unused_variables))]
let mask = opts.layout.map(|l| wav_mask(&l, channels)).transpose()?;
let writer = match opts.format {
#[cfg(feature = "pcm-encode")]
@@ -216,24 +276,45 @@ impl<W: Write + Seek> FileEncoder<W> {
EncodeFormat::Aiff => Writer::Aiff(aiff::Writer::new(out, channels, sample_rate, depth, dither)?),
#[cfg(feature = "flac-encode")]
EncodeFormat::Flac => Writer::Flac(flac::Writer::new(out, channels, sample_rate, depth, dither, mask)?),
#[cfg(any(feature = "aac-encode", feature = "alac-encode", feature = "mp3-encode", feature = "ac3-encode", feature = "eac3-encode"))]
EncodeFormat::Aac | EncodeFormat::Alac | EncodeFormat::Mp3 | EncodeFormat::Ac3 | EncodeFormat::Eac3 => {
Writer::Coded(Box::new(coded::Writer::new(out, opts, sample_rate, channels)?))
}
#[allow(unreachable_patterns)]
f => return Err(AudioError::Unsupported(format!("writing {f:?}"))),
};
Ok(FileEncoder { writer, channels })
Ok(FileEncoder { writer, format: opts.format, channels })
}
/// The constant bit rate the file is written at, in bits per second for all channels
/// together: the rate asked for or the format's default, moved to one the stream
/// can carry as [`RateControl::Bitrate`](crate::RateControl::Bitrate) describes. `None` for the lossless
/// formats and for AAC at a constant quality.
pub fn bitrate(&self) -> Option<u32> {
match &self.writer {
#[cfg(any(feature = "aac-encode", feature = "alac-encode", feature = "mp3-encode", feature = "ac3-encode", feature = "eac3-encode"))]
Writer::Coded(w) => w.bitrate(),
#[allow(unreachable_patterns)]
_ => None,
}
}
/// Fails, without writing anything, when `frames` more frames would not fit the format (an
/// AIFF holds 4 GiB, a FLAC 2^36 - 1 frames).
/// AIFF holds 4 GiB, a FLAC 2^36 - 1 frames). The coded formats have no limit a file reaches.
pub fn check_room(&self, frames: u64) -> Result<()> {
match &self.writer {
#[cfg(feature = "pcm-encode")]
Writer::Wav(w) => w.check_room(frames),
Writer::Wav(w) => w.check_room(frames).map(drop),
#[cfg(feature = "pcm-encode")]
Writer::Aiff(w) => w.check_room(frames),
Writer::Aiff(w) => w.check_room(frames).map(drop),
#[cfg(feature = "flac-encode")]
Writer::Flac(w) => w.check_room(frames),
Writer::Flac(w) => w.check_room(frames).map(drop),
#[cfg(any(feature = "aac-encode", feature = "alac-encode", feature = "mp3-encode", feature = "ac3-encode", feature = "eac3-encode"))]
Writer::Coded(_) => {
let _ = frames;
Ok(())
}
}
.map(drop)
}
/// Appends the first `frames` frames of `block`, one slice per channel (`&[Vec<f32>]`,
@@ -256,10 +337,13 @@ impl<W: Write + Seek> FileEncoder<W> {
Writer::Aiff(w) => w.write(block, frames),
#[cfg(feature = "flac-encode")]
Writer::Flac(w) => w.write(block, frames),
#[cfg(any(feature = "aac-encode", feature = "alac-encode", feature = "mp3-encode", feature = "ac3-encode", feature = "eac3-encode"))]
Writer::Coded(w) => w.write(block, frames),
}
}
/// Completes the headers and hands back `out`, positioned at the end of the file.
/// Encodes what is still buffered, completes the headers and hands back `out`, positioned at
/// the end of the file.
pub fn finish(self) -> Result<W> {
match self.writer {
#[cfg(feature = "pcm-encode")]
@@ -268,10 +352,50 @@ impl<W: Write + Seek> FileEncoder<W> {
Writer::Aiff(w) => w.finish(),
#[cfg(feature = "flac-encode")]
Writer::Flac(w) => w.finish(),
#[cfg(any(feature = "aac-encode", feature = "alac-encode", feature = "mp3-encode", feature = "ac3-encode", feature = "eac3-encode"))]
Writer::Coded(w) => w.finish(),
}
}
}
#[cfg(any(
feature = "pcm-encode",
feature = "flac-encode",
feature = "aac-encode",
feature = "alac-encode",
feature = "mp3-encode",
feature = "ac3-encode",
feature = "eac3-encode"
))]
impl EncodeOptions {
/// Whether a file of `channels` channels at `sample_rate` can be written with these options:
/// `Ok`, or the error [`FileEncoder::new`] and [`encode`] would return, with nothing written.
/// For choosing a format before a file is created; [`EncodeFormat::sample_rates`],
/// [`EncodeFormat::max_channels`] and [`EncodeFormat::supports_layout`] say what a format takes.
///
/// ```
/// # #[cfg(feature = "mp3-encode")] {
/// use craft_audio::{EncodeFormat, EncodeOptions};
///
/// let mp3 = EncodeOptions::new(EncodeFormat::Mp3).with_bitrate(200_000);
/// assert!(mp3.check(48_000, 2).is_ok());
/// assert!(mp3.check(96_000, 2).is_err()); // not an MP3 sample rate
/// assert_eq!(mp3.bitrate(48_000, 2).unwrap(), Some(192_000)); // the table rate below 200 kbit/s
/// # }
/// ```
pub fn check(&self, sample_rate: u32, channels: u16) -> Result<()> {
self.bitrate(sample_rate, channels).map(drop)
}
/// The constant bit rate such a file would be written at ([`FileEncoder::bitrate`]), or the
/// error [`EncodeOptions::check`] returns.
pub fn bitrate(&self, sample_rate: u32, channels: u16) -> Result<Option<u32>> {
// The encoder a file would get, on a sink that is thrown away: what it accepts and the
// rate it settles on are then the writer's by construction.
Ok(FileEncoder::new(std::io::Cursor::new(Vec::new()), self, sample_rate, channels)?.bitrate())
}
}
/// The header of a 32-bit float WAV holding `frames` frames (little-endian samples follow it). Its
/// length doesn't depend on `frames`, so a recorder can rewrite it in place as the file grows; it
/// switches to RF64 above 4 GiB.
@@ -309,6 +433,7 @@ mod tests {
let enc = FileEncoder::new(std::io::Cursor::new(Vec::new()), &opts, 48_000, 1);
assert!(matches!(enc, Err(AudioError::Unsupported(_))));
assert_eq!(encode_format_for(name), None);
assert!(!format.is_built() && EncodeFormat::ALL.iter().any(|f| f.is_built()));
// Also with a layout it could not use.
let opts = opts.with_layout(ChannelLayout::STEREO);
assert!(matches!(encode(&buf, &opts), Err(AudioError::Unsupported(_))));
+3
View File
@@ -1,6 +1,9 @@
//! PCM helpers shared by the WAV, AIFF and FLAC writers: quantization (with optional TPDF
//! dither), interleaving and layout checks.
// The coded formats use the layout check, and of those only ALAC the quantizer.
#![cfg_attr(not(any(feature = "pcm-encode", feature = "flac-encode")), allow(dead_code))]
use crate::{AudioBuffer, AudioError, Result};
#[cfg(feature = "pcm-encode")]
use {crate::BitDepth, std::io::Write};
+47 -3
View File
@@ -9,8 +9,10 @@ pub const OGG_BITRATES: (u32, u32) = (64, 500);
/// The block size the encoder processes at a time: small enough that memory stays bounded
/// regardless of file length.
#[cfg(not(target_arch = "wasm32"))]
const BLOCK: usize = 4096;
#[cfg(not(target_arch = "wasm32"))]
fn encode_error(e: vorbis_rs::VorbisError) -> AudioError {
AudioError::Encode(e.to_string())
}
@@ -22,7 +24,13 @@ fn encode_error(e: vorbis_rs::VorbisError) -> AudioError {
pub fn encode(buf: &AudioBuffer, kbps: u32) -> Result<Vec<u8>> {
use std::num::{NonZeroU8, NonZeroU32};
let channels = buf.channels.len().clamp(1, 2);
let channels = buf.channels.len();
if !(1..=2).contains(&channels) {
return Err(AudioError::Unsupported("Ogg Vorbis export requires mono or stereo audio".into()));
}
if buf.channels.iter().any(|c| c.len() != buf.frames() || c.iter().any(|s| !s.is_finite())) {
return Err(AudioError::Encode("Vorbis samples must be finite and channels equally long".into()));
}
let (Some(rate), Some(count)) = (NonZeroU32::new(buf.sample_rate), NonZeroU8::new(channels as u8)) else {
return Err(AudioError::Encode("there is no audio to encode".into()));
};
@@ -44,7 +52,7 @@ pub fn encode(buf: &AudioBuffer, kbps: u32) -> Result<Vec<u8>> {
encoder.finish().map_err(encode_error)
};
// The library is C: whatever it does wrong ends here as an error, never as a crash of the app.
// Convert Rust unwinds to an error. This does not catch native crashes or aborts.
let attempt = |strategy| {
std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| encode(strategy)))
.unwrap_or_else(|_| Err(AudioError::Encode("the Vorbis encoder failed".into())))
@@ -58,5 +66,41 @@ pub fn encode(buf: &AudioBuffer, kbps: u32) -> Result<Vec<u8>> {
#[cfg(target_arch = "wasm32")]
pub fn encode(_buf: &AudioBuffer, _kbps: u32) -> Result<Vec<u8>> {
Err("Ogg Vorbis files are exported by the desktop app".into())
Err(AudioError::Unsupported("Ogg Vorbis files are exported by the desktop app".into()))
}
#[cfg(all(test, not(target_arch = "wasm32")))]
mod tests {
use super::*;
#[test]
fn rejects_unsupported_or_malformed_channels_without_dropping_audio() {
for channels in [0, 3, 6] {
assert!(matches!(encode(&AudioBuffer::new(48_000, channels, 16), 192), Err(AudioError::Unsupported(_))));
}
let ragged = AudioBuffer { sample_rate: 48_000, channels: vec![vec![0.0; 16], vec![0.0; 15]] };
assert!(encode(&ragged, 192).is_err());
assert!(encode(&AudioBuffer::new(0, 1, 16), 192).is_err());
let invalid = AudioBuffer { sample_rate: 48_000, channels: vec![vec![f32::NAN]] };
assert!(encode(&invalid, 192).is_err());
}
#[test]
fn generic_and_direct_encoders_write_mono_and_stereo_ogg() {
for channels in [1, 2] {
let audio = AudioBuffer::new(48_000, channels, 512);
let opts = crate::EncodeOptions::new(crate::EncodeFormat::Ogg);
let direct = encode(&audio, 192).unwrap();
let generic = crate::encode(&audio, &opts).unwrap();
assert!(direct.starts_with(b"OggS"));
assert_eq!(direct, generic);
#[cfg(feature = "decode")]
{
let (info, decoded) = crate::decode(&generic, Some("ogg")).unwrap();
assert_eq!(info.channels, channels);
assert_eq!(decoded.num_channels(), channels);
assert_eq!(decoded.frames(), audio.frames());
}
}
}
}
+13 -3
View File
@@ -62,11 +62,21 @@ fn every_decode_extension_probes_and_decodes() {
fn every_encode_format_has_an_extension_it_is_written_and_read_under() {
for &format in EncodeFormat::ALL {
let ext = format.extension();
assert_eq!(craft_audio::encode_format_for(ext), Some(format), "{ext}");
assert!(craft_audio::ENCODE_EXTENSIONS.contains(&ext), "{ext}");
// The extension names the format, or for `m4a`, which two formats share, AAC before ALAC.
// A format whose feature is off has no name.
match craft_audio::encode_format_for(ext) {
Some(named) => {
let shares_m4a = |f| matches!(f, EncodeFormat::Aac | EncodeFormat::Alac);
assert!(named == format || (shares_m4a(named) && shares_m4a(format)), "{ext}");
assert!(named.is_built(), "{ext}");
assert!(craft_audio::ENCODE_EXTENSIONS.contains(&ext), "{ext}");
}
None => assert!(!matches!(format, EncodeFormat::Wav | EncodeFormat::Aiff | EncodeFormat::Flac), "{ext}"),
}
assert!(DECODE_EXTENSIONS.contains(&ext), "{ext}: what is written reads back");
assert!(format.mime_type().starts_with("audio/"), "{format:?}");
}
assert_eq!(EncodeFormat::ALL.iter().map(|f| f.extension()).collect::<Vec<_>>(), ["wav", "aif", "flac", "ogg"]);
let extensions: Vec<_> = EncodeFormat::ALL.iter().map(|f| f.extension()).collect();
assert_eq!(extensions, ["wav", "aif", "flac", "m4a", "m4a", "mp3", "ac3", "eac3", "ogg"]);
assert_eq!(EncodeFormat::Aiff.mime_type(), "audio/aiff");
}
+9 -1
View File
@@ -14,7 +14,15 @@ fn only_formats_the_encoder_writes_are_named() {
for name in craft_audio::ENCODE_EXTENSIONS {
assert!(encode_format_for(name).is_some(), "{name}");
}
for other in ["mp3", "m4a", "xyz", ""] {
for other in ["opus", "aac", "mp4", "xyz", ""] {
assert_eq!(encode_format_for(other), None, "{other}");
}
}
#[test]
fn ogg_names_follow_the_native_feature() {
let built = cfg!(all(feature = "vorbis-encode", not(target_arch = "wasm32")));
assert_eq!(EncodeFormat::Ogg.is_built(), built);
assert_eq!(encode_format_for("ogg"), built.then_some(EncodeFormat::Ogg));
assert_eq!(craft_audio::ENCODE_EXTENSIONS.contains(&"ogg"), built);
}
+571
View File
@@ -0,0 +1,571 @@
//! The coded formats of `encode` and `FileEncoder` (AAC and ALAC in M4A; MP3, AC-3 and E-AC-3
//! streams), read back with this crate's decoder and, where ffmpeg is installed, with ffmpeg.
use std::io::{Cursor, Seek, SeekFrom, Write};
use std::process::Command;
use craft_audio::{
AudioBuffer, AudioError, BitDepth, ChannelLayout, CodecId, Container, ENCODE_EXTENSIONS, EncodeFormat, EncodeOptions, FileEncoder, RateControl,
decode, encode, encode_format_for,
};
const CODED: [EncodeFormat; 5] = [EncodeFormat::Aac, EncodeFormat::Alac, EncodeFormat::Mp3, EncodeFormat::Ac3, EncodeFormat::Eac3];
/// `channels` channels of `frames` frames, each channel a tone of its own frequency, on the
/// 16-bit grid (so a lossless 16-bit format returns it exactly).
fn tones(sample_rate: u32, channels: usize, frames: usize) -> AudioBuffer {
let channel = |c: usize| {
let step = (60.0 + 17.0 * c as f32) * std::f32::consts::TAU / sample_rate as f32;
(0..frames).map(|i| ((i as f32 * step).sin() * 0.4 * 32768.0).round() / 32768.0).collect()
};
AudioBuffer { sample_rate, channels: (0..channels).map(channel).collect() }
}
/// Signal-to-noise ratio in dB of `got` against `want`, over the frames both have.
fn snr(want: &[f32], got: &[f32]) -> f64 {
let (signal, noise) =
want.iter().zip(got).fold((0f64, 0f64), |(s, n), (&w, &g)| (s + f64::from(w).powi(2), n + (f64::from(w) - f64::from(g)).powi(2)));
10.0 * (signal / noise.max(1e-30)).log10()
}
fn is_unsupported<T: std::fmt::Debug>(r: Result<T, AudioError>) -> bool {
matches!(r, Err(AudioError::Unsupported(_)))
}
/// An AAC file decodes to the frames that were written, in place: the edit list skips the
/// encoder's priming and cuts the padding of the last packet.
#[test]
fn aac_decodes_to_the_frames_written() {
for frames in [1, 1000, 1024, 1025, 5000, 48_017] {
let buf = tones(48_000, 2, frames);
let file = encode(&buf, &EncodeOptions::new(EncodeFormat::Aac)).unwrap();
let (info, out) = decode(&file, Some("m4a")).unwrap();
assert_eq!((info.container, info.codec, info.sample_rate, info.damaged), (Container::Mp4, CodecId::Aac, 48_000, 0));
assert_eq!((info.frames, out.frames(), info.layout), (frames as u64, frames, ChannelLayout::STEREO), "{frames} frames");
if frames >= 5000 {
for (want, got) in buf.channels.iter().zip(&out.channels) {
assert!(snr(want, got) > 30.0, "{frames} frames: {} dB", snr(want, got));
}
}
}
}
/// The M4A track's durations add up to the priming and the audio, and its one edit skips the
/// priming and lasts as long as the audio, in a movie timescale that is the sample rate.
#[test]
fn aac_timing_is_in_the_sample_table_and_the_edit_list() {
use craft_audio::craft_media::isobmff;
let file = encode(&tones(44_100, 1, 3000), &EncodeOptions::new(EncodeFormat::Aac)).unwrap();
let mp4 = isobmff::open(file.as_slice()).unwrap();
let track = &mp4.tracks[0];
assert_eq!((mp4.timescale, track.timescale), (44_100, 44_100));
assert_eq!(track.samples.iter().map(|s| u64::from(s.duration)).sum::<u64>(), 1024 + 3000);
assert_eq!(track.edits.len(), 1);
assert_eq!((track.edits[0].media_time, track.edits[0].segment_duration), (1024, 3000));
// Every packet is in a `roll` group of distance -1, which Apple's decoders need to apply the edit.
let groups = &track.sample_groups;
assert_eq!((groups.len(), groups[0].grouping_type), (1, isobmff::FourCc(*b"roll")));
assert_eq!((groups[0].runs.as_slice(), &groups[0].descriptions), ([(track.samples.len() as u32, 1)].as_slice(), &vec![vec![0xFF, 0xFF]]));
}
/// The sample entry is completed when the file is: AAC's average bit rate, and the largest packet
/// and average bit rate in ALAC's cookie.
#[test]
fn the_sample_entry_describes_the_finished_stream() {
use craft_audio::craft_media::isobmff::{self, CodecConfig};
let buf = tones(48_000, 2, 48_000);
let file = encode(&buf, &EncodeOptions::new(EncodeFormat::Aac).with_bitrate(96_000)).unwrap();
let mp4 = isobmff::open(file.as_slice()).unwrap();
let CodecConfig::Aac(aac) = &mp4.tracks[0].entries[0].codec else { panic!("not AAC") };
assert!((90_000..100_000).contains(&aac.avg_bitrate), "{} bit/s", aac.avg_bitrate);
let file = encode(&buf, &EncodeOptions::new(EncodeFormat::Alac).with_bit_depth(BitDepth::Int16)).unwrap();
let mp4 = isobmff::open(file.as_slice()).unwrap();
let CodecConfig::Alac { cookie } = &mp4.tracks[0].entries[0].codec else { panic!("not ALAC") };
let config = craft_audio::alac::SpecificConfig::parse(cookie).unwrap();
let largest = mp4.tracks[0].samples.iter().map(|s| s.size).max().unwrap();
assert_eq!((config.max_frame_bytes, config.bit_depth, config.frame_length), (largest, 16, 4096));
assert!(config.avg_bit_rate > 0);
}
/// Dither reaches ALAC's quantizer: a level below one 16-bit step is silence without it.
#[test]
fn alac_dithers_when_asked() {
let buf = AudioBuffer { sample_rate: 48_000, channels: vec![vec![0.3 / 32768.0; 4096]] };
let opts = EncodeOptions::new(EncodeFormat::Alac).with_bit_depth(BitDepth::Int16);
let (_, plain) = decode(&encode(&buf, &opts).unwrap(), Some("m4a")).unwrap();
let (_, dithered) = decode(&encode(&buf, &opts.with_dither(true)).unwrap(), Some("m4a")).unwrap();
assert!(plain.channels[0].iter().all(|&s| s == 0.0));
assert!(dithered.channels[0].iter().any(|&s| s != 0.0));
}
/// ALAC returns the quantized samples exactly, for every channel count, with each channel where
/// its speaker is.
#[test]
fn alac_is_lossless_in_every_layout() {
for channels in 1..=8u8 {
let layout = ChannelLayout::from_mask(craft_audio::alac::channel_mask(channels));
let buf = tones(44_100, usize::from(channels), 10_000);
let opts = EncodeOptions::new(EncodeFormat::Alac).with_bit_depth(BitDepth::Int16).with_layout(layout);
let file = encode(&buf, &opts).unwrap();
let (info, out) = decode(&file, Some("m4a")).unwrap();
assert_eq!((info.container, info.codec, info.frames, info.layout), (Container::Mp4, CodecId::Alac, 10_000, layout), "{channels} channels");
assert_eq!(out, buf, "{channels} channels");
}
// 24 bits, and a length that is no whole number of packets.
let buf = tones(96_000, 2, 4096 * 2 + 1);
let (_, out) = decode(&encode(&buf, &EncodeOptions::new(EncodeFormat::Alac)).unwrap(), Some("m4a")).unwrap();
assert_eq!(out, buf);
}
/// Channels go to the encoder by speaker. ALAC's 6.1 has the back centre last and AAC's has it
/// before the surround pair; 5.1 with side surrounds is the format's one 5.1.
#[test]
fn channels_reach_their_speakers() {
// WAV 6.1 with a back pair (L R C LFE Lb Rb Cb), the usual 7-channel layout, into ALAC: the same.
let buf = tones(48_000, 7, 8000);
let (info, out) = decode(&encode(&buf, &EncodeOptions::new(EncodeFormat::Alac).with_bit_depth(BitDepth::Int16)).unwrap(), Some("m4a")).unwrap();
assert_eq!(info.layout, ChannelLayout::from_mask(0x13F));
assert_eq!(out, buf);
// 5.1 with side surrounds decodes from ALAC as 5.1 with back surrounds, channel for channel.
let buf = tones(48_000, 6, 8000);
let opts = EncodeOptions::new(EncodeFormat::Alac).with_bit_depth(BitDepth::Int16).with_layout(ChannelLayout::SURROUND_5_1_SIDE);
assert_eq!(decode(&encode(&buf, &opts).unwrap(), Some("m4a")).unwrap().1, buf);
// AAC: the decoded channel each input channel comes back as. 5.1 decodes in WAV order; the
// 6.1 and 7.1 streams have no speaker assignment and decode in AAC order (C L R Ls Rs Cs LFE
// and C Lc Rc L R Ls Rs LFE).
let wide = ChannelLayout::from_mask(0xFF);
let cases: [(usize, Option<ChannelLayout>, &[usize]); 3] =
[(6, None, &[0, 1, 2, 3, 4, 5]), (7, None, &[2, 0, 1, 4, 5, 6, 3]), (8, Some(wide), &[2, 6, 7, 0, 1, 4, 5, 3])];
for (channels, layout, decoded_from) in cases {
let buf = tones(48_000, channels, 48_000);
let mut opts = EncodeOptions::new(EncodeFormat::Aac);
opts.layout = layout;
let (info, out) = decode(&encode(&buf, &opts).unwrap(), Some("m4a")).unwrap();
assert_eq!((usize::from(info.channels), out.frames()), (channels, 48_000));
for (decoded, &input) in decoded_from.iter().enumerate() {
let db = snr(&buf.channels[input], &out.channels[decoded]);
assert!(db > 20.0, "{channels} channels: decoded {decoded} is not input {input} ({db} dB)");
}
}
}
/// MP3, AC-3 and E-AC-3 are raw streams: the audio comes back behind the codec's delay.
#[test]
fn raw_streams_decode_behind_the_codec_delay() {
let buf = tones(48_000, 2, 48_000);
for (format, codec, container, delay, floor) in [
(EncodeFormat::Mp3, CodecId::Mp3, Container::MpegAudio, craft_audio::mp3::DELAY as usize, 25.0),
(EncodeFormat::Ac3, CodecId::Ac3, Container::Ac3, 256, 15.0),
(EncodeFormat::Eac3, CodecId::Eac3, Container::Ac3, 256, 15.0),
] {
let file = encode(&buf, &EncodeOptions::new(format)).unwrap();
let (info, out) = decode(&file, Some(format.extension())).unwrap();
assert_eq!((info.codec, info.container, info.sample_rate, info.layout, info.damaged), (codec, container, 48_000, ChannelLayout::STEREO, 0));
assert_eq!((format.codec(), format.container()), (codec, container));
assert!(out.frames() >= 48_000 + delay, "{format:?}: {} frames", out.frames());
for (want, got) in buf.channels.iter().zip(&out.channels) {
let db = snr(want, &got[delay..]);
assert!(db > floor, "{format:?}: {db} dB");
}
}
// 5.1 with back surrounds is AC-3's 3/2 mode with an LFE, channel for channel.
let buf = tones(48_000, 6, 48_000);
let (info, out) = decode(&encode(&buf, &EncodeOptions::new(EncodeFormat::Ac3)).unwrap(), Some("ac3")).unwrap();
assert_eq!(info.layout, ChannelLayout::SURROUND_5_1_SIDE);
for (c, (want, got)) in buf.channels.iter().zip(&out.channels).enumerate() {
// The encoder low-pass filters the LFE, which shifts its phase: it is compared by level.
if c == 3 {
let rms = |x: &[f32]| (x.iter().map(|&s| f64::from(s).powi(2)).sum::<f64>() / x.len() as f64).sqrt();
let level = rms(&got[4800..]) / rms(want);
assert!((0.5..1.5).contains(&level), "LFE at {level} of its level");
} else {
assert!(snr(want, &got[256..]) > 12.0, "channel {c}: {} dB", snr(want, &got[256..]));
}
}
// 7.1 is an E-AC-3 programme.
let buf = tones(48_000, 8, 4800);
assert!(is_unsupported(encode(&buf, &EncodeOptions::new(EncodeFormat::Ac3))));
// (Read back by ffmpeg in `ffmpeg_reads_the_files`: this crate's file reader plays the 5.1
// independent substream of a raw 7.1 stream.)
assert!(!encode(&buf, &EncodeOptions::new(EncodeFormat::Eac3)).unwrap().is_empty());
}
/// Blocks of any sizes give the bytes `encode` gives.
#[test]
fn streaming_writes_the_bytes_of_encode() {
let buf = tones(44_100, 2, 30_000);
for format in CODED {
let opts = EncodeOptions::new(format);
let whole = encode(&buf, &opts).unwrap();
let mut enc = FileEncoder::new(Cursor::new(Vec::new()), &opts, 44_100, 2).unwrap();
assert!(format!("{enc:?}").contains(&format!("{format:?}")));
let mut at = 0;
for n in [1, 4095, 4097, 0, 9000, 12_807] {
let block: Vec<&[f32]> = buf.channels.iter().map(|c| &c[at..]).collect();
enc.check_room(n as u64).unwrap();
enc.write(&block, n).unwrap();
at += n;
}
assert_eq!(at, buf.frames());
assert!(enc.finish().unwrap().into_inner() == whole, "{format:?}");
}
}
/// A file starts at the sink's position.
#[test]
fn a_file_starts_at_the_sinks_position() {
let buf = tones(48_000, 1, 6000);
for format in CODED {
let opts = EncodeOptions::new(format);
let mut sink = Cursor::new(b"junk".to_vec());
sink.seek(SeekFrom::End(0)).unwrap();
let mut enc = FileEncoder::new(sink, &opts, 48_000, 1).unwrap();
enc.write(&buf.channels, 6000).unwrap();
let mut sink = enc.finish().unwrap();
let end = sink.stream_position().unwrap();
let bytes = sink.into_inner();
assert_eq!(end, bytes.len() as u64, "{format:?}");
assert!(bytes[4..] == encode(&buf, &opts).unwrap(), "{format:?}");
}
}
/// A file with no audio is still a file of its format.
#[test]
fn no_audio_gives_an_empty_file() {
let buf = AudioBuffer::new(48_000, 2, 0);
for format in CODED {
let file = encode(&buf, &EncodeOptions::new(format)).unwrap();
if format.container() == Container::Mp4 {
let mp4 = craft_audio::craft_media::isobmff::open(file.as_slice()).unwrap();
assert_eq!((mp4.tracks.len(), mp4.tracks[0].samples.len(), mp4.tracks[0].edits.len()), (1, 0, 0), "{format:?}");
} else {
assert!(file.is_empty(), "{format:?}");
}
}
}
/// The bit rate asked for is the one written, moved to the nearest the format has.
#[test]
fn the_bit_rate_is_followed() {
let buf = tones(48_000, 2, 48_000);
let size = |opts: &EncodeOptions| encode(&buf, opts).unwrap().len();
// MP3 at 48 kHz: 24 bytes per frame and kbit/s, 43 frames for a second and the delay.
assert_eq!(size(&EncodeOptions::new(EncodeFormat::Mp3)), 43 * 192 * 3);
assert_eq!(size(&EncodeOptions::new(EncodeFormat::Mp3).with_bitrate(130_000)), 43 * 128 * 3);
assert_eq!(size(&EncodeOptions::new(EncodeFormat::Mp3).with_bitrate(1)), 43 * 32 * 3);
assert_eq!(size(&EncodeOptions::new(EncodeFormat::Mp3).with_bitrate(u32::MAX)), 43 * 320 * 3);
// AC-3: 32 packets of 1536 frames, 4 bytes per packet and kbit/s.
assert_eq!(size(&EncodeOptions::new(EncodeFormat::Ac3)), 32 * 192 * 4);
assert_eq!(size(&EncodeOptions::new(EncodeFormat::Ac3).with_bitrate(100_000)), 32 * 96 * 4);
assert_eq!(size(&EncodeOptions::new(EncodeFormat::Eac3).with_bitrate(100_000)), 32 * 100 * 4);
// AAC: a second of audio at about the rate asked for, around the 128 kbit/s default.
let (low, default, high) = (
size(&EncodeOptions::new(EncodeFormat::Aac).with_bitrate(64_000)),
size(&EncodeOptions::new(EncodeFormat::Aac)),
size(&EncodeOptions::new(EncodeFormat::Aac).with_bitrate(256_000)),
);
assert!((7000..10_000).contains(&low) && (15_000..18_500).contains(&default) && (30_000..35_000).contains(&high), "{low} {default} {high}");
// A rate no stream can carry is moved into range, not refused.
encode(&buf, &EncodeOptions::new(EncodeFormat::Aac).with_bitrate(u32::MAX)).unwrap();
// The lowest rate still codes the audio: the encoder accepts rates that leave only silence
// (128 for 128 kbit/s is one), and the writer does not go that low.
for (sample_rate, channels) in [(8000, 1), (16_000, 2), (44_100, 2), (48_000, 6), (96_000, 2)] {
let buf = tones(sample_rate, channels, sample_rate as usize);
let (_, out) = decode(&encode(&buf, &EncodeOptions::new(EncodeFormat::Aac).with_bitrate(128)).unwrap(), Some("m4a")).unwrap();
let rms = |x: &[f32]| (x.iter().map(|&s| f64::from(s).powi(2)).sum::<f64>() / x.len() as f64).sqrt();
let level = rms(&out.channels[0]) / rms(&buf.channels[0]);
assert!(level > 0.5, "{sample_rate} Hz, {channels} channels: {level} of the level");
}
// Quality is AAC's; ALAC has no rate to control.
let (small, large) =
(size(&EncodeOptions::new(EncodeFormat::Aac).with_quality(0.0)), size(&EncodeOptions::new(EncodeFormat::Aac).with_quality(1.0)));
assert!(small < large, "{small} {large}");
assert!(matches!(encode(&buf, &EncodeOptions::new(EncodeFormat::Aac).with_quality(f32::NAN)), Err(AudioError::Encode(_))));
for format in [EncodeFormat::Mp3, EncodeFormat::Ac3, EncodeFormat::Eac3] {
assert!(is_unsupported(encode(&buf, &EncodeOptions::new(format).with_quality(0.5))), "{format:?}");
}
let alac = EncodeOptions::new(EncodeFormat::Alac);
assert_eq!(size(&alac), size(&alac.clone().with_bitrate(64_000)));
assert_eq!(alac.rate_control, None);
assert_eq!(alac.with_quality(0.5).rate_control, Some(RateControl::Quality(0.5)));
}
/// What a format cannot hold is refused before anything is written.
#[test]
fn what_a_format_cannot_hold_is_refused() {
let refused = |format, sample_rate, channels: u16, layout: Option<ChannelLayout>| {
let mut opts = EncodeOptions::new(format);
opts.layout = layout;
let mut sink = Cursor::new(Vec::new());
let r = FileEncoder::new(&mut sink, &opts, sample_rate, channels).map(drop);
assert!(r.is_ok() || sink.into_inner().is_empty(), "{format:?}: bytes written for a refused file");
assert_eq!(r.is_err(), encode(&AudioBuffer::new(sample_rate, channels, 100), &opts).is_err());
r
};
// Quad has no centre, which AAC's and ALAC's four channels have.
assert!(is_unsupported(refused(EncodeFormat::Aac, 48_000, 4, None)));
assert!(is_unsupported(refused(EncodeFormat::Alac, 48_000, 4, None)));
refused(EncodeFormat::Aac, 48_000, 4, Some(ChannelLayout::from_mask(0x107))).unwrap();
// WAV 7.1 (backs and sides) is not the 7.1 of AAC and ALAC (a front pair left and right of centre).
assert!(is_unsupported(refused(EncodeFormat::Aac, 48_000, 8, None)));
assert!(is_unsupported(refused(EncodeFormat::Alac, 48_000, 8, Some(ChannelLayout::SURROUND_7_1))));
assert!(is_unsupported(refused(EncodeFormat::Aac, 48_000, 2, Some(ChannelLayout::unordered(2)))));
for format in CODED {
assert!(is_unsupported(refused(format, 48_000, 9, None)), "{format:?}");
assert!(matches!(refused(format, 48_000, 2, Some(ChannelLayout::MONO)), Err(AudioError::Encode(_))), "{format:?}");
assert!(matches!(refused(format, 0, 2, None), Err(AudioError::Encode(_))), "{format:?}");
assert!(matches!(refused(format, 48_000, 0, None), Err(AudioError::Encode(_))), "{format:?}");
}
assert!(is_unsupported(refused(EncodeFormat::Mp3, 48_000, 3, None)));
assert!(is_unsupported(refused(EncodeFormat::Ac3, 48_000, 7, None)));
// Sample rates the codec has not.
for format in [EncodeFormat::Aac, EncodeFormat::Mp3, EncodeFormat::Ac3, EncodeFormat::Eac3] {
assert!(matches!(refused(format, 44_000, 2, None), Err(AudioError::Encode(_))), "{format:?}");
}
refused(EncodeFormat::Alac, 44_000, 2, None).unwrap();
let float = EncodeOptions::new(EncodeFormat::Alac).with_bit_depth(BitDepth::Float32);
assert!(is_unsupported(encode(&AudioBuffer::new(48_000, 2, 100), &float)));
}
/// Samples no encoder should see: NaN is silence, and values past full scale do not fail a
/// write (AC-3, whose encoder refuses them, gets them clamped).
#[test]
fn non_finite_and_loud_samples_are_written() {
let mut buf = tones(48_000, 2, 6000);
buf.channels[0][100] = f32::NAN;
buf.channels[0][200] = f32::INFINITY;
buf.channels[1][300] = -7.5;
for format in CODED {
let file = encode(&buf, &EncodeOptions::new(format)).unwrap();
let (_, out) = decode(&file, Some(format.extension())).unwrap();
assert!(out.channels.iter().flatten().all(|s| s.is_finite()), "{format:?}");
}
}
/// A sink that fails once `room` bytes are written.
struct Full {
inner: Cursor<Vec<u8>>,
room: usize,
}
impl Write for Full {
fn write(&mut self, data: &[u8]) -> std::io::Result<usize> {
if self.inner.get_ref().len() + data.len() > self.room {
return Err(std::io::Error::other("disk full"));
}
self.inner.write(data)
}
fn flush(&mut self) -> std::io::Result<()> {
Ok(())
}
}
impl Seek for Full {
fn seek(&mut self, pos: SeekFrom) -> std::io::Result<u64> {
self.inner.seek(pos)
}
}
/// After a failed write the encoder is unusable: later writes and `finish` fail too.
#[test]
fn a_failed_write_ends_the_encoder() {
let buf = tones(48_000, 2, 48_000);
for format in CODED {
let mut enc = FileEncoder::new(Full { inner: Cursor::new(Vec::new()), room: 2000 }, &EncodeOptions::new(format), 48_000, 2).unwrap();
assert!(matches!(enc.write(&buf.channels, 48_000), Err(AudioError::Io(_))), "{format:?}");
assert!(matches!(enc.write(&buf.channels, 1), Err(AudioError::Encode(_))), "{format:?}");
assert!(matches!(enc.finish(), Err(AudioError::Encode(_))), "{format:?}");
}
}
#[test]
fn the_formats_are_named() {
assert_eq!(encode_format_for("m4a"), Some(EncodeFormat::Aac));
assert_eq!(encode_format_for(".ALAC"), Some(EncodeFormat::Alac));
assert_eq!(encode_format_for("mp3"), Some(EncodeFormat::Mp3));
assert_eq!(encode_format_for("ac3"), Some(EncodeFormat::Ac3));
assert_eq!(encode_format_for("eac3"), Some(EncodeFormat::Eac3));
assert_eq!(encode_format_for("ec3"), Some(EncodeFormat::Eac3));
for &format in EncodeFormat::ALL {
assert!(ENCODE_EXTENSIONS.contains(&format.extension()), "{format:?}");
let named = encode_format_for(format.extension()).unwrap();
assert_eq!((named.extension(), named.mime_type()), (format.extension(), format.mime_type()));
assert_eq!(format.is_lossy(), !matches!(format.codec(), CodecId::Pcm | CodecId::Flac | CodecId::Alac));
}
for name in ENCODE_EXTENSIONS {
assert!(encode_format_for(name).is_some(), "{name}");
}
assert_eq!(ENCODE_EXTENSIONS.len(), 12);
for format in CODED {
assert!(EncodeFormat::ALL.contains(&format) && format.is_built());
}
let features: Vec<_> = EncodeFormat::ALL.iter().map(|f| f.feature()).collect();
assert_eq!(features, ["pcm-encode", "pcm-encode", "flac-encode", "alac-encode", "aac-encode", "mp3-encode", "ac3-encode", "eac3-encode"]);
}
/// ffmpeg's decode of `file` as interleaved `f32`, split into `channels` channels.
fn ffmpeg_decode(ff: &std::path::Path, file: &[u8], name: &str, channels: usize) -> Vec<Vec<f32>> {
let path = crate::testkit::fixtures_dir("file_formats").join(name);
std::fs::write(&path, file).unwrap();
let out = Command::new(ff).args(["-v", "error", "-i"]).arg(&path).args(["-f", "f32le", "-"]).output().unwrap();
assert!(out.status.success() && out.stderr.is_empty(), "{name}: {}", String::from_utf8_lossy(&out.stderr));
let mut planar = vec![Vec::new(); channels];
for (i, s) in out.stdout.as_chunks::<4>().0.iter().enumerate() {
planar[i % channels].push(f32::from_le_bytes(*s));
}
planar
}
/// ffmpeg reads every format: the M4A files without their priming (it applies the edit list) and,
/// from ffmpeg 9, at the length written; ALAC exactly; the raw streams behind their delay.
#[test]
fn ffmpeg_reads_the_files() {
let ff = require_ffmpeg!();
for (channels, layout) in [(1, None), (2, None), (6, None), (8, Some(ChannelLayout::from_mask(0xFF)))] {
let buf = tones(48_000, channels, 20_000);
let mut opts = EncodeOptions::new(EncodeFormat::Aac);
opts.layout = layout;
let out = ffmpeg_decode(&ff, &encode(&buf, &opts).unwrap(), &format!("aac_{channels}.m4a"), channels);
// The priming is skipped by every ffmpeg (the channels below line up). The padding of the
// last packet is cut by ffmpeg 9; ffmpeg 8 plays it, to the end of the 20th packet.
assert!([20_000, 20_480].contains(&out[0].len()), "AAC, {channels} channels: {} frames", out[0].len());
if channels <= 6 {
// ffmpeg also returns 5.1 in WAV order.
for (c, (want, got)) in buf.channels.iter().zip(&out).enumerate() {
assert!(snr(want, got) > 20.0, "AAC, {channels} channels, channel {c}: {} dB", snr(want, got));
}
}
let opts = opts.with_format(EncodeFormat::Alac).with_bit_depth(BitDepth::Int16);
let opts = if channels == 6 { opts.with_layout(ChannelLayout::SURROUND_5_1) } else { opts };
let out = ffmpeg_decode(&ff, &encode(&buf, &opts).unwrap(), &format!("alac_{channels}.m4a"), channels);
assert!(out == buf.channels, "ALAC, {channels} channels");
}
let buf = tones(44_100, 2, 20_000);
for (format, delay, floor) in
[(EncodeFormat::Mp3, craft_audio::mp3::DELAY as usize, 25.0), (EncodeFormat::Ac3, 256, 15.0), (EncodeFormat::Eac3, 256, 15.0)]
{
let name = format!("stream.{}", format.extension());
let out = ffmpeg_decode(&ff, &encode(&buf, &EncodeOptions::new(format)).unwrap(), &name, 2);
for (want, got) in buf.channels.iter().zip(&out) {
assert!(
got.len() >= 20_000 + delay && snr(want, &got[delay..]) > floor,
"{format:?}: {} frames, {} dB",
got.len(),
snr(want, &got[delay..])
);
}
}
// E-AC-3 7.1: the front channels, which the 5.1 downmix leaves as they are.
let buf = tones(48_000, 8, 20_000);
let out = ffmpeg_decode(&ff, &encode(&buf, &EncodeOptions::new(EncodeFormat::Eac3)).unwrap(), "stream_7_1.eac3", 8);
assert!(out[7].len() >= 20_256);
for c in 0..3 {
assert!(snr(&buf.channels[c], &out[c][256..]) > 12.0, "E-AC-3 7.1, channel {c}: {} dB", snr(&buf.channels[c], &out[c][256..]));
}
}
/// Apple's decoder (macOS `afinfo`; skipped elsewhere) takes the priming and the length of an AAC
/// file from the edit list, which it does only for a track with a `roll` sample group.
#[test]
fn apple_reads_the_aac_priming_and_length() {
let Some(afinfo) = crate::testkit::oracle::find_tool("afinfo") else { return };
for (frames, remainder) in [(20_000, 480), (1, 1023), (4096, 0)] {
let path = crate::testkit::fixtures_dir("file_formats").join(format!("apple_{frames}.m4a"));
std::fs::write(&path, encode(&tones(48_000, 2, frames), &EncodeOptions::new(EncodeFormat::Aac)).unwrap()).unwrap();
let out = Command::new(&afinfo).arg(&path).output().unwrap();
let text = String::from_utf8_lossy(&out.stdout);
assert!(text.contains(&format!("{frames} valid frames + 1024 priming + {remainder} remainder")), "{frames} frames: {text}");
}
}
/// What `EncodeFormat` says a format takes is what the writer accepts: for every format, a file
/// can be begun exactly when the sample rate, the channel count and the layout are listed.
#[test]
fn the_format_queries_agree_with_the_writer() {
// Every rate a format lists, each with its neighbours, and some that none lists.
let mut rates: Vec<u32> = EncodeFormat::ALL.iter().filter_map(|f| f.sample_rates()).flatten().flat_map(|&r| [r - 1, r, r + 1]).collect();
rates.extend([44_000, 176_400, 192_000]);
rates.sort_unstable();
rates.dedup();
let masks = [
0x4, 0x1, 0x3, 0xC, 0x600, 0x7, 0xB, 0x103, 0x33, 0x107, 0x603, 0xF, 0x10B, 0x37, 0x607, 0x10F, 0x60B, 0x3F, 0x60F, 0x13F, 0x70F, 0x63F, 0xFF,
];
let layouts = masks.iter().map(|&mask| ChannelLayout::from_mask(mask)).chain((1..=9).map(ChannelLayout::unordered));
for layout in layouts {
for &format in EncodeFormat::ALL {
// 24 bits is a depth every format has.
let opts = EncodeOptions::new(format).with_layout(layout);
for &sample_rate in &rates {
let listed = format.sample_rates().is_none_or(|r| r.contains(&sample_rate))
&& layout.channels() <= format.max_channels()
&& format.supports_layout(&layout);
let checked = opts.check(sample_rate, layout.channels());
assert_eq!(checked.is_ok(), listed, "{format:?}, {sample_rate} Hz, {layout:?}: {checked:?}");
let begun = FileEncoder::new(Cursor::new(Vec::new()), &opts, sample_rate, layout.channels());
assert_eq!(begun.is_ok(), listed, "{format:?}, {sample_rate} Hz, {layout:?}");
}
if let Some(fixed) = format.fixed_layouts(layout.channels()) {
assert!(fixed.iter().all(|l| format.supports_layout(l) && l.channels() == layout.channels()));
assert_eq!(format.supports_layout(&layout), fixed.iter().any(|l| same_speakers(l, &layout)), "{format:?}, {layout:?}");
}
}
}
for &format in EncodeFormat::ALL {
assert!(!format.supports_layout(&ChannelLayout::unordered(0)));
assert_eq!(format.supports_quality(), EncodeOptions::new(format).with_quality(0.5).check(48_000, 2).is_ok() && format.is_lossy());
assert_eq!(format.fixed_layouts(2).is_none(), matches!(format, EncodeFormat::Wav | EncodeFormat::Aiff | EncodeFormat::Flac));
}
// The most channels is the most: one more is refused, by the layouts of a format that has
// a fixed set and by the writer of one that has not.
let most: Vec<u16> = EncodeFormat::ALL.iter().map(|f| f.max_channels()).collect();
assert_eq!(most, [32_767, 32_767, 8, 8, 8, 2, 6, 8]);
for &format in EncodeFormat::ALL {
let most = format.max_channels();
match format.fixed_layouts(most) {
Some(layouts) => assert!(!layouts.is_empty() && format.fixed_layouts(most + 1).unwrap().is_empty(), "{format:?}"),
None => {
let opts = EncodeOptions::new(format).with_bit_depth(BitDepth::Int16);
assert!(opts.check(48_000, most).is_ok() && opts.check(48_000, most + 1).is_err(), "{format:?}");
assert!(format.supports_layout(&ChannelLayout::unordered(most)) && !format.supports_layout(&ChannelLayout::unordered(most + 1)));
}
}
}
assert_eq!(EncodeFormat::Ac3.fixed_layouts(3).unwrap().len(), 3);
assert!(EncodeFormat::Aac.fixed_layouts(9).unwrap().is_empty());
}
/// Whether two layouts name the same speakers, a surround pair being either sides or backs.
fn same_speakers(a: &ChannelLayout, b: &ChannelLayout) -> bool {
let one_pair = |mask: u32| if mask & 0x630 == 0x30 { mask & !0x30 | 0x600 } else { mask };
matches!((a.mask(), b.mask()), (Some(a), Some(b)) if one_pair(a) == one_pair(b))
}
/// `bitrate` is the rate the file is written at, for the options and for the encoder they give.
#[test]
fn the_bit_rate_used_can_be_asked_for() {
let rate = |opts: EncodeOptions, sample_rate, channels| {
let asked = opts.bitrate(sample_rate, channels).unwrap();
assert_eq!(FileEncoder::new(Cursor::new(Vec::new()), &opts, sample_rate, channels).unwrap().bitrate(), asked);
asked
};
assert_eq!(rate(EncodeOptions::new(EncodeFormat::Mp3), 48_000, 2), Some(192_000));
assert_eq!(rate(EncodeOptions::new(EncodeFormat::Mp3).with_bitrate(130_000), 48_000, 2), Some(128_000));
assert_eq!(rate(EncodeOptions::new(EncodeFormat::Mp3).with_bitrate(u32::MAX), 22_050, 1), Some(160_000));
assert_eq!(rate(EncodeOptions::new(EncodeFormat::Ac3).with_bitrate(191_999), 48_000, 2), Some(160_000));
assert_eq!(rate(EncodeOptions::new(EncodeFormat::Ac3), 48_000, 6), Some(448_000));
assert_eq!(rate(EncodeOptions::new(EncodeFormat::Eac3).with_bitrate(100_999), 48_000, 2), Some(100_000));
assert_eq!(rate(EncodeOptions::new(EncodeFormat::Aac), 48_000, 2), Some(128_000));
assert_eq!(rate(EncodeOptions::new(EncodeFormat::Aac).with_bitrate(128), 48_000, 2), Some(24_000));
assert_eq!(rate(EncodeOptions::new(EncodeFormat::Aac).with_bitrate(u32::MAX), 8000, 1), Some(48_000));
assert_eq!(rate(EncodeOptions::new(EncodeFormat::Aac).with_quality(0.5), 48_000, 2), None);
for format in [EncodeFormat::Wav, EncodeFormat::Aiff, EncodeFormat::Flac, EncodeFormat::Alac] {
assert_eq!(rate(EncodeOptions::new(format).with_bitrate(96_000), 48_000, 2), None, "{format:?}");
}
// The size of a second of MP3 is the rate reported.
let buf = tones(48_000, 2, 48_000);
let opts = EncodeOptions::new(EncodeFormat::Mp3).with_bitrate(130_000);
assert_eq!(encode(&buf, &opts).unwrap().len() as u32, 43 * 1152 / 8 * opts.bitrate(48_000, 2).unwrap().unwrap() / 48_000);
assert!(is_unsupported(EncodeOptions::new(EncodeFormat::Mp3).bitrate(48_000, 6)));
}
+1
View File
@@ -12,6 +12,7 @@ mod ac3_encoder_oracle;
mod ac3_oracle;
mod alac;
mod concealment;
mod file_formats;
mod mp3_decoder_oracle;
mod mp3_encoder_oracle;
mod mpa_oracle;
+3 -1
View File
@@ -138,7 +138,9 @@ impl Fib {
}
let w_ident = u16le(0);
if w_ident == 0xA5DC {
return Err(DocbinError::NotWord("Word 6.0/95 format, only Word 97-2003 is supported".into()));
// `read` sends Word 6.0/95 streams to `word6` before this FIB is parsed. This keeps any
// other caller from reading one with the Word 97 layout, which it doesn't have.
return Err(DocbinError::NotWord("a Word 6.0/95 file doesn't have the Word 97 FIB layout".into()));
}
if w_ident != W_IDENT {
return Err(DocbinError::NotWord(format!("magic 0x{w_ident:04X}, expected 0x{W_IDENT:04X}")));
+54 -5
View File
@@ -29,6 +29,19 @@ pub(crate) struct Bins {
sorted: bool,
/// Page number (× 512 = byte offset in the WordDocument stream).
pns: Vec<u32>,
/// Runs read ahead of time instead of pages (Word 6.0/95, whose FKPs and sprms are another
/// layout, translated by [`crate::word6`]): sorted by `lo`, not overlapping.
translated: Option<Vec<TranslatedRun>>,
}
/// One run of a [`Bins::translated`] table: the FCs `[lo, hi)` it covers, the paragraph style
/// (for PAPX runs) and a Word 97 grpprl.
#[derive(Clone, Debug, PartialEq)]
pub(crate) struct TranslatedRun {
pub(crate) lo: u32,
pub(crate) hi: u32,
pub(crate) istd: u16,
pub(crate) grpprl: Vec<u8>,
}
impl Bins {
@@ -37,7 +50,7 @@ impl Bins {
let fc = fc as usize;
let lcb = lcb as usize;
if lcb < 4 || !(lcb - 4).is_multiple_of(8) {
return Ok(Bins { fcs: Vec::new(), sorted: true, pns: Vec::new() });
return Ok(Bins { fcs: Vec::new(), sorted: true, pns: Vec::new(), translated: None });
}
let end = fc.checked_add(lcb).ok_or_else(|| DocbinError::Malformed("bin table overflow".into()))?;
let plc = table.get(fc..end).ok_or_else(|| DocbinError::Malformed("bin table outside the Table stream".into()))?;
@@ -56,7 +69,31 @@ impl Bins {
pns.push(at(n + 1 + i).ok_or_else(|| DocbinError::Malformed("truncated bin aPn".into()))? & 0x003F_FFFF);
}
let sorted = fcs.windows(2).all(|w| w.first() <= w.get(1));
Ok(Bins { fcs, sorted, pns })
Ok(Bins { fcs, sorted, pns, translated: None })
}
/// A table of runs read ahead of time ([`TranslatedRun`]). Runs are sorted by start; one that
/// overlaps an earlier one (a corrupt file) or covers nothing is dropped.
pub(crate) fn translated(mut runs: Vec<TranslatedRun>) -> Bins {
runs.sort_by_key(|r| r.lo);
let mut kept: Vec<TranslatedRun> = Vec::with_capacity(runs.len());
for r in runs {
if r.lo < r.hi && kept.last().is_none_or(|last| r.lo >= last.hi) {
kept.push(r);
}
}
Bins { fcs: Vec::new(), sorted: true, pns: Vec::new(), translated: Some(kept) }
}
/// For a translated table: the run covering `fc`, or the gap `[lo, hi)` between runs that
/// holds it.
fn translated_at(runs: &[TranslatedRun], fc: u32) -> Result<&TranslatedRun, (u32, u32)> {
let i = runs.partition_point(|r| r.lo <= fc);
let prev = i.checked_sub(1).and_then(|i| runs.get(i));
match prev {
Some(r) if fc < r.hi => Ok(r),
_ => Err((prev.map_or(0, |r| r.hi), runs.get(i).map_or(u32::MAX, |r| r.lo))),
}
}
/// The page containing `fc`, as a slice of the WordDocument stream, and the FC range
@@ -77,13 +114,19 @@ impl Bins {
/// The grpprl of the Chpx covering `fc` ([MS-DOC] ChpxFkp: rgfc u32s, rgb offsets ×2,
/// crun in the last byte).
pub(crate) fn chpx<'w>(&self, word: &'w [u8], fc: u32) -> &'w [u8] {
pub(crate) fn chpx<'w>(&'w self, word: &'w [u8], fc: u32) -> &'w [u8] {
self.chpx_run(word, fc).grpprl
}
/// [`Bins::chpx`] with the FC range over which the same grpprl is the answer, so a walk
/// over consecutive characters looks it up once per run, not once per character.
pub(crate) fn chpx_run<'w>(&self, word: &'w [u8], fc: u32) -> ChpxRun<'w> {
pub(crate) fn chpx_run<'w>(&'w self, word: &'w [u8], fc: u32) -> ChpxRun<'w> {
if let Some(runs) = &self.translated {
return match Self::translated_at(runs, fc) {
Ok(r) => ChpxRun { grpprl: &r.grpprl, lo: r.lo, hi: r.hi },
Err((lo, hi)) => ChpxRun { grpprl: &[], lo, hi },
};
}
let none = ChpxRun { grpprl: &[], lo: 1, hi: 0 };
let Some((page, page_lo, page_hi)) = self.page(word, fc) else { return none };
let Some(&crun) = page.get(511) else { return none };
@@ -113,7 +156,13 @@ impl Bins {
/// ([MS-DOC] PapxFkp: rgfc u32s — each the FC *following* a paragraph mark —, rgbx BX
/// entries (1 offset byte + 12 PHE bytes), crun in the last byte; the PAPX itself is a
/// PapxInFkp with the cb/cb' size quirk). Query with the FC of the character after the mark.
pub(crate) fn papx<'w>(&self, word: &'w [u8], fc: u32) -> (u16, &'w [u8]) {
pub(crate) fn papx<'w>(&'w self, word: &'w [u8], fc: u32) -> (u16, &'w [u8]) {
if let Some(runs) = &self.translated {
return match Self::translated_at(runs, fc) {
Ok(r) => (r.istd, &r.grpprl),
Err(_) => (0, &[]),
};
}
let Some((page, _, _)) = self.page(word, fc) else { return (0, &[]) };
let Some(&crun) = page.get(511) else { return (0, &[]) };
// BX is 13 bytes; cap crun at what fits before byte 511.
+100 -1
View File
@@ -6,6 +6,9 @@
//! like the other Craft parsers, is lenient by design (unknown structures are skipped, bad numbers
//! fall back to defaults) and bounded (stream sizes, piece counts and property counts are
//! capped), so hostile input yields an error or a best-effort document, never a panic.
//!
//! Word 6.0/95 files, which that specification does not cover, are read by `word6` from their
//! observed layout: their text, formatting and tables so far.
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
// The code came from an app whose lints allow this.
#![allow(clippy::type_complexity)]
@@ -29,6 +32,7 @@ mod sections;
mod sprm;
mod stsh;
mod table;
mod word6;
use std::sync::Arc;
@@ -220,6 +224,9 @@ fn read_limited(bytes: &[u8], password: Option<&str>, max_paragraphs: usize) ->
if word.len() as u64 > MAX_STREAM {
return Err(DocbinError::Limit(format!("WordDocument stream is {} bytes", word.len())));
}
if word6::is_word6(&word) {
return read_word6(&comp, &word, max_paragraphs);
}
let enc = fib::peek_encryption(&word);
// The FIB names the Table stream (0Table or 1Table); fall back to whichever exists,
// since files written by other writers sometimes carry the wrong bit.
@@ -431,6 +438,55 @@ fn read_limited(bytes: &[u8], password: Option<&str>, max_paragraphs: usize) ->
Ok(doc)
}
/// Read a Word 6.0/95 file ([`word6`]): its main text, with its character and paragraph
/// formatting and table rows translated to Word 97 sprms, through the same walk as a Word 97 file.
/// Its paragraph styles are read too; character styles and the other stories are not yet, and a
/// section mark reads as a page break.
fn read_word6(comp: &craft_cfb::CompoundFile<'_>, word: &[u8], max_paragraphs: usize) -> Result<Document, DocbinError> {
let fib = word6::Fib6::parse(word)?;
let content = word6::content(word, &fib)?;
let mut doc = Document::new();
// Word opens these files in compatibility mode 11 too.
doc.settings.compat_mode = 11;
if let Some(core) = metadata::read(comp) {
doc.core = core;
}
doc.body.clear();
// The paragraph styles, built as for Word 97 files from their translated formatting.
doc.styles = Arc::new(fmt::stylesheet(&content.styles, &content.fonts, stsh::StandardFonts::default()));
let sheet: StyleSheet = StyleSheet::clone(&doc.styles);
// As for Word 97 files: the text read can't exceed twice the stream, nor the absolute ceiling.
let budget = std::cell::Cell::new((word.len() as u64).saturating_mul(2).min(MAX_TOTAL_CHARS));
let work = Work::new(MAX_WORK);
let paragraphs = ParaBudget { left: std::cell::Cell::new(max_paragraphs), exceeded: std::cell::Cell::new(false) };
let mut pics = media::Pictures::for_input(word.len());
let ctx = WalkCtx {
word,
data: &[],
pieces: &content.pieces,
chpx_bins: &content.chpx,
papx_bins: &content.papx,
fonts: &content.fonts,
raw_styles: &content.styles,
sheet: &sheet,
notes: &[],
marks: &[],
drawn: &[],
sect_ends: &[],
budget: &budget,
paragraphs: &paragraphs,
work: &work,
};
let paras = walk(&ctx, 0, fib.ccp_text, &mut pics);
if paragraphs.exceeded.get() {
return Err(paragraph_limit(max_paragraphs));
}
doc.body = table::assemble(paras);
doc.ensure_nonempty();
work.log();
Ok(doc)
}
fn paragraph_limit(max_paragraphs: usize) -> DocbinError {
DocbinError::Limit(format!("the document has more than {max_paragraphs} paragraphs and table cells"))
}
@@ -648,6 +704,20 @@ fn walk<'a>(ctx: &WalkCtx<'a>, cp_start: u32, cp_end: u32, pics: &mut media::Pic
// querying at the mark's own FC finds that paragraph's properties.
let fc_mark = ctx.pieces.fc_of_cp(cp).unwrap_or(0);
let (istd, papx) = ctx.papx_bins.papx(ctx.word, fc_mark);
// The Prm of the piece holding the mark adds its paragraph sprms after the PAPX's
// ([MS-DOC] §2.4.6.1, step 5), as Word 6/95's fast saves record a paragraph change.
let extra = prm_paragraph_sprms(ctx.pieces.piece_prm(cp), ctx.work);
let combined;
let papx: &[u8] = if extra.is_empty() {
papx
} else {
// Re-framed from its Prls, so that a pad byte at its end can't swallow the
// first appended opcode.
let mut v: Vec<u8> = sprm::iter(papx).flat_map(|p| p.op.to_le_bytes().into_iter().chain(p.operand.iter().copied())).collect();
v.extend_from_slice(&extra);
combined = v;
&combined
};
if let Some(st) = ctx.raw_styles.get(istd as usize).filter(|s| !s.name.is_empty()) {
pb.props.style = Some(fmt::style_id(&st.name));
}
@@ -991,13 +1061,42 @@ struct FmtState<'a> {
/// paragraph style stay the same, so a Prm grpprl (up to 64 KB) is interpreted once per
/// formatting change, not once per character (#3692).
struct FmtMemo<'a> {
/// The CHPX grpprl, compared by address: it is a slice of the WordDocument stream.
/// The CHPX grpprl, compared by address: a slice of the WordDocument stream, or of a Word 6.0/95
/// file's translated runs, both of which stay put for the walk.
chpx: &'a [u8],
prm: u16,
style: Option<String>,
props: CharProps,
}
/// The paragraph and table sprms (sgc 1 and 5) of a piece's Prm, as Prls to append to a
/// paragraph's PAPX: a Prm0's single sprm, or those of the Prm1's grpprl. A Prm1 grpprl is
/// charged to `work`, as for [`apply_prm`].
fn prm_paragraph_sprms(prm: PrmRef<'_>, work: &Work) -> Vec<u8> {
let mut out = Vec::new();
match prm {
PrmRef::Sprm0 { isprm, val } => {
if let Some(op) = sprm::from_prm0(isprm)
&& matches!(Prl { op, operand: &[] }.sgc(), 1 | 5)
{
out.extend_from_slice(&op.to_le_bytes());
out.push(val);
}
}
PrmRef::Grpprl(Some(g)) => {
if !work.charge(g.len() as u64, Cost::Formatting) {
return out;
}
for prl in sprm::iter(g).filter(|p| matches!(p.sgc(), 1 | 5)) {
out.extend_from_slice(&prl.op.to_le_bytes());
out.extend_from_slice(prl.operand);
}
}
PrmRef::None | PrmRef::Grpprl(None) => {}
}
out
}
/// Apply a piece's Prm (Prm0 short sprm or Prm1 grpprl) to character properties. A Prm1
/// grpprl is charged to `work`; once that is spent the grpprl is skipped.
fn apply_prm(props: &mut CharProps, prm: PrmRef<'_>, fonts: &[String], base: &CharProps, work: &Work) {
+161 -17
View File
@@ -1,20 +1,71 @@
//! The piece table ([MS-DOC] `Clx`/`Pcdt`/`PlcPcd`): where every character position lives in
//! the WordDocument stream, and how it is encoded.
//!
//! Word 6.0/95 files ([`crate::word6`]) keep the same `Clx` shape, but every piece's text is at a
//! plain byte offset: 8-bit text in the code page of its piece's or run's font (or the document's),
//! or UTF-16 in a file with the FIB's fExtChar flag.
use craft_codepage::cp1252;
use craft_codepage::{code_page_byte, cp1252, is_byte_code_page};
use crate::DocbinError;
/// Most pieces any real file has; more means a corrupt `PlcPcd`.
const MAX_PIECES: usize = 1_000_000;
/// One piece: text at FcCompressed `fc` (30-bit offset + compression bit).
/// How a piece's characters are stored.
#[derive(Clone, Copy, Debug, PartialEq)]
enum Text {
/// UTF-16LE at `fc`.
Utf16,
/// Windows-1252, one byte per character at `fc / 2` (Word 97 FcCompressed).
Compressed,
/// One byte per character at `fc` itself, in the code page [`PieceTable::code_page_at`] gives
/// that byte (Word 6.0/95).
Bytes,
}
/// One piece: its text at `fc` (for Word 97, the 30-bit offset of FcCompressed).
#[derive(Clone, Copy, Debug)]
struct Pcd {
fc: u32,
compressed: bool,
/// `Prm`: either a single sprm (Prm0) or an index into the Clx's Prc grpprls (Prm1).
text: Text,
/// `Prm`: either a single sprm (Prm0) or an index into the Clx's Prc grpprls (Prm1). In a Word
/// 6.0/95 table the Prcs hold translated grpprls ([`PieceTable::parse_word6`]), and a Prm0's
/// isprm is already the opcode [MS-DOC]'s isprm table maps.
prm: u16,
/// For a Word 6.0/95 [`Text::Bytes`] piece whose Prm names a font: that font's code page,
/// which outranks the runs' ([`PieceTable::code_page_at`]).
code_page: Option<u16>,
}
impl Pcd {
/// The byte offset of the character `step / 2` characters into the piece. `step` is twice
/// the CP offset, so one formula serves all three encodings.
fn fc_at(&self, step: u32) -> Option<u32> {
match self.text {
Text::Utf16 => self.fc.checked_add(step),
Text::Compressed => self.fc.checked_add(step)?.checked_div(2),
Text::Bytes => self.fc.checked_add(step / 2),
}
}
}
/// The code page of the 8-bit text in the byte range `[lo, hi)` of the WordDocument stream.
#[derive(Clone, Copy, Debug, PartialEq)]
pub(crate) struct CodePageRun {
pub(crate) lo: u32,
pub(crate) hi: u32,
pub(crate) code_page: u16,
}
/// How a Word 6.0/95 file's text is stored and decoded ([`crate::word6`]).
pub(crate) struct Word6Text {
/// UTF-16 rather than 8-bit (the FIB's fExtChar flag).
pub(crate) wide: bool,
/// The code page of 8-bit text that no piece or run gives one for.
pub(crate) default_code_page: u16,
/// The code page of each byte range, from its run's font (sorted by `lo`, not overlapping).
pub(crate) code_pages: Vec<CodePageRun>,
}
/// The parsed piece table plus the grpprls of the Prcs that Prm1 references.
@@ -23,11 +74,58 @@ pub(crate) struct PieceTable {
cps: Vec<u32>,
pieces: Vec<Pcd>,
prc_grpprls: Vec<Vec<u8>>,
/// For [`Text::Bytes`] pieces: the code page of each byte range, sorted by `lo`, not
/// overlapping. Bytes outside every range are in `default_code_page`.
code_pages: Vec<CodePageRun>,
default_code_page: u16,
}
impl PieceTable {
/// Parse the `Clx` at `table[fc .. fc+lcb]`.
pub(crate) fn parse(table: &[u8], fc: u32, lcb: u32) -> Result<PieceTable, DocbinError> {
Self::parse_clx(table, fc, lcb, None)
}
/// Parse a Word 6.0/95 `Clx` at `word[fc .. fc+lcb]`: the Word 97 shape, but every piece's text
/// is at its plain byte offset. `piece_code_page` gives the code page a piece's raw Prm
/// imposes (with the Clx's raw Prc grpprls to look Prm1 indices up in), if any; then each Prc
/// grpprl is replaced by `translate_prc`'s Word 97 sprms, which the walk applies to the piece.
pub(crate) fn parse_word6(
word: &[u8],
fc: u32,
lcb: u32,
text: Word6Text,
piece_code_page: impl Fn(u16, &[Vec<u8>]) -> Option<u16>,
translate_prc: impl Fn(&[u8]) -> Vec<u8>,
) -> Result<PieceTable, DocbinError> {
let mut t = Self::parse_clx(word, fc, lcb, Some(text.wide))?;
if !text.wide {
for p in &mut t.pieces {
p.code_page = piece_code_page(p.prm, &t.prc_grpprls);
}
}
t.prc_grpprls = t.prc_grpprls.iter().map(|g| translate_prc(g)).collect();
t.code_pages = text.code_pages;
t.default_code_page = text.default_code_page;
Ok(t)
}
/// One Word 6.0/95 piece: `ccp` characters from byte `fc` on. This covers a file that was not
/// fast-saved, which has no `Clx`.
pub(crate) fn contiguous_word6(fc: u32, ccp: u32, text: Word6Text) -> PieceTable {
let kind = if text.wide { Text::Utf16 } else { Text::Bytes };
PieceTable {
cps: vec![0, ccp],
pieces: vec![Pcd { fc, text: kind, prm: 0, code_page: None }],
prc_grpprls: Vec::new(),
code_pages: text.code_pages,
default_code_page: text.default_code_page,
}
}
/// `word6`: `None` for Word 97 and later, `Some(wide)` for a Word 6.0/95 file (whose raw Prms
/// and Prcs are kept for [`PieceTable::parse_word6`]).
fn parse_clx(table: &[u8], fc: u32, lcb: u32, word6: Option<bool>) -> Result<PieceTable, DocbinError> {
let fc = fc as usize;
let lcb = lcb as usize;
if lcb == 0 {
@@ -95,9 +193,26 @@ impl PieceTable {
return Err(DocbinError::Malformed("truncated aPcd".into()));
};
let prm = plc.get(at + 4..at + 6).map(|b| u16::from_le_bytes([b[0], b[1]])).unwrap_or(0);
pieces.push(Pcd { fc: fc_raw & 0x3FFF_FFFF, compressed: fc_raw & 0x4000_0000 != 0, prm });
pieces.push(match word6 {
// A plain byte offset, with no compression bit: 8-bit text, or UTF-16 in a file with
// fExtChar. The raw Prm is kept for `parse_word6`.
Some(wide) => Pcd { fc: fc_raw, text: if wide { Text::Utf16 } else { Text::Bytes }, prm, code_page: None },
None => {
let text = if fc_raw & 0x4000_0000 != 0 { Text::Compressed } else { Text::Utf16 };
Pcd { fc: fc_raw & 0x3FFF_FFFF, text, prm, code_page: None }
}
});
}
Ok(PieceTable { cps, pieces, prc_grpprls, code_pages: Vec::new(), default_code_page: 1252 })
}
/// The code page of the 8-bit text byte at `fc` (in [`Text::Bytes`] pieces).
fn code_page_at(&self, fc: u32) -> u16 {
let i = self.code_pages.partition_point(|r| r.lo <= fc);
match i.checked_sub(1).and_then(|i| self.code_pages.get(i)) {
Some(r) if fc < r.hi => r.code_page,
_ => self.default_code_page,
}
Ok(PieceTable { cps, pieces, prc_grpprls })
}
/// The Prls this piece's `Prm` adds. Bit 0 (`fComplex`) discriminates: a Prm0
@@ -133,8 +248,7 @@ impl PieceTable {
let p = self.piece_of(cp)?;
let i = self.cps.partition_point(|&c| c <= cp).checked_sub(1)?;
let cp0 = *self.cps.get(i)?;
let step = cp.checked_sub(cp0)?.checked_mul(2)?;
if p.compressed { p.fc.checked_add(step)?.checked_div(2) } else { p.fc.checked_add(step) }
p.fc_at(cp.checked_sub(cp0)?.checked_mul(2)?)
}
/// The piece holding `cp`, with the CP range it covers: for every CP in that range the
@@ -167,13 +281,24 @@ impl PieceTable {
let (Some(p), Some(&cp0)) = (self.pieces.get(i), self.cps.get(i)) else { return Err(u32::MAX) };
let Some(off) = cp.checked_sub(cp0) else { return Err(next) };
let off = off as usize;
if p.compressed {
// 8-bit, Windows-1252, one byte per character, stored at fc/2.
let at = ((p.fc / 2) as usize).checked_add(off);
return match at.and_then(|a| word.get(a)) {
Some(&b) => Ok((cp1252(b), 1)),
None => Err(next),
};
match p.text {
Text::Compressed => {
// 8-bit, Windows-1252, one byte per character, stored at fc/2.
let at = ((p.fc / 2) as usize).checked_add(off);
return match at.and_then(|a| word.get(a)) {
Some(&b) => Ok((cp1252(b), 1)),
None => Err(next),
};
}
Text::Bytes => {
// 8-bit, one byte per character at fc, in its run's code page.
let at = (p.fc as usize).checked_add(off);
return match at.and_then(|a| Some((u32::try_from(a).ok()?, *word.get(a)?))) {
Some((a, b)) => Ok((byte_char(p.code_page.unwrap_or_else(|| self.code_page_at(a)), b), 1)),
None => Err(next),
};
}
Text::Utf16 => {}
}
// UTF-16LE, one 16-bit unit per character, stored at fc.
let unit = |k: usize| -> Option<u16> {
@@ -207,8 +332,7 @@ impl PieceSpan<'_> {
/// [`PieceTable::fc_of_cp`] for a CP inside the span.
pub(crate) fn fc_at(&self, cp: u32) -> Option<u32> {
let step = cp.checked_sub(self.cp_lo)?.checked_mul(2)?;
if self.pcd.compressed { self.pcd.fc.checked_add(step)?.checked_div(2) } else { self.pcd.fc.checked_add(step) }
self.pcd.fc_at(cp.checked_sub(self.cp_lo)?.checked_mul(2)?)
}
/// The raw Prm of the piece: two CPs with the same value get the same [`PrmRef`].
@@ -228,3 +352,23 @@ pub(crate) enum PrmRef<'a> {
/// Prm1: a grpprl from a Prc (absent if out of range).
Grpprl(Option<&'a [u8]>),
}
/// Windows' code page number for symbol fonts (CP_SYMBOL).
pub(crate) const SYMBOL_CODE_PAGE: u16 = 42;
/// One byte of 8-bit text in `code_page`. The East Asian code pages store a character as a lead
/// and a trail byte, which one CP per byte can't represent, so their bytes above ASCII read as
/// U+FFFD rather than as unrelated Windows-1252 letters.
fn byte_char(code_page: u16, b: u8) -> char {
if code_page == SYMBOL_CODE_PAGE {
// Each character from the space up to its private-use code point, as Word reads a document
// marked as Symbol; control characters (paragraph marks, fields) stay themselves.
if b < 0x20 { char::from(b) } else { char::from_u32(0xF000 + u32::from(b)).unwrap_or('\u{FFFD}') }
} else if is_byte_code_page(code_page) {
code_page_byte(code_page, b)
} else if b.is_ascii() {
char::from(b)
} else {
'\u{FFFD}'
}
}
+30 -5
View File
@@ -10,6 +10,7 @@ use super::read;
mod drawing;
mod encrypted;
mod metadata;
mod word6;
/// Offset in the WordDocument stream where test text pieces are placed (past the FIB).
const TEXT_FC: u32 = 0x600;
@@ -176,12 +177,15 @@ fn wrong_magic_rejected() {
}
#[test]
fn word_6_95_rejected() {
let mut fib = fib_bytes(&FibSpec::default());
fn word_6_95_magic_goes_to_the_word6_reader() {
// A Word 6.0/95 signature is no longer refused: the stream is read as that version (here an
// empty document, since a Word 97 FIB holds no Word 6 text length). The flags are cleared:
// the Word 97 default sets fExtChar, which the Word 6 reader refuses.
let mut fib = fib_bytes(&FibSpec { flags: 0, ..FibSpec::default() });
fib[0] = 0xDC;
fib[1] = 0xA5;
let f = cfb_file(&[("WordDocument", &fib)]);
assert!(matches!(read(&f), Err(super::DocbinError::NotWord(m)) if m.contains("6.0/95")));
assert!(read(&f).is_ok());
}
#[test]
@@ -882,8 +886,6 @@ fn corpus_files_open() {
let bytes = std::fs::read(&p).expect("read");
let doc = match super::read(&bytes) {
Ok(d) => d,
// Word 6/95 files are a documented, intentional rejection.
Err(super::DocbinError::NotWord(m)) if m.contains("6.0/95") => continue,
Err(e) => panic!("{}: {e}", p.display()),
};
assert!(!doc.styles.styles.is_empty(), "{}: no styles", p.display());
@@ -2106,6 +2108,29 @@ fn one_section(text: &'static str, sepx: Vec<u8>, papx_entries: Vec<(u32, u16, V
}
}
#[test]
fn piece_prm_paragraph_formatting_applies_to_the_marks_paragraph() {
// [MS-DOC] §2.4.6.1 step 5: the Prm of the piece holding the paragraph mark adds its paragraph
// sprms after the PAPX's. Prm1 -> a Prc with sprmPDxaLeft80 (1440 twips) and sprmPJc80
// (centred); Prm0 isprm 0x05 (sprmPJc) with operand 2 (right).
let prcs = vec![grpprl(&[(0x840F, &1440i16.to_le_bytes()), (0x2403, &[0x01])])];
let para = |prm: u16| {
let spec = RichSpec {
text: "Text\r",
styles: vec![(1, 0x0FFF, "Normal", Vec::new(), Vec::new())],
fonts: vec!["Times New Roman"],
chpx_runs: vec![(0, Vec::new())],
papx_entries: vec![(4, 0, grpprl(&[(0x840F, &360i16.to_le_bytes())]))],
};
let doc = read(&rich_doc_with(&spec, &RichExtra { prcs: prcs.clone(), prm, ..Default::default() })).expect("opens");
let p = para0(&doc);
(p.props.indent_left, p.props.align)
};
assert_eq!(para(0x0000), (Some(18.0), None), "no Prm: the PAPX's indent");
assert_eq!(para(0x0001), (Some(72.0), Some(craft_wordmodel::props::Align::Center)), "Prm1: the Prc's sprms override the PAPX's");
assert_eq!(para(0x020A), (Some(18.0), Some(craft_wordmodel::props::Align::Right)), "Prm0: sprmPJc right");
}
#[test]
fn piece_prm_character_formatting_applied() {
// #458. Bit 0 of a Prm is fComplex ([MS-DOC] §2.9.215/§2.9.216): Prm0 = isprm in bits
+747
View File
@@ -0,0 +1,747 @@
//! Word 6.0/95 fixtures, built in code. No public specification describes this version; these
//! build the layout observed in real files and described in `crate::word6`.
use proptest::prelude::*;
use super::{body_texts, cfb_file};
use crate::{DocbinError, read};
/// Where the text starts: right after the FIB, as in every observed file.
const TEXT_AT: u32 = 0x300;
/// One stylesheet entry as Word 6/95 stores it.
#[derive(Clone, Copy, Default)]
struct Std<'a> {
/// The built-in style id, or 0x0FFE for a user-defined style.
sti: u16,
/// 1 paragraph, 2 character.
sgc: u16,
/// The base style's index, or 0x0FFF.
base: u16,
name: &'a str,
/// Paragraph sprms (paragraph styles only).
papx: &'a [u8],
/// Character sprms.
chpx: &'a [u8],
}
/// The stylesheet bytes for `styles`: the 14-byte header (count, fixed-part size 8, …), then per
/// style a size and the entry, or 0 for an empty slot.
fn stylesheet(styles: &[Option<Std>]) -> Vec<u8> {
let mut v = vec![14u8, 0];
for w in [styles.len() as u16, 8, 1, 0x4B, 0x0F, 0, 0] {
v.extend_from_slice(&w.to_le_bytes());
}
for (istd, st) in styles.iter().enumerate() {
let Some(st) = st else {
v.extend_from_slice(&[0, 0]);
continue;
};
let cupx: u16 = if st.sgc == 1 { 2 } else { 1 };
let mut e = Vec::new();
for w in [st.sti, st.sgc | st.base << 4, cupx, 0] {
e.extend_from_slice(&w.to_le_bytes());
}
e.push(st.name.len() as u8);
e.extend_from_slice(st.name.as_bytes());
e.push(0);
let upx = |e: &mut Vec<u8>, bytes: &[u8]| {
if e.len() % 2 == 1 {
e.push(0);
}
e.extend_from_slice(&(bytes.len() as u16).to_le_bytes());
e.extend_from_slice(bytes);
};
if st.sgc == 1 {
let mut papx = (istd as u16).to_le_bytes().to_vec();
papx.extend_from_slice(st.papx);
upx(&mut e, &papx);
}
upx(&mut e, st.chpx);
v.extend_from_slice(&(e.len() as u16).to_le_bytes());
v.extend_from_slice(&e);
}
v
}
/// What a test Word 6.0/95 file holds. Offsets in `runs` and `pieces` are into `text`.
#[derive(Clone, Default)]
struct Doc6<'a> {
nfib: u16,
flags: u16,
/// The stored 8-bit text.
text: &'a [u8],
/// (charset, name) per font index.
fonts: &'a [(u8, &'a str)],
/// The font table's entries as raw bytes instead of `fonts` (the size word is added).
raw_fonts: Option<&'a [u8]>,
/// Contiguous character runs (lo, hi, grpprl), all in one FKP page.
runs: &'a [(u32, u32, &'a [u8])],
/// Contiguous paragraph runs (lo, hi, grpprl), style 0, all in one FKP page. Each covers the
/// paragraph whose mark lies in it.
paras: &'a [(u32, u32, &'a [u8])],
/// For a fast-saved file: (length, offset) per piece, in CP order.
pieces: Option<&'a [(u32, u32)]>,
/// Each piece's Prm (0 when absent or shorter than `pieces`).
prms: &'a [u16],
/// The Clx's Prc grpprls, which a Prm1 indexes.
prcs: &'a [&'a [u8]],
/// The FIB's character set word at 0x14.
chse: u16,
/// The style of each paragraph run (0, Normal, when absent or shorter than `paras`).
para_styles: &'a [u16],
/// The stylesheet: one entry per style index, `None` for an empty slot.
styles: &'a [Option<Std<'a>>],
/// The main text's length in characters, when it isn't the stored bytes' (16-bit text).
ccp: Option<u32>,
}
fn put16(v: &mut [u8], at: usize, x: u16) {
v[at..at + 2].copy_from_slice(&x.to_le_bytes());
}
fn put32(v: &mut [u8], at: usize, x: u32) {
v[at..at + 4].copy_from_slice(&x.to_le_bytes());
}
/// Append one FKP page for `runs` and its bin table, and return the bin table's (fc, lcb). A
/// character page has a 1-byte entry per run and CHPXs (byte count + grpprl); a paragraph page
/// has 7-byte entries and PAPXs (word count + style 0 + grpprl padded to whole words).
fn fkp(w: &mut Vec<u8>, runs: &[(u32, u32, &[u8])], papx: bool, istds: &[u16]) -> (u32, u32) {
let (Some(first), Some(last)) = (runs.first(), runs.last()) else { return (0, 0) };
w.resize(w.len().div_ceil(512) * 512, 0);
let pn = (w.len() / 512) as u16;
let crun = runs.len();
let entry = if papx { 7 } else { 1 };
let mut page = [0u8; 512];
for (k, (lo, _, _)) in runs.iter().enumerate() {
put32(&mut page, 4 * k, TEXT_AT + lo);
}
put32(&mut page, 4 * crun, TEXT_AT + last.1);
// Records from the end of the page down, each at an even offset.
let mut top = 511usize;
for (k, (_, _, g)) in runs.iter().enumerate() {
let body: Vec<u8> = if papx {
let mut b = istds.get(k).copied().unwrap_or(0).to_le_bytes().to_vec();
b.extend_from_slice(g);
if b.len() % 2 == 1 {
b.push(0);
}
b
} else if g.is_empty() {
continue;
} else {
g.to_vec()
};
let at = (top - 1 - body.len()) & !1;
page[at] = if papx { (body.len() / 2) as u8 } else { body.len() as u8 };
page[at + 1..at + 1 + body.len()].copy_from_slice(&body);
page[4 * (crun + 1) + entry * k] = (at / 2) as u8;
top = at;
}
page[511] = crun as u8;
w.extend_from_slice(&page);
let mut bte = Vec::new();
bte.extend_from_slice(&(TEXT_AT + first.0).to_le_bytes());
bte.extend_from_slice(&(TEXT_AT + last.1).to_le_bytes());
bte.extend_from_slice(&pn.to_le_bytes());
let at = w.len() as u32;
w.extend_from_slice(&bte);
(at, bte.len() as u32)
}
/// The WordDocument stream: FIB, text, then the FKP pages, font table and piece table.
fn word_stream(d: &Doc6) -> Vec<u8> {
let mut w = vec![0u8; TEXT_AT as usize];
w.extend_from_slice(d.text);
let ccp = match (d.ccp, d.pieces) {
(Some(ccp), _) => ccp,
(None, pieces) => match pieces {
Some(p) => p.iter().map(|(len, _)| len).sum(),
None => d.text.len() as u32,
},
};
let mut pairs: Vec<(usize, u32, u32)> = Vec::new();
for (pair, runs, papx) in [(12, d.runs, false), (13, d.paras, true)] {
let (fc, lcb) = fkp(&mut w, runs, papx, d.para_styles);
if lcb > 0 {
pairs.push((pair, fc, lcb));
}
}
if !d.styles.is_empty() {
let st = stylesheet(d.styles);
pairs.push((1, w.len() as u32, st.len() as u32));
w.extend_from_slice(&st);
}
if !d.fonts.is_empty() || d.raw_fonts.is_some() {
let mut ffn = vec![0u8, 0];
ffn.extend_from_slice(d.raw_fonts.unwrap_or_default());
for (charset, name) in d.fonts {
let mut e = vec![0u8, 0x16, 0x90, 0x01, *charset, 0x00];
e.extend_from_slice(name.as_bytes());
e.push(0);
e[0] = (e.len() - 1) as u8;
ffn.extend_from_slice(&e);
}
let size = ffn.len() as u16;
put16(&mut ffn, 0, size);
pairs.push((15, w.len() as u32, ffn.len() as u32));
w.extend_from_slice(&ffn);
}
if let Some(pieces) = d.pieces {
let mut plc = Vec::new();
let mut cp = 0u32;
plc.extend_from_slice(&cp.to_le_bytes());
for (len, _) in pieces {
cp += len;
plc.extend_from_slice(&cp.to_le_bytes());
}
for (i, (_, off)) in pieces.iter().enumerate() {
plc.extend_from_slice(&[0, 0]);
plc.extend_from_slice(&(TEXT_AT + off).to_le_bytes());
plc.extend_from_slice(&d.prms.get(i).copied().unwrap_or(0).to_le_bytes());
}
let mut clx = Vec::new();
for g in d.prcs {
clx.push(0x01);
clx.extend_from_slice(&(g.len() as u16).to_le_bytes());
clx.extend_from_slice(g);
}
clx.push(0x02);
clx.extend_from_slice(&(plc.len() as u32).to_le_bytes());
clx.extend_from_slice(&plc);
pairs.push((33, w.len() as u32, clx.len() as u32));
w.extend_from_slice(&clx);
}
put16(&mut w, 0x00, 0xA5DC);
put16(&mut w, 0x02, if d.nfib == 0 { 0x0065 } else { d.nfib });
put16(&mut w, 0x06, 0x0409);
put16(&mut w, 0x0A, d.flags | if d.pieces.is_some() { 0x0004 } else { 0 });
put16(&mut w, 0x0C, 0x0065);
put16(&mut w, 0x14, d.chse);
put32(&mut w, 0x18, TEXT_AT);
put32(&mut w, 0x1C, TEXT_AT + d.text.len() as u32);
let len = w.len() as u32;
put32(&mut w, 0x20, len);
put32(&mut w, 0x34, ccp);
for (i, fc, lcb) in pairs {
put32(&mut w, 0x58 + i * 8, fc);
put32(&mut w, 0x58 + i * 8 + 4, lcb);
}
w
}
/// A Word 6.0/95 file holding `d`: the WordDocument stream only, as the real ones have no Table
/// stream.
fn word6_file(d: &Doc6) -> Vec<u8> {
cfb_file(&[("WordDocument", &word_stream(d))])
}
fn texts(d: &Doc6) -> Vec<String> {
body_texts(&read(&word6_file(d)).expect("a Word 6.0/95 file opens"))
}
/// Fonts 0 (Western) and 1 (Cyrillic, charset 204), as the Russian files have.
const FONTS: &[(u8, &str)] = &[(0, "Times New Roman"), (204, "Times New Roman Cyr")];
#[test]
fn word_6_and_95_files_open_as_paragraphs() {
for nfib in [0x0065, 0x0068] {
let d = Doc6 { nfib, text: b"Hello\rWorld\r", ..Default::default() };
assert_eq!(texts(&d), ["Hello", "World"], "nFib 0x{nfib:04X}");
}
}
#[test]
fn fast_saved_text_follows_the_piece_table() {
// Stored out of order; the pieces' fcs are plain byte offsets (Word 97 would halve them).
let d = Doc6 { text: b"World\rHello\r", pieces: Some(&[(6, 6), (6, 0)]), ..Default::default() };
assert_eq!(texts(&d), ["Hello", "World"]);
}
#[test]
fn fast_saved_file_without_a_piece_table_is_malformed() {
let d = Doc6 { flags: 0x0004, text: b"Hello\r", ..Default::default() };
assert!(matches!(read(&word6_file(&d)), Err(DocbinError::Malformed(_))));
}
#[test]
fn a_runs_font_charset_chooses_its_code_page() {
// "Da " in font 0, then 0xC4 0xE0 ("Да" in Windows-1251) in the Cyrillic font 1.
let text = b"Da \xC4\xE0\r";
let runs: &[(u32, u32, &[u8])] = &[(0, 3, &[]), (3, 5, &[0x5D, 0x01, 0x00]), (5, 6, &[])];
let d = Doc6 { text, fonts: FONTS, runs, ..Default::default() };
assert_eq!(texts(&d), ["Da Да"]);
}
/// Text in an East Asian code page (a Japanese font, charset 128: Shift-JIS) is refused, not
/// read a byte at a time into replacement characters (review of wordcraft#6345).
#[test]
fn east_asian_text_is_refused_not_lost() {
let fonts: &[(u8, &str)] = &[(0, "Times New Roman"), (128, "MS Mincho")];
let runs: &[(u32, u32, &[u8])] = &[(0, 2, &[0x5D, 0x01, 0x00]), (2, 3, &[])];
let d = Doc6 { text: b"\x93\xfa\r", fonts, runs, ..Default::default() };
assert!(matches!(read(&word6_file(&d)), Err(DocbinError::NotWord(e)) if e.contains("East Asian")));
// The same file in a Western font still opens.
let d = Doc6 { text: b"\x93\xfa\r", fonts, runs: &[], ..Default::default() };
assert_eq!(texts(&d).len(), 1);
}
#[test]
fn the_font_sprm_is_found_after_other_sprms() {
// As in real files: bold-like toggles, a size, a picture anchor's length-prefixed sprm.
let text = b"\xC4\xE0\r";
for g in [&[0x55, 0x81, 0x63, 0x18, 0x00, 0x5D, 0x01, 0x00][..], &[0x75, 0x01, 0x44, 0x04, 0, 0, 0, 0, 0x5D, 0x01, 0x00][..]] {
let runs: &[(u32, u32, &[u8])] = &[(0, 2, g), (2, 3, &[])];
let d = Doc6 { text, fonts: FONTS, runs, ..Default::default() };
assert_eq!(texts(&d), ["Да"], "grpprl {g:02X?}");
}
}
#[test]
fn the_last_font_sprm_of_a_run_chooses_its_code_page() {
// Font 0, then font 1 (Cyrillic): the later sprm is the one the formatting applies.
let runs: &[(u32, u32, &[u8])] = &[(0, 2, &[0x5D, 0x00, 0x00, 0x5D, 0x01, 0x00]), (2, 3, &[])];
let d = Doc6 { text: b"\xC4\xE0\r", fonts: FONTS, runs, ..Default::default() };
assert_eq!(texts(&d), ["Да"]);
}
#[test]
fn an_unknown_sprm_leaves_font_0() {
// 0x99 has no known operand length, so the rest can't be framed: font 0 (Windows-1252).
let text = b"\xC4\xE0\r";
let runs: &[(u32, u32, &[u8])] = &[(0, 2, &[0x99, 0x5D, 0x01, 0x00]), (2, 3, &[])];
let d = Doc6 { text, fonts: FONTS, runs, ..Default::default() };
assert_eq!(texts(&d), ["Äà"]);
}
#[test]
fn the_toggle_sprms_before_the_font_are_framed() {
// 0x57 (strike, a one-byte toggle in [MS-DOC]'s Prm0 isprm table) before the font sprm: the
// font must still be found, or the Cyrillic text reads as Windows-1252.
let text = b"\xC4\xE0\r";
for op in [0x57, 0x58, 0x59, 0x5C] {
let g = [op, 0x01, 0x5D, 0x01, 0x00];
let runs: &[(u32, u32, &[u8])] = &[(0, 2, &g), (2, 3, &[])];
let d = Doc6 { text, fonts: FONTS, runs, ..Default::default() };
assert_eq!(texts(&d), ["Да"], "opcode 0x{op:02X}");
}
}
#[test]
fn a_font_entry_too_short_for_its_charset_ends_the_font_table() {
// Entry 0 says it is 3 bytes long, which can't hold the charset at offset 4. The bytes after
// it (the next entry, whose flags byte is 0xCC) must not be read as font 0's charset.
let raw: &[u8] = &[0x02, 0x16, 0x90, 0x05, 0xCC, 0x90, 0x01, 0xCC, 0x00, b'X', 0];
let d = Doc6 { text: b"\xC4\xE0\r", raw_fonts: Some(raw), runs: &[(0, 3, &[])], ..Default::default() };
assert_eq!(texts(&d), ["Äà"], "font 0 has no charset: Windows-1252");
}
#[test]
fn a_bin_table_naming_one_page_many_times_reads_it_once() {
// A hostile bin table: 1,000,000 entries, all naming one page of 50 Cyrillic runs. The text still
// reads right; that the page is read once is pinned in `word6::tests`.
let text: Vec<u8> = std::iter::repeat_n(0xC4u8, 50).chain(*b"\r").collect();
let g: &[u8] = &[0x5D, 0x01, 0x00];
let runs: Vec<(u32, u32, &[u8])> = (0..50).map(|i| (i, i + 1, g)).chain([(50, 51, &[][..])]).collect();
let mut w = word_stream(&Doc6 { text: &text, fonts: FONTS, runs: &runs, ..Default::default() });
let u32_at = |w: &[u8], at: usize| u32::from_le_bytes([w[at], w[at + 1], w[at + 2], w[at + 3]]);
let bte_fc = u32_at(&w, 0x58 + 12 * 8) as usize;
let pn = u16::from_le_bytes([w[bte_fc + 8], w[bte_fc + 9]]);
let n = 1_000_000usize;
let mut bte = Vec::with_capacity(4 * (n + 1) + 2 * n);
bte.extend_from_slice(&TEXT_AT.to_le_bytes());
for _ in 0..n {
bte.extend_from_slice(&(TEXT_AT + 51).to_le_bytes());
}
for _ in 0..n {
bte.extend_from_slice(&pn.to_le_bytes());
}
let at = w.len() as u32;
w.extend_from_slice(&bte);
put32(&mut w, 0x58 + 12 * 8, at);
put32(&mut w, 0x58 + 12 * 8 + 4, bte.len() as u32);
let doc = read(&cfb_file(&[("WordDocument", &w)])).expect("opens");
assert_eq!(body_texts(&doc), ["Д".repeat(50)]);
}
/// `s` as UTF-16LE bytes.
fn utf16(s: &str) -> Vec<u8> {
s.encode_utf16().flat_map(u16::to_le_bytes).collect()
}
#[test]
fn a_file_with_extended_characters_holds_utf16_text() {
// fExtChar (0x1000): Word reads the text as 16-bit units.
let text = utf16("Да ok\r");
let d = Doc6 { flags: 0x1000, text: &text, ccp: Some(6), ..Default::default() };
assert_eq!(texts(&d), ["Да ok"]);
}
#[test]
fn utf16_text_stops_at_the_end_of_its_bytes() {
// Word reads no more 16-bit characters than the text's byte range (0x18..0x1C) holds, even
// when the character count says more.
let text = utf16("Hi\r");
let d = Doc6 { flags: 0x1000, text: &text, ccp: Some(50), ..Default::default() };
assert_eq!(texts(&d), ["Hi"]);
}
#[test]
fn text_stops_at_the_end_of_its_bytes() {
// The same for 8-bit text: Word read 19 characters of a file whose count said 40. The font
// table after the text must not be read as body text.
let d = Doc6 { text: b"Hi\r", ccp: Some(50), fonts: FONTS, ..Default::default() };
assert_eq!(texts(&d), ["Hi"]);
}
#[test]
fn fast_saved_utf16_pieces_are_at_plain_byte_offsets() {
let text = utf16("World\rHello\r");
let d = Doc6 { flags: 0x1000, text: &text, pieces: Some(&[(6, 12), (6, 0)]), ..Default::default() };
assert_eq!(texts(&d), ["Hello", "World"]);
}
#[test]
fn a_macintosh_document_reads_as_mac_roman() {
// FIB 0x14 = 0x0100: byte 0x8E is "é" (Mac Roman), not "Ž" (Windows-1252), even in a run whose
// font is Cyrillic.
let runs: &[(u32, u32, &[u8])] = &[(0, 2, &[0x5D, 0x01, 0x00]), (2, 3, &[])];
let d = Doc6 { chse: 0x0100, text: b"H\x8E\r", fonts: FONTS, runs, ..Default::default() };
assert_eq!(texts(&d), ["Hé"]);
}
#[test]
fn a_symbol_document_maps_characters_to_private_use() {
// FIB 0x14 = 0x0002: every character from the space up is U+F000 + byte; marks stay marks.
let d = Doc6 { chse: 0x0002, text: b"Hi\x8E\rA\r", ..Default::default() };
assert_eq!(texts(&d), ["\u{F048}\u{F069}\u{F08E}", "\u{F041}"]);
}
#[test]
fn another_character_set_leaves_only_ascii_readable() {
let d = Doc6 { chse: 0x0001, text: b"H\x8Ei\r", ..Default::default() };
assert_eq!(texts(&d), ["H\u{FFFD}i"]);
}
#[test]
fn a_prm_on_the_marks_piece_formats_its_paragraph() {
// As Word 95 fast-saves a 1" left indent on the first paragraph: the piece holding its mark
// has Prm1 -> Prc `11 a0 05` (left indent 1440), and its PAPX says nothing. Word shows 72 pt;
// the second paragraph keeps none.
let text = b"First\rSecond\r";
let pieces: &[(u32, u32)] = &[(5, 0), (1, 5), (7, 6)];
let d = Doc6 { text, pieces: Some(pieces), prms: &[0, 0x0001], prcs: &[&[0x11, 0xA0, 0x05]], ..Default::default() };
let doc = read(&word6_file(&d)).expect("opens");
let paras: Vec<_> = doc.body.iter().filter_map(|b| b.as_para()).collect();
assert_eq!(paras.iter().map(|p| p.text.as_str()).collect::<Vec<_>>(), ["First", "Second"]);
assert_eq!((paras[0].props.indent_left, paras[1].props.indent_left), (Some(72.0), None));
}
#[test]
fn a_pieces_prm_formats_its_text() {
// As Word 95 fast-saves formatting: piece 0 has Prm1 -> a Prc setting font 1 and bold, which
// its character run doesn't. Piece 0 shows in font 1, bold (and decodes in its code page);
// piece 1 keeps the run's plain formatting.
let text = b"\xC4\xE0\xC4\xE0\r";
let d =
Doc6 { text, fonts: FONTS, pieces: Some(&[(2, 0), (3, 2)]), prms: &[0x0001], prcs: &[&[0x5D, 0x01, 0x00, 0x55, 0x01]], ..Default::default() };
let doc = read(&word6_file(&d)).expect("opens");
let p = first_para(&doc);
assert_eq!(p.text, "ДаÄà");
let first = &p.runs.first().expect("a run").props;
assert_eq!((first.font.as_deref(), first.bold), (Some("Times New Roman Cyr"), Some(true)));
let last = &p.runs.last().expect("a run").props;
assert_eq!((last.font.as_deref(), last.bold), (None, None));
}
#[test]
fn a_font_in_a_pieces_prm_chooses_its_code_page() {
// As Word 95 fast-saves a font change: piece 0 ("\xC4\xE0") has Prm1 -> Prc 0 = sprm 0x5D font 1
// (Cyrillic), while its character run names no font. Piece 1 keeps the run's font 0.
let text = b"\xC4\xE0\xC4\xE0\r";
let d = Doc6 { text, fonts: FONTS, pieces: Some(&[(2, 0), (3, 2)]), prms: &[0x0001], prcs: &[&[0x5D, 0x01, 0x00]], ..Default::default() };
assert_eq!(texts(&d), ["ДаÄà"]);
}
#[test]
fn a_prm_index_past_the_prcs_is_ignored() {
let d = Doc6 { text: b"\xC4\xE0\r", fonts: FONTS, pieces: Some(&[(3, 0)]), prms: &[0x0011], prcs: &[&[0x5D, 0x01, 0x00]], ..Default::default() };
assert_eq!(texts(&d), ["Äà"]);
}
#[test]
fn password_protected_files_are_refused() {
let d = Doc6 { flags: 0x0100, text: b"secret\r", ..Default::default() };
assert!(matches!(read(&word6_file(&d)), Err(DocbinError::Encryption(_))));
}
/// The first paragraph of `doc`'s body.
fn first_para(doc: &craft_wordmodel::Document) -> &craft_wordmodel::para::Paragraph {
doc.body.iter().find_map(|b| b.as_para()).expect("a paragraph")
}
#[test]
fn character_formatting_is_read() {
// Bold on, italic as the opposite of the (unread, so plain) style, 14 pt, red, single
// underline, font 2: the Word 6 opcodes as observed.
let g: &[u8] = &[0x55, 0x01, 0x56, 0x81, 0x63, 0x1C, 0x00, 0x62, 0x06, 0x5E, 0x01, 0x5D, 0x02, 0x00];
let runs: &[(u32, u32, &[u8])] = &[(0, 2, g), (2, 3, &[])];
let fonts = &[(0, "Times New Roman"), (2, "Symbol"), (0, "Arial")];
let doc = read(&word6_file(&Doc6 { text: b"Hi\r", fonts, runs, ..Default::default() })).expect("opens");
let p = first_para(&doc);
let c = &p.runs.first().expect("a run").props;
assert_eq!((c.bold, c.italic, c.size), (Some(true), Some(true), Some(14.0)));
assert_eq!(c.color, Some(craft_wordmodel::props::TextColor::Rgb(craft_wordmodel::props::Rgb(0xFF, 0, 0))));
assert_eq!(c.underline, Some(craft_wordmodel::props::Underline::Single));
assert_eq!(c.font.as_deref(), Some("Arial"));
}
#[test]
fn unseen_operand_values_are_left_unread() {
// Underline 3 and "multiple" line spacing were never seen in a real file, so they aren't
// guessed at.
let runs: &[(u32, u32, &[u8])] = &[(0, 3, &[0x5E, 0x03])];
let paras: &[(u32, u32, &[u8])] = &[(0, 3, &[0x14, 0xF0, 0x00, 0x01, 0x00])];
let doc = read(&word6_file(&Doc6 { text: b"Hi\r", runs, paras, ..Default::default() })).expect("opens");
let p = first_para(&doc);
assert_eq!(p.runs.first().and_then(|r| r.props.underline), None);
assert_eq!(p.props.line_spacing, None);
}
#[test]
fn an_unseen_alignment_value_is_left_unread() {
// Only 0-3 were seen; 4 would otherwise become "distribute" and 0xFF "left".
for jc in [0x04u8, 0xFF] {
let g = [0x05, jc];
let paras: &[(u32, u32, &[u8])] = &[(0, 3, &g)];
let doc = read(&word6_file(&Doc6 { text: b"Hi\r", paras, ..Default::default() })).expect("opens");
assert_eq!(first_para(&doc).props.align, None, "jc {jc:#04x}");
}
}
#[test]
fn paragraph_formatting_is_read() {
// Justified, 0.5" left and 0.25" right indents, a 0.5" hanging first line, at least 27 pt.
let g: &[u8] = &[0x05, 0x03, 0x11, 0xD0, 0x02, 0x10, 0x68, 0x01, 0x13, 0x30, 0xFD, 0x14, 0x1C, 0x02, 0x00, 0x00];
let paras: &[(u32, u32, &[u8])] = &[(0, 3, g), (3, 6, &[0x05, 0x01])];
let doc = read(&word6_file(&Doc6 { text: b"Hi\rHo\r", paras, ..Default::default() })).expect("opens");
let ps: Vec<_> = doc.body.iter().filter_map(|b| b.as_para()).collect();
let p = &ps[0].props;
assert_eq!(p.align, Some(craft_wordmodel::props::Align::Justify));
assert_eq!((p.indent_left, p.indent_right, p.indent_first), (Some(36.0), Some(18.0), Some(-36.0)));
assert_eq!(p.line_spacing, Some(craft_wordmodel::props::LineSpacing::AtLeast(27.0)));
assert_eq!(ps[1].props.align, Some(craft_wordmodel::props::Align::Center));
}
/// A Word 6 table definition sprm (0xBE): the cell edges, then a 10-byte descriptor per cell
/// whose first word holds the merge flags.
fn def_table(edges: &[i16], rgfs: &[u16]) -> Vec<u8> {
let mut rest = vec![rgfs.len() as u8];
for e in edges {
rest.extend_from_slice(&e.to_le_bytes());
}
for r in rgfs {
rest.extend_from_slice(&r.to_le_bytes());
rest.extend_from_slice(&[0; 8]);
}
let mut v = vec![0xBE];
v.extend_from_slice(&((rest.len() + 1) as u16).to_le_bytes());
v.extend_from_slice(&rest);
v
}
/// The rows of the first table in `doc`'s body, each as its cells' texts.
fn table_rows(doc: &craft_wordmodel::Document) -> Vec<Vec<String>> {
let t = doc.body.iter().find_map(|b| match b.as_ref() {
craft_wordmodel::Block::Table(t) => Some(t),
_ => None,
});
let t = t.expect("a table");
t.rows
.iter()
.map(|r| r.cells.iter().map(|c| c.blocks.iter().filter_map(|b| b.as_para()).map(|p| p.text.clone()).collect::<Vec<_>>().join("|")).collect())
.collect()
}
#[test]
fn table_rows_and_merged_cells_are_read() {
// Row 1: "A", "B". Row 2: "C" merged across both cells. In-table marks carry 0x18, the row
// ends 0x18, 0x19 and the table definition.
let text = b"A\x07B\x07\x07C\x07\x07\x07after\r";
let mut row1 = vec![0x18, 1, 0x19, 1];
row1.extend(def_table(&[0, 1440, 2880], &[0, 0]));
let mut row2 = vec![0x18, 1, 0x19, 1];
row2.extend(def_table(&[0, 1440, 2880], &[0x0001, 0x0002]));
let cell: &[u8] = &[0x18, 1];
let paras: &[(u32, u32, &[u8])] = &[(0, 2, cell), (2, 4, cell), (4, 5, &row1), (5, 7, cell), (7, 8, cell), (8, 9, &row2), (9, 15, &[])];
let doc = read(&word6_file(&Doc6 { text, paras, ..Default::default() })).expect("opens");
assert_eq!(table_rows(&doc), [vec!["A", "B"], vec!["C"]]);
assert_eq!(body_texts(&doc), ["after"], "the paragraph after the table stays outside it");
}
#[test]
fn several_merges_in_one_row_each_keep_their_cells() {
// Five cells merged as [A B] [C] [D E]: the second merge must not be shifted by the first.
let text = b"A\x07B\x07C\x07D\x07E\x07\x07";
let mut row = vec![0x18, 1, 0x19, 1];
row.extend(def_table(&[0, 100, 200, 300, 400, 500], &[0x0001, 0x0002, 0x0000, 0x0001, 0x0002]));
let cell: &[u8] = &[0x18, 1];
let paras: &[(u32, u32, &[u8])] = &[(0, 2, cell), (2, 4, cell), (4, 6, cell), (6, 8, cell), (8, 10, cell), (10, 11, &row)];
let doc = read(&word6_file(&Doc6 { text, paras, ..Default::default() })).expect("opens");
assert_eq!(table_rows(&doc), [vec!["A|B", "C", "D|E"]]);
}
#[test]
fn a_field_shows_its_cached_result() {
let d = Doc6 { text: b"Date \x13DATE \x1412/12/97\x15\r", ..Default::default() };
let text = read(&word6_file(&d)).expect("opens").plain_text(craft_wordmodel::StoryRef::Body);
assert!(text.contains("Date 12/12/97"), "{text:?}");
assert!(!text.contains("DATE"), "{text:?}");
}
/// A fixture's paragraph styles: Normal, an empty slot, then "Mine" (user-defined, centred, bold, on
/// Normal) and "Heading" stored under a local name with sti 1.
const STYLES: &[Option<Std>] = &[
Some(Std { sti: 0, sgc: 1, base: 0x0FFF, name: "Standard", papx: &[], chpx: &[0x61, 0x09, 0x04] }),
None,
Some(Std { sti: 0x0FFE, sgc: 1, base: 0, name: "Mine", papx: &[0x05, 0x01], chpx: &[0x55, 0x01] }),
Some(Std { sti: 1, sgc: 1, base: 0, name: "Überschrift 1", papx: &[0x08, 0x01], chpx: &[0x55, 0x81, 0x63, 0x20, 0x00] }),
];
/// Each paragraph's style name, through the document's style sheet.
fn style_names(doc: &craft_wordmodel::Document) -> Vec<String> {
doc.body
.iter()
.filter_map(|b| b.as_para())
.map(|p| p.props.style.as_deref().and_then(|id| doc.styles.get(id)).map_or(String::new(), |s| s.name.clone()))
.collect()
}
#[test]
fn paragraphs_take_their_styles() {
let paras: &[(u32, u32, &[u8])] = &[(0, 2, &[]), (2, 4, &[]), (4, 6, &[])];
let d = Doc6 { text: b"A\rB\rC\r", paras, para_styles: &[0, 2, 3], styles: STYLES, ..Default::default() };
let doc = read(&word6_file(&d)).expect("opens");
// A built-in style goes by its built-in name, whatever the file stores (as in Word).
assert_eq!(style_names(&doc), ["Normal", "Mine", "Heading 1"]);
}
#[test]
fn styles_carry_their_formatting_and_base() {
let d = Doc6 { text: b"A\r", styles: STYLES, ..Default::default() };
let doc = read(&word6_file(&d)).expect("opens");
let mine = doc.styles.styles.iter().find(|s| s.name == "Mine").expect("Mine");
assert_eq!(mine.para.align, Some(craft_wordmodel::props::Align::Center));
assert_eq!(mine.chr.bold, Some(true));
assert_eq!(mine.based_on.as_deref().and_then(|id| doc.styles.get(id)).map(|s| s.name.as_str()), Some("Normal"));
let heading = doc.styles.styles.iter().find(|s| s.name == "Heading 1").expect("Heading 1");
assert_eq!((heading.para.keep_next, heading.chr.size), (Some(true), Some(16.0)));
}
#[test]
fn bulleted_styles_frame_past_their_numbering() {
// 0x0D (1 byte) and 0x0C (a count byte and its bytes) before the indents, as in the corpus.
let mut papx = vec![0x05, 0x03, 0x0D, 0x0B, 0x11, 0x1C, 0x01, 0x13, 0xE4, 0xFE, 0x0C, 4, 0xFF, 0x01, 0x00, 0x08];
papx.extend_from_slice(&[0x0E, 0x01, 0x2C, 0x00, 0x1D, 0x60, 0x1A, 0xF8, 0xFF, 0x25, 0x02, 0x10, 0x68, 0x01]);
let styles = &[Some(Std { sgc: 1, base: 0x0FFF, name: "Normal", papx: &papx, ..Default::default() })];
let doc = read(&word6_file(&Doc6 { text: b"A\r", styles, ..Default::default() })).expect("opens");
let normal = doc.styles.get("Normal").expect("Normal");
assert_eq!((normal.para.indent_left, normal.para.indent_first, normal.para.indent_right), (Some(14.2), Some(-14.2), Some(18.0)));
}
#[test]
fn a_runs_language_or_its_styles_chooses_the_code_page_without_a_font() {
// No font named anywhere: the style's language decides (Russian -> Windows-1251), as in Word.
let styles = &[Some(Std { sgc: 1, base: 0x0FFF, name: "Normal", chpx: &[0x61, 0x19, 0x04], ..Default::default() })];
let d = Doc6 { text: b"\xC4\xE0\r", fonts: FONTS, styles, ..Default::default() };
assert_eq!(texts(&d), ["Да"]);
// The run's own language outranks the style's.
let runs: &[(u32, u32, &[u8])] = &[(0, 3, &[0x61, 0x09, 0x04])];
let d = Doc6 { text: b"\xC4\xE0\r", fonts: FONTS, styles, runs, ..Default::default() };
assert_eq!(texts(&d), ["Äà"]);
}
#[test]
fn font_0_is_not_a_fallback() {
// Font 0 is Cyrillic, but nothing names it and the style's language is English: Word reads
// Windows-1252.
let fonts = &[(204, "Times New Roman Cyr"), (0, "Arial")];
let styles = &[Some(Std { sgc: 1, base: 0x0FFF, name: "Normal", chpx: &[0x61, 0x09, 0x04], ..Default::default() })];
// A character run that names no font (where the reader used to take font 0).
let runs: &[(u32, u32, &[u8])] = &[(0, 3, &[])];
let d = Doc6 { text: b"\xC4\xE0\r", fonts, styles, runs, ..Default::default() };
assert_eq!(texts(&d), ["Äà"]);
}
#[test]
fn a_font_named_in_the_style_chooses_the_code_page() {
// The base style names the Cyrillic font 1; the run and its own style name none.
let styles = &[
Some(Std { sgc: 1, base: 0x0FFF, name: "Normal", chpx: &[0x5D, 0x01, 0x00], ..Default::default() }),
Some(Std { sti: 0x0FFE, sgc: 1, base: 0, name: "Child", ..Default::default() }),
];
let paras: &[(u32, u32, &[u8])] = &[(0, 3, &[])];
let d = Doc6 { text: b"\xC4\xE0\r", fonts: FONTS, styles, paras, para_styles: &[1], ..Default::default() };
assert_eq!(texts(&d), ["Да"]);
}
#[test]
fn an_ansi_font_leaves_the_code_page_to_the_language() {
// Arial (ANSI) named on the run, the style's language Russian: Word reads Cyrillic.
let fonts = &[(0, "Times New Roman"), (0, "Arial")];
let styles = &[Some(Std { sgc: 1, base: 0x0FFF, name: "Normal", chpx: &[0x61, 0x19, 0x04], ..Default::default() })];
let runs: &[(u32, u32, &[u8])] = &[(0, 2, &[0x5D, 0x01, 0x00]), (2, 3, &[])];
let d = Doc6 { text: b"\xC4\xE0\r", fonts, styles, runs, ..Default::default() };
assert_eq!(texts(&d), ["Да"]);
}
/// A fixture with every structure read: runs, fonts and a piece table.
fn full_stream() -> Vec<u8> {
let runs: &[(u32, u32, &[u8])] = &[(0, 6, &[0x55, 0x81]), (6, 9, &[0x5D, 0x01, 0x00]), (9, 12, &[])];
let styles = &[
Some(Std { sgc: 1, base: 0x0FFF, name: "Normal", chpx: &[0x61, 0x09, 0x04], ..Default::default() }),
None,
Some(Std { sti: 0x0FFE, sgc: 1, base: 0, name: "Mine", papx: &[0x05, 0x01], chpx: &[0x55, 0x01] }),
];
let paras: &[(u32, u32, &[u8])] = &[(0, 6, &[]), (6, 12, &[])];
word_stream(&Doc6 {
text: b"Hello\r\xC4\xE0\rx\r\r",
fonts: FONTS,
runs,
paras,
para_styles: &[2, 0],
styles,
pieces: Some(&[(6, 0), (6, 6)]),
..Default::default()
})
}
#[test]
fn the_full_fixture_reads() {
let f = cfb_file(&[("WordDocument", &full_stream())]);
let doc = read(&f).expect("opens");
assert_eq!(body_texts(&doc), ["Hello", "Да", "x", ""]);
assert_eq!(style_names(&doc)[0], "Mine");
}
proptest! {
#![proptest_config(ProptestConfig::with_cases(256))]
#[test]
fn corrupt_word6_streams_never_panic(edits in proptest::collection::vec((0..0x700usize, any::<u8>()), 1..16)) {
let mut w = full_stream();
for (at, b) in edits {
if let Some(x) = w.get_mut(at) {
*x = b;
}
}
let _ = read(&cfb_file(&[("WordDocument", &w)]));
}
#[test]
fn truncated_word6_streams_never_panic(n in 0..0x700usize) {
let w = full_stream();
let _ = read(&cfb_file(&[("WordDocument", &w[..n.min(w.len())])]));
}
}
+842
View File
@@ -0,0 +1,842 @@
//! Word 6.0 and Word 95 `.doc` files (`wIdent` 0xA5DC, `nFib` 0x0065 and 0x0068).
//!
//! No public specification describes this version: [MS-DOC] covers Word 97 and later. Everything
//! here is observed, from the layout of real files checked against what Word shows when it opens
//! them (its text through COM, its formatting in the `.docx` Word saves from them), plus the Word
//! 97 structures in [MS-DOC] that these files visibly share. Nothing else is assumed.
//!
//! What is read: the main text, its paragraphs and fields, the code page of each run, the
//! character and paragraph formatting listed below, table rows, and the paragraph styles (with
//! their formatting). Character styles, sections, headers and footers, notes, pictures, borders,
//! shading and tabs are not read yet.
//!
//! The layout as observed:
//!
//! - A compound file with a `WordDocument` stream and **no Table stream**: the structures that
//! Word 97 keeps in `0Table`/`1Table` live in the WordDocument stream itself.
//! - The FIB is one fixed block. The flags at 0x0A have the Word 97 meaning for bit 2 (fast-saved,
//! set exactly in the files that carry a piece table) and, as far as can be told, bit 8
//! (encrypted). The text starts at the u32 at 0x18, and the main text's length in characters is
//! the u32 at 0x34.
//! - From 0x58, (u32 fc, u32 lcb) pairs, in the order of Word 97's `FibRgFcLcb97`. Index 12 is the
//! character bin table, 13 the paragraph bin table, 15 the font table and 33 the piece table.
//! - Text is one byte per character, in the code page of the font of its run. The FIB's language
//! does not choose it: files marked English hold Russian and Czech text that Word shows as such.
//! - Both bin tables hold 2-byte page numbers (Word 97: 4 bytes). The FKP pages have the Word 97
//! layout, except that a paragraph page's entries are 7 bytes (an offset byte and 6 more; Word
//! 97: 13), and a PAPX is a count of 2-byte words followed by exactly that many words: the
//! 2-byte style index, then the grpprl (padded with one 0 byte to whole words).
//! - Sprms have **1-byte opcodes**. Those with a 1-byte operand match the opcodes [MS-DOC]'s
//! `Prm0` table lists for the same properties (bold 0x55, colour 0x62, in-table 0x18…); the
//! others were identified against Word. See [`chp`] and [`pap`].
//! - A font table entry is a size byte (the entry's length − 1), a flags byte, a 2-byte weight, the
//! charset byte, one more byte, then the name in 8-bit characters.
//! - The stylesheet (pair 1) has the Word 97 shape with smaller parts: a u16 header size (14),
//! then a header of that many bytes whose first two words are the style count and the size of
//! a style's fixed part (8, Word 97: 10);
//! then per style a u16 size (0: an empty slot) and that many bytes: the fixed part (sti, then
//! kind and base style, then UPX count and next style, then a size), the name (a length byte,
//! 8-bit characters, a 0), and the UPXs, each a u16 size and its bytes, padded to even. A
//! paragraph style's first UPX is its style index and paragraph sprms, the second its character
//! sprms; a character style has one, its character sprms.
use craft_codepage::charset_code_page;
use crate::DocbinError;
use crate::fkp::{Bins, TranslatedRun};
use crate::piece::{CodePageRun, PieceTable, SYMBOL_CODE_PAGE, Word6Text};
use crate::stsh::RawStyle;
/// `wIdent` of a Word 6.0/95 file.
const W_IDENT: u16 = 0xA5DC;
const OFF_FLAGS: usize = 0x0A;
/// Fast-saved: the text is in pieces listed by a piece table.
const F_COMPLEX: u16 = 0x0004;
/// Password-protected (Word 97's bit; no unprotected file sets it).
const F_ENCRYPTED: u16 = 0x0100;
/// Word 97's `fExtChar` bit. Word reads a Word 6.0/95 file that sets it as UTF-16 text (each
/// piece's fc a plain byte offset), and so does this reader.
const F_EXT_CHAR: u16 = 0x1000;
/// The document's character set (u16): 0 Windows, 0x0100 Macintosh (all 8-bit text is Mac Roman,
/// whatever the fonts say), 0x0002 Symbol (every byte a private-use character). Word reads the
/// bytes above ASCII of any other value as U+FFFD.
const OFF_CHSE: usize = 0x14;
const OFF_FC_MAC: usize = 0x1C;
/// Bin table entries read, as for Word 97 (`fkp::MAX_BINS`).
const MAX_BINS: usize = 100_000;
/// FKP runs read (character or paragraph): far more than any real file's, and few enough to stay small.
const MAX_RUNS: usize = 1_000_000;
const OFF_FC_MIN: usize = 0x18;
const OFF_CCP_TEXT: usize = 0x34;
const OFF_PAIRS: usize = 0x58;
/// Pairs read: up to and including the piece table's.
const PAIRS: usize = 34;
const PAIR_STSH: usize = 1;
const PAIR_BTE_CHPX: usize = 12;
const PAIR_BTE_PAPX: usize = 13;
const PAIR_FONTS: usize = 15;
const PAIR_CLX: usize = 33;
/// More characters than Word's own documents get near: the FIB is corrupt (as for Word 97).
const MAX_CCP: u32 = 100_000_000;
/// The font table's entries: more than any real file has.
const MAX_FONTS: usize = 0x1_0000;
/// FKP page size in bytes.
const PAGE: usize = 512;
/// Size of a paragraph FKP entry (offset byte + 6).
const PAPX_BX: usize = 7;
/// Most cells a row's table definition is read for (the model's own cap is 63).
const MAX_CELLS: usize = 63;
/// Styles read: style indexes stop below 0x0FFF ("no style").
const MAX_STYLES: usize = 0x0FFE;
/// Base-style links followed when a style inherits a font or language.
const MAX_STYLE_DEPTH: usize = 16;
/// Character sprms read, by Word 6.0/95 opcode. Each one was matched against Word's own reading of
/// the corpus files (the `.docx` it saves from them).
mod chp {
/// Bold, a toggle (0 off, 1 on, 0x80 as the style, 0x81 the opposite of the style).
pub(super) const BOLD: u8 = 0x55;
/// Italic, a toggle.
pub(super) const ITALIC: u8 = 0x56;
/// Small capitals, a toggle.
pub(super) const SMALL_CAPS: u8 = 0x5A;
/// All capitals, a toggle.
pub(super) const CAPS: u8 = 0x5B;
/// The font: a 2-byte index into the font table.
pub(super) const FONT: u8 = 0x5D;
/// Underline: 0 none, 1 single (the only values seen).
pub(super) const UNDERLINE: u8 = 0x5E;
/// Colour: an index into Word's 16-colour palette, as Word 97's `Ico`.
pub(super) const COLOR: u8 = 0x62;
/// Size in half-points (2 bytes).
pub(super) const SIZE: u8 = 0x63;
/// The language (2 bytes, a Windows LCID): with no non-ANSI font, it gives the code page.
pub(super) const LID: u8 = 0x61;
}
/// Paragraph and table sprms read, by Word 6.0/95 opcode, matched like [`chp`]'s.
mod pap {
/// Alignment: 0 left, 1 centred, 2 right, 3 justified.
pub(super) const JC: u8 = 0x05;
/// Keep with the next paragraph (1 byte; on the heading styles H1-H6, which Word shows with
/// keepNext; [MS-DOC]'s isprm table has sprmPFKeepFollow at 0x08).
pub(super) const KEEP_NEXT: u8 = 0x08;
/// Right indent in twips (signed, 2 bytes).
pub(super) const RIGHT: u8 = 0x10;
/// Left indent in twips.
pub(super) const LEFT: u8 = 0x11;
/// First-line indent in twips, relative to the left one (negative: hanging).
pub(super) const FIRST: u8 = 0x13;
/// Line spacing: the 4-byte Word 97 `LSPD` (dyaLine, fMultLinespace).
pub(super) const LINE: u8 = 0x14;
/// The paragraph is in a table.
pub(super) const IN_TABLE: u8 = 0x18;
/// The mark ends a table row.
pub(super) const TTP: u8 = 0x19;
/// Row alignment (2 bytes): 1 centred.
pub(super) const ROW_JC: u8 = 0xB6;
/// Row height in twips (signed, 2 bytes): positive at least, negative exactly.
pub(super) const ROW_HEIGHT: u8 = 0xBD;
/// The row's cells: u16 count, cell count, (count + 1) i16 cell edges, then a 10-byte
/// descriptor per cell whose first word's bit 0 starts a horizontal merge and bit 1 continues
/// it.
pub(super) const DEF_TABLE: u8 = 0xBE;
}
/// Word 97 opcodes the translations produce ([MS-DOC] §2.6).
mod w97 {
pub(super) const C_BOLD: u16 = 0x0835;
pub(super) const C_ITALIC: u16 = 0x0836;
pub(super) const C_SMALL_CAPS: u16 = 0x083A;
pub(super) const C_CAPS: u16 = 0x083B;
pub(super) const C_KUL: u16 = 0x2A3E;
pub(super) const C_ICO: u16 = 0x2A42;
pub(super) const C_HPS: u16 = 0x4A43;
pub(super) const C_FTC0: u16 = 0x4A4F;
pub(super) const P_JC80: u16 = 0x2403;
pub(super) const P_KEEP_FOLLOW: u16 = 0x2406;
pub(super) const P_DXA_RIGHT80: u16 = 0x840E;
pub(super) const P_DXA_LEFT80: u16 = 0x840F;
pub(super) const P_DXA_LEFT1_80: u16 = 0x8411;
pub(super) const P_DYA_LINE: u16 = 0x6412;
pub(super) const P_IN_TABLE: u16 = 0x2416;
pub(super) const P_TTP: u16 = 0x2417;
pub(super) const T_JC: u16 = 0x5400;
pub(super) const T_ROW_HEIGHT: u16 = 0x9407;
pub(super) const T_DEF_TABLE: u16 = 0xD608;
pub(super) const T_MERGE: u16 = 0x5624;
}
/// Is this WordDocument stream a Word 6.0/95 one?
pub(crate) fn is_word6(word: &[u8]) -> bool {
word.get(0..2) == Some(&W_IDENT.to_le_bytes()[..])
}
/// The fields of a Word 6.0/95 FIB that are read.
#[derive(Clone, Debug)]
pub(crate) struct Fib6 {
complex: bool,
/// Text is UTF-16 (fExtChar).
wide: bool,
chse: u16,
fc_min: u32,
fc_mac: u32,
/// Characters in the main text.
pub(crate) ccp_text: u32,
pairs: [(u32, u32); PAIRS],
}
impl Fib6 {
pub(crate) fn parse(word: &[u8]) -> Result<Fib6, DocbinError> {
let u16_at = |at: usize| word.get(at..at + 2).map(|b| u16::from_le_bytes([b[0], b[1]]));
let u32_at = |at: usize| word.get(at..at + 4).map(|b| u32::from_le_bytes([b[0], b[1], b[2], b[3]]));
if word.len() < OFF_PAIRS + PAIRS * 8 {
return Err(DocbinError::NotWord(format!("Word 6.0/95 WordDocument stream is {} bytes", word.len())));
}
let flags = u16_at(OFF_FLAGS).unwrap_or(0);
if flags & F_ENCRYPTED != 0 {
return Err(DocbinError::Encryption("password-protected Word 6.0/95 files can't be opened".into()));
}
let ccp_text = u32_at(OFF_CCP_TEXT).unwrap_or(0);
if ccp_text > MAX_CCP {
return Err(DocbinError::Limit(format!("document claims {ccp_text} characters")));
}
let mut pairs = [(0, 0); PAIRS];
for (i, p) in pairs.iter_mut().enumerate() {
let at = OFF_PAIRS + i * 8;
*p = (u32_at(at).unwrap_or(0), u32_at(at + 4).unwrap_or(0));
}
Ok(Fib6 {
complex: flags & F_COMPLEX != 0,
wide: flags & F_EXT_CHAR != 0,
chse: u16_at(OFF_CHSE).unwrap_or(0),
fc_min: u32_at(OFF_FC_MIN).unwrap_or(0),
fc_mac: u32_at(OFF_FC_MAC).unwrap_or(0),
ccp_text,
pairs,
})
}
/// The (fc, lcb) pair at index `i`, if it points at anything.
fn pair(&self, i: usize) -> Option<(u32, u32)> {
self.pairs.get(i).copied().filter(|&(_, lcb)| lcb > 0)
}
}
/// Everything the walk needs from a Word 6.0/95 file besides its text stream.
pub(crate) struct Content {
pub(crate) pieces: PieceTable,
/// Character formatting, translated to Word 97 grpprls.
pub(crate) chpx: Bins,
/// Paragraph formatting and table rows, translated to Word 97 grpprls.
pub(crate) papx: Bins,
/// Font names by index (the walk resolves translated font sprms against them).
pub(crate) fonts: Vec<String>,
/// The styles by index, their formatting translated to Word 97 grpprls.
pub(crate) styles: Vec<RawStyle>,
}
/// Read the text, formatting and fonts of a Word 6.0/95 file.
///
/// 8-bit text decodes, as Word does, in the code page of: the document's character set when it
/// isn't Windows ([`OFF_CHSE`]); else the font a piece's Prm names (as Word 95 writes when a fast
/// save changes a font) when its charset has a code page; else, the same for the font of the
/// character run, or the one its paragraph style (or a base of it) names; else the language of
/// the run, or of its paragraph style; else Windows-1252. A font is only one named somewhere:
/// font 0 is not a fallback, and a font with the ANSI charset leaves the choice to the language.
pub(crate) fn content(word: &[u8], fib: &Fib6) -> Result<Content, DocbinError> {
let fonts = fib.pair(PAIR_FONTS).map(|(fc, lcb)| font_table(word, fc, lcb)).unwrap_or_default();
let chp_runs = fib.pair(PAIR_BTE_CHPX).map(|(fc, lcb)| fkp_runs(word, fc, lcb, false)).unwrap_or_default();
let pap_runs = fib.pair(PAIR_BTE_PAPX).map(|(fc, lcb)| fkp_runs(word, fc, lcb, true)).unwrap_or_default();
let (styles, facts) = fib.pair(PAIR_STSH).map(|(fc, lcb)| stylesheet(word, fc, lcb)).unwrap_or_default();
let windows = fib.chse == 0;
let default_code_page = match fib.chse {
// Text that no run covers is formatted by the Normal style.
0 => text_code_page(&fonts, &facts, 0, None, None),
0x0100 => MAC_ROMAN,
0x0002 => SYMBOL_CODE_PAGE,
// Not a code page: bytes above ASCII read as U+FFFD.
_ => 0,
};
let code_pages = if windows { code_page_runs(&chp_runs, &pap_runs, &facts, &fonts, default_code_page) } else { Vec::new() };
// shortcut: East Asian (lead and trail byte) text is refused, as all Word 6.0/95 files were
// before; read it a character at a time when the piece walk can decode byte pairs.
let east_asian = || DocbinError::NotWord("Word 6.0/95 text in an East Asian code page is not read yet".into());
if craft_codepage::is_multibyte_code_page(default_code_page) || code_pages.iter().any(|r| craft_codepage::is_multibyte_code_page(r.code_page)) {
return Err(east_asian());
}
let multibyte_piece = std::cell::Cell::new(false);
let text = Word6Text { wide: fib.wide, default_code_page, code_pages };
let pieces = if fib.complex {
let (fc, lcb) = fib.pair(PAIR_CLX).ok_or_else(|| DocbinError::Malformed("the fast-saved file has no piece table".into()))?;
// A Prm1's Prc may name the piece's font (sprm 0x5D); a Prm0 can't, its operand being one
// byte.
let piece_code_page = |prm: u16, prcs: &[Vec<u8>]| -> Option<u16> {
if !windows || prm & 1 == 0 {
return None;
}
let cp = last_font(prcs.get(usize::from(prm >> 1))?).and_then(|f| font_code_page(&fonts, f));
if cp.is_some_and(craft_codepage::is_multibyte_code_page) {
multibyte_piece.set(true);
}
cp
};
// The Prcs then carry Word 97 sprms, as the CHPXs and PAPXs do: the walk applies their
// character sprms to the piece's text and their paragraph sprms to the paragraph whose mark
// the piece holds.
let table = PieceTable::parse_word6(word, fc, lcb, text, piece_code_page, translate_prc)?;
if multibyte_piece.get() {
return Err(east_asian());
}
table
} else {
// Word reads no more characters than the text's byte range (fcMin..fcMac) holds, one byte
// each or two for UTF-16, whatever the character count says.
let unit = if fib.wide { 2 } else { 1 };
let ccp = fib.ccp_text.min(fib.fc_mac.saturating_sub(fib.fc_min) / unit);
PieceTable::contiguous_word6(fib.fc_min, ccp, text)
};
let chpx = Bins::translated(chp_runs.iter().map(|r| TranslatedRun { lo: r.lo, hi: r.hi, istd: 0, grpprl: translate_chp(r.grpprl) }).collect());
let papx =
Bins::translated(pap_runs.iter().map(|r| TranslatedRun { lo: r.lo, hi: r.hi, istd: r.istd, grpprl: translate_pap(r.grpprl) }).collect());
Ok(Content { pieces, chpx, papx, fonts: fonts.into_iter().map(|f| f.name).collect(), styles })
}
/// Mac OS Roman, the 8-bit text of a Macintosh Word document.
const MAC_ROMAN: u16 = craft_codepage::MAC_ROMAN_CODE_PAGE;
/// The code page of font `font`'s charset, if it has one (not for ANSI, default or symbol
/// charsets, whose text Word decodes by its language).
fn font_code_page(fonts: &[Font], font: u16) -> Option<u16> {
fonts.get(usize::from(font)).and_then(|f| charset_code_page(i32::from(f.charset)))
}
/// Windows' ANSI code page for the language `lid` (an LCID), which Word uses for 8-bit text in a
/// font without a charset of its own. Russian (1251) and English (1252) were checked against Word;
/// the rest is the standard Windows assignment.
fn lid_code_page(lid: u16) -> u16 {
match lid & 0x03FF {
// Serbian in Cyrillic (0x0C1A, 0x1C1A); Croatian and Serbian in Latin otherwise.
0x1A => match lid {
0x0C1A | 0x1C1A => 1251,
_ => 1250,
},
0x02 | 0x19 | 0x22 | 0x23 | 0x2F | 0x3F | 0x40 | 0x44 | 0x50 => 1251,
0x05 | 0x0E | 0x15 | 0x18 | 0x1B | 0x1C | 0x24 => 1250,
0x08 => 1253,
0x1F => 1254,
0x0D => 1255,
0x01 | 0x20 | 0x29 => 1256,
0x25..=0x27 => 1257,
0x2A => 1258,
0x1E => 874,
0x11 => 932,
0x12 => 949,
0x04 => match lid {
0x0804 | 0x1004 => 936,
_ => 950,
},
_ => 1252,
}
}
/// A style's own font and language sprms and its base, for inheritance ([`StyleFacts::resolve`]).
#[derive(Clone, Copy, Debug, Default)]
struct StyleFacts {
base: u16,
font: Option<u16>,
lid: Option<u16>,
}
impl StyleFacts {
/// Style `istd`'s font and language, each from the style itself or the nearest base that has
/// one.
fn resolve(facts: &[StyleFacts], istd: u16) -> (Option<u16>, Option<u16>) {
let (mut font, mut lid) = (None, None);
let mut at = istd;
for _ in 0..MAX_STYLE_DEPTH {
let Some(f) = facts.get(usize::from(at)) else { break };
font = font.or(f.font);
lid = lid.or(f.lid);
if font.is_some() && lid.is_some() {
break;
}
at = f.base;
}
(font, lid)
}
}
/// The styles of the stylesheet at `word[fc..fc+lcb]`, by index (an empty slot is a default
/// style, which keeps the indexes aligned), with their formatting translated, and each style's
/// own font and language. Reading stops at the first entry that runs past the table.
fn stylesheet(word: &[u8], fc: u32, lcb: u32) -> (Vec<RawStyle>, Vec<StyleFacts>) {
let Some(st) = (fc as usize).checked_add(lcb as usize).and_then(|end| word.get(fc as usize..end)) else { return Default::default() };
let u16_at = |b: &[u8], at: usize| b.get(at..at + 2).map(|x| u16::from_le_bytes([x[0], x[1]]));
let Some(cb_header) = u16_at(st, 0).map(usize::from) else { return Default::default() };
let (Some(cstd), Some(cb_base)) = (u16_at(st, 2), u16_at(st, 4)) else { return Default::default() };
let cb_base = usize::from(cb_base);
let (mut styles, mut facts) = (Vec::new(), Vec::new());
let mut at = 2 + cb_header;
for _ in 0..usize::from(cstd).min(MAX_STYLES) {
let Some(cb) = u16_at(st, at).map(usize::from) else { break };
let Some(std) = st.get(at + 2..at + 2 + cb) else { break };
at += 2 + cb;
let (style, fact) = style(std, cb_base).unwrap_or_else(|| (RawStyle::default(), StyleFacts { base: 0x0FFF, ..Default::default() }));
styles.push(style);
facts.push(fact);
}
(styles, facts)
}
/// The names of the built-in styles by sti: the "Index within built-in styles" of the reserved
/// style names in [MS-OE376] (Part 4 §2.7.3.9), which [MS-DOC]'s StdfBase says sti is. 0x0FFE
/// (user-defined) and anything past the table keep the name stored in the file.
const BUILT_IN_NAMES: [&str; 107] = [
"Normal",
"heading 1",
"heading 2",
"heading 3",
"heading 4",
"heading 5",
"heading 6",
"heading 7",
"heading 8",
"heading 9",
"index 1",
"index 2",
"index 3",
"index 4",
"index 5",
"index 6",
"index 7",
"index 8",
"index 9",
"toc 1",
"toc 2",
"toc 3",
"toc 4",
"toc 5",
"toc 6",
"toc 7",
"toc 8",
"toc 9",
"Normal Indent",
"footnote text",
"annotation text",
"header",
"footer",
"index heading",
"caption",
"table of figures",
"envelope address",
"envelope return",
"footnote reference",
"annotation reference",
"line number",
"page number",
"endnote reference",
"endnote text",
"table of authorities",
"macro",
"toa heading",
"List",
"List Bullet",
"List Number",
"List 2",
"List 3",
"List 4",
"List 5",
"List Bullet 2",
"List Bullet 3",
"List Bullet 4",
"List Bullet 5",
"List Number 2",
"List Number 3",
"List Number 4",
"List Number 5",
"Title",
"Closing",
"Signature",
"Default Paragraph Font",
"Body Text",
"Body Text Indent",
"List Continue",
"List Continue 2",
"List Continue 3",
"List Continue 4",
"List Continue 5",
"Message Header",
"Subtitle",
"Salutation",
"Date",
"Body Text First Indent",
"Body Text First Indent 2",
"Note Heading",
"Body Text 2",
"Body Text 3",
"Body Text Indent 2",
"Body Text Indent 3",
"Block Text",
"Hyperlink",
"FollowedHyperlink",
"Strong",
"Emphasis",
"Document Map",
"Plain Text",
"E-mail Signature",
"HTML Top of Form",
"HTML Bottom of Form",
"Normal (Web)",
"HTML Acronym",
"HTML Address",
"HTML Cite",
"HTML Code",
"HTML Definition",
"HTML Keyboard",
"HTML Preformatted",
"HTML Sample",
"HTML Typewriter",
"HTML Variable",
"Normal Table",
"annotation subject",
];
/// One style entry (`None` for an empty slot or one too short for its fixed part and name).
fn style(std: &[u8], cb_base: usize) -> Option<(RawStyle, StyleFacts)> {
let u16_at = |at: usize| std.get(at..at + 2).map(|x| u16::from_le_bytes([x[0], x[1]]));
if cb_base < 8 {
return None;
}
let (sti, kind_base, upx_next) = (u16_at(0)? & 0x0FFF, u16_at(2)?, u16_at(4)?);
let (stk, istd_base, cupx) = ((kind_base & 0x000F) as u8, kind_base >> 4, usize::from(upx_next & 0x000F));
let len = usize::from(*std.get(cb_base)?);
// A built-in style goes by its built-in name, as in Word, whatever name the file stores
// ("Default" or "Обычный" for Normal). Other names are 8-bit, as Word shows them
// (Windows-1252: names it couldn't store read back with '?').
let stored = std.get(cb_base + 1..cb_base + 1 + len)?;
let name: String = match BUILT_IN_NAMES.get(usize::from(sti)) {
Some(built_in) => (*built_in).to_owned(),
None => stored.iter().map(|&b| craft_codepage::cp1252(b)).collect(),
};
let mut upxs: Vec<&[u8]> = Vec::new();
let mut j = cb_base + 1 + len + 1;
for _ in 0..cupx.min(3) {
j += j % 2;
let Some(n) = u16_at(j).map(usize::from) else { break };
let Some(upx) = std.get(j + 2..j + 2 + n) else { break };
upxs.push(upx);
j += 2 + n;
}
// A paragraph style: style index + paragraph sprms, then character sprms. A character style:
// character sprms.
let (papx, chpx) = match stk {
1 => (upxs.first().and_then(|u| u.get(2..)).unwrap_or_default(), upxs.get(1).copied().unwrap_or_default()),
_ => (&[][..], upxs.first().copied().unwrap_or_default()),
};
let fact = StyleFacts { base: istd_base, font: last_font(chpx), lid: last_lid(chpx) };
Some((RawStyle { stk, istd_base, name, papx: translate_pap(papx), chpx: translate_chp(chpx) }, fact))
}
/// One font table entry.
struct Font {
name: String,
charset: u8,
}
/// The fonts of the font table at `word[fc..fc+lcb]`, by index. A truncated entry ends the table.
fn font_table(word: &[u8], fc: u32, lcb: u32) -> Vec<Font> {
let Some(table) = (fc as usize).checked_add(lcb as usize).and_then(|end| word.get(fc as usize..end)) else { return Vec::new() };
// The table starts with its own size, which bounds the entries along with `lcb`.
let size = table.get(0..2).map_or(0, |b| usize::from(u16::from_le_bytes([b[0], b[1]])));
let table = table.get(..size.min(table.len())).unwrap_or_default();
let mut fonts = Vec::new();
let mut at = 2usize;
while let Some(&cb_m1) = table.get(at) {
let next = at + usize::from(cb_m1) + 1;
// The entry must lie inside the table and hold its charset (one too short is corrupt).
let Some(entry) = table.get(at..next) else { break };
let (Some(&charset), Some(name)) = (entry.get(4), entry.get(6..)) else { break };
if fonts.len() >= MAX_FONTS {
break;
}
// An 8-bit name; font names are ASCII in every file seen, other bytes read as Latin-1.
let name = name.split(|&b| b == 0).next().unwrap_or_default().iter().map(|&b| char::from(b)).collect();
fonts.push(Font { name, charset });
at = next;
}
fonts
}
/// One FKP run as stored: its FC range, the paragraph style (PAPX runs) and its Word 6 grpprl.
struct Run<'w> {
lo: u32,
hi: u32,
istd: u16,
grpprl: &'w [u8],
}
/// The page numbers of a bin table with `n` entries ((n+1) u32 FCs, then n u16 page numbers),
/// each once, however many entries name it: a page's runs carry their own FCs, so reading it
/// again would only repeat them. The entries read are capped as for Word 97.
fn distinct_pages(plc: &[u8], n: usize) -> Vec<usize> {
let mut pns: Vec<usize> = (0..n.min(MAX_BINS))
.filter_map(|i| plc.get(4 * (n + 1) + 2 * i..4 * (n + 1) + 2 * i + 2).map(|b| usize::from(u16::from_le_bytes([b[0], b[1]]))))
.collect();
pns.sort_unstable();
pns.dedup();
pns
}
/// Every run of the FKP pages a bin table at `word[fc..fc+lcb]` lists, each page read once and
/// at most [`MAX_RUNS`] runs in all. Unreadable pages are skipped.
fn fkp_runs(word: &[u8], fc: u32, lcb: u32, papx: bool) -> Vec<Run<'_>> {
let Some(plc) = (fc as usize).checked_add(lcb as usize).and_then(|end| word.get(fc as usize..end)) else { return Vec::new() };
let Some(n) = plc.len().checked_sub(4).filter(|r| r % 6 == 0).map(|r| r / 6) else { return Vec::new() };
let entry = if papx { PAPX_BX } else { 1 };
let mut runs = Vec::new();
for pn in distinct_pages(plc, n) {
if runs.len() >= MAX_RUNS {
break;
}
let Some(page) = pn.checked_mul(PAGE).and_then(|at| word.get(at..at.checked_add(PAGE)?)) else { continue };
let crun = usize::from(page.get(PAGE - 1).copied().unwrap_or(0));
// The FCs and the entries must fit before the count byte.
if 4 * (crun + 1) + entry * crun >= PAGE {
continue;
}
let fc_at = |k: usize| page.get(4 * k..4 * k + 4).map(|b| u32::from_le_bytes([b[0], b[1], b[2], b[3]]));
for k in 0..crun {
let (Some(lo), Some(hi)) = (fc_at(k), fc_at(k + 1)) else { break };
let off = usize::from(page.get(4 * (crun + 1) + entry * k).copied().unwrap_or(0)) * 2;
let (istd, grpprl) = match (off, papx) {
(0, _) => (0, &[][..]),
// A CHPX: a byte count, then the grpprl.
(_, false) => (0, page.get(off).and_then(|&cb| page.get(off + 1..off + 1 + usize::from(cb))).unwrap_or_default()),
// A PAPX: a count of 2-byte words, then the style index and the grpprl.
(_, true) => {
let body = page.get(off).and_then(|&cw| page.get(off + 1..off + 1 + 2 * usize::from(cw))).unwrap_or_default();
let istd = body.get(0..2).map_or(0, |b| u16::from_le_bytes([b[0], b[1]]));
(istd, body.get(2..).unwrap_or_default())
}
};
runs.push(Run { lo, hi, istd, grpprl });
}
}
runs
}
/// The sprms of a Word 6.0/95 grpprl as (opcode, operand). Reading stops at an opcode whose
/// operand length is not known, since the rest can't be framed, and at a lone trailing 0 (the
/// padding of a PAPX to whole words).
fn sprms(grpprl: &[u8]) -> impl Iterator<Item = (u8, &[u8])> {
let mut rest = grpprl;
std::iter::from_fn(move || {
let (&op, after) = rest.split_first()?;
let len = match op {
// 0x55-0x5C are the character toggles of [MS-DOC]'s Prm0 isprm table (bold, italic,
// strike, outline, shadow, small caps, caps, hidden), all one byte; 0x55, 0x56, 0x5A
// and 0x5B are also seen in real files.
// 0x0D, 0x0E, 0x1D, 0x25 and 0x2C are one-byte paragraph sprms of [MS-DOC]'s isprm table
// too (numbering level, no line numbers, frame anchoring, wrapping, no hyphenation).
0x05 | 0x08 | 0x0D | 0x0E | 0x18 | 0x19 | 0x1D | 0x25 | 0x2C | 0x33 | 0x55..=0x5C | 0x5E | 0x62 | 0x68 | 0x75 | 0xB7 | 0xB9 => 1,
// 0x1A/0x1B: a frame's position; 0x6B: kerning in half-points (H1 has 0x0024; Word
// shows kern=36).
0x10 | 0x11 | 0x13 | 0x15 | 0x16 | 0x1A | 0x1B | 0x26 | 0x27 | 0x28 | 0x29 | 0x2F | 0x50 | 0x5D | 0x60 | 0x61 | 0x63 | 0x6B | 0xB6
| 0xB8 | 0xBD | 0xC0 => 2,
0x14 => 4,
// A count byte, then that many bytes (0x0C: a bulleted style's numbering, 52 bytes).
0x0C | 0x0F | 0x44 | 0xBF => 1 + usize::from(*after.first()?),
// A 2-byte count, then one byte fewer than it says (as Word 97's sprmTDefTable).
0xBE => 2 + usize::from(u16::from_le_bytes([*after.first()?, *after.get(1)?])).saturating_sub(1),
_ => return None,
};
let operand = after.get(..len)?;
rest = after.get(len..).unwrap_or_default();
Some((op, operand))
})
}
/// Append a Word 97 Prl: opcode, then operand.
fn prl(out: &mut Vec<u8>, op: u16, operand: &[u8]) {
out.extend_from_slice(&op.to_le_bytes());
out.extend_from_slice(operand);
}
/// A Word 6.0/95 CHPX grpprl as the Word 97 sprms it stands for. Sprms not read are left out.
fn translate_chp(grpprl: &[u8]) -> Vec<u8> {
let mut out = Vec::new();
for (op, v) in sprms(grpprl) {
match op {
chp::BOLD => prl(&mut out, w97::C_BOLD, v),
chp::ITALIC => prl(&mut out, w97::C_ITALIC, v),
chp::SMALL_CAPS => prl(&mut out, w97::C_SMALL_CAPS, v),
chp::CAPS => prl(&mut out, w97::C_CAPS, v),
// Only none and single were seen; any other value is left unread.
chp::UNDERLINE if matches!(v, [0] | [1]) => prl(&mut out, w97::C_KUL, v),
chp::COLOR => prl(&mut out, w97::C_ICO, v),
chp::SIZE => prl(&mut out, w97::C_HPS, v),
chp::FONT => prl(&mut out, w97::C_FTC0, v),
_ => {}
}
}
out
}
/// A Word 6.0/95 Prc grpprl as the Word 97 sprms it stands for: character and paragraph sprms
/// alike (Word 95 records a paragraph change before a fast save as a Prc on the mark's piece).
fn translate_prc(grpprl: &[u8]) -> Vec<u8> {
[translate_chp(grpprl), translate_pap(grpprl)].concat()
}
/// A Word 6.0/95 PAPX grpprl as the Word 97 sprms it stands for, table rows included. Sprms not
/// read are left out.
fn translate_pap(grpprl: &[u8]) -> Vec<u8> {
let mut out = Vec::new();
for (op, v) in sprms(grpprl) {
match op {
// Only 0-3 were seen: another value is left unread.
pap::JC if matches!(v, [0..=3]) => prl(&mut out, w97::P_JC80, v),
pap::KEEP_NEXT => prl(&mut out, w97::P_KEEP_FOLLOW, v),
pap::RIGHT => prl(&mut out, w97::P_DXA_RIGHT80, v),
pap::LEFT => prl(&mut out, w97::P_DXA_LEFT80, v),
pap::FIRST => prl(&mut out, w97::P_DXA_LEFT1_80, v),
// Only "at least" spacing was seen (a positive height, not a multiple): the other
// forms are left unread.
pap::LINE => {
if let [l0, l1, 0, 0] = v
&& i16::from_le_bytes([*l0, *l1]) > 0
{
prl(&mut out, w97::P_DYA_LINE, v);
}
}
pap::IN_TABLE => prl(&mut out, w97::P_IN_TABLE, v),
pap::TTP => prl(&mut out, w97::P_TTP, v),
pap::ROW_JC => prl(&mut out, w97::T_JC, v),
pap::ROW_HEIGHT => prl(&mut out, w97::T_ROW_HEIGHT, v),
pap::DEF_TABLE => def_table(&mut out, v),
_ => {}
}
}
out
}
/// A Word 6.0/95 table definition as a Word 97 `sprmTDefTable` holding the cell edges (the only
/// part the table reader uses) and one `sprmTMerge` per horizontal merge.
fn def_table(out: &mut Vec<u8>, v: &[u8]) {
let Some(&itc) = v.get(2) else { return };
let itc = usize::from(itc).min(MAX_CELLS);
let Some(edges) = v.get(3..3 + 2 * (itc + 1)) else { return };
// Word 97 operand: cb (u16: the bytes after it, plus one), the cell count, the edges.
let cb = (1 + edges.len() + 1) as u16;
out.extend_from_slice(&w97::T_DEF_TABLE.to_le_bytes());
out.extend_from_slice(&cb.to_le_bytes());
out.push(itc as u8);
out.extend_from_slice(edges);
let cells = v.get(3 + edges.len()..).unwrap_or_default();
let mut merges: Vec<(usize, usize)> = Vec::new();
let mut start: Option<usize> = None;
for i in 0..=itc {
let rgf = cells.get(10 * i..10 * i + 2).map_or(0, |b| u16::from_le_bytes([b[0], b[1]]));
let continues = i < itc && rgf & 0x0002 != 0 && rgf & 0x0001 == 0;
if continues {
continue;
}
// A merge runs from its first cell through every cell that continues it.
if let Some(a) = start.take()
&& i > a + 1
{
merges.push((a, i));
}
if i < itc && rgf & 0x0001 != 0 {
start = Some(i);
}
}
// Right to left: the table reader folds each merge's cells into its first one as it goes, so
// a merge further right must be applied before one to its left moves its cells.
for (a, b) in merges.into_iter().rev() {
prl(out, w97::T_MERGE, &[a as u8, b as u8]);
}
}
/// The code page of text in paragraph style `istd` whose run names `run_font` and `run_lid`: the
/// run's font, else the style's (nearest in its base chain), when that font's charset has a code
/// page; else the run's language, else the style's; else Windows-1252.
fn text_code_page(fonts: &[Font], facts: &[StyleFacts], istd: u16, run_font: Option<u16>, run_lid: Option<u16>) -> u16 {
let (style_font, style_lid) = StyleFacts::resolve(facts, istd);
run_font.or(style_font).and_then(|f| font_code_page(fonts, f)).or_else(|| run_lid.or(style_lid).map(lid_code_page)).unwrap_or(1252)
}
/// The language a grpprl names (sprm 0x61), if any: the last one.
fn last_lid(grpprl: &[u8]) -> Option<u16> {
sprms(grpprl).filter(|(op, _)| *op == chp::LID).filter_map(|(_, v)| Some(u16::from_le_bytes([*v.first()?, *v.get(1)?]))).last()
}
/// The byte ranges whose code page is not the document default `default`, cut at every character and paragraph run
/// boundary, each stretch in [`text_code_page`]'s. Sorted by start and not overlapping.
fn code_page_runs(chp: &[Run], pap: &[Run], facts: &[StyleFacts], fonts: &[Font], default: u16) -> Vec<CodePageRun> {
let sorted = |runs: &[Run]| -> Vec<(u32, u32, usize)> {
let mut v: Vec<(u32, u32, usize)> = runs.iter().enumerate().filter(|(_, r)| r.lo < r.hi).map(|(i, r)| (r.lo, r.hi, i)).collect();
v.sort_unstable();
v
};
let (chp_sorted, pap_sorted) = (sorted(chp), sorted(pap));
let covering = |v: &[(u32, u32, usize)], fc: u32| -> Option<usize> {
let k = v.partition_point(|&(lo, _, _)| lo <= fc).checked_sub(1)?;
v.get(k).filter(|&&(_, hi, _)| fc < hi).map(|&(_, _, i)| i)
};
let mut cuts: Vec<u32> = chp_sorted.iter().chain(pap_sorted.iter()).flat_map(|&(lo, hi, _)| [lo, hi]).collect();
cuts.sort_unstable();
cuts.dedup();
let mut out: Vec<CodePageRun> = Vec::new();
for w in cuts.windows(2) {
let (&lo, &hi) = (w.first().unwrap_or(&0), w.get(1).unwrap_or(&0));
let run = covering(&chp_sorted, lo).and_then(|i| chp.get(i));
let para = covering(&pap_sorted, lo).and_then(|i| pap.get(i));
if run.is_none() && para.is_none() {
continue;
}
let run_font = run.and_then(|r| last_font(r.grpprl));
let run_lid = run.and_then(|r| last_lid(r.grpprl));
let code_page = text_code_page(fonts, facts, para.map_or(0, |p| p.istd), run_font, run_lid);
if code_page == default {
continue;
}
match out.last_mut() {
Some(last) if last.hi == lo && last.code_page == code_page => last.hi = hi,
_ => out.push(CodePageRun { lo, hi, code_page }),
}
}
out
}
/// The font a CHPX or Prc grpprl names (sprm 0x5D), if any: the last one, as a later sprm
/// overrides an earlier one when the formatting is applied (a font before an opcode of unknown
/// length stands).
fn last_font(grpprl: &[u8]) -> Option<u16> {
sprms(grpprl).filter(|(op, _)| *op == chp::FONT).filter_map(|(_, v)| Some(u16::from_le_bytes([*v.first()?, *v.get(1)?]))).last()
}
#[cfg(test)]
mod tests {
#[test]
fn a_page_named_by_many_bin_entries_is_read_once() {
// A hostile bin table: a million entries all naming page 7, and one naming page 3.
let n = 1_000_001usize;
let mut plc = vec![0u8; 4 * (n + 1)];
for i in 0..n {
plc.extend_from_slice(&(if i == 5 { 3u16 } else { 7u16 }).to_le_bytes());
}
assert_eq!(super::distinct_pages(&plc, n), [3, 7]);
}
#[test]
fn bin_entries_past_the_cap_are_not_read() {
let n = super::MAX_BINS + 1;
let mut plc = vec![0u8; 4 * (n + 1)];
for i in 0..n {
plc.extend_from_slice(&(if i == n - 1 { 9u16 } else { 7u16 }).to_le_bytes());
}
assert_eq!(super::distinct_pages(&plc, n), [7]);
}
}
+29
View File
@@ -0,0 +1,29 @@
//! Paths long enough that a per-level recursive descent would exhaust the stack. Parsing is
//! iterative — `resolve` and `classify` reach `parse_share` at a fixed depth — so these come
//! back; a refusal is fine, a crash is not.
use craft_docpath::{classify, resolve};
/// Half a megabyte of components under a UNC share: one component per level for a parser that
/// recursed on each separator.
#[test]
fn a_half_megabyte_unc_path_comes_back() {
let mut path = String::from(r"\\?\UNC\host\share");
for _ in 0..(1 << 18) {
path.push_str(r"\d");
}
let _ = resolve(&path, None);
let _ = classify(&path);
}
/// Sixteen thousand nested verbatim prefixes: each level was a candidate recursive call when the
/// UNC prefixes were first reviewed.
#[test]
fn nested_verbatim_prefixes_come_back() {
let mut path = String::new();
for _ in 0..(1 << 14) {
path.push_str(r"\\?\UNC\");
}
let _ = resolve(&path, None);
let _ = classify(&path);
}
+5
View File
@@ -119,6 +119,10 @@ pub(crate) struct Reader<'p> {
pub theme_fills: shape_style::ThemeFills,
/// The fill of the group being read (what its members' `a:grpFill` stands for).
pub group_fill: Option<craft_wordmodel::fill::Fill>,
/// The package has no default table style (no styles part, or none marked `w:default`):
/// Word then gives tables no cell margins rather than its Normal Table's 0.08". Set by
/// `read_styles`, which runs before any story with tables is read.
pub no_default_table_style: bool,
}
/// The package path that internal relationship `id` points at, if it has type `kind` (an `rt`
@@ -193,6 +197,7 @@ fn read_opened_in(pkg: &Package, chunks: ChunkState) -> Result<(Document, usize,
theme_fills: Default::default(),
group_fill: None,
chunks,
no_default_table_style: true,
};
r.doc.missing_pictures.main = main.clone();
r.pc.major_font = r.doc.settings.major_font.clone();
+2
View File
@@ -113,6 +113,8 @@ pub struct StoryCtx {
pub story_depth: usize,
/// Reading a header or footer (not a text box inside one): where Word keeps its watermark.
pub in_hf: bool,
/// Reading a table cell's paragraphs (not a text box inside one).
in_cell: bool,
}
/// Paragraph content under construction.
+38 -1
View File
@@ -276,6 +276,10 @@ impl Reader<'_> {
if sc.fields.iter().any(|f| f.phase == Phase::Instr) && para.plain_text().is_empty() {
para.mark.hidden = Some(true);
}
// A cell's paragraphs are marked once their table is read: its style counts.
if !sc.in_cell {
self.doc.styles.mark_runs_as_word_draws_them(&mut para, None);
}
para.normalize();
para
}
@@ -314,15 +318,32 @@ impl Reader<'_> {
// ---- tables ----
/// Word gives a table no cell margins when the file has no default table style and neither the
/// table nor its style sets them; saving may write a default Normal Table, so the zeros are
/// kept as the table's own. shortcut: they stay direct formatting (a table style applied later
/// keeps them), until the model knows the file's default table style. A `w:tblCellMar` that sets
/// only some sides keeps them: only the sides it omits become 0.
fn no_default_margins(&self, props: &mut craft_wordmodel::props::TableProps) {
if self.no_default_table_style
&& props.cell_margins.is_none()
&& props.style.as_deref().and_then(|id| self.doc.styles.table_style(id)).is_none_or(|s| s.parts.cell_margins.is_none())
{
props.cell_margins = Some([0.0; 4]);
}
}
fn read_table(&mut self, sc: &mut StoryCtx, t: &El, rels: &Rels, depth: usize) -> Option<Table> {
let mut table = Table::default();
if let Some(p) = t.child("w:tblPr") {
table.props = self.pc.tblpr(p);
if let Some(ch) = p.child("w:tblPrChange") {
let old = ch.child("w:tblPr").map(|o| self.pc.tblpr(o)).unwrap_or_default();
let mut old = ch.child("w:tblPr").map(|o| self.pc.tblpr(o)).unwrap_or_default();
// Rejecting the change brings back these properties: with the same margins.
self.no_default_margins(&mut old);
table.props.fmt_change = PropChange::boxed(self.revision(RevisionKind::Format, ch), old);
}
}
self.no_default_margins(&mut table.props);
if let Some(g) = t.child("w:tblGrid") {
table.grid = g
.children("w:gridCol")
@@ -355,8 +376,10 @@ impl Reader<'_> {
continue;
}
let mut blocks = Blocks::new();
let outer = std::mem::replace(&mut sc.in_cell, true);
self.read_blocks(sc, tc, rels, &mut blocks, depth + 4);
self.flush_pending(sc, &mut blocks);
sc.in_cell = outer;
row.cells.push(Cell { props, blocks, controls: cell_controls });
}
if !row.cells.is_empty() {
@@ -370,6 +393,20 @@ impl Reader<'_> {
let cols = table.cols().clamp(1, MAX_COLS);
table.grid = vec![72.0; cols];
}
// The cells' paragraphs, with the run formatting the table style gives each cell (a
// table inside has marked its own).
let chrs = self.doc.styles.table_cells_chr(&table);
for (ri, row) in table.rows.iter_mut().enumerate() {
for (ci, cell) in row.cells.iter_mut().enumerate() {
let chr = chrs.as_ref().and_then(|c| c.get(ri)?.get(ci));
for b in &mut cell.blocks {
if let Block::Para(p) = Arc::make_mut(b) {
self.doc.styles.mark_runs_as_word_draws_them(p, chr);
p.normalize();
}
}
}
}
Some(table)
}
}
+24 -2
View File
@@ -64,6 +64,20 @@ fn builtin_heading_level(name: &str) -> Option<u8> {
}
impl Reader<'_> {
/// Whether a style's kept (last) definition is a default table style.
fn has_default_table_style(&self, root: &El) -> bool {
let mut defaults: Vec<String> = Vec::new();
for s in root.children("w:style").take(10_000) {
let Some(raw_id) = s.attr("w:styleId").filter(|i| !i.is_empty()) else { continue };
let id = self.pc.style_id(raw_id);
defaults.retain(|d| *d != id);
if s.attr("w:type") == Some("table") && style_is_default(s) {
defaults.push(id);
}
}
!defaults.is_empty()
}
pub(super) fn read_styles(&mut self, path: &str) -> Result<(), DocxError> {
/// Largest `w:latentStyles` kept (Word's has ~380 exceptions, ~40 KB).
const MAX_LATENT_STYLES_XML: usize = 1 << 20;
@@ -207,6 +221,7 @@ impl Reader<'_> {
None => sheet.styles.push(st),
}
}
self.no_default_table_style = !self.has_default_table_style(&root);
// Styles that give only a list level take the list from the style they are based on
// (Heading 3: level 3 of Heading 2's outline list).
let fixed: Vec<Option<craft_wordmodel::props::NumRef>> = sheet
@@ -316,9 +331,11 @@ impl Reader<'_> {
for a in root.children("w:abstractNum").take(10_000) {
let Some(id) = a.attr("w:abstractNumId").and_then(u32_of) else { continue };
let mut levels: Vec<Level> = (0..9).map(default_level).collect();
let mut explicit_levels = [false; 9];
for l in a.children("w:lvl") {
let Some(i) = numbering_level_index(l.attr("w:ilvl")) else { continue };
levels[i] = self.level(l, i);
explicit_levels[i] = true;
}
if let Some(link) = a.child_val("w:numStyleLink") {
links.push((id, link.to_string()));
@@ -328,6 +345,7 @@ impl Reader<'_> {
id,
name: a.child_val("w:name").map(str::to_string),
levels,
explicit_levels: Some(explicit_levels),
nsid: a.child_val("w:nsid").filter(|v| hex(v)).map(str::to_ascii_uppercase),
tmpl: a.child_val("w:tmpl").filter(|v| hex(v)).map(str::to_ascii_uppercase),
multi_level_type: a
@@ -361,9 +379,13 @@ impl Reader<'_> {
for (aid, style) in links {
let num = self.doc.styles.get(&self.pc.style_id(&style)).and_then(|s| s.para.numbering).map(|n| n.num);
let src = num.and_then(|n| nums.iter().find(|x: &&Num| x.id == n)).map(|x| x.abstract_id);
let levels = src.filter(|s| *s != aid).and_then(|s| abstracts.iter().find(|a: &&AbstractNum| a.id == s)).map(|a| a.levels.clone());
if let (Some(levels), Some(a)) = (levels, abstracts.iter_mut().find(|a| a.id == aid)) {
let source = src
.filter(|s| *s != aid)
.and_then(|s| abstracts.iter().find(|a: &&AbstractNum| a.id == s))
.map(|a| (a.levels.clone(), a.explicit_levels));
if let (Some((levels, explicit_levels)), Some(a)) = (source, abstracts.iter_mut().find(|a| a.id == aid)) {
a.levels = levels;
a.explicit_levels = explicit_levels;
}
}
Arc::make_mut(&mut self.doc.numbering).abstracts = abstracts;
+152
View File
@@ -175,3 +175,155 @@ fn rtl_tables_and_sections_round_trip() {
assert_eq!(again, vec![true, false]);
assert!(r.last_section.rtl && r.last_section.columns.count == 2);
}
/// A package whose body is `body` and whose styles part holds `styles`.
fn docx_with_styles(body: &str, styles: &str) -> Vec<u8> {
let ns = r#"xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main""#;
let root = r#"<?xml version="1.0" encoding="UTF-8"?><Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/></Relationships>"#;
let rels = r#"<?xml version="1.0" encoding="UTF-8"?><Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rIdS" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml"/></Relationships>"#;
let doc = format!(r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w:document {ns}><w:body>{body}</w:body></w:document>"#);
let st = format!(r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?><w:styles {ns}>{styles}</w:styles>"#);
zip(&[
("_rels/.rels", root.as_bytes()),
("word/_rels/document.xml.rels", rels.as_bytes()),
("word/document.xml", doc.as_bytes()),
("word/styles.xml", st.as_bytes()),
])
}
/// Thai text draws in the complex-script formatting only where Word draws it so (measured in Word
/// for Windows; run defaults Angsana New 22 pt, complex script Tahoma 11 pt bold). Without
/// `w:cs` or `w:rtl` on the run, its paragraph style or the run defaults, Thai text measures as
/// Angsana New 22 pt, whatever its language, `w:hint` or character style.
#[test]
fn thai_text_takes_the_complex_script_formatting_only_in_a_complex_script_run() {
let thai = "ทดสอบ ภาษาไทย";
let defaults = |extra: &str| {
format!(
r#"<w:docDefaults><w:rPrDefault><w:rPr><w:rFonts w:ascii="Angsana New" w:hAnsi="Angsana New" w:cs="Tahoma"/><w:bCs/><w:sz w:val="44"/><w:szCs w:val="22"/>{extra}</w:rPr></w:rPrDefault></w:docDefaults>
<w:style w:type="paragraph" w:default="1" w:styleId="Normal"><w:name w:val="Normal"/></w:style>
<w:style w:type="paragraph" w:styleId="CsPara"><w:name w:val="CsPara"/><w:basedOn w:val="Normal"/><w:rPr><w:cs/></w:rPr></w:style>
<w:style w:type="character" w:styleId="CsChar"><w:name w:val="CsChar"/><w:rPr><w:cs/></w:rPr></w:style>
<w:style w:type="character" w:styleId="CsOff"><w:name w:val="CsOff"/><w:rPr><w:cs w:val="0"/></w:rPr></w:style>
<w:style w:type="character" w:styleId="RtlChar"><w:name w:val="RtlChar"/><w:rPr><w:rtl/></w:rPr></w:style>
<w:style w:type="table" w:styleId="CsTable"><w:name w:val="CsTable"/><w:rPr><w:cs/></w:rPr></w:style>
<w:style w:type="table" w:styleId="SizeTable"><w:name w:val="SizeTable"/><w:rPr><w:sz w:val="30"/><w:szCs w:val="16"/></w:rPr></w:style>"#
)
};
let latin = ("Angsana New", 22.0, false);
let complex = ("Tahoma", 11.0, true);
let run = |rpr: &str| format!(r#"<w:p><w:r><w:rPr>{rpr}</w:rPr><w:t xml:space="preserve">{thai}</w:t></w:r></w:p>"#);
let styled = |p: &str, rpr: &str| {
format!(r#"<w:p><w:pPr><w:pStyle w:val="{p}"/></w:pPr><w:r><w:rPr>{rpr}</w:rPr><w:t xml:space="preserve">{thai}</w:t></w:r></w:p>"#)
};
let in_table = |style: &str| {
format!(
r#"<w:tbl><w:tblPr><w:tblStyle w:val="{style}"/></w:tblPr><w:tblGrid><w:gridCol w:w="6000"/></w:tblGrid><w:tr><w:tc>{}</w:tc></w:tr></w:tbl>"#,
run("")
)
};
let cs_off = r#"<w:rStyle w:val="CsOff"/>"#;
let cases: Vec<(&str, String, String, (&str, f32, bool))> = vec![
("plain", defaults(""), run(""), latin),
("bidi language", defaults(""), run(r#"<w:lang w:val="th-TH" w:bidi="th-TH"/>"#), latin),
("hint", defaults(""), run(r#"<w:rFonts w:hint="cs"/>"#), latin),
("character style", defaults(""), run(r#"<w:rStyle w:val="CsChar"/>"#), latin),
("character style rtl", defaults(""), run(r#"<w:rStyle w:val="RtlChar"/>"#), latin),
("run cs", defaults(""), run("<w:cs/>"), complex),
("run rtl", defaults(""), run("<w:rtl/>"), complex),
("paragraph style", defaults(""), styled("CsPara", ""), complex),
("paragraph style, run cs off", defaults(""), styled("CsPara", r#"<w:cs w:val="0"/>"#), latin),
("run defaults", defaults("<w:cs/>"), run(""), complex),
// A character style's `w:cs w:val="0"` doesn't turn the paragraph style's or the run
// defaults' off either.
("paragraph style, character style cs off", defaults(""), styled("CsPara", cs_off), complex),
("run defaults, character style cs off", defaults("<w:cs/>"), run(cs_off), complex),
// A table style's `w:cs` counts, and its sizes are the run's.
("table style", defaults(""), in_table("CsTable"), complex),
("table style sizes", defaults(""), in_table("SizeTable"), ("Angsana New", 15.0, false)),
];
let check = |d: &Document, name: &str, want: (&str, f32, bool), when: &str| {
let (p, table) = match &*d.body[0] {
craft_wordmodel::Block::Table(t) => {
(t.rows[0].cells[0].blocks[0].as_para().unwrap(), d.styles.table_cells_chr(t).map(|c| c[0][0].clone()))
}
b => (b.as_para().unwrap(), None),
};
let rc = d.styles.resolve_char_in(p.props.style.as_deref(), table.as_ref(), &p.runs[0].props);
for ch in p.text.chars() {
let drawn = if rc.uses_complex(ch) { rc.complex() } else { rc.clone() };
assert_eq!((drawn.font.as_str(), drawn.size, drawn.bold), want, "{name} {when}: {ch:?}");
}
let c = &p.runs[0].props;
assert_eq!((c.font_cs.as_deref(), c.size_cs, c.bold_cs), (None, None, None), "{name} {when}: nothing is pinned");
};
for (name, styles, body, want) in &cases {
let d = craft_docx::read(&docx_with_styles(body, styles)).unwrap();
check(&d, name, *want, "read");
let again = craft_docx::read(&craft_docx::write(&d).unwrap()).unwrap();
check(&again, name, *want, "after a save");
}
// Latin text and right-to-left text are left as they were.
let body = r#"<w:p><w:r><w:t>Latin only</w:t></w:r></w:p><w:p><w:r><w:t>سلام</w:t></w:r></w:p>"#;
let d = craft_docx::read(&docx_with_styles(body, &defaults(""))).unwrap();
for p in paras(&d) {
assert_eq!(p.runs[0].props.cs, None, "{}", p.text);
}
// Latin text follows the same rule (measured): a character style's `w:cs` or `w:rtl` leaves it in the
// run's own formatting, a character style's `w:cs w:val="0"` under a paragraph style's
// `w:cs` in the complex-script formatting.
let latin_in =
|p: &str, rpr: &str| format!(r#"<w:p><w:pPr><w:pStyle w:val="{p}"/></w:pPr><w:r><w:rPr>{rpr}</w:rPr><w:t>Latin</w:t></w:r></w:p>"#);
let body =
latin_in("Normal", r#"<w:rStyle w:val="CsChar"/>"#) + &latin_in("CsPara", cs_off) + &latin_in("Normal", r#"<w:rStyle w:val="RtlChar"/>"#);
let d = craft_docx::read(&docx_with_styles(&body, &defaults(""))).unwrap();
let again = craft_docx::read(&craft_docx::write(&d).unwrap()).unwrap();
for (d, when) in [(&d, "read"), (&again, "after a save")] {
let drawn: Vec<_> = paras(d)
.iter()
.map(|p| {
let rc = d.styles.resolve_char(p.props.style.as_deref(), &p.runs[0].props);
let c = if rc.uses_complex('L') { rc.complex() } else { rc };
(c.font, c.size)
})
.collect();
assert_eq!(drawn, [("Angsana New".to_string(), 22.0), ("Tahoma".to_string(), 11.0), ("Angsana New".to_string(), 22.0)], "{when}");
}
}
/// Measured in Word for Windows: Thai text as a field's result follows the same rule as ordinary
/// text, also when the reader keeps the field as one object with its result.
#[test]
fn a_fields_thai_result_takes_the_complex_script_formatting_only_in_a_complex_script_run() {
let styles = r#"<w:docDefaults><w:rPrDefault><w:rPr><w:rFonts w:ascii="Angsana New" w:hAnsi="Angsana New" w:cs="Tahoma"/><w:sz w:val="20"/><w:szCs w:val="40"/></w:rPr></w:rPrDefault></w:docDefaults>
<w:style w:type="paragraph" w:default="1" w:styleId="Normal"><w:name w:val="Normal"/></w:style>"#;
let field = |rpr: &str| {
let r = |inner: &str| format!("<w:r><w:rPr>{rpr}</w:rPr>{inner}</w:r>");
format!(
"<w:p>{}{}{}{}{}</w:p>",
r(r#"<w:fldChar w:fldCharType="begin"/>"#),
r(r#"<w:instrText xml:space="preserve"> QUOTE "x" </w:instrText>"#),
r(r#"<w:fldChar w:fldCharType="separate"/>"#),
r("<w:t>ทดสอบ</w:t>"),
r(r#"<w:fldChar w:fldCharType="end"/>"#)
)
};
let drawn = |d: &Document| {
let p = paras(d)[0];
let at = p.text.find(craft_wordmodel::para::OBJ).expect("the field is one object");
let run = p.runs.iter().scan(0, |end, r| {
let start = *end;
*end += r.len;
Some((start, r))
});
let (_, run) = run.into_iter().find(|(start, r)| *start <= at && at < start + r.len).unwrap();
let rc = d.styles.resolve_char(p.props.style.as_deref(), &run.props);
if rc.uses_complex('ท') { (rc.font_cs.clone(), rc.size_cs) } else { (rc.font.clone(), rc.size) }
};
for (what, rpr, want) in [("nothing", "", ("Angsana New", 10.0)), ("w:cs", "<w:cs/>", ("Tahoma", 20.0))] {
let d = craft_docx::read(&docx_with_styles(&field(rpr), styles)).unwrap();
assert_eq!(drawn(&d), (want.0.to_string(), want.1), "a run with {what}: read");
let again = craft_docx::read(&craft_docx::write(&d).unwrap()).unwrap();
assert_eq!(drawn(&again), (want.0.to_string(), want.1), "a run with {what}: after a save");
}
}
@@ -28,3 +28,73 @@ fn partial_margin_stays_partial() {
assert!(!margins.contains("<w:bottom"));
assert!(!margins.contains("<w:right"));
}
/// A package with this body and, if given, this styles part.
fn package(body: &str, styles: Option<&str>) -> Vec<u8> {
const W: &str = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
let mut zip = zip::ZipWriter::new(Cursor::new(Vec::new()));
let mut add = |name: &str, xml: &str| {
zip.start_file(name, zip::write::SimpleFileOptions::default()).unwrap();
zip.write_all(xml.as_bytes()).unwrap();
};
add("word/document.xml", &format!(r#"<w:document xmlns:w="{W}"><w:body>{body}</w:body></w:document>"#));
if let Some(styles) = styles {
add("word/styles.xml", &format!(r#"<w:styles xmlns:w="{W}">{styles}</w:styles>"#));
add(
"word/_rels/document.xml.rels",
r#"<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml"/></Relationships>"#,
);
}
zip.finish().unwrap().into_inner()
}
/// Without a default table style (no styles part, or none marked `w:default`) Word gives a table
/// no cell margins: a cell that sets only its right margin has none on its other sides.
#[test]
fn no_default_table_style_means_no_cell_margins() {
let body = r#"<w:tbl><w:tblPr><w:tblW w:w="6000" w:type="dxa"/></w:tblPr><w:tblGrid><w:gridCol w:w="3000"/></w:tblGrid><w:tr><w:tc><w:tcPr><w:tcMar><w:right w:w="108" w:type="dxa"/></w:tcMar></w:tcPr><w:p/></w:tc></w:tr></w:tbl>"#;
let normal_table = r#"<w:style w:type="table" w:default="1" w:styleId="TableNormal"><w:name w:val="Normal Table"/><w:tblPr><w:tblCellMar><w:left w:w="108" w:type="dxa"/><w:right w:w="108" w:type="dxa"/></w:tblCellMar></w:tblPr></w:style>"#;
let margins = |styles: Option<&str>| {
let doc = craft_docx::read(&package(body, styles)).unwrap();
let table = doc.body[0].as_table().unwrap();
(table.props.cell_margins, table.rows[0].cells[0].props.resolved_margins(table.props.cell_margins.unwrap_or([0.0, 5.4, 0.0, 5.4])))
};
assert_eq!(margins(None), (Some([0.0; 4]), [0.0, 0.0, 0.0, 5.4]));
assert_eq!(margins(Some(r#"<w:docDefaults/>"#)), (Some([0.0; 4]), [0.0, 0.0, 0.0, 5.4]));
// With Word's usual Normal Table the table keeps no margins of its own (the defaults apply).
assert_eq!(margins(Some(normal_table)).0, None);
// A style defined twice is its last definition: a default one redefined as not default leaves none.
let redefined = format!(r#"{normal_table}<w:style w:type="table" w:styleId="TableNormal"><w:name w:val="Normal Table"/></w:style>"#);
assert_eq!(margins(Some(&redefined)).0, Some([0.0; 4]));
// A custom default table style marked `on` is a default too, also after saving and reopening.
let plain = r#"<w:style w:type="table" w:default="on" w:customStyle="1" w:styleId="Plain"><w:name w:val="Plain"/></w:style>"#;
let doc = craft_docx::read(&package(body, Some(plain))).unwrap();
assert_eq!(doc.body[0].as_table().unwrap().props.cell_margins, None);
let reopened = craft_docx::read(&craft_docx::write(&doc).unwrap()).unwrap();
assert_eq!(reopened.body[0].as_table().unwrap().props.cell_margins, None);
// A table that sets only some sides keeps them; the sides it omits are 0.
let partial = body.replace("<w:tblPr>", r#"<w:tblPr><w:tblCellMar><w:left w:w="144" w:type="dxa"/></w:tblCellMar>"#);
let doc = craft_docx::read(&package(&partial, None)).unwrap();
assert_eq!(doc.body[0].as_table().unwrap().props.cell_margins, Some([0.0, 7.2, 0.0, 0.0]));
// Rejecting a tracked change to the table's properties brings back the same zero margins.
let tracked = body.replace(
"</w:tblPr>",
r#"<w:tblPrChange w:id="1" w:author="A" w:date="2026-11-13T00:00:00Z"><w:tblPr><w:tblW w:w="5000" w:type="dxa"/></w:tblPr></w:tblPrChange></w:tblPr>"#,
);
let doc = craft_docx::read(&package(&tracked, None)).unwrap();
let change = doc.body[0].as_table().unwrap().props.fmt_change.as_deref().expect("a tracked table change");
assert_eq!(change.old.cell_margins, Some([0.0; 4]));
// A table whose own style gives margins keeps them.
let styled = body.replace("<w:tblPr>", r#"<w:tblPr><w:tblStyle w:val="Boxed"/>"#);
let boxed = r#"<w:style w:type="table" w:styleId="Boxed"><w:name w:val="Boxed"/><w:tblPr><w:tblCellMar><w:left w:w="144" w:type="dxa"/></w:tblCellMar></w:tblPr></w:style>"#;
let doc = craft_docx::read(&package(&styled, Some(boxed))).unwrap();
assert_eq!(doc.body[0].as_table().unwrap().props.cell_margins, None);
// The zeros survive saving, which writes a default Normal Table.
let doc = craft_docx::read(&package(body, None)).unwrap();
let bytes = craft_docx::write(&doc).unwrap();
let mut xml = String::new();
zip::ZipArchive::new(Cursor::new(bytes.clone())).unwrap().by_name("word/document.xml").unwrap().read_to_string(&mut xml).unwrap();
assert!(xml.contains("<w:tblCellMar>"), "{xml}");
let reopened = craft_docx::read(&bytes).unwrap();
assert_eq!(reopened.body[0].as_table().unwrap().props.cell_margins, Some([0.0; 4]));
}
+3
View File
@@ -335,6 +335,9 @@ fn malformed_numbering_levels_are_skipped_instead_of_becoming_level_zero() {
})
.collect();
assert_eq!(paragraphs.len(), 5);
assert!(doc.numbering.level_is_defined(1, 0));
assert!(!doc.numbering.level_is_defined(1, 2), "effective defaults remain distinguishable from source definitions");
assert!(doc.numbering.level(1, 2).is_some(), "Word's effective default level remains available");
assert_eq!(paragraphs[0].props.numbering.map(|n| (n.num, n.level)), Some((1, 0)), "an omitted level defaults to zero");
assert_eq!(paragraphs[1].props.numbering.map(|n| (n.num, n.level)), Some((1, 2)), "a valid level is preserved");
for p in &paragraphs[2..] {
+3 -1
View File
@@ -11,7 +11,9 @@ allocation failure inside the decoder. On native applications, call `use_own_wor
startup and call `serve_if_asked()` before normal argument handling. Subsequent `decode` and
`encode_*` calls then run in a child process with a 30-minute timeout; a crash or stack overflow
is contained to that child. The worker has no operating-system memory limit yet. Without a
configured worker, conversions run in the current process.
configured worker, conversions are refused rather than run in the current process: call
`allow_in_process()` only for input that is known to be trusted (tests, or bytes this process
produced itself). Coordinates, once a worker is configured but cannot start, also fail closed.
The bridge is not built for `wasm32` or FreeBSD/aarch64. Those targets retain the public API and
return a clear unsupported-build error. The `acadrust` 0.6.6 dependency is used unmodified under
+11 -1
View File
@@ -21,6 +21,11 @@
//! These bound the input- and output-size variants. A small file that declares a huge internal
//! table or section can still make the dependency allocate before any size is known, so the app
//! runs both directions in a child process ([`worker`]): what that kills is the child.
//!
//! Isolation is not optional for untrusted input. With no worker configured the conversion is
//! refused rather than run here, and a worker that cannot start is an error, so a missing worker
//! never turns into decoding a hostile file in the caller's process. [`worker::allow_in_process`]
//! is the explicit exception, for input the caller knows is trusted.
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
#![forbid(unsafe_code)]
@@ -65,7 +70,10 @@ fn mb(n: u64) -> String {
#[cfg(not(no_dwg_bridge))]
pub mod worker;
#[cfg(not(no_dwg_bridge))]
pub use worker::{WORKER_ARG, crash_worker_for_test, decode, encode_as, encode_kept_noted, encode_noted, serve_if_asked, use_own_worker, use_worker};
pub use worker::{
WORKER_ARG, allow_in_process, crash_worker_for_test, decode, encode_as, encode_kept_noted, encode_noted, serve_if_asked, use_own_worker,
use_worker,
};
#[cfg(not(no_dwg_bridge))]
mod proxy_transport;
@@ -1569,6 +1577,8 @@ pub fn serve_if_asked() -> Option<i32> {
#[cfg(no_dwg_bridge)]
pub fn use_own_worker() {}
#[cfg(no_dwg_bridge)]
pub fn allow_in_process() {}
#[cfg(no_dwg_bridge)]
pub fn decode(bytes: &[u8], limits: Limits) -> Result<(Vec<u8>, Vec<String>), String> {
dwg_to_dxf_noted(bytes, limits)
}
+60 -13
View File
@@ -6,9 +6,11 @@
//! that reads one request from standard input and writes one reply to standard output. A file that
//! kills the worker then costs that one open or save, and every other open drawing stays safe.
//!
//! Without a worker (libraries, tests, a build that can't start one) [`decode`] and [`encode_as`]
//! run in the calling process, as they always did. There's no memory limit on the worker yet: that
//! takes per-platform system calls, which `unsafe_code = "forbid"` keeps out of this crate.
//! Without a worker [`decode`] and [`encode_as`] refuse rather than run the conversion in the
//! calling process, because the third-party code is the part that can end a process.
//! [`allow_in_process`] is the explicit exception, for input the caller knows is trusted (tests, or
//! bytes this process produced itself). There's no memory limit on the worker yet: that takes
//! per-platform system calls, which `unsafe_code = "forbid"` keeps out of this crate.
//!
//! A reply comes from a process that just handled a possibly hostile file, so it is parsed as
//! untrusted input.
@@ -18,6 +20,7 @@ use std::io::{Read, Write};
use std::path::PathBuf;
use std::process::{Command, Stdio};
use std::sync::Mutex;
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::mpsc::{RecvTimeoutError, channel};
use std::time::Duration;
@@ -38,6 +41,9 @@ const MAX_NOTES_BYTES: u64 = 64 << 20;
const MAX_DWG_REPLY: u64 = 2 << 30;
/// Most bytes one request holds: the largest input, whichever the direction, and its header.
const MAX_REQUEST: u64 = (2 << 30) + 256;
/// What a conversion says when it has no worker and is not allowed to run here.
const NO_WORKER: &str = "DWG: no worker is configured, so this file was not converted; \
call use_worker or use_own_worker at startup, or allow_in_process for input that is trusted";
struct Worker {
program: PathBuf,
@@ -45,6 +51,8 @@ struct Worker {
}
static WORKER: Mutex<Option<Worker>> = Mutex::new(None);
/// Whether this process may run the conversion itself, set only by [`allow_in_process`].
static IN_PROCESS: AtomicBool = AtomicBool::new(false);
/// Start `program args` as the worker from now on. `program` must call [`serve_if_asked`].
pub fn use_worker(program: PathBuf, args: Vec<OsString>) {
@@ -62,12 +70,27 @@ pub fn use_own_worker() {
}
}
/// Let [`decode`] and [`encode_as`] run the conversion in this process when no worker is set.
///
/// This opts out of the isolation the crate exists for: the third-party code allocates from sizes
/// a hostile file declares, and a failed allocation ends the process. Call it for input the caller
/// knows is trusted (tests, or bytes this process produced), never for a file that arrived from
/// outside.
pub fn allow_in_process() {
IN_PROCESS.store(true, Ordering::Relaxed);
}
fn in_process_allowed() -> bool {
IN_PROCESS.load(Ordering::Relaxed)
}
/// Serve one request and return the exit code if this process was started as a worker.
pub fn serve_if_asked() -> Option<i32> {
(std::env::args_os().nth(1)? == WORKER_ARG).then(|| serve(std::io::stdin().lock(), std::io::stdout().lock()))
}
/// [`super::dwg_to_dxf_noted`] in the worker, when there is one.
/// [`super::dwg_to_dxf_noted`] in the worker. With no worker configured this is refused unless
/// [`allow_in_process`] was called; a configured worker that cannot start is an error.
pub fn decode(bytes: &[u8], limits: Limits) -> Result<(Vec<u8>, Vec<String>), String> {
// Before starting a process, and so the same limit holds with or without one.
if bytes.len() > limits.max_dwg_bytes {
@@ -76,17 +99,19 @@ pub fn decode(bytes: &[u8], limits: Limits) -> Result<(Vec<u8>, Vec<String>), St
let reply_limit = (limits.max_dxf_bytes as u64).saturating_add(MAX_NOTES_BYTES);
match call(&request(DECODE, limits, ""), bytes, reply_limit, "reading this file") {
Some(reply) => reply?,
None => super::dwg_to_dxf_noted(bytes, limits),
None if in_process_allowed() => super::dwg_to_dxf_noted(bytes, limits),
None => Err(NO_WORKER.to_string()),
}
}
/// [`super::dxf_to_dwg_as`] in the worker, when there is one.
/// [`super::dxf_to_dwg_as`] in the worker. Refused without a worker unless [`allow_in_process`]
/// was called.
pub fn encode_as(dxf: &[u8], version: &str) -> Result<Vec<u8>, String> {
encode_noted(dxf, version).map(|(dwg, _)| dwg)
}
/// [`super::dxf_to_dwg_noted`] in the worker, when there is one. What the writer left out comes
/// back as notes of `TYPE<tab>count`.
/// [`super::dxf_to_dwg_noted`] in the worker. What the writer left out comes back as notes of
/// `TYPE<tab>count`.
pub fn encode_noted(dxf: &[u8], version: &str) -> Result<(Vec<u8>, super::Unwritten), String> {
encode_kept_noted(dxf, version, None)
}
@@ -103,7 +128,8 @@ pub fn encode_kept_noted(dxf: &[u8], version: &str, kept: Option<&str>) -> Resul
push_str(&mut header, kept.unwrap_or(""));
match call(&header, dxf, MAX_DWG_REPLY, "writing this file") {
Some(reply) => reply?.map(|(dwg, notes)| (dwg, unwritten_from(&notes))),
None => encode_here(dxf, version, kept),
None if in_process_allowed() => encode_here(dxf, version, kept),
None => Err(NO_WORKER.to_string()),
}
}
@@ -147,8 +173,9 @@ fn push_str(r: &mut Vec<u8>, text: &str) {
type Reply = Result<(Vec<u8>, Vec<String>), String>;
/// Run one request in a worker. `None`: none could be started, so the caller does the work.
/// `Err`: the worker went wrong, and `doing` says at what, for the user.
/// Run one request in a worker. `None`: no worker is configured, so the caller decides what to do
/// (convert here only with [`allow_in_process`], or refuse). `Err`: a configured worker could not
/// start or went wrong, and `doing` says at what, for the user.
fn call(header: &[u8], payload: &[u8], reply_limit: u64, doing: &str) -> Option<Result<Reply, String>> {
let mut command = {
let worker = WORKER.lock().ok()?;
@@ -167,14 +194,15 @@ fn call(header: &[u8], payload: &[u8], reply_limit: u64, doing: &str) -> Option<
let mut child = match command.spawn() {
Ok(c) => c,
Err(e) => {
// A worker is configured but cannot run: never fall back to decoding here.
log::warn!("DWG worker: can't start it: {e}");
return None;
return Some(Err(format!("the DWG worker could not start ({e}); nothing else is affected")));
}
};
let (Some(mut to_child), Some(from_child)) = (child.stdin.take(), child.stdout.take()) else {
let _ = child.kill();
let _ = child.wait();
return None;
return Some(Err("the DWG worker could not start (no pipes); nothing else is affected".to_string()));
};
let received = std::thread::scope(|scope| {
// Written beside the read: a worker that replies before it has read everything, or dies,
@@ -367,6 +395,25 @@ mod tests {
}
}
/// A conversion is refused rather than run here, and a worker that cannot start is an error:
/// neither case may turn into decoding a (possibly hostile) file in this process.
#[test]
fn a_conversion_is_refused_without_a_worker_and_never_falls_back_to_this_process() {
// No worker is configured and nothing opted in.
assert_eq!(decode(b"AC1032", Limits::DEFAULT).unwrap_err(), NO_WORKER);
assert_eq!(encode_as(b"not a dxf", "AC1032").unwrap_err(), NO_WORKER);
// Trusted input may run here, and the reader still reports a file it cannot read.
allow_in_process();
assert!(in_process_allowed());
assert!(decode(b"AC1032", Limits::DEFAULT).is_err());
assert!(encode_as(b"not a dxf", "AC1032").is_err());
// A configured worker that cannot start is an error even after the opt-in: the conversion
// never runs here instead.
use_worker(PathBuf::from("/nonexistent/craft-dwg-worker"), Vec::new());
assert!(decode(b"AC1032", Limits::DEFAULT).unwrap_err().contains("could not start"));
assert!(encode_as(b"not a dxf", "AC1032").unwrap_err().contains("could not start"));
}
#[test]
fn serving_reports_a_decode_failure_as_a_reply() {
let mut request = self::request(DECODE, Limits::DEFAULT, "");
+4 -2
View File
@@ -12,8 +12,10 @@ use crate::{Error, corrupt};
const MAX_META: u64 = 1 << 20;
/// Largest file [`write_archive`] writes (the canvas and the images together).
const MAX_FILE: u64 = 2 * 1024 * 1024 * 1024;
/// Most entries an archive may declare; checked before the archive is indexed.
pub const MAX_ENTRIES: u64 = 1_000_000;
/// Most entries an archive may declare; checked before the archive is indexed. The archive holds one
/// entry per image, so 100 000 leaves room for far more than a `.fig` file carries, and a header
/// count can no longer make the index alone cost a hundred megabytes.
pub const MAX_ENTRIES: u64 = 100_000;
/// What one open may read from `images/`.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+52
View File
@@ -194,6 +194,45 @@ pub fn animation(width: u32, height: u32, frames: &[RgbaFrame<'_>], options: Opt
writer.finish()
}
/// Encode a single pre-quantized indexed-color frame as a GIF89a image.
///
/// `palette` holds 1 to 256 RGB triplets; `indices` is `width * height` row-major palette indices.
/// When `interlaced` is true, rows are reordered into GIF's 4-pass interlaced order before writing.
pub fn encode_indexed(
width: u32,
height: u32,
palette: &[[u8; 3]],
indices: &[u8],
transparent: Option<u8>,
interlaced: bool,
) -> Result<Vec<u8>, Error> {
let (w, h) = dimensions(width, height)?;
let expected = usize::from(w) * usize::from(h);
if indices.len() != expected {
return Err(Error::FrameLength { index: 0, actual: indices.len(), expected });
}
if palette.is_empty() || palette.len() > 256 {
return Err(Error::Encode("GIF palette must hold 1 to 256 entries".into()));
}
let flat_palette: Vec<u8> = palette.iter().flat_map(|c| *c).collect();
let buffer = if interlaced { std::borrow::Cow::Owned(interlace(indices, usize::from(w))) } else { std::borrow::Cow::Borrowed(indices) };
let mut enc = gif::Encoder::new(Vec::new(), w, h, &flat_palette).map_err(Error::from)?;
let frame = gif::Frame { width: w, height: h, buffer, transparent, interlaced, ..gif::Frame::default() };
enc.write_frame(&frame).map_err(Error::from)?;
enc.into_inner().map_err(Error::from)
}
/// The rows of a `width`-wide image in GIF's interlaced order: every 8th row from 0, every 8th
/// from 4, every 4th from 2, then every 2nd from 1.
fn interlace(px: &[u8], width: usize) -> Vec<u8> {
let rows: Vec<&[u8]> = px.chunks(width.max(1)).collect();
[(0, 8), (4, 8), (2, 4), (1, 2)]
.into_iter()
.flat_map(|(start, step)| rows.iter().skip(start).step_by(step))
.flat_map(|r| r.iter().copied())
.collect()
}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used)]
@@ -288,4 +327,17 @@ mod tests {
assert_eq!(decoded.frames[0].rgba, red);
assert_eq!(decoded.frames[1].rgba, blue);
}
#[test]
fn encode_indexed_validates_and_writes_gif() {
let palette = [[255, 0, 0], [0, 255, 0]];
let indices = [0u8, 1, 1, 0, 0, 1, 1, 0, 0];
let bytes = super::encode_indexed(3, 3, &palette, &indices, Some(1), true).unwrap();
let info = crate::scan(&bytes, 4).unwrap();
assert_eq!((info.width, info.height), (3, 3));
assert_eq!(info.frames.len(), 1);
assert_eq!(info.frames[0].transparent, Some(1));
assert!(super::encode_indexed(2, 2, &[], &[0; 4], None, false).is_err());
assert!(super::encode_indexed(2, 2, &palette, &[0; 3], None, false).is_err());
}
}
+43 -6
View File
@@ -11,7 +11,9 @@
//!
//! Input is treated as hostile: the header length and the picture size are capped by [`Limits`],
//! and every scan line is validated before the float picture is allocated, so a short file cannot
//! ask for a large allocation.
//! ask for a large allocation. Whatever the limits, no buffer is requested past the target's
//! largest allocation (`isize::MAX` bytes), so raised limits on a 32-bit target such as `wasm32`
//! give [`Error::LimitExceeded`] instead of a panic.
#[cfg(test)]
mod tests;
@@ -42,6 +44,7 @@ pub type Result<T> = std::result::Result<T, Error>;
#[non_exhaustive]
pub struct Limits {
/// Most pixels (width × height) a picture may have; each takes 12 bytes decoded. Default 2^26.
/// A picture over the target's largest allocation is refused at any setting.
pub max_pixels: u64,
/// Longest header read, in bytes (real ones are a few hundred). Default 64 KiB.
pub max_header: usize,
@@ -62,6 +65,27 @@ pub struct Picture {
pub rgb: Vec<f32>,
}
/// The largest allocation in bytes that a `Vec` or `String` can make on the target.
const MAX_ALLOC_BYTES: u64 = isize::MAX as u64;
/// Bytes taken by `count` elements of `element_bytes` each, or `None` when the count overflows `u64`.
fn checked_byte_len(count: u64, element_bytes: usize) -> Option<u64> {
count.checked_mul(element_bytes as u64)
}
/// `count` as a length when `count` elements of `element_bytes` each fit in `max_alloc_bytes`.
fn alloc_len(count: u64, element_bytes: usize, max_alloc_bytes: u64) -> Option<usize> {
checked_byte_len(count, element_bytes).filter(|&bytes| bytes <= max_alloc_bytes).and_then(|_| usize::try_from(count).ok())
}
/// Bytes of `String::from_utf8_lossy(bytes)`: each invalid sequence becomes one U+FFFD (3 bytes).
fn lossy_len(bytes: &[u8]) -> Option<u64> {
bytes.utf8_chunks().try_fold(0u64, |n, chunk| {
let invalid = if chunk.invalid().is_empty() { 0 } else { '\u{FFFD}'.len_utf8() };
n.checked_add(chunk.valid().len() as u64)?.checked_add(invalid as u64)
})
}
/// Whether `bytes` starts like a Radiance picture.
pub fn sniff(bytes: &[u8]) -> bool {
bytes.starts_with(b"#?RADIANCE") || bytes.starts_with(b"#?RGBE")
@@ -158,6 +182,11 @@ fn scanline(b: &[u8], pos: &mut usize, line: &mut [[u8; 4]]) -> Result<()> {
/// Decodes a Radiance picture to linear float RGB, top row first.
pub fn decode(b: &[u8], limits: &Limits) -> Result<Picture> {
decode_within(b, limits, MAX_ALLOC_BYTES)
}
/// [`decode`] with `max_alloc_bytes` as the largest allocation the target allows.
fn decode_within(b: &[u8], limits: &Limits, max_alloc_bytes: u64) -> Result<Picture> {
if !sniff(b) {
return Err(Error::NotHdr);
}
@@ -166,7 +195,11 @@ pub fn decode(b: &[u8], limits: &Limits) -> Result<Picture> {
let line = |pos: &mut usize| -> Result<String> {
let rest = b.get(*pos..).ok_or(Error::Malformed("truncated header"))?;
let end = rest.iter().take(limits.max_header).position(|&c| c == b'\n').ok_or(Error::Malformed("truncated header"))?;
let s = String::from_utf8_lossy(rest.get(..end).unwrap_or_default()).trim_end_matches('\r').to_string();
let raw = rest.get(..end).unwrap_or_default();
if lossy_len(raw).is_none_or(|n| n > max_alloc_bytes) {
return Err(Error::LimitExceeded("header length"));
}
let s = String::from_utf8_lossy(raw).trim_end_matches('\r').to_string();
*pos += end + 1;
Ok(s)
};
@@ -188,8 +221,9 @@ pub fn decode(b: &[u8], limits: &Limits) -> Result<Picture> {
}
let res = line(&mut pos)?;
let bad = Error::Malformed("bad resolution line");
let t: Vec<&str> = res.split_whitespace().collect();
let &[a1, n1, a2, n2] = t.as_slice().first_chunk::<4>().ok_or(bad.clone())?;
// Tokens after the fourth are ignored, so they are not collected.
let mut t = res.split_whitespace();
let (Some(a1), Some(n1), Some(a2), Some(n2)) = (t.next(), t.next(), t.next(), t.next()) else { return Err(bad) };
let ((x1, p1), (x2, p2)) = (axis(a1).ok_or(bad.clone())?, axis(a2).ok_or(bad.clone())?);
if x1 == x2 {
return Err(Error::Malformed("resolution line names one axis twice"));
@@ -205,6 +239,10 @@ pub fn decode(b: &[u8], limits: &Limits) -> Result<Picture> {
if pixels > limits.max_pixels {
return Err(Error::LimitExceeded("pixel count"));
}
// One scan line of RGBE pixels and the float picture, each within the target's largest allocation.
let scan_len = alloc_len(u64::from(if x1 { height } else { width }), size_of::<[u8; 4]>(), max_alloc_bytes);
let rgb_len = pixels.checked_mul(3).and_then(|floats| alloc_len(floats, size_of::<f32>(), max_alloc_bytes));
let (Some(scan_len), Some(total)) = (scan_len, rgb_len) else { return Err(Error::LimitExceeded("pixel count")) };
// A scan line takes at least a few bits of file, so a header cannot ask for more than the data has.
if (b.len().saturating_sub(pos) as u64).saturating_mul(4096) < pixels {
return Err(Error::Malformed("truncated pixel data"));
@@ -212,12 +250,11 @@ pub fn decode(b: &[u8], limits: &Limits) -> Result<Picture> {
// Validate every encoded scan line before allocating the float picture: a short file could
// otherwise ask for the whole limit of zeroed pixels and only then fail on its first line.
let pixel_data = pos;
let mut scan = vec![[0u8; 4]; n2];
let mut scan = vec![[0u8; 4]; scan_len];
for _ in 0..n1 {
scanline(b, &mut pos, &mut scan)?;
}
let total = w.checked_mul(h).and_then(|n| n.checked_mul(3)).ok_or(Error::LimitExceeded("pixel count"))?;
let mut rgb = vec![0f32; total];
pos = pixel_data;
for i in 0..n1 {
+54
View File
@@ -142,3 +142,57 @@ fn limits_are_checked_before_allocating() {
assert_eq!(decode(&long, &Limits { max_header: 8, ..Limits::default() }), Err(Error::Malformed("truncated header")));
assert_eq!((Limits::default().max_pixels, Limits::default().max_header), (1 << 26, 64 << 10));
}
/// `isize::MAX` on a 32-bit target such as `wasm32`.
const BOUND_32: u64 = i32::MAX as u64;
#[test]
fn buffer_lengths_respect_target_isize_bound() {
// A scan line of RGBE pixels, 4 bytes each.
assert_eq!(alloc_len(536_870_911, 4, BOUND_32), Some(536_870_911));
assert_eq!(alloc_len(536_870_912, 4, BOUND_32), None);
assert_eq!(alloc_len(u64::from(u32::MAX), 4, BOUND_32), None);
// The float picture: 3 floats of 4 bytes a pixel.
assert_eq!(alloc_len(178_956_970 * 3, 4, BOUND_32), Some(178_956_970 * 3));
assert_eq!(alloc_len(178_956_971 * 3, 4, BOUND_32), None);
// The default pixel limit fits a 32-bit target.
assert_eq!(alloc_len(Limits::default().max_pixels * 3, 4, BOUND_32), Some(3 << 26));
assert_eq!(checked_byte_len(u64::MAX, 4), None);
assert_eq!(alloc_len(u64::MAX, 1, MAX_ALLOC_BYTES), None);
}
#[test]
fn raised_pixel_limit_stops_at_the_target_bound() {
let open = Limits { max_pixels: u64::MAX, ..Limits::default() };
// 2 × 2 needs an 8-byte scan line and a 48-byte float picture.
let ok = file("-Y 2 +X 2", &[0; 16]);
assert!(decode_within(&ok, &open, 48).is_ok());
assert_eq!(decode_within(&ok, &open, 47), Err(Error::LimitExceeded("pixel count")));
// A 1 × 536,870,912 picture is past the 32-bit bound in both buffers; refused before
// anything is allocated, ahead of the scan-line validation.
let wide = file("-Y 1 +X 536870912", &[0; 131_072]);
assert_eq!(decode_within(&wide, &open, BOUND_32), Err(Error::LimitExceeded("pixel count")));
// 178,956,971 one-pixel scan lines fit the scan buffer but not the float picture.
let tall = file("-Y 178956971 +X 1", &[0; 43_692]);
assert_eq!(decode_within(&tall, &open, BOUND_32), Err(Error::LimitExceeded("pixel count")));
}
#[test]
fn header_lines_are_measured_after_lossy_conversion() {
// `#` and ten bytes that are not UTF-8: 11 bytes in the file, 31 as text.
let mut f = b"#?RADIANCE\n#".to_vec();
f.extend_from_slice(&[0xff; 10]);
f.extend_from_slice(b"\n\n-Y 1 +X 1\n\0\0\0\0");
assert_eq!(lossy_len(&f[11..22]), Some(31));
assert!(decode_within(&f, &Limits::default(), 31).is_ok());
assert_eq!(decode_within(&f, &Limits::default(), 30), Err(Error::LimitExceeded("header length")));
assert_eq!(lossy_len(b"ok \xe2\x82"), Some(6));
assert_eq!(lossy_len(b""), Some(0));
}
#[test]
fn resolution_tokens_after_the_fourth_are_ignored() {
let f = dec(&file("-Y 1 +X 1 a b c d e f", &[0; 4])).unwrap();
assert_eq!((f.width, f.height), (1, 1));
assert_eq!(dec(&file("-Y 1 +X", &[0; 4])), Err(Error::Malformed("bad resolution line")));
}
+5 -1
View File
@@ -13,7 +13,7 @@ workspace = true
[features]
corpus = []
default = []
avif = ["image/avif"]
avif = ["image/avif", "dep:ravif", "dep:rav1e", "dep:avif-serialize"]
heif = ["dep:craft-heif"]
[dependencies]
@@ -33,6 +33,10 @@ craft-jpeg = { workspace = true }
craft-metadata = { workspace = true }
zune-jpegxl = { version = "=0.5.2", default-features = false, features = ["std"] }
craft-heif = { workspace = true, optional = true }
ravif = { version = "0.13", default-features = false, optional = true }
rav1e = { version = "0.8", default-features = false, optional = true }
avif-serialize = { version = "0.8", optional = true }
hayro-jpeg2000 = { version = "=0.3.5", default-features = false, features = ["std", "simd"] }
[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
rayon = { workspace = true }
+2
View File
@@ -1,3 +1,4 @@
pub(crate) mod avif;
pub(crate) mod dds;
pub(crate) mod dds_bc;
pub(crate) mod deep_exr;
@@ -10,6 +11,7 @@ pub(crate) mod gif_frames;
pub(crate) mod gif_palette;
pub(crate) mod heif;
pub(crate) mod iff;
pub(crate) mod jp2;
pub(crate) mod jpeg;
pub(crate) mod jxl;
pub(crate) mod pcx;
+211
View File
@@ -0,0 +1,211 @@
//! AVIF encoding helpers (8/16-bit SDR via `ravif` and 10-bit 4:4:4 BT.2020 HDR via `rav1e` + `avif-serialize`).
use crate::{CodecError, Format, Image};
/// Transfer function for [`encode_avif_hdr`].
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum HdrTransfer {
Pq,
Hlg,
}
/// Absolute luminance of SDR white in an HDR file (ITU-R BT.2408 reference white), cd/m^2.
pub const HDR_REFERENCE_WHITE_NITS: f32 = 203.0;
#[cfg(all(feature = "avif", not(target_arch = "wasm32")))]
fn pq_encode(nits: f32) -> f32 {
const M1: f32 = 2610.0 / 16384.0;
const M2: f32 = 2523.0 / 4096.0 * 128.0;
const C1: f32 = 3424.0 / 4096.0;
const C2: f32 = 2413.0 / 4096.0 * 32.0;
const C3: f32 = 2392.0 / 4096.0 * 32.0;
let y = (nits / 10_000.0).clamp(0.0, 1.0).powf(M1);
((C1 + C2 * y) / (1.0 + C3 * y)).powf(M2)
}
#[cfg(all(feature = "avif", not(target_arch = "wasm32")))]
fn hlg_signal(rgb: [f32; 3]) -> [f32; 3] {
const A: f32 = 0.17883277;
const B: f32 = 0.28466892;
const C: f32 = 0.559_910_7;
rgb.map(|v| {
let s = if v.is_finite() { v.clamp(0.0, 12.0) / 12.0 } else { 0.0 };
if s <= 1.0 / 12.0 { (3.0 * s).sqrt() } else { A * (12.0 * s - B).ln() + C }
})
}
/// Encode an 8-bit or 16-bit SDR `Image` as AVIF (`4:4:4`, 10-bit AV1) with `quality` (`1..=100`)
/// and `speed` (`1..=10`).
pub fn encode_avif_with_speed(img: &Image, quality: u8, speed: u8) -> Result<Vec<u8>, CodecError> {
#[cfg(all(feature = "avif", not(target_arch = "wasm32")))]
{
let mut enc =
ravif::Encoder::new().with_quality(f32::from(quality.clamp(1, 100))).with_speed(speed.clamp(1, 10)).with_bit_depth(ravif::BitDepth::Ten);
let alpha_mode = if img.layout().has_alpha() { ravif::AlphaColorMode::UnassociatedClean } else { ravif::AlphaColorMode::UnassociatedDirty };
enc = enc.with_alpha_color_mode(alpha_mode);
let w = img.width() as usize;
let h = img.height() as usize;
if let Some(s16) = img.to_u16_samples() {
let ch = img.layout().channels();
let mut planes = Vec::with_capacity(w * h);
let mut a_plane = if img.layout().has_alpha() { Some(Vec::with_capacity(w * h)) } else { None };
for px in s16.chunks_exact(ch) {
let (r, g, b, a) = match ch {
1 => (px[0], px[0], px[0], u16::MAX),
2 => (px[0], px[0], px[0], px[1]),
3 => (px[0], px[1], px[2], u16::MAX),
_ => (px[0], px[1], px[2], px[3]),
};
let (rf, gf, bf) = (f32::from(r) / 65535.0, f32::from(g) / 65535.0, f32::from(b) / 65535.0);
let y = 0.299 * rf + 0.587 * gf + 0.114 * bf;
let cb = (bf - y) * (0.5 / (1.0 - 0.114)) + 0.5;
let cr = (rf - y) * (0.5 / (1.0 - 0.299)) + 0.5;
let q10 = |v: f32| (v * 1023.0).round().clamp(0.0, 1023.0) as u16;
planes.push([q10(y), q10(cb), q10(cr)]);
if let Some(ap) = &mut a_plane {
ap.push(q10(f32::from(a) / 65535.0));
}
}
let alpha = a_plane.map(Vec::into_iter);
let res = enc
.encode_raw_planes_10_bit(w, h, planes, alpha, ravif::PixelRange::Full, ravif::MatrixCoefficients::BT601)
.map_err(|e| CodecError::encode(Format::Avif, e))?;
return Ok(res.avif_file);
}
let rgba = img.to_rgba8();
let px: Vec<ravif::RGBA8> = rgba.as_chunks::<4>().0.iter().map(|c| ravif::RGBA8::new(c[0], c[1], c[2], c[3])).collect();
let res = enc.encode_rgba(ravif::Img::new(&px[..], w, h)).map_err(|e| CodecError::encode(Format::Avif, e))?;
Ok(res.avif_file)
}
#[cfg(not(all(feature = "avif", not(target_arch = "wasm32"))))]
{
let _ = (img, quality, speed);
Err(CodecError::unsupported(Format::Avif, "AVIF encoding is not available in this build"))
}
}
/// Encode linear BT.2020 HDR `rgb` (`width * height * 3` floats, `1.0` = `203` cd/m^2) as
/// 10-bit 4:4:4 BT.2020 PQ or HLG AVIF.
pub fn encode_avif_hdr(
width: u32,
height: u32,
rgb: &[f32],
quality: u8,
speed: u8,
exif: Option<&[u8]>,
transfer: HdrTransfer,
) -> Result<Vec<u8>, CodecError> {
let (w, h) = (width as usize, height as usize);
let n = w.checked_mul(h).ok_or_else(|| CodecError::encode(Format::Avif, "image too large"))?;
if n == 0 || n.checked_mul(3).is_none_or(|need| rgb.len() < need) {
return Err(CodecError::encode(Format::Avif, "HDR AVIF: sample buffer too short"));
}
#[cfg(all(feature = "avif", not(target_arch = "wasm32")))]
{
use rav1e::prelude::*;
const K: [f32; 3] = [0.2627, 0.6780, 0.0593];
let mut max_nits = 0f32;
let mut sum_nits = 0f64;
let planes: Vec<[u16; 3]> = rgb
.as_chunks::<3>()
.0
.iter()
.take(n)
.map(|c| {
let nits = [c[0], c[1], c[2]].map(|v| (if v.is_finite() { v.max(0.0) } else { 0.0 }) * HDR_REFERENCE_WHITE_NITS);
let y_nits = K[0] * nits[0] + K[1] * nits[1] + K[2] * nits[2];
max_nits = max_nits.max(nits[0].max(nits[1]).max(nits[2]));
sum_nits += f64::from(y_nits);
let [r, g, b] = match transfer {
HdrTransfer::Pq => nits.map(pq_encode),
HdrTransfer::Hlg => hlg_signal([c[0], c[1], c[2]]),
};
let y = K[0] * r + K[1] * g + K[2] * b;
let cb = (b - y) / (2.0 * (1.0 - K[2])) + 0.5;
let cr = (r - y) / (2.0 * (1.0 - K[0])) + 0.5;
[y, cb, cr].map(|v| (v * 1023.0).round().clamp(0.0, 1023.0) as u16)
})
.collect();
let q = f32::from(quality.clamp(1, 100)) / 100.0;
let x = if q >= 0.82 {
(1.0 - q) * 2.6
} else if q > 0.25 {
1.0 - 0.125 - q * 0.5
} else {
1.0 - q
};
let quantizer = (x * 255.0).round() as usize;
let mut ec = EncoderConfig::with_speed_preset(speed.clamp(1, 10));
ec.width = w;
ec.height = h;
ec.time_base = Rational::new(1, 1);
ec.bit_depth = 10;
ec.chroma_sampling = ChromaSampling::Cs444;
ec.pixel_range = PixelRange::Full;
ec.color_description = Some(ColorDescription {
color_primaries: ColorPrimaries::BT2020,
transfer_characteristics: match transfer {
HdrTransfer::Pq => TransferCharacteristics::SMPTE2084,
HdrTransfer::Hlg => TransferCharacteristics::HLG,
},
matrix_coefficients: MatrixCoefficients::BT2020NCL,
});
let cll = (max_nits.ceil().clamp(1.0, 10_000.0) as u16, (sum_nits / n as f64).ceil().clamp(1.0, 10_000.0) as u16);
ec.content_light =
(transfer == HdrTransfer::Pq).then_some(ContentLight { max_content_light_level: cll.0, max_frame_average_light_level: cll.1 });
ec.still_picture = true;
ec.quantizer = quantizer;
ec.min_quantizer = quantizer.min(255) as u8;
ec.speed_settings.multiref = false;
ec.speed_settings.rdo_lookahead_frames = 1;
ec.speed_settings.scene_detection_mode = SceneDetectionSpeed::None;
let mut ctx: Context<u16> = Config::new().with_encoder_config(ec).new_context().map_err(|e| CodecError::encode(Format::Avif, e))?;
let mut frame = ctx.new_frame();
{
let mut it = planes.iter();
let mut fp = frame.planes.iter_mut();
let (Some(py), Some(pu), Some(pv)) = (fp.next(), fp.next(), fp.next()) else {
return Err(CodecError::encode(Format::Avif, "AV1: frame has no planes"));
};
let (mut sy, mut su, mut sv) = (py.mut_slice(Default::default()), pu.mut_slice(Default::default()), pv.mut_slice(Default::default()));
for ((ry, ru), rv) in sy.rows_iter_mut().zip(su.rows_iter_mut()).zip(sv.rows_iter_mut()).take(h) {
for ((y, u), v) in ry.iter_mut().zip(ru.iter_mut()).zip(rv.iter_mut()).take(w) {
let Some(p) = it.next() else { break };
(*y, *u, *v) = (p[0], p[1], p[2]);
}
}
}
ctx.send_frame(frame).map_err(|e| CodecError::encode(Format::Avif, e))?;
ctx.flush();
let mut av1 = Vec::new();
loop {
match ctx.receive_packet() {
Ok(mut p) if p.frame_type == FrameType::KEY => av1.append(&mut p.data),
Ok(_) => {}
Err(EncoderStatus::Encoded | EncoderStatus::LimitReached) => break,
Err(e) => return Err(CodecError::encode(Format::Avif, e)),
}
}
use avif_serialize::constants as c;
let mut a = avif_serialize::Aviffy::new();
a.set_matrix_coefficients(c::MatrixCoefficients::Bt2020Ncl)
.set_transfer_characteristics(match transfer {
HdrTransfer::Pq => c::TransferCharacteristics::Smpte2084,
HdrTransfer::Hlg => c::TransferCharacteristics::Hlg,
})
.set_color_primaries(c::ColorPrimaries::Bt2020)
.set_full_color_range(true);
if transfer == HdrTransfer::Pq {
a.set_content_light_level(cll.0, cll.1);
}
if let Some(exif) = exif {
a.set_exif(exif.to_vec());
}
Ok(a.to_vec(&av1, None, width, height, 10))
}
#[cfg(not(all(feature = "avif", not(target_arch = "wasm32"))))]
{
let _ = (width, height, rgb, quality, speed, exif, transfer);
Err(CodecError::unsupported(Format::Avif, "AVIF encoding is not available in this build"))
}
}
+242
View File
@@ -0,0 +1,242 @@
//! JPEG 2000 (JP2 container and raw J2K codestream) decoding via `hayro-jpeg2000`.
//!
//! Decodes within `Limits`, rejecting unsupported JPX multi-layer/composition boxes and
//! checking declared SIZ/tile/palette/channel-definition bounds before pixel allocation.
use hayro_jpeg2000::{ColorSpace, DecodeSettings, DecoderContext, Image as Jp2Image};
use crate::Format;
use crate::error::CodecError;
use crate::image::{ChannelLayout, Image, SampleType};
use crate::options::Limits;
const F: Format = Format::Jp2;
const JP2_SIGNATURE: &[u8] = b"\0\0\0\x0cjP \r\n\x87\n";
const MAX_PROFILE: usize = 4 * 1024 * 1024;
const MAX_TILES: u64 = 65_535;
const TILE_COMPONENT_BYTES: u64 = 256;
/// Boxes at one JP2 nesting level. Invalid lengths stop the walk at that level.
fn boxes(b: &[u8]) -> impl Iterator<Item = (&[u8], &[u8])> {
let mut at = 0usize;
std::iter::from_fn(move || {
let header = b.get(at..at.checked_add(8)?)?;
let size = u32::from_be_bytes(header.get(..4)?.try_into().ok()?);
let (length, head) = match size {
0 => (b.len().checked_sub(at)?, 8usize),
1 => (usize::try_from(u64::from_be_bytes(b.get(at.checked_add(8)?..at.checked_add(16)?)?.try_into().ok()?)).ok()?, 16usize),
n => (n as usize, 8usize),
};
if length < head {
return None;
}
let end = at.checked_add(length)?;
let data = b.get(at.checked_add(head)?..end)?;
let ty = header.get(4..8)?;
at = end;
Some((ty, data))
})
}
fn unsupported_jpx_content(bytes: &[u8]) -> bool {
fn association_has_content(data: &[u8], depth: usize) -> bool {
if depth >= 16 {
return true;
}
boxes(data).any(|(ty, child)| {
matches!(ty, b"jp2c" | b"jpch" | b"jplh" | b"comp" | b"ftbl") || (ty == b"asoc" && association_has_content(child, depth + 1))
})
}
let mut codestreams = 0u8;
for (ty, data) in boxes(bytes) {
match ty {
b"jp2c" => {
codestreams = codestreams.saturating_add(1);
if codestreams > 1 {
return true;
}
}
b"jpch" | b"jplh" | b"comp" | b"ftbl" => return true,
b"asoc" if association_has_content(data, 0) => return true,
_ => {}
}
}
false
}
fn codestream_size(bytes: &[u8]) -> Option<(u64, u32, u32, u64)> {
let stream = if bytes.starts_with(b"\xff\x4f") { bytes } else { boxes(bytes).find_map(|(ty, data)| (ty == b"jp2c").then_some(data))? };
if stream.get(..4)? != b"\xff\x4f\xff\x51" {
return None;
}
let length = u16::from_be_bytes(stream.get(4..6)?.try_into().ok()?) as usize;
let count = u16::from_be_bytes(stream.get(40..42)?.try_into().ok()?) as usize;
if count == 0 || length != 38usize.checked_add(count.checked_mul(3)?)? || stream.get(4..4usize.checked_add(length)?)?.len() != length {
return None;
}
let be32 = |range: std::ops::Range<usize>| stream.get(range).and_then(|v| v.try_into().ok()).map(u32::from_be_bytes);
let width = be32(8..12)?.checked_sub(be32(16..20)?)?;
let height = be32(12..16)?.checked_sub(be32(20..24)?)?;
let tiles = |grid: u32, offset: u32, tile: u32| match (grid.checked_sub(offset), tile) {
(Some(span), 1..) => Some(u64::from(span).div_ceil(u64::from(tile))),
_ => None,
};
let across = tiles(be32(8..12)?, be32(32..36)?, be32(24..28)?)?;
let down = tiles(be32(12..16)?, be32(36..40)?, be32(28..32)?)?;
Some((count as u64, width, height, across.checked_mul(down)?))
}
fn single_header_boxes(bytes: &[u8]) -> bool {
let mut headers = boxes(bytes).filter(|(ty, _)| *ty == b"jp2h");
let (Some((_, header)), None) = (headers.next(), headers.next()) else {
return false;
};
[b"pclr", b"cmap", b"cdef"].iter().all(|kind| boxes(header).filter(|(ty, _)| ty == kind).count() <= 1)
}
fn channel_definitions(bytes: &[u8]) -> Option<u64> {
if bytes.starts_with(b"\xff\x4f") {
return None;
}
let header = boxes(bytes).find_map(|(ty, data)| (ty == b"jp2h").then_some(data))?;
let cdef = boxes(header).find_map(|(ty, data)| (ty == b"cdef").then_some(data))?;
let count = cdef.get(..2).and_then(|n| n.try_into().ok()).map_or(0, |n: [u8; 2]| usize::from(u16::from_be_bytes(n)));
let Some(entries) = cdef.get(2..).filter(|rest| count > 0 && rest.len() == count * 6) else {
return Some(0);
};
let mut defs: Vec<[u16; 3]> =
entries.as_chunks::<6>().0.iter().map(|&[a, b, c, d, e, f]| [[a, b], [c, d], [e, f]].map(u16::from_be_bytes)).collect();
defs.sort_unstable();
let opacity = defs.last().is_some_and(|&[_, kind, association]| kind == 1 && association == 0);
let colors = defs.len() - usize::from(opacity);
let mut seen = vec![false; colors];
let layout_ok = defs.iter().enumerate().all(|(i, &[channel, kind, association])| {
usize::from(channel) == i
&& (i >= colors
|| (kind == 0
&& usize::from(association).checked_sub(1).and_then(|slot| seen.get_mut(slot)).is_some_and(|s| !std::mem::replace(s, true))))
});
Some(if layout_ok { defs.len() as u64 } else { 0 })
}
fn palette_columns(bytes: &[u8], components: u64) -> Result<Option<u64>, ()> {
if bytes.starts_with(b"\xff\x4f") {
return Ok(None);
}
let Some(header) = boxes(bytes).find_map(|(ty, data)| (ty == b"jp2h").then_some(data)) else {
return Ok(None);
};
let Some(palette) = boxes(header).find_map(|(ty, data)| (ty == b"pclr").then_some(data)) else {
return Ok(None);
};
let columns = palette.get(2).copied().ok_or(())?;
let depths = palette.get(3..3 + usize::from(columns)).ok_or(())?;
if columns == 0 || depths.iter().any(|&d| d & 0x80 != 0 || (d & 0x7f) + 1 > 31) {
return Err(());
}
let Some(mapping) = boxes(header).find_map(|(ty, data)| (ty == b"cmap").then_some(data)) else {
return Ok(Some(u64::from(columns)));
};
if mapping.len() != usize::from(columns) * 4 {
return Err(());
}
for &[c0, c1, kind, column] in mapping.as_chunks::<4>().0 {
let valid = u64::from(u16::from_be_bytes([c0, c1])) < components
&& match kind {
0 => true,
1 => column < columns,
_ => false,
};
if !valid {
return Err(());
}
}
Ok(Some(u64::from(columns)))
}
pub(crate) fn decode(bytes: &[u8], limits: &Limits) -> Result<Image, CodecError> {
let malformed = |msg: &str| CodecError::malformed(F, msg);
if bytes.starts_with(JP2_SIGNATURE) && unsupported_jpx_content(bytes) {
return Err(CodecError::unsupported(F, "unsupported color space or JPX content"));
}
if bytes.starts_with(JP2_SIGNATURE) && !single_header_boxes(bytes) {
return Err(malformed("invalid JP2 header boxes"));
}
let (codestream_channels, declared_w, declared_h, tile_count) = codestream_size(bytes).ok_or_else(|| malformed("invalid codestream SIZ"))?;
if tile_count == 0 || tile_count > MAX_TILES {
return Err(malformed("invalid tile count"));
}
let max_alloc = limits.max_alloc;
let declared_pixels = u64::from(declared_w).checked_mul(u64::from(declared_h));
if declared_w == 0
|| declared_h == 0
|| declared_w > limits.max_width
|| declared_h > limits.max_height
|| declared_pixels.is_none_or(|n| n > limits.max_pixels)
|| declared_pixels.and_then(|n| n.checked_mul(codestream_channels)).and_then(|n| n.checked_mul(4)).is_none_or(|n| n > max_alloc)
|| tile_count.checked_mul(codestream_channels).and_then(|n| n.checked_mul(TILE_COMPONENT_BYTES)).is_none_or(|n| n > max_alloc)
{
return Err(CodecError::LimitExceeded(format!("dimensions {declared_w}x{declared_h} exceed decode limits")));
}
let header = boxes(bytes).find_map(|(ty, data)| (ty == b"jp2h").then_some(data)).unwrap_or_default();
if boxes(header).any(|(ty, data)| ty == b"colr" && data.len() > MAX_PROFILE + 3) {
return Err(CodecError::unsupported(F, "ICC profile exceeds 4 MiB limit"));
}
let palette = palette_columns(bytes, codestream_channels).map_err(|()| malformed("invalid JP2 palette"))?;
let palette_rows = boxes(header).find_map(|(ty, data)| (ty == b"pclr").then(|| data.get(..2)).flatten());
if let (Some(columns), Some(&[r0, r1])) = (palette, palette_rows)
&& u64::from(u16::from_be_bytes([r0, r1])) * (columns * 8 + 24) > max_alloc
{
return Err(CodecError::LimitExceeded("JP2 palette exceeds max_alloc".into()));
}
let image = Jp2Image::new(bytes, &DecodeSettings::default()).map_err(|e| malformed(&format!("{e:?}")))?;
let (w, h) = (image.width(), image.height());
let color = image.color_space();
let (channels, icc) = match color {
ColorSpace::Gray => (1u8, None),
ColorSpace::RGB => (3u8, None),
ColorSpace::CMYK => (4u8, None),
ColorSpace::Icc { num_channels: ch @ (1 | 3 | 4), profile } if profile.len() <= MAX_PROFILE => (*ch, Some(profile.to_vec())),
_ => return Err(CodecError::unsupported(F, "unsupported JPEG 2000 color space")),
};
let has_alpha = image.has_alpha();
let stride = u64::from(channels) + u64::from(has_alpha);
if palette.is_some_and(|columns| columns != stride) {
return Err(malformed("JP2 palette columns do not match output channels"));
}
if channel_definitions(bytes).is_some_and(|count| count != stride || count != palette.unwrap_or(codestream_channels)) {
return Err(malformed("JP2 channel definitions do not match output channels"));
}
let layout = match (channels, has_alpha) {
(1, false) => ChannelLayout::Gray,
(1, true) => ChannelLayout::GrayA,
(3, false) => ChannelLayout::Rgb,
(3, true) => ChannelLayout::Rgba,
(4, false) => ChannelLayout::Cmyk,
(4, true) => ChannelLayout::CmykA,
_ => return Err(CodecError::unsupported(F, "unsupported channel count")),
};
limits.check(w, h, layout, SampleType::U8)?;
let plane_channels = codestream_channels.max(stride).max(palette.unwrap_or(0));
let pixels = u64::from(w).checked_mul(u64::from(h)).ok_or_else(|| CodecError::LimitExceeded("pixel count overflow".into()))?;
let size = pixels.checked_mul(stride).ok_or_else(|| CodecError::LimitExceeded("sample count overflow".into()))?;
let plane_bytes =
pixels.checked_mul(plane_channels).and_then(|n| n.checked_mul(4)).ok_or_else(|| CodecError::LimitExceeded("plane overflow".into()))?;
let scratch_bytes = plane_bytes
.checked_mul(2)
.and_then(|n| n.checked_add(pixels.checked_mul(8)?))
.ok_or_else(|| CodecError::LimitExceeded("scratch overflow".into()))?;
let working = size
.checked_add(plane_bytes)
.and_then(|n| n.checked_add(scratch_bytes))
.ok_or_else(|| CodecError::LimitExceeded("memory overflow".into()))?;
if working > max_alloc {
return Err(CodecError::LimitExceeded(format!("working set {working} exceeds max_alloc {max_alloc}")));
}
let len = usize::try_from(size).map_err(|_| CodecError::LimitExceeded("buffer does not fit in memory".into()))?;
let mut samples = vec![0u8; len];
image.decode_into(&mut samples, &mut DecoderContext::default()).map_err(|e| malformed(&format!("{e:?}")))?;
let mut out = Image::from_raw(w, h, layout, SampleType::U8, samples)?;
out.icc = icc;
Ok(out)
}
+3
View File
@@ -479,6 +479,9 @@ pub(crate) fn encode(src: &Image, plan: Plan, opts: &EncodeOptions) -> Result<Ve
// Optimized keeps the standard tables until that decoder is updated. Progressive is fine.
let progressive = opts.jpeg_format == JpegFormat::Progressive;
enc.set_progressive(progressive);
if progressive && let Some(scans) = opts.jpeg_progressive_scans {
enc.set_progressive_scans(scans);
}
let optimized = opts.jpeg_format == JpegFormat::Optimized && !subsampled;
enc.set_optimized_huffman_tables(progressive || optimized);
let e = |e: jpeg_encoder::EncodingError| CodecError::encode(F, e);
+13 -1
View File
@@ -42,6 +42,8 @@ pub enum Format {
Dicom,
/// Amiga IFF/ILBM (`FORM ... ILBM`): planar bitplanes with a palette or 24-bit RGB.
Iff,
/// JPEG 2000 (JP2 container or raw J2K codestream): read-only; see [`ASYMMETRIC_EXCEPTIONS`].
Jp2,
}
/// What a format can hold **and** what this crate reads/writes for it.
@@ -98,6 +100,7 @@ pub const ASYMMETRIC_EXCEPTIONS: &[(Format, &str)] = &[
writing needs an HEVC encoder, and the mature ones (x265, libheif) are C, so write stays \
unsupported. Without the feature HEIF is detected but neither read nor written.",
),
(Format::Jp2, "JPEG 2000 decode uses hayro-jpeg2000 (pure Rust); writing JPEG 2000 is not provided."),
];
use ChannelLayout as L;
@@ -110,9 +113,10 @@ const TIFF_LAYOUTS: &[ChannelLayout] = &[L::Gray, L::GrayA, L::Rgb, L::Rgba, L::
impl Format {
/// Every format known to the crate (enabled or not).
pub const ALL: [Format; 23] = [
pub const ALL: [Format; 24] = [
Format::Png,
Format::Jpeg,
Format::Jp2,
Format::Jxl,
Format::Tiff,
Format::WebP,
@@ -171,6 +175,7 @@ impl Format {
Format::Cineon => "Cineon",
Format::Dicom => "DICOM",
Format::Iff => "Amiga IFF",
Format::Jp2 => "JPEG 2000",
}
}
@@ -201,6 +206,7 @@ impl Format {
Format::Cineon => &["cin"],
Format::Dicom => &["dcm", "dicom", "dc3"],
Format::Iff => &["iff", "lbm", "ilbm"],
Format::Jp2 => &["jp2", "j2k", "j2c", "jpf", "jpx"],
}
}
@@ -229,6 +235,7 @@ impl Format {
Format::Cineon => "image/x-cin",
Format::Dicom => "application/dicom",
Format::Iff => "image/x-iff",
Format::Jp2 => "image/jp2",
}
}
@@ -303,6 +310,7 @@ pub fn caps(format: Format) -> FormatCaps {
Format::Cineon => FormatCaps { depths: &[S::U16], layouts: &[L::Gray, L::Rgb], alpha: false, ..base },
Format::Dicom => FormatCaps { read: true, write: false, depths: &[S::U8, S::U16], layouts: &[L::Gray, L::Rgb], alpha: false, ..base },
Format::Iff => FormatCaps { depths: &[S::U8], layouts: &[L::Rgb, L::Rgba], alpha: true, ..base },
Format::Jp2 => FormatCaps { read: true, write: false, layouts: &[L::Gray, L::GrayA, L::Rgb, L::Rgba, L::Cmyk, L::CmykA], icc: true, ..base },
}
}
@@ -320,6 +328,10 @@ pub fn detect(bytes: &[u8]) -> Option<Format> {
if b.starts_with(&[0xFF, 0x0A]) || b.starts_with(b"\0\0\0\x0cJXL \r\n\x87\n") {
return Some(Format::Jxl);
}
// JPEG 2000 container signature box or raw J2K codestream (SOC + SIZ).
if b.starts_with(b"\0\0\0\x0cjP \r\n\x87\n") || b.starts_with(b"\xff\x4f\xff\x51") {
return Some(Format::Jp2);
}
if b.starts_with(b"II*\0") || b.starts_with(b"MM\0*") || b.starts_with(b"II+\0") || b.starts_with(b"MM\0+") {
return Some(Format::Tiff);
}
+4 -1
View File
@@ -33,6 +33,7 @@ pub mod web;
pub use crate::allocation::probe_allocation_size;
pub use crate::cicp::Cicp;
pub use crate::cicp::ContentLightLevel;
pub use crate::codecs::avif::{HDR_REFERENCE_WHITE_NITS, HdrTransfer, encode_avif_hdr, encode_avif_with_speed};
pub use crate::codecs::exr_cryptomatte::{cryptomatte_id, cryptomatte_key, cryptomatte_preview_color};
pub use crate::codecs::gif_frames::{AnimationFrame, MAX_GIF_FRAMES};
pub use crate::codecs::png::{
@@ -61,7 +62,7 @@ pub use crate::resolution::{exif_resolution, export_exif, export_xmp, photoshop_
pub use crate::source_settings::{WebpEncoding, jpeg_quality, webp_encoding};
pub use half::f16;
use crate::codecs::{dds, dicom, dpx, exr, fits, heif, iff, jpeg, jxl, pcx, png, pnm, tiff, via_image, webp, xpm};
use crate::codecs::{dds, dicom, dpx, exr, fits, heif, iff, jp2, jpeg, jxl, pcx, png, pnm, tiff, via_image, webp, xpm};
/// Detect the format and decode with default [`Limits`].
pub fn decode(bytes: &[u8]) -> Result<Image, CodecError> {
@@ -102,6 +103,7 @@ pub fn decode_as_with(format: Format, bytes: &[u8], opts: &DecodeOptions) -> Res
Format::Iff => iff::decode(bytes, l),
Format::OpenExr => exr::decode(bytes, l),
Format::Heif => heif::decode(bytes, l, opts.keep_orientation),
Format::Jp2 => jp2::decode(bytes, l),
Format::Jxl => Err(CodecError::unsupported(format, "JPEG XL reading is not yet available; export is supported")),
Format::Gif | Format::Bmp | Format::Tga | Format::Ico | Format::Qoi | Format::Hdr | Format::Avif => via_image::decode(format, bytes, l),
}?;
@@ -446,6 +448,7 @@ pub fn encode(image: &Image, format: Format, opts: &EncodeOptions) -> Result<Vec
Format::Iff => iff::encode(image, plan),
Format::OpenExr => exr::encode(image, plan, opts),
Format::Heif => Err(CodecError::unsupported(format, "encoding is not available in this build")),
Format::Jp2 => Err(CodecError::unsupported(format, "JPEG 2000 is import-only; save as PNG or TIFF instead")),
Format::Jxl => jxl::encode(image, plan),
Format::Gif | Format::Bmp | Format::Tga | Format::Ico | Format::Qoi | Format::Hdr | Format::Avif => {
via_image::encode(format, image, plan, opts)
+4
View File
@@ -299,6 +299,9 @@ pub struct EncodeOptions {
pub jpeg_chroma_subsampling: bool,
/// JPEG scan layout (baseline, baseline optimized or progressive).
pub jpeg_format: JpegFormat,
/// Optional number of progressive JPEG scans (typically 3..=5). Ignored unless
/// `jpeg_format` is [`JpegFormat::Progressive`].
pub jpeg_progressive_scans: Option<u8>,
pub png_compression: PngCompression,
/// Write Adam7-interlaced PNG.
pub png_interlaced: bool,
@@ -336,6 +339,7 @@ impl Default for EncodeOptions {
jpeg_quality: 90,
jpeg_chroma_subsampling: true,
jpeg_format: JpegFormat::Baseline,
jpeg_progressive_scans: None,
png_compression: PngCompression::Default,
png_interlaced: false,
png_stereo: None,
+33 -6
View File
@@ -286,7 +286,8 @@ pub fn decode_wbmp(bytes: &[u8]) -> Result<(u32, u32, Vec<bool>), CodecError> {
/// JPEG from 8-bit RGB (`rgb.len() == 3·w·h`): quality 1..=100, optional progressive scans and
/// optimised Huffman tables (Save for Web's "Optimized"), optional ICC profile, density, EXIF and
/// XMP. EXIF that doesn't fit in one segment is left out (see [`jpeg_exif_fits`]).
/// XMP. EXIF that doesn't fit in one segment is left out (see [`jpeg_exif_fits`]); XMP that
/// doesn't fit loses its layered-document properties, else is left out too (see [`jpeg_xmp_fits`]).
#[allow(clippy::too_many_arguments)]
pub fn encode_jpeg_rgb8(
width: u32,
@@ -326,11 +327,10 @@ pub fn encode_jpeg_rgb8(
if let Some(seg) = exif.and_then(|x| crate::codecs::jpeg::exif_segment(x, ppi)) {
enc.add_app_segment(1, &seg).map_err(e)?;
}
if let Some(x) = xmp {
// Its `tiff:` resolution, if any, says what the JFIF density says (#1691).
let x = crate::resolution::export_xmp(x, ppi);
let mut seg = b"http://ns.adobe.com/xap/1.0/\0".to_vec();
seg.extend_from_slice(x.as_bytes());
// Its `tiff:` resolution, if any, says what the JFIF density says. A packet past one segment
// loses its layered-document properties, else is left out, as the other JPEG paths do; see
// [`jpeg_xmp_fits`].
if let Some(seg) = xmp.and_then(|x| crate::codecs::jpeg::xmp_segment(x, ppi)) {
enc.add_app_segment(1, &seg).map_err(e)?;
}
if let Some(icc) = icc {
@@ -345,6 +345,12 @@ pub fn jpeg_exif_fits(exif: &[u8], dpi: Option<f32>) -> bool {
crate::codecs::jpeg::exif_segment(exif, dpi.filter(|d| *d >= 1.0).map(|d| (d, d))).is_some()
}
/// Whether [`encode_jpeg_rgb8`] writes `xmp` at `dpi`: it must fit in one APP1 segment, if need
/// be without its layered-document properties.
pub fn jpeg_xmp_fits(xmp: &str, dpi: Option<f32>) -> bool {
crate::codecs::jpeg::xmp_segment(xmp, dpi.filter(|d| *d >= 1.0).map(|d| (d, d))).is_some()
}
#[cfg(test)]
mod tests {
use super::*;
@@ -355,6 +361,27 @@ mod tests {
(w, h, img.convert(crate::ChannelLayout::Rgba, crate::SampleType::U8).data().to_vec())
}
/// XMP past one APP1 segment loses its layered-document properties, and a packet still too
/// large is left out; the JPEG is written either way.
#[test]
fn web_jpeg_oversized_xmp_is_trimmed_or_left_out() {
let rgb = vec![100u8; 8 * 8 * 3];
let ancestors = format!(
"<x:xmpmeta xmlns:x=\"adobe:ns:meta/\"><rdf:Description dc:title=\"kept\"><photoshop:DocumentAncestors>{}</photoshop:DocumentAncestors></rdf:Description></x:xmpmeta>",
"<rdf:li>id</rdf:li>".repeat(5_000)
);
assert!(ancestors.len() > 70_000);
assert!(jpeg_xmp_fits(&ancestors, Some(72.0)), "trimmed, it fits");
let out = encode_jpeg_rgb8(8, 8, &rgb, 80, false, false, None, Some(72.0), None, Some(&ancestors)).unwrap();
let xmp = crate::decode(&out).unwrap().meta.xmp.unwrap_or_default();
assert!(xmp.contains("dc:title=\"kept\"") && !xmp.contains("DocumentAncestors"), "{xmp}");
let big = format!("<x:xmpmeta xmlns:x=\"adobe:ns:meta/\"><!-- {} --></x:xmpmeta>", "x".repeat(70_000));
assert!(!jpeg_xmp_fits(&big, Some(72.0)));
let out = encode_jpeg_rgb8(8, 8, &rgb, 80, false, false, None, Some(72.0), None, Some(&big)).unwrap();
let img = crate::decode(&out).unwrap();
assert_eq!((img.dimensions(), img.meta.xmp), ((8, 8), None), "written without the XMP");
}
fn pattern(w: usize, h: usize, n: usize) -> Vec<u8> {
(0..w * h).map(|i| (((i % w) * 7 + (i / w) * 13 + (i * i) % 5) % n) as u8).collect()
}
+1
View File
@@ -31,6 +31,7 @@ here. There is no writer.
| `<layer>` nodes | 8192 (`MAX_NODES`) |
| `maindoc.xml` | 32 MiB, 512 levels of nesting, no internal DTD subset |
| A pixel file, inflated | 1 GiB (`MAX_LAYER_FILE`) |
| All entries read from one archive | 4 GiB (`MAX_TOTAL`) |
| ICC profile | 16 MiB |
| Tile | 1024 × 1024 px, 64 bytes per pixel, header lines of 256 bytes |
+11 -2
View File
@@ -56,6 +56,10 @@ pub const MAX_MAINDOC: usize = 32 << 20;
pub const MAX_LAYER_FILE: usize = 1 << 30;
/// Most entries the archive may declare; checked before the archive is indexed.
pub const MAX_ENTRIES: u64 = 100_000;
/// Most bytes all the entries read from one archive may expand to together. Each pixel file may be
/// [`MAX_LAYER_FILE`] on its own, so without a total a document of many layers could spend far more
/// than one open should.
pub const MAX_TOTAL: u64 = 4 << 30;
/// Largest ICC profile.
pub const MAX_ICC: usize = 16 << 20;
/// Deepest element nesting of `maindoc.xml`.
@@ -287,8 +291,13 @@ pub struct Archive<'a> {
impl<'a> Archive<'a> {
/// Opens the archive, checks its `mimetype` and reads `maindoc.xml`.
pub fn open(bytes: &'a [u8]) -> Result<Archive<'a>> {
let mut zip =
craft_zip::Archive::open(bytes, craft_zip::Limits { max_entries: MAX_ENTRIES, max_total_bytes: u64::MAX }).map_err(zip_error)?;
Self::open_with(bytes, craft_zip::Limits { max_entries: MAX_ENTRIES, max_total_bytes: MAX_TOTAL })
}
/// [`Archive::open`] with explicit zip limits, so a test can set a small document-wide total
/// ([`MAX_TOTAL`] is what [`Archive::open`] passes).
pub(crate) fn open_with(bytes: &'a [u8], limits: craft_zip::Limits) -> Result<Archive<'a>> {
let mut zip = craft_zip::Archive::open(bytes, limits).map_err(zip_error)?;
// `zip` keeps one entry of a repeated name; which one the writer meant is not known.
if zip.has_duplicate_names() {
return Err(invalid("two entries of the archive share a name"));
+17
View File
@@ -386,6 +386,23 @@ fn an_archive_declaring_too_many_entries_is_refused_before_it_is_indexed() {
);
}
/// Every entry read is charged to one document-wide total: each pixel file may be
/// [`MAX_LAYER_FILE`] on its own, but a document with many of them still has one budget.
#[test]
fn pixel_files_share_one_document_wide_budget() {
let doc = maindoc("RGBA", "");
// `layer_file("x")` reads `<image name>/layers/x`.
let (first, second) = ("img/layers/x", "img/layers/y");
let files: Vec<(&str, Vec<u8>)> = vec![(first, vec![3; 64]), (second, vec![4; 64])];
let bytes = archive(&doc, &files);
// The mimetype and maindoc reads are charged too: room for one 64-byte pixel file and 16 bytes.
let total = doc.len() as u64 + MIMETYPE.len() as u64 + 64 + 16;
let limits = craft_zip::Limits { max_entries: MAX_ENTRIES, max_total_bytes: total };
let mut archive = Archive::open_with(&bytes, limits).unwrap();
assert_eq!(archive.layer_file("x").unwrap().unwrap(), vec![3; 64]);
assert!(matches!(archive.layer_file("y"), Err(Error::Invalid(_))), "the second pixel file is past the total");
}
/// Two entries of one name: `zip` keeps one, and which one the writer meant is not known.
#[test]
fn two_entries_of_one_name_are_refused() {
+4
View File
@@ -243,6 +243,10 @@ let bytes = w.finish_faststart()?.into_inner(); // or finish() for moov-at-end
`ipcm`/`fpcm` + `pcmC` in MP4. A PCM `write_sample` call can hold any whole number of frames, and the
track timescale must equal the sample rate.
- Edit lists: set `TrackConfig::edits` explicitly, or use `media_start` to get a single edit.
- Audio pre-roll: `TrackConfig::roll_distance` puts every sample in a `roll` sample group (`sgpd` +
`sbgp`). Set -1 for AAC with `media_start` at the priming: Apple's decoders apply that edit only
when the track has the group.
- A file starts at the writer's position: chunk offsets count from there.
- Timecode: `add_timecode_track(video, TimecodeConfig, start_frame)` adds a `tmcd` track (with `gmhd`)
and a `tref/tmcd` link from the video track.
- `WriterOptions::metadata` writes `©xxx` text atoms to `udta`.
+149 -12
View File
@@ -51,11 +51,17 @@ pub struct TrackConfig {
pub media_start: Option<i64>,
/// `hdlr` name; a sensible default is used when `None`.
pub handler_name: Option<String>,
/// Audio pre-roll: puts every sample in a `roll` sample group (`sgpd` + `sbgp`, ISO/IEC
/// 14496-12 §10.1) with this roll distance, the number of samples a decoder must decode before
/// (negative) a sample for its output to be correct; -1 for AAC. Apple's decoders take an AAC
/// track's priming from the edit list only when the track has this group. Written by
/// [`Mp4Writer`]; [`FragmentedWriter`] ignores it.
pub roll_distance: Option<i16>,
}
impl TrackConfig {
pub fn new(entry: SampleEntry, timescale: u32) -> Self {
TrackConfig { entry, timescale, language: "und".into(), edits: Vec::new(), media_start: None, handler_name: None }
TrackConfig { entry, timescale, language: "und".into(), edits: Vec::new(), media_start: None, handler_name: None, roll_distance: None }
}
}
@@ -543,6 +549,23 @@ fn write_stbl(b: &mut BoxBuf, t: &WTrack, qt: bool, shift: u64, force_co64: bool
}
}
b.end(m);
if let Some(distance) = t.cfg.roll_distance
&& sample_count > 0
{
// One description, which every sample maps to.
let m = b.start_full(b"sgpd", 1, 0);
b.bytes(b"roll");
b.u32(2);
b.u32(1);
b.i16(distance);
b.end(m);
let m = b.start_full(b"sbgp", 0, 0);
b.bytes(b"roll");
b.u32(1);
b.u32(sample_count);
b.u32(1);
b.end(m);
}
b.end(stbl);
Ok(())
}
@@ -592,12 +615,21 @@ fn validate_track(entry: &SampleEntry, timescale: u32) -> Result<Option<u32>> {
Ok(None)
}
/// The position after `bytes` more. A writer that takes bytes past the last position a file can
/// have is an error here, not an overflow.
fn advance(pos: u64, bytes: usize) -> Result<u64> {
pos.checked_add(bytes as u64).ok_or_else(|| Error::Mux("the file would end past the last position".into()))
}
/// Progressive MP4/MOV writer: `ftyp`, then one `mdat` streamed to `W`, then `moov` at [`finish`](Self::finish)
/// (or moved in front of `mdat` by [`finish_faststart`](Self::finish_faststart)).
pub struct Mp4Writer<W: Write + Seek> {
w: W,
opts: WriterOptions,
tracks: Vec<WTrack>,
/// The writer's position when the file was begun: chunk offsets count from here, the first
/// byte of the file, wherever in the writer that is.
start: u64,
/// Offset of the placeholder box (8 bytes) preceding the mdat header.
pad_pos: u64,
mdat_pos: u64,
@@ -608,18 +640,22 @@ pub struct Mp4Writer<W: Write + Seek> {
}
impl<W: Write + Seek> Mp4Writer<W> {
/// Start a file: writes `ftyp`, a placeholder box and the `mdat` header.
/// Start a file at the writer's current position: writes `ftyp`, a placeholder box and the
/// `mdat` header.
pub fn new(mut w: W, opts: WriterOptions) -> Result<Self> {
let start = w.stream_position()?;
let mut b = BoxBuf::new();
write_ftyp(&mut b, opts.brand);
let pad_pos = start + b.len() as u64;
let pad = b.len() as u64;
b.leaf(if opts.brand == Brand::Mov { b"wide" } else { b"free" }, &[]);
let mdat_pos = start + b.len() as u64;
let mdat = b.len() as u64;
b.leaf(b"mdat", &[]);
// A writer positioned at the very end of what a position can count has no room for the
// header; the positions below are sums that would overflow.
let pos = start.checked_add(b.len() as u64).ok_or_else(|| Error::Mux("the writer's position leaves no room for a file".into()))?;
let (pad_pos, mdat_pos) = (start + pad, start + mdat);
w.write_all(&b.buf)?;
let pos = start + b.len() as u64;
Ok(Mp4Writer { w, opts, tracks: Vec::new(), pad_pos, mdat_pos, pos, last_track: None, chapters: Vec::new() })
Ok(Mp4Writer { w, opts, tracks: Vec::new(), start, pad_pos, mdat_pos, pos, last_track: None, chapters: Vec::new() })
}
/// Add a track; returns its index (track ids are index + 1).
@@ -708,8 +744,8 @@ impl<W: Write + Seek> Mp4Writer<W> {
return Err(too_many_samples());
}
self.w.write_all(s.data)?;
let offset = self.pos;
self.pos += s.data.len() as u64;
let offset = self.pos - self.start;
self.pos = advance(self.pos, s.data.len())?;
let contiguous = self.last_track == Some(track);
self.last_track = Some(track);
let tr = &mut self.tracks[track];
@@ -749,8 +785,8 @@ impl<W: Write + Seek> Mp4Writer<W> {
};
let d = rescale(vd, vts, tts).max(tc_dur as u64).min(u32::MAX as u64) as u32;
self.w.write_all(&start.to_be_bytes())?;
let off = self.pos;
self.pos += 4;
let off = self.pos - self.start;
self.pos = advance(self.pos, 4)?;
self.last_track = None;
let t = &mut self.tracks[i].t;
t.stts.push((1, d));
@@ -807,13 +843,13 @@ impl<W: Write + Seek> Mp4Writer<W> {
}
let id = self.tracks.len() as u32 + 1;
let mut t = Tables::new();
let off = self.pos;
let off = self.pos - self.start;
for (i, c) in self.chapters.iter().enumerate() {
let end = self.chapters.get(i + 1).map_or(duration, |n| n.start);
let d = u32::try_from(end.saturating_sub(c.start)).map_err(|_| Error::Mux("chapter longer than 2^32 movie ticks".into()))?;
let data = text_sample(&c.title);
self.w.write_all(&data)?;
self.pos += data.len() as u64;
self.pos = advance(self.pos, data.len())?;
Tables::push_run(&mut t.stts, 1, d);
Tables::push_run(&mut t.ctts, 1, 0);
t.sizes.push(data.len() as u32);
@@ -1341,4 +1377,105 @@ mod tests {
}
assert_eq!(t.sync_sample_before(5), 3);
}
/// `roll_distance` puts every sample in one `roll` group; without it, or without samples,
/// the track has no sample group.
#[test]
fn roll_distance_is_a_sample_group_over_every_sample() {
let file = |roll: Option<i16>, samples: u32| {
let mut w = Mp4Writer::new(Cursor::new(Vec::new()), WriterOptions::new(Brand::Mp4)).unwrap();
let mut cfg = TrackConfig::new(SampleEntry::aac(vec![0x11, 0x90], 2, 48_000), 48_000);
cfg.roll_distance = roll;
let t = w.add_track(cfg).unwrap();
for _ in 0..samples {
w.write_sample(t, WriteSample { data: &[0; 8], duration: 1024, composition_offset: 0, is_sync: true }).unwrap();
}
w.finish().unwrap().into_inner()
};
let out = file(Some(-1), 5);
let f = crate::isobmff::open(out.as_slice()).unwrap();
let groups = &f.tracks[0].sample_groups;
assert_eq!(groups.len(), 1);
assert_eq!((groups[0].grouping_type, groups[0].runs.as_slice()), (crate::isobmff::FourCc(*b"roll"), [(5, 1)].as_slice()));
assert_eq!(groups[0].descriptions, [(-1i16).to_be_bytes().to_vec()]);
assert_eq!(f.tracks[0].samples.len(), 5);
for out in [file(None, 5), file(Some(-1), 0)] {
assert!(crate::isobmff::open(out.as_slice()).unwrap().tracks[0].sample_groups.is_empty());
}
// The boxes as ISO/IEC 14496-12 §8.9 has them (and ffmpeg writes them): `sgpd` version 1
// with a default description length of 2, one description; `sbgp` version 0, one run.
let sgpd = [&26u32.to_be_bytes()[..], b"sgpd", &[1, 0, 0, 0], b"roll", &[0, 0, 0, 2, 0, 0, 0, 1, 0xFF, 0xFF]].concat();
let sbgp = [&28u32.to_be_bytes()[..], b"sbgp", &[0, 0, 0, 0], b"roll", &[0, 0, 0, 1, 0, 0, 0, 5, 0, 0, 0, 1]].concat();
let both = [sgpd, sbgp].concat();
assert!(out.windows(both.len()).any(|w| w == both));
}
/// A writer positioned where the header's end would pass `u64::MAX` is refused, not overflowed.
#[test]
fn a_writer_at_the_end_of_the_position_range_is_refused() {
for back in [0, 1, 10, 27] {
let mut bytes = [0u8; 8];
let mut sink = Cursor::new(&mut bytes[..]);
sink.set_position(u64::MAX - back);
assert!(matches!(Mp4Writer::new(sink, WriterOptions::new(Brand::Mp4)), Err(Error::Mux(_))), "{back} before the end");
}
}
/// A writer that keeps taking bytes where positions end makes writing fail, not overflow.
#[test]
fn samples_past_the_last_position_are_refused() {
struct Endless(u64);
impl Write for Endless {
fn write(&mut self, data: &[u8]) -> std::io::Result<usize> {
self.0 = self.0.wrapping_add(data.len() as u64);
Ok(data.len())
}
fn flush(&mut self) -> std::io::Result<()> {
Ok(())
}
}
impl Seek for Endless {
fn seek(&mut self, _: SeekFrom) -> std::io::Result<u64> {
Ok(self.0)
}
}
let mut w = Mp4Writer::new(Endless(u64::MAX - 100), WriterOptions::new(Brand::Mp4)).unwrap();
let v = w.add_track(TrackConfig::new(avc_entry(), 1000)).unwrap();
let sample = WriteSample { data: &[0; 40], duration: 40, composition_offset: 0, is_sync: true };
w.write_sample(v, sample).unwrap();
assert!(matches!(w.write_sample(v, sample), Err(Error::Mux(_))));
}
/// A file begun in the middle of a writer is a file from there: its chunk offsets count from
/// its own first byte, with `moov` at the end or in front, a timecode track and chapters.
#[test]
fn a_file_begun_mid_writer_has_offsets_from_its_start() {
let file = |prefix: usize, faststart: bool| {
let mut sink = Cursor::new(vec![0xAA; prefix]);
sink.set_position(prefix as u64);
let mut opts = WriterOptions::new(Brand::Mov);
opts.chapters = vec![Chapter { start: 0, title: "one".into() }];
let mut w = Mp4Writer::new(sink, opts).unwrap();
let v = w.add_track(TrackConfig::new(avc_entry(), 1000)).unwrap();
let tc = TimecodeConfig { timescale: 1000, frame_duration: 40, frames_per_second: 25, ..Default::default() };
w.add_timecode_track(v, tc, 7).unwrap();
for i in 0..4u8 {
w.write_sample(v, WriteSample { data: &[i + 1; 10], duration: 40, composition_offset: 0, is_sync: true }).unwrap();
}
let out = if faststart { w.finish_faststart() } else { w.finish() }.unwrap();
assert_eq!(out.position(), out.get_ref().len() as u64);
out.into_inner()
};
for faststart in [false, true] {
let (plain, offset) = (file(0, faststart), file(100, faststart));
assert!(offset[..100].iter().all(|&b| b == 0xAA));
assert!(offset[100..] == plain, "faststart {faststart}");
let f = crate::isobmff::open(plain.as_slice()).unwrap();
assert_eq!(f.tracks.len(), 3);
for i in 0..4 {
assert_eq!(f.read_sample(plain.as_slice(), 0, i).unwrap(), vec![i as u8 + 1; 10]);
}
assert_eq!(f.read_sample(plain.as_slice(), 1, 0).unwrap(), 7u32.to_be_bytes());
}
}
}
+1
View File
@@ -29,6 +29,7 @@ means. `SVG_COMPOSITE_OPS` lists the names the specification defines.
| Elements under the root stack | 8192 (`MAX_NODES`) |
| `stack.xml` | 16 MiB, 512 levels of nesting, no document type declaration |
| An entry | the caller's limit; `MAX_ENTRY` (512 MiB) is the suggested one for a layer image |
| All entries read from one archive | 4 GiB (`MAX_TOTAL`) |
## ZIP
+11 -2
View File
@@ -51,6 +51,10 @@ pub const MAX_STACK_XML: usize = 16 << 20;
pub const MAX_ENTRY: usize = 512 << 20;
/// Most entries the archive may declare; checked before the archive is indexed.
pub const MAX_ENTRIES: u64 = 100_000;
/// Most bytes all the entries read from one archive may expand to together. Each layer image may
/// be [`MAX_ENTRY`] on its own, so without a total a document of many layers could spend far more
/// than one open should.
pub const MAX_TOTAL: u64 = 4 << 30;
/// Deepest element nesting of `stack.xml`.
pub const MAX_XML_DEPTH: usize = 512;
@@ -363,8 +367,13 @@ pub struct Archive<'a> {
impl<'a> Archive<'a> {
/// Opens the archive, checks its `mimetype` and reads `stack.xml`.
pub fn open(bytes: &'a [u8]) -> Result<Archive<'a>> {
let mut zip =
craft_zip::Archive::open(bytes, craft_zip::Limits { max_entries: MAX_ENTRIES, max_total_bytes: u64::MAX }).map_err(zip_error)?;
Self::open_with_total(bytes, MAX_TOTAL)
}
/// [`Archive::open`], allowing the entries read from the archive to expand to
/// `max_total_bytes` together ([`MAX_TOTAL`] is the default).
pub(crate) fn open_with_total(bytes: &'a [u8], max_total_bytes: u64) -> Result<Archive<'a>> {
let mut zip = craft_zip::Archive::open(bytes, craft_zip::Limits { max_entries: MAX_ENTRIES, max_total_bytes }).map_err(zip_error)?;
// `zip` keeps one entry of a repeated name; which one the writer meant is not known.
if zip.has_duplicate_names() {
return Err(invalid("two entries of the archive share a name"));
+13
View File
@@ -315,6 +315,19 @@ fn an_archive_declaring_too_many_entries_is_refused_before_it_is_indexed() {
);
}
/// Every entry read is charged to one document-wide total, so an archive of many individually
/// allowed entries cannot spend an unbounded amount of memory in one open.
#[test]
fn entries_are_charged_to_one_document_wide_total() {
let stack = "<image w='1' h='1'><stack/></image>";
let bytes = archive(stack, &[("a.png", vec![1; 100]), ("b.png", vec![2; 100])]);
// Room for `stack.xml` and one image, not two.
let mut a = Archive::open_with_total(&bytes, stack.len() as u64 + 120).unwrap();
assert_eq!(a.entry("a.png", MAX_ENTRY).unwrap().unwrap(), vec![1; 100]);
let err = a.entry("b.png", MAX_ENTRY).unwrap_err();
assert!(matches!(&err, Error::Invalid(m) if m.contains("b.png") && m.contains("may expand to")), "{err:?}");
}
/// Two entries of one name: `zip` keeps one, and which one the writer meant is not known.
#[test]
fn two_entries_of_one_name_are_refused() {
+4
View File
@@ -17,6 +17,7 @@ interpret = ["read", "dep:hayro-interpret"]
paths = ["interpret", "dep:kurbo"]
raster = ["interpret", "dep:hayro", "dep:bytemuck"]
write = ["dep:krilla", "dep:thiserror"]
write-svg = ["write", "dep:craft-svg", "dep:krilla-svg", "dep:usvg", "craft-svg/tree-text"]
write-pdf = ["write", "krilla/pdf"]
write-raster = ["dep:flate2", "dep:roxmltree"]
write-simple-text = ["write", "krilla/simple-text"]
@@ -30,6 +31,9 @@ hayro-interpret = { workspace = true, optional = true }
hayro = { workspace = true, optional = true }
bytemuck = { workspace = true, optional = true }
krilla = { workspace = true, optional = true }
craft-svg = { workspace = true, optional = true }
krilla-svg = { version = "=0.8.1", optional = true }
usvg = { version = "=0.47.0", features = ["text"], optional = true }
thiserror = { workspace = true, optional = true }
flate2 = { version = "1.1", default-features = false, features = ["zlib-rs"], optional = true }
roxmltree = { version = "0.21", optional = true }
+10 -3
View File
@@ -10,6 +10,7 @@ No feature is enabled by default.
| `interpret` | `read` plus an app-owned Device interpreter, fonts and CMaps |
| `raster` | `interpret` plus premultiplied RGBA8 rendering |
| `write` | Guarded Krilla authoring; no shared reader dependency |
| `write-svg` | `write` plus bounded SVG-to-PDF vector drawing |
| `write-pdf` | `write` plus Krilla's embedded-PDF support |
| `write-simple-text` | `write` plus Krilla's optional text shaper and `draw_text` |
| `filters` | The `/Filter` chain for editing and writing PDF files: decode and encode, with limits and accounting. No reader or writer dependency |
@@ -201,9 +202,12 @@ PDF files. The reader decrypts on its own and does not use it. It covers revisio
block is ignored and bad padding is left in.
- `permissions()` gives the `/P` flags; for R5/R6 a permission counts only when `/Perms` grants
it too. Owners have every permission.
- `create(&NewEncryption, id0)` builds the `/Encrypt` values for RC4-40, RC4-128, AES-128 or
AES-256. The caller supplies 32 bytes of entropy (`seed`), so the module needs no OS access
and builds for the web. `file_id` derives a file identifier from the same seed.
- `create(&NewEncryption, id0)` builds the `/Encrypt` values for AES-128 or AES-256. It refuses
the legacy RC4-40 and RC4-128 schemes, because RC4 is broken (RFC 7465); `create_legacy`
writes those, for a file that must stay readable by an old reader. `Document::set_encryption`
refuses them too, with `set_encryption_legacy` as the explicit way in. The caller supplies 32
bytes of entropy (`seed`), so the module needs no OS access and builds for the web. `file_id`
derives a file identifier from the same seed.
- `EncryptDict` holds the dictionary's values. The caller reads them from, and writes them to,
its own object model; the module does not parse PDF syntax. Keys and prepared passwords are
zeroized when dropped.
@@ -240,6 +244,9 @@ serialization uses the same backend version as before extraction. It provides:
refuses it. Apps build URI links with it instead of `backend::action::LinkAction`, so a
link target from someone else's document becomes a PDF link only when it is an `http`/`https`
URL with a host or a `mailto` address. A refused target writes no link annotation.
- `write::svg` (feature `write-svg`): bounded SVG/SVGZ text preflight, data-only image
resolution, and vector drawing through krilla-svg. Callers provide font and fallback options;
the adapter enforces input, nesting, embedded-image, destination-area and filter budgets.
- `safe_url` (crate root, any feature): the same rule, for apps that open links themselves,
such as a slide show.
+2 -1
View File
@@ -22,7 +22,8 @@ fn main() {
_ => craft_pdf::cos::Algorithm::Aes256,
};
let mut doc = craft_pdf::cos::Document::open(std::sync::Arc::new(std::fs::read(input).unwrap())).unwrap();
doc.set_encryption(&craft_pdf::cos::NewEncryption {
// `rc4-40` and `rc4-128` are the legacy schemes, which `set_encryption` refuses.
doc.set_encryption_legacy(&craft_pdf::cos::NewEncryption {
algorithm,
user_password: user,
owner_password: owner,
+15 -1
View File
@@ -414,7 +414,20 @@ impl Document {
/// Protect the document with a password (§7.6.4). Takes effect on the next save, which is
/// always a full rewrite. Returns the handler (authenticated as owner).
///
/// The legacy RC4 schemes are refused (RC4 is broken, `RFC 7465`): [`Self::set_encryption_legacy`]
/// writes them for a file an old reader must open.
pub fn set_encryption(&mut self, params: &crate::crypt::NewEncryption) -> Result<(), CosError> {
self.set_encryption_with(params, false)
}
/// [`Self::set_encryption`] with the legacy RC4-40 and RC4-128 schemes allowed. Pass it only
/// for a file that must stay readable by a reader without AES.
pub fn set_encryption_legacy(&mut self, params: &crate::crypt::NewEncryption) -> Result<(), CosError> {
self.set_encryption_with(params, true)
}
fn set_encryption_with(&mut self, params: &crate::crypt::NewEncryption, legacy: bool) -> Result<(), CosError> {
// The file identifier is part of the key; make sure it exists and keep it.
let id = self.trailer.get(b"ID").map(|id| self.resolve(id));
let id0 = match id.as_deref() {
@@ -426,7 +439,8 @@ impl Document {
id
}
};
let h = crate::crypt::create(params, &id0).map_err(|e| CosError::Security(e.to_string()))?;
let built = if legacy { crate::crypt::create_legacy(params, &id0) } else { crate::crypt::create(params, &id0) };
let h = built.map_err(|e| CosError::Security(e.to_string()))?;
let d = h.dict();
let s = |b: &[u8]| Object::String(crate::cos::PdfString { bytes: b.to_vec(), hex: true });
let mut e = Dict::new();
+36 -5
View File
@@ -283,7 +283,7 @@ impl SecurityHandler {
/// different key is refused too.
pub fn authenticate_owner(&self, id0: &[u8], password: &str) -> Result<Self, CryptError> {
let owner = Self::open(self.dict.clone(), id0, Some(password))?;
if owner.auth != Auth::Owner || owner.key != self.key {
if owner.auth != Auth::Owner || !same(owner.key.as_slice(), self.key.as_slice()) {
return Err(CryptError::WrongPassword);
}
Ok(owner)
@@ -539,6 +539,12 @@ fn u_value_r4(d: &EncryptDict, id0: &[u8], key: &[u8]) -> Vec<u8> {
x
}
/// Whether `a` and `b` are equal, in time that depends only on their lengths: password-derived
/// digests, keys and verifiers are compared without stopping at the first differing byte.
fn same(a: &[u8], b: &[u8]) -> bool {
a.len() == b.len() && a.iter().zip(b).fold(0u8, |acc, (x, y)| acc | (x ^ y)) == 0
}
/// Algorithm 6: authenticate a user password; returns the file key.
///
/// Some producers ignore `/EncryptMetadata false` when deriving the key (they omit the
@@ -549,7 +555,7 @@ fn user_key_r4(d: &EncryptDict, id0: &[u8], pw: &[u8]) -> Option<Zeroizing<Vec<u
let key = file_key_r4(d, id0, pw);
let u = u_value_r4(d, id0, &key);
let n = if d.r == 2 { 32 } else { 16 };
(d.u.len() >= n && u[..n] == d.u[..n]).then_some(key)
(d.u.len() >= n && same(&u[..n], &d.u[..n])).then_some(key)
};
check(d).or_else(|| (d.r >= 4 && !d.encrypt_metadata).then(|| check(&EncryptDict { encrypt_metadata: true, ..d.clone() })).flatten())
}
@@ -636,7 +642,8 @@ fn key_r6(d: &EncryptDict, pw: &[u8], owner: bool) -> Result<Option<Zeroizing<Ve
return Err(CryptError::Malformed("/O and /U must be 48 bytes for R5/R6".into()));
}
let (hashed, encrypted, udata) = if owner { (&d.o[..48], &d.oe, &d.u[..48]) } else { (&d.u[..48], &d.ue, &[][..]) };
if *hash_r6(d.r, pw, &hashed[32..40], udata) != hashed[..32] {
let verifier = hash_r6(d.r, pw, &hashed[32..40], udata);
if !same(verifier.as_slice(), &hashed[..32]) {
return Ok(None);
}
if encrypted.len() < 32 {
@@ -651,9 +658,9 @@ fn key_r6(d: &EncryptDict, pw: &[u8], owner: bool) -> Result<Option<Zeroizing<Ve
/// Which encryption to create.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Algorithm {
/// R2, 40-bit RC4 (legacy; for tests and compatibility only).
/// R2, 40-bit RC4 (legacy: [`create`] refuses it, [`create_legacy`] writes it).
Rc4_40,
/// R3, 128-bit RC4.
/// R3, 128-bit RC4 (legacy: [`create`] refuses it, [`create_legacy`] writes it).
Rc4_128,
/// R4, AES-128 crypt filters.
Aes128,
@@ -661,6 +668,14 @@ pub enum Algorithm {
Aes256,
}
impl Algorithm {
/// Whether this is one of the broken legacy ciphers: read for compatibility, and refused for
/// new encryption by [`create`].
pub fn is_legacy(self) -> bool {
matches!(self, Algorithm::Rc4_40 | Algorithm::Rc4_128)
}
}
/// A password as [`create`] prepares it: for R2–R4 its PDFDocEncoding (characters it lacks
/// dropped), at most 32 bytes; for R6 its SASLprep (RFC 4013: soft hyphens and the like removed,
/// other spaces made plain, then NFKC; the password as given if SASLprep refuses it), in UTF-8,
@@ -725,7 +740,23 @@ pub fn file_id(seed: &[u8; 32]) -> Vec<u8> {
}
/// Build the `/Encrypt` values and an authenticated (owner) handler for a new encryption.
///
/// The legacy RC4 schemes are refused, because RC4 is broken (`RFC 7465`) and a file written with
/// it protects nothing: [`create_legacy`] is the explicit way to write them.
pub fn create(params: &NewEncryption, id0: &[u8]) -> Result<SecurityHandler, CryptError> {
if params.algorithm.is_legacy() {
return Err(CryptError::Unsupported("RC4 encryption is legacy (RFC 7465); use create_legacy for a file an old reader must open".into()));
}
create_any(params, id0)
}
/// [`create`] without the RC4 gate: writes RC4-40 and RC4-128 too. For a file that must stay
/// readable by a reader without AES, and for tests that read and write every algorithm.
pub fn create_legacy(params: &NewEncryption, id0: &[u8]) -> Result<SecurityHandler, CryptError> {
create_any(params, id0)
}
fn create_any(params: &NewEncryption, id0: &[u8]) -> Result<SecurityHandler, CryptError> {
// R2 reserves bits 7-32; later revisions reserve bits 7-8 and 13-32.
// Reserved bits must be 1, and bits 1-2 must be 0 (§7.6.4.2).
let reserved = if params.algorithm == Algorithm::Rc4_40 { !0x3F } else { !0xFFF | 0xC0 };
+33 -1
View File
@@ -52,13 +52,45 @@ fn aes_padding_is_added_and_tolerantly_removed() {
const ID: &[u8] = b"0123456789abcdef";
fn new(alg: Algorithm, user: &str, owner: &str, perms: i32) -> SecurityHandler {
create(
// These tests read and write every algorithm, RC4 included.
create_legacy(
&NewEncryption { algorithm: alg, user_password: user, owner_password: owner, permissions: perms, encrypt_metadata: true, seed: [42; 32] },
ID,
)
.unwrap()
}
/// New files are not written with RC4: `create` refuses it, and the explicitly named
/// `create_legacy` is the only way to write it.
#[test]
fn create_refuses_rc4_unless_asked() {
let params = |algorithm| NewEncryption {
algorithm,
user_password: "user",
owner_password: "owner",
permissions: -1,
encrypt_metadata: true,
seed: [42; 32],
};
for (alg, revision) in [(Algorithm::Rc4_40, 2), (Algorithm::Rc4_128, 3)] {
assert!(matches!(create(&params(alg), ID), Err(CryptError::Unsupported(_))), "{alg:?}");
assert_eq!(create_legacy(&params(alg), ID).unwrap().dict().r, revision, "{alg:?}");
}
for alg in [Algorithm::Aes128, Algorithm::Aes256] {
assert!(create(&params(alg), ID).is_ok(), "AES is not legacy: {alg:?}");
}
}
/// Every verifier check goes through this comparison: it reads both sides in full and a value
/// that merely starts the same never matches.
#[test]
fn verifier_comparison_reads_every_byte() {
assert!(super::same(b"", b""));
assert!(super::same(b"0123456789abcdef", b"0123456789abcdef"));
assert!(!super::same(b"0123456789abcdef", b"0123456789abcdee"), "difference in the last byte");
assert!(!super::same(b"0123456789abcdef", b"0123456789abcde"), "shorter value");
}
const ALL: [Algorithm; 4] = [Algorithm::Rc4_40, Algorithm::Rc4_128, Algorithm::Aes128, Algorithm::Aes256];
#[test]
+2
View File
@@ -15,6 +15,8 @@ const _: bool = backend::CRAFT_PRINT_COLOR;
const _: bool = backend::CRAFT_OPTIONAL_CONTENT;
pub mod print;
#[cfg(feature = "write-svg")]
pub mod svg;
use backend::configure::{Archival, Configuration, ConfigurationBuilder, ConfigurationError, PdfVersion};
use backend::text::{Font, Tag};
+176
View File
@@ -0,0 +1,176 @@
//! Bounded SVG parsing and vector drawing on a PDF surface.
//!
//! This adapter owns the usvg version required by krilla-svg. Callers pass their font and
//! fallback options, while this module checks input, embedded SVGs, and output/filter budgets
//! before converting SVG to PDF drawing operations.
use std::sync::Arc;
use std::sync::atomic::{AtomicUsize, Ordering};
use krilla_svg::SurfaceExt;
pub use krilla_svg::SvgSettings;
pub use usvg;
/// Resource limits for parsing SVG and drawing it to PDF.
#[derive(Clone, Copy, Debug)]
pub struct Limits {
/// Maximum decoded bytes in one SVG document.
pub input_bytes: usize,
/// Maximum SVG element and reference depth.
pub depth: usize,
/// Maximum XML nodes in one document.
pub xml_nodes: u32,
/// Maximum total decoded bytes of embedded SVGs.
pub embedded_svg_bytes: usize,
/// Maximum number of embedded SVG documents nested within one another.
pub embedded_svg_depth: usize,
/// Maximum encoded bytes retained for embedded raster images.
pub embedded_image_bytes: usize,
/// Maximum PDF surface area, measured in 96 dpi pixels.
pub vector_pixels: u64,
/// Maximum raster pixels used by filters after `filter_scale` is applied.
pub filter_pixels: u64,
}
impl Default for Limits {
fn default() -> Self {
Self {
input_bytes: 16 * 1024 * 1024,
depth: 64,
xml_nodes: 100_000,
embedded_svg_bytes: 32 * 1024 * 1024,
embedded_svg_depth: 4,
embedded_image_bytes: 32 * 1024 * 1024,
vector_pixels: 256_000_000,
filter_pixels: 256_000_000,
}
}
}
/// Why an SVG could not be parsed or drawn within its limits.
#[derive(Debug, thiserror::Error)]
pub enum Error {
/// The bounded SVG text/XML preflight refused the input.
#[error("SVG preflight failed: {0}")]
Preflight(String),
/// usvg could not construct the SVG tree.
#[error("SVG parsing failed: {0}")]
Parse(String),
/// The requested PDF area or filter raster exceeds its budget.
#[error("SVG drawing exceeds the PDF area or filter budget")]
DrawLimit,
/// krilla-svg refused to draw the parsed tree.
#[error("krilla-svg could not draw the parsed tree")]
Draw,
}
/// An SVG tree parsed within [`Limits`], ready to draw as PDF vectors.
pub struct Document {
tree: usvg::Tree,
limits: Limits,
}
impl Document {
/// Parse SVG/SVGZ bytes after bounded shared preflight. `options` controls the caller's font
/// database, family selection, and fallback policy; its file-reading and image resolvers are
/// replaced with a data-only resolver governed by `limits`.
pub fn parse<'a>(bytes: &[u8], limits: Limits, mut options: usvg::Options<'a>) -> Result<Self, Error> {
let text = bounded_text(bytes, limits.input_bytes, limits).map_err(|e| Error::Preflight(e.to_string()))?;
options.image_href_resolver = image_resolver(limits);
let tree = usvg::Tree::from_str(&text, &options).map_err(|e| Error::Parse(e.to_string()))?;
Ok(Self { tree, limits })
}
/// Draw the parsed tree as PDF vectors. The limits account for the destination size and the
/// renderer's filter scale before krilla-svg allocates filter rasters.
pub fn draw(&self, surface: &mut krilla::surface::Surface<'_>, size: krilla::geom::Size, settings: SvgSettings) -> Result<(), Error> {
let width = f64::from(size.width());
let height = f64::from(size.height());
let scale = f64::from(settings.filter_scale);
if !width.is_finite() || !height.is_finite() || !scale.is_finite() || width <= 0.0 || height <= 0.0 || scale <= 0.0 {
return Err(Error::DrawLimit);
}
let area = width * height * (96.0_f64 / 72.0).powi(2);
let filter_area = area * scale * scale;
if !area.is_finite() || !filter_area.is_finite() || area > self.limits.vector_pixels as f64 || filter_area > self.limits.filter_pixels as f64
{
return Err(Error::DrawLimit);
}
surface.draw_svg(&self.tree, size, settings).ok_or(Error::Draw)
}
}
#[derive(Default)]
struct Usage {
svg_bytes: AtomicUsize,
svg_depth: AtomicUsize,
image_bytes: AtomicUsize,
}
fn shared_limits(bytes: usize, limits: Limits) -> craft_svg::tree::Limits {
craft_svg::tree::Limits {
bytes,
depth: limits.depth,
tree_depth: limits.depth,
refuse_entity_markup: true,
xml_nodes: limits.xml_nodes,
embedded_bytes: limits.embedded_svg_bytes,
embedded_depth: limits.embedded_svg_depth,
..Default::default()
}
}
fn bounded_text(bytes: &[u8], byte_limit: usize, limits: Limits) -> Result<std::borrow::Cow<'_, str>, craft_svg::tree::Error> {
craft_svg::tree::text(bytes, &shared_limits(byte_limit, limits))
}
fn reserve(counter: &AtomicUsize, amount: usize, limit: usize) -> bool {
counter.try_update(Ordering::Relaxed, Ordering::Relaxed, |used| used.checked_add(amount).filter(|next| *next <= limit)).is_ok()
}
fn embedded_svg(usage: &Usage, limits: Limits, bytes: &[u8], options: &usvg::Options<'_>) -> Option<usvg::ImageKind> {
let used = usage.svg_bytes.load(Ordering::Relaxed);
let remaining = limits.embedded_svg_bytes.saturating_sub(used);
let text = bounded_text(bytes, remaining.min(limits.input_bytes), limits).ok()?;
if !reserve(&usage.svg_bytes, text.len(), limits.embedded_svg_bytes) {
return None;
}
let depth = usage.svg_depth.fetch_add(1, Ordering::Relaxed);
if depth >= limits.embedded_svg_depth {
usage.svg_depth.fetch_sub(1, Ordering::Relaxed);
return None;
}
let parsed = usvg::Tree::from_str(&text, options).ok();
usage.svg_depth.fetch_sub(1, Ordering::Relaxed);
parsed.map(usvg::ImageKind::SVG)
}
fn image_resolver(limits: Limits) -> usvg::ImageHrefResolver<'static> {
let usage = Arc::new(Usage::default());
let default_data = usvg::ImageHrefResolver::default_data_resolver();
usvg::ImageHrefResolver {
resolve_data: Box::new(move |mime, bytes, options| {
if mime == "image/svg+xml" || (mime == "text/plain" && (craft_svg::sniff::is_svg(&bytes) || craft_svg::sniff::is_svgz(&bytes))) {
return embedded_svg(&usage, limits, &bytes, options);
}
if !reserve(&usage.image_bytes, bytes.len(), limits.embedded_image_bytes) {
return None;
}
default_data(mime, bytes, options)
}),
resolve_string: Box::new(|_, _| None),
}
}
#[cfg(test)]
mod tests {
use super::{Limits, shared_limits};
#[test]
fn shared_depth_limit_also_bounds_svg_references() {
let limits = shared_limits(1024, Limits { depth: 7, ..Limits::default() });
assert_eq!(limits.depth, 7);
assert_eq!(limits.tree_depth, 7);
}
}
+2 -1
View File
@@ -139,7 +139,8 @@ fn full_rewrites_preserve_graph_across_multiple_object_streams_and_evictions() {
}
fn protect(doc: &mut Document, algorithm: Algorithm) {
doc.set_encryption(&NewEncryption {
// Every algorithm, RC4 included, has to survive a rewrite.
doc.set_encryption_legacy(&NewEncryption {
algorithm,
user_password: "user",
owner_password: "owner",
+6 -4
View File
@@ -39,9 +39,11 @@ fn fixture_with(extra: &str) -> Vec<u8> {
out
}
/// Every algorithm, RC4-40 and RC4-128 included: those two are the legacy schemes, which
/// `set_encryption` refuses.
fn protect(alg: Algorithm, user: &str, owner: &str, permissions: i32) -> Vec<u8> {
let mut doc = Document::open(Arc::new(fixture())).unwrap();
doc.set_encryption(&NewEncryption {
doc.set_encryption_legacy(&NewEncryption {
algorithm: alg,
user_password: user,
owner_password: owner,
@@ -287,7 +289,7 @@ fn signature_contents_stay_unencrypted() {
c.set(b"Test".to_vec(), Object::Array(vec![Object::Ref(sig), Object::Ref(untyped), Object::Ref(note)]))
})
.unwrap();
doc.set_encryption(&NewEncryption {
doc.set_encryption_legacy(&NewEncryption {
algorithm: alg,
user_password: "",
owner_password: "owner",
@@ -423,7 +425,7 @@ fn an_earlier_revision_opens_with_the_documents_own_credentials() {
// Another file, encrypted with other keys: the document's key is no use, and it says so.
let other = {
let mut doc = Document::open(Arc::new(fixture())).unwrap();
doc.set_encryption(&NewEncryption {
doc.set_encryption_legacy(&NewEncryption {
algorithm: alg,
user_password: "user",
owner_password: "owner",
@@ -444,7 +446,7 @@ fn an_earlier_revision_opens_with_the_documents_own_credentials() {
/// instead of as an indirect object.
fn protect_inline(alg: Algorithm, user: &str, owner: &str) -> Vec<u8> {
let mut doc = Document::open(Arc::new(fixture())).unwrap();
doc.set_encryption(&NewEncryption {
doc.set_encryption_legacy(&NewEncryption {
algorithm: alg,
user_password: user,
owner_password: owner,
+3 -2
View File
@@ -122,7 +122,8 @@ fn caller_entropy_makes_the_new_identifier_reproducible() {
fn an_encrypted_rewrite_keeps_the_first_identifier_string_its_key_depends_on() {
for algorithm in [Algorithm::Rc4_128, Algorithm::Aes128, Algorithm::Aes256] {
let mut doc = reopen(source(true));
doc.set_encryption(&NewEncryption {
// The loop covers RC4-128, which `set_encryption` refuses.
doc.set_encryption_legacy(&NewEncryption {
algorithm,
user_password: "user",
owner_password: "owner",
@@ -160,7 +161,7 @@ fn unusable_ids() -> Vec<(&'static str, Option<Object>)> {
/// An encrypted file whose key is derived from the empty string, with its trailer `/ID` replaced by `id`.
fn protected_with_id(algorithm: Algorithm, id: Option<Object>) -> Vec<u8> {
let mut doc = reopen(source_with(Some("/ID [<> <>]")));
doc.set_encryption(&NewEncryption {
doc.set_encryption_legacy(&NewEncryption {
algorithm,
user_password: "user",
owner_password: "owner",

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