Add model repository contents

.gitattributes

@@ -0,0 +1,3 @@
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+golden/*.npy filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,2 @@
+.repro/
+.venv/

LICENSE.md

@@ -0,0 +1,159 @@
+# Creative Commons Attribution-NonCommercial 4.0 International
+
+Creative Commons Corporation (“Creative Commons”) is not a law firm and does not provide legal services or legal advice. Distribution of Creative Commons public licenses does not create a lawyer-client or other relationship. Creative Commons makes its licenses and related information available on an “as-is” basis. Creative Commons gives no warranties regarding its licenses, any material licensed under their terms and conditions, or any related information. Creative Commons disclaims all liability for damages resulting from their use to the fullest extent possible.
+
+**Using Creative Commons Public Licenses**
+
+Creative Commons public licenses provide a standard set of terms and conditions that creators and other rights holders may use to share original works of authorship and other material subject to copyright and certain other rights specified in the public license below. The following considerations are for informational purposes only, are not exhaustive, and do not form part of our licenses.
+
+* __Considerations for licensors:__ Our public licenses are intended for use by those authorized to give the public permission to use material in ways otherwise restricted by copyright and certain other rights. Our licenses are irrevocable. Licensors should read and understand the terms and conditions of the license they choose before applying it. Licensors should also secure all rights necessary before applying our licenses so that the public can reuse the material as expected. Licensors should clearly mark any material not subject to the license. This includes other CC-licensed material, or material used under an exception or limitation to copyright. [More considerations for licensors](http://wiki.creativecommons.org/Considerations_for_licensors_and_licensees#Considerations_for_licensors).
+
+* __Considerations for the public:__ By using one of our public licenses, a licensor grants the public permission to use the licensed material under specified terms and conditions. If the licensor’s permission is not necessary for any reason–for example, because of any applicable exception or limitation to copyright–then that use is not regulated by the license. Our licenses grant only permissions under copyright and certain other rights that a licensor has authority to grant. Use of the licensed material may still be restricted for other reasons, including because others have copyright or other rights in the material. A licensor may make special requests, such as asking that all changes be marked or described. Although not required by our licenses, you are encouraged to respect those requests where reasonable. [More considerations for the public](http://wiki.creativecommons.org/Considerations_for_licensors_and_licensees#Considerations_for_licensees).
+
+## Creative Commons Attribution-NonCommercial 4.0 International Public License
+
+By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution-NonCommercial 4.0 International Public License ("Public License"). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions.
+
+### Section 1 – Definitions.
+
+a. __Adapted Material__ means material subject to Copyright and Similar Rights that is derived from or based upon the Licensed Material and in which the Licensed Material is translated, altered, arranged, transformed, or otherwise modified in a manner requiring permission under the Copyright and Similar Rights held by the Licensor. For purposes of this Public License, where the Licensed Material is a musical work, performance, or sound recording, Adapted Material is always produced where the Licensed Material is synched in timed relation with a moving image.
+
+b. __Adapter's License__ means the license You apply to Your Copyright and Similar Rights in Your contributions to Adapted Material in accordance with the terms and conditions of this Public License.
+
+c. __Copyright and Similar Rights__ means copyright and/or similar rights closely related to copyright including, without limitation, performance, broadcast, sound recording, and Sui Generis Database Rights, without regard to how the rights are labeled or categorized. For purposes of this Public License, the rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights.
+
+d. __Effective Technological Measures__ means those measures that, in the absence of proper authority, may not be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, and/or similar international agreements.
+
+e. __Exceptions and Limitations__ means fair use, fair dealing, and/or any other exception or limitation to Copyright and Similar Rights that applies to Your use of the Licensed Material.
+
+f. __Licensed Material__ means the artistic or literary work, database, or other material to which the Licensor applied this Public License.
+
+g. __Licensed Rights__ means the rights granted to You subject to the terms and conditions of this Public License, which are limited to all Copyright and Similar Rights that apply to Your use of the Licensed Material and that the Licensor has authority to license.
+
+h. __Licensor__ means the individual(s) or entity(ies) granting rights under this Public License.
+
+i. __NonCommercial__ means not primarily intended for or directed towards commercial advantage or monetary compensation. For purposes of this Public License, the exchange of the Licensed Material for other material subject to Copyright and Similar Rights by digital file-sharing or similar means is NonCommercial provided there is no payment of monetary compensation in connection with the exchange.
+
+j. __Share__ means to provide material to the public by any means or process that requires permission under the Licensed Rights, such as reproduction, public display, public performance, distribution, dissemination, communication, or importation, and to make material available to the public including in ways that members of the public may access the material from a place and at a time individually chosen by them.
+
+k. __Sui Generis Database Rights__ means rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world.
+
+l. __You__ means the individual or entity exercising the Licensed Rights under this Public License. __Your__ has a corresponding meaning.
+
+### Section 2 – Scope.
+
+a. ___License grant.___
+
+   1. Subject to the terms and conditions of this Public License, the Licensor hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Licensed Material to:
+
+       A. reproduce and Share the Licensed Material, in whole or in part, for NonCommercial purposes only; and
+
+       B. produce, reproduce, and Share Adapted Material for NonCommercial purposes only.
+
+   2. __Exceptions and Limitations.__ For the avoidance of doubt, where Exceptions and Limitations apply to Your use, this Public License does not apply, and You do not need to comply with its terms and conditions.
+
+   3. __Term.__ The term of this Public License is specified in Section 6(a).
+
+   4. __Media and formats; technical modifications allowed.__ The Licensor authorizes You to exercise the Licensed Rights in all media and formats whether now known or hereafter created, and to make technical modifications necessary to do so. The Licensor waives and/or agrees not to assert any right or authority to forbid You from making technical modifications necessary to exercise the Licensed Rights, including technical modifications necessary to circumvent Effective Technological Measures. For purposes of this Public License, simply making modifications authorized by this Section 2(a)(4) never produces Adapted Material.
+
+   5. __Downstream recipients.__
+
+        A. __Offer from the Licensor – Licensed Material.__ Every recipient of the Licensed Material automatically receives an offer from the Licensor to exercise the Licensed Rights under the terms and conditions of this Public License.
+
+        B. __No downstream restrictions.__ You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, the Licensed Material if doing so restricts exercise of the Licensed Rights by any recipient of the Licensed Material.
+
+   6. __No endorsement.__ Nothing in this Public License constitutes or may be construed as permission to assert or imply that You are, or that Your use of the Licensed Material is, connected with, or sponsored, endorsed, or granted official status by, the Licensor or others designated to receive attribution as provided in Section 3(a)(1)(A)(i).
+
+b. ___Other rights.___
+
+   1. Moral rights, such as the right of integrity, are not licensed under this Public License, nor are publicity, privacy, and/or other similar personality rights; however, to the extent possible, the Licensor waives and/or agrees not to assert any such rights held by the Licensor to the limited extent necessary to allow You to exercise the Licensed Rights, but not otherwise.
+
+   2. Patent and trademark rights are not licensed under this Public License.
+
+   3. To the extent possible, the Licensor waives any right to collect royalties from You for the exercise of the Licensed Rights, whether directly or through a collecting society under any voluntary or waivable statutory or compulsory licensing scheme. In all other cases the Licensor expressly reserves any right to collect such royalties, including when the Licensed Material is used other than for NonCommercial purposes.
+
+### Section 3 – License Conditions.
+
+Your exercise of the Licensed Rights is expressly made subject to the following conditions.
+
+a. ___Attribution.___
+
+   1. If You Share the Licensed Material (including in modified form), You must:
+
+       A. retain the following if it is supplied by the Licensor with the Licensed Material:
+
+         i. identification of the creator(s) of the Licensed Material and any others designated to receive attribution, in any reasonable manner requested by the Licensor (including by pseudonym if designated);
+
+         ii. a copyright notice;
+
+         iii. a notice that refers to this Public License;
+
+         iv. a notice that refers to the disclaimer of warranties;
+
+         v. a URI or hyperlink to the Licensed Material to the extent reasonably practicable;
+
+       B. indicate if You modified the Licensed Material and retain an indication of any previous modifications; and
+
+       C. indicate the Licensed Material is licensed under this Public License, and include the text of, or the URI or hyperlink to, this Public License.
+
+   2. You may satisfy the conditions in Section 3(a)(1) in any reasonable manner based on the medium, means, and context in which You Share the Licensed Material. For example, it may be reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that includes the required information.
+
+   3. If requested by the Licensor, You must remove any of the information required by Section 3(a)(1)(A) to the extent reasonably practicable.
+
+   4. If You Share Adapted Material You produce, the Adapter's License You apply must not prevent recipients of the Adapted Material from complying with this Public License.
+
+### Section 4 – Sui Generis Database Rights.
+
+Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material:
+
+a. for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, reuse, reproduce, and Share all or a substantial portion of the contents of the database for NonCommercial purposes only;
+
+b. if You include all or a substantial portion of the database contents in a database in which You have Sui Generis Database Rights, then the database in which You have Sui Generis Database Rights (but not its individual contents) is Adapted Material; and
+
+c. You must comply with the conditions in Section 3(a) if You Share all or a substantial portion of the contents of the database.
+
+For the avoidance of doubt, this Section 4 supplements and does not replace Your obligations under this Public License where the Licensed Rights include other Copyright and Similar Rights.
+
+### Section 5 – Disclaimer of Warranties and Limitation of Liability.
+
+a. __Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Licensed Material as-is and as-available, and makes no representations or warranties of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not allowed in full or in part, this disclaimer may not apply to You.__
+
+b. __To the extent possible, in no event will the Licensor be liable to You on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this Public License or use of the Licensed Material, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply to You.__
+
+c. The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability.
+
+### Section 6 – Term and Termination.
+
+a. This Public License applies for the term of the Copyright and Similar Rights licensed here. However, if You fail to comply with this Public License, then Your rights under this Public License terminate automatically.
+
+b. Where Your right to use the Licensed Material has terminated under Section 6(a), it reinstates:
+
+   1. automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or
+
+   2. upon express reinstatement by the Licensor.
+
+   For the avoidance of doubt, this Section 6(b) does not affect any right the Licensor may have to seek remedies for Your violations of this Public License.
+
+c. For the avoidance of doubt, the Licensor may also offer the Licensed Material under separate terms or conditions or stop distributing the Licensed Material at any time; however, doing so will not terminate this Public License.
+
+d. Sections 1, 5, 6, 7, and 8 survive termination of this Public License.
+
+### Section 7 – Other Terms and Conditions.
+
+a. The Licensor shall not be bound by any additional or different terms or conditions communicated by You unless expressly agreed.
+
+b. Any arrangements, understandings, or agreements regarding the Licensed Material not stated herein are separate from and independent of the terms and conditions of this Public License.
+
+### Section 8 – Interpretation.
+
+a. For the avoidance of doubt, this Public License does not, and shall not be interpreted to, reduce, limit, restrict, or impose conditions on any use of the Licensed Material that could lawfully be made without permission under this Public License.
+
+b. To the extent possible, if any provision of this Public License is deemed unenforceable, it shall be automatically reformed to the minimum extent necessary to make it enforceable. If the provision cannot be reformed, it shall be severed from this Public License without affecting the enforceability of the remaining terms and conditions.
+
+c. No term or condition of this Public License will be waived and no failure to comply consented to unless expressly agreed to by the Licensor.
+
+d. Nothing in this Public License constitutes or may be interpreted as a limitation upon, or waiver of, any privileges and immunities that apply to the Licensor or You, including from the legal processes of any jurisdiction or authority.
+
+> Creative Commons is not a party to its public licenses. Notwithstanding, Creative Commons may elect to apply one of its public licenses to material it publishes and in those instances will be considered the “Licensor.” Except for the limited purpose of indicating that material is shared under a Creative Commons public license or as otherwise permitted by the Creative Commons policies published at [creativecommons.org/policies](http://creativecommons.org/policies), Creative Commons does not authorize the use of the trademark “Creative Commons” or any other trademark or logo of Creative Commons without its prior written consent including, without limitation, in connection with any unauthorized modifications to any of its public licenses or any other arrangements, understandings, or agreements concerning use of licensed material. For the avoidance of doubt, this paragraph does not form part of the public licenses.
+>
+> Creative Commons may be contacted at creativecommons.org

PROVENANCE.json

@@ -0,0 +1,60 @@
+{
+  "schema_version": 1,
+  "publication_status": "ready-to-publish-noncommercial-only",
+  "artifact": {
+    "path": "batdetect2-uk-same.onnx",
+    "bytes": 7603041,
+    "sha256": "9eddc08f1a22695ffdb1cdb52d947752d83777cd8596554f108bcf701481d340",
+    "opset": 17,
+    "modifications": "Converted from the pinned PyTorch checkpoint to ONNX."
+  },
+  "source": {
+    "repository": "https://github.com/macaodha/batdetect2",
+    "revision": "9e2697458d3b3b03c30ccd7e49ed5409c8ac330d",
+    "path": "src/batdetect2/models/checkpoints/batdetect2_uk_same.ckpt",
+    "archived_path": "upstream/batdetect2_uk_same.ckpt",
+    "bytes": 7610085,
+    "sha256": "52e3f329a046e434d16751005b252b4fd1b142b8b63a4edc2740aeb81f48adcf"
+  },
+  "exporter": {
+    "path": "scripts/export_batdetect2_onnx.py",
+    "sha256": "654aefbf39ebfb0815ecb85dff34382ea9a9dd32f28690474f44774514ece66f",
+    "project": "environment/pyproject.toml",
+    "project_sha256": "1dae942acf443726fc72cec3398e308c7c1c57eef36814b720c1fe30bacd8383",
+    "lock": "environment/uv.lock",
+    "lock_sha256": "6a18952a219703f0f03e6f091ed898f7b23bc886e6bdd96dd933d5b94dc57e92"
+  },
+  "export_environment": {
+    "python": "3.11.15",
+    "batdetect2": "2.0.0b3",
+    "torch": "2.13.0",
+    "onnx": "1.22.0",
+    "onnxruntime": "1.28.0"
+  },
+  "source_runtime_parity": {
+    "fixture": "seeded random float32 tensor (seed 20260818)",
+    "detection_maximum_absolute_error": 1.0579824447631836e-06,
+    "class_maximum_absolute_error": 5.364418029785156e-07,
+    "tolerance": 0.0001
+  },
+  "contract": {
+    "input": "float32 NCHW [1,1,128,256] named input",
+    "outputs": {
+      "detection_probs": [1, 1, 128, 256],
+      "class_probs": [1, 17, 128, 256]
+    },
+    "labels": "labels.json",
+    "region": "United Kingdom"
+  },
+  "preprocessing": {
+    "repository_revision": "9e2697458d3b3b03c30ccd7e49ed5409c8ac330d",
+    "path": "preprocessing/upstream"
+  },
+  "golden_fixture": "golden/manifest.json",
+  "rights": {
+    "license": "CC-BY-NC-4.0",
+    "attribution": "BatDetect2 contributors",
+    "commercial_use": false,
+    "redistribution": "noncommercial only, with attribution, licence link, and change notice"
+  }
+}

PUBLISHING.md

@@ -0,0 +1,19 @@
+# Publishing checklist
+
+Status: **READY TO PUBLISH — NONCOMMERCIAL ONLY**
+
+- [x] The upstream CC BY-NC 4.0 licence is preserved unchanged.
+- [x] The model card attributes the original authors and cites the upstream work.
+- [x] The model card identifies the ONNX file as an unofficial conversion.
+- [x] Source revision, environment, parity result, file sizes, and hashes are pinned.
+- [x] The byte-identical original PyTorch checkpoint is archived with a safety warning.
+- [x] The exporter, locked environment, source verifier, and rebuild verifier are included.
+- [x] Exact label order, pinned preprocessing, and a deterministic golden fixture are included.
+- [x] The private staging repository is `legojoey17/batdetect2-uk-same-onnx`.
+- [x] The remote ONNX, checkpoint, and golden-fixture SHA-256 values match the local manifest.
+- [x] The rendered private repository has been reviewed.
+- [x] The intended public distribution has been confirmed as noncommercial under CC BY-NC 4.0.
+- [ ] Obtain separate rights before using this repository to support commercial distribution.
+
+Publishing from another namespace makes that account the uploader. It does not make the
+conversion official or imply endorsement by BatDetect2 or its authors.

README.md

@@ -0,0 +1,113 @@
+---
+license: cc-by-nc-4.0
+library_name: onnxruntime
+tags:
+  - onnx
+  - onnxruntime
+  - bioacoustics
+  - bats
+  - audio-classification
+  - object-detection
+  - united-kingdom
+  - non-commercial
+---
+
+# BatDetect2 UK `same` ONNX
+
+> **Noncommercial only.** The source checkpoint is CC BY-NC 4.0. Commercial use or distribution
+> requires separate permission from the rights holder.
+
+This repository contains the original BatDetect2 UK `same` checkpoint and the reproducible ONNX
+export used by OpenBat. It is an unofficial conversion, not a BatDetect2 release.
+
+`UK same` is the paper's evaluation split where test files come from the same UK recording data
+sources represented in training. It contrasts with `UK different`, which holds out a complete
+recording source to measure transfer to unseen conditions. See the
+[BatDetect2 paper](https://www.biorxiv.org/content/10.1101/2022.12.14.520490v2.full).
+
+## Artifact
+
+| File | Size | SHA-256 |
+|---|---:|---|
+| `batdetect2-uk-same.onnx` | 7,603,041 bytes | `9eddc08f1a22695ffdb1cdb52d947752d83777cd8596554f108bcf701481d340` |
+| `upstream/batdetect2_uk_same.ckpt` | 7,610,085 bytes | `52e3f329a046e434d16751005b252b4fd1b142b8b63a4edc2740aeb81f48adcf` |
+
+## Source and conversion
+
+- Source repository: [`macaodha/batdetect2`](https://github.com/macaodha/batdetect2).
+- Source revision: `9e2697458d3b3b03c30ccd7e49ed5409c8ac330d`.
+- Source checkpoint: `src/batdetect2/models/checkpoints/batdetect2_uk_same.ckpt`.
+- Conversion: PyTorch checkpoint to ONNX opset 17.
+- Export environment: CPython 3.11.15, BatDetect2 2.0.0b3, PyTorch 2.13.0,
+  ONNX 1.22.0, and ONNX Runtime 1.28.0.
+- Seeded source-runtime parity: detection maximum absolute error `1.0579824447631836e-06`;
+  class maximum absolute error `5.364418029785156e-07`; tolerance `0.0001`.
+
+The original checkpoint is archived byte-identically under `upstream/`. The exact exporter is in
+`scripts/`, the complete `uv` lock is in `environment/`, and `PROVENANCE.json` records the source
+and output contract.
+
+## Reproduce the conversion
+
+The rebuild requires Git, `uv`, and CPython 3.11.15. Fetch the pinned BatDetect2 revision, compare
+its checkpoint with the archived copy, then run the locked exporter and parity check:
+
+```sh
+./scripts/fetch-upstream.sh
+./scripts/rebuild-and-verify.sh --accept-noncommercial-license
+```
+
+The explicit flag acknowledges that the checkpoint and conversion remain subject to CC BY-NC
+4.0. The first run downloads the checksum-locked Python environment. Output goes to the ignored
+`.repro/output/` directory. A passing rebuild establishes byte identity and seeded runtime
+agreement; it does not validate classification accuracy.
+
+The `.ckpt` file is a Python/PyTorch checkpoint. Treat it as trusted upstream archival input and
+do not load checkpoints from untrusted sources. Use the ONNX file for ordinary inference.
+
+## Model contract
+
+- Input: `input`, `float32`, NCHW `[1, 1, 128, 256]`, mono spectrogram.
+- Outputs: `detection_probs` `[1, 1, 128, 256]` and `class_probs`
+  `[1, 17, 128, 256]`.
+- Exact class order: [`labels.json`](labels.json).
+- Region: United Kingdom.
+
+The model does not accept raw audio. Callers must reproduce the BatDetect2 spectrogram and
+normalization contract.
+
+## Preprocessing
+
+[`preprocessing/README.md`](preprocessing/README.md) links directly to the pinned BatDetect2
+implementation and includes an unchanged copy of its complete `preprocess` package.
+
+## Golden fixture
+
+`golden/` contains a deterministic model-ready spectrogram tensor and expected detection and class
+outputs. It checks the published model contract separately from raw-audio preprocessing.
+
+```sh
+uv run --project golden --frozen --python 3.11.15 python scripts/verify_golden.py
+```
+
+The generation seed, runtime versions, hashes, and tolerances are recorded in
+`golden/manifest.json`.
+
+## Licence and attribution
+
+The upstream project and checkpoint are licensed under Creative Commons
+Attribution-NonCommercial 4.0 International. The upstream licence is included unchanged as
+`LICENSE.md`, and the ONNX file is identified as a conversion.
+
+Upstream reference:
+
+> Mac Aodha, O. et al. (2023), “Towards a General Approach for Bat Echolocation Detection and
+> Classification,” bioRxiv, https://www.biorxiv.org/content/10.1101/2022.12.14.520490v2.
+
+## Limitations
+
+- The original authors have not authorized or endorsed this conversion.
+- It is noncommercial-only unless separate rights are obtained.
+- Exact preprocessing is part of the model contract.
+- Source-runtime parity measures conversion fidelity, not biological accuracy.
+- The model is geographically scoped and should not be treated as a global classifier.

SHA256SUMS

@@ -0,0 +1,23 @@
+9eddc08f1a22695ffdb1cdb52d947752d83777cd8596554f108bcf701481d340  batdetect2-uk-same.onnx
+52e3f329a046e434d16751005b252b4fd1b142b8b63a4edc2740aeb81f48adcf  upstream/batdetect2_uk_same.ckpt
+654aefbf39ebfb0815ecb85dff34382ea9a9dd32f28690474f44774514ece66f  scripts/export_batdetect2_onnx.py
+82b7d4f46c7a0bfe21be53d5cf0d83f37fe002fd73f28c3f6b28ee803a25d0e6  scripts/fetch-upstream.sh
+833d7472dbea173977481dde86b26d622de10cb8f4d6be392c35bcdaa9e86845  scripts/rebuild-and-verify.sh
+0ea516a80751bbb4a5d048917a5c58fb9068583ec9fce80b8a015c3628ae3e64  scripts/verify_golden.py
+1dae942acf443726fc72cec3398e308c7c1c57eef36814b720c1fe30bacd8383  environment/pyproject.toml
+6a18952a219703f0f03e6f091ed898f7b23bc886e6bdd96dd933d5b94dc57e92  environment/uv.lock
+0a82dcd7a2a5d86a32ca3dcf22b9ced20fdb8c04bd2a78589cfaebd412e32122  labels.json
+28de21910f625e8d14935cb30151660a5139f060bc48197854ec873b7210e2aa  export-metadata.json
+6ef2dc2fd3cd8ad1a201ac07cabfe873f67ff0be40006671a890cbef5521eb43  golden/input.npy
+5440e3d980f0bb594881bbaba0d41b69b267b9d2ba08e50ee5ee485a84f759eb  golden/detection_probs.npy
+fd1d40e8e7399b3310c0679dd948028427dbb336963ada0ab5cba6440e464657  golden/class_probs.npy
+334ff9d8f923c200aa2e1b232277dfb29070d927ede85580711a5a2ce1916650  golden/manifest.json
+38170f35c4b4a7c73360fc2d454fb2c60dcadafea7fb6bf03602f6165ea48c7f  golden/pyproject.toml
+ff27ad09676f47e1f396e636c7379a95b904d8ac8bcada5aa04da8256a4f859a  golden/uv.lock
+db79d1f9935f9d545ea7e25bf38fee12a3b763d1ad26125845e50a767c17a9ee  preprocessing/upstream/__init__.py
+a838a668cc91c421f5774cc0eb0469c9ec9d6017efadf8e4193245842f99367a  preprocessing/upstream/audio.py
+cae8b4f54a1ce21aeb94ee54a288903efb74afd9a1e1563b6f1df5f8ad36fd21  preprocessing/upstream/common.py
+7050a0491b8a798b6954815ee2efd79bb8329ea0e4a069d805aca419f4b1284e  preprocessing/upstream/config.py
+1d97dd8cf84cf53df67727d7445dc70edc9bb257d97b2013b28921678bdc1672  preprocessing/upstream/preprocessor.py
+370bca8e29bec523ea71a958c6d44a80ce33e540653181d9d62c42ea409ce6fe  preprocessing/upstream/spectrogram.py
+cd896d3b98919851aa130c009f57107167fba696cc4a41d75fbeb3d3d59fbec8  preprocessing/upstream/types.py

batdetect2-uk-same.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9eddc08f1a22695ffdb1cdb52d947752d83777cd8596554f108bcf701481d340
+size 7603041

environment/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "bat-ml-batdetect2-exporter"
+version = "0.0.0"
+requires-python = "==3.11.15"
+dependencies = [
+  "batdetect2",
+  "numpy==2.4.6",
+  "onnx==1.22.0",
+  "onnxruntime==1.28.0",
+  "torch==2.13.0",
+  "torchaudio==2.11.0",
+]
+
+[tool.uv]
+package = false
+
+[tool.uv.sources]
+batdetect2 = { git = "https://github.com/macaodha/batdetect2.git", rev = "9e2697458d3b3b03c30ccd7e49ed5409c8ac330d" }

export-metadata.json

@@ -0,0 +1,76 @@
+{
+  "backend": "batdetect2",
+  "source": "https://github.com/macaodha/batdetect2",
+  "source_revision": "9e2697458d3b3b03c30ccd7e49ed5409c8ac330d",
+  "checkpoint": "src/batdetect2/models/checkpoints/batdetect2_uk_same.ckpt",
+  "input_name": "input",
+  "input_shape": [
+    1,
+    1,
+    128,
+    256
+  ],
+  "outputs": {
+    "detection_probs": [
+      1,
+      1,
+      128,
+      256
+    ],
+    "class_probs": [
+      1,
+      17,
+      128,
+      256
+    ]
+  },
+  "labels": [
+    "MYOMYS",
+    "MYOALC",
+    "CNESER",
+    "PIPNAT",
+    "BARBAR",
+    "MYONAT",
+    "MYODAU",
+    "MYOBRA",
+    "PIPPIP",
+    "MYOBEC",
+    "PIPPYG",
+    "RHIHIP",
+    "NYCLEI",
+    "RHIFER",
+    "PLEAUR",
+    "NYCNOC",
+    "PLEAUS"
+  ],
+  "source_labels": [
+    "myomys",
+    "myoalc",
+    "cneser",
+    "pipnat",
+    "barbar",
+    "myonat",
+    "myodau",
+    "myobra",
+    "pippip",
+    "myobec",
+    "pippyg",
+    "rhihip",
+    "nyclei",
+    "rhifer",
+    "pleaur",
+    "nycnoc",
+    "pleaus"
+  ],
+  "opset": 17,
+  "license": "CC BY-NC 4.0",
+  "commercial_use": false,
+  "onnx_bytes": 7603041,
+  "onnx_sha256": "9eddc08f1a22695ffdb1cdb52d947752d83777cd8596554f108bcf701481d340",
+  "source_runtime_parity": {
+    "fixture": "seeded random float32 tensor (seed 20260818)",
+    "detection_maximum_absolute_error": 1.0579824447631836e-06,
+    "class_maximum_absolute_error": 5.364418029785156e-07,
+    "tolerance": 0.0001
+  }
+}

golden/class_probs.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fd1d40e8e7399b3310c0679dd948028427dbb336963ada0ab5cba6440e464657
+size 2228352

golden/detection_probs.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5440e3d980f0bb594881bbaba0d41b69b267b9d2ba08e50ee5ee485a84f759eb
+size 131200

golden/input.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6ef2dc2fd3cd8ad1a201ac07cabfe873f67ff0be40006671a890cbef5521eb43
+size 131200

golden/manifest.json

@@ -0,0 +1,57 @@
+{
+  "schema_version": 1,
+  "purpose": "Deterministic model-ready tensor fixture for the ONNX runtime contract; it does not test raw-audio preprocessing.",
+  "seed": 20260818,
+  "model": {
+    "path": "batdetect2-uk-same.onnx",
+    "sha256": "9eddc08f1a22695ffdb1cdb52d947752d83777cd8596554f108bcf701481d340"
+  },
+  "runtime": {
+    "numpy": "2.4.6",
+    "onnxruntime": "1.28.0",
+    "provider": "CPUExecutionProvider"
+  },
+  "input": {
+    "path": "input.npy",
+    "name": "input",
+    "dtype": "float32",
+    "shape": [
+      1,
+      1,
+      128,
+      256
+    ],
+    "generator": "numpy.default_rng(seed).random(dtype=float32)",
+    "sha256": "6ef2dc2fd3cd8ad1a201ac07cabfe873f67ff0be40006671a890cbef5521eb43"
+  },
+  "outputs": [
+    {
+      "path": "detection_probs.npy",
+      "name": "detection_probs",
+      "dtype": "float32",
+      "shape": [
+        1,
+        1,
+        128,
+        256
+      ],
+      "sha256": "5440e3d980f0bb594881bbaba0d41b69b267b9d2ba08e50ee5ee485a84f759eb"
+    },
+    {
+      "path": "class_probs.npy",
+      "name": "class_probs",
+      "dtype": "float32",
+      "shape": [
+        1,
+        17,
+        128,
+        256
+      ],
+      "sha256": "fd1d40e8e7399b3310c0679dd948028427dbb336963ada0ab5cba6440e464657"
+    }
+  ],
+  "tolerance": {
+    "rtol": 1e-05,
+    "atol": 1e-06
+  }
+}

golden/pyproject.toml

@@ -0,0 +1,11 @@
+[project]
+name = "batdetect2-uk-same-onnx-fixture"
+version = "0.0.0"
+requires-python = "==3.11.15"
+dependencies = [
+  "numpy==2.4.6",
+  "onnxruntime==1.28.0",
+]
+
+[tool.uv]
+package = false

golden/uv.lock

@@ -0,0 +1,94 @@
+version = 1
+revision = 3
+requires-python = "==3.11.15"
+
+[[package]]
+name = "batdetect2-uk-same-onnx-fixture"
+version = "0.0.0"
+source = { virtual = "." }
+dependencies = [
+    { name = "numpy" },
+    { name = "onnxruntime" },
+]
+
+[package.metadata]
+requires-dist = [
+    { name = "numpy", specifier = "==2.4.6" },
+    { name = "onnxruntime", specifier = "==1.28.0" },
+]
+
+[[package]]
+name = "flatbuffers"
+version = "25.12.19"
+source = { registry = "https://pypi.org/simple" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e8/2d/d2a548598be01649e2d46231d151a6c56d10b964d94043a335ae56ea2d92/flatbuffers-25.12.19-py2.py3-none-any.whl", hash = "sha256:7634f50c427838bb021c2d66a3d1168e9d199b0607e6329399f04846d42e20b4", size = 26661, upload-time = "2025-12-19T23:16:13.622Z" },
+]
+
+[[package]]
+name = "numpy"
+version = "2.4.6"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d0/ad/fed0499ce6a338d2a03ebae59cd15093910c8875328855781952abf6c2fe/numpy-2.4.6.tar.gz", hash = "sha256:f3a3570c4a2a16746ac2c31a7c7c7b0c186b95ce902e33db6f28094ed7387dda", size = 20735807, upload-time = "2026-05-18T23:37:14.07Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b3/49/ec46835a70be8fa6446c495126ac84fdb28cb2558e1620ffb87a10c8b64c/numpy-2.4.6-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:0280e0356c0829a18d9de1cb7eee50ec22ca639878d7240307ca0943d73cd2c4", size = 16969194, upload-time = "2026-05-18T23:33:13.503Z" },
+    { url = "https://files.pythonhosted.org/packages/0e/0d/f5957185c0ee2f3e12f78715aa9e3b353fd83633316c8532b38faa37e3f6/numpy-2.4.6-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:110f8b71aacb688ec69062bb7f6938a0f8acb01b7c1c4beb453c65b6d234584d", size = 14964111, upload-time = "2026-05-18T23:33:17.795Z" },
+    { url = "https://files.pythonhosted.org/packages/ad/40/40a40ee0ddf7ceb782c49af278894b686e586d65d8c1889c8b5da01a3d7d/numpy-2.4.6-cp311-cp311-macosx_14_0_arm64.whl", hash = "sha256:4cfe66903cc32a9921a6733d96b19bb6abf310397581bbad89c228f5abaf0ee8", size = 5469159, upload-time = "2026-05-18T23:33:20.654Z" },
+    { url = "https://files.pythonhosted.org/packages/63/13/f9a8046535cb21deae82f8d03de9617e08882d274fad2539630761888228/numpy-2.4.6-cp311-cp311-macosx_14_0_x86_64.whl", hash = "sha256:8155154c7c691289fe18f510b5d4657c68c67989f293f0535a91360392ff6538", size = 6798936, upload-time = "2026-05-18T23:33:22.987Z" },
+    { url = "https://files.pythonhosted.org/packages/33/a8/6fa8c1a345a8c85dbb21932c447bee07c30a2c2a3f31e369c0a84b300147/numpy-2.4.6-cp311-cp311-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0ab0a9c4ffb1a6d95ef519fe4247dba8eb6b18ad93999f76b7f657039acabd47", size = 15966692, upload-time = "2026-05-18T23:33:26.62Z" },
+    { url = "https://files.pythonhosted.org/packages/02/03/74fe2a4cb3817d94d86402f2506554130a2f01414e299b5a843e5a8a957f/numpy-2.4.6-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:89cd468399cfd2504718f0ba50e410dca55a170b61a02ad92bb18c8a65186e93", size = 16918164, upload-time = "2026-05-18T23:33:29.955Z" },
+    { url = "https://files.pythonhosted.org/packages/c5/80/3615be3313f7e7696609bc194b9f0101da809df79e859bdb84e0cd043f46/numpy-2.4.6-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:c2d37ab77531417474168eb79d6d80b14f821a966818505d03013d0833edb7a8", size = 17322877, upload-time = "2026-05-18T23:33:34.724Z" },
+    { url = "https://files.pythonhosted.org/packages/ca/ac/a691e0fe2675e370d0e08ff905adc49a1c8830e8cae03efe4477e92cd55d/numpy-2.4.6-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:f407cb6b8e9d6d8c626bc73c945db1706035af8fd632295547bf1c9e46d092d6", size = 18651487, upload-time = "2026-05-18T23:33:38.217Z" },
+    { url = "https://files.pythonhosted.org/packages/15/a7/9bc1cd626d7bf6869bfedf27b91b6ab5dd607758bf8e959d6fa80c6a59cb/numpy-2.4.6-cp311-cp311-win32.whl", hash = "sha256:ddea102b48f9e339f3948bf22040944184627a30fdf7f858667673b9c5f033c8", size = 6233945, upload-time = "2026-05-18T23:33:41.331Z" },
+    { url = "https://files.pythonhosted.org/packages/c5/31/7fc6239c12bce7e931463251cca4426c465e1876ba3cc785402ef4dd8f4e/numpy-2.4.6-cp311-cp311-win_amd64.whl", hash = "sha256:1e254a00cdf42b1e4d5b3d68d33af63268d41340d8885df2ab6470f2e1500147", size = 12608406, upload-time = "2026-05-18T23:33:44.131Z" },
+    { url = "https://files.pythonhosted.org/packages/27/83/140f85a466595a16382996a1bf06b2b54bcd597488921b0c9daaeeda72af/numpy-2.4.6-cp311-cp311-win_arm64.whl", hash = "sha256:ed9749eef4cbd126da3dc1d6bcb3a57f5eb7ac6a6484146bdbf743f552dfc577", size = 10479528, upload-time = "2026-05-18T23:33:50.725Z" },
+    { url = "https://files.pythonhosted.org/packages/de/12/b422cc84439adc0d00de605bf4a308890ae5c26f2c71fbd73e5d08fbb0dd/numpy-2.4.6-pp311-pypy311_pp73-macosx_10_15_x86_64.whl", hash = "sha256:55cced7c52e981362f708ad635198e97a752dfba412cc03c23bbf3bd8d5cd662", size = 16847511, upload-time = "2026-05-18T23:36:50.673Z" },
+    { url = "https://files.pythonhosted.org/packages/44/53/f481bef68011740f8849418d82db07230e825013f31f4eef5ba5b805316a/numpy-2.4.6-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:d6da64deb6b8ed903e7560180a92f2d804ee1ba5eeb849ac2748b8c1aba1f6d7", size = 14889064, upload-time = "2026-05-18T23:36:53.879Z" },
+    { url = "https://files.pythonhosted.org/packages/7f/57/42ed575c10ced8af951d426bc4e1f8aff16fd851db33f067036215a7f860/numpy-2.4.6-pp311-pypy311_pp73-macosx_14_0_arm64.whl", hash = "sha256:68a5124b13fa6cc2086764a20005d30bc0548146f7f5322f02fce212ca14317f", size = 5394157, upload-time = "2026-05-18T23:36:57.194Z" },
+    { url = "https://files.pythonhosted.org/packages/6a/ef/f66cc724fcc36c1e364c67f51ae9146090b8b584f27d58b97fdae3edd737/numpy-2.4.6-pp311-pypy311_pp73-macosx_14_0_x86_64.whl", hash = "sha256:948424b06129ce883307e8cff868c31396d8dc7630a59c61d70d98dbe70f222c", size = 6708728, upload-time = "2026-05-18T23:36:59.575Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/9c/c531f2293b91265d8b48e9b329f54fdd7ffae73cb4134ea10cca4237e9cc/numpy-2.4.6-pp311-pypy311_pp73-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:5dbbdb29840ca3d91ee0fece42fc29278886d908280bfec0a5846c6f901a3eb0", size = 15798374, upload-time = "2026-05-18T23:37:02.674Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/b0/413077f6b1153ed3cba361401c6783bbad6114804a000cc22eb71c13e190/numpy-2.4.6-pp311-pypy311_pp73-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:8ad03c0965fb3c692200e74d458ca28c1dbb4ce96f9a479a8aa041ad5fabca02", size = 16747286, upload-time = "2026-05-18T23:37:06.327Z" },
+    { url = "https://files.pythonhosted.org/packages/15/ce/e5ec180bc41812edcd8daeb8639d205622c0e8c02259d8ab25a0201b3c2a/numpy-2.4.6-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:2803abfebfc990042cd494d8ce2d5f82e9d847af6d35ec486923aa19dbad5e73", size = 12504263, upload-time = "2026-05-18T23:37:09.715Z" },
+]
+
+[[package]]
+name = "onnxruntime"
+version = "1.28.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "flatbuffers" },
+    { name = "numpy" },
+    { name = "packaging" },
+    { name = "protobuf" },
+]
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/17/4d/5014667e2a3a77d6e1b74cc3d88948d06163b8e0a33a84c85073322b5dec/onnxruntime-1.28.0-cp311-cp311-macosx_14_0_arm64.whl", hash = "sha256:f5c5daabd28aad610f83fdcf32acec8fb57e6adc6c6a39fe2a3c755db957b410", size = 19130506, upload-time = "2026-07-25T01:22:34.489Z" },
+    { url = "https://files.pythonhosted.org/packages/ea/97/b7ce1bc8bb6048b5fe9129f55d6506dc19499068ef2e0a0af1ae3c8aa4e7/onnxruntime-1.28.0-cp311-cp311-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:8d66f9ceb29909c70839e4e4fb3435c7b490050d8f162bd5f3aba4ca01ee517f", size = 17039880, upload-time = "2026-07-25T01:21:37.538Z" },
+    { url = "https://files.pythonhosted.org/packages/f3/17/4e5ecd8764f87573c495d834ce79e61ecca47f7a01d1e444a606e570edcb/onnxruntime-1.28.0-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:a166b78ee04f3a37fa1ef82034b6a3ce96d9684e582d4d30b296de83e9998bb5", size = 19193162, upload-time = "2026-07-25T01:21:59.151Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/10/3d946d5d5f2cdcc3c8da36cae63190c516d16349edaffd944bda60ca4c3e/onnxruntime-1.28.0-cp311-cp311-win_amd64.whl", hash = "sha256:0d650aeee29368414367b65529e90afe4bf1bab76254789063b8b2f7ea3013c8", size = 13752539, upload-time = "2026-07-25T01:22:24.524Z" },
+    { url = "https://files.pythonhosted.org/packages/8f/74/1c440be7af1e026280b139caa1be5d11bd4dc368011ddbe8f5362b58e12f/onnxruntime-1.28.0-cp311-cp311-win_arm64.whl", hash = "sha256:0faf85fb447a663c9cdadc39bd6b19bdf7bedded6699e45731b9b36c46fd993d", size = 13449940, upload-time = "2026-07-25T01:22:14.97Z" },
+]
+
+[[package]]
+name = "packaging"
+version = "26.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/7d/fa/3944b40b07da9ce895c0e6303a5ab7d53da063554f534556b134a54d6093/packaging-26.3.tar.gz", hash = "sha256:94edc256424af38762eb31306eed28beb9f0efc50a8837492c9d6fd6004aed79", size = 313412, upload-time = "2026-08-04T18:15:28.737Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/63/34/ba1c580383c9eada3711951fef0795c80b829a078d72188184bcab9dd527/packaging-26.3-py3-none-any.whl", hash = "sha256:d7193f7c8e4e93f444fde0262bf90af30e16fa0ad0ad44cb553c87339b23cd1c", size = 129956, upload-time = "2026-08-04T18:15:27.159Z" },
+]
+
+[[package]]
+name = "protobuf"
+version = "7.35.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/da/01/9ef0afd7999eb9badb3a768b4aedd78c86d4c65cfaf1958ab276199e76b4/protobuf-7.35.1.tar.gz", hash = "sha256:ce115a26fe0c39a2c29973d914d327e516a6455464489fe3cd1e51a1b354f81a", size = 458717, upload-time = "2026-06-11T21:55:40.257Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/10/03/8aeeb7458d22546bf64b5250ca1daeb5ff757d900e8e4a7476c6f0db843e/protobuf-7.35.1-cp310-abi3-macosx_10_9_universal2.whl", hash = "sha256:24f857477359a85c0c235261b8ba905fd51b2562f4a64ca1df5473f29850cbf6", size = 433226, upload-time = "2026-06-11T21:55:31.719Z" },
+    { url = "https://files.pythonhosted.org/packages/37/4b/dfb89eb0e652a1ff073c39a59fb5e3a83cfe9b57a2c83fa6d78270101767/protobuf-7.35.1-cp310-abi3-manylinux2014_aarch64.whl", hash = "sha256:11d6b0ec246892d85215b0a13ca6e0233cf5284b68f0ac02646427f4ff88a799", size = 328847, upload-time = "2026-06-11T21:55:34.035Z" },
+    { url = "https://files.pythonhosted.org/packages/0f/58/dc12f2cd484951524af6e3382c785869b9b3fb5e52ee95ae23add53ee8f9/protobuf-7.35.1-cp310-abi3-manylinux2014_s390x.whl", hash = "sha256:b73f9489a4b8b1c9cb1f8ed951c736392592edb24b9d6819f36d2e10b171d5b4", size = 344030, upload-time = "2026-06-11T21:55:34.941Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/be/5b3cfe508bfab6761414ff944e3366eb13be4fd71efcd69450f89ba39f43/protobuf-7.35.1-cp310-abi3-manylinux2014_x86_64.whl", hash = "sha256:74758715c53d7158fb76caf4f0cfdacc5329a4b1bb994f865d6cf302d413a1c4", size = 327130, upload-time = "2026-06-11T21:55:35.921Z" },
+    { url = "https://files.pythonhosted.org/packages/d8/bc/6d6c7ba8709c85f8f2c390b2b118d6fb08a783676a572271851bf45a7d22/protobuf-7.35.1-cp310-abi3-win32.whl", hash = "sha256:353652e4efd0bca5b5fc2656abf8307ef351f0cf938c9eba09f0e09c20a25c30", size = 428945, upload-time = "2026-06-11T21:55:37.034Z" },
+    { url = "https://files.pythonhosted.org/packages/0a/19/8d0cb6f20a1ef7b18f1c8986ad5783f22f84cce39c6ce9a6e645ea55192e/protobuf-7.35.1-cp310-abi3-win_amd64.whl", hash = "sha256:230a75ddfc2de4806e56696ce9640c1cdfdb6543b7cfce98d42a4c0a0e7bdb87", size = 439996, upload-time = "2026-06-11T21:55:38.123Z" },
+    { url = "https://files.pythonhosted.org/packages/19/c7/5f7c636ec43e0c545e28d1f1db71990108306f7bdcb89f069ba97e428e7f/protobuf-7.35.1-py3-none-any.whl", hash = "sha256:4bc97768d8fe4ad6743c8a19403e314511ed9f6d13205b687e52421c023ac1b9", size = 171659, upload-time = "2026-06-11T21:55:39.155Z" },
+]

labels.json

@@ -0,0 +1,7 @@
+{
+  "labels": [
+    "MYOMYS", "MYOALC", "CNESER", "PIPNAT", "BARBAR", "MYONAT",
+    "MYODAU", "MYOBRA", "PIPPIP", "MYOBEC", "PIPPYG", "RHIHIP",
+    "NYCLEI", "RHIFER", "PLEAUR", "NYCNOC", "PLEAUS"
+  ]
+}

preprocessing/README.md

@@ -0,0 +1,12 @@
+# Preprocessing reference
+
+The ONNX model starts at a normalized mono spectrogram tensor with shape `[1, 1, 128, 256]`. It
+does not accept raw audio.
+
+The Python files under [`upstream/`](upstream/) are an unchanged copy of BatDetect2's complete
+`src/batdetect2/preprocess` package at revision
+`9e2697458d3b3b03c30ccd7e49ed5409c8ac330d`. [View the same pinned directory upstream](https://github.com/macaodha/batdetect2/tree/9e2697458d3b3b03c30ccd7e49ed5409c8ac330d/src/batdetect2/preprocess).
+
+These files depend on the rest of the BatDetect2 package. Use `scripts/fetch-upstream.sh` to
+retrieve the complete pinned checkout, or the locked environment in `environment/` when
+rebuilding the export. The reference copy remains subject to CC BY-NC 4.0.

preprocessing/upstream/__init__.py

@@ -0,0 +1,17 @@
+"""Main entry point for the BatDetect2 preprocessing subsystem."""
+
+from batdetect2.audio import TARGET_SAMPLERATE_HZ
+from batdetect2.preprocess.config import PreprocessingConfig
+from batdetect2.preprocess.preprocessor import Preprocessor, build_preprocessor
+from batdetect2.preprocess.spectrogram import MAX_FREQ, MIN_FREQ
+from batdetect2.preprocess.types import PreprocessorProtocol
+
+__all__ = [
+    "PreprocessorProtocol",
+    "MAX_FREQ",
+    "MIN_FREQ",
+    "PreprocessingConfig",
+    "Preprocessor",
+    "TARGET_SAMPLERATE_HZ",
+    "build_preprocessor",
+]

preprocessing/upstream/audio.py

@@ -0,0 +1,240 @@
+"""Audio-level transforms applied to waveforms before spectrogram computation.
+
+This module defines ``torch.nn.Module`` transforms that operate on raw
+audio tensors and the Pydantic configuration classes that control them.
+Each transform is registered in the ``audio_transforms`` registry so that
+the pipeline can be assembled from a configuration object.
+
+The supported transforms are:
+
+* ``CenterAudio`` — subtract the DC offset (mean) from the waveform.
+* ``ScaleAudio`` — peak-normalise the waveform to the range ``[-1, 1]``.
+* ``FixDuration`` — truncate or zero-pad the waveform to a fixed length.
+"""
+
+from typing import Annotated, Literal
+
+import torch
+from pydantic import Field
+
+from batdetect2.audio import TARGET_SAMPLERATE_HZ
+from batdetect2.core import (
+    BaseConfig,
+    ImportConfig,
+    Registry,
+    add_import_config,
+)
+from batdetect2.preprocess.common import center_tensor, peak_normalize
+
+__all__ = [
+    "AudioTransformImportConfig",
+    "CenterAudioConfig",
+    "ScaleAudioConfig",
+    "FixDurationConfig",
+    "build_audio_transform",
+]
+
+
+audio_transforms: Registry[torch.nn.Module, [int]] = Registry(
+    "audio_transform"
+)
+"""Registry mapping audio transform config classes to their builder methods."""
+
+
+@add_import_config(audio_transforms)
+class AudioTransformImportConfig(ImportConfig):
+    """Use any callable as an audio transform.
+
+    Set ``name="import"`` and provide a ``target`` pointing to any
+    callable to use it instead of a built-in option.
+    """
+
+    name: Literal["import"] = "import"
+
+
+class CenterAudioConfig(BaseConfig):
+    """Configuration for the DC-offset removal transform.
+
+    Attributes
+    ----------
+    name : str
+        Fixed identifier; always ``"center_audio"``.
+    """
+
+    name: Literal["center_audio"] = "center_audio"
+
+
+class CenterAudio(torch.nn.Module):
+    """Remove the DC offset from an audio waveform.
+
+    Subtracts the global mean of the waveform from every sample,
+    centring the signal around zero. This is useful when an analogue
+    recording chain introduces a constant voltage bias.
+    """
+
+    def forward(self, wav: torch.Tensor) -> torch.Tensor:
+        """Subtract the mean from the waveform.
+
+        Parameters
+        ----------
+        wav : torch.Tensor
+            Input waveform tensor of shape ``(samples,)`` or
+            ``(channels, samples)``.
+
+        Returns
+        -------
+        torch.Tensor
+            Zero-centred waveform with the same shape as the input.
+        """
+        return center_tensor(wav)
+
+    @audio_transforms.register(CenterAudioConfig)
+    @staticmethod
+    def from_config(config: CenterAudioConfig, samplerate: int):
+        return CenterAudio()
+
+
+class ScaleAudioConfig(BaseConfig):
+    """Configuration for the peak-normalisation transform.
+
+    Attributes
+    ----------
+    name : str
+        Fixed identifier; always ``"scale_audio"``.
+    """
+
+    name: Literal["scale_audio"] = "scale_audio"
+
+
+class ScaleAudio(torch.nn.Module):
+    """Peak-normalise an audio waveform to the range ``[-1, 1]``.
+
+    Divides the waveform by its largest absolute sample value. If the
+    waveform is identically zero it is returned unchanged.
+    """
+
+    def forward(self, wav: torch.Tensor) -> torch.Tensor:
+        """Peak-normalise the waveform.
+
+        Parameters
+        ----------
+        wav : torch.Tensor
+            Input waveform tensor of any shape.
+
+        Returns
+        -------
+        torch.Tensor
+            Normalised waveform with the same shape as the input and
+            values in the range ``[-1, 1]``.
+        """
+        return peak_normalize(wav)
+
+    @audio_transforms.register(ScaleAudioConfig)
+    @staticmethod
+    def from_config(config: ScaleAudioConfig, samplerate: int):
+        return ScaleAudio()
+
+
+class FixDurationConfig(BaseConfig):
+    """Configuration for the fixed-duration transform.
+
+    Attributes
+    ----------
+    name : str
+        Fixed identifier; always ``"fix_duration"``.
+    duration : float, default=0.5
+        Target duration in seconds. The waveform will be truncated or
+        zero-padded to match this length.
+    """
+
+    name: Literal["fix_duration"] = "fix_duration"
+    duration: float = 0.5
+
+
+class FixDuration(torch.nn.Module):
+    """Ensure a waveform has exactly a specified number of samples.
+
+    If the input is longer than the target length it is truncated from
+    the end. If it is shorter, it is zero-padded at the end.
+
+    Parameters
+    ----------
+    samplerate : int
+        Sample rate of the audio in Hz. Used with ``duration`` to
+        compute the target number of samples.
+    duration : float
+        Target duration in seconds.
+    """
+
+    def __init__(self, samplerate: int, duration: float):
+        super().__init__()
+        self.samplerate = samplerate
+        self.duration = duration
+        self.length = int(samplerate * duration)
+
+    def forward(self, wav: torch.Tensor) -> torch.Tensor:
+        """Truncate or pad the waveform to the target length.
+
+        Parameters
+        ----------
+        wav : torch.Tensor
+            Input waveform tensor of shape ``(samples,)`` or
+            ``(channels, samples)``. The last dimension is adjusted.
+
+        Returns
+        -------
+        torch.Tensor
+            Waveform with exactly ``self.length`` samples along the last
+            dimension.
+        """
+        length = wav.shape[-1]
+
+        if length == self.length:
+            return wav
+
+        if length > self.length:
+            return wav[: self.length]
+
+        return torch.nn.functional.pad(wav, (0, self.length - length))
+
+    @audio_transforms.register(FixDurationConfig)
+    @staticmethod
+    def from_config(config: FixDurationConfig, samplerate: int):
+        return FixDuration(samplerate=samplerate, duration=config.duration)
+
+
+AudioTransform = Annotated[
+    FixDurationConfig | ScaleAudioConfig | CenterAudioConfig,
+    Field(discriminator="name"),
+]
+"""Discriminated union of all audio transform configuration types.
+
+Use this type when a field should accept any of the supported audio
+transforms. Pydantic will select the correct config class based on the
+``name`` field.
+"""
+
+
+def build_audio_transform(
+    config: AudioTransform,
+    samplerate: int = TARGET_SAMPLERATE_HZ,
+) -> torch.nn.Module:
+    """Build an audio transform module from a configuration object.
+
+    Parameters
+    ----------
+    config : AudioTransform
+        A configuration object for one of the supported audio transforms
+        (``CenterAudioConfig``, ``ScaleAudioConfig``, or
+        ``FixDurationConfig``).
+    samplerate : int, default=256000
+        Sample rate of the audio in Hz. Passed to the transform builder;
+        some transforms (e.g. ``FixDuration``) use it to convert seconds
+        to samples.
+
+    Returns
+    -------
+    torch.nn.Module
+        The constructed audio transform module.
+    """
+    return audio_transforms.build(config, samplerate)

preprocessing/upstream/common.py

@@ -0,0 +1,60 @@
+"""Shared tensor primitives used across the preprocessing pipeline.
+
+This module provides small, stateless helper functions that operate on
+PyTorch tensors. They are used by both audio-level and spectrogram-level
+transforms, and are kept here to avoid duplication.
+"""
+
+import torch
+
+__all__ = [
+    "center_tensor",
+    "peak_normalize",
+]
+
+
+def center_tensor(tensor: torch.Tensor) -> torch.Tensor:
+    """Subtract the mean of a tensor from all of its values.
+
+    This centres the signal around zero, removing any constant DC offset.
+
+    Parameters
+    ----------
+    tensor : torch.Tensor
+        Input tensor of any shape.
+
+    Returns
+    -------
+    torch.Tensor
+        A new tensor of the same shape and dtype with the global mean
+        subtracted from every element.
+    """
+    return tensor - tensor.mean()
+
+
+def peak_normalize(tensor: torch.Tensor) -> torch.Tensor:
+    """Scale a tensor so that its largest absolute value equals one.
+
+    Divides the tensor by its peak absolute value. If the tensor is
+    identically zero, it is returned unchanged (no division by zero).
+
+    Parameters
+    ----------
+    tensor : torch.Tensor
+        Input tensor of any shape.
+
+    Returns
+    -------
+    torch.Tensor
+        A new tensor of the same shape and dtype with values in the range
+        ``[-1, 1]`` (or exactly ``[0, 0]`` for a zero tensor).
+    """
+    max_value = tensor.abs().max()
+
+    denominator = torch.where(
+        max_value == 0,
+        torch.tensor(1.0, device=tensor.device, dtype=tensor.dtype),
+        max_value,
+    )
+
+    return tensor / denominator

preprocessing/upstream/config.py

@@ -0,0 +1,75 @@
+"""Configuration for the full batdetect2 preprocessing pipeline.
+
+This module defines :class:`PreprocessingConfig`, which aggregates all
+configuration needed to convert a raw audio waveform into a normalised
+spectrogram ready for the detection model.
+"""
+
+from typing import List
+
+from pydantic import Field
+
+from batdetect2.core.configs import BaseConfig
+from batdetect2.preprocess.audio import AudioTransform
+from batdetect2.preprocess.spectrogram import (
+    FrequencyConfig,
+    PcenConfig,
+    ResizeConfig,
+    SpectralMeanSubtractionConfig,
+    SpectrogramTransform,
+    STFTConfig,
+)
+
+__all__ = [
+    "AudioTransform",
+    "PreprocessingConfig",
+]
+
+
+def _default_spectrogram_transforms() -> list[SpectrogramTransform]:
+    return [
+        PcenConfig(),
+        SpectralMeanSubtractionConfig(),
+    ]
+
+
+class PreprocessingConfig(BaseConfig):
+    """Unified configuration for the audio preprocessing pipeline.
+
+    Aggregates the parameters for every stage of the pipeline:
+    audio-level transforms, STFT computation, frequency cropping,
+    spectrogram-level transforms, and the final resize step.
+
+    Attributes
+    ----------
+    audio_transforms : list of AudioTransform, default=[]
+        Ordered list of transforms applied to the raw audio waveform
+        before the STFT is computed. Each entry is a configuration
+        object for one of the supported audio transforms
+        (``"center_audio"``, ``"scale_audio"``, or ``"fix_duration"``).
+    spectrogram_transforms : list of SpectrogramTransform
+        Ordered list of transforms applied to the cropped spectrogram
+        after the STFT and frequency crop steps. Defaults to
+        ``[PcenConfig(), SpectralMeanSubtractionConfig()]``, which
+        applies PCEN followed by spectral mean subtraction.
+    stft : STFTConfig
+        Parameters for the Short-Time Fourier Transform (window
+        duration, overlap, and window function).
+    frequencies : FrequencyConfig
+        Frequency range (in Hz) to retain after the STFT.
+    size : ResizeConfig
+        Target height (number of frequency bins) and time-axis scaling
+        factor for the final resize step.
+    """
+
+    audio_transforms: List[AudioTransform] = Field(default_factory=list)
+
+    spectrogram_transforms: List[SpectrogramTransform] = Field(
+        default_factory=_default_spectrogram_transforms
+    )
+
+    stft: STFTConfig = Field(default_factory=STFTConfig)
+
+    frequencies: FrequencyConfig = Field(default_factory=FrequencyConfig)
+
+    size: ResizeConfig = Field(default_factory=ResizeConfig)

preprocessing/upstream/preprocessor.py

@@ -0,0 +1,253 @@
+"""Assembles the full batdetect2 preprocessing pipeline.
+
+This module defines :class:`Preprocessor`, the concrete implementation of
+:class:`~batdetect2.preprocess.types.PreprocessorProtocol`, and the
+:func:`build_preprocessor` factory function that constructs it from a
+:class:`~batdetect2.preprocess.config.PreprocessingConfig`.
+
+The preprocessing pipeline converts a raw audio waveform (as a
+``torch.Tensor``) into a normalised, cropped, and resized spectrogram ready
+for the detection model. The stages are applied in this order:
+
+1. **Audio transforms** — optional waveform-level operations such as DC
+   removal, peak normalisation, or duration fixing.
+2. **STFT** — Short-Time Fourier Transform to produce an amplitude
+   spectrogram.
+3. **Frequency crop** — retain only the frequency band of interest.
+4. **Spectrogram transforms** — normalisation operations such as PCEN and
+   spectral mean subtraction.
+5. **Resize** — scale the spectrogram to the model's expected height and
+   reduce the time resolution.
+"""
+
+import torch
+from loguru import logger
+
+from batdetect2.audio import TARGET_SAMPLERATE_HZ
+from batdetect2.preprocess.audio import build_audio_transform
+from batdetect2.preprocess.config import PreprocessingConfig
+from batdetect2.preprocess.spectrogram import (
+    _spec_params_from_config,
+    build_spectrogram_builder,
+    build_spectrogram_crop,
+    build_spectrogram_resizer,
+    build_spectrogram_transform,
+)
+from batdetect2.preprocess.types import PreprocessorProtocol
+
+__all__ = [
+    "Preprocessor",
+    "build_preprocessor",
+]
+
+
+class Preprocessor(torch.nn.Module, PreprocessorProtocol):
+    """Standard implementation of the :class:`~batdetect2.preprocess.types.PreprocessorProtocol`.
+
+    Wraps all preprocessing stages as ``torch.nn.Module`` submodules so
+    that parameters (e.g. PCEN filter coefficients) can be tracked and
+    moved between devices.
+
+    Parameters
+    ----------
+    config : PreprocessingConfig
+        Full pipeline configuration.
+    input_samplerate : int
+        Sample rate of the audio that will be passed to this preprocessor,
+        in Hz.
+
+    Attributes
+    ----------
+    input_samplerate : int
+        Sample rate of the input audio in Hz.
+    output_samplerate : float
+        Effective frame rate of the output spectrogram in frames per second.
+        Computed from the STFT hop length and the time-axis resize factor.
+    min_freq : float
+        Lower bound of the retained frequency band in Hz.
+    max_freq : float
+        Upper bound of the retained frequency band in Hz.
+    """
+
+    input_samplerate: int
+    output_samplerate: float
+
+    max_freq: float
+    min_freq: float
+
+    def __init__(
+        self,
+        config: PreprocessingConfig,
+        input_samplerate: int,
+    ) -> None:
+        super().__init__()
+
+        self.audio_transforms = torch.nn.Sequential(
+            *(
+                build_audio_transform(step, samplerate=input_samplerate)
+                for step in config.audio_transforms
+            )
+        )
+
+        self.spectrogram_transforms = torch.nn.Sequential(
+            *(
+                build_spectrogram_transform(step, samplerate=input_samplerate)
+                for step in config.spectrogram_transforms
+            )
+        )
+
+        self.spectrogram_builder = build_spectrogram_builder(
+            config.stft,
+            samplerate=input_samplerate,
+        )
+
+        self.spectrogram_crop = build_spectrogram_crop(
+            config.frequencies,
+            stft=config.stft,
+            samplerate=input_samplerate,
+        )
+
+        self.spectrogram_resizer = build_spectrogram_resizer(config.size)
+
+        self.min_freq = config.frequencies.min_freq
+        self.max_freq = config.frequencies.max_freq
+
+        self.input_samplerate = input_samplerate
+        self.output_samplerate = compute_output_samplerate(
+            config,
+            input_samplerate=input_samplerate,
+        )
+
+    def forward(self, wav: torch.Tensor) -> torch.Tensor:
+        """Run the full preprocessing pipeline on a waveform.
+
+        Applies audio transforms, then the STFT, then
+        :meth:`process_spectrogram`.
+
+        Parameters
+        ----------
+        wav : torch.Tensor
+            Input waveform of shape ``(samples,)``.
+
+        Returns
+        -------
+        torch.Tensor
+            Preprocessed spectrogram of shape
+            ``(freq_bins, time_frames)``.
+        """
+        wav = self.audio_transforms(wav)
+        spec = self.spectrogram_builder(wav)
+        return self.process_spectrogram(spec)
+
+    def generate_spectrogram(self, wav: torch.Tensor) -> torch.Tensor:
+        """Compute the raw STFT spectrogram without any further processing.
+
+        Parameters
+        ----------
+        wav : torch.Tensor
+            Input waveform of shape ``(samples,)``.
+
+        Returns
+        -------
+        torch.Tensor
+            Amplitude spectrogram of shape ``(n_fft//2 + 1, time_frames)``
+            with no frequency cropping, normalisation, or resizing applied.
+        """
+        return self.spectrogram_builder(wav)
+
+    def process_audio(self, wav: torch.Tensor) -> torch.Tensor:
+        """Alias for :meth:`forward`.
+
+        Parameters
+        ----------
+        wav : torch.Tensor
+            Input waveform of shape ``(samples,)``.
+
+        Returns
+        -------
+        torch.Tensor
+            Preprocessed spectrogram (same as calling the object directly).
+        """
+        return self(wav)
+
+    def process_spectrogram(self, spec: torch.Tensor) -> torch.Tensor:
+        """Apply the post-STFT processing stages to an existing spectrogram.
+
+        Applies frequency cropping, spectrogram-level transforms (e.g.
+        PCEN, spectral mean subtraction), and the final resize step.
+
+        Parameters
+        ----------
+        spec : torch.Tensor
+            Raw amplitude spectrogram of shape
+            ``(..., n_fft//2 + 1, time_frames)``.
+
+        Returns
+        -------
+        torch.Tensor
+            Normalised and resized spectrogram of shape
+            ``(..., height, scaled_time_frames)``.
+        """
+        spec = self.spectrogram_crop(spec)
+        spec = self.spectrogram_transforms(spec)
+        return self.spectrogram_resizer(spec)
+
+
+def compute_output_samplerate(
+    config: PreprocessingConfig,
+    input_samplerate: int = TARGET_SAMPLERATE_HZ,
+) -> float:
+    """Compute the effective frame rate of the preprocessor's output.
+
+    The output frame rate (in frames per second) depends on the STFT hop
+    length and the time-axis resize factor applied by the final resize step.
+
+    Parameters
+    ----------
+    config : PreprocessingConfig
+        Pipeline configuration.
+    input_samplerate : int, default=256000
+        Sample rate of the input audio in Hz.
+
+    Returns
+    -------
+    float
+        Output frame rate in frames per second.
+        For example, at the default settings (256 kHz, hop=128,
+        resize_factor=0.5) this equals ``1000.0``.
+    """
+    _, hop_size = _spec_params_from_config(
+        config.stft, samplerate=input_samplerate
+    )
+    factor = config.size.resize_factor
+    return input_samplerate * factor / hop_size
+
+
+def build_preprocessor(
+    config: PreprocessingConfig | None = None,
+    input_samplerate: int = TARGET_SAMPLERATE_HZ,
+) -> PreprocessorProtocol:
+    """Build the standard preprocessor from a configuration object.
+
+    Parameters
+    ----------
+    config : PreprocessingConfig, optional
+        Pipeline configuration. If ``None``, the default
+        ``PreprocessingConfig()`` is used (PCEN + spectral mean
+        subtraction, 256 kHz, standard STFT parameters).
+    input_samplerate : int, default=256000
+        Sample rate of the audio that will be fed to the preprocessor,
+        in Hz.
+
+    Returns
+    -------
+    PreprocessorProtocol
+        A :class:`Preprocessor` instance ready to convert waveforms to
+        spectrograms.
+    """
+    config = config or PreprocessingConfig()
+    logger.opt(lazy=True).debug(
+        "Building preprocessor with config: \n{}",
+        lambda: config.to_yaml_string(),
+    )
+    return Preprocessor(config=config, input_samplerate=input_samplerate)

preprocessing/upstream/spectrogram.py

@@ -0,0 +1,820 @@
+"""Computes spectrograms from audio waveforms with configurable parameters.
+
+This module defines the STFT-based spectrogram builder and a collection of
+spectrogram-level transforms (PCEN, spectral mean subtraction, amplitude
+scaling, peak normalisation, frequency cropping, and resizing) that form the
+signal-processing stage of the batdetect2 preprocessing pipeline.
+
+Each transform is paired with a Pydantic configuration class and registered
+in the ``spectrogram_transforms`` registry so that the pipeline can be fully
+specified via a YAML or Python configuration object.
+"""
+
+from typing import Annotated, Callable, Literal
+
+import numpy as np
+import torch
+import torchaudio
+from pydantic import Field
+
+from batdetect2.audio import TARGET_SAMPLERATE_HZ
+from batdetect2.core.configs import BaseConfig
+from batdetect2.core.registries import (
+    ImportConfig,
+    Registry,
+    add_import_config,
+)
+from batdetect2.preprocess.common import peak_normalize
+
+__all__ = [
+    "STFTConfig",
+    "SpectrogramTransformImportConfig",
+    "build_spectrogram_transform",
+    "build_spectrogram_builder",
+]
+
+
+MIN_FREQ = 10_000
+"""Default minimum frequency (Hz) for spectrogram frequency cropping."""
+
+MAX_FREQ = 120_000
+"""Default maximum frequency (Hz) for spectrogram frequency cropping."""
+
+
+class STFTConfig(BaseConfig):
+    """Configuration for the Short-Time Fourier Transform (STFT).
+
+    Attributes
+    ----------
+    window_duration : float, default=0.002
+        Duration of the STFT analysis window in seconds (e.g. 0.002 for
+        2 ms). Must be > 0. A longer window gives finer frequency resolution
+        but coarser time resolution.
+    window_overlap : float, default=0.75
+        Fraction of overlap between consecutive windows (e.g. 0.75 for
+        75 %). Must be >= 0 and < 1. Higher overlap gives finer time
+        resolution at the cost of more computation.
+    window_fn : str, default="hann"
+        Name of the tapering window applied to each frame before the FFT.
+        Supported values: ``"hann"``, ``"hamming"``, ``"kaiser"``,
+        ``"blackman"``, ``"bartlett"``.
+
+    Notes
+    -----
+    At the default sample rate of 256 kHz, ``window_duration=0.002`` and
+    ``window_overlap=0.75`` give ``n_fft=512`` and ``hop_length=128``.
+    """
+
+    window_duration: float = Field(default=0.002, gt=0)
+    window_overlap: float = Field(default=0.75, ge=0, lt=1)
+    window_fn: str = "hann"
+
+
+def build_spectrogram_builder(
+    config: STFTConfig,
+    samplerate: int = TARGET_SAMPLERATE_HZ,
+) -> torch.nn.Module:
+    """Build a torchaudio STFT spectrogram module from an ``STFTConfig``.
+
+    Parameters
+    ----------
+    config : STFTConfig
+        STFT parameters (window duration, overlap, and window function).
+    samplerate : int, default=256000
+        Sample rate of the input audio in Hz. Used to convert the
+        window duration into a number of samples.
+
+    Returns
+    -------
+    torch.nn.Module
+        A ``torchaudio.transforms.Spectrogram`` module configured to
+        produce an amplitude (``power=1``) spectrogram with centred
+        frames.
+    """
+    n_fft, hop_length = _spec_params_from_config(config, samplerate=samplerate)
+    return torchaudio.transforms.Spectrogram(
+        n_fft=n_fft,
+        hop_length=hop_length,
+        window_fn=get_spectrogram_window(config.window_fn),
+        center=True,
+        power=1,
+    )
+
+
+def get_spectrogram_window(name: str) -> Callable[..., torch.Tensor]:
+    """Return the PyTorch window function matching the given name.
+
+    Parameters
+    ----------
+    name : str
+        Name of the window function. One of ``"hann"``, ``"hamming"``,
+        ``"kaiser"``, ``"blackman"``, or ``"bartlett"``.
+
+    Returns
+    -------
+    Callable[..., torch.Tensor]
+        A PyTorch window function that accepts a window length and returns
+        a 1-D tensor of weights.
+
+    Raises
+    ------
+    NotImplementedError
+        If ``name`` does not match any supported window function.
+    """
+    if name == "hann":
+        return torch.hann_window
+
+    if name == "hamming":
+        return torch.hamming_window
+
+    if name == "kaiser":
+        return torch.kaiser_window
+
+    if name == "blackman":
+        return torch.blackman_window
+
+    if name == "bartlett":
+        return torch.bartlett_window
+
+    raise NotImplementedError(
+        f"Spectrogram window function {name} not implemented"
+    )
+
+
+def _spec_params_from_config(
+    config: STFTConfig,
+    samplerate: int = TARGET_SAMPLERATE_HZ,
+) -> tuple[int, int]:
+    """Compute ``n_fft`` and ``hop_length`` from an ``STFTConfig``.
+
+    Parameters
+    ----------
+    config : STFTConfig
+        STFT parameters.
+    samplerate : int, default=256000
+        Sample rate of the input audio in Hz.
+
+    Returns
+    -------
+    tuple[int, int]
+        A pair ``(n_fft, hop_length)`` giving the FFT size and the step
+        between consecutive frames in samples.
+    """
+    n_fft = int(samplerate * config.window_duration)
+    hop_length = int(n_fft * (1 - config.window_overlap))
+    return n_fft, hop_length
+
+
+def _frequency_to_index(
+    freq: float,
+    n_fft: int,
+    samplerate: int = TARGET_SAMPLERATE_HZ,
+) -> int | None:
+    """Convert a frequency in Hz to the nearest STFT frequency bin index.
+
+    Parameters
+    ----------
+    freq : float
+        Frequency in Hz to convert.
+    n_fft : int
+        FFT size used by the STFT.
+    samplerate : int, default=256000
+        Sample rate of the audio in Hz.
+
+    Returns
+    -------
+    int or None
+        The bin index corresponding to ``freq``, or ``None`` if the
+        frequency is outside the valid range (i.e. <= 0 Hz or >= the
+        Nyquist frequency).
+    """
+    alpha = freq * 2 / samplerate
+    height = np.floor(n_fft / 2) + 1
+    index = int(np.floor(alpha * height))
+
+    if index <= 0:
+        return None
+
+    if index >= height:
+        return None
+
+    return index
+
+
+class FrequencyConfig(BaseConfig):
+    """Configuration for frequency axis parameters.
+
+    Attributes
+    ----------
+    max_freq : int, default=120000
+        Maximum frequency in Hz to retain after STFT. Frequency bins
+        above this value are discarded. Must be >= 0.
+    min_freq : int, default=10000
+        Minimum frequency in Hz to retain after STFT. Frequency bins
+        below this value are discarded. Must be >= 0.
+    """
+
+    max_freq: int = Field(default=MAX_FREQ, ge=0)
+    min_freq: int = Field(default=MIN_FREQ, ge=0)
+
+
+class FrequencyCrop(torch.nn.Module):
+    """Crop a spectrogram to a specified frequency band.
+
+    On construction the Hz boundaries are converted to STFT bin indices.
+    During the forward pass the spectrogram is sliced along its
+    frequency axis (second-to-last dimension) to retain only the bins
+    that fall within ``[min_freq, max_freq)``.
+
+    Parameters
+    ----------
+    samplerate : int
+        Sample rate of the audio in Hz.
+    n_fft : int
+        FFT size used by the STFT.
+    min_freq : int, optional
+        Lower frequency bound in Hz. If ``None``, no lower crop is
+        applied and the DC bin is retained.
+    max_freq : int, optional
+        Upper frequency bound in Hz. If ``None``, no upper crop is
+        applied and all bins up to Nyquist are retained.
+    """
+
+    def __init__(
+        self,
+        samplerate: int,
+        n_fft: int,
+        min_freq: int | None = None,
+        max_freq: int | None = None,
+    ):
+        super().__init__()
+        self.n_fft = n_fft
+        self.samplerate = samplerate
+        self.min_freq = min_freq
+        self.max_freq = max_freq
+
+        low_index = None
+        if min_freq is not None:
+            low_index = _frequency_to_index(
+                min_freq,
+                n_fft=self.n_fft,
+                samplerate=self.samplerate,
+            )
+        self.low_index = low_index
+
+        high_index = None
+        if max_freq is not None:
+            high_index = _frequency_to_index(
+                max_freq,
+                n_fft=self.n_fft,
+                samplerate=self.samplerate,
+            )
+        self.high_index = high_index
+
+    def forward(self, spec: torch.Tensor) -> torch.Tensor:
+        """Crop the spectrogram to the configured frequency band.
+
+        Parameters
+        ----------
+        spec : torch.Tensor
+            Spectrogram tensor of shape ``(..., freq_bins, time_frames)``.
+
+        Returns
+        -------
+        torch.Tensor
+            Cropped spectrogram with shape
+            ``(..., n_retained_bins, time_frames)``.
+        """
+        low_index = self.low_index
+        if low_index is None:
+            low_index = 0
+
+        if self.high_index is None:
+            length = spec.shape[-2] - low_index
+        else:
+            length = self.high_index - low_index
+
+        return torch.narrow(
+            spec,
+            dim=-2,
+            start=low_index,
+            length=length,
+        )
+
+
+def build_spectrogram_crop(
+    config: FrequencyConfig,
+    stft: STFTConfig | None = None,
+    samplerate: int = TARGET_SAMPLERATE_HZ,
+) -> torch.nn.Module:
+    """Build a ``FrequencyCrop`` module from configuration objects.
+
+    Parameters
+    ----------
+    config : FrequencyConfig
+        Frequency boundary configuration specifying ``min_freq`` and
+        ``max_freq`` in Hz.
+    stft : STFTConfig, optional
+        STFT configuration used to derive ``n_fft``. Defaults to
+        ``STFTConfig()`` if not provided.
+    samplerate : int, default=256000
+        Sample rate of the audio in Hz.
+
+    Returns
+    -------
+    torch.nn.Module
+        A ``FrequencyCrop`` module ready to crop spectrograms.
+    """
+    stft = stft or STFTConfig()
+    n_fft, _ = _spec_params_from_config(stft, samplerate=samplerate)
+    return FrequencyCrop(
+        samplerate=samplerate,
+        n_fft=n_fft,
+        min_freq=config.min_freq,
+        max_freq=config.max_freq,
+    )
+
+
+class ResizeConfig(BaseConfig):
+    """Configuration for the final spectrogram resize step.
+
+    Attributes
+    ----------
+    name : str
+        Fixed identifier; always ``"resize_spec"``.
+    height : int, default=128
+        Target number of frequency bins in the output spectrogram.
+        The spectrogram is resized to this height using bilinear
+        interpolation.
+    resize_factor : float, default=0.5
+        Fraction by which the time axis is scaled. For example, ``0.5``
+        halves the number of time frames, reducing computational cost
+        downstream.
+    """
+
+    name: Literal["resize_spec"] = "resize_spec"
+    height: int = 128
+    resize_factor: float = 0.5
+
+
+class ResizeSpec(torch.nn.Module):
+    """Resize a spectrogram to a fixed height and scaled width.
+
+    Uses bilinear interpolation so it handles arbitrary input shapes
+    gracefully. Input tensors with fewer than four dimensions are
+    temporarily unsqueezed to satisfy ``torch.nn.functional.interpolate``.
+
+    Parameters
+    ----------
+    height : int
+        Target number of frequency bins (output height).
+    time_factor : float
+        Multiplicative scaling applied to the time axis length.
+    """
+
+    def __init__(self, height: int, time_factor: float):
+        super().__init__()
+        self.height = height
+        self.time_factor = time_factor
+
+    def forward(self, spec: torch.Tensor) -> torch.Tensor:
+        """Resize the spectrogram to the configured output dimensions.
+
+        Parameters
+        ----------
+        spec : torch.Tensor
+            Input spectrogram of shape ``(..., freq_bins, time_frames)``.
+
+        Returns
+        -------
+        torch.Tensor
+            Resized spectrogram with shape
+            ``(..., height, int(time_factor * time_frames))``.
+        """
+        current_length = spec.shape[-1]
+        target_length = int(self.time_factor * current_length)
+
+        original_ndim = spec.ndim
+        while spec.ndim < 4:
+            spec = spec.unsqueeze(0)
+
+        resized = torch.nn.functional.interpolate(
+            spec,
+            size=(self.height, target_length),
+            mode="bilinear",
+        )
+
+        while resized.ndim != original_ndim:
+            resized = resized.squeeze(0)
+
+        return resized
+
+
+def build_spectrogram_resizer(config: ResizeConfig) -> torch.nn.Module:
+    """Build a ``ResizeSpec`` module from a ``ResizeConfig``.
+
+    Parameters
+    ----------
+    config : ResizeConfig
+        Resize configuration specifying ``height`` and ``resize_factor``.
+
+    Returns
+    -------
+    torch.nn.Module
+        A ``ResizeSpec`` module configured with the given parameters.
+    """
+    return ResizeSpec(height=config.height, time_factor=config.resize_factor)
+
+
+spectrogram_transforms: Registry[torch.nn.Module, [int]] = Registry(
+    "spectrogram_transform"
+)
+
+
+@add_import_config(spectrogram_transforms)
+class SpectrogramTransformImportConfig(ImportConfig):
+    """Use any callable as a spectrogram transform.
+
+    Set ``name="import"`` and provide a ``target`` pointing to any
+    callable to use it instead of a built-in option.
+    """
+
+    name: Literal["import"] = "import"
+
+
+class PcenConfig(BaseConfig):
+    """Configuration for Per-Channel Energy Normalisation (PCEN).
+
+    PCEN is a frontend processing technique that replaces simple log
+    compression. It applies a learnable automatic gain control followed
+    by a stabilised root compression, making the representation more
+    robust to variations in recording level.
+
+    Attributes
+    ----------
+    name : str
+        Fixed identifier; always ``"pcen"``.
+    time_constant : float, default=0.4
+        Time constant (in seconds) of the IIR smoothing filter used
+        for the background estimate. Larger values produce a slower-
+        adapting background.
+    gain : float, default=0.98
+        Exponent controlling how strongly the background estimate
+        suppresses the signal.
+    bias : float, default=2
+        Stabilisation bias added inside the root-compression step to
+        avoid division by zero.
+    power : float, default=0.5
+        Root-compression exponent. A value of 0.5 gives square-root
+        compression, similar to log compression but differentiable at
+        zero.
+    """
+
+    name: Literal["pcen"] = "pcen"
+    time_constant: float = 0.4
+    gain: float = 0.98
+    bias: float = 2
+    power: float = 0.5
+
+
+class PCEN(torch.nn.Module):
+    """Per-Channel Energy Normalisation (PCEN) transform.
+
+    Applies automatic gain control and root compression to a spectrogram.
+    The background estimate is computed with a first-order IIR filter
+    applied along the time axis.
+
+    Parameters
+    ----------
+    smoothing_constant : float
+        IIR filter coefficient ``alpha``. Derived from the time constant
+        and sample rate via ``_compute_smoothing_constant``.
+    gain : float, default=0.98
+        AGC gain exponent.
+    bias : float, default=2.0
+        Root-compression stabilisation bias.
+    power : float, default=0.5
+        Root-compression exponent.
+    eps : float, default=1e-6
+        Small constant for numerical stability.
+    dtype : torch.dtype, default=torch.float32
+        Floating-point precision used for internal computation.
+
+    Notes
+    -----
+    The smoothing constant is computed to match the original batdetect2
+    implementation for numerical compatibility. See
+    ``_compute_smoothing_constant`` for details.
+    """
+
+    def __init__(
+        self,
+        smoothing_constant: float,
+        gain: float = 0.98,
+        bias: float = 2.0,
+        power: float = 0.5,
+        eps: float = 1e-6,
+        dtype=torch.float32,
+    ):
+        super().__init__()
+        self.smoothing_constant = smoothing_constant
+        self.gain = torch.tensor(gain, dtype=dtype)
+        self.bias = torch.tensor(bias, dtype=dtype)
+        self.power = torch.tensor(power, dtype=dtype)
+        self.eps = torch.tensor(eps, dtype=dtype)
+        self.dtype = dtype
+
+        self._b = torch.tensor([self.smoothing_constant, 0.0], dtype=dtype)
+        self._a = torch.tensor(
+            [1.0, self.smoothing_constant - 1.0], dtype=dtype
+        )
+
+    def forward(self, spec: torch.Tensor) -> torch.Tensor:
+        """Apply PCEN to a spectrogram.
+
+        Parameters
+        ----------
+        spec : torch.Tensor
+            Input amplitude spectrogram of shape
+            ``(..., freq_bins, time_frames)``.
+
+        Returns
+        -------
+        torch.Tensor
+            PCEN-normalised spectrogram with the same shape and dtype as
+            the input.
+        """
+        S = spec.to(self.dtype) * 2**31
+
+        M = (
+            torchaudio.functional.lfilter(
+                S,
+                self._a,
+                self._b,
+                clamp=False,
+            )
+        ).clamp(min=0)
+
+        smooth = torch.exp(
+            -self.gain * (torch.log(self.eps) + torch.log1p(M / self.eps))
+        )
+
+        return (
+            (self.bias**self.power)
+            * torch.expm1(self.power * torch.log1p(S * smooth / self.bias))
+        ).to(spec.dtype)
+
+    @spectrogram_transforms.register(PcenConfig)
+    @staticmethod
+    def from_config(config: PcenConfig, samplerate: int):
+        smooth = _compute_smoothing_constant(samplerate, config.time_constant)
+        return PCEN(
+            smoothing_constant=smooth,
+            gain=config.gain,
+            bias=config.bias,
+            power=config.power,
+        )
+
+
+def _compute_smoothing_constant(
+    samplerate: int,
+    time_constant: float,
+) -> float:
+    """Compute the IIR smoothing coefficient for PCEN.
+
+    Parameters
+    ----------
+    samplerate : int
+        Sample rate of the audio in Hz.
+    time_constant : float
+        Desired smoothing time constant in seconds.
+
+    Returns
+    -------
+    float
+        IIR filter coefficient ``alpha`` used by ``PCEN``.
+
+    Notes
+    -----
+    The hop length (512) and the sample-rate divisor (10) are fixed to
+    reproduce the numerical behaviour of the original batdetect2
+    implementation, which used ``librosa.pcen`` with ``sr=samplerate/10``
+    and the default ``hop_length=512``. These values do not reflect the
+    actual STFT hop length used in the pipeline; they are retained
+    solely for backward compatibility.
+    """
+    # NOTE: These parameters are fixed to match the original implementation.
+    hop_length = 512
+    sr = samplerate / 10
+    t_frames = time_constant * sr / float(hop_length)
+    return (np.sqrt(1 + 4 * t_frames**2) - 1) / (2 * t_frames**2)
+
+
+class ScaleAmplitudeConfig(BaseConfig):
+    """Configuration for amplitude scaling of a spectrogram.
+
+    Attributes
+    ----------
+    name : str
+        Fixed identifier; always ``"scale_amplitude"``.
+    scale : str, default="db"
+        Scaling mode. Either ``"db"`` (convert amplitude to decibels
+        using ``torchaudio.transforms.AmplitudeToDB``) or ``"power"``
+        (square the amplitude values).
+    """
+
+    name: Literal["scale_amplitude"] = "scale_amplitude"
+    scale: Literal["power", "db"] = "db"
+
+
+class ToPower(torch.nn.Module):
+    """Square the values of a spectrogram (amplitude → power).
+
+    Raises each element to the power of two, converting an amplitude
+    spectrogram into a power spectrogram.
+    """
+
+    def forward(self, spec: torch.Tensor) -> torch.Tensor:
+        """Square all elements of the spectrogram.
+
+        Parameters
+        ----------
+        spec : torch.Tensor
+            Input amplitude spectrogram.
+
+        Returns
+        -------
+        torch.Tensor
+            Power spectrogram (same shape as input).
+        """
+        return spec**2
+
+
+_scalers = {
+    "db": torchaudio.transforms.AmplitudeToDB,
+    "power": ToPower,
+}
+
+
+class ScaleAmplitude(torch.nn.Module):
+    """Convert spectrogram amplitude values to a different scale.
+
+    Supports conversion to decibels (dB) or to power (squared amplitude).
+
+    Parameters
+    ----------
+    scale : str
+        Either ``"db"`` or ``"power"``.
+    """
+
+    def __init__(self, scale: Literal["power", "db"]):
+        super().__init__()
+        self.scale = scale
+        self.scaler = _scalers[scale]()
+
+    def forward(self, spec: torch.Tensor) -> torch.Tensor:
+        """Apply the configured amplitude scaling.
+
+        Parameters
+        ----------
+        spec : torch.Tensor
+            Input spectrogram tensor.
+
+        Returns
+        -------
+        torch.Tensor
+            Scaled spectrogram with the same shape as the input.
+        """
+        return self.scaler(spec)
+
+    @spectrogram_transforms.register(ScaleAmplitudeConfig)
+    @staticmethod
+    def from_config(config: ScaleAmplitudeConfig, samplerate: int):
+        return ScaleAmplitude(scale=config.scale)
+
+
+class SpectralMeanSubtractionConfig(BaseConfig):
+    """Configuration for spectral mean subtraction.
+
+    Attributes
+    ----------
+    name : str
+        Fixed identifier; always ``"spectral_mean_subtraction"``.
+    """
+
+    name: Literal["spectral_mean_subtraction"] = "spectral_mean_subtraction"
+
+
+class SpectralMeanSubtraction(torch.nn.Module):
+    """Remove the time-averaged background noise from a spectrogram.
+
+    For each frequency bin, the mean value across all time frames is
+    computed and subtracted. The result is then clamped to zero so that
+    no values fall below the baseline. This is a simple form of spectral
+    denoising that suppresses stationary background noise.
+    """
+
+    def forward(self, spec: torch.Tensor) -> torch.Tensor:
+        """Subtract the time-axis mean from each frequency bin.
+
+        Parameters
+        ----------
+        spec : torch.Tensor
+            Input spectrogram of shape ``(..., freq_bins, time_frames)``.
+
+        Returns
+        -------
+        torch.Tensor
+            Denoised spectrogram with the same shape as the input. All
+            values are non-negative (clamped to 0).
+        """
+        mean = spec.mean(-1, keepdim=True)
+        return (spec - mean).clamp(min=0)
+
+    @spectrogram_transforms.register(SpectralMeanSubtractionConfig)
+    @staticmethod
+    def from_config(
+        config: SpectralMeanSubtractionConfig,
+        samplerate: int,
+    ):
+        return SpectralMeanSubtraction()
+
+
+class PeakNormalizeConfig(BaseConfig):
+    """Configuration for peak normalisation of a spectrogram.
+
+    Attributes
+    ----------
+    name : str
+        Fixed identifier; always ``"peak_normalize"``.
+    """
+
+    name: Literal["peak_normalize"] = "peak_normalize"
+
+
+class PeakNormalize(torch.nn.Module):
+    """Scale a spectrogram so that its largest absolute value equals one.
+
+    Wraps :func:`batdetect2.preprocess.common.peak_normalize` as a
+    ``torch.nn.Module`` for use inside a sequential transform pipeline.
+    """
+
+    def forward(self, spec: torch.Tensor) -> torch.Tensor:
+        """Peak-normalise the spectrogram.
+
+        Parameters
+        ----------
+        spec : torch.Tensor
+            Input spectrogram tensor of any shape.
+
+        Returns
+        -------
+        torch.Tensor
+            Normalised spectrogram where the maximum absolute value is 1.
+            If the input is identically zero, it is returned unchanged.
+        """
+        return peak_normalize(spec)
+
+    @spectrogram_transforms.register(PeakNormalizeConfig)
+    @staticmethod
+    def from_config(config: PeakNormalizeConfig, samplerate: int):
+        return PeakNormalize()
+
+
+SpectrogramTransform = Annotated[
+    PcenConfig
+    | ScaleAmplitudeConfig
+    | SpectralMeanSubtractionConfig
+    | PeakNormalizeConfig,
+    Field(discriminator="name"),
+]
+"""Discriminated union of all spectrogram transform configuration types.
+
+Use this type when a field should accept any of the supported spectrogram
+transforms. Pydantic will select the correct config class based on the
+``name`` field.
+"""
+
+
+def build_spectrogram_transform(
+    config: SpectrogramTransform,
+    samplerate: int,
+) -> torch.nn.Module:
+    """Build a spectrogram transform module from a configuration object.
+
+    Parameters
+    ----------
+    config : SpectrogramTransform
+        A configuration object for one of the supported spectrogram
+        transforms (PCEN, amplitude scaling, spectral mean subtraction,
+        or peak normalisation).
+    samplerate : int
+        Sample rate of the audio in Hz. Some transforms (e.g. PCEN) use
+        this to set internal parameters.
+
+    Returns
+    -------
+    torch.nn.Module
+        The constructed transform module.
+    """
+    return spectrogram_transforms.build(config, samplerate)

preprocessing/upstream/types.py

@@ -0,0 +1,31 @@
+from typing import Protocol
+
+import numpy as np
+import torch
+
+__all__ = [
+    "PreprocessorProtocol",
+    "SpectrogramBuilder",
+]
+
+
+class SpectrogramBuilder(Protocol):
+    def __call__(self, wav: torch.Tensor) -> torch.Tensor: ...
+
+
+class PreprocessorProtocol(Protocol):
+    max_freq: float
+    min_freq: float
+    input_samplerate: int
+    output_samplerate: float
+
+    def __call__(self, wav: torch.Tensor) -> torch.Tensor: ...
+
+    def generate_spectrogram(self, wav: torch.Tensor) -> torch.Tensor: ...
+
+    def process_audio(self, wav: torch.Tensor) -> torch.Tensor: ...
+
+    def process_spectrogram(self, spec: torch.Tensor) -> torch.Tensor: ...
+
+    def process_numpy(self, wav: np.ndarray) -> np.ndarray:
+        return self(torch.tensor(wav)).numpy()

scripts/export_batdetect2_onnx.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""Export the authoritative BatDetect2 detector/classifier checkpoint to ONNX."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+EXPECTED_UK_LABELS = [
+    "MYOMYS",
+    "MYOALC",
+    "CNESER",
+    "PIPNAT",
+    "BARBAR",
+    "MYONAT",
+    "MYODAU",
+    "MYOBRA",
+    "PIPPIP",
+    "MYOBEC",
+    "PIPPYG",
+    "RHIHIP",
+    "NYCLEI",
+    "RHIFER",
+    "PLEAUR",
+    "NYCNOC",
+    "PLEAUS",
+]
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--source", type=Path, required=True, help="BatDetect2 repository checkout")
+    parser.add_argument(
+        "--checkpoint",
+        type=Path,
+        help="defaults to the checkout's bundled batdetect2_uk_same.ckpt",
+    )
+    parser.add_argument("--output", type=Path, default=Path("models/batdetect2-uk-same.onnx"))
+    parser.add_argument("--opset", type=int, default=17)
+    parser.add_argument(
+        "--accept-noncommercial-license",
+        action="store_true",
+        help="acknowledge that the checkpoint is CC BY-NC 4.0",
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    if not args.accept_noncommercial_license:
+        raise SystemExit(
+            "BatDetect2's bundled model is CC BY-NC 4.0; rerun with "
+            "--accept-noncommercial-license after reviewing those terms"
+        )
+    source = args.source.resolve()
+    checkpoint = args.checkpoint or (
+        source / "src/batdetect2/models/checkpoints/batdetect2_uk_same.ckpt"
+    )
+    if not checkpoint.is_file() or not (source / "src/batdetect2").is_dir():
+        raise SystemExit("--source or --checkpoint does not contain the expected BatDetect2 files")
+    sys.path.insert(0, str(source / "src"))
+    try:
+        import numpy as np
+        import onnx
+        import onnxruntime as ort
+        import torch
+        from batdetect2.train import load_model_from_checkpoint
+    except ImportError as exc:
+        raise SystemExit(
+            "Install BatDetect2 and ONNX export dependencies in an isolated environment; "
+            "see docs/MODELS.md"
+        ) from exc
+
+    model, _ = load_model_from_checkpoint(checkpoint)
+    source_labels = list(model.class_names)
+    labels = [label.upper() for label in source_labels]
+    if labels != EXPECTED_UK_LABELS:
+        raise SystemExit(
+            "checkpoint class order differs from the locked Android contract:\n"
+            f"expected={EXPECTED_UK_LABELS}\nactual={source_labels}"
+        )
+
+    class DetectorOnly(torch.nn.Module):
+        def __init__(self, detector: torch.nn.Module) -> None:
+            super().__init__()
+            self.detector = detector
+
+        def forward(self, input: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:
+            output = self.detector(input)
+            return output.detection_probs, output.class_probs
+
+    wrapper = DetectorOnly(model.detector).eval()
+    dummy = torch.zeros((1, 1, 128, 256), dtype=torch.float32)
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    with torch.inference_mode():
+        torch.onnx.export(
+            wrapper,
+            (dummy,),
+            args.output,
+            input_names=["input"],
+            output_names=["detection_probs", "class_probs"],
+            opset_version=args.opset,
+            do_constant_folding=True,
+            dynamo=False,
+        )
+    onnx.checker.check_model(onnx.load(args.output))
+    with torch.inference_mode():
+        detection, classes = wrapper(dummy)
+        torch.manual_seed(20260818)
+        parity_input = torch.rand((1, 1, 128, 256), dtype=torch.float32)
+        reference_detection, reference_classes = wrapper(parity_input)
+    runtime = ort.InferenceSession(str(args.output), providers=["CPUExecutionProvider"])
+    converted_detection, converted_classes = runtime.run(
+        ["detection_probs", "class_probs"],
+        {runtime.get_inputs()[0].name: parity_input.numpy()},
+    )
+    detection_error = float(np.max(np.abs(reference_detection.numpy() - converted_detection)))
+    class_error = float(np.max(np.abs(reference_classes.numpy() - converted_classes)))
+    maximum_absolute_error = max(detection_error, class_error)
+    if maximum_absolute_error > 1e-4:
+        raise SystemExit(
+            f"PyTorch/ONNX parity failed: max absolute error {maximum_absolute_error:.8g}"
+        )
+    try:
+        source_revision = subprocess.run(
+            ["git", "-C", str(source), "rev-parse", "HEAD"],
+            check=True,
+            capture_output=True,
+            text=True,
+        ).stdout.strip()
+    except (OSError, subprocess.CalledProcessError):
+        source_revision = "unknown"
+    try:
+        checkpoint_identity = str(checkpoint.resolve().relative_to(source))
+    except ValueError:
+        checkpoint_identity = checkpoint.name
+    metadata = {
+        "backend": "batdetect2",
+        "source": "https://github.com/macaodha/batdetect2",
+        "source_revision": source_revision,
+        "checkpoint": checkpoint_identity,
+        "input_name": "input",
+        "input_shape": [1, 1, 128, 256],
+        "outputs": {
+            "detection_probs": list(detection.shape),
+            "class_probs": list(classes.shape),
+        },
+        "labels": labels,
+        "source_labels": source_labels,
+        "opset": args.opset,
+        "license": "CC BY-NC 4.0",
+        "commercial_use": False,
+        "onnx_bytes": args.output.stat().st_size,
+        "onnx_sha256": hashlib.sha256(args.output.read_bytes()).hexdigest(),
+        "source_runtime_parity": {
+            "fixture": "seeded random float32 tensor (seed 20260818)",
+            "detection_maximum_absolute_error": detection_error,
+            "class_maximum_absolute_error": class_error,
+            "tolerance": 1e-4,
+        },
+    }
+    args.output.with_suffix(".json").write_text(json.dumps(metadata, indent=2) + "\n")
+    print(f"wrote {args.output}")
+
+
+if __name__ == "__main__":
+    main()

scripts/fetch-upstream.sh

@@ -0,0 +1,31 @@
+#!/bin/sh
+set -eu
+
+repository_root=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+target=${1:-"$repository_root/.repro/batdetect2"}
+url='https://github.com/macaodha/batdetect2.git'
+revision='9e2697458d3b3b03c30ccd7e49ed5409c8ac330d'
+checkpoint='src/batdetect2/models/checkpoints/batdetect2_uk_same.ckpt'
+expected_sha256='52e3f329a046e434d16751005b252b4fd1b142b8b63a4edc2740aeb81f48adcf'
+
+if test ! -e "$target"; then
+  mkdir -p "$(dirname -- "$target")"
+  git clone --filter=blob:none --no-checkout "$url" "$target"
+  git -C "$target" checkout --detach "$revision"
+elif test ! -d "$target/.git"; then
+  echo "$target exists but is not a Git checkout" >&2
+  exit 1
+fi
+
+actual_revision=$(git -C "$target" rev-parse HEAD)
+test "$actual_revision" = "$revision" || {
+  echo "$target: expected revision $revision, got $actual_revision" >&2
+  exit 1
+}
+actual_sha256=$(shasum -a 256 "$target/$checkpoint" | awk '{print $1}')
+test "$actual_sha256" = "$expected_sha256" || {
+  echo "$target/$checkpoint: expected SHA-256 $expected_sha256, got $actual_sha256" >&2
+  exit 1
+}
+cmp "$target/$checkpoint" "$repository_root/upstream/batdetect2_uk_same.ckpt"
+echo "$target: pinned source revision and archived checkpoint verified"

scripts/rebuild-and-verify.sh

@@ -0,0 +1,41 @@
+#!/bin/sh
+set -eu
+
+if test "${1:-}" != '--accept-noncommercial-license'; then
+  echo 'Review CC BY-NC 4.0, then rerun with --accept-noncommercial-license' >&2
+  exit 1
+fi
+
+repository_root=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+source_checkout="$repository_root/.repro/batdetect2"
+output_dir="$repository_root/.repro/output"
+output="$output_dir/batdetect2-uk-same.onnx"
+checkpoint='src/batdetect2/models/checkpoints/batdetect2_uk_same.ckpt'
+expected_bytes='7603041'
+expected_sha256='9eddc08f1a22695ffdb1cdb52d947752d83777cd8596554f108bcf701481d340'
+
+command -v uv >/dev/null 2>&1 || {
+  echo 'uv is required: https://docs.astral.sh/uv/' >&2
+  exit 1
+}
+"$repository_root/scripts/fetch-upstream.sh" "$source_checkout"
+mkdir -p "$output_dir"
+cd "$repository_root"
+uv run --project environment --frozen --python 3.11.15 python \
+  scripts/export_batdetect2_onnx.py \
+  --source "$source_checkout" \
+  --checkpoint "$source_checkout/$checkpoint" \
+  --output "$output" \
+  --accept-noncommercial-license
+
+actual_bytes=$(wc -c < "$output" | tr -d ' ')
+actual_sha256=$(shasum -a 256 "$output" | awk '{print $1}')
+test "$actual_bytes" = "$expected_bytes" || {
+  echo "$output: expected $expected_bytes bytes, got $actual_bytes" >&2
+  exit 1
+}
+test "$actual_sha256" = "$expected_sha256" || {
+  echo "$output: expected SHA-256 $expected_sha256, got $actual_sha256" >&2
+  exit 1
+}
+echo "$output: byte-identical ONNX rebuild verified"

scripts/verify_golden.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""Create or verify the deterministic ONNX contract fixture."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+from pathlib import Path
+
+import numpy as np
+import onnxruntime as ort
+
+
+ROOT = Path(__file__).resolve().parents[1]
+SEED = 20260818
+INPUT_SHAPE = (1, 1, 128, 256)
+RTOL = 1e-5
+ATOL = 1e-6
+OUTPUTS = ("detection_probs", "class_probs")
+
+
+def sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def generated_input() -> np.ndarray:
+    return np.random.default_rng(SEED).random(INPUT_SHAPE, dtype=np.float32)
+
+
+def write_fixture(model: Path, golden: Path) -> None:
+    golden.mkdir(parents=True, exist_ok=True)
+    input_path = golden / "input.npy"
+    input_tensor = generated_input()
+    session = ort.InferenceSession(str(model), providers=["CPUExecutionProvider"])
+    outputs = session.run(list(OUTPUTS), {"input": input_tensor})
+    np.save(input_path, input_tensor, allow_pickle=False)
+    output_entries = []
+    for name, output in zip(OUTPUTS, outputs, strict=True):
+        output_path = golden / f"{name}.npy"
+        np.save(output_path, output, allow_pickle=False)
+        output_entries.append({"path": output_path.name, "name": name, "dtype": str(output.dtype), "shape": list(output.shape), "sha256": sha256(output_path)})
+    manifest = {
+        "schema_version": 1,
+        "purpose": "Deterministic model-ready tensor fixture for the ONNX runtime contract; it does not test raw-audio preprocessing.",
+        "seed": SEED,
+        "model": {"path": "batdetect2-uk-same.onnx", "sha256": sha256(model)},
+        "runtime": {"numpy": np.__version__, "onnxruntime": ort.__version__, "provider": "CPUExecutionProvider"},
+        "input": {"path": "input.npy", "name": "input", "dtype": str(input_tensor.dtype), "shape": list(input_tensor.shape), "generator": "numpy.default_rng(seed).random(dtype=float32)", "sha256": sha256(input_path)},
+        "outputs": output_entries,
+        "tolerance": {"rtol": RTOL, "atol": ATOL},
+    }
+    (golden / "manifest.json").write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
+
+
+def verify_fixture(model: Path, golden: Path) -> None:
+    manifest = json.loads((golden / "manifest.json").read_text(encoding="utf-8"))
+    if sha256(model) != manifest["model"]["sha256"]:
+        raise SystemExit("model SHA-256 does not match golden/manifest.json")
+    input_path = golden / manifest["input"]["path"]
+    if sha256(input_path) != manifest["input"]["sha256"]:
+        raise SystemExit("golden input SHA-256 mismatch")
+    input_tensor = np.load(input_path, allow_pickle=False)
+    np.testing.assert_array_equal(input_tensor, generated_input())
+    session = ort.InferenceSession(str(model), providers=["CPUExecutionProvider"])
+    actual_outputs = session.run(list(OUTPUTS), {"input": input_tensor})
+    for actual, entry in zip(actual_outputs, manifest["outputs"], strict=True):
+        expected_path = golden / entry["path"]
+        if sha256(expected_path) != entry["sha256"]:
+            raise SystemExit(f"golden output SHA-256 mismatch: {entry['path']}")
+        expected = np.load(expected_path, allow_pickle=False)
+        np.testing.assert_allclose(actual, expected, rtol=manifest["tolerance"]["rtol"], atol=manifest["tolerance"]["atol"])
+        print(f"{entry['name']} passed; max_abs_error={float(np.max(np.abs(actual - expected))):.9g}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--model", type=Path, default=ROOT / "batdetect2-uk-same.onnx")
+    parser.add_argument("--golden-dir", type=Path, default=ROOT / "golden")
+    parser.add_argument("--write", action="store_true", help="regenerate the committed fixture")
+    args = parser.parse_args()
+    if args.write:
+        write_fixture(args.model, args.golden_dir)
+    verify_fixture(args.model, args.golden_dir)
+
+
+if __name__ == "__main__":
+    main()

upstream/README.md

@@ -0,0 +1,8 @@
+# Archived upstream checkpoint
+
+`batdetect2_uk_same.ckpt` is a byte-identical copy of
+`src/batdetect2/models/checkpoints/batdetect2_uk_same.ckpt` from BatDetect2 revision
+`9e2697458d3b3b03c30ccd7e49ed5409c8ac330d`.
+
+From the repository root, run `./scripts/fetch-upstream.sh` to clone that revision and compare its
+checkpoint with this archive. The checkpoint remains subject to CC BY-NC 4.0.

upstream/batdetect2_uk_same.ckpt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:52e3f329a046e434d16751005b252b4fd1b142b8b63a4edc2740aeb81f48adcf
+size 7610085