deepmark-anni 0.1.0__tar.gz

deepmark_anni-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepMark Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

deepmark_anni-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: deepmark-anni
+Version: 0.1.0
+Summary: ANNI (Auditory Nerve Noticeability Index): how noticeable the difference between two audio signals is
+Author: DeepMark Inc.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/deepmark/anni
+Project-URL: Issues, https://github.com/deepmark/anni/issues
+Keywords: audio,quality,audibility,auditory nerve,neurogram,psychoacoustics,watermarking
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: torch>=2.4.1
+Requires-Dist: soxr>=0.4
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Dynamic: license-file
+
+# ANNI: Auditory Nerve Noticeability Index
+
+ANNI is a full-reference measure of how noticeable the difference between a reference and a test audio signal is.
+It simulates how the auditory nerve responds to each signal and compares the two responses the way an ideal observer
+would. The score is in d′ units, the standard unit of detectability: **0 means no difference, and larger values mean
+a more noticeable difference.** ANNI is built for small differences near the threshold of hearing, such as audio
+watermarks.
+
+> **Status: research prototype (v0.1).** ANNI is calibrated so that D = 1 marks a just-noticeable difference: the
+> point at which listeners in classic laboratory experiments start to detect a change. A score below 1 should
+> therefore mean the difference is hard to hear, even when comparing directly. This has not yet been confirmed by
+> listening tests on real-world audio.
+
+## Install
+
+```bash
+pip install deepmark-anni
+```
+
+Requires Python 3.9 or newer, PyTorch, NumPy and soxr.
+
+For development, install from a clone in editable mode:
+
+```bash
+git clone https://github.com/deepmark/anni.git
+cd anni
+python -m pip install -e ".[test]"
+```
+
+## Usage
+
+```python
+import soundfile as sf          # any audio loader works
+from anni import ANNI
+
+reference, sr = sf.read("original.wav")
+test, _ = sf.read("watermarked.wav")
+
+anni = ANNI()
+anni(reference, test, sr=sr)
+# e.g. {'D_peak': 1.49, 'D_med': 0.81}
+```
+
+| Score | Meaning |
+|---|---|
+| `D_peak` | how noticeable the difference is at the most noticeable 200 ms moment |
+| `D_med` | how noticeable it is at a typical moment (median over 200 ms windows) |
+
+Lower is better. To compare two processed versions, score both against the same reference. A difference between two
+scores can be expressed in dB as 20·log₁₀(D_B / D_A).
+
+## Inputs
+
+- **Mono signals** at the same sample rate. The model runs at 44.1 kHz; other rates are resampled to it.
+- **Playback level:** the reference is played at 65 dB SPL, about conversational speech (`ANNI(level=...)` changes
+  this). Both signals get the same gain, so a level change in the test signal counts as a difference.
+- **Timing:** a constant delay of up to ±10 ms is removed. If the lengths differ, the longer signal is cut.
+- **Length:** clips from 0.5 s to about 10 s, as for PESQ and ViSQOL. Memory grows with length: a 5 s pair takes about
+  1 s and 1.5 GB on a laptop CPU. On an NVIDIA GPU, use `ANNI(device="cuda")`.
+
+ANNI warns whenever it changes the inputs (resampling, cutting, removing a delay or a constant offset between them)
+and when the test signal is polarity-inverted. It also warns when the two signals correlate weakly (below 0.9), for
+example after a speech codec: the scores may then not be meaningful.
+
+## How it works
+
+1. A filter models the outer and middle ear.
+2. An auditory-nerve model turns each signal into the firing rates of 128 nerve fibres tuned from 80 Hz to 16 kHz:
+   cochlear (gammatone) filters, inner-hair-cell rectification and smoothing, and a sigmoid firing-rate curve.
+3. Two observers compare the firing rates. Each change is weighed against the natural randomness of nerve firing,
+   which is what makes loud sounds mask quieter ones. One observer looks at slow changes in firing rate (level and
+   colouration), the other at changes in how the rate fluctuates (roughness, flutter).
+4. The evidence is added up over fibres and over 200 ms windows. `D_peak` is the largest window, `D_med` the median.
+
+Four constants set the scale so that classic laboratory thresholds score about D = 1: the threshold of hearing and
+the 1 dB level difference at 1 kHz (following Taal et al. 2012), noise and tone masking (ITU-R BS.1387), and
+amplitude-modulation detection on tones (He et al. 2008) and on noise (O'Connor et al. 2011).
+
+A function-by-function walk-through of the code is in [docs.md](https://github.com/deepmark/anni/blob/main/docs.md).
+For a comparison with PESQ and ViSQOL on controlled changes, with audio, see
+[examples/](https://github.com/deepmark/anni/tree/main/examples).
+
+## Evaluation
+
+On [ODAQ](https://zenodo.org/records/10405774), an open dataset of music, film sound and speech over music rated by 26
+listeners (210 versions of 30 excerpts; Torcoli et al. 2024), `D_med` orders the versions like the listeners with a
+Spearman correlation of 0.85 (95 % interval 0.79–0.89). That is on par with Zimtohrli (0.83) and above ViSQOL (0.65 in
+audio mode) and PESQ (0.42). On degraded speech, in the TCD-VoIP dataset (Harte et al. 2015; packet loss, clipping,
+echo, competing speakers and noise, rated by 24 listeners), PESQ and ViSQOL follow listeners better.
+
+## Limitations
+
+- It compares the signals moment by moment, so it does not suit audio whose timing or pitch has changed
+  (time-stretching, pitch-shifting) or that went through a speech codec.
+- It doesn't see energy above 16 kHz or below 80 Hz, very fast fluctuations or fine timing structure.
+- Mono only, normal hearing.
+
+## Credits and licence
+
+ANNI is developed by DeepMark Inc. and released under the
+[MIT License](https://github.com/deepmark/anni/blob/main/LICENSE).
+
+The auditory-nerve model is adapted from Mark R. Saddler's
+[auditory_machine_learning](https://github.com/msaddler/auditory_machine_learning). If you use ANNI, please also cite:
+
+- Saddler, M. R., & McDermott, J. H. (2024). Models optimized for real-world tasks reveal the task-dependent necessity
+  of precise temporal coding in hearing. *Nature Communications*.
+  [doi:10.1038/s41467-024-54700-5](https://doi.org/10.1038/s41467-024-54700-5)
+
+Listening-test data:
+
+- Torcoli, M., Wu, C.-W., Dick, S., Williams, P. A., Halimeh, M. M., Wolcott, W., & Habets, E. A. P. (2024). ODAQ: Open
+  Dataset of Audio Quality. *Proc. IEEE ICASSP*. [arXiv:2401.00197](https://arxiv.org/abs/2401.00197)
+- Harte, N., Gillen, E., & Hines, A. (2015). TCD-VoIP, a research database of degraded speech for assessing quality in
+  VoIP applications. *Proc. QoMEX*.
+
+Calibration references:
+
+- Taal, C. H., Hendriks, R. C., & Heusdens, R. (2012). A low-complexity spectro-temporal distortion measure for audio
+  processing applications. *IEEE Transactions on Audio, Speech, and Language Processing*, 20(5).
+  [doi:10.1109/TASL.2012.2184753](https://doi.org/10.1109/TASL.2012.2184753)
+- ITU-R BS.1387: Method for objective measurements of perceived audio quality (PEAQ).
+- He, N., Mills, J. H., Ahlstrom, J. B., & Dubno, J. R. (2008). Age-related differences in the temporal modulation
+  transfer function with pure-tone carriers. *The Journal of the Acoustical Society of America*, 124(6), 3841–3849.
+  [doi:10.1121/1.2998779](https://doi.org/10.1121/1.2998779)
+- O'Connor, K. N., Johnson, J. S., Niwa, M., Noriega, N. C., Marshall, E. A., & Sutter, M. L. (2011). Amplitude
+  modulation detection as a function of modulation frequency and stimulus duration: comparisons between macaques and
+  humans. *Hearing Research*, 277, 37–43. [doi:10.1016/j.heares.2011.03.014](https://doi.org/10.1016/j.heares.2011.03.014)

deepmark_anni-0.1.0/README.md

@@ -0,0 +1,128 @@
+# ANNI: Auditory Nerve Noticeability Index
+
+ANNI is a full-reference measure of how noticeable the difference between a reference and a test audio signal is.
+It simulates how the auditory nerve responds to each signal and compares the two responses the way an ideal observer
+would. The score is in d′ units, the standard unit of detectability: **0 means no difference, and larger values mean
+a more noticeable difference.** ANNI is built for small differences near the threshold of hearing, such as audio
+watermarks.
+
+> **Status: research prototype (v0.1).** ANNI is calibrated so that D = 1 marks a just-noticeable difference: the
+> point at which listeners in classic laboratory experiments start to detect a change. A score below 1 should
+> therefore mean the difference is hard to hear, even when comparing directly. This has not yet been confirmed by
+> listening tests on real-world audio.
+
+## Install
+
+```bash
+pip install deepmark-anni
+```
+
+Requires Python 3.9 or newer, PyTorch, NumPy and soxr.
+
+For development, install from a clone in editable mode:
+
+```bash
+git clone https://github.com/deepmark/anni.git
+cd anni
+python -m pip install -e ".[test]"
+```
+
+## Usage
+
+```python
+import soundfile as sf          # any audio loader works
+from anni import ANNI
+
+reference, sr = sf.read("original.wav")
+test, _ = sf.read("watermarked.wav")
+
+anni = ANNI()
+anni(reference, test, sr=sr)
+# e.g. {'D_peak': 1.49, 'D_med': 0.81}
+```
+
+| Score | Meaning |
+|---|---|
+| `D_peak` | how noticeable the difference is at the most noticeable 200 ms moment |
+| `D_med` | how noticeable it is at a typical moment (median over 200 ms windows) |
+
+Lower is better. To compare two processed versions, score both against the same reference. A difference between two
+scores can be expressed in dB as 20·log₁₀(D_B / D_A).
+
+## Inputs
+
+- **Mono signals** at the same sample rate. The model runs at 44.1 kHz; other rates are resampled to it.
+- **Playback level:** the reference is played at 65 dB SPL, about conversational speech (`ANNI(level=...)` changes
+  this). Both signals get the same gain, so a level change in the test signal counts as a difference.
+- **Timing:** a constant delay of up to ±10 ms is removed. If the lengths differ, the longer signal is cut.
+- **Length:** clips from 0.5 s to about 10 s, as for PESQ and ViSQOL. Memory grows with length: a 5 s pair takes about
+  1 s and 1.5 GB on a laptop CPU. On an NVIDIA GPU, use `ANNI(device="cuda")`.
+
+ANNI warns whenever it changes the inputs (resampling, cutting, removing a delay or a constant offset between them)
+and when the test signal is polarity-inverted. It also warns when the two signals correlate weakly (below 0.9), for
+example after a speech codec: the scores may then not be meaningful.
+
+## How it works
+
+1. A filter models the outer and middle ear.
+2. An auditory-nerve model turns each signal into the firing rates of 128 nerve fibres tuned from 80 Hz to 16 kHz:
+   cochlear (gammatone) filters, inner-hair-cell rectification and smoothing, and a sigmoid firing-rate curve.
+3. Two observers compare the firing rates. Each change is weighed against the natural randomness of nerve firing,
+   which is what makes loud sounds mask quieter ones. One observer looks at slow changes in firing rate (level and
+   colouration), the other at changes in how the rate fluctuates (roughness, flutter).
+4. The evidence is added up over fibres and over 200 ms windows. `D_peak` is the largest window, `D_med` the median.
+
+Four constants set the scale so that classic laboratory thresholds score about D = 1: the threshold of hearing and
+the 1 dB level difference at 1 kHz (following Taal et al. 2012), noise and tone masking (ITU-R BS.1387), and
+amplitude-modulation detection on tones (He et al. 2008) and on noise (O'Connor et al. 2011).
+
+A function-by-function walk-through of the code is in [docs.md](https://github.com/deepmark/anni/blob/main/docs.md).
+For a comparison with PESQ and ViSQOL on controlled changes, with audio, see
+[examples/](https://github.com/deepmark/anni/tree/main/examples).
+
+## Evaluation
+
+On [ODAQ](https://zenodo.org/records/10405774), an open dataset of music, film sound and speech over music rated by 26
+listeners (210 versions of 30 excerpts; Torcoli et al. 2024), `D_med` orders the versions like the listeners with a
+Spearman correlation of 0.85 (95 % interval 0.79–0.89). That is on par with Zimtohrli (0.83) and above ViSQOL (0.65 in
+audio mode) and PESQ (0.42). On degraded speech, in the TCD-VoIP dataset (Harte et al. 2015; packet loss, clipping,
+echo, competing speakers and noise, rated by 24 listeners), PESQ and ViSQOL follow listeners better.
+
+## Limitations
+
+- It compares the signals moment by moment, so it does not suit audio whose timing or pitch has changed
+  (time-stretching, pitch-shifting) or that went through a speech codec.
+- It doesn't see energy above 16 kHz or below 80 Hz, very fast fluctuations or fine timing structure.
+- Mono only, normal hearing.
+
+## Credits and licence
+
+ANNI is developed by DeepMark Inc. and released under the
+[MIT License](https://github.com/deepmark/anni/blob/main/LICENSE).
+
+The auditory-nerve model is adapted from Mark R. Saddler's
+[auditory_machine_learning](https://github.com/msaddler/auditory_machine_learning). If you use ANNI, please also cite:
+
+- Saddler, M. R., & McDermott, J. H. (2024). Models optimized for real-world tasks reveal the task-dependent necessity
+  of precise temporal coding in hearing. *Nature Communications*.
+  [doi:10.1038/s41467-024-54700-5](https://doi.org/10.1038/s41467-024-54700-5)
+
+Listening-test data:
+
+- Torcoli, M., Wu, C.-W., Dick, S., Williams, P. A., Halimeh, M. M., Wolcott, W., & Habets, E. A. P. (2024). ODAQ: Open
+  Dataset of Audio Quality. *Proc. IEEE ICASSP*. [arXiv:2401.00197](https://arxiv.org/abs/2401.00197)
+- Harte, N., Gillen, E., & Hines, A. (2015). TCD-VoIP, a research database of degraded speech for assessing quality in
+  VoIP applications. *Proc. QoMEX*.
+
+Calibration references:
+
+- Taal, C. H., Hendriks, R. C., & Heusdens, R. (2012). A low-complexity spectro-temporal distortion measure for audio
+  processing applications. *IEEE Transactions on Audio, Speech, and Language Processing*, 20(5).
+  [doi:10.1109/TASL.2012.2184753](https://doi.org/10.1109/TASL.2012.2184753)
+- ITU-R BS.1387: Method for objective measurements of perceived audio quality (PEAQ).
+- He, N., Mills, J. H., Ahlstrom, J. B., & Dubno, J. R. (2008). Age-related differences in the temporal modulation
+  transfer function with pure-tone carriers. *The Journal of the Acoustical Society of America*, 124(6), 3841–3849.
+  [doi:10.1121/1.2998779](https://doi.org/10.1121/1.2998779)
+- O'Connor, K. N., Johnson, J. S., Niwa, M., Noriega, N. C., Marshall, E. A., & Sutter, M. L. (2011). Amplitude
+  modulation detection as a function of modulation frequency and stimulus duration: comparisons between macaques and
+  humans. *Hearing Research*, 277, 37–43. [doi:10.1016/j.heares.2011.03.014](https://doi.org/10.1016/j.heares.2011.03.014)

deepmark_anni-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "deepmark-anni"
+dynamic = ["version"]
+description = "ANNI (Auditory Nerve Noticeability Index): how noticeable the difference between two audio signals is"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "DeepMark Inc." }]
+keywords = ["audio", "quality", "audibility", "auditory nerve", "neurogram", "psychoacoustics", "watermarking"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia :: Sound/Audio",
+    "Topic :: Scientific/Engineering",
+]
+
+dependencies = [
+    "numpy>=1.21",
+    "torch>=2.4.1",
+    "soxr>=0.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/deepmark/anni"
+Issues = "https://github.com/deepmark/anni/issues"
+
+[project.optional-dependencies]
+test = ["pytest>=7.0"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.dynamic]
+version = { attr = "anni.__version__" }

deepmark_anni-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

deepmark_anni-0.1.0/src/anni/__init__.py

@@ -0,0 +1,5 @@
+"""ANNI: Auditory Nerve Noticeability Index."""
+from .measure import ANNI
+
+__all__ = ["ANNI"]
+__version__ = "0.1.0"

deepmark_anni-0.1.0/src/anni/_auditory_model.py

@@ -0,0 +1,111 @@
+"""Adapted from https://github.com/msaddler/auditory_machine_learning, under the following licence:
+
+MIT License
+
+Copyright (c) 2026 Mark R. Saddler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""
+import math
+
+import numpy as np
+import soxr
+import torch
+
+
+def freq2erb(freq):
+    """Frequency in Hz to ERB-number."""
+    return 9.2645 * np.sign(freq) * np.log(1 + np.abs(freq) * 0.00437)
+
+
+def erb2freq(erb):
+    """ERB-number to frequency in Hz."""
+    return (1.0 / 0.00437) * np.sign(erb) * (np.exp(np.abs(erb) / 9.2645) - 1)
+
+
+def erbspace(start, stop, num):
+    """num frequencies (Hz) evenly spaced on the ERB-number scale."""
+    return erb2freq(np.linspace(freq2erb(start), freq2erb(stop), num=num))
+
+
+def gammatone_filterbank_fir(sr, cfs, fir_dur=0.05, order=4, bw_mult=1.0):
+    """Impulse responses of a gammatone filterbank, shape (n_filters, int(sr * fir_dur))."""
+    cfs = np.array(cfs).reshape([-1])
+    bw = 2 * np.pi * bw_mult * (24.7 + cfs / 9.265)
+    wc = 2 * np.pi * cfs
+    t = np.arange(0, fir_dur, 1 / sr)
+    a = 2 / math.factorial(order - 1) / np.abs(1 / bw ** order + 1 / (bw + 2j * wc) ** order) / sr
+    return a[:, None] * t ** (order - 1) * np.exp(-bw[:, None] * t[None, :]) * np.cos(wc[:, None] * t[None, :])
+
+
+def ihc_lowpass_filter_fir(sr, fir_dur, cutoff=3e3, order=7):
+    """Impulse response of the inner-hair-cell low-pass filter (from bez2018model/model_IHC_BEZ2018.c)."""
+    sr_bez2018 = 100e3
+
+    def resample(x):
+        return soxr.resample(x, in_rate=sr_bez2018, out_rate=sr, quality="VHQ")
+
+    n_taps = int(sr_bez2018 * fir_dur)
+    while len(resample(np.zeros(n_taps))) % 2 == 0:
+        n_taps = n_taps + 1
+    impulse = np.zeros(n_taps)
+    impulse[0] = 1
+    fir = np.zeros(n_taps)
+    ihc = np.zeros(order + 1)
+    ihcl = np.zeros(order + 1)
+    c1LP = (sr_bez2018 - 2 * np.pi * cutoff) / (sr_bez2018 + 2 * np.pi * cutoff)
+    c2LP = (np.pi * cutoff) / (sr_bez2018 + 2 * np.pi * cutoff)
+    for n in range(n_taps):
+        ihc[0] = impulse[n]
+        for i in range(order):
+            ihc[i + 1] = (c1LP * ihcl[i + 1]) + c2LP * (ihc[i] + ihcl[i])
+        ihcl = ihc
+        fir[n] = ihc[order]
+    fir = fir * np.hanning(n_taps)
+    fir = resample(fir)
+    fir[fir < 0] = 0
+    return fir / fir.sum()
+
+
+class GradientStableSigmoid(torch.autograd.Function):
+    """Sigmoid with a NaN-free gradient (avoids overflow in the rate-level function)."""
+
+    @staticmethod
+    def forward(ctx, x, k, x0):
+        ctx.save_for_backward(x, k, x0)
+        return 1.0 / (1.0 + torch.exp(-k * (x - x0)))
+
+    @staticmethod
+    def backward(ctx, grad_output):
+        x, k, x0 = ctx.saved_tensors
+        grad = k * torch.exp(-k * (x - x0))
+        grad = grad / (torch.exp(-k * (x - x0)) + 1.0) ** 2
+        grad = torch.nan_to_num(grad, nan=0.0, posinf=None, neginf=None)
+        return grad_output * grad, None, None
+
+
+def rate_level(x, rate_spont=0.0, rate_max=250.0, threshold=0.0, dynamic_range=80.0, dynamic_range_interval=0.95):
+    """Sigmoid rate-level function: half-wave rectified, low-passed subbands (Pa) -> firing rate (spikes/s)."""
+    y_threshold = (1 - dynamic_range_interval) / 2
+    k = math.log((1 / y_threshold) - 1) / (dynamic_range / 2)
+    x0 = threshold - (math.log((1 / y_threshold) - 1) / (-k))
+    k_t = torch.tensor(k, dtype=x.dtype, device=x.device)
+    x0_t = torch.tensor(x0, dtype=x.dtype, device=x.device)
+    s = GradientStableSigmoid.apply(20 * torch.log10(x / 20e-6), k_t, x0_t)
+    return rate_spont + (rate_max - rate_spont) * s

deepmark_anni-0.1.0/src/anni/_core.py

@@ -0,0 +1,287 @@
+"""ANNI's computation, in PyTorch.
+
+Steps: presentation level (one gain for both signals) -> alignment (constant delay) -> outer/middle-ear filter ->
+auditory-nerve model (polarity-averaged, delay-compensated) -> 1.9 ms bins -> pattern and texture observers ->
+200 ms windows -> D_peak, D_med.
+"""
+import cmath
+import math
+from functools import lru_cache
+
+import torch
+
+from . import _auditory_model
+
+SR = 44100                     # the model's input rate
+FS_N = 11025                   # nerve output rate (stride 4)
+P_REF = 20e-6                  # Pa at 0 dB SPL
+DT = torch.float32
+# calibration constants: internal-noise floor r0 (spikes/s), pattern gain kP, texture gain kS, texture floor e0
+CONSTANTS = dict(r0=66.56840796512564, kP=7.440094426024921, kS=0.05248517778798395, e0=2.3703160271327422e-05)
+
+
+def next_fast_len(n):
+    """Smallest 2^a 3^b 5^c >= n."""
+    best = 1 << max(0, (n - 1).bit_length())
+    p5 = 1
+    while p5 < best:
+        p35 = p5
+        while p35 < best:
+            q = p35
+            while q < n:
+                q *= 2
+            best = min(best, q)
+            p35 *= 3
+        p5 *= 5
+    return best
+
+
+# ------------------------------------------------------------------------------------------------ presentation
+
+def tq(f):
+    """Terhardt threshold in quiet (dB SPL)."""
+    f = torch.clamp(torch.as_tensor(f, dtype=DT), min=1.0) / 1000.0
+    return 3.64 * f ** -0.8 - 6.5 * torch.exp(-0.6 * (f - 3.3) ** 2) + 1e-3 * f ** 4
+
+
+def ear_filter(x, pad=8192):
+    """Zero-phase outer/middle-ear filter: gain clip(-(Tq(f) - Tq(1 kHz)), -100, 20) dB, H(0) = 0; x [..., T]."""
+    T = x.shape[-1]
+    n = next_fast_len(T + 2 * pad)
+    xp = torch.nn.functional.pad(x, (pad, n - T - pad))
+    f = torch.fft.rfftfreq(n, 1.0 / SR, dtype=DT)
+    H = 10 ** (torch.clamp(-(tq(f) - tq(1000.0)), -100.0, 20.0) / 20.0)
+    H[0] = 0.0
+    return torch.fft.irfft(torch.fft.rfft(xp, dim=-1) * H.to(device=x.device, dtype=x.dtype), n, dim=-1)[..., pad:pad + T]
+
+
+def active_rms(x, frame=0.02, rel_db=40.0):
+    """RMS over 20 ms frames whose power is within rel_db of the 99th-percentile frame power (mean removed)."""
+    x = x - x.mean()
+    L = int(SR * frame)
+    n = x.shape[-1] // L
+    e = (x[:n * L].reshape(n, L) ** 2).mean(1)
+    thr = torch.quantile(e, 0.99) * 10 ** (-rel_db / 10)
+    return torch.sqrt(e[e > thr].mean())
+
+
+def pa_gain(x, level=65.0):
+    """Pa per digital unit that puts x's active level at `level` dB SPL."""
+    return P_REF * 10 ** (level / 20) / active_rms(x)
+
+
+def shift(y, tau, pad=4096):
+    """y(t + tau) by an FFT phase ramp (zero-padded)."""
+    T = y.shape[-1]
+    N = next_fast_len(T + 2 * pad)
+    yp = torch.nn.functional.pad(y, (pad, N - T - pad))
+    f = torch.fft.rfftfreq(N, dtype=DT, device=y.device)
+    ramp = torch.exp(2j * math.pi * f * torch.as_tensor(tau, dtype=DT))
+    return torch.fft.irfft(torch.fft.rfft(yp) * ramp, N)[..., pad:pad + T]
+
+
+def align(x, y, max_lag=441, min_shift=0.05):
+    """Removes a constant delay of up to max_lag samples: integer lag by FFT cross-correlation (largest |c|),
+    parabolic sub-sample refinement, phase-ramp shift of y. x and y have equal length. Returns (y, tau, rho), tau
+    being the shift applied in samples (0.0 when the delay found is below min_shift and y is left as it is)."""
+    n = next_fast_len(2 * x.shape[-1])
+    with torch.no_grad():
+        c = torch.fft.irfft(torch.conj(torch.fft.rfft(x, n)) * torch.fft.rfft(y, n), n)
+        lags = torch.cat([torch.arange(0, max_lag + 1), torch.arange(-max_lag, 0)])
+        cv = c[lags % n]
+        i = int(torch.argmax(cv.abs()))
+        l0 = int(lags[i])
+        sgn = 1.0 if float(cv[i]) >= 0 else -1.0
+        cm, c0, cp = sgn * float(c[(l0 - 1) % n]), sgn * float(cv[i]), sgn * float(c[(l0 + 1) % n])
+        den = cm - 2 * c0 + cp
+        tau = l0 + (0.5 * (cm - cp) / den if den != 0 else 0.0)
+        rho = float(cv[i]) / math.sqrt(float((x ** 2).sum() * (y ** 2).sum()) + 1e-30)
+    if abs(tau) < min_shift:
+        return y, 0.0, rho
+    return shift(y, tau), float(tau), rho
+
+
+# ------------------------------------------------------------------------------------------------ auditory nerve
+
+def analytic(g):
+    """Analytic signal along the last axis."""
+    N = g.shape[-1]
+    h = torch.zeros(N, dtype=DT)
+    if N % 2 == 0:
+        h[0] = h[N // 2] = 1
+        h[1:N // 2] = 2
+    else:
+        h[0] = 1
+        h[1:(N + 1) // 2] = 2
+    return torch.fft.ifft(torch.fft.fft(g, dim=-1) * h, dim=-1)
+
+
+class Nerve:
+    """Saddler's simple auditory-nerve model in a full-band configuration: 44.1 kHz in, 128 ERB-spaced fibres from
+    80 Hz to 16 kHz, 4th-order gammatone filters (1 ERB), IHC low-pass (nominal 3 kHz, order 7), sigmoid rate-level
+    function (0 dB SPL threshold, 80 dB range, max 250 spikes/s), 11025 Hz output. FIR filtering by FFT."""
+
+    def __init__(self, device="cpu"):
+        self.device = torch.device(device)
+        cfs = _auditory_model.erbspace(80.0, 16000.0, 128)
+        g = torch.as_tensor(_auditory_model.gammatone_filterbank_fir(SR, cfs, fir_dur=0.05, bw_mult=1.0), dtype=DT)
+        lp = torch.as_tensor(_auditory_model.ihc_lowpass_filter_fir(SR, 0.05, cutoff=3000.0, order=7), dtype=DT)
+        self.cfs = torch.as_tensor(cfs, dtype=DT)
+        self.g, self.lp = g.to(device), lp.to(device)
+        self.stride = SR // FS_N
+        tau_g = torch.argmax(analytic(g).abs(), dim=-1).to(DT) / SR          # gammatone envelope peak
+        tau_l = (torch.arange(len(lp), dtype=DT) * lp).sum() / lp.sum() / SR  # low-pass centroid
+        self.delays = torch.round((tau_g + tau_l) * FS_N).long()              # per-fibre delay, output samples
+
+    def forward(self, x):
+        """x [B, T] (Pa) -> firing rates [B, 128, ceil(T / 4)] (spikes/s)."""
+        T = x.shape[-1]
+        n1 = next_fast_len(T + self.g.shape[-1] - 1)
+        n2 = next_fast_len(T + self.lp.shape[-1] - 1)
+        G = torch.fft.rfft(self.g, n=n1)
+        LP = torch.fft.rfft(self.lp, n=n2)
+        out = []
+        for xb in x:                                       # one row at a time keeps the memory down
+            y = torch.fft.irfft(torch.fft.rfft(xb, n=n1)[None, :] * G, n=n1)[:, :T]
+            y = torch.relu(y)
+            y = torch.fft.irfft(torch.fft.rfft(y, n=n2) * LP, n=n2)[:, :T:self.stride]
+            out.append(torch.relu(y))
+        return _auditory_model.rate_level(torch.stack(out))
+
+    def compensate(self, r):
+        """Removes each fibre's own delay, so all fibres line up in time."""
+        cols = []
+        for c in range(r.shape[-2]):
+            s = int(self.delays[c])
+            cols.append(torch.nn.functional.pad(r[..., c, s:], (0, s)))
+        return torch.stack(cols, dim=-2)
+
+    def rates(self, p):
+        """p [B, T] pressure (Pa) at 44.1 kHz -> ear filter -> polarity-averaged, delay-compensated rates, returned
+        on the CPU for the observers."""
+        x = ear_filter(p.to(device=self.device, dtype=DT))
+        r = self.forward(torch.cat([x, -x]))
+        r = 0.5 * (r[:len(x)] + r[len(x):])
+        return self.compensate(r).cpu()
+
+
+# ------------------------------------------------------------------------------------------------ observers
+
+def _bilinear(zs, ps, k, fs):
+    fs2 = 2.0 * fs
+    zd = [(fs2 + z) / (fs2 - z) for z in zs]
+    pd = [(fs2 + p) / (fs2 - p) for p in ps]
+    zd += [-1.0] * (len(ps) - len(zs))
+    num = 1.0
+    for z in zs:
+        num *= (fs2 - z)
+    den = 1.0
+    for p in ps:
+        den *= (fs2 - p)
+    return zd, pd, k * (num / den).real
+
+
+def _poly2(roots):
+    r1, r2 = roots
+    return [1.0, (-(r1 + r2)).real, (r1 * r2).real]
+
+
+def butter2(kind, wn, fs):
+    """One second-order Butterworth section (b, a), as scipy.signal.butter designs it: 'lowpass' (order 2, wn Hz) or
+    'bandpass' (order 1, wn = (lo, hi) Hz)."""
+    fsn = 2.0
+    warp = lambda w: 2 * fsn * math.tan(math.pi * (2 * w / fs) / fsn)        # noqa: E731
+    if kind == "lowpass":
+        p_proto = [complex(-math.sqrt(0.5), math.sqrt(0.5)), complex(-math.sqrt(0.5), -math.sqrt(0.5))]
+        wo = warp(wn)
+        zs, ps, k = [], [wo * p for p in p_proto], wo ** 2
+    elif kind == "bandpass":
+        lo, hi = warp(wn[0]), warp(wn[1])
+        bw, wo = hi - lo, math.sqrt(lo * hi)
+        disc = cmath.sqrt((-bw / 2) ** 2 - wo ** 2)
+        zs, ps, k = [0.0], [-bw / 2 + disc, -bw / 2 - disc], bw
+    else:
+        raise ValueError(kind)
+    zd, pd, kd = _bilinear(zs, ps, k, fsn)
+    return [kd * c for c in _poly2(zd)], _poly2(pd)
+
+
+@lru_cache(maxsize=64)
+def _impulse(sec, n):
+    """Impulse response (n samples) of one biquad (b0, b1, b2, a0, a1, a2), from rest."""
+    b0, b1, b2, _, a1, a2 = sec
+    h = [0.0] * n
+    y1 = y2 = 0.0
+    for i in range(n):
+        y0 = (b0 if i == 0 else b1 if i == 1 else b2 if i == 2 else 0.0) - a1 * y1 - a2 * y2
+        h[i] = y0
+        y2, y1 = y1, y0
+    return tuple(h)
+
+
+class Observer:
+    """Compares two neurograms: the pattern observer (rate changes slower than ~3 Hz) and the texture observer
+    (changes in rate fluctuation, octave bands 4-128 Hz), evidence in d'^2 units pooled over fibres and 200 ms."""
+
+    def __init__(self, cfs, bin_n=21, bands=(4., 8., 16., 32., 64., 128.), win_s=0.1995, pad_s=1.0,
+                 trim_s=(0.1, 0.05)):
+        self.bin_n, self.dt = bin_n, bin_n / FS_N
+        fsb = 1.0 / self.dt
+        secs = [butter2("lowpass", 2.0 * math.sqrt(2.0), fsb)]
+        secs += [butter2("bandpass", (fc / math.sqrt(2), fc * math.sqrt(2)), fsb) for fc in bands]
+        self.secs = [tuple(b) + tuple(a) for b, a in secs]
+        fk = torch.tensor(bands, dtype=DT)
+        self.W = int(round(win_s / self.dt))
+        self.padc = int(round(pad_s / self.dt))
+        cfs = torch.as_tensor(cfs, dtype=DT)
+        self.dz = float(torch.diff(torch.as_tensor(_auditory_model.freq2erb(cfs.numpy()))).mean())  # fibre spacing
+        self.mask = (fk[:, None] <= cfs[None, :] / 4.0).to(DT)      # a band counts only up to CF / 4
+        self.trim_s = trim_s
+
+    def bin(self, r):
+        nb = r.shape[-1] // self.bin_n
+        return r[..., :nb * self.bin_n].reshape(*r.shape[:-1], nb, self.bin_n).mean(-1)
+
+    def split(self, a):
+        """Causal filter bank along the bin axis (start-padded with the first bin): [1 + K, ..., nb]."""
+        ap = torch.cat([a[..., :1].expand(*a.shape[:-1], self.padc), a], -1)
+        L = ap.shape[-1]
+        n = next_fast_len(2 * L)
+        A = torch.fft.rfft(ap, n)
+        out = []
+        for sec in self.secs:
+            h = torch.tensor(_impulse(sec, L), dtype=a.dtype, device=a.device)
+            out.append(torch.fft.irfft(A * torch.fft.rfft(h, n), n)[..., :L][..., self.padc:])
+        return torch.stack(out)
+
+    def movmean(self, a):
+        W = self.W
+        c = torch.cumsum(torch.nn.functional.pad(a, (1, 0)), -1)
+        return (c[..., W:] - c[..., :-W]) / W
+
+    def valid(self, npos, nb):
+        """Windows clear of the trimmed start and end of the signal."""
+        t0b, t1b = math.ceil(self.trim_s[0] / self.dt), math.ceil(self.trim_s[1] / self.dt)
+        pos = torch.arange(npos)
+        return (pos >= t0b) & (pos + self.W <= nb - t1b)
+
+    def window_d2(self, Rx, Ry, p):
+        """Total evidence (d'^2) in each 200 ms window: pattern + texture."""
+        rbar = 0.5 * (Rx + Ry)
+        db, xb, yb = self.split(Ry - Rx), self.split(Rx), self.split(Ry)
+        d2P = p["kP"] * self.dz * self.dt * db[0] ** 2 / (rbar + p["r0"])
+        P_w = self.movmean(d2P.sum(0)) * self.W
+        mx, my = self.movmean(Rx), self.movmean(Ry)
+        ex = self.movmean(xb[1:] ** 2) / (mx + p["r0"]) ** 2
+        ey = self.movmean(yb[1:] ** 2) / (my + p["r0"]) ** 2
+        lr2 = p["kS"] * self.dz * torch.log((ey + p["e0"]) / (ex + p["e0"])) ** 2 * self.mask[:, :, None]
+        return P_w + lr2.sum((0, 1))
+
+
+def scores(ob, Rx, Ry, p=CONSTANTS):
+    """D_peak (most noticeable 200 ms window) and D_med (median window) as tensors."""
+    bx, by = ob.bin(Rx), ob.bin(Ry)
+    tot = ob.window_d2(bx, by, p)
+    ok = ob.valid(len(tot), bx.shape[-1])
+    d2 = tot[ok]
+    return dict(D_peak=torch.sqrt(d2.max()), D_med=torch.median(torch.sqrt(torch.clamp(d2, min=0))))

deepmark_anni-0.1.0/src/anni/measure.py

@@ -0,0 +1,103 @@
+"""The ANNI measure."""
+import warnings
+
+import numpy as np
+import soxr
+import torch
+
+from . import _core
+
+MIN_SECONDS = 0.5
+
+
+class ANNI:
+    """Auditory Nerve Noticeability Index: how noticeable the difference between a reference and a test signal
+    is, in d' units (0 = no difference; larger = more noticeable).
+
+    Args:
+        level: playback level of the reference, in dB SPL of its active (non-silent) parts. Default 65 dB SPL,
+            about conversational speech.
+        device: "cpu" (default) or "cuda".
+
+    Example:
+        >>> anni = ANNI()
+        >>> anni(reference, test, sr=44100)
+        {'D_peak': 1.49, 'D_med': 0.81}
+    """
+
+    def __init__(self, level=65.0, device="cpu"):
+        self.level = float(level)
+        if torch.device(device).type not in ("cpu", "cuda"):
+            raise ValueError(f'device must be "cpu" or "cuda"; got {device!r}')
+        self._nerve = _core.Nerve(device=device)
+        self._observer = _core.Observer(self._nerve.cfs)
+
+    def __call__(self, reference, test, sr):
+        """Scores `test` against `reference`.
+
+        Args:
+            reference, test: mono signals (1-D NumPy arrays or torch tensors) at sample rate `sr`.
+            sr: sample rate in Hz. The model runs at 44.1 kHz; other rates are resampled, with a warning.
+
+        Returns:
+            {"D_peak": float, "D_med": float}: D_peak is the most noticeable 200 ms moment, D_med the typical one.
+        """
+        with torch.no_grad():
+            px, py = self._prepare(reference, test, sr)
+            d = self._forward(px, py)
+        return {k: float(v) for k, v in d.items()}
+
+    def _prepare(self, reference, test, sr):
+        """Inputs -> pressure signals (Pa) at 44.1 kHz: offsets removed, equal length, resampling, constant-delay
+        alignment, one playback gain for both (so a level change in `test` is kept and scored). Warns about every
+        change it makes to the inputs."""
+        if not sr > 0:
+            raise ValueError(f"sr must be a positive sample rate; got {sr}")
+        x, y = self._check(reference, "reference"), self._check(test, "test")
+        x, y, dc = x - x.mean(), y - y.mean(), y.mean() - x.mean()
+        if len(x) != len(y):
+            warnings.warn(f"reference and test differ in length ({len(x)} vs {len(y)} samples); the longer one is "
+                          "cut to the shorter.", stacklevel=3)
+            m = min(len(x), len(y))
+            x, y = x[:m], y[:m]
+        if len(x) < MIN_SECONDS * sr:
+            raise ValueError(f"signals must be at least {MIN_SECONDS} s long")
+        if np.ptp(x) == 0.0:
+            raise ValueError("reference is silent (or constant)")
+        if abs(dc) > 1e-3 * np.sqrt(np.mean(x ** 2)):
+            warnings.warn(f"test has a constant (DC) offset of {dc:+.3g} relative to reference; removed, as it is "
+                          "inaudible.", stacklevel=3)
+        if sr != _core.SR:
+            warnings.warn(f"resampling from {sr:g} Hz to {_core.SR} Hz, the model's input rate.", stacklevel=3)
+            x, y = (soxr.resample(s, sr, _core.SR, quality="VHQ") for s in (x, y))
+        x, y = torch.as_tensor(x, dtype=_core.DT), torch.as_tensor(y, dtype=_core.DT)
+        y, tau, rho = _core.align(x, y)
+        shifted = f"test was shifted by {tau:+.2f} samples ({1000 * tau / _core.SR:+.3f} ms) to line up with reference"
+        if abs(rho) < 0.9:                    # the delay and polarity estimates are unreliable too: one warning only
+            warnings.warn(f"reference and test correlate weakly (|rho| = {abs(rho):.2f} < 0.9) after alignment: they "
+                          "may be too different for a sample-by-sample comparison, so the scores may not be "
+                          "meaningful." + (f" Also, {shifted}." if tau != 0.0 else ""), stacklevel=3)
+        else:
+            if tau != 0.0:
+                warnings.warn(shifted + ".", stacklevel=3)
+            if rho < 0:
+                warnings.warn("test is polarity-inverted relative to reference.", stacklevel=3)
+        g = _core.pa_gain(x, self.level)
+        return g * x, g * y
+
+    def _forward(self, px, py):
+        """Pressure signals -> {"D_peak", "D_med"} tensors."""
+        R = self._nerve.rates(torch.stack([px, py]))
+        return _core.scores(self._observer, R[0], R[1])
+
+    @staticmethod
+    def _check(s, name):
+        """A mono, finite NumPy array (float64 for the input steps; the model itself runs in 32-bit)."""
+        if isinstance(s, torch.Tensor):
+            s = s.detach().cpu().numpy()
+        s = np.asarray(s, dtype=np.float64)
+        if s.ndim != 1:
+            raise ValueError(f"{name} must be mono (1-D); got shape {s.shape}")
+        if not np.all(np.isfinite(s)):
+            raise ValueError(f"{name} contains NaN or infinite values")
+        return s

deepmark_anni-0.1.0/src/deepmark_anni.egg-info/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: deepmark-anni
+Version: 0.1.0
+Summary: ANNI (Auditory Nerve Noticeability Index): how noticeable the difference between two audio signals is
+Author: DeepMark Inc.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/deepmark/anni
+Project-URL: Issues, https://github.com/deepmark/anni/issues
+Keywords: audio,quality,audibility,auditory nerve,neurogram,psychoacoustics,watermarking
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: torch>=2.4.1
+Requires-Dist: soxr>=0.4
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Dynamic: license-file
+
+# ANNI: Auditory Nerve Noticeability Index
+
+ANNI is a full-reference measure of how noticeable the difference between a reference and a test audio signal is.
+It simulates how the auditory nerve responds to each signal and compares the two responses the way an ideal observer
+would. The score is in d′ units, the standard unit of detectability: **0 means no difference, and larger values mean
+a more noticeable difference.** ANNI is built for small differences near the threshold of hearing, such as audio
+watermarks.
+
+> **Status: research prototype (v0.1).** ANNI is calibrated so that D = 1 marks a just-noticeable difference: the
+> point at which listeners in classic laboratory experiments start to detect a change. A score below 1 should
+> therefore mean the difference is hard to hear, even when comparing directly. This has not yet been confirmed by
+> listening tests on real-world audio.
+
+## Install
+
+```bash
+pip install deepmark-anni
+```
+
+Requires Python 3.9 or newer, PyTorch, NumPy and soxr.
+
+For development, install from a clone in editable mode:
+
+```bash
+git clone https://github.com/deepmark/anni.git
+cd anni
+python -m pip install -e ".[test]"
+```
+
+## Usage
+
+```python
+import soundfile as sf          # any audio loader works
+from anni import ANNI
+
+reference, sr = sf.read("original.wav")
+test, _ = sf.read("watermarked.wav")
+
+anni = ANNI()
+anni(reference, test, sr=sr)
+# e.g. {'D_peak': 1.49, 'D_med': 0.81}
+```
+
+| Score | Meaning |
+|---|---|
+| `D_peak` | how noticeable the difference is at the most noticeable 200 ms moment |
+| `D_med` | how noticeable it is at a typical moment (median over 200 ms windows) |
+
+Lower is better. To compare two processed versions, score both against the same reference. A difference between two
+scores can be expressed in dB as 20·log₁₀(D_B / D_A).
+
+## Inputs
+
+- **Mono signals** at the same sample rate. The model runs at 44.1 kHz; other rates are resampled to it.
+- **Playback level:** the reference is played at 65 dB SPL, about conversational speech (`ANNI(level=...)` changes
+  this). Both signals get the same gain, so a level change in the test signal counts as a difference.
+- **Timing:** a constant delay of up to ±10 ms is removed. If the lengths differ, the longer signal is cut.
+- **Length:** clips from 0.5 s to about 10 s, as for PESQ and ViSQOL. Memory grows with length: a 5 s pair takes about
+  1 s and 1.5 GB on a laptop CPU. On an NVIDIA GPU, use `ANNI(device="cuda")`.
+
+ANNI warns whenever it changes the inputs (resampling, cutting, removing a delay or a constant offset between them)
+and when the test signal is polarity-inverted. It also warns when the two signals correlate weakly (below 0.9), for
+example after a speech codec: the scores may then not be meaningful.
+
+## How it works
+
+1. A filter models the outer and middle ear.
+2. An auditory-nerve model turns each signal into the firing rates of 128 nerve fibres tuned from 80 Hz to 16 kHz:
+   cochlear (gammatone) filters, inner-hair-cell rectification and smoothing, and a sigmoid firing-rate curve.
+3. Two observers compare the firing rates. Each change is weighed against the natural randomness of nerve firing,
+   which is what makes loud sounds mask quieter ones. One observer looks at slow changes in firing rate (level and
+   colouration), the other at changes in how the rate fluctuates (roughness, flutter).
+4. The evidence is added up over fibres and over 200 ms windows. `D_peak` is the largest window, `D_med` the median.
+
+Four constants set the scale so that classic laboratory thresholds score about D = 1: the threshold of hearing and
+the 1 dB level difference at 1 kHz (following Taal et al. 2012), noise and tone masking (ITU-R BS.1387), and
+amplitude-modulation detection on tones (He et al. 2008) and on noise (O'Connor et al. 2011).
+
+A function-by-function walk-through of the code is in [docs.md](https://github.com/deepmark/anni/blob/main/docs.md).
+For a comparison with PESQ and ViSQOL on controlled changes, with audio, see
+[examples/](https://github.com/deepmark/anni/tree/main/examples).
+
+## Evaluation
+
+On [ODAQ](https://zenodo.org/records/10405774), an open dataset of music, film sound and speech over music rated by 26
+listeners (210 versions of 30 excerpts; Torcoli et al. 2024), `D_med` orders the versions like the listeners with a
+Spearman correlation of 0.85 (95 % interval 0.79–0.89). That is on par with Zimtohrli (0.83) and above ViSQOL (0.65 in
+audio mode) and PESQ (0.42). On degraded speech, in the TCD-VoIP dataset (Harte et al. 2015; packet loss, clipping,
+echo, competing speakers and noise, rated by 24 listeners), PESQ and ViSQOL follow listeners better.
+
+## Limitations
+
+- It compares the signals moment by moment, so it does not suit audio whose timing or pitch has changed
+  (time-stretching, pitch-shifting) or that went through a speech codec.
+- It doesn't see energy above 16 kHz or below 80 Hz, very fast fluctuations or fine timing structure.
+- Mono only, normal hearing.
+
+## Credits and licence
+
+ANNI is developed by DeepMark Inc. and released under the
+[MIT License](https://github.com/deepmark/anni/blob/main/LICENSE).
+
+The auditory-nerve model is adapted from Mark R. Saddler's
+[auditory_machine_learning](https://github.com/msaddler/auditory_machine_learning). If you use ANNI, please also cite:
+
+- Saddler, M. R., & McDermott, J. H. (2024). Models optimized for real-world tasks reveal the task-dependent necessity
+  of precise temporal coding in hearing. *Nature Communications*.
+  [doi:10.1038/s41467-024-54700-5](https://doi.org/10.1038/s41467-024-54700-5)
+
+Listening-test data:
+
+- Torcoli, M., Wu, C.-W., Dick, S., Williams, P. A., Halimeh, M. M., Wolcott, W., & Habets, E. A. P. (2024). ODAQ: Open
+  Dataset of Audio Quality. *Proc. IEEE ICASSP*. [arXiv:2401.00197](https://arxiv.org/abs/2401.00197)
+- Harte, N., Gillen, E., & Hines, A. (2015). TCD-VoIP, a research database of degraded speech for assessing quality in
+  VoIP applications. *Proc. QoMEX*.
+
+Calibration references:
+
+- Taal, C. H., Hendriks, R. C., & Heusdens, R. (2012). A low-complexity spectro-temporal distortion measure for audio
+  processing applications. *IEEE Transactions on Audio, Speech, and Language Processing*, 20(5).
+  [doi:10.1109/TASL.2012.2184753](https://doi.org/10.1109/TASL.2012.2184753)
+- ITU-R BS.1387: Method for objective measurements of perceived audio quality (PEAQ).
+- He, N., Mills, J. H., Ahlstrom, J. B., & Dubno, J. R. (2008). Age-related differences in the temporal modulation
+  transfer function with pure-tone carriers. *The Journal of the Acoustical Society of America*, 124(6), 3841–3849.
+  [doi:10.1121/1.2998779](https://doi.org/10.1121/1.2998779)
+- O'Connor, K. N., Johnson, J. S., Niwa, M., Noriega, N. C., Marshall, E. A., & Sutter, M. L. (2011). Amplitude
+  modulation detection as a function of modulation frequency and stimulus duration: comparisons between macaques and
+  humans. *Hearing Research*, 277, 37–43. [doi:10.1016/j.heares.2011.03.014](https://doi.org/10.1016/j.heares.2011.03.014)

deepmark_anni-0.1.0/src/deepmark_anni.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/anni/__init__.py
+src/anni/_auditory_model.py
+src/anni/_core.py
+src/anni/measure.py
+src/deepmark_anni.egg-info/PKG-INFO
+src/deepmark_anni.egg-info/SOURCES.txt
+src/deepmark_anni.egg-info/dependency_links.txt
+src/deepmark_anni.egg-info/requires.txt
+src/deepmark_anni.egg-info/top_level.txt
+tests/test_anni.py

deepmark_anni-0.1.0/src/deepmark_anni.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

deepmark_anni-0.1.0/src/deepmark_anni.egg-info/requires.txt

@@ -0,0 +1,6 @@
+numpy>=1.21
+torch>=2.4.1
+soxr>=0.4
+
+[test]
+pytest>=7.0

deepmark_anni-0.1.0/src/deepmark_anni.egg-info/top_level.txt

@@ -0,0 +1 @@
+anni

deepmark_anni-0.1.0/tests/test_anni.py

@@ -0,0 +1,93 @@
+import numpy as np
+import pytest
+import torch
+
+from anni import ANNI
+
+SR = 44100
+
+
+@pytest.fixture(scope="module")
+def measure():
+    return ANNI()
+
+
+@pytest.fixture(scope="module")
+def ref():
+    t = np.arange(int(1.5 * SR)) / SR
+    rng = np.random.default_rng(0)
+    return 0.1 * np.sin(2 * np.pi * 440 * t) * (1 + 0.5 * np.sin(2 * np.pi * 3 * t)) + 0.02 * rng.standard_normal(len(t))
+
+
+def noisy(x, amp):
+    return x + amp * np.random.default_rng(1).standard_normal(len(x))
+
+
+def test_identical_signals_score_zero(measure, ref):
+    assert measure(ref, ref, sr=SR) == {"D_peak": 0.0, "D_med": 0.0}
+
+
+def test_regression_values(measure, ref):
+    s = measure(ref, noisy(ref, 0.003), sr=SR)
+    assert s["D_peak"] == pytest.approx(0.5433951020240784, rel=1e-5)
+    assert s["D_med"] == pytest.approx(0.5027734041213989, rel=1e-5)
+
+
+def test_larger_difference_scores_higher(measure, ref):
+    d = [measure(ref, noisy(ref, a), sr=SR)["D_peak"] for a in (0.001, 0.003, 0.01)]
+    assert d[0] < d[1] < d[2]
+
+
+def test_level_change_is_scored(measure, ref):
+    assert measure(ref, ref * 10 ** (1 / 20), sr=SR)["D_peak"] > 0.5
+
+
+def test_tensor_input_and_constant_delay(measure, ref):
+    y = noisy(ref, 0.003)
+    a = measure(ref, y, sr=SR)
+    with pytest.warns(UserWarning, match="shifted by"):
+        b = measure(torch.tensor(ref), torch.tensor(np.concatenate([np.zeros(20), y[:-20]])), sr=SR)
+    assert b["D_med"] == pytest.approx(a["D_med"], rel=0.1)
+
+
+def test_no_warnings_for_clean_input(measure, ref):
+    import warnings
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")
+        measure(ref, noisy(ref, 0.003), sr=SR)
+
+
+def test_other_sample_rate_is_resampled_with_a_warning(measure):
+    sr = 48000
+    t = np.arange(int(1.5 * sr)) / sr
+    x = 0.1 * np.sin(2 * np.pi * 440 * t)
+    with pytest.warns(UserWarning, match="resampling"):
+        assert measure(x, x * 1.1, sr=sr)["D_peak"] > 0
+
+
+def test_dc_offset_is_removed_with_a_warning(measure, ref):
+    with pytest.warns(UserWarning, match="DC"):
+        s = measure(ref, ref + 0.05, sr=SR)
+    assert s["D_peak"] < 1e-6
+
+
+def test_pauses_do_not_change_the_playback_level(ref):
+    from anni import _core
+    x = torch.tensor(ref)
+    padded = torch.cat([torch.zeros(SR), x])
+    assert float(_core.pa_gain(padded)) == pytest.approx(float(_core.pa_gain(x)), rel=1e-5)
+
+
+def test_input_checks(measure, ref):
+    with pytest.raises(ValueError):
+        measure(np.stack([ref, ref]), np.stack([ref, ref]), sr=SR)
+    with pytest.raises(ValueError):
+        measure(ref[:1000], ref[:1000], sr=SR)
+    with pytest.raises(ValueError, match="silent"):
+        measure(np.full(len(ref), 0.3), ref, sr=SR)
+    with pytest.warns(UserWarning, match="correlate weakly"):
+        measure(ref, np.random.default_rng(2).standard_normal(len(ref)) * 0.05, sr=SR)
+    with pytest.warns(UserWarning, match="differ in length"):
+        measure(ref, noisy(ref, 0.003)[:-100], sr=SR)
+    with pytest.warns(UserWarning, match="polarity-inverted"):
+        measure(ref, -noisy(ref, 0.003), sr=SR)