audio-diag 0.1.0__tar.gz

audio_diag-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adrián Cancio / contributors
+
+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.

audio_diag-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE
+include README.md
+include report.schema.json
+recursive-include audio_diag *.json

audio_diag-0.1.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: audio-diag
+Version: 0.1.0
+Summary: Stereo-master audio diagnostics with explicit reliability tiers (Level 1, Level 2, Level 3).
+Author: Adrián Cancio
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Dynamic: license-file
+
+# audio-diag
+
+Standalone Python CLI and library for stereo-master audio diagnostics with explicit reliability tiers. It operates completely offline, requires no external services or telemetry, and classifies measurements into three clear levels of trustworthiness.
+
+- **Level 1 (reliable):** BS.1770-4 / EBU R128 loudness (integrated, momentary max, short-term max, LRA), sample peak, true peak (4x polyphase Kaiser sinc oversampling), sample-level clipping runs, DC offset, leading and trailing silence, 8-band energy distribution, spectral slope, per-band stereo correlation and mono compatibility.
+- **Level 2 (heuristic hints):** Beat-window energy drops (dropouts vs. sustained breaks), kick-onset deviation from a BPM grid, section energy contrast, crest factor (global and FFT band projections). Always reported with `confidence: "heuristic"` and a warning; never treated as an automatic defect.
+- **Level 3 (not determinable from a stereo master):** Kick fundamental frequency, kick envelope, kick/rumble ratio, sub masking, musical key. Always reports `{"status": "not_determinable", "reason": ...}`. No estimators exist for these from mixed stereo audio.
+
+## Requirements
+
+- Python >= 3.12
+- `numpy`
+- `ffmpeg` and `ffprobe` installed and available on `PATH`
+
+System `ffmpeg` is used solely to decode audio into float32 PCM; all loudness, true-peak, spectral, and time-domain calculations are performed directly by audio-diag's internal NumPy implementation.
+
+## Installation
+
+Install via pip from source:
+
+```bash
+pip install .
+```
+
+For editable development:
+
+```bash
+pip install -e .
+```
+
+## CLI Usage
+
+The package installs the `audio-diag` executable and can also be run via `python3 -m audio_diag`.
+
+```bash
+# Analyze an audio file
+audio-diag analyze track.wav
+
+# Pass tempo and declare intentional arrangement decisions
+audio-diag analyze master.wav --bpm 155 --intent "break at bars 33-40" --intent "mono bass"
+
+# Export machine-readable JSON and human-readable Markdown
+audio-diag analyze master.wav --json report.json --md report.md
+
+# Inspect the bundled JSON Schema
+audio-diag schema
+```
+
+### Options
+
+```
+usage: audio_diag analyze [-h] [--bpm BPM] [--json OUT] [--md OUT]
+                          [--intent TEXT] [--target-lufs TARGET_LUFS]
+                          [--tolerance-lu TOLERANCE_LU] [--tp-max TP_MAX]
+                          [--silence-dbfs SILENCE_DBFS] [--drop-db DROP_DB]
+                          file
+```
+
+- `file`: Path to input audio file (opened strictly read-only).
+- `--bpm N`: Tempo in beats per minute; enables grid-aligned Level 2 onset hints.
+- `--json OUT`: Write formatted JSON report to `OUT` instead of stdout.
+- `--md OUT`: Write Markdown report to `OUT` instead of stderr.
+- `--intent TEXT`: Declare an intentional artistic choice (repeatable). Echoed in `intentional_decisions` and never reported as a defect.
+- `--target-lufs N`: Integrated loudness target in LUFS (default: `-8.0`).
+- `--tolerance-lu N`: Loudness tolerance in LU (default: `2.0`).
+- `--tp-max N`: Maximum true peak in dBTP (default: `-0.3`).
+- `--silence-dbfs N`: Threshold for digital silence detection (default: `-60.0`).
+- `--drop-db N`: Energy drop threshold for dropout/break detection (default: `6.0`).
+
+### Path Safety and Safeguards
+
+- The input file is opened strictly read-only (`O_RDONLY`).
+- The CLI refuses any output path that matches the input file (resolving symlinks and hardlinks).
+- The CLI refuses to write output inside protected directories:
+  - Standard user music directories (`~/Music`, `~/Música`).
+  - Directories configured via the `AUDIO_DIAG_PROTECTED_DIRS` environment variable (colon-separated).
+- Exit codes: `0` on success, `2` on invalid arguments, decoding failure, or unsafe output paths.
+
+## Python API
+
+```python
+from audio_diag import analyze, load_schema, to_markdown, DecodeError
+
+# Analyze an audio file
+try:
+    report = analyze("master.wav", bpm=158, intents=["break at bars 33-40"])
+except DecodeError as err:
+    print(f"Decoding failed: {err}")
+
+# Access Level 1 metrics
+loudness = report["level1"]["loudness"]
+print(f"Integrated LUFS: {loudness['integrated_lufs']}")
+print(f"True Peak dBTP:  {report['level1']['peaks']['true_peak_dbtp']}")
+
+# Render Markdown report
+md_text = to_markdown(report)
+
+# Load the JSON Schema definition
+schema = load_schema()
+```
+
+### Direct PCM Measurement
+
+Measure in-memory float32 PCM samples without decoding from disk:
+
+```python
+import numpy as np
+from audio_diag.loudness import measure
+
+# samples: 2D numpy array of shape (num_samples, channels)
+stats = measure(samples, sample_rate=48000)
+print(stats["integrated_lufs"], stats["true_peak_dbtp"])
+```
+
+### Spectral Profiles and Dispersion
+
+Compare relative spectral balance across tracks using gain-normalized power profiles:
+
+```python
+from audio_diag.profiles import profile, compare
+
+p1 = profile(analyze("track1.wav"))
+p2 = profile(analyze("track2.wav"))
+dispersion = compare([p1, p2])
+```
+
+Profiles normalize by total spectral power ($P_{band} / P_{total}$), canceling gain differences. Comparisons produce observed minimum and maximum envelopes per band rather than an artificial average or arbitrary pass/fail gate.
+
+## Schema & Report Invariants
+
+- Schema definition is bundled as `report.schema.json` and accessible via `audio_diag.load_schema()`.
+- Standard keys: `tool`, `version`, `file`, `thresholds`, `level1`, `level2`, `level3`, `intentional_decisions`, `warnings`, `verdicts`.
+- Finite JSON: values are never `NaN` or `inf`. Missing or invalid numbers are represented as `null` with an accompanying `<metric>_reason` explanation.
+- Lossy inputs (e.g. MP3, Opus, AAC) set `file.lossy_source: true`. True peak, crest factor, and absolute loudness are explicitly marked `"not valid for calibration (lossy source)"` because lossy codecs alter peaks and levels dynamically.
+
+## Metric Summary
+
+- **Loudness:** ITU-R BS.1770-4 / EBU R128 biquad K-weighting, 400 ms blocks with 75% overlap, -70 LUFS absolute and -10 LU relative gating. Maxima evaluated on a 10 ms grid. LRA uses 3 s windows, -20 LU relative gate, P10-P95 span.
+- **True Peak:** 4x polyphase Kaiser-windowed sinc oversampling filter (32 taps).
+- **Clipping:** Identifies consecutive runs of full-scale samples (`|x| >= 1.0 - 1e-6`) per channel.
+- **Bands:** Relative energy across 8 sub-bands computed via Hann-windowed periodogram (8192-point FFT, 50% overlap).
+- **Mono Compatibility:** Inter-channel correlation and mono energy ratio $10 \log_{10} \frac{E[((L+R)/2)^2]}{E[(L^2+R^2)/2]}$ per frequency band.
+
+## Testing
+
+The test suite runs with Python's standard `unittest`:
+
+```bash
+# Run the entire test suite
+python3 -m unittest discover
+
+# Run specific test modules
+python3 -m unittest tests.test_cli_robustness
+python3 -m unittest tests.test_corpus_expected
+python3 -m unittest tests.test_ebu_tech3341
+```
+
+- `test_corpus_expected`: Verifies measurements against analytically calculated mathematical ground truths (sine LUFS via K-weighting filter transfer function, pink noise LUFS via Parseval's theorem, exact clipping runs, synthesized click trains).
+- `test_ebu_tech3341`: Reconstructs EBU Tech 3341 compliance signals and asserts tolerances according to the specification ($\pm 0.1$ LU).
+- `test_ffmpeg_crosscheck`: Cross-checks loudness and true-peak results against system `ffmpeg -af ebur128=peak=true`.
+- `test_cli_robustness`: Verifies CLI exit codes, error handling, path traversal and overwrite protection, memory limits, and schema output.
+
+Test audio signals are generated deterministically in memory or temporary directories and are not committed to source control.
+
+## License
+
+MIT License. Copyright (c) 2026 Adrián Cancio / contributors. See `LICENSE` for details.

audio_diag-0.1.0/README.md

@@ -0,0 +1,167 @@
+# audio-diag
+
+Standalone Python CLI and library for stereo-master audio diagnostics with explicit reliability tiers. It operates completely offline, requires no external services or telemetry, and classifies measurements into three clear levels of trustworthiness.
+
+- **Level 1 (reliable):** BS.1770-4 / EBU R128 loudness (integrated, momentary max, short-term max, LRA), sample peak, true peak (4x polyphase Kaiser sinc oversampling), sample-level clipping runs, DC offset, leading and trailing silence, 8-band energy distribution, spectral slope, per-band stereo correlation and mono compatibility.
+- **Level 2 (heuristic hints):** Beat-window energy drops (dropouts vs. sustained breaks), kick-onset deviation from a BPM grid, section energy contrast, crest factor (global and FFT band projections). Always reported with `confidence: "heuristic"` and a warning; never treated as an automatic defect.
+- **Level 3 (not determinable from a stereo master):** Kick fundamental frequency, kick envelope, kick/rumble ratio, sub masking, musical key. Always reports `{"status": "not_determinable", "reason": ...}`. No estimators exist for these from mixed stereo audio.
+
+## Requirements
+
+- Python >= 3.12
+- `numpy`
+- `ffmpeg` and `ffprobe` installed and available on `PATH`
+
+System `ffmpeg` is used solely to decode audio into float32 PCM; all loudness, true-peak, spectral, and time-domain calculations are performed directly by audio-diag's internal NumPy implementation.
+
+## Installation
+
+Install via pip from source:
+
+```bash
+pip install .
+```
+
+For editable development:
+
+```bash
+pip install -e .
+```
+
+## CLI Usage
+
+The package installs the `audio-diag` executable and can also be run via `python3 -m audio_diag`.
+
+```bash
+# Analyze an audio file
+audio-diag analyze track.wav
+
+# Pass tempo and declare intentional arrangement decisions
+audio-diag analyze master.wav --bpm 155 --intent "break at bars 33-40" --intent "mono bass"
+
+# Export machine-readable JSON and human-readable Markdown
+audio-diag analyze master.wav --json report.json --md report.md
+
+# Inspect the bundled JSON Schema
+audio-diag schema
+```
+
+### Options
+
+```
+usage: audio_diag analyze [-h] [--bpm BPM] [--json OUT] [--md OUT]
+                          [--intent TEXT] [--target-lufs TARGET_LUFS]
+                          [--tolerance-lu TOLERANCE_LU] [--tp-max TP_MAX]
+                          [--silence-dbfs SILENCE_DBFS] [--drop-db DROP_DB]
+                          file
+```
+
+- `file`: Path to input audio file (opened strictly read-only).
+- `--bpm N`: Tempo in beats per minute; enables grid-aligned Level 2 onset hints.
+- `--json OUT`: Write formatted JSON report to `OUT` instead of stdout.
+- `--md OUT`: Write Markdown report to `OUT` instead of stderr.
+- `--intent TEXT`: Declare an intentional artistic choice (repeatable). Echoed in `intentional_decisions` and never reported as a defect.
+- `--target-lufs N`: Integrated loudness target in LUFS (default: `-8.0`).
+- `--tolerance-lu N`: Loudness tolerance in LU (default: `2.0`).
+- `--tp-max N`: Maximum true peak in dBTP (default: `-0.3`).
+- `--silence-dbfs N`: Threshold for digital silence detection (default: `-60.0`).
+- `--drop-db N`: Energy drop threshold for dropout/break detection (default: `6.0`).
+
+### Path Safety and Safeguards
+
+- The input file is opened strictly read-only (`O_RDONLY`).
+- The CLI refuses any output path that matches the input file (resolving symlinks and hardlinks).
+- The CLI refuses to write output inside protected directories:
+  - Standard user music directories (`~/Music`, `~/Música`).
+  - Directories configured via the `AUDIO_DIAG_PROTECTED_DIRS` environment variable (colon-separated).
+- Exit codes: `0` on success, `2` on invalid arguments, decoding failure, or unsafe output paths.
+
+## Python API
+
+```python
+from audio_diag import analyze, load_schema, to_markdown, DecodeError
+
+# Analyze an audio file
+try:
+    report = analyze("master.wav", bpm=158, intents=["break at bars 33-40"])
+except DecodeError as err:
+    print(f"Decoding failed: {err}")
+
+# Access Level 1 metrics
+loudness = report["level1"]["loudness"]
+print(f"Integrated LUFS: {loudness['integrated_lufs']}")
+print(f"True Peak dBTP:  {report['level1']['peaks']['true_peak_dbtp']}")
+
+# Render Markdown report
+md_text = to_markdown(report)
+
+# Load the JSON Schema definition
+schema = load_schema()
+```
+
+### Direct PCM Measurement
+
+Measure in-memory float32 PCM samples without decoding from disk:
+
+```python
+import numpy as np
+from audio_diag.loudness import measure
+
+# samples: 2D numpy array of shape (num_samples, channels)
+stats = measure(samples, sample_rate=48000)
+print(stats["integrated_lufs"], stats["true_peak_dbtp"])
+```
+
+### Spectral Profiles and Dispersion
+
+Compare relative spectral balance across tracks using gain-normalized power profiles:
+
+```python
+from audio_diag.profiles import profile, compare
+
+p1 = profile(analyze("track1.wav"))
+p2 = profile(analyze("track2.wav"))
+dispersion = compare([p1, p2])
+```
+
+Profiles normalize by total spectral power ($P_{band} / P_{total}$), canceling gain differences. Comparisons produce observed minimum and maximum envelopes per band rather than an artificial average or arbitrary pass/fail gate.
+
+## Schema & Report Invariants
+
+- Schema definition is bundled as `report.schema.json` and accessible via `audio_diag.load_schema()`.
+- Standard keys: `tool`, `version`, `file`, `thresholds`, `level1`, `level2`, `level3`, `intentional_decisions`, `warnings`, `verdicts`.
+- Finite JSON: values are never `NaN` or `inf`. Missing or invalid numbers are represented as `null` with an accompanying `<metric>_reason` explanation.
+- Lossy inputs (e.g. MP3, Opus, AAC) set `file.lossy_source: true`. True peak, crest factor, and absolute loudness are explicitly marked `"not valid for calibration (lossy source)"` because lossy codecs alter peaks and levels dynamically.
+
+## Metric Summary
+
+- **Loudness:** ITU-R BS.1770-4 / EBU R128 biquad K-weighting, 400 ms blocks with 75% overlap, -70 LUFS absolute and -10 LU relative gating. Maxima evaluated on a 10 ms grid. LRA uses 3 s windows, -20 LU relative gate, P10-P95 span.
+- **True Peak:** 4x polyphase Kaiser-windowed sinc oversampling filter (32 taps).
+- **Clipping:** Identifies consecutive runs of full-scale samples (`|x| >= 1.0 - 1e-6`) per channel.
+- **Bands:** Relative energy across 8 sub-bands computed via Hann-windowed periodogram (8192-point FFT, 50% overlap).
+- **Mono Compatibility:** Inter-channel correlation and mono energy ratio $10 \log_{10} \frac{E[((L+R)/2)^2]}{E[(L^2+R^2)/2]}$ per frequency band.
+
+## Testing
+
+The test suite runs with Python's standard `unittest`:
+
+```bash
+# Run the entire test suite
+python3 -m unittest discover
+
+# Run specific test modules
+python3 -m unittest tests.test_cli_robustness
+python3 -m unittest tests.test_corpus_expected
+python3 -m unittest tests.test_ebu_tech3341
+```
+
+- `test_corpus_expected`: Verifies measurements against analytically calculated mathematical ground truths (sine LUFS via K-weighting filter transfer function, pink noise LUFS via Parseval's theorem, exact clipping runs, synthesized click trains).
+- `test_ebu_tech3341`: Reconstructs EBU Tech 3341 compliance signals and asserts tolerances according to the specification ($\pm 0.1$ LU).
+- `test_ffmpeg_crosscheck`: Cross-checks loudness and true-peak results against system `ffmpeg -af ebur128=peak=true`.
+- `test_cli_robustness`: Verifies CLI exit codes, error handling, path traversal and overwrite protection, memory limits, and schema output.
+
+Test audio signals are generated deterministically in memory or temporary directories and are not committed to source control.
+
+## License
+
+MIT License. Copyright (c) 2026 Adrián Cancio / contributors. See `LICENSE` for details.

audio_diag-0.1.0/audio_diag/__init__.py

@@ -0,0 +1,12 @@
+"""audio_diag: stereo-master audio measurements in three reliability levels.
+
+Public API: analyze(path, bpm=None, intents=(), thresholds=None) -> dict,
+loudness.measure(samples, sample_rate), load_schema() -> dict, DecodeError.
+"""
+__version__ = '0.1.0'
+
+from .decode import DecodeError  # noqa: E402
+from .analyze import analyze, DEFAULT_THRESHOLDS  # noqa: E402
+from .report import load_schema, to_markdown  # noqa: E402
+
+__all__ = ['analyze', 'DecodeError', 'DEFAULT_THRESHOLDS', 'load_schema', 'to_markdown', '__version__']

audio_diag-0.1.0/audio_diag/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

audio_diag-0.1.0/audio_diag/analyze.py

@@ -0,0 +1,159 @@
+"""Public analysis entry point: analyze(path, ...) -> JSON-safe dict."""
+import math
+import os
+
+import numpy as np
+
+from . import __version__
+from . import decode, level2
+from .loudness import LoudnessMeter
+from .spectral import SpectrumAccumulator
+from .timedomain import DEFAULT_SILENCE_DBFS, TimeDomainAccumulator
+from .util import sanitize
+
+DEFAULT_THRESHOLDS = {
+    'target_lufs': -8.0,
+    'target_tolerance_lu': 2.0,
+    'true_peak_max_dbtp': -0.3,
+    'silence_dbfs': DEFAULT_SILENCE_DBFS,
+    'energy_drop_db': 6.0,
+}
+NOT_VALID = 'not valid for calibration (lossy source)'
+
+
+def analyze(path, bpm=None, intents=(), thresholds=None, chunk_frames=decode.CHUNK_FRAMES):
+    """Analyze an audio file (read-only). Returns a strict-JSON-safe dict.
+
+    Raises audio_diag.decode.DecodeError if the file cannot be decoded.
+    thresholds: optional dict overriding DEFAULT_THRESHOLDS keys.
+    """
+    th = dict(DEFAULT_THRESHOLDS)
+    th.update(thresholds or {})
+    if bpm is not None:
+        bpm = float(bpm)
+        if not (math.isfinite(bpm) and 20 <= bpm <= 400):
+            raise ValueError('bpm must be a finite number between 20 and 400')
+    intents = [str(i) for i in (intents or ())]
+    import hashlib
+    try:
+        with open(path, 'rb') as source:
+            sha256 = hashlib.file_digest(source, 'sha256').hexdigest()
+    except OSError as exc:
+        raise decode.DecodeError(f'cannot read input: {exc}') from exc
+    meta = decode.probe(path)
+    meta['sha256'] = sha256
+    warnings = []
+    src_ch = meta['channels']
+    ch = 1 if src_ch == 1 else 2
+    if src_ch > 2:
+        warnings.append(f'{src_ch}-channel source was downmixed to stereo by ffmpeg before analysis')
+    sr = meta['sample_rate']
+    loud = LoudnessMeter(sr, ch)
+    spec = SpectrumAccumulator(sr, ch)
+    td = TimeDomainAccumulator(sr, ch, th['silence_dbfs'])
+    feat = level2.FeatureAccumulator(sr)
+    for block in decode.stream(path, ch, warnings, chunk_frames):
+        loud.update(block)
+        spec.update(block)
+        td.update(block)
+        feat.update(block)
+    lm = loud.finish()
+    t = td.result()
+    duration = t['duration_s']
+    sp = spec.result()
+    lossy = bool(meta['lossy_source'])
+    meta = dict(meta)
+    meta['duration_s'] = duration  # decoded duration is authoritative
+    meta['analyzed_channels'] = ch
+    file = {'path': os.fspath(path), **meta}
+
+    loudness = {k: lm.get(k) for k in ('integrated_lufs', 'momentary_max_lufs', 'short_term_max_lufs', 'lra_lu')}
+    for k in list(loudness):
+        if lm.get(k + '_reason'):
+            loudness[k + '_reason'] = lm[k + '_reason']
+    loudness['definition'] = ('independent numpy BS.1770-4 / EBU R128: K-weighting, 400 ms blocks (75 % overlap), '
+                              '-70 LUFS absolute and -10 LU relative gates; LRA from 3 s blocks, -20 LU gate, '
+                              'P10-P95')
+    peaks = dict(t['peaks'])
+    peaks['true_peak_dbtp'] = lm['true_peak_dbtp']
+    if lm.get('true_peak_dbtp_reason'):
+        peaks['true_peak_dbtp_reason'] = lm['true_peak_dbtp_reason']
+    names = list(t['peaks']['per_channel'])
+    for n, v in zip(names, lm['true_peak_dbtp_per_channel']):
+        peaks['per_channel'][n]['true_peak_dbtp'] = v
+    peaks['true_peak_definition'] = '4x oversampled (polyphase Kaiser-windowed sinc, 32 taps) peak in dBTP'
+    if lossy:
+        loudness['validity'] = NOT_VALID
+        peaks['true_peak_validity'] = NOT_VALID
+    level1 = {
+        'loudness': loudness,
+        'peaks': peaks,
+        'dc_offset': t['dc_offset'],
+        'silence': t['silence'],
+        'clipping': t['clipping'],
+        'bands': {'definition': 'energy_db = band mean-square relative to the total of the full-range signal '
+                                '(L/R power averaged); energy_db_rel_max relative to the loudest band',
+                  'bands': sp['bands']},
+        'spectral_slope': sp['slope'],
+        'stereo': sp['stereo'] if sp['stereo'] else {
+            'status': 'not_applicable', 'reason': 'mono source: no stereo metrics'},
+    }
+    if t['nonfinite_samples']:
+        warnings.append(f"{t['nonfinite_samples']} non-finite samples were treated as 0")
+    if duration < 1.0:
+        warnings.append('file shorter than 1 s: gated loudness metrics may be unavailable')
+    if t['silence'].get('total_silent'):
+        warnings.append('file is silent (everything below the silence threshold)')
+    if lossy:
+        warnings.append('lossy source: true peak, crest factor and absolute loudness are ' + NOT_VALID)
+
+    l2 = level2.analyze_level2(feat, sr, bpm, {n: v['sample_peak_dbfs'] for n, v in t['peaks']['per_channel'].items()},
+                               t['rms_dbfs'], lossy, intents, drop_db=th['energy_drop_db'])
+    l2['crest_factor']['per_band_db'] = {
+        name: (20 * math.log10(spec.band_peak[name]) -
+               10 * math.log10(spec.band_square[name] / spec.band_samples))
+        if spec.band_square[name] > 1e-20 and spec.band_samples else None
+        for name in sp['bands']}
+    l2['crest_factor']['band_definition'] = ('Peak/RMS of brick-wall FFT band projections of '
+        '8192-sample Hann-windowed frames, 50% overlap, pooled channels; window and frame-boundary '
+        'effects make this heuristic, not equivalent to continuous bandpass filtering.')
+    powers = [10 ** (v / 10) for v in t['rms_dbfs'].values() if v is not None]
+    l2['crest_factor']['global_db'] = (peaks['sample_peak_dbfs'] - 10 * math.log10(sum(powers) / ch)
+        if powers and peaks['sample_peak_dbfs'] is not None else None)
+    if lossy:
+        l2['crest_factor']['validity'] = NOT_VALID
+    result = {
+        'tool': 'audio-diag', 'version': __version__, 'file': file,
+        'thresholds': th, 'level1': level1, 'level2': l2, 'level3': level2.level3(),
+        'intentional_decisions': [{'text': i, 'note': 'declared by the user; never reported as a defect'}
+                                  for i in intents],
+        'warnings': warnings,
+        'verdicts': _verdicts(level1, th, lossy),
+    }
+    return sanitize(result)
+
+
+def _verdicts(l1, th, lossy):
+    v = {}
+    i = l1['loudness']['integrated_lufs']
+    if i is None:
+        v['loudness_target'] = {'status': 'unknown', 'reason': l1['loudness'].get('integrated_lufs_reason',
+                                                                                  'no integrated loudness')}
+    else:
+        delta = i - th['target_lufs']
+        v['loudness_target'] = {'status': 'pass' if abs(delta) <= th['target_tolerance_lu'] else 'fail',
+                                'integrated_lufs': i, 'target_lufs': th['target_lufs'],
+                                'tolerance_lu': th['target_tolerance_lu'], 'delta_lu': delta}
+    tp = l1['peaks']['true_peak_dbtp']
+    if tp is None:
+        v['true_peak'] = {'status': 'unknown', 'reason': l1['peaks'].get('true_peak_dbtp_reason', 'silent')}
+    else:
+        v['true_peak'] = {'status': 'pass' if tp <= th['true_peak_max_dbtp'] else 'fail',
+                          'true_peak_dbtp': tp, 'max_dbtp': th['true_peak_max_dbtp']}
+    c = l1['clipping']
+    v['clipping'] = {'status': 'pass' if c['runs_min_len_2'] == 0 else 'fail',
+                     'runs_min_len_2': c['runs_min_len_2'], 'clipped_samples': c['clipped_samples']}
+    if lossy:
+        for k in ('loudness_target', 'true_peak'):
+            v[k]['note'] = NOT_VALID
+    return v

audio_diag-0.1.0/audio_diag/cli.py

@@ -0,0 +1,87 @@
+"""Command line: python3 -m audio_diag analyze FILE [options].
+
+stdout: JSON (or nothing when --json OUT is given); stderr: markdown report
+(or nothing when --md OUT is given). Exit 0 ok, 2 usage/decode/output error.
+"""
+import argparse
+import json
+import sys
+
+from .analyze import DEFAULT_THRESHOLDS, analyze
+from .decode import DecodeError
+from .report import load_schema, to_markdown
+from .safety import OutputRefused, check_output_path, write_text_atomic
+
+
+class _Parser(argparse.ArgumentParser):
+    def error(self, message):
+        self.print_usage(sys.stderr)
+        sys.stderr.write(f'audio_diag: error: {message}\n')
+        raise SystemExit(2)
+
+
+def build_parser():
+    p = _Parser(prog='audio_diag', description='Stereo-master audio diagnostics.')
+    sub = p.add_subparsers(dest='command', required=True)
+    a = sub.add_parser('analyze', help='analyze an audio file (read-only)')
+    a.add_argument('file')
+    a.add_argument('--bpm', type=float, help='tempo, enables bpm-dependent level-2 hints')
+    a.add_argument('--json', metavar='OUT', help='write JSON here instead of stdout')
+    a.add_argument('--md', metavar='OUT', help='write markdown here instead of stderr')
+    a.add_argument('--intent', action='append', default=[], metavar='TEXT',
+                   help='declare an intentional decision (repeatable); never reported as a defect')
+    a.add_argument('--target-lufs', type=float, default=DEFAULT_THRESHOLDS['target_lufs'])
+    a.add_argument('--tolerance-lu', type=float, default=DEFAULT_THRESHOLDS['target_tolerance_lu'])
+    a.add_argument('--tp-max', type=float, default=DEFAULT_THRESHOLDS['true_peak_max_dbtp'],
+                   help='maximum true peak in dBTP')
+    a.add_argument('--silence-dbfs', type=float, default=DEFAULT_THRESHOLDS['silence_dbfs'])
+    a.add_argument('--drop-db', type=float, default=DEFAULT_THRESHOLDS['energy_drop_db'])
+    sub.add_parser('schema', help='print report JSON schema')
+    return p
+
+
+def main(argv=None):
+    try:
+        args = build_parser().parse_args(argv)
+    except SystemExit as e:
+        return 2 if e.code not in (0, None) else 0
+    if args.command == 'schema':
+        schema = load_schema()
+        sys.stdout.write(json.dumps(schema, indent=2) + '\n')
+        return 0
+    try:
+        for out in (args.json, args.md):
+            if out:
+                check_output_path(out, args.file)
+        if args.json and args.md:
+            from os.path import realpath
+            if realpath(args.json) == realpath(args.md):
+                raise OutputRefused('--json and --md point at the same file')
+    except OutputRefused as exc:
+        sys.stderr.write(f'audio_diag: error: {exc}\n')
+        return 2
+    th = {'target_lufs': args.target_lufs, 'target_tolerance_lu': args.tolerance_lu,
+          'true_peak_max_dbtp': args.tp_max, 'silence_dbfs': args.silence_dbfs, 'energy_drop_db': args.drop_db}
+    try:
+        result = analyze(args.file, bpm=args.bpm, intents=args.intent, thresholds=th)
+    except DecodeError as exc:
+        sys.stderr.write(f'audio_diag: error: {exc}\n')
+        return 2
+    except ValueError as exc:
+        sys.stderr.write(f'audio_diag: error: {exc}\n')
+        return 2
+    text = json.dumps(result, indent=2, allow_nan=False, ensure_ascii=False) + '\n'
+    md = to_markdown(result)
+    try:
+        if args.json:
+            write_text_atomic(args.json, text, args.file)
+        else:
+            sys.stdout.write(text)
+        if args.md:
+            write_text_atomic(args.md, md, args.file)
+        else:
+            sys.stderr.write(md)
+    except (OutputRefused, OSError) as exc:
+        sys.stderr.write(f'audio_diag: error: cannot write output: {exc}\n')
+        return 2
+    return 0