diff --git a/.cargo/config.toml b/.cargo/config.toml new file mode 100644 index 000000000..873f4f7aa --- /dev/null +++ b/.cargo/config.toml @@ -0,0 +1,2 @@ +[lints] +cargo.unused_workspace_dependencies = "allow" diff --git a/.coderabbit.yaml b/.coderabbit.yaml new file mode 100644 index 000000000..2408084cf --- /dev/null +++ b/.coderabbit.yaml @@ -0,0 +1,6 @@ +# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json +reviews: + auto_review: + # Dependabot bumps are checked by CI; skip CodeRabbit reviews on them. + ignore_usernames: + - "dependabot[bot]" diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 000000000..5d79390a2 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,2 @@ +# Copies of the vendored krilla source diff, one per patch (see vendor/krilla/README.craft.md). +vendor/krilla/patches/*.patch linguist-generated=true diff --git a/.github/workflows/ai-core.yml b/.github/workflows/ai-core.yml index 4733eaee8..cc8d738ac 100644 --- a/.github/workflows/ai-core.yml +++ b/.github/workflows/ai-core.yml @@ -11,18 +11,30 @@ on: permissions: contents: read +concurrency: + # Pull requests share one group per branch, so a newer push cancels the older run. Every other + # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. + group: ai-core-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + jobs: ai-core: timeout-minutes: 15 strategy: fail-fast: false matrix: - os: [ubuntu-latest, windows-latest, macos-latest] + # macOS runners are kept for releases: macOS runs only when started by hand. + os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} runs-on: ${{ matrix.os }} steps: - - uses: actions/checkout@v4 - - uses: dtolnay/rust-toolchain@stable + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 with: + egress-policy: audit + - uses: actions/checkout@v7 + - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + with: + toolchain: stable components: rustfmt, clippy targets: wasm32-unknown-unknown - run: cargo fmt --check diff --git a/.github/workflows/atomic.yml b/.github/workflows/atomic.yml index 25423780e..1a20fa679 100644 --- a/.github/workflows/atomic.yml +++ b/.github/workflows/atomic.yml @@ -11,18 +11,30 @@ on: permissions: contents: read +concurrency: + # Pull requests share one group per branch, so a newer push cancels the older run. Every other + # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. + group: atomic-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + jobs: atomic: timeout-minutes: 15 strategy: fail-fast: false matrix: - os: [ubuntu-latest, windows-latest, macos-latest] + # macOS runners are kept for releases: macOS runs only when started by hand. + os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} runs-on: ${{ matrix.os }} steps: - - uses: actions/checkout@v4 - - uses: dtolnay/rust-toolchain@stable + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 with: + egress-policy: audit + - uses: actions/checkout@v7 + - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + with: + toolchain: stable components: rustfmt, clippy - name: Install ACL tools if: runner.os == 'Linux' @@ -33,3 +45,14 @@ jobs: - name: Check inherited Linux ACLs if: runner.os == 'Linux' run: cargo test -p craft-atomic --locked -- --ignored --nocapture + + wasm: + name: Atomic WASM + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: dtolnay/rust-toolchain@stable + with: + targets: wasm32-unknown-unknown + - run: cargo check -p craft-atomic --target wasm32-unknown-unknown + diff --git a/.github/workflows/audio.yml b/.github/workflows/audio.yml new file mode 100644 index 000000000..0104f848e --- /dev/null +++ b/.github/workflows/audio.yml @@ -0,0 +1,163 @@ +name: Shared audio + +on: + push: + branches: [main] + paths: ["crates/audio/**", "crates/media/**", "crates/media-testkit/**", "scripts/fetch-opus-vectors.sh", "Cargo.toml", "Cargo.lock", ".github/workflows/audio.yml"] + pull_request: + paths: ["crates/audio/**", "crates/media/**", "crates/media-testkit/**", "scripts/fetch-opus-vectors.sh", "Cargo.toml", "Cargo.lock", ".github/workflows/audio.yml"] + workflow_dispatch: + +permissions: + contents: read + +concurrency: + # Pull requests share one group per branch, so a newer push cancels the older run. Every other + # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it + # always gets to save the cache. + group: shared-audio-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + lint: + timeout-minutes: 15 + name: Audio lint, feature sets, docs, WASM + runs-on: ubuntu-latest + steps: + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + with: + toolchain: stable + components: rustfmt, clippy + targets: wasm32-unknown-unknown + - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + with: + key: craft-audio-lint + save-if: ${{ github.ref == 'refs/heads/main' }} + - run: cargo fmt -p craft-audio --check + # Each feature on its own, so code that needs another feature fails here. + - name: Clippy, each feature alone + run: | + for f in "" decode decode-native symphonia encode lossless-encode pcm-encode flac-encode peaks aac-decode aac-encode "aac-encode,rayon" opus-decode ac3-decode mpa-decode serde; do + echo "::group::features: ${f:-none}" + cargo clippy -p craft-audio --all-targets --locked --no-default-features ${f:+--features "$f"} -- -D warnings + echo "::endgroup::" + done + - run: cargo clippy -p craft-audio --all-targets --locked --all-features -- -D warnings + # missing_docs is a warning in the crate; -D warnings makes it (and broken links) fail here. + - run: cargo doc -p craft-audio --all-features --no-deps --locked + env: + RUSTDOCFLAGS: "-D warnings" + # Partial feature sets must document too (their links to other features are allowed to dangle). + - run: cargo doc -p craft-audio --no-default-features --features decode-native --no-deps --locked + env: + RUSTDOCFLAGS: "-D warnings" + - run: cargo doc -p craft-audio --no-default-features --features lossless-encode --no-deps --locked + env: + RUSTDOCFLAGS: "-D warnings" + - run: cargo check -p craft-audio --all-features --locked --target wasm32-unknown-unknown + - run: cargo check -p craft-audio --no-default-features --features lossless-encode --locked --target wasm32-unknown-unknown + msrv: + timeout-minutes: 10 + name: Audio on the minimum Rust version + runs-on: ubuntu-latest + steps: + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # 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 + with: + key: craft-audio-msrv + save-if: ${{ github.ref == 'refs/heads/main' }} + - run: cargo +1.95.0 check -p craft-audio -p craft-media --all-features --locked + features: + timeout-minutes: 10 + name: Audio tests without symphonia and lossless-encode only + runs-on: ubuntu-latest + steps: + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + with: + toolchain: stable + - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + with: + key: craft-audio-features + save-if: ${{ github.ref == 'refs/heads/main' }} + - run: cargo test -p craft-audio --no-default-features --features lossless-encode --locked + - run: cargo test -p craft-audio --no-default-features --features pcm-encode --locked --lib + - run: cargo test -p craft-audio --no-default-features --features flac-encode --locked --lib + - run: cargo test -p craft-audio --no-default-features --features decode-native --locked + test: + timeout-minutes: 20 + name: Audio tests with ffmpeg oracles and the Opus conformance vectors + # Pinned for the ffmpeg its apt ships (8.0), so the files the oracle tests write do not change + # with the runner image. + runs-on: ubuntu-26.04 + steps: + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + with: + toolchain: stable + - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + with: + key: craft-audio-test + save-if: ${{ github.ref == 'refs/heads/main' }} + - uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0 + with: + path: ${{ runner.temp }}/media-fixtures/opus/vectors + # The archive's SHA-256 (scripts/fetch-opus-vectors.sh checks it). + key: opus-testvectors-rfc8251-6b26a22f + - name: Build tests while installing ffmpeg and fetching the Opus vectors + run: | + # The man-db index rebuild after dpkg is slow on hosted runners. + sudo rm -f /var/lib/man-db/auto-update + # A mirror can stall for most of the job's time limit, and the next try usually gets a good one. + install_ffmpeg() { + for attempt in 1 2 3; do + # timeout runs as root, so a stalled apt-get is killed too and frees the dpkg lock. + sudo timeout -k 10 180 sh -c 'apt-get update -qq && apt-get install -y -qq --no-install-recommends ffmpeg' && return 0 + echo "apt: attempt $attempt failed with exit code $?" + sudo timeout -k 10 60 dpkg --configure -a || true + done + return 1 + } + # The vectors are fetched after ffmpeg, so the two downloads do not slow each other. + { + install_ffmpeg > "$RUNNER_TEMP/apt.log" 2>&1 || exit 1 + scripts/fetch-opus-vectors.sh "$RUNNER_TEMP/media-fixtures/opus/vectors" > "$RUNNER_TEMP/vectors.log" 2>&1 || exit 2 + } & + fetch=$! + cargo test -p craft-audio --all-features --locked --no-run + wait "$fetch" || case $? in + 1) cat "$RUNNER_TEMP/apt.log"; exit 1 ;; + *) cat "$RUNNER_TEMP/vectors.log"; exit 1 ;; + esac + ffmpeg -hide_banner -version | sed -n 1p + - run: cargo test -p craft-audio --all-features --locked + env: + CRAFT_MEDIA_REQUIRE_ORACLES: "1" + CRAFT_MEDIA_FIXTURES_DIR: ${{ runner.temp }}/media-fixtures diff --git a/.github/workflows/cms.yml b/.github/workflows/cms.yml new file mode 100644 index 000000000..a15a48c9d --- /dev/null +++ b/.github/workflows/cms.yml @@ -0,0 +1,26 @@ +name: Colour management + +on: + workflow_dispatch: + push: + branches: [main] + paths: ['crates/cms/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/cms.yml'] + pull_request: + paths: ['crates/cms/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/cms.yml'] + +permissions: + contents: read + +jobs: + cms: + timeout-minutes: 20 + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: dtolnay/rust-toolchain@stable + with: + components: clippy + - run: cargo clippy -p craft-cms --all-targets --all-features --locked -- -D warnings + # Release: the FOGRA39 fit and ink-limit tests take about 35 s in debug and 4 s here. Tests that need + # installed system profiles print "skipped:" when none are present. + - run: cargo test -p craft-cms --all-features --release --locked -- --nocapture diff --git a/.github/workflows/crw.yml b/.github/workflows/crw.yml new file mode 100644 index 000000000..8fec98661 --- /dev/null +++ b/.github/workflows/crw.yml @@ -0,0 +1,101 @@ +name: Shared CRW + +on: + push: + branches: [main] + paths: ["crates/crw/**", "scripts/fetch-crw-samples.py", "Cargo.toml", "Cargo.lock", ".github/workflows/crw.yml"] + pull_request: + paths: ["crates/crw/**", "scripts/fetch-crw-samples.py", "Cargo.toml", "Cargo.lock", ".github/workflows/crw.yml"] + workflow_dispatch: + +permissions: + contents: read + +concurrency: + # Pull requests share one group per branch, so a newer push cancels the older run. Every other + # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it + # always gets to save the cache. + group: shared-crw-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + native: + timeout-minutes: 20 + name: CRW lint and tests (${{ matrix.os }}) + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest, windows-latest] + runs-on: ${{ matrix.os }} + steps: + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - uses: actions/checkout@v7 + with: + persist-credentials: false + - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + with: + toolchain: stable + components: rustfmt, clippy + - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + with: + key: craft-crw-${{ matrix.os }} + save-if: ${{ github.ref == 'refs/heads/main' }} + - run: cargo fmt -p craft-crw --check + - run: cargo clippy -p craft-crw --all-targets --locked -- -D warnings + - run: cargo test -p craft-crw --locked + + wasm: + timeout-minutes: 10 + name: CRW WASM + runs-on: ubuntu-latest + steps: + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - uses: actions/checkout@v7 + with: + persist-credentials: false + - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + with: + toolchain: stable + targets: wasm32-unknown-unknown + - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + with: + key: craft-crw-wasm + save-if: ${{ github.ref == 'refs/heads/main' }} + - run: cargo check -p craft-crw --locked --target wasm32-unknown-unknown + + samples: + timeout-minutes: 20 + name: CRW sample files decode exactly + runs-on: ubuntu-latest + steps: + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - uses: actions/checkout@v7 + with: + persist-credentials: false + - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + with: + toolchain: stable + - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # 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 + with: + path: ${{ runner.temp }}/crw-samples + key: crw-samples-${{ hashFiles('crates/crw/tests/samples.json') }} + - name: Fetch the pinned CC0 sample files (raw.pixls.us) + run: python scripts/fetch-crw-samples.py "$RUNNER_TEMP/crw-samples" + - run: cargo test -p craft-crw --release --locked --test samples -- --nocapture + env: + CRAFT_CRW_SAMPLES: ${{ runner.temp }}/crw-samples + CRAFT_CRW_REQUIRE_SAMPLES: "1" diff --git a/.github/workflows/dialogs.yml b/.github/workflows/dialogs.yml new file mode 100644 index 000000000..97a931aec --- /dev/null +++ b/.github/workflows/dialogs.yml @@ -0,0 +1,42 @@ +name: Dialogs + +on: + workflow_dispatch: + push: + branches: [main] + paths: ['crates/dialogs/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/dialogs.yml'] + pull_request: + paths: ['crates/dialogs/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/dialogs.yml'] + +permissions: + contents: read + +concurrency: + # Pull requests share one group per branch, so a newer push cancels the older run. Every other + # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. + group: dialogs-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + dialogs: + timeout-minutes: 15 + runs-on: ubuntu-latest + steps: + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - uses: actions/checkout@v7 + 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 + with: + toolchain: stable + components: clippy + # The macOS code is linted on Linux: it compiles for the target without the SDK. + targets: aarch64-apple-darwin + - run: cargo clippy -p craft-dialogs --all-targets --locked -- -D warnings + - run: cargo clippy -p craft-dialogs --target aarch64-apple-darwin --locked -- -D warnings + - run: cargo test -p craft-dialogs --locked diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml new file mode 100644 index 000000000..a0c619c1e --- /dev/null +++ b/.github/workflows/doc.yml @@ -0,0 +1,47 @@ +name: Craft documents + +on: + workflow_dispatch: + push: + branches: [main] + paths: ['crates/doc/**', 'crates/pcraft-format/**', 'crates/vectorcraft-format/**', 'crates/ecproj-format/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/doc.yml'] + pull_request: + paths: ['crates/doc/**', 'crates/pcraft-format/**', 'crates/vectorcraft-format/**', 'crates/ecproj-format/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/doc.yml'] + +permissions: + contents: read + +concurrency: + # Pull requests share one group per branch, so a newer push cancels the older run. Every other + # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. + group: doc-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + doc: + timeout-minutes: 15 + strategy: + fail-fast: false + matrix: + # macOS runners are kept for releases: macOS runs only when started by hand. + os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} + runs-on: ${{ matrix.os }} + steps: + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - uses: actions/checkout@v7 + with: + persist-credentials: false + - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + with: + toolchain: stable + components: rustfmt, clippy + targets: wasm32-unknown-unknown + - run: cargo fmt --check + - run: cargo clippy -p craft-doc --all-targets --locked -- -D warnings + - run: cargo clippy -p craft-doc --all-targets --all-features --locked -- -D warnings + - run: cargo test -p craft-doc --locked -- --nocapture + - run: cargo test -p craft-doc --all-features --locked -- --nocapture + - run: cargo check -p craft-doc --all-features --locked --target wasm32-unknown-unknown diff --git a/.github/workflows/docpath.yml b/.github/workflows/docpath.yml index 557f00f52..571b65eca 100644 --- a/.github/workflows/docpath.yml +++ b/.github/workflows/docpath.yml @@ -11,18 +11,30 @@ on: permissions: contents: read +concurrency: + # Pull requests share one group per branch, so a newer push cancels the older run. Every other + # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. + group: docpath-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + jobs: docpath: timeout-minutes: 15 strategy: fail-fast: false matrix: - os: [ubuntu-latest, windows-latest, macos-latest] + # macOS runners are kept for releases: macOS runs only when started by hand. + os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} runs-on: ${{ matrix.os }} steps: - - uses: actions/checkout@v4 - - uses: dtolnay/rust-toolchain@stable + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 with: + egress-policy: audit + - uses: actions/checkout@v7 + - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + with: + toolchain: stable components: rustfmt, clippy - run: cargo fmt --check - run: cargo clippy -p craft-docpath --all-targets --locked -- -D warnings diff --git a/.github/workflows/ecproj-format.yml b/.github/workflows/ecproj-format.yml new file mode 100644 index 000000000..16bab05c7 --- /dev/null +++ b/.github/workflows/ecproj-format.yml @@ -0,0 +1,45 @@ +name: EffectCraft project format + +on: + workflow_dispatch: + push: + branches: [main] + paths: ['crates/ecproj-format/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/ecproj-format.yml'] + pull_request: + paths: ['crates/ecproj-format/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/ecproj-format.yml'] + +permissions: + contents: read + +concurrency: + # Pull requests share one group per branch, so a newer push cancels the older run. Every other + # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. + group: ecproj-format-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + ecproj-format: + timeout-minutes: 15 + strategy: + fail-fast: false + matrix: + # macOS runners are kept for releases: macOS runs only when started by hand. + os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} + runs-on: ${{ matrix.os }} + steps: + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - uses: actions/checkout@v7 + with: + persist-credentials: false + - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + with: + toolchain: stable + components: rustfmt, clippy + targets: wasm32-unknown-unknown + - run: cargo fmt --check + - run: cargo clippy -p craft-ecproj-format --all-targets --locked -- -D warnings + - run: cargo test -p craft-ecproj-format --locked -- --nocapture + - run: cargo check -p craft-ecproj-format --locked --target wasm32-unknown-unknown diff --git a/.github/workflows/font-store.yml b/.github/workflows/font-store.yml new file mode 100644 index 000000000..f246f621a --- /dev/null +++ b/.github/workflows/font-store.yml @@ -0,0 +1,47 @@ +name: Font store + +on: + workflow_dispatch: + push: + branches: [main] + paths: ['crates/font-store/**', 'crates/font-catalog/**', 'crates/atomic/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/font-store.yml'] + pull_request: + paths: ['crates/font-store/**', 'crates/font-catalog/**', 'crates/atomic/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/font-store.yml'] + +permissions: + contents: read + +concurrency: + # Pull requests share one group per branch, so a newer push cancels the older run. Every other + # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. + group: font-store-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + font-store: + timeout-minutes: 20 + strategy: + fail-fast: false + matrix: + # macOS runners are kept for releases: macOS runs only when started by hand. + os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} + runs-on: ${{ matrix.os }} + steps: + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + with: + toolchain: stable + components: rustfmt, clippy + targets: wasm32-unknown-unknown + - run: cargo fmt --check + - run: cargo clippy -p craft-font-store --all-targets --locked -- -D warnings + - run: cargo test -p craft-font-store --locked + - run: cargo clippy -p craft-font-catalog --all-targets --locked -- -D warnings + - run: cargo test -p craft-font-catalog --locked + - name: Check the web build + if: runner.os == 'Linux' + run: cargo check -p craft-font-store --target wasm32-unknown-unknown --locked diff --git a/.github/workflows/formats.yml b/.github/workflows/formats.yml new file mode 100644 index 000000000..e19902e8c --- /dev/null +++ b/.github/workflows/formats.yml @@ -0,0 +1,111 @@ +name: Shared format crates + +on: + push: + branches: [main] + paths: + - "crates/xml/**" + - "crates/mime/**" + - "crates/cfb/**" + - "crates/mesh/**" + - "crates/metafile/**" + - "crates/dxf/**" + - "crates/gcode/**" + - "crates/svg-paths/**" + - "crates/silhouette-studio/**" + - "crates/tiff/**" + - "crates/heif/**" + - "crates/cms/**" + - "Cargo.toml" + - "Cargo.lock" + - ".github/workflows/formats.yml" + pull_request: + paths: + - "crates/xml/**" + - "crates/mime/**" + - "crates/cfb/**" + - "crates/mesh/**" + - "crates/metafile/**" + - "crates/dxf/**" + - "crates/gcode/**" + - "crates/svg-paths/**" + - "crates/silhouette-studio/**" + - "crates/tiff/**" + - "crates/heif/**" + - "crates/cms/**" + - "Cargo.toml" + - "Cargo.lock" + - ".github/workflows/formats.yml" + workflow_dispatch: + +permissions: + contents: read + +concurrency: + # Pull requests share one group per branch, so a newer push cancels the older run. Every other + # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it + # always gets to save the cache. + group: shared-formats-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + check: + timeout-minutes: 20 + strategy: + fail-fast: false + matrix: + include: + # `features`: each is linted alone, so code that needs another feature fails here. + - { crate: craft-xml, features: "" } + - { crate: craft-mime, features: "" } + - { crate: craft-cfb, features: "" } + - { crate: craft-mesh, features: "stl obj ply gltf" } + - { crate: craft-metafile, features: "write" } + - { crate: craft-dxf, features: "" } + - { crate: craft-gcode, features: "" } + - { crate: craft-svg-paths, features: "" } + - { crate: craft-silhouette-studio, features: "" } + - { crate: craft-tiff, features: "" } + - { crate: craft-heif, features: "testdata" } + - { crate: craft-cms, features: "" } + name: ${{ matrix.crate }} lint, tests, WASM + runs-on: ubuntu-latest + steps: + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: dtolnay/rust-toolchain@b725eda525362e7cf34af9a7243cac1e3f01a7ec # stable + with: + components: rustfmt, clippy + targets: wasm32-unknown-unknown + - uses: Swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3 + with: + key: ${{ matrix.crate }} + save-if: ${{ github.ref == 'refs/heads/main' }} + - run: cargo fmt -p "$CRATE" --check + env: + CRATE: ${{ matrix.crate }} + - name: Clippy, default features and each feature alone + env: + CRATE: ${{ matrix.crate }} + FEATURES: ${{ matrix.features }} + run: | + cargo clippy -p "$CRATE" --all-targets --locked -- -D warnings + for f in $FEATURES; do + echo "::group::feature: $f" + cargo clippy -p "$CRATE" --all-targets --locked --no-default-features --features "$f" -- -D warnings + echo "::endgroup::" + done + - run: cargo clippy -p "$CRATE" --all-targets --locked --all-features -- -D warnings + env: + CRATE: ${{ matrix.crate }} + - run: cargo test -p "$CRATE" --all-features --locked + env: + CRATE: ${{ matrix.crate }} + - run: cargo check -p "$CRATE" --all-features --locked --target wasm32-unknown-unknown + env: + CRATE: ${{ matrix.crate }} diff --git a/.github/workflows/house-rules.yml b/.github/workflows/house-rules.yml new file mode 100644 index 000000000..de64ad3ee --- /dev/null +++ b/.github/workflows/house-rules.yml @@ -0,0 +1,28 @@ +name: House rules + +on: + push: + branches: [main] + paths: + - AGENTS.md + - CLAUDE.md + - .github/workflows/house-rules.yml + pull_request: + paths: + - AGENTS.md + - CLAUDE.md + - .github/workflows/house-rules.yml + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: house-rules-${{ github.ref }} + cancel-in-progress: true + +jobs: + house-rules: + uses: storytold/craft-common-actions/.github/workflows/house-rules.yml@main + with: + rust: true diff --git a/.github/workflows/i18n.yml b/.github/workflows/i18n.yml index d7e6f5b5a..5f717aeff 100644 --- a/.github/workflows/i18n.yml +++ b/.github/workflows/i18n.yml @@ -11,19 +11,31 @@ on: permissions: contents: read +concurrency: + # Pull requests share one group per branch, so a newer push cancels the older run. Every other + # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. + group: i18n-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + jobs: i18n: timeout-minutes: 15 strategy: fail-fast: false matrix: - os: [ubuntu-latest, windows-latest, macos-latest] + # macOS runners are kept for releases: macOS runs only when started by hand. + os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} runs-on: ${{ matrix.os }} steps: - - uses: actions/checkout@v4 - - uses: dtolnay/rust-toolchain@stable + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 with: + egress-policy: audit + - uses: actions/checkout@v7 + - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + with: + toolchain: stable components: rustfmt, clippy - run: cargo fmt --check - - run: cargo clippy -p craft-i18n --all-targets --locked -- -D warnings - - run: cargo test -p craft-i18n --locked -- --nocapture + - run: cargo clippy -p craft-i18n --all-targets --features collate --locked -- -D warnings + - run: cargo test -p craft-i18n --features collate --locked -- --nocapture diff --git a/.github/workflows/jpeg.yml b/.github/workflows/jpeg.yml new file mode 100644 index 000000000..900baf678 --- /dev/null +++ b/.github/workflows/jpeg.yml @@ -0,0 +1,46 @@ +name: Shared JPEG + +on: + push: + branches: [main] + paths: ["crates/jpeg/**", "Cargo.toml", "Cargo.lock", ".github/workflows/jpeg.yml"] + pull_request: + paths: ["crates/jpeg/**", "Cargo.toml", "Cargo.lock", ".github/workflows/jpeg.yml"] + workflow_dispatch: + +permissions: + contents: read + +concurrency: + # Pull requests share one group per branch, so a newer push cancels the older run. Every other + # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it + # always gets to save the cache. + group: shared-jpeg-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + check: + timeout-minutes: 10 + name: JPEG lint, tests, WASM + runs-on: ubuntu-latest + steps: + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + with: + toolchain: stable + components: rustfmt, clippy + targets: wasm32-unknown-unknown + - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + with: + key: craft-jpeg + save-if: ${{ github.ref == 'refs/heads/main' }} + - run: cargo fmt -p craft-jpeg --check + - run: cargo clippy -p craft-jpeg --all-targets --locked -- -D warnings + - run: cargo test -p craft-jpeg --locked + - run: cargo check -p craft-jpeg --locked --target wasm32-unknown-unknown diff --git a/.github/workflows/keymap.yml b/.github/workflows/keymap.yml new file mode 100644 index 000000000..aba535265 --- /dev/null +++ b/.github/workflows/keymap.yml @@ -0,0 +1,115 @@ +name: Keymap + +on: + push: + branches: [main] + paths: ["crates/keymap/**", "crates/settings/**", "crates/ui/**", "crates/i18n/**", "Cargo.toml", "Cargo.lock", ".github/workflows/keymap.yml"] + pull_request: + paths: ["crates/keymap/**", "crates/settings/**", "crates/ui/**", "crates/i18n/**", "Cargo.toml", "Cargo.lock", ".github/workflows/keymap.yml"] + workflow_dispatch: + +permissions: + contents: read + +concurrency: + # Pull requests share one group per branch, so a newer push cancels the older run. Every other + # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it + # always gets to save the cache. + group: keymap-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + linux: + timeout-minutes: 15 + name: Keymap (Linux) + runs-on: ubuntu-latest + env: + CRAFT_FONTS_DIR: ${{ github.workspace }}/.test-inputs/craft-fonts + steps: + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - uses: actions/checkout@v7 + with: + persist-credentials: false + - name: Checkout test fonts + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # 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 + with: + toolchain: stable + components: rustfmt, clippy + - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + with: + key: craft-keymap-linux + save-if: ${{ github.ref == 'refs/heads/main' }} + - run: cargo fmt -p craft-keymap --check + - run: cargo clippy -p craft-keymap --all-targets --no-default-features --locked -- -D warnings + # `snapshot` covers `ui` and `egui` and compiles the dialog screenshots, which need a GPU + # to run, so the test steps leave them out. + - run: cargo clippy -p craft-keymap --all-targets --features snapshot --locked -- -D warnings + # Doctests run once, in the `ui` step. + - name: Test core + run: cargo test -p craft-keymap --no-default-features --lib --tests --locked + - name: Test egui dispatch and the shortcuts dialog + run: cargo test -p craft-keymap --features ui --locked + native: + timeout-minutes: 15 + name: Keymap (${{ matrix.os }}) + strategy: + fail-fast: false + matrix: + # macOS runners are kept for releases: macOS runs only when started by hand. + os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["macos-latest","windows-latest"]') || fromJSON('["windows-latest"]') }} + runs-on: ${{ matrix.os }} + env: + CRAFT_FONTS_DIR: ${{ github.workspace }}/.test-inputs/craft-fonts + steps: + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - uses: actions/checkout@v7 + with: + persist-credentials: false + - name: Checkout test fonts + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # 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 + with: + toolchain: stable + - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + with: + key: craft-keymap-${{ matrix.os }} + save-if: ${{ github.ref == 'refs/heads/main' }} + - run: cargo test -p craft-keymap --features ui --locked + wasm: + timeout-minutes: 10 + name: Keymap WASM + runs-on: ubuntu-latest + steps: + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - uses: actions/checkout@v7 + with: + persist-credentials: false + - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + with: + toolchain: stable + targets: wasm32-unknown-unknown + - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + with: + key: craft-keymap-wasm + save-if: ${{ github.ref == 'refs/heads/main' }} + - run: cargo check -p craft-keymap --features ui --locked --target wasm32-unknown-unknown diff --git a/.github/workflows/media.yml b/.github/workflows/media.yml new file mode 100644 index 000000000..cb3912d54 --- /dev/null +++ b/.github/workflows/media.yml @@ -0,0 +1,84 @@ +name: Shared media + +on: + push: + branches: [main] + paths: ["crates/media/**", "crates/media-testkit/**", "Cargo.toml", "Cargo.lock", ".github/workflows/media.yml"] + pull_request: + paths: ["crates/media/**", "crates/media-testkit/**", "Cargo.toml", "Cargo.lock", ".github/workflows/media.yml"] + workflow_dispatch: + +permissions: + contents: read + +concurrency: + # Pull requests share one group per branch, so a newer push cancels the older run. Every other + # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it + # always gets to save the cache. + group: shared-media-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + lint: + timeout-minutes: 10 + name: Media lint, feature sets, WASM + runs-on: ubuntu-latest + steps: + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - uses: actions/checkout@v7 + with: + persist-credentials: false + - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + with: + toolchain: stable + components: rustfmt, clippy + targets: wasm32-unknown-unknown + - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + with: + key: craft-media-lint + save-if: ${{ github.ref == 'refs/heads/main' }} + - run: cargo fmt -p craft-media --check + - run: cargo clippy -p craft-media --all-targets --locked --no-default-features -- -D warnings + - run: cargo clippy -p craft-media --all-targets --locked --no-default-features --features bitstream -- -D warnings + - run: cargo clippy -p craft-media --all-targets --locked -- -D warnings + - run: cargo clippy -p craft-media --all-targets --locked --no-default-features --features matroska -- -D warnings + - run: cargo clippy -p craft-media --all-targets --locked --no-default-features --features ogg -- -D warnings + - run: cargo clippy -p craft-media --all-targets --locked --all-features -- -D warnings + - run: cargo clippy -p craft-media-testkit --all-targets --locked -- -D warnings + - run: cargo clippy -p craft-media --all-targets --locked --no-default-features --features serde -- -D warnings + - run: cargo check -p craft-media --all-features --locked --target wasm32-unknown-unknown + test: + timeout-minutes: 15 + name: Media tests with ffmpeg oracles + runs-on: ubuntu-latest + steps: + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - uses: actions/checkout@v7 + with: + persist-credentials: false + - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + with: + toolchain: stable + - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + with: + key: craft-media-test + save-if: ${{ github.ref == 'refs/heads/main' }} + - name: Build tests while installing ffmpeg + run: | + # The man-db index rebuild after dpkg is slow on hosted runners. + sudo rm -f /var/lib/man-db/auto-update + (sudo apt-get update -qq && sudo apt-get install -y -qq --no-install-recommends ffmpeg) > "$RUNNER_TEMP/apt.log" 2>&1 & + apt=$! + cargo test -p craft-media --all-features --locked --no-run + wait "$apt" || { cat "$RUNNER_TEMP/apt.log"; exit 1; } + ffmpeg -hide_banner -version | sed -n 1p + - run: cargo test -p craft-media --all-features --locked + env: + CRAFT_MEDIA_REQUIRE_ORACLES: "1" + CRAFT_MEDIA_FIXTURES_DIR: ${{ runner.temp }}/media-fixtures diff --git a/.github/workflows/menu.yml b/.github/workflows/menu.yml new file mode 100644 index 000000000..6d0e082cb --- /dev/null +++ b/.github/workflows/menu.yml @@ -0,0 +1,39 @@ +name: Menu + +on: + push: + branches: [main] + paths: ["crates/menu/**", "crates/keymap/**", "crates/quit/**", "Cargo.toml", "Cargo.lock", ".github/workflows/menu.yml"] + pull_request: + paths: ["crates/menu/**", "crates/keymap/**", "crates/quit/**", "Cargo.toml", "Cargo.lock", ".github/workflows/menu.yml"] + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: menu-${{ github.ref }} + cancel-in-progress: true + +jobs: + linux: + timeout-minutes: 15 + name: Menu (Linux) + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + with: + persist-credentials: false + - uses: dtolnay/rust-toolchain@b725eda525362e7cf34af9a7243cac1e3f01a7ec # stable + with: + components: rustfmt, clippy + targets: aarch64-apple-darwin, wasm32-unknown-unknown + - uses: Swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3 + with: + key: craft-menu-linux + - run: cargo fmt -p craft-menu --check + - run: cargo clippy -p craft-menu --all-targets --locked -- -D warnings + # The macOS backend type-checks from Linux; it needs no linker or SDK. + - run: cargo clippy -p craft-menu --lib --locked --target aarch64-apple-darwin -- -D warnings + - run: cargo clippy -p craft-menu --lib --locked --target wasm32-unknown-unknown -- -D warnings + - run: cargo test -p craft-menu --locked diff --git a/.github/workflows/pcraft-format.yml b/.github/workflows/pcraft-format.yml new file mode 100644 index 000000000..177bb4593 --- /dev/null +++ b/.github/workflows/pcraft-format.yml @@ -0,0 +1,45 @@ +name: PhotoCraft format + +on: + workflow_dispatch: + push: + branches: [main] + paths: ['crates/pcraft-format/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/pcraft-format.yml'] + pull_request: + paths: ['crates/pcraft-format/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/pcraft-format.yml'] + +permissions: + contents: read + +concurrency: + # Pull requests share one group per branch, so a newer push cancels the older run. Every other + # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. + group: pcraft-format-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + pcraft-format: + timeout-minutes: 15 + strategy: + fail-fast: false + matrix: + # macOS runners are kept for releases: macOS runs only when started by hand. + os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} + runs-on: ${{ matrix.os }} + steps: + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + with: + toolchain: "1.95" + components: rustfmt, clippy + targets: wasm32-unknown-unknown + - run: cargo fmt --check + - run: cargo clippy -p craft-pcraft-format --all-targets --locked -- -D warnings + - run: cargo test -p craft-pcraft-format --locked -- --nocapture + - run: cargo check -p craft-pcraft-format --locked --target wasm32-unknown-unknown diff --git a/.github/workflows/pdf.yml b/.github/workflows/pdf.yml index e0d9fcf1b..a494d085c 100644 --- a/.github/workflows/pdf.yml +++ b/.github/workflows/pdf.yml @@ -3,17 +3,20 @@ name: Shared PDF on: push: branches: [main] - paths: ["crates/pdf/**", "vendor/hayro*/**", "vendor/krilla/**", "scripts/test-pdf-backends.sh", "scripts/*fetch-pdf-test-fonts.py", "Cargo.toml", "Cargo.lock", ".github/workflows/pdf.yml"] + paths: ["crates/pdf/**", "crates/plate-test/**", "crates/prepress/**", "crates/cms/**", "vendor/hayro*/**", "vendor/krilla/**", "vendor/linesweeper/**","scripts/test-pdf-backends.sh", "scripts/*fetch-pdf-test-fonts.py", "Cargo.toml", "Cargo.lock", ".github/workflows/pdf.yml"] pull_request: - paths: ["crates/pdf/**", "vendor/hayro*/**", "vendor/krilla/**", "scripts/test-pdf-backends.sh", "scripts/*fetch-pdf-test-fonts.py", "Cargo.toml", "Cargo.lock", ".github/workflows/pdf.yml"] + paths: ["crates/pdf/**", "crates/plate-test/**", "crates/prepress/**", "crates/cms/**", "vendor/hayro*/**", "vendor/krilla/**", "vendor/linesweeper/**","scripts/test-pdf-backends.sh", "scripts/*fetch-pdf-test-fonts.py", "Cargo.toml", "Cargo.lock", ".github/workflows/pdf.yml"] workflow_dispatch: permissions: contents: read concurrency: - group: shared-pdf-${{ github.ref }} - cancel-in-progress: true + # Pull requests share one group per branch, so a newer push cancels the older run. Every other + # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it + # always gets to save the cache. + group: shared-pdf-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} jobs: native: @@ -21,19 +24,26 @@ jobs: strategy: fail-fast: false matrix: - os: [ubuntu-latest, windows-latest, macos-latest] + # macOS runners are kept for releases: macOS runs only when started by hand. + os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} runs-on: ${{ matrix.os }} env: RUSTFLAGS: --cfg craft_pdf_unicode_fixtures steps: - - uses: actions/checkout@v4 - - uses: dtolnay/rust-toolchain@stable + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 with: + egress-policy: audit + - uses: actions/checkout@v7 + - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + with: + toolchain: stable components: rustfmt, clippy - - uses: Swatinem/rust-cache@v2 + - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 with: key: craft-pdf - - uses: actions/setup-python@v5 + save-if: ${{ github.ref == 'refs/heads/main' }} + - uses: actions/setup-python@v7 with: python-version: "3.12" - name: Provision licensed PDF test fonts @@ -50,11 +60,18 @@ jobs: name: PDF vendored contracts runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 - - uses: dtolnay/rust-toolchain@stable - - uses: Swatinem/rust-cache@v2 + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - uses: actions/checkout@v7 + - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + with: + toolchain: stable + - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 with: key: craft-pdf-backends + save-if: ${{ github.ref == 'refs/heads/main' }} - run: bash scripts/test-pdf-backends.sh wasm: name: PDF WASM runtime @@ -63,14 +80,20 @@ jobs: RUSTFLAGS: --cfg craft_pdf_unicode_fixtures CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUNNER: wasm-bindgen-test-runner steps: - - uses: actions/checkout@v4 - - uses: dtolnay/rust-toolchain@stable + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 with: + egress-policy: audit + - uses: actions/checkout@v7 + - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + with: + toolchain: stable targets: wasm32-unknown-unknown - - uses: Swatinem/rust-cache@v2 + - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 with: key: craft-pdf-wasm - - uses: actions/setup-python@v5 + save-if: ${{ github.ref == 'refs/heads/main' }} + - uses: actions/setup-python@v7 with: python-version: "3.12" - name: Provision licensed PDF test fonts @@ -79,10 +102,46 @@ jobs: python scripts/test-fetch-pdf-test-fonts.py python scripts/fetch-pdf-test-fonts.py "$RUNNER_TEMP/craft-pdf-test-fonts" echo "CRAFT_PDF_TEST_FONT_DIR=$RUNNER_TEMP/craft-pdf-test-fonts" >> "$GITHUB_ENV" - - name: Install the matching WASM test runner + - name: Read the wasm-bindgen version from Cargo.lock + id: wasm-bindgen shell: bash run: | runner_version=$(python3 -c 'import tomllib; d=tomllib.load(open("Cargo.lock", "rb")); print(next(p["version"] for p in d["package"] if p["name"] == "wasm-bindgen"))') - cargo install wasm-bindgen-cli --version "$runner_version" --locked + echo "version=$runner_version" >> "$GITHUB_OUTPUT" + - 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 + with: + tool: wasm-bindgen@${{ steps.wasm-bindgen.outputs.version }} + fallback: cargo-install - run: cargo test -p craft-pdf --all-features --locked --target wasm32-unknown-unknown - run: cargo test --manifest-path crates/pdf/read-only-contract/Cargo.toml --locked --target wasm32-unknown-unknown + plate-test: + name: Plate tests and craft-prepress + runs-on: ubuntu-latest + steps: + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - uses: actions/checkout@v7 + - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + with: + toolchain: stable + components: clippy + - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + with: + key: craft-plate-test + save-if: ${{ github.ref == 'refs/heads/main' }} + - uses: actions/setup-python@v7 + with: + python-version: "3.12" + - name: Provision licensed PDF test fonts + shell: bash + run: | + python scripts/test-fetch-pdf-test-fonts.py + python scripts/fetch-pdf-test-fonts.py "$RUNNER_TEMP/craft-pdf-test-fonts" + echo "CRAFT_PDF_TEST_FONT_DIR=$RUNNER_TEMP/craft-pdf-test-fonts" >> "$GITHUB_ENV" + - run: cargo clippy -p craft-plate-test -p craft-prepress --all-targets --all-features --locked -- -D warnings + - run: cargo test -p craft-plate-test -p craft-prepress --all-features --locked diff --git a/.github/workflows/print.yml b/.github/workflows/print.yml index ea0696e3f..3838e6c42 100644 --- a/.github/workflows/print.yml +++ b/.github/workflows/print.yml @@ -8,18 +8,29 @@ on: paths: ['crates/print/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/print.yml'] permissions: contents: read +concurrency: + # Pull requests share one group per branch, so a newer push cancels the older run. Every other + # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. + group: print-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} jobs: print: timeout-minutes: 30 strategy: fail-fast: false matrix: - os: [ubuntu-latest, windows-latest, macos-latest] + # macOS runners are kept for releases: macOS runs only when started by hand. + os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} runs-on: ${{ matrix.os }} steps: - - uses: actions/checkout@v4 - - uses: dtolnay/rust-toolchain@stable + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 with: + egress-policy: audit + - uses: actions/checkout@v7 + - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + with: + toolchain: stable components: rustfmt, clippy - run: cargo fmt --check - run: cargo clippy -p craft-print --all-targets -- -D warnings diff --git a/.github/workflows/proof.yml b/.github/workflows/proof.yml new file mode 100644 index 000000000..0035b1c04 --- /dev/null +++ b/.github/workflows/proof.yml @@ -0,0 +1,77 @@ +name: Proofing + +on: + push: + branches: [main] + paths: ["crates/proof/**", "Cargo.toml", "Cargo.lock", ".github/workflows/proof.yml"] + pull_request: + paths: ["crates/proof/**", "Cargo.toml", "Cargo.lock", ".github/workflows/proof.yml"] + workflow_dispatch: + +permissions: + contents: read + +concurrency: + # Pull requests share one group per branch, so a newer push cancels the older run. Every other + # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it + # always gets to save the cache. + group: craft-proof-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + check: + timeout-minutes: 20 + name: Proofing lint, tests with and without Language data, WASM + runs-on: ubuntu-latest + steps: + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # 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 + with: + repository: storytold/craft-i18n + ref: c239f934ace90b7939afaceb23b472ceeafd6b8a + path: craft-i18n + persist-credentials: false + - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + with: + toolchain: stable + components: rustfmt, clippy + targets: wasm32-unknown-unknown + - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + with: + key: craft-proof + save-if: ${{ github.ref == 'refs/heads/main' }} + - run: cargo fmt -p craft-proof --check + - name: Without Language data (a fork, docs.rs, offline) + run: | + cargo clippy -p craft-proof --all-targets --locked -- -D warnings + cargo test -p craft-proof --locked + cargo check -p craft-proof --locked --target wasm32-unknown-unknown + - name: A release without Language data fails + run: | + if CRAFT_I18N_REQUIRED=1 cargo check -p craft-proof --locked 2>build.log; then + echo "::error::CRAFT_I18N_REQUIRED=1 without CRAFT_I18N_DIR built"; exit 1 + fi + grep -q "CRAFT_I18N_REQUIRED=1 but CRAFT_I18N_DIR is unset" build.log + - name: With Language data + env: + CRAFT_I18N_DIR: ${{ github.workspace }}/craft-i18n + CRAFT_I18N_REQUIRED: "1" + run: | + cargo clippy -p craft-proof --all-targets --locked -- -D warnings + cargo test -p craft-proof --locked + cargo check -p craft-proof --locked --target wasm32-unknown-unknown + - name: The English-only build (CRAFT_PROOF_EMBED=en, CP4.4's default once Language packs ship) + env: + CRAFT_I18N_DIR: ${{ github.workspace }}/craft-i18n + CRAFT_I18N_REQUIRED: "1" + CRAFT_PROOF_EMBED: en + run: cargo test -p craft-proof --locked diff --git a/.github/workflows/sonarcloud.yml b/.github/workflows/sonarcloud.yml new file mode 100644 index 000000000..654fe4c02 --- /dev/null +++ b/.github/workflows/sonarcloud.yml @@ -0,0 +1,27 @@ +name: SonarCloud + +on: + push: + branches: [main] + pull_request: + types: [opened, synchronize, reopened] + +permissions: + contents: read + +concurrency: + group: sonarcloud-${{ github.ref }} + # A push to main is the run that publishes coverage; superseded runs there would never finish. + cancel-in-progress: ${{ github.ref != 'refs/heads/main' }} + +jobs: + sonarcloud: + # Track shared CI improvements on main. + uses: storytold/craft-common-actions/.github/workflows/sonarcloud.yml@main + with: + pdf-test-fonts: true + # The codec and format code behind features that are off by default. Without these the + # coverage build never compiles it, and new code there reads as untested. + cargo-features: >- + craft-video/dnx,craft-video/vp8,craft-video/prores,craft-video/h264,craft-video/hevc,craft-video/vp9,craft-video/av1,craft-video/threads,craft-audio/decode,craft-audio/encode,craft-audio/peaks,craft-audio/rayon,craft-audio/serde,craft-media/matroska,craft-media/ogg,craft-media/bitstream,craft-media/serde,craft-mesh/stl,craft-mesh/obj,craft-mesh/ply,craft-mesh/gltf,craft-metafile/write + secrets: inherit diff --git a/.github/workflows/ui.yml b/.github/workflows/ui.yml index 79845a449..0892f5a2c 100644 --- a/.github/workflows/ui.yml +++ b/.github/workflows/ui.yml @@ -3,17 +3,20 @@ name: Shared UI on: push: branches: [main] - paths: ["crates/ui/**", "Cargo.toml", "Cargo.lock", ".github/workflows/ui.yml"] + paths: ["crates/ui/**", "crates/i18n/**", "Cargo.toml", "Cargo.lock", ".github/workflows/ui.yml"] pull_request: - paths: ["crates/ui/**", "Cargo.toml", "Cargo.lock", ".github/workflows/ui.yml"] + paths: ["crates/ui/**", "crates/i18n/**", "Cargo.toml", "Cargo.lock", ".github/workflows/ui.yml"] workflow_dispatch: permissions: contents: read concurrency: - group: shared-ui-${{ github.ref }} - cancel-in-progress: true + # Pull requests share one group per branch, so a newer push cancels the older run. Every other + # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it + # always gets to save the cache. + group: shared-ui-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} jobs: native: @@ -22,22 +25,29 @@ jobs: strategy: fail-fast: false matrix: - os: [ubuntu-latest, windows-latest, macos-latest] + # macOS runners are kept for releases: macOS runs only when started by hand. + os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} runs-on: ${{ matrix.os }} steps: - - uses: actions/checkout@v4 + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - uses: actions/checkout@v7 - 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: dtolnay/rust-toolchain@stable + - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 with: + toolchain: stable components: rustfmt, clippy - - uses: Swatinem/rust-cache@v2 + - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 with: key: craft-ui + save-if: ${{ github.ref == 'refs/heads/main' }} - run: cargo fmt --check - run: cargo clippy -p craft-ui --all-targets --locked -- -D warnings - run: cargo clippy -p craft-ui --all-targets --all-features --locked -- -D warnings @@ -48,11 +58,17 @@ jobs: name: UI WASM runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 - - uses: dtolnay/rust-toolchain@stable + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 with: + egress-policy: audit + - uses: actions/checkout@v7 + - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + with: + toolchain: stable targets: wasm32-unknown-unknown - - uses: Swatinem/rust-cache@v2 + - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 with: key: craft-ui-wasm + save-if: ${{ github.ref == 'refs/heads/main' }} - run: cargo check -p craft-ui --all-features --locked --target wasm32-unknown-unknown diff --git a/.github/workflows/update.yml b/.github/workflows/update.yml new file mode 100644 index 000000000..f9c8e1498 --- /dev/null +++ b/.github/workflows/update.yml @@ -0,0 +1,48 @@ +name: App updates + +on: + workflow_dispatch: + push: + branches: [main] + paths: ['crates/update/**', 'Cargo.toml', 'Cargo.lock', 'rustfmt.toml', 'clippy.toml', '.github/workflows/update.yml'] + pull_request: + paths: ['crates/update/**', 'Cargo.toml', 'Cargo.lock', 'rustfmt.toml', 'clippy.toml', '.github/workflows/update.yml'] + +permissions: + contents: read + +concurrency: + # Pull requests share one group per branch, so a newer push cancels the older run. Every other + # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. + group: update-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + update: + timeout-minutes: 15 + strategy: + fail-fast: false + matrix: + # macOS runners are kept for releases: macOS runs only when started by hand. + os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} + runs-on: ${{ matrix.os }} + steps: + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # 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 + with: + toolchain: stable + components: rustfmt, clippy + - run: cargo fmt --check + # Default (no egui) and the egui feature both build and lint cleanly. + - run: cargo clippy -p craft-update --all-targets --locked -- -D warnings + - run: cargo clippy -p craft-update --all-targets --locked --features egui -- -D warnings + - run: cargo test -p craft-update --locked -- --nocapture + - run: cargo test -p craft-update --locked --features egui -- --nocapture diff --git a/.github/workflows/vectorcraft-format.yml b/.github/workflows/vectorcraft-format.yml new file mode 100644 index 000000000..b2b20463a --- /dev/null +++ b/.github/workflows/vectorcraft-format.yml @@ -0,0 +1,45 @@ +name: VectorCraft format + +on: + workflow_dispatch: + push: + branches: [main] + paths: ['crates/vectorcraft-format/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/vectorcraft-format.yml'] + pull_request: + paths: ['crates/vectorcraft-format/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/vectorcraft-format.yml'] + +permissions: + contents: read + +concurrency: + # Pull requests share one group per branch, so a newer push cancels the older run. Every other + # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. + group: vectorcraft-format-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + vectorcraft-format: + timeout-minutes: 15 + strategy: + fail-fast: false + matrix: + # macOS runners are kept for releases: macOS runs only when started by hand. + os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} + runs-on: ${{ matrix.os }} + steps: + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + with: + toolchain: "1.95" + components: rustfmt, clippy + targets: wasm32-unknown-unknown + - run: cargo fmt --check + - run: cargo clippy -p craft-vectorcraft-format --all-targets --locked -- -D warnings + - run: cargo test -p craft-vectorcraft-format --locked -- --nocapture + - run: cargo check -p craft-vectorcraft-format --locked --target wasm32-unknown-unknown diff --git a/.github/workflows/video.yml b/.github/workflows/video.yml new file mode 100644 index 000000000..ec1c16eda --- /dev/null +++ b/.github/workflows/video.yml @@ -0,0 +1,80 @@ +name: Shared video + +on: + push: + branches: [main] + paths: ["crates/video/**", "crates/media/**", "crates/media-testkit/**", "Cargo.toml", "Cargo.lock", ".github/workflows/video.yml"] + pull_request: + paths: ["crates/video/**", "crates/media/**", "crates/media-testkit/**", "Cargo.toml", "Cargo.lock", ".github/workflows/video.yml"] + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: shared-video-${{ github.ref }} + cancel-in-progress: true + +jobs: + lint: + timeout-minutes: 20 + name: Video lint, feature sets, docs, WASM + runs-on: ubuntu-latest + steps: + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + with: + toolchain: "1.95" + components: rustfmt, clippy + targets: wasm32-unknown-unknown + - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + with: + key: craft-video-lint + - run: cargo fmt -p craft-video --check + # Each feature on its own, so code that needs another feature fails here. + - name: Clippy, each feature alone + run: | + for f in "" dnx vp8 prores h264 hevc vp9 vp9-decode vp9-encode av1 threads; do + echo "::group::features: ${f:-none}" + cargo clippy -p craft-video --all-targets --locked --no-default-features ${f:+--features "$f"} -- -D warnings + echo "::endgroup::" + done + - run: cargo clippy -p craft-video --all-targets --locked --all-features -- -D warnings + - run: cargo doc -p craft-video --all-features --no-deps --locked + env: + RUSTDOCFLAGS: "-D warnings" + - run: cargo check -p craft-video --all-features --locked --target wasm32-unknown-unknown + test: + timeout-minutes: 30 + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest, windows-latest] + runs-on: ${{ matrix.os }} + name: Video tests (${{ matrix.os }}) + steps: + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + with: + toolchain: "1.95" + - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + with: + key: craft-video-${{ matrix.os }} + - name: Install ffmpeg (Linux) + if: runner.os == 'Linux' + run: | + sudo rm -f /var/lib/man-db/auto-update + sudo apt-get update -qq && sudo apt-get install -y -qq --no-install-recommends ffmpeg + - run: cargo test -p craft-video --all-features --locked diff --git a/.github/workflows/web-api.yml b/.github/workflows/web-api.yml new file mode 100644 index 000000000..2460fb569 --- /dev/null +++ b/.github/workflows/web-api.yml @@ -0,0 +1,57 @@ +name: Web API (page command API) + +on: + workflow_dispatch: + push: + branches: [main] + paths: ['crates/web-api/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/web-api.yml'] + pull_request: + paths: ['crates/web-api/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/web-api.yml'] + +permissions: + contents: read + +concurrency: + # Pull requests share one group per branch, so a newer push cancels the older run. Every other + # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. + group: web-api-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + web-api: + # One OS: the crate is platform-independent JSON handling plus wasm32; no platform code. + timeout-minutes: 30 + runs-on: ubuntu-latest + env: + CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUNNER: wasm-bindgen-test-runner + steps: + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + with: + toolchain: stable + components: rustfmt, clippy + targets: wasm32-unknown-unknown + - name: Read the wasm-bindgen version from Cargo.lock + id: wasm-bindgen + shell: bash + run: | + runner_version=$(python3 -c 'import tomllib; d=tomllib.load(open("Cargo.lock", "rb")); print(next(p["version"] for p in d["package"] if p["name"] == "wasm-bindgen"))') + echo "version=$runner_version" >> "$GITHUB_OUTPUT" + - 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 + with: + tool: wasm-bindgen@${{ steps.wasm-bindgen.outputs.version }} + fallback: cargo-install + - run: cargo fmt --check + - run: cargo clippy -p craft-web-api --all-targets --locked -- -D warnings + - run: cargo clippy -p craft-web-api --all-targets --locked --target wasm32-unknown-unknown -- -D warnings + - run: cargo test -p craft-web-api --locked + - run: cargo test -p craft-web-api --locked --target wasm32-unknown-unknown diff --git a/.github/workflows/web-host.yml b/.github/workflows/web-host.yml new file mode 100644 index 000000000..b780ee76b --- /dev/null +++ b/.github/workflows/web-host.yml @@ -0,0 +1,62 @@ +name: Shared web host + +on: + push: + branches: [main] + paths: ["crates/web-host/**", "Cargo.toml", "Cargo.lock", ".github/workflows/web-host.yml"] + pull_request: + paths: ["crates/web-host/**", "Cargo.toml", "Cargo.lock", ".github/workflows/web-host.yml"] + workflow_dispatch: + +permissions: + contents: read + +concurrency: + # Pull requests share one group per branch, so a newer push cancels the older run. Every other + # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it + # always gets to save the cache. + group: shared-web-host-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + check: + timeout-minutes: 20 + name: Web host lint, tests, WASM tests + runs-on: ubuntu-latest + env: + CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUNNER: wasm-bindgen-test-runner + steps: + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: step-security/dtolnay-rust-toolchain@8dd607977d06adf4ed49b190381e74c17a9dd25f # v1.0.0 + with: + toolchain: stable + components: rustfmt, clippy + targets: wasm32-unknown-unknown + - uses: step-security/rust-cache@8871c8ba063416da7c32246932ea6ae08700453e # v2.9.2 + with: + key: craft-web-host + save-if: ${{ github.ref == 'refs/heads/main' }} + - run: cargo fmt -p craft-web-host --check + - run: cargo clippy -p craft-web-host --all-targets --locked -- -D warnings + - run: cargo clippy -p craft-web-host --all-targets --locked --target wasm32-unknown-unknown -- -D warnings + - run: cargo test -p craft-web-host --locked + - name: Read the wasm-bindgen version from Cargo.lock + id: wasm-bindgen + shell: bash + run: | + runner_version=$(grep -A1 '^name = "wasm-bindgen"$' Cargo.lock | sed -n 's/^version = "\(.*\)"$/\1/p') + echo "version=$runner_version" >> "$GITHUB_OUTPUT" + - 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 + with: + tool: wasm-bindgen@${{ steps.wasm-bindgen.outputs.version }} + fallback: cargo-install + - run: cargo test -p craft-web-host --locked --target wasm32-unknown-unknown diff --git a/.github/workflows/window.yml b/.github/workflows/window.yml new file mode 100644 index 000000000..f570ef5ce --- /dev/null +++ b/.github/workflows/window.yml @@ -0,0 +1,50 @@ +name: Window decorations + +on: + workflow_dispatch: + push: + branches: [main] + paths: ['crates/window/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/window.yml'] + pull_request: + paths: ['crates/window/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/window.yml'] + +permissions: + contents: read + +concurrency: + # Pull requests share one group per branch, so a newer push cancels the older run. Every other + # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. + group: window-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + window: + timeout-minutes: 15 + strategy: + fail-fast: false + matrix: + # macOS runners are kept for releases: macOS runs only when started by hand. + os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} + runs-on: ${{ matrix.os }} + steps: + - name: Harden runner + uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4 + with: + egress-policy: audit + - uses: actions/checkout@v7 + 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 + with: + toolchain: stable + components: rustfmt, clippy + - run: cargo fmt --check + # Default (no egui) and the egui feature both build and lint cleanly. + - run: cargo clippy -p craft-window --all-targets --locked -- -D warnings + - run: cargo clippy -p craft-window --all-targets --locked --features egui -- -D warnings + - run: cargo test -p craft-window --locked -- --nocapture + - run: cargo test -p craft-window --locked --features egui -- --nocapture + - run: cargo clippy -p craft-window --all-targets --locked --features restore -- -D warnings + - run: cargo test -p craft-window --locked --features restore,egui -- --nocapture diff --git a/.github/workflows/workspace.yml b/.github/workflows/workspace.yml new file mode 100644 index 000000000..4002900d9 --- /dev/null +++ b/.github/workflows/workspace.yml @@ -0,0 +1,75 @@ +name: Workspace + +on: + push: + branches: [main] + tags: ["v*"] + pull_request: + workflow_dispatch: + +permissions: + contents: read + +jobs: + native: + name: Workspace (${{ matrix.os }}) + timeout-minutes: 30 + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest, windows-latest, macos-latest] + runs-on: ${{ matrix.os }} + steps: + - uses: actions/checkout@v4 + - 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: dtolnay/rust-toolchain@stable + with: + components: rustfmt, clippy + - uses: Swatinem/rust-cache@v2 + with: + key: workspace + - name: Prepare the Windows test driver + if: runner.os == 'Windows' + shell: powershell + run: | + $ErrorActionPreference = 'Stop' + Start-Service Spooler + Add-PrinterDriver -Name 'Generic / Text Only' + - run: cargo fmt --check + - run: cargo clippy --workspace --all-targets --locked -- -D warnings + - run: cargo clippy --workspace --all-targets --all-features --locked -- -D warnings + - run: cargo test --workspace --locked + env: + CRAFT_PRINT_REQUIRE_QUEUE: ${{ runner.os == 'Windows' && '1' || '0' }} + - run: cargo test --workspace --all-features --locked + env: + CRAFT_PRINT_REQUIRE_QUEUE: ${{ runner.os == 'Windows' && '1' || '0' }} + msrv: + name: Rust 1.95 (Linux libraries) + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - uses: actions/checkout@v4 + - uses: dtolnay/rust-toolchain@1.95.0 + - uses: Swatinem/rust-cache@v2 + with: + key: workspace-msrv + - run: cargo check --workspace --lib --all-features --locked + wasm: + name: UI and settings WASM + runs-on: ubuntu-latest + timeout-minutes: 15 + steps: + - uses: actions/checkout@v4 + - uses: dtolnay/rust-toolchain@stable + with: + targets: wasm32-unknown-unknown + - uses: Swatinem/rust-cache@v2 + with: + key: workspace-wasm + - run: cargo check -p craft-ui -p craft-settings --all-features --locked --target wasm32-unknown-unknown diff --git a/.gitignore b/.gitignore index 9108c660c..3c2518872 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,10 @@ plan/ plans/ /target +# Also a sub-crate's own build directory: `crates/pdf/read-only-contract/target/` is not covered +# by the anchored `/target` above, and 803 of its files reached a commit once (#185 review). +target/ .DS_Store /.claude/ .idea/ +/vendor/*/target diff --git a/AGENTS.md b/AGENTS.md index 03e7ff50e..aa4561e67 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,14 +1,63 @@ + +## House rules + +These apply in every Craft repository. A later rule may be stricter, not weaker. The source is `standards/house-rules-core.md` in `storytold/craft-contrib`. Propose changes there, not in a copy. + +1. **A person is accountable.** Whoever runs an agent answers for what it opens and for its review comments. +2. **Check, then claim.** Before writing code, read the issue comments, search pull requests for `#N` and the keywords, and check recent commits on `main`. Comment on the issue first. Release a claim you will not finish. +3. **Verify, don't guess.** Open a definition before using it. Confirm the cause in the code, even when someone names a location. +4. **Keep fixes narrow and tested.** Fix what the issue describes, where the bug is. Add a test that fails without the fix. +5. **Review the diff before opening a pull request.** Identifiers exist as used, the test fails without the fix, nothing unrelated changed, and the description is true. +6. **Look for a better pull request.** If another fixes the same thing, close yours when it is better or equal, and say why. +7. **Report only what ran.** Say what you tested and what you could not run. Without a local build or test, say so and rely on CI before marking ready. +8. **`main` changes through a pull request.** Do not push to it. Branch protection enforces this. There is no exception. +9. **Stop and ask only about** licensing outside the allowlist, publishing, releases, a new remote, secrets, spending money, destructive git, and anything else hard to undo. Otherwise keep working. `plan/` is a gitignored notebook, not rules. Without it, do not ask for it and do not stop. +10. **Keep secrets and personal details out** of the repository, logs and requests. +11. **CI stays shared.** Workflows call `storytold/craft-common-actions`. Do not change CI in a feature or fix pull request. If CI cannot cover a change, open an issue there. +12. **Guards say why.** A check that looks removable says what it prevents. Read that before changing it. +13. **Instructions must be readable by everyone.** No notes about one machine, and no links to files a reader cannot open. `craftrules` is retired. Do not link to it. +14. **Keep pull requests moving.** Concurrent pull requests are fine; unanswered actionable feedback is not. Respond in 7 days, a reminder at 14, closure eligible at 30, from when an actionable request waits on the author. Suggestions and unconfirmed bot findings do not start the clock. A fix, explanation or agreed plan resets it; unrelated activity does not. Waiting on a reviewer or maintainer pauses it and does not count against the author. A maintainer decides closure; it is never automatic. Reuse search results, do not poll, and stop at a rate limit. +15. **No agent attribution.** A pull request does not say an agent wrote it. A repository rule may not require that. + + +## Rust Craft repositories + +These apply to native Craft apps and to shared Rust libraries. Select them by repository type. A repository that merely contains some Rust does not take this block. Rules later in a repository's file may be stricter, but not weaker. The source is `standards/house-rules-rust.md` in [storytold/craft-contrib](https://github.com/storytold/craft-contrib). + +1. **Never crash.** Non-test code does not panic and has no `unsafe`, except where the repository file names an exception. Return errors, treat input as hostile, and bound recursion and allocations. New production crate roots copy the `deny` attribute from an existing crate: `clippy::unwrap_used`, `clippy::expect_used`, `clippy::panic`, `clippy::unimplemented`, `clippy::todo`, `clippy::unreachable`. Every crash fix comes with a test that panicked before the fix. +2. **Clean room.** Learn from observed behaviour and public specifications. Do not copy another product's code, assets, strings or artwork. Check a dependency's licence before adding it. +3. **Assets and fonts.** Every asset is original or suitably licensed, and is recorded in `ATTRIBUTION.md` in the same change. Font files live in [storytold/craft-fonts](https://github.com/storytold/craft-fonts), not in the app repository. +4. **Rust only for native Craft apps.** No handwritten JavaScript or TypeScript, and no Tauri, Electron or webview shell, in those apps. Shared tooling follows its documented technical scope and maintainer-approved exceptions. Craft PR Review's existing Tauri and TypeScript UI is one such exception. It does not relax this rule for native apps. Preserve any existing web build. +5. **Time goes through `chrono`.** Do not hand-roll calendar conversion. For dates beyond what `chrono` can represent, follow [standards/time.md](https://github.com/storytold/craft-contrib/blob/main/standards/time.md). +6. **Contributor credits.** Add or edit only your own person's entry in `contributors/people.toml`, and only after asking them. Never guess a name or hand-edit `contributors.json`. + +## Licence allowlist + +Dependencies and assets use SPDX identifiers. An expression is allowed when every identifier is in this list. A repository may name a shorter list. It may not add an identifier here by editing its own copy of these rules. + +- `ISC` +- `MIT` +- `BSD-2-Clause` +- `BSD-3-Clause` +- `Apache-2.0` +- `OFL-1.1` +- `Ubuntu-font-1.0` +- `Bitstream-Vera` +- `CC0-1.0` +- `CC-BY-4.0` +- `CC-BY-SA-4.0` +- `LicenseRef-Public-Domain` + +`LicenseRef-Storyteller-Trademark` is not in this list. It covers Storyteller brand marks only, where a repository already says so. + + # AGENTS.md -Shared Rust libraries for the Craft Apps. The shared standards live in -[craftrules](https://github.com/storytold/craftrules) (`../../craftrules` on a dev machine): read its -`AGENTS.md`, then `standards/never-crash.md`, `standards/engineering.md` and `standards/licensing.md`. +Shared Rust libraries for the Craft Apps. -- **Never crash.** Every crate's `lib.rs` starts with - `#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]`. - No `unsafe` (the workspace forbids it). - **New crates** go in `crates/`, named `craft-`, inherit the workspace package fields - and lints, and are listed in `[workspace.dependencies]`. + and lints, and are listed in `[workspace.dependencies]`. A new crate's `Cargo.toml` includes + `[lints] workspace = true`. - **No app code.** A crate here must be useful to more than one app and must not depend on any app. - **Before merging:** `cargo fmt --check`, `cargo clippy --workspace --all-targets -- -D warnings`, `cargo test --workspace`. diff --git a/ATTRIBUTION.md b/ATTRIBUTION.md index 34cd2ee23..965b348e4 100644 --- a/ATTRIBUTION.md +++ b/ATTRIBUTION.md @@ -8,7 +8,29 @@ author, source and license. Library code and original assets are under the repos |---|---|---|---| | `crates/cms/profiles/photocraft-coated-cmyk.icc` | PhotoCraft contributors; generated by `craft_cms::synth::coated_cmyk` | [PhotoCraft `crates/cms`](https://github.com/storytold/photocraft/tree/b3222ee8e7e6bcb4799c37f904c595f20f9baf5e/crates/cms) | CC0-1.0 | | `crates/cms/profiles/craft-coated-fogra39.icc` | craft-libs contributors; generated by `crates/cms/tests/fogra39.rs` from the FOGRA39 data below | this repository | CC0-1.0 | +| `crates/font-store/index/sources.json` (unmodified) | craft-font-index contributors | [aiongg/craft-font-index@5a9a7f8](https://github.com/aiongg/craft-font-index/tree/5a9a7f8038c8f3e2e1583a79c92a816e8e71b34f) | Apache-2.0 | +| `crates/font-store/index/indexes/google-fonts.json.gz` (unmodified) | craft-font-index contributors; generated from the METADATA.pb files of [google/fonts](https://github.com/google/fonts) at `45e3d5269e4a17d823f6d84470bc084dc5ae46f6` | [aiongg/craft-font-index@5a9a7f8](https://github.com/aiongg/craft-font-index/tree/5a9a7f8038c8f3e2e1583a79c92a816e8e71b34f) | Apache-2.0 | +| `crates/font-store/index/indexes/noto.json.gz` (unmodified) | craft-font-index contributors; generated from [notofonts/notofonts.github.io](https://github.com/notofonts/notofonts.github.io) at `93fac8abebe6c7fed0c5b7d2456d8fa484fa146c` and [noto-cjk](https://github.com/notofonts/noto-cjk) releases | [aiongg/craft-font-index@5a9a7f8](https://github.com/aiongg/craft-font-index/tree/5a9a7f8038c8f3e2e1583a79c92a816e8e71b34f) | Apache-2.0 | | `crates/cms/tests/data/FOGRA39.txt` (unmodified) | Fogra | [Fogra characterisation data](https://fogra.org/en/downloads/work-tools/characterisation-data), `FOGRA39_to_FOGRA60_v2.zip` | Fogra terms: free use and redistribution, unmodified, with Fogra identified as the source; "FOGRA39" identifies the reference data only and implies no certification, approval or endorsement by Fogra (full text in [NOTICE](NOTICE)) | +| `vendor/linesweeper/tests/regression/`, `vendor/linesweeper/proptest-regressions/`, the `.snap` files under `vendor/linesweeper/src/` and the path data in `vendor/linesweeper/benches/painted_dreams.rs` (all unmodified; hashes in `vendor/linesweeper/SOURCE.json`) | As published in the package, whose manifest names Joe Neeman as author and records no other source | [linesweeper 0.5.0](https://crates.io/crates/linesweeper/0.5.0) | MIT OR Apache-2.0 (the package's `license` field) | +| `crates/i18n/data/collation.postcard` | Unicode, Inc. (ICU 78.1 collation data, CLDR 48.2.1); generated by `crates/i18n/data/generate-collation.sh` | [ICU](https://github.com/unicode-org/icu/releases/tag/release-78.1rc) | Unicode-3.0 | +| `crates/text/assets/hyphen/en-us.dic` | Grady Ward (Moby Hyphenator II), converted by DesignCraft | [Project Gutenberg eBook #3204](https://www.gutenberg.org/ebooks/3204) | Public domain | +| `crates/proof/data/en-words.dic` | Grady Ward (Moby Hyphenator II word list); break points dropped by craft-proof contributors with `crates/proof/examples/en_words.rs` | [Project Gutenberg eBook #3204](https://www.gutenberg.org/ebooks/3204), via craft-i18n `language-data/en-us/en-us.dic` | Public domain | +| `crates/proof/data/en-extra.txt` | WordCraft contributors (original list, no other dictionary copied) | craft-i18n `language-data/en-us/en-extra.txt` | MIT OR Apache-2.0 | +| `crates/text/assets/hyphen/en-us.pat` | DesignCraft contributors, trained from the Moby Hyphenator II list | `crates/text/examples/hyphgen.rs` | CC0-1.0 | +| Patterns embedded through `hypher` (optional `craft-text` language features) | hyph-utf8 authors, per language | [tex-hyphen](https://github.com/hyphenation/tex-hyphen), as packaged in [hypher](https://github.com/typst/hypher/tree/main/patterns) | Per file header: LPPL, MIT, BSD-3-Clause, Unlicense or a permit-any-use notice (or a choice including one); Slovak (`hyph-sk.tex`, embedded whenever `hypher/slovak` is on: feature `slovak-gpl`, or another dependency through feature unification) is GPL-2.0-or-later; Spanish (`hyph-es.tex` 5.0, Javier Bezos, CervanTeX) is MIT | +| Word-break dictionaries and LSTM models embedded through `icu_segmenter_data` (optional `craft-text` features `thai`, `lao`, `khmer`, `burmese`) | Unicode, Inc. and ICU4X contributors | [ICU4X](https://github.com/unicode-org/icu4x) | Unicode-3.0 | +| `crates/ui/tests/fonts/NotoSansArabic-test.ttf` (subset to the test strings, default weight set to 100, width axis dropped) | The Noto Project Authors | [google/fonts@7085eb8 `ofl/notosansarabic`](https://github.com/google/fonts/tree/7085eb89a950e85db5b166b7a58d414544b4140c/ofl/notosansarabic), via craft-fonts | OFL-1.1 (`licenses/ui-test-fonts/OFL-NotoSansArabic.txt`) | +| `crates/ui/tests/fonts/NotoSansCJKsc-test.otf` (subset to the test strings) | The Noto Project Authors (Adobe, Google) | [notofonts/noto-cjk@f8d1575 `Sans/OTF/SimplifiedChinese`](https://github.com/notofonts/noto-cjk/tree/f8d157532fbfaeda587e826d4cd5b21a49186f7c/Sans/OTF/SimplifiedChinese), via craft-fonts | OFL-1.1 (`licenses/ui-test-fonts/OFL-NotoSansCJK.txt`) | +| `crates/ui/tests/fonts/NotoSansArabic-screens.ttf` (instance at weight 400 and width 100, subset to the screen test strings) | The Noto Project Authors | [google/fonts@7085eb8 `ofl/notosansarabic`](https://github.com/google/fonts/tree/7085eb89a950e85db5b166b7a58d414544b4140c/ofl/notosansarabic), via craft-fonts | OFL-1.1 (`licenses/ui-test-fonts/OFL-NotoSansArabic.txt`) | +| `crates/ui/tests/fonts/NotoSansCJKsc-screens.otf` (subset to printable ASCII and the screen test strings) | The Noto Project Authors (Adobe, Google) | [notofonts/noto-cjk@f8d1575 `Sans/OTF/SimplifiedChinese`](https://github.com/notofonts/noto-cjk/tree/f8d157532fbfaeda587e826d4cd5b21a49186f7c/Sans/OTF/SimplifiedChinese), via craft-fonts | OFL-1.1 (`licenses/ui-test-fonts/OFL-NotoSansCJK.txt`) | +| `crates/ui/tests/fonts/NotoSansThai-screens.ttf` (instance at weight 400 and width 100, subset to the screen test strings) | The Noto Project Authors | [google/fonts@8b0a1d0 `ofl/notosansthai`](https://github.com/google/fonts/tree/8b0a1d0f5983c89bc2b93f1b5fb55f9e252744b5/ofl/notosansthai), via craft-fonts | OFL-1.1 (`licenses/ui-test-fonts/OFL-NotoSansThai.txt`) | +| `crates/crw/tests/samples.json` (manifest only; the 11 raw files are not bundled, `scripts/fetch-crw-samples.py` downloads them outside the checkout) | The photographers who contributed each file to raw.pixls.us (Canon EOS D30, D60, 10D ×3, 300D ×2, Digital Rebel, PowerShot G1, G5, G6) | [raw.pixls.us](https://raw.pixls.us/), each file's `getfile.php` URL and SHA-256 in the manifest | CC0-1.0 (as published by raw.pixls.us for each file) | +| `crates/crw/src/tables.rs`, `crates/crw/clean-room/logs/table_sel*.json` | craft-crw contributors (derived in LightCraft, 2026-10, by known-plaintext alignment of the sample files' entropy streams; `crates/crw/clean-room/02-crw-format.md`) | this repository | MIT OR Apache-2.0 | +| `crates/crw/clean-room/logs/private-corpus.tsv` (file names, sizes and SHA-256 of the maintainer's own EOS D60 files; no image content) | craft-crw contributors (LightCraft derivation record) | this repository | MIT OR Apache-2.0 | +| `crates/prc/src/acof/table.rs` (the rows of the PRC `Double` prefix-code table, reformatted as Rust tuples) | Kristof Ralovich (prc-rs); the table is defined by ISO 14739-1 | [ralovich/prc-rs@287b671](https://github.com/ralovich/prc-rs/blob/287b671bb5b31b05efb5ec1b98f7c359b9e4dd7d/src/double.rs), through [PdfCraft `crates/prc`](https://github.com/storytold/pdfcraft/tree/80e26e674d1aa33078e83c8139875047f3289eb6/crates/prc) | MIT (`licenses/prc-rs/LICENSE.txt`; the notice is also in the file header) | +| `crates/math/tests/corpus/equations.tsv`, `crates/math/tests/corpus/latex.tsv` (unmodified) | shuff57 (equaSHion) | [storytold/craft-libs#29](https://github.com/storytold/craft-libs/pull/29) at `7a6ef6b9`, `corpus/` | MIT OR Apache-2.0 | +| `crates/math/tests/corpus/omml/*.xml` (unmodified) | WordCraft and DeckCraft contributors, collected by shuff57 (equaSHion) | [storytold/craft-libs#29](https://github.com/storytold/craft-libs/pull/29) at `7a6ef6b9`, `corpus/omml/` | MIT OR Apache-2.0 | Original assets are covered by the repository licence. @@ -28,14 +50,15 @@ The profile licence is retained in `licenses/pdf-writer/LICENSE-ICC.txt`. | `krilla 0.8.2 / icc/sRGB-v4.icc` | Clinton Ingram | https://github.com/LaurenzV/krilla/blob/3ffdf0588cf98050aad6edba51ca70162e1fb5b5/crates/krilla/icc/sRGB-v4.icc | CC0-1.0 | `c56e1685d888f5edb92fe07f2750f387f8fe8e91b32ff8fb0b56bfbbb9458353` | PDF writer colour profiles | The four Krilla ICC entries above are also stored unchanged in `vendor/krilla/icc`. -The vendored source patch and per-file hashes are recorded in `vendor/krilla/README.craft.md` and `vendor/krilla/SOURCE.json`. +The vendored source patches are in `vendor/krilla/patches`, described in `vendor/krilla/README.craft.md`; per-file hashes are in `vendor/krilla/SOURCE.json`. ## Assets retained with the optional PDF reader -The shared reader centralizes the four existing patched Hayro source trees from PdfCraft. +The shared reader centralizes the five patched Hayro source trees from PdfCraft and the +patched crates.io `hayro-postscript` 0.1.0 scanner, which bundles no assets. The standard-14 fonts, CMYK profile and generated metrics listed below remain byte-identical -in `vendor/hayro-interpret`; no application document fonts are added. CMaps remain a pinned -registry dependency. The removed upstream LAB.icc profile is not restored. Source hashes +in `vendor/hayro-interpret`, and the CMaps in `vendor/hayro-cmap/assets`; no application +document fonts are added. The removed upstream LAB.icc profile is not restored. Source hashes and the exact transfer revision are recorded in each vendored crate's SOURCE.json. | Crate / file | Author | Source | Licence | SHA-256 | Use | @@ -55,5 +78,17 @@ and the exact transfer revision are recorded in each vendored crate's SOURCE.jso | `hayro-interpret 0.7.0 / assets/FoxitSerifItalic.pfb` | Foxit Software Inc. / PDFium Authors | https://github.com/storytold/pdfcraft/blob/7437bde378f43856eada40af25b983812e615e8a/vendor/hayro-interpret/assets/FoxitSerifItalic.pfb | BSD-3-Clause | `610ae0687198045c4db5d1a6650fd5e92536631706382eb8b72e38df578d0ae9` | Renders non-embedded standard-14 fonts (pinned hayro-interpret) | | `hayro-interpret 0.7.0 / assets/FoxitSymbol.pfb` | Foxit Software Inc. / PDFium Authors | https://github.com/storytold/pdfcraft/blob/7437bde378f43856eada40af25b983812e615e8a/vendor/hayro-interpret/assets/FoxitSymbol.pfb | BSD-3-Clause | `47967d055530e7357088a08403115425643ec2cdfd6201ba8af0fbd7116c1539` | Renders non-embedded standard-14 fonts (pinned hayro-interpret) | | `hayro-interpret 0.7.0 / assets/CGATS001Compat-v2-micro.icc` | Clinton Ingram (saucecontrol/Compact-ICC-Profiles) | https://github.com/storytold/pdfcraft/blob/7437bde378f43856eada40af25b983812e615e8a/vendor/hayro-interpret/assets/CGATS001Compat-v2-micro.icc | CC0-1.0 | `73e1ba37d2bad5bab2a964f40a9eed96209666efc067c3322626214bbef234a0` | Default CMYK colour conversion (pinned hayro-interpret) | -| `hayro-cmap 0.1.0 / assets/cmaps.brotli` | Adobe | https://crates.io/crates/hayro-cmap/0.1.0 | BSD-3-Clause | `ddf37af521d904d5646c2fc37b2b7e912dc1b56f0d210190b61f598154758e46` | Character-code mapping tables required to read CJK PDFs. Non-visual dependency data; existing embedding unchanged | +| `hayro-cmap 0.1.0 / assets/cmaps.brotli` | Adobe | https://github.com/storytold/pdfcraft/blob/a2ec27b4775f53c40cad3456936d9406611e3a8d/vendor/hayro-cmap/assets/cmaps.brotli | BSD-3-Clause | `ddf37af521d904d5646c2fc37b2b7e912dc1b56f0d210190b61f598154758e46` | Character-code mapping tables required to read CJK PDFs. Non-visual dependency data; existing embedding unchanged | | `hayro-interpret 0.7.0 / src/font/generated/metrics.rs` | Adobe (Core 14 AFM metrics, PDF specification encodings); tables by The Hayro Authors | https://github.com/storytold/pdfcraft/blob/7437bde378f43856eada40af25b983812e615e8a/vendor/hayro-interpret/src/font/generated/metrics.rs | MIT OR Apache-2.0 | `2ec9e608573eda459de1e1d9bda3bb494315e36bee885acc88912a11fe0caa41` | Glyph widths and encodings for non-embedded standard fonts. Non-visual dependency data; existing embedding unchanged | +| `crates/audio/src/ac3/golden_frames.bin` | FilmCraft contributors (original work: 12 AC-3 and E-AC-3 syncframes that ffmpeg's `ac3` and `eac3` encoders made from tones and seeded noise synthesised by ffmpeg's lavfi generators; no third-party or recorded audio) | [FilmCraft `crates/ac3`](https://github.com/storytold/filmcraft/tree/1c9c2e82/crates/ac3/src) | MIT OR Apache-2.0 | +| `crates/audio/tests/fixtures/` | SoundCraft and craft-libs contributors (original work: 0.1 s test tones from ffmpeg's `sine` generator and hand-built silent MPEG frames; no third-party or recorded audio; commands in `crates/audio/tests/fixtures/README.md`) | [SoundCraft `crates/audio-io/tests/fixtures`](https://github.com/storytold/soundcraft/tree/e86d09a/crates/audio-io/tests/fixtures); `tone.mov`, `tone.mka`, `tone.opus`, `tone.ac3` and `tone.eac3` made in this repository | MIT OR Apache-2.0 | +| `crates/raster-codecs/src/xpm/x11_colors.rs` | X.Org Foundation and X11 contributors (X11 `rgb.txt` colour names and values, normalised into a lookup table) | , via [PhotoCraft `crates/codecs`](https://github.com/storytold/photocraft/tree/63b641b55e54bf8f5c83efd977fdb16a2c255431/crates/codecs/src/codecs/xpm) | MIT (X.Org app/rgb) | +| `crates/psd/tests/fixtures/atn/*.atn` (seven synthetic action sets, encoded field by field; `crates/psd/tests/fixtures/atn/README.md`) | PhotoCraft contributors | [PhotoCraft `crates/psd/tests/fixtures/atn`](https://github.com/storytold/photocraft/tree/63b641b55e54bf8f5c83efd977fdb16a2c255431/crates/psd/tests/fixtures/atn) | MIT OR Apache-2.0 | +| `crates/lottie/tests/fixtures/` | EffectCraft contributors (original work: four hand-written Lottie JSON documents, written from the public Lottie format description; not exported from any Adobe product or third-party file) | [EffectCraft `crates/lottie/tests/fixtures`](https://github.com/storytold/effectcraft/tree/e18f48fb/crates/lottie/tests/fixtures) | MIT OR Apache-2.0 | +| `crates/pkcs7/tests/data/` | PdfCraft contributors (original work: throw-away test keys and certificates made with OpenSSL 3 for these tests, as seven PKCS #12 files with the password `test` and two PEM certificates; they protect nothing; commands in `crates/pkcs7/tests/data/README.md`) | [PdfCraft `crates/sign/tests/data`](https://github.com/storytold/pdfcraft/tree/1d7a9f9f/crates/sign/tests/data) | MIT OR Apache-2.0 | +| `crates/affinity/tests/support/corpus.tsv`, `crates/affinity/tests/support/affinity3-signatures.txt` (manifest and measured signatures only; the 51 documents are not bundled, `scripts/fetch-affinity-corpus.sh` downloads them outside the checkout) | The authors of each document: samuel-etver (vector-art), Seth A. Robinson (Patchy fixtures), Nick Beeuwsaert (AFDesignLoad), Jeremy Cantu (Branding), eviltwo (AssetStoreTemplate), Square (leakcanary) | each file's pinned upstream URL and SHA-256 in the manifest; list carried over from [VectorCraft `xtask/src/affinity_corpus.rs`](https://github.com/storytold/vectorcraft/blob/6e873b806c9d5b3f2b55f651df57bd97933b579a/xtask/src/affinity_corpus.rs) | CC0-1.0, MIT or Apache-2.0 (per file, in the manifest) | +| `crates/raw/docs/coverage/adobe-cameras.tsv` | Facts (maker, model, extension, profile, minimum Camera Raw version) parsed by LightCraft contributors from Adobe's published list | [Adobe Camera Raw supported cameras](https://helpx.adobe.com/camera-raw/desktop/dng-and-file-formats/camera-raw-plug-supported-cameras.html), Wayback capture 20261003133011; moved from [LightCraft `docs/raw`](https://github.com/storytold/lightcraft/tree/5ff567a4a2e067bef1b6bce152c11e7f727ccbaf/docs/raw) | Facts, not copyrightable expression; the file is MIT OR Apache-2.0 | +| `crates/raw/docs/coverage/{coverage,coverage-sweep,evidence,usage-weights}.tsv`, `coverage.py` | LightCraft contributors | [LightCraft `docs/raw`](https://github.com/storytold/lightcraft/tree/5ff567a4a2e067bef1b6bce152c11e7f727ccbaf/docs/raw) | MIT OR Apache-2.0 | +| `crates/raw/docs/raf-corpus.sha256` (hashes only; the files are not bundled) | The photographers who contributed each file to raw.pixls.us | [raw.pixls.us](https://raw.pixls.us/) | CC0-1.0 | +| `crates/drawingml/src/preset_text.txt` | DeckCraft contributors (Nikita Rakitin); generated by `crates/drawingml/tests/fixtures/make_preset_guides.py` from the guide formulas of ECMA-376 Part 1 `presetShapeDefinitions.xml` | [storytold/deckcraft#650](https://github.com/storytold/deckcraft/pull/650) | MIT OR Apache-2.0 (the formulas are the format's definition in ECMA-376) | +| `crates/drawingml/tests/fixtures/preset_table.txt` | DeckCraft contributors (Nikita Rakitin); generated by `crates/drawingml/tests/fixtures/make_preset_table.py` from ECMA-376 Part 1 `presetShapeDefinitions.xml` | [storytold/deckcraft#650](https://github.com/storytold/deckcraft/pull/650) | MIT OR Apache-2.0 (the formulas are the format's definition in ECMA-376) | diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 000000000..31364ecf9 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,65 @@ +# Changelog + +All crates share the workspace version. See [the versioning policy](docs/versioning.md). + +## v0.1.0 — 2026-10-12 + +First coordinated Git release of craft-libs. Applications can pin a named baseline instead of +following development commits. This is an initial 0.x release: compatibility is maintained +within `0.1.x`; changes requiring consumer migration use a new minor version. + +### Included crates + +- **craft-atomic:** same-directory staged file replacement, exclusive creation, streaming + writes, transient rename retries and fault-injection support, extracted from PhotoCraft. +- **craft-settings:** app-owned TOML settings with platform/portable paths, atomic saves, + backups, damaged-file recovery, schema migrations and preservation of unknown fields. +- **craft-quit:** native macOS termination, optional egui close handling and an optional + application menu. Save decisions and prompts stay with the app. +- **craft-print:** CUPS and native Windows PDF submission, printer discovery, copies, duplex, + colour and scaling options. Includes bounded PDF sheet handling and the pinned Windows + completion fix. PDF generation stays with the app. +- **craft-ui:** egui icon buttons, tabs, splits, resize handles, toolbar overflow, transactional + docking, theme helpers and print-settings controls. Commands, content, localization and + application state stay with the consumer. Docking serialization is opt-in through `serde`. + +### Requirements and adoption + +- Rust **1.95+**, edition 2024. Public UI integrations use **egui 0.36**. +- Use `git = "https://github.com/storytold/craft-libs", tag = "v0.1.0"` for each required crate; + use the same tag everywhere. The [README](README.md#use-a-released-version) has a complete + manifest example and a commit-pin alternative. Commit application lockfiles. +- No automatic migration from an arbitrary earlier Git revision is implied. Compare the API + you used with this release and test affected workflows before changing pins. +- For `craft-quit`, run the close hook last in `eframe::App::logic`, after the app's unsaved-work + decision. Finish asynchronous saves before requesting close; termination does not execute + code after `run_native`. See the crate's API documentation before adoption. +- This release is distributed through Git only. No crates.io packages are published by it. + +### Platform coverage and known limits + +The release gate checks the workspace on Linux, macOS and Windows with default and all features, +plus Linux minimum-compiler and UI/settings WASM checks. UI tests include offscreen visual +regressions. Windows print tests exercise a temporary paused spooler queue; those checks do +not establish physical printer fidelity or every application's native GUI behavior. + +- `craft-ui` supports native and WASM use. Font coverage, bidirectional text and screen-reader + behavior still depend on the application and upstream stack; see [#17](https://github.com/storytold/craft-libs/issues/17). +- `craft-settings` persistence is native-only. WASM exposes settings traits, document helpers + and error types. Concurrent writers are best-effort, last-writer-wins; strict coordination + needs an application-owned lock. +- `craft-atomic` does not preserve all filesystem metadata during replacement. Directory sync + is best effort; tests do not prove physical power-loss durability. See its README's contract. +- `craft-quit`'s native behavior is macOS-specific; other platforms keep their normal close + path. Earlier hardware testing of the close hook is recorded in + [#3](https://github.com/storytold/craft-libs/issues/3); it does not qualify every consuming app. +- `craft-print` requires CUPS command-line tools on Linux/macOS or the native Windows spooler. + Browser submission is unsupported. Windows accepts a bounded subset of print-ready PDFs; + unsupported inputs and driver paper/scaling mismatches return errors. Printing is synchronous, + so call it from a worker. Physical output needs hardware testing. +- Windows printing retains a pinned Git dependency on the maintained `winprint` fork. Its + build dependencies require the license/advisory policy exceptions documented in + [craft-print's README](crates/print/README.md). Registry publication is deferred. + +Planned crates and open feature PRs are not part of this release. Existing commit pins remain +valid, and consumers do not need to update simply because `main` changes. diff --git a/CLAUDE.md b/CLAUDE.md index 11908a75d..43c994c2d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1 +1 @@ -Read `AGENTS.md`. +@AGENTS.md diff --git a/Cargo.lock b/Cargo.lock index 4136a81de..2dbe34bdd 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4,21 +4,23 @@ version = 4 [[package]] name = "accesskit" -version = "0.24.1" +version = "0.25.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "d3b7f7f85a7e5f68090000ed7622545829afd484d210358702ae4cb97dd0c320" +checksum = "ad442f58ee04714aaa0ba0a2768c1ea1935b29507bb22ddece8cbbc76db02932" dependencies = [ + "enumn", + "serde", "uuid", ] [[package]] name = "accesskit_consumer" -version = "0.35.0" +version = "0.39.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "53cf47daed85312e763fbf85ceca136e0d7abc68e0a7e12abe11f48172bc3b10" +checksum = "8a45e2bb300bea6d5f33a82c3e051c3ddc6f41c209750f68a0acbe991a284344" dependencies = [ "accesskit", - "hashbrown 0.16.1", + "hashbrown 0.17.1", ] [[package]] @@ -27,6 +29,62 @@ version = "2.0.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa" +[[package]] +name = "aead" +version = "0.5.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d122413f284cf2d62fb1b7db97e02edb8cda96d769b16e443a4f6195e35662b0" +dependencies = [ + "bytes", + "crypto-common 0.1.7", + "generic-array", +] + +[[package]] +name = "aes" +version = "0.8.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b169f7a6d4742236a0a00c541b845991d0ac43e546831af1249753ab4c3aa3a0" +dependencies = [ + "cfg-if", + "cipher 0.4.4", + "cpufeatures 0.2.17", +] + +[[package]] +name = "aes" +version = "0.9.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fc0fc36d7440d015b45468ba08a21e80e056ebbd014c611c6298bb7503e04bd1" +dependencies = [ + "cipher 0.5.2", + "cpubits", + "cpufeatures 0.3.1", +] + +[[package]] +name = "aes-gcm" +version = "0.10.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "831010a0f742e1209b3bcea8fab6a8e149051ba6099432c8cb2cc117dec3ead1" +dependencies = [ + "aead", + "aes 0.8.4", + "cipher 0.4.4", + "ctr", + "ghash", + "subtle", +] + +[[package]] +name = "aes-kw" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "69fa2b352dcefb5f7f3a5fb840e02665d311d878955380515e4fd50095dd3d8c" +dependencies = [ + "aes 0.8.4", +] + [[package]] name = "ahash" version = "0.8.12" @@ -35,6 +93,7 @@ checksum = "5a15f179cd60c4584b8a8c596927aadc462e27f2ca70c04e0071964a73ba7a75" dependencies = [ "cfg-if", "once_cell", + "serde", "version_check", "zerocopy", ] @@ -45,13 +104,28 @@ version = "2.0.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "cc7bb162ec39d46ab1ca8c77bf72e890535becd1751bb45f64c597edb4c8c6b3" +[[package]] +name = "alloc-no-stdlib" +version = "3.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c2fb6cfd47bf496ff64095c20eaba0c201404ee38714d4142fcfa1dc334fcc7a" + [[package]] name = "alloc-stdlib" version = "0.2.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0e76a019e91224d279006ff972f1e984179a6e9feb050adba6ce8274aef23195" dependencies = [ - "alloc-no-stdlib", + "alloc-no-stdlib 2.0.4", +] + +[[package]] +name = "alloc-stdlib" +version = "0.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0b5c1865780388bfa186411ab5f247819487fc4864c6e9c3106611fa347586e1" +dependencies = [ + "alloc-no-stdlib 3.0.0", ] [[package]] @@ -60,6 +134,12 @@ version = "0.2.21" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "683d7910e743518b0e34f1186f92494becacb047c7b6bf616c96772180fef923" +[[package]] +name = "ambient-authority" +version = "0.0.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e9d4ee0d472d1cd2e28c97dfa124b3d8d992e10eb0a035f33f5d12e3a177ba3b" + [[package]] name = "android-activity" version = "0.6.1" @@ -95,23 +175,22 @@ dependencies = [ ] [[package]] -name = "arboard" -version = "3.6.1" +name = "anyhow" +version = "1.0.104" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0348a1c054491f4bfe6ab86a7b6ab1e44e45d899005de92f58b3df180b36ddaf" +checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470" + +[[package]] +name = "argon2" +version = "0.5.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3c3610892ee6e0cbce8ae2700349fcf8f98adb0dbfbee85aec3c9179d29cc072" dependencies = [ - "clipboard-win", - "image", - "log", - "objc2 0.6.5", - "objc2-app-kit 0.3.2", - "objc2-core-foundation", - "objc2-core-graphics", - "objc2-foundation 0.3.2", - "parking_lot", - "percent-encoding", - "windows-sys 0.60.2", - "x11rb", + "base64ct", + "blake2", + "cpufeatures 0.2.17", + "password-hash", + "zeroize", ] [[package]] @@ -125,6 +204,15 @@ name = "arrayvec" version = "0.7.8" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d3fb67a6e08acf24fdeccbac2cb6ac4305825bd1f117462e0e6f2f193345ad56" +dependencies = [ + "serde", +] + +[[package]] +name = "as-raw-xcb-connection" +version = "1.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "175571dd1d178ced59193a6fc02dde1b972eb0bc56c892cde9beeceac5bf0f6b" [[package]] name = "ash" @@ -135,6 +223,126 @@ dependencies = [ "libloading", ] +[[package]] +name = "async-broadcast" +version = "0.7.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "435a87a52755b8f27fcf321ac4f04b2802e337c8c4872923137471ec39c37532" +dependencies = [ + "event-listener", + "event-listener-strategy", + "futures-core", + "pin-project-lite", +] + +[[package]] +name = "async-channel" +version = "2.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "924ed96dd52d1b75e9c1a3e6275715fd320f5f9439fb5a4a11fa51f4221158d2" +dependencies = [ + "concurrent-queue", + "event-listener-strategy", + "futures-core", + "pin-project-lite", +] + +[[package]] +name = "async-executor" +version = "1.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c96bf972d85afc50bf5ab8fe2d54d1586b4e0b46c97c50a0c9e71e2f7bcd812a" +dependencies = [ + "async-task", + "concurrent-queue", + "fastrand", + "futures-lite", + "pin-project-lite", + "slab", +] + +[[package]] +name = "async-io" +version = "2.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "456b8a8feb6f42d237746d4b3e9a178494627745c3c56c6ea55d92ba50d026fc" +dependencies = [ + "autocfg", + "cfg-if", + "concurrent-queue", + "futures-io", + "futures-lite", + "parking", + "polling", + "rustix 1.1.5", + "slab", + "windows-sys 0.61.2", +] + +[[package]] +name = "async-lock" +version = "3.4.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "290f7f2596bd5b78a9fec8088ccd89180d7f9f55b94b0576823bbbdc72ee8311" +dependencies = [ + "event-listener", + "event-listener-strategy", + "pin-project-lite", +] + +[[package]] +name = "async-process" +version = "2.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fc50921ec0055cdd8a16de48773bfeec5c972598674347252c0399676be7da75" +dependencies = [ + "async-channel", + "async-io", + "async-lock", + "async-signal", + "async-task", + "blocking", + "cfg-if", + "event-listener", + "futures-lite", + "rustix 1.1.5", +] + +[[package]] +name = "async-recursion" +version = "1.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4f8abc12baad266b1c8cec146854c195b5864b4221d4b2ca7296a7ae82d9e451" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.6", +] + +[[package]] +name = "async-signal" +version = "0.2.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "52b5aaafa020cf5053a01f2a60e8ff5dccf550f0f77ec54a4e47285ac2bab485" +dependencies = [ + "async-io", + "async-lock", + "atomic-waker", + "cfg-if", + "futures-core", + "futures-io", + "rustix 1.1.5", + "signal-hook-registry", + "slab", + "windows-sys 0.61.2", +] + +[[package]] +name = "async-task" +version = "4.7.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8b75356056920673b02621b35afd0f7dda9306d03c79a30f5c56c44cf256e3de" + [[package]] name = "async-trait" version = "0.1.92" @@ -182,6 +390,18 @@ dependencies = [ "pkg-config", ] +[[package]] +name = "base16ct" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4c7f02d4ea65f2c1853089ffd8d2787bdbc63de2f0d29dedbcf8ccdfa0ccd4cf" + +[[package]] +name = "base16ct" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fd307490d624467aa6f74b0eabb77633d1f758a7b25f12bceb0b22e08d9726f6" + [[package]] name = "base64" version = "0.22.1" @@ -234,6 +454,33 @@ dependencies = [ "serde", ] +[[package]] +name = "bit_field" +version = "0.10.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cb2907cc03d08cdb1c6724ad0670ce67c4a71e1c45a6d7635224011714cfc4b1" + +[[package]] +name = "bitfields" +version = "1.0.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ef6e59298da389bc0649c7463856b34c6e17fe542f88939426ede4436c6b1195" +dependencies = [ + "bitfields-impl", +] + +[[package]] +name = "bitfields-impl" +version = "1.0.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f2c044f98f86f15414668d6c8187c7e4fadab1ad2b31680f648703e0fe07c555" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", + "thiserror 2.0.21", +] + [[package]] name = "bitflags" version = "1.3.2" @@ -246,6 +493,40 @@ version = "2.13.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06" +[[package]] +name = "bitvec" +version = "1.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ddcec3d12c579d40898fe0a9a358a803c23e9c52ca3c425707f81c9436211837" +dependencies = [ + "funty", + "radium", + "tap", + "wyz", +] + +[[package]] +name = "blake2" +version = "0.10.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "46502ad458c9a52b69d4d4d32775c788b7a1b85e8bc9d482d92250fc0e3f8efe" +dependencies = [ + "digest 0.10.7", +] + +[[package]] +name = "blake3" +version = "1.8.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6d9e454fc11f76977dc803893aff6304ed33d6a26efae8696573bea74baa27ae" +dependencies = [ + "arrayvec", + "cc", + "cfg-if", + "constant_time_eq", + "cpufeatures 0.3.1", +] + [[package]] name = "block-buffer" version = "0.10.4" @@ -255,6 +536,33 @@ dependencies = [ "generic-array", ] +[[package]] +name = "block-buffer" +version = "0.12.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d2f6c7dbe95a6ed67ad9f18e57daf93a2f034c524b99fd2b76d18fdfeb6660aa" +dependencies = [ + "hybrid-array", +] + +[[package]] +name = "block-padding" +version = "0.3.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a8894febbff9f758034a5b8e12d87918f56dfc64a8e1fe757d65e29041538d93" +dependencies = [ + "generic-array", +] + +[[package]] +name = "block-padding" +version = "0.4.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "710f1dd022ef4e93f8a438b4ba958de7f64308434fa6a87104481645cc30068b" +dependencies = [ + "hybrid-array", +] + [[package]] name = "block2" version = "0.5.1" @@ -273,6 +581,29 @@ dependencies = [ "objc2 0.6.5", ] +[[package]] +name = "blocking" +version = "1.7.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a70e4329df6cb94385eed412ec92375c3cdd8a6e502493d1229b6414e4036dfa" +dependencies = [ + "async-channel", + "async-task", + "futures-io", + "futures-lite", + "piper", +] + +[[package]] +name = "blowfish" +version = "0.9.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e412e2cd0f2b2d93e02543ceae7917b3c70331573df19ee046bcbc35e45e87d7" +dependencies = [ + "byteorder", + "cipher 0.4.4", +] + [[package]] name = "borsh" version = "1.8.1" @@ -297,15 +628,50 @@ dependencies = [ "syn 3.0.6", ] +[[package]] +name = "bp256" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "46f98c2d9e8e0796b24f84b7ae14159b91ae6ae4b85f74f7655a678a56ad5e1e" +dependencies = [ + "ecdsa 0.17.0", + "elliptic-curve 0.14.3", + "primefield", + "primeorder 0.14.0", +] + +[[package]] +name = "bp384" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bc61f3a96b44a33fbb971e9917b81f4207d6dae9a6b0715845c785a48e73d9c2" +dependencies = [ + "ecdsa 0.17.0", + "elliptic-curve 0.14.3", + "primefield", + "primeorder 0.14.0", +] + [[package]] name = "brotli" version = "8.0.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "5cc91aac060a7a1e25823bdccbfb6af1875b88f17c6daac97894eed8207166b3" dependencies = [ - "alloc-no-stdlib", - "alloc-stdlib", - "brotli-decompressor", + "alloc-no-stdlib 2.0.4", + "alloc-stdlib 0.2.4", + "brotli-decompressor 5.0.3", +] + +[[package]] +name = "brotli" +version = "9.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "627b7cfb0578f0eafce087a90fcd40add1231900b69e4d4de2d456260a4f5d81" +dependencies = [ + "alloc-no-stdlib 3.0.0", + "alloc-stdlib 0.3.0", + "brotli-decompressor 6.3.1", ] [[package]] @@ -314,8 +680,27 @@ version = "5.0.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "3a32acac15fe1967bc3986b2a6347dffc965602354ea6f450ad07e8bfd253583" dependencies = [ - "alloc-no-stdlib", - "alloc-stdlib", + "alloc-no-stdlib 2.0.4", + "alloc-stdlib 0.2.4", +] + +[[package]] +name = "brotli-decompressor" +version = "6.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "75c74c9c51b9140663e196b5fb88bc94c334d7a497c8311cb759d8557874747f" +dependencies = [ + "alloc-no-stdlib 3.0.0", + "alloc-stdlib 0.3.0", +] + +[[package]] +name = "buffer-redux" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "431a9cc8d7efa49bc326729264537f5e60affce816c66edf434350778c9f4f54" +dependencies = [ + "memchr", ] [[package]] @@ -344,6 +729,12 @@ dependencies = [ "syn 3.0.6", ] +[[package]] +name = "byteorder" +version = "1.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b" + [[package]] name = "byteorder-lite" version = "0.1.0" @@ -371,27 +762,31 @@ dependencies = [ ] [[package]] -name = "calloop" -version = "0.14.5" +name = "camellia" +version = "0.1.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "43b32313e937c8721c9d17ee9bf60699a6402b4b7c2cb6ac1bee0ffcaa4b4e5e" +checksum = "3264e2574e9ef2b53ce6f536dea83a69ac0bc600b762d1523ff83fe07230ce30" dependencies = [ - "bitflags 2.13.2", - "polling", - "rustix 1.1.5", - "tracing", + "byteorder", + "cipher 0.4.4", ] [[package]] -name = "calloop-wayland-source" -version = "0.4.1" +name = "cap-primitives" +version = "4.0.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "138efcf0940a02ebf0cc8d1eff41a1682a46b431630f4c52450d6265876021fa" +checksum = "8b5f74729fd2f44701d1a8eb47e906cdb3ccd9ec0f02baad85a744b791940b18" dependencies = [ - "calloop 0.14.5", + "ambient-authority", + "fs-set-times", + "io-extras", + "io-lifetimes 3.0.1", + "ipnet", + "maybe-owned", "rustix 1.1.5", - "wayland-backend", - "wayland-client", + "rustix-linux-procfs", + "windows-sys 0.61.2", + "winx", ] [[package]] @@ -400,6 +795,24 @@ version = "0.3.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "37b2a672a2cb129a2e41c10b1224bb368f9f37a2b16b612598138befd7b37eb5" +[[package]] +name = "cast5" +version = "0.11.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "26b07d673db1ccf000e90f54b819db9e75a8348d6eb056e9b8ab53231b7a9911" +dependencies = [ + "cipher 0.4.4", +] + +[[package]] +name = "cbc" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ce2dc9ee5f88d11e0beb842c88b33c8a5cf0d1329c4b19494af42b07dbfe8896" +dependencies = [ + "cipher 0.5.2", +] + [[package]] name = "cc" version = "1.6.0" @@ -412,6 +825,26 @@ dependencies = [ "shlex", ] +[[package]] +name = "cfb" +version = "0.15.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0f13298d9178622b7916ec5d01d470425c04273c8ed07e87b1c38b34c4f4612b" +dependencies = [ + "fnv", + "uuid", + "web-time", +] + +[[package]] +name = "cfb-mode" +version = "0.8.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "738b8d467867f80a71351933f70461f5b56f24d5c93e0cf216e59229c968d330" +dependencies = [ + "cipher 0.4.4", +] + [[package]] name = "cfg-if" version = "1.0.5" @@ -424,6 +857,15 @@ version = "0.2.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "f079e83a288787bcd14a6aea84cee5c87a67c5a3e660c30f557a3d24761b3527" +[[package]] +name = "cgl" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0ced0551234e87afee12411d535648dd89d2e7f34c78b753395567aff3d447ff" +dependencies = [ + "libc", +] + [[package]] name = "chacha20" version = "0.10.2" @@ -435,6 +877,17 @@ dependencies = [ "rand_core 0.10.1", ] +[[package]] +name = "chardetng" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "13de944a44b5064ee5d3a5ceccc49a41bfec50f2580e66f82e87703acdb88b53" +dependencies = [ + "cfg-if", + "encoding_rs", + "memchr", +] + [[package]] name = "chrono" version = "0.4.45" @@ -450,12 +903,34 @@ dependencies = [ ] [[package]] -name = "clipboard-win" -version = "5.4.1" +name = "cipher" +version = "0.4.4" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "bde03770d3df201d4fb868f2c9c59e66a3e4e2bd06692a0fe701e7103c7e84d4" +checksum = "773f3b9af64447d2ce9850330c473515014aa235e6a783b02db81ff39e4a3dad" dependencies = [ - "error-code", + "crypto-common 0.1.7", + "inout 0.1.4", +] + +[[package]] +name = "cipher" +version = "0.5.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e8cf2a2c93cd704877c0858356ed03480ff301ee950b43f1cbe4573b088bfa6c" +dependencies = [ + "crypto-common 0.2.2", + "inout 0.2.6", +] + +[[package]] +name = "cmac" +version = "0.7.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8543454e3c3f5126effff9cd44d562af4e31fb8ce1cc0d3dcd8f084515dbc1aa" +dependencies = [ + "cipher 0.4.4", + "dbl", + "digest 0.10.7", ] [[package]] @@ -467,6 +942,12 @@ dependencies = [ "cc", ] +[[package]] +name = "cmov" +version = "0.5.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0c9ea0ac24bc397ab3c98583a3c9ba74fa56b09a4449bbe172b9b1ddb016027a" + [[package]] name = "cmpv2" version = "0.2.0" @@ -474,8 +955,8 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "961b955a666e25ee5a1091d219128d6e6401e3dab84efb1a2bf6b4035d797b39" dependencies = [ "crmf", - "der", - "spki", + "der 0.7.10", + "spki 0.7.3", "x509-cert", ] @@ -485,12 +966,21 @@ version = "0.2.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "7b77c319abfd5219629c45c34c89ba945ed3c5e49fcde9d16b6c3885f118a730" dependencies = [ - "const-oid", - "der", - "spki", + "const-oid 0.9.6", + "der 0.7.10", + "spki 0.7.3", "x509-cert", ] +[[package]] +name = "cobs" +version = "0.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0fa961b519f0b462e3a3b4a34b64d119eeaca1d59af726fe450bbba07a9fc0a1" +dependencies = [ + "thiserror 2.0.21", +] + [[package]] name = "codespan-reporting" version = "0.13.1" @@ -517,6 +1007,16 @@ version = "1.1.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "3d7b894f5411737b7867f4827955924d7c254fc9f4d91a6aad6b097804b1018b" +[[package]] +name = "colored" +version = "2.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "117725a109d387c937a1533ce01b450cbde6b88abceea8473c4d7a85853cda3c" +dependencies = [ + "lazy_static", + "windows-sys 0.59.0", +] + [[package]] name = "combine" version = "4.6.8" @@ -542,6 +1042,27 @@ version = "0.9.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "c2459377285ad874054d797f3ccebf984978aa39129f6eafde5cdc8315b612f8" +[[package]] +name = "const-oid" +version = "0.10.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "be95d4a884358a21a199689323c29e9256b4a1b315e22f183d155422041d3a9a" + +[[package]] +name = "constant_time_eq" +version = "0.4.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3d52eff69cd5e647efe296129160853a42795992097e8af39800e1060caeea9b" + +[[package]] +name = "convert_case" +version = "0.10.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "633458d4ef8c78b72454de2d54fd6ab2e60f9e02be22f3c6104cdc8a4e0fceb9" +dependencies = [ + "unicode-segmentation", +] + [[package]] name = "core-foundation" version = "0.9.4" @@ -607,6 +1128,12 @@ dependencies = [ "libm", ] +[[package]] +name = "cpubits" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "15b85f9c39137c3a891689859392b1bd49812121d0d61c9caf00d46ed5ce06ae" + [[package]] name = "cpufeatures" version = "0.2.17" @@ -625,14 +1152,49 @@ dependencies = [ "libc", ] +[[package]] +name = "craft-aaf" +version = "0.1.0" +dependencies = [ + "craft-audio", + "craft-cfb", + "craft-timeline", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-aep" +version = "0.1.0" + +[[package]] +name = "craft-affinity" +version = "0.1.0" +dependencies = [ + "crc32fast", + "flate2", + "image", + "proptest", + "ruzstd", + "sha2 0.10.9", +] + [[package]] name = "craft-ai-core" version = "0.1.0" dependencies = [ + "chrono", "serde", "serde_json", ] +[[package]] +name = "craft-assuan" +version = "0.1.0" +dependencies = [ + "proptest", + "thiserror 2.0.21", +] + [[package]] name = "craft-atomic" version = "0.1.0" @@ -640,41 +1202,849 @@ dependencies = [ "rustix 1.1.5", ] +[[package]] +name = "craft-audio" +version = "0.1.0" +dependencies = [ + "craft-media", + "craft-media-testkit", + "log", + "proptest", + "rayon", + "serde", + "serde_json", + "symphonia", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-captions" +version = "0.1.0" +dependencies = [ + "craft-timeline", + "craft-xml", + "proptest", + "roxmltree 0.21.2", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-cfb" +version = "0.1.0" +dependencies = [ + "craft-media-testkit", +] + [[package]] name = "craft-cms" version = "0.1.0" dependencies = [ + "md-5 0.10.6", "moxcms", "rayon", ] +[[package]] +name = "craft-codepage" +version = "0.1.0" +dependencies = [ + "encoding_rs", +] + +[[package]] +name = "craft-crs" +version = "0.1.0" +dependencies = [ + "craft-metadata", + "craft-xml", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-crw" +version = "0.1.0" +dependencies = [ + "proptest", + "serde", + "serde_json", + "sha2 0.10.9", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-csv" +version = "0.1.0" +dependencies = [ + "thiserror 2.0.21", +] + +[[package]] +name = "craft-dav" +version = "0.1.0" +dependencies = [ + "craft-xml", + "proptest", +] + +[[package]] +name = "craft-dialogs" +version = "0.1.0" +dependencies = [ + "block2 0.6.2", + "objc2 0.6.5", + "objc2-app-kit 0.3.2", + "objc2-foundation 0.3.2", + "raw-window-handle", + "rfd", +] + +[[package]] +name = "craft-doc" +version = "0.1.0" +dependencies = [ + "blake3", + "craft-ecproj-format", + "craft-pcraft-format", + "craft-vectorcraft-format", + "flate2", + "proptest", + "ruzstd", + "serde", + "serde_json", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-doc-binary" +version = "0.1.0" +dependencies = [ + "cfb", + "chrono", + "craft-cfb", + "craft-codepage", + "craft-wordmodel", + "image", + "log", + "miniz_oxide 0.9.1", + "proptest", + "serde_json", + "sha1 0.11.0", + "thiserror 2.0.21", +] + [[package]] name = "craft-docpath" version = "0.1.0" +[[package]] +name = "craft-docx" +version = "0.1.0" +dependencies = [ + "base64 0.23.1", + "chrono", + "craft-cfb", + "craft-drawingml", + "craft-math", + "craft-offcrypto", + "craft-opc", + "craft-wordmodel", + "craft-xml", + "image", + "log", + "proptest", + "quick-xml 0.41.0", + "serde_json", + "thiserror 2.0.21", + "unicode-bidi", + "zeroize", + "zip", +] + +[[package]] +name = "craft-dpx" +version = "0.1.0" +dependencies = [ + "thiserror 2.0.21", +] + +[[package]] +name = "craft-drawingml" +version = "0.1.0" +dependencies = [ + "craft-xml", + "kurbo 0.13.1", + "log", + "serde", + "serde_json", +] + +[[package]] +name = "craft-dxf" +version = "0.1.0" +dependencies = [ + "craft-codepage", + "encoding_rs", + "log", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-ecproj-format" +version = "0.1.0" +dependencies = [ + "serde", + "serde_json", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-eps" +version = "0.1.0" + +[[package]] +name = "craft-epub" +version = "0.1.0" +dependencies = [ + "craft-xml", + "craft-zip", + "thiserror 2.0.21", + "zip", +] + +[[package]] +name = "craft-ews" +version = "0.1.0" +dependencies = [ + "craft-xml", + "proptest", +] + +[[package]] +name = "craft-exr" +version = "0.1.0" +dependencies = [ + "exr", + "flate2", + "half", + "serde_json", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-fig" +version = "0.1.0" +dependencies = [ + "craft-figma-rest", + "craft-kiwi", + "craft-zip", + "flate2", + "kurbo 0.13.1", + "ruzstd", + "serde_json", + "thiserror 2.0.21", + "zip", +] + +[[package]] +name = "craft-figma-rest" +version = "0.1.0" +dependencies = [ + "serde", + "serde_json", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-flags" +version = "0.1.0" +dependencies = [ + "craft-atomic", + "dirs", + "tempfile", + "toml_edit", +] + +[[package]] +name = "craft-flow" +version = "0.1.0" +dependencies = [ + "craft-wordmodel", + "image", + "log", +] + +[[package]] +name = "craft-font-catalog" +version = "0.1.0" +dependencies = [ + "fontique", + "skrifa 0.47.0", + "thiserror 2.0.21", + "windows-registry", + "write-fonts 0.54.1", +] + +[[package]] +name = "craft-font-manager" +version = "0.1.0" +dependencies = [ + "craft-font-catalog", + "craft-font-store", + "craft-i18n", + "craft-ui", + "egui", + "egui_kittest", + "egui_system_font_provider", + "epaint_default_fonts", + "image", + "log", + "serde", +] + +[[package]] +name = "craft-font-store" +version = "0.1.0" +dependencies = [ + "cap-primitives", + "craft-atomic", + "craft-font-catalog", + "flate2", + "log", + "ruzstd", + "serde", + "serde_json", + "sha2 0.10.9", + "skrifa 0.47.0", + "tar", + "thiserror 2.0.21", + "toml", + "ureq", + "write-fonts 0.54.1", +] + +[[package]] +name = "craft-fonts-build" +version = "0.1.0" +dependencies = [ + "craft-fonts-build-consumer", + "skera", + "skrifa 0.48.0", +] + +[[package]] +name = "craft-fonts-build-consumer" +version = "0.1.0" +dependencies = [ + "craft-fonts-build", +] + +[[package]] +name = "craft-gainmap" +version = "0.1.0" +dependencies = [ + "thiserror 2.0.21", +] + +[[package]] +name = "craft-gcode" +version = "0.1.0" +dependencies = [ + "thiserror 2.0.21", +] + +[[package]] +name = "craft-gif" +version = "0.1.0" +dependencies = [ + "image", +] + +[[package]] +name = "craft-hdr" +version = "0.1.0" +dependencies = [ + "thiserror 2.0.21", +] + +[[package]] +name = "craft-heif" +version = "0.1.0" +dependencies = [ + "heic-rs", + "rayon", +] + +[[package]] +name = "craft-html" +version = "0.1.0" +dependencies = [ + "craft-codepage", + "craft-flow", + "craft-math", + "craft-mime", + "craft-wordmodel", + "encoding_rs", + "proptest", +] + [[package]] name = "craft-i18n" version = "0.1.0" dependencies = [ - "intl_pluralrules", + "fixed_decimal", + "icu_collator", + "icu_decimal", + "icu_locale_core", + "icu_locale_fallback", + "icu_normalizer", + "icu_plurals", + "icu_properties", + "icu_provider", + "icu_provider_adapters", + "icu_provider_blob", + "log", + "objc2-foundation 0.3.2", "sys-locale", - "unic-langid", + "unicode-bidi", + "windows-registry", + "writeable", +] + +[[package]] +name = "craft-ical" +version = "0.1.0" +dependencies = [ + "chrono", + "proptest", +] + +[[package]] +name = "craft-idml" +version = "0.1.0" +dependencies = [ + "craft-xml", + "craft-zip", + "thiserror 2.0.21", + "zip", +] + +[[package]] +name = "craft-jmap" +version = "0.1.0" +dependencies = [ + "proptest", + "serde_json", +] + +[[package]] +name = "craft-jpeg" +version = "0.1.0" +dependencies = [ + "jpeg-encoder 0.6.1", + "thiserror 2.0.21", + "zune-jpeg", +] + +[[package]] +name = "craft-keymap" +version = "0.1.0" +dependencies = [ + "craft-i18n", + "craft-settings", + "craft-ui", + "egui", + "egui_kittest", + "image", + "serde", + "serde_json", + "sha2 0.10.9", + "tempfile", +] + +[[package]] +name = "craft-kiwi" +version = "0.1.0" + +[[package]] +name = "craft-kra" +version = "0.1.0" +dependencies = [ + "craft-xml", + "craft-zip", + "thiserror 2.0.21", + "zip", +] + +[[package]] +name = "craft-latex" +version = "0.1.0" +dependencies = [ + "craft-flow", + "craft-markdown", + "craft-math", + "craft-mime", + "craft-wordmodel", + "proptest", +] + +[[package]] +name = "craft-lottie" +version = "0.1.0" +dependencies = [ + "serde_json", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-markdown" +version = "0.1.0" +dependencies = [ + "craft-flow", + "craft-html", + "craft-wordmodel", +] + +[[package]] +name = "craft-math" +version = "0.1.0" +dependencies = [ + "craft-xml", + "proptest", + "serde", + "serde_json", +] + +[[package]] +name = "craft-media" +version = "0.1.0" +dependencies = [ + "chrono", + "craft-media-testkit", + "proptest", + "serde", + "serde_json", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-media-testkit" +version = "0.1.0" + +[[package]] +name = "craft-menu" +version = "0.1.0" +dependencies = [ + "craft-keymap", + "craft-quit", + "egui", + "muda", + "objc2 0.6.5", + "objc2-app-kit 0.3.2", +] + +[[package]] +name = "craft-mesh" +version = "0.1.0" +dependencies = [ + "craft-opc", + "craft-xml", + "miniz_oxide 0.9.1", + "serde_json", +] + +[[package]] +name = "craft-metadata" +version = "0.1.0" +dependencies = [ + "brotli 9.1.1", + "brotli-decompressor 6.3.1", + "chrono", + "craft-tiff", + "proptest", + "quick-xml 0.41.0", + "serde", + "serde_json", +] + +[[package]] +name = "craft-metafile" +version = "0.1.0" +dependencies = [ + "encoding_rs", + "image", + "kurbo 0.13.1", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-midi" +version = "0.1.0" +dependencies = [ + "proptest", + "serde", + "serde_json", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-mime" +version = "0.1.0" +dependencies = [ + "chardetng", + "chrono", + "craft-codepage", + "encoding_rs", + "proptest", +] + +[[package]] +name = "craft-odf" +version = "0.1.0" +dependencies = [ + "aes 0.9.4", + "base64 0.23.1", + "chrono", + "craft-flow", + "craft-math", + "craft-metafile", + "craft-wordmodel", + "craft-xml", + "craft-zip", + "flate2", + "getrandom 0.3.4", + "hmac 0.13.0", + "image", + "js-sys", + "log", + "sha1 0.11.0", + "sha2 0.11.1", + "thiserror 2.0.21", + "zeroize", + "zip", +] + +[[package]] +name = "craft-ods" +version = "0.1.0" +dependencies = [ + "craft-odf", + "craft-sheet", + "craft-xml", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-offcrypto" +version = "0.1.0" +dependencies = [ + "aes 0.9.4", + "base64 0.23.1", + "craft-cfb", + "craft-xml", + "getrandom 0.3.4", + "hmac 0.13.0", + "sha1 0.11.0", + "sha2 0.11.1", + "thiserror 2.0.21", + "zeroize", +] + +[[package]] +name = "craft-opc" +version = "0.1.0" +dependencies = [ + "craft-xml", + "craft-zip", + "log", + "thiserror 2.0.21", + "zip", +] + +[[package]] +name = "craft-openpgp" +version = "0.1.0" +dependencies = [ + "ed25519-dalek 2.2.0", + "pgp", + "proptest", + "rand 0.8.8", + "rsa 0.9.10", + "sha1 0.10.7", + "sha2 0.10.9", + "sha3 0.10.9", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-ora" +version = "0.1.0" +dependencies = [ + "craft-xml", + "craft-zip", + "thiserror 2.0.21", + "zip", +] + +[[package]] +name = "craft-pcraft-format" +version = "0.1.0" +dependencies = [ + "serde", + "serde_json", + "thiserror 2.0.21", ] [[package]] name = "craft-pdf" version = "0.1.0" dependencies = [ + "aes 0.9.4", "bytemuck", + "chrono", + "craft-stream-codecs", + "flate2", "hayro", "hayro-cmap", "hayro-interpret", "hayro-syntax", + "js-sys", "krilla", "kurbo 0.13.1", + "md-5 0.11.0", + "proptest", + "serde_json", + "sha2 0.11.1", + "stringprep", "thiserror 2.0.21", "ttf-parser", + "wasm-bindgen", "wasm-bindgen-test", + "zeroize", +] + +[[package]] +name = "craft-pdn" +version = "0.1.0" +dependencies = [ + "flate2", + "proptest", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-penpot" +version = "0.1.0" +dependencies = [ + "craft-zip", + "serde", + "serde_json", + "thiserror 2.0.21", + "zip", +] + +[[package]] +name = "craft-pkcs7" +version = "0.1.0" +dependencies = [ + "aes 0.9.4", + "aws-lc-rs", + "base64 0.23.1", + "bp256", + "bp384", + "cbc", + "chrono", + "crypto-bigint 0.7.11", + "des 0.9.0", + "ecdsa 0.17.0", + "ed25519-dalek 3.0.0", + "getrandom 0.4.3", + "hmac 0.13.0", + "p256 0.14.0", + "p384 0.14.0", + "p521 0.14.0", + "pbkdf2", + "rc2", + "ripemd 0.2.0", + "rsa 0.10.0-rc.18", + "sha1 0.11.0", + "sha2 0.11.1", + "sha3 0.12.0", + "thiserror 2.0.21", + "zeroize", +] + +[[package]] +name = "craft-plate-test" +version = "0.1.0" +dependencies = [ + "craft-cms", + "craft-pdf", + "hayro-syntax", + "serde", + "serde_json", + "tempfile", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-platform" +version = "0.1.0" +dependencies = [ + "async-channel", + "async-io", + "async-process", + "egui", + "futures-lite", + "js-sys", + "wasm-bindgen", + "wasm-bindgen-futures", + "wasm-bindgen-test", + "web-sys", + "zbus", +] + +[[package]] +name = "craft-plotter" +version = "0.1.0" +dependencies = [ + "serde", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-pptx" +version = "0.1.0" +dependencies = [ + "craft-drawingml", + "craft-opc", + "craft-xml", + "kurbo 0.13.1", + "log", + "serde", + "serde_json", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-prc" +version = "0.1.0" +dependencies = [ + "flate2", + "proptest", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-prepress" +version = "0.1.0" +dependencies = [ + "craft-cms", + "craft-pdf", + "craft-plate-test", + "kurbo 0.13.1", + "linesweeper", + "thiserror 2.0.21", + "ttf-parser", ] [[package]] @@ -682,13 +2052,45 @@ name = "craft-print" version = "0.1.0" dependencies = [ "craft-winprint-gdi", - "miniz_oxide 0.8.9", - "roxmltree", + "log", + "miniz_oxide 0.9.1", + "roxmltree 0.21.2", "tempfile", "winprint", "winsafe", ] +[[package]] +name = "craft-proof" +version = "0.1.0" +dependencies = [ + "log", + "miniz_oxide 0.9.1", + "proptest", + "toml", + "unicode-normalization", +] + +[[package]] +name = "craft-psd" +version = "0.1.0" +dependencies = [ + "craft-psd", + "encoding_rs", + "flate2", + "proptest", + "rayon", + "serde", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-pst" +version = "0.1.0" +dependencies = [ + "proptest", +] + [[package]] name = "craft-quit" version = "0.1.0" @@ -700,6 +2102,49 @@ dependencies = [ "objc2-app-kit 0.3.2", ] +[[package]] +name = "craft-raster-codecs" +version = "0.1.0" +dependencies = [ + "rayon", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-raw" +version = "0.1.0" +dependencies = [ + "chrono", + "craft-crw", + "craft-metadata", + "craft-tiff", + "jpeg-encoder 0.7.1", + "jxl-oxide", + "miniz_oxide 0.9.1", + "proptest", + "rayon", + "serde", + "sha2 0.10.9", + "thiserror 2.0.21", + "zune-core", + "zune-jpeg", + "zune-jpegxl", +] + +[[package]] +name = "craft-rtf" +version = "0.1.0" +dependencies = [ + "craft-codepage", + "craft-flow", + "craft-metafile", + "craft-mime", + "craft-wordmodel", + "encoding_rs", + "image", + "proptest", +] + [[package]] name = "craft-settings" version = "0.1.0" @@ -711,6 +2156,100 @@ dependencies = [ "toml_edit", ] +[[package]] +name = "craft-sf2" +version = "0.1.0" +dependencies = [ + "craft-sf2", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-sheet" +version = "0.1.0" + +[[package]] +name = "craft-silhouette-studio" +version = "0.1.0" +dependencies = [ + "kurbo 0.13.1", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-sketch" +version = "0.1.0" +dependencies = [ + "craft-figma-rest", + "craft-zip", + "kurbo 0.13.1", + "serde_json", + "thiserror 2.0.21", + "zip", +] + +[[package]] +name = "craft-stream-codecs" +version = "0.1.0" +dependencies = [ + "fax", + "hayro-ccitt", + "hayro-jbig2", + "proptest", + "thiserror 2.0.21", + "weezl 0.2.1", +] + +[[package]] +name = "craft-svg" +version = "0.1.0" +dependencies = [ + "craft-xml", + "flate2", + "kurbo 0.13.1", + "roxmltree 0.21.2", + "thiserror 2.0.21", + "usvg 0.48.1", +] + +[[package]] +name = "craft-svg-paths" +version = "0.1.0" +dependencies = [ + "craft-svg", + "kurbo 0.13.1", +] + +[[package]] +name = "craft-text" +version = "0.1.0" +dependencies = [ + "hypher", + "icu_segmenter", + "miniz_oxide 0.8.9", + "unicode-bidi", + "unicode-bidi-mirroring", + "unicode-general-category", + "unicode-linebreak", + "unicode-segmentation", +] + +[[package]] +name = "craft-tga" +version = "0.1.0" +dependencies = [ + "thiserror 2.0.21", +] + +[[package]] +name = "craft-tiff" +version = "0.1.0" +dependencies = [ + "proptest", + "serde", + "thiserror 2.0.21", +] + [[package]] name = "craft-time" version = "0.1.0" @@ -722,25 +2261,236 @@ dependencies = [ ] [[package]] -name = "craft-ui" +name = "craft-timeline" version = "0.1.0" dependencies = [ - "egui", - "egui_extras", - "egui_kittest", - "image", + "craft-xml", + "proptest", "serde", "serde_json", ] +[[package]] +name = "craft-ui" +version = "0.1.0" +dependencies = [ + "craft-fonts-build", + "craft-i18n", + "eframe", + "egui", + "egui_extras", + "egui_kittest", + "epaint", + "fontique", + "image", + "js-sys", + "log", + "objc2 0.6.5", + "objc2-app-kit 0.3.2", + "objc2-foundation 0.3.2", + "serde", + "serde_json", + "skrifa 0.44.0", + "unicode-script", + "wasm-bindgen", + "wasm-bindgen-futures", + "wasm-bindgen-test", + "web-sys", +] + +[[package]] +name = "craft-update" +version = "0.1.0" +dependencies = [ + "chrono", + "dunce", + "egui", + "egui_kittest", + "epaint_default_fonts", + "flate2", + "getrandom 0.3.4", + "image", + "log", + "plist", + "rustix 1.1.5", + "semver", + "serde", + "serde_json", + "sha2 0.10.9", + "tar", + "tempfile", + "ureq", + "verifysign", + "winreg", + "winsafe", + "zip", +] + +[[package]] +name = "craft-vcard" +version = "0.1.0" +dependencies = [ + "chrono", + "craft-mime", + "proptest", +] + +[[package]] +name = "craft-vectorcraft-format" +version = "0.1.0" +dependencies = [ + "flate2", + "serde", + "serde_json", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-vectordrawable" +version = "0.1.0" +dependencies = [ + "craft-xml", + "kurbo 0.13.1", +] + +[[package]] +name = "craft-video" +version = "0.1.0" +dependencies = [ + "craft-media", + "craft-media-testkit", + "rayon", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-web-api" +version = "0.1.0" +dependencies = [ + "js-sys", + "serde_json", + "wasm-bindgen", + "wasm-bindgen-futures", + "wasm-bindgen-test", +] + +[[package]] +name = "craft-web-host" +version = "0.1.0" +dependencies = [ + "wasm-bindgen", + "wasm-bindgen-test", + "web-sys", +] + +[[package]] +name = "craft-webp" +version = "0.1.0" +dependencies = [ + "craft-video", + "image", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-window" +version = "0.1.0" +dependencies = [ + "craft-atomic", + "craft-settings", + "egui", + "objc2 0.6.5", + "objc2-app-kit 0.3.2", + "serde", + "serde_json", + "tempfile", + "wayland-client", +] + [[package]] name = "craft-winprint-gdi" version = "0.1.0" -source = "git+https://github.com/storytold/winprint.rs?rev=417ac3c4d14d3da5485a99c7d5ce8f05664ec312#417ac3c4d14d3da5485a99c7d5ce8f05664ec312" +source = "git+https://github.com/storytold/winprint.rs?rev=64e7afd4d1483512385012c340ecaaaf0f3beb7f#64e7afd4d1483512385012c340ecaaaf0f3beb7f" dependencies = [ "windows-sys 0.61.2", ] +[[package]] +name = "craft-wordmodel" +version = "0.1.0" +dependencies = [ + "base64 0.23.1", + "craft-math", + "log", + "proptest", + "serde", + "serde_json", + "thiserror 2.0.21", + "unicode-segmentation", +] + +[[package]] +name = "craft-xcf" +version = "0.1.0" +dependencies = [ + "flate2", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-xls" +version = "0.1.0" +dependencies = [ + "craft-cfb", + "craft-sheet", + "md-5 0.10.6", + "miniz_oxide 0.9.1", + "sha1 0.10.7", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-xlsx" +version = "0.1.0" +dependencies = [ + "craft-drawingml", + "craft-opc", + "craft-sheet", + "craft-xml", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-xml" +version = "0.1.0" +dependencies = [ + "quick-xml 0.41.0", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-y4m" +version = "0.1.0" +dependencies = [ + "thiserror 2.0.21", +] + +[[package]] +name = "craft-zip" +version = "0.1.0" +dependencies = [ + "craft-zip", + "flate2", + "thiserror 2.0.21", + "zip", +] + +[[package]] +name = "crc24" +version = "0.1.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fd121741cf3eb82c08dd3023eb55bf2665e5f60ec20f89760cf836ae4562e6a0" + [[package]] name = "crc32fast" version = "1.5.2" @@ -757,8 +2507,8 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "36fe21b96d5b87f5de4b5b7202ec41c00110ac817ce6728fe75fb2fe5962ed92" dependencies = [ "cms", - "der", - "spki", + "der 0.7.10", + "spki 0.7.3", "x509-cert", ] @@ -802,6 +2552,35 @@ version = "0.2.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "460fbee9c2c2f33933d720630a6a0bac33ba7053db5344fac858d4b8952d77d5" +[[package]] +name = "crypto-bigint" +version = "0.5.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0dc92fb57ca44df6db8059111ab3af99a63d5d0f8375d9972e319a379c6bab76" +dependencies = [ + "generic-array", + "rand_core 0.6.4", + "subtle", + "zeroize", +] + +[[package]] +name = "crypto-bigint" +version = "0.7.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "914c195c4d7fbc5ed7f88d14cbf85914d5c664967658d43404b263913a477e82" +dependencies = [ + "cpubits", + "ctutils", + "getrandom 0.4.3", + "hybrid-array", + "num-traits", + "rand_core 0.10.1", + "serdect 0.4.3", + "subtle", + "zeroize", +] + [[package]] name = "crypto-common" version = "0.1.7" @@ -809,31 +2588,187 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a" dependencies = [ "generic-array", + "rand_core 0.6.4", "typenum", ] +[[package]] +name = "crypto-common" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ce6e4c961d6cd6c9a86db418387425e8bdeaf05b3c8bc1411e6dca4c252f1453" +dependencies = [ + "getrandom 0.4.3", + "hybrid-array", + "rand_core 0.10.1", +] + +[[package]] +name = "crypto-primes" +version = "0.7.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3633a51a39c69ebbaa4feaa694bd83d241e4093901c84a0963b19d9bb3f0cf8f" +dependencies = [ + "crypto-bigint 0.7.11", + "rand_core 0.10.1", +] + +[[package]] +name = "ctr" +version = "0.9.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0369ee1ad671834580515889b80f2ea915f23b8be8d0daa4bbaf2ac5c7590835" +dependencies = [ + "cipher 0.4.4", +] + +[[package]] +name = "ctutils" +version = "0.4.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "261af4dc7a06ea8a527a8717d8cbba3417530d6ea14e1edb3de6b67806be474f" +dependencies = [ + "cmov", + "subtle", +] + [[package]] name = "cursor-icon" version = "1.2.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "f27ae1dd37df86211c42e150270f82743308803d90a6f6e6651cd730d5e1732f" +[[package]] +name = "curve25519-dalek" +version = "4.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "97fb8b7c4503de7d6ae7b42ab72a5a59857b4c937ec27a3d4539dba95b5ab2be" +dependencies = [ + "cfg-if", + "cpufeatures 0.2.17", + "curve25519-dalek-derive", + "digest 0.10.7", + "fiat-crypto 0.2.9", + "rustc_version", + "subtle", + "zeroize", +] + +[[package]] +name = "curve25519-dalek" +version = "5.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b5eed333089e2e1c1ac8c6c0398e5e2497b4c9926ca6d0365ed1e099afa5bc23" +dependencies = [ + "cfg-if", + "cpufeatures 0.3.1", + "curve25519-dalek-derive", + "digest 0.11.3", + "fiat-crypto 0.3.0", + "rustc_version", + "subtle", + "zeroize", +] + +[[package]] +name = "curve25519-dalek-derive" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f46882e17999c6cc590af592290432be3bce0428cb0d5f8b6715e4dc7b383eb3" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "cx448" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b4c0cf476284b03eb6c10e78787b21c7abb7d7d43cb2f02532ba6b831ed892fa" +dependencies = [ + "crypto-bigint 0.5.5", + "elliptic-curve 0.13.8", + "pkcs8 0.10.2", + "rand_core 0.6.4", + "serdect 0.3.0", + "sha3 0.10.9", + "signature 2.2.0", + "subtle", + "zeroize", +] + +[[package]] +name = "darling" +version = "0.20.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fc7f46116c46ff9ab3eb1597a45688b6715c6e628b5c133e288e709a29bcb4ee" +dependencies = [ + "darling_core", + "darling_macro", +] + +[[package]] +name = "darling_core" +version = "0.20.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0d00b9596d185e565c2207a0b01f8bd1a135483d02d9b7b0a54b11da8d53412e" +dependencies = [ + "fnv", + "ident_case", + "proc-macro2", + "quote", + "strsim", + "syn 2.0.119", +] + +[[package]] +name = "darling_macro" +version = "0.20.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fc34b93ccb385b40dc71c6fceac4b2ad23662c7eeb248cf10d529b7e055b6ead" +dependencies = [ + "darling_core", + "quote", + "syn 2.0.119", +] + [[package]] name = "data-url" version = "0.3.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "be1e0bca6c3637f992fc1cc7cbc52a78c1ef6db076dbf1059c4323d6a2048376" +[[package]] +name = "dbl" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bd2735a791158376708f9347fe8faba9667589d82427ef3aed6794a8981de3d9" +dependencies = [ + "generic-array", +] + [[package]] name = "der" version = "0.7.10" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "e7c1832837b905bbfb5101e07cc24c8deddf52f93225eee6ead5f4d63d53ddcb" dependencies = [ - "const-oid", + "const-oid 0.9.6", "der_derive", "flagset", - "pem-rfc7468", + "pem-rfc7468 0.7.0", + "zeroize", +] + +[[package]] +name = "der" +version = "0.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6a996a108feb8b427a6e12fcf6af4aa83409b79d72c15337d7741368131ee004" +dependencies = [ + "const-oid 0.10.3", + "pem-rfc7468 1.0.0", "zeroize", ] @@ -848,14 +2783,119 @@ dependencies = [ "syn 2.0.119", ] +[[package]] +name = "deranged" +version = "0.5.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9e9de72ce2ad1f90dc62fa25f0f430ef85eb4b0d8fa0be4f30373bc40a21d28e" + +[[package]] +name = "derive_builder" +version = "0.20.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "507dfb09ea8b7fa618fcf76e953f4f5e192547945816d5358edffe39f6f94947" +dependencies = [ + "derive_builder_macro", +] + +[[package]] +name = "derive_builder_core" +version = "0.20.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2d5bcf7b024d6835cfb3d473887cd966994907effbe9227e8c8219824d06c4e8" +dependencies = [ + "darling", + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "derive_builder_macro" +version = "0.20.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ab63b0e2bf4d5928aff72e83a7dace85d7bba5fe12dcc3c5a572d78caffd3f3c" +dependencies = [ + "derive_builder_core", + "syn 2.0.119", +] + +[[package]] +name = "derive_more" +version = "2.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d751e9e49156b02b44f9c1815bcb94b984cdcc4396ecc32521c739452808b134" +dependencies = [ + "derive_more-impl", +] + +[[package]] +name = "derive_more-impl" +version = "2.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "799a97264921d8623a957f6c3b9011f3b5492f557bbb7a5a19b7fa6d06ba8dcb" +dependencies = [ + "convert_case", + "proc-macro2", + "quote", + "rustc_version", + "syn 2.0.119", + "unicode-xid", +] + +[[package]] +name = "des" +version = "0.8.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ffdd80ce8ce993de27e9f063a444a4d53ce8e8db4c1f00cc03af5ad5a9867a1e" +dependencies = [ + "cipher 0.4.4", +] + +[[package]] +name = "des" +version = "0.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "916a94e407b54f9034d71dd748234cd1e516ced6284009906ae246f177eafe5a" +dependencies = [ + "cipher 0.5.2", +] + +[[package]] +name = "dify" +version = "0.8.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "90ce0fb972943b4e88cd03b8f92953df0c71bb05e0bde8e5b684895d808013cc" +dependencies = [ + "anyhow", + "colored", + "getopts", + "image", + "rayon", +] + [[package]] name = "digest" version = "0.10.7" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292" dependencies = [ - "block-buffer", - "crypto-common", + "block-buffer 0.10.4", + "const-oid 0.9.6", + "crypto-common 0.1.7", + "subtle", +] + +[[package]] +name = "digest" +version = "0.11.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f1dd6dbb5841937940781866fa1281a1ff7bd3bf827091440879f9994983d5c2" +dependencies = [ + "block-buffer 0.12.1", + "const-oid 0.10.3", + "crypto-common 0.2.2", + "ctutils", ] [[package]] @@ -892,6 +2932,8 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "1e0e367e4e7da84520dedcac1901e4da967309406d1e51017ae1abfb97adbd38" dependencies = [ "bitflags 2.13.2", + "block2 0.6.2", + "libc", "objc2 0.6.5", ] @@ -936,6 +2978,22 @@ version = "0.1.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d8b14ccef22fc6f5a8f4d7d768562a182c04ce9a3b3157b91390b52ddfdf1a76" +[[package]] +name = "dsa" +version = "0.6.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "48bc224a9084ad760195584ce5abb3c2c34a225fa312a128ad245a6b412b7689" +dependencies = [ + "digest 0.10.7", + "num-bigint-dig", + "num-traits", + "pkcs8 0.10.2", + "rfc6979 0.4.0", + "sha2 0.10.9", + "signature 2.2.0", + "zeroize", +] + [[package]] name = "dunce" version = "1.0.5" @@ -943,20 +3001,108 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "92773504d58c093f6de2459af4af33faa518c13451eb8f2b5698ed3d36e7c813" [[package]] -name = "ecolor" -version = "0.36.2" +name = "eax" +version = "0.5.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0656a7530b9e2841ee7a5f983965bdd9840c32f4012f759cfd44b912cced6b34" +checksum = "9954fabd903b82b9d7a68f65f97dc96dd9ad368e40ccc907a7c19d53e6bfac28" +dependencies = [ + "aead", + "cipher 0.4.4", + "cmac", + "ctr", + "subtle", +] + +[[package]] +name = "ecdsa" +version = "0.16.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ee27f32b5c5292967d2d4a9d7f1e0b0aed2c15daded5a60300e4abb9d8020bca" +dependencies = [ + "der 0.7.10", + "digest 0.10.7", + "elliptic-curve 0.13.8", + "rfc6979 0.4.0", + "signature 2.2.0", + "spki 0.7.3", +] + +[[package]] +name = "ecdsa" +version = "0.17.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c0681a4fc24c767085329728d8dfba959af91228aa4610cca4f8ce317ba46ae0" +dependencies = [ + "der 0.8.3", + "digest 0.11.3", + "elliptic-curve 0.14.3", + "rfc6979 0.6.0", + "signature 3.0.0", + "spki 0.8.1", + "zeroize", +] + +[[package]] +name = "ecolor" +version = "0.37.0" +source = "git+https://github.com/storytold/egui.git?rev=6d518fc799681571963842f95b55a6b68431b15a#6d518fc799681571963842f95b55a6b68431b15a" dependencies = [ "bytemuck", "emath", + "serde", +] + +[[package]] +name = "ed25519" +version = "2.2.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "115531babc129696a58c64a4fef0a8bf9e9698629fb97e9e40767d235cfbcd53" +dependencies = [ + "pkcs8 0.10.2", + "signature 2.2.0", +] + +[[package]] +name = "ed25519" +version = "3.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "29fcf32e6c73d1079f83ab4d782de2d81620346a5f38c6237a86a22f8368980a" +dependencies = [ + "signature 3.0.0", +] + +[[package]] +name = "ed25519-dalek" +version = "2.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "70e796c081cee67dc755e1a36a0a172b897fab85fc3f6bc48307991f64e4eca9" +dependencies = [ + "curve25519-dalek 4.1.3", + "ed25519 2.2.3", + "rand_core 0.6.4", + "serde", + "sha2 0.10.9", + "subtle", + "zeroize", +] + +[[package]] +name = "ed25519-dalek" +version = "3.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6ebaa1a2bf1290ab3bfe5a7b771d050ebffab2711c19a81691c683a5144a25de" +dependencies = [ + "curve25519-dalek 5.0.0", + "ed25519 3.0.0", + "sha2 0.11.1", + "subtle", + "zeroize", ] [[package]] name = "eframe" -version = "0.36.2" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "55ad41fac6e3149abb4866e93df37dbd33baa95db525c3368c944584e95a5dc2" +version = "0.37.0" +source = "git+https://github.com/storytold/egui.git?rev=6d518fc799681571963842f95b55a6b68431b15a#6d518fc799681571963842f95b55a6b68431b15a" dependencies = [ "ahash", "bytemuck", @@ -964,6 +3110,9 @@ dependencies = [ "egui", "egui-wgpu", "egui-winit", + "egui_glow", + "glutin", + "glutin-winit", "image", "js-sys", "log", @@ -972,9 +3121,10 @@ dependencies = [ "objc2-foundation 0.3.2", "parking_lot", "percent-encoding", - "pollster", + "pollster 1.0.1", "profiling", "raw-window-handle", + "send_wrapper", "static_assertions", "wasm-bindgen", "web-sys", @@ -986,9 +3136,8 @@ dependencies = [ [[package]] name = "egui" -version = "0.36.2" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "dc938cc27cd911415e1e4d151bc56ff9df063d8db081374e87aeb805ea74b2ba" +version = "0.37.0" +source = "git+https://github.com/storytold/egui.git?rev=6d518fc799681571963842f95b55a6b68431b15a#6d518fc799681571963842f95b55a6b68431b15a" dependencies = [ "accesskit", "ahash", @@ -999,6 +3148,7 @@ dependencies = [ "log", "nohash-hasher", "profiling", + "serde", "smallvec", "unicode-segmentation", "web-sys", @@ -1006,9 +3156,8 @@ dependencies = [ [[package]] name = "egui-wgpu" -version = "0.36.2" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5cef1f6d1bba40b09a4d0d62cb822b81030922cfbf65c5373398c3a3caafc5bd" +version = "0.37.0" +source = "git+https://github.com/storytold/egui.git?rev=6d518fc799681571963842f95b55a6b68431b15a#6d518fc799681571963842f95b55a6b68431b15a" dependencies = [ "ahash", "bytemuck", @@ -1026,29 +3175,28 @@ dependencies = [ [[package]] name = "egui-winit" -version = "0.36.2" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "98466000559d66ba4db786a30448b01483946add4188e7f10f522a27b4fb89cc" +version = "0.37.0" +source = "git+https://github.com/storytold/egui.git?rev=6d518fc799681571963842f95b55a6b68431b15a#6d518fc799681571963842f95b55a6b68431b15a" dependencies = [ - "arboard", + "block2 0.6.2", "bytemuck", "egui", "log", "objc2 0.6.5", + "objc2-app-kit 0.3.2", "objc2-foundation 0.3.2", "objc2-ui-kit 0.3.2", "profiling", "raw-window-handle", - "smithay-clipboard", "web-time", + "windows-sys 0.61.2", "winit", ] [[package]] name = "egui_extras" -version = "0.36.2" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "05cbdc785020861553f230f23d330ba1fb72613b9d8e0e457f3bdc8ba6db6dcf" +version = "0.37.0" +source = "git+https://github.com/storytold/egui.git?rev=6d518fc799681571963842f95b55a6b68431b15a#6d518fc799681571963842f95b55a6b68431b15a" dependencies = [ "ahash", "egui", @@ -1060,23 +3208,52 @@ dependencies = [ ] [[package]] -name = "egui_kittest" -version = "0.36.2" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5eb3f3effb2726fee23449293e67acbf6cc6ce35525b1722bd5743bb348114d5" +name = "egui_glow" +version = "0.37.0" +source = "git+https://github.com/storytold/egui.git?rev=6d518fc799681571963842f95b55a6b68431b15a#6d518fc799681571963842f95b55a6b68431b15a" dependencies = [ + "bytemuck", + "egui", + "glow", + "log", + "profiling", + "winit", +] + +[[package]] +name = "egui_kittest" +version = "0.37.0" +source = "git+https://github.com/storytold/egui.git?rev=6d518fc799681571963842f95b55a6b68431b15a#6d518fc799681571963842f95b55a6b68431b15a" +dependencies = [ + "dify", "eframe", "egui", "egui-wgpu", "image", "kittest", "log", - "pollster", + "open", + "pollster 1.0.1", "serde", + "tempfile", "toml", "wgpu", ] +[[package]] +name = "egui_system_font_provider" +version = "0.37.0" +source = "git+https://github.com/storytold/egui.git?rev=6d518fc799681571963842f95b55a6b68431b15a#6d518fc799681571963842f95b55a6b68431b15a" +dependencies = [ + "epaint", + "fontique", + "log", + "poll-promise", + "skrifa 0.44.0", + "sys-locale", + "unicode-script", +] + [[package]] name = "either" version = "1.19.0" @@ -1084,14 +3261,71 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0e9c71c2167ca323c882b99918929403426e2373ea17242ff5653e0d5e1058be" [[package]] -name = "emath" -version = "0.36.2" +name = "elliptic-curve" +version = "0.13.8" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "52c8d4141cf0f60fb2f7aefaf352d3ffa5171ef0ab09731c64391801e95e48f1" +checksum = "b5e6043086bf7973472e0c7dff2142ea0b680d30e18d9cc40f267efbf222bd47" +dependencies = [ + "base16ct 0.2.0", + "base64ct", + "crypto-bigint 0.5.5", + "digest 0.10.7", + "ff 0.13.1", + "generic-array", + "group 0.13.0", + "hkdf", + "pem-rfc7468 0.7.0", + "pkcs8 0.10.2", + "rand_core 0.6.4", + "sec1 0.7.3", + "serde_json", + "serdect 0.2.0", + "subtle", + "tap", + "zeroize", +] + +[[package]] +name = "elliptic-curve" +version = "0.14.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "900f37e7e18d74a2347389af6cd69e3a30d5cc9e697f40004865679aa75e9c7c" +dependencies = [ + "base16ct 1.0.0", + "crypto-bigint 0.7.11", + "crypto-common 0.2.2", + "digest 0.11.3", + "ff 0.14.0", + "group 0.14.0", + "hybrid-array", + "pkcs8 0.11.0", + "rand_core 0.10.1", + "sec1 0.8.1", + "subtle", + "zeroize", +] + +[[package]] +name = "emath" +version = "0.37.0" +source = "git+https://github.com/storytold/egui.git?rev=6d518fc799681571963842f95b55a6b68431b15a#6d518fc799681571963842f95b55a6b68431b15a" dependencies = [ "bytemuck", + "serde", ] +[[package]] +name = "embedded-io" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ef1a6892d9eef45c8fa6b9e0086428a2cca8491aca8f787c534a3d6d0bcb3ced" + +[[package]] +name = "embedded-io" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "edd0f118536f44f5ccd48bcb8b111bdc3de888b58c74639dfb034a357d0f206d" + [[package]] name = "encoding_rs" version = "0.8.42" @@ -1107,19 +3341,57 @@ dependencies = [ ] [[package]] -name = "enum-map" -version = "2.7.3" +name = "endi" +version = "1.1.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "6866f3bfdf8207509a033af1a75a7b08abda06bbaaeae6669323fd5a097df2e9" +checksum = "66b7e2430c6dff6a955451e2cfc438f09cea1965a9d6f87f7e3b90decc014099" + +[[package]] +name = "enum-map" +version = "3.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d4532960034c15ba2f55e9eee631040ecc473c32e6c4b200828c759840f13a06" dependencies = [ "enum-map-derive", ] [[package]] name = "enum-map-derive" -version = "0.17.0" +version = "1.0.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "f282cfdfe92516eb26c2af8589c274c7c17681f5ecc03c18255fe741c6aa64eb" +checksum = "7127272f64b3e098f7d81f350d672081b879bff896d219c42370dc858b1af9ff" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.6", +] + +[[package]] +name = "enumflags2" +version = "0.7.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1027f7680c853e056ebcec683615fb6fbbc07dbaa13b4d5d9442b146ded4ecef" +dependencies = [ + "enumflags2_derive", + "serde", +] + +[[package]] +name = "enumflags2_derive" +version = "0.7.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "67c78a4d8fdf9953a5c9d458f9efe940fd97a0cab0941c075a813ac594733827" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "enumn" +version = "0.1.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2f9ed6b3789237c8a0c1c505af1c7eb2c560df6186f01b098c3a1064ea532f38" dependencies = [ "proc-macro2", "quote", @@ -1128,34 +3400,35 @@ dependencies = [ [[package]] name = "epaint" -version = "0.36.2" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "a0ec0308dc23130fc1a7d4623a8534c2ed069c6dc84e258ee4f3de99615aa1a3" +version = "0.37.0" +source = "git+https://github.com/storytold/egui.git?rev=6d518fc799681571963842f95b55a6b68431b15a#6d518fc799681571963842f95b55a6b68431b15a" dependencies = [ "ahash", "bytemuck", "ecolor", "emath", "epaint_default_fonts", - "font-types 0.12.6", + "font-types 0.12.7", "harfrust", "log", "nohash-hasher", "parking_lot", "profiling", "self_cell", + "serde", "skrifa 0.44.0", "smallvec", + "unicode-bidi", "unicode-general-category", + "unicode-properties", "unicode-segmentation", - "vello_cpu 0.1.0", + "vello_cpu 0.2.0", ] [[package]] name = "epaint_default_fonts" -version = "0.36.2" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "773fa9c96dd0dbef887e39d0ed6177f141cce4d68e6041df77570aa3702dfa13" +version = "0.37.0" +source = "git+https://github.com/storytold/egui.git?rev=6d518fc799681571963842f95b55a6b68431b15a#6d518fc799681571963842f95b55a6b68431b15a" [[package]] name = "equivalent" @@ -1173,12 +3446,6 @@ dependencies = [ "windows-sys 0.61.2", ] -[[package]] -name = "error-code" -version = "3.4.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0b5343afd4a8365a643ac588dab4cf234a190c7f6c88c9f6dd6ffe00837661b7" - [[package]] name = "euclid" version = "0.22.14" @@ -1188,6 +3455,47 @@ dependencies = [ "num-traits", ] +[[package]] +name = "event-listener" +version = "5.4.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5a23add41df1562121a9393cb065eab5146a1242410f23a644851e90cfd669d2" +dependencies = [ + "parking", + "pin-project-lite", +] + +[[package]] +name = "event-listener-strategy" +version = "0.5.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8be9f3dfaaffdae2972880079a491a1a8bb7cbed0b8dd7a347f668b4150a3b93" +dependencies = [ + "event-listener", + "pin-project-lite", +] + +[[package]] +name = "exr" +version = "1.74.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cb29d0be702adf92c645d9b2f93472906ba83d400e59f98adb3770ce5c18c2f6" +dependencies = [ + "bit_field", + "half", + "lebe", + "miniz_oxide 0.8.9", + "multiversion", + "smallvec", + "zune-inflate", +] + +[[package]] +name = "extended" +version = "0.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "af9673d8203fcb076b19dfd17e38b3d4ae9f44959416ea532ce72415a6020365" + [[package]] name = "fastrand" version = "2.5.0" @@ -1215,6 +3523,39 @@ version = "0.4.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "b97b65636e5b9ef369943878ac74335ba1c55c1cb6adbf1e2c293c624248d693" +[[package]] +name = "ff" +version = "0.13.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c0b50bfb653653f9ca9095b427bed08ab8d75a137839d9ad64eb11810d5b6393" +dependencies = [ + "bitvec", + "rand_core 0.6.4", + "subtle", +] + +[[package]] +name = "ff" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a1f686ab92a9fb0eaf188f6c6c87b89490baa6fdb0db4544ba4dc47f7942489f" +dependencies = [ + "rand_core 0.10.1", + "subtle", +] + +[[package]] +name = "fiat-crypto" +version = "0.2.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "28dea519a9695b9977216879a3ebfddf92f1c08c05d984f8996aecd6ecdc811d" + +[[package]] +name = "fiat-crypto" +version = "0.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "64cd1e32ddd350061ae6edb1b082d7c54915b5c672c389143b9a63403a109f24" + [[package]] name = "filetime" version = "0.2.29" @@ -1231,6 +3572,17 @@ version = "0.1.14" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "aedcfb3409746eddb02b9e19ebda1c3394f759a152e48ee875a0844d1b955484" +[[package]] +name = "fixed_decimal" +version = "0.7.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2214fb00f669ee96bee5bb29dfb1ddabe058b2bc426817efc79afa03c9bc55ae" +dependencies = [ + "displaydoc", + "smallvec", + "writeable", +] + [[package]] name = "flagset" version = "0.4.7" @@ -1302,11 +3654,55 @@ dependencies = [ [[package]] name = "font-types" -version = "0.12.6" +version = "0.12.7" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "6c92d9081c7ab3bd83ef1eecdfad090f3d966e3ce74106779664114cfe1a6274" +checksum = "835ae9d781464a79026cde387f9cbc650c9a4909d7cf7e658b127e3c35d2f35d" dependencies = [ "bytemuck", + "serde", +] + +[[package]] +name = "fontconfig-parser" +version = "0.5.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bbc773e24e02d4ddd8395fd30dc147524273a83e54e0f312d986ea30de5f5646" +dependencies = [ + "roxmltree 0.20.0", +] + +[[package]] +name = "fontdb" +version = "0.24.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2660c5e9157bf76d2db1294e4a9feba604ef610819a3b591088d0d8392a3290f" +dependencies = [ + "fontconfig-parser", + "log", + "slotmap", + "tinyvec", +] + +[[package]] +name = "fontique" +version = "0.11.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6688bc1294fe7117d788937b6c53480169b29c566954af490830d4c09da9516a" +dependencies = [ + "hashbrown 0.17.1", + "linebender_resource_handle", + "memmap2", + "objc2 0.6.5", + "objc2-core-foundation", + "objc2-core-text", + "objc2-foundation 0.3.2", + "parlance", + "read-fonts 0.41.0", + "roxmltree 0.21.2", + "smallvec", + "windows", + "windows-core", + "yeslogic-fontconfig-sys", ] [[package]] @@ -1345,12 +3741,29 @@ dependencies = [ "percent-encoding", ] +[[package]] +name = "fs-set-times" +version = "0.20.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "94e7099f6313ecacbe1256e8ff9d617b75d1bcb16a6fddef94866d225a01a14a" +dependencies = [ + "io-lifetimes 2.0.4", + "rustix 1.1.5", + "windows-sys 0.59.0", +] + [[package]] name = "fs_extra" version = "1.3.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "42703706b716c37f96a77aea830392ad231f44c9e9a67872fa5548707e11b11c" +[[package]] +name = "funty" +version = "2.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e6d5a32815ae3f33302d95fdcb2ce17862f8c65363dcfd29360480ba1001fc9c" + [[package]] name = "futures-channel" version = "0.3.34" @@ -1373,6 +3786,19 @@ version = "0.3.34" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "53c0fa8157de1303bfffdaa1cc2a673bfffb60102f76b0ef4441659124373fed" +[[package]] +name = "futures-lite" +version = "2.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f78e10609fe0e0b3f4157ffab1876319b5b0db102a2c60dc4626306dc46b44ad" +dependencies = [ + "fastrand", + "futures-core", + "futures-io", + "parking", + "pin-project-lite", +] + [[package]] name = "futures-sink" version = "0.3.34" @@ -1408,6 +3834,7 @@ checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a" dependencies = [ "typenum", "version_check", + "zeroize", ] [[package]] @@ -1420,6 +3847,15 @@ dependencies = [ "windows-link", ] +[[package]] +name = "getopts" +version = "0.2.24" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cfe4fbac503b8d1f88e6676011885f34b7174f46e59956bba534ba83abded4df" +dependencies = [ + "unicode-width", +] + [[package]] name = "getrandom" version = "0.2.17" @@ -1433,6 +3869,20 @@ dependencies = [ "wasm-bindgen", ] +[[package]] +name = "getrandom" +version = "0.3.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd" +dependencies = [ + "cfg-if", + "js-sys", + "libc", + "r-efi 5.3.0", + "wasip2", + "wasm-bindgen", +] + [[package]] name = "getrandom" version = "0.4.3" @@ -1442,11 +3892,21 @@ dependencies = [ "cfg-if", "js-sys", "libc", - "r-efi", + "r-efi 6.0.0", "rand_core 0.10.1", "wasm-bindgen", ] +[[package]] +name = "ghash" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f0d8a4362ccb29cb0b265253fb0a2728f592895ee6854fd9bc13f2ffda266ff1" +dependencies = [ + "opaque-debug", + "polyval", +] + [[package]] name = "gif" version = "0.14.2" @@ -1454,7 +3914,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "ee8cfcc411d9adbbaba82fb72661cc1bcca13e8bba98b364e62b2dba8f960159" dependencies = [ "color_quant", - "weezl", + "weezl 0.1.12", ] [[package]] @@ -1487,18 +3947,19 @@ dependencies = [ [[package]] name = "glifo" -version = "0.2.0" +version = "0.3.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ed4a1bb24121291d27230c1b1b44e07d6a9b28cefdb32fe1581dfb84e14f940a" +checksum = "282a26c1e23de04bdab3e34a21b6f877a479b96737792516b9b8b8f69b6661be" dependencies = [ "bytemuck", "foldhash", "hashbrown 0.17.1", "log", "peniko", + "png 0.18.1", "skrifa 0.44.0", "smallvec", - "vello_common 0.1.0", + "vello_common 0.2.0", ] [[package]] @@ -1513,6 +3974,62 @@ dependencies = [ "web-sys", ] +[[package]] +name = "glutin" +version = "0.32.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "12124de845cacfebedff80e877bb37b5b75c34c5a4c89e47e1cdd67fb6041325" +dependencies = [ + "bitflags 2.13.2", + "cfg_aliases", + "cgl", + "dispatch2", + "glutin_egl_sys", + "glutin_glx_sys", + "glutin_wgl_sys", + "libloading", + "objc2 0.6.5", + "objc2-app-kit 0.3.2", + "objc2-core-foundation", + "objc2-foundation 0.3.2", + "once_cell", + "raw-window-handle", + "windows-sys 0.52.0", + "x11-dl", +] + +[[package]] +name = "glutin-winit" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "85edca7075f8fc728f28cb8fbb111a96c3b89e930574369e3e9c27eb75d3788f" +dependencies = [ + "cfg_aliases", + "glutin", + "raw-window-handle", + "winit", +] + +[[package]] +name = "glutin_egl_sys" +version = "0.7.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4c4680ba6195f424febdc3ba46e7a42a0e58743f2edb115297b86d7f8ecc02d2" +dependencies = [ + "gl_generator", + "windows-sys 0.52.0", +] + +[[package]] +name = "glutin_glx_sys" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8a7bb2938045a88b612499fbcba375a77198e01306f52272e692f8c1f3751185" +dependencies = [ + "gl_generator", + "x11-dl", +] + [[package]] name = "glutin_wgl_sys" version = "0.6.1" @@ -1536,6 +4053,28 @@ dependencies = [ "windows", ] +[[package]] +name = "group" +version = "0.13.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f0f9ef7462f7c099f518d754361858f86d8a07af53ba9af0fe635bbccb151a63" +dependencies = [ + "ff 0.13.1", + "rand_core 0.6.4", + "subtle", +] + +[[package]] +name = "group" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7fd1a1c7a5206c5b7a3f5a0d7ccd3ff85d0c8f5133d62a02680255b0004af5f4" +dependencies = [ + "ff 0.14.0", + "rand_core 0.10.1", + "subtle", +] + [[package]] name = "guillotiere" version = "0.7.0" @@ -1630,10 +4169,8 @@ checksum = "9f4d0e94ddd48749f06bbe4e5389fb9799a0c45bcaf00495042076ef05e3241a" [[package]] name = "hayro-cmap" version = "0.1.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "24d285dc30731c8485de5fa732fbdf2b3affdf01e4da7c2135022ca6fa664bf6" dependencies = [ - "brotli", + "brotli 8.0.4", "hayro-postscript", ] @@ -1674,8 +4211,6 @@ dependencies = [ [[package]] name = "hayro-postscript" version = "0.1.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "885c5ef0654933139a9b9546fc2c69e18d37f38aa2520f079092b1be18f1fcaa" [[package]] name = "hayro-syntax" @@ -1709,6 +4244,15 @@ version = "0.5.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea" +[[package]] +name = "heic-rs" +version = "0.1.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8883c3bfa6b4ff19a40e52a6dc051c5612cbe21bf408fc6d4875e8dfd777cb66" +dependencies = [ + "rayon", +] + [[package]] name = "hermit-abi" version = "0.5.3" @@ -1721,6 +4265,33 @@ version = "0.4.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "7f24254aa9a54b5c858eaee2f5bccdb46aaf0e486a595ed5fd8f86ba55232a70" +[[package]] +name = "hkdf" +version = "0.12.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7b5f8eb2ad728638ea2c7d47a21db23b7b58a72ed6a38256b8a1849f15fbbdf7" +dependencies = [ + "hmac 0.12.1", +] + +[[package]] +name = "hmac" +version = "0.12.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6c49c37c09c17a53d937dfbb742eb3a961d65a994e6bcdcf37e7399d0cc8ab5e" +dependencies = [ + "digest 0.10.7", +] + +[[package]] +name = "hmac" +version = "0.13.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6303bc9732ae41b04cb554b844a762b4115a61bfaa81e3e83050991eeb56863f" +dependencies = [ + "digest 0.11.3", +] + [[package]] name = "http" version = "1.5.0" @@ -1760,6 +4331,17 @@ version = "1.10.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87" +[[package]] +name = "hybrid-array" +version = "0.4.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "27f864f10dfb56725ce5ce5472bc52252c8f93a4ab86327122cebf62c5f59a17" +dependencies = [ + "subtle", + "typenum", + "zeroize", +] + [[package]] name = "hyper" version = "1.12.0" @@ -1822,6 +4404,12 @@ dependencies = [ "windows-registry", ] +[[package]] +name = "hypher" +version = "0.1.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "45f2b4f6b5da34d400d4c112eadcc14512cc5d04307a8eee182586d9bebd7ce6" + [[package]] name = "iana-time-zone" version = "0.1.65" @@ -1846,6 +4434,24 @@ dependencies = [ "cc", ] +[[package]] +name = "icu_collator" +version = "2.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "08984ed58ac439ebf3e13d2cf26b0c46a60afcd21721c1d14087c0b240344dda" +dependencies = [ + "icu_collections", + "icu_locale_core", + "icu_normalizer", + "icu_properties", + "icu_provider", + "serde", + "smallvec", + "utf16_iter", + "utf8_iter", + "zerovec", +] + [[package]] name = "icu_collections" version = "2.3.0" @@ -1854,12 +4460,30 @@ checksum = "fa68d21081c4a05d5a901a1c62add574c77048b6a1c67be3b50ce0b60d4ca513" dependencies = [ "displaydoc", "potential_utf", + "serde", "utf8_iter", "yoke", "zerofrom", "zerovec", ] +[[package]] +name = "icu_decimal" +version = "2.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9eb8f655bba2d0c0459e43a5b0e6cd3cd388109898fb3d85d048165e8b0abd08" +dependencies = [ + "displaydoc", + "fixed_decimal", + "icu_locale_core", + "icu_pattern", + "icu_plurals", + "icu_provider", + "serde", + "writeable", + "zerovec", +] + [[package]] name = "icu_locale_core" version = "2.3.0" @@ -1868,11 +4492,32 @@ checksum = "d56e28588da92eee5c3201a6eff33fabdd49b62269c8938d4ff050ce4d900deb" dependencies = [ "displaydoc", "litemap", + "serde", "tinystr", "writeable", "zerovec", ] +[[package]] +name = "icu_locale_fallback" +version = "2.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "251af8e57c9400e3eb58242fe5b8b1152b2a64fdf4cf632f923c38ccee6f2fa9" +dependencies = [ + "icu_locale_core", + "icu_locale_fallback_data", + "icu_provider", + "potential_utf", + "tinystr", + "zerovec", +] + +[[package]] +name = "icu_locale_fallback_data" +version = "2.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "decf2a22ec8fa68f1a0c1129a3f8583f8f8bc24e8b9ccbe98ead99f62a4dc3a8" + [[package]] name = "icu_normalizer" version = "2.3.0" @@ -1883,7 +4528,11 @@ dependencies = [ "icu_normalizer_data", "icu_properties", "icu_provider", + "serde", "smallvec", + "utf16_iter", + "utf8_iter", + "write16", "zerovec", ] @@ -1893,6 +4542,32 @@ version = "2.3.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "1563da1ed3e0b3bf3d74c9b85917ac9c56464d2f57242270c09c9e752f8021a0" +[[package]] +name = "icu_pattern" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2b3db611446bd92c246b03e4aa0bafa71ddb194af431ddbb42b9d70e4bfce1a0" +dependencies = [ + "displaydoc", + "either", + "serde", + "writeable", + "zerovec", +] + +[[package]] +name = "icu_plurals" +version = "2.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e475e6766ef87b1d3c1f97be6363995b0bfaeddbc789671615df598a97ff0593" +dependencies = [ + "displaydoc", + "fixed_decimal", + "icu_provider", + "serde", + "zerovec", +] + [[package]] name = "icu_properties" version = "2.3.0" @@ -1904,6 +4579,7 @@ dependencies = [ "icu_locale_core", "icu_properties_data", "icu_provider", + "serde", "zerotrie", "zerovec", ] @@ -1922,6 +4598,9 @@ checksum = "d27bbb9d3abbefac45d55f647c9de1d44aafcd1186eb91879afef17c396c3e73" dependencies = [ "displaydoc", "icu_locale_core", + "postcard", + "serde", + "stable_deref_trait", "writeable", "yoke", "zerofrom", @@ -1929,6 +4608,68 @@ dependencies = [ "zerovec", ] +[[package]] +name = "icu_provider_adapters" +version = "2.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "df887bc4f55dbc773c7c45a0c7dfa75be886f7b7812830a71ab7271cc1801820" +dependencies = [ + "icu_locale_fallback", + "icu_provider", +] + +[[package]] +name = "icu_provider_blob" +version = "2.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5916b44fac319d3f58e4d8d805a627df19e27937b582cd99fcde3bb6b7ce1b0e" +dependencies = [ + "icu_provider", + "postcard", + "serde", + "writeable", + "zerotrie", + "zerovec", +] + +[[package]] +name = "icu_segmenter" +version = "2.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "82d07aafccd67af15d02512a6adf5896fbc5ed00f2e99b471d2efa14016db3db" +dependencies = [ + "core_maths", + "icu_collections", + "icu_locale_fallback", + "icu_provider", + "icu_segmenter_data", + "potential_utf", + "smallvec", + "utf8_iter", + "zerovec", +] + +[[package]] +name = "icu_segmenter_data" +version = "2.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ae293c039020f9ec10710af98d29ce6aa2051486638b49c9a6409f3b4a9e98ad" + +[[package]] +name = "idea" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "075557004419d7f2031b8bb7f44bb43e55a83ca7b63076a8fb8fe75753836477" +dependencies = [ + "cipher 0.4.4", +] + +[[package]] +name = "ident_case" +version = "1.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b9e0384b61958566e926dc50660321d12159025e767c18e043daf26b70104c39" + [[package]] name = "idna" version = "1.1.0" @@ -1958,10 +4699,15 @@ checksum = "85ab80394333c02fe689eaf900ab500fbd0c2213da414687ebf995a65d5a6104" dependencies = [ "bytemuck", "byteorder-lite", + "color_quant", + "gif", + "image-webp", "moxcms", "num-traits", "png 0.18.1", "tiff", + "zune-core", + "zune-jpeg", ] [[package]] @@ -1986,6 +4732,12 @@ version = "0.14.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "09e54e57b4c48b40f7aec75635392b12b3421fa26fe8b4332e63138ed278459c" +[[package]] +name = "imagesize" +version = "0.15.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "65b27460c2c92b037f3f94c538ed9a3342f3fdf923606781629ccb35f82d042a" + [[package]] name = "indexmap" version = "2.14.2" @@ -1997,20 +4749,71 @@ dependencies = [ ] [[package]] -name = "intl_pluralrules" -version = "7.0.2" +name = "inout" +version = "0.1.4" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "078ea7b7c29a2b4df841a7f6ac8775ff6074020c6776d48491ce2268e068f972" +checksum = "879f10e63c20629ecabbb64a8010319738c66a5cd0c29b02d63d272b03751d01" dependencies = [ - "unic-langid", + "generic-array", ] +[[package]] +name = "inout" +version = "0.2.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3a580c13f0ffc335ef42dd3f6b1a41b726051c5e1656d9a3aa6fddb3c5dfbbf9" +dependencies = [ + "block-padding 0.4.2", + "hybrid-array", +] + +[[package]] +name = "io-extras" +version = "0.19.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "20fd6de4ccfcc187e38bc21cfa543cb5a302cb86a8b114eb7f0bf0dc9f8ac00f" +dependencies = [ + "io-lifetimes 3.0.1", + "windows-sys 0.59.0", +] + +[[package]] +name = "io-lifetimes" +version = "2.0.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "06432fb54d3be7964ecd3649233cddf80db2832f47fec34c01f65b3d9d774983" + +[[package]] +name = "io-lifetimes" +version = "3.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2f0fb0570afe1fed943c5c3d4102d5358592d8625fda6a0007fdbe65a92fba96" + [[package]] name = "ipnet" version = "2.12.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "791930b43c0d5973160d90a8f3894509f2b273430f5c5c73b668636d0287c5c0" +[[package]] +name = "is-docker" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "928bae27f42bc99b60d9ac7334e3a21d10ad8f1835a4e12ec3ec0464765ed1b3" +dependencies = [ + "once_cell", +] + +[[package]] +name = "is-wsl" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "173609498df190136aa7dea1a91db051746d339e18476eed5ca40521f02d7aa5" +dependencies = [ + "is-docker", + "once_cell", +] + [[package]] name = "itertools" version = "0.15.0" @@ -2094,6 +4897,18 @@ dependencies = [ "libc", ] +[[package]] +name = "jpeg-encoder" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b454d911ac55068f53495488d8ccd0646eaa540c033a28ee15b07838afafb01f" + +[[package]] +name = "jpeg-encoder" +version = "0.7.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a0370574b86f7eca156b9f298392b5e69a23f8c86f3f865add60bbc2e79467a6" + [[package]] name = "js-sys" version = "0.3.106" @@ -2105,6 +4920,215 @@ dependencies = [ "wasm-bindgen", ] +[[package]] +name = "jxl-bitstream" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b480e752277e29eb4054f69546887a9b84656fe78c08f54ba5850ced98a378fe" +dependencies = [ + "tracing", +] + +[[package]] +name = "jxl-coding" +version = "1.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cd972bcd125e776f1eb241ac50e39f956095a1c2770c64736c968f8946bd9a3c" +dependencies = [ + "jxl-bitstream", + "tracing", +] + +[[package]] +name = "jxl-color" +version = "0.11.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f316b1358c1711755b3ee8e8cb5c4a1dad12e796233088a7a513440782de80b2" +dependencies = [ + "jxl-bitstream", + "jxl-coding", + "jxl-grid", + "jxl-image", + "jxl-oxide-common", + "jxl-threadpool", + "tracing", +] + +[[package]] +name = "jxl-frame" +version = "0.13.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2d967c6fd669c7c01060b5022d8835fa82fd46b06ffc98b549f17600a097c2b3" +dependencies = [ + "jxl-bitstream", + "jxl-coding", + "jxl-grid", + "jxl-image", + "jxl-modular", + "jxl-oxide-common", + "jxl-threadpool", + "jxl-vardct", + "tracing", +] + +[[package]] +name = "jxl-grid" +version = "0.6.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "01671307879a033bfa52e6e8784b941aca770b3f3a7d33830b455b6844f793fb" +dependencies = [ + "tracing", +] + +[[package]] +name = "jxl-image" +version = "0.13.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c5f752d62577c702a94dbbce4045caf08cb58639e8a4d56464b40ecf33ffe565" +dependencies = [ + "jxl-bitstream", + "jxl-grid", + "jxl-oxide-common", + "tracing", +] + +[[package]] +name = "jxl-jbr" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e35d032bcec660647828527ff42c6f5776d2fd44b8357f9f6d9ac6dc07218e46" +dependencies = [ + "brotli-decompressor 5.0.3", + "jxl-bitstream", + "jxl-frame", + "jxl-grid", + "jxl-image", + "jxl-modular", + "jxl-oxide-common", + "jxl-threadpool", + "jxl-vardct", + "tracing", +] + +[[package]] +name = "jxl-modular" +version = "0.11.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2a2f045b24c738dd91d482be385512b512721ae08a671bd4b27bf1c47f215235" +dependencies = [ + "jxl-bitstream", + "jxl-coding", + "jxl-grid", + "jxl-oxide-common", + "jxl-threadpool", + "tracing", +] + +[[package]] +name = "jxl-oxide" +version = "0.12.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d36c662923f47586880211f3bc7c0d83fb3a9b410d278c7bde93450748abeef3" +dependencies = [ + "brotli-decompressor 5.0.3", + "jxl-bitstream", + "jxl-color", + "jxl-frame", + "jxl-grid", + "jxl-image", + "jxl-jbr", + "jxl-oxide-common", + "jxl-render", + "jxl-threadpool", + "tracing", +] + +[[package]] +name = "jxl-oxide-common" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b62394c5021b3a9e7e0dbb2d639d555d019090c9946c39f6d3b09d390db4157b" +dependencies = [ + "jxl-bitstream", +] + +[[package]] +name = "jxl-render" +version = "0.12.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d34386bfdb6a19b5a30cc9beb4d475d537422c31ae8c39bb69640fcce3fcaf19" +dependencies = [ + "bytemuck", + "jxl-bitstream", + "jxl-coding", + "jxl-color", + "jxl-frame", + "jxl-grid", + "jxl-image", + "jxl-modular", + "jxl-oxide-common", + "jxl-threadpool", + "jxl-vardct", + "tracing", +] + +[[package]] +name = "jxl-threadpool" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "25f15eb830aa77a7f21148d72e153562a26bfe570139bd4922eab1908dd499d3" +dependencies = [ + "tracing", +] + +[[package]] +name = "jxl-vardct" +version = "0.11.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ce72a18c6d3a47172ab6c479be2bdb56f22066b5d7092663f03b4490820b4511" +dependencies = [ + "jxl-bitstream", + "jxl-coding", + "jxl-grid", + "jxl-modular", + "jxl-oxide-common", + "jxl-threadpool", + "tracing", +] + +[[package]] +name = "k256" +version = "0.13.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f6e3919bbaa2945715f0bb6d3934a173d1e9a59ac23767fbaaef277265a7411b" +dependencies = [ + "cfg-if", + "ecdsa 0.16.9", + "elliptic-curve 0.13.8", + "once_cell", + "sha2 0.10.9", + "signature 2.2.0", +] + +[[package]] +name = "keccak" +version = "0.1.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cb26cec98cce3a3d96cbb7bced3c4b16e3d13f27ec56dbd62cbc8f39cfb9d653" +dependencies = [ + "cpufeatures 0.2.17", +] + +[[package]] +name = "keccak" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d8f198d1db720e4940b5a493201d199d9f24f568f8f746bd13706243a2f71598" +dependencies = [ + "cfg-if", + "cpufeatures 0.3.1", +] + [[package]] name = "keyboard-types" version = "0.8.3" @@ -2134,9 +5158,9 @@ checksum = "e2db585e1d738fc771bf08a151420d3ed193d9d895a36df7f6f8a9456b911ddc" [[package]] name = "kittest" -version = "0.4.0" +version = "0.5.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "90ceaa75eb0036a32b6b9833962eb18137449e9817e2e586006471925b727fd5" +checksum = "0bb81a721ba76aa095b7f45deb180504f786904e56ca4b8e141f66eb89a78b75" dependencies = [ "accesskit", "accesskit_consumer", @@ -2189,9 +5213,25 @@ dependencies = [ "arrayvec", "euclid", "polycool", + "serde", "smallvec", ] +[[package]] +name = "lazy_static" +version = "1.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "20870f649af7073d53e38067b2a84312175d56ea15217e1b15bc83506ec50afb" +dependencies = [ + "spin", +] + +[[package]] +name = "lebe" +version = "0.5.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7a79a3332a6609480d7d0c9eab957bca6b455b91bb84e66d19f5ff66294b85b8" + [[package]] name = "libc" version = "0.2.190" @@ -2232,6 +5272,17 @@ version = "0.1.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d4a5ff6bcca6c4867b1c4fd4ef63e4db7436ef363e0ad7531d1558856bae64f4" +[[package]] +name = "linesweeper" +version = "0.5.0" +dependencies = [ + "arrayvec", + "kurbo 0.13.1", + "polycool", + "rustc-hash 2.1.3", + "smallvec", +] + [[package]] name = "linux-raw-sys" version = "0.4.15" @@ -2249,6 +5300,9 @@ name = "litemap" version = "0.8.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "47d9d19d1d6efa0109d2f65ff4c85cddd50bd572e5a00127ab10987290bcefae" +dependencies = [ + "serde_core", +] [[package]] name = "litrs" @@ -2277,6 +5331,32 @@ version = "0.1.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "4050469837a6ff301cd14c1f8f24f88549e6d548f24f64e2148eb0f72cebc51f" +[[package]] +name = "maybe-owned" +version = "0.3.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4facc753ae494aeb6e3c22f839b158aebd4f9270f55cd3c79906c45476c47ab4" + +[[package]] +name = "md-5" +version = "0.10.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d89e7ee0cfbedfc4da3340218492196241d89eefb6dab27de5df917a6d2e78cf" +dependencies = [ + "cfg-if", + "digest 0.10.7", +] + +[[package]] +name = "md-5" +version = "0.11.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "69b6441f590336821bb897fb28fc622898ccceb1d6cea3fde5ea86b090c4de98" +dependencies = [ + "cfg-if", + "digest 0.11.3", +] + [[package]] name = "memchr" version = "2.8.3" @@ -2285,13 +5365,22 @@ checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98" [[package]] name = "memmap2" -version = "0.9.11" +version = "0.9.12" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "d1219ed1b7f229ee7104d281dd01d6802fe28bb6e95d292942c4daacdeb798c0" +checksum = "6b0ca1155a9ecc25aa12e8313a119f32edf0255fea2f44839c4ac0a12b2ac157" dependencies = [ "libc", ] +[[package]] +name = "memoffset" +version = "0.9.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "488016bfae457b036d996092f6cb448677611ce4449e970ceaf42695203f218a" +dependencies = [ + "autocfg", +] + [[package]] name = "mime" version = "0.3.17" @@ -2367,6 +5456,28 @@ dependencies = [ "windows-sys 0.61.2", ] +[[package]] +name = "multiversion" +version = "0.8.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "eb8a68be21d0755f83bfe47e79b896cc732687cf1903f0e50585e8d6ecc53076" +dependencies = [ + "multiversion-macros", + "target-features", +] + +[[package]] +name = "multiversion-macros" +version = "0.8.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a05e0c3c3e4edaa21d87c645852ed0b0c3663752bcc6ec43353bd6189dce35e1" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", + "target-features", +] + [[package]] name = "multiversion_no_op" version = "1.0.0" @@ -2441,12 +5552,33 @@ dependencies = [ "jni-sys 0.3.1", ] +[[package]] +name = "nix" +version = "0.31.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf20d2fde8ff38632c426f1165ed7436270b44f199fc55284c38276f9db47c3d" +dependencies = [ + "bitflags 2.13.2", + "cfg-if", + "cfg_aliases", + "libc", +] + [[package]] name = "nohash-hasher" version = "0.2.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "2bf50223579dc7cdcfb3bfcacf7069ff68243f8c363f62ffa99cf000a6b9c451" +[[package]] +name = "nom" +version = "8.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "df9761775871bdef83bee530e60050f7e54b1105350d6884eb0fb4f46c2f9405" +dependencies = [ + "memchr", +] + [[package]] name = "nu-ansi-term" version = "0.50.3" @@ -2456,6 +5588,57 @@ dependencies = [ "windows-sys 0.61.2", ] +[[package]] +name = "num-bigint-dig" +version = "0.8.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e661dda6640fad38e827a6d4a310ff4763082116fe217f279885c97f511bb0b7" +dependencies = [ + "lazy_static", + "libm", + "num-integer", + "num-iter", + "num-traits", + "rand 0.8.8", + "serde", + "smallvec", + "zeroize", +] + +[[package]] +name = "num-complex" +version = "0.4.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "73f88a1307638156682bada9d7604135552957b7818057dcef22705b4d509495" +dependencies = [ + "num-traits", +] + +[[package]] +name = "num-conv" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "521739c6d2bac4aa25192232afe6841231376b2b26d4d9fae5ecf8ca5772e441" + +[[package]] +name = "num-integer" +version = "0.1.47" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7ce2d95d4b3734dc35aa2f45e1aa22cd416814592a4f9d9205e11affd5b8e10b" +dependencies = [ + "num-traits", +] + +[[package]] +name = "num-iter" +version = "0.1.46" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c92800bd69a1eac91786bcfe9da64a897eb72911b8dc3095decbd07429e8048b" +dependencies = [ + "num-integer", + "num-traits", +] + [[package]] name = "num-traits" version = "0.2.19" @@ -2536,9 +5719,9 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d49e936b501e5c5bf01fda3a9452ff86dc3ea98ad5f283e1455153142d97518c" dependencies = [ "bitflags 2.13.2", + "block2 0.6.2", "objc2 0.6.5", "objc2-core-foundation", - "objc2-core-graphics", "objc2-foundation 0.3.2", ] @@ -2595,7 +5778,6 @@ version = "0.3.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "e022c9d066895efa1345f8e33e584b9f958da2fd4cd116792e15e07e4720a807" dependencies = [ - "bitflags 2.13.2", "dispatch2", "objc2 0.6.5", "objc2-core-foundation", @@ -2626,6 +5808,16 @@ dependencies = [ "objc2-foundation 0.2.2", ] +[[package]] +name = "objc2-core-text" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0cde0dfb48d25d2b4862161a4d5fcc0e3c24367869ad306b0c9ec0073bfed92d" +dependencies = [ + "bitflags 2.13.2", + "objc2-core-foundation", +] + [[package]] name = "objc2-encode" version = "4.1.0" @@ -2798,6 +5990,18 @@ dependencies = [ "objc2-foundation 0.2.2", ] +[[package]] +name = "ocb3" +version = "0.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c196e0276c471c843dd5777e7543a36a298a4be942a2a688d8111cd43390dedb" +dependencies = [ + "aead", + "cipher 0.4.4", + "ctr", + "subtle", +] + [[package]] name = "once_cell" version = "1.21.4" @@ -2810,6 +6014,22 @@ version = "11.1.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d6790f58c7ff633d8771f42965289203411a5e5c68388703c06e14f24770b41e" +[[package]] +name = "opaque-debug" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c08d65885ee38876c4f86fa503fb49d7b507c2b62552df7c70b2fce627e06381" + +[[package]] +name = "open" +version = "5.4.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8d8c8b8e725ad26404d6896eb2f064294a0a7b4f1d9120210d85544684c4ca95" +dependencies = [ + "is-wsl", + "libc", +] + [[package]] name = "openssl-probe" version = "0.2.1" @@ -2841,6 +6061,101 @@ dependencies = [ "num-traits", ] +[[package]] +name = "ordered-stream" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9aa2b01e1d916879f73a53d01d1d6cee68adbb31d6d9177a8cfce093cced1d50" +dependencies = [ + "futures-core", + "pin-project-lite", +] + +[[package]] +name = "p256" +version = "0.13.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c9863ad85fa8f4460f9c48cb909d38a0d689dba1f6f6988a5e3e0d31071bcd4b" +dependencies = [ + "ecdsa 0.16.9", + "elliptic-curve 0.13.8", + "primeorder 0.13.6", + "sha2 0.10.9", +] + +[[package]] +name = "p256" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d2c9239b2dbc807adbbe147e8cf72ea7450c3a0aabe62cb8e75ff4ec22e1f72a" +dependencies = [ + "ecdsa 0.17.0", + "elliptic-curve 0.14.3", + "primefield", + "primeorder 0.14.0", + "sha2 0.11.1", +] + +[[package]] +name = "p384" +version = "0.13.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fe42f1670a52a47d448f14b6a5c61dd78fce51856e68edaa38f7ae3a46b8d6b6" +dependencies = [ + "ecdsa 0.16.9", + "elliptic-curve 0.13.8", + "primeorder 0.13.6", + "sha2 0.10.9", +] + +[[package]] +name = "p384" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d17b851e6b3e378ab4ecb07fa2ed23f4d15f075735f8fec9fa1e7bdce5f8301f" +dependencies = [ + "ecdsa 0.17.0", + "elliptic-curve 0.14.3", + "fiat-crypto 0.3.0", + "primefield", + "primeorder 0.14.0", + "sha2 0.11.1", +] + +[[package]] +name = "p521" +version = "0.13.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0fc9e2161f1f215afdfce23677034ae137bbd45016a880c2eb3ba8eb95f085b2" +dependencies = [ + "base16ct 0.2.0", + "ecdsa 0.16.9", + "elliptic-curve 0.13.8", + "primeorder 0.13.6", + "rand_core 0.6.4", + "sha2 0.10.9", +] + +[[package]] +name = "p521" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4ad64cc32c2dc466317c12ee5853e61f159f9eab1fe7efade0395dc2e7b43449" +dependencies = [ + "base16ct 1.0.0", + "ecdsa 0.17.0", + "elliptic-curve 0.14.3", + "primefield", + "primeorder 0.14.0", + "sha2 0.11.1", +] + +[[package]] +name = "parking" +version = "2.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f38d5652c16fde515bb1ecef450ab0f6a219d619a7274976324d5e377f7dceba" + [[package]] name = "parking_lot" version = "0.12.5" @@ -2864,6 +6179,33 @@ dependencies = [ "windows-link", ] +[[package]] +name = "parlance" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "73072a9470554c8e794778acece2312661218aaabb635600957d952cf01c716e" + +[[package]] +name = "password-hash" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "346f04948ba92c43e8469c1ee6736c7563d71012b17d40745260fe106aac2166" +dependencies = [ + "base64ct", + "rand_core 0.6.4", + "subtle", +] + +[[package]] +name = "pbkdf2" +version = "0.13.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "112d82ceb8c5bf524d9af484d4e4970c9fd5a0cc15ba14ad93dccd28873b0629" +dependencies = [ + "digest 0.11.3", + "hmac 0.13.0", +] + [[package]] name = "pdf-writer" version = "0.15.0" @@ -2895,6 +6237,15 @@ dependencies = [ "base64ct", ] +[[package]] +name = "pem-rfc7468" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a6305423e0e7738146434843d1694d621cce767262b2a86910beab705e4493d9" +dependencies = [ + "base64ct", +] + [[package]] name = "peniko" version = "0.6.1" @@ -2914,6 +6265,77 @@ version = "2.3.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220" +[[package]] +name = "pgp" +version = "0.21.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ae70f4d9325a391db30d115d6191a7bb67cec856aa0bba131290f0c4e09a532a" +dependencies = [ + "aead", + "aes 0.8.4", + "aes-gcm", + "aes-kw", + "argon2", + "base64 0.22.1", + "bitfields", + "block-padding 0.3.3", + "blowfish", + "buffer-redux", + "byteorder", + "bytes", + "camellia", + "cast5", + "cfb-mode", + "cipher 0.4.4", + "const-oid 0.9.6", + "crc24", + "curve25519-dalek 4.1.3", + "cx448", + "derive_builder", + "derive_more", + "des 0.8.1", + "digest 0.10.7", + "dsa", + "eax", + "ecdsa 0.16.9", + "ed25519-dalek 2.2.0", + "elliptic-curve 0.13.8", + "flate2", + "generic-array", + "getrandom 0.2.17", + "hex", + "hkdf", + "idea", + "k256", + "log", + "md-5 0.10.6", + "memchr", + "nom", + "num-bigint-dig", + "num-traits", + "num_enum", + "ocb3", + "p256 0.13.2", + "p384 0.13.1", + "p521 0.13.3", + "rand 0.8.8", + "replace_with", + "ripemd 0.1.3", + "rsa 0.9.10", + "sha1 0.10.7", + "sha1-checked", + "sha2 0.10.9", + "sha3 0.10.9", + "signature 2.2.0", + "smallvec", + "snafu", + "subtle", + "twofish", + "web-time", + "x25519-dalek", + "zeroize", +] + [[package]] name = "phf" version = "0.13.1" @@ -2998,6 +6420,58 @@ version = "0.2.17" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd" +[[package]] +name = "piper" +version = "0.2.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c835479a4443ded371d6c535cbfd8d31ad92c5d23ae9770a61bc155e4992a3c1" +dependencies = [ + "atomic-waker", + "fastrand", + "futures-io", +] + +[[package]] +name = "pkcs1" +version = "0.7.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c8ffb9f10fa047879315e6625af03c164b16962a5368d724ed16323b68ace47f" +dependencies = [ + "der 0.7.10", + "pkcs8 0.10.2", + "spki 0.7.3", +] + +[[package]] +name = "pkcs1" +version = "0.8.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6250dd7321adbe93d12b750aee0ced159fd13e77f625edcdf1cb6f83cd99f650" +dependencies = [ + "der 0.8.3", + "spki 0.8.1", +] + +[[package]] +name = "pkcs8" +version = "0.10.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f950b2377845cebe5cf8b5165cb3cc1a5e0fa5cfa3e1f7f55707d8fd82e0a7b7" +dependencies = [ + "der 0.7.10", + "spki 0.7.3", +] + +[[package]] +name = "pkcs8" +version = "0.11.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "451913da69c775a56034ea8d9003d27ee8948e12443eae7c038ba100a4f21cb7" +dependencies = [ + "der 0.8.3", + "spki 0.8.1", +] + [[package]] name = "pkg-config" version = "0.3.34" @@ -3010,6 +6484,19 @@ version = "0.2.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "b4596b6d070b27117e987119b4dac604f3c58cfb0b191112e24771b2faeac1a6" +[[package]] +name = "plist" +version = "1.10.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "327a4cb2ad49dc48adfdc9da89e22c64d488b508c67a044d71ba729e4521a285" +dependencies = [ + "base64 0.23.1", + "indexmap", + "quick-xml 0.42.0", + "serde", + "time", +] + [[package]] name = "png" version = "0.17.16" @@ -3036,6 +6523,16 @@ dependencies = [ "miniz_oxide 0.8.9", ] +[[package]] +name = "poll-promise" +version = "0.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5f6a58fecbf9da8965bcdb20ce4fd29788d1acee68ddbb64f0ba1b81bccdb7df" +dependencies = [ + "document-features", + "static_assertions", +] + [[package]] name = "polling" version = "3.11.0" @@ -3050,6 +6547,12 @@ dependencies = [ "windows-sys 0.61.2", ] +[[package]] +name = "pollster" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2f3a9f18d041e6d0e102a0a46750538147e5e8992d3b4873aaafee2520b00ce3" + [[package]] name = "pollster" version = "1.0.1" @@ -3065,6 +6568,18 @@ dependencies = [ "arrayvec", ] +[[package]] +name = "polyval" +version = "0.6.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9d1fe60d06143b2430aa532c94cfe9e29783047f06c0d7fd359a9a51b729fa25" +dependencies = [ + "cfg-if", + "cpufeatures 0.2.17", + "opaque-debug", + "universal-hash", +] + [[package]] name = "portable-atomic" version = "1.15.0" @@ -3080,21 +6595,86 @@ dependencies = [ "portable-atomic", ] +[[package]] +name = "postcard" +version = "1.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6764c3b5dd454e283a30e6dfe78e9b31096d9e32036b5d1eaac7a6119ccb9a24" +dependencies = [ + "cobs", + "embedded-io 0.4.0", + "embedded-io 0.6.1", + "serde", +] + [[package]] name = "potential_utf" version = "0.1.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d83eb9bc6d8e5cf568e7a1101d60ee05e81ed50ea106026f3d18deeb046d7661" dependencies = [ + "serde_core", + "writeable", "zerovec", ] +[[package]] +name = "powerfmt" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4a6394b9e965e73d0a289ee54f589087e2c676aedf60885baf52c76b771e4958" + +[[package]] +name = "ppv-lite86" +version = "0.2.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "85eae3c4ed2f50dcfe72643da4befc30deadb458a9b590d720cde2f2b1e97da9" +dependencies = [ + "zerocopy", +] + [[package]] name = "presser" version = "0.3.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "e8cf8e6a8aa66ce33f63993ffc4ea4271eb5b0530a9002db8455ea6050c77bfa" +[[package]] +name = "primefield" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c555a6e4eb7d4e158fcb028c835c3b8642206ddc279b5c6b202ef9a8bdb592f4" +dependencies = [ + "crypto-bigint 0.7.11", + "crypto-common 0.2.2", + "ff 0.14.0", + "rand_core 0.10.1", + "subtle", + "zeroize", +] + +[[package]] +name = "primeorder" +version = "0.13.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "353e1ca18966c16d9deb1c69278edbc5f194139612772bd9537af60ac231e1e6" +dependencies = [ + "elliptic-curve 0.13.8", +] + +[[package]] +name = "primeorder" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5c9f42978c78a00e3d68f69fc03e57a234debae69da4020a4fb588fcdcd07b06" +dependencies = [ + "elliptic-curve 0.14.3", + "once_cell", + "primefield", + "serdect 0.4.3", + "wnaf", +] + [[package]] name = "proc-macro-crate" version = "3.5.0" @@ -3155,7 +6735,7 @@ dependencies = [ "chacha20", "core_detect", "num-traits", - "rand", + "rand 0.10.3", "rand_xorshift", "regex-syntax", "rusty-fork", @@ -3190,6 +6770,15 @@ dependencies = [ "memchr", ] +[[package]] +name = "quick-xml" +version = "0.42.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "41b1177fdf999d2321d3fb46ff47159d9c1fb9ad66a4879f8c50a0b504615e9b" +dependencies = [ + "memchr", +] + [[package]] name = "quinn" version = "0.11.12" @@ -3220,7 +6809,7 @@ dependencies = [ "bytes", "getrandom 0.4.3", "lru-slab", - "rand", + "rand 0.10.3", "rand_pcg", "ring", "rustc-hash 2.1.3", @@ -3256,12 +6845,35 @@ dependencies = [ "proc-macro2", ] +[[package]] +name = "r-efi" +version = "5.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f" + [[package]] name = "r-efi" version = "6.0.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf" +[[package]] +name = "radium" +version = "0.7.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dc33ff2d4973d518d823d61aa239014831e521c75da58e3df4840d3f47749d09" + +[[package]] +name = "rand" +version = "0.8.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e058c7de0b26af77780c769414d6257830bb240f3c38477dbc2c16e5f54d6d4c" +dependencies = [ + "libc", + "rand_chacha", + "rand_core 0.6.4", +] + [[package]] name = "rand" version = "0.10.3" @@ -3273,11 +6885,24 @@ dependencies = [ "rand_core 0.10.1", ] +[[package]] +name = "rand_chacha" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e6c10a63a0fa32252be49d21e7709d4d4baf8d231c2dbce1eaa8141b9b127d88" +dependencies = [ + "ppv-lite86", + "rand_core 0.6.4", +] + [[package]] name = "rand_core" version = "0.6.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "ec0be4795e2f6a28069bec0b5ff3e2ac9bafc99e6a9a7dc3547996c5c816922c" +dependencies = [ + "getrandom 0.2.17", +] [[package]] name = "rand_core" @@ -3347,6 +6972,15 @@ dependencies = [ "crossbeam-utils", ] +[[package]] +name = "rc2" +version = "0.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ceda21af1ae61033b63175653a1af86cae399d79cd03ca80ba347eb3a6c4a7fe" +dependencies = [ + "cipher 0.5.2", +] + [[package]] name = "read-fonts" version = "0.39.2" @@ -3364,7 +6998,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "046a7d674daf459825b32f5062056d6882db0d2f5a479fbd76ccfc870ac18709" dependencies = [ "bytemuck", - "font-types 0.12.6", + "font-types 0.12.7", "once_cell", ] @@ -3375,10 +7009,23 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d5a0cf4bb6cbce4c29756270d189a5e400ac05e91192161d83a0bcb6e68492e8" dependencies = [ "bytemuck", - "font-types 0.12.6", + "font-types 0.12.7", "once_cell", ] +[[package]] +name = "read-fonts" +version = "0.45.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4edc8db0d972de88e53a085b1f01fb3fbdae7bb0cb7a0ce2b2f8285a412fe3ef" +dependencies = [ + "bytemuck", + "foldhash", + "font-types 0.12.7", + "once_cell", + "yoke", +] + [[package]] name = "redox_syscall" version = "0.4.1" @@ -3416,6 +7063,12 @@ dependencies = [ "thiserror 2.0.21", ] +[[package]] +name = "regex-lite" +version = "0.1.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cab834c73d247e67f4fae452806d17d3c7501756d98c8808d7c9c7aa7d18f973" + [[package]] name = "regex-syntax" version = "0.8.11" @@ -3428,6 +7081,12 @@ version = "1.1.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "19b30a45b0cd0bcca8037f3d0dc3421eaf95327a17cad11964fb8179b4fc4832" +[[package]] +name = "replace_with" +version = "0.1.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "51743d3e274e2b18df81c4dc6caf8a5b8e15dbe799e0dca05c7617380094e884" + [[package]] name = "reqwest" version = "0.13.5" @@ -3480,9 +7139,53 @@ dependencies = [ "log", "pico-args", "rgb", - "svgtypes", + "svgtypes 0.15.3", "tiny-skia", - "usvg", + "usvg 0.45.1", +] + +[[package]] +name = "rfc6979" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8dd2a808d456c4a54e300a23e9f5a67e122c3024119acbfd73e3bf664491cb2" +dependencies = [ + "hmac 0.12.1", + "subtle", +] + +[[package]] +name = "rfc6979" +version = "0.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b4a459cddafb3fe76b31fd8f1108007566c40301feb64dc7b54656eb7388172b" +dependencies = [ + "crypto-bigint 0.7.11", + "hmac 0.13.0", +] + +[[package]] +name = "rfd" +version = "0.17.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "20dafead71c16a34e1ff357ddefc8afc11e7d51d6d2b9fbd07eaa48e3e540220" +dependencies = [ + "block2 0.6.2", + "dispatch2", + "js-sys", + "libc", + "log", + "objc2 0.6.5", + "objc2-app-kit 0.3.2", + "objc2-core-foundation", + "objc2-foundation 0.3.2", + "percent-encoding", + "pollster 0.4.0", + "raw-window-handle", + "wasm-bindgen", + "wasm-bindgen-futures", + "web-sys", + "windows-sys 0.61.2", ] [[package]] @@ -3508,12 +7211,76 @@ dependencies = [ "windows-sys 0.52.0", ] +[[package]] +name = "ripemd" +version = "0.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bd124222d17ad93a644ed9d011a40f4fb64aa54275c08cc216524a9ea82fb09f" +dependencies = [ + "digest 0.10.7", +] + +[[package]] +name = "ripemd" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4dd4211456b4172d7e44261920c25acf07367c4f04bb5f5d54fc21b090d9b159" +dependencies = [ + "digest 0.11.3", +] + [[package]] name = "roxmltree" version = "0.20.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "6c20b6793b5c2fa6553b250154b78d6d0db37e72700ae35fad9387a46f487c97" +[[package]] +name = "roxmltree" +version = "0.21.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9da7f59328b09405b181fee1018925fad50f157afb43c0c0f5c522c256dd5907" +dependencies = [ + "memchr", +] + +[[package]] +name = "rsa" +version = "0.9.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b8573f03f5883dcaebdfcf4725caa1ecb9c15b2ef50c43a07b816e06799bb12d" +dependencies = [ + "const-oid 0.9.6", + "digest 0.10.7", + "num-bigint-dig", + "num-integer", + "num-traits", + "pkcs1 0.7.5", + "pkcs8 0.10.2", + "rand_core 0.6.4", + "signature 2.2.0", + "spki 0.7.3", + "subtle", + "zeroize", +] + +[[package]] +name = "rsa" +version = "0.10.0-rc.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "30b2aa4ba0d89f73d1e332df05be0eeab8840351c36ca5654341dfdb57bb3caf" +dependencies = [ + "const-oid 0.10.3", + "crypto-bigint 0.7.11", + "crypto-primes", + "digest 0.11.3", + "pkcs1 0.8.0", + "pkcs8 0.11.0", + "rand_core 0.10.1", + "signature 3.0.0", + "zeroize", +] + [[package]] name = "rustc-hash" version = "1.1.0" @@ -3562,13 +7329,25 @@ dependencies = [ ] [[package]] -name = "rustls" -version = "0.23.45" +name = "rustix-linux-procfs" +version = "0.1.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0d41d731c7d2f962d1ccc364cec258de3c0e93b38c2fb3ba97ac74513048d634" +checksum = "2fc84bf7e9aa16c4f2c758f27412dc9841341e16aa682d9c7ac308fe3ee12056" +dependencies = [ + "once_cell", + "rustix 1.1.5", +] + +[[package]] +name = "rustls" +version = "0.23.46" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "48e13bd8c0e9365c43cfa5c9e8f9ad49d3c8444926c9aac819e0e4dc503c8fdf" dependencies = [ "aws-lc-rs", + "log", "once_cell", + "ring", "rustls-pki-types", "rustls-webpki", "subtle", @@ -3672,6 +7451,12 @@ dependencies = [ "unicode-script", ] +[[package]] +name = "ruzstd" +version = "0.9.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "69e4ce4a039f42bf25920b95667e4d789e98749ab11bbb8d2c2936f788421bb5" + [[package]] name = "ryu" version = "1.0.23" @@ -3702,18 +7487,41 @@ dependencies = [ "windows-sys 0.61.2", ] -[[package]] -name = "scoped-tls" -version = "1.0.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e1cf6437eb19a8f4a6cc0f7dca544973b0b78843adbfeb3683d1a94a0024a294" - [[package]] name = "scopeguard" version = "1.2.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49" +[[package]] +name = "sec1" +version = "0.7.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d3e97a565f76233a6003f9f5c54be1d9c5bdfa3eccfb189469f11ec4901c47dc" +dependencies = [ + "base16ct 0.2.0", + "der 0.7.10", + "generic-array", + "pkcs8 0.10.2", + "serdect 0.2.0", + "subtle", + "zeroize", +] + +[[package]] +name = "sec1" +version = "0.8.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d56d437c2f19203ce5f7122e507831de96f3d2d4d3be5af44a0b0a09d8a80e4d" +dependencies = [ + "base16ct 1.0.0", + "ctutils", + "der 0.8.3", + "hybrid-array", + "subtle", + "zeroize", +] + [[package]] name = "security-framework" version = "3.7.0" @@ -3748,6 +7556,16 @@ name = "semver" version = "1.0.28" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd" +dependencies = [ + "serde", + "serde_core", +] + +[[package]] +name = "send_wrapper" +version = "0.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cd0b0ec5f1c1ca621c432a25813d8d60c88abe6d3e08a3eb9cf37d97a0fe3d73" [[package]] name = "serde" @@ -3781,9 +7599,9 @@ dependencies = [ [[package]] name = "serde_json" -version = "1.0.151" +version = "1.0.154" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14" +checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6" dependencies = [ "itoa", "memchr", @@ -3803,6 +7621,17 @@ dependencies = [ "serde_json", ] +[[package]] +name = "serde_repr" +version = "0.1.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8d3b1629de253c70a0508c3899572da79ca359fdab27c7920ff00406df418906" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.6", +] + [[package]] name = "serde_spanned" version = "1.1.2" @@ -3824,6 +7653,36 @@ dependencies = [ "serde", ] +[[package]] +name = "serdect" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a84f14a19e9a014bb9f4512488d9829a68e04ecabffb0f9904cd1ace94598177" +dependencies = [ + "base16ct 0.2.0", + "serde", +] + +[[package]] +name = "serdect" +version = "0.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f42f67da2385b51a5f9652db9c93d78aeaf7610bf5ec366080b6de810604af53" +dependencies = [ + "base16ct 0.2.0", + "serde", +] + +[[package]] +name = "serdect" +version = "0.4.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "66cf8fedced2fcf12406bcb34223dffb92eaf34908ede12fed414c82b7f00b3e" +dependencies = [ + "base16ct 1.0.0", + "serde", +] + [[package]] name = "sha1" version = "0.10.7" @@ -3832,7 +7691,29 @@ checksum = "a978451301f4db1d02937a4ab3ccce137717b81826e79b7d49ffe3244a13c3b8" dependencies = [ "cfg-if", "cpufeatures 0.2.17", - "digest", + "digest 0.10.7", +] + +[[package]] +name = "sha1" +version = "0.11.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "aacc4cc499359472b4abe1bf11d0b12e688af9a805fa5e3016f9a386dc2d0214" +dependencies = [ + "cfg-if", + "cpufeatures 0.3.1", + "digest 0.11.3", +] + +[[package]] +name = "sha1-checked" +version = "0.10.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "89f599ac0c323ebb1c6082821a54962b839832b03984598375bff3975b804423" +dependencies = [ + "digest 0.10.7", + "sha1 0.10.7", + "zeroize", ] [[package]] @@ -3843,7 +7724,39 @@ checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283" dependencies = [ "cfg-if", "cpufeatures 0.2.17", - "digest", + "digest 0.10.7", +] + +[[package]] +name = "sha2" +version = "0.11.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "47d7069beb7d6ac7b9acd1039986e73443f24234f41074da099d6f994ac9ad19" +dependencies = [ + "cfg-if", + "cpufeatures 0.3.1", + "digest 0.11.3", +] + +[[package]] +name = "sha3" +version = "0.10.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "77fd7028345d415a4034cf8777cd4f8ab1851274233b45f84e3d955502d93874" +dependencies = [ + "digest 0.10.7", + "keccak 0.1.6", +] + +[[package]] +name = "sha3" +version = "0.12.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bc9bad02c26382724b2d2692c6f179285e4b54eeecd7968f52a50059c3c11759" +dependencies = [ + "digest 0.11.3", + "keccak 0.2.2", + "sponge-cursor", ] [[package]] @@ -3852,15 +7765,36 @@ version = "2.0.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba" +[[package]] +name = "signal-hook-registry" +version = "1.4.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c4db69cba1110affc0e9f7bcd48bbf87b3f4fc7c61fc9155afd4c469eb3d6c1b" +dependencies = [ + "errno", + "libc", +] + [[package]] name = "signature" version = "2.2.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "77549399552de45a898a580c1b41d445bf730df867cc44e6c0233bbc4b8329de" dependencies = [ + "digest 0.10.7", "rand_core 0.6.4", ] +[[package]] +name = "signature" +version = "3.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "28d567dcbaf0049cb8ac2608a76cd95ff9e4412e1899d389ee400918ca7537f5" +dependencies = [ + "digest 0.11.3", + "rand_core 0.10.1", +] + [[package]] name = "sigstore-bundle" version = "0.6.6" @@ -3887,15 +7821,15 @@ checksum = "da90c3d9af638898a5fdc347479b18f950bb0dde11ecf2244f94cd28135da53b" dependencies = [ "aws-lc-rs", "base64 0.22.1", - "const-oid", - "der", - "digest", + "const-oid 0.9.6", + "der 0.7.10", + "digest 0.10.7", "pem", "rand_core 0.10.1", - "sha2", - "signature", + "sha2 0.10.9", + "signature 2.2.0", "sigstore-types", - "spki", + "spki 0.7.3", "thiserror 2.0.21", "tracing", "x509-cert", @@ -3961,10 +7895,10 @@ dependencies = [ "chrono", "cmpv2", "cms", - "const-oid", - "der", + "const-oid 0.9.6", + "der 0.7.10", "hex", - "rand", + "rand 0.10.3", "reqwest", "rustls-pki-types", "rustls-webpki", @@ -4000,7 +7934,7 @@ dependencies = [ "base64 0.22.1", "chrono", "cms", - "const-oid", + "const-oid 0.9.6", "hex", "pem", "rustls-pki-types", @@ -4058,6 +7992,18 @@ version = "1.0.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "33f4fe9184a62d842c9ef383018f3306d8ba224fd9d836f56d7288308847c256" +[[package]] +name = "skera" +version = "0.8.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "531045338e36ad05b9652912a47ba38a935d0eaa0293c3e33d8112cfa414c14b" +dependencies = [ + "hashbrown 0.17.1", + "skrifa 0.48.0", + "thiserror 2.0.21", + "write-fonts 0.54.1", +] + [[package]] name = "skrifa" version = "0.42.1" @@ -4088,6 +8034,16 @@ dependencies = [ "read-fonts 0.44.0", ] +[[package]] +name = "skrifa" +version = "0.48.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a5213b4825bac3587046330052d61bfac7bd3bd0d203c758d7c2ef726fcea034" +dependencies = [ + "bytemuck", + "read-fonts 0.45.1", +] + [[package]] name = "slab" version = "0.4.12" @@ -4108,43 +8064,8 @@ name = "smallvec" version = "1.16.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "f9395f0f0eee849a9b707b2f06bb92a6a422090e2123bb2ef8e87a0e61892a8e" - -[[package]] -name = "smithay-client-toolkit" -version = "0.20.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0512da38f5e2b31201a93524adb8d3136276fa4fe4aafab4e1f727a82b534cc0" dependencies = [ - "bitflags 2.13.2", - "calloop 0.14.5", - "calloop-wayland-source", - "cursor-icon", - "libc", - "log", - "memmap2", - "rustix 1.1.5", - "thiserror 2.0.21", - "wayland-backend", - "wayland-client", - "wayland-csd-frame", - "wayland-cursor", - "wayland-protocols", - "wayland-protocols-experimental", - "wayland-protocols-misc", - "wayland-protocols-wlr", - "wayland-scanner", - "xkeysym", -] - -[[package]] -name = "smithay-clipboard" -version = "0.7.3" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "71704c03f739f7745053bde45fa203a46c58d25bc5c4efba1d9a60e9dba81226" -dependencies = [ - "libc", - "smithay-client-toolkit", - "wayland-backend", + "serde", ] [[package]] @@ -4156,6 +8077,27 @@ dependencies = [ "serde", ] +[[package]] +name = "snafu" +version = "0.9.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e45cb604038abb7b926b679887b3226d8d0f23874b66623625a0454be425a4b7" +dependencies = [ + "snafu-derive", +] + +[[package]] +name = "snafu-derive" +version = "0.9.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "287f59010008f0d7cf5e3b03196d666c1acc46c8d3e9cf34c28a1a7157601e72" +dependencies = [ + "heck", + "proc-macro2", + "quote", + "syn 2.0.119", +] + [[package]] name = "socket2" version = "0.6.5" @@ -4166,6 +8108,12 @@ dependencies = [ "windows-sys 0.61.2", ] +[[package]] +name = "spin" +version = "0.9.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3763264f6b73151db08c50ff20d7d8a0b8796e021cdea7ceedad07b80155fa0e" + [[package]] name = "spirv" version = "0.4.0+sdk-1.4.341.0" @@ -4182,9 +8130,25 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d91ed6c858b01f942cd56b37a94b3e0a1798290327d1236e4d9cf4eaca44d29d" dependencies = [ "base64ct", - "der", + "der 0.7.10", ] +[[package]] +name = "spki" +version = "0.8.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7ef958a98b9d5da290cfc78946e9f3e61e1e62a18db0d92cac0b83cc161491a9" +dependencies = [ + "base64ct", + "der 0.8.3", +] + +[[package]] +name = "sponge-cursor" +version = "0.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3a0219bd7d979d58245a4f41f695e1ac9f8befdffadd7f61f1bae9e39abc6620" + [[package]] name = "stable_deref_trait" version = "1.2.1" @@ -4217,6 +8181,12 @@ dependencies = [ "unicode-properties", ] +[[package]] +name = "strsim" +version = "0.11.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f" + [[package]] name = "strum" version = "0.28.0" @@ -4247,7 +8217,7 @@ dependencies = [ "kurbo 0.13.1", "rustc-hash 2.1.3", "skrifa 0.42.1", - "write-fonts", + "write-fonts 0.48.1", ] [[package]] @@ -4266,6 +8236,213 @@ dependencies = [ "siphasher", ] +[[package]] +name = "svgtypes" +version = "0.16.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9f12b12995e3638c70618c1facb1ce65302f6a6f706b675f07c58a5d7391120e" +dependencies = [ + "kurbo 0.13.1", + "siphasher", +] + +[[package]] +name = "symphonia" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a7edef6a96b696d4e0cab5ee9ebb7ca155ed95f30a6b45bbb8b97d2727f02424" +dependencies = [ + "lazy_static", + "symphonia-bundle-flac", + "symphonia-bundle-mp3", + "symphonia-codec-aac", + "symphonia-codec-adpcm", + "symphonia-codec-alac", + "symphonia-codec-pcm", + "symphonia-codec-vorbis", + "symphonia-core", + "symphonia-format-caf", + "symphonia-format-isomp4", + "symphonia-format-mkv", + "symphonia-format-ogg", + "symphonia-format-riff", + "symphonia-metadata", +] + +[[package]] +name = "symphonia-bundle-flac" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6405d5c34ff6f8f7ca08a4101efe66d21e180f7322ef9359900a0e55698a7892" +dependencies = [ + "log", + "symphonia-common", + "symphonia-core", + "symphonia-metadata", +] + +[[package]] +name = "symphonia-bundle-mp3" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "98ea5ffc8716bff677dfb3b01b420c7b758de901a72b8c330bf2040ab74b4add" +dependencies = [ + "lazy_static", + "log", + "symphonia-core", +] + +[[package]] +name = "symphonia-codec-aac" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f5bf8e39552d34a3c4c98333370e62f48c92456d2e814f273b5c3ad7c4a5f45c" +dependencies = [ + "lazy_static", + "log", + "symphonia-common", + "symphonia-core", +] + +[[package]] +name = "symphonia-codec-adpcm" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "445932ecb0c59362fde9c082dd63a75380650c5077fdb8b80b8cac850442a74c" +dependencies = [ + "log", + "symphonia-core", +] + +[[package]] +name = "symphonia-codec-alac" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "920a78f96f3cf62932d0c497959c0cc2100ef36b03c7ca1417b260f432a482d8" +dependencies = [ + "log", + "symphonia-common", + "symphonia-core", +] + +[[package]] +name = "symphonia-codec-pcm" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e04ba75686acbe43542fdd374571195f0530c0b7785ca25cc6840e9c6c4b6eea" +dependencies = [ + "log", + "symphonia-core", +] + +[[package]] +name = "symphonia-codec-vorbis" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "73d90b4fcf796137cc683c538282804ff9629f8ad9dbfd881fcbba331ac4e986" +dependencies = [ + "log", + "symphonia-common", + "symphonia-core", +] + +[[package]] +name = "symphonia-common" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2acc3fcc18ec9b8cdd48614e259c4cf0d27b71d41e5d9b120b42c5adab12d7c4" +dependencies = [ + "log", + "symphonia-core", + "symphonia-metadata", +] + +[[package]] +name = "symphonia-core" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "01c412864d599d4750d0c3d684d7e093ec05e5309681ef5252cc1096a437f6e0" +dependencies = [ + "bitflags 2.13.2", + "bytemuck", + "lazy_static", + "log", + "num-complex", + "smallvec", +] + +[[package]] +name = "symphonia-format-caf" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ab64327ee1920531c5bf86cf7e9cd1a599d57013ddc30691da62683cefc65191" +dependencies = [ + "log", + "symphonia-common", + "symphonia-core", +] + +[[package]] +name = "symphonia-format-isomp4" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0e681a70e1870d34e02abf1dbc51e4267c3f1827801474e8870be8c689fc4dc3" +dependencies = [ + "log", + "symphonia-common", + "symphonia-core", + "symphonia-metadata", +] + +[[package]] +name = "symphonia-format-mkv" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d015c5c0558864665894b3f4cbd95e10abb01b9c868e751c72670f326a56360e" +dependencies = [ + "lazy_static", + "log", + "symphonia-common", + "symphonia-core", +] + +[[package]] +name = "symphonia-format-ogg" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0b5495e7f7e3c7035328d82b6d6e377eef289bb0c4105bdeb557fc93a833f994" +dependencies = [ + "log", + "symphonia-common", + "symphonia-core", + "symphonia-metadata", +] + +[[package]] +name = "symphonia-format-riff" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1ff70929083a8c1a5f6cd7c904b6071c7914ad04739b510c2f7239dfc9b7dabe" +dependencies = [ + "extended", + "log", + "symphonia-core", + "symphonia-metadata", +] + +[[package]] +name = "symphonia-metadata" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "83713a97705d77bdef7cdbc0768fd6e5a54e4cd7e48d60a806ae85639e2c87c6" +dependencies = [ + "lazy_static", + "log", + "regex-lite", + "smallvec", + "symphonia-core", +] + [[package]] name = "syn" version = "1.0.109" @@ -4351,6 +8528,12 @@ dependencies = [ "libc", ] +[[package]] +name = "tap" +version = "1.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "55937e1799185b12863d447f42597ed69d9928686b8d88a1df17376a097d8369" + [[package]] name = "tar" version = "0.4.46" @@ -4362,6 +8545,12 @@ dependencies = [ "xattr", ] +[[package]] +name = "target-features" +version = "0.1.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c1bbb9f3c5c463a01705937a24fdabc5047929ac764b2d5b9cf681c1f5041ed5" + [[package]] name = "tempfile" version = "3.27.0" @@ -4434,10 +8623,40 @@ dependencies = [ "flate2", "half", "quick-error 2.0.1", - "weezl", + "weezl 0.1.12", "zune-jpeg", ] +[[package]] +name = "time" +version = "0.3.55" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cdb87b95ec50ddfa440816d227a17b2ccbdda963a316a727fda0fc4334f7d134" +dependencies = [ + "deranged", + "num-conv", + "powerfmt", + "serde_core", + "time-core", + "time-macros", +] + +[[package]] +name = "time-core" +version = "0.1.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9e1c906769ad99c88eaa54e728060edef082f8e358ff32030cb7c7d315e81109" + +[[package]] +name = "time-macros" +version = "0.2.32" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7e689342a48d2ea927c87ea50cabf8594854bf940e9310208848d680d668ed85" +dependencies = [ + "num-conv", + "time-core", +] + [[package]] name = "tiny-skia" version = "0.11.4" @@ -4557,10 +8776,12 @@ version = "1.1.8+spec-1.1.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "20489e00e4d8741d6be680764cc12e270655e375a20d1011e844a9c3379e678d" dependencies = [ + "indexmap", "serde_core", "serde_spanned", "toml_datetime", "toml_parser", + "toml_writer", "winnow", ] @@ -4654,7 +8875,6 @@ version = "0.1.44" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100" dependencies = [ - "log", "pin-project-lite", "tracing-attributes", "tracing-core", @@ -4695,6 +8915,15 @@ dependencies = [ "core_maths", ] +[[package]] +name = "twofish" +version = "0.7.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a78e83a30223c757c3947cd144a31014ff04298d8719ae10d03c31c0448c8013" +dependencies = [ + "cipher 0.4.4", +] + [[package]] name = "type-map" version = "0.5.1" @@ -4704,36 +8933,35 @@ dependencies = [ "rustc-hash 2.1.3", ] +[[package]] +name = "typed-path" +version = "0.13.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9ce898823d8cd0f028662d2f349694b1af0a5cc9be83f1d213a00d3147445e1e" + [[package]] name = "typenum" version = "1.20.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20" +[[package]] +name = "uds_windows" +version = "1.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f2f6fb2847f6742cd76af783a2a2c49e9375d0a111c7bef6f71cd9e738c72d6e" +dependencies = [ + "memoffset", + "tempfile", + "windows-sys 0.61.2", +] + [[package]] name = "unarray" version = "0.1.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "eaea85b334db583fe3274d12b4cd1880032beab409c0d774be044d4480ab9a94" -[[package]] -name = "unic-langid" -version = "0.9.6" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "a28ba52c9b05311f4f6e62d5d9d46f094bd6e84cb8df7b3ef952748d752a7d05" -dependencies = [ - "unic-langid-impl", -] - -[[package]] -name = "unic-langid-impl" -version = "0.9.6" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "dce1bf08044d4b7a94028c93786f8566047edc11110595914de93362559bc658" -dependencies = [ - "tinystr", -] - [[package]] name = "unicode-bidi" version = "0.3.18" @@ -4764,6 +8992,12 @@ version = "1.0.26" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d245f478577f809a851594d02313b640fb437e0bb33866753cff937863096954" +[[package]] +name = "unicode-linebreak" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3b09c83c3c29d37506a3e260c08c03743a6bb66a9cd432c6934ab501a190571f" + [[package]] name = "unicode-normalization" version = "0.1.25" @@ -4791,12 +9025,34 @@ version = "1.13.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "c6f5d3c3b1bf09027a88a6bc961fc00497d651009560b5463668dc81b0fa87a8" +[[package]] +name = "unicode-vo" +version = "0.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b1d386ff53b415b7fe27b50bb44679e2cc4660272694b7b6f3326d8480823a94" + [[package]] name = "unicode-width" version = "0.2.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "b4ac048d71ede7ee76d585517add45da530660ef4390e49b098733c6e897f254" +[[package]] +name = "unicode-xid" +version = "0.2.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ebc1c04c71510c7f702b52b7c350734c9ff1295c464a03335b00bb84fc54f853" + +[[package]] +name = "universal-hash" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fc1de2c688dc15305988b563c3854064043356019f97a4b46276fe734c4f07ea" +dependencies = [ + "crypto-common 0.1.7", + "subtle", +] + [[package]] name = "untrusted" version = "0.7.1" @@ -4809,6 +9065,36 @@ version = "0.9.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1" +[[package]] +name = "ureq" +version = "3.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cde93ff05758a36a851a398a772b0b79a82fbe3c186a46f2696baaeaf84c966b" +dependencies = [ + "base64 0.23.1", + "flate2", + "log", + "percent-encoding", + "rustls", + "rustls-pki-types", + "rustls-platform-verifier", + "ureq-proto", + "utf8-zero", + "webpki-roots", +] + +[[package]] +name = "ureq-proto" +version = "0.6.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "841583fc36089d7d59419568ae157f43a5a03a2e5a81ba87c77d1596ef46e922" +dependencies = [ + "base64 0.23.1", + "http", + "httparse", + "log", +] + [[package]] name = "url" version = "2.5.8" @@ -4834,15 +9120,54 @@ dependencies = [ "kurbo 0.11.3", "log", "pico-args", - "roxmltree", + "roxmltree 0.20.0", "simplecss", "siphasher", "strict-num", - "svgtypes", + "svgtypes 0.15.3", "tiny-skia-path 0.11.4", "xmlwriter", ] +[[package]] +name = "usvg" +version = "0.48.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "977d0a4abdef933f424a99fe09f95576e089b90aebc6f016a3bc813762493e91" +dependencies = [ + "base64 0.23.1", + "data-url", + "fontdb", + "harfrust", + "imagesize 0.15.0", + "kurbo 0.13.1", + "log", + "pico-args", + "roxmltree 0.21.2", + "simplecss", + "siphasher", + "skrifa 0.44.0", + "strict-num", + "svgtypes 0.16.2", + "tiny-skia-path 0.12.0", + "unicode-bidi", + "unicode-script", + "unicode-vo", + "xmlwriter", +] + +[[package]] +name = "utf16_iter" +version = "1.0.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c8232dd3cdaed5356e0f716d285e4b40b932ac434100fe9b7e0e8e935b9e6246" + +[[package]] +name = "utf8-zero" +version = "0.8.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b8c0a043c9540bae7c578c88f91dda8bd82e59ae27c21baca69c8b191aaf5a6e" + [[package]] name = "utf8_iter" version = "1.0.4" @@ -4854,6 +9179,11 @@ name = "uuid" version = "1.27.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "97277d36b9c3ace13e58fa6e753f8b0bbbf302a18dd193240d70f9e29681059a" +dependencies = [ + "js-sys", + "serde_core", + "wasm-bindgen", +] [[package]] name = "vello_common" @@ -4891,15 +9221,16 @@ dependencies = [ [[package]] name = "vello_common" -version = "0.1.0" +version = "0.2.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "b2e9aed918117e8152c9eddfd8362d73c465c23f26c44786aa331707b8a64fa2" +checksum = "bbb2141a2bca6e6d598e471fd4d1d7eed8e020aad6a28187edda07f091a325dd" dependencies = [ "bytemuck", "fearless_simd", "guillotiere", "log", "peniko", + "png 0.18.1", "smallvec", "thiserror 2.0.21", ] @@ -4919,14 +9250,25 @@ dependencies = [ [[package]] name = "vello_cpu" -version = "0.1.0" +version = "0.2.0" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ac7349e1f55f6b801c7c277958df4ea53e7f20f21e8014910ad888b2ecda93ea" +checksum = "ace506ca414548966fcf3c283be94eb1cad8254de488791ee698bf438b0890a9" dependencies = [ "bytemuck", - "glifo 0.2.0", + "glifo 0.3.0", "hashbrown 0.17.1", - "vello_common 0.1.0", + "png 0.18.1", + "vello_common 0.2.0", +] + +[[package]] +name = "verifysign" +version = "1.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6acfcc42a8d44f340d001193d97ef56bf33210b51ad760ae8308c97d5241ca51" +dependencies = [ + "core-foundation 0.10.1", + "windows-sys 0.61.2", ] [[package]] @@ -4969,6 +9311,15 @@ version = "0.11.1+wasi-snapshot-preview1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b" +[[package]] +name = "wasip2" +version = "1.0.4+wasi-0.2.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b67efb37e106e55ce722a510d6b5f9c17f083e5fc79afc2badeb12cc313d9487" +dependencies = [ + "wit-bindgen", +] + [[package]] name = "wasm-bindgen" version = "0.2.129" @@ -5073,7 +9424,6 @@ dependencies = [ "cc", "downcast-rs", "rustix 1.1.5", - "scoped-tls", "smallvec", "wayland-sys", ] @@ -5090,79 +9440,6 @@ dependencies = [ "wayland-scanner", ] -[[package]] -name = "wayland-csd-frame" -version = "0.3.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "625c5029dbd43d25e6aa9615e88b829a5cad13b2819c4ae129fdbb7c31ab4c7e" -dependencies = [ - "bitflags 2.13.2", - "cursor-icon", - "wayland-backend", -] - -[[package]] -name = "wayland-cursor" -version = "0.31.14" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "4a52d18780be9b1314328a3de5f930b73d2200112e3849ca6cb11822793fb34d" -dependencies = [ - "rustix 1.1.5", - "wayland-client", - "xcursor", -] - -[[package]] -name = "wayland-protocols" -version = "0.32.13" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "23d0c813de3daa2ed6520af85a3bd49b0e722a3078506899aa9686fea58dc4b6" -dependencies = [ - "bitflags 2.13.2", - "wayland-backend", - "wayland-client", - "wayland-scanner", -] - -[[package]] -name = "wayland-protocols-experimental" -version = "20250721.0.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "40a1f863128dcaaec790d7b4b396cc9b9a7a079e878e18c47e6c2d2c5a8dcbb1" -dependencies = [ - "bitflags 2.13.2", - "wayland-backend", - "wayland-client", - "wayland-protocols", - "wayland-scanner", -] - -[[package]] -name = "wayland-protocols-misc" -version = "0.3.12" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "6e9567599ef23e09b8dad6e429e5738d4509dfc46b3b21f32841a304d16b29c8" -dependencies = [ - "bitflags 2.13.2", - "wayland-backend", - "wayland-client", - "wayland-protocols", - "wayland-scanner", -] - -[[package]] -name = "wayland-protocols-wlr" -version = "0.3.12" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "eb04e52f7836d7c7976c78ca0250d61e33873c34156a2a1fc9474828ec268234" -dependencies = [ - "bitflags 2.13.2", - "wayland-backend", - "wayland-client", - "wayland-protocols", - "wayland-scanner", -] - [[package]] name = "wayland-scanner" version = "0.31.11" @@ -5170,7 +9447,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "338e30461b3a2b67d70eb30a6d89f8e0c93a833e07d2ae89085cd070c4a00ac0" dependencies = [ "proc-macro2", - "quick-xml", + "quick-xml 0.41.0", "quote", ] @@ -5215,12 +9492,27 @@ dependencies = [ "rustls-pki-types", ] +[[package]] +name = "webpki-roots" +version = "1.0.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f5f280bbb2b287bc8e7de7e3852945a0ff50d1bbcb5ed42b6c7a568c546df171" +dependencies = [ + "rustls-pki-types", +] + [[package]] name = "weezl" version = "0.1.12" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "a28ac98ddc8b9274cb41bb4d9d4d5c425b6020c50c46f25559911905610b4a88" +[[package]] +name = "weezl" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d4ca08e5ef825b65b056d9efbd95c8750683f0a6d0466d02e96dc2e4e360f3d2" + [[package]] name = "wgpu" version = "30.0.1" @@ -5531,7 +9823,7 @@ version = "0.52.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d" dependencies = [ - "windows-targets 0.52.6", + "windows-targets", ] [[package]] @@ -5540,16 +9832,7 @@ version = "0.59.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b" dependencies = [ - "windows-targets 0.52.6", -] - -[[package]] -name = "windows-sys" -version = "0.60.2" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "f2f500e4d28234f72040990ec9d39e3a6b950f9f22d3dba18416c35882612bcb" -dependencies = [ - "windows-targets 0.53.5", + "windows-targets", ] [[package]] @@ -5567,31 +9850,14 @@ version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973" dependencies = [ - "windows_aarch64_gnullvm 0.52.6", - "windows_aarch64_msvc 0.52.6", - "windows_i686_gnu 0.52.6", - "windows_i686_gnullvm 0.52.6", - "windows_i686_msvc 0.52.6", - "windows_x86_64_gnu 0.52.6", - "windows_x86_64_gnullvm 0.52.6", - "windows_x86_64_msvc 0.52.6", -] - -[[package]] -name = "windows-targets" -version = "0.53.5" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "4945f9f551b88e0d65f3db0bc25c33b8acea4d9e41163edf90dcd0b19f9069f3" -dependencies = [ - "windows-link", - "windows_aarch64_gnullvm 0.53.1", - "windows_aarch64_msvc 0.53.1", - "windows_i686_gnu 0.53.1", - "windows_i686_gnullvm 0.53.1", - "windows_i686_msvc 0.53.1", - "windows_x86_64_gnu 0.53.1", - "windows_x86_64_gnullvm 0.53.1", - "windows_x86_64_msvc 0.53.1", + "windows_aarch64_gnullvm", + "windows_aarch64_msvc", + "windows_i686_gnu", + "windows_i686_gnullvm", + "windows_i686_msvc", + "windows_x86_64_gnu", + "windows_x86_64_gnullvm", + "windows_x86_64_msvc", ] [[package]] @@ -5609,107 +9875,59 @@ version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3" -[[package]] -name = "windows_aarch64_gnullvm" -version = "0.53.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "a9d8416fa8b42f5c947f8482c43e7d89e73a173cead56d044f6a56104a6d1b53" - [[package]] name = "windows_aarch64_msvc" version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469" -[[package]] -name = "windows_aarch64_msvc" -version = "0.53.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "b9d782e804c2f632e395708e99a94275910eb9100b2114651e04744e9b125006" - [[package]] name = "windows_i686_gnu" version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b" -[[package]] -name = "windows_i686_gnu" -version = "0.53.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "960e6da069d81e09becb0ca57a65220ddff016ff2d6af6a223cf372a506593a3" - [[package]] name = "windows_i686_gnullvm" version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66" -[[package]] -name = "windows_i686_gnullvm" -version = "0.53.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "fa7359d10048f68ab8b09fa71c3daccfb0e9b559aed648a8f95469c27057180c" - [[package]] name = "windows_i686_msvc" version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66" -[[package]] -name = "windows_i686_msvc" -version = "0.53.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "1e7ac75179f18232fe9c285163565a57ef8d3c89254a30685b57d83a38d326c2" - [[package]] name = "windows_x86_64_gnu" version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78" -[[package]] -name = "windows_x86_64_gnu" -version = "0.53.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "9c3842cdd74a865a8066ab39c8a7a473c0778a3f29370b5fd6b4b9aa7df4a499" - [[package]] name = "windows_x86_64_gnullvm" version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d" -[[package]] -name = "windows_x86_64_gnullvm" -version = "0.53.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0ffa179e2d07eee8ad8f57493436566c7cc30ac536a3379fdf008f47f6bb7ae1" - [[package]] name = "windows_x86_64_msvc" version = "0.52.6" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec" -[[package]] -name = "windows_x86_64_msvc" -version = "0.53.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "d6bbff5f0aada427a1e5a6da5f1f98158182f26556f345ac9e04d36d0ebed650" - [[package]] name = "winit" version = "0.30.13" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "a6755fa58a9f8350bd1e472d4c3fcc25f824ec358933bba33306d0b63df5978d" +source = "git+https://github.com/storytold/winit.git?rev=a517b3846ee8457d84ee4975110bfda6797c44dc#a517b3846ee8457d84ee4975110bfda6797c44dc" dependencies = [ "android-activity", "atomic-waker", "bitflags 2.13.2", "block2 0.5.1", - "calloop 0.13.0", + "bytemuck", + "calloop", "cfg_aliases", "concurrent-queue", "core-foundation 0.9.4", @@ -5724,6 +9942,7 @@ dependencies = [ "objc2-foundation 0.2.2", "objc2-ui-kit 0.2.2", "orbclient", + "percent-encoding", "pin-project", "raw-window-handle", "redox_syscall 0.4.1", @@ -5736,6 +9955,8 @@ dependencies = [ "web-sys", "web-time", "windows-sys 0.52.0", + "x11-dl", + "x11rb", "xkbcommon-dl", ] @@ -5751,7 +9972,7 @@ dependencies = [ [[package]] name = "winprint" version = "0.2.1" -source = "git+https://github.com/storytold/winprint.rs?rev=5f80b9baf6b58937c401656634e42d33f00ddf49#5f80b9baf6b58937c401656634e42d33f00ddf49" +source = "git+https://github.com/dotCooCoo/winprint.rs?rev=72951d7455ebcab569fbd9386c513d3d9f53fb02#72951d7455ebcab569fbd9386c513d3d9f53fb02" dependencies = [ "flate2", "fmt-derive", @@ -5766,15 +9987,54 @@ dependencies = [ "windows", "windows-core", "windows-implement", + "windows-numerics", "xml", ] +[[package]] +name = "winreg" +version = "0.55.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cb5a765337c50e9ec252c2069be9bf91c7df47afb103b642ba3a53bf8101be97" +dependencies = [ + "cfg-if", + "windows-sys 0.59.0", +] + [[package]] name = "winsafe" version = "0.0.29" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "9ef0ffc427f045c0cc9ebffd6f4f91153dcd2a1547b5c3c29ee3f541e16e95c6" +[[package]] +name = "winx" +version = "0.36.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3f3fd376f71958b862e7afb20cfe5a22830e1963462f3a17f49d82a6c1d1f42d" +dependencies = [ + "bitflags 2.13.2", + "windows-sys 0.59.0", +] + +[[package]] +name = "wit-bindgen" +version = "0.57.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e" + +[[package]] +name = "wnaf" +version = "0.14.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "795ca18b3fdb5e62bf982199278341ddcf7ebf7d32e25e212ad05d496e95f6fa" +dependencies = [ + "ff 0.14.0", + "group 0.14.0", + "hybrid-array", + "primefield", +] + [[package]] name = "write-fonts" version = "0.48.1" @@ -5788,11 +10048,53 @@ dependencies = [ "read-fonts 0.39.2", ] +[[package]] +name = "write-fonts" +version = "0.54.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "55716cfa7e8bcdb90289e07dfac478ccb2e3ec0f9a604fe682c7a03a7984d705" +dependencies = [ + "font-types 0.12.7", + "indexmap", + "kurbo 0.13.1", + "log", + "read-fonts 0.45.1", +] + +[[package]] +name = "write16" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d1890f4022759daae28ed4fe62859b1236caebfc61ede2f63ed4e695f3f6d936" + [[package]] name = "writeable" version = "0.6.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "3ad82d2a33cdc9674dc7465672f271e096168fcdbe0f799d9e6db8c5892679dc" +dependencies = [ + "either", +] + +[[package]] +name = "wyz" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "05f360fc0b24296329c78fda852a1e9ae82de9cf7b27dae4b7f62f118f77b9ed" +dependencies = [ + "tap", +] + +[[package]] +name = "x11-dl" +version = "2.21.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "38735924fedd5314a6e548792904ed8c6de6636285cb9fec04d5b1db85c1516f" +dependencies = [ + "libc", + "once_cell", + "pkg-config", +] [[package]] name = "x11rb" @@ -5800,7 +10102,11 @@ version = "0.13.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "9993aa5be5a26815fe2c3eacfc1fde061fc1a1f094bf1ad2a18bf9c495dd7414" dependencies = [ + "as-raw-xcb-connection", "gethostname", + "libc", + "libloading", + "once_cell", "rustix 1.1.5", "x11rb-protocol", ] @@ -5811,17 +10117,29 @@ version = "0.13.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "ea6fc2961e4ef194dcbfe56bb845534d0dc8098940c7e5c012a258bfec6701bd" +[[package]] +name = "x25519-dalek" +version = "2.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c7e468321c81fb07fa7f4c636c3972b9100f0346e5b6a9f2bd0603a52f7ed277" +dependencies = [ + "curve25519-dalek 4.1.3", + "rand_core 0.6.4", + "serde", + "zeroize", +] + [[package]] name = "x509-cert" version = "0.2.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "1301e935010a701ae5f8655edc0ad17c44bad3ac5ce8c39185f75453b720ae94" dependencies = [ - "const-oid", - "der", - "sha1", - "signature", - "spki", + "const-oid 0.9.6", + "der 0.7.10", + "sha1 0.10.7", + "signature 2.2.0", + "spki 0.7.3", "tls_codec", ] @@ -5833,7 +10151,7 @@ checksum = "f5ceece934a21607055b7ac5c25adb56a2ff559804b10705dc674d1d838c15e1" dependencies = [ "cmpv2", "cms", - "der", + "der 0.7.10", ] [[package]] @@ -5846,12 +10164,6 @@ dependencies = [ "rustix 1.1.5", ] -[[package]] -name = "xcursor" -version = "0.3.11" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "163b33ed8786455e2fa5d72f554057ce3f3182425434f756cd39c99839d88e23" - [[package]] name = "xkbcommon-dl" version = "0.4.2" @@ -5895,6 +10207,17 @@ version = "0.3.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "9440ea3e5aeabb0ac63af70daf835274065238cdd0cec83418f417eae38bacee" +[[package]] +name = "yeslogic-fontconfig-sys" +version = "6.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1d8b8abf912b9a29ff112e1671c97c33636903d13a69712037190e6805af4f76" +dependencies = [ + "dlib", + "once_cell", + "pkg-config", +] + [[package]] name = "yoke" version = "0.8.3" @@ -5918,6 +10241,76 @@ dependencies = [ "synstructure", ] +[[package]] +name = "zbus" +version = "5.19.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5db4be7c075cb421e4b7ee645541604239bd243ba7c357511f4ff3a74b555907" +dependencies = [ + "async-broadcast", + "async-executor", + "async-io", + "async-lock", + "async-process", + "async-recursion", + "async-task", + "async-trait", + "blocking", + "enumflags2", + "event-listener", + "futures-core", + "futures-lite", + "hex", + "libc", + "ordered-stream", + "rustix 1.1.5", + "serde", + "serde_repr", + "tracing", + "uds_windows", + "uuid", + "windows-sys 0.61.2", + "winnow", + "zbus_macros", + "zbus_names", + "zvariant", +] + +[[package]] +name = "zbus_macros" +version = "5.19.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2990635d09ade6df1868f72f8cac69a876a90981e8bd3c40b1be413f8dc88f40" +dependencies = [ + "proc-macro-crate", + "proc-macro2", + "quote", + "syn 3.0.6", + "zbus_names", + "zvariant", + "zvariant_utils", +] + +[[package]] +name = "zbus_names" +version = "4.3.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "812a12be4ead7a59e18ea8f047d08add0066b73bc62fc1467066a2472ae088dd" +dependencies = [ + "serde", + "winnow", + "zvariant", +] + +[[package]] +name = "zcheapstr" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d1afec51604565183aeb5c54c20aeab286120d4e4460f7f76e3e8bb8c0d99473" +dependencies = [ + "serde", +] + [[package]] name = "zerocopy" version = "0.8.62" @@ -5986,8 +10379,11 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "4ea269c3bd32f0a32c321907a2ae912ba6f4649bb0fc764a15627e99a7095a3f" dependencies = [ "displaydoc", + "litemap", + "serde_core", "yoke", "zerofrom", + "zerovec", ] [[package]] @@ -6013,6 +10409,22 @@ dependencies = [ "syn 3.0.6", ] +[[package]] +name = "zip" +version = "9.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2886b00003a72c4ccee3f42cfc34908d33b2508a74d827dc2a4244706475c704" +dependencies = [ + "crc32fast", + "flate2", + "getrandom 0.4.3", + "indexmap", + "memchr", + "nix", + "typed-path", + "windows-sys 0.61.2", +] + [[package]] name = "zlib-rs" version = "0.6.8" @@ -6031,6 +10443,15 @@ version = "0.5.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d56377fd46368984a170bc5aac5567e52ca5da874caa60bea39fcbca78fb658b" +[[package]] +name = "zune-inflate" +version = "0.2.54" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "73ab332fe2f6680068f3582b16a24f90ad7096d5d39b974d1c0aff0125116f02" +dependencies = [ + "simd-adler32", +] + [[package]] name = "zune-jpeg" version = "0.5.15" @@ -6039,3 +10460,63 @@ checksum = "27bc9d5b815bc103f142aa054f561d9187d191692ec7c2d1e2b4737f8dbd7296" dependencies = [ "zune-core", ] + +[[package]] +name = "zune-jpegxl" +version = "0.5.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cba11ecd07cc23351500e840ae03841b7e4997923ec8e4832ee3ae199ea0b6b4" +dependencies = [ + "zune-core", +] + +[[package]] +name = "zvariant" +version = "5.15.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "80bf6d6cd6a4b601acb64cfb8284cdc643fcfa75ef26ae3c46ec8aa4e8a1fbb7" +dependencies = [ + "endi", + "enumflags2", + "serde", + "winnow", + "zcheapstr", + "zvariant_derive", + "zvariant_utils", +] + +[[package]] +name = "zvariant_derive" +version = "5.15.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ef2672456ba1cb54b5eaec136e63135b3c7495fb938e53b28a62e633496d486d" +dependencies = [ + "proc-macro-crate", + "proc-macro2", + "quote", + "syn 3.0.6", + "zvariant_utils", +] + +[[package]] +name = "zvariant_utils" +version = "4.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bad0294361a320b694a328460dc73add56c306150f5cb6bfafc44446120008a3" +dependencies = [ + "proc-macro2", + "quote", + "serde", + "syn 3.0.6", + "winnow", +] + +[[patch.unused]] +name = "egui_demo_lib" +version = "0.37.0" +source = "git+https://github.com/storytold/egui.git?rev=6d518fc799681571963842f95b55a6b68431b15a#6d518fc799681571963842f95b55a6b68431b15a" + +[[patch.unused]] +name = "egui_inspection" +version = "0.37.0" +source = "git+https://github.com/storytold/egui.git?rev=6d518fc799681571963842f95b55a6b68431b15a#6d518fc799681571963842f95b55a6b68431b15a" diff --git a/Cargo.toml b/Cargo.toml index cf90e022a..23e3e5d46 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,7 +1,7 @@ [workspace] resolver = "3" members = ["crates/*"] -exclude = ["vendor/krilla", "vendor/hayro", "vendor/hayro-interpret", "vendor/hayro-syntax", "vendor/hayro-jbig2"] +exclude = ["vendor/krilla", "vendor/hayro", "vendor/hayro-interpret", "vendor/hayro-syntax", "vendor/hayro-jbig2", "vendor/hayro-cmap", "vendor/hayro-postscript", "vendor/linesweeper"] [workspace.package] version = "0.1.0" @@ -12,33 +12,152 @@ repository = "https://github.com/storytold/craft-libs" [workspace.dependencies] # internal: add each crate here as `craft- = { path = "crates/" }` +craft-platform = { path = "crates/platform" } +craft-aep = { path = "crates/aep" } +craft-affinity = { path = "crates/affinity" } craft-ai-core = { path = "crates/ai-core" } craft-pdf = { path = "crates/pdf", version = "=0.1.0" } +craft-pdn = { path = "crates/pdn" } +craft-plate-test = { path = "crates/plate-test" } krilla = { version = "=0.8.2", default-features = false, features = ["raster-images"] } hayro = { version = "=0.7.1", default-features = false } hayro-interpret = { version = "=0.7.0", default-features = false, features = ["embed-fonts", "embed-cmaps"] } hayro-syntax = { version = "=0.7.2", default-features = false, features = ["std"] } bytemuck = "1" +kurbo = "0.13" thiserror = "2" +craft-aaf = { path = "crates/aaf" } craft-atomic = { path = "crates/atomic" } +craft-captions = { path = "crates/captions" } +craft-cfb = { path = "crates/cfb" } +craft-codepage = { path = "crates/codepage" } craft-cms = { path = "crates/cms" } +craft-crs = { path = "crates/crs" } +craft-crw = { path = "crates/crw" } +craft-csv = { path = "crates/csv" } +craft-dav = { path = "crates/dav" } +craft-dialogs = { path = "crates/dialogs" } +craft-doc-binary = { path = "crates/doc-binary" } +craft-docx = { path = "crates/docx" } +craft-dxf = { path = "crates/dxf" } +craft-drawingml = { path = "crates/drawingml" } +craft-eps = { path = "crates/eps" } +craft-doc = { path = "crates/doc" } craft-docpath = { path = "crates/docpath" } +craft-dpx = { path = "crates/dpx" } +craft-ecproj-format = { path = "crates/ecproj-format" } +craft-figma-rest = { path = "crates/figma-rest" } +craft-exr = { path = "crates/exr" } +craft-flags = { path = "crates/flags" } +craft-font-catalog = { path = "crates/font-catalog" } +craft-font-manager = { path = "crates/font-manager" } +craft-font-store = { path = "crates/font-store" } +craft-gainmap = { path = "crates/gainmap" } +craft-flow = { path = "crates/flow" } +craft-gcode = { path = "crates/gcode" } +craft-gif = { path = "crates/gif" } +craft-hdr = { path = "crates/hdr" } +craft-mesh = { path = "crates/mesh" } +craft-html = { path = "crates/html" } +craft-heif = { path = "crates/heif" } +craft-fig = { path = "crates/fig" } +craft-fonts-build = { path = "crates/fonts-build" } craft-i18n = { path = "crates/i18n" } +craft-idml = { path = "crates/idml" } +craft-jmap = { path = "crates/jmap" } +craft-ical = { path = "crates/ical" } +craft-jpeg = { path = "crates/jpeg" } +craft-kiwi = { path = "crates/kiwi" } +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" } +craft-media = { path = "crates/media", default-features = false } +craft-media-testkit = { path = "crates/media-testkit" } +craft-midi = { path = "crates/midi" } +craft-sf2 = { path = "crates/sf2" } +craft-mime = { path = "crates/mime" } +craft-odf = { path = "crates/odf" } +craft-ods = { path = "crates/ods" } +craft-prc = { path = "crates/prc" } +craft-lottie = { path = "crates/lottie" } +craft-menu = { path = "crates/menu" } +craft-metafile = { path = "crates/metafile" } +craft-offcrypto = { path = "crates/offcrypto" } +craft-opc = { path = "crates/opc" } +craft-openpgp = { path = "crates/openpgp" } +craft-ora = { path = "crates/ora" } +craft-pptx = { path = "crates/pptx" } +craft-penpot = { path = "crates/penpot" } +craft-pcraft-format = { path = "crates/pcraft-format" } +craft-pkcs7 = { path = "crates/pkcs7" } +craft-plotter = { path = "crates/plotter" } +craft-prepress = { path = "crates/prepress" } craft-print = { path = "crates/print" } +craft-proof = { path = "crates/proof" } +craft-raster-codecs = { path = "crates/raster-codecs" } +craft-psd = { path = "crates/psd" } +craft-pst = { path = "crates/pst" } craft-quit = { path = "crates/quit" } +craft-rtf = { path = "crates/rtf" } +craft-raw = { path = "crates/raw" } +craft-sheet = { path = "crates/sheet" } +craft-sketch = { path = "crates/sketch" } craft-settings = { path = "crates/settings" } craft-time = { path = "crates/time" } +craft-silhouette-studio = { path = "crates/silhouette-studio" } +craft-svg = { path = "crates/svg" } +craft-svg-paths = { path = "crates/svg-paths" } +craft-stream-codecs = { path = "crates/stream-codecs" } +craft-text = { path = "crates/text" } +craft-tga = { path = "crates/tga" } +craft-timeline = { path = "crates/timeline" } +craft-tiff = { path = "crates/tiff" } +craft-metadata = { path = "crates/metadata" } craft-ui = { path = "crates/ui" } -egui = { version = "0.36", default-features = false } +craft-update = { path = "crates/update" } +craft-vcard = { path = "crates/vcard" } +craft-vectorcraft-format = { path = "crates/vectorcraft-format" } +craft-vectordrawable = { path = "crates/vectordrawable" } +craft-xls = { path = "crates/xls" } +craft-wordmodel = { path = "crates/wordmodel" } +craft-xlsx = { path = "crates/xlsx" } +craft-xcf = { path = "crates/xcf" } +craft-xml = { path = "crates/xml" } +craft-zip = { path = "crates/zip" } +craft-y4m = { path = "crates/y4m" } +craft-epub = { path = "crates/epub" } +craft-ews = { path = "crates/ews" } +craft-video = { path = "crates/video" } +craft-web-api = { path = "crates/web-api" } +craft-window = { path = "crates/window" } +craft-web-host = { path = "crates/web-host" } +craft-webp = { path = "crates/webp" } +egui = { version = "0.37", default-features = false } +md5 = { package = "md-5", version = "0.10", default-features = false } rayon = "1" serde = { version = "1", features = ["derive"] } serde_json = "1" +proptest = "1" +# Character sets of the WHATWG Encoding Standard (craft-mime). (Apache-2.0 OR MIT) AND BSD-3-Clause. +encoding_rs = "0.8" +# All date/time conversion goes through chrono (no hand-rolled calendar code beyond the 400-year range extension; AGENTS.md). +chrono = { version = "0.4.45", default-features = false, features = ["std"] } [workspace.lints.rust] unsafe_code = "forbid" +unused_workspace_dependencies = "allow" unexpected_cfgs = { level = "warn", check-cfg = ["cfg(craft_pdf_unicode_fixtures)"] } [workspace.lints.clippy] +cognitive_complexity = "deny" +too_many_arguments = "deny" +unused_workspace_dependencies = "allow" +wildcard_imports = "deny" dbg_macro = "warn" todo = "warn" @@ -49,3 +168,37 @@ hayro = { path = "vendor/hayro" } hayro-interpret = { path = "vendor/hayro-interpret" } hayro-syntax = { path = "vendor/hayro-syntax" } hayro-jbig2 = { path = "vendor/hayro-jbig2" } +hayro-cmap = { path = "vendor/hayro-cmap" } +hayro-postscript = { path = "vendor/hayro-postscript" } +linesweeper = { path = "vendor/linesweeper" } +ecolor = { git = "https://github.com/storytold/egui.git", rev = "6d518fc799681571963842f95b55a6b68431b15a" } +emath = { git = "https://github.com/storytold/egui.git", rev = "6d518fc799681571963842f95b55a6b68431b15a" } +epaint = { git = "https://github.com/storytold/egui.git", rev = "6d518fc799681571963842f95b55a6b68431b15a" } +epaint_default_fonts = { git = "https://github.com/storytold/egui.git", rev = "6d518fc799681571963842f95b55a6b68431b15a" } +egui = { git = "https://github.com/storytold/egui.git", rev = "6d518fc799681571963842f95b55a6b68431b15a" } +egui-winit = { git = "https://github.com/storytold/egui.git", rev = "6d518fc799681571963842f95b55a6b68431b15a" } +egui-wgpu = { git = "https://github.com/storytold/egui.git", rev = "6d518fc799681571963842f95b55a6b68431b15a" } +egui_glow = { git = "https://github.com/storytold/egui.git", rev = "6d518fc799681571963842f95b55a6b68431b15a" } +egui_extras = { git = "https://github.com/storytold/egui.git", rev = "6d518fc799681571963842f95b55a6b68431b15a" } +egui_kittest = { git = "https://github.com/storytold/egui.git", rev = "6d518fc799681571963842f95b55a6b68431b15a" } +egui_system_font_provider = { git = "https://github.com/storytold/egui.git", rev = "6d518fc799681571963842f95b55a6b68431b15a" } +eframe = { git = "https://github.com/storytold/egui.git", rev = "6d518fc799681571963842f95b55a6b68431b15a" } +egui_demo_lib = { git = "https://github.com/storytold/egui.git", rev = "6d518fc799681571963842f95b55a6b68431b15a" } +egui_inspection = { git = "https://github.com/storytold/egui.git", rev = "6d518fc799681571963842f95b55a6b68431b15a" } +winit = { git = "https://github.com/storytold/winit.git", rev = "a517b3846ee8457d84ee4975110bfda6797c44dc" } + +# symphonia's FLAC decoder restores LPC samples as `residual + (prediction as i32)`. In a valid +# 32-bit stream the prediction can leave the i32 range while the sum does not, so a debug build +# panics where a release build wraps to the right sample. Apps that decode 32-bit FLAC through +# craft-audio's `decode` need the same override in their own workspace. +[profile.dev.package.symphonia-bundle-flac] +overflow-checks = false + +# Codec hot loops: the oracle and conformance tests of a debug build take minutes below opt-level 3. +[profile.dev.package.craft-video] +opt-level = 3 + +# The object-stream parser follows nesting 384 levels deep: unoptimised, its frames overflow the +# 2 MiB stack of a test thread. The apps this reader came from build their crates at this level. +[profile.dev.package.craft-affinity] +opt-level = 1 diff --git a/NOTICE b/NOTICE index 9467671f3..c6583cc70 100644 --- a/NOTICE +++ b/NOTICE @@ -19,11 +19,93 @@ crates/cms/tests/data/FOGRA39.txt: FOGRA39 characterisation data, distributed un the data are distributed unmodified and Fogra is identified as the source. The designation FOGRAxx may be used solely to identify the respective reference data. Such use does not imply certification, approval or endorsement by Fogra." +crates/text/assets/hyphen/en-us.dic: public domain, derived from the Moby Hyphenator II list by + Grady Ward (Project Gutenberg eBook #3204). +crates/proof/data/en-words.dic: public domain, the words of the Moby Hyphenator II list by Grady + Ward (Project Gutenberg eBook #3204), without its break points. +crates/proof/data/en-extra.txt: MIT OR Apache-2.0, WordCraft contributors' own list of modern + English words (a copy of craft-i18n's language-data/en-us/en-extra.txt). +craft-proof Language data, embedded at build time from craft-i18n's language-data/ when + CRAFT_I18N_DIR is set (CRAFT_PROOF_EMBED picks the locales; by default English and the German, + Polish, Portuguese, Italian and Russian data). Each file keeps its licence header; the + licences are listed in craft-i18n's ATTRIBUTION.md, and a pattern file's notice ships with any + application that embeds it. The Portuguese hyphenation patterns (language-data/pt/ + hyphenation.pat, hyph-utf8 hyph-pt 1.4) are under the BSD 3-clause licence: + Copyright (C) 1987, 1994, 1996, 2015 Pedro J. de Rezende, 1996, 2015 J. Joao Dias Almeida, + 2024 Leonardo Araujo and Aline Benevides. + Redistribution and use in source and binary forms, with or without modification, are + permitted provided that the following conditions are met: + * Redistributions of source code must retain the above copyright notice, this list of + conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above copyright notice, this list of + conditions and the following disclaimer in the documentation and/or other materials + provided with the distribution. + * Neither the name of the University of Campinas, of the University of Minho nor the names of + its contributors may be used to endorse or promote products derived from this software + without specific prior written permission. + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND + FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL PEDRO J. DE REZENDE OR J.JOAO + DIAS ALMEIDA BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR + OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. +crates/text/assets/hyphen/en-us.pat: CC0-1.0, trained from en-us.dic by DesignCraft's trainer. +Hyphenation patterns for other languages, embedded through the hypher crate only when the + matching craft-text feature is enabled (none are by default). They come from hyph-utf8, + https://github.com/hyphenation/tex-hyphen, as packaged in https://github.com/typst/hypher + (patterns/). Each file is under the license stated in its header: LPPL, MIT, BSD-3-Clause, the + Unlicense, a notice permitting any use, or a choice of licenses that includes one of these. An + application that enables a language ships that file's copyright and license notice. The + exception is Slovak (hyph-sk.tex, Copyright (C) 1992 Jana Chlebíková), under the GNU General + Public License, version 2 or later (SPDX: GPL-2.0-or-later). craft-text asks for it through the + feature "slovak-gpl", which "all-languages" does not include; an application that enables it + ships GPL-licensed data. Cargo unifies features, so another dependency that enables hypher's + "slovak" feature (hypher's default features do) embeds the same data; a build that must exclude + it checks its dependency graph. The Spanish patterns (feature "spanish") are hyph-es.tex 5.0. + Copyright (C) 1993, 1997 Javier Bezos, 2001-2019 Javier Bezos, CervanTeX. MIT License: + Permission is hereby granted, free of charge, to any person obtaining a copy of this software + and associated documentation files (the "Software"), to deal in the Software without + restriction, including without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following conditions: The above copyright notice + and this permission notice shall be included in all copies or substantial portions of the + Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, + INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE + AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, + DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +- Word-break dictionaries and LSTM models for Thai, Lao, Khmer and Burmese, embedded through the + icu_segmenter_data crate only when craft-text's "thai", "lao", "khmer" or "burmese" feature is + enabled (none are by default). From ICU4X, https://github.com/unicode-org/icu4x. + Copyright (c) 2020-2024 Unicode, Inc. Unicode License v3 (SPDX: Unicode-3.0); portions adapted + from ICU4C, (c) 1995-2016 International Business Machines Corporation and others. An + application that enables one of these features ships the Unicode License v3 copyright and + permission notice, https://www.unicode.org/license.txt. The optional PDF writer bundles four CC0 ICC profiles by Clinton Ingram. See ATTRIBUTION.md for per-file sources and hashes. Source provenance +crates/raw (craft-raw) is moved from LightCraft, with behaviour ported from two other readers: +- LightCraft, crates/raw (src/lib.rs, dng.rs, dngwrite.rs, tiffraw.rs, unpack.rs, ljpeg.rs, jxl.rs, + opcodes.rs, profile.rs, gaintable.rs, semantic.rs, preview.rs, vendor/crw.rs, vendor/hasselblad.rs, + vendor.rs (shared level helpers), vendor/mrw.rs, vendor/erf.rs, vendor/mef.rs, vendor/kodak.rs, vendor/pef.rs, + vendor/srw.rs, vendor/cr2.rs, vendor/cr2/sraw.rs, vendor/nef.rs, vendor/nefc.rs, vendor/nef_lens.rs, docs/nikon-lens-corrections.md, vendor/rw2.rs, vendor/raf.rs, vendor/rafc.rs, vendor/raf_lens.rs, docs/raf-compression.md, docs/raf-corpus.sha256, vendor/orf.rs, docs/orf-compression.md, vendor/arw.rs, vendor/arw6.rs, vendor/arw6_curve.rs, vendor/arw6_testenc.rs, vendor/arw_lens.rs, vendor/arw_lens_rm6.rs, vendor/sr2.rs, llvc.rs, lens_metadata.rs, docs/arw6-compression.md, docs/sony-lens-corrections.md, docs/sony-ilce7rm6-lens-corrections.md, vendor/cr3.rs, vendor/crx.rs, vendor/crx_wavelet.rs, sparse.rs, saturation.rs (the CR3 white extension), docs/cr3.md, docs/raw/, kelvin_presets.rs (the preset ordering), tests/it/vendor_robust.rs and their tests) and crates/meta/src/mrw.rs (the MRW block container), + revision 5ff567a4a2e067bef1b6bce152c11e7f727ccbaf. + https://github.com/storytold/lightcraft + Copyright (c) 2026 ArtCraft Team and the LightCraft contributors. +- PhotoCraft, crates/raw/src/dng.rs, hasselblad.rs and tests/it/dng.rs (default-crop defaults, + white-level fallbacks, the 8-bit rule for lossy JPEG, Hasselblad's per-site black levels), + revision c1b22bdaae2a1359ba3d164eca4d4b0c7378b547. + https://github.com/storytold/photocraft + Copyright (c) 2026 ArtCraft Team and the PhotoCraft contributors. +- FilmCraft, crates/dng/src/lib.rs (the CinemaDNG frame tags and time code), revision + 4bec22bd03bd1d995c9cf72e02a284f96d3d72cd. + https://github.com/storytold/filmcraft + Copyright (c) 2026 ArtCraft Team and the FilmCraft contributors. The SVG icon preparation in crates/ui is adapted from: - PhotoCraft, crates/ui-egui/src/icons.rs, revision e7a83ca342cdff568254f85f442b9cc8afb08066. https://github.com/storytold/photocraft @@ -53,6 +135,13 @@ The transactional panel model and drop-zone semantics in crates/ui/src/docking d FilmCraft/EffectCraft split, tab and accordion layouts and VectorCraft floating groups listed above. The generic transaction validation, optional renderer and workspace-location helpers are implemented here without dependencies on application engines or native window helpers. +The hyphenation code, data and generator in crates/text (src/hyphen/, assets/hyphen/ and +examples/hyphgen.rs) are adapted from: +- DesignCraft, crates/compose/src/hyphen/, crates/compose/examples/hyphgen.rs and + assets/hyphenation/, revision e161878e4c7744fa06f9a2eede8103cb4c296355 (above). +- WordCraft, crates/proof/src/hyphen.rs, revision e4b7d155f15a7784197ba34eeea0b54490d70eb2. + https://github.com/storytold/wordcraft + Copyright (c) 2026 ArtCraft Team and the WordCraft contributors. All sources listed above are licensed MIT OR Apache-2.0. No icon artwork is copied here. The PDF spooler in crates/print is extracted from: @@ -75,6 +164,31 @@ PrintTicket and its driver-paper preference): Copyright (c) 2026 ArtCraft Team and the PdfCraft contributors. Licensed MIT OR Apache-2.0. +The menu layout and native-menu driver in crates/menu are extracted from: +- PhotoCraft, crates/ui-egui/src/native_menu.rs, revision 6f85054288a564f9fbbccb99268ffdb34e581584. + https://github.com/storytold/photocraft + Copyright (c) 2026 ArtCraft Team and the PhotoCraft contributors. + Licensed MIT OR Apache-2.0. PhotoCraft's menus, translations and command handling are not copied. +The macOS backend in crates/menu/src/mac.rs is adapted from: +- PhotoCraft, apps/photocraft/src/mac_menu.rs, revision 6f85054288a564f9fbbccb99268ffdb34e581584. + https://github.com/storytold/photocraft + Copyright (c) 2026 ArtCraft Team and the PhotoCraft contributors. +- VectorCraft, apps/vectorcraft/src/mac_menu.rs, revision 0d0ea352df99044589a7ce0efc7004f7a5b6b7c0 + (closing an open menu on a click or Escape, and its tests, in crates/menu/src/driver.rs). + https://github.com/storytold/vectorcraft + Copyright (c) 2026 ArtCraft Team and the VectorCraft contributors. + Both licensed MIT OR Apache-2.0. +The egui menu bar in crates/menu/src/bar (its menu navigation, scrolling, submenu hover +intent, keyboard access and mnemonics, and their tests) is ported from: +- PhotoCraft, crates/ui-egui/src/menu_nav.rs and menu_nav_tests.rs, menu_keys.rs and + menu_keys_tests.rs, and the menu bar in crates/ui-egui/src/menus.rs, revision + c36e46c3873ee39f299cc50a3dcd28494c78366d. + https://github.com/storytold/photocraft + Copyright (c) 2026 ArtCraft Team and the PhotoCraft contributors, among them aiongg, artman67, + BFlat, Brandon Thomas, Brennan Stehling, Daniel Lošák, David Mann, Fabio Lissi, FredApps, + Higgs32584, itsF4LCON, jason4short, Korg1ch, MarekSpodBiedry and Nigel Ihza Firdausy. + Licensed MIT OR Apache-2.0. PhotoCraft's menus, theme and Help search are not copied. + The colour management module in crates/cms is extracted from: - PhotoCraft, crates/cms, revision b3222ee8e7e6bcb4799c37f904c595f20f9baf5e. https://github.com/storytold/photocraft @@ -91,18 +205,74 @@ The optional writer embeds Compact ICC Profiles by Clinton Ingram See licenses/pdf-writer/LICENSE-ICC.txt and ATTRIBUTION.md for sources and hashes. The writer adds no font files. Its four existing ICC profiles are retained under vendor/krilla/icc. -Krilla is vendored with a native unwind-cleanup patch; see vendor/krilla/README.craft.md +Krilla is vendored with the local patches in vendor/krilla/patches; see vendor/krilla/README.craft.md and vendor/krilla/SOURCE.json. Its upstream MIT/Apache-2.0 licences and CC0 profiles are unchanged. Optional PDF reader -Hayro 0.7.1, hayro-interpret 0.7.0, hayro-syntax 0.7.2 and hayro-jbig2 0.3.0 -(https://github.com/LaurenzV/hayro), MIT OR Apache-2.0, retain their upstream licence files. -These patched sources are transferred from PdfCraft revision -7437bde378f43856eada40af25b983812e615e8a (https://github.com/storytold/pdfcraft). +Hayro 0.7.1, hayro-interpret 0.7.0, hayro-syntax 0.7.2, hayro-jbig2 0.3.0, hayro-cmap 0.1.0 +and hayro-postscript 0.1.0 (https://github.com/LaurenzV/hayro), MIT OR Apache-2.0, retain their +upstream licence files. The first five are patched sources transferred from PdfCraft +(https://github.com/storytold/pdfcraft): hayro-cmap from revision +a2ec27b4775f53c40cad3456936d9406611e3a8d, the others from revision +ec0a965074f376a5bf610435948e4e5184bf3299. hayro-postscript is the crates.io 0.1.0 package +(upstream revision a2354aebaf86f5ab13e5fd6b6b0521306488bf9d) with one local patch. See vendor/README.craft-reader.md and each crate's SOURCE.json for provenance and local changes. +The hayro-interpret plate mode (separations, overprint and output-intent simulation) is ported +from PdfCraft pull request #2770 by Guillem Hermida, commit +6fcf2a4aca29e943e28cb69017ff8f87d00656c6 (https://github.com/storytold/pdfcraft/pull/2770), +MIT OR Apache-2.0; crates/pdf/tests/plates.rs and tests/support/synthetic_icc.rs adapt its tests. +Knockout transparency groups in hayro-interpret and hayro are ported from PdfCraft pull request +#2974 by mtlcl410, commit bae69819594a6385a027fec1f67e6b3c36c259b4 +(https://github.com/storytold/pdfcraft/pull/2974), MIT OR Apache-2.0; +crates/pdf/tests/knockout.rs adapts its test. The reader retains the existing Foxit/PDFium standard-14 font assets (BSD-3-Clause), Compact ICC Profiles by Clinton Ingram (CC0-1.0), and dependency CMaps (BSD-3-Clause). Their licences and per-file hashes are retained in vendor/hayro-interpret/assets, -licenses/pdf-backend and ATTRIBUTION.md. These are existing reader dependency assets; +vendor/hayro-cmap/assets, licenses/pdf-backend and ATTRIBUTION.md. These are existing reader dependency assets; 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 +and the files left out. + +Platform lifecycle source provenance + +The optional crates/platform services adapt the preserved local platform candidate +9b135779a1e7136438a217c18afe1693ea23f1ab (dialog outcomes and browser resource ownership), +and current application implementations: +- PdfCraft crates/platform/src/desktop_theme.rs, a8cd797a917b1007544575c7280c9a0ce6a17e8f. +- CADCraft apps/cadcraft/src/desktop_theme.rs, 0cc66ad3066e71f2c3d4cacb7de905e79ba1c95b. +- ArtCraft Launcher apps/artcraft-launcher/src/system_theme.rs, f1676dfb41c226b5be490721f486ee6427419d80. +- Earlier PhotoCraft, FilmCraft and EffectCraft appearance services at revisions + 0c72d95425dece90ef9a1cceb49e3315c96e22d5, 794a25fc9ed2e3f6fab51a254625bc9b99a88015 + and 1b4d47f34f2b1c1b4a89f4b7348889def8fd648b respectively. +Sources: https://github.com/storytold/pdfcraft, https://github.com/storytold/cadcraft, +https://github.com/storytold/craft-launcher, https://github.com/storytold/photocraft, +https://github.com/storytold/filmcraft, https://github.com/storytold/effectcraft. +Copyright (c) 2026 ArtCraft Team and the respective application and craft-libs contributors. +All adapted source is licensed MIT OR Apache-2.0. + +The Canon CRW decoder in crates/crw (src/lib.rs, src/tables.rs, src/tests.rs, tests/) and its +derivation record (crates/crw/clean-room/) come from: +- LightCraft, crates/raw/src/vendor/crw.rs, crates/raw/src/vendor/crw_tables.rs, + crates/raw/tests/crw_oracle.rs, crates/raw/tests/it/vendor_robust.rs and clean-room/crw/, + https://github.com/storytold/lightcraft/pull/3021, revision 6ca439b5155820d2befeacd81ec0c6a80b2bd3bc + (decoder ported at 70c755e42a65661401142819278d51b0c5977f7f; the record is identical at both). + https://github.com/storytold/lightcraft + Copyright (c) 2026 ArtCraft Team and the LightCraft contributors. +Its white-level plateau estimate (saturation_plateau) is LightCraft's vendor::white_from_data at the +same revision. The CRW compression was derived clean-room from CC0 sample files and the +maintainer's own photographs by black-box comparison with a reference decoder's command-line +output; no raw-decoder source was consulted (crates/crw/clean-room/sources.md). + +crates/audio/src/alac/ (the ALAC decoder and encoder) is ported from Apple's ALAC reference +implementation, https://github.com/macosforge/alac at c38887c5c5e64a4b31108733bd79ca9b2496d987 +(codec/), Copyright (c) 2011 Apple Inc., licensed under the Apache License, Version 2.0 +(LICENSE-APACHE). The files are modified: translated to Rust, with bounds checks on hostile input, +wrapping integer arithmetic, the unrolled predictor and per-width matrix routines folded into one, +and the average bit rate filled in. Those files are Apache-2.0 only. diff --git a/README.md b/README.md index 2bfd050a9..c56ce2bf0 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ Craft App Libraries =================== +Scanned by SonarCloud + This repo contains libraries used by the various Craft Apps. It's a Rust monorepo workspace, and the libraries can be included by any Craft Apps that need them. In the future this may grow to include non-Rust library code. @@ -15,37 +17,365 @@ A Cargo workspace (edition 2024, resolver 3). Each library is a crate under `cra (`license.workspace = true`, and so on) and `[lints] workspace = true`. Register each crate in `[workspace.dependencies]` in the root `Cargo.toml`. -Apps depend on a crate by git: +## Use a released version + +The first coordinated release is **[v0.1.0](https://github.com/storytold/craft-libs/releases/tag/v0.1.0)**. +It gives consumers a fixed baseline while development continues on `main`. All five crates +share this version. They require Rust 1.95 or later; the UI integrations use egui 0.36. + +Add only the crates you need, using the same tag for every craft-libs dependency: ```toml -craft- = { git = "https://github.com/storytold/craft-libs", rev = "" } +[dependencies] +craft-ui = { git = "https://github.com/storytold/craft-libs", tag = "v0.1.0" } +craft-settings = { git = "https://github.com/storytold/craft-libs", tag = "v0.1.0" } +# Optional, for egui close handling and the macOS application menu: +craft-quit = { git = "https://github.com/storytold/craft-libs", tag = "v0.1.0", features = ["menu"] } ``` +`craft-atomic` and `craft-print` use the same dependency syntax. Enable `craft-ui`'s +`serde` feature if you need to serialize its docking layout. These are Git releases; +crates.io publication is deferred. + +Release tags are never moved or reused. For a commit pin, resolve the tag with +`git ls-remote https://github.com/storytold/craft-libs 'refs/tags/v0.1.0^{}'` and replace +`tag = "v0.1.0"` with `rev = ""` on every craft-libs dependency. +Use either `tag` or `rev`, not both. An existing commit pin keeps working; switching to this +release may require adapting to changes since that commit. + +Commit your application's `Cargo.lock` and build with `cargo build --locked` for reproducible +Rust dependency resolution. A Git pin fixes craft-libs source, not every transitive dependency. +A library's own lockfile does not constrain its downstream consumers. Upgrade deliberately: +read the release notes, update all craft-libs pins together, refresh the lockfile with +`cargo check`, and run your application's tests and affected workflows before committing. + +See the [release notes](CHANGELOG.md) for included functionality and known limits, and the +[versioning policy](docs/versioning.md) for compatibility guarantees and release checks. + ## Libraries +- [`craft-platform`](crates/platform/README.md): optional native dialog lifecycle, Linux/BSD desktop appearance observation and browser download ownership; application policy stays in the apps. + +- [`craft-aep`](crates/aep/README.md): After Effects projects: the `.aep` (RIFX) and `.aepx` + container as a lossless chunk tree that writes back byte for byte, and a typed, read-only view + of compositions, layers, properties, keyframes, effects, masks, shapes, text and footage. + Clean room, from EffectCraft. Mapping onto an app's document stays in the app. - [`craft-ai-core`](crates/ai-core/README.md): the data model and contract for AI in the Craft Apps (connections, models, tools, requests, jobs, consent, history, route spec). Pure, no I/O, wasm-safe. Contract in [docs/ai-shared-layer.md](docs/ai-shared-layer.md). - [`craft-pdf`](crates/pdf/README.md): independently optional PDF parsing, interpretation, rasterization and guarded authoring. Apps retain layout, fonts, editing and export policy; writer-only consumers do not enable the shared reader. +- [`craft-pdn`](crates/pdn/README.md): Paint.NET documents (`.pdn`, PDN3), read: the layer list, blend modes and chunked gzip pixel blocks, with a data-only MS-NRBF (.NET binary serialization) reader. From PhotoCraft. +- [`craft-aaf`](crates/aaf/README.md): clean-room AAF (Edit Protocol, structured storage) and OMF Interchange 2.0 (Bento) readers and writers over one mob-style composition model with exact times, clip gain, markers, nested compositions and embedded PCM essence. From FilmCraft. +- [`craft-assuan`](crates/assuan/README.md): the Assuan protocol and gpg-agent's operations (key lookup, signing a digest, decrypting a session key) over any `Read + Write` stream, with a bounded canonical S-expression reader. No sockets; everything the agent sends is capped. +- [`craft-affinity`](crates/affinity/README.md): bounded reader for native Affinity documents (`.af`, `.afdesign`, `.afphoto`, `.afpub`): archive, object stream and a neutral document model with layers, artboards, vectors, text, tables, images and masks. Read only; mapping onto an app's document stays in the app. - [`craft-atomic`](crates/atomic/README.md): Crash-safe atomic file writing and replacement with same-directory staging, directory fsync, Apple `F_FULLFSYNC` fallback, transient lock backoff, and fault injection for the Craft suite. +- [`craft-captions`](crates/captions/README.md): caption and subtitle files behind one neutral + model (cues with exact tick times): SubRip, WebVTT, Scenarist SCC, MacCaption MCC, EBU STL and + TTML / IMSC1 / DFXP readers and writers, and CEA-608 / CEA-708 byte-pair coding. Carved from + FilmCraft. +- [`craft-cfb`](crates/cfb/README.md): clean-room Compound File Binary ([MS-CFB], OLE structured + storage) reader and writer: the container of legacy Office files, Outlook messages, encrypted + OOXML packages and AAF. Bounded on hostile input; what the streams hold stays with each format. +- [`craft-dav`](crates/dav/README.md): WebDAV multistatus documents (RFC 4918) with the CalDAV and + CardDAV namespaces, from MailCraft: read fail-closed into a bounded `craft-xml` tree with fixed + prefixes, and the successful properties of each response. No I/O. - [`craft-cms`](crates/cms/README.md): pure-Rust ICC v2/v4 colour management: profile parsing and writing, transforms, rendering intents, black point compensation, soft proofing, gamut checks, 3D LUTs and built-in profiles (sRGB, Display P3, synthetic coated CMYK and others). +- [`craft-crs`](crates/crs/README.md): Adobe Camera Raw settings (the `crs:` namespace of an XMP packet or `.xmp` sidecar, read through craft-metadata): the settings by name, numbers, tone curve points, local corrections and the crop, read and written. From PhotoCraft. +- [`craft-codepage`](crates/codepage/README.md): legacy 8-bit code pages, one table each: the single-byte Windows pages, Mac OS Roman and fifteen DOS pages, keyed by Windows code page number, with the RTF/Word font charsets. craft-rtf, craft-dxf and craft-mime decode through it. +- [`craft-crw`](crates/crw/README.md): clean-room Canon CRW (CIFF) raw decoder, from LightCraft: + the heap container, the entropy coding derived by black-box analysis (frozen code tables), sensor + black and white levels and as-shot white balance. The complete derivation record (plan, sources + log, scripts, verification) is in `crates/crw/clean-room/`. Colour stays in each app. +- [`craft-csv`](crates/csv/README.md): delimited text (CSV, TSV) and SYLK: encoding detection (UTF-8, UTF-16, Windows-1252 or Windows-1256), delimiter sniffing, a record parser with a cap on fields per record, field quoting for writers, and a SYLK (`.slk`) reader with R1C1 formulas rewritten to A1. +- [`craft-dialogs`](crates/dialogs/README.md): native file and message dialogs that never block + the event loop: queued requests shown at the end of the frame and answered on a later frame, + free-standing Open and Folder panels and Save sheets on macOS, case-insensitive filters. What + to do with the answer stays in each app. +- [`craft-doc`](crates/doc/README.md): reads PhotoCraft `.pcraft`, VectorCraft `.vectorcraft` + and EffectCraft `.ecproj` documents without the apps: the kind and version, the previews and + PDF they carry, and their pages and layers. Rendering and editing stay in each app. +- [`craft-doc-binary`](crates/doc-binary/README.md): the Word 97-2003 binary format (`.doc`, [MS-DOC]) read into + `craft-wordmodel`, with XOR, RC4 and RC4 CryptoAPI password protection. WordCraft's reader, on `craft-cfb`. - [`craft-docpath`](crates/docpath/src/lib.rs): decides whether a path or `file:` URL stored in a document may be opened. Paths stored in documents are followed only when they are local or on the document's own network share; other network paths, device paths and non-file URLs are refused. +- [`craft-dpx`](crates/dpx/src/lib.rs): DPX (SMPTE ST 268) and Kodak Cineon frames, from PhotoCraft, + FilmCraft and EffectCraft: header fields and code values at 8, 10, 12 and 16 bits in both byte + orders, filled and packed, RGB, RGBA, ABGR, luma and Y'CbCr descriptors, and a writer for both + formats. Bounded on hostile input. Colour conversion and orientation stay in each app. +- [`craft-drawingml`](crates/drawingml/README.md): the DrawingML that PPTX, DOCX and XLSX share: + EMU units and `a:xfrm`, colours with theme slots and colour transforms, preset shape outlines + (`a:prstGeom`), custom geometry with guide formulas (`a:custGeom`) and preset text warps + (`a:prstTxWarp`). From DeckCraft. Takes `craft-xml` trees; packages stay with each format. +- [`craft-eps`](crates/eps/README.md): Encapsulated PostScript files as a container: the binary + preview header (read and write), the DSC header comments and bounding boxes (also `(atend)`), + the EPSI preview bitmap, ASCII85 data, and telling EPS, PostScript and Illustrator files + (PostScript- or PDF-based) apart. No PostScript interpreter. +- [`craft-docx`](crates/docx/README.md): DOCX (WordprocessingML) read and written on `craft-wordmodel`, with + Word XML (Flat OPC) and Word 2003 XML, password-protected packages and Restrict Editing hashes. + WordCraft's DOCX crate on `craft-opc`, `craft-xml` and `craft-offcrypto`. +- [`craft-dxf`](crates/dxf/src/lib.rs): DXF tag reader and writer, from CADCraft: ASCII and + binary DXF as (group code, value) tags, split into sections and entities, with pre-2007 code + pages and version detection, and written back; and `model`, the drawing above the tags (header + variables, tables, blocks, layouts, entities) and its writer (R12 to 2018), merged from CADCraft's and VectorCraft's readers. Bounded + on hostile input. Mapping the model onto a document stays in each app. +- [`craft-ecproj-format`](crates/ecproj-format/README.md): the envelope of EffectCraft `.ecproj` + project files: `savedBy`, the schema version and its check, and the file object with the + project and its saved view as type parameters. The project model stays in EffectCraft. +- [`craft-fig`](crates/fig/README.md): clean-room reader and writer for the `.fig` container + (Figma Design and FigJam local copies): the ZIP archive, the chunked canvas with its kiwi schema + and message, images, and the vector network and geometry blobs. Bounded on hostile input. + Carved from FigCraft. +- [`craft-epub`](crates/epub/README.md): EPUB packages: the OCF ZIP container, the package document (metadata, manifest, spine) and the navigation document, written as EPUB 3 (reflowable and fixed layout) and read (EPUB 2 and 3) with bounded entry sizes. Content documents are the caller's. +- [`craft-figma-rest`](crates/figma-rest/README.md): typed model of the Figma REST API file JSON + (document tree, paints, effects, text styles, layout, component metadata), read and written with + serde without losing fields it has no name for. The neutral model the `.fig` and `.sketch` + readers map onto, with their extensions documented. +- [`craft-ews`](crates/ews/README.md): the SOAP layer of Exchange Web Services, from MailCraft, without + sockets: the request envelope and an escaping element builder, and the answer envelope, faults + and response messages with their codes, read with `craft-xml`. The operations and everything + over HTTP stay in each app. +- [`craft-exr`](crates/exr/src/lib.rs): OpenEXR pieces shared by PhotoCraft and EffectCraft: layer + and channel names, the channels that make a colour picture, and Cryptomatte IDs, metadata keys, + manifests and rank channels. The optional `decode` feature adds bounded part listing, flat + decoding (scan lines, tiles, every compression of the `exr` crate) and writing. +- [`craft-flags`](crates/flags/README.md): Feature flags shared by the Craft apps and the ArtCraft Launcher: one per-user `ArtCraft/flags.toml`, a `CRAFT_FLAGS` override, every flag off by default (`AI-MCP`, `AI-MODELS`). +- [`craft-flow`](crates/flow/README.md): the flow model every text format maps to (paragraphs with a kind, lists and formatted spans; tables; pictures, fields, notes, equations), converted to and from a craft-wordmodel `Document`. +- [`craft-font-catalog`](crates/font-catalog/README.md): the installed fonts on every platform + (font folders, fontconfig and Flatpak host folders, CoreText, DirectWrite, the font store), + lookup by family, style, localized, legacy, full and PostScript names, family loads shared + between threads, and rescans when fonts are installed or removed. +- [`craft-font-manager`](crates/font-manager/README.md): Craft Font Manager as a library: search + and filters over the Google Fonts index, installed fonts by family, the font store interface, + and (`egui` feature) `FontsPanel`, the whole interface as one panel for the launcher's Fonts tab + and the standalone app. +- [`craft-font-store`](crates/font-store/README.md): the suite's font store: the pinned Google + Fonts and Noto indexes plus indexes the user adds (never curated), exact lookup by family and + style or PostScript name, and installs from each source's URLs (jsDelivr, then raw GitHub) + checked by size, sha256 and parsing, with the licence, a manifest, and removal. Off until the + user turns downloading on; agents can't. +- [`craft-fonts-build`](crates/fonts-build/README.md): embeds the optional craft-fonts faces + from an app's `build.rs` (`CRAFT_FONTS_DIR`, `CRAFT_FONTS_REQUIRED`, script filters) as a table + of `EmbeddedFace`s. No dependencies; the app picks the faces. +- [`craft-gainmap`](crates/gainmap/README.md): HDR gain maps, from LightCraft: the ISO 21496-1 + metadata and Adobe `hdrgm` XMP (read and write), measuring a gain map from SDR and HDR + renditions, applying one, and Apple's legacy maps. Encoding and the container stay in each app. +- [`craft-gcode`](crates/gcode/src/lib.rs): Grbl-style G-code writer: polylines in + millimetres to `G0`/`G1` moves with laser power and feed, for cutting lasers and plotters, as a + commented file or as bare lines for streaming. Its `grbl` module has the real-time command bytes + and the status and acknowledgement parsers. +- [`craft-gif`](crates/gif/src/lib.rs): GIF block reader, from PhotoCraft: the logical screen, + every frame's position, delay, disposal and transparent colour, the loop count and the first + frame's colour table, without decompressing pixels. Tells an animation from a still and whether + a file can hold the picture it declares before a decoder runs. +- [`craft-hdr`](crates/hdr/src/lib.rs): Radiance HDR (RGBE) picture reader, from FilmCraft: flat, + old and new run-length scan lines and all eight axis orders, to linear float RGB. Scan lines are + validated before the picture is allocated. +- [`craft-heif`](crates/heif/README.md): optional HEIF/HEIC still-image decoder, from LightCraft: + heic-rs reads the container and HEVC pictures, and this crate converts to 16-bit RGB to match + libheif (VUI range and matrix, chroma upsampling, `imir`, ICC on grid tiles). Also orientation, + alpha, EXIF/XMP and thumbnails. It never panics, and apps put it behind a non-default feature. +- [`craft-html`](crates/html/README.md): the bottom layer of reading and writing HTML: a tolerant tokenizer (text, start tags, end tags; elements to drop or to read as raw text are options), character references with the legacy names browsers accept without `;`, escaping, and the character set a page declares. With the `flow` feature, HTML documents read into and written from the craft-flow model. - [`craft-i18n`](crates/i18n/README.md): translations over the embedded craft-i18n catalogs: lookup with fallback (`pt-br` → `pt` → English), plurals, language names, the system locale and a pseudo locale. The catalogs stay a fully optional build input; apps keep `tl!` and their language setting. +- [`craft-raw`](crates/raw/README.md): camera raw files, the file-format layer, from LightCraft with + what PhotoCraft's and FilmCraft's readers added: container parsing and decompression to a neutral + raw image (samples, CFA, black and white levels, active area, crop, orientation, colour tags, + opcode lists, embedded previews), one Cargo feature per format. DNG reading and writing, + Hasselblad 3FR/FFF, Minolta MRW, Epson ERF, Mamiya MEF, Kodak DCS, Pentax PEF, Samsung SRW, Canon CR2, Nikon NEF/NRW, Panasonic RW2, Fujifilm RAF, Olympus ORF (uncompressed), Sony ARW, Canon CR3 and Canon CRW (through + `craft-crw`) so far; demosaicing and everything after stay with the develop + pipeline. +- [`craft-tga`](crates/tga/src/lib.rs): Truevision Targa, from FilmCraft (reader) and PhotoCraft + (writer): true-colour, grayscale and colour-mapped pictures, raw or run-length encoded, any + origin, to RGBA8, and a run-length writer whose packets end with their scan line. Bounded on + hostile input. +- [`craft-idml`](crates/idml/README.md): IDML (InDesign Markup Language) packages: the ZIP container read with bounded part sizes and lenient part names, `designmap.xml` with its includes in place, the `` form on craft-xml elements, value codecs and the package writer; and InDesign Tagged Text, read and written. +- [`craft-ical`](crates/ical/README.md): iCalendar (RFC 5545) building blocks, from MailCraft: content + lines, DATE/DATE-TIME values, durations, TEXT escaping, the common subset of recurrence rules, + and `VTIMEZONE` definitions read and written. No time-zone database; what events and to-dos + mean stays in each app. Bounded and panic-free on hostile input. +- [`craft-stream-codecs`](crates/stream-codecs/README.md): byte-stream and bi-level image codecs that + PDF, PostScript and TIFF share: LZW, ASCII85, ASCIIHex, RunLength, TIFF and PNG predictors, + CCITT Group 3 and 4 decoding and Group 4 encoding, JBIG2 decoding and lossless encoding. Every + decoder is bounded and returns its partial output on damage. From PdfCraft; a PDF filter chain + is built on it in `craft-pdf`. +- [`craft-timeline`](crates/timeline/README.md): editorial timeline interchange: exact media time and SMPTE timecode, import/export reports, media path and `file://` URL handling, Avid Log Exchange (ALE) and CMX 3600 EDL documents, format detection. From FilmCraft. +- [`craft-time`](crates/time/README.md): exact rational ticks and SMPTE time across media, with a `soundcraft` compatibility module retaining SoundCraft's sample-index timebase, tempo maps, grids and session serialization semantics. +- [`craft-metadata`](crates/metadata/README.md): photo metadata, from LightCraft: EXIF (read and write, + maker-note lens and focus point, every tag by name), IPTC-IIM, XMP packets (read, write, and a merge + that keeps what another program wrote), GPX track logs, and the blocks that carry them in JPEG, PNG, + WebP, TIFF-based, RAF and CR3 files. One `Metadata` model for all of them. Built on `craft-tiff`. +- [`craft-tiff`](crates/tiff/README.md): TIFF and BigTIFF IFD reader and writer, from LightCraft: + every field type, the IFD chain, SubIFDs and Exif/GPS/Interop pointer IFDs, maker-note IFDs + (Canon, Nikon, Sony, Fujifilm, Olympus, Panasonic, Pentax), strip and tile layout. Bounded and + panic-free on hostile input. Pixel decompression stays with the callers. +- [`craft-metafile`](crates/metafile/README.md): Windows metafiles, from DeckCraft, WordCraft and + VectorCraft: a WMF, EMF and EMF+ reader into a neutral picture (paths with line styles, pattern + fills, bitmaps, text, clip regions and clip paths) and, behind `write`, EMF and WMF writers. + Bounded and panic-free on hostile input. Mapping the picture onto a document stays in each app. +- [`craft-psd`](crates/psd/README.md): Adobe Photoshop PSD and PSB reader and writer, from + PhotoCraft: a lossless format-level model (layers, masks, tagged blocks, image resources, + descriptors, all four compressions, lazy reading from a file) that writes an unmodified file + back byte for byte, a builder for new files, and the Photoshop resource files that share its + primitives (`.abr`, `.asl`, `.aco`, `.act`, `.ase`, `.grd`, `.pat`, `.atn`, `.csh`, `.shc`) and + the Photoshop blocks of a layered TIFF. Bounded and panic-free on hostile input. Compositing + and the mapping onto a document stay in each app. +- [`craft-jmap`](crates/jmap/README.md): the JMAP protocol core (RFC 8620), from MailCraft, without + sockets: session, requests of method calls with back-references, responses, ids, address + templates, credentials and the judgement of HTTP answers, over any HTTP implementation. Bounded + on hostile answers; what a program asks and makes of the answers stays in it. +- [`craft-jpeg`](crates/jpeg/README.md): clean-room decoder for 12-bit and arithmetic-coded + JPEG (T.81 SOF0/SOF1 at 12 bits, SOF9, SOF10), from PhotoCraft, and a frame probe for routing. + Metadata stays in each app. +- [`craft-raster-codecs`](crates/raster-codecs/README.md): small raster formats, one module each, + from PhotoCraft: DDS (BC1 to BC3, read and write), DICOM, FITS (read and write), IFF/ILBM (read + and write), PCX, PNM/PAM/PFM (read and write) and XPM, into one flat image type. Bounded and + panic-free on hostile input. Colour, orientation and the document mapping stay in each app. +- [`craft-kiwi`](crates/kiwi/README.md): clean-room decoder and encoder for the kiwi binary schema + format (the encoding inside `.fig` files): a schema of enums, structs and messages, and messages + decoded with it into a tree keyed by field name. Bounded on hostile input. Carved from FigCraft. +- [`craft-keymap`](crates/keymap/README.md): keyboard bindings: chords and their text forms, + scopes, conflicts, user overrides stored through craft-settings and import of other + applications' shortcut sets. Command catalogs, file readers and the shortcut editor UI stay + in each app. +- [`craft-audio`](crates/audio/README.md): audio file I/O and codecs (WAV, AIFF, FLAC, AAC, Opus, + AC-3/E-AC-3, MP1/MP2, MP3 encoding), streaming and seeking, and packet decoding for any demuxer. See its + README for formats and features. +- [`craft-latex`](crates/latex/README.md): LaTeX documents read (the everyday subset) and written (a standalone article), to and from the craft-flow model. +- [`craft-markdown`](crates/markdown/README.md): Markdown read and written (a CommonMark subset with GitHub tables and strikethrough), to and from the craft-flow model. +- [`craft-math`](crates/math/README.md): equations as one tree (the Office Math object model) with its syntaxes, read and written: OMML, presentation MathML, LaTeX math and the UnicodeMath linear format. +- [`craft-media`](crates/media/README.md): bit-level I/O (`bitstream`), clean-room MP4/MOV + (`isobmff`), Matroska/WebM (`matroska`) and MXF (`mxf`) demuxers and muxers, Ogg (`ogg`), AVI (`avi`) and + MPEG-TS/PS (`mpegts`) demuxers, from FilmCraft, and an ISO BMFF box reader. Containers only; codecs are in `craft-audio`, and + video codecs will go in a separate crate. +- [`craft-lottie`](crates/lottie/README.md): Lottie (Bodymovin) JSON: the document model of + lottie-spec 1.0 (animation, assets, layers by type, shape items, masks, effects, text, markers) + with a bounded reader and a writer that keep what they do not know, and the encodings of its + values (keyframes, ease tangents, bezier paths, gradients, data URIs). From EffectCraft; mapping + onto an app's document stays in the app. +- [`craft-menu`](crates/menu/README.md): an app's menus as a macOS menu bar: the Mac layout + (app menu, Window, Help, system-key clashes), a platform backend trait, and key equivalents + fed back to egui as the input egui-winit would have made. Commands and their enabled state + stay in each app. +- [`craft-mesh`](crates/mesh/README.md): 3D mesh file formats behind one neutral model (meshes + of polygons with per-corner indices, materials, a node hierarchy): STL, OBJ with MTL, PLY, + glTF 2.0 / GLB and 3MF, one feature each. Readers are bounded by `Limits`, never open a file themselves + glTF 2.0 / GLB and FBX, one feature each. Readers are bounded by `Limits`, never open a file themselves + and never panic. Carved from EffectCraft, SolidCraft, TextureCraft and MaterialCraft. +- [`craft-midi`](crates/midi/README.md): Standard MIDI Files: a bounded reader for formats 0, 1 and + 2 and a format-1 writer, over a neutral model of notes and channel events in ticks at 960 per + quarter note. From SoundCraft. +- [`craft-mime`](crates/mime/README.md): Internet messages and MIME, read and written: RFC 5322 + header fields, MIME parts and multiparts, encoded-words, RFC 2231 parameters, base64 and + quoted-printable, character sets, address lists, dates, mbox files and the `multipart/related` + lookups of MHT web archives. What a message means (body, attachments, flags) stays in each app. +- [`craft-openpgp`](crates/openpgp/README.md): OpenPGP as mail carries it: PGP/MIME and cleartext + Digital signatures checked, attached Public keys and `Autocrypt:` headers read, a secret key + file inspected without using it. Built on rPGP; no I/O, and every size and count is capped. +- [`craft-odf`](crates/odf/README.md): OpenDocument packages (ODF 1.3 Part 2), read and written: the ZIP container with its `mimetype` and manifest within limits, password protection (AES-256-CBC with PBKDF2, as LibreOffice writes it) and flat single-file documents. With the `text` feature, OpenDocument Text documents read into and written from the craft-flow model. +- [`craft-prc`](crates/prc/README.md): a reader for PRC (ISO 14739-1), the 3D model format of PDF 3D + annotations: container, bit-level primitives, schema, tessellations and the product tree as + placed, coloured triangle meshes and a model tree. Bounded on hostile input. From PdfCraft; + rendering stays in the app. +- [`craft-offcrypto`](crates/offcrypto/README.md): clean-room Office document cryptography ([MS-OFFCRYPTO]): password-encrypted OOXML packages on `craft-cfb` (agile and standard encryption read, with the integrity check enforced; agile written), unsupported schemes named, and the password hashes of document and sheet protection. +- [`craft-ods`](crates/ods/README.md): OpenDocument spreadsheets (`.ods`, `.ots`) on `craft-odf`: the tables of `content.xml` with typed values, displayed text, formulas as text, style names, repeats expanded and merged cells, with dates and durations as serial numbers. Bounded cells, merges and text; strict XML. +- [`craft-opc`](crates/opc/README.md): Open Packaging Conventions, the ZIP container of DOCX, XLSX and PPTX + files: bounded readers (every part up front, or on demand), part names, relationships, content + types and a deterministic package writer. What the parts hold stays with each format's crate. +- [`craft-pcraft-format`](crates/pcraft-format/README.md): the envelope of PhotoCraft's `.pcraft` + bundle: `Manifest` with the document as a type parameter, `TileRef`, the entry paths, the + manifest decode limits and the migration runner. The document model stays in PhotoCraft. +- [`craft-pkcs7`](crates/pkcs7/README.md): the formats of digital signatures, read, verified and + written: ASN.1 DER, X.509 certificates and chains, CMS SignedData (PKCS #7), PKCS #12 identity + files, RFC 3161 timestamps, and CRL / OCSP revocation evidence. What a signature means for a + document or a message stays in each app. +- [`craft-penpot`](crates/penpot/README.md): clean-room reader and writer for the Penpot 2.x export + container (`.penpot`): the ZIP archive, its manifest, the per-file, per-page and per-shape JSON + members and media objects, as the JSON the file holds. Bounded on hostile input. Carved from + FigCraft. +- [`craft-plotter`](crates/plotter/README.md): cutter and pen-plotter command languages: HP-GL, + DMPL and GP-GL (plain and the Silhouette dialect, three generations, registration marks) from a + job in millimetres, plus the Silhouette device queries and reply parsers. No I/O. +- [`craft-pptx`](crates/pptx/README.md): PresentationML, the model of a `.pptx` presentation: + masters, layouts, slides, shapes, placeholders and their inheritance, transitions and animations, + comments, sections, media and kept parts. From DeckCraft. DrawingML comes from `craft-drawingml`. - [`craft-print`](crates/print/README.md): PDF submission to CUPS and Windows, printer discovery, duplex/copies/colour and driver preferences. PDF generation stays in each app. +- [`craft-proof`](crates/proof/README.md): proofing per language (spelling, suggestions, grammar, + hyphenation, a Hunspell reader, user words, Language packs). The word lists and patterns are + craft-i18n's `language-data/`, embedded at build time from `CRAFT_I18N_DIR`: English and the + carry-over locales by default, the set `CRAFT_PROOF_EMBED` names otherwise (`en` for English + only); other languages come from installed Language packs. + +- [`craft-pst`](crates/pst/README.md): Outlook personal folders files (`.pst`, [MS-PST]) read over any + `Read + Seek`, from MailCraft: the node database, property and table contexts, folders, messages, + recipients, attachments, attached messages and named properties, ANSI and Unicode, encoded or not, + with a password. Salvages damaged files. Bounded and panic-free on hostile input. What an item + means stays in each app. + - [`craft-quit`](crates/quit/src/lib.rs): native macOS quit, egui close handling and an optional app menu. Unsaved-document decisions and save prompts stay in each app. +- [`craft-rtf`](crates/rtf/README.md): Rich Text Format: a tokenizer, text decoding in the file's code pages + (`\uN`, `\'hh`, single-byte and East Asian multibyte pages), escaping and dates, and a reader and writer + for a small neutral model (paragraphs, character formatting, outline levels, tables). - [`craft-settings`](crates/settings/README.md): `config.toml` settings storage for every app: platform folders, portable mode and overrides, atomic saves while running, backup, damaged-file recovery and schema migrations. Policy in [docs/settings-storage.md](docs/settings-storage.md). -- [`craft-time`](crates/time/README.md): Exact media time base (`TICKS_PER_SECOND = 254_016_000_000`), rational frame rates, and SMPTE timecode (drop/non-drop frame, 35mm/16mm feet+frames) for FilmCraft, SoundCraft, EffectCraft, and animation timeline consumers. +- [`craft-sheet`](crates/sheet/README.md): spreadsheet vocabulary shared by `craft-xls`, `craft-xlsx` and `craft-ods`: cell positions and A1 text, cell values and error values, sheet-name quoting, Excel's built-in number formats and indexed colour palette. Not a file format; no dependencies. +- [`craft-sf2`](crates/sf2/README.md): SoundFont 2 (`.sf2`) reader: the sample pool and, per preset, the key and velocity regions a note sounds, with tuning, loop points, pan, level and volume envelope resolved from the preset and instrument zones. Bounded on hostile input. From LoopCraft. +- [`craft-silhouette-studio`](crates/silhouette-studio/src/lib.rs): bounded, fail-closed reader for Silhouette Studio `.studio` and `.studio3` documents: outlines, line colours and page size in millimetres. Protected designs are refused. +- [`craft-sketch`](crates/sketch/README.md): clean-room reader for the `.sketch` container (Sketch 48 and newer): the ZIP archive, the version cut, `document.json`, the pages in document order and images, as the JSON the file holds. Bounded on hostile input. Carved from FigCraft. +- [`craft-svg`](crates/svg/src/lib.rs): SVG. `sniff` recognises SVG and SVGZ data; `svgz` unpacks + SVGZ within a byte limit, decodes UTF-8, UTF-16 and ISO 8859-1, and compresses; `guard` bounds + element nesting and entity expansion before any XML reader sees the text; `paths` reads geometry + (shapes, transforms, ``/`` instances and the CSS cascade as Bézier paths in + millimetres, each tagged by the caller); `color` parses CSS colours; `write` writes documents + (elements with escaping, path data, numbers). Feature `tree`: the full parser, usvg at the one + version every Craft app uses, re-exported behind an entry point that runs those checks first + (plus nesting with references followed, attribute counts, bounded embedded SVGs), and a budget + check for drawing a tree with resvg. Apps take usvg from here, not as their own dependency. +- [`craft-svg-paths`](crates/svg-paths/src/lib.rs): the former name of `craft-svg`'s `paths`, + `color` and `write`; re-exports them for existing users. +- [`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-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 + (legacy character sets, quoted-printable, labels and Apple label groups, `KEY` certificates and + OpenPGP public keys), vCard 3.0 written. Bounded and panic-free on hostile input. The mapping onto + an app's contact type stays in each app. + +- [`craft-vectorcraft-format`](crates/vectorcraft-format/README.md): the envelope of VectorCraft's + `.vectorcraft` file: its members, versions, embedded images and the data after the JSON, with the + document as a type parameter. The document and its migrations stay in VectorCraft. +- [`craft-vectordrawable`](crates/vectordrawable/src/lib.rs): Android Vector Drawable writer: a model of + paths, groups, clip outlines, strokes and linear, radial and sweep gradients; the XML as Android + Studio formats it; and the mapping of a gradient on any affine frame to what a drawable can say. + What a drawable cannot draw is the caller's to bake in or leave out. No reader. +- [`craft-web-api`](crates/web-api/README.md): the page command API every Craft web build offers its page — one + `window.` shape (`request`, `execute`, `commands`, `docInspect`, `uiInspect`, `screenshot`) over the app's + JSON control channel. +- [`craft-web-host`](crates/web-host/README.md): the host messages between a Craft app's web build and the page that hosts it (`?host=parent` or `data-host="page"`): one contract and one bridge for every app. +- [`craft-webp`](crates/webp/src/lib.rs): the WebP container, from EffectCraft (reader) and + PhotoCraft (writer): canvas size, alpha and every animation frame's timing from the chunk + headers without decoding, and the RIFF container around an encoded VP8 frame with alpha, ICC, + EXIF and XMP chunks. The VP8 and VP8L codecs are not part of it. +- [`craft-xls`](crates/xls/README.md): clean-room Excel 97-2003 workbook (`.xls`, BIFF8) reader: worksheets, cell values, formulas as A1 text (shared and array formulas included), cell formats with resolved palette colours, merged cells, column and row records, defined names, print areas and calculation settings, with limits on records, cells and text. +- [`craft-wordmodel`](crates/wordmodel/README.md): a word-processing document model (stories, paragraphs, + runs, tables, sections, styles, numbering, fields, notes, comments, revisions, drawings, math): what the + text-format crates read into and write from. WordCraft's model without its editing code. +- [`craft-xlsx`](crates/xlsx/README.md): Excel workbooks (`.xlsx`, `.xlsm`, SpreadsheetML, transitional and strict) and binary workbooks (`.xlsb`) on `craft-opc`: the workbook part, shared strings, the styles tables and worksheet rows streamed one at a time, with limits on the package, the XML and the binary records. +- [`craft-ora`](crates/ora/README.md): OpenRaster documents (`.ora`): the ZIP archive and the `stack.xml` layer tree as written, read with bounded sizes and written. From PhotoCraft. +- [`craft-y4m`](crates/y4m/src/lib.rs): YUV4MPEG2 (`.y4m`) reader, from FilmCraft: the stream + header, colour space layouts at 8 to 16 bits, a frame index built from the `FRAME` lines without + loading the file, and plane access. Bounded on hostile input. +- [`craft-kra`](crates/kra/README.md): Krita documents (`.kra`, `.krz`), read: the ZIP archive, the `maindoc.xml` node tree as written, and the tiled pixel files with their LZF compression, a tile at a time. From PhotoCraft. +- [`craft-xcf`](crates/xcf/README.md): GIMP XCF images (`.xcf`, `.xcf.gz`), read: header, properties, parasites, layers with their item paths, channels, and tiled pixels (uncompressed, RLE, zlib) at every precision, under a caller's byte budget. From PhotoCraft. +- [`craft-xml`](crates/xml/README.md): bounded XML for hostile input: an owned element tree with limits on size, depth, nodes and attributes, streaming of repeated elements, namespace handling (as written, by local name, or canonical prefixes by URI), escaping and a writer. No DTDs and no entity expansion. +- [`craft-zip`](crates/zip/README.md): ZIP archives from untrusted files: an entry-count check before the archive is indexed (ZIP64 included), entry reads within per-entry and total budgets that count real bytes, duplicate-name detection, a strict structure preflight, and a deterministic stored/deflate writer. The shared ZIP layer for the package formats. - [Shared UI component audit](docs/ui-components-audit.md): source inventory, extraction priorities and compatibility boundaries across the Craft suite. - [Theme infrastructure](docs/theme-infrastructure.md): eight-app comparison and the small shared diff --git a/clippy.toml b/clippy.toml index 4b6c79f55..8f54197d8 100644 --- a/clippy.toml +++ b/clippy.toml @@ -2,3 +2,7 @@ allow-unwrap-in-tests = true allow-expect-in-tests = true allow-panic-in-tests = true allow-indexing-slicing-in-tests = true +cognitive-complexity-threshold = 30 +disallowed-types = [ + { path = "egui::ComboBox", reason = "use craft_ui::ComboBox: egui's combo box menu can't grow back while open (egui#5225)" }, +] diff --git a/crates/aaf/Cargo.toml b/crates/aaf/Cargo.toml new file mode 100644 index 000000000..397032961 --- /dev/null +++ b/crates/aaf/Cargo.toml @@ -0,0 +1,18 @@ +[package] +name = "craft-aaf" +description = "Clean-room AAF (Edit Protocol, structured storage) and OMF Interchange 2.0 (Bento) readers and writers over one mob-style composition model, with embedded PCM essence." +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +repository.workspace = true + +[lints] +workspace = true + +[dependencies] +craft-cfb = { workspace = true } +craft-timeline = { workspace = true } +# WAV and AIFF around embedded PCM essence: the one WAV/AIFF implementation, not a second one here. +craft-audio = { workspace = true, features = ["decode-native", "pcm-encode"] } +thiserror = { workspace = true } diff --git a/crates/aaf/README.md b/crates/aaf/README.md new file mode 100644 index 000000000..7d3d44767 --- /dev/null +++ b/crates/aaf/README.md @@ -0,0 +1,67 @@ +# craft-aaf + +AAF and OMF, the two mob-based editorial interchange formats, read and written through one +composition model. + +| Module | What | +|---|---| +| `model` | `Document`: compositions (tracks of fillers, source clips and overlapping transitions; clip gain, constant or keyframed; markers; start timecode), nested compositions, and the media `Source`s they reference (file path or embedded PCM, picture size and rate, sound channels / rate / bits, start timecode, markers). Times are exact `craft_timeline::time::Tick`s. | +| `aaf` | `read`, `write`, `sniff`: AAF Edit Protocol in structured storage (`craft-cfb`). | +| `omf` | `read`, `write`, `sniff`: OMF Interchange 2.0 in a Bento container. Sound only. | + +No file I/O: documents are bytes and media references are strings. An application maps its own +timeline onto `model` once and gets both formats. Embedded audio is PCM in the model; the WAVE and +AIFF wrappers the formats use come from `craft-audio`. + +## Specifications + +Clean-room: written from public specifications only. The AAF SDK, pyaaf2, the OMF Toolkit and +other implementations were not consulted. Where a specification leaves a layout open (how a +nested sequence is written, how several video tracks share a slot), what Premiere Pro does was +read off files it exports. + +| Format | Document | Edition | Used for | +|---|---|---|---| +| AAF | AMWA *AAF Object Specification* | v1.1 (2005) | classes, properties, mob / slot / segment model, sequences and transitions, operation groups, parameters, definitions, descriptors, locators, essence data | +| AAF | AMWA *AAF Low-Level Container Specification* | v1.0.1 | objects as structured storages, `properties` streams, stored forms, strong / weak reference collections and their index streams, `referenced properties` | +| AAF | AMWA *AAF Edit Protocol* | v1.0 (AMWA AS-01) | top-level composition, mob chains (composition → master → file → physical source), operation definitions, usage codes | +| AAF | SMPTE RP 224 / RP 210 registers | — | data definition, class and type labels | +| AAF | Microsoft [MS-CFB] | rev. 10.0 | the container, see `craft-cfb` | +| OMF | Avid *OMF Interchange Specification* | Version 2.0 (1997) | classes (`HEAD`, `CMOB`, `MMOB`, `SMOB`, `MSLT`, `TRKD`, `SEQU`, `SCLP`, `FILL`, `TRAN`, `EFFE`, `ESLT`, `CVAL`, `VVAL`, `TCCP`, `WAVD`, `AIFD`, `WAVE`, `AIFC`, locators), property and type names | +| OMF | Apple *Bento Specification* | revision 1.0d5 | container label, TOC encoding, objects / properties / types, references | + +## What is read and written + +AAF: a top-level composition mob with a timecode slot, a timeline slot per track (sequences of +fillers, source clips and transitions; `VideoDissolve`, `VideoFadeToBlack`, `SMPTEVideoWipe`, +`MonoAudioDissolve`), clip gain as a `MonoAudioGain` operation group with a constant or varying +amplitude, markers as comment markers in an event slot, a composition mob for every nested +composition, and per media item a master mob, file source mobs (CDCI or PCM descriptor with a +network locator, or `EssenceData` with embedded PCM) and a tape source mob with the start +timecode. The reader also takes sequences inside sequences, selectors, essence groups, legacy data +definitions, and Premiere Pro's layout (all video tracks as layers of one slot, nested compositions +tagged top-level). 512-byte or 4096-byte sectors. + +OMF: a composition mob with a timecode slot and a sound slot per track, in samples; transitions as +`SimpleMonoAudioDissolve`; gain as `MonoAudioGain`; master, file (`WAVD` / `AIFD`, embedded `WAVE` +data or a locator) and tape mobs. + +Not represented: speed changes, video effects other than transitions, OMF picture and markers. + +Private tags, first written by FilmCraft and kept so existing files read back: AAF tagged values +`FilmCraft Effect`, `FilmCraft Frame Size`, `FilmCraft Audio Sample Rate`; OMF properties +`FilmCraft:SCLP:ClipName`, `FilmCraft:EFFE:EffectID`. + +## Hostile input + +A damaged or crafted file gives an error or a report entry, never a panic, a hang or an allocation +sized by a count in the file: weak-collection counts are checked against the index stream, zero-size +keys are refused, a storage owned twice is an error, nesting of segments and of compositions is +bounded, times are clamped to about three days. `src/aaf/hostile_tests.rs` and +`src/roundtrip_tests.rs` (truncation at every 97th byte, 400 random 8-byte corruptions per format) +cover them. + +## Origin + +Moved from FilmCraft's `filmcraft-interchange` (`aaf`, `omf`, the model types of `comp`). The +mapping between the model and an application's project stays in the application. diff --git a/crates/aaf/src/aaf.rs b/crates/aaf/src/aaf.rs new file mode 100644 index 000000000..05894f94e --- /dev/null +++ b/crates/aaf/src/aaf.rs @@ -0,0 +1,84 @@ +//! AAF (Advanced Authoring Format) import and export, following the AAF Edit Protocol. +//! +//! Written from the public AMWA specifications: *AAF Object Specification v1.1*, *AAF Low-Level +//! Container Specification v1.0.1* (structured storage mapping, see [`store`]) and *AAF Edit +//! Protocol v1.0*; the container is Microsoft's Compound File Binary format ([`craft_cfb`]). +//! +//! A written file holds one top-level **CompositionMob** (Edit Protocol usage code +//! "top level") with +//! +//! - a timecode slot (sequence start timecode, rounded rate, drop frame), +//! - one timeline slot per video track (picture) and per audio track (sound; one per channel when +//! broken out to mono), each a **Sequence** of **Filler**s, **SourceClip**s and **Transition**s +//! (Cross Dissolve → `VideoDissolve_2`, Dip to Black → `VideoFadeToBlack`, audio crossfades → +//! `MonoAudioDissolve`; the model's transition name is kept in a tagged value), +//! - clip volume as a `MonoAudioGain` **OperationGroup** around the source clip with an +//! `Amplitude` **ConstantValue** or **VaryingValue** (keyframes as control points), +//! - sequence markers as **CommentMarker**s in an event slot; +//! +//! a **CompositionMob** without a usage code for every nested sequence, built the same way (a +//! clip of the nested sequence is a **SourceClip** that points at that mob, at its first slot of +//! the clip's kind, with its start in that slot's edit units; Premiere Pro writes nested sequences +//! this way); +//! +//! and for every media item a **MasterMob**, a file **SourceMob** per essence (a CDCI or PCM +//! descriptor with a network locator to the file, or `EssenceData` holding embedded PCM) and a +//! tape **SourceMob** carrying the media's start timecode. Clip and media markers become comment +//! markers on the master mob. +//! +//! Import reads the same structures (and the common variations: sequences inside sequences, +//! selectors, operation groups around clips, legacy data definitions, essence groups, and Premiere +//! Pro's one video slot holding a nested scope with a segment per video track) into the model: +//! compositions (one that others use is a nested composition), sources (with their path, or their +//! embedded audio as PCM) and markers. +//! +//! Private tags. Three tagged values are not in any register; they were first written by FilmCraft +//! and keep their names so that existing files read back: `FilmCraft Effect` (a transition's +//! name), `FilmCraft Frame Size` and `FilmCraft Audio Sample Rate` (on the composition). + +mod ids; +mod read; +pub(crate) mod store; +mod write; + +use crate::model::Document; +use crate::{Identity, Report, Result}; + +/// How to write an AAF file. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct WriteOptions<'a> { + pub identity: Identity<'a>, + /// Write 512-byte sectors (compound file version 3) instead of 4096-byte sectors. + pub small_sectors: bool, +} + +/// Write `doc` as an AAF file: its first composition is the top-level one, with every nested +/// composition and every source it uses. Times that are not on whole edit units are rounded and +/// reported. +pub fn write(doc: &Document, opts: &WriteOptions<'_>, report: &mut Report) -> Result> { + let version = if opts.small_sectors { craft_cfb::Version::V3 } else { craft_cfb::Version::V4 }; + write::write(doc, version, &opts.identity, report) +} + +/// Read an AAF file: its top-level compositions, the compositions nested in them and their +/// sources. What cannot be represented is skipped and named in `report`. +pub fn read(bytes: &[u8], report: &mut Report) -> Result { + read::read(bytes, report) +} + +/// Whether `bytes` look like an AAF file (a compound file whose root has the AAF root class or a +/// `Header-2` storage). +pub fn sniff(bytes: &[u8]) -> bool { + if !craft_cfb::sniff(bytes) { + return false; + } + match craft_cfb::CompoundFile::open(bytes) { + Ok(cf) => cf.root().clsid == ids::ROOT || cf.find("Header-2").is_ok(), + Err(_) => false, + } +} + +#[cfg(test)] +mod hostile_tests; +#[cfg(test)] +mod tests; diff --git a/crates/aaf/src/aaf/hostile_tests.rs b/crates/aaf/src/aaf/hostile_tests.rs new file mode 100644 index 000000000..853b0000c --- /dev/null +++ b/crates/aaf/src/aaf/hostile_tests.rs @@ -0,0 +1,110 @@ +//! Hostile object trees: a crafted file must give an error, never a crash, a hang or an +//! allocation sized by a count in the file (AGENTS.md §0). + +use craft_cfb::{Version, Writer}; + +use super::store::{self, SF_STRONG_VECTOR, SF_WEAK_SET, SF_WEAK_VECTOR, Value, utf16z}; + +const PID: u16 = 0x0007; + +/// A root object whose one property `PID` is a weak reference vector or set (stored form `sf`) +/// named `Keys`, with `index` as its `Keys index` stream. +fn weak_collection_file(sf: u16, index: Vec) -> Vec { + let name = utf16z("Keys"); + // byte order 'L', format version, 1 entry { pid, stored form, value length }, the value + let mut props = vec![0x4C, 0x20]; + for x in [1, PID, sf, name.len() as u16] { + props.extend_from_slice(&x.to_le_bytes()); + } + props.extend_from_slice(&name); + let mut w = Writer::new(Version::V3); + w.stream(Writer::ROOT, "properties", props).unwrap(); + w.stream(Writer::ROOT, "Keys index", index).unwrap(); + w.finish() +} + +/// A weak collection index: u32 count, u16 tag, u16 key pid, u8 key size, then the keys. +fn index(count: u32, size: u8, keys: &[u8]) -> Vec { + let mut v = count.to_le_bytes().to_vec(); + v.extend_from_slice(&0u16.to_le_bytes()); + v.extend_from_slice(&0x1B01u16.to_le_bytes()); + v.push(size); + v.extend_from_slice(keys); + v +} + +fn read_keys(sf: u16, index: Vec) -> Result>, String> { + match store::read(&weak_collection_file(sf, index))?.get(PID) { + Some(Value::WeakVec(_, _, keys)) => Ok(keys.clone()), + other => panic!("not a weak collection: {other:?}"), + } +} + +/// With a key size of 0 every key fits, so the count alone drove the loop: up to 4.29 billion +/// empty keys (about 100 GB) from a 9-byte index. A million is enough to show it, cheaply. +#[test] +fn zero_size_weak_collection_keys_are_an_error() { + for sf in [SF_WEAK_VECTOR, SF_WEAK_SET] { + match read_keys(sf, index(1_000_000, 0, &[])) { + Err(e) => assert!(e.contains("zero-size"), "{e}"), + Ok(keys) => panic!("read {} empty keys instead of an error", keys.len()), + } + } +} + +#[test] +fn weak_collection_count_beyond_the_index_is_an_error() { + for sf in [SF_WEAK_VECTOR, SF_WEAK_SET] { + let e = read_keys(sf, index(u32::MAX, 4, &[1, 2, 3, 4, 5, 6, 7, 8])).unwrap_err(); + assert!(e.contains("short weak collection index"), "{e}"); + } +} + +#[test] +fn weak_collections_within_the_index_are_read() { + for sf in [SF_WEAK_VECTOR, SF_WEAK_SET] { + assert_eq!(read_keys(sf, index(0, 0, &[])).unwrap(), Vec::>::new()); + assert_eq!(read_keys(sf, index(2, 4, &[1, 2, 3, 4, 5, 6, 7, 8])).unwrap(), [vec![1, 2, 3, 4], vec![5, 6, 7, 8]]); + } +} + +/// A strong vector whose entries all name the same child storage would rebuild that subtree once +/// per entry; a storage has one owner, so the repeat is an error. +#[test] +fn a_storage_owned_twice_is_an_error() { + let name = utf16z("Items"); + let mut props = vec![0x4C, 0x20]; + for x in [1, PID, SF_STRONG_VECTOR, name.len() as u16] { + props.extend_from_slice(&x.to_le_bytes()); + } + props.extend_from_slice(&name); + // count, next free key, last key, then the entry keys + let mut idx = 3u32.to_le_bytes().to_vec(); + idx.extend_from_slice(&[0; 8]); + for _ in 0..3 { + idx.extend_from_slice(&1u32.to_le_bytes()); + } + let mut w = Writer::new(Version::V3); + w.stream(Writer::ROOT, "properties", props).unwrap(); + w.stream(Writer::ROOT, "Items index", idx).unwrap(); + let child = w.storage(Writer::ROOT, "Items{1}", [0; 16]).unwrap(); + w.stream(child, "properties", vec![0x4C, 0x20, 0, 0]).unwrap(); + let e = store::read(&w.finish()).unwrap_err(); + assert!(e.contains("more than one reference"), "{e}"); +} + +/// Objects nest through strong references; a chain deeper than the reader follows is an error, +/// and one within it reads. +#[test] +fn objects_nested_too_deeply_are_an_error() { + let chain = |depth: usize| { + let mut o = store::Obj::new([1; 16]); + for _ in 0..depth { + o = store::Obj::new([1; 16]).with(PID, Value::Strong(Box::new(o))); + } + store::write(&o, Version::V4).unwrap() + }; + assert!(store::read(&chain(150)).is_ok()); + let e = store::read(&chain(250)).unwrap_err(); + assert!(e.contains("nested too deeply"), "{e}"); +} diff --git a/crates/aaf/src/aaf/ids.rs b/crates/aaf/src/aaf/ids.rs new file mode 100644 index 000000000..70a184060 --- /dev/null +++ b/crates/aaf/src/aaf/ids.rs @@ -0,0 +1,262 @@ +//! Class ids, property ids and definition ids of the AAF object model subset read and +//! writes (AAF Object Specification v1.1, AAF Edit Protocol). Class and data definition AUIDs are +//! SMPTE labels (RP 224 / RP 210 registers) in AUID byte order; property ids are the AAF / ST 377-1 +//! local tags. + +use super::store::Auid; + +/// AUID of a SMPTE universal label: the label's last 8 bytes become Data1–Data3 (stored +/// little-endian), its first 8 bytes Data4. +pub(crate) const fn ul(b: [u8; 16]) -> Auid { + [b[11], b[10], b[9], b[8], b[13], b[12], b[15], b[14], b[0], b[1], b[2], b[3], b[4], b[5], b[6], b[7]] +} + +/// A GUID `{d1-d2-d3-d4}` in AUID byte order. +pub(crate) const fn guid(d1: u32, d2: u16, d3: u16, d4: [u8; 8]) -> Auid { + let a = d1.to_le_bytes(); + let b = d2.to_le_bytes(); + let c = d3.to_le_bytes(); + [a[0], a[1], a[2], a[3], b[0], b[1], c[0], c[1], d4[0], d4[1], d4[2], d4[3], d4[4], d4[5], d4[6], d4[7]] +} + +/// Class AUID: SMPTE label 06.0E.2B.34.02.06.01.01.0D.01.01.01.01.01.xx.00. +pub(crate) const fn class(xx: u8) -> Auid { + ul([0x06, 0x0E, 0x2B, 0x34, 0x02, 0x06, 0x01, 0x01, 0x0D, 0x01, 0x01, 0x01, 0x01, 0x01, xx, 0x00]) +} + +/// The root object's class (the storage class of the file's root). +pub(crate) const ROOT: Auid = guid(0xB3B398A5, 0x1C90, 0x11D4, [0x80, 0x53, 0x08, 0x00, 0x36, 0x21, 0x08, 0x04]); +/// The meta-dictionary (class 0x25 of the meta-model, 06.0E.2B.34.02.06.01.01.0D.01.01.01.02.25.00.00). +pub(crate) const META_DICTIONARY: Auid = ul([0x06, 0x0E, 0x2B, 0x34, 0x02, 0x06, 0x01, 0x01, 0x0D, 0x01, 0x01, 0x01, 0x02, 0x25, 0x00, 0x00]); + +#[allow(dead_code)] +pub(crate) mod cls { + use super::class; + use crate::aaf::store::Auid; + pub const COMMENT_MARKER: Auid = class(0x08); + pub const FILLER: Auid = class(0x09); + pub const OPERATION_GROUP: Auid = class(0x0A); + pub const NESTED_SCOPE: Auid = class(0x0B); + pub const SCOPE_REFERENCE: Auid = class(0x0D); + pub const SELECTOR: Auid = class(0x0E); + pub const SEQUENCE: Auid = class(0x0F); + pub const SOURCE_CLIP: Auid = class(0x11); + pub const TIMECODE: Auid = class(0x14); + pub const TRANSITION: Auid = class(0x17); + pub const CONTENT_STORAGE: Auid = class(0x18); + pub const CONTROL_POINT: Auid = class(0x19); + pub const DATA_DEFINITION: Auid = class(0x1B); + pub const OPERATION_DEFINITION: Auid = class(0x1C); + pub const PARAMETER_DEFINITION: Auid = class(0x1D); + pub const CONTAINER_DEFINITION: Auid = class(0x20); + pub const INTERPOLATION_DEFINITION: Auid = class(0x21); + pub const DICTIONARY: Auid = class(0x22); + pub const ESSENCE_DATA: Auid = class(0x23); + pub const CDCI_DESCRIPTOR: Auid = class(0x28); + pub const TAPE_DESCRIPTOR: Auid = class(0x2E); + pub const HEADER: Auid = class(0x2F); + pub const IDENTIFICATION: Auid = class(0x30); + pub const NETWORK_LOCATOR: Auid = class(0x32); + pub const COMPOSITION_MOB: Auid = class(0x35); + pub const MASTER_MOB: Auid = class(0x36); + pub const SOURCE_MOB: Auid = class(0x37); + pub const EVENT_MOB_SLOT: Auid = class(0x39); + pub const TIMELINE_MOB_SLOT: Auid = class(0x3B); + pub const CONSTANT_VALUE: Auid = class(0x3D); + pub const VARYING_VALUE: Auid = class(0x3E); + pub const TAGGED_VALUE: Auid = class(0x3F); + pub const DESCRIPTIVE_MARKER: Auid = class(0x41); + pub const PCM_DESCRIPTOR: Auid = class(0x48); + pub const IMPORT_DESCRIPTOR: Auid = class(0x4A); + /// Classes with a `Locator` and media properties read as file descriptors. + pub const WAVE_DESCRIPTOR: Auid = class(0x2C); + pub const AIFC_DESCRIPTOR: Auid = class(0x26); + pub const SOUND_DESCRIPTOR: Auid = class(0x42); + pub const RGBA_DESCRIPTOR: Auid = class(0x29); + pub const MULTIPLE_DESCRIPTOR: Auid = class(0x44); +} + +/// Property ids. +#[allow(dead_code)] +pub(crate) mod pid { + // Root + pub const ROOT_META_DICTIONARY: u16 = 0x0001; + pub const ROOT_HEADER: u16 = 0x0002; + // MetaDictionary and MetaDefinition + pub const META_CLASS_DEFINITIONS: u16 = 0x0003; + pub const META_TYPE_DEFINITIONS: u16 = 0x0004; + pub const META_IDENTIFICATION: u16 = 0x0005; + // Header + pub const BYTE_ORDER: u16 = 0x3B01; + pub const LAST_MODIFIED: u16 = 0x3B02; + pub const CONTENT: u16 = 0x3B03; + pub const DICTIONARY: u16 = 0x3B04; + pub const VERSION: u16 = 0x3B05; + pub const IDENTIFICATION_LIST: u16 = 0x3B06; + pub const OBJECT_MODEL_VERSION: u16 = 0x3B07; + pub const OPERATIONAL_PATTERN: u16 = 0x3B09; + // Identification + pub const COMPANY_NAME: u16 = 0x3C01; + pub const PRODUCT_NAME: u16 = 0x3C02; + pub const PRODUCT_VERSION_STRING: u16 = 0x3C04; + pub const PRODUCT_ID: u16 = 0x3C05; + pub const DATE: u16 = 0x3C06; + pub const PLATFORM: u16 = 0x3C08; + pub const GENERATION_AUID: u16 = 0x3C09; + // ContentStorage + pub const MOBS: u16 = 0x1901; + pub const ESSENCE_DATA: u16 = 0x1902; + // Dictionary + pub const OPERATION_DEFINITIONS: u16 = 0x2603; + pub const PARAMETER_DEFINITIONS: u16 = 0x2604; + pub const DATA_DEFINITIONS: u16 = 0x2605; + pub const CONTAINER_DEFINITIONS: u16 = 0x2608; + pub const INTERPOLATION_DEFINITIONS: u16 = 0x2609; + // DefinitionObject + pub const IDENTIFICATION: u16 = 0x1B01; + pub const NAME: u16 = 0x1B02; + pub const DESCRIPTION: u16 = 0x1B03; + // OperationDefinition + pub const OPDEF_DATA_DEFINITION: u16 = 0x1E01; + pub const OPDEF_IS_TIME_WARP: u16 = 0x1E02; + pub const OPDEF_NUMBER_INPUTS: u16 = 0x1E07; + pub const OPDEF_PARAMETERS_DEFINED: u16 = 0x1E09; + // ParameterDefinition + pub const PARAMDEF_DISPLAY_UNITS: u16 = 0x1F03; + // Mob + pub const MOB_ID: u16 = 0x4401; + pub const MOB_NAME: u16 = 0x4402; + pub const SLOTS: u16 = 0x4403; + pub const MOB_LAST_MODIFIED: u16 = 0x4404; + pub const MOB_CREATION_TIME: u16 = 0x4405; + pub const MOB_USER_COMMENTS: u16 = 0x4406; + pub const USAGE_CODE: u16 = 0x4408; + // SourceMob + pub const ESSENCE_DESCRIPTION: u16 = 0x4701; + // MobSlot + pub const SLOT_ID: u16 = 0x4801; + pub const SLOT_NAME: u16 = 0x4802; + pub const SEGMENT: u16 = 0x4803; + pub const PHYSICAL_TRACK_NUMBER: u16 = 0x4804; + // TimelineMobSlot / EventMobSlot + pub const EDIT_RATE: u16 = 0x4B01; + pub const ORIGIN: u16 = 0x4B02; + pub const EVENT_EDIT_RATE: u16 = 0x4901; + // Component + pub const DATA_DEFINITION: u16 = 0x0201; + pub const LENGTH: u16 = 0x0202; + pub const COMPONENT_USER_COMMENTS: u16 = 0x0204; + // Sequence + pub const COMPONENTS: u16 = 0x1001; + // SourceReference / SourceClip + pub const SOURCE_ID: u16 = 0x1101; + pub const SOURCE_MOB_SLOT_ID: u16 = 0x1102; + pub const START_TIME: u16 = 0x1201; + // Event + pub const POSITION: u16 = 0x0601; + pub const COMMENT: u16 = 0x0602; + // Timecode + pub const TC_START: u16 = 0x1501; + pub const TC_FPS: u16 = 0x1502; + pub const TC_DROP: u16 = 0x1503; + // Transition + pub const OPERATION_GROUP: u16 = 0x1801; + pub const CUT_POINT: u16 = 0x1802; + // OperationGroup + pub const OPERATION: u16 = 0x0B01; + pub const INPUT_SEGMENTS: u16 = 0x0B02; + pub const PARAMETERS: u16 = 0x0B03; + // Selector / NestedScope + pub const SELECTED: u16 = 0x0F01; + pub const NESTED_SLOTS: u16 = 0x0C01; + // Parameter / ConstantValue / VaryingValue / ControlPoint + pub const PARAMETER_DEFINITION: u16 = 0x4C01; + pub const CONSTANT_VALUE: u16 = 0x4D01; + pub const INTERPOLATION: u16 = 0x4E01; + pub const POINT_LIST: u16 = 0x4E02; + pub const CP_VALUE: u16 = 0x1A02; + pub const CP_TIME: u16 = 0x1A03; + pub const CP_EDIT_HINT: u16 = 0x1A04; + // TaggedValue + pub const TAG_NAME: u16 = 0x5001; + pub const TAG_VALUE: u16 = 0x5003; + // EssenceDescriptor / FileDescriptor + pub const LOCATOR: u16 = 0x2F01; + pub const SAMPLE_RATE: u16 = 0x3001; + pub const FILE_LENGTH: u16 = 0x3002; + pub const CONTAINER_FORMAT: u16 = 0x3004; + pub const STORED_HEIGHT: u16 = 0x3202; + pub const STORED_WIDTH: u16 = 0x3203; + pub const FRAME_LAYOUT: u16 = 0x320C; + pub const VIDEO_LINE_MAP: u16 = 0x320D; + pub const IMAGE_ASPECT_RATIO: u16 = 0x320E; + pub const COMPONENT_WIDTH: u16 = 0x3301; + pub const HORIZONTAL_SUBSAMPLING: u16 = 0x3302; + pub const QUANTIZATION_BITS: u16 = 0x3D01; + pub const LOCKED: u16 = 0x3D02; + pub const AUDIO_SAMPLING_RATE: u16 = 0x3D03; + pub const CHANNELS: u16 = 0x3D07; + pub const AVERAGE_BPS: u16 = 0x3D09; + pub const BLOCK_ALIGN: u16 = 0x3D0A; + // NetworkLocator + pub const URL_STRING: u16 = 0x4001; + // EssenceData + pub const ESSENCE_MOB_ID: u16 = 0x2701; + pub const ESSENCE_STREAM: u16 = 0x2702; +} + +/// Data definitions (SMPTE RP 224 labels 06.0E.2B.34.04.01.01.01.01.03.02.xx.yy). +pub(crate) mod ddef { + use super::{guid, ul}; + use crate::aaf::store::Auid; + pub const PICTURE: Auid = ul([0x06, 0x0E, 0x2B, 0x34, 0x04, 0x01, 0x01, 0x01, 0x01, 0x03, 0x02, 0x02, 0x01, 0x00, 0x00, 0x00]); + pub const SOUND: Auid = ul([0x06, 0x0E, 0x2B, 0x34, 0x04, 0x01, 0x01, 0x01, 0x01, 0x03, 0x02, 0x02, 0x02, 0x00, 0x00, 0x00]); + pub const TIMECODE: Auid = ul([0x06, 0x0E, 0x2B, 0x34, 0x04, 0x01, 0x01, 0x01, 0x01, 0x03, 0x02, 0x01, 0x01, 0x00, 0x00, 0x00]); + pub const DESCRIPTIVE_METADATA: Auid = ul([0x06, 0x0E, 0x2B, 0x34, 0x04, 0x01, 0x01, 0x01, 0x01, 0x03, 0x02, 0x01, 0x10, 0x00, 0x00, 0x00]); + /// Pre-SMPTE ("legacy") data definitions written by older applications. + pub const LEGACY_PICTURE: Auid = guid(0x6F3C8CE1, 0x6CEF, 0x11D2, [0x80, 0x7D, 0x00, 0x60, 0x08, 0x14, 0x3E, 0x6F]); + pub const LEGACY_SOUND: Auid = guid(0x78E1EBE1, 0x6CEF, 0x11D2, [0x80, 0x7D, 0x00, 0x60, 0x08, 0x14, 0x3E, 0x6F]); + pub const LEGACY_TIMECODE: Auid = guid(0x7F275E81, 0x77E5, 0x11D2, [0x80, 0x7F, 0x00, 0x60, 0x08, 0x14, 0x3E, 0x6F]); +} + +/// Operation, parameter, interpolation and container definitions. +pub(crate) mod def { + use super::guid; + use crate::aaf::store::Auid; + const AV: [u8; 8] = [0x8A, 0x09, 0x00, 0x60, 0x08, 0x14, 0x3E, 0x6F]; + pub const VIDEO_DISSOLVE: Auid = guid(0x0C3BEA41, 0xFC05, 0x11D2, AV); + pub const VIDEO_FADE_TO_BLACK: Auid = guid(0x0C3BEA40, 0xFC05, 0x11D2, AV); + pub const SMPTE_VIDEO_WIPE: Auid = guid(0x0C3BEA43, 0xFC05, 0x11D2, AV); + pub const MONO_AUDIO_DISSOLVE: Auid = guid(0x0C3BEA44, 0xFC05, 0x11D2, AV); + const AG: [u8; 8] = [0x8A, 0x38, 0x00, 0x50, 0x04, 0x0E, 0xF7, 0xD2]; + pub const MONO_AUDIO_GAIN: Auid = guid(0x9D2EA893, 0x0968, 0x11D3, AG); + const PD: [u8; 8] = [0x8A, 0x4C, 0x00, 0x50, 0x04, 0x0E, 0xF7, 0xD2]; + pub const PARAM_LEVEL: Auid = guid(0xE4962320, 0x2267, 0x11D3, PD); + pub const PARAM_AMPLITUDE: Auid = guid(0xE4962321, 0x2267, 0x11D3, PD); + const IP: [u8; 8] = [0x80, 0xA9, 0x00, 0x60, 0x08, 0x14, 0x3E, 0x6F]; + pub const INTERP_LINEAR: Auid = guid(0x5B6C85A4, 0x0EDE, 0x11D3, IP); + pub const INTERP_CONSTANT: Auid = guid(0x5B6C85A5, 0x0EDE, 0x11D3, IP); + const CD: [u8; 8] = [0x80, 0x9B, 0x00, 0x60, 0x08, 0x14, 0x3E, 0x6F]; + pub const CONTAINER_AAF: Auid = guid(0x4313B571, 0xD8BA, 0x11D2, CD); + pub const CONTAINER_EXTERNAL: Auid = guid(0x4313B572, 0xD8BA, 0x11D2, CD); + /// Type ids of indirect values (SMPTE RP 210 type labels). + pub const TYPE_RATIONAL: Auid = super::ul([0x06, 0x0E, 0x2B, 0x34, 0x01, 0x04, 0x01, 0x01, 0x03, 0x01, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00]); + pub const TYPE_STRING: Auid = super::ul([0x06, 0x0E, 0x2B, 0x34, 0x01, 0x04, 0x01, 0x01, 0x01, 0x10, 0x02, 0x00, 0x00, 0x00, 0x00, 0x00]); + /// Edit Protocol operational pattern (`AAFEditProtocol`) and mob usage codes (`Usage_TopLevel`), + /// as in the SMPTE Labels register. + pub const OP_EDIT_PROTOCOL: Auid = super::ul([0x06, 0x0E, 0x2B, 0x34, 0x04, 0x01, 0x01, 0x05, 0x0D, 0x01, 0x12, 0x01, 0x01, 0x00, 0x00, 0x00]); + pub const USAGE_TOP_LEVEL: Auid = super::ul([0x06, 0x0E, 0x2B, 0x34, 0x04, 0x01, 0x01, 0x01, 0x0D, 0x01, 0x01, 0x02, 0x01, 0x01, 0x07, 0x00]); + /// The label FilmCraft 0.16 and earlier wrote as the top-level usage code (in no register). + /// Import reads it as top-level too. + pub const USAGE_TOP_LEVEL_OLD: Auid = super::ul([0x06, 0x0E, 0x2B, 0x34, 0x04, 0x01, 0x01, 0x05, 0x0D, 0x01, 0x12, 0x01, 0x02, 0x03, 0x00, 0x00]); +} + +/// Weak reference target paths (pids from the root object). +pub(crate) mod path { + use super::pid; + pub const DATA_DEFS: [u16; 3] = [pid::ROOT_HEADER, pid::DICTIONARY, pid::DATA_DEFINITIONS]; + pub const OPERATION_DEFS: [u16; 3] = [pid::ROOT_HEADER, pid::DICTIONARY, pid::OPERATION_DEFINITIONS]; + pub const PARAMETER_DEFS: [u16; 3] = [pid::ROOT_HEADER, pid::DICTIONARY, pid::PARAMETER_DEFINITIONS]; + pub const INTERPOLATION_DEFS: [u16; 3] = [pid::ROOT_HEADER, pid::DICTIONARY, pid::INTERPOLATION_DEFINITIONS]; + pub const CONTAINER_DEFS: [u16; 3] = [pid::ROOT_HEADER, pid::DICTIONARY, pid::CONTAINER_DEFINITIONS]; +} diff --git a/crates/aaf/src/aaf/read.rs b/crates/aaf/src/aaf/read.rs new file mode 100644 index 000000000..31c841c5d --- /dev/null +++ b/crates/aaf/src/aaf/read.rs @@ -0,0 +1,759 @@ +//! AAF objects → composition model. + +use std::collections::{HashMap, HashSet}; + +use craft_timeline::time::{FrameRate, Tick}; + +use super::ids::{cls, ddef, def, pid}; +use super::store::{self, Auid, Obj, Value, rational_of, utf16_of}; +use crate::model::{CClip, CItem, CKind, CMarker, CTrack, CTransition, Composition, Document, Gain, Source, units_to_ticks}; +use crate::{Error, Report, Result}; + +type MobId = [u8; 32]; + +#[derive(Clone, Copy, PartialEq, Eq)] +enum DataKind { + Picture, + Sound, + Timecode, + Other, +} + +fn data_kind(o: &Obj) -> DataKind { + match o.weak_key(pid::DATA_DEFINITION).and_then(|k| ::try_from(k).ok()) { + Some(k) if k == ddef::PICTURE || k == ddef::LEGACY_PICTURE => DataKind::Picture, + Some(k) if k == ddef::SOUND || k == ddef::LEGACY_SOUND => DataKind::Sound, + Some(k) if k == ddef::TIMECODE || k == ddef::LEGACY_TIMECODE => DataKind::Timecode, + Some(_) => DataKind::Other, + None => DataKind::Other, + } +} + +fn len_of(o: &Obj) -> i64 { + o.i64(pid::LENGTH).unwrap_or(0).max(0) +} + +/// The value of an indirect property: (type id, bytes). +fn indirect(d: &[u8]) -> Option<(Auid, &[u8])> { + if d.len() >= 17 && (d[0] == 0x4C || d[0] == 0x42) { + return Some((d[1..17].try_into().ok()?, &d[17..])); + } + if d.len() >= 16 { + return Some((d[..16].try_into().ok()?, &d[16..])); + } + None +} + +fn tagged_values(o: &Obj, p: u16) -> Vec<(String, String)> { + o.objs(p) + .iter() + .filter_map(|t| { + let name = t.string(pid::TAG_NAME)?; + let (ty, v) = indirect(t.data(pid::TAG_VALUE)?)?; + let value = if ty == def::TYPE_STRING || v.len() % 2 == 0 { utf16_of(v) } else { String::new() }; + Some((name, value)) + }) + .collect() +} + +fn indirect_f64(d: &[u8]) -> Option { + let (_, v) = indirect(d)?; + match v.len() { + 8 => rational_of(v).filter(|r| r.1 != 0).map(|(n, d)| n as f64 / d as f64), + 4 => Some(i32::from_le_bytes(v.try_into().ok()?) as f64), + _ => None, + } +} + +struct R<'a> { + report: &'a mut Report, + mobs: HashMap, + essence: HashMap, + doc: Document, + /// (file mob id, slot id, master key) → source index + sources: HashMap<(MobId, u32, String), usize>, + /// Composition mobs read as nested compositions: their index in `doc.nested`. + nests: HashMap, + /// The compositions being read, outermost first. + open: Vec, +} + +struct NestClip<'a> { + mob_id: MobId, + slot_id: u32, + rate: (i64, i64), + kind: CKind, + name: String, + mob: &'a Obj, +} + +/// Compositions nested deeper than this are read as gaps. +const MAX_NESTING: usize = 16; + +pub(crate) fn read(bytes: &[u8], report: &mut Report) -> Result { + let root = store::read(bytes).map_err(|e| Error::Parse { format: "AAF", message: e })?; + let header = root.strong(pid::ROOT_HEADER).ok_or_else(|| Error::Parse { format: "AAF", message: "no header object".into() })?; + let content = header.strong(pid::CONTENT).ok_or_else(|| Error::Parse { format: "AAF", message: "no content storage".into() })?; + let mut mobs = HashMap::new(); + for m in content.objs(pid::MOBS) { + if let Some(id) = m.mob_id(pid::MOB_ID) { + mobs.insert(id, m); + } + } + let mut essence = HashMap::new(); + for e in content.objs(pid::ESSENCE_DATA) { + if let (Some(id), Some(d)) = (e.mob_id(pid::ESSENCE_MOB_ID), e.stream(pid::ESSENCE_STREAM)) { + essence.insert(id, d); + } + } + let mut r = R { report, mobs, essence, doc: Document::default(), sources: HashMap::new(), nests: HashMap::new(), open: Vec::new() }; + // Top-level compositions: those no other composition uses, among the ones tagged top-level + // when any are. (Premiere Pro tags a nested sequence's composition top-level too; it is still + // only a nested sequence.) Compositions that only use each other in a circle all count. The + // label older FilmCraft versions wrote for top-level counts as top-level too. + let comps: Vec<&Obj> = content.objs(pid::MOBS).iter().filter(|m| m.class == cls::COMPOSITION_MOB).collect(); + let mut referenced = HashSet::new(); + for c in &comps { + collect_refs(c, &mut referenced); + } + let is_top = |c: &&Obj| c.auid(pid::USAGE_CODE).is_some_and(|u| u == def::USAGE_TOP_LEVEL || u == def::USAGE_TOP_LEVEL_OLD); + let tagged_top: Vec<&Obj> = comps.iter().copied().filter(is_top).collect(); + let pool = if tagged_top.is_empty() { comps } else { tagged_top }; + let unused: Vec<&Obj> = pool.iter().copied().filter(|c| c.mob_id(pid::MOB_ID).is_none_or(|id| !referenced.contains(&id))).collect(); + let top = if unused.is_empty() { pool } else { unused }; + for c in top { + r.open.extend(c.mob_id(pid::MOB_ID)); + let comp = r.composition(c); + r.open.clear(); + r.doc.compositions.push(comp); + } + if r.doc.compositions.is_empty() { + return Err(Error::Empty); + } + Ok(r.doc) +} + +fn collect_refs(o: &Obj, out: &mut HashSet) { + if o.class == cls::SOURCE_CLIP + && let Some(id) = o.mob_id(pid::SOURCE_ID) + { + out.insert(id); + } + for (_, v) in &o.props { + match v { + Value::Strong(c) => collect_refs(c, out), + Value::StrongVec(v) | Value::StrongSet(v, _) => v.iter().for_each(|c| collect_refs(c, out)), + _ => {} + } + } +} + +fn rate_of(o: &Obj, p: u16) -> Option<(i64, i64)> { + o.rational(p).filter(|r| r.0 > 0 && r.1 > 0) +} + +impl R<'_> { + fn composition(&mut self, c: &Obj) -> Composition { + let name = c.string(pid::MOB_NAME).unwrap_or_else(|| "Sequence".into()); + let slots = c.objs(pid::SLOTS); + let pic_rate = slots + .iter() + .filter(|s| s.class == cls::TIMELINE_MOB_SLOT) + .find(|s| s.strong(pid::SEGMENT).is_some_and(|g| matches!(data_kind(g), DataKind::Picture | DataKind::Timecode))) + .and_then(|s| rate_of(s, pid::EDIT_RATE)) + .or_else(|| slots.iter().find_map(|s| rate_of(s, pid::EDIT_RATE))) + .unwrap_or((25, 1)); + let rate = FrameRate::new(pic_rate.0, pic_rate.1); + let tags = tagged_values(c, pid::MOB_USER_COMMENTS); + let tag = |n: &str| tags.iter().find(|(k, _)| k == n).map(|(_, v)| v.clone()); + let (mut width, mut height) = tag("FilmCraft Frame Size") + .and_then(|s| s.split_once('x').and_then(|(a, b)| Some((a.trim().parse().ok()?, b.trim().parse().ok()?)))) + .unwrap_or((0, 0)); + let mut sample_rate = tag("FilmCraft Audio Sample Rate").and_then(|s| s.parse().ok()).unwrap_or(0u32); + let mut comp = Composition { + name, + aaf_mob_id: c.mob_id(pid::MOB_ID).map(|id| hex(&id)), + rate, + sample_rate: 48_000, + width: 1920, + height: 1080, + start_tc: 0, + drop: false, + tracks: Vec::new(), + markers: Vec::new(), + }; + let (mut nv, mut na) = (0, 0); + for s in slots { + let Some(seg) = s.strong(pid::SEGMENT) else { continue }; + if s.class == cls::EVENT_MOB_SLOT { + let er = rate_of(s, pid::EVENT_EDIT_RATE).unwrap_or(pic_rate); + comp.markers.extend(markers_of(seg, er)); + continue; + } + let er = rate_of(s, pid::EDIT_RATE).unwrap_or(pic_rate); + let origin = s.i64(pid::ORIGIN).unwrap_or(0); + match data_kind(seg) { + DataKind::Timecode => { + if let Some(tc) = find_class(seg, cls::TIMECODE) { + comp.start_tc = tc.i64(pid::TC_START).unwrap_or(0); + comp.drop = tc.u8(pid::TC_DROP).unwrap_or(0) != 0; + } + } + kind @ (DataKind::Picture | DataKind::Sound) => { + let ckind = if kind == DataKind::Picture { CKind::Picture } else { CKind::Sound }; + if ckind == CKind::Sound && sample_rate == 0 && er.1 == 1 && er.0 >= 8000 { + sample_rate = er.0 as u32; + } + // Premiere Pro writes every video track into one slot: a nested scope with a + // segment per track, the lowest track first. (A scope whose last segment + // refers to the others is an effect over layers: one track, as before.) + let layers: Vec<&Obj> = if ckind == CKind::Picture && seg.class == cls::NESTED_SCOPE && !refers_to_scope(seg, 0) { + seg.objs(pid::NESTED_SLOTS).iter().collect() + } else { + Vec::new() + }; + let layered = !layers.is_empty(); + let whole = units_to_ticks(len_of(seg), er.0, er.1); + for layer in if layered { layers } else { vec![seg] } { + let mut items = self.segment(layer, er, ckind, 0); + if layered { + fit(&mut items, whole); + } + if origin > 0 { + // material before the origin is not shown + trim_front(&mut items, units_to_ticks(origin, er.0, er.1)); + } + let number = s.u32(pid::PHYSICAL_TRACK_NUMBER).unwrap_or(0); + let name = s.string(pid::SLOT_NAME).unwrap_or_default(); + let channels = if ckind == CKind::Sound { + items + .iter() + .filter_map(|i| match i { + CItem::Clip(c) => self.doc.sources.get(c.source).map(|s| s.channels), + _ => None, + }) + .max() + .unwrap_or(1) + .min(6) + } else { + 0 + }; + let n = if ckind == CKind::Picture { + nv += 1; + nv + } else { + na += 1; + na + }; + comp.tracks.push(CTrack { kind: ckind, name, number: if number > 0 && !layered { number } else { n }, channels, items }); + } + } + DataKind::Other => self.report.info("a slot of an unsupported data kind was skipped"), + } + } + if width == 0 { + // no size in the file: that of the first picture this composition shows, else of any + let own = comp.tracks.iter().filter(|t| t.kind == CKind::Picture).flat_map(|t| &t.items).find_map(|i| match i { + CItem::Clip(c) => self.doc.sources.get(c.source).filter(|s| s.kind == CKind::Picture && s.width > 0 && s.nested.is_none()), + _ => None, + }); + let pic = own.or_else(|| self.doc.sources.iter().find(|s| s.kind == CKind::Picture && s.width > 0)); + (width, height) = pic.map_or((1920, 1080), |p| (p.width, p.height)); + } + comp.width = width; + comp.height = height; + if sample_rate > 0 { + comp.sample_rate = sample_rate; + } + comp + } + + /// Items of a segment (a sequence or a single component). + fn segment(&mut self, seg: &Obj, rate: (i64, i64), kind: CKind, depth: usize) -> Vec { + if depth > 32 { + self.report.warn("segments nested too deeply were skipped"); + return vec![CItem::Filler(units_to_ticks(len_of(seg), rate.0, rate.1))]; + } + if seg.class == cls::SEQUENCE { + let mut out = Vec::new(); + for c in seg.objs(pid::COMPONENTS) { + out.extend(self.component(c, rate, kind, depth + 1)); + } + return out; + } + self.component(seg, rate, kind, depth + 1) + } + + fn component(&mut self, c: &Obj, rate: (i64, i64), kind: CKind, depth: usize) -> Vec { + let len = units_to_ticks(len_of(c), rate.0, rate.1); + match c.class { + x if x == cls::FILLER => vec![CItem::Filler(len)], + x if x == cls::SOURCE_CLIP => vec![self.clip(c, rate, kind, None)], + x if x == cls::SEQUENCE => self.segment(c, rate, kind, depth), + x if x == cls::TRANSITION => { + let cut = units_to_ticks(c.i64(pid::CUT_POINT).unwrap_or(0), rate.0, rate.1); + let og = c.strong(pid::OPERATION_GROUP); + let effect = og + .and_then(|o| tagged_values(o, pid::COMPONENT_USER_COMMENTS).into_iter().find(|(k, _)| k == "FilmCraft Effect").map(|(_, v)| v)) + .unwrap_or_else(|| { + let op = og.and_then(|o| o.weak_key(pid::OPERATION)).and_then(|k| ::try_from(k).ok()); + match (kind, op) { + (CKind::Sound, _) => "constant_power".into(), + (_, Some(o)) if o == def::VIDEO_FADE_TO_BLACK => "dip_to_black".into(), + (_, Some(o)) if o == def::SMPTE_VIDEO_WIPE => "wipe".into(), + _ => "cross_dissolve".into(), + } + }); + vec![CItem::Transition(CTransition { len, cut: cut.clamp(Tick::ZERO, len), effect })] + } + x if x == cls::OPERATION_GROUP => { + let op = c.weak_key(pid::OPERATION).and_then(|k| ::try_from(k).ok()); + let inputs = c.objs(pid::INPUT_SEGMENTS); + let Some(input) = inputs.first() else { + self.report.info("an effect without input was imported as a gap"); + return vec![CItem::Filler(len)]; + }; + let gain = if op == Some(def::MONO_AUDIO_GAIN) { + self.gain(c, len, rate) + } else { + self.report.warn("effects other than audio gain are not imported (their first input is used)"); + None + }; + let mut items = self.segment(input, rate, kind, depth); + // the operation's length rules + fit(&mut items, len); + if let Some(g) = gain { + match items.as_mut_slice() { + [CItem::Clip(cl)] => cl.gain = Some(g), + _ => self.report.warn("audio gain around several clips was not imported"), + } + } + items + } + x if x == cls::SELECTOR => { + self.report.info("a selector was flattened to its selected input"); + match c.strong(pid::SELECTED) { + Some(s) => { + let mut items = self.segment(s, rate, kind, depth); + fit(&mut items, len); + items + } + None => vec![CItem::Filler(len)], + } + } + x if x == cls::NESTED_SCOPE => { + self.report.info("a nested scope was flattened to its final input"); + match c.objs(pid::NESTED_SLOTS).last() { + Some(s) => { + let mut items = self.segment(s, rate, kind, depth); + fit(&mut items, len); + items + } + None => vec![CItem::Filler(len)], + } + } + _ => { + self.report.info("an unsupported component was imported as a gap"); + vec![CItem::Filler(len)] + } + } + } + + fn gain(&mut self, og: &Obj, len: Tick, _rate: (i64, i64)) -> Option { + let p = og + .objs(pid::PARAMETERS) + .iter() + .find(|p| p.auid(pid::PARAMETER_DEFINITION) == Some(def::PARAM_AMPLITUDE)) + .or_else(|| og.objs(pid::PARAMETERS).first())?; + if p.class == cls::CONSTANT_VALUE { + return p.data(pid::CONSTANT_VALUE).and_then(indirect_f64).map(Gain::Constant); + } + if p.class == cls::VARYING_VALUE { + let linear = p.weak_key(pid::INTERPOLATION).and_then(|k| ::try_from(k).ok()) != Some(def::INTERP_CONSTANT); + let points: Vec<(Tick, f64)> = p + .objs(pid::POINT_LIST) + .iter() + .filter_map(|cp| { + let (n, d) = cp.rational(pid::CP_TIME).filter(|r| r.1 != 0)?; + let v = cp.data(pid::CP_VALUE).and_then(indirect_f64)?; + Some((Tick((len.0 as i128 * n as i128 / d as i128).clamp(-(1i128 << 56), 1i128 << 56) as i64), v)) + }) + .collect(); + return (!points.is_empty()).then_some(Gain::Varying { linear, points }); + } + None + } + + fn clip(&mut self, c: &Obj, rate: (i64, i64), kind: CKind, master_key: Option) -> CItem { + let len = units_to_ticks(len_of(c), rate.0, rate.1); + let tagged_name = tagged_values(c, pid::COMPONENT_USER_COMMENTS).into_iter().find(|(k, _)| k == "Clip Name").map(|(_, v)| v); + let (Some(id), Some(slot)) = (c.mob_id(pid::SOURCE_ID), c.u32(pid::SOURCE_MOB_SLOT_ID)) else { return CItem::Filler(len) }; + let name = tagged_name.or_else(|| self.mobs.get(&id).and_then(|mob| mob.string(pid::MOB_NAME))).unwrap_or_default(); + if id == [0; 32] { + return CItem::Filler(len); + } + if let Some(mob) = self.mobs.get(&id).copied().filter(|m| m.class == cls::COMPOSITION_MOB) { + return self.nest_clip(c, NestClip { mob, mob_id: id, slot_id: slot, rate, kind, name }); + } + let source_rate = self + .mobs + .get(&id) + .and_then(|mob| mob.objs(pid::SLOTS).iter().find(|s| s.u32(pid::SLOT_ID) == Some(slot))) + .and_then(|s| rate_of(s, pid::EDIT_RATE)) + .unwrap_or(rate); + let start = units_to_ticks(c.i64(pid::START_TIME).unwrap_or(0), source_rate.0, source_rate.1); + match self.resolve(id, slot, start, kind, master_key, 0) { + Some((source, t)) => CItem::Clip(CClip { len, source, start: t, gain: None, name }), + None => CItem::Filler(len), + } + } + + /// A source clip that points at a composition: a nested sequence (Premiere Pro writes its + /// nested sequences this way). The composition is read once, however many clips use it. + fn nest_clip(&mut self, c: &Obj, clip: NestClip<'_>) -> CItem { + let NestClip { mob, mob_id: id, slot_id, rate, kind, name } = clip; + let len = units_to_ticks(len_of(c), rate.0, rate.1); + let index = match self.nests.get(&id) { + Some(&i) => i, + None => { + if self.open.contains(&id) || self.open.len() >= MAX_NESTING { + self.report.warn("a composition nested in itself or nested too deeply was imported as a gap"); + return CItem::Filler(len); + } + self.open.push(id); + let comp = self.composition(mob); + self.open.pop(); + let i = self.doc.nested.len(); + self.doc.nested.push(comp); + self.nests.insert(id, i); + i + } + }; + // the start counts edit units of the slot the clip points at + let slot_rate = + mob.objs(pid::SLOTS).iter().find(|s| s.u32(pid::SLOT_ID) == Some(slot_id)).and_then(|s| rate_of(s, pid::EDIT_RATE)).unwrap_or(rate); + let start = units_to_ticks(c.i64(pid::START_TIME).unwrap_or(0), slot_rate.0, slot_rate.1); + let skey = (id, if kind == CKind::Picture { 0 } else { 1 }, "composition".to_string()); + let source = match self.sources.get(&skey) { + Some(&i) => i, + None => { + let Some(comp) = self.doc.nested.get(index) else { return CItem::Filler(len) }; + let length = comp + .tracks + .iter() + .map(|t| { + Tick(t.items.iter().fold(0i64, |a, i| { + if matches!(i, CItem::Transition(_)) { a.saturating_sub(i.len().0) } else { a.saturating_add(i.len().0) } + })) + }) + .max() + .unwrap_or(Tick::ZERO); + let channels = if kind == CKind::Sound { 2 } else { 0 }; + let s = Source { + key: format!("composition:{}", hex(&id)), + name: comp.name.clone(), + kind, + path: None, + channel: None, + channels, + file_channels: channels, + width: comp.width, + height: comp.height, + frame_rate: comp.rate, + sample_rate: comp.sample_rate, + bits: 16, + length, + offset: Tick::ZERO, + start_tc: None, + tc_rate: comp.rate, + embedded: None, + markers: Vec::new(), + nested: Some(index), + }; + let i = self.doc.sources.len(); + self.doc.sources.push(s); + self.sources.insert(skey, i); + i + } + }; + CItem::Clip(CClip { len, source, start, gain: None, name }) + } + + /// Follow a source reference to a file source mob: (source index, file time). + fn resolve(&mut self, id: MobId, slot_id: u32, start: Tick, kind: CKind, master_key: Option, depth: usize) -> Option<(usize, Tick)> { + if depth > 16 { + return None; + } + let Some(mob) = self.mobs.get(&id).copied() else { + self.report.warn("a clip references a mob that is not in the file (imported as a gap)"); + return None; + }; + let slot = mob.objs(pid::SLOTS).iter().find(|s| s.u32(pid::SLOT_ID) == Some(slot_id))?; + let rate = rate_of(slot, pid::EDIT_RATE).unwrap_or((25, 1)); + let seg = slot.strong(pid::SEGMENT)?; + if mob.class == cls::COMPOSITION_MOB { + self.report.warn("nested compositions are not supported (imported as gaps)"); + return None; + } + if mob.class == cls::MASTER_MOB { + let key = master_key.unwrap_or_else(|| hex(&id)); + let clip = first_clip(seg)?; + let next = clip.mob_id(pid::SOURCE_ID)?; + let next_slot = clip.u32(pid::SOURCE_MOB_SLOT_ID)?; + let source_rate = self + .mobs + .get(&next) + .and_then(|m| m.objs(pid::SLOTS).iter().find(|s| s.u32(pid::SLOT_ID) == Some(next_slot))) + .and_then(|s| rate_of(s, pid::EDIT_RATE)) + .unwrap_or(rate); + let inner = units_to_ticks(clip.i64(pid::START_TIME).unwrap_or(0), source_rate.0, source_rate.1); + if next == [0; 32] { + return None; + } + let markers = mob + .objs(pid::SLOTS) + .iter() + .filter(|s| s.class == cls::EVENT_MOB_SLOT) + .flat_map(|s| s.strong(pid::SEGMENT).map(|g| markers_of(g, rate_of(s, pid::EVENT_EDIT_RATE).unwrap_or(rate))).unwrap_or_default()) + .collect::>(); + let r = self.resolve(next, next_slot, start + inner, kind, Some(key), depth + 1)?; + let src = &mut self.doc.sources[r.0]; + if src.markers.is_empty() { + src.markers = markers; + } + if src.name.is_empty() + && let Some(n) = mob.string(pid::MOB_NAME) + { + src.name = n; + } + return Some(r); + } + // a source mob: file (has a file descriptor) or physical (tape / import) + let desc = mob.strong(pid::ESSENCE_DESCRIPTION); + let is_file = desc.is_some_and(|d| d.get(pid::SAMPLE_RATE).is_some() || d.get(pid::LOCATOR).is_some() || self.essence.contains_key(&id)); + if !is_file { + return None; + } + let key = master_key.unwrap_or_else(|| hex(&id)); + let skey = (id, slot_id, key.clone()); + if let Some(&i) = self.sources.get(&skey) { + return Some((i, start)); + } + let d = desc?; + let seg_kind = match data_kind(seg) { + DataKind::Picture => CKind::Picture, + DataKind::Sound => CKind::Sound, + _ => kind, + }; + let path = d.objs(pid::LOCATOR).iter().find_map(|l| l.string(pid::URL_STRING)).map(|u| locator_path(&u)); + let file_rate = rate_of(d, pid::SAMPLE_RATE).unwrap_or(rate); + let length = d + .i64(pid::FILE_LENGTH) + .map(|l| units_to_ticks(l, file_rate.0, file_rate.1)) + .unwrap_or_else(|| units_to_ticks(len_of(seg), rate.0, rate.1)); + let sound_slots = mob.objs(pid::SLOTS).iter().filter(|s| s.strong(pid::SEGMENT).is_some_and(|g| data_kind(g) == DataKind::Sound)).count(); + let file_channels = d.u32(pid::CHANNELS).unwrap_or(1).max(1); + let channel = (seg_kind == CKind::Sound && file_channels > 1 && sound_slots > 1) + .then(|| slot.u32(pid::PHYSICAL_TRACK_NUMBER).unwrap_or(slot_id).saturating_sub(1).min(file_channels - 1)); + let mut layout = d.u8(pid::FRAME_LAYOUT).unwrap_or(0); + if layout > 4 { + layout = 0; + } + let stored_h = d.u32(pid::STORED_HEIGHT).unwrap_or(0); + let fr = FrameRate::new(file_rate.0, file_rate.1); + // timecode from the physical source mob + let tc = first_clip(seg).and_then(|clip| { + let tid = clip.mob_id(pid::SOURCE_ID)?; + let tape = self.mobs.get(&tid)?; + let tslot = tape.objs(pid::SLOTS).iter().find_map(|s| { + let g = s.strong(pid::SEGMENT)?; + let t = find_class(g, cls::TIMECODE)?; + Some((t.i64(pid::TC_START).unwrap_or(0), t.u16(pid::TC_FPS).unwrap_or(25).max(1) as i64, rate_of(s, pid::EDIT_RATE))) + })?; + let off = units_to_ticks(clip.i64(pid::START_TIME).unwrap_or(0), rate.0, rate.1); + let tcr = tslot.2.map(|r| FrameRate::new(r.0, r.1)).unwrap_or_else(|| FrameRate::new(tslot.1, 1)); + Some((tslot.0 + tcr.frame_at(off), tcr)) + }); + let mut s = Source { + key, + name: mob.string(pid::MOB_NAME).unwrap_or_default(), + kind: seg_kind, + path, + channel, + channels: if channel.is_some() { 1 } else { file_channels }, + file_channels, + width: d.u32(pid::STORED_WIDTH).unwrap_or(0), + height: if matches!(layout, 1 | 3) { stored_h.saturating_mul(2) } else { stored_h }, + frame_rate: if seg_kind == CKind::Picture { fr } else { FrameRate::FPS_25 }, + sample_rate: d + .rational(pid::AUDIO_SAMPLING_RATE) + .filter(|r| r.1 > 0 && r.0 > 0) + .map(|r| (r.0 / r.1) as u32) + .unwrap_or(file_rate.0 as u32), + bits: d.u32(pid::QUANTIZATION_BITS).unwrap_or(16).clamp(8, 32) as u16, + length, + offset: Tick::ZERO, + start_tc: tc.map(|t| t.0), + tc_rate: tc.map(|t| t.1).unwrap_or(fr), + embedded: None, + markers: Vec::new(), + nested: None, + }; + if s.kind == CKind::Sound { + s.frame_rate = FrameRate::FPS_25; + if let Some(data) = self.essence.get(&id) { + s.embedded = Some(data.to_vec()); + // embedded essence may be a whole WAVE / AIFF file + if let Some((pcm, ch, sr, bits)) = crate::pcm::parse_wav(data) { + s.embedded = Some(pcm); + s.file_channels = ch as u32; + s.channels = if s.channel.is_some() { 1 } else { ch as u32 }; + s.sample_rate = sr; + s.bits = bits; + } + } + } + if s.kind == CKind::Picture && s.width == 0 { + s.width = 1920; + s.height = 1080; + } + let i = self.doc.sources.len(); + self.doc.sources.push(s); + self.sources.insert(skey, i); + Some((i, start)) + } +} + +/// Drop `t` from the front of a track's items (slot origin). +fn trim_front(items: &mut Vec, mut t: Tick) { + while t > Tick::ZERO && !items.is_empty() { + let l = items[0].len(); + if matches!(items[0], CItem::Transition(_)) { + items.remove(0); + continue; + } + if l <= t { + items.remove(0); + t -= l; + } else { + match &mut items[0] { + CItem::Filler(x) => *x -= t, + CItem::Clip(c) => { + c.len -= t; + c.start += t; + } + CItem::Transition(_) => {} + } + t = Tick::ZERO; + } + } +} + +/// Make the items exactly `len` long (an operation group / selector is as long as itself). +fn fit(items: &mut Vec, len: Tick) { + let total = Tick( + items.iter().fold(0i64, |a, i| if matches!(i, CItem::Transition(_)) { a.saturating_sub(i.len().0) } else { a.saturating_add(i.len().0) }), + ); + if total == len || items.is_empty() { + if items.is_empty() { + items.push(CItem::Filler(len)); + } + return; + } + if total < len { + items.push(CItem::Filler(len - total)); + return; + } + let mut excess = total - len; + while excess > Tick::ZERO { + match items.last_mut() { + Some(CItem::Filler(x)) | Some(CItem::Clip(CClip { len: x, .. })) if *x > excess => { + *x -= excess; + excess = Tick::ZERO; + } + Some(CItem::Transition(_)) => { + items.pop(); + } + Some(other) => { + excess -= other.len(); + items.pop(); + } + None => break, + } + } +} + +/// Whether anything inside `o` is a scope reference (a nested scope used as an effect's layers). +fn refers_to_scope(o: &Obj, depth: usize) -> bool { + if o.class == cls::SCOPE_REFERENCE { + return true; + } + if depth > 32 { + return false; + } + o.props.iter().any(|(_, v)| match v { + Value::Strong(c) => refers_to_scope(c, depth + 1), + Value::StrongVec(v) | Value::StrongSet(v, _) => v.iter().any(|c| refers_to_scope(c, depth + 1)), + _ => false, + }) +} + +fn first_clip(seg: &Obj) -> Option<&Obj> { + if seg.class == cls::SOURCE_CLIP { + return Some(seg); + } + if seg.class == cls::SEQUENCE { + return seg.objs(pid::COMPONENTS).iter().find_map(first_clip); + } + // essence group (choices 0x0501) / operation group inputs + seg.objs(0x0501).iter().find_map(first_clip).or_else(|| seg.objs(pid::INPUT_SEGMENTS).iter().find_map(first_clip)) +} + +fn find_class(seg: &Obj, class: Auid) -> Option<&Obj> { + if seg.class == class { + return Some(seg); + } + seg.objs(pid::COMPONENTS).iter().find_map(|c| find_class(c, class)) +} + +fn markers_of(seg: &Obj, rate: (i64, i64)) -> Vec { + let events: Vec<&Obj> = if seg.class == cls::SEQUENCE { seg.objs(pid::COMPONENTS).iter().collect() } else { vec![seg] }; + events + .into_iter() + .filter(|e| e.class == cls::COMMENT_MARKER || e.class == cls::DESCRIPTIVE_MARKER || e.get(pid::POSITION).is_some()) + .map(|e| { + let tags = tagged_values(e, pid::COMPONENT_USER_COMMENTS); + let tag = |n: &str| tags.iter().find(|(k, _)| k == n).map(|(_, v)| v.clone()); + let comment = e.string(pid::COMMENT).unwrap_or_default(); + let start = units_to_ticks(e.i64(pid::POSITION).unwrap_or(0), rate.0, rate.1); + CMarker { + start, + duration: units_to_ticks(e.i64(pid::LENGTH).unwrap_or(0).max(0), rate.0, rate.1), + name: tag("Name").unwrap_or_else(|| comment.clone()), + comment: tag("Comment").unwrap_or_else(|| if tags.is_empty() { String::new() } else { comment.clone() }), + color: tag("Color"), + } + }) + .collect() +} + +fn hex(b: &[u8]) -> String { + b.iter().map(|x| format!("{x:02x}")).collect() +} + +fn locator_path(url: &str) -> String { + if url.contains("://") { craft_timeline::path::file_url_to_path(url) } else { craft_timeline::path::decode_uri_path(url) } +} + +#[cfg(test)] +mod locator_tests { + use super::locator_path; + + #[test] + fn decodes_relative_locator_escapes_without_losing_remote_authorities() { + assert_eq!(locator_path("Audio%20Files/Di%C3%A1logo%20%231.wav"), "Audio Files/Diálogo #1.wav"); + assert_eq!(locator_path("file:///tmp/a%20b.wav"), "/tmp/a b.wav"); + assert_eq!(locator_path("file://server/share/a.wav"), "//server/share/a.wav"); + assert_eq!(locator_path("https://example.com/a%20b.wav"), "https://example.com/a%20b.wav"); + } +} diff --git a/crates/aaf/src/aaf/store.rs b/crates/aaf/src/aaf/store.rs new file mode 100644 index 000000000..69b14fcf2 --- /dev/null +++ b/crates/aaf/src/aaf/store.rs @@ -0,0 +1,539 @@ +//! AAF objects in structured storage (the AAF Low-Level Container Specification): every object +//! is a storage whose class id is the object's class AUID, holding a `properties` stream; strong +//! references are child storages, collections have an index stream, weak references name a key +//! in a target collection through the root's `referenced properties` table. +//! +//! `properties` stream (little-endian): +//! +//! ```text +//! u8 byte order (0x4C 'L') u8 format version (0x20) u16 entry count +//! entry count × { u16 pid, u16 stored form, u16 value length } the values, in entry order +//! ``` +//! +//! | stored form | value | +//! |---|---| +//! | 0x82 data | the property's bytes | +//! | 0x22 strong reference | UTF-16 name of the child storage | +//! | 0x32 strong reference vector | UTF-16 collection name; storages `name{key}`, stream `name index`: u32 count, u32 first free key, u32 last free key, count × u32 local key | +//! | 0x3A strong reference set | as a vector; the index adds u16 key pid, u8 key size, and each entry is u32 local key, u32 reference count, key bytes | +//! | 0x02 weak reference | u16 referenced-property tag, u16 key pid, u8 key size, key bytes | +//! | 0x12 / 0x1A weak reference vector / set | UTF-16 collection name; stream `name index`: u32 count, u16 tag, u16 key pid, u8 key size, count × key | +//! | 0x42 data stream | u8 byte order, UTF-16 name of the stream | +//! +//! `referenced properties` (root stream): u8 byte order, u16 path count, u32 pid count, then the +//! pids of each path (from the root object) terminated by a 0 pid. + +use craft_cfb::{CompoundFile, EntryKind, NodeId, Version, Writer}; + +pub(crate) type Auid = [u8; 16]; + +pub(crate) const SF_DATA: u16 = 0x82; +pub(crate) const SF_DATA_STREAM: u16 = 0x42; +pub(crate) const SF_STRONG: u16 = 0x22; +pub(crate) const SF_STRONG_VECTOR: u16 = 0x32; +pub(crate) const SF_STRONG_SET: u16 = 0x3A; +pub(crate) const SF_WEAK: u16 = 0x02; +pub(crate) const SF_WEAK_VECTOR: u16 = 0x12; +pub(crate) const SF_WEAK_SET: u16 = 0x1A; + +const BYTE_ORDER_LE: u8 = 0x4C; +const FORMAT_VERSION: u8 = 0x20; + +/// A property value. +#[derive(Clone, Debug, PartialEq)] +pub(crate) enum Value { + Data(Vec), + Strong(Box), + StrongVec(Vec), + /// Objects keyed by the data property `key_pid` of each. + StrongSet(Vec, u16), + /// (path of pids from the root to the target collection, key pid, key) + Weak(Vec, u16, Vec), + WeakVec(Vec, u16, Vec>), + Stream(Vec), +} + +/// An AAF object: its class and properties. +#[derive(Clone, Debug, PartialEq)] +pub(crate) struct Obj { + pub class: Auid, + pub props: Vec<(u16, Value)>, +} + +impl Obj { + pub fn new(class: Auid) -> Obj { + Obj { class, props: Vec::new() } + } + pub fn set(&mut self, pid: u16, v: Value) -> &mut Obj { + match self.props.iter_mut().find(|(p, _)| *p == pid) { + Some(slot) => slot.1 = v, + None => self.props.push((pid, v)), + } + self + } + pub fn with(mut self, pid: u16, v: Value) -> Obj { + self.set(pid, v); + self + } + pub fn data_prop(mut self, pid: u16, d: Vec) -> Obj { + self.set(pid, Value::Data(d)); + self + } + pub fn get(&self, pid: u16) -> Option<&Value> { + self.props.iter().find(|(p, _)| *p == pid).map(|(_, v)| v) + } + pub fn data(&self, pid: u16) -> Option<&[u8]> { + match self.get(pid)? { + Value::Data(d) => Some(d), + _ => None, + } + } + pub fn strong(&self, pid: u16) -> Option<&Obj> { + match self.get(pid)? { + Value::Strong(o) => Some(o), + _ => None, + } + } + /// Elements of a strong vector or set (empty when absent). + pub fn objs(&self, pid: u16) -> &[Obj] { + match self.get(pid) { + Some(Value::StrongVec(v)) | Some(Value::StrongSet(v, _)) => v, + _ => &[], + } + } + pub fn weak_key(&self, pid: u16) -> Option<&[u8]> { + match self.get(pid)? { + Value::Weak(_, _, k) => Some(k), + _ => None, + } + } + pub fn stream(&self, pid: u16) -> Option<&[u8]> { + match self.get(pid)? { + Value::Stream(d) => Some(d), + _ => None, + } + } + pub fn u8(&self, pid: u16) -> Option { + self.data(pid).and_then(|d| d.first().copied()) + } + pub fn u16(&self, pid: u16) -> Option { + self.data(pid).filter(|d| d.len() >= 2).map(|d| u16::from_le_bytes([d[0], d[1]])) + } + pub fn u32(&self, pid: u16) -> Option { + self.data(pid).filter(|d| d.len() >= 4).map(|d| u32::from_le_bytes([d[0], d[1], d[2], d[3]])) + } + pub fn i64(&self, pid: u16) -> Option { + let d = self.data(pid)?; + match d.len() { + 8.. => Some(i64::from_le_bytes(d[..8].try_into().ok()?)), + 4..=7 => Some(i32::from_le_bytes(d[..4].try_into().ok()?) as i64), + _ => None, + } + } + pub fn rational(&self, pid: u16) -> Option<(i64, i64)> { + self.data(pid).and_then(rational_of) + } + pub fn string(&self, pid: u16) -> Option { + self.data(pid).map(utf16_of) + } + pub fn auid(&self, pid: u16) -> Option { + self.data(pid).and_then(|d| d.get(..16)).and_then(|d| d.try_into().ok()) + } + pub fn mob_id(&self, pid: u16) -> Option<[u8; 32]> { + self.data(pid).and_then(|d| d.get(..32)).and_then(|d| d.try_into().ok()) + } +} + +pub(crate) fn rational_of(d: &[u8]) -> Option<(i64, i64)> { + (d.len() >= 8).then(|| (i32::from_le_bytes([d[0], d[1], d[2], d[3]]) as i64, i32::from_le_bytes([d[4], d[5], d[6], d[7]]) as i64)) +} + +pub(crate) fn rational(num: i64, den: i64) -> Vec { + let mut v = (num.clamp(i32::MIN as i64, i32::MAX as i64) as i32).to_le_bytes().to_vec(); + v.extend_from_slice(&(den.clamp(i32::MIN as i64, i32::MAX as i64) as i32).to_le_bytes()); + v +} + +/// UTF-16LE with a terminating NUL. +pub(crate) fn utf16z(s: &str) -> Vec { + let mut v: Vec = s.encode_utf16().flat_map(u16::to_le_bytes).collect(); + v.extend_from_slice(&[0, 0]); + v +} + +pub(crate) fn utf16_of(d: &[u8]) -> String { + let u: Vec = d.as_chunks::<2>().0.iter().map(|c| u16::from_le_bytes([c[0], c[1]])).take_while(|&c| c != 0).collect(); + String::from_utf16_lossy(&u) +} + +/// Short property names used to name storages and streams (any name is valid: readers follow +/// the names stored in the property values). +fn prop_name(pid: u16) -> &'static str { + match pid { + 0x0001 => "MetaDictionary", + 0x0002 => "Header", + 0x0003 => "ClassDefinitions", + 0x0004 => "TypeDefinitions", + 0x3B03 => "Content", + 0x3B04 => "Dictionary", + 0x3B06 => "IdentificationList", + 0x1901 => "Mobs", + 0x1902 => "EssenceData", + 0x2603 => "OperationDefinitions", + 0x2604 => "ParameterDefinitions", + 0x2605 => "DataDefinitions", + 0x2607 => "CodecDefinitions", + 0x2608 => "ContainerDefinitions", + 0x2609 => "InterpolationDefs", + 0x4403 => "Slots", + 0x4406 => "UserComments", + 0x4803 => "Segment", + 0x1001 => "Components", + 0x1801 => "OperationGroup", + 0x0B02 => "InputSegments", + 0x0B03 => "Parameters", + 0x4E02 => "PointList", + 0x4701 => "EssenceDescription", + 0x2F01 => "Locator", + 0x2702 => "Data", + 0x0204 => "ComponentComments", + 0x1E09 => "ParametersDefined", + _ => "Property", + } +} + +/// The key size of a strong reference set keyed by `key_pid`, for a set with no entry to take it +/// from: AUIDs (definitions) are 16 bytes, MobIDs 32. +fn set_key_size(key_pid: u16) -> usize { + match key_pid { + 0x0005 | 0x1B01 => 16, + 0x4401 | 0x2701 => 32, + _ => 0, + } +} + +fn storage_name(pid: u16) -> String { + let suffix = format!("-{pid:x}"); + let name: String = prop_name(pid).chars().take(22 - suffix.len()).collect(); + format!("{name}{suffix}") +} + +/// Errors while reading the object tree. +fn bad(s: impl Into) -> String { + s.into() +} + +// --------------------------------------------------------------------------------------------- +// Writing +// --------------------------------------------------------------------------------------------- + +struct W { + cfb: Writer, + paths: Vec>, +} + +/// Serialise `root` (the Root object: MetaDictionary 0x0001, Header 0x0002) into a compound file. +pub(crate) fn write(root: &Obj, version: Version) -> Result, String> { + let mut w = W { cfb: Writer::new(version), paths: Vec::new() }; + w.obj(Writer::ROOT, root)?; + let mut rp = vec![BYTE_ORDER_LE]; + rp.extend_from_slice(&(w.paths.len() as u16).to_le_bytes()); + let n: usize = w.paths.iter().map(|p| p.len() + 1).sum(); + rp.extend_from_slice(&(n as u32).to_le_bytes()); + for p in &w.paths { + for pid in p { + rp.extend_from_slice(&pid.to_le_bytes()); + } + rp.extend_from_slice(&0u16.to_le_bytes()); + } + w.cfb.stream(Writer::ROOT, "referenced properties", rp).map_err(|e| e.to_string())?; + Ok(w.cfb.finish()) +} + +impl W { + fn tag(&mut self, path: &[u16]) -> u16 { + match self.paths.iter().position(|p| p == path) { + Some(i) => i as u16, + None => { + self.paths.push(path.to_vec()); + (self.paths.len() - 1) as u16 + } + } + } + + fn obj(&mut self, node: NodeId, o: &Obj) -> Result<(), String> { + self.cfb.set_clsid(node, o.class); + let mut entries: Vec<(u16, u16, Vec)> = Vec::new(); + for (pid, v) in &o.props { + let pid = *pid; + let (sf, value) = match v { + Value::Data(d) => (SF_DATA, d.clone()), + Value::Strong(child) => { + let name = storage_name(pid); + let s = self.cfb.storage(node, &name, child.class).map_err(|e| e.to_string())?; + self.obj(s, child)?; + (SF_STRONG, utf16z(&name)) + } + Value::StrongVec(items) | Value::StrongSet(items, _) => { + let name = storage_name(pid); + let mut index = Vec::new(); + index.extend_from_slice(&(items.len() as u32).to_le_bytes()); + index.extend_from_slice(&(items.len() as u32).to_le_bytes()); // first free key + index.extend_from_slice(&u32::MAX.to_le_bytes()); // last free key + let set_key = if let Value::StrongSet(_, k) = v { Some(*k) } else { None }; + let key_size = set_key.map(|k| items.first().and_then(|i| i.data(k)).map_or_else(|| set_key_size(k), <[u8]>::len)).unwrap_or(0); + if let Some(k) = set_key { + index.extend_from_slice(&k.to_le_bytes()); + index.push(key_size as u8); + } + for (i, item) in items.iter().enumerate() { + let s = self.cfb.storage(node, &format!("{name}{{{i:x}}}"), item.class).map_err(|e| e.to_string())?; + self.obj(s, item)?; + index.extend_from_slice(&(i as u32).to_le_bytes()); + if let Some(k) = set_key { + index.extend_from_slice(&1u32.to_le_bytes()); + let mut key = item.data(k).unwrap_or(&[]).to_vec(); + key.resize(key_size, 0); + index.extend_from_slice(&key); + } + } + self.cfb.stream(node, &format!("{name} index"), index).map_err(|e| e.to_string())?; + (if set_key.is_some() { SF_STRONG_SET } else { SF_STRONG_VECTOR }, utf16z(&name)) + } + Value::Weak(path, key_pid, key) => { + let mut d = self.tag(path).to_le_bytes().to_vec(); + d.extend_from_slice(&key_pid.to_le_bytes()); + d.push(key.len() as u8); + d.extend_from_slice(key); + (SF_WEAK, d) + } + Value::WeakVec(path, key_pid, keys) => { + let name = storage_name(pid); + let tag = self.tag(path); + let size = keys.first().map_or(0, Vec::len); + let mut index = (keys.len() as u32).to_le_bytes().to_vec(); + index.extend_from_slice(&tag.to_le_bytes()); + index.extend_from_slice(&key_pid.to_le_bytes()); + index.push(size as u8); + for k in keys { + let mut k = k.clone(); + k.resize(size, 0); + index.extend_from_slice(&k); + } + self.cfb.stream(node, &format!("{name} index"), index).map_err(|e| e.to_string())?; + (SF_WEAK_VECTOR, utf16z(&name)) + } + Value::Stream(data) => { + let name = storage_name(pid); + self.cfb.stream(node, &name, data.clone()).map_err(|e| e.to_string())?; + let mut d = vec![BYTE_ORDER_LE]; + d.extend_from_slice(&utf16z(&name)); + (SF_DATA_STREAM, d) + } + }; + if value.len() > u16::MAX as usize { + return Err(format!("property {pid:#06x} is {} bytes (the limit is 65535)", value.len())); + } + entries.push((pid, sf, value)); + } + let mut props = vec![BYTE_ORDER_LE, FORMAT_VERSION]; + props.extend_from_slice(&(entries.len() as u16).to_le_bytes()); + for (pid, sf, v) in &entries { + props.extend_from_slice(&pid.to_le_bytes()); + props.extend_from_slice(&sf.to_le_bytes()); + props.extend_from_slice(&(v.len() as u16).to_le_bytes()); + } + for (_, _, v) in &entries { + props.extend_from_slice(v); + } + self.cfb.stream(node, "properties", props).map_err(|e| e.to_string())?; + Ok(()) + } +} + +// --------------------------------------------------------------------------------------------- +// Reading +// --------------------------------------------------------------------------------------------- + +struct R<'a> { + cf: CompoundFile<'a>, + paths: Vec>, + objects: usize, + materialized_stream_bytes: usize, + /// Storages already read: a storage is owned by one parent, so a second strong reference to it + /// (which would rebuild its whole subtree again) is refused. + owned: std::collections::HashSet, + /// Bytes of weak-reference target paths copied into the tree so far. + path_bytes: usize, +} + +const MAX_DEPTH: usize = 200; +const MAX_OBJECTS: usize = 2_000_000; +const MAX_MATERIALIZED_STREAM_BYTES: usize = 256 << 20; +/// Each weak reference carries its own copy of its target path (real paths are a handful of +/// property ids); the copies together may not exceed this. +const MAX_PATH_BYTES: usize = 64 << 20; + +/// Parse the object tree of an AAF compound file (the root object). +pub(crate) fn read(bytes: &[u8]) -> Result { + let cf = CompoundFile::open(bytes).map_err(|e| e.to_string())?; + cf.validate_root_chain().map_err(|e| e.to_string())?; + let mut paths = Vec::new(); + if let Ok(rp) = cf.read_path("referenced properties") + && rp.len() >= 7 + { + let count = u16::from_le_bytes([rp[1], rp[2]]) as usize; + let mut cur = Vec::new(); + for c in rp[7..].as_chunks::<2>().0 { + let pid = u16::from_le_bytes([c[0], c[1]]); + if pid == 0 { + paths.push(std::mem::take(&mut cur)); + if paths.len() == count { + break; + } + } else { + cur.push(pid); + } + } + } + let mut r = R { cf, paths, objects: 0, materialized_stream_bytes: 0, owned: Default::default(), path_bytes: 0 }; + r.obj(0, 0) +} + +fn rd_u16(b: &[u8], at: usize) -> Option { + b.get(at..at + 2).map(|s| u16::from_le_bytes([s[0], s[1]])) +} +fn rd_u32(b: &[u8], at: usize) -> Option { + b.get(at..at + 4).map(|s| u32::from_le_bytes([s[0], s[1], s[2], s[3]])) +} + +impl R<'_> { + fn child(&self, parent: usize, name: &str) -> Result { + self.cf.child(parent, name).ok_or_else(|| bad(format!("missing storage or stream \"{name}\""))) + } + + fn stream(&mut self, parent: usize, name: &str) -> Result, String> { + let id = self.child(parent, name)?; + let data = self.cf.read(id).map_err(|e| e.to_string())?; + self.materialized_stream_bytes = self + .materialized_stream_bytes + .checked_add(data.len()) + .filter(|&n| n <= MAX_MATERIALIZED_STREAM_BYTES) + .ok_or_else(|| bad("AAF materialized stream data exceeds the memory limit"))?; + Ok(data) + } + + /// A copy of weak-reference path `tag`, counted against [`MAX_PATH_BYTES`]. + fn path(&mut self, tag: u16) -> Result, String> { + let path = self.paths.get(tag as usize).cloned().unwrap_or_default(); + self.path_bytes = self.path_bytes.saturating_add(path.len() * 2); + if self.path_bytes > MAX_PATH_BYTES { + return Err(bad("weak reference paths exceed the memory limit")); + } + Ok(path) + } + + fn obj(&mut self, entry: usize, depth: usize) -> Result { + if depth > MAX_DEPTH { + return Err(bad("objects nested too deeply")); + } + if !self.owned.insert(entry) { + return Err(bad("a storage is owned by more than one reference")); + } + self.objects += 1; + if self.objects > MAX_OBJECTS { + return Err(bad("too many objects")); + } + let e = self.cf.entry(entry).ok_or_else(|| bad("bad directory entry"))?; + if !matches!(e.kind, EntryKind::Root | EntryKind::Storage) { + return Err(bad(format!("\"{}\" is not a storage", e.name))); + } + let mut o = Obj::new(e.clsid); + let props = self.stream(entry, "properties")?; + if props.len() < 4 { + return Err(bad("short properties stream")); + } + if props[0] != BYTE_ORDER_LE { + return Err(bad("big-endian AAF files are not supported")); + } + let n = rd_u16(&props, 2).unwrap_or(0) as usize; + let mut at = 4 + n * 6; + if at > props.len() { + return Err(bad("truncated property index")); + } + for i in 0..n { + let (Some(pid), Some(sf), Some(len)) = (rd_u16(&props, 4 + i * 6), rd_u16(&props, 6 + i * 6), rd_u16(&props, 8 + i * 6)) else { + return Err(bad("truncated property index")); + }; + if o.props.iter().any(|(previous, _)| *previous == pid) { + return Err(bad("duplicate property id")); + } + let v = props.get(at..at + len as usize).ok_or_else(|| bad("truncated property value"))?; + at += len as usize; + let value = match sf { + SF_STRONG => { + let c = self.child(entry, &utf16_of(v))?; + Value::Strong(Box::new(self.obj(c, depth + 1)?)) + } + SF_STRONG_VECTOR | SF_STRONG_SET => { + let name = utf16_of(v); + let idx = self.stream(entry, &format!("{name} index"))?; + let count = rd_u32(&idx, 0).ok_or_else(|| bad("short collection index"))? as usize; + let mut items = Vec::new(); + if sf == SF_STRONG_VECTOR { + for k in 0..count { + let key = rd_u32(&idx, 12 + k * 4).ok_or_else(|| bad("short vector index"))?; + let c = self.child(entry, &format!("{name}{{{key:x}}}"))?; + items.push(self.obj(c, depth + 1)?); + } + Value::StrongVec(items) + } else { + let key_pid = rd_u16(&idx, 12).ok_or_else(|| bad("short set index"))?; + let key_size = *idx.get(14).ok_or_else(|| bad("short set index"))? as usize; + let stride = 8 + key_size; + for k in 0..count { + let key = rd_u32(&idx, 15 + k * stride).ok_or_else(|| bad("short set index"))?; + let c = self.child(entry, &format!("{name}{{{key:x}}}"))?; + items.push(self.obj(c, depth + 1)?); + } + Value::StrongSet(items, key_pid) + } + } + SF_WEAK => { + let (Some(tag), Some(key_pid), Some(&size)) = (rd_u16(v, 0), rd_u16(v, 2), v.get(4)) else { + return Err(bad("short weak reference")); + }; + let key = v.get(5..5 + size as usize).ok_or_else(|| bad("short weak reference"))?.to_vec(); + Value::Weak(self.path(tag)?, key_pid, key) + } + SF_WEAK_VECTOR | SF_WEAK_SET => { + let name = utf16_of(v); + let idx = self.stream(entry, &format!("{name} index"))?; + let (Some(count), Some(tag), Some(key_pid), Some(&size)) = (rd_u32(&idx, 0), rd_u16(&idx, 4), rd_u16(&idx, 6), idx.get(8)) else { + return Err(bad("short weak collection index")); + }; + let size = size as usize; + if count > 0 && size == 0 { + return Err(bad("zero-size weak collection key")); + } + // every key must lie in the index, so its length (not the count) bounds the loop + if (count as usize).checked_mul(size).and_then(|n| n.checked_add(9)).is_none_or(|end| end > idx.len()) { + return Err(bad("short weak collection index")); + } + let mut keys = Vec::new(); + for k in 0..count as usize { + keys.push(idx.get(9 + k * size..9 + (k + 1) * size).ok_or_else(|| bad("short weak collection index"))?.to_vec()); + } + Value::WeakVec(self.path(tag)?, key_pid, keys) + } + SF_DATA_STREAM => { + let name = utf16_of(v.get(1..).unwrap_or(&[])); + Value::Stream(self.stream(entry, &name)?) + } + _ => Value::Data(v.to_vec()), + }; + o.props.push((pid, value)); + } + Ok(o) + } +} diff --git a/crates/aaf/src/aaf/tests.rs b/crates/aaf/src/aaf/tests.rs new file mode 100644 index 000000000..3e7794471 --- /dev/null +++ b/crates/aaf/src/aaf/tests.rs @@ -0,0 +1,559 @@ +//! Structural checks of written AAF files against the required properties and rules of the AAF +//! Object Specification v1.1 and the Edit Protocol, read back through the compound file reader. + +use std::collections::HashSet; + +use craft_timeline::time::FrameRate; + +use super::ids::{self, cls, ddef, def, path, pid}; +use super::store::{self, Obj, Value}; +use super::*; +use crate::model::{CItem, CKind}; +use crate::testdoc::{IDENTITY, clip, composition, picture_and_sound_cut, source, track}; + +fn document() -> Document { + // two 48-frame clips from source frames 10 and 200, a 12-frame transition + picture_and_sound_cut(FrameRate::FPS_24, 48, 12, (10, 200)) +} + +fn written(doc: &Document, small_sectors: bool) -> Vec { + let mut report = Report::default(); + let bytes = write(doc, &WriteOptions { identity: IDENTITY, small_sectors }, &mut report).unwrap(); + assert!(!report.has_warnings(), "{report}"); + bytes +} + +fn read_clean(bytes: &[u8]) -> Document { + let mut report = Report::default(); + let doc = read(bytes, &mut report).unwrap(); + assert!(!report.has_warnings(), "{report}"); + doc +} + +fn walk<'a>(o: &'a Obj, out: &mut Vec<&'a Obj>) { + out.push(o); + for (_, v) in &o.props { + match v { + Value::Strong(c) => walk(c, out), + Value::StrongVec(v) | Value::StrongSet(v, _) => v.iter().for_each(|c| walk(c, out)), + _ => {} + } + } +} + +fn keys(dict: &Obj, p: u16) -> HashSet> { + dict.objs(p).iter().filter_map(|d| d.data(pid::IDENTIFICATION).map(<[u8]>::to_vec)).collect() +} + +/// filmcraft#323: readers that load the meta-dictionary (pyaaf2) need its ClassDefinitions and +/// TypeDefinitions sets. They are empty: everything written uses the baseline classes and types +/// those readers already know. +#[test] +fn the_meta_dictionary_has_its_class_and_type_definition_sets() { + for small in [false, true] { + let bytes = written(&document(), small); + let cf = craft_cfb::CompoundFile::open(&bytes).unwrap(); + assert_eq!(cf.entries[cf.find("MetaDictionary-1").unwrap()].clsid, ids::META_DICTIONARY); + for name in ["ClassDefinitions-3", "TypeDefinitions-4"] { + // u32 count, u32 first free key, u32 last free key, u16 key pid, u8 key size + let index = cf.read_path(&format!("MetaDictionary-1/{name} index")).unwrap_or_else(|e| panic!("{name}: {e}")); + assert_eq!(index.len(), 15, "{name}: an empty set"); + assert_eq!(index[0..4], 0u32.to_le_bytes(), "{name}: no entries"); + assert_eq!(u16::from_le_bytes([index[12], index[13]]), pid::META_IDENTIFICATION, "{name}: keyed by the definition's AUID"); + assert_eq!(index[14], 16, "{name}: 16-byte keys"); + } + let root = store::read(&bytes).unwrap(); + let meta = root.strong(pid::ROOT_META_DICTIONARY).unwrap(); + for set in [pid::META_CLASS_DEFINITIONS, pid::META_TYPE_DEFINITIONS] { + assert!(matches!(meta.get(set), Some(Value::StrongSet(items, k)) if items.is_empty() && *k == pid::META_IDENTIFICATION), "{set:#06x}"); + } + } +} + +#[test] +fn written_files_have_the_required_structure() { + for small in [false, true] { + let bytes = written(&document(), small); + assert_written_file(&bytes, small); + } +} + +/// The top-level composition is tagged `Usage_TopLevel`, which the SMPTE Labels register gives as +/// urn:smpte:ul:060e2b34.04010101.0d010102.01010700, stored as the AUID +/// {0d010102-0101-0700-060e-2b3404010101}. Readers that look for it (LibAAF) find no sequence +/// without it. +#[test] +fn the_top_level_composition_has_the_registered_usage_code() { + let bytes = written(&document(), false); + let root = store::read(&bytes).unwrap(); + let content = root.strong(pid::ROOT_HEADER).unwrap().strong(pid::CONTENT).unwrap(); + let comp = content.objs(pid::MOBS).iter().find(|m| m.class == cls::COMPOSITION_MOB).unwrap(); + let usage = [0x02, 0x01, 0x01, 0x0D, 0x01, 0x01, 0x00, 0x07, 0x06, 0x0E, 0x2B, 0x34, 0x04, 0x01, 0x01, 0x01]; + assert_eq!(comp.data(pid::USAGE_CODE), Some(&usage[..])); +} + +/// Files from FilmCraft 0.16 and earlier tag the top-level composition with the unregistered label +/// 060e2b34.04010105.0d011201.02030000. They still import: the composition no other one uses is +/// the edit. +#[test] +fn files_with_the_old_usage_code_still_import() { + let bytes = written(&document(), false); + let mut root = store::read(&bytes).unwrap(); + let content = strong_mut(strong_mut(&mut root, pid::ROOT_HEADER), pid::CONTENT); + for mob in objs_mut(content, pid::MOBS).iter_mut().filter(|m| m.class == cls::COMPOSITION_MOB) { + mob.set(pid::USAGE_CODE, Value::Data(def::USAGE_TOP_LEVEL_OLD.to_vec())); + } + let old_file = store::write(&root, craft_cfb::Version::V4).unwrap(); + let got = read_clean(&old_file); + assert_eq!(got.compositions.len(), 1); + assert_eq!(got, read_clean(&bytes)); +} + +/// A file that holds one edit tagged with each label (a tool merged a composition from an older +/// file into a newer one) imports both edits. +#[test] +fn edits_tagged_with_either_usage_code_both_import() { + let bytes = written(&document(), false); + let mut root = store::read(&bytes).unwrap(); + let content = strong_mut(strong_mut(&mut root, pid::ROOT_HEADER), pid::CONTENT); + let mobs = objs_mut(content, pid::MOBS); + let mut old = mobs.iter().find(|m| m.class == cls::COMPOSITION_MOB).unwrap().clone(); + let mut id = old.mob_id(pid::MOB_ID).unwrap(); + id[31] ^= 0xFF; + old.set(pid::MOB_ID, Value::Data(id.to_vec())); + old.set(pid::MOB_NAME, Value::Data(store::utf16z("Old"))); + old.set(pid::USAGE_CODE, Value::Data(def::USAGE_TOP_LEVEL_OLD.to_vec())); + mobs.push(old); + let mixed = store::write(&root, craft_cfb::Version::V4).unwrap(); + let document = read_clean(&mixed); + let mut ids: Vec<_> = document.compositions.iter().map(|c| c.aaf_mob_id.as_deref().unwrap()).collect(); + assert_eq!(ids.len(), 2); + assert!(ids.iter().all(|id| id.len() == 64 && id.bytes().all(|b| b.is_ascii_hexdigit() && !b.is_ascii_uppercase()))); + ids.sort_unstable(); + ids.dedup(); + assert_eq!(ids.len(), 2, "each composition keeps its own MobID"); + let mut names: Vec = document.compositions.into_iter().map(|c| c.name).collect(); + names.sort(); + assert_eq!(names, ["Old", "S"]); +} + +fn assert_written_file(bytes: &[u8], small: bool) { + assert_compound_file(bytes, small); + let root = store::read(bytes).unwrap(); + assert!(root.strong(pid::ROOT_META_DICTIONARY).is_some()); + let header = root.strong(pid::ROOT_HEADER).unwrap(); + let content = assert_header(header); + let dict = header.strong(pid::DICTIONARY).unwrap(); + let definitions = Definitions { + data: keys(dict, pid::DATA_DEFINITIONS), + operations: keys(dict, pid::OPERATION_DEFINITIONS), + interpolation: keys(dict, pid::INTERPOLATION_DEFINITIONS), + containers: keys(dict, pid::CONTAINER_DEFINITIONS), + parameters: keys(dict, pid::PARAMETER_DEFINITIONS), + }; + let mobs = content.objs(pid::MOBS); + let comp = assert_mob_set(content, mobs); + for mob in mobs { + assert_mob(mob, mobs, &definitions); + } + assert_composition(comp); +} + +fn assert_compound_file(bytes: &[u8], small: bool) { + let cf = craft_cfb::CompoundFile::open(bytes).unwrap(); + assert_eq!(cf.version, if small { 3 } else { 4 }); + assert_eq!(cf.root().clsid, ids::ROOT); + let references = cf.read_path("referenced properties").unwrap(); + let pids: Vec = references[7..].as_chunks::<2>().0.iter().map(|c| u16::from_le_bytes([c[0], c[1]])).collect(); + assert!(pids.windows(3).any(|w| w == path::DATA_DEFS)); + let header = cf.find("Header-2").unwrap(); + assert_eq!(cf.entries[header].clsid, cls::HEADER); + assert!(cf.read_path("Header-2/properties").unwrap().starts_with(&[0x4C, 0x20])); +} + +fn assert_header(header: &Obj) -> &Obj { + for req in [pid::BYTE_ORDER, pid::LAST_MODIFIED, pid::CONTENT, pid::DICTIONARY, pid::VERSION, pid::IDENTIFICATION_LIST, pid::OBJECT_MODEL_VERSION] + { + assert!(header.get(req).is_some(), "Header property {req:#06x}"); + } + assert_eq!(header.auid(pid::OPERATIONAL_PATTERN), Some(def::OP_EDIT_PROTOCOL)); + let ident = &header.objs(pid::IDENTIFICATION_LIST)[0]; + for req in [pid::COMPANY_NAME, pid::PRODUCT_NAME, pid::PRODUCT_VERSION_STRING, pid::PRODUCT_ID, pid::DATE, pid::GENERATION_AUID] { + assert!(ident.get(req).is_some(), "Identification property {req:#06x}"); + } + header.strong(pid::CONTENT).unwrap() +} + +struct Definitions { + data: HashSet>, + operations: HashSet>, + interpolation: HashSet>, + containers: HashSet>, + parameters: HashSet>, +} + +fn assert_mob_set<'a>(content: &Obj, mobs: &'a [Obj]) -> &'a Obj { + let mob_ids: Vec<[u8; 32]> = mobs.iter().map(|m| m.mob_id(pid::MOB_ID).unwrap()).collect(); + assert_eq!(mob_ids.iter().collect::>().len(), mob_ids.len(), "unique mob ids"); + assert!(matches!(content.get(pid::MOBS), Some(Value::StrongSet(_, k)) if *k == pid::MOB_ID)); + let compositions: Vec<&Obj> = mobs.iter().filter(|m| m.class == cls::COMPOSITION_MOB).collect(); + assert_eq!(compositions.len(), 1); + assert_eq!(compositions[0].auid(pid::USAGE_CODE), Some(def::USAGE_TOP_LEVEL)); + assert_eq!(mobs.iter().filter(|m| m.class == cls::MASTER_MOB).count(), 1); + assert_eq!(mobs.iter().filter(|m| m.class == cls::SOURCE_MOB).count(), 3, "picture file, sound file, tape"); + compositions[0] +} + +fn assert_mob(mob: &Obj, mobs: &[Obj], definitions: &Definitions) { + for req in [pid::MOB_ID, pid::MOB_NAME, pid::SLOTS, pid::MOB_LAST_MODIFIED, pid::MOB_CREATION_TIME] { + assert!(mob.get(req).is_some(), "Mob property {req:#06x}"); + } + assert_source_descriptor(mob, &definitions.containers); + for slot in mob.objs(pid::SLOTS) { + assert!(slot.get(pid::SLOT_ID).is_some() && slot.get(pid::SEGMENT).is_some()); + if slot.class == cls::TIMELINE_MOB_SLOT { + assert!(slot.rational(pid::EDIT_RATE).is_some_and(|r| r.0 > 0 && r.1 > 0)); + assert!(slot.get(pid::ORIGIN).is_some()); + } + } + let mut all = Vec::new(); + walk(mob, &mut all); + for component in all { + assert_component(component, mobs, definitions); + } +} + +fn assert_source_descriptor(mob: &Obj, containers: &HashSet>) { + if mob.class != cls::SOURCE_MOB { + return; + } + let descriptor = mob.strong(pid::ESSENCE_DESCRIPTION).expect("SourceMob::EssenceDescription"); + if descriptor.class != cls::TAPE_DESCRIPTOR { + for req in [pid::SAMPLE_RATE, pid::FILE_LENGTH, pid::CONTAINER_FORMAT] { + assert!(descriptor.get(req).is_some(), "FileDescriptor property {req:#06x}"); + } + assert!(containers.contains(descriptor.weak_key(pid::CONTAINER_FORMAT).unwrap())); + let url = descriptor.objs(pid::LOCATOR)[0].string(pid::URL_STRING).unwrap(); + assert_eq!(url, "file:///m/a.mov"); + } + if descriptor.class == cls::PCM_DESCRIPTOR { + assert_eq!(descriptor.u32(pid::CHANNELS), Some(2)); + assert_eq!(descriptor.u32(pid::QUANTIZATION_BITS), Some(24)); + assert_eq!(descriptor.u16(pid::BLOCK_ALIGN), Some(6)); + } +} + +fn assert_component(o: &Obj, mobs: &[Obj], definitions: &Definitions) { + if is_component(o) { + let dd = o.weak_key(pid::DATA_DEFINITION).expect("Component::DataDefinition"); + assert!(definitions.data.contains(dd), "data definition in the dictionary"); + let event_seq = o.class == cls::SEQUENCE && dd == ddef::DESCRIPTIVE_METADATA; + assert!(event_seq || o.get(pid::LENGTH).is_some(), "Component::Length"); + } + if o.class == cls::SOURCE_CLIP { + assert_source_clip(o, mobs); + } else if o.class == cls::OPERATION_GROUP { + assert_operation_group(o, definitions); + } else if o.class == cls::SEQUENCE && o.get(pid::LENGTH).is_some() { + assert_sequence_length(o); + } +} + +fn is_component(o: &Obj) -> bool { + [cls::FILLER, cls::SOURCE_CLIP, cls::SEQUENCE, cls::TRANSITION, cls::OPERATION_GROUP, cls::TIMECODE, cls::COMMENT_MARKER].contains(&o.class) +} + +fn assert_source_clip(clip: &Obj, mobs: &[Obj]) { + let id = clip.mob_id(pid::SOURCE_ID).unwrap(); + let slot = clip.u32(pid::SOURCE_MOB_SLOT_ID).unwrap(); + assert!(clip.get(pid::START_TIME).is_some()); + if id != [0; 32] { + let target = mobs.iter().find(|m| m.mob_id(pid::MOB_ID) == Some(id)).expect("source clip target in the file"); + assert!(target.objs(pid::SLOTS).iter().any(|s| s.u32(pid::SLOT_ID) == Some(slot)), "target slot exists"); + } +} + +fn assert_operation_group(group: &Obj, definitions: &Definitions) { + assert!(definitions.operations.contains(group.weak_key(pid::OPERATION).unwrap())); + for parameter in group.objs(pid::PARAMETERS) { + assert!(definitions.parameters.contains(parameter.auid(pid::PARAMETER_DEFINITION).unwrap().as_slice())); + if parameter.class == cls::VARYING_VALUE { + assert!(definitions.interpolation.contains(parameter.weak_key(pid::INTERPOLATION).unwrap())); + assert!(!parameter.objs(pid::POINT_LIST).is_empty()); + } + } +} + +fn assert_sequence_length(sequence: &Obj) { + let components = sequence.objs(pid::COMPONENTS); + let sum = components + .iter() + .enumerate() + .map(|(i, component)| { + let len = component.i64(pid::LENGTH).unwrap(); + if component.class == cls::TRANSITION { + assert!(i > 0 && i + 1 < components.len(), "transition at a sequence end"); + assert!(components[i - 1].class != cls::TRANSITION && components[i + 1].class != cls::TRANSITION); + assert!(components[i - 1].i64(pid::LENGTH).unwrap() >= len && components[i + 1].i64(pid::LENGTH).unwrap() >= len); + let cut = component.i64(pid::CUT_POINT).unwrap(); + assert!((0..=len).contains(&cut)); + assert!(component.strong(pid::OPERATION_GROUP).is_some()); + -len + } else { + len + } + }) + .sum::(); + assert_eq!(sum, sequence.i64(pid::LENGTH).unwrap(), "sequence length = segments − transitions"); +} + +fn assert_composition(comp: &Obj) { + let slots = comp.objs(pid::SLOTS); + let tc = slots[0].strong(pid::SEGMENT).unwrap(); + assert_eq!(tc.class, cls::TIMECODE); + assert_eq!(tc.u16(pid::TC_FPS), Some(24)); + let video = slots[1].strong(pid::SEGMENT).unwrap().objs(pid::COMPONENTS); + assert_eq!(video.iter().map(|c| c.class).collect::>(), vec![cls::SOURCE_CLIP, cls::TRANSITION, cls::SOURCE_CLIP]); + assert_eq!(video[0].i64(pid::LENGTH), Some(54), "outgoing clip extends to the transition end"); + assert_eq!(video[2].i64(pid::LENGTH), Some(54), "incoming clip starts at the transition start"); + assert_eq!(video[2].i64(pid::START_TIME), Some(194)); + assert_eq!(video[1].i64(pid::CUT_POINT), Some(6)); + assert_eq!(video[1].strong(pid::OPERATION_GROUP).unwrap().weak_key(pid::OPERATION), Some(&def::VIDEO_DISSOLVE[..])); + assert_audio_composition_slot(&slots[2]); +} + +fn assert_audio_composition_slot(slot: &Obj) { + let audio = slot.strong(pid::SEGMENT).unwrap().objs(pid::COMPONENTS); + assert_eq!(slot.rational(pid::EDIT_RATE), Some((48_000, 1))); + assert_eq!(audio[2].class, cls::OPERATION_GROUP); + assert_eq!(audio[2].weak_key(pid::OPERATION), Some(&def::MONO_AUDIO_GAIN[..])); + let amplitude = audio[2].objs(pid::PARAMETERS)[0].data(pid::CONSTANT_VALUE).unwrap(); + let (numerator, denominator) = store::rational_of(&litude[17..]).unwrap(); + assert!((numerator as f64 / denominator as f64 - 10f64.powf(-3.0 / 20.0)).abs() < 1e-4); + assert_eq!(audio[1].strong(pid::OPERATION_GROUP).unwrap().weak_key(pid::OPERATION), Some(&def::MONO_AUDIO_DISSOLVE[..])); +} + +#[test] +fn store_round_trips_every_stored_form() { + let leaf = |n: u8| Obj::new([n; 16]).data_prop(0x1B01, vec![n; 16]); + let root = Obj::new(ids::ROOT) + .data_prop(0x0003, vec![1, 2, 3]) + .with(0x0004, Value::Strong(Box::new(leaf(1).with(0x0005, Value::StrongVec(vec![leaf(2), leaf(3)]))))) + .with( + 0x0002, + Value::Strong(Box::new( + Obj::new([9; 16]) + .with(0x3B04, Value::Strong(Box::new(Obj::new([8; 16]).with(0x2605, Value::StrongSet(vec![leaf(4), leaf(5)], 0x1B01))))), + )), + ) + .with(0x0006, Value::Weak(path::DATA_DEFS.to_vec(), 0x1B01, vec![5; 16])) + .with(0x0007, Value::WeakVec(path::DATA_DEFS.to_vec(), 0x1B01, vec![vec![4; 16], vec![5; 16]])) + .with(0x0008, Value::Stream((0..10_000u32).map(|i| i as u8).collect())); + for v in [craft_cfb::Version::V3, craft_cfb::Version::V4] { + let bytes = store::write(&root, v).unwrap(); + assert_eq!(store::read(&bytes).unwrap(), root); + } + // a data value longer than a property can hold is an error, not a panic + assert!(store::write(&Obj::new(ids::ROOT).data_prop(1, vec![0; 70_000]), craft_cfb::Version::V4).is_err()); +} + +/// The property `p` of `o` as a list of objects, to change. +fn objs_mut(o: &mut Obj, p: u16) -> &mut Vec { + match o.props.iter_mut().find(|(k, _)| *k == p).map(|(_, v)| v) { + Some(Value::StrongVec(v)) | Some(Value::StrongSet(v, _)) => v, + _ => panic!("no object list {p:#06x}"), + } +} + +fn strong_mut(o: &mut Obj, p: u16) -> &mut Obj { + match o.props.iter_mut().find(|(k, _)| *k == p).map(|(_, v)| v) { + Some(Value::Strong(v)) => v, + _ => panic!("no object {p:#06x}"), + } +} + +fn is_picture(o: &Obj) -> bool { + o.weak_key(pid::DATA_DEFINITION) == Some(&ddef::PICTURE[..]) +} + +/// How Premiere Pro 26.5.2 lays a sequence with a nested sequence out in AAF (seen in a file it +/// exported): every composition is tagged top-level, the nested one too; all video tracks of a +/// composition are in ONE slot, a nested scope with a segment per track, lowest first; a clip of +/// the nested sequence is a source clip that points at its composition. Our own file is rewritten +/// into that layout and must read back as the same edit. +#[test] +fn premiere_style_layers_and_nested_compositions_are_read() { + let r = FrameRate::FPS_24; + // "Outer": media on V1 and V3, the sequence "S" nested on V2 with its sound on A1 + let inner = document(); + let mut sources = inner.sources.clone(); + for kind in [CKind::Picture, CKind::Sound] { + let mut nest = source("seq:2", "S", kind, r, 16, None); + (nest.path, nest.nested, nest.length, nest.width, nest.height) = (None, Some(0), r.tick_of(96), 1920, 1080); + sources.push(nest); + } + let gap = |frames: i64| CItem::Filler(r.tick_of(frames)); + let outer = composition( + "Outer", + r, + vec![ + track(CKind::Picture, "V1", 1, vec![clip(r, 0, 5, 30, "a")]), + track(CKind::Picture, "V2", 2, vec![gap(10), clip(r, 2, 12, 40, "S")]), + track(CKind::Picture, "V3", 3, vec![gap(60), clip(r, 0, 100, 20, "a")]), + track(CKind::Sound, "A1", 1, vec![gap(10), clip(r, 3, 12, 40, "S")]), + ], + ); + let ours = written(&Document { compositions: vec![outer], sources, nested: inner.compositions }, false); + + let mut root = store::read(&ours).unwrap(); + let content = strong_mut(strong_mut(&mut root, pid::ROOT_HEADER), pid::CONTENT); + let mut compositions = 0; + for mob in objs_mut(content, pid::MOBS).iter_mut().filter(|m| m.class == cls::COMPOSITION_MOB) { + compositions += 1; + mob.set(pid::USAGE_CODE, Value::Data(def::USAGE_TOP_LEVEL.to_vec())); + let slots = objs_mut(mob, pid::SLOTS); + let picture: Vec = slots.iter().enumerate().filter(|(_, s)| s.strong(pid::SEGMENT).is_some_and(is_picture)).map(|(i, _)| i).collect(); + let layers: Vec = picture.iter().map(|&i| slots[i].strong(pid::SEGMENT).unwrap().clone()).collect(); + let length = layers.iter().filter_map(|l| l.i64(pid::LENGTH)).max().unwrap_or(0); + let scope = Obj::new(cls::NESTED_SCOPE) + .with(pid::DATA_DEFINITION, Value::Weak(path::DATA_DEFS.to_vec(), pid::IDENTIFICATION, ddef::PICTURE.to_vec())) + .data_prop(pid::LENGTH, length.to_le_bytes().to_vec()) + .with(pid::NESTED_SLOTS, Value::StrongVec(layers)); + // the first video slot keeps its id (clips of the nested sequence point at it) and holds + // every layer; the other video slots go + slots[picture[0]].set(pid::SEGMENT, Value::Strong(Box::new(scope))); + for &i in picture[1..].iter().rev() { + slots.remove(i); + } + } + assert_eq!(compositions, 2); + let theirs = store::write(&root, craft_cfb::Version::V4).unwrap(); + assert_ne!(theirs, ours); + + let want = read_clean(&ours); + let got = read_clean(&theirs); + // one edit; the nested composition is one it uses, not a second edit + assert_eq!(got.compositions.len(), 1); + assert_eq!(got.nested.len(), 1); + // layers of one slot share its name and are all as long as the scope: the same edit apart + // from picture track names and gaps after the last clip + let edit = |mut doc: Document| { + for t in doc.compositions.iter_mut().chain(&mut doc.nested).flat_map(|c| &mut c.tracks).filter(|t| t.kind == CKind::Picture) { + t.name.clear(); + while matches!(t.items.last(), Some(CItem::Filler(_))) { + t.items.pop(); + } + } + doc + }; + assert_eq!(edit(got.clone()), edit(want)); + // and that edit is the one that was written: three video tracks, the nest on the second + let q = &got.compositions[0]; + let picture: Vec<_> = q.tracks.iter().filter(|t| t.kind == CKind::Picture).collect(); + assert_eq!(picture.iter().map(|t| t.items.iter().filter(|i| matches!(i, CItem::Clip(_))).count()).collect::>(), [1, 1, 1]); + let nest_of = |kind: CKind| { + let t = q.tracks.iter().filter(|t| t.kind == kind).nth(if kind == CKind::Picture { 1 } else { 0 }).unwrap(); + let [CItem::Filler(gap), CItem::Clip(c), ..] = &t.items[..] else { panic!("{:?}", t.items) }; + (*gap, c.len, c.start, got.sources[c.source].nested, got.sources[c.source].name.clone()) + }; + assert_eq!(nest_of(CKind::Picture), (r.tick_of(10), r.tick_of(40), r.tick_of(12), Some(0), "S".to_string())); + assert_eq!(nest_of(CKind::Sound), nest_of(CKind::Picture)); + assert_eq!(got.nested[0].name, "S"); +} + +/// A slot's name is the track's name, whatever it starts with; a track without one reads back +/// without one. +#[test] +fn audio_tracks_keep_their_names() { + for name in ["Dialogue.Dialogue-1", "Dialogue.Dialogue-1 L", "", "é", "音声", "🎤 Dialogue", "Ä1"] { + let mut doc = document(); + doc.compositions[0].tracks[1].name = name.into(); + let back = read_clean(&written(&doc, false)); + assert_eq!(back.compositions[0].tracks[1].name, name); + } +} + +#[test] +fn unnamed_source_clip_uses_the_referenced_master_name() { + let mut doc = crate::testdoc::sound_only(None); + let name = doc.sources[0].name.clone(); + for item in &mut doc.compositions[0].tracks[0].items { + if let CItem::Clip(clip) = item { + clip.name = name.clone(); + } + } + let mut root = store::read(&written(&doc, false)).unwrap(); + let content = strong_mut(strong_mut(&mut root, pid::ROOT_HEADER), pid::CONTENT); + let master = objs_mut(content, pid::MOBS).iter_mut().find(|m| m.class == cls::MASTER_MOB).unwrap(); + master.set(pid::MOB_NAME, Value::Data(store::utf16z("Master edit"))); + let bytes = store::write(&root, craft_cfb::Version::V4).unwrap(); + let back = read_clean(&bytes); + let clip = back.compositions[0].tracks[0] + .items + .iter() + .find_map(|item| match item { + CItem::Clip(c) => Some(c), + _ => None, + }) + .unwrap(); + assert_eq!(clip.name, "Master edit"); +} + +#[test] +fn sound_source_offsets_use_audio_sample_rate_on_disk() { + let doc = crate::testdoc::sound_only(None); + let bytes = written(&doc, false); + let root = store::read(&bytes).unwrap(); + let mut all = Vec::new(); + walk(&root, &mut all); + let starts: Vec = all.iter().filter(|o| o.class == cls::SOURCE_CLIP).filter_map(|o| o.i64(pid::START_TIME)).collect(); + assert!(starts.contains(&19_200), "expected 0.4 seconds at 48 kHz: {starts:?}"); + let back = read_clean(&bytes); + let clip = back.compositions[0].tracks[0] + .items + .iter() + .find_map(|i| match i { + CItem::Clip(c) => Some(c), + _ => None, + }) + .unwrap(); + assert_eq!(clip.start, craft_timeline::time::FrameRate::FPS_25.tick_of(10)); +} + +#[test] +fn flattened_selectors_and_nested_scopes_are_reported() { + for (class, property, message) in + [(cls::SELECTOR, pid::SELECTED, "selector was flattened"), (cls::NESTED_SCOPE, pid::NESTED_SLOTS, "nested scope was flattened")] + { + let mut root = store::read(&written(&document(), false)).unwrap(); + let content = strong_mut(strong_mut(&mut root, pid::ROOT_HEADER), pid::CONTENT); + let comp = objs_mut(content, pid::MOBS).iter_mut().find(|mob| mob.class == cls::COMPOSITION_MOB).unwrap(); + let slot = objs_mut(comp, pid::SLOTS) + .iter_mut() + .find(|slot| { + slot.strong(pid::SEGMENT).is_some_and(|s| s.class == cls::SEQUENCE && s.weak_key(pid::DATA_DEFINITION) == Some(&ddef::SOUND[..])) + }) + .unwrap(); + let segment = strong_mut(slot, pid::SEGMENT); + let child = segment.clone(); + let mut wrapper = Obj::new(class) + .with(pid::DATA_DEFINITION, child.get(pid::DATA_DEFINITION).unwrap().clone()) + .with(pid::LENGTH, child.get(pid::LENGTH).unwrap().clone()); + let value = if class == cls::SELECTOR { Value::Strong(Box::new(child)) } else { Value::StrongVec(vec![child]) }; + wrapper.set(property, value); + *segment = wrapper; + let bytes = store::write(&root, craft_cfb::Version::V4).unwrap(); + let mut report = Report::default(); + read(&bytes, &mut report).unwrap(); + assert!(report.mentions(message), "{report}"); + } +} + +#[test] +fn relative_media_locator_round_trips_escaped_characters() { + let mut doc = document(); + doc.sources[0].path = Some("Audio Files/100%20 #1.wav".into()); + let bytes = written(&doc, false); + let got = read_clean(&bytes); + assert!(got.sources.iter().any(|s| s.path.as_deref() == Some("Audio Files/100%20 #1.wav"))); +} diff --git a/crates/aaf/src/aaf/write.rs b/crates/aaf/src/aaf/write.rs new file mode 100644 index 000000000..8c9aae88e --- /dev/null +++ b/crates/aaf/src/aaf/write.rs @@ -0,0 +1,804 @@ +//! Composition model → AAF objects. + +use std::collections::HashMap; + +use craft_timeline::time::{FrameRate, Tick}; + +use super::ids::{META_DICTIONARY, ROOT, cls, ddef, def, path, pid}; +use super::store::{self, Auid, Obj, Value, rational, utf16z}; +use crate::model::{CItem, CKind, CMarker, Composition, Document, Gain, Source, ticks_to_units}; +use crate::{Error, Identity, Report, Result}; + +/// UMID-style mob id (SMPTE 330 basic UMID): label, length 0x13, instance 0, material number. +pub(crate) fn mob_id(seed: u64, n: u64) -> [u8; 32] { + let mut id = [0u8; 32]; + id[..12].copy_from_slice(&[0x06, 0x0A, 0x2B, 0x34, 0x01, 0x01, 0x01, 0x05, 0x01, 0x01, 0x0F, 0x20]); + id[12] = 0x13; + let a = mix(seed ^ n.wrapping_mul(0x9E37_79B9_7F4A_7C15)); + let b = mix(a ^ 0xD6E8_FEB8_6659_FD93); + id[16..24].copy_from_slice(&a.to_le_bytes()); + id[24..32].copy_from_slice(&b.to_le_bytes()); + // a "random" material number per RFC 4122 v4 layout keeps it a valid UUID + id[22] = (id[22] & 0x0F) | 0x40; + id[24] = (id[24] & 0x3F) | 0x80; + id +} + +fn mix(mut z: u64) -> u64 { + z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9); + z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB); + z ^ (z >> 31) +} + +pub(crate) fn fnv(s: &[u8], h: u64) -> u64 { + s.iter().fold(h, |h, &b| (h ^ b as u64).wrapping_mul(0x0000_0100_0000_01B3)) +} + +fn timestamp() -> Vec { + // 1970-01-01 00:00:00.00: written files are reproducible + let mut v = 1970i16.to_le_bytes().to_vec(); + v.extend_from_slice(&[1, 1, 0, 0, 0, 0]); + v +} + +fn weak(path: [u16; 3], key: Auid) -> Value { + Value::Weak(path.to_vec(), pid::IDENTIFICATION, key.to_vec()) +} + +fn data_def(kind: CKind) -> Auid { + match kind { + CKind::Picture => ddef::PICTURE, + CKind::Sound => ddef::SOUND, + } +} + +/// An indirect value: byte order, type id, value. +pub(crate) fn indirect(ty: Auid, v: &[u8]) -> Vec { + let mut d = vec![0x4C]; + d.extend_from_slice(&ty); + d.extend_from_slice(v); + d +} + +fn tagged(name: &str, value: &str) -> Obj { + Obj::new(cls::TAGGED_VALUE).data_prop(pid::TAG_NAME, utf16z(name)).data_prop(pid::TAG_VALUE, indirect(def::TYPE_STRING, &utf16z(value))) +} + +fn gain_rational(g: f64) -> Vec { + rational((g.max(0.0) * 65536.0).round().min(i32::MAX as f64) as i64, 65536) +} + +fn definition(class: Auid, id: Auid, name: &str) -> Obj { + Obj::new(class).data_prop(pid::IDENTIFICATION, id.to_vec()).data_prop(pid::NAME, utf16z(name)).data_prop(pid::DESCRIPTION, utf16z("")) +} + +struct W<'a> { + report: &'a mut Report, + inexact: bool, +} + +struct IdGen { + seed: u64, + next: u64, +} + +impl IdGen { + fn for_document(doc: &Document, comp: &Composition) -> Self { + let mut seed = fnv(comp.name.as_bytes(), 0xCBF2_9CE4_8422_2325); + for source in &doc.sources { + seed = fnv(source.path.as_deref().unwrap_or("").as_bytes(), fnv(source.key.as_bytes(), seed)); + } + seed = fnv(&(comp.tracks.len() as u64).to_le_bytes(), seed); + Self { seed, next: 0 } + } + + fn next(&mut self) -> [u8; 32] { + self.next += 1; + mob_id(self.seed, self.next) + } +} + +struct MediaOutput { + mobs: Vec, + essence: Vec, + master_ref: HashMap, +} + +type FileMob = ((Option, usize, CKind), [u8; 32], Vec, usize); + +struct GroupSlots { + master_id: [u8; 32], + tape_id: [u8; 32], + timecode: Option<(i64, FrameRate)>, + master_slots: Vec, + tape_slots: Vec, + files: Vec, + master_ref: HashMap, +} + +struct GroupSlotBuilder<'a, 'b> { + doc: &'a Document, + master_id: [u8; 32], + tape_id: [u8; 32], + ids: &'b mut IdGen, + files: &'b mut Vec, + master_slots: &'b mut Vec, + tape_slots: &'b mut Vec, + master_ref: &'b mut HashMap, +} + +struct FileSlotInput<'a> { + source: &'a Source, + file_slot: u32, + length: i64, + has_timecode: bool, + tape_id: [u8; 32], + member_index: usize, + slots: &'a mut Vec, + rate: (i64, i64), +} + +impl W<'_> { + /// Edit units at `rate` of tick `t`. + fn u(&mut self, t: Tick, rate: (i64, i64)) -> i64 { + let (n, exact) = ticks_to_units(t, rate.0, rate.1); + if !exact { + self.inexact = true; + } + n + } +} + +fn source_rate(s: &Source) -> (i64, i64) { + match s.kind { + CKind::Picture => (s.frame_rate.num, s.frame_rate.den), + CKind::Sound => (s.sample_rate.max(1) as i64, 1), + } +} + +fn write_media(doc: &Document, w: &mut W<'_>, ids: &mut IdGen) -> MediaOutput { + let mut groups: Vec<(String, Vec)> = Vec::new(); + for (index, source) in doc.sources.iter().enumerate() { + if source.nested.is_some() { + continue; + } + match groups.iter_mut().find(|(key, _)| *key == source.key) { + Some((_, members)) => members.push(index), + None => groups.push((source.key.clone(), vec![index])), + } + } + + let mut output = MediaOutput { mobs: Vec::new(), essence: Vec::new(), master_ref: HashMap::new() }; + for (_, members) in groups { + write_source_group(doc, &members, w, ids, &mut output); + } + output +} + +fn write_source_group(doc: &Document, members: &[usize], w: &mut W<'_>, ids: &mut IdGen, output: &mut MediaOutput) { + let first = &doc.sources[members[0]]; + let slots = build_group_slots(doc, members, w, ids); + output.master_ref.extend(slots.master_ref); + let mut master_slots = slots.master_slots; + add_master_markers(doc, members, w, &mut master_slots); + output.mobs.push( + Obj::new(cls::MASTER_MOB) + .data_prop(pid::MOB_ID, slots.master_id.to_vec()) + .data_prop(pid::MOB_NAME, utf16z(&first.name)) + .data_prop(pid::MOB_LAST_MODIFIED, timestamp()) + .data_prop(pid::MOB_CREATION_TIME, timestamp()) + .with(pid::SLOTS, Value::StrongVec(master_slots)), + ); + let tape_id = slots.tape_id; + let timecode = slots.timecode; + let tape_slots = slots.tape_slots; + add_file_mobs(doc, slots.files, w, output); + add_tape_mob(first, tape_id, timecode, tape_slots, output); +} + +fn build_group_slots(doc: &Document, members: &[usize], w: &mut W<'_>, ids: &mut IdGen) -> GroupSlots { + let master_id = ids.next(); + let tape_id = ids.next(); + let timecode = members.iter().find_map(|&i| doc.sources[i].start_tc.map(|t| (t, doc.sources[i].tc_rate))); + let mut tape_slots = Vec::new(); + if let Some((start, rate)) = timecode { + tape_slots.push(timecode_slot(members, doc, w, start, rate)); + } + let mut files: Vec = Vec::new(); + let mut master_slots = Vec::new(); + let mut master_ref = HashMap::new(); + let mut builder = GroupSlotBuilder { + doc, + master_id, + tape_id, + ids, + files: &mut files, + master_slots: &mut master_slots, + tape_slots: &mut tape_slots, + master_ref: &mut master_ref, + }; + for (member_index, &source_index) in members.iter().enumerate() { + builder.add_source(source_index, member_index, timecode.is_some(), w); + } + GroupSlots { master_id, tape_id, timecode, master_slots, tape_slots, files, master_ref } +} + +fn timecode_slot(members: &[usize], doc: &Document, w: &mut W<'_>, start: i64, rate: FrameRate) -> Obj { + let edit_rate = (rate.num, rate.den); + let len = members.iter().map(|&i| doc.sources[i].length).max().unwrap_or(Tick::ZERO); + let units = w.u(len, edit_rate); + timeline_slot( + 1, + "TC1", + 0, + edit_rate, + Obj::new(cls::TIMECODE) + .with(pid::DATA_DEFINITION, weak(path::DATA_DEFS, ddef::TIMECODE)) + .data_prop(pid::LENGTH, units.to_le_bytes().to_vec()) + .data_prop(pid::TC_START, start.to_le_bytes().to_vec()) + .data_prop(pid::TC_FPS, (rate.timecode_base().clamp(1, u16::MAX as i64) as u16).to_le_bytes().to_vec()) + .data_prop(pid::TC_DROP, vec![0]), + ) +} + +impl GroupSlotBuilder<'_, '_> { + fn add_source(&mut self, source_index: usize, member_index: usize, has_timecode: bool, w: &mut W<'_>) { + let source = &self.doc.sources[source_index]; + let rate = source_rate(source); + let embedded_key = if source.embedded.is_some() { source_index } else { usize::MAX }; + let file_key = (source.path.clone(), embedded_key, source.kind); + let file_slot = source.channel.map_or(1, |channel| channel + 1); + let len_units = w.u(source.length, rate); + let file_index = match self.files.iter().position(|file| file.0 == file_key) { + Some(index) => index, + None => { + self.files.push((file_key, self.ids.next(), Vec::new(), source_index)); + self.files.len() - 1 + } + }; + let file_id = self.files[file_index].1; + add_file_slot(FileSlotInput { + source, + file_slot, + length: len_units, + has_timecode, + tape_id: self.tape_id, + member_index, + slots: &mut self.files[file_index].2, + rate, + }); + if has_timecode { + let tape_slot_id = 2 + member_index as u32; + self.tape_slots.push(timeline_slot( + tape_slot_id, + &slot_name(source.kind, member_index as u32 + 1), + member_index as u32 + 1, + rate, + source_clip(source.kind, len_units, [0; 32], 0, 0), + )); + } + let master_slot = member_index as u32 + 1; + self.master_slots.push(timeline_slot( + master_slot, + &slot_name(source.kind, master_slot), + master_slot, + rate, + source_clip(source.kind, len_units, file_id, file_slot, 0), + )); + self.master_ref.insert(source_index, (self.master_id, master_slot)); + } +} + +fn add_file_slot(input: FileSlotInput<'_>) { + let FileSlotInput { source, file_slot, length, has_timecode, tape_id, member_index, slots, rate } = input; + if slots.iter().any(|slot| slot.u32(pid::SLOT_ID) == Some(file_slot)) { + return; + } + let tape_slot_id = if has_timecode { 2 + member_index as u32 } else { 0 }; + let mob_id = if has_timecode { tape_id } else { [0; 32] }; + let clip = source_clip(source.kind, length, mob_id, tape_slot_id, 0); + slots.push(timeline_slot(file_slot, &slot_name(source.kind, file_slot), file_slot, rate, clip)); +} + +fn add_master_markers(doc: &Document, members: &[usize], w: &mut W<'_>, master_slots: &mut Vec) { + let first = &doc.sources[members[0]]; + let marker_rate = + members.iter().map(|&i| &doc.sources[i]).find(|source| source.kind == CKind::Picture).map(source_rate).unwrap_or_else(|| source_rate(first)); + let markers: Vec<&CMarker> = members.iter().flat_map(|&i| doc.sources[i].markers.iter()).collect(); + if markers.is_empty() { + return; + } + let mut unique: Vec = markers.into_iter().cloned().collect(); + unique.sort_by(|a, b| (a.start, &a.name).cmp(&(b.start, &b.name))); + unique.dedup(); + master_slots.push(event_slot(w, members.len() as u32 + 1, marker_rate, &unique)); +} + +fn add_file_mobs(doc: &Document, files: Vec, w: &mut W<'_>, output: &mut MediaOutput) { + for (_, file_id, slots, source_index) in files { + let source = &doc.sources[source_index]; + let desc = descriptor(w, source); + output.mobs.push( + Obj::new(cls::SOURCE_MOB) + .data_prop(pid::MOB_ID, file_id.to_vec()) + .data_prop(pid::MOB_NAME, utf16z(&source.name)) + .data_prop(pid::MOB_LAST_MODIFIED, timestamp()) + .data_prop(pid::MOB_CREATION_TIME, timestamp()) + .with(pid::SLOTS, Value::StrongVec(slots)) + .with(pid::ESSENCE_DESCRIPTION, Value::Strong(Box::new(desc))), + ); + if let Some(data) = &source.embedded { + output.essence.push( + Obj::new(cls::ESSENCE_DATA).data_prop(pid::ESSENCE_MOB_ID, file_id.to_vec()).with(pid::ESSENCE_STREAM, Value::Stream(data.clone())), + ); + } + } +} + +fn add_tape_mob(first: &Source, tape_id: [u8; 32], timecode: Option<(i64, FrameRate)>, tape_slots: Vec, output: &mut MediaOutput) { + let Some(_) = timecode else { return }; + let reel = first.path.as_deref().map(craft_timeline::path::file_stem).unwrap_or(&first.name).to_string(); + output.mobs.push( + Obj::new(cls::SOURCE_MOB) + .data_prop(pid::MOB_ID, tape_id.to_vec()) + .data_prop(pid::MOB_NAME, utf16z(&reel)) + .data_prop(pid::MOB_LAST_MODIFIED, timestamp()) + .data_prop(pid::MOB_CREATION_TIME, timestamp()) + .with(pid::SLOTS, Value::StrongVec(tape_slots)) + .with(pid::ESSENCE_DESCRIPTION, Value::Strong(Box::new(Obj::new(cls::TAPE_DESCRIPTOR)))), + ); +} + +/// Serialise a composition document. +pub(crate) fn write(doc: &Document, version: craft_cfb::Version, identity: &Identity<'_>, report: &mut Report) -> Result> { + let comp = doc.compositions.first().ok_or(Error::Empty)?; + let mut w = W { report, inexact: false }; + let mut ids = IdGen::for_document(doc, comp); + let MediaOutput { mut mobs, essence, master_ref } = write_media(doc, &mut w, &mut ids); + let mut used_ops: Vec = Vec::new(); + let mut uses_varying = false; + + // ---- nested compositions: a clip refers to one as it does to a master mob, through the + // composition's first track of the clip's kind (a broken-out channel: that channel's track) + let mut refs = Refs { mobs: master_ref, rates: doc.sources.iter().enumerate().map(|(i, s)| (i, source_rate(s))).collect() }; + let nested_ids: Vec<[u8; 32]> = doc.nested.iter().map(|_| ids.next()).collect(); + for (si, s) in doc.sources.iter().enumerate() { + let Some((comp, id)) = s.nested.and_then(|n| Some((doc.nested.get(n)?, nested_ids.get(n)?))) else { continue }; + let of_kind: Vec = comp.tracks.iter().enumerate().filter(|(_, t)| t.kind == s.kind).map(|(i, _)| i).collect(); + let Some(&track) = s.channel.and_then(|c| of_kind.get(c as usize)).or(of_kind.first()) else { continue }; + let rate = match s.kind { + CKind::Picture => (comp.rate.num, comp.rate.den), + CKind::Sound => (comp.sample_rate.max(1) as i64, 1), + }; + refs.mobs.insert(si, (*id, track as u32 + 2)); + refs.rates.insert(si, rate); + } + + // ---- the compositions: the exported sequence first + let comp_id = ids.next(); + let composition_mobs = { + let mut composition_writer = CompositionWriter { w: &mut w, doc, refs: &refs, used_ops: &mut used_ops, uses_varying: &mut uses_varying }; + let mut output = vec![composition_writer.write(comp, comp_id, true)]; + output.extend(doc.nested.iter().zip(&nested_ids).map(|(nested, id)| composition_writer.write(nested, *id, false))); + output + }; + mobs.splice(0..0, composition_mobs); + if w.inexact { + w.report.info("some times are not on whole edit units and were rounded"); + } + + // ---- dictionary + let mut ddefs = Vec::new(); + for (id, name) in + [(ddef::PICTURE, "Picture"), (ddef::SOUND, "Sound"), (ddef::TIMECODE, "Timecode"), (ddef::DESCRIPTIVE_METADATA, "DescriptiveMetadata")] + { + ddefs.push(definition(cls::DATA_DEFINITION, id, name)); + } + let mut opdefs = Vec::new(); + for op in &used_ops { + let (name, dd, inputs) = match *op { + x if x == def::VIDEO_DISSOLVE => ("Video Dissolve", ddef::PICTURE, 2), + x if x == def::VIDEO_FADE_TO_BLACK => ("Video Fade To Black", ddef::PICTURE, 1), + x if x == def::SMPTE_VIDEO_WIPE => ("SMPTE Video Wipe", ddef::PICTURE, 2), + x if x == def::MONO_AUDIO_DISSOLVE => ("Mono Audio Dissolve", ddef::SOUND, 2), + _ => ("Mono Audio Gain", ddef::SOUND, 1i32), + }; + let params: Vec> = if *op == def::MONO_AUDIO_GAIN { + vec![def::PARAM_AMPLITUDE.to_vec()] + } else if *op == def::VIDEO_DISSOLVE { + vec![def::PARAM_LEVEL.to_vec()] + } else { + Vec::new() + }; + let mut o = definition(cls::OPERATION_DEFINITION, *op, name) + .with(pid::OPDEF_DATA_DEFINITION, weak(path::DATA_DEFS, dd)) + .data_prop(pid::OPDEF_IS_TIME_WARP, vec![0]) + .data_prop(pid::OPDEF_NUMBER_INPUTS, inputs.to_le_bytes().to_vec()); + if !params.is_empty() { + o.set(pid::OPDEF_PARAMETERS_DEFINED, Value::WeakVec(path::PARAMETER_DEFS.to_vec(), pid::IDENTIFICATION, params)); + } + opdefs.push(o); + } + let pdefs = vec![ + definition(cls::PARAMETER_DEFINITION, def::PARAM_LEVEL, "Level").data_prop(pid::PARAMDEF_DISPLAY_UNITS, utf16z("")), + definition(cls::PARAMETER_DEFINITION, def::PARAM_AMPLITUDE, "Amplitude").data_prop(pid::PARAMDEF_DISPLAY_UNITS, utf16z("")), + ]; + let idefs = if uses_varying || !used_ops.is_empty() { + vec![ + definition(cls::INTERPOLATION_DEFINITION, def::INTERP_LINEAR, "Linear"), + definition(cls::INTERPOLATION_DEFINITION, def::INTERP_CONSTANT, "Constant"), + ] + } else { + Vec::new() + }; + let cdefs = vec![ + definition(cls::CONTAINER_DEFINITION, def::CONTAINER_EXTERNAL, "External Container"), + definition(cls::CONTAINER_DEFINITION, def::CONTAINER_AAF, "AAF Container"), + ]; + let mut dict = Obj::new(cls::DICTIONARY) + .with(pid::DATA_DEFINITIONS, Value::StrongSet(ddefs, pid::IDENTIFICATION)) + .with(pid::PARAMETER_DEFINITIONS, Value::StrongSet(pdefs, pid::IDENTIFICATION)) + .with(pid::CONTAINER_DEFINITIONS, Value::StrongSet(cdefs, pid::IDENTIFICATION)); + if !opdefs.is_empty() { + dict.set(pid::OPERATION_DEFINITIONS, Value::StrongSet(opdefs, pid::IDENTIFICATION)); + } + if !idefs.is_empty() { + dict.set(pid::INTERPOLATION_DEFINITIONS, Value::StrongSet(idefs, pid::IDENTIFICATION)); + } + + let mut content = Obj::new(cls::CONTENT_STORAGE).with(pid::MOBS, Value::StrongSet(mobs, pid::MOB_ID)); + if !essence.is_empty() { + content.set(pid::ESSENCE_DATA, Value::StrongSet(essence, pid::ESSENCE_MOB_ID)); + } + let ident = Obj::new(cls::IDENTIFICATION) + .data_prop(pid::COMPANY_NAME, utf16z(identity.company)) + .data_prop(pid::PRODUCT_NAME, utf16z(identity.product)) + .data_prop(pid::PRODUCT_VERSION_STRING, utf16z(identity.version)) + .data_prop(pid::PRODUCT_ID, identity.product_id.to_vec()) + .data_prop(pid::DATE, timestamp()) + .data_prop(pid::PLATFORM, utf16z(identity.platform)) + .data_prop(pid::GENERATION_AUID, mob_id(ids.seed, 0)[16..].to_vec()); + let header = Obj::new(cls::HEADER) + .data_prop(pid::BYTE_ORDER, 0x4949i16.to_le_bytes().to_vec()) + .data_prop(pid::LAST_MODIFIED, timestamp()) + .data_prop(pid::VERSION, vec![1, 1]) + .data_prop(pid::OBJECT_MODEL_VERSION, 1u32.to_le_bytes().to_vec()) + .data_prop(pid::OPERATIONAL_PATTERN, def::OP_EDIT_PROTOCOL.to_vec()) + .with(pid::CONTENT, Value::Strong(Box::new(content))) + .with(pid::DICTIONARY, Value::Strong(Box::new(dict))) + .with(pid::IDENTIFICATION_LIST, Value::StrongVec(vec![ident])); + // The meta-dictionary holds only extensions to the baseline object model, and everything written + // here is baseline, so its class and type definition sets are empty; readers that load them + // (pyaaf2) still need the sets to be there (filmcraft#323). + let meta = Obj::new(META_DICTIONARY) + .with(pid::META_CLASS_DEFINITIONS, Value::StrongSet(Vec::new(), pid::META_IDENTIFICATION)) + .with(pid::META_TYPE_DEFINITIONS, Value::StrongSet(Vec::new(), pid::META_IDENTIFICATION)); + let root = Obj::new(ROOT).with(pid::ROOT_META_DICTIONARY, Value::Strong(Box::new(meta))).with(pid::ROOT_HEADER, Value::Strong(Box::new(header))); + store::write(&root, version).map_err(Error::Other) +} + +/// Where clips find their sources: source index → (mob id, slot id), and for nested compositions +/// the edit rate of that slot. +#[derive(Default)] +struct Refs { + mobs: HashMap, + rates: HashMap, +} + +/// The composition mob of `comp`. Slot 1 is its timecode; its tracks follow from slot 2 in order. +struct CompositionWriter<'a, 'b, 'c> { + w: &'a mut W<'c>, + doc: &'b Document, + refs: &'b Refs, + used_ops: &'a mut Vec, + uses_varying: &'a mut bool, +} + +impl CompositionWriter<'_, '_, '_> { + fn write(&mut self, comp: &Composition, id: [u8; 32], top: bool) -> Obj { + let w = &mut *self.w; + let doc = self.doc; + let refs = self.refs; + let used_ops = &mut *self.used_ops; + let uses_varying = &mut *self.uses_varying; + let crate_rate = (comp.rate.num, comp.rate.den); + let mut slots = Vec::new(); + let total = comp + .tracks + .iter() + .map(|t| { + let mut c = Tick::ZERO; + for i in &t.items { + match i { + CItem::Transition(x) => c -= x.len, + other => c += other.len(), + } + } + c + }) + .max() + .unwrap_or(Tick::ZERO); + let total_units = w.u(total, crate_rate); + slots.push(timeline_slot( + 1, + "TC1", + 0, + crate_rate, + Obj::new(cls::TIMECODE) + .with(pid::DATA_DEFINITION, weak(path::DATA_DEFS, ddef::TIMECODE)) + .data_prop(pid::LENGTH, total_units.to_le_bytes().to_vec()) + .data_prop(pid::TC_START, comp.start_tc.to_le_bytes().to_vec()) + .data_prop(pid::TC_FPS, (comp.rate.timecode_base().clamp(1, u16::MAX as i64) as u16).to_le_bytes().to_vec()) + .data_prop(pid::TC_DROP, vec![comp.drop as u8]), + )); + let mut slot_id = 2u32; + for t in &comp.tracks { + let rate = match t.kind { + CKind::Picture => crate_rate, + CKind::Sound => (comp.sample_rate.max(1) as i64, 1), + }; + let dd = data_def(t.kind); + let mut comps = Vec::new(); + let mut cursor = Tick::ZERO; + for it in &t.items { + match it { + CItem::Filler(l) => { + let n = w.u(cursor + *l, rate) - w.u(cursor, rate); + cursor += *l; + comps.push( + Obj::new(cls::FILLER) + .with(pid::DATA_DEFINITION, weak(path::DATA_DEFS, dd)) + .data_prop(pid::LENGTH, n.to_le_bytes().to_vec()), + ); + } + CItem::Clip(c) => { + let n = w.u(cursor + c.len, rate) - w.u(cursor, rate); + let s = &doc.sources[c.source]; + let (mid, mslot) = refs.mobs.get(&c.source).copied().unwrap_or(([0; 32], 0)); + // (a nested composition counts the start in its own slot's edit units) + let start = w.u(c.start, refs.rates.get(&c.source).copied().unwrap_or(rate)); + let mut sc = source_clip(t.kind, n, mid, mslot, start); + if !c.name.is_empty() && c.name != s.name { + sc.set(pid::COMPONENT_USER_COMMENTS, Value::StrongVec(vec![tagged("Clip Name", &c.name)])); + } + let seg = match (&c.gain, t.kind) { + (Some(g), CKind::Sound) => { + if !used_ops.contains(&def::MONO_AUDIO_GAIN) { + used_ops.push(def::MONO_AUDIO_GAIN); + } + let param = match g { + Gain::Constant(a) => Obj::new(cls::CONSTANT_VALUE) + .data_prop(pid::PARAMETER_DEFINITION, def::PARAM_AMPLITUDE.to_vec()) + .data_prop(pid::CONSTANT_VALUE, indirect(def::TYPE_RATIONAL, &gain_rational(*a))), + Gain::Varying { linear, points } => { + *uses_varying = true; + let pts = points + .iter() + .map(|(off, a)| { + let o = w.u(cursor + *off, rate) - w.u(cursor, rate); + Obj::new(cls::CONTROL_POINT) + .data_prop(pid::CP_TIME, rational(o, n.max(1))) + .data_prop(pid::CP_VALUE, indirect(def::TYPE_RATIONAL, &gain_rational(*a))) + .data_prop(pid::CP_EDIT_HINT, vec![0]) + }) + .collect(); + Obj::new(cls::VARYING_VALUE) + .data_prop(pid::PARAMETER_DEFINITION, def::PARAM_AMPLITUDE.to_vec()) + .with( + pid::INTERPOLATION, + weak(path::INTERPOLATION_DEFS, if *linear { def::INTERP_LINEAR } else { def::INTERP_CONSTANT }), + ) + .with(pid::POINT_LIST, Value::StrongVec(pts)) + } + }; + Obj::new(cls::OPERATION_GROUP) + .with(pid::DATA_DEFINITION, weak(path::DATA_DEFS, dd)) + .data_prop(pid::LENGTH, n.to_le_bytes().to_vec()) + .with(pid::OPERATION, weak(path::OPERATION_DEFS, def::MONO_AUDIO_GAIN)) + .with(pid::INPUT_SEGMENTS, Value::StrongVec(vec![sc])) + .with(pid::PARAMETERS, Value::StrongVec(vec![param])) + } + _ => sc, + }; + comps.push(seg); + cursor += c.len; + } + CItem::Transition(x) => { + let ts = cursor - x.len; + let n = w.u(cursor, rate) - w.u(ts, rate); + let cut = w.u(ts + x.cut, rate) - w.u(ts, rate); + cursor = ts; + let op = transition_op(t.kind, &x.effect); + if !used_ops.contains(&op) { + used_ops.push(op); + } + let mut og = Obj::new(cls::OPERATION_GROUP) + .with(pid::DATA_DEFINITION, weak(path::DATA_DEFS, dd)) + .data_prop(pid::LENGTH, n.to_le_bytes().to_vec()) + .with(pid::OPERATION, weak(path::OPERATION_DEFS, op)) + .with(pid::COMPONENT_USER_COMMENTS, Value::StrongVec(vec![tagged("FilmCraft Effect", &x.effect)])); + if op == def::VIDEO_DISSOLVE { + *uses_varying = true; + let pts = [(0, 0), (1, 1)] + .iter() + .map(|&(t, v)| { + Obj::new(cls::CONTROL_POINT) + .data_prop(pid::CP_TIME, rational(t, 1)) + .data_prop(pid::CP_VALUE, indirect(def::TYPE_RATIONAL, &rational(v, 1))) + .data_prop(pid::CP_EDIT_HINT, vec![0]) + }) + .collect(); + og.set( + pid::PARAMETERS, + Value::StrongVec(vec![ + Obj::new(cls::VARYING_VALUE) + .data_prop(pid::PARAMETER_DEFINITION, def::PARAM_LEVEL.to_vec()) + .with(pid::INTERPOLATION, weak(path::INTERPOLATION_DEFS, def::INTERP_LINEAR)) + .with(pid::POINT_LIST, Value::StrongVec(pts)), + ]), + ); + } + comps.push( + Obj::new(cls::TRANSITION) + .with(pid::DATA_DEFINITION, weak(path::DATA_DEFS, dd)) + .data_prop(pid::LENGTH, n.to_le_bytes().to_vec()) + .data_prop(pid::CUT_POINT, cut.to_le_bytes().to_vec()) + .with(pid::OPERATION_GROUP, Value::Strong(Box::new(og))), + ); + } + } + } + let len: i64 = comps + .iter() + .map(|c| { + let l = c.i64(pid::LENGTH).unwrap_or(0); + if c.class == cls::TRANSITION { -l } else { l } + }) + .sum(); + let seq = Obj::new(cls::SEQUENCE) + .with(pid::DATA_DEFINITION, weak(path::DATA_DEFS, dd)) + .data_prop(pid::LENGTH, len.to_le_bytes().to_vec()) + .with(pid::COMPONENTS, Value::StrongVec(comps)); + slots.push(timeline_slot(slot_id, &t.name, t.number, rate, seq)); + slot_id += 1; + } + if !comp.markers.is_empty() { + slots.push(event_slot(w, slot_id, crate_rate, &comp.markers)); + } + let mut mob = Obj::new(cls::COMPOSITION_MOB) + .data_prop(pid::MOB_ID, id.to_vec()) + .data_prop(pid::MOB_NAME, utf16z(&comp.name)) + .data_prop(pid::MOB_LAST_MODIFIED, timestamp()) + .data_prop(pid::MOB_CREATION_TIME, timestamp()); + // only the exported sequence is a top-level composition; a nested sequence is found through + // the clips that use it + if top { + mob.set(pid::USAGE_CODE, Value::Data(def::USAGE_TOP_LEVEL.to_vec())); + } + mob.with(pid::SLOTS, Value::StrongVec(slots)).with( + pid::MOB_USER_COMMENTS, + Value::StrongVec(vec![ + tagged("FilmCraft Frame Size", &format!("{}x{}", comp.width, comp.height)), + tagged("FilmCraft Audio Sample Rate", &comp.sample_rate.to_string()), + ]), + ) + } +} + +fn slot_name(kind: CKind, n: u32) -> String { + match kind { + CKind::Picture => format!("V{n}"), + CKind::Sound => format!("A{n}"), + } +} + +fn timeline_slot(id: u32, name: &str, number: u32, rate: (i64, i64), segment: Obj) -> Obj { + let mut o = Obj::new(cls::TIMELINE_MOB_SLOT) + .data_prop(pid::SLOT_ID, id.to_le_bytes().to_vec()) + .data_prop(pid::SLOT_NAME, utf16z(name)) + .data_prop(pid::EDIT_RATE, rational(rate.0, rate.1)) + .data_prop(pid::ORIGIN, 0i64.to_le_bytes().to_vec()) + .with(pid::SEGMENT, Value::Strong(Box::new(segment))); + if number > 0 { + o.set(pid::PHYSICAL_TRACK_NUMBER, Value::Data(number.to_le_bytes().to_vec())); + } + o +} + +fn source_clip(kind: CKind, len: i64, source: [u8; 32], slot: u32, start: i64) -> Obj { + Obj::new(cls::SOURCE_CLIP) + .with(pid::DATA_DEFINITION, weak(path::DATA_DEFS, data_def(kind))) + .data_prop(pid::LENGTH, len.to_le_bytes().to_vec()) + .data_prop(pid::SOURCE_ID, source.to_vec()) + .data_prop(pid::SOURCE_MOB_SLOT_ID, slot.to_le_bytes().to_vec()) + .data_prop(pid::START_TIME, start.to_le_bytes().to_vec()) +} + +fn event_slot(w: &mut W, id: u32, rate: (i64, i64), markers: &[CMarker]) -> Obj { + let comps = markers + .iter() + .map(|m| { + let pos = w.u(m.start, rate); + let len = w.u(m.start + m.duration, rate) - pos; + let mut tags = vec![tagged("Name", &m.name), tagged("Comment", &m.comment)]; + if let Some(c) = &m.color { + tags.push(tagged("Color", c)); + } + Obj::new(cls::COMMENT_MARKER) + .with(pid::DATA_DEFINITION, weak(path::DATA_DEFS, ddef::DESCRIPTIVE_METADATA)) + .data_prop(pid::LENGTH, len.to_le_bytes().to_vec()) + .data_prop(pid::POSITION, pos.to_le_bytes().to_vec()) + .data_prop(pid::COMMENT, utf16z(if m.comment.is_empty() { &m.name } else { &m.comment })) + .with(pid::COMPONENT_USER_COMMENTS, Value::StrongVec(tags)) + }) + .collect(); + Obj::new(cls::EVENT_MOB_SLOT) + .data_prop(pid::SLOT_ID, id.to_le_bytes().to_vec()) + .data_prop(pid::SLOT_NAME, utf16z("Markers")) + .data_prop(pid::EVENT_EDIT_RATE, rational(rate.0, rate.1)) + .with( + pid::SEGMENT, + Value::Strong(Box::new( + Obj::new(cls::SEQUENCE) + .with(pid::DATA_DEFINITION, weak(path::DATA_DEFS, ddef::DESCRIPTIVE_METADATA)) + .with(pid::COMPONENTS, Value::StrongVec(comps)), + )), + ) +} + +fn transition_op(kind: CKind, effect: &str) -> Auid { + match kind { + CKind::Sound => def::MONO_AUDIO_DISSOLVE, + CKind::Picture => match effect { + "dip_to_black" => def::VIDEO_FADE_TO_BLACK, + e if e.contains("wipe") => def::SMPTE_VIDEO_WIPE, + _ => def::VIDEO_DISSOLVE, + }, + } +} + +fn descriptor(w: &mut W, s: &Source) -> Obj { + let rate = source_rate(s); + let len = w.u(s.length, rate); + let container = if s.embedded.is_some() { def::CONTAINER_AAF } else { def::CONTAINER_EXTERNAL }; + let mut d = match s.kind { + CKind::Picture => Obj::new(cls::CDCI_DESCRIPTOR) + .data_prop(pid::STORED_WIDTH, s.width.to_le_bytes().to_vec()) + .data_prop(pid::STORED_HEIGHT, s.height.to_le_bytes().to_vec()) + .data_prop(pid::FRAME_LAYOUT, vec![0]) + .data_prop(pid::IMAGE_ASPECT_RATIO, rational(s.width.max(1) as i64, s.height.max(1) as i64)) + .data_prop(pid::VIDEO_LINE_MAP, { + let mut v = 2u32.to_le_bytes().to_vec(); + v.extend_from_slice(&4u32.to_le_bytes()); + v.extend_from_slice(&0i32.to_le_bytes()); + v.extend_from_slice(&0i32.to_le_bytes()); + v + }) + .data_prop(pid::COMPONENT_WIDTH, 8u32.to_le_bytes().to_vec()) + .data_prop(pid::HORIZONTAL_SUBSAMPLING, 2u32.to_le_bytes().to_vec()), + CKind::Sound => { + // Channel counts and rates come from the project: saturate, as these fields can't + // hold more anyway. + let block = s.file_channels.max(1).saturating_mul((s.bits as u32).div_ceil(8)); + Obj::new(cls::PCM_DESCRIPTOR) + .data_prop(pid::AUDIO_SAMPLING_RATE, rational(s.sample_rate as i64, 1)) + .data_prop(pid::LOCKED, vec![1]) + .data_prop(pid::CHANNELS, s.file_channels.max(1).to_le_bytes().to_vec()) + .data_prop(pid::QUANTIZATION_BITS, (s.bits as u32).to_le_bytes().to_vec()) + .data_prop(pid::BLOCK_ALIGN, u16::try_from(block).unwrap_or(u16::MAX).to_le_bytes().to_vec()) + .data_prop(pid::AVERAGE_BPS, block.saturating_mul(s.sample_rate).to_le_bytes().to_vec()) + } + }; + d.set(pid::SAMPLE_RATE, Value::Data(rational(rate.0, rate.1))); + d.set(pid::FILE_LENGTH, Value::Data(len.to_le_bytes().to_vec())); + d.set(pid::CONTAINER_FORMAT, weak(path::CONTAINER_DEFS, container)); + if let Some(p) = &s.path { + let url = if craft_timeline::path::is_absolute(p) { + craft_timeline::path::path_to_file_url(p, false) + } else { + craft_timeline::path::encode_uri_path(p) + }; + d.set(pid::LOCATOR, Value::StrongVec(vec![Obj::new(cls::NETWORK_LOCATOR).data_prop(pid::URL_STRING, utf16z(&url))])); + } + d +} diff --git a/crates/aaf/src/lib.rs b/crates/aaf/src/lib.rs new file mode 100644 index 000000000..ee7448bc0 --- /dev/null +++ b/crates/aaf/src/lib.rs @@ -0,0 +1,60 @@ +#![cfg_attr(not(test), deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable))] +//! AAF and OMF: the two mob-based editorial interchange formats, read and written through one +//! composition model. +//! +//! - [`model`]: a [`model::Document`] of compositions (tracks of fillers, source clips and +//! overlapping transitions, with clip gain and markers) and the media sources they reference, +//! with exact times ([`craft_timeline::time::Tick`]). +//! - [`aaf`]: Advanced Authoring Format, Edit Protocol, in structured storage (`craft-cfb`). +//! - [`omf`]: OMF Interchange 2.0 in a Bento container; sound only. +//! +//! Both read into and write from the same model, so an application maps its timeline onto the +//! model once. Audio essence can be embedded: the model carries it as PCM, and the WAVE / AIFF +//! wrappers the formats use are craft-audio's. +//! +//! Clean-room: written from the public specifications only (AMWA *AAF Object Specification* v1.1, +//! *AAF Low-Level Container Specification* v1.0.1, *AAF Edit Protocol* v1.0, SMPTE RP 224 / RP 210 +//! labels; Avid *OMF Interchange Specification* 2.0, Apple *Bento Specification* 1.0d5). No file +//! I/O: documents are bytes and media references are strings. +//! +//! Input is untrusted: a damaged or crafted file gives an [`Error`] or a [`Report`] entry, never +//! a panic, a hang or an allocation sized by a count in the file. + +pub mod aaf; +pub mod model; +pub mod omf; +mod pcm; +#[cfg(test)] +mod roundtrip_tests; +#[cfg(test)] +mod testdoc; + +pub use craft_timeline::report::Report; + +/// Error from a reader or writer. Unsupported *features* never error; they go in the [`Report`]. +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum Error { + /// The bytes are not a readable document of the format. + #[error("{format} parse error: {message}")] + Parse { format: &'static str, message: String }, + /// The document has no composition. + #[error("the document contains no timeline")] + Empty, + /// The document could not be written. + #[error("{0}")] + Other(String), +} + +pub type Result = std::result::Result; + +/// Who a written file says made it (the AAF `Identification` object, the OMF `IDNT` object). +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct Identity<'a> { + pub company: &'a str, + pub product: &'a str, + /// The product's version, as text. + pub version: &'a str, + pub platform: &'a str, + /// AAF `ProductID`: an AUID naming the product. + pub product_id: [u8; 16], +} diff --git a/crates/aaf/src/model.rs b/crates/aaf/src/model.rs new file mode 100644 index 000000000..e6bc79140 --- /dev/null +++ b/crates/aaf/src/model.rs @@ -0,0 +1,189 @@ +//! A format-neutral mob-style composition model shared by AAF and OMF. +//! +//! Both formats describe a timeline as a composition of slots (tracks) whose segments are +//! sequences of fillers, source clips and transitions, where a transition *overlaps* the end of +//! the segment before it and the start of the segment after it (the sequence's length is the sum of +//! its segment lengths minus its transition lengths). Source clips reference media through master +//! mobs and file source mobs: here, a [`Source`] per essence, grouped into one media item by its +//! key. All times are ticks; the format serialisers convert to and from edit units. + +use craft_timeline::time::{FrameRate, TICKS_PER_SECOND, Tick}; + +/// Picture or sound. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] +pub enum CKind { + Picture, + Sound, +} + +/// A whole document: compositions and the media they reference. +#[derive(Clone, Debug, Default, PartialEq)] +pub struct Document { + /// The top-level compositions. + pub compositions: Vec, + pub sources: Vec, + /// Compositions that are only used inside others (nested sequences); a [`Source`] refers to + /// one by its index here. They may nest further. + pub nested: Vec, +} + +/// How a nested sequence is written. Premiere Pro writes one as a composition of its own in AAF +/// (clips refer to it the way they refer to media) and renders its sound in OMF, which has no +#[derive(Clone, Debug, PartialEq)] +pub struct Composition { + pub name: String, + /// AAF CompositionMob identifier as 64 lowercase hexadecimal digits. OMF has no equivalent. + /// It is a read identity for applications that let a user choose among compositions; writers + /// generate fresh format identifiers and do not preserve it. + pub aaf_mob_id: Option, + pub rate: FrameRate, + pub sample_rate: u32, + pub width: u32, + pub height: u32, + pub start_tc: i64, + pub drop: bool, + pub tracks: Vec, + pub markers: Vec, +} + +#[derive(Clone, Debug, PartialEq)] +pub struct CTrack { + pub kind: CKind, + pub name: String, + /// Physical track number (1-based, per kind). + pub number: u32, + /// Sound: channels of the track (1 mono, 2 stereo, 6 5.1). + pub channels: u32, + pub items: Vec, +} + +#[derive(Clone, Debug, PartialEq)] +pub enum CItem { + Filler(Tick), + Clip(CClip), + Transition(CTransition), +} + +impl CItem { + /// The item's length on the track. + pub fn len(&self) -> Tick { + match self { + CItem::Filler(l) => *l, + CItem::Clip(c) => c.len, + CItem::Transition(t) => t.len, + } + } +} + +#[derive(Clone, Debug, PartialEq)] +pub struct CClip { + pub len: Tick, + /// Index into [`Document::sources`]. + pub source: usize, + /// Source (file) time of the segment's first frame. + pub start: Tick, + pub gain: Option, + pub name: String, +} + +/// Clip gain (linear amplitude). +#[derive(Clone, Debug, PartialEq)] +pub enum Gain { + Constant(f64), + /// Points at offsets from the segment start; `linear` false = hold (step) interpolation. + Varying { + linear: bool, + points: Vec<(Tick, f64)>, + }, +} + +#[derive(Clone, Debug, PartialEq)] +pub struct CTransition { + pub len: Tick, + /// Where the cut lies, from the transition start. + pub cut: Tick, + /// The transition, by a name of the writing application's choosing; it is kept in a private tag + /// and comes back unchanged. Names the formats themselves can say: `cross_dissolve` and + /// `dip_to_black` (picture), any name containing `wipe` (a SMPTE wipe), `constant_power` (sound). + /// A file without the tag reads as one of these. + pub effect: String, +} + +#[derive(Clone, Debug, PartialEq)] +pub struct CMarker { + pub start: Tick, + pub duration: Tick, + pub name: String, + pub comment: String, + pub color: Option, +} + +/// One essence: a file (or embedded data) carrying the picture, or some channels of sound, of a +/// media item. +#[derive(Clone, Debug, PartialEq)] +pub struct Source { + /// Groups the sources of one media item (one master mob). + pub key: String, + pub name: String, + pub kind: CKind, + pub path: Option, + /// Sound: the (0-based) channel of the file this source exposes (broken out to mono), or + /// `None` for all of them. + pub channel: Option, + /// Sound: channels this source exposes (1 when `channel` is set, else `file_channels`). + pub channels: u32, + /// Sound: channels of the file / embedded data. + pub file_channels: u32, + pub width: u32, + pub height: u32, + /// Picture: the frame rate of the media. + pub frame_rate: FrameRate, + pub sample_rate: u32, + pub bits: u16, + pub length: Tick, + /// Media time of the essence's time 0 (trimmed / consolidated essence). + pub offset: Tick, + /// Start timecode in frames at `tc_rate`. + pub start_tc: Option, + pub tc_rate: FrameRate, + pub embedded: Option>, + pub markers: Vec, + /// Not media but a nested composition: its index in [`Document::nested`]. `start` of a clip + /// that uses it is a time in that composition. + pub nested: Option, +} + +impl Source { + /// A picture source with no length: a still image. + pub fn is_still(&self) -> bool { + self.kind == CKind::Picture && self.length == Tick::ZERO + } +} + +/// The largest time read from a document (about 3.3 days). +pub const MAX_TIME: Tick = Tick(1 << 56); + +/// Ticks of `n` edit units at rate `num/den` (rounded to the nearest tick). +pub fn units_to_ticks(n: i64, num: i64, den: i64) -> Tick { + if num <= 0 || den <= 0 { + return Tick::ZERO; + } + let t = n as i128 * den as i128 * TICKS_PER_SECOND as i128; + let q = t.div_euclid(num as i128); + let r = t.rem_euclid(num as i128); + // documents are untrusted: keep every time far from overflow (±3 days) + Tick((q + if r * 2 >= num as i128 { 1 } else { 0 }).clamp(-MAX_TIME.0 as i128, MAX_TIME.0 as i128) as i64) +} + +/// Edit units at rate `num/den` nearest to `t`; the flag is false when `t` is not on a unit. +pub fn ticks_to_units(t: Tick, num: i64, den: i64) -> (i64, bool) { + if num <= 0 || den <= 0 { + return (0, false); + } + let x = t.0 as i128 * num as i128; + let d = den as i128 * TICKS_PER_SECOND as i128; + let q = x.div_euclid(d); + let r = x.rem_euclid(d); + let n = q + if r * 2 >= d { 1 } else { 0 }; + (n.clamp(i64::MIN as i128, i64::MAX as i128) as i64, r == 0) +} diff --git a/crates/aaf/src/omf.rs b/crates/aaf/src/omf.rs new file mode 100644 index 000000000..57e0f756c --- /dev/null +++ b/crates/aaf/src/omf.rs @@ -0,0 +1,47 @@ +//! OMF Interchange 2.0 for audio post: written, and the same structures read. +//! +//! Written from the public *OMF Interchange Specification Version 2.0* (Avid Technology, 1995/97) +//! and Apple's *Bento Specification* revision 1.0d5 for the container ([`bento`]). +//! +//! The file holds a composition mob (`CMOB`) with a timecode slot and one sound slot per audio +//! track (one per channel when broken out to mono): sequences (`SEQU`) of fillers (`FILL`), source +//! clips (`SCLP`) and transitions (`TRAN` with a `SimpleMonoAudioDissolve` effect); clip volume is a +//! `MonoAudioGain` effect (`EFFE`) whose slot −1 is the clip and slot 1 the amplitude +//! (`CVAL` constant or `VVAL` keyframes). Every media item has a master mob (`MMOB`), a file source +//! mob (`SMOB` with a `WAVD` / `AIFD` descriptor: embedded essence in a `WAVE` media data object, +//! or a locator to a separate file) and a tape source mob carrying its timecode. Times are in +//! samples (sound slots use the sample rate as edit rate) so edits are sample-exact. +//! +//! Only sound is written: picture tracks and markers of the model are left out, and a nested +//! composition is not written as one (readers of OMF do not follow compositions). A caller with +//! nested sequences mixes their sound and passes it as media like any other; Premiere Pro's OMF +//! export does the same. +//! +//! Private properties. `FilmCraft:SCLP:ClipName` (a clip's name) and `FilmCraft:EFFE:EffectID` (a +//! transition's name) are not in the specification; they were first written by FilmCraft and keep +//! their names so that existing files read back. + +pub(crate) mod bento; +mod read; +mod write; + +use crate::model::Document; +use crate::{Identity, Report, Result}; + +/// Write the sound of `doc`'s first composition as an OMF 2.0 file. +pub fn write(doc: &Document, identity: &Identity<'_>, report: &mut Report) -> Result> { + write::write(doc, identity, report) +} + +/// Read an OMF 2.0 file (as written by [`write`] and by applications using the same structures). +pub fn read(bytes: &[u8], report: &mut Report) -> Result { + read::read(bytes, report) +} + +/// Whether `bytes` end with a Bento container label (OMF files do). +pub fn sniff(bytes: &[u8]) -> bool { + bento::sniff(bytes) +} + +#[cfg(test)] +mod tests; diff --git a/crates/aaf/src/omf/bento.rs b/crates/aaf/src/omf/bento.rs new file mode 100644 index 000000000..00a7e2a26 --- /dev/null +++ b/crates/aaf/src/omf/bento.rs @@ -0,0 +1,407 @@ +//! The Bento container (Apple, *Bento Specification* revision 1.0d5), the storage layer of OMF +//! Interchange 2.0 files. +//! +//! A Bento container is a heap of value bytes, a table of contents (TOC) describing every value of +//! every object, and a fixed-size label at the very end of the file that locates the TOC: +//! +//! ```text +//! label (24 bytes, big-endian): magic A4 'C' 'M' A5 'H' 'd' 'r' D7, u16 flags, u16 buffer size +//! (KiB), u16 major version (1), u16 minor version (0), +//! u32 TOC offset, u32 TOC size +//! ``` +//! +//! Every value belongs to an (object id, property id, type id) triple. Properties and types are +//! themselves objects carrying a global name (`"OMFI:CPNT:Length"`, `"omfi:Length32"`). The TOC +//! is a stream of one-byte operations, each followed by its operands (big-endian): +//! +//! | op | operands | meaning | +//! |---|---|---| +//! | 1 NewObject | u32 id | following entries belong to this object | +//! | 2 NewProperty | u32 id | … to this property | +//! | 3 NewType | u32 id | starts a new value of this type | +//! | 4 ExplicitGen | u32 | generation of the value | +//! | 5 Offset4Len4 | u32 offset, u32 length | a value segment in the file | +//! | 6 ContdOffset4Len4 | u32 offset, u32 length | a continuation segment | +//! | 7 Offset8Len4 / 8 Contd… | u64 offset, u32 length | segments beyond 4 GiB | +//! | 9–13 Immediate0–4 | 4 bytes | a value of 0–4 bytes stored in the TOC | +//! | 14 ContdImmediate4 | 4 bytes | continuation | +//! | 15 ReferenceListID | u32 id | the object holding this value's reference list | +//! | 24 EndOfBufr | — | skip to the end of the current TOC buffer | +//! | 0xFF Padding | — | ignored | +//! +//! Object references (OMF's `omfi:ObjRef`) are 4-byte keys resolved through the referencing +//! object's reference list (standard property 22: pairs of u32 key, u32 object id). FilmCraft +//! uses the referenced object's id as the key. + +use std::collections::{BTreeMap, HashMap}; + +pub(crate) const MAGIC: [u8; 8] = [0xA4, b'C', b'M', 0xA5, b'H', b'd', b'r', 0xD7]; +pub(crate) const LABEL_SIZE: usize = 24; + +// standard object ids +const TOC_OBJECT: u32 = 1; +const TOC_SEED: u32 = 2; +const TOC_MIN_SEED: u32 = 3; +const TOC_TYPE: u32 = 19; +const TYPE_7BIT_ASCII: u32 = 21; +pub(crate) const OBJ_REFERENCES: u32 = 22; +const GLOBAL_TYPE_NAME: u32 = 23; +const GLOBAL_PROP_NAME: u32 = 24; +const MIN_USER_ID: u32 = 100; + +const OP_NEW_OBJECT: u8 = 1; +const OP_NEW_PROPERTY: u8 = 2; +const OP_NEW_TYPE: u8 = 3; +const OP_EXPLICIT_GEN: u8 = 4; +const OP_OFFSET4_LEN4: u8 = 5; +const OP_CONTD_OFFSET4_LEN4: u8 = 6; +const OP_OFFSET8_LEN4: u8 = 7; +const OP_CONTD_OFFSET8_LEN4: u8 = 8; +const OP_IMMEDIATE0: u8 = 9; +const OP_IMMEDIATE4: u8 = 13; +const OP_CONTD_IMMEDIATE4: u8 = 14; +const OP_REFERENCE_LIST_ID: u8 = 15; +const OP_END_OF_BUFFER: u8 = 24; +const OP_PADDING: u8 = 0xFF; + +const TOC_BUFFER_KIB: u16 = 8; + +#[derive(Clone, Debug, PartialEq, Eq)] +enum Seg { + Imm(Vec), + At(u64, u32), +} + +/// Bento values are metadata, not essence payloads. Limit reassembled segments so repeated +/// references cannot amplify a small OMF into an enormous allocation. +const MAX_VALUE_BYTES: usize = 16 << 20; + +/// Most bytes of global names (property and type names) kept for one container. Real files name a +/// few hundred short strings; without a cap, many objects naming one large shared range would each +/// retain their own copy. +const MAX_NAME_BYTES: usize = 4 << 20; + +/// Builds a Bento container. +pub(crate) struct Writer { + data: Vec, + names: HashMap<(u32, String), u32>, + next: u32, + /// (object, property, type, segments) + entries: Vec<(u32, u32, u32, Vec)>, +} + +impl Writer { + pub fn new() -> Writer { + Writer { data: Vec::new(), names: HashMap::new(), next: MIN_USER_ID, entries: Vec::new() } + } + + fn named(&mut self, kind: u32, name: &str) -> u32 { + if let Some(&id) = self.names.get(&(kind, name.to_string())) { + return id; + } + let id = self.new_object(); + let mut v = name.as_bytes().to_vec(); + v.push(0); + let seg = self.store(&v); + self.entries.push((id, kind, TYPE_7BIT_ASCII, vec![seg])); + self.names.insert((kind, name.to_string()), id); + id + } + + pub fn property(&mut self, name: &str) -> u32 { + self.named(GLOBAL_PROP_NAME, name) + } + + pub fn type_id(&mut self, name: &str) -> u32 { + self.named(GLOBAL_TYPE_NAME, name) + } + + pub fn new_object(&mut self) -> u32 { + let id = self.next; + self.next += 1; + id + } + + fn store(&mut self, v: &[u8]) -> Seg { + if v.len() <= 4 { + return Seg::Imm(v.to_vec()); + } + let at = self.data.len() as u64; + self.data.extend_from_slice(v); + Seg::At(at, v.len() as u32) + } + + /// Set a value of `obj` (values of more than 4 GiB are not supported by OMF). + pub fn set(&mut self, obj: u32, property: &str, ty: &str, value: &[u8]) { + let p = self.property(property); + let t = self.type_id(ty); + let seg = self.store(value); + self.entries.push((obj, p, t, vec![seg])); + } + + /// The reference list of `obj` (keys are object ids). + pub fn set_references(&mut self, obj: u32, targets: &[u32]) { + let mut v = Vec::with_capacity(targets.len() * 8); + for t in targets { + v.extend_from_slice(&t.to_be_bytes()); + v.extend_from_slice(&t.to_be_bytes()); + } + let seg = self.store(&v); + self.entries.push((obj, OBJ_REFERENCES, TYPE_7BIT_ASCII, vec![seg])); + } + + pub fn finish(mut self) -> Vec { + let seed = self.next; + self.entries.push((TOC_OBJECT, TOC_SEED, TOC_TYPE, vec![Seg::Imm(seed.to_be_bytes().to_vec())])); + self.entries.push((TOC_OBJECT, TOC_MIN_SEED, TOC_TYPE, vec![Seg::Imm(MIN_USER_ID.to_be_bytes().to_vec())])); + self.entries.sort_by_key(|e| (e.0, e.1, e.2)); + let mut toc = Vec::new(); + let (mut cur_obj, mut cur_prop) = (u32::MAX, u32::MAX); + for (obj, prop, ty, segs) in &self.entries { + if *obj != cur_obj { + toc.push(OP_NEW_OBJECT); + toc.extend_from_slice(&obj.to_be_bytes()); + cur_obj = *obj; + cur_prop = u32::MAX; + } + if *prop != cur_prop { + toc.push(OP_NEW_PROPERTY); + toc.extend_from_slice(&prop.to_be_bytes()); + cur_prop = *prop; + } + toc.push(OP_NEW_TYPE); + toc.extend_from_slice(&ty.to_be_bytes()); + for (i, s) in segs.iter().enumerate() { + match s { + Seg::Imm(b) => { + toc.push(if i > 0 { OP_CONTD_IMMEDIATE4 } else { OP_IMMEDIATE0 + b.len() as u8 }); + let mut w = [0u8; 4]; + w[..b.len()].copy_from_slice(b); + toc.extend_from_slice(&w); + } + Seg::At(off, len) if *off <= u32::MAX as u64 => { + toc.push(if i > 0 { OP_CONTD_OFFSET4_LEN4 } else { OP_OFFSET4_LEN4 }); + toc.extend_from_slice(&(*off as u32).to_be_bytes()); + toc.extend_from_slice(&len.to_be_bytes()); + } + Seg::At(off, len) => { + toc.push(if i > 0 { OP_CONTD_OFFSET8_LEN4 } else { OP_OFFSET8_LEN4 }); + toc.extend_from_slice(&off.to_be_bytes()); + toc.extend_from_slice(&len.to_be_bytes()); + } + } + } + } + let mut out = self.data; + let toc_at = out.len() as u64; + out.extend_from_slice(&toc); + let mut label = MAGIC.to_vec(); + label.extend_from_slice(&0u16.to_be_bytes()); // flags + label.extend_from_slice(&TOC_BUFFER_KIB.to_be_bytes()); + label.extend_from_slice(&1u16.to_be_bytes()); + label.extend_from_slice(&0u16.to_be_bytes()); + label.extend_from_slice(&(toc_at.min(u32::MAX as u64) as u32).to_be_bytes()); + label.extend_from_slice(&(toc.len() as u32).to_be_bytes()); + out.extend_from_slice(&label); + out + } +} + +/// One value of a parsed object. +#[derive(Clone, Debug)] +pub(crate) struct Prop { + pub prop: u32, + #[allow(dead_code)] + pub ty: u32, + segs: Vec, +} + +/// A parsed Bento container. +pub(crate) struct Container<'a> { + data: &'a [u8], + pub objects: BTreeMap>, + names: HashMap, + by_name: HashMap, +} + +fn be32(b: &[u8], at: usize) -> Option { + b.get(at..at + 4).map(|s| u32::from_be_bytes([s[0], s[1], s[2], s[3]])) +} + +/// Whether `b` ends with a Bento label. +pub(crate) fn sniff(b: &[u8]) -> bool { + b.len() >= LABEL_SIZE && b[b.len() - LABEL_SIZE..b.len() - LABEL_SIZE + 8] == MAGIC +} + +impl<'a> Container<'a> { + pub fn open(data: &'a [u8]) -> Result, String> { + if !sniff(data) { + return Err("no Bento label at the end of the file".into()); + } + let l = &data[data.len() - LABEL_SIZE..]; + let buf = (u16::from_be_bytes([l[10], l[11]]) as usize).max(1) * 1024; + let toc_at = be32(l, 16).unwrap_or(0) as usize; + let toc_len = be32(l, 20).unwrap_or(0) as usize; + let toc = data.get(toc_at..toc_at.checked_add(toc_len).ok_or("bad TOC size")?).ok_or("the TOC lies outside the file")?; + let mut c = Container { data, objects: BTreeMap::new(), names: HashMap::new(), by_name: HashMap::new() }; + let (mut obj, mut prop) = (0u32, 0u32); + let mut i = 0; + while i < toc.len() { + let op = toc[i]; + i += 1; + let need = |n: usize| -> Result<&[u8], String> { toc.get(i..i + n).ok_or_else(|| "truncated TOC".to_string()) }; + match op { + OP_NEW_OBJECT => { + obj = be32(need(4)?, 0).unwrap_or(0); + i += 4; + } + OP_NEW_PROPERTY => { + prop = be32(need(4)?, 0).unwrap_or(0); + i += 4; + } + OP_NEW_TYPE => { + let ty = be32(need(4)?, 0).unwrap_or(0); + i += 4; + c.objects.entry(obj).or_default().push(Prop { prop, ty, segs: Vec::new() }); + } + OP_EXPLICIT_GEN | OP_REFERENCE_LIST_ID => { + need(4)?; + i += 4; + } + OP_OFFSET4_LEN4 | OP_CONTD_OFFSET4_LEN4 => { + let b = need(8)?; + let seg = Seg::At(be32(b, 0).unwrap_or(0) as u64, be32(b, 4).unwrap_or(0)); + i += 8; + c.push_seg(obj, seg)?; + } + OP_OFFSET8_LEN4 | OP_CONTD_OFFSET8_LEN4 => { + let b = need(12)?; + let off = u64::from_be_bytes(b[..8].try_into().map_err(|_| "truncated TOC")?); + let seg = Seg::At(off, be32(b, 8).unwrap_or(0)); + i += 12; + c.push_seg(obj, seg)?; + } + x @ (OP_IMMEDIATE0..=OP_IMMEDIATE4 | OP_CONTD_IMMEDIATE4) => { + let b = need(4)?; + let n = if x == OP_CONTD_IMMEDIATE4 { 4 } else { (x - OP_IMMEDIATE0) as usize }; + let seg = Seg::Imm(b[..n].to_vec()); + i += 4; + c.push_seg(obj, seg)?; + } + OP_END_OF_BUFFER => { + // the rest of this TOC buffer is unused + i = (i - 1) / buf * buf + buf; + } + OP_PADDING | 0 => {} + other => return Err(format!("unknown TOC operation {other}")), + } + } + // global names + let ids: Vec = c.objects.keys().copied().collect(); + let mut name_bytes = 0usize; + for id in ids { + let name = c.objects[&id].iter().find(|p| p.prop == GLOBAL_PROP_NAME || p.prop == GLOBAL_TYPE_NAME).and_then(|p| c.value(p).ok()); + if let Some(n) = name { + name_bytes = name_bytes.saturating_add(n.len()); + if name_bytes > MAX_NAME_BYTES { + return Err("Bento global names exceed the name budget".into()); + } + let s = String::from_utf8_lossy(&n).trim_end_matches('\0').to_string(); + c.by_name.insert(s.clone(), id); + c.names.insert(id, s); + } + } + Ok(c) + } + + fn push_seg(&mut self, obj: u32, seg: Seg) -> Result<(), String> { + let p = self.objects.get_mut(&obj).and_then(|v| v.last_mut()).ok_or("a value without a type in the TOC")?; + if p.segs.len() > 1 << 20 { + return Err("too many value segments".into()); + } + p.segs.push(seg); + Ok(()) + } + + /// The bytes of a value. + pub fn value(&self, p: &Prop) -> Result, String> { + let total = p.segs.iter().try_fold(0usize, |total, s| { + let len = match s { + Seg::Imm(b) => b.len(), + Seg::At(_, len) => *len as usize, + }; + total.checked_add(len).ok_or_else(|| "Bento value length overflows".to_string()) + })?; + if total > MAX_VALUE_BYTES { + return Err("Bento value exceeds the decoded-value budget".into()); + } + let mut out = Vec::new(); + out.try_reserve_exact(total).map_err(|_| "cannot allocate Bento value")?; + for s in &p.segs { + match s { + Seg::Imm(b) => out.extend_from_slice(b), + Seg::At(off, len) => { + let start = usize::try_from(*off).map_err(|_| "value offset too large")?; + let b = + self.data.get(start..start.checked_add(*len as usize).ok_or("bad value length")?).ok_or("a value lies outside the file")?; + out.extend_from_slice(b); + } + } + } + Ok(out) + } + + pub fn id_of(&self, name: &str) -> Option { + self.by_name.get(name).copied() + } + + #[allow(dead_code)] + pub fn name_of(&self, id: u32) -> Option<&str> { + self.names.get(&id).map(String::as_str) + } + + /// The first value of property `name` of `obj`. + pub fn get(&self, obj: u32, name: &str) -> Option> { + let pid = self.id_of(name)?; + let p = self.objects.get(&obj)?.iter().find(|p| p.prop == pid)?; + self.value(p).ok() + } + + /// Resolve an object reference key of `obj` through its reference list. + pub fn resolve(&self, obj: u32, key: u32) -> u32 { + if let Some(p) = self.objects.get(&obj).and_then(|v| v.iter().find(|p| p.prop == OBJ_REFERENCES)) + && let Ok(v) = self.value(p) + { + for pair in v.as_chunks::<8>().0 { + if be32(pair, 0) == Some(key) { + return be32(pair, 4).unwrap_or(key); + } + } + } + key + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn many_objects_cannot_name_themselves_with_one_shared_range() { + let mut w = Writer::new(); + w.data = vec![b'a'; 1 << 20]; + let ids: Vec = (0..8).map(|_| w.new_object()).collect(); + for id in ids { + w.entries.push((id, GLOBAL_PROP_NAME, TYPE_7BIT_ASCII, vec![Seg::At(0, 1 << 20)])); + } + let file = w.finish(); + assert!(Container::open(&file).err().is_some_and(|e| e.contains("name budget"))); + } + + #[test] + fn repeated_segments_cannot_expand_a_value_past_its_budget() { + let p = Prop { prop: 1, ty: 1, segs: vec![Seg::At(0, MAX_VALUE_BYTES as u32), Seg::Imm(vec![0])] }; + let c = Container { data: &[], objects: BTreeMap::new(), names: HashMap::new(), by_name: HashMap::new() }; + assert!(c.value(&p).unwrap_err().contains("budget")); + } +} diff --git a/crates/aaf/src/omf/read.rs b/crates/aaf/src/omf/read.rs new file mode 100644 index 000000000..d45b6ff63 --- /dev/null +++ b/crates/aaf/src/omf/read.rs @@ -0,0 +1,439 @@ +//! OMF 2.0 objects (Bento) → composition model. + +use std::collections::{HashMap, HashSet}; + +use craft_timeline::time::{FrameRate, Tick}; + +use super::bento::Container; +use crate::model::{CClip, CItem, CKind, CTrack, CTransition, Composition, Document, Gain, Source, units_to_ticks}; +use crate::{Error, Report, Result}; + +type Uid = [u8; 12]; + +const MAX_REFERENCE_VISITS: usize = 65_536; + +struct R<'a, 'b> { + c: &'b Container<'a>, + report: &'b mut Report, + /// big-endian values ("MM"); "II" files are little-endian + be: bool, + mobs: HashMap, + media: HashMap>, + doc: Document, + sources: HashMap<(Uid, u32, String), usize>, +} + +pub(crate) fn read(bytes: &[u8], report: &mut Report) -> Result { + let perr = |m: String| Error::Parse { format: "OMF", message: m }; + let c = Container::open(bytes).map_err(perr)?; + let class_of = |o: u32| c.get(o, "OMFI:OOBJ:ObjClass").and_then(|v| v.get(..4).map(|b| [b[0], b[1], b[2], b[3]])); + let head = c.objects.keys().copied().find(|&o| class_of(o) == Some(*b"HEAD")).ok_or_else(|| perr("no OMF header object".into()))?; + let be = c.get(head, "OMFI:HEAD:ByteOrder").is_none_or(|v| v.first() != Some(&0x49)); + let mut r = R { c: &c, report, be, mobs: HashMap::new(), media: HashMap::new(), doc: Document::default(), sources: HashMap::new() }; + let mob_list = r.refs(head, "OMFI:HEAD:Mobs"); + let mob_list = if mob_list.is_empty() { + c.objects.keys().copied().filter(|&o| matches!(class_of(o).as_ref(), Some(b"CMOB" | b"MMOB" | b"SMOB"))).collect() + } else { + mob_list + }; + for &m in &mob_list { + if let Some(id) = r.uid(m, "OMFI:MOBJ:MobID") { + r.mobs.insert(id, m); + } + } + let md = r.refs(head, "OMFI:HEAD:MediaData"); + let md = + if md.is_empty() { c.objects.keys().copied().filter(|&o| matches!(class_of(o).as_ref(), Some(b"WAVE" | b"AIFC"))).collect() } else { md }; + for m in md { + let Some(id) = r.uid(m, "OMFI:MDAT:MobID") else { continue }; + if let Some(d) = c.get(m, "OMFI:WAVE:Data") { + r.media.insert(id, d); + } else if let Some(d) = c.get(m, "OMFI:AIFC:Data") { + r.media.insert(id, d); + } + } + let cmobs: Vec = mob_list.iter().copied().filter(|&m| class_of(m) == Some(*b"CMOB")).collect(); + let mut referenced = HashSet::new(); + let mut visited = HashSet::new(); + let mut visits = 0; + for &m in &cmobs { + r.collect_refs(m, &mut referenced, &mut visited, &mut visits, 0); + } + let primary: Vec = r.refs(head, "OMFI:HEAD:PrimaryMobs").into_iter().filter(|m| cmobs.contains(m)).collect(); + let top: Vec = if !primary.is_empty() { + primary + } else { + cmobs.iter().copied().filter(|m| r.uid(*m, "OMFI:MOBJ:MobID").is_none_or(|id| !referenced.contains(&id))).collect() + }; + for m in top { + let comp = r.composition(m); + r.doc.compositions.push(comp); + } + if r.doc.compositions.is_empty() { + return Err(Error::Empty); + } + Ok(r.doc) +} + +impl R<'_, '_> { + fn class(&self, o: u32) -> [u8; 4] { + self.c.get(o, "OMFI:OOBJ:ObjClass").and_then(|v| v.get(..4).map(|b| [b[0], b[1], b[2], b[3]])).unwrap_or(*b"????") + } + fn u32_of(&self, b: &[u8]) -> Option { + let a: [u8; 4] = b.get(..4)?.try_into().ok()?; + Some(if self.be { u32::from_be_bytes(a) } else { u32::from_le_bytes(a) }) + } + fn i32(&self, o: u32, p: &str) -> Option { + self.c.get(o, p).and_then(|v| self.u32_of(&v)).map(|x| x as i32 as i64) + } + fn u32(&self, o: u32, p: &str) -> Option { + self.c.get(o, p).and_then(|v| self.u32_of(&v)) + } + fn u16(&self, o: u32, p: &str) -> Option { + let v = self.c.get(o, p)?; + let a: [u8; 2] = v.get(..2)?.try_into().ok()?; + Some(if self.be { u16::from_be_bytes(a) } else { u16::from_le_bytes(a) }) + } + fn rational(&self, o: u32, p: &str) -> Option<(i64, i64)> { + let v = self.c.get(o, p)?; + self.rational_of(&v) + } + fn rational_of(&self, v: &[u8]) -> Option<(i64, i64)> { + Some((self.u32_of(v)? as i32 as i64, self.u32_of(v.get(4..)?)? as i32 as i64)) + } + fn string(&self, o: u32, p: &str) -> Option { + self.c.get(o, p).map(|v| String::from_utf8_lossy(&v).trim_end_matches('\0').to_string()) + } + fn uid(&self, o: u32, p: &str) -> Option { + self.c.get(o, p).and_then(|v| v.get(..12).and_then(|b| b.try_into().ok())) + } + fn r#ref(&self, o: u32, p: &str) -> Option { + let v = self.c.get(o, p)?; + let key = u32::from_be_bytes(v.get(..4)?.try_into().ok()?); + Some(self.c.resolve(o, key)) + } + fn refs(&self, o: u32, p: &str) -> Vec { + let Some(v) = self.c.get(o, p) else { return Vec::new() }; + if v.len() < 2 { + return Vec::new(); + } + let n = u16::from_be_bytes([v[0], v[1]]) as usize; + v[2..].as_chunks::<4>().0.iter().take(n).map(|k| self.c.resolve(o, u32::from_be_bytes([k[0], k[1], k[2], k[3]]))).collect() + } + fn data_kind(&self, o: u32) -> String { + self.r#ref(o, "OMFI:CPNT:DataKind").and_then(|d| self.string(d, "OMFI:DDEF:DataKindID")).unwrap_or_default() + } + fn len(&self, o: u32) -> i64 { + self.i32(o, "OMFI:CPNT:Length").unwrap_or(0).max(0) + } + + fn collect_refs(&self, o: u32, out: &mut HashSet, visited: &mut HashSet, visits: &mut usize, depth: usize) { + if depth > 64 || !visited.insert(o) || *visits >= MAX_REFERENCE_VISITS { + return; + } + *visits += 1; + if self.class(o) == *b"SCLP" + && let Some(id) = self.uid(o, "OMFI:SCLP:SourceID") + { + out.insert(id); + } + for p in ["OMFI:MOBJ:Slots", "OMFI:SEQU:Components", "OMFI:EFFE:EffectSlots"] { + for c in self.refs(o, p) { + self.collect_refs(c, out, visited, visits, depth + 1); + } + } + for p in ["OMFI:MSLT:Segment", "OMFI:ESLT:ArgValue"] { + if let Some(c) = self.r#ref(o, p) { + self.collect_refs(c, out, visited, visits, depth + 1); + } + } + } + + fn composition(&mut self, m: u32) -> Composition { + let name = self.string(m, "OMFI:MOBJ:Name").unwrap_or_else(|| "Sequence".into()); + let mut comp = Composition { + name, + aaf_mob_id: None, + rate: FrameRate::FPS_25, + sample_rate: 48_000, + width: 1920, + height: 1080, + start_tc: 0, + drop: false, + tracks: Vec::new(), + markers: Vec::new(), + }; + let slots = self.refs(m, "OMFI:MOBJ:Slots"); + let mut na = 0; + for s in slots { + let Some(seg) = self.r#ref(s, "OMFI:MSLT:Segment") else { continue }; + let rate = self.rational(s, "OMFI:MSLT:EditRate").filter(|r| r.0 > 0 && r.1 > 0).unwrap_or((25, 1)); + let kind = self.data_kind(seg); + if self.class(seg) == *b"TCCP" || kind == "omfi:data:Timecode" { + comp.rate = FrameRate::new(rate.0, rate.1); + if self.class(seg) == *b"TCCP" { + comp.start_tc = self.i32(seg, "OMFI:TCCP:Start").unwrap_or(0); + comp.drop = self.c.get(seg, "OMFI:TCCP:Drop").and_then(|v| v.first().copied()).unwrap_or(0) != 0; + } + continue; + } + let ckind = match kind.as_str() { + "omfi:data:Sound" => CKind::Sound, + "omfi:data:Picture" | "omfi:data:PictureWithMatte" => CKind::Picture, + _ => { + self.report.info("an OMF slot of an unsupported data kind was skipped"); + continue; + } + }; + if ckind == CKind::Picture { + self.report.info("OMF picture slots are not imported (audio only)"); + continue; + } + if rate.1 == 1 && rate.0 >= 8000 { + comp.sample_rate = rate.0 as u32; + } + let items = self.segment(seg, rate, 0); + na += 1; + let td = self.r#ref(s, "OMFI:MSLT:TrackDesc"); + let tname = td.and_then(|t| self.string(t, "OMFI:TRKD:TrackName")).unwrap_or_else(|| format!("A{na}")); + let number = td.and_then(|t| self.u32(t, "OMFI:TRKD:PhysicalTrack")).unwrap_or(na); + let channels = items + .iter() + .filter_map(|i| match i { + CItem::Clip(c) => Some(self.doc.sources[c.source].channels), + _ => None, + }) + .max() + .unwrap_or(1) + .min(6); + comp.tracks.push(CTrack { kind: CKind::Sound, name: tname, number, channels, items }); + } + comp + } + + fn segment(&mut self, seg: u32, rate: (i64, i64), depth: usize) -> Vec { + let len = units_to_ticks(self.len(seg), rate.0, rate.1); + if depth > 32 { + return vec![CItem::Filler(len)]; + } + match &self.class(seg) { + b"SEQU" => { + let mut out = Vec::new(); + for c in self.refs(seg, "OMFI:SEQU:Components") { + out.extend(self.segment(c, rate, depth + 1)); + } + out + } + b"FILL" => vec![CItem::Filler(len)], + b"SCLP" => vec![self.clip(seg, rate)], + b"TRAN" => { + let cut = units_to_ticks(self.i32(seg, "OMFI:TRAN:CutPoint").unwrap_or(0), rate.0, rate.1); + let effect = self + .r#ref(seg, "OMFI:TRAN:Effect") + .and_then(|e| self.string(e, "FilmCraft:EFFE:EffectID")) + .unwrap_or_else(|| "constant_power".into()); + vec![CItem::Transition(CTransition { len, cut: cut.clamp(Tick::ZERO, len), effect })] + } + b"EFFE" => { + let kind = self.r#ref(seg, "OMFI:EFFE:EffectKind").and_then(|k| self.string(k, "OMFI:EDEF:EffectID")).unwrap_or_default(); + let slots = self.refs(seg, "OMFI:EFFE:EffectSlots"); + let arg = |r: &Self, id: i64| { + slots.iter().copied().find(|&s| r.i32(s, "OMFI:ESLT:ArgID") == Some(id)).and_then(|s| r.r#ref(s, "OMFI:ESLT:ArgValue")) + }; + let Some(input) = arg(self, -1).or_else(|| arg(self, 1).filter(|_| kind != "omfi:effect:MonoAudioGain")) else { + return vec![CItem::Filler(len)]; + }; + let gain = if kind == "omfi:effect:MonoAudioGain" { + arg(self, 1).and_then(|v| self.gain(v, len)) + } else { + self.report.warn("OMF effects other than audio gain are not imported (their input is used)"); + None + }; + let mut items = self.segment(input, rate, depth + 1); + if let (Some(g), [CItem::Clip(c)]) = (gain, items.as_mut_slice()) { + c.gain = Some(g); + } + items + } + _ => { + self.report.info("an unsupported OMF component was imported as a gap"); + vec![CItem::Filler(len)] + } + } + } + + fn amp(&self, v: &[u8]) -> Option { + self.rational_of(v).filter(|r| r.1 != 0).map(|(n, d)| n as f64 / d as f64) + } + + fn gain(&mut self, v: u32, len: Tick) -> Option { + match &self.class(v) { + b"CVAL" => self.c.get(v, "OMFI:CVAL:Value").and_then(|d| self.amp(&d)).map(Gain::Constant), + b"VVAL" => { + let linear = self.u16(v, "OMFI:VVAL:Interpolation") != Some(1); + let points: Vec<(Tick, f64)> = self + .refs(v, "OMFI:VVAL:PointList") + .into_iter() + .filter_map(|p| { + let (n, d) = self.rational(p, "OMFI:CTLP:Time").filter(|r| r.1 != 0)?; + let a = self.c.get(p, "OMFI:CTLP:Value").and_then(|d| self.amp(&d))?; + Some((Tick((len.0 as i128 * n as i128 / d as i128).clamp(-(1i128 << 56), 1i128 << 56) as i64), a)) + }) + .collect(); + (!points.is_empty()).then_some(Gain::Varying { linear, points }) + } + _ => None, + } + } + + fn clip(&mut self, c: u32, rate: (i64, i64)) -> CItem { + let len = units_to_ticks(self.len(c), rate.0, rate.1); + let start = units_to_ticks(self.i32(c, "OMFI:SCLP:StartTime").unwrap_or(0), rate.0, rate.1); + let name = self.string(c, "FilmCraft:SCLP:ClipName").unwrap_or_default(); + let (Some(id), Some(track)) = (self.uid(c, "OMFI:SCLP:SourceID"), self.u32(c, "OMFI:SCLP:SourceTrackID")) else { return CItem::Filler(len) }; + if id == [0; 12] { + return CItem::Filler(len); + } + match self.resolve(id, track, start, None, 0) { + Some((source, t)) => CItem::Clip(CClip { len, source, start: t, gain: None, name }), + None => CItem::Filler(len), + } + } + + fn slot_of(&self, mob: u32, track: u32) -> Option { + self.refs(mob, "OMFI:MOBJ:Slots") + .into_iter() + .find(|&s| self.r#ref(s, "OMFI:MSLT:TrackDesc").and_then(|t| self.u32(t, "OMFI:TRKD:TrackID")) == Some(track)) + } + + fn first_clip(&self, seg: u32) -> Option { + match &self.class(seg) { + b"SCLP" => Some(seg), + b"SEQU" => self.refs(seg, "OMFI:SEQU:Components").into_iter().find_map(|c| self.first_clip(c)), + _ => None, + } + } + + fn resolve(&mut self, id: Uid, track: u32, start: Tick, master: Option, depth: usize) -> Option<(usize, Tick)> { + if depth > 16 { + return None; + } + let Some(&mob) = self.mobs.get(&id) else { + self.report.warn("a clip references a mob that is not in the file (imported as a gap)"); + return None; + }; + let slot = self.slot_of(mob, track)?; + let rate = self.rational(slot, "OMFI:MSLT:EditRate").filter(|r| r.0 > 0 && r.1 > 0).unwrap_or((48_000, 1)); + let seg = self.r#ref(slot, "OMFI:MSLT:Segment")?; + match &self.class(mob) { + b"MMOB" => { + let key = master.unwrap_or_else(|| id.iter().map(|b| format!("{b:02x}")).collect()); + let clip = self.first_clip(seg)?; + let inner = units_to_ticks(self.i32(clip, "OMFI:SCLP:StartTime").unwrap_or(0), rate.0, rate.1); + let next = self.uid(clip, "OMFI:SCLP:SourceID")?; + let next_track = self.u32(clip, "OMFI:SCLP:SourceTrackID")?; + let name = self.string(mob, "OMFI:MOBJ:Name"); + let r = self.resolve(next, next_track, start + inner, Some(key), depth + 1)?; + if let Some(n) = name { + self.doc.sources[r.0].name = n; + } + Some(r) + } + b"SMOB" => { + let desc = self.r#ref(mob, "OMFI:SMOB:MediaDescription")?; + let sr = self.rational(desc, "OMFI:MDFL:SampleRate"); + if sr.is_none() && !self.media.contains_key(&id) { + return None; // a tape / physical source + } + let key = master.unwrap_or_else(|| id.iter().map(|b| format!("{b:02x}")).collect()); + let skey = (id, track, key.clone()); + if let Some(&i) = self.sources.get(&skey) { + return Some((i, start)); + } + let file_rate = sr.filter(|r| r.0 > 0 && r.1 > 0).unwrap_or(rate); + let length = units_to_ticks(self.i32(desc, "OMFI:MDFL:Length").unwrap_or(0), file_rate.0, file_rate.1); + let summary = self.c.get(desc, "OMFI:WAVD:Summary").or_else(|| self.c.get(desc, "OMFI:AIFD:Summary")).unwrap_or_default(); + let fmt = crate::pcm::parse_wav(&summary).or_else(|| crate::pcm::parse_aiff(&summary)).map(|(_, ch, sr, bits)| (ch as u32, sr, bits)); + let mut path = None; + for l in self.refs(desc, "OMFI:MDES:Locator") { + let p = match &self.class(l) { + b"UNXL" => self.string(l, "OMFI:UNXL:PathName"), + b"DOSL" => self.string(l, "OMFI:DOSL:PathName"), + b"MACL" => self.string(l, "OMFI:MACL:PathName"), + b"TXTL" => self.string(l, "OMFI:TXTL:Name"), + b"NETL" => self.string(l, "OMFI:NETL:URLString").map(|u| craft_timeline::path::file_url_to_path(&u)), + _ => None, + }; + if p.is_some() { + path = p; + break; + } + } + let sound_slots = self.refs(mob, "OMFI:MOBJ:Slots").len(); + let (file_channels, sample_rate, bits) = fmt.unwrap_or((1, file_rate.0 as u32, 16)); + let channel = (file_channels > 1 && sound_slots > 1).then(|| track.saturating_sub(1).min(file_channels - 1)); + // timecode of the physical source + let tc = self.first_clip(seg).and_then(|clip| { + let tid = self.uid(clip, "OMFI:SCLP:SourceID")?; + let tape = *self.mobs.get(&tid)?; + let (start_tc, fps, trate) = self.refs(tape, "OMFI:MOBJ:Slots").into_iter().find_map(|s| { + let g = self.r#ref(s, "OMFI:MSLT:Segment")?; + (self.class(g) == *b"TCCP").then(|| { + ( + self.i32(g, "OMFI:TCCP:Start").unwrap_or(0), + self.u16(g, "OMFI:TCCP:FPS").unwrap_or(25), + self.rational(s, "OMFI:MSLT:EditRate"), + ) + }) + })?; + let tcr = trate + .filter(|r| r.0 > 0 && r.1 > 0) + .map(|r| FrameRate::new(r.0, r.1)) + .unwrap_or_else(|| FrameRate::new(fps.max(1) as i64, 1)); + let off = units_to_ticks(self.i32(clip, "OMFI:SCLP:StartTime").unwrap_or(0), rate.0, rate.1); + Some((start_tc + tcr.frame_at(off), tcr)) + }); + let mut s = Source { + key, + name: self.string(mob, "OMFI:MOBJ:Name").unwrap_or_default(), + kind: CKind::Sound, + path, + channel, + channels: if channel.is_some() { 1 } else { file_channels }, + file_channels, + width: 0, + height: 0, + frame_rate: FrameRate::FPS_25, + sample_rate, + bits, + length, + offset: Tick::ZERO, + start_tc: tc.map(|t| t.0), + tc_rate: tc.map(|t| t.1).unwrap_or(FrameRate::FPS_25), + embedded: None, + markers: Vec::new(), + nested: None, + }; + if let Some(d) = self.media.get(&id) { + if let Some((pcm, ch, sr, b)) = crate::pcm::parse_wav(d).or_else(|| crate::pcm::parse_aiff(d)) { + s.embedded = Some(pcm); + s.file_channels = ch as u32; + s.channels = if s.channel.is_some() { 1 } else { ch as u32 }; + s.sample_rate = sr; + s.bits = b; + } else { + self.report.warn("embedded OMF audio in an unsupported format was skipped"); + } + } + let i = self.doc.sources.len(); + self.doc.sources.push(s); + self.sources.insert(skey, i); + Some((i, start)) + } + _ => { + self.report.warn("nested OMF compositions are not supported (imported as gaps)"); + None + } + } + } +} diff --git a/crates/aaf/src/omf/tests.rs b/crates/aaf/src/omf/tests.rs new file mode 100644 index 000000000..c6f4ef9f0 --- /dev/null +++ b/crates/aaf/src/omf/tests.rs @@ -0,0 +1,135 @@ +//! Structural checks of written OMF files: the Bento label and TOC, and the required properties of +//! the OMF Interchange 2.0 classes written. + +use std::collections::HashMap; + +use super::bento::{self, Container}; +use super::*; +use crate::testdoc::{IDENTITY, sound_only}; + +/// Every object of a class written has the properties the specification requires of it. +fn assert_required_properties(c: &Container<'_>, by_class: &HashMap>) { + let required: &[(&str, &[&str])] = &[ + ( + "HEAD", + &[ + "OMFI:HEAD:ByteOrder", + "OMFI:HEAD:LastModified", + "OMFI:HEAD:Version", + "OMFI:HEAD:Mobs", + "OMFI:HEAD:MediaData", + "OMFI:HEAD:DefinitionObjects", + ], + ), + ("CMOB", &["OMFI:MOBJ:MobID", "OMFI:MOBJ:Slots", "OMFI:MOBJ:LastModified", "OMFI:MOBJ:CreationTime"]), + ("MMOB", &["OMFI:MOBJ:MobID", "OMFI:MOBJ:Slots", "OMFI:MOBJ:LastModified", "OMFI:MOBJ:CreationTime"]), + ("SMOB", &["OMFI:MOBJ:MobID", "OMFI:MOBJ:Slots", "OMFI:SMOB:MediaDescription"]), + ("MSLT", &["OMFI:MSLT:Segment", "OMFI:MSLT:EditRate", "OMFI:MSLT:TrackDesc"]), + ("TRKD", &["OMFI:TRKD:Origin", "OMFI:TRKD:TrackID"]), + ("SEQU", &["OMFI:CPNT:DataKind", "OMFI:CPNT:Length", "OMFI:SEQU:Components"]), + ("SCLP", &["OMFI:CPNT:DataKind", "OMFI:CPNT:Length", "OMFI:SCLP:SourceID", "OMFI:SCLP:SourceTrackID", "OMFI:SCLP:StartTime"]), + ("FILL", &["OMFI:CPNT:DataKind", "OMFI:CPNT:Length"]), + ("TRAN", &["OMFI:CPNT:DataKind", "OMFI:CPNT:Length", "OMFI:TRAN:CutPoint", "OMFI:TRAN:Effect"]), + ("EFFE", &["OMFI:CPNT:DataKind", "OMFI:CPNT:Length", "OMFI:EFFE:EffectKind"]), + ("ESLT", &["OMFI:ESLT:ArgID", "OMFI:ESLT:ArgValue"]), + ("CVAL", &["OMFI:CPNT:DataKind", "OMFI:CPNT:Length", "OMFI:CVAL:Value"]), + ("EDEF", &["OMFI:EDEF:EffectID"]), + ("DDEF", &["OMFI:DDEF:DataKindID"]), + ("TCCP", &["OMFI:CPNT:DataKind", "OMFI:CPNT:Length", "OMFI:TCCP:Start", "OMFI:TCCP:FPS", "OMFI:TCCP:Drop"]), + ("WAVD", &["OMFI:MDFL:IsOMFI", "OMFI:MDFL:SampleRate", "OMFI:MDFL:Length", "OMFI:WAVD:Summary"]), + ("WAVE", &["OMFI:MDAT:MobID", "OMFI:WAVE:Data"]), + ("IDNT", &["OMFI:IDNT:CompanyName", "OMFI:IDNT:ProductName"]), + ]; + for (k, props) in required { + let Some(objs) = by_class.get(*k) else { + assert_eq!(*k, "FILL", "no {k} object"); + continue; + }; + for &o in objs { + for prop in *props { + assert!(c.get(o, prop).is_some(), "{k} {o} lacks {prop}"); + } + } + } +} + +#[test] +fn written_files_have_the_required_structure() { + let mut report = Report::default(); + let bytes = write(&sound_only(Some(vec![7; 480 * 4])), &IDENTITY, &mut report).unwrap(); + assert!(!report.has_warnings(), "{report}"); + // label + let l = &bytes[bytes.len() - bento::LABEL_SIZE..]; + assert_eq!(&l[..8], &bento::MAGIC); + assert_eq!(u16::from_be_bytes([l[12], l[13]]), 1, "Bento major version"); + let c = Container::open(&bytes).unwrap(); + let class = |o: u32| c.get(o, "OMFI:OOBJ:ObjClass").map(|v| String::from_utf8_lossy(&v).to_string()); + let mut by_class: HashMap> = HashMap::new(); + for &o in c.objects.keys() { + if let Some(k) = class(o) { + by_class.entry(k).or_default().push(o); + } + } + assert_required_properties(&c, &by_class); + assert_eq!(by_class["HEAD"].len(), 1); + assert_eq!(by_class["CMOB"].len(), 1); + let head = by_class["HEAD"][0]; + assert_eq!(c.get(head, "OMFI:HEAD:Version"), Some(vec![2, 0])); + assert_eq!(c.get(head, "OMFI:HEAD:ByteOrder"), Some(b"MM".to_vec())); + // object references resolve to objects of the right class + let refs = |o: u32, p: &str| -> Vec { + let v = c.get(o, p).unwrap(); + let n = u16::from_be_bytes([v[0], v[1]]) as usize; + v[2..].as_chunks::<4>().0.iter().take(n).map(|k| c.resolve(o, u32::from_be_bytes([k[0], k[1], k[2], k[3]]))).collect() + }; + let one = |o: u32, p: &str| -> u32 { c.resolve(o, u32::from_be_bytes(c.get(o, p).unwrap()[..4].try_into().unwrap())) }; + for m in refs(head, "OMFI:HEAD:Mobs") { + assert!(matches!(class(m).as_deref(), Some("CMOB" | "MMOB" | "SMOB"))); + for s in refs(m, "OMFI:MOBJ:Slots") { + assert_eq!(class(s).as_deref(), Some("MSLT")); + assert_eq!(class(one(s, "OMFI:MSLT:TrackDesc")).as_deref(), Some("TRKD")); + } + } + // embedded media: WAVE data is a WAVE file of the file mob it names + for w in &by_class["WAVE"] { + let data = c.get(*w, "OMFI:WAVE:Data").unwrap(); + let (pcm, ch, sr, bits) = crate::pcm::parse_wav(&data).unwrap(); + assert_eq!((pcm.len(), ch, sr, bits), (480 * 4, 2, 48_000, 16)); + let id = c.get(*w, "OMFI:MDAT:MobID").unwrap(); + assert!(by_class["SMOB"].iter().any(|s| c.get(*s, "OMFI:MOBJ:MobID") == Some(id.clone()))); + } + // the composition's sound sequence: clip, transition, gain effect around a clip + let cm = by_class["CMOB"][0]; + let slots = refs(cm, "OMFI:MOBJ:Slots"); + assert_eq!(class(one(slots[0], "OMFI:MSLT:Segment")).as_deref(), Some("TCCP")); + let seq = one(slots[1], "OMFI:MSLT:Segment"); + let comps = refs(seq, "OMFI:SEQU:Components"); + let classes: Vec = comps.iter().map(|&o| class(o).unwrap()).collect(); + assert_eq!(classes, vec!["EFFE", "TRAN", "SCLP"]); + let len = |o: u32| i32::from_be_bytes(c.get(o, "OMFI:CPNT:Length").unwrap()[..4].try_into().unwrap()) as i64; + let samples = |f: i64| f * 48_000 / 25; + assert_eq!(len(comps[0]), samples(55)); + assert_eq!(len(comps[1]), samples(10)); + assert_eq!(len(comps[2]), samples(55)); + assert_eq!(len(seq), samples(100)); + assert_eq!(c.get(one(comps[0], "OMFI:EFFE:EffectKind"), "OMFI:EDEF:EffectID"), Some(b"omfi:effect:MonoAudioGain\0".to_vec())); +} + +#[test] +fn bento_values_round_trip() { + let mut w = bento::Writer::new(); + let a = w.new_object(); + let b = w.new_object(); + w.set(a, "Test:Small", "test:Bytes", &[1, 2]); + w.set(a, "Test:Empty", "test:Bytes", &[]); + w.set(b, "Test:Big", "test:Bytes", &vec![9; 100_000]); + w.set_references(a, &[b]); + let bytes = w.finish(); + let c = Container::open(&bytes).unwrap(); + assert_eq!(c.get(a, "Test:Small"), Some(vec![1, 2])); + assert_eq!(c.get(a, "Test:Empty"), Some(vec![])); + assert_eq!(c.get(b, "Test:Big").map(|v| v.len()), Some(100_000)); + assert_eq!(c.resolve(a, b), b); + assert_eq!(c.name_of(c.id_of("Test:Big").unwrap()), Some("Test:Big")); + assert!(Container::open(&bytes[..bytes.len() - 1]).is_err()); +} diff --git a/crates/aaf/src/omf/write.rs b/crates/aaf/src/omf/write.rs new file mode 100644 index 000000000..755994804 --- /dev/null +++ b/crates/aaf/src/omf/write.rs @@ -0,0 +1,419 @@ +//! Composition model → OMF 2.0 objects in a Bento container. + +use std::collections::HashMap; + +use craft_timeline::time::Tick; + +use super::bento; +use crate::model::{CItem, CKind, Document, Gain, Source, ticks_to_units}; +use crate::{Error, Identity, Report, Result}; + +/// An OMF mob id (`omfi:UID`): prefix, major, minor. +pub(crate) type Uid = [u8; 12]; + +pub(crate) fn uid(prefix: u32, major: u32, minor: u32) -> Uid { + let mut u = [0u8; 12]; + u[..4].copy_from_slice(&prefix.to_be_bytes()); + u[4..8].copy_from_slice(&major.to_be_bytes()); + u[8..].copy_from_slice(&minor.to_be_bytes()); + u +} + +struct W<'a> { + b: bento::Writer, + refs: HashMap>, + ddefs: HashMap<&'static str, u32>, + edefs: HashMap<&'static str, u32>, + defs: Vec, + report: &'a mut Report, + inexact: bool, +} + +fn rational(n: i64, d: i64) -> Vec { + let mut v = (n.clamp(i32::MIN as i64, i32::MAX as i64) as i32).to_be_bytes().to_vec(); + v.extend_from_slice(&(d.clamp(i32::MIN as i64, i32::MAX as i64) as i32).to_be_bytes()); + v +} + +fn cstr(s: &str) -> Vec { + let mut v = s.as_bytes().to_vec(); + v.push(0); + v +} + +impl W<'_> { + fn obj(&mut self, class: &[u8; 4]) -> u32 { + let id = self.b.new_object(); + self.b.set(id, "OMFI:OOBJ:ObjClass", "omfi:ClassID", class); + id + } + fn str(&mut self, o: u32, p: &str, v: &str) { + self.b.set(o, p, "omfi:String", &cstr(v)); + } + fn i32(&mut self, o: u32, p: &str, ty: &str, v: i64) { + if v > i32::MAX as i64 || v < i32::MIN as i64 { + self.report.warn("a time does not fit OMF's 32-bit positions and was clamped"); + } + self.b.set(o, p, ty, &(v.clamp(i32::MIN as i64, i32::MAX as i64) as i32).to_be_bytes()); + } + fn r#ref(&mut self, o: u32, p: &str, target: u32) { + self.b.set(o, p, "omfi:ObjRef", &target.to_be_bytes()); + self.refs.entry(o).or_default().push(target); + } + fn refs(&mut self, o: u32, p: &str, targets: &[u32]) { + let mut v = (targets.len() as u16).to_be_bytes().to_vec(); + for t in targets { + v.extend_from_slice(&t.to_be_bytes()); + } + self.b.set(o, p, "omfi:ObjRefArray", &v); + self.refs.entry(o).or_default().extend_from_slice(targets); + } + fn u(&mut self, t: Tick, rate: (i64, i64)) -> i64 { + let (n, exact) = ticks_to_units(t, rate.0, rate.1); + if !exact { + self.inexact = true; + } + n + } + fn ddef(&mut self, kind: &'static str) -> u32 { + if let Some(&d) = self.ddefs.get(kind) { + return d; + } + let d = self.obj(b"DDEF"); + self.b.set(d, "OMFI:DDEF:DataKindID", "omfi:UniqueName", &cstr(kind)); + self.ddefs.insert(kind, d); + self.defs.push(d); + d + } + fn edef(&mut self, id: &'static str, name: &str) -> u32 { + if let Some(&d) = self.edefs.get(id) { + return d; + } + let d = self.obj(b"EDEF"); + self.b.set(d, "OMFI:EDEF:EffectID", "omfi:UniqueName", &cstr(id)); + self.str(d, "OMFI:EDEF:EffectName", name); + self.b.set(d, "OMFI:EDEF:Bypass", "omfi:ArgIDType", &(-1i32).to_be_bytes()); + self.edefs.insert(id, d); + self.defs.push(d); + d + } + fn cpnt(&mut self, o: u32, kind: &'static str, len: i64) { + let d = self.ddef(kind); + self.r#ref(o, "OMFI:CPNT:DataKind", d); + self.i32(o, "OMFI:CPNT:Length", "omfi:Length32", len); + } + fn mob(&mut self, class: &[u8; 4], id: Uid, name: &str, slots: &[u32]) -> u32 { + let m = self.obj(class); + self.b.set(m, "OMFI:MOBJ:MobID", "omfi:UID", &id); + self.str(m, "OMFI:MOBJ:Name", name); + self.refs(m, "OMFI:MOBJ:Slots", slots); + self.b.set(m, "OMFI:MOBJ:LastModified", "omfi:TimeStamp", &[0, 0, 0, 0, 1]); + self.b.set(m, "OMFI:MOBJ:CreationTime", "omfi:TimeStamp", &[0, 0, 0, 0, 1]); + m + } + fn slot(&mut self, rate: (i64, i64), segment: u32, track_id: u32, name: &str, physical: u32) -> u32 { + let t = self.obj(b"TRKD"); + self.i32(t, "OMFI:TRKD:Origin", "omfi:Position32", 0); + self.b.set(t, "OMFI:TRKD:TrackID", "omfi:UInt32", &track_id.to_be_bytes()); + self.str(t, "OMFI:TRKD:TrackName", name); + if physical > 0 { + self.b.set(t, "OMFI:TRKD:PhysicalTrack", "omfi:UInt32", &physical.to_be_bytes()); + } + let s = self.obj(b"MSLT"); + self.b.set(s, "OMFI:MSLT:EditRate", "omfi:Rational", &rational(rate.0, rate.1)); + self.r#ref(s, "OMFI:MSLT:Segment", segment); + self.r#ref(s, "OMFI:MSLT:TrackDesc", t); + s + } + fn sclp(&mut self, kind: &'static str, len: i64, source: Uid, track: u32, start: i64) -> u32 { + let c = self.obj(b"SCLP"); + self.cpnt(c, kind, len); + self.b.set(c, "OMFI:SCLP:SourceID", "omfi:UID", &source); + self.b.set(c, "OMFI:SCLP:SourceTrackID", "omfi:UInt32", &track.to_be_bytes()); + self.i32(c, "OMFI:SCLP:StartTime", "omfi:Position32", start); + c + } + fn tccp(&mut self, len: i64, start: i64, fps: i64, drop: bool) -> u32 { + let t = self.obj(b"TCCP"); + self.cpnt(t, "omfi:data:Timecode", len); + self.i32(t, "OMFI:TCCP:Start", "omfi:Position32", start); + self.b.set(t, "OMFI:TCCP:FPS", "omfi:UInt16", &(fps.clamp(1, u16::MAX as i64) as u16).to_be_bytes()); + self.b.set(t, "OMFI:TCCP:Drop", "omfi:Boolean", &[drop as u8]); + t + } + fn value(&mut self, len: i64, g: &Gain, seg_len: i64, rate: (i64, i64), base: Tick) -> u32 { + match g { + Gain::Constant(a) => { + let v = self.obj(b"CVAL"); + self.cpnt(v, "omfi:data:Rational", len); + self.b.set(v, "OMFI:CVAL:Value", "omfi:DataValue", &(*a)); + v + } + Gain::Varying { linear, points } => { + let mut pts = Vec::new(); + for (off, a) in points { + let o = self.u(base + *off, rate) - self.u(base, rate); + let p = self.obj(b"CTLP"); + self.b.set(p, "OMFI:CTLP:Time", "omfi:Rational", &rational(o, seg_len.max(1))); + self.b.set(p, "OMFI:CTLP:Value", "omfi:DataValue", &(*a)); + self.b.set(p, "OMFI:CTLP:EditHint", "omfi:EditHintType", &[0]); + pts.push(p); + } + let v = self.obj(b"VVAL"); + self.cpnt(v, "omfi:data:Rational", len); + self.b.set(v, "OMFI:VVAL:Interpolation", "omfi:InterpKind", &(if *linear { 2u16 } else { 1u16 }).to_be_bytes()); + self.refs(v, "OMFI:VVAL:PointList", &pts); + v + } + } + } +} + +fn fnv(s: &[u8], h: u64) -> u64 { + s.iter().fold(h, |h, &b| (h ^ b as u64).wrapping_mul(0x0000_0100_0000_01B3)) +} + +fn amp(a: f64) -> Vec { + rational((a.max(0.0) * 65536.0).round().min(i32::MAX as f64) as i64, 65536) +} + +fn rate_of(s: &Source) -> (i64, i64) { + match s.kind { + CKind::Picture => (s.frame_rate.num, s.frame_rate.den), + CKind::Sound => (s.sample_rate.max(1) as i64, 1), + } +} + +pub(crate) fn write(doc: &Document, identity: &Identity<'_>, report: &mut Report) -> Result> { + let comp = doc.compositions.first().ok_or(Error::Empty)?; + let mut w = + W { b: bento::Writer::new(), refs: HashMap::new(), ddefs: HashMap::new(), edefs: HashMap::new(), defs: Vec::new(), report, inexact: false }; + let mut seed = fnv(comp.name.as_bytes(), 0xCBF2_9CE4_8422_2325); + for s in &doc.sources { + seed = fnv(s.path.as_deref().unwrap_or("").as_bytes(), fnv(s.key.as_bytes(), seed)); + } + let major = (seed >> 32) as u32 ^ seed as u32; + let mut minor = 0u32; + let mut new_uid = || { + minor += 1; + uid(0x464C_4D43, major, minor) + }; + let mut mobs = Vec::new(); + let mut media_data = Vec::new(); + let mut master_ref: HashMap = HashMap::new(); + // media + let mut groups: Vec<(String, Vec)> = Vec::new(); + for (i, s) in doc.sources.iter().enumerate() { + if s.kind != CKind::Sound { + continue; + } + match groups.iter_mut().find(|(k, _)| *k == s.key) { + Some((_, v)) => v.push(i), + None => groups.push((s.key.clone(), vec![i])), + } + } + for (_, members) in &groups { + let first = &doc.sources[members[0]]; + let master = new_uid(); + let tc = members.iter().find_map(|&i| doc.sources[i].start_tc.map(|t| (t, doc.sources[i].tc_rate))); + let tape = new_uid(); + let mut tape_slots = Vec::new(); + if let Some((start, r)) = tc { + let len = members.iter().map(|&i| doc.sources[i].length).max().unwrap_or(Tick::ZERO); + let l = w.u(len, (r.num, r.den)); + let t = w.tccp(l, start, r.timecode_base(), false); + tape_slots.push(w.slot((r.num, r.den), t, 1, "TC1", 0)); + } + let mut master_slots = Vec::new(); + for (k, &si) in members.iter().enumerate() { + let s = &doc.sources[si]; + let rate = rate_of(s); + let len = w.u(s.length, rate); + // file mob + let file = new_uid(); + let file_track = s.channel.map_or(1, |c| c + 1); + let tape_track = 2 + k as u32; + let to_tape = + if tc.is_some() { w.sclp("omfi:data:Sound", len, tape, tape_track, 0) } else { w.sclp("omfi:data:Sound", len, uid(0, 0, 0), 0, 0) }; + let fslot = w.slot(rate, to_tape, file_track, &format!("A{file_track}"), file_track); + let desc = descriptor(&mut w, s, len); + let fm = w.mob(b"SMOB", file, &s.name, &[fslot]); + w.r#ref(fm, "OMFI:SMOB:MediaDescription", desc); + mobs.push(fm); + if let Some(pcm) = &s.embedded { + let md = w.obj(b"WAVE"); + w.b.set(md, "OMFI:MDAT:MobID", "omfi:UID", &file); + w.b.set( + md, + "OMFI:WAVE:Data", + "omfi:DataValue", + &craft_audio::pcm_wav_file(pcm, u16::try_from(s.file_channels.max(1)).unwrap_or(u16::MAX), s.sample_rate, s.bits), + ); + media_data.push(md); + } + if tc.is_some() { + let c = w.sclp("omfi:data:Sound", len, uid(0, 0, 0), 0, 0); + tape_slots.push(w.slot(rate, c, tape_track, &format!("A{}", k + 1), k as u32 + 1)); + } + let mclip = w.sclp("omfi:data:Sound", len, file, file_track, 0); + master_slots.push(w.slot(rate, mclip, k as u32 + 1, &format!("A{}", k + 1), k as u32 + 1)); + master_ref.insert(si, (master, k as u32 + 1)); + } + mobs.push(w.mob(b"MMOB", master, &first.name, &master_slots)); + if tc.is_some() { + let d = w.obj(b"MDTP"); + let reel = first.path.as_deref().map(craft_timeline::path::file_stem).unwrap_or(&first.name).to_string(); + let tm = w.mob(b"SMOB", tape, &reel, &tape_slots); + w.r#ref(tm, "OMFI:SMOB:MediaDescription", d); + mobs.push(tm); + } + } + // composition + let crate_rate = (comp.rate.num, comp.rate.den); + let mut slots = Vec::new(); + let total = comp + .tracks + .iter() + .map(|t| t.items.iter().fold(Tick::ZERO, |a, i| if matches!(i, CItem::Transition(_)) { a - i.len() } else { a + i.len() })) + .max() + .unwrap_or(Tick::ZERO); + let tl = w.u(total, crate_rate); + let tcc = w.tccp(tl, comp.start_tc, comp.rate.timecode_base(), comp.drop); + slots.push(w.slot(crate_rate, tcc, 1, "TC1", 0)); + for (track_id, t) in (2..).zip(comp.tracks.iter().filter(|t| t.kind == CKind::Sound)) { + let rate = (comp.sample_rate.max(1) as i64, 1); + let mut comps = Vec::new(); + let mut cursor = Tick::ZERO; + for it in &t.items { + match it { + CItem::Filler(l) => { + let n = w.u(cursor + *l, rate) - w.u(cursor, rate); + cursor += *l; + let f = w.obj(b"FILL"); + w.cpnt(f, "omfi:data:Sound", n); + comps.push(f); + } + CItem::Clip(c) => { + let n = w.u(cursor + c.len, rate) - w.u(cursor, rate); + let (mid, mtrack) = master_ref.get(&c.source).copied().unwrap_or((uid(0, 0, 0), 0)); + let start = w.u(c.start, rate); + let sc = w.sclp("omfi:data:Sound", n, mid, mtrack, start); + if !c.name.is_empty() { + w.str(sc, "FilmCraft:SCLP:ClipName", &c.name); + } + let seg = match &c.gain { + Some(g) => { + let v = w.value(n, g, n, rate, cursor); + let input = w.obj(b"ESLT"); + w.b.set(input, "OMFI:ESLT:ArgID", "omfi:ArgIDType", &(-1i32).to_be_bytes()); + w.r#ref(input, "OMFI:ESLT:ArgValue", sc); + let level = w.obj(b"ESLT"); + w.b.set(level, "OMFI:ESLT:ArgID", "omfi:ArgIDType", &1i32.to_be_bytes()); + w.r#ref(level, "OMFI:ESLT:ArgValue", v); + let kind = w.edef("omfi:effect:MonoAudioGain", "Mono Audio Gain"); + let e = w.obj(b"EFFE"); + w.cpnt(e, "omfi:data:Sound", n); + w.r#ref(e, "OMFI:EFFE:EffectKind", kind); + w.refs(e, "OMFI:EFFE:EffectSlots", &[input, level]); + e + } + None => sc, + }; + comps.push(seg); + cursor += c.len; + } + CItem::Transition(x) => { + let ts = cursor - x.len; + let n = w.u(cursor, rate) - w.u(ts, rate); + let cut = w.u(ts + x.cut, rate) - w.u(ts, rate); + cursor = ts; + let kind = w.edef("omfi:effect:SimpleMonoAudioDissolve", "Simple Mono Audio Dissolve"); + let e = w.obj(b"EFFE"); + w.cpnt(e, "omfi:data:Sound", n); + w.r#ref(e, "OMFI:EFFE:EffectKind", kind); + w.refs(e, "OMFI:EFFE:EffectSlots", &[]); + w.str(e, "FilmCraft:EFFE:EffectID", &x.effect); + let tr = w.obj(b"TRAN"); + w.cpnt(tr, "omfi:data:Sound", n); + w.i32(tr, "OMFI:TRAN:CutPoint", "omfi:Position32", cut); + w.r#ref(tr, "OMFI:TRAN:Effect", e); + comps.push(tr); + } + } + } + let len = w.u(cursor.max(Tick::ZERO), rate); + let seq = w.obj(b"SEQU"); + w.cpnt(seq, "omfi:data:Sound", len); + w.refs(seq, "OMFI:SEQU:Components", &comps); + slots.push(w.slot(rate, seq, track_id, &t.name, t.number)); + } + let cmob = w.mob(b"CMOB", new_uid(), &comp.name, &slots); + mobs.insert(0, cmob); + if w.inexact { + w.report.info("some times are not on whole samples / frames and were rounded"); + } + let ident = w.obj(b"IDNT"); + w.str(ident, "OMFI:IDNT:CompanyName", identity.company); + w.str(ident, "OMFI:IDNT:ProductName", identity.product); + w.str(ident, "OMFI:IDNT:ProductVersionString", identity.version); + w.str(ident, "OMFI:IDNT:Platform", identity.platform); + w.b.set(ident, "OMFI:IDNT:Date", "omfi:TimeStamp", &[0, 0, 0, 0, 1]); + let head = w.obj(b"HEAD"); + w.b.set(head, "OMFI:HEAD:ByteOrder", "omfi:Int16", &0x4D4Di16.to_be_bytes()); + w.b.set(head, "OMFI:HEAD:LastModified", "omfi:TimeStamp", &[0, 0, 0, 0, 1]); + w.b.set(head, "OMFI:HEAD:Version", "omfi:VersionType", &[2, 0]); + w.refs(head, "OMFI:HEAD:Mobs", &mobs); + w.refs(head, "OMFI:HEAD:MediaData", &media_data); + w.refs(head, "OMFI:HEAD:PrimaryMobs", &[cmob]); + let defs = w.defs.clone(); + w.refs(head, "OMFI:HEAD:DefinitionObjects", &defs); + w.refs(head, "OMFI:HEAD:IdentificationList", &[ident]); + let refs = std::mem::take(&mut w.refs); + let mut keys: Vec<_> = refs.keys().copied().collect(); + keys.sort_unstable(); + for k in keys { + let mut t = refs[&k].clone(); + t.sort_unstable(); + t.dedup(); + w.b.set_references(k, &t); + } + Ok(w.b.finish()) +} + +fn descriptor(w: &mut W, s: &Source, len: i64) -> u32 { + let aiff = + s.embedded.is_none() && s.path.as_deref().is_some_and(|p| matches!(craft_timeline::path::extension(p).as_str(), "aif" | "aiff" | "aifc")); + let d = w.obj(if aiff { b"AIFD" } else { b"WAVD" }); + w.b.set(d, "OMFI:MDFL:IsOMFI", "omfi:Boolean", &[s.embedded.is_some() as u8]); + let r = rate_of(s); + w.b.set(d, "OMFI:MDFL:SampleRate", "omfi:Rational", &rational(r.0, r.1)); + w.i32(d, "OMFI:MDFL:Length", "omfi:Length32", len); + let frames = u32::try_from(len.max(0)).unwrap_or(u32::MAX); + // Channel counts come from the project: saturate, as the headers can't hold more anyway. + let bytes_per_frame = s.file_channels.max(1).saturating_mul((s.bits as u32).div_ceil(8)); + let channels = u16::try_from(s.file_channels.max(1)).unwrap_or(u16::MAX); + if aiff { + w.b.set(d, "OMFI:AIFD:Summary", "omfi:DataValue", &craft_audio::pcm_aiff_header(frames, channels, s.sample_rate, s.bits)); + } else { + w.b.set( + d, + "OMFI:WAVD:Summary", + "omfi:DataValue", + &craft_audio::pcm_wav_header(frames.saturating_mul(bytes_per_frame), channels, s.sample_rate, s.bits), + ); + } + if let Some(p) = &s.path { + let mut locs = Vec::new(); + let dos = p.len() > 2 && p.as_bytes()[1] == b':'; + let l = w.obj(if dos { b"DOSL" } else { b"UNXL" }); + w.str(l, if dos { "OMFI:DOSL:PathName" } else { "OMFI:UNXL:PathName" }, p); + locs.push(l); + if craft_timeline::path::is_absolute(p) { + let n = w.obj(b"NETL"); + w.str(n, "OMFI:NETL:URLString", &craft_timeline::path::path_to_file_url(p, false)); + locs.push(n); + } + w.refs(d, "OMFI:MDES:Locator", &locs); + } + d +} diff --git a/crates/aaf/src/pcm.rs b/crates/aaf/src/pcm.rs new file mode 100644 index 000000000..789c976a8 --- /dev/null +++ b/crates/aaf/src/pcm.rs @@ -0,0 +1,11 @@ +//! Embedded PCM essence in and out of WAVE and AIFF wrappers (craft-audio does the containers). + +/// PCM (little-endian, 8-bit unsigned), channels, sample rate and bits of a WAVE file. +pub(crate) fn parse_wav(b: &[u8]) -> Option<(Vec, u16, u32, u16)> { + craft_audio::wav_pcm(b).map(|p| (p.data, p.channels, p.sample_rate, p.bits)) +} + +/// The same for an AIFF / AIFF-C (`NONE`, `twos`, `sowt`) file. +pub(crate) fn parse_aiff(b: &[u8]) -> Option<(Vec, u16, u32, u16)> { + craft_audio::aiff_pcm(b).map(|p| (p.data, p.channels, p.sample_rate, p.bits)) +} diff --git a/crates/aaf/src/roundtrip_tests.rs b/crates/aaf/src/roundtrip_tests.rs new file mode 100644 index 000000000..7ba6e993a --- /dev/null +++ b/crates/aaf/src/roundtrip_tests.rs @@ -0,0 +1,251 @@ +//! Documents written and read back, in both formats; damaged files. + +use craft_timeline::time::{FrameRate, Tick}; + +use crate::model::{CItem, CKind, CMarker, Composition, Document, Gain}; +use crate::testdoc::{IDENTITY, pcm_ramp, picture_and_sound, sound_only}; +use crate::{Error, Report, aaf, omf}; + +fn aaf_bytes(doc: &Document, small_sectors: bool) -> Vec { + let mut report = Report::default(); + let bytes = aaf::write(doc, &aaf::WriteOptions { identity: IDENTITY, small_sectors }, &mut report).unwrap(); + assert!(report.is_empty(), "{report}"); + bytes +} + +fn omf_bytes(doc: &Document) -> Vec { + let mut report = Report::default(); + let bytes = omf::write(doc, &IDENTITY, &mut report).unwrap(); + assert!(!report.has_warnings(), "{report}"); + bytes +} + +fn read_clean(bytes: &[u8], is_aaf: bool) -> Document { + let mut report = Report::default(); + let doc = if is_aaf { aaf::read(bytes, &mut report) } else { omf::read(bytes, &mut report) }.unwrap(); + assert!(!report.has_warnings(), "{report}"); + doc +} + +/// What a track holds, with each clip's source by what it is rather than by index. Gain is stored +/// as a rational: four decimals survive. +fn shape(doc: &Document) -> Vec<(CKind, String, u32, Vec)> { + let comp = &doc.compositions[0]; + comp.tracks + .iter() + .map(|t| { + let items = t + .items + .iter() + .map(|i| match i { + CItem::Filler(l) => format!("gap {}", l.0), + CItem::Transition(x) => format!("{} {} cut {}", x.effect, x.len.0, x.cut.0), + CItem::Clip(c) => { + let s = &doc.sources[c.source]; + let gain = match &c.gain { + None => "unity".to_string(), + Some(Gain::Constant(g)) => format!("{g:.4}"), + Some(Gain::Varying { linear, points }) => { + format!("{linear} {:?}", points.iter().map(|(t, g)| (t.0, format!("{g:.4}"))).collect::>()) + } + }; + format!("clip {} from {} of {:?} {:?} gain {gain}", c.len.0, c.start.0, s.path, s.kind) + } + }) + .collect(); + (t.kind, t.name.clone(), t.number, items) + }) + .collect() +} + +#[test] +fn aaf_round_trips_the_edit_at_every_rate() { + for (rate, drop) in [(FrameRate::FPS_25, false), (FrameRate::FPS_29_97, true), (FrameRate::FPS_23_976, false), (FrameRate::FPS_59_94, true)] { + let mut doc = picture_and_sound(rate); + let comp = &mut doc.compositions[0]; + (comp.start_tc, comp.drop) = (rate.timecode_base() * 3600, drop); + comp.markers = vec![ + CMarker { start: rate.tick_of(10), duration: Tick::ZERO, name: "Slate".into(), comment: "take 2".into(), color: Some("Green".into()) }, + CMarker { start: rate.tick_of(40), duration: rate.tick_of(5), name: "Range".into(), comment: String::new(), color: None }, + ]; + // keyframed gain on the first sound clip, held gain steps on nothing else + if let Some(CItem::Clip(c)) = comp.tracks[1].items.first_mut() { + c.gain = Some(Gain::Varying { linear: true, points: vec![(Tick::ZERO, 1.0), (rate.tick_of(25), 0.5)] }); + } + doc.sources[0].markers = + vec![CMarker { start: rate.tick_of(30), duration: Tick::ZERO, name: "In media".into(), comment: String::new(), color: None }]; + for small in [false, true] { + let back = read_clean(&aaf_bytes(&doc, small), true); + let (want, got) = (&doc.compositions[0], &back.compositions[0]); + assert_eq!(shape(&back), shape(&doc), "{rate} small {small}"); + assert_eq!((&got.name, got.rate, got.start_tc, got.drop), (&want.name, want.rate, want.start_tc, want.drop), "{rate}"); + assert_eq!((got.width, got.height, got.sample_rate), (1920, 1080, 48_000), "{rate}"); + let markers = |m: &[CMarker]| m.iter().map(|m| (m.start, m.duration, m.name.clone(), m.comment.clone())).collect::>(); + assert_eq!(markers(&got.markers), markers(&want.markers), "{rate}"); + assert_eq!(back.nested, []); + let picture = back.sources.iter().find(|s| s.kind == CKind::Picture).unwrap(); + assert_eq!((picture.width, picture.height, picture.frame_rate, picture.length), (1280, 720, rate, doc.sources[0].length), "{rate}"); + assert_eq!((picture.start_tc, picture.tc_rate), (Some(86_400), rate), "{rate}"); + assert_eq!(markers(&picture.markers), markers(&doc.sources[0].markers), "{rate}"); + let sound = back.sources.iter().find(|s| s.kind == CKind::Sound).unwrap(); + assert_eq!((sound.channels, sound.file_channels, sound.sample_rate, sound.bits), (2, 2, 48_000, 24), "{rate}"); + assert_eq!(sound.key, picture.key, "one media item"); + // what was read, written again, reads as the same edit (mob ids, and so source keys, are new; + // a writer generates fresh format identifiers and never preserves `aaf_mob_id`) + let again = read_clean(&aaf_bytes(&back, small), true); + let no_ids = |c: &[Composition]| { + c.iter() + .cloned() + .map(|mut c| { + c.aaf_mob_id = None; + c + }) + .collect::>() + }; + assert_eq!((shape(&again), no_ids(&again.compositions)), (shape(&back), no_ids(&back.compositions)), "{rate}"); + } + } +} + +#[test] +fn embedded_audio_comes_back_bit_for_bit() { + let pcm = pcm_ramp(480, 2, 3); + let mut doc = sound_only(Some(pcm.clone())); + // trimmed essence: its first sample is media time 0.2 s + doc.sources[0].offset = Tick::from_units(9_600, 48_000); + for is_aaf in [true, false] { + let bytes = if is_aaf { aaf_bytes(&doc, false) } else { omf_bytes(&doc) }; + assert_eq!((aaf::sniff(&bytes), omf::sniff(&bytes)), (is_aaf, !is_aaf)); + let back = read_clean(&bytes, is_aaf); + let s = &back.sources[0]; + assert_eq!(s.embedded.as_deref(), Some(&pcm[..]), "aaf {is_aaf}"); + assert_eq!((s.path.as_deref(), s.file_channels, s.sample_rate, s.bits), (None, 2, 48_000, 16), "aaf {is_aaf}"); + assert_eq!(s.length, Tick::from_units(480, 48_000), "aaf {is_aaf}"); + assert_eq!(shape(&back), shape(&doc), "aaf {is_aaf}"); + } +} + +#[test] +fn omf_round_trips_sound_linked_to_wave_and_aiff_files() { + for path in ["/m/a.wav", "/m/a.aif"] { + let mut doc = sound_only(None); + doc.sources[0].path = Some(path.into()); + let back = read_clean(&omf_bytes(&doc), false); + assert_eq!(shape(&back), shape(&doc), "{path}"); + let s = &back.sources[0]; + assert_eq!((s.file_channels, s.sample_rate, s.bits, s.embedded.as_ref()), (2, 48_000, 16, None), "{path}"); + assert_eq!(back.compositions[0].rate, FrameRate::FPS_25); + } +} + +#[test] +fn omf_leaves_picture_out() { + let doc = picture_and_sound(FrameRate::FPS_25); + let back = read_clean(&omf_bytes(&doc), false); + assert!(back.compositions[0].tracks.iter().all(|t| t.kind == CKind::Sound)); + assert_eq!(shape(&back).len(), 1); +} + +#[test] +fn empty_and_foreign_documents() { + let none = Document::default(); + assert_eq!(aaf::write(&none, &aaf::WriteOptions { identity: IDENTITY, small_sectors: false }, &mut Report::default()), Err(Error::Empty)); + assert_eq!(omf::write(&none, &IDENTITY, &mut Report::default()), Err(Error::Empty)); + let mut empty = sound_only(None); + empty.compositions[0].tracks.clear(); + empty.sources.clear(); + for small in [false, true] { + assert_eq!(read_clean(&aaf_bytes(&empty, small), true).compositions.len(), 1); + } + assert_eq!(read_clean(&omf_bytes(&empty), false).compositions.len(), 1); + assert!(matches!(aaf::read(b"not an aaf", &mut Report::default()), Err(Error::Parse { format: "AAF", .. }))); + assert!(matches!(omf::read(b"not an omf", &mut Report::default()), Err(Error::Parse { format: "OMF", .. }))); + assert!(!aaf::sniff(b"\xD0\xCF\x11\xE0\xA1\xB1\x1A\xE1 but short")); + assert!(!omf::sniff(b"")); +} + +/// Truncation and random corruption: an error or a document, never a panic. +#[test] +fn damaged_documents_never_panic() { + let aaf_file = aaf_bytes(&picture_and_sound(FrameRate::FPS_25), true); + let omf_file = omf_bytes(&sound_only(Some(pcm_ramp(100, 2, 1)))); + for (bytes, is_aaf) in [(&aaf_file, true), (&omf_file, false)] { + let read = |b: &[u8]| { + let mut report = Report::default(); + let _ = if is_aaf { aaf::read(b, &mut report) } else { omf::read(b, &mut report) }; + }; + for cut in (0..bytes.len()).step_by(97) { + read(&bytes[..cut]); + } + let mut seed = 0xA5A5_1234_5678_9ABCu64; + for _ in 0..400 { + let mut g = bytes.clone(); + for _ in 0..8 { + seed ^= seed << 13; + seed ^= seed >> 7; + seed ^= seed << 17; + let at = (seed as usize) % g.len(); + g[at] = (seed >> 40) as u8; + } + read(&g); + } + } +} + +/// A time that is not on a whole edit unit is rounded, and the report says so. +#[test] +fn off_grid_times_are_rounded_and_reported() { + let mut doc = picture_and_sound(FrameRate::FPS_25); + if let Some(CItem::Clip(c)) = doc.compositions[0].tracks[0].items.first_mut() { + c.start += Tick(7); + } + let mut report = Report::default(); + aaf::write(&doc, &aaf::WriteOptions { identity: IDENTITY, small_sectors: false }, &mut report).unwrap(); + assert!(report.mentions("rounded"), "{report}"); +} + +/// A composition that uses itself (a damaged file) is a gap with a warning, not a recursion. +#[test] +fn a_composition_nested_in_itself_is_a_gap() { + let rate = FrameRate::FPS_25; + let mut doc = picture_and_sound(rate); + let mut inner = doc.compositions[0].clone(); + inner.name = "Inner".into(); + let mut nest = doc.sources[0].clone(); + (nest.key, nest.path, nest.nested, nest.start_tc) = ("seq:9".into(), None, Some(0), None); + doc.sources.push(nest); + let uses_inner = CItem::Clip(crate::model::CClip { len: rate.tick_of(20), source: 2, start: Tick::ZERO, gain: None, name: "Inner".into() }); + inner.tracks[0].items = vec![uses_inner.clone()]; + doc.nested.push(inner); + doc.compositions[0].tracks[0].items = vec![uses_inner]; + let bytes = aaf::write(&doc, &aaf::WriteOptions { identity: IDENTITY, small_sectors: false }, &mut Report::default()).unwrap(); + let mut report = Report::default(); + let back = aaf::read(&bytes, &mut report).unwrap(); + assert!(report.mentions("nested in itself"), "{report}"); + assert_eq!(back.nested.len(), 1); + assert!(matches!(back.nested[0].tracks[0].items[..], [CItem::Filler(_)]), "{:?}", back.nested[0].tracks[0].items); +} + +#[test] +fn aaf_source_start_uses_referenced_slot_rate() { + let doc = sound_only(None); + let bytes = aaf_bytes(&doc, false); + let back = read_clean(&bytes, true); + let original = doc.compositions[0].tracks[0] + .items + .iter() + .find_map(|item| match item { + CItem::Clip(c) => Some(c.start), + _ => None, + }) + .unwrap(); + let actual = back.compositions[0].tracks[0] + .items + .iter() + .find_map(|item| match item { + CItem::Clip(c) => Some(c.start), + _ => None, + }) + .unwrap(); + assert_eq!(actual, original); +} diff --git a/crates/aaf/src/testdoc.rs b/crates/aaf/src/testdoc.rs new file mode 100644 index 000000000..c2740e1e7 --- /dev/null +++ b/crates/aaf/src/testdoc.rs @@ -0,0 +1,117 @@ +//! Documents the tests write: what an editor's two-clip sequence with a dissolve looks like in +//! the model. + +use craft_timeline::time::{FrameRate, Tick}; + +use crate::Identity; +use crate::model::{CClip, CItem, CKind, CTrack, CTransition, Composition, Document, Gain, Source}; + +pub(crate) const IDENTITY: Identity<'static> = + Identity { company: "Craft", product: "craft-aaf tests", version: "1.2.3", platform: "test", product_id: *b"craft-aaf-tests." }; + +/// A source of `kind` for the media item `key` at `path`: 1280×720 picture at `rate`, or stereo +/// 48 kHz sound of `bits` bits; 100 seconds long. +pub(crate) fn source(key: &str, path: &str, kind: CKind, rate: FrameRate, bits: u16, start_tc: Option) -> Source { + let sound = kind == CKind::Sound; + Source { + key: key.into(), + name: path.rsplit('/').next().unwrap_or(path).into(), + kind, + path: Some(path.into()), + channel: None, + channels: if sound { 2 } else { 0 }, + file_channels: if sound { 2 } else { 0 }, + width: if sound { 0 } else { 1280 }, + height: if sound { 0 } else { 720 }, + frame_rate: rate, + sample_rate: 48_000, + bits, + length: rate.tick_of(100 * rate.timecode_base()), + offset: Tick::ZERO, + start_tc, + tc_rate: rate, + embedded: None, + markers: Vec::new(), + nested: None, + } +} + +pub(crate) fn clip(rate: FrameRate, source: usize, start: i64, len: i64, name: &str) -> CItem { + CItem::Clip(CClip { len: rate.tick_of(len), source, start: rate.tick_of(start), gain: None, name: name.into() }) +} + +/// Two clips of `source` cut at frame `cut`, each `cut` frames long on the timeline, joined by a +/// transition of `dur` frames centred on the cut: each clip runs half the transition past the cut. +pub(crate) fn two_clips(rate: FrameRate, source: usize, cut: i64, dur: i64, (in_a, in_b): (i64, i64), effect: &str) -> Vec { + let half = dur / 2; + vec![ + clip(rate, source, in_a, cut + half, "a"), + CItem::Transition(CTransition { len: rate.tick_of(dur), cut: rate.tick_of(half), effect: effect.into() }), + clip(rate, source, in_b - half, cut + half, "a"), + ] +} + +pub(crate) fn composition(name: &str, rate: FrameRate, tracks: Vec) -> Composition { + Composition { + name: name.into(), + aaf_mob_id: None, + rate, + sample_rate: 48_000, + width: 1920, + height: 1080, + start_tc: 0, + drop: false, + tracks, + markers: Vec::new(), + } +} + +pub(crate) fn track(kind: CKind, name: &str, number: u32, items: Vec) -> CTrack { + CTrack { kind, name: name.into(), number, channels: if kind == CKind::Sound { 2 } else { 0 }, items } +} + +/// "S" at `rate`: V1 and A1 each hold two clips of `a.mov`, `cut` frames each on the timeline (from +/// source frames `ins`), with a transition of `dur` frames centred on the cut; the second sound +/// clip is 3 dB down. +pub(crate) fn picture_and_sound_cut(rate: FrameRate, cut: i64, dur: i64, ins: (i64, i64)) -> Document { + let sources = vec![ + source("item:1", "/m/a.mov", CKind::Picture, rate, 24, Some(86_400)), + source("item:1", "/m/a.mov", CKind::Sound, rate, 24, Some(86_400)), + ]; + let mut sound = two_clips(rate, 1, cut, dur, ins, "constant_power"); + if let Some(CItem::Clip(c)) = sound.last_mut() { + c.gain = Some(Gain::Constant(10f64.powf(-3.0 / 20.0))); + } + let tracks = vec![track(CKind::Picture, "V1", 1, two_clips(rate, 0, cut, dur, ins, "cross_dissolve")), track(CKind::Sound, "A1", 1, sound)]; + Document { compositions: vec![composition("S", rate, tracks)], sources, nested: Vec::new() } +} + +/// [`picture_and_sound_cut`] with 50-frame clips from source frames 10 and 205 and a 10-frame +/// transition: every time is a multiple of five frames, which is a whole number of 48 kHz samples +/// at the NTSC rates too. +pub(crate) fn picture_and_sound(rate: FrameRate) -> Document { + picture_and_sound_cut(rate, 50, 10, (10, 205)) +} + +/// 16-bit PCM: `frames` frames of `channels` channels, every sample different from its neighbours. +pub(crate) fn pcm_ramp(frames: usize, channels: usize, seed: i32) -> Vec { + (0..frames * channels).flat_map(|i| ((i as i32 * 37 + seed * 1000) as i16).to_le_bytes()).collect() +} + +/// "S" at 25 fps, sound only: A1 holds two 50-frame clips of `a.wav` (from source frames 10 and +/// 300) with a 10-frame crossfade centred on the cut; the first clip is 6 dB up. The sound is +/// embedded when `embedded` is given (480 frames of 16-bit stereo). +pub(crate) fn sound_only(embedded: Option>) -> Document { + let rate = FrameRate::FPS_25; + let mut s = source("item:1", "/m/a.wav", CKind::Sound, rate, 16, None); + if let Some(pcm) = embedded { + s.path = None; + s.length = Tick::from_units((pcm.len() / 4) as i64, 48_000); + s.embedded = Some(pcm); + } + let mut items = two_clips(rate, 0, 50, 10, (10, 300), "constant_power"); + if let Some(CItem::Clip(c)) = items.first_mut() { + c.gain = Some(Gain::Constant(10f64.powf(6.0 / 20.0))); + } + Document { compositions: vec![composition("S", rate, vec![track(CKind::Sound, "A1", 1, items)])], sources: vec![s], nested: Vec::new() } +} diff --git a/crates/aep/Cargo.toml b/crates/aep/Cargo.toml new file mode 100644 index 000000000..b0ebb9110 --- /dev/null +++ b/crates/aep/Cargo.toml @@ -0,0 +1,16 @@ +[package] +name = "craft-aep" +description = "After Effects projects: the .aep (RIFX 'Egg!') and .aepx container as a lossless chunk tree with a typed, read-only view (compositions, layers, properties, keyframes, effects, masks, shapes, text, footage), bounded on hostile input" +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +repository.workspace = true + +[lints] +workspace = true + +# The tool's own tests run with the crate's (examples are only built by default). +[[example]] +name = "stubicc" +test = true diff --git a/crates/aep/README.md b/crates/aep/README.md new file mode 100644 index 000000000..95fcdd1a6 --- /dev/null +++ b/crates/aep/README.md @@ -0,0 +1,104 @@ +# craft-aep + +After Effects projects (`.aep`, `.aepx`): the container as a lossless chunk tree, and a typed, +read-only view of what it holds. Bytes in, a neutral model out, and the tree back to bytes. +Mapping the view onto an application's document (which effect becomes which, units, what is +reported as lost) stays in the application. + +No file access: callers pass bytes, so the crate builds for wasm32. No dependencies. + +| Form | Read | Write | +|---|---|---| +| `.aep` (RIFX `Egg!`) | chunk tree and typed view | the chunk tree, byte for byte | +| `.aepx` (XML) | into the same chunk tree | no | + +## Container + +An `.aep` is a `RIFX` container (big-endian RIFF) with form type `Egg!`: chunks of a 4-byte id, a +big-endian `u32` size and a body padded to an even length; `LIST` chunks start with a 4-byte list +type followed by chunks. `parse` builds the tree, `write` serialises it, and for every input that +parses, `write(parse(x)) == x` byte for byte (container and chunk sizes are recomputed from the +tree; pad bytes, odd bodies and the bytes after the container, an XMP packet, are kept). + +The XML form of a project (`.aepx`) is read into the same tree by `read_aepx` (a small bounded +XML tokenizer of its own); `parse_any` picks the reader by content, so the typed view takes +either form. The mapping is in [`docs/aep-format.md`](docs/aep-format.md), section 1. + +A reader that only looks does not need the owned tree. `TreeIndex` is the same tree as one flat, +read-only array in depth-first order, borrowed from the input: `TreeIndex::parse` for an `.aep`, +`index_aepx` and `TreeIndex::from_drafts` for an `.aepx` (decoded into one buffer first). It +counts the same chunks against the same `Limits` and returns the same errors as `parse`, and the +typed view reads through either (`Project::new` for the owned tree, `Project::from_index` for the +index). An importer should use the index; it is about twice as fast and allocates far less. + +Bodies that look like lists but are not chunk sequences (for example `LIST btdk`, raw text) stay +opaque rather than failing the parse. Input is untrusted: sizes are checked against the remaining +input, nesting and chunk count are bounded (`Limits`), nothing is allocated from a declared size, +and truncated or damaged files return `Err` (or, inside the container, an opaque body). + +## Typed view + +The container layer decodes no chunk body. On top of it, a typed view (`Project`, `Item`, `Comp`, +`Layer`, `Property`, ...) reads the fields whose layout was verified against the values the test +files were made with: layer and composition headers (switches, exact times and time stretch, size, +frame rate, work area, shutter phase, display start, renderer), static transform values in After +Effects' units with the "absent = default" rule, keyframe records (interpolation sides, ease per +component, plain and spatial templates), Time Remapping, expressions with their enable switch, +effect instances and parameter values (with the settings data of Curves, Levels, Hue/Saturation, +Cryptomatte, EXtractoR, IDentifier and Puppet meshes), masks and bezier paths with tangents, shape +layer groups, text documents (paragraph and style runs, box, justification, tracking, faux styles, +caps, leading), markers with duration, strings and cue data, cameras and lights with their +options, track mattes, project settings and the working space's name, the version that saved the +file, footage (stills, audio, image sequences, the layer of a Photoshop file an item shows), solids +and precomp links. Every accessor returns +`Option` or an empty list on damaged data and never panics. Which fields are verified, which are +not decoded, and how it was found is in [`docs/aep-format.md`](docs/aep-format.md). + +Writing a project from an application's document (building every chunk in code) is not here: it +is EffectCraft's exporter, which is written against EffectCraft's own model. + +## Specifications + +Public specifications used for parts the format embeds: + +- ICC.1:2010: the profile description of a working-space profile (a v2 `desc` or a v4 `mluc` + tag), from which the working space's name is read (`settings.rs`). +- RFC 4648 (base64): the profile data in the project's colour settings JSON. + +## Clean room + +Everything here comes from our own observations: project files that we generated ourselves with +After Effects, one change per file, compared byte by byte. No source code or format +documentation of another `.aep` reader or writer was used, and no Adobe asset is used. + +## Tests + +The unit tests and the robustness tests build their input in code. The tests of the typed view +read generated projects (own test data): a few combined projects, one composition per case +([`tests/fixtures/CASES.md`](tests/fixtures/CASES.md)). They are not in this repository but in +[storytold/effectcraft-corpus](https://github.com/storytold/effectcraft-corpus), with their +attribution, the generation notes and the inspection of their embedded content. +`tests/fixtures/corpus.lock` pins the commit and lists the SHA-256 of every file used. To run +against them: + +```sh +git clone https://github.com/storytold/effectcraft-corpus.git +git -C effectcraft-corpus checkout +CRAFT_AEP_FIXTURES=$PWD/effectcraft-corpus/aep CRAFT_AEP_FIXTURES_REQUIRED=1 cargo test -p craft-aep +``` + +The tests reach the projects only through `tests/it/common/mod.rs`, which hands a test its case +as a project of its own cut from the combined file. Without `CRAFT_AEP_FIXTURES` such a test +prints `SKIPPED: fixture missing` and passes; with `CRAFT_AEP_FIXTURES_REQUIRED` set, a +missing project fails it. + +## Tools + +- `examples/aepdump.rs`: prints the chunk tree of a file (ids, sizes, short data, match names): + `cargo run -p craft-aep --example aepdump -- file.aep`. +- `examples/stubicc.rs`: replaces every embedded ICC profile of a saved project by a stub that + keeps only the profile's description: the JSON `colorProfileData` of the working space in an + `.aep` chunk or the `.aepx` text, and a raw profile of an imported image: + `cargo run -p craft-aep --example stubicc -- in.aep out.aep`. A profile it cannot replace stops + it before anything is written. Use it before a generated project becomes test data, so no + vendor colour data stays in it, and check the result independently. diff --git a/crates/aep/docs/aep-format.md b/crates/aep/docs/aep-format.md new file mode 100644 index 000000000..3582276d7 --- /dev/null +++ b/crates/aep/docs/aep-format.md @@ -0,0 +1,1102 @@ +# After Effects project format (`.aep`) + +> **Last reviewed:** 2026-11-05 · **Last updated:** 2026-11-11 · **Change:** footage: the Photoshop layer an item shows and its document's size (`opti` tag `8BPS`, section 3.3, EffectCraft issue 3087); before that: Puppet (`ADBE FreePin3`, 3.7): the property tree from an external scripting listing, **?** until a byte sample exists (#3093); before that: footage: an image sequence without a filename prefix stores only the suffix `Utf8`, and one imported with Force alphabetical order stores its file list in `LIST StVc` / `StVS` (section 3, footage); before that: versions: `svap` is the version that wrote the file, `head` bytes 4 to 7 the version it is written for, and what a Save a Copy As 25.x / 24.x of After Effects 2026 changes (section 1, "Versions"); before that: the stretch numerator is signed (a negative one reverses the layer, 981-983); layer styles (3.12b, 950-980); before that: footage: `sspc@118` of an image sequence is its folder's modification time (860, read-back x1-x3); before that: text: paragraph `/24`, `/35` and style `/68` are neutral for 0 and 1 (732-734, edited in place); before that: keyframes: the ease of mask path keys (599, 700), the spatial speed unit of fractional values (597, 598, 730); before that: text: character and paragraph settings, manual kerning, vertical text, `/nil` is neutral (S17: 538-578, 595, 596); before that: cameras, lights and 3D rotations (S16: the auto Position of a two-node camera is where After Effects renders it, 537; camera and light defaults read back 255, 256; Orientation `otst/otda` 488), Timewarp (529-533), an expression on an effect parameter (534); before that: text: style slot /13 is superscript / subscript (526-528; every scripted text of the corpus is superscript), wrapping box text 517; before that: effects of batch 5 (409-450, 511-516: integer sliders, checkbox defaults in `pard`, arbitrary data of Hue/Saturation and Levels, the parameters of Invert, Fast Box Blur, Gaussian Blur, Drop Shadow, Glow; section 3.7); before that: shape items of batch 5 (451-484, 519: ellipse, fill and stroke opacity, fill rule, group transform, shape layer anchor, trim paths, rectangle roundness, polystar fields, gradient default, nested groups, the defaults of every item; section 3.9); before that: track mattes: mode at `ldta` byte 107 and the matte layer id at byte 160 (cases 402-408, section 3.1); before that: text: automatic leading is verified (400); Exposure (`ADBE Exposure2`, cases 389-397): group start / end parameter types 13 / 14, float slider valid minimum and slider range (section 3.7); before that: text: U+0003 is a paragraph break (386, 387); before that: a stored text Anchor Point is pixels (385, now V); before that: the XML form `.aepx` is read into the same chunk tree (section 1, "The XML form"); the `head` save counter is a `u32` at byte 16; text documents for the importer (stroke colour, automatic leading, the font of each run, the undecoded-slot check, the text-layer Anchor Point, the Source Text record); before that: third round of verified field layouts (explicit-default semantics, type-major bezier ease, exact time stretch and in / out points, Time Remapping state, comp pixel aspect / shutter phase / display start, Point default, Layer Control None, dropdown selection, one `mkif` per mask, polystar and radial gradient records, text styles, camera and light options, marker cue data, audio and image-sequence footage) added to the typed view of `craft-aep` · **Target:** Adobe After Effects 2026 + +What `crates/aep` ([`craft-aep`](../README.md)) reads and writes, and the evidence +for each statement. Everything here was observed on project files we generated ourselves; no +source code, specification or format documentation of any other reader was used (every layout is +backed by our own cases, see section 5). This is the container and a set of +verified field layouts, not a project importer: turning a parsed `.aep` into an application's +document is the application's work. This document was written in EffectCraft, whose importer and +exporter are the first users of the crate; where it names `import/...`, `export/...`, +`aep-import.md`, `aep-export.md`, `effect_map` or `style_map`, those are in +[EffectCraft](https://github.com/storytold/effectcraft) (`crates/aep`, `docs/`). + +Evidence is cited as **case numbers**: the files `NNN-*.aep` of our synthetic corpus, each made by +one scripted change to a base project. Batch 1 (cases 000 to 126) was made in one chain of +Save As; batch 2 (cases 200 to 259) was made in later sessions, each case starting again from the +same loaded base; batch 3 (cases 299 to 354) was made in three further sessions (299 is a Save As +without any edit, the reference for save noise). The base project `000-base` is one composition `C` +(1920x1080, 25 fps, 5 s) holding one red solid layer `L` (1920x1080) in the folder `Solids`. 374 of +these cases (369 `.aep`, and the `.aepx` of `000`, `058`, `060`, `110`, `124`) are the test fixtures. They +are a few combined projects, one composition per case named like the case and rebuilt from the +same recipe (`crates/aep/tests/fixtures/CASES.md`; the generator is in EffectCraft, `crates/aep/tests/fixtures/tools/`), read from the +folder named by `CRAFT_AEP_FIXTURES` (opt-in); `crates/aep/tests/it/common/mod.rs` hands a test its case as a project of its own cut from +the combined file, and a test whose fixture is missing prints `SKIPPED: fixture missing` and passes. The tests named below run on them; +the `.aepx` cases are one pair, `aepx-pair.aep` and `aepx-pair.aepx`. The container +of every fixture is byte-identical to the generated file, with two exceptions that keep the +fixtures small and free of local data: the XMP packet after the container (which grows by 1.7 KB +with every save of the corpus chain) is replaced by the 5.8 KB packet of the base project in all +fixtures but `001` (and inside `` of the five `.aepx` fixtures), and in every fixture that imports a file (a footage item: `126`, `350`-`354` and the later footage cases) the +file path and machine name inside the footage alias JSON are replaced by neutral text of the same +length. + +**Read-back tests.** Some evidence comes from files we wrote ourselves (not After Effects), opened +in After Effects 2026 and read back value by value or rendered: an exporter in development, which is +not in this repository. They are named by an id (`e1`, `f1`, `o1`, `s1`, `t7`, `x1`-`x3`, ...) or by +their local folder (`export-tests\...`), which is not in the repository either. + +Confidence codes in the field tables: **V** = a test in `crates/aep/tests/` asserts that the decoded +value equals the value the case was made with (the corpus manifest); **E** = decoded and consistent +in the case diffs, but no manifest value to assert against (the field is exposed only where a test +pins what the fixtures contain); fields that the corpus does not decide (**?**) or only suggests +(**H**) are not decoded; they are listed in section 4. + +## 1. Container + +| Fact | Evidence | +|---|---| +| The file starts with `RIFX`, a big-endian `u32` size and the form type `Egg!`; all integers in the structure are big-endian (the one exception, `iide`/`idpi`, is little-endian). | All 139 files of batches 1 and 2. | +| The declared size is `4 + the chunks`; it ends before the end of the file. The bytes after it are an XMP packet (``, UTF-8 XML, 5.8 KB in `000`) that grows with every save. | All files; test `header_and_trailer_facts`. | +| A chunk is a 4-byte id, a big-endian `u32` body size and the body; an odd-sized body is followed by one pad byte, always `0` in the corpus (15 622 odd bodies). | Test `odd_sized_chunks_keep_their_pad_byte_even_when_not_zero` keeps any value. | +| The chunks of every file tile the container exactly: no leftover bytes, no chunk larger than its parent. | 139 of 139 files parse without a repair and write back byte for byte. | +| A `LIST` chunk's body is a 4-byte list type followed by chunks. List types seen include `Fold`, `Item`, `Layr`, `tdgp`, `tdbs`, `list`, `Pin ` and `FEE ` (the space is part of the type). | `000`; test `list_types_ending_in_a_space_are_kept`. | +| Lists can be empty (size 4, only the type): `Ewst`, `Pefl`, `CPPl`, `LItm`. | `000`; test `empty_list_and_list_shorter_than_its_type`. | +| Nesting: at most 13 levels in the corpus (the path of a shape layer, 240). | All files; test `nesting_depth_is_below_the_limit`. | +| `LIST btdk` is not a chunk sequence: its body (7775 bytes in `110`) is text. A reader must keep it opaque. Only files with a text layer have it. | `110`-`114`, `243`-`248`; test `raw_text_lists_are_kept_opaque`. | +| Three non-`LIST` ids hold a chunk instead of data: `tdsn`, `pdnm`, `fnam`. Each holds exactly one `Utf8` chunk (a name or label, UTF-8 text, possibly empty). | `tdsn` 31 209 times, `fnam` 40, `pdnm` 32 over the corpus; test `nested_chunk_ids_hold_one_utf8_chunk`. | +| Ids can end in a space; the space is part of the id. In the corpus this happens for the list types `Pin ` and `FEE `. All ids are 4 printable ASCII bytes. | `Pin `, `FEE ` in all files but `001`; tests `list_types_ending_in_a_space_are_kept`, `ids_ending_in_a_space_are_kept`. | +| Every payload that is decoded here is plain: no compression, no encryption. Text is readable, numbers are IEEE big-endian doubles or integers. Entropy and decompression probes (zlib, raw deflate, gzip, lzma, bz2, LZ4 block) over all chunk ids of the corpus found no compressed chunk, and consecutive saves of a project differ in only a few bytes. **One body is not understood: `opti` (footage and render options) has a plain 125-byte header and then a high-entropy body (7.9 bits per byte); whether it is compressed is open.** The high entropy of `sdat` is a flat histogram (five identity ramps 0..255), not random data. | `010` (the layer name `Renamed` is readable in a `Utf8` chunk), `040` (`100.0` and `200.0` as doubles). | + +### How the crate handles it + +- `parse` builds a tree of `Chunk { id, body, pad }`; a body is `Data`, `Chunks` (the three + nested ids), `List { list_type, children }` or `OpaqueList { list_type, data }`. The bytes after + the container are kept as the trailer. +- `write` recomputes every size from the tree. For every input that parses, `write(parse(x)) == x` + byte for byte, including pad bytes, an odd last body without a pad byte, and the trailer. The + tests assert this for all fixtures and for every damaged input that still parses. +- A `LIST` (or nested id) whose body is not a well-formed chunk sequence, or that is nested deeper + than `Limits::max_depth` (64), stays opaque instead of failing the parse. At the top level, a + chunk that does not fit, a wrong form type or a container larger than the input is an error. + Sizes are checked against the remaining input; nothing is allocated from a declared size; the + chunk count is bounded (`Limits::max_chunks`). + +### The XML form (`.aepx`) + +After Effects also saves a project as XML (`.aepx`). Every case of the corpus was saved in both +forms from the same state, the `.aepx` right after the `.aep`. Comparing each pair element by +element with the chunk tree of the `.aep` gives the mapping below. It holds for all 223 pairs of +the corpus (batches 1 to 3 and the 29 cases 355 to 383 of a fourth batch made the same way, which +this document does not use otherwise): the tree read from the `.aepx` is the tree of the `.aep`, and written back as an +`.aep` it gives the same bytes, apart from the save counter and the XMP packet (last row). + +| Fact | Evidence | +|---|---| +| The file is UTF-8 XML with the declaration `` and one root element ``. Its children are the top-level chunks of the `.aep`, in the same order. The `RIFX` header and the `Egg!` form type have no element. Indentation is tabs and line feeds; there are no comments, no entities and no carriage returns in any sample. | All pairs; `000`. | +| A data chunk is an element named by its id, with the body as lowercase hex in the attribute `bdata` and no content: ``. Every body of the `.aep` comes back byte for byte, including large ones (`cdat`, `ldat`, `opti`). | `000` (1 183 `bdata` elements, all equal but `head`, last row), all pairs. | +| A `LIST` is an element named by its list type, holding its chunks as child elements: ``, ``, ``, ``, ``, ``. An empty list is an element without children and without `bdata` (``, ``, ``, ``). The `LIST` id itself is not written. | `000`. | +| A trailing space of an id or list type is dropped: `Pin ` is ``, `FEE ` is ``. A name shorter than 4 characters is padded with spaces to read it back. | `000` (`FEE`, and `Pin` of the solid's footage), `126`. | +| The same name can be a list or a data chunk: `sspc` is a data chunk in a footage item (``) and a list in an effect instance (`` with children). Whether an element has `bdata` decides. | `000` (footage), `071` (Slider Control). | +| The three nested ids `tdsn`, `pdnm` and `fnam` are written like lists: an element with one child, the `Utf8` chunk. | `000` (`tdsn`), `071` (`pdnm`, `fnam`). | +| A `Utf8` chunk is `` with its text as content; an empty one is ``. The text is the chunk body exactly (no trimming). | `000` (`C`, `Solids`, the JSON strings of the colour settings, 19 empty ones), `010` (`Renamed`), `060` (`wiggle(1,10)`). | +| Two numeric chunks are written as text, in a `` child: `numS` (4 bytes, big-endian) as a decimal integer (only `0` is sampled, so whether it is signed is not decided; the reader accepts -2^31 to 2^32-1), and `ppSn` (8 bytes, an `f64`) with nine decimals (`150.000000000`, `0.000000000`). A `ppSn` value that is not a multiple of 10^-9 would be rounded by the XML form (no sample). | `000`, `124` (two compositions: two of each), all pairs. | +| `LIST btdk` (the text document, raw text in the `.aep`, see 3.10) is written like a data chunk: ``, the hex of the bytes after the list type. It is read back as an opaque list. | `110`-`114`, `243`-`248`, `334`-`340`. | +| The footage alias `alas` (a JSON object in the `.aep`) is the element `` inside ``, with one attribute per JSON key, in the same (alphabetical) order: `ascendcount_base`, `ascendcount_target`, `fullpath`, `platform`, `server_name`, `server_volume_name`, `target_is_folder`. The JSON writes the two counts as numbers, `platform` `Win` as `1` and `target_is_folder` `0` / `1` as `false` / `true`, and escapes a backslash of the path as `\\`. Rebuilt this way, the JSON equals the `.aep` body byte for byte. Other platforms and non-ASCII paths were not sampled. | `125`, `126`, `350`-`354` (`352`-`354`: an image sequence, `target_is_folder` `1`). | +| The XMP packet that follows the container of an `.aep` is the CDATA content of ``, a child of the root between the top-level `string` that follows `pdvc` and ``. It is not a chunk. | All pairs. | +| Pad bytes are not written. An odd body gets a zero pad byte when the tree is written as an `.aep`, which is what every `.aep` of the corpus has. | All pairs: the rewritten tree equals the `.aep` byte for byte. | +| The only differences inside the container are save state: the save counter, a big-endian `u32` at byte 16 of `head`, is one higher in the `.aepx` (only byte 19 changes in 222 pairs; in `314` it carries from `0x000000ff` to `0x00000100`), and the XMP packet has one more history entry. | All pairs. | + +**What the XML form leaves out.** In the corpus, nothing: every chunk of every `.aep` has its +element (the count per id agrees in all 223 pairs, apart from the `` children of `numS` and +`ppSn` and the renamed `alas`), and all 239 pairs of the current corpus read into the same chunk +tree (the local test `every_corpus_pair_gives_the_same_chunk_tree`). The reader still tolerates an +`.aepx` that lacks chunks: `elab`, `cmta` and `empd` are not read by the typed view, so a missing one +changes nothing it decodes, and a missing `tdbs` cannot be told apart from a property at its default +(the sparse rule of section 2): its value reads as the default. Elements that have no chunk +counterpart (a name that is not 1 to 4 characters) are skipped with their content. + +### How the crate reads an `.aepx` + +- `read_aepx` returns the same `AepFile` as `parse`; `parse_any` picks the reader by content (a + `RIFX` header, or an optional byte order mark and white space followed by `= 1 (51 200 at 200 %, 38 400 at 150 %) and stays 25 600 at 50 % | 000, 018, 316, 317 | V | +| start | 12 / 16 | i32 / u32 | layer start time = num / den seconds; den = composition timescale (25 600), 1 in a layer made by the precomp operation | 000, 021 (12 800 / 25 600 = 0.5 s), 124 | V | +| in point | 20 / 24 | i32 / u32 | **relative to the start**: absolute = start + in * stretch (the exact ratio above). **Fractional times are exact multiples of 1/25 600 s: 0.3333 s became 8 532/25 600 = 0.33328125 s, and setting the in point moved the out point with it (duration kept)** | 000, 019 (25 600 / 25 600 = 1 s), 021 (stays 0 while the layer starts at 0.5 s), 318 | V | +| out point | 28 / 32 | i32 / u32 | same convention; 5 s = 128 000 / 25 600. **For footage layers the denominator is the footage time base, not 25 600: 48 000 / 48 000 for the 1 s audio layer (the sample rate), 3 / 30 for the three-frame image sequence (the frame rate); start and in point keep 25 600** | 000, 018 (stays 5 s, the layer ends at 10 s), 019 (6 s), 021 (5.5 s), 316, 317 (stays 5 s, ends at 2.5 s / 7.5 s), 318, 351, 353-354 | V | +| name is user-set | 37 bit `0x01` | flag | clear while the layer shows its source's name (000, 124, new solids, default-named camera and light), set when named | 000, 010, 022, 110, 113, 124, 211 | V | +| guide layer | 37 bit `0x02` | flag | | 026 | V | +| adjustment layer | 38 bit `0x02` | flag | | 025 | V | +| 3D layer | 38 bit `0x04` | flag | always set on cameras and lights | 015, 251 | V | +| solo | 38 bit `0x08` | flag | | 014 | V | +| auto-orient | 38 bit `0x40` | flag | orients towards the point of interest: set on two-node cameras (byte 38 is `0x44`) and on all lights, clear on a one-node camera (`0x04`) | 256 (`0x44`), 251 (`0x04`), 252, 254 | V | +| null object | 38 bit `0x80` | flag | set on a layer created as a null | 022, 220 | V | +| **video switch** | 39 bit `0x01` | flag | the eye icon (`enabled`); off gives byte 39 = `06` | 222 | V | +| **audio switch** | 39 bit `0x02` | flag | `audioEnabled` (also changes on a solid); off gives `05` | 223 | V | +| **effects switch** | 39 bit `0x04` | flag | `effectsActive`; off gives `03` | 224 | V | +| motion blur | 39 bit `0x08` | flag | | 017 | V | +| locked | 39 bit `0x20` | flag | | 013 | V | +| shy | 39 bit `0x40` | flag | | 012 | V | +| collapse transformations | 39 bit `0x80` | flag | continuously rasterize; set from creation on shape and text layers | 024, 238 | V | +| source id | 40 | u32 | `idta@16` of the source item (solid, footage or comp); 0 for shape, text and camera layers, `0xffff_ffff` for lights | 000, 022, 124, 126, 252 | V | +| label | 61 | u8 | label colour index (1 red, 5, 8 blue, 15, ...); a footage layer copies the label of its footage item (audio 7, image sequence 3) | 000 (1), 124 (15), 126 (5), 351 (7), 354 (3) | V | +| name copy | 64..95 | ASCII, NUL padded | copy of the user-set name; empty while the layer is unnamed | 000 (empty), 010 (`Renamed`) | V | +| **blend mode** | 99 | u8 | Normal 2, Add 4, Multiply 5, Screen 6, Overlay 7, Difference 26 (each case changes only this byte); set by name (906): Soft Light 8, Hard Light 9, Darken 10, Lighten 11, Exclusion 25, Color Dodge 27, Color Burn 28; by render (907: a script enum sweep wrote codes 2-34, each code rendered over a test image and matched one mode): Classic Difference 12, Hue 13, Saturation 14, Color 15, Luminosity 16, Stencil Alpha 17, Stencil Luma 18, Silhouette Alpha 19, Silhouette Luma 20, Linear Dodge 29, Linear Burn 30, Linear Light 31, Vivid Light 32, Pin Light 33, Hard Mix 34; 23 / 24 render as Color Dodge / Burn there (taken as the classic variants, E); 3 is written for Dissolve and Dancing Dissolve; 21 / 22 are Alpha Add / Luminescent Premul (not told apart). The reader keeps every code beyond the first six raw | 000, 016, 225-228, 906, 907 | V (6 + 22), E (23, 24) | +| layer type | 128 | u32 | 0 AV (solid, footage, precomp, null), 1 light, 2 camera, 3 text, 4 shape | AV: 000, 022, 126; text: 110, 113, 243; shape: 238-242; camera: 251, 253, 256; light: 252, 254 | V | +| parent id | 132 | u32 | 0 = no parent | 000, 022 (L gets the id of the new null layer) | V | +| **light type** | 136 | u32 | 1 = spot, 2 = point (0 on every other layer); parallel and ambient were not sampled and are kept raw | 252, 254 | V | +| **track matte mode** | 107 | u8 | 0 = none, 1 = alpha, 2 = alpha inverted, 3 = luma, 4 = luma inverted; bytes 104..106 are 0 in every file. Setting a matte changes only this byte and the matte layer id on the target layer, and turns the matte layer's video switch off (byte 39 `07` -> `06`) | 402-408 | V | +| **track matte layer** | 160 | u32 | the id (byte 0) of the matte layer, anywhere in the composition: `0x1d` (`M`, above) in 403-406 and 408, `0x1b` (`L`, below its target) in 407; 0 without a matte. A mode with id 0 has no case (After Effects 2026 writes the id; before 23.0 the matte was always the layer directly above) | 403-408 | V | + +API: `LayerHeader` (`is_video_enabled`/`is_enabled`, `is_audio_enabled`, `is_effects_enabled`, +`is_auto_oriented`, `light_type`, `blend_mode`, `stretch` / `stretch_den`, `stretch_ratio`, +`in_point`, `out_point`); the same switches on `Layer`; `Layer::track_matte` +(`TrackMatte`, `MatteMode`; test `tests/matte.rs`). `stretch` is now the +numerator of the ratio (it was the whole multiplier before 50 % and 150 % were sampled). Tests: +`tests/header.rs`, `tests/layer_switches.rs`. The layer name itself is the `Utf8` child of the +`Layr` (empty while the name is the source's); the layer then shows the name of its source item +(`Project::layer_source(...)` then `Item::display_name`, the rule the importer uses). + +### 3.2 Composition header (`Item/cdta`, 204 bytes; the decoder needs the first 176) and renderer + +| Field | Offset | Type | Meaning | Evidence | Conf. | +|---|---|---|---|---|---| +| frame duration | 4 | u32 | time units per frame: 1024 at 25 and 30 fps, **800 at 29.97 fps, 1000 at 23.976 fps** | 000, 031, 229, 230 | V | +| timescale | 8 | u32 | time units per second: 25 600 at 25 fps, 30 720 at 30 fps, **23 976 at 29.97 and 23.976 fps**; fps = timescale / frame duration exactly as typed (29.97 is `23976 / 800`, not `30000 / 1001`) | 000, 031, 229, 230 | V | +| work area start | 28 | u32 | in time units | 035 (25 600 = 1 s) | V | +| work area end | 36 | u32 | start + duration in time units; `0xffff_ffff` = the whole composition | 000, 035 (76 800 = 3 s) | V | +| duration | 44 | u32 | in time units. **A duration is snapped to whole frames: 5 s at 29.97 fps is 120 000 units = 150 frames = 5.005005 s, at 23.976 fps 120 frames** | 000, 031, 032 (256 000), 229, 230 | V | +| background | 52..54 | u8 R, G, B | **8 bits per channel**: 0.5 is stored as 128 and reads back as 128/255 = 0.50196 | 000, 033, 231 | V | +| motion blur | 139 bit `0x08` | flag | the composition's switch | 038 | V | +| width, height | 140, 142 | u16, u16 | | 000, 030 (1280 x 720) | V | +| pixel aspect | 144 / 148 | u32 / u32 | numerator / denominator; **0.9091 is stored as the exact ratio 10 / 11 (read-back 0.90909090909091)** | 000 (1 / 1), 037 (2 / 1), 325 (10 / 11) | V | +| frame rate | 156 | u32 | 16.16 fixed point of the float32 rate (25 = `0x0019_0000`, 29.97 = 1 964 114 = 29.9700012, 23.976 = 1 571 291) | 000, 031, 229, 230 | V | +| shutter angle | 172 | u32 | degrees | 000 (180), 034 (90) | V | +| **shutter phase** | 180 | i32 | degrees: 0 by default, -90 = `ffffffa6`; the shutter angle at 172 does not change | 000, 326 | V | +| **display start** | 164 / 168 | u32 / u32 | the comp start timecode as `num / den` seconds: 0 by default; display start frame 100 at 25 fps is 102 400 / 25 600 = 4 s (the denominator is the timescale; at other frame rates it was not sampled) | 000, 327 | V (one sample) | +| renderer | `LIST PRin` / `prin` 4 | 32 ASCII | match name: `ADBE Escher` in the base, `ADBE Calder` in 039 | 000, 039 | V | +| renderer name | `prin` 52 | 32 ASCII | display name: `Classic 3D`, `Advanced 3D` | 000, 039 | V | +| composition name | `Item/Utf8` | text | | 000 (`C`), 124 (`Pre`) | V | + +The inert `ADBE Time Remapping` record of every AV layer has `tduM` = the source's duration in seconds: 5 for 5 s compositions (124, 257, 258), 3 and 2 for a 3 s and a 2 s composition (600, 601), 1 for the 1 s WAV (351), 0.1 for the three-frame sequence (353), 0 on solids and stills (000, 126). Every property's keyframe time scale (`tdb4` bytes 12 to 15) follows the composition (23 976 in every +property of `L` after 229 and 230). The corpus manifest calls the classic renderer +`ADBE Advanced 3d`; the file stores `ADBE Escher` / `Classic 3D`. API: `CompHeader::{time_base, +frame_rate_fixed, duration_units, shutter_phase, display_start}` (`display_start` is the exact +fraction). Tests: `tests/header.rs`, `tests/layer_switches.rs`. + +### 3.3 Items, footage and precomps + +| Field | Chunk path | Offset | Type | Meaning | Evidence | Conf. | +|---|---|---|---|---|---|---| +| item kind | `Item/idta` | 0 | u16 | 1 folder, 4 composition, 7 footage | 000 | V | +| item id | `Item/idta` | 16 | u32 | what a layer's source id refers to (`iide` holds the same number little-endian) | 000 (`0x1a` solid, `0x0d` comp), 022, 124 | V | +| item label | `Item/idta` | 58 | u8 | label colour of the item | 000 (1 solid), 124 (15 for `Pre`) | V | +| used comp | `Item/idpi` | 0 | u32 **little-endian** | a composition that uses another as a precomp layer gets one `idpi` per used composition | 124 (`C` uses `Pre`) | V | +| used comp count | `Item/idpc` | 0 | u32 little-endian | the number of `idpi` chunks: one per distinct composition shown (the same one twice counts once); the order of the `idpi` carries no meaning (an After Effects re-save reverses it) | 124, 257, 258, 600, 602 (1), 601 (2) | V | +| footage type tag | `Pin /sspc` | 22 | 4 ASCII | `Soli` for a solid, `png!` for a png | 000, 126 | V | +| footage size | `Pin /sspc` | 30, 34 | u32, u32 | width, height in pixels | 000 (1920 x 1080), 022 (100 x 100 null), 126 (8 x 8), 211, 212, 259 | V | +| footage name | `Pin /opti` | 26 (solid), 58 (file) | ASCII, NUL terminated | the item's own `Utf8` name is empty for footage | 000 (`L`), 022 (`Null 1`), 126 (`test8x8.png`), 211 (`S100`), 259 (`Blue`) | V | +| **solid colour** | `Pin /opti` | 10, 14, 18, 22 | 4 x f32 | ARGB, 0..1: red [1, 0, 0] is `1, 1, 0, 0`, blue [0, 0, 1] is `1, 0, 0, 1` | 000, 259 | V | +| **Photoshop layer** | `Pin /opti` (tag `8BPS`) | 14; 32, 36; 78, 82, 86, 90; 344 | i32 BE; 2 x u32 **LE**; 4 x i32 **LE**; UTF-8, NUL terminated | an item made from one layer of a `.psd`: the layer record's index in the file (bottom of the stack = 0; -1 is the merged image), the document's two sides (which is the width: **?**, the one sample is square), the layer's bounds top, left, bottom, right in document pixels (all 0 for a layer without pixels, such as an adjustment layer) and the layer's name. The item's size (`sspc` 30 / 34) is the bounds' size with Retain Layer Sizes, else the document's. `Footage::psd_layer` | the project of issue 3087: ten layers, each index, bounds and name equal to the `.psd`'s layer record at that position (`Layer 1` `[9, -346, 1083, 1086]`, item 1432 x 1074; `test` `[749, 800, 764, 848]`, item 48 x 15; 32 and 36 hold 1000, 1000 in every record, the `.psd`'s size) | V | +| file path | `Pin /Als2/alas` | key `fullpath` | JSON string | alias JSON of a file footage item | 126 (the fixture holds a neutral path) | V | +| precomp linkage | `Layr/ldta` | 40 | u32 | the layer's source id is the id of the precomp's item | 124 | V | + +Footage items beyond solids and stills (`Pin /sspc`, 222 bytes; audio and image sequences, batch 3): + +| Field | `sspc` offset | Type | Meaning | Evidence | Conf. | +|---|---|---|---|---|---| +| file type tag | 22 | 4 ASCII | `png!`, `Soli`, **`WAVE`**; `TPIC` Targa (650), `8BPS` Photoshop (651), `TEXT` for both an Illustrator / PDF file (652) and an EPS (653); all four stills store the duration 0 / 600 | 126, 000, 350, 650-653 | V | +| width, height | 30, 34 | u32, u32 | 0 / 0 for audio; 64 x 64 for the sequence | 350, 352 | V | +| **duration** | 38 / 42 | u32 / u32 | seconds as `num / den`, unreduced: still 0/1, **WAV 48 000/48 000 (the sample rate is the denominator), image sequence 3/30 (the frame rate is the denominator)** | 126, 350, 352 | V | +| native frame rate | 56 | u32 | 30 for the sequence, 0 for stills, audio and solids | 126, 352 | V | +| frame rate (again) | 150 | u32 (unaligned) | the same rate as @56 for sequences and clips: 30 (353, 603), 25 (606, 612); 0 for stills and audio. Conforming a sequence to 25 fps (615 against its reference 614) changes @42 (the duration denominator), @56 and @150 from 30 to 25 together; for clips see @146 | 353, 603, 606, 612, 614, 615 | V | +| conformed rate of a clip | 146 | u32 (unaligned) | the rate a clip is conformed to (Interpret Footage), 0 when not conformed; the effective rate is then also at @150, while @38 / @42 (the duration in native frames over the native rate) and @56 stay native: the 25 fps 25-frame mp4 conformed to 30 stores 25 / 25, @56 25, @146 30, @150 30 (645 against 644), the layer's Time Remapping maximum becomes 25 / 30 s. A conformed image sequence keeps @146 at 0 and stores the new rate at @42, @56 and @150 (615) | 615, 644, 645 | V | +| bits per pixel | 60 | u32 | RGBA still 32, RGB sequence 24, 0 for solids and audio | 126, 352 | V | +| **sample rate** | 160 | f64 | 48 000.0 for the WAV; the same for an mp4 with sound (48 000.0 and 44 100.0 read back from AAC tracks of those rates), absent for an mp4 without (the importer takes a clip's audio from it) | 350, read-back vid-audio | V | +| **file size** | 208 | u32 | bytes of the source file(s): png 149, WAV 96 044 (44 + 48 000 x 2), three png of 168 bytes 504 | 126, 350, 352 | V | +| **sequence numbering** | 172, 176, 180 | u32 x 3 | first and last frame number and the digits of a sequence: 1, 3, 3 for `seq_001.png`..`seq_003.png` (353), 101, 103, 4 for `shot_0101.exr`..`shot_0103.exr` (603); 0 for single files (604, 605, 607). The name around the number is the pair of `Utf8` chunks between `Als2` and `opti` in `Pin ` (`seq_` / `.png`, `shot_` / `.exr`), absent on single files. **An empty prefix is not written**: `0001.png`..`0005.png` leave one `Utf8` (`.png`) there, so a single `Utf8` is the prefix when the first file name in `opti` (byte 58: `0001.png`) starts with it and the suffix when it ends with it; without that evidence the reader takes one starting with `.` as the suffix and reads nothing else. `Item::sequence_info`, `SequenceInfo::file_name` | 353, 603, 604, 605, 607; the prefix-less sequence of issue 3174 (After Effects 25.2) | V | +| **sequence file list** (Force alphabetical order) | `Pin /LIST StVc` | `StVS` (4 bytes, `u32` LE), then `Utf8` x count | a sequence imported with Force alphabetical order has, between `Als2` and `opti`, a `LIST StVc` instead of the prefix and suffix `Utf8`s: `StVS` holds the file count as a **little-endian** `u32` (`05 00 00 00`), followed by one `Utf8` per file name in order (`shot_0001.png`..`shot_0005.png`). The numbering at @172 / @176 is then `0xFFFFFFFF` and the digits @180 0; duration and rate are stored as for a numbered sequence (5/30, 30). The list replaces the numbering; a list without a readable `StVS` count, or with a name that is not a plain file name (`/`, `\`, `:`, a control character such as NUL, `.`, `..`), is not read. Without a stored item name the importer names the item after its first listed file (an assumption: what After Effects shows was not sampled). `SequenceInfo::files`, `SequenceInfo::nth_file_name` | the alphabetical sequence of issue 3174 (After Effects 25.2) | V | +| **sequence folder time** | 118 | u32 (unaligned) | seconds since 1904-01-01 UTC: the modification time of a sequence's folder when After Effects scanned it (860: 0xe6fb443a = 2026-10-19 03:51:22, the folder's and its files' time). With the folder's time After Effects keeps the stored numbering on open; with another (an older time, the first or the last file's time while the folder's differs: x1, x2 against x3) it scans the folder again and warns about a gap in a modal dialog | 860, `export-tests\sparse860\exp` x1-x3 | V | +| still duration denominator | 42 | u32 | 1 for png (126, 607), 600 for jpeg (605), 100 for OpenEXR (604): a still's duration is 0 over a per-format denominator | 126, 604, 605, 607 | V | + +An **image sequence is ONE item** (`opti` holds the first file name `seq_001.png` at 58, 322 bytes like +a still, with the width and height at 20 and 24 and the PNG colour type at 36); its alias JSON points +at the sequence **folder** (`"target_is_folder":true`, `ascendcount_target` 2). The audio item has its +name in the item's `Utf8` (`test-tone.wav`), label 7 (sequence 3, still 5); its `opti` has no display +name. A footage layer shows the item's name while it has no name of its own (351, 354). + +Test: `tests/header.rs` (precomp), `tests/text_markers_footage.rs` and `tests/batch3_objects.rs` +(footage), `tests/layer_switches.rs` (solid colour). API: `Footage::{duration, native_frame_rate, +bits_per_pixel, file_size, audio_sample_rate, is_sequence}`; `Item::sequence_info` (with +`SequenceInfo::frame_count`). + +### 3.4 Properties: sparse storage, static values and units + +A layer's property tree contains a `tdbs` only for a property whose value differs from the default +that After Effects computes for the layer and composition. A reader supplies the defaults: + +| Property (match name) | Stored | Unit in the API | Default when absent | Evidence | Conf. | +|---|---|---|---|---|---| +| `ADBE Position` | f64 x, y, z | pixels | the composition centre `[width / 2, height / 2, 0]` | 000, 040 (`100, 200, 0`), 030 (the comp becomes 1280 x 720, L stays 1920 x 1080: `960, 540, 0` is now stored), 211, 212 (absent on new solids) | V | +| `ADBE Anchor Point` | f64 x, y as a **fraction of the layer's source size**, z in pixels | px = fraction * source size | `0.5, 0.5, 0` (the layer centre) | 044 (`10, 20` px on 1920 x 1080 is `10/1920, 20/1080`), **211 (100 x 100 solid: `10, 20` is stored `0.1, 0.2`), 212 (400 x 300 solid: `100, 50` is stored `0.25, 1/6`)**: the composition size is not the divisor | V | +| `ADBE Anchor Point` of a **text** layer | f64 x, y, z (a text layer has no source) | pixels, as stored | `0, 0, 0` (the text origin) | absent in every other text sample (110-114, 243-248, 334-340, 386); **385 (text anchor set to `10, 20`) stores `10, 20, 0` as f64 pixels**, not a fraction of a size; test `a_stored_text_anchor_is_pixels` | V | +| `ADBE Scale` | f64 fractions | percent (fraction * 100) | 100 % | 000, 041 (`0.5, 0.5, 1.0`) | V | +| `ADBE Rotate Z` | f64 degrees | degrees | 0 | 000, 042 | V | +| `ADBE Opacity` | f64 fraction | percent (fraction * 100) | 100 % | 000, 043 (`0.25`) | V | +| mask feather | f64 x, y | pixels | `[0, 0]` | 090, 091 (`20, 20`), 208 | V | +| mask opacity | f64 fraction | percent | 100 % | 090, 091 (`0.5`) | V | +| mask expansion `ADBE Mask Offset` | f64 | pixels | 0 | 090, 091 (5) | V | +| effect slider | f64 | as set | the `pard` default | 071 (77) | V | +| effect colour | 4 x f64, ARGB 0..255 | ARGB fractions | the `pard` default | 073 (`[0.2, 0.6, 1]` is `255, 51, 153, 255`) | V | +| shape stroke width, round corners radius, light intensity | f64 | as set (pixels, pixels, percent) | not decoded as defaults except the light (100) | 239 (8), 238 (20), 254 (50) | V | +| shape group position, gradient start and end | f64 x, y | pixels | group position `[0, 0]` | 242, 241 | V | +| camera Position, point of interest | f64 x, y, z | pixels | see 3.12 | 251, 253, 256 | V | +| camera Zoom, light colour, cone angle, cone feather | f64 / ARGB 0..255 | pixels, `[A, R, G, B]` fractions, degrees, percent | Zoom 2 666.67 (1920 px comp), colour white, cone angle 90, cone feather 50 | 341, 343-345 | V | + +`Project::layer_anchor_px` multiplies the anchor fraction by the size of the layer's source (a +solid or footage item, or the composition of a precomp). `Transform::text_anchor_px` gives the +anchor of a text layer (pixels as stored, `[0, 0, 0]` when absent). + +**Explicit defaults (batch 3).** A value record exists exactly when the value differs from the +default; setting a value to its default never creates a record and setting it back removes it. A +Gaussian Blur read back as Blurriness **25** when added (the corpus manifest's "0" for rows 214 and +216 was wrong, with a correction note in the manifest); Blurriness set to 0 writes a record, 25 -> 40 -> 25 +leaves the effect subtree byte-identical to the never-touched default (300, 301, and 214 / 078). +The same holds for Fill Opacity 1 -> 1 and 1 -> 0.5 -> 1 (302, 303) and Slider 0 -> 0 (304), and +for the five transform properties set to the value they already had (Position, Opacity, Anchor, +Scale, Rotation, 311-315: the layer tree is byte-identical to the unedited save 299). A writer may +therefore rely on "absent = default" and drop a record that equals the default. Exceptions are +records AE materialises together with a type switch (polygon, radial gradient: 3.9). +`EffectParam::is_default` returns this; `Tracked::source` tells `Default` from `Stored`. + +**Time Remapping (batch 3).** Every layer has an inert `ADBE Time Remapping` property at the root of +its tree (`tdsb` 3, static value 0, no keys). Enabling the remap turns it into a keyed property +(`tdsb` 1, `tdb4` byte 5 bit 0 cleared, byte 68 = 1, no `cdat`) with two plain 48-byte keys whose value +(seconds) is at byte 8: 0 s -> 0 and 5 s -> 5 on a precomp layer (319), 0 s -> 0 and 0.1 s -> 0.1 on an +image-sequence layer (354). It cannot be enabled on a solid. API: `Layer::time_remap` (`TimeRemap`, +`TimeRemapKey`). + +Property record (`LIST tdbs`: `tdsb`, `tdsn`, `tdb4`, then `cdat` or a `LIST list`, optionally a +`Utf8` expression, `tdum`, `tduM`): + +| Field | Chunk path | Offset | Type | Meaning | Evidence | Conf. | +|---|---|---|---|---|---|---| +| magic | `tdb4` | 0..2 | `db 99 00` | every property | all fixtures | V | +| components | `tdb4` | 3 | u8 | values in `cdat` / in each key (1, 2, 3, 4 = ARGB) | 040, 041, 043, 073, 091, 206, 208, 210 | V | +| static flag | `tdb4` | 5 bit 0 | flag | set while the property has no keys (Position: 15 static; the bit is clear on an animated property) | 040, 055, 058 | V | +| **template flag** | `tdb4` | 7 | u8 | 0 = plain keyframe template, non-zero = spatial template (3 on Position, 1 on colours and paths) | 204-206, 208, 210 | V | +| time scale | `tdb4` | 12 | u32 | units per second of the keyframe times (25 600; 30 720 at 30 fps; 23 976 at 29.97 and 23.976 fps) | 055, 058, 122, 229, 230 | V | +| has keys | `tdb4` | 68 | u8 | 1 exactly when the property has a `LIST list` | every fixture (test) | V | +| keyed spatial-template flag | `tdb4` | 79 | u8 | 1 on a static colour or point effect value, 0 once it is keyed (359 / 364, 369 / 382); 0 on keyed and static sliders (362 / 363, 391 / 397); meaning **?** | 359, 362-364, 369, 382, 391, 397 | V (values) | +| expression flags | `tdb4` | 76, 77, 120 | u8 | all three are 1 when an expression exists. 76 and 77 are also 1 on a camera's or light's computed (auto) Position, which has no expression | 060, 213, 251 | V | +| **expression disabled** | `tdb4` | 119 | u8 | 1 = the expression is disabled; the text and bytes 76, 77, 120 stay. On the built-in view layers the byte flips by itself after the first save, so it counts only together with an expression | 060 (0), 213 (1) | V | +| state | `tdsb` | 0 | u32 | 1 = written (non-default value, keys or expression), 3 = default state. **A layer, camera, light, shape or text property in the default state holds After Effects' default** or a value with no effect on that layer (survey of 839 corpus and sample files: Material Options, cone 90 / 50 and falloff 500 / 500 of point lights, Position `[0, 0, -1333.33]` of ambient and environment lights, Opacity 1 and Scale `[1, 1, 1]` of cameras and lights, a polygon's Inner Radius 50, Miter Limit 4, the inert Time Remap 0), so the importer skips it. **An effect parameter's record in the default state holds the effective value** (3.7, stored value) | 040, 071, 073 (1); 3 on the unwritten properties of 000; 1200, 1400 (effects) | V (1), E (3), V (effects) | +| static value | `cdat` | 0 | `components` x f64 | the first `components` doubles are the value | 040, 041, 043, 071 | V | +| user name | `tdsn/Utf8` | | text | `-_0_/-` means "no custom name" | 091 (`Mask 1`), 238 (`Group 1`) | V | + +Test: `tests/values.rs`, `tests/typed.rs`, `tests/keyframes.rs`. + +### 3.5 Keyframes (`tdbs/list`: `lhd3` + `ldat`) + +`lhd3` (13 `u32`): word 0 `0x00d0_0bee`, word 2 the record count, word 3 `ceil(count / 4)`, word 4 +the record size, word 7 the count rounded up to a multiple of 4, words 8 to 12 zero; `ldat` is +exactly `count * record size` bytes (cases 050, 055; every list of every fixture). In path lists +(record size 8) words 3 and 7 are allocation capacities in vertices and four times that (12 records: +4 and 16; 9 records: 4 and 16 in the shape paths of 105 and 240, 3 and 12 in the open mask path 233), +not a function of the count. + +**Record header (8 bytes, every kind).** + +| Field | Offset | Type | Meaning | Evidence | Conf. | +|---|---|---|---|---|---| +| time | 0 | i32 | in the property's time scale; **layer time** (roving moved key 2 from 25 600 to 26 509 = 1.0355078125 s) | 055 (0, 25 600, 64 000), 056, 058 | V | +| **interpolation in** | 4 | u8 | the incoming side: 1 = linear, 2 = bezier, 3 = hold | 202 (in linear, out hold: `01 03`), 203 (in hold, out linear: `03 01`), 204, 205, 052, 053 | V | +| **interpolation out** | 5 | u8 | the outgoing side, same codes | same | V | +| label | 6..7, bits 6..9 | u16 | keyframe label: label 9 turns the flags `0x0007` into `0x0247` | 057 | V | +| roving | 6..7, bit `0x0020` | u16 | `0x0007` becomes `0x0027` | 056 | V | + +A hold key has no further field (the value is unchanged); a linear key has all ease slots 0. Keys +added through the scripting interface are linear in and out. + +**The template follows the property header (`tdb4` bytes 3 and 7), not the record size.** With +`n` components: + +| Template | `tdb4[7]` | Size | Used by | Evidence | +|---|---|---|---|---| +| plain | 0 | `8 + 40 n`: 48 (n=1), 88 (n=2), 128 (n=3) | Opacity, Rotation, Slider (1); Mask Feather, Rectangle Size (2); Scale (3) | 205, 206, 208, 221 | +| spatial | non-zero | `56 + 24 n`: 128 (n=3), 152 (n=4) | Position (3), colours (4) | 204, 210 | +| mask path | | 64 | the path property of an animated mask (the path itself is in `shap`) | 093 | +| marker | | 16 | `mrst` marker times | 122, 123, 249 | + +A 128-byte record is a Scale key (plain, 3 components) or a Position key (spatial): a reader must +look at the header (206 against 204). Layout of the plain template: value (`n` x `f64`) at 8, then +`4 n` ease doubles in **type-major order**: `[in speed x n][in influence x n][out speed x n][out +influence x n]`, starting at `8 + 8 n` (for `n = 1`: **at 16 in speed, at 24 in influence, at 32 +out speed, at 40 out influence**). Scale key 1 of 305 (`n = 3`, in 0 / 33 %, out 20 / 66 %) is +`0,0,0, .33,.33,.33, .2,.2,.2, .66,.66,.66`; Mask Feather key 1 of 306 (`n = 2`, in 0 / 33, out +15 / 66) is `0,0, .33,.33, 15,15, .66,.66`. Component `i` uses slot `i` of each block (**V** for the +block layout and the units, Scale speed in fractions per second and Mask Feather speed in pixels +per second; **E** that different values per dimension sit in the slot of their dimension, because +the tool that made the corpus applies one ease to all dimensions; **V** since the exporter wrote three different eases for the three Scale dimensions and After Effects read the same three back, aep-export.md R13). `Keyframe::ease_component(i)` +returns one component's `KeyEase`, `Keyframe::ease_components` all of them. Layout of +the spatial template: `u32` at 8 (1 normally, 0 after the spatial auto-bezier and continuous +switches were turned off together, 054), `f64` arc length of the segment to the next key at 16 +(100 in 204 key 1, 0 on the last key and right after creation; safe to ignore), **ease at 24 in +speed, at 32 in influence, at 40 out speed, at 48 out influence**, value (`n` x `f64`) at 56, spatial +in tangent (`n` x `f64`, relative offset from the value) at `56 + 8 n`, out tangent at `56 + 16 n`. + +| Field | Where | Meaning | Evidence | Conf. | +|---|---|---|---|---| +| ease, Position | spatial @24..55 | 204 key 1: in speed 5 / influence 0.2, out speed 50 / influence 0.8; key 2: in 7 / 0.6, out 9 / 0.4. Speed in pixels per second, influence a fraction. **After Effects reports key 1's in speed and the last key's out speed as 0, but the file keeps the requested values (5 and 9): ignore those two slots** | 204, 052 (preset: speed 0, influence 0.33) | V | +| ease, Opacity | plain n=1 @16..47 | 205 key 1: in 0.05 / 0.2, out 0.2 / 0.8; key 2: in 0.3 / 0.6, out 0.09 / 0.4. Speed is in stored units per second, i.e. 100 times smaller than the percent per second shown in the UI; influence a fraction | 205 | V | +| value, Scale | plain n=3 @8 | 206: `[1, 1, 1]` and `[2, 1.5, 1]` (fractions of the manifest percent) | 206 | V | +| value, Rotation, Slider | plain n=1 @8 | degrees / as set (keyed slider 10 and 90) | 221 | V (slider), E (rotation, 207 is not a fixture) | +| value, Mask Feather | plain n=2 @8 | pixels `[0, 0]` and `[40, 20]` | 208 | V | +| value, colour | spatial n=4 @56 | ARGB doubles 0..255: `[255, 255, 0, 0]` and `[255, 0, 127.5, 255]`; flags `0x0001`, tangents zero; the project-level `EfdG` copy of the effect has the same list | 210 | V | +| value, Position | spatial n=3 @56 | pixels | 055 (`[0,0,0]`, `[100,0,0]`, `[200,100,0]`), 056 | V | +| tangents | spatial @`56+8n`, `56+16n` | 054: key 1 out `[30, 60, 0]`, key 2 in `[-30, -60, 0]` | 054 | V | +| arc length | spatial @16 | 100 on key 1, 0 on key 2 | 204 | E | +| **colour distance** | spatial n=4 @16 | for bezier colour keys the Euclidean ARGB distance to the next key, 255 sqrt(2) = 360.6245 for red to blue, 0 on the last key; linear colour keys have 0 (like the Position arc length, filled only for non-linear interpolation). The ease slots of a colour key are one entry (speed 0, influence 0) | 307 against 210 | V | +| **keyed Orientation** | `otst`: `tdbs` key list of 80-byte records (time, interpolation sides, flags at 0..7; `f64` 2.0 at 16 on the first key; the rest 0 for linear keys) and `otky` with one `otda` (three `f64` degrees) per key, in the same order. **After Effects interpolates by a quaternion slerp of the rotation `Rx Ry Rz`**: 703 (keys `[0,0,0]` at 0 s, `[10,20,30]` at 2 s, linear) reads back 0.5 s `[3.434, 4.469, 7.713]`, 1 s `[6.264, 9.353, 15.219]`, 1.5 s `[8.465, 14.560, 22.610]`, which slerp with that order reproduces to 0.001 degree (not per-component: 5 / 10 / 15 at 1 s; the order `Rz Ry Rx` gives `[3.58, 10.64, 14.32]`) | 703 | V (layout, linear), H (ease of bezier keys) | +| **light type** | `ldta` `u32` at 136: 0 parallel (701), 1 spot, 2 point, 3 ambient (702). A light created as an environment light by script without the Advanced 3D renderer is stored as ambient (704) | 701, 702, 704 | V | +| **ease, Anchor Point and effect points** | spatial @24..55 | the value is a fraction of the layer size, and **a speed is pixels per second divided by the layer height**: out speed 50 is 50 / 1080 = 0.046296 on the 1920 x 1080 L (597 Anchor Point, 598 Gradient Ramp Start), 50 / 800 = 0.0625 on a 400 x 800 solid (730; not the width, not the smaller side, not the composition height); influence a fraction. After Effects reads 597 back as 0.5 s [1004.41, 562.21], 1 s [1084.84, 602.42], 1.5 s [1137.13, 628.57] | 597, 598, 730 | V | +| **ease, colour switched to bezier** | spatial n=4 @24..55 | keyframe.set_interpolation bezier on two colour keys stores speed 0 and influence 0 on both sides, and After Effects interpolates them linearly (598 Start Color red to blue: 0.75 / 0.5 / 0.25 red at 0.5 / 1 / 1.5 s); a custom colour ease cannot be set by script | 598 | V | +| **ease, mask path** | 64-byte record @24..55 | in speed, in influence, out speed, out influence as in the spatial template: 599 out / in influence 0.75, 700 0.2 / 0.5, speeds 0 (the path at 0.5 s is 5.42 % / 28.0 % of the way). The `f64` at 16 is 1 (093) or 2 (599, 700) on the first key and 0 on the last (not decoded) | 093, 599, 700 | V (influence), ? (speed unit) | + +API: `Keyframe::{interpolation_in, interpolation_out, kind, value, ease, ease_component, ease_components, spatial}` (the `f64` at byte 16 of a colour key is `SpatialKey::segment_length`); +`Property::keys()` hands the property's template to its records. Marker record (16 bytes): time, +`03 03` hold bytes, 8 stale bytes. Mask path record (64 bytes): the common fields and the ease at byte 24 (599, 700). Test: +`tests/values.rs`, `tests/keyframes.rs`. + +### 3.6 Expressions + +| Field | Chunk path | Meaning | Evidence | Conf. | +|---|---|---|---|---| +| source | `tdbs/Utf8`, after `cdat` / `list` and before `tdum` | raw UTF-8 text, no length prefix, no NUL, no engine tag | 060 (`wiggle(1,10)` on Opacity) | V | +| flags | `tdb4` 76, 77, 120 | all 1 when present, all 0 otherwise | 060, 040 | V | +| **disabled** | `tdb4` 119 | 1 when disabled (`expression.disable_all`); the only byte that differs between 060 and 213 | 060, 213 | V | +| static value | `cdat` | kept while an expression exists (Opacity 1.0) | 060 | V | +| **on an effect parameter** | the parameter's own value record, as on any property: Slider Control's Slider with `time*10` holds the text and the static value 0 | 534 | V | + +The expression engine is project-wide (`LIST ExEn/Utf8`, `javascript-1.0`). API: +`Property::expression_enabled`. Test: `tests/keyframes.rs`. + +### 3.7 Effects (`tdgp[ADBE Effect Parade]/sspc`) + +| Field | Chunk path | Offset | Type | Meaning | Evidence | Conf. | +|---|---|---|---|---|---|---| +| match name | the `tdmn` before the `sspc` | | text | `ADBE Slider Control`, `Pseudo/@@S1iPXtJFTHK4QaDbgJvLhw`, ... | 071, 073, 077, 080, 214 | V | +| instance name | `sspc/fnam/Utf8` | | text | the effect's own name (`Slider Control`, `Tint`); it stays the same when the instance is renamed (610) | 071, 073, 077, 080, 610 | V | +| **user name of an instance** | `sspc/tdgp/tdsn/Utf8` (the value group's name) | | text | `-_0_/-` (the placeholder every unnamed group has) while the instance shows the effect's name; the given name otherwise (610: `My Tint`, `fnam` still `Tint`). `Effect::user_name`, `Effect::display_name` | 356, 609, 610 | V | +| **fx switch** | `sspc/tdgp/tdsb` (the value group's flags, `u32`) | | flag | 1 on, 0 switched off in the Effect Controls (`fx-switch.aep`: two Gaussian Blurs on one layer in one save, the first switched off, the second on; read back `enabled` false / true). `Effect::enabled` | fx-switch | V | +| parameter count | `sspc/parT/parn` | 0 | u32 | including the implicit input layer and the built-in entry (3 for a slider) | 071 | V | +| parameter match name | `parT/tdmn` | | text | `-NNNN`; the last is `ADBE Effect Built In Params` | 071 | V | +| parameter type | `parT/pard` | 12 | u32 | 0 layer, 2 fixed slider (16.16), 3 angle, 4 checkbox, 5 colour, 6 point, 7 popup, 9 no data, 10 float slider, 12 path, **13 group start / 14 group end** (Exposure's Master, Red, Green and Blue twirl-downs; the end repeats the group's name; no value), **15 button** (Swap Colors of Tint and Gradient Ramp: empty name, label in `pdnm`) | 071, 073, 077, 080, 214, 215, 356, 368, 389 | V | +| UI flags | `pard` | 4 | u32 | 0x20 greyed out, 0x08 on a group end. **Stale:** After Effects does not reset it on undo (391-397 keep the flags of 390 although Channels is back to Master), so it is UI state and never read for meaning | 389-397 | V (values), E (meaning) | +| parameter name | `pard` | 16 | 32 ASCII | `Slider`, `Color`, `Menu`, `Blurriness`, `Shadow Color`, ... (empty for some checkboxes) | same | V | +| **default** | `pard` | 56 | by type | float slider: f64 (Slider 0, **Blurriness 25**); fixed slider and angle: 16.16 (drop shadow opacity 127.5, direction 135, distance 5, softness 0; Fill opacity 1.0 = 100 %; **Tint Amount to Tint 100, Ramp Scatter 0, Blend With Original 0**); **colour: ARGB bytes (drop shadow `ff000000` black, Fill `ffff0000` red; Ramp Start `ff000000`, End `ffffffff`; Tint Map Black To `00000000` and Map White To `00ffffff`: alpha 0, which is what After Effects reads back)**; popup: u32 index (1); **point: two 16.16 fractions of the layer size at 56 and 60 (Point Control 0.5, 0.5; Ramp Start 0.5, 0 and End 0.5, 1)** | 071, 077, 080, 214, 215, 356, 368, 383 | V | +| **valid maximum** | `pard` | 128 / 108 | 16.16 / f32 | the largest valid value of a fixed slider (128: Tint Amount 100, Ramp Scatter 512, Blend With Original **1.0**) and of a float slider (108: Blurriness 30 000; **Exposure 100, Offset 2, Gamma Correction 10**). The stored scale differs per slider (below), so this is the reader's only hint at it | 356, 368, 078, 389 | V | +| **float slider valid minimum, slider range** | `pard` | 104; 112 / 116 | f32; f32 x 2 | the smallest valid value (Exposure -100, Offset -2, Gamma Correction 0.1 as f32) and the range the slider covers (Exposure -4..4, Offset -0.5..0.5, Gamma 0.1..10); the slider range is repeated as `tdum` / `tduM` (f64) in each value record (391-394). @120 holds the default again as f32 (Gamma 1.0, Blurriness 25), u16 @124 the display decimals (**H**: Exposure 2, Offset 4) | 389, 391-394 | V | +| **definitions of a second instance** | top-level `LIST EfdG` | | | one `EfDf` per effect TYPE (`tdmn` = match name, then a copy of ONE instance's `sspc`, including that instance's value records); the `EfDC` count before them is a little-endian u32. When two layers carry the same effect type, only one instance keeps a full `parT`; **the other has an empty `LIST parT` (4 bytes)** but its own `tdgp` (input layer `-0000` with its own `tdpi`, the button record, and its value records). Its definitions come from the `EfdG` copy by match name, its values from its own records, never from the copy (383: the copy holds S100's Start [0.1, 0.2]; L's Ramp reads the 368 defaults). Which instance keeps the full `parT` is **?** (in 383 S100 is both first in the file and newest). The `EfDf` order follows the stack order (365 / 366); `Pefl/pjef` does not. **Some files have no `EfdG` at all** (seen in 17 projects, all from inside After Effects-made Motion Graphics templates). In each of them every effect type (196 in all; 2 to 14 Color Controls per file) has exactly one instance with a full `parT` and an empty one in every other instance, and the reader takes the others' definitions from that instance (`DefinitionSource::OtherInstance`, #3170). Which instance keeps it is **?** here too | 365, 366, 383; templates | V | +| popup items | `parT/pdnm/Utf8` | | text | items separated by `\|` | 077 (`Item 1\|Item 2\|Item 3`), 214 | V | +| stored value | `sspc/tdgp/-NNNN` | | `tdbs` | present only for a parameter that differs from its default; `tdsb` 1, `cdat` as in 3.4. **Absent record = the `pard` default.** Some parameters are recorded in the default state (`tdsb` 3) and the record still holds the value After Effects uses: every one of the 25 such records in the corpus and the samples differs from its `pard` default and reads back as recorded (Lumetri Color's hidden controls High Dynamic Range, HDR Specular, the second Look, Legacy Tone And Saturation, Face Detection, Auto Color, Auto Intensity and SemanticAutoTone Progress, 1200; Cryptomatte's Selection Mode on, 1400). No effect record in the default state holds a value that does not count. The reader takes the value in either state (`EffectParam::recorded_value`, `EffectParam::value`); `EffectParam::stored_value` keeps to written records, and a record in any other state (no sample has one) is not read: the importer reports it as damaged data. That other effects record values so is H (no sample shows one) | see below; 1200, 1400 | V (1200, 1400), H (other effects) | + +Stored values by type (`tdsb` 1, or 3 as above): + +| Type | Stored | Evidence | Conf. | +|---|---|---|---| +| float slider | `cdat[0]` as set (Slider 77, Blurriness 40); a keyed slider has 48-byte plain records and no `cdat`. **The value is the float32 After Effects keeps, widened to f64: Offset 0.1 is `0.10000000149011612`, Gamma 2.2 is `2.200000047683716`** | 071, 216, 221, 393, 394, 397 | V | +| **group start / end** | the record always exists (`tdsb` 1, `cdat` 0, descriptor `00010000`), `tdsn` = the group name; no value (scripting: NO_VALUE) | 389-397 | V | +| **fixed slider** | `cdat[0]` as a plain double in the parameter's own scale: Tint Amount to Tint is a **percent** (0 -> 0.0, 37.5 -> 37.5; valid max 100), Gradient Ramp Scatter is **pixels** (12, 250.5; valid max 512), Blend With Original is a **0..1 fraction** (25 % -> 0.25, 100 % -> 1.0; valid max 1.0). Keyed: 48-byte plain records with the plain value (Amount 20 / 80) | 361-363, 378-381 | V | +| colour | ARGB doubles 0..255 (Tint Map Black To [0.2, 0.4, 0.6] -> `[255, 51, 102, 153]`, float32 precision; Ramp Start Color red `[255, 255, 0, 0]`); keyed: 152-byte spatial records with the ARGB value at 56 (210 Fill, 364 Tint Map White To) | 073, 357, 371; keyed: 210, 364 | V | +| **button** | the record always exists (`tdsb` 1, `cdat` 0, descriptor `00010000`) and carries no value (scripting: NO_VALUE). An exception to the sparse rule, like the Layer Control record | 356-383 | V | +| **popup (built-in)** | 1-based index as a double: Ramp Shape Radial = `2.0`; the selection is also written to `pard` @56 (only byte 59 changes, as for the dropdown 324). Default Linear = 1, item count u16 @60 = 2, `pdnm` `Linear Ramp\|Radial Ramp` | 368, 377 | V | +| **checkbox** | `cdat[0] = 1.0` when on, `0.0` when off; **the default is the `u32` at `pard` byte 56** (0 off: Checkbox Control 217, Shadow Only 420, Bypass 389; **1 on: Repeat Edge Pixels of Fast Box Blur and Gaussian Blur, read back 1 in 412 and 417**), and a record exists only when the value differs from it (416 and 419 switch Repeat Edge Pixels off: a record with 0.0, descriptor `00010004`). The corpus manifest's "off" for the Gaussian Blur of 214 was wrong. Exposure's Bypass Linear Light Conversion has an empty `pard` name and its label in `pdnm` (like the buttons) | 217, 389, 396, 412, 416, 417, 419, 420, 426 | V | +| **integer slider** (type 1) | Fast Box Blur's Iterations: default `i32` at `pard` 56 (3), valid maximum `i32` at 128 (50), the value record a plain double (1.0 for 1) with `tdum` / `tduM` 1 / 5 (the slider range) | 412, 414 | V | +| **arbitrary data** (type 11) | the value record is a 4-byte `cdat` 0 followed by a `LIST aRbs` holding the data (`aRbp`); `parT` has the default `aRbp` after the `pard`. Hue/Saturation's Master Hue, Saturation, Lightness and Levels' Input / Output Black and White and Gamma are NOT in their visible parameters (which keep no record) but in this data; see below | 443-446, 511-516 | V | +| **point** | two doubles, a **fraction of the layer size** (`tdb4@24` = the layer's width / height: 16 / 9 in 369, 374, 218, 1 on the 100 x 100 solid of 383; `@16` = 6.25e-12 in all): `[111, 222]` is `[111/1920, 222/1080]` (`tdb4[3]` = 2, `[5]` = 15). **The default is two 16.16 fractions 0.5 in `pard` @56 and @60, relative to the layer: a Point Control on a 100x100 solid reads back [50, 50]**. Gradient Ramp Start / End are stored the same way; values outside the layer give fractions outside 0..1 (`[2000, -100]` -> `[1.0417, -0.0926]`); on a 100x100 solid `[10, 20]` is `[0.1, 0.2]`. **Keyed: 104-byte spatial records (56 + 24 x 2), flags `0x0007`, `u32@8` = 1, the two fractions at 56, tangents zero**; `f64@16` holds a derived distance on linear keys too (1.7397 in 382: ignore it) | 218, 310, 369, 374, 382, 383 | V | +| **angle** | plain degrees: 90 is `90.0` | 219 | V | +| **layer control** | the `-0001` record always exists (`cdat` 0); the sibling `tdpi` (u32) is the **id of the chosen layer** (the new Null, `0x22`). **The default ("Layer 1" on the first layer) and an explicit 1 are the owning layer's own id (320); "None" is `tdpi` 0 (321).** The manifest's "None" for the default (076, 220 rows) was wrong. In the implicit first parameter `tdpi` is the id of the layer that owns the effect | 220, 320, 321 | V | +| **layer parameter** (any effect) | as the Layer Control: the `-NNNN` record always exists with `cdat` 0 and `tdpi` = the id of the chosen layer (Set Matte, Displacement Map, Compound Blur set to the layer below: `tdpi` 340 / 354 / 368 = that layer's id); the effect's implicit `-0000` record holds the owning layer's id | 904, 905 | V | +| **dropdown** | the items are in `pdnm` (`Alpha\|Beta\|...`), `pard` u16 @60 is the item count (5), `pard` @56 the selection (1 by default). Selecting item 3 adds a value record (`cdat[0]` = 3.0, descriptor `00010004`) AND writes 3 into `pard` @56. Setting the items re-creates the effect definition under a new match name (`Pseudo/@@KbKT0rCPQi2A0ytuyGLWSw`; display name `Dropdown Menu Control`) | 077, 323, 324 | V | + +The default of Gaussian Blur: the default-only file is byte-identical to the one with Blurriness 25 +and has no value record; `pard` holds 25 (f64 @56 and f32 @120); setting 40 adds a record and leaves +`pard` at 25, so `pard@56` is the default and not the current value (a popup selection is the one +exception, it overwrites `pard@56`). The corpus manifest's default of 0 was wrong: After Effects +reads a fresh Gaussian Blur as 25 (300, **V**; the conflict is resolved). + +Because a popup selection overwrites `pard@56`, a popup whose definition comes from the `EfdG` copy +has no reliable default in the file (the slot holds the copied instance's selection); the reader +returns no default for it (`EffectParam::pard_default` is `None`), and a consumer uses the effect's +known default. Effect stack order is the order of the `sspc` children of the Effect Parade: moving an +effect (366) reorders them and the `EfDf` copies and changes nothing else (365, 366, **V**). + +**Exposure (`ADBE Exposure2`, 389-397, V).** `parn` = 24: 0 the input layer, 1 `Channels:` (popup +`Master|Individual Channels`, 1-based, default 1), then four groups of five entries, Master 2-6, +Red 7-11, Green 12-16, Blue 17-21, each `[group start (13), Exposure, Offset, Gamma Correction, +group end (14)]` (the channel groups' sliders are named `Red Exposure`, `Red Offset`, `Red Gamma +Correction`, ...), 22 Bypass Linear Light Conversion (checkbox, default off) and 23 the built-in +entry. The three sliders are float sliders with the same `pard` in every group: Exposure (stops) +default 0, valid -100..100, slider -4..4; Offset default 0, valid -2..2, slider -0.5..0.5; Gamma +Correction default **1**, valid and slider 0.1..10. Each one-change case adds exactly one value +record (twice: layer tree and `EfdG`): Channels 2 (390), Exposure 1.5 (391) and -2.25 (392), Offset +0.1 (393), Gamma 2.2 (394), Channels 2 + Red Exposure 1 (395, two records), Bypass 1.0 (396). A +keyed Exposure (397: -1 at 0 s, 2 at 2 s, linear) has plain 48-byte records. With Channels = Master +the per-channel values are stored but inactive. The other byte changes against 389 are only the +stale UI flags `pard@4` and, for a popup selection, `pard@59`. + +**Batch 5 effects (409-450, 511-516, 522-525; V).** Defaults as read back by After Effects for the +fresh effect (MANIFEST), each value change one case. The scale of a fixed slider is told by its +valid maximum (`pard` 128): + +| Effect (match name) | Parameters (`parT` index: type, valid maximum, default) | Evidence | +|---|---|---| +| `ADBE Invert` | 1 Channel: popup of 16 items **including three separators `(-`** (RGB, Red, Green, Blue, `(-`, HLS, Hue, Lightness, Saturation, `(-`, YIQ, Luminance, In Phase Chrominance, Quadrature Chrominance, `(-`, Alpha), default 1, stored 1-based over all 16 (Red = 2); 2 Blend With Original: fixed, max 100 (percent), 50 stored 50.0 | 409-411 | +| `ADBE Box Blur2` (Fast Box Blur) | 1 Blur Radius: fixed, max 30 000, pixels (20); 2 Iterations: integer slider, default 3, max 50; 3 Blur Dimensions: popup (Horizontal and Vertical, Horizontal, Vertical), default 1; 4 Repeat Edge Pixels: checkbox, **default on** | 412-416 | +| `ADBE Gaussian Blur 2` | 1 Blurriness: float, default 25, max 30 000; 2 Blur Dimensions: popup as above (Vertical = 3); 3 Repeat Edge Pixels: checkbox, **default on** | 417-419 (and 214, 216, 300, 301) | +| `ADBE Drop Shadow` | 1 Shadow Color: default black; 2 Opacity: fixed, **max 255** (default 127.5 = 50 %, 204 = 80 %); 3 Direction: angle, default 135; 4 Distance: fixed, max 4 000, pixels, default 5; 5 Softness: fixed, max 30 000, default 0; 6 Shadow Only: checkbox, default off | 420-426 | +| `ADBE Glo2` (Glow) | 1 Glow Based On: popup (Alpha Channel, Color Channels), default 2; 2 Glow Threshold: fixed, **max 255** (default 153 = 60 %); 3 Glow Radius: fixed, max 1 000, default 10; 4 Glow Intensity: fixed, max 255, default 1; 5 Composite Original: popup (On Top, Behind, None), **default 2 (Behind)**; 6 Glow Operation: popup of 25 blend modes starting None, Normal, Add, ..., default 3 (Add); 7 Glow Colors: popup (Original Colors, A & B Colors, Arbitrary Map), default 1; 8 Color Looping: popup (Sawtooth A>B, Sawtooth B>A, Triangle A>B>A, Triangle B>A>B), default 3; 9 Color Loops: fixed, max 127, default 1; 10 Color Phase: angle; 11 A & B Midpoint: fixed, **max 0.99, a 0..1 fraction**, default 0.5; 12 Color A white; 13 Color B black; 14 Glow Dimensions: popup as Blur Dimensions | 427-441 | +| `ADBE HUE SATURATION` | 1 Channel Control: popup (Master, Reds, Yellows, Greens, Cyans, Blues, Magentas); 2 Channel Range: **arbitrary data** (below); 3 Master Hue (angle), 4 Master Saturation, 5 Master Lightness (fixed, max 100): **never stored, the values are in the data**; 6 Colorize: checkbox; 7 Colorize Hue: angle; 8 Colorize Saturation: fixed, max 100, default 25; 9 Colorize Lightness: fixed, max 100 | 443-450 | +| `ADBE Timewarp` | 1 Method: popup (Whole Frames, Frame Mix, Pixel Motion), default 3; 2 Adjust Time By: popup (Speed, Source Frame), default 1; 3 Speed: fixed, max 5 000, default 50, plain (25 stored 25.0; keyed: plain 48-byte records 50 / 200); 4 Source Frame: fixed, max 5 000, plain (12); the tuning, motion blur, matte (`Matte Layer`, `Warp Layer`: layer records always present, 0 = none) and crop parameters follow | 529-533 | +| `ADBE Easy Levels2` (Levels) | 1 Channel: popup (RGB, Red, Green, Blue, Alpha); 2 Histogram: **arbitrary data** (below); 3-7 Input Black, Input White, Gamma, Output Black, Output White: float sliders (max 10 000, Gamma 5), **never stored, the values are in the data**; 8 / 9 Clip To Output Black / White: popup (**On, Off, Off for 32 bpc Color**), default 3 | 511-516 | + +Hue/Saturation data (180 bytes): `i32` master hue at 0 (444: 90), saturation at 4 (445: 50), +lightness at 8 (446: -30; V); then six colour ranges (Reds, Yellows, Greens, Cyans, Blues, +Magentas) of 28 bytes: four `i32` range points in degrees (default Reds 315, 345, 15, 45; Yellows +15, 45, 75, 105; ...; Magentas 255, 285, 315, 345) and the range's hue, saturation, lightness (E: +layout read from the default, no range was changed). The Colorize values are ordinary records +(447-450). Levels data (108 bytes): `u32` `0x000f10a7`, `u32` 1, then five channels (RGB, Red, +Green, Blue, Alpha) of five `f32` input black, input white, gamma, output black, output white; the +RGB values are V (512-516: 0.1, 0.8, 2, 0.2, 0.9 as float32), the other channels E (their defaults +0, 1, 1, 0, 1). After Effects' undo does not revert a change of these values (MANIFEST). API: +`Effect::arbitrary_data`, `HueSaturationData`, `LevelsData`; test `tests/effects_batch5.rs`. + +API: `EffectParam::{stored_value, pard_default, value, is_default, is_animated, keys, valid_max, +valid_min, slider_range, point_px, layer_ref, popup_item_count, popup_selected_index, +popup_selected_item, borrowed_definition}`, `Effect::has_own_definitions`, +`Project::{effect_params, effect_definitions, definition_source}`, `ParamValue`, +`ParamKind::{Button, GroupStart, GroupEnd}`, `DefinitionSource`, `LayerRef`. Tests: +`tests/effects.rs`, `tests/batch3_core.rs`, `tests/batch3_objects.rs`, `tests/effects_batch4.rs` +(356, 357, 361, 363, 364, 366, 368, 369, 371, 374, 377, 378, 380, 382, 383), +`tests/effects_exposure.rs` (389-391, 393-397). + +**Importer block 2026-11-05, #3110 (`1100-quickwins.aep`, After Effects 26.2.1; V for every +row: defaults from the defaults composition, the valid ranges from the minimum and maximum +compositions, the items from one composition per popup item).** Each set value is stored as set +(Decay 20 is `20.0`, Blend With Original 100 % is `1.0`); a value set to the default leaves no record +(HDR Amount 100): + +| Effect (match name) | Parameters (`parT` index: type, valid range, default) | +|---|---| +| `ADBE HDR ToneMap` (HDR Highlight Compression) | 1 Amount: float, 0..100 (slider 0..100), default 100 | +| `ADBE Echo` | 1 Echo Time (seconds): float, -30 000..30 000 (slider -5..5), default -1/30 (float32); 2 Number Of Echoes: integer, max 30 000, default 1; 3 Starting Intensity: float, 0..1, default 1; 4 Decay: float, **valid 0..100, slider 0..1**, default 1; 5 Echo Operator: popup (Add, Maximum, Minimum, Screen, Composite In Back, Composite In Front, Blend), default 1 | +| `ADBE Linear Wipe` | 1 Transition Completion: fixed, max 100, default 0; 2 Wipe Angle: angle, default 90; 3 Feather: fixed, max 32 000, default 0 | +| `ADBE Offset` | 1 Shift Center To: point, default the layer centre; 2 Blend With Original: fixed, **max 1 (a 0..1 fraction)**, default 0 | +| `ADBE Deflicker` (Color Stabilizer) | 1 Stabilize: popup (Brightness, Levels, Curves), **default 2 (Levels)**; 2 Black Point, 3 Mid Point, 4 White Point: points, defaults 0.2 / 0.5 / 0.8 of the width at half the height; 5 Sample Size: fixed, max 50, default 3. The reference frame the Set Frame button picks is not among the parameters | + +**Importer block 2026-11-05, #3112 (`1300-thirdparty.aep`; V for the parameter lists, H for the +data layouts, read from default instances only):** + +| Effect (match name, plug-in version) | Parameters (`parT` index: type, valid range, default) | +|---|---| +| `CS Color Neutralizer` (CC Color Neutralizer, 1.3) | 1 / 7 / 13 Shadows / Midtones / Highlights Unbalance: colours (black, 127 grey, white; pickers: setting one sets the range's sliders, e.g. [0.27, 0.55, 0.85] gives Red 42.94, Green 1.18, Blue -44.12 = (mean - channel) x 150 / 255 on 8-bit values, and leaves no colour record); 2-6, 8-12, 14-18 a group per range (start, Red, Green, Blue, end) with float sliders -100..100 (slider -50..50), default 0; 19 Pinning: float 0..100 (slider 0..50); 20 Blend w. Original: float 0..100; 21-25 the Special group: 22 View popup (Final Result, Correction B to W, Correction Stair), default 1, 23 Black Point float 0..49.9, default 0, 24 White Point float 50.1..100, default 100 | +| `EXtractoR` (2.6.6) | 1 Channel Info (`EXtractoR-0013`): arbitrary data, 688 bytes, below; 2-6 the Process group: 3 Black Point and 4 White Point float sliders, valid ±3.4028235e38 (the float32 range; slider ±1 000), default 0 / 1; 5 UnMult: checkbox (empty `pard` name, the label in `pdnm`), default off | +| `IDentifier` (2.6.6) | 1 Channel Info (`IDentifier-0005`): arbitrary data, 148 bytes, below; 2 Display: popup (Colors, Luma Matte, Alpha Matte, Raw), default 1; 3 ID: integer slider, max 2 147 483 647, default 0 | + +EXtractoR's Channel Info is the plug-in's own **little-endian** layout: `u32` 1 and 28 bytes, then +four 164-byte records (Red, Green, Blue, Alpha), each a kind in byte 0 (1 a channel of the footage by +name: `R`, `G`, `B` by default; 2 the input's own channel, named `(copy)`: Alpha by default) and the +channel name NUL-terminated from record byte 35. EffectCraft imports kind 2 as its EXtractoR's `(copy)`, +the effect input's channel of the same position as earlier effects left it, not as `A` (which names +an OpenEXR footage's own alpha plane). The rest is not read: it differs between instances +with the same channels (uninitialised-looking values, also in bytes 1..4 of a record: `02 00 00 32` +on Alpha in one definition's default, which is why only byte 0 is the kind). **A chosen channel** +(`extractor-07-preset-channel-z`, a preset of our own that reads `Z` into Red, Green and Blue) is kind +1 with its name (`Z`), and the `u32` at record byte 4 is then 13, which looks like the channel's +position in the EXR's sorted channel list of 14 (the defaults hold 0 there: H). IDentifier's data +differs between instances with the same settings except for **the chosen channel's name**, +NUL-terminated from byte 19, which is `Object ID` when no channel is chosen. After Effects lists +only integer (UINT) channels: in 1300's EXR (a FLOAT `ID` channel) it found none ("No ID channels +available"), so that block's preset `identifier-09-preset-channel-id` only sets ID 2; in 1310's +EXR (UINT `objectId` and `IndexOB.X` added) the preset `identifier-09-preset-channel-objectid-id2` +stores `objectId`, with 15 at byte 4 (the channel's position in the sorted list of 16, as for +EXtractoR: H). Without a chosen channel After Effects leaves the layer unchanged (1300 and 1310 +defaults). The other bytes are not read. API: `ExtractorChannels`, +`identifier_channel_type`. + +**Curves and Mesh Warp** (961-965, 985; applied from presets, the data is not scriptable): their +arbitrary-data parameter (type 11) always has a record (`tdbs` with a 4-byte `cdat`) and a `LIST +aRbs` / `aRbp`, also at the default. Curves (`ADBE CurvesCustom-0001`, 1644 bytes): `u16` 1, 1; +five 256-byte tables (RGB, Red, Green, Blue, Alpha) = the natural cubic spline through the points, +rounded (0 of 1280 entries differ); five 72-byte point records of 16 (`u16` in, `u16` out) slots, +the count at 64, an `i32` at 68 (-1 untouched, count - 2 in every edited sample: H). Mesh Warp +(`ADBE MESH WARP-0004`): `u32` rows + 1, `u32` columns + 1 (a 1 x 2-cell read-back test renders as made only in +this order, `export-tests\mesh`; AE does not rebuild the stored mesh when Rows / Columns change, 989), 12 bytes +(zeros, `0d 0d`), then per vertex row-major ten big-endian `f32`: position, handles top, right, +bottom, left as fractions of the layer (H: or of the comp), outward border handles (0, 0); Rows / +Columns / Quality are integer sliders with records only off their default (7, 7, 8). The `-NNNN` +suffix is a parameter id, not the `parT` position (Curves -0002 Channel before -0001; Mesh Warp +-0005 Quality before -0004). API: `CurvesData`, `MeshData`, `curve_lut`. [V; details: corpus FORMAT +S] + +**Lumetri Color** (`ADBE Lumetri`, 1200: 63 compositions in After Effects 2026, 32 bpc, working space +None; by script: defaults, all set, one per section, valid minima and maxima, every popup item the script +can set, checkboxes toggled, keys, an expression; from presets made by hand, `-58` ... `-62`: an Input +LUT, a Look, the RGB curve, Hue vs Sat, the colour wheels): 131 `parT` entries. The `-NNNN` suffix is a +parameter id, not the position (`-0127` ... `-0130` sit between `-0005` and `-0026`), so the importer +keys by suffix. Float sliders (type 10) store the value After Effects shows; the valid ranges (`pard` +104 / 108) are wider than the slider's (112 / 116): Temperature / Tint -300..300 (slider -100..100), +Saturation 0..300 (0..200), Exposure -7..7 (-5..5), Contrast, Highlights, Shadows, Whites, Blacks, +HDR Specular, Tint Balance -150..150 (-100..100), Faded Film 0..150 (0..100), HDR White 100..1000, +HDR Range 100..10000, Refine Blur 0..1000 (0..30), Vignette Amount -5..5 (-3..3); the read-backs of +`-19-min` / `-20-max` equal the stored numbers. **Hidden controls are recorded in the default state** +(`tdsb` 3) and still hold the value After Effects reads back: High Dynamic Range `-0062` (1.0), +HDR Specular `-0064` (22), the second Look popup `-0128` (26.16 as set, read back 26), Legacy Tone And +Saturation `-0097` (its `pard` default reads off as the script saved the project and on once the +project was opened and saved again, `versions/1200-lumetri-26`, `-25x`, `-24x`; a fresh instance reads +back off), Auto Color `-0124`, Face Detection `-0102`, the Auto Intensity `-0123` +(`EffectParam::recorded_value`). Each section has an Active checkbox (blank `pard` name; `-0003` Basic +Correction, `-0023` Creative, `-0037` Curves, `-0118` RGB Curves, `-0104` / `-0105` / `-0107` / `-0109` / +`-0111` the hue / saturation curves, `-0046` Color Wheels, `-0068` HSL Secondary, `-0050` Vignette, on +by default); off, the section does nothing (`-03-sec-basic-correction`, `-17-sec-vignette` render as +`-00-defaults`). Arbitrary data (type 11, a record and `aRbs` in every instance; empty is `fe fe`): +`-0001` an XML copy of the grade written only when the Look changes (not kept current: `-01-set-all` +holds defaults for controls set after the Look; it names the LUT file, `Fuji F125 Kodak 2393 (by +Adobe).cube`); `-0096` the Look's name, UTF-16LE (`SL BLUE ICE`, `Fuji F125 Kodak 2393 (by Adobe)` in +`-59-preset-look-lut`; the popup `-0025` itself has no record, `-0128` can disagree with it: +`-07-sec-creative` names item 20 while `-0128` holds 23), `-0095` likewise for the Input LUT +(`ALEXA_Default_LogC2Rec709`, `-58-preset-input-lut`; the popups `-0005` / `-0127` keep no record, +`-0004`, `-0024` and the assets `-0125` / `-0126` stay `fe fe`: the LUTs are After Effects' own files, +named, not embedded); `-0129` the Look colour space's 16-byte id (the GUID `LookColorSpace` of `-0001` +in Windows layout: the first 4, 2 and 2 bytes little-endian; zero for None; the Color Space popup +`-0130` writes no record of its own, `-22-pop38-1` ... `-53-pop38-33`); +`-0032` Split Toning (32 zero bytes); `-0039` the four RGB curves and `-0042`, `-0106`, `-0108`, +`-0110`, `-0112` the hue / saturation curves, 520 bytes each: `i32` type (3 for the hue curves, 2 for +Luma vs Sat and Sat vs Sat, 0 for an RGB curve), `u32` point count, then little-endian `f64` pairs x, y +sorted by x (bytes after the counted points are stale). RGB: x and y 0..1, (0, 0), (1, 1) by default; +the first of the four is the master curve (`-60-preset-curves-rgb`: (0.491, 0.787) lifts R, G and B +alike, and the render follows a natural cubic spline through the points within 0.003); the order of +the other three is H (the `-0001` XML names `ToneCurvesLuma`, `Red`, `Green`, `Blue`; no sample moves +one). Hue / saturation: x the hue (0 red, 1/3 green) or the luma / saturation 0..1, y the offset from +neutral 0; a fresh curve has no points, the selector colours `-0113` ... `-0117` add three at y = 0, +the hue picked +- 0.0556. Hue vs Sat's y scales the saturation by 1 + y in linear light +(`-61-preset-curves-huesat`: (0.0155, 0.97) takes pure red's linear saturation to 1.96 times, (0.263, +-0.03) and (0.765, -0.02) green, cyan and blue to 0.97); the other four curves' scale is H. `-0047` +Color Wheels, 4 `f64` triples: hue in degrees (0 red, 120 green), brightness slider 0..1 (0.5 +neutral), distance from the centre 0..1; 0, 0.5, 0 each by default; Shadows, Midtones, Highlights, then +a fourth wheel of unknown role (`-62-preset-wheels`: Shadows 229.1, 0.370, 0.547 towards blue with the +slider down; Midtones 0.1, 0.5, 0.395 towards red; Highlights 93.4, 0.727, 0.319 towards yellow-green +with the slider up; the fourth at its default); `-0085` the HSL correction wheels (8 triples, the same +default; layout H); `-0073` the HSL key, 40 bytes: a flag byte (1 once a colour was picked), then hue, +saturation, lightness, each centre, range, tolerance (`f32` LE, fractions) and an enabled byte (fresh: +0.5, 0, 0, on; picking RGB 0.02 0.55 0.85 gives hue centre 0.5605 = that colour's hue and lightness +centre 0.435 = its HSL lightness, range 0.05, tolerance 0.1: `-01-set-all`; whether range is the half +or full width is H); `-0122` the Auto Tone analysis (UTF-16 JSON). The project saved as 25.x and 24.x +copies (`versions/1200-lumetri-25x`, `-24x`: the 58 scripted compositions, saved by After Effects +2026) stores every Lumetri definition, valid range and value as the 26 save does. [V for the sliders, +checkboxes, popups, the `tdsb` 3 values, the master RGB curve, Hue vs Sat, the colour wheels and the +LUT names; H where marked] + +**Cryptomatte plug-in** (match name `Cryptomatte`, the free Cryptomatte plug-in, 2.6.6 in our +sample; read from 88 instances in one production project, not made by us, and from our own After +Effects 2026 sample 1400 (corpus `aep/cryptomatte.aep`: a fresh instance, Selection Mode on, each +Output item, and two presets of our own that choose a layer and pick one object or material in the +plug-in's UI; scripting read-backs and renders per composition); H for what neither varies): +`parT` 0 the input layer; 1 Settings: **arbitrary data** (type 11, `Cryptomatte-0001`, a record and +`aRbs` / `aRbp` in every instance); 2 Output: popup (Colors, Matted Colors, Matted RGBA, Matte +Only), **`pard` default 1 = Colors** (bytes 56..64 `00000001 0004 0001`, in the instance's own and +the project's shared definition; scripting reads 1 from a fresh effect: 1400 `crypto-00-defaults`), +a written record (`tdsb` 1) holding the item number when set (1400: 2, 3, 4; production: 3 in 81, +4 in 7); 3 Selection Mode: checkbox (`pdnm` `fnord!`), no record when off, and when on **a +default-state record (`tdsb` 3) holding 1.0** that After Effects reads back as on and renders +(1400 `crypto-01-set-all`, `crypto-02-chk-toggled`; the general reader takes only `tdsb` 1 +values, so the importer reads this one itself); the built-in entry. As in every project, only the +first instance has its own `parT`; the others borrow the project's (1400). The Settings data is +the plug-in's own layout, **little-endian**: `cry1`; bytes 4..32 differ between instances with +the same settings (zeros in one, pointer-like values in others: not read); the layer name at 32, +NUL-padded to 64 bytes (`CryptoObject`, `CryptoMaterial` in 1400: the EXR layer's name, which is +also its channel prefix there, so the sample cannot tell which of the two the plug-in stores); at +96 a `u32` 1 and a `u32` that is the same in every instance; at 104 the `u32` length of the +selection text including its NUL; at 108 **the MurmurHash3 (x86, 32-bit, seed 0) of the selection +text with its NUL** (V on the three texts of 1400: `<11a97486>` `0x27880767`, `` +`0xf7374a5b`, the empty text `0x514e28b7`; not read); a zero byte at 112; the selection text from +113, the matte list as comma-and-space separated ID hashes `<11a97486>, ` (303 tokens in +production, all in that form). Each token is the 8-digit hash of a picked name as the EXR's +manifest lists it, i.e. the MurmurHash3 of the name (1400: `box_red` `11a97486` picked on +CryptoObject, `mat_paint` `a5deeb9e` on CryptoMaterial). After the text 2 to 3 bytes, zeros or +left-overs of a longer earlier text (1400's presets: 127 bytes, three zeros after the text). **A fresh effect** (the `parT` +default and the record alike, 116 bytes, 1400) is `cry1`, zeros to 96, then `u32`s 1, +`0x514e28b7`, 1, `0x514e28b7` and four zero bytes: no layer and an empty text (length 1, its NUL). +`0x514e28b7` is the hash of a single NUL byte, so the `u32` at 100 looks like the hash of a first +text that is empty in every sample, its length the `u32` 1 at 96 and its NUL the zero byte at 112 +(H: one value). Layer and selection decode the same in the production project and in 1400's two +presets, and After Effects draws exactly the picked objects as selected (`crypto-06`: the box, +`crypto-07`: box and disc, the two objects of `mat_paint`). API: `CryptomatteData` (refuses data without `cry1`, a length past the end or +a non-zero byte at 112). + +**Puppet (`ADBE FreePin3`; ?: external listing, not the corpus, #3093).** No file of the +corpus, the committed fixtures or the samples holds a Puppet. The tree below comes from outside +the corpus: a public scripting listing of the effect's properties (a forum post, an After Effects +release from before the Advanced and Bend pins and Density). It is not bytes we have seen; that +After Effects writes it by the general rule (a `tdmn` and the `LIST tdgp` or `tdbs` it names, +nested in the instance's value group `sspc/tdgp`, as masks, shapes and layer styles are) is +**H**: + +```text +Puppet ADBE FreePin3 + On Transparent ADBE FreePin3 On Transparent + arap ADBE FreePin3 ARAP Group (hidden) + Auto-traced Shapes ADBE FreePin3 Outlines + Mesh ADBE FreePin3 Mesh Group (hidden) + Mesh 1 ADBE FreePin3 Mesh Atom + Mesh ADBE FreePin3 Mesh (hidden: the triangulation) + Triangles ADBE FreePin3 Mesh Tri Count + Expansion ADBE FreePin3 Mesh Expansion + Deform ADBE FreePin3 PosPins + Puppet Pin 1 ADBE FreePin3 PosPin Atom + Vertex Offset ADBE FreePin3 PosPin Vtx Offset (hidden, 2 values) + Vertex Index ADBE FreePin3 PosPin Vtx Index (hidden; 4294967295 = none) + Position ADBE FreePin3 PosPin Position + Overlap ADBE FreePin3 HghtPins (hidden while empty) + Stiffness ADBE FreePin3 StarchPins (hidden while empty) +``` + +A pin's rest place is not a property: it is a vertex of the hidden mesh (Vertex Index) plus an +offset, so it cannot be read without decoding the mesh data. The unit of Position (layer pixels, +or a fraction of the layer as effect points are) is **?**. The match names of the Overlap and +Starch pin atoms and their properties, of the Advanced and Bend pins (Scale, Rotation) and of +Density, Mesh Rotation Refinement and the Puppet Engine are **?**, and so is which of them are +`parT` parameters; whether After Effects stores some `parT` parameters of a fresh Puppet even at +their defaults (the importer would then report them every time) is **?**; whether a Puppet +without pins has an (empty) Mesh Group, or no ARAP group at all, is **?**. The importer +(`import/puppet.rs`) therefore brings the effect in as EffectCraft's Puppet without meshes or +pins and reports, per mesh, Triangles, Expansion and per pin group the pins, how many are keyed +or carry an expression, and their atom match names; every entry outside this tree is named in the +report. The sample that settles it: a fresh Puppet with no pins in one composition and, in +another, a 400 x 800 solid in a larger composition (pixels against fractions) with a Puppet of +three Position pins (one keyed, one moved off its rest place without +keys), one Advanced, one Bend, one Starch and one Overlap pin, Triangles, Expansion and Density +off their defaults, a second mesh, and a scripting read-back of every property's match name and +value, the hidden ones included. Pins added by script are reported to come out disabled, so the +pins are placed by hand or by a preset. + +### 3.8 Masks and bezier paths (`tdgp[ADBE Mask Parade]`) + +| Field | Chunk path | Offset | Type | Meaning | Evidence | Conf. | +|---|---|---|---|---|---|---| +| inverted | `Mask Parade/mkif` | 0 | u8 | | 090 (0), 091 (1) | V | +| **mode** | `mkif` | 4 | u32 | Add 1, Subtract 2, **Intersect 3, Lighten 4, Darken 5, Difference 6, None 0** (329: the same ellipse path as 232) | 090, 091, 234-237, 329 | V | +| name | `tdgp[ADBE Mask Atom]/tdsn/Utf8` | | text | `Mask 1` | 090 | V | +| feather, opacity, expansion | `ADBE Mask Feather`, `ADBE Mask Opacity`, `ADBE Mask Offset` | | see 3.4 | stored only when not at the default; feather can be keyed (plain n=2 records) | 090, 091, 208 | V | +| path property | `om-s[ADBE Mask Shape]/tdbs` | | | animated: `tdb4` byte 68 = 1 and a `list` of 64-byte records (time and common fields only) | 090, 093 | V | +| path shapes | `om-s/omks/LIST shap` | | | one per keyframe, one for a static path | 090, 093 | V | +| path never set | (no `ADBE Mask Shape` entry in the atom) | | | a mask added without a path (scripted `addProperty`) stores no Mask Path at all, also no `om-s`; After Effects reads it back, also after reopening, as the **source rectangle** `[0,0] [0,h] [w,h] [w,0]` (clockwise from the top left, no tangents) and renders it so (901: expansion -100 leaves a 100 px border) | 900, 901 | V | +| box | `shap/shph` | 4, 8, 12, 16 | 4 x f32 | left, top, right, bottom **normalised to the layer (source) size** for masks (560 / 1920, 340 / 1080, 1360 / 1920, 740 / 1080; on a 100x100 solid a 60x40 rectangle has the box 0.2, 0.3, 0.8, 0.7 and decodes exactly with the layer size, not the 1920x1080 composition). It is the box of the vertices **and** of the handles | 090, 232, 309 | V | +| **open path** | `shph` | 3 | u8 | bit `0x08` set = open path (`0x09` against `0x01`); byte 20 is 1 in every sample, open or closed | 233 against 090, 232, 234 | V | +| points | `shap/list` (`lhd3` record size 8) | | f32 x, y | three per vertex in the order **vertex i, out handle i, in handle i + 1**, normalised inside the box (u = (x - left) / (right - left)); the last record is the in handle of vertex 0. A **tangent is the handle minus the vertex**, without a sign change | 090 (rect), 093 (two rects), 232 (ellipse: tangents `0.5523 x radius`, `[-220.91, 0]`, `[0, -110.46]`, ...), 233 (open path, 3 vertices) | V | + +**There is one `mkif` per mask**, placed directly before its atom (two masks: `mkif tdgp mkif tdgp`, +328), so mode and inverted are reported per mask. `mkif` byte 8 is the running mask id counter of the +**layer** in the session (1, 2 for the two masks of 328; 329 then gets 3; undo does not reset it; a new +layer starts at 1 again): exposed as `Mask::counter`, a session counter and not a stable id. API: +`Mask::{mode, inverted, counter}`, `ShapePath::vertices(size)` (vertices in layer pixels: `size` is the size of the layer's source, `Project::layer_source_size`; a text or shape layer has no source size and its mask boxes are already pixels, so the importer passes 1 x 1), `Layer::mask_atoms` (`MaskAtom`: the mask with its atom group, its path property and its shapes by position, for the keys and expressions of the mask properties). Tests: +`tests/masks.rs` (with a synthetic check of the handle order), `tests/batch3_objects.rs`. + +### 3.9 Shape layers (`tdgp[ADBE Root Vectors Group]`) + +A shape layer (type 4) holds `ADBE Vector Group` (user name `Group 1`) with `ADBE Vectors Group` +(the contents, in z-order, `tdsb` 0x401) and `ADBE Vector Transform Group`. Items are named by their +match name and carry their own user name. Colours are ARGB doubles 0..255. All sizes, positions and +path points are in pixels. **An item's eye switch is bit 0 of its group's `tdsb`** (1 on; 986: a +Fill at 0 is not drawn, 987: the same file at 1 draws it; both saved by After Effects from a patched +copy of 850, the switch is not scriptable) [V]. + +| Item (match name) | Property | Stored | Evidence | Conf. | +|---|---|---|---|---| +| `ADBE Vector Shape - Rect` ("Rectangle Path 1") | `ADBE Vector Rect Size` | f64 `[400, 300]` (2 components) | 238-242 | V | +| `ADBE Vector Shape - Group` ("Path 1") | `om-s[ADBE Vector Shape]` | the same `shph` + point list as a mask, with a box in **pixels** relative to the layer origin; vertices `[0,-100] [100,100] [-100,100]`, in tangents `[-10,-20] [30,20] [-60,10]`, out tangents `[40,0] [-20,30] [0,-50]`; the box covers vertices and handles: `-160, -120, 130, 130` | 240 | V | +| `ADBE Vector Graphic - Fill` | `ADBE Vector Fill Color` | `[255, 0, 255, 0]` | 238, 240, 242 | V | +| `ADBE Vector Graphic - Stroke` | `Stroke Color` `[255, 0, 255, 0]`, `Stroke Width` 8, **`Stroke Line Cap` 2.0 (round; butt = 1 is absent)**, **`Stroke Line Join` 2.0 (round; miter = 1 is absent)**, `Stroke Miter Limit` 4 with `tdsb` 3 once the join was touched | doubles | 239 | V | +| `ADBE Vector Filter - RC` ("Round Corners 1") | `ADBE Vector RoundCorner Radius` | f64 20 | 238 | V | +| `ADBE Vector Graphic - G-Fill` ("Gradient Fill 1") | `ADBE Vector Grad Start Pt` `[-200, 0]`, `ADBE Vector Grad End Pt` `[200, 0]` | 2 components, class 15; the gradient type (linear) and the colour stops stay at After Effects' default and are not stored | 241 | V (points) | +| `ADBE Vector Transform Group` | `ADBE Vector Position` | f64 `[50, 50]`; absent = `[0, 0]`, as are all other transform properties at default | 242 | V | + +Batch 3 (all **V**; shape layer `Shape`, label 8): + +| Item | Stored | Evidence | +|---|---|---| +| `ADBE Vector Shape - Star` ("Polystar Path 1") | After Effects' defaults are star, 5 points, outer radius 100, inner radius 50, rotation 0, roundness 0, so **a default star has no property record at all** (the 150 / 70 of batch 1 were stored). A **polygon** stores `ADBE Vector Star Type` 2.0 (`tdsb` 1, descriptor `00020000`) plus `Inner Radius` 50 and `Inner Roundess` 0 (After Effects' own spelling) as `tdsb` 3 default-state records; Points 5 and Outer Radius 100 stay absent | 330, 331 | +| `ADBE Vector Graphic - G-Fill` | `ADBE Vector Grad Type` 2.0 for radial (`tdsb` 1, descriptor `00020000`; linear is 1 and absent); Start Point `[0, 0]` is the default and absent, End Point `[200, 0]` stored; the radial-only `Grad HiLite Length` and `Grad HiLite Angle` are written with `tdsb` 1 and value 0 (absent in the linear 241). Colour stops are in no property | 241, 332 | +| two siblings with one match name | one group holds `Rectangle Path 1` (Size `[400, 300]` stored), `Rectangle Path 2` (Size `[100, 100]` is the default, no record; `ADBE Vector Rect Position` `[300, 0]`, 2 components, class 15) and `Fill 1`, in z-order: a reader keys the items by occurrence, not by match name | 333 | + +Batch 5 (all **V**; shape layer `S`, Group 1 = Ellipse Path 1 [400,300] + Fill 1 green in 451, one change each): every value is stored **as After Effects shows it**, in the shape's own record (`tdsb` 1), and absent at its default: + +| Property (match name) | Stored | Evidence | +|---|---|---| +| `ADBE Vector Shape - Ellipse`: `ADBE Vector Ellipse Size`, `... Ellipse Position` | pixels `[500,200]`, `[100,50]` | 452, 453 | +| `ADBE Vector Graphic - Fill`: `ADBE Vector Fill Opacity`, `ADBE Vector Fill Rule` | percent 50; popup 1-based, even-odd = 2 | 454, 455 | +| `ADBE Vector Transform Group` of a group: `ADBE Vector Anchor`, `Scale`, `Rotation`, `Group Opacity`, `Skew`, `Skew Axis` | pixels `[10,20]`; **percent** `[50,80]` (not a fraction as the layer's Scale); degrees 30; percent 40; 20; degrees 45 | 456-461 | +| layer `ADBE Anchor Point` of a shape layer | pixels `[10,20,0]` as stored (no source size), as on a text layer | 462 | +| `ADBE Vector Graphic - Stroke`: `ADBE Vector Stroke Opacity` | percent 50 (colour `[255,255,0,0]` and width 6 as in 239) | 463, 464 | +| `ADBE Vector Filter - Trim`: `Trim Start`, `Trim End`, `Trim Offset`, `Trim Type` | percent 20, 70; degrees 45; popup 1-based, individually = 2; a new Trim Paths has no record | 465-469 | +| `ADBE Vector Rect Roundness` | pixels 30 | 470, 471 | +| `ADBE Vector Shape - Star`: `Points`, `Rotation`, `Inner Roundess`, `Outer Roundess`, `Position`, `Outer Radius`, `Inner Radius` | 6; degrees 30; percent 20, 40; pixels `[50,-20]`, 150, 30 | 472-479 | +| `ADBE Vector Graphic - G-Fill` added: Start `[0,0]` and End `[100,0]` are the defaults, no record; **the colour stops have no record at their default**, which renders white to black, linear in the encoded values (481: 0.75 / 0.5 / 0.25 at a quarter, half and three quarters) | 480, 481 | +| a second top-level group, a group nested in a group (`ADBE Vector Group` inside `ADBE Vectors Group`), `ADBE Vector Graphic - G-Stroke` (width 10) | the same records as at the top level, in z-order | 482, 483, 484 | +| defaults of every item (519: AE read-back with no record stored): rectangle and ellipse size 100 x 100, position 0, roundness 0; star 5 points, radii 100 / 50, rotation and roundness 0; fill red `[1,0,0]`, opacity 100, rule 1; stroke white, width 2, cap / join 1, miter 4; gradients linear, start `[0,0]`, end `[100,0]`; trim 0 / 100 / 0, type 1; round corners radius 10; group transform anchor / position 0, scale 100, opacity 100; blend mode, composite order, shape direction 1 | none of them has a record | 519 | + +The 3D-extrusion `ADBE Vector Materials Group` of a group changes its `tdsb` from 1 to 3 when a polystar or a gradient is added (472-484), with no property record. + +API: `Layer::shape_groups` (`ShapeGroup`, `ShapeItem`, `Stroke`, and `ShapeGroup::details` with +`ShapeDetail::{Polystar, Gradient, RectPosition}`, `PolystarType`, `GradientType`). Other items +(ellipse, trim paths, repeater, dashes, ...) are listed as `ShapeItem::Other` with their match name; +the polystar is listed as `Other` and the gradient fill as `GradientFill`; both carry their extra +fields in `details` (indexed by `item_index`); see section 4. Tests: `tests/shapes.rs`, +`tests/batch3_objects.rs`. + +### 3.10 Text documents (`btds[ADBE Text Document]/LIST btdk`) + +`btdk` is not a chunk sequence but a PostScript-like dictionary (`/key value` pairs, `<< >>`, `[ ]`, +numbers, `true` / `false`, `/names`, strings as `(` + `fe ff` + UTF-16BE + `)` with `\` escapes). The +verified paths from the top level (keys `/98 /0 /1`; `RUN` = `/1/1[0]/0`): + +| What | Path | Evidence | Conf. | +|---|---|---|---| +| text | `RUN/0`; a trailing `\r` ends the paragraph. **A hard line break is `\r` too: `A\rB` is stored `A\rB\r`** | 110 (`A`), 113 (`Hello`), 243 | V | +| **U+0003 in the text** | stored as it is (`A`, U+0003, `B` is `A\u{3}B\r`), with the paragraph runs of a CR (`[2, 2]`). After Effects lays it out exactly like `A\rB` (387): two composed lines, two paragraphs, baselines at y 0 and 98 (`text.measure` in AE). So U+0003 is a line break that starts a new paragraph; the importer maps it to `\r` | 386, 387; test `etx_is_stored_as_it_is_and_splits_the_paragraph_runs` | V | +| font size | `RUN/6/0[n]/0/0/6/1` (100 by default) | 110, 113 (60) | V | +| fill colour | `RUN/6/0[n]/0/0/6/53/0/1` = `[A R G B]` floats 0..1 | 110 (white), 113 (`[1 1 0.5 0]`), 248 | V | +| **paragraph runs** | `RUN/5/0[n]/1` = characters including the `\r` (`A\rB\r`: `[2, 2]`; `Hello\r`: `[6]`) | 243, 245 | V | +| **style runs** | `RUN/6/0[n]/1` = characters per style run (`A\rB\r`: `[4]`). **A range style splits `Hello\r`: characters 1 to 3 red gives `[1, 2, 3]` with the fills white, `[1 1 0 0]`, white** | 243, 248 | V | +| **justification** | `RUN/5/0[n]/0/0/5/0`: 0 = left, **1 = right (334)**, 2 = centre, **3 = justified with the last line left, 4 = last line right, 5 = last line centred, 6 = every line justified**; the scripting enum value of right (7414) is not what is stored | 245 (0), 246 (2), 334 (1), 565 (3), 567 (4), 566 (5), 568 (6) | V | +| **character settings (S17)** | one `text.set_style` change each against the point text 538 (`HHHH`, Times New Roman 100 px, normal baseline), the slot named is the only one that changes: `/6` horizontal scale as a factor (539: 1.0 -> 0.9), `/7` vertical scale (540: 1.5), `/9` baseline shift in px (541: 41), `/11` automatic kerning **0 none, 1 metrics (default), 2 optical** (542, 543), `/18` ligatures (off by default, 555; switching ligatures off in 551 changes nothing), `/35` baseline direction **1 with the stream (default), 2 rotated (573), 3 across the stream / tate-chu-yoko (576)**, `/36` tsume as a fraction (553: 0.5), `/52` no break (552), `/56` fill drawn (on by default, 546), `/57` stroke drawn (off by default, 544), `/58` **stroke over fill (on by default: 547 setting it on changes nothing, 550 setting it off gives false)**, `/62` line join **0 miter, 1 round** (548), `/63` stroke width in px (**1.0 by default**, 545: 5), `/70` digit set **0 default, 1 Arabic (571), 2 Hindi (578)**; with digit set Arabic the text `1234` has the same layer bounds as with the default (S17, not saved) | 538-578, 595, 596; tests `tests/text_style_slots.rs` | V | +| **manual kerning** | `RUN/8/0` (beside the style runs): one entry `<< /0 << /0 amount >> /1 length >>` per run of characters, amount in 1/1000 em; kerning 50 on `HHHH` gives four entries of length 1 with 50 and one for the closing `\r` without an amount, `RUN/7` = 50, and switches automatic kerning `/11` to 0 | 554 | V | +| **paragraph settings (S17)** | `RUN/5/0[n]/0/0/5/`, one change each against 538: `/1` first-line indent (560: 20), `/2` start indent (561: 30), `/3` end indent (562: 40), `/4` space before (563: 10), `/5` space after (564: 12), all in px; `/8` leading model **0 Roman, 1 Japanese** (572); `/9` automatic hyphenation (**on by default**, 556 off); `/21` Roman hanging punctuation (558); `/29` **every-line composer, off by default** (559 on; 557 setting it off changes nothing, so a new text uses the single-line composer); `/33` direction **0 left to right, 1 right to left** (569). Setting the Universal composer (570) changes nothing; the Latin/CJK composer cannot be set by script | 556-572 | V | +| **vertical text** | `lineOrientation` vertical right to left adds `/0/8/0[0]/0/2/1` = 2 to the frame dictionary (absent for horizontal text) | 575 | V | +| **box (paragraph) text** | frame dictionary `/0/8/0[0]/0`: `/1/0` = 32 floats = 16 x, y pairs tracing the rectangle (corners `[-200,-100] [200,-100] [200,100] [-200,100]`), `/2/0` = 1; both keys are absent for point text. Alignment changes only the glyph geometry, not the frame | 245, 246 (box 400 x 200, top-left `[-200, -100]`), 247 (point text: absent) | V | +| **tracking** | `RUN/6/0[n]/0/0/6/8` = 0, 100 in 247 | 247 | V | +| **faux bold / faux italic** | style slots `.../6/2` and `.../6/3`, `false` -> `true`; the font style stays Regular. **Side effect: the font list `/0/1/0` gains a new first entry (4 -> 5 fonts) with property `/3` = 2 (bold) or 1 (italic), the old entries shift up and the style's font index `/6/0` becomes 1** | 335, 336 | V | +| **caps** | style slot `.../6/12`: 0 normal, **1 small caps, 2 all caps** | 337, 338 | V | +| **superscript / subscript** | style slot `.../6/13`: **1 superscript, 0 normal, 2 subscript** (the only slot that changes between 526, 527 and 528). After Effects lays superscript and subscript out at 58.3 % of the size, 33.3 % of the size above / below the baseline: `HHHH` in Times New Roman 100 px is 288.9 px wide with its baseline at 0 when normal, 168.4 px with its baseline at -33.3 / +33.3 when superscript / subscript (`text.measure`, layer bounds). **Every scripted text of the corpus is superscript** (526: the character state After Effects was in; 243, 517 and the reference 244 too), which is why this slot never showed up as undecoded | 526-528, 243, 517 | V | +| **wrapping box text** | a 600 x 400 box at `[-300, -200]` (as in 245) with a sentence of 70 characters: the document holds the text, size and box only; After Effects composes four lines (`The quick brown fox ` / `jumps over the lazy dog ` / `and keeps running far ` / `away`), the line breaks are not stored | 517 | V | +| **leading** | style slot `.../6/5`: the scripted samples have the explicit leading 98.0 (100 px Times New Roman; `/4` false), leading 60 is 60.0; with automatic leading on, 400 stores 0.01 (see "automatic leading" below) | 339, 400 | V | +| **last run** | the last style run reaches the paragraph end and includes the final `\r` (two range styles on `Hello`: runs `[1, 2, 3]`, fills white / `[1 1 0 0]` / `[1 0 0 1]`, sizes 100 / 100 / 60) | 340 | V | +| font | `.../6/0` = index into the font list `/0/1/0[i]/0/0/0` (`TimesNewRomanPSMT`, ...). The list always holds entries no run uses (`Myriad-Roman`, `MyriadPro-Regular`, `AdobeInvisFont`), so only the fonts the runs point at matter | 110, 335 (index 1 is still `TimesNewRomanPSMT`) | E | +| **stroke colour** | `.../6/54/0/1` = `[A R G B]`, the fill's layout; white in the untouched samples, red `[1 1 0 0]` in 574, blue in 595. The stroke switch, width and order are slots `/57`, `/63`, `/58` (see "character settings") | 110, 113, 574, 595 | V | +| **automatic leading** | style slot `.../6/4`: `true` = automatic leading (lines advance by 1.2 x the size; `/5` is then not used), `false` = `/5` is the leading. **243: `/4` false, `/5` 98, the second line's baseline is stored 98 px below the first (`/1/1[0]/1/2[0]/6[0]/6[0]/6[0]/6[1]/0/0[1]`)**. **400 (Auto Leading switched on for `A` CR `B`, size 100, leading 98; against its unedited save 399): the run style changes in `/4` (false -> true) and `/5` (98 -> 0.01) only, the stored second baseline moves from 98 to 120 px below the first (1.2 x 100), and After Effects measures the same 120 px (`text.measure`)**; the rest of the diff is save noise (`head`, the comp's modification time, the text's `btgu/pgui`). That `/5` holds 0.01 under automatic leading is seen in 400 only | 243, 339 (`/5`); 400 (`/4`); test `automatic_leading_is_slot_4` | V | +| **undecoded slots** | the run style and paragraph dictionaries of an untouched document (244; 110 stores the same bytes) are the reference: a slot that is not decoded and differs from it is listed (`TextDocument::undecoded_style_fields`, `undecoded_paragraph_fields`); a slot the reference lacks is listed only when it is not 0, `false`, empty or `/nil` (a neutral value is taken to carry nothing, so it is not reported as a loss; `/nil` is how 244 stores its paragraph slots `/27`, `/28` and `/36`). Decoded style slots: `/0 /1 /2 /3 /4 /5 /6 /7 /8 /9 /11 /12 /13 /18 /35 /36 /52 /53 /54 /56 /57 /58 /62 /63 /70`; paragraph slots: `/0 /1 /2 /3 /4 /5 /8 /9 /21 /29 /33`. Not found by any scriptable setting (none of the `text.set_style` attributes tried in S17 changes them): style `/20 /38 /78 /87 /88`, paragraph `/31 /32`. **Paragraph `/24`, `/35` and style `/68`** (1, 1 and 0 in a scripted text) were edited in place in the wrapping box text 517 (732: `/24` 0, 733: `/35` 0, 734: `/68` 1, same length); After Effects opens each without a dialog, keeps the value on a re-save and composes the same four lines, baselines and bounds (`text.measure`, `layer.bounds`; 734 renders like 517), so 0 and 1 are not listed (`NEUTRAL_PARAGRAPH_VALUES`, `NEUTRAL_STYLE_VALUES`; their meaning stays unknown, Latin text only). **Paragraph `/34`** is 0 in a scripted text and 7 after Reset Paragraph (727: the only slot that changes); a justified 600 px box text of 88 characters composes the same four lines, baselines and bounds with both values (S18), so 0 and 7 are not listed (`NEUTRAL_PARAGRAPH_VALUES`), other values are | every text sample lists none; 725, 727 | V (reference), E (/34) | +| **Source Text record** | the `tdbs` in `btds[ADBE Text Document]` (next to the `btdk`) has no keys and no expression in every sample; Source Text keyframes (presumably one `btdk` per key) and expressions were not sampled, the reader only reports them (`Layer::source_text_property`, `Layer::text_document_count`) | 110-114, 243-248, 334-340 | E | + +API: `TextDocument` (`paragraphs`, `style_runs`, `text_box`, `paragraph_texts`, `font_of`, +`incomplete_runs`, `undecoded_style_fields`, `undecoded_paragraph_fields`, `kerning`, +`line_orientation`), `StyleRun::{faux_bold, faux_italic, caps, auto_leading, leading, stroke_argb, +font_index, horizontal_scale, vertical_scale, baseline_shift, auto_kern, ligatures, +baseline_direction, tsume, no_break, apply_fill, apply_stroke, stroke_over_fill, line_join, +stroke_width, digit_set}`, `ParagraphRun::{first_line_indent, start_indent, end_indent, space_before, +space_after, leading_type, auto_hyphenate, hanging_roman, every_line_composer, direction}`, `Caps`, +`AutoKern`, `KernRun`, `Justification`. +A damaged run is never dropped silently: a run without a readable length is left out, a run with a +missing size, fill or font index takes them from the run before it, and both count in +`incomplete_runs`. Tests: `tests/text_markers_footage.rs`, `tests/batch3_objects.rs`, +`tests/text_fields.rs`. + +### 3.11 Markers + +`mrst[ADBE Marker]` holds a `tdbs` with a `list` of 16-byte records (the times; `tdb4` byte 12 is the +time scale) and one `LIST mrky/LIST Nmrd` per marker. Layer markers live in the layer's own tree, +composition markers in the `SecL` list named `Markers`. + +| What | Chunk path | Meaning | Evidence | Conf. | +|---|---|---|---|---| +| time | the key list | 25 600 = 1 s | 122, 123, 249 | V | +| **duration** | `Nmrd/NmHd` (20 bytes: u32 4, u32 0, u32 duration, u32 600, u32 0) | duration / 600 = the marker duration in seconds (1 s is 600; 0 for none); 600 is the units per second; **0.5 s and 0.3 s read back exactly (509, 510)** | 249 (1 s), 122 (0), 509, 510 | V | +| **several markers** | the key records and the `Nmrd` lists in the same (time) order: 509 has two composition markers, 1 s `M1` label 2 and 2.5 s `M2` duration 0.5; a fractional time is a plain key time (0.52 s = 13 312 / 25 600, 510) | | 509, 510; test `tests/batch5.rs` | V | +| **strings** | five `Utf8` children of `Nmrd`, in the order **comment, chapter, URL, frame target, cue point name**; unused ones are empty | `LM`, `Chap`, `http://a.example/u`, `_blank`, `CueX` | 249 | V | +| **cue type** | `NmHd` u32 @0: **4 = event cue (also for markers without a cue point name), 5 = navigation cue** | 347 (4), 348 (5) | V | +| **cue parameters** | `NmHd` u32 @4 = the number of key / value pairs; the pairs follow the five fixed strings as `2 x pairs` extra `Utf8` (key, value, key, value): `speaker` = `A`, `n` = `2` with the cue point name `CueE` | 349 | V | +| **label** | `NmHd` u8 @16 (followed by three pad bytes): label 3 is `03 00 00 00`. The label is not in the keyframe flags (unlike the keyframe label of 057) | 347 | V | + +API: `Marker::{label, cue_type, cue_params}`, `CueType`. Tests: `tests/text_markers_footage.rs`, +`tests/batch3_objects.rs`. + +### 3.12 Cameras and lights + +Both have no source item (`ldta@40` is 0 for a camera, `0xffff_ffff` for a light), type 2 or 1, the 3D +bit and byte 38 bit `0x40` (3.1); `ldta@136` is the light type. Their properties sit in the same +groups as on other layers, with these conventions: + +| What | Path | Stored | Evidence | Conf. | +|---|---|---|---|---| +| camera Position, default (auto state) | `ADBE Transform Group/ADBE Position`, `tdb4` 76 and 77 = 1 although no expression exists | `[0, 0, -2666.67]` (x and y are 0 whatever the composition size; z = -zoom). A **one-node** camera reports `[0, 0, -2666.67]` (251). **Correction (S16): a reopened two-node camera reports `[0, 0, -2666.67]` too (256 read back), and After Effects renders it there**: the default two-node camera of 537 above the 3D solid of 486 renders from `[0, 0, -2666.67]` towards the point of interest, not like the composition's default view (537 differs from 486 in 24 % of the grid points, and EffectCraft's import with the stored position matches 537 but for 4 edge points). The `[960, 540, ...]` of the batch-3 notes was not reproduced (535 and 537, created by script, read back the stored value too); the reader keeps only the stored value (`CameraPosition::stored`) | 256, 251, 537 | V | +| camera Position, set by the user | same, `tdb4` 76 and 77 = 0 | the absolute value `[100, 200, -1000]` | 253 | V | +| camera point of interest | `ADBE Anchor Point` | `[960, 540, 0]` in **pixels** (not a fraction); the record's `tdsb` is 1 on a two-node and 3 on the one-node camera (not asserted) | 251, 253, 256 | V (value), E (`tdsb`) | +| light Position, default | same as the camera | `[0, 0, -1333.33]`, as After Effects reports it (255 read back); the point of interest `[960, 540, 0]` | 254, 255 | V | +| light intensity | `ADBE Light Options Group/ADBE Light Intensity` | f64 50.0 percent, `tdsb` 1; absent at the default 100 | 254 (50), 252 (absent) | V | +| light type | `ldta@136` | 1 spot, 2 point | 254, 252 | V | +| **camera Zoom** | `ADBE Camera Options Group/ADBE Camera Zoom` | plain pixels (`tdsb` 1), absent at the default 2 666.67; the auto Position keeps `[0, 0, -2666.67]` and is not recomputed from the zoom | 341 (2000) | V | +| **camera depth of field** | same group: `ADBE Camera Depth of Field` 1.0 (checkbox descriptor `ffff0004`), `ADBE Camera Focus Distance` 800, `ADBE Camera Aperture` 30 (plain numbers), all `tdsb` 1. **Defaults (256 read back): Depth of Field off, Focus Distance = Zoom = 2 666.67, Aperture 25.309 336 332 958 4, Blur Level 100** | 342, 256 | V | +| **light Casts Shadows** | `ADBE Light Options Group/ADBE Casts Shadows` | a set record (`tdsb` 1) holding 0.0 (off) in every light | 252, 254, 255 | V | +| **3D rotations** | `ADBE Rotate X`, `ADBE Rotate Y` | plain degrees, absent at 0 | 486, 487 | V | +| **Orientation** | `LIST otst` = `tdbs` + `LIST otky/otda`: `otda` is three big-endian `f64` degrees; absent at `[0, 0, 0]`. Keyed orientation is not sampled | 488, 485 | V | +| **light colour** | `ADBE Light Options Group/ADBE Light Color` | ARGB doubles 0..255 (`[255, 255, 0, 0]` for red; 4 components, descriptor `0002ffff`), absent = white | 343 | V | +| **light cone** | same group: `ADBE Light Cone Angle` 60 and `ADBE Light Cone Feather 2` 30 (percent), each `tdsb` 1 and absent in the default spot light (90 and 50). Every point light stores them as `tdsb` 3 records with 90 and 50 (a point light created directly equals the converted one of 252, so the "odd" property set is not a conversion artefact) | 344, 345, 346, 252 | V | + +A point light made by converting a spot light has a different property set (`Orientation`, `Rotate +X/Y/Z`, `Cone Angle`, `Cone Feather 2` in the default state) that a spot light lacks (252); whether that +is an artefact of the conversion is untested. API: `Layer::camera_position`; the camera and light +options are read by the importer's table (`import/camera.rs`); `DEFAULT_CAMERA_ZOOM` (2 666.67 is verified for the 1920 px +composition only), `Layer::orientation` (`Orientation`; test `orientation_is_otst_otda` in +`tests/batch5.rs`). Render checks against After Effects (20 px grid, 5 184 points): 486 1 point +off, 535 2, 536 0, 537 4 (anti-aliased edges); **488 (Orientation `[10, 20, 30]`): 272 points +(5.25 %) differ; the import carries the stored angles, and permuted or negated inputs match worse +(6.2 % to 34 %), so the cause is in EffectCraft's renderer and not isolated.** Tests: `tests/layer_switches.rs`, `tests/batch3_objects.rs`. + +### 3.12a Project settings (top-level chunks; cases 620-634) + +Each case is the base reopened and saved with one setting changed (`project.set_settings`), compared +with 620 (the base saved the same way); apart from the save noise (`head` byte 19, `nhed` / `nnhd` +bytes 20-27 / 28-35, `fdta`) only the bytes below changed. + +| setting | where | stored | cases | conf | +|---|---|---|---|---| +| colour depth | `nhed` byte 15 (and `nnhd` byte 24) | 0 = 8, 1 = 16, 2 = 32 bits per channel (the base is 32) | 620, 621, 622, 631 | V | +| working space | `cpid` (16 bytes) and the `Utf8` right after `PwCs` | None: `cpid` all `0xff` and the JSON `{}`; a profile: JSON `{"baseColorProfile":{"colorProfileData":"","colorProfileName":""},"baseProfileType":2}` (`sRGB IEC61966-2.1` in the base, `Rec.709 Gamma 2.4` in 624) and `cpid` a 16-byte id of the profile; After Effects 26.2.1 leaves `colorProfileName` out in a fresh save (settings-c), and the name is then the profile's ICC `desc` tag (v2 `desc` or v4 `mluc`) | 620, 623, 624, 631, 902 | V (None, the name), ? (`cpid`) | +| working gamma | `dwga` `u32` @0 | 0 = 2.2, 1 = 2.4 | 625, 631 | V | +| Linearize Working Space | `lnrp` (1 byte, 1) inserted after `cpid` | absent when off | 626, 632 | V | +| Blend Colors Using 1.0 Gamma | `lnrb` (1 byte, 1) inserted after `cpid`, before `lnrp` | absent when off | 627, 632 | V | +| Compensate for Scene-referred Profiles | `acer` byte 0 | 1 on (base), 0 off | 628 | V | +| time display | `nhed` (and `nnhd`) byte 8 | 0 timecode, 1 frames; feet + frames: byte 8 = 1 and byte 11 = 1, byte 13 = frames per foot (16 = 35 mm, 40 = 16 mm; the base holds 16) | 629, 633, 634 | V | +| frame count start | `nhed` byte 14 (`nnhd` byte 20) | 2 for a count from 0 (base), 1 for a count from 1 | 630 | E (one value each) | + +The audio sample rate of the project is `adfr` (`f64` 48 000 in every case, not varied). API: +`ProjectSettings::read` (`TimeDisplay`, `WorkingSpace`). Test: `tests/it/container/cases_600.rs`. The +fixture of 624 is not in the repository: its working-space JSON holds the profile data After +Effects embeds for that space. + +### 3.12b Layer styles (`tdgp[ADBE Layer Styles]`; cases 950-980) + +Every layer's root group holds `ADBE Layer Styles` (third, after Time Remapping and Transform), also +when no style is used (950). Inside: `ADBE Blend Options Group` (Global Light Angle `ADBE Global +Angle2`, Altitude `ADBE Global Altitude2`, and `ADBE Adv Blend Group` with `ADBE Layer Fill +Opacity2`, `ADBE R/G/B Channel Blend`, `ADBE Blend Interior`, `ADBE Blend Ranges`; 977), then one +switch group per style, `café <3", opts); +let mut text = String::new(); +while let Some(token) = lexer.next() { + match token { + Token::Text(t) => text.push_str(&unescape(t)), + // A style sheet's text, for a caller that reads it. + Token::Start(tag) if tag.name == "style" => assert_eq!(lexer.raw_content("style"), "p{}"), + Token::Start(tag) => assert_eq!(tag.attr("class").as_deref(), Some("x")), + Token::End(name) => assert_eq!(name, "b"), + } +} +assert_eq!(text, "café <3"); +assert_eq!(escape(&text), "café <3"); +``` + +## The tokenizer + +`Lexer` is an iterator of `Token::Text`, `Token::Start(Tag)` and `Token::End(name)`, borrowed +from the input. Text and attribute values come as written; `unescape` and `Tag::attr` decode +them. + +- A `<` that starts no tag is text. A tag, comment or raw element that never ends runs to the + end of the input. +- Comments, doctypes, processing instructions and conditional comments never come out. +- `Options::drop`: elements skipped whole, content and end tag included. +- `Options::raw_text`: elements whose content is one text token, not markup. +- `Lexer::raw_content(name)`: after a start tag, take the element's raw content yourself. +- `Limits`: attributes kept per tag (64) and the longest tag name (64 bytes; a longer one has an + empty name). + +## Character references + +`unescape` decodes named, decimal and hex references. The named set is HTML 4's (Latin-1, Greek, +symbols, arrows, mathematics) and a few more. The 94 legacy names decode without their `;` +(`© 2024`), longest match first, as in browsers; `unescape_attr` leaves such a name alone +when a letter, a digit or `=` follows, so a query string keeps its `©=1`. A numeric reference +to 0x80-0x9F means the Windows-1252 character; 0, surrogates, and numbers past U+10FFFF or too +long to be numbers become U+FFFD. Names are looked at for 32 bytes at most, so the work is +linear. + +`escape` writes `& < > " '` as references; `escape_dq` leaves `'`, for content and attribute +values in double quotes. + +## HTML documents (feature `flow`) + +`craft_html::doc` reads a page or a pasted fragment into the [craft-flow](../flow/README.md) +model and a craft-wordmodel `Document`, and writes one as clean HTML. The reader is a tolerant +tag-soup builder on this crate's tokenizer (a stack of open elements with HTML's implicit closes), +with a CSS subset from `style` attributes and `\n\n\n", + ); + blocks_html(&flow.blocks, &mut out, 0); + out.push_str("\n\n"); + out +} diff --git a/crates/html/src/doc/import.rs b/crates/html/src/doc/import.rs new file mode 100644 index 000000000..c653f4b44 --- /dev/null +++ b/crates/html/src/doc/import.rs @@ -0,0 +1,125 @@ +use super::builder::{Builder, ImageLoader, parse_sheet}; +use super::lexer::{Lexer, Tok}; +use super::math_ruby::{read_math, read_ruby}; +use super::{Document, Flow, Inline, model}; + +/// Parse HTML text into the flow model. +pub fn parse(s: &str) -> Flow { + parse_with(s, &|_| None) +} + +/// [`parse`], loading pictures that aren't `data:` URIs through `images`. +pub fn parse_with(s: &str, images: ImageLoader) -> Flow { + parse_in(s, images, false) +} + +pub(super) fn parse_in(s: &str, images: ImageLoader, page: bool) -> Flow { + // HTML normalizes input newlines before tokenization, not after decoding character references. + let normalized = if s.contains('\r') { + let mut out = String::with_capacity(s.len()); + let mut chunks = s.split('\r'); + out.push_str(chunks.next().unwrap_or_default()); + for chunk in chunks { + out.push('\n'); + out.push_str(chunk.strip_prefix('\n').unwrap_or(chunk)); + } + std::borrow::Cow::Owned(out) + } else { + std::borrow::Cow::Borrowed(s) + }; + // The lexer's offsets (a style element's text is cut out by them) are into the normalized text. + let s: &str = &normalized; + let mut lx = Lexer::new(s); + let mut b = Builder::new(images, page); + let mut guard = 0usize; + while let Some(t) = lx.next() { + guard += 1; + if guard > 50_000_000 { + break; + } + match t { + Tok::Text(t) => b.text(&t), + Tok::Start { name, attrs, self_close } => { + b.close_head_for_start(&name); + if craft_math::mathml::local(&name) == "math" && !self_close { + let el = read_math(&mut lx, name, attrs); + if !b.in_head() + && let Some((linear, display)) = craft_math::mathml::read(&el) + { + b.start_para().inlines.push(Inline::Equation { linear, display }); + } + continue; + } + if name == "ruby" && !self_close { + let r = read_ruby(&mut lx); + if !b.in_head() { + b.push_ruby(&r.base, &r.ruby); + } + continue; + } + if matches!(name.as_str(), "script" | "style" | "noscript" | "template" | "textarea") && !self_close { + let from = lx.pos(); + let to = lx.skip_past_end_tag(&name); + if name == "style" { + parse_sheet(s.get(from..to).unwrap_or(""), &mut b.sheet); + } + continue; + } + b.start(&name, &attrs, self_close); + } + Tok::End(name) => b.end(&name), + } + } + b.finish() +} + +/// Collapse white space inside ruby markup as body text does (HTML's white space only: an +/// ideographic space is text), without the space the element's indentation leaves at the edges. +pub(super) fn collapse_ws(s: &str) -> String { + let mut out = String::with_capacity(s.len()); + for c in s.chars() { + if matches!(c, ' ' | '\t' | '\n' | '\r' | '\u{000C}') { + if !out.ends_with(' ') { + out.push(' '); + } + } else { + out.push(c); + } + } + out.trim_matches(' ').to_string() +} + +/// Parse HTML into a document. +pub fn import(s: &str) -> Document { + model::begin_import(); + model::to_doc(&parse(s)) +} + +/// [`import`], loading pictures that aren't `data:` URIs through `images`. +pub fn import_with(s: &str, images: ImageLoader) -> Document { + model::begin_import(); + model::to_doc(&parse_with(s, images)) +} + +/// A web page opened as a document, as Word opens one (a file, or a document's HTML +/// `w:altChunk`): its text is Times New Roman 12 pt on single lines, headings bold and black at +/// the sizes browsers give them, and a `p` or heading whose CSS leaves a margin out (or writes it +/// invalidly) gets HTML's automatic spacing there; a margin a span states replaces the one its +/// paragraph states (both as Word's import does). [`import`] reads a pasted fragment, which takes +/// the document's own formatting instead (but its CSS still applies). +pub fn import_page(s: &str, images: ImageLoader) -> Document { + model::begin_import(); + model::to_doc(&parse_in(s, images, true)) +} + +/// [`import_page`] onto `page` (its size and margins), which tables size to: HTML gives no page +/// size, so the caller picks it (the region's paper, #1381). +pub fn import_on(s: &str, images: ImageLoader, page: &craft_wordmodel::SectionProps) -> Document { + model::begin_import(); + model::to_doc_in(&parse_in(s, images, true), page.clone()) +} + +/// The font of a web page's text when its CSS names none. +pub const PAGE_FONT: &str = "Times New Roman"; +/// Heading sizes on a web page, `h1`–`h6`, points. +pub(super) const PAGE_HEADING_SIZES: [f32; 6] = [24.0, 18.0, 13.5, 12.0, 10.0, 7.5]; diff --git a/crates/html/src/doc/lexer.rs b/crates/html/src/doc/lexer.rs new file mode 100644 index 000000000..a29d6d38b --- /dev/null +++ b/crates/html/src/doc/lexer.rs @@ -0,0 +1,50 @@ +//! The crate's tokenizer ([`crate::Lexer`]) as the document reader takes its tokens: text and +//! attribute values decoded, element and attribute names in lower case. + +use crate::{Token, unescape, unescape_attr}; + +#[derive(Debug)] +pub(super) enum Tok { + Text(String), + Start { name: String, attrs: Vec<(String, String)>, self_close: bool }, + End(String), +} + +pub(super) struct Lexer<'a> { + inner: crate::Lexer<'a, 'static>, +} + +impl<'a> Lexer<'a> { + pub(super) fn new(s: &'a str) -> Lexer<'a> { + Lexer { inner: crate::Lexer::new(s) } + } + + /// Where the next token starts. + pub(super) fn pos(&self) -> usize { + self.inner.pos() + } + + /// Read again from `pos` (an earlier [`Lexer::pos`]). + pub(super) fn set_pos(&mut self, pos: usize) { + self.inner.set_pos(pos); + } + + /// Skip past the end tag of raw text element `tag`; returns where that end tag starts (the + /// end of the input when there is none). + pub(super) fn skip_past_end_tag(&mut self, tag: &str) -> usize { + let from = self.inner.pos(); + from + self.inner.raw_content(tag).len() + } + + pub(super) fn next(&mut self) -> Option { + Some(match self.inner.next()? { + Token::Text(t) => Tok::Text(unescape(t)), + Token::Start(tag) => Tok::Start { + attrs: tag.attrs.iter().map(|(n, v)| (n.to_ascii_lowercase(), unescape_attr(v))).collect(), + name: tag.name, + self_close: tag.self_close, + }, + Token::End(name) => Tok::End(name), + }) + } +} diff --git a/crates/html/src/doc/math_ruby.rs b/crates/html/src/doc/math_ruby.rs new file mode 100644 index 000000000..3a81cde50 --- /dev/null +++ b/crates/html/src/doc/math_ruby.rs @@ -0,0 +1,156 @@ +use super::builder::block_kind; +use super::lexer::{Lexer, Tok}; + +/// A `` element (#816): its tokens up to the matching end tag, as a tree. Nesting and size +/// are bounded; an unclosed element ends with the input. +pub(super) fn read_math(lx: &mut Lexer, name: String, attrs: Vec<(String, String)>) -> craft_math::mathml::El { + use craft_math::mathml::{El, Item, MAX_NODES, local}; + let mut stack: Vec = vec![El { name, attrs, children: Vec::new() }]; + let mut count = 0usize; + let close = |stack: &mut Vec| { + if stack.len() > 1 + && let Some(done) = stack.pop() + && let Some(parent) = stack.last_mut() + { + parent.children.push(Item::El(done)); + } + }; + while let Some(t) = lx.next() { + count += 1; + if count > MAX_NODES * 4 { + // Over the cap: drop the rest of this element so its tokens aren't read as HTML text. + skip_math(lx, t); + break; + } + match t { + Tok::Text(t) => { + if let Some(top) = stack.last_mut() + && !t.is_empty() + { + top.children.push(Item::Text(t)); + } + } + Tok::Start { name, attrs, self_close } => { + let el = El { name, attrs, children: Vec::new() }; + if self_close || stack.len() > craft_wordmodel::math::MAX_DEPTH { + if let Some(top) = stack.last_mut() { + top.children.push(Item::El(el)); + } + } else { + stack.push(el); + } + } + Tok::End(name) => { + let name = local(&name).to_string(); + // Close up to the matching open element; a stray end tag is ignored. + if let Some(k) = stack.iter().rposition(|e| local(&e.name) == name) { + if k == 0 { + break; + } + while stack.len() > k { + close(&mut stack); + } + } + } + } + } + while stack.len() > 1 { + close(&mut stack); + } + stack.pop().unwrap_or_default() +} + +/// Skip tokens (starting with `first`) up to and including the `` that closes the element +/// being read; nested `` elements are counted. An unclosed element ends with the input. +fn skip_math(lx: &mut Lexer, first: Tok) { + use craft_math::mathml::local; + let mut depth = 0usize; + let mut t = Some(first); + while let Some(tok) = t { + match tok { + Tok::Start { name, self_close: false, .. } if local(&name) == "math" => depth = depth.saturating_add(1), + Tok::End(name) if local(&name) == "math" => { + if depth == 0 { + return; + } + depth = depth.saturating_sub(1); + } + _ => {} + } + t = lx.next(); + } +} + +/// A `` element's base text and reading (#1681). +#[derive(Default)] +pub(super) struct RubyText { + pub(super) base: String, + pub(super) ruby: String, +} + +/// Which part of a `` element the text being read belongs to. +#[derive(Clone, Copy, PartialEq, Eq)] +enum RubyPart { + /// The text being annotated: an `` child, or the text outside ``/``. + Base, + /// The reading: an `` child. + Ruby, + /// `` fallback parentheses, which are not text: browsers show them only where ruby isn't + /// supported. + Fallback, +} + +/// A block-level tag ends an open `` implicitly, as it does in a browser. +fn ends_ruby(t: &Tok) -> bool { + match t { + Tok::Start { name, .. } | Tok::End(name) => block_kind(name).is_some(), + Tok::Text(_) => false, + } +} + +/// Read a `` element's content: its base text from `` children (or the text outside +/// them), its reading from `` children, and `` fallback parentheses dropped. Tolerant, +/// like the rest of the reader: tags inside are ignored, an unclosed element ends at the next +/// block-level tag (handed back to the caller) or with the input, and the tokens read are capped. +pub(super) fn read_ruby(lx: &mut Lexer) -> RubyText { + /// Most tokens one `` element is read from: a missing end tag must not scan the rest of + /// a hostile file here. + const MAX_TOKENS: usize = 4096; + let mut out = RubyText::default(); + let mut part = RubyPart::Base; + let mut nested = 0usize; + let mut count = 0usize; + while count < MAX_TOKENS { + count += 1; + let start = lx.pos(); + let Some(t) = lx.next() else { break }; + if nested == 0 && ends_ruby(&t) { + // The boundary ends the element: give the token back to the main reader. + lx.set_pos(start); + break; + } + match t { + Tok::Text(t) => match part { + RubyPart::Base => out.base.push_str(&t), + RubyPart::Ruby => out.ruby.push_str(&t), + RubyPart::Fallback => {} + }, + // The self-closing slash is ignored on HTML elements (`` opens an `rt`), as in a + // browser's parser. + Tok::Start { name, self_close, .. } => match name.as_str() { + "rb" => part = RubyPart::Base, + "rt" => part = RubyPart::Ruby, + "rp" => part = RubyPart::Fallback, + "ruby" if !self_close => nested += 1, + _ => {} + }, + Tok::End(name) => match name.as_str() { + "rb" | "rt" | "rp" => part = RubyPart::Base, + "ruby" if nested > 0 => nested -= 1, + "ruby" => break, + _ => {} + }, + } + } + out +} diff --git a/crates/html/src/doc/tests.rs b/crates/html/src/doc/tests.rs new file mode 100644 index 000000000..640ab07d0 --- /dev/null +++ b/crates/html/src/doc/tests.rs @@ -0,0 +1,769 @@ +use super::*; + +#[test] +fn numeric_entity_rejects_sign() { + assert_eq!(unescape("a&#+65;b"), "a&#+65;b"); + assert_eq!(unescape("a&#x+41;b"), "a&#x+41;b"); + assert_eq!(unescape("aAAb"), "aAAb"); +} + +#[test] +fn important_declarations_win_the_cascade() { + let color = |html: &str| fmt_of(paras(&parse(html))[0]).color; + let red = Some(craft_wordmodel::Rgb(255, 0, 0)); + let blue = Some(craft_wordmodel::Rgb(0, 0, 255)); + assert_eq!(color("

x

"), blue); + assert_eq!(color("

x

"), red); + assert_eq!(color("

x

"), blue); + assert_eq!(color("

x

"), red); +} + +#[test] +fn a_declared_charset_decodes_the_page() { + // ISO 8859-2 (Central European): 0xA9 Š, 0xB9 š; named by the caller or the page. + assert_eq!(decode_as(&[0xA9, b' ', 0xB9], Some("iso-8859-2")), "Š š"); + assert!(decode_as(b"

\xA9

", None).contains("

Š

")); + assert_eq!(decode_as(&[0x8A], Some("windows-1252")), "Š"); + // A page that says UTF-16 without a BOM is read as UTF-8, as browsers do. + assert_eq!(decode_as("é".as_bytes(), Some("utf-16")), "é"); +} + +fn texts(f: &Flow) -> Vec { + f.blocks + .iter() + .map(|b| match b { + FBlock::Para(p) => format!("{:?}{:?}:{}", p.kind, p.list.map(|l| (l.ordered, l.level)), p.text()), + FBlock::Table(t) => format!("table{}x{}", t.rows.len(), t.cols()), + }) + .collect() +} + +fn table_style(html: &str) -> Option { + let doc = craft_flow::to_doc(&parse(html)); + doc.body.iter().find_map(|b| match &**b { + craft_wordmodel::Block::Table(t) => Some(t.props.style.clone().unwrap_or_default()), + _ => None, + }) +} + +#[test] +fn borderless_tables_get_no_grid_style() { + assert_eq!(table_style("
ab
").as_deref(), Some("")); + assert_eq!(table_style("
a
").as_deref(), Some("")); + assert_eq!(table_style("
a
").as_deref(), Some("")); + assert_eq!(table_style("
a
").as_deref(), Some("TableGrid")); + assert_eq!(table_style("
a
").as_deref(), Some("TableGrid")); + assert_eq!(table_style("
a
").as_deref(), Some("TableGrid")); + // The last declaration decides: a `style` attribute's over the style sheet's. + assert_eq!(table_style("
a
").as_deref(), Some("TableGrid")); + assert_eq!(table_style("
a
").as_deref(), Some("")); +} + +#[test] +fn borderless_tables_export_without_cell_borders() { + // #438: a table without grid style and borders writes no cell borders and reopens borderless. + for (src, grid) in [ + ("
AB
", false), + ("
AB
", false), + ("
AB
", true), + ] { + let out = export(&craft_flow::to_doc(&parse(src))); + assert_eq!(out.contains("border:1px"), grid, "{src}: {out}"); + assert_eq!(table_style(&out).as_deref(), Some(if grid { "TableGrid" } else { "" }), "{src}"); + assert!(out.contains(">A") && out.contains(">B"), "{out}"); + } +} + +#[test] +fn input_newlines_preserve_preformatted_lines() { + for newline in ["\n", "\r\n", "\r"] { + let f = parse(&format!("
{newline}  Alpha{newline}  Beta{newline}{newline}  Gamma
")); + assert_eq!(texts(&f), ["CodeNone: Alpha", "CodeNone: Beta", "CodeNone:", "CodeNone: Gamma"], "{newline:?}"); + let FBlock::Para(p) = &f.blocks[1] else { panic!() }; + assert!(matches!(p.inlines.last(), Some(Inline::Text(t, f)) if t == "Beta" && f.bold)); + } +} + +#[test] +fn input_newlines_are_normalized_before_character_references() { + let f = parse("

A B\r\nC\rD

A\r\nB\rC

"); + assert_eq!(texts(&f), ["NormalNone:A\rB\nC\nD", "NormalNone:A B C"]); + let f = parse("

α\r\r\nβ γ

link"); + assert_eq!(texts(&f), ["NormalNone:α\n\nβ\rγ", "NormalNone:link"]); + let FBlock::Para(p) = &f.blocks[1] else { panic!() }; + assert!(matches!(p.inlines.first(), Some(Inline::Text(_, f)) if f.link.as_deref() == Some("https://example.test/a\nb\nc\rd"))); +} + +#[test] +fn css_preformatted_paragraphs_keep_edge_spaces() { + // #439: `white-space:pre` keeps leading and trailing spaces like `
`; normal
+    // paragraphs still collapse.
+    let f = parse(
+        "

Alpha Beta

\n Gamma \n

  Alpha  

Alpha Beta

", + ); + assert_eq!(texts(&f), vec!["NormalNone: Alpha Beta ", "NormalNone: Gamma ", "CodeNone: Alpha ", "NormalNone:Alpha Beta"]); +} + +#[test] +fn tag_soup() { + let f = parse( + "T & U

Head

One bold

Two it\n text

  • a
  • b
    1. c
xy
z
q
l1\nl2
", + ); + assert_eq!(f.meta.title, "T & U"); + assert_eq!( + texts(&f), + vec![ + "Heading(1)None:Head", + "NormalNone:One bold", + "NormalNone:Two it text", + "NormalSome((false, 0)):a", + "NormalSome((false, 0)):b", + "NormalSome((true, 1)):c", + "table2x3", + "QuoteNone:q", + "CodeNone:l1", + "CodeNone:l2", + ] + ); + let FBlock::Para(p) = &f.blocks[1] else { panic!() }; + assert!(matches!(&p.inlines[1], Inline::Text(t, f) if t == "bold" && f.bold)); +} + +#[test] +fn omitted_head_keeps_body_text() { + let f = parse("T\n

Hello world

Second

"); + assert_eq!(f.meta.title, "T"); + assert_eq!(texts(&f), vec!["NormalNone:Hello world", "NormalNone:Second"]); + + for body in [ + "

Hello world

", + "
Hello world
", + "Hello world", + "Hello world", + "Hello world", + "Hello world", + ] { + let f = parse(&format!( + "T & U{body}", + )); + assert_eq!(f.meta.title, "T & U"); + assert_eq!(f.meta.author, "Ann"); + assert_eq!(texts(&f), vec!["NormalNone:Hello world"], "{body}"); + } +} + +#[test] +fn styles_and_links() { + let f = parse("

red l
n

"); + let FBlock::Para(p) = &f.blocks[0] else { panic!() }; + assert_eq!(p.align, Some(Align::Center)); + assert!(matches!(&p.inlines[0], Inline::Text(t, f) if t == "red" && f.bold && f.color == Some(craft_wordmodel::Rgb(255,0,0)))); + assert!(p.inlines.iter().any(|i| matches!(i, Inline::Text(t, f) if t == "l" && f.link.as_deref() == Some("http://x")))); + assert!(p.text().ends_with("l\nn")); +} + +/// The paragraphs of every cell of the first table, row by row. +fn cell_paras(f: &Flow) -> Vec>> { + let Some(FBlock::Table(t)) = f.blocks.iter().find(|b| matches!(b, FBlock::Table(_))) else { panic!("no table") }; + t.rows + .iter() + .map(|r| r.iter().map(|c| c.blocks.iter().filter_map(|b| if let FBlock::Para(p) = b { Some(p.clone()) } else { None }).collect()).collect()) + .collect() +} + +fn all_bold(p: &Para) -> bool { + !p.inlines.is_empty() && p.inlines.iter().all(|i| matches!(i, Inline::Text(_, f) if f.bold)) +} + +fn any_bold(p: &Para) -> bool { + p.inlines.iter().any(|i| matches!(i, Inline::Text(_, f) if f.bold)) +} + +#[test] +fn header_cells_are_bold_unless_their_css_says_otherwise() { + // #1381: a is bold, as in browsers and Word; `font-weight:normal` on it or inside it wins. + let f = parse( + "
HeadPlainInner
abc
", + ); + let rows = cell_paras(&f); + assert!(all_bold(&rows[0][0][0]), "{:?}", rows[0][0]); + assert!(!any_bold(&rows[0][1][0]), "{:?}", rows[0][1]); + assert!(!any_bold(&rows[0][2][0]), "{:?}", rows[0][2]); + assert!(!any_bold(&rows[1][0][0]), "td stays regular"); +} + +#[test] +fn cell_text_align_reaches_the_cell_paragraphs() { + // #1381: `text-align` on a td/th, or inherited from its tr/thead/tbody/table, aligns the + // cell's paragraphs; a paragraph's own text-align inside the cell wins. + let f = parse( + "\ + \ +
rinherited

own

attr
body
table
", + ); + let rows = cell_paras(&f); + assert_eq!(rows[0][0][0].align, Some(Align::Right), "td style"); + assert_eq!(rows[0][1][0].align, Some(Align::Right), "from tr"); + assert_eq!(rows[0][2][0].align, Some(Align::Center), "own paragraph wins"); + assert_eq!(rows[0][3][0].align, Some(Align::Right), "align attribute"); + assert_eq!(rows[1][0][0].align, Some(Align::Justify), "from tbody"); + assert_eq!(rows[2][0][0].align, Some(Align::Center), "from table"); + // `align` on a table places the table; it doesn't align the text in its cells. + let f = parse("
x
"); + assert_eq!(cell_paras(&f)[0][0][0].align, None); +} + +#[test] +fn reporter_sample_header_bold_and_right_aligned_cells() { + // #1381: the reporter's table. + let f = parse( + "\n\n\n\n
IndicatoreValore atteso
Audit4
", + ); + let rows = cell_paras(&f); + assert!(all_bold(&rows[0][0][0]) && all_bold(&rows[0][1][0]), "{:?}", rows[0]); + assert_eq!(rows[1][1][0].align, Some(Align::Right)); + assert_eq!(rows[1][0][0].align, None); +} + +#[test] +fn entities() { + assert_eq!(unescape("a <b> AB &bogus; &"), "a AB &bogus; &"); + assert_eq!(unescape("− © &EURO; ™ ½ ¾"), "− © € ™ ½ ¾"); + assert_eq!(unescape("θ λ Δ ∇ ∑ √ ≠ ≤ ≥ ♥"), "θ λ Δ ∇ ∑ √ ≠ ≤ ≥ ♥"); +} + +/// Browsers decode numeric and legacy named references without their `;` in text, +/// but keep `&name=` and `&nameX` intact inside attribute values (query strings). +#[test] +fn references_without_semicolon() { + assert_eq!(unescape("© 2024 Acme"), "© 2024 Acme"); + assert_eq!(unescape("© 2024 Acme"), "© 2024 Acme"); + assert_eq!(unescape("© 2024 & <"), "© 2024 & <"); + assert_eq!(unescape("&bogus &# &#x &"), "&bogus &# &#x &"); + assert_eq!(unescape(" x"), "\u{00A0}x"); + let f = parse("

l © 2024

"); + let FBlock::Para(p) = &f.blocks[0] else { panic!() }; + assert!(p.inlines.iter().any(|i| matches!(i, Inline::Text(t, f) if t == "l" && f.link.as_deref() == Some("/q?a=1©=2®2=3&b=<")))); + assert!(p.text().ends_with("© 2024")); +} + +#[test] +fn wbr_word_break_opportunity() { + let f = parse("

Supercalifragilistic

"); + let Some(FBlock::Para(p)) = f.blocks.first() else { panic!("expected para") }; + assert_eq!(p.text(), "Super\u{200B}cali\u{200B}fragilistic"); +} + +#[test] +fn page_break_after_and_before() { + let f = parse("

First

Second

"); + let paras: Vec<_> = f.blocks.iter().filter_map(|b| if let FBlock::Para(p) = b { Some(p) } else { None }).collect(); + assert_eq!(paras.len(), 2); + assert!(!paras[0].page_break); + assert!(paras[1].page_break); + + let f2 = parse("

Part 1

Part 2

"); + let paras2: Vec<_> = f2.blocks.iter().filter_map(|b| if let FBlock::Para(p) = b { Some(p) } else { None }).collect(); + assert_eq!(paras2.len(), 2); + assert!(!paras2[0].page_break); + assert!(paras2[1].page_break); +} + +#[test] +fn font_size_relative_and_absolute() { + let f = parse("largersmallerhuge"); + let inls = match &f.blocks[0] { + FBlock::Para(p) => &p.inlines, + _ => panic!("expected para"), + }; + let sizes: Vec> = inls + .iter() + .map(|i| match i { + Inline::Text(_, fmt) => fmt.size, + _ => None, + }) + .collect(); + assert_eq!(sizes, vec![Some(13.5), Some(10.0), Some(18.0)]); +} + +#[test] +fn decode_with_charset_declarations() { + let iso = b"\xE9l\xE8ve"; + assert!(decode(iso).contains("élève")); + + let win = b"\x80100"; + assert!(decode(win).contains("€100")); + + let gbk = b"\xC4\xE3\xBA\xC3"; + assert!(decode(gbk).contains("你好")); + + let xml = b"hello"; + assert!(decode(xml).contains("hello")); +} + +#[test] +fn raw_text_elements_skip_only_matching_end_tag() { + let f = parse("

Hello

"); + assert_eq!(f.blocks.len(), 1); + let p = match &f.blocks[0] { + FBlock::Para(p) => p, + b => panic!("expected para, got {b:?}"), + }; + assert_eq!(p.text(), "Hello"); + + let f = parse("

World

"); + assert_eq!(f.blocks.len(), 1); + let p = match &f.blocks[0] { + FBlock::Para(p) => p, + b => panic!("expected para, got {b:?}"), + }; + assert_eq!(p.text(), "World"); +} + +#[test] +fn leading_space_survives_round_trip() { + let doc = Document::from_text(" lead"); + let html = export(&doc); + assert!(!html.contains("

lead"), "{html}"); + let back = import(&html); + assert_eq!(back.plain_text(Default::default()).replace('\u{a0}', " "), " lead"); +} + +#[test] +fn css_escapes_read_every_kind_of_newline() { + // A backslash before CR LF, CR, LF or form feed continues the line; after hex digits, one + // of them (CR LF as one) ends the escape. + assert_eq!(css_unescape("A\\\r\nB\\\rC\\\nD\\\u{C}E"), "ABCDE"); + assert_eq!(css_unescape("\\41\r\nB \\42\u{C}C \\43 D"), "AB BC CD"); + assert_eq!(css_unescape("x\\'y\\"), "x'y"); +} + +#[test] +fn font_names_are_written_as_css_strings() { + // A font name could end the CSS string or the declaration and add CSS of its own (#3739). + let fonts = ["Arial\n;position:fixed", "Back\\slash", "O'Brien \"Sans\"", "A,B", "Times New Roman", "M+ 1p"]; + let mut p = Para::default(); + for (i, font) in fonts.iter().enumerate() { + p.push_text(&format!("t{i}"), &Fmt { font: Some((*font).into()), ..Default::default() }); + } + let html = export(&model::to_doc(&Flow { blocks: vec![FBlock::Para(p)], meta: Meta::default() })); + assert!(html.contains("font-family:'Times New Roman'") && html.contains("font-family:'M+ 1p'"), "{html}"); + let styles: Vec<&str> = html.split(" style=\"").skip(1).filter_map(|s| s.split('"').next()).filter(|s| s.contains("font-family")).collect(); + assert_eq!(styles.len(), fonts.len(), "{html}"); + for s in styles { + assert!(!s.contains([';', '\n']) && s.matches('\'').count() == 2, "{s}"); + } + // Read back, each run has its font as it was. + let back = parse(&html); + let runs: Vec<(String, Option)> = back + .blocks + .iter() + .filter_map(|b| if let FBlock::Para(p) = b { Some(p) } else { None }) + .flat_map(|p| p.inlines.iter()) + .filter_map(|i| if let Inline::Text(t, f) = i { Some((t.clone(), f.font.as_deref().map(String::from))) } else { None }) + .collect(); + for (i, font) in fonts.iter().enumerate() { + assert!(runs.contains(&(format!("t{i}"), Some(font.to_string()))), "{font:?} in {runs:?}"); + } +} + +/// A document that reads "I read " then a phonetic guide over `base`, then " daily.". +fn ruby_doc(base: &str, ruby: &str) -> Document { + let props = craft_wordmodel::CharProps::default(); + let mut p = craft_wordmodel::Paragraph::with_text("I read ", props.clone()); + let n = p.len(); + p.insert_object(n, craft_flow::ruby_object(base.into(), ruby.into(), 20.0), &props).unwrap(); + let n = p.len(); + p.insert_text(n, " daily.", &props).unwrap(); + let mut d = Document::new(); + d.body = vec![craft_wordmodel::para_block(p)]; + d +} + +/// The first flow ruby: its base text and reading. +fn ruby_of(f: &Flow) -> Option<(String, String)> { + f.blocks.iter().find_map(|b| match b { + FBlock::Para(p) => p.inlines.iter().find_map(|i| match i { + Inline::Ruby { base, ruby, .. } => Some((base.clone(), ruby.clone())), + _ => None, + }), + _ => None, + }) +} + +/// The first document ruby: its base text and reading. +fn doc_ruby(d: &Document) -> Option<(String, String)> { + d.body.iter().find_map(|b| match &**b { + craft_wordmodel::Block::Para(p) => p.objects.iter().find_map(|o| match o { + craft_wordmodel::InlineObject::Ruby { base, ruby, .. } => Some((base.clone(), ruby.clone())), + _ => None, + }), + _ => None, + }) +} + +/// The first document ruby: base size, ruby size, raise and alignment. +fn doc_ruby_attrs(d: &Document) -> Option<(f32, f32, f32, craft_wordmodel::para::RubyAlign)> { + d.body.iter().find_map(|b| match &**b { + craft_wordmodel::Block::Para(p) => p.objects.iter().find_map(|o| match o { + craft_wordmodel::InlineObject::Ruby { base_size, size, raise, align, .. } => Some((*base_size, *size, *raise, *align)), + _ => None, + }), + _ => None, + }) +} + +#[test] +fn ruby_exports_as_ruby_markup() { + // #1681: the base text with its reading in ``, not plain base text. + let out = export(&ruby_doc("漢字", "かんじ")); + assert!(out.contains("

I read 漢字かんじ daily.

"), "{out}"); + // The base and the reading are escaped like any other text. + let out = export(&ruby_doc("A&B", "xA&Bx<y"), "{out}"); +} + +#[test] +fn ruby_imports_with_its_surrounding_text() { + let f = parse("

I read 漢字かんじ daily.

"); + assert_eq!(ruby_of(&f), Some(("漢字".into(), "かんじ".into()))); + assert_eq!(texts(&f), vec!["NormalNone:I read 漢字 daily."]); + let FBlock::Para(p) = &f.blocks[0] else { panic!() }; + assert!(matches!(&p.inlines[0], Inline::Text(t, _) if t == "I read "), "{:?}", p.inlines); + assert!(matches!(p.inlines.last(), Some(Inline::Text(t, _)) if t == " daily."), "{:?}", p.inlines); + // One document object, holding the base text and the reading. + assert_eq!(doc_ruby(&craft_flow::to_doc(&f)), Some(("漢字".into(), "かんじ".into()))); +} + +#[test] +fn ruby_rb_and_rp_fallbacks_import_as_one_guide() { + // `` holds the base text and `` the fallback parentheses for browsers without + // ruby: the parentheses are not text, and the base pieces join. + let f = parse("

漢字(かんじ)

"); + assert_eq!(ruby_of(&f), Some(("漢字".into(), "かんじ".into()))); + assert_eq!(texts(&f), vec!["NormalNone:漢字"]); + assert_eq!(doc_ruby(&craft_flow::to_doc(&f)), Some(("漢字".into(), "かんじ".into()))); +} + +#[test] +fn ruby_import_uses_the_phonetic_guide_defaults() { + // HTML states no alignment, size or raise: the Phonetic Guide's own defaults over a + // 20 pt run (half the base size, raised clear of the base text, centred)… + let d = crate::doc::import("

漢字かんじ

"); + let Some((base_size, size, raise, align)) = doc_ruby_attrs(&d) else { panic!("no ruby") }; + assert_eq!((base_size, size, align.ooxml()), (20.0, 10.0, "center")); + assert!((raise - 18.0).abs() < 0.001, "{raise}"); + // …and the guide's 10.5 pt fallback base size when the source states none. + let d = crate::doc::import("

漢字かんじ

"); + let Some((base_size, size, raise, _)) = doc_ruby_attrs(&d) else { panic!("no ruby") }; + assert_eq!((base_size, size), (10.5, 5.0)); + assert!((raise - 9.4).abs() < 0.001, "{raise}"); +} + +#[test] +fn ruby_survives_an_html_round_trip() { + let html = export(&ruby_doc("漢字", "かんじ")); + assert_eq!(ruby_of(&parse(&html)), Some(("漢字".into(), "かんじ".into()))); + let back = crate::doc::import(&html); + assert_eq!(doc_ruby(&back), Some(("漢字".into(), "かんじ".into()))); + assert_eq!(back.plain_text(Default::default()), "I read 漢字 daily."); +} + +#[test] +fn ruby_keeps_the_run_formatting() { + let props = craft_wordmodel::CharProps { bold: Some(true), ..Default::default() }; + let mut p = craft_wordmodel::Paragraph::with_text("I read ", props.clone()); + let n = p.len(); + p.insert_object(n, craft_flow::ruby_object("漢字".into(), "かんじ".into(), 20.0), &props).unwrap(); + let mut d = Document::new(); + d.body = vec![craft_wordmodel::para_block(p)]; + assert!(export(&d).contains("漢字かんじ"), "{}", export(&d)); + // Importing it back keeps the formatting for the base text and the reading. + let f = parse("

漢字かんじ

"); + let FBlock::Para(p) = &f.blocks[0] else { panic!() }; + assert!(matches!(&p.inlines[0], Inline::Ruby { fmt, .. } if fmt.bold), "{:?}", p.inlines); +} + +#[test] +fn malformed_ruby_keeps_its_text() { + // No reading, an empty reading, a missing base, an unclosed element and a block boundary + // closing it: none of them panics, and the text inside is kept. + let cases: [(&str, &[&str]); 7] = [ + ("

a 漢字 b

", &["NormalNone:a 漢字 b"]), + ("

a 漢字 b

", &["NormalNone:a 漢字 b"]), + ("

a かんじ b

", &["NormalNone:a かんじ b"]), + ("

a b

", &["NormalNone:a b"]), + ("", &[]), + ("

a 漢字かんじ b

next

", &["NormalNone:a 漢字 b", "NormalNone:next"]), + ("

a 漢字かんじ

next

", &["NormalNone:a 漢字", "NormalNone:next"]), + ]; + for (src, want) in cases { + assert_eq!(texts(&parse(src)), want, "{src}"); + } + // Ruby in ruby: the inner element's text joins the outer guide's. + assert_eq!(ruby_of(&parse("

漢字字じかんじ

")), Some(("漢字字".into(), "じかんじ".into()))); +} + +#[test] +fn small_big_and_css_font_sizes() { + let f = parse( + "

small big huge tiny

", + ); + let FBlock::Para(p) = &f.blocks[0] else { panic!() }; + let sz = |i: usize| match &p.inlines[i] { + Inline::Text(_, f) => f.size, + _ => None, + }; + assert_eq!(sz(0), Some(10.0)); + assert_eq!(sz(2), Some(14.0)); + assert_eq!(sz(4), Some(36.0)); + assert_eq!(sz(6), Some(10.0)); +} + +#[test] +fn css_important_casing_and_spacing() { + let f = parse( + "

Styled

", + ); + assert_eq!(f.blocks.len(), 1); + let p = match &f.blocks[0] { + FBlock::Para(p) => p, + b => panic!("expected para, got {b:?}"), + }; + assert_eq!(p.align, Some(Align::Center)); + match &p.inlines[0] { + Inline::Text(_, fmt) => { + assert_eq!(fmt.color, Some(craft_wordmodel::props::Rgb(0xFF, 0x00, 0x00))); + assert_eq!(fmt.size, Some(16.0)); + assert!(fmt.bold); + } + i => panic!("expected text inline, got {i:?}"), + } +} + +#[test] +fn table_cell_vertical_alignment() { + let f = parse("
topmidbot
"); + let FBlock::Table(t) = &f.blocks[0] else { panic!() }; + assert_eq!(t.rows[0][0].valign, Some(VAlign::Top)); + assert_eq!(t.rows[0][1].valign, Some(VAlign::Center)); + assert_eq!(t.rows[0][2].valign, Some(VAlign::Bottom)); + let doc = craft_flow::to_doc(&f); + let craft_wordmodel::Block::Table(dt) = &*doc.body[0] else { panic!() }; + assert_eq!(dt.rows[0].cells[0].props.valign, Some(VAlign::Top)); + assert_eq!(dt.rows[0].cells[1].props.valign, Some(VAlign::Center)); + assert_eq!(dt.rows[0].cells[2].props.valign, Some(VAlign::Bottom)); + let html = export(&doc); + assert!(html.contains("vertical-align:top")); + assert!(html.contains("vertical-align:middle")); + assert!(html.contains("vertical-align:bottom")); +} + +#[test] +fn many_formatted_leading_breaks_trim_quickly() { + // #3705: a paragraph opening with alternating bold and italic `
` was trimmed one + // span at a time with `Vec::remove(0)`. + let html = format!("

{}x

", "

".repeat(100_000)); + let t = std::time::Instant::now(); + let f = parse(&html); + // About a second on a loaded machine; trimming one span at a time ran past 6 minutes. + assert!(t.elapsed() < std::time::Duration::from_secs(20), "{:?}", t.elapsed()); + let texts: Vec = f.blocks.iter().filter_map(|b| if let FBlock::Para(p) = b { Some(p.text()) } else { None }).collect(); + assert_eq!(texts, ["x"]); +} + +#[test] +fn font_size_at_the_integer_limits_does_not_overflow() { + // `` offsets were added to 3 unchecked, so the extreme values panicked in debug builds. + for size in ["+2147483647", "--2147483648", "-2147483647", "+99999999999"] { + let f = parse(&format!("x")); + assert!(texts(&f).iter().any(|t| t.ends_with(":x")), "size={size}"); + } + // The offsets saturate, then clamp to the 1..=7 scale: 7 is 36 pt, 1 is 7.5 pt. + let size = |html: &str| match &parse(html).blocks[0] { + FBlock::Para(p) => p.inlines.iter().find_map(|i| match i { + Inline::Text(_, fmt) => fmt.size, + _ => None, + }), + _ => None, + }; + assert_eq!(size("x"), Some(36.0)); + assert_eq!(size("x"), Some(36.0)); + assert_eq!(size("x"), Some(7.5)); +} + +#[test] +fn empty_comments_do_not_swallow_the_rest() { + for html in ["

ab

c

", "

ab

c

"] { + let doc = crate::doc::import(html); + assert_eq!(doc.plain_text(Default::default()), "ab\nc", "{html}"); + } +} + +fn paras(f: &Flow) -> Vec<&Para> { + f.blocks.iter().filter_map(|b| if let FBlock::Para(p) = b { Some(p) } else { None }).collect() +} +fn fmt_of(p: &Para) -> Fmt { + p.inlines.iter().find_map(|i| if let Inline::Text(_, f) = i { Some(f.clone()) } else { None }).unwrap_or_default() +} + +#[test] +fn style_sheet_rules_apply_in_cascade_order() { + let f = parse( + "\ +

plain

big

inline wins

digits

", + ); + let ps = paras(&f); + let (plain, big, inline, digits) = (fmt_of(ps[0]), fmt_of(ps[1]), fmt_of(ps[2]), fmt_of(ps[3])); + assert_eq!((plain.color, plain.size, plain.bold, plain.italic), (Some(craft_wordmodel::Rgb(0, 255, 0)), Some(10.0), false, false)); + assert_eq!((big.size, big.bold), (Some(20.0), true)); + assert_eq!(inline.size, Some(8.0)); + assert_eq!(ps[3].align, Some(Align::Center)); + assert_eq!(digits.size, Some(10.0)); +} + +#[test] +fn paragraph_css_states_spacing_indents_and_line_height() { + let f = parse( + "\ +

a

b

c

", + ); + let ps = paras(&f); + assert_eq!( + ps[0].spacing, + Spacing { + before: Some(6.0), + after: Some(3.0), + left: Some(72.0), + right: Some(72.0), + first: Some(-18.0), + line: Some(LineSpacing::Multiple(1.5)), + ..Spacing::default() + } + ); + // Values that don't parse (a comma decimal, `auto`) state nothing. + assert_eq!(ps[1].spacing, Spacing { line: Some(LineSpacing::Exactly(20.0)), ..Spacing::default() }); + assert_eq!(ps[2].spacing, Spacing::default()); +} + +#[test] +fn a_page_opens_as_word_opens_one() { + let html = "\ +

first

Head

kept

own

bare

 

"; + let f = parse_in(html, &|_| None, true); + let ps = paras(&f); + // Times New Roman 12 pt on single lines; headings bold and black at a browser's sizes. + let first = fmt_of(ps[0]); + assert_eq!((first.font.as_deref(), first.size), (Some(PAGE_FONT), Some(12.0))); + assert_eq!(ps[0].spacing.line, Some(LineSpacing::Multiple(1.0))); + let cell = parse_in("
cell
", &|_| None, true); + let FBlock::Table(t) = &cell.blocks[0] else { panic!() }; + let FBlock::Para(cp) = &t.rows[0][0].blocks[0] else { panic!() }; + assert_eq!(cp.spacing.line, Some(LineSpacing::Multiple(1.0))); + let head = fmt_of(ps[1]); + assert_eq!((head.bold, head.size, head.color), (true, Some(24.0), Some(craft_wordmodel::Rgb(0, 0, 0)))); + // A colour the heading inherits stays. + // A generic family names a face on a page; pasted text keeps the document's font. + let generic = parse_in("

a

b

", &|_| None, true); + let fonts: Vec> = paras(&generic).iter().map(|p| fmt_of(p).font.map(|f| f.to_string())).collect(); + assert_eq!(fonts, [Some("Arial".to_string()), Some(PAGE_FONT.to_string())]); + assert_eq!(fmt_of(paras(&parse("

a

"))[0]).font, None); + let inherited = parse_in("

Head

", &|_| None, true); + assert_eq!(fmt_of(paras(&inherited)[0]).color, Some(craft_wordmodel::Rgb(0, 0, 0x80))); + // Automatic spacing where a p or heading leaves its margins out (layout drops it at the + // top of the page and of a cell). + let auto = |p: &Para| (p.spacing.before_auto, p.spacing.after_auto, p.spacing.before, p.spacing.after); + assert_eq!(auto(ps[0]), (true, true, None, None)); + assert_eq!(auto(ps[1]), (true, true, None, None)); + // A span's margin replaces the one its paragraph states; the one it leaves out stays automatic. + assert_eq!(auto(ps[2]), (true, false, None, Some(0.0))); + assert_eq!(auto(ps[3]), (true, false, None, Some(9.75))); + // Other blocks get no automatic spacing. + assert_eq!(auto(ps[4]), (false, false, None, None)); + // The document says so, and the empty paragraph's mark keeps its size. + let d = model::to_doc(&f); + let props = |i: usize| match &*d.body[i] { + craft_wordmodel::Block::Para(p) => p.clone(), + b => panic!("{b:?}"), + }; + assert_eq!((props(0).props.space_before_auto, props(0).props.space_after_auto), (Some(true), Some(true))); + assert_eq!((props(2).props.space_after_auto, props(2).props.space_after), (None, Some(0.0))); + assert_eq!(props(5).mark.size, Some(12.0)); + // `

 

` keeps the size of its space for its line. + assert!(ps[5].inlines.is_empty()); + assert_eq!(ps[5].mark.as_ref().and_then(|m| m.size), Some(12.0)); + // A fragment (a paste) keeps the document's own formatting. + let pasted = parse(html); + assert_eq!(fmt_of(paras(&pasted)[0]).font, None); + assert_eq!(paras(&pasted)[0].spacing, Spacing::default()); +} + +#[test] +fn cells_give_their_columns_widths() { + let f = parse( + "
t
1ab
", + ); + let FBlock::Table(t) = &f.blocks[0] else { panic!("{:?}", f.blocks) }; + assert_eq!(t.widths, [31.5, 150.0, 144.0]); + // A column without a width leaves them all to the layout. + let f = parse("
ab
"); + let FBlock::Table(t) = &f.blocks[0] else { panic!() }; + assert!(t.widths.is_empty()); + // A cell beside a cell spanning rows from above gives its own column its width. + let f = + parse("
ab
c
de
"); + let FBlock::Table(t) = &f.blocks[0] else { panic!() }; + assert_eq!(t.widths, [75.0, 150.0]); +} + +#[test] +fn cells_take_their_css_borders() { + use craft_wordmodel::props::{Border, BorderStyle}; + let f = parse( + "
ab
", + ); + let FBlock::Table(t) = &f.blocks[0] else { panic!() }; + // The style sheet's other cell properties apply too. + assert_eq!(t.rows[0][0].valign, Some(craft_wordmodel::props::VAlign::Bottom)); + let b = t.rows[0][0].borders.expect("borders"); + assert_eq!(b.top, Some(Border::single(0.75))); + assert_eq!(b.bottom, Some(Border { style: BorderStyle::Double, width: 2.0, color: Some(craft_wordmodel::Rgb(255, 0, 0)), space: 0.0 })); + assert_eq!(b.left.map(|l| l.style), Some(BorderStyle::None)); + // A border of no width is none (OOXML has no zero-width line). + assert_eq!(b.right.map(|r| r.style), Some(BorderStyle::None)); + assert_eq!(t.rows[0][1].borders, None); +} + +#[test] +fn style_sheet_edge_cases() { + let f = parse_in( + "\ +

a

bare

b

", + &|_| None, + true, + ); + let ps = paras(&f); + // A rule right after statement at-rules still applies. + assert_eq!(fmt_of(ps[0]).color, Some(craft_wordmodel::Rgb(0, 0, 255))); + // The body's margins aren't the paragraphs' indents. + assert_eq!((ps[1].spacing.left, ps[1].spacing.before), (None, None)); + // Bare numbers, percentages and keywords state no margin: automatic spacing stays. + assert_eq!((ps[2].spacing.before_auto, ps[2].spacing.left), (true, None)); + // The `style` attribute wins even over a sheet with more declarations than are read. + let many = (0..600).map(|i| format!("x-{i}: 1")).collect::>().join(";"); + let f = parse(&format!("

c

")); + assert_eq!(fmt_of(paras(&f)[0]).color, Some(craft_wordmodel::Rgb(0, 255, 0))); +} + +#[test] +fn hostile_style_sheets_never_panic() { + // One declaration block shared by many selectors isn't copied for each. + let selectors = vec!["p"; 20_000].join(","); + let huge = format!("

x

", "x: y;".repeat(200_000)); + let _ = parse_in(&huge, &|_| None, true); + let many = ".a { color: red } ".repeat(20_000); + for css in ["{", "}", "p {", "@media { p { x } ", "p { color: red", "/* open", ".{}", "p..a{}", "\u{0}.é{x:y}", many.as_str()] { + let _ = parse_in(&format!("

x

y"), &|_| None, true); + } +} diff --git a/crates/html/src/entity.rs b/crates/html/src/entity.rs new file mode 100644 index 000000000..8ece41926 --- /dev/null +++ b/crates/html/src/entity.rs @@ -0,0 +1,388 @@ +//! Character references (`&`, `é`, `é`) and escaping. + +/// The Latin-1 names in code point order, from U+00A0 (`nbsp`) to U+00FF (`yuml`). +const LATIN1: [&str; 96] = [ + "nbsp", "iexcl", "cent", "pound", "curren", "yen", "brvbar", "sect", "uml", "copy", "ordf", "laquo", "not", "shy", "reg", "macr", "deg", + "plusmn", "sup2", "sup3", "acute", "micro", "para", "middot", "cedil", "sup1", "ordm", "raquo", "frac14", "frac12", "frac34", "iquest", "Agrave", + "Aacute", "Acirc", "Atilde", "Auml", "Aring", "AElig", "Ccedil", "Egrave", "Eacute", "Ecirc", "Euml", "Igrave", "Iacute", "Icirc", "Iuml", "ETH", + "Ntilde", "Ograve", "Oacute", "Ocirc", "Otilde", "Ouml", "times", "Oslash", "Ugrave", "Uacute", "Ucirc", "Uuml", "Yacute", "THORN", "szlig", + "agrave", "aacute", "acirc", "atilde", "auml", "aring", "aelig", "ccedil", "egrave", "eacute", "ecirc", "euml", "igrave", "iacute", "icirc", + "iuml", "eth", "ntilde", "ograve", "oacute", "ocirc", "otilde", "ouml", "divide", "oslash", "ugrave", "uacute", "ucirc", "uuml", "yacute", + "thorn", "yuml", +]; + +/// Greek capitals from U+0391; U+03A2 is unassigned. +const GREEK_UPPER: [&str; 25] = [ + "Alpha", "Beta", "Gamma", "Delta", "Epsilon", "Zeta", "Eta", "Theta", "Iota", "Kappa", "Lambda", "Mu", "Nu", "Xi", "Omicron", "Pi", "Rho", "", + "Sigma", "Tau", "Upsilon", "Phi", "Chi", "Psi", "Omega", +]; + +/// Greek small letters from U+03B1. +const GREEK_LOWER: [&str; 25] = [ + "alpha", "beta", "gamma", "delta", "epsilon", "zeta", "eta", "theta", "iota", "kappa", "lambda", "mu", "nu", "xi", "omicron", "pi", "rho", + "sigmaf", "sigma", "tau", "upsilon", "phi", "chi", "psi", "omega", +]; + +/// What a numeric reference to 0x80–0x9F means (HTML Living Standard §13.2.5.80: the +/// Windows-1252 characters, by long tradition). +const C1: [u32; 32] = [ + 0x20AC, 0x81, 0x201A, 0x0192, 0x201E, 0x2026, 0x2020, 0x2021, 0x02C6, 0x2030, 0x0160, 0x2039, 0x0152, 0x8D, 0x017D, 0x8F, 0x90, 0x2018, 0x2019, + 0x201C, 0x201D, 0x2022, 0x2013, 0x2014, 0x02DC, 0x2122, 0x0161, 0x203A, 0x0153, 0x9D, 0x017E, 0x0178, +]; + +/// Longest entity name looked at. +const MAX_NAME: usize = 32; + +/// The legacy names HTML also decodes without a `;`, sorted by bytes. +const BARE_NAMES: &[&str] = &[ + "AElig", "AMP", "Aacute", "Acirc", "Agrave", "Aring", "Atilde", "Auml", "COPY", "Ccedil", "Eacute", "Ecirc", "Egrave", "Euml", "GT", "Iacute", + "Icirc", "Igrave", "Iuml", "LT", "Ntilde", "Oacute", "Ocirc", "Ograve", "Oslash", "Otilde", "Ouml", "QUOT", "REG", "Uacute", "Ucirc", "Ugrave", + "Uuml", "Yacute", "aacute", "acirc", "aelig", "agrave", "amp", "aring", "atilde", "auml", "ccedil", "cent", "copy", "curren", "deg", "divide", + "eacute", "ecirc", "egrave", "euml", "frac12", "frac14", "frac34", "gt", "iacute", "icirc", "iexcl", "igrave", "iquest", "iuml", "laquo", "lt", + "micro", "middot", "nbsp", "ntilde", "oacute", "ocirc", "ograve", "oslash", "otilde", "ouml", "para", "plusmn", "pound", "quot", "raquo", "reg", + "sect", "shy", "sup1", "sup2", "sup3", "szlig", "times", "uacute", "ucirc", "ugrave", "uuml", "yacute", "yen", "yuml", +]; + +/// Text as HTML, for content and for attribute values in either kind of quote: `&`, `<`, `>`, +/// `"` and `'` become character references. +pub fn escape(text: &str) -> String { + let mut out = String::with_capacity(text.len().saturating_add(text.len() / 8)); + push_escaped(&mut out, text, true); + out +} + +/// [`escape`] that leaves `'` as it is: for content and for attribute values in double quotes. +pub fn escape_dq(text: &str) -> String { + let mut out = String::with_capacity(text.len().saturating_add(text.len() / 8)); + push_escaped(&mut out, text, false); + out +} + +fn push_escaped(out: &mut String, text: &str, apos: bool) { + for c in text.chars() { + match c { + '&' => out.push_str("&"), + '<' => out.push_str("<"), + '>' => out.push_str(">"), + '"' => out.push_str("""), + '\'' if apos => out.push_str("'"), + c => out.push(c), + } + } +} + +/// The character an entity body names (`amp`, `#38`, `#x26`: what stands between `&` and `;`). +pub fn decode_entity(body: &str) -> Option { + match body.strip_prefix('#') { + Some(_) => reference(body, false).filter(|(_, used)| *used == body.len()).map(|(c, _)| c), + None => named(body), + } +} + +/// Character references in text decoded: named (the HTML 4 set and more), decimal and hex. +/// Anything that is no reference stays as it is. A legacy name decodes without its `;` +/// (`© 2024`), as in browsers. +pub fn unescape(text: &str) -> String { + unescape_in(text, false) +} + +/// [`unescape`] for an attribute value: a legacy name without its `;` stays text when a letter, +/// a digit or `=` follows, so `?a=1©=2` is a query string and not a copyright sign. +pub fn unescape_attr(text: &str) -> String { + unescape_in(text, true) +} + +fn unescape_in(text: &str, attr: bool) -> String { + if !text.contains('&') { + return text.to_string(); + } + let mut out = String::with_capacity(text.len()); + let mut rest = text; + while let Some(i) = rest.find('&') { + out.push_str(rest.get(..i).unwrap_or("")); + let after = rest.get(i + 1..).unwrap_or(""); + match reference(after, attr) { + Some((c, used)) => { + out.push(c); + rest = after.get(used..).unwrap_or(""); + } + None => { + out.push('&'); + rest = after; + } + } + } + out.push_str(rest); + out +} + +/// The character a reference names and the bytes it takes, given the text after its `&` +/// (`attr`: inside an attribute value, see [`unescape_attr`]). At most [`MAX_NAME`] bytes are +/// looked at for a name, so a text of stray `&`s is read in linear time. +pub fn reference(s: &str, attr: bool) -> Option<(char, usize)> { + if let Some(num) = s.strip_prefix('#') { + let (digits, radix, skip) = match num.strip_prefix(['x', 'X']) { + Some(hex) => (hex, 16, 2), + None => (num, 10, 1), + }; + let len = digits.bytes().take_while(|b| char::from(*b).is_digit(radix)).count(); + if len == 0 { + return None; + } + // Too many digits is not a character; neither is 0, a surrogate, or anything past U+10FFFF. + let mut code: u32 = 0; + for d in digits.bytes().take(len) { + let d = char::from(d).to_digit(radix).unwrap_or(0); + code = code.checked_mul(radix).and_then(|c| c.checked_add(d)).unwrap_or(u32::MAX); + } + let semicolon = usize::from(digits.as_bytes().get(len) == Some(&b';')); + return Some((numeric(code), skip + len + semicolon)); + } + let len = s.bytes().take(MAX_NAME).take_while(u8::is_ascii_alphanumeric).count(); + if s.as_bytes().get(len) == Some(&b';') + && let Some(c) = s.get(..len).and_then(named) + { + return Some((c, len + 1)); + } + // Without its `;`: the longest legacy name (2 to 6 letters) the text starts with. + let len = (2..=len.min(6)).rev().find(|&l| s.get(..l).is_some_and(|p| BARE_NAMES.binary_search(&p).is_ok()))?; + if attr && s.as_bytes().get(len).is_some_and(|b| b.is_ascii_alphanumeric() || *b == b'=') { + return None; + } + s.get(..len).and_then(named).map(|c| (c, len)) +} + +fn numeric(code: u32) -> char { + let code = match code { + 0x80..=0x9F => C1.get((code - 0x80) as usize).copied().unwrap_or(code), + c => c, + }; + match char::from_u32(code) { + Some('\0') | None => char::REPLACEMENT_CHARACTER, + Some(c) => c, + } +} + +fn named(name: &str) -> Option { + if name.is_empty() { + return None; + } + let c = match name { + "amp" | "AMP" => '&', + "lt" | "LT" => '<', + "gt" | "GT" => '>', + "quot" | "QUOT" => '"', + "apos" | "APOS" => '\'', + "nbsp" | "NBSP" => '\u{00A0}', + "ensp" => '\u{2002}', + "emsp" => '\u{2003}', + "thinsp" => '\u{2009}', + "shy" => '\u{00AD}', + "copy" | "COPY" => '©', + "reg" | "REG" => '®', + "trade" | "TRADE" => '™', + "hellip" => '…', + "mdash" => '—', + "ndash" => '–', + "minus" => '−', + "lsquo" => '‘', + "rsquo" => '’', + "sbquo" => '‚', + "ldquo" => '“', + "rdquo" => '”', + "bdquo" => '„', + "laquo" => '«', + "raquo" => '»', + "bull" => '•', + "middot" => '·', + "deg" => '°', + "plusmn" => '±', + "times" => '×', + "divide" => '÷', + "frac12" => '½', + "frac14" => '¼', + "frac34" => '¾', + "frac13" => '⅓', + "frac23" => '⅔', + "frac18" => '⅛', + "frac38" => '⅜', + "frac58" => '⅝', + "frac78" => '⅞', + "sup1" => '¹', + "sup2" => '²', + "sup3" => '³', + "micro" => 'µ', + "permil" => '‰', + "prime" => '′', + "Prime" => '″', + "oline" => '‾', + "frasl" => '⁄', + "sect" => '§', + "para" => '¶', + "euro" | "EURO" => '€', + "pound" | "POUND" => '£', + "yen" | "YEN" => '¥', + "cent" | "CENT" => '¢', + "curren" => '¤', + "dagger" => '†', + "Dagger" => '‡', + "larr" => '←', + "rarr" => '→', + "uarr" => '↑', + "darr" => '↓', + "harr" => '↔', + "lArr" => '⇐', + "rArr" => '⇒', + "uArr" => '⇑', + "dArr" => '⇓', + "hArr" => '⇔', + "crarr" => '↵', + "forall" => '∀', + "part" => '∂', + "exist" => '∃', + "empty" => '∅', + "nabla" => '∇', + "isin" => '∈', + "notin" => '∉', + "ni" => '∋', + "prod" => '∏', + "sum" => '∑', + "radic" => '√', + "prop" => '∝', + "ang" => '∠', + "and" => '∧', + "or" => '∨', + "cap" => '∩', + "cup" => '∪', + "int" => '∫', + "there4" => '∴', + "sim" => '∼', + "cong" => '≅', + "asymp" | "approx" => '≈', + "ne" => '≠', + "equiv" => '≡', + "le" => '≤', + "ge" => '≥', + "sub" => '⊂', + "sup" => '⊃', + "nsub" => '⊄', + "sube" => '⊆', + "supe" => '⊇', + "oplus" => '⊕', + "otimes" => '⊗', + "perp" => '⊥', + "sdot" => '⋅', + "infin" => '∞', + "loz" => '◊', + "spades" => '♠', + "clubs" => '♣', + "hearts" => '♥', + "diams" => '♦', + "check" => '✓', + "iexcl" => '¡', + "iquest" => '¿', + "szlig" => 'ß', + "auml" => 'ä', + "ouml" => 'ö', + "uuml" => 'ü', + "Auml" => 'Ä', + "Ouml" => 'Ö', + "Uuml" => 'Ü', + "eacute" => 'é', + "egrave" => 'è', + "ecirc" => 'ê', + "euml" => 'ë', + "Eacute" => 'É', + "Egrave" => 'È', + "Ecirc" => 'Ê', + "Euml" => 'Ë', + "aacute" => 'á', + "agrave" => 'à', + "acirc" => 'â', + "atilde" => 'ã', + "Agrave" => 'À', + "Aacute" => 'Á', + "Acirc" => 'Â', + "Atilde" => 'Ã', + "iacute" => 'í', + "igrave" => 'ì', + "icirc" => 'î', + "iuml" => 'ï', + "Iacute" => 'Í', + "Igrave" => 'Ì', + "Icirc" => 'Î', + "Iuml" => 'Ï', + "oacute" => 'ó', + "ograve" => 'ò', + "ocirc" => 'ô', + "otilde" => 'õ', + "Oacute" => 'Ó', + "Ograve" => 'Ò', + "Ocirc" => 'Ô', + "Otilde" => 'Õ', + "uacute" => 'ú', + "ugrave" => 'ù', + "ucirc" => 'û', + "Uacute" => 'Ú', + "Ugrave" => 'Ù', + "Ucirc" => 'Û', + "yacute" => 'ý', + "yuml" => 'ÿ', + "Yacute" => 'Ý', + "ntilde" => 'ñ', + "Ntilde" => 'Ñ', + "ccedil" => 'ç', + "Ccedil" => 'Ç', + "aring" => 'å', + "Aring" => 'Å', + "oslash" => 'ø', + "Oslash" => 'Ø', + "aelig" => 'æ', + "AElig" => 'Æ', + "alpha" => 'α', + "beta" => 'β', + "gamma" => 'γ', + "delta" => 'δ', + "epsilon" => 'ε', + "zeta" => 'ζ', + "eta" => 'η', + "theta" => 'θ', + "iota" => 'ι', + "kappa" => 'κ', + "lambda" => 'λ', + "mu" => 'μ', + "nu" => 'ν', + "xi" => 'ξ', + "pi" => 'π', + "rho" => 'ρ', + "sigma" => 'σ', + "tau" => 'τ', + "upsilon" => 'υ', + "phi" => 'φ', + "chi" => 'χ', + "psi" => 'ψ', + "omega" => 'ω', + "Gamma" => 'Γ', + "Delta" => 'Δ', + "Theta" => 'Θ', + "Lambda" => 'Λ', + "Xi" => 'Ξ', + "Pi" => 'Π', + "Sigma" => 'Σ', + "Upsilon" => 'Υ', + "Phi" => 'Φ', + "Psi" => 'Ψ', + "Omega" => 'Ω', + "zwj" => '\u{200D}', + "zwnj" => '\u{200C}', + "cross" => '\u{2717}', + _ => { + let at = |table: &[&str], base: u32| table.iter().position(|n| *n == name).and_then(|i| char::from_u32(base + i as u32)); + return at(&LATIN1, 0xA0).or_else(|| at(&GREEK_UPPER, 0x391)).or_else(|| at(&GREEK_LOWER, 0x3B1)); + } + }; + Some(c) +} + +#[cfg(test)] +mod tests; diff --git a/crates/html/src/entity/tests.rs b/crates/html/src/entity/tests.rs new file mode 100644 index 000000000..3abd35fdc --- /dev/null +++ b/crates/html/src/entity/tests.rs @@ -0,0 +1,132 @@ +use super::{BARE_NAMES, GREEK_LOWER, GREEK_UPPER, LATIN1, decode_entity, escape, escape_dq, named, reference, unescape, unescape_attr}; + +#[test] +fn escapes_the_five() { + assert_eq!(escape(r#"Tom & 'Jerry'"#), "<a href="x">Tom & 'Jerry'</a>"); + assert_eq!(escape_dq(r#"Tom & 'Jerry'"#), "<a href="x">Tom & 'Jerry'</a>"); + assert_eq!(escape("plain ünïcode"), "plain ünïcode"); + assert_eq!(escape(""), ""); +} + +#[test] +fn bare_names_are_sorted_and_known() { + assert_eq!(BARE_NAMES.len(), 94); + assert!(BARE_NAMES.windows(2).all(|w| w[0] < w[1])); + assert!(BARE_NAMES.iter().all(|n| (2..=6).contains(&n.len()) && named(n).is_some())); +} + +#[test] +fn every_latin_1_and_greek_name_is_its_code_point() { + for (table, base) in [(&LATIN1[..], 0xA0), (&GREEK_UPPER[..], 0x391), (&GREEK_LOWER[..], 0x3B1)] { + for (i, name) in table.iter().enumerate().filter(|(_, n)| !n.is_empty()) { + assert_eq!(named(name), char::from_u32(base + i as u32), "{name}"); + } + } +} + +#[test] +fn named_references() { + assert_eq!(unescape("<b> & "x" 'y'"), " & \"x\" 'y'"); + assert_eq!(unescape("a b"), "a\u{a0}b"); + assert_eq!(unescape("© ® ™ … — –"), "© ® ™ … — –"); + assert_eq!(unescape("‘a’ “b” €5"), "‘a’ “b” €5"); + assert_eq!(unescape("café naïve Über ß ÿ"), "café naïve Über ß ÿ"); + assert_eq!(unescape("αβΩς → ≤ ≠"), "αβΩς → ≤ ≠"); + assert_eq!(unescape("‌¦ÐþΑο✗✓♦"), "\u{200c}¦Ðþ\u{391}ο✗✓♦"); + assert_eq!(unescape("⅓∴⇔◊"), "⅓∴⇔◊"); +} + +#[test] +fn names_are_case_sensitive() { + assert_eq!(unescape("Éé"), "Éé"); + assert_eq!(unescape("&EACUTE;"), "&EACUTE;"); + assert_eq!(unescape("&<"), "&<"); +} + +#[test] +fn numeric_references() { + assert_eq!(unescape("ééé"), "ééé"); + assert_eq!(unescape("😀"), "😀"); + assert_eq!(unescape("😀"), "😀"); + // Without the semicolon. + assert_eq!(unescape("A B."), "A B."); + // Windows-1252 for the C1 range. + assert_eq!(unescape("“hi” € ™"), "“hi” € ™"); +} + +#[test] +fn bad_numbers_become_the_replacement_character() { + assert_eq!(unescape("�"), "\u{fffd}"); + assert_eq!(unescape("�"), "\u{fffd}"); + assert_eq!(unescape("�"), "\u{fffd}"); + assert_eq!(unescape("�"), "\u{fffd}"); + assert_eq!(unescape("�"), "\u{fffd}"); +} + +#[test] +fn invalid_references_are_left_alone() { + for s in ["&", "&&", "& ", "&;", "&#;", "&#x;", "&#xZZ;", "&bogus;", "AT&T", "a & b", "x&y=z", "&#", "&#x", "&eacut", "ünï&", "&Alpha", "&hellip"] + { + assert_eq!(unescape(s), s, "{s}"); + assert_eq!(unescape_attr(s), s, "{s}"); + } +} + +#[test] +fn legacy_names_work_without_a_semicolon() { + assert_eq!(unescape("a < b > c"), "a < b > c"); + assert_eq!(unescape("x "), "x\u{a0}"); + assert_eq!(unescape("&"), "&"); + assert_eq!(unescape("© 2024 café!"), "© 2024 café!"); + // The longest name wins: `∉` is one reference; `¥x;` is `¥` and `x;`. + assert_eq!(unescape("∉ ¥x;"), "∉ ¥x;"); + // In text even inside a word, as browsers read it. + assert_eq!(unescape("&lify ?a=1&=2"), "&lify ?a=1&=2"); +} + +#[test] +fn in_an_attribute_a_bare_name_before_a_letter_digit_or_equals_is_text() { + assert_eq!(unescape_attr("?a=1&=2<=3©=4®1"), "?a=1&=2<=3©=4®1"); + assert_eq!(unescape_attr("&lify"), "&lify"); + assert_eq!(unescape_attr("?a=1&b=2"), "?a=1&b=2"); + assert_eq!(unescape_attr("a < b©"), "a < b©"); + // Numeric references need no `;` anywhere. + assert_eq!(unescape_attr("A=1"), "A=1"); +} + +#[test] +fn an_entity_body_decodes_whole_or_not_at_all() { + assert_eq!(decode_entity("amp"), Some('&')); + assert_eq!(decode_entity("#38"), Some('&')); + assert_eq!(decode_entity("#x26"), Some('&')); + assert_eq!(decode_entity("#150"), Some('–')); + for none in ["", "#", "#x", "#38x", "#3 8", "bogus", "amp;"] { + assert_eq!(decode_entity(none), None, "{none}"); + } + assert_eq!(reference("amp;rest", false), Some(('&', 4))); + assert_eq!(reference("#x41;", true), Some(('A', 5))); +} + +#[test] +fn a_long_run_of_ampersands_is_quick() { + let s = "&".repeat(200_000); + assert_eq!(unescape(&s), s); + let s = "&#".repeat(100_000); + assert_eq!(unescape(&s), s); + let s = "&aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa".repeat(20_000); + assert_eq!(unescape(&s), s); +} + +proptest::proptest! { + #[test] + fn unescape_undoes_escape(s in proptest::prelude::any::()) { + proptest::prop_assert_eq!(unescape(&escape(&s)), s.clone()); + proptest::prop_assert_eq!(unescape_attr(&escape_dq(&s)), s); + } + + #[test] + fn unescape_never_panics(s in "[&#xX0-9a-zA-Z;= é]{0,60}") { + let _ = unescape(&s); + let _ = unescape_attr(&s); + } +} diff --git a/crates/html/src/lex.rs b/crates/html/src/lex.rs new file mode 100644 index 000000000..ef6b20636 --- /dev/null +++ b/crates/html/src/lex.rs @@ -0,0 +1,359 @@ +//! A tolerant HTML tokenizer: text, start tags and end tags. +//! +//! It follows the general syntax of the HTML Living Standard closely enough for documents, mail +//! and clipboard fragments, and reads anything: a `<` that starts no tag is text, a tag or +//! comment that never ends runs to the end of the input. Comments, doctypes and processing +//! instructions never leave it. + +use crate::entity::unescape_attr; + +/// What a [`Lexer`] caps. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct Limits { + /// Most attributes kept per tag; the rest are read and dropped. Default 64. + pub max_attrs: usize, + /// Longest tag name kept, in bytes; a longer one is no real element and its name is empty. + /// Default 64. + pub max_tag_name: usize, +} + +impl Limits { + pub const DEFAULT: Limits = Limits { max_attrs: 64, max_tag_name: 64 }; +} + +impl Default for Limits { + fn default() -> Limits { + Limits::DEFAULT + } +} + +/// How a [`Lexer`] reads. Element names are lower case. +#[derive(Clone, Copy, Debug, Default)] +pub struct Options<'o> { + pub limits: Limits, + /// Elements that never leave the lexer: the start tag, the content (raw text, not markup) + /// and the end tag are skipped. For `script`, `style`, `title` and the like, when the caller + /// has no use for them. A caller that wants a `style`'s text leaves it out of this list and + /// calls [`Lexer::raw_content`] on its start tag. + pub drop: &'o [&'o str], + /// Elements whose content is text, not markup, and is given: after the start tag comes one + /// [`Token::Text`] with everything up to the end tag. For `textarea`, `xmp`, `plaintext`. + pub raw_text: &'o [&'o str], +} + +/// A start tag. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Tag<'a> { + /// Lower case; empty for a name longer than [`Limits::max_tag_name`]. + pub name: String, + /// Names and values as written, in the order written. + pub attrs: Vec<(&'a str, &'a str)>, + /// The tag ends in `/>`. + pub self_close: bool, +} + +impl Tag<'_> { + /// An attribute's value with character references decoded ([`unescape_attr`]); the first + /// of a name wins, as in browsers. Names match in any letter case. + pub fn attr(&self, name: &str) -> Option { + self.raw_attr(name).map(unescape_attr) + } + + /// An attribute's value as written, character references and all. + pub fn raw_attr(&self, name: &str) -> Option<&str> { + self.attrs.iter().find(|(n, _)| n.eq_ignore_ascii_case(name)).map(|(_, v)| *v) + } + + /// Whether the tag has the attribute, with or without a value. + pub fn has(&self, name: &str) -> bool { + self.attrs.iter().any(|(n, _)| n.eq_ignore_ascii_case(name)) + } + + /// Every attribute in the order written: the name as written, the value decoded. + pub fn attributes(&self) -> impl Iterator + '_ { + self.attrs.iter().map(|(n, v)| (*n, unescape_attr(v))) + } +} + +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum Token<'a> { + /// Character data as written: references are not decoded ([`crate::unescape`]). + Text(&'a str), + Start(Tag<'a>), + /// An end tag's name, lower case (empty when longer than [`Limits::max_tag_name`]). + End(String), +} + +/// The tokenizer: an iterator of [`Token`]s over a string. +pub struct Lexer<'a, 'o> { + src: &'a str, + pos: usize, + opts: Options<'o>, + /// Set after the start tag of a raw-text element: its content comes next. + raw: Option, +} + +impl<'a> Lexer<'a, 'static> { + /// A lexer with [`Options::default`]: nothing dropped, no raw-text elements. + pub fn new(src: &'a str) -> Lexer<'a, 'static> { + Lexer::with(src, Options::default()) + } +} + +impl<'a, 'o> Lexer<'a, 'o> { + pub fn with(src: &'a str, opts: Options<'o>) -> Lexer<'a, 'o> { + Lexer { src, pos: 0, opts, raw: None } + } + + /// How far into the input the tokens given so far go, in bytes. + pub fn pos(&self) -> usize { + self.pos + } + + /// Goes back (or forward) to `pos`, a byte offset an earlier [`Lexer::pos`] gave, to read + /// from there again: for a reader that looked at a token and hands it back. An offset past the + /// end, or inside a character, moves to the next character boundary. + pub fn set_pos(&mut self, pos: usize) { + let mut pos = pos.min(self.src.len()); + while !self.src.is_char_boundary(pos) { + pos += 1; + } + self.pos = pos; + self.raw = None; + } + + /// The raw content of element `name`, whose start tag was the last token: everything up to + /// its end tag (any letter case), or to the end of the input when it has none. The end tag + /// is consumed. For `style` and `script`, whose content is not markup. + pub fn raw_content(&mut self, name: &str) -> &'a str { + self.raw = None; + let b = self.bytes(); + let end = find_end_tag(b, self.pos, name).unwrap_or(b.len()); + let text = self.slice(self.pos, end); + self.pos = find_byte(b, end, b'>').map_or(b.len(), |i| i + 1); + text + } + + fn bytes(&self) -> &'a [u8] { + self.src.as_bytes() + } + + fn slice(&self, start: usize, end: usize) -> &'a str { + self.src.get(start..end).unwrap_or("") + } + + /// A tag name in lower case; empty when it is too long to be a real element. + fn tag_name(&self, raw: &str) -> String { + if raw.len() > self.opts.limits.max_tag_name { String::new() } else { raw.to_ascii_lowercase() } + } + + /// Whether the `<` at `i` starts a tag, a comment or a declaration (rather than being text). + fn markup_at(&self, i: usize) -> bool { + let b = self.bytes(); + match b.get(i + 1) { + Some(c) if c.is_ascii_alphabetic() => true, + Some(b'!' | b'?') => true, + Some(b'/') => matches!(b.get(i + 2), Some(c) if c.is_ascii_alphabetic() || *c == b'>'), + _ => false, + } + } + + /// The end of the text run that starts at `self.pos`: the next `<` that starts markup. + fn text_end(&self) -> usize { + let b = self.bytes(); + let mut i = self.pos + 1; + loop { + match find_byte(b, i, b'<') { + Some(j) if self.markup_at(j) => return j, + Some(j) => i = j + 1, + None => return b.len(), + } + } + } + + /// Skip a comment, doctype or processing instruction at `self.pos`. + fn skip_declaration(&mut self) { + let b = self.bytes(); + let end = if b.get(self.pos..self.pos + 4) == Some(b"").map_or(b.len(), |i| i + 3) + } + } else { + find_byte(b, self.pos, b'>').map_or(b.len(), |i| i + 1) + }; + self.pos = end.min(b.len()); + } + + /// Read the end tag at `self.pos` (``). + fn close_tag(&mut self) -> Option> { + let b = self.bytes(); + let start = self.pos + 2; + let mut i = start; + while let Some(c) = b.get(i) { + if c.is_ascii_whitespace() || *c == b'/' || *c == b'>' { + break; + } + i += 1; + } + let name = self.slice(start, i); + self.pos = find_byte(b, i, b'>').map_or(b.len(), |j| j + 1); + // `` is nothing at all. + (!name.is_empty()).then(|| Token::End(self.tag_name(name))) + } + + /// Read the start tag at `self.pos` (``). + fn open_tag(&mut self) -> Tag<'a> { + let b = self.bytes(); + let start = self.pos + 1; + let mut i = start; + while let Some(c) = b.get(i) { + if c.is_ascii_whitespace() || *c == b'/' || *c == b'>' { + break; + } + i += 1; + } + let name = self.tag_name(self.slice(start, i)); + let mut attrs = Vec::new(); + let mut self_close = false; + loop { + while matches!(b.get(i), Some(c) if c.is_ascii_whitespace() || *c == b'/') { + self_close = b.get(i) == Some(&b'/') && b.get(i + 1) == Some(&b'>'); + i += 1; + } + match b.get(i) { + None => break, + Some(b'>') => { + i += 1; + break; + } + Some(_) => {} + } + // An attribute name runs to white space, `/`, `>` or `=`; a leading `=` is part of it. + let name_start = i; + i += 1; + while let Some(c) = b.get(i) { + if c.is_ascii_whitespace() || matches!(*c, b'/' | b'>' | b'=') { + break; + } + i += 1; + } + let attr = self.slice(name_start, i); + let (value, next) = self.attr_value(i); + i = next; + if attrs.len() < self.opts.limits.max_attrs { + attrs.push((attr, value)); + } + } + self.pos = i.min(b.len()); + Tag { name, attrs, self_close } + } + + /// The value after an attribute name that ends at `i` (empty when it has none), and where + /// reading goes on. + fn attr_value(&self, i: usize) -> (&'a str, usize) { + let b = self.bytes(); + let mut j = i; + while matches!(b.get(j), Some(c) if c.is_ascii_whitespace()) { + j += 1; + } + if b.get(j) != Some(&b'=') { + return ("", j); + } + j += 1; + while matches!(b.get(j), Some(c) if c.is_ascii_whitespace()) { + j += 1; + } + match b.get(j) { + Some(&q) if q == b'"' || q == b'\'' => { + let end = find_byte(b, j + 1, q).unwrap_or(b.len()); + (self.slice(j + 1, end), (end + 1).min(b.len())) + } + _ => { + let mut end = j; + while let Some(c) = b.get(end) { + if c.is_ascii_whitespace() || *c == b'>' { + break; + } + end += 1; + } + (self.slice(j, end), end) + } + } + } +} + +impl<'a> Iterator for Lexer<'a, '_> { + type Item = Token<'a>; + + fn next(&mut self) -> Option> { + loop { + let b = self.bytes(); + if self.pos >= b.len() { + return None; + } + if let Some(name) = self.raw.take() { + let end = find_end_tag(b, self.pos, &name).unwrap_or(b.len()); + let text = self.slice(self.pos, end); + self.pos = end; + if !text.is_empty() { + return Some(Token::Text(text)); + } + continue; + } + if b.get(self.pos) != Some(&b'<') || !self.markup_at(self.pos) { + let start = self.pos; + self.pos = self.text_end(); + return Some(Token::Text(self.slice(start, self.pos))); + } + match b.get(self.pos + 1) { + Some(b'!' | b'?') => self.skip_declaration(), + Some(b'/') => { + if let Some(token) = self.close_tag() { + return Some(token); + } + } + _ => { + let tag = self.open_tag(); + if self.opts.drop.contains(&tag.name.as_str()) { + self.raw_content(&tag.name); + continue; + } + if self.opts.raw_text.contains(&tag.name.as_str()) { + self.raw = Some(tag.name.clone()); + } + return Some(Token::Start(tag)); + } + } + } + } +} + +fn find_byte(b: &[u8], from: usize, byte: u8) -> Option { + b.get(from..)?.iter().position(|c| *c == byte).map(|i| i + from) +} + +fn find_sub(b: &[u8], from: usize, needle: &[u8]) -> Option { + b.get(from..)?.windows(needle.len()).position(|w| w == needle).map(|i| i + from) +} + +/// Where `` or the end), at or after `from`. +fn find_end_tag(b: &[u8], from: usize, name: &str) -> Option { + let mut i = from; + while let Some(lt) = find_byte(b, i, b'<') { + let after = lt + 2 + name.len(); + let named = b.get(lt + 1) == Some(&b'/') && b.get(lt + 2..after).is_some_and(|n| n.eq_ignore_ascii_case(name.as_bytes())); + if named && b.get(after).is_none_or(|c| c.is_ascii_whitespace() || matches!(*c, b'/' | b'>')) { + return Some(lt); + } + i = lt + 1; + } + None +} + +#[cfg(test)] +mod tests; diff --git a/crates/html/src/lex/tests.rs b/crates/html/src/lex/tests.rs new file mode 100644 index 000000000..084caf702 --- /dev/null +++ b/crates/html/src/lex/tests.rs @@ -0,0 +1,192 @@ +use super::{Lexer, Limits, Options, Token}; + +/// As a mail reader sets it up. +const MAIL: Options<'static> = + Options { limits: Limits { max_attrs: 32, max_tag_name: 24 }, drop: &["script", "style", "title", "iframe"], raw_text: &["textarea", "xmp"] }; + +fn show<'a>(lexer: impl Iterator>) -> Vec { + lexer + .map(|t| match t { + Token::Text(t) => format!("T:{t}"), + Token::Start(tag) => { + let attrs: Vec = tag.attrs.iter().map(|(n, v)| format!("{n}={v}")).collect(); + if attrs.is_empty() { format!("<{}>", tag.name) } else { format!("<{} {}>", tag.name, attrs.join(" ")) } + } + Token::End(n) => format!(""), + }) + .collect() +} + +fn tokens(html: &str) -> Vec { + show(Lexer::with(html, MAIL)) +} + +#[test] +fn text_and_tags() { + assert_eq!(tokens("Hi there!"), ["T:Hi ", "", "T:there", "", "T:!"]); + assert_eq!(tokens(""), Vec::::new()); + assert_eq!(tokens("plain"), ["T:plain"]); + assert_eq!(tokens("

"), ["
", "
"]); +} + +#[test] +fn attributes_in_every_quoting_style() { + assert_eq!(tokens(r#""#), [r#""#]); + assert_eq!(tokens("t"), ["", "T:t"]); + assert_eq!(tokens(""), [""]); + assert_eq!(tokens("

"), ["

"]); + // A `>` inside a quoted value does not end the tag. + assert_eq!(tokens(r#"t"#), ["b>", "T:t", ""]); +} + +#[test] +fn attribute_values_are_decoded_on_demand() { + let mut t = Lexer::new(r#""#); + let Some(Token::Start(tag)) = t.next() else { panic!("no tag") }; + assert_eq!(tag.attr("href").as_deref(), Some("?a=1&b=2©=3")); + assert_eq!(tag.raw_attr("href"), Some("?a=1&b=2©=3")); + assert_eq!(tag.attr("missing"), None); + assert!(tag.has("checked") && !tag.has("check")); + assert_eq!(tag.attributes().map(|(n, _)| n).collect::>(), ["HREF", "href", "Checked"]); +} + +#[test] +fn a_tag_that_closes_itself_says_so() { + let closes = |html: &str| match Lexer::new(html).next() { + Some(Token::Start(tag)) => tag.self_close, + other => panic!("{other:?}"), + }; + for yes in ["
", "
", "", "", ""] { + assert!(closes(yes), "{yes}"); + } + // A `/` that ends an unquoted value, or stands anywhere but before the `>`, is not it. + for no in ["
", "", "
", "", "
d"), ["T:a < b and c > d"]); + assert_eq!(tokens("1<2<3"), ["T:1<2<3"]); + assert_eq!(tokens("<"), ["T:<"]); + assert_eq!(tokens("x<"), ["T:x<"]); + assert_eq!(tokens("<3 <- b"), ["T:a", "T:b"]); +} + +#[test] +fn comments_and_declarations_vanish() { + assert_eq!(tokens("ab"), ["T:a", "T:b"]); + assert_eq!(tokens("

x"), ["

", "T:x"]); + assert_eq!(tokens("x"), ["T:x"]); + assert_eq!(tokens("abc"), ["T:a", "T:b", "T:c"]); + assert_eq!(tokens("shown"), ["T:shown"]); + assert_eq!(tokens("shown"), ["T:shown"]); + // An unfinished comment swallows the rest. + assert_eq!(tokens("a") { + break; + } + } + continue; + } + if t.starts_with('>') { + flush_para(&mut para, &mut out, depth, refs); + parse_quote(lines, &mut i, depth, level, refs, budget, &mut out); + continue; + } + if para.is_empty() + && t.contains('|') + && let Some((aligns, width)) = lines.get(i + 1).and_then(|l| delimiter_row(l, MAX_COLS)) + { + let (head, head_width) = split_row(t, MAX_COLS); + if head_width == width { + let mut table = FTable::default(); + let cell = |s: &str, header: bool, a: Option| { + let p = Para { align: a, inlines: parse_inlines(s, &Fmt::default(), depth, refs), ..Default::default() }; + Cell { blocks: vec![FBlock::Para(p)], header, ..Default::default() } + }; + // The document keeps no more columns or rows than this, nor cells past its budget, + // so those aren't built; their lines are still the table's. + let cols = aligns.len(); + let fits = |rows: usize| rows < MAX_ROWS && budget.get() >= cols; + let mut cut = head_width > cols; + if fits(0) { + budget.set(budget.get() - cols); + table.rows.push(head.iter().zip(&aligns).map(|(s, a)| cell(s, true, *a)).collect()); + } else { + cut = true; + } + i += 2; + while let Some(l) = lines.get(i) { + if is_blank(l) || !l.contains('|') || interrupts(l) { + break; + } + if !table.rows.is_empty() && fits(table.rows.len()) { + budget.set(budget.get() - cols); + let (mut cells, _) = split_row(l, cols); + cells.resize(cols, String::new()); + table.rows.push(cells.iter().zip(&aligns).map(|(s, a)| cell(s, false, *a)).collect()); + } else { + cut = true; + } + i += 1; + } + if cut { + model::dropped(model::Dropped::TableCells); + } + if !table.rows.is_empty() { + out.push(FBlock::Table(table)); + } + continue; + } + } + if let Some(m) = list_marker(t) + && (para.is_empty() || ((!m.ordered || m.start == 1) && !is_blank(t.get(m.len..).unwrap_or("")))) + { + flush_para(&mut para, &mut out, depth, refs); + i = parse_list(lines, i, depth, level, &mut out, refs, budget); + continue; + } + para.push(line.clone()); + i += 1; + } + flush_para(&mut para, &mut out, depth, refs); + out +} + +fn parse_indented_code(lines: &[String], i: &mut usize, out: &mut Vec) { + let mut code: Vec<&str> = Vec::new(); + while let Some(line) = lines.get(*i) { + if is_blank(line) { + code.push(""); + } else if indent(line) >= 4 { + code.push(strip_indent(line, 4)); + } else { + break; + } + *i += 1; + } + while code.last().is_some_and(|line| line.is_empty()) { + code.pop(); + } + out.extend(code.into_iter().map(code_para)); +} + +fn parse_quote(lines: &[String], i: &mut usize, depth: usize, level: u8, refs: &Refs, budget: &std::cell::Cell, out: &mut Vec) { + let mut inner = Vec::new(); + while let Some(line) = lines.get(*i) { + let trimmed = line.trim_start_matches([' ', '\t']); + if indent(line) < 4 && trimmed.starts_with('>') { + let content = &trimmed[1..]; + inner.push(content.strip_prefix(' ').unwrap_or(content).to_string()); + } else if !is_blank(line) && !interrupts(line) && inner.last().is_some_and(|line| !is_blank(line)) { + inner.push(line.clone()); + } else { + break; + } + *i += 1; + } + if depth >= MAX_NEST { + let mut p = Para::new(Kind::Quote); + p.push_text(&inner.join(" "), &Fmt::default()); + out.push(FBlock::Para(p)); + return; + } + for mut block in parse_blocks(&inner, depth + 1, level, refs, budget) { + if let FBlock::Para(p) = &mut block + && p.kind == Kind::Normal + { + p.kind = Kind::Quote; + } + out.push(block); + } +} + +fn marker_space(ind: usize, marker_len: usize, after: &str) -> (usize, usize) { + let mut cols = 0; + let mut bytes = 0; + let mut rest = after; + while let Some(c) = rest.chars().next() { + match c { + ' ' => { + cols += 1; + bytes += 1; + rest = &rest[1..]; + if cols >= 4 { + break; + } + } + '\t' => { + let col = ind + marker_len + cols; + let n = 4 - col % 4; + cols += n; + bytes += 1; + break; + } + _ => break, + } + } + (cols, bytes) +} + +/// Parse a list starting at `lines[i]`; returns the index after it. +fn parse_list(lines: &[String], mut i: usize, depth: usize, level: u8, out: &mut Vec, refs: &Refs, budget: &std::cell::Cell) -> usize { + let Some(first) = lines.get(i).and_then(|l| list_marker(l.trim_start_matches([' ', '\t']))) else { return i + 1 }; + while let Some(line) = lines.get(i) { + let ind = indent(line); + if ind >= 4 { + break; + } + let t = line.trim_start_matches([' ', '\t']); + let Some(m) = list_marker(t) else { break }; + if m.ordered != first.ordered || m.ch != first.ch { + break; + } + let after = t.get(m.len..).unwrap_or(""); + let (spaces, skip) = if indent(after) > 4 { + (1, 1) + } else if after.starts_with([' ', '\t']) { + marker_space(ind, m.len, after) + } else { + (0, 0) + }; + let content_indent = if is_blank(after) { ind + m.len + 1 } else { ind + m.len + spaces }; + let item0 = if is_blank(after) { String::new() } else { after.get(skip.min(after.len())..).unwrap_or("").to_string() }; + let mut item: Vec = vec![item0]; + i += 1; + while let Some(l) = lines.get(i) { + if is_blank(l) { + item.push(String::new()); + } else if indent(l) >= content_indent { + item.push(strip_indent(l, content_indent).to_string()); + } else if item.last().is_some_and(|x| !is_blank(x)) && !interrupts(l) && list_marker(l.trim_start_matches([' ', '\t'])).is_none() { + // Lazy continuation of the item's paragraph. + item.push(l.trim_start_matches([' ', '\t']).to_string()); + } else { + break; + } + i += 1; + } + // Blank lines at the end of an item belong between items. + while item.len() > 1 && item.last().is_some_and(String::is_empty) { + item.pop(); + } + let li = ListInfo { ordered: first.ordered, level: level.min(8), start: first.start, ..Default::default() }; + let inner = if depth >= MAX_NEST { + let mut p = Para::default(); + p.push_text(&item.join(" "), &Fmt::default()); + vec![FBlock::Para(p)] + } else { + parse_blocks(&item, depth + 1, level.saturating_add(1).min(8), refs, budget) + }; + let mut placed = false; + if inner.is_empty() { + out.push(FBlock::Para(Para { list: Some(li), ..Default::default() })); + placed = true; + } + for b in inner { + match b { + FBlock::Para(mut p) if p.list.is_none() => { + if !placed { + p.list = Some(li); + placed = true; + out.push(FBlock::Para(p)); + } else if let Some(FBlock::Para(prev)) = out.last_mut() + && prev.list.is_some_and(|x| x.level == li.level) + { + // A continuation paragraph joins the item with a line break. + prev.push_text("\n", &Fmt::default()); + prev.inlines.extend(p.inlines); + } else { + p.list = Some(li); + out.push(FBlock::Para(p)); + } + } + FBlock::Para(p) => { + if !placed { + // The item starts with a nested list: give it an empty first line. + out.push(FBlock::Para(Para { list: Some(li), ..Default::default() })); + placed = true; + } + out.push(FBlock::Para(p)); + } + other => { + placed = true; + out.push(other); + } + } + } + // Blank lines between items. + while lines.get(i).is_some_and(|l| is_blank(l)) { + let next_is_item = lines.get(i + 1).is_some_and(|l| { + indent(l) < 4 && list_marker(l.trim_start_matches([' ', '\t'])).is_some_and(|m| m.ordered == first.ordered && m.ch == first.ch) + }); + if !next_is_item { + return i; + } + i += 1; + } + } + i +} diff --git a/crates/markdown/src/export.rs b/crates/markdown/src/export.rs new file mode 100644 index 000000000..82fd952e3 --- /dev/null +++ b/crates/markdown/src/export.rs @@ -0,0 +1,448 @@ +use super::blocks::thematic_break; +use super::inlines::{is_punct, within}; +use super::{Align, Arc, Cell, Document, FBlock, FTable, Fmt, Inline, Kind, model}; + +// --------------------------------------------------------------------------------------------- +// Export + +/// Escape text for Markdown (inline context). +pub fn escape(s: &str) -> String { + let mut out = String::with_capacity(s.len() + 8); + for c in s.chars() { + match c { + '\\' | '`' | '*' | '_' | '[' | ']' | '<' | '>' | '~' | '|' | '&' => { + out.push('\\'); + out.push(c); + } + '\u{000C}' | '\u{000E}' => {} + _ => out.push(c), + } + } + out +} + +/// Escape what would start a block at the beginning of a line. Leading spaces are kept, but at +/// most three (a tab counts as four): four would turn the line into an indented code block. +pub(super) fn escape_line_start(s: String) -> String { + let t = s.trim_start_matches([' ', '\t']); + let lead = s.get(..s.len() - t.len()).unwrap_or(""); + let cols: usize = lead.chars().map(|c| if c == '\t' { 4 } else { 1 }).sum(); + let indent = " ".repeat(cols.min(3)); + let needs = t.starts_with('#') + || t.starts_with('>') + || t.starts_with("- ") + || t.starts_with("+ ") + || t.starts_with("-\t") + || t.starts_with("+\t") + || t == "-" + || t == "+" + || t.starts_with('=') + || (t.starts_with('-') && t.trim_end_matches([' ', '\t']).chars().all(|c| c == '-')) + || thematic_break(t) + || { + let d = t.chars().take_while(char::is_ascii_digit).count(); + d > 0 + && t.get(d..).is_some_and(|r| { + r.starts_with(". ") || r.starts_with(") ") || r.starts_with(".\t") || r.starts_with(")\t") || r == "." || r == ")" + }) + }; + if !needs { + return if cols > 3 || lead.contains('\t') { format!("{indent}{t}") } else { s }; + } + if let Some(d) = t.find(['.', ')']).filter(|_| t.starts_with(|c: char| c.is_ascii_digit())) { + return format!("{indent}{}\\{}", &t[..d], &t[d..]); + } + format!("{indent}\\{t}") +} + +/// [`escape_line_start`] for every line of a body, including those after a manual line break. +fn escape_lines(body: String) -> String { + if !body.contains("\\\n") { + return escape_line_start(body); + } + body.split("\\\n").map(|l| escape_line_start(l.to_string())).collect::>().join("\\\n") +} + +fn code_span(t: &str) -> String { + let t = t.replace("\r\n", " ").replace(['\r', '\n'], " "); + let mut longest = 0; + let mut cur = 0; + for c in t.chars() { + if c == '`' { + cur += 1; + longest = longest.max(cur); + } else { + cur = 0; + } + } + let ticks = "`".repeat(longest + 1); + let pad = if t.starts_with('`') || t.ends_with('`') || (t.starts_with(' ') && t.ends_with(' ') && !t.trim().is_empty()) { " " } else { "" }; + format!("{ticks}{pad}{t}{pad}{ticks}") +} + +#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug)] +enum Mark { + Bold, + Italic, + Strike, +} + +/// Inline spans → Markdown with properly nested markers. +pub(super) fn inlines_md(inlines: &[Inline]) -> String { + inlines_md_impl(inlines, false) +} + +fn inlines_md_table(inlines: &[Inline]) -> String { + inlines_md_impl(inlines, true) +} + +fn inlines_md_impl(inlines: &[Inline], in_table: bool) -> String { + // Split into (text, fmt) pieces with whitespace moved outside emphasis. + let mut pieces: Vec<(String, Fmt, Option)> = Vec::new(); + let eq = craft_flow::equations_as_text(inlines); + // Markdown keeps no ruby: its base text goes through the text path below. + let inlines = craft_flow::ruby_as_text(&eq); + for i in inlines.iter() { + match i { + Inline::Text(t, f) => { + let has_emph = f.bold || f.italic || f.strike; + if has_emph && !f.code { + let core = t.trim_matches([' ', '\t', '\n']); + let lead = &t[..t.len() - t.trim_start_matches([' ', '\t', '\n']).len()]; + let trail = &t[t.trim_end_matches([' ', '\t', '\n']).len()..]; + let plain = Fmt { bold: false, italic: false, strike: false, ..f.clone() }; + if !lead.is_empty() { + pieces.push((lead.to_string(), plain.clone(), None)); + } + if !core.is_empty() { + pieces.push((core.to_string(), f.clone(), None)); + } + if !trail.is_empty() && !core.is_empty() { + pieces.push((trail.to_string(), plain, None)); + } + } else { + pieces.push((t.clone(), f.clone(), None)); + } + } + Inline::Image(img) => { + let name = format!("image.{}", img.ext); + pieces.push((String::new(), Fmt::default(), Some(format!("![{}]({})", escape(&img.alt), name)))); + } + Inline::Anchor(a) => { + let safe: String = a.chars().filter(|c| c.is_alphanumeric() || matches!(c, '_' | '-' | '.' | ':')).collect(); + pieces.push((String::new(), Fmt::default(), Some(format!("")))); + } + Inline::Figure(alt) | Inline::Chart(craft_flow::Chart { alt, .. }) => { + pieces.push((String::new(), Fmt::default(), Some(format!("![{}]()", escape(alt))))) + } + Inline::Equation { .. } => {} + // ASK and SET show nothing (see `model::shows_nothing`). + Inline::Field { instr, .. } if model::shows_nothing(instr) => {} + Inline::Field { result, fmt, .. } | Inline::Control { text: result, fmt, .. } => pieces.push((result.clone(), fmt.clone(), None)), + Inline::Note { .. } + | Inline::Comment { .. } + | Inline::CommentEnd(_) + | Inline::Shape { .. } + | Inline::Group { .. } + | Inline::FieldStart(_) + | Inline::FieldEnd + | Inline::AnchorEnd(_) => {} + // Read as its base text by `ruby_as_text` above. + Inline::Ruby { .. } => {} + } + } + let mut out = String::new(); + let mut stack: Vec = Vec::new(); + let mut link: Option> = None; + let close_all = |out: &mut String, stack: &mut Vec| { + while let Some(m) = stack.pop() { + out.push_str(marker(m)); + } + }; + for (text, f, raw) in pieces { + // Links are the outermost construct; a script or other non-web target is plain text. + let f_link = f.link.clone().filter(|l| craft_wordmodel::link::is_safe_href(l)); + if f_link != link || raw.is_some() { + close_all(&mut out, &mut stack); + if let Some(l) = &link { + out.push_str(&format!("]({})", link_target(l))); + } + link = None; + if let Some(r) = raw { + out.push_str(&r); + continue; + } + if let Some(l) = f_link { + out.push('['); + link = Some(l); + } + } + let want: Vec = + [(f.bold, Mark::Bold), (f.italic, Mark::Italic), (f.strike, Mark::Strike)].iter().filter(|x| x.0).map(|x| x.1).collect(); + let body = if f.code { + if in_table { code_span(&text.replace('|', "\\|")) } else { code_span(&text) } + } else { + escape(&text).replace('\n', "\\\n").replace('\t', " ") + }; + // Close until the stack is a prefix of what we want. + let mut close = String::new(); + while let Some(pos) = stack.iter().position(|m| !want.contains(m)) { + while stack.len() > pos { + if let Some(m) = stack.pop() { + close.push_str(marker(m)); + } + } + } + let mut open = String::new(); + for m in want { + if !stack.contains(&m) { + open.push_str(marker(m)); + stack.push(m); + } + } + // CommonMark only reads a closing run after punctuation as closing when whitespace or + // punctuation follows it, and an opening run before punctuation as opening when whitespace + // or punctuation precedes it. Where a letter sits there instead, or an opening run would + // directly follow a closing run (the two would merge into one run), an empty HTML comment (which readers drop) supplies + // the punctuation. + let prev = out.chars().next_back(); + let next = body.chars().next(); + let word = |c: Option| c.is_some_and(|c| !c.is_whitespace() && !is_punct(c)); + out.push_str(&close); + let close_needs = !close.is_empty() && prev.is_some_and(is_punct) && (!open.is_empty() || word(next)); + let open_needs = !open.is_empty() && next.is_some_and(is_punct) && (!close.is_empty() || word(prev)); + if close_needs || open_needs { + out.push_str(EMPTY_COMMENT); + } + out.push_str(&open); + out.push_str(&body); + } + close_all(&mut out, &mut stack); + if let Some(l) = &link { + out.push_str(&format!("]({})", link_target(l))); + } + out +} + +/// `l` as a Markdown link destination that reads back as exactly `l`, the target +/// `is_safe_href` passed. What Markdown would decode (a backslash escape, an entity reference) +/// or end the destination on (`<`, `>`) is backslash-escaped, never deleted: deleting `<` or `>` +/// could turn an accepted relative target into `javascript:…` or `//host`. Control characters +/// can't be written in a destination and are left out, as the safety check ignores them. +fn link_target(l: &str) -> String { + let l: String = l.chars().filter(|c| !c.is_ascii_control()).collect(); + let mut out = String::with_capacity(l.len() + 2); + for (i, c) in l.char_indices() { + let rest = l.get(i + c.len_utf8()..).unwrap_or(""); + match c { + '<' | '>' => out.push('\\'), + // A backslash is literal unless punctuation (or the closing `)`/`>`) follows it. + '\\' if rest.chars().next().is_none_or(|n| n.is_ascii_punctuation()) => out.push('\\'), + '&' if entity_like(rest) => out.push('\\'), + _ => {} + } + out.push(c); + } + if l.contains(|c: char| c.is_whitespace() || matches!(c, '(' | ')' | '<' | '>')) { format!("<{out}>") } else { out } +} + +/// Whether `rest` (the text after a `&`) starts like an entity reference (`amp;`, `#106;`, +/// `#x6A;`), which a Markdown reader would decode. +fn entity_like(rest: &str) -> bool { + let Some(end) = within(rest, 34).find(';') else { return false }; + let body = rest.get(..end).unwrap_or(""); + let body = body.strip_prefix('#').map_or(body, |n| n.strip_prefix(['x', 'X']).unwrap_or(n)); + !body.is_empty() && body.chars().all(|c| c.is_ascii_alphanumeric()) +} + +/// Inline HTML that Markdown readers drop, used to separate emphasis markers from letters. +const EMPTY_COMMENT: &str = ""; + +fn marker(m: Mark) -> &'static str { + match m { + Mark::Bold => "**", + Mark::Italic => "*", + Mark::Strike => "~~", + } +} + +pub(super) fn table_md(t: &FTable, out: &mut Vec) { + let cols = t.cols().max(1); + let cell_md = |c: &Cell| -> String { + let mut parts = Vec::new(); + for b in &c.blocks { + match b { + FBlock::Para(p) => parts.push(inlines_md_table(&p.inlines).replace("\\\n", "
")), + FBlock::Table(inner) => parts.push(escape(&inner.rows.iter().flat_map(|r| r.iter().map(Cell::text)).collect::>().join(" "))), + } + } + parts.join("
").replace('\n', " ") + }; + let align_of = |c: &Cell| c.blocks.iter().find_map(|b| if let FBlock::Para(p) = b { Some(p.align) } else { None }).flatten(); + let row_md = |r: &Vec| -> Vec { + let mut v: Vec = Vec::new(); + for c in r { + v.push(if c.covered { String::new() } else { cell_md(c) }); + for _ in 1..c.colspan.clamp(1, 63) { + v.push(String::new()); + } + } + v.resize(cols, String::new()); + v + }; + let Some(head) = t.rows.first() else { return }; + out.push(format!("| {} |", row_md(head).join(" | "))); + let mut aligns: Vec> = Vec::new(); + for c in head { + aligns.push(align_of(c)); + for _ in 1..c.colspan.clamp(1, 63) { + aligns.push(None); + } + } + aligns.resize(cols, None); + let delim: Vec<&str> = aligns + .iter() + .map(|a| match a { + Some(Align::Center) => ":---:", + Some(Align::Right) => "---:", + Some(Align::Left) => ":---", + _ => "---", + }) + .collect(); + out.push(format!("| {} |", delim.join(" | "))); + for r in t.rows.iter().skip(1) { + out.push(format!("| {} |", row_md(r).join(" | "))); + } +} + +/// Markdown text of a document. +pub fn export(doc: &Document) -> String { + let flow = model::from_doc(doc); + let mut out: Vec = Vec::new(); + write_blocks(&flow.blocks, &mut out); + let mut s = out.join("\n"); + while s.ends_with("\n\n") { + s.pop(); + } + if !s.ends_with('\n') { + s.push('\n'); + } + s +} + +/// A heading's text on one line, with a trailing run of '#' escaped so a reader does not take it +/// for the optional closing sequence (`## Item #` reads back as "Item"). +fn heading_text(body: &str) -> String { + let mut s = body.replace("\\\n", " "); + let t = s.trim_end(); + let core = t.trim_end_matches('#'); + if core.len() != t.len() && (core.is_empty() || core.ends_with([' ', '\t'])) { + s.insert(core.len(), '\\'); + } + s +} + +pub(super) fn write_blocks(blocks: &[FBlock], out: &mut Vec) { + let mut i = 0; + let mut counters = [0u32; 9]; + let mut prev_list = false; + let mut prev_top_ordered = false; + while let Some(b) = blocks.get(i) { + match b { + FBlock::Table(t) => { + table_md(t, out); + out.push(String::new()); + prev_list = false; + } + FBlock::Para(p) if p.kind == Kind::Code && p.list.is_none() => { + let mut lines = Vec::new(); + while let Some(FBlock::Para(q)) = blocks.get(i) { + if q.kind != Kind::Code || q.list.is_some() { + break; + } + lines.push(q.text()); + i += 1; + } + let longest = lines.iter().map(|l| l.chars().filter(|c| *c == '`').count()).max().unwrap_or(0); + // The fence must be longer than the longest run in the content, or a content + // line is read back as the closing fence (the `.min(64)` cap did exactly that). + let fence = "`".repeat(3.max(longest + 1)); + out.push(fence.clone()); + out.extend(lines); + out.push(fence); + out.push(String::new()); + prev_list = false; + continue; + } + FBlock::Para(p) => { + let body = inlines_md(&p.inlines); + match p.list { + Some(li) => { + let lv = li.level.min(8) as usize; + if !prev_list || (lv == 0 && prev_top_ordered != li.ordered) { + counters = [0; 9]; + } + if lv == 0 { + prev_top_ordered = li.ordered; + } + let n = counters.get_mut(lv).map(|c| { + if *c == 0 { + *c = li.start.saturating_sub(1); + } + *c = c.saturating_add(1); + *c + }); + for d in counters.iter_mut().skip(lv + 1) { + *d = 0; + } + let marker = if li.ordered { format!("{}.", n.unwrap_or(1)) } else { "-".to_string() }; + let pad = " ".repeat(4 * lv); + let cont = " ".repeat(4 * lv + marker.len() + 1); + let body = if p.kind == Kind::Code { + code_span(&p.text()) + } else { + let body = escape_lines(body).replace("\\\n", &format!("\\\n{cont}")); + // The bullet marker can turn a short run of hyphens into a rule. + if thematic_break(&format!("{marker} {body}")) { format!("\\{body}") } else { body } + }; + let line = format!("{pad}{marker} {body}").trim_end().to_string(); + // A list inside a block quote stays in it: every line of the item, its + // continuation lines included, takes the quote marker. + let line = if p.kind == Kind::Quote { format!("> {}", line.replace('\n', "\n> ")) } else { line }; + out.push(line); + prev_list = true; + // A list going into or out of a block quote is a new block: without the + // blank line, an unquoted item would be read back into the quote. + let quoted = |k: Kind| k == Kind::Quote; + let next_is_list = matches!(blocks.get(i + 1), Some(FBlock::Para(q)) if q.list.is_some() && quoted(q.kind) == quoted(p.kind)); + if !next_is_list { + out.push(String::new()); + } + } + None => { + prev_list = false; + let line = match p.kind { + Kind::Heading(n) => format!("{} {}", "#".repeat(n.clamp(1, 6) as usize), heading_text(&body)), + Kind::Title => format!("# {}", heading_text(&body)), + Kind::Rule => "---".to_string(), + Kind::Quote => { + let b = escape_lines(body); + format!("> {}", b.replace("\\\n", "\\\n> ")) + } + _ => { + if body.is_empty() { + i += 1; + continue; + } + escape_lines(body) + } + }; + out.push(line); + out.push(String::new()); + } + } + } + } + i += 1; + } +} diff --git a/crates/markdown/src/inlines.rs b/crates/markdown/src/inlines.rs new file mode 100644 index 000000000..99c397246 --- /dev/null +++ b/crates/markdown/src/inlines.rs @@ -0,0 +1,595 @@ +use super::blocks::{MAX_NEST, Refs, ref_label}; +use super::{Arc, Fmt, HashMap, Inline, decode_entity, make_img, model}; + +// ---- inlines ---- + +#[derive(Clone, Copy, PartialEq, Eq)] +enum Emph { + Em, + Strong, + Strike, +} + +enum Node { + Text(String, Fmt), + Inl(Inline), + Delim { ch: char, orig: usize, left: usize, open: bool, close: bool, opens: Vec, closes: Vec }, +} + +pub(super) fn is_punct(c: char) -> bool { + c.is_ascii_punctuation() || (!c.is_alphanumeric() && !c.is_whitespace() && !c.is_control()) +} + +/// Parse inline Markdown into formatted spans (on top of `base`). +pub fn parse_inlines(s: &str, base: &Fmt, depth: usize, refs: &Refs) -> Vec { + let nodes = tokenize(s, base, depth, refs); + emit(nodes) +} + +fn push_text(nodes: &mut Vec, s: &str, f: &Fmt) { + if s.is_empty() { + return; + } + if let Some(Node::Text(t, pf)) = nodes.last_mut() + && pf == f + { + t.push_str(s); + return; + } + nodes.push(Node::Text(s.to_string(), f.clone())); +} + +/// The closing `]` matching the `[` at byte `open` (escapes and code spans respected). Gives up +/// after looking `max` bytes ahead. Records in `known` every bracket pair it passes, and every `[` +/// still open at the end of the text: a scan from one of those would take the same path. +fn matching_bracket(s: &str, open: usize, max: usize, ticks: &Backticks, known: &mut HashMap>) -> Option { + let b = s.as_bytes(); + let mut opens: Vec = Vec::new(); + let mut i = open; + while let Some(&c) = b.get(i) { + if i - open > max { + return None; + } + match c { + b'\\' => i += 1, + b'`' => { + let n = b.get(i..).map(|r| r.iter().take_while(|x| **x == b'`').count()).unwrap_or(1); + if let Some(end) = ticks.find(i + n, n) { + i = end + n - 1; + } else { + i += n - 1; + } + } + b'[' => opens.push(i), + b']' => { + if let Some(o) = opens.pop() { + known.insert(o, Some(i)); + } + if opens.is_empty() { + return Some(i); + } + } + _ => {} + } + i += 1; + } + for o in opens { + known.insert(o, None); + } + None +} + +/// Where a text's runs of backticks start, by run length. Finding the run that closes a code span +/// is then a lookup: scanning the rest of the text for it, again for every run nothing closes +/// (each of a different length) and from every link bracket over them, was superlinear. +struct Backticks(HashMap>); + +impl Backticks { + fn new(s: &str) -> Self { + let b = s.as_bytes(); + let mut runs: HashMap> = HashMap::new(); + let mut i = 0; + while let Some(&c) = b.get(i) { + if c == b'`' { + let k = b.get(i..).map(|r| r.iter().take_while(|x| **x == b'`').count()).unwrap_or(1); + runs.entry(k).or_default().push(i); + i += k; + } else { + i += 1; + } + } + Self(runs) + } + + /// Byte index of a run of exactly `n` backticks at or after `from` (which is not inside a run). + fn find(&self, from: usize, n: usize) -> Option { + let starts = self.0.get(&n)?; + starts.get(starts.partition_point(|&p| p < from)).copied() + } +} + +struct LinkScan<'a> { + text: &'a str, + refs: &'a Refs, + ticks: &'a Backticks, + known: HashMap>, + budget: usize, +} + +impl<'a> LinkScan<'a> { + fn parse_at(&mut self, open: usize) -> Option<(&'a str, Arc, usize)> { + let bytes = self.text.as_bytes(); + let close = match self.known.get(&open).copied() { + Some(found) => found, + None if self.budget > 0 => { + let found = matching_bracket(self.text, open, self.budget, self.ticks, &mut self.known); + self.budget = self.budget.saturating_sub(found.unwrap_or(self.text.len()).saturating_sub(open)); + found + } + None => None, + }?; + if self.budget == 0 { + return None; + } + let label_text = self.text.get(open + 1..close)?; + if bytes.get(close + 1) == Some(&b'(') { + let destination = link_dest(self.text, close + 1); + self.budget = self.budget.saturating_sub(destination.as_ref().map_or(self.text.len(), |d| d.1).saturating_sub(close)); + let (destination, end) = destination?; + return Some((label_text, Arc::from(destination), end)); + } + // Full and shortcut reference links use definitions collected before inline parsing. + if self.refs.is_empty() { + return None; + } + let (label, end) = match self.text.get(close + 1..).and_then(|rest| rest.strip_prefix('[')) { + Some(rest) => { + let ahead = within(rest, self.budget); + let shut = ahead.find(']'); + self.budget = self.budget.saturating_sub(shut.map_or(ahead.len(), |n| n + 1)); + let shut = shut?; + let inner = rest.get(..shut)?; + let label = if inner.trim().is_empty() { label_text } else { inner }; + (label, close + 2 + shut + 1) + } + None => (label_text, close + 1), + }; + // A cached bracket pair still costs a pass over its label. Without charging it, + // nested undefined references normalize every suffix again. + if label.len() > self.budget { + self.budget = 0; + return None; + } + self.budget -= label.len(); + Some((label_text, self.refs.get(&ref_label(label))?.clone(), end)) + } +} + +/// Parse `(dest "title")` at byte `at` (which holds `(`): (destination, index after `)`). +fn link_dest(s: &str, at: usize) -> Option<(String, usize)> { + let rest = s.get(at..)?.strip_prefix('(')?; + let mut i = at + 1; + let ws = rest.len() - rest.trim_start().len(); + i += ws; + let r = s.get(i..)?; + let (dest, used) = if let Some(inner) = r.strip_prefix('<') { + // The first `>` not escaped by a backslash ends it; a line break first means no link. + let b = inner.as_bytes(); + let mut k = 0; + let end = loop { + match b.get(k)? { + b'\\' => k += 1, + b'>' => break k, + b'\n' => return None, + _ => {} + } + k += 1; + }; + (inner.get(..end)?.to_string(), end + 2) + } else { + let mut depth = 0i32; + let mut end = r.len(); + let mut chars = r.char_indices().peekable(); + while let Some((k, c)) = chars.next() { + match c { + '\\' => { + chars.next(); + } + '(' => depth += 1, + ')' if depth == 0 => { + end = k; + break; + } + ')' => depth -= 1, + c if c.is_whitespace() => { + end = k; + break; + } + _ => {} + } + } + (r.get(..end)?.to_string(), end) + }; + i += used; + let r = s.get(i..)?; + let ws = r.len() - r.trim_start().len(); + i += ws; + let r = s.get(i..)?; + if let Some(q) = r.chars().next().filter(|c| matches!(c, '"' | '\'' | '(')) { + let close = if q == '(' { ')' } else { q }; + let end = r.get(1..)?.find(close)?; + i += end + 2; + let r = s.get(i..)?; + i += r.len() - r.trim_start().len(); + } + if s.get(i..)?.starts_with(')') { Some((unescape(&dest), i + 1)) } else { None } +} + +fn unescape(s: &str) -> String { + let mut out = String::with_capacity(s.len()); + let mut chars = s.chars().peekable(); + while let Some(c) = chars.next() { + if c == '\\' + && let Some(n) = chars.peek().copied().filter(char::is_ascii_punctuation) + { + out.push(n); + chars.next(); + } else { + out.push(c); + } + } + out +} + +/// The value of attribute `name` in an HTML tag's text. +fn tag_attr(tag: &str, name: &str) -> Option { + let lower = tag.to_ascii_lowercase(); + let mut from = 0; + while let Some(k) = lower.get(from..)?.find(name) { + let at = from + k; + let before = lower.get(..at)?.chars().next_back(); + let after = lower.get(at + name.len()..)?.trim_start(); + if before.is_some_and(char::is_whitespace) && after.starts_with('=') { + let v = after.get(1..)?.trim_start(); + let q = v.chars().next()?; + return Some(if q == '"' || q == '\'' { + let inner = v.get(1..)?; + let off = tag.len() - inner.len(); + let end = inner.find(q)?; + tag.get(off..off + end)?.to_string() + } else { + let end = v.find(|c: char| c.is_whitespace() || c == '>').unwrap_or(v.len()); + let off = tag.len() - v.len(); + tag.get(off..off + end)?.to_string() + }); + } + from = at + name.len(); + } + None +} + +fn tokenize(s: &str, base: &Fmt, depth: usize, refs: &Refs) -> Vec { + let mut nodes: Vec = Vec::new(); + // Bytes the link/image scans and reference-label lookups may read in total. Unmatched + // brackets and nested undefined references would otherwise rescan the rest of the text, + // which is quadratic on hostile input. Once the budget is gone, further brackets are plain + // text. A scan pays for what it reads; earlier bracket matches are looked up in `known`. + let ticks = Backticks::new(s); + let mut links = LinkScan { text: s, refs, ticks: &ticks, known: HashMap::new(), budget: s.len().saturating_mul(8).saturating_add(8192) }; + let b = s.as_bytes(); + let mut i = 0usize; + let mut text_start = 0usize; + macro_rules! flush { + () => { + if text_start < i { + push_text(&mut nodes, s.get(text_start..i).unwrap_or(""), base); + } + }; + } + while let Some(&c) = b.get(i) { + match c { + b'\\' => { + flush!(); + match s.get(i + 1..).and_then(|r| r.chars().next()) { + Some(n) if n.is_ascii_punctuation() => { + push_text(&mut nodes, &n.to_string(), base); + i += 2; + } + _ => { + push_text(&mut nodes, "\\", base); + i += 1; + } + } + text_start = i; + } + b'`' => { + flush!(); + let (code, fmt, end) = code_span(s, i, base, &ticks); + push_text(&mut nodes, &code, &fmt); + i = end; + text_start = i; + } + b'*' | b'_' | b'~' => { + flush!(); + let ch = c as char; + let n = b.get(i..).map(|r| r.iter().take_while(|x| **x == c).count()).unwrap_or(1); + let before = s.get(..i).and_then(|r| r.chars().next_back()).unwrap_or(' '); + let after = s.get(i + n..).and_then(|r| r.chars().next()).unwrap_or(' '); + let lf = !after.is_whitespace() && (!is_punct(after) || before.is_whitespace() || is_punct(before)); + let rf = !before.is_whitespace() && (!is_punct(before) || after.is_whitespace() || is_punct(after)); + let (open, close) = match ch { + '_' => (lf && (!rf || is_punct(before)), rf && (!lf || is_punct(after))), + '~' if n != 2 => (false, false), + _ => (lf, rf), + }; + if open || close { + nodes.push(Node::Delim { ch, orig: n, left: n, open, close, opens: Vec::new(), closes: Vec::new() }); + } else { + push_text(&mut nodes, s.get(i..i + n).unwrap_or(""), base); + } + i += n; + text_start = i; + } + b'!' | b'[' if depth < MAX_NEST => { + let img = c == b'!'; + let open = if img { i + 1 } else { i }; + let parsed = if b.get(open) == Some(&b'[') { links.parse_at(open) } else { None }; + match parsed { + Some((inner, dest, end)) if img => { + flush!(); + let alt: String = parse_inlines(inner, &Fmt::default(), depth + 1, refs) + .iter() + .filter_map(|x| if let Inline::Text(t, _) = x { Some(t.as_str()) } else { None }) + .collect(); + match model::data_uri(&dest).and_then(|d| make_img(d, None, None, &alt)) { + Some(im) => nodes.push(Node::Inl(Inline::Image(im))), + None => push_text(&mut nodes, &alt, base), + } + i = end; + text_start = i; + } + Some((inner, dest, end)) if base.link.is_none() => { + flush!(); + let mut f = base.clone(); + // A destination too long to keep leaves its text unlinked. + f.link = (dest.len() <= model::MAX_LINK).then_some(dest); + if f.link.is_none() { + model::dropped(model::Dropped::Link); + } + for x in parse_inlines(inner, &f, depth + 1, refs) { + nodes.push(Node::Inl(x)); + } + i = end; + text_start = i; + } + _ => i += 1, + } + } + b'<' => { + if let Some((end, parsed)) = angle_inlines(s, i, base) { + flush!(); + nodes.extend(parsed); + i = end; + text_start = end; + } else { + i += 1; + } + } + b'&' => { + let rest = s.get(i..).unwrap_or(""); + match within(rest, 33).find(';').and_then(|k| decode_entity(rest.get(1..k)?).map(|ch| (ch, k))) { + Some((ch, k)) => { + flush!(); + push_text(&mut nodes, &ch, base); + i += k + 1; + text_start = i; + } + None => i += 1, + } + } + _ => i += 1, + } + } + flush!(); + nodes +} + +fn angle_inlines(s: &str, start: usize, base: &Fmt) -> Option<(usize, Vec)> { + if let Some(pos) = s.get(start..).and_then(|rest| rest.strip_prefix("")) { + return Some((start + 4 + pos + 3, Vec::new())); + } + let rest = s.get(start + 1..).unwrap_or(""); + let tag_end = within(rest, MAX_TAG).find('>')?; + let inner = rest.get(..tag_end)?; + let lower = inner.to_ascii_lowercase(); + let end = start + inner.len() + 2; + let mut nodes = Vec::new(); + if !inner.is_empty() + && !inner.contains([' ', '<', '\n']) + && (inner.contains("://") || lower.starts_with("mailto:") || (inner.contains('@') && !inner.contains('/'))) + { + let mut fmt = base.clone(); + fmt.link = Some(if inner.contains('@') && !inner.contains(':') { format!("mailto:{inner}").into() } else { inner.into() }); + push_text(&mut nodes, inner, &fmt); + Some((end, nodes)) + } else if matches!(lower.trim_end_matches('/').trim(), "br") { + push_text(&mut nodes, "\n", base); + Some((end, nodes)) + } else if lower.starts_with("a ") && rest.get(inner.len() + 1..).is_some_and(|tail| tail.to_ascii_lowercase().starts_with("")) { + if let Some(name) = tag_attr(inner, "id").or_else(|| tag_attr(inner, "name")) { + nodes.push(Node::Inl(Inline::Anchor(name))); + } + Some((end + 4, nodes)) + } else { + None + } +} + +fn code_span(s: &str, start: usize, base: &Fmt, ticks: &Backticks) -> (String, Fmt, usize) { + let bytes = s.as_bytes(); + let count = bytes.get(start..).map(|tail| tail.iter().take_while(|byte| **byte == b'`').count()).unwrap_or(1); + let Some(end) = ticks.find(start + count, count) else { + return (s.get(start..start + count).unwrap_or("").to_string(), base.clone(), start + count); + }; + let mut code = s.get(start + count..end).unwrap_or("").replace('\n', " "); + if code.len() >= 2 && code.starts_with(' ') && code.ends_with(' ') && !code.trim().is_empty() { + code = code[1..code.len() - 1].to_string(); + } + let mut fmt = base.clone(); + fmt.code = true; + (code, fmt, end + count) +} + +/// Longest `<...>` tag or autolink taken as inline HTML. +const MAX_TAG: usize = 4096; + +/// The first `n` bytes of `s` (fewer if that would cut a character), so a search for a closing +/// character stays short however long the text is. +pub(super) fn within(s: &str, n: usize) -> &str { + let mut end = n.min(s.len()); + while !s.is_char_boundary(end) { + end -= 1; + } + s.get(..end).unwrap_or("") +} + +fn emph_index(ch: char) -> usize { + match ch { + '*' => 0, + '_' => 1, + _ => 2, + } +} + +/// The CommonMark "process emphasis" pass over the delimiter runs, then flattening into spans. +fn emit(mut nodes: Vec) -> Vec { + // Delimiter stack of node indexes; bottoms per (char, closer length % 3, closer can open). + let mut stack: Vec = Vec::new(); + let mut bottom = [[[None::; 2]; 3]; 3]; + for c in 0..nodes.len() { + let (ch, corig, copen, cclose) = match nodes.get(c) { + Some(Node::Delim { ch, orig, open, close, .. }) => (*ch, *orig, *open, *close), + _ => continue, + }; + if cclose { + loop { + let cleft = match nodes.get(c) { + Some(Node::Delim { left, .. }) => *left, + _ => 0, + }; + if cleft == 0 { + break; + } + let bot = bottom.get(emph_index(ch)).and_then(|x| x.get(corig % 3)).and_then(|x| x.get(copen as usize)).copied().flatten(); + let mut found = None; + for (k, &o) in stack.iter().enumerate().rev() { + if bot.is_some_and(|b| o <= b) { + break; + } + if let Some(Node::Delim { ch: och, orig: oorig, left: oleft, open: oopen, close: oclose, .. }) = nodes.get(o) { + if *och != ch || !*oopen || *oleft == 0 { + continue; + } + if ch == '~' && (*oleft < 2 || cleft < 2) { + continue; + } + let odd = (*oclose || copen) && (oorig + corig) % 3 == 0 && !(oorig % 3 == 0 && corig % 3 == 0); + if odd { + continue; + } + found = Some((k, o, *oleft)); + break; + } + } + let Some((k, o, oleft)) = found else { + if let Some(slot) = bottom.get_mut(emph_index(ch)).and_then(|x| x.get_mut(corig % 3)).and_then(|x| x.get_mut(copen as usize)) { + *slot = Some(c.saturating_sub(1)); + } + break; + }; + let (used, kind) = if ch == '~' { + (2, Emph::Strike) + } else if oleft >= 2 && cleft >= 2 { + (2, Emph::Strong) + } else { + (1, Emph::Em) + }; + if let Some(Node::Delim { left, opens, .. }) = nodes.get_mut(o) { + *left -= used; + opens.push(kind); + } + if let Some(Node::Delim { left, closes, .. }) = nodes.get_mut(c) { + *left -= used; + closes.push(kind); + } + // Delimiters between opener and closer can no longer match. + stack.truncate(k + 1); + if oleft - used == 0 { + stack.truncate(k); + } + } + } + let left = match nodes.get(c) { + Some(Node::Delim { left, .. }) => *left, + _ => 0, + }; + if copen && left > 0 { + stack.push(c); + } + } + // Flatten. + let mut out: Vec = Vec::new(); + let (mut em, mut strong, mut strike) = (0usize, 0usize, 0usize); + let push = |out: &mut Vec, t: &str, f: &Fmt, em: usize, strong: usize, strike: usize| { + if t.is_empty() { + return; + } + let mut f = f.clone(); + f.italic |= em > 0; + f.bold |= strong > 0; + f.strike |= strike > 0; + if let Some(Inline::Text(pt, pf)) = out.last_mut() + && *pf == f + { + pt.push_str(t); + return; + } + out.push(Inline::Text(t.to_string(), f)); + }; + // Delimiter literals take the formatting (link, …) of the text before them: the last text + // node, tracked here rather than searched for backwards from every delimiter (quadratic on + // a paragraph of delimiters). + let mut last_text: Option<&Fmt> = None; + for n in &nodes { + match n { + Node::Text(t, f) => { + push(&mut out, t, f, em, strong, strike); + last_text = Some(f); + } + Node::Inl(Inline::Text(t, f)) => push(&mut out, t, f, em, strong, strike), + Node::Inl(other) => out.push(other.clone()), + Node::Delim { ch, left, opens, closes, .. } => { + for e in closes { + match e { + Emph::Em => em = em.saturating_sub(1), + Emph::Strong => strong = strong.saturating_sub(1), + Emph::Strike => strike = strike.saturating_sub(1), + } + } + if *left > 0 { + let lit: String = std::iter::repeat_n(*ch, *left).collect(); + let f = last_text.map_or_else(Fmt::default, |f| Fmt { bold: false, italic: false, strike: false, ..f.clone() }); + push(&mut out, &lit, &f, em, strong, strike); + } + for e in opens { + match e { + Emph::Em => em += 1, + Emph::Strong => strong += 1, + Emph::Strike => strike += 1, + } + } + } + } + } + out +} diff --git a/crates/markdown/src/lib.rs b/crates/markdown/src/lib.rs new file mode 100644 index 000000000..e7fc9abfc --- /dev/null +++ b/crates/markdown/src/lib.rs @@ -0,0 +1,48 @@ +#![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)] +//! Markdown: a CommonMark subset plus GitHub tables and strikethrough. +//! +//! Import: ATX and setext headings, paragraphs with soft/hard breaks, block quotes (→ Quote +//! style), fenced and indented code (→ one Code paragraph per line), thematic breaks (→ a +//! bottom-border paragraph), bullet and ordered lists (nested by indentation), GFM pipe tables, +//! and inlines: emphasis/strong (the CommonMark delimiter algorithm), `~~strike~~`, code spans, +//! inline links, autolinks, images (`data:` URIs become pictures, others their alt text), +//! backslash escapes, entities, HTML comments (``), `
` and `` anchors. +//! +//! Export writes the same constructs; pictures become `![alt](media-name)` placeholders. + +#[cfg(doctest)] +#[doc = include_str!("../README.md")] +struct ReadmeExamples; + +use std::collections::HashMap; +use std::sync::Arc; + +use craft_wordmodel::table::{MAX_COLS, MAX_ROWS}; +use craft_wordmodel::{Align, Document}; + +use craft_flow::{self as model, Cell, FBlock, FTable, Fmt, Inline, Kind, ListInfo, Para, make_img}; + +mod blocks; +mod export; +mod inlines; + +pub use craft_flow::MAX_TABLE_CELLS; + +/// The text of an entity body (`amp`, `#38`, `#x26`). +fn decode_entity(body: &str) -> Option { + craft_html::decode_entity(body).map(String::from) +} + +pub use blocks::{Refs, import, import_on, parse}; +pub use export::escape; +pub use export::export; +#[cfg(test)] +use export::{escape_line_start, inlines_md, table_md, write_blocks}; +pub use inlines::parse_inlines; + +#[cfg(test)] +use blocks::split_row; +#[cfg(test)] +mod tests; diff --git a/crates/markdown/src/tests.rs b/crates/markdown/src/tests.rs new file mode 100644 index 000000000..96ad1dc3a --- /dev/null +++ b/crates/markdown/src/tests.rs @@ -0,0 +1,795 @@ +use super::*; + +fn inl(s: &str) -> Vec { + parse_inlines(s, &Fmt::default(), 0, &Refs::new()) +} + +fn spans(s: &str) -> Vec<(String, bool, bool)> { + inl(s).into_iter().filter_map(|i| if let Inline::Text(t, f) = i { Some((t, f.bold, f.italic)) } else { None }).collect() +} + +#[test] +fn emphasis() { + assert_eq!(spans("a *b* c"), vec![("a ".into(), false, false), ("b".into(), false, true), (" c".into(), false, false)]); + assert_eq!(spans("**b**"), vec![("b".into(), true, false)]); + assert_eq!(spans("***x***"), vec![("x".into(), true, true)]); + assert_eq!(spans("*a **b** c*"), vec![("a ".into(), false, true), ("b".into(), true, true), (" c".into(), false, true)]); + assert_eq!(spans("snake_case_name"), vec![("snake_case_name".into(), false, false)]); + assert_eq!(spans("2 * 3 * 4"), vec![("2 * 3 * 4".into(), false, false)]); + assert_eq!(spans("**unclosed"), vec![("**unclosed".into(), false, false)]); + let s = inl("~~gone~~"); + assert!(matches!(&s[0], Inline::Text(t, f) if t == "gone" && f.strike)); +} + +#[test] +fn links_code_escapes() { + let s = inl("see [the *site*](http://x.org \"T\") and `a*b*` \\*lit\\* & "); + let link: Vec<_> = s + .iter() + .filter_map(|i| if let Inline::Text(t, f) = i { f.link.as_ref().map(|l| (t.clone(), l.to_string(), f.italic)) } else { None }) + .collect(); + assert_eq!(link[0], ("the ".into(), "http://x.org".into(), false)); + assert_eq!(link[1], ("site".into(), "http://x.org".into(), true)); + assert!(link.iter().any(|l| l.1 == "https://y.com")); + assert!(s.iter().any(|i| matches!(i, Inline::Text(t, f) if t == "a*b*" && f.code))); + let text: String = s.iter().filter_map(|i| if let Inline::Text(t, _) = i { Some(t.as_str()) } else { None }).collect(); + assert!(text.contains("*lit* & "), "{text}"); +} + +/// Reference links: `[text][label]`, `[text][]` and `[text]` take their destination from a +/// definition line, and the definition itself leaves the document. Before, none of the three +/// was a link and the definition stayed as a paragraph of its own (#3238). +#[test] +fn reference_links_resolve_and_their_definitions_leave_the_body() { + let links = |md: &str| -> Vec<(String, String)> { + match &*parse(md).blocks { + [FBlock::Para(p), ..] => p + .inlines + .iter() + .filter_map(|x| match x { + Inline::Text(t, f) => f.link.as_deref().map(|l| (t.clone(), l.to_string())), + _ => None, + }) + .collect(), + _ => vec![], + } + }; + let def = "\n\n[ref1]: https://example.com/ref\n"; + let to_ref = |text: &str| vec![(text.to_string(), "https://example.com/ref".to_string())]; + + assert_eq!(links(&format!("[click here][ref1]{def}")), to_ref("click here"), "full"); + assert_eq!(links(&format!("[ref1][]{def}")), to_ref("ref1"), "collapsed"); + assert_eq!(links(&format!("[ref1]{def}")), to_ref("ref1"), "shortcut"); + // Labels match case-folded with runs of white space collapsed (CommonMark §4.7). + assert_eq!(links(&format!("[click here][ REF1 ]{def}")), to_ref("click here"), "folded label"); + // An undefined label is not a link: an ordinary bracketed phrase stays text. + assert_eq!(links(&format!("[nope]{def}")), vec![], "undefined"); + // Inline links are unaffected. + assert_eq!(links("[x](https://inline.example)"), vec![("x".into(), "https://inline.example".into())], "inline"); + + // The definition is not a paragraph, and its text is nowhere in the body. + let doc = import(&format!("Reference link: [click here][ref1]{def}")); + let text = doc.plain_text(craft_wordmodel::StoryRef::Body); + assert_eq!(text, "Reference link: click here", "{text:?}"); + + // A definition inside a fence is code, not a definition. + let fenced = "```\n[ref1]: https://example.com/ref\n```\n\n[ref1]\n"; + let body = import(fenced).plain_text(craft_wordmodel::StoryRef::Body); + assert!(body.contains("[ref1]: https://example.com/ref"), "the fenced definition is still code: {body:?}"); + assert_eq!(links(fenced), vec![], "a fenced definition defines nothing"); +} + +/// Cached bracket pairs must not make undefined shortcut references normalize every nested +/// suffix again. One unrelated definition keeps this on the reference-lookup path. +#[test] +fn nested_undefined_reference_labels_have_bounded_work() { + let literal = format!("prefix {}x{} suffix", "[".repeat(128_000), "]".repeat(128_000)); + let src = format!("{literal}\n\n[other]: https://example.com/other\n"); + let started = std::time::Instant::now(); + let doc = import(&src); + let elapsed = started.elapsed(); + assert_eq!(doc.plain_text(craft_wordmodel::StoryRef::Body), literal); + assert!(elapsed < std::time::Duration::from_secs(10), "nested undefined references took {elapsed:?}"); +} + +#[test] +fn reference_lookup_keeps_long_unicode_labels_and_nested_text() { + // The work guard is not a label-length cap. Collapsed/full/shortcut references keep their + // case and whitespace matching, even when lowercasing changes the number of UTF-8 bytes. + let label = format!("{}İ END", "Écho ".repeat(1500)); + let key = label.to_lowercase(); + let src = format!("[{label}] [{label}][] [full][{label}]\n\n[{key}]: https://example.com/long\n"); + let flow = parse(&src); + let FBlock::Para(p) = &flow.blocks[0] else { panic!("paragraph") }; + let links: Vec<_> = p + .inlines + .iter() + .filter_map(|x| match x { + Inline::Text(t, f) if f.link.is_some() => Some((t.as_str(), f.link.as_deref())), + _ => None, + }) + .collect(); + assert_eq!( + links, + vec![ + (label.as_str(), Some("https://example.com/long")), + (label.as_str(), Some("https://example.com/long")), + ("full", Some("https://example.com/long")) + ] + ); + + let refs = Refs::from([("known".into(), Arc::from("https://example.com/known"))]); + let out = parse_inlines("[outer [known]] tail [inline](https://example.com/inline)", &Fmt::default(), 0, &refs); + let text: String = out.iter().filter_map(|x| if let Inline::Text(t, _) = x { Some(t.as_str()) } else { None }).collect(); + assert_eq!(text, "[outer known] tail inline"); + assert!(out.iter().any(|x| matches!(x, Inline::Text(t, f) if t == "known" && f.link.as_deref() == Some("https://example.com/known")))); + assert!(out.iter().any(|x| matches!(x, Inline::Text(t, f) if t == "inline" && f.link.as_deref() == Some("https://example.com/inline")))); +} + +/// A definition has to start a block (CommonMark §4.7), and a fence opens and closes by the +/// same rules the block parser uses. Reading a line without that context deleted text: a +/// definition-shaped line inside a paragraph, and every such line inside a code block whose +/// fence this pass thought had closed. +#[test] +fn a_definition_shaped_line_that_is_not_a_definition_stays_in_the_document() { + let body = |md: &str| import(md).plain_text(craft_wordmodel::StoryRef::Body); + + // A definition cannot interrupt a paragraph: this is the author's text, lines and all. + let para = "Status update\n[Warning]: unstable\nmore text\n"; + assert_eq!(body(para), "Status update [Warning]: unstable more text", "{:?}", body(para)); + + // `` ```rust `` holds an info string, so it does not close a fence: the definition-shaped + // line after it is still code. + let code = "```\n```rust\n[foo]: /bar\n```\n\nSee [foo].\n"; + assert!(body(code).contains("[foo]: /bar"), "{:?}", body(code)); + assert!(body(code).ends_with("See [foo]."), "nothing defines foo: {:?}", body(code)); + + // Four spaces of indentation is code, not a fence, so the definition that follows is + // taken and the reference resolves. + let indented = " ```\n\n[x]: /y\n\nSee [x].\n"; + let doc = import(indented); + let text = doc.plain_text(craft_wordmodel::StoryRef::Body); + assert!(text.contains("```") && text.ends_with("See x."), "{text:?}"); + + // A definition still gives up its line after a blank line, at the start of the document, + // after a heading, and after another definition. + let starts = "[a]: /a\n[b]: /b\n\n# Head\n[c]: /c\n\nSee [a], [b], [c].\n"; + assert_eq!(body(starts), "Head\nSee a, b, c.", "{:?}", body(starts)); + + // A footnote definition is not a link definition: it stays in the body. + let footnote = "x[^1]\n\n[^1]: Note\n"; + assert!(body(footnote).contains("[^1]: Note"), "{:?}", body(footnote)); +} + +#[test] +fn blocks() { + let f = parse( + "# Title\n\nPara one\ncontinues.\n\n> quoted\n\n- a\n- b\n 1. nested\n\n```\ncode *x*\n```\n\n---\n\n| A | B |\n|---|:-:|\n| 1 | 2 |\n", + ); + let kinds: Vec = f + .blocks + .iter() + .map(|b| match b { + FBlock::Para(p) => format!("{:?}{:?}:{}", p.kind, p.list.map(|l| (l.ordered, l.level)), p.text()), + FBlock::Table(t) => format!("table{}", t.rows.len()), + }) + .collect(); + assert_eq!( + kinds, + vec![ + "Heading(1)None:Title", + "NormalNone:Para one continues.", + "QuoteNone:quoted", + "NormalSome((false, 0)):a", + "NormalSome((false, 0)):b", + "NormalSome((true, 1)):nested", + "CodeNone:code *x*", + "RuleNone:", + "table2", + ] + ); +} + +#[test] +fn export_escapes_round_trip() { + let mut p = Para::default(); + p.push_text("1. not a list *really*", &Fmt::default()); + let md = escape_line_start(inlines_md(&p.inlines)); + let back = parse(&md); + let FBlock::Para(q) = &back.blocks[0] else { panic!() }; + assert_eq!(q.text(), "1. not a list *really*"); + assert!(q.list.is_none()); +} + +#[test] +fn export_emphasis_next_to_punctuation_round_trips() { + let marks: [(&str, fn(&mut Fmt)); 3] = [("bold", |f| f.bold = true), ("italic", |f| f.italic = true), ("strike", |f| f.strike = true)]; + let cases: [&[(&str, bool)]; 4] = [ + &[("注意:", true), ("请阅读", false)], + &[("a.", true), ("b", false)], + &[("a", false), ("!", true), ("b", false)], + &[("a", false), ("(x)", true), ("b", false)], + ]; + for (name, set) in marks { + for runs in cases { + let mut p = Para::default(); + for (t, on) in runs { + let mut f = Fmt::default(); + if *on { + set(&mut f); + } + p.push_text(t, &f); + } + let md = inlines_md(&p.inlines); + let back = parse(&md); + let FBlock::Para(q) = &back.blocks[0] else { panic!() }; + let want: String = runs.iter().map(|r| r.0).collect(); + assert_eq!(q.text(), want, "{name} exported as {md:?}"); + let got: Vec<(String, bool)> = q + .inlines + .iter() + .filter_map(|i| if let Inline::Text(t, f) = i { Some((t.clone(), f.bold || f.italic || f.strike)) } else { None }) + .collect(); + let expect: Vec<(String, bool)> = runs.iter().map(|(t, on)| (t.to_string(), *on)).collect(); + assert_eq!(got, expect, "{name} exported as {md:?}"); + } + } +} + +#[test] +fn export_adjacent_emphasis_next_to_punctuation_round_trips() { + let b = Fmt { bold: true, ..Fmt::default() }; + let i = Fmt { italic: true, ..Fmt::default() }; + let s = Fmt { strike: true, ..Fmt::default() }; + let cases: [&[(&str, &Fmt)]; 6] = [ + &[("ab", &b), ("!c", &i)], + &[("ab", &i), ("!c", &b)], + &[("ab", &b), ("!c", &s)], + &[("ab", &s), ("(c)", &b)], + &[("a.", &b), ("b", &i)], + &[("a.", &b), ("!b", &i)], + ]; + for runs in cases { + let mut p = Para::default(); + for (t, f) in runs { + p.push_text(t, f); + } + let md = inlines_md(&p.inlines); + let back = parse(&md); + let FBlock::Para(q) = &back.blocks[0] else { panic!() }; + let got: Vec<(String, bool, bool, bool)> = + q.inlines.iter().filter_map(|x| if let Inline::Text(t, f) = x { Some((t.clone(), f.bold, f.italic, f.strike)) } else { None }).collect(); + let expect: Vec<(String, bool, bool, bool)> = runs.iter().map(|(t, f)| (t.to_string(), f.bold, f.italic, f.strike)).collect(); + assert_eq!(got, expect, "exported as {md:?}"); + } +} + +#[test] +fn escape_line_start_preserves_indentation() { + assert_eq!(escape_line_start(" indented text".to_string()), " indented text"); + assert_eq!(escape_line_start(" # not a heading".to_string()), " \\# not a heading"); + assert_eq!(escape_line_start(" 1. not a list".to_string()), " 1\\. not a list"); + assert_eq!(escape_line_start(" > quote".to_string()), " \\> quote"); + // Four spaces or a tab would make an indented code block: the indent is capped at three. + assert_eq!(escape_line_start(" deep".to_string()), " deep"); + assert_eq!(escape_line_start("\tTabbed # text".to_string()), " Tabbed # text"); + assert_eq!(escape_line_start(" # not a heading".to_string()), " \\# not a heading"); + assert_eq!(escape_line_start(" \t1. not a list".to_string()), " 1\\. not a list"); +} + +#[test] +fn leading_unicode_whitespace_is_kept_and_does_not_start_blocks() { + let kinds_text = |md: &str| -> Vec<(Kind, bool, String)> { + parse(md).blocks.iter().filter_map(|b| if let FBlock::Para(p) = b { Some((p.kind, p.list.is_some(), p.text())) } else { None }).collect() + }; + assert_eq!(kinds_text("\u{3000}\u{3000}日本語の段落\n"), vec![(Kind::Normal, false, "\u{3000}\u{3000}日本語の段落".to_string())]); + for src in ["\u{a0}# not a heading", "\u{3000}1. not a list", "\u{a0}- x", "\u{a0}> not a quote"] { + let mut p = Para::default(); + p.push_text(src, &Fmt::default()); + let md = escape_line_start(inlines_md(&p.inlines)); + assert_eq!(kinds_text(&md), vec![(Kind::Normal, false, src.to_string())], "{src:?} via {md:?}"); + } +} + +#[test] +fn single_backtick_code_span_escaped_pipe() { + let md = "| Command | Status |\n| --- | --- |\n| `cmd \\| grep` | pass |\n"; + let flow = parse(md); + let FBlock::Table(t) = &flow.blocks[0] else { panic!("expected table") }; + assert_eq!(t.rows.len(), 2); + assert_eq!(t.rows[1].len(), 2); + let FBlock::Para(p0) = &t.rows[1][0].blocks[0] else { panic!() }; + assert_eq!(p0.inlines.len(), 1); + assert!(matches!(&p0.inlines[0], Inline::Text(t, f) if t == "cmd | grep" && f.code)); + let FBlock::Para(p1) = &t.rows[1][1].blocks[0] else { panic!() }; + assert_eq!(p1.text(), "pass"); + + let mut out = Vec::new(); + table_md(t, &mut out); + let exported = out.join("\n"); + assert!(exported.contains("`cmd \\| grep`"), "Exported: {exported}"); +} + +#[test] +fn double_backtick_code_span_escaped_pipe() { + let md = "| Syntax | Note |\n| --- | --- |\n| ``a \\| b`` | second |\n"; + let flow = parse(md); + let FBlock::Table(t) = &flow.blocks[0] else { panic!("expected table") }; + assert_eq!(t.rows.len(), 2); + assert_eq!(t.rows[1].len(), 2); + let FBlock::Para(p0) = &t.rows[1][0].blocks[0] else { panic!() }; + assert_eq!(p0.inlines.len(), 1); + assert!(matches!(&p0.inlines[0], Inline::Text(t, f) if t == "a | b" && f.code)); + let FBlock::Para(p1) = &t.rows[1][1].blocks[0] else { panic!() }; + assert_eq!(p1.text(), "second"); +} + +#[test] +fn code_span_literal_backtick_and_escaped_pipe() { + let md = "| Expression | Detail |\n| --- | --- |\n| ``a`b\\|c`` | distinct |\n"; + let flow = parse(md); + let FBlock::Table(t) = &flow.blocks[0] else { panic!("expected table") }; + assert_eq!(t.rows.len(), 2); + assert_eq!(t.rows[1].len(), 2); + let FBlock::Para(p0) = &t.rows[1][0].blocks[0] else { panic!() }; + assert_eq!(p0.inlines.len(), 1); + assert!(matches!(&p0.inlines[0], Inline::Text(t, f) if t == "a`b|c" && f.code)); + let FBlock::Para(p1) = &t.rows[1][1].blocks[0] else { panic!() }; + assert_eq!(p1.text(), "distinct"); +} + +#[test] +fn three_column_table_with_distinctive_text() { + let md = "| Col1 | Col2 | Col3 |\n| --- | --- | --- |\n| `p1\\|q1` | Distinctive Two | Distinctive Three |\n"; + let flow = parse(md); + let FBlock::Table(t) = &flow.blocks[0] else { panic!("expected table") }; + assert_eq!(t.rows.len(), 2); + assert_eq!(t.rows[1].len(), 3); + assert_eq!(t.rows[1][0].text(), "p1|q1"); + assert_eq!(t.rows[1][1].text(), "Distinctive Two"); + assert_eq!(t.rows[1][2].text(), "Distinctive Three"); + let FBlock::Para(p0) = &t.rows[1][0].blocks[0] else { panic!() }; + assert!(matches!(&p0.inlines[0], Inline::Text(_, f) if f.code)); + let FBlock::Para(p1) = &t.rows[1][1].blocks[0] else { panic!() }; + assert!(matches!(&p1.inlines[0], Inline::Text(_, f) if !f.code)); + let FBlock::Para(p2) = &t.rows[1][2].blocks[0] else { panic!() }; + assert!(matches!(&p2.inlines[0], Inline::Text(_, f) if !f.code)); +} + +#[test] +fn table_cells_past_the_document_limits_are_not_built() { + // Every body row was padded to the header's width before any cap (#3701). + let wide = format!("{}|\n{}|\n|\n| b |\n", "|a".repeat(50_000), "|-".repeat(50_000)); + craft_flow::begin_import(); + let flow = parse(&wide); + let FBlock::Table(t) = &flow.blocks[0] else { panic!("expected table") }; + assert_eq!(t.rows.len(), 3); + assert!(t.rows.iter().all(|r| r.len() == MAX_COLS)); + assert_eq!(t.rows[2][0].text(), "b"); + assert!(craft_flow::Dropped::TableCells.reported(), "the columns left out are logged"); + // Rows past the limit still belong to the table, so the text after it reads as before. + let tall = format!("| a |\n| - |\n{}\nafter\n", "| x |\n".repeat(MAX_ROWS + 10)); + craft_flow::begin_import(); + let flow = parse(&tall); + let FBlock::Table(t) = &flow.blocks[0] else { panic!("expected table") }; + assert_eq!(t.rows.len(), MAX_ROWS); + let FBlock::Para(p) = &flow.blocks[1] else { panic!("expected paragraph") }; + assert_eq!(p.text(), "after"); + assert_eq!(flow.blocks.len(), 2); + assert!(craft_flow::Dropped::TableCells.reported(), "the rows left out are logged"); +} + +/// A short row is padded to its header's width, so a small file of one-cell rows under wide +/// headers made millions of cells (CodeRabbit on #3862). The document's tables share one cell +/// budget: rows past it are left out and logged, and their lines make no paragraphs. +#[test] +fn tables_share_one_cell_budget() { + let header = |n: usize| format!("|{}|\n|{}|\n", vec![" h "; n].join("|"), vec!["-"; n].join("|")); + let fits = crate::MAX_TABLE_CELLS / MAX_COLS; + let src = format!("{}{}\nafter\n\n{}| 1 | 2 |\n", header(MAX_COLS), "| x |\n".repeat(fits + 100), header(2)); + craft_flow::begin_import(); + let flow = parse(&src); + let tables: Vec<&FTable> = flow.blocks.iter().filter_map(|b| if let FBlock::Table(t) = b { Some(t) } else { None }).collect(); + let cells: usize = tables.iter().flat_map(|t| &t.rows).map(Vec::len).sum(); + assert!(cells <= crate::MAX_TABLE_CELLS, "{cells} cells"); + assert_eq!(tables.iter().map(|t| t.rows.len()).collect::>(), [fits], "the second table is past the budget"); + let texts: Vec = flow.blocks.iter().filter_map(|b| if let FBlock::Para(p) = b { Some(p.text()) } else { None }).collect(); + assert_eq!(texts, ["after"]); + assert!(craft_flow::Dropped::TableCells.reported()); + // Within the budget a table is whole and nothing is logged. + craft_flow::begin_import(); + let flow = parse(&format!("{}| 1 | 2 |\n", header(2))); + let [FBlock::Table(t)] = flow.blocks.as_slice() else { panic!("{:?}", flow.blocks) }; + assert_eq!(t.rows.len(), 2); + assert!(!craft_flow::Dropped::TableCells.reported()); +} + +#[test] +fn a_wide_table_still_checks_every_header_and_delimiter_cell() { + // Only the first 63 cells are kept, but every one is counted and checked. + let head = "|a".repeat(100) + "|\n"; + let delim = |bad: Option| (0..100).map(|i| if Some(i) == bad { "|x" } else { "|-" }).collect::() + "|\n"; + let is_table = |md: String| matches!(parse(&md).blocks.first(), Some(FBlock::Table(_))); + assert!(is_table(format!("{head}{}| b |\n", delim(None)))); + assert!(!is_table(format!("{head}{}| b |\n", delim(Some(80)))), "a bad delimiter cell past the kept ones"); + assert!(!is_table(format!("{}|\n{}| b |\n", "|a".repeat(99), delim(None))), "99 header cells, 100 delimiter cells"); + let (cells, n) = split_row(r"| a | b \| c | d |", 2); + assert_eq!((cells, n), (vec!["a".to_string(), "b | c".to_string()], 3)); +} + +#[test] +fn regular_table_cells_containing_escaped_pipes() { + let md = "| Option | Description |\n| --- | --- |\n| Regular \\| Pipe | Normal text cell |\n"; + let flow = parse(md); + let FBlock::Table(t) = &flow.blocks[0] else { panic!("expected table") }; + assert_eq!(t.rows.len(), 2); + assert_eq!(t.rows[1].len(), 2); + assert_eq!(t.rows[1][0].text(), "Regular | Pipe"); + assert_eq!(t.rows[1][1].text(), "Normal text cell"); + let FBlock::Para(p0) = &t.rows[1][0].blocks[0] else { panic!() }; + assert!(matches!(&p0.inlines[0], Inline::Text(_, f) if !f.code)); + + let mut out = Vec::new(); + table_md(t, &mut out); + let exported = out.join("\n"); + assert!(exported.contains("Regular \\| Pipe"), "Exported: {exported}"); + assert!(!exported.contains("Regular \\\\| Pipe"), "Exported: {exported}"); +} + +#[test] +fn unescaped_pipes_behave_as_gfm_column_separators() { + let md = "| Header 1 | Header 2 |\n| --- | --- |\n| `raw|pipe` | Extra Column |\n"; + let flow = parse(md); + let FBlock::Table(t) = &flow.blocks[0] else { panic!("expected table") }; + assert_eq!(t.rows.len(), 2); + assert_eq!(t.rows[1].len(), 2); + assert_eq!(t.rows[1][0].text(), "`raw"); + assert_eq!(t.rows[1][1].text(), "pipe`"); +} + +#[test] +fn ordinary_tables_and_standalone_code_spans_unchanged() { + let md = "| Alpha | Beta |\n| --- | --- |\n| 1 | 2 |\n"; + let flow = parse(md); + let FBlock::Table(t) = &flow.blocks[0] else { panic!() }; + let mut out = Vec::new(); + table_md(t, &mut out); + assert_eq!(out.join("\n"), "| Alpha | Beta |\n| --- | --- |\n| 1 | 2 |"); + + let mut p = Para::default(); + let f = Fmt { code: true, ..Default::default() }; + p.push_text("cmd | grep", &f); + let exported = inlines_md(&p.inlines); + assert_eq!(exported, "`cmd | grep`"); +} + +#[test] +fn code_span_line_endings_stay_literal_on_export() { + let cases = [ + ("a\n# b", "a # b"), + ("a\n

", "a
b
"), + ("a\n- b", "a - b"), + ("a\n```", "a ```"), + ("a\r# b", "a # b"), + ("a\r\n# b", "a # b"), + ("a\n\n> b", "a > b"), + ("\na\n", " a "), + ("`a\n# b`", "`a # b`"), + ("cmd | grep", "cmd | grep"), + ]; + let shapes = [ + (Kind::Normal, None), + (Kind::Normal, Some(ListInfo { ordered: false, level: 0, start: 1, ..Default::default() })), + (Kind::Code, Some(ListInfo { ordered: true, level: 0, start: 1, ..Default::default() })), + ]; + for (source, expected) in cases { + for (kind, list) in shapes { + let mut p = Para::new(kind); + p.list = list; + p.push_text(source, &Fmt { code: true, ..Default::default() }); + let mut doc = model::to_doc(&model::Flow { blocks: vec![FBlock::Para(p)], ..Default::default() }); + // The flow builder removes CR controls; keep the native document's raw input. + let p = doc.para_mut(craft_wordmodel::StoryRef::Body, &craft_wordmodel::Path::top(0)).unwrap(); + p.text = source.to_string(); + p.runs[0].len = source.len(); + let md = export(&doc); + assert_eq!(md.trim_end().lines().count(), 1, "{source:?} {kind:?} {list:?} -> {md:?}"); + assert!(!md.contains('\r'), "{md:?}"); + let back = import(&md); + let flow = model::from_doc(&back); + let [FBlock::Para(q)] = flow.blocks.as_slice() else { panic!("{md:?}") }; + assert_eq!(q.text(), expected, "{source:?} {kind:?} {list:?} -> {md:?}"); + assert_eq!(q.list, list, "{md:?}"); + assert!(q.inlines.iter().all(|i| matches!(i, Inline::Text(_, f) if f.code)), "{md:?}"); + } + } + let fenced = "```\na\n# b\n```"; + assert_eq!(export(&import(fenced)).trim_end(), fenced); +} + +#[test] +fn code_span_line_endings_in_table_cells_stay_literal() { + for ending in ["\n", "\r", "\r\n"] { + let source = format!("a{ending}# b|c"); + let mut p = Para::default(); + p.push_text(&source, &Fmt { code: true, ..Default::default() }); + let cell = Cell { blocks: vec![FBlock::Para(p)], ..Default::default() }; + let table = FTable { rows: vec![vec![cell, Cell::default()], vec![Cell::default(), Cell::default()]], ..Default::default() }; + let mut doc = model::to_doc(&model::Flow { blocks: vec![FBlock::Table(table)], ..Default::default() }); + let p = doc.para_mut(craft_wordmodel::StoryRef::Body, &craft_wordmodel::Path(vec![0, 0, 0, 0])).unwrap(); + p.text = source.clone(); + p.runs[0].len = source.len(); + let md = export(&doc); + let back = model::from_doc(&import(&md)); + let [FBlock::Table(table), ..] = back.blocks.as_slice() else { panic!("{md:?}") }; + assert!(back.blocks.iter().skip(1).all(|b| matches!(b, FBlock::Para(p) if p.text().is_empty())), "{md:?}"); + assert_eq!(table.rows.len(), 2, "{md:?}"); + assert_eq!(table.rows[0].len(), 2, "{md:?}"); + let [FBlock::Para(p)] = table.rows[0][0].blocks.as_slice() else { panic!("{md:?}") }; + assert_eq!(p.text(), "a # b|c", "{md:?}"); + assert!(p.inlines.iter().all(|i| matches!(i, Inline::Text(_, f) if f.code)), "{md:?}"); + } +} + +#[test] +fn table_code_pipe_export_import_round_trip() { + let mut table = FTable::default(); + let mut cell_a = Cell::default(); + let mut para_a = Para::default(); + let fmt_a = Fmt { code: true, ..Default::default() }; + para_a.push_text("a`b|c", &fmt_a); + cell_a.blocks.push(FBlock::Para(para_a)); + + let mut cell_b = Cell::default(); + let mut para_b = Para::default(); + para_b.push_text("CRITICAL_DISTINCTIVE_INFO", &Fmt::default()); + cell_b.blocks.push(FBlock::Para(para_b)); + + let mut head_a = Cell::default(); + let mut head_para_a = Para::default(); + head_para_a.push_text("Col A", &Fmt::default()); + head_a.blocks.push(FBlock::Para(head_para_a)); + + let mut head_b = Cell::default(); + let mut head_para_b = Para::default(); + head_para_b.push_text("Col B", &Fmt::default()); + head_b.blocks.push(FBlock::Para(head_para_b)); + + table.rows.push(vec![head_a, head_b]); + table.rows.push(vec![cell_a, cell_b]); + + let mut out = Vec::new(); + table_md(&table, &mut out); + let exported_md = out.join("\n"); + + assert!(exported_md.contains("``a`b\\|c``"), "Exported: {exported_md}"); + assert!(exported_md.contains("CRITICAL\\_DISTINCTIVE\\_INFO"), "Exported: {exported_md}"); + + let back_flow = parse(&exported_md); + let FBlock::Table(back_table) = &back_flow.blocks[0] else { panic!("expected table") }; + + assert_eq!(back_table.rows.len(), 2, "Both rows must exist"); + let row1 = &back_table.rows[1]; + assert_eq!(row1.len(), 2, "Both cells must exist in row 1"); + + let back_cell_a = &row1[0]; + let back_cell_b = &row1[1]; + assert_eq!(back_cell_a.text(), "a`b|c", "Cell A text must be preserved"); + assert_eq!(back_cell_b.text(), "CRITICAL_DISTINCTIVE_INFO", "Cell B text must be preserved"); + + let FBlock::Para(back_p_a) = &back_cell_a.blocks[0] else { panic!() }; + assert_eq!(back_p_a.inlines.len(), 1); + assert!( + matches!(&back_p_a.inlines[0], Inline::Text(t, f) if t == "a`b|c" && f.code), + "Code formatting must remain intact on Cell A: {:?}", + back_p_a.inlines + ); + + let FBlock::Para(back_p_b) = &back_cell_b.blocks[0] else { panic!() }; + assert_eq!(back_p_b.inlines.len(), 1); + assert!( + matches!(&back_p_b.inlines[0], Inline::Text(t, f) if t == "CRITICAL_DISTINCTIVE_INFO" && !f.code), + "Cell B formatting must remain plain text: {:?}", + back_p_b.inlines + ); + + assert_eq!(back_cell_a.text(), "a`b|c"); + assert_eq!(back_cell_b.text(), "CRITICAL_DISTINCTIVE_INFO"); + + assert!(!back_cell_a.text().contains("CRITICAL_DISTINCTIVE_INFO")); + assert!(!back_cell_b.text().contains("a`b|c")); + + let doc = import(&exported_md); + let re_exported = export(&doc); + assert!(re_exported.contains("``a`b\\|c``"), "Re-exported: {re_exported}"); + assert!(re_exported.contains("CRITICAL\\_DISTINCTIVE\\_INFO"), "Re-exported: {re_exported}"); + let doc2 = import(&re_exported); + let back_flow2 = model::from_doc(&doc2); + let FBlock::Table(back_table2) = &back_flow2.blocks[0] else { panic!() }; + assert_eq!(back_table2.rows[1][0].text(), "a`b|c"); + assert_eq!(back_table2.rows[1][1].text(), "CRITICAL_DISTINCTIVE_INFO"); +} + +#[test] +fn ordered_list_keeps_start_number() { + assert_eq!(export(&import("5. a\n6. b")).trim_end(), "5. a\n6. b"); +} + +/// A list inside a block quote stays in the quote: its items were imported as quoted list +/// paragraphs but written back without `>`, so the list moved out of the quote. +#[test] +fn a_list_inside_a_quote_stays_quoted() { + let src = "> Intro\n>\n> - one\n> - two\n> - nested\n> 1. first\n\nAfter.\n"; + let want = "> Intro\n\n> - one\n> - two\n> - nested\n> 1. first\n\nAfter."; + let md = export(&import(src)); + assert_eq!(md.trim_end(), want); + assert_eq!(export(&import(&md)).trim_end(), want, "and stays so when read back"); + // An item's continuation line is quoted too. + assert_eq!(export(&import("> - a\\\n> b\n")).trim_end(), "> - a\\\n> b"); + // A list outside a quote is unchanged. + assert_eq!(export(&import("- one\n- two\n")).trim_end(), "- one\n- two"); + // A list after a quoted list stays outside the quote. + let md = export(&import("> - a\n\n2. b\n")); + assert_eq!(md.trim_end(), "> - a\n\n2. b"); + assert_eq!(export(&import(&md)).trim_end(), "> - a\n\n2. b", "and stays so when read back"); +} + +#[test] +fn lines_after_line_break_stay_in_paragraph() { + use craft_wordmodel::{CharProps, Document, Paragraph, StoryRef, para_block}; + let cases = ["Shopping\n- milk\n# not a heading", "a\n1. x", "a\n2) x", "a\n+ x", "a\n---", "a\n***", "a\n==", "a\n--", "a\n> q"]; + for s in cases { + let mut d = Document::new(); + d.body = vec![para_block(Paragraph::with_text(s, CharProps::default()))]; + let md = export(&d); + let back = import(&md); + assert_eq!(back.body.len(), 1, "{s:?} -> {md:?}"); + assert_eq!(back.plain_text(StoryRef::Body), s, "{md:?}"); + } +} + +#[test] +fn lines_after_line_break_stay_in_list_item_and_quote() { + let cases = ["a\n- x", "a\n# h", "a\n1. x", "a\n--", "a\n---", "a\n==", "a\n> q"]; + let shapes: [(Kind, Option); 5] = [ + (Kind::Normal, Some(ListInfo { ordered: false, level: 0, start: 1, ..Default::default() })), + (Kind::Normal, Some(ListInfo { ordered: true, level: 0, start: 1, ..Default::default() })), + (Kind::Normal, Some(ListInfo { ordered: false, level: 1, start: 1, ..Default::default() })), + (Kind::Normal, Some(ListInfo { ordered: true, level: 1, start: 1, ..Default::default() })), + (Kind::Quote, None), + ]; + for s in cases { + for (kind, list) in shapes { + let mut blocks = Vec::new(); + if let Some(li) = list.filter(|l| l.level > 0) { + let mut parent = Para::new(Kind::Normal); + parent.list = Some(ListInfo { ordered: li.ordered, level: 0, start: 1, ..Default::default() }); + parent.push_text("top", &Fmt::default()); + blocks.push(FBlock::Para(parent)); + } + let mut p = Para::new(kind); + p.list = list; + p.push_text(s, &Fmt::default()); + blocks.push(FBlock::Para(p)); + let mut out = Vec::new(); + write_blocks(&blocks, &mut out); + let md = out.join("\n"); + let back = parse(&md); + assert_eq!(back.blocks.len(), blocks.len(), "{s:?} {kind:?} {list:?} -> {md:?}"); + let Some(FBlock::Para(q)) = back.blocks.last() else { panic!("{md:?}") }; + assert_eq!(q.kind, kind, "{md:?}"); + assert_eq!(q.list, list, "{md:?}"); + assert_eq!(q.text(), s, "{md:?}"); + } + } +} + +#[test] +fn table_column_alignments_import_and_export() { + let md = "| Left | Center | Right | Default |\n| :--- | :---: | ---: | --- |\n| 1 | 2 | 3 | 4 |\n"; + let flow = parse(md); + let FBlock::Table(t) = &flow.blocks[0] else { panic!("expected table") }; + assert_eq!(t.rows.len(), 2); + let aligns: Vec> = + t.rows[0].iter().map(|c| c.blocks.iter().find_map(|b| if let FBlock::Para(p) = b { Some(p.align) } else { None }).flatten()).collect(); + assert_eq!(aligns, vec![Some(Align::Left), Some(Align::Center), Some(Align::Right), None]); + + let mut out = Vec::new(); + table_md(t, &mut out); + let exported = out.join("\n"); + assert!(exported.contains("| :--- | :---: | ---: | --- |"), "Exported: {exported}"); +} + +#[test] +fn tab_separated_list_markers() { + let f = parse("-\tbullet item\n*\tstar item\n+\tplus item\n1.\tone item\n2)\ttwo item\n"); + assert_eq!(f.blocks.len(), 5); + for (i, b) in f.blocks.iter().enumerate() { + let FBlock::Para(p) = b else { panic!("block {i} not a para") }; + assert!(p.list.is_some(), "block {i} should be a list item: {:?}", p); + } + let FBlock::Para(p0) = &f.blocks[0] else { panic!() }; + assert_eq!(p0.text(), "bullet item"); + assert!(!p0.list.unwrap().ordered); + + let FBlock::Para(p3) = &f.blocks[3] else { panic!() }; + assert_eq!(p3.text(), "one item"); + assert!(p3.list.unwrap().ordered); +} + +#[test] +fn html_comments_are_ignored_in_blocks_and_inlines() { + let md = "\n\nHello world!\n\n\n\nAfter comment."; + let flow = parse(md); + assert_eq!(flow.blocks.len(), 2); + let texts: Vec = flow.blocks.iter().filter_map(|b| if let FBlock::Para(p) = b { Some(p.text()) } else { None }).collect(); + assert_eq!(texts, ["Hello world!", "After comment."]); +} + +#[test] +fn a_paragraph_of_delimiters_parses_in_linear_time() { + // #3714: each delimiter's literal looked back for the text before it, to the start of + // the paragraph when there was none (quadratic). + let src = "*_".repeat(200_000); + let t = std::time::Instant::now(); + let out = inl(&src); + // Under a second on a loaded machine; the backwards search ran past 6 minutes. + assert!(t.elapsed() < std::time::Duration::from_secs(10), "{:?}", t.elapsed()); + let text: String = out.iter().filter_map(|i| if let Inline::Text(t, _) = i { Some(t.as_str()) } else { None }).collect(); + assert!(text.chars().all(|c| matches!(c, '*' | '_')), "only delimiters come out"); + // Literal delimiters still take the link of the text before them. + let s = inl("[a](http://x.org) [b*](http://y.org)"); + assert!(s.iter().any(|i| matches!(i, Inline::Text(t, f) if t == "b*" && f.link.as_deref() == Some("http://y.org"))), "{s:?}"); +} + +#[test] +fn exported_link_destinations_read_back_unchanged() { + // Removing `<` and `>` from a destination after the safety check could make a relative + // target a script or network-path one (`java)"); + for l in [ + "javab c", + "javascript:alert(1)", + "javascript:x", + "&", + "javascript\\:x", + "dir\\", + "dir\\(1)\\", + "q?a=1&b=2", + ] { + let out = md(l); + let back = inl(&out); + let got: Vec<_> = back.iter().filter_map(|i| if let Inline::Text(_, f) = i { f.link.as_deref().map(str::to_string) } else { None }).collect(); + assert_eq!(got, [l.to_string()], "{l:?} → {out:?}"); + } + // Ordinary destinations are written as before. + assert_eq!(md("https://example.com/a?b=1&c=2"), "[x](https://example.com/a?b=1&c=2)"); + assert_eq!(md("https://example.com/a b"), "[x]()"); + assert_eq!(md("https://e.com/x\ny"), "[x](https://e.com/xy)"); +} + +#[test] +fn heading_trailing_hash_survives_round_trip() { + let heading = |md: &str| { + let f = parse(md); + let Some(FBlock::Para(p)) = f.blocks.first() else { panic!("no paragraph in {md:?}") }; + assert_eq!(p.kind, Kind::Heading(2), "{md:?}"); + p.text() + }; + for (src, text, want) in [ + ("## Item \\#\n", "Item #", "## Item \\#\n"), + ("## Issue \\##\n", "Issue ##", "## Issue \\##\n"), + ("## \\#\n", "#", "## \\#\n"), + ("## C#\n", "C#", "## C#\n"), + ] { + assert_eq!(heading(src), text, "{src:?}"); + let md = export(&import(src)); + assert_eq!(md, want, "first export of {src:?}"); + assert_eq!(heading(&md), text, "md was {md:?}"); + assert_eq!(export(&import(&md)), want, "second export of {src:?}"); + } +} diff --git a/crates/math/Cargo.toml b/crates/math/Cargo.toml new file mode 100644 index 000000000..6cbc3251e --- /dev/null +++ b/crates/math/Cargo.toml @@ -0,0 +1,19 @@ +[package] +name = "craft-math" +description = "Equations as one tree (the Office Math object model) with its syntaxes: OMML, MathML, LaTeX math and the UnicodeMath linear format, read and written." +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +repository.workspace = true + +[lints] +workspace = true + +[dependencies] +craft-xml = { workspace = true } +serde = { workspace = true } + +[dev-dependencies] +serde_json = { workspace = true } +proptest = { workspace = true } diff --git a/crates/math/README.md b/crates/math/README.md new file mode 100644 index 000000000..77fb99984 --- /dev/null +++ b/crates/math/README.md @@ -0,0 +1,56 @@ +# craft-math + +Equations as one tree, and the syntaxes it is read from and written to: + +| Module | Syntax | Read | Write | +| --- | --- | --- | --- | +| `math` | the tree: `MNode`, `MRun`, `Math` (an equation with its kept source OMML), modelled on the Office Math object model (ECMA-376 Part 1 §22.1) | | | +| `math_linear` | UnicodeMath, the linear format Word shows (`x=(-b±√(b^2-4ac))/2a`) | `math::parse_linear` | `math::to_linear` | +| `math_latex` | LaTeX math, including MathLive's spellings | `parse_latex` | `to_latex` | +| `latex_text` | LaTeX math as text, keeping the source's spacing (for LaTeX documents) | `latex_to_linear` | `linear_to_latex` | +| `omml` | Office Math Markup (`m:oMath`, DOCX/PPTX/XLSX) | `read_omath`, `read_str` | `write_equation`, `write_str` | +| `mathml` | presentation MathML (HTML, ODF formulas, the clipboard) | `parse`, `read`, `to_tree` | `to_mathml`, `linear_to_mathml` | + +Beside them: `math_symbols` (LaTeX names of symbols), `math_tree` (the arguments of a node, a walk +over every run), `symbol_fonts` (Symbol, Wingdings and the other symbol fonts as Unicode) and +`Rgb` (a run's colour). + +```rust +use craft_math::{Math, math, math_latex, mathml, omml}; + +let tree = math_latex::parse_latex(r"\frac{a}{b}+\sqrt{x}"); +assert_eq!(math::to_linear(&tree), "a/b+√x"); + +// OMML out and back. +let eq = Math { nodes: tree.clone(), ..Default::default() }; +let xml = omml::write_str("", false, &eq, None); +let read = omml::read_str(&xml).unwrap(); +assert_eq!(read.nodes, tree); + +// MathML carries the linear format in an annotation, so it reads back exactly. +let ml = mathml::linear_to_mathml("a/b+√x", true); +assert_eq!(mathml::parse(&ml).and_then(|m| mathml::read(&m)), Some(("a/b+√x".to_string(), true))); +``` + +## Reading OMML + +`omml::read_omath` takes an `m:oMath` element of a `craft_xml` tree read with the canonical +prefixes of `omml::NAMESPACES` (`m`, `w` and `mc`, transitional and strict URIs), so a document +reader passes the element it already has. `omml::read_str` and `omml::parse` read a string. The +source XML is kept in `Math::omml`; `write_equation` writes it back unchanged while the +equation's colour is the same and the XML is well formed, so a saved document carries the +equation as Word wrote it. + +## Limits + +Nesting is bounded by `math::MAX_DEPTH` in every reader and writer; `omml::parse` reads at most +`omml::MAX_ELEMENTS` elements and `mathml::parse` keeps at most `mathml::MAX_NODES`; the LaTeX +reader looks at 20,000 characters. Nothing panics on any input. + +## Provenance + +The tree, the linear format, LaTeX, the symbol names, the tree walk, the symbol fonts and `Rgb` +are WordCraft's (`crates/doc`), as moved into craft-wordmodel; OMML is WordCraft's DOCX reader +and writer (`crates/docx/src/read/math.rs`, `write/math.rs`) and MathML its formats crate's +(`crates/formats/src/mathml.rs`), moved onto craft-xml. The MathLive command spellings and the +round-trip corpus in `tests/corpus/` come from equaSHion (storytold/craft-libs#29). diff --git a/crates/math/src/latex_text.rs b/crates/math/src/latex_text.rs new file mode 100644 index 000000000..5541a36c3 --- /dev/null +++ b/crates/math/src/latex_text.rs @@ -0,0 +1,629 @@ +//! LaTeX math and the linear format converted as text, keeping the source's spacing: for LaTeX +//! documents, whose math should read back as it was written. [`crate::math_latex`] converts the +//! same two syntaxes through the equation tree. + +/// Nesting limit for groups and arguments (hostile input). +const MAX_NEST: usize = 32; + +// --------------------------------------------------------------------------------------------- +// Equations: WordCraft keeps them in the linear format (`x=(-b±√(b^2-4ac))/2a`). + +/// Symbols with a LaTeX command: (character, command without the backslash). +const MATH_SYMBOLS: &[(char, &str)] = &[ + ('α', "alpha"), + ('β', "beta"), + ('γ', "gamma"), + ('δ', "delta"), + ('ϵ', "epsilon"), + ('ε', "varepsilon"), + ('ζ', "zeta"), + ('η', "eta"), + ('θ', "theta"), + ('ϑ', "vartheta"), + ('ι', "iota"), + ('κ', "kappa"), + ('λ', "lambda"), + ('μ', "mu"), + ('ν', "nu"), + ('ξ', "xi"), + ('π', "pi"), + ('ϖ', "varpi"), + ('ρ', "rho"), + ('ϱ', "varrho"), + ('σ', "sigma"), + ('ς', "varsigma"), + ('τ', "tau"), + ('υ', "upsilon"), + ('ϕ', "phi"), + ('φ', "varphi"), + ('χ', "chi"), + ('ψ', "psi"), + ('ω', "omega"), + ('Γ', "Gamma"), + ('Δ', "Delta"), + ('Θ', "Theta"), + ('Λ', "Lambda"), + ('Ξ', "Xi"), + ('Π', "Pi"), + ('Σ', "Sigma"), + ('Υ', "Upsilon"), + ('Φ', "Phi"), + ('Ψ', "Psi"), + ('Ω', "Omega"), + ('±', "pm"), + ('∓', "mp"), + ('×', "times"), + ('÷', "div"), + ('⋅', "cdot"), + ('·', "cdot"), + ('∘', "circ"), + ('∗', "ast"), + ('≤', "leq"), + ('≥', "geq"), + ('≠', "neq"), + ('≈', "approx"), + ('≡', "equiv"), + ('∼', "sim"), + ('≃', "simeq"), + ('≅', "cong"), + ('∝', "propto"), + ('≪', "ll"), + ('≫', "gg"), + ('∈', "in"), + ('∉', "notin"), + ('∋', "ni"), + ('⊂', "subset"), + ('⊃', "supset"), + ('⊆', "subseteq"), + ('⊇', "supseteq"), + ('∪', "cup"), + ('∩', "cap"), + ('∖', "setminus"), + ('∅', "emptyset"), + ('∀', "forall"), + ('∃', "exists"), + ('¬', "neg"), + ('∧', "wedge"), + ('∨', "vee"), + ('⊕', "oplus"), + ('⊗', "otimes"), + ('→', "to"), + ('←', "leftarrow"), + ('↔', "leftrightarrow"), + ('⇒', "Rightarrow"), + ('⇐', "Leftarrow"), + ('⇔', "Leftrightarrow"), + ('↦', "mapsto"), + ('↑', "uparrow"), + ('↓', "downarrow"), + ('∑', "sum"), + ('∏', "prod"), + ('∐', "coprod"), + ('∫', "int"), + ('∬', "iint"), + ('∭', "iiint"), + ('∮', "oint"), + ('⋃', "bigcup"), + ('⋂', "bigcap"), + ('∞', "infty"), + ('∂', "partial"), + ('∇', "nabla"), + ('ℏ', "hbar"), + ('ℓ', "ell"), + ('ℵ', "aleph"), + ('ℜ', "Re"), + ('ℑ', "Im"), + ('∠', "angle"), + ('⊥', "perp"), + ('∥', "parallel"), + ('′', "prime"), + ('…', "ldots"), + ('⋯', "cdots"), + ('⋮', "vdots"), + ('⋱', "ddots"), + ('⟨', "langle"), + ('⟩', "rangle"), + ('⌊', "lfloor"), + ('⌋', "rfloor"), + ('⌈', "lceil"), + ('⌉', "rceil"), + ('°', "circ"), + ('•', "bullet"), + ('⊤', "top"), +]; + +/// Extra input spellings mapped to the same symbols. +const MATH_ALIASES: &[(&str, char)] = &[ + ("le", '≤'), + ("ge", '≥'), + ("ne", '≠'), + ("rightarrow", '→'), + ("gets", '←'), + ("land", '∧'), + ("lor", '∨'), + ("lnot", '¬'), + ("dots", '…'), + ("dotsc", '…'), + ("dotsb", '⋯'), + ("varnothing", '∅'), + ("implies", '⇒'), + ("iff", '⇔'), + ("degree", '°'), + ("lbrace", '{'), + ("rbrace", '}'), + ("vert", '|'), + ("mid", '|'), + ("Vert", '‖'), + ("lvert", '|'), + ("rvert", '|'), + ("bot", '⊥'), + ("hslash", 'ℏ'), + ("colon", ':'), +]; + +/// Operator names written upright in both formats. +const MATH_FUNCTIONS: &[&str] = &[ + "sin", "cos", "tan", "cot", "sec", "csc", "arcsin", "arccos", "arctan", "sinh", "cosh", "tanh", "coth", "log", "ln", "lg", "exp", "lim", + "liminf", "limsup", "min", "max", "sup", "inf", "det", "dim", "gcd", "deg", "arg", "ker", "Pr", "hom", +]; + +/// Control words an exported equation may carry besides the symbols and functions above (font +/// switches, delimiters, spacing). +const MATH_COMMANDS: &[&str] = &[ + "mathbb", + "mathbf", + "mathcal", + "mathfrak", + "mathit", + "mathrm", + "mathsf", + "mathtt", + "boldsymbol", + "left", + "right", + "quad", + "qquad", + "displaystyle", + "textstyle", + "limits", + "nolimits", + "not", +]; + +/// May `\\name` from an equation's text be written to the exported file as a command? Only the +/// names known here. An equation's text comes from the document (a file someone else may have +/// made), and `\\input`, `\\write` or `\\def` in it would act on the machine of whoever compiles +/// the export. +fn known_math_command(name: &str) -> bool { + math_symbol(name).is_some() || MATH_FUNCTIONS.contains(&name) || MATH_COMMANDS.contains(&name) +} + +fn math_symbol(name: &str) -> Option { + MATH_SYMBOLS.iter().find(|(_, n)| *n == name).map(|(c, _)| *c).or_else(|| MATH_ALIASES.iter().find(|(n, _)| *n == name).map(|(_, c)| *c)) +} + +/// For every `l` in `chars`, the index of the `r` that closes it, found in one stack pass. +/// Looking groups up here keeps scanning linear: rescanning to the end of the input for every +/// unmatched `(` made long equations quadratic. +pub fn closers(chars: &[char], l: char, r: char) -> Vec> { + let mut out = vec![None; chars.len()]; + let mut open = Vec::new(); + for (i, c) in chars.iter().enumerate() { + if *c == l { + open.push(i); + } else if *c == r + && let Some(o) = open.pop() + && let Some(slot) = out.get_mut(o) + { + *slot = Some(i); + } + } + out +} + +/// The balanced group opening at `open` (see [`closers`]): its content and the index after it. +pub fn balanced(chars: &[char], closers: &[Option], open: usize) -> Option<(String, usize)> { + let close = (*closers.get(open)?)?; + Some((chars.get(open + 1..close).unwrap_or_default().iter().collect(), close + 1)) +} + +/// A linear-format equation as LaTeX math. +pub fn linear_to_latex(linear: &str) -> String { + linear_to_latex_at(linear, 0) +} + +fn linear_to_latex_at(linear: &str, depth: usize) -> String { + let chars: Vec = linear.chars().collect(); + let parens = closers(&chars, '(', ')'); + let mut o = String::new(); + let mut i = 0; + let sub = |s: &str| if depth < MAX_NEST { linear_to_latex_at(s, depth + 1) } else { escape_math_text(s) }; + while let Some(&c) = chars.get(i) { + // (a)/(b) → \frac{a}{b} + // (The `/` is looked for before the group is copied out: copying every group of a deeply + // nested equation only to find no `/` after it was quadratic.) + if c == '(' + && let Some(Some(close)) = parens.get(i) + && chars.get(close + 1) == Some(&'/') + && let Some((num, after)) = balanced(&chars, &parens, i) + && let Some((den, end)) = balanced(&chars, &parens, after + 1) + { + o.push_str(&format!("\\frac{{{}}}{{{}}}", sub(&num), sub(&den))); + i = end; + continue; + } + match c { + '^' | '_' => { + // Never `^^`: TeX reads `^^5c` as a backslash, which would start a command. + if c == '^' && o.ends_with('^') { + o.push_str("{}"); + } + o.push(c); + match balanced(&chars, &parens, i + 1) { + Some((inner, end)) => { + o.push_str(&format!("{{{}}}", sub(&inner))); + i = end; + } + None => i += 1, + } + continue; + } + '√' => { + match balanced(&chars, &parens, i + 1) { + Some((inner, end)) => { + match inner.split_once('&') { + Some((n, x)) => o.push_str(&format!("\\sqrt[{}]{{{}}}", sub(n), sub(x))), + None => o.push_str(&format!("\\sqrt{{{}}}", sub(&inner))), + } + i = end; + } + None => { + o.push_str("\\surd "); + i += 1; + } + } + continue; + } + '\\' => { + // Linear format control words (`\alpha`) are LaTeX's too. + let name: String = chars.iter().skip(i + 1).take_while(|c| c.is_ascii_alphabetic()).collect(); + if name.is_empty() { + o.push_str("\\backslash "); + i += 1; + } else if !known_math_command(&name) { + // Not a command we know: written as the text it is. + o.push_str("\\backslash "); + o.push_str(&name); + i += 1 + name.len(); + } else { + o.push('\\'); + o.push_str(&name); + i += 1 + name.len(); + if chars.get(i).is_some_and(char::is_ascii_alphabetic) { + o.push(' '); + } + } + continue; + } + '#'..='&' => { + o.push('\\'); + o.push(c); + } + '{' => o.push_str("\\{"), + '}' => o.push_str("\\}"), + '~' => o.push_str("\\sim "), + c => match MATH_SYMBOLS.iter().find(|(s, _)| *s == c) { + Some((_, name)) => { + o.push('\\'); + o.push_str(name); + // A control word needs a space only before a letter. + if chars.get(i + 1).is_some_and(char::is_ascii_alphabetic) { + o.push(' '); + } + } + None if c.is_control() => {} + None => o.push(c), + }, + } + i += 1; + } + o.trim().to_string() +} + +fn escape_math_text(s: &str) -> String { + let mut o = String::new(); + for c in s.chars().filter(|c| !matches!(c, '{' | '}' | '\\' | '$' | '%' | '#' | '&') && !c.is_control()) { + // Never `^^` (see `linear_to_latex_at`). + if c == '^' && o.ends_with('^') { + continue; + } + o.push(c); + } + o +} + +/// LaTeX math as a linear-format equation. +pub fn latex_to_linear(src: &str) -> String { + let toks = math_tokens(src); + let mut pos = 0; + let s = math_seq(&toks, &mut pos, 0, false); + s.split_whitespace().collect::>().join(" ") +} + +#[derive(Clone, Debug, PartialEq)] +enum MTok { + Cmd(String), + Open, + Close, + OptOpen, + OptClose, + Char(char), +} + +fn math_tokens(src: &str) -> Vec { + let chars: Vec = src.chars().collect(); + let mut out = Vec::new(); + let mut i = 0; + while let Some(&c) = chars.get(i) { + match c { + '\\' => { + let name: String = chars.iter().skip(i + 1).take_while(|c| c.is_ascii_alphabetic()).collect(); + if name.is_empty() { + if let Some(&n) = chars.get(i + 1) { + out.push(MTok::Cmd(n.to_string())); + } + i += 2; + } else { + i += 1 + name.len(); + out.push(MTok::Cmd(name)); + } + } + '{' => { + out.push(MTok::Open); + i += 1; + } + '}' => { + out.push(MTok::Close); + i += 1; + } + '[' => { + out.push(MTok::OptOpen); + i += 1; + } + ']' => { + out.push(MTok::OptClose); + i += 1; + } + '%' => { + // A comment, to the end of the line. + while chars.get(i).is_some_and(|c| *c != '\n') { + i += 1; + } + } + c => { + out.push(MTok::Char(if c.is_whitespace() { ' ' } else { c })); + i += 1; + } + } + } + out +} + +/// One argument: a `{…}` group or a single token. +fn math_arg(t: &[MTok], pos: &mut usize, depth: usize) -> String { + while t.get(*pos) == Some(&MTok::Char(' ')) { + *pos += 1; + } + match t.get(*pos) { + Some(MTok::Open) => { + *pos += 1; + let s = math_seq(t, pos, depth + 1, false); + if t.get(*pos) == Some(&MTok::Close) { + *pos += 1; + } + s + } + Some(MTok::Close) | None => String::new(), + Some(_) => { + let end = *pos + 1; + let mut p = *pos; + let s = math_seq(t.get(..end).unwrap_or_default(), &mut p, depth + 1, false); + *pos = end; + s + } + } +} + +/// An optional `[…]` argument. +fn math_opt(t: &[MTok], pos: &mut usize, depth: usize) -> Option { + if t.get(*pos) != Some(&MTok::OptOpen) { + return None; + } + *pos += 1; + let s = math_seq(t, pos, depth + 1, true); + if t.get(*pos) == Some(&MTok::OptClose) { + *pos += 1; + } + Some(s) +} + +/// Parenthesise a fraction part or script unless it is a single symbol. +fn wrap_part(s: &str) -> String { + let s = s.trim(); + if s.chars().count() == 1 || (!s.is_empty() && s.chars().all(|c| c.is_ascii_digit())) { s.to_string() } else { format!("({s})") } +} + +fn math_seq(t: &[MTok], pos: &mut usize, depth: usize, in_opt: bool) -> String { + let mut o = String::new(); + while let Some(tok) = t.get(*pos) { + match tok { + MTok::Close => break, + MTok::OptClose if in_opt => break, + MTok::Open => { + *pos += 1; + if depth < MAX_NEST { + o.push_str(&math_seq(t, pos, depth + 1, false)); + } + if t.get(*pos) == Some(&MTok::Close) { + *pos += 1; + } + continue; + } + MTok::OptOpen => o.push('['), + MTok::OptClose => o.push(']'), + MTok::Char('^') | MTok::Char('_') => { + let c = if *tok == MTok::Char('^') { '^' } else { '_' }; + *pos += 1; + let a = if depth < MAX_NEST { math_arg(t, pos, depth) } else { String::new() }; + o.push(c); + o.push_str(&wrap_part(&a)); + continue; + } + MTok::Char('&') => o.push(' '), + MTok::Char('~') => o.push(' '), + MTok::Char(c) => o.push(*c), + MTok::Cmd(name) => { + *pos += 1; + let name = name.as_str(); + if depth >= MAX_NEST { + continue; + } + match name { + "frac" | "dfrac" | "tfrac" | "cfrac" => { + let a = math_arg(t, pos, depth); + let b = math_arg(t, pos, depth); + o.push_str(&format!("{}/{}", wrap_part(&a), wrap_part(&b))); + } + "binom" | "dbinom" | "tbinom" => { + let a = math_arg(t, pos, depth); + let b = math_arg(t, pos, depth); + o.push_str(&format!("({a}¦{b})")); + } + "sqrt" => { + let n = math_opt(t, pos, depth); + let a = math_arg(t, pos, depth); + match n { + Some(n) => o.push_str(&format!("√({n}&{a})")), + None => o.push_str(&format!("√({a})")), + } + } + "left" | "right" | "big" | "Big" | "bigg" | "Bigg" | "bigl" | "bigr" | "Bigl" | "Bigr" | "middle" => { + // Keep the delimiter, drop the sizing; `\left.` is no delimiter. + if t.get(*pos) == Some(&MTok::Char('.')) { + *pos += 1; + } + } + "text" | "textrm" | "textit" | "textbf" | "mathrm" | "mathit" | "mathbf" | "mathsf" | "mathtt" | "mathcal" | "mathbb" + | "mathfrak" | "boldsymbol" | "bm" | "pmb" | "operatorname" | "mbox" | "hbox" | "displaystyle" | "textstyle" | "scriptstyle" => { + if t.get(*pos) == Some(&MTok::Open) || !matches!(name, "displaystyle" | "textstyle" | "scriptstyle") { + let a = math_arg(t, pos, depth); + o.push_str(&a); + } + } + "overline" | "bar" => o.push_str(&format!("{}¯", wrap_part(&math_arg(t, pos, depth)))), + "hat" | "widehat" => o.push_str(&format!("{}̂", math_arg(t, pos, depth))), + "tilde" | "widetilde" => o.push_str(&format!("{}̃", math_arg(t, pos, depth))), + "vec" => o.push_str(&format!("{}⃗", math_arg(t, pos, depth))), + "dot" => o.push_str(&format!("{}̇", math_arg(t, pos, depth))), + "ddot" => o.push_str(&format!("{}̈", math_arg(t, pos, depth))), + "acute" => o.push_str(&format!("{}́", math_arg(t, pos, depth))), + "grave" => o.push_str(&format!("{}̀", math_arg(t, pos, depth))), + "breve" => o.push_str(&format!("{}̆", math_arg(t, pos, depth))), + "check" => o.push_str(&format!("{}̌", math_arg(t, pos, depth))), + "pmod" => { + let a = math_arg(t, pos, depth); + o.push_str(&format!(" (mod {a})")); + } + "bmod" => o.push_str(" mod "), + "begin" | "end" => { + // Inner environments (`matrix`, `cases`, `aligned`…): keep the content. + let _ = math_arg(t, pos, depth); + if name == "begin" { + let _ = math_opt(t, pos, depth); + } + } + "," | ";" | ":" | "quad" | "qquad" | " " | "enspace" | "thinspace" => o.push(' '), + "!" | "limits" | "nolimits" | "nonumber" | "notag" => {} + "\\" | "cr" => o.push(' '), + "{" | "}" | "%" | "#" | "&" | "$" | "_" => o.push_str(name), + "label" | "tag" => { + let _ = math_arg(t, pos, depth); + } + n if MATH_FUNCTIONS.contains(&n) => { + o.push_str(n); + o.push(' '); + } + n => match math_symbol(n) { + Some(c) => o.push(c), + // Linear format knows LaTeX-style control words too. + None => { + o.push('\\'); + o.push_str(n); + o.push(' '); + } + }, + } + continue; + } + } + *pos += 1; + } + o +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn math_conversions() { + for (tex, linear) in [ + (r"\frac{1}{2}", "1/2"), + (r"x_{i}^{2}", "x_i^2"), + (r"x^{10}", "x^10"), + (r"e^{i\pi}", "e^(iπ)"), + (r"\sqrt[3]{x}", "√(3&x)"), + (r"\left( a \right)", "( a )"), + (r"\sin x + \text{if } y", "sin x + if y"), + (r"a \cdot b \times c \neq d", "a ⋅ b × c ≠ d"), + (r"a \bullet b", "a • b"), + (r"x \top y \bot z", "x ⊤ y ⊥ z"), + (r"f \colon X \to Y", "f : X → Y"), + (r"\hbar \hslash", "ℏ ℏ"), + (r"\bm{v}", "v"), + (r"\acute{x} \grave{y} \breve{z} \check{w}", "x́ ỳ z̆ w̌"), + (r"a \equiv b \pmod{m}", "a ≡ b (mod m)"), + (r"a \bmod b", "a mod b"), + (r"\unknowncmd", r"\unknowncmd"), + ] { + assert_eq!(latex_to_linear(tex), linear, "{tex}"); + } + for (linear, tex) in [ + ("x=(-b±√(b^2-4ac))/(2a)", r"x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}"), + ("α ≤ β", r"\alpha \leq \beta"), + ("αβ", r"\alpha\beta"), + ("πr", r"\pi r"), + ("a • b", r"a \bullet b"), + ("x ⊤ y", r"x \top y"), + ("a_(i+1)", r"a_{i+1}"), + ("50% & #", r"50\% \& \#"), + ("√(3&x)", r"\sqrt[3]{x}"), + ] { + assert_eq!(linear_to_latex(linear), tex, "{linear}"); + } + } + + /// Unmatched and deeply nested groups convert in linear time; nothing the text says becomes a + /// TeX command (from WordCraft's cross-format tests). + #[test] + fn hostile_math_is_linear_and_carries_no_commands() { + assert_eq!(linear_to_latex(&"(".repeat(200_000)).len(), 200_000); + let nested = format!("{}x{}", "(".repeat(100_000), ")".repeat(100_000)); + assert_eq!(linear_to_latex(&nested).len(), 200_001); + let tex = linear_to_latex("\\input secret.txt \\immediate\\write18"); + assert!(!tex.contains("\\input") && !tex.contains("\\write") && tex.contains("\\backslash input"), "{tex}"); + for linear in ["a^^5cinput", "x^(^^5cinput)"] { + assert!(!linear_to_latex(linear).contains("^^"), "{linear}"); + } + } +} diff --git a/crates/math/src/lib.rs b/crates/math/src/lib.rs new file mode 100644 index 000000000..29220245f --- /dev/null +++ b/crates/math/src/lib.rs @@ -0,0 +1,58 @@ +#![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)] +//! Equations: one tree and the syntaxes it is read from and written to. +//! +//! - [`math`]: the tree ([`MNode`], [`MRun`], an argument [`Arg`] is a `Vec`), modelled on +//! the Office Math object model (ECMA-376 Part 1 §22.1), and [`Math`], an equation with its kept +//! source OMML. +//! - [`math_linear`]: the linear format (UnicodeMath, the plain text Word shows for an equation), +//! read and written ([`math::parse_linear`], [`math::to_linear`]). +//! - [`math_latex`]: LaTeX math, read and written ([`math_latex::parse_latex`], +//! [`math_latex::to_latex`]), with the named symbols of [`math_symbols`]. +//! - [`omml`]: Office Math Markup, read ([`omml::read_omath`], [`omml::read_str`]) and written +//! ([`omml::write_equation`], [`omml::write_str`]). +//! - [`mathml`]: presentation MathML, written ([`mathml::to_mathml`]) and read +//! ([`mathml::parse`], [`mathml::read`], [`mathml::to_tree`]). +//! - [`latex_text`]: LaTeX math and the linear format converted as text, keeping the source's +//! spacing, for LaTeX documents ([`latex_text::latex_to_linear`], [`latex_text::linear_to_latex`]). +//! - [`math_tree`]: the arguments of a node and a walk over every run. +//! - [`symbol_fonts`]: text in symbol fonts (Symbol, Wingdings…) as Unicode, as OMML runs and +//! Word text need it. +//! - [`Rgb`]: the colour of a run. +//! +//! Every reader is bounded (nesting [`math::MAX_DEPTH`], node budgets) and never panics on any +//! input. +//! +//! ``` +//! use craft_math::{math, math_latex, mathml, omml}; +//! +//! let tree = math::parse_linear("x=(-b±√(b^2-4ac))/2a"); +//! assert_eq!(math::to_linear(&tree), "x=(-b±√(b^2-4ac))/2a"); +//! assert!(math_latex::to_latex(&tree).contains("\\frac")); +//! +//! let eq = math::Math { nodes: tree.clone(), ..Default::default() }; +//! let xml = omml::write_str("", false, &eq, None); +//! assert_eq!(omml::read_str(&xml).map(|m| m.nodes), Some(tree.clone())); +//! +//! let ml = mathml::to_mathml(&tree, false, ""); +//! assert_eq!(mathml::parse(&ml).as_ref().map(mathml::to_tree), Some(tree)); +//! ``` + +#[cfg(doctest)] +#[doc = include_str!("../README.md")] +struct ReadmeExamples; + +pub mod latex_text; +pub mod math; +pub mod math_latex; +pub mod math_linear; +pub mod math_symbols; +pub mod math_tree; +pub mod mathml; +pub mod omml; +mod rgb; +pub mod symbol_fonts; + +pub use math::{Arg, MNode, MRun, Math, MathProps}; +pub use rgb::Rgb; diff --git a/crates/math/src/math.rs b/crates/math/src/math.rs new file mode 100644 index 000000000..dc09cd164 --- /dev/null +++ b/crates/math/src/math.rs @@ -0,0 +1,1138 @@ +//! Equations: the Office Math object model (OMML, ECMA-376 Part 1 §22.1) as a tree, its linear +//! format (UnicodeMath, the plain text Word shows for an equation) and a parser for that format. +//! +//! An equation is a list of [`MNode`]s (an *argument*); structures hold arguments of their own +//! (a fraction's numerator and denominator, a radical's degree and base…). Layout reads the tree; +//! DOCX import builds it from OMML and keeps the source XML so a saved file carries the equation +//! exactly as Word wrote it. + +use serde::{Deserialize, Serialize}; + +use crate::rgb::Rgb; + +/// A sequence of math nodes (OMML's `m:e`, `m:num`, `m:sub`…). +pub type Arg = Vec; + +/// Deepest structure nesting kept (parsers stop here; layout draws nothing deeper). +pub const MAX_DEPTH: usize = 64; + +/// Most matrix columns kept (writers pad every row to the widest, so this bounds a row's cost). +pub const MAX_MATRIX_COLS: usize = 64; + +/// Most matrix rows kept. +pub const MAX_MATRIX_ROWS: usize = 1000; + +/// An equation's structure, plus what's needed to write it back. +#[derive(Clone, Debug, PartialEq, Default, Serialize, Deserialize)] +pub struct Math { + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub nodes: Arg, + /// The source `m:oMath` element (DOCX import), written back unchanged on save. Empty for + /// equations made here. + #[serde(default, skip_serializing_if = "String::is_empty")] + pub omml: String, + /// Justification of a display equation. + #[serde(default, skip_serializing_if = "is_default")] + pub jc: MathJc, + /// Shown as its linear-format text (Equation › Convert › Linear) instead of built up. + #[serde(default, skip_serializing_if = "is_default")] + pub linear: bool, +} + +fn is_default(v: &T) -> bool { + *v == T::default() +} + +impl Math { + pub fn is_empty(&self) -> bool { + self.nodes.is_empty() + } + + /// Rough heap bytes a clone copies: every node, its argument lists and its run text. + /// Iterative, so it costs at most the size of the structure. + pub fn heap_bytes(&self) -> usize { + let mut n = self.omml.len(); + let mut todo: Vec<&MNode> = self.nodes.iter().collect(); + while let Some(node) = todo.pop() { + n = n.saturating_add(std::mem::size_of::()); + if let MNode::Run(r) = node { + n = n.saturating_add(r.text.len()).saturating_add(r.font.as_ref().map_or(0, String::len)); + } + each_arg(node, &mut |a| { + n = n.saturating_add(std::mem::size_of::()); + todo.extend(a); + }); + } + n + } +} + +/// Display equation justification (`m:oMathParaPr/m:jc`). +#[derive(Clone, Copy, Debug, PartialEq, Eq, Default, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub enum MathJc { + #[default] + CenterGroup, + Center, + Left, + Right, +} + +/// Where a display equation too wide for its line breaks at a binary operator (`m:brkBin`). +#[derive(Clone, Copy, Debug, PartialEq, Eq, Default, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub enum BrkBin { + /// The operator starts the next line. + #[default] + Before, + /// The operator ends the line. + After, + /// The operator ends the line and starts the next one again. + Repeat, +} + +/// How a minus repeats across a break when [`BrkBin::Repeat`] (`m:brkBinSub`): the operator +/// ending the line, then the one starting the next. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Default, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub enum BrkBinSub { + /// `--` + #[default] + MinusMinus, + /// `-+` + MinusPlus, + /// `+-` + PlusMinus, +} + +/// Document-wide equation options (`m:mathPr` in the settings part) that layout uses: how long +/// display equations wrap. +#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] +#[serde(default, rename_all = "camelCase")] +pub struct MathProps { + pub brk_bin: BrkBin, + pub brk_bin_sub: BrkBinSub, + /// Indent of a wrapped equation's continuation lines, points (`m:wrapIndent`). + pub wrap_indent: f32, + /// Continuation lines align right instead (`m:wrapRight`). + pub wrap_right: bool, +} + +/// `m:wrapIndent`'s default: 1440 twips, one inch. +pub const DEFAULT_WRAP_INDENT: f32 = 72.0; + +impl Default for MathProps { + fn default() -> Self { + MathProps { brk_bin: BrkBin::Before, brk_bin_sub: BrkBinSub::MinusMinus, wrap_indent: DEFAULT_WRAP_INDENT, wrap_right: false } + } +} + +/// Math run style (`m:sty`): plain, bold, italic, bold italic. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub enum MSty { + Plain, + Bold, + Italic, + BoldItalic, +} + +/// Math alphabet (`m:scr`). +#[derive(Clone, Copy, Debug, PartialEq, Eq, Default, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub enum MScr { + #[default] + Roman, + Script, + Fraktur, + DoubleStruck, + SansSerif, + Monospace, +} + +/// A run of math text (`m:r`). +#[derive(Clone, Debug, PartialEq, Default, Serialize, Deserialize)] +pub struct MRun { + pub text: String, + /// `None`: math default (letters italic, the rest upright). + #[serde(default, skip_serializing_if = "Option::is_none")] + pub sty: Option, + #[serde(default, skip_serializing_if = "is_default")] + pub scr: MScr, + /// Normal (non-math) text. + #[serde(default, skip_serializing_if = "is_default")] + pub nor: bool, + /// Literal: no automatic operator handling. + #[serde(default, skip_serializing_if = "is_default")] + pub lit: bool, + /// Font size, points. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub size: Option, + #[serde(default, skip_serializing_if = "Option::is_none")] + pub color: Option, + /// Font for normal text. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub font: Option, + /// A manual line break before this run in a display equation (`m:brk`): `Some(0)` wraps as + /// usual, `Some(n)` aligns the new line at the `n`th operator of the first line (`m:alnAt`). + #[serde(default, skip_serializing_if = "Option::is_none")] + pub brk: Option, +} + +impl MRun { + pub fn new(text: impl Into) -> MRun { + MRun { text: text.into(), ..Default::default() } + } + pub fn plain(text: impl Into) -> MRun { + MRun { text: text.into(), sty: Some(MSty::Plain), ..Default::default() } + } +} + +#[derive(Clone, Copy, Debug, PartialEq, Eq, Default, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub enum FracKind { + /// Stacked with a rule. + #[default] + Bar, + /// Skewed (num ⁄ den). + Skewed, + /// Linear (num/den). + Linear, + /// Stacked without a rule. + NoBar, +} + +#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub enum ScriptKind { + Sup, + Sub, + SubSup, + /// Pre-scripts (`m:sPre`). + Pre, +} + +/// Where an n-ary operator's limits go. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub enum LimLoc { + /// Under and over the operator. + UndOvr, + /// As sub- and superscripts. + SubSup, +} + +/// Column justification in a matrix. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Default, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub enum ColJc { + #[default] + Center, + Left, + Right, +} + +/// A math node. +#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] +#[serde(tag = "t", rename_all = "camelCase")] +pub enum MNode { + Run(MRun), + /// `m:f`. + Frac { + #[serde(default)] + kind: FracKind, + num: Arg, + den: Arg, + }, + /// `m:sSup`, `m:sSub`, `m:sSubSup`, `m:sPre`. + Script { + kind: ScriptKind, + base: Arg, + #[serde(default)] + sub: Arg, + #[serde(default)] + sup: Arg, + }, + /// `m:rad`. + Rad { + #[serde(default)] + deg: Arg, + #[serde(default)] + deg_hide: bool, + e: Arg, + }, + /// `m:nary`: ∑ ∫ ∏ … with limits and an operand. + Nary { + chr: char, + /// `None`: Word's default (integrals take sub/sup limits, the rest under/over). + #[serde(default)] + lim_loc: Option, + #[serde(default)] + grow: bool, + #[serde(default)] + sub_hide: bool, + #[serde(default)] + sup_hide: bool, + #[serde(default)] + sub: Arg, + #[serde(default)] + sup: Arg, + e: Arg, + }, + /// `m:d`: delimiters around elements separated by `sep`. + Delim { + /// `None` = no delimiter. + beg: Option, + end: Option, + #[serde(default)] + sep: Option, + /// Delimiters grow to the content (Word's default). + #[serde(default = "yes")] + grow: bool, + /// Grow to match the content exactly rather than centred on the math axis. + #[serde(default)] + shp_match: bool, + elems: Vec, + }, + /// `m:func`: function name applied to an argument (sin x). + Func { + name: Arg, + e: Arg, + }, + /// `m:limLow` / `m:limUpp`. + Lim { + upper: bool, + e: Arg, + lim: Arg, + }, + /// `m:acc`: accent over the base. + Acc { + chr: char, + e: Arg, + }, + /// `m:bar`: overbar or underbar. + Bar { + top: bool, + e: Arg, + }, + /// `m:borderBox`. `hide`: top, bottom, left, right. `strike`: horizontal, vertical, + /// bottom-left→top-right, top-left→bottom-right. + BorderBox { + #[serde(default)] + hide: [bool; 4], + #[serde(default)] + strike: [bool; 4], + e: Arg, + }, + /// `m:box`. + Boxed { + e: Arg, + }, + /// `m:groupChr`: a stretched character (brace, arrow) under or over the base. + GroupChr { + chr: char, + top: bool, + e: Arg, + }, + /// `m:eqArr`: rows aligned at `&`. + EqArr { + rows: Vec, + }, + /// `m:m`. + Matrix { + rows: Vec>, + #[serde(default)] + col_jc: Vec, + }, + /// `m:phant`. + Phant { + #[serde(default = "yes")] + show: bool, + #[serde(default)] + zero_wid: bool, + #[serde(default)] + zero_asc: bool, + #[serde(default)] + zero_desc: bool, + e: Arg, + }, +} + +fn yes() -> bool { + true +} + +/// A row holds an equation-number mark (`#`) in a top-level run. +pub fn has_number_mark(row: &[MNode]) -> bool { + row.iter().any(|n| matches!(n, MNode::Run(r) if !r.lit && !r.nor && r.text.contains('#'))) +} + +/// Integral signs (their limits default to sub/sup positions). +pub fn is_integral(c: char) -> bool { + matches!(c, '∫' | '∬' | '∭' | '∮' | '∯' | '∰' | '∱' | '∲' | '∳' | '⨌') +} + +/// Characters that take n-ary operator form in the linear format. +pub fn is_nary_char(c: char) -> bool { + is_integral(c) || matches!(c, '∑' | '∏' | '∐' | '⋃' | '⋂' | '⋁' | '⋀' | '⨁' | '⨂' | '⨀' | '⨄' | '⨆') +} + +/// Mathematical alphanumeric for `c` in a style and alphabet (Unicode block U+1D400). +pub fn math_alnum(c: char, bold: bool, italic: bool, scr: MScr) -> char { + let off = |base: u32, k: u32| char::from_u32(base + k).unwrap_or(c); + let upper = c.is_ascii_uppercase(); + let lower = c.is_ascii_lowercase(); + if upper || lower { + let k = if upper { c as u32 - 'A' as u32 } else { c as u32 - 'a' as u32 }; + // Letters that live in the Letterlike Symbols block. + let hole = |table: &[(char, char)]| table.iter().find(|(f, _)| *f == c).map(|(_, t)| *t); + let (base_u, base_l) = match (scr, bold, italic) { + (MScr::Roman, false, false) => return c, + (MScr::Roman, true, false) => (0x1D400, 0x1D41A), + (MScr::Roman, false, true) => { + if c == 'h' { + return '\u{210E}'; + } + (0x1D434, 0x1D44E) + } + (MScr::Roman, true, true) => (0x1D468, 0x1D482), + (MScr::Script, false, _) => { + if let Some(t) = hole(&[ + ('B', 'ℬ'), + ('E', 'ℰ'), + ('F', 'ℱ'), + ('H', 'ℋ'), + ('I', 'ℐ'), + ('L', 'ℒ'), + ('M', 'ℳ'), + ('R', 'ℛ'), + ('e', 'ℯ'), + ('g', 'ℊ'), + ('o', 'ℴ'), + ]) { + return t; + } + (0x1D49C, 0x1D4B6) + } + (MScr::Script, true, _) => (0x1D4D0, 0x1D4EA), + (MScr::Fraktur, false, _) => { + if let Some(t) = hole(&[('C', 'ℭ'), ('H', 'ℌ'), ('I', 'ℑ'), ('R', 'ℜ'), ('Z', 'ℨ')]) { + return t; + } + (0x1D504, 0x1D51E) + } + (MScr::Fraktur, true, _) => (0x1D56C, 0x1D586), + (MScr::DoubleStruck, _, _) => { + if let Some(t) = hole(&[('C', 'ℂ'), ('H', 'ℍ'), ('N', 'ℕ'), ('P', 'ℙ'), ('Q', 'ℚ'), ('R', 'ℝ'), ('Z', 'ℤ')]) { + return t; + } + (0x1D538, 0x1D552) + } + (MScr::SansSerif, false, false) => (0x1D5A0, 0x1D5BA), + (MScr::SansSerif, true, false) => (0x1D5D4, 0x1D5EE), + (MScr::SansSerif, false, true) => (0x1D608, 0x1D622), + (MScr::SansSerif, true, true) => (0x1D63C, 0x1D656), + (MScr::Monospace, _, _) => (0x1D670, 0x1D68A), + }; + return off(if upper { base_u } else { base_l }, k); + } + if c.is_ascii_digit() { + let k = c as u32 - '0' as u32; + return match (scr, bold) { + (MScr::Roman, true) => off(0x1D7CE, k), + (MScr::DoubleStruck, _) => off(0x1D7D8, k), + (MScr::SansSerif, false) => off(0x1D7E2, k), + (MScr::SansSerif, true) => off(0x1D7EC, k), + (MScr::Monospace, _) => off(0x1D7F6, k), + _ => c, + }; + } + // Greek (roman alphabet only). + if scr == MScr::Roman && (bold || italic) { + let (cap, small) = match (bold, italic) { + (true, false) => (0x1D6A8, 0x1D6C2), + (false, true) => (0x1D6E2, 0x1D6FC), + _ => (0x1D71C, 0x1D736), + }; + let u = c as u32; + if (0x391..=0x3A9).contains(&u) && u != 0x3A2 { + return off(cap, u - 0x391); + } + if (0x3B1..=0x3C9).contains(&u) { + return off(small, u - 0x3B1); + } + let extra = match c { + '∂' => Some(25), + 'ϵ' => Some(26), + 'ϑ' => Some(27), + 'ϰ' => Some(28), + 'ϕ' => Some(29), + 'ϱ' => Some(30), + 'ϖ' => Some(31), + _ => None, + }; + if let Some(e) = extra + && italic + { + return off(small, e); + } + } + c +} + +// --------------------------------------------------------------------------------------------- +// Linear format out. + +/// The equation as linear-format text (`x=(-b±√(b^2-4ac))/2a`). +pub fn to_linear(nodes: &[MNode]) -> String { + let mut s = String::new(); + lin_arg(nodes, &mut s, 0); + s +} + +fn lin_arg(a: &[MNode], s: &mut String, depth: usize) { + if depth > MAX_DEPTH { + return; + } + for (i, n) in a.iter().enumerate() { + lin_node(n, s, depth + 1); + // A bare script or limit ends at a space: a letter, digit or period after it is its own item. + if matches!(n, MNode::Script { kind, .. } if *kind != ScriptKind::Pre) || matches!(n, MNode::Lim { .. }) { + let ends_bare = s.chars().next_back().is_some_and(|c| c.is_alphanumeric() || c == '.'); + if ends_bare && a.get(i + 1).and_then(first_lin_char).is_some_and(|c| c.is_alphanumeric() || c == '.') { + s.push(' '); + } + } + } +} + +/// The first character `n` is written with, when that is cheap to tell (letters and digits). +fn first_lin_char(n: &MNode) -> Option { + match n { + MNode::Run(r) => r.text.chars().next(), + MNode::Func { name, .. } => name.first().and_then(first_lin_char), + MNode::Script { kind, base, .. } if *kind != ScriptKind::Pre => base.first().and_then(first_lin_char), + MNode::Lim { e, .. } => e.first().and_then(first_lin_char), + MNode::Frac { num, .. } => num.first().and_then(first_lin_char), + _ => None, + } +} + +/// An argument as an operand: bare when it's a single simple atom, parenthesised otherwise. +fn lin_operand(a: &[MNode], s: &mut String, depth: usize) { + let mut inner = String::new(); + lin_arg(a, &mut inner, depth); + let simple = match a { + [MNode::Run(r)] => { + let mut cs = r.text.chars(); + match (cs.next(), cs.next()) { + (Some(c), None) => !"+-−=/^_ ".contains(c), + _ => r.text.chars().all(|c| c.is_alphanumeric() || c == '.'), + } + } + [MNode::Delim { .. }] => true, + _ => false, + }; + if simple && !inner.is_empty() { + s.push_str(&inner); + } else { + s.push('('); + s.push_str(&inner); + s.push(')'); + } +} + +/// A script or limit operand. The parser reads a run of letters and digits up to the next space or +/// operator, so `V_dd` is written bare as Word's Linear format shows it (`V_(dd)` reads back the same). +fn lin_script(a: &[MNode], s: &mut String, depth: usize) { + // Bare only when the parser reads the whole run back, in the same style. + if let [MNode::Run(r)] = a + && r.text.chars().nth(1).is_some() + { + let upright_name = r.sty == Some(MSty::Plain) && crate::math_linear::FUNCTION_NAMES.contains(&r.text.as_str()); + let number = r.text.starts_with(|c: char| c.is_ascii_digit()) && r.text.chars().all(|c| c.is_alphanumeric() || c == '.'); + let word = r.text.starts_with(char::is_alphabetic) && r.text.chars().all(char::is_alphanumeric); + let upright_other = r.sty == Some(MSty::Plain) && !upright_name; + if upright_other || (!number && !word) { + s.push('('); + s.push_str(&r.text); + s.push(')'); + return; + } + } + lin_operand(a, s, depth); +} + +fn lin_node(n: &MNode, s: &mut String, depth: usize) { + match n { + MNode::Run(r) => s.push_str(&r.text), + MNode::Frac { kind, num, den } => { + lin_operand(num, s, depth); + s.push(match kind { + FracKind::Skewed => '⁄', + FracKind::Linear => '∕', + FracKind::NoBar => '¦', + FracKind::Bar => '/', + }); + lin_operand(den, s, depth); + } + MNode::Script { kind, base, sub, sup } => { + if *kind == ScriptKind::Pre { + s.push('_'); + lin_script(sub, s, depth); + s.push('^'); + lin_script(sup, s, depth); + s.push('▒'); + lin_operand(base, s, depth); + return; + } + lin_operand(base, s, depth); + if matches!(kind, ScriptKind::Sub | ScriptKind::SubSup) { + s.push('_'); + lin_script(sub, s, depth); + } + if matches!(kind, ScriptKind::Sup | ScriptKind::SubSup) { + s.push('^'); + lin_script(sup, s, depth); + } + } + MNode::Rad { deg, deg_hide, e } => { + if *deg_hide || deg.is_empty() { + s.push('√'); + lin_operand(e, s, depth); + } else { + s.push_str("√("); + lin_arg(deg, s, depth); + s.push('&'); + lin_arg(e, s, depth); + s.push(')'); + } + } + MNode::Nary { chr, sub_hide, sup_hide, sub, sup, e, .. } => { + s.push(*chr); + if !sub_hide && !sub.is_empty() { + s.push('_'); + lin_script(sub, s, depth); + } + if !sup_hide && !sup.is_empty() { + s.push('^'); + lin_script(sup, s, depth); + } + s.push('▒'); + lin_operand(e, s, depth); + } + MNode::Delim { beg, end, elems, .. } => { + // A standard pair writes as itself; anything else uses explicit `├X … Y┤`. + let pair = matches!((beg, end), (Some(b), Some(e)) if crate::math_linear::closer(*b) == Some(*e)); + let invisible = beg.is_none() && end.is_none(); + if pair { + s.extend(*beg); + } else if invisible { + s.push('〖'); + } else { + s.push('├'); + s.extend(*beg); + } + for (i, e) in elems.iter().enumerate() { + if i > 0 { + s.push('│'); + } + lin_arg(e, s, depth); + } + if pair { + s.extend(*end); + } else if invisible { + s.push('〗'); + } else { + s.extend(*end); + s.push('┤'); + } + } + MNode::Func { name, e } => { + lin_arg(name, s, depth); + s.push('\u{2061}'); + lin_operand(e, s, depth); + } + MNode::Lim { upper, e, lim } => { + lin_operand(e, s, depth); + s.push(if *upper { '┴' } else { '┬' }); + lin_script(lim, s, depth); + } + MNode::Acc { chr, e } => { + lin_operand(e, s, depth); + s.push(*chr); + } + MNode::Bar { top, e } => { + s.push(if *top { '¯' } else { '▁' }); + lin_operand(e, s, depth); + } + MNode::BorderBox { e, .. } => { + s.push('▭'); + lin_operand(e, s, depth); + } + MNode::Boxed { e } => { + s.push('□'); + lin_operand(e, s, depth); + } + MNode::GroupChr { chr, e, .. } => { + s.push(*chr); + lin_operand(e, s, depth); + } + // A numbered equation (`E=mc^2#(1)`) is written as its one row. + MNode::EqArr { rows } if rows.len() == 1 && rows.first().is_some_and(|r| has_number_mark(r)) => { + if let Some(r) = rows.first() { + lin_arg(r, s, depth); + } + } + MNode::EqArr { rows } => { + s.push_str("█("); + for (i, r) in rows.iter().enumerate() { + if i > 0 { + s.push('@'); + } + lin_arg(r, s, depth); + } + s.push(')'); + } + MNode::Matrix { rows, .. } => { + s.push_str("■("); + for (i, r) in rows.iter().enumerate() { + if i > 0 { + s.push('@'); + } + for (j, c) in r.iter().enumerate() { + if j > 0 { + s.push('&'); + } + lin_arg(c, s, depth); + } + } + s.push(')'); + } + MNode::Phant { e, .. } => { + s.push('⟡'); + lin_operand(e, s, depth); + } + } +} + +// --------------------------------------------------------------------------------------------- +// Linear format in. + +/// Parse linear-format text into nodes ([`crate::math_linear`]). Never fails: what isn't +/// understood stays as text. +pub fn parse_linear(s: &str) -> Arg { + crate::math_linear::parse(s) +} + +pub use crate::math_linear::FUNCTION_NAMES; + +/// Spacing class of a math character (TeX's atom classes). +#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)] +pub enum MClass { + #[default] + Ord, + Op, + Bin, + Rel, + Open, + Close, + Punct, + Inner, +} + +/// The spacing class of a character in an equation. +pub fn math_class(c: char) -> MClass { + match c { + '+' | '−' | '-' | '±' | '∓' | '×' | '÷' | '·' | '∙' | '∗' | '*' | '∘' | '⊕' | '⊖' | '⊗' | '⊘' | '⊙' | '⊚' | '⊛' | '∪' | '∩' | '∧' | '∨' + | '∖' | '⋅' | '⋆' | '⊎' | '⊓' | '⊔' | '⋄' | '⊞' | '⊟' | '⊠' | '⊡' | '⋉' | '⋊' | '⋋' | '⋌' | '⋎' | '⋏' | '⋒' | '⋓' | '∔' | '∸' | '≀' | '⨿' + | '⊼' | '⊻' | '⊽' => MClass::Bin, + '=' | '<' | '>' | '≤' | '≥' | '≠' | '≈' | '≡' | '≢' | '∼' | '≃' | '≅' | '≐' | '∝' | '≪' | '≫' | '≺' | '≻' | '≼' | '≽' | '⊂' | '⊃' | '⊆' + | '⊇' | '⊄' | '⊅' | '⊈' | '⊉' | '⊊' | '⊋' | '∈' | '∉' | '∋' | '∌' | '⊥' | '∥' | '∦' | '∣' | '∤' | '≔' | '≕' | '≝' | '≜' | '≞' | '≟' | '→' + | '←' | '↔' | '⇒' | '⇐' | '⇔' | '↦' | '⟼' | '⟶' | '⟵' | '⟷' | '⟹' | '⟸' | '⟺' | '↑' | '↓' | '↕' | '⇑' | '⇓' | '⇕' | '↗' | '↘' | '↙' | '↖' + | '⊢' | '⊣' | '⊨' | '⊩' | '⊪' | '⊬' | '⊭' | '⊮' | '⊯' | '≲' | '≳' | '≍' | '⊏' | '⊐' | '⊑' | '⊒' | '⋢' | '⋣' | '≶' | '≷' | '≮' | '≯' | '≰' + | '≱' | '≦' | '≧' | '⩽' | '⩾' | ':' | '∶' | '∷' | '∺' | '∻' | '≗' | '≙' | '≚' | '≑' | '≒' | '≓' | '≖' | '⇌' | '⇋' | '⇄' | '⇆' | '⇇' | '⇉' + | '⇈' | '⇊' | '↪' | '↩' | '↼' | '↽' | '⇀' | '⇁' | '↿' | '↾' | '⇃' | '⇂' | '↶' | '↷' | '↺' | '↻' | '⊸' | '↜' | '↝' | '↞' | '↠' | '↢' | '↣' + | '↫' | '↬' | '↭' | '⇚' | '⇛' | '↰' | '↱' | '⇝' | '≁' | '≄' | '≉' | '≇' | '≭' | '≨' | '≩' | '⊀' | '⊁' | '⋠' | '⋡' | '⋦' | '⋧' | '⋨' | '⋩' + | '⋪' | '⋫' | '⋬' | '⋭' | '⋈' | '∴' | '∵' | '≏' | '≎' | '⋘' | '⋙' | '⊲' | '⊳' | '⊴' | '⊵' | '⋐' | '⋑' => { + MClass::Rel + } + '(' | '[' | '{' | '⟨' | '⌈' | '⌊' | '⟦' | '〈' => MClass::Open, + ')' | ']' | '}' | '⟩' | '⌉' | '⌋' | '⟧' | '〉' | '!' => MClass::Close, + ',' | ';' => MClass::Punct, + c if is_nary_char(c) => MClass::Op, + _ => MClass::Ord, + } +} + +/// Merge adjacent runs with the same formatting; recurse into every structure. +pub fn merge_runs(a: Arg) -> Arg { + let mut out: Arg = Vec::with_capacity(a.len()); + for n in a { + let n = match n { + MNode::Run(r) => { + if let Some(MNode::Run(prev)) = out.last_mut() + && prev.sty == r.sty + && prev.scr == r.scr + && prev.nor == r.nor + && prev.lit == r.lit + && prev.size == r.size + && prev.color == r.color + && prev.font == r.font + && r.brk.is_none() + { + prev.text.push_str(&r.text); + continue; + } + MNode::Run(r) + } + other => crate::math_linear::map_args(other, &merge_runs), + }; + out.push(n); + } + out +} + +/// Deepest node (a leaf counts 1) the parsers wrap further. Half of [`MAX_DEPTH`]: serde_json +/// stops reading at 128 nested containers and a node costs two (object and array). +pub const WRAP_DEPTH: usize = MAX_DEPTH / 2; + +/// Calls `f` with every argument of `n`. +fn each_arg<'a>(n: &'a MNode, f: &mut impl FnMut(&'a [MNode])) { + match n { + MNode::Run(_) => {} + MNode::Frac { num, den, .. } => { + f(num); + f(den); + } + MNode::Script { base, sub, sup, .. } => { + f(base); + f(sub); + f(sup); + } + MNode::Rad { deg, e, .. } => { + f(deg); + f(e); + } + MNode::Nary { sub, sup, e, .. } => { + f(sub); + f(sup); + f(e); + } + MNode::Delim { elems, .. } => elems.iter().for_each(|a| f(a)), + MNode::Func { name, e } => { + f(name); + f(e); + } + MNode::Lim { e, lim, .. } => { + f(e); + f(lim); + } + MNode::Acc { e, .. } + | MNode::Bar { e, .. } + | MNode::BorderBox { e, .. } + | MNode::Boxed { e } + | MNode::GroupChr { e, .. } + | MNode::Phant { e, .. } => f(e), + MNode::EqArr { rows } => rows.iter().for_each(|a| f(a)), + MNode::Matrix { rows, .. } => rows.iter().flatten().for_each(|a| f(a)), + } +} + +/// `n` is already nested too deeply to be wrapped in another structure. The parsers use this so +/// `x^1^1^1…` stays shallow (a left-nested tree 10 000 deep overflows the stack in `Clone`, +/// `Drop`, `PartialEq` and serde). Iterative, stops at the first too-deep path; costs at most the +/// size of `n`, which the parsers' input caps bound. +pub fn too_deep(n: &MNode) -> bool { + let mut stack: Vec<(&MNode, usize)> = vec![(n, 1)]; + while let Some((n, d)) = stack.pop() { + if d >= WRAP_DEPTH { + return true; + } + each_arg(n, &mut |a| stack.extend(a.iter().map(|c| (c, d + 1)))); + } + false +} + +/// Any of `a` is too deep to be wrapped ([`too_deep`]). +pub fn any_too_deep(a: &[MNode]) -> bool { + a.iter().any(too_deep) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn run(t: &str) -> MNode { + MNode::Run(MRun::new(t)) + } + + #[test] + fn quadratic_formula_parses_into_structures() { + let n = parse_linear("x=(-b±√(b^2-4ac))/2a"); + assert_eq!(n.len(), 2, "{n:#?}"); + assert_eq!(n[0], run("x=")); + let MNode::Frac { num, den, .. } = &n[1] else { panic!("{n:#?}") }; + assert_eq!(den, &vec![run("2a")]); + assert!(num.iter().any(|m| matches!(m, MNode::Rad { .. })), "{num:#?}"); + let MNode::Rad { e, .. } = num.iter().find(|m| matches!(m, MNode::Rad { .. })).unwrap() else { panic!() }; + assert!(matches!(e.first(), Some(MNode::Script { kind: ScriptKind::Sup, .. })), "{e:#?}"); + } + + #[test] + fn scripts_and_nary() { + let n = parse_linear("∑_(i=1)^n▒i^2"); + let MNode::Nary { chr, sub, sup, e, .. } = &n[0] else { panic!("{n:#?}") }; + assert_eq!(*chr, '∑'); + assert_eq!(sub, &vec![run("i=1")]); + assert_eq!(sup, &vec![run("n")]); + assert!(matches!(e.first(), Some(MNode::Script { .. }))); + let n = parse_linear("x_i^2"); + assert!(matches!(&n[0], MNode::Script { kind: ScriptKind::SubSup, .. }), "{n:#?}"); + } + + #[test] + fn functions_and_matrices() { + let n = parse_linear("sin x"); + assert!(matches!(&n[0], MNode::Func { .. }), "{n:#?}"); + let n = parse_linear("■(a&b@c&d)"); + let MNode::Matrix { rows, .. } = &n[0] else { panic!("{n:#?}") }; + assert_eq!(rows.len(), 2); + assert_eq!(rows[0].len(), 2); + } + + #[test] + fn linear_round_trip_keeps_structure() { + for s in [ + "x=(-b±√(b^2-4ac))/2a", + "∑_(i=1)^n▒i", + "a/b+c", + "E=mc^2", + "√(3&x)", + "├]a[┤", + "{█(x@y)┤", + "|x|+‖v‖", + "⏞(a+b)┴k", + "_1^n▒Y", + "sin^(−1)⁡x", + "lim┬(n→∞)⁡a_n", + "A⃗+x̂", + "▭(a)+¯(b)+▁(c)", + "(a│b)", + "E=mc^2#(1)", + ] { + let n = parse_linear(s); + let back = parse_linear(&to_linear(&n)); + assert_eq!(n, back, "{s} → {}", to_linear(&n)); + } + } + + //T1 + /// Deepest nesting of `a` (a leaf counts 1), without recursion. + fn depth_of(a: &[MNode]) -> usize { + let mut best = 0; + let mut stack: Vec<(&MNode, usize)> = a.iter().map(|n| (n, 1)).collect(); + while let Some((n, d)) = stack.pop() { + best = best.max(d); + each_arg(n, &mut |a| stack.extend(a.iter().map(|c| (c, d + 1)))); + } + best + } + + /// Run `f` on a thread with a stack far below the 8 MB of a main thread (#1456). + fn on_small_stack(f: impl FnOnce() + Send + 'static) { + std::thread::Builder::new().stack_size(512 * 1024).spawn(f).unwrap().join().unwrap(); + } + + #[test] + fn deeply_chained_input_stays_shallow() { + on_small_stack(|| { + let cases: Vec<(&str, Arg)> = vec![ + ("x^1^1…", parse_linear(&format!("x{}", "^1".repeat(9999)))), + ("a/a/a…", parse_linear(&format!("a{}", "/a".repeat(9999)))), + ("accents", parse_linear(&format!("x{}", "\u{302}".repeat(9999)))), + ("limits", parse_linear(&format!("x{}", "┬a".repeat(9000)))), + ("(a b)^1^1…", parse_linear(&format!("(a b){}", "^1".repeat(9000)))), + ("latex x^1^1…", crate::math_latex::parse_latex(&format!("x{}", "^1".repeat(9999)))), + ("latex \\sum…", crate::math_latex::parse_latex(&"\\sum".repeat(5000))), + ("latex \\sin x^1…", crate::math_latex::parse_latex(&format!("\\sin x{}", "^1".repeat(9000)))), + ]; + for (name, n) in cases { + assert!(!n.is_empty(), "{name}"); + assert!(depth_of(&n) <= 70, "{name}: depth {}", depth_of(&n)); + let copy = n.clone(); + assert_eq!(copy, n, "{name}"); + let _ = to_linear(&n); + let _ = crate::math_latex::to_latex(&n); + let json = serde_json::to_string(&n).unwrap(); + let back: Arg = serde_json::from_str(&json).unwrap(); + assert_eq!(back, n, "{name}"); + } + }); + } + + #[test] + fn ordinary_nesting_is_still_built() { + // Well below the cap: scripts, fractions and operators still wrap. + let n = parse_linear(&format!("x{}", "^1".repeat(10))); + assert_eq!(depth_of(&n), 11, "{n:#?}"); + let n = crate::math_latex::parse_latex(r"\sum_{i}\sum_{j}a_{ij}"); + assert!(matches!(&n[0], MNode::Nary { e, .. } if matches!(e.first(), Some(MNode::Nary { .. }))), "{n:#?}"); + } + + //T2 + #[test] + fn latex_text_escapes_what_latex_reads_as_markup() { + for text in ["a}b\\c", "{x}", "50% of #1", "a_b&c$d~e^f", "\\", "\\alpha", "\\{"] { + let n = vec![MNode::Run(MRun { text: text.into(), nor: true, sty: Some(MSty::Plain), ..Default::default() })]; + let tex = crate::math_latex::to_latex(&n); + assert_eq!(crate::math_latex::parse_latex(&tex), n, "{text:?} → {tex}"); + } + let n = vec![MNode::Run(MRun::new("a\\b"))]; + assert_eq!(crate::math_latex::parse_latex(&crate::math_latex::to_latex(&n)), n); + } + + //T3 + #[test] + fn latex_runs_merge_inside_every_structure() { + use crate::math_latex::parse_latex; + for (tex, lin) in [(r"\overline{ab}", "¯(ab)"), (r"\underline{ab}", "▁(ab)"), (r"\boxed{ab}", "▭(ab)"), (r"\phantom{ab}", "⟡(ab)")] { + assert_eq!(parse_latex(tex), parse_linear(lin), "{tex}"); + } + let n = parse_latex(r"\begin{matrix}a b&c d\\e f&g\end{matrix}"); + let MNode::Matrix { rows, .. } = &n[0] else { panic!("{n:#?}") }; + assert!(rows.iter().flatten().all(|c| c.len() == 1), "{rows:#?}"); + let n = parse_latex(r"\hat{ab}\underbrace{ab}\underset{ab}{cd}"); + let runs = |a: &Arg| a.iter().filter(|n| matches!(n, MNode::Run(_))).count(); + assert!(matches!(&n[0], MNode::Acc { e, .. } if runs(e) == 1), "{n:#?}"); + assert!(matches!(&n[1], MNode::GroupChr { e, .. } if runs(e) == 1), "{n:#?}"); + assert!(matches!(&n[2], MNode::Lim { e, lim, .. } if runs(e) == 1 && runs(lim) == 1), "{n:#?}"); + } + + #[test] + fn multi_letter_scripts_round_trip() { + // Word for Mac 16.113.4 (#1609): a script is the whole run up to a space or operator, and Word's + // Linear format shows it bare (`V_dd`); the parenthesised form reads back identically. + let script = |kind, sub: &str, sup: &str| MNode::Script { kind, base: vec![run("V")], sub: parse_linear(sub), sup: parse_linear(sup) }; + for n in [ + vec![script(ScriptKind::Sub, "dd", "")], + vec![script(ScriptKind::Sup, "", "ab")], + vec![script(ScriptKind::SubSup, "in", "2")], + vec![MNode::Nary { + chr: '∑', + lim_loc: None, + grow: false, + sub_hide: false, + sup_hide: false, + sub: vec![run("ij")], + sup: vec![run("n")], + e: vec![run("x")], + }], + vec![MNode::Lim { upper: false, e: vec![run("⟶")], lim: vec![run("yields")] }], + ] { + assert_eq!(parse_linear(&to_linear(&n)), n, "{}", to_linear(&n)); + } + // Numbers and single letters stay bare. + assert_eq!(to_linear(&[script(ScriptKind::SubSup, "10", "2.5")]), "V_10^2.5"); + assert_eq!(to_linear(&[script(ScriptKind::Sub, "d", "")]), "V_d"); + assert_eq!(to_linear(&[script(ScriptKind::Sub, "dd", "")]), "V_dd"); + assert_eq!(to_linear(&[script(ScriptKind::Sup, "", "ab")]), "V^ab"); + } + + #[test] + fn multi_letter_script_operands_follow_word() { + // #1609, Word for Mac 16.113.4: `V_dd` and `V_(dd)` build up the same; `dd` is all subscript. + let sub_dd = MNode::Script { kind: ScriptKind::Sub, base: vec![run("V")], sub: vec![run("dd")], sup: vec![] }; + assert_eq!(parse_linear("V_dd"), vec![sub_dd.clone()]); + assert_eq!(parse_linear("V_(dd)"), vec![sub_dd]); + let sup_ab = MNode::Script { kind: ScriptKind::Sup, base: vec![run("x")], sub: vec![], sup: vec![run("ab")] }; + assert_eq!(parse_linear("x^ab"), vec![sup_ab.clone()]); + assert_eq!(parse_linear("x^(ab)"), vec![sup_ab]); + // Delimiters still end the operand. + let both = MNode::Script { kind: ScriptKind::SubSup, base: vec![run("x")], sub: vec![run("i")], sup: vec![run("2")] }; + assert_eq!(parse_linear("x_i^2"), vec![both]); + let a_i = MNode::Script { kind: ScriptKind::Sub, base: vec![run("a")], sub: vec![run("i")], sup: vec![] }; + assert_eq!(parse_linear("a_i b"), vec![a_i, run("b")]); + let both2 = MNode::Script { kind: ScriptKind::SubSup, base: vec![run("x")], sub: vec![run("ij")], sup: vec![run("kl")] }; + assert_eq!(parse_linear("x_ij^kl"), vec![both2]); + // Round trip is Word's bare form. + assert_eq!(to_linear(&parse_linear("V_(dd)")), "V_dd"); + } + + #[test] + fn a_bare_script_does_not_absorb_what_follows() { + // #1609 review: `x_i` then `y` must not read back as x with subscript `iy`. + let sc = + |kind, base: &str, sub: &str, sup: &str| MNode::Script { kind, base: vec![run(base)], sub: parse_linear(sub), sup: parse_linear(sup) }; + let sin_x = MNode::Func { name: vec![MNode::Run(MRun::plain("sin"))], e: vec![run("x")] }; + let lim = MNode::Lim { upper: false, e: vec![run("a")], lim: vec![run("n")] }; + for n in [ + vec![sc(ScriptKind::Sub, "x", "i", ""), run("y")], + vec![sc(ScriptKind::Sub, "a", "i", ""), sc(ScriptKind::Sub, "b", "j", "")], + vec![sc(ScriptKind::Sup, "x", "", "2"), run("y")], + vec![sc(ScriptKind::Sup, "x", "", "2"), run("3")], + vec![sc(ScriptKind::Sub, "x", "i", ""), sin_x], + vec![lim.clone(), run("y")], + vec![sc(ScriptKind::Sub, "x", "ab", ""), run("y")], + vec![sc(ScriptKind::Sub, "x", "i", ""), run(".5")], + ] { + let lin = to_linear(&n); + assert_eq!(parse_linear(&lin), n, "{lin}"); + } + assert_eq!(to_linear(&[sc(ScriptKind::Sub, "x", "i", ""), run("y")]), "x_i y"); + // Nothing extra when the script already ends in a bracket or a symbol follows. + assert_eq!(to_linear(&[sc(ScriptKind::Sub, "x", "i", ""), run("+")]), "x_i+"); + } + + #[test] + fn a_function_name_in_a_script_stays_upright() { + // Word for Mac (#1609): `x_max` and `x_(max)` both give an upright function name. + let up = vec![MNode::Script { kind: ScriptKind::Sub, base: vec![run("x")], sub: vec![MNode::Run(MRun::plain("max"))], sup: vec![] }]; + assert_eq!(parse_linear("x_max"), up); + assert_eq!(parse_linear("x_(max)"), up); + assert_eq!(parse_linear(&to_linear(&up)), up, "{}", to_linear(&up)); + // Other upright text is not a function name: it keeps its parentheses. + let other = vec![MNode::Script { kind: ScriptKind::Sub, base: vec![run("x")], sub: vec![MNode::Run(MRun::plain("ab"))], sup: vec![] }]; + assert_eq!(to_linear(&other), "x_(ab)"); + } + + #[test] + fn digits_then_letters_continue_a_script() { + // Word for Mac (#1609): a script runs to a space or operator, so `x_2a` is subscript "2a". + let sub = |t: &str| vec![MNode::Script { kind: ScriptKind::Sub, base: vec![run("x")], sub: vec![run(t)], sup: vec![] }]; + assert_eq!(parse_linear("x_2a"), sub("2a")); + assert_eq!(parse_linear("x_a2"), sub("a2")); + assert_eq!(parse_linear("x_αβ"), sub("αβ")); + assert_eq!(parse_linear("x_10"), sub("10")); + assert_eq!(parse_linear("x_2.5"), sub("2.5")); + assert_eq!(to_linear(&sub("2a")), "x_2a"); + assert_eq!(parse_linear(&to_linear(&sub("2a"))), sub("2a")); + } + + #[test] + fn hostile_linear_never_panics() { + for s in ["", "/", "^", "_", "√", "∑", "((((", "))))", "■(", "█(@@&&", "a/", "/b", "^^^__", "√(&)", "∫_^▒", "lim_", "sin"] { + let _ = to_linear(&parse_linear(s)); + } + let deep = "(".repeat(5000) + &")".repeat(5000); + let _ = parse_linear(&deep); + let deep = "√".repeat(3000); + let _ = parse_linear(&deep); + } + + #[test] + fn a_long_run_of_letters_parses_in_linear_time() { + // Each letter that doesn't start a function name used to rescan (and copy) the rest of + // the run, so a 20,000-letter equation did 200 million steps. (No wall-clock assert: a + // loaded runner would fail it; a regression shows as a slow test.) + for _ in 0..5 { + let e = parse_linear(&"x".repeat(30_000)); + assert!(matches!(e.as_slice(), [MNode::Run(r)] if r.text.len() == 20_000), "{:?}", e.len()); + } + // Function names are still found at the start of a run, and only as whole runs. + assert!(matches!(parse_linear("sin x").as_slice(), [MNode::Func { .. }])); + assert!(matches!(parse_linear("arcsin x").as_slice(), [MNode::Func { .. }])); + assert!(matches!(parse_linear("sinx").as_slice(), [MNode::Run(_)])); + assert!(matches!(parse_linear("arcsinhx").as_slice(), [MNode::Run(_)])); + } +} diff --git a/crates/math/src/math_latex.rs b/crates/math/src/math_latex.rs new file mode 100644 index 000000000..24c0d5541 --- /dev/null +++ b/crates/math/src/math_latex.rs @@ -0,0 +1,1316 @@ +//! LaTeX ↔ math tree (Word's LaTeX equation input and conversion). +//! +//! Input covers the commands people type in equations: `\frac`, `\sqrt[n]{}`, scripts, big +//! operators with limits, `\left…\middle…\right`, matrix and `cases`/`aligned` environments, +//! accents, `\overbrace`/`\underbrace`, `\text`/`\mathrm`/`\mathbf`/`\mathbb`…, function names, +//! spacing and every named symbol in [`crate::math_symbols`]. Unknown commands stay as text. + +use crate::math::{ + Arg, ColJc, FracKind, MAX_DEPTH, MNode, MRun, MScr, MSty, ScriptKind, WRAP_DEPTH, any_too_deep, is_nary_char, math_class, merge_runs, too_deep, +}; +use crate::math_linear::{FUNCTION_NAMES, map_args}; +use crate::math_symbols::{name_of, symbol}; + +#[derive(Clone, Debug, PartialEq)] +enum Tok { + Cmd(String), + Open, + Close, + Sup, + Sub, + Amp, + Row, + Ch(char), +} + +/// Commands whose `{…}` argument is text, where spaces are part of the content. +const TEXT_COMMANDS: &[&str] = &["text", "textrm", "mbox", "hbox", "textnormal", "textbf", "textit", "emph", "textsf"]; + +fn tokenize(s: &str) -> Vec { + let cs: Vec = s.chars().take(20_000).collect(); + let mut out = Vec::new(); + let mut i = 0; + // A text command was just read: its `{` starts text, where spaces count (#448). + let mut text_next = false; + // Brace depth inside a text argument. + let mut text_depth: Option = None; + while let Some(&c) = cs.get(i) { + i += 1; + if text_depth.is_some() && matches!(c, ' ' | '\t' | '\n' | '\r') { + // A run of white space is one space, as in LaTeX. + if out.last() != Some(&Tok::Ch(' ')) { + out.push(Tok::Ch(' ')); + } + continue; + } + let was_text_next = std::mem::take(&mut text_next); + match c { + '\\' => { + let start = i; + while cs.get(i).is_some_and(char::is_ascii_alphabetic) { + i += 1; + } + if i == start { + match cs.get(i) { + Some('\\') => { + i += 1; + out.push(Tok::Row); + } + Some(&c) => { + i += 1; + out.push(Tok::Cmd(c.to_string())); + } + None => {} + } + } else { + let name: String = cs.get(start..i).unwrap_or(&[]).iter().collect(); + text_next = text_depth.is_none() && TEXT_COMMANDS.contains(&name.as_str()); + out.push(Tok::Cmd(name)); + } + } + '{' => { + text_depth = match text_depth { + Some(d) => Some(d.saturating_add(1)), + None if was_text_next => Some(0), + None => None, + }; + out.push(Tok::Open); + } + '}' => { + text_depth = match text_depth { + Some(0) | None => None, + Some(d) => Some(d.saturating_sub(1)), + }; + out.push(Tok::Close); + } + '^' => out.push(Tok::Sup), + '_' => out.push(Tok::Sub), + '&' => out.push(Tok::Amp), + // White space between a text command and its `{` doesn't end the wait. + ' ' | '\t' | '\n' | '\r' => text_next = was_text_next, + '~' => out.push(Tok::Ch('\u{A0}')), + c => out.push(Tok::Ch(c)), + } + } + out +} + +/// Parse LaTeX math into nodes. Never fails. +pub fn parse_latex(s: &str) -> Arg { + let mut p = Lp { t: tokenize(s), i: 0, depth: 0 }; + let mut out = Vec::new(); + while p.i < p.t.len() { + out.extend(p.seq(false)); + // A stray `}` or `&`/`\\` at the top level. + match p.t.get(p.i) { + Some(Tok::Amp) => out.push(run("&")), + Some(Tok::Row) => {} + Some(Tok::Close) => {} + _ => {} + } + p.i += 1; + } + let out = merge_runs(out); + if out.iter().any(|n| matches!(n, MNode::Run(r) if !r.nor && r.text.contains('#'))) { + return vec![MNode::EqArr { rows: vec![out] }]; + } + out +} + +fn run(t: &str) -> MNode { + MNode::Run(MRun::new(t)) +} + +struct Lp { + t: Vec, + i: usize, + depth: usize, +} + +impl Lp { + fn peek(&self) -> Option<&Tok> { + self.t.get(self.i) + } + + /// A sequence up to `}` (in a group), `&`, `\\`, `\right`, `\middle` or `\end`. + fn seq(&mut self, in_group: bool) -> Arg { + self.depth += 1; + let mut out: Arg = Vec::new(); + if self.depth > MAX_DEPTH { + self.i = self.t.len(); + self.depth -= 1; + return out; + } + while let Some(tok) = self.peek().cloned() { + match tok { + Tok::Close if in_group => break, + Tok::Close | Tok::Amp | Tok::Row => break, + Tok::Cmd(ref c) if matches!(c.as_str(), "right" | "middle" | "end") => break, + Tok::Sup | Tok::Sub => { + self.i += 1; + let s = self.arg(); + if out.last().is_some_and(too_deep) { + // Too deep to wrap (`x^1^1^1…`): the operator is dropped, the script kept. + out.extend(s); + } else { + let base = out.pop(); + out.push(script(base, tok == Tok::Sup, s)); + } + } + Tok::Cmd(ref c) if c == "limits" || c == "nolimits" || c == "displaystyle" || c == "textstyle" => { + self.i += 1; + if c == "nolimits" + && let Some(MNode::Nary { lim_loc, .. }) = out.last_mut() + { + *lim_loc = Some(crate::math::LimLoc::SubSup); + } + if c == "limits" + && let Some(MNode::Nary { lim_loc, .. }) = out.last_mut() + { + *lim_loc = Some(crate::math::LimLoc::UndOvr); + } + } + _ => { + let a = self.atom(); + out.extend(a); + } + } + } + self.depth -= 1; + // Big operators take the following term as their operand. + nary_operands(out, self.depth) + } + + /// A command argument: a `{group}` or one token. + fn arg(&mut self) -> Arg { + match self.peek() { + Some(Tok::Open) => { + self.i += 1; + let g = self.seq(true); + if self.peek() == Some(&Tok::Close) { + self.i += 1; + } + g + } + Some(_) => self.atom(), + None => Vec::new(), + } + } + + /// `[optional]` argument. + fn opt(&mut self) -> Option { + if self.peek() != Some(&Tok::Ch('[')) { + return None; + } + self.i += 1; + let mut toks = Vec::new(); + let mut level = 0i32; + while let Some(t) = self.peek().cloned() { + self.i += 1; + match t { + Tok::Ch(']') if level == 0 => break, + Tok::Open => level += 1, + Tok::Close => level -= 1, + _ => {} + } + toks.push(t); + } + let mut p = Lp { t: toks, i: 0, depth: self.depth }; + Some(p.seq(false)) + } + + /// The text of a `{…}` argument, verbatim. + fn raw_arg(&mut self) -> String { + let mut s = String::new(); + if self.peek() != Some(&Tok::Open) { + if let Some(Tok::Ch(c)) = self.peek().cloned() { + self.i += 1; + s.push(c); + } + return s; + } + self.i += 1; + let mut level = 0i32; + // The previous token was a control word (`\backslash{}`: the empty braces end its name). + let mut after_word = false; + while let Some(t) = self.peek().cloned() { + self.i += 1; + let was_word = std::mem::replace(&mut after_word, matches!(&t, Tok::Cmd(c) if c.chars().all(|c| c.is_ascii_alphabetic()))); + match t { + Tok::Close if level == 0 => break, + Tok::Open if was_word && self.peek() == Some(&Tok::Close) => self.i += 1, + Tok::Open => { + level += 1; + s.push('{'); + } + Tok::Close => { + level -= 1; + s.push('}'); + } + Tok::Ch(c) => s.push(c), + Tok::Cmd(c) => { + if c.chars().all(|c| c.is_ascii_alphabetic()) { + match symbol(&c) { + Some(sym) => s.push(sym), + None => s.push_str(&c), + } + } else { + s.push_str(&c); + } + if c == " " { + s.push(' '); + } + } + Tok::Sup => s.push('^'), + Tok::Sub => s.push('_'), + Tok::Amp => s.push('&'), + Tok::Row => s.push('\n'), + } + } + s + } + + /// A delimiter after `\left`, `\right`, `\middle`, `\big…`. + fn delim(&mut self) -> Option { + let t = self.peek().cloned()?; + self.i += 1; + match t { + Tok::Ch('.') => None, + Tok::Ch(c) => Some(c), + Tok::Cmd(c) => match c.as_str() { + "{" => Some('{'), + "}" => Some('}'), + "|" => Some('‖'), + other => symbol(other), + }, + _ => None, + } + } + + fn atom(&mut self) -> Arg { + if self.depth > MAX_DEPTH { + self.i = self.t.len(); + return Vec::new(); + } + self.depth += 1; + let out = self.atom_inner(); + self.depth -= 1; + out + } + + fn atom_inner(&mut self) -> Arg { + let Some(t) = self.peek().cloned() else { return Vec::new() }; + self.i += 1; + match t { + Tok::Open => { + let g = self.seq(true); + if self.peek() == Some(&Tok::Close) { + self.i += 1; + } + g + } + Tok::Ch(c) => vec![run(&c.to_string())], + Tok::Close | Tok::Amp | Tok::Row | Tok::Sup | Tok::Sub => Vec::new(), + Tok::Cmd(c) => self.command(&c), + } + } + + fn command(&mut self, c: &str) -> Arg { + let styled = |a: Arg, sty: Option, scr: MScr, nor: bool| -> Arg { restyle(a, sty, scr, nor) }; + let one = |n: MNode| vec![n]; + match c { + "frac" | "dfrac" | "tfrac" | "cfrac" => { + let num = self.arg(); + let den = self.arg(); + one(MNode::Frac { kind: FracKind::Bar, num, den }) + } + "genfrac" => { + let beg = delim_arg(&self.arg()); + let end = delim_arg(&self.arg()); + let thickness = self.arg(); + let _style = self.arg(); + let num = self.arg(); + let den = self.arg(); + let kind = if is_zero_length(&thickness) { FracKind::NoBar } else { FracKind::Bar }; + let frac = MNode::Frac { kind, num, den }; + if beg.is_none() && end.is_none() { + one(frac) + } else { + one(MNode::Delim { beg, end, sep: None, grow: true, shp_match: false, elems: vec![vec![frac]] }) + } + } + "binom" | "dbinom" | "tbinom" => { + let n = self.arg(); + let k = self.arg(); + one(MNode::Delim { + beg: Some('('), + end: Some(')'), + sep: None, + grow: true, + shp_match: false, + elems: vec![vec![MNode::Frac { kind: FracKind::NoBar, num: n, den: k }]], + }) + } + "sqrt" => { + let deg = self.opt().unwrap_or_default(); + let e = self.arg(); + one(MNode::Rad { deg_hide: deg.is_empty(), deg, e }) + } + "left" => { + let beg = self.delim(); + let mut elems = vec![self.seq(false)]; + let mut sep = None; + let mut end = None; + while let Some(Tok::Cmd(k)) = self.peek().cloned() { + self.i += 1; + if k == "middle" { + sep = self.delim().or(Some('|')); + elems.push(self.seq(false)); + } else { + if k == "right" { + end = self.delim(); + } + break; + } + } + one(MNode::Delim { beg, end, sep, grow: true, shp_match: false, elems }) + } + "bigl" | "Bigl" | "biggl" | "Biggl" | "bigr" | "Bigr" | "biggr" | "Biggr" | "big" | "Big" | "bigg" | "Bigg" => { + self.delim().map(|d| vec![run(&d.to_string())]).unwrap_or_default() + } + "begin" => { + let env = self.raw_arg(); + self.environment(env.trim()) + } + "text" | "textrm" | "mbox" | "hbox" | "textnormal" => { + let t = self.raw_arg(); + one(MNode::Run(MRun { text: t, nor: true, sty: Some(MSty::Plain), ..Default::default() })) + } + "textbf" => { + let t = self.raw_arg(); + one(MNode::Run(MRun { text: t, nor: true, sty: Some(MSty::Bold), ..Default::default() })) + } + "textit" | "emph" => { + let t = self.raw_arg(); + one(MNode::Run(MRun { text: t, nor: true, sty: Some(MSty::Italic), ..Default::default() })) + } + "textsf" => { + let t = self.raw_arg(); + one(MNode::Run(MRun { text: t, nor: true, sty: Some(MSty::Plain), scr: MScr::SansSerif, ..Default::default() })) + } + // MathLive's absolute value, upright constants and differential. + "abs" => { + let e = self.arg(); + one(MNode::Delim { beg: Some('|'), end: Some('|'), sep: None, grow: true, shp_match: false, elems: vec![e] }) + } + "differentialD" => vec![run("d")], + "exponentialE" => vec![MNode::Run(MRun::plain("e"))], + "imaginaryI" => vec![MNode::Run(MRun::plain("i"))], + "operatorname" => { + let starred = self.peek() == Some(&Tok::Ch('*')); + if starred { + self.i += 1; + } + let t = self.raw_arg(); + let name = vec![MNode::Run(MRun::plain(t))]; + if starred && self.peek() == Some(&Tok::Sub) { + self.i += 1; + let lim = self.arg(); + vec![MNode::Lim { upper: false, e: name, lim }] + } else { + self.apply(name) + } + } + "tag" => { + let starred = self.peek() == Some(&Tok::Ch('*')); + if starred { + self.i += 1; + } + let t = self.raw_arg(); + let num_str = if starred { format!("#{t}") } else { format!("# ({t})") }; + let mut r = MRun::new(num_str); + r.lit = false; + vec![MNode::Run(r)] + } + "mathrm" | "rm" => { + let a = self.arg(); + styled(a, Some(MSty::Plain), MScr::Roman, false) + } + "mathbf" | "bf" => { + let a = self.arg(); + styled(a, Some(MSty::Bold), MScr::Roman, false) + } + "mathnormal" => self.arg(), + "mathit" => { + let a = self.arg(); + styled(a, Some(MSty::Italic), MScr::Roman, false) + } + "boldsymbol" | "bm" => { + let a = self.arg(); + styled(a, Some(MSty::BoldItalic), MScr::Roman, false) + } + "mathbb" => { + let a = self.arg(); + styled(a, None, MScr::DoubleStruck, false) + } + "mathcal" | "mathscr" => { + let a = self.arg(); + styled(a, None, MScr::Script, false) + } + "mathfrak" => { + let a = self.arg(); + styled(a, None, MScr::Fraktur, false) + } + "mathsf" => { + let a = self.arg(); + styled(a, None, MScr::SansSerif, false) + } + "mathtt" => { + let a = self.arg(); + styled(a, None, MScr::Monospace, false) + } + "overline" => one(MNode::Bar { top: true, e: self.arg() }), + "underline" => one(MNode::Bar { top: false, e: self.arg() }), + "boxed" | "fbox" => one(MNode::BorderBox { hide: [false; 4], strike: [false; 4], e: self.arg() }), + "phantom" => one(MNode::Phant { show: false, zero_wid: false, zero_asc: false, zero_desc: false, e: self.arg() }), + "overbrace" | "underbrace" | "overparen" | "underparen" | "overbracket" | "underbracket" => { + let top = c.starts_with("over"); + let chr = match c { + "overbrace" => '⏞', + "underbrace" => '⏟', + "overparen" => '⏜', + "underparen" => '⏝', + "overbracket" => '⎴', + _ => '⎵', + }; + let e = self.arg(); + let g = MNode::GroupChr { chr, top, e }; + let want = if top { Tok::Sup } else { Tok::Sub }; + if self.peek() == Some(&want) { + self.i += 1; + let lim = self.arg(); + one(MNode::Lim { upper: top, e: vec![g], lim }) + } else { + one(g) + } + } + "underleftarrow" | "underrightarrow" | "underleftrightarrow" => { + let chr = match c { + "underleftarrow" => '←', + "underrightarrow" => '→', + _ => '↔', + }; + one(MNode::GroupChr { chr, top: false, e: self.arg() }) + } + "stackrel" | "overset" => { + let over = self.arg(); + let base = self.arg(); + one(MNode::Lim { upper: true, e: base, lim: over }) + } + "underset" => { + let under = self.arg(); + let base = self.arg(); + one(MNode::Lim { upper: false, e: base, lim: under }) + } + "hat" | "widehat" | "tilde" | "widetilde" | "dot" | "ddot" | "dddot" | "check" | "breve" | "acute" | "grave" | "vec" | "bar" + | "overrightarrow" | "overleftarrow" | "overleftrightarrow" | "mathring" => { + let chr = match c { + "hat" | "widehat" => '\u{302}', + "tilde" | "widetilde" => '\u{303}', + "dot" => '\u{307}', + "ddot" => '\u{308}', + "dddot" => '\u{20DB}', + "check" => '\u{30C}', + "breve" => '\u{306}', + "acute" => '\u{301}', + "grave" => '\u{300}', + "bar" => '\u{305}', + "overleftarrow" => '\u{20D6}', + "overleftrightarrow" => '\u{20E1}', + "mathring" => '\u{30A}', + _ => '\u{20D7}', + }; + one(MNode::Acc { chr, e: self.arg() }) + } + "," | "thinspace" => vec![run("\u{2009}")], + ":" | ">" | "medspace" => vec![run("\u{205F}")], + ";" | "thickspace" => vec![run("\u{2005}")], + "!" | "negthinspace" => Vec::new(), + " " => vec![run(" ")], + "qquad" => vec![run("\u{2003}\u{2003}")], + "{" | "}" | "%" | "$" | "#" | "&" | "_" => { + // Escaped characters (a literal `#` must not number the equation). + let mut r = MRun::new(c); + r.lit = c == "#"; + vec![MNode::Run(r)] + } + "|" => vec![run("‖")], + name if FUNCTION_NAMES.contains(&name) => { + let plain = vec![MNode::Run(MRun::plain(name))]; + let limits = matches!(name, "lim" | "liminf" | "limsup" | "max" | "min" | "sup" | "inf" | "det" | "gcd" | "Pr"); + let named = if limits && self.peek() == Some(&Tok::Sub) { + self.i += 1; + let lim = self.arg(); + vec![MNode::Lim { upper: false, e: plain, lim }] + } else if matches!(self.peek(), Some(Tok::Sup) | Some(Tok::Sub)) { + let sup = self.peek() == Some(&Tok::Sup); + self.i += 1; + let s = self.arg(); + vec![script(Some(MNode::Run(MRun::plain(name))), sup, s)] + } else { + plain + }; + self.apply(named) + } + name => match symbol(name) { + Some(ch) if is_nary_char(ch) => vec![MNode::Nary { + chr: ch, + lim_loc: None, + grow: false, + sub_hide: true, + sup_hide: true, + sub: Vec::new(), + sup: Vec::new(), + e: Vec::new(), + }], + Some(ch) => vec![run(&ch.to_string())], + None => vec![run(&format!("\\{name}"))], + }, + } + } + + /// A function name applied to the next atom (with its scripts). + fn apply(&mut self, name: Arg) -> Arg { + let mut e = self.atom(); + while let Some(t @ (Tok::Sup | Tok::Sub)) = self.peek().cloned() { + self.i += 1; + let s = self.arg(); + if any_too_deep(&e) { + e.extend(s); + continue; + } + let base = if e.len() == 1 { e.pop() } else { Some(group(std::mem::take(&mut e))) }; + e.push(script(base, t == Tok::Sup, s)); + } + if e.is_empty() { + return name; + } + vec![MNode::Func { name, e }] + } + + fn environment(&mut self, env: &str) -> Arg { + let base = env.trim_end_matches('*'); + let mut col_jc = Vec::new(); + if base == "array" || base == "tabular" { + let _ = self.opt(); + let spec = self.raw_arg(); + for ch in spec.chars() { + match ch { + 'l' | 'L' => col_jc.push(ColJc::Left), + 'r' | 'R' => col_jc.push(ColJc::Right), + 'c' | 'C' => col_jc.push(ColJc::Center), + _ => {} + } + } + } else if base == "aligned" { + let _ = self.opt(); + } + // Rows of `&`-separated cells up to `\end{…}`. + let mut rows: Vec> = vec![vec![]]; + loop { + let cell = self.seq(false); + if let Some(r) = rows.last_mut() { + r.push(cell); + } + match self.peek().cloned() { + Some(Tok::Amp) => self.i += 1, + Some(Tok::Row) => { + self.i += 1; + rows.push(vec![]); + } + Some(Tok::Cmd(k)) if k == "end" => { + self.i += 1; + let _ = self.raw_arg(); + break; + } + Some(Tok::Close) => self.i += 1, + Some(_) => self.i += 1, + None => break, + } + } + // A trailing `\\` leaves an empty last row. + if rows.len() > 1 && rows.last().is_some_and(|r| r.iter().all(|c| c.is_empty())) { + rows.pop(); + } + let delims = match base { + "pmatrix" => Some((Some('('), Some(')'))), + "bmatrix" => Some((Some('['), Some(']'))), + "Bmatrix" => Some((Some('{'), Some('}'))), + "vmatrix" => Some((Some('|'), Some('|'))), + "Vmatrix" => Some((Some('‖'), Some('‖'))), + _ => None, + }; + let wrap = |inner: MNode, beg: Option, end: Option| MNode::Delim { + beg, + end, + sep: None, + grow: true, + shp_match: false, + elems: vec![vec![inner]], + }; + match base { + "matrix" | "pmatrix" | "bmatrix" | "Bmatrix" | "vmatrix" | "Vmatrix" | "smallmatrix" | "array" | "tabular" => { + let m = MNode::Matrix { rows, col_jc }; + match delims { + Some((b, e)) => vec![wrap(m, b, e)], + None => vec![m], + } + } + "cases" | "dcases" => { + let eq = MNode::EqArr { rows: rows.into_iter().map(join_cells).collect() }; + vec![wrap(eq, Some('{'), None)] + } + "rcases" => { + let eq = MNode::EqArr { rows: rows.into_iter().map(join_cells).collect() }; + vec![wrap(eq, None, Some('}'))] + } + _ => vec![MNode::EqArr { rows: rows.into_iter().map(join_cells).collect() }], + } + } +} + +/// Cells of an aligned row joined with `&` alignment marks. +fn join_cells(cells: Vec) -> Arg { + let mut out = Vec::new(); + for (i, c) in cells.into_iter().enumerate() { + if i > 0 { + out.push(run("&")); + } + out.extend(c); + } + merge_runs(out) +} + +fn group(a: Arg) -> MNode { + MNode::Delim { beg: None, end: None, sep: None, grow: true, shp_match: false, elems: vec![a] } +} + +fn script(base: Option, sup: bool, s: Arg) -> MNode { + match base { + Some(MNode::Nary { chr, lim_loc, grow, sub_hide, sup_hide, sub, sup: sp, e }) if e.is_empty() => { + if sup { + MNode::Nary { chr, lim_loc, grow, sub_hide, sup_hide: false, sub, sup: s, e } + } else { + MNode::Nary { chr, lim_loc, grow, sub_hide: false, sup_hide, sub: s, sup: sp, e } + } + } + Some(MNode::Script { kind: ScriptKind::Sub, base, sub, .. }) if sup => MNode::Script { kind: ScriptKind::SubSup, base, sub, sup: s }, + Some(MNode::Script { kind: ScriptKind::Sup, base, sup: sp, .. }) if !sup => MNode::Script { kind: ScriptKind::SubSup, base, sub: s, sup: sp }, + b => { + let base = b.map(|b| vec![b]).unwrap_or_default(); + if sup { + MNode::Script { kind: ScriptKind::Sup, base, sub: Vec::new(), sup: s } + } else { + MNode::Script { kind: ScriptKind::Sub, base, sub: s, sup: Vec::new() } + } + } + } +} + +/// Big operators without an operand take the atoms after them up to a relation or binary operator. +/// `depth` is how deep the operators already sit; past [`WRAP_DEPTH`] they stay without operand +/// (`\sum\sum\sum…` must not nest once per operator). +fn nary_operands(a: Arg, depth: usize) -> Arg { + let mut out: Arg = Vec::with_capacity(a.len()); + let mut it = a.into_iter().peekable(); + while let Some(n) = it.next() { + match n { + MNode::Nary { chr, lim_loc, grow, sub_hide, sup_hide, sub, sup, e } if e.is_empty() && depth < WRAP_DEPTH => { + let mut body = Vec::new(); + while let Some(next) = it.peek() { + let stop = match next { + MNode::Run(r) => r.text.chars().next().is_some_and(|c| { + matches!(math_class(c), crate::math::MClass::Rel | crate::math::MClass::Bin | crate::math::MClass::Punct) || c == '&' + }), + _ => false, + }; + if stop { + break; + } + if let Some(x) = it.next() { + body.push(x); + } + } + let body = merge_runs(nary_operands(body, depth + 1)); + if any_too_deep(&body) { + // No room to wrap the operand: it follows the operator. + out.push(MNode::Nary { chr, lim_loc, grow, sub_hide, sup_hide, sub, sup, e }); + out.extend(body); + } else { + out.push(MNode::Nary { chr, lim_loc, grow, sub_hide, sup_hide, sub, sup, e: body }); + } + } + other => out.push(other), + } + } + out +} + +/// Set a style on every run inside. +fn restyle(a: Arg, sty: Option, scr: MScr, nor: bool) -> Arg { + a.into_iter() + .map(|n| match n { + MNode::Run(mut r) => { + if sty.is_some() { + r.sty = sty; + } + if scr != MScr::Roman { + r.scr = scr; + } + r.nor |= nor; + MNode::Run(r) + } + other => map_args(other, &|a| restyle(a, sty, scr, nor)), + }) + .collect() +} + +// --------------------------------------------------------------------------------------------- +// Out. + +/// The equation as LaTeX. +pub fn to_latex(nodes: &[MNode]) -> String { + let mut s = String::new(); + arg(nodes, &mut s, 0); + s.trim().to_string() +} + +fn arg(a: &[MNode], s: &mut String, depth: usize) { + if depth > MAX_DEPTH { + return; + } + for n in a { + node(n, s, depth + 1); + } +} + +fn braced(a: &[MNode], s: &mut String, depth: usize) { + s.push('{'); + arg(a, s, depth); + s.push('}'); +} + +fn chars(text: &str, s: &mut String) { + for c in text.chars() { + match c { + '{' | '}' | '%' | '$' | '#' | '&' | '_' => { + s.push('\\'); + s.push(c); + } + '\\' => s.push_str("\\backslash "), + '−' => s.push('-'), + c if c.is_ascii() => s.push(c), + c => match name_of(c) { + Some(n) if !matches!(n, "sqrt" | "matrix" | "of" | "above" | "below" | "box" | "rect") => { + s.push('\\'); + s.push_str(n); + s.push(' '); + } + _ => s.push(c), + }, + } + } +} + +/// Text inside `\text{…}`: only what LaTeX would read as markup is escaped. +fn text_chars(text: &str, s: &mut String) { + for c in text.chars() { + match c { + '{' | '}' | '%' | '$' | '#' | '&' | '_' | '~' => { + s.push('\\'); + s.push(c); + } + // `{}` ends the command name without adding a space (spaces count in text). + '\\' => s.push_str("\\backslash{}"), + c => s.push(c), + } + } +} + +/// The delimiter of a `\genfrac` argument: one character, or none for `{}` and anything else. +fn delim_arg(a: &[MNode]) -> Option { + let [MNode::Run(r)] = a else { return None }; + let mut cs = r.text.chars(); + match (cs.next(), cs.next()) { + (Some(c), None) if c != '.' => Some(c), + _ => None, + } +} + +/// Whether a `\genfrac` thickness is a zero length such as `0pt`, `0.0pt` or `0 em`. An empty +/// thickness means the default rule and anything that is not a plain number and unit is not zero. +fn is_zero_length(a: &[MNode]) -> bool { + let mut text = String::new(); + for n in a { + let MNode::Run(r) = n else { return false }; + text.extend(r.text.chars().filter(|c| !c.is_whitespace() && !matches!(c, '\u{2009}' | '\u{205F}' | '\u{2005}'))); + } + let number = text.trim_end_matches(|c: char| c.is_ascii_alphabetic()); + let unit = &text[number.len()..]; + !number.is_empty() + && matches!(unit, "pt" | "em" | "ex" | "mm" | "cm" | "in" | "bp" | "pc" | "sp" | "mu") + && number.parse::().is_ok_and(|v| v == 0.0) +} + +fn delim_tex(c: Option) -> String { + match c { + None => ".".into(), + Some('{') => "\\{".into(), + Some('}') => "\\}".into(), + Some('‖') => "\\|".into(), + Some(c) if c.is_ascii() => c.to_string(), + Some(c) => name_of(c).map(|n| format!("\\{n} ")).unwrap_or_else(|| c.to_string()), + } +} + +fn group_chr_tex(chr: char, top: bool) -> &'static str { + match chr { + '⏜' => "\\overparen", + '⏝' => "\\underparen", + '⎴' => "\\overbracket", + '⎵' => "\\underbracket", + _ if top => "\\overbrace", + _ => "\\underbrace", + } +} + +fn node(node: &MNode, output: &mut String, depth: usize) { + match node { + MNode::Run(run) => run_node(run, output), + MNode::Frac { kind, num, den } => fraction_node(*kind, num, den, output, depth), + MNode::Script { kind, base, sub, sup } => script_node(*kind, base, sub, sup, output, depth), + MNode::Rad { deg, deg_hide, e } => radical_node(deg, *deg_hide, e, output, depth), + MNode::Nary { .. } => nary_node(node, output, depth), + MNode::Delim { beg, end, sep, elems, .. } => delimiter_node(*beg, *end, *sep, elems, output, depth), + MNode::Func { name, e } => { + arg(name, output, depth); + braced(e, output, depth); + } + MNode::Lim { upper, e, lim } => limit_node(*upper, e, lim, output, depth), + MNode::Acc { chr, e } => accent_node(*chr, e, output, depth), + MNode::Bar { top, e } => { + output.push_str(if *top { "\\overline" } else { "\\underline" }); + braced(e, output, depth); + } + MNode::BorderBox { e, .. } => { + output.push_str("\\boxed"); + braced(e, output, depth); + } + MNode::Boxed { e } => braced(e, output, depth), + MNode::GroupChr { chr, top, e } => { + output.push_str(group_chr_tex(*chr, *top)); + braced(e, output, depth); + } + MNode::EqArr { rows } => equation_array_node(rows, output, depth), + MNode::Matrix { rows, .. } => matrix_node(rows, output, depth), + MNode::Phant { e, .. } => { + output.push_str("\\phantom"); + braced(e, output, depth); + } + } +} + +fn run_node(run: &MRun, output: &mut String) { + let (open, close) = if run.nor { + ("\\text{", "}") + } else { + match (run.sty, run.scr) { + (_, MScr::DoubleStruck) => ("\\mathbb{", "}"), + (_, MScr::Script) => ("\\mathcal{", "}"), + (_, MScr::Fraktur) => ("\\mathfrak{", "}"), + (_, MScr::SansSerif) => ("\\mathsf{", "}"), + (_, MScr::Monospace) => ("\\mathtt{", "}"), + (Some(MSty::Bold), _) => ("\\mathbf{", "}"), + (Some(MSty::BoldItalic), _) => ("\\boldsymbol{", "}"), + (Some(MSty::Plain), _) if run.text.chars().any(char::is_alphabetic) => { + if FUNCTION_NAMES.contains(&run.text.as_str()) { + output.push('\\'); + output.push_str(&run.text); + output.push(' '); + return; + } + ("\\mathrm{", "}") + } + _ => ("", ""), + } + }; + output.push_str(open); + if run.nor { + text_chars(&run.text, output) + } else { + chars(&run.text, output) + } + output.push_str(close); +} + +fn fraction_node(kind: FracKind, numerator: &[MNode], denominator: &[MNode], output: &mut String, depth: usize) { + match kind { + FracKind::NoBar => { + output.push_str("\\genfrac{}{}{0pt}{}"); + braced(numerator, output, depth); + braced(denominator, output, depth); + } + FracKind::Linear | FracKind::Skewed => { + braced(numerator, output, depth); + output.push('/'); + braced(denominator, output, depth); + } + FracKind::Bar => { + output.push_str("\\frac"); + braced(numerator, output, depth); + braced(denominator, output, depth); + } + } +} + +fn script_node(kind: ScriptKind, base: &[MNode], sub: &[MNode], sup: &[MNode], output: &mut String, depth: usize) { + if kind == ScriptKind::Pre { + output.push_str("{}_"); + braced(sub, output, depth); + output.push('^'); + braced(sup, output, depth); + braced(base, output, depth); + return; + } + // An operator name takes its scripts directly (`\sin^{2}`): in braces it would no longer apply + // to what follows it when read back. + match base { + [MNode::Run(r)] if is_function_name(r) => run_node(r, output), + _ => braced(base, output, depth), + } + if matches!(kind, ScriptKind::Sub | ScriptKind::SubSup) { + output.push('_'); + braced(sub, output, depth); + } + if matches!(kind, ScriptKind::Sup | ScriptKind::SubSup) { + output.push('^'); + braced(sup, output, depth); + } +} + +/// Is `r` an operator name the writer writes as a command (`\sin`, `\log`)? +fn is_function_name(r: &MRun) -> bool { + !r.nor && r.sty == Some(MSty::Plain) && r.scr == MScr::Roman && FUNCTION_NAMES.contains(&r.text.as_str()) +} + +fn radical_node(degree: &[MNode], degree_hidden: bool, expression: &[MNode], output: &mut String, depth: usize) { + output.push_str("\\sqrt"); + if !degree_hidden && !degree.is_empty() { + output.push('['); + arg(degree, output, depth); + output.push(']'); + } + braced(expression, output, depth); +} + +fn nary_node(node: &MNode, output: &mut String, depth: usize) { + let MNode::Nary { chr, lim_loc, sub_hide, sup_hide, sub, sup, e, .. } = node else { return }; + match name_of(*chr) { + Some(name) => { + output.push('\\'); + output.push_str(name); + } + None => output.push(*chr), + } + match lim_loc { + Some(crate::math::LimLoc::UndOvr) => output.push_str("\\limits"), + Some(crate::math::LimLoc::SubSup) if !crate::math::is_integral(*chr) => output.push_str("\\nolimits"), + _ => {} + } + if !sub_hide && !sub.is_empty() { + output.push('_'); + braced(sub, output, depth); + } + if !sup_hide && !sup.is_empty() { + output.push('^'); + braced(sup, output, depth); + } + output.push(' '); + braced(e, output, depth); +} + +fn delimiter_node(begin: Option, end: Option, separator: Option, elements: &[Arg], output: &mut String, depth: usize) { + output.push_str("\\left"); + output.push_str(&delim_tex(begin)); + let middle = separator.map(|c| format!("\\middle{}", delim_tex(Some(c)))).unwrap_or_else(|| "\\middle|".to_string()); + for (index, element) in elements.iter().enumerate() { + if index > 0 { + output.push_str(&middle); + } + arg(element, output, depth); + } + output.push_str("\\right"); + output.push_str(&delim_tex(end)); +} + +fn limit_node(upper: bool, expression: &[MNode], limit: &[MNode], output: &mut String, depth: usize) { + let simple = matches!(expression, [MNode::Run(run)] if run.sty == Some(MSty::Plain) && FUNCTION_NAMES.contains(&run.text.as_str())); + if simple && !upper { + arg(expression, output, depth); + output.push('_'); + braced(limit, output, depth); + } else if let [MNode::GroupChr { chr, top, e: inner }] = expression { + output.push_str(group_chr_tex(*chr, *top)); + braced(inner, output, depth); + output.push(if upper { '^' } else { '_' }); + braced(limit, output, depth); + } else { + output.push_str(if upper { "\\overset" } else { "\\underset" }); + braced(limit, output, depth); + braced(expression, output, depth); + } +} + +fn accent_node(character: char, expression: &[MNode], output: &mut String, depth: usize) { + let command = match character { + '\u{302}' => "hat", + '\u{303}' => "tilde", + '\u{307}' => "dot", + '\u{308}' => "ddot", + '\u{20DB}' => "dddot", + '\u{30C}' => "check", + '\u{306}' => "breve", + '\u{301}' => "acute", + '\u{300}' => "grave", + '\u{305}' | '\u{AF}' => "bar", + '\u{20D6}' => "overleftarrow", + '\u{20E1}' => "overleftrightarrow", + _ => "vec", + }; + output.push('\\'); + output.push_str(command); + braced(expression, output, depth); +} + +fn equation_array_node(rows: &[Arg], output: &mut String, depth: usize) { + if rows.len() == 1 + && let Some(row) = rows.first() + && crate::math::has_number_mark(row) + { + arg(row, output, depth); + return; + } + output.push_str("\\begin{aligned}"); + for (index, row) in rows.iter().enumerate() { + if index > 0 { + output.push_str("\\\\"); + } + for child_node in row { + match child_node { + MNode::Run(run) if !run.lit && run.text.contains('&') => { + for (index, part) in run.text.split('&').enumerate() { + if index > 0 { + output.push('&'); + } + let mut piece = run.clone(); + piece.text = part.to_string(); + run_node(&piece, output); + } + } + other => node(other, output, depth + 1), + } + } + } + output.push_str("\\end{aligned}"); +} + +fn matrix_node(rows: &[Vec], output: &mut String, depth: usize) { + output.push_str("\\begin{matrix}"); + for (row_index, row) in rows.iter().enumerate() { + if row_index > 0 { + output.push_str("\\\\"); + } + for (column, cell) in row.iter().enumerate() { + if column > 0 { + output.push('&'); + } + arg(cell, output, depth); + } + } + output.push_str("\\end{matrix}"); +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::math::{LimLoc, MathJc}; + + #[test] + fn latex_structures() { + let n = parse_latex(r"x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}"); + assert_eq!(crate::math::to_linear(&n), "x=(-b±√(b^2-4ac))/2a"); + let n = parse_latex(r"\sum_{i=1}^{n} i^2 = \frac{n(n+1)(2n+1)}{6}"); + let MNode::Nary { chr, sub, sup, e, .. } = &n[0] else { panic!("{n:#?}") }; + assert_eq!((*chr, sub.len(), sup.len()), ('∑', 1, 1)); + assert!(matches!(e.first(), Some(MNode::Script { .. })), "{e:#?}"); + let n = parse_latex(r"\begin{pmatrix} a & b \\ c & d \end{pmatrix}"); + assert!( + matches!(&n[0], MNode::Delim { beg: Some('('), elems, .. } if matches!(elems[0][0], MNode::Matrix { ref rows, .. } if rows.len() == 2)) + ); + let n = parse_latex(r"f(x)=\begin{cases} x & x\ge 0\\ -x & x<0\end{cases}"); + assert!(n.iter().any(|m| matches!(m, MNode::Delim { beg: Some('{'), end: None, .. })), "{n:#?}"); + let n = parse_latex(r"\lim_{n\to\infty}\left(1+\frac{1}{n}\right)^n"); + assert!(matches!(&n[0], MNode::Func { .. }), "{n:#?}"); + let n = parse_latex(r"\mathbb{R}\hat{x}\text{ if }\overbrace{a+b}^{k}"); + assert!(matches!(&n[0], MNode::Run(r) if r.scr == MScr::DoubleStruck)); + let _ = (LimLoc::UndOvr, MathJc::Center); + } + + #[test] + fn latex_binom_round_trip() { + let a = parse_latex(r"\binom{n}{k}"); + let l = to_latex(&a); + assert_eq!(parse_latex(&l), a, "exported as {l}"); + let nobar = |n: &str, k: &str| MNode::Frac { kind: FracKind::NoBar, num: parse_latex(n), den: parse_latex(k) }; + let b = parse_latex(r"\genfrac{}{}{0pt}{}{n}{k}"); + assert_eq!(b, vec![nobar("n", "k")]); + assert_eq!(parse_latex(&to_latex(&b)), b); + // Other spellings of a zero thickness. + for z in ["0 pt", "0.0pt", r"0\,pt", "0em"] { + let c = parse_latex(&format!(r"\genfrac{{}}{{}}{{{z}}}{{}}{{n}}{{k}}")); + assert_eq!(c, vec![nobar("n", "k")], "thickness {z}"); + } + // A non-zero or default thickness keeps the bar. + for t in ["1pt", "0.4pt", ""] { + let c = parse_latex(&format!(r"\genfrac{{}}{{}}{{{t}}}{{}}{{n}}{{k}}")); + let bar = MNode::Frac { kind: FracKind::Bar, num: parse_latex("n"), den: parse_latex("k") }; + assert_eq!(c, vec![bar], "thickness {t:?}"); + } + // Delimiters are kept. + let d = parse_latex(r"\genfrac(){0pt}{}{n}{k}"); + assert_eq!(d, a); + let e = parse_latex(r"\genfrac[]{0pt}{}{n}{k}"); + assert!(matches!(&e[..], [MNode::Delim { beg: Some('['), end: Some(']'), .. }]), "{e:#?}"); + assert_eq!(parse_latex(&to_latex(&e)), e); + } + + #[test] + fn latex_round_trip() { + for lin in ["x=(-b±√(b^2-4ac))/2a", "∑_(i=1)^n▒i^2", "√(3&x)", "a⃗+x̂", "■(a&b@c&d)", "sin⁡x+cos⁡y", "e^(-x^2)"] { + let n = crate::math::parse_linear(lin); + let tex = to_latex(&n); + let back = parse_latex(&tex); + assert_eq!(crate::math::to_linear(&back), crate::math::to_linear(&n), "{lin} → {tex}"); + } + } + + #[test] + fn group_character_latex_roundtrip() { + for cmd in ["\\overparen{a+b}", "\\underparen{a+b}", "\\overbracket{x}", "\\underbracket{x}"] { + let n = parse_latex(cmd); + let tex = to_latex(&n); + assert_eq!(tex, cmd); + } + } + + #[test] + fn hostile_latex_never_panics() { + for s in ["", "\\", "{", "}", "^", "_", "\\frac", "\\sqrt[", "\\left(", "\\right)", "\\begin{matrix", "&&\\\\", "{{{{", "\\end{x}", "a^^b__c"] + { + let _ = to_latex(&parse_latex(s)); + } + let deep = "{".repeat(5000); + let _ = parse_latex(&deep); + let deep = "\\frac{".repeat(3000); + let _ = parse_latex(&deep); + let deep = "\\sqrt".repeat(5000); + let _ = parse_latex(&deep); + let deep = "\\hat".repeat(5000) + "x"; + let _ = parse_latex(&deep); + } + + #[test] + fn array_column_specs_and_aligned_optional_args() { + let n = parse_latex(r"\begin{array}{lcr} a & b & c \\ d & e & f \end{array}"); + let MNode::Matrix { rows, col_jc } = &n[0] else { panic!("{n:#?}") }; + assert_eq!(col_jc, &[ColJc::Left, ColJc::Center, ColJc::Right]); + assert_eq!(rows.len(), 2); + assert_eq!(crate::math::to_linear(&rows[0][0]), "a"); + assert_eq!(crate::math::to_linear(&rows[0][1]), "b"); + assert_eq!(crate::math::to_linear(&rows[0][2]), "c"); + + let n = parse_latex(r"\begin{aligned}[t] x &= 1 \\ y &= 2 \end{aligned}"); + assert!(matches!(&n[0], MNode::EqArr { rows } if rows.len() == 2)); + } + + #[test] + fn operatorname_starred_and_tag() { + let n = parse_latex(r"\operatorname*{argmin}_{x} f(x)"); + assert!(matches!(&n[0], MNode::Lim { upper: false, .. })); + + let n = parse_latex(r"E=mc^2 \tag{1}"); + let MNode::EqArr { rows } = &n[0] else { panic!("{n:#?}") }; + assert!(crate::math::has_number_mark(&rows[0])); + + let n = parse_latex(r"E=mc^2 \tag*{(A)}"); + let MNode::EqArr { rows } = &n[0] else { panic!("{n:#?}") }; + assert!(crate::math::has_number_mark(&rows[0])); + } + + #[test] + fn delim_preserves_custom_separator() { + let delim = MNode::Delim { + beg: Some('{'), + end: Some('}'), + sep: Some('‖'), + grow: true, + shp_match: false, + elems: vec![vec![MNode::Run(MRun::new("x"))], vec![MNode::Run(MRun::new("y"))]], + }; + let tex = to_latex(&[delim]); + assert!(tex.contains(r"\middle\|"), "Expected \\middle\\|, got: {tex}"); + } + + /// Commands MathLive and typed input use, from equaSHion (storytold/craft-libs#29). + #[test] + fn mathlive_and_other_spellings() { + let lin = |src: &str| crate::math::to_linear(&parse_latex(src)); + assert_eq!(lin(r"\abs{x-1}"), lin(r"\left|x-1\right|")); + assert_eq!(lin(r"\lvert x\rvert+\lVert v\rVert"), "|x|+‖v‖"); + assert_eq!(lin(r"a\nparallel b \backprime"), "a∦b‵"); + assert_eq!(lin(r"\infinity\cross 2"), "∞×2"); + assert_eq!(lin(r"\mathnormal{x}"), "x"); + let runs = parse_latex(r"\exponentialE^{\imaginaryI\pi}\differentialD x"); + assert!( + matches!(&runs[0], MNode::Script { base, .. } if matches!(&base[0], MNode::Run(r) if r.text == "e" && r.sty == Some(MSty::Plain))), + "{runs:?}" + ); + for (src, sty, scr) in [ + (r"\emph{so it is}", MSty::Italic, MScr::Roman), + (r"\textsf{so it is}", MSty::Plain, MScr::SansSerif), + (r"\hbox{so it is}", MSty::Plain, MScr::Roman), + ] { + let a = parse_latex(src); + assert!(matches!(a.as_slice(), [MNode::Run(r)] if r.text == "so it is" && r.nor && r.sty == Some(sty) && r.scr == scr), "{src}: {a:?}"); + } + for (src, want) in [(r"\underrightarrow{AB}", '→'), (r"\underleftarrow{AB}", '←'), (r"\underleftrightarrow{AB}", '↔')] { + assert!(matches!(parse_latex(src).as_slice(), [MNode::GroupChr { chr, top: false, .. }] if *chr == want), "{src}"); + } + // The writer keeps its own names. + assert_eq!(to_latex(&parse_latex(r"\infinity")), to_latex(&parse_latex(r"\infty"))); + } + + /// An operator name with a script still applies to its argument when the LaTeX is read back. + #[test] + fn operator_names_take_their_scripts_directly() { + for src in [r"\sin^2\theta+\cos^2\theta=1", r"\log_2 x", r"\ln^{3}(x+1)"] { + let tree = parse_latex(src); + let tex = to_latex(&tree); + assert_eq!(crate::math::to_linear(&parse_latex(&tex)), crate::math::to_linear(&tree), "{src}: {tex}"); + assert!(!tex.contains(r"{\sin }") && !tex.contains(r"{\log }"), "{tex}"); + } + assert!(to_latex(&parse_latex(r"\sin^2\theta")).starts_with(r"\sin ^{2}")); + // Other bases keep their braces. + assert_eq!(to_latex(&parse_latex("x^2")), "{x}^{2}"); + } +} diff --git a/crates/math/src/math_linear.rs b/crates/math/src/math_linear.rs new file mode 100644 index 000000000..39a25ab5d --- /dev/null +++ b/crates/math/src/math_linear.rs @@ -0,0 +1,762 @@ +//! The linear format (UnicodeMath, the plain text Word builds equations from) → math tree. +//! +//! Grammar, informally: an expression is a sequence of atoms and operators. Atoms are characters, +//! bracket groups (`(…)`, `[…]`, `{…}`, `|…|`, `〖…〗` invisible, `├…┤` one-sided, `│` +//! separators), prefix structures (`√x`, `∑_a^b▒x`, `█(…)`, `■(…)`, `▭x`, `□x`, `¯x`, `▁x`, +//! `⏞x`, `⏟x`, `⟡x`), function names (`sin x`, `log_2 x`, `lim┬(n→∞) x`) and placeholders (`⬚`). +//! Postfix operators apply to the atom before them: `^` `_` scripts, combining accents, `┬` `┴` +//! limits. `/` `⁄` `∕` `¦` take the operands on either side (an operand is a run of atoms up to +//! an operator or space; a parenthesised operand loses its parentheses). `^`/`_` with nothing +//! before them are pre-scripts. A top-level `#` numbers the equation (`E=mc^2#(1)`). + +use crate::math::{Arg, FracKind, MAX_DEPTH, MClass, MNode, MRun, ScriptKind, any_too_deep, is_nary_char, math_class, merge_runs, too_deep}; + +/// Function names set upright and applied to the following operand. +pub const FUNCTION_NAMES: &[&str] = &[ + "arccos", "arccot", "arccsc", "arcsec", "arcsin", "arctan", "arg", "cos", "cosh", "cot", "coth", "csc", "csch", "deg", "det", "dim", "exp", + "gcd", "hom", "inf", "ker", "lg", "lim", "liminf", "limsup", "ln", "log", "max", "min", "mod", "Pr", "sec", "sech", "sin", "sinh", "sup", "tan", + "tanh", +]; + +/// Length of the longest of [`FUNCTION_NAMES`]. +const MAX_NAME: usize = { + let (mut max, mut i) = (0, 0); + while i < FUNCTION_NAMES.len() { + if FUNCTION_NAMES[i].len() > max { + max = FUNCTION_NAMES[i].len(); + } + i += 1; + } + max +}; + +/// Function names whose subscripts go underneath (`lim_(n→∞)`). +const LIMIT_NAMES: &[&str] = &["lim", "liminf", "limsup", "max", "min", "sup", "inf", "det", "gcd", "Pr"]; + +/// The empty-argument placeholder. +pub const PLACEHOLDER: char = '⬚'; + +/// Parse linear-format text. Never fails: what isn't understood stays as text. +pub fn parse(s: &str) -> Arg { + let mut p = P { c: s.chars().take(20_000).collect(), i: 0, depth: 0, no_limits: 0, steps: 0 }; + let mut out = Vec::new(); + // Stray closers at the top level are text. + while p.i < p.c.len() { + out.extend(p.expr(&[])); + if let Some(c) = p.peek() { + p.i += 1; + out.push(text(c)); + } + } + let mut out = clean(out); + // `expr#(n)`: a numbered equation. + if out.iter().any(|n| matches!(n, MNode::Run(r) if r.text.contains('#'))) { + out = vec![MNode::EqArr { rows: vec![out] }]; + } + out +} + +fn text(c: char) -> MNode { + MNode::Run(MRun::new(c.to_string())) +} + +/// Closing bracket for an opening one. +pub fn closer(c: char) -> Option { + Some(match c { + '(' => ')', + '[' => ']', + '{' => '}', + '⟨' => '⟩', + '〈' => '〉', + '⌈' => '⌉', + '⌊' => '⌋', + '⟦' => '⟧', + '〖' => '〗', + _ => return None, + }) +} + +fn is_closer(c: char) -> bool { + matches!(c, ')' | ']' | '}' | '⟩' | '〉' | '⌉' | '⌋' | '⟧' | '〗' | '┤') +} + +/// Prefix characters that make a structure from the operand after them. +fn is_prefix(c: char) -> bool { + matches!(c, '√' | '∛' | '∜' | '█' | '■' | '▭' | '□' | '¯' | '▁' | '⟡' | '⏞' | '⏟' | '⏜' | '⏝' | '⎴' | '⎵') || is_nary_char(c) +} + +/// Combining marks used as accents. +pub fn is_combining(c: char) -> bool { + matches!(c as u32, 0x300..=0x36F | 0x20D0..=0x20FF) +} + +/// Characters that end an operand. +fn is_boundary(c: char) -> bool { + matches!(c, ' ' | '&' | '@' | '#' | '▒' | '│' | '/' | '⁄' | '∕' | '¦' | '\u{2061}') + || is_closer(c) + || matches!(math_class(c), MClass::Bin | MClass::Rel | MClass::Punct) +} + +struct P { + c: Vec, + i: usize, + depth: usize, + /// Inside a brace's operand: limits are left for the brace. + no_limits: usize, + /// Work done (bounds hostile input). + steps: usize, +} + +const MAX_STEPS: usize = 400_000; + +impl P { + fn peek(&self) -> Option { + self.c.get(self.i).copied() + } + fn peek_at(&self, k: usize) -> Option { + self.c.get(self.i + k).copied() + } + fn tired(&mut self) -> bool { + self.steps += 1; + self.steps > MAX_STEPS || self.depth > MAX_DEPTH + } + /// The rest of the input as text (when too deep or too long). + fn rest(&mut self) -> Arg { + let t: String = self.c.get(self.i..).unwrap_or(&[]).iter().collect(); + self.i = self.c.len(); + if t.is_empty() { Vec::new() } else { vec![MNode::Run(MRun::new(t))] } + } + + /// A sequence up to one of `stops` (not consumed) or the end. + fn expr(&mut self, stops: &[char]) -> Arg { + self.depth += 1; + let mut out: Arg = Vec::new(); + if self.tired() { + self.depth -= 1; + return self.rest(); + } + while let Some(c) = self.peek() { + if stops.contains(&c) || (is_closer(c) && !stops.is_empty()) { + break; + } + if self.tired() { + out.extend(self.rest()); + break; + } + match c { + '/' | '⁄' | '∕' | '¦' => { + self.i += 1; + let start = operand_start(&out); + // A numerator that is already deep stays as it is: `/` is text then. + if out.get(start..).is_some_and(any_too_deep) { + out.push(text(c)); + continue; + } + let num = strip_parens(out.drain(start..).collect()); + let den = self.operand(stops); + let kind = match c { + '⁄' => FracKind::Skewed, + '∕' => FracKind::Linear, + '¦' => FracKind::NoBar, + _ => FracKind::Bar, + }; + out.push(MNode::Frac { kind, num, den }); + } + '^' | '_' => { + let pre = match out.last() { + None => true, + Some(MNode::Run(r)) => r.text == " " || r.text.chars().all(|c| is_boundary(c) && c != '#'), + _ => false, + }; + if pre { + out.push(self.prescript(stops)); + } else { + self.i += 1; + let s = self.script_operand(stops); + if out.last().is_some_and(too_deep) { + out.push(text(c)); + out.extend(s); + } else { + let base = out.pop(); + out.push(attach_script(base, c == '^', s)); + } + } + } + '┬' | '┴' => { + self.i += 1; + let lim = self.script_operand(stops); + if out.last().is_some_and(too_deep) { + out.push(text(c)); + out.extend(lim); + } else { + let e = out.pop().map(|n| vec![n]).unwrap_or_default(); + out.push(MNode::Lim { upper: c == '┴', e: strip_parens(e), lim }); + } + } + c if is_combining(c) => { + self.i += 1; + if out.last().is_some_and(too_deep) { + out.push(text(c)); + } else { + let e = out.pop().map(|n| strip_parens(vec![n])).unwrap_or_default(); + out.push(MNode::Acc { chr: c, e }); + } + } + '▒' | '\u{2061}' => self.i += 1, + ' ' => { + self.i += 1; + out.push(text(' ')); + } + _ => { + let atom = self.atom(stops); + out.extend(atom); + } + } + } + self.depth -= 1; + out + } + + /// One atom (a character, a bracket group, a structure or a function application). + fn atom(&mut self, stops: &[char]) -> Arg { + let Some(c) = self.peek() else { return Vec::new() }; + if let Some(close) = closer(c) { + self.i += 1; + return vec![self.group(Some(c), &[close])]; + } + if c == '├' { + self.i += 1; + if let Some(d) = self.explicit_group() { + return vec![d]; + } + return vec![self.group(None, &[')', ']', '}', '⟩', '⌉', '⌋', '|', '‖'])]; + } + if (c == '|' || c == '‖') && self.c.get(self.i + 1..).is_some_and(|r| r.contains(&c)) { + self.i += 1; + return vec![self.group(Some(c), &[c])]; + } + if is_prefix(c) { + self.i += 1; + return vec![self.prefix(c, stops)]; + } + if c.is_ascii_alphabetic() { + return self.word(stops); + } + self.i += 1; + vec![text(c)] + } + + /// A bracket group after its opening character; `closers` end it. + fn group(&mut self, open: Option, closers: &[char]) -> MNode { + let mut stops: Vec = closers.to_vec(); + stops.extend(['┤', '│']); + let mut elems = Vec::new(); + let mut end = None; + loop { + let e = self.expr(&stops); + elems.push(e); + match self.peek() { + Some('│') => self.i += 1, + Some('┤') => { + self.i += 1; + break; + } + Some(c) if closers.contains(&c) => { + self.i += 1; + end = Some(c); + break; + } + // Another closer: the group ends unclosed there. + _ => break, + } + if self.tired() { + break; + } + } + let beg = open.filter(|c| *c != '〖'); + let end = end.filter(|c| *c != '〗'); + let sep = if elems.len() > 1 { Some('|') } else { None }; + MNode::Delim { beg, end, sep, grow: true, shp_match: false, elems } + } + + /// `├X … Y┤`: brackets given explicitly (any bracket characters, either side optional), the + /// cursor just after `├`. `None` (cursor unchanged) when there's no matching `┤`. + fn explicit_group(&mut self) -> Option { + let mut level = 1usize; + let mut k = self.i; + while let Some(c) = self.c.get(k) { + match c { + '├' => level += 1, + '┤' => { + level -= 1; + if level == 0 { + break; + } + } + _ => {} + } + k += 1; + } + if level != 0 { + return None; + } + let bracket = |c: &char| matches!(c, '(' | ')' | '[' | ']' | '{' | '}' | '⟨' | '⟩' | '⌈' | '⌉' | '⌊' | '⌋' | '|' | '‖' | '⟦' | '⟧'); + let mut inner: Vec = self.c.get(self.i..k).unwrap_or(&[]).to_vec(); + self.i = k + 1; + let beg = if inner.first().is_some_and(bracket) { Some(inner.remove(0)) } else { None }; + // A closing bracket at the end that pairs with an opening one inside is content. + let paired = |inner: &[char]| -> bool { + let Some((last, body)) = inner.split_last() else { return false }; + let opener = match last { + ')' => '(', + ']' => '[', + '}' => '{', + '⟩' => '⟨', + '⌉' => '⌈', + '⌋' => '⌊', + '⟧' => '⟦', + _ => return false, + }; + body.iter().filter(|c| **c == opener).count() > body.iter().filter(|c| *c == last).count() + }; + let end = if !inner.is_empty() && inner.last().is_some_and(bracket) && !paired(&inner) { inner.pop() } else { None }; + let mut sub = P { c: inner, i: 0, depth: self.depth + 1, no_limits: 0, steps: self.steps }; + let mut elems = vec![Vec::new()]; + while sub.i < sub.c.len() { + if let Some(e) = elems.last_mut() { + e.extend(sub.expr(&['│'])); + } + match sub.peek() { + Some('│') => { + sub.i += 1; + elems.push(Vec::new()); + } + Some(c) => { + sub.i += 1; + if let Some(e) = elems.last_mut() { + e.push(text(c)); + } + } + None => {} + } + if sub.tired() { + break; + } + } + self.steps = sub.steps; + let sep = if elems.len() > 1 { Some('|') } else { None }; + Some(MNode::Delim { beg, end, sep, grow: true, shp_match: false, elems }) + } + + /// A prefix structure after its character. + fn prefix(&mut self, c: char, stops: &[char]) -> MNode { + match c { + '√'..='∜' => { + let mut deg = match c { + '∛' => vec![text('3')], + '∜' => vec![text('4')], + _ => Vec::new(), + }; + let mut e = self.operand(stops); + if let Some(k) = e.iter().position(|n| matches!(n, MNode::Run(r) if r.text == "&")) { + let rest = e.split_off(k + 1); + e.pop(); + deg = e; + e = rest; + } + MNode::Rad { deg_hide: deg.is_empty(), deg, e } + } + '█' | '■' => { + if self.peek() == Some('(') { + self.i += 1; + let inner = self.expr(&[')']); + if self.peek() == Some(')') { + self.i += 1; + } + grid(c == '■', inner) + } else { + text(c) + } + } + '▭' => MNode::BorderBox { hide: [false; 4], strike: [false; 4], e: self.operand(stops) }, + '□' => MNode::Boxed { e: self.operand(stops) }, + '¯' => MNode::Bar { top: true, e: self.operand(stops) }, + '▁' => MNode::Bar { top: false, e: self.operand(stops) }, + '⟡' => MNode::Phant { show: false, zero_wid: false, zero_asc: false, zero_desc: false, e: self.operand(stops) }, + // A label (`┴`/`┬`) after the operand belongs to the whole brace. + '⏞' | '⏜' | '⎴' | '⏟' | '⏝' | '⎵' => { + self.no_limits += 1; + let e = self.operand(stops); + self.no_limits -= 1; + MNode::GroupChr { chr: c, top: matches!(c, '⏞' | '⏜' | '⎴'), e } + } + _ => { + // N-ary operator: limits, then the operand. + let (mut sub, mut sup) = (Vec::new(), Vec::new()); + let (mut has_sub, mut has_sup) = (false, false); + loop { + match self.peek() { + Some('_') => { + self.i += 1; + sub = self.script_operand(stops); + has_sub = true; + } + Some('^') => { + self.i += 1; + sup = self.script_operand(stops); + has_sup = true; + } + _ => break, + } + } + if self.peek() == Some('▒') { + self.i += 1; + } + let e = if self.peek().is_some_and(|c| c == ' ') { Vec::new() } else { self.operand(stops) }; + MNode::Nary { chr: c, lim_loc: None, grow: false, sub_hide: !has_sub, sup_hide: !has_sup, sub, sup, e } + } + } + } + + /// Letters: a function application when they spell a function name, else one letter. + fn word(&mut self, stops: &[char]) -> Arg { + let start = self.i; + let mut end = start; + // Look no further than the longest name (and one past it, to see the run is longer): a + // scan to the end of every run made a long run of letters quadratic (CWE-407). + while end - start <= MAX_NAME && self.c.get(end).is_some_and(char::is_ascii_alphabetic) { + end += 1; + } + let word: String = if end - start > MAX_NAME { String::new() } else { self.c.get(start..end).unwrap_or(&[]).iter().collect() }; + if !FUNCTION_NAMES.contains(&word.as_str()) { + self.i = start + 1; + return vec![text(self.c.get(start).copied().unwrap_or(' '))]; + } + self.i = end; + let plain = vec![MNode::Run(MRun::plain(word.clone()))]; + // Limits and scripts on the name. + let name = match self.peek() { + Some('┬') | Some('┴') => { + let upper = self.peek() == Some('┴'); + self.i += 1; + let lim = self.script_operand(stops); + vec![MNode::Lim { upper, e: plain, lim }] + } + Some('_') if LIMIT_NAMES.contains(&word.as_str()) => { + self.i += 1; + let lim = self.script_operand(stops); + vec![MNode::Lim { upper: false, e: plain, lim }] + } + Some(c @ ('^' | '_')) => { + self.i += 1; + let s = self.script_operand(stops); + let mut n = attach_script(Some(MNode::Run(MRun::plain(word.clone()))), c == '^', s); + if let Some(c2 @ ('^' | '_')) = self.peek() { + self.i += 1; + let s2 = self.script_operand(stops); + n = attach_script(Some(n), c2 == '^', s2); + } + vec![n] + } + _ => plain, + }; + // The operand, after an optional space or function-application mark. + if matches!(self.peek(), Some(' ') | Some('\u{2061}') | Some('▒')) { + self.i += 1; + } + let next = self.peek(); + let applies = next.is_some_and(|c| !stops.contains(&c) && !is_closer(c) && (!is_boundary(c) || c == '(' || matches!(c, '−' | '-' | '+'))); + if !applies { + return name; + } + let e = self.operand(stops); + if e.is_empty() { + return name; + } + vec![MNode::Func { name, e }] + } + + /// Pre-scripts (`_a^b x`): the scripts, then the base. + fn prescript(&mut self, stops: &[char]) -> MNode { + let (mut sub, mut sup) = (Vec::new(), Vec::new()); + while let Some(c @ ('^' | '_')) = self.peek() { + self.i += 1; + let s = self.script_operand(stops); + if c == '^' { + sup = s; + } else { + sub = s; + } + } + if self.peek() == Some('▒') { + self.i += 1; + } + let base = self.operand(stops); + MNode::Script { kind: ScriptKind::Pre, base, sub, sup } + } + + /// An operand: a parenthesised group (parentheses dropped) or a run of atoms with their + /// postfix scripts, accents and limits, up to an operator or space. + fn operand(&mut self, stops: &[char]) -> Arg { + if self.tired() { + return self.rest(); + } + self.depth += 1; + let mut out: Arg = Vec::new(); + if self.peek() == Some('(') { + self.i += 1; + let g = self.group(Some('('), &[')']); + let inner = match g { + MNode::Delim { elems, end: Some(')'), .. } if elems.len() == 1 => elems.into_iter().next().unwrap_or_default(), + other => vec![other], + }; + out = inner; + self.postfix(&mut out, stops, true); + } else if self.peek() == Some('〖') { + self.i += 1; + let g = self.group(Some('〖'), &['〗']); + out = match g { + MNode::Delim { elems, .. } if elems.len() == 1 => elems.into_iter().next().unwrap_or_default(), + other => vec![other], + }; + self.postfix(&mut out, stops, true); + } else { + // A signed operand (`e^-x`, `−b`). + if let Some(c @ ('−' | '-' | '+' | '±' | '∓')) = self.peek() + && self.peek_at(1).is_some_and(|n| !is_boundary(n)) + { + self.i += 1; + out.push(text(c)); + } + while let Some(c) = self.peek() { + if stops.contains(&c) || is_boundary(c) || self.tired() { + break; + } + let a = self.atom(stops); + if a.is_empty() { + break; + } + out.extend(a); + self.postfix(&mut out, stops, false); + } + if out.is_empty() + && let Some(c) = self.peek() + && c != ' ' + && !stops.contains(&c) + && !is_closer(c) + && !matches!(c, '/' | '⁄' | '∕' | '¦' | '&' | '@' | '#' | '│' | '▒') + { + // A lone operator as operand. + self.i += 1; + out.push(text(c)); + } + } + self.depth -= 1; + out + } + + /// Postfix operators on the last atom of `out` (`whole`: on all of `out` as one group). + fn postfix(&mut self, out: &mut Arg, stops: &[char], whole: bool) { + while let Some(c) = self.peek() { + if self.tired() { + break; + } + let base = |out: &mut Arg| -> Option { + if whole && out.len() != 1 { + if out.is_empty() { + return None; + } + return Some(MNode::Delim { beg: None, end: None, sep: None, grow: true, shp_match: false, elems: vec![std::mem::take(out)] }); + } + out.pop() + }; + if !(matches!(c, '^' | '_') || matches!(c, '┬' | '┴') && self.no_limits == 0 || is_combining(c)) { + break; + } + // The base is already deep: the operator is text (see `too_deep`). + let deep = if whole { any_too_deep(out) } else { out.last().is_some_and(too_deep) }; + self.i += 1; + if deep { + let s = if matches!(c, '^' | '_' | '┬' | '┴') { self.script_operand(stops) } else { Vec::new() }; + out.push(text(c)); + out.extend(s); + continue; + } + match c { + '^' | '_' => { + let s = self.script_operand(stops); + let b = base(out); + out.push(attach_script(b, c == '^', s)); + } + '┬' | '┴' => { + let lim = self.script_operand(stops); + let b = base(out); + out.push(MNode::Lim { upper: c == '┴', e: b.map(|n| vec![n]).unwrap_or_default(), lim }); + } + _ => { + let b = base(out); + out.push(MNode::Acc { chr: c, e: b.map(|n| strip_parens(vec![n])).unwrap_or_default() }); + } + } + } + } + + /// A script or limit: a parenthesised group, a structure, a number, a signed operand, a run of + /// letters (and digits) or one other character. + fn script_operand(&mut self, stops: &[char]) -> Arg { + if self.tired() { + return self.rest(); + } + self.depth += 1; + let out = match self.peek() { + Some('(') => { + self.i += 1; + match self.group(Some('('), &[')']) { + MNode::Delim { elems, end: Some(')'), .. } if elems.len() == 1 => elems.into_iter().next().unwrap_or_default(), + other => vec![other], + } + } + Some('〖') => { + self.i += 1; + match self.group(Some('〖'), &['〗']) { + MNode::Delim { elems, .. } if elems.len() == 1 => elems.into_iter().next().unwrap_or_default(), + other => vec![other], + } + } + Some(c) if is_prefix(c) || closer(c).is_some() => self.atom(stops), + Some(c) if c.is_ascii_digit() => { + let start = self.i; + while self.peek().is_some_and(|k| k.is_alphanumeric() || k == '.') { + self.i += 1; + } + let t: String = self.c.get(start..self.i).unwrap_or(&[]).iter().collect(); + vec![MNode::Run(MRun::new(t))] + } + Some(c @ ('−' | '-' | '+' | '±' | '∓')) if self.peek_at(1).is_some_and(|n| !is_boundary(n)) => { + self.i += 1; + let mut v = vec![text(c)]; + v.extend(self.script_operand(stops)); + v + } + Some(c) if c.is_alphabetic() => { + // Word (#1609): the whole run of letters and digits up to a space or operator, so + // `V_dd` is V with a subscript `dd`, exactly like `V_(dd)`. + let start = self.i; + while self.peek().is_some_and(char::is_alphanumeric) { + self.i += 1; + } + let t: String = self.c.get(start..self.i).unwrap_or(&[]).iter().collect(); + // A known function name stays upright, as Word builds it. + vec![MNode::Run(if FUNCTION_NAMES.contains(&t.as_str()) { MRun::plain(t) } else { MRun::new(t) })] + } + Some(c) if !stops.contains(&c) && c != ' ' && !is_closer(c) => { + self.i += 1; + vec![text(c)] + } + _ => Vec::new(), + }; + self.depth -= 1; + out + } +} + +/// Where the trailing operand of `out` starts (after the last operator or space). +fn operand_start(out: &[MNode]) -> usize { + let mut k = out.len(); + while k > 0 { + match out.get(k - 1) { + Some(MNode::Run(r)) if r.text.chars().all(is_boundary) => break, + _ => k -= 1, + } + } + k +} + +/// A single parenthesised group used as an operand loses its parentheses. +pub fn strip_parens(mut a: Arg) -> Arg { + if a.len() == 1 + && let Some(MNode::Delim { beg: Some('('), end: Some(')'), elems, .. } | MNode::Delim { beg: None, end: None, elems, .. }) = a.first_mut() + && elems.len() == 1 + { + return elems.pop().unwrap_or_default(); + } + a +} + +fn attach_script(base: Option, sup: bool, s: Arg) -> MNode { + match base { + Some(MNode::Script { kind: ScriptKind::Sub, base, sub, .. }) if sup => MNode::Script { kind: ScriptKind::SubSup, base, sub, sup: s }, + Some(MNode::Script { kind: ScriptKind::Sup, base, sup: sp, .. }) if !sup => MNode::Script { kind: ScriptKind::SubSup, base, sub: s, sup: sp }, + b => { + let base = b.map(|b| vec![b]).unwrap_or_default(); + if sup { + MNode::Script { kind: ScriptKind::Sup, base, sub: Vec::new(), sup: s } + } else { + MNode::Script { kind: ScriptKind::Sub, base, sub: s, sup: Vec::new() } + } + } + } +} + +/// `█(a@b)` equation array / `■(a&b@c&d)` matrix from the parsed inside. +fn grid(matrix: bool, inner: Arg) -> MNode { + let mut rows: Vec> = vec![vec![Vec::new()]]; + for n in inner { + match &n { + MNode::Run(r) if r.text == "@" => rows.push(vec![Vec::new()]), + MNode::Run(r) if r.text == "&" && matrix => { + if let Some(row) = rows.last_mut() { + row.push(Vec::new()); + } + } + _ => { + if let Some(cell) = rows.last_mut().and_then(|r| r.last_mut()) { + cell.push(n); + } + } + } + } + if matrix { + MNode::Matrix { rows, col_jc: Vec::new() } + } else { + MNode::EqArr { rows: rows.into_iter().map(|r| r.into_iter().flatten().collect()).collect() } + } +} + +/// Drop placeholders and build-up spaces, merge runs; recursively. +fn clean(a: Arg) -> Arg { + let mut out = Vec::with_capacity(a.len()); + for n in a { + match n { + MNode::Run(r) if r.text == " " || r.text.chars().all(|c| c == PLACEHOLDER) => {} + other => out.push(map_args(other, &clean)), + } + } + merge_runs(out) +} + +/// Apply `f` to every argument of a node. +pub fn map_args(n: MNode, f: &dyn Fn(Arg) -> Arg) -> MNode { + match n { + MNode::Run(r) => MNode::Run(r), + MNode::Frac { kind, num, den } => MNode::Frac { kind, num: f(num), den: f(den) }, + MNode::Script { kind, base, sub, sup } => MNode::Script { kind, base: f(base), sub: f(sub), sup: f(sup) }, + MNode::Rad { deg, deg_hide, e } => MNode::Rad { deg: f(deg), deg_hide, e: f(e) }, + MNode::Nary { chr, lim_loc, grow, sub_hide, sup_hide, sub, sup, e } => { + MNode::Nary { chr, lim_loc, grow, sub_hide, sup_hide, sub: f(sub), sup: f(sup), e: f(e) } + } + MNode::Delim { beg, end, sep, grow, shp_match, elems } => { + MNode::Delim { beg, end, sep, grow, shp_match, elems: elems.into_iter().map(f).collect() } + } + MNode::Func { name, e } => MNode::Func { name: f(name), e: f(e) }, + MNode::Lim { upper, e, lim } => MNode::Lim { upper, e: f(e), lim: f(lim) }, + MNode::Acc { chr, e } => MNode::Acc { chr, e: f(e) }, + MNode::Bar { top, e } => MNode::Bar { top, e: f(e) }, + MNode::BorderBox { hide, strike, e } => MNode::BorderBox { hide, strike, e: f(e) }, + MNode::Boxed { e } => MNode::Boxed { e: f(e) }, + MNode::GroupChr { chr, top, e } => MNode::GroupChr { chr, top, e: f(e) }, + MNode::EqArr { rows } => MNode::EqArr { rows: rows.into_iter().map(f).collect() }, + MNode::Matrix { rows, col_jc } => MNode::Matrix { rows: rows.into_iter().map(|r| r.into_iter().map(f).collect()).collect(), col_jc }, + MNode::Phant { show, zero_wid, zero_asc, zero_desc, e } => MNode::Phant { show, zero_wid, zero_asc, zero_desc, e: f(e) }, + } +} diff --git a/crates/math/src/math_symbols.rs b/crates/math/src/math_symbols.rs new file mode 100644 index 000000000..279ffd2ca --- /dev/null +++ b/crates/math/src/math_symbols.rs @@ -0,0 +1,399 @@ +//! Named math characters: Math AutoCorrect while typing in an equation (`\alpha` + space → α) +//! and LaTeX conversion. Names are the usual TeX names plus the linear-format operators +//! (`\sqrt` → √, `\above` → ┴, `\matrix` → ■…). + +/// (name without the backslash, character). When a character has several names the first one +/// listed is the one LaTeX output uses. +pub const SYMBOLS: &[(&str, char)] = &[ + // Greek. + ("alpha", 'α'), + ("beta", 'β'), + ("gamma", 'γ'), + ("delta", 'δ'), + ("epsilon", 'ϵ'), + ("varepsilon", 'ε'), + ("zeta", 'ζ'), + ("eta", 'η'), + ("theta", 'θ'), + ("vartheta", 'ϑ'), + ("iota", 'ι'), + ("kappa", 'κ'), + ("varkappa", 'ϰ'), + ("lambda", 'λ'), + ("mu", 'μ'), + ("nu", 'ν'), + ("xi", 'ξ'), + ("omicron", 'ο'), + ("pi", 'π'), + ("varpi", 'ϖ'), + ("rho", 'ρ'), + ("varrho", 'ϱ'), + ("sigma", 'σ'), + ("varsigma", 'ς'), + ("tau", 'τ'), + ("upsilon", 'υ'), + ("phi", 'ϕ'), + ("varphi", 'φ'), + ("chi", 'χ'), + ("psi", 'ψ'), + ("omega", 'ω'), + ("Alpha", 'Α'), + ("Beta", 'Β'), + ("Gamma", 'Γ'), + ("Delta", 'Δ'), + ("Epsilon", 'Ε'), + ("Zeta", 'Ζ'), + ("Eta", 'Η'), + ("Theta", 'Θ'), + ("Iota", 'Ι'), + ("Kappa", 'Κ'), + ("Lambda", 'Λ'), + ("Mu", 'Μ'), + ("Nu", 'Ν'), + ("Xi", 'Ξ'), + ("Omicron", 'Ο'), + ("Pi", 'Π'), + ("Rho", 'Ρ'), + ("Sigma", 'Σ'), + ("Tau", 'Τ'), + ("Upsilon", 'Υ'), + ("Phi", 'Φ'), + ("Chi", 'Χ'), + ("Psi", 'Ψ'), + ("Omega", 'Ω'), + ("digamma", 'ϝ'), + // Binary operators. + ("pm", '±'), + ("mp", '∓'), + ("times", '×'), + ("div", '÷'), + ("cdot", '⋅'), + ("bullet", '∙'), + ("ast", '∗'), + ("star", '⋆'), + ("circ", '∘'), + ("oplus", '⊕'), + ("ominus", '⊖'), + ("otimes", '⊗'), + ("oslash", '⊘'), + ("odot", '⊙'), + ("cup", '∪'), + ("cap", '∩'), + ("uplus", '⊎'), + ("sqcup", '⊔'), + ("sqcap", '⊓'), + ("vee", '∨'), + ("wedge", '∧'), + ("setminus", '∖'), + ("backslash", '\\'), + ("wr", '≀'), + ("diamond", '⋄'), + ("dagger", '†'), + ("ddagger", '‡'), + ("amalg", '⨿'), + ("dotplus", '∔'), + ("ltimes", '⋉'), + ("rtimes", '⋊'), + // Relations. + ("le", '≤'), + ("leq", '≤'), + ("ge", '≥'), + ("geq", '≥'), + ("ne", '≠'), + ("neq", '≠'), + ("approx", '≈'), + ("equiv", '≡'), + ("sim", '∼'), + ("simeq", '≃'), + ("cong", '≅'), + ("propto", '∝'), + ("ll", '≪'), + ("gg", '≫'), + ("prec", '≺'), + ("succ", '≻'), + ("preceq", '≼'), + ("succeq", '≽'), + ("subset", '⊂'), + ("supset", '⊃'), + ("subseteq", '⊆'), + ("supseteq", '⊇'), + ("sqsubseteq", '⊑'), + ("sqsupseteq", '⊒'), + ("in", '∈'), + ("ni", '∋'), + ("notin", '∉'), + ("perp", '⊥'), + ("parallel", '∥'), + ("mid", '∣'), + ("nmid", '∤'), + ("asymp", '≍'), + ("doteq", '≐'), + ("models", '⊨'), + ("vdash", '⊢'), + ("dashv", '⊣'), + ("bowtie", '⋈'), + ("coloneq", '≔'), + ("defeq", '≝'), + ("triangleq", '≜'), + ("nless", '≮'), + ("ngtr", '≯'), + ("nleq", '≰'), + ("ngeq", '≱'), + ("nsim", '≁'), + ("ncong", '≇'), + ("nequiv", '≢'), + ("nsubset", '⊄'), + ("nsupset", '⊅'), + ("nsubseteq", '⊈'), + ("nsupseteq", '⊉'), + ("subsetneq", '⊊'), + ("supsetneq", '⊋'), + ("lesssim", '≲'), + ("gtrsim", '≳'), + ("therefore", '∴'), + ("because", '∵'), + // Arrows. + ("rightarrow", '→'), + ("to", '→'), + ("leftarrow", '←'), + ("gets", '←'), + ("leftrightarrow", '↔'), + ("uparrow", '↑'), + ("downarrow", '↓'), + ("updownarrow", '↕'), + ("Rightarrow", '⇒'), + ("Leftarrow", '⇐'), + ("Leftrightarrow", '⇔'), + ("Uparrow", '⇑'), + ("Downarrow", '⇓'), + ("Updownarrow", '⇕'), + ("longrightarrow", '⟶'), + ("longleftarrow", '⟵'), + ("longleftrightarrow", '⟷'), + ("Longrightarrow", '⟹'), + ("Longleftarrow", '⟸'), + ("Longleftrightarrow", '⟺'), + ("implies", '⟹'), + ("iff", '⟺'), + ("mapsto", '↦'), + ("longmapsto", '⟼'), + ("nearrow", '↗'), + ("searrow", '↘'), + ("swarrow", '↙'), + ("nwarrow", '↖'), + ("hookleftarrow", '↩'), + ("hookrightarrow", '↪'), + ("leftharpoonup", '↼'), + ("leftharpoondown", '↽'), + ("rightharpoonup", '⇀'), + ("rightharpoondown", '⇁'), + ("rightleftharpoons", '⇌'), + ("leftrightharpoons", '⇋'), + ("circlearrowleft", '↺'), + ("circlearrowright", '↻'), + // Big operators. + ("sum", '∑'), + ("prod", '∏'), + ("coprod", '∐'), + ("int", '∫'), + ("iint", '∬'), + ("iiint", '∭'), + ("oint", '∮'), + ("oiint", '∯'), + ("oiiint", '∰'), + ("bigcup", '⋃'), + ("bigcap", '⋂'), + ("bigvee", '⋁'), + ("bigwedge", '⋀'), + ("bigoplus", '⨁'), + ("bigotimes", '⨂'), + ("bigodot", '⨀'), + ("biguplus", '⨄'), + ("bigsqcup", '⨆'), + // Brackets. + ("langle", '⟨'), + ("rangle", '⟩'), + ("lceil", '⌈'), + ("rceil", '⌉'), + ("lfloor", '⌊'), + ("rfloor", '⌋'), + ("lbrack", '['), + ("rbrack", ']'), + ("lbrace", '{'), + ("rbrace", '}'), + ("Vert", '‖'), + ("norm", '‖'), + ("vert", '|'), + ("lbbrack", '⟦'), + ("rbbrack", '⟧'), + // Miscellaneous. + ("infty", '∞'), + ("partial", '∂'), + ("nabla", '∇'), + ("forall", '∀'), + ("exists", '∃'), + ("nexists", '∄'), + ("neg", '¬'), + ("lnot", '¬'), + ("emptyset", '∅'), + ("varnothing", '∅'), + ("hbar", 'ℏ'), + ("ell", 'ℓ'), + ("Re", 'ℜ'), + ("Im", 'ℑ'), + ("wp", '℘'), + ("aleph", 'ℵ'), + ("beth", 'ℶ'), + ("gimel", 'ℷ'), + ("daleth", 'ℸ'), + ("degree", '°'), + ("angle", '∠'), + ("measuredangle", '∡'), + ("sphericalangle", '∢'), + ("rightangle", '∟'), + ("triangle", '△'), + ("square", '□'), + ("blacksquare", '■'), + ("qed", '∎'), + ("top", '⊤'), + ("bot", '⊥'), + ("cdots", '⋯'), + ("ldots", '…'), + ("dots", '…'), + ("vdots", '⋮'), + ("ddots", '⋱'), + ("adots", '⋰'), + ("prime", '′'), + ("dprime", '″'), + ("trprime", '‴'), + ("dd", 'ⅆ'), + ("Dd", 'ⅅ'), + ("ee", 'ⅇ'), + ("ii", 'ⅈ'), + ("jj", 'ⅉ'), + ("imath", 'ı'), + ("jmath", 'ȷ'), + ("complement", '∁'), + ("Angstrom", 'Å'), + ("mho", '℧'), + ("eth", 'ð'), + ("flat", '♭'), + ("natural", '♮'), + ("sharp", '♯'), + ("clubsuit", '♣'), + ("diamondsuit", '♢'), + ("heartsuit", '♡'), + ("spadesuit", '♠'), + // Spaces. + ("quad", '\u{2003}'), + ("emsp", '\u{2003}'), + ("ensp", '\u{2002}'), + ("thicksp", '\u{2005}'), + ("medsp", '\u{205F}'), + ("thinsp", '\u{2009}'), + ("hairsp", '\u{200A}'), + ("nbsp", '\u{A0}'), + ("zwsp", '\u{200B}'), + // Linear-format operators (build-up). + ("sqrt", '√'), + ("cbrt", '∛'), + ("qdrt", '∜'), + ("matrix", '■'), + ("eqarray", '█'), + ("above", '┴'), + ("below", '┬'), + ("of", '▒'), + ("naryand", '▒'), + ("funcapply", '\u{2061}'), + ("box", '□'), + ("rect", '▭'), + ("overbar", '¯'), + ("underbar", '▁'), + ("phantom", '⟡'), + ("overbrace", '⏞'), + ("underbrace", '⏟'), + ("overparen", '⏜'), + ("underparen", '⏝'), + ("atop", '¦'), + ("over", '/'), + ("ldiv", '∕'), + ("sdiv", '⁄'), + ("begin", '〖'), + ("end", '〗'), + ("left", '├'), + ("right", '┤'), + ("eqno", '#'), + ("placeholder", '⬚'), + // Accents (combining, typed after the base). + ("hat", '\u{302}'), + ("check", '\u{30C}'), + ("tilde", '\u{303}'), + ("acute", '\u{301}'), + ("grave", '\u{300}'), + ("dot", '\u{307}'), + ("ddot", '\u{308}'), + ("dddot", '\u{20DB}'), + ("breve", '\u{306}'), + ("bar", '\u{305}'), + ("Bar", '\u{33F}'), + ("vec", '\u{20D7}'), + ("tvec", '\u{20E1}'), + ("lhvec", '\u{20D0}'), + ("hvec", '\u{20D1}'), + // Other spellings (after the names the writer uses, which come first). + ("nparallel", '∦'), + ("backprime", '‵'), + ("lvert", '|'), + ("rvert", '|'), + ("lVert", '‖'), + ("rVert", '‖'), + ("infinity", '∞'), + ("cross", '×'), +]; + +/// The character for a name (`alpha` → α), including `doubleR`, `scriptL`, `frakturg`. +pub fn symbol(name: &str) -> Option { + if let Some((_, c)) = SYMBOLS.iter().find(|(n, _)| *n == name) { + return Some(*c); + } + for (prefix, scr) in [("double", crate::math::MScr::DoubleStruck), ("script", crate::math::MScr::Script), ("fraktur", crate::math::MScr::Fraktur)] + { + if let Some(rest) = name.strip_prefix(prefix) { + let mut cs = rest.chars(); + if let (Some(c), None) = (cs.next(), cs.next()) + && c.is_ascii_alphanumeric() + { + let m = crate::math::math_alnum(c, false, false, scr); + if m != c { + return Some(m); + } + } + } + } + None +} + +/// The (first) name of a character. +pub fn name_of(c: char) -> Option<&'static str> { + SYMBOLS.iter().find(|(_, s)| *s == c).map(|(n, _)| *n) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn names_resolve() { + assert_eq!(symbol("alpha"), Some('α')); + assert_eq!(symbol("doubleR"), Some('ℝ')); + assert_eq!(symbol("scriptL"), Some('ℒ')); + assert_eq!(symbol("nonesuch"), None); + assert_eq!(name_of('≤'), Some("le")); + // No name is listed twice. + let mut names: Vec<&str> = SYMBOLS.iter().map(|(n, _)| *n).collect(); + names.sort_unstable(); + let before = names.len(); + names.dedup(); + assert_eq!(before, names.len()); + } +} diff --git a/crates/math/src/math_tree.rs b/crates/math/src/math_tree.rs new file mode 100644 index 000000000..45d2c603a --- /dev/null +++ b/crates/math/src/math_tree.rs @@ -0,0 +1,104 @@ +//! Structural access to an equation tree: the arguments of a node, and every run in a tree. + +use crate::math::{Arg, MAX_DEPTH, MNode, MRun}; + +/// Number of child arguments of a node. +pub fn child_count(n: &MNode) -> usize { + match n { + MNode::Run(_) => 0, + MNode::Frac { .. } | MNode::Func { .. } | MNode::Lim { .. } => 2, + MNode::Rad { .. } => 2, + MNode::Script { .. } | MNode::Nary { .. } => 3, + MNode::Delim { elems, .. } => elems.len(), + MNode::EqArr { rows } => rows.len(), + MNode::Matrix { rows, .. } => rows.iter().map(|r| r.len()).sum(), + MNode::Acc { .. } | MNode::Bar { .. } | MNode::BorderBox { .. } | MNode::Boxed { .. } | MNode::GroupChr { .. } | MNode::Phant { .. } => 1, + } +} + +/// Child argument `i` of a node (see [`child_count`] for the numbering: fraction num 0 / den 1; +/// script base 0 / sub 1 / sup 2; radical degree 0 / base 1; n-ary sub 0 / sup 1 / operand 2; +/// function name 0 / argument 1; limit base 0 / limit 1; matrices row by row). +pub fn child(n: &MNode, i: usize) -> Option<&Arg> { + match (n, i) { + (MNode::Frac { num, .. }, 0) => Some(num), + (MNode::Frac { den, .. }, 1) => Some(den), + (MNode::Script { base, .. }, 0) => Some(base), + (MNode::Script { sub, .. }, 1) => Some(sub), + (MNode::Script { sup, .. }, 2) => Some(sup), + (MNode::Rad { deg, .. }, 0) => Some(deg), + (MNode::Rad { e, .. }, 1) => Some(e), + (MNode::Nary { sub, .. }, 0) => Some(sub), + (MNode::Nary { sup, .. }, 1) => Some(sup), + (MNode::Nary { e, .. }, 2) => Some(e), + (MNode::Delim { elems, .. }, i) => elems.get(i), + (MNode::Func { name, .. }, 0) => Some(name), + (MNode::Func { e, .. }, 1) => Some(e), + (MNode::Lim { e, .. }, 0) => Some(e), + (MNode::Lim { lim, .. }, 1) => Some(lim), + ( + MNode::Acc { e, .. } + | MNode::Bar { e, .. } + | MNode::BorderBox { e, .. } + | MNode::Boxed { e } + | MNode::GroupChr { e, .. } + | MNode::Phant { e, .. }, + 0, + ) => Some(e), + (MNode::EqArr { rows }, i) => rows.get(i), + (MNode::Matrix { rows, .. }, i) => rows.iter().flatten().nth(i), + _ => None, + } +} + +pub fn child_mut(n: &mut MNode, i: usize) -> Option<&mut Arg> { + match (n, i) { + (MNode::Frac { num, .. }, 0) => Some(num), + (MNode::Frac { den, .. }, 1) => Some(den), + (MNode::Script { base, .. }, 0) => Some(base), + (MNode::Script { sub, .. }, 1) => Some(sub), + (MNode::Script { sup, .. }, 2) => Some(sup), + (MNode::Rad { deg, .. }, 0) => Some(deg), + (MNode::Rad { e, .. }, 1) => Some(e), + (MNode::Nary { sub, .. }, 0) => Some(sub), + (MNode::Nary { sup, .. }, 1) => Some(sup), + (MNode::Nary { e, .. }, 2) => Some(e), + (MNode::Delim { elems, .. }, i) => elems.get_mut(i), + (MNode::Func { name, .. }, 0) => Some(name), + (MNode::Func { e, .. }, 1) => Some(e), + (MNode::Lim { e, .. }, 0) => Some(e), + (MNode::Lim { lim, .. }, 1) => Some(lim), + ( + MNode::Acc { e, .. } + | MNode::Bar { e, .. } + | MNode::BorderBox { e, .. } + | MNode::Boxed { e } + | MNode::GroupChr { e, .. } + | MNode::Phant { e, .. }, + 0, + ) => Some(e), + (MNode::EqArr { rows }, i) => rows.get_mut(i), + (MNode::Matrix { rows, .. }, i) => rows.iter_mut().flatten().nth(i), + _ => None, + } +} + +/// Call `f` on every run in the tree. +pub fn each_run_mut(root: &mut Arg, f: &mut dyn FnMut(&mut MRun)) { + fn go(a: &mut Arg, f: &mut dyn FnMut(&mut MRun), depth: usize) { + if depth > MAX_DEPTH { + return; + } + for n in a.iter_mut() { + if let MNode::Run(r) = n { + f(r); + } + for c in 0..child_count(n) { + if let Some(ch) = child_mut(n, c) { + go(ch, f, depth + 1); + } + } + } + } + go(root, f, 0); +} diff --git a/crates/math/src/mathml.rs b/crates/math/src/mathml.rs new file mode 100644 index 000000000..9dc2433ac --- /dev/null +++ b/crates/math/src/mathml.rs @@ -0,0 +1,1080 @@ +//! Equations as MathML (W3C MathML Core / Presentation MathML): written into HTML export and the +//! HTML a copy puts on the system clipboard, so programs that read MathML can get a formatted +//! equation instead of its linear text (#816); for a copy of one equation alone, the text of the +//! platform's MathML clipboard formats, which Word reads first when it pastes math (#1297; +//! pasting into Word and LibreOffice not yet verified); and read back from pasted or opened HTML. +//! +//! The writer walks the equation tree ([`MNode`]) and wraps it in `` with the linear +//! format as an `application/x-unicodemath` annotation, which renderers ignore and WordCraft reads +//! back exactly. The reader takes that annotation when present, else a TeX annotation, else +//! builds the tree from the presentation elements (fractions, scripts, radicals, under/over +//! limits, tables, fences); both bound their nesting and size. + +use crate::math::{ + Arg, ColJc, FracKind, LimLoc, MAX_DEPTH, MClass, MNode, MRun, MScr, MSty, ScriptKind, is_integral, is_nary_char, math_alnum, math_class, + to_linear, +}; +use crate::math_linear::FUNCTION_NAMES; + +/// Escape text for HTML or XML content and attribute values. +fn esc(s: &str) -> String { + let mut o = String::with_capacity(s.len() + 8); + for c in s.chars() { + match c { + '&' => o.push_str("&"), + '<' => o.push_str("<"), + '>' => o.push_str(">"), + '"' => o.push_str("""), + '\u{000C}' | '\u{000E}' => {} + _ => o.push(c), + } + } + o +} + +/// The MathML namespace. +pub const NS: &str = "http://www.w3.org/1998/Math/MathML"; +/// The annotation encoding carrying the linear format (UnicodeMath). +pub const UNICODEMATH: &str = "application/x-unicodemath"; + +// --------------------------------------------------------------------------------------------- +// Writer + +/// An equation as a `` element. `linear` (the linear format) goes in an annotation for an +/// exact round trip; empty = taken from the tree. +pub fn to_mathml(nodes: &[MNode], display: bool, linear: &str) -> String { + let mut o = String::new(); + o.push_str(&format!(""); + arg(nodes, &mut o, 0, false); + o.push_str(""); + let linear = if linear.is_empty() { to_linear(nodes) } else { linear.to_string() }; + if !linear.is_empty() { + o.push_str(&format!("{}", esc(&linear))); + } + o.push_str(""); + o +} + +/// An equation known by its linear format, as a `` element. +pub fn linear_to_mathml(linear: &str, display: bool) -> String { + to_mathml(&crate::math::parse_linear(linear), display, linear) +} + +/// An argument as a row of elements. `eq_arr`: a row of an equation array, whose `&` marks are +/// alignment points, not text. +fn arg(a: &[MNode], o: &mut String, depth: usize, eq_arr: bool) { + if depth > MAX_DEPTH { + return; + } + for n in a { + node(n, o, depth + 1, eq_arr); + } +} + +/// An argument as one element (`` around several). +fn group(a: &[MNode], o: &mut String, depth: usize) { + o.push_str(""); + arg(a, o, depth, false); + o.push_str(""); +} + +fn mo(c: char, attrs: &str, o: &mut String) { + o.push_str(&format!("{}", esc(&c.to_string()))); +} + +fn run(r: &MRun, o: &mut String, eq_arr: bool) { + let color = r.color.map(|c| format!(" mathcolor=\"#{}\"", c.hex())).unwrap_or_default(); + if r.nor { + if !r.text.is_empty() { + o.push_str(&format!("{}", esc(&r.text))); + } + return; + } + let bold = matches!(r.sty, Some(MSty::Bold | MSty::BoldItalic)); + let italic = match r.sty { + None => r.scr == MScr::Roman, + Some(s) => matches!(s, MSty::Italic | MSty::BoldItalic), + }; + let cs: Vec = r.text.chars().collect(); + let mut i = 0; + while let Some(&c) = cs.get(i) { + if c.is_ascii_digit() || (c == '.' && cs.get(i + 1).is_some_and(char::is_ascii_digit)) { + let mut num = String::new(); + while let Some(&d) = + cs.get(i).filter(|d| d.is_ascii_digit() || **d == '.' || **d == ',' && cs.get(i + 1).is_some_and(char::is_ascii_digit)) + { + num.push(d); + i += 1; + } + let num: String = if bold { num.chars().map(|d| math_alnum(d, true, false, MScr::Roman)).collect() } else { num }; + o.push_str(&format!("{}", esc(&num))); + continue; + } + i += 1; + if c.is_whitespace() || (eq_arr && c == '&') { + continue; + } + if c.is_alphabetic() { + if bold || r.scr != MScr::Roman { + let m = math_alnum(c, bold, italic, r.scr); + let plain = if m == c && !italic { " mathvariant=\"normal\"" } else { "" }; + o.push_str(&format!("{}", esc(&m.to_string()))); + } else if italic { + o.push_str(&format!("{}", esc(&c.to_string()))); + } else { + o.push_str(&format!("{}", esc(&c.to_string()))); + } + } else if math_class(c) == MClass::Ord && !c.is_ascii_punctuation() && c != '\u{2061}' { + // ∞, ∂, ∅, ℏ…: identifiers, not operators. + o.push_str(&format!("{}", esc(&c.to_string()))); + } else { + mo(c, &color, o); + } + } +} + +/// A function name (`sin`, `lim`): one upright identifier when it's plain text. +fn func_name(name: &[MNode], o: &mut String, depth: usize) { + match name { + [MNode::Run(r)] if !r.nor && r.text.chars().all(char::is_alphabetic) && !r.text.is_empty() => { + o.push_str(&format!("{}", esc(&r.text))); + } + _ => group(name, o, depth), + } +} + +fn fraction(kind: FracKind, num: &[MNode], den: &[MNode], o: &mut String, depth: usize) { + match kind { + FracKind::Bar | FracKind::NoBar => { + o.push_str(if kind == FracKind::NoBar { "" } else { "" }); + group(num, o, depth); + group(den, o, depth); + o.push_str(""); + } + FracKind::Skewed | FracKind::Linear => { + o.push_str(""); + group(num, o, depth); + mo(if kind == FracKind::Skewed { '⁄' } else { '/' }, "", o); + group(den, o, depth); + o.push_str(""); + } + } +} + +fn script(kind: ScriptKind, base: &[MNode], sub: &[MNode], sup: &[MNode], o: &mut String, depth: usize) { + match kind { + ScriptKind::Sup => { + o.push_str(""); + group(base, o, depth); + group(sup, o, depth); + o.push_str(""); + } + ScriptKind::Sub => { + o.push_str(""); + group(base, o, depth); + group(sub, o, depth); + o.push_str(""); + } + ScriptKind::SubSup => { + o.push_str(""); + group(base, o, depth); + group(sub, o, depth); + group(sup, o, depth); + o.push_str(""); + } + ScriptKind::Pre => { + o.push_str(""); + group(base, o, depth); + o.push_str(""); + if sub.is_empty() { + o.push_str(""); + } else { + group(sub, o, depth); + } + if sup.is_empty() { + o.push_str(""); + } else { + group(sup, o, depth); + } + o.push_str(""); + } + } +} + +fn write_nary(n: &MNode, o: &mut String, depth: usize) { + let MNode::Nary { chr, lim_loc, sub_hide, sup_hide, sub, sup, e, .. } = n else { return }; + let under_over = match lim_loc { + Some(l) => *l == LimLoc::UndOvr, + None => !is_integral(*chr), + }; + let has_sub = !*sub_hide && !sub.is_empty(); + let has_sup = !*sup_hide && !sup.is_empty(); + let tag = match (under_over, has_sub, has_sup) { + (_, false, false) => "", + (true, true, true) => "munderover", + (true, true, false) => "munder", + (true, false, true) => "mover", + (false, true, true) => "msubsup", + (false, true, false) => "msub", + (false, false, true) => "msup", + }; + o.push_str(""); + if !tag.is_empty() { + o.push_str(&format!("<{tag}>")); + } + mo(*chr, " largeop=\"true\" movablelimits=\"false\"", o); + if has_sub { + group(sub, o, depth); + } + if has_sup { + group(sup, o, depth); + } + if !tag.is_empty() { + o.push_str(&format!("")); + } + group(e, o, depth); + o.push_str(""); +} + +fn delimiters(n: &MNode, o: &mut String, depth: usize) { + let MNode::Delim { beg, end, sep, grow, elems, .. } = n else { return }; + let stretchy = if *grow { "" } else { " stretchy=\"false\"" }; + o.push_str(""); + if let Some(begin) = beg { + mo(*begin, &format!(" fence=\"true\" form=\"prefix\"{stretchy}"), o); + } + for (i, element) in elems.iter().enumerate() { + if i > 0 { + mo(sep.unwrap_or('|'), &format!(" separator=\"true\"{stretchy}"), o); + } + group(element, o, depth); + } + if let Some(close) = end { + mo(*close, &format!(" fence=\"true\" form=\"postfix\"{stretchy}"), o); + } + o.push_str(""); +} + +fn node(n: &MNode, o: &mut String, depth: usize, eq_arr: bool) { + match n { + MNode::Run(r) => run(r, o, eq_arr), + MNode::Frac { kind, num, den } => fraction(*kind, num, den, o, depth), + MNode::Script { kind, base, sub, sup } => script(*kind, base, sub, sup, o, depth), + MNode::Rad { deg, deg_hide, e } => { + if *deg_hide || deg.is_empty() { + o.push_str(""); + arg(e, o, depth, false); + o.push_str(""); + } else { + o.push_str(""); + group(e, o, depth); + group(deg, o, depth); + o.push_str(""); + } + } + MNode::Nary { .. } => write_nary(n, o, depth), + MNode::Delim { .. } => delimiters(n, o, depth), + MNode::Func { name, e } => { + o.push_str(""); + func_name(name, o, depth); + mo('\u{2061}', "", o); + group(e, o, depth); + o.push_str(""); + } + MNode::Lim { upper, e, lim } => { + let tag = if *upper { "mover" } else { "munder" }; + o.push_str(&format!("<{tag}>")); + func_name(e, o, depth); + group(lim, o, depth); + o.push_str(&format!("")); + } + MNode::Acc { chr, e } => { + o.push_str(""); + group(e, o, depth); + mo(spacing_accent(*chr), "", o); + o.push_str(""); + } + MNode::Bar { top, e } => { + if *top { + o.push_str(""); + group(e, o, depth); + mo('\u{203E}', "", o); + o.push_str(""); + } else { + o.push_str(""); + group(e, o, depth); + mo('_', "", o); + o.push_str(""); + } + } + MNode::BorderBox { hide, strike, e } => { + let mut notation: Vec<&str> = Vec::new(); + for (h, name) in hide.iter().zip(["top", "bottom", "left", "right"]) { + if !h { + notation.push(name); + } + } + if notation.len() == 4 { + notation = vec!["box"]; + } + for (s, name) in strike.iter().zip(["horizontalstrike", "verticalstrike", "updiagonalstrike", "downdiagonalstrike"]) { + if *s { + notation.push(name); + } + } + o.push_str(&format!("", notation.join(" "))); + arg(e, o, depth, false); + o.push_str(""); + } + MNode::Boxed { e } => group(e, o, depth), + MNode::GroupChr { chr, top, e } => { + let tag = if *top { "mover" } else { "munder" }; + o.push_str(&format!("<{tag}>")); + group(e, o, depth); + mo(*chr, " stretchy=\"true\"", o); + o.push_str(&format!("")); + } + MNode::EqArr { rows } => { + // `displaystyle` marks an equation array; a bare one-column table reads as a matrix. + o.push_str(""); + for r in rows { + o.push_str(""); + arg(r, o, depth, true); + o.push_str(""); + } + o.push_str(""); + } + MNode::Matrix { rows, col_jc } => { + o.push_str(""); + for r in rows { + o.push_str(""); + for (k, cell) in r.iter().enumerate() { + match col_jc.get(k) { + Some(ColJc::Left) => o.push_str(""), + Some(ColJc::Right) => o.push_str(""), + _ => o.push_str(""), + } + arg(cell, o, depth, false); + o.push_str(""); + } + o.push_str(""); + } + o.push_str(""); + } + MNode::Phant { show, zero_wid, zero_asc, zero_desc, e } => { + let mut pad = String::new(); + for (z, a) in [(zero_wid, "width"), (zero_asc, "height"), (zero_desc, "depth")] { + if *z { + pad.push_str(&format!(" {a}=\"0\"")); + } + } + if !pad.is_empty() { + o.push_str(&format!("")); + } + o.push_str(if *show { "" } else { "" }); + arg(e, o, depth, false); + o.push_str(if *show { "" } else { "" }); + if !pad.is_empty() { + o.push_str(""); + } + } + } +} + +/// Combining accents (how equations keep them) and the spacing characters MathML puts over the +/// base, both ways. +const ACCENTS: &[(char, char)] = &[ + ('\u{0302}', '^'), + ('\u{0303}', '~'), + ('\u{0304}', '¯'), + ('\u{0305}', '\u{203E}'), + ('\u{0306}', '˘'), + ('\u{0307}', '˙'), + ('\u{0308}', '¨'), + ('\u{030C}', 'ˇ'), + ('\u{0301}', '´'), + ('\u{0300}', '`'), + ('\u{030A}', '˚'), + ('\u{20D7}', '→'), + ('\u{20D6}', '←'), + ('\u{20E1}', '↔'), + ('\u{20D1}', '⇀'), + ('\u{20D0}', '↼'), +]; + +fn spacing_accent(c: char) -> char { + ACCENTS.iter().find(|(comb, _)| *comb == c).map(|(_, s)| *s).unwrap_or(c) +} + +fn combining_accent(c: char) -> Option { + let c = match c { + 'ˆ' => '^', + '˜' => '~', + '‾' => '\u{203E}', + '\u{20D7}' | '\u{0302}' | '\u{0303}' | '\u{0307}' | '\u{0308}' => return Some(c), + c => c, + }; + ACCENTS.iter().find(|(_, s)| *s == c).map(|(comb, _)| *comb) +} + +// --------------------------------------------------------------------------------------------- +// Reader + +/// Most elements read from one `` element. +pub const MAX_NODES: usize = 20_000; + +/// A parsed MathML element (namespace prefixes dropped, names lowercase). +#[derive(Clone, Debug, Default, PartialEq)] +pub struct El { + pub name: String, + pub attrs: Vec<(String, String)>, + pub children: Vec, +} + +#[derive(Clone, Debug, PartialEq)] +pub enum Item { + El(El), + Text(String), +} + +impl El { + fn attr(&self, name: &str) -> Option<&str> { + self.attrs.iter().find(|(k, _)| k == name).map(|(_, v)| v.as_str()) + } + fn els(&self) -> impl Iterator { + self.children.iter().filter_map(|c| match c { + Item::El(e) => Some(e), + Item::Text(_) => None, + }) + } + /// The text inside, all descendants (depth-limited). + pub fn text(&self) -> String { + let mut s = String::new(); + text_into(self, &mut s, 0); + s + } +} + +fn text_into(e: &El, s: &mut String, depth: usize) { + if depth > MAX_DEPTH { + return; + } + for c in &e.children { + match c { + Item::Text(t) => s.push_str(t), + Item::El(c) => text_into(c, s, depth + 1), + } + } +} + +/// The first `` element of XML text (the root or a descendant, any prefix), as an [`El`]: +/// for MathML read from an XML file or a clipboard format. At most [`MAX_NODES`] elements are +/// kept; `None` when there is no `math` element or the text is not XML. +pub fn parse(xml: &str) -> Option { + let limits = craft_xml::Limits { max_nodes: MAX_NODES.saturating_mul(4), max_depth: MAX_DEPTH.saturating_mul(2), ..craft_xml::Limits::DEFAULT }; + let (root, _) = craft_xml::Options { ns_decls: false, ..craft_xml::Options::default() }.with_limits(limits).parse_streaming_partial( + xml.as_bytes(), + &[], + |_| Ok::<(), craft_xml::Error>(()), + ); + let root = root?; + let math = if local(&root.name).eq_ignore_ascii_case("math") { &root } else { root.find(craft_xml::Local("math"))? }; + let mut budget = MAX_NODES; + Some(from_xml(math, 0, &mut budget)) +} + +fn from_xml(e: &craft_xml::El, depth: usize, budget: &mut usize) -> El { + let mut out = El { name: e.name.to_ascii_lowercase(), attrs: e.attrs.clone(), children: Vec::new() }; + if depth > MAX_DEPTH { + return out; + } + for n in &e.children { + match n { + craft_xml::Node::El(c) if *budget > 0 => { + *budget -= 1; + out.children.push(Item::El(from_xml(c, depth + 1, budget))); + } + craft_xml::Node::Text(t) => out.children.push(Item::Text(t.clone())), + _ => {} + } + } + out +} + +/// The element name without a namespace prefix (`m:math`, `mml:mfrac`). +pub fn local(name: &str) -> &str { + name.rsplit(':').next().unwrap_or(name) +} + +/// The linear format of a `` element, and whether it's a display equation. `None` when it +/// holds nothing. +pub fn read(math: &El) -> Option<(String, bool)> { + let display = + math.attr("display").is_some_and(|d| d.eq_ignore_ascii_case("block")) || math.attr("mode").is_some_and(|d| d.eq_ignore_ascii_case("display")); + let linear = linear_of(math); + let linear: String = linear.chars().filter(|c| !c.is_control()).collect(); + let linear = linear.trim().to_string(); + (!linear.is_empty()).then_some((linear, display)) +} + +fn linear_of(math: &El) -> String { + // Our own copy carries the linear format exactly. + if let Some(sem) = math.els().find(|e| local(&e.name) == "semantics") { + let ann = |enc: &dyn Fn(&str) -> bool| { + sem.els() + .filter(|e| local(&e.name) == "annotation") + .find(|e| e.attr("encoding").is_some_and(|v| enc(&v.to_ascii_lowercase()))) + .map(El::text) + .filter(|t| !t.trim().is_empty()) + }; + if let Some(t) = ann(&|v| v == UNICODEMATH) { + return t; + } + let tree = to_tree(math); + if !tree.is_empty() { + return to_linear(&tree); + } + if let Some(t) = ann(&|v| v.contains("tex")) { + return to_linear(&crate::math_latex::parse_latex(&t)); + } + return String::new(); + } + to_linear(&to_tree(math)) +} + +/// A MathML element's children as an equation tree. +pub fn to_tree(math: &El) -> Arg { + let mut budget = MAX_NODES; + crate::math::merge_runs(children(math, 0, &mut budget)) +} + +fn children(e: &El, depth: usize, budget: &mut usize) -> Arg { + let els: Vec<&El> = e.els().collect(); + seq(&els, depth, budget) +} + +/// A sequence of elements; an n-ary operator without an operand takes the next element. +fn seq(els: &[&El], depth: usize, budget: &mut usize) -> Arg { + let mut out: Arg = Vec::new(); + let mut i = 0; + while let Some(el) = els.get(i) { + i += 1; + // A function name (`sin`) applies to the next element even without U+2061, + // so it doesn't merge with it into `sinx`. Before an operator (`(`, U+2061) the runs + // merge and the linear format finds the function itself. + if local(&el.name) == "mi" + && let Some(next) = els.get(i).filter(|n| local(&n.name) != "mo") + { + let t = el.text(); + let t = t.trim(); + if FUNCTION_NAMES.contains(&t) && *budget > 0 { + *budget -= 1; + i += 1; + out.push(MNode::Func { name: vec![MNode::Run(MRun::plain(t))], e: elem(next, depth + 1, budget) }); + continue; + } + } + let mut a = elem(el, depth, budget); + if let [MNode::Nary { e, .. }] = a.as_mut_slice() + && e.is_empty() + && let Some(next) = els.get(i) + { + i += 1; + *e = elem(next, depth, budget); + } + out.extend(a); + } + out +} + +/// The `k`th child element as an argument. +fn nth(e: &El, k: usize, depth: usize, budget: &mut usize) -> Arg { + e.els().nth(k).map(|c| elem(c, depth, budget)).unwrap_or_default() +} + +/// A lone operator character (`∑`). +fn lone_char(a: &[MNode]) -> Option { + match a { + [MNode::Run(r)] => { + let mut cs = r.text.trim().chars(); + let c = cs.next()?; + cs.next().is_none().then_some(c) + } + _ => None, + } +} + +/// A plain word (`lim`, `max`). +fn word(a: &[MNode]) -> bool { + matches!(a, [MNode::Run(r)] if r.text.chars().count() > 1 && r.text.chars().all(char::is_alphabetic)) +} + +fn elem(e: &El, depth: usize, budget: &mut usize) -> Arg { + if depth > MAX_DEPTH || *budget == 0 { + return Vec::new(); + } + *budget -= 1; + let d = depth + 1; + match local(&e.name) { + "mi" | "mn" | "mo" | "ms" => { + let t = e.text(); + let t = t.trim(); + if t.is_empty() { + return Vec::new(); + } + let mut r = MRun::new(t); + if local(&e.name) == "mi" && e.attr("mathvariant") == Some("normal") && t.chars().count() == 1 { + r.sty = Some(MSty::Plain); + } + vec![MNode::Run(r)] + } + "mtext" => { + let t = e.text(); + if t.trim().is_empty() { + return Vec::new(); + } + vec![MNode::Run(MRun { text: t, nor: true, ..Default::default() })] + } + "mfrac" => { + let thin = e.attr("linethickness").is_some_and(|t| { + let s = t.trim(); + s.eq_ignore_ascii_case("none") || s.trim_end_matches(|c: char| c.is_alphabetic() || c == '%').trim() == "0" + }); + let kind = if e.attr("bevelled").is_some_and(|b| b.eq_ignore_ascii_case("true")) { + FracKind::Skewed + } else if thin { + FracKind::NoBar + } else { + FracKind::Bar + }; + vec![MNode::Frac { kind, num: nth(e, 0, d, budget), den: nth(e, 1, d, budget) }] + } + "msqrt" => vec![MNode::Rad { deg: Vec::new(), deg_hide: true, e: children(e, d, budget) }], + "mroot" => vec![MNode::Rad { deg: nth(e, 1, d, budget), deg_hide: false, e: nth(e, 0, d, budget) }], + "msup" | "msub" | "msubsup" => { + let name = local(&e.name); + let base = nth(e, 0, d, budget); + let (sub, sup) = match name { + "msup" => (Vec::new(), nth(e, 1, d, budget)), + "msub" => (nth(e, 1, d, budget), Vec::new()), + _ => (nth(e, 1, d, budget), nth(e, 2, d, budget)), + }; + if let Some(c) = lone_char(&base).filter(|c| is_nary_char(*c)) { + return vec![nary(c, LimLoc::SubSup, sub, sup)]; + } + let kind = match name { + "msup" => ScriptKind::Sup, + "msub" => ScriptKind::Sub, + _ => ScriptKind::SubSup, + }; + vec![MNode::Script { kind, base, sub, sup }] + } + "munder" | "mover" | "munderover" => { + let name = local(&e.name); + let base = nth(e, 0, d, budget); + let (under, over) = match name { + "munder" => (nth(e, 1, d, budget), Vec::new()), + "mover" => (Vec::new(), nth(e, 1, d, budget)), + _ => (nth(e, 1, d, budget), nth(e, 2, d, budget)), + }; + if let Some(c) = lone_char(&base).filter(|c| is_nary_char(*c)) { + return vec![nary(c, LimLoc::UndOvr, under, over)]; + } + if name == "munderover" { + let inner = MNode::Lim { upper: false, e: base, lim: under }; + return vec![MNode::Lim { upper: true, e: vec![inner], lim: over }]; + } + let upper = name == "mover"; + let mark = if upper { lone_char(&over) } else { lone_char(&under) }; + match mark { + Some('\u{203E}' | '¯' | '‾') if upper => vec![MNode::Bar { top: true, e: base }], + Some('_' | '\u{203E}' | '¯') if !upper => vec![MNode::Bar { top: false, e: base }], + Some(c @ ('⏞' | '⏟' | '⏜' | '⏝' | '⎴' | '⎵' | '←' | '→' | '↔' | '⇐' | '⇒' | '⇔')) if !word(&base) => { + vec![MNode::GroupChr { chr: c, top: upper, e: base }] + } + Some(c) if upper && combining_accent(c).is_some() => vec![MNode::Acc { chr: combining_accent(c).unwrap_or(c), e: base }], + _ => vec![MNode::Lim { upper, e: base, lim: if upper { over } else { under } }], + } + } + "mmultiscripts" => { + let els: Vec<&El> = e.els().collect(); + let base = els.first().map(|b| elem(b, d, budget)).unwrap_or_default(); + let pre_at = els.iter().position(|c| local(&c.name) == "mprescripts"); + let script = + |k: usize, budget: &mut usize| els.get(k).filter(|c| local(&c.name) != "none").map(|c| elem(c, d, budget)).unwrap_or_default(); + match pre_at { + Some(p) => { + let sub = script(p + 1, budget); + let sup = script(p + 2, budget); + let pre_node = MNode::Script { kind: ScriptKind::Pre, base, sub, sup }; + if p > 1 { + let post_sub = script(1, budget); + let post_sup = script(2, budget); + let kind = match (post_sub.is_empty(), post_sup.is_empty()) { + (true, true) => return vec![pre_node], + (false, true) => ScriptKind::Sub, + (true, false) => ScriptKind::Sup, + (false, false) => ScriptKind::SubSup, + }; + vec![MNode::Script { kind, base: vec![pre_node], sub: post_sub, sup: post_sup }] + } else { + vec![pre_node] + } + } + None => { + let sub = script(1, budget); + let sup = script(2, budget); + let kind = match (sub.is_empty(), sup.is_empty()) { + (true, true) => return base, + (false, true) => ScriptKind::Sub, + (true, false) => ScriptKind::Sup, + (false, false) => ScriptKind::SubSup, + }; + vec![MNode::Script { kind, base, sub, sup }] + } + } + } + "mfenced" => { + let first = |a: &str, dflt: char| e.attr(a).map(|v| v.trim().chars().next()).unwrap_or(Some(dflt)); + let beg = first("open", '('); + let end = first("close", ')'); + let sep = first("separators", ','); + let elems: Vec = e.els().map(|c| elem(c, d, budget)).collect(); + vec![MNode::Delim { beg, end, sep, grow: true, shp_match: false, elems }] + } + "mtable" => { + let mtr_list: Vec<&El> = e.els().filter(|r| matches!(local(&r.name), "mtr" | "mlabeledtr")).take(256).collect(); + let rows: Vec> = + mtr_list.iter().map(|r| r.els().filter(|c| local(&c.name) == "mtd").take(256).map(|c| children(c, d, budget)).collect()).collect(); + if rows.is_empty() { + return Vec::new(); + } + // One column is an equation array only when marked as one (`displaystyle`, alignment + // marks, labelled rows, as TeX's align and our own writer give); else a column vector. + let marked = + e.attr("displaystyle").is_some_and(|v| v.trim() == "true") || e.els().any(|r| local(&r.name) == "mlabeledtr") || has_align_mark(e, 0); + if marked && rows.iter().all(|r| r.len() <= 1) { + return vec![MNode::EqArr { rows: rows.into_iter().map(|mut r| r.pop().unwrap_or_default()).collect() }]; + } + let mut col_jc: Vec = e + .attr("columnalign") + .map(|ca| { + ca.split_whitespace() + .map(|a| match a { + "left" => ColJc::Left, + "right" => ColJc::Right, + _ => ColJc::Center, + }) + .collect() + }) + .unwrap_or_default(); + if col_jc.is_empty() + && let Some(first_row) = mtr_list.first() + { + let cell_aligns: Vec = first_row + .els() + .filter(|c| local(&c.name) == "mtd") + .map(|c| match c.attr("columnalign") { + Some("left") => ColJc::Left, + Some("right") => ColJc::Right, + _ => ColJc::Center, + }) + .collect(); + if cell_aligns.iter().any(|a| *a != ColJc::Center) { + col_jc = cell_aligns; + } + } + vec![MNode::Matrix { rows, col_jc }] + } + "mpadded" => { + let zero_wid = e.attr("width").is_some_and(|w| w.trim() == "0"); + let zero_asc = e.attr("height").is_some_and(|h| h.trim() == "0"); + let zero_desc = e.attr("depth").is_some_and(|d| d.trim() == "0"); + let ch = children(e, d, budget); + if zero_wid || zero_asc || zero_desc { + if let [MNode::Phant { show, e, .. }] = ch.as_slice() { + vec![MNode::Phant { show: *show, zero_wid, zero_asc, zero_desc, e: e.clone() }] + } else { + vec![MNode::Phant { show: true, zero_wid, zero_asc, zero_desc, e: ch }] + } + } else { + ch + } + } + "mphantom" => vec![MNode::Phant { show: false, zero_wid: false, zero_asc: false, zero_desc: false, e: children(e, d, budget) }], + "menclose" => { + let n = e.attr("notation").unwrap_or("longdiv"); + let has = |k: &str| n.split_whitespace().any(|w| w.eq_ignore_ascii_case(k)); + if has("radical") { + return vec![MNode::Rad { deg: Vec::new(), deg_hide: true, e: children(e, d, budget) }]; + } + // An actuarial symbol is the top and right edges. + let actuarial = has("actuarial"); + let is_box = has("box") || has("roundedbox") || has("circle"); + let (top, right) = (has("top") || actuarial, has("right") || actuarial); + let has_border = is_box || top || has("bottom") || has("left") || right; + let strike = + [has("horizontalstrike"), has("verticalstrike"), has("updiagonalstrike") || has("cross"), has("downdiagonalstrike") || has("cross")]; + if has_border || strike.iter().any(|&s| s) { + let hide = if is_box { + [false; 4] + } else if has_border { + [!top, !has("bottom"), !has("left"), !right] + } else { + [true; 4] + }; + return vec![MNode::BorderBox { hide, strike, e: children(e, d, budget) }]; + } + children(e, d, budget) + } + // The first child of `semantics` is the presentation; annotations aren't content. + "semantics" => e.els().next().map(|c| elem(c, d, budget)).unwrap_or_default(), + "annotation" | "annotation-xml" | "mspace" | "none" | "mprescripts" | "maligngroup" | "malignmark" => Vec::new(), + _ => children(e, d, budget), + } +} + +/// Whether `e` holds a `maligngroup` or `malignmark` near the top (in a cell or a row inside it). +fn has_align_mark(e: &El, depth: usize) -> bool { + depth <= 4 && e.els().any(|c| matches!(local(&c.name), "maligngroup" | "malignmark") || has_align_mark(c, depth + 1)) +} + +fn nary(chr: char, lim_loc: LimLoc, sub: Arg, sup: Arg) -> MNode { + let lim_loc = Some(lim_loc).filter(|l| *l != if is_integral(chr) { LimLoc::SubSup } else { LimLoc::UndOvr }); + MNode::Nary { chr, lim_loc, grow: false, sub_hide: sub.is_empty(), sup_hide: sup.is_empty(), sub, sup, e: Vec::new() } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::math::parse_linear; + + fn ml(linear: &str) -> String { + to_mathml(&parse_linear(linear), false, "") + } + + #[test] + fn runs_split_into_identifiers_numbers_and_operators() { + let m = ml("y=2x"); + assert!(m.starts_with(""), "{m}"); + assert!(m.contains("y=2x"), "{m}"); + assert!(m.contains("y=2x"), "{m}"); + assert!(to_mathml(&parse_linear("x"), true, "").contains("display=\"block\"")); + } + + #[test] + fn structures_become_their_elements() { + for (linear, want) in [ + ("a/b", "ab"), + ("x^2", "x2"), + ("x_s", "xs"), + ("x_i^2", ""), + ("√x", "x"), + ("√(3&x)", "x3"), + ("∑_(i=1)^n▒i", "∑"), + ("∫_0^1▒x", "∫"), + ("(a+b)", "("), + ("sin⁡x", "sin\u{2061}"), + ("■(a&b@c&d)", "ab"), + ] { + let m = ml(linear); + assert!(m.contains(want), "{linear}: {m}"); + } + let acc = to_mathml(&[MNode::Acc { chr: '\u{0302}', e: parse_linear("a") }], false, ""); + assert!(acc.contains("a^"), "{acc}"); + let bar = to_mathml(&[MNode::Bar { top: true, e: parse_linear("a") }], false, ""); + assert!(bar.contains("\u{203E}"), "{bar}"); + let lim = to_mathml(&[MNode::Lim { upper: false, e: parse_linear("lim"), lim: parse_linear("n→∞") }], false, ""); + assert!(lim.contains("limn→∞"), "{lim}"); + let bb = to_mathml(&[MNode::BorderBox { hide: [false; 4], strike: [false; 4], e: parse_linear("a") }], false, ""); + assert!(bb.contains(""), "{bb}"); + let gc = to_mathml(&[MNode::GroupChr { chr: '⏟', top: false, e: parse_linear("a") }], false, ""); + assert!(gc.contains("a⏟"), "{gc}"); + let pre = to_mathml(&[MNode::Script { kind: ScriptKind::Pre, base: parse_linear("C"), sub: parse_linear("n"), sup: vec![] }], false, ""); + assert!(pre.contains("") && pre.contains(""), "{pre}"); + let eq = to_mathml(&[MNode::EqArr { rows: vec![parse_linear("x&=1"), parse_linear("y&=2")] }], false, ""); + assert!(eq.contains("x=1") && !eq.contains("&"), "{eq}"); + let ph = to_mathml(&[MNode::Phant { show: false, zero_wid: true, zero_asc: false, zero_desc: false, e: parse_linear("a") }], false, ""); + assert!(ph.contains(""), "{ph}"); + let styled = to_mathml( + &[ + MNode::Run(MRun { text: "R".into(), scr: MScr::DoubleStruck, ..Default::default() }), + MNode::Run(MRun::plain("d")), + MNode::Run(MRun { text: "speed".into(), nor: true, ..Default::default() }), + ], + false, + "", + ); + assert!( + styled.contains("ℝ") && styled.contains("d") && styled.contains("speed"), + "{styled}" + ); + // Text is escaped. + assert!(ml("a<")); + } + + fn pasted(xml: &str) -> Vec<(String, bool)> { + parse(xml).and_then(|m| read(&m)).into_iter().collect() + } + + #[test] + fn written_mathml_reads_back_exactly() { + for (linear, display) in [("y=2x_s", false), ("x=(-b±√(b^2-4ac))/2a", true), ("∑_(k=1)^n▒k", false), ("■(a&b@c&d)", false)] { + let xml = linear_to_mathml(linear, display); + assert!(xml.starts_with("Before {xml} after

")), vec![(linear.to_string(), display)], "{xml}"); + } + } + + #[test] + fn foreign_mathml_is_read_from_its_elements() { + let cases = [ + ("y=2xs", "y=2x_s"), + ("ab+1", "a/(b+1)"), + ("x", "√x"), + ("∑k=1nk", "∑_(k=1)^n▒k"), + ("ex", "e^x"), + // A TeX annotation is used when the presentation is empty. + ("\\frac{1}{2}", "1/2"), + ]; + for (html, want) in cases { + let got = pasted(html); + assert_eq!(got.first().map(|g| g.0.as_str()), Some(want), "{html}"); + } + assert!(pasted("x").first().is_some_and(|g| g.1)); + // An unclosed element ends with the input. + assert!(!pasted("

x").is_empty()); + // Hostile nesting is bounded. + let deep = format!("{}x{}", "".repeat(5000), "".repeat(5000)); + assert!(pasted(&deep).len() <= 1); + } + + #[test] + fn math_over_the_node_cap_keeps_the_first_elements() { + let xml = format!("{}z", "y".repeat(MAX_NODES * 2)); + let el = parse(&xml).unwrap(); + assert_eq!(el.children.len(), MAX_NODES); + assert!(read(&el).is_some_and(|(l, _)| !l.contains('z'))); + // Not XML, or no math element: nothing. + assert!(parse("").is_none() && parse("

no math

").is_none() && parse("\u{0}<<").is_none()); + } + + #[test] + fn function_names_apply_without_the_invisible_operator() { + let cases = [ + ("sinx", "sin\u{2061}x"), + ("logab", "log\u{2061}ab"), + ("cos\u{2061}x", "cos\u{2061}x"), + ("abx", "abx"), + ]; + for (html, want) in cases { + assert_eq!(pasted(html).first().map(|g| g.0.as_str()), Some(want), "{html}"); + } + let tree = to_tree(&El { + name: "math".into(), + attrs: vec![], + children: vec![ + Item::El(El { name: "mi".into(), attrs: vec![], children: vec![Item::Text("sin".into())] }), + Item::El(El { name: "mi".into(), attrs: vec![], children: vec![Item::Text("x".into())] }), + ], + }); + assert!(matches!(tree.as_slice(), [MNode::Func { .. }]), "{tree:?}"); + } + + #[test] + fn one_column_tables_are_column_vectors_unless_marked() { + let tree = |html: &str| { + let linear = pasted(html).first().map(|g| g.0.clone()).unwrap_or_default(); + crate::math::parse_linear(&linear) + }; + let vector = tree("ab"); + assert!(matches!(vector.as_slice(), [MNode::Matrix { rows, .. }] if rows.len() == 2), "{vector:?}"); + for marked in [ + "ab", + "a=1b", + ] { + let t = tree(marked); + assert!(matches!(t.as_slice(), [MNode::EqArr { rows }] if rows.len() == 2), "{marked}: {t:?}"); + } + // Our own equation arrays read back as equation arrays from their elements alone. + let ml = to_mathml(&[MNode::EqArr { rows: vec![parse_linear("x=1"), parse_linear("y=2")] }], false, ""); + let ml = ml.replace("application/x-unicodemath", "x-ignored"); + let t = tree(&ml); + assert!(matches!(t.as_slice(), [MNode::EqArr { .. }]), "{ml}: {t:?}"); + } + + #[test] + fn mmultiscripts_and_borderbox_round_trip() { + let html = "X12"; + let p = pasted(html); + assert!(!p.is_empty(), "should parse mmultiscripts with pre and post scripts"); + + let html_box = "x"; + let p_box = pasted(html_box); + assert!(!p_box.is_empty(), "should parse menclose"); + + let html_tbl = "ab"; + let p_tbl = pasted(html_tbl); + assert!(!p_tbl.is_empty(), "should parse mtable with columnalign"); + + let html_pad = "z"; + let p_pad = pasted(html_pad); + assert!(!p_pad.is_empty(), "should parse mpadded phantom"); + } + + #[test] + fn deep_nesting_is_bounded() { + let mut n = parse_linear("x"); + for _ in 0..500 { + n = vec![MNode::Frac { kind: FracKind::Bar, num: n, den: parse_linear("y") }]; + } + let m = to_mathml(&n, false, "z"); + assert!(m.ends_with("
")); + } + + #[test] + fn test_mfrac_linethickness_none_and_menclose_notations() { + let el_frac = El { + name: "mfrac".into(), + attrs: vec![("linethickness".into(), "none".into())], + children: vec![ + Item::El(El { name: "mi".into(), attrs: vec![], children: vec![Item::Text("n".into())] }), + Item::El(El { name: "mi".into(), attrs: vec![], children: vec![Item::Text("k".into())] }), + ], + }; + let mut budget = MAX_NODES; + let tree_frac = elem(&el_frac, 0, &mut budget); + assert!(matches!(tree_frac.as_slice(), [MNode::Frac { kind: FracKind::NoBar, .. }]), "{tree_frac:?}"); + + let el_strike = El { + name: "menclose".into(), + attrs: vec![("notation".into(), "horizontalstrike".into())], + children: vec![Item::El(El { name: "mi".into(), attrs: vec![], children: vec![Item::Text("x".into())] })], + }; + let mut budget = MAX_NODES; + let tree_strike = elem(&el_strike, 0, &mut budget); + assert!(matches!(tree_strike.as_slice(), [MNode::BorderBox { strike: [true, false, false, false], .. }]), "{tree_strike:?}"); + + let el_cross = El { + name: "menclose".into(), + attrs: vec![("notation".into(), "cross".into())], + children: vec![Item::El(El { name: "mi".into(), attrs: vec![], children: vec![Item::Text("x".into())] })], + }; + let mut budget = MAX_NODES; + let tree_cross = elem(&el_cross, 0, &mut budget); + assert!(matches!(tree_cross.as_slice(), [MNode::BorderBox { strike: [false, false, true, true], .. }]), "{tree_cross:?}"); + + let el_rad = El { + name: "menclose".into(), + attrs: vec![("notation".into(), "radical".into())], + children: vec![Item::El(El { name: "mi".into(), attrs: vec![], children: vec![Item::Text("x".into())] })], + }; + let mut budget = MAX_NODES; + let tree_rad = elem(&el_rad, 0, &mut budget); + assert!(matches!(tree_rad.as_slice(), [MNode::Rad { deg_hide: true, .. }]), "{tree_rad:?}"); + } +} diff --git a/crates/math/src/omml.rs b/crates/math/src/omml.rs new file mode 100644 index 000000000..99024ec8b --- /dev/null +++ b/crates/math/src/omml.rs @@ -0,0 +1,232 @@ +//! Office Math Markup (OMML, ECMA-376 Part 1 §22.1) read into and written from the equation tree +//! ([`crate::math`]). +//! +//! The reader takes an `m:oMath` element of a [`craft_xml`] tree read with the canonical +//! prefixes of [`NAMESPACES`] (`m:` for math, `w:` for WordprocessingML, `mc:` for markup +//! compatibility), whatever prefixes the file used; [`parse`] does that for a string. It keeps +//! the source XML in [`Math::omml`], and the writer writes that back unchanged while the +//! equation's colour is the same, so a saved file carries the equation exactly as Word wrote it. +//! The writer otherwise writes the tree: `m:oMath`, inside `m:oMathPara` for a display equation. + +use craft_xml::{Canonical, El, Options}; + +use crate::math::{Math, MathJc}; +use crate::rgb::Rgb; + +mod read; +mod write; + +pub use read::{lift_color, para_jc, read_math_pr, read_omath}; +pub use write::{math_pr, resolve_numbers, write_equation}; + +/// The OMML namespace (transitional), and the strict one. +pub const MATH_NS: &str = "http://schemas.openxmlformats.org/officeDocument/2006/math"; +pub const MATH_NS_STRICT: &str = "http://purl.oclc.org/ooxml/officeDocument/math"; +/// The WordprocessingML namespace OMML runs borrow (`w:rPr`, `w:t`, `w:sym`), transitional and +/// strict. +pub const W_NS: &str = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"; +pub const W_NS_STRICT: &str = "http://purl.oclc.org/ooxml/wordprocessingml/main"; +/// Markup compatibility (`mc:AlternateContent`). +pub const MC_NS: &str = "http://schemas.openxmlformats.org/markup-compatibility/2006"; + +/// The canonical prefixes the reader expects, for [`craft_xml::Canonical`]. +pub const NAMESPACES: &[(&str, &str)] = &[("m", MATH_NS), ("m", MATH_NS_STRICT), ("w", W_NS), ("w", W_NS_STRICT), ("mc", MC_NS)]; + +/// Most elements [`parse`] reads from one string. +pub const MAX_ELEMENTS: usize = 250_000; + +/// OMML text read into a tree with the canonical prefixes of [`NAMESPACES`]: the first +/// `m:oMathPara` or `m:oMath` element in it (the root or any descendant). `None` when there is +/// none, or the text is not XML. Text kept by the reader ([`Math::omml`]) declares no +/// namespaces; its prefixes are already the canonical ones and are read as written. +pub fn parse(xml: &str) -> Option { + let canonical = Canonical::new(NAMESPACES); + let limits = craft_xml::Limits { max_nodes: MAX_ELEMENTS.saturating_mul(2), ..craft_xml::Limits::DEFAULT }; + let first = |root: El| -> Option { + if matches!(root.name.as_str(), "m:oMath" | "m:oMathPara") { + return Some(root); + } + root.find("m:oMathPara").or_else(|| root.find("m:oMath")).cloned() + }; + let read = Options::canonical(&canonical).with_limits(limits).parse(xml.as_bytes()).ok().and_then(first); + read.or_else(|| parse_kept(xml).and_then(first)) +} + +/// Kept OMML (canonical prefixes, no declarations) read as written. +fn parse_kept(xml: &str) -> Option { + let limits = craft_xml::Limits { max_nodes: MAX_ELEMENTS.saturating_mul(2), ..craft_xml::Limits::DEFAULT }; + Options { ns_decls: false, ..Options::default() }.with_limits(limits).parse(xml.as_bytes()).ok() +} + +/// Is `xml` (kept OMML) well-formed enough to write back as it is? +fn is_well_formed(xml: &str) -> bool { + xml.starts_with(" Option { + let e = parse(xml)?; + if e.name == "m:oMathPara" { + let jc = para_jc(&e); + return e.find("m:oMath").map(|m| read_omath(m, jc)); + } + Some(read_omath(&e, MathJc::default())) +} + +/// An equation as OMML text ([`write_equation`] into a string, no XML declaration). +pub fn write_str(linear: &str, display: bool, math: &Math, color: Option) -> String { + let mut w = W::default(); + write_equation(&mut w, linear, display, math, color); + w.s +} + +/// OMML on/off property of WordprocessingML (`w:b`, `w:i`): absent `w:val` = on. +fn on_off(e: &El) -> bool { + match e.attr_or_plain("w:val") { + None => true, + Some(v) => !matches!(v.trim(), "0" | "false" | "off" | "False" | "FALSE"), + } +} + +/// Largest absolute length accepted, points (200 inches). +const MAX_LEN_PT: f32 = 14_400.0; + +/// A twips value (`m:wrapIndent`), with or without an ISO 29500 universal measure (`1in`, +/// `2.5cm`, `12pt`), in points. +fn measure_twips(s: Option<&str>) -> Option { + let t = s?.trim(); + if t.is_empty() || t.len() > 40 { + return None; + } + let bytes = t.as_bytes(); + let mut split = t.len(); + let mut in_exp = false; + for (i, &b) in bytes.iter().enumerate() { + if b.is_ascii_digit() || b == b'.' { + in_exp = false; + continue; + } + if (b == b'-' || b == b'+') && (i == 0 || in_exp) { + in_exp = false; + continue; + } + if b == b'e' || b == b'E' { + let rest = bytes.get(i + 1..).unwrap_or_default(); + let after_sign = match rest.first() { + Some(&s) if s == b'+' || s == b'-' => rest.get(1..).unwrap_or_default(), + _ => rest, + }; + if after_sign.first().is_some_and(u8::is_ascii_digit) { + in_exp = true; + continue; + } + } + split = i; + break; + } + let (num, unit) = t.split_at(split); + let v: f64 = num.parse().ok()?; + if !v.is_finite() { + return None; + } + let pt = match unit.trim().to_ascii_lowercase().as_str() { + "" => v / 20.0, + "pt" => v, + "in" => v * 72.0, + "cm" => v * 72.0 / 2.54, + "mm" => v * 72.0 / 25.4, + "pc" | "pi" => v * 12.0, + "px" => v * 0.75, + "emu" => v / 12_700.0, + _ => return None, + }; + let pt = pt as f32; + pt.is_finite().then_some(pt.clamp(-MAX_LEN_PT, MAX_LEN_PT)) +} + +/// Points as a twips attribute value. +fn twips(pt: f32) -> String { + let pt = pt.clamp(-MAX_LEN_PT, MAX_LEN_PT); + let pt = if pt.is_finite() { pt } else { 0.0 }; + ((pt * 20.0).round() as i64).to_string() +} + +fn xml_char_ok(c: char) -> bool { + matches!(c, '\t' | '\n' | '\r' | '\u{20}'..='\u{D7FF}' | '\u{E000}'..='\u{FFFD}' | '\u{10000}'..='\u{10FFFF}') +} + +/// Escape text for element content or attribute values (drops characters XML can't carry). +fn esc(s: &str) -> String { + let mut o = String::with_capacity(s.len()); + for c in s.chars() { + match c { + '&' => o.push_str("&"), + '<' => o.push_str("<"), + '>' => o.push_str(">"), + '"' => o.push_str("""), + '\'' => o.push_str("'"), + '\t' => o.push_str(" "), + '\n' => o.push_str(" "), + '\r' => o.push_str(" "), + c if xml_char_ok(c) => o.push(c), + _ => {} + } + } + o +} + +/// A string-building XML writer, as WordprocessingML writers write: names as given, values +/// escaped. +#[derive(Default)] +pub struct W { + pub s: String, +} + +impl W { + fn attrs(&mut self, attrs: &[(&str, &str)]) { + for (k, v) in attrs { + self.s.push(' '); + self.s.push_str(k); + self.s.push_str("=\""); + self.s.push_str(&esc(v)); + self.s.push('"'); + } + } + pub fn open(&mut self, name: &str, attrs: &[(&str, &str)]) { + self.s.push('<'); + self.s.push_str(name); + self.attrs(attrs); + self.s.push('>'); + } + pub fn empty(&mut self, name: &str, attrs: &[(&str, &str)]) { + self.s.push('<'); + self.s.push_str(name); + self.attrs(attrs); + self.s.push_str("/>"); + } + pub fn close(&mut self, name: &str) { + self.s.push_str("'); + } + pub fn text(&mut self, t: &str) { + self.s.push_str(&esc(t)); + } + /// `text`. + pub fn leaf(&mut self, name: &str, attrs: &[(&str, &str)], t: &str) { + self.open(name, attrs); + self.text(t); + self.close(name); + } + /// ``. + pub fn val(&mut self, name: &str, v: &str) { + self.empty(name, &[("w:val", v)]); + } + pub fn raw(&mut self, s: &str) { + self.s.push_str(s); + } +} + +#[cfg(test)] +mod tests; diff --git a/crates/math/src/omml/read.rs b/crates/math/src/omml/read.rs new file mode 100644 index 000000000..2f01f6fb4 --- /dev/null +++ b/crates/math/src/omml/read.rs @@ -0,0 +1,359 @@ +//! OMML into the tree. + +use craft_xml::El; + +use super::{measure_twips, on_off}; +use crate::math::{ + Arg, BrkBin, BrkBinSub, ColJc, FracKind, LimLoc, MAX_DEPTH, MNode, MRun, MScr, MSty, Math, MathJc, MathProps, ScriptKind, merge_runs, +}; +use crate::rgb::Rgb; +use crate::symbol_fonts; + +/// An `m:oMath` element as an equation (structure plus its source XML). +pub fn read_omath(e: &El, jc: MathJc) -> Math { + Math { nodes: merge_runs(arg(e, 0)), omml: e.to_xml(), jc, linear: false } +} + +/// A colour every math run shares, taken off the runs: it is the equation's own colour, as +/// [`write_equation`] spreads it (#1467). The source OMML +/// is kept: the writer replaces it only when the colour changes. +pub fn lift_color(math: &mut Math) -> Option { + let (mut shared, mut uniform) = (None, true); + crate::math_tree::each_run_mut(&mut math.nodes, &mut |r| match shared { + None => shared = Some(r.color), + Some(c) => uniform &= c == r.color, + }); + let c = shared.flatten().filter(|_| uniform)?; + crate::math_tree::each_run_mut(&mut math.nodes, &mut |r| r.color = None); + Some(c) +} + +/// `m:oMathParaPr/m:jc`. +pub fn para_jc(para: &El) -> MathJc { + match para.child("m:oMathParaPr").and_then(|p| p.child("m:jc")).and_then(|j| j.attr_or_plain("m:val")) { + Some("left") => MathJc::Left, + Some("right") => MathJc::Right, + Some("center") => MathJc::Center, + _ => MathJc::CenterGroup, + } +} + +/// The settings part's `m:mathPr`: how display equations wrap. +pub fn read_math_pr(e: &El) -> MathProps { + let mut m = MathProps::default(); + let pr = Some(e); + m.brk_bin = match val(pr, "m:brkBin") { + Some("after") => BrkBin::After, + Some("repeat") => BrkBin::Repeat, + _ => BrkBin::Before, + }; + m.brk_bin_sub = match val(pr, "m:brkBinSub") { + Some("-+") => BrkBinSub::MinusPlus, + Some("+-") => BrkBinSub::PlusMinus, + _ => BrkBinSub::MinusMinus, + }; + if let Some(v) = e.child("m:wrapIndent").and_then(|c| measure_twips(c.attr_or_plain("m:val"))).filter(|v| v.is_finite() && *v >= 0.0) { + m.wrap_indent = v.min(1584.0); + } + m.wrap_right = prop(pr, "m:wrapRight", false); + m +} + +/// OMML on/off property: absent `m:val` = on. +fn on(e: &El) -> bool { + match e.attr_or_plain("m:val") { + None => true, + Some(v) => !matches!(v.trim(), "0" | "false" | "off" | "False" | "FALSE"), + } +} + +/// An on/off property `name` in the properties element `pr` (absent = `default`). +fn prop(pr: Option<&El>, name: &str, default: bool) -> bool { + pr.and_then(|p| p.child(name)).map(on).unwrap_or(default) +} + +/// A character property (`m:chr`, `m:begChr`…): `None` when absent, `Some(None)` when empty. +fn chr(pr: Option<&El>, name: &str) -> Option> { + let c = pr?.child(name)?; + match c.attr_or_plain("m:val") { + Some(v) => Some(v.chars().next()), + None => Some(None), + } +} + +fn val<'a>(pr: Option<&'a El>, name: &str) -> Option<&'a str> { + pr.and_then(|p| p.child(name)).and_then(|c| c.attr_or_plain("m:val")) +} + +/// The argument held by child `name` of `e`. +fn sub_arg(e: &El, name: &str, depth: usize) -> Arg { + e.child(name).map(|c| arg(c, depth + 1)).unwrap_or_default() +} + +/// Read the math content of an element (`m:oMath`, `m:e`, `m:num`…). +fn arg(e: &El, depth: usize) -> Arg { + let mut out = Vec::new(); + if depth > MAX_DEPTH { + return out; + } + for k in e.elements() { + node(k, depth, &mut out); + } + out +} + +fn node(k: &El, depth: usize, out: &mut Arg) { + let d = depth + 1; + match k.name.as_str() { + "m:r" => { + if let Some(r) = run(k) { + out.push(MNode::Run(r)); + } + } + // Word puts ordinary runs in math zones for normal text in some files. + "w:r" => { + let text = run_text(k); + if !text.is_empty() { + let mut r = MRun { text, nor: true, sty: Some(MSty::Plain), ..Default::default() }; + wrpr(k.child("w:rPr"), &mut r); + out.push(MNode::Run(r)); + } + } + "m:f" => { + let pr = k.child("m:fPr"); + let kind = match val(pr, "m:type") { + Some("skw") => FracKind::Skewed, + Some("lin") => FracKind::Linear, + Some("noBar") => FracKind::NoBar, + _ => FracKind::Bar, + }; + out.push(MNode::Frac { kind, num: sub_arg(k, "m:num", d), den: sub_arg(k, "m:den", d) }); + } + "m:sSup" => out.push(MNode::Script { kind: ScriptKind::Sup, base: sub_arg(k, "m:e", d), sub: Vec::new(), sup: sub_arg(k, "m:sup", d) }), + "m:sSub" => out.push(MNode::Script { kind: ScriptKind::Sub, base: sub_arg(k, "m:e", d), sub: sub_arg(k, "m:sub", d), sup: Vec::new() }), + "m:sSubSup" => { + out.push(MNode::Script { kind: ScriptKind::SubSup, base: sub_arg(k, "m:e", d), sub: sub_arg(k, "m:sub", d), sup: sub_arg(k, "m:sup", d) }) + } + "m:sPre" => { + out.push(MNode::Script { kind: ScriptKind::Pre, base: sub_arg(k, "m:e", d), sub: sub_arg(k, "m:sub", d), sup: sub_arg(k, "m:sup", d) }) + } + "m:rad" => { + let pr = k.child("m:radPr"); + out.push(MNode::Rad { deg: sub_arg(k, "m:deg", d), deg_hide: prop(pr, "m:degHide", false), e: sub_arg(k, "m:e", d) }); + } + "m:nary" => { + let pr = k.child("m:naryPr"); + let chr = chr(pr, "m:chr").map(|c| c.unwrap_or('∫')).unwrap_or('∫'); + let lim_loc = match val(pr, "m:limLoc") { + Some("undOvr") => Some(LimLoc::UndOvr), + Some("subSup") => Some(LimLoc::SubSup), + _ => None, + }; + out.push(MNode::Nary { + chr, + lim_loc, + grow: prop(pr, "m:grow", false), + sub_hide: prop(pr, "m:subHide", false), + sup_hide: prop(pr, "m:supHide", false), + sub: sub_arg(k, "m:sub", d), + sup: sub_arg(k, "m:sup", d), + e: sub_arg(k, "m:e", d), + }); + } + "m:d" => { + let pr = k.child("m:dPr"); + let beg = chr(pr, "m:begChr").unwrap_or(Some('(')); + let end = chr(pr, "m:endChr").unwrap_or(Some(')')); + let sep = chr(pr, "m:sepChr").unwrap_or(Some('|')); + let elems: Vec = k.children("m:e").map(|e| arg(e, d)).collect(); + out.push(MNode::Delim { + beg, + end, + sep, + grow: prop(pr, "m:grow", true), + shp_match: val(pr, "m:shp") == Some("match"), + elems: if elems.is_empty() { vec![Vec::new()] } else { elems }, + }); + } + "m:func" => out.push(MNode::Func { name: sub_arg(k, "m:fName", d), e: sub_arg(k, "m:e", d) }), + "m:limLow" => out.push(MNode::Lim { upper: false, e: sub_arg(k, "m:e", d), lim: sub_arg(k, "m:lim", d) }), + "m:limUpp" => out.push(MNode::Lim { upper: true, e: sub_arg(k, "m:e", d), lim: sub_arg(k, "m:lim", d) }), + "m:acc" => { + let c = chr(k.child("m:accPr"), "m:chr").map(|c| c.unwrap_or('\u{302}')).unwrap_or('\u{302}'); + out.push(MNode::Acc { chr: c, e: sub_arg(k, "m:e", d) }); + } + "m:bar" => out.push(MNode::Bar { top: val(k.child("m:barPr"), "m:pos") == Some("top"), e: sub_arg(k, "m:e", d) }), + "m:borderBox" => { + let pr = k.child("m:borderBoxPr"); + out.push(MNode::BorderBox { + hide: [prop(pr, "m:hideTop", false), prop(pr, "m:hideBot", false), prop(pr, "m:hideLeft", false), prop(pr, "m:hideRight", false)], + strike: [ + prop(pr, "m:strikeH", false), + prop(pr, "m:strikeV", false), + prop(pr, "m:strikeBLTR", false), + prop(pr, "m:strikeTLBR", false), + ], + e: sub_arg(k, "m:e", d), + }); + } + "m:box" => out.push(MNode::Boxed { e: sub_arg(k, "m:e", d) }), + "m:groupChr" => { + let pr = k.child("m:groupChrPr"); + let c = chr(pr, "m:chr").map(|c| c.unwrap_or('\u{23DF}')).unwrap_or('\u{23DF}'); + out.push(MNode::GroupChr { chr: c, top: val(pr, "m:pos") == Some("top"), e: sub_arg(k, "m:e", d) }); + } + "m:eqArr" => out.push(MNode::EqArr { rows: k.children("m:e").map(|e| arg(e, d)).collect() }), + "m:m" => { + let mut col_jc = Vec::new(); + if let Some(mcs) = k.child("m:mPr").and_then(|p| p.child("m:mcs")) { + for mc in mcs.children("m:mc") { + let pr = mc.child("m:mcPr"); + let jc = match val(pr, "m:mcJc") { + Some("left") => ColJc::Left, + Some("right") => ColJc::Right, + _ => ColJc::Center, + }; + let count = val(pr, "m:count").and_then(|c| c.trim().parse::().ok()).unwrap_or(1).clamp(1, 64); + for _ in 0..count { + if col_jc.len() < 64 { + col_jc.push(jc); + } + } + } + } + let rows = k.children("m:mr").take(1000).map(|r| r.children("m:e").take(64).map(|e| arg(e, d)).collect()).collect(); + out.push(MNode::Matrix { rows, col_jc }); + } + "m:phant" => { + let pr = k.child("m:phantPr"); + out.push(MNode::Phant { + show: prop(pr, "m:show", true), + zero_wid: prop(pr, "m:zeroWid", false), + zero_asc: prop(pr, "m:zeroAsc", false), + zero_desc: prop(pr, "m:zeroDesc", false), + e: sub_arg(k, "m:e", d), + }); + } + // Tracked insertions show; deletions don't. Hyperlinks, simple fields and direction + // wrappers (EG_PContentMath, §22.1.2.77) keep their runs (#1273). + "w:ins" | "w:moveTo" | "w:smartTag" | "w:customXml" | "w:hyperlink" | "w:fldSimple" | "w:dir" | "w:bdo" | "m:oMath" if depth <= MAX_DEPTH => { + for c in k.elements() { + node(c, d, out); + } + } + // Markup compatibility: the math choice (we read math), else the fallback. + "mc:AlternateContent" if depth <= MAX_DEPTH => { + if let Some(c) = k.child("mc:Choice").or_else(|| k.child("mc:Fallback")) { + for c in c.elements() { + node(c, d, out); + } + } + } + "w:sdt" => { + if let Some(c) = k.child("w:sdtContent") { + for c in c.elements() { + node(c, d, out); + } + } + } + _ => {} + } +} + +/// `m:t` (and `w:t`) text of a run, with symbol characters (`w:sym`) and special hyphens. +/// Text in a symbol font (Symbol, Wingdings…) becomes its Unicode equivalent: the math font has +/// no glyphs at those private-use codes (#1273). +fn run_text(r: &El) -> String { + let font = r + .child("w:rPr") + .and_then(|p| p.child("w:rFonts")) + .and_then(|f| f.attr_or_plain("w:ascii").or_else(|| f.attr_or_plain("w:hAnsi"))) + .unwrap_or(""); + let mut s = String::new(); + for c in r.elements() { + match c.name.as_str() { + "m:t" | "w:t" => s.push_str(&symbol_fonts::map_text(font, &c.text())), + "w:tab" => s.push('\t'), + "w:noBreakHyphen" => s.push('\u{2011}'), + "w:sym" => { + let ch = c + .attr_or_plain("w:char") + .and_then(|h| u32::from_str_radix(h.trim(), 16).ok()) + .and_then(char::from_u32) + .filter(|c| *c as u32 >= 0x20); + if let Some(ch) = ch { + let f = c.attr_or_plain("w:font").unwrap_or(font); + s.push(symbol_fonts::symbol_char(f, ch).unwrap_or(ch)); + } + } + _ => {} + } + } + s +} + +fn run(r: &El) -> Option { + let text = run_text(r); + if text.is_empty() { + return None; + } + let mut out = MRun { text, ..Default::default() }; + if let Some(pr) = r.child("m:rPr") { + out.sty = match pr.child("m:sty").and_then(|s| s.attr_or_plain("m:val")) { + Some("p") => Some(MSty::Plain), + Some("b") => Some(MSty::Bold), + Some("i") => Some(MSty::Italic), + Some("bi") => Some(MSty::BoldItalic), + _ => None, + }; + out.scr = match pr.child("m:scr").and_then(|s| s.attr_or_plain("m:val")) { + Some("script") => MScr::Script, + Some("fraktur") => MScr::Fraktur, + Some("double-struck") => MScr::DoubleStruck, + Some("sans-serif") => MScr::SansSerif, + Some("monospace") => MScr::Monospace, + _ => MScr::Roman, + }; + out.nor = pr.child("m:nor").is_some_and(on); + out.lit = pr.child("m:lit").is_some_and(on); + if let Some(b) = pr.child("m:brk") { + let aln = b.attr_or_plain("m:alnAt").and_then(|v| v.trim().parse::().ok()).unwrap_or(0); + out.brk = Some(aln.min(255) as u8); + } + } + wrpr(r.child("w:rPr"), &mut out); + Some(out) +} + +/// The run formatting a math run takes from `w:rPr`: size, colour, normal-text font and weight. +fn wrpr(pr: Option<&El>, out: &mut MRun) { + let Some(pr) = pr else { return }; + if let Some(sz) = pr.child("w:sz").and_then(|s| s.attr_or_plain("w:val")).and_then(|v| v.trim().parse::().ok()) { + let pt = sz / 2.0; + if pt.is_finite() && (1.0..=1638.0).contains(&pt) { + out.size = Some(pt); + } + } + if let Some(c) = pr.child("w:color").and_then(|c| c.attr_or_plain("w:val")).and_then(Rgb::parse) { + out.color = Some(c); + } + if out.nor { + // Symbol-font text was mapped to Unicode: it takes the text font. + if let Some(f) = pr + .child("w:rFonts") + .and_then(|f| f.attr_or_plain("w:ascii").or_else(|| f.attr_or_plain("w:hAnsi"))) + .filter(|f| !symbol_fonts::is_symbol_font(f)) + { + out.font = Some(f.to_string()); + } + let bold = pr.child("w:b").is_some_and(on_off); + let italic = pr.child("w:i").is_some_and(on_off); + if bold || italic { + out.sty = Some(match (bold, italic) { + (true, true) => MSty::BoldItalic, + (true, false) => MSty::Bold, + _ => MSty::Italic, + }); + } + } +} diff --git a/crates/math/src/omml/tests.rs b/crates/math/src/omml/tests.rs new file mode 100644 index 000000000..863bacf4f --- /dev/null +++ b/crates/math/src/omml/tests.rs @@ -0,0 +1,191 @@ +use super::*; +use crate::math::*; + +fn omath(inner: &str) -> El { + let x = format!( + r#"{inner}"# + ); + parse(&x).unwrap() +} + +#[test] +fn reads_fraction_radical_and_scripts() { + let e = omath( + r#"x=-b±b2-4ac2a"#, + ); + let m = read_omath(&e, MathJc::CenterGroup); + assert_eq!(m.nodes.len(), 2); + let MNode::Frac { num, den, kind } = &m.nodes[1] else { panic!("{:#?}", m.nodes) }; + assert_eq!(*kind, FracKind::Bar); + assert_eq!(den, &vec![MNode::Run(MRun::new("2a"))]); + let MNode::Rad { deg_hide, e, .. } = &num[1] else { panic!() }; + assert!(*deg_hide); + assert!(matches!(e[0], MNode::Script { kind: ScriptKind::Sup, .. })); + assert_eq!(crate::math::to_linear(&m.nodes), "x=(-b±√(b^2-4ac))/2a"); + assert!(m.omml.starts_with("")); +} + +#[test] +fn reads_nary_delims_matrix_and_defaults() { + let e = omath( + r#"iiab"#, + ); + let m = read_omath(&e, MathJc::CenterGroup); + let MNode::Nary { chr, lim_loc, .. } = &m.nodes[0] else { panic!() }; + assert_eq!((*chr, *lim_loc), ('∑', Some(LimLoc::UndOvr))); + let MNode::Delim { beg, end, sep, elems, .. } = &m.nodes[1] else { panic!() }; + assert_eq!((*beg, *end, *sep, elems.len()), (Some('['), None, Some('|'), 2)); + assert!(matches!(m.nodes[2], MNode::Nary { chr: '∫', .. })); + assert!(matches!(&m.nodes[3], MNode::Matrix { rows, .. } if rows.len() == 1 && rows[0].len() == 2)); +} + +/// Every run's text in the tree, in reading order. +fn texts(m: &mut Math) -> Vec { + let mut out = Vec::new(); + crate::math_tree::each_run_mut(&mut m.nodes, &mut |r| out.push(r.text.clone())); + out +} + +fn t(s: &str) -> String { + format!("{s}") +} + +/// #1273: one equation using every Office Math element of ECMA-376 §22.1 (each argument +/// holding a distinct marker) keeps every argument's text: nothing is silently dropped. +#[test] +fn every_omml_element_keeps_its_content() { + let parts = [ + format!("{}", t("A1")), + format!("{}", t("B1")), + format!("{}", t("C1")), + format!("{}", t("D1")), + format!("{}{}", t("E1"), t("E2")), + format!("{}{}", t("F1"), t("F2")), + format!("{}{}", t("G1"), t("G2")), + format!("{}{}", t("H1"), t("H2")), + format!("{}", t("I1")), + format!("{}{}", t("J1"), t("J2")), + format!("{}{}", t("K1"), t("K2")), + format!("{}{}{}", t("L1"), t("L2"), t("L3")), + format!( + "{}{}{}", + t("M1"), + t("M2"), + t("M3") + ), + format!("{}", t("N1")), + format!("{}{}", t("O1"), t("O2")), + format!("{}{}{}", t("P1"), t("P2"), t("P3")), + format!("{}{}", t("Q1"), t("Q2")), + format!("{}{}{}", t("R1"), t("R2"), t("R3")), + format!("{}{}", t("S1"), t("S2")), + // Run-level wrappers allowed in math (EG_PContentMath): hyperlinks, simple fields, + // tracked insertions, content controls, markup compatibility. + format!("{}", t("T1")), + format!("{}", t("T2")), + format!("{}", t("T3")), + format!("{}", t("T4")), + format!( + "{}picture", + t("T5") + ), + "T6".to_string(), + ]; + let x = format!( + r#"{}"#, + parts.concat() + ); + let e = parse(&x).unwrap(); + let mut m = read_omath(&e, MathJc::CenterGroup); + let got = texts(&mut m).concat(); + let markers = [ + "A1", "B1", "C1", "D1", "E1", "E2", "F1", "F2", "G1", "G2", "H1", "H2", "I1", "J1", "J2", "K1", "K2", "L1", "L2", "L3", "M1", "M2", "M3", + "N1", "O1", "O2", "P1", "P2", "P3", "Q1", "Q2", "R1", "R2", "R3", "S1", "S2", "T1", "T2", "T3", "T4", "T5", "T6", + ]; + for k in markers { + assert!(got.contains(k), "{k} dropped from {got}"); + } + assert!(!got.contains("picture"), "the math choice wins over the fallback: {got}"); +} + +/// #1273: deleted text stays out; symbol characters and symbol-font text become Unicode. +#[test] +fn symbols_and_deletions_in_math() { + let e = omath( + r#"xgone"#, + ); + let mut m = read_omath(&e, MathJc::CenterGroup); + let got = texts(&mut m).concat(); + assert_eq!(got, "xαβ\u{2011}γ"); + let mut font = None; + crate::math_tree::each_run_mut(&mut m.nodes, &mut |r| { + if r.nor { + font = Some(r.font.clone()); + } + }); + assert_eq!(font, Some(None), "mapped symbol text takes the text font"); +} + +/// Hostile nesting through the wrappers is bounded (no stack overflow, no panic). +#[test] +fn deeply_nested_wrappers_are_bounded() { + // Deeper than the math limit, within the XML parser's own depth limit. + let n = 120; + let inner = format!("{}{}{}", "".repeat(n), t("deep"), "".repeat(n)); + let e = omath(&inner); + let _ = read_omath(&e, MathJc::CenterGroup); + let inner = format!( + "{}{}{}", + "".repeat(n), + t("deep"), + "".repeat(n) + ); + let e = omath(&inner); + let _ = read_omath(&e, MathJc::CenterGroup); +} + +#[test] +fn text_entry_points_find_the_equation_and_refuse_junk() { + let ns = r#"xmlns:m="http://schemas.openxmlformats.org/officeDocument/2006/math""#; + // Any prefix, inside other markup, as a display paragraph with its justification. + let x = r#"

x

"#; + let m = read_str(x).unwrap(); + assert_eq!((crate::math::to_linear(&m.nodes).as_str(), m.jc), ("x", MathJc::Left)); + // The strict OOXML namespace. + let strict = r#"y"#; + assert_eq!(read_str(strict).map(|m| crate::math::to_linear(&m.nodes)).as_deref(), Some("y")); + // Kept OMML, prefixes without declarations. + assert_eq!(read_str("z").map(|m| crate::math::to_linear(&m.nodes)).as_deref(), Some("z")); + for junk in ["", "

", "not xml", "").is_none() && read_str("").is_none()); + // More elements than the reader keeps: refused, not read in part. + let wide = format!("{}", "".repeat(MAX_ELEMENTS * 2 + 1)); + assert!(parse(&wide).is_none()); + let fits = format!("{}", "a".repeat(1000)); + assert!(parse(&fits).is_some()); + // Deep nesting is bounded. + let deep = format!("{}x{}", "".repeat(5000), "".repeat(5000)); + let _ = read_str(&deep); +} + +#[test] +fn kept_omml_is_written_back_only_when_well_formed() { + let m = read_str(r#"x"#).unwrap(); + assert_eq!(write_str("", false, &m, None), m.omml); + let broken = Math { omml: "".into(), ..m.clone() }; + let out = write_str("", false, &broken, None); + assert!(out.starts_with("") && out.ends_with("") && out.contains(">x"), "{out}"); + // A colour that differs from the kept one rewrites the equation from the tree, with the colour. + let red = write_str("", false, &m, Some(Rgb(255, 0, 0))); + assert!(red.contains(r#""#), "{red}"); +} + +proptest::proptest! { + #[test] + fn any_text_reads_without_panicking(s in "[<>/=\"a-z:m ]{0,120}") { + let _ = read_str(&s); + let _ = crate::mathml::parse(&s).map(|e| crate::mathml::to_tree(&e)); + } +} diff --git a/crates/math/src/omml/write.rs b/crates/math/src/omml/write.rs new file mode 100644 index 000000000..9f09aab67 --- /dev/null +++ b/crates/math/src/omml/write.rs @@ -0,0 +1,480 @@ +//! The tree as OMML. + +use super::read::{lift_color, read_omath}; +use super::{W, is_well_formed, parse_kept, twips}; +use crate::math::{ + Arg, BrkBin, BrkBinSub, ColJc, FracKind, LimLoc, MAX_DEPTH, MAX_MATRIX_COLS, MAX_MATRIX_ROWS, MNode, MRun, MScr, MSty, Math, MathJc, MathProps, + ScriptKind, parse_linear, +}; +use crate::rgb::Rgb; + +/// Write an equation: `m:oMath`, inside `m:oMathPara` for a display equation. The source OMML +/// is written back unchanged when the equation came from a file. `color` (the equation's run +/// colour) goes on every math run without its own: OMML has no equation-level colour (#1467). +pub fn write_equation(w: &mut W, linear: &str, display: bool, math: &Math, color: Option) { + let tinted; + let math = if color == omml_color(&math.omml) { + math + } else { + // The kept source XML has the old colour baked in: write from the nodes instead. + let mut m = math.clone(); + if m.nodes.is_empty() { + m.nodes = parse_linear(linear); + } + if let Some(c) = color { + crate::math_tree::each_run_mut(&mut m.nodes, &mut |r| { + r.color.get_or_insert(c); + }); + } + m.omml.clear(); + tinted = m; + &tinted + }; + if display { + w.open("m:oMathPara", &[]); + let jc = match math.jc { + MathJc::CenterGroup => None, + MathJc::Center => Some("center"), + MathJc::Left => Some("left"), + MathJc::Right => Some("right"), + }; + if let Some(jc) = jc { + w.open("m:oMathParaPr", &[]); + w.empty("m:jc", &[("m:val", jc)]); + w.close("m:oMathParaPr"); + } + } + if !math.omml.is_empty() && math.omml.starts_with(" Option { + if !display { + return None; + } + let [MNode::EqArr { rows }] = math.nodes.as_slice() else { return None }; + let mut out = rows.clone(); + let mut changed = false; + for row in out.iter_mut() { + if !crate::math::has_number_mark(row) { + continue; + } + *counter = counter.saturating_add(1); + // Nothing after the `#`: an automatic number. + let mut after = false; + let mut empty = true; + for n in row.iter() { + match n { + MNode::Run(r) if !after => { + if let Some(k) = r.text.find('#') { + after = true; + if !r.text.get(k + 1..).unwrap_or("").is_empty() { + empty = false; + } + } + } + _ if after => empty = false, + _ => {} + } + } + if empty { + let n = vec![MNode::Run(MRun::new(counter.to_string()))]; + row.push(MNode::Delim { beg: Some('('), end: Some(')'), sep: None, grow: true, shp_match: false, elems: vec![n] }); + changed = true; + } + } + changed.then(|| Math { nodes: vec![MNode::EqArr { rows: out }], omml: String::new(), ..math.clone() }) +} + +/// The equation colour the kept source OMML carries, as the reader lifts it. +fn omml_color(omml: &str) -> Option { + if omml.is_empty() { + return None; + } + let root = parse_kept(omml)?; + let e = if root.name == "m:oMath" { &root } else { root.find("m:oMath")? }; + lift_color(&mut read_omath(e, MathJc::default())) +} + +/// The settings part's `m:mathPr` (CT_MathPr order; `m:wrapIndent` and `m:wrapRight` are a choice). +pub fn math_pr(w: &mut W, m: &MathProps) { + w.open("m:mathPr", &[]); + let bin = match m.brk_bin { + BrkBin::Before => "before", + BrkBin::After => "after", + BrkBin::Repeat => "repeat", + }; + val(w, "m:brkBin", bin); + let sub = match m.brk_bin_sub { + BrkBinSub::MinusMinus => "--", + BrkBinSub::MinusPlus => "-+", + BrkBinSub::PlusMinus => "+-", + }; + val(w, "m:brkBinSub", sub); + if m.wrap_right { + w.empty("m:wrapRight", &[]); + } else { + let indent = if m.wrap_indent.is_finite() { m.wrap_indent.clamp(0.0, 1584.0) } else { crate::math::DEFAULT_WRAP_INDENT }; + val(w, "m:wrapIndent", &twips(indent)); + } + w.close("m:mathPr"); +} + +fn val(w: &mut W, name: &str, v: &str) { + w.empty(name, &[("m:val", v)]); +} + +fn arg(w: &mut W, name: &str, a: &[MNode], depth: usize) { + if a.is_empty() { + w.empty(name, &[]); + return; + } + w.open(name, &[]); + arg_inner(w, a, depth + 1); + w.close(name); +} + +fn arg_inner(w: &mut W, a: &[MNode], depth: usize) { + if depth > MAX_DEPTH { + return; + } + for n in a { + node(w, n, depth); + } +} + +fn ctrl(w: &mut W) { + w.open("m:ctrlPr", &[]); + w.open("w:rPr", &[]); + w.empty("w:rFonts", &[("w:ascii", "Cambria Math"), ("w:hAnsi", "Cambria Math")]); + w.empty("w:i", &[]); + w.close("w:rPr"); + w.close("m:ctrlPr"); +} + +fn char_prop(w: &mut W, name: &str, c: Option) { + let s = c.map(|c| c.to_string()).unwrap_or_default(); + val(w, name, &s); +} + +fn write_matrix(w: &mut W, n: &MNode, depth: usize) { + let MNode::Matrix { rows, col_jc } = n else { return }; + // Every row is padded to the widest one, so a ragged matrix is clamped to the reader's + // caps rather than written as rows × widest cells (#3643). + let rows = rows.get(..rows.len().min(MAX_MATRIX_ROWS)).unwrap_or_default(); + let cols = rows.iter().map(|r| r.len()).max().unwrap_or(0).clamp(1, MAX_MATRIX_COLS); + w.open("m:m", &[]); + w.open("m:mPr", &[]); + w.open("m:mcs", &[]); + for c in 0..cols { + let jc = match col_jc.get(c).copied().unwrap_or_default() { + ColJc::Center => "center", + ColJc::Left => "left", + ColJc::Right => "right", + }; + w.open("m:mc", &[]); + w.open("m:mcPr", &[]); + val(w, "m:count", "1"); + val(w, "m:mcJc", jc); + w.close("m:mcPr"); + w.close("m:mc"); + } + w.close("m:mcs"); + ctrl(w); + w.close("m:mPr"); + for row in rows { + w.open("m:mr", &[]); + for c in 0..cols { + arg(w, "m:e", row.get(c).map(|v| v.as_slice()).unwrap_or(&[]), depth); + } + w.close("m:mr"); + } + w.close("m:m"); +} + +fn write_nary(w: &mut W, n: &MNode, depth: usize) { + let MNode::Nary { chr, lim_loc, grow, sub_hide, sup_hide, sub, sup, e } = n else { return }; + w.open("m:nary", &[]); + w.open("m:naryPr", &[]); + if *chr != '∫' { + char_prop(w, "m:chr", Some(*chr)); + } + match lim_loc { + Some(LimLoc::UndOvr) => val(w, "m:limLoc", "undOvr"), + Some(LimLoc::SubSup) => val(w, "m:limLoc", "subSup"), + None => {} + } + if *grow { + val(w, "m:grow", "1"); + } + if *sub_hide { + val(w, "m:subHide", "1"); + } + if *sup_hide { + val(w, "m:supHide", "1"); + } + ctrl(w); + w.close("m:naryPr"); + arg(w, "m:sub", sub, depth); + arg(w, "m:sup", sup, depth); + arg(w, "m:e", e, depth); + w.close("m:nary"); +} + +fn node(w: &mut W, n: &MNode, depth: usize) { + match n { + MNode::Run(r) => run(w, r), + MNode::Frac { kind, num, den } => { + w.open("m:f", &[]); + w.open("m:fPr", &[]); + match kind { + FracKind::Bar => {} + FracKind::Skewed => val(w, "m:type", "skw"), + FracKind::Linear => val(w, "m:type", "lin"), + FracKind::NoBar => val(w, "m:type", "noBar"), + } + ctrl(w); + w.close("m:fPr"); + arg(w, "m:num", num, depth); + arg(w, "m:den", den, depth); + w.close("m:f"); + } + MNode::Script { kind, base, sub, sup } => { + let (el, pr) = match kind { + ScriptKind::Sup => ("m:sSup", "m:sSupPr"), + ScriptKind::Sub => ("m:sSub", "m:sSubPr"), + ScriptKind::SubSup => ("m:sSubSup", "m:sSubSupPr"), + ScriptKind::Pre => ("m:sPre", "m:sPrePr"), + }; + w.open(el, &[]); + w.open(pr, &[]); + ctrl(w); + w.close(pr); + if *kind == ScriptKind::Pre { + arg(w, "m:sub", sub, depth); + arg(w, "m:sup", sup, depth); + arg(w, "m:e", base, depth); + } else { + arg(w, "m:e", base, depth); + if matches!(kind, ScriptKind::Sub | ScriptKind::SubSup) { + arg(w, "m:sub", sub, depth); + } + if matches!(kind, ScriptKind::Sup | ScriptKind::SubSup) { + arg(w, "m:sup", sup, depth); + } + } + w.close(el); + } + MNode::Rad { deg, deg_hide, e } => { + w.open("m:rad", &[]); + w.open("m:radPr", &[]); + if *deg_hide { + val(w, "m:degHide", "1"); + } + ctrl(w); + w.close("m:radPr"); + arg(w, "m:deg", deg, depth); + arg(w, "m:e", e, depth); + w.close("m:rad"); + } + MNode::Nary { .. } => write_nary(w, n, depth), + MNode::Delim { beg, end, sep, grow, shp_match, elems } => { + w.open("m:d", &[]); + w.open("m:dPr", &[]); + if *beg != Some('(') { + char_prop(w, "m:begChr", *beg); + } + if *sep != Some('|') { + char_prop(w, "m:sepChr", *sep); + } + if *end != Some(')') { + char_prop(w, "m:endChr", *end); + } + if !grow { + val(w, "m:grow", "0"); + } + if *shp_match { + val(w, "m:shp", "match"); + } + ctrl(w); + w.close("m:dPr"); + for e in elems { + arg(w, "m:e", e, depth); + } + w.close("m:d"); + } + MNode::Func { name, e } => { + w.open("m:func", &[]); + w.open("m:funcPr", &[]); + ctrl(w); + w.close("m:funcPr"); + arg(w, "m:fName", name, depth); + arg(w, "m:e", e, depth); + w.close("m:func"); + } + MNode::Lim { upper, e, lim } => { + let (el, pr) = if *upper { ("m:limUpp", "m:limUppPr") } else { ("m:limLow", "m:limLowPr") }; + w.open(el, &[]); + w.open(pr, &[]); + ctrl(w); + w.close(pr); + arg(w, "m:e", e, depth); + arg(w, "m:lim", lim, depth); + w.close(el); + } + MNode::Acc { chr, e } => { + w.open("m:acc", &[]); + w.open("m:accPr", &[]); + char_prop(w, "m:chr", Some(*chr)); + ctrl(w); + w.close("m:accPr"); + arg(w, "m:e", e, depth); + w.close("m:acc"); + } + MNode::Bar { top, e } => { + w.open("m:bar", &[]); + w.open("m:barPr", &[]); + val(w, "m:pos", if *top { "top" } else { "bot" }); + ctrl(w); + w.close("m:barPr"); + arg(w, "m:e", e, depth); + w.close("m:bar"); + } + MNode::BorderBox { hide, strike, e } => { + w.open("m:borderBox", &[]); + w.open("m:borderBoxPr", &[]); + for (on, name) in hide.iter().zip(["m:hideTop", "m:hideBot", "m:hideLeft", "m:hideRight"]) { + if *on { + val(w, name, "1"); + } + } + for (on, name) in strike.iter().zip(["m:strikeH", "m:strikeV", "m:strikeBLTR", "m:strikeTLBR"]) { + if *on { + val(w, name, "1"); + } + } + ctrl(w); + w.close("m:borderBoxPr"); + arg(w, "m:e", e, depth); + w.close("m:borderBox"); + } + MNode::Boxed { e } => { + w.open("m:box", &[]); + w.open("m:boxPr", &[]); + ctrl(w); + w.close("m:boxPr"); + arg(w, "m:e", e, depth); + w.close("m:box"); + } + MNode::GroupChr { chr, top, e } => { + w.open("m:groupChr", &[]); + w.open("m:groupChrPr", &[]); + char_prop(w, "m:chr", Some(*chr)); + val(w, "m:pos", if *top { "top" } else { "bot" }); + val(w, "m:vertJc", if *top { "bot" } else { "top" }); + ctrl(w); + w.close("m:groupChrPr"); + arg(w, "m:e", e, depth); + w.close("m:groupChr"); + } + MNode::EqArr { rows } => { + w.open("m:eqArr", &[]); + w.open("m:eqArrPr", &[]); + // Numbered rows (`#`) stretch across the line so the number reaches the margin. + if rows.iter().any(|r| crate::math::has_number_mark(r)) { + val(w, "m:maxDist", "1"); + } + ctrl(w); + w.close("m:eqArrPr"); + for r in rows { + arg(w, "m:e", r, depth); + } + w.close("m:eqArr"); + } + MNode::Matrix { .. } => write_matrix(w, n, depth), + MNode::Phant { show, zero_wid, zero_asc, zero_desc, e } => { + w.open("m:phant", &[]); + w.open("m:phantPr", &[]); + val(w, "m:show", if *show { "1" } else { "0" }); + for (on, name) in [(*zero_wid, "m:zeroWid"), (*zero_asc, "m:zeroAsc"), (*zero_desc, "m:zeroDesc")] { + if on { + val(w, name, "1"); + } + } + ctrl(w); + w.close("m:phantPr"); + arg(w, "m:e", e, depth); + w.close("m:phant"); + } + } +} + +fn run(w: &mut W, r: &MRun) { + w.open("m:r", &[]); + let sty = r.sty.map(|s| match s { + MSty::Plain => "p", + MSty::Bold => "b", + MSty::Italic => "i", + MSty::BoldItalic => "bi", + }); + let scr = match r.scr { + MScr::Roman => None, + MScr::Script => Some("script"), + MScr::Fraktur => Some("fraktur"), + MScr::DoubleStruck => Some("double-struck"), + MScr::SansSerif => Some("sans-serif"), + MScr::Monospace => Some("monospace"), + }; + if sty.is_some() || scr.is_some() || r.nor || r.lit || r.brk.is_some() { + w.open("m:rPr", &[]); + if r.lit { + w.empty("m:lit", &[]); + } + if r.nor { + w.empty("m:nor", &[]); + } + if let Some(s) = scr { + val(w, "m:scr", s); + } + if let Some(s) = sty { + val(w, "m:sty", s); + } + match r.brk { + Some(0) => w.empty("m:brk", &[]), + Some(n) => w.empty("m:brk", &[("m:alnAt", &n.to_string())]), + None => {} + } + w.close("m:rPr"); + } + w.open("w:rPr", &[]); + let font = r.font.as_deref().filter(|_| r.nor).unwrap_or("Cambria Math"); + w.empty("w:rFonts", &[("w:ascii", font), ("w:hAnsi", font)]); + if let Some(c) = r.color { + w.val("w:color", &c.hex()); + } + if let Some(sz) = r.size { + let hp = (sz * 2.0).round().clamp(2.0, 3276.0) as i64; + w.val("w:sz", &hp.to_string()); + w.val("w:szCs", &hp.to_string()); + } + w.close("w:rPr"); + w.leaf("m:t", &[("xml:space", "preserve")], &r.text); + w.close("m:r"); +} diff --git a/crates/math/src/rgb.rs b/crates/math/src/rgb.rs new file mode 100644 index 000000000..f624cda15 --- /dev/null +++ b/crates/math/src/rgb.rs @@ -0,0 +1,173 @@ +//! An sRGB colour, the one type of colour every Craft document model and this crate share. + +use serde::{Deserialize, Serialize}; + +/// An sRGB colour. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Default)] +pub struct Rgb(pub u8, pub u8, pub u8); + +impl<'de> Deserialize<'de> for Rgb { + /// Reads what it writes (`[r, g, b]`) and also a string [`Rgb::parse`] reads, so the colours in + /// `CharProps` / `ParaProps` take the `RRGGBB` that `para.borders` and `table.shading` take (#865). + fn deserialize>(d: D) -> Result { + use serde::de::{Error, SeqAccess, Unexpected, Visitor}; + struct V; + impl<'de> Visitor<'de> for V { + type Value = Rgb; + fn expecting(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result { + f.write_str("`[r, g, b]`, `RRGGBB` or `#RRGGBB`") + } + fn visit_str(self, s: &str) -> Result { + Rgb::parse(s).ok_or_else(|| E::invalid_value(Unexpected::Str(s), &self)) + } + fn visit_seq>(self, mut a: A) -> Result { + let mut c = [0u8; 3]; + for (i, x) in c.iter_mut().enumerate() { + *x = a.next_element()?.ok_or_else(|| A::Error::invalid_length(i, &self))?; + } + if a.next_element::()?.is_some() { + return Err(A::Error::invalid_length(4, &self)); + } + Ok(Rgb(c[0], c[1], c[2])) + } + } + d.deserialize_any(V) + } +} + +impl Rgb { + pub const BLACK: Rgb = Rgb(0, 0, 0); + pub const WHITE: Rgb = Rgb(255, 255, 255); + /// `RRGGBB` (no `#`). + pub fn hex(self) -> String { + format!("{:02X}{:02X}{:02X}", self.0, self.1, self.2) + } + /// Parse `RRGGBB` or `#RRGGBB`. + pub fn parse(s: &str) -> Option { + let s = s.trim(); + let s = s.strip_prefix('#').unwrap_or(s); + if s.len() != 6 || !s.bytes().all(|b| b.is_ascii_hexdigit()) { + return None; + } + let p = |i: usize| s.get(i..i + 2).and_then(|h| u8::from_str_radix(h, 16).ok()); + Some(Rgb(p(0)?, p(2)?, p(4)?)) + } + /// This colour with the DrawingML colour modifier `name` (`lumMod`, `lumOff`, `tint`, + /// `shade`, `satMod`, ECMA-376 §20.1.2.3) at `v` (1.0 = 100%); other names leave it + /// unchanged. + pub fn modified(self, name: &str, v: f64) -> Rgb { + match name { + "lumMod" => adjust_lum(self, |l| l * v), + "lumOff" => adjust_lum(self, |l| l + v), + "tint" => mix(self, 255.0, v), + "shade" => mix(self, 0.0, v), + "satMod" => { + let (h, sat, l) = to_hsl(self); + from_hsl(h, (sat * v).clamp(0.0, 1.0), l) + } + _ => self, + } + } + /// The colour with hue `h` (0..1 of a turn), saturation `s` and lightness `l` (0..1). + pub fn from_hsl(h: f64, s: f64, l: f64) -> Rgb { + from_hsl(h, s, l) + } + /// This colour with its HSL luminance changed by `f`. + pub fn with_lum(self, f: impl Fn(f64) -> f64) -> Rgb { + adjust_lum(self, f) + } + pub fn luma(self) -> f32 { + 0.299 * self.0 as f32 + 0.587 * self.1 as f32 + 0.114 * self.2 as f32 + } +} + +/// `tint` (towards `to` = 255) and `shade` (towards 0): `v` is the share of the original colour kept. +fn mix(c: Rgb, to: f64, v: f64) -> Rgb { + let f = |x: u8| (x as f64 * v + to * (1.0 - v)).round().clamp(0.0, 255.0) as u8; + Rgb(f(c.0), f(c.1), f(c.2)) +} + +/// `c` with its HSL luminance changed by `f`. +fn adjust_lum(c: Rgb, f: impl Fn(f64) -> f64) -> Rgb { + let (h, s, l) = to_hsl(c); + from_hsl(h, s, f(l).clamp(0.0, 1.0)) +} + +fn to_hsl(c: Rgb) -> (f64, f64, f64) { + let (r, g, b) = (c.0 as f64 / 255.0, c.1 as f64 / 255.0, c.2 as f64 / 255.0); + let (max, min) = (r.max(g).max(b), r.min(g).min(b)); + let l = (max + min) / 2.0; + if max == min { + return (0.0, 0.0, l); + } + let d = max - min; + let s = if l > 0.5 { d / (2.0 - max - min) } else { d / (max + min) }; + let h = if max == r { + (g - b) / d + if g < b { 6.0 } else { 0.0 } + } else if max == g { + (b - r) / d + 2.0 + } else { + (r - g) / d + 4.0 + }; + (h / 6.0, s, l) +} + +fn from_hsl(h: f64, s: f64, l: f64) -> Rgb { + let byte = |v: f64| (v * 255.0).round().clamp(0.0, 255.0) as u8; + if s == 0.0 { + return Rgb(byte(l), byte(l), byte(l)); + } + let q = if l < 0.5 { l * (1.0 + s) } else { l + s - l * s }; + let p = 2.0 * l - q; + let channel = |t: f64| { + let t = t.rem_euclid(1.0); + let v = if t < 1.0 / 6.0 { + p + (q - p) * 6.0 * t + } else if t < 0.5 { + q + } else if t < 2.0 / 3.0 { + p + (q - p) * (2.0 / 3.0 - t) * 6.0 + } else { + p + }; + byte(v) + }; + Rgb(channel(h + 1.0 / 3.0), channel(h), channel(h - 1.0 / 3.0)) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn rgb_hex() { + assert_eq!(Rgb(255, 0, 16).hex(), "FF0010"); + assert_eq!(Rgb::parse("#FF0010"), Some(Rgb(255, 0, 16))); + assert_eq!(Rgb::parse("zzzzzz"), None); + assert_eq!(Rgb::parse("é1234"), None); + } + + #[test] + fn rgb_parse_rejects_non_hex() { + assert_eq!(Rgb::parse("+1+2+3"), None); + assert_eq!(Rgb::parse("-1-2-3"), None); + assert_eq!(Rgb::parse("##ff0000"), None); + assert_eq!(Rgb::parse("ff00 0"), None); + assert_eq!(Rgb::parse("#ff0000"), Some(Rgb(255, 0, 0))); + assert_eq!(Rgb::parse("ff0000"), Some(Rgb(255, 0, 0))); + } + + /// #865: an [`Rgb`] reads `RRGGBB` / `#RRGGBB` as well as the `[r, g, b]` it still writes. + #[test] + fn rgb_reads_hex_and_keeps_its_serialized_form() { + let read = |j: &str| serde_json::from_str::(j); + let ink = Rgb(0x1B, 0x16, 0x11); + assert_eq!(serde_json::to_string(&ink).unwrap(), "[27,22,17]", "written as before"); + for j in ["[27,22,17]", r#""1B1611""#, r##""#1b1611""##] { + assert_eq!(read(j).unwrap(), ink, "{j}"); + } + for bad in ["[27,22]", "[27,22,17,0]", "[27,22,300]", "[-1,0,0]", r#""auto""#, r#""1B161""#, r#""""#, "7", "null", r#"{"r":1}"#] { + assert!(read(bad).is_err(), "{bad}"); + } + } +} diff --git a/crates/math/src/symbol_fonts.rs b/crates/math/src/symbol_fonts.rs new file mode 100644 index 000000000..1d5175540 --- /dev/null +++ b/crates/math/src/symbol_fonts.rs @@ -0,0 +1,316 @@ +//! Word's symbol fonts — Symbol, Wingdings, Wingdings 2, Wingdings 3 and Webdings — mapped to +//! standard Unicode characters, so text set in them shows the intended symbols when the font +//! isn't installed (they are proprietary and never bundled) and exports as real characters. +//! +//! Word stores a symbol-font character either as the private-use code U+F000 + the font's own +//! 8-bit code (U+F020–U+F0FF, what Insert › Symbol and `w:sym` write) or as the plain 8-bit code +//! (U+0020–U+00FF) in a run whose font is the symbol font. Both map the same way. The stored text +//! never changes: the mapping is for display, layout and plain-text output only. +//! +//! Sources (Unicode's own published data; no font file was read): +//! - Symbol: the Adobe Symbol encoding table published by Unicode, +//! (codes it maps to the +//! private use area are left out; 0x6D maps to GREEK SMALL LETTER MU). +//! - Wingdings, Wingdings 2, Wingdings 3, Webdings: the correspondence tables in "Status of +//! encoding of Wingdings and Webdings Symbols", Unicode L2/12-368 (WG2 N4384, M. Suignard, +//! 2012), the frozen repertoire of the Unicode 7.0 encoding (earlier drafts L2/11-052, +//! L2/11-344), checked against the Unicode Character Database names. The one character not +//! encoded (Wingdings 0xFF) has no entry. +//! +//! Tables are indexed by code − 0x20; 0 = no Unicode equivalent. + +/// The symbol table for a single family name, by lowercase family name. +fn single_table(family: &str) -> Option<&'static [u32; 224]> { + let f = family.trim(); + if f.eq_ignore_ascii_case("symbol") || f.eq_ignore_ascii_case("symbol (pcl6)") { + Some(&SYMBOL) + } else if f.eq_ignore_ascii_case("wingdings") { + Some(&WINGDINGS) + } else if f.eq_ignore_ascii_case("wingdings 2") { + Some(&WINGDINGS_2) + } else if f.eq_ignore_ascii_case("wingdings 3") { + Some(&WINGDINGS_3) + } else if f.eq_ignore_ascii_case("webdings") { + Some(&WEBDINGS) + } else { + None + } +} + +/// The symbol fonts this module knows, by lowercase family name. +fn table(family: &str) -> Option<&'static [u32; 224]> { + if family.contains(';') { family.split(';').map(str::trim).filter(|s| !s.is_empty()).find_map(single_table) } else { single_table(family) } +} + +/// Whether `family` is one of Word's symbol fonts (Symbol, Wingdings, Wingdings 2, Wingdings 3, +/// Webdings), whose characters [`symbol_char`] maps. +pub fn is_symbol_font(family: &str) -> bool { + table(family).is_some() +} + +/// The standard Unicode character for `c` in a run set in the symbol font `family`: `c` is the +/// font's code stored as U+F020–U+F0FF or as U+0020–U+00FF (except the soft hyphen U+00AD). +/// `None` for other fonts, other characters and codes with no Unicode equivalent. +pub fn symbol_char(family: &str, c: char) -> Option { + let t = table(family)?; + let u = u32::from(c); + let code = match u { + 0xF020..=0xF0FF => u - 0xF000, + // A soft hyphen stays a soft hyphen (Word stores `w:softHyphen` as U+00AD). + 0xAD => return None, + 0x20..=0xFF => u, + _ => return None, + }; + let i = usize::try_from(code.checked_sub(0x20)?).ok()?; + t.get(i).copied().filter(|v| *v != 0).and_then(char::from_u32) +} + +/// `text` (in a run set in `family`) with every symbol-font character replaced by its Unicode +/// equivalent; unchanged for other fonts. +pub fn map_text(family: &str, text: &str) -> String { + if !is_symbol_font(family) { + return text.to_string(); + } + text.chars().map(|c| symbol_char(family, c).unwrap_or(c)).collect() +} + +const SYMBOL: [u32; 224] = [ + 0x0020, 0x0021, 0x2200, 0x0023, 0x2203, 0x0025, 0x0026, 0x220B, // 0x20 + 0x0028, 0x0029, 0x2217, 0x002B, 0x002C, 0x2212, 0x002E, 0x002F, // 0x28 + 0x0030, 0x0031, 0x0032, 0x0033, 0x0034, 0x0035, 0x0036, 0x0037, // 0x30 + 0x0038, 0x0039, 0x003A, 0x003B, 0x003C, 0x003D, 0x003E, 0x003F, // 0x38 + 0x2245, 0x0391, 0x0392, 0x03A7, 0x0394, 0x0395, 0x03A6, 0x0393, // 0x40 + 0x0397, 0x0399, 0x03D1, 0x039A, 0x039B, 0x039C, 0x039D, 0x039F, // 0x48 + 0x03A0, 0x0398, 0x03A1, 0x03A3, 0x03A4, 0x03A5, 0x03C2, 0x03A9, // 0x50 + 0x039E, 0x03A8, 0x0396, 0x005B, 0x2234, 0x005D, 0x22A5, 0x005F, // 0x58 + 0x0000, 0x03B1, 0x03B2, 0x03C7, 0x03B4, 0x03B5, 0x03C6, 0x03B3, // 0x60 + 0x03B7, 0x03B9, 0x03D5, 0x03BA, 0x03BB, 0x03BC, 0x03BD, 0x03BF, // 0x68 + 0x03C0, 0x03B8, 0x03C1, 0x03C3, 0x03C4, 0x03C5, 0x03D6, 0x03C9, // 0x70 + 0x03BE, 0x03C8, 0x03B6, 0x007B, 0x007C, 0x007D, 0x223C, 0x0000, // 0x78 + 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, // 0x80 + 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, // 0x88 + 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, // 0x90 + 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, // 0x98 + 0x20AC, 0x03D2, 0x2032, 0x2264, 0x2044, 0x221E, 0x0192, 0x2663, // 0xA0 + 0x2666, 0x2665, 0x2660, 0x2194, 0x2190, 0x2191, 0x2192, 0x2193, // 0xA8 + 0x00B0, 0x00B1, 0x2033, 0x2265, 0x00D7, 0x221D, 0x2202, 0x2022, // 0xB0 + 0x00F7, 0x2260, 0x2261, 0x2248, 0x2026, 0x0000, 0x0000, 0x21B5, // 0xB8 + 0x2135, 0x2111, 0x211C, 0x2118, 0x2297, 0x2295, 0x2205, 0x2229, // 0xC0 + 0x222A, 0x2283, 0x2287, 0x2284, 0x2282, 0x2286, 0x2208, 0x2209, // 0xC8 + 0x2220, 0x2207, 0x0000, 0x0000, 0x0000, 0x220F, 0x221A, 0x22C5, // 0xD0 + 0x00AC, 0x2227, 0x2228, 0x21D4, 0x21D0, 0x21D1, 0x21D2, 0x21D3, // 0xD8 + 0x25CA, 0x2329, 0x0000, 0x0000, 0x0000, 0x2211, 0x0000, 0x0000, // 0xE0 + 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, // 0xE8 + 0x0000, 0x232A, 0x222B, 0x2320, 0x0000, 0x2321, 0x0000, 0x0000, // 0xF0 + 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, // 0xF8 +]; + +const WEBDINGS: [u32; 224] = [ + 0x0020, 0x1F577, 0x1F578, 0x1F572, 0x1F576, 0x1F3C6, 0x1F396, 0x1F587, // 0x20 + 0x1F5E8, 0x1F5E9, 0x1F5F0, 0x1F5F1, 0x1F336, 0x1F397, 0x1F67E, 0x1F67C, // 0x28 + 0x1F5D5, 0x1F5D6, 0x1F5D7, 0x23F4, 0x23F5, 0x23F6, 0x23F7, 0x23EA, // 0x30 + 0x23E9, 0x23EE, 0x23ED, 0x23F8, 0x23F9, 0x23FA, 0x1F5DA, 0x1F5F3, // 0x38 + 0x1F6E0, 0x1F3D7, 0x1F3D8, 0x1F3D9, 0x1F3DA, 0x1F3DC, 0x1F3ED, 0x1F3DB, // 0x40 + 0x1F3E0, 0x1F3D6, 0x1F3DD, 0x1F6E3, 0x1F50D, 0x1F3D4, 0x1F441, 0x1F442, // 0x48 + 0x1F3DE, 0x1F3D5, 0x1F6E4, 0x1F3DF, 0x1F6F3, 0x1F56C, 0x1F56B, 0x1F568, // 0x50 + 0x1F508, 0x1F394, 0x1F395, 0x1F5EC, 0x1F67D, 0x1F5ED, 0x1F5EA, 0x1F5EB, // 0x58 + 0x2B94, 0x2714, 0x1F6B2, 0x2B1C, 0x1F6E1, 0x1F4E6, 0x1F6F1, 0x2B1B, // 0x60 + 0x1F691, 0x1F6C8, 0x1F6E9, 0x1F6F0, 0x1F7C8, 0x1F574, 0x2B24, 0x1F6E5, // 0x68 + 0x1F694, 0x1F5D8, 0x1F5D9, 0x2753, 0x1F6F2, 0x1F687, 0x1F68D, 0x26F3, // 0x70 + 0x29B8, 0x2296, 0x1F6AD, 0x1F5EE, 0x23D0, 0x1F5EF, 0x1F5F2, 0x0000, // 0x78 + 0x1F6B9, 0x1F6BA, 0x1F6C9, 0x1F6CA, 0x1F6BC, 0x1F47D, 0x1F3CB, 0x26F7, // 0x80 + 0x1F3C2, 0x1F3CC, 0x1F3CA, 0x1F3C4, 0x1F3CD, 0x1F3CE, 0x1F698, 0x1F5E0, // 0x88 + 0x1F6E2, 0x1F4B0, 0x1F3F7, 0x1F4B3, 0x1F46A, 0x1F5E1, 0x1F5E2, 0x1F5E3, // 0x90 + 0x272F, 0x1F584, 0x1F585, 0x1F583, 0x1F586, 0x1F5B9, 0x1F5BA, 0x1F5BB, // 0x98 + 0x1F575, 0x1F570, 0x1F5BD, 0x1F5BE, 0x1F4CB, 0x1F5D2, 0x1F5D3, 0x1F56E, // 0xA0 + 0x1F4DA, 0x1F5DE, 0x1F5DF, 0x1F5C3, 0x1F5C2, 0x1F5BC, 0x1F3AD, 0x1F39C, // 0xA8 + 0x1F398, 0x1F399, 0x1F3A7, 0x1F4BF, 0x1F39E, 0x1F4F7, 0x1F39F, 0x1F3AC, // 0xB0 + 0x1F4FD, 0x1F4F9, 0x1F4FE, 0x1F4FB, 0x1F39A, 0x1F39B, 0x1F4FA, 0x1F4BB, // 0xB8 + 0x1F5A5, 0x1F5A6, 0x1F5A7, 0x1F579, 0x1F3AE, 0x1F57B, 0x1F57C, 0x1F4DF, // 0xC0 + 0x1F581, 0x1F580, 0x1F5A8, 0x1F5A9, 0x1F5BF, 0x1F5AA, 0x1F5DC, 0x1F512, // 0xC8 + 0x1F513, 0x1F5DD, 0x1F4E5, 0x1F4E4, 0x1F573, 0x1F323, 0x1F324, 0x1F325, // 0xD0 + 0x1F326, 0x2601, 0x1F328, 0x1F327, 0x1F329, 0x1F32A, 0x1F32C, 0x1F32B, // 0xD8 + 0x1F31C, 0x1F321, 0x1F6CB, 0x1F6CF, 0x1F37D, 0x1F378, 0x1F6CE, 0x1F6CD, // 0xE0 + 0x24C5, 0x267F, 0x1F6C6, 0x1F588, 0x1F393, 0x1F5E4, 0x1F5E5, 0x1F5E6, // 0xE8 + 0x1F5E7, 0x1F6EA, 0x1F43F, 0x1F426, 0x1F41F, 0x1F415, 0x1F408, 0x1F66C, // 0xF0 + 0x1F66E, 0x1F66D, 0x1F66F, 0x1F5FA, 0x1F30D, 0x1F30F, 0x1F30E, 0x1F54A, // 0xF8 +]; + +const WINGDINGS: [u32; 224] = [ + 0x0020, 0x1F589, 0x2702, 0x2701, 0x1F453, 0x1F56D, 0x1F56E, 0x1F56F, // 0x20 + 0x1F57F, 0x2706, 0x1F582, 0x1F583, 0x1F4EA, 0x1F4EB, 0x1F4EC, 0x1F4ED, // 0x28 + 0x1F5C0, 0x1F5C1, 0x1F5CE, 0x1F5CF, 0x1F5D0, 0x1F5C4, 0x23F3, 0x1F5AE, // 0x30 + 0x1F5B0, 0x1F5B2, 0x1F5B3, 0x1F5B4, 0x1F5AB, 0x1F5AC, 0x2707, 0x270D, // 0x38 + 0x1F58E, 0x270C, 0x1F58F, 0x1F44D, 0x1F44E, 0x261C, 0x261E, 0x261D, // 0x40 + 0x1F597, 0x1F590, 0x263A, 0x1F610, 0x2639, 0x1F4A3, 0x1F571, 0x1F3F3, // 0x48 + 0x1F3F1, 0x2708, 0x263C, 0x1F322, 0x2744, 0x1F546, 0x271E, 0x1F548, // 0x50 + 0x2720, 0x2721, 0x262A, 0x262F, 0x1F549, 0x2638, 0x2648, 0x2649, // 0x58 + 0x264A, 0x264B, 0x264C, 0x264D, 0x264E, 0x264F, 0x2650, 0x2651, // 0x60 + 0x2652, 0x2653, 0x1F670, 0x1F675, 0x26AB, 0x1F53E, 0x25FC, 0x1F78F, // 0x68 + 0x1F790, 0x2751, 0x2752, 0x1F79F, 0x29EB, 0x25C6, 0x2756, 0x1F799, // 0x70 + 0x2327, 0x2BB9, 0x2318, 0x1F3F5, 0x1F3F6, 0x1F676, 0x1F677, 0x0000, // 0x78 + 0x1F10B, 0x2780, 0x2781, 0x2782, 0x2783, 0x2784, 0x2785, 0x2786, // 0x80 + 0x2787, 0x2788, 0x2789, 0x1F10C, 0x278A, 0x278B, 0x278C, 0x278D, // 0x88 + 0x278E, 0x278F, 0x2790, 0x2791, 0x2792, 0x2793, 0x1F662, 0x1F660, // 0x90 + 0x1F661, 0x1F663, 0x1F65E, 0x1F65C, 0x1F65D, 0x1F65F, 0x2219, 0x2022, // 0x98 + 0x2B1D, 0x2B58, 0x1F786, 0x1F788, 0x1F78A, 0x1F78B, 0x1F53F, 0x25AA, // 0xA0 + 0x1F78E, 0x1F7C1, 0x1F7C5, 0x2605, 0x1F7CB, 0x1F7CF, 0x1F7D3, 0x1F7D1, // 0xA8 + 0x2BD0, 0x2316, 0x2BCE, 0x2BCF, 0x2BD1, 0x272A, 0x2730, 0x1F550, // 0xB0 + 0x1F551, 0x1F552, 0x1F553, 0x1F554, 0x1F555, 0x1F556, 0x1F557, 0x1F558, // 0xB8 + 0x1F559, 0x1F55A, 0x1F55B, 0x2BB0, 0x2BB1, 0x2BB2, 0x2BB3, 0x2BB4, // 0xC0 + 0x2BB5, 0x2BB6, 0x2BB7, 0x1F66A, 0x1F66B, 0x1F655, 0x1F654, 0x1F657, // 0xC8 + 0x1F656, 0x1F650, 0x1F651, 0x1F652, 0x1F653, 0x232B, 0x2326, 0x2B98, // 0xD0 + 0x2B9A, 0x2B99, 0x2B9B, 0x2B88, 0x2B8A, 0x2B89, 0x2B8B, 0x1F868, // 0xD8 + 0x1F86A, 0x1F869, 0x1F86B, 0x1F86C, 0x1F86D, 0x1F86F, 0x1F86E, 0x1F878, // 0xE0 + 0x1F87A, 0x1F879, 0x1F87B, 0x1F87C, 0x1F87D, 0x1F87F, 0x1F87E, 0x21E6, // 0xE8 + 0x21E8, 0x21E7, 0x21E9, 0x2B04, 0x21F3, 0x2B01, 0x2B00, 0x2B03, // 0xF0 + 0x2B02, 0x1F8AC, 0x1F8AD, 0x1F5F6, 0x2713, 0x1F5F7, 0x1F5F9, 0x0000, // 0xF8 +]; + +const WINGDINGS_2: [u32; 224] = [ + 0x0020, 0x1F58A, 0x1F58B, 0x1F58C, 0x1F58D, 0x2704, 0x2700, 0x1F57E, // 0x20 + 0x1F57D, 0x1F5C5, 0x1F5C6, 0x1F5C7, 0x1F5C8, 0x1F5C9, 0x1F5CA, 0x1F5CB, // 0x28 + 0x1F5CC, 0x1F5CD, 0x1F4CB, 0x1F5D1, 0x1F5D4, 0x1F5B5, 0x1F5B6, 0x1F5B7, // 0x30 + 0x1F5B8, 0x1F5AD, 0x1F5AF, 0x1F5B1, 0x1F592, 0x1F593, 0x1F598, 0x1F599, // 0x38 + 0x1F59A, 0x1F59B, 0x1F448, 0x1F449, 0x1F59C, 0x1F59D, 0x1F59E, 0x1F59F, // 0x40 + 0x1F5A0, 0x1F5A1, 0x1F446, 0x1F447, 0x1F5A2, 0x1F5A3, 0x1F591, 0x1F5F4, // 0x48 + 0x1F5F8, 0x1F5F5, 0x2611, 0x2BBD, 0x2612, 0x2BBE, 0x2BBF, 0x1F6C7, // 0x50 + 0x29B8, 0x1F671, 0x1F674, 0x1F672, 0x1F673, 0x203D, 0x1F679, 0x1F67A, // 0x58 + 0x1F67B, 0x1F666, 0x1F664, 0x1F665, 0x1F667, 0x1F65A, 0x1F658, 0x1F659, // 0x60 + 0x1F65B, 0x24EA, 0x2460, 0x2461, 0x2462, 0x2463, 0x2464, 0x2465, // 0x68 + 0x2466, 0x2467, 0x2468, 0x2469, 0x24FF, 0x2776, 0x2777, 0x2778, // 0x70 + 0x2779, 0x277A, 0x277B, 0x277C, 0x277D, 0x277E, 0x277F, 0x0000, // 0x78 + 0x2609, 0x1F315, 0x263D, 0x263E, 0x2E3F, 0x271D, 0x1F547, 0x1F55C, // 0x80 + 0x1F55D, 0x1F55E, 0x1F55F, 0x1F560, 0x1F561, 0x1F562, 0x1F563, 0x1F564, // 0x88 + 0x1F565, 0x1F566, 0x1F567, 0x1F668, 0x1F669, 0x22C5, 0x1F784, 0x2981, // 0x90 + 0x25CF, 0x25CB, 0x1F785, 0x1F787, 0x1F789, 0x2299, 0x29BF, 0x1F78C, // 0x98 + 0x1F78D, 0x25FE, 0x25A0, 0x25A1, 0x1F791, 0x1F792, 0x1F793, 0x1F794, // 0xA0 + 0x25A3, 0x1F795, 0x1F796, 0x1F797, 0x1F798, 0x2B29, 0x2B25, 0x25C7, // 0xA8 + 0x1F79A, 0x25C8, 0x1F79B, 0x1F79C, 0x1F79D, 0x1F79E, 0x2B2A, 0x2B27, // 0xB0 + 0x25CA, 0x1F7A0, 0x25D6, 0x25D7, 0x2BCA, 0x2BCB, 0x2BC0, 0x2BC1, // 0xB8 + 0x2B1F, 0x2BC2, 0x2B23, 0x2B22, 0x2BC3, 0x2BC4, 0x1F7A1, 0x1F7A2, // 0xC0 + 0x1F7A3, 0x1F7A4, 0x1F7A5, 0x1F7A6, 0x1F7A7, 0x1F7A8, 0x1F7A9, 0x1F7AA, // 0xC8 + 0x1F7AB, 0x1F7AC, 0x1F7AD, 0x1F7AE, 0x1F7AF, 0x1F7B0, 0x1F7B1, 0x1F7B2, // 0xD0 + 0x1F7B3, 0x1F7B4, 0x1F7B5, 0x1F7B6, 0x1F7B7, 0x1F7B8, 0x1F7B9, 0x1F7BA, // 0xD8 + 0x1F7BB, 0x1F7BC, 0x1F7BD, 0x1F7BE, 0x1F7BF, 0x1F7C0, 0x1F7C2, 0x1F7C4, // 0xE0 + 0x1F7C6, 0x1F7C9, 0x1F7CA, 0x2736, 0x1F7CC, 0x1F7CE, 0x1F7D0, 0x1F7D2, // 0xE8 + 0x2739, 0x1F7C3, 0x1F7C7, 0x272F, 0x1F7CD, 0x1F7D4, 0x2BCC, 0x2BCD, // 0xF0 + 0x203B, 0x2042, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, // 0xF8 +]; + +const WINGDINGS_3: [u32; 224] = [ + 0x0020, 0x2B60, 0x2B62, 0x2B61, 0x2B63, 0x2B66, 0x2B67, 0x2B69, // 0x20 + 0x2B68, 0x2B70, 0x2B72, 0x2B71, 0x2B73, 0x2B76, 0x2B78, 0x2B7B, // 0x28 + 0x2B7D, 0x2B64, 0x2B65, 0x2B6A, 0x2B6C, 0x2B6B, 0x2B6D, 0x2B4D, // 0x30 + 0x2BA0, 0x2BA1, 0x2BA2, 0x2BA3, 0x2BA4, 0x2BA5, 0x2BA6, 0x2BA7, // 0x38 + 0x2B90, 0x2B91, 0x2B92, 0x2B93, 0x2B80, 0x2B83, 0x2B7E, 0x2B7F, // 0x40 + 0x2B84, 0x2B86, 0x2B85, 0x2B87, 0x2B8F, 0x2B8D, 0x2B8E, 0x2B8C, // 0x48 + 0x2B6E, 0x2B6F, 0x238B, 0x2324, 0x2303, 0x2325, 0x2423, 0x237D, // 0x50 + 0x21EA, 0x2BB8, 0x1F8A0, 0x1F8A1, 0x1F8A2, 0x1F8A3, 0x1F8A4, 0x1F8A5, // 0x58 + 0x1F8A6, 0x1F8A7, 0x1F8A8, 0x1F8A9, 0x1F8AA, 0x1F8AB, 0x1F850, 0x1F852, // 0x60 + 0x1F851, 0x1F853, 0x1F854, 0x1F855, 0x1F857, 0x1F856, 0x1F858, 0x1F859, // 0x68 + 0x25B2, 0x25BC, 0x25B3, 0x25BD, 0x25C0, 0x25B6, 0x25C1, 0x25B7, // 0x70 + 0x25E3, 0x25E2, 0x25E4, 0x25E5, 0x1F780, 0x1F782, 0x1F781, 0x0000, // 0x78 + 0x1F783, 0x2BC5, 0x2BC6, 0x2BC7, 0x2BC8, 0x2B9C, 0x2B9E, 0x2B9D, // 0x80 + 0x2B9F, 0x1F810, 0x1F812, 0x1F811, 0x1F813, 0x1F814, 0x1F816, 0x1F815, // 0x88 + 0x1F817, 0x1F818, 0x1F81A, 0x1F819, 0x1F81B, 0x1F81C, 0x1F81E, 0x1F81D, // 0x90 + 0x1F81F, 0x1F800, 0x1F802, 0x1F801, 0x1F803, 0x1F804, 0x1F806, 0x1F805, // 0x98 + 0x1F807, 0x1F808, 0x1F80A, 0x1F809, 0x1F80B, 0x1F820, 0x1F822, 0x1F824, // 0xA0 + 0x1F826, 0x1F828, 0x1F82A, 0x1F82C, 0x1F89C, 0x1F89D, 0x1F89E, 0x1F89F, // 0xA8 + 0x1F82E, 0x1F830, 0x1F832, 0x1F834, 0x1F836, 0x1F838, 0x1F83A, 0x1F839, // 0xB0 + 0x1F83B, 0x1F898, 0x1F89A, 0x1F899, 0x1F89B, 0x1F83C, 0x1F83E, 0x1F83D, // 0xB8 + 0x1F83F, 0x1F840, 0x1F842, 0x1F841, 0x1F843, 0x1F844, 0x1F846, 0x1F845, // 0xC0 + 0x1F847, 0x2BA8, 0x2BA9, 0x2BAA, 0x2BAB, 0x2BAC, 0x2BAD, 0x2BAE, // 0xC8 + 0x2BAF, 0x1F860, 0x1F862, 0x1F861, 0x1F863, 0x1F864, 0x1F865, 0x1F867, // 0xD0 + 0x1F866, 0x1F870, 0x1F872, 0x1F871, 0x1F873, 0x1F874, 0x1F875, 0x1F877, // 0xD8 + 0x1F876, 0x1F880, 0x1F882, 0x1F881, 0x1F883, 0x1F884, 0x1F885, 0x1F887, // 0xE0 + 0x1F886, 0x1F890, 0x1F892, 0x1F891, 0x1F893, 0x1F894, 0x1F896, 0x1F895, // 0xE8 + 0x1F897, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, // 0xF0 + 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, // 0xF8 +]; + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn both_storage_forms_map_alike() { + for f in ["Symbol", "Wingdings", "Wingdings 2", "Wingdings 3", "Webdings"] { + assert!(is_symbol_font(f)); + for code in 0x20u32..=0xFF { + let (Some(pua), Some(plain)) = (char::from_u32(0xF000 + code), char::from_u32(code)) else { continue }; + if code == 0xAD { + assert_eq!(symbol_char(f, plain), None); + continue; + } + assert_eq!(symbol_char(f, pua), symbol_char(f, plain), "{f} {code:#X}"); + } + } + } + + #[test] + fn pcl6_symbol_encoding() { + for family in ["Symbol (PCL6)", " symbol (pcl6) "] { + assert!(is_symbol_font(family)); + for code in 0x20..=0xFF { + let c = char::from_u32(code).unwrap(); + assert_eq!(symbol_char(family, c), symbol_char("Symbol", c)); + let pua = char::from_u32(0xF000 + code).unwrap(); + assert_eq!(symbol_char(family, pua), symbol_char("Symbol", pua)); + } + assert_eq!(symbol_char(family, '\u{F0B3}'), Some('≥')); + } + assert!(!is_symbol_font("Symbol (unknown)")); + } + + #[test] + fn symbol_uses_the_adobe_symbol_encoding() { + assert_eq!(symbol_char("Symbol", '\u{F061}'), Some('α')); + assert_eq!(symbol_char("symbol", 'a'), Some('α')); + assert_eq!(symbol_char("Symbol", 'm'), Some('μ')); + assert_eq!(symbol_char("Symbol", 'W'), Some('Ω')); + assert_eq!(symbol_char("Symbol", '\u{F0B7}'), Some('•')); + assert_eq!(symbol_char("Symbol", '\u{F0A5}'), Some('∞')); + assert_eq!(symbol_char("Symbol", '\u{F0D6}'), Some('√')); + // The radical extender is private use in the Adobe table: no equivalent. + assert_eq!(symbol_char("Symbol", '\u{F060}'), None); + } + + #[test] + fn wingdings_codes() { + assert_eq!(symbol_char("Wingdings", '\u{F04A}'), Some('☺')); + assert_eq!(symbol_char("Wingdings", 'J'), Some('☺')); + assert_eq!(symbol_char("Wingdings", 'L'), Some('☹')); + assert_eq!(symbol_char("Wingdings", '\u{F0FC}'), Some('✓')); + assert_eq!(symbol_char("Wingdings", '\u{F0FE}'), Some('\u{1F5F9}')); + assert_eq!(symbol_char("Wingdings", '\u{F06E}'), Some('◼')); + assert_eq!(symbol_char("Wingdings", '\u{F0A7}'), Some('▪')); + assert_eq!(symbol_char("Wingdings", '\u{F076}'), Some('❖')); + assert_eq!(symbol_char("Wingdings", '\u{F028}'), Some('\u{1F57F}')); + // The one character Unicode didn't encode. + assert_eq!(symbol_char("Wingdings", '\u{F0FF}'), None); + } + + #[test] + fn wingdings_2_3_and_webdings_codes() { + assert_eq!(symbol_char("Wingdings 2", '\u{F050}'), Some('\u{1F5F8}')); + assert_eq!(symbol_char("Wingdings 2", 'O'), Some('\u{1F5F4}')); + assert_eq!(symbol_char("Wingdings 2", '\u{F0FA}'), None); + assert_eq!(symbol_char("Wingdings 3", '\u{F021}'), Some('⭠')); + assert_eq!(symbol_char("Wingdings 3", '\u{F0F1}'), None); + assert_eq!(symbol_char("Webdings", '\u{F059}'), Some('\u{1F394}')); + assert_eq!(symbol_char("Webdings", 'a'), Some('\u{2714}')); + assert_eq!(symbol_char("Webdings", '\u{F0FF}'), Some('\u{1F54A}')); + } + + #[test] + fn other_fonts_and_characters_are_left_alone() { + assert!(!is_symbol_font("Arial")); + assert_eq!(symbol_char("Arial", '\u{F04A}'), None); + assert_eq!(symbol_char("Wingdings", '\u{1F600}'), None); + assert_eq!(symbol_char("Wingdings", '\u{10FFFF}'), None); + assert_eq!(symbol_char("Wingdings", '\u{1F}'), None); + assert_eq!(map_text("Wingdings", "J\u{F04C}é"), "☺☹\u{1F879}"); + assert_eq!(map_text("Arial", "J\u{F04C}"), "J\u{F04C}"); + } +} diff --git a/crates/math/tests/corpus.rs b/crates/math/tests/corpus.rs new file mode 100644 index 000000000..383b77783 --- /dev/null +++ b/crates/math/tests/corpus.rs @@ -0,0 +1,75 @@ +//! Round trips over equaSHion's corpus (storytold/craft-libs#29): its typed LaTeX equations +//! (`corpus/equations.tsv`), the MathLive-style LaTeX of `corpus/latex.tsv` and its OMML samples +//! from WordCraft and DeckCraft files (`corpus/omml/`). + +use craft_math::{Math, math, math_latex, mathml, omml}; + +const DIR: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/tests/corpus"); + +fn rows(file: &str) -> Vec> { + let text = std::fs::read_to_string(format!("{DIR}/{file}")).unwrap(); + text.lines().filter(|l| !l.trim().is_empty() && !l.starts_with('#')).map(|l| l.split('\t').map(str::to_string).collect()).collect() +} + +/// The equations of `equations.tsv`: (id, tree, display). +fn equations() -> Vec<(String, math::Arg, bool)> { + let v: Vec<_> = rows("equations.tsv").into_iter().map(|f| (f[0].clone(), math_latex::parse_latex(&f[1]), f[2].trim() == "1")).collect(); + assert!(v.len() >= 40, "{} rows", v.len()); + v +} + +#[test] +fn every_corpus_equation_reads_without_unknown_commands() { + for (id, tree, _) in equations() { + let lin = math::to_linear(&tree); + assert!(!tree.is_empty() && !lin.contains('\\'), "{id}: {lin}"); + } + for f in rows("latex.tsv") { + let lin = math::to_linear(&math_latex::parse_latex(&f[0])); + assert!(!lin.contains('\\'), "{}: {lin}", f[0]); + } +} + +#[test] +fn every_corpus_equation_survives_omml() { + for (id, tree, display) in equations() { + let eq = Math { nodes: tree.clone(), ..Default::default() }; + let xml = omml::write_str("", display, &eq, None); + let back = omml::read_str(&xml).unwrap_or_else(|| panic!("{id}: {xml}")); + // The writer states matrix column alignment the parser left implicit; the text is the same. + assert_eq!(math::to_linear(&back.nodes), math::to_linear(&tree), "{id}: {xml}"); + // And the OMML written from what was read is the same OMML. + let again = omml::write_str("", display, &Math { omml: String::new(), ..back }, None); + assert_eq!(again, xml, "{id}"); + } +} + +#[test] +fn every_corpus_equation_survives_mathml_and_latex() { + for (id, tree, display) in equations() { + let lin = math::to_linear(&tree); + let ml = mathml::to_mathml(&tree, display, ""); + assert_eq!(mathml::parse(&ml).and_then(|m| mathml::read(&m)), Some((lin.clone(), display)), "{id}: {ml}"); + let tex = math_latex::to_latex(&tree); + assert_eq!(math::to_linear(&math_latex::parse_latex(&tex)), lin, "{id}: {tex}"); + } +} + +#[test] +fn omml_samples_read_and_write_back() { + let mut n = 0; + for e in std::fs::read_dir(format!("{DIR}/omml")).unwrap().flatten() { + let xml = std::fs::read_to_string(e.path()).unwrap(); + let name = e.file_name(); + let m = omml::read_str(&xml).unwrap_or_else(|| panic!("{name:?}")); + assert!(!m.nodes.is_empty() && m.omml.starts_with("ab diff --git a/crates/math/tests/corpus/omml/deckcraft_pptx_roundtrip_frac_rpr.xml b/crates/math/tests/corpus/omml/deckcraft_pptx_roundtrip_frac_rpr.xml new file mode 100644 index 000000000..ca4636abf --- /dev/null +++ b/crates/math/tests/corpus/omml/deckcraft_pptx_roundtrip_frac_rpr.xml @@ -0,0 +1 @@ +x2 diff --git a/crates/math/tests/corpus/omml/wordcraft_docx_fixture_ssup.xml b/crates/math/tests/corpus/omml/wordcraft_docx_fixture_ssup.xml new file mode 100644 index 000000000..de1ea3b30 --- /dev/null +++ b/crates/math/tests/corpus/omml/wordcraft_docx_fixture_ssup.xml @@ -0,0 +1 @@ +x2 diff --git a/crates/math/tests/corpus/omml/wordcraft_docx_roundtrip_display_rad.xml b/crates/math/tests/corpus/omml/wordcraft_docx_roundtrip_display_rad.xml new file mode 100644 index 000000000..38a71f375 --- /dev/null +++ b/crates/math/tests/corpus/omml/wordcraft_docx_roundtrip_display_rad.xml @@ -0,0 +1 @@ +x diff --git a/crates/math/tests/corpus/omml/wordcraft_docx_roundtrip_foreign_attrs.xml b/crates/math/tests/corpus/omml/wordcraft_docx_roundtrip_foreign_attrs.xml new file mode 100644 index 000000000..270088e0b --- /dev/null +++ b/crates/math/tests/corpus/omml/wordcraft_docx_roundtrip_foreign_attrs.xml @@ -0,0 +1 @@ +x diff --git a/crates/math/tests/corpus/omml/wordcraft_docx_roundtrip_frac.xml b/crates/math/tests/corpus/omml/wordcraft_docx_roundtrip_frac.xml new file mode 100644 index 000000000..e13045b5e --- /dev/null +++ b/crates/math/tests/corpus/omml/wordcraft_docx_roundtrip_frac.xml @@ -0,0 +1 @@ +ab+1 diff --git a/crates/math/tests/omml_latex.rs b/crates/math/tests/omml_latex.rs new file mode 100644 index 000000000..6ecd9adc1 --- /dev/null +++ b/crates/math/tests/omml_latex.rs @@ -0,0 +1,41 @@ +//! OMML read into the tree and written as LaTeX means what GridCraft's direct OMML-to-LaTeX +//! reader (`crates/xlsx/src/omml.rs`) gave for its test cases, so GridCraft can read equations in +//! drawings through this crate. The LaTeX is compared by what it reads back as, not byte for byte. + +use craft_math::{math, math_latex, omml}; +fn tex(inner: &str) -> String { + let x = format!(r#"{inner}"#); + math_latex::to_latex(&omml::read_str(&x).unwrap().nodes) +} +#[test] +fn gridcraft_omml_cases_mean_the_same_latex() { + let brace = |chr: &str, pos: &str| { + format!( + "x" + ) + }; + let lim = "n"; + let under = format!("{}{lim}", brace("\u{23DF}", "bot")); + let cases: Vec<(String, &str)> = vec![ + ("x+1".into(), "x+1"), + ("ab".into(), "\\frac{a}{b}"), + ("x2".into(), "{x}^{2}"), + ("π".into(), "\\sqrt{\\pi }"), + ("i=1ni".into(), "\\sum_{i=1}^{n} {i}"), + ("f".into(), "\\int {f}"), + ("1001".into(), "\\left[ \\begin{matrix}1 & 0 \\\\ 0 & 1\\end{matrix} \\right]"), + ("sinx".into(), "\\sin x"), + ("R".into(), "\\mathbb{R}"), + ("if {x}".into(), "\\text{if \\{x\\}}"), + ("x".into(), "\\hat{x}"), + (under.clone(), "\\underbrace{x}_{n}"), + (format!("{under}2"), "{\\underbrace{x}_{n}}^{2}"), + (format!("{}{lim}", brace("\u{23DE}", "top")), "\\overbrace{x}^{n}"), + (format!("a{lim}"), "\\underset{n}{a}"), + (format!("{}+1{lim}", brace("\u{23DF}", "bot")), "\\underset{n}{\\underbrace{x}+1}"), + ]; + for (x, want) in cases { + let got = tex(&x); + assert_eq!(math::to_linear(&math_latex::parse_latex(&got)), math::to_linear(&math_latex::parse_latex(want)), "{x}: {got} for {want}"); + } +} diff --git a/crates/media-testkit/Cargo.toml b/crates/media-testkit/Cargo.toml new file mode 100644 index 000000000..827d2ae6b --- /dev/null +++ b/crates/media-testkit/Cargo.toml @@ -0,0 +1,12 @@ +[package] +name = "craft-media-testkit" +description = "Oracle-test support (ffmpeg discovery, fixture locations) for the craft-libs media crates. Test support only." +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +repository.workspace = true +publish = false + +[lints] +workspace = true diff --git a/crates/media-testkit/src/hostile.rs b/crates/media-testkit/src/hostile.rs new file mode 100644 index 000000000..1051d0405 --- /dev/null +++ b/crates/media-testkit/src/hostile.rs @@ -0,0 +1,89 @@ +//! Deterministic hostile-input hammer: truncations, bit flips and extreme-value overwrites of a +//! valid seed, each run under `catch_unwind` with a time budget. No dependencies, no `unsafe`. + +use std::fmt::Write as _; +use std::panic::{AssertUnwindSafe, catch_unwind}; +use std::time::{Duration, Instant}; + +/// xorshift64* PRNG. +pub struct Rng(pub u64); + +impl Rng { + /// The next value. + pub fn next_u64(&mut self) -> u64 { + self.0 ^= self.0 >> 12; + self.0 ^= self.0 << 25; + self.0 ^= self.0 >> 27; + self.0.wrapping_mul(0x2545_F491_4F6C_DD1D) + } + /// A value below `n` (0 for `n` = 0). + pub fn below(&mut self, n: usize) -> usize { + (self.next_u64() % n.max(1) as u64) as usize + } +} + +const EXTREMES: [u64; 8] = [0, 1, 0x7F, 0x80, 0xFF, 0xFFFF, 0x8000_0000, u64::MAX]; + +fn run_one(name: &str, what: &str, data: &[u8], run: &dyn Fn(&[u8])) { + let t = Instant::now(); + let r = catch_unwind(AssertUnwindSafe(|| run(data))); + let el = t.elapsed(); + assert!(r.is_ok(), "{name}: PANIC on {what} (len {})", data.len()); + assert!(el < Duration::from_secs(5), "{name}: HANG/slow ({el:?}) on {what} (len {})", data.len()); +} + +/// Run `run` over every truncation of `seed` (stepped beyond 4096 lengths), then `iters` random +/// mutations (bit flips, random bytes, 1/2/4/8-byte extreme-value overwrites in both +/// endiannesses, deletions, truncation). Panics, naming the mutation, on the first panic or on +/// a run slower than 5 s. +pub fn hammer(name: &str, seed: &[u8], iters: usize, run: impl Fn(&[u8])) { + run_one(name, "the unmodified seed", seed, &run); + let step = (seed.len() / 4096).max(1); + for n in (0..seed.len()).step_by(step) { + run_one(name, &format!("truncation to {n}"), &seed[..n], &run); + } + let mut rng = Rng((0x5EED_F00D ^ seed.len() as u64) | 1); + // CRAFT_MEDIA_HOSTILE_MULT=10 runs ten times the iterations (soak runs). + let mult = std::env::var("CRAFT_MEDIA_HOSTILE_MULT").ok().and_then(|v| v.parse::().ok()).unwrap_or(1); + for _ in 0..iters.saturating_mul(mult) { + let mut d = seed.to_vec(); + let mut what = String::new(); + for _ in 0..1 + rng.below(4) { + if d.is_empty() { + break; + } + let pos = rng.below(d.len()); + match rng.below(7) { + 0 => { + let b = rng.below(8); + d[pos] ^= 1 << b; + let _ = write!(what, "flip[{pos}].{b} "); + } + 1 => { + d[pos] = rng.next_u64() as u8; + let _ = write!(what, "set[{pos}]={:#x} ", d[pos]); + } + 2..=4 => { + let w = [1usize, 2, 4, 8][rng.below(4)]; + let v = EXTREMES[rng.below(EXTREMES.len())]; + let be = rng.below(2) == 0; + let bytes = if be { v.to_be_bytes()[8 - w..].to_vec() } else { v.to_le_bytes()[..w].to_vec() }; + let end = (pos + w).min(d.len()); + d[pos..end].copy_from_slice(&bytes[..end - pos]); + let _ = write!(what, "put{w}{}[{pos}]={v:#x} ", if be { "be" } else { "le" }); + } + 5 => { + let n = 1 + rng.below(16); + let end = (pos + n).min(d.len()); + d.drain(pos..end); + let _ = write!(what, "del[{pos}..{end}] "); + } + _ => { + d.truncate(pos); + let _ = write!(what, "trunc{pos} "); + } + } + } + run_one(name, &what, &d, &run); + } +} diff --git a/crates/media-testkit/src/lib.rs b/crates/media-testkit/src/lib.rs new file mode 100644 index 000000000..6d3a75525 --- /dev/null +++ b/crates/media-testkit/src/lib.rs @@ -0,0 +1,348 @@ +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] +//! Oracle-test support for the craft-libs media crates (craft-media, craft-audio, and the video +//! crate to come): ffmpeg/ffprobe discovery, the skip-or-fail rule, and fixture locations. +//! ffmpeg is used only as an external fixture generator and oracle (never linked). Test support +//! only: unpublished, and used as a dev-dependency. +//! +//! Tool search order: `CRAFT_MEDIA_FFMPEG` / `CRAFT_MEDIA_FFPROBE` (an explicit path; a wrong +//! path fails the test), then `PATH`, then well-known install directories. A missing tool, a +//! failed fixture generator or a failed ffprobe run prints `SKIPPED` and the test passes, unless +//! `CRAFT_MEDIA_REQUIRE_ORACLES=1` is set: then each of these fails the test. +//! Fixtures are generated into `$CRAFT_MEDIA_FIXTURES_DIR` or `/target/fixtures`, one +//! directory per crate or format, and never committed. +//! +//! [`hostile::hammer`] runs a parser over truncations and mutations of a valid input and fails on +//! a panic or a slow run; `CRAFT_MEDIA_HOSTILE_MULT=10` runs ten times the iterations. +//! +//! Failing loudly is what a test helper is for: a wrong `CRAFT_MEDIA_*` setting or an unwritable +//! fixture directory panics, which fails the test that asked. + +pub mod hostile; + +use std::path::{Path, PathBuf}; +use std::process::Command; +use std::sync::OnceLock; +use std::sync::atomic::{AtomicUsize, Ordering}; + +const REQUIRE_ENV: &str = "CRAFT_MEDIA_REQUIRE_ORACLES"; + +const KNOWN_DIRS: &[&str] = &[ + "/opt/homebrew/bin", + "/usr/local/bin", + "/usr/bin", + "/opt/local/bin", + "/snap/bin", + r"C:\ffmpeg\bin", + r"C:\Program Files\ffmpeg\bin", + r"C:\ProgramData\chocolatey\bin", +]; + +fn env_var(name: &str) -> String { + format!("CRAFT_MEDIA_{}", name.to_ascii_uppercase()) +} + +#[allow(clippy::panic)] +fn find_tool(name: &str) -> Option { + if let Some(e) = std::env::var_os(env_var(name)).filter(|e| !e.is_empty()) { + let p = PathBuf::from(e); + assert!(p.is_file(), "{} is set but `{}` is not a file", env_var(name), p.display()); + return Some(p); + } + let names = if cfg!(windows) { [format!("{name}.exe"), name.to_string()] } else { [name.to_string(), format!("{name}.exe")] }; + let path_dirs = std::env::var_os("PATH").map(|p| std::env::split_paths(&p).collect::>()).unwrap_or_default(); + let dirs = path_dirs.into_iter().chain(KNOWN_DIRS.iter().map(PathBuf::from)); + for dir in dirs { + for n in &names { + let p = dir.join(n); + if p.is_file() { + return Some(p); + } + } + } + None +} + +/// Find a tool silently (cached for the process for ffmpeg and ffprobe). +pub fn tool(name: &str) -> Option { + static FFMPEG: OnceLock> = OnceLock::new(); + static FFPROBE: OnceLock> = OnceLock::new(); + match name { + "ffmpeg" => FFMPEG.get_or_init(|| find_tool("ffmpeg")).clone(), + "ffprobe" => FFPROBE.get_or_init(|| find_tool("ffprobe")).clone(), + _ => find_tool(name), + } +} + +pub fn oracles_required() -> bool { + std::env::var(REQUIRE_ENV).is_ok_and(|v| matches!(v.trim().to_ascii_lowercase().as_str(), "1" | "true" | "yes" | "on")) +} + +/// Give up on an oracle check: print `SKIPPED` and return `None`, or fail when oracles are +/// required. +pub fn skip(reason: &str) -> Option { + skip_with(oracles_required(), reason) +} + +#[allow(clippy::panic)] +fn skip_with(required: bool, reason: &str) -> Option { + assert!(!required, "oracle: {reason}, and {REQUIRE_ENV}=1 forbids skipping oracle tests"); + eprintln!("SKIPPED (oracle): {reason}"); + None +} + +/// Run a fixture generator writing `tmp`, then rename it to `out`. A generator that cannot start +/// or fails skips (see [`skip`]); `required` is explicit so tests can set it without touching +/// the process environment. +pub fn run_generator(cmd: &mut Command, tmp: &Path, out: &Path, required: bool) -> Option { + let reason = match cmd.output() { + Ok(o) if o.status.success() => match std::fs::rename(tmp, out) { + Ok(()) => return Some(out.to_path_buf()), + Err(e) => format!("could not move {} into place: {e}", tmp.display()), + }, + Ok(o) => format!("generator failed for {} ({}): {}", out.display(), o.status, String::from_utf8_lossy(&o.stderr).trim()), + Err(e) => format!("could not start generator for {}: {e}", out.display()), + }; + let _ = std::fs::remove_file(tmp); + skip_with(required, &format!("{reason} (encoder unavailable?)")) +} + +fn tool_or_skip(name: &str) -> Option { + tool(name).or_else(|| skip(&format!("{name} not found (set {} or put {name} on PATH)", env_var(name)))) +} + +/// ffmpeg, or `None` after printing `SKIPPED` (a failure with `CRAFT_MEDIA_REQUIRE_ORACLES=1`). +pub fn ffmpeg() -> Option { + tool_or_skip("ffmpeg") +} + +/// ffprobe, or `None` after printing `SKIPPED` (a failure with `CRAFT_MEDIA_REQUIRE_ORACLES=1`). +pub fn ffprobe() -> Option { + tool_or_skip("ffprobe") +} + +/// `$CRAFT_MEDIA_FIXTURES_DIR/` or `/target/fixtures/`, created if missing. +#[allow(clippy::unwrap_used)] +pub fn fixture_subdir(name: &str) -> PathBuf { + let d = match std::env::var_os("CRAFT_MEDIA_FIXTURES_DIR").filter(|v| !v.is_empty()) { + Some(d) => PathBuf::from(d), + None => { + let here = Path::new(env!("CARGO_MANIFEST_DIR")); + let root = here.parent().and_then(Path::parent).unwrap_or(here); + root.join("target").join("fixtures") + } + } + .join(name); + std::fs::create_dir_all(&d).unwrap(); + d +} + +/// A new, empty directory in the system temporary directory that only this call created: made with +/// `create_dir`, which fails rather than follow a pre-planted name or symlink, so a test can write +/// fixed file names inside it. The caller removes it. +#[allow(clippy::panic)] +pub fn private_dir(tag: &str) -> PathBuf { + static N: AtomicUsize = AtomicUsize::new(0); + let nanos = std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).map_or(0, |d| d.as_nanos()); + for _ in 0..100 { + let n = N.fetch_add(1, Ordering::Relaxed); + let d = std::env::temp_dir().join(format!("craft-media-{tag}-{}-{nanos:x}-{n}", std::process::id())); + match std::fs::create_dir(&d) { + Ok(()) => return d, + Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => {} + Err(e) => panic!("cannot create {}: {e}", d.display()), + } + } + panic!("no free scratch directory name for {tag}"); +} + +/// A temporary sibling of `out` that no other thread or process will pick; the extension is kept +/// because ffmpeg chooses the muxer from it. +pub fn temp_path(out: &Path) -> PathBuf { + static N: AtomicUsize = AtomicUsize::new(0); + let tid = format!("{:?}", std::thread::current().id()).replace(|c: char| !c.is_ascii_alphanumeric(), ""); + let n = N.fetch_add(1, Ordering::Relaxed); + let stem = out.file_stem().map(|s| s.to_string_lossy().to_string()).unwrap_or_default(); + let name = match out.extension() { + Some(ext) => format!("{stem}.tmp-{}-{tid}-{n}.{}", std::process::id(), ext.to_string_lossy()), + None => format!("{stem}.tmp-{}-{tid}-{n}", std::process::id()), + }; + out.with_file_name(name) +} + +/// Run a fixture generator and print `FIXTURE `. +pub fn generate_and_report(name: &str, outputs: &[PathBuf], generate: impl FnOnce() -> Option) -> Option { + let existed = !outputs.is_empty() && outputs.iter().all(|p| std::fs::metadata(p).is_ok_and(|m| m.len() > 0)); + let r = generate(); + let status = match (&r, existed) { + (None, _) => "skipped", + (Some(_), true) => "cached", + (Some(_), false) => "made", + }; + println!("FIXTURE {status} {name}"); + r +} + +/// Check if ffmpeg has a specific encoder compiled in. +pub fn ffmpeg_has_encoder(ff: &Path, encoder: &str) -> bool { + let Ok(output) = Command::new(ff).args(["-hide_banner", "-encoders"]).output() else { + return false; + }; + if !output.status.success() { + return false; + } + parse_has_encoder(&String::from_utf8_lossy(&output.stdout), encoder) +} + +fn parse_has_encoder(stdout: &str, encoder: &str) -> bool { + stdout.lines().any(|line| { + let mut parts = line.split_whitespace(); + if let (Some(_flags), Some(name)) = (parts.next(), parts.next()) { name == encoder } else { false } + }) +} + +/// Report a skipped test that is not an oracle check (an unsupported platform or an optional +/// encoder capability). Unlike [`skip`], this never fails under `CRAFT_MEDIA_REQUIRE_ORACLES=1`. +pub fn skip_test(what: &str, reason: &str) { + eprintln!("SKIPPED ({what}): {reason}"); +} + +/// Find ffmpeg, or print a skip message and return None. +pub fn ffmpeg_or_skip(reason: &str) -> Option { + tool("ffmpeg").or_else(|| skip(&format!("{reason}: ffmpeg not found (set {} or put ffmpeg on PATH)", env_var("ffmpeg")))) +} + +/// Log progress of long tests. +pub fn set_progress(label: &str) { + eprintln!("PROGRESS: {label}"); +} + +/// Run closure with an execution deadline, terminating with a panic if the limit is exceeded. +#[allow(clippy::panic)] +pub fn with_deadline(secs: u64, f: F) { + let timeout_secs = std::env::var("CRAFT_TEST_TIMEOUT_SECS").ok().and_then(|s| s.parse().ok()).unwrap_or(secs); + with_timeout(timeout_secs, f); +} + +#[allow(clippy::panic)] +fn with_timeout(timeout_secs: u64, f: F) { + let (tx, rx) = std::sync::mpsc::channel(); + let handle = std::thread::spawn(move || { + f(); + let _ = tx.send(()); + }); + match rx.recv_timeout(std::time::Duration::from_secs(timeout_secs)) { + Ok(()) => { + if let Err(payload) = handle.join() { + std::panic::resume_unwind(payload); + } + } + Err(std::sync::mpsc::RecvTimeoutError::Timeout) => { + panic!("test exceeded execution deadline of {timeout_secs} seconds"); + } + Err(std::sync::mpsc::RecvTimeoutError::Disconnected) => { + if let Err(payload) = handle.join() { + std::panic::resume_unwind(payload); + } + } + } +} + +/// Return fixture directory for a crate/category, creating it if needed. +pub fn fixtures_dir(subdir: &str) -> PathBuf { + fixture_subdir(subdir) +} + +pub mod fixtures { + use super::temp_path; + use std::path::{Path, PathBuf}; + + /// Atomically publish a fixture by renaming `tmp` to `path`. + pub fn publish(tmp: &Path, path: &Path) -> std::io::Result<()> { + std::fs::rename(tmp, path) + } + + /// Generate fixture `out` using generator closure if it does not already exist. A generator + /// that returns `false`, or whose output cannot be moved into place, skips (see + /// [`skip`](super::skip)): a failure with `CRAFT_MEDIA_REQUIRE_ORACLES=1`, so a required + /// oracle run cannot pass with a fixture missing. + pub fn generate bool>(out: &Path, f: F) -> Option { + generate_with(out, super::oracles_required(), f) + } + + /// [`generate`] with `required` explicit, so tests can set it without touching the process + /// environment. + pub fn generate_with bool>(out: &Path, required: bool, f: F) -> Option { + if out.exists() { + return Some(out.to_path_buf()); + } + let tmp = temp_path(out); + let reason = if f(&tmp) { + match std::fs::rename(&tmp, out) { + Ok(()) => return Some(out.to_path_buf()), + Err(e) => format!("could not move {} into place: {e}", tmp.display()), + } + } else { + format!("fixture generator failed for {}", out.display()) + }; + let _ = std::fs::remove_file(&tmp); + super::skip_with(required, &reason) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn failed_generator_skips_when_optional() { + let dir = private_dir("testkit-gen-opt"); + let out = dir.join("fixture"); + assert!(fixtures::generate_with(&out, false, |_| false).is_none()); + assert!(!out.exists()); + std::fs::remove_dir_all(&dir).unwrap(); + } + + #[test] + #[should_panic(expected = "forbids skipping oracle tests")] + fn failed_generator_fails_when_required() { + let dir = private_dir("testkit-gen-req"); + let out = dir.join("fixture"); + let result = std::panic::catch_unwind(|| fixtures::generate_with(&out, true, |_| false)); + let _ = std::fs::remove_dir_all(&dir); + if let Err(panic) = result { + std::panic::resume_unwind(panic); + } + } + + #[test] + fn parse_has_encoder_exact_match() { + let sample = "\ +Encoders: + V..... = Video + ------ + V....D libvpx-vp9 libvpx VP9 (codec vp9) + V....D libvpx libvpx VP8 (codec vp8) + A....D flac FLAC (Free Lossless Audio Codec) +"; + assert!(parse_has_encoder(sample, "libvpx")); + assert!(parse_has_encoder(sample, "libvpx-vp9")); + assert!(parse_has_encoder(sample, "flac")); + assert!(!parse_has_encoder(sample, "vp8")); + assert!(!parse_has_encoder(sample, "libvp")); + } + + #[test] + fn with_deadline_completes() { + with_deadline(5, || { + // fast operation + }); + } + + #[test] + #[should_panic(expected = "test exceeded execution deadline")] + fn with_deadline_times_out() { + with_timeout(1, || { + std::thread::sleep(std::time::Duration::from_secs(3)); + }); + } +} diff --git a/crates/media/Cargo.toml b/crates/media/Cargo.toml new file mode 100644 index 000000000..cdbf28349 --- /dev/null +++ b/crates/media/Cargo.toml @@ -0,0 +1,80 @@ +[package] +name = "craft-media" +description = "Bit-level I/O, clean-room ISO BMFF (MP4), QuickTime (MOV) and Matroska (MKV, WebM) and MXF demuxers and muxers, and Ogg, AVI and MPEG-TS/PS demuxers." +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +repository.workspace = true + +[package.metadata.docs.rs] +all-features = true + +[lints] +workspace = true + +[features] +default = ["isobmff"] +bitstream = [] +isobmff = ["bitstream", "dep:thiserror"] +matroska = [] +# AVI (RIFF) and OpenDML demuxer (`craft_media::avi`). +avi = [] +# MXF demuxer and writer (`craft_media::mxf`); the writer formats dates with chrono. +mxf = ["dep:chrono"] +# MPEG-2 Systems demuxer: transport streams and program streams (`craft_media::mpegts`). +mpegts = [] +# Ogg demuxer (Ogg Opus and Vorbis mapping, `craft_media::ogg`). +ogg = [] +# Serialize and Deserialize for `Container`, `CodecId`, `CodecParams` and `PcmFormat`. +serde = ["dep:serde"] + +[dependencies] +thiserror = { workspace = true, optional = true } +serde = { workspace = true, optional = true } +chrono = { workspace = true, optional = true } + +[dev-dependencies] +craft-media-testkit = { workspace = true } +proptest = { workspace = true } +serde_json = { workspace = true } + +[[test]] +name = "fuzz" +required-features = ["isobmff"] + +[[test]] +name = "fuzz_matroska" +required-features = ["matroska"] + +[[test]] +name = "oracle_avi" +required-features = ["avi"] + +[[test]] +name = "oracle_demux" +required-features = ["isobmff"] + +[[test]] +name = "oracle_matroska" +required-features = ["matroska"] + +[[test]] +name = "oracle_mpegts" +required-features = ["mpegts"] + +[[test]] +name = "oracle_mux" +required-features = ["isobmff"] + +[[test]] +name = "oracle_mxf" +required-features = ["mxf"] + +[[test]] +name = "oracle_ogg" +required-features = ["ogg"] + +[[test]] +name = "roundtrip" +required-features = ["isobmff"] diff --git a/crates/media/README.md b/crates/media/README.md new file mode 100644 index 000000000..387ab8cdd --- /dev/null +++ b/crates/media/README.md @@ -0,0 +1,828 @@ +# craft-media + +Media containers and bit-level I/O for the Craft apps: an MSB-first bit reader and writer, +clean-room ISO BMFF (MP4), QuickTime (MOV) and Matroska (MKV, WebM) and MXF demuxers and muxers, and +Ogg, AVI and MPEG-2 Systems (transport and program stream) demuxers, written from the public specifications. No `unsafe`, no panics on malformed +input, builds for `wasm32-unknown-unknown`. Dependencies: `thiserror` (for `isobmff`), `chrono` +(for `mxf`), `serde` (optional). + +Codecs are in separate crates that depend on this one: [`craft-audio`](../audio/README.md) for +audio; `craft-video` for video. What both need lives here: the containers, the +bit I/O, one `ByteSource` trait, and the [shared identifiers](#containers-codecs-and-codec-parameters) +that codec crates use to describe a file and configure a decoder. + +## Features + +| Feature | Module | Enables | +|---|---|---| +| `bitstream` | `craft_media::bitstream` | none | +| `isobmff` | `craft_media::isobmff` | `bitstream`, `thiserror` | +| `matroska` | `craft_media::matroska` | none | +| `ogg` | `craft_media::ogg` | none | +| `avi` | `craft_media::avi` | none | +| `mxf` | `craft_media::mxf` | `chrono` | +| `mpegts` | `craft_media::mpegts` | none | +| (none) | `Container`, `CodecId`, `CodecParams`, `PcmFormat`, `xiph_lace`, `ByteSource`, `ReadSeekSource` | none | +| `serde` | `Serialize`/`Deserialize` on `Container`, `CodecId`, `CodecParams` and `PcmFormat` | `serde` | + +`default = ["isobmff"]`, so `bitstream` and `isobmff` build. `matroska` is opt-in: it is about as +much code as `isobmff`, and most users of MP4/MOV (LightCraft, FigCraft, SoundCraft, EffectCraft) +do not read Matroska. `ogg`, `avi`, `mxf` and `mpegts` are opt-in as well. The features are independent. + +```toml +craft-media = { git = "https://github.com/storytold/craft-libs", rev = "", features = ["matroska"] } +``` + +A crate that needs only bit I/O (a codec) uses: + +```toml +craft-media = { git = "https://github.com/storytold/craft-libs", rev = "", default-features = false, features = ["bitstream"] } +``` + +## Boundaries + +- In scope: bit-level reading and writing, and container demuxing and muxing (boxes, sample + tables, sample entries and codec configuration records) for audio and video tracks. +- Out of scope: codecs. Audio codecs are in `craft-audio`; video codecs (H.264, HEVC, ProRes, + DNx, VP8, VP9, AV1) are in `craft-video`. Containers only FilmCraft reads (MXF, + MPEG-TS/PS, AVI) are not here yet. +- Anything both the audio and the video codec crates need belongs here, so the two never depend + on each other. + +## Origin and API + +The code comes from FilmCraft's `filmcraft-bitstream`, `filmcraft-isobmff` and +`filmcraft-matroska` crates at +[storytold/filmcraft@6c3948a](https://github.com/storytold/filmcraft/commit/6c3948a36c80e4996d924766ba7157eec4fca85e). +Public items keep their names and signatures, so FilmCraft can turn all three crates into +re-exports (`pub use craft_media::isobmff::*;`), except for the renames below. Our own names use +US spelling; names taken from a specification keep its spelling. + +Renamed: + +| FilmCraft | craft-media | +|---|---| +| `matroska::Colour` | `matroska::Color` | +| `matroska::VideoInfo::colour` | `matroska::VideoInfo::color` | +| `matroska::VideoInfo::colour_space` | `matroska::VideoInfo::color_space` | + +The element IDs `element_ids::COLOUR` and `COLOUR_SPACE` and the field +`isobmff::VpcConfig::colour_primaries` keep the spellings of the Matroska and VP9 specifications. + +Output that differs on valid input: + +- Matroska lacing applies only to tracks with a `DefaultDuration`, and a lace ends at a timestamp + gap. Readers space the frames of a lace by `DefaultDuration`, so FilmCraft's laces moved frames + that followed a gap. +- The sample budget covers the whole file, so a multi-track file with more than 2²⁶ samples in + total fails with `TooLarge` (ISO BMFF: all tracks and fragments; Matroska: all tracks, and at + most 2¹⁶ TrackEntries). FilmCraft capped ISO BMFF per track and Matroska not at all. +- MOV and MP4 PCM chunks end at 1 MiB, as ffmpeg writes them; FilmCraft wrote + each contiguous run of one track as one chunk. The reader splits a PCM chunk above 16 MiB into + samples of at most 16 MiB; FilmCraft made it one sample, cut at 4 GiB. +- MOV PCM at 65,536 Hz and above, and unsigned 16-bit PCM, is written as `lpcm` (sound + description v2), and signed 8-bit PCM as `twos`. FilmCraft wrote 0 Hz for the former and + labeled the signedness wrongly for the latter two. `raw ` under a sound handler reads as PCM. +- Matroska `BlockDuration` is rounded to the nearest tick; FilmCraft truncated it. +- A Matroska `TimestampScale` above 2³² is ignored, like a zero scale. +- `matroska::MkvWriter` writes `MuxingApp` = `craft-media`, and `MuxOptions::default()` has + `writing_app` = `craft-media` (FilmCraft: `filmcraft-matroska` and `filmcraft`). Apps set + `writing_app` to their own name. + +Other differences: + +- `bitstream::BitReader::read_ue_plus` (from DeckCraft's copy) is new. +- `isobmff::boxes` is new: FilmCraft's private box iterator and byte reader, made public (see + [Box reader](#box-reader)). +- `BitReader::peek`, `BitReader::read_bits` and `BitWriter::write_bits` accept widths above 32 + without a debug assertion: `peek` and `read_bits` return the low 32 bits of the field (use + `read_bits_u64` for wide fields), and `write_bits` writes leading zero bits, at most 64 bits in + all. +- `bitstream::length_prefixed_nals` returns the new `BitError::InvalidNalLengthSize` for a + `length_size` outside 1 to 4 (as FilmCraft does since filmcraft#2953) and cannot overflow on a + hostile length prefix. +- `isobmff::PcmConfig::bytes_per_frame` saturates at `u32::MAX` for a hostile channel count. +- `matroska`: a cluster timestamp above `i64::MAX` saturates at `i64::MAX` (FilmCraft wraps it to + a negative value), and adding a block's relative timestamp saturates instead of overflowing (a + debug-build panic in FilmCraft). +- `matroska::Error::TooLarge` is new: indexing a file past the limits above returns it. +- `matroska::MuxOptions::max_lace_frames` is clamped to 1 to 256; FilmCraft wrote a corrupt + frame count above 256. +- `isobmff::Mp4Writer::set_sample_entry` returns an error when the new entry changes the codec, + the media type or the PCM frame size, and `Error::NoSuchTrack` for a bad index. FilmCraft + accepted any entry. +- `isobmff::Mp4Writer::write_sample` returns an error when a track would pass 2³² − 1 samples + (PCM: frames), the most `stsz` can count; FilmCraft clamped the count. +- `isobmff::ByteSource`, `matroska::ByteSource` and `ogg::ByteSource` are one trait, + `craft_media::ByteSource` (with `ReadSeekSource`, which was Matroska's). A type FilmCraft + implements both traits for keeps one of its two impls. +- `isobmff::Track`, `matroska::Track`, `ogg::Stream`, `avi::Stream`, `mxf::EssenceTrack` and `mpegts::Stream` have `codec_params()`, all returning a + `CodecParams` (`CodecId::Unknown` for a codec without an identifier). The MP4 one describes + the first sample's sample description; `codec_params_for(description_index)` gives any other, + and `has_mixed_descriptions()` says whether the samples use more than one. + `isobmff::CodecConfig` has `codec_id()` and `extradata()`, and `OpusConfig::opus_head()`. +- `ogg::Codec` and `ogg::Error`, and the `ogg` structs, are `#[non_exhaustive]`. + +## `bitstream` + +- `BitReader`: MSB-first reader with Exp-Golomb (`ue(v)`, `se(v)`, `te(v)`), as used by + H.264/HEVC/AV1 headers. +- `BitWriter`: the matching writer, for encoders and header rewriting. +- `unescape_rbsp` / `escape_rbsp`: remove or insert H.264/HEVC emulation-prevention bytes. +- `annexb_nals` / `length_prefixed_nals`: split Annex-B byte streams and AVCC/HVCC samples into + NAL units. +- `crc32`: CRC-32 (IEEE), as used by Matroska and PNG. + +## `isobmff` + +### Demuxing + +```rust +use craft_media::isobmff::{open, TrackKind}; + +let file = std::fs::File::open("clip.mov")?; +let mp4 = open(&file)?; // any ByteSource: &[u8], Vec, Arc<[u8]>, File, ... +let v = mp4.track_of_kind(TrackKind::Video).unwrap(); +let track = &mp4.tracks[v]; +let i = track.sample_at_presentation_time(1000).unwrap(); // track timescale, edit-adjusted +let key = track.sync_sample_before(i); // decode from here +let bytes = mp4.read_sample(&file, v, key)?; // raw sample (AVCC/HVCC length-prefixed NALs, ...) +``` + +- `ByteSource` (`len`, `read_at(offset, buf)`) is the input abstraction. Implementations exist for `[u8]`, + `Vec`, `&T`, `Arc`, `Box`, and `std::fs::File` on non-wasm targets. +- `open` reads only top-level box headers, `ftyp`, `moov` and every `moof`. It never reads `mdat`. + The one exception is the first sample of a `tmcd` track, which it reads (4 bytes) to get the timecode + start frame. +- `Mp4File`: brands, `is_quicktime`, movie `timescale`/`duration`, `tracks`, `metadata`, `fragmented`, + `fragment_count`, `chpl_chapters` (Nero `udta/chpl`). `read_chapters(src)` returns the chapter list: + the QuickTime chapter track (`tref/chap`) when there is one, else `chpl`. +- `Track`: `id`, `kind` (Video/Audio/Timecode/Subtitle/Other), `handler`, `timescale`, `duration`, + `language`, `tkhd` fields (size, matrix, volume, enabled), `entries: Vec`, `samples`, + `edits`, `edit_offset`, `references` (`tref`), `sdtp`, `sample_groups` (`sbgp`+`sgpd`, raw), `pcm_chunked`. + Helpers: `codec()`, `video()`, `audio()`, `presentation_pts(i)`, `sample_at_pts(pts)`, + `sample_at_presentation_time(t)`, `sync_sample_before(i)`, `sync_samples()`. +- `Sample`: `offset`, `size`, `dts`, `pts` (dts + ctts), `duration`, `is_sync` (all samples are sync when + `stss` is absent), `description_index`. All times are raw media time in the track timescale. +- **Edit lists:** `edits` holds the `elst` entries unchanged. `edit_offset` is + `leading empty edits (rescaled to media timescale) − first non-empty edit's media_time`, so + `presentation time = pts + edit_offset`. This matches ffprobe's timestamps for the common cases + (B-frame delay, AAC priming, empty-edit offsets). Multi-segment edits, dwells and rate changes are exposed + raw for the caller to interpret. +- **Uncompressed PCM** (`lpcm`, `sowt`, `twos`, `in24`, `in32`, `fl32`, `fl64`, `raw `, `ipcm`, `fpcm`) is + merged to one `Sample` per chunk (`pcm_chunked = true`), with `duration` in frames. This avoids one + table entry per audio frame. A chunk above 16 MiB becomes several samples of at most 16 MiB. + +#### Parsed boxes +`ftyp`, `moov/mvhd`, `trak/tkhd`, `edts/elst` (v0/v1), `tref`, `mdia/mdhd` (v0/v1, ISO and Mac language +codes), `hdlr` (ISO and Pascal names), `minf/stbl`: `stsd`, `stts`, `ctts` (v0/v1, read as signed), `stss`, +`stsc`, `stsz`/`stz2` (4/8/16-bit), `stco`/`co64`, `sdtp`, `sbgp`/`sgpd`, `udta/chpl`. Also `mvex/trex`, `moof/traf/tfhd/tfdt/trun` +(every `tfhd` base-offset mode and multiple `moof`s), and `udta` metadata (QuickTime `©xxx` atoms, +`meta/ilst`, and `meta/keys` (mdta)). `uuid`, `free`, `skip`, `wide`, `sidx` and `mfra` are skipped. +Boxes with 64-bit sizes and with size 0 (runs to the end of the file) are supported. + +#### Sample entries → `CodecConfig` +| Format | Config | +|---|---| +| `avc1`/`avc3` + `avcC` | `Avc(AvcConfig)`: profile, level, length size, SPS/PPS, extension bytes | +| `hvc1`/`hev1` + `hvcC` | `Hevc(HevcConfig)`: all header fields plus NAL arrays (`vps()/sps()/pps()`) | +| `av01` + `av1C` | `Av1(Av1Config)` | +| `vp09` + `vpcC` | `Vp9(VpcConfig)` | +| `apch apcn apcs apco ap4h ap4x` | `ProRes { fourcc }` | +| `jpeg mjpa mjpb` | `Jpeg { fourcc }` | +| `AVdn AVdh` | `Dnx { fourcc }` | +| `mp4a` + `esds` (in `wave` too) | `Aac(AacConfig)`: ASC bytes + decoded object type/rate/channels; `Mp3` for OTI 0x69/0x6B | +| `.mp3`/`.mp2` | `Mp3`: MPEG-1/2 audio of any layer (each frame header names it; `Track::codec_params()` reports `Mp1`, `Mp2` or `Mp3` from the first frame) | +| PCM fourccs | `Pcm(PcmConfig)`: bits, float, endianness (`enda`, lpcm flags, `pcmC`), channels, rate | +| `alac` | `Alac { cookie }` | +| `Opus` + `dOps` | `Opus(OpusConfig)` | +| `fLaC` + `dfLa` | `Flac(FlacConfig)` (STREAMINFO decoded) | +| `ac-3`/`ec-3` | `Ac3 { dac3 }` / `Eac3 { dec3 }` | +| `tmcd` | `Timecode(TimecodeConfig)`: flags (drop frame), timescale, frame duration, fps, start frame, reel name; `format_frame()` | +| anything else | `Unknown { fourcc, raw }` | + +Video entries also parse `colr` (`nclx`/`nclc`/ICC), `pasp`, `clap`, `fiel`, `gama` and `btrt` into +`VideoParams`, and QuickTime's `logs` box into `VideoParams::log_transfer_function`: the CoreMedia log +transfer-function identifier (`com.apple.rec2020.apple-log` for Apple Log), kept as text whatever +curve it names. It is non-empty UTF-8 without NUL of at most 255 bytes; anything else, or a second +`logs` box, reads as unknown, and the writer refuses an identifier the reader would not accept. Audio entries parse QuickTime sound description v0/v1/v2 into `AudioParams`. + +#### Robustness +The parser does not panic on malformed input; every error comes back as an `Error`. Table counts are +checked against the bytes in their box before anything is allocated. A constant-size `stsz` count is +clamped to what fits in the file. `trun` counts are checked, and the whole file (all tracks and +fragments) is capped at 2²⁶ samples. +`moov`/`moof` are capped at 1 GiB. Compressed movie headers (`cmov`) are rejected with +`Error::Unsupported`. + +### Muxing + +```rust +use craft_media::isobmff::*; +let mut w = Mp4Writer::new(std::io::Cursor::new(Vec::new()), WriterOptions::new(Brand::Mp4))?; +let v = w.add_track(TrackConfig::new(SampleEntry::avc(avcc, 1920, 1080), 90_000))?; +let mut acfg = TrackConfig::new(SampleEntry::aac(asc, 2, 48_000), 48_000); +acfg.media_start = Some(1024); // AAC encoder delay → edit list +let a = w.add_track(acfg)?; +w.write_sample(v, WriteSample { data: &au, duration: 3000, composition_offset: 6000, is_sync: true })?; +// ... interleave samples in decode order ... +let bytes = w.finish_faststart()?.into_inner(); // or finish() for moov-at-end +``` + +- `Mp4Writer` streams samples into a single `mdat`. `finish()` appends `moov`. + `finish_faststart()` (needs `W: Read + Write + Seek`) moves the media data forward in place and writes + `moov` before it. If `mdat` goes past 4 GiB the header becomes a large-size header, and chunk offsets + switch to `co64` when needed. +- Brands: `Brand::Mp4` writes `isom` with `isom iso2 avc1 mp41 mp42`. `Brand::Mov` writes `qt `, uses + QuickTime `hdlr`/Pascal names, and sets `wide` as the placeholder box. +- Tables written: `stts`, `ctts` (v1 when an offset is negative), `stss` (omitted when every sample is + sync), `stsc`, `stsz` (constant or table), `stco`/`co64`. Consecutive samples of one track share a chunk; + a PCM chunk ends at 1 MiB. +- Sample entries come from `SampleEntry` (`avc`, `hevc`, `prores`, `jpeg`, `aac`, `pcm`, or any demuxed + entry). Remuxing copies codec config, `colr`, `pasp`, `clap`, `fiel`, `gama` and `btrt`. + PCM is written as `sowt`/`twos` (16-bit) or `raw ` (8-bit) or sound description v2 `lpcm` in MOV, and as + `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. +- 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`. +- `WriterOptions::chapters` (`Chapter { start, title }`, starts in the movie timescale) writes a chapter + list in both forms players read: a QuickTime chapter track (a disabled `text` track with `gmhd`, + one length-prefixed UTF-8 sample plus `encd` atom per chapter, referenced by `tref/chap` from the first + video or audio track; Apple's QuickTime File Format Specification, 2016 edition, "Chapter lists" + and "Text media") for Apple players, and a Nero `udta/chpl` list (version 1, 100 ns units; there is + no official specification, this is the publicly documented layout) for VLC and ffprobe. Chapters are + sorted, one per start time, cut to the movie duration, at most 255 (`MAX_CHAPTERS`) with titles of at + most 255 bytes (`MAX_CHAPTER_TITLE_BYTES`, cut at a character boundary). A first chapter after the + start is placed with an empty edit. The fragmented writer writes only `chpl`. +- `FragmentedWriter` writes fMP4. The init segment is `ftyp` + `moov` with `mvex/trex`. Each + `flush_fragment()` then writes `moof` (`mfhd`, `traf` with default-base-is-moof `tfhd`, `tfdt` v1, + `trun` with per-sample duration, size, flags and composition offset) followed by `mdat`. + +### Box reader + +`isobmff::boxes` gives direct access to the box format, for files and boxes the demuxer does not +model: CR3 `uuid` boxes, HEIF `meta` items, JPEG 2000 (JP2, JPX, JPM, MJ2) boxes. + +```rust +use craft_media::isobmff::boxes::{BoxIter, Reader}; + +for b in BoxIter::new(&bytes) { + let b = b?; + if b.kind == b"uuid" && b.user_type == Some(CANON_UUID) { + for c in BoxIter::within(&bytes, b.payload_range()) { /* CMT1..CMT4, THMB */ } + } +} +``` + +- `BoxIter::new(data)` yields the sibling boxes in `data`; `BoxIter::within(data, range)` yields + those in `data[range]` with offsets relative to `data`, so a walker keeps file offsets as it + descends. Each `BoxRef` has `kind`, `user_type` (the 16-byte extended type of a `uuid` box), + `offset`, `header_len`, `payload`, `payload_range()`, `range()` and `end()`. +- 64-bit `largesize` and size 0 (runs to the end of the range) are handled. A malformed header or a + box larger than the range yields one `Err` and ends the iteration; `allow_truncated()` instead + yields that last box cut at the end of the range, with `truncated` set. A 32-bit zero terminator + (QuickTime) ends the iteration. +- `BoxHeader::parse(buf)` reads one header (up to `BoxHeader::MAX_LEN` = 32 bytes), for scanning a + file through `ByteSource` without loading it. +- `Reader` is the bounds-checked big-endian cursor the demuxer uses: `u8` to `u64`, `i16` to + `i64`, `f64`, `u24`, `fourcc`, `full_header` (version and flags), `bytes`, `skip`, `rest` and + `count` (an entry count checked against the bytes left, before allocating). +- The iterator does not recurse. The caller bounds nesting depth and box count. + +### Limitations +- `presentation time = pts + edit_offset` only applies the leading empty edits and the first media + edit. Multi-segment edit lists, dwell edits and non-unity rates are exposed raw. ffmpeg handles an edit + that starts mid-frame differently: it snaps to the frame. +- Other data references (external `alis`/`url ` files), encrypted entries (`encv`/`enca`, `sinf`, + `senc`), `cmov`, and QuickTime reference movies are not supported. +- `sidx`/`mfra` are ignored, because the demuxer scans every top-level box. `stsd` entries with a + QuickTime color table are not decoded. +- Subtitle and text tracks (`tx3g`, `c608`, `wvtt`) and `mp4v` show up as `Unknown`. +- Muxer: one `mdat`, no chunk-size or duration limits outside PCM (the caller controls interleaving), no `sdtp`, + `sgpd`/`sbgp` or `cslg` output, ISO-style `meta/ilst` metadata is not written, and the fragmented + writer has no PCM, `sidx` or `mfra`. +- Chapters: at most 255 per file and 255 bytes per title (the `chpl` count and length fields are one + byte each); chapters past the end of the movie are dropped. Only the first `tref/chap` reference is + read, and chapter-track samples are read as titles only (`styl`/`hlit` atoms and per-chapter URLs or + images are ignored). ffprobe ends the last chapter early by the empty edit when the first chapter + starts after zero. + +## `matroska` + +A clean-room Matroska (MKV) and WebM demuxer, plus a minimal muxer, written from RFC 8794 (EBML), +RFC 9559 (Matroska), the Matroska codec mappings and the WebM container guidelines. No GPL or LGPL +code (FFmpeg, libmatroska, mkvtoolnix) was consulted; FFmpeg is a test oracle only. + +### Demuxing + +```rust +use craft_media::matroska::{Demuxer, TrackKind, open}; + +// Sample tables in the same shape as isobmff (any ByteSource: &[u8], Vec, Arc<[u8]>, File, ...) +let file = std::fs::File::open("clip.mkv")?; +let mkv = open(&file)?; +let v = mkv.track_of_kind(TrackKind::Video).unwrap(); +let k = mkv.keyframe_before(v, 2_000_000_000).unwrap(); // sample index +let frame = mkv.read_sample(&file, v, k)?; + +// Streaming packets and seeking (from a ByteSource, any Read + Seek, or a byte slice) +let mut d = Demuxer::from_reader(std::io::BufReader::new(std::fs::File::open("clip.webm")?))?; +let sp = d.seek(v, 2_000_000_000)?; // lands on the keyframe with pts <= 2 s +while let Some(p) = d.next_packet()? { // file order, all tracks + // p.track, p.pts (ticks), p.pts_ns, p.duration, p.keyframe, p.data +} +``` + +- **Open** (`open`, `open_with(src, &OpenOptions { index, verify_crc, index_limit })`): EBML header (DocType + `matroska` or `webm`), the first Segment, and its level-1 elements: SeekHead (followed for + elements after the clusters), Info, Tracks, Cues, Chapters, Tags, Attachments (listed with offset + and size; payloads are not read). With `index: true` (the default) every Cluster is scanned, + element and block headers only, to build per-track `Sample` tables (`offset`, `size`, `pts`, + `duration`, `keyframe`, cluster, block offset, lace index, `BlockAdditional` location) and + keyframe lists. With `index: false`, `open` stops at the first Cluster. +- **Progressive index** (`index_limit: Some(offset)`): the scan stops at that byte offset, so a + source that has loaded only the front of the file opens at once. The first Cluster is always + scanned; later ones only if they end below the limit. `MkvFile::index_end` is `Some(offset)` + while the index is incomplete (`indexed` is `false`; the tables are exact for everything before + it; Cues after the scanned part are not read yet), and `MkvFile::extend_index(src, &opts)` + continues from there with a larger limit (`None`: to the end, which completes the index) + without rescanning. A read that fails part-way (data not loaded yet) can be retried. +- **Timestamps:** Matroska ticks are `TimestampScale` ns (usually 1 ms); `Track::timebase` is that + as a reduced fraction of a second. `pts` is in ticks, `pts_ns` in exact nanoseconds. `CodecDelay` + is subtracted (RFC 9559), as FFmpeg does, so Opus and Vorbis priming gives negative pts. Laced + frames get `block ts + i × (BlockDuration or DefaultDuration) / n`; when neither is known, later + laces repeat the block timestamp and have `duration == 0` (`Packet::lace` tells which). +- **Keyframes:** the SimpleBlock keyframe flag; a BlockGroup is a keyframe when it has no + ReferenceBlock. +- **Lacing:** Xiph, fixed-size and EBML. **Unknown sizes:** a Segment (live or streamed output) and + Clusters end at the next top-level element. **CRC-32:** optional verification of level-1 + elements and clusters; mismatches go to `MkvFile::crc_errors` and are not fatal. +- **Damage:** an undecodable or oversized element starts a byte scan for the next plausible level-1 + element (a Cluster whose first child is Timestamp, or a sized metadata element); a truncated final + block is dropped. Problems are listed in `MkvFile::warnings`. +- **Limits:** indexing stops with `Error::TooLarge` past 2²⁶ frames in the file, past one frame + per file byte (each frame counts its stored size, and at least one byte), or past 2¹⁶ + TrackEntries. Level-1 elements read at most the file's length in all, so SeekHead entries that + point into one another are skipped with a warning. +- **Seeking** (`Demuxer::seek(track, time_ns)`): uses the sample index when present, otherwise Cues + (refined by scanning the cued cluster for the exact keyframe), otherwise builds the index by + scanning all clusters. `Demuxer::keyframe_index(track)` returns the keyframe list. +- **Block additions:** `MkvFile::read_sample_addition` returns the `BlockAdditional` with + `BlockAddID` 1 of an unlaced block (in WebM, the VP8/VP9 alpha layer). +- **Tracks:** number, UID, type, flags, `DefaultDuration`, name, language (and BCP 47), CodecID, + CodecPrivate, CodecName, `CodecDelay`, `SeekPreRoll`; `VideoInfo` (pixel and display size, crop, + interlacing, stereo, alpha mode, `pixel_aspect()`, `display_rotation()`), `Color` (matrix, + range, transfer, primaries, subsampling and siting, MaxCLL/MaxFALL, SMPTE 2086 mastering + metadata); `AudioInfo` (rate, output rate, channels, bit depth); `ContentEncoding`s. +- **Content encodings:** header stripping is undone in every packet and in `read_sample`. zlib, + bzlib and lzo compression and encryption are reported (`Track::frames_readable() == false`); + packets are then returned as stored and `read_sample` fails with `Unsupported`. +- `matroska::ebml` (public) has the EBML primitives: variable-length integers, element headers, + typed values, CRC-32 and lacing. `matroska::element_ids` lists the element IDs. + +#### Codec mapping (`Codec`) + +| CodecID | `Codec` | Payload | +|---|---|---| +| `V_MPEG4/ISO/AVC` | `Avc` | avcC (CodecPrivate) | +| `V_MPEGH/ISO/HEVC` | `Hevc` | hvcC | +| `V_VP8`, `V_VP9` | `Vp8`, `Vp9` | VP9 CodecPrivate features | +| `V_AV1` | `Av1` | av1C | +| `V_APV` | `Apv` | apvC | +| `V_PRORES` | `ProRes` | FourCC; frames get the 8-byte `size` + `icpf` header re-added | +| `V_MJPEG`, `V_MS/VFW/FOURCC` (MJPG) | `Mjpeg` | | +| `V_MS/VFW/FOURCC` (other) | `VfwFourcc` | BITMAPINFOHEADER | +| `A_AAC`, legacy `A_AAC/MPEG{2,4}/...` | `Aac` | AudioSpecificConfig (synthesized for legacy IDs, SBR included) | +| `A_OPUS` | `Opus` | OpusHead | +| `A_VORBIS` | `Vorbis` | three headers split from the Xiph-laced CodecPrivate | +| `A_FLAC` | `Flac` | `fLaC` + metadata blocks | +| `A_PCM/INT/LIT`, `A_PCM/INT/BIG`, `A_PCM/FLOAT/IEEE` | `Pcm` | bit depth from Audio | +| `A_AC3`, `A_EAC3`, `A_MPEG/L3`, `A_MPEG/L2`, `A_MPEG/L1` | `Ac3`, `Eac3`, `Mp3`, `Mp2`, `Mp1` | | +| `S_TEXT/UTF8` | `SubRip` | | +| `S_TEXT/WEBVTT`, `D_WEBVTT/*` (WebM) | `WebVtt` | WebM blocks keep `id\nsettings\npayload` | +| `S_TEXT/ASS`, `S_TEXT/SSA` | `Ass` | script header | +| anything else | `Other(id)` | `Track::codec_private` | + +`Codec::name()` matches FFmpeg's `codec_name` for these. + +### Muxing + +`MkvWriter::new(w: Write + Seek, Vec, MuxOptions)`, then `write_frame(track, pts_ns, +keyframe, data, duration_ns)` per frame, then `finish()`. It writes the EBML header, Segment, +SeekHead, Info (with Duration), Tracks, Clusters of SimpleBlocks (a new cluster at a video keyframe +after `cluster_duration_ns`), BlockGroups for frames whose duration differs from the track's +`default_duration_ns`, optional audio lacing (Xiph, EBML, fixed-size; for tracks with a +`default_duration_ns`, at most 256 frames, ending at a timestamp gap), and Cues (video keyframes, +or the first frame of each track per cluster). `MuxOptions::doc_type` = `"webm"` writes WebM. +`TrackSpec::color` writes a video track's `Colour` element (matrix, range, transfer, primaries, +chroma layout, light levels and mastering metadata: the fields that are set), which is where a WebM +file says it is Rec. 2020, P3, PQ or HLG. +CodecPrivate is fixed when the writer is created, so a codec whose configuration arrives with the +first frame (AV1 from `rav1e`) creates the writer after that frame. + +### Limitations + +- Only the first Segment is read (no linked or chained segments, no ordered-chapter playback). +- zlib, bzlib and lzo compressed and encrypted tracks are detected, but their frames are not + decoded. `EncryptedBlock` is ignored. +- `TrackTimestampScale` (deprecated) is ignored. +- Lace timestamps without any duration information repeat the block timestamp (FFmpeg derives them + from codec parsers). +- Muxer: no CRC-32, Chapters, Tags, Attachments, content encodings or block additions. + +## `ogg` + +A clean-room Ogg demuxer from FilmCraft's `filmcraft-ogg` (RFC 3533, RFC 7845 Ogg Opus, the Vorbis +I Ogg mapping). `open` reads every page (CRC-32 checked; damage is skipped by searching for the next +`OggS`), groups pages by logical stream and assembles packets across pages; codec headers are kept +apart from audio packets. A gap in a stream's page sequence numbers drops the packet the lost page +continued, and a beginning-of-stream page for a serial already seen starts a new stream (the next +link of a chained file), unless it carries on the page sequence of a stream with no end-of-stream +page yet. Damage recovery may read bytes again up to twice the file's length plus 1 MiB, so a file +is read at most about three times over; the packets kept and the header packets of a stream are +bounded too, with a warning when a bound is reached. +`OpusTiming` gives each Opus packet's start, the pre-skip and the end trimming of the final page. +No muxer. + +## `avi` + +A clean-room AVI demuxer from FilmCraft's `filmcraft-avi` (storytold/filmcraft@4bec22b), written +from Microsoft's published AVI RIFF file reference and the OpenDML AVI File Format Extensions 1.02. +No FFmpeg, libavformat or other AVI implementation was read; ffmpeg and ffprobe are test oracles +only. No muxer. + +```rust +use craft_media::avi::{open, StreamKind}; + +let file = open(&bytes)?; // any ByteSource +for (i, s) in file.streams.iter().enumerate() { + let params = s.codec_params(); // CodecId, FourCC, size or sample rate and channels + if s.kind == StreamKind::Video { + println!("{} {} fps", params.codec.name(), s.rate as f64 / s.scale as f64); + } + let first = file.read_chunk(&bytes, i, 0)?; // frame data, on demand +} +``` + +| Part | | +|---|---| +| Headers | `avih`; per stream `strh`, `strf` (`BITMAPINFOHEADER`, `WAVEFORMATEX` / `WAVEFORMATEXTENSIBLE`), `strn` | +| Index | OpenDML `indx` super index → `ix##` standard indexes (field indexes too), else `idx1` (offsets relative to `movi` or absolute), else a scan of the `movi` lists | +| Large files | `RIFF AVIX` extensions: through the OpenDML index, or scanned after `idx1`, which only covers the first RIFF | +| Key frames | from the index; a scan marks every chunk and says so (`keyframes_known`) | +| Damage | sizes clamped to the file (a cut-off recording opens with what is there) | + +Limits, each with a test: a header list of at most 16 MiB (larger is refused), at most 64 streams +(more are ignored), `rec ` lists nested at most 3 deep, at most 64 MiB of OpenDML standard indexes +(past that the file opens from `idx1` or a scan), and chunk tables bounded by what the file could +hold. + +`Stream::codec_params()` maps `biCompression` and the `WAVEFORMATEX` format tag to a `CodecId` +(Motion JPEG, H.264, HEVC, MPEG-4 Part 2, MPEG-2, VP8/VP9, AV1, ProRes, DNxHD; PCM, ADPCM, A-law, +µ-law, MP2, MP3, AAC, AC-3, Vorbis, FLAC). `extradata` is the bytes after the format header +as stored. For H.264 and HEVC, `Stream::nal_framing()` says what they are: nothing (parameter sets in +the chunks), Annex B parameter sets (a file written with global headers) or an `avcC` / `hvcC` record +(a stream copied from MP4, whose chunks are then length-prefixed by the size it gives; +`bitstream::length_prefixed_nals` splits them). Uncompressed video +is `CodecId::Unknown` with the FourCC in `tag`. + +Differences from `filmcraft-avi`: `ByteSource` is `craft_media::ByteSource`; `Error::Io` holds the +`io::Error` (FilmCraft: its text), so `Error` is no longer `Clone`/`PartialEq`, and is +`#[non_exhaustive]`; `Stream::codec_params()` is new. + +Tests: hand-built files for every index path, truncation, every single-byte mutation and random +multi-byte damage (never a panic). `tests/oracle_avi.rs` checks ffmpeg-made files (Motion JPEG, +H.264 with B-frames, BGR24, YUY2; PCM and MP3) against ffprobe; the ignored `opendml_file_past_1_gb` +checks a 1.16 GB OpenDML file with `AVIX` extensions. +## `mpegts` + +A clean-room MPEG-2 Systems demuxer from FilmCraft's `filmcraft-mpegts` +(storytold/filmcraft@4bec22b): transport streams (188-byte, 192-byte BDAV / M2TS, 204-byte) and +program streams (MPEG-1/2 PS, VOB, MOD). No GPL/LGPL code (FFmpeg, libavformat) was consulted; +FFmpeg is a fixture generator and test oracle only. No muxer, no decoding. + +```rust +use craft_media::mpegts::{Kind, open}; + +let file = open(&bytes)?; // any ByteSource +for s in &file.streams { + println!("{:?} {} {} units", s.id, s.codec.name(), s.units.len()); +} +let v = file.find(Kind::Video, |_| true).unwrap(); +let au: Vec = file.read_unit(&bytes, v, 0)?; // the first access unit +``` + +- **Transport streams**: 188-byte packets, 192-byte BDAV packets (sync byte after a 4-byte + arrival timestamp) and 204-byte packets; the packet size is sniffed from five consecutive sync + bytes. Lost sync resynchronises on the next aligned run. PSI sections are reassembled across + packets and checked with the MPEG CRC-32; the first program of the PAT is demuxed. Continuity + counter errors, CRC errors and resyncs are reported as warnings. +- **Program streams**: MPEG-2 and MPEG-1 packs, system headers, the program stream map (stream + types for elementary stream ids), padding, private stream 2 (DVD navigation) skipped, private + stream 1 split by sub-stream id. Garbage resynchronises on the next pack or PES start code. +- **Streams**: MPEG-1/2 video, H.264, HEVC, MPEG audio, AAC (ADTS, LATM/LOAS), AC-3, E-AC-3, + DTS, TrueHD, Blu-ray LPCM, DVD LPCM (format from the sub-stream header), PGS / DVB / teletext + subtitles; ISO 639 language from the PMT. +- **Access units**, found while the file is scanned (one pass, streaming; only a few bytes of + each stream are buffered): + - MPEG-1/2 video: a coded frame — a frame picture, or two field pictures (paired by + picture_structure) — with the sequence / GOP headers before it; picture type, temporal + reference, field structure, top_field_first, repeat_first_field, progressive_frame, closed + GOP / broken link. A PTS belongs to the unit whose picture start code is in that PES. + - H.264 / HEVC: PES packets with a timestamp (a PES without one continues the previous unit); + random access from IDR / IRAP NAL types; disposable when every slice is a non-reference. + - Audio: one frame per unit from the frame headers (sync re-hunted after garbage; a header + found while hunting is confirmed by the next one); a PTS belongs to the first frame starting + in the PES. + - LPCM and everything else: one PES packet per unit. +- **Timestamps**: 33-bit PTS/DTS unwrapped across the wrap (and back, for B pictures shown + before a wrap that came earlier); PCR / SCR range. +- **Reading**: a unit records only the position of its first packet and its offset in that + packet's payload; `read_unit` re-reads from there (the index costs a few dozen bytes per + unit, not per packet). + +`frame_bytes`, `frame_info` and `sei_has_recovery_point` are public: other containers that store +MPEG audio or AC-3 frames in chunks that do not follow them (AVI) find the frames again with them. + +`Codec::codec_id()` and `Stream::codec_params()` give the crate-wide `CodecId` / `CodecParams`. +MPEG-1 video reports `Mpeg2Video`; MPEG audio reports `Mp2` whatever its layer (the layer is in +each frame header: `frame_info(..).variant`); ADTS and LATM AAC both report `Aac`; DTS, TrueHD and +subtitles have no identifier (`Unknown`). The streams carry their configuration in band, so +`extradata` is empty; DVD LPCM fills `sample_rate`, `channels` and `pcm`. + +Limits, each with a test: 2²³ access units per stream (the rest are not indexed, with a warning), +128 MiB per unit read (`MAX_UNIT_BYTES`), a PES header given up after 1024 bytes, 16 stuffing bytes +in an MPEG-1 packet header, a pack header sniffed behind at most 64 zero bytes, and E-AC-3 frames of +at least 8 bytes. + +### Specifications + +| Document | Edition | Used for | +|---|---|---| +| ITU-T H.222.0 \| ISO/IEC 13818-1 | 2000 (second edition) | TS packets, adaptation fields, PCR, PSI (PAT / PMT, CRC-32 of Annex A), PES headers, PTS/DTS, program streams (pack, system header, program stream map), stream types | +| ISO/IEC 11172-1 | 1993 | MPEG-1 system streams (pack header, PES header stuffing / STD buffer / timestamps) | +| Blu-ray / AVCHD BDAV MPEG-2 TS layout (192-byte source packets with a 4-byte TP_extra_header; registration `HDMV`; stream types 0x80-0x92) | public descriptions | `.m2ts` / `.mts` | +| DVD-Video private stream 1 sub-stream layout (AC-3 / DTS 0x80-0x8F with a 3-byte header, LPCM 0xA0-0xAF with a 6-byte header, sub-pictures 0x20-0x3F) | public descriptions | `.vob` | +| ETSI EN 300 468 (descriptors 0x56, 0x59, 0x6A, 0x7A, 0x7B), ATSC A/52 Annex A (AC-3 in TS) | — | identifying private PES streams | +| ISO/IEC 11172-3, 13818-3 (frame headers), ISO/IEC 13818-7 (ADTS), 14496-3 (LOAS), ATSC A/52 (syncinfo, E-AC-3 frmsiz) | — | audio frame lengths for splitting | + +### Gaps + +- One program per TS (the first in the PAT); no program switching, no section-based + metadata (SDT / EIT), no scrambled streams. +- H.264 / HEVC access units follow PES packets: streams that put several pictures in one PES + packet (rare in practice; not seen in broadcast, AVCHD or FFmpeg output) would be indexed as + one unit. +- DVD navigation (IFO / NAV packets), multiple VOB concatenation and angle interleaving are not + handled; each file opens on its own. + +Differences from `filmcraft-mpegts`: `ByteSource` is `craft_media::ByteSource`; +`Error` is written by hand, without `thiserror`, and is `#[non_exhaustive]`; +`Codec::codec_id()` and `Stream::codec_params()` are new. + +Tests: a small TS muxer and PS writer (every access unit reads back byte-identical with its PTS, +key and disposable flags), 33-bit unwrap, truncation and mutation, streams of every codec filled +with random start codes and sync words, damaged PSI sections with valid CRCs, and the frame-header +helpers on arbitrary bytes. `tests/oracle_mpegts.rs` compares ten ffmpeg-made files (MPEG-2, H.264 +and HEVC video; MP2, ADTS and LATM AAC, AC-3, E-AC-3, Blu-ray and DVD LPCM; TS, M2TS, VOB and +MPEG-1 system streams) with ffprobe's packets: unit counts, sizes, timestamps and key flags. + +## `mxf` + +A clean-room MXF demuxer and writer from FilmCraft's `filmcraft-mxf` (storytold/filmcraft@4bec22b): +OP1a and OP-Atom, index tables, AVC / VC-3 / ProRes / MPEG-2 pictures and PCM sound. No GPL/LGPL +code (FFmpeg, libMXF, bmx, MXFLib) was consulted; FFmpeg is a fixture generator and test oracle +only. One dependency: `chrono`, for the calendar dates the writer stores. + +### Specifications + +Implemented from the SMPTE documents (editions used): + +| Document | Edition | Used for | +|---|---|---| +| SMPTE ST 336 | 2017 | KLV coding: 16-byte UL keys, BER lengths | +| SMPTE ST 377-1 | 2011 (+ Amd 1:2012) | partitions, primer pack, header metadata sets and local tags, index table segments, random index pack, run-in | +| SMPTE ST 378 | 2004 | OP1a | +| SMPTE ST 390 | 2011 | OP-Atom | +| SMPTE ST 379-1 / 379-2 | 2009 / 2010 | generic container: content packages, element keys, frame / clip wrapping | +| SMPTE ST 381-1 | 2005 | MPEG video mapping (MPEG-2 identified, MPEG video descriptor) | +| SMPTE ST 381-3 | 2013 | AVC byte-stream mapping and AVC sub-descriptor | +| SMPTE ST 382 | 2007 | AES3 and Broadcast Wave audio mapping (wave / AES3 descriptors) | +| SMPTE ST 331 | 2011 | element data of 8-channel AES3 sound (D-10) | +| SMPTE ST 386 | 2004 | D-10 (IMX) mapping: container label, sound element type | +| SMPTE ST 2019-4 | 2009 | VC-3 (DNxHD / DNxHR) mapping | +| SMPTE RDD 44 | 2017 | Apple ProRes mapping | +| SMPTE RP 224 / RP 210 | registers | labels: data definitions, picture coding, essence containers, operational patterns; property labels of the primer pack (writer) | +| SMPTE ST 330 | 2011 | basic UMIDs of the written packages | + +### Reading a file + +```rust +use craft_media::mxf::{TrackKind, open}; + +let mxf = open(&file)?; // any ByteSource +println!("{} {:?}", mxf.operational_pattern.name(), mxf.timecode.map(|t| t.format())); +let v = mxf.track_of_kind(TrackKind::Picture).unwrap(); +let t = &mxf.tracks[v]; +let key = t.sync_before(t.sample_at(42).unwrap()); // stored index of the random-access picture +let bytes = mxf.read_sample(&file, v, key)?; // one edit unit's essence +let a = mxf.track_of_kind(TrackKind::Sound).unwrap(); +let pcm = mxf.read_pcm(&file, a, 48_000, 1920)?; // planar f32, sample-exact +``` + +- **Open.** The header partition pack is found in the run-in (≤ 64 KiB). Every KLV packet is then + walked (keys and lengths only; essence values are skipped, never read): partition packs, primer + packs, header metadata local sets, index table segments, fill, and generic-container elements + (system items are ignored). A lost KLV sync resynchronises on the next partition pack; a + truncated file keeps everything before the cut (a truncated frame-wrapped picture is dropped, + clip-wrapped essence keeps its whole edit units). +- **Metadata.** The header metadata of the most complete partition is used (closed complete > + open complete > closed > open; later partitions win ties, so the footer's final durations are + preferred). Dynamic local tags resolve through the primer pack (e.g. `SubDescriptors`). +- **Tracks.** Material package picture/sound tracks → source clip → file package track (track + number, edit rate, origin) → descriptor (a multiple descriptor's sub-descriptor by + `LinkedTrackID`). Without a usable material package the file packages' tracks are used directly. + Elements are matched by track number, or — when the number is 0 or does not match (some OP-Atom + writers) — the only unclaimed element stream of the right kind. +- **Pictures.** One `Sample` per edit unit in stored order: frame wrapping (one element each) or + clip wrapping (one element split by the index: constant `EditUnitByteCount` or VBR entries). + Random access from index flag bit 7 (intra-only codings: every picture); without an index the + essence is scanned (AVC IDR, MPEG-2 sequence header). Presentation order from the index temporal + offsets (display position *n* is stored at *n* + `TemporalOffset[n]`). When the index marks B + pictures but has no temporal offsets (FFmpeg-written AVC), `needs_reorder` is set: the caller + orders by the bitstream (the AVC picture order counts). +- **Codecs.** From the picture essence coding label, then the essence container label, then the + essence bytes: AVC / AVC-Intra, VC-3, ProRes (profile from the label), MPEG-2, + MPEG-4 visual, JPEG 2000, DV, uncompressed. +- **Sound.** PCM chunks (frame- or clip-wrapped) with sample counts; `read_pcm` decodes + little-endian 8/16/24/32-bit PCM (wave / AES3 descriptors) and ST 331 AES3 elements (D-10). +- **Timecode.** The material package timecode component (start frame count, rounded base, + drop frame), falling back to the file package's; `Timecode::format` gives `HH:MM:SS:FF` / + `HH:MM:SS;FF`. + +Not supported: OP1b/OP2x+ edit lists beyond the first source clip, external essence (OP-Atom +material packages whose other tracks live in other files are opened track by track), partial or +encrypted essence (ST 429-6), and descriptive metadata (parsed sets are ignored). + +`Codec::codec_id()` and `EssenceTrack::codec_params()` give the crate-wide `CodecId` / +`CodecParams`: AVC is `H264`, VC-3 is `Dnxhd`, PCM and AES3 element data are `Pcm`; JPEG 2000, DV +and uncompressed pictures have no identifier. The size is the displayed frame, sound gets its +sample rate, channels and (for plain PCM) the little-endian `PcmFormat`. MXF essence carries its +configuration in band, so `extradata` is empty. + +Limits, each with a test: a run-in of at most 65 535 bytes before the header partition pack, a +metadata or index value of at most 64 MiB (larger is refused before it is read) and 256 MiB of +them in all, 16 MiB scanned +for the next partition pack after a lost KLV sync, an index position that cannot make a sparse +table, at most 256 sound channels (8 in an AES3 element), a PCM block alignment of at most 4096 +bytes, and a sound request of at most 2²⁴ samples past the stored essence. + +### Writing a file + +```rust +use craft_media::mxf::*; + +let ids = PackageIds::from_seed("unique seed (path + time)", "Clip name"); // material + file UMIDs +let mut cfg = WriterConfig::new(Pattern::Op1a, Rational::new(25, 1), ids); +cfg.picture = Some(PictureDesc::new(PictureCoding::Vc3 { cid: 1272 }, 1920, 1080)); +cfg.sound = vec![SoundDesc { sample_rate: 48_000, channels: 2, bits: 24 }]; +cfg.timecode = Some(StartTimecode { frames: 90_000, rate: Rational::new(25, 1), drop_frame: false }); +cfg.company = "My company".into(); // `craft-media` unless set, like `product` +let mut w = MxfWriter::new(std::io::BufWriter::new(std::fs::File::create("out.mxf")?), cfg)?; +w.push_picture(&frame_bytes, FrameInfo::intra())?; // stored order; AVC: key / P / B + display position +w.push_sound(0, &interleaved_le_pcm)?; // any chunking: content packages are cut per edit unit +w.finish()?; +``` + +- **Streaming.** Any `Write + Seek` sink. `new` writes the header partition (open, incomplete, + durations unknown) and a body partition; essence follows as it is pushed; `finish` writes the + footer partition (closed, complete header metadata with the final durations and the index table + segments), the random index pack, then rewrites the header partition pack and header metadata in + place (the metadata's size does not depend on the durations; a reserved fill item absorbs any + difference) and the body partition pack's footer offset. Only the index entries (11 bytes per + edit unit, plus 4 per sound slice) are kept in memory. +- **OP1a** (ST 378): one content package per edit unit, frame wrapping (ST 379-1): the picture + element then one element per sound track. Sound is buffered and cut into edit units exactly + (`floor((n+1)·rate·den/num) − floor(n·rate·den/num)` samples: 1601/1602 at 29.97). Pictures + without their sound yet wait; `finish` pads the last units' sound with silence. A multiple + descriptor with one sub-descriptor per track (linked track ids), the "multiple wrappings" + container label. +- **OP-Atom** (ST 390, Avid style): exactly one essence track per file, clip-wrapped (one element + with a 9-byte BER length patched by `finish`). Several atom files of one clip can share the + material package UMID with distinct track ids (`WriterConfig::first_track_id`). Sound files may + use the sample rate as the edit rate (a constant-bytes index) or the frame rate (VBR entries). +- **Index tables** (ST 377-1 §11): VBR entries per edit unit — stream offset (from the first + essence byte; clip-wrapped: from the element value), key-frame offset, flags (`0x80` random + access, `0xC0` AVC IDR with its parameter sets, `0x22` P, `0x33` B) and temporal offsets from the + display positions (`TO[d] = stored(d) − d`); a delta entry and a slice per sound element. Split + into segments of at most ~60 KB (the entry array is a 2-byte-length local set item). +- **Metadata.** Preface, identification (company / product / version / modification date), + content storage, essence container data (BodySID 1, IndexSID 2), material and file packages + (`PackageIds`: UMIDs and names) with a timecode track (start, rounded base, drop frame) and one + timeline track per essence (source clip → file package track; track numbers = element keys), + CDCI picture descriptors (size, aspect ratio, depth, subsampling, black / white / range, BT.709 / + BT.2020 PQ / HLG colour labels, coding label) and wave audio descriptors. +- **Mappings.** VC-3 (ST 2019-4: coding label `…71 cc` from the compression id, container `02 11`, + element types 0x0C / 0x0D), ProRes (RDD 44: coding label profile byte, container `02 1C`), + AVC byte stream (ST 381-3: container `02 10 60`, coding label from `profile_idc`; Annex B access + units with in-band SPS / PPS — the AVC sub-descriptor is not written), Broadcast Wave PCM + (ST 382: container `02 06 01/02`, element types 0x01 / 0x02). +- `write_opatom_pcm(&OpAtomPcm, &[i32])` builds a complete in-memory OP-Atom PCM file (AAF media + consolidation); `encode_pcm` interleaves planar f32 as little-endian PCM. + +### Differences from `filmcraft-mxf` + +- `ByteSource` is `craft_media::ByteSource`. +- `WriterConfig::new` sets `company` and `product` to `craft-media` (FilmCraft: `FilmCraft`) and + `version` to this crate's. Apps set their own; `write_opatom_pcm_as` takes them for the + in-memory OP-Atom PCM writer (`write_opatom_pcm` writes the defaults). The identification + set's product UID is derived from `" MXF writer"`, so `company` and `product` of + `FilmCraft` with FilmCraft's version string write the bytes `filmcraft-mxf` wrote. +- Everything read while opening (partition packs, primers, metadata sets, index segments) shares + a budget of 256 MiB; past it the file is refused. `filmcraft-mxf` bounded each value only. +- `EssenceTrack::sync_before` returns 0 for a track without picture samples (a sound track); it + indexed an empty table and panicked. +- `Timecode::format` saturates for a drop-frame start near `i64::MAX`; it overflowed (a panic in + a debug build). +- `Error` is `#[non_exhaustive]`; `Codec::codec_id()` and `EssenceTrack::codec_params()` are new. + +### Tests + +Synthetic OP1a files (temporal offsets, key flags, PCM, timecode), writer output read back (OP1a +with two sound tracks, 29.97 sound per edit unit, long-GOP AVC index, OP-Atom picture and PCM, +multi-segment index), truncation and mutation, and `hostile_tests.rs`: every metadata item, index +item and partition pack field set to extreme values, KLV lengths that lie, and the parsers on +arbitrary bytes. `tests/oracle_mxf.rs`: eight ffmpeg-written files (OP1a H.264 with and without B +pictures, DNxHR, ProRes, MPEG-2; OP-Atom DNxHR and PCM; D-10) compared with ffprobe's packets and +ffmpeg's decoded sound sample for sample; and files written by `MxfWriter` from the same essence, +which ffprobe must describe like their source and ffmpeg must decode to the same pictures and +sound. + +## Containers, codecs and codec parameters + +Always built, with no dependencies, so codec crates share them: + +- `Container`: the file format (`Wav`, `Aiff`, `Flac`, `Mp4`, `QuickTime`, `Matroska`, `WebM`, + `Ogg`, `Caf`, `Adts`, `MpegAudio`, `Ac3`, `Avi`, `Mxf`, `MpegTs`, `MpegPs`), with `name()`. +- `CodecId`: audio and video codecs (`Aac`, `HeAac`, `Opus`, `Eac3`, `Speex`, …, `H264`, `Hevc`, + `Av1`, `ProRes`, `Dnxhd`, `Apv`, `Theora`, …, `Unknown`), with `name()`, `is_audio()`, + `is_video()`. +- `PcmFormat`: the layout of uncompressed samples, built with `PcmFormat::int(bits, signed, + big_endian)` or `PcmFormat::float(bits, big_endian)`. +- `CodecParams`: what a decoder needs about a track, whatever its container: `codec`, + `extradata`, `tag` (the container's four-character code, such as a ProRes profile), the audio + fields `sample_rate`, `channels` and `pcm` (`PcmFormat`), and the video fields `width` and + `height`. Built with `CodecParams::new(codec)` and the `with_*` methods, or by the demuxers' + `codec_params()`, which every container returns in the same form. `extradata` follows + Matroska's `CodecPrivate`, as ffmpeg's extradata does: the `AudioSpecificConfig` for AAC, the + `OpusHead` for Opus (MP4's `dOps` is converted), Xiph-laced headers for Vorbis (`xiph_lace`, + `None` for more than 256 packets), `fLaC` + metadata blocks for FLAC, the + `avcC`/`hvcC`/`av1C`/`apvC` record for video. + +All are `#[non_exhaustive]`: new formats and fields are minor changes. + +## `ByteSource` + +`craft_media::ByteSource` (`len`, `read_at(offset, buf)`) is what every demuxer reads from. It is +always built, so a crate that uses only `bitstream` can name it too. `isobmff::ByteSource`, +`matroska::ByteSource`, `ogg::ByteSource`, `avi::ByteSource`, `mxf::ByteSource` and `mpegts::ByteSource` are the same trait. It is implemented for `[u8]`, +`Vec`, `&T`, `Arc`, `Box` and `std::fs::File` (not on wasm). `ReadSeekSource` adapts any +`Read + Seek`; it is `Send + Sync` when the reader is `Send`. Implement the trait once for a +custom source (a web `Blob`, a network range reader) to use every container with it. + +## Tests + +- Unit tests cover the bit reader and writer, the box reader (64-bit, size-0, `uuid`, truncated and + hostile sizes), hand-built `stbl` edge cases, codec configuration round trips and allocation + guards. For Matroska: EBML integers, typed values, CRC-32, every lacing mode, codec mapping, a + hand-built file (unknown-size Segment and Clusters, header stripping, BlockGroups, block + additions, color and mastering metadata, Chapters, Tags, Attachments, CRC-32, Cue-less seek, + hostile cluster timestamps) and mux-demux round trips. For Ogg (`src/ogg`): page parsing, CRC, + packets across pages, damage resync and its read budget, lost pages, chained links and stray + beginning-of-stream flags, the packet and header caps, Opus timing (end trimming, hostile granules) and the codec parameters of each codec. +- `tests/roundtrip.rs`: property tests that write random multi-track files (progressive and + fragmented) and read them back. +- `tests/oracle_demux.rs` and `tests/oracle_mux.rs` compare the demuxer and muxer with ffprobe and + ffmpeg on generated fixtures in `target/fixtures/isobmff/` (`$CRAFT_MEDIA_FIXTURES_DIR` + overrides it). Fixtures are never committed. `chapters_are_listed_by_ffprobe` checks that + `ffprobe -show_chapters` lists the chapters the muxer writes (count, starts, ends, UTF-8 titles) in + MP4 and MOV. +- `tests/oracle_matroska.rs` compares every packet (stream, size, keyframe flag, pts, duration), + codec names, time bases, dimensions and audio parameters with ffprobe on fixtures in + `target/fixtures/matroska/`: H.264+AAC, VP9+Opus WebM, FLAC, Vorbis, SRT+ASS, WebVTT WebM, Cues + at the front, a streamed file without Cues, HEVC with HDR color, ProRes+PCM, MJPEG+AC-3, AV1. + Seeks must land on the latest keyframe at or before the target. The muxer's laced output is read + back by ffprobe. A damaged file must resync. +- `tests/fuzz.rs` and `tests/fuzz_matroska.rs`: deterministic mutation fuzzing; nothing may panic. + `fuzz.rs` also walks every box of a mutated file as a container and checks that each payload + range stays inside its parent. + +ffmpeg and ffprobe are test oracles only, never linked. The helpers are in `craft-media-testkit` +(an unpublished crate, shared with craft-audio and the video crate to come). They are looked up in +`$CRAFT_MEDIA_FFMPEG` / `$CRAFT_MEDIA_FFPROBE`, then `PATH`, then common install directories. When +a tool is missing, the oracle tests print `SKIPPED` and pass; `CRAFT_MEDIA_REQUIRE_ORACLES=1` turns +a skip into a failure. CI (`.github/workflows/media.yml`) sets it and installs Ubuntu's ffmpeg. +craft-audio's oracle tests use the same variables. Generate every fixture ahead of time with +`cargo test -p craft-media --all-features -- --ignored generate_fixtures`. diff --git a/crates/media/src/avi/mod.rs b/crates/media/src/avi/mod.rs new file mode 100644 index 000000000..592139cef --- /dev/null +++ b/crates/media/src/avi/mod.rs @@ -0,0 +1,745 @@ +//! Clean-room AVI demuxer, written from Microsoft's published AVI RIFF file reference and the +//! OpenDML AVI File Format Extensions 1.02. +//! +//! [`open`] reads the `hdrl` header list (`avih`, and per stream `strh` / `strf` / `strn` / +//! `indx`) of the first `RIFF AVI ` and builds a per-stream table of [`Chunk`]s from the best index +//! the file has: the OpenDML super index (`indx` → `ix##` standard indexes, which also cover the +//! `RIFF AVIX` extensions of files past 1 GB), else the AVI 1.0 `idx1` (plus a scan of any `AVIX` +//! extension it cannot see), else a scan of the `movi` lists. Frame data is read on demand with +//! [`AviFile::read_chunk`]. Truncated files (a recording cut off) open with what is there. +//! +//! Every size and count comes from the file and is treated as hostile: reads are bounded by the +//! file length, tables by the number of chunks the file could hold, and nesting by a fixed depth. +//! +//! No dependencies beyond `std`, no `unsafe`, builds for `wasm32-unknown-unknown`. +//! +//! From FilmCraft's `filmcraft-avi` (storytold/filmcraft@4bec22b). Public items keep their names. +//! `ByteSource` is the crate's one source trait, and [`Error::Io`] holds the `io::Error`. + +#![warn(missing_docs)] + +#[cfg(test)] +mod tests; + +pub use crate::source::{ByteSource, ReadSeekSource}; + +use std::collections::HashSet; +use std::io; + +/// Errors from reading an AVI file. +#[non_exhaustive] +#[derive(Debug)] +pub enum Error { + /// Not an AVI file (no `RIFF` … `AVI ` header). + NotAvi, + /// A read failed. + Io(io::Error), + /// Structurally invalid data. + Invalid(String), +} + +impl std::fmt::Display for Error { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + Error::NotAvi => f.write_str("not an AVI file"), + Error::Io(e) => write!(f, "I/O error: {e}"), + Error::Invalid(e) => write!(f, "invalid AVI: {e}"), + } + } +} + +impl std::error::Error for Error { + fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { + match self { + Error::Io(e) => Some(e), + _ => None, + } + } +} + +impl From for Error { + fn from(e: io::Error) -> Self { + Error::Io(e) + } +} + +/// Result alias for this module. +pub type Result = std::result::Result; + +/// Whether `head` starts like an AVI file: `RIFF`, a size, `AVI `. +pub fn sniff(head: &[u8]) -> bool { + head.get(..4) == Some(b"RIFF") && head.get(8..12) == Some(b"AVI ") +} + +/// `avih`: the main header (frame period, flags, frame count, size). +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct MainHeader { + /// `dwMicroSecPerFrame`: the frame period in microseconds. + pub micro_sec_per_frame: u32, + /// `dwFlags` (`AVIF_HASINDEX` 0x10, `AVIF_ISINTERLEAVED` 0x100…). + pub flags: u32, + /// `dwTotalFrames` (of the first RIFF only in an OpenDML file). + pub total_frames: u32, + /// `dwStreams`: the stream count the header declares. + pub streams: u32, + /// Picture width in pixels. + pub width: u32, + /// Picture height in pixels. + pub height: u32, +} + +/// What a stream carries (`fccType` of its `strh`). +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum StreamKind { + /// `vids`. + Video, + /// `auds`. + Audio, + /// Text, MIDI or anything else (`fccType`). + Other([u8; 4]), +} + +/// `strf` of a video stream: a `BITMAPINFOHEADER`. +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct BitmapInfo { + /// `biWidth` in pixels. + pub width: i32, + /// Positive: rows stored bottom-up (uncompressed RGB); negative: top-down. + pub height: i32, + /// `biBitCount`: bits per pixel. + pub bit_count: u16, + /// `biCompression` as four bytes: a FourCC (`MJPG`, `H264`, `YUY2`…) or 0 / 3 (`BI_RGB`, + /// `BI_BITFIELDS`) in little-endian. + pub compression: [u8; 4], + /// `biSizeImage`: bytes of one uncompressed picture, often 0. + pub size_image: u32, + /// Bytes after the 40-byte header (codec setup, palette). + pub extra: Vec, +} + +impl BitmapInfo { + /// Uncompressed RGB (`BI_RGB` / `BI_BITFIELDS`). + pub fn is_rgb(&self) -> bool { + matches!(u32::from_le_bytes(self.compression), 0 | 3) + } +} + +/// `strf` of an audio stream: a `WAVEFORMATEX` (`WAVEFORMATEXTENSIBLE` is resolved to its sub-format). +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct WaveFormat { + /// 1 PCM, 3 IEEE float, 0x50 MPEG audio, 0x55 MP3, 0x2000 AC-3, 0xFF AAC… + pub format_tag: u16, + /// `nChannels`. + pub channels: u16, + /// `nSamplesPerSec`. + pub sample_rate: u32, + /// `nAvgBytesPerSec`. + pub avg_bytes_per_sec: u32, + /// `nBlockAlign`: bytes per sample frame for PCM. + pub block_align: u16, + /// `wBitsPerSample`. + pub bits_per_sample: u16, + /// `cbSize` bytes after the 18-byte header. + pub extra: Vec, +} + +/// One stored frame or audio chunk. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] +pub struct Chunk { + /// Offset of the data (after the 8-byte chunk header). + pub offset: u64, + /// Bytes of data. + pub size: u32, + /// A key frame (always true for audio and when the index does not say). + pub key: bool, +} + +/// Where the chunk tables came from. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum IndexSource { + /// OpenDML `indx` super index and `ix##` standard indexes. + OpenDml, + /// The AVI 1.0 `idx1` (plus a scan of the `AVIX` extensions). + Idx1, + /// No usable index: the `movi` lists were scanned (key frames unknown). + Scan, +} + +/// One stream: its `strl` headers and its chunk table. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Stream { + /// What the stream carries. + pub kind: StreamKind, + /// `fccHandler`. + pub handler: [u8; 4], + /// Time base: `rate / scale` units per second (frames per second for video). + pub scale: u32, + /// See `scale`. + pub rate: u32, + /// Start time in `scale / rate` units. + pub start: u32, + /// Length in `scale / rate` units. + pub length: u32, + /// Bytes per sample for fixed-size samples (PCM block align), 0 when samples vary. + pub sample_size: u32, + /// `strf` of a video stream. + pub video: Option, + /// `strf` of an audio stream. + pub audio: Option, + /// `strn`. + pub name: Option, + /// The stored frames or audio chunks, in file order. + pub chunks: Vec, + /// Whether [`Chunk::key`] comes from an index (a scan cannot tell). + pub keyframes_known: bool, + /// The OpenDML super index entries (offsets of the `ix##` chunks). + super_index: Vec, +} + +/// How the NAL units of an H.264 or HEVC stream are framed ([`Stream::nal_framing`]). +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum NalFraming { + /// Start codes (Annex B). With `header_sets`, the bytes after the format header are parameter + /// sets in Annex B, which a decoder needs before the first chunk: the chunks need not repeat + /// them. + AnnexB { + /// The stream header carries parameter sets. + header_sets: bool, + }, + /// Length prefixes of this many bytes (1 to 4): the bytes after the format header are an + /// `avcC` / `hvcC` record, as in a stream copied from MP4 as it is. + LengthPrefixed(usize), +} + +impl Stream { + /// How the chunks of an H.264 or HEVC stream frame their NAL units, from the bytes after the + /// format header (`BitmapInfo::extra`); `None` for any other stream. A record (first byte 1) + /// gives the length-prefix size it declares, start codes mean parameter sets in Annex B, and + /// anything else leaves the stream as Annex B with its sets in band. + pub fn nal_framing(&self) -> Option { + let extra = &self.video.as_ref()?.extra; + // lengthSizeMinusOne: byte 4 of an avcC record, byte 21 of an hvcC record + let size_at = match self.codec_params().codec { + crate::CodecId::H264 => 4, + crate::CodecId::Hevc => 21, + _ => return None, + }; + Some(if extra.first() == Some(&1) { + NalFraming::LengthPrefixed(extra.get(size_at).map_or(4, |b| usize::from(b & 3) + 1)) + } else { + NalFraming::AnnexB { header_sets: extra.starts_with(&[0, 0, 1]) || extra.starts_with(&[0, 0, 0, 1]) } + }) + } + + /// What a decoder needs for this stream, in the container-neutral form the codec crates take. + /// + /// The codec comes from `biCompression` (video) or the format tag (audio). `tag` is the video + /// FourCC as stored. `extradata` is the bytes after the format header as stored. For H.264 + /// and HEVC that is one of three things, which [`Stream::nal_framing`] tells apart: nothing + /// (the parameter sets are in the chunks), Annex B parameter sets (a file written with global + /// headers), or an `avcC` / `hvcC` record (a stream copied from MP4, whose chunks are then + /// length-prefixed). Uncompressed video is [`CodecId::Unknown`] + /// with its FourCC (or `BI_RGB` / `BI_BITFIELDS`) in `tag`; see [`BitmapInfo`] for its layout. + /// + /// [`CodecId::Unknown`]: crate::CodecId::Unknown + pub fn codec_params(&self) -> crate::CodecParams { + use crate::CodecId as Id; + if let Some(b) = &self.video { + let mut f = b.compression; + f.make_ascii_uppercase(); + let id = match &f { + b"MJPG" | b"AVRN" | b"LJPG" | b"JPGL" | b"DMB1" | b"JPEG" | b"MJPA" => Id::Mjpeg, + b"H264" | b"X264" | b"AVC1" | b"DAVC" | b"VSSH" => Id::H264, + b"HEVC" | b"H265" | b"HEV1" | b"HVC1" | b"X265" => Id::Hevc, + b"DIVX" | b"DX50" | b"XVID" | b"FMP4" | b"MP4V" | b"M4S2" | b"3IV2" => Id::Mpeg4Video, + b"MPG2" | b"MPEG" | b"MPG1" => Id::Mpeg2Video, + b"VP80" => Id::Vp8, + b"VP90" => Id::Vp9, + b"AV01" => Id::Av1, + [b'A', b'P', b'C' | b'4', _] => Id::ProRes, + b"AVDN" | b"AVDH" => Id::Dnxhd, + _ => Id::Unknown, + }; + return crate::CodecParams::new(id) + .with_tag(b.compression) + .with_extradata(b.extra.clone()) + .with_size(b.width.unsigned_abs(), b.height.unsigned_abs()); + } + let Some(w) = &self.audio else { return crate::CodecParams::new(Id::Unknown) }; + let bits = w.bits_per_sample; + let (id, pcm) = match w.format_tag { + // 8-bit PCM is unsigned, as in WAV + 1 => (Id::Pcm, Some(crate::PcmFormat::int(bits, bits > 8, false))), + 3 => (Id::Pcm, Some(crate::PcmFormat::float(bits, false))), + 2 | 0x11 => (Id::Adpcm, None), + 6 => (Id::ALaw, None), + 7 => (Id::MuLaw, None), + 0x50 => (Id::Mp2, None), + 0x55 => (Id::Mp3, None), + 0xFF | 0x1610 => (Id::Aac, None), + 0x2000 => (Id::Ac3, None), + 0x566F | 0x6750 | 0x6751 => (Id::Vorbis, None), + 0xF1AC => (Id::Flac, None), + _ => (Id::Unknown, None), + }; + let mut p = crate::CodecParams::new(id).with_extradata(w.extra.clone()).with_sample_rate(w.sample_rate).with_channels(w.channels); + p.pcm = pcm; + p + } + + /// Stream index of a `movi` chunk id (`00dc`, `01wb`…): its first two characters. + fn number(id: &[u8; 4]) -> Option { + // ffmpeg-style writers number streams in decimal ("10dc" = 10), Video for Windows in hex + // ("0adc" = 10): a hex letter means hex, two decimal digits mean decimal + let [a, b, ..] = *id; + let radix = if [a, b].iter().any(|c| matches!(c, b'a'..=b'f' | b'A'..=b'F')) { 16 } else { 10 }; + let d = |c: u8| (c as char).to_digit(radix).map(|v| v as usize); + Some(d(a)? * radix as usize + d(b)?) + } +} + +/// An opened AVI file: headers and per-stream chunk tables. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct AviFile { + /// `avih`. + pub header: MainHeader, + /// The streams, in `strl` order (at most 64). + pub streams: Vec, + /// Which index the chunk tables came from. + pub index: IndexSource, +} + +/// Options for [`open_with`] (tests reach the fallback indexes with them). +#[derive(Clone, Copy, Debug, Default)] +pub struct OpenOptions { + /// Do not use the OpenDML index. + pub ignore_odml: bool, + /// Do not use `idx1`. + pub ignore_idx1: bool, +} + +/// Headers larger than this are refused (a real `hdrl` is a few kilobytes). +const MAX_HEADER: u64 = 16 << 20; +/// Total OpenDML standard-index bytes accepted while opening one file. This bounds hostile +/// repeated index references without constraining practical large-file indexes. +const MAX_ODML_INDEX_BYTES: u64 = 64 << 20; +/// Streams beyond this are ignored. +const MAX_STREAMS: usize = 64; +/// `LIST rec ` inside `movi` nests once; deeper is refused. +const MAX_DEPTH: u32 = 3; + +fn read(src: &S, at: u64, n: u64) -> Result> { + let end = at.checked_add(n).filter(|e| *e <= src.len()).ok_or_else(|| Error::Invalid(format!("{n} bytes at {at} run past the end")))?; + let len = usize::try_from(end - at).map_err(|_| Error::Invalid("chunk too large".into()))?; + let mut buf = vec![0; len]; + src.read_at(at, &mut buf)?; + Ok(buf) +} + +fn fourcc(b: &[u8], at: usize) -> [u8; 4] { + let mut f = [0; 4]; + if let Some(s) = b.get(at..at + 4) { + f.copy_from_slice(s); + } + f +} + +fn le16(b: &[u8], at: usize) -> u16 { + b.get(at..at + 2).map_or(0, |s| u16::from_le_bytes([s[0], s[1]])) +} + +fn le32(b: &[u8], at: usize) -> u32 { + b.get(at..at + 4).map_or(0, |s| u32::from_le_bytes([s[0], s[1], s[2], s[3]])) +} + +fn le64(b: &[u8], at: usize) -> u64 { + u64::from(le32(b, at)) | (u64::from(le32(b, at + 4)) << 32) +} + +/// A chunk header at `at`: (id, size, data offset). The size is clamped to the file (a truncated +/// recording keeps what is there). +fn header_at(src: &S, at: u64) -> Result<([u8; 4], u64, u64)> { + let h = read(src, at, 8)?; + let data = at + 8; + let size = u64::from(le32(&h, 4)).min(src.len().saturating_sub(data)); + Ok((fourcc(&h, 0), size, data)) +} + +/// Iterate the chunks of `[from, to)`: (id, size, data offset). Stops at the first unreadable +/// header; every step moves forward, so it ends. A child's size is clamped to its parent's end, +/// so lists never reach past their container: overlapping `movi` or `rec ` lists would otherwise +/// each scan (and record) the same physical chunks again. +fn children(src: &S, from: u64, to: u64) -> Vec<([u8; 4], u64, u64)> { + let mut out = Vec::new(); + let mut at = from; + while at.checked_add(8).is_some_and(|e| e <= to) { + let Ok((id, size, data)) = header_at(src, at) else { break }; + let size = size.min(to.saturating_sub(data)); + out.push((id, size, data)); + // chunks are padded to an even size + let Some(next) = data.checked_add(size).and_then(|e| e.checked_add(size & 1)) else { break }; + if next <= at { + break; + } + at = next; + } + out +} + +/// Open an AVI file. +pub fn open(src: &S) -> Result { + open_with(src, OpenOptions::default()) +} + +/// Open an AVI file, skipping the indexes `opts` names. +pub fn open_with(src: &S, opts: OpenOptions) -> Result { + let head = read(src, 0, 12.min(src.len())).map_err(|_| Error::NotAvi)?; + if !sniff(&head) { + return Err(Error::NotAvi); + } + // the RIFF forms: the first `AVI `, then any `AVIX` extensions (OpenDML) + let mut hdrl = None; + let mut movis: Vec<(u64, u64, u64)> = Vec::new(); // (position of the `movi` id, data start, data end) + let mut idx1 = None; + for (id, size, data) in children(src, 0, src.len()) { + if id != *b"RIFF" || size < 4 { + continue; + } + let end = data + size; + let form = fourcc(&read(src, data, 4)?, 0); + if form != *b"AVI " && form != *b"AVIX" { + continue; + } + for (cid, csize, cdata) in children(src, data + 4, end) { + match &cid { + b"LIST" if csize >= 4 => { + let ltype = fourcc(&read(src, cdata, 4)?, 0); + if ltype == *b"hdrl" && hdrl.is_none() && form == *b"AVI " { + hdrl = Some((cdata + 4, cdata + csize)); + } else if ltype == *b"movi" { + movis.push((cdata, cdata + 4, cdata + csize)); + } + } + b"idx1" if form == *b"AVI " => idx1 = Some((cdata, csize)), + _ => {} + } + } + } + let (hfrom, hto) = hdrl.ok_or_else(|| Error::Invalid("no hdrl header list".into()))?; + if hto - hfrom > MAX_HEADER { + return Err(Error::Invalid("header list too large".into())); + } + let (header, mut streams) = parse_hdrl(src, hfrom, hto)?; + if streams.is_empty() { + return Err(Error::Invalid("no streams".into())); + } + // chunk tables from the best index + let odml = !opts.ignore_odml && streams.iter().any(|s| !s.super_index.is_empty()); + let index = if odml && read_odml(src, &mut streams) { + IndexSource::OpenDml + } else if let (false, Some((at, size)), Some(first)) = (opts.ignore_idx1, idx1, movis.first()) { + clear(&mut streams); + read_idx1(src, &mut streams, at, size, first.0); + if streams.iter().all(|s| s.chunks.is_empty()) { + scan_all(src, &mut streams, &movis) + } else { + scan_missing(src, &mut streams, first); + // idx1 only covers the first RIFF: the AVIX extensions are scanned + for &(_, from, to) in movis.iter().skip(1) { + scan(src, &mut streams, &|_| true, from, to, 0); + } + IndexSource::Idx1 + } + } else { + scan_all(src, &mut streams, &movis) + }; + Ok(AviFile { header, streams, index }) +} + +/// A stream that declares data (`length`) but that `idx1` left without a single chunk while +/// others have theirs (its entries damaged or missing) gets its chunks from a scan of the first +/// `movi` list (the one `idx1` covers), as a file without an index does, before the AVIX +/// extensions add theirs; its key frames are then unknown. The indexed streams keep their +/// tables, and a stream that declares no data is not looked for. +fn scan_missing(src: &S, streams: &mut [Stream], &(_, from, to): &(u64, u64, u64)) { + let missing: Vec = streams.iter().map(|s| s.chunks.is_empty() && s.length > 0).collect(); + if !missing.contains(&true) { + return; + } + scan(src, streams, &|n| missing.get(n) == Some(&true), from, to, 0); + for (s, _) in streams.iter_mut().zip(&missing).filter(|(_, m)| **m) { + s.keyframes_known = false; + } +} + +fn clear(streams: &mut [Stream]) { + for s in streams.iter_mut() { + s.chunks.clear(); + s.keyframes_known = true; + } +} + +fn scan_all(src: &S, streams: &mut [Stream], movis: &[(u64, u64, u64)]) -> IndexSource { + clear(streams); + for &(_, from, to) in movis { + scan(src, streams, &|_| true, from, to, 0); + } + for s in streams.iter_mut() { + s.keyframes_known = false; + } + IndexSource::Scan +} + +fn parse_hdrl(src: &S, from: u64, to: u64) -> Result<(MainHeader, Vec)> { + let mut header = MainHeader::default(); + let mut streams = Vec::new(); + for (id, size, data) in children(src, from, to) { + match &id { + b"avih" => { + let b = read(src, data, size.min(64))?; + header = MainHeader { + micro_sec_per_frame: le32(&b, 0), + flags: le32(&b, 12), + total_frames: le32(&b, 16), + streams: le32(&b, 24), + width: le32(&b, 32), + height: le32(&b, 36), + }; + } + b"LIST" if size >= 4 && streams.len() < MAX_STREAMS && fourcc(&read(src, data, 4)?, 0) == *b"strl" => { + streams.push(parse_strl(src, data + 4, data + size)?); + } + _ => {} + } + } + Ok((header, streams)) +} + +fn parse_strl(src: &S, from: u64, to: u64) -> Result { + let mut s = Stream { + kind: StreamKind::Other([0; 4]), + handler: [0; 4], + scale: 1, + rate: 1, + start: 0, + length: 0, + sample_size: 0, + video: None, + audio: None, + name: None, + chunks: Vec::new(), + keyframes_known: true, + super_index: Vec::new(), + }; + let mut strf = None; + for (id, size, data) in children(src, from, to) { + match &id { + b"strh" => { + let b = read(src, data, size.min(64))?; + s.kind = match &fourcc(&b, 0) { + b"vids" => StreamKind::Video, + b"auds" => StreamKind::Audio, + other => StreamKind::Other(*other), + }; + s.handler = fourcc(&b, 4); + s.scale = le32(&b, 20); + s.rate = le32(&b, 24); + s.start = le32(&b, 28); + s.length = le32(&b, 32); + s.sample_size = le32(&b, 44); + } + b"strf" => strf = Some(read(src, data, size.min(1 << 20))?), + b"strn" => { + let b = read(src, data, size.min(4096))?; + let name = String::from_utf8_lossy(b.split(|&c| c == 0).next().unwrap_or_default()).trim().to_string(); + s.name = (!name.is_empty()).then_some(name); + } + b"indx" => s.super_index = super_index(&read(src, data, size.min(MAX_HEADER))?), + _ => {} + } + } + if let Some(b) = strf { + match s.kind { + StreamKind::Video => { + s.video = Some(BitmapInfo { + width: le32(&b, 4) as i32, + height: le32(&b, 8) as i32, + bit_count: le16(&b, 14), + compression: fourcc(&b, 16), + size_image: le32(&b, 20), + extra: b.get(40.min(b.len())..).unwrap_or_default().to_vec(), + }); + } + StreamKind::Audio => { + let cb = usize::from(le16(&b, 16)); + let extra = b.get(18.min(b.len())..(18 + cb).min(b.len())).unwrap_or_default().to_vec(); + let mut tag = le16(&b, 0); + // WAVE_FORMAT_EXTENSIBLE: the sub-format GUID starts with the real tag + if tag == 0xFFFE && extra.len() >= 22 { + tag = le16(&extra, 6); + } + s.audio = Some(WaveFormat { + format_tag: tag, + channels: le16(&b, 2), + sample_rate: le32(&b, 4), + avg_bytes_per_sec: le32(&b, 8), + block_align: le16(&b, 12), + bits_per_sample: le16(&b, 14), + extra, + }); + } + StreamKind::Other(_) => {} + } + } + if s.scale == 0 || s.rate == 0 { + (s.scale, s.rate) = (1, 1); + } + Ok(s) +} + +/// The `ix##` chunk offsets of an `indx` super index (`AVI_INDEX_OF_INDEXES`, 4 longs per entry). +fn super_index(b: &[u8]) -> Vec { + let longs = usize::from(le16(b, 0)); + let (subtype, itype, n) = (b.get(2).copied().unwrap_or(0), b.get(3).copied().unwrap_or(0xFF), le32(b, 4) as usize); + if itype != 0 || subtype != 0 || longs != 4 { + return Vec::new(); + } + // header 24 bytes, entries of 16: qwOffset, dwSize, dwDuration + let n = n.min(b.len().saturating_sub(24) / 16); + (0..n).map(|k| le64(b, 24 + k * 16)).filter(|&o| o > 0).collect() +} + +/// Fill the chunk tables from the OpenDML standard indexes; false (tables cleared) when a stream +/// that has data lacks one or none could be read. +fn read_odml(src: &S, streams: &mut [Stream]) -> bool { + let entry_limit = src.len() / 8; + let mut entries = 0u64; + let mut index_bytes = 0u64; + let mut seen = HashSet::new(); + for s in streams.iter_mut() { + s.chunks.clear(); + s.keyframes_known = true; + for &at in &s.super_index { + // A super index can repeat an offset (even across streams). Read and process a + // standard index once, rather than multiplying its work and allocations. + if !seen.insert(at) { + continue; + } + let Ok((id, size, data)) = header_at(src, at) else { continue }; + if &id[..2] != b"ix" { + continue; + } + // Validate the fixed header before allocating the variable entry body. + if size < 24 || index_bytes.checked_add(24).is_none_or(|n| n > MAX_ODML_INDEX_BYTES) { + return false; + } + let Ok(header) = read(src, data, 24) else { continue }; + index_bytes += 24; + let (longs, subtype, itype) = (usize::from(le16(&header, 0)), header.get(2).copied().unwrap_or(0), header.get(3).copied().unwrap_or(0)); + // AVI_INDEX_OF_CHUNKS; 2 longs per entry, or 3 for the field index (AVI_INDEX_2FIELD) + if itype != 1 || !(longs == 2 && subtype == 0 || longs == 3 && subtype == 1) { + continue; + } + let step = longs * 4; + let n = u64::from(le32(&header, 4)).min(size.saturating_sub(24) / step as u64); + let body = n.saturating_mul(step as u64); + let Some(next_bytes) = index_bytes.checked_add(body) else { return false }; + let Some(next_entries) = entries.checked_add(n) else { return false }; + if next_bytes > MAX_ODML_INDEX_BYTES || next_entries > entry_limit { + return false; + } + let Ok(b) = read(src, data, 24 + body) else { continue }; + index_bytes = next_bytes; + entries = next_entries; + let base = le64(&b, 12); + let n = usize::try_from(n).unwrap_or(0); + for k in 0..n { + let e = 24 + k * step; + let (off, raw) = (u64::from(le32(&b, e)), le32(&b, e + 4)); + let size = raw & 0x7FFF_FFFF; + let Some(offset) = base.checked_add(off).filter(|o| o.checked_add(u64::from(size)).is_some_and(|end| end <= src.len())) else { + continue; + }; + s.chunks.push(Chunk { offset, size, key: raw & 0x8000_0000 == 0 }); + } + } + } + let ok = + streams.iter().any(|s| !s.chunks.is_empty()) && streams.iter().all(|s| !s.super_index.is_empty() || matches!(s.kind, StreamKind::Other(_))); + if !ok { + clear(streams); + } + ok +} + +/// Fill the chunk tables from `idx1` (16-byte entries: id, flags, offset, size). Offsets are +/// relative to the `movi` list's type id, or (some writers) absolute: the first entry decides. +fn read_idx1(src: &S, streams: &mut [Stream], at: u64, size: u64, movi: u64) { + let Ok(b) = read(src, at, size.min(src.len() / 2)) else { return }; + let entries: Vec<&[u8]> = b.as_chunks::<16>().0.iter().map(|e| e.as_slice()).collect(); + let id_at = |pos: u64| read(src, pos, 4).ok().map(|v| fourcc(&v, 0)); + let first = entries.iter().find(|e| le32(e, 4) & 1 == 0); + let relative = match first { + Some(e) => { + let (id, off) = (fourcc(e, 0), u64::from(le32(e, 8))); + id_at(movi + off) == Some(id) || id_at(off) != Some(id) + } + None => true, + }; + let base = if relative { movi } else { 0 }; + for e in entries { + let (id, flags, off, len) = (fourcc(e, 0), le32(e, 4), u64::from(le32(e, 8)), le32(e, 12)); + // AVIIF_LIST entries (`rec ` lists) and palette changes carry no samples + if flags & 1 != 0 || &id[2..] == b"pc" { + continue; + } + let Some(s) = Stream::number(&id).and_then(|n| streams.get_mut(n)) else { continue }; + let Some(offset) = + base.checked_add(off).and_then(|o| o.checked_add(8)).filter(|o| o.checked_add(u64::from(len)).is_some_and(|end| end <= src.len())) + else { + continue; + }; + s.chunks.push(Chunk { offset, size: len, key: flags & 0x10 != 0 || s.kind != StreamKind::Video }); + } +} + +/// Append the data chunks of a `movi` list (`[from, to)`) to the tables of the streams `want` +/// picks, in file order. +fn scan(src: &S, streams: &mut [Stream], want: &dyn Fn(usize) -> bool, from: u64, to: u64, depth: u32) { + if depth >= MAX_DEPTH { + return; + } + for (id, size, data) in children(src, from, to) { + if id == *b"LIST" { + if size >= 4 { + scan(src, streams, want, data + 4, data + size, depth + 1); + } + continue; + } + if &id[..2] == b"ix" || &id[2..] == b"pc" { + continue; + } + if let Some(s) = Stream::number(&id).filter(|&n| want(n)).and_then(|n| streams.get_mut(n)) { + s.chunks.push(Chunk { offset: data, size: u32::try_from(size).unwrap_or(u32::MAX), key: true }); + } + } +} + +impl AviFile { + /// The bytes of chunk `i` of stream `stream`. + pub fn read_chunk(&self, src: &S, stream: usize, i: usize) -> Result> { + let c = self.streams.get(stream).and_then(|s| s.chunks.get(i)).ok_or_else(|| Error::Invalid(format!("no chunk {i} in stream {stream}")))?; + read(src, c.offset, u64::from(c.size)) + } + + /// `len` bytes of chunk `i` of stream `stream`, from `off` bytes into it (only those bytes are read). + pub fn read_chunk_range(&self, src: &S, stream: usize, i: usize, off: usize, len: usize) -> Result> { + let c = self.streams.get(stream).and_then(|s| s.chunks.get(i)).ok_or_else(|| Error::Invalid(format!("no chunk {i} in stream {stream}")))?; + let end = off + .checked_add(len) + .filter(|&e| e as u64 <= u64::from(c.size)) + .ok_or_else(|| Error::Invalid(format!("range outside chunk {i} of stream {stream}")))?; + let at = c.offset.checked_add(off as u64).ok_or_else(|| Error::Invalid(format!("chunk {i} offset overflows")))?; + read(src, at, (end - off) as u64) + } +} diff --git a/crates/media/src/avi/tests.rs b/crates/media/src/avi/tests.rs new file mode 100644 index 000000000..2edac310b --- /dev/null +++ b/crates/media/src/avi/tests.rs @@ -0,0 +1,666 @@ +use super::*; + +mod hostile; + +#[test] +fn stream_number_supports_decimal_and_hex_ids() { + assert_eq!(Stream::number(b"10dc"), Some(10)); + assert_eq!(Stream::number(b"0adc"), Some(10)); + assert_eq!(Stream::number(b"00dc"), Some(0)); + assert_eq!(Stream::number(b"09wb"), Some(9)); + assert_eq!(Stream::number(b"0Fdc"), Some(15)); + // `from_str_radix` would take a sign; a chunk id never has one + assert_eq!(Stream::number(b"+1dc"), None); + assert_eq!(Stream::number(b"ixdc"), None); +} + +fn chunk(id: &[u8; 4], data: &[u8]) -> Vec { + let mut v = id.to_vec(); + v.extend_from_slice(&(data.len() as u32).to_le_bytes()); + v.extend_from_slice(data); + if data.len() % 2 == 1 { + v.push(0); + } + v +} + +fn list(ltype: &[u8; 4], body: &[u8]) -> Vec { + let mut d = ltype.to_vec(); + d.extend_from_slice(body); + chunk(b"LIST", &d) +} + +fn strl(video: bool) -> Vec { + let mut strh = vec![0u8; 56]; + strh[..4].copy_from_slice(if video { b"vids" } else { b"auds" }); + strh[4..8].copy_from_slice(if video { b"MJPG" } else { &[0; 4] }); + let (scale, rate, ss) = if video { (1u32, 25u32, 0u32) } else { (4, 192_000, 4) }; + strh[20..24].copy_from_slice(&scale.to_le_bytes()); + strh[24..28].copy_from_slice(&rate.to_le_bytes()); + // declared length: 3 frames, 6 audio blocks + strh[32..36].copy_from_slice(&(if video { 3u32 } else { 6 }).to_le_bytes()); + strh[44..48].copy_from_slice(&ss.to_le_bytes()); + let strf = if video { + let mut b = vec![0u8; 40]; + b[..4].copy_from_slice(&40u32.to_le_bytes()); + b[4..8].copy_from_slice(&64i32.to_le_bytes()); + b[8..12].copy_from_slice(&48i32.to_le_bytes()); + b[14..16].copy_from_slice(&24u16.to_le_bytes()); + b[16..20].copy_from_slice(b"MJPG"); + b + } else { + let mut b = vec![0u8; 18]; + b[..2].copy_from_slice(&1u16.to_le_bytes()); + b[2..4].copy_from_slice(&2u16.to_le_bytes()); + b[4..8].copy_from_slice(&48_000u32.to_le_bytes()); + b[8..12].copy_from_slice(&192_000u32.to_le_bytes()); + b[12..14].copy_from_slice(&4u16.to_le_bytes()); + b[14..16].copy_from_slice(&16u16.to_le_bytes()); + b + }; + let mut body = chunk(b"strh", &strh); + body.extend(chunk(b"strf", &strf)); + body.extend(chunk(b"strn", if video { b"Camera\0" } else { b"Mic\0" })); + list(b"strl", &body) +} + +/// A small AVI: 3 video frames (the second a delta, the third odd-sized) and 2 audio chunks, +/// optionally inside a `rec ` list, with an `idx1` whose offsets are relative to `movi` or absolute. +fn avi(idx1: bool, absolute: bool, rec: bool) -> Vec { + let mut avih = vec![0u8; 56]; + avih[0..4].copy_from_slice(&40_000u32.to_le_bytes()); + avih[12..16].copy_from_slice(&0x10u32.to_le_bytes()); + avih[16..20].copy_from_slice(&3u32.to_le_bytes()); + avih[24..28].copy_from_slice(&2u32.to_le_bytes()); + avih[32..36].copy_from_slice(&64u32.to_le_bytes()); + avih[36..40].copy_from_slice(&48u32.to_le_bytes()); + let mut hdrl = chunk(b"avih", &avih); + hdrl.extend(strl(true)); + hdrl.extend(strl(false)); + let hdrl = list(b"hdrl", &hdrl); + let samples: [(&[u8; 4], Vec, bool); 5] = [ + (b"00dc", vec![1; 10], true), + (b"01wb", vec![2; 16], true), + (b"00dc", vec![3; 6], false), + (b"01wb", vec![4; 8], true), + (b"00dc", vec![5; 7], true), + ]; + let mut body = Vec::new(); + let mut entries = Vec::new(); + for (id, data, key) in &samples { + entries.push((**id, body.len() as u32 + 4, data.len() as u32, *key)); + body.extend(chunk(id, data)); + } + let movi_body = if rec { + let r = list(b"rec ", &body); + // the samples moved 12 bytes in (the rec list's header and type) + for e in &mut entries { + e.1 += 12; + } + r + } else { + body + }; + let movi = list(b"movi", &movi_body); + let mut riff = b"AVI ".to_vec(); + riff.extend(hdrl); + // position of the `movi` type id: after `RIFF` , what `riff` holds so far, `LIST` + let movi_at = (8 + riff.len() + 8) as u32; + riff.extend(movi); + if idx1 { + let mut ix = Vec::new(); + for (id, off, len, key) in entries { + ix.extend_from_slice(&id); + ix.extend_from_slice(&(if key { 0x10u32 } else { 0 }).to_le_bytes()); + ix.extend_from_slice(&(if absolute { off + movi_at } else { off }).to_le_bytes()); + ix.extend_from_slice(&len.to_le_bytes()); + } + riff.extend(chunk(b"idx1", &ix)); + } + chunk(b"RIFF", &riff) +} + +fn table(f: &AviFile, s: usize) -> Vec<(u32, bool)> { + f.streams[s].chunks.iter().map(|c| (c.size, c.key)).collect() +} + +#[test] +fn headers_and_every_index_path_agree() { + for (idx1, absolute, rec, want) in [ + (true, false, false, IndexSource::Idx1), + (true, true, false, IndexSource::Idx1), + (true, false, true, IndexSource::Idx1), + (false, false, false, IndexSource::Scan), + (false, false, true, IndexSource::Scan), + ] { + let file = avi(idx1, absolute, rec); + let f = open(&file).unwrap(); + let what = format!("idx1 {idx1} absolute {absolute} rec {rec}"); + assert_eq!(f.index, want, "{what}"); + assert_eq!((f.header.width, f.header.height, f.header.total_frames, f.header.micro_sec_per_frame), (64, 48, 3, 40_000)); + let (v, a) = (&f.streams[0], &f.streams[1]); + assert_eq!((v.kind, v.handler, v.scale, v.rate, v.name.as_deref()), (StreamKind::Video, *b"MJPG", 1, 25, Some("Camera"))); + assert_eq!(v.video.as_ref().map(|b| (b.width, b.height, b.bit_count, b.compression)), Some((64, 48, 24, *b"MJPG"))); + let w = a.audio.as_ref().unwrap(); + assert_eq!((w.format_tag, w.channels, w.sample_rate, w.block_align, w.bits_per_sample, a.sample_size), (1, 2, 48_000, 4, 16, 4)); + // the index knows the delta frame; a scan cannot + let keys = if idx1 { [true, false, true] } else { [true; 3] }; + assert_eq!(table(&f, 0), vec![(10, keys[0]), (6, keys[1]), (7, keys[2])], "{what}"); + assert_eq!(f.streams[0].keyframes_known, idx1); + assert_eq!(table(&f, 1), vec![(16, true), (8, true)], "{what}"); + assert_eq!(f.read_chunk(&file, 0, 1).unwrap(), vec![3; 6], "{what}"); + assert_eq!(f.read_chunk(&file, 0, 2).unwrap(), vec![5; 7], "{what}"); + assert_eq!(f.read_chunk(&file, 1, 1).unwrap(), vec![4; 8], "{what}"); + assert!(f.read_chunk(&file, 0, 3).is_err() && f.read_chunk(&file, 5, 0).is_err()); + } + // the idx1 path can be skipped + let f = open_with(&avi(true, false, false), OpenOptions { ignore_idx1: true, ..Default::default() }).unwrap(); + assert_eq!(f.index, IndexSource::Scan); +} + +#[test] +fn not_avi_and_truncated_recordings() { + assert!(matches!(open(&b"RIFF\0\0\0\0WAVEfmt ".to_vec()), Err(Error::NotAvi))); + assert!(matches!(open(&Vec::new()), Err(Error::NotAvi))); + assert!(sniff(&avi(true, false, false)) && !sniff(b"RIFF")); + // a recording cut off in its last frame: the headers and the whole frames are there + let full = avi(false, false, false); + let cut = full[..full.len() - 4].to_vec(); + let f = open(&cut).unwrap(); + assert_eq!(f.streams[0].chunks.len(), 3); + assert!(f.read_chunk(&cut, 0, 0).is_ok()); +} + +/// The idx1 entries of one stream damaged (offsets past the file) while the other's are fine: the +/// video still comes from a scan of `movi` instead of vanishing, its key frames unknown, and the +/// audio keeps its index. A stream with no data at all stays empty. +#[test] +fn a_stream_whose_index_entries_are_damaged_is_scanned() { + let mut file = avi(true, false, false); + let ix = file.windows(4).rposition(|w| w == b"idx1").unwrap() + 8; + for e in file[ix..].as_chunks_mut::<16>().0.iter_mut().filter(|e| &e[..4] == b"00dc") { + e[8..12].copy_from_slice(&0xFFFF_FF00u32.to_le_bytes()); + } + let f = open(&file).unwrap(); + assert_eq!(f.index, IndexSource::Idx1); + assert_eq!(table(&f, 0), vec![(10, true), (6, true), (7, true)]); + assert!(!f.streams[0].keyframes_known); + assert_eq!(f.read_chunk(&file, 0, 1).unwrap(), vec![3; 6]); + assert_eq!(table(&f, 1), vec![(16, true), (8, true)]); + assert!(f.streams[1].keyframes_known); + // with an AVIX extension after it: the first RIFF's frames come first, then the extension's + let mut extended = file.clone(); + extended.extend(chunk(b"RIFF", &[b"AVIX".to_vec(), list(b"movi", &chunk(b"00dc", &[6; 9]))].concat())); + let f = open(&extended).unwrap(); + assert_eq!(table(&f, 0), vec![(10, true), (6, true), (7, true), (9, true)]); + assert_eq!(table(&f, 1), vec![(16, true), (8, true)]); + // an audio-only recording of a file that declares video: nothing to find + let mut silent = avi(true, false, false); + while let Some(i) = silent.windows(4).position(|w| w == b"00dc") { + silent[i..i + 4].copy_from_slice(b"JUNK"); + } + let f = open(&silent).unwrap(); + assert!(f.streams[0].chunks.is_empty()); + assert_eq!(table(&f, 1), vec![(16, true), (8, true)]); +} + +/// A healthy file whose index leaves a stream empty because it declares no data (an audio track +/// that never recorded a sample) opens from the index alone: the stream is not looked for in +/// `movi`, which a large file would pay for with a read per chunk. +#[test] +fn an_empty_stream_that_declares_no_data_is_not_scanned() { + struct Counted<'a>(&'a [u8], std::cell::Cell); + impl ByteSource for Counted<'_> { + fn len(&self) -> u64 { + self.0.len() as u64 + } + fn read_at(&self, offset: u64, buf: &mut [u8]) -> std::io::Result<()> { + self.1.set(self.1.get() + 1); + self.0.read_at(offset, buf) + } + } + let open_counted = |file: &[u8]| { + let src = Counted(file, Default::default()); + (open(&src).unwrap(), src.1.get()) + }; + let intact = avi(true, false, false); + // the audio's index entries gone and its length zero; its chunks stay where a scan would find them + let mut file = intact.clone(); + let ix = file.windows(4).rposition(|w| w == b"idx1").unwrap() + 8; + for e in file[ix..].as_chunks_mut::<16>().0.iter_mut().filter(|e| &e[..4] == b"01wb") { + e[..4].copy_from_slice(b"JUNK"); + } + let strh = file.windows(4).enumerate().filter(|(_, w)| w == b"strh").nth(1).unwrap().0 + 8; + file[strh + 32..strh + 36].fill(0); + let (f, reads) = open_counted(&file); + assert_eq!(f.index, IndexSource::Idx1); + assert_eq!(table(&f, 0), vec![(10, true), (6, false), (7, true)]); + assert!(f.streams[1].chunks.is_empty() && f.streams[1].keyframes_known); + assert_eq!(reads, open_counted(&intact).1); +} + +/// Every single-byte change and every truncation of a valid file opens or fails, never panics, and +/// whatever opens reads its chunks without panicking. +#[test] +fn mutations_never_panic() { + for base in [avi(true, false, true), avi(false, false, false), avi(true, true, false)] { + for cut in 0..base.len() { + let b = base[..cut].to_vec(); + if let Ok(f) = open(&b) { + for (s, st) in f.streams.iter().enumerate() { + for i in 0..st.chunks.len() { + let _ = f.read_chunk(&b, s, i); + } + } + } + } + for at in 0..base.len() { + for v in [0x00u8, 0xFF, 0x7F, 0x80] { + let mut b = base.clone(); + b[at] = v; + if let Ok(f) = open(&b) { + for (s, st) in f.streams.iter().enumerate() { + for i in 0..st.chunks.len() { + let _ = f.read_chunk(&b, s, i); + } + } + } + } + } + } +} + +/// An OpenDML file: each stream's `indx` super index points at an `ix##` standard index (base +/// offset + offsets to the data, bit 31 of the size marking delta frames). Built twice: the second +/// pass knows where the `ix##` chunks landed. +fn avi_odml(ix_at: [u64; 2]) -> (Vec, [u64; 2]) { + let indx = |stream: u8, at: u64| { + let mut b = Vec::new(); + b.extend_from_slice(&4u16.to_le_bytes()); // wLongsPerEntry + b.extend_from_slice(&[0, 0]); // subtype, AVI_INDEX_OF_INDEXES + b.extend_from_slice(&1u32.to_le_bytes()); + b.extend_from_slice(&[b'0', b'0' + stream, if stream == 0 { b'd' } else { b'w' }, if stream == 0 { b'c' } else { b'b' }]); + b.extend_from_slice(&[0; 12]); + b.extend_from_slice(&at.to_le_bytes()); + b.extend_from_slice(&0u32.to_le_bytes()); + b.extend_from_slice(&0u32.to_le_bytes()); + chunk(b"indx", &b) + }; + let mut hdrl = chunk(b"avih", &[0; 56]); + for (s, at) in ix_at.iter().enumerate() { + let l = strl(s == 0); + // strl = LIST strl …: append indx inside it + let mut body = l[12..].to_vec(); + body.extend(indx(s as u8, *at)); + hdrl.extend(list(b"strl", &body)); + } + let mut riff = b"AVI ".to_vec(); + riff.extend(list(b"hdrl", &hdrl)); + // movi: video 10 (key) 6 (delta) 7 (key), audio 16 8; then ix00, ix01 + let movi_data_at = 8 + riff.len() as u64 + 12; // RIFF hdr, so far, LIST hdr + `movi` + let mut body = Vec::new(); + let mut at: [Vec<(u64, u32, bool)>; 2] = [Vec::new(), Vec::new()]; + for (s, data, key) in + [(0usize, vec![1u8; 10], true), (1, vec![2; 16], true), (0, vec![3; 6], false), (1, vec![4; 8], true), (0, vec![5; 7], true)] + { + let id = if s == 0 { b"00dc" } else { b"01wb" }; + at[s].push((movi_data_at + body.len() as u64 + 8, data.len() as u32, key)); + body.extend(chunk(id, &data)); + } + let mut where_ix = [0u64; 2]; + for (s, entries) in at.iter().enumerate() { + let base = 100u64; // offsets are relative to qwBaseOffset + let mut b = Vec::new(); + b.extend_from_slice(&2u16.to_le_bytes()); + b.extend_from_slice(&[0, 1]); // subtype 0, AVI_INDEX_OF_CHUNKS + b.extend_from_slice(&(entries.len() as u32).to_le_bytes()); + b.extend_from_slice(if s == 0 { b"00dc" } else { b"01wb" }); + b.extend_from_slice(&base.to_le_bytes()); + b.extend_from_slice(&0u32.to_le_bytes()); + for &(off, size, key) in entries { + b.extend_from_slice(&((off - base) as u32).to_le_bytes()); + b.extend_from_slice(&(size | if key { 0 } else { 0x8000_0000 }).to_le_bytes()); + } + where_ix[s] = movi_data_at + body.len() as u64; + body.extend(chunk(if s == 0 { b"ix00" } else { b"ix01" }, &b)); + } + riff.extend(list(b"movi", &body)); + (chunk(b"RIFF", &riff), where_ix) +} + +#[test] +fn opendml_standard_indexes() { + let (_, at) = avi_odml([0, 0]); + let (file, again) = avi_odml(at); + assert_eq!(at, again, "the layout does not depend on the offsets"); + let f = open(&file).unwrap(); + assert_eq!(f.index, IndexSource::OpenDml); + assert_eq!(table(&f, 0), vec![(10, true), (6, false), (7, true)]); + assert_eq!(table(&f, 1), vec![(16, true), (8, true)]); + assert_eq!(f.read_chunk(&file, 0, 2).unwrap(), vec![5; 7]); + // ignoring the OpenDML index, the scan finds the same chunks (and skips the ix## chunks) + let s = open_with(&file, OpenOptions { ignore_odml: true, ..Default::default() }).unwrap(); + assert_eq!(s.index, IndexSource::Scan); + assert_eq!(s.streams[0].chunks.iter().map(|c| c.offset).collect::>(), f.streams[0].chunks.iter().map(|c| c.offset).collect::>()); + // a broken super index (pointing nowhere) falls back to a scan + let (bad, _) = avi_odml([3, 5]); + assert_eq!(open(&bad).unwrap().index, IndexSource::Scan); + // and mutations of the OpenDML file never panic + for i in 0..file.len() { + let mut b = file.clone(); + b[i] ^= 0xFF; + if let Ok(f) = open(&b) { + for (s, st) in f.streams.iter().enumerate() { + for k in 0..st.chunks.len() { + let _ = f.read_chunk(&b, s, k); + } + } + } + } +} + +#[test] +fn opendml_repeated_index_offsets_are_read_once() { + let (_, at) = avi_odml([0, 0]); + let (file, _) = avi_odml(at); + let mut streams = open(&file).unwrap().streams; + // A malicious super index repeats each valid standard-index address. It must not multiply + // its chunks, allocations, or traversal work. + for (stream, &index) in streams.iter_mut().zip(&at) { + stream.super_index = vec![index; 100]; + } + assert!(read_odml(&file, &mut streams)); + assert_eq!(streams[0].chunks.len(), 3); + assert_eq!(streams[1].chunks.len(), 2); +} + +/// Tiny `AVIX` forms whose `movi` lists claim the rest of the file: each list is held to its +/// form, so the chunks after them are neither recorded once per list nor recorded at all. +#[test] +fn lists_do_not_reach_past_their_container() { + let mut file = avi(false, false, false); + let forms = 64; + for _ in 0..forms { + let mut riff = b"RIFF".to_vec(); + riff.extend_from_slice(&16u32.to_le_bytes()); + riff.extend_from_slice(b"AVIX"); + riff.extend_from_slice(b"LIST"); + riff.extend_from_slice(&0xFFFF_FFF0u32.to_le_bytes()); + riff.extend_from_slice(b"movi"); + file.extend(riff); + } + for _ in 0..32 { + file.extend(chunk(b"00dc", &[9; 8])); + } + let f = open(&file).unwrap(); + assert_eq!(f.index, IndexSource::Scan); + assert_eq!(table(&f, 0), vec![(10, true), (6, true), (7, true)]); + assert_eq!(table(&f, 1), vec![(16, true), (8, true)]); + + // `rec ` lists inside one `movi` that each claim the rest of it + let mut body = Vec::new(); + for _ in 0..64 { + // LIST(16) rec { LIST(huge) rec … } + body.extend_from_slice(b"LIST"); + body.extend_from_slice(&16u32.to_le_bytes()); + body.extend_from_slice(b"rec LIST"); + body.extend_from_slice(&0xFFFF_FFF0u32.to_le_bytes()); + body.extend_from_slice(b"rec "); + } + for _ in 0..32 { + body.extend(chunk(b"00dc", &[9; 8])); + } + let mut streams = open(&avi(false, false, false)).unwrap().streams; + clear(&mut streams); + let movi = list(b"movi", &body); + scan(&movi, &mut streams, &|_| true, 12, movi.len() as u64, 0); + assert_eq!(streams[0].chunks.len(), 32); +} + +#[test] +fn read_chunk_range_reads_only_the_range_and_refuses_one_outside_the_chunk() { + let data: Vec = (0..100).collect(); + let stream = Stream { + kind: StreamKind::Audio, + handler: [0; 4], + scale: 1, + rate: 1, + start: 0, + length: 0, + sample_size: 0, + video: None, + audio: None, + name: None, + chunks: vec![Chunk { offset: 10, size: 50, key: true }], + keyframes_known: false, + super_index: Vec::new(), + }; + let file = AviFile { header: MainHeader::default(), streams: vec![stream], index: IndexSource::Scan }; + assert_eq!(file.read_chunk_range(&data, 0, 0, 5, 3).unwrap(), [15, 16, 17]); + assert_eq!(file.read_chunk_range(&data, 0, 0, 0, 50).unwrap().len(), 50); + assert!(file.read_chunk_range(&data, 0, 0, 48, 3).is_err(), "past the chunk's size"); + assert!(file.read_chunk_range(&data, 0, 0, usize::MAX, 2).is_err()); + assert!(file.read_chunk_range(&data, 0, 1, 0, 1).is_err()); +} + +/// A file with the given `hdrl` body and one video chunk in `movi`. +fn avi_with_hdrl(hdrl: &[u8]) -> Vec { + let mut riff = b"AVI ".to_vec(); + riff.extend(list(b"hdrl", hdrl)); + riff.extend(list(b"movi", &chunk(b"00dc", &[1; 4]))); + chunk(b"RIFF", &riff) +} + +#[test] +fn streams_past_the_limit_are_ignored() { + let hdrl: Vec = (0..MAX_STREAMS + 6).flat_map(|_| strl(true)).collect(); + let f = open(&avi_with_hdrl(&hdrl)).unwrap(); + assert_eq!(f.streams.len(), MAX_STREAMS); +} + +#[test] +fn a_header_list_past_the_limit_is_refused() { + let mut hdrl = strl(true); + hdrl.extend(chunk(b"JUNK", &vec![0; MAX_HEADER as usize - hdrl.len() - 8])); + assert!(open(&avi_with_hdrl(&hdrl)).is_ok(), "exactly the limit"); + hdrl.extend(chunk(b"JUNK", &[0; 2])); + assert!(matches!(open(&avi_with_hdrl(&hdrl)), Err(Error::Invalid(_)))); +} + +#[test] +fn rec_lists_nested_past_the_limit_are_not_scanned() { + let nested = |depth: u32| { + let mut body = chunk(b"00dc", &[7; 4]); + for _ in 0..depth { + body = list(b"rec ", &body); + } + let mut riff = b"AVI ".to_vec(); + riff.extend(list(b"hdrl", &strl(true))); + riff.extend(list(b"movi", &body)); + open(&chunk(b"RIFF", &riff)).unwrap().streams[0].chunks.len() + }; + // `movi` itself is depth 0 + assert_eq!(nested(MAX_DEPTH - 1), 1); + assert_eq!(nested(MAX_DEPTH), 0); + assert_eq!(nested(500), 0); +} + +/// A source that is `.1` long and zero after its real bytes, and counts the bytes read. +struct Sparse(Vec, u64, std::cell::Cell); + +impl ByteSource for Sparse { + fn len(&self) -> u64 { + self.1 + } + fn read_at(&self, offset: u64, buf: &mut [u8]) -> std::io::Result<()> { + self.2.set(self.2.get() + buf.len() as u64); + buf.fill(0); + let real = self.0.get(offset.min(self.0.len() as u64) as usize..).unwrap_or_default(); + let n = real.len().min(buf.len()); + buf[..n].copy_from_slice(&real[..n]); + Ok(()) + } +} + +/// A standard index that declares more entries than the index budget is not read (nor +/// allocated): the file opens from a scan. +#[test] +fn opendml_indexes_past_the_byte_budget_are_not_read() { + let (_, at) = avi_odml([0, 0]); + let (mut file, _) = avi_odml(at); + // the video's ix00: claim the rest of a 1 GiB file, full of entries + let ix = at[0] as usize; + file[ix + 4..ix + 8].copy_from_slice(&0x3000_0000u32.to_le_bytes()); + file[ix + 12..ix + 16].copy_from_slice(&((MAX_ODML_INDEX_BYTES / 8) as u32 + 1).to_le_bytes()); + let mut streams = open(&file).unwrap().streams; + let src = Sparse(file, 1 << 30, Default::default()); + assert!(!read_odml(&src, &mut streams)); + assert!(src.2.get() < 1024, "only headers were read, not {} bytes", src.2.get()); + assert!(streams[0].chunks.is_empty()); + // one entry fewer fits the budget in bytes (and is then read) + let mut file = src.0; + file[ix + 12..ix + 16].copy_from_slice(&(((MAX_ODML_INDEX_BYTES - 24) / 8) as u32).to_le_bytes()); + let src = Sparse(file, 1 << 30, Default::default()); + read_odml(&src, &mut streams); + assert!(src.2.get() >= MAX_ODML_INDEX_BYTES); +} + +#[test] +fn codec_params_map_fourccs_and_format_tags() { + use crate::{CodecId, PcmFormat}; + let f = open(&avi(true, false, false)).unwrap(); + let v = f.streams[0].codec_params(); + assert_eq!((v.codec, v.tag, v.width, v.height), (CodecId::Mjpeg, Some(*b"MJPG"), Some(64), Some(48))); + let a = f.streams[1].codec_params(); + assert_eq!((a.codec, a.sample_rate, a.channels, a.pcm), (CodecId::Pcm, Some(48_000), Some(2), Some(PcmFormat::int(16, true, false)))); + let mut s = f.streams[0].clone(); + let video = |s: &mut Stream, fourcc: &[u8; 4], height: i32| { + let b = s.video.as_mut().unwrap(); + (b.compression, b.height, b.extra) = (*fourcc, height, vec![1, 2]); + s.codec_params() + }; + for (fourcc, codec) in [ + (b"h264", CodecId::H264), + (b"X264", CodecId::H264), + (b"hvc1", CodecId::Hevc), + (b"XVID", CodecId::Mpeg4Video), + (b"apch", CodecId::ProRes), + (b"AVdn", CodecId::Dnxhd), + (b"YUY2", CodecId::Unknown), + (&[0; 4], CodecId::Unknown), + ] { + let p = video(&mut s, fourcc, -48); + assert_eq!((p.codec, p.tag, p.height, p.extradata.as_slice()), (codec, Some(*fourcc), Some(48), &[1u8, 2][..]), "{fourcc:?}"); + } + assert_eq!(video(&mut s, b"MJPG", i32::MIN).height, Some(1 << 31)); + let mut s = f.streams[1].clone(); + for (tag, bits, codec, pcm) in [ + (1, 8, CodecId::Pcm, Some(PcmFormat::int(8, false, false))), + (3, 32, CodecId::Pcm, Some(PcmFormat::float(32, false))), + (0x55, 0, CodecId::Mp3, None), + (0x50, 0, CodecId::Mp2, None), + (0x2000, 0, CodecId::Ac3, None), + (0xFF, 0, CodecId::Aac, None), + (0x1234, 0, CodecId::Unknown, None), + ] { + let w = s.audio.as_mut().unwrap(); + (w.format_tag, w.bits_per_sample) = (tag, bits); + let p = s.codec_params(); + assert_eq!((p.codec, p.pcm), (codec, pcm), "tag {tag:#x}"); + } + // a stream that is neither + s.audio = None; + assert_eq!(s.codec_params().codec, CodecId::Unknown); +} + +/// `WAVE_FORMAT_EXTENSIBLE` resolves to the tag its sub-format GUID starts with. +#[test] +fn wave_format_extensible_resolves_to_its_sub_format() { + let file = avi(true, false, false); + let strf = file.windows(4).enumerate().filter(|(_, w)| w == b"strf").nth(1).unwrap().0; + // an 18-byte WAVEFORMATEX becomes 40 bytes: cbSize 22, then valid bits, mask, GUID + let mut ext = file[strf + 8..strf + 26].to_vec(); + ext[..2].copy_from_slice(&0xFFFEu16.to_le_bytes()); + ext[16..18].copy_from_slice(&22u16.to_le_bytes()); + ext.extend_from_slice(&[16, 0, 3, 0, 0, 0]); + ext.extend_from_slice(&[3, 0, 0, 0, 0, 0, 0x10, 0, 0x80, 0, 0, 0xAA, 0, 0x38, 0x9B, 0x71]); + // rebuild the stream list around the longer strf + let strl_at = file.windows(4).enumerate().filter(|(_, w)| w == b"strl").nth(1).unwrap().0 - 8; + let old = le32(&file, strl_at + 4) as usize; + let mut body = file[strl_at + 12..strf].to_vec(); + body.extend(chunk(b"strf", &ext)); + body.extend_from_slice(&file[strf + 26..strl_at + 8 + old]); + let mut hdrl = chunk(b"avih", &[0; 56]); + hdrl.extend(strl(true)); + hdrl.extend(list(b"strl", &body)); + let f = open(&avi_with_hdrl(&hdrl)).unwrap(); + let w = f.streams[1].audio.as_ref().unwrap(); + assert_eq!((w.format_tag, w.extra.len()), (3, 22)); + assert_eq!(f.streams[1].codec_params().codec, crate::CodecId::Pcm); +} + +/// Random multi-byte damage to every kind of file (including OpenDML): opening, reading every +/// chunk and mapping the codecs never panics. +#[test] +fn random_damage_never_panics() { + let (_, at) = avi_odml([0, 0]); + let mut state = 0x9E37_79B9_7F4A_7C15u64; + let mut next = move || { + state ^= state << 13; + state ^= state >> 7; + state ^= state << 17; + state + }; + for base in [avi(true, false, true), avi(false, false, false), avi(true, true, false), avi_odml(at).0] { + for _ in 0..4000 { + let mut b = base.clone(); + for _ in 0..1 + next() % 6 { + let at = (next() % b.len() as u64) as usize; + // whole 32-bit fields as often as single bytes: sizes, counts and offsets + let v = [0u32, 1, 0x7FFF_FFFF, 0x8000_0000, 0xFFFF_FFFF, next() as u32][(next() % 6) as usize].to_le_bytes(); + let n = if next() % 2 == 0 { 1 } else { 4 }; + for (d, s) in b[at..].iter_mut().zip(&v[..n]) { + *d = *s; + } + } + b.truncate(b.len() - (next() % 3) as usize * (next() % 40) as usize); + let Ok(f) = open(&b) else { continue }; + for (s, st) in f.streams.iter().enumerate() { + let _ = st.codec_params(); + for i in 0..st.chunks.len() { + let _ = f.read_chunk(&b, s, i); + let _ = f.read_chunk_range(&b, s, i, 1, usize::MAX); + } + } + } + } +} + +/// The bytes after an H.264 / HEVC format header say how the chunks are framed: nothing (sets in +/// band), Annex B parameter sets, or an `avcC` / `hvcC` record with its length-prefix size. +#[test] +fn nal_framing_reads_the_stream_header_setup() { + let f = open(&avi(true, false, false)).unwrap(); + let mut s = f.streams[0].clone(); + assert_eq!(s.nal_framing(), None, "Motion JPEG has no NAL units"); + assert_eq!(f.streams[1].nal_framing(), None, "nor has audio"); + let mut framing = |fourcc: &[u8; 4], extra: &[u8]| { + let b = s.video.as_mut().unwrap(); + (b.compression, b.extra) = (*fourcc, extra.to_vec()); + (s.nal_framing(), s.codec_params().extradata == extra) + }; + assert_eq!(framing(b"H264", &[]), (Some(NalFraming::AnnexB { header_sets: false }), true)); + assert_eq!(framing(b"H264", &[0, 0, 0, 1, 0x67, 0x64]), (Some(NalFraming::AnnexB { header_sets: true }), true)); + assert_eq!(framing(b"hevc", &[0, 0, 1, 0x40, 1]), (Some(NalFraming::AnnexB { header_sets: true }), true)); + // avcC: version 1, profile, compatibility, level, then 6 reserved bits and lengthSizeMinusOne + assert_eq!(framing(b"avc1", &[1, 0x64, 0, 0x1F, 0xFF, 0xE1]), (Some(NalFraming::LengthPrefixed(4)), true)); + assert_eq!(framing(b"avc1", &[1, 0x64, 0, 0x1F, 0xFD]), (Some(NalFraming::LengthPrefixed(2)), true)); + // hvcC keeps it in byte 21 + let mut hvcc = vec![1u8; 23]; + hvcc[21] = 0xF2; + assert_eq!(framing(b"hvc1", &hvcc), (Some(NalFraming::LengthPrefixed(3)), true)); + // a record cut short still frames the chunks, with the usual four bytes + assert_eq!(framing(b"hvc1", &[1, 2, 3]), (Some(NalFraming::LengthPrefixed(4)), true)); + // setup that is neither: left as Annex B with the sets in band + assert_eq!(framing(b"H264", &[9, 9, 9]), (Some(NalFraming::AnnexB { header_sets: false }), true)); +} diff --git a/crates/media/src/avi/tests/hostile.rs b/crates/media/src/avi/tests/hostile.rs new file mode 100644 index 000000000..b4f57db41 --- /dev/null +++ b/crates/media/src/avi/tests/hostile.rs @@ -0,0 +1,25 @@ +//! Hostile-input hammer: truncation, bit flips and extreme field values must never panic or hang. + +use super::*; + +fn exercise(d: &[u8]) { + for opts in [OpenOptions::default(), OpenOptions { ignore_odml: true, ..Default::default() }] { + if let Ok(f) = open_with(d, opts) { + for (s, st) in f.streams.iter().enumerate() { + let n = st.chunks.len(); + for k in [0, n / 2, n.saturating_sub(1), n, usize::MAX] { + let _ = f.read_chunk(d, s, k); + } + } + } + } +} + +#[test] +fn hostile_input_never_panics() { + let (_, at) = avi_odml([0, 0]); + let seeds = [avi(true, false, false), avi(true, true, true), avi(false, false, false), avi_odml(at).0]; + for (i, s) in seeds.iter().enumerate() { + craft_media_testkit::hostile::hammer(&format!("avi seed {i}"), s, 30_000, exercise); + } +} diff --git a/crates/media/src/bitstream.rs b/crates/media/src/bitstream.rs new file mode 100644 index 000000000..abfcdaa2c --- /dev/null +++ b/crates/media/src/bitstream.rs @@ -0,0 +1,979 @@ +//! Bit-level reading and writing for codec and container code. +//! +//! - [`BitReader`]: MSB-first reader with Exp-Golomb (`ue(v)`, `se(v)`), as used by H.264/HEVC/AV1 headers. +//! - [`BitWriter`]: the matching writer (for encoders and header rewriting). +//! - [`unescape_rbsp`] / [`escape_rbsp`]: remove/insert H.264/HEVC emulation-prevention bytes. +//! - [`annexb_nals`] / [`length_prefixed_nals`]: split Annex-B byte streams and AVCC/HVCC samples into NAL units. + +use std::fmt; + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum BitError { + /// Tried to read past the end of the buffer. + Eof, + /// An Exp-Golomb code longer than 32 leading zeros. + InvalidExpGolomb, + /// An AVCC/HVCC NAL length prefix width outside 1 to 4 bytes. + InvalidNalLengthSize, +} + +impl fmt::Display for BitError { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + BitError::Eof => f.write_str("unexpected end of bitstream"), + BitError::InvalidExpGolomb => f.write_str("invalid Exp-Golomb code"), + BitError::InvalidNalLengthSize => f.write_str("NAL length prefix must be 1 to 4 bytes"), + } + } +} +impl std::error::Error for BitError {} + +pub type Result = std::result::Result; + +/// MSB-first bit reader over a byte slice. +#[derive(Clone)] +pub struct BitReader<'a> { + data: &'a [u8], + /// Position in bits. + pos: usize, + /// Bit position of the last set bit (the `rbsp_stop_one_bit`), found once so that + /// [`Self::more_rbsp_data`] does not rescan a long zero suffix on every call. + rbsp_stop: Option, +} + +impl<'a> BitReader<'a> { + pub fn new(data: &'a [u8]) -> Self { + let rbsp_stop = data.iter().rposition(|&b| b != 0).map(|i| i.saturating_mul(8).saturating_add(7 - data[i].trailing_zeros() as usize)); + Self { data, pos: 0, rbsp_stop } + } + pub fn data(&self) -> &'a [u8] { + self.data + } + /// Bit position from the start. + pub fn position(&self) -> usize { + self.pos + } + pub fn bits_left(&self) -> usize { + self.data.len().saturating_mul(8).saturating_sub(self.pos) + } + pub fn is_byte_aligned(&self) -> bool { + self.pos.is_multiple_of(8) + } + pub fn byte_align(&mut self) { + self.pos = self.pos.div_ceil(8) * 8; + } + /// Byte offset of the current position (rounded down). + pub fn byte_pos(&self) -> usize { + self.pos / 8 + } + pub fn seek_bits(&mut self, pos: usize) { + self.pos = pos; + } + + /// Peek `n` bits without consuming, zero-padded past the end. For `n` above 32 this returns + /// what [`read_bits`](Self::read_bits) would: the low 32 bits of the `n`-bit field. + #[inline] + pub fn peek(&self, n: u32) -> u32 { + if n > 32 { + let mut r = self.clone(); + r.pos = r.pos.saturating_add((n - 32) as usize); + return r.peek(32); + } + if n == 0 { + return 0; + } + let byte = self.pos / 8; + let shift = self.pos % 8; + // One 8-byte load while at least 8 bytes are left (`shift` <= 7 leaves 57 valid bits). + if let Some(w) = self.data.get(byte..).and_then(<[u8]>::first_chunk::<8>) { + return ((u64::from_be_bytes(*w) << shift) >> (64 - n)) as u32; + } + self.peek_tail(n, byte, shift) + } + + /// [`Self::peek`] for the last 7 bytes and past the end: byte loads, zero padded. + #[cold] + fn peek_tail(&self, n: u32, byte: usize, shift: usize) -> u32 { + let mut v: u64 = 0; + for i in 0..5 { + v = (v << 8) | *self.data.get(byte.saturating_add(i)).unwrap_or(&0) as u64; + } + // v holds 40 bits starting at `byte` + ((v << (24 + shift)) >> (64 - n)) as u32 + } + + /// Read `n` bits. For `n` above 32 this consumes `n` bits and returns the low 32 of them. + #[inline] + pub fn read_bits(&mut self, n: u32) -> Result { + if n as usize > self.bits_left() { + return Err(BitError::Eof); + } + if n > 32 { + self.pos += (n - 32) as usize; + return self.read_bits(32); + } + let v = self.peek(n); + self.pos += n as usize; + Ok(v) + } + + pub fn read_bits_u64(&mut self, n: u32) -> Result { + if n <= 32 { + return self.read_bits(n).map(u64::from); + } + let hi = self.read_bits(n - 32)? as u64; + let lo = self.read_bits(32)? as u64; + Ok((hi << 32) | lo) + } + + #[inline] + pub fn read_bit(&mut self) -> Result { + if self.bits_left() == 0 { + return Err(BitError::Eof); + } + // `pos` is below `len * 8` here, so the byte exists. + let byte = self.data.get(self.pos / 8).copied().unwrap_or(0); + let bit = (byte >> (7 - self.pos % 8)) & 1; + self.pos += 1; + Ok(bit == 1) + } + pub fn read_flag(&mut self) -> Result { + self.read_bit() + } + + pub fn skip(&mut self, n: usize) -> Result<()> { + if n > self.bits_left() { + return Err(BitError::Eof); + } + self.pos += n; + Ok(()) + } + + /// Raw Exp-Golomb codeNum, up to 32 leading zeros (so below 2^33). + #[inline] + fn read_code_num(&mut self) -> Result { + // Codes up to 31 bits (15 leading zeros) that lie wholly inside the data: one peek. + let w = self.peek(32); + let zeros = w.leading_zeros(); + if zeros < 16 { + let len = 2 * zeros + 1; + if len as usize <= self.bits_left() { + self.pos += len as usize; + // The `len`-bit field is 2^zeros + suffix; codeNum is that minus one. + return Ok(u64::from((w >> (32 - len)) - 1)); + } + } + self.read_code_num_slow() + } + + /// [`Self::read_code_num`] bit by bit: long codes, the end of the data and invalid codes. + #[cold] + fn read_code_num_slow(&mut self) -> Result { + let mut zeros = 0u32; + while !self.read_bit()? { + zeros += 1; + if zeros > 32 { + return Err(BitError::InvalidExpGolomb); + } + } + if zeros == 0 { + return Ok(0); + } + let v = self.read_bits_u64(zeros)?; + Ok((1u64 << zeros) - 1 + v) + } + + /// Unsigned Exp-Golomb `ue(v)`. + pub fn read_ue(&mut self) -> Result { + u32::try_from(self.read_code_num()?).map_err(|_| BitError::InvalidExpGolomb) + } + + /// `ue(v) + add` (the `..._minus1` / `..._minus8` fields), failing instead of overflowing on a + /// hostile value near `u32::MAX`. + pub fn read_ue_plus(&mut self, add: u32) -> Result { + self.read_ue()?.checked_add(add).ok_or(BitError::InvalidExpGolomb) + } + + /// Signed Exp-Golomb `se(v)`. + pub fn read_se(&mut self) -> Result { + // codeNum 2^32 is -2^31, so the mapping is done before narrowing to 32 bits. + let k = self.read_code_num()? as i64; + let v = if k & 1 == 1 { (k + 1) / 2 } else { -(k / 2) }; + i32::try_from(v).map_err(|_| BitError::InvalidExpGolomb) + } + + /// Truncated Exp-Golomb `te(v)` with range `max`. + pub fn read_te(&mut self, max: u32) -> Result { + if max > 1 { self.read_ue() } else { Ok(!self.read_bit()? as u32) } + } + + /// H.264/HEVC `more_rbsp_data()`: true if there is data before the rbsp trailing bits. + pub fn more_rbsp_data(&self) -> bool { + self.rbsp_stop.is_some_and(|stop| self.pos < stop) + } +} + +/// MSB-first bit writer. +#[derive(Default, Clone)] +pub struct BitWriter { + buf: Vec, + acc: u64, + nbits: u32, +} + +impl BitWriter { + pub fn new() -> Self { + Self::default() + } + /// Write the low `n` bits of `value`. For `n` above 32 the extra high bits are zeros; + /// `n` above 64 writes 64 bits. + pub fn write_bits(&mut self, value: u32, n: u32) { + let mut n = n.min(64); + while n > 32 { + let pad = (n - 32).min(32); + self.write_bits(0, pad); + n -= pad; + } + if n == 0 { + return; + } + let v = (value as u64) & ((1u64 << n) - 1); + self.acc = (self.acc << n) | v; + self.nbits += n; + while self.nbits >= 8 { + self.nbits -= 8; + self.buf.push((self.acc >> self.nbits) as u8); + } + self.acc &= (1u64 << self.nbits) - 1; + } + pub fn write_bit(&mut self, b: bool) { + self.write_bits(b as u32, 1); + } + pub fn write_ue(&mut self, v: u32) { + self.write_code_num(u64::from(v)); + } + /// Exp-Golomb codeNum up to 2^32 (the code of `se(v)` -2^31). + fn write_code_num(&mut self, v: u64) { + let x = v + 1; + let len = 64 - x.leading_zeros(); + let zeros = len - 1; + if zeros + len <= 32 { + // The leading zeros are the high bits of a (zeros + len)-bit field. + self.write_bits(x as u32, zeros + len); + return; + } + self.write_bits(0, zeros); + if len > 32 { + self.write_bits((x >> 32) as u32, len - 32); + self.write_bits(x as u32, 32); + } else { + self.write_bits(x as u32, len); + } + } + pub fn write_se(&mut self, v: i32) { + let m = u64::from(v.unsigned_abs()) * 2; + self.write_code_num(if v > 0 { m - 1 } else { m }); + } + pub fn bit_len(&self) -> usize { + self.buf.len() * 8 + self.nbits as usize + } + pub fn is_byte_aligned(&self) -> bool { + self.nbits == 0 + } + /// Pad with zero bits to a byte boundary. + pub fn align_zero(&mut self) { + if self.nbits > 0 { + self.write_bits(0, 8 - self.nbits); + } + } + /// `rbsp_trailing_bits()`: a one bit then zeros to alignment. + pub fn rbsp_trailing(&mut self) { + self.write_bit(true); + self.align_zero(); + } + pub fn write_bytes(&mut self, bytes: &[u8]) { + if self.nbits == 0 { + self.buf.extend_from_slice(bytes); + } else { + for &b in bytes { + self.write_bits(b as u32, 8); + } + } + } + pub fn finish(mut self) -> Vec { + self.align_zero(); + self.buf + } + pub fn bytes(&self) -> &[u8] { + &self.buf + } +} + +/// Remove emulation-prevention bytes (`00 00 03` → `00 00`) from a NAL payload. +pub fn unescape_rbsp(data: &[u8]) -> Vec { + let mut out = Vec::with_capacity(data.len()); + // `data[start..]` is not copied yet; a removed `03` restarts the zero count at `start`. + let mut start = 0; + // Candidate position of an `03` preceded by two zeros at or after `start`. + let mut i = 2; + while let Some(&b) = data.get(i) { + if b != 0 { + // A nonzero byte at `i` rules out an `00 00 03` ending at i + 1 or i + 2. + if b == 3 && data.get(i - 2..i) == Some(&[0, 0][..]) { + out.extend_from_slice(data.get(start..i).unwrap_or_default()); + start = i + 1; + i = start + 2; + } else { + i += 3; + } + } else { + i += 1; + } + } + out.extend_from_slice(data.get(start..).unwrap_or_default()); + out +} + +/// Insert emulation-prevention bytes so no `00 00 0x` (x ≤ 3) sequence appears. +pub fn escape_rbsp(data: &[u8]) -> Vec { + let mut out = Vec::with_capacity(data.len() + data.len() / 64); + let mut zeros = 0; + for &b in data { + if zeros >= 2 && b <= 3 { + out.push(3); + zeros = 0; + } + out.push(b); + zeros = if b == 0 { zeros + 1 } else { 0 }; + } + out +} + +/// Split an Annex-B byte stream (start codes `00 00 01` / `00 00 00 01`) into NAL units (escaped payloads). +pub fn annexb_nals(data: &[u8]) -> Vec<&[u8]> { + let mut starts = Vec::new(); + let mut i = 0; + while i + 3 <= data.len() { + if data[i] == 0 && data[i + 1] == 0 && data[i + 2] == 1 { + starts.push(i + 3); + i += 3; + } else { + i += 1; + } + } + let mut out = Vec::with_capacity(starts.len()); + for (k, &s) in starts.iter().enumerate() { + let mut e = if k + 1 < starts.len() { starts[k + 1] - 3 } else { data.len() }; + // trim trailing zero bytes (part of a 4-byte start code or trailing_zero_8bits) + while e > s && data[e - 1] == 0 { + e -= 1; + } + if e > s { + out.push(&data[s..e]); + } + } + out +} + +/// Split a length-prefixed sample (AVCC/HVCC, `length_size` 1 to 4 bytes) into NAL units. +/// Any other `length_size` returns [`BitError::InvalidNalLengthSize`], even for empty data. +pub fn length_prefixed_nals(data: &[u8], length_size: usize) -> Result> { + if !(1..=4).contains(&length_size) { + return Err(BitError::InvalidNalLengthSize); + } + let mut out = Vec::new(); + let mut i = 0; + while i < data.len() { + if length_size > data.len() - i { + return Err(BitError::Eof); + } + let mut len = 0usize; + for k in 0..length_size { + len = (len << 8) | data[i + k] as usize; + } + i += length_size; + if len > data.len() - i { + return Err(BitError::Eof); + } + out.push(&data[i..i + len]); + i += len; + } + Ok(out) +} + +/// CRC-32 (IEEE, reflected) — used by containers (e.g. Matroska CRC-32 elements, PNG). +pub fn crc32(data: &[u8]) -> u32 { + let mut crc = 0xFFFF_FFFFu32; + for &b in data { + crc ^= b as u32; + for _ in 0..8 { + crc = if crc & 1 != 0 { (crc >> 1) ^ 0xEDB8_8320 } else { crc >> 1 }; + } + } + !crc +} + +#[cfg(test)] +mod tests { + use super::*; + use proptest::prelude::*; + + #[test] + fn reads_bits() { + let d = [0b1010_1100, 0b0101_0011]; + let mut r = BitReader::new(&d); + assert_eq!(r.read_bits(1).unwrap(), 1); + assert_eq!(r.read_bits(3).unwrap(), 0b010); + assert_eq!(r.read_bits(8).unwrap(), 0b1100_0101); + assert_eq!(r.bits_left(), 4); + assert_eq!(r.read_bits(5), Err(BitError::Eof)); + } + + #[test] + fn exp_golomb_known() { + // 1 | 010 | 011 | 00100 | 00101 -> 0,1,2,3,4 + let mut w = BitWriter::new(); + for v in 0..5 { + w.write_ue(v); + } + let b = w.finish(); + let mut r = BitReader::new(&b); + for v in 0..5 { + assert_eq!(r.read_ue().unwrap(), v); + } + let mut w = BitWriter::new(); + for v in [0, 1, -1, 2, -2, 1000, -1000] { + w.write_se(v); + } + let b = w.finish(); + let mut r = BitReader::new(&b); + for v in [0, 1, -1, 2, -2, 1000, -1000] { + assert_eq!(r.read_se().unwrap(), v); + } + } + + #[test] + fn signed_exp_golomb_extremes_roundtrip() { + let vals = [0, 1, -1, i32::MAX, i32::MIN]; + let mut w = BitWriter::new(); + for v in vals { + w.write_se(v); + } + let b = w.finish(); + let mut r = BitReader::new(&b); + for v in vals { + assert_eq!(r.read_se(), Ok(v)); + } + } + + #[test] + fn signed_exp_golomb_reads_minimum_from_spec_bits() { + // 32 zero bits, 1, then the 32-bit suffix 1: codeNum = 2^32 -> -2^31. + let bytes = [0, 0, 0, 0, 0x80, 0, 0, 0, 0x80]; + assert_eq!(BitReader::new(&bytes).read_se(), Ok(i32::MIN)); + } + + #[test] + fn signed_exp_golomb_rejects_positive_overflow() { + // 32 zero bits, 1, then 32 zero bits: codeNum = 2^32 - 1 -> +2^31, not an i32. + let bytes = [0, 0, 0, 0, 0x80, 0, 0, 0, 0]; + assert_eq!(BitReader::new(&bytes).read_se(), Err(BitError::InvalidExpGolomb)); + } + + #[test] + fn unsigned_exp_golomb_keeps_u32_range() { + // codeNum = 2^32 is a valid se(v) code but does not fit ue(v)'s u32. + let bytes = [0, 0, 0, 0, 0x80, 0, 0, 0, 0x80]; + assert_eq!(BitReader::new(&bytes).read_ue(), Err(BitError::InvalidExpGolomb)); + } + + #[test] + fn emulation_prevention() { + let raw = [0, 0, 1, 0, 0, 0, 5, 0, 0, 3]; + let esc = escape_rbsp(&raw); + assert_eq!(esc, vec![0, 0, 3, 1, 0, 0, 3, 0, 5, 0, 0, 3, 3]); + assert_eq!(unescape_rbsp(&esc), raw); + } + + /// Verbatim copy of the byte-at-a-time `unescape_rbsp` that this one replaced. + fn old_unescape_rbsp(data: &[u8]) -> Vec { + let mut out = Vec::with_capacity(data.len()); + let mut zeros = 0; + for &b in data { + if zeros >= 2 && b == 3 { + zeros = 0; + continue; + } + out.push(b); + zeros = if b == 0 { zeros + 1 } else { 0 }; + } + out + } + + #[test] + fn unescape_edge_cases() { + let cases: &[(&[u8], &[u8])] = &[ + (&[], &[]), + (&[3], &[3]), + (&[0, 0], &[0, 0]), + (&[0, 0, 3], &[0, 0]), + (&[0, 0, 3, 3], &[0, 0, 3]), + (&[0, 0, 3, 0, 0, 3], &[0, 0, 0, 0]), + (&[0, 0, 0, 3], &[0, 0, 0]), + (&[0, 0, 0, 0, 3, 1], &[0, 0, 0, 0, 1]), + (&[0, 3, 0, 0, 3, 7], &[0, 3, 0, 0, 7]), + (&[1, 0, 0, 3, 3, 0, 0, 3], &[1, 0, 0, 3, 0, 0]), + (&[0, 0, 3, 0, 3], &[0, 0, 0, 3]), + ]; + for (input, want) in cases { + assert_eq!(unescape_rbsp(input), *want, "input {input:?}"); + assert_eq!(old_unescape_rbsp(input), *want, "input {input:?}"); + } + } + + #[test] + fn unescape_matches_the_pre_change_function_on_random_buffers() { + // Fixed-seed xorshift64*, no new dependencies. + let mut state = 0x9E37_79B9_7F4A_7C15u64; + let mut next = move || { + state ^= state >> 12; + state ^= state << 25; + state ^= state >> 27; + (state.wrapping_mul(0x2545_F491_4F6C_DD1D) >> 32) as u32 + }; + for round in 0..20_000u32 { + let len = (next() % 300) as usize; + // Mostly zeros and threes, some small values, some random bytes. + let zero_bias = next() % 4; + let data: Vec = (0..len) + .map(|_| match next() % 8 { + 0..=3 if zero_bias > 0 => 0, + 4 | 5 => 3, + 6 => (next() % 5) as u8, + _ => (next() & 0xFF) as u8, + }) + .collect(); + assert_eq!(unescape_rbsp(&data), old_unescape_rbsp(&data), "round {round}: {data:?}"); + } + } + + #[test] + fn annexb_split() { + let s = [0, 0, 0, 1, 0x67, 1, 2, 0, 0, 1, 0x68, 3, 0, 0, 0, 1, 0x65, 9, 9]; + let n = annexb_nals(&s); + assert_eq!(n, vec![&[0x67, 1, 2][..], &[0x68, 3][..], &[0x65, 9, 9][..]]); + let l = [0, 0, 0, 2, 0x67, 1, 0, 0, 0, 1, 0x68]; + assert_eq!(length_prefixed_nals(&l, 4).unwrap(), vec![&[0x67, 1][..], &[0x68][..]]); + } + + #[test] + fn more_rbsp() { + let d = [0b1100_0000]; + let mut r = BitReader::new(&d); + assert!(r.more_rbsp_data()); + r.read_bit().unwrap(); + assert!(!r.more_rbsp_data()); + } + + #[test] + fn more_rbsp_data_finds_the_stop_bit_before_a_zero_suffix() { + let mut d = vec![0b1010_0000]; + d.resize(1 << 16, 0); + let mut r = BitReader::new(&d); + assert_eq!(r.rbsp_stop, Some(2)); + assert!(r.more_rbsp_data()); + r.skip(2).unwrap(); + assert!(!r.more_rbsp_data()); + assert_eq!(BitReader::new(&[0; 4]).rbsp_stop, None); + assert!(!BitReader::new(&[0; 4]).more_rbsp_data()); + } + + #[test] + fn crc() { + assert_eq!(crc32(b"123456789"), 0xCBF4_3926); + } + + #[test] + fn read_ue_plus_rejects_overflow() { + let mut w = BitWriter::new(); + w.write_ue(7); + w.write_ue(u32::MAX - 1); + w.rbsp_trailing(); + let b = w.finish(); + let mut r = BitReader::new(&b); + assert_eq!(r.read_ue_plus(1).unwrap(), 8); + assert_eq!(r.read_ue_plus(2), Err(BitError::InvalidExpGolomb)); + } + + #[test] + fn length_prefixed_rejects_invalid_width_and_oversized_length() { + for size in [0, 5, 8, usize::MAX] { + assert_eq!(length_prefixed_nals(&[], size), Err(BitError::InvalidNalLengthSize), "size {size}"); + assert_eq!(length_prefixed_nals(&[0; 16], size), Err(BitError::InvalidNalLengthSize), "size {size}"); + } + // `(lengthSizeMinusOne & 3) + 1` can be 3; such samples still split. + assert_eq!(length_prefixed_nals(&[0, 0, 1, 7], 3).unwrap(), vec![&[7u8][..]]); + assert_eq!(length_prefixed_nals(&[0xFF, 0xFF, 0xFF, 0xFF, 1], 4), Err(BitError::Eof)); + assert_eq!(length_prefixed_nals(&[0, 0, 0, 1, 9], 4).unwrap(), vec![&[9u8][..]]); + } + + #[test] + fn widths_above_32_bits_do_not_panic() { + let mut w = BitWriter::new(); + w.write_bits(0xABCD_EF01, 40); + w.write_bits(1, 60); + let b = w.finish(); + assert_eq!(b.len(), 13); + assert_eq!(&b[..5], &[0x00, 0xAB, 0xCD, 0xEF, 0x01]); + let mut r = BitReader::new(&b); + assert_eq!(r.peek(40), 0xABCD_EF01); + assert_eq!(r.read_bits(40).unwrap(), 0xABCD_EF01); + assert_eq!(r.peek(60), 1); + assert_eq!(r.read_bits_u64(60).unwrap(), 1); + assert_eq!(r.bits_left(), 4); + assert_eq!(r.read_bits(40), Err(BitError::Eof)); + } + + #[test] + fn huge_write_width_is_capped_at_64_bits() { + let mut w = BitWriter::new(); + w.write_bits(0xFFFF_FFFF, u32::MAX); + assert_eq!(w.finish(), [0, 0, 0, 0, 0xFF, 0xFF, 0xFF, 0xFF]); + } + + /// Bit `p` of `d`, MSB first, zero past the end. + fn bit_at(d: &[u8], p: usize) -> u32 { + d.get(p / 8).map_or(0, |&b| u32::from(b >> (7 - p % 8)) & 1) + } + + /// Bit-by-bit reference for `peek`: the low 32 bits of the `n`-bit field at `pos`. + fn reference_peek(d: &[u8], pos: usize, n: u32) -> u32 { + let start = pos + n.saturating_sub(32) as usize; + (0..n.min(32) as usize).fold(0, |v, i| (v << 1) | bit_at(d, start + i)) + } + + proptest! { + #[test] + fn peek_and_read_bit_match_a_bitwise_reference(data in proptest::collection::vec(any::(), 0..24)) { + // Every position, including the last 7 bytes (byte loads) and past the end. + for pos in 0..=data.len() * 8 + 9 { + let mut r = BitReader::new(&data); + r.seek_bits(pos); + for n in 0..=40 { + prop_assert_eq!(r.peek(n), reference_peek(&data, pos, n), "pos {} n {}", pos, n); + } + let bit = r.read_bit(); + if pos < data.len() * 8 { + prop_assert_eq!(bit, Ok(bit_at(&data, pos) == 1)); + prop_assert_eq!(r.position(), pos + 1); + } else { + prop_assert_eq!(bit, Err(BitError::Eof)); + prop_assert_eq!(r.position(), pos); + } + } + } + } + + /// The reader as it was before the 8-byte load, kept verbatim as the reference. + struct OldReader<'a> { + data: &'a [u8], + pos: usize, + } + + impl OldReader<'_> { + fn bits_left(&self) -> usize { + self.data.len().saturating_mul(8).saturating_sub(self.pos) + } + fn peek(&self, n: u32) -> u32 { + if n > 32 { + let r = OldReader { data: self.data, pos: self.pos.saturating_add((n - 32) as usize) }; + return r.peek(32); + } + if n == 0 { + return 0; + } + let byte = self.pos / 8; + let shift = self.pos % 8; + let mut v: u64 = 0; + for i in 0..5 { + v = (v << 8) | *self.data.get(byte.saturating_add(i)).unwrap_or(&0) as u64; + } + ((v << (24 + shift)) >> (64 - n)) as u32 + } + fn read_bits(&mut self, n: u32) -> Result { + if n as usize > self.bits_left() { + return Err(BitError::Eof); + } + if n > 32 { + self.pos += (n - 32) as usize; + return self.read_bits(32); + } + let v = self.peek(n); + self.pos += n as usize; + Ok(v) + } + fn read_bit(&mut self) -> Result { + self.read_bits(1).map(|b| b == 1) + } + fn skip(&mut self, n: usize) -> Result<()> { + if n > self.bits_left() { + return Err(BitError::Eof); + } + self.pos += n; + Ok(()) + } + } + + /// Fixed-seed xorshift64*, so the differential test is reproducible. + struct Rng(u64); + + impl Rng { + fn next(&mut self) -> u64 { + self.0 ^= self.0 >> 12; + self.0 ^= self.0 << 25; + self.0 ^= self.0 >> 27; + self.0.wrapping_mul(0x2545_F491_4F6C_DD1D) + } + fn below(&mut self, n: u64) -> u64 { + self.next() % n + } + } + + #[test] + fn reader_matches_the_pre_change_reader_on_random_operations() { + let mut rng = Rng(0x9E37_79B9_7F4A_7C15); + for _ in 0..3000 { + // Lengths cluster around the 8-byte boundary of the fast path; some buffers are zero heavy. + let len = if rng.below(2) == 0 { rng.below(20) } else { rng.below(200) } as usize; + let zero_heavy = rng.below(3) == 0; + let data: Vec = (0..len).map(|_| if zero_heavy && rng.below(4) != 0 { 0 } else { rng.next() as u8 }).collect(); + let mut new = BitReader::new(&data); + let mut old = OldReader { data: &data, pos: 0 }; + for step in 0..200 { + let n = match rng.below(8) { + 0 => [31, 32, 33, 63, 64, 65, u32::MAX][rng.below(7) as usize], + _ => rng.below(33) as u32, + }; + let ctx = format!("len {len} step {step} pos {} n {n}", old.pos); + match rng.below(8) { + 0 | 1 => assert_eq!(new.read_bits(n), old.read_bits(n), "read_bits {ctx}"), + 2 => assert_eq!(new.read_bit(), old.read_bit(), "read_bit {ctx}"), + 3 | 4 => assert_eq!(new.peek(n), old.peek(n), "peek {ctx}"), + 5 => { + let k = [rng.below(70) as usize, len * 8 + rng.below(10) as usize, usize::MAX - rng.below(8) as usize][rng.below(3) as usize]; + assert_eq!(new.skip(k), old.skip(k), "skip {k} {ctx}"); + } + 6 => { + let p = [ + rng.below(len as u64 * 8 + 12) as usize, + len * 8, + len.saturating_sub(7) * 8 + rng.below(8) as usize, + usize::MAX - rng.below(4) as usize, + ][rng.below(4) as usize]; + new.seek_bits(p); + old.pos = p; + } + // `byte_align` itself overflows within 7 bits of `usize::MAX`, before and after this change. + _ if old.pos > usize::MAX - 8 => {} + _ => { + new.byte_align(); + old.pos = old.pos.div_ceil(8) * 8; + } + } + assert_eq!(new.position(), old.pos, "position {ctx}"); + assert_eq!(new.bits_left(), old.bits_left(), "bits_left {ctx}"); + } + } + } + + #[test] + fn peek_and_read_bit_at_the_edges_of_the_fast_path() { + // Exactly 8 bytes: the last position with an 8-byte load is bit 0 of byte 0. + let d: Vec = (1..=9).collect(); + for len in [0, 1, 7, 8, 9] { + let data = &d[..len]; + let end = len * 8; + for pos in [0, 1, 7, 8, end.saturating_sub(64), end.saturating_sub(57), end.saturating_sub(33), end.saturating_sub(1), end, end + 1] { + for n in [0, 1, 7, 8, 31, 32, 33, 40, 64, u32::MAX] { + let mut new = BitReader::new(data); + let mut old = OldReader { data, pos }; + new.seek_bits(pos); + assert_eq!(new.peek(n), old.peek(n), "peek len {len} pos {pos} n {n}"); + assert_eq!(new.read_bits(n), old.read_bits(n), "read_bits len {len} pos {pos} n {n}"); + assert_eq!(new.position(), old.pos); + } + let mut new = BitReader::new(data); + let mut old = OldReader { data, pos }; + new.seek_bits(pos); + assert_eq!(new.read_bit(), old.read_bit(), "read_bit len {len} pos {pos}"); + assert_eq!(new.position(), old.pos); + } + } + // Positions near usize::MAX must neither panic nor read. + let mut r = BitReader::new(&d); + r.seek_bits(usize::MAX); + assert_eq!(r.peek(32), 0); + assert_eq!(r.read_bit(), Err(BitError::Eof)); + assert_eq!(r.position(), usize::MAX); + } + + /// Verbatim copy of the bit-by-bit `read_code_num` that the one-peek version replaced. + fn old_read_code_num(r: &mut BitReader) -> Result { + let mut zeros = 0u32; + while !r.read_bit()? { + zeros += 1; + if zeros > 32 { + return Err(BitError::InvalidExpGolomb); + } + } + if zeros == 0 { + return Ok(0); + } + let v = r.read_bits_u64(zeros)?; + Ok((1u64 << zeros) - 1 + v) + } + + fn old_read_ue(r: &mut BitReader) -> Result { + u32::try_from(old_read_code_num(r)?).map_err(|_| BitError::InvalidExpGolomb) + } + + fn old_read_se(r: &mut BitReader) -> Result { + let k = old_read_code_num(r)? as i64; + let v = if k & 1 == 1 { (k + 1) / 2 } else { -(k / 2) }; + i32::try_from(v).map_err(|_| BitError::InvalidExpGolomb) + } + + /// Verbatim copy of the `write_ue` / `write_code_num` before the one-call version. + fn old_write_code_num(w: &mut BitWriter, v: u64) { + let x = v + 1; + let len = 64 - x.leading_zeros(); + let zeros = len - 1; + for _ in 0..zeros { + w.write_bit(false); + } + if len > 32 { + w.write_bits((x >> 32) as u32, len - 32); + w.write_bits(x as u32, 32); + } else { + w.write_bits(x as u32, len); + } + } + + #[test] + fn exp_golomb_reader_matches_the_pre_change_reader() { + let mut rng = Rng(0xD1B5_4A32_D192_ED03); + for round in 0..20_000u32 { + let len = rng.below(17) as usize; + let mut data: Vec = (0..len).map(|_| rng.next() as u8).collect(); + if round % 2 == 0 && len > 0 { + // A zero run of 28..=40 bits, then a one bit, somewhere in the buffer. + let start = rng.below(len as u64 * 8) as usize; + let zeros = 28 + rng.below(13) as usize; + for p in start..(start + zeros + 1).min(len * 8) { + data[p / 8] &= !(0x80 >> (p % 8)); + } + if start + zeros < len * 8 { + let p = start + zeros; + data[p / 8] |= 0x80 >> (p % 8); + } + } + // Every start position, including the last bits and past the end. + for pos in 0..=len * 8 + 2 { + let mut old = BitReader::new(&data); + let mut new = BitReader::new(&data); + old.seek_bits(pos); + new.seek_bits(pos); + // Several codes in a row, so the position after each result is checked too. + for step in 0..4 { + if (round + step) % 2 == 0 { + assert_eq!(new.read_ue(), old_read_ue(&mut old), "ue {data:02x?} pos {pos} step {step}"); + } else { + assert_eq!(new.read_se(), old_read_se(&mut old), "se {data:02x?} pos {pos} step {step}"); + } + assert_eq!(new.position(), old.position(), "position {data:02x?} pos {pos} step {step}"); + assert_eq!(new.bits_left(), old.bits_left()); + } + } + } + } + + #[test] + fn exp_golomb_reader_edge_codes() { + // 31-bit (15 zeros) and 32-bit (16 zeros) codes, 33-bit-wide codes, and 32 or 33 zeros. + for zeros in 0..=34usize { + for extra in 0..4usize { + let total = (2 * zeros + 1 + extra).div_ceil(8) * 8; + let mut data = vec![0u8; total / 8]; + data[zeros / 8] |= 0x80 >> (zeros % 8); + for tail in [0u8, 0xFF] { + let mut d = data.clone(); + for p in 2 * zeros + 1..total { + if tail != 0 { + d[p / 8] |= 0x80 >> (p % 8); + } + } + for cut in [d.len(), d.len().saturating_sub(1)] { + let d = &d[..cut]; + let (mut o, mut n) = (BitReader::new(d), BitReader::new(d)); + assert_eq!(n.read_ue(), old_read_ue(&mut o), "ue zeros {zeros} cut {cut}"); + assert_eq!(n.position(), o.position()); + let (mut o, mut n) = (BitReader::new(d), BitReader::new(d)); + assert_eq!(n.read_se(), old_read_se(&mut o), "se zeros {zeros} cut {cut}"); + assert_eq!(n.position(), o.position()); + } + } + } + } + } + + #[test] + fn write_ue_matches_the_pre_change_writer() { + let mut rng = Rng(0x1234_5678_9ABC_DEF1); + let mut values: Vec = vec![0, 1, 2, 3, 6, 7, 8, 65534, 65535, 65536, u32::MAX - 1, u32::MAX]; + values.extend((0..32).flat_map(|b| [(1u32 << b) - 1, 1 << b, (1u32 << b) + 1])); + values.extend((0..5000).map(|_| (rng.next() as u32) >> rng.below(32))); + for (i, &v) in values.iter().enumerate() { + for lead in [0u32, 1, 3, 7] { + let mut new = BitWriter::new(); + let mut old = BitWriter::new(); + new.write_bits(0x55, lead); + old.write_bits(0x55, lead); + new.write_ue(v); + old_write_code_num(&mut old, u64::from(v)); + assert_eq!(new.bit_len(), old.bit_len(), "value {v} lead {lead} (#{i})"); + assert_eq!(new.finish(), old.finish(), "value {v} lead {lead} (#{i})"); + } + } + // write_se goes through the same code with codeNum 2^32 at i32::MIN. + for v in [0, 1, -1, 2, -2, i32::MAX, i32::MIN, i32::MIN + 1] { + let mut new = BitWriter::new(); + new.write_se(v); + new.rbsp_trailing(); + let b = new.finish(); + assert_eq!(BitReader::new(&b).read_se(), Ok(v)); + } + } + + proptest! { + #[test] + fn roundtrip(vals in proptest::collection::vec((0u32..u32::MAX, 1u32..=32), 0..200), ues in proptest::collection::vec(0u32..u32::MAX - 1, 0..50)) { + let mut w = BitWriter::new(); + for &(v, n) in &vals { w.write_bits(v, n); } + for &u in &ues { w.write_ue(u); } + let b = w.finish(); + let mut r = BitReader::new(&b); + for &(v, n) in &vals { + let mask = if n == 32 { u32::MAX } else { (1 << n) - 1 }; + prop_assert_eq!(r.read_bits(n).unwrap(), v & mask); + } + for &u in &ues { prop_assert_eq!(r.read_ue().unwrap(), u); } + } + + #[test] + fn escape_roundtrip(data in proptest::collection::vec(0u8..4, 0..300)) { + let e = escape_rbsp(&data); + prop_assert_eq!(unescape_rbsp(&e), data); + for w in e.windows(3) { prop_assert!(!(w[0] == 0 && w[1] == 0 && w[2] < 3)); } + } + } +} diff --git a/crates/media/src/id.rs b/crates/media/src/id.rs new file mode 100644 index 000000000..00b63d004 --- /dev/null +++ b/crates/media/src/id.rs @@ -0,0 +1,389 @@ +//! Container and codec identifiers and codec parameters shared by the codec crates (craft-audio, +//! and the video crate to come), so a file's container and codec are named the same way +//! everywhere, and a codec is configured the same way whatever container its track came from. +//! +//! Both enums are `#[non_exhaustive]`: new formats are added as minor changes, so a `match` on them +//! needs a `_` arm. + +#![warn(missing_docs)] + +/// The file or stream format that holds the codec data. +#[non_exhaustive] +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] +pub enum Container { + /// RIFF WAVE, including BWF and RF64/BW64. + Wav, + /// AIFF and AIFF-C. + Aiff, + /// A native FLAC stream (`fLaC`). + Flac, + /// ISO base media file format: MP4, M4A, M4B. + Mp4, + /// QuickTime (MOV). + QuickTime, + /// Matroska (MKV, MKA). + Matroska, + /// WebM (the Matroska subset). + WebM, + /// Ogg. + Ogg, + /// Apple Core Audio Format. + Caf, + /// A raw ADTS AAC stream. + Adts, + /// A raw MPEG audio stream (MP1, MP2 or MP3 frames, optionally behind ID3v2 tags). + MpegAudio, + /// A raw AC-3 or E-AC-3 stream. + Ac3, + /// AVI (RIFF), including OpenDML. + Avi, + /// MXF (SMPTE ST 377-1): OP1a, OP-Atom. + Mxf, + /// MPEG-2 transport stream (TS, M2TS). + MpegTs, + /// MPEG-1/2 program stream (MPG, VOB). + MpegPs, +} + +impl Container { + /// A short display name: `"WAV"`, `"MP4"`, `"Matroska"`. + pub fn name(self) -> &'static str { + match self { + Container::Wav => "WAV", + Container::Aiff => "AIFF", + Container::Flac => "FLAC", + Container::Mp4 => "MP4", + Container::QuickTime => "QuickTime", + Container::Matroska => "Matroska", + Container::WebM => "WebM", + Container::Ogg => "Ogg", + Container::Caf => "CAF", + Container::Adts => "ADTS", + Container::MpegAudio => "MPEG audio", + Container::Ac3 => "AC-3", + Container::Avi => "AVI", + Container::Mxf => "MXF", + Container::MpegTs => "MPEG-TS", + Container::MpegPs => "MPEG-PS", + } + } +} + +/// A codec, audio or video. +#[non_exhaustive] +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] +pub enum CodecId { + /// Uncompressed PCM, integer or float. + Pcm, + /// ADPCM (IMA, Microsoft, G.722, G.726). + Adpcm, + /// G.711 A-law. + ALaw, + /// G.711 µ-law. + MuLaw, + /// FLAC. + Flac, + /// Apple Lossless. + Alac, + /// AAC (LC). Containers report every AAC stream as `Aac`; a decoder that finds spectral band + /// replication reports [`CodecId::HeAac`]. + Aac, + /// HE-AAC (AAC with spectral band replication, v1 or v2). + HeAac, + /// MPEG-1/2 Audio Layer I. + Mp1, + /// MPEG-1/2 Audio Layer II. + Mp2, + /// MPEG-1/2 Audio Layer III. + Mp3, + /// AC-3 (Dolby Digital). + Ac3, + /// E-AC-3 (Dolby Digital Plus). + Eac3, + /// Opus. + Opus, + /// Vorbis. + Vorbis, + /// Speex. + Speex, + /// H.264 / AVC. + H264, + /// H.265 / HEVC. + Hevc, + /// AV1. + Av1, + /// VP8. + Vp8, + /// VP9. + Vp9, + /// Apple ProRes. + ProRes, + /// Motion JPEG. + Mjpeg, + /// MPEG-2 video. + Mpeg2Video, + /// MPEG-4 Part 2 video. + Mpeg4Video, + /// Theora. + Theora, + /// Avid DNxHD / DNxHR. + Dnxhd, + /// APV (Advanced Professional Video). + Apv, + /// A codec this crate has no identifier for. + Unknown, +} + +impl CodecId { + /// A short display name: `"AAC"`, `"HE-AAC"`, `"E-AC-3"`, `"H.264"`. + pub fn name(self) -> &'static str { + match self { + CodecId::Pcm => "PCM", + CodecId::Adpcm => "ADPCM", + CodecId::ALaw => "A-law", + CodecId::MuLaw => "µ-law", + CodecId::Flac => "FLAC", + CodecId::Alac => "ALAC", + CodecId::Aac => "AAC", + CodecId::HeAac => "HE-AAC", + CodecId::Mp1 => "MP1", + CodecId::Mp2 => "MP2", + CodecId::Mp3 => "MP3", + CodecId::Ac3 => "AC-3", + CodecId::Eac3 => "E-AC-3", + CodecId::Opus => "Opus", + CodecId::Vorbis => "Vorbis", + CodecId::Speex => "Speex", + CodecId::H264 => "H.264", + CodecId::Hevc => "HEVC", + CodecId::Av1 => "AV1", + CodecId::Vp8 => "VP8", + CodecId::Vp9 => "VP9", + CodecId::ProRes => "ProRes", + CodecId::Mjpeg => "Motion JPEG", + CodecId::Mpeg2Video => "MPEG-2", + CodecId::Mpeg4Video => "MPEG-4", + CodecId::Theora => "Theora", + CodecId::Dnxhd => "DNxHD", + CodecId::Apv => "APV", + CodecId::Unknown => "unknown", + } + } + + /// Whether this is an audio codec. + pub fn is_audio(self) -> bool { + matches!( + self, + CodecId::Pcm + | CodecId::Adpcm + | CodecId::ALaw + | CodecId::MuLaw + | CodecId::Flac + | CodecId::Alac + | CodecId::Aac + | CodecId::HeAac + | CodecId::Mp1 + | CodecId::Mp2 + | CodecId::Mp3 + | CodecId::Ac3 + | CodecId::Eac3 + | CodecId::Opus + | CodecId::Vorbis + | CodecId::Speex + ) + } + + /// Whether this is a video codec. + pub fn is_video(self) -> bool { + matches!( + self, + CodecId::H264 + | CodecId::Hevc + | CodecId::Av1 + | CodecId::Vp8 + | CodecId::Vp9 + | CodecId::ProRes + | CodecId::Mjpeg + | CodecId::Mpeg2Video + | CodecId::Mpeg4Video + | CodecId::Theora + | CodecId::Dnxhd + | CodecId::Apv + ) + } +} + +/// The layout of uncompressed PCM samples. +#[non_exhaustive] +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] +pub struct PcmFormat { + /// Bits per sample (8, 16, 24, 32 for integers; 32 or 64 for floats). + pub bits: u16, + /// IEEE float samples. + pub float: bool, + /// Big-endian byte order. + pub big_endian: bool, + /// Signed integers (8-bit WAV and `raw ` QuickTime PCM are unsigned). + pub signed: bool, +} + +impl PcmFormat { + /// Integer samples of `bits` bits. + pub fn int(bits: u16, signed: bool, big_endian: bool) -> PcmFormat { + PcmFormat { bits, float: false, big_endian, signed } + } + + /// IEEE float samples of `bits` bits (32 or 64). + pub fn float(bits: u16, big_endian: bool) -> PcmFormat { + PcmFormat { bits, float: true, big_endian, signed: true } + } +} + +/// What a decoder needs to know about a track, whatever container it came from. +/// +/// `extradata` is the codec configuration in Matroska's `CodecPrivate` form, which ffmpeg's +/// extradata also follows: +/// +/// | Codec | `extradata` | +/// |---|---| +/// | AAC | `AudioSpecificConfig` | +/// | Opus | the `OpusHead` identification header (RFC 7845 §5.1) | +/// | Vorbis, Theora | the three headers, Xiph-laced | +/// | Speex | the Speex header | +/// | FLAC | `fLaC` followed by the metadata blocks (STREAMINFO first) | +/// | ALAC | the magic cookie (`ALACSpecificConfig`) | +/// | AC-3 / E-AC-3 | the MP4 `dac3` / `dec3` payload, or empty | +/// | MP1/MP2/MP3, PCM | empty | +/// | H.264 / HEVC / AV1 | the `avcC` / `hvcC` / `av1C` record | +/// | VP9 | the MP4 `vpcC` payload, or Matroska's codec feature metadata | +/// | APV | the `apvC` record | +/// +/// `sample_rate` and `channels` are what the container declares (for HE-AAC with implicit +/// signalling, usually the core rate), except that Opus is always 48 kHz, the rate it decodes at; +/// `width` and `height` are the coded picture size of a video +/// track. `tag` is the container's four-character code for the codec when it has one (the MP4 +/// sample entry format, Matroska's ProRes or VfW FourCC), which is how a ProRes profile (`apcn`, +/// `ap4h`, …) or a DNx variant is told apart. +/// +/// `#[non_exhaustive]`: build it with [`CodecParams::new`] and the `with_*` methods. +#[non_exhaustive] +#[derive(Debug, Clone, PartialEq, Eq)] +#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] +pub struct CodecParams { + /// The codec. + pub codec: CodecId, + /// The codec configuration (see the table above). + pub extradata: Vec, + /// The container's four-character code for the codec, if it has one. + pub tag: Option<[u8; 4]>, + /// Audio: samples per second. + pub sample_rate: Option, + /// Audio: channel count. + pub channels: Option, + /// Audio: the sample layout of uncompressed PCM. + pub pcm: Option, + /// Video: coded picture width in pixels. + pub width: Option, + /// Video: coded picture height in pixels. + pub height: Option, +} + +impl CodecParams { + /// Parameters for `codec`, with nothing else known yet. + pub fn new(codec: CodecId) -> CodecParams { + CodecParams { codec, extradata: Vec::new(), tag: None, sample_rate: None, channels: None, pcm: None, width: None, height: None } + } + + /// Sets `tag`. + pub fn with_tag(mut self, tag: [u8; 4]) -> CodecParams { + self.tag = Some(tag); + self + } + + /// The coded picture size; a zero dimension leaves both unknown. + pub fn with_size(mut self, width: u32, height: u32) -> CodecParams { + (self.width, self.height) = if width > 0 && height > 0 { (Some(width), Some(height)) } else { (None, None) }; + self + } + + /// Sets `extradata`. + pub fn with_extradata(mut self, extradata: impl Into>) -> CodecParams { + self.extradata = extradata.into(); + self + } + + /// Sets `sample_rate`; 0 leaves it unknown. + pub fn with_sample_rate(mut self, sample_rate: u32) -> CodecParams { + self.sample_rate = (sample_rate > 0).then_some(sample_rate); + self + } + + /// Sets `channels`; 0 leaves it unknown. + pub fn with_channels(mut self, channels: u16) -> CodecParams { + self.channels = (channels > 0).then_some(channels); + self + } + + /// Sets `pcm`. + pub fn with_pcm(mut self, pcm: PcmFormat) -> CodecParams { + self.pcm = Some(pcm); + self + } +} + +/// Xiph lacing of `packets` (Matroska `CodecPrivate` for Vorbis): the count less one, each +/// length but the last as a run of 255s and a remainder, then the packets. `None` for no packets +/// or more than 256, which the one-byte count cannot hold. +pub fn xiph_lace(packets: &[Vec]) -> Option> { + let mut out = vec![u8::try_from(packets.len().checked_sub(1)?).ok()?]; + for p in packets.iter().take(packets.len().saturating_sub(1)) { + let mut n = p.len(); + while n >= 255 { + out.push(255); + n -= 255; + } + out.push(n as u8); + } + for p in packets { + out.extend_from_slice(p); + } + Some(out) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn audio_and_video_are_disjoint() { + for c in [CodecId::Aac, CodecId::Opus, CodecId::Pcm, CodecId::Eac3, CodecId::Speex] { + assert!(c.is_audio() && !c.is_video(), "{c:?}"); + } + for c in [CodecId::H264, CodecId::Av1, CodecId::ProRes, CodecId::Theora, CodecId::Dnxhd, CodecId::Apv] { + assert!(c.is_video() && !c.is_audio(), "{c:?}"); + } + assert!(!CodecId::Unknown.is_audio() && !CodecId::Unknown.is_video()); + } + + #[test] + fn params_builder() { + let p = CodecParams::new(CodecId::Aac).with_extradata([0x12, 0x10]).with_sample_rate(48_000).with_channels(2).with_sample_rate(0); + assert_eq!((p.codec, p.extradata.as_slice(), p.sample_rate, p.channels), (CodecId::Aac, &[0x12, 0x10][..], None, Some(2))); + let v = CodecParams::new(CodecId::ProRes).with_tag(*b"apcn").with_size(1920, 1080); + assert_eq!((v.tag, v.width, v.height), (Some(*b"apcn"), Some(1920), Some(1080))); + assert_eq!(v.with_size(0, 1080).width, None); + } + + #[test] + fn xiph_lacing() { + let laced = xiph_lace(&[vec![1; 30], vec![2; 300], vec![3; 5]]).unwrap(); + assert_eq!(&laced[..4], &[2, 30, 255, 45]); + assert_eq!(laced.len(), 4 + 335); + assert_eq!(xiph_lace(&[]), None); + assert_eq!(xiph_lace(&vec![vec![0]; 257]), None); + assert!(xiph_lace(&vec![vec![0]; 256]).is_some()); + } +} diff --git a/crates/media/src/isobmff/boxes.rs b/crates/media/src/isobmff/boxes.rs new file mode 100644 index 000000000..a4135248e --- /dev/null +++ b/crates/media/src/isobmff/boxes.rs @@ -0,0 +1,480 @@ +//! Box-level access to ISO BMFF data: a box header parser, an iterator over the boxes in a byte +//! slice, and a bounds-checked big-endian [`Reader`] for box payloads. +//! +//! The same box format is used by MP4, QuickTime, HEIF/AVIF, CR3, JPEG 2000 (JP2, JPX, JPM, MJ2) +//! and 3GP. Use this module to read boxes that [`open`](super::open) does not model, such as +//! `uuid` boxes or HEIF `meta` items. +//! +//! ``` +//! use craft_media::isobmff::boxes::{BoxIter, Reader}; +//! +//! // `ftyp` with major brand `crx `, then a `uuid` box with one child. +//! let mut file = vec![0, 0, 0, 16, b'f', b't', b'y', b'p', b'c', b'r', b'x', b' ', 0, 0, 0, 1]; +//! file.extend_from_slice(&[0, 0, 0, 36, b'u', b'u', b'i', b'd']); +//! file.extend_from_slice(&[0x85; 16]); +//! file.extend_from_slice(&[0, 0, 0, 12, b'C', b'M', b'T', b'1', 1, 2, 3, 4]); +//! +//! for b in BoxIter::new(&file) { +//! let b = b?; +//! if b.kind == b"ftyp" { +//! assert_eq!(Reader::new(b.payload).fourcc()?, b"crx "); +//! } +//! if b.kind == b"uuid" && b.user_type == Some([0x85; 16]) { +//! // Iterate the children in place; offsets stay relative to `file`. +//! for c in BoxIter::within(&file, b.payload_range()) { +//! let c = c?; +//! assert_eq!((c.kind, c.offset, c.payload), (b"CMT1".into(), 40, &[1u8, 2, 3, 4][..])); +//! } +//! } +//! } +//! # Ok::<(), craft_media::isobmff::Error>(()) +//! ``` +//! +//! Nothing here recurses. A caller that walks nested boxes bounds its own depth and box count. + +use crate::isobmff::bytes::FourCc; +use crate::isobmff::error::{Error, Result}; +use std::ops::Range; + +/// Bounds-checked big-endian cursor over a byte slice. +/// +/// Every read checks the remaining length and returns [`Error::Truncated`] with the reader's label +/// when the data ends early. A failed read leaves the position unchanged. +#[derive(Clone, Debug)] +pub struct Reader<'a> { + data: &'a [u8], + pos: usize, + what: &'static str, +} + +impl<'a> Reader<'a> { + /// A reader at the start of `data`. Errors name the data `"box payload"`. + pub fn new(data: &'a [u8]) -> Self { + Self::labeled(data, "box payload") + } + /// A reader whose [`Error::Truncated`] errors name the data `what`. + pub fn labeled(data: &'a [u8], what: &'static str) -> Self { + Reader { data, pos: 0, what } + } + /// The whole slice the reader was created with. + pub fn data(&self) -> &'a [u8] { + self.data + } + /// Bytes read so far. + pub fn position(&self) -> usize { + self.pos + } + /// Bytes left to read. + pub fn remaining(&self) -> usize { + self.data.len().saturating_sub(self.pos) + } + /// True when no bytes are left. + pub fn is_empty(&self) -> bool { + self.remaining() == 0 + } + /// The unread bytes, without consuming them. + pub fn rest(&self) -> &'a [u8] { + self.data.get(self.pos..).unwrap_or(&[]) + } + /// Read `n` bytes. + pub fn bytes(&mut self, n: usize) -> Result<&'a [u8]> { + let end = self.pos.checked_add(n).ok_or(Error::Truncated(self.what))?; + let s = self.data.get(self.pos..end).ok_or(Error::Truncated(self.what))?; + self.pos = end; + Ok(s) + } + /// Skip `n` bytes. + pub fn skip(&mut self, n: usize) -> Result<()> { + self.bytes(n).map(|_| ()) + } + /// Read `N` bytes into an array. + pub fn array(&mut self) -> Result<[u8; N]> { + let s = self.bytes(N)?; + let mut a = [0u8; N]; + a.copy_from_slice(s); + Ok(a) + } + pub fn u8(&mut self) -> Result { + let [b] = self.array::<1>()?; + Ok(b) + } + pub fn u16(&mut self) -> Result { + Ok(u16::from_be_bytes(self.array()?)) + } + pub fn i16(&mut self) -> Result { + Ok(i16::from_be_bytes(self.array()?)) + } + pub fn u24(&mut self) -> Result { + let [a, b, c] = self.array::<3>()?; + Ok(u32::from_be_bytes([0, a, b, c])) + } + pub fn u32(&mut self) -> Result { + Ok(u32::from_be_bytes(self.array()?)) + } + pub fn i32(&mut self) -> Result { + Ok(i32::from_be_bytes(self.array()?)) + } + pub fn u64(&mut self) -> Result { + Ok(u64::from_be_bytes(self.array()?)) + } + pub fn i64(&mut self) -> Result { + Ok(i64::from_be_bytes(self.array()?)) + } + pub fn f64(&mut self) -> Result { + Ok(f64::from_be_bytes(self.array()?)) + } + pub fn fourcc(&mut self) -> Result { + Ok(FourCc(self.array()?)) + } + /// Full-box header: `(version, flags)`. + pub fn full_header(&mut self) -> Result<(u8, u32)> { + let v = self.u32()?; + Ok(((v >> 24) as u8, v & 0x00FF_FFFF)) + } + /// Read a 32-bit entry count and check that `count * entry_size` bytes remain, so a hostile + /// count cannot drive a large allocation. + pub fn count(&mut self, entry_size: usize) -> Result { + let n = self.u32()? as usize; + self.check_count(n, entry_size)?; + Ok(n) + } + /// Check that `n * entry_size` bytes remain. + pub fn check_count(&self, n: usize, entry_size: usize) -> Result<()> { + match n.checked_mul(entry_size) { + Some(b) if b <= self.remaining() => Ok(()), + _ => Err(Error::Truncated(self.what)), + } + } +} + +/// The header of one box. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +#[non_exhaustive] +pub struct BoxHeader { + /// Box type. + pub kind: FourCc, + /// Header length in bytes: 8, plus 8 for a 64-bit `largesize`, plus 16 for a `uuid` user type. + pub header_len: u64, + /// Total box size including the header. `None` for a size field of 0: the box runs to the end + /// of its container (or of the file at top level). + pub size: Option, + /// The 16-byte extended type of a `uuid` box. + pub user_type: Option<[u8; 16]>, +} + +impl BoxHeader { + /// The longest possible header: size, type, `largesize` and a `uuid` user type. + pub const MAX_LEN: usize = 32; + + /// Parse a box header from the start of `buf`. Pass at least [`MAX_LEN`](Self::MAX_LEN) bytes + /// when that many are available; fewer are enough for headers without `largesize` or a user + /// type. + /// + /// Errors: [`Error::Truncated`] when `buf` ends inside the header, [`Error::Invalid`] when the + /// declared size is smaller than the header. + pub fn parse(buf: &[u8]) -> Result { + let mut c = Reader::labeled(buf, "box header"); + let size32 = c.u32()?; + let kind = c.fourcc()?; + let mut header_len = 8u64; + let size = match size32 { + 0 => None, + 1 => { + header_len += 8; + Some(c.u64()?) + } + s => Some(u64::from(s)), + }; + let user_type = if kind == b"uuid" { + header_len += 16; + Some(c.array::<16>()?) + } else { + None + }; + if let Some(s) = size + && s < header_len + { + return Err(Error::Invalid(format!("box '{kind}' size {s} smaller than its header"))); + } + Ok(BoxHeader { kind, header_len, size, user_type }) + } + + /// Payload size (box size minus header), or `None` when the box runs to the end. + pub fn payload_size(&self) -> Option { + self.size.map(|s| s.saturating_sub(self.header_len)) + } +} + +/// One box found by [`BoxIter`]. Offsets are relative to the slice the iterator was created with. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +#[non_exhaustive] +pub struct BoxRef<'a> { + /// Box type. + pub kind: FourCc, + /// The 16-byte extended type of a `uuid` box. The payload starts after it. + pub user_type: Option<[u8; 16]>, + /// Offset of the box's first header byte. + pub offset: usize, + /// Header length in bytes, including `largesize` and the `uuid` user type. + pub header_len: usize, + /// The box contents after the header. + pub payload: &'a [u8], + /// The size field was 0, so the box runs to the end of the iterated range. + pub extends_to_end: bool, + /// The declared size went past the end of the range and the payload was cut there. Only + /// [`BoxIter::allow_truncated`] produces this. + pub truncated: bool, +} + +impl BoxRef<'_> { + /// Offset one past the box's last byte (where the next sibling starts). + pub fn end(&self) -> usize { + self.offset.saturating_add(self.header_len).saturating_add(self.payload.len()) + } + /// The byte range of the whole box, header included. + pub fn range(&self) -> Range { + self.offset..self.end() + } + /// The byte range of the payload. + pub fn payload_range(&self) -> Range { + self.offset.saturating_add(self.header_len)..self.end() + } +} + +/// Iterator over the sibling boxes in a byte range. +/// +/// Yields each complete box in order. A malformed header or a box larger than the remaining range +/// yields one `Err` and ends the iteration, so the iterator always terminates and never reads +/// outside the range. Fewer than 8 trailing bytes that are all zero (the QuickTime 32-bit +/// terminator) end the iteration silently; other short trailing data is an error. +#[derive(Clone, Debug)] +pub struct BoxIter<'a> { + data: &'a [u8], + pos: usize, + end: usize, + allow_truncated: bool, + done: bool, +} + +impl<'a> BoxIter<'a> { + /// Iterate the boxes in all of `data`. + pub fn new(data: &'a [u8]) -> Self { + Self::within(data, 0..data.len()) + } + + /// Iterate the boxes in `data[range]`, reporting offsets relative to `data`. Use it to walk + /// into a box's [`payload_range`](BoxRef::payload_range) (or a part of it, after a full-box + /// header or a sample entry's fixed fields) and keep file offsets. A range that reaches past + /// `data` is cut at its end. + pub fn within(data: &'a [u8], range: Range) -> Self { + let end = range.end.min(data.len()); + let pos = range.start.min(end); + BoxIter { data, pos, end, allow_truncated: false, done: false } + } + + /// Accept a last box whose declared size runs past the end of the range: it is yielded with + /// the payload cut at the end and [`BoxRef::truncated`] set, and the iteration ends. For + /// partially downloaded or cut files. + pub fn allow_truncated(mut self) -> Self { + self.allow_truncated = true; + self + } + + /// Offset where the next box would start, relative to the iterated slice. + pub fn offset(&self) -> usize { + self.pos + } + + fn step(&mut self) -> Option>> { + let rest = self.data.get(self.pos..self.end).unwrap_or(&[]); + if rest.is_empty() { + return None; + } + if rest.len() < 8 { + if rest.iter().all(|&b| b == 0) { + return None; + } + return Some(Err(Error::Truncated("box header"))); + } + let h = match BoxHeader::parse(rest) { + Ok(h) => h, + Err(e) => return Some(Err(e)), + }; + let avail = rest.len() as u64; + let (size, truncated) = match h.size { + None => (avail, false), + Some(s) if s <= avail => (s, false), + Some(_) if self.allow_truncated => (avail, true), + Some(s) => { + return Some(Err(Error::Invalid(format!("box '{}' size {s} exceeds its container ({avail} bytes left)", h.kind)))); + } + }; + // `size <= rest.len()` and `header_len <= size` (or the header could not have parsed from + // `rest`), so both fit in usize. + let (size, header_len) = (size as usize, h.header_len as usize); + let payload = rest.get(header_len..size)?; + let b = BoxRef { kind: h.kind, user_type: h.user_type, offset: self.pos, header_len, payload, extends_to_end: h.size.is_none(), truncated }; + self.pos += size; + if truncated { + self.done = true; + } + Some(Ok(b)) + } +} + +impl<'a> Iterator for BoxIter<'a> { + type Item = Result>; + fn next(&mut self) -> Option { + if self.done { + return None; + } + let item = self.step(); + if !matches!(item, Some(Ok(_))) { + self.done = true; + } + item + } +} + +impl std::iter::FusedIterator for BoxIter<'_> {} + +/// Iterate the boxes in all of `data`; the same as [`BoxIter::new`]. +pub fn boxes(data: &[u8]) -> BoxIter<'_> { + BoxIter::new(data) +} + +/// The payload of the first box of type `kind` in `data`. Boxes after a malformed one are not +/// searched. +pub fn find<'a>(data: &'a [u8], kind: &[u8; 4]) -> Option<&'a [u8]> { + boxes(data).map_while(|b| b.ok()).find(|b| b.kind == kind).map(|b| b.payload) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::isobmff::bytes::BoxBuf; + + fn bx(kind: &[u8; 4], payload: &[u8]) -> Vec { + let mut v = ((payload.len() + 8) as u32).to_be_bytes().to_vec(); + v.extend_from_slice(kind); + v.extend_from_slice(payload); + v + } + + #[test] + fn header_forms() { + let h = BoxHeader::parse(&[0, 0, 0, 16, b'f', b'r', b'e', b'e']).unwrap(); + assert_eq!((h.kind, h.header_len, h.size, h.payload_size()), (FourCc(*b"free"), 8, Some(16), Some(8))); + let h = BoxHeader::parse(&[0, 0, 0, 0, b'm', b'd', b'a', b't']).unwrap(); + assert_eq!((h.size, h.payload_size()), (None, None)); + let mut v = vec![0, 0, 0, 1, b'm', b'd', b'a', b't']; + v.extend_from_slice(&100u64.to_be_bytes()); + let h = BoxHeader::parse(&v).unwrap(); + assert_eq!((h.header_len, h.size), (16, Some(100))); + let mut v = vec![0, 0, 0, 30, b'u', b'u', b'i', b'd']; + v.extend_from_slice(&[7u8; 16]); + let h = BoxHeader::parse(&v).unwrap(); + assert_eq!((h.header_len, h.user_type), (24, Some([7u8; 16]))); + assert!(BoxHeader::parse(&[0, 0, 0, 4, b'f', b'r', b'e', b'e']).is_err()); + assert!(BoxHeader::parse(&[0, 0, 0]).is_err()); + // A uuid box whose size does not cover its user type. + let mut v = vec![0, 0, 0, 20, b'u', b'u', b'i', b'd']; + v.extend_from_slice(&[7u8; 16]); + assert!(BoxHeader::parse(&v).is_err()); + } + + #[test] + fn iterate_children() { + let mut b = BoxBuf::new(); + b.leaf(b"aaaa", &[1, 2]); + let m = b.start(b"bbbb"); + b.leaf(b"cccc", &[]); + b.end(m); + b.u32(0); // QT terminator + let kids: Vec<_> = boxes(&b.buf).collect::>>().unwrap(); + assert_eq!(kids.len(), 2); + assert_eq!(kids[0].payload, &[1, 2]); + assert_eq!((kids[1].offset, kids[1].payload_range(), kids[1].range()), (10, 18..26, 10..26)); + assert_eq!(find(&b.buf, b"bbbb").map(|p| p.len()), Some(8)); + let inner: Vec<_> = BoxIter::within(&b.buf, kids[1].payload_range()).map(|r| r.unwrap().offset).collect(); + assert_eq!(inner, [18]); + // Oversized child → one error, then the iterator stops. + let bad = [0u8, 0, 0, 99, b'x', b'x', b'x', b'x', 0]; + let mut it = boxes(&bad); + assert!(it.next().unwrap().is_err()); + assert!(it.next().is_none()); + } + + #[test] + fn large_size_zero_size_and_uuid() { + let mut large = vec![0, 0, 0, 1, b'm', b'd', b'a', b't']; + large.extend_from_slice(&19u64.to_be_bytes()); + large.extend_from_slice(&[9, 9, 9]); + let mut uuid = vec![0, 0, 0, 26, b'u', b'u', b'i', b'd']; + uuid.extend_from_slice(&[0xAB; 16]); + uuid.extend_from_slice(&[1, 2]); + let tail = [0, 0, 0, 0, b'm', b'd', b'a', b't', 5, 6, 7]; + let file = [large, uuid, tail.to_vec()].concat(); + let all: Vec<_> = boxes(&file).collect::>>().unwrap(); + assert_eq!(all.len(), 3); + assert_eq!((all[0].header_len, all[0].payload), (16, &[9u8, 9, 9][..])); + assert_eq!((all[1].user_type, all[1].header_len, all[1].payload), (Some([0xAB; 16]), 24, &[1u8, 2][..])); + assert_eq!((all[2].offset, all[2].extends_to_end, all[2].payload), (45, true, &[5u8, 6, 7][..])); + // Size 0 inside a range runs to the end of the range, not of the slice. + let in_range: Vec<_> = BoxIter::within(&file, 45..53).map(|r| r.unwrap().payload.len()).collect(); + assert_eq!(in_range, [0]); + } + + #[test] + fn truncated_last_box() { + let mut file = bx(b"ftyp", b"jp2 "); + let mut cut = bx(b"jp2c", &[0xFF, 0x4F, 0xFF, 0x51, 0, 0]); + cut.truncate(10); + file.extend_from_slice(&cut); + assert!(boxes(&file).nth(1).unwrap().is_err()); + let all: Vec<_> = boxes(&file).allow_truncated().collect::>>().unwrap(); + assert_eq!(all.len(), 2); + assert!(!all[0].truncated); + assert_eq!((all[1].truncated, all[1].payload), (true, &[0xFF, 0x4F][..])); + } + + #[test] + fn hostile_sizes_never_panic() { + let headers: [&[u8]; 6] = [ + &[0xFF, 0xFF, 0xFF, 0xFF, b'a', b'b', b'c', b'd'], + &[0, 0, 0, 1, b'a', b'b', b'c', b'd', 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF], + &[0, 0, 0, 1, b'a', b'b', b'c', b'd', 0, 0, 0, 0, 0, 0, 0, 3], + &[0, 0, 0, 1, b'u', b'u', b'i', b'd', 0, 0, 0, 0, 0, 0, 0, 30], + &[0, 0, 0, 0, b'u', b'u', b'i', b'd', 1, 2, 3], + &[0, 0, 0, 7, b'a', b'b', b'c', b'd'], + ]; + for h in headers { + for lenient in [false, true] { + let mut it = BoxIter::new(h); + if lenient { + it = it.allow_truncated(); + } + assert!(it.count() <= 1); + } + } + // Ranges outside the data are clipped. + assert_eq!(BoxIter::within(&[0, 0, 0, 8, 1, 2, 3, 4], 4..100).count(), 1); + #[allow(clippy::reversed_empty_ranges)] + let backwards = 6..2; + assert_eq!(BoxIter::within(&[0; 8], backwards).count(), 0); + assert_eq!(BoxIter::within(&[0; 8], 50..60).count(), 0); + } + + #[test] + fn reader_bounds() { + let mut c = Reader::labeled(&[0, 0, 0, 5, 1], "t"); + assert!(c.count(1).is_err()); + let mut c = Reader::new(&[0xFF, 0xFF, 0xFF, 0xFF]); + assert!(c.count(usize::MAX).is_err()); + let mut c = Reader::new(&[1, 2, 3, 4, 5]); + assert_eq!(c.u24().unwrap(), 0x010203); + assert!(c.u32().is_err()); + assert_eq!((c.position(), c.rest()), (3, &[4u8, 5][..])); + assert!(matches!(Reader::labeled(&[], "x").u8(), Err(Error::Truncated("x")))); + } +} diff --git a/crates/media/src/isobmff/bytes.rs b/crates/media/src/isobmff/bytes.rs new file mode 100644 index 000000000..92ea81aaf --- /dev/null +++ b/crates/media/src/isobmff/bytes.rs @@ -0,0 +1,127 @@ +//! Four-character codes and a box builder for the muxers. Box reading lives in +//! [`boxes`](super::boxes). + +pub(crate) use crate::isobmff::boxes::{BoxHeader, Reader as Cur, boxes, find}; +use std::fmt; + +/// A four-character code (box type, sample entry format, brand, handler type…). +#[derive(Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Default)] +pub struct FourCc(pub [u8; 4]); + +impl FourCc { + pub const fn new(b: &[u8; 4]) -> Self { + FourCc(*b) + } + pub fn as_u32(self) -> u32 { + u32::from_be_bytes(self.0) + } + /// Lossy string form; `©` (0xA9) is mapped to U+00A9, other non-printables to `?`. + pub fn to_string_lossy(self) -> String { + self.0 + .iter() + .map(|&b| match b { + 0xA9 => '©', + 0x20..=0x7E => b as char, + _ => '?', + }) + .collect() + } +} + +impl fmt::Display for FourCc { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + f.write_str(&self.to_string_lossy()) + } +} +impl fmt::Debug for FourCc { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + write!(f, "FourCc({:?})", self.to_string_lossy()) + } +} +impl From<&[u8; 4]> for FourCc { + fn from(b: &[u8; 4]) -> Self { + FourCc(*b) + } +} +impl PartialEq<[u8; 4]> for FourCc { + fn eq(&self, other: &[u8; 4]) -> bool { + &self.0 == other + } +} +impl PartialEq<&[u8; 4]> for FourCc { + fn eq(&self, other: &&[u8; 4]) -> bool { + &self.0 == *other + } +} +impl PartialEq<&&[u8; 4]> for FourCc { + fn eq(&self, other: &&&[u8; 4]) -> bool { + &self.0 == **other + } +} + +/// Growable buffer for building boxes. +#[derive(Default, Clone, Debug)] +pub(crate) struct BoxBuf { + pub buf: Vec, +} + +impl BoxBuf { + pub fn new() -> Self { + Self::default() + } + /// Begin a box; returns a marker to pass to [`end`](Self::end). + pub fn start(&mut self, kind: &[u8; 4]) -> usize { + let at = self.buf.len(); + self.buf.extend_from_slice(&[0, 0, 0, 0]); + self.buf.extend_from_slice(kind); + at + } + pub fn start_full(&mut self, kind: &[u8; 4], version: u8, flags: u32) -> usize { + let at = self.start(kind); + self.u32(((version as u32) << 24) | (flags & 0xFF_FFFF)); + at + } + pub fn end(&mut self, at: usize) { + let size = (self.buf.len() - at) as u32; + self.buf[at..at + 4].copy_from_slice(&size.to_be_bytes()); + } + /// Append a complete box with the given payload. + pub fn leaf(&mut self, kind: &[u8; 4], payload: &[u8]) { + let at = self.start(kind); + self.bytes(payload); + self.end(at); + } + pub fn u8(&mut self, v: u8) { + self.buf.push(v); + } + pub fn u16(&mut self, v: u16) { + self.buf.extend_from_slice(&v.to_be_bytes()); + } + pub fn i16(&mut self, v: i16) { + self.buf.extend_from_slice(&v.to_be_bytes()); + } + pub fn u32(&mut self, v: u32) { + self.buf.extend_from_slice(&v.to_be_bytes()); + } + pub fn i32(&mut self, v: i32) { + self.buf.extend_from_slice(&v.to_be_bytes()); + } + pub fn u64(&mut self, v: u64) { + self.buf.extend_from_slice(&v.to_be_bytes()); + } + pub fn i64(&mut self, v: i64) { + self.buf.extend_from_slice(&v.to_be_bytes()); + } + pub fn f64(&mut self, v: f64) { + self.buf.extend_from_slice(&v.to_be_bytes()); + } + pub fn bytes(&mut self, b: &[u8]) { + self.buf.extend_from_slice(b); + } + pub fn zeros(&mut self, n: usize) { + self.buf.resize(self.buf.len() + n, 0); + } + pub fn len(&self) -> usize { + self.buf.len() + } +} diff --git a/crates/media/src/isobmff/chapters.rs b/crates/media/src/isobmff/chapters.rs new file mode 100644 index 000000000..dfb83197a --- /dev/null +++ b/crates/media/src/isobmff/chapters.rs @@ -0,0 +1,239 @@ +//! Chapter lists, in the two forms players read. +//! +//! - **QuickTime chapter track** (QuickTime File Format, "Chapter lists" and "Text media"): a +//! disabled text track whose samples are the chapter titles, referenced from a video or audio track +//! by a `tref/chap` track reference. QuickTime Player, Apple TV, iOS and Final Cut read this form. +//! Each sample is a 16-bit big-endian length, the title, and an `encd` atom with value `0x100` +//! marking the text as UTF-8 (the convention Apple's own chapter tracks in `.m4a`/`.m4v` files use; +//! plain QuickTime text is Mac Roman). +//! - **Nero chapter list** `moov/udta/chpl`, version 1: `u32` reserved, `u8` chapter count, then per +//! chapter a `u64` start in 100 ns units, a `u8` title length and the UTF-8 title. It has no +//! official specification; this is the layout publicly documented for Nero Digital files and +//! written by many tools. VLC and ffprobe (`-show_chapters`) read it. +//! +//! Both forms carry at most [`MAX_CHAPTERS`] chapters with titles of at most +//! [`MAX_CHAPTER_TITLE_BYTES`] bytes (the `chpl` count and length fields are one byte each). + +use crate::isobmff::bytes::{BoxBuf, Cur}; + +/// One chapter mark: `start` in the movie timescale ([`crate::isobmff::WriterOptions::movie_timescale`] +/// when writing, [`crate::isobmff::Mp4File::timescale`] when reading), `title` UTF-8. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Chapter { + pub start: u64, + pub title: String, +} + +/// Most chapters written (the `chpl` count is one byte); later ones are dropped. +pub const MAX_CHAPTERS: usize = 255; +/// Longest chapter title in bytes (the `chpl` length is one byte); longer titles are cut at a +/// character boundary. +pub const MAX_CHAPTER_TITLE_BYTES: usize = 255; + +/// `chpl` times are in 100 ns units. +const CHPL_UNITS_PER_SECOND: u64 = 10_000_000; + +/// Cut `s` to at most `max` bytes without splitting a character. +pub(crate) fn truncate_utf8(s: &str, max: usize) -> &str { + if s.len() <= max { + return s; + } + let mut end = max; + while end > 0 && !s.is_char_boundary(end) { + end -= 1; + } + s.get(..end).unwrap_or("") +} + +/// The chapters a file can carry: sorted by start, one per start time (the first title given for +/// a time wins), starts before `duration` only (when it is known), titles cut to +/// [`MAX_CHAPTER_TITLE_BYTES`] with control characters replaced by spaces, at most +/// [`MAX_CHAPTERS`]. +pub fn normalize_chapters(chapters: &[Chapter], duration: Option) -> Vec { + let mut v: Vec<&Chapter> = chapters.iter().filter(|c| duration.is_none_or(|d| c.start < d)).collect(); + v.sort_by_key(|c| c.start); + v.dedup_by_key(|c| c.start); + v.into_iter() + .take(MAX_CHAPTERS) + .map(|c| { + let clean: String = c.title.chars().map(|ch| if ch.is_control() { ' ' } else { ch }).collect(); + Chapter { start: c.start, title: truncate_utf8(clean.trim(), MAX_CHAPTER_TITLE_BYTES).to_string() } + }) + .collect() +} + +fn rescale(v: u64, from: u64, to: u64) -> u64 { + if from == 0 { + return 0; + } + (u128::from(v) * u128::from(to) / u128::from(from)).min(u128::from(u64::MAX)) as u64 +} + +/// Write `udta/chpl` content (the box itself) for already normalized chapters. +pub(crate) fn write_chpl(b: &mut BoxBuf, chapters: &[Chapter], movie_timescale: u32) { + let m = b.start_full(b"chpl", 1, 0); + b.u32(0); + let n = chapters.len().min(MAX_CHAPTERS); + b.u8(n as u8); + for c in chapters.iter().take(n) { + b.u64(rescale(c.start, u64::from(movie_timescale), CHPL_UNITS_PER_SECOND)); + let t = truncate_utf8(&c.title, MAX_CHAPTER_TITLE_BYTES); + b.u8(t.len() as u8); + b.bytes(t.as_bytes()); + } + b.end(m); +} + +/// Parse a `chpl` payload (after the box header) into chapters in `movie_timescale` units. +/// Malformed or truncated lists yield the chapters read so far. +pub(crate) fn parse_chpl(p: &[u8], movie_timescale: u32) -> Vec { + let mut out = Vec::new(); + let mut c = Cur::labeled(p, "chpl"); + let Ok((version, _)) = c.full_header() else { return out }; + if version >= 1 && c.skip(4).is_err() { + return out; + } + let Ok(n) = c.u8() else { return out }; + for _ in 0..n { + let Ok(start) = c.u64() else { break }; + let Ok(len) = c.u8() else { break }; + let Ok(title) = c.bytes(len as usize) else { break }; + out.push(Chapter { + start: rescale(start, CHPL_UNITS_PER_SECOND, u64::from(movie_timescale)), + title: String::from_utf8_lossy(title).into_owned(), + }); + } + out +} + +/// Payload of the QuickTime `text` sample description (after its 8-byte box header), QTFF "Text +/// sample description": reserved + data reference index, display flags, justification, background +/// colour, default text box, reserved, font number and face, reserved, foreground colour, an empty +/// Pascal font name, then an `ftab` font table naming one font. +pub(crate) fn text_sample_entry_payload() -> Vec { + let mut b = BoxBuf::new(); + b.zeros(6); + b.u16(1); // data reference index + b.u32(0); // display flags + b.i32(0); // justification: left + b.zeros(6); // background colour (RGB) + b.zeros(8); // default text box (top, left, bottom, right) + b.zeros(8); // reserved + b.u16(1); // font number (matches the ftab entry) + b.u16(0); // font face: plain + b.u8(0); // reserved + b.u16(0); // reserved + b.zeros(6); // foreground colour (RGB) + b.u8(0); // text name: empty Pascal string + let f = b.start(b"ftab"); + b.u16(1); + b.u16(1); + let name = b"Sans-Serif"; + b.u8(name.len() as u8); + b.bytes(name); + b.end(f); + b.buf +} + +/// One chapter-track sample: length-prefixed UTF-8 title plus an `encd` atom (UTF-8). +pub(crate) fn text_sample(title: &str) -> Vec { + let t = truncate_utf8(title, MAX_CHAPTER_TITLE_BYTES); + let mut b = BoxBuf::new(); + b.u16(t.len() as u16); + b.bytes(t.as_bytes()); + let e = b.start(b"encd"); + b.u32(0x100); + b.end(e); + b.buf +} + +/// The title in a QuickTime text sample (UTF-8, or UTF-16 when it starts with a byte order mark). +pub fn parse_text_sample(data: &[u8]) -> Option { + let mut c = Cur::labeled(data, "text sample"); + let n = c.u16().ok()? as usize; + decode_title(c.bytes(n).ok()?) +} + +/// [`parse_text_sample`] of the start of a longer sample: as much of the title as `data` holds. +pub(crate) fn parse_text_sample_prefix(data: &[u8]) -> Option { + let (declared, rest) = data.split_first_chunk::<2>()?; + decode_title(rest.get(..usize::from(u16::from_be_bytes(*declared))).unwrap_or(rest)) +} + +fn decode_title(t: &[u8]) -> Option { + if let Some(rest) = t.strip_prefix(&[0xFE, 0xFF]) { + let units: Vec = rest.as_chunks::<2>().0.iter().map(|u| u16::from_be_bytes(*u)).collect(); + return Some(String::from_utf16_lossy(&units)); + } + if let Some(rest) = t.strip_prefix(&[0xFF, 0xFE]) { + let units: Vec = rest.as_chunks::<2>().0.iter().map(|u| u16::from_le_bytes(*u)).collect(); + return Some(String::from_utf16_lossy(&units)); + } + // trailing atoms (`encd`, `styl` …) are not part of the text + Some(String::from_utf8_lossy(t).into_owned()) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn ch(start: u64, title: &str) -> Chapter { + Chapter { start, title: title.into() } + } + + #[test] + fn normalize_sorts_dedups_drops_and_caps() { + let v = normalize_chapters(&[ch(500, "b"), ch(0, "a"), ch(500, "dup"), ch(2000, "past end"), ch(1999, "\tend\n")], Some(2000)); + assert_eq!(v, vec![ch(0, "a"), ch(500, "b"), ch(1999, "end")]); + let many: Vec = (0..1000).map(|i| ch(i, "x")).collect(); + assert_eq!(normalize_chapters(&many, None).len(), MAX_CHAPTERS); + let long = "é".repeat(300); + let t = &normalize_chapters(&[ch(0, &long)], None)[0].title; + assert!(t.len() <= MAX_CHAPTER_TITLE_BYTES && t.chars().all(|c| c == 'é')); + assert!(normalize_chapters(&[ch(0, "a")], Some(0)).is_empty()); + } + + #[test] + fn chpl_roundtrip() { + let chapters = vec![ch(0, "Intro"), ch(1500, "Teil 2 — ü"), ch(u64::MAX, "far")]; + let mut b = BoxBuf::new(); + write_chpl(&mut b, &chapters, 1000); + // box header (8) + version/flags (4) + reserved (4) + count (1) + assert_eq!(&b.buf[4..8], b"chpl"); + assert_eq!(b.buf[8], 1); + assert_eq!(b.buf[16], 3); + assert_eq!(u64::from_be_bytes(b.buf[17..25].try_into().unwrap()), 0); + assert_eq!(u64::from_be_bytes(b.buf[31..39].try_into().unwrap()), 15_000_000); + let back = parse_chpl(&b.buf[8..], 1000); + assert_eq!(back[..2], chapters[..2]); + assert_eq!(back.len(), 3); + } + + #[test] + fn chpl_parse_survives_garbage() { + let mut b = BoxBuf::new(); + write_chpl(&mut b, &[ch(0, "a"), ch(10, "bb")], 1000); + let p = b.buf[8..].to_vec(); + for cut in 0..p.len() { + let _ = parse_chpl(&p[..cut], 1000); + } + let mut lying = p.clone(); + lying[8] = 255; // count says 255 + assert_eq!(parse_chpl(&lying, 1000).len(), 2); + assert!(parse_chpl(&p, 0).iter().all(|c| c.start == 0)); + } + + #[test] + fn text_sample_roundtrip() { + let s = text_sample("Kapitel “1”"); + assert_eq!(parse_text_sample(&s).as_deref(), Some("Kapitel “1”")); + assert_eq!(&s[s.len() - 12..s.len() - 4], &[0, 0, 0, 12, b'e', b'n', b'c', b'd']); + assert_eq!(parse_text_sample(&[0, 4, 0xFE, 0xFF, 0, b'A']).as_deref(), Some("A")); + assert_eq!(parse_text_sample(&[0, 9, b'a']), None); + assert_eq!(parse_text_sample(&[]), None); + // The start of a longer sample: what it holds of the title, and no further than the title. + assert_eq!(parse_text_sample_prefix(&[0, 9, b'a']).as_deref(), Some("a")); + assert_eq!(parse_text_sample_prefix(&[0, 1, b'a', b'b']).as_deref(), Some("a")); + assert_eq!(parse_text_sample_prefix(&[0]), None); + } +} diff --git a/crates/media/src/isobmff/codec.rs b/crates/media/src/isobmff/codec.rs new file mode 100644 index 000000000..302d7addf --- /dev/null +++ b/crates/media/src/isobmff/codec.rs @@ -0,0 +1,2036 @@ +//! Sample entries (`stsd` children) and codec configuration records: parsing and serialization. + +use crate::CodecId; +use crate::bitstream::BitReader; +use crate::isobmff::bytes::{BoxBuf, Cur, FourCc, boxes}; +use crate::isobmff::error::{Error, Result}; + +/// One sample description (an entry of `stsd`). +#[derive(Clone, Debug, PartialEq)] +pub struct SampleEntry { + /// Sample entry format (`avc1`, `mp4a`, `apch`, …). + pub format: FourCc, + pub data_reference_index: u16, + pub codec: CodecConfig, + /// Present for visual sample entries. + pub video: Option, + /// Present for audio sample entries. + pub audio: Option, + /// `btrt` box. + pub bitrate: Option, +} + +/// Fields common to all visual sample entries plus the optional descriptive boxes. +#[derive(Clone, Debug, PartialEq, Default)] +pub struct VideoParams { + pub width: u16, + pub height: u16, + /// Horizontal/vertical resolution in pixels per inch (16.16 fixed point; 72 dpi = 0x0048_0000). + pub horiz_resolution: u32, + pub vert_resolution: u32, + pub frame_count: u16, + pub compressor_name: String, + pub depth: u16, + /// QuickTime `vendor` / version fields (zero in ISO files). + pub vendor: FourCc, + pub temporal_quality: u32, + pub spatial_quality: u32, + pub color: Option, + /// QuickTime `logs`: the CoreMedia log transfer-function identifier (for example + /// `com.apple.rec2020.apple-log`). Non-empty UTF-8 without NUL, at most 255 bytes; anything + /// else, or a second `logs` box, reads as `None`. + pub log_transfer_function: Option, + /// `pasp`: (hSpacing, vSpacing). + pub pixel_aspect: Option<(u32, u32)>, + pub clean_aperture: Option, + pub field_info: Option, + /// QuickTime `gama` (16.16 fixed point). + pub gamma: Option, + /// `mdcv`: mastering display color volume (SMPTE ST 2086). + pub mastering_display: Option, + /// `clli`: content light level (MaxCLL, MaxFALL in cd/m²; 0 = unknown). + pub content_light: Option<(u16, u16)>, +} + +/// SMPTE ST 2086 mastering display metadata, in the units of the `mdcv` box and the H.264/HEVC +/// SEI: chromaticities in 0.00002 steps (order G, B, R as the SEI), luminance in 0.0001 cd/m². +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct MasteringDisplay { + pub primaries: [(u16, u16); 3], + pub white_point: (u16, u16), + pub max_luminance: u32, + pub min_luminance: u32, +} + +impl MasteringDisplay { + /// BT.2020 primaries, D65, with the given peak and black in cd/m². + pub fn bt2020(max_nits: f64, min_nits: f64) -> Self { + let q = |v: f64| (v / 0.00002).round() as u16; + MasteringDisplay { + primaries: [(q(0.170), q(0.797)), (q(0.131), q(0.046)), (q(0.708), q(0.292))], + white_point: (q(0.3127), q(0.3290)), + max_luminance: (max_nits * 10_000.0).round() as u32, + min_luminance: (min_nits * 10_000.0).round() as u32, + } + } + pub fn max_nits(&self) -> f64 { + self.max_luminance as f64 / 10_000.0 + } + /// The 24-byte payload shared by `mdcv` and the SEI message. + pub fn to_bytes(&self) -> Vec { + let mut v = Vec::with_capacity(24); + for (x, y) in self.primaries { + v.extend_from_slice(&x.to_be_bytes()); + v.extend_from_slice(&y.to_be_bytes()); + } + v.extend_from_slice(&self.white_point.0.to_be_bytes()); + v.extend_from_slice(&self.white_point.1.to_be_bytes()); + v.extend_from_slice(&self.max_luminance.to_be_bytes()); + v.extend_from_slice(&self.min_luminance.to_be_bytes()); + v + } + pub fn parse(p: &[u8]) -> Option { + if p.len() < 24 { + return None; + } + let u16_at = |i: usize| u16::from_be_bytes([p[i], p[i + 1]]); + let u32_at = |i: usize| u32::from_be_bytes([p[i], p[i + 1], p[i + 2], p[i + 3]]); + Some(MasteringDisplay { + primaries: [(u16_at(0), u16_at(2)), (u16_at(4), u16_at(6)), (u16_at(8), u16_at(10))], + white_point: (u16_at(12), u16_at(14)), + max_luminance: u32_at(16), + min_luminance: u32_at(20), + }) + } +} + +/// `colr` box contents. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum ColorInfo { + /// ISO `nclx` (with full-range flag). + Nclx { primaries: u16, transfer: u16, matrix: u16, full_range: bool }, + /// QuickTime `nclc`. + Nclc { primaries: u16, transfer: u16, matrix: u16 }, + /// Embedded ICC profile (`prof` restricted/unrestricted `rICC`). + Icc { kind: FourCc, profile: Vec }, +} + +/// `clap` clean aperture (all rationals num/den; offsets are signed). +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct CleanAperture { + pub width: (u32, u32), + pub height: (u32, u32), + pub horiz_offset: (i32, u32), + pub vert_offset: (i32, u32), +} + +/// QuickTime `fiel`: field count (1 progressive, 2 interlaced) and ordering detail +/// (0, 1 = top first, 6 = bottom first, 9 / 14 per the QuickTime spec). +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct FieldInfo { + pub fields: u8, + pub detail: u8, +} + +/// `btrt` box. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct BitRate { + pub buffer_size: u32, + pub max_bitrate: u32, + pub avg_bitrate: u32, +} + +/// Fields of audio sample entries (ISO v0 plus QuickTime sound description v1/v2 extensions). +#[derive(Clone, Debug, PartialEq, Default)] +pub struct AudioParams { + /// QuickTime sound description version (0, 1, 2). ISO files use 0. + pub qt_version: u16, + pub channels: u32, + /// Bits per sample from the entry (16 for most compressed formats). + pub sample_size: u16, + pub sample_rate: f64, + pub compression_id: i16, + /// v1 fields. + pub samples_per_packet: u32, + pub bytes_per_packet: u32, + pub bytes_per_frame: u32, + pub bytes_per_sample: u32, + /// v2 fields. + pub const_bits_per_channel: u32, + pub lpcm_flags: u32, + pub const_bytes_per_packet: u32, + pub const_frames_per_packet: u32, + /// `enda` little-endian flag inside a QuickTime `wave` box. + pub little_endian: Option, +} + +/// Codec configuration decoded from the sample entry. +#[derive(Clone, Debug, PartialEq)] +pub enum CodecConfig { + Avc(AvcConfig), + Hevc(HevcConfig), + Av1(Av1Config), + Vp9(VpcConfig), + /// Apple ProRes; fourcc is `apch`/`apcn`/`apcs`/`apco`/`ap4h`/`ap4x`. + ProRes { + fourcc: FourCc, + }, + /// Motion JPEG (`jpeg`, `mjpa`, `mjpb`). + Jpeg { + fourcc: FourCc, + }, + /// Avid DNxHD/DNxHR (`AVdn`, `AVdh`). + Dnx { + fourcc: FourCc, + }, + /// Advanced Professional Video (`apv1` + `apvC`). + Apv(ApvConfig), + Aac(AacConfig), + /// MPEG-1/2 audio (esds object type 0x69/0x6B, or QuickTime `.mp3` / `.mp2`). Usually layer + /// III, but these name no layer: ffmpeg stores MP2 as `mp4a` + 0x6B. Each frame header has it, + /// and [`crate::isobmff::Track::codec_params`] reports the layer the first frame names. + Mp3, + Pcm(PcmConfig), + /// ALAC magic cookie (ALACSpecificConfig, 24 bytes, optionally followed by a channel layout). + Alac { + cookie: Vec, + }, + Opus(OpusConfig), + Flac(FlacConfig), + /// `dac3` payload. + Ac3 { + dac3: Vec, + }, + /// `dec3` payload. + Eac3 { + dec3: Vec, + }, + Timecode(TimecodeConfig), + /// Anything else; `raw` is the full sample entry payload (after the 8-byte box header). + Unknown { + fourcc: FourCc, + raw: Vec, + }, +} + +impl CodecConfig { + /// The codec this configuration is for. `Mp3` covers every MPEG audio layer: these entries + /// name none, and each frame header has it (ffmpeg stores MP2 as `mp4a` + 0x6B); + /// [`crate::isobmff::Track::codec_params`] reads it from the first frame. + pub fn codec_id(&self) -> CodecId { + match self { + CodecConfig::Avc(_) => CodecId::H264, + CodecConfig::Hevc(_) => CodecId::Hevc, + CodecConfig::Av1(_) => CodecId::Av1, + CodecConfig::Vp9(_) => CodecId::Vp9, + CodecConfig::ProRes { .. } => CodecId::ProRes, + CodecConfig::Jpeg { .. } => CodecId::Mjpeg, + CodecConfig::Aac(_) => CodecId::Aac, + CodecConfig::Mp3 => CodecId::Mp3, + CodecConfig::Pcm(_) => CodecId::Pcm, + CodecConfig::Alac { .. } => CodecId::Alac, + CodecConfig::Opus(_) => CodecId::Opus, + CodecConfig::Flac(_) => CodecId::Flac, + CodecConfig::Ac3 { .. } => CodecId::Ac3, + CodecConfig::Eac3 { .. } => CodecId::Eac3, + CodecConfig::Dnx { .. } => CodecId::Dnxhd, + CodecConfig::Apv(_) => CodecId::Apv, + CodecConfig::Timecode(_) | CodecConfig::Unknown { .. } => CodecId::Unknown, + } + } + + /// The codec configuration in Matroska's `CodecPrivate` form (see [`crate::CodecParams`]): + /// the `OpusHead` built from `dOps`, `fLaC` + the `dfLa` metadata blocks, the other records + /// as stored. + pub fn extradata(&self) -> Vec { + match self { + CodecConfig::Avc(c) => c.to_bytes(), + CodecConfig::Hevc(c) => c.to_bytes(), + CodecConfig::Av1(c) => c.to_bytes(), + CodecConfig::Vp9(c) => c.to_bytes(), + CodecConfig::Apv(c) => c.record_bytes(), + CodecConfig::Aac(a) => a.asc.clone(), + CodecConfig::Alac { cookie } => cookie.clone(), + CodecConfig::Opus(o) => o.opus_head(), + CodecConfig::Flac(f) => [b"fLaC".as_slice(), &f.metadata_blocks].concat(), + CodecConfig::Ac3 { dac3 } => dac3.clone(), + CodecConfig::Eac3 { dec3 } => dec3.clone(), + _ => Vec::new(), + } + } + + /// A short human-readable codec name. + pub fn name(&self) -> &'static str { + match self { + CodecConfig::Avc(_) => "h264", + CodecConfig::Hevc(_) => "hevc", + CodecConfig::Av1(_) => "av1", + CodecConfig::Vp9(_) => "vp9", + CodecConfig::ProRes { .. } => "prores", + CodecConfig::Jpeg { .. } => "mjpeg", + CodecConfig::Dnx { .. } => "dnxhd", + CodecConfig::Apv(_) => "apv", + CodecConfig::Aac(_) => "aac", + CodecConfig::Mp3 => "mp3", + CodecConfig::Pcm(_) => "pcm", + CodecConfig::Alac { .. } => "alac", + CodecConfig::Opus(_) => "opus", + CodecConfig::Flac(_) => "flac", + CodecConfig::Ac3 { .. } => "ac3", + CodecConfig::Eac3 { .. } => "eac3", + CodecConfig::Timecode(_) => "timecode", + CodecConfig::Unknown { .. } => "unknown", + } + } +} + +/// `avcC` — AVCDecoderConfigurationRecord (ISO/IEC 14496-15 §5.3.3). +#[derive(Clone, Debug, PartialEq, Eq, Default)] +pub struct AvcConfig { + pub profile: u8, + pub compatibility: u8, + pub level: u8, + /// NAL length field size in bytes (1, 2 or 4). + pub length_size: u8, + pub sps: Vec>, + pub pps: Vec>, + /// Bytes after the PPS list (high-profile extension: chroma format, bit depths, SPS-ext). + pub ext: Vec, +} + +impl AvcConfig { + /// Build from parameter sets (NAL units without start codes); profile/level taken from the first SPS. + pub fn new(sps: Vec>, pps: Vec>, length_size: u8) -> Self { + let (profile, compatibility, level) = sps.first().filter(|s| s.len() >= 4).map(|s| (s[1], s[2], s[3])).unwrap_or((0, 0, 0)); + AvcConfig { profile, compatibility, level, length_size, sps, pps, ext: Vec::new() } + } + + pub fn parse(data: &[u8]) -> Result { + let mut c = Cur::labeled(data, "avcC"); + let _version = c.u8()?; + let profile = c.u8()?; + let compatibility = c.u8()?; + let level = c.u8()?; + let length_size = (c.u8()? & 3) + 1; + let nsps = (c.u8()? & 0x1F) as usize; + let mut sps = Vec::with_capacity(nsps); + for _ in 0..nsps { + let n = c.u16()? as usize; + sps.push(c.bytes(n)?.to_vec()); + } + let npps = c.u8()? as usize; + let mut pps = Vec::with_capacity(npps); + for _ in 0..npps { + let n = c.u16()? as usize; + pps.push(c.bytes(n)?.to_vec()); + } + Ok(AvcConfig { profile, compatibility, level, length_size, sps, pps, ext: c.rest().to_vec() }) + } + + pub fn to_bytes(&self) -> Vec { + let mut b = BoxBuf::new(); + b.u8(1); + b.u8(self.profile); + b.u8(self.compatibility); + b.u8(self.level); + b.u8(0xFC | (self.length_size.clamp(1, 4) - 1)); + b.u8(0xE0 | (self.sps.len().min(31) as u8)); + for s in self.sps.iter().take(31) { + b.u16(s.len() as u16); + b.bytes(s); + } + b.u8(self.pps.len().min(255) as u8); + for p in self.pps.iter().take(255) { + b.u16(p.len() as u16); + b.bytes(p); + } + b.bytes(&self.ext); + b.buf + } +} + +/// One NAL array of an `hvcC` record. +#[derive(Clone, Debug, PartialEq, Eq, Default)] +pub struct HevcNalArray { + pub completeness: bool, + pub nal_type: u8, + pub nalus: Vec>, +} + +/// `hvcC` — HEVCDecoderConfigurationRecord (ISO/IEC 14496-15 §8.3.3). +#[derive(Clone, Debug, PartialEq, Eq, Default)] +pub struct HevcConfig { + pub general_profile_space: u8, + pub general_tier_flag: bool, + pub general_profile_idc: u8, + pub general_profile_compatibility_flags: u32, + /// 48 bits of general constraint indicator flags. + pub general_constraint_indicator_flags: u64, + pub general_level_idc: u8, + pub min_spatial_segmentation_idc: u16, + pub parallelism_type: u8, + pub chroma_format_idc: u8, + pub bit_depth_luma: u8, + pub bit_depth_chroma: u8, + pub avg_frame_rate: u16, + pub constant_frame_rate: u8, + pub num_temporal_layers: u8, + pub temporal_id_nested: bool, + pub length_size: u8, + pub arrays: Vec, +} + +impl HevcConfig { + pub fn parse(data: &[u8]) -> Result { + let mut c = Cur::labeled(data, "hvcC"); + let _version = c.u8()?; + let b = c.u8()?; + let compat = c.u32()?; + let hi = c.u16()? as u64; + let lo = c.u32()? as u64; + let level = c.u8()?; + let min_seg = c.u16()? & 0x0FFF; + let par = c.u8()? & 3; + let chroma = c.u8()? & 3; + let bdl = (c.u8()? & 7) + 8; + let bdc = (c.u8()? & 7) + 8; + let afr = c.u16()?; + let x = c.u8()?; + let narrays = c.u8()? as usize; + let mut arrays = Vec::new(); + for _ in 0..narrays { + let t = c.u8()?; + let n = c.u16()? as usize; + c.check_count(n, 2)?; + let mut nalus = Vec::with_capacity(n); + for _ in 0..n { + let len = c.u16()? as usize; + nalus.push(c.bytes(len)?.to_vec()); + } + arrays.push(HevcNalArray { completeness: t & 0x80 != 0, nal_type: t & 0x3F, nalus }); + } + Ok(HevcConfig { + general_profile_space: b >> 6, + general_tier_flag: b & 0x20 != 0, + general_profile_idc: b & 0x1F, + general_profile_compatibility_flags: compat, + general_constraint_indicator_flags: (hi << 32) | lo, + general_level_idc: level, + min_spatial_segmentation_idc: min_seg, + parallelism_type: par, + chroma_format_idc: chroma, + bit_depth_luma: bdl, + bit_depth_chroma: bdc, + avg_frame_rate: afr, + constant_frame_rate: x >> 6, + num_temporal_layers: (x >> 3) & 7, + temporal_id_nested: x & 4 != 0, + length_size: (x & 3) + 1, + arrays, + }) + } + + pub fn to_bytes(&self) -> Vec { + let mut b = BoxBuf::new(); + b.u8(1); + b.u8((self.general_profile_space << 6) | ((self.general_tier_flag as u8) << 5) | (self.general_profile_idc & 0x1F)); + b.u32(self.general_profile_compatibility_flags); + b.u16((self.general_constraint_indicator_flags >> 32) as u16); + b.u32(self.general_constraint_indicator_flags as u32); + b.u8(self.general_level_idc); + b.u16(0xF000 | (self.min_spatial_segmentation_idc & 0x0FFF)); + b.u8(0xFC | (self.parallelism_type & 3)); + b.u8(0xFC | (self.chroma_format_idc & 3)); + b.u8(0xF8 | (self.bit_depth_luma.saturating_sub(8) & 7)); + b.u8(0xF8 | (self.bit_depth_chroma.saturating_sub(8) & 7)); + b.u16(self.avg_frame_rate); + b.u8((self.constant_frame_rate << 6) + | ((self.num_temporal_layers & 7) << 3) + | ((self.temporal_id_nested as u8) << 2) + | (self.length_size.clamp(1, 4) - 1)); + b.u8(self.arrays.len() as u8); + for a in &self.arrays { + b.u8(((a.completeness as u8) << 7) | (a.nal_type & 0x3F)); + b.u16(a.nalus.len() as u16); + for n in &a.nalus { + b.u16(n.len() as u16); + b.bytes(n); + } + } + b.buf + } + + fn nalus_of(&self, t: u8) -> Vec<&[u8]> { + self.arrays.iter().filter(|a| a.nal_type == t).flat_map(|a| a.nalus.iter().map(|n| n.as_slice())).collect() + } + pub fn vps(&self) -> Vec<&[u8]> { + self.nalus_of(32) + } + pub fn sps(&self) -> Vec<&[u8]> { + self.nalus_of(33) + } + pub fn pps(&self) -> Vec<&[u8]> { + self.nalus_of(34) + } +} + +/// `av1C` — AV1CodecConfigurationRecord. +#[derive(Clone, Debug, PartialEq, Eq, Default)] +pub struct Av1Config { + pub seq_profile: u8, + pub seq_level_idx_0: u8, + pub seq_tier_0: bool, + pub high_bitdepth: bool, + pub twelve_bit: bool, + pub monochrome: bool, + pub chroma_subsampling_x: bool, + pub chroma_subsampling_y: bool, + pub chroma_sample_position: u8, + pub initial_presentation_delay_minus_one: Option, + pub config_obus: Vec, +} + +impl Av1Config { + pub fn parse(data: &[u8]) -> Result { + let mut c = Cur::labeled(data, "av1C"); + let m = c.u8()?; + if m & 0x80 == 0 { + return Err(Error::Invalid("av1C marker bit not set".into())); + } + let a = c.u8()?; + let b = c.u8()?; + let d = c.u8()?; + Ok(Av1Config { + seq_profile: a >> 5, + seq_level_idx_0: a & 0x1F, + seq_tier_0: b & 0x80 != 0, + high_bitdepth: b & 0x40 != 0, + twelve_bit: b & 0x20 != 0, + monochrome: b & 0x10 != 0, + chroma_subsampling_x: b & 0x08 != 0, + chroma_subsampling_y: b & 0x04 != 0, + chroma_sample_position: b & 3, + initial_presentation_delay_minus_one: if d & 0x10 != 0 { Some(d & 0x0F) } else { None }, + config_obus: c.rest().to_vec(), + }) + } + pub fn to_bytes(&self) -> Vec { + let mut b = BoxBuf::new(); + b.u8(0x81); + b.u8((self.seq_profile << 5) | (self.seq_level_idx_0 & 0x1F)); + b.u8(((self.seq_tier_0 as u8) << 7) + | ((self.high_bitdepth as u8) << 6) + | ((self.twelve_bit as u8) << 5) + | ((self.monochrome as u8) << 4) + | ((self.chroma_subsampling_x as u8) << 3) + | ((self.chroma_subsampling_y as u8) << 2) + | (self.chroma_sample_position & 3)); + b.u8(match self.initial_presentation_delay_minus_one { + Some(d) => 0x10 | (d & 0x0F), + None => 0, + }); + b.bytes(&self.config_obus); + b.buf + } +} + +/// `vpcC` — VP codec configuration (version 1). +#[derive(Clone, Debug, PartialEq, Eq, Default)] +pub struct VpcConfig { + pub profile: u8, + pub level: u8, + pub bit_depth: u8, + pub chroma_subsampling: u8, + pub full_range: bool, + pub colour_primaries: u8, + pub transfer_characteristics: u8, + pub matrix_coefficients: u8, + pub codec_init: Vec, +} + +impl VpcConfig { + pub fn parse(data: &[u8]) -> Result { + let mut c = Cur::labeled(data, "vpcC"); + let (version, _) = c.full_header()?; + if version == 0 { + // Version 0 draft layout: profile, level, bitDepth(4)|colorSpace(4), chroma(4)|transfer(3)|range(1) + let profile = c.u8()?; + let level = c.u8()?; + let a = c.u8()?; + let b = c.u8()?; + return Ok(VpcConfig { profile, level, bit_depth: a >> 4, chroma_subsampling: b >> 4, full_range: b & 1 != 0, ..Default::default() }); + } + let profile = c.u8()?; + let level = c.u8()?; + let a = c.u8()?; + let colour_primaries = c.u8()?; + let transfer_characteristics = c.u8()?; + let matrix_coefficients = c.u8()?; + let n = c.u16()? as usize; + let codec_init = c.bytes(n)?.to_vec(); + Ok(VpcConfig { + profile, + level, + bit_depth: a >> 4, + chroma_subsampling: (a >> 1) & 7, + full_range: a & 1 != 0, + colour_primaries, + transfer_characteristics, + matrix_coefficients, + codec_init, + }) + } + pub fn to_bytes(&self) -> Vec { + let mut b = BoxBuf::new(); + b.u32(1 << 24); + b.u8(self.profile); + b.u8(self.level); + b.u8((self.bit_depth << 4) | ((self.chroma_subsampling & 7) << 1) | self.full_range as u8); + b.u8(self.colour_primaries); + b.u8(self.transfer_characteristics); + b.u8(self.matrix_coefficients); + b.u16(self.codec_init.len() as u16); + b.bytes(&self.codec_init); + b.buf + } +} + +/// AAC (MPEG-4 audio) configuration from `esds`. +#[derive(Clone, Debug, PartialEq, Eq, Default)] +pub struct AacConfig { + /// AudioSpecificConfig bytes (DecoderSpecificInfo). + pub asc: Vec, + /// Audio object type (2 = AAC-LC, 5 = SBR/HE-AAC, 29 = PS …) as signaled first in the ASC. + pub object_type: u8, + /// Sampling rate signaled by the ASC (core rate; 0 if the ASC is missing). + pub sample_rate: u32, + /// Channel configuration from the ASC (0 = defined elsewhere). + pub channel_config: u8, + /// DecoderConfigDescriptor fields. + pub max_bitrate: u32, + pub avg_bitrate: u32, + pub buffer_size: u32, +} + +const AAC_RATES: [u32; 13] = [96000, 88200, 64000, 48000, 44100, 32000, 24000, 22050, 16000, 12000, 11025, 8000, 7350]; + +impl AacConfig { + /// Build from an AudioSpecificConfig, decoding its header fields. + pub fn from_asc(asc: Vec) -> Self { + let (object_type, sample_rate, channel_config) = parse_asc(&asc).unwrap_or((0, 0, 0)); + AacConfig { asc, object_type, sample_rate, channel_config, max_bitrate: 0, avg_bitrate: 0, buffer_size: 0 } + } + /// Channel count implied by the channel configuration (ISO/IEC 14496-3 Table 1.19 with Amd 4: + /// 7 and 12 are 7.1 front / back, 11 is 6.1, 13 is 22.2, 14 is 7.1 with front heights), 0 if + /// unspecified (a PCE) or reserved. + pub fn channels(&self) -> u32 { + match self.channel_config { + 1..=6 => self.channel_config as u32, + 11 => 7, + 7 | 12 | 14 => 8, + 13 => 24, + _ => 0, + } + } +} + +/// Decode (audio object type, sampling frequency, channel configuration) from an AudioSpecificConfig. +pub fn parse_asc(asc: &[u8]) -> Option<(u8, u32, u8)> { + let mut r = BitReader::new(asc); + let aot = |r: &mut BitReader| -> Option { + let t = r.read_bits(5).ok()? as u8; + if t == 31 { Some(32 + r.read_bits(6).ok()? as u8) } else { Some(t) } + }; + let rate = |r: &mut BitReader| -> Option { + let i = r.read_bits(4).ok()? as usize; + if i == 15 { r.read_bits(24).ok() } else { AAC_RATES.get(i).copied() } + }; + let t = aot(&mut r)?; + let sr = rate(&mut r)?; + let ch = r.read_bits(4).ok()? as u8; + Some((t, sr, ch)) +} + +/// Uncompressed PCM description. +#[derive(Clone, Copy, Debug, PartialEq, Default)] +pub struct PcmConfig { + pub bits: u16, + pub float: bool, + pub big_endian: bool, + /// Signed integer samples (8-bit `raw ` is unsigned). + pub signed: bool, + pub channels: u32, + pub sample_rate: f64, +} + +impl PcmConfig { + /// Bytes per interleaved audio frame (all channels). + /// Saturates at `u32::MAX` for a hostile channel count or sample size. + pub fn bytes_per_frame(&self) -> u32 { + (self.bits as u32).div_ceil(8).saturating_mul(self.channels.max(1)) + } +} + +/// `dOps` — Opus specific box. +#[derive(Clone, Debug, PartialEq, Eq, Default)] +pub struct OpusConfig { + pub output_channels: u8, + pub pre_skip: u16, + pub input_sample_rate: u32, + pub output_gain: i16, + pub channel_mapping_family: u8, + /// StreamCount, CoupledCount and ChannelMapping bytes when family != 0. + pub channel_mapping: Vec, +} + +impl OpusConfig { + /// The Ogg Opus identification header (RFC 7845 §5.1) this `dOps` box describes: the same + /// fields, little-endian, behind the `OpusHead` magic. + pub fn opus_head(&self) -> Vec { + let mut h = Vec::with_capacity(19 + self.channel_mapping.len()); + h.extend_from_slice(b"OpusHead"); + h.push(1); + h.push(self.output_channels); + h.extend_from_slice(&self.pre_skip.to_le_bytes()); + h.extend_from_slice(&self.input_sample_rate.to_le_bytes()); + h.extend_from_slice(&self.output_gain.to_le_bytes()); + h.push(self.channel_mapping_family); + if self.channel_mapping_family != 0 { + h.extend_from_slice(&self.channel_mapping); + } + h + } + + pub fn parse(data: &[u8]) -> Result { + let mut c = Cur::labeled(data, "dOps"); + let _version = c.u8()?; + Ok(OpusConfig { + output_channels: c.u8()?, + pre_skip: c.u16()?, + input_sample_rate: c.u32()?, + output_gain: c.i16()?, + channel_mapping_family: c.u8()?, + channel_mapping: c.rest().to_vec(), + }) + } + pub fn to_bytes(&self) -> Vec { + let mut b = BoxBuf::new(); + b.u8(0); + b.u8(self.output_channels); + b.u16(self.pre_skip); + b.u32(self.input_sample_rate); + b.i16(self.output_gain); + b.u8(self.channel_mapping_family); + b.bytes(&self.channel_mapping); + b.buf + } +} + +/// `dfLa` — FLAC metadata blocks, with STREAMINFO decoded. +#[derive(Clone, Debug, PartialEq, Eq, Default)] +pub struct FlacConfig { + /// Raw metadata blocks (each with its 4-byte header) as stored in `dfLa`. + pub metadata_blocks: Vec, + pub sample_rate: u32, + pub channels: u8, + pub bits_per_sample: u8, + pub total_samples: u64, +} + +impl FlacConfig { + pub fn parse(data: &[u8]) -> Result { + let mut c = Cur::labeled(data, "dfLa"); + c.full_header()?; + let blocks = c.rest().to_vec(); + let mut cfg = FlacConfig { metadata_blocks: blocks.clone(), ..Default::default() }; + let mut b = Cur::labeled(&blocks, "dfLa"); + let hdr = b.u32()?; + if (hdr >> 24) & 0x7F == 0 { + let si = b.bytes(((hdr & 0xFF_FFFF) as usize).min(34))?; + if si.len() >= 18 { + let mut r = BitReader::new(&si[10..18]); + cfg.sample_rate = r.read_bits(20).unwrap_or(0); + cfg.channels = r.read_bits(3).unwrap_or(0) as u8 + 1; + cfg.bits_per_sample = r.read_bits(5).unwrap_or(0) as u8 + 1; + cfg.total_samples = r.read_bits_u64(36).unwrap_or(0); + } + } + Ok(cfg) + } +} + +/// QuickTime timecode sample description (`tmcd`) plus the start frame read from its first sample. +#[derive(Clone, Debug, PartialEq, Eq, Default)] +pub struct TimecodeConfig { + /// Bit 0 drop frame, bit 1 24-hour max, bit 2 negative times OK, bit 3 counter. + pub flags: u32, + pub timescale: u32, + pub frame_duration: u32, + /// Nominal frames per second (`numberOfFrames`), e.g. 30 for 29.97. + pub frames_per_second: u8, + /// Frame number of the first timecode sample (filled in by the demuxer). + pub start_frame: Option, + /// Source reel name (`name` box) if present. + pub name: Option, +} + +impl TimecodeConfig { + pub fn drop_frame(&self) -> bool { + self.flags & 1 != 0 + } + /// Format a frame number as `HH:MM:SS:FF` (`;` before the frames when drop-frame). + pub fn format_frame(&self, frame: u32) -> String { + let fps = self.frames_per_second.max(1) as u64; + let mut f = frame as u64; + if self.drop_frame() && fps >= 30 { + let drop = (fps / 30) * 2; // 2 frames per minute at 30, 4 at 60 + let per_min = fps * 60 - drop; + let per_10 = per_min * 10 + drop; + let d = f / per_10; + let m = f % per_10; + f += drop * 9 * d + if m > drop { drop * ((m - drop) / per_min) } else { 0 }; + } + let ff = f % fps; + let s = (f / fps) % 60; + let mi = (f / fps / 60) % 60; + let h = (f / fps / 3600) % 24; + let sep = if self.drop_frame() { ';' } else { ':' }; + format!("{h:02}:{mi:02}:{s:02}{sep}{ff:02}") + } +} + +/// `apvC` — APVDecoderConfigurationBox (`FullBox('apvC', version = 0, flags = 0)` containing +/// `APVDecoderConfigurationRecord`). +#[derive(Clone, Debug, PartialEq, Eq, Default)] +pub struct ApvConfig { + pub profile_idc: u8, + pub level_idc: u8, + pub band_idc: u8, + pub frame_width: u32, + pub frame_height: u32, + pub chroma_format_idc: u8, + pub bit_depth_minus8: u8, + pub capture_time_distance: u8, + pub capture_time_distance_ignored: bool, + pub color_description_present: bool, + pub color_primaries: u8, + pub transfer_characteristics: u8, + pub matrix_coefficients: u8, + pub full_range: bool, + /// Raw `APVDecoderConfigurationRecord` bytes (after the 4-byte FullBox header). + pub raw_record: Vec, +} + +impl ApvConfig { + /// Build from a raw `APVDecoderConfigurationRecord` (starting with `configurationVersion = 1`). + pub fn from_record(record: Vec) -> Result { + let mut c = Cur::labeled(&record, "apvC"); + let version = c.u8()?; + if version != 1 { + return Err(Error::Invalid(format!("unsupported APVDecoderConfigurationRecord version {version}"))); + } + let num_entries = c.u8()?; + let mut cfg = ApvConfig { raw_record: record.clone(), ..Default::default() }; + if num_entries >= 1 && c.remaining() >= 2 { + let _pbu_type = c.u8()?; + let num_fi = c.u8()?; + if num_fi >= 1 && c.remaining() >= 14 { + let flags = c.u8()?; + cfg.color_description_present = (flags & 0x02) != 0; + cfg.capture_time_distance_ignored = (flags & 0x01) != 0; + cfg.profile_idc = c.u8()?; + cfg.level_idc = c.u8()?; + cfg.band_idc = c.u8()?; + cfg.frame_width = c.u32()?; + cfg.frame_height = c.u32()?; + let cb = c.u8()?; + cfg.chroma_format_idc = cb >> 4; + cfg.bit_depth_minus8 = cb & 0x0F; + cfg.capture_time_distance = c.u8()?; + if cfg.color_description_present && c.remaining() >= 4 { + cfg.color_primaries = c.u8()?; + cfg.transfer_characteristics = c.u8()?; + cfg.matrix_coefficients = c.u8()?; + cfg.full_range = (c.u8()? & 0x80) != 0; + } + } + } + Ok(cfg) + } + + /// Parse the payload of an `apvC` box (with or without the 4-byte `FullBox` header). + pub fn parse(data: &[u8]) -> Result { + if data.len() >= 5 && data[..4] == [0, 0, 0, 0] && data[4] == 1 { + Self::from_record(data[4..].to_vec()) + } else if !data.is_empty() && data[0] == 1 { + Self::from_record(data.to_vec()) + } else { + let mut c = Cur::labeled(data, "apvC"); + let (v, _) = c.full_header()?; + if v != 0 { + return Err(Error::Invalid(format!("unsupported apvC FullBox version {v}"))); + } + Self::from_record(c.rest().to_vec()) + } + } + + /// Serialize the full `apvC` box payload (4-byte `FullBox` header + `APVDecoderConfigurationRecord`). + pub fn to_bytes(&self) -> Vec { + [&[0u8; 4][..], &self.record_bytes()].concat() // FullBox version = 0, flags = 0 + } + + /// Serialize the bare `APVDecoderConfigurationRecord` (Matroska's `CodecPrivate` for `V_APV`). + pub fn record_bytes(&self) -> Vec { + if !self.raw_record.is_empty() { + return self.raw_record.clone(); + } + let mut b = BoxBuf::new(); + b.u8(1); // configurationVersion = 1 + b.u8(1); // number_of_configuration_entry = 1 + b.u8(1); // pbu_type = 1 (primary frame) + b.u8(1); // number_of_frame_info = 1 + let flags = (if self.color_description_present { 0x02 } else { 0 }) | (if self.capture_time_distance_ignored { 0x01 } else { 0 }); + b.u8(flags); + b.u8(self.profile_idc); + b.u8(self.level_idc); + b.u8(self.band_idc); + b.u32(self.frame_width); + b.u32(self.frame_height); + b.u8((self.chroma_format_idc << 4) | (self.bit_depth_minus8 & 0x0F)); + b.u8(self.capture_time_distance); + if self.color_description_present { + b.u8(self.color_primaries); + b.u8(self.transfer_characteristics); + b.u8(self.matrix_coefficients); + b.u8(if self.full_range { 0x80 } else { 0 }); + } + b.buf + } +} + +// --------------------------------------------------------------------------------------------- +// Parsing + +fn is_video_fourcc(f: &[u8; 4]) -> bool { + matches!( + f, + b"avc1" + | b"avc3" + | b"hvc1" + | b"hev1" + | b"av01" + | b"vp09" + | b"vp08" + | b"apch" + | b"apcn" + | b"apcs" + | b"apco" + | b"ap4h" + | b"ap4x" + | b"apv1" + | b"jpeg" + | b"mjpa" + | b"mjpb" + | b"AVdn" + | b"AVdh" + | b"mp4v" + | b"encv" + | b"raw " + | b"2vuy" + | b"v210" + ) +} + +fn is_audio_fourcc(f: &[u8; 4]) -> bool { + matches!( + f, + b"mp4a" + | b"lpcm" + | b"sowt" + | b"twos" + | b"in24" + | b"in32" + | b"fl32" + | b"fl64" + | b"ipcm" + | b"fpcm" + | b"alac" + | b"Opus" + | b"fLaC" + | b"ac-3" + | b"ec-3" + | b".mp3" + | b".mp2" + | b"enca" + | b"ulaw" + | b"alaw" + | b"NONE" + ) +} + +/// Parse one `stsd` entry. `handler` is the track handler type; `is_qt` selects QuickTime +/// interpretation of the sound description version field. +pub(crate) fn parse_sample_entry(format: FourCc, payload: &[u8], handler: FourCc, is_qt: bool) -> Result { + let mut c = Cur::labeled(payload, "sample entry"); + c.skip(6)?; + let data_reference_index = c.u16()?; + let f = &format.0; + let unknown = || CodecConfig::Unknown { fourcc: format, raw: payload.to_vec() }; + if f == b"tmcd" || (handler == b"tmcd" && !is_video_fourcc(f)) { + let mut tc = TimecodeConfig::default(); + c.skip(4)?; + tc.flags = c.u32()?; + tc.timescale = c.u32()?; + tc.frame_duration = c.u32()?; + tc.frames_per_second = c.u8()?; + c.skip(1)?; + for b in boxes(c.rest()).map_while(|b| b.ok()) { + if b.kind == b"name" && b.payload.len() >= 4 { + let n = u16::from_be_bytes([b.payload[0], b.payload[1]]) as usize; + let s = b.payload.get(4..4 + n).unwrap_or(&b.payload[4..]); + tc.name = Some(String::from_utf8_lossy(s).into_owned()); + } + } + return Ok(SampleEntry { format, data_reference_index, codec: CodecConfig::Timecode(tc), video: None, audio: None, bitrate: None }); + } + // `raw ` names both uncompressed video and 8-bit unsigned PCM; the handler decides. + let raw_audio = f == b"raw " && handler == b"soun"; + let video_like = (is_video_fourcc(f) && !raw_audio) || (handler == b"vide" && !is_audio_fourcc(f)); + let audio_like = is_audio_fourcc(f) || (handler == b"soun" && !video_like); + if video_like { + let mut v = VideoParams::default(); + let _version = c.u16()?; + let _revision = c.u16()?; + v.vendor = c.fourcc()?; + v.temporal_quality = c.u32()?; + v.spatial_quality = c.u32()?; + v.width = c.u16()?; + v.height = c.u16()?; + v.horiz_resolution = c.u32()?; + v.vert_resolution = c.u32()?; + c.skip(4)?; + v.frame_count = c.u16()?; + let name = c.bytes(32)?; + let n = (name[0] as usize).min(31); + v.compressor_name = String::from_utf8_lossy(&name[1..1 + n]).into_owned(); + v.depth = c.u16()?; + let _ctab = c.i16()?; + let mut codec = None; + let mut bitrate = None; + let mut log_seen = false; + for b in boxes(c.rest()).map_while(|b| b.ok()) { + let p = b.payload; + match &b.kind.0 { + b"avcC" if matches!(f, b"avc1" | b"avc3") => codec = Some(CodecConfig::Avc(AvcConfig::parse(p)?)), + b"hvcC" if matches!(f, b"hvc1" | b"hev1") => codec = Some(CodecConfig::Hevc(HevcConfig::parse(p)?)), + b"av1C" if f == b"av01" => codec = Some(CodecConfig::Av1(Av1Config::parse(p)?)), + b"vpcC" if f == b"vp09" => codec = Some(CodecConfig::Vp9(VpcConfig::parse(p)?)), + b"apvC" if f == b"apv1" => codec = Some(CodecConfig::Apv(ApvConfig::parse(p)?)), + b"colr" => v.color = parse_colr(p).ok(), + b"logs" => { + // Two identifiers are ambiguous: neither is believed. + v.log_transfer_function = + if log_seen { None } else { std::str::from_utf8(p).ok().filter(|s| valid_log_identifier(s)).map(str::to_owned) }; + log_seen = true; + } + b"mdcv" => v.mastering_display = MasteringDisplay::parse(p), + b"clli" if p.len() >= 4 => v.content_light = Some((u16::from_be_bytes([p[0], p[1]]), u16::from_be_bytes([p[2], p[3]]))), + b"pasp" => { + let mut c = Cur::labeled(p, "pasp"); + v.pixel_aspect = Some((c.u32()?, c.u32()?)); + } + b"clap" => { + let mut c = Cur::labeled(p, "clap"); + v.clean_aperture = Some(CleanAperture { + width: (c.u32()?, c.u32()?), + height: (c.u32()?, c.u32()?), + horiz_offset: (c.i32()?, c.u32()?), + vert_offset: (c.i32()?, c.u32()?), + }); + } + b"fiel" => { + let mut c = Cur::labeled(p, "fiel"); + v.field_info = Some(FieldInfo { fields: c.u8()?, detail: c.u8()? }); + } + b"gama" => v.gamma = Some(Cur::labeled(p, "gama").u32()?), + b"btrt" => bitrate = Some(parse_btrt(p)?), + _ => {} + } + } + let codec = match codec { + Some(c) => c, + None => match f { + b"apch" | b"apcn" | b"apcs" | b"apco" | b"ap4h" | b"ap4x" => CodecConfig::ProRes { fourcc: format }, + b"jpeg" | b"mjpa" | b"mjpb" => CodecConfig::Jpeg { fourcc: format }, + b"AVdn" | b"AVdh" => CodecConfig::Dnx { fourcc: format }, + b"apv1" => CodecConfig::Apv(ApvConfig::default()), + _ => unknown(), + }, + }; + return Ok(SampleEntry { format, data_reference_index, codec, video: Some(v), audio: None, bitrate }); + } + if audio_like { + let mut a = AudioParams { qt_version: c.u16()?, ..Default::default() }; + let _revision = c.u16()?; + let _vendor = c.u32()?; + a.channels = c.u16()? as u32; + a.sample_size = c.u16()?; + a.compression_id = c.i16()?; + let _packet_size = c.u16()?; + a.sample_rate = c.u32()? as f64 / 65536.0; + if is_qt && a.qt_version == 1 { + a.samples_per_packet = c.u32()?; + a.bytes_per_packet = c.u32()?; + a.bytes_per_frame = c.u32()?; + a.bytes_per_sample = c.u32()?; + } else if is_qt && a.qt_version == 2 { + let _size_of_struct = c.u32()?; + a.sample_rate = c.f64()?; + a.channels = c.u32()?; + if a.channels > u32::from(u16::MAX) { + return Err(Error::Invalid(format!("QuickTime v2 sound entry with {} channels", a.channels))); + } + let _always = c.u32()?; + a.const_bits_per_channel = c.u32()?; + a.lpcm_flags = c.u32()?; + a.const_bytes_per_packet = c.u32()?; + a.const_frames_per_packet = c.u32()?; + } + // Flatten QuickTime `wave` children into the list of extension boxes. + let mut ext: Vec<(FourCc, &[u8])> = Vec::new(); + for b in boxes(c.rest()).map_while(|b| b.ok()) { + if b.kind == b"wave" { + for w in boxes(b.payload).map_while(|b| b.ok()) { + ext.push((w.kind, w.payload)); + } + } else { + ext.push((b.kind, b.payload)); + } + } + let get = |k: &[u8; 4]| ext.iter().find(|(kk, _)| kk == k).map(|(_, p)| *p); + if let Some(p) = get(b"enda") { + let v = if p.len() >= 2 { u16::from_be_bytes([p[0], p[1]]) } else { p.first().copied().unwrap_or(0) as u16 }; + a.little_endian = Some(v != 0); + } + let bitrate = get(b"btrt").and_then(|p| parse_btrt(p).ok()); + let codec = match f { + b"mp4a" => match get(b"esds") { + Some(p) => parse_esds(p)?, + None => unknown(), + }, + b".mp3" | b".mp2" => CodecConfig::Mp3, + b"alac" => match get(b"alac") { + Some(p) if p.len() >= 4 => CodecConfig::Alac { cookie: p[4..].to_vec() }, + _ => unknown(), + }, + b"Opus" => match get(b"dOps") { + Some(p) => CodecConfig::Opus(OpusConfig::parse(p)?), + None => unknown(), + }, + b"fLaC" => match get(b"dfLa") { + Some(p) => CodecConfig::Flac(FlacConfig::parse(p)?), + None => unknown(), + }, + b"ac-3" => CodecConfig::Ac3 { dac3: get(b"dac3").unwrap_or(&[]).to_vec() }, + b"ec-3" => CodecConfig::Eac3 { dec3: get(b"dec3").unwrap_or(&[]).to_vec() }, + b"lpcm" | b"sowt" | b"twos" | b"in24" | b"in32" | b"fl32" | b"fl64" | b"raw " | b"NONE" => CodecConfig::Pcm(qt_pcm(f, &a)?), + b"ipcm" | b"fpcm" => { + let mut pcm = PcmConfig { + bits: a.sample_size, + float: f == b"fpcm", + big_endian: true, + signed: true, + channels: a.channels, + sample_rate: a.sample_rate, + }; + if let Some(p) = get(b"pcmC") { + let mut c = Cur::labeled(p, "pcmC"); + c.full_header()?; + let flags = c.u8()?; + pcm.big_endian = flags & 1 == 0; + pcm.bits = c.u8()? as u16; + } + CodecConfig::Pcm(pcm) + } + _ => unknown(), + }; + return Ok(SampleEntry { format, data_reference_index, codec, video: None, audio: Some(a), bitrate }); + } + Ok(SampleEntry { format, data_reference_index, codec: unknown(), video: None, audio: None, bitrate: None }) +} + +fn qt_pcm(f: &[u8; 4], a: &AudioParams) -> Result { + let mut p = PcmConfig { channels: a.channels, sample_rate: a.sample_rate, signed: true, ..Default::default() }; + match f { + b"lpcm" => { + p.bits = u16::try_from(a.const_bits_per_channel) + .map_err(|_| Error::Invalid(format!("lpcm with {} bits per channel", a.const_bits_per_channel)))?; + p.float = a.lpcm_flags & 1 != 0; + p.big_endian = a.lpcm_flags & 2 != 0; + p.signed = a.lpcm_flags & 4 != 0 || p.float; + if p.bits == 0 { + p.bits = a.sample_size; + } + } + b"sowt" => { + p.bits = if a.sample_size == 0 { 16 } else { a.sample_size }; + } + b"twos" => { + p.bits = if a.sample_size == 0 { 16 } else { a.sample_size }; + p.big_endian = true; + } + b"raw " | b"NONE" => { + p.bits = if a.sample_size == 0 { 8 } else { a.sample_size }; + p.signed = p.bits != 8; + p.big_endian = true; + } + b"in24" | b"in32" | b"fl32" | b"fl64" => { + p.bits = match f { + b"in24" => 24, + b"in32" | b"fl32" => 32, + _ => 64, + }; + p.float = f[0] == b'f'; + p.big_endian = !a.little_endian.unwrap_or(false); + } + _ => {} + } + Ok(p) +} + +fn parse_btrt(p: &[u8]) -> Result { + let mut c = Cur::labeled(p, "btrt"); + Ok(BitRate { buffer_size: c.u32()?, max_bitrate: c.u32()?, avg_bitrate: c.u32()? }) +} + +fn parse_colr(p: &[u8]) -> Result { + let mut c = Cur::labeled(p, "colr"); + let kind = c.fourcc()?; + Ok(match &kind.0 { + b"nclx" => { + ColorInfo::Nclx { primaries: c.u16()?, transfer: c.u16()?, matrix: c.u16()?, full_range: c.u8().map(|v| v & 0x80 != 0).unwrap_or(false) } + } + b"nclc" => ColorInfo::Nclc { primaries: c.u16()?, transfer: c.u16()?, matrix: c.u16()? }, + _ => ColorInfo::Icc { kind, profile: c.rest().to_vec() }, + }) +} + +fn descriptor(c: &mut Cur) -> Result<(u8, usize)> { + let tag = c.u8()?; + let mut len = 0usize; + for _ in 0..4 { + let b = c.u8()?; + len = (len << 7) | (b & 0x7F) as usize; + if b & 0x80 == 0 { + break; + } + } + Ok((tag, len)) +} + +fn parse_esds(p: &[u8]) -> Result { + let mut c = Cur::labeled(p, "esds"); + c.full_header()?; + let (tag, len) = descriptor(&mut c)?; + if tag != 3 { + return Err(Error::Invalid(format!("esds: expected ES_Descriptor, got tag {tag}"))); + } + let es = c.bytes(len.min(c.remaining()))?; + let mut c = Cur::labeled(es, "ES_Descriptor"); + c.u16()?; + let fl = c.u8()?; + if fl & 0x80 != 0 { + c.u16()?; + } + if fl & 0x40 != 0 { + let n = c.u8()? as usize; + c.skip(n)?; + } + if fl & 0x20 != 0 { + c.u16()?; + } + while c.remaining() > 0 { + let (tag, len) = descriptor(&mut c)?; + let body = c.bytes(len.min(c.remaining()))?; + if tag != 4 { + continue; + } + let mut d = Cur::labeled(body, "DecoderConfigDescriptor"); + let oti = d.u8()?; + let _stream_type = d.u8()?; + let buffer_size = d.u24()?; + let max_bitrate = d.u32()?; + let avg_bitrate = d.u32()?; + let mut asc = Vec::new(); + while d.remaining() > 0 { + let (t, l) = descriptor(&mut d)?; + let b = d.bytes(l.min(d.remaining()))?; + if t == 5 { + asc = b.to_vec(); + break; + } + } + return Ok(match oti { + 0x69 | 0x6B => CodecConfig::Mp3, + _ => { + let mut a = AacConfig::from_asc(asc); + a.max_bitrate = max_bitrate; + a.avg_bitrate = avg_bitrate; + a.buffer_size = buffer_size; + CodecConfig::Aac(a) + } + }); + } + Err(Error::Invalid("esds without DecoderConfigDescriptor".into())) +} + +// --------------------------------------------------------------------------------------------- +// Serialization (muxer) + +fn put_descriptor(b: &mut BoxBuf, tag: u8, body: &[u8]) { + b.u8(tag); + let n = body.len() as u32; + // Always use the 4-byte length form for simplicity (as many encoders do). + b.u8(0x80 | ((n >> 21) & 0x7F) as u8); + b.u8(0x80 | ((n >> 14) & 0x7F) as u8); + b.u8(0x80 | ((n >> 7) & 0x7F) as u8); + b.u8((n & 0x7F) as u8); + b.bytes(body); +} + +pub(crate) fn esds_payload(oti: u8, asc: &[u8], max_bitrate: u32, avg_bitrate: u32, buffer_size: u32) -> Vec { + let mut dcd = BoxBuf::new(); + dcd.u8(oti); + dcd.u8(0x15); // streamType audio (5) << 2 | upstream 0 | reserved 1 + dcd.u8((buffer_size >> 16) as u8); + dcd.u16(buffer_size as u16); + dcd.u32(max_bitrate); + dcd.u32(avg_bitrate); + if !asc.is_empty() { + put_descriptor(&mut dcd, 5, asc); + } + let mut es = BoxBuf::new(); + es.u16(1); // ES_ID + es.u8(0); + put_descriptor(&mut es, 4, &dcd.buf); + put_descriptor(&mut es, 6, &[2]); // SLConfigDescriptor, predefined = 2 (MP4) + let mut b = BoxBuf::new(); + b.u32(0); + put_descriptor(&mut b, 3, &es.buf); + b.buf +} + +impl SampleEntry { + /// Convenience constructor for a video entry. + pub fn video(format: FourCc, codec: CodecConfig, width: u16, height: u16) -> Self { + let compressor_name = match &codec { + CodecConfig::ProRes { fourcc } => match &fourcc.0 { + b"apch" => "Apple ProRes 422 HQ", + b"apcn" => "Apple ProRes 422", + b"apcs" => "Apple ProRes 422 LT", + b"apco" => "Apple ProRes 422 Proxy", + b"ap4h" => "Apple ProRes 4444", + _ => "Apple ProRes 4444 XQ", + }, + CodecConfig::Jpeg { .. } => "Photo - JPEG", + _ => "", + }; + SampleEntry { + format, + data_reference_index: 1, + codec, + video: Some(VideoParams { + width, + height, + horiz_resolution: 0x0048_0000, + vert_resolution: 0x0048_0000, + frame_count: 1, + compressor_name: compressor_name.into(), + depth: 24, + ..Default::default() + }), + audio: None, + bitrate: None, + } + } + + /// Convenience constructor for an audio entry (ISO v0 layout; the muxer upgrades PCM in MOV to v2). + pub fn audio(format: FourCc, codec: CodecConfig, channels: u32, sample_rate: f64, sample_size: u16) -> Self { + SampleEntry { + format, + data_reference_index: 1, + codec, + video: None, + audio: Some(AudioParams { channels, sample_rate, sample_size, ..Default::default() }), + bitrate: None, + } + } + + /// H.264 entry (`avc1`). + pub fn avc(cfg: AvcConfig, width: u16, height: u16) -> Self { + Self::video(FourCc(*b"avc1"), CodecConfig::Avc(cfg), width, height) + } + /// HEVC entry (`hvc1`, parameter sets in the config only). + pub fn hevc(cfg: HevcConfig, width: u16, height: u16) -> Self { + Self::video(FourCc(*b"hvc1"), CodecConfig::Hevc(cfg), width, height) + } + /// AV1 entry (`av01`). + pub fn av1(cfg: Av1Config, width: u16, height: u16) -> Self { + Self::video(FourCc(*b"av01"), CodecConfig::Av1(cfg), width, height) + } + /// ProRes entry; `fourcc` one of `apch`/`apcn`/`apcs`/`apco`/`ap4h`/`ap4x`. + pub fn prores(fourcc: FourCc, width: u16, height: u16) -> Self { + let mut e = Self::video(fourcc, CodecConfig::ProRes { fourcc }, width, height); + if let Some(v) = e.video.as_mut() + && matches!(&fourcc.0, b"ap4h" | b"ap4x") + { + v.depth = 32; + } + e + } + /// Avid DNxHD / DNxHR entry (`AVdn`, or `AVdh` for DNxHR). + pub fn dnx(fourcc: FourCc, width: u16, height: u16) -> Self { + let mut e = Self::video(fourcc, CodecConfig::Dnx { fourcc }, width, height); + if let Some(v) = e.video.as_mut() { + v.depth = 24; + } + e + } + /// Advanced Professional Video entry (`apv1` + `apvC`). + pub fn apv(cfg: ApvConfig, width: u16, height: u16) -> Self { + let mut e = Self::video(FourCc(*b"apv1"), CodecConfig::Apv(cfg), width, height); + if let Some(v) = e.video.as_mut() { + v.compressor_name = "APV".into(); + } + e + } + /// Motion-JPEG entry (`jpeg`). + pub fn jpeg(width: u16, height: u16) -> Self { + let f = FourCc(*b"jpeg"); + Self::video(f, CodecConfig::Jpeg { fourcc: f }, width, height) + } + /// AAC entry (`mp4a` + `esds`) from an AudioSpecificConfig. + pub fn aac(asc: Vec, channels: u32, sample_rate: u32) -> Self { + Self::audio(FourCc(*b"mp4a"), CodecConfig::Aac(AacConfig::from_asc(asc)), channels, sample_rate as f64, 16) + } + /// FLAC entry (`fLaC` + `dfLa`) from the 34-byte STREAMINFO body: the only metadata block. + pub fn flac(streaminfo: &[u8; 34]) -> Self { + let mut blocks = vec![0x80, 0, 0, 34]; + blocks.extend_from_slice(streaminfo); + let mut full = vec![0; 4]; + full.extend_from_slice(&blocks); + let cfg = FlacConfig::parse(&full).unwrap_or(FlacConfig { metadata_blocks: blocks, ..Default::default() }); + let (channels, rate, bits) = (u32::from(cfg.channels), f64::from(cfg.sample_rate), u16::from(cfg.bits_per_sample)); + Self::audio(FourCc(*b"fLaC"), CodecConfig::Flac(cfg), channels, rate, bits) + } + /// PCM entry. The muxer picks the on-disk format (`sowt`/`twos`/`lpcm` for MOV, `ipcm`/`fpcm` for MP4). + pub fn pcm(cfg: PcmConfig) -> Self { + Self::audio(FourCc(*b"lpcm"), CodecConfig::Pcm(cfg), cfg.channels, cfg.sample_rate, cfg.bits) + } + + /// Serialize as a complete sample entry box. For PCM the format is chosen from the brand. + pub(crate) fn write(&self, b: &mut BoxBuf, qt: bool) -> Result<()> { + // An identifier the reader would not accept is refused, not truncated. + if self.video.as_ref().and_then(|v| v.log_transfer_function.as_deref()).is_some_and(|s| !valid_log_identifier(s)) { + return Err(Error::Invalid("invalid log transfer-function identifier".into())); + } + if let CodecConfig::Unknown { fourcc, raw } = &self.codec { + let m = b.start(&fourcc.0); + b.bytes(raw); + b.end(m); + return Ok(()); + } + if let CodecConfig::Timecode(tc) = &self.codec { + let m = b.start(b"tmcd"); + b.zeros(6); + b.u16(self.data_reference_index); + b.u32(0); + b.u32(tc.flags); + b.u32(tc.timescale); + b.u32(tc.frame_duration); + b.u8(tc.frames_per_second); + b.u8(0); + if let Some(name) = &tc.name { + let n = b.start(b"name"); + b.u16(name.len() as u16); + b.u16(0); + b.bytes(name.as_bytes()); + b.end(n); + } + b.end(m); + return Ok(()); + } + if let Some(v) = &self.video { + self.write_video(b, v); + return Ok(()); + } + let a = self.audio.clone().ok_or_else(|| Error::Mux("sample entry has neither video nor audio params".into()))?; + // Choose the on-disk format and sound description version. + let (format, version, pcm) = match &self.codec { + CodecConfig::Pcm(p) => { + if qt { + // Version 0 stores the rate as 16.16 fixed point; `raw ` is unsigned and + // `twos`/`sowt` are signed. Everything else needs `lpcm` v2. + let v0_rate = p.sample_rate < 65536.0; + if v0_rate && p.bits == 16 && !p.float && p.signed { + (if p.big_endian { *b"twos" } else { *b"sowt" }, 0u16, Some(*p)) + } else if v0_rate && p.bits == 8 && !p.float { + (if p.signed { *b"twos" } else { *b"raw " }, 0, Some(*p)) + } else { + (*b"lpcm", 2, Some(*p)) + } + } else { + (if p.float { *b"fpcm" } else { *b"ipcm" }, 0, Some(*p)) + } + } + _ => (self.format.0, if qt { a.qt_version.min(2) } else { 0 }, None), + }; + let m = b.start(&format); + b.zeros(6); + b.u16(self.data_reference_index); + if version == 2 { + let p = pcm.unwrap_or_default(); + b.u16(2); + b.u16(0); + b.u32(0); + b.u16(3); + b.u16(16); + b.i16(-2); + b.u16(0); + b.u32(65536); + b.u32(72); + b.f64(p.sample_rate); + b.u32(p.channels); + b.u32(0x7F00_0000); + b.u32(p.bits as u32); + let flags = (p.float as u32) | ((p.big_endian as u32) << 1) | (((p.signed && !p.float) as u32) << 2) | 8; + b.u32(flags); + b.u32(p.bytes_per_frame()); + b.u32(1); + } else { + b.u16(version); + b.u16(0); + b.u32(0); + b.u16(a.channels.min(u16::MAX as u32) as u16); + b.u16(match pcm { + Some(p) => p.bits, + None => { + if a.sample_size == 0 { + 16 + } else { + a.sample_size + } + } + }); + b.i16(if version == 1 { a.compression_id } else { 0 }); + b.u16(0); + let sr = if a.sample_rate < 65536.0 { (a.sample_rate * 65536.0).round() as u32 } else { 0 }; + b.u32(sr); + if version == 1 { + b.u32(a.samples_per_packet); + b.u32(a.bytes_per_packet); + b.u32(a.bytes_per_frame); + b.u32(a.bytes_per_sample); + } + } + match &self.codec { + CodecConfig::Aac(c) => { + b.leaf(b"esds", &esds_payload(0x40, &c.asc, c.max_bitrate, c.avg_bitrate, c.buffer_size)); + } + CodecConfig::Mp3 if format == *b"mp4a" => { + b.leaf(b"esds", &esds_payload(0x6B, &[], 0, 0, 0)); + } + CodecConfig::Alac { cookie } => { + let m = b.start_full(b"alac", 0, 0); + b.bytes(cookie); + b.end(m); + } + CodecConfig::Opus(o) => b.leaf(b"dOps", &o.to_bytes()), + CodecConfig::Flac(fl) => { + let m = b.start_full(b"dfLa", 0, 0); + b.bytes(&fl.metadata_blocks); + b.end(m); + } + CodecConfig::Ac3 { dac3 } => b.leaf(b"dac3", dac3), + CodecConfig::Eac3 { dec3 } => b.leaf(b"dec3", dec3), + CodecConfig::Pcm(p) if !qt => { + let m = b.start_full(b"pcmC", 0, 0); + b.u8(if p.big_endian { 0 } else { 1 }); + b.u8(p.bits as u8); + b.end(m); + } + CodecConfig::Pcm(p) if p.channels == 6 => { + // QuickTime channel layout: kAudioChannelLayoutTag_MPEG_5_1_A (L R C LFE Ls Rs) + let m = b.start_full(b"chan", 0, 0); + b.u32((121 << 16) | 6); + b.u32(0); + b.u32(0); + b.end(m); + } + _ => {} + } + if let Some(br) = self.bitrate { + write_btrt(b, br); + } + b.end(m); + Ok(()) + } + + fn write_video(&self, b: &mut BoxBuf, v: &VideoParams) { + let m = b.start(&self.format.0); + b.zeros(6); + b.u16(self.data_reference_index); + b.u16(0); + b.u16(0); + b.u32(v.vendor.as_u32()); + b.u32(v.temporal_quality); + b.u32(v.spatial_quality); + b.u16(v.width); + b.u16(v.height); + b.u32(v.horiz_resolution); + b.u32(v.vert_resolution); + b.u32(0); + b.u16(v.frame_count); + let name = v.compressor_name.as_bytes(); + let n = name.len().min(31); + let mut nb = [0u8; 32]; + nb[0] = n as u8; + nb[1..1 + n].copy_from_slice(&name[..n]); + b.bytes(&nb); + b.u16(v.depth); + b.i16(-1); + write_video_codec_config(b, &self.codec); + write_video_descriptive_boxes(b, v); + if let Some(br) = self.bitrate { + write_btrt(b, br); + } + b.end(m); + } +} + +fn write_video_codec_config(b: &mut BoxBuf, codec: &CodecConfig) { + match codec { + CodecConfig::Avc(config) => b.leaf(b"avcC", &config.to_bytes()), + CodecConfig::Hevc(config) => b.leaf(b"hvcC", &config.to_bytes()), + CodecConfig::Av1(config) => b.leaf(b"av1C", &config.to_bytes()), + CodecConfig::Vp9(config) => b.leaf(b"vpcC", &config.to_bytes()), + CodecConfig::Apv(config) => b.leaf(b"apvC", &config.to_bytes()), + _ => {} + } +} + +/// What a `logs` box may hold: a non-empty identifier of at most 255 bytes with no NUL. +fn valid_log_identifier(s: &str) -> bool { + !s.is_empty() && s.len() <= 255 && !s.as_bytes().contains(&0) +} + +fn write_video_descriptive_boxes(b: &mut BoxBuf, v: &VideoParams) { + if let Some(gamma) = v.gamma { + b.leaf(b"gama", &gamma.to_be_bytes()); + } + if let Some(field_info) = v.field_info { + b.leaf(b"fiel", &[field_info.fields, field_info.detail]); + } + if let Some(color) = &v.color { + write_color_box(b, color); + } + if let Some(log) = &v.log_transfer_function { + b.leaf(b"logs", log.as_bytes()); + } + if let Some(display) = &v.mastering_display { + b.leaf(b"mdcv", &display.to_bytes()); + } + if let Some((cll, fall)) = v.content_light { + let mut data = cll.to_be_bytes().to_vec(); + data.extend_from_slice(&fall.to_be_bytes()); + b.leaf(b"clli", &data); + } + write_pixel_aspect_box(b, v.pixel_aspect); + write_clean_aperture_box(b, v.clean_aperture); +} + +fn write_color_box(b: &mut BoxBuf, color: &ColorInfo) { + let m = b.start(b"colr"); + match color { + ColorInfo::Nclx { primaries, transfer, matrix, full_range } => { + b.bytes(b"nclx"); + b.u16(*primaries); + b.u16(*transfer); + b.u16(*matrix); + b.u8(if *full_range { 0x80 } else { 0 }); + } + ColorInfo::Nclc { primaries, transfer, matrix } => { + b.bytes(b"nclc"); + b.u16(*primaries); + b.u16(*transfer); + b.u16(*matrix); + } + ColorInfo::Icc { kind, profile } => { + b.bytes(&kind.0); + b.bytes(profile); + } + } + b.end(m); +} + +fn write_pixel_aspect_box(b: &mut BoxBuf, pixel_aspect: Option<(u32, u32)>) { + if let Some((horizontal, vertical)) = pixel_aspect { + let m = b.start(b"pasp"); + b.u32(horizontal); + b.u32(vertical); + b.end(m); + } +} + +fn write_clean_aperture_box(b: &mut BoxBuf, clean_aperture: Option) { + if let Some(aperture) = clean_aperture { + let m = b.start(b"clap"); + b.u32(aperture.width.0); + b.u32(aperture.width.1); + b.u32(aperture.height.0); + b.u32(aperture.height.1); + b.i32(aperture.horiz_offset.0); + b.u32(aperture.horiz_offset.1); + b.i32(aperture.vert_offset.0); + b.u32(aperture.vert_offset.1); + b.end(m); + } +} + +fn write_btrt(b: &mut BoxBuf, br: BitRate) { + let m = b.start(b"btrt"); + b.u32(br.buffer_size); + b.u32(br.max_bitrate); + b.u32(br.avg_bitrate); + b.end(m); +} + +#[cfg(test)] +mod tests { + use super::*; + + fn roundtrip(e: &SampleEntry, qt: bool, handler: &[u8; 4]) -> SampleEntry { + let mut b = BoxBuf::new(); + e.write(&mut b, qt).unwrap(); + let bx = crate::isobmff::bytes::boxes(&b.buf).next().unwrap().unwrap(); + parse_sample_entry(bx.kind, bx.payload, FourCc(*handler), qt).unwrap() + } + + /// A QuickTime `logs` box keeps its identifier whatever curve it names; the reader does not + /// guess what an unknown one means. + #[test] + fn log_transfer_function_roundtrip() { + for id in ["com.apple.rec2020.apple-log", "com.apple.rec2020.apple-log2", "another.vendor.unknown-curve"] { + let mut e = SampleEntry::prores(FourCc(*b"apch"), 64, 64); + e.video.as_mut().unwrap().log_transfer_function = Some(id.into()); + let back = roundtrip(&e, true, b"vide"); + assert_eq!(back.video.as_ref().unwrap().log_transfer_function.as_deref(), Some(id)); + assert_eq!(back, e); + } + // Apple Log is a 35-byte box: the 27 identifier bytes with no terminator. + let mut e = SampleEntry::prores(FourCc(*b"apch"), 64, 64); + e.video.as_mut().unwrap().log_transfer_function = Some("com.apple.rec2020.apple-log".into()); + let mut b = BoxBuf::new(); + e.write(&mut b, true).unwrap(); + let logs = [&35u32.to_be_bytes()[..], b"logscom.apple.rec2020.apple-log"].concat(); + assert!(b.buf.windows(logs.len()).any(|w| w == logs)); + } + + /// The writer refuses an identifier the reader would not accept; it is never truncated. + #[test] + fn invalid_log_transfer_functions_are_not_written() { + for id in [String::new(), "a".repeat(256), "com.apple.rec2020.apple-log\0".into()] { + let mut e = SampleEntry::prores(FourCc(*b"apch"), 64, 64); + e.video.as_mut().unwrap().log_transfer_function = Some(id); + assert!(e.write(&mut BoxBuf::new(), true).is_err()); + } + let mut e = SampleEntry::prores(FourCc(*b"apch"), 64, 64); + e.video.as_mut().unwrap().log_transfer_function = Some("a".repeat(255)); + assert!(e.write(&mut BoxBuf::new(), true).is_ok()); + } + + /// An empty, oversized, non-UTF-8 or NUL-holding `logs` box, or two of them, reads as unknown. + #[test] + fn malformed_or_duplicate_logs_boxes_read_as_unknown() { + let read = |children: &[&[u8]]| { + let mut b = BoxBuf::new(); + SampleEntry::prores(FourCc(*b"apch"), 64, 64).write(&mut b, true).unwrap(); + for payload in children { + b.leaf(b"logs", payload); + } + let len = (b.buf.len() as u32).to_be_bytes(); + b.buf[..4].copy_from_slice(&len); + let bx = crate::isobmff::bytes::boxes(&b.buf).next().unwrap().unwrap(); + parse_sample_entry(bx.kind, bx.payload, FourCc(*b"vide"), true).unwrap().video.unwrap().log_transfer_function + }; + assert_eq!(read(&[b"vendor.curve"]).as_deref(), Some("vendor.curve")); + assert_eq!(read(&[b""]), None); + assert_eq!(read(&[&[b'a'; 256]]), None); + assert_eq!(read(&[b"bad\xFFutf8"]), None); + assert_eq!(read(&[b"nul\0inside"]), None); + assert_eq!(read(&[b"vendor.curve", b"vendor.curve"]), None); + assert_eq!(read(&[b"vendor.curve", b""]), None); + } + + #[test] + fn avcc_roundtrip() { + let cfg = AvcConfig::new(vec![vec![0x67, 0x64, 0x00, 0x1F, 0xAC]], vec![vec![0x68, 0xEB]], 4); + assert_eq!(cfg.profile, 0x64); + assert_eq!(AvcConfig::parse(&cfg.to_bytes()).unwrap(), cfg); + let mut e = SampleEntry::avc(cfg, 1920, 1080); + e.video.as_mut().unwrap().color = Some(ColorInfo::Nclx { primaries: 1, transfer: 1, matrix: 1, full_range: false }); + e.video.as_mut().unwrap().pixel_aspect = Some((4, 3)); + e.video.as_mut().unwrap().field_info = Some(FieldInfo { fields: 2, detail: 9 }); + e.video.as_mut().unwrap().clean_aperture = + Some(CleanAperture { width: (1920, 1), height: (1080, 1), horiz_offset: (-2, 1), vert_offset: (0, 1) }); + e.video.as_mut().unwrap().mastering_display = Some(MasteringDisplay::bt2020(1000.0, 0.0001)); + e.video.as_mut().unwrap().content_light = Some((1000, 400)); + e.bitrate = Some(BitRate { buffer_size: 1, max_bitrate: 2, avg_bitrate: 3 }); + assert_eq!(roundtrip(&e, false, b"vide"), e); + assert_eq!(MasteringDisplay::bt2020(1000.0, 0.0001).max_nits(), 1000.0); + } + + #[test] + fn hvcc_roundtrip() { + let cfg = HevcConfig { + general_profile_idc: 1, + general_profile_compatibility_flags: 0x6000_0000, + general_constraint_indicator_flags: 0x9000_0000_0000, + general_level_idc: 93, + chroma_format_idc: 1, + bit_depth_luma: 8, + bit_depth_chroma: 8, + length_size: 4, + num_temporal_layers: 1, + temporal_id_nested: true, + arrays: vec![ + HevcNalArray { completeness: true, nal_type: 32, nalus: vec![vec![0x40, 1]] }, + HevcNalArray { completeness: true, nal_type: 33, nalus: vec![vec![0x42, 1, 2]] }, + HevcNalArray { completeness: true, nal_type: 34, nalus: vec![vec![0x44, 1]] }, + ], + ..Default::default() + }; + let back = HevcConfig::parse(&cfg.to_bytes()).unwrap(); + assert_eq!(back, cfg); + assert_eq!(back.sps(), vec![&[0x42u8, 1, 2][..]]); + } + + #[test] + fn av1_vp9_opus_roundtrip() { + let a = Av1Config { seq_profile: 1, seq_level_idx_0: 8, high_bitdepth: true, config_obus: vec![1, 2], ..Default::default() }; + assert_eq!(Av1Config::parse(&a.to_bytes()).unwrap(), a); + let v = VpcConfig { + profile: 2, + level: 31, + bit_depth: 10, + chroma_subsampling: 1, + full_range: true, + colour_primaries: 9, + transfer_characteristics: 16, + matrix_coefficients: 9, + codec_init: vec![], + }; + assert_eq!(VpcConfig::parse(&v.to_bytes()).unwrap(), v); + let o = OpusConfig { + output_channels: 2, + pre_skip: 312, + input_sample_rate: 48000, + output_gain: 0, + channel_mapping_family: 0, + channel_mapping: vec![], + }; + assert_eq!(OpusConfig::parse(&o.to_bytes()).unwrap(), o); + } + + #[test] + fn aac_channel_configuration_is_an_index() { + // 48 kHz AAC LC: configuration → channels (Table 1.19 with Amd 4; #922) + let channels = |c: u16| AacConfig::from_asc(((2 << 11) | (3 << 7) | (c << 3)).to_be_bytes().to_vec()).channels(); + assert_eq!([0, 1, 6, 7, 8, 11, 12, 13, 14, 15].map(channels), [0, 1, 6, 8, 0, 7, 8, 24, 8, 0]); + } + + #[test] + fn aac_esds_roundtrip() { + let e = SampleEntry::aac(vec![0x12, 0x10], 2, 44100); + match &e.codec { + CodecConfig::Aac(a) => { + assert_eq!((a.object_type, a.sample_rate, a.channel_config), (2, 44100, 2)); + } + _ => panic!(), + } + assert_eq!(roundtrip(&e, false, b"soun"), e); + assert_eq!(roundtrip(&e, true, b"soun"), e); + } + + /// QuickTime's `.mp2` entry (what ffmpeg writes for MP2 in MOV) is MPEG audio, as `.mp3` is, + /// even under a handler that does not say "sound" (#800). + #[test] + fn quicktime_mpeg_audio_entries() { + for fourcc in [*b".mp3", *b".mp2"] { + let e = SampleEntry::audio(FourCc(fourcc), CodecConfig::Mp3, 2, 48000.0, 16); + for handler in [b"soun", b"\0\0\0\0"] { + let back = roundtrip(&e, true, handler); + assert_eq!(back.codec, CodecConfig::Mp3, "{fourcc:?} {handler:?}"); + assert_eq!(back.audio.map(|a| (a.channels, a.sample_rate)), Some((2, 48000.0)), "{fourcc:?} {handler:?}"); + } + } + } + + fn qt_v2_lpcm(channels: u32, bits: u32) -> Vec { + let mut p = vec![0; 6]; + let u16b = |p: &mut Vec, v: u16| p.extend(v.to_be_bytes()); + let u32b = |p: &mut Vec, v: u32| p.extend(v.to_be_bytes()); + u16b(&mut p, 1); + u16b(&mut p, 2); + u16b(&mut p, 0); + u32b(&mut p, 0); + u16b(&mut p, 2); + u16b(&mut p, 16); + u16b(&mut p, 0); + u16b(&mut p, 0); + u32b(&mut p, 65536); + u32b(&mut p, 72); + p.extend(48000.0f64.to_be_bytes()); + u32b(&mut p, channels); + u32b(&mut p, 0); + u32b(&mut p, bits); + u32b(&mut p, 0); + u32b(&mut p, 0); + u32b(&mut p, 1); + p + } + + #[test] + fn pcm_frame_size_saturates_on_a_hostile_channel_count() { + assert_eq!(PcmConfig { bits: 16, channels: 2, sample_rate: 48000.0, ..Default::default() }.bytes_per_frame(), 4); + assert_eq!(PcmConfig { bits: 24, channels: 0, ..Default::default() }.bytes_per_frame(), 3); + assert_eq!(PcmConfig { bits: 16, channels: u32::MAX, ..Default::default() }.bytes_per_frame(), u32::MAX); + let ok = parse_sample_entry(FourCc(*b"lpcm"), &qt_v2_lpcm(2, 16), FourCc(*b"soun"), true).unwrap(); + assert!(matches!(ok.codec, CodecConfig::Pcm(p) if p.bytes_per_frame() == 4)); + } + + #[test] + fn qt_v2_pcm_rejects_channels_and_bits_past_16_bits() { + let entry = |channels, bits| parse_sample_entry(FourCc(*b"lpcm"), &qt_v2_lpcm(channels, bits), FourCc(*b"soun"), true); + assert!(matches!(entry(u32::MAX, 16), Err(Error::Invalid(_)))); + assert!(matches!(entry(65_536, 16), Err(Error::Invalid(_)))); + assert!(entry(65_535, 16).is_ok()); + // 0x0001_0010 would read as 16-bit PCM, and 0x0001_0000 would fall back to the sample size. + assert!(matches!(entry(2, 0x0001_0010), Err(Error::Invalid(_)))); + assert!(matches!(entry(2, 0x0001_0000), Err(Error::Invalid(_)))); + let ok = entry(2, 24).unwrap(); + assert!(matches!(ok.codec, CodecConfig::Pcm(p) if p.bits == 24)); + } + + #[test] + fn pcm_entries() { + for (bits, float, be, qt) in [ + (16, false, false, true), + (16, false, true, true), + (24, false, false, true), + (32, true, false, true), + (24, false, true, false), + (32, true, false, false), + ] { + let p = PcmConfig { bits, float, big_endian: be, signed: true, channels: 2, sample_rate: 48000.0 }; + let e = SampleEntry::pcm(p); + let back = roundtrip(&e, qt, b"soun"); + assert_eq!(back.codec, CodecConfig::Pcm(p), "{bits} {float} {be} {qt}"); + } + } + + #[test] + fn mov_pcm_keeps_high_rates_and_signedness() { + let pcm = |bits, signed, sample_rate| PcmConfig { bits, float: false, big_endian: true, signed, channels: 2, sample_rate }; + for (p, format) in [ + (pcm(16, true, 48000.0), b"twos"), + (pcm(16, true, 96000.0), b"lpcm"), + (pcm(16, false, 48000.0), b"lpcm"), + (pcm(8, false, 48000.0), b"raw "), + (pcm(8, true, 48000.0), b"twos"), + (pcm(8, false, 192000.0), b"lpcm"), + ] { + let mut b = BoxBuf::new(); + SampleEntry::pcm(p).write(&mut b, true).unwrap(); + let bx = crate::isobmff::bytes::boxes(&b.buf).next().unwrap().unwrap(); + assert_eq!(&bx.kind.0, format, "{p:?}"); + let back = roundtrip(&SampleEntry::pcm(p), true, b"soun"); + assert_eq!(back.codec, CodecConfig::Pcm(p)); + assert_eq!(back.audio.unwrap().sample_rate, p.sample_rate); + } + } + + #[test] + fn timecode_and_prores() { + let tc = + TimecodeConfig { flags: 1, timescale: 30000, frame_duration: 1001, frames_per_second: 30, start_frame: None, name: Some("reel".into()) }; + let e = SampleEntry { + format: FourCc(*b"tmcd"), + data_reference_index: 1, + codec: CodecConfig::Timecode(tc.clone()), + video: None, + audio: None, + bitrate: None, + }; + assert_eq!(roundtrip(&e, true, b"tmcd"), e); + assert_eq!(tc.format_frame(107892), "01:00:00;00"); + let nd = TimecodeConfig { flags: 0, frames_per_second: 24, ..Default::default() }; + assert_eq!(nd.format_frame(86400), "01:00:00:00"); + let p = SampleEntry::prores(FourCc(*b"apch"), 1920, 1080); + assert_eq!(roundtrip(&p, true, b"vide"), p); + } + + #[test] + fn asc_parse() { + assert_eq!(parse_asc(&[0x11, 0x90]), Some((2, 48000, 2))); + assert_eq!(parse_asc(&[]), None); + } +} + +#[cfg(test)] +mod params_tests { + use super::*; + + /// `dOps` is big-endian; the `OpusHead` it becomes is little-endian, with the mapping table + /// only for families other than 0. + #[test] + fn dops_becomes_an_opus_head() { + let o = OpusConfig { + output_channels: 6, + pre_skip: 312, + input_sample_rate: 48_000, + output_gain: -256, + channel_mapping_family: 1, + channel_mapping: vec![4, 2, 0, 4, 1, 2, 3, 5], + }; + let h = o.opus_head(); + assert_eq!(&h[..8], b"OpusHead"); + assert_eq!(&h[8..19], &[1, 6, 0x38, 0x01, 0x80, 0xBB, 0, 0, 0x00, 0xFF, 1]); + assert_eq!(&h[19..], &o.channel_mapping[..]); + let stereo = OpusConfig { output_channels: 2, channel_mapping_family: 0, channel_mapping: vec![9, 9], ..o }; + assert_eq!(stereo.opus_head().len(), 19); + assert_eq!(CodecConfig::Opus(stereo).codec_id(), CodecId::Opus); + } + + #[test] + fn apv_extradata_is_the_bare_record() { + let cfg = ApvConfig { + profile_idc: 33, + level_idc: 60, + frame_width: 1920, + frame_height: 1080, + chroma_format_idc: 2, + bit_depth_minus8: 2, + ..Default::default() + }; + let record = cfg.record_bytes(); + assert_eq!(record[0], 1, "configurationVersion"); + assert_eq!(cfg.to_bytes(), [&[0u8; 4][..], &record].concat()); + // Matroska's V_APV CodecPrivate carries the record as is; an MP4 track must match it + let parsed = ApvConfig::parse(&cfg.to_bytes()).unwrap(); + assert_eq!(parsed.raw_record, record); + assert_eq!(CodecConfig::Apv(parsed.clone()).extradata(), record); + assert_eq!(parsed.to_bytes(), cfg.to_bytes()); + assert_eq!(CodecConfig::Apv(cfg).extradata(), record); + } +} diff --git a/crates/media/src/isobmff/demux.rs b/crates/media/src/isobmff/demux.rs new file mode 100644 index 000000000..b6f2e704c --- /dev/null +++ b/crates/media/src/isobmff/demux.rs @@ -0,0 +1,1656 @@ +//! Demuxer: parses box structure lazily (headers + `moov`/`moof` only) and builds per-track sample tables. + +use crate::isobmff::bytes::{BoxHeader, Cur, FourCc, boxes, find}; +use crate::isobmff::codec::{CodecConfig, SampleEntry, parse_sample_entry}; +use crate::isobmff::error::{Error, Result, invalid}; +use crate::source::ByteSource; +use std::collections::HashMap; + +/// Hard cap on the sample count of the whole file, all tracks and fragments (after PCM chunk merging). +const MAX_SAMPLES: usize = 1 << 26; +/// Bytes of file each sample needs beyond the first `MIN_SAMPLE_ALLOWANCE` samples. A [`Sample`] +/// takes 40 bytes of memory and a constant-size `stsz` or a `trun` without per-sample fields +/// describes one in a byte or none, so without this a file could make the sample tables about +/// 40 times its own size. A table-backed sample has a 4-byte `stsz` or `trun` entry. +const FILE_BYTES_PER_SAMPLE: u64 = 4; +/// Samples any file may hold, however short: 40 MiB of sample tables. +const MIN_SAMPLE_ALLOWANCE: usize = 1 << 20; +/// Hard cap on the size of an in-memory `moov`/`moof` box. +const MAX_HEADER_BOX: u64 = 1 << 30; +/// Most text all metadata entries may hold together; entries past it are dropped. One `keys` +/// name can be named by many `ilst` items, each a copy, so the file's size does not bound this. +const MAX_METADATA_BYTES: usize = 4 << 20; +/// What an entry costs beyond its text, so that empty entries are bounded too. +const METADATA_ENTRY_COST: usize = 64; + +/// Largest sample built from a PCM chunk; larger chunks are split. Writers that put a whole +/// recording in one chunk would otherwise give samples past `u32::MAX` bytes. +const PCM_MAX_SAMPLE_BYTES: u64 = 1 << 24; + +/// Frames in one piece of a split PCM chunk: whole units, at most `PCM_MAX_SAMPLE_BYTES`. +fn pcm_piece_frames(unit: u64, unit_bytes: u64) -> u64 { + (PCM_MAX_SAMPLE_BYTES / unit_bytes.max(1)).max(1) * unit +} + +/// What is left of the file-wide limits while tracks and fragments are parsed. +struct SampleBudget { + /// Samples (what the file's length allows, at most `MAX_SAMPLES`, minus those already built). + samples: usize, + /// Bytes of file for samples whose count no table entry backs (constant-size `stsz`, `trun` + /// without per-sample fields). Each such sample claims at least one byte, so a file can't + /// describe more of them than it has bytes, however many tracks or fragments repeat the claim. + implied_bytes: u64, +} + +impl SampleBudget { + fn new(file_len: u64) -> Self { + let by_len = usize::try_from(file_len / FILE_BYTES_PER_SAMPLE).unwrap_or(usize::MAX); + Self { samples: by_len.clamp(MIN_SAMPLE_ALLOWANCE, MAX_SAMPLES), implied_bytes: file_len } + } + + fn take(&mut self, n: usize) -> Result<()> { + self.samples = self.samples.checked_sub(n).ok_or(Error::TooLarge("sample count"))?; + Ok(()) + } +} + +/// One sample (access unit) of a track, in the track's media timescale. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)] +pub struct Sample { + /// Absolute byte offset in the file. + pub offset: u64, + pub size: u32, + /// Decode timestamp (raw media time, edit lists not applied). + pub dts: i64, + /// Presentation timestamp = dts + composition offset (raw media time). + pub pts: i64, + pub duration: u32, + pub is_sync: bool, + /// 1-based index into [`Track::entries`]. + pub description_index: u32, +} + +/// One edit list entry (`elst`). +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct Edit { + /// Duration of this edit in the movie timescale. + pub segment_duration: u64, + /// Start time within the media (track timescale); `-1` marks an empty edit. + pub media_time: i64, + /// Media rate as 16.16 fixed point (0x0001_0000 = normal speed, 0 = dwell). + pub media_rate: i32, +} + +/// Broad classification of a track by its handler. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum TrackKind { + Video, + Audio, + Timecode, + Subtitle, + Other, +} + +/// A sample-to-group mapping (`sbgp`) with the matching descriptions (`sgpd`) kept raw. +#[derive(Clone, Debug, PartialEq, Eq, Default)] +pub struct SampleGroup { + pub grouping_type: FourCc, + /// (sample_count, group_description_index) runs. + pub runs: Vec<(u32, u32)>, + /// Raw description entries from `sgpd`. + pub descriptions: Vec>, +} + +/// A demuxed track. +#[derive(Clone, Debug, PartialEq)] +pub struct Track { + pub id: u32, + pub kind: TrackKind, + pub handler: FourCc, + pub handler_name: String, + /// Media timescale (`mdhd`). + pub timescale: u32, + /// Media duration in the media timescale (`mdhd`). + pub duration: u64, + /// Track duration in the movie timescale (`tkhd`). + pub tkhd_duration: u64, + /// ISO 639-2/T language code (e.g. `und`, `eng`). + pub language: String, + /// `tkhd` presentation size (16.16 fixed point converted to integer pixels, rounded down). + pub width: u32, + pub height: u32, + pub enabled: bool, + pub alternate_group: u16, + /// `tkhd` volume (8.8 fixed point). + pub volume: i16, + /// `tkhd` transformation matrix. + pub matrix: [i32; 9], + pub entries: Vec, + pub samples: Vec, + pub edits: Vec, + /// Offset to add to raw pts to get presentation time (track timescale), derived from the + /// leading empty edits and the first non-empty edit's `media_time`. + pub edit_offset: i64, + /// Track references (`tref`): (type, track ids). + pub references: Vec<(FourCc, Vec)>, + /// Raw `sdtp` bytes (one per sample) if present. + pub sdtp: Vec, + pub sample_groups: Vec, + /// True if uncompressed audio samples were merged into one [`Sample`] per chunk. + pub pcm_chunked: bool, + sync_index: Vec, + pts_order: Vec, + /// Per entry: the MPEG audio codec its first sample's frame header names, for the + /// [`CodecConfig::Mp3`] entries, which name no layer themselves. + mpeg_audio: Vec>, +} + +impl Track { + /// The first sample entry's codec configuration. + pub fn codec(&self) -> Option<&CodecConfig> { + self.entries.first().map(|e| &e.codec) + } + + /// What a decoder needs for this track, in the container-neutral form the codec crates take: + /// [`Track::codec_params_for`] the first sample's description (the first entry for a track + /// without samples, or when that index names no entry). A track whose samples use more than + /// one description ([`Track::has_mixed_descriptions`]) needs `codec_params_for` per sample. + pub fn codec_params(&self) -> crate::CodecParams { + let first = self.samples.first().map(|s| s.description_index); + self.codec_params_for(first.filter(|&i| i >= 1 && i as usize <= self.entries.len()).unwrap_or(1)) + } + + /// What a decoder needs for the samples whose [`Sample::description_index`] is + /// `description_index` (1-based, into [`Track::entries`]); [`crate::CodecId::Unknown`] when + /// there is no such entry. + pub fn codec_params_for(&self, description_index: u32) -> crate::CodecParams { + let Some(entry) = description_index.checked_sub(1).and_then(|i| self.entries.get(i as usize)) else { + return crate::CodecParams::new(crate::CodecId::Unknown); + }; + let codec = &entry.codec; + let id = self.mpeg_audio.get(description_index as usize - 1).copied().flatten().unwrap_or(codec.codec_id()); + let mut p = crate::CodecParams::new(id).with_extradata(codec.extradata()).with_tag(entry.format.0); + if let Some(v) = &entry.video { + p = p.with_size(u32::from(v.width), u32::from(v.height)); + } + if let Some(a) = &entry.audio { + p = p.with_sample_rate(a.sample_rate.round() as u32).with_channels(u16::try_from(a.channels).unwrap_or(0)); + } + match codec { + CodecConfig::Pcm(c) => { + p = p.with_pcm(if c.float { + crate::PcmFormat::float(c.bits, c.big_endian) + } else { + crate::PcmFormat::int(c.bits, c.signed, c.big_endian) + }); + p = p.with_sample_rate(c.sample_rate.round() as u32).with_channels(u16::try_from(c.channels).unwrap_or(0)); + } + CodecConfig::Opus(o) => p = p.with_sample_rate(48_000).with_channels(u16::from(o.output_channels)), + _ => {} + } + p + } + + /// True when the samples use more than one sample description, so no single + /// [`Track::codec_params`] describes them all. + pub fn has_mixed_descriptions(&self) -> bool { + self.samples.windows(2).any(|w| w[0].description_index != w[1].description_index) + } + pub fn video(&self) -> Option<&crate::isobmff::codec::VideoParams> { + self.entries.first().and_then(|e| e.video.as_ref()) + } + /// Clockwise quarter turns (0–3) the `tkhd` matrix applies for display, or None when it is not + /// a pure 0/90/180/270° rotation (mirrored, scaled or sheared — left to the caller). + /// + /// ISO/IEC 14496-12 §8.3.2: a sample point (p, q) is displayed at p′ = a·p + c·q + x, + /// q′ = b·p + d·q + y for the matrix {a, b, u, c, d, v, x, y, w}, with y pointing down. So + /// {0, 1, −1, 0} sends the top row to the right-hand column (90° clockwise — iPhone portrait + /// video), {−1, 0, 0, −1} is 180° and {0, −1, 1, 0} is 270°. Only the signs matter: a·d − b·c + /// carries the scale, which the presentation size already reflects. + pub fn display_rotation(&self) -> Option { + let [a, b, _, c, d, _, _, _, _] = self.matrix; + match (a.signum(), b.signum(), c.signum(), d.signum()) { + (1, 0, 0, 1) => Some(0), + (0, 1, -1, 0) => Some(1), + (-1, 0, 0, -1) => Some(2), + (0, -1, 1, 0) => Some(3), + _ => None, + } + } + pub fn audio(&self) -> Option<&crate::isobmff::codec::AudioParams> { + self.entries.first().and_then(|e| e.audio.as_ref()) + } + /// Presentation (edit-adjusted) pts of sample `i`. + pub fn presentation_pts(&self, i: usize) -> Option { + self.samples.get(i).map(|s| s.pts.saturating_add(self.edit_offset)) + } + /// Index of the sample being presented at raw media time `pts` (the last sample, in + /// presentation order, whose pts is ≤ `pts`; the first sample if `pts` precedes all). + pub fn sample_at_pts(&self, pts: i64) -> Option { + if self.pts_order.is_empty() { + return None; + } + let k = self.pts_order.partition_point(|&i| self.samples[i as usize].pts <= pts); + Some(self.pts_order[k.saturating_sub(1)] as usize) + } + /// Like [`sample_at_pts`](Self::sample_at_pts) but for edit-adjusted presentation time. + pub fn sample_at_presentation_time(&self, t: i64) -> Option { + self.sample_at_pts(t.saturating_sub(self.edit_offset)) + } + /// The closest sync sample at or before `index` (decode order); 0 if there is none. + pub fn sync_sample_before(&self, index: usize) -> usize { + let k = self.sync_index.partition_point(|&i| i as usize <= index); + if k == 0 { 0 } else { self.sync_index[k - 1] as usize } + } + /// Indices of all sync samples. + pub fn sync_samples(&self) -> &[u32] { + &self.sync_index + } + + fn finish_indexes(&mut self) { + self.sync_index = self.samples.iter().enumerate().filter(|(_, s)| s.is_sync).map(|(i, _)| i as u32).collect(); + let mut order: Vec = (0..self.samples.len() as u32).collect(); + order.sort_by_key(|&i| (self.samples[i as usize].pts, i)); + self.pts_order = order; + } +} + +/// Text metadata from `udta` (QuickTime `©xxx` atoms and iTunes-style `meta/ilst`, incl. `keys`). +#[derive(Clone, Debug, PartialEq, Eq, Default)] +pub struct Metadata { + pub entries: Vec<(String, String)>, +} + +impl Metadata { + pub fn get(&self, key: &str) -> Option<&str> { + self.entries.iter().find(|(k, _)| k == key).map(|(_, v)| v.as_str()) + } + /// Title from `©nam` or the `com.apple.quicktime.title` key. + pub fn title(&self) -> Option<&str> { + self.get("©nam").or_else(|| self.get("com.apple.quicktime.title")).or_else(|| self.get("title")) + } +} + +/// A parsed MP4/MOV file (headers and sample tables; media data stays in the source). +#[derive(Clone, Debug, PartialEq)] +pub struct Mp4File { + pub major_brand: FourCc, + pub minor_version: u32, + pub compatible_brands: Vec, + /// QuickTime file (major brand `qt ` or no `ftyp`). + pub is_quicktime: bool, + /// Movie timescale (`mvhd`). + pub timescale: u32, + /// Movie duration in the movie timescale (`mvhd`; for fragmented files, the longest track). + pub duration: u64, + pub tracks: Vec, + pub metadata: Metadata, + /// File uses movie fragments (`mvex` present). + pub fragmented: bool, + /// Byte offset of the `moov` box. + pub moov_offset: u64, + /// Number of `moof` boxes found. + pub fragment_count: usize, + /// Nero chapter list (`udta/chpl`), starts in the movie timescale. QuickTime chapter tracks + /// live in media data: read them with [`Mp4File::read_chapters`]. + pub chpl_chapters: Vec, +} + +impl Mp4File { + /// Read the bytes of sample `index` of track `track` (index into [`tracks`](Self::tracks)). + pub fn read_sample(&self, src: &S, track: usize, index: usize) -> Result> { + let t = self.tracks.get(track).ok_or(Error::NoSuchTrack(track))?; + let s = t.samples.get(index).ok_or(Error::NoSuchSample(index))?; + read_range(src, s.offset, s.size as u64) + } + pub fn sample_at_pts(&self, track: usize, pts: i64) -> Option { + self.tracks.get(track)?.sample_at_pts(pts) + } + pub fn sync_sample_before(&self, track: usize, index: usize) -> Option { + Some(self.tracks.get(track)?.sync_sample_before(index)) + } + /// The chapter list: the QuickTime chapter track (the text track an enabled track's `tref/chap` + /// points at; titles read from `src`, starts in the movie timescale, edit-adjusted) when there is + /// one, else the Nero `chpl` list. Empty when the file has neither. + /// + /// Chapters outside the track's first non-empty edit are left out, and one spanning that edit's + /// start begins where the edit does; later edits are ignored. Titles are cut to + /// [`MAX_CHAPTER_TITLE_BYTES`](crate::isobmff::MAX_CHAPTER_TITLE_BYTES). + pub fn read_chapters(&self, src: &S) -> Result> { + let chap_id = self + .tracks + .iter() + .filter(|t| t.enabled) + .flat_map(|t| &t.references) + .find(|(k, _)| k == b"chap") + .and_then(|(_, ids)| ids.first().copied()); + let Some(t) = chap_id.and_then(|id| self.tracks.iter().find(|t| t.id == id)) else { return Ok(self.chpl_chapters.clone()) }; + let edit = t.edits.iter().find(|e| e.media_time != -1); + let media_start = edit.map_or(i64::MIN, |e| e.media_time); + let media_end = edit + .filter(|e| e.segment_duration > 0) + .map_or(i64::MAX, |e| media_start.saturating_add(rescale(i128::from(e.segment_duration), self.timescale, t.timescale))); + let mut out = Vec::new(); + for s in t.samples.iter().take(crate::isobmff::MAX_CHAPTERS.saturating_mul(16)) { + if s.pts >= media_end || (s.pts.saturating_add(i64::from(s.duration)) <= media_start && s.pts < media_start) { + continue; + } + let data = read_range(src, s.offset, u64::from(s.size).min(MAX_CHAPTER_SAMPLE_BYTES))?; + let title = if u64::from(s.size) > MAX_CHAPTER_SAMPLE_BYTES { + crate::isobmff::chapters::parse_text_sample_prefix(&data) + } else { + crate::isobmff::chapters::parse_text_sample(&data) + }; + let title = title.unwrap_or_default(); + let title = crate::isobmff::chapters::truncate_utf8(&title, crate::isobmff::MAX_CHAPTER_TITLE_BYTES).to_string(); + let pts = s.pts.max(media_start).saturating_add(t.edit_offset).max(0) as u64; + let start = if t.timescale == 0 { + 0 + } else { + (u128::from(pts) * u128::from(self.timescale) / u128::from(t.timescale)).min(u128::from(u64::MAX)) as u64 + }; + out.push(crate::isobmff::Chapter { start, title }); + } + Ok(out) + } + /// First track of the given kind. + pub fn track_of_kind(&self, kind: TrackKind) -> Option { + self.tracks.iter().position(|t| t.kind == kind) + } +} + +/// Most of a chapter sample read for its title: its 16-bit length and far more title than is kept. +/// A longer title is decoded from what this holds of it. +const MAX_CHAPTER_SAMPLE_BYTES: u64 = 4098; + +fn read_range(src: &S, offset: u64, size: u64) -> Result> { + let end = offset.checked_add(size).ok_or(Error::Truncated("sample"))?; + if end > src.len() { + return Err(Error::Truncated("sample data")); + } + let mut v = vec![0u8; size as usize]; + src.read_at(offset, &mut v)?; + Ok(v) +} + +/// Parse an MP4/MOV file. Only box headers, `ftyp`, `moov` and `moof` boxes are read. +pub fn open(src: S) -> Result { + let len = src.len(); + let mut offset = 0u64; + let mut ftyp: Option> = None; + let mut moov: Option<(u64, Vec)> = None; + let mut moofs: Vec<(u64, Vec)> = Vec::new(); + while offset + 8 <= len { + let n = (len - offset).min(32) as usize; + let mut hb = [0u8; 32]; + src.read_at(offset, &mut hb[..n])?; + let h = BoxHeader::parse(&hb[..n])?; + let size = h.size.unwrap_or(len - offset); + let end = offset.saturating_add(size).min(len); + let body_len = end.saturating_sub(offset + h.header_len); + let read_body = |max: u64| -> Result> { + if body_len > max { + return Err(Error::TooLarge("header box")); + } + read_range(&src, offset + h.header_len, body_len) + }; + match &h.kind.0 { + b"ftyp" if ftyp.is_none() => ftyp = Some(read_body(1 << 16)?), + b"moov" if moov.is_none() => moov = Some((offset, read_body(MAX_HEADER_BOX)?)), + b"moof" => moofs.push((offset, read_body(MAX_HEADER_BOX)?)), + _ => {} + } + if h.size.is_none() { + break; + } + // A box that claims to run past the end of the file ends the scan. + offset = end; + } + let (moov_offset, moov) = moov.ok_or(Error::NoMoov)?; + let mut file = Mp4File { + major_brand: FourCc::default(), + minor_version: 0, + compatible_brands: Vec::new(), + is_quicktime: true, + timescale: 0, + duration: 0, + tracks: Vec::new(), + metadata: Metadata::default(), + fragmented: false, + moov_offset, + fragment_count: moofs.len(), + chpl_chapters: Vec::new(), + }; + if let Some(f) = &ftyp { + let mut c = Cur::labeled(f, "ftyp"); + file.major_brand = c.fourcc()?; + file.minor_version = c.u32().unwrap_or(0); + while c.remaining() >= 4 { + file.compatible_brands.push(c.fourcc()?); + } + file.is_quicktime = file.major_brand == b"qt "; + } + let mut trex: HashMap = HashMap::new(); + let mut trak_payloads = Vec::new(); + let mut meta_left = MAX_METADATA_BYTES; + let mut chpl = None; + for b in boxes(&moov) { + let b = b?; + match &b.kind.0 { + b"cmov" => return Err(Error::Unsupported("compressed movie header (cmov)".into())), + b"mvhd" => { + let mut c = Cur::labeled(b.payload, "mvhd"); + let (v, _) = c.full_header()?; + if v == 1 { + c.skip(16)?; + file.timescale = c.u32()?; + file.duration = c.u64()?; + } else { + c.skip(8)?; + file.timescale = c.u32()?; + file.duration = c.u32()? as u64; + } + } + b"trak" => trak_payloads.push(b.payload), + b"mvex" => { + file.fragmented = true; + for m in boxes(b.payload).map_while(|b| b.ok()) { + if m.kind == b"trex" { + let mut c = Cur::labeled(m.payload, "trex"); + c.full_header()?; + let id = c.u32()?; + trex.insert(id, Trex { description_index: c.u32()?, duration: c.u32()?, size: c.u32()?, flags: c.u32()? }); + } + } + } + b"udta" => { + parse_udta(b.payload, &mut file.metadata, &mut meta_left); + chpl = find(b.payload, b"chpl"); + } + b"meta" => parse_meta(b.payload, &mut file.metadata, &mut meta_left), + _ => {} + } + } + if let Some(p) = chpl { + file.chpl_chapters = crate::isobmff::chapters::parse_chpl(p, file.timescale); + } + let mut budget = SampleBudget::new(len); + for p in trak_payloads { + let t = parse_trak(p, &file, len, &mut budget)?; + file.tracks.push(t); + } + // Movie fragments. + let mut next_dts: Vec = + file.tracks.iter().map(|t| t.samples.last().map(|s| s.dts.saturating_add(i64::from(s.duration))).unwrap_or(0)).collect(); + // A duplicate track ID resolves to its first track. + let mut track_index = HashMap::new(); + for (i, t) in file.tracks.iter().enumerate() { + track_index.entry(t.id).or_insert(i); + } + for (moof_off, moof) in &moofs { + parse_moof(*moof_off, moof, &mut file.tracks, &track_index, &trex, &mut next_dts, &mut budget)?; + } + for t in &mut file.tracks { + if file.fragmented && !moofs.is_empty() { + let d: u64 = t.samples.iter().map(|s| s.duration as u64).sum(); + t.duration = t.duration.max(d); + if t.timescale > 0 && file.timescale > 0 { + let md = (t.duration as u128 * file.timescale as u128 / t.timescale as u128) as u64; + file.duration = file.duration.max(md); + } + } + t.finish_indexes(); + // Timecode start frame from the first sample. + if let Some(CodecConfig::Timecode(tc)) = t.entries.first_mut().map(|e| &mut e.codec) + && let Some(s) = t.samples.first() + && s.size >= 4 + { + let mut b = [0u8; 4]; + if src.read_at(s.offset, &mut b).is_ok() { + tc.start_frame = Some(u32::from_be_bytes(b)); + } + } + t.mpeg_audio = mpeg_audio_layers(t, &src); + } + Ok(file) +} + +/// For each [`CodecConfig::Mp3`] entry, the layer its first sample's frame header names (these +/// entries name none: ffmpeg stores MP2 as `mp4a` + 0x6B), else what the sample entry says +/// (QuickTime `.mp2`, `.mp3`). +fn mpeg_audio_layers(t: &Track, src: &S) -> Vec> { + use crate::CodecId; + let from_header = |index: u32| { + let s = t.samples.iter().find(|s| s.description_index == index && s.size >= 4)?; + let mut b = [0u8; 4]; + src.read_at(s.offset, &mut b).ok()?; + if b[0] != 0xFF || b[1] & 0xE0 != 0xE0 { + return None; + } + match (b[1] >> 1) & 3 { + 3 => Some(CodecId::Mp1), + 2 => Some(CodecId::Mp2), + 1 => Some(CodecId::Mp3), + _ => None, + } + }; + (1..) + .zip(&t.entries) + .map(|(index, e)| match e.codec { + CodecConfig::Mp3 => from_header(index).or(Some(if e.format == b".mp2" { CodecId::Mp2 } else { CodecId::Mp3 })), + _ => None, + }) + .collect() +} + +#[derive(Clone, Copy, Debug, Default)] +struct Trex { + description_index: u32, + duration: u32, + size: u32, + flags: u32, +} + +fn parse_language(code: u16) -> String { + if code < 0x400 { + // QuickTime Macintosh language code. + return if code == 0 { "eng".into() } else { "und".into() }; + } + let c = |s: u16| (((code >> s) & 0x1F) as u8 + 0x60) as char; + let s: String = [c(10), c(5), c(0)].into_iter().collect(); + if s.chars().all(|ch| ch.is_ascii_lowercase()) { s } else { "und".into() } +} + +fn rescale(v: i128, from: u32, to: u32) -> i64 { + if from == 0 { + return 0; + } + (v * to as i128 / from as i128).clamp(i64::MIN as i128, i64::MAX as i128) as i64 +} + +fn parse_trak(p: &[u8], file: &Mp4File, file_len: u64, budget: &mut SampleBudget) -> Result { + let mut t = Track { + id: 0, + kind: TrackKind::Other, + handler: FourCc::default(), + handler_name: String::new(), + timescale: 0, + duration: 0, + tkhd_duration: 0, + language: "und".into(), + width: 0, + height: 0, + enabled: true, + alternate_group: 0, + volume: 0, + matrix: [0x10000, 0, 0, 0, 0x10000, 0, 0, 0, 0x4000_0000], + entries: Vec::new(), + samples: Vec::new(), + edits: Vec::new(), + edit_offset: 0, + references: Vec::new(), + sdtp: Vec::new(), + sample_groups: Vec::new(), + pcm_chunked: false, + sync_index: Vec::new(), + pts_order: Vec::new(), + mpeg_audio: Vec::new(), + }; + let mut mdia = None; + for b in boxes(p) { + let b = b?; + match &b.kind.0 { + b"tkhd" => { + let mut c = Cur::labeled(b.payload, "tkhd"); + let (v, flags) = c.full_header()?; + t.enabled = flags & 1 != 0; + if v == 1 { + c.skip(16)?; + t.id = c.u32()?; + c.skip(4)?; + t.tkhd_duration = c.u64()?; + } else { + c.skip(8)?; + t.id = c.u32()?; + c.skip(4)?; + t.tkhd_duration = c.u32()? as u64; + } + c.skip(8)?; + let _layer = c.i16()?; + t.alternate_group = c.u16()?; + t.volume = c.i16()?; + c.skip(2)?; + for m in t.matrix.iter_mut() { + *m = c.i32()?; + } + t.width = c.u32()? >> 16; + t.height = c.u32()? >> 16; + } + b"edts" => { + if let Some(e) = find(b.payload, b"elst") { + let mut c = Cur::labeled(e, "elst"); + let (v, _) = c.full_header()?; + let n = c.count(if v == 1 { 20 } else { 12 })?; + for _ in 0..n { + let (segment_duration, media_time) = if v == 1 { (c.u64()?, c.i64()?) } else { (c.u32()? as u64, c.i32()? as i64) }; + t.edits.push(Edit { segment_duration, media_time, media_rate: c.i32()? }); + } + } + } + b"tref" => { + for r in boxes(b.payload).map_while(|b| b.ok()) { + let ids = r.payload.as_chunks::<4>().0.iter().map(|c| u32::from_be_bytes([c[0], c[1], c[2], c[3]])).collect(); + t.references.push((r.kind, ids)); + } + } + b"mdia" => mdia = Some(b.payload), + _ => {} + } + } + let mdia = mdia.ok_or_else(|| Error::Invalid("trak without mdia".into()))?; + let mut minf = None; + for b in boxes(mdia) { + let b = b?; + match &b.kind.0 { + b"mdhd" => { + let mut c = Cur::labeled(b.payload, "mdhd"); + let (v, _) = c.full_header()?; + if v == 1 { + c.skip(16)?; + t.timescale = c.u32()?; + t.duration = c.u64()?; + } else { + c.skip(8)?; + t.timescale = c.u32()?; + t.duration = c.u32()? as u64; + } + t.language = parse_language(c.u16()?); + } + b"hdlr" => { + let mut c = Cur::labeled(b.payload, "hdlr"); + c.full_header()?; + let _pre = c.u32()?; + t.handler = c.fourcc()?; + c.skip(12)?; + let name = c.rest(); + // ISO: null-terminated UTF-8; QuickTime: Pascal string. + let s = if !name.is_empty() && name[0] as usize == name.len() - 1 && name.len() > 1 { + &name[1..] + } else { + name.split(|&b| b == 0).next().unwrap_or(&[]) + }; + t.handler_name = String::from_utf8_lossy(s).into_owned(); + } + b"minf" => minf = Some(b.payload), + _ => {} + } + } + t.kind = match &t.handler.0 { + b"vide" => TrackKind::Video, + b"soun" => TrackKind::Audio, + b"tmcd" => TrackKind::Timecode, + b"text" | b"sbtl" | b"subt" | b"clcp" => TrackKind::Subtitle, + _ => TrackKind::Other, + }; + // Edit offset in media timescale. + let mut empty = 0i128; + for e in &t.edits { + if e.media_time == -1 { + empty += e.segment_duration as i128; + } else { + t.edit_offset = rescale(empty, file.timescale, t.timescale).saturating_sub(e.media_time); + break; + } + } + if let Some(stbl) = minf.and_then(|m| find(m, b"stbl")) { + parse_stbl(stbl, &mut t, file.is_quicktime, file_len, budget)?; + } + Ok(t) +} + +struct SttsCursor<'a> { + runs: &'a [(u32, u32)], + run: usize, + used: u32, +} + +impl SttsCursor<'_> { + /// Advance by `n` samples, returning the summed duration. + fn take(&mut self, mut n: u64) -> u64 { + let mut total = 0u64; + while n > 0 && self.run < self.runs.len() { + let (count, delta) = self.runs[self.run]; + let avail = (count - self.used) as u64; + let k = avail.min(n); + total = total.saturating_add(k.saturating_mul(delta as u64)); + n -= k; + self.used += k as u32; + if self.used >= count { + self.run += 1; + self.used = 0; + } + } + total + } + fn next_value(&mut self) -> u32 { + while self.run < self.runs.len() && self.runs[self.run].0 == 0 { + self.run += 1; + } + let Some(&(_, d)) = self.runs.get(self.run) else { return 0 }; + self.take(1); + d + } +} + +struct StblTables { + stts: Vec<(u32, u32)>, + ctts: Vec<(u32, u32)>, + stss: Option>, + stsc: Vec<(u32, u32, u32)>, + const_size: u32, + sample_count: usize, + sizes: Vec, + chunks: Vec, + sample_groups: Vec, +} + +fn parse_stbl_tables(stbl: &[u8], t: &mut Track, is_qt: bool, file_len: u64) -> Result { + let mut stts: Vec<(u32, u32)> = Vec::new(); + let mut ctts: Vec<(u32, u32)> = Vec::new(); + let mut stss: Option> = None; + let mut stsc: Vec<(u32, u32, u32)> = Vec::new(); + let mut const_size = 0u32; + let mut sample_count = 0usize; + let mut sizes: Vec = Vec::new(); + let mut chunks: Vec = Vec::new(); + let mut sbgp: Vec<(FourCc, Vec<(u32, u32)>)> = Vec::new(); + let mut sgpd: HashMap>> = HashMap::new(); + for b in boxes(stbl) { + let b = b?; + let mut c = Cur::labeled(b.payload, "stbl child"); + match &b.kind.0 { + b"stsd" => { + c.full_header()?; + let n = c.count(8)?; + for e in boxes(c.rest()).take(n) { + let e = e?; + t.entries.push(parse_sample_entry(e.kind, e.payload, t.handler, is_qt)?); + } + } + b"stts" => { + c.full_header()?; + let n = c.count(8)?; + stts = (0..n).map(|_| Ok((c.u32()?, c.u32()?))).collect::>()?; + } + b"ctts" => { + c.full_header()?; + let n = c.count(8)?; + ctts = (0..n).map(|_| Ok((c.u32()?, c.u32()?))).collect::>()?; + } + b"stss" => { + c.full_header()?; + let n = c.count(4)?; + let mut v: Vec = (0..n).map(|_| c.u32()).collect::>()?; + v.sort_unstable(); + stss = Some(v); + } + b"stsc" => { + c.full_header()?; + let n = c.count(12)?; + stsc = (0..n).map(|_| Ok((c.u32()?, c.u32()?, c.u32()?))).collect::>()?; + } + b"stsz" => { + c.full_header()?; + const_size = c.u32()?; + let n = c.u32()? as usize; + if const_size == 0 { + c.check_count(n, 4)?; + sizes = (0..n).map(|_| c.u32()).collect::>()?; + sample_count = n; + } else { + // Samples of constant size must fit in the file: clamp absurd counts. + sample_count = (n as u64).min(file_len / const_size as u64) as usize; + } + } + b"stz2" => { + c.full_header()?; + let field = c.u32()? & 0xFF; + let n = c.u32()? as usize; + let bits = match field { + 4 | 8 | 16 => field as usize, + _ => return invalid(format!("stz2 field size {field}")), + }; + if n.checked_mul(bits).is_none_or(|b| b.div_ceil(8) > c.remaining()) { + return Err(Error::Truncated("stz2")); + } + let d = c.rest(); + sizes = (0..n) + .map(|i| match bits { + 4 => ((d[i / 2] >> if i % 2 == 0 { 4 } else { 0 }) & 0xF) as u32, + 8 => d[i] as u32, + _ => u16::from_be_bytes([d[2 * i], d[2 * i + 1]]) as u32, + }) + .collect(); + sample_count = n; + } + b"stco" => { + c.full_header()?; + let n = c.count(4)?; + chunks = (0..n).map(|_| c.u32().map(|v| v as u64)).collect::>()?; + } + b"co64" => { + c.full_header()?; + let n = c.count(8)?; + chunks = (0..n).map(|_| c.u64()).collect::>()?; + } + b"sdtp" => { + c.full_header()?; + t.sdtp = c.rest().to_vec(); + } + b"sbgp" => { + let (v, _) = c.full_header()?; + let gt = c.fourcc()?; + if v == 1 { + c.u32()?; + } + let n = c.count(8)?; + let runs = (0..n).map(|_| Ok((c.u32()?, c.u32()?))).collect::>()?; + sbgp.push((gt, runs)); + } + b"sgpd" => { + let (v, _) = c.full_header()?; + let gt = c.fourcc()?; + let default_len = if v >= 1 { c.u32()? } else { 0 }; + if v >= 2 { + c.u32()?; + } + let n = c.count(0)?; + let mut descs = Vec::new(); + for _ in 0..n { + let l = if v >= 1 && default_len == 0 { c.u32()? } else { default_len }; + if l == 0 { + // Version 0 without known length: keep the remainder as a single entry. + descs.push(c.rest().to_vec()); + break; + } + descs.push(c.bytes(l as usize)?.to_vec()); + } + sgpd.insert(gt, descs); + } + _ => {} + } + } + let sample_groups = + sbgp.into_iter().map(|(gt, runs)| SampleGroup { grouping_type: gt, runs, descriptions: sgpd.remove(>).unwrap_or_default() }).collect(); + Ok(StblTables { stts, ctts, stss, stsc, const_size, sample_count, sizes, chunks, sample_groups }) +} + +fn parse_stbl(stbl: &[u8], t: &mut Track, is_qt: bool, file_len: u64, budget: &mut SampleBudget) -> Result<()> { + let StblTables { stts, ctts, stss, stsc, const_size, mut sample_count, sizes, chunks, sample_groups } = + parse_stbl_tables(stbl, t, is_qt, file_len)?; + t.sample_groups = sample_groups; + if sample_count == 0 || chunks.is_empty() || stsc.is_empty() { + return Ok(()); + } + if stsc[0].0 == 0 || stsc.windows(2).any(|w| w[1].0 <= w[0].0) { + return invalid("stsc first_chunk values are not increasing from 1"); + } + let pcm = match t.entries.first().map(|e| &e.codec) { + Some(CodecConfig::Pcm(p)) if const_size != 0 => Some(*p), + _ => None, + }; + let mut stts_c = SttsCursor { runs: &stts, run: 0, used: 0 }; + let mut ctts_c = SttsCursor { runs: &ctts, run: 0, used: 0 }; + let mut samples = Vec::new(); + let mut sidx = 0usize; + let mut dts = 0i64; + let mut stsc_i = 0usize; + if let Some(p) = pcm { + t.pcm_chunked = true; + let a = t.audio().cloned().unwrap_or_default(); + // Frames come in units of `unit` frames and `unit_bytes` bytes (QuickTime v1 packets). + let (unit, unit_bytes) = if a.qt_version == 1 && a.bytes_per_frame > 0 && a.samples_per_packet > 0 { + (u64::from(a.samples_per_packet), u64::from(a.bytes_per_frame)) + } else if const_size > 1 { + (1, u64::from(const_size)) + } else { + (1, u64::from(p.bytes_per_frame())) + }; + let frame_bytes = |frames: u64| -> u64 { (frames / unit).saturating_mul(unit_bytes) }; + let piece_frames = pcm_piece_frames(unit, unit_bytes); + if chunks.len() > budget.samples { + return Err(Error::TooLarge("chunk count")); + } + samples.reserve(chunks.len()); + for (ci, &off) in chunks.iter().enumerate() { + while stsc_i + 1 < stsc.len() && stsc[stsc_i + 1].0 as usize <= ci + 1 { + stsc_i += 1; + } + let spc = (stsc[stsc_i].1 as usize).min(sample_count - sidx); + if spc == 0 { + continue; + } + // A chunk past PCM_MAX_SAMPLE_BYTES becomes several samples. + let mut left = spc as u64; + let mut pos = off; + while left > 0 { + if samples.len() >= budget.samples { + return Err(Error::TooLarge("sample count")); + } + let split = frame_bytes(left) > PCM_MAX_SAMPLE_BYTES; + let frames = if split { piece_frames } else { left }; + let dur = stts_c.take(frames); + let size = frame_bytes(frames); + if split { + // Each piece is at least half of PCM_MAX_SAMPLE_BYTES, so the file's size + // bounds how many a hostile chunk size can make. + budget.implied_bytes = budget.implied_bytes.checked_sub(size).ok_or(Error::TooLarge("PCM chunk size"))?; + } + samples.push(Sample { + offset: pos, + size: size.min(u32::MAX as u64) as u32, + dts, + pts: dts, + duration: dur.min(u32::MAX as u64) as u32, + is_sync: true, + description_index: stsc[stsc_i].2, + }); + dts = dts.saturating_add(dur.min(i64::MAX as u64) as i64); + pos = pos.saturating_add(size); + left -= frames; + } + sidx += spc; + if sidx >= sample_count { + break; + } + } + } else { + if const_size != 0 { + sample_count = sample_count.min((budget.implied_bytes / const_size as u64) as usize); + } + if sample_count > budget.samples { + return Err(Error::TooLarge("sample count")); + } + // Reserve only what the chunk map can place. A declared count far past it would keep + // capacity the budget below never charges, track after track. + let mut mapped = 0usize; + let mut map_i = 0usize; + for ci in 0..chunks.len() { + while map_i + 1 < stsc.len() && stsc[map_i + 1].0 as usize <= ci + 1 { + map_i += 1; + } + mapped = mapped.saturating_add(stsc.get(map_i).map_or(0, |e| e.1 as usize)); + if mapped >= sample_count { + break; + } + } + samples.try_reserve(sample_count.min(mapped)).map_err(|_| Error::TooLarge("sample count"))?; + let mut stss_i = 0usize; + 'chunks: for (ci, &off) in chunks.iter().enumerate() { + while stsc_i + 1 < stsc.len() && stsc[stsc_i + 1].0 as usize <= ci + 1 { + stsc_i += 1; + } + let (_, spc, sdi) = stsc[stsc_i]; + let mut pos = off; + for _ in 0..spc { + if sidx >= sample_count { + break 'chunks; + } + let size = if const_size != 0 { const_size } else { sizes[sidx] }; + let duration = stts_c.next_value(); + let cts = ctts_c.next_value() as i32 as i64; + let is_sync = match &stss { + None => true, + Some(v) => { + while stss_i < v.len() && (v[stss_i] as usize) < sidx + 1 { + stss_i += 1; + } + stss_i < v.len() && v[stss_i] as usize == sidx + 1 + } + }; + samples.push(Sample { offset: pos, size, dts, pts: dts.saturating_add(cts), duration, is_sync, description_index: sdi }); + pos = pos.saturating_add(size as u64); + dts = dts.saturating_add(duration as i64); + sidx += 1; + } + } + } + if pcm.is_none() && const_size != 0 { + budget.implied_bytes -= samples.len() as u64 * const_size as u64; + } + budget.take(samples.len())?; + t.samples = samples; + Ok(()) +} + +fn parse_moof( + moof_off: u64, + moof: &[u8], + tracks: &mut [Track], + track_index: &HashMap, + trex: &HashMap, + next_dts: &mut [i64], + budget: &mut SampleBudget, +) -> Result<()> { + // End of data of the previous traf, for the base-offset default of subsequent trafs. + let mut prev_end: Option = None; + for b in boxes(moof) { + let b = b?; + if b.kind != b"traf" { + continue; + } + let mut tfhd = None; + let mut tfdt = None; + let mut truns = Vec::new(); + for c in boxes(b.payload) { + let c = c?; + match &c.kind.0 { + b"tfhd" => tfhd = Some(c.payload), + b"tfdt" => tfdt = Some(c.payload), + b"trun" => truns.push(c.payload), + _ => {} + } + } + let tfhd = tfhd.ok_or_else(|| Error::Invalid("traf without tfhd".into()))?; + let mut c = Cur::labeled(tfhd, "tfhd"); + let (_, fl) = c.full_header()?; + let id = c.u32()?; + let Some(&ti) = track_index.get(&id) else { continue }; + let d = trex.get(&id).copied().unwrap_or_default(); + let base = if fl & 1 != 0 { + c.u64()? + } else if fl & 0x20000 != 0 { + moof_off + } else { + prev_end.unwrap_or(moof_off) + }; + let sdi = if fl & 2 != 0 { c.u32()? } else { d.description_index }; + let def_dur = if fl & 8 != 0 { c.u32()? } else { d.duration }; + let def_size = if fl & 0x10 != 0 { c.u32()? } else { d.size }; + let def_flags = if fl & 0x20 != 0 { c.u32()? } else { d.flags }; + if let Some(p) = tfdt { + let mut c = Cur::labeled(p, "tfdt"); + let (v, _) = c.full_header()?; + let t = if v == 1 { c.u64()? } else { c.u32()? as u64 }; + next_dts[ti] = t.min(i64::MAX as u64) as i64; + } + let mut data_pos = base; + for tr in truns { + let mut c = Cur::labeled(tr, "trun"); + let (v, tf) = c.full_header()?; + let per = [0x100u32, 0x200, 0x400, 0x800].iter().filter(|&&f| tf & f != 0).count() * 4; + let n = c.u32()? as usize; + if per > 0 { + c.check_count(n, per)?; + } else { + let implied = (n as u64).saturating_mul(def_size.max(1) as u64); + budget.implied_bytes = budget.implied_bytes.checked_sub(implied).ok_or(Error::TooLarge("trun sample count"))?; + } + budget.take(n)?; + if tf & 1 != 0 { + data_pos = base.wrapping_add_signed(c.i32()? as i64); + } + let first_flags = if tf & 4 != 0 { Some(c.u32()?) } else { None }; + let t = &mut tracks[ti]; + t.samples.reserve(n); + for i in 0..n { + let dur = if tf & 0x100 != 0 { c.u32()? } else { def_dur }; + let size = if tf & 0x200 != 0 { c.u32()? } else { def_size }; + let flags = if tf & 0x400 != 0 { c.u32()? } else { def_flags }; + // first_sample_flags overrides the flags of the first sample only. + let flags = if i == 0 { first_flags.unwrap_or(flags) } else { flags }; + let cto = if tf & 0x800 != 0 { + let raw = c.u32()?; + if v == 0 { raw as i64 } else { raw as i32 as i64 } + } else { + 0 + }; + let dts = next_dts[ti]; + t.samples.push(Sample { + offset: data_pos, + size, + dts, + pts: dts.saturating_add(cto), + duration: dur, + is_sync: flags & 0x1_0000 == 0, + description_index: sdi, + }); + data_pos = data_pos.saturating_add(size as u64); + next_dts[ti] = dts.saturating_add(dur as i64); + } + } + prev_end = Some(data_pos); + } + Ok(()) +} + +/// Takes an entry of `key_len` and `value_len` bytes from `left`; false once it would not fit. +fn charge_metadata(left: &mut usize, key_len: usize, value_len: usize) -> bool { + let cost = key_len.saturating_add(value_len).saturating_add(METADATA_ENTRY_COST); + match left.checked_sub(cost) { + Some(rest) => { + *left = rest; + true + } + None => false, + } +} + +/// Length of `String::from_utf8_lossy(bytes)` without building it: each invalid sequence +/// becomes one three-byte U+FFFD. +fn lossy_len(bytes: &[u8]) -> usize { + bytes.utf8_chunks().map(|c| c.valid().len() + if c.invalid().is_empty() { 0 } else { 3 }).sum() +} + +fn parse_udta(p: &[u8], md: &mut Metadata, left: &mut usize) { + for b in boxes(p).map_while(|b| b.ok()) { + if b.kind == b"meta" { + parse_meta(b.payload, md, left); + } else if b.kind.0[0] == 0xA9 && b.payload.len() >= 4 { + let n = u16::from_be_bytes([b.payload[0], b.payload[1]]) as usize; + // Charged at the stored text's length, before the value is converted. + let key = b.kind.to_string_lossy(); + if let Some(s) = b.payload.get(4..4 + n) + && charge_metadata(left, key.len(), lossy_len(s)) + { + md.entries.push((key, String::from_utf8_lossy(s).into_owned())); + } + } + } +} + +fn parse_meta(p: &[u8], md: &mut Metadata, left: &mut usize) { + // QuickTime `meta` is a plain box; ISO `meta` is a full box. + let body = if p.len() >= 8 && &p[4..8] == b"hdlr" { p } else { p.get(4..).unwrap_or(&[]) }; + let mut keys: Vec = Vec::new(); + if let Some(k) = find(body, b"keys") { + let mut c = Cur::labeled(k, "keys"); + if c.full_header().is_ok() + && let Ok(n) = c.count(8) + { + for _ in 0..n { + let Ok(sz) = c.u32() else { break }; + let Ok(_ns) = c.u32() else { break }; + let Ok(name) = c.bytes((sz as usize).saturating_sub(8)) else { break }; + keys.push(String::from_utf8_lossy(name).into_owned()); + } + } + } + let Some(ilst) = find(body, b"ilst") else { return }; + for item in boxes(ilst).map_while(|b| b.ok()) { + let idx = item.kind.as_u32() as usize; + let named = if idx >= 1 { keys.get(idx - 1) } else { None }; + if let Some(d) = find(item.payload, b"data") + && d.len() >= 8 + { + let ty = u32::from_be_bytes([d[0], d[1], d[2], d[3]]) & 0xFF_FFFF; + // Charged before the key is copied (every item naming one long key is another copy) + // and before the value is converted, at the lengths they will be stored at. + if ty == 1 || ty == 0 { + let fallback = if named.is_none() { Some(item.kind.to_string_lossy()) } else { None }; + let key_len = named.or(fallback.as_ref()).map_or(0, String::len); + if charge_metadata(left, key_len, lossy_len(&d[8..])) { + let key = named.cloned().or(fallback).unwrap_or_default(); + md.entries.push((key, String::from_utf8_lossy(&d[8..]).into_owned())); + } + } + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn language_codes() { + // "und" = 0x55C4 + assert_eq!(parse_language(0x55C4), "und"); + assert_eq!(parse_language(0), "eng"); + assert_eq!(parse_language(0x15C7), "eng"); + } + + #[test] + fn stts_cursor() { + let runs = [(2, 10), (0, 99), (3, 5)]; + let mut c = SttsCursor { runs: &runs, run: 0, used: 0 }; + assert_eq!(c.next_value(), 10); + assert_eq!(c.take(3), 10 + 5 + 5); + assert_eq!(c.next_value(), 5); + assert_eq!(c.next_value(), 0); + } + + #[test] + fn codec_params_follow_the_sample_description() { + use crate::isobmff::codec::SampleEntry; + use crate::isobmff::mux::{Brand, Mp4Writer, TrackConfig, WriteSample, WriterOptions}; + let mut w = Mp4Writer::new(std::io::Cursor::new(Vec::new()), WriterOptions::new(Brand::Mp4)).unwrap(); + let a = w.add_track(TrackConfig::new(SampleEntry::aac(vec![0x12, 0x10], 2, 48_000), 48_000)).unwrap(); + for _ in 0..2 { + w.write_sample(a, WriteSample { data: &[0; 8], duration: 1024, composition_offset: 0, is_sync: true }).unwrap(); + } + let out = w.finish().unwrap().into_inner(); + let mut t = open(out.as_slice()).unwrap().tracks.remove(0); + assert!(!t.has_mixed_descriptions()); + assert_eq!(t.codec_params(), t.codec_params_for(1)); + // entry 1 unused, every sample on entry 2 (a 44.1 kHz mono AudioSpecificConfig) + t.entries.push(SampleEntry::aac(vec![0x12, 0x08], 1, 44_100)); + t.samples.iter_mut().for_each(|s| s.description_index = 2); + let p = t.codec_params(); + assert_eq!((p.extradata.as_slice(), p.sample_rate, p.channels), (&[0x12, 0x08][..], Some(44_100), Some(1))); + assert_eq!(t.codec_params_for(1).extradata, [0x12, 0x10]); + assert_eq!(t.codec_params_for(0).codec, crate::CodecId::Unknown); + assert_eq!(t.codec_params_for(3).codec, crate::CodecId::Unknown); + assert!(!t.has_mixed_descriptions()); + t.samples[1].description_index = 1; + assert!(t.has_mixed_descriptions()); + t.samples[0].description_index = 0; // malformed: falls back to the first entry + assert_eq!(t.codec_params().extradata, [0x12, 0x10]); + } + + #[test] + fn mpeg_audio_layer_comes_from_the_first_frame() { + use crate::CodecId; + use crate::isobmff::codec::SampleEntry; + use crate::isobmff::mux::{Brand, Mp4Writer, TrackConfig, WriteSample, WriterOptions}; + // MPEG-1 frame headers: layer I, II, III; then no frame header at all + let cases: [(&[u8; 4], Brand, [u8; 2], CodecId); 5] = [ + (b"mp4a", Brand::Mp4, [0xFF, 0xFF], CodecId::Mp1), + (b"mp4a", Brand::Mp4, [0xFF, 0xFD], CodecId::Mp2), + (b"mp4a", Brand::Mp4, [0xFF, 0xFB], CodecId::Mp3), + (b"mp4a", Brand::Mp4, [0, 0], CodecId::Mp3), + (b".mp2", Brand::Mov, [0, 0], CodecId::Mp2), + ]; + for (format, brand, header, want) in cases { + let mut w = Mp4Writer::new(std::io::Cursor::new(Vec::new()), WriterOptions::new(brand)).unwrap(); + let entry = SampleEntry::audio(FourCc(*format), CodecConfig::Mp3, 2, 48_000.0, 16); + let a = w.add_track(TrackConfig::new(entry, 48_000)).unwrap(); + let frame = [&header[..], &[0x94, 0x00, 0, 0, 0, 0]].concat(); + w.write_sample(a, WriteSample { data: &frame, duration: 1152, composition_offset: 0, is_sync: true }).unwrap(); + let out = w.finish().unwrap().into_inner(); + let t = &open(out.as_slice()).unwrap().tracks[0]; + assert_eq!(t.codec(), Some(&CodecConfig::Mp3)); + assert_eq!(t.codec_params().codec, want, "{format:?} {header:02X?}"); + } + } + + #[test] + fn rejects_no_moov_and_cmov() { + let mut b = crate::isobmff::bytes::BoxBuf::new(); + b.leaf(b"free", &[0; 4]); + assert!(matches!(open(b.buf.clone()), Err(Error::NoMoov))); + let m = b.start(b"moov"); + b.leaf(b"cmov", &[]); + b.end(m); + assert!(matches!(open(b.buf), Err(Error::Unsupported(_)))); + } + + #[test] + fn metadata_qt_and_ilst() { + let mut b = crate::isobmff::bytes::BoxBuf::new(); + let m = b.start(&[0xA9, b'n', b'a', b'm']); + b.u16(2); + b.u16(0); + b.bytes(b"hi"); + b.end(m); + let meta = b.start_full(b"meta", 0, 0); + b.leaf(b"hdlr", &[0; 24]); + let il = b.start(b"ilst"); + let it = b.start(&[0xA9, b'A', b'R', b'T']); + let d = b.start(b"data"); + b.u32(1); + b.u32(0); + b.bytes(b"me"); + b.end(d); + b.end(it); + b.end(il); + b.end(meta); + let mut md = Metadata::default(); + parse_udta(&b.buf, &mut md, &mut { MAX_METADATA_BYTES }); + assert_eq!(md.title(), Some("hi")); + assert_eq!(md.get("©ART"), Some("me")); + } + + use crate::isobmff::bytes::BoxBuf; + + fn full(b: &mut BoxBuf, kind: &[u8; 4], v: u8, f: impl FnOnce(&mut BoxBuf)) { + let m = b.start_full(kind, v, 0); + f(b); + b.end(m); + } + + /// Hand-built file: uuid/wide/skip boxes, stz2 sizes, co64, ctts v1 with negative offsets, + /// stss, sdtp, sbgp/sgpd, and an edit list with a leading empty edit. + fn handmade(stsz_override: Option<(u32, u32)>) -> Vec { + let mut b = BoxBuf::new(); + let m = b.start(b"ftyp"); + b.bytes(b"isom"); + b.u32(0); + b.bytes(b"isom"); + b.end(m); + let m = b.start(b"uuid"); + b.bytes(&[0xAB; 16]); + b.bytes(b"payload"); + b.end(m); + b.leaf(b"wide", &[]); + b.leaf(b"skip", &[1, 2, 3]); + // mdat with 64-bit size: 4 samples of 3,1,2,4 bytes. + let data_start = b.len() as u64 + 16; + b.u32(1); + b.bytes(b"mdat"); + b.u64(16 + 10); + b.bytes(&[1, 1, 1, 2, 3, 3, 4, 4, 4, 4]); + let moov = b.start(b"moov"); + full(&mut b, b"mvhd", 0, |b| { + b.u32(0); + b.u32(0); + b.u32(1000); + b.u32(500); + b.zeros(80); + }); + let trak = b.start(b"trak"); + full(&mut b, b"tkhd", 0, |b| { + b.u32(0); + b.u32(0); + b.u32(7); + b.u32(0); + b.u32(500); + b.zeros(52); + b.u32(320 << 16); + b.u32(240 << 16); + }); + let edts = b.start(b"edts"); + full(&mut b, b"elst", 1, |b| { + b.u32(2); + b.u64(100); + b.i64(-1); + b.i32(0x10000); + b.u64(400); + b.i64(20); + b.i32(0x10000); + }); + b.end(edts); + let mdia = b.start(b"mdia"); + full(&mut b, b"mdhd", 0, |b| { + b.u32(0); + b.u32(0); + b.u32(100); + b.u32(40); + b.u16(0x15C7); + b.u16(0); + }); + full(&mut b, b"hdlr", 0, |b| { + b.u32(0); + b.bytes(b"vide"); + b.zeros(12); + b.bytes(b"Video\0"); + }); + let minf = b.start(b"minf"); + let stbl = b.start(b"stbl"); + full(&mut b, b"stsd", 0, |b| { + b.u32(1); + crate::isobmff::codec::SampleEntry::jpeg(320, 240).write(b, false).unwrap(); + }); + full(&mut b, b"stts", 0, |b| { + b.u32(1); + b.u32(4); + b.u32(10); + }); + full(&mut b, b"ctts", 1, |b| { + b.u32(2); + b.u32(2); + b.i32(-5); + b.u32(2); + b.i32(5); + }); + full(&mut b, b"stss", 0, |b| { + b.u32(2); + b.u32(3); + b.u32(1); + }); + full(&mut b, b"stsc", 0, |b| { + b.u32(2); + b.u32(1); + b.u32(3); + b.u32(1); + b.u32(2); + b.u32(1); + b.u32(1); + }); + match stsz_override { + Some((size, count)) => full(&mut b, b"stsz", 0, |b| { + b.u32(size); + b.u32(count); + }), + None => full(&mut b, b"stz2", 0, |b| { + b.u32(4); + b.u32(4); + b.u8(0x31); + b.u8(0x24); + }), + } + full(&mut b, b"co64", 0, |b| { + b.u32(2); + b.u64(data_start); + b.u64(data_start + 6); + }); + full(&mut b, b"sdtp", 0, |b| b.bytes(&[0x20, 0x10, 0x10, 0x10])); + full(&mut b, b"sbgp", 0, |b| { + b.bytes(b"roll"); + b.u32(1); + b.u32(4); + b.u32(1); + }); + full(&mut b, b"sgpd", 1, |b| { + b.bytes(b"roll"); + b.u32(2); + b.u32(1); + b.i16(-1); + }); + b.end(stbl); + b.end(minf); + b.end(mdia); + b.end(trak); + b.end(moov); + // Trailing box extending to EOF (size 0). + b.u32(0); + b.bytes(b"free"); + b.bytes(&[9; 5]); + b.buf + } + + #[test] + fn handmade_sample_table() { + let d = handmade(None); + let f = open(d.as_slice()).unwrap(); + assert_eq!(f.major_brand, *b"isom"); + let t = &f.tracks[0]; + assert_eq!((t.id, t.kind, t.timescale, t.language.as_str()), (7, TrackKind::Video, 100, "eng")); + assert_eq!((t.width, t.height), (320, 240)); + assert_eq!(t.handler_name, "Video"); + let sizes: Vec = t.samples.iter().map(|s| s.size).collect(); + assert_eq!(sizes, [3, 1, 2, 4]); + let offs: Vec = t.samples.iter().map(|s| s.offset - t.samples[0].offset).collect(); + assert_eq!(offs, [0, 3, 4, 6]); + let pts: Vec = t.samples.iter().map(|s| s.pts).collect(); + assert_eq!(pts, [-5, 5, 25, 35]); + let sync: Vec = t.samples.iter().map(|s| s.is_sync).collect(); + assert_eq!(sync, [true, false, true, false]); + for (i, want) in [vec![1u8, 1, 1], vec![2], vec![3, 3], vec![4; 4]].iter().enumerate() { + assert_eq!(&f.read_sample(d.as_slice(), 0, i).unwrap(), want); + } + // Empty edit of 100 movie ticks = 10 media ticks, then media starts at 20. + assert_eq!(t.edits.len(), 2); + assert_eq!(t.edit_offset, 10 - 20); + assert_eq!(t.presentation_pts(2), Some(15)); + assert_eq!(t.sdtp.len(), 4); + assert_eq!(t.sample_groups[0].grouping_type, *b"roll"); + assert_eq!(t.sample_groups[0].descriptions, vec![vec![0xFF, 0xFF]]); + assert!(f.read_sample(d.as_slice(), 0, 4).is_err()); + assert!(f.read_sample(d.as_slice(), 1, 0).is_err()); + } + + #[test] + fn constant_size_samples_share_one_file_budget() { + // One chunk of u32::MAX constant-size samples makes a track build one sample per file + // byte. Repeating the track must not repeat that allocation. + let mut d = handmade(Some((1, u32::MAX))); + let p = d.windows(4).position(|w| w == b"stsc").unwrap(); + d[p + 16..p + 20].copy_from_slice(&u32::MAX.to_be_bytes()); + let at = d.windows(4).position(|w| w == b"trak").unwrap() - 4; + let size = u32::from_be_bytes(d[at..at + 4].try_into().unwrap()) as usize; + let trak = d[at..at + size].to_vec(); + for _ in 0..3 { + d.splice(at..at, trak.iter().copied()); + } + let moov = d.windows(4).position(|w| w == b"moov").unwrap() - 4; + let moov_size = u32::from_be_bytes(d[moov..moov + 4].try_into().unwrap()) + 3 * size as u32; + d[moov..moov + 4].copy_from_slice(&moov_size.to_be_bytes()); + let f = open(d.as_slice()).unwrap(); + assert_eq!(f.tracks.len(), 4); + assert!(f.tracks[0].samples.len() > d.len() / 2); + assert!(f.tracks.iter().map(|t| t.samples.len()).sum::() <= d.len()); + } + + #[test] + fn oversized_trailing_box_ends_the_scan() { + let mut d = handmade(None); + d.truncate(d.len() - 13); + d.extend_from_slice(&1u32.to_be_bytes()); + d.extend_from_slice(b"free"); + d.extend_from_slice(&u64::MAX.to_be_bytes()); + d.extend_from_slice(&[0; 16]); + assert_eq!(open(d.as_slice()).unwrap().tracks[0].samples.len(), 4); + } + + #[test] + fn one_long_key_named_by_many_items_stays_within_the_metadata_budget() { + let key = vec![b'k'; 64 * 1024]; + let mut b = BoxBuf::new(); + b.leaf(b"hdlr", &[0; 24]); + let keys = b.start_full(b"keys", 0, 0); + b.u32(1); + b.u32(8 + key.len() as u32); + b.bytes(b"mdta"); + b.bytes(&key); + b.end(keys); + let il = b.start(b"ilst"); + for _ in 0..1000 { + let it = b.start(&1u32.to_be_bytes()); + let d = b.start(b"data"); + b.u32(1); + b.u32(0); + b.bytes(b"v"); + b.end(d); + b.end(it); + } + b.end(il); + let mut payload = vec![0; 4]; + payload.extend_from_slice(&b.buf); + let mut md = Metadata::default(); + parse_meta(&payload, &mut md, &mut { MAX_METADATA_BYTES }); + assert!(!md.entries.is_empty() && md.entries.len() < 1000, "{}", md.entries.len()); + assert!(md.entries.iter().map(|(k, v)| k.len() + v.len()).sum::() <= MAX_METADATA_BYTES); + assert_eq!(md.entries[0].0.len(), key.len()); + } + + #[test] + fn metadata_is_charged_at_its_stored_length() { + assert_eq!(lossy_len(b"plain"), 5); + for bytes in [&b"a\xFFb"[..], b"\xFF\xFE\xFD", b"\xE2\x82", "\u{a9}nam".as_bytes()] { + assert_eq!(lossy_len(bytes), String::from_utf8_lossy(bytes).len(), "{bytes:?}"); + } + // Invalid UTF-8 triples in size when converted; the budget sees the converted size. + let mut b = BoxBuf::new(); + let m = b.start(&[0xA9, b'n', b'a', b'm']); + b.u16(1000); + b.u16(0); + b.bytes(&[0xFF; 1000]); + b.end(m); + let mut md = Metadata::default(); + let mut left = 3000 + METADATA_ENTRY_COST + 5; + parse_udta(&b.buf, &mut md, &mut left); + assert_eq!(md.entries.len(), 1); + assert_eq!(md.entries[0].0.len() + md.entries[0].1.len(), 3000 + 5 - left); + } + + #[test] + fn a_declared_sample_count_past_the_chunk_map_reserves_only_what_it_maps() { + // stsz claims u32::MAX samples; the two chunks place four. + let d = handmade(Some((1, u32::MAX))); + let f = open(d.as_slice()).unwrap(); + assert_eq!(f.tracks[0].samples.len(), 4); + assert!(f.tracks[0].samples.capacity() < 64, "{}", f.tracks[0].samples.capacity()); + } + + #[test] + fn absurd_counts_are_bounded() { + // Constant-size stsz claiming 4 billion samples is clamped to what fits in the file. + let d = handmade(Some((1, u32::MAX))); + let f = open(d.as_slice()).unwrap(); + assert!(f.tracks[0].samples.len() <= d.len()); + // A table claiming more entries than its box holds fails cleanly. + let mut d = handmade(None); + let p = d.windows(4).position(|w| w == b"stts").unwrap(); + d[p + 8..p + 12].copy_from_slice(&u32::MAX.to_be_bytes()); + assert!(matches!(open(d.as_slice()), Err(Error::Truncated(_)))); + // Box larger than its parent. + let mut d = handmade(None); + let p = d.windows(4).position(|w| w == b"stsc").unwrap(); + d[p - 4..p].copy_from_slice(&0x7FFF_FFFFu32.to_be_bytes()); + assert!(open(d.as_slice()).is_err()); + } + /// `data` followed by zeros up to `len` bytes. + struct Padded(Vec, u64); + + impl ByteSource for Padded { + fn len(&self) -> u64 { + self.1 + } + fn read_at(&self, offset: u64, buf: &mut [u8]) -> std::io::Result<()> { + buf.fill(0); + let start = (offset as usize).min(self.0.len()); + let end = (start + buf.len()).min(self.0.len()); + buf[..end - start].copy_from_slice(&self.0[start..end]); + Ok(()) + } + } + + #[test] + fn samples_scale_with_the_file_length() { + assert_eq!(SampleBudget::new(1000).samples, MIN_SAMPLE_ALLOWANCE); + assert_eq!(SampleBudget::new(64 << 20).samples, 16 << 20); + assert_eq!(SampleBudget::new(u64::MAX).samples, MAX_SAMPLES); + // A constant-size stsz of one-byte samples claims as many as a 64 MiB file has bytes. + let d = handmade(Some((1, u32::MAX))); + assert!(matches!(open(Padded(d, 64 << 20)), Err(Error::TooLarge(_)))); + } + + #[test] + fn a_pcm_chunk_past_4_gib_reads_as_bounded_samples() { + use crate::isobmff::{Brand, Mp4Writer, PcmConfig, TrackConfig, WriteSample, WriterOptions}; + let pcm = PcmConfig { bits: 8, float: false, big_endian: false, signed: false, channels: 1, sample_rate: 48000.0 }; + let mut w = Mp4Writer::new(std::io::Cursor::new(Vec::new()), WriterOptions::new(Brand::Mov)).unwrap(); + let t = w.add_track(TrackConfig::new(SampleEntry::pcm(pcm), 48000)).unwrap(); + w.write_sample(t, WriteSample { data: &[0; 4], duration: 0, composition_offset: 0, is_sync: true }).unwrap(); + let mut d = w.finish_faststart().unwrap().into_inner(); + // One chunk of u32::MAX one-byte frames, as a writer without chunk limits makes for a + // 4 GiB recording. + let frames = u32::MAX.to_be_bytes(); + for (kind, at) in [(b"stts", 12), (b"stsz", 12), (b"stsc", 16)] { + let p = d.windows(4).position(|w| w == kind).unwrap(); + d[p + at..p + at + 4].copy_from_slice(&frames); + } + // In a file too small for it, the claim is clamped to the file. + let f = open(d.as_slice()).unwrap(); + assert!(f.tracks[0].samples.iter().map(|s| u64::from(s.size)).sum::() <= d.len() as u64); + let len = d.len() as u64 + u64::from(u32::MAX); + let f = open(Padded(d, len)).unwrap(); + let s = &f.tracks[0].samples; + assert_eq!(s.len(), 256); + assert!(s.iter().all(|s| u64::from(s.size) <= PCM_MAX_SAMPLE_BYTES)); + assert_eq!(s.iter().map(|s| u64::from(s.size)).sum::(), u64::from(u32::MAX)); + assert_eq!(s.iter().map(|s| u64::from(s.duration)).sum::(), u64::from(u32::MAX)); + assert!(s.windows(2).all(|w| w[1].offset == w[0].offset + u64::from(w[0].size) && w[1].dts == w[0].dts + i64::from(w[0].duration))); + } +} diff --git a/crates/media/src/isobmff/error.rs b/crates/media/src/isobmff/error.rs new file mode 100644 index 000000000..b5dfd752f --- /dev/null +++ b/crates/media/src/isobmff/error.rs @@ -0,0 +1,38 @@ +use std::io; + +/// Errors produced by the demuxer and muxer. +#[derive(Debug, thiserror::Error)] +pub enum Error { + #[error("I/O error: {0}")] + Io(#[from] io::Error), + /// A box or structure ended before all required fields were read. + #[error("truncated data while reading {0}")] + Truncated(&'static str), + /// Structurally invalid data. + #[error("invalid data: {0}")] + Invalid(String), + /// Valid but unsupported feature (e.g. compressed `cmov` movie header). + #[error("unsupported: {0}")] + Unsupported(String), + /// A count or size exceeds sanity limits relative to the file size. + #[error("size limit exceeded: {0}")] + TooLarge(&'static str), + /// No `moov` box was found. + #[error("no moov box found")] + NoMoov, + /// A track index was out of range. + #[error("track index {0} out of range")] + NoSuchTrack(usize), + /// A sample index was out of range. + #[error("sample index {0} out of range")] + NoSuchSample(usize), + /// Muxer usage error (e.g. invalid track config, bad sample). + #[error("muxer: {0}")] + Mux(String), +} + +pub type Result = std::result::Result; + +pub(crate) fn invalid(msg: impl Into) -> Result { + Err(Error::Invalid(msg.into())) +} diff --git a/crates/media/src/isobmff/mod.rs b/crates/media/src/isobmff/mod.rs new file mode 100644 index 000000000..4692ebedd --- /dev/null +++ b/crates/media/src/isobmff/mod.rs @@ -0,0 +1,30 @@ +//! Clean-room ISO Base Media File Format (MP4, ISO/IEC 14496-12/14/15) and QuickTime (MOV) support. +//! +//! - **Demux:** [`open`] parses box headers plus `moov` (and `moof` for fragmented files) from a +//! [`ByteSource`] and builds per-track [`Sample`] tables; media data is read on demand with +//! [`Mp4File::read_sample`]. +//! - **Mux:** [`Mp4Writer`] writes progressive MP4/MOV (optionally faststart); +//! [`FragmentedWriter`] writes fragmented MP4. Both can write a chapter list ([`chapters`]). +//! - **Boxes:** [`boxes`] iterates the boxes in a byte slice and reads their payloads, for box +//! formats and boxes the demuxer does not model (`uuid` boxes, HEIF items, JPEG 2000, CR3). +//! +//! See the crate README for supported boxes and limitations. + +pub mod boxes; +mod bytes; +pub mod chapters; +mod codec; +mod demux; +mod error; +mod mux; + +pub use crate::source::{ByteSource, ReadSeekSource}; +pub use bytes::FourCc; +pub use chapters::{Chapter, MAX_CHAPTER_TITLE_BYTES, MAX_CHAPTERS}; +pub use codec::{ + AacConfig, ApvConfig, AudioParams, Av1Config, AvcConfig, BitRate, CleanAperture, CodecConfig, ColorInfo, FieldInfo, FlacConfig, HevcConfig, + HevcNalArray, MasteringDisplay, OpusConfig, PcmConfig, SampleEntry, TimecodeConfig, VideoParams, VpcConfig, parse_asc, +}; +pub use demux::{Edit, Metadata, Mp4File, Sample, SampleGroup, Track, TrackKind, open}; +pub use error::{Error, Result}; +pub use mux::{Brand, FragmentedWriter, Mp4Writer, TrackConfig, WriteSample, WriterOptions}; diff --git a/crates/media/src/isobmff/mux.rs b/crates/media/src/isobmff/mux.rs new file mode 100644 index 000000000..e38186e9f --- /dev/null +++ b/crates/media/src/isobmff/mux.rs @@ -0,0 +1,1344 @@ +//! Muxers: progressive MP4/MOV ([`Mp4Writer`], optional faststart) and fragmented MP4 ([`FragmentedWriter`]). + +use crate::isobmff::bytes::BoxBuf; +use crate::isobmff::chapters::{Chapter, normalize_chapters, text_sample, text_sample_entry_payload, write_chpl}; +use crate::isobmff::codec::{CodecConfig, SampleEntry, TimecodeConfig}; +use crate::isobmff::demux::Edit; +use crate::isobmff::error::{Error, Result}; +use std::io::{Read, Seek, SeekFrom, Write}; + +/// Output flavor: determines brands and some sample-entry encodings. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Brand { + /// ISO MP4: `isom` major brand, compatible `isom iso2 avc1 mp41 mp42`. + Mp4, + /// QuickTime MOV: `qt ` major brand. + Mov, +} + +/// Movie-level writer options. +#[derive(Clone, Debug)] +pub struct WriterOptions { + pub brand: Brand, + /// Movie timescale (`mvhd`); default 1000. + pub movie_timescale: u32, + /// Text metadata written to `moov/udta` (keys like `©nam`, `©ART`, `©cmt`, `©too`). + pub metadata: Vec<(String, String)>, + /// Chapter marks (starts in `movie_timescale`). [`Mp4Writer`] writes them both as a QuickTime + /// chapter track (`tref/chap` → disabled text track) and as a Nero `udta/chpl` list; + /// [`FragmentedWriter`] writes only `chpl`. See [`crate::isobmff::chapters`] for the formats and limits. + pub chapters: Vec, +} + +impl WriterOptions { + pub fn new(brand: Brand) -> Self { + WriterOptions { brand, movie_timescale: 1000, metadata: Vec::new(), chapters: Vec::new() } + } +} + +/// Per-track configuration. +#[derive(Clone, Debug)] +pub struct TrackConfig { + pub entry: SampleEntry, + /// Media timescale. For PCM it must equal the sample rate (one tick per audio frame). + pub timescale: u32, + /// ISO 639-2/T language (`und` by default). + pub language: String, + /// Explicit edit list (segment durations in the movie timescale). Takes precedence over `media_start`. + pub edits: Vec, + /// Convenience: create one edit starting at this media time (e.g. AAC encoder delay / priming, + /// or the first pts of a B-frame stream) spanning the rest of the media. + pub media_start: Option, + /// `hdlr` name; a sensible default is used when `None`. + pub handler_name: Option, +} + +impl TrackConfig { + pub fn new(entry: SampleEntry, timescale: u32) -> Self { + TrackConfig { entry, timescale, language: "und".into(), edits: Vec::new(), media_start: None, handler_name: None } + } +} + +/// A sample handed to the muxers. +#[derive(Clone, Copy, Debug)] +pub struct WriteSample<'a> { + pub data: &'a [u8], + /// Duration in the media timescale. Ignored for PCM (each frame lasts one tick). + pub duration: u32, + /// pts − dts in the media timescale. + pub composition_offset: i32, + pub is_sync: bool, +} + +#[derive(Clone, Copy, PartialEq, Eq)] +enum Handler { + Video, + Audio, + Timecode, + /// QuickTime text track carrying chapter titles. + Text, + Other, +} + +fn handler_of(e: &SampleEntry) -> Handler { + if matches!(e.codec, CodecConfig::Timecode(_)) { + Handler::Timecode + } else if e.video.is_some() { + Handler::Video + } else if e.audio.is_some() { + Handler::Audio + } else { + Handler::Other + } +} + +/// The `CodecConfig` variant, and the fourcc of variants that cover several codecs. +fn same_codec(a: &CodecConfig, b: &CodecConfig) -> bool { + use CodecConfig::*; + match (a, b) { + (ProRes { fourcc: x }, ProRes { fourcc: y }) + | (Jpeg { fourcc: x }, Jpeg { fourcc: y }) + | (Dnx { fourcc: x }, Dnx { fourcc: y }) + | (Unknown { fourcc: x, .. }, Unknown { fourcc: y, .. }) => x == y, + _ => std::mem::discriminant(a) == std::mem::discriminant(b), + } +} + +/// Accumulated sample tables for one track. +#[derive(Clone, Debug, Default)] +struct Tables { + stts: Vec<(u32, u32)>, + ctts: Vec<(u32, i32)>, + sizes: Vec, + /// Constant sample size (PCM) — then `sizes` is unused. + const_size: Option, + sample_count: u64, + /// 1-based sync sample numbers. + sync: Vec, + all_sync: bool, + /// (offset relative to file start before shifting, sample count) + chunks: Vec<(u64, u32)>, + media_duration: u64, + /// End of the last sample on the composition timeline (decode time + composition offset + + /// duration, maximum over samples). + comp_end: u64, +} + +impl Tables { + fn new() -> Self { + Tables { all_sync: true, ..Default::default() } + } + fn push_run(runs: &mut Vec<(u32, T)>, mut count: u64, v: T) { + if let Some(last) = runs.last_mut() + && last.1 == v + { + let n = count.min(u64::from(u32::MAX - last.0)); + last.0 += n as u32; + count -= n; + } + while count > 0 { + let n = count.min(u64::from(u32::MAX)); + runs.push((n as u32, v)); + count -= n; + } + } + + /// Records `count` samples written at `offset`, `sample_bytes` each, extending the last + /// chunk when the write follows it. A chunk holds at most `max` samples. + fn push_chunks(&mut self, mut offset: u64, mut count: u64, sample_bytes: u64, contiguous: bool, max: u32) { + if contiguous && let Some(c) = self.chunks.last_mut() { + let n = count.min(u64::from(max.saturating_sub(c.1))); + c.1 += n as u32; + count -= n; + offset += n * sample_bytes; + } + while count > 0 { + let n = count.min(u64::from(max)); + self.chunks.push((offset, n as u32)); + count -= n; + offset += n * sample_bytes; + } + } +} + +/// `stsz` counts samples (PCM: frames) in 32 bits. +fn too_many_samples() -> Error { + Error::Mux("more than 2^32 - 1 samples in one track".into()) +} + +/// PCM chunk size limit, ffmpeg's: readers that take each PCM chunk as one sample (this crate's +/// demuxer among them) get samples of bounded size. +const PCM_CHUNK_BYTES: u64 = 1 << 20; + +/// Frames per PCM chunk: at most [`PCM_CHUNK_BYTES`], at least one frame. +fn pcm_chunk_frames(frame_bytes: u32) -> u32 { + (PCM_CHUNK_BYTES / u64::from(frame_bytes.max(1))).max(1) as u32 +} + +struct WTrack { + cfg: TrackConfig, + id: u32, + handler: Handler, + pcm_frame_bytes: Option, + t: Tables, + /// Track id of a linked timecode track (`tref/tmcd`). + tmcd_ref: Option, + /// For timecode tracks: (video track index, start frame). + tmcd_source: Option<(usize, u32)>, + /// Track id of the chapter text track (`tref/chap`). + chap_ref: Option, +} + +fn pack_language(lang: &str) -> u16 { + let b = lang.as_bytes(); + if b.len() == 3 && b.iter().all(|c| c.is_ascii_lowercase()) { + (((b[0] - 0x60) as u16) << 10) | (((b[1] - 0x60) as u16) << 5) | ((b[2] - 0x60) as u16) + } else { + 0x55C4 // "und" + } +} + +fn rescale(v: u64, from: u32, to: u32) -> u64 { + if from == 0 { + return 0; + } + (v as u128 * to as u128 / from as u128).min(u64::MAX as u128) as u64 +} + +const MATRIX: [i32; 9] = [0x10000, 0, 0, 0, 0x10000, 0, 0, 0, 0x4000_0000]; + +fn write_ftyp(b: &mut BoxBuf, brand: Brand) { + let m = b.start(b"ftyp"); + match brand { + Brand::Mp4 => { + b.bytes(b"isom"); + b.u32(0x200); + for c in [b"isom", b"iso2", b"avc1", b"mp41", b"mp42"] { + b.bytes(c); + } + } + Brand::Mov => { + b.bytes(b"qt "); + b.u32(0x200); + b.bytes(b"qt "); + } + } + b.end(m); +} + +fn movie_duration(tracks: &[WTrack], movie_ts: u32) -> u64 { + tracks.iter().map(|t| presentation_duration(t, movie_ts)).max().unwrap_or(0) +} + +fn effective_edits(t: &WTrack, movie_ts: u32) -> Vec { + if !t.cfg.edits.is_empty() { + return t.cfg.edits.clone(); + } + if let Some(start) = t.cfg.media_start { + // presentation runs from `start` to the end of the last sample in composition order (with + // B-frame reordering that is past the end of the decode timeline) + let rest = t.t.comp_end.max(t.t.media_duration).saturating_sub(start.max(0) as u64); + return vec![Edit { segment_duration: rescale(rest, t.cfg.timescale, movie_ts), media_time: start, media_rate: 0x10000 }]; + } + Vec::new() +} + +fn presentation_duration(t: &WTrack, movie_ts: u32) -> u64 { + let e = effective_edits(t, movie_ts); + if e.is_empty() { rescale(t.t.media_duration, t.cfg.timescale, movie_ts) } else { e.iter().map(|e| e.segment_duration).sum() } +} + +fn write_mvhd(b: &mut BoxBuf, timescale: u32, duration: u64, next_id: u32) { + let v1 = duration > u32::MAX as u64; + let m = b.start_full(b"mvhd", v1 as u8, 0); + if v1 { + b.u64(0); + b.u64(0); + b.u32(timescale); + b.u64(duration); + } else { + b.u32(0); + b.u32(0); + b.u32(timescale); + b.u32(duration as u32); + } + b.u32(0x10000); + b.u16(0x100); + b.zeros(10); + for v in MATRIX { + b.i32(v); + } + b.zeros(24); + b.u32(next_id); + b.end(m); +} + +fn write_trak(b: &mut BoxBuf, t: &WTrack, movie_ts: u32, qt: bool, shift: u64, force_co64: bool) -> Result<()> { + let trak = b.start(b"trak"); + let dur = presentation_duration(t, movie_ts); + let v1 = dur > u32::MAX as u64; + // a chapter track is in the movie but disabled: players list it as chapters, never show it + let m = b.start_full(b"tkhd", v1 as u8, if t.handler == Handler::Text { 2 } else { 3 }); + if v1 { + b.u64(0); + b.u64(0); + b.u32(t.id); + b.u32(0); + b.u64(dur); + } else { + b.u32(0); + b.u32(0); + b.u32(t.id); + b.u32(0); + b.u32(dur as u32); + } + b.zeros(8); + b.i16(0); + b.u16(0); + b.i16(if t.handler == Handler::Audio { 0x100 } else { 0 }); + b.u16(0); + for v in MATRIX { + b.i32(v); + } + let (w, h) = match &t.cfg.entry.video { + Some(v) => { + let w = match v.pixel_aspect { + Some((hs, vs)) if hs > 0 && vs > 0 => (v.width as u64 * hs as u64 / vs as u64) as u32, + _ => v.width as u32, + }; + (w, v.height as u32) + } + None => (0, 0), + }; + b.u32(w << 16); + b.u32(h << 16); + b.end(m); + let edits = effective_edits(t, movie_ts); + if !edits.is_empty() { + let e = b.start(b"edts"); + let v1 = edits.iter().any(|e| e.segment_duration > u32::MAX as u64 || e.media_time > i32::MAX as i64 || e.media_time < i32::MIN as i64); + let l = b.start_full(b"elst", v1 as u8, 0); + b.u32(edits.len() as u32); + for ed in &edits { + if v1 { + b.u64(ed.segment_duration); + b.i64(ed.media_time); + } else { + b.u32(ed.segment_duration as u32); + b.i32(ed.media_time as i32); + } + b.i32(ed.media_rate); + } + b.end(l); + b.end(e); + } + if t.tmcd_ref.is_some() || t.chap_ref.is_some() { + let r = b.start(b"tref"); + for (kind, id) in [(b"tmcd", t.tmcd_ref), (b"chap", t.chap_ref)] { + if let Some(id) = id { + let m = b.start(kind); + b.u32(id); + b.end(m); + } + } + b.end(r); + } + let mdia = b.start(b"mdia"); + let mv1 = t.t.media_duration > u32::MAX as u64; + let m = b.start_full(b"mdhd", mv1 as u8, 0); + if mv1 { + b.u64(0); + b.u64(0); + b.u32(t.cfg.timescale); + b.u64(t.t.media_duration); + } else { + b.u32(0); + b.u32(0); + b.u32(t.cfg.timescale); + b.u32(t.t.media_duration as u32); + } + b.u16(pack_language(&t.cfg.language)); + b.u16(0); + b.end(m); + let (htype, default_name) = match t.handler { + Handler::Video => (b"vide", "VideoHandler"), + Handler::Audio => (b"soun", "SoundHandler"), + Handler::Timecode => (b"tmcd", "TimeCodeHandler"), + Handler::Text => (b"text", "Chapters"), + Handler::Other => (b"meta", "MetaHandler"), + }; + let name = t.cfg.handler_name.clone().unwrap_or_else(|| default_name.into()); + let m = b.start_full(b"hdlr", 0, 0); + b.bytes(if qt { b"mhlr" } else { &[0, 0, 0, 0] }); + b.bytes(htype); + b.zeros(12); + if qt { + let n = name.len().min(255); + b.u8(n as u8); + b.bytes(&name.as_bytes()[..n]); + } else { + b.bytes(name.as_bytes()); + b.u8(0); + } + b.end(m); + let minf = b.start(b"minf"); + match t.handler { + Handler::Video => { + let m = b.start_full(b"vmhd", 0, 1); + b.zeros(8); + b.end(m); + } + Handler::Audio => { + let m = b.start_full(b"smhd", 0, 0); + b.zeros(4); + b.end(m); + } + Handler::Timecode => { + let g = b.start(b"gmhd"); + let m = b.start_full(b"gmin", 0, 0); + b.u16(0x40); + b.u16(0x8000); + b.u16(0x8000); + b.u16(0x8000); + b.i16(0); + b.u16(0); + b.end(m); + let tm = b.start(b"tmcd"); + let m = b.start_full(b"tcmi", 0, 0); + b.u16(0); + b.u16(0); + b.u16(12); + b.u16(0); + b.bytes(&[0xFF; 6]); + b.zeros(6); + b.u8(0); + b.end(m); + b.end(tm); + b.end(g); + } + Handler::Text => { + // QTFF "Base media information header" with a text media information atom (a matrix) + let g = b.start(b"gmhd"); + let m = b.start_full(b"gmin", 0, 0); + b.u16(0x40); + b.u16(0x8000); + b.u16(0x8000); + b.u16(0x8000); + b.i16(0); + b.u16(0); + b.end(m); + let tx = b.start(b"text"); + for v in MATRIX { + b.i32(v); + } + b.end(tx); + b.end(g); + } + Handler::Other => { + let m = b.start_full(b"nmhd", 0, 0); + b.end(m); + } + } + if qt { + // QuickTime data handler reference. + let m = b.start_full(b"hdlr", 0, 0); + b.bytes(b"dhlr"); + b.bytes(b"url "); + b.zeros(12); + b.u8(0); + b.end(m); + } + let d = b.start(b"dinf"); + let r = b.start_full(b"dref", 0, 0); + b.u32(1); + let u = b.start_full(b"url ", 0, 1); + b.end(u); + b.end(r); + b.end(d); + write_stbl(b, t, qt, shift, force_co64)?; + b.end(minf); + b.end(mdia); + b.end(trak); + Ok(()) +} + +fn write_stbl(b: &mut BoxBuf, t: &WTrack, qt: bool, shift: u64, force_co64: bool) -> Result<()> { + let stbl = b.start(b"stbl"); + let m = b.start_full(b"stsd", 0, 0); + b.u32(1); + t.cfg.entry.write(b, qt)?; + b.end(m); + let tb = &t.t; + let m = b.start_full(b"stts", 0, 0); + b.u32(tb.stts.len() as u32); + for &(c, d) in &tb.stts { + b.u32(c); + b.u32(d); + } + b.end(m); + if tb.ctts.iter().any(|&(_, o)| o != 0) { + let neg = tb.ctts.iter().any(|&(_, o)| o < 0); + let m = b.start_full(b"ctts", neg as u8, 0); + b.u32(tb.ctts.len() as u32); + for &(c, o) in &tb.ctts { + b.u32(c); + b.i32(o); + } + b.end(m); + } + if !tb.all_sync { + let m = b.start_full(b"stss", 0, 0); + b.u32(tb.sync.len() as u32); + for &s in &tb.sync { + b.u32(s); + } + b.end(m); + } + let m = b.start_full(b"stsc", 0, 0); + let mut runs: Vec<(u32, u32)> = Vec::new(); + for (i, &(_, n)) in tb.chunks.iter().enumerate() { + if runs.last().is_none_or(|r| r.1 != n) { + runs.push((i as u32 + 1, n)); + } + } + b.u32(runs.len() as u32); + for (first, n) in runs { + b.u32(first); + b.u32(n); + b.u32(1); + } + b.end(m); + let sample_count = u32::try_from(tb.sample_count).map_err(|_| too_many_samples())?; + let m = b.start_full(b"stsz", 0, 0); + match tb.const_size { + Some(s) => { + b.u32(s); + b.u32(sample_count); + } + None => { + let first = tb.sizes.first().copied().unwrap_or(0); + // A uniform size of 0 would mean "table follows" (ISO/IEC 14496-12 §8.7.3), so + // all-empty samples must still be written as a table. + if first != 0 && !tb.sizes.is_empty() && tb.sizes.iter().all(|&s| s == first) { + b.u32(first); + b.u32(sample_count); + } else { + b.u32(0); + b.u32(sample_count); + for &s in &tb.sizes { + b.u32(s); + } + } + } + } + b.end(m); + let co64 = force_co64 || tb.chunks.iter().any(|&(o, _)| o + shift > u32::MAX as u64); + let m = b.start_full(if co64 { b"co64" } else { b"stco" }, 0, 0); + b.u32(tb.chunks.len() as u32); + for &(o, _) in &tb.chunks { + if co64 { + b.u64(o + shift); + } else { + b.u32((o + shift) as u32); + } + } + b.end(m); + b.end(stbl); + Ok(()) +} + +fn write_udta(b: &mut BoxBuf, md: &[(String, String)], chapters: &[Chapter], movie_ts: u32) { + let items: Vec<([u8; 4], &str)> = md + .iter() + .filter_map(|(k, v)| { + let mut chars = k.chars(); + if chars.next()? != '©' { + return None; + } + let rest: Vec = chars.map(|c| c as u32 as u8).collect(); + (rest.len() == 3).then(|| ([0xA9, rest[0], rest[1], rest[2]], v.as_str())) + }) + .collect(); + if items.is_empty() && chapters.is_empty() { + return; + } + let u = b.start(b"udta"); + for (k, v) in items { + let m = b.start(&k); + b.u16(v.len() as u16); + b.u16(0x55C4); + b.bytes(v.as_bytes()); + b.end(m); + } + if !chapters.is_empty() { + write_chpl(b, chapters, movie_ts); + } + b.end(u); +} + +fn validate_track(entry: &SampleEntry, timescale: u32) -> Result> { + if timescale == 0 { + return Err(Error::Mux("timescale must be non-zero".into())); + } + if let CodecConfig::Pcm(p) = &entry.codec { + if p.bits == 0 || p.channels == 0 { + return Err(Error::Mux("PCM needs bits and channels".into())); + } + if (p.sample_rate - timescale as f64).abs() > 0.5 { + return Err(Error::Mux("PCM track timescale must equal the sample rate".into())); + } + return Ok(Some(p.bytes_per_frame())); + } + Ok(None) +} + +/// 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: W, + opts: WriterOptions, + tracks: Vec, + /// Offset of the placeholder box (8 bytes) preceding the mdat header. + pad_pos: u64, + mdat_pos: u64, + pos: u64, + last_track: Option, + /// Chapters as written (normalized against the movie duration at finish). + chapters: Vec, +} + +impl Mp4Writer { + /// Start a file: writes `ftyp`, a placeholder box and the `mdat` header. + pub fn new(mut w: W, opts: WriterOptions) -> Result { + let start = w.stream_position()?; + let mut b = BoxBuf::new(); + write_ftyp(&mut b, opts.brand); + let pad_pos = start + b.len() as u64; + b.leaf(if opts.brand == Brand::Mov { b"wide" } else { b"free" }, &[]); + let mdat_pos = start + b.len() as u64; + b.leaf(b"mdat", &[]); + w.write_all(&b.buf)?; + let pos = start + b.len() as u64; + Ok(Mp4Writer { w, opts, tracks: Vec::new(), pad_pos, mdat_pos, pos, last_track: None, chapters: Vec::new() }) + } + + /// Add a track; returns its index (track ids are index + 1). + pub fn add_track(&mut self, cfg: TrackConfig) -> Result { + let pcm = validate_track(&cfg.entry, cfg.timescale)?; + let handler = handler_of(&cfg.entry); + let mut t = Tables::new(); + t.const_size = pcm; + self.tracks.push(WTrack { + id: self.tracks.len() as u32 + 1, + handler, + pcm_frame_bytes: pcm, + t, + cfg, + tmcd_ref: None, + tmcd_source: None, + chap_ref: None, + }); + Ok(self.tracks.len() - 1) + } + + /// Replace a track's sample entry before the file is finished (the `moov` is written last), for + /// codecs whose configuration is only complete at the end, like the FLAC STREAMINFO in `dfLa`. + /// The new entry must keep the codec and, for PCM, the frame size. + pub fn set_sample_entry(&mut self, track: usize, entry: SampleEntry) -> Result<()> { + let t = self.tracks.get_mut(track).ok_or(Error::NoSuchTrack(track))?; + if handler_of(&entry) != t.handler + || !same_codec(&entry.codec, &t.cfg.entry.codec) + || validate_track(&entry, t.cfg.timescale)? != t.pcm_frame_bytes + { + return Err(Error::Mux("replacement sample entry changes the track's codec or PCM layout".into())); + } + t.cfg.entry = entry; + Ok(()) + } + + /// Add a QuickTime timecode track referenced by `video_track`. Its single sample (the start + /// frame number) is written at finish, spanning the video track's duration. + pub fn add_timecode_track(&mut self, video_track: usize, tc: TimecodeConfig, start_frame: u32) -> Result { + if video_track >= self.tracks.len() { + return Err(Error::NoSuchTrack(video_track)); + } + if tc.timescale == 0 || tc.frame_duration == 0 || tc.frames_per_second == 0 { + return Err(Error::Mux("timecode needs timescale, frame duration and fps".into())); + } + let entry = SampleEntry { + format: crate::isobmff::bytes::FourCc(*b"tmcd"), + data_reference_index: 1, + codec: CodecConfig::Timecode(tc.clone()), + video: None, + audio: None, + bitrate: None, + }; + let idx = self.add_track(TrackConfig::new(entry, tc.timescale))?; + self.tracks[idx].tmcd_source = Some((video_track, start_frame)); + let id = self.tracks[idx].id; + self.tracks[video_track].tmcd_ref = Some(id); + Ok(idx) + } + + /// Append one sample to track `track` (decode order). For PCM tracks `data` may hold any whole + /// number of audio frames. + pub fn write_sample(&mut self, track: usize, s: WriteSample) -> Result<()> { + let tr = self.tracks.get(track).ok_or(Error::NoSuchTrack(track))?; + if tr.tmcd_source.is_some() || tr.handler == Handler::Text { + return Err(Error::Mux("timecode and chapter track samples are written automatically".into())); + } + let (count, dur) = match tr.pcm_frame_bytes { + Some(fb) => { + if !s.data.len().is_multiple_of(fb as usize) { + return Err(Error::Mux("PCM data is not a whole number of frames".into())); + } + (s.data.len() as u64 / u64::from(fb), 1u32) + } + None => { + if s.data.len() > u32::MAX as usize { + return Err(Error::Mux("sample larger than 4 GiB".into())); + } + (1, s.duration) + } + }; + if count == 0 { + return Ok(()); + } + if tr.t.sample_count + count > u64::from(u32::MAX) { + return Err(too_many_samples()); + } + self.w.write_all(s.data)?; + let offset = self.pos; + self.pos += s.data.len() as u64; + let contiguous = self.last_track == Some(track); + self.last_track = Some(track); + let tr = &mut self.tracks[track]; + let t = &mut tr.t; + Tables::push_run(&mut t.stts, count, dur); + Tables::push_run(&mut t.ctts, count, if tr.pcm_frame_bytes.is_some() { 0 } else { s.composition_offset }); + if tr.pcm_frame_bytes.is_none() { + t.sizes.push(s.data.len() as u32); + if s.is_sync { + t.sync.push(t.sample_count as u32 + 1); + } else { + t.all_sync = false; + } + } + t.sample_count += count; + let ct = if tr.pcm_frame_bytes.is_some() { 0 } else { s.composition_offset as i64 }; + t.comp_end = t.comp_end.max((t.media_duration as i64 + ct + count as i64 * dur as i64).max(0) as u64); + t.media_duration += count * dur as u64; + match tr.pcm_frame_bytes { + Some(fb) => t.push_chunks(offset, count, u64::from(fb), contiguous, pcm_chunk_frames(fb)), + None => t.push_chunks(offset, count, s.data.len() as u64, contiguous, u32::MAX), + } + Ok(()) + } + + fn finish_mdat(&mut self) -> Result<()> { + // Timecode samples. + for i in 0..self.tracks.len() { + let Some((vi, start)) = self.tracks[i].tmcd_source else { continue }; + let v = &self.tracks[vi]; + let vd = v.t.media_duration; + let vts = v.cfg.timescale; + let tts = self.tracks[i].cfg.timescale; + let tc_dur = match &self.tracks[i].cfg.entry.codec { + CodecConfig::Timecode(tc) => tc.frame_duration, + _ => 1, + }; + 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; + self.last_track = None; + let t = &mut self.tracks[i].t; + t.stts.push((1, d)); + t.sizes.push(4); + t.sync.push(1); + t.sample_count = 1; + t.media_duration = d as u64; + t.chunks.push((off, 1)); + } + self.write_chapter_track()?; + let size = self.pos - self.mdat_pos; + if size <= u32::MAX as u64 { + self.w.seek(SeekFrom::Start(self.mdat_pos))?; + self.w.write_all(&(size as u32).to_be_bytes())?; + } else { + // Merge the placeholder into a 16-byte large-size mdat header. + let mut h = [0u8; 16]; + h[..4].copy_from_slice(&1u32.to_be_bytes()); + h[4..8].copy_from_slice(b"mdat"); + h[8..].copy_from_slice(&(self.pos - self.pad_pos).to_be_bytes()); + self.w.seek(SeekFrom::Start(self.pad_pos))?; + self.w.write_all(&h)?; + } + self.w.seek(SeekFrom::Start(self.pos))?; + Ok(()) + } + + /// Add the QuickTime chapter track and its samples (one per chapter, each lasting until the next + /// chapter or the end of the movie), referenced by `tref/chap` from the first video or audio + /// track. A first chapter after the start is placed with an empty edit. + fn write_chapter_track(&mut self) -> Result<()> { + let ts = self.opts.movie_timescale.max(1); + let duration = movie_duration(&self.tracks, ts); + self.chapters = normalize_chapters(&self.opts.chapters, Some(duration)); + let Some(first) = self.chapters.first().map(|c| c.start) else { return Ok(()) }; + let Some(host) = self.tracks.iter().position(|t| matches!(t.handler, Handler::Video | Handler::Audio)) else { + // nothing to hang a QuickTime chapter track on; `chpl` still carries the chapters + return Ok(()); + }; + let entry = SampleEntry { + format: crate::isobmff::bytes::FourCc(*b"text"), + data_reference_index: 1, + codec: CodecConfig::Unknown { fourcc: crate::isobmff::bytes::FourCc(*b"text"), raw: text_sample_entry_payload() }, + video: None, + audio: None, + bitrate: None, + }; + let mut cfg = TrackConfig::new(entry, ts); + if first > 0 { + cfg.edits = vec![ + Edit { segment_duration: first, media_time: -1, media_rate: 0x10000 }, + Edit { segment_duration: duration.saturating_sub(first), media_time: 0, media_rate: 0x10000 }, + ]; + } + let id = self.tracks.len() as u32 + 1; + let mut t = Tables::new(); + let off = self.pos; + 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; + Tables::push_run(&mut t.stts, 1, d); + Tables::push_run(&mut t.ctts, 1, 0); + t.sizes.push(data.len() as u32); + t.sample_count += 1; + t.sync.push(t.sample_count as u32); + t.media_duration += u64::from(d); + } + t.comp_end = t.media_duration; + t.chunks.push((off, self.chapters.len() as u32)); + self.last_track = None; + self.tracks.push(WTrack { cfg, id, handler: Handler::Text, pcm_frame_bytes: None, t, tmcd_ref: None, tmcd_source: None, chap_ref: None }); + if let Some(h) = self.tracks.get_mut(host) { + h.chap_ref = Some(id); + } + Ok(()) + } + + fn build_moov(&self, shift: u64, force_co64: bool) -> Result> { + let qt = self.opts.brand == Brand::Mov; + let ts = self.opts.movie_timescale.max(1); + let mut b = BoxBuf::new(); + let m = b.start(b"moov"); + write_mvhd(&mut b, ts, movie_duration(&self.tracks, ts), self.tracks.len() as u32 + 1); + for t in &self.tracks { + write_trak(&mut b, t, ts, qt, shift, force_co64)?; + } + write_udta(&mut b, &self.opts.metadata, &self.chapters, ts); + b.end(m); + Ok(b.buf) + } + + /// Finish the file with `moov` after `mdat`. Returns the underlying writer. + pub fn finish(mut self) -> Result { + self.finish_mdat()?; + let moov = self.build_moov(0, false)?; + self.w.write_all(&moov)?; + self.w.flush()?; + Ok(self.w) + } +} + +impl Mp4Writer { + /// Finish with `moov` in front of `mdat` ("fast start"): media data is shifted forward in place. + pub fn finish_faststart(mut self) -> Result { + self.finish_mdat()?; + let mut moov = self.build_moov(0, false)?; + let mut force = false; + loop { + let shift = moov.len() as u64; + let next = self.build_moov(shift, force)?; + if next.len() == moov.len() { + moov = next; + break; + } + // Offsets crossed the 32-bit boundary: switch to co64 (size only grows, so this converges). + force = true; + moov = next; + } + let shift = moov.len() as u64; + let start = self.pad_pos; + let end = self.pos; + let mut buf = vec![0u8; 1 << 20]; + let mut cur = end; + while cur > start { + let n = (cur - start).min(buf.len() as u64) as usize; + cur -= n as u64; + self.w.seek(SeekFrom::Start(cur))?; + self.w.read_exact(&mut buf[..n])?; + self.w.seek(SeekFrom::Start(cur + shift))?; + self.w.write_all(&buf[..n])?; + } + self.w.seek(SeekFrom::Start(start))?; + self.w.write_all(&moov)?; + self.w.seek(SeekFrom::Start(end + shift))?; + self.w.flush()?; + Ok(self.w) + } +} + +/// Buffered fragment sample: (data, duration, composition offset, sync). +type PendingSample = (Vec, u32, i32, bool); + +/// Fragmented MP4 writer: an init segment (`ftyp` + `moov` with `mvex`) followed by +/// `moof`+`mdat` fragments. Samples are buffered until [`flush_fragment`](Self::flush_fragment). +pub struct FragmentedWriter { + w: W, + opts: WriterOptions, + tracks: Vec, + pending: Vec>, + next_dts: Vec, + seq: u32, + init_written: bool, +} + +impl FragmentedWriter { + pub fn new(w: W, opts: WriterOptions) -> Self { + FragmentedWriter { w, opts, tracks: Vec::new(), pending: Vec::new(), next_dts: Vec::new(), seq: 0, init_written: false } + } + + /// Add a track (before the first fragment). PCM is not supported in fragments. + pub fn add_track(&mut self, cfg: TrackConfig) -> Result { + if self.init_written { + return Err(Error::Mux("tracks must be added before the first fragment".into())); + } + if validate_track(&cfg.entry, cfg.timescale)?.is_some() { + return Err(Error::Mux("PCM is not supported by the fragmented writer".into())); + } + let handler = handler_of(&cfg.entry); + self.tracks.push(WTrack { + id: self.tracks.len() as u32 + 1, + handler, + pcm_frame_bytes: None, + t: Tables::new(), + cfg, + tmcd_ref: None, + tmcd_source: None, + chap_ref: None, + }); + self.pending.push(Vec::new()); + self.next_dts.push(0); + Ok(self.tracks.len() - 1) + } + + fn write_init(&mut self) -> Result<()> { + let qt = self.opts.brand == Brand::Mov; + let ts = self.opts.movie_timescale.max(1); + let mut b = BoxBuf::new(); + write_ftyp(&mut b, self.opts.brand); + let m = b.start(b"moov"); + write_mvhd(&mut b, ts, 0, self.tracks.len() as u32 + 1); + for t in &self.tracks { + write_trak(&mut b, t, ts, qt, 0, false)?; + } + let mv = b.start(b"mvex"); + for t in &self.tracks { + let x = b.start_full(b"trex", 0, 0); + b.u32(t.id); + b.u32(1); + b.u32(0); + b.u32(0); + b.u32(0); + b.end(x); + } + b.end(mv); + write_udta(&mut b, &self.opts.metadata, &normalize_chapters(&self.opts.chapters, None), ts); + b.end(m); + self.w.write_all(&b.buf)?; + self.init_written = true; + Ok(()) + } + + /// Buffer a sample for the next fragment. + pub fn write_sample(&mut self, track: usize, s: WriteSample) -> Result<()> { + let p = self.pending.get_mut(track).ok_or(Error::NoSuchTrack(track))?; + if s.data.len() > u32::MAX as usize { + return Err(Error::Mux("sample larger than 4 GiB".into())); + } + p.push((s.data.to_vec(), s.duration, s.composition_offset, s.is_sync)); + Ok(()) + } + + fn build_moof(&self, data_offsets: &[i32]) -> Vec { + let mut b = BoxBuf::new(); + let m = b.start(b"moof"); + let h = b.start_full(b"mfhd", 0, 0); + b.u32(self.seq); + b.end(h); + for (i, t) in self.tracks.iter().enumerate() { + let p = &self.pending[i]; + if p.is_empty() { + continue; + } + let tf = b.start(b"traf"); + let h = b.start_full(b"tfhd", 0, 0x20000); + b.u32(t.id); + b.end(h); + let h = b.start_full(b"tfdt", 1, 0); + b.u64(self.next_dts[i]); + b.end(h); + let neg = p.iter().any(|s| s.2 < 0); + let h = b.start_full(b"trun", neg as u8, 0x1 | 0x100 | 0x200 | 0x400 | 0x800); + b.u32(p.len() as u32); + b.i32(data_offsets[i]); + for (d, dur, cto, sync) in p { + b.u32(*dur); + b.u32(d.len() as u32); + b.u32(if *sync { 0x0200_0000 } else { 0x0101_0000 }); + b.i32(*cto); + } + b.end(h); + b.end(tf); + } + b.end(m); + b.buf + } + + /// Write all buffered samples as one `moof` + `mdat` fragment (no-op if nothing is buffered). + pub fn flush_fragment(&mut self) -> Result<()> { + if !self.init_written { + self.write_init()?; + } + if self.pending.iter().all(|p| p.is_empty()) { + return Ok(()); + } + self.seq += 1; + let probe = self.build_moof(&vec![0; self.tracks.len()]); + let data_len: u64 = self.pending.iter().flatten().map(|s| s.0.len() as u64).sum(); + let large = data_len + 8 > u32::MAX as u64; + let hdr = if large { 16 } else { 8 }; + let mut offs = Vec::with_capacity(self.tracks.len()); + let mut acc = probe.len() as u64 + hdr; + for p in &self.pending { + offs.push(i32::try_from(acc).map_err(|_| Error::Mux("fragment too large".into()))?); + acc += p.iter().map(|s| s.0.len() as u64).sum::(); + } + let moof = self.build_moof(&offs); + self.w.write_all(&moof)?; + if large { + self.w.write_all(&1u32.to_be_bytes())?; + self.w.write_all(b"mdat")?; + self.w.write_all(&(data_len + 16).to_be_bytes())?; + } else { + self.w.write_all(&((data_len + 8) as u32).to_be_bytes())?; + self.w.write_all(b"mdat")?; + } + for (i, p) in self.pending.iter_mut().enumerate() { + for (d, dur, _, _) in p.drain(..) { + self.w.write_all(&d)?; + self.next_dts[i] += dur as u64; + } + } + Ok(()) + } + + /// Flush remaining samples and return the writer. + pub fn finish(mut self) -> Result { + self.flush_fragment()?; + self.w.flush()?; + Ok(self.w) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::isobmff::codec::{AvcConfig, PcmConfig}; + use std::io::Cursor; + + fn avc_entry() -> SampleEntry { + SampleEntry::avc(AvcConfig::new(vec![vec![0x67, 0x42, 0, 0x1E]], vec![vec![0x68, 0xCE]], 4), 64, 48) + } + + #[test] + fn language_pack() { + assert_eq!(pack_language("und"), 0x55C4); + assert_eq!(pack_language("eng"), 0x15C7); + assert_eq!(pack_language("EN"), 0x55C4); + } + + #[test] + fn simple_roundtrip_and_faststart() { + for fast in [false, true] { + let mut w = Mp4Writer::new(Cursor::new(Vec::new()), WriterOptions::new(Brand::Mp4)).unwrap(); + let v = w.add_track(TrackConfig::new(avc_entry(), 12800)).unwrap(); + let pcm = PcmConfig { bits: 16, float: false, big_endian: false, signed: true, channels: 2, sample_rate: 48000.0 }; + let a = w.add_track(TrackConfig::new(SampleEntry::pcm(pcm), 48000)).unwrap(); + for i in 0..10u8 { + let data = vec![i; 100 + i as usize]; + w.write_sample( + v, + WriteSample { data: &data, duration: 512, composition_offset: if i % 2 == 0 { 1024 } else { 0 }, is_sync: i % 5 == 0 }, + ) + .unwrap(); + w.write_sample(a, WriteSample { data: &[i; 400], duration: 0, composition_offset: 0, is_sync: true }).unwrap(); + } + let out = if fast { w.finish_faststart() } else { w.finish() }.unwrap().into_inner(); + let f = crate::isobmff::open(out.as_slice()).unwrap(); + assert_eq!(f.tracks.len(), 2); + let t = &f.tracks[0]; + assert_eq!(t.samples.len(), 10); + for (i, s) in t.samples.iter().enumerate() { + assert_eq!(s.size as usize, 100 + i); + assert_eq!(s.dts, 512 * i as i64); + assert_eq!(s.is_sync, i % 5 == 0); + assert_eq!(f.read_sample(out.as_slice(), 0, i).unwrap(), vec![i as u8; 100 + i]); + } + let at = &f.tracks[1]; + assert!(at.pcm_chunked); + assert_eq!(at.samples.len(), 10); + assert_eq!(at.samples[3].size, 400); + assert_eq!(at.samples[3].duration, 100); + assert_eq!(f.read_sample(out.as_slice(), 1, 3).unwrap(), vec![3u8; 400]); + if fast { + assert!(f.moov_offset < t.samples[0].offset); + } + } + } + + #[test] + fn set_sample_entry_keeps_track_layout() { + let mut w = Mp4Writer::new(Cursor::new(Vec::new()), WriterOptions::new(Brand::Mov)).unwrap(); + let pcm = PcmConfig { bits: 16, float: false, big_endian: false, signed: true, channels: 2, sample_rate: 48000.0 }; + let a = w.add_track(TrackConfig::new(SampleEntry::pcm(pcm), 48000)).unwrap(); + let f = w.add_track(TrackConfig::new(SampleEntry::flac(&[0; 34]), 48000)).unwrap(); + assert!(w.set_sample_entry(a, SampleEntry::pcm(PcmConfig { big_endian: true, ..pcm })).is_ok()); + assert!(w.set_sample_entry(a, SampleEntry::pcm(PcmConfig { bits: 24, ..pcm })).is_err()); + assert!(w.set_sample_entry(a, avc_entry()).is_err()); + let v = w.add_track(TrackConfig::new(avc_entry(), 90_000)).unwrap(); + assert!(w.set_sample_entry(v, avc_entry()).is_ok()); + assert!(w.set_sample_entry(v, SampleEntry::jpeg(64, 64)).is_err()); + assert!(w.set_sample_entry(f, SampleEntry::flac(&[1; 34])).is_ok()); + assert!(w.set_sample_entry(f, SampleEntry::pcm(pcm)).is_err()); + assert!(matches!(w.set_sample_entry(5, avc_entry()), Err(Error::NoSuchTrack(5)))); + } + + fn chaptered(brand: Brand, chapters: Vec, fast: bool) -> Vec { + let mut opts = WriterOptions::new(brand); + opts.chapters = chapters; + let mut w = Mp4Writer::new(Cursor::new(Vec::new()), opts).unwrap(); + let v = w.add_track(TrackConfig::new(avc_entry(), 12800)).unwrap(); + // 100 frames of 512 / 12800 s = 4 s + for i in 0..100u32 { + w.write_sample(v, WriteSample { data: &[1, 2, 3], duration: 512, composition_offset: 0, is_sync: i % 25 == 0 }).unwrap(); + } + if fast { w.finish_faststart() } else { w.finish() }.unwrap().into_inner() + } + + fn ch(start: u64, title: &str) -> Chapter { + Chapter { start, title: title.into() } + } + + #[test] + fn chapters_are_written_as_quicktime_track_and_chpl() { + for brand in [Brand::Mp4, Brand::Mov] { + for fast in [false, true] { + let out = chaptered(brand, vec![ch(2500, "Zwei"), ch(0, "Eins"), ch(1000, "日本語")], fast); + let f = crate::isobmff::open(out.as_slice()).unwrap(); + let want = vec![ch(0, "Eins"), ch(1000, "日本語"), ch(2500, "Zwei")]; + assert_eq!(f.chpl_chapters, want, "{brand:?} chpl"); + assert_eq!(f.read_chapters(out.as_slice()).unwrap(), want, "{brand:?} chapter track"); + // the text track: disabled, referenced by the video track's tref/chap, lasting the movie + assert_eq!(f.tracks.len(), 2); + let t = &f.tracks[1]; + assert_eq!(t.handler, b"text"); + assert!(!t.enabled); + assert_eq!(f.tracks[0].references, vec![(crate::isobmff::FourCc(*b"chap"), vec![t.id])]); + let durs: Vec = t.samples.iter().map(|s| s.duration).collect(); + assert_eq!(durs, vec![1000, 1500, 1500]); + assert_eq!(f.duration, 4000); + // the video still reads back + assert_eq!(f.tracks[0].samples.len(), 100); + assert_eq!(f.read_sample(out.as_slice(), 0, 99).unwrap(), vec![1, 2, 3]); + } + } + } + + #[test] + fn a_late_first_chapter_is_placed_by_an_empty_edit() { + let out = chaptered(Brand::Mp4, vec![ch(1500, "Later"), ch(3000, "End")], false); + let f = crate::isobmff::open(out.as_slice()).unwrap(); + let t = &f.tracks[1]; + assert_eq!(t.edits.len(), 2); + assert_eq!(t.edits[0].media_time, -1); + assert_eq!(t.edits[0].segment_duration, 1500); + assert_eq!(f.read_chapters(out.as_slice()).unwrap(), vec![ch(1500, "Later"), ch(3000, "End")]); + assert_eq!(f.chpl_chapters, vec![ch(1500, "Later"), ch(3000, "End")]); + } + + /// The media time (chapter track timescale) of `movie` ticks. + fn chapter_media_time(f: &crate::isobmff::Mp4File, movie: u64) -> i64 { + (u128::from(movie) * u128::from(f.tracks[1].timescale) / u128::from(f.timescale)) as i64 + } + + #[test] + fn chapters_are_clipped_to_the_chapter_tracks_edit() { + let out = chaptered(Brand::Mp4, vec![ch(0, "A"), ch(1000, "B"), ch(2000, "C"), ch(3000, "D")], false); + let mut f = crate::isobmff::open(out.as_slice()).unwrap(); + // the edit starts inside B and ends inside C: A and D are outside, B begins at zero + let from = chapter_media_time(&f, 1500); + f.tracks[1].edits = vec![crate::isobmff::Edit { segment_duration: 1000, media_time: from, media_rate: 0x0001_0000 }]; + f.tracks[1].edit_offset = -from; + assert_eq!(f.read_chapters(out.as_slice()).unwrap(), vec![ch(0, "B"), ch(500, "C")]); + } + + #[test] + fn chapters_come_from_an_enabled_track_only() { + let out = chaptered(Brand::Mp4, vec![ch(0, "Track"), ch(1000, "Two")], false); + let mut f = crate::isobmff::open(out.as_slice()).unwrap(); + f.chpl_chapters = vec![ch(0, "Nero")]; + assert_eq!(f.read_chapters(out.as_slice()).unwrap()[0].title, "Track"); + for t in f.tracks.iter_mut().filter(|t| t.references.iter().any(|(k, _)| k == b"chap")) { + t.enabled = false; + } + assert_eq!(f.read_chapters(out.as_slice()).unwrap(), vec![ch(0, "Nero")]); + } + + #[test] + fn a_hostile_chapter_sample_is_cut_and_read_only_in_part() { + let mut out = chaptered(Brand::Mp4, vec![ch(0, "A"), ch(1000, "B")], false); + let mut f = crate::isobmff::open(out.as_slice()).unwrap(); + let offset = out.len() as u64; + out.extend_from_slice(&3000u16.to_be_bytes()); + out.extend_from_slice(&[b'x'; 3000]); + // a long title is cut, and a declared size past the end of the file reads only what is needed + f.tracks[1].samples[0].offset = offset; + f.tracks[1].samples[0].size = 3002; + f.tracks[1].samples[1].offset = offset; + f.tracks[1].samples[1].size = u32::MAX; + out.extend_from_slice(&[0; 4098]); + let v = f.read_chapters(out.as_slice()).unwrap(); + assert_eq!(v.len(), 2); + assert!(v.iter().all(|c| c.title.len() == crate::isobmff::MAX_CHAPTER_TITLE_BYTES), "{:?}", v[0].title.len()); + } + + /// A title longer than the part of the sample that is read keeps its first bytes, in either encoding. + #[test] + fn a_title_longer_than_the_sample_read_keeps_its_start() { + let declared = |title: &[u8]| { + let mut sample = (title.len() as u16).to_be_bytes().to_vec(); + sample.extend_from_slice(title); + sample + }; + let utf16 = |bom: [u8; 2], unit: fn(u16) -> [u8; 2]| { + let mut t = bom.to_vec(); + t.extend(std::iter::repeat_n(unit(0x00E9), 3000).flatten()); + t + }; + let cases = [ + (declared(&vec![b'x'; 4097]), "x".repeat(crate::isobmff::MAX_CHAPTER_TITLE_BYTES)), + // 255 bytes of two-byte characters is cut back to a whole character + (declared("é".repeat(10_000).as_bytes()), "é".repeat(127)), + (declared(&utf16([0xFE, 0xFF], u16::to_be_bytes)), "é".repeat(127)), + (declared(&utf16([0xFF, 0xFE], u16::to_le_bytes)), "é".repeat(127)), + ]; + for (sample, want) in cases { + let mut out = chaptered(Brand::Mp4, vec![ch(0, "A"), ch(1000, "B")], false); + let mut f = crate::isobmff::open(out.as_slice()).unwrap(); + f.tracks[1].samples[0].offset = out.len() as u64; + f.tracks[1].samples[0].size = sample.len() as u32; + out.extend_from_slice(&sample); + assert_eq!(f.read_chapters(out.as_slice()).unwrap()[0].title, want); + } + } + + /// A sample whose whole length was read but declares more than it holds is still no title. + #[test] + fn a_short_sample_declaring_a_longer_title_has_no_title() { + let mut out = chaptered(Brand::Mp4, vec![ch(0, "A"), ch(1000, "B")], false); + let mut f = crate::isobmff::open(out.as_slice()).unwrap(); + f.tracks[1].samples[0].offset = out.len() as u64; + f.tracks[1].samples[0].size = 3; + out.extend_from_slice(&[0, 9, b'a']); + assert_eq!(f.read_chapters(out.as_slice()).unwrap()[0].title, ""); + } + + #[test] + fn hostile_chapters_do_not_break_the_file() { + let long = "x".repeat(10_000); + let chapters = vec![ch(0, ""), ch(0, "dup"), ch(4000, "at the end"), ch(u64::MAX, "far"), ch(10, &long), ch(20, "a\0b\nc")]; + let out = chaptered(Brand::Mov, chapters, true); + let f = crate::isobmff::open(out.as_slice()).unwrap(); + let got = f.read_chapters(out.as_slice()).unwrap(); + assert_eq!(got.iter().map(|c| c.start).collect::>(), vec![0, 10, 20]); + assert_eq!(got[0].title, ""); + assert_eq!(got[1].title.len(), crate::isobmff::MAX_CHAPTER_TITLE_BYTES); + assert_eq!(got[2].title, "a b c"); + assert_eq!(f.chpl_chapters, got); + // all chapters past the end: no chapter track, no chpl + let out = chaptered(Brand::Mp4, vec![ch(9000, "gone")], false); + let f = crate::isobmff::open(out.as_slice()).unwrap(); + assert_eq!(f.tracks.len(), 1); + assert!(f.chpl_chapters.is_empty() && f.read_chapters(out.as_slice()).unwrap().is_empty()); + // over the cap + let many: Vec = (0..1000).map(|i| ch(i * 3, "c")).collect(); + let out = chaptered(Brand::Mp4, many, false); + let f = crate::isobmff::open(out.as_slice()).unwrap(); + assert_eq!(f.read_chapters(out.as_slice()).unwrap().len(), crate::isobmff::MAX_CHAPTERS); + assert_eq!(f.chpl_chapters.len(), crate::isobmff::MAX_CHAPTERS); + } + + #[test] + fn chapter_track_samples_cannot_be_written_by_hand() { + let mut opts = WriterOptions::new(Brand::Mp4); + opts.chapters = vec![ch(0, "a")]; + let mut w = Mp4Writer::new(Cursor::new(Vec::new()), opts).unwrap(); + let v = w.add_track(TrackConfig::new(avc_entry(), 1000)).unwrap(); + w.write_sample(v, WriteSample { data: &[1], duration: 40, composition_offset: 0, is_sync: true }).unwrap(); + assert!(w.write_sample(5, WriteSample { data: &[1], duration: 40, composition_offset: 0, is_sync: true }).is_err()); + let out = w.finish().unwrap().into_inner(); + assert_eq!(crate::isobmff::open(out.as_slice()).unwrap().chpl_chapters, vec![ch(0, "a")]); + } + + #[test] + fn fragmented_files_carry_chpl() { + let mut opts = WriterOptions::new(Brand::Mp4); + opts.chapters = vec![ch(40, "b"), ch(0, "a")]; + let mut w = FragmentedWriter::new(Vec::new(), opts); + let v = w.add_track(TrackConfig::new(avc_entry(), 1000)).unwrap(); + w.write_sample(v, WriteSample { data: &[1], duration: 80, composition_offset: 0, is_sync: true }).unwrap(); + let out = w.finish().unwrap(); + assert_eq!(crate::isobmff::open(out.as_slice()).unwrap().chpl_chapters, vec![ch(0, "a"), ch(40, "b")]); + } + + #[test] + fn fragmented_roundtrip() { + let mut w = FragmentedWriter::new(Vec::new(), WriterOptions::new(Brand::Mp4)); + let v = w.add_track(TrackConfig::new(avc_entry(), 1000)).unwrap(); + for i in 0..6u8 { + w.write_sample(v, WriteSample { data: &[i; 10], duration: 40, composition_offset: -(i as i32 % 2), is_sync: i % 3 == 0 }).unwrap(); + if i % 3 == 2 { + w.flush_fragment().unwrap(); + } + } + let out = w.finish().unwrap(); + let f = crate::isobmff::open(out.as_slice()).unwrap(); + assert!(f.fragmented); + assert_eq!(f.fragment_count, 2); + let t = &f.tracks[0]; + assert_eq!(t.samples.len(), 6); + for (i, s) in t.samples.iter().enumerate() { + assert_eq!(s.dts, 40 * i as i64); + assert_eq!(s.pts, s.dts - (i as i64 % 2)); + assert_eq!(s.is_sync, i % 3 == 0); + assert_eq!(f.read_sample(out.as_slice(), 0, i).unwrap(), vec![i as u8; 10]); + } + assert_eq!(t.sync_sample_before(5), 3); + } +} diff --git a/crates/media/src/lib.rs b/crates/media/src/lib.rs new file mode 100644 index 000000000..a9c812318 --- /dev/null +++ b/crates/media/src/lib.rs @@ -0,0 +1,39 @@ +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] +//! Media containers and bit-level I/O for the Craft apps. Codecs are in other crates +//! (`craft-audio`; video later), which depend on this one. +//! +//! - `bitstream` (feature `bitstream`): MSB-first bit reader and writer, Exp-Golomb codes, +//! emulation-prevention escaping and NAL unit splitting. +//! - `isobmff` (feature `isobmff`, enables `bitstream`): a clean-room ISO BMFF (MP4) and +//! QuickTime (MOV) demuxer and muxer, and a box reader for other ISO BMFF formats. +//! - `matroska` (feature `matroska`): a clean-room Matroska (MKV) and WebM demuxer and muxer. +//! - `ogg` (feature `ogg`): a clean-room Ogg demuxer with Ogg Opus and Ogg Vorbis stream mapping. +//! - `avi` (feature `avi`): a clean-room AVI (RIFF) and OpenDML demuxer. +//! - `mxf` (feature `mxf`, enables `chrono`): a clean-room MXF demuxer and writer (OP1a, OP-Atom). +//! - `mpegts` (feature `mpegts`): a clean-room MPEG-2 Systems demuxer (transport streams and +//! program streams). +//! - [`Container`] and [`CodecId`] (no feature): the identifiers the codec crates report a file's +//! container and codec with. +//! +//! `bitstream` and `isobmff` are on by default; `matroska`, `ogg`, `avi`, `mxf` and `mpegts` are opt-in. A crate that needs +//! only bit I/O uses `default-features = false, features = ["bitstream"]`. + +#[cfg(feature = "avi")] +pub mod avi; +#[cfg(feature = "bitstream")] +pub mod bitstream; +mod id; +#[cfg(feature = "isobmff")] +pub mod isobmff; +#[cfg(feature = "matroska")] +pub mod matroska; +#[cfg(feature = "mpegts")] +pub mod mpegts; +#[cfg(feature = "mxf")] +pub mod mxf; +#[cfg(feature = "ogg")] +pub mod ogg; +pub mod source; + +pub use id::{CodecId, CodecParams, Container, PcmFormat, xiph_lace}; +pub use source::{ByteSource, ReadSeekSource}; diff --git a/crates/media/src/matroska/codec.rs b/crates/media/src/matroska/codec.rs new file mode 100644 index 000000000..199145964 --- /dev/null +++ b/crates/media/src/matroska/codec.rs @@ -0,0 +1,236 @@ +//! Matroska CodecID → codec mapping (Matroska codec specifications, RFC 9559 §5.1.4.1.21 and the +//! codec mappings registry). + +/// Codec of a track, derived from `CodecID` and `CodecPrivate`. +/// +/// Configuration records are passed through as the raw bytes found in `CodecPrivate`, which for +/// the ISO codecs are exactly the ISOBMFF configuration boxes' payloads (avcC, hvcC, av1C, ASC…). +#[derive(Clone, Debug, PartialEq)] +pub enum Codec { + /// `V_MPEG4/ISO/AVC`; payload is an `AVCDecoderConfigurationRecord` (avcC). + Avc { avcc: Vec }, + /// `V_MPEGH/ISO/HEVC`; payload is an `HEVCDecoderConfigurationRecord` (hvcC). + Hevc { hvcc: Vec }, + /// `V_VP8`. + Vp8, + /// `V_VP9`; `CodecPrivate` (optional) holds VP9 codec feature metadata. + Vp9 { private: Vec }, + /// `V_AV1`; payload is an `AV1CodecConfigurationRecord` (av1C). + Av1 { av1c: Vec }, + /// `V_APV`; payload is an `APVDecoderConfigurationRecord` (apvC), if present. + Apv { apvc: Vec }, + /// `V_PRORES`; `fourcc` from `CodecPrivate` (e.g. `apcn`), if present. + ProRes { fourcc: Option<[u8; 4]> }, + /// `V_MJPEG`, or `V_MS/VFW/FOURCC` with an `MJPG` compression FourCC. + Mjpeg, + /// `V_MS/VFW/FOURCC` with any other FourCC; `bitmap_info_header` is the whole `CodecPrivate`. + VfwFourcc { fourcc: [u8; 4], bitmap_info_header: Vec }, + /// `A_AAC` (and the legacy `A_AAC/MPEG{2,4}/` IDs); `asc` is the + /// `AudioSpecificConfig` (synthesized for legacy IDs without `CodecPrivate`). + Aac { asc: Vec }, + /// `A_OPUS`; `head` is the `OpusHead` identification header. + Opus { head: Vec }, + /// `A_VORBIS`; the three Vorbis headers (identification, comment, setup), split from the + /// Xiph-laced `CodecPrivate`. + Vorbis { headers: Vec> }, + /// `A_FLAC`; `private` is `fLaC` + metadata blocks (STREAMINFO first). + Flac { private: Vec }, + /// `A_PCM/INT/LIT`, `A_PCM/INT/BIG`, `A_PCM/FLOAT/IEEE`. Bit depth comes from the Audio element. + Pcm { float: bool, big_endian: bool, bits: u16 }, + /// `A_AC3`. + Ac3, + /// `A_EAC3`. + Eac3, + /// `A_MPEG/L3`. + Mp3, + /// `A_MPEG/L2`. + Mp2, + /// `A_MPEG/L1`. + Mp1, + /// `S_TEXT/UTF8` (SubRip-style plain text). + SubRip, + /// `S_TEXT/WEBVTT`, or WebM's `D_WEBVTT/{SUBTITLES,CAPTIONS,DESCRIPTIONS,METADATA}`. + WebVtt, + /// `S_TEXT/ASS` / `S_TEXT/SSA`; `header` is the script header from `CodecPrivate`. + Ass { header: Vec, ssa: bool }, + /// Any other CodecID (kept verbatim along with `Track::codec_private`). + Other(String), +} + +impl Codec { + /// Short codec name, matching FFmpeg's `codec_name` where one exists (useful for logs/UI). + pub fn name(&self) -> String { + match self { + Codec::Avc { .. } => "h264".into(), + Codec::Hevc { .. } => "hevc".into(), + Codec::Vp8 => "vp8".into(), + Codec::Vp9 { .. } => "vp9".into(), + Codec::Av1 { .. } => "av1".into(), + Codec::Apv { .. } => "apv".into(), + Codec::ProRes { .. } => "prores".into(), + Codec::Mjpeg => "mjpeg".into(), + Codec::VfwFourcc { fourcc, .. } => String::from_utf8_lossy(fourcc).trim().to_ascii_lowercase(), + Codec::Aac { .. } => "aac".into(), + Codec::Opus { .. } => "opus".into(), + Codec::Vorbis { .. } => "vorbis".into(), + Codec::Flac { .. } => "flac".into(), + Codec::Pcm { float, big_endian, bits } => { + let k = if *float { + 'f' + } else if *bits == 8 { + 'u' + } else { + 's' + }; + if *bits == 8 { format!("pcm_{k}8") } else { format!("pcm_{k}{bits}{}", if *big_endian { "be" } else { "le" }) } + } + Codec::Ac3 => "ac3".into(), + Codec::Eac3 => "eac3".into(), + Codec::Mp3 => "mp3".into(), + Codec::Mp2 => "mp2".into(), + Codec::Mp1 => "mp1".into(), + Codec::SubRip => "subrip".into(), + Codec::WebVtt => "webvtt".into(), + Codec::Ass { ssa, .. } => if *ssa { "ssa" } else { "ass" }.into(), + Codec::Other(id) => id.clone(), + } + } +} + +const AAC_RATES: [u32; 13] = [96000, 88200, 64000, 48000, 44100, 32000, 24000, 22050, 16000, 12000, 11025, 8000, 7350]; + +/// Build a 2-byte (or 5-byte with SBR extension) AudioSpecificConfig for legacy `A_AAC/...` IDs. +fn synth_asc(object_type: u8, rate: f64, out_rate: Option, channels: u64, sbr: bool) -> Vec { + let rate_index = |r: f64| AAC_RATES.iter().position(|&x| x as f64 == r).unwrap_or(4) as u8; + let ri = rate_index(rate); + let ch = channels.min(7) as u8; + let mut v = vec![(object_type << 3) | (ri >> 1), ((ri & 1) << 7) | (ch << 3)]; + if sbr { + // backward-compatible explicit signaling: sync 0x2b7, SBR object type 5, flag, ext rate index + let ext = rate_index(out_rate.unwrap_or(rate * 2.0)); + v.push(0x56); + v.push(0xE5); + v.push(0x80 | (ext << 3)); + } + v +} + +/// Split a Xiph-laced `CodecPrivate` (Vorbis/Theora headers). +fn split_xiph(p: &[u8]) -> Vec> { + let Some(&n) = p.first() else { return Vec::new() }; + let mut pos = 1; + let mut sizes = Vec::new(); + for _ in 0..n { + let mut s = 0usize; + loop { + let Some(&b) = p.get(pos) else { return Vec::new() }; + pos += 1; + s += b as usize; + if b != 255 { + break; + } + } + sizes.push(s); + } + let mut out = Vec::new(); + for s in sizes { + let Some(h) = p.get(pos..pos + s) else { return Vec::new() }; + out.push(h.to_vec()); + pos += s; + } + out.push(p[pos.min(p.len())..].to_vec()); + out +} + +/// Map a CodecID + CodecPrivate (+ audio params for legacy AAC / PCM) to a [`Codec`]. +pub(crate) fn map_codec(id: &str, private: &[u8], audio: Option<&crate::matroska::AudioInfo>) -> Codec { + let p = private.to_vec(); + match id { + "V_MPEG4/ISO/AVC" => Codec::Avc { avcc: p }, + "V_MPEGH/ISO/HEVC" => Codec::Hevc { hvcc: p }, + "V_VP8" => Codec::Vp8, + "V_VP9" => Codec::Vp9 { private: p }, + "V_AV1" => Codec::Av1 { av1c: p }, + "V_APV" => Codec::Apv { apvc: p }, + "V_PRORES" => Codec::ProRes { fourcc: private.get(..4).and_then(|f| f.try_into().ok()) }, + "V_MJPEG" => Codec::Mjpeg, + "V_MS/VFW/FOURCC" => { + let fourcc: [u8; 4] = private.get(16..20).and_then(|f| f.try_into().ok()).unwrap_or(*b" "); + match &fourcc { + b"MJPG" | b"mjpg" | b"AVRn" | b"AVDJ" => Codec::Mjpeg, + b"H264" | b"h264" | b"avc1" | b"X264" | b"x264" => Codec::Avc { avcc: Vec::new() }, + b"apch" | b"apcn" | b"apcs" | b"apco" | b"ap4h" | b"ap4x" => Codec::ProRes { fourcc: Some(fourcc) }, + b"apv1" | b"APV1" => Codec::Apv { apvc: Vec::new() }, + _ => Codec::VfwFourcc { fourcc, bitmap_info_header: p }, + } + } + "A_AAC" => Codec::Aac { asc: p }, + "A_OPUS" => Codec::Opus { head: p }, + "A_VORBIS" => Codec::Vorbis { headers: split_xiph(private) }, + "A_FLAC" => Codec::Flac { private: p }, + "A_PCM/INT/LIT" | "A_PCM/INT/BIG" | "A_PCM/FLOAT/IEEE" => { + let bits = audio.and_then(|a| a.bit_depth).unwrap_or(if id == "A_PCM/FLOAT/IEEE" { 32 } else { 16 }) as u16; + Codec::Pcm { float: id == "A_PCM/FLOAT/IEEE", big_endian: id == "A_PCM/INT/BIG", bits } + } + "A_AC3" | "A_AC3/BSID9" | "A_AC3/BSID10" => Codec::Ac3, + "A_EAC3" => Codec::Eac3, + "A_MPEG/L3" => Codec::Mp3, + "A_MPEG/L2" => Codec::Mp2, + "A_MPEG/L1" => Codec::Mp1, + "S_TEXT/UTF8" => Codec::SubRip, + "S_TEXT/WEBVTT" | "D_WEBVTT/SUBTITLES" | "D_WEBVTT/CAPTIONS" | "D_WEBVTT/DESCRIPTIONS" | "D_WEBVTT/METADATA" => Codec::WebVtt, + "S_TEXT/ASS" | "S_ASS" => Codec::Ass { header: p, ssa: false }, + "S_TEXT/SSA" | "S_SSA" => Codec::Ass { header: p, ssa: true }, + _ if id.starts_with("A_AAC/") => { + if !private.is_empty() { + return Codec::Aac { asc: p }; + } + let (rate, out_rate, ch) = audio.map_or((48000.0, None, 2), |a| (a.sampling_frequency, a.output_sampling_frequency, a.channels)); + let object_type = if id.ends_with("/MAIN") { + 1 + } else if id.ends_with("/SSR") { + 3 + } else if id.ends_with("/LTP") { + 4 + } else { + 2 + }; + let sbr = id.ends_with("/SBR"); + Codec::Aac { asc: synth_asc(object_type, rate, out_rate, ch, sbr) } + } + _ => Codec::Other(id.to_string()), + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn mapping() { + assert_eq!(map_codec("V_MPEG4/ISO/AVC", &[1, 2], None), Codec::Avc { avcc: vec![1, 2] }); + assert_eq!(map_codec("V_APV", &[1, 2, 3], None), Codec::Apv { apvc: vec![1, 2, 3] }); + assert_eq!(map_codec("V_APV", &[], None).name(), "apv"); + assert_eq!(map_codec("V_PRORES", b"apcn", None), Codec::ProRes { fourcc: Some(*b"apcn") }); + let mut bih = vec![0u8; 40]; + bih[16..20].copy_from_slice(b"MJPG"); + assert_eq!(map_codec("V_MS/VFW/FOURCC", &bih, None), Codec::Mjpeg); + bih[16..20].copy_from_slice(b"FFV1"); + assert!(matches!(map_codec("V_MS/VFW/FOURCC", &bih, None), Codec::VfwFourcc { fourcc, .. } if &fourcc == b"FFV1")); + let a = crate::matroska::AudioInfo { sampling_frequency: 44100.0, channels: 2, bit_depth: Some(24), output_sampling_frequency: None }; + assert_eq!(map_codec("A_PCM/INT/LIT", &[], Some(&a)).name(), "pcm_s24le"); + assert_eq!(map_codec("A_PCM/FLOAT/IEEE", &[], Some(&a)), Codec::Pcm { float: true, big_endian: false, bits: 24 }); + // legacy AAC LC 44.1k stereo → 0x12 0x10 + assert_eq!(map_codec("A_AAC/MPEG4/LC", &[], Some(&a)), Codec::Aac { asc: vec![0x12, 0x10] }); + assert_eq!(map_codec("S_TEXT/UTF8", &[], None).name(), "subrip"); + assert_eq!(map_codec("X_WHATEVER", &[], None), Codec::Other("X_WHATEVER".into())); + } + + #[test] + fn xiph_split() { + let mut p = vec![2u8, 3, 2]; + p.extend_from_slice(&[1, 1, 1, 2, 2, 3, 3, 3, 3]); + let h = split_xiph(&p); + assert_eq!(h, vec![vec![1, 1, 1], vec![2, 2], vec![3, 3, 3, 3]]); + } +} diff --git a/crates/media/src/matroska/demux.rs b/crates/media/src/matroska/demux.rs new file mode 100644 index 000000000..964585449 --- /dev/null +++ b/crates/media/src/matroska/demux.rs @@ -0,0 +1,1557 @@ +//! Matroska / WebM demuxer: EBML header, Segment walk, cluster scanning, packet reading, seeking. + +use std::collections::{HashMap, VecDeque}; + +use crate::matroska::ebml::{self, Children, Lacing, Size, parse_lacing, read_id, read_size}; +use crate::matroska::error::{Error, Result}; +use crate::matroska::ids::{ + ATTACHED_FILE, ATTACHMENTS, BLOCK, BLOCK_ADD_ID, BLOCK_ADDITIONAL, BLOCK_ADDITIONS, BLOCK_DURATION, BLOCK_GROUP, BLOCK_MORE, CHAPTERS, CLUSTER, + CRC32, CUES, DISCARD_PADDING, DOC_TYPE, DOC_TYPE_READ_VERSION, DOC_TYPE_VERSION, EBML, EBML_MAX_ID_LENGTH, EBML_MAX_SIZE_LENGTH, FILE_DATA, + FILE_DESCRIPTION, FILE_MEDIA_TYPE, FILE_NAME, FILE_UID, INFO, REFERENCE_BLOCK, SEEK_HEAD, SEGMENT, SIMPLE_BLOCK, TAGS, TIMESTAMP, TRACK_ENTRY, + TRACKS, VOID, is_top_level, +}; +use crate::matroska::meta::{ + Attachment, ClusterInfo, CuePoint, Edition, SeekEntry, SegmentInfo, Tag, parse_chapters, parse_cues, parse_info, parse_seekhead, parse_tags, + parse_tracks, +}; +use crate::matroska::track::{Sample, Track, TrackKind, gcd}; +use crate::source::{ByteSource, ReadSeekSource}; + +const WIN: usize = 64 * 1024; +/// Source bytes damage recovery may read per file (the same bound as the Ogg demuxer's). +const RECOVERY_BUDGET: u64 = 64 << 20; +/// Largest EBML header element read. A real one is a few dozen bytes. +const MAX_EBML_HEADER: u64 = 4096; +/// Largest laced block body read into memory to split its frames. Laced blocks hold small frames +/// (audio); a bigger one is skipped as damage rather than read whole. +const MAX_LACED_BODY: u64 = 16 << 20; +/// Warnings kept per file; the rest are counted in one last entry. +const MAX_WARNINGS: usize = 256; +/// Upper bound for level-1 metadata elements read into memory (Info, Tracks, Cues, Tags…). +const MAX_META: u64 = 256 << 20; +/// Cap on the frames indexed from one file, all tracks together. +const MAX_FRAMES: usize = 1 << 26; +/// Bytes of file each indexed frame needs beyond the first `MIN_FRAME_ALLOWANCE` frames. An +/// indexed frame takes about 76 bytes of memory (its [`Sample`] and keyframe entry) and fixed +/// lacing can describe one in no bytes at all, so without this a file could make the index +/// about 76 times its own size. Real frames carry a block header or lace size and their data, +/// well over 8 bytes each. +const FILE_BYTES_PER_FRAME: u64 = 8; +/// Frames any file may index, however short: about 80 MiB of index. +const MIN_FRAME_ALLOWANCE: usize = 1 << 20; +/// Cap on the TrackEntries of a file. Each kept entry needs only 5 bytes of file but becomes a +/// [`Track`] of several hundred bytes. +pub(super) const MAX_TRACKS: usize = 1 << 16; + +/// Record a warning, keeping at most `MAX_WARNINGS` and one entry saying the rest were dropped. +fn warn(warnings: &mut Vec, msg: String) { + match warnings.len().cmp(&MAX_WARNINGS) { + std::cmp::Ordering::Less => warnings.push(msg), + std::cmp::Ordering::Equal => warnings.push("further warnings omitted".into()), + std::cmp::Ordering::Greater => {} + } +} + +/// What is left of the file-wide limits while clusters are scanned. +struct FrameBudget { + /// Frames (what the file's length allows, at most `MAX_FRAMES`, minus those already indexed). + frames: usize, + /// Bytes of file not yet claimed by a frame. Each frame claims its stored size and at least + /// one byte, because fixed-size lacing describes up to 256 empty frames in a 4-byte block. + bytes: u64, +} + +impl FrameBudget { + fn new(file_len: u64) -> Self { + let by_len = usize::try_from(file_len / FILE_BYTES_PER_FRAME).unwrap_or(usize::MAX); + Self { frames: by_len.clamp(MIN_FRAME_ALLOWANCE, MAX_FRAMES), bytes: file_len } + } + + /// The budget left for a file whose `tracks` already hold the frames of an earlier scan. + fn resumed(file_len: u64, tracks: &[Track]) -> Self { + let mut b = Self::new(file_len); + let (frames, bytes) = tracks + .iter() + .flat_map(|t| t.samples.iter()) + .fold((0usize, 0u64), |(n, b), s| (n.saturating_add(1), b.saturating_add(u64::from(s.size.max(1))))); + b.frames = b.frames.saturating_sub(frames); + b.bytes = b.bytes.saturating_sub(bytes); + b + } + + fn take(&mut self, frames: &[(u64, u32)]) -> Result<()> { + self.frames = self.frames.checked_sub(frames.len()).ok_or(Error::TooLarge("frame count"))?; + let bytes = frames.iter().map(|&(_, n)| u64::from(n.max(1))).sum::(); + self.bytes = self.bytes.checked_sub(bytes).ok_or(Error::TooLarge("frame count"))?; + Ok(()) + } +} + +/// Options for [`open_with`] / [`Demuxer::with_options`]. +#[derive(Clone, Debug)] +pub struct OpenOptions { + /// Scan every cluster at open to build per-track sample tables and keyframe indices + /// (reads only element and block headers, never frame payloads). Default `true`. + /// + /// With `false`, open stops at the first Cluster and uses the SeekHead to find Cues, Tags, + /// Chapters… placed after the clusters; [`Demuxer::seek`] then uses Cues (or builds the index + /// on first use if there are none). + pub index: bool, + /// Verify CRC-32 elements of level-1 elements (and clusters while indexing). Mismatches are + /// recorded in [`MkvFile::crc_errors`]; parsing continues. Default `false`. + pub verify_crc: bool, + /// Index only the front of the file: stop the cluster scan at this absolute byte offset. + /// Default `None` (scan every cluster). + /// + /// The first Cluster is always scanned (a file needs at least one to be useful). After it, an + /// element of known size (a Cluster, or Cues or Tags between Clusters) is read only if it lies + /// entirely below the limit, so a byte source that has loaded only the front of the file is + /// enough. Two things can still read past the limit: the first Cluster, and a Cluster of + /// unknown size (live streams), whose end is only found by scanning it. Info and Tracks are + /// read as usual; Cues, Tags and the other elements after the scanned part are not read + /// until the index is completed. + /// + /// The sample tables then cover everything before [`MkvFile::index_end`], which is `Some` + /// until the index is complete ([`MkvFile::indexed`]). Continue with [`MkvFile::extend_index`] + /// without rescanning. Ignored when `index` is `false`. + pub index_limit: Option, +} + +impl Default for OpenOptions { + fn default() -> Self { + Self { index: true, verify_crc: false, index_limit: None } + } +} + +/// A parsed Matroska / WebM file (first Segment). +#[derive(Clone, Debug)] +pub struct MkvFile { + /// EBML `DocType`: `matroska` or `webm`. + pub doc_type: String, + pub doc_type_version: u64, + pub doc_type_read_version: u64, + /// Absolute offset of the Segment's data (base for SeekHead and Cues positions). + pub segment_data_start: u64, + /// Absolute end of the Segment (file end for unknown-size / live segments). + pub segment_end: u64, + /// Segment size field was "unknown" (live / streamed output). + pub live: bool, + pub info: SegmentInfo, + pub tracks: Vec, + pub seek_head: Vec, + /// Cue points, sorted by time. + pub cues: Vec, + /// Clusters in file order (complete only when [`MkvFile::indexed`]). + pub clusters: Vec, + pub chapters: Vec, + pub tags: Vec, + pub attachments: Vec, + /// Absolute offset of the first Cluster. + pub first_cluster: Option, + /// Sample tables have been built by scanning all clusters. + pub indexed: bool, + /// Set while an open limited by [`OpenOptions::index_limit`] left the index incomplete: the + /// absolute offset where the cluster scan stopped and where [`MkvFile::extend_index`] + /// continues. The tables cover every frame before it and none after. `None` once the index + /// is complete, and for files opened without an index. + pub index_end: Option, + /// Walker state to continue the scan from [`MkvFile::index_end`]. + resume: Option, + /// Number of CRC-32 elements verified (with `verify_crc`). + pub crc_checked: u32, + /// Absolute offsets of elements whose CRC-32 did not match. + pub crc_errors: Vec, + /// Non-fatal problems met while parsing (damage, resyncs, truncation). + pub warnings: Vec, +} + +/// What a scan stopped at [`MkvFile::index_end`] needs to continue: the level-1 elements already +/// read (so a later pass does not read them twice) and the metadata byte budget left. +#[derive(Clone, Debug, Default)] +struct Resume { + parsed: HashMap, + meta_left: u64, +} + +/// One demuxed frame. +#[derive(Clone, Debug, PartialEq)] +pub struct Packet { + /// Index into [`MkvFile::tracks`]. + pub track: usize, + /// Matroska `TrackNumber`. + pub track_number: u64, + /// Presentation timestamp in timestamp ticks (the track timebase, [`Track::timebase`]). + pub pts: i64, + /// Presentation timestamp in nanoseconds. + pub pts_ns: i64, + /// Duration in ticks (0 if unknown). + pub duration: u64, + /// Duration in nanoseconds (0 if unknown). + pub duration_ns: u64, + pub keyframe: bool, + pub discardable: bool, + pub invisible: bool, + /// `DiscardPadding` (ns) from the enclosing BlockGroup. + pub discard_padding_ns: Option, + /// Absolute offset of the stored frame data. + pub offset: u64, + /// Index of the frame within a laced block (0 when not laced). Laced frames after the first + /// only have exact timestamps when the block or track carries a duration; otherwise they + /// repeat the block timestamp and `duration` is 0. + pub lace: u16, + /// Frame bytes with header stripping undone. Frames of tracks with other content encodings + /// (zlib, encryption) are returned as stored; see [`Track::frames_readable`]. + pub data: Vec, +} + +/// Result of [`Demuxer::seek`]. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct SeekPoint { + pub track: usize, + /// Keyframe timestamp in ticks and ns. + pub pts: i64, + pub pts_ns: i64, + /// Sample index of the keyframe when the file is indexed. + pub sample: Option, + pub cluster_offset: u64, + pub block_offset: u64, +} + +/// A keyframe index entry ([`Demuxer::keyframe_index`]). +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct Keyframe { + pub sample: usize, + pub pts: i64, + pub pts_ns: i64, + pub block_offset: u64, +} + +// --------------------------------------------------------------------------------------------- +// I/O with a small read window +// --------------------------------------------------------------------------------------------- + +#[derive(Clone, Debug)] +struct Cache { + buf: Vec, + start: u64, + /// Bytes read from the source to refill the window, all told. + refilled: u64, + /// Source bytes left for damage recovery ([`Io::resync`]) in this file. Each candidate it tests can + /// refill the window several times, so the work is charged by what was actually read. + recovery_left: u64, +} + +impl Default for Cache { + fn default() -> Self { + Self { buf: Vec::new(), start: 0, refilled: 0, recovery_left: RECOVERY_BUDGET } + } +} + +struct Io<'a, S: ByteSource + ?Sized> { + src: &'a S, + len: u64, + /// Bytes the caller has available (an [`OpenOptions::index_limit`]): the read window does not + /// run past it unless a read needs the bytes, so a source that has loaded only the front of + /// the file is not asked for the rest. `len` without a limit. + avail: u64, + cache: &'a mut Cache, +} + +#[derive(Clone, Copy, Debug)] +struct Hdr { + id: u32, + pos: u64, + size: Size, + hlen: usize, +} + +impl Hdr { + fn data_start(&self) -> u64 { + self.pos + self.hlen as u64 + } + /// End offset, clamped to `limit`; unknown sizes run to `limit`. + fn end(&self, limit: u64) -> u64 { + match self.size { + Size::Known(n) => self.data_start().saturating_add(n).min(limit), + Size::Unknown => limit, + } + } + fn overruns(&self, limit: u64) -> bool { + matches!(self.size, Size::Known(n) if self.data_start().saturating_add(n) > limit) + } +} + +impl<'a, S: ByteSource + ?Sized> Io<'a, S> { + fn new(src: &'a S, cache: &'a mut Cache) -> Self { + let len = src.len(); + Self { src, len, avail: len, cache } + } + + /// Up to `n` (≤ WIN) bytes at `pos` (fewer at EOF). + fn peek(&mut self, pos: u64, n: usize) -> Result<&[u8]> { + let n = n.min(WIN); + if pos >= self.len { + return Ok(&[]); + } + let want_end = (pos + n as u64).min(self.len); + let c = &*self.cache; + if !(pos >= c.start && want_end <= c.start + c.buf.len() as u64) { + let window_end = (pos + WIN as u64).min(self.len); + // stay inside what is available, but never fetch less than this read needs + let end = if self.avail > pos { window_end.min(self.avail).max(want_end) } else { want_end }; + let fill = (end - pos) as usize; + let mut buf = std::mem::take(&mut self.cache.buf); + buf.resize(fill, 0); + self.src.read_at(pos, &mut buf)?; + self.cache.refilled = self.cache.refilled.saturating_add(fill as u64); + self.cache.buf = buf; + self.cache.start = pos; + } + let o = (pos - self.cache.start) as usize; + Ok(&self.cache.buf[o..o + (want_end - pos) as usize]) + } + + /// Exactly `n` bytes at `pos`. + fn read_vec(&mut self, pos: u64, n: u64) -> Result> { + if pos.checked_add(n).is_none_or(|e| e > self.len) { + return Err(Error::Io(std::io::Error::new(std::io::ErrorKind::UnexpectedEof, "read past end of file"))); + } + if n as usize <= WIN / 2 { + return Ok(self.peek(pos, n as usize)?.to_vec()); + } + let mut v = vec![0u8; n as usize]; + self.src.read_at(pos, &mut v)?; + Ok(v) + } + + /// Element header at `pos` (`None` if undecodable or past `limit`). + fn header(&mut self, pos: u64, limit: u64) -> Result> { + if pos >= limit { + return Ok(None); + } + // never more than the parent holds: its last element may be shorter than a maximal header + let b = self.peek(pos, 12.min(usize::try_from(limit - pos).unwrap_or(12)))?; + let Some((id, il)) = read_id(b) else { return Ok(None) }; + let Some((size, sl)) = read_size(&b[il..]) else { return Ok(None) }; + let hlen = il + sl; + if pos + hlen as u64 > limit { + return Ok(None); + } + Ok(Some(Hdr { id, pos, size, hlen })) + } + + /// Scan forward from `from` for a plausible level-1 element (Cluster preferred), up to `limit`. + /// + /// The scan stops (`None`) once the file's recovery budget is spent: every candidate can make + /// [`Io::plausible`] refill the window at a far offset, which a damaged region would repeat per byte. + fn resync(&mut self, from: u64, limit: u64) -> Result> { + let mut pos = from; + while pos + 4 <= limit { + if self.cache.recovery_left == 0 { + return Ok(None); + } + let before = self.cache.refilled; + let chunk = self.peek(pos, WIN)?.to_vec(); + self.charge_recovery(before); + if chunk.len() < 4 { + return Ok(None); + } + for i in 0..chunk.len() - 3 { + if chunk[i] & 0xF0 != 0x10 { + continue; + } + let id = u32::from_be_bytes([chunk[i], chunk[i + 1], chunk[i + 2], chunk[i + 3]]); + if !is_top_level(id) || id == EBML || id == SEGMENT { + continue; + } + let p = pos + i as u64; + let before = self.cache.refilled; + let found = self.plausible(p, id, limit)?; + self.charge_recovery(before); + if found { + return Ok(Some(p)); + } + if self.cache.recovery_left == 0 { + return Ok(None); + } + } + pos += (chunk.len() - 3) as u64; + } + Ok(None) + } + + /// Charge the recovery budget for the window refills since `refilled_before`. + fn charge_recovery(&mut self, refilled_before: u64) { + let spent = self.cache.refilled.saturating_sub(refilled_before); + self.cache.recovery_left = self.cache.recovery_left.saturating_sub(spent); + } + + fn plausible(&mut self, p: u64, id: u32, limit: u64) -> Result { + let Some(h) = self.header(p, limit)? else { return Ok(false) }; + if h.id != id || h.overruns(limit) { + return Ok(false); + } + if h.size == Size::Unknown && id != CLUSTER { + return Ok(false); + } + // first child must decode and fit; clusters must start with Timestamp (after CRC-32/Void) + let mut cp = h.data_start(); + let end = h.end(limit); + for _ in 0..3 { + let Some(c) = self.header(cp, end)? else { return Ok(false) }; + if c.overruns(end) { + return Ok(false); + } + if id != CLUSTER { + return Ok(true); + } + match c.id { + TIMESTAMP => return Ok(true), + CRC32 | VOID => cp = c.end(end), + _ => return Ok(false), + } + } + Ok(false) + } + + /// End of an unknown-size master element: the first child that is a top-level ID or undecodable. + fn unknown_end(&mut self, data_start: u64, limit: u64) -> Result { + let mut pos = data_start; + while pos < limit { + let Some(h) = self.header(pos, limit)? else { return Ok(pos) }; + if is_top_level(h.id) || h.size == Size::Unknown { + return Ok(pos); + } + pos = h.end(limit); + } + Ok(limit) + } +} + +// --------------------------------------------------------------------------------------------- +// Blocks +// --------------------------------------------------------------------------------------------- + +#[derive(Clone, Debug)] +struct BlockRef { + track: usize, + block_offset: u64, + /// Timestamp in ticks (cluster + relative). + ts: i64, + /// Absolute (offset, size) of each frame. + frames: Vec<(u64, u32)>, + block_duration: Option, + keyframe: bool, + discardable: bool, + invisible: bool, + discard_padding: Option, + /// (offset, size) of the `BlockAdditional` with `BlockAddID` 1 (WebM: the VP8/VP9 alpha + /// layer), kept for unlaced blocks only. + addition: Option<(u64, u32)>, +} + +#[derive(Clone, Copy, Debug)] +struct FrameRef { + track: usize, + offset: u64, + size: u32, + pts: i64, + pts_ns: i64, + duration: u64, + duration_ns: u64, + keyframe: bool, + discardable: bool, + invisible: bool, + discard_padding: Option, + block_offset: u64, + lace: u16, + addition: Option<(u64, u32)>, +} + +/// Track number to track index. A duplicate number resolves to its first track. +type TrackIndex = HashMap; + +fn track_index(tracks: &[Track]) -> TrackIndex { + let mut m = HashMap::with_capacity(tracks.len()); + for (i, t) in tracks.iter().enumerate() { + m.entry(t.number).or_insert(i); + } + m +} + +/// A parsed block header: (track index, relative ts, flags, frames as (offset, size)). +type BlockHeader = (usize, i16, u8, Vec<(u64, u32)>); + +/// Parse the Block/SimpleBlock header at `data_start` (`len` bytes). +/// Returns `None` for unknown tracks / damage. +fn parse_block(io: &mut Io<'_, S>, data_start: u64, len: u64, lookup: &TrackIndex) -> Result> { + let head = io.peek(data_start, 16.min(len as usize))?; + let Some((tn, tl, _)) = ebml::read_vint(head) else { return Ok(None) }; + if head.len() < tl + 3 { + return Ok(None); + } + let rel = i16::from_be_bytes([head[tl], head[tl + 1]]); + let flags = head[tl + 2]; + let Some(&track) = lookup.get(&tn) else { return Ok(None) }; + let hdr = (tl + 3) as u64; + let lacing = Lacing::from_flags(flags); + let frames = if lacing == Lacing::None { + let Ok(size) = u32::try_from(len.saturating_sub(hdr)) else { return Ok(None) }; + vec![(data_start + hdr, size)] + } else { + let body_len = len.saturating_sub(hdr); + if body_len > MAX_LACED_BODY { + return Ok(None); + } + let body = io.read_vec(data_start + hdr, body_len)?; + let Ok(laced) = parse_lacing(lacing, &body) else { return Ok(None) }; + let mut frames = Vec::with_capacity(laced.len()); + for (o, l) in laced { + let Ok(size) = u32::try_from(l) else { return Ok(None) }; + frames.push((data_start + hdr + o as u64, size)); + } + frames + }; + Ok(Some((track, rel, flags, frames))) +} + +/// The `BlockAdditional` with `BlockAddID` 1 (the default ID) in a `BlockAdditions` element: +/// (offset, size) of its data. Other IDs, empty additions and damaged children are skipped. +fn block_addition(io: &mut Io<'_, S>, start: u64, end: u64) -> Result> { + let mut pos = start; + while pos < end { + let Some(more) = io.header(pos, end)? else { break }; + let me = more.end(end); + if more.id == BLOCK_MORE { + let (mut id, mut data) = (1u64, None); + let mut p = more.data_start(); + while p < me { + let Some(c) = io.header(p, me)? else { break }; + let ce = c.end(me); + let len = ce.saturating_sub(c.data_start()); + match c.id { + BLOCK_ADD_ID => id = ebml::uint(io.peek(c.data_start(), len.min(8) as usize)?), + BLOCK_ADDITIONAL => data = u32::try_from(len).ok().filter(|&n| n > 0).map(|n| (c.data_start(), n)), + _ => {} + } + p = ce; + } + if id == 1 && data.is_some() { + return Ok(data); + } + } + pos = me; + } + Ok(None) +} + +/// Cluster timestamps are unsigned; a hostile value beyond `i64::MAX` saturates, so adding a +/// block's relative timestamp cannot overflow. +fn sat_i64(v: i128) -> i64 { + v.clamp(i64::MIN as i128, i64::MAX as i128) as i64 +} + +fn cluster_timestamp(raw: u64) -> i64 { + i64::try_from(raw).unwrap_or(i64::MAX) +} + +/// Parse one SimpleBlock or BlockGroup element. +fn parse_block_elem(io: &mut Io<'_, S>, h: &Hdr, end: u64, cluster_ts: i64, lookup: &TrackIndex) -> Result> { + let ds = h.data_start(); + match h.id { + SIMPLE_BLOCK => { + let Some((track, rel, flags, frames)) = parse_block(io, ds, end - ds, lookup)? else { return Ok(None) }; + Ok(Some(BlockRef { + track, + block_offset: h.pos, + ts: cluster_ts.saturating_add(i64::from(rel)), + frames, + block_duration: None, + keyframe: flags & 0x80 != 0, + discardable: flags & 0x01 != 0, + invisible: flags & 0x08 != 0, + discard_padding: None, + addition: None, + })) + } + BLOCK_GROUP => { + let mut pos = ds; + let mut block = None; + let (mut dur, mut has_ref, mut pad, mut addition) = (None, false, None, None); + while pos < end { + let Some(c) = io.header(pos, end)? else { break }; + let ce = c.end(end); + match c.id { + BLOCK => block = parse_block(io, c.data_start(), ce - c.data_start(), lookup)?, + BLOCK_ADDITIONS => addition = block_addition(io, c.data_start(), ce)?, + BLOCK_DURATION => dur = Some(ebml::uint(io.peek(c.data_start(), (ce - c.data_start()) as usize)?)), + REFERENCE_BLOCK => has_ref = true, + DISCARD_PADDING => pad = Some(ebml::int(io.peek(c.data_start(), (ce - c.data_start()) as usize)?)), + _ => {} + } + pos = ce; + } + let Some((track, rel, flags, frames)) = block else { return Ok(None) }; + // with lacing, an addition belongs to the block, not to one of its frames + let addition = addition.filter(|_| frames.len() == 1); + Ok(Some(BlockRef { + track, + block_offset: h.pos, + ts: cluster_ts.saturating_add(i64::from(rel)), + frames, + block_duration: dur, + keyframe: !has_ref, + discardable: false, + invisible: flags & 0x08 != 0, + discard_padding: pad, + addition, + })) + } + _ => Ok(None), + } +} + +/// Expand a block into frames with per-lace timestamps. +fn expand(b: &BlockRef, t: &Track, scale: u64, skip: u16, out: &mut impl Extend) { + let n = b.frames.len() as u64; + // total block duration in ns + let block_ns: Option = match (b.block_duration, t.default_duration_ns) { + (Some(d), _) => Some(d as u128 * scale as u128), + (None, Some(dd)) => Some(dd as u128 * n as u128), + _ => None, + }; + let scale_i = scale as i128; + // round half away from zero + let to_ticks = |ns: i128| -> i64 { sat_i64(if ns >= 0 { (ns + scale_i / 2) / scale_i } else { (ns - scale_i / 2) / scale_i }) }; + // CodecDelay is subtracted from every timestamp (RFC 9559 §5.1.4.1.25); in ticks it is rounded + // once, so tick timestamps stay on the block grid. + let delay_ns = t.codec_delay_ns as i128; + let delay_ticks = to_ticks(delay_ns); + // `parse_info` caps the scale at 2^32, which keeps these products within i128; results + // outside i64 saturate. + let base_ns = b.ts as i128 * scale_i; + out.extend(b.frames.iter().enumerate().skip(skip as usize).map(|(i, &(offset, size))| { + let (start, end) = match block_ns { + Some(total) => ((total * i as u128 / n as u128) as i128, Some((total * (i as u128 + 1) / n as u128) as i128)), + None => (0, None), + }; + let pts_ns = base_ns + start - delay_ns; + let pts = to_ticks(base_ns + start).saturating_sub(delay_ticks); + let duration = end.map_or(0, |e| to_ticks(e).saturating_sub(to_ticks(start)).max(0) as u64); + FrameRef { + track: b.track, + offset, + size, + pts, + pts_ns: sat_i64(pts_ns), + duration, + duration_ns: end.map_or(0, |e| u64::try_from((e - start).max(0)).unwrap_or(u64::MAX)), + keyframe: b.keyframe, + discardable: b.discardable, + invisible: b.invisible, + discard_padding: b.discard_padding, + block_offset: b.block_offset, + lace: i as u16, + addition: b.addition, + } + })); +} + +/// Scan a whole cluster (headers only), returning its info and blocks. +fn scan_cluster( + io: &mut Io<'_, S>, + h: &Hdr, + limit: u64, + lookup: &TrackIndex, + budget: &mut FrameBudget, + warnings: &mut Vec, +) -> Result<(ClusterInfo, Vec)> { + let ds = h.data_start(); + let known_end = match h.size { + Size::Known(_) => Some(h.end(limit)), + Size::Unknown => None, + }; + let lim = known_end.unwrap_or(limit); + let mut ts: i64 = 0; + let mut blocks = Vec::new(); + let mut pos = ds; + let end = loop { + if pos >= lim { + break lim; + } + let Some(c) = io.header(pos, lim)? else { + warn(warnings, format!("damaged cluster at {}: undecodable element at {pos}", h.pos)); + break io.resync(pos + 1, limit)?.unwrap_or(limit); + }; + if known_end.is_none() && is_top_level(c.id) { + break pos; + } + if c.size == Size::Unknown || c.overruns(lim) { + warn(warnings, format!("damaged cluster at {}: element 0x{:X} at {pos} overruns", h.pos, c.id)); + if c.overruns(lim) && matches!(c.id, SIMPLE_BLOCK | BLOCK_GROUP) && io.len <= c.data_start() + c.size.known().unwrap_or(0) { + break lim; // truncated file: drop the partial block + } + break io.resync(pos + 1, limit)?.unwrap_or(limit); + } + let ce = c.end(lim); + match c.id { + TIMESTAMP => ts = cluster_timestamp(ebml::uint(io.peek(c.data_start(), (ce - c.data_start()) as usize)?)), + SIMPLE_BLOCK | BLOCK_GROUP => { + if let Some(b) = parse_block_elem(io, &c, ce, ts, lookup)? { + budget.take(&b.frames)?; + blocks.push(b); + } + } + _ => {} + } + pos = ce; + }; + Ok((ClusterInfo { offset: h.pos, data_start: ds, end, timestamp: ts.max(0) as u64 }, blocks)) +} + +// --------------------------------------------------------------------------------------------- +// Open +// --------------------------------------------------------------------------------------------- + +/// Open a Matroska/WebM file with default options (full sample index). +pub fn open(src: S) -> Result { + open_with(src, &OpenOptions::default()) +} + +/// Open with explicit options. +pub fn open_with(src: S, opts: &OpenOptions) -> Result { + let mut cache = Cache::default(); + open_impl(&src, opts, &mut cache) +} + +fn open_impl(src: &S, opts: &OpenOptions, cache: &mut Cache) -> Result { + // each pass over the file (open, building the index) gets the whole budget + cache.recovery_left = RECOVERY_BUDGET; + let mut io = Io::new(src, cache); + if let Some(l) = opts.index_limit.filter(|_| opts.index) { + io.avail = l; + } + let len = io.len; + // EBML header (tolerate leading junk in the first 64 KiB) + let start = { + let magic = [0x1A, 0x45, 0xDF, 0xA3]; + // the usual case needs 4 bytes, not the whole window (a source may hold only the front of the file) + if io.peek(0, 4)? == magic { + 0 + } else { + let b = io.peek(0, WIN)?; + b.windows(4).position(|w| w == magic).ok_or_else(|| Error::NotMatroska("no EBML header".into()))? as u64 + } + }; + let eh = io.header(start, len)?.ok_or_else(|| Error::NotMatroska("bad EBML header".into()))?; + let hdr_end = eh.end(len); + let hdr_len = hdr_end - eh.data_start(); + if hdr_len > MAX_EBML_HEADER { + return Err(Error::NotMatroska(format!("EBML header of {hdr_len} bytes"))); + } + let hdr = io.read_vec(eh.data_start(), hdr_len)?; + let (mut doc_type, mut dtv, mut dtrv) = ("matroska".to_string(), 1, 1); + for e in Children::new(&hdr) { + match e.id { + DOC_TYPE => doc_type = ebml::string(e.data), + DOC_TYPE_VERSION => dtv = ebml::uint(e.data), + DOC_TYPE_READ_VERSION => dtrv = ebml::uint(e.data), + EBML_MAX_ID_LENGTH if ebml::uint(e.data) > 4 => return Err(Error::Unsupported("EBMLMaxIDLength > 4".into())), + EBML_MAX_SIZE_LENGTH if ebml::uint(e.data) > 8 => return Err(Error::Unsupported("EBMLMaxSizeLength > 8".into())), + _ => {} + } + } + if doc_type != "matroska" && doc_type != "webm" { + return Err(Error::NotMatroska(format!("DocType {doc_type:?}"))); + } + // Segment + let mut pos = hdr_end; + let seg = loop { + let h = io.header(pos, len)?.ok_or_else(|| Error::Invalid("no Segment".into()))?; + if h.id == SEGMENT { + break h; + } + if h.size == Size::Unknown { + return Err(Error::Invalid("unknown-size element before Segment".into())); + } + pos = h.end(len); + }; + let mut file = MkvFile { + doc_type, + doc_type_version: dtv, + doc_type_read_version: dtrv, + segment_data_start: seg.data_start(), + segment_end: seg.end(len), + live: seg.size == Size::Unknown, + info: SegmentInfo::default(), + tracks: Vec::new(), + seek_head: Vec::new(), + cues: Vec::new(), + clusters: Vec::new(), + chapters: Vec::new(), + tags: Vec::new(), + attachments: Vec::new(), + first_cluster: None, + indexed: false, + index_end: None, + resume: None, + crc_checked: 0, + crc_errors: Vec::new(), + warnings: Vec::new(), + }; + if seg.overruns(len) { + warn(&mut file.warnings, "Segment extends past end of file (truncated)".into()); + } + let mut w = + Walker { opts, parsed: HashMap::new(), meta_left: len, blocks_seen: false, resuming: false, lookup: None, budget: FrameBudget::new(len) }; + w.walk(&mut io, &mut file)?; + finish_tracks(&mut file); + Ok(file) +} + +struct Walker<'o> { + opts: &'o OpenOptions, + /// Start and end of each level-1 element read. + parsed: HashMap, + /// Bytes level-1 elements may still read or scan. Distinct elements do not overlap, so a + /// valid file stays within its length; SeekHead entries pointing into one another do not. + meta_left: u64, + blocks_seen: bool, + /// Continuing a scan (see [`MkvFile::extend_index`]): keep `file.index_end` and the resume + /// state current, as a limited open does, so that a failed read can be retried. + resuming: bool, + /// Built at the first Cluster after Tracks is parsed. + lookup: Option, + budget: FrameBudget, +} + +impl Walker<'_> { + fn walk(&mut self, io: &mut Io<'_, S>, file: &mut MkvFile) -> Result<()> { + let start = file.segment_data_start; + self.walk_from(io, file, start) + } + + /// Walk the Segment's children from `start`. With an [`OpenOptions::index_limit`] the walk may + /// stop early, leaving `file.index_end` and the resume state for [`MkvFile::extend_index`]. + fn walk_from(&mut self, io: &mut Io<'_, S>, file: &mut MkvFile, start: u64) -> Result<()> { + let result = self.walk_children(io, file, start); + // Stopped early or failed part-way: hand the elements read so far to the next + // `extend_index`. `parsed` holds only elements read in full (see `level1`), so it is + // moved, not copied per element. + if file.index_end.is_some() { + file.resume = Some(Resume { parsed: std::mem::take(&mut self.parsed), meta_left: self.meta_left }); + } + result + } + + fn walk_children(&mut self, io: &mut Io<'_, S>, file: &mut MkvFile, start: u64) -> Result<()> { + let seg_end = file.segment_end; + let limit = self.opts.index_limit.filter(|_| self.opts.index); + if let Some(l) = limit { + io.avail = l; + } + let mut pos = start; + let track = limit.is_some() || self.resuming; + let mut stopped = false; + while pos < seg_end { + if track { + self.save(file, pos); + } + // the first Cluster is always scanned; the rest only while they fit below the limit + // (checked before the header is read: that lies past the limit too) + if limit.is_some_and(|l| pos >= l) && !file.clusters.is_empty() { + stopped = true; + break; + } + let Some(h) = io.header(pos, seg_end)? else { + match io.resync(pos + 1, seg_end)? { + Some(p) => { + warn(&mut file.warnings, format!("undecodable element at {pos}; resynced at {p}")); + pos = p; + continue; + } + None => break, + } + }; + if let Some(l) = limit + && !file.clusters.is_empty() + && matches!(h.size, Size::Known(_)) + && h.end(seg_end) > l + { + stopped = true; + break; + } + match h.id { + CLUSTER => { + if file.first_cluster.is_none() { + file.first_cluster = Some(h.pos); + // make sure Info/Tracks are known before interpreting blocks + self.follow_seek_head(io, file, &[INFO, TRACKS], u64::MAX)?; + if !self.opts.index { + break; + } + } + let lookup = self.lookup.get_or_insert_with(|| track_index(&file.tracks)); + let (ci, blocks) = scan_cluster(io, &h, seg_end, lookup, &mut self.budget, &mut file.warnings)?; + if self.opts.verify_crc && h.size != Size::Unknown { + let data = io.read_vec(h.data_start(), ci.end - h.data_start())?; + self.check_crc(file, h.pos, &data); + } + add_blocks(file, file.clusters.len() as u32, &blocks); + self.blocks_seen = true; + file.clusters.push(ci); + pos = ci.end.max(h.data_start()); + } + SEEK_HEAD | INFO | TRACKS | CUES | CHAPTERS | TAGS | ATTACHMENTS => { + pos = self.level1(io, file, &h, seg_end)?; + } + EBML | SEGMENT => break, // chained segment: only the first one is read + _ => { + if h.size == Size::Unknown { + pos = io.unknown_end(h.data_start(), seg_end)?; + } else if h.overruns(seg_end) && h.id != VOID { + match io.resync(pos + 1, seg_end)? { + Some(p) => { + warn(&mut file.warnings, format!("oversized element 0x{:X} at {pos}; resynced at {p}", h.id)); + pos = p; + } + None => break, + } + } else { + pos = h.end(seg_end); + } + } + } + } + if io.cache.recovery_left == 0 { + warn(&mut file.warnings, "recovery budget spent; the rest of the damaged data was not searched".into()); + } + if track { + self.save(file, pos); + } + if stopped { + // what lies after the scanned part (Cues, Tags…) waits for the rest of the index + let before = file.index_end.unwrap_or(pos); + self.follow_seek_head(io, file, &[INFO, TRACKS, CUES, CHAPTERS, TAGS, ATTACHMENTS, SEEK_HEAD], before)?; + file.cues.sort_by_key(|c| c.time); + file.indexed = false; + return Ok(()); + } + self.follow_seek_head(io, file, &[INFO, TRACKS, CUES, CHAPTERS, TAGS, ATTACHMENTS, SEEK_HEAD], u64::MAX)?; + // follow a second-level SeekHead reached through the first one + self.follow_seek_head(io, file, &[CUES, CHAPTERS, TAGS, ATTACHMENTS], u64::MAX)?; + file.cues.sort_by_key(|c| c.time); + file.indexed = self.opts.index; + file.index_end = None; + file.resume = None; + Ok(()) + } + + /// Record that everything before `pos` is done: a read that fails from here on (data not + /// loaded yet) can be retried by [`MkvFile::extend_index`] without repeating any of it. + fn save(&self, file: &mut MkvFile, pos: u64) { + file.index_end = Some(pos); + } + + /// Read the elements of the given kinds that the SeekHead points at below `before`. + fn follow_seek_head(&mut self, io: &mut Io<'_, S>, file: &mut MkvFile, ids: &[u32], before: u64) -> Result<()> { + let entries = file.seek_head.clone(); + for e in entries { + if !ids.contains(&e.id) { + continue; + } + let Some(abs) = file.segment_data_start.checked_add(e.position) else { continue }; + if self.parsed.contains_key(&abs) || abs >= file.segment_end || abs >= before { + continue; + } + match io.header(abs, file.segment_end)? { + Some(h) if h.id == e.id => { + self.level1(io, file, &h, file.segment_end)?; + } + _ => warn(&mut file.warnings, format!("SeekHead entry 0x{:X} -> {abs} does not point at that element", e.id)), + } + } + Ok(()) + } + + fn check_crc(&self, file: &mut MkvFile, pos: u64, data: &[u8]) { + if let Some(ok) = ebml::verify_crc(data) { + file.crc_checked += 1; + if !ok { + file.crc_errors.push(pos); + warn(&mut file.warnings, format!("CRC-32 mismatch in element at {pos}")); + } + } + } + + /// Parse a level-1 metadata element; returns its end. An element whose read fails is left + /// unrecorded, so a retry reads it again and one that succeeded is never read twice. + fn level1(&mut self, io: &mut Io<'_, S>, file: &mut MkvFile, h: &Hdr, limit: u64) -> Result { + let known = self.parsed.contains_key(&h.pos); + let (meta_left, attachments) = (self.meta_left, file.attachments.len()); + let result = self.level1_read(io, file, h, limit); + if result.is_err() && !known { + self.parsed.remove(&h.pos); + self.meta_left = meta_left; + file.attachments.truncate(attachments); + } + result + } + + fn level1_read(&mut self, io: &mut Io<'_, S>, file: &mut MkvFile, h: &Hdr, limit: u64) -> Result { + if let Some(&end) = self.parsed.get(&h.pos) { + return Ok(end); + } + let end = match h.size { + Size::Unknown => io.unknown_end(h.data_start(), limit.min(h.data_start().saturating_add(self.meta_left)))?, + Size::Known(_) => h.end(limit), + }; + self.parsed.insert(h.pos, end); + if h.overruns(limit) { + warn(&mut file.warnings, format!("element 0x{:X} at {} truncated", h.id, h.pos)); + } + let n = end - h.data_start(); + if n > self.meta_left || (h.size == Size::Unknown && n == self.meta_left && end < limit) { + self.meta_left = 0; + warn(&mut file.warnings, format!("element 0x{:X} at {} overlaps elements already read; skipped", h.id, h.pos)); + return Ok(end); + } + self.meta_left -= n; + if h.id == ATTACHMENTS { + self.attachments(io, file, h.data_start(), end)?; + return Ok(end); + } + let n = end - h.data_start(); + if n > MAX_META { + warn(&mut file.warnings, format!("element 0x{:X} at {} too large ({n} bytes); skipped", h.id, h.pos)); + return Ok(end); + } + let data = io.read_vec(h.data_start(), n)?; + if self.opts.verify_crc { + self.check_crc(file, h.pos, &data); + } + match h.id { + SEEK_HEAD => file.seek_head.extend(parse_seekhead(&data)), + INFO => file.info = parse_info(&data), + TRACKS if file.tracks.is_empty() => { + if Children::new(&data).filter(|e| e.id == TRACK_ENTRY).count() > MAX_TRACKS { + return Err(Error::TooLarge("track count")); + } + file.tracks = parse_tracks(&data, file.info.timestamp_scale); + self.lookup = None; + } + CUES => parse_cues(&data, &mut file.cues), + CHAPTERS => parse_chapters(&data, &mut file.chapters), + TAGS => parse_tags(&data, &mut file.tags), + _ => {} + } + Ok(end) + } + + fn attachments(&mut self, io: &mut Io<'_, S>, file: &mut MkvFile, start: u64, end: u64) -> Result<()> { + let mut pos = start; + while pos < end { + let Some(h) = io.header(pos, end)? else { break }; + let he = h.end(end); + if h.id == ATTACHED_FILE { + let mut a = Attachment::default(); + let mut p = h.data_start(); + while p < he { + let Some(c) = io.header(p, he)? else { break }; + let ce = c.end(he); + let n = ce - c.data_start(); + if c.id == FILE_DATA { + a.data_offset = c.data_start(); + a.data_size = n; + } else if n <= 4096 { + let d = io.peek(c.data_start(), n as usize)?; + match c.id { + FILE_NAME => a.name = ebml::string(d), + FILE_MEDIA_TYPE => a.media_type = ebml::string(d), + FILE_DESCRIPTION => a.description = Some(ebml::string(d)), + FILE_UID => a.uid = ebml::uint(d), + _ => {} + } + } + p = ce; + } + file.attachments.push(a); + } + pos = he; + } + Ok(()) + } +} + +fn add_blocks(file: &mut MkvFile, cluster: u32, blocks: &[BlockRef]) { + let scale = file.info.timestamp_scale; + let mut frames: Vec = Vec::new(); + for b in blocks { + frames.clear(); + let t = &file.tracks[b.track]; + expand(b, t, scale, 0, &mut frames); + let t = &mut file.tracks[b.track]; + for f in &frames { + if f.keyframe { + t.sync.push(t.samples.len() as u32); + } + t.samples.push(Sample { + offset: f.offset, + size: f.size, + pts: f.pts, + duration: f.duration, + keyframe: f.keyframe, + cluster, + block_offset: f.block_offset, + lace: f.lace, + addition: f.addition, + }); + } + } +} + +fn finish_tracks(file: &mut MkvFile) { + let scale = file.info.timestamp_scale; + let g = gcd(scale, 1_000_000_000); + for t in &mut file.tracks { + t.timebase = (scale / g, 1_000_000_000 / g); + } +} + +// --------------------------------------------------------------------------------------------- +// MkvFile helpers +// --------------------------------------------------------------------------------------------- + +impl MkvFile { + /// True for WebM (`DocType` = `webm`). + pub fn is_webm(&self) -> bool { + self.doc_type == "webm" + } + + /// Segment duration in ns: `Info/Duration` if present, else the end of the last indexed sample. + pub fn duration_ns(&self) -> Option { + if let Some(d) = self.info.duration { + return Some((d * self.info.timestamp_scale as f64).round() as u64); + } + let end = self.tracks.iter().flat_map(|t| t.samples.iter().map(|s| s.pts.saturating_add(s.duration.min(i64::MAX as u64) as i64))).max()?; + Some((end.max(0) as u64).saturating_mul(self.info.timestamp_scale)) + } + + /// Continue a scan that an [`OpenOptions::index_limit`] stopped, from [`MkvFile::index_end`], + /// without rescanning what is indexed. `opts.index_limit` bounds the new scan like at open + /// (`None`: to the end of the Segment, which completes the index: Cues, Tags… are read and + /// [`MkvFile::indexed`] becomes `true`); `opts.verify_crc` applies as at open. + /// + /// A no-op when there is nothing left to scan, including a limit at or below `index_end`. + /// Safe to call again after an error such as a byte source that has not loaded the range yet + /// (`WouldBlock`): the clusters scanned before the failure stay indexed and `index_end` says + /// where the next call continues. + pub fn extend_index(&mut self, src: &S, opts: &OpenOptions) -> Result<()> { + let Some(start) = self.index_end else { return Ok(()) }; + let resume = self.resume.take().unwrap_or_default(); + let opts = OpenOptions { index: true, ..opts.clone() }; + let mut cache = Cache::default(); + let mut io = Io::new(src, &mut cache); + let budget = FrameBudget::resumed(io.len, &self.tracks); + let mut w = + Walker { opts: &opts, parsed: resume.parsed, meta_left: resume.meta_left, blocks_seen: true, resuming: true, lookup: None, budget }; + w.walk_from(&mut io, self, start) + } + + /// Index of the track with this `TrackNumber`. + pub fn track_by_number(&self, number: u64) -> Option { + self.tracks.iter().position(|t| t.number == number) + } + + /// Index of the first track of the given kind (preferring the default flag). + pub fn track_of_kind(&self, kind: TrackKind) -> Option { + let mut it = self.tracks.iter().enumerate().filter(|(_, t)| t.kind == kind); + let first = it.clone().next().map(|x| x.0); + it.find(|(_, t)| t.default).map(|x| x.0).or(first) + } + + /// Read sample `index` of `track` (header stripping undone). + pub fn read_sample(&self, src: &S, track: usize, index: usize) -> Result> { + let t = self.tracks.get(track).ok_or(Error::NoSuchTrack(track))?; + let s = t.samples.get(index).ok_or(Error::NoSuchSample(index))?; + if !t.frames_readable() { + return Err(Error::Unsupported(format!("content encoding of track {} (compression/encryption)", t.number))); + } + let mut data = t.frame_prefix(s.size as u64); + let at = data.len(); + data.resize(at + s.size as usize, 0); + src.read_at(s.offset, &mut data[at..])?; + Ok(data) + } + + /// The `BlockAdditional` (ID 1) of sample `index` of `track`, `None` when the block has none + /// (see [`Sample::addition`]). Stored as is: header stripping applies to frames only. + pub fn read_sample_addition(&self, src: &S, track: usize, index: usize) -> Result>> { + let t = self.tracks.get(track).ok_or(Error::NoSuchTrack(track))?; + let s = t.samples.get(index).ok_or(Error::NoSuchSample(index))?; + let Some((offset, size)) = s.addition else { return Ok(None) }; + if offset.checked_add(size as u64).is_none_or(|end| end > src.len()) { + return Err(Error::Invalid("block addition past end of file".into())); + } + let mut data = vec![0; size as usize]; + src.read_at(offset, &mut data)?; + Ok(Some(data)) + } + + /// Keyframe sample of `track` with the greatest pts ≤ `time_ns` (indexed files only). + pub fn keyframe_before(&self, track: usize, time_ns: i64) -> Option { + let t = self.tracks.get(track)?; + t.keyframe_before_pts(t.ns_to_ticks(time_ns)) + } +} + +// --------------------------------------------------------------------------------------------- +// Demuxer (streaming packets + seeking) +// --------------------------------------------------------------------------------------------- + +#[derive(Clone, Copy, Debug)] +struct InCluster { + ts: i64, + end: Option, +} + +/// Packet reader over a [`ByteSource`]: iterates frames in file order and seeks to keyframes. +pub struct Demuxer { + src: S, + file: MkvFile, + opts: OpenOptions, + cache: Cache, + lookup: TrackIndex, + pos: u64, + cluster: Option, + pending: VecDeque, + skip_laces: Option<(u64, u16)>, + done: bool, +} + +impl Demuxer> { + /// Open from any `Read + Seek` stream. + pub fn from_reader(r: R) -> Result { + Self::new(ReadSeekSource::new(r)?) + } +} + +impl<'a> Demuxer<&'a [u8]> { + /// Open from an in-memory byte slice. + pub fn from_slice(data: &'a [u8]) -> Result { + Self::new(data) + } +} + +impl Demuxer { + /// Open with default options (full index). + pub fn new(src: S) -> Result { + Self::with_options(src, OpenOptions::default()) + } + + pub fn with_options(src: S, opts: OpenOptions) -> Result { + let mut cache = Cache::default(); + let file = open_impl(&src, &opts, &mut cache)?; + // reading packets recovers from damage on its own budget, not what the open left + cache.recovery_left = RECOVERY_BUDGET; + let pos = file.first_cluster.unwrap_or(file.segment_end); + let lookup = track_index(&file.tracks); + Ok(Self { src, file, opts, cache, lookup, pos, cluster: None, pending: VecDeque::new(), skip_laces: None, done: false }) + } + + pub fn file(&self) -> &MkvFile { + &self.file + } + pub fn tracks(&self) -> &[Track] { + &self.file.tracks + } + pub fn source(&self) -> &S { + &self.src + } + pub fn into_parts(self) -> (S, MkvFile) { + (self.src, self.file) + } + /// Segment duration in ns. + pub fn duration_ns(&self) -> Option { + self.file.duration_ns() + } + + /// Scan all clusters and build sample tables (no-op if already indexed; continues a scan that + /// stopped at [`OpenOptions::index_limit`] from where it stopped). + pub fn build_index(&mut self) -> Result<()> { + if self.file.indexed { + return Ok(()); + } + let opts = OpenOptions { index: true, verify_crc: self.opts.verify_crc, index_limit: None }; + if self.file.index_end.is_some() { + return self.file.extend_index(&self.src, &opts); + } + self.file = open_impl(&self.src, &opts, &mut self.cache)?; + // the index pass spent its own budget; packet reading keeps a whole one + self.cache.recovery_left = RECOVERY_BUDGET; + self.lookup = track_index(&self.file.tracks); + Ok(()) + } + + /// Keyframes of `track` (builds the index if needed). + pub fn keyframe_index(&mut self, track: usize) -> Result> { + self.build_index()?; + let t = self.file.tracks.get(track).ok_or(Error::NoSuchTrack(track))?; + Ok(t.keyframes() + .iter() + .map(|&k| { + let s = &t.samples[k as usize]; + Keyframe { sample: k as usize, pts: s.pts, pts_ns: t.ticks_to_ns(s.pts), block_offset: s.block_offset } + }) + .collect()) + } + + /// Rewind to the first cluster. + pub fn rewind(&mut self) { + self.pos = self.file.first_cluster.unwrap_or(self.file.segment_end); + self.cluster = None; + self.pending.clear(); + self.skip_laces = None; + self.done = false; + } + + /// Read sample `index` of `track` (requires an index). + pub fn read_sample(&self, track: usize, index: usize) -> Result> { + self.file.read_sample(&self.src, track, index) + } + + /// Position the packet stream at the keyframe of `track` with the greatest pts ≤ `time_ns` + /// (or the track's first keyframe if none precedes it). The next [`Demuxer::next_packet`] + /// call returns packets starting at that keyframe's block (all tracks). + /// + /// Uses the sample index when present, else Cues (refined by scanning the cued cluster), else + /// builds the index first. + pub fn seek(&mut self, track: usize, time_ns: i64) -> Result { + let t = self.file.tracks.get(track).ok_or(Error::NoSuchTrack(track))?; + let ticks = t.ns_to_ticks(time_ns); + if !self.file.indexed { + let tn = t.number; + let cue = self + .file + .cues + .iter() + .filter(|c| c.time as i64 <= ticks) + .filter_map(|c| c.positions.iter().find(|p| p.track == tn).map(|p| (c.time, *p))) + .next_back() + .or_else(|| self.file.cues.iter().find_map(|c| c.positions.iter().find(|p| p.track == tn).map(|p| (c.time, *p)))); + if let Some((_, cp)) = cue + && let Some(sp) = self.seek_via_cue(track, ticks, cp.cluster_position)? + { + return Ok(sp); + } + self.build_index()?; + } + let t = &self.file.tracks[track]; + let k = t.keyframe_before_pts(ticks).ok_or_else(|| Error::Invalid(format!("track {} has no keyframes", t.number)))?; + let s = t.samples[k]; + let c = self.file.clusters[s.cluster as usize]; + let sp = + SeekPoint { track, pts: s.pts, pts_ns: t.ticks_to_ns(s.pts), sample: Some(k), cluster_offset: c.offset, block_offset: s.block_offset }; + self.position_at(c, s.block_offset, s.lace); + Ok(sp) + } + + fn position_at(&mut self, c: ClusterInfo, block_offset: u64, lace: u16) { + self.pending.clear(); + self.done = false; + self.pos = block_offset; + let known = c.end; + self.cluster = Some(InCluster { ts: cluster_timestamp(c.timestamp), end: Some(known) }); + self.skip_laces = (lace > 0).then_some((block_offset, lace)); + } + + fn seek_via_cue(&mut self, track: usize, ticks: i64, cluster_position: u64) -> Result> { + let Some(abs) = self.file.segment_data_start.checked_add(cluster_position) else { + warn(&mut self.file.warnings, format!("cue position {cluster_position} is past the segment end")); + return Ok(None); + }; + let mut io = Io::new(&self.src, &mut self.cache); + let Some(h) = io.header(abs, self.file.segment_end)? else { return Ok(None) }; + if h.id != CLUSTER { + warn(&mut self.file.warnings, format!("cue points at {abs}, which is not a Cluster")); + return Ok(None); + } + let mut warnings = Vec::new(); + let mut budget = FrameBudget::new(io.len); + let (ci, blocks) = scan_cluster(&mut io, &h, self.file.segment_end, &self.lookup, &mut budget, &mut warnings)?; + let t = &self.file.tracks[track]; + let mut frames = Vec::new(); + for b in blocks.iter().filter(|b| b.track == track && b.keyframe) { + expand(b, t, self.file.info.timestamp_scale, 0, &mut frames); + } + let best = frames.iter().filter(|f| f.pts <= ticks).max_by_key(|f| f.pts).or_else(|| frames.iter().min_by_key(|f| f.pts)).copied(); + let Some(f) = best else { return Ok(None) }; + let sp = SeekPoint { track, pts: f.pts, pts_ns: f.pts_ns, sample: None, cluster_offset: ci.offset, block_offset: f.block_offset }; + self.position_at(ci, f.block_offset, f.lace); + Ok(Some(sp)) + } + + /// Next frame in file order, or `None` at the end of the Segment. + pub fn next_packet(&mut self) -> Result> { + loop { + if let Some(f) = self.pending.pop_front() { + return self.materialize(f).map(Some); + } + if self.done || !self.fill()? { + self.done = true; + return Ok(None); + } + } + } + + fn materialize(&mut self, f: FrameRef) -> Result { + let t = &self.file.tracks[f.track]; + let mut data = if t.frames_readable() { t.frame_prefix(f.size as u64) } else { Vec::new() }; + let at = data.len(); + data.resize(at + f.size as usize, 0); + let mut io = Io::new(&self.src, &mut self.cache); + if (f.size as usize) <= WIN / 2 { + let b = io.peek(f.offset, f.size as usize)?; + if b.len() != f.size as usize { + return Err(Error::Invalid("frame data past end of file".into())); + } + data[at..].copy_from_slice(b); + } else { + self.src.read_at(f.offset, &mut data[at..])?; + } + Ok(Packet { + track: f.track, + track_number: t.number, + pts: f.pts, + pts_ns: f.pts_ns, + duration: f.duration, + duration_ns: f.duration_ns, + keyframe: f.keyframe, + discardable: f.discardable, + invisible: f.invisible, + discard_padding_ns: f.discard_padding, + offset: f.offset, + lace: f.lace, + data, + }) + } + + /// Advance over elements until at least one frame is pending. Returns false at the end. + fn fill(&mut self) -> Result { + let seg_end = self.file.segment_end; + let scale = self.file.info.timestamp_scale; + let mut io = Io::new(&self.src, &mut self.cache); + let lookup = &self.lookup; + loop { + if let Some(c) = self.cluster { + let lim = c.end.unwrap_or(seg_end); + if self.pos >= lim { + self.cluster = None; + continue; + } + let Some(h) = io.header(self.pos, lim)? else { + self.cluster = None; + match io.resync(self.pos + 1, seg_end)? { + Some(p) => { + self.pos = p; + continue; + } + None => return Ok(false), + } + }; + if c.end.is_none() && is_top_level(h.id) { + self.cluster = None; + continue; + } + if h.size == Size::Unknown || h.overruns(lim) { + self.cluster = None; + match io.resync(self.pos + 1, seg_end)? { + Some(p) => { + self.pos = p; + continue; + } + None => return Ok(false), + } + } + let he = h.end(lim); + self.pos = he; + match h.id { + TIMESTAMP => { + let v = cluster_timestamp(ebml::uint(io.peek(h.data_start(), (he - h.data_start()) as usize)?)); + self.cluster = Some(InCluster { ts: v, end: c.end }); + } + SIMPLE_BLOCK | BLOCK_GROUP => { + if let Some(b) = parse_block_elem(&mut io, &h, he, c.ts, lookup)? { + let skip = match self.skip_laces.take() { + Some((off, n)) if off == h.pos => n, + _ => 0, + }; + expand(&b, &self.file.tracks[b.track], scale, skip, &mut self.pending); + if !self.pending.is_empty() { + return Ok(true); + } + } + } + _ => {} + } + continue; + } + if self.pos >= seg_end { + return Ok(false); + } + let Some(h) = io.header(self.pos, seg_end)? else { + match io.resync(self.pos + 1, seg_end)? { + Some(p) => { + self.pos = p; + continue; + } + None => return Ok(false), + } + }; + match h.id { + CLUSTER => { + self.cluster = Some(InCluster { ts: 0, end: h.size.known().map(|_| h.end(seg_end)) }); + self.pos = h.data_start(); + } + EBML | SEGMENT => return Ok(false), + _ => { + self.pos = if h.size == Size::Unknown { io.unknown_end(h.data_start(), seg_end)? } else { h.end(seg_end) }; + if self.pos <= h.pos { + return Ok(false); + } + } + } + } + } +} + +impl Iterator for Demuxer { + type Item = Result; + fn next(&mut self) -> Option> { + match self.next_packet() { + Ok(Some(p)) => Some(Ok(p)), + Ok(None) => None, + Err(e) => { + self.done = true; + Some(Err(e)) + } + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn frames_indexed_scale_with_the_file_length() { + assert_eq!(FrameBudget::new(1000).frames, MIN_FRAME_ALLOWANCE); + // 64 MiB of file is enough bytes for 2^26 empty frames, but not enough index memory. + let mut b = FrameBudget::new(64 << 20); + assert_eq!(b.frames, 8 << 20); + let lace = [(0u64, 0u32); 256]; + let taken = (0..1 << 18).take_while(|_| b.take(&lace).is_ok()).count(); + assert_eq!(taken * lace.len(), 8 << 20); + assert_eq!(FrameBudget::new(u64::MAX).frames, MAX_FRAMES); + } +} diff --git a/crates/media/src/matroska/ebml.rs b/crates/media/src/matroska/ebml.rs new file mode 100644 index 000000000..95a680e75 --- /dev/null +++ b/crates/media/src/matroska/ebml.rs @@ -0,0 +1,476 @@ +//! EBML primitives (RFC 8794): variable-length integers, element headers, typed values, CRC-32, +//! and Matroska block lacing (RFC 9559 §10.3). + +use crate::matroska::error::{Result, invalid}; + +/// Length in bytes of a VINT whose first byte is `b` (1..=8), or `None` for a zero first byte. +#[inline] +pub fn vint_len(b: u8) -> Option { + if b == 0 { None } else { Some(b.leading_zeros() as usize + 1) } +} + +/// Element data size: known, or "unknown" (all value bits set). +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Size { + Known(u64), + Unknown, +} + +impl Size { + pub fn known(self) -> Option { + match self { + Size::Known(n) => Some(n), + Size::Unknown => None, + } + } +} + +/// Decode an unsigned VINT (marker bit stripped). Returns `(value, length, all_ones)`. +pub fn read_vint(data: &[u8]) -> Option<(u64, usize, bool)> { + let first = *data.first()?; + let len = vint_len(first)?; + if data.len() < len { + return None; + } + let mask = if len == 8 { 0 } else { 0xFFu8 >> len }; + let mut v = (first & mask) as u64; + for &b in &data[1..len] { + v = (v << 8) | b as u64; + } + let all_ones = v == (1u64 << (7 * len)) - 1; + Some((v, len, all_ones)) +} + +/// Decode an element data size. All-ones is the reserved "unknown size". +pub fn read_size(data: &[u8]) -> Option<(Size, usize)> { + let (v, len, ones) = read_vint(data)?; + Some((if ones { Size::Unknown } else { Size::Known(v) }, len)) +} + +/// Decode an element ID (marker bits kept, 1..=4 bytes). Rejects all-ones value bits (reserved). +/// All-zero value bits are accepted, because Matroska's `ChapterDisplay` uses ID `0x80`. +pub fn read_id(data: &[u8]) -> Option<(u32, usize)> { + let first = *data.first()?; + let len = vint_len(first)?; + if len > 4 || data.len() < len { + return None; + } + let (v, _, ones) = read_vint(&data[..len])?; + if ones || (v == 0 && len > 1) { + return None; + } + let mut id = 0u32; + for &b in &data[..len] { + id = (id << 8) | b as u32; + } + Some((id, len)) +} + +/// Decode a signed VINT as used by EBML lacing (value − (2^(7·len−1) − 1)). +pub fn read_svint(data: &[u8]) -> Option<(i64, usize)> { + let (v, len, _) = read_vint(data)?; + let bias = (1i64 << (7 * len - 1)) - 1; + Some((v as i64 - bias, len)) +} + +/// Encode an element ID (already carrying its marker bits). +pub fn write_id(out: &mut Vec, id: u32) { + let n = if id >= 0x100_0000 { + 4 + } else if id >= 0x1_0000 { + 3 + } else if id >= 0x100 { + 2 + } else { + 1 + }; + out.extend_from_slice(&id.to_be_bytes()[4 - n..]); +} + +/// Encode a data size as a VINT using the shortest length (or `min_len` if larger). +pub fn write_size(out: &mut Vec, size: u64, min_len: usize) { + let mut len = 1; + while len < 8 && size >= (1u64 << (7 * len)) - 1 { + len += 1; + } + let len = len.max(min_len).min(8); + let v = size | (1u64 << (7 * len)); + out.extend_from_slice(&v.to_be_bytes()[8 - len..]); +} + +/// Encode the "unknown size" marker of the given length. +pub fn write_unknown_size(out: &mut Vec, len: usize) { + out.push(0xFFu8 >> (len - 1)); + out.extend(std::iter::repeat_n(0xFF, len - 1)); +} + +/// Big-endian unsigned integer of 0..=8 bytes. +pub fn uint(data: &[u8]) -> u64 { + data.iter().take(8).fold(0u64, |a, &b| (a << 8) | b as u64) +} + +/// Big-endian two's-complement signed integer of 0..=8 bytes. +pub fn int(data: &[u8]) -> i64 { + let n = data.len().min(8); + if n == 0 { + return 0; + } + let v = uint(&data[..n]); + let shift = 64 - 8 * n as u32; + ((v << shift) as i64) >> shift +} + +/// IEEE float of 0, 4 or 8 bytes. +pub fn float(data: &[u8]) -> f64 { + match data.len() { + 4 => f32::from_be_bytes(data.try_into().unwrap_or([0; 4])) as f64, + 8 => f64::from_be_bytes(data.try_into().unwrap_or([0; 8])), + _ => 0.0, + } +} + +/// String / UTF-8 value: bytes up to the first NUL, lossily decoded. +pub fn string(data: &[u8]) -> String { + let end = data.iter().position(|&b| b == 0).unwrap_or(data.len()); + String::from_utf8_lossy(&data[..end]).into_owned() +} + +/// One element inside an in-memory master element. +#[derive(Clone, Copy, Debug)] +pub struct Elem<'a> { + pub id: u32, + /// Offset of the element header, relative to the start of the parent's data. + pub offset: usize, + pub header_len: usize, + pub data: &'a [u8], + /// The size field was "unknown" (data runs to the end of the parent). + pub unknown_size: bool, + /// The declared size overran the parent and was truncated. + pub truncated: bool, +} + +/// Iterator over the children of an in-memory master element. +/// +/// Damaged data ends the iteration (see [`Children::damaged`]); oversize elements are truncated to +/// the parent's end. +pub struct Children<'a> { + data: &'a [u8], + pos: usize, + damaged: bool, +} + +impl<'a> Children<'a> { + pub fn new(data: &'a [u8]) -> Self { + Self { data, pos: 0, damaged: false } + } + /// True if iteration stopped on an undecodable header. + pub fn damaged(&self) -> bool { + self.damaged + } +} + +impl<'a> Iterator for Children<'a> { + type Item = Elem<'a>; + fn next(&mut self) -> Option> { + let rest = self.data.get(self.pos..)?; + if rest.is_empty() { + return None; + } + let Some((id, il)) = read_id(rest) else { + self.damaged = true; + self.pos = self.data.len(); + return None; + }; + let Some((size, sl)) = read_size(&rest[il..]) else { + self.damaged = true; + self.pos = self.data.len(); + return None; + }; + let hl = il + sl; + let avail = (rest.len() - hl) as u64; + let (len, unknown, truncated) = match size { + Size::Known(n) if n <= avail => (n as usize, false, false), + Size::Known(_) => (avail as usize, false, true), + Size::Unknown => (avail as usize, true, false), + }; + let e = Elem { id, offset: self.pos, header_len: hl, data: &rest[hl..hl + len], unknown_size: unknown, truncated }; + self.pos += hl + len; + Some(e) + } +} + +/// CRC-32 (ISO 3309 / IEEE 802.3, reflected polynomial 0xEDB88320), as used by EBML CRC-32 elements. +pub fn crc32(data: &[u8]) -> u32 { + crc32_update(0xFFFF_FFFF, data) ^ 0xFFFF_FFFF +} + +/// Incremental form: start with `0xFFFF_FFFF`, finish with `^ 0xFFFF_FFFF`. +pub fn crc32_update(mut crc: u32, data: &[u8]) -> u32 { + static TABLE: std::sync::OnceLock<[u32; 256]> = std::sync::OnceLock::new(); + let t = TABLE.get_or_init(|| { + let mut t = [0u32; 256]; + for (i, e) in t.iter_mut().enumerate() { + let mut c = i as u32; + for _ in 0..8 { + c = if c & 1 != 0 { 0xEDB8_8320 ^ (c >> 1) } else { c >> 1 }; + } + *e = c; + } + t + }); + for &b in data { + crc = t[((crc ^ b as u32) & 0xFF) as usize] ^ (crc >> 8); + } + crc +} + +/// Check a master element's leading CRC-32 child, if present. `Some(true/false)` if there is one. +pub fn verify_crc(master_data: &[u8]) -> Option { + let mut it = Children::new(master_data); + let first = it.next()?; + if first.id != crate::matroska::ids::CRC32 || first.data.len() != 4 { + return None; + } + let stored = u32::from_le_bytes(first.data.try_into().ok()?); + let rest = &master_data[first.offset + first.header_len + 4..]; + Some(crc32(rest) == stored) +} + +/// Block lacing mode (flags bits 1–2). +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Lacing { + None, + Xiph, + FixedSize, + Ebml, +} + +impl Lacing { + pub fn from_flags(flags: u8) -> Lacing { + match (flags >> 1) & 3 { + 0 => Lacing::None, + 1 => Lacing::Xiph, + 2 => Lacing::FixedSize, + _ => Lacing::Ebml, + } + } +} + +/// Split laced block payload. `data` starts right after the block's flags byte and runs to the end +/// of the block. Returns `(offset, len)` of each frame relative to `data`. +pub fn parse_lacing(lacing: Lacing, data: &[u8]) -> Result> { + if lacing == Lacing::None { + return Ok(vec![(0, data.len())]); + } + let Some(&n1) = data.first() else { return invalid("laced block without frame count") }; + let count = n1 as usize + 1; + let mut pos = 1usize; + let mut sizes = Vec::with_capacity(count); + match lacing { + Lacing::None => return Ok(vec![(0, data.len())]), + Lacing::Xiph => { + for _ in 0..count - 1 { + let mut s = 0usize; + loop { + let Some(&b) = data.get(pos) else { return invalid("truncated Xiph lace header") }; + pos += 1; + s += b as usize; + if b != 255 { + break; + } + } + sizes.push(s); + } + } + Lacing::Ebml => { + if count > 1 { + let Some((first, l, _)) = read_vint(&data[pos..]) else { return invalid("bad EBML lace size") }; + pos += l; + let mut prev = first as i64; + sizes.push(first as usize); + for _ in 1..count - 1 { + let Some((d, l)) = read_svint(&data[pos..]) else { return invalid("bad EBML lace delta") }; + pos += l; + prev += d; + if prev < 0 { + return invalid("negative EBML lace size"); + } + sizes.push(prev as usize); + } + } + } + Lacing::FixedSize => { + let rest = data.len() - pos; + if !rest.is_multiple_of(count) { + return invalid("fixed-size lacing does not divide block"); + } + sizes.extend(std::iter::repeat_n(rest / count, count - 1)); + } + } + let used: usize = sizes.iter().try_fold(0usize, |a, &s| a.checked_add(s)).unwrap_or(usize::MAX); + if pos > data.len() || used > data.len() - pos { + return invalid("lace sizes exceed block"); + } + sizes.push(data.len() - pos - used); + let mut out = Vec::with_capacity(count); + for s in sizes { + out.push((pos, s)); + pos += s; + } + Ok(out) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn vint_roundtrip() { + for &v in &[0u64, 1, 126, 127, 128, 16382, 16383, 16384, 1 << 20, (1 << 56) - 2] { + let mut b = Vec::new(); + write_size(&mut b, v, 1); + let (s, l) = read_size(&b).unwrap(); + assert_eq!(s, Size::Known(v), "value {v}"); + assert_eq!(l, b.len()); + } + // 127 needs 2 bytes because 0xFF is "unknown" + let mut b = Vec::new(); + write_size(&mut b, 127, 1); + assert_eq!(b, [0x40, 0x7F]); + // padded length + let mut b = Vec::new(); + write_size(&mut b, 5, 8); + assert_eq!(b, [1, 0, 0, 0, 0, 0, 0, 5]); + assert_eq!(read_size(&b).unwrap(), (Size::Known(5), 8)); + } + + #[test] + fn vint_unknown_and_invalid() { + assert_eq!(read_size(&[0xFF]).unwrap(), (Size::Unknown, 1)); + assert_eq!(read_size(&[0x01, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF]).unwrap(), (Size::Unknown, 8)); + for l in 1..=8 { + let mut b = Vec::new(); + write_unknown_size(&mut b, l); + assert_eq!(read_size(&b).unwrap(), (Size::Unknown, l)); + } + assert!(read_size(&[0x00, 1, 2]).is_none()); + assert!(read_size(&[0x40]).is_none()); // truncated + assert_eq!(read_vint(&[0x81]).unwrap(), (1, 1, false)); + assert_eq!(read_vint(&[0x10, 0x00, 0x00, 0x01]).unwrap(), (1, 4, false)); + } + + #[test] + fn ids() { + assert_eq!(read_id(&[0x1A, 0x45, 0xDF, 0xA3, 0x99]).unwrap(), (crate::matroska::ids::EBML, 4)); + assert_eq!(read_id(&[0xA3]).unwrap(), (0xA3, 1)); + assert_eq!(read_id(&[0x42, 0x86]).unwrap(), (0x4286, 2)); + assert!(read_id(&[0xFF]).is_none()); // reserved + assert_eq!(read_id(&[0x80]).unwrap(), (0x80, 1)); // ChapterDisplay + assert!(read_id(&[0x40, 0x00]).is_none()); // zero value + assert!(read_id(&[0x08, 0, 0, 0, 1]).is_none()); // 5-byte ID + for id in [0xA3u32, 0x4286, 0x2AD7B1, 0x1F43B675] { + let mut b = Vec::new(); + write_id(&mut b, id); + assert_eq!(read_id(&b).unwrap(), (id, b.len())); + } + } + + #[test] + fn signed_vint() { + assert_eq!(read_svint(&[0xBF]).unwrap(), (0, 1)); // 63 - 63 + assert_eq!(read_svint(&[0x80]).unwrap(), (-63, 1)); + assert_eq!(read_svint(&[0xC0]).unwrap(), (1, 1)); + assert_eq!(read_svint(&[0x5F, 0xFF]).unwrap(), (0, 2)); + assert_eq!(read_svint(&[0x60, 0x00]).unwrap(), (1, 2)); + } + + #[test] + fn values() { + assert_eq!(uint(&[]), 0); + assert_eq!(uint(&[1, 0]), 256); + assert_eq!(int(&[0xFF]), -1); + assert_eq!(int(&[0xFF, 0xFE]), -2); + assert_eq!(int(&[0x7F]), 127); + assert_eq!(float(&1.5f32.to_be_bytes()), 1.5); + assert_eq!(float(&2.25f64.to_be_bytes()), 2.25); + assert_eq!(string(b"abc\0\0"), "abc"); + } + + #[test] + fn crc() { + assert_eq!(crc32(b"123456789"), 0xCBF4_3926); + let payload = [0x42u8, 0x86, 0x81, 0x01]; + let mut m = vec![0xBF, 0x84]; + m.extend_from_slice(&crc32(&payload).to_le_bytes()); + m.extend_from_slice(&payload); + assert_eq!(verify_crc(&m), Some(true)); + m[7] ^= 1; + assert_eq!(verify_crc(&m), Some(false)); + assert_eq!(verify_crc(&payload), None); + } + + #[test] + fn children_iter() { + // two elements, then one whose size overruns + let d = [0x42, 0x86, 0x81, 0x01, 0xEC, 0x82, 0, 0, 0xA3, 0x85, 1, 2]; + let v: Vec<_> = Children::new(&d).collect(); + assert_eq!(v.len(), 3); + assert_eq!(v[0].id, 0x4286); + assert_eq!(v[0].data, &[1]); + assert_eq!(v[1].id, 0xEC); + assert_eq!(v[2].data, &[1, 2]); + assert!(v[2].truncated); + let mut it = Children::new(&[0x00, 0x01]); + assert!(it.next().is_none()); + assert!(it.damaged()); + } + + fn frames<'a>(d: &'a [u8], f: &[(usize, usize)]) -> Vec<&'a [u8]> { + f.iter().map(|&(o, l)| &d[o..o + l]).collect() + } + + #[test] + fn lacing_xiph() { + // 3 frames: 300, 2, rest(3) + let mut d = vec![2u8, 255, 45, 2]; + d.extend(std::iter::repeat_n(7u8, 300)); + d.extend_from_slice(&[1, 2]); + d.extend_from_slice(&[3, 4, 5]); + let f = parse_lacing(Lacing::Xiph, &d).unwrap(); + assert_eq!(f.iter().map(|x| x.1).collect::>(), [300, 2, 3]); + assert_eq!(frames(&d, &f)[2], &[3, 4, 5]); + // exact multiple of 255 needs a terminating 0 + let mut d = vec![1u8, 255, 0]; + d.extend(std::iter::repeat_n(1u8, 255)); + d.push(9); + let f = parse_lacing(Lacing::Xiph, &d).unwrap(); + assert_eq!(f.iter().map(|x| x.1).collect::>(), [255, 1]); + assert!(parse_lacing(Lacing::Xiph, &[1, 200, 1]).is_err()); + } + + #[test] + fn lacing_ebml() { + // 4 frames: 5, 3 (delta -2), 4 (delta +1), rest 2 + let mut d = vec![3u8, 0x85, 0xBF - 2, 0xBF + 1]; + d.extend_from_slice(&[1; 5]); + d.extend_from_slice(&[2; 3]); + d.extend_from_slice(&[3; 4]); + d.extend_from_slice(&[4; 2]); + let f = parse_lacing(Lacing::Ebml, &d).unwrap(); + assert_eq!(f.iter().map(|x| x.1).collect::>(), [5, 3, 4, 2]); + assert_eq!(frames(&d, &f), [&[1u8; 5][..], &[2; 3], &[3; 4], &[4; 2]]); + assert!(parse_lacing(Lacing::Ebml, &[1, 0x90]).is_err()); + } + + #[test] + fn lacing_fixed_and_none() { + let d = [2u8, 1, 1, 2, 2, 3, 3]; + let f = parse_lacing(Lacing::FixedSize, &d).unwrap(); + assert_eq!(frames(&d, &f), [&[1u8, 1][..], &[2, 2], &[3, 3]]); + assert!(parse_lacing(Lacing::FixedSize, &[2, 1, 1]).is_err()); + assert_eq!(parse_lacing(Lacing::None, &[9, 9]).unwrap(), [(0, 2)]); + assert_eq!(Lacing::from_flags(0x80 | 0x06), Lacing::Ebml); + assert_eq!(Lacing::from_flags(0x02), Lacing::Xiph); + assert_eq!(Lacing::from_flags(0x04), Lacing::FixedSize); + } +} diff --git a/crates/media/src/matroska/error.rs b/crates/media/src/matroska/error.rs new file mode 100644 index 000000000..e3157a3d1 --- /dev/null +++ b/crates/media/src/matroska/error.rs @@ -0,0 +1,56 @@ +use std::fmt; +use std::io; + +/// Errors produced by the demuxer. +#[derive(Debug)] +pub enum Error { + /// Underlying I/O failure. + Io(io::Error), + /// Structurally invalid data that could not be recovered from. + Invalid(String), + /// Valid but unsupported feature (e.g. zlib-compressed or encrypted tracks when reading data). + Unsupported(String), + /// Not an EBML file, or an EBML file whose DocType is not `matroska`/`webm`. + NotMatroska(String), + /// A track index was out of range. + NoSuchTrack(usize), + /// A sample index was out of range. + NoSuchSample(usize), + /// The file describes more than the demuxer's limits allow (frames, tracks). + TooLarge(&'static str), +} + +impl fmt::Display for Error { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + Error::Io(e) => write!(f, "I/O error: {e}"), + Error::Invalid(s) => write!(f, "invalid data: {s}"), + Error::Unsupported(s) => write!(f, "unsupported: {s}"), + Error::NotMatroska(s) => write!(f, "not a Matroska/WebM file: {s}"), + Error::NoSuchTrack(i) => write!(f, "track index {i} out of range"), + Error::NoSuchSample(i) => write!(f, "sample index {i} out of range"), + Error::TooLarge(s) => write!(f, "size limit exceeded: {s}"), + } + } +} + +impl std::error::Error for Error { + fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { + match self { + Error::Io(e) => Some(e), + _ => None, + } + } +} + +impl From for Error { + fn from(e: io::Error) -> Self { + Error::Io(e) + } +} + +pub type Result = std::result::Result; + +pub(crate) fn invalid(msg: impl Into) -> Result { + Err(Error::Invalid(msg.into())) +} diff --git a/crates/media/src/matroska/ids.rs b/crates/media/src/matroska/ids.rs new file mode 100644 index 000000000..5998c1e2c --- /dev/null +++ b/crates/media/src/matroska/ids.rs @@ -0,0 +1,216 @@ +//! EBML / Matroska element IDs (RFC 8794, RFC 9559). IDs keep their VINT marker bits. +#![allow(dead_code)] + +// EBML header + global elements +pub const EBML: u32 = 0x1A45_DFA3; +pub const EBML_VERSION: u32 = 0x4286; +pub const EBML_READ_VERSION: u32 = 0x42F7; +pub const EBML_MAX_ID_LENGTH: u32 = 0x42F2; +pub const EBML_MAX_SIZE_LENGTH: u32 = 0x42F3; +pub const DOC_TYPE: u32 = 0x4282; +pub const DOC_TYPE_VERSION: u32 = 0x4287; +pub const DOC_TYPE_READ_VERSION: u32 = 0x4285; +pub const CRC32: u32 = 0xBF; +pub const VOID: u32 = 0xEC; + +// Segment and level-1 elements +pub const SEGMENT: u32 = 0x1853_8067; +pub const SEEK_HEAD: u32 = 0x114D_9B74; +pub const INFO: u32 = 0x1549_A966; +pub const TRACKS: u32 = 0x1654_AE6B; +pub const CLUSTER: u32 = 0x1F43_B675; +pub const CUES: u32 = 0x1C53_BB6B; +pub const ATTACHMENTS: u32 = 0x1941_A469; +pub const CHAPTERS: u32 = 0x1043_A770; +pub const TAGS: u32 = 0x1254_C367; + +/// True for IDs that can only appear directly inside a Segment (or are the EBML/Segment headers): +/// used to find the end of unknown-size elements. +pub fn is_top_level(id: u32) -> bool { + matches!(id, EBML | SEGMENT | SEEK_HEAD | INFO | TRACKS | CLUSTER | CUES | ATTACHMENTS | CHAPTERS | TAGS) +} + +// SeekHead +pub const SEEK: u32 = 0x4DBB; +pub const SEEK_ID: u32 = 0x53AB; +pub const SEEK_POSITION: u32 = 0x53AC; + +// Info +pub const SEGMENT_UUID: u32 = 0x73A4; +pub const SEGMENT_FILENAME: u32 = 0x7384; +pub const TIMESTAMP_SCALE: u32 = 0x2A_D7B1; +pub const DURATION: u32 = 0x4489; +pub const DATE_UTC: u32 = 0x4461; +pub const TITLE: u32 = 0x7BA9; +pub const MUXING_APP: u32 = 0x4D80; +pub const WRITING_APP: u32 = 0x5741; + +// Cluster +pub const TIMESTAMP: u32 = 0xE7; +pub const POSITION: u32 = 0xA7; +pub const PREV_SIZE: u32 = 0xAB; +pub const SIMPLE_BLOCK: u32 = 0xA3; +pub const BLOCK_GROUP: u32 = 0xA0; +pub const ENCRYPTED_BLOCK: u32 = 0xAF; +pub const SILENT_TRACKS: u32 = 0x5854; +pub const BLOCK: u32 = 0xA1; +pub const BLOCK_ADDITIONS: u32 = 0x75A1; +pub const BLOCK_MORE: u32 = 0xA6; +pub const BLOCK_ADD_ID: u32 = 0xEE; +pub const BLOCK_ADDITIONAL: u32 = 0xA5; +pub const BLOCK_DURATION: u32 = 0x9B; +pub const REFERENCE_PRIORITY: u32 = 0xFA; +pub const REFERENCE_BLOCK: u32 = 0xFB; +pub const CODEC_STATE: u32 = 0xA4; +pub const DISCARD_PADDING: u32 = 0x75A2; + +pub fn is_cluster_child(id: u32) -> bool { + matches!(id, TIMESTAMP | POSITION | PREV_SIZE | SIMPLE_BLOCK | BLOCK_GROUP | ENCRYPTED_BLOCK | SILENT_TRACKS | CRC32 | VOID) +} + +// Tracks +pub const TRACK_ENTRY: u32 = 0xAE; +pub const TRACK_NUMBER: u32 = 0xD7; +pub const TRACK_UID: u32 = 0x73C5; +pub const TRACK_TYPE: u32 = 0x83; +pub const FLAG_ENABLED: u32 = 0xB9; +pub const FLAG_DEFAULT: u32 = 0x88; +pub const FLAG_FORCED: u32 = 0x55AA; +pub const FLAG_HEARING_IMPAIRED: u32 = 0x55AB; +pub const FLAG_VISUAL_IMPAIRED: u32 = 0x55AC; +pub const FLAG_ORIGINAL: u32 = 0x55AE; +pub const FLAG_COMMENTARY: u32 = 0x55AF; +pub const FLAG_LACING: u32 = 0x9C; +pub const DEFAULT_DURATION: u32 = 0x23_E383; +pub const TRACK_TIMESTAMP_SCALE: u32 = 0x23_314F; +pub const NAME: u32 = 0x536E; +pub const LANGUAGE: u32 = 0x22_B59C; +pub const LANGUAGE_BCP47: u32 = 0x22_B59D; +pub const CODEC_ID: u32 = 0x86; +pub const CODEC_PRIVATE: u32 = 0x63A2; +pub const CODEC_NAME: u32 = 0x25_8688; +pub const CODEC_DELAY: u32 = 0x56AA; +pub const SEEK_PRE_ROLL: u32 = 0x56BB; + +// Video +pub const VIDEO: u32 = 0xE0; +pub const FLAG_INTERLACED: u32 = 0x9A; +pub const FIELD_ORDER: u32 = 0x9D; +pub const STEREO_MODE: u32 = 0x53B8; +pub const ALPHA_MODE: u32 = 0x53C0; +pub const PIXEL_WIDTH: u32 = 0xB0; +pub const PIXEL_HEIGHT: u32 = 0xBA; +pub const PIXEL_CROP_BOTTOM: u32 = 0x54AA; +pub const PIXEL_CROP_TOP: u32 = 0x54BB; +pub const PIXEL_CROP_LEFT: u32 = 0x54CC; +pub const PIXEL_CROP_RIGHT: u32 = 0x54DD; +pub const DISPLAY_WIDTH: u32 = 0x54B0; +pub const DISPLAY_HEIGHT: u32 = 0x54BA; +pub const DISPLAY_UNIT: u32 = 0x54B2; +/// `ColourSpace`; read into [`VideoInfo::color_space`](crate::matroska::VideoInfo::color_space). +pub const COLOUR_SPACE: u32 = 0x2E_B524; +/// `Colour`; read into [`Color`](crate::matroska::Color). +pub const COLOUR: u32 = 0x55B0; +pub const PROJECTION: u32 = 0x7670; +pub const PROJECTION_TYPE: u32 = 0x7671; +pub const PROJECTION_POSE_YAW: u32 = 0x7673; +pub const PROJECTION_POSE_PITCH: u32 = 0x7674; +pub const PROJECTION_POSE_ROLL: u32 = 0x7675; + +// Colour +pub const MATRIX_COEFFICIENTS: u32 = 0x55B1; +pub const BITS_PER_CHANNEL: u32 = 0x55B2; +pub const CHROMA_SUBSAMPLING_HORZ: u32 = 0x55B3; +pub const CHROMA_SUBSAMPLING_VERT: u32 = 0x55B4; +pub const CB_SUBSAMPLING_HORZ: u32 = 0x55B5; +pub const CB_SUBSAMPLING_VERT: u32 = 0x55B6; +pub const CHROMA_SITING_HORZ: u32 = 0x55B7; +pub const CHROMA_SITING_VERT: u32 = 0x55B8; +pub const RANGE: u32 = 0x55B9; +pub const TRANSFER_CHARACTERISTICS: u32 = 0x55BA; +pub const PRIMARIES: u32 = 0x55BB; +pub const MAX_CLL: u32 = 0x55BC; +pub const MAX_FALL: u32 = 0x55BD; +pub const MASTERING_METADATA: u32 = 0x55D0; +pub const PRIMARY_R_X: u32 = 0x55D1; +pub const PRIMARY_R_Y: u32 = 0x55D2; +pub const PRIMARY_G_X: u32 = 0x55D3; +pub const PRIMARY_G_Y: u32 = 0x55D4; +pub const PRIMARY_B_X: u32 = 0x55D5; +pub const PRIMARY_B_Y: u32 = 0x55D6; +pub const WHITE_POINT_X: u32 = 0x55D7; +pub const WHITE_POINT_Y: u32 = 0x55D8; +pub const LUMINANCE_MAX: u32 = 0x55D9; +pub const LUMINANCE_MIN: u32 = 0x55DA; + +// Audio +pub const AUDIO: u32 = 0xE1; +pub const SAMPLING_FREQUENCY: u32 = 0xB5; +pub const OUTPUT_SAMPLING_FREQUENCY: u32 = 0x78B5; +pub const CHANNELS: u32 = 0x9F; +pub const BIT_DEPTH: u32 = 0x6264; + +// ContentEncodings +pub const CONTENT_ENCODINGS: u32 = 0x6D80; +pub const CONTENT_ENCODING: u32 = 0x6240; +pub const CONTENT_ENCODING_ORDER: u32 = 0x5031; +pub const CONTENT_ENCODING_SCOPE: u32 = 0x5032; +pub const CONTENT_ENCODING_TYPE: u32 = 0x5033; +pub const CONTENT_COMPRESSION: u32 = 0x5034; +pub const CONTENT_COMP_ALGO: u32 = 0x4254; +pub const CONTENT_COMP_SETTINGS: u32 = 0x4255; +pub const CONTENT_ENCRYPTION: u32 = 0x5035; + +// Cues +pub const CUE_POINT: u32 = 0xBB; +pub const CUE_TIME: u32 = 0xB3; +pub const CUE_TRACK_POSITIONS: u32 = 0xB7; +pub const CUE_TRACK: u32 = 0xF7; +pub const CUE_CLUSTER_POSITION: u32 = 0xF1; +pub const CUE_RELATIVE_POSITION: u32 = 0xF0; +pub const CUE_DURATION: u32 = 0xB2; +pub const CUE_BLOCK_NUMBER: u32 = 0x5378; + +// Attachments +pub const ATTACHED_FILE: u32 = 0x61A7; +pub const FILE_DESCRIPTION: u32 = 0x467E; +pub const FILE_NAME: u32 = 0x466E; +pub const FILE_MEDIA_TYPE: u32 = 0x4660; +pub const FILE_DATA: u32 = 0x465C; +pub const FILE_UID: u32 = 0x46AE; + +// Chapters +pub const EDITION_ENTRY: u32 = 0x45B9; +pub const EDITION_UID: u32 = 0x45BC; +pub const EDITION_FLAG_HIDDEN: u32 = 0x45BD; +pub const EDITION_FLAG_DEFAULT: u32 = 0x45DB; +pub const EDITION_FLAG_ORDERED: u32 = 0x45DD; +pub const CHAPTER_ATOM: u32 = 0xB6; +pub const CHAPTER_UID: u32 = 0x73C4; +pub const CHAPTER_STRING_UID: u32 = 0x5654; +pub const CHAPTER_TIME_START: u32 = 0x91; +pub const CHAPTER_TIME_END: u32 = 0x92; +pub const CHAPTER_FLAG_HIDDEN: u32 = 0x98; +pub const CHAPTER_FLAG_ENABLED: u32 = 0x4598; +pub const CHAPTER_DISPLAY: u32 = 0x80; +pub const CHAP_STRING: u32 = 0x85; +pub const CHAP_LANGUAGE: u32 = 0x437C; +pub const CHAP_LANGUAGE_BCP47: u32 = 0x437D; +pub const CHAP_COUNTRY: u32 = 0x437E; + +// Tags +pub const TAG: u32 = 0x7373; +pub const TARGETS: u32 = 0x63C0; +pub const TARGET_TYPE_VALUE: u32 = 0x68CA; +pub const TARGET_TYPE: u32 = 0x63CA; +pub const TAG_TRACK_UID: u32 = 0x63C5; +pub const TAG_EDITION_UID: u32 = 0x63C9; +pub const TAG_CHAPTER_UID: u32 = 0x63C4; +pub const TAG_ATTACHMENT_UID: u32 = 0x63C6; +pub const SIMPLE_TAG: u32 = 0x67C8; +pub const TAG_NAME: u32 = 0x45A3; +pub const TAG_LANGUAGE: u32 = 0x447A; +pub const TAG_LANGUAGE_BCP47: u32 = 0x447B; +pub const TAG_DEFAULT: u32 = 0x4484; +pub const TAG_STRING: u32 = 0x4487; +pub const TAG_BINARY: u32 = 0x4485; diff --git a/crates/media/src/matroska/index_limit_tests.rs b/crates/media/src/matroska/index_limit_tests.rs new file mode 100644 index 000000000..059a1388b --- /dev/null +++ b/crates/media/src/matroska/index_limit_tests.rs @@ -0,0 +1,269 @@ +//! Limited indexing ([`OpenOptions::index_limit`]) and [`MkvFile::extend_index`], on files written +//! with [`MkvWriter`] (one Cluster per second, Cues at the end). + +use std::cell::Cell; +use std::io::{Cursor, ErrorKind}; + +use crate::matroska::{ByteSource, Demuxer, MkvFile, MkvWriter, MuxOptions, OpenOptions, TrackKind, TrackSpec, open_with}; + +/// A video track of `frames` 100 ms frames (every fifth a keyframe): ten frames per Cluster. +fn file(frames: i64) -> Vec { + let mut v = TrackSpec::new(TrackKind::Video, "V_MJPEG"); + v.video_size = Some((16, 16)); + v.default_duration_ns = Some(100_000_000); + let mut w = MkvWriter::new(Cursor::new(Vec::new()), vec![v], MuxOptions::default()).expect("writer"); + for k in 0..frames { + w.write_frame(0, k * 100_000_000, k % 5 == 0, &[k as u8; 200], Some(100_000_000)).expect("frame"); + } + w.finish().expect("finish").into_inner() +} + +fn limited(bytes: &[u8], limit: Option) -> MkvFile { + open_with(bytes, &OpenOptions { index_limit: limit, ..OpenOptions::default() }).expect("open") +} + +fn unlimited() -> OpenOptions { + OpenOptions::default() +} + +/// The sample tables, cluster list and cues of two files are equal. +fn assert_same(a: &MkvFile, b: &MkvFile) { + assert_eq!(a.tracks.len(), b.tracks.len()); + for (x, y) in a.tracks.iter().zip(&b.tracks) { + assert_eq!(x.samples, y.samples); + assert_eq!(x.sync, y.sync); + } + assert_eq!(a.clusters, b.clusters); + assert_eq!(a.cues, b.cues); + assert_eq!((a.indexed, a.index_end), (b.indexed, b.index_end)); +} + +#[test] +fn default_options_are_unchanged() { + let bytes = file(45); + let f = open_with(&bytes[..], &OpenOptions::default()).expect("open"); + assert!(f.indexed && f.index_end.is_none()); + assert_eq!(f.clusters.len(), 5); + assert_eq!(f.tracks[0].samples.len(), 45); + assert!(!f.cues.is_empty()); +} + +#[test] +fn limit_stops_before_a_cluster_that_does_not_fit() { + let bytes = file(45); + let full = limited(&bytes, None); + let c = &full.clusters; + // the limit lies in the middle of the third cluster: two are indexed, the third waits + let f = limited(&bytes, Some(c[2].offset + 40)); + assert_eq!(f.clusters, c[..2]); + assert_eq!(f.tracks[0].samples, full.tracks[0].samples[..20]); + assert!(!f.indexed); + assert_eq!(f.index_end, Some(c[2].offset)); + // Info and Tracks are there; the Cues at the end are not read yet + assert_eq!(f.info.duration, full.info.duration); + assert_eq!(f.duration_ns(), full.duration_ns()); + assert!(f.cues.is_empty()); + // a limit exactly at the end of a cluster keeps that cluster + let g = limited(&bytes, Some(c[1].end)); + assert_eq!(g.clusters.len(), 2); + assert_eq!(g.index_end, Some(c[1].end)); +} + +#[test] +fn limit_before_the_first_cluster_still_scans_it() { + let bytes = file(45); + let full = limited(&bytes, None); + for limit in [0, 1, full.first_cluster.expect("cluster") / 2] { + let f = limited(&bytes, Some(limit)); + assert_eq!(f.clusters.len(), 1, "limit {limit}"); + assert_eq!(f.tracks[0].samples.len(), 10); + assert_eq!(f.index_end, Some(full.clusters[0].end)); + assert!(!f.indexed); + } +} + +#[test] +fn limit_past_the_end_is_a_full_index() { + let bytes = file(45); + let full = limited(&bytes, None); + for limit in [bytes.len() as u64, bytes.len() as u64 + 1, u64::MAX] { + assert_same(&limited(&bytes, Some(limit)), &full); + } +} + +#[test] +fn limit_without_an_index_is_ignored() { + let bytes = file(45); + let f = open_with(&bytes[..], &OpenOptions { index: false, verify_crc: false, index_limit: Some(0) }).expect("open"); + assert!(!f.indexed && f.index_end.is_none() && f.clusters.is_empty()); + assert!(!f.cues.is_empty(), "the SeekHead still leads to the Cues"); +} + +#[test] +fn extending_in_steps_equals_a_full_open() { + let bytes = file(45); + let full = limited(&bytes, None); + let mut f = limited(&bytes, Some(0)); + let mut seen = vec![f.clusters.len()]; + for c in &full.clusters { + f.extend_index(&bytes[..], &OpenOptions { index_limit: Some(c.end), ..unlimited() }).expect("extend"); + seen.push(f.clusters.len()); + } + assert_eq!(seen, [1, 1, 2, 3, 4, 5]); + // the Cues after the last cluster wait for the rest of the index + assert!(!f.indexed && f.index_end.is_some() && f.cues.is_empty()); + f.extend_index(&bytes[..], &unlimited()).expect("complete"); + assert_same(&f, &full); +} + +#[test] +fn extending_twice_with_the_same_limit_changes_nothing() { + let bytes = file(45); + let mut f = limited(&bytes, Some(0)); + let limit = f.clusters[0].end + 5_000; + let opts = OpenOptions { index_limit: Some(limit), ..unlimited() }; + f.extend_index(&bytes[..], &opts).expect("extend"); + let (samples, end) = (f.tracks[0].samples.clone(), f.index_end); + f.extend_index(&bytes[..], &opts).expect("extend again"); + assert_eq!((f.tracks[0].samples.clone(), f.index_end), (samples, end)); + // a lower limit than what is indexed is a no-op too + f.extend_index(&bytes[..], &OpenOptions { index_limit: Some(0), ..unlimited() }).expect("extend lower"); + assert_eq!(f.index_end, end); + // to the end, then once more on a complete index + f.extend_index(&bytes[..], &unlimited()).expect("complete"); + assert!(f.indexed); + f.extend_index(&bytes[..], &unlimited()).expect("complete again"); + assert_same(&f, &limited(&bytes, None)); +} + +/// A source that has loaded only a prefix: reads beyond it fail like the web build's pending reads. +struct Loaded<'a> { + data: &'a [u8], + loaded: Cell, +} + +impl ByteSource for Loaded<'_> { + fn len(&self) -> u64 { + self.data.len() as u64 + } + fn read_at(&self, offset: u64, buf: &mut [u8]) -> std::io::Result<()> { + if offset + buf.len() as u64 > self.loaded.get() { + return Err(std::io::Error::new(ErrorKind::WouldBlock, "not loaded yet")); + } + self.data.read_at(offset, buf) + } +} + +#[test] +fn a_growing_prefix_indexes_without_reading_ahead() { + let bytes = file(45); + let full = limited(&bytes, None); + let src = Loaded { data: &bytes, loaded: Cell::new(0) }; + // nothing loaded: the open fails with WouldBlock instead of panicking + let opts = |limit: u64| OpenOptions { index_limit: Some(limit), ..unlimited() }; + let err = open_with(&src, &opts(0)).expect_err("nothing loaded"); + assert!(err.to_string().contains("not loaded"), "{err}"); + // the head up to the end of the first cluster is enough to open, however much more is asked for + src.loaded.set(full.clusters[0].end); + let mut f = open_with(&src, &opts(src.loaded.get())).expect("first cluster loaded"); + assert_eq!(f.clusters.len(), 1); + // each chunk that arrives indexes the clusters it holds completely, and nothing past them + for (n, c) in full.clusters.iter().enumerate().skip(1) { + src.loaded.set(c.end - 1); + f.extend_index(&src, &opts(src.loaded.get())).expect("extend"); + assert_eq!(f.clusters.len(), n, "a cluster missing its last byte waits"); + src.loaded.set(c.end); + f.extend_index(&src, &opts(src.loaded.get())).expect("extend"); + assert_eq!(f.clusters.len(), n + 1); + } + // the tail (Cues) arrives: the index completes + src.loaded.set(bytes.len() as u64); + f.extend_index(&src, &unlimited()).expect("complete"); + assert_same(&f, &full); +} + +/// A source whose read number `fail_at` fails once with `WouldBlock`, whatever it asks for. +struct Flaky<'a> { + data: &'a [u8], + calls: Cell, + fail_at: usize, +} + +impl ByteSource for Flaky<'_> { + fn len(&self) -> u64 { + self.data.len() as u64 + } + fn read_at(&self, offset: u64, buf: &mut [u8]) -> std::io::Result<()> { + self.calls.set(self.calls.get() + 1); + if self.calls.get() == self.fail_at { + return Err(std::io::Error::new(ErrorKind::WouldBlock, "not loaded yet")); + } + self.data.read_at(offset, buf) + } +} + +#[test] +fn a_failed_extension_resumes_without_duplicates() { + // Tags between the clusters and Cues after them make the elements read twice visible + let bytes = file(45); + let full = limited(&bytes, None); + let mut failed = 0; + for fail_at in 1..40 { + let mut f = limited(&bytes, Some(0)); + let src = Flaky { data: &bytes, calls: Cell::new(0), fail_at }; + // a read that fails anywhere in the scan leaves the file consistent: the retry finishes it + if f.extend_index(&src, &unlimited()).is_err() { + failed += 1; + assert!(f.index_end.is_some() && !f.indexed, "fail_at {fail_at}"); + assert_eq!(f.clusters.len(), f.tracks[0].samples.len() / 10, "whole clusters only, fail_at {fail_at}"); + f.extend_index(&bytes[..], &unlimited()).expect("resume"); + } + assert_same(&f, &full); + } + assert!(failed > 0, "the failing read was reached"); +} + +#[test] +fn truncated_files_never_panic() { + let bytes = file(25); + for len in 0..bytes.len() { + for limit in [Some(0), Some(len as u64 / 2), None] { + let cut = &bytes[..len]; + let Ok(mut f) = open_with(cut, &OpenOptions { index_limit: limit, ..unlimited() }) else { continue }; + let _ = f.extend_index(cut, &unlimited()); + let _ = f.extend_index(cut, &OpenOptions { index_limit: Some(1), ..unlimited() }); + assert!(f.index_end.is_none() || !f.indexed); + } + } +} + +#[test] +fn demuxer_completes_a_limited_index_and_seeks() { + let bytes = file(45); + let full = limited(&bytes, None); + let mut d = Demuxer::with_options(&bytes[..], OpenOptions { index_limit: Some(0), ..unlimited() }).expect("open"); + assert_eq!(d.file().clusters.len(), 1); + // packets stream from the first Cluster on, whatever the index covers + assert_eq!(d.next_packet().expect("packet").expect("some").pts, 0); + let keys = d.keyframe_index(0).expect("keyframes"); + assert!(d.file().indexed); + assert_eq!(keys.len(), full.tracks[0].sync.len()); + let at = d.seek(0, 3_500_000_000).expect("seek"); + assert_eq!(at.pts_ns, 3_500_000_000); +} + +#[test] +fn a_tiny_last_block_needs_no_bytes_past_its_cluster() { + let mut v = TrackSpec::new(TrackKind::Video, "V_MJPEG"); + v.video_size = Some((16, 16)); + let mut w = MkvWriter::new(Cursor::new(Vec::new()), vec![v], MuxOptions::default()).expect("writer"); + for k in 0..30 { + w.write_frame(0, k * 100_000_000, true, &[k as u8], Some(100_000_000)).expect("frame"); + } + let bytes = w.finish().expect("finish").into_inner(); + let full = limited(&bytes, None); + // a 7-byte block ends each cluster: its header read must not reach into the next cluster + let src = Loaded { data: &bytes, loaded: Cell::new(full.clusters[0].end) }; + let f = open_with(&src, &OpenOptions { index_limit: Some(src.loaded.get()), ..unlimited() }).expect("open"); + assert_eq!(f.clusters.len(), 1); +} diff --git a/crates/media/src/matroska/meta.rs b/crates/media/src/matroska/meta.rs new file mode 100644 index 000000000..2d19ea0b0 --- /dev/null +++ b/crates/media/src/matroska/meta.rs @@ -0,0 +1,682 @@ +//! Segment-level metadata: Info, SeekHead, Cues, Chapters, Tags, Attachments — types and parsers +//! for their in-memory element data. + +use crate::matroska::codec::map_codec; +use crate::matroska::ebml::{Children, float, int, string, uint}; +use crate::matroska::ids::{ + ALPHA_MODE, AUDIO, BIT_DEPTH, BITS_PER_CHANNEL, CB_SUBSAMPLING_HORZ, CB_SUBSAMPLING_VERT, CHANNELS, CHAP_COUNTRY, CHAP_LANGUAGE, + CHAP_LANGUAGE_BCP47, CHAP_STRING, CHAPTER_ATOM, CHAPTER_DISPLAY, CHAPTER_FLAG_ENABLED, CHAPTER_FLAG_HIDDEN, CHAPTER_STRING_UID, CHAPTER_TIME_END, + CHAPTER_TIME_START, CHAPTER_UID, CHROMA_SITING_HORZ, CHROMA_SITING_VERT, CHROMA_SUBSAMPLING_HORZ, CHROMA_SUBSAMPLING_VERT, CODEC_DELAY, CODEC_ID, + CODEC_NAME, CODEC_PRIVATE, COLOUR, COLOUR_SPACE, CONTENT_COMP_ALGO, CONTENT_COMP_SETTINGS, CONTENT_COMPRESSION, CONTENT_ENCODING, + CONTENT_ENCODING_ORDER, CONTENT_ENCODING_SCOPE, CONTENT_ENCODING_TYPE, CONTENT_ENCODINGS, CUE_BLOCK_NUMBER, CUE_CLUSTER_POSITION, CUE_DURATION, + CUE_POINT, CUE_RELATIVE_POSITION, CUE_TIME, CUE_TRACK, CUE_TRACK_POSITIONS, DATE_UTC, DEFAULT_DURATION, DISPLAY_HEIGHT, DISPLAY_UNIT, + DISPLAY_WIDTH, DURATION, EDITION_ENTRY, EDITION_FLAG_DEFAULT, EDITION_FLAG_HIDDEN, EDITION_FLAG_ORDERED, EDITION_UID, FIELD_ORDER, FLAG_DEFAULT, + FLAG_ENABLED, FLAG_FORCED, FLAG_HEARING_IMPAIRED, FLAG_INTERLACED, FLAG_LACING, LANGUAGE, LANGUAGE_BCP47, LUMINANCE_MAX, LUMINANCE_MIN, + MASTERING_METADATA, MATRIX_COEFFICIENTS, MAX_CLL, MAX_FALL, MUXING_APP, NAME, OUTPUT_SAMPLING_FREQUENCY, PIXEL_CROP_BOTTOM, PIXEL_CROP_LEFT, + PIXEL_CROP_RIGHT, PIXEL_CROP_TOP, PIXEL_HEIGHT, PIXEL_WIDTH, PRIMARIES, PRIMARY_B_X, PRIMARY_B_Y, PRIMARY_G_X, PRIMARY_G_Y, PRIMARY_R_X, + PRIMARY_R_Y, PROJECTION, PROJECTION_POSE_PITCH, PROJECTION_POSE_ROLL, PROJECTION_POSE_YAW, PROJECTION_TYPE, RANGE, SAMPLING_FREQUENCY, SEEK, + SEEK_ID, SEEK_POSITION, SEEK_PRE_ROLL, SEGMENT_UUID, SIMPLE_TAG, STEREO_MODE, TAG, TAG_ATTACHMENT_UID, TAG_BINARY, TAG_CHAPTER_UID, TAG_DEFAULT, + TAG_EDITION_UID, TAG_LANGUAGE, TAG_NAME, TAG_STRING, TAG_TRACK_UID, TARGET_TYPE, TARGET_TYPE_VALUE, TARGETS, TIMESTAMP_SCALE, TITLE, TRACK_ENTRY, + TRACK_NUMBER, TRACK_TYPE, TRACK_UID, TRANSFER_CHARACTERISTICS, VIDEO, WHITE_POINT_X, WHITE_POINT_Y, WRITING_APP, +}; +use crate::matroska::track::{AudioInfo, Color, ContentEncoding, MasteringMetadata, Projection, Track, TrackKind, VideoInfo, gcd}; + +// A malformed Matroska file may contain arbitrarily deep ChapterAtom and SimpleTag chains. +const MAX_META_DEPTH: usize = 64; +/// Longest header-stripping prefix accepted. It is copied in front of every frame, laced +/// zero-length frames included, so its length multiplies what a small file can make a reader +/// produce. Real files strip a few bytes of codec header; a longer one is treated as an +/// unsupported compression and its frames are not reconstructed. +const MAX_STRIPPED_HEADER: usize = 256; +/// Most `ContentEncoding` entries a track may list. A muxer writes one or two (compression, +/// encryption); readers check the whole chain for every frame they return, so a longer chain +/// would multiply that work by the frame count. A track with more is treated as having an +/// unsupported compression, and its frames are returned as stored. +const MAX_CONTENT_ENCODINGS: usize = 16; +/// Largest accepted `TimestampScale` (about 4.3 s per tick). It keeps tick to nanosecond +/// arithmetic on 64-bit timestamps within `i128`. +const MAX_TIMESTAMP_SCALE: u64 = 1 << 32; + +/// `Info` element. +#[derive(Clone, Debug, PartialEq)] +pub struct SegmentInfo { + /// Nanoseconds per timestamp tick (default 1 000 000 = 1 ms). A file's value above 2^32 is + /// ignored. + pub timestamp_scale: u64, + /// `Duration` in timestamp ticks (float), if present. + pub duration: Option, + pub title: Option, + pub muxing_app: String, + pub writing_app: String, + /// `DateUTC`: nanoseconds since 2001-01-01T00:00:00 UTC. + pub date_utc: Option, + pub segment_uuid: Option<[u8; 16]>, +} + +impl Default for SegmentInfo { + fn default() -> Self { + Self { + timestamp_scale: 1_000_000, + duration: None, + title: None, + muxing_app: String::new(), + writing_app: String::new(), + date_utc: None, + segment_uuid: None, + } + } +} + +/// One `SeekHead` entry: level-1 element ID and its position relative to the Segment data start. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct SeekEntry { + pub id: u32, + pub position: u64, +} + +/// One `CueTrackPositions` of a `CuePoint`. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct CuePosition { + pub track: u64, + /// Cluster position relative to the Segment data start. + pub cluster_position: u64, + /// Block position relative to the Cluster data start. + pub relative_position: Option, + pub block_number: Option, + pub duration: Option, +} + +/// One `CuePoint`. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct CuePoint { + /// In timestamp ticks. + pub time: u64, + pub positions: Vec, +} + +/// A cluster found while scanning. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct ClusterInfo { + /// Absolute offset of the Cluster element header. + pub offset: u64, + /// Absolute offset of the first child. + pub data_start: u64, + /// Absolute end offset (for unknown-size clusters, where the next top-level element starts). + pub end: u64, + /// Cluster `Timestamp` in ticks. + pub timestamp: u64, +} + +/// One `ChapterDisplay`. +#[derive(Clone, Debug, Default, PartialEq)] +pub struct ChapterDisplay { + pub string: String, + pub languages: Vec, + pub languages_bcp47: Vec, + pub countries: Vec, +} + +/// `ChapterAtom` (possibly nested). +#[derive(Clone, Debug, PartialEq)] +pub struct Chapter { + pub uid: u64, + pub string_uid: Option, + pub start_ns: u64, + pub end_ns: Option, + pub hidden: bool, + pub enabled: bool, + pub displays: Vec, + pub children: Vec, +} + +impl Chapter { + /// First display string, if any. + pub fn title(&self) -> Option<&str> { + self.displays.first().map(|d| d.string.as_str()) + } +} + +/// `EditionEntry`. +#[derive(Clone, Debug, Default, PartialEq)] +pub struct Edition { + pub uid: Option, + pub hidden: bool, + pub default: bool, + pub ordered: bool, + pub chapters: Vec, +} + +/// `Targets` of a `Tag`. Empty UID lists mean "the whole segment". +#[derive(Clone, Debug, PartialEq)] +pub struct TagTargets { + pub type_value: u64, + pub type_name: Option, + pub track_uids: Vec, + pub edition_uids: Vec, + pub chapter_uids: Vec, + pub attachment_uids: Vec, +} + +impl Default for TagTargets { + fn default() -> Self { + Self { + type_value: 50, + type_name: None, + track_uids: Vec::new(), + edition_uids: Vec::new(), + chapter_uids: Vec::new(), + attachment_uids: Vec::new(), + } + } +} + +/// `SimpleTag` (possibly nested). +#[derive(Clone, Debug, PartialEq)] +pub struct SimpleTag { + pub name: String, + pub language: String, + pub default: bool, + pub string: Option, + pub binary: Option>, + pub children: Vec, +} + +/// `Tag`. +#[derive(Clone, Debug, Default, PartialEq)] +pub struct Tag { + pub targets: TagTargets, + pub simple: Vec, +} + +/// `AttachedFile` (listed only; the payload is located by `data_offset`/`data_size`). +#[derive(Clone, Debug, Default, PartialEq)] +pub struct Attachment { + pub uid: u64, + pub name: String, + pub media_type: String, + pub description: Option, + pub data_offset: u64, + pub data_size: u64, +} + +pub(crate) fn parse_info(d: &[u8]) -> SegmentInfo { + let mut info = SegmentInfo::default(); + for e in Children::new(d) { + match e.id { + TIMESTAMP_SCALE => { + let v = uint(e.data); + if v > 0 && v <= MAX_TIMESTAMP_SCALE { + info.timestamp_scale = v; + } + } + DURATION => info.duration = Some(float(e.data)).filter(|v| v.is_finite() && *v >= 0.0), + TITLE => info.title = Some(string(e.data)), + MUXING_APP => info.muxing_app = string(e.data), + WRITING_APP => info.writing_app = string(e.data), + DATE_UTC => info.date_utc = Some(int(e.data)), + SEGMENT_UUID => info.segment_uuid = e.data.try_into().ok(), + _ => {} + } + } + info +} + +pub(crate) fn parse_seekhead(d: &[u8]) -> Vec { + let mut out = Vec::new(); + for s in Children::new(d).filter(|e| e.id == SEEK) { + let (mut id, mut pos) = (None, None); + for e in Children::new(s.data) { + match e.id { + SEEK_ID => id = Some(uint(e.data) as u32), + SEEK_POSITION => pos = Some(uint(e.data)), + _ => {} + } + } + if let (Some(id), Some(position)) = (id, pos) { + out.push(SeekEntry { id, position }); + } + } + out +} + +pub(crate) fn parse_cues(d: &[u8], out: &mut Vec) { + for cp in Children::new(d).filter(|e| e.id == CUE_POINT) { + let mut time = None; + let mut positions = Vec::new(); + for e in Children::new(cp.data) { + match e.id { + CUE_TIME => time = Some(uint(e.data)), + CUE_TRACK_POSITIONS => { + let mut p = CuePosition { track: 0, cluster_position: u64::MAX, relative_position: None, block_number: None, duration: None }; + for c in Children::new(e.data) { + match c.id { + CUE_TRACK => p.track = uint(c.data), + CUE_CLUSTER_POSITION => p.cluster_position = uint(c.data), + CUE_RELATIVE_POSITION => p.relative_position = Some(uint(c.data)), + CUE_BLOCK_NUMBER => p.block_number = Some(uint(c.data)), + CUE_DURATION => p.duration = Some(uint(c.data)), + _ => {} + } + } + if p.track != 0 && p.cluster_position != u64::MAX { + positions.push(p); + } + } + _ => {} + } + } + if let Some(time) = time + && !positions.is_empty() + { + out.push(CuePoint { time, positions }); + } + } +} + +fn parse_chapter(d: &[u8], depth: usize) -> Chapter { + let mut c = + Chapter { uid: 0, string_uid: None, start_ns: 0, end_ns: None, hidden: false, enabled: true, displays: Vec::new(), children: Vec::new() }; + for e in Children::new(d) { + match e.id { + CHAPTER_UID => c.uid = uint(e.data), + CHAPTER_STRING_UID => c.string_uid = Some(string(e.data)), + CHAPTER_TIME_START => c.start_ns = uint(e.data), + CHAPTER_TIME_END => c.end_ns = Some(uint(e.data)), + CHAPTER_FLAG_HIDDEN => c.hidden = uint(e.data) != 0, + CHAPTER_FLAG_ENABLED => c.enabled = uint(e.data) != 0, + CHAPTER_DISPLAY => { + let mut disp = ChapterDisplay::default(); + for x in Children::new(e.data) { + match x.id { + CHAP_STRING => disp.string = string(x.data), + CHAP_LANGUAGE => disp.languages.push(string(x.data)), + CHAP_LANGUAGE_BCP47 => disp.languages_bcp47.push(string(x.data)), + CHAP_COUNTRY => disp.countries.push(string(x.data)), + _ => {} + } + } + if disp.languages.is_empty() { + disp.languages.push("eng".into()); + } + c.displays.push(disp); + } + CHAPTER_ATOM if depth < MAX_META_DEPTH => c.children.push(parse_chapter(e.data, depth + 1)), + _ => {} + } + } + c +} + +pub(crate) fn parse_chapters(d: &[u8], out: &mut Vec) { + for ed in Children::new(d).filter(|e| e.id == EDITION_ENTRY) { + let mut edition = Edition::default(); + for e in Children::new(ed.data) { + match e.id { + EDITION_UID => edition.uid = Some(uint(e.data)), + EDITION_FLAG_HIDDEN => edition.hidden = uint(e.data) != 0, + EDITION_FLAG_DEFAULT => edition.default = uint(e.data) != 0, + EDITION_FLAG_ORDERED => edition.ordered = uint(e.data) != 0, + CHAPTER_ATOM => edition.chapters.push(parse_chapter(e.data, 0)), + _ => {} + } + } + out.push(edition); + } +} + +fn parse_simple_tag(d: &[u8], depth: usize) -> SimpleTag { + let mut t = SimpleTag { name: String::new(), language: "und".into(), default: true, string: None, binary: None, children: Vec::new() }; + for e in Children::new(d) { + match e.id { + TAG_NAME => t.name = string(e.data), + TAG_LANGUAGE => t.language = string(e.data), + TAG_DEFAULT => t.default = uint(e.data) != 0, + TAG_STRING => t.string = Some(string(e.data)), + TAG_BINARY => t.binary = Some(e.data.to_vec()), + SIMPLE_TAG if depth < MAX_META_DEPTH => t.children.push(parse_simple_tag(e.data, depth + 1)), + _ => {} + } + } + t +} + +pub(crate) fn parse_tags(d: &[u8], out: &mut Vec) { + for tg in Children::new(d).filter(|e| e.id == TAG) { + let mut tag = Tag::default(); + for e in Children::new(tg.data) { + match e.id { + TARGETS => { + for x in Children::new(e.data) { + match x.id { + TARGET_TYPE_VALUE => tag.targets.type_value = uint(x.data), + TARGET_TYPE => tag.targets.type_name = Some(string(x.data)), + TAG_TRACK_UID => tag.targets.track_uids.push(uint(x.data)), + TAG_EDITION_UID => tag.targets.edition_uids.push(uint(x.data)), + TAG_CHAPTER_UID => tag.targets.chapter_uids.push(uint(x.data)), + TAG_ATTACHMENT_UID => tag.targets.attachment_uids.push(uint(x.data)), + _ => {} + } + } + } + SIMPLE_TAG => tag.simple.push(parse_simple_tag(e.data, 0)), + _ => {} + } + } + out.push(tag); + } +} + +fn parse_color(d: &[u8]) -> Color { + let mut c = Color::default(); + for e in Children::new(d) { + let v = || Some(uint(e.data)); + match e.id { + MATRIX_COEFFICIENTS => c.matrix_coefficients = v(), + BITS_PER_CHANNEL => c.bits_per_channel = v(), + CHROMA_SUBSAMPLING_HORZ => c.chroma_subsampling_horz = v(), + CHROMA_SUBSAMPLING_VERT => c.chroma_subsampling_vert = v(), + CB_SUBSAMPLING_HORZ => c.cb_subsampling_horz = v(), + CB_SUBSAMPLING_VERT => c.cb_subsampling_vert = v(), + CHROMA_SITING_HORZ => c.chroma_siting_horz = v(), + CHROMA_SITING_VERT => c.chroma_siting_vert = v(), + RANGE => c.range = v(), + TRANSFER_CHARACTERISTICS => c.transfer_characteristics = v(), + PRIMARIES => c.primaries = v(), + MAX_CLL => c.max_cll = v(), + MAX_FALL => c.max_fall = v(), + MASTERING_METADATA => { + let mut m = MasteringMetadata::default(); + for x in Children::new(e.data) { + let f = float(x.data); + match x.id { + PRIMARY_R_X => m.primaries[0].0 = f, + PRIMARY_R_Y => m.primaries[0].1 = f, + PRIMARY_G_X => m.primaries[1].0 = f, + PRIMARY_G_Y => m.primaries[1].1 = f, + PRIMARY_B_X => m.primaries[2].0 = f, + PRIMARY_B_Y => m.primaries[2].1 = f, + WHITE_POINT_X => m.white_point.0 = f, + WHITE_POINT_Y => m.white_point.1 = f, + LUMINANCE_MAX => m.luminance_max = f, + LUMINANCE_MIN => m.luminance_min = f, + _ => {} + } + } + c.mastering = Some(m); + } + _ => {} + } + } + c +} + +fn parse_video(d: &[u8]) -> VideoInfo { + let mut v = VideoInfo::default(); + for e in Children::new(d) { + let u = uint(e.data); + match e.id { + PIXEL_WIDTH => v.pixel_width = u as u32, + PIXEL_HEIGHT => v.pixel_height = u as u32, + DISPLAY_WIDTH => v.display_width = Some(u as u32), + DISPLAY_HEIGHT => v.display_height = Some(u as u32), + DISPLAY_UNIT => v.display_unit = u, + PIXEL_CROP_TOP => v.crop.0 = u as u32, + PIXEL_CROP_BOTTOM => v.crop.1 = u as u32, + PIXEL_CROP_LEFT => v.crop.2 = u as u32, + PIXEL_CROP_RIGHT => v.crop.3 = u as u32, + FLAG_INTERLACED => v.flag_interlaced = u, + FIELD_ORDER => v.field_order = Some(u), + STEREO_MODE => v.stereo_mode = Some(u), + ALPHA_MODE => v.alpha_mode = u, + COLOUR_SPACE => v.color_space = e.data.try_into().ok(), + COLOUR => v.color = Some(parse_color(e.data)), + PROJECTION => { + let mut p = Projection::default(); + for x in Children::new(e.data) { + match x.id { + PROJECTION_TYPE => p.projection_type = uint(x.data), + PROJECTION_POSE_YAW => p.yaw = float(x.data), + PROJECTION_POSE_PITCH => p.pitch = float(x.data), + PROJECTION_POSE_ROLL => p.roll = float(x.data), + _ => {} + } + } + v.projection = Some(p); + } + _ => {} + } + } + v +} + +fn parse_audio(d: &[u8]) -> AudioInfo { + let mut a = AudioInfo::default(); + for e in Children::new(d) { + match e.id { + SAMPLING_FREQUENCY => a.sampling_frequency = float(e.data), + OUTPUT_SAMPLING_FREQUENCY => a.output_sampling_frequency = Some(float(e.data)), + CHANNELS => a.channels = uint(e.data), + BIT_DEPTH => a.bit_depth = Some(uint(e.data)), + _ => {} + } + } + a +} + +fn parse_encodings(d: &[u8]) -> Vec { + if Children::new(d).filter(|e| e.id == CONTENT_ENCODING).nth(MAX_CONTENT_ENCODINGS).is_some() { + return vec![ContentEncoding::Compression { algo: u64::MAX, settings: Vec::new(), scope: 1 }]; + } + let mut list: Vec<(u64, ContentEncoding)> = Vec::new(); + for ce in Children::new(d).filter(|e| e.id == CONTENT_ENCODING) { + let (mut order, mut scope, mut ty) = (0u64, 1u64, 0u64); + let mut comp: Option<(u64, Vec)> = None; + for e in Children::new(ce.data) { + match e.id { + CONTENT_ENCODING_ORDER => order = uint(e.data), + CONTENT_ENCODING_SCOPE => scope = uint(e.data), + CONTENT_ENCODING_TYPE => ty = uint(e.data), + CONTENT_COMPRESSION => { + let (mut algo, mut settings) = (0u64, Vec::new()); + for x in Children::new(e.data) { + match x.id { + CONTENT_COMP_ALGO => algo = uint(x.data), + CONTENT_COMP_SETTINGS => settings = x.data.to_vec(), + _ => {} + } + } + comp = Some((algo, settings)); + } + _ => {} + } + } + let enc = if ty == 1 { + ContentEncoding::Encryption { scope } + } else { + let (algo, settings) = comp.unwrap_or((0, Vec::new())); + if algo == 3 && settings.len() <= MAX_STRIPPED_HEADER { + ContentEncoding::HeaderStripping { bytes: settings, scope } + } else { + ContentEncoding::Compression { algo, settings, scope } + } + }; + list.push((order, enc)); + } + // highest order is applied last on muxing → first to undo; keep decode order + list.sort_by_key(|e| std::cmp::Reverse(e.0)); + list.into_iter().map(|e| e.1).collect() +} + +pub(crate) fn parse_tracks(d: &[u8], timestamp_scale: u64) -> Vec { + let g = gcd(timestamp_scale, 1_000_000_000); + let timebase = (timestamp_scale / g, 1_000_000_000 / g); + let mut out = Vec::new(); + for te in Children::new(d).filter(|e| e.id == TRACK_ENTRY) { + let mut t = Track { + number: 0, + uid: 0, + kind: TrackKind::Other(0), + enabled: true, + default: true, + forced: false, + hearing_impaired: false, + lacing: true, + default_duration_ns: None, + name: String::new(), + language: "eng".into(), + language_bcp47: None, + codec_id: String::new(), + codec_private: Vec::new(), + codec_name: String::new(), + codec: crate::matroska::Codec::Other(String::new()), + codec_delay_ns: 0, + seek_pre_roll_ns: 0, + video: None, + audio: None, + encodings: Vec::new(), + timebase, + samples: Vec::new(), + sync: Vec::new(), + }; + for e in Children::new(te.data) { + match e.id { + TRACK_NUMBER => t.number = uint(e.data), + TRACK_UID => t.uid = uint(e.data), + TRACK_TYPE => t.kind = TrackKind::from_type(uint(e.data)), + FLAG_ENABLED => t.enabled = uint(e.data) != 0, + FLAG_DEFAULT => t.default = uint(e.data) != 0, + FLAG_FORCED => t.forced = uint(e.data) != 0, + FLAG_HEARING_IMPAIRED => t.hearing_impaired = uint(e.data) != 0, + FLAG_LACING => t.lacing = uint(e.data) != 0, + DEFAULT_DURATION => t.default_duration_ns = Some(uint(e.data)).filter(|&v| v > 0), + NAME => t.name = string(e.data), + LANGUAGE => t.language = string(e.data), + LANGUAGE_BCP47 => t.language_bcp47 = Some(string(e.data)), + CODEC_ID => t.codec_id = string(e.data), + CODEC_PRIVATE => t.codec_private = e.data.to_vec(), + CODEC_NAME => t.codec_name = string(e.data), + CODEC_DELAY => t.codec_delay_ns = uint(e.data), + SEEK_PRE_ROLL => t.seek_pre_roll_ns = uint(e.data), + VIDEO => t.video = Some(parse_video(e.data)), + AUDIO => t.audio = Some(parse_audio(e.data)), + CONTENT_ENCODINGS => t.encodings = parse_encodings(e.data), + _ => {} + } + } + if t.number == 0 { + continue; + } + if t.kind == TrackKind::Audio && t.audio.is_none() { + t.audio = Some(AudioInfo::default()); + } + // CodecPrivate may itself be header-stripped (scope bit 2 = private data) + // Prepends in list order, built in one pass: a hostile entry can list millions. + let mut prefix = Vec::new(); + for enc in t.encodings.iter().rev() { + if let ContentEncoding::HeaderStripping { bytes, scope } = enc + && scope & 2 != 0 + { + prefix.extend_from_slice(bytes); + } + } + if !prefix.is_empty() { + prefix.extend_from_slice(&t.codec_private); + t.codec_private = prefix; + } + t.codec = map_codec(&t.codec_id, &t.codec_private, t.audio.as_ref()); + out.push(t); + } + out +} + +#[cfg(test)] +mod metadata_depth_tests { + use super::*; + use crate::matroska::mux::{el, el_uint}; + + fn header_stripping(bytes: &[u8]) -> Vec { + let mut comp = Vec::new(); + el_uint(&mut comp, CONTENT_COMP_ALGO, 3); + el(&mut comp, CONTENT_COMP_SETTINGS, bytes); + let mut enc = Vec::new(); + el(&mut enc, CONTENT_COMPRESSION, &comp); + let mut encs = Vec::new(); + el(&mut encs, CONTENT_ENCODING, &enc); + parse_encodings(&encs) + } + + #[test] + fn a_long_stripped_header_is_not_put_in_front_of_frames() { + let kept = header_stripping(&[7; MAX_STRIPPED_HEADER]); + assert!(matches!(&kept[..], [ContentEncoding::HeaderStripping { bytes, .. }] if bytes.len() == MAX_STRIPPED_HEADER)); + let refused = header_stripping(&[7; MAX_STRIPPED_HEADER + 1]); + assert!(matches!(&refused[..], [ContentEncoding::Compression { algo: 3, .. }]), "{refused:?}"); + } + + fn track_with_private(private: &[u8], strips: &[(&[u8], u64)]) -> Track { + let mut encs = Vec::new(); + for &(bytes, scope) in strips { + let mut comp = Vec::new(); + el_uint(&mut comp, CONTENT_COMP_ALGO, 3); + el(&mut comp, CONTENT_COMP_SETTINGS, bytes); + let mut enc = Vec::new(); + el_uint(&mut enc, CONTENT_ENCODING_SCOPE, scope); + el(&mut enc, CONTENT_COMPRESSION, &comp); + el(&mut encs, CONTENT_ENCODING, &enc); + } + let mut te = Vec::new(); + el_uint(&mut te, TRACK_NUMBER, 1); + el(&mut te, CODEC_ID, b"V_TEST"); + el(&mut te, CODEC_PRIVATE, private); + el(&mut te, CONTENT_ENCODINGS, &encs); + let mut tracks = Vec::new(); + el(&mut tracks, TRACK_ENTRY, &te); + let mut parsed = parse_tracks(&tracks, 1_000_000); + assert_eq!(parsed.len(), 1); + parsed.remove(0) + } + + #[test] + fn a_long_encoding_chain_is_not_rechecked_for_every_frame() { + let strip: (&[u8], u64) = (b"", 2); + let most = track_with_private(b"private", &[strip; MAX_CONTENT_ENCODINGS]); + assert_eq!(most.encodings.len(), MAX_CONTENT_ENCODINGS); + assert!(most.frames_readable()); + let many = track_with_private(b"private", &vec![strip; 10_000]); + assert!(matches!(&many.encodings[..], [ContentEncoding::Compression { scope: 1, .. }]), "{:?}", many.encodings.len()); + assert!(!many.frames_readable()); + assert_eq!(many.codec_private, b"private"); + } + + #[test] + fn codec_private_stripped_headers_are_restored_in_reverse_order() { + let strips: [(&[u8], u64); 4] = [(b"first", 2), (b"", 2), (b"second", 2), (b"frame", 1)]; + assert_eq!(track_with_private(b"private", &strips).codec_private, b"secondfirstprivate"); + assert_eq!(track_with_private(b"private", &[(b"frame", 1)]).codec_private, b"private"); + } + + #[test] + fn deeply_nested_chapters_stop_at_depth_limit() { + // Unknown-size elements make every pair the sole child of the previous ChapterAtom. + let data = [0xB6, 0xFF].repeat(100_000); + let chapter = parse_chapter(&data, 0); + let mut current = &chapter; + for _ in 0..MAX_META_DEPTH { + assert_eq!(current.children.len(), 1); + current = ¤t.children[0]; + } + assert!(current.children.is_empty()); + } + + #[test] + fn deeply_nested_simple_tags_stop_at_depth_limit() { + let data = [0x67, 0xC8, 0xFF].repeat(100_000); + let tag = parse_simple_tag(&data, 0); + let mut current = &tag; + for _ in 0..MAX_META_DEPTH { + assert_eq!(current.children.len(), 1); + current = ¤t.children[0]; + } + assert!(current.children.is_empty()); + } +} diff --git a/crates/media/src/matroska/mod.rs b/crates/media/src/matroska/mod.rs new file mode 100644 index 000000000..9e60a9600 --- /dev/null +++ b/crates/media/src/matroska/mod.rs @@ -0,0 +1,39 @@ +//! Clean-room Matroska (MKV) and WebM demuxer, written from RFC 8794 (EBML), RFC 9559 (Matroska) +//! and the WebM container guidelines. +//! +//! - [`open`] / [`open_with`] parse the EBML header and the first Segment (Info, Tracks, SeekHead, +//! Cues, Chapters, Tags, Attachments) and, by default, scan every Cluster's block headers to build +//! per-track [`Sample`] tables — the same shape as [`isobmff`](crate::isobmff), so callers can treat both +//! containers alike. Frame data is read on demand with [`MkvFile::read_sample`]. +//! - [`Demuxer`] iterates [`Packet`]s in file order (from any [`ByteSource`], `Read + Seek`, or a +//! byte slice) and seeks to the keyframe preceding a time, via the index, Cues, or a cluster scan. +//! +//! No dependencies beyond `std`, no `unsafe`, builds for `wasm32-unknown-unknown`. + +mod codec; +mod demux; +pub mod ebml; +mod error; +mod ids; +#[cfg(test)] +mod index_limit_tests; +mod meta; +mod mux; +#[cfg(test)] +mod synthetic_tests; +mod track; + +pub use crate::source::{ByteSource, ReadSeekSource}; +pub use codec::Codec; +pub use demux::{Demuxer, Keyframe, MkvFile, OpenOptions, Packet, SeekPoint, open, open_with}; +pub use error::{Error, Result}; +pub use meta::{ + Attachment, Chapter, ChapterDisplay, ClusterInfo, CuePoint, CuePosition, Edition, SeekEntry, SegmentInfo, SimpleTag, Tag, TagTargets, +}; +pub use mux::{LacingMode, MkvWriter, MuxOptions, TrackSpec}; +pub use track::{AudioInfo, Color, ContentEncoding, MasteringMetadata, Projection, Sample, Track, TrackKind, VideoInfo}; + +/// Element IDs used by the demuxer (marker bits included), for callers inspecting raw elements. +pub mod element_ids { + pub use crate::matroska::ids::*; +} diff --git a/crates/media/src/matroska/mux.rs b/crates/media/src/matroska/mux.rs new file mode 100644 index 000000000..b0ae893d9 --- /dev/null +++ b/crates/media/src/matroska/mux.rs @@ -0,0 +1,726 @@ +//! Minimal Matroska / WebM muxer: SimpleBlocks (optionally laced), BlockGroups for explicit +//! durations, Cues, SeekHead, Info with Duration. Output must be `Write + Seek` (sizes and the +//! SeekHead are back-patched on [`MkvWriter::finish`]). + +use std::io::{Seek, SeekFrom, Write}; + +use crate::matroska::ebml::{write_id, write_size, write_unknown_size}; +use crate::matroska::error::{Error, Result}; +use crate::matroska::ids::{ + AUDIO, BIT_DEPTH, BITS_PER_CHANNEL, BLOCK, BLOCK_DURATION, BLOCK_GROUP, CB_SUBSAMPLING_HORZ, CB_SUBSAMPLING_VERT, CHANNELS, CHROMA_SITING_HORZ, + CHROMA_SITING_VERT, CHROMA_SUBSAMPLING_HORZ, CHROMA_SUBSAMPLING_VERT, CLUSTER, CODEC_DELAY, CODEC_ID, CODEC_PRIVATE, COLOUR, + CUE_CLUSTER_POSITION, CUE_POINT, CUE_TIME, CUE_TRACK, CUE_TRACK_POSITIONS, CUES, DEFAULT_DURATION, DOC_TYPE, DOC_TYPE_READ_VERSION, + DOC_TYPE_VERSION, DURATION, EBML, EBML_MAX_ID_LENGTH, EBML_MAX_SIZE_LENGTH, EBML_READ_VERSION, EBML_VERSION, FLAG_LACING, INFO, LANGUAGE, + LUMINANCE_MAX, LUMINANCE_MIN, MASTERING_METADATA, MATRIX_COEFFICIENTS, MAX_CLL, MAX_FALL, MUXING_APP, NAME, PIXEL_HEIGHT, PIXEL_WIDTH, PRIMARIES, + PRIMARY_B_X, PRIMARY_B_Y, PRIMARY_G_X, PRIMARY_G_Y, PRIMARY_R_X, PRIMARY_R_Y, RANGE, REFERENCE_BLOCK, SAMPLING_FREQUENCY, SEEK, SEEK_HEAD, + SEEK_ID, SEEK_POSITION, SEEK_PRE_ROLL, SEGMENT, SIMPLE_BLOCK, TIMESTAMP, TIMESTAMP_SCALE, TITLE, TRACK_ENTRY, TRACK_NUMBER, TRACK_TYPE, + TRACK_UID, TRACKS, TRANSFER_CHARACTERISTICS, VIDEO, VOID, WHITE_POINT_X, WHITE_POINT_Y, WRITING_APP, +}; +use crate::matroska::track::{Color, TrackKind}; + +/// Lacing used for audio tracks. Only frames of a track with a DefaultDuration lace, and a lace +/// ends where the timestamps stop advancing by that duration. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum LacingMode { + None, + Xiph, + Ebml, + /// Fixed-size lacing when consecutive frames have equal sizes, otherwise EBML lacing. + FixedOrEbml, +} + +/// Track description for [`MkvWriter`]. +#[derive(Clone, Debug)] +pub struct TrackSpec { + pub kind: TrackKind, + pub codec_id: String, + pub codec_private: Vec, + pub default_duration_ns: Option, + pub language: Option, + pub name: Option, + /// Pixel width/height for video tracks. + pub video_size: Option<(u32, u32)>, + /// The video track's `Colour` element (RFC 9559): the fields that are set are written. VP9's + /// own colour syntax carries only the matrix and range, so without it a Rec. 2020, P3, PQ or + /// HLG stream reads as BT.709. Ignored without a `video_size`. + pub color: Option, + /// (sampling frequency, channels, bit depth) for audio tracks. + pub audio: Option<(f64, u64, Option)>, + pub codec_delay_ns: u64, + pub seek_pre_roll_ns: u64, +} + +impl TrackSpec { + pub fn new(kind: TrackKind, codec_id: impl Into) -> Self { + Self { + kind, + codec_id: codec_id.into(), + codec_private: Vec::new(), + default_duration_ns: None, + language: None, + name: None, + video_size: None, + color: None, + audio: None, + codec_delay_ns: 0, + seek_pre_roll_ns: 0, + } + } +} + +/// Muxer options. +#[derive(Clone, Debug)] +pub struct MuxOptions { + /// `webm` or `matroska`. + pub doc_type: String, + /// Nanoseconds per tick (default 1 000 000). + pub timestamp_scale: u64, + /// Start a new cluster at the next video keyframe (or any frame without video) after this long. + pub cluster_duration_ns: u64, + pub lacing: LacingMode, + /// Maximum frames per laced block. Matroska allows 1 to 256; [`MkvWriter::new`] clamps + /// other values into that range. + pub max_lace_frames: usize, + pub title: Option, + pub writing_app: String, +} + +impl Default for MuxOptions { + fn default() -> Self { + Self { + doc_type: "matroska".into(), + timestamp_scale: 1_000_000, + cluster_duration_ns: 1_000_000_000, + lacing: LacingMode::None, + max_lace_frames: 8, + title: None, + writing_app: "craft-media".into(), + } + } +} + +pub(crate) fn el(out: &mut Vec, id: u32, data: &[u8]) { + write_id(out, id); + write_size(out, data.len() as u64, 1); + out.extend_from_slice(data); +} + +pub(crate) fn el_uint(out: &mut Vec, id: u32, v: u64) { + let n = (8 - v.leading_zeros() as usize / 8).max(1); + el(out, id, &v.to_be_bytes()[8 - n..]); +} + +pub(crate) fn el_float(out: &mut Vec, id: u32, v: f64) { + el(out, id, &v.to_be_bytes()); +} + +/// The body of a `Colour` element: every field of `c` that is set. +fn colour(c: &Color) -> Vec { + let mut out = Vec::new(); + for (id, v) in [ + (MATRIX_COEFFICIENTS, c.matrix_coefficients), + (BITS_PER_CHANNEL, c.bits_per_channel), + (CHROMA_SUBSAMPLING_HORZ, c.chroma_subsampling_horz), + (CHROMA_SUBSAMPLING_VERT, c.chroma_subsampling_vert), + (CB_SUBSAMPLING_HORZ, c.cb_subsampling_horz), + (CB_SUBSAMPLING_VERT, c.cb_subsampling_vert), + (CHROMA_SITING_HORZ, c.chroma_siting_horz), + (CHROMA_SITING_VERT, c.chroma_siting_vert), + (RANGE, c.range), + (TRANSFER_CHARACTERISTICS, c.transfer_characteristics), + (PRIMARIES, c.primaries), + (MAX_CLL, c.max_cll), + (MAX_FALL, c.max_fall), + ] { + if let Some(v) = v { + el_uint(&mut out, id, v); + } + } + if let Some(m) = &c.mastering { + let [r, g, b] = m.primaries; + let mut md = Vec::new(); + for (id, v) in [ + (PRIMARY_R_X, r.0), + (PRIMARY_R_Y, r.1), + (PRIMARY_G_X, g.0), + (PRIMARY_G_Y, g.1), + (PRIMARY_B_X, b.0), + (PRIMARY_B_Y, b.1), + (WHITE_POINT_X, m.white_point.0), + (WHITE_POINT_Y, m.white_point.1), + (LUMINANCE_MAX, m.luminance_max), + (LUMINANCE_MIN, m.luminance_min), + ] { + el_float(&mut md, id, v); + } + el(&mut out, MASTERING_METADATA, &md); + } + out +} + +pub(crate) fn el_str(out: &mut Vec, id: u32, s: &str) { + el(out, id, s.as_bytes()); +} + +fn void(out: &mut Vec, total: usize) { + debug_assert!(total >= 2); + let sl = if total - 2 <= 126 { 1 } else { 8 }; + write_id(out, VOID); + write_size(out, (total - 1 - sl) as u64, sl); + out.resize(out.len() + total - 1 - sl, 0); +} + +#[derive(Clone, Debug)] +struct Pending { + track: usize, + ts: i64, + frames: Vec>, +} + +const SEEK_HEAD_SPACE: usize = 128; + +/// Streaming Matroska/WebM writer. +pub struct MkvWriter { + w: W, + opts: MuxOptions, + tracks: Vec, + segment_size_pos: u64, + segment_data_start: u64, + seek_head_pos: u64, + duration_pos: u64, + info_pos: u64, + tracks_pos: u64, + cluster: Vec, + cluster_ts: Option, + cluster_start_ns: i64, + pending: Option, + cues: Vec<(u64, u64, u64)>, // (time ticks, track number, cluster position) + /// The cluster number in which each track last had a cue. Starting a cluster bumps + /// `cluster_number` instead of clearing an entry for every declared track. + track_cued_in: Vec, + cluster_number: u64, + end_ns: i64, + has_video: bool, +} + +impl MkvWriter { + pub fn new(mut w: W, tracks: Vec, mut opts: MuxOptions) -> Result { + if tracks.is_empty() || opts.timestamp_scale == 0 { + return Err(Error::Invalid("muxer needs at least one track and a non-zero timestamp scale".into())); + } + // A block stores its frame count minus one in a byte. + opts.max_lace_frames = opts.max_lace_frames.clamp(1, 256); + let mut out = Vec::new(); + let mut h = Vec::new(); + el_uint(&mut h, EBML_VERSION, 1); + el_uint(&mut h, EBML_READ_VERSION, 1); + el_uint(&mut h, EBML_MAX_ID_LENGTH, 4); + el_uint(&mut h, EBML_MAX_SIZE_LENGTH, 8); + el_str(&mut h, DOC_TYPE, &opts.doc_type); + el_uint(&mut h, DOC_TYPE_VERSION, 4); + el_uint(&mut h, DOC_TYPE_READ_VERSION, 2); + el(&mut out, EBML, &h); + write_id(&mut out, SEGMENT); + let base = w.stream_position()?; + let segment_size_pos = base + out.len() as u64; + write_unknown_size(&mut out, 8); + let segment_data_start = base + out.len() as u64; + let seek_head_pos = segment_data_start; + void(&mut out, SEEK_HEAD_SPACE); + // Info + let info_pos = base + out.len() as u64; + let mut info = Vec::new(); + el_uint(&mut info, TIMESTAMP_SCALE, opts.timestamp_scale); + el_str(&mut info, MUXING_APP, "craft-media"); + el_str(&mut info, WRITING_APP, &opts.writing_app); + if let Some(t) = &opts.title { + el_str(&mut info, TITLE, t); + } + let dur_off_in_info = info.len() + 2 + 1; // ID (2) + size (1) + el_float(&mut info, DURATION, 0.0); + write_id(&mut out, INFO); + write_size(&mut out, info.len() as u64, 1); + let duration_pos = base + out.len() as u64 + dur_off_in_info as u64; + out.extend_from_slice(&info); + // Tracks + let tracks_pos = base + out.len() as u64; + let mut tr = Vec::new(); + for (i, t) in tracks.iter().enumerate() { + let mut e = Vec::new(); + el_uint(&mut e, TRACK_NUMBER, i as u64 + 1); + el_uint(&mut e, TRACK_UID, 0x1000 + i as u64 + 1); + let ty = match t.kind { + TrackKind::Video => 1, + TrackKind::Audio => 2, + TrackKind::Subtitle => 0x11, + TrackKind::Complex => 3, + TrackKind::Logo => 0x10, + TrackKind::Buttons => 0x12, + TrackKind::Control => 0x20, + TrackKind::Metadata => 0x21, + TrackKind::Other(n) => n as u64, + }; + el_uint(&mut e, TRACK_TYPE, ty); + el_uint(&mut e, FLAG_LACING, (t.kind == TrackKind::Audio && opts.lacing != LacingMode::None) as u64); + if let Some(l) = &t.language { + el_str(&mut e, LANGUAGE, l); + } + if let Some(n) = &t.name { + el_str(&mut e, NAME, n); + } + el_str(&mut e, CODEC_ID, &t.codec_id); + if !t.codec_private.is_empty() { + el(&mut e, CODEC_PRIVATE, &t.codec_private); + } + if let Some(d) = t.default_duration_ns { + el_uint(&mut e, DEFAULT_DURATION, d); + } + if t.codec_delay_ns > 0 { + el_uint(&mut e, CODEC_DELAY, t.codec_delay_ns); + } + if t.seek_pre_roll_ns > 0 { + el_uint(&mut e, SEEK_PRE_ROLL, t.seek_pre_roll_ns); + } + if let Some((pw, ph)) = t.video_size { + let mut v = Vec::new(); + el_uint(&mut v, PIXEL_WIDTH, pw as u64); + el_uint(&mut v, PIXEL_HEIGHT, ph as u64); + if let Some(c) = &t.color { + el(&mut v, COLOUR, &colour(c)); + } + el(&mut e, VIDEO, &v); + } + if let Some((rate, ch, bits)) = t.audio { + let mut a = Vec::new(); + el_float(&mut a, SAMPLING_FREQUENCY, rate); + el_uint(&mut a, CHANNELS, ch); + if let Some(b) = bits { + el_uint(&mut a, BIT_DEPTH, b); + } + el(&mut e, AUDIO, &a); + } + el(&mut tr, TRACK_ENTRY, &e); + } + el(&mut out, TRACKS, &tr); + w.write_all(&out)?; + let has_video = tracks.iter().any(|t| t.kind == TrackKind::Video); + let n = tracks.len(); + Ok(Self { + w, + opts, + tracks, + segment_size_pos, + segment_data_start, + seek_head_pos, + duration_pos, + info_pos, + tracks_pos, + cluster: Vec::new(), + cluster_ts: None, + cluster_start_ns: 0, + pending: None, + cues: Vec::new(), + track_cued_in: vec![u64::MAX; n], + cluster_number: 0, + end_ns: 0, + has_video, + }) + } + + /// Add one frame. `pts_ns` is the presentation time (codec delay is added back for storage); + /// frames must be supplied in the desired file order. `duration_ns` forces a BlockGroup with a + /// BlockDuration when it differs from the track's DefaultDuration. + pub fn write_frame(&mut self, track: usize, pts_ns: i64, keyframe: bool, data: &[u8], duration_ns: Option) -> Result<()> { + let spec = self.tracks.get(track).ok_or(Error::NoSuchTrack(track))?; + // the Matroska ProRes mapping stores frames without the 8-byte `size`+`icpf` header + let data = if spec.codec_id == "V_PRORES" && data.get(4..8) == Some(b"icpf") { &data[8..] } else { data }; + let scale = self.opts.timestamp_scale as i64; + let stored_ns = pts_ns + spec.codec_delay_ns as i64; + if stored_ns < 0 { + return Err(Error::Invalid("negative timestamp".into())); + } + let ts = (stored_ns + scale / 2) / scale; + let dur_end = pts_ns + duration_ns.or(spec.default_duration_ns).unwrap_or(0) as i64; + self.end_ns = self.end_ns.max(dur_end).max(pts_ns); + let is_video = spec.kind == TrackKind::Video; + let lacing = spec.kind == TrackKind::Audio && self.opts.lacing != LacingMode::None; + let explicit_dur = duration_ns.filter(|&d| Some(d) != spec.default_duration_ns); + let lace_duration = spec.default_duration_ns.filter(|_| lacing && explicit_dur.is_none()); + // new cluster? + let start_new = match self.cluster_ts { + None => true, + Some(cts) => { + let long = stored_ns - self.cluster_start_ns >= self.opts.cluster_duration_ns as i64; + (long && (!self.has_video || (is_video && keyframe))) || ts - cts > 30_000 || ts < cts + } + }; + if start_new { + self.flush_cluster()?; + self.cluster_ts = Some(ts); + self.cluster_start_ns = stored_ns; + el_uint(&mut self.cluster, TIMESTAMP, ts as u64); + } + let cts = self.cluster_ts.unwrap_or(0); + // cue: video keyframes, or the first frame of each track per cluster when there is no video + if (is_video && keyframe) || (!self.has_video && self.track_cued_in[track] != self.cluster_number) { + self.track_cued_in[track] = self.cluster_number; + let pos = self.w.stream_position()? - self.segment_data_start; + if self.cues.last().is_none_or(|c| c.2 != pos || c.1 != track as u64 + 1) { + self.cues.push((ts as u64, track as u64 + 1, pos)); + } + } + // A laced frame has no timestamp of its own: readers space the frames of a block by + // DefaultDuration. So only frames with that duration lace, and a frame joins the pending + // lace only when the tick it would get there is the tick it has. + if let Some(dd) = lace_duration { + let max = self.opts.max_lace_frames; + let joins = self.pending.as_ref().is_some_and(|p| { + let n = p.frames.len(); + let implied = ((cts + p.ts) as i128 * scale as i128 + n as i128 * dd as i128 + scale as i128 / 2) / scale as i128; + p.track == track && n < max && implied == ts as i128 + }); + if !joins { + self.flush_pending(); + } + match &mut self.pending { + Some(p) => p.frames.push(data.to_vec()), + None => self.pending = Some(Pending { track, ts: ts - cts, frames: vec![data.to_vec()] }), + } + return Ok(()); + } + self.flush_pending(); + let mut block = Vec::new(); + write_size(&mut block, track as u64 + 1, 1); + block.extend_from_slice(&((ts - cts) as i16).to_be_bytes()); + if let Some(d) = explicit_dur { + block.push(0); + block.extend_from_slice(data); + let mut g = Vec::new(); + el(&mut g, BLOCK, &block); + el_uint(&mut g, BLOCK_DURATION, ((u128::from(d) + scale as u128 / 2) / scale as u128) as u64); + if !keyframe { + el(&mut g, REFERENCE_BLOCK, &[0xFF]); + } + el(&mut self.cluster, BLOCK_GROUP, &g); + } else { + block.push(if keyframe { 0x80 } else { 0 }); + block.extend_from_slice(data); + el(&mut self.cluster, SIMPLE_BLOCK, &block); + } + Ok(()) + } + + fn flush_pending(&mut self) { + let Some(p) = self.pending.take() else { return }; + let mut block = Vec::new(); + write_size(&mut block, p.track as u64 + 1, 1); + block.extend_from_slice(&(p.ts as i16).to_be_bytes()); + let n = p.frames.len(); + let mode = if n == 1 { LacingMode::None } else { self.opts.lacing }; + let fixed = p.frames.iter().all(|f| f.len() == p.frames[0].len()); + match mode { + LacingMode::None => block.push(0x80), + LacingMode::Xiph => { + block.push(0x80 | 0x02); + block.push((n - 1) as u8); + for f in &p.frames[..n - 1] { + let mut s = f.len(); + while s >= 255 { + block.push(255); + s -= 255; + } + block.push(s as u8); + } + } + LacingMode::FixedOrEbml if fixed => { + block.push(0x80 | 0x04); + block.push((n - 1) as u8); + } + LacingMode::Ebml | LacingMode::FixedOrEbml => { + block.push(0x80 | 0x06); + block.push((n - 1) as u8); + write_size(&mut block, p.frames[0].len() as u64, 1); + for i in 1..n - 1 { + let d = p.frames[i].len() as i64 - p.frames[i - 1].len() as i64; + // signed VINT: smallest length whose range holds d + let mut len = 1; + while len < 8 && d.unsigned_abs() >= (1u64 << (7 * len - 1)) - 1 { + len += 1; + } + let v = (d + (1i64 << (7 * len - 1)) - 1) as u64 | (1u64 << (7 * len)); + block.extend_from_slice(&v.to_be_bytes()[8 - len..]); + } + } + } + for f in &p.frames { + block.extend_from_slice(f); + } + el(&mut self.cluster, SIMPLE_BLOCK, &block); + } + + fn flush_cluster(&mut self) -> Result<()> { + self.flush_pending(); + if self.cluster_ts.is_some() { + let mut out = Vec::new(); + el(&mut out, CLUSTER, &self.cluster); + self.w.write_all(&out)?; + } + self.cluster.clear(); + self.cluster_ts = None; + self.cluster_number = self.cluster_number.wrapping_add(1); + Ok(()) + } + + /// Write Cues, back-patch SeekHead / Segment size / Duration, and return the writer. + pub fn finish(mut self) -> Result { + self.flush_cluster()?; + let cues_pos = self.w.stream_position()?; + let mut cues = Vec::new(); + for &(time, track, pos) in &self.cues { + let mut ctp = Vec::new(); + el_uint(&mut ctp, CUE_TRACK, track); + el_uint(&mut ctp, CUE_CLUSTER_POSITION, pos); + let mut cp = Vec::new(); + el_uint(&mut cp, CUE_TIME, time); + el(&mut cp, CUE_TRACK_POSITIONS, &ctp); + el(&mut cues, CUE_POINT, &cp); + } + let has_cues = !cues.is_empty(); + if has_cues { + let mut out = Vec::new(); + el(&mut out, CUES, &cues); + self.w.write_all(&out)?; + } + let end = self.w.stream_position()?; + // SeekHead + let mut sh = Vec::new(); + let mut entries = vec![(INFO, self.info_pos), (TRACKS, self.tracks_pos)]; + if has_cues { + entries.push((CUES, cues_pos)); + } + for (id, pos) in entries { + let mut s = Vec::new(); + let mut idb = Vec::new(); + write_id(&mut idb, id); + el(&mut s, SEEK_ID, &idb); + el_uint(&mut s, SEEK_POSITION, pos - self.segment_data_start); + el(&mut sh, SEEK, &s); + } + let mut out = Vec::new(); + el(&mut out, SEEK_HEAD, &sh); + if out.len() + 2 > SEEK_HEAD_SPACE { + return Err(Error::Invalid("SeekHead does not fit its reserved space".into())); + } + let rest = SEEK_HEAD_SPACE - out.len(); + void(&mut out, rest); + self.w.seek(SeekFrom::Start(self.seek_head_pos))?; + self.w.write_all(&out)?; + // Duration + let dur = self.end_ns as f64 / self.opts.timestamp_scale as f64; + self.w.seek(SeekFrom::Start(self.duration_pos))?; + self.w.write_all(&dur.to_be_bytes())?; + // Segment size + let mut sz = Vec::new(); + write_size(&mut sz, end - self.segment_data_start, 8); + self.w.seek(SeekFrom::Start(self.segment_size_pos))?; + self.w.write_all(&sz)?; + self.w.seek(SeekFrom::Start(end))?; + self.w.flush()?; + Ok(self.w) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::matroska::{Demuxer, TrackKind}; + use std::io::Cursor; + + fn roundtrip(lacing: LacingMode) { + let mut v = TrackSpec::new(TrackKind::Video, "V_MJPEG"); + v.video_size = Some((16, 16)); + v.default_duration_ns = Some(40_000_000); + let mut a = TrackSpec::new(TrackKind::Audio, "A_PCM/INT/LIT"); + a.audio = Some((48000.0, 1, Some(16))); + a.default_duration_ns = Some(10_000_000); + let mut s = TrackSpec::new(TrackKind::Subtitle, "S_TEXT/UTF8"); + s.language = Some("fre".into()); + let opts = MuxOptions { lacing, ..Default::default() }; + let mut m = MkvWriter::new(Cursor::new(Vec::new()), vec![v, a, s], opts).unwrap(); + let mut expect = Vec::new(); + for i in 0..50i64 { + let vf = vec![i as u8; 100 + i as usize]; + m.write_frame(0, i * 40_000_000, i % 10 == 0, &vf, None).unwrap(); + expect.push((0usize, i * 40, vf, i % 10 == 0)); + for k in 0..4 { + let n = if lacing == LacingMode::FixedOrEbml { 960 } else { 900 + (i as usize * 7 + k * 13) % 300 }; + let af = vec![(i * 4 + k as i64) as u8; n]; + let t = i * 40 + k as i64 * 10; + m.write_frame(1, t * 1_000_000, true, &af, None).unwrap(); + expect.push((1, t, af, true)); + } + if i % 20 == 5 { + m.write_frame(2, i * 40_000_000, true, b"hello", Some(500_000_000)).unwrap(); + expect.push((2, i * 40, b"hello".to_vec(), true)); + } + } + let bytes = m.finish().unwrap().into_inner(); + let mut d = Demuxer::from_slice(&bytes).unwrap(); + assert!(d.file().warnings.is_empty(), "{:?}", d.file().warnings); + assert_eq!(d.tracks()[2].language, "fre"); + assert!(!d.file().cues.is_empty()); + assert_eq!(d.duration_ns(), Some(2_300_000_000)); + let got: Vec<_> = d.by_ref().map(|p| p.unwrap()).collect(); + assert_eq!(got.len(), expect.len()); + for (g, e) in got.iter().zip(&expect) { + assert_eq!((g.track, g.pts, &g.data, g.keyframe), (e.0, e.1, &e.2, e.3)); + } + let sub = got.iter().find(|p| p.track == 2).unwrap(); + assert_eq!(sub.duration, 500); + // the index agrees with the packet stream + let f = d.file(); + for (ti, t) in f.tracks.iter().enumerate() { + let pk: Vec<_> = got.iter().filter(|p| p.track == ti).collect(); + assert_eq!(t.samples.len(), pk.len()); + for (i, p) in pk.iter().enumerate() { + assert_eq!(f.read_sample(&bytes[..], ti, i).unwrap(), p.data); + assert_eq!(t.samples[i].pts, p.pts); + } + } + // seeking + let sp = d.seek(0, 1_230_000_000).unwrap(); + assert_eq!(sp.pts, 1200); + let p = d.next_packet().unwrap().unwrap(); + assert_eq!((p.track, p.pts, p.keyframe), (0, 1200, true)); + let sp = d.seek(1, 1_235_000_000).unwrap(); + assert_eq!(sp.pts, 1230); + let p = d.next_packet().unwrap().unwrap(); + assert_eq!((p.track, p.pts), (1, 1230)); + } + + #[test] + fn roundtrip_unlaced() { + roundtrip(LacingMode::None); + } + #[test] + fn roundtrip_xiph() { + roundtrip(LacingMode::Xiph); + } + #[test] + fn roundtrip_ebml() { + roundtrip(LacingMode::Ebml); + } + #[test] + fn roundtrip_fixed() { + roundtrip(LacingMode::FixedOrEbml); + } + + /// Laced frames get their timestamps from the block's and DefaultDuration, so a gap in the + /// input must end the lace, and a track without DefaultDuration must not lace at all. + #[test] + fn lacing_keeps_timestamp_gaps() { + let mut a = TrackSpec::new(TrackKind::Audio, "A_PCM/INT/LIT"); + a.audio = Some((48000.0, 1, Some(16))); + a.default_duration_ns = Some(10_000_000); + let mut b = TrackSpec::new(TrackKind::Audio, "A_PCM/INT/LIT"); + b.audio = Some((48000.0, 1, Some(16))); + let opts = MuxOptions { lacing: LacingMode::Xiph, ..Default::default() }; + let mut m = MkvWriter::new(Cursor::new(Vec::new()), vec![a, b], opts).unwrap(); + for ms in [0i64, 100, 110, 120, 200] { + m.write_frame(0, ms * 1_000_000, true, &[ms as u8; 64], None).unwrap(); + } + for ms in [300i64, 310] { + m.write_frame(1, ms * 1_000_000, true, &[ms as u8; 64], None).unwrap(); + } + let bytes = m.finish().unwrap().into_inner(); + let got: Vec<_> = Demuxer::from_slice(&bytes).unwrap().map(|p| p.unwrap()).map(|p| (p.track, p.pts, p.lace)).collect(); + assert_eq!(got, [(0, 0, 0), (0, 100, 0), (0, 110, 1), (0, 120, 2), (0, 200, 0), (1, 300, 0), (1, 310, 0)]); + } + + #[test] + fn lace_size_is_clamped_to_256_frames() { + let mut a = TrackSpec::new(TrackKind::Audio, "A_PCM/INT/LIT"); + a.audio = Some((48000.0, 1, Some(16))); + a.default_duration_ns = Some(1_000_000); + for lacing in [LacingMode::Xiph, LacingMode::Ebml, LacingMode::FixedOrEbml] { + let opts = MuxOptions { lacing, max_lace_frames: 300, ..Default::default() }; + let mut m = MkvWriter::new(Cursor::new(Vec::new()), vec![a.clone()], opts).unwrap(); + for i in 0..300i64 { + m.write_frame(0, i * 1_000_000, true, &[i as u8; 4], None).unwrap(); + } + let bytes = m.finish().unwrap().into_inner(); + let d = Demuxer::from_slice(&bytes).unwrap(); + assert!(d.file().warnings.is_empty(), "{:?}", d.file().warnings); + let got: Vec<_> = d.map(|p| p.unwrap()).map(|p| (p.pts, p.lace, p.data)).collect(); + let want: Vec<_> = (0..300i64).map(|i| (i, (i % 256) as u16, vec![i as u8; 4])).collect(); + assert_eq!(got, want); + } + } + + /// A video track's `Colour` element reads back as it was given, and is absent when not set. + #[test] + fn colour_element_roundtrip() { + use crate::matroska::track::MasteringMetadata; + let write = |color: Option| { + let mut v = TrackSpec::new(TrackKind::Video, "V_VP9"); + v.video_size = Some((16, 16)); + v.color = color; + let mut m = MkvWriter::new(Cursor::new(Vec::new()), vec![v], MuxOptions::default()).unwrap(); + m.write_frame(0, 0, true, &[0; 4], None).unwrap(); + let bytes = m.finish().unwrap().into_inner(); + crate::matroska::open(&bytes[..]).unwrap().tracks[0].video.clone().unwrap().color + }; + assert_eq!(write(None), None); + // Rec. 2020 PQ, broadcast range: the four fields a render knows + let pq = Color { matrix_coefficients: Some(9), range: Some(1), transfer_characteristics: Some(16), primaries: Some(9), ..Default::default() }; + assert_eq!(write(Some(pq.clone())), Some(pq.clone())); + let full = Color { + bits_per_channel: Some(10), + chroma_subsampling_horz: Some(1), + chroma_subsampling_vert: Some(1), + cb_subsampling_horz: Some(0), + cb_subsampling_vert: Some(0), + chroma_siting_horz: Some(1), + chroma_siting_vert: Some(2), + max_cll: Some(1000), + max_fall: Some(400), + mastering: Some(MasteringMetadata { + primaries: [(0.708, 0.292), (0.17, 0.797), (0.131, 0.046)], + white_point: (0.3127, 0.329), + luminance_max: 1000.0, + luminance_min: 0.0001, + }), + ..pq + }; + assert_eq!(write(Some(full.clone())), Some(full)); + } + + #[test] + fn block_duration_rounds_to_the_nearest_tick() { + let mut v = TrackSpec::new(TrackKind::Video, "V_MJPEG"); + v.video_size = Some((16, 16)); + let mut m = MkvWriter::new(Cursor::new(Vec::new()), vec![v], MuxOptions::default()).unwrap(); + m.write_frame(0, 0, true, &[0; 4], Some(41_700_000)).unwrap(); + let bytes = m.finish().unwrap().into_inner(); + assert_eq!(Demuxer::from_slice(&bytes).unwrap().next_packet().unwrap().unwrap().duration, 42); + } + + #[test] + fn audio_only_files_cue_each_track_once_per_cluster() { + let mut a = TrackSpec::new(TrackKind::Audio, "A_PCM/INT/LIT"); + a.audio = Some((48000.0, 1, Some(16))); + let opts = MuxOptions { cluster_duration_ns: 1, lacing: LacingMode::None, ..Default::default() }; + let mut m = MkvWriter::new(Cursor::new(Vec::new()), vec![a.clone(), a], opts).unwrap(); + for i in 0..4i64 { + m.write_frame(0, i * 10, true, &[1; 4], None).unwrap(); + m.write_frame(1, i * 10, true, &[2; 4], None).unwrap(); + m.write_frame(0, i * 10 + 1, true, &[3; 4], None).unwrap(); + } + // Clusters hold [t0, t1] then [t0] at each step: one cue per track per cluster. + let mut seen: Vec<(u64, u64)> = m.cues.iter().map(|c| (c.1, c.2)).collect(); + assert_eq!(seen.len(), 12, "{:?}", m.cues); + seen.sort_unstable(); + seen.dedup(); + assert_eq!(seen.len(), 12, "{:?}", m.cues); + } +} diff --git a/crates/media/src/matroska/synthetic_tests.rs b/crates/media/src/matroska/synthetic_tests.rs new file mode 100644 index 000000000..ba96d483c --- /dev/null +++ b/crates/media/src/matroska/synthetic_tests.rs @@ -0,0 +1,647 @@ +//! Hand-built files exercising features FFmpeg does not write: unknown-size Segment/Clusters, +//! header stripping, BlockGroups, Colour + mastering metadata, Chapters, Tags, Attachments, CRC-32. + +use crate::matroska::codec::Codec; +use crate::matroska::demux::MAX_TRACKS; +use crate::matroska::ebml::{self, write_id, write_unknown_size}; +use crate::matroska::error::Error; +use crate::matroska::ids::*; +use crate::matroska::mux::{el, el_float, el_str, el_uint}; +use crate::matroska::track::ContentEncoding; +use crate::matroska::{ByteSource, Demuxer, MkvFile, OpenOptions, Packet, open_with}; + +mod hostile; + +fn block(track: u8, rel: i16, flags: u8, data: &[u8]) -> Vec { + let mut b = vec![0x80 | track]; + b.extend_from_slice(&rel.to_be_bytes()); + b.push(flags); + b.extend_from_slice(data); + b +} + +fn synthetic() -> Vec { + let mut f = Vec::new(); + let mut h = Vec::new(); + el_str(&mut h, DOC_TYPE, "matroska"); + el_uint(&mut h, DOC_TYPE_VERSION, 4); + el(&mut f, EBML, &h); + write_id(&mut f, SEGMENT); + write_unknown_size(&mut f, 8); + // Info with a correct CRC-32 and a Void + let mut info = Vec::new(); + el_uint(&mut info, TIMESTAMP_SCALE, 1_000_000); + el_str(&mut info, TITLE, "Synthetic"); + el(&mut info, VOID, &[0; 3]); + let mut crc_info = Vec::new(); + el(&mut crc_info, CRC32, &ebml::crc32(&info).to_le_bytes()); + crc_info.extend_from_slice(&info); + el(&mut f, INFO, &crc_info); + // Tracks + let mut v = Vec::new(); + el_uint(&mut v, TRACK_NUMBER, 1); + el_uint(&mut v, TRACK_UID, 11); + el_uint(&mut v, TRACK_TYPE, 1); + el_str(&mut v, CODEC_ID, "V_MPEG4/ISO/AVC"); + el(&mut v, CODEC_PRIVATE, &[1, 0x64, 0, 0x1F]); + el_uint(&mut v, DEFAULT_DURATION, 40_000_000); + let mut mm = Vec::new(); + for (id, val) in + [(PRIMARY_R_X, 0.708), (PRIMARY_R_Y, 0.292), (PRIMARY_G_X, 0.17), (PRIMARY_G_Y, 0.797), (PRIMARY_B_X, 0.131), (PRIMARY_B_Y, 0.046)] + { + el_float(&mut mm, id, val); + } + el_float(&mut mm, WHITE_POINT_X, 0.3127); + el_float(&mut mm, WHITE_POINT_Y, 0.329); + el_float(&mut mm, LUMINANCE_MAX, 1000.0); + el_float(&mut mm, LUMINANCE_MIN, 0.0001); + let mut col = Vec::new(); + el_uint(&mut col, MATRIX_COEFFICIENTS, 9); + el_uint(&mut col, RANGE, 2); + el_uint(&mut col, TRANSFER_CHARACTERISTICS, 16); + el_uint(&mut col, PRIMARIES, 9); + el_uint(&mut col, MAX_CLL, 1000); + el_uint(&mut col, MAX_FALL, 400); + el(&mut col, MASTERING_METADATA, &mm); + let mut vid = Vec::new(); + el_uint(&mut vid, PIXEL_WIDTH, 1440); + el_uint(&mut vid, PIXEL_HEIGHT, 1080); + el_uint(&mut vid, DISPLAY_WIDTH, 1920); + el_uint(&mut vid, DISPLAY_HEIGHT, 1080); + el(&mut vid, COLOUR, &col); + // rectangular, a quarter turn clockwise (portrait phone video) + let mut proj = Vec::new(); + el_uint(&mut proj, PROJECTION_TYPE, 0); + el_float(&mut proj, PROJECTION_POSE_ROLL, -90.0); + el(&mut vid, PROJECTION, &proj); + el(&mut v, VIDEO, &vid); + // header stripping: every frame starts with 00 00 00 01 + let mut comp = Vec::new(); + el_uint(&mut comp, CONTENT_COMP_ALGO, 3); + el(&mut comp, CONTENT_COMP_SETTINGS, &[0, 0, 0, 1]); + let mut enc = Vec::new(); + el(&mut enc, CONTENT_COMPRESSION, &comp); + let mut encs = Vec::new(); + el(&mut encs, CONTENT_ENCODING, &enc); + el(&mut v, CONTENT_ENCODINGS, &encs); + let mut a = Vec::new(); + el_uint(&mut a, TRACK_NUMBER, 2); + el_uint(&mut a, TRACK_TYPE, 2); + el_str(&mut a, CODEC_ID, "A_AAC/MPEG4/LC/SBR"); + el_str(&mut a, LANGUAGE, "ger"); + let mut au = Vec::new(); + el_float(&mut au, SAMPLING_FREQUENCY, 24000.0); + el_float(&mut au, OUTPUT_SAMPLING_FREQUENCY, 48000.0); + el_uint(&mut au, CHANNELS, 2); + el(&mut a, AUDIO, &au); + let mut tr = Vec::new(); + el(&mut tr, TRACK_ENTRY, &v); + el(&mut tr, TRACK_ENTRY, &a); + el(&mut f, TRACKS, &tr); + // Chapters + let mut disp = Vec::new(); + el_str(&mut disp, CHAP_STRING, "Intro"); + let mut atom = Vec::new(); + el_uint(&mut atom, CHAPTER_UID, 5); + el_uint(&mut atom, CHAPTER_TIME_START, 0); + el_uint(&mut atom, CHAPTER_TIME_END, 40_000_000); + el(&mut atom, CHAPTER_DISPLAY, &disp); + let mut ed = Vec::new(); + el(&mut ed, CHAPTER_ATOM, &atom); + let mut ch = Vec::new(); + el(&mut ch, EDITION_ENTRY, &ed); + el(&mut f, CHAPTERS, &ch); + // Attachments + let mut af = Vec::new(); + el_str(&mut af, FILE_NAME, "font.ttf"); + el_str(&mut af, FILE_MEDIA_TYPE, "font/ttf"); + el_uint(&mut af, FILE_UID, 77); + el(&mut af, FILE_DATA, &[9; 100]); + let mut att = Vec::new(); + el(&mut att, ATTACHED_FILE, &af); + el(&mut f, ATTACHMENTS, &att); + // Cluster 1 (unknown size): keyframe SimpleBlock, BlockGroup with ReferenceBlock + duration + write_id(&mut f, CLUSTER); + write_unknown_size(&mut f, 1); + el_uint(&mut f, TIMESTAMP, 1000); + el(&mut f, SIMPLE_BLOCK, &block(1, 0, 0x80, &[0x65, 1, 2])); + el(&mut f, SIMPLE_BLOCK, &block(2, 5, 0x80, &[0xAA; 10])); + let mut g = Vec::new(); + el(&mut g, BLOCK, &block(1, 40, 0, &[0x41, 3])); + el(&mut g, REFERENCE_BLOCK, &[0xD8]); + el_uint(&mut g, BLOCK_DURATION, 80); + el(&mut f, BLOCK_GROUP, &g); + el(&mut f, SIMPLE_BLOCK, &block(9, 0, 0x80, &[1])); // unknown track: ignored + // Cluster 2 (unknown size), ended by Tags + write_id(&mut f, CLUSTER); + write_unknown_size(&mut f, 8); + el_uint(&mut f, TIMESTAMP, 1120); + el(&mut f, SIMPLE_BLOCK, &block(1, 0, 0x80, &[0x65, 4])); + let mut st = Vec::new(); + el_str(&mut st, TAG_NAME, "ARTIST"); + el_str(&mut st, TAG_STRING, "Nobody"); + let mut tg = Vec::new(); + let mut tgt = Vec::new(); + el_uint(&mut tgt, TAG_TRACK_UID, 11); + el(&mut tg, TARGETS, &tgt); + el(&mut tg, SIMPLE_TAG, &st); + let mut tags = Vec::new(); + el(&mut tags, TAG, &tg); + el(&mut f, TAGS, &tags); + f +} + +fn assert_synthetic_metadata(f: &MkvFile, bytes: &[u8]) { + assert!(f.live); + assert!(f.warnings.is_empty(), "{:?}", f.warnings); + assert_eq!((f.crc_checked, f.crc_errors.len()), (1, 0)); + assert_eq!(f.info.title.as_deref(), Some("Synthetic")); + let video = &f.tracks[0]; + assert!(matches!(&video.codec, Codec::Avc { avcc } if avcc[1] == 0x64)); + let info = video.video.as_ref().unwrap(); + assert_eq!(info.pixel_aspect(), (4, 3)); + assert_eq!(info.projection.as_ref().map(|projection| projection.roll), Some(-90.0)); + assert_eq!(info.display_rotation(), Some(1)); + let color = info.color.as_ref().unwrap(); + assert!(color.full_range()); + assert_eq!( + (color.matrix_coefficients, color.transfer_characteristics, color.primaries, color.max_cll, color.max_fall), + (Some(9), Some(16), Some(9), Some(1000), Some(400)) + ); + let mastering = color.mastering.as_ref().unwrap(); + assert_eq!(mastering.primaries[1], (0.17, 0.797)); + assert_eq!(mastering.white_point, (0.3127, 0.329)); + assert_eq!((mastering.luminance_max, mastering.luminance_min), (1000.0, 0.0001)); + assert_eq!(video.encodings, vec![ContentEncoding::HeaderStripping { bytes: vec![0, 0, 0, 1], scope: 1 }]); + // Legacy AAC ID synthesizes explicit SBR signaling (LC, 24 kHz, stereo to 48 kHz). + assert_eq!(f.tracks[1].codec, Codec::Aac { asc: vec![0x13, 0x10, 0x56, 0xE5, 0x98] }); + assert_eq!(f.tracks[1].language, "ger"); + assert_eq!(f.chapters[0].chapters[0].title(), Some("Intro")); + assert_eq!(f.chapters[0].chapters[0].end_ns, Some(40_000_000)); + assert_eq!(f.attachments.len(), 1); + let attachment = &f.attachments[0]; + assert_eq!((attachment.name.as_str(), attachment.media_type.as_str(), attachment.uid), ("font.ttf", "font/ttf", 77)); + assert_eq!(&bytes[attachment.data_offset as usize..][..100], &[9; 100]); + assert_eq!(f.tags[0].targets.track_uids, vec![11]); + assert_eq!(f.tags[0].simple[0].string.as_deref(), Some("Nobody")); + assert_eq!(f.clusters.len(), 2); + assert_eq!(video.samples.len(), 3); + assert_eq!(video.keyframes(), &[0, 2]); +} + +fn assert_synthetic_packets(f: &MkvFile, bytes: &[u8]) { + let packets: Vec = Demuxer::from_slice(bytes).unwrap().map(|packet| packet.unwrap()).collect(); + assert_eq!(packets.len(), 4); + assert_eq!((packets[0].track, packets[0].pts, packets[0].keyframe, packets[0].duration), (0, 1000, true, 40)); + assert_eq!(packets[0].data, [0, 0, 0, 1, 0x65, 1, 2]); + assert_eq!((packets[1].track, packets[1].pts, packets[1].data.len()), (1, 1005, 10)); + assert_eq!((packets[2].pts, packets[2].keyframe, packets[2].duration), (1040, false, 80)); + assert_eq!(packets[2].data, [0, 0, 0, 1, 0x41, 3]); + assert_eq!((packets[3].pts, packets[3].pts_ns), (1120, 1_120_000_000)); + assert_eq!(f.read_sample(bytes, 0, 1).unwrap(), packets[2].data); +} + +fn assert_crc_mismatch_is_reported(bytes: &[u8]) { + let mut corrupted = bytes.to_vec(); + let title = corrupted.windows(9).position(|window| window == b"Synthetic").unwrap(); + corrupted[title] = b's'; + let file = open_with(&corrupted[..], &OpenOptions { index: true, verify_crc: true, index_limit: None }).unwrap(); + assert_eq!(file.crc_errors.len(), 1); +} + +fn assert_seek_builds_an_index(bytes: &[u8]) { + let mut demuxer = Demuxer::with_options(bytes, OpenOptions { index: false, verify_crc: false, index_limit: None }).unwrap(); + assert_eq!(demuxer.file().tracks.len(), 2); + assert_eq!(demuxer.seek(0, 1_100_000_000).unwrap().pts, 1000); + assert_eq!(demuxer.seek(0, 1_130_000_000).unwrap().pts, 1120); + assert_eq!(demuxer.next_packet().unwrap().unwrap().pts, 1120); + assert!(demuxer.file().indexed); +} + +#[test] +fn synthetic_file() { + let bytes = synthetic(); + let file = open_with(&bytes[..], &OpenOptions { index: true, verify_crc: true, index_limit: None }).unwrap(); + assert_synthetic_metadata(&file, &bytes); + assert_synthetic_packets(&file, &bytes); + assert_crc_mismatch_is_reported(&bytes); + assert_seek_builds_an_index(&bytes); +} + +/// One video track and one cluster at timestamp `ts` holding `content`. +fn one_cluster(ts: u64, content: &[u8]) -> Vec { + one_cluster_scaled(1_000_000, ts, content) +} + +fn one_cluster_scaled(scale: u64, ts: u64, content: &[u8]) -> Vec { + let mut f = Vec::new(); + let mut h = Vec::new(); + el_str(&mut h, DOC_TYPE, "matroska"); + el(&mut f, EBML, &h); + write_id(&mut f, SEGMENT); + write_unknown_size(&mut f, 8); + let mut info = Vec::new(); + el_uint(&mut info, TIMESTAMP_SCALE, scale); + el(&mut f, INFO, &info); + let mut v = Vec::new(); + el_uint(&mut v, TRACK_NUMBER, 1); + el_uint(&mut v, TRACK_UID, 1); + el_uint(&mut v, TRACK_TYPE, 1); + el_str(&mut v, CODEC_ID, "V_VP9"); + let mut tr = Vec::new(); + el(&mut tr, TRACK_ENTRY, &v); + el(&mut f, TRACKS, &tr); + write_id(&mut f, CLUSTER); + write_unknown_size(&mut f, 8); + el_uint(&mut f, TIMESTAMP, ts); + f.extend_from_slice(content); + f +} + +fn one_block(ts: u64, rel: i16) -> Vec { + let mut b = Vec::new(); + el(&mut b, SIMPLE_BLOCK, &block(1, rel, 0x80, &[0])); + one_cluster(ts, &b) +} + +/// A BlockGroup whose BlockAdditions hold `(BlockAddID, data)` pairs. +fn group_with_additions(block_data: &[u8], additions: &[(Option, &[u8])]) -> Vec { + let mut adds = Vec::new(); + for (id, data) in additions { + let mut more = Vec::new(); + if let Some(id) = id { + el_uint(&mut more, BLOCK_ADD_ID, *id); + } + el(&mut more, BLOCK_ADDITIONAL, data); + el(&mut adds, BLOCK_MORE, &more); + } + let mut g = Vec::new(); + el(&mut g, BLOCK, block_data); + el(&mut g, BLOCK_ADDITIONS, &adds); + let mut out = Vec::new(); + el(&mut out, BLOCK_GROUP, &g); + out +} + +#[test] +fn block_additional_id_1_is_located() { + let mut c = group_with_additions(&block(1, 0, 0, b"frame"), &[(Some(2), b"other"), (None, b"alpha")]); + c.extend(group_with_additions(&block(1, 40, 0, b"next"), &[(Some(2), b"other")])); + // Xiph lacing with two frames: an addition belongs to the block, not to one frame. + c.extend(group_with_additions(&block(1, 80, 0x02, &[1, 2, b'a', b'b', b'c']), &[(Some(1), b"laced")])); + let bytes = one_cluster(0, &c); + let f = open_with(&bytes[..], &OpenOptions::default()).unwrap(); + let t = &f.tracks[0]; + assert_eq!(t.samples.len(), 4); + let adds: Vec<_> = (0..4).map(|i| f.read_sample_addition(&bytes[..], 0, i).unwrap()).collect(); + assert_eq!(adds, [Some(b"alpha".to_vec()), None, None, None]); + assert_eq!(f.read_sample(&bytes[..], 0, 0).unwrap(), b"frame"); + assert!(f.read_sample_addition(&bytes[..], 0, 9).is_err()); +} + +#[test] +fn hostile_cluster_timestamps_saturate() { + let pts = |bytes: &[u8]| { + let first = Demuxer::from_slice(bytes).unwrap().next_packet().unwrap().unwrap().pts; + let indexed = open_with(bytes, &OpenOptions::default()).unwrap().tracks[0].samples[0].pts; + assert_eq!(first, indexed); + first + }; + assert_eq!(pts(&one_block(1000, 5)), 1005); + assert_eq!(pts(&one_block(i64::MAX as u64, 0)), i64::MAX); + assert_eq!(pts(&one_block(i64::MAX as u64, 1)), i64::MAX); + assert_eq!(pts(&one_block(u64::MAX, -3)), i64::MAX - 3); +} + +#[test] +fn cue_position_past_the_file_falls_back_to_the_index() { + for pos in [1 << 40, u64::MAX - 1] { + let mut ctp = Vec::new(); + el_uint(&mut ctp, CUE_TRACK, 1); + el_uint(&mut ctp, CUE_CLUSTER_POSITION, pos); + let mut cp = Vec::new(); + el_uint(&mut cp, CUE_TIME, 0); + el(&mut cp, CUE_TRACK_POSITIONS, &ctp); + let mut cues = Vec::new(); + el(&mut cues, CUE_POINT, &cp); + let mut bytes = one_block(1000, 0); + let at = bytes.windows(4).position(|w| w == CLUSTER.to_be_bytes()).unwrap(); + let mut el_cues = Vec::new(); + el(&mut el_cues, CUES, &cues); + bytes.splice(at..at, el_cues); + let mut d = Demuxer::with_options(bytes, OpenOptions { index: false, verify_crc: false, index_limit: None }).unwrap(); + assert_eq!(d.file().cues.len(), 1); + assert_eq!(d.seek(0, 0).unwrap().pts, 1000); + } +} + +#[test] +fn huge_timestamp_scale_is_ignored() { + // Three laced frames sharing the largest BlockDuration: with TimestampScale near 2^64 the + // per-lace split overflowed u128 and i128. + let mut g = Vec::new(); + el(&mut g, BLOCK, &block(1, 0, 0x02, &[2, 1, 1, b'a', b'b', b'c'])); + el_uint(&mut g, BLOCK_DURATION, u64::MAX); + let mut c = Vec::new(); + el(&mut c, BLOCK_GROUP, &g); + let f = open_with(&one_cluster_scaled(u64::MAX, i64::MAX as u64, &c)[..], &OpenOptions::default()).unwrap(); + assert_eq!(f.info.timestamp_scale, 1_000_000); + assert_eq!(f.tracks[0].samples.len(), 3); + let f = open_with(&one_cluster_scaled(1 << 32, 0, &c)[..], &OpenOptions::default()).unwrap(); + assert_eq!(f.info.timestamp_scale, 1 << 32); +} + +#[test] +fn duration_of_a_block_at_the_largest_timestamp_saturates() { + for d in [80, u64::MAX] { + let mut g = Vec::new(); + el(&mut g, BLOCK, &block(1, 0, 0, &[0])); + el_uint(&mut g, BLOCK_DURATION, d); + let mut c = Vec::new(); + el(&mut c, BLOCK_GROUP, &g); + let f = open_with(&one_cluster(i64::MAX as u64, &c)[..], &OpenOptions::default()).unwrap(); + assert_eq!(f.duration_ns(), Some(u64::MAX)); + } +} + +#[test] +fn empty_laced_frames_exhaust_the_frame_budget() { + // Each 7-byte SimpleBlock is a fixed-size lace of 256 empty frames. + let mut c = Vec::new(); + for _ in 0..100 { + el(&mut c, SIMPLE_BLOCK, &block(1, 0, 0x04, &[0xFF])); + } + let r = open_with(&one_cluster(0, &c)[..], &OpenOptions::default()); + assert!(matches!(r, Err(Error::TooLarge(_))), "{r:?}"); + // Laces of one-byte frames are paid for by their bytes. + let mut c = Vec::new(); + for _ in 0..4 { + let mut data = vec![0xFF]; + data.extend_from_slice(&[0; 256]); + el(&mut c, SIMPLE_BLOCK, &block(1, 0, 0x04, &data)); + } + let f = open_with(&one_cluster(0, &c)[..], &OpenOptions::default()).unwrap(); + assert_eq!(f.tracks[0].samples.len(), 1024); +} + +#[test] +fn track_entries_past_the_cap_are_rejected() { + let file = |entries: usize| { + let mut f = Vec::new(); + let mut h = Vec::new(); + el_str(&mut h, DOC_TYPE, "matroska"); + el(&mut f, EBML, &h); + write_id(&mut f, SEGMENT); + write_unknown_size(&mut f, 8); + let mut tr = Vec::new(); + for _ in 0..entries { + el(&mut tr, TRACK_ENTRY, &[0xD7, 0x81, 0x02]); + } + el(&mut f, TRACKS, &tr); + f + }; + assert_eq!(open_with(&file(3)[..], &OpenOptions::default()).unwrap().tracks.len(), 3); + let r = open_with(&file(MAX_TRACKS + 1)[..], &OpenOptions::default()); + assert!(matches!(r, Err(Error::TooLarge(_))), "{r:?}"); +} + +/// Counts the bytes read from `data`. +struct Counting<'a>(&'a [u8], std::cell::Cell); + +impl ByteSource for Counting<'_> { + fn len(&self) -> u64 { + self.0.len() as u64 + } + fn read_at(&self, offset: u64, buf: &mut [u8]) -> std::io::Result<()> { + self.1.set(self.1.get() + buf.len() as u64); + self.0.read_at(offset, buf) + } +} + +#[test] +fn overlapping_seek_head_targets_are_read_once() { + // SeekHead entries point at nested Tags headers, each running to the end of the file. + let (n, pad) = (64u64, 128usize << 10); + let entry = |pos: u64| { + let mut s = Vec::new(); + el(&mut s, SEEK_ID, &TAGS.to_be_bytes()); + el(&mut s, SEEK_POSITION, &pos.to_be_bytes()); + let mut o = Vec::new(); + el(&mut o, SEEK, &s); + o + }; + let seek_head = |first: u64| { + let entries: Vec = (0..n).flat_map(|i| entry(first + i * 12)).collect(); + let mut o = Vec::new(); + el(&mut o, SEEK_HEAD, &entries); + o + }; + let mut f = Vec::new(); + let mut h = Vec::new(); + el_str(&mut h, DOC_TYPE, "matroska"); + el(&mut f, EBML, &h); + write_id(&mut f, SEGMENT); + write_unknown_size(&mut f, 8); + let first = seek_head(0).len() as u64; + f.extend_from_slice(&seek_head(first)); + let total = n * 12 + pad as u64; + for i in 0..n { + write_id(&mut f, TAGS); + ebml::write_size(&mut f, total - (i + 1) * 12, 8); + } + f.resize(f.len() + pad, 0xEC); + let src = Counting(&f, std::cell::Cell::new(0)); + let file = open_with(&src, &OpenOptions { index: false, verify_crc: false, index_limit: None }).unwrap(); + assert_eq!(file.seek_head.len(), n as usize); + assert!(src.1.get() <= 4 * f.len() as u64, "read {} bytes of a {}-byte file", src.1.get(), f.len()); +} + +/// Fake Cluster candidates every 16 bytes: a Cluster of 512 KiB whose first child is a 64 KiB Void, so +/// `plausible` has to look 64 KiB away from each candidate and then finds a Cluster ID, not a Timestamp. +fn dense_fake_clusters(total: usize) -> Vec { + let mut unit = Vec::new(); + write_id(&mut unit, CLUSTER); + ebml::write_size(&mut unit, 512 << 10, 8); + write_id(&mut unit, VOID); + ebml::write_size(&mut unit, 64 << 10, 3); + assert_eq!(unit.len(), 16); + let mut f = Vec::new(); + let mut h = Vec::new(); + el_str(&mut h, DOC_TYPE, "matroska"); + el(&mut f, EBML, &h); + write_id(&mut f, SEGMENT); + write_unknown_size(&mut f, 8); + // an undecodable first Segment child forces a resync into the fake candidates + f.push(0x00); + while f.len() < total { + f.extend_from_slice(&unit); + } + f +} + +#[test] +fn resync_over_dense_fake_clusters_is_bounded_by_the_recovery_budget() { + let f = dense_fake_clusters(1 << 20); + let src = Counting(&f, std::cell::Cell::new(0)); + let _ = open_with(&src, &OpenOptions::default()); + let read = src.1.get(); + // 64 MiB of recovery work plus the one candidate that overdraws it; unbounded this is gigabytes + assert!(read <= (64 << 20) + (1 << 20), "read {read} bytes of a {}-byte file", f.len()); +} + +#[test] +fn ebml_header_as_large_as_the_file_is_rejected_without_reading_it() { + let mut f = Vec::new(); + write_id(&mut f, EBML); + ebml::write_size(&mut f, (8 << 20) - 12, 8); + f.resize(8 << 20, 0); + let src = Counting(&f, std::cell::Cell::new(0)); + let r = open_with(&src, &OpenOptions::default()); + assert!(matches!(r, Err(Error::NotMatroska(_))), "{r:?}"); + assert!(src.1.get() <= 256 << 10, "read {} bytes", src.1.get()); +} + +#[test] +fn warnings_are_capped() { + // 3000 SeekHead entries, each pointing at a Void instead of the Tags it claims + let mut sh2 = Vec::new(); + for i in 0..3000u32 { + let mut s = Vec::new(); + el(&mut s, SEEK_ID, &TAGS.to_be_bytes()); + el(&mut s, SEEK_POSITION, &(1000 + i).to_be_bytes()); + el(&mut sh2, SEEK, &s); + } + let mut g = Vec::new(); + let mut h = Vec::new(); + el_str(&mut h, DOC_TYPE, "matroska"); + el(&mut g, EBML, &h); + write_id(&mut g, SEGMENT); + write_unknown_size(&mut g, 8); + el(&mut g, SEEK_HEAD, &sh2); + el(&mut g, VOID, &vec![0xEC; 100_000]); + let file = open_with(&g[..], &OpenOptions::default()).unwrap(); + assert_eq!(file.warnings.len(), 257, "256 kept and the note"); + assert_eq!(file.warnings.last().map(String::as_str), Some("further warnings omitted")); +} + +/// `prefix` followed by zeros up to `len` bytes, without holding them. +struct Sparse { + prefix: Vec, + len: u64, +} + +impl ByteSource for Sparse { + fn len(&self) -> u64 { + self.len + } + fn read_at(&self, offset: u64, buf: &mut [u8]) -> std::io::Result<()> { + if offset.checked_add(buf.len() as u64).is_none_or(|e| e > self.len) { + return Err(std::io::ErrorKind::UnexpectedEof.into()); + } + if buf.len() > 64 << 20 { + return Err(std::io::Error::other("a read this large is the bug under test")); + } + for (i, b) in buf.iter_mut().enumerate() { + *b = self.prefix.get((offset as usize).saturating_add(i)).copied().unwrap_or(0); + } + Ok(()) + } +} + +#[test] +fn a_block_larger_than_u32_is_not_indexed_with_a_truncated_size() { + let frame = (1u64 << 32) + 100; + let mut hdr = Vec::new(); + write_id(&mut hdr, SIMPLE_BLOCK); + ebml::write_size(&mut hdr, 4 + frame, 8); + hdr.extend_from_slice(&[0x81, 0, 0, 0x80]); + let prefix = one_cluster(0, &hdr); + let len = prefix.len() as u64 + frame; + let f = open_with(Sparse { prefix, len }, &OpenOptions::default()).unwrap(); + assert!(f.tracks[0].samples.is_empty(), "{:?}", f.tracks[0].samples); +} + +#[test] +fn a_laced_block_larger_than_the_cap_is_skipped_without_reading_its_body() { + // flags 0x02 / 0x06 / 0x04: Xiph, EBML and fixed-size lacing + for flags in [0x82u8, 0x86, 0x84] { + let frame = (1u64 << 32) + 100; + let mut hdr = Vec::new(); + write_id(&mut hdr, SIMPLE_BLOCK); + ebml::write_size(&mut hdr, 4 + frame, 8); + hdr.extend_from_slice(&[0x81, 0, 0, flags]); + let prefix = one_cluster(0, &hdr); + let len = prefix.len() as u64 + frame; + let f = open_with(Sparse { prefix, len }, &OpenOptions::default()); + let f = f.unwrap_or_else(|e| panic!("flags {flags:#x}: {e:?}")); + assert!(f.tracks[0].samples.is_empty(), "flags {flags:#x}: {:?}", f.tracks[0].samples); + } +} + +/// One fake Cluster candidate: it costs the resync two window refills, about 128 KiB. +fn fake_cluster_unit() -> Vec { + let mut unit = Vec::new(); + write_id(&mut unit, CLUSTER); + ebml::write_size(&mut unit, 512 << 10, 8); + write_id(&mut unit, VOID); + ebml::write_size(&mut unit, 64 << 10, 3); + unit +} + +/// Fake Cluster candidates, then a real Cluster. +fn damaged_before_a_cluster() -> Vec { + let unit = fake_cluster_unit(); + let mut f = one_cluster(0, &[]); + // cut the real cluster off: keep EBML, Segment, Info and Tracks + let cluster_at = f.windows(4).position(|w| w == CLUSTER.to_be_bytes()).unwrap(); + f.truncate(cluster_at); + f.push(0x00); + // about 50 MiB of recovery reads: under the 64 MiB budget once, over it twice + for _ in 0..400 { + f.extend_from_slice(&unit); + } + f.resize(f.len() + (700 << 10), 0); + write_id(&mut f, CLUSTER); + write_unknown_size(&mut f, 8); + el_uint(&mut f, TIMESTAMP, 0); + el(&mut f, SIMPLE_BLOCK, &block(1, 0, 0x80, &[1, 2, 3])); + f +} + +#[test] +fn building_the_index_gets_its_own_recovery_budget() { + let f = damaged_before_a_cluster(); + let opts = OpenOptions { index: false, verify_crc: false, index_limit: None }; + let one = open_with(&f[..], &OpenOptions::default()).unwrap(); + assert_eq!(one.tracks[0].samples.len(), 1, "one pass finds the cluster: {:?}", one.warnings); + let mut d = Demuxer::with_options(&f[..], opts).unwrap(); + d.build_index().unwrap(); + assert_eq!(d.file().tracks[0].samples.len(), 1, "the second pass found the cluster too: {:?}", d.file().warnings); +} + +#[test] +fn packet_reading_keeps_its_recovery_budget_after_the_index_is_built() { + // a Cluster, about 40 MiB of recovery reads of damage, then a second Cluster + let mut f = one_cluster(0, &{ + let mut b = Vec::new(); + el(&mut b, SIMPLE_BLOCK, &block(1, 0, 0x80, &[1])); + b + }); + f.push(0x00); + for _ in 0..320 { + f.extend_from_slice(&fake_cluster_unit()); + } + f.resize(f.len() + (700 << 10), 0); + write_id(&mut f, CLUSTER); + write_unknown_size(&mut f, 8); + el_uint(&mut f, TIMESTAMP, 10); + el(&mut f, SIMPLE_BLOCK, &block(1, 0, 0x80, &[2])); + let mut d = Demuxer::with_options(&f[..], OpenOptions { index: false, verify_crc: false, index_limit: None }).unwrap(); + d.build_index().unwrap(); + assert_eq!(d.file().tracks[0].samples.len(), 2, "the index found both clusters: {:?}", d.file().warnings); + let mut n = 0; + while d.next_packet().unwrap().is_some() { + n += 1; + } + assert_eq!(n, 2, "reading ended at the damage: {:?}", d.file().warnings); +} diff --git a/crates/media/src/matroska/synthetic_tests/hostile.rs b/crates/media/src/matroska/synthetic_tests/hostile.rs new file mode 100644 index 000000000..e8180fd3b --- /dev/null +++ b/crates/media/src/matroska/synthetic_tests/hostile.rs @@ -0,0 +1,75 @@ +//! Hostile-input hammer: truncation, bit flips and extreme field values must never panic or hang. + +use super::*; +use crate::matroska::mux::{LacingMode, MkvWriter, MuxOptions, TrackSpec}; +use crate::matroska::{MkvFile, TrackKind}; +use std::io::Cursor; + +fn muxed(lacing: LacingMode) -> Vec { + let mut v = TrackSpec::new(TrackKind::Video, "V_MJPEG"); + v.video_size = Some((16, 16)); + v.default_duration_ns = Some(40_000_000); + let mut a = TrackSpec::new(TrackKind::Audio, "A_PCM/INT/LIT"); + a.audio = Some((48000.0, 1, Some(16))); + let mut s = TrackSpec::new(TrackKind::Subtitle, "S_TEXT/UTF8"); + s.language = Some("fre".into()); + let opts = MuxOptions { lacing, cluster_duration_ns: 100_000_000, ..Default::default() }; + let mut m = MkvWriter::new(Cursor::new(Vec::new()), vec![v, a, s], opts).unwrap(); + for i in 0..12i64 { + m.write_frame(0, i * 40_000_000, i % 4 == 0, &vec![i as u8; 30 + i as usize], None).unwrap(); + for k in 0..3 { + m.write_frame(1, (i * 40 + k * 10) * 1_000_000, true, &[k as u8; 48], None).unwrap(); + } + if i % 5 == 0 { + m.write_frame(2, i * 40_000_000, true, b"hello", Some(500_000_000)).unwrap(); + } + } + m.finish().unwrap().into_inner() +} + +fn walk(f: &MkvFile, d: &[u8]) { + for t in 0..f.tracks.len() { + let n = f.tracks[t].samples.len(); + for k in [0, n / 2, n.saturating_sub(1), n, usize::MAX] { + let _ = f.read_sample(d, t, k); + let _ = f.read_sample_addition(d, t, k); + } + let _ = f.keyframe_before(t, i64::MIN); + let _ = f.keyframe_before(t, i64::MAX); + } + let _ = f.duration_ns(); +} + +fn exercise(d: &[u8]) { + for opts in + [OpenOptions { index: true, verify_crc: true, ..Default::default() }, OpenOptions { index: false, verify_crc: false, ..Default::default() }] + { + if let Ok(f) = open_with(d, &opts) { + walk(&f, d); + } + if let Ok(mut dm) = Demuxer::with_options(d, opts) { + let mut n = 0; + while let Ok(Some(_)) = dm.next_packet() { + n += 1; + if n > 100_000 { + break; + } + } + for t in 0..dm.tracks().len() { + let _ = dm.seek(t, 20_000_000); + let _ = dm.seek(t, i64::MAX); + let _ = dm.seek(t, i64::MIN); + let _ = dm.keyframe_index(t); + } + let _ = dm.build_index(); + } + } +} + +#[test] +fn hostile_input_never_panics() { + let seeds = [synthetic(), muxed(LacingMode::None), muxed(LacingMode::Xiph), muxed(LacingMode::Ebml), muxed(LacingMode::FixedOrEbml)]; + for (i, s) in seeds.iter().enumerate() { + craft_media_testkit::hostile::hammer(&format!("matroska seed {i}"), s, 20_000, exercise); + } +} diff --git a/crates/media/src/matroska/track.rs b/crates/media/src/matroska/track.rs new file mode 100644 index 000000000..edb8fc87b --- /dev/null +++ b/crates/media/src/matroska/track.rs @@ -0,0 +1,467 @@ +//! Track descriptions (RFC 9559 §5.1.4). + +use crate::matroska::codec::Codec; + +/// Track type (`TrackType`). +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum TrackKind { + Video, + Audio, + Complex, + Logo, + Subtitle, + Buttons, + Control, + Metadata, + Other(u8), +} + +impl TrackKind { + pub(crate) fn from_type(t: u64) -> TrackKind { + match t { + 1 => TrackKind::Video, + 2 => TrackKind::Audio, + 3 => TrackKind::Complex, + 0x10 => TrackKind::Logo, + 0x11 => TrackKind::Subtitle, + 0x12 => TrackKind::Buttons, + 0x20 => TrackKind::Control, + 0x21 => TrackKind::Metadata, + n => TrackKind::Other(n as u8), + } + } +} + +/// SMPTE ST 2086 mastering display metadata (`MasteringMetadata`). Chromaticities are CIE 1931 xy, +/// luminance in cd/m². +#[derive(Clone, Debug, Default, PartialEq)] +pub struct MasteringMetadata { + /// Red, green, blue primaries as (x, y). + pub primaries: [(f64, f64); 3], + pub white_point: (f64, f64), + pub luminance_max: f64, + pub luminance_min: f64, +} + +/// `Colour` element. Code points use ITU-T H.273 values (as Matroska does). +#[derive(Clone, Debug, Default, PartialEq)] +pub struct Color { + /// `MatrixCoefficients` (H.273; 2 = unspecified). + pub matrix_coefficients: Option, + pub bits_per_channel: Option, + pub chroma_subsampling_horz: Option, + pub chroma_subsampling_vert: Option, + pub cb_subsampling_horz: Option, + pub cb_subsampling_vert: Option, + pub chroma_siting_horz: Option, + pub chroma_siting_vert: Option, + /// `Range`: 0 unspecified, 1 broadcast (limited), 2 full, 3 defined by matrix/transfer. + pub range: Option, + /// `TransferCharacteristics` (H.273). + pub transfer_characteristics: Option, + /// `Primaries` (H.273). + pub primaries: Option, + /// Maximum content light level (cd/m²). + pub max_cll: Option, + /// Maximum frame-average light level (cd/m²). + pub max_fall: Option, + pub mastering: Option, +} + +impl Color { + /// True if `Range` says full range. + pub fn full_range(&self) -> bool { + self.range == Some(2) + } +} + +/// `Video` element. +#[derive(Clone, Debug, Default, PartialEq)] +pub struct VideoInfo { + pub pixel_width: u32, + pub pixel_height: u32, + /// `DisplayWidth`/`DisplayHeight`, in `display_unit` (0 = pixels, 3 = display aspect ratio). + pub display_width: Option, + pub display_height: Option, + pub display_unit: u64, + /// Crop (top, bottom, left, right) in pixels. + pub crop: (u32, u32, u32, u32), + /// `FlagInterlaced`: 0 undetermined, 1 interlaced, 2 progressive. + pub flag_interlaced: u64, + /// `FieldOrder` (0 progressive, 1 tff, 2 undetermined, 6 bff, 9/14 interleaved). + pub field_order: Option, + pub stereo_mode: Option, + /// `AlphaMode`: 1 if BlockAdditions carry alpha. + pub alpha_mode: u64, + /// `ColourSpace` FourCC (uncompressed video). + pub color_space: Option<[u8; 4]>, + pub color: Option, + pub projection: Option, +} + +/// `Projection` element (RFC 9559 §5.1.4.1.28.41): pose angles in degrees. +#[derive(Clone, Debug, Default, PartialEq)] +pub struct Projection { + /// 0 rectangular, 1 equirectangular, 2 cubemap, 3 mesh. + pub projection_type: u64, + /// Clockwise around the up vector. + pub yaw: f64, + /// Counter-clockwise around the right vector. + pub pitch: f64, + /// Counter-clockwise around the forward vector. + pub roll: f64, +} + +impl VideoInfo { + /// Clockwise quarter turns (0–3) to display a rectangular video, from `ProjectionPoseRoll` + /// (a counter-clockwise angle, so −90 is a quarter turn clockwise). None for other + /// projections, flips (non-zero yaw / pitch) or angles that are not a multiple of 90°. + pub fn display_rotation(&self) -> Option { + let Some(p) = &self.projection else { return Some(0) }; + if p.projection_type != 0 || p.yaw != 0.0 || p.pitch != 0.0 || p.roll % 90.0 != 0.0 { + return None; + } + Some((-(p.roll / 90.0) as i64).rem_euclid(4) as u8) + } + + /// Pixel aspect ratio derived from the display size (pixels or aspect-ratio units), reduced. + pub fn pixel_aspect(&self) -> (u32, u32) { + let pw = self.pixel_width.saturating_sub(self.crop.2.saturating_add(self.crop.3)) as u64; + let ph = self.pixel_height.saturating_sub(self.crop.0.saturating_add(self.crop.1)) as u64; + let (Some(dw), Some(dh)) = (self.display_width, self.display_height) else { return (1, 1) }; + if pw == 0 || ph == 0 || dw == 0 || dh == 0 || !matches!(self.display_unit, 0 | 3) { + return (1, 1); + } + // PAR = (dw/dh) / (pw/ph) + let (n, d) = (dw as u64 * ph, dh as u64 * pw); + let g = gcd(n, d); + ((n / g) as u32, (d / g) as u32) + } +} + +pub(crate) fn gcd(mut a: u64, mut b: u64) -> u64 { + while b != 0 { + (a, b) = (b, a % b); + } + a.max(1) +} + +/// `Audio` element. +#[derive(Clone, Debug, PartialEq)] +pub struct AudioInfo { + /// `SamplingFrequency` (Hz). + pub sampling_frequency: f64, + /// `OutputSamplingFrequency` (e.g. SBR output rate). + pub output_sampling_frequency: Option, + pub channels: u64, + pub bit_depth: Option, +} + +impl Default for AudioInfo { + fn default() -> Self { + Self { sampling_frequency: 8000.0, output_sampling_frequency: None, channels: 1, bit_depth: None } + } +} + +/// One `ContentEncoding`. +#[derive(Clone, Debug, PartialEq)] +pub enum ContentEncoding { + /// `ContentCompAlgo` 3: the given bytes were stripped from the start of every frame. + HeaderStripping { bytes: Vec, scope: u64 }, + /// Other compression (0 zlib, 1 bzlib, 2 lzo1x): not supported for reading frame data. + /// `algo` is `u64::MAX` for a chain of more encodings than a reader checks. + Compression { algo: u64, settings: Vec, scope: u64 }, + /// Encryption (not supported for reading frame data). + Encryption { scope: u64 }, +} + +/// One entry of a track's sample (frame) table. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct Sample { + /// Byte offset of the (stored) frame data in the file. + pub offset: u64, + /// Stored size (excluding header-stripped bytes; see [`Track::sample_size`]). + pub size: u32, + /// Presentation timestamp in the track timebase (`TimestampScale` ticks). + pub pts: i64, + /// Duration in timebase ticks (from `BlockDuration` or `DefaultDuration`), 0 if unknown. + pub duration: u64, + pub keyframe: bool, + /// Index of the owning cluster in [`crate::matroska::MkvFile::clusters`]. + pub cluster: u32, + /// Offset of the block element (SimpleBlock / BlockGroup) header. + pub block_offset: u64, + /// Index of this frame within a laced block. + pub lace: u16, + /// (offset, size) of the block's `BlockAdditional` with `BlockAddID` 1, when it has one and + /// is not laced. In WebM this is the alpha layer of a VP8/VP9 track with `AlphaMode` 1: a + /// second, independently coded stream whose luma plane is the frame's alpha. + pub addition: Option<(u64, u32)>, +} + +/// A Matroska track (`TrackEntry`) plus, once indexed, its sample table. +#[derive(Clone, Debug)] +pub struct Track { + pub number: u64, + pub uid: u64, + pub kind: TrackKind, + pub enabled: bool, + pub default: bool, + pub forced: bool, + pub hearing_impaired: bool, + pub lacing: bool, + /// `DefaultDuration` in nanoseconds. + pub default_duration_ns: Option, + pub name: String, + /// `Language` (ISO 639-2, default `eng`). + pub language: String, + pub language_bcp47: Option, + pub codec_id: String, + pub codec_private: Vec, + pub codec_name: String, + pub codec: Codec, + /// `CodecDelay` in nanoseconds. + pub codec_delay_ns: u64, + /// `SeekPreRoll` in nanoseconds. + pub seek_pre_roll_ns: u64, + pub video: Option, + pub audio: Option, + pub encodings: Vec, + /// Timebase numerator/denominator in seconds: `TimestampScale / 1e9`, reduced. + pub timebase: (u64, u64), + /// Frame table (empty unless the file was opened with indexing). + pub samples: Vec, + pub(crate) sync: Vec, +} + +impl Track { + /// What a decoder needs for this track, in the container-neutral form the codec crates take + /// (`CodecPrivate` is already in that form). + pub fn codec_params(&self) -> crate::CodecParams { + use crate::CodecId as Id; + let (id, extradata) = match &self.codec { + Codec::Avc { avcc } => (Id::H264, avcc.clone()), + Codec::Hevc { hvcc } => (Id::Hevc, hvcc.clone()), + Codec::Vp8 => (Id::Vp8, Vec::new()), + Codec::Vp9 { private } => (Id::Vp9, private.clone()), + Codec::Av1 { av1c } => (Id::Av1, av1c.clone()), + Codec::ProRes { .. } => (Id::ProRes, Vec::new()), + Codec::Apv { apvc } => (Id::Apv, apvc.clone()), + Codec::Mjpeg => (Id::Mjpeg, Vec::new()), + Codec::Aac { asc } => (Id::Aac, asc.clone()), + Codec::Opus { head } => (Id::Opus, head.clone()), + Codec::Vorbis { headers } => (Id::Vorbis, crate::xiph_lace(headers).unwrap_or_default()), + Codec::Flac { private } => (Id::Flac, private.clone()), + Codec::Pcm { .. } => (Id::Pcm, Vec::new()), + Codec::Ac3 => (Id::Ac3, Vec::new()), + Codec::Eac3 => (Id::Eac3, Vec::new()), + Codec::Mp3 => (Id::Mp3, Vec::new()), + Codec::Mp2 => (Id::Mp2, Vec::new()), + Codec::Mp1 => (Id::Mp1, Vec::new()), + // the ALACSpecificConfig, as MP4's `alac` box holds it after its FullBox header + Codec::Other(id) if id == "A_ALAC" => (Id::Alac, self.codec_private.clone()), + Codec::VfwFourcc { fourcc: [b'A', b'V', b'd', b'n' | b'h'], .. } => (Id::Dnxhd, Vec::new()), + _ => (Id::Unknown, Vec::new()), + }; + let mut p = crate::CodecParams::new(id).with_extradata(extradata); + match &self.codec { + Codec::ProRes { fourcc: Some(tag) } | Codec::VfwFourcc { fourcc: tag, .. } => p = p.with_tag(*tag), + _ => {} + } + if let Some(v) = &self.video { + p = p.with_size(v.pixel_width, v.pixel_height); + } + if let Some(a) = &self.audio { + p = p.with_sample_rate(a.sampling_frequency.round() as u32).with_channels(u16::try_from(a.channels).unwrap_or(0)); + } + if let Codec::Opus { .. } = self.codec { + // Opus always decodes at 48 kHz; a muxer may have declared the input rate instead + p = p.with_sample_rate(48_000); + } + if let Codec::Pcm { float, big_endian, bits } = self.codec { + // 8-bit integer PCM is unsigned in Matroska, as in WAV. + p = p.with_pcm(if float { crate::PcmFormat::float(bits, big_endian) } else { crate::PcmFormat::int(bits, bits > 8, big_endian) }); + } + p + } + + /// Bytes prepended to every frame by header-stripping compression, if any. + pub fn stripped_header(&self) -> Option<&[u8]> { + self.encodings.iter().find_map(|e| match e { + ContentEncoding::HeaderStripping { bytes, scope } if scope & 1 != 0 => Some(bytes.as_slice()), + _ => None, + }) + } + + /// True if frames can be returned verbatim or with header stripping undone. + pub fn frames_readable(&self) -> bool { + self.encodings.iter().all(|e| match e { + ContentEncoding::HeaderStripping { .. } => true, + ContentEncoding::Compression { scope, .. } | ContentEncoding::Encryption { scope } => scope & 1 == 0, + }) + } + + /// Bytes to put in front of a stored frame of `stored_size` bytes to get the codec frame: + /// header-stripped bytes, or for `V_PRORES` the 8-byte frame header (`size` + `icpf`) that the + /// Matroska ProRes mapping omits. + pub fn frame_prefix(&self, stored_size: u64) -> Vec { + let mut p = self.stripped_header().map(<[u8]>::to_vec).unwrap_or_default(); + if matches!(self.codec, Codec::ProRes { .. }) { + let total = stored_size + p.len() as u64 + 8; + let mut h = (total as u32).to_be_bytes().to_vec(); + h.extend_from_slice(b"icpf"); + h.extend_from_slice(&p); + p = h; + } + p + } + + /// Length of [`frame_prefix`](Self::frame_prefix), without building it. + pub fn frame_prefix_len(&self) -> u64 { + let stripped = self.stripped_header().map_or(0, <[u8]>::len) as u64; + if matches!(self.codec, Codec::ProRes { .. }) { stripped + 8 } else { stripped } + } + + /// Frame size of sample `i` as returned by `read_sample` / packets (stored size plus prefix). + pub fn sample_size(&self, i: usize) -> Option { + let s = self.samples.get(i)?; + Some(s.size as u64 + self.frame_prefix_len()) + } + + /// Indices of keyframe samples, ascending by file order. + pub fn keyframes(&self) -> &[u32] { + &self.sync + } + + /// Timebase ticks → nanoseconds. + pub fn ticks_to_ns(&self, t: i64) -> i64 { + let ns = t as i128 * self.timebase.0 as i128 * 1_000_000_000 / self.timebase.1 as i128; + ns.clamp(i64::MIN as i128, i64::MAX as i128) as i64 + } + + /// Nanoseconds → timebase ticks (floor). + pub fn ns_to_ticks(&self, ns: i64) -> i64 { + let n = ns as i128 * self.timebase.1 as i128; + let d = self.timebase.0 as i128 * 1_000_000_000; + n.div_euclid(d) as i64 + } + + /// Index of the last sample with `pts <= t` (in file order), or the first sample. + pub fn sample_at_pts(&self, t: i64) -> Option { + if self.samples.is_empty() { + return None; + } + let mut best: Option = None; + for (i, s) in self.samples.iter().enumerate() { + if s.pts <= t && best.is_none_or(|b| s.pts >= self.samples[b].pts) { + best = Some(i); + } + } + Some(best.unwrap_or(0)) + } + + /// Index of the keyframe with the greatest `pts <= t` (the first keyframe if none precedes `t`). + pub fn keyframe_before_pts(&self, t: i64) -> Option { + let mut best: Option = None; + for &k in &self.sync { + let s = &self.samples[k as usize]; + if s.pts <= t && best.is_none_or(|b| s.pts >= self.samples[b].pts) { + best = Some(k as usize); + } + } + best.or_else(|| self.sync.first().map(|&k| k as usize)) + } + + /// Index of the nearest keyframe at or before sample `index` in file order. + pub fn sync_sample_before(&self, index: usize) -> usize { + match self.sync.binary_search(&(index as u32)) { + Ok(i) => self.sync[i] as usize, + Err(0) => 0, + Err(i) => self.sync[i - 1] as usize, + } + } +} + +#[cfg(test)] +mod rotation_tests { + use super::{Projection, VideoInfo}; + + fn with_roll(projection_type: u64, yaw: f64, pitch: f64, roll: f64) -> VideoInfo { + VideoInfo { projection: Some(Projection { projection_type, yaw, pitch, roll }), ..Default::default() } + } + + #[test] + fn display_rotation_maps_rectangular_roll_to_clockwise_quarter_turns() { + assert_eq!(VideoInfo::default().display_rotation(), Some(0), "no Projection: as stored"); + // ProjectionPoseRoll is counter-clockwise: -90 is a quarter turn clockwise + for (roll, turns) in [(0.0, 0), (-90.0, 1), (180.0, 2), (-180.0, 2), (90.0, 3), (-270.0, 3), (270.0, 1), (360.0, 0)] { + assert_eq!(with_roll(0, 0.0, 0.0, roll).display_rotation(), Some(turns), "roll {roll}"); + } + } + + #[test] + fn display_rotation_leaves_non_rectangular_flipped_and_odd_angles_alone() { + assert_eq!(with_roll(1, 0.0, 0.0, -90.0).display_rotation(), None, "equirectangular"); + assert_eq!(with_roll(0, 180.0, 0.0, 0.0).display_rotation(), None, "yaw flip"); + assert_eq!(with_roll(0, 0.0, 180.0, 0.0).display_rotation(), None, "pitch flip"); + assert_eq!(with_roll(0, 0.0, 0.0, 45.0).display_rotation(), None, "not a quarter turn"); + assert_eq!(with_roll(0, 0.0, 0.0, f64::NAN).display_rotation(), None, "malformed angle"); + } +} + +#[cfg(test)] +mod aspect_overflow_tests { + use super::VideoInfo; + + #[test] + fn hostile_crop_sums_do_not_overflow() { + let video = VideoInfo { + pixel_width: 640, + pixel_height: 480, + display_width: Some(640), + display_height: Some(480), + crop: (u32::MAX, 1, u32::MAX, 1), + ..Default::default() + }; + assert_eq!(video.pixel_aspect(), (1, 1)); + } + + #[test] + fn ordinary_pixel_aspect_is_unchanged() { + let video = VideoInfo { pixel_width: 1920, pixel_height: 1080, display_width: Some(1440), display_height: Some(1080), ..Default::default() }; + assert_eq!(video.pixel_aspect(), (3, 4)); + } +} + +#[cfg(test)] +mod codec_params_tests { + use crate::CodecId; + use crate::matroska::mux::{MkvWriter, MuxOptions, TrackSpec}; + use crate::matroska::{Demuxer, TrackKind}; + + #[test] + fn alac_dnx_and_opus_match_mp4() { + let cookie: Vec = (0..24).collect(); + let mut alac = TrackSpec::new(TrackKind::Audio, "A_ALAC"); + alac.codec_private = cookie.clone(); + alac.audio = Some((44_100.0, 2, Some(16))); + let mut bih = vec![0u8; 40]; + bih[16..20].copy_from_slice(b"AVdn"); + let mut dnx = TrackSpec::new(TrackKind::Video, "V_MS/VFW/FOURCC"); + dnx.codec_private = bih; + dnx.video_size = Some((1920, 1080)); + let mut opus = TrackSpec::new(TrackKind::Audio, "A_OPUS"); + opus.codec_private = [b"OpusHead".as_slice(), &[1, 2, 0x38, 0x01, 0x44, 0xAC, 0, 0, 0, 0, 0]].concat(); + opus.audio = Some((44_100.0, 2, None)); // the input rate, as some muxers write it + let mut m = MkvWriter::new(std::io::Cursor::new(Vec::new()), vec![alac, dnx, opus], MuxOptions::default()).unwrap(); + for t in 0..3 { + m.write_frame(t, 0, true, &[0; 4], None).unwrap(); + } + let bytes = m.finish().unwrap().into_inner(); + let d = Demuxer::from_slice(&bytes).unwrap(); + let p: Vec<_> = d.tracks().iter().map(|t| t.codec_params()).collect(); + assert_eq!((p[0].codec, p[0].extradata.as_slice()), (CodecId::Alac, cookie.as_slice())); + assert_eq!((p[1].codec, p[1].tag), (CodecId::Dnxhd, Some(*b"AVdn"))); + assert_eq!((p[2].codec, p[2].sample_rate, p[2].channels), (CodecId::Opus, Some(48_000), Some(2))); + } +} diff --git a/crates/media/src/mpegts/es.rs b/crates/media/src/mpegts/es.rs new file mode 100644 index 000000000..8568c7cba --- /dev/null +++ b/crates/media/src/mpegts/es.rs @@ -0,0 +1,902 @@ +//! Splitting elementary streams into access units while the file is scanned. +//! +//! The scanners feed each stream's payload bytes chunk by chunk (a TS packet's payload, a PS +//! packet's payload). A chunk is identified by the position the reader restarts from (`pos`) and +//! the elementary-stream offset of its first byte. Splitting needs only a few bytes beyond a +//! boundary, so only the most recent chunks are remembered. + +use std::collections::VecDeque; + +use super::{Codec, PictureInfo, Unit}; + +/// How a stream is cut into units. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +enum Mode { + /// MPEG-1/2 video: one coded frame (a frame picture or two field pictures) per unit. + MpegVideo, + /// H.264 / HEVC: one access unit per unit (the first of a PES packet keeps its timestamps); + /// NAL types give the flags. + Nal { hevc: bool }, + /// Framed audio with self-describing frame headers. + Audio(AudioSync), + /// One PES packet per unit. + Pes, +} + +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub(crate) enum AudioSync { + Mpa, + Adts, + Loas, + Ac3, +} + +impl Mode { + fn of(codec: &Codec) -> Mode { + match codec { + Codec::Mpeg1Video | Codec::Mpeg2Video => Mode::MpegVideo, + Codec::H264 => Mode::Nal { hevc: false }, + Codec::Hevc => Mode::Nal { hevc: true }, + Codec::MpegAudio => Mode::Audio(AudioSync::Mpa), + Codec::AacAdts => Mode::Audio(AudioSync::Adts), + Codec::AacLatm => Mode::Audio(AudioSync::Loas), + Codec::Ac3 | Codec::Eac3 => Mode::Audio(AudioSync::Ac3), + _ => Mode::Pes, + } + } +} + +#[derive(Clone, Copy)] +struct PesMark { + es_start: u64, + pts: Option, + dts: Option, + used: bool, +} + +/// A unit whose end is not known yet. +#[derive(Clone, Copy)] +struct Open { + start: u64, + pos: u64, + offset: u32, + pts: Option, + dts: Option, + key: bool, + disposable: bool, + /// A coded slice has been seen (H.264 / HEVC). + vcl: bool, + picture: Option, +} + +/// MPEG video picture waiting for its coding extension (to tell fields from frames). +#[derive(Clone, Copy)] +struct PendingPicture { + /// Start of the unit if the picture begins one (its first sequence / GOP header). + unit_start: u64, + /// The picture start code (timestamps belong to the unit whose picture starts in the PES). + at: u64, + info: PictureInfo, +} + +pub(crate) struct Splitter { + mode: Mode, + /// Elementary-stream bytes fed so far. + es_pos: u64, + /// Recent chunks: (reader position, ES offset of the first byte). + chunks: VecDeque<(u64, u64)>, + pes: VecDeque, + /// Unconsumed bytes (start codes / frame headers spanning chunks), starting at `buf_start`. + buf: Vec, + buf_start: u64, + open: Option, + pub units: Vec, + pub skipped: u64, + /// Units beyond [`MAX_UNITS`] were dropped. + pub truncated: bool, + max_units: usize, + // MPEG video state + header_start: Option, + seq_in_unit: bool, + gop: Option<(bool, bool)>, + pending: Option, + open_field: Option, + // audio state + next_frame: Option, +} + +/// AC-3 frame sizes in 16-bit words for 48 / 44.1 / 32 kHz (A/52 Table 5.18), by +/// frmsizecod / 2; 44.1 kHz adds a word for odd frmsizecod. +const AC3_KBPS: [u32; 19] = [32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320, 384, 448, 512, 576, 640]; + +pub(crate) fn ac3_frame_bytes(fscod: u8, frmsizecod: u8) -> Option { + let kbps = *AC3_KBPS.get((frmsizecod / 2) as usize)?; + let words = match fscod { + 0 => kbps * 2, + 1 => kbps * 96_000 / 44_100 + (frmsizecod & 1) as u32, + 2 => kbps * 3, + _ => return None, + }; + Some(words as usize * 2) +} + +const MPA_KBPS: [[u16; 15]; 5] = [ + [0, 32, 64, 96, 128, 160, 192, 224, 256, 288, 320, 352, 384, 416, 448], // MPEG-1 layer I + [0, 32, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320, 384], // MPEG-1 layer II + [0, 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320], // MPEG-1 layer III + [0, 32, 48, 56, 64, 80, 96, 112, 128, 144, 160, 176, 192, 224, 256], // MPEG-2/2.5 layer I + [0, 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160], // MPEG-2/2.5 layers II, III +]; + +/// MPEG audio frame header (ISO/IEC 11172-3 §2.4.2.3, 13818-3 LSF): (frame bytes, sample rate, +/// samples per frame). +pub(crate) fn mpa_header(b: &[u8]) -> Option<(usize, u32, u32)> { + if b.len() < 4 || b[0] != 0xFF || b[1] & 0xE0 != 0xE0 { + return None; + } + let version = (b[1] >> 3) & 3; // 0: 2.5, 2: MPEG-2, 3: MPEG-1 + let layer = (b[1] >> 1) & 3; // 3: I, 2: II, 1: III + let br = (b[2] >> 4) as usize; + let sr = (b[2] >> 2) & 3; + let pad = ((b[2] >> 1) & 1) as usize; + if version == 1 || layer == 0 || br == 0 || br == 15 || sr == 3 { + return None; + } + let rate = [44_100u32, 48_000, 32_000][sr as usize] + >> match version { + 3 => 0, + 2 => 1, + _ => 2, + }; + let table = match (version == 3, layer) { + (true, 3) => 0, + (true, 2) => 1, + (true, _) => 2, + (false, 3) => 3, + (false, _) => 4, + }; + let kbps = MPA_KBPS[table][br] as usize; + let (bytes, samples) = match layer { + 3 => ((12 * kbps * 1000 / rate as usize + pad) * 4, 384), + 2 => (144 * kbps * 1000 / rate as usize + pad, 1152), + _ if version == 3 => (144 * kbps * 1000 / rate as usize + pad, 1152), + _ => (72 * kbps * 1000 / rate as usize + pad, 576), + }; + (bytes >= 4).then_some((bytes, rate, samples)) +} + +/// What an audio frame header says. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct FrameInfo { + /// Samples per second. + pub sample_rate: u32, + /// Channel count. + pub channels: u32, + /// Samples per channel in the frame. + pub samples: u32, + /// MPEG audio layer (1-3); AC-3 bsid; ADTS object type (profile + 1). + pub variant: u8, +} + +const ADTS_RATES: [u32; 13] = [96_000, 88_200, 64_000, 48_000, 44_100, 32_000, 24_000, 22_050, 16_000, 12_000, 11_025, 8_000, 7_350]; + +/// Bytes of the audio frame whose header starts `b` (MPEG audio, ADTS, LATM, AC-3, E-AC-3), or +/// `None` without a valid header there. For containers that store frames in chunks that need not +/// follow them (AVI): the frames are found again with it. +pub fn frame_bytes(codec: &Codec, b: &[u8]) -> Option { + let sync = match codec { + Codec::MpegAudio => AudioSync::Mpa, + Codec::AacAdts => AudioSync::Adts, + Codec::AacLatm => AudioSync::Loas, + Codec::Ac3 | Codec::Eac3 => AudioSync::Ac3, + _ => return None, + }; + frame_len(sync, b) +} + +/// Sample rate, channels and samples of the audio frame whose header starts `b` (the codecs of +/// [`frame_bytes`] except LATM), or `None` without a valid header there. +pub fn frame_info(codec: &Codec, b: &[u8]) -> Option { + match codec { + Codec::MpegAudio => { + let (_, sample_rate, samples) = mpa_header(b)?; + let layer = 4 - ((b[1] >> 1) & 3); + Some(FrameInfo { sample_rate, channels: if b[3] >> 6 == 3 { 1 } else { 2 }, samples, variant: layer }) + } + Codec::AacAdts => { + frame_len(AudioSync::Adts, b)?; + let sf = ((b[2] >> 2) & 15) as usize; + let ch = (((b[2] & 1) << 2) | (b[3] >> 6)) as u32; + Some(FrameInfo { + sample_rate: *ADTS_RATES.get(sf)?, + channels: if ch == 0 { + 2 + } else if ch == 7 { + 8 + } else { + ch + }, + samples: 1024 * ((b[6] & 3) as u32 + 1), + variant: (b[2] >> 6) + 1, + }) + } + Codec::Ac3 | Codec::Eac3 => { + frame_len(AudioSync::Ac3, b)?; + let bsid = b[5] >> 3; + if bsid > 10 { + // E-AC-3: fscod(2) numblkscod(2) acmod(3) lfeon(1) + let fscod = b[4] >> 6; + let (rate, blocks) = if fscod == 3 { + // fscod2 3 is reserved (no sample rate) + (*[24_000, 22_050, 16_000].get(((b[4] >> 4) & 3) as usize)?, 6) + } else { + ([48_000, 44_100, 32_000][fscod as usize], [1, 2, 3, 6][((b[4] >> 4) & 3) as usize]) + }; + let acmod = (b[4] >> 1) & 7; + return Some(FrameInfo { + sample_rate: rate, + channels: AC3_CHANNELS[acmod as usize] + (b[4] & 1) as u32, + samples: 256 * blocks, + variant: bsid, + }); + } + let fscod = b[4] >> 6; + let rate = *[48_000u32, 44_100, 32_000].get(fscod as usize)?; + // bsi: bsid(5) bsmod(3) acmod(3) [cmixlev(2)] [surmixlev(2)] [dsurmod(2)] lfeon(1) + let b6 = *b.get(6)?; + let acmod = b6 >> 5; + let mut bit = 3; // bits of byte 6 consumed + if acmod & 1 != 0 && acmod != 1 { + bit += 2; + } + if acmod & 4 != 0 { + bit += 2; + } + if acmod == 2 { + bit += 2; + } + let word = u16::from_be_bytes([b6, *b.get(7)?]); + let lfe = (word >> (15 - bit)) & 1; + Some(FrameInfo { sample_rate: rate, channels: AC3_CHANNELS[acmod as usize] + lfe as u32, samples: 1536, variant: bsid }) + } + _ => None, + } +} + +/// Whether the syncframe at the start of `b` is E-AC-3 (bsid 11-16) other than independent +/// substream 0: a dependent substream (strmtyp 1) or another program (A/52 §E2.3.1.1-2). +fn eac3_joins_unit(b: &[u8]) -> bool { + match b.get(2..6) { + Some(&[b2, _, _, b5]) => (11..=16).contains(&(b5 >> 3)) && (b2 >> 6 == 1 || (b2 >> 3) & 7 != 0), + _ => false, + } +} + +/// Bytes of an SEI NAL scanned for a recovery point message; a longer NAL is judged by its start. +const SEI_WINDOW: usize = 2048; + +/// Whether an H.264 SEI NAL (`nal` is the NAL header byte and the payload, as in the stream) +/// holds a recovery point message (payloadType 6, H.264 D.1.7) with recovery_frame_cnt 0. +pub fn sei_has_recovery_point(nal: &[u8]) -> bool { + // undo emulation prevention so that payload sizes are in RBSP bytes + let mut b = Vec::with_capacity(nal.len()); + let mut zeros = 0; + for &x in nal.iter().skip(1) { + if zeros >= 2 && x == 3 { + zeros = 0; + continue; + } + zeros = if x == 0 { zeros + 1 } else { 0 }; + b.push(x); + } + // payloadType / payloadSize: bytes of 0xFF followed by the last byte + let read = |i: &mut usize| { + let mut v = 0usize; + while let Some(&x) = b.get(*i) { + *i += 1; + v = v.saturating_add(x as usize); + if x != 0xFF { + break; + } + } + v + }; + let mut i = 0; + // each message takes at least two bytes, so the loop ends at the end of the NAL + while i + 2 <= b.len() { + let ty = read(&mut i); + let size = read(&mut i); + // recovery_frame_cnt is ue(v): a leading 1 bit is the value 0, i.e. decoding from here is + // correct at once. A count above 0 (gradual intra refresh) is not a safe seek point. + if ty == 6 && b.get(i).is_some_and(|x| x & 0x80 != 0) { + return true; + } + i = i.saturating_add(size); + } + false +} + +/// Shortest E-AC-3 syncframe accepted. A real syncframe holds the 6 header bytes read here plus +/// bsi and audio blocks (the smallest real ones are tens of bytes), so shorter "frames" +/// (`0B 77 00 01` is 4 bytes) are noise; they would otherwise turn every 4 input bytes into a +/// 64-byte `Unit`. +const EAC3_MIN_FRAME: usize = 8; + +/// Most units one stream may index. A `Unit` is 64 bytes, so this bounds a stream's table to +/// 512 MiB. It is 47 hours of 48 kHz AAC (the densest audio, 46.9 units/s), 9 hours of 240 fps +/// video: far beyond any real file, while a hostile file (a unit per 7 input bytes) cannot grow +/// the table without limit. +pub(crate) const MAX_UNITS: usize = 1 << 23; + +/// Full-bandwidth channels per AC-3 audio coding mode (A/52 Table 5.8). +const AC3_CHANNELS: [u32; 8] = [2, 1, 2, 3, 3, 4, 4, 5]; + +/// Frame length at the start of `b` for the given sync type (`None`: no valid header; `Some(0)` +/// is never returned). +fn frame_len(sync: AudioSync, b: &[u8]) -> Option { + match sync { + AudioSync::Mpa => mpa_header(b).map(|h| h.0), + AudioSync::Adts => { + if b.len() < 7 || b[0] != 0xFF || b[1] & 0xF6 != 0xF0 { + return None; + } + let len = ((b[3] as usize & 3) << 11) | (b[4] as usize) << 3 | (b[5] as usize) >> 5; + (len >= 7).then_some(len) + } + AudioSync::Loas => { + if b.len() < 3 || b[0] != 0x56 || b[1] & 0xE0 != 0xE0 { + return None; + } + let len = ((b[1] as usize & 0x1F) << 8) | b[2] as usize; + (len > 0).then_some(len + 3) + } + AudioSync::Ac3 => { + if b.len() < 6 || b[0] != 0x0B || b[1] != 0x77 { + return None; + } + let bsid = b[5] >> 3; + if bsid <= 10 { + ac3_frame_bytes(b[4] >> 6, b[4] & 0x3F) + } else if bsid <= 16 { + // E-AC-3: frmsiz + let len = ((((b[2] & 7) as usize) << 8) | b[3] as usize) * 2 + 2; + (len >= EAC3_MIN_FRAME).then_some(len) + } else { + None + } + } + } +} + +impl Splitter { + pub fn new(codec: &Codec) -> Splitter { + Splitter { + mode: Mode::of(codec), + es_pos: 0, + chunks: VecDeque::new(), + pes: VecDeque::new(), + buf: Vec::new(), + buf_start: 0, + open: None, + units: Vec::new(), + skipped: 0, + truncated: false, + max_units: MAX_UNITS, + header_start: None, + seq_in_unit: false, + gop: None, + pending: None, + open_field: None, + next_frame: None, + } + } + + /// A PES packet starts (its payload follows in the next chunks). + pub fn pes_start(&mut self, pts: Option, dts: Option) { + self.pes.push_back(PesMark { es_start: self.es_pos, pts, dts, used: false }); + while self.pes.len() > 64 { + self.pes.pop_front(); + } + match self.mode { + Mode::Pes => self.begin_pes_unit(true), + Mode::Nal { .. } => self.begin_pes_unit(pts.is_some() || dts.is_some()), + _ => {} + } + } + + /// PES-delimited units: a packet with a timestamp (or any packet in plain PES mode) starts a + /// new unit; one without continues the previous unit. + fn begin_pes_unit(&mut self, new: bool) { + if !new && self.open.is_some() { + return; + } + let at = self.es_pos; + self.close(at); + // the chunk of this position arrives with the next feed: resolved there + let mut o = Open { start: at, pos: u64::MAX, offset: 0, pts: None, dts: None, key: false, disposable: false, vcl: false, picture: None }; + if let Some((pts, dts)) = self.timestamps_at(at) { + o.pts = pts; + o.dts = dts; + } + if self.mode == Mode::Pes { + o.key = true; + } + self.open = Some(o); + } + + /// The unused timestamps of the PES packet holding `at` (consumed). + fn timestamps_at(&mut self, at: u64) -> Option<(Option, Option)> { + let m = self.pes.iter_mut().rev().find(|m| m.es_start <= at)?; + if m.used || (m.pts.is_none() && m.dts.is_none()) { + return None; + } + m.used = true; + Some((m.pts, m.dts)) + } + + /// Reader position and offset of elementary-stream byte `at`. + fn locate(&self, at: u64) -> Option<(u64, u32)> { + let c = self.chunks.iter().rev().find(|c| c.1 <= at)?; + Some((c.0, (at - c.1) as u32)) + } + + /// End the open unit at `end`. + fn close(&mut self, end: u64) { + let Some(o) = self.open.take() else { return }; + if end <= o.start || o.pos == u64::MAX { + return; + } + if self.units.len() >= self.max_units { + self.truncated = true; + return; + } + let size = (end - o.start).min(u32::MAX as u64) as u32; + self.units.push(Unit { + pts: o.pts, + dts: o.dts, + key: o.key, + disposable: o.disposable, + size, + pos: o.pos, + offset: o.offset, + picture: o.picture, + }); + } + + /// Payload bytes of one chunk (`pos`: where the reader restarts to find them). + pub fn feed(&mut self, pos: u64, data: &[u8]) { + if data.is_empty() { + return; + } + // PES-delimited modes resolve a unit's position from `pos` right here and never look a + // chunk up again, so remembering chunks there would only grow without bound (NAL streams + // keep theirs: an access unit can start inside a PES; `keep_from` prunes them) + if matches!(self.mode, Mode::MpegVideo | Mode::Audio(_) | Mode::Nal { .. }) { + self.chunks.push_back((pos, self.es_pos)); + } + if let Some(o) = self.open.as_mut() + && o.pos == u64::MAX + && o.start == self.es_pos + { + o.pos = pos; + o.offset = 0; + } + let start = self.es_pos; + self.es_pos += data.len() as u64; + match self.mode { + Mode::Pes => {} + Mode::Nal { hevc } => self.scan_nal(start, data, hevc), + Mode::MpegVideo => self.scan_mpeg(start, data), + Mode::Audio(sync) => self.scan_audio(start, data, sync), + } + // forget chunks no pending position can refer to + let keep_from = self.buf_start.min(self.pending.map_or(u64::MAX, |p| p.unit_start.min(p.at))).min(self.header_start.unwrap_or(u64::MAX)); + while self.chunks.len() > 2 && self.chunks[1].1 <= keep_from { + self.chunks.pop_front(); + } + } + + /// Append to the window and return it with its start. + fn window(&mut self, start: u64, data: &[u8]) { + if self.buf.is_empty() || self.buf_start + self.buf.len() as u64 != start { + self.buf.clear(); + self.buf_start = start; + } + self.buf.extend_from_slice(data); + } + + /// Keep only the last `keep` bytes of the window. + fn trim(&mut self, keep: usize) { + if self.buf.len() > keep { + let drop = self.buf.len() - keep; + self.buf.drain(..drop); + self.buf_start += drop as u64; + } + } + + /// Start codes in the window from index `from`: (window index of `00 00 01`, code). + fn next_start_code(&self, from: usize) -> Option { + let b = &self.buf; + let mut i = from; + while i + 3 <= b.len() { + match b[i + 2] { + 1 if b[i] == 0 && b[i + 1] == 0 => return Some(i), + 0 => i += 1, + _ => i += 3, + } + } + None + } + + fn scan_nal(&mut self, start: u64, data: &[u8], hevc: bool) { + self.window(start, data); + let mut i = 0; + let mut blocked = None; + while let Some(k) = self.next_start_code(i) { + // NAL header byte(s) and the first byte of the slice header needed + if k + if hevc { 6 } else { 5 } > self.buf.len() { + blocked = Some(k); + break; + } + // a four-byte start code begins with the zero_byte that belongs to its NAL + let at = self.buf_start + k as u64 - (k > 0 && self.buf.get(k - 1) == Some(&0)) as u64; + let (Some(&h), Some(&h1)) = (self.buf.get(k + 3), self.buf.get(k + if hevc { 5 } else { 4 })) else { + blocked = Some(k); + break; + }; + let (key, vcl, non_ref, au_start) = if hevc { + let t = (h >> 1) & 0x3F; + ( + (16..=23).contains(&t), + t < 32, + // sub-layer non-reference pictures (TRAIL_N, TSA_N, STSA_N, RADL_N, RASL_N) + t < 16 && t.is_multiple_of(2), + // first_slice_segment_in_pic_flag, or a NAL that precedes the first slice + // (VPS, SPS, PPS, AUD, prefix SEI, 41..=44, 48..=55; H.265 7.4.2.4.4) + if t < 32 { h1 & 0x80 != 0 } else { matches!(t, 32..=35 | 39 | 41..=44 | 48..=55) }, + ) + } else { + let t = h & 0x1F; + ( + t == 5, + (1..=5).contains(&t), + h & 0x60 == 0, + // first_mb_in_slice == 0 (ue(v) "1"), or a NAL that precedes the first slice + // (SEI, SPS, PPS, AUD, 14..=18; H.264 7.4.1.2.3) + match t { + 1 | 2 | 5 => h1 & 0x80 != 0, + 6..=9 | 14..=18 => true, + _ => false, + }, + ) + }; + let mut recovery = false; + if !hevc && h & 0x1F == 6 { + // the whole SEI NAL is needed to find a recovery point message among others + let end = self.next_start_code(k + 3); + if end.is_none() && self.buf.len() - k < SEI_WINDOW { + blocked = Some(k); + break; + } + let nal = self.buf.get(k + 3..end.unwrap_or(self.buf.len())).unwrap_or(&[]); + recovery = sei_has_recovery_point(nal); + } + // a unit holds one access unit: a new one starts at the first NAL that cannot belong + // to the slices already seen (a unit opened later than this NAL is left alone) + if au_start && self.open.as_ref().is_some_and(|o| o.vcl && at > o.start) { + self.begin_access_unit(at); + } + if let Some(o) = self.open.as_mut() + && at >= o.start + { + // a recovery point is a random-access point (the pictures before its recovery + // frame count completes may be imperfect) + o.key |= recovery; + if vcl { + o.key |= key; + // disposable while every slice is non-reference + o.disposable = if o.vcl { o.disposable && non_ref } else { non_ref }; + o.vcl = true; + } + } + i = k + 3; + } + self.keep_tail(i, blocked); + } + + /// Close the open unit and start the next access unit at `at`: it has no timestamp (the PES + /// timestamps belong to the first access unit of the packet). + fn begin_access_unit(&mut self, at: u64) { + self.close(at); + let (pos, offset) = self.locate(at).unwrap_or((u64::MAX, 0)); + self.open = Some(Open { start: at, pos, offset, pts: None, dts: None, key: false, disposable: false, vcl: false, picture: None }); + } + + /// Drop the scanned part of the window: keep from a start code waiting for more bytes, or + /// the last bytes a split start code may begin in. + fn keep_tail(&mut self, i: usize, blocked: Option) { + let len = self.buf.len(); + let resume = blocked.unwrap_or_else(|| i.max(len.saturating_sub(3))); + self.trim(len - resume.min(len)); + } + + fn scan_mpeg(&mut self, start: u64, data: &[u8]) { + self.window(start, data); + let mut i = 0; + let mut blocked = None; + while let Some(k) = self.next_start_code(i) { + // up to 5 bytes after the code are inspected + if k + 9 > self.buf.len() { + blocked = Some(k); + break; + } + let at = self.buf_start + k as u64; + let code = self.buf[k + 3]; + let p = [self.buf[k + 4], self.buf[k + 5], self.buf[k + 6], self.buf[k + 7], self.buf[k + 8]]; + match code { + 0xB3 => { + self.settle_pending(); + self.header_start.get_or_insert(at); + self.seq_in_unit = true; + } + 0xB8 => { + self.settle_pending(); + self.header_start.get_or_insert(at); + self.gop = Some((p[3] & 0x40 != 0, p[3] & 0x20 != 0)); + } + 0x00 => { + self.settle_pending(); + let info = PictureInfo { + coding_type: (p[1] >> 3) & 7, + temporal_reference: ((p[0] as u16) << 2) | (p[1] >> 6) as u16, + structure: 3, + progressive_frame: true, + sequence_header: self.seq_in_unit, + gop: self.gop.is_some(), + closed_gop: self.gop.is_some_and(|g| g.0), + broken_link: self.gop.is_some_and(|g| g.1), + ..Default::default() + }; + let unit_start = self.header_start.take().unwrap_or(at); + self.seq_in_unit = false; + self.gop = None; + self.pending = Some(PendingPicture { unit_start, at, info }); + } + 0xB5 if p[0] >> 4 == 8 => { + if let Some(pp) = self.pending.as_mut() { + pp.info.structure = p[2] & 3; + pp.info.top_field_first = p[3] & 0x80 != 0; + pp.info.repeat_first_field = p[3] & 0x02 != 0; + pp.info.progressive_frame = p[4] & 0x80 != 0; + } + self.settle_pending(); + } + 0xB5 | 0xB2 => {} + _ => self.settle_pending(), + } + i = k + 3; + } + self.keep_tail(i, blocked); + } + + /// A picture's structure is known: start a unit, or join a first field. + fn settle_pending(&mut self) { + let Some(pp) = self.pending.take() else { return }; + let s = pp.info.structure; + if let Some(first) = self.open_field + && s != 3 + && first != s + && s != 0 + { + self.open_field = None; + return; + } + self.close(pp.unit_start); + let (pos, offset) = self.locate(pp.unit_start).unwrap_or((u64::MAX, 0)); + let mut o = Open { + start: pp.unit_start, + pos, + offset, + pts: None, + dts: None, + key: matches!(pp.info.coding_type, 1 | 4), + disposable: pp.info.coding_type == 3, + vcl: true, + picture: Some(pp.info), + }; + if let Some((pts, dts)) = self.timestamps_at(pp.at) { + o.pts = pts; + o.dts = dts; + } + self.open = Some(o); + self.open_field = (s == 1 || s == 2).then_some(s); + } + + fn scan_audio(&mut self, start: u64, data: &[u8], sync: AudioSync) { + let end = start + data.len() as u64; + // skip whole chunks inside the current frame + if let Some(n) = self.next_frame + && n >= end + { + return; + } + self.window(start, data); + loop { + let at = match self.next_frame { + Some(n) if n >= self.buf_start => n, + _ => self.buf_start, + }; + let i = (at - self.buf_start) as usize; + if i + 8 > self.buf.len() { + // not enough bytes for a header yet + self.trim(self.buf.len().saturating_sub(i)); + return; + } + match frame_len(sync, &self.buf[i..]) { + Some(len) if self.next_frame == Some(at) || self.confirmed(sync, i, len) => { + // an E-AC-3 dependent substream or further program joins the access unit of + // the independent substream 0 before it, as in MP4 and Matroska + if !(sync == AudioSync::Ac3 && self.open.is_some() && eac3_joins_unit(&self.buf[i..])) { + self.close(at); + let (pos, offset) = self.locate(at).unwrap_or((u64::MAX, 0)); + let mut o = Open { start: at, pos, offset, pts: None, dts: None, key: true, disposable: false, vcl: false, picture: None }; + if let Some((pts, dts)) = self.timestamps_at(at) { + o.pts = pts; + o.dts = dts; + } + self.open = Some(o); + } + self.next_frame = Some(at + len as u64); + if at + len as u64 >= self.buf_start + self.buf.len() as u64 { + self.buf.clear(); + self.buf_start = at + len as u64; + return; + } + } + _ => { + // lost sync: look for the next header from the following byte + self.next_frame = None; + self.skipped += 1; + let next = self.buf[i + 1..].iter().position(|&b| { + matches!((sync, b), (AudioSync::Ac3, 0x0B) | (AudioSync::Loas, 0x56) | (AudioSync::Mpa | AudioSync::Adts, 0xFF)) + }); + match next { + Some(d) => { + self.skipped += d as u64; + // Keep a cursor into the current window rather than draining its + // prefix for every false sync candidate. + self.next_frame = Some(at + 1 + d as u64); + } + None => { + self.skipped += (self.buf.len() - i - 1) as u64; + // A split header can begin in the final few bytes; compact once. + self.trim(7); + return; + } + } + } + } + } + } + + /// A header found while hunting for sync is accepted when the next frame's header follows + /// it (or the data ends before it). + fn confirmed(&self, sync: AudioSync, i: usize, len: usize) -> bool { + let j = i + len; + if j + 8 > self.buf.len() { + return true; + } + frame_len(sync, &self.buf[j..]).is_some() + } + + /// End of stream: close the open unit. + pub fn finish(&mut self) { + self.settle_pending(); + let end = match (self.mode, self.next_frame) { + (Mode::Audio(_), Some(n)) => n.min(self.es_pos), + _ => self.es_pos, + }; + if let (Mode::Audio(_), Some(o)) = (self.mode, self.open) { + // a truncated last frame is dropped + if self.next_frame.is_some_and(|n| n > self.es_pos) { + self.skipped += self.es_pos - o.start; + self.open = None; + } + } + self.close(end); + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn audio_frame_sizes() { + // MPEG-1 layer II 48 kHz 192 kb/s: 576 bytes; layer III 44.1 kHz 128 kb/s with padding: 418 + assert_eq!(mpa_header(&[0xFF, 0xFD, 0xA4, 0x00]), Some((576, 48_000, 1152))); + assert_eq!(mpa_header(&[0xFF, 0xFB, 0x92, 0x00]), Some((418, 44_100, 1152))); + // MPEG-2 layer III 24 kHz 64 kb/s: 192 bytes, 576 samples + assert_eq!(mpa_header(&[0xFF, 0xF3, 0x84, 0x00]), Some((192, 24_000, 576))); + // AC-3 448 kb/s at 48 kHz = 1792 bytes; 44.1 kHz 192 kb/s odd code = 836 bytes + assert_eq!(ac3_frame_bytes(0, 30), Some(1792)); + assert_eq!(ac3_frame_bytes(1, 21), Some(836)); + assert_eq!(ac3_frame_bytes(2, 0), Some(192)); + } + + #[test] + fn eac3_dependent_substreams_join_the_access_unit() { + // 16-byte E-AC-3 syncframes (frmsiz 7), 48 kHz six blocks stereo: independent, dependent + // (7.1 extension), independent, dependent + let frame = |strmtyp: u8| { + let mut f = vec![0x0B, 0x77, strmtyp << 6, 7, (3 << 4) | (2 << 1), 16 << 3]; + f.resize(16, 0); + f + }; + let es: Vec = [frame(0), frame(1), frame(0), frame(1)].concat(); + let mut s = Splitter::new(&Codec::Eac3); + s.feed(0, &es); + s.finish(); + assert_eq!(s.units.iter().map(|u| u.size).collect::>(), vec![32, 32]); + assert_eq!(frame_info(&Codec::Eac3, &es).map(|f| f.samples), Some(1536)); + // AC-3 frames are never joined + assert!(!eac3_joins_unit(&[0x0B, 0x77, 0x40, 0, 0, 8 << 3])); + } + + #[test] + fn ac3_header_prefix_of_six_bytes_is_not_indexed_out_of_bounds() { + // exactly the six bytes frame_len() guarantees: byte 6 (acmod) is missing + assert_eq!(frame_info(&Codec::Ac3, &[0x0B, 0x77, 0, 0, 0x1E, 0x40]), None); + assert_eq!(frame_info(&Codec::Ac3, &[0x0B, 0x77, 0, 0, 0x1E, 0x40, 0]), None); + } + + #[test] + fn eac3_reserved_sample_rate_is_refused() { + // fscod 3 and fscod2 3: no sample rate + let mut f = vec![0x0B, 0x77, 0, 7, 0xF0, 16 << 3]; + f.resize(16, 0); + assert_eq!(frame_info(&Codec::Eac3, &f), None); + f[4] = 0xE0; // fscod2 2: 16 kHz + assert_eq!(frame_info(&Codec::Eac3, &f).map(|i| i.sample_rate), Some(16_000)); + } + + #[test] + fn four_byte_eac3_frames_make_no_units() { + let es: Vec = [0x0B, 0x77, 0x00, 0x01].repeat(10_000); + let mut s = Splitter::new(&Codec::Eac3); + s.feed(0, &es); + s.finish(); + assert!(s.units.is_empty(), "{} units from 40000 noise bytes", s.units.len()); + } + + #[test] + fn pes_delimited_modes_do_not_retain_chunks() { + for codec in [Codec::LpcmBluray, Codec::Unknown(0x99)] { + let mut s = Splitter::new(&codec); + for k in 0..5000u64 { + s.pes_start(Some(k as i64), None); + s.feed(k * 188, &[0x11; 184]); + } + s.finish(); + assert!(s.chunks.len() <= 2, "{codec:?}: {} chunks retained", s.chunks.len()); + assert_eq!(s.units.len(), 5000, "{codec:?}"); + assert!(s.units.iter().enumerate().all(|(k, u)| u.pos == k as u64 * 188 && u.offset == 0), "{codec:?}"); + } + } + + #[test] + fn unit_table_is_capped() { + let frame = |k: u8| { + let mut v = vec![0x0B, 0x77, 0, 7, (3 << 4) | (2 << 1), 16 << 3]; + v.resize(16, k); + v + }; + let mut s = Splitter::new(&Codec::Eac3); + s.max_units = 10; + let es: Vec = (0..100).flat_map(frame).collect(); + s.feed(0, &es); + s.finish(); + assert_eq!(s.units.len(), 10); + assert!(s.truncated); + } +} diff --git a/crates/media/src/mpegts/hostile_tests.rs b/crates/media/src/mpegts/hostile_tests.rs new file mode 100644 index 000000000..3990acaef --- /dev/null +++ b/crates/media/src/mpegts/hostile_tests.rs @@ -0,0 +1,209 @@ +//! Hostile input: streams of every codec filled with start codes and sync words at random, +//! damaged containers, and the public frame-header helpers on arbitrary bytes. Errors and empty +//! tables are fine; a panic (an index out of range, an overflow in a debug build) is not. + +use super::tests::{TsMux, pes}; +use super::*; + +/// Deterministic xorshift. +struct Rng(u64); + +impl Rng { + fn next(&mut self) -> u64 { + self.0 ^= self.0 << 13; + self.0 ^= self.0 >> 7; + self.0 ^= self.0 << 17; + self.0 + } + fn below(&mut self, n: usize) -> usize { + (self.next() % n.max(1) as u64) as usize + } +} + +/// Random bytes with the patterns the splitters look for scattered through them: start codes of +/// every kind, MPEG audio / ADTS / LOAS / AC-3 sync words, with header bytes at the extremes. +/// At least one byte, at most about `max`. +fn soup(r: &mut Rng, max: usize) -> Vec { + let n = 1 + r.below(max); + let mut v = Vec::with_capacity(n + 16); + while v.len() < n { + let edge = [0x00u8, 0xFF, 0x80, 0x7F, r.next() as u8][r.below(5)]; + match r.below(12) { + 0 => v.extend([0, 0, 1, r.next() as u8]), + 1 => v.extend([0, 0, 1, [0x00, 0xB3, 0xB5, 0xB8, 0x09, 0x65, 0x41, 0x06, 0x26, 0x40, 0x46][r.below(11)], edge, edge]), + 2 => v.extend([0, 0, 0, 1, r.next() as u8, edge]), + 3 => v.extend([0xFF, 0xF0 | (r.next() as u8 & 0x0F), r.next() as u8, edge, edge, edge, edge]), + 4 => v.extend([0x0B, 0x77, edge, edge, r.next() as u8, r.next() as u8, edge]), + 5 => v.extend([0x56, 0xE0 | (r.next() as u8 & 0x1F), r.next() as u8]), + 6 => v.extend([edge; 3]), + _ => v.push(r.next() as u8), + } + } + v +} + +/// Opens and reads; returns how many units the tables hold. +fn open_and_read_all(data: &[u8]) -> usize { + let Ok(f) = open(data) else { return 0 }; + let _ = (f.format.name(), f.pcr_range); + for (s, st) in f.streams.iter().enumerate() { + let _ = (st.codec_params(), st.codec.name(), st.pts_range()); + let n = st.units.len(); + // every unit of a small table, a spread of a large one + for i in (0..n).step_by((n / 64).max(1)).chain(n.checked_sub(1)) { + let _ = f.read_unit(data, s, i); + } + } + let _ = f.read_unit(data, f.streams.len(), 0); + f.streams.iter().map(|s| s.units.len()).sum() +} + +/// Every stream type the PMT maps, each on its own PID. +const TYPES: [u8; 16] = [0x01, 0x02, 0x03, 0x04, 0x0F, 0x11, 0x1B, 0x24, 0x80, 0x81, 0x83, 0x84, 0x87, 0x90, 0x06, 0x42]; + +fn soup_ts(r: &mut Rng, m2ts: bool, packets: usize) -> Vec { + let mut mux = TsMux::new(m2ts); + let streams: Vec<(u8, u16)> = TYPES.iter().enumerate().map(|(i, &t)| (t, 0x200 + i as u16)).collect(); + mux.psi(&streams); + for _ in 0..packets { + let (_, pid) = streams[r.below(streams.len())]; + let payload = soup(r, 700); + let pts = (r.below(3) > 0).then(|| r.next() as i64 & ((1 << 33) - 1)); + let dts = pts.filter(|_| r.below(2) == 0).map(|p| p.wrapping_sub(3600) & ((1 << 33) - 1)); + mux.pes(pid, &pes([0xE0, 0xC0, 0xBD, 0xFD][r.below(4)], pts, dts, &payload, r.below(2) == 0)); + } + mux.out +} + +fn soup_ps(r: &mut Rng, mpeg1: bool, packets: usize) -> Vec { + let mut out = Vec::new(); + for _ in 0..packets { + if mpeg1 { + out.extend([0, 0, 1, 0xBA, 0x21, 0, 1, 0, 1, 0x80, 0, 1]); + } else { + out.extend([0, 0, 1, 0xBA, 0x44, 0, 4, 0, 4, 1, 1, 0x89, 0xC3, 0xF8 | r.below(8) as u8]); + out.extend(std::iter::repeat_n(0xFF, r.below(8))); + } + let mut payload = soup(r, 1500); + let id = [0xE0, 0xE1, 0xC0, 0xC1, 0xBD, 0xBD, 0xBD, 0xBB, 0xBC, 0xBE, 0xBF][r.below(11)]; + if id == 0xBD { + // DVD sub-streams: AC-3, DTS, LPCM (every format byte), sub-pictures + payload[0] = [0x80, 0x88, 0xA0, 0xA1, 0x20, r.next() as u8][r.below(6)]; + } + let pts = (r.below(3) > 0).then(|| r.next() as i64 & ((1 << 33) - 1)); + out.extend(pes(id, pts, None, &payload, true)); + } + out.extend([0, 0, 1, 0xB9]); + out +} + +#[test] +fn streams_of_start_codes_and_sync_words_never_panic() { + let mut r = Rng(0x1234_5678_9ABC_DEF1); + let (mut ts, mut ps) = (0, 0); + for round in 0..40 { + ts += open_and_read_all(&soup_ts(&mut r, round % 2 == 1, 150)); + ps += open_and_read_all(&soup_ps(&mut r, round % 2 == 1, 60)); + } + // the streams reach the splitters: they are cut into units, not rejected up front + assert!(ts > 2000 && ps > 500, "{ts} transport stream units, {ps} program stream units"); +} + +#[test] +fn damaged_containers_never_panic() { + let mut r = Rng(0xDEAD_BEEF_0BAD_F00D); + let bases = [soup_ts(&mut r, false, 60), soup_ts(&mut r, true, 60), soup_ps(&mut r, false, 40), soup_ps(&mut r, true, 40)]; + for base in &bases { + for _ in 0..300 { + let mut d = base.clone(); + for _ in 0..1 + r.below(24) { + let at = r.below(d.len()); + // header bytes at their extremes, lengths that run past the packet, lost sync + d[at] = [0x00, 0xFF, 0x47, 0x01, 0x80, 0xBA, r.next() as u8][r.below(7)]; + } + match r.below(4) { + 0 => d.truncate(r.below(d.len())), + // a run cut out of the middle: the packet grid shifts + 1 => { + let at = r.below(d.len()); + d.drain(at..(at + r.below(300)).min(d.len())); + } + _ => {} + } + open_and_read_all(&d); + } + } +} + +/// Program-specific information with every length field wrong. +#[test] +fn damaged_psi_sections_never_panic() { + let mut r = Rng(0x0F0F_1234_5555_AAAA); + for _ in 0..3000 { + let mut mux = TsMux::new(false); + // sections the muxer signs with a valid CRC, so the parsers see the damage + let mut pat = vec![0x00, 0xB0, 13, 0, 1, 0xC1, 0, 0, 0, 1, 0xE1, 0x00]; + let mut pmt = vec![0x02, 0xB0, 0, 0, 1, 0xC1, 0, 0, 0xE1, 0x00, 0xF0, 0]; + for _ in 0..r.below(6) { + pmt.extend([TYPES[r.below(TYPES.len())], 0xE2, r.next() as u8, 0xF0 | r.below(16) as u8, r.next() as u8]); + pmt.extend(soup(&mut r, 12)); + } + let len = pmt.len() - 3 + 4; + pmt[1] = 0xB0 | (len >> 8) as u8; + pmt[2] = len as u8; + for sec in [&mut pat, &mut pmt] { + for _ in 0..r.below(3) { + let at = r.below(sec.len()); + sec[at] = [0x00, 0xFF, 0x0F, 0xF0, r.next() as u8][r.below(5)]; + } + } + mux.section(0, &pat); + mux.section(0x100, &pmt); + for i in 0..8u16 { + mux.pes(0x200 + i, &pes(0xE0, Some(0), None, &soup(&mut r, 200), false)); + } + // enough packets for the sniffer + open_and_read_all(&mux.out); + } +} + +#[test] +fn frame_header_helpers_never_panic_on_any_bytes() { + let mut r = Rng(0x5EED_5EED_5EED_5EED); + let codecs = [Codec::MpegAudio, Codec::AacAdts, Codec::AacLatm, Codec::Ac3, Codec::Eac3, Codec::H264, Codec::LpcmDvd]; + for _ in 0..20_000 { + let b = soup(&mut r, 24); + for cut in 0..=b.len() { + let b = &b[..cut]; + for c in &codecs { + if let Some(n) = frame_bytes(c, b) { + assert!(n > 0, "{c:?}: an empty frame would never advance"); + } + let _ = frame_info(c, b); + } + let _ = (sei_has_recovery_point(b), pes::parse(b), sniff(b)); + let _ = ts::codec_of(b.first().copied().unwrap_or(6), b, cut % 2 == 0); + } + } + // every MPEG audio, ADTS and AC-3 header value in its first four bytes + for h in 0..=0xFFFFu32 { + for sync in [[0xFFu8, 0xE0], [0x0B, 0x77]] { + let b = [sync[0], sync[1] | (h >> 12) as u8, (h >> 4) as u8, (h << 4) as u8, h as u8, (h >> 8) as u8, 0xFF, 0x00]; + for c in &codecs[..5] { + let _ = (frame_bytes(c, &b), frame_info(c, &b)); + } + } + } +} + +/// A pack header is looked for behind at most 64 zero bytes. +#[test] +fn a_pack_header_behind_too_many_zero_bytes_is_not_sniffed() { + let pack = [0u8, 0, 1, 0xBA, 0x44, 0, 4, 0, 4, 1, 1, 0x89, 0xC3, 0xF8]; + let behind = |zeros: usize| [vec![0u8; zeros], pack.to_vec()].concat(); + assert_eq!(sniff(&behind(0)), Some(Format::Ps { mpeg1: false })); + assert_eq!(sniff(&behind(62)), Some(Format::Ps { mpeg1: false })); + assert_eq!(sniff(&behind(63)), None); + assert_eq!(sniff(&behind(5000)), None); + assert!(matches!(open(&behind(5000)), Err(Error::NotMpeg))); +} diff --git a/crates/media/src/mpegts/mod.rs b/crates/media/src/mpegts/mod.rs new file mode 100644 index 000000000..a0a62efa5 --- /dev/null +++ b/crates/media/src/mpegts/mod.rs @@ -0,0 +1,506 @@ +//! Clean-room MPEG-2 Systems demuxer (ITU-T H.222.0 | ISO/IEC 13818-1). +//! +//! - **Transport Stream**: 188-byte packets, 192-byte BDAV / AVCHD packets (`.m2ts`, `.mts`: +//! a 4-byte arrival timestamp before each packet) and 204-byte packets (Reed-Solomon parity). +//! PAT / PMT (sections reassembled across packets, CRC checked), PES reassembly, PCR, PTS/DTS +//! (33-bit wrap-around unwrapped), discontinuity indicators. +//! - **Program Stream** (`.mpg`, `.vob`, `.mod`, `.tod`): MPEG-2 and ISO/IEC 11172-1 (MPEG-1) +//! packs, system headers, program stream maps, DVD private stream 1 sub-streams (AC-3, DTS, +//! LPCM). +//! - **Elementary streams** are split into access units on open — coded frames for MPEG-1/2 +//! video (picture start codes, field pairs), H.264 and HEVC (access unit delimiters / first +//! slice of a picture), audio frames for MPEG audio, ADTS / LATM AAC, AC-3 and E-AC-3, PES +//! packets for LPCM — each with its PTS/DTS (a PES timestamp belongs to the first access unit +//! that starts in the packet), random-access flag and, for MPEG video, picture type, temporal +//! reference and field structure. That index is the seeking table. +//! - Units are read back on demand by re-reading the file from the unit's first packet, so the +//! index costs a few dozen bytes per access unit. +//! +//! The module does no decoding. No dependencies beyond `std`, no `unsafe`, builds for +//! `wasm32-unknown-unknown`. +//! +//! From FilmCraft's `filmcraft-mpegts` (storytold/filmcraft@4bec22b). Public items keep their names. +//! `ByteSource` is the crate's one source trait. + +#![warn(missing_docs)] + +mod es; +pub use es::{FrameInfo, frame_bytes, frame_info, sei_has_recovery_point}; +mod pes; +mod ps; +mod ts; + +use std::fmt; +use std::io; + +pub use crate::source::{ByteSource, ReadSeekSource}; + +/// Errors from reading a transport or program stream. +#[non_exhaustive] +#[derive(Debug)] +pub enum Error { + /// Neither a transport stream nor a program stream. + NotMpeg, + /// Reading the source failed. + Io(io::Error), + /// Structurally invalid data. + Invalid(String), +} + +impl fmt::Display for Error { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + Error::NotMpeg => write!(f, "not an MPEG transport or program stream"), + Error::Io(e) => write!(f, "I/O: {e}"), + Error::Invalid(s) => write!(f, "invalid stream: {s}"), + } + } +} + +impl std::error::Error for Error { + fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { + match self { + Error::Io(e) => Some(e), + _ => None, + } + } +} + +impl From for Error { + fn from(e: io::Error) -> Self { + Error::Io(e) + } +} + +/// Result alias for this module. +pub type Result = std::result::Result; + +/// Read as much as is available at `offset` (up to `buf.len()`); returns the count. +pub(crate) fn read_some(src: &S, offset: u64, buf: &mut [u8]) -> io::Result { + let len = src.len(); + if offset >= len { + return Ok(0); + } + let n = ((len - offset) as usize).min(buf.len()); + src.read_at(offset, &mut buf[..n])?; + Ok(n) +} + +/// The container layout. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Format { + /// Transport stream with `packet_size`-byte packets whose 0x47 sync byte is at `sync_offset` + /// (4 for 192-byte BDAV packets). + Ts { + /// 188, 192 or 204. + packet_size: usize, + /// Offset of the sync byte in a packet. + sync_offset: usize, + }, + /// Program stream (`mpeg1`: ISO/IEC 11172-1 packs). + Ps { + /// ISO/IEC 11172-1 packs. + mpeg1: bool, + }, +} + +impl Format { + /// A display name: `"MPEG-2 TS"`, `"MPEG-2 PS"`… + pub fn name(&self) -> &'static str { + match self { + Format::Ts { packet_size: 192, .. } => "MPEG-2 TS (BDAV/AVCHD)", + Format::Ts { .. } => "MPEG-2 TS", + Format::Ps { mpeg1: true } => "MPEG-1 System", + Format::Ps { mpeg1: false } => "MPEG-2 PS", + } + } +} + +/// Recognise a transport stream (five consecutive sync bytes at one of the packet sizes, within +/// the first packets) or a program stream (a pack header). +pub fn sniff(head: &[u8]) -> Option { + for (size, off) in [(188usize, 0usize), (192, 4), (204, 0)] { + for start in 0..size.min(head.len()) { + let ok = (0..5).all(|k| head.get(start + off + k * size) == Some(&0x47)); + if ok { + return Some(Format::Ts { packet_size: size, sync_offset: off }); + } + } + } + // a pack header, possibly after a few zero bytes + let z = head.iter().take(64).take_while(|&&b| b == 0).count(); + let p = z.saturating_sub(2); + if head.len() >= p + 5 && head[p..p + 4] == [0, 0, 1, 0xBA] { + return Some(Format::Ps { mpeg1: head[p + 4] >> 6 != 1 }); + } + None +} + +/// What kind of media a stream carries. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Kind { + /// Pictures. + Video, + /// Sound. + Audio, + /// Subtitles (PGS, DVB, teletext). + Subtitle, + /// Anything else. + Other, +} + +/// What an elementary stream carries. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum Codec { + /// MPEG-1 video (ISO/IEC 11172-2). + Mpeg1Video, + /// MPEG-2 video (H.262). + Mpeg2Video, + /// H.264 / AVC, Annex B. + H264, + /// H.265 / HEVC, Annex B. + Hevc, + /// MPEG-1/2 audio (layers I-III; the layer is in each frame header). + MpegAudio, + /// AAC in ADTS frames. + AacAdts, + /// AAC in LATM/LOAS frames. + AacLatm, + /// AC-3. + Ac3, + /// E-AC-3. + Eac3, + /// DTS. + Dts, + /// Dolby TrueHD. + TrueHd, + /// Blu-ray / AVCHD LPCM (a 4-byte header per PES packet, big-endian samples). + LpcmBluray, + /// DVD LPCM (program stream private stream 1; format in [`Stream::lpcm`]). + LpcmDvd, + /// Subtitles; the text names the format. + Subtitle(&'static str), + /// Anything else: the stream type. + Unknown(u8), +} + +impl Codec { + /// A display name: `"H.264"`, `"AAC (ADTS)"`, `"stream type 0x42"`. + pub fn name(&self) -> String { + match self { + Codec::Mpeg1Video => "MPEG-1 Video".into(), + Codec::Mpeg2Video => "MPEG-2 Video".into(), + Codec::H264 => "H.264".into(), + Codec::Hevc => "HEVC".into(), + Codec::MpegAudio => "MPEG Audio".into(), + Codec::AacAdts => "AAC (ADTS)".into(), + Codec::AacLatm => "AAC (LATM)".into(), + Codec::Ac3 => "AC-3".into(), + Codec::Eac3 => "E-AC-3".into(), + Codec::Dts => "DTS".into(), + Codec::TrueHd => "Dolby TrueHD".into(), + Codec::LpcmBluray => "LPCM (Blu-ray)".into(), + Codec::LpcmDvd => "LPCM (DVD)".into(), + Codec::Subtitle(s) => (*s).into(), + Codec::Unknown(t) => format!("stream type 0x{t:02x}"), + } + } + /// The crate-wide identifier. MPEG-1 video reports [`CodecId::Mpeg2Video`] (an MPEG-2 + /// decoder decodes it), MPEG audio reports [`CodecId::Mp2`] whatever its layer (the layer is + /// in each frame header: [`frame_info`]'s `variant`), and DTS, TrueHD and subtitles have no + /// identifier. + /// + /// [`CodecId::Mpeg2Video`]: crate::CodecId::Mpeg2Video + /// [`CodecId::Mp2`]: crate::CodecId::Mp2 + pub fn codec_id(&self) -> crate::CodecId { + use crate::CodecId as Id; + match self { + Codec::Mpeg1Video | Codec::Mpeg2Video => Id::Mpeg2Video, + Codec::H264 => Id::H264, + Codec::Hevc => Id::Hevc, + Codec::MpegAudio => Id::Mp2, + Codec::AacAdts | Codec::AacLatm => Id::Aac, + Codec::Ac3 => Id::Ac3, + Codec::Eac3 => Id::Eac3, + Codec::LpcmBluray | Codec::LpcmDvd => Id::Pcm, + Codec::Dts | Codec::TrueHd | Codec::Subtitle(_) | Codec::Unknown(_) => Id::Unknown, + } + } + + /// The kind of media. + pub fn kind(&self) -> Kind { + match self { + Codec::Mpeg1Video | Codec::Mpeg2Video | Codec::H264 | Codec::Hevc => Kind::Video, + Codec::MpegAudio + | Codec::AacAdts + | Codec::AacLatm + | Codec::Ac3 + | Codec::Eac3 + | Codec::Dts + | Codec::TrueHd + | Codec::LpcmBluray + | Codec::LpcmDvd => Kind::Audio, + Codec::Subtitle(_) => Kind::Subtitle, + Codec::Unknown(_) => Kind::Other, + } + } +} + +/// MPEG-1/2 video picture properties of an access unit (its first picture). +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] +pub struct PictureInfo { + /// 1 I, 2 P, 3 B, 4 D. + pub coding_type: u8, + /// `temporal_reference`: display order within the GOP. + pub temporal_reference: u16, + /// 1 top field, 2 bottom field, 3 frame (two field pictures form one unit). + pub structure: u8, + /// `top_field_first` of the picture coding extension. + pub top_field_first: bool, + /// `repeat_first_field` (pulldown). + pub repeat_first_field: bool, + /// `progressive_frame`. + pub progressive_frame: bool, + /// A sequence header precedes the picture in this unit. + pub sequence_header: bool, + /// A GOP header precedes the picture (and its flags). + pub gop: bool, + /// `closed_gop` of that GOP header. + pub closed_gop: bool, + /// `broken_link` of that GOP header. + pub broken_link: bool, +} + +/// One access unit (a coded frame, an audio frame, or an LPCM PES packet). +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct Unit { + /// Presentation / decoding time stamps, 90 kHz, 33-bit wrap-around unwrapped. + pub pts: Option, + /// See `pts`. + pub dts: Option, + /// Decoding can start here (I / IDR / IRAP pictures; every audio frame). + pub key: bool, + /// No other unit depends on it (B pictures of MPEG-1/2 video, non-reference H.264/HEVC). + pub disposable: bool, + /// Bytes of elementary stream. + pub size: u32, + /// TS: byte offset of the packet holding the first byte; PS: byte offset of its PES packet. + pub(crate) pos: u64, + /// Offset of the first byte within that packet's elementary-stream payload. + pub(crate) offset: u32, + /// MPEG-1/2 video: the picture's properties. + pub picture: Option, +} + +/// DVD LPCM format (from the private stream 1 header). +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct LpcmFormat { + /// Samples per second. + pub sample_rate: u32, + /// Channel count. + pub channels: u32, + /// Bits per sample (16, 20 or 24). + pub bits: u32, +} + +/// Where a stream's PES packets come from. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum StreamId { + /// Transport stream PID. + Pid(u16), + /// Program stream stream_id, and the private stream 1 sub-stream id. + Ps { + /// PES stream_id. + stream_id: u8, + /// Private stream 1 sub-stream id. + sub_id: Option, + }, +} + +/// One elementary stream and its access-unit table. +#[derive(Clone, Debug)] +pub struct Stream { + /// Where its PES packets come from. + pub id: StreamId, + /// PMT stream_type (TS), or the equivalent for program streams. + pub stream_type: u8, + /// What it carries. + pub codec: Codec, + /// ISO 639 language code from the PMT. + pub language: Option, + /// The access units, in stream order. + pub units: Vec, + /// DVD LPCM: the sample format. + pub lpcm: Option, + /// PES packets seen. + pub pes_packets: u64, + /// Bytes of payload ignored because the stream could not be split (e.g. before the first + /// frame header). + pub skipped_bytes: u64, +} + +impl Stream { + /// The kind of media. + pub fn kind(&self) -> Kind { + self.codec.kind() + } + /// What a decoder needs for this stream, in the container-neutral form the codec crates take: + /// the codec ([`Codec::codec_id`]) and, for DVD LPCM, the sample format (big-endian). These + /// streams carry their configuration in band, so `extradata` is empty: H.264 and HEVC are + /// Annex B with their parameter sets, AAC is ADTS or LATM frames, and a Blu-ray LPCM packet + /// starts with its own 4-byte format header. + pub fn codec_params(&self) -> crate::CodecParams { + let mut p = crate::CodecParams::new(self.codec.codec_id()); + if let Some(f) = self.lpcm { + let n = |v: u32| u16::try_from(v).unwrap_or(0); + p = p.with_sample_rate(f.sample_rate).with_channels(n(f.channels)).with_pcm(crate::PcmFormat::int(n(f.bits), true, true)); + } + p + } + /// First and last presentation timestamps (90 kHz) of the stream's units. + pub fn pts_range(&self) -> Option<(i64, i64)> { + let mut it = self.units.iter().filter_map(|u| u.pts); + let first = it.next()?; + Some(it.fold((first, first), |(a, b), p| (a.min(p), b.max(p)))) + } +} + +/// A demuxed file: its streams with their access-unit tables. +#[derive(Clone, Debug)] +pub struct File { + /// The container layout. + pub format: Format, + /// The elementary streams (TS: in PMT order). + pub streams: Vec, + /// Program number of the program the streams belong to (TS). + pub program: Option, + /// Smallest and largest PCR (27 MHz, unwrapped) or SCR. For a transport stream this is the + /// clock of the PMT's PCR_PID; without a PMT, of the first PID seen carrying a PCR. `None` if + /// that PID never carries one. + pub pcr_range: Option<(i64, i64)>, + /// Problems found while scanning (lost sync, CRC errors, continuity errors…). + pub warnings: Vec, +} + +/// Largest unit `read_unit` returns. The biggest real units are intra pictures (a few MB at +/// 4K/8K broadcast rates); a stream without PES timestamps can make one unit of a whole PID. +pub const MAX_UNIT_BYTES: u32 = 128 << 20; + +/// Bytes reserved up front by `read_unit`; the buffer grows beyond this only as data is read. +const UNIT_PREALLOC: usize = 1 << 20; + +impl File { + /// The first stream of `kind` whose codec satisfies `f`. + pub fn find(&self, kind: Kind, f: impl Fn(&Codec) -> bool) -> Option { + self.streams.iter().position(|s| s.kind() == kind && !s.units.is_empty() && f(&s.codec)) + } + + /// Read access unit `i` of stream `s`. + pub fn read_unit(&self, src: &S, s: usize, i: usize) -> Result> { + let st = self.streams.get(s).ok_or_else(|| Error::Invalid("no such stream".into()))?; + let u = st.units.get(i).ok_or_else(|| Error::Invalid("no such unit".into()))?; + if u.size > MAX_UNIT_BYTES { + return Err(Error::Invalid(format!("unit {i} is {} bytes (limit {MAX_UNIT_BYTES})", u.size))); + } + // grow as bytes arrive: a damaged table must not reserve more than the file can supply + let mut out = Vec::with_capacity((u.size as usize).min(UNIT_PREALLOC)); + match self.format { + Format::Ts { packet_size, sync_offset } => ts::read(src, packet_size, sync_offset, st, u, &mut out)?, + Format::Ps { .. } => ps::read(src, st, u, &mut out)?, + } + if out.len() < u.size as usize { + return Err(Error::Invalid(format!("unit {i} truncated ({} of {} bytes)", out.len(), u.size))); + } + Ok(out) + } +} + +/// Scan a transport or program stream and index its access units. +pub fn open(src: &S) -> Result { + let mut head = vec![0u8; 64 * 1024]; + let n = read_some(src, 0, &mut head)?; + head.truncate(n); + match sniff(&head).ok_or(Error::NotMpeg)? { + Format::Ts { packet_size, sync_offset } => ts::scan(src, packet_size, sync_offset), + Format::Ps { mpeg1 } => ps::scan(src, mpeg1), + } +} + +/// Unwraps the 33-bit PTS/DTS of ONE stream into an i64 timeline. Values are absolute, not +/// relative to the first one: the first timestamp comes back unchanged, every later wrap adds +/// 2^33, and a timestamp from just before a wrap that arrives after it (B pictures, slightly +/// out-of-order audio) is mapped below the wrap (negative if the stream started after it). +/// Keep one `Unwrap` per clock: the streams of a program share one. +#[derive(Default, Clone, Copy)] +pub(crate) struct Unwrap { + last: Option, + base: i64, +} + +impl Unwrap { + const WRAP: i64 = 1 << 33; + /// 1 minute at 90 kHz: how close to the wrap point a pre-wrap timestamp must be. + const NEAR_WRAP: i64 = 90_000 * 60; + /// Start a stream-local unwrapper at a value already aligned to its program's clock epoch. + pub fn aligned(raw: i64, value: i64) -> Self { + Self { last: Some(value), base: value.saturating_sub(raw) } + } + /// Advance a program-level epoch anchor to a stream that has progressed farther. + pub fn observe(&mut self, stream: Self) { + if stream.last > self.last { + *self = stream; + } + } + pub fn unwrap(&mut self, raw: i64) -> i64 { + let mut v = raw.saturating_add(self.base); + if let Some(l) = self.last { + if v < l.saturating_sub(Self::WRAP / 2) { + self.base = self.base.saturating_add(Self::WRAP); + v = v.saturating_add(Self::WRAP); + } else if v > l.saturating_add(Self::WRAP / 2) && raw >= Self::WRAP - Self::NEAR_WRAP && l < self.base.saturating_add(Self::NEAR_WRAP) { + // a timestamp from before the wrap: it does not move the timeline. Before the + // first wrap and after later wraps this applies only right at the boundary; any + // other forward jump is a new time base (spliced capture) and is followed. + return v.saturating_sub(Self::WRAP); + } + } + self.last = Some(v); + v + } +} + +/// Unwraps the 27 MHz clock reference (PCR/SCR: 33-bit base × 300 + 9-bit extension) of one +/// clock into an i64 timeline and keeps the smallest and largest value seen. +#[derive(Default, Clone, Copy)] +pub(crate) struct ClockRange { + last: Option, + base: i64, + range: Option<(i64, i64)>, +} + +impl ClockRange { + /// 33-bit base × 300 wraps at 2^33·300. + const WRAP: i64 = (1 << 33) * 300; + /// The (min, max) of the unwrapped values so far. + pub fn range(&self) -> Option<(i64, i64)> { + self.range + } + pub fn push(&mut self, raw: i64) { + let mut v = raw.saturating_add(self.base); + if let Some(l) = self.last + && v < l.saturating_sub(Self::WRAP / 2) + { + self.base = self.base.saturating_add(Self::WRAP); + v = v.saturating_add(Self::WRAP); + } + self.last = Some(v); + self.range = Some(self.range.map_or((v, v), |(a, b)| (a.min(v), b.max(v)))); + } +} + +#[cfg(test)] +mod hostile_tests; +#[cfg(test)] +mod tests; +#[cfg(test)] +mod work_tests; diff --git a/crates/media/src/mpegts/pes.rs b/crates/media/src/mpegts/pes.rs new file mode 100644 index 000000000..06c7a2abf --- /dev/null +++ b/crates/media/src/mpegts/pes.rs @@ -0,0 +1,126 @@ +//! PES packet headers (H.222.0 §2.4.3.6; ISO/IEC 11172-1 §2.4.3.3 for MPEG-1 packets). + +/// A parsed PES header. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub(crate) struct PesHeader { + /// Bytes from the packet start code to the first payload byte. + pub header_len: usize, + /// Raw 33-bit timestamps. + pub pts: Option, + pub dts: Option, +} + +/// Stream ids whose packets have no optional header (§2.4.3.7). +pub(crate) fn plain_stream(id: u8) -> bool { + matches!(id, 0xBC | 0xBE | 0xBF | 0xF0 | 0xF1 | 0xF2 | 0xF8 | 0xFF) +} + +pub(crate) fn timestamp(b: &[u8]) -> i64 { + (((b[0] >> 1) & 7) as i64) << 30 | (b[1] as i64) << 22 | ((b[2] >> 1) as i64) << 15 | (b[3] as i64) << 7 | (b[4] >> 1) as i64 +} + +/// Parse a PES header at the start of `b` (which begins with `00 00 01 stream_id`). `None` when +/// `b` is too short to hold the whole header or it is malformed. +pub(crate) fn parse(b: &[u8]) -> Option { + if b.len() < 6 || b[0] != 0 || b[1] != 0 || b[2] != 1 { + return None; + } + if plain_stream(b[3]) { + return Some(PesHeader { header_len: 6, pts: None, dts: None }); + } + if b.len() >= 9 && b[6] & 0xC0 == 0x80 { + // ISO/IEC 13818-1 syntax + let flags = b[7]; + let header_len = 9 + b[8] as usize; + if b.len() < header_len { + return None; + } + let (mut pts, mut dts) = (None, None); + if flags & 0x80 != 0 && header_len >= 14 { + pts = Some(timestamp(&b[9..14])); + if flags & 0x40 != 0 && header_len >= 19 { + dts = Some(timestamp(&b[14..19])); + } + } + return Some(PesHeader { header_len, pts, dts }); + } + // ISO/IEC 11172-1 syntax: stuffing, STD buffer, timestamps + let mut p = 6; + let mut stuffing = 0; + while b.get(p) == Some(&0xFF) { + p += 1; + stuffing += 1; + if stuffing > 16 { + return None; + } + } + let c = *b.get(p)?; + if c >> 6 == 1 { + p += 2; + } + let c = *b.get(p)?; + let (mut pts, mut dts) = (None, None); + match c >> 4 { + 2 => { + pts = Some(timestamp(b.get(p..p + 5)?)); + p += 5; + } + 3 => { + pts = Some(timestamp(b.get(p..p + 5)?)); + dts = Some(timestamp(b.get(p + 5..p + 10)?)); + p += 10; + } + 0 if c == 0x0F => p += 1, + _ => return None, + } + Some(PesHeader { header_len: p, pts, dts }) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn ts_bytes(prefix: u8, v: i64) -> [u8; 5] { + [ + (prefix << 4) | (((v >> 30) & 7) as u8) << 1 | 1, + (v >> 22) as u8, + (((v >> 15) & 0x7F) as u8) << 1 | 1, + (v >> 7) as u8, + ((v & 0x7F) as u8) << 1 | 1, + ] + } + + #[test] + fn mpeg2_and_mpeg1_headers() { + let pts = 0x1_2345_6789i64; + let dts = 0x0_8765_4321i64; + let mut b = vec![0, 0, 1, 0xE0, 0, 0, 0x80, 0xC0, 10]; + b.extend(ts_bytes(3, pts)); + b.extend(ts_bytes(1, dts)); + b.push(0xAA); + let h = parse(&b).unwrap(); + assert_eq!((h.header_len, h.pts, h.dts), (19, Some(pts), Some(dts))); + // MPEG-1: stuffing, STD buffer, PTS only + let mut b = vec![0, 0, 1, 0xC0, 0, 20, 0xFF, 0xFF, 0x40, 0x20]; + b.extend(ts_bytes(2, 90_000)); + let h = parse(&b).unwrap(); + assert_eq!((h.header_len, h.pts, h.dts), (15, Some(90_000), None)); + assert_eq!(parse(&[0, 0, 1, 0xC0, 0, 1, 0x0F]).unwrap().header_len, 7); + assert_eq!(parse(&[0, 0, 1, 0xBE, 0, 4]).unwrap().header_len, 6); + assert!(parse(&[0, 0, 1, 0xE0, 0, 0, 0x80, 0x80]).is_none()); + } + + /// MPEG-1 packets: at most 16 stuffing bytes before the timestamps. + #[test] + fn mpeg1_stuffing_past_the_limit_is_refused() { + let with = |stuffing: usize| { + let mut b = vec![0, 0, 1, 0xC0, 0, 40]; + b.extend(std::iter::repeat_n(0xFF, stuffing)); + b.extend(ts_bytes(2, 90_000)); + parse(&b) + }; + assert_eq!(with(16).map(|h| (h.header_len, h.pts)), Some((6 + 16 + 5, Some(90_000)))); + assert_eq!(with(17), None); + assert_eq!(with(5000), None); + } +} diff --git a/crates/media/src/mpegts/ps.rs b/crates/media/src/mpegts/ps.rs new file mode 100644 index 000000000..d044c01f4 --- /dev/null +++ b/crates/media/src/mpegts/ps.rs @@ -0,0 +1,414 @@ +//! Program streams (H.222.0 §2.5; ISO/IEC 11172-1 §2.4.3): packs, system headers, the program +//! stream map, PES packets, and the DVD sub-streams of private stream 1. + +use std::collections::HashMap; + +use super::es::Splitter; +use super::pes; +use super::{ByteSource, ClockRange, Codec, Error, File, Format, LpcmFormat, Result, Stream, StreamId, Unit, Unwrap, read_some}; + +/// Sequential reader with a refillable window. +struct Win<'a, S: ByteSource + ?Sized> { + src: &'a S, + buf: Vec, + start: u64, + /// Bytes zero-filled by window refills (tests count them). + #[cfg(test)] + zero_filled: usize, + /// Window refills (tests count them). + #[cfg(test)] + refills: usize, +} + +impl<'a, S: ByteSource + ?Sized> Win<'a, S> { + fn new(src: &'a S) -> Self { + Self { + src, + buf: Vec::new(), + start: 0, + #[cfg(test)] + zero_filled: 0, + #[cfg(test)] + refills: 0, + } + } + /// The bytes [pos, pos + n) (fewer at the end of the file). + fn get(&mut self, pos: u64, n: usize) -> Result<&[u8]> { + let end = self.start + self.buf.len() as u64; + // a window that already reaches the end of the file holds all there is to read past `pos` + let have = pos >= self.start && (pos.saturating_add(n as u64) <= end || end >= self.src.len()); + if !have { + #[cfg(test)] + { + self.refills += 1; + } + // never more than the file still holds past `pos`: `read_some` would not fill it, and + // zeroing a megabyte for every packet near the end of the file is wasted work + let remaining = self.src.len().saturating_sub(pos); + let want = (n.max(1 << 20) as u64).min(remaining) as usize; + #[cfg(test)] + { + self.zero_filled += want.saturating_sub(self.buf.len()); + } + self.buf.resize(want, 0); + let got = read_some(self.src, pos, &mut self.buf)?; + self.buf.truncate(got); + self.start = pos; + } + let i = (pos - self.start) as usize; + let end = (i + n).min(self.buf.len()); + Ok(&self.buf[i.min(end)..end]) + } +} + +/// How many bytes of a private stream 1 payload precede the elementary stream, by sub-stream id +/// (DVD-Video: AC-3 / DTS 4, LPCM 7, sub-pictures 1). +fn sub_header(sub: u8) -> usize { + match sub { + 0x80..=0x8F => 4, + 0xA0..=0xAF => 7, + _ => 1, + } +} + +fn codec_for(stream_id: u8, sub: Option, psm: &HashMap, mpeg1: bool) -> Codec { + if let Some(&t) = psm.get(&stream_id) { + let c = super::ts::codec_of(t, &[], false); + if !matches!(c, Codec::Unknown(_)) { + return c; + } + } + match (stream_id, sub) { + (0xE0..=0xEF, _) => { + if mpeg1 { + Codec::Mpeg1Video + } else { + Codec::Mpeg2Video + } + } + (0xC0..=0xDF, _) => Codec::MpegAudio, + (0xBD, Some(0x80..=0x87)) => Codec::Ac3, + (0xBD, Some(0x88..=0x8F)) => Codec::Dts, + (0xBD, Some(0xA0..=0xAF)) => Codec::LpcmDvd, + (0xBD, Some(0x20..=0x3F)) => Codec::Subtitle("DVD sub-pictures"), + (id, _) => Codec::Unknown(id), + } +} + +/// DVD LPCM header bytes after the sub-stream id (and the frame count / pointer). +fn lpcm_format(h: &[u8]) -> Option { + let b = *h.get(4)?; + let bits = [16, 20, 24, 0][(b >> 6) as usize]; + let sample_rate = [48_000, 96_000, 44_100, 32_000][((b >> 4) & 3) as usize]; + let channels = (b & 7) as u32 + 1; + (bits > 0).then_some(LpcmFormat { sample_rate, channels, bits }) +} + +struct EsState { + stream: Stream, + split: Splitter, + /// Progression is unwrapped per stream after its first timestamp is aligned to the program. + unwrap: Option, +} + +fn unwrap_time(epoch: &mut Unwrap, stream: &mut Option, raw: i64) -> i64 { + if let Some(unwrap) = stream { + let value = unwrap.unwrap(raw); + epoch.observe(*unwrap); + value + } else { + let value = epoch.unwrap(raw); + *stream = Some(Unwrap::aligned(raw, value)); + value + } +} + +/// Length of the packet (pack header, system header, PES…) starting at `b` (which begins with a +/// start code), `None` if it is not one. +fn packet_len(b: &[u8]) -> Option { + if b.len() < 6 || b[0] != 0 || b[1] != 0 || b[2] != 1 { + return None; + } + match b[3] { + 0xBA => { + if b[4] >> 6 == 1 { + let stuff = (*b.get(13)? & 7) as usize; + Some(14 + stuff) + } else if b[4] >> 4 == 2 { + // MPEG-1 pack header: start code, 5-byte SCR, 3-byte mux rate. A file cut inside + // it is not a pack header yet (`scan` reads the SCR from the first 9 bytes). + b.get(..12)?; + Some(12) + } else { + None + } + } + 0xB9 => Some(4), + 0xBB..=0xFF => Some(6 + u16::from_be_bytes([b[4], b[5]]) as usize), + _ => None, + } +} + +pub(crate) fn scan(src: &S, mpeg1: bool) -> Result { + let len = src.len(); + let mut win = Win::new(src); + let mut pos = 0u64; + let mut streams: HashMap<(u8, Option), EsState> = HashMap::new(); + let mut order = Vec::new(); + let mut psm: HashMap = HashMap::new(); + let mut scr = ClockRange::default(); + // Program-stream elementary streams share one clock epoch. The anchor follows the farthest + // progressed stream so a stream first seen after a wrap joins that epoch, while each stream + // keeps independent progression so its reordered timestamps cannot move another stream. + let mut timestamp_epoch = Unwrap::default(); + let mut resyncs = 0u64; + while pos + 4 <= len { + let head = win.get(pos, 32)?; + let Some(plen) = packet_len(head) else { + // resynchronise on the next pack header or PES start code + resyncs += 1; + let mut p = pos + 1; + let found = loop { + let w = win.get(p, 1 << 16)?; + if w.len() < 4 { + break None; + } + if let Some(i) = w.windows(4).position(|x| x[0] == 0 && x[1] == 0 && x[2] == 1 && (x[3] == 0xBA || (0xBD..=0xEF).contains(&x[3]))) { + break Some(p + i as u64); + } + p += (w.len() - 3) as u64; + }; + match found { + Some(f) => { + pos = f; + continue; + } + None => break, + } + }; + let id = head[3]; + if id == 0xBA { + // SCR (MPEG-2: 33 bits base, 9 bits extension; MPEG-1: 33 bits) + let v = if head[4] >> 6 == 1 { + let b = &head[4..10]; + let base = (((b[0] >> 3) & 7) as i64) << 30 + | ((b[0] & 3) as i64) << 28 + | (b[1] as i64) << 20 + | ((b[2] >> 3) as i64) << 15 + | ((b[2] & 3) as i64) << 13 + | (b[3] as i64) << 5 + | (b[4] >> 3) as i64; + let ext = (((b[4] & 3) as i64) << 7) | (b[5] >> 1) as i64; + base * 300 + ext + } else { + pes::timestamp(&head[4..9]) * 300 + }; + scr.push(v); + } else if id == 0xBC { + // program stream map: elementary stream id → stream_type + let body = win.get(pos, plen)?; + if body.len() >= 12 { + let info = u16::from_be_bytes([body[8], body[9]]) as usize; + let mut i = 10 + info; + if i + 2 <= body.len() { + let map_len = u16::from_be_bytes([body[i], body[i + 1]]) as usize; + i += 2; + let end = (i + map_len).min(body.len()); + while i + 4 <= end { + psm.insert(body[i + 1], body[i]); + i += 4 + u16::from_be_bytes([body[i + 2], body[i + 3]]) as usize; + } + } + } + } else if id == 0xBD || (0xC0..=0xEF).contains(&id) || id == 0xFD { + let pkt = win.get(pos, plen)?; + if pkt.len() < plen { + break; // truncated + } + if let Some(h) = pes::parse(pkt) { + let payload = &pkt[h.header_len.min(plen)..]; + let (sub, skip) = if id == 0xBD { + match payload.first() { + Some(&s) => (Some(s), sub_header(s).min(payload.len())), + None => (None, 0), + } + } else { + (None, 0) + }; + let key = (id, sub); + let e = streams.entry(key).or_insert_with(|| { + let codec = codec_for(id, sub, &psm, mpeg1); + let lpcm = if codec == Codec::LpcmDvd { lpcm_format(&payload[1.min(payload.len())..]) } else { None }; + order.push(key); + let stream = Stream { + id: StreamId::Ps { stream_id: id, sub_id: sub }, + stream_type: psm.get(&id).copied().unwrap_or(0), + codec: codec.clone(), + language: None, + units: Vec::new(), + lpcm, + pes_packets: 0, + skipped_bytes: 0, + }; + EsState { stream, split: Splitter::new(&codec), unwrap: None } + }); + e.stream.pes_packets += 1; + let pts = h.pts.map(|t| unwrap_time(&mut timestamp_epoch, &mut e.unwrap, t)); + let dts = h.dts.map(|t| unwrap_time(&mut timestamp_epoch, &mut e.unwrap, t)); + e.split.pes_start(pts, dts); + e.split.feed(pos, &payload[skip..]); + } + } + pos += plen as u64; + } + let mut warnings = Vec::new(); + if resyncs > 0 { + warnings.push(format!("resynchronised {resyncs} time(s)")); + } + let mut out = Vec::new(); + for key in order { + let Some(mut e) = streams.remove(&key) else { continue }; + e.split.finish(); + e.stream.units = std::mem::take(&mut e.split.units); + e.stream.skipped_bytes = e.split.skipped; + out.push(e.stream); + } + if out.is_empty() { + return Err(Error::Invalid("program stream without elementary streams".into())); + } + Ok(File { format: Format::Ps { mpeg1 }, streams: out, program: None, pcr_range: scr.range(), warnings }) +} + +/// Collect unit `u` of stream `st`, starting at the PES packet at `u.pos`. +pub(crate) fn read(src: &S, st: &Stream, u: &Unit, out: &mut Vec) -> Result<()> { + let StreamId::Ps { stream_id, sub_id } = st.id else { return Err(Error::Invalid("not a PS stream".into())) }; + let need = u.size as usize; + let mut skip = u.offset as usize; + let mut pos = u.pos; + let len = src.len(); + let mut win = Win::new(src); + while out.len() < need && pos + 4 <= len { + let head = win.get(pos, 32)?; + let Some(plen) = packet_len(head) else { + // corrupt: stop at what we have + return Ok(()); + }; + if head[3] == stream_id { + let pkt = win.get(pos, plen)?; + if let Some(h) = pes::parse(pkt) { + let payload = &pkt[h.header_len.min(pkt.len())..]; + let matches = stream_id != 0xBD || payload.first().copied() == sub_id; + if matches { + let s0 = if stream_id == 0xBD { sub_id.map_or(0, sub_header).min(payload.len()) } else { 0 }; + let mut bytes = &payload[s0..]; + if skip > 0 { + let s = skip.min(bytes.len()); + skip -= s; + bytes = &bytes[s..]; + } + let take = bytes.len().min(need - out.len()); + out.extend_from_slice(&bytes[..take]); + } + } + } + pos += plen as u64; + } + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + + /// The window refill before the zero-fill cap: always `max(n, 1 MiB)` bytes, counted when the + /// buffer has to grow. + struct OldWin<'a> { + src: &'a [u8], + buf: Vec, + start: u64, + zero_filled: usize, + } + + impl OldWin<'_> { + fn get(&mut self, pos: u64, n: usize) -> Vec { + let have = pos >= self.start && pos + n as u64 <= self.start + self.buf.len() as u64; + if !have { + let want = n.max(1 << 20); + self.zero_filled += want.saturating_sub(self.buf.len()); + self.buf.resize(want, 0); + let got = read_some(self.src, pos, &mut self.buf).unwrap(); + self.buf.truncate(got); + self.start = pos; + } + let i = (pos - self.start) as usize; + let end = (i + n).min(self.buf.len()); + self.buf[i.min(end)..end].to_vec() + } + } + + fn data(len: usize) -> Vec { + (0..len).map(|i| (i * 31 + i / 7) as u8).collect() + } + + #[test] + fn capped_window_returns_what_the_uncapped_window_returned() { + for len in [0usize, 1, 31, 32, 33, 1000, (1 << 20) - 1, 1 << 20, (1 << 20) + 5, (3 << 20) + 17] { + let d = data(len); + let mut new = Win::new(d.as_slice()); + let mut old = OldWin { src: &d, buf: Vec::new(), start: 0, zero_filled: 0 }; + let len64 = len as u64; + let mut positions = vec![ + 0, + 1, + 31, + 32, + 1 << 19, + 1 << 20, + (1 << 20) - 1, + (1 << 20) + 1, + 2 << 20, + len64.saturating_sub(40), + len64.saturating_sub(1), + len64, + len64 + 1, + len64 + 100, + ]; + positions.extend((0..10).map(|k| len64.saturating_sub(100) + k * 13)); + for &pos in &positions { + for n in [0usize, 1, 33, 1000, 65_541, 1 << 20, (1 << 20) + 1] { + assert_eq!(new.get(pos, n).unwrap(), old.get(pos, n).as_slice(), "len {len} pos {pos} n {n}"); + } + } + } + } + + /// Dense recovery candidates near the end ask for more bytes than the file still holds: the + /// window that already reaches the end serves them, without a refill each. + #[test] + fn requests_past_the_end_reuse_a_window_that_reaches_it() { + let d = data(5000); + let mut w = Win::new(d.as_slice()); + assert_eq!(w.get(4000, 32).unwrap(), &d[4000..4032]); + let first = w.refills; + for pos in 4000..4990 { + assert_eq!(w.get(pos, 4096).unwrap(), &d[pos as usize..], "pos {pos}"); + } + assert_eq!(w.refills, first, "a refill per request"); + } + + #[test] + fn misses_near_the_end_zero_at_most_the_bytes_that_are_left() { + let len = (2 << 20) + 1000; + let d = data(len); + let mut new = Win::new(d.as_slice()); + let mut old = OldWin { src: &d, buf: Vec::new(), start: 0, zero_filled: 0 }; + // a PES packet whose length runs past the end of the file, asked for once per packet + let first = (2u64 << 20) as usize; + for k in 0..500 { + let pos = (first + k) as u64; + assert_eq!(new.get(pos, 2000).unwrap(), old.get(pos, 2000).as_slice()); + } + assert!(new.zero_filled <= 1000, "zeroed {} bytes, only 1000 are left in the file", new.zero_filled); + assert!(old.zero_filled > 499 * ((1 << 20) - 1000), "the reference zeroes about a megabyte per miss: {}", old.zero_filled); + } +} diff --git a/crates/media/src/mpegts/tests.rs b/crates/media/src/mpegts/tests.rs new file mode 100644 index 000000000..0215680ad --- /dev/null +++ b/crates/media/src/mpegts/tests.rs @@ -0,0 +1,1125 @@ +//! Synthetic transport and program streams: a small muxer writes known access units, the +//! demuxer must give them back exactly (bytes, timestamps, flags); truncation and mutation never +//! panic. + +use super::*; + +mod hostile; + +fn ts_bytes(prefix: u8, v: i64) -> [u8; 5] { + let v = v & ((1 << 33) - 1); + [ + (prefix << 4) | (((v >> 30) & 7) as u8) << 1 | 1, + (v >> 22) as u8, + (((v >> 15) & 0x7F) as u8) << 1 | 1, + (v >> 7) as u8, + ((v & 0x7F) as u8) << 1 | 1, + ] +} + +pub(super) fn pes(stream_id: u8, pts: Option, dts: Option, payload: &[u8], bounded: bool) -> Vec { + let mut h = Vec::new(); + match (pts, dts) { + (Some(p), Some(d)) => { + h.extend(ts_bytes(3, p)); + h.extend(ts_bytes(1, d)); + } + (Some(p), None) => h.extend(ts_bytes(2, p)), + _ => {} + } + let flags = match (pts, dts) { + (Some(_), Some(_)) => 0xC0, + (Some(_), None) => 0x80, + _ => 0, + }; + let len = if bounded { 3 + h.len() + payload.len() } else { 0 }; + let mut v = vec![0, 0, 1, stream_id, (len >> 8) as u8, len as u8, 0x80, flags, h.len() as u8]; + v.extend(h); + v.extend_from_slice(payload); + v +} + +fn ps_pack() -> [u8; 14] { + [0, 0, 1, 0xBA, 0x44, 0, 4, 0, 4, 1, 1, 0x89, 0xC3, 0xF8] +} + +/// A tiny TS muxer: PAT, PMT and PES packets cut into 188-byte packets (192 with `m2ts`). +pub(super) struct TsMux { + pub(super) out: Vec, + cc: std::collections::HashMap, + m2ts: bool, +} + +impl TsMux { + pub(super) fn new(m2ts: bool) -> Self { + Self { out: Vec::new(), cc: Default::default(), m2ts } + } + fn packet(&mut self, pid: u16, pusi: bool, payload: &[u8]) -> usize { + let cc = self.cc.entry(pid).or_insert(0); + let mut p = vec![0x47, (pusi as u8) << 6 | (pid >> 8) as u8, pid as u8]; + let n = payload.len().min(184); + if n < 184 { + // adaptation field stuffing + let al = 183 - n; + p.push(0x30 | *cc); + p.push(al as u8); + if al > 0 { + p.push(0); + p.extend(std::iter::repeat_n(0xFF, al - 1)); + } + } else { + p.push(0x10 | *cc); + } + *cc = (*cc + 1) & 15; + p.extend_from_slice(&payload[..n]); + assert_eq!(p.len(), 188); + if self.m2ts { + self.out.extend_from_slice(&[0, 0, 0, 0]); + } + self.out.extend(p); + n + } + pub(super) fn section(&mut self, pid: u16, body: &[u8]) { + let mut s = body.to_vec(); + let crc = super::ts::crc32_mpeg(&s); + s.extend(crc.to_be_bytes()); + let mut payload = vec![0]; + payload.extend(s); + self.packet(pid, true, &payload); + } + pub(super) fn psi(&mut self, streams: &[(u8, u16)]) { + self.psi_pcr(streams, 0x100); + } + /// PAT and PMT; the PMT names `pcr_pid` as the PCR PID. The streams' ES info is empty. + fn psi_pcr(&mut self, streams: &[(u8, u16)], pcr_pid: u16) { + let descs: Vec<(u8, u16, Vec)> = streams.iter().map(|&(st, pid)| (st, pid, Vec::new())).collect(); + self.psi_full(&descs, pcr_pid); + } + /// PAT and PMT with ES descriptors per stream. + fn psi_full(&mut self, streams: &[(u8, u16, Vec)], pcr_pid: u16) { + // PAT: program 1 → PMT PID 0x100 + let pat = [0x00, 0xB0, 13, 0, 1, 0xC1, 0, 0, 0, 1, 0xE1, 0x00]; + self.section(0, &pat); + let mut pmt = vec![0x02, 0xB0, 0, 0, 1, 0xC1, 0, 0, 0xE0 | (pcr_pid >> 8) as u8, pcr_pid as u8, 0xF0, 0]; + for (st, pid, desc) in streams { + pmt.extend([*st, 0xE0 | (*pid >> 8) as u8, *pid as u8, 0xF0 | (desc.len() >> 8) as u8, desc.len() as u8]); + pmt.extend_from_slice(desc); + } + let len = pmt.len() - 3 + 4; + pmt[1] = 0xB0 | (len >> 8) as u8; + pmt[2] = len as u8; + self.section(0x100, &pmt); + } + /// An adaptation-field-only packet carrying a PCR with the given 33-bit base. + fn pcr(&mut self, pid: u16, base: i64) { + let cc = self.cc.entry(pid).or_insert(0); + let b = base & ((1 << 33) - 1); + let mut p = vec![0x47, (pid >> 8) as u8, pid as u8, 0x20 | *cc, 183, 0x10]; + p.extend([(b >> 25) as u8, (b >> 17) as u8, (b >> 9) as u8, (b >> 1) as u8, ((b & 1) as u8) << 7 | 0x7E, 0]); + p.resize(188, 0xFF); + if self.m2ts { + self.out.extend_from_slice(&[0, 0, 0, 0]); + } + self.out.extend(p); + } + pub(super) fn pes(&mut self, pid: u16, data: &[u8]) { + let mut rest = data; + let mut first = true; + while !rest.is_empty() { + let n = self.packet(pid, first, rest); + rest = &rest[n..]; + first = false; + } + } +} + +/// An MPEG-2 coded frame: sequence header (on I), GOP, picture header, picture coding +/// extension and a slice of filler; or a field pair. +fn mpeg2_frame(coding_type: u8, tref: u16, fields: bool, filler: usize) -> Vec { + let mut v = Vec::new(); + if coding_type == 1 { + v.extend([0, 0, 1, 0xB3, 0x14, 0x00, 0xF0, 0x13, 0xFF, 0xFF, 0xE0, 0x18]); + v.extend([0, 0, 1, 0xB8, 0, 8, 0, 0x40]); + } + let pics: &[u8] = if fields { &[1, 2] } else { &[3] }; + for &s in pics { + v.extend([0, 0, 1, 0x00, (tref >> 2) as u8, ((tref & 3) << 6) as u8 | coding_type << 3, 0xFF, 0xF8]); + v.extend([0, 0, 1, 0xB5, 0x8F, 0xFF, 0xF0 | s, 0x80, 0x80]); + v.extend([0, 0, 1, 0x01]); + v.extend((0..filler).map(|i| (i % 200) as u8 | 0x10)); + } + v +} + +/// MPEG-1 layer II frame, 48 kHz 192 kb/s (576 bytes). +fn mp2_frame(k: u8) -> Vec { + let mut v = vec![0xFF, 0xFD, 0xA4, 0x00]; + v.extend((0..572).map(|i| (i as u8) ^ k)); + v +} + +#[test] +fn transport_stream_units_round_trip() { + for m2ts in [false, true] { + let mut mux = TsMux::new(m2ts); + mux.psi(&[(0x02, 0x1011), (0x03, 0x1100)]); + // decode order I0 P3 B1 B2 with PTS = display time, DTS on anchors + let frames = [(1u8, 0u16, false), (2, 3, false), (3, 1, true), (3, 2, false)]; + let mut expect_video = Vec::new(); + for (k, &(t, tref, fields)) in frames.iter().enumerate() { + let f = mpeg2_frame(t, tref, fields, 300 + 97 * k); + let pts = 90_000 + tref as i64 * 3600; + let dts = (t != 3).then_some(90_000 - 3600 + k as i64 * 3600); + mux.pes(0x1011, &pes(0xE0, Some(pts), dts, &f, false)); + expect_video.push((f, pts, t)); + // two audio frames per PES, the second without its own timestamp + let a: Vec = [mp2_frame(2 * k as u8), mp2_frame(2 * k as u8 + 1)].concat(); + mux.pes(0x1100, &pes(0xC0, Some(90_000 + 2160 * 2 * k as i64), None, &a, true)); + } + let data = mux.out; + let f = open(&data).unwrap(); + assert_eq!(f.format, Format::Ts { packet_size: if m2ts { 192 } else { 188 }, sync_offset: if m2ts { 4 } else { 0 } }); + assert!(f.warnings.is_empty(), "{:?}", f.warnings); + assert_eq!(f.program, Some(1)); + let v = f.find(Kind::Video, |_| true).unwrap(); + let s = &f.streams[v]; + assert_eq!(s.codec, Codec::Mpeg2Video); + assert_eq!(s.units.len(), 4); + for (i, (bytes, pts, t)) in expect_video.iter().enumerate() { + let u = &s.units[i]; + assert_eq!(f.read_unit(&data, v, i).unwrap(), *bytes, "unit {i}"); + assert_eq!(u.pts, Some(*pts)); + assert_eq!(u.key, *t == 1); + assert_eq!(u.disposable, *t == 3); + assert_eq!(u.picture.unwrap().coding_type, *t); + } + assert_eq!(s.units[2].picture.unwrap().structure, 1, "field pair in one unit"); + assert!(s.units[0].picture.unwrap().sequence_header && s.units[0].picture.unwrap().gop); + let a = f.find(Kind::Audio, |c| *c == Codec::MpegAudio).unwrap(); + let s = &f.streams[a]; + assert_eq!(s.units.len(), 8); + for (i, u) in s.units.iter().enumerate() { + assert_eq!(f.read_unit(&data, a, i).unwrap(), mp2_frame(i as u8)); + assert_eq!(u.pts, (i % 2 == 0).then_some(90_000 + 2160 * i as i64)); + } + } +} + +#[test] +fn program_stream_units_round_trip() { + // packs of ≤ 2048 bytes: frames are split across PES packets + let frames: Vec> = (0..5).map(|k| mpeg2_frame(if k == 0 { 1 } else { 2 }, k as u16, k == 3, 2500 + 300 * k)).collect(); + let es: Vec = frames.concat(); + let mut starts = Vec::new(); + let mut acc = 0; + for f in &frames { + starts.push(acc); + acc += f.len(); + } + let mut out = Vec::new(); + let mut p = 0; + let mut a = 0u8; + while p < es.len() { + out.extend([0, 0, 1, 0xBA, 0x44, 0, 4, 0, 4, 1, 1, 0x89, 0xC3, 0xF8]); + let n = (es.len() - p).min(2000); + // a timestamp when a frame starts in this packet + let k = starts.iter().position(|&s| s >= p && s < p + n); + out.extend(pes(0xE0, k.map(|k| 3600 * k as i64), None, &es[p..p + n], true)); + p += n; + // AC-3 in private stream 1 (sub-stream 0x80, 4-byte header), 448 kb/s frames + let mut ac3 = vec![0x80, 1, 0, 1, 0x0B, 0x77, 0, 0, 30, 0x40]; + ac3.extend(std::iter::repeat_n(a, 1792 - 6)); + a += 1; + out.extend(pes(0xBD, Some(1000 + 2880 * a as i64), None, &ac3, true)); + } + out.extend([0, 0, 1, 0xB9]); + let f = open(&out).unwrap(); + assert_eq!(f.format, Format::Ps { mpeg1: false }); + let v = f.find(Kind::Video, |_| true).unwrap(); + assert_eq!(f.streams[v].units.len(), 5); + for (i, fr) in frames.iter().enumerate() { + assert_eq!(&f.read_unit(&out, v, i).unwrap(), fr); + assert_eq!(f.streams[v].units[i].pts, Some(3600 * i as i64)); + } + let a = f.find(Kind::Audio, |c| *c == Codec::Ac3).unwrap(); + assert_eq!(f.streams[a].id, StreamId::Ps { stream_id: 0xBD, sub_id: Some(0x80) }); + assert_eq!(f.streams[a].units.len(), a_count(&out)); + let u0 = f.read_unit(&out, a, 0).unwrap(); + assert_eq!(&u0[..2], &[0x0B, 0x77]); + assert_eq!(u0.len(), 1792); +} + +fn a_count(ps: &[u8]) -> usize { + ps.windows(4).filter(|w| *w == [0, 0, 1, 0xBD]).count() +} + +#[test] +fn sniffing() { + assert_eq!(sniff(&[0, 0, 1, 0xBA, 0x44]), Some(Format::Ps { mpeg1: false })); + assert_eq!(sniff(&[0, 0, 1, 0xBA, 0x21]), Some(Format::Ps { mpeg1: true })); + assert_eq!(sniff(&[0, 0, 1, 0xB3, 0x44]), None); + let mut ts = vec![0u8; 188 * 6]; + for k in 0..6 { + ts[k * 188] = 0x47; + } + assert!(matches!(sniff(&ts), Some(Format::Ts { packet_size: 188, .. }))); +} + +#[test] +fn truncation_and_mutation_never_panic() { + let mut mux = TsMux::new(false); + mux.psi(&[(0x02, 0x1011), (0x0F, 0x1100), (0x1B, 0x1200)]); + for k in 0..6u16 { + mux.pes(0x1011, &pes(0xE0, Some(3600 * k as i64), None, &mpeg2_frame(if k == 0 { 1 } else { 3 }, k, k % 2 == 1, 400), false)); + let mut adts = vec![0xFF, 0xF1, 0x50, 0x80, 0x0C, 0x9F, 0xFC]; + adts.extend([0x21u8; 93]); + mux.pes(0x1100, &pes(0xC0, Some(1920 * k as i64), None, &adts, true)); + mux.pes(0x1200, &pes(0xE1, Some(3600 * k as i64), None, &[0, 0, 0, 1, 0x09, 0xF0, 0, 0, 1, 0x65, 0x88, 1, 2, 3], false)); + } + let data = mux.out; + let full = open(&data).unwrap(); + assert_eq!(full.streams.len(), 3); + assert_eq!(full.streams[1].units.len(), 6, "ADTS frames"); + assert!(full.streams[2].units.iter().all(|u| u.key), "IDR access units"); + for cut in (0..data.len()).step_by(37) { + if let Ok(f) = open(&data[..cut].to_vec()) { + for (s, st) in f.streams.iter().enumerate() { + for i in 0..st.units.len() { + let _ = f.read_unit(&data[..cut].to_vec(), s, i); + } + } + } + } + let mut x = 0x9E37_79B9u32; + for _ in 0..400 { + let mut m = data.clone(); + for _ in 0..8 { + x ^= x << 13; + x ^= x >> 17; + x ^= x << 5; + let i = x as usize % m.len(); + m[i] = (x >> 8) as u8; + } + if let Ok(f) = open(&m) { + for (s, st) in f.streams.iter().enumerate() { + for i in 0..st.units.len() { + let _ = f.read_unit(&m, s, i); + } + } + } + } +} + +/// Opens `data` and reads every unit; errors are fine, panics are not. +fn open_and_read_all(data: &[u8]) { + let data = data.to_vec(); + if let Ok(f) = open(&data) { + for (s, st) in f.streams.iter().enumerate() { + for i in 0..st.units.len() { + let _ = f.read_unit(&data, s, i); + } + } + } +} + +#[test] +fn program_stream_cut_inside_a_pack_header_never_panics() { + // MPEG-1 pack header cut after the 4-byte start code + 3 bytes (once panicked in `scan`). + open_and_read_all(&[0, 0, 1, 0xBA, 0x21, 0, 0]); + for n in 4..=12 { + let mpeg1 = [0u8, 0, 1, 0xBA, 0x21, 0, 1, 0, 1, 0x80, 0, 1]; + open_and_read_all(&mpeg1[..n]); + } +} + +#[test] +fn program_stream_truncation_at_every_length_never_panics() { + let frames: Vec> = (0..3).map(|k| mpeg2_frame(if k == 0 { 1 } else { 2 }, k as u16, false, 300)).collect(); + let es: Vec = frames.concat(); + for mpeg1 in [false, true] { + let mut out = Vec::new(); + for (k, chunk) in es.chunks(500).enumerate() { + if mpeg1 { + out.extend([0, 0, 1, 0xBA, 0x21, 0, 1, 0, 1, 0x80, 0, 1]); + } else { + out.extend([0, 0, 1, 0xBA, 0x44, 0, 4, 0, 4, 1, 1, 0x89, 0xC3, 0xF8]); + } + out.extend(pes(0xE0, Some(3600 * k as i64), None, chunk, true)); + } + out.extend([0, 0, 1, 0xB9]); + assert!(open(&out).is_ok(), "the untruncated stream opens (mpeg1: {mpeg1})"); + for cut in 0..=out.len() { + open_and_read_all(&out[..cut]); + } + } +} + +#[test] +fn timestamps_unwrap_across_the_33_bit_wrap() { + let mut u = Unwrap::default(); + let near = (1i64 << 33) - 3000; + assert_eq!(u.unwrap(near), near); + assert_eq!(u.unwrap(600), (1 << 33) + 600); + // a B picture timestamp from just before the wrap + assert_eq!(u.unwrap(near + 1000), near + 1000); + assert_eq!(u.unwrap(4200), (1 << 33) + 4200); +} + +#[test] +fn pcr_range_follows_the_pmt_pcr_pid() { + // two PIDs carry PCRs on unrelated time bases; only the PMT's PCR_PID counts + let mut mux = TsMux::new(false); + mux.psi_pcr(&[(0x02, 0x101)], 0x101); + for k in 0..3i64 { + mux.pcr(0x101, 1000 + 40_500 * k); + mux.pcr(0x102, (1 << 32) + 5000 + 40_500 * k); + } + let f = open(&mux.out).unwrap(); + assert_eq!(f.pcr_range, Some((1000 * 300, (1000 + 81_000) * 300))); + // the other PID is the clock reference instead + let mut mux = TsMux::new(false); + mux.psi_pcr(&[(0x02, 0x101)], 0x102); + for k in 0..3i64 { + mux.pcr(0x101, 1000 + 40_500 * k); + mux.pcr(0x102, (1 << 32) + 5000 + 40_500 * k); + } + let f = open(&mux.out).unwrap(); + assert_eq!(f.pcr_range, Some((((1 << 32) + 5000) * 300, ((1 << 32) + 5000 + 81_000) * 300))); +} + +#[test] +fn pcr_range_without_a_usable_pcr_pid() { + // the PMT says "no PCR" (0x1FFF) or names a PID that never carries one + for pcr_pid in [0x1FFF, 0x150] { + let mut mux = TsMux::new(false); + mux.psi_pcr(&[(0x02, 0x101)], pcr_pid); + for base in [1000, 2000, 3000, 4000] { + mux.pcr(0x101, base); + } + assert_eq!(open(&mux.out).unwrap().pcr_range, None, "pcr_pid {pcr_pid:#x}"); + } + // no PMT at all: the first PID seen with a PCR stands in + let mut mux = TsMux::new(false); + for k in 0..6i64 { + mux.pcr(0x101, 1000 + 500 * k); + mux.pcr(0x102, (1 << 32) + 5000 + 500 * k); + } + let f = open(&mux.out).unwrap(); + assert_eq!(f.pcr_range, Some((1000 * 300, 3500 * 300))); +} + +#[test] +fn pcr_range_unwraps_the_33_bit_base() { + let mut mux = TsMux::new(false); + mux.psi_pcr(&[(0x02, 0x101)], 0x101); + let near = (1i64 << 33) - 1000; + for base in [near, near + 500, 2000, 2500] { + mux.pcr(0x101, base); + } + let f = open(&mux.out).unwrap(); + assert_eq!(f.pcr_range, Some((near * 300, ((1 << 33) + 2500) * 300))); +} + +#[test] +fn pcr_range_continues_when_a_later_pmt_changes_the_pcr_pid() { + let mut mux = TsMux::new(false); + let pat = [0x00, 0xB0, 13, 0, 1, 0xC1, 0, 0, 0, 1, 0xE1, 0x00]; + mux.section(0, &pat); + mux.section(0x100, &pmt_section_for(1, 0, true, 0x101, &[(0x03, 0x1100)])); + let near = (1i64 << 33) - 1000; + mux.pcr(0x101, near); + mux.section(0x100, &pmt_section_for(1, 1, true, 0x102, &[(0x03, 0x1100)])); + mux.pcr(0x101, near + 500); // no longer active + mux.pcr(0x102, 500); + mux.pes(0x1100, &pes(0xC0, Some(90_000), None, &mp2_frame(0), true)); + let f = open(&mux.out).unwrap(); + assert_eq!(f.pcr_range, Some((near * 300, ((1 << 33) + 500) * 300))); +} + +#[test] +fn pcr_before_the_pmt_is_kept_when_the_pmt_confirms_its_pid() { + let mut mux = TsMux::new(false); + mux.pcr(0x101, 1000); + mux.psi_pcr(&[(0x03, 0x1100)], 0x101); + mux.pcr(0x101, 2000); + mux.pes(0x1100, &pes(0xC0, Some(90_000), None, &mp2_frame(0), true)); + let f = open(&mux.out).unwrap(); + assert_eq!(f.pcr_range, Some((1000 * 300, 2000 * 300))); +} + +#[test] +fn pcr_before_the_pmt_is_kept_when_another_pid_carried_the_first_pcr() { + // PID 0x102 carries the first PCR, but the PMT names 0x101: its earlier PCRs still count + let mut mux = TsMux::new(false); + mux.pcr(0x102, 500); + mux.pcr(0x101, 1000); + mux.pcr(0x101, 2000); + mux.psi_pcr(&[(0x03, 0x1100)], 0x101); + mux.pes(0x1100, &pes(0xC0, Some(90_000), None, &mp2_frame(0), true)); + let f = open(&mux.out).unwrap(); + assert_eq!(f.pcr_range, Some((1000 * 300, 2000 * 300))); +} + +#[test] +fn streams_sharing_a_clock_stay_in_step_across_the_33_bit_wrap() { + // video's first PTS is just before the wrap, audio's just after: one clock, so audio is + // 2^33 + 500, not 500 (26.5 hours apart) + let w = 1i64 << 33; + for audio_first in [false, true] { + let mut mux = TsMux::new(false); + mux.psi(&[(0x03, 0x1100), (0x03, 0x1101)]); + let (v0, a0) = (w - 1000, 500); + let video = |mux: &mut TsMux, k: u8| mux.pes(0x1101, &pes(0xC0, Some((v0 + 2160 * k as i64) % w), None, &mp2_frame(k), true)); + let audio = |mux: &mut TsMux, k: u8| mux.pes(0x1100, &pes(0xC0, Some(a0 + 2160 * k as i64), None, &mp2_frame(k), true)); + for k in 0..3u8 { + if audio_first { + audio(&mut mux, k); + video(&mut mux, k); + } else { + video(&mut mux, k); + audio(&mut mux, k); + } + } + let f = open(&mux.out).unwrap(); + let pts = |s: usize| f.streams[s].units.iter().map(|u| u.pts.unwrap()).collect::>(); + // one timeline: audio starts 1500 ticks after video (-1000 and 500 around the wrap), whichever + // stream the unwrapper saw first, and video steps by 2160 + let (a, v) = (pts(0), pts(1)); + assert_eq!(a[0] - v[0], 1500, "audio_first {audio_first}: audio {a:?} video {v:?}"); + assert_eq!(v[1] - v[0], 2160, "video {v:?}"); + } +} + +#[test] +fn a_late_pre_wrap_timestamp_first_after_the_wrap_goes_below_zero() { + let mut u = Unwrap::default(); + assert_eq!(u.unwrap(5), 5); + // a B picture from just before the wrap, arriving after the wrapped one + assert_eq!(u.unwrap((1 << 33) - 3), -3); + assert_eq!(u.unwrap(10), 10, "the late one did not shift the timeline"); +} + +#[test] +fn a_forward_jump_from_a_small_first_timestamp_is_followed() { + // spliced capture: new time base far above the first value, no wrap involved + let mut u = Unwrap::default(); + let a = u.unwrap(90_000); + let b = u.unwrap(0x1_8000_0000); + let c = u.unwrap(0x1_8000_0000 + 3_000); + assert_eq!((a, b, c), (90_000, 0x1_8000_0000, 0x1_8000_0000 + 3_000)); +} + +#[test] +fn a_forward_jump_after_a_wrap_stays_in_the_current_epoch() { + let wrap = 1i64 << 33; + let mut u = Unwrap::default(); + assert_eq!(u.unwrap(wrap - 1000), wrap - 1000); + assert_eq!(u.unwrap(500), wrap + 500); + let jump = 0x1_8000_0000; + assert_eq!(u.unwrap(jump), wrap + jump); + assert_eq!(u.unwrap(jump + 3000), wrap + jump + 3000); +} + +#[test] +fn program_streams_share_their_initial_wrap_epoch() { + let wrap = 1i64 << 33; + for audio_first in [false, true] { + let video = pes(0xE0, Some(wrap - 1000), None, &mpeg2_frame(1, 0, false, 100), true); + let audio = pes(0xC0, Some(500), None, &mp2_frame(0), true); + let mut out = ps_pack().to_vec(); + if audio_first { + out.extend(audio); + out.extend(video); + } else { + out.extend(video); + out.extend(audio); + } + out.extend([0, 0, 1, 0xB9]); + let f = open(&out).unwrap(); + let pts = |id| { + f.streams + .iter() + .find(|s| s.id == (StreamId::Ps { stream_id: id, sub_id: None })) + .and_then(|s| s.units.first()) + .and_then(|u| u.pts) + .unwrap() + }; + assert_eq!(pts(0xC0) - pts(0xE0), 1500, "audio_first {audio_first}"); + } +} + +#[test] +fn a_program_stream_first_seen_after_a_wrap_joins_the_current_epoch() { + let wrap = 1i64 << 33; + let mut out = ps_pack().to_vec(); + out.extend(pes(0xC0, Some(wrap - 1000), None, &mp2_frame(0), true)); + out.extend(pes(0xC0, Some(500), None, &mp2_frame(1), true)); + out.extend(pes(0xC1, Some(600), None, &mp2_frame(2), true)); + out.extend([0, 0, 1, 0xB9]); + let f = open(&out).unwrap(); + let pts = |id| { + f.streams.iter().find(|s| s.id == (StreamId::Ps { stream_id: id, sub_id: None })).and_then(|s| s.units.first()).and_then(|u| u.pts).unwrap() + }; + assert_eq!(pts(0xC1), wrap + 600); +} + +#[test] +fn program_stream_scr_is_unwrapped_and_ordered() { + // two packs, the SCR wraps between them: the range is first..last, not a 2^33 jump backwards + fn scr_pack(base: i64) -> Vec { + let b = base & ((1 << 33) - 1); + let mut v = vec![0, 0, 1, 0xBA]; + v.extend([ + 0x44 | (((b >> 30) & 7) as u8) << 3 | ((b >> 28) & 3) as u8, + (b >> 20) as u8, + 0x04 | (((b >> 15) & 0x1F) as u8) << 3 | ((b >> 13) & 3) as u8, + (b >> 5) as u8, + 0x04 | ((b & 0x1F) as u8) << 3, + 1, + 1, + 0x89, + 0xC3, + 0xF8, + ]); + v + } + let near = (1i64 << 33) - 1000; + let mut out = scr_pack(near); + out.extend(pes(0xE0, Some(0), None, &mpeg2_frame(1, 0, false, 100), true)); + out.extend(scr_pack(2000)); + out.extend(pes(0xE0, Some(3600), None, &mpeg2_frame(2, 1, false, 100), true)); + out.extend([0, 0, 1, 0xB9]); + let f = open(&out).unwrap(); + assert_eq!(f.pcr_range, Some((near * 300, ((1 << 33) + 2000) * 300))); +} + +#[test] +fn language_descriptor_accepts_only_three_letters() { + let cases: [([u8; 3], Option<&str>); 5] = [(*b"ger", Some("ger")), (*b"ENG", Some("eng")), ([0, 0, 0], None), (*b"e\0g", None), (*b"d e", None)]; + for (code, want) in cases { + let mut desc = vec![0x0A, 4]; + desc.extend(code); + desc.push(0); + let mut mux = TsMux::new(false); + mux.psi_full(&[(0x03, 0x1100, desc)], 0x100); + mux.pes(0x1100, &pes(0xC0, Some(0), None, &mp2_frame(0), true)); + let f = open(&mux.out).unwrap(); + assert_eq!(f.streams[0].language.as_deref(), want, "{code:?}"); + } +} + +/// Audio-only TS: `n` PES packets of two MPEG-1 layer II frames each (7 transport packets apiece). +fn audio_ts(n: u8) -> Vec { + let mut mux = TsMux::new(false); + mux.psi(&[(0x03, 0x1100)]); + for k in 0..n { + let a: Vec = [mp2_frame(2 * k), mp2_frame(2 * k + 1)].concat(); + mux.pes(0x1100, &pes(0xC0, Some(90_000 + 4320 * k as i64), None, &a, true)); + } + mux.out +} + +/// Byte offset of the `n`-th (0-based) packet of `pid` that has no unit start. +fn nth_continuation(data: &[u8], pid: u16, n: usize) -> usize { + (0..data.len() / 188) + .map(|i| i * 188) + .filter(|&o| data[o] == 0x47 && (((data[o + 1] & 0x1F) as u16) << 8 | data[o + 2] as u16) == pid && data[o + 1] & 0x40 == 0) + .nth(n) + .expect("packet exists") +} + +fn audio_bytes(f: &File, data: &[u8]) -> Vec> { + let a = f.find(Kind::Audio, |_| true).unwrap(); + (0..f.streams[a].units.len()).map(|i| f.read_unit(data, a, i).unwrap()).collect() +} + +#[test] +fn packet_with_transport_error_indicator_is_dropped() { + let clean = audio_ts(6); + let base = open(&clean).unwrap(); + assert!(base.warnings.is_empty(), "{:?}", base.warnings); + let mut data = clean.clone(); + let o = nth_continuation(&data, 0x1100, 10); + data[o + 1] |= 0x80; + // a corrupted payload must not reach the splitter either + data[o + 20] ^= 0xFF; + let f = open(&data).unwrap(); + assert!(f.warnings.iter().any(|w| w.contains("1 packet(s) with the transport error indicator")), "{:?}", f.warnings); + let a = f.find(Kind::Audio, |_| true).unwrap(); + let total = |f: &File| f.streams[a].units.iter().map(|u| u.size as u64).sum::(); + assert!(total(&f) < total(&base), "the 184 payload bytes of the flagged packet are gone"); + for unit in audio_bytes(&f, &data) { + assert!(!unit.is_empty()); + } +} + +/// An Annex B NAL unit: start code, header bytes and `n` bytes of payload (no zero runs). +fn nal(header: &[u8], body: &[u8]) -> Vec { + let mut v = vec![0, 0, 0, 1]; + v.extend(header); + v.extend(body); + v +} + +/// A slice of `n` filler bytes after the first byte of the slice header (0x88: first_mb 0). +fn slice(header: &[u8], first: u8, n: usize) -> Vec { + let mut body = vec![first]; + body.extend((0..n).map(|i| 0x40 | (i % 31) as u8)); + nal(header, &body) +} + +const AUD: [u8; 2] = [0x09, 0xF0]; + +fn h264_idr(n: usize) -> Vec { + [nal(&AUD, &[]), nal(&[0x67], &[0x42, 0x80, 0x1E]), nal(&[0x68], &[0xCE, 0x38, 0x80]), slice(&[0x65], 0x88, n)].concat() +} + +fn h264_p(n: usize) -> Vec { + [nal(&AUD, &[]), slice(&[0x41], 0x88, n)].concat() +} + +/// A non-reference B picture (nal_ref_idc 0). +fn h264_b(n: usize) -> Vec { + [nal(&AUD, &[]), slice(&[0x01], 0x88, n)].concat() +} + +/// A non-IDR I picture introduced by SEI with a buffering period message and a recovery point. +fn h264_recovery_i(n: usize) -> Vec { + let sei = nal(&[0x06], &[0x00, 0x02, 0xAA, 0xBB, 0x06, 0x01, 0x84, 0x80]); + [nal(&AUD, &[]), sei, slice(&[0x41], 0x88, n)].concat() +} + +fn h264_units(aus: &[(Option, Vec)]) -> (Vec, File) { + let mut mux = TsMux::new(false); + mux.psi(&[(0x1B, 0x1011)]); + for (pts, au) in aus { + mux.pes(0x1011, &pes(0xE0, *pts, None, au, false)); + } + let data = mux.out; + let f = open(&data).unwrap(); + (data, f) +} + +#[test] +fn h264_recovery_point_is_a_random_access_point() { + let aus = [(Some(90_000), h264_idr(300)), (Some(93_600), h264_p(300)), (Some(97_200), h264_recovery_i(300)), (Some(100_800), h264_p(300))]; + let (data, f) = h264_units(&aus); + let s = &f.streams[0]; + assert_eq!(s.codec, Codec::H264); + assert_eq!(s.units.iter().map(|u| u.key).collect::>(), [true, false, true, false]); + for (i, (pts, au)) in aus.iter().enumerate() { + assert_eq!(f.read_unit(&data, 0, i).unwrap(), *au, "unit {i}"); + assert_eq!(s.units[i].pts, *pts); + } + // a stream cut so that it starts at a recovery point (no IDR at all) has a key unit + let (_, f) = h264_units(&[(Some(1000), h264_recovery_i(400)), (Some(4600), h264_p(400)), (Some(8200), h264_p(400))]); + assert_eq!(f.streams[0].units.iter().map(|u| u.key).collect::>(), [true, false, false]); + // SEI without a recovery point message is not one + let sei = nal(&[0x06], &[0x00, 0x02, 0xAA, 0xBB, 0x80]); + let au = [nal(&AUD, &[]), sei, slice(&[0x41], 0x88, 600)].concat(); + let (_, f) = h264_units(&[(Some(1000), au)]); + assert!(!f.streams[0].units[0].key); +} + +#[test] +fn h264_intra_refresh_recovery_point_is_not_a_random_access_point() { + // recovery_frame_cnt 1 (ue(v) "010"): decoding from here shows broken pictures + let sei = nal(&[0x06], &[0x00, 0x02, 0xAA, 0xBB, 0x06, 0x01, 0x44, 0x80]); + let au = [nal(&AUD, &[]), sei, slice(&[0x41], 0x88, 300)].concat(); + let (_, f) = h264_units(&[(Some(1000), au), (Some(4600), h264_p(300))]); + assert_eq!(f.streams[0].units.iter().map(|u| u.key).collect::>(), [false, false]); +} + +#[test] +fn h264_several_access_units_in_one_pes_are_separate_units() { + // IDR, then in one PES a non-reference B picture and a reference P picture, only the first + // access unit of the PES has a timestamp + let (idr, b, p) = (h264_idr(400), h264_b(300), h264_p(250)); + let (data, f) = h264_units(&[(Some(90_000), idr.clone()), (Some(93_600), [b.clone(), p.clone()].concat()), (Some(100_800), h264_p(100))]); + let s = &f.streams[0]; + assert_eq!(s.units.len(), 4); + assert_eq!(s.units.iter().map(|u| u.pts).collect::>(), [Some(90_000), Some(93_600), None, Some(100_800)]); + assert_eq!(s.units.iter().map(|u| u.key).collect::>(), [true, false, false, false]); + assert_eq!(s.units.iter().map(|u| u.disposable).collect::>(), [false, true, false, false]); + assert_eq!(f.read_unit(&data, 0, 0).unwrap(), idr); + assert_eq!(f.read_unit(&data, 0, 1).unwrap(), b); + assert_eq!(f.read_unit(&data, 0, 2).unwrap(), p); +} + +#[test] +fn h264_units_without_delimiters_split_at_the_first_slice() { + // no AUD or SEI: a slice with first_mb_in_slice 0 starts the next access unit, a further + // slice of the same picture (first_mb != 0) does not + let two_slices = [slice(&[0x41], 0x88, 300), slice(&[0x41], 0x42, 300)].concat(); + let idr = slice(&[0x65], 0x88, 200); + let (data, f) = h264_units(&[(Some(0), [idr.clone(), two_slices.clone(), two_slices.clone()].concat())]); + let s = &f.streams[0]; + assert_eq!(s.units.len(), 3); + assert_eq!(s.units.iter().map(|u| u.key).collect::>(), [true, false, false]); + assert_eq!(f.read_unit(&data, 0, 1).unwrap(), two_slices); + assert_eq!(f.read_unit(&data, 0, 0).unwrap(), idr); +} + +#[test] +fn h264_one_access_unit_per_pes_is_unchanged() { + // parameter sets inside the access unit (after the AUD, before the slices) do not split it + let aus: Vec<(Option, Vec)> = + (0..6).map(|k| (Some(90_000 + 3600 * k), if k % 3 == 0 { h264_idr(500) } else { h264_p(150 + 70 * k as usize) })).collect(); + let (data, f) = h264_units(&aus); + let s = &f.streams[0]; + assert_eq!(s.units.len(), 6); + for (i, (pts, au)) in aus.iter().enumerate() { + assert_eq!(f.read_unit(&data, 0, i).unwrap(), *au); + assert_eq!(s.units[i].pts, *pts); + assert_eq!(s.units[i].key, i % 3 == 0); + assert!(!s.units[i].disposable); + } +} + +#[test] +fn scrambled_packet_is_skipped_with_a_warning() { + let clean = audio_ts(6); + let base = open(&clean).unwrap(); + let mut data = clean.clone(); + let o = nth_continuation(&data, 0x1100, 10); + data[o + 3] |= 0x80; // transport_scrambling_control = 2 (even key) + let f = open(&data).unwrap(); + assert!(f.warnings.iter().any(|w| w.contains("1 scrambled packet(s) skipped")), "{:?}", f.warnings); + assert!(!f.warnings.iter().any(|w| w.contains("continuity")), "{:?}", f.warnings); + let a = f.find(Kind::Audio, |_| true).unwrap(); + let total = |f: &File| f.streams[a].units.iter().map(|u| u.size as u64).sum::(); + assert!(total(&f) < total(&base)); +} + +#[test] +fn duplicate_packet_is_dropped_but_a_different_payload_with_the_same_counter_is_kept() { + let clean = audio_ts(6); + let base = open(&clean).unwrap(); + let expect = audio_bytes(&base, &clean); + let o = nth_continuation(&clean, 0x1100, 10); + // exact duplicate right behind the original + let mut dup = clean.clone(); + let copy = dup[o..o + 188].to_vec(); + dup.splice(o + 188..o + 188, copy); + let f = open(&dup).unwrap(); + assert!(f.warnings.iter().any(|w| w.contains("1 duplicate packet(s) dropped")), "{:?}", f.warnings); + assert!(!f.warnings.iter().any(|w| w.contains("continuity")), "{:?}", f.warnings); + assert_eq!(audio_bytes(&f, &dup), expect, "the repeated payload is not fed twice"); + // same counter but other content: not a duplicate, kept + let mut other = clean.clone(); + let mut copy = other[o..o + 188].to_vec(); + copy[187] ^= 0x55; + other.splice(o + 188..o + 188, copy); + let f = open(&other).unwrap(); + assert!(!f.warnings.iter().any(|w| w.contains("duplicate")), "{:?}", f.warnings); + let a = f.find(Kind::Audio, |_| true).unwrap(); + let total = |f: &File| f.streams[a].units.iter().map(|u| u.size as u64).sum::(); + assert!(total(&f) > total(&base), "the differing packet's payload is kept"); +} + +/// A PMT section with the given program, version, applicability, PCR PID and streams (valid CRC). +fn pmt_section_for(program: u16, version: u8, current_next: bool, pcr_pid: u16, streams: &[(u8, u16)]) -> Vec { + let mut pmt = vec![ + 0x02, + 0xB0, + 0, + (program >> 8) as u8, + program as u8, + 0xC0 | (version << 1) | current_next as u8, + 0, + 0, + 0xE0 | (pcr_pid >> 8) as u8, + pcr_pid as u8, + 0xF0, + 0, + ]; + for &(st, pid) in streams { + pmt.extend([st, 0xE0 | (pid >> 8) as u8, pid as u8, 0xF0, 0]); + } + let len = pmt.len() - 3 + 4; + pmt[1] = 0xB0 | (len >> 8) as u8; + pmt[2] = len as u8; + pmt +} + +/// A PMT section for program 1 with the given version / current_next / streams (valid CRC). +fn pmt_section(version: u8, current_next: bool, streams: &[(u8, u16)]) -> Vec { + pmt_section_for(1, version, current_next, 0x100, streams) +} + +#[test] +fn later_pmt_adds_streams_but_never_changes_or_removes_known_ones() { + let mut mux = TsMux::new(false); + mux.psi(&[(0x03, 0x1100)]); + let audio = |mux: &mut TsMux, k: u8| { + let a: Vec = [mp2_frame(2 * k), mp2_frame(2 * k + 1)].concat(); + mux.pes(0x1100, &pes(0xC0, Some(90_000 + 4320 * k as i64), None, &a, true)); + }; + audio(&mut mux, 0); + // version 1: the PID becomes AAC and a second stream appears; version 2: PID removed + mux.section(0x100, &pmt_section(1, true, &[(0x0F, 0x1100), (0x03, 0x1200)])); + audio(&mut mux, 1); + mux.section(0x100, &pmt_section(2, true, &[(0x03, 0x1200)])); + mux.section(0x100, &pmt_section(2, true, &[(0x03, 0x1200)])); + audio(&mut mux, 2); + let f = open(&mux.out).unwrap(); + assert!(f.streams.iter().any(|s| s.id == StreamId::Pid(0x1200)), "the PID added by a later PMT is read"); + assert_eq!(f.streams[0].id, StreamId::Pid(0x1100)); + assert_eq!(f.streams[0].codec, Codec::MpegAudio); + assert_eq!(f.streams[0].units.len(), 6, "audio kept flowing through the first PMT's splitter"); + assert_eq!(f.warnings.iter().filter(|w| w.contains("program map table changed")).count(), 1, "{:?}", f.warnings); +} + +#[test] +fn audio_pid_announced_in_a_later_pmt_is_read_without_warning() { + let mut mux = TsMux::new(false); + mux.psi(&[(0x03, 0x1100)]); + let a: Vec = [mp2_frame(0), mp2_frame(1)].concat(); + mux.pes(0x1100, &pes(0xC0, Some(90_000), None, &a, true)); + // version 1 keeps 0x1100 as it was and announces a second audio PID + mux.section(0x100, &pmt_section(1, true, &[(0x03, 0x1100), (0x03, 0x1200)])); + let b: Vec = [mp2_frame(2), mp2_frame(3)].concat(); + mux.pes(0x1200, &pes(0xC0, Some(90_000 + 8640), None, &b, true)); + let f = open(&mux.out).unwrap(); + let late = f.streams.iter().find(|s| s.id == StreamId::Pid(0x1200)).expect("late audio PID"); + assert!(!late.units.is_empty(), "the late stream has units"); + assert!(f.warnings.iter().all(|w| !w.contains("program map table")), "{:?}", f.warnings); +} + +#[test] +fn pmt_not_yet_applicable_is_ignored() { + let mut mux = TsMux::new(false); + let pat = [0x00, 0xB0, 13, 0, 1, 0xC1, 0, 0, 0, 1, 0xE1, 0x00]; + mux.section(0, &pat); + // current_next_indicator 0: describes a future table, must not be used + mux.section(0x100, &pmt_section(3, false, &[(0x03, 0x1200)])); + mux.section(0x100, &pmt_section(0, true, &[(0x03, 0x1100)])); + let a: Vec = [mp2_frame(0), mp2_frame(1)].concat(); + mux.pes(0x1100, &pes(0xC0, Some(90_000), None, &a, true)); + let f = open(&mux.out).unwrap(); + assert_eq!(f.streams.len(), 1); + assert_eq!(f.streams[0].id, StreamId::Pid(0x1100)); + assert!(f.warnings.is_empty(), "{:?}", f.warnings); +} + +#[test] +fn a_bad_crc_on_the_current_pmt_version_is_reported() { + let mut mux = TsMux::new(false); + mux.psi(&[(0x03, 0x1100)]); + mux.section(0x100, &pmt_section(0, true, &[(0x03, 0x1100)])); + // A short PSI section is placed at the end of its stuffed packet, so the final byte is CRC. + if let Some(last) = mux.out.last_mut() { + *last ^= 1; + } + mux.pes(0x1100, &pes(0xC0, Some(90_000), None, &mp2_frame(0), true)); + let f = open(&mux.out).unwrap(); + assert!(f.warnings.iter().any(|w| w == "1 PSI section(s) with bad CRC"), "{:?}", f.warnings); +} + +#[test] +fn a_pmt_for_another_program_on_the_same_pid_is_ignored() { + let mut mux = TsMux::new(false); + let pat = [0x00, 0xB0, 13, 0, 1, 0xC1, 0, 0, 0, 1, 0xE1, 0x00]; + mux.section(0, &pat); + // The other program deliberately has the same PMT version and arrives first. + mux.section(0x100, &pmt_section_for(2, 0, true, 0x102, &[(0x03, 0x1200)])); + mux.section(0x100, &pmt_section_for(1, 0, true, 0x101, &[(0x03, 0x1100)])); + mux.pcr(0x101, 1000); + mux.pcr(0x101, 2000); + mux.pcr(0x102, 50_000); + mux.pes(0x1100, &pes(0xC0, Some(90_000), None, &mp2_frame(0), true)); + let f = open(&mux.out).unwrap(); + assert_eq!(f.program, Some(1)); + assert_eq!(f.streams.len(), 1); + assert_eq!(f.streams[0].id, StreamId::Pid(0x1100)); + assert_eq!(f.pcr_range, Some((1000 * 300, 2000 * 300))); +} + +#[test] +fn hevc_several_access_units_in_one_pes_are_separate_units() { + let aud = nal(&[0x46, 0x01], &[0x50]); + let idr = [aud.clone(), slice(&[0x26, 0x01], 0x80, 300)].concat(); + // TRAIL_N picture: sub-layer non-reference + let trail_n = [aud.clone(), slice(&[0x00, 0x01], 0x80, 300)].concat(); + let trail_r = [aud, slice(&[0x02, 0x01], 0x80, 200)].concat(); + let mut mux = TsMux::new(false); + mux.psi(&[(0x24, 0x1011)]); + mux.pes(0x1011, &pes(0xE0, Some(90_000), None, &idr, false)); + mux.pes(0x1011, &pes(0xE0, Some(93_600), None, &[trail_n.clone(), trail_r.clone()].concat(), false)); + let f = open(&mux.out).unwrap(); + let s = &f.streams[0]; + assert_eq!(s.codec, Codec::Hevc); + assert_eq!(s.units.iter().map(|u| u.pts).collect::>(), [Some(90_000), Some(93_600), None]); + assert_eq!(s.units.iter().map(|u| u.key).collect::>(), [true, false, false]); + assert_eq!(s.units.iter().map(|u| u.disposable).collect::>(), [false, true, false]); + assert_eq!(f.read_unit(&mux.out, 0, 1).unwrap(), trail_n); + assert_eq!(f.read_unit(&mux.out, 0, 2).unwrap(), trail_r); +} + +fn adts_frame(k: u8) -> Vec { + let mut v = vec![0xFF, 0xF1, 0x50, 0x80, 0x0C, 0x9F, 0xFC]; + v.extend([k; 93]); + v +} + +#[test] +fn non_pes_payload_is_dropped_until_the_next_unit_start() { + // a unit start whose payload is not a PES header, then continuation packets that happen to + // hold ADTS frames: nothing of it may become a unit + let mut mux = TsMux::new(false); + mux.psi(&[(0x0F, 0x1100)]); + mux.packet(0x1100, true, &[0x55; 184]); + for k in 0..10 { + mux.packet(0x1100, false, &adts_frame(k)); + } + let f = open(&mux.out).unwrap(); + assert_eq!(f.streams.first().map(|s| s.units.len()), Some(0)); + // a real PES packet afterwards is indexed again + let mut mux2 = TsMux::new(false); + mux2.psi(&[(0x0F, 0x1100)]); + mux2.packet(0x1100, true, &[0x55; 184]); + mux2.packet(0x1100, false, &adts_frame(1)); + mux2.pes(0x1100, &pes(0xC0, Some(9000), None, &adts_frame(2), true)); + let f = open(&mux2.out).unwrap(); + let u = &f.streams[0].units; + assert_eq!(u.len(), 1); + assert_eq!(u[0].pts, Some(9000)); +} + +#[test] +fn adaptation_field_only_unit_start_keeps_the_pes_in_progress() { + let mut mux = TsMux::new(false); + mux.psi(&[(0x03, 0x1100)]); + let data = pes(0xC0, Some(9000), None, &[mp2_frame(0), mp2_frame(1)].concat(), true); + mux.packet(0x1100, true, &data[..184]); + // PUSI set, adaptation field only (no payload) + let cc = mux.cc.get(&0x1100).copied().unwrap_or(0); + let mut af = vec![0x47, 0x40 | 0x11, 0x00, 0x20 | cc, 183, 0x00]; + af.resize(188, 0xFF); + mux.out.extend(af); + for chunk in data[184..].chunks(184) { + mux.packet(0x1100, false, chunk); + } + let f = open(&mux.out).unwrap(); + let s = &f.streams[0]; + assert_eq!(s.units.len(), 2); + assert_eq!(s.units[0].pts, Some(9000)); + assert_eq!(f.read_unit(&mux.out, 0, 1).unwrap(), mp2_frame(1)); +} + +#[test] +fn oversized_unit_is_refused_without_reserving_it() { + let f = File { + format: Format::Ts { packet_size: 188, sync_offset: 0 }, + streams: vec![Stream { + id: StreamId::Pid(0x100), + stream_type: 0x1B, + codec: Codec::H264, + language: None, + units: vec![Unit { pts: None, dts: None, key: true, disposable: false, size: u32::MAX, pos: 0, offset: 0, picture: None }], + lpcm: None, + pes_packets: 0, + skipped_bytes: 0, + }], + program: None, + pcr_range: None, + warnings: Vec::new(), + }; + assert!(matches!(f.read_unit(&Vec::::new(), 0, 0), Err(Error::Invalid(_)))); +} + +/// A `ByteSource` that counts the bytes requested through `read_at`. +struct Counting<'a> { + data: &'a [u8], + read: std::cell::Cell, +} + +impl ByteSource for Counting<'_> { + fn len(&self) -> u64 { + self.data.len() as u64 + } + fn read_at(&self, offset: u64, buf: &mut [u8]) -> std::io::Result<()> { + self.read.set(self.read.get() + buf.len() as u64); + self.data.read_at(offset, buf) + } +} + +#[test] +fn bad_adaptation_fields_do_not_amplify_reads() { + // aligned packets whose adaptation_field_length (255) overruns the packet: the packet grid is + // intact, so this must cost one pass over the file, not one block read per packet + let mut data = Vec::new(); + for _ in 0..3000 { + data.extend([0x47, 0x11, 0x00, 0x30]); + data.extend(std::iter::repeat_n(0xFF, 184)); + } + let src = Counting { data: &data, read: Default::default() }; + let f = open(&src).unwrap(); + assert!(f.warnings.iter().any(|w| w.contains("adaptation field")), "{:?}", f.warnings); + assert!(!f.warnings.iter().any(|w| w.contains("lost packet sync")), "{:?}", f.warnings); + let read = src.read.get(); + assert!(read <= 4 * data.len() as u64, "read {read} bytes of a {}-byte file", data.len()); +} + +#[test] +fn garbage_without_sync_does_not_amplify_reads() { + // a sync byte every 189 bytes: five-in-a-row never lines up, every 0x47 is a false candidate + let mut data = Vec::new(); + for _ in 0..3000 { + data.extend([0x47]); + data.extend(std::iter::repeat_n(0x11, 188)); + } + let head: Vec = (0..188 * 8).map(|i| if i % 188 == 0 { 0x47 } else { 0 }).collect(); + let mut all = head; + all.extend(data); + let src = Counting { data: &all, read: Default::default() }; + let f = open(&src).unwrap(); + assert!(f.warnings.iter().any(|w| w.contains("lost packet sync")), "{:?}", f.warnings); + let read = src.read.get(); + assert!(read <= 4 * all.len() as u64, "read {read} bytes of a {}-byte file", all.len()); +} + +#[test] +fn transport_stream_resyncs_after_garbage() { + const BLOCK_PACKETS: usize = 4096; + for m2ts in [false, true] { + let ps = if m2ts { 192 } else { 188 }; + // garbage in front of the stream (shorter than 8 packets) and, at a few places around the + // first block boundary, between two frames; lengths that are not a multiple of the packet + for (delta, glen) in [(0usize, 100usize), (1, 37), (2, 188), (3, 301), (5, 5), (8, 1000)] { + let edge = (BLOCK_PACKETS - delta) * ps; + let mut mux = TsMux::new(m2ts); + mux.out.extend([0x11, 0x47, 0x22]); // garbage prefix with a lone 0x47 + mux.psi(&[(0x02, 0x1011)]); + let mut expect = Vec::new(); + let mut placed = false; + let mut k = 0usize; + while k < 3000 || !placed { + if !placed && mux.out.len() >= edge { + // garbage between two PES packets, with lone sync bytes inside + let mut g: Vec = (0..glen).map(|i| 0x10 + (i % 7) as u8).collect(); + if let Some(b) = g.get_mut(3) { + *b = 0x47; + } + mux.out.extend(g); + placed = true; + } + let f = mpeg2_frame(if k == 0 { 1 } else { 2 }, (k % 1000) as u16, false, 40 + k % 300); + mux.pes(0x1011, &pes(0xE0, Some(90_000 + 3600 * k as i64), None, &f, false)); + expect.push(f); + k += 1; + } + assert!(mux.out.len() > (BLOCK_PACKETS + 4) * ps, "stream must cross a block boundary"); + let data = mux.out; + let f = open(&data).unwrap(); + assert!(f.warnings.iter().any(|w| w.contains("lost packet sync")), "{:?}", f.warnings); + let v = f.find(Kind::Video, |_| true).unwrap(); + let s = &f.streams[v]; + assert_eq!(s.units.len(), expect.len(), "m2ts {m2ts} delta {delta} glen {glen}"); + for (i, fr) in expect.iter().enumerate() { + assert_eq!(&f.read_unit(&data, v, i).unwrap(), fr, "unit {i} (m2ts {m2ts} delta {delta} glen {glen})"); + assert_eq!(s.units[i].pts, Some(90_000 + 3600 * i as i64)); + } + } + } +} diff --git a/crates/media/src/mpegts/tests/hostile.rs b/crates/media/src/mpegts/tests/hostile.rs new file mode 100644 index 000000000..ff1784fc8 --- /dev/null +++ b/crates/media/src/mpegts/tests/hostile.rs @@ -0,0 +1,99 @@ +//! Hostile-input hammer: truncation, bit flips and extreme field values must never panic or hang. + +use super::*; + +fn exercise(d: &[u8]) { + let data = d.to_vec(); + let _ = sniff(d); + let Ok(f) = open(&data) else { return }; + for (s, st) in f.streams.iter().enumerate() { + let _ = (st.kind(), st.pts_range(), st.codec.name()); + let n = st.units.len(); + for i in [0, n / 2, n.saturating_sub(1), n, usize::MAX] { + let _ = f.read_unit(&data, s, i); + } + } + let _ = f.find(Kind::Video, |_| true); +} + +fn ts_seed(m2ts: bool) -> Vec { + let mut mux = TsMux::new(m2ts); + mux.psi(&[(0x02, 0x1011), (0x0F, 0x1100), (0x1B, 0x1200), (0x81, 0x1300), (0x24, 0x1400), (0x03, 0x1500)]); + for k in 0..6u16 { + mux.pes( + 0x1011, + &pes(0xE0, Some(3600 * k as i64), Some(3600 * k as i64 - 7200), &mpeg2_frame(if k == 0 { 1 } else { 3 }, k, k % 2 == 1, 400), false), + ); + mux.pes(0x1100, &pes(0xC0, Some(1920 * k as i64), None, &adts_frame(k as u8), true)); + mux.pes(0x1200, &pes(0xE1, Some(3600 * k as i64), None, &[0, 0, 0, 1, 0x09, 0xF0, 0, 0, 1, 0x65, 0x88, 1, 2, 3], false)); + let mut ac3 = vec![0x0B, 0x77, 0, 0, 30, 0x40]; + ac3.extend(std::iter::repeat_n(k as u8, 1792 - 6)); + mux.pes(0x1300, &pes(0xBD, Some(2880 * k as i64), None, &ac3, true)); + mux.pes(0x1400, &pes(0xE2, Some(3600 * k as i64), None, &[0, 0, 0, 1, 0x46, 0x01, 0x50, 0, 0, 0, 1, 0x26, 0x01, 0xAF, 1, 2], false)); + mux.pes(0x1500, &pes(0xC1, Some(2880 * k as i64), None, &mp2_frame(k as u8), true)); + } + mux.out +} + +fn ps_seed() -> Vec { + let frames: Vec> = (0..5).map(|k| mpeg2_frame(if k == 0 { 1 } else { 2 }, k as u16, k == 3, 900 + 100 * k)).collect(); + let es: Vec = frames.concat(); + let mut out = Vec::new(); + let mut a = 0u8; + for (i, chunk) in es.chunks(700).enumerate() { + out.extend([0, 0, 1, 0xBA, 0x44, 0, 4, 0, 4, 1, 1, 0x89, 0xC3, 0xF8]); + out.extend(pes(0xE0, Some(3600 * i as i64), None, chunk, true)); + let mut ac3 = vec![0x80, 1, 0, 1, 0x0B, 0x77, 0, 0, 30, 0x40]; + ac3.extend(std::iter::repeat_n(a, 1792 - 6)); + a += 1; + out.extend(pes(0xBD, Some(1000 + 2880 * a as i64), None, &ac3, true)); + // LPCM in private stream 1, system header and PSM-ish noise between packs + out.extend([0, 0, 1, 0xBB, 0, 6, 0x80, 0, 1, 4, 0xE1, 0xFF]); + out.extend(pes(0xBD, Some(5000 + 100 * i as i64), None, &[0xA0, 1, 0, 4, 0, 0x01, 0x81, 1, 2, 3, 4, 5, 6, 7, 8], true)); + } + out.extend([0, 0, 1, 0xB9]); + out +} + +#[test] +fn hostile_input_never_panics() { + let mut seeds = vec![ts_seed(false), ts_seed(true), ps_seed()]; + seeds.push(work_tests::big_program_stream(false, 40).0); + seeds.push(work_tests::big_program_stream(true, 40).0); + // fewer rounds than FilmCraft's 40 000: tests here build without optimisation, and the two + // large program streams cost a megabyte of window refill per unit read + for (i, s) in seeds.iter().enumerate() { + craft_media_testkit::hostile::hammer(&format!("mpegts seed {i}"), s, if i < 3 { 4_000 } else { 150 }, exercise); + } +} + +#[test] +fn elementary_stream_frame_parsers_never_panic() { + let codecs = [ + Codec::Mpeg1Video, + Codec::Mpeg2Video, + Codec::H264, + Codec::Hevc, + Codec::MpegAudio, + Codec::AacAdts, + Codec::AacLatm, + Codec::Ac3, + Codec::Eac3, + Codec::Dts, + Codec::TrueHd, + Codec::LpcmBluray, + Codec::LpcmDvd, + Codec::Unknown(0x55), + ]; + let mut ac3 = vec![0x0B, 0x77, 0, 0, 30, 0x40]; + ac3.extend([1u8; 60]); + let seeds = [adts_frame(3), mp2_frame(1), ac3, mpeg2_frame(1, 0, false, 64), vec![0x56, 0xE0, 0x10, 0x20, 0x30, 0x40, 0x50, 0x60, 0x70, 0x80]]; + for (i, s) in seeds.iter().enumerate() { + craft_media_testkit::hostile::hammer(&format!("es seed {i}"), s, 40_000, |d| { + for c in &codecs { + let _ = frame_bytes(c, d); + let _ = frame_info(c, d); + } + }); + } +} diff --git a/crates/media/src/mpegts/ts.rs b/crates/media/src/mpegts/ts.rs new file mode 100644 index 000000000..a4c01a986 --- /dev/null +++ b/crates/media/src/mpegts/ts.rs @@ -0,0 +1,749 @@ +//! Transport streams (H.222.0 §2.4.3): packets, PSI (PAT/PMT), PES reassembly. + +use std::collections::HashMap; + +use super::es::Splitter; +use super::pes::{self, PesHeader}; +use super::{ByteSource, ClockRange, Codec, Error, File, Format, Result, Stream, StreamId, Unit, Unwrap, read_some}; + +/// Byte-wise table for the MSB-first CRC-32 (polynomial 0x04C11DB7): entry `i` is the CRC register +/// after shifting the byte `i` through eight bit steps. +const CRC_TABLE: [u32; 256] = { + let mut t = [0u32; 256]; + let mut i = 0; + while i < 256 { + let mut crc = (i as u32) << 24; + let mut bit = 0; + while bit < 8 { + crc = if crc & 0x8000_0000 != 0 { (crc << 1) ^ 0x04C1_1DB7 } else { crc << 1 }; + bit += 1; + } + t[i] = crc; + i += 1; + } + t +}; + +/// CRC-32 of PSI sections (MSB-first, polynomial 0x04C11DB7, initial value all ones; Annex A). +pub(crate) fn crc32_mpeg(data: &[u8]) -> u32 { + let mut crc = 0xFFFF_FFFFu32; + for &b in data { + crc = (crc << 8) ^ CRC_TABLE[((crc >> 24) as u8 ^ b) as usize]; + } + crc +} + +/// A packet's fields. +struct Packet<'a> { + pusi: bool, + pid: u16, + cc: u8, + has_payload: bool, + discontinuity: bool, + pcr: Option, + payload: &'a [u8], +} + +/// Why a packet could not be parsed. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +enum Bad { + /// No sync byte (or too short): the packet grid is lost. + Sync, + /// Sync byte present but the adaptation field overruns the packet: the grid is intact, the + /// packet carries nothing usable. + Adaptation, +} + +fn packet(p: &[u8]) -> std::result::Result, Bad> { + if p.len() < 188 || p[0] != 0x47 { + return Err(Bad::Sync); + } + let pusi = p[1] & 0x40 != 0; + let pid = (((p[1] & 0x1F) as u16) << 8) | p[2] as u16; + let afc = (p[3] >> 4) & 3; + let cc = p[3] & 15; + let mut start = 4; + let mut pcr = None; + let mut discontinuity = false; + if afc & 2 != 0 { + let al = p[4] as usize; + start = 5 + al; + if start > 188 { + return Err(Bad::Adaptation); + } + if al > 0 { + let flags = p[5]; + discontinuity = flags & 0x80 != 0; + if flags & 0x10 != 0 && al >= 7 { + let base = ((p[6] as i64) << 25) | ((p[7] as i64) << 17) | ((p[8] as i64) << 9) | ((p[9] as i64) << 1) | (p[10] as i64 >> 7); + let ext = (((p[10] & 1) as i64) << 8) | p[11] as i64; + pcr = Some(base * 300 + ext); + } + } + } + let has_payload = afc & 1 != 0; + Ok(Packet { pusi, pid, cc, has_payload, discontinuity, pcr, payload: if has_payload { &p[start..188] } else { &[] } }) +} + +/// `(transport_error_indicator, scrambled)` of a packet whose first byte is the sync byte (H.222.0 +/// §2.4.3.3). Both are false for anything without a sync byte or too short for the header. +fn skip_flags(p: &[u8]) -> (bool, bool) { + match (p.first(), p.get(1), p.get(3)) { + (Some(0x47), Some(b1), Some(b3)) => (b1 & 0x80 != 0, b3 >> 6 != 0), + _ => (false, false), + } +} + +/// Drops an exact duplicate packet (§2.4.3.3: a packet may be sent twice, same continuity counter +/// and same content). Conservative: only a payload-bearing packet with the previous payload-bearing +/// packet's counter and identical payload bytes counts; a packet that signals a discontinuity +/// starts a new sequence and is never a duplicate; anything else is kept. +struct DupGuard { + cc: Option, + len: usize, + data: [u8; 188], +} + +impl Default for DupGuard { + fn default() -> Self { + Self { cc: None, len: 0, data: [0; 188] } + } +} + +impl DupGuard { + /// Whether `pk` repeats the previous packet of its PID; remembers `pk` as the previous one. + fn is_dup(&mut self, pk: &Packet<'_>) -> bool { + if pk.discontinuity { + // a restart: the saved counter and payload belong to the old sequence, even when + // this packet carries only an adaptation field + self.cc = None; + } + if !pk.has_payload { + return false; + } + let dup = !pk.discontinuity && self.cc == Some(pk.cc) && self.data.get(..self.len) == Some(pk.payload); + if !dup { + self.cc = Some(pk.cc); + self.len = pk.payload.len().min(self.data.len()); + if let (Some(dst), Some(src)) = (self.data.get_mut(..self.len), pk.payload.get(..self.len)) { + dst.copy_from_slice(src); + } + } + dup + } +} + +/// Reassembles a PES header that may span packets; yields each packet's elementary-stream bytes. +#[derive(Default)] +pub(crate) struct PesAsm { + hdr: Vec, + waiting: bool, + /// The packet that started the current unit was not a PES packet: its continuation packets + /// are dropped until the next unit start. + dropping: bool, +} + +impl PesAsm { + /// The PES header completed by this packet (if any) and the packet's ES payload bytes. + pub fn packet<'a>(&mut self, pusi: bool, payload: &'a [u8]) -> (Option, &'a [u8]) { + if pusi { + if payload.is_empty() { + // an adaptation-field-only packet carries no PES data: it must not cut short + // the PES packet in progress + return (None, &[]); + } + self.hdr.clear(); + self.waiting = true; + self.dropping = false; + } else if self.dropping { + return (None, &[]); + } else if !self.waiting { + return (None, payload); + } + let before = self.hdr.len(); + self.hdr.extend_from_slice(payload); + // `pes::parse` only succeeds once the whole header (`header_len` bytes) is buffered + if let Some(h) = pes::parse(&self.hdr) { + self.waiting = false; + let skip = h.header_len.saturating_sub(before).min(payload.len()); + return (Some(h), &payload[skip..]); + } + if self.hdr.len() > 1024 || (self.hdr.len() >= 6 && !(self.hdr[0] == 0 && self.hdr[1] == 0 && self.hdr[2] == 1)) { + // not a PES packet after all: drop until the next unit start + self.waiting = false; + self.dropping = true; + self.hdr.clear(); + return (None, &[]); + } + (None, &[]) + } +} + +/// PSI section reassembly for one PID. +#[derive(Default)] +struct Psi { + buf: Vec, +} + +impl Psi { + /// Feed a packet payload; returns completed sections. + fn feed(&mut self, pusi: bool, payload: &[u8]) -> Vec> { + let mut out = Vec::new(); + if pusi { + let Some(&ptr) = payload.first() else { return out }; + let ptr = ptr as usize; + if !self.buf.is_empty() { + self.buf.extend_from_slice(payload.get(1..1 + ptr).unwrap_or(&[])); + self.drain(&mut out); + } + self.buf = payload.get(1 + ptr..).unwrap_or(&[]).to_vec(); + } else if !self.buf.is_empty() { + self.buf.extend_from_slice(payload); + } + self.drain(&mut out); + out + } + + fn drain(&mut self, out: &mut Vec>) { + while self.buf.len() >= 3 { + if self.buf[0] == 0xFF { + self.buf.clear(); + return; + } + let total = 3 + ((((self.buf[1] & 0x0F) as usize) << 8) | self.buf[2] as usize); + if self.buf.len() < total { + if total > 4096 { + self.buf.clear(); + } + return; + } + out.push(self.buf[..total].to_vec()); + self.buf.drain(..total); + } + } +} + +/// Elementary stream of the selected program. +struct EsState { + stream: Stream, + split: Splitter, + asm: PesAsm, + cc: Option, + dup: DupGuard, +} + +/// Map a PMT stream_type (and the ES descriptors) to a codec. `hdmv`: a Blu-ray / AVCHD stream +/// (registration descriptor "HDMV", or 192-byte packets). +pub(crate) fn codec_of(stream_type: u8, desc: &[u8], hdmv: bool) -> Codec { + let mut tags = Vec::new(); + let mut reg = None; + let mut i = 0; + while i + 2 <= desc.len() { + let (tag, len) = (desc[i], desc[i + 1] as usize); + let body = desc.get(i + 2..i + 2 + len).unwrap_or(&[]); + tags.push(tag); + if tag == 5 && body.len() >= 4 { + reg = Some([body[0], body[1], body[2], body[3]]); + } + i += 2 + len; + } + match stream_type { + 0x01 => Codec::Mpeg1Video, + 0x02 => Codec::Mpeg2Video, + 0x03 | 0x04 => Codec::MpegAudio, + 0x0F => Codec::AacAdts, + 0x11 => Codec::AacLatm, + 0x1B => Codec::H264, + 0x24 => Codec::Hevc, + 0x80 if hdmv => Codec::LpcmBluray, + 0x80 => Codec::Mpeg2Video, + 0x81 => Codec::Ac3, + 0x82 | 0x85 | 0x86 | 0xA2 if hdmv => Codec::Dts, + 0x83 if hdmv => Codec::TrueHd, + 0x84 | 0xA1 if hdmv => Codec::Eac3, + 0x87 => Codec::Eac3, + 0x90 if hdmv => Codec::Subtitle("PGS subtitles"), + 0x92 if hdmv => Codec::Subtitle("Text subtitles"), + 0x06 => { + if tags.contains(&0x6A) || reg == Some(*b"AC-3") { + Codec::Ac3 + } else if tags.contains(&0x7A) || reg == Some(*b"EAC3") { + Codec::Eac3 + } else if tags.contains(&0x7B) || matches!(reg, Some([b'D', b'T', b'S', _])) { + Codec::Dts + } else if tags.contains(&0x59) { + Codec::Subtitle("DVB subtitles") + } else if tags.contains(&0x56) { + Codec::Subtitle("Teletext") + } else { + Codec::Unknown(6) + } + } + t => Codec::Unknown(t), + } +} + +fn language(desc: &[u8]) -> Option { + let mut i = 0; + while i + 2 <= desc.len() { + let (tag, len) = (desc[i], desc[i + 1] as usize); + if tag == 0x0A && len >= 3 { + let b = desc.get(i + 2..i + 5)?; + // ISO 639-2 codes are three ASCII letters; anything else is garbage + return b.iter().all(u8::is_ascii_alphabetic).then(|| b.to_ascii_lowercase().iter().map(|&c| c as char).collect()); + } + i += 2 + len; + } + None +} + +/// First file offset at which `packet_size`-byte packets line up (sync byte at `sync_offset`). +fn first_sync(head: &[u8], packet_size: usize, sync_offset: usize) -> Option { + (0..packet_size.min(head.len())).find(|&s| (0..5).all(|k| head.get(s + sync_offset + k * packet_size) == Some(&0x47))) +} + +/// Find where packets line up again, searching `block` from byte `from`: the first packet start +/// `i` whose sync byte and the next four packets' sync bytes are all 0x47. Returns `(i, false)` +/// when found. Returns `(i, true)` when the block ran out first: `i` is where to refill from (a +/// candidate whose five-packet window does not fit yet, or the last place a whole packet fits). +/// At the end of the file (`at_end`) a candidate is accepted with as many sync bytes as exist. +fn resync(block: &[u8], from: usize, packet_size: usize, sync_offset: usize, at_end: bool) -> (usize, bool) { + let mut i = from; + while i + packet_size <= block.len() { + if block.get(i + sync_offset) == Some(&0x47) { + let mut aligned = true; + let mut complete = true; + for k in 1..5 { + match block.get(i + sync_offset + k * packet_size) { + Some(&0x47) => {} + Some(_) => { + aligned = false; + break; + } + None => { + complete = false; + break; + } + } + } + if aligned { + return (i, !complete && !at_end); + } + } + i += 1; + } + (i, true) +} + +/// Register the elementary streams a (CRC-checked) PMT section announces and that are not yet known. +/// For a `later` PMT version, returns whether it changed a known stream's type or left one out. +fn add_pmt_streams(sec: &[u8], packet_size: usize, later: bool, es: &mut HashMap, order: &mut Vec) -> bool { + let mut changed = false; + let mut listed: Vec = Vec::new(); + let pinfo = (((sec[10] & 0x0F) as usize) << 8) | sec[11] as usize; + let prog_desc = sec.get(12..12 + pinfo).unwrap_or(&[]); + let hdmv = packet_size == 192 || prog_desc.windows(4).any(|w| w == b"HDMV"); + let mut i = 12 + pinfo; + let end = sec.len() - 4; + while i + 5 <= end { + let st = sec[i]; + let pid = (((sec[i + 1] & 0x1F) as u16) << 8) | sec[i + 2] as u16; + let ilen = (((sec[i + 3] & 0x0F) as usize) << 8) | sec[i + 4] as usize; + let desc = sec.get(i + 5..(i + 5 + ilen).min(end)).unwrap_or(&[]); + i += 5 + ilen; + listed.push(pid); + if let Some(old) = es.get(&pid) { + if later && old.stream.stream_type != st { + changed = true; + } + continue; + } + let mut codec = codec_of(st, desc, hdmv); + if codec == Codec::Unknown(6) && prog_desc.windows(4).any(|w| w == b"AC-3") { + codec = Codec::Ac3; + } + let stream = Stream { + id: StreamId::Pid(pid), + stream_type: st, + codec: codec.clone(), + language: language(desc), + units: Vec::new(), + lpcm: None, + pes_packets: 0, + skipped_bytes: 0, + }; + es.insert(pid, EsState { stream, split: Splitter::new(&codec), asm: PesAsm::default(), cc: None, dup: DupGuard::default() }); + order.push(pid); + } + changed || (later && es.keys().any(|p| !listed.contains(p))) +} + +/// The PSI state gathered while scanning: the selected program and its PMT, the PMT's PCR_PID +/// and whether a later PMT version added streams mid-stream. +#[derive(Default)] +struct PmtState { + pmt_pid: Option, + program: Option, + pmt: Psi, + pmt_version: Option, + pcr_pid: Option, + pmt_changed: bool, +} + +/// One program clock across every PCR_PID that is active in packet order. Until the first PMT +/// names the clock, each PID carrying a PCR keeps its own candidate (a fixed-size min/max, so at +/// most one per 13-bit PID); the named PID's candidate becomes the clock. Without a PMT, the first +/// PID carrying a PCR stands in. +#[derive(Default)] +struct ProgramClock { + clock: ClockRange, + candidates: HashMap, + first_pid: Option, +} + +impl ProgramClock { + /// A PCR on `pid`, with the PMT's PCR_PID so far. + fn push(&mut self, pcr_pid: Option, pid: u16, pcr: i64) { + match pcr_pid { + Some(p) if p == pid => self.clock.push(pcr), + Some(_) => {} + None => { + self.first_pid.get_or_insert(pid); + self.candidates.entry(pid).or_default().push(pcr); + } + } + } + + /// The first PMT names `pid`: the PCRs it carried before count, the other candidates go + /// (0x1fff, "no PCR PID", has none). + fn named(&mut self, pid: u16) { + self.clock = self.candidates.remove(&pid).unwrap_or_default(); + self.candidates = HashMap::new(); + } + + fn range(&self, pcr_pid: Option) -> Option<(i64, i64)> { + match (pcr_pid, self.first_pid) { + (None, Some(pid)) => self.candidates.get(&pid).and_then(ClockRange::range), + _ => self.clock.range(), + } + } +} + +/// Feed one PAT section stream: the first program's PMT PID is chosen; later PAT repeats +/// cannot change it. +fn feed_pat(pk: &Packet<'_>, pat: &mut Psi, pmt: &mut PmtState, crc_errors: &mut u64) { + for sec in pat.feed(pk.pusi, pk.payload) { + if sec.len() < 12 || sec[0] != 0 { + continue; + } + if sec[5] & 1 == 0 { + // not yet applicable (current_next_indicator 0) + continue; + } + if crc32_mpeg(&sec) != 0 { + *crc_errors += 1; + continue; + } + let body = &sec[8..sec.len() - 4]; + for e in body.as_chunks::<4>().0 { + let num = u16::from_be_bytes([e[0], e[1]]); + let pid = (((e[2] & 0x1F) as u16) << 8) | e[3] as u16; + if num != 0 && pmt.pmt_pid.is_none() { + pmt.pmt_pid = Some(pid); + pmt.program = Some(num); + } + } + } +} + +/// Feed one PMT section stream: the PMT's PCR_PID becomes the file clock and new PIDs are +/// registered; a later PMT version may only add PIDs, existing streams are never re-mapped or +/// dropped. +fn feed_pmt<'a>(pk: &Packet<'a>, pmt: &mut PmtState, packet_size: usize, es: &mut HashMap, order: &mut Vec, crc_errors: &mut u64) { + for sec in pmt.pmt.feed(pk.pusi, pk.payload) { + if sec.len() < 16 || sec[0] != 2 { + continue; + } + // current_next_indicator 0: not yet applicable; a PMT is one section (0 of 0) + if sec[5] & 1 == 0 || sec[6] != 0 || sec[7] != 0 { + continue; + } + if Some(u16::from_be_bytes([sec[3], sec[4]])) != pmt.program { + continue; + } + if crc32_mpeg(&sec) != 0 { + *crc_errors += 1; + continue; + } + let version = (sec[5] >> 1) & 0x1F; + if pmt.pmt_version == Some(version) { + // a repeat of the PMT already used: no need to check it again + continue; + } + let later = pmt.pmt_version.is_some(); + pmt.pmt_version = Some(version); + pmt.pcr_pid = Some((((sec[8] & 0x1F) as u16) << 8) | sec[9] as u16); + if add_pmt_streams(&sec, packet_size, later, es, order) { + pmt.pmt_changed = true; + } + } +} + +pub(crate) fn scan(src: &S, packet_size: usize, sync_offset: usize) -> Result { + let len = src.len(); + let mut head = vec![0u8; packet_size * 8]; + let n = read_some(src, 0, &mut head)?; + let mut off = first_sync(&head[..n], packet_size, sync_offset).ok_or(Error::NotMpeg)? as u64; + let mut warnings: Vec = Vec::new(); + let mut pat = Psi::default(); + let mut pmt = PmtState::default(); + let mut es: HashMap = HashMap::new(); + let mut order: Vec = Vec::new(); + // one timestamp unwrapper for the program: its streams share one clock, so a stream whose + // first timestamp lies just after the 33-bit wrap stays in step with one just before it + let mut unwrap = Unwrap::default(); + let mut pcr_clock = ProgramClock::default(); + let (mut lost_sync, mut cc_errors, mut crc_errors) = (0u64, 0u64, 0u64); + let (mut tei_dropped, mut scrambled, mut duplicates) = (0u64, 0u64, 0u64); + const BLOCK: usize = 4096; + let mut block = vec![0u8; BLOCK * packet_size]; + let mut bad_adaptation = 0u64; + while off + packet_size as u64 <= len { + let got = read_some(src, off, &mut block)?; + if got < packet_size { + break; + } + let at_end = off + got as u64 >= len; + // `p`: byte index of the next packet in `block`. Packets are parsed in place; a lost + // sync is repaired inside the loaded block, and the block is refilled from the file + // (at `off + p`) only when it is used up, so the bytes read stay close to the file size. + let mut p = 0usize; + while p + packet_size <= got { + let pos = off + p as u64; + let raw = &block[p..p + packet_size]; + let (tei, is_scrambled) = skip_flags(&raw[sync_offset..]); + if tei { + // transport_error_indicator: the payload (and the header) cannot be trusted + tei_dropped += 1; + p += packet_size; + continue; + } + let pk = match packet(&raw[sync_offset..]) { + Ok(pk) => pk, + Err(Bad::Adaptation) => { + // the packet grid is intact: this packet just has no usable payload + bad_adaptation += 1; + p += packet_size; + continue; + } + Err(Bad::Sync) => { + lost_sync += 1; + let (next, exhausted) = resync(&block[..got], p + 1, packet_size, sync_offset, at_end); + p = next; + if exhausted { + break; + } + continue; + } + }; + p += packet_size; + if let Some(pcr) = pk.pcr { + pcr_clock.push(pmt.pcr_pid, pk.pid, pcr); + } + if is_scrambled { + // encrypted payload is noise to the splitter; keep the counter in step + scrambled += 1; + if let Some(e) = es.get_mut(&pk.pid) + && pk.has_payload + { + e.cc = Some(pk.cc); + } + continue; + } + if pk.pid == 0 { + feed_pat(&pk, &mut pat, &mut pmt, &mut crc_errors); + continue; + } + if Some(pk.pid) == pmt.pmt_pid { + let had_pcr_pid = pmt.pcr_pid.is_some(); + feed_pmt(&pk, &mut pmt, packet_size, &mut es, &mut order, &mut crc_errors); + if !had_pcr_pid && let Some(pid) = pmt.pcr_pid { + pcr_clock.named(pid); + } + continue; + } + let Some(e) = es.get_mut(&pk.pid) else { continue }; + if e.dup.is_dup(&pk) { + duplicates += 1; + continue; + } + if pk.has_payload { + if let Some(prev) = e.cc + && !pk.discontinuity + && pk.cc != (prev + 1) & 15 + && pk.cc != prev + { + cc_errors += 1; + } + e.cc = Some(pk.cc); + } + let (hdr, bytes) = e.asm.packet(pk.pusi, pk.payload); + if let Some(h) = hdr { + e.stream.pes_packets += 1; + let pts = h.pts.map(|t| unwrap.unwrap(t)); + let dts = h.dts.map(|t| unwrap.unwrap(t)); + e.split.pes_start(pts, dts); + } + e.split.feed(pos, bytes); + } + // `p >= 1` here (the loop ran at least once or `resync` moved past the failed packet) + off += p.max(1) as u64; + } + if lost_sync > 0 { + warnings.push(format!("lost packet sync {lost_sync} time(s)")); + } + if bad_adaptation > 0 { + warnings.push(format!("{bad_adaptation} packet(s) with an invalid adaptation field")); + } + if cc_errors > 0 { + warnings.push(format!("{cc_errors} continuity counter error(s)")); + } + if tei_dropped > 0 { + warnings.push(format!("{tei_dropped} packet(s) with the transport error indicator dropped")); + } + if scrambled > 0 { + warnings.push(format!("{scrambled} scrambled packet(s) skipped")); + } + if duplicates > 0 { + warnings.push(format!("{duplicates} duplicate packet(s) dropped")); + } + if pmt.pmt_changed { + warnings.push("program map table changed mid-stream; new streams were added, changes to or removal of known ones ignored".into()); + } + if crc_errors > 0 { + warnings.push(format!("{crc_errors} PSI section(s) with bad CRC")); + } + if pmt.pmt_pid.is_none() { + warnings.push("no program association table".into()); + } + let mut streams = Vec::new(); + for pid in order { + let Some(mut e) = es.remove(&pid) else { continue }; + e.split.finish(); + e.stream.units = std::mem::take(&mut e.split.units); + e.stream.skipped_bytes = e.split.skipped; + if e.split.truncated { + warnings.push(format!("PID {pid}: more than {} access units, the rest are not indexed", super::es::MAX_UNITS)); + } + streams.push(e.stream); + } + let pcr_range = pcr_clock.range(pmt.pcr_pid); + Ok(File { format: Format::Ts { packet_size, sync_offset }, streams, program: pmt.program, pcr_range, warnings }) +} + +/// Collect unit `u` of stream `st`: from the packet at `u.pos`, the PID's elementary-stream bytes. +pub(crate) fn read(src: &S, packet_size: usize, sync_offset: usize, st: &Stream, u: &Unit, out: &mut Vec) -> Result<()> { + let StreamId::Pid(pid) = st.id else { return Err(Error::Invalid("not a TS stream".into())) }; + let need = u.size as usize; + let mut skip = u.offset as usize; + let mut off = u.pos; + let mut asm = PesAsm::default(); + let mut dup = DupGuard::default(); + let mut first = true; + let mut block = vec![0u8; 512 * packet_size]; + while out.len() < need { + let got = read_some(src, off, &mut block)?; + let whole = got / packet_size; + if whole == 0 { + break; + } + for k in 0..whole { + let raw = &block[k * packet_size..(k + 1) * packet_size]; + if skip_flags(&raw[sync_offset..]).0 { + continue; + } + let pk = match packet(&raw[sync_offset..]) { + Ok(pk) => pk, + Err(Bad::Sync) => return Ok(()), + Err(Bad::Adaptation) => continue, + }; + if pk.pid != pid || skip_flags(&raw[sync_offset..]).1 || dup.is_dup(&pk) { + continue; + } + // a unit starting in a PES packet's first packet: the header is skipped + let (_, bytes) = if first && !pk.pusi { (None, pk.payload) } else { asm.packet(pk.pusi, pk.payload) }; + first = false; + let bytes = if skip > 0 { + let s = skip.min(bytes.len()); + skip -= s; + &bytes[s..] + } else { + bytes + }; + let take = bytes.len().min(need - out.len()); + out.extend_from_slice(&bytes[..take]); + if out.len() >= need { + return Ok(()); + } + } + off += (whole * packet_size) as u64; + } + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + + /// A unit start that never completes a PES header (MPEG-1 syntax, stuffing without end) is + /// given up after 1024 bytes: the bytes are not kept, and the next unit start is read again. + #[test] + fn a_pes_header_that_never_ends_is_not_buffered_past_the_limit() { + let mut asm = PesAsm::default(); + let mut first = vec![0, 0, 1, 0xC0, 0, 0]; + first.resize(184, 0xFF); + assert_eq!(asm.packet(true, &first), (None, &[][..])); + let stuffing = [0xFFu8; 184]; + for k in 0..200 { + assert_eq!(asm.packet(false, &stuffing), (None, &[][..]), "packet {k}"); + assert!(asm.hdr.len() <= 1024 + 184, "{} header bytes buffered", asm.hdr.len()); + } + assert!(asm.dropping && asm.hdr.is_empty()); + let (h, es) = asm.packet(true, &[0, 0, 1, 0xC0, 0, 0, 0x80, 0, 0, 0xAA, 0xBB]); + assert_eq!((h.map(|h| h.header_len), es), (Some(9), &[0xAA, 0xBB][..])); + } +} + +#[cfg(test)] +mod dup_tests { + use super::*; + + #[test] + fn a_discontinuity_packet_is_never_a_duplicate() { + let payload = [7u8; 20]; + let pk = |discontinuity| Packet { pusi: true, pid: 0x100, cc: 3, has_payload: true, discontinuity, pcr: None, payload: &payload }; + let mut g = DupGuard::default(); + assert!(!g.is_dup(&pk(false))); + assert!(!g.is_dup(&pk(true)), "same counter and payload, but the stream restarts here"); + assert!(g.is_dup(&pk(false)), "the discontinuity packet is the new reference"); + } + + #[test] + fn an_adaptation_only_discontinuity_resets_the_duplicate_history() { + let payload = [7u8; 20]; + let pk = |has_payload, discontinuity| Packet { + pusi: true, + pid: 0x100, + cc: 3, + has_payload, + discontinuity, + pcr: None, + payload: if has_payload { &payload } else { &[] }, + }; + let mut g = DupGuard::default(); + assert!(!g.is_dup(&pk(true, false))); + assert!(!g.is_dup(&pk(false, true)), "adaptation-only packets are never dropped"); + assert!(!g.is_dup(&pk(true, false)), "payload A with CC=3 after the restart is new"); + assert!(g.is_dup(&pk(true, false)), "a real repeat is still dropped"); + } +} diff --git a/crates/media/src/mpegts/work_tests.rs b/crates/media/src/mpegts/work_tests.rs new file mode 100644 index 000000000..d92aca42a --- /dev/null +++ b/crates/media/src/mpegts/work_tests.rs @@ -0,0 +1,115 @@ +//! Equality and counting tests for the redundant-work removals: the old implementation is kept +//! here as the reference, the new one must give the same results. + +use super::*; + +/// The bitwise CRC-32 that `ts::crc32_mpeg` replaced. +fn crc32_bitwise(data: &[u8]) -> u32 { + let mut crc = 0xFFFF_FFFFu32; + for &b in data { + crc ^= (b as u32) << 24; + for _ in 0..8 { + crc = if crc & 0x8000_0000 != 0 { (crc << 1) ^ 0x04C1_1DB7 } else { crc << 1 }; + } + } + crc +} + +/// Deterministic xorshift bytes. +fn noise(seed: u32, n: usize) -> Vec { + let mut x = seed | 1; + (0..n) + .map(|_| { + x ^= x << 13; + x ^= x >> 17; + x ^= x << 5; + (x >> 8) as u8 + }) + .collect() +} + +#[test] +fn table_crc_equals_the_bitwise_crc() { + // the standard check value of CRC-32/MPEG-2 + assert_eq!(ts::crc32_mpeg(b"123456789"), 0x0376_E6E7); + assert_eq!(ts::crc32_mpeg(&[]), 0xFFFF_FFFF); + for b in 0..=255u8 { + assert_eq!(ts::crc32_mpeg(&[b]), crc32_bitwise(&[b])); + } + for n in [0usize, 1, 2, 3, 4, 5, 15, 16, 17, 183, 184, 1023, 1024, 4096] { + for seed in 1..6u32 { + let d = noise(seed * 7919 + n as u32, n); + assert_eq!(ts::crc32_mpeg(&d), crc32_bitwise(&d), "len {n} seed {seed}"); + } + } + // a section followed by its own CRC checks to zero + let mut sec = noise(5, 40); + let crc = ts::crc32_mpeg(&sec); + sec.extend(crc.to_be_bytes()); + assert_eq!(ts::crc32_mpeg(&sec), 0); +} + +/// MPEG-1 layer II frame, 48 kHz 192 kb/s (576 bytes), distinct per `k` and `salt`. +fn mp2_frame(k: usize, salt: u8) -> Vec { + let mut v = vec![0xFF, 0xFD, 0xA4, 0x00]; + v.extend((0..572).map(|i| (i as u8) ^ (k as u8) ^ salt)); + v +} + +fn pes_packet(stream_id: u8, payload: &[u8]) -> Vec { + let len = 3 + payload.len(); + let mut v = vec![0, 0, 1, stream_id, (len >> 8) as u8, len as u8, 0x80, 0, 0]; + v.extend_from_slice(payload); + v +} + +/// Two audio streams interleaved in maximal PES packets over more than three window refills, +/// with a pack header per PES packet; MPEG-2 or MPEG-1 pack headers. +pub(super) fn big_program_stream(mpeg1: bool, frames: usize) -> (Vec, Vec>, Vec>) { + let a: Vec> = (0..frames).map(|k| mp2_frame(k, 0)).collect(); + let b: Vec> = (0..frames).map(|k| mp2_frame(k, 0x55)).collect(); + let (ea, eb) = (a.concat(), b.concat()); + let mut out = Vec::new(); + for (ca, cb) in ea.chunks(60_000).zip(eb.chunks(60_000)) { + for (id, chunk) in [(0xC0, ca), (0xC1, cb)] { + if mpeg1 { + out.extend([0, 0, 1, 0xBA, 0x21, 0, 1, 0, 1, 0x80, 0, 1]); + } else { + out.extend([0, 0, 1, 0xBA, 0x44, 0, 4, 0, 4, 1, 1, 0x89, 0xC3, 0xF8]); + } + out.extend(pes_packet(id, chunk)); + } + } + out.extend([0, 0, 1, 0xB9]); + (out, a, b) +} + +#[test] +fn program_stream_with_large_pes_packets_gives_back_every_frame() { + for mpeg1 in [false, true] { + let (data, a, b) = big_program_stream(mpeg1, 2000); // about 1.2 MB per stream + assert!(data.len() > 2 << 20, "more than the 1 MiB window twice"); + let f = open(&data).unwrap(); + assert_eq!(f.format, Format::Ps { mpeg1 }); + assert_eq!(f.streams.len(), 2); + for (s, frames) in f.streams.iter().zip([&a, &b]) { + assert_eq!(s.units.len(), frames.len()); + // a read refills a 1 MiB window: every seventh unit and the last ones keep a debug build quick + for (i, fr) in frames.iter().enumerate().filter(|(i, _)| i % 7 == 0 || i + 4 > frames.len()) { + assert_eq!(&f.read_unit(&data, f.streams.iter().position(|x| std::ptr::eq(x, s)).unwrap(), i).unwrap(), fr, "mpeg1 {mpeg1} unit {i}"); + } + } + // cut inside the last packets: never panics, and the units before the cut are intact + for cut in [data.len() - 1, data.len() - 4, data.len() - 30_000, data.len() - 61_000, 100_000, 1 << 20] { + let d = &data[..cut]; + let Ok(f) = open(d) else { continue }; + for (si, frames) in [&a, &b].into_iter().enumerate() { + let Some(s) = f.streams.get(si) else { continue }; + let n = s.units.len().saturating_sub(1); + for (i, frame) in frames.iter().enumerate().take(n).filter(|(i, _)| i % 61 == 0 || i + 8 > n) { + assert_eq!(&f.read_unit(d, si, i).unwrap(), frame, "cut {cut} stream {si} unit {i}"); + } + } + } + } +} diff --git a/crates/media/src/mxf/essence.rs b/crates/media/src/mxf/essence.rs new file mode 100644 index 000000000..27f893dc5 --- /dev/null +++ b/crates/media/src/mxf/essence.rs @@ -0,0 +1,450 @@ +//! Essence identification and PCM sound decoding. +//! +//! Picture codecs are identified from the descriptor's picture essence coding label, then the +//! essence container label (ST 379-2 mapping numbers), then the first bytes of the essence. + +use crate::mxf::klv::Ul; +use crate::mxf::{Rational, Result}; + +/// The essence codec of a track. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Codec { + /// H.264 / AVC byte stream (ST 381-3). `intra`: AVC-Intra / an intra-only profile. + Avc { + intra: bool, + }, + /// SMPTE VC-3 (DNxHD / DNxHR, ST 2019-4). + Vc3, + /// Apple ProRes (RDD 44). `profile`: byte 14 of the coding label (1 Proxy … 6 4444 XQ). + ProRes { + profile: Option, + }, + /// MPEG-2 video (ST 381-1, or D-10 / IMX). + Mpeg2, + /// MPEG-4 part 2 visual. + Mpeg4Visual, + Jpeg2000, + Dv, + /// Uncompressed pictures (ST 384). + Uncompressed, + /// Linear PCM, little-endian (Broadcast Wave and AES3 descriptors, ST 382). + Pcm, + /// 8-channel AES3 element data (ST 331, D-10 sound). + Aes3Element, + Unknown, +} + +impl Codec { + pub fn name(&self) -> &'static str { + match self { + Codec::Avc { intra: true } => "AVC-Intra", + Codec::Avc { intra: false } => "H.264", + Codec::Vc3 => "VC-3", + Codec::ProRes { .. } => "Apple ProRes", + Codec::Mpeg2 => "MPEG-2 Video", + Codec::Mpeg4Visual => "MPEG-4 Visual", + Codec::Jpeg2000 => "JPEG 2000", + Codec::Dv => "DV", + Codec::Uncompressed => "Uncompressed", + Codec::Pcm => "PCM", + Codec::Aes3Element => "AES3 PCM", + Codec::Unknown => "unknown", + } + } + /// The crate-wide identifier: VC-3 is [`CodecId::Dnxhd`], PCM and AES3 element data are + /// [`CodecId::Pcm`]; JPEG 2000, DV and uncompressed pictures have no identifier. + /// + /// [`CodecId::Dnxhd`]: crate::CodecId::Dnxhd + /// [`CodecId::Pcm`]: crate::CodecId::Pcm + pub fn codec_id(&self) -> crate::CodecId { + use crate::CodecId as Id; + match self { + Codec::Avc { .. } => Id::H264, + Codec::Vc3 => Id::Dnxhd, + Codec::ProRes { .. } => Id::ProRes, + Codec::Mpeg2 => Id::Mpeg2Video, + Codec::Mpeg4Visual => Id::Mpeg4Video, + Codec::Pcm | Codec::Aes3Element => Id::Pcm, + Codec::Jpeg2000 | Codec::Dv | Codec::Uncompressed | Codec::Unknown => Id::Unknown, + } + } + /// Every picture is coded independently. + pub fn intra_only(&self) -> bool { + matches!(self, Codec::Avc { intra: true } | Codec::Vc3 | Codec::ProRes { .. } | Codec::Jpeg2000 | Codec::Dv | Codec::Uncompressed) + } +} + +/// Identify a picture codec from the picture essence coding label and the essence container label. +pub fn identify_picture(coding: Option