phonipy 0.1.0__tar.gz

phonipy-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish to PyPI
+on:
+  release:
+    types: [published]
+permissions:
+  contents: read
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: python -m pip install --upgrade pip certifi
+      - run: python -m pip install -e '.[test,app]'
+      - run: ruff check .
+      - run: pytest
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - name: Check release tag matches package version
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: python -c "import os, phonipy; assert os.environ['RELEASE_TAG'] == 'v' + phonipy.__version__"
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: true

phonipy-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,28 @@
+name: Test and build
+on:
+  push:
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ['3.10', '3.12', '3.14']
+    runs-on: ${{ matrix.os }}
+    env:
+      MPLBACKEND: Agg
+      STREAMLIT_BROWSER_GATHER_USAGE_STATS: 'false'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install --upgrade pip certifi
+      - run: python -m pip install -e '.[test,app]'
+      - run: ruff check .
+      - run: pytest --cov=phonipy --cov-report=term-missing
+      - run: python -m build
+      - run: python -m twine check dist/*

phonipy-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+*.egg-info/
+benchmarks/data/
+benchmarks/results/
+.DS_Store
+.env
+.pypirc

phonipy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muhammad Umair Danish
+
+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.

phonipy-0.1.0/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.5
+Name: phonipy
+Version: 0.1.0
+Summary: Reproducible musical-note stability and harmonic-purity analysis of voice recordings
+Project-URL: Homepage, https://github.com/udanish50/PhoniPy
+Project-URL: Issues, https://github.com/udanish50/PhoniPy/issues
+Author: Muhammad Umair Danish
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audio,music-therapy,phonation,pitch,voice
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: soundfile>=0.12
+Provides-Extra: app
+Requires-Dist: matplotlib>=3.7; extra == 'app'
+Requires-Dist: pandas>=2; extra == 'app'
+Requires-Dist: streamlit>=1.40; extra == 'app'
+Provides-Extra: benchmark
+Requires-Dist: certifi>=2026.10.19; extra == 'benchmark'
+Requires-Dist: wfdb>=4.1; extra == 'benchmark'
+Provides-Extra: excel
+Requires-Dist: openpyxl>=3.1; extra == 'excel'
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.7; extra == 'plot'
+Provides-Extra: test
+Requires-Dist: build>=1.2; extra == 'test'
+Requires-Dist: matplotlib>=3.7; extra == 'test'
+Requires-Dist: openpyxl>=3.1; extra == 'test'
+Requires-Dist: pytest-cov>=5; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Requires-Dist: ruff>=0.9; extra == 'test'
+Requires-Dist: twine>=6; extra == 'test'
+Description-Content-Type: text/markdown
+
+# PhoniPy
+
+Reproducible musical-note stability and harmonic-purity analysis for solo voice recordings.
+PhoniPy reads audio, detects stable note intervals, computes all ten parameters from
+*Musical-Key Stability Analysis of Continuous Voice*, and exports recording summaries,
+frame data, segment data, and composite plots.
+
+**Research software, version 0.1.0.** The detector is an explicitly documented implementation
+of the manuscript's framework, not a verified reproduction of its unavailable prototype.
+The manuscript's clinical claims and thresholds are not validated by this package.
+
+## Install
+
+```bash
+pip install phonipy
+# Optional exports, plots, dashboard:
+pip install 'phonipy[excel,plot,app]'
+```
+
+Python 3.10 or newer. Core dependencies: NumPy, SciPy, and SoundFile/libsndfile.
+WAV, FLAC, OGG, AIFF and other libsndfile-supported formats are accepted. MP3 support
+depends on the installed libsndfile build; unsupported codecs produce a per-file error.
+For compressed video/audio containers such as M4A, convert to PCM WAV first.
+
+## Python API
+
+```python
+from phonipy import AnalysisConfig, analyze_file, analyze_directory
+
+config = AnalysisConfig.preset("speech", reference_key=57)  # A3, MIDI numbering
+result = analyze_file("voice.wav", config)
+print(result.metrics)
+result.to_json("voice-results.json", include_frames=True)
+result.plot("voice-composite.png")  # requires phonipy[plot]
+
+batch = analyze_directory("recordings", config, recursive=True)
+batch.save("results.csv")  # also JSON or XLSX; failures are retained
+print(batch.errors)
+```
+
+The package also accepts NumPy arrays with `analyze_samples(samples, sample_rate, config)`.
+Arrays use samples-by-channels order; integer PCM is scaled automatically. Floating PCM
+should be approximately within -1 to 1. No automatic gain normalization is performed.
+
+### Familiar midipy-style batch API
+
+```python
+from phonipy import parser
+
+table = parser(
+    "recordings",
+    metrics=["source", "valid_time", "average_energy", "breakouts"],
+    output_format="csv",
+    save_path="VoiceOutput",
+)
+```
+
+`parser` requires pandas (included with `phonipy[app]`). `metrics` selects returned DataFrame
+columns; the saved analysis summary always retains all ten metrics and failures for auditing.
+Prefer the core batch API when pandas is not needed. No outputs are created by analysis
+functions until an explicit save/export call.
+
+## Command line
+
+```bash
+phonipy voice.wav -o result.json --reference-key 57 --details details --plot
+phonipy recordings -o results.csv --recursive --preset speech
+python -m phonipy recordings -o results.xlsx --config examples/config.json
+```
+
+Exit codes: **0** complete success, **1** batch completed with failed files, **2** invalid
+input/settings/output or a single-file failure. Batch processing continues after corrupt
+files by default; `--strict` stops on the first failure. JSON includes settings, warnings,
+and failures; CSV/XLSX include failure rows plus a `.metadata.json` sidecar. `--details`
+adds full JSON and frame/segment CSVs. Duplicate filenames receive distinct numeric prefixes.
+
+## Local dashboard
+
+```bash
+pip install 'phonipy[app]'
+streamlit run "$(python -c 'import phonipy.app; print(phonipy.app.__file__)')"
+```
+
+Upload multiple files, adjust settings, view composite plots, and download CSV/JSON.
+Analysis runs locally without uploads to an analysis service or telemetry from PhoniPy.
+The dashboard limits each recording to five minutes and 100 MB.
+
+## The ten metrics
+
+Let `d_i = end_i - start_i` for each valid stable-note segment; `N` is the segment count.
+
+| Metric | Definition | Unit |
+| --- | --- | --- |
+| `raw_duration` | Original sample count / original sample rate | s |
+| `active_time` | Last valid offset − first valid onset | s |
+| `valid_time` | Sum of valid segment durations | s |
+| `average_offset` | Unweighted segment mean of fractional pitch − reference note | semitones |
+| `average_energy` | Duration-weighted harmonic-energy ratio across valid intervals | 0–1 |
+| `hoarseness` | `(1 - average_energy) * 100` | % |
+| `average_duration` | `valid_time / N` | s |
+| `continuity` | `average_duration / valid_time` | dimensionless |
+| `sparsity` | `valid_time / active_time` | 0–1 |
+| `breakouts` | `N`, including the initial acquisition | count |
+
+No valid detections: time totals, breakouts, continuity and sparsity are zero; undefined
+means and hoarseness are `null` in JSON and blank in CSV/XLSX. **Continuity equals `1/N`**
+whenever N > 0; it is retained exactly as specified, not presented as an independent metric.
+The manuscript uses two inconsistent descriptions of breakouts; this package follows
+Appendix A's segment count. Signed pitch offsets can cancel. `hoarseness` is the manuscript's
+name for an acoustic residual-energy transform, not a clinical hoarseness rating.
+
+## Detector and reproducibility
+
+- Default analysis rate: 16 kHz; hop: 17.25 ms (276 samples); Hann window: 69 ms.
+- Normalized autocorrelation supplies candidate periods; the earliest sufficiently strong
+  local peak is refined with parabolic interpolation. This makes the fundamental candidate
+  stage explicit where the manuscript only says "strongest harmonic series."
+- Harmonic-series energy is measured from a one-sided Hann-windowed power spectrum in
+  nonoverlapping frequency bands around up to 12 harmonics; total energy includes all bins.
+- RMS, periodicity, spectral flatness, pitch range, and harmonic ratio gate detections.
+- The identical rounded MIDI note must persist for at least eight frames. Accepted runs are
+  backdated to their first frame, not the eighth. Invalid/unvoiced frames end a run.
+- Each frame represents a hop interval. Durations use disjoint intervals and the last interval
+  is clipped to the original duration. Forward-looking windows are zero-padded at the end.
+  Overlapping spectral windows do not create overlapping measured durations.
+- Fractional pitch is retained separately for pitch offset. A4=440 Hz is MIDI note 69;
+  traditional 88-key piano index = MIDI number minus 20. Differences are identical.
+- All effective settings, sample rates, channel selection, and warnings are exported.
+
+See [methodology](docs/methodology.md) for equations and limitations.
+
+## Input handling and limits
+
+Stereo/multichannel recordings select the loudest channel by default to avoid phase cancellation.
+Choose `channel="mix"`, `"left"`, or `"right"` explicitly if desired. Resampling is polyphase.
+NaN/infinite samples raise an error unless `nonfinite="zero"` explicitly enables replacement.
+Empty/corrupt inputs, absent channels, invalid ranges, unavailable codecs, and excessive
+durations produce actionable errors. Clipping/DC offset and short input produce warnings.
+The default one-hour duration cap is configurable. Audio and frame results are held in memory;
+split very large recordings into tasks. Output failures are surfaced rather than silently ignored.
+
+Use quiet, solo voice recordings with consistent microphones and levels. Stable vowels and
+single-note holds are the clearest tasks. Speech has natural unvoiced intervals and singing
+has intentional pitch changes; their scores should not be directly compared with vowel scores.
+Noise, reverberation, vibrato, note-boundary quantization, and octave errors can affect results.
+No automatic recovery can reconstruct information absent from a recording.
+
+## Tests and benchmarks
+
+```bash
+pip install -e '.[test,app,benchmark]'
+pytest --cov=phonipy --cov-report=term-missing
+ruff check .
+python benchmarks/download.py --data-dir benchmarks/data
+python benchmarks/run.py --data-dir benchmarks/data --output benchmarks/results
+python -m build
+python -m twine check dist/*
+```
+
+The benchmark scripts analyze synthetic signals with known pitch/timing, all 3,000 recordings
+in a pinned Free Spoken Digit Dataset snapshot, and all 208 VOICED sustained-vowel records.
+They record source hashes, settings, dependency versions, wall time, failures, and per-file metrics.
+Real recordings have no ground-truth values for these novel metrics: those runs demonstrate
+processing coverage, not clinical accuracy or disease classification.
+See [benchmark protocol](benchmarks/README.md) and [results](docs/benchmark-results.md).
+
+## Attribution and license
+
+Implementation: Muhammad Umair Danish. Scientific framework: the user-supplied manuscript
+*Musical-Key Stability Analysis of Continuous Voice: A Methodology for Quantifying Phonatory
+Continuity and Purity in Neurological Disorders with Applications in Music Therapy*, by
+Demian Kogutek and Danish Umair Muhammad. The manuscript itself is not redistributed.
+
+Code: MIT. Benchmark recordings retain their upstream licenses and are not bundled in
+the wheel/source distribution. See the benchmark protocol for dataset citations.

phonipy-0.1.0/README.md

@@ -0,0 +1,175 @@
+# PhoniPy
+
+Reproducible musical-note stability and harmonic-purity analysis for solo voice recordings.
+PhoniPy reads audio, detects stable note intervals, computes all ten parameters from
+*Musical-Key Stability Analysis of Continuous Voice*, and exports recording summaries,
+frame data, segment data, and composite plots.
+
+**Research software, version 0.1.0.** The detector is an explicitly documented implementation
+of the manuscript's framework, not a verified reproduction of its unavailable prototype.
+The manuscript's clinical claims and thresholds are not validated by this package.
+
+## Install
+
+```bash
+pip install phonipy
+# Optional exports, plots, dashboard:
+pip install 'phonipy[excel,plot,app]'
+```
+
+Python 3.10 or newer. Core dependencies: NumPy, SciPy, and SoundFile/libsndfile.
+WAV, FLAC, OGG, AIFF and other libsndfile-supported formats are accepted. MP3 support
+depends on the installed libsndfile build; unsupported codecs produce a per-file error.
+For compressed video/audio containers such as M4A, convert to PCM WAV first.
+
+## Python API
+
+```python
+from phonipy import AnalysisConfig, analyze_file, analyze_directory
+
+config = AnalysisConfig.preset("speech", reference_key=57)  # A3, MIDI numbering
+result = analyze_file("voice.wav", config)
+print(result.metrics)
+result.to_json("voice-results.json", include_frames=True)
+result.plot("voice-composite.png")  # requires phonipy[plot]
+
+batch = analyze_directory("recordings", config, recursive=True)
+batch.save("results.csv")  # also JSON or XLSX; failures are retained
+print(batch.errors)
+```
+
+The package also accepts NumPy arrays with `analyze_samples(samples, sample_rate, config)`.
+Arrays use samples-by-channels order; integer PCM is scaled automatically. Floating PCM
+should be approximately within -1 to 1. No automatic gain normalization is performed.
+
+### Familiar midipy-style batch API
+
+```python
+from phonipy import parser
+
+table = parser(
+    "recordings",
+    metrics=["source", "valid_time", "average_energy", "breakouts"],
+    output_format="csv",
+    save_path="VoiceOutput",
+)
+```
+
+`parser` requires pandas (included with `phonipy[app]`). `metrics` selects returned DataFrame
+columns; the saved analysis summary always retains all ten metrics and failures for auditing.
+Prefer the core batch API when pandas is not needed. No outputs are created by analysis
+functions until an explicit save/export call.
+
+## Command line
+
+```bash
+phonipy voice.wav -o result.json --reference-key 57 --details details --plot
+phonipy recordings -o results.csv --recursive --preset speech
+python -m phonipy recordings -o results.xlsx --config examples/config.json
+```
+
+Exit codes: **0** complete success, **1** batch completed with failed files, **2** invalid
+input/settings/output or a single-file failure. Batch processing continues after corrupt
+files by default; `--strict` stops on the first failure. JSON includes settings, warnings,
+and failures; CSV/XLSX include failure rows plus a `.metadata.json` sidecar. `--details`
+adds full JSON and frame/segment CSVs. Duplicate filenames receive distinct numeric prefixes.
+
+## Local dashboard
+
+```bash
+pip install 'phonipy[app]'
+streamlit run "$(python -c 'import phonipy.app; print(phonipy.app.__file__)')"
+```
+
+Upload multiple files, adjust settings, view composite plots, and download CSV/JSON.
+Analysis runs locally without uploads to an analysis service or telemetry from PhoniPy.
+The dashboard limits each recording to five minutes and 100 MB.
+
+## The ten metrics
+
+Let `d_i = end_i - start_i` for each valid stable-note segment; `N` is the segment count.
+
+| Metric | Definition | Unit |
+| --- | --- | --- |
+| `raw_duration` | Original sample count / original sample rate | s |
+| `active_time` | Last valid offset − first valid onset | s |
+| `valid_time` | Sum of valid segment durations | s |
+| `average_offset` | Unweighted segment mean of fractional pitch − reference note | semitones |
+| `average_energy` | Duration-weighted harmonic-energy ratio across valid intervals | 0–1 |
+| `hoarseness` | `(1 - average_energy) * 100` | % |
+| `average_duration` | `valid_time / N` | s |
+| `continuity` | `average_duration / valid_time` | dimensionless |
+| `sparsity` | `valid_time / active_time` | 0–1 |
+| `breakouts` | `N`, including the initial acquisition | count |
+
+No valid detections: time totals, breakouts, continuity and sparsity are zero; undefined
+means and hoarseness are `null` in JSON and blank in CSV/XLSX. **Continuity equals `1/N`**
+whenever N > 0; it is retained exactly as specified, not presented as an independent metric.
+The manuscript uses two inconsistent descriptions of breakouts; this package follows
+Appendix A's segment count. Signed pitch offsets can cancel. `hoarseness` is the manuscript's
+name for an acoustic residual-energy transform, not a clinical hoarseness rating.
+
+## Detector and reproducibility
+
+- Default analysis rate: 16 kHz; hop: 17.25 ms (276 samples); Hann window: 69 ms.
+- Normalized autocorrelation supplies candidate periods; the earliest sufficiently strong
+  local peak is refined with parabolic interpolation. This makes the fundamental candidate
+  stage explicit where the manuscript only says "strongest harmonic series."
+- Harmonic-series energy is measured from a one-sided Hann-windowed power spectrum in
+  nonoverlapping frequency bands around up to 12 harmonics; total energy includes all bins.
+- RMS, periodicity, spectral flatness, pitch range, and harmonic ratio gate detections.
+- The identical rounded MIDI note must persist for at least eight frames. Accepted runs are
+  backdated to their first frame, not the eighth. Invalid/unvoiced frames end a run.
+- Each frame represents a hop interval. Durations use disjoint intervals and the last interval
+  is clipped to the original duration. Forward-looking windows are zero-padded at the end.
+  Overlapping spectral windows do not create overlapping measured durations.
+- Fractional pitch is retained separately for pitch offset. A4=440 Hz is MIDI note 69;
+  traditional 88-key piano index = MIDI number minus 20. Differences are identical.
+- All effective settings, sample rates, channel selection, and warnings are exported.
+
+See [methodology](docs/methodology.md) for equations and limitations.
+
+## Input handling and limits
+
+Stereo/multichannel recordings select the loudest channel by default to avoid phase cancellation.
+Choose `channel="mix"`, `"left"`, or `"right"` explicitly if desired. Resampling is polyphase.
+NaN/infinite samples raise an error unless `nonfinite="zero"` explicitly enables replacement.
+Empty/corrupt inputs, absent channels, invalid ranges, unavailable codecs, and excessive
+durations produce actionable errors. Clipping/DC offset and short input produce warnings.
+The default one-hour duration cap is configurable. Audio and frame results are held in memory;
+split very large recordings into tasks. Output failures are surfaced rather than silently ignored.
+
+Use quiet, solo voice recordings with consistent microphones and levels. Stable vowels and
+single-note holds are the clearest tasks. Speech has natural unvoiced intervals and singing
+has intentional pitch changes; their scores should not be directly compared with vowel scores.
+Noise, reverberation, vibrato, note-boundary quantization, and octave errors can affect results.
+No automatic recovery can reconstruct information absent from a recording.
+
+## Tests and benchmarks
+
+```bash
+pip install -e '.[test,app,benchmark]'
+pytest --cov=phonipy --cov-report=term-missing
+ruff check .
+python benchmarks/download.py --data-dir benchmarks/data
+python benchmarks/run.py --data-dir benchmarks/data --output benchmarks/results
+python -m build
+python -m twine check dist/*
+```
+
+The benchmark scripts analyze synthetic signals with known pitch/timing, all 3,000 recordings
+in a pinned Free Spoken Digit Dataset snapshot, and all 208 VOICED sustained-vowel records.
+They record source hashes, settings, dependency versions, wall time, failures, and per-file metrics.
+Real recordings have no ground-truth values for these novel metrics: those runs demonstrate
+processing coverage, not clinical accuracy or disease classification.
+See [benchmark protocol](benchmarks/README.md) and [results](docs/benchmark-results.md).
+
+## Attribution and license
+
+Implementation: Muhammad Umair Danish. Scientific framework: the user-supplied manuscript
+*Musical-Key Stability Analysis of Continuous Voice: A Methodology for Quantifying Phonatory
+Continuity and Purity in Neurological Disorders with Applications in Music Therapy*, by
+Demian Kogutek and Danish Umair Muhammad. The manuscript itself is not redistributed.
+
+Code: MIT. Benchmark recordings retain their upstream licenses and are not bundled in
+the wheel/source distribution. See the benchmark protocol for dataset citations.

phonipy-0.1.0/benchmarks/README.md

@@ -0,0 +1,42 @@
+# Benchmark protocol
+
+Run from the repository root after `pip install -e '.[test,benchmark]'`.
+
+```bash
+python benchmarks/download.py --data-dir benchmarks/data
+python benchmarks/run.py --data-dir benchmarks/data --output benchmarks/results
+```
+
+Use `--datasets synthetic fsdd` or `--datasets voiced` to run selected corpora. Runs in the
+same output directory merge summaries only when configuration and dependency versions match.
+
+## Sources
+
+1. **Free Spoken Digit Dataset (FSDD)**, Jakobovski and contributors:
+   https://github.com/Jakobovski/free-spoken-digit-dataset
+   Snapshot: `26eb9aaf76e81b692f806f9140c2d2777410d7a1`.
+   CC BY-SA 4.0; 3,000 8-kHz English digit recordings from six speakers.
+   All files are processed; no training or classification is performed.
+2. **VOICED Database**, version 1.0.0:
+   https://physionet.org/content/voiced/1.0.0/
+   DOI: https://doi.org/10.13026/C25Q2N
+   License: Open Data Commons Attribution License v1.0.
+   208 sustained-vowel records, including healthy and pathological voices.
+   All records are processed as a technical coverage benchmark; no disease labels are predicted.
+   WFDB `p_signal` is decoded using the record's physical gain/baseline. It is not
+   per-recording peak-normalized, so amplitude gating remains an explicit limitation.
+3. **PhoniPy synthetic-v1**: generated sines, harmonic tones, interrupted holds, noise,
+   and silence with fixed RNG seed. Code is MIT, with known pitch for periodic cases.
+
+Downloads use HTTPS with verification, timeout/retry, safe selective FSDD archive extraction,
+and SHA-256 provenance manifests. VOICED signals/headers are checked against PhysioNet's
+official SHA256SUMS. Raw third-party recordings are never included in package
+distributions or committed. Dataset hashes and per-file result hashes are saved with results.
+The benchmark writes all ten metrics for each recording, failure manifests, summaries,
+dependency/platform metadata, and synthetic pitch-error measurements. Low/zero detection
+coverage is reported, never hidden as a successful clinical measurement.
+
+No ground-truth values for the ten manuscript metrics are supplied by these corpora. Real-data
+results measure executability and detector coverage, not pitch-estimation accuracy, clinical
+validity, or sensitivity/specificity. Use a separate annotated pitch corpus and clinical study
+before making those claims.

phonipy-0.1.0/benchmarks/download.py

@@ -0,0 +1,133 @@
+"""Download pinned public benchmarks; no credentials needed and no raw data committed."""
+
+import argparse
+import hashlib
+import json
+import re
+import shutil
+import ssl
+import time
+import zipfile
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path, PurePosixPath
+from urllib.error import URLError
+from urllib.request import urlopen
+
+import certifi
+
+FSDD_COMMIT = "26eb9aaf76e81b692f806f9140c2d2777410d7a1"
+FSDD_URL = f"https://codeload.github.com/Jakobovski/free-spoken-digit-dataset/zip/{FSDD_COMMIT}"
+VOICED_URL = "https://physionet.org/files/voiced/1.0.0/"
+
+
+def sha256_file(path):
+    digest = hashlib.sha256()
+    with Path(path).open("rb") as handle:
+        for block in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+def download(url, path, expected=None):
+    if path.exists() and (expected is None or sha256_file(path) == expected):
+        return
+    partial = path.with_name(path.name + ".part")
+    for attempt in range(3):
+        try:
+            context = ssl.create_default_context(cafile=certifi.where())
+            with urlopen(url, timeout=60, context=context) as response, partial.open("wb") as out:
+                shutil.copyfileobj(response, out)
+            if expected is not None and sha256_file(partial) != expected:
+                raise ValueError(f"Official checksum mismatch: {path.name}")
+            partial.replace(path)
+            return
+        except (URLError, OSError, ValueError):
+            if attempt == 2:
+                raise
+            time.sleep(2**attempt)
+
+
+def file_manifest(output, root):
+    return [
+        {"file": path.relative_to(root).as_posix(), "sha256": sha256_file(path)}
+        for path in sorted(output.rglob("*"))
+        if path.is_file()
+    ]
+
+
+def fetch_fsdd(root):
+    archive = root / "fsdd.zip"
+    print("Downloading/extracting pinned FSDD...", flush=True)
+    download(FSDD_URL, archive)
+    output = root / "fsdd"
+    output.mkdir(exist_ok=True)
+    with zipfile.ZipFile(archive) as handle:
+        for member in handle.infolist():
+            path = PurePosixPath(member.filename)
+            if member.is_dir() or ".." in path.parts or path.is_absolute():
+                continue
+            if "recordings" not in path.parts and path.name not in ("README.md", "LICENSE"):
+                continue
+            relative = (
+                Path("recordings") / path.name if "recordings" in path.parts else Path(path.name)
+            )
+            destination = output / relative
+            destination.parent.mkdir(parents=True, exist_ok=True)
+            with handle.open(member) as src, destination.open("wb") as dst:
+                shutil.copyfileobj(src, dst)
+    return {
+        "dataset": "fsdd",
+        "url": FSDD_URL,
+        "snapshot": FSDD_COMMIT,
+        "archive_sha256": sha256_file(archive),
+        "license": "CC-BY-SA-4.0",
+        "files": file_manifest(output, root),
+    }
+
+
+def fetch_voiced(root):
+    output = root / "voiced"
+    output.mkdir(exist_ok=True)
+    download(VOICED_URL + "RECORDS", output / "RECORDS")
+    download(VOICED_URL + "SHA256SUMS.txt", output / "SHA256SUMS.txt")
+    expected = {}
+    for line in (output / "SHA256SUMS.txt").read_text().splitlines():
+        digest, filename = line.split(maxsplit=1)
+        expected[PurePosixPath(filename.lstrip("*")).name] = digest
+    records = (output / "RECORDS").read_text().splitlines()
+    if len(records) != 208 or not all(re.fullmatch(r"voice\d{3}", r) for r in records):
+        raise ValueError("Unexpected VOICED record manifest")
+    files = [r + suffix for r in records for suffix in (".hea", ".dat")]
+    if not all(name in expected for name in files):
+        raise ValueError("VOICED is missing official signal/header checksums")
+
+    def fetch(name):
+        download(VOICED_URL + name, output / name, expected[name])
+
+    print("Downloading 208 VOICED signals and headers (four connections)...", flush=True)
+    with ThreadPoolExecutor(max_workers=4) as pool:
+        for index, _ in enumerate(pool.map(fetch, files), 1):
+            if index % 50 == 0:
+                print(f"VOICED: {index}/{len(files)} files", flush=True)
+    return {
+        "dataset": "voiced",
+        "url": VOICED_URL,
+        "snapshot": "1.0.0",
+        "license": "Open Data Commons Attribution License v1.0",
+        "doi": "10.13026/C25Q2N",
+        "files": file_manifest(output, root),
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--data-dir", type=Path, default=Path("benchmarks/data"))
+    args = parser.parse_args()
+    args.data_dir.mkdir(parents=True, exist_ok=True)
+    manifest = [fetch_fsdd(args.data_dir), fetch_voiced(args.data_dir)]
+    (args.data_dir / "provenance.json").write_text(json.dumps(manifest, indent=2) + "\n")
+    print("All benchmark downloads complete; official VOICED checksums verified", flush=True)
+
+
+if __name__ == "__main__":
+    main()