umbr 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,166 @@
1
+ Metadata-Version: 2.4
2
+ Name: umbr
3
+ Version: 0.1.0
4
+ Summary: Sub-audible STFT-domain audio perturbation research console.
5
+ Author-email: ra0x3 <ractz@pm.me>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/ra0x3/umbr
8
+ Project-URL: Documentation, https://github.com/ra0x3/umbr#readme
9
+ Project-URL: Repository, https://github.com/ra0x3/umbr
10
+ Keywords: audio,psychoacoustics,stft,perturbation,robustness,research
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Intended Audience :: Science/Research
13
+ Classifier: Programming Language :: Python :: 3.12
14
+ Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
15
+ Classifier: Topic :: Scientific/Engineering
16
+ Requires-Python: >=3.12
17
+ Description-Content-Type: text/markdown
18
+ License-File: LICENSE
19
+ Requires-Dist: numpy>=2.0
20
+ Dynamic: license-file
21
+
22
+ # umbr
23
+
24
+ Sub-audible, STFT-domain audio perturbation research console.
25
+
26
+ `umbr` (from *umbra*, the fully shadowed core of a shadow) takes an input track
27
+ and produces a transformed version that is intended to sound perceptually
28
+ identical to a human listener, while its machine-readable representation is
29
+ nudged away from the original. Every claim the tool makes about transparency,
30
+ representation divergence, and processing robustness is **measured** and written
31
+ to an audit report - nothing is asserted or simulated.
32
+
33
+ This is a research instrument for studying the tension between *inaudibility*
34
+ and *survivability under lossy processing*. It does **not** encode messages or
35
+ payloads: the perturbation is a deterministic, non-semantic sign lattice with no
36
+ recoverable content.
37
+
38
+ > Status: alpha / research prototype. Expect the honest finding that a
39
+ > perturbation quiet enough to be inaudible is largely erased by ordinary lossy
40
+ > compression. The point of the tool is to quantify that, not to hide it.
41
+
42
+ ## Installation
43
+
44
+ ```bash
45
+ pip install umbr
46
+ ```
47
+
48
+ `umbr` requires Python 3.12+ and depends on [NumPy](https://numpy.org/) (>= 2.0).
49
+
50
+ It also shells out to **FFmpeg** for decoding, codec round-trips, and duration
51
+ probing, so `ffmpeg` and `ffprobe` must be on your `PATH`
52
+ (<https://ffmpeg.org/download.html>). The optional fingerprint cross-check uses
53
+ the Chromaprint `fpcalc` binary if present
54
+ (<https://acoustid.org/chromaprint>); when it is missing the stage degrades
55
+ gracefully and says so in the audit.
56
+
57
+ ## Usage
58
+
59
+ The source track is required; everything else is derived or optional:
60
+
61
+ ```bash
62
+ # Output derives to <source-stem>.umbr.wav next to the source.
63
+ umbr song.flac
64
+
65
+ # Explicit output, a research-strength preset, first 60s only.
66
+ umbr song.flac -o out/song.umbr.wav --strength research --limit-seconds 60
67
+ ```
68
+
69
+ Key options (`umbr --help` for the full list):
70
+
71
+ | Option | Default | Meaning |
72
+ | --- | --- | --- |
73
+ | `source` | *(required)* | Input audio, any format FFmpeg can decode. |
74
+ | `-o, --output` | `<stem>.umbr.wav` | Rendered WAV. |
75
+ | `--delta-output` | `<output-stem>.delta_x60dB.wav` | Residual amplified +60 dB for spectrogram inspection. |
76
+ | `--artifacts` | `artifacts` | Directory for the CSV/JSON/Markdown audit. |
77
+ | `--strength` | `medium` | `conservative` / `medium` / `research` (quieter to louder). |
78
+ | `--n-fft` | `2048` | STFT window size (power of two, 512-8192). |
79
+ | `--hop` | `512` | STFT hop size. |
80
+ | `--sample-rate` | `44100` | Internal working rate (16000-96000). |
81
+ | `--limit-seconds` | `0` (full) | Process only the first N seconds. |
82
+
83
+ ## How it works
84
+
85
+ The pipeline mirrors the spec stages, all in the short-time Fourier domain.
86
+
87
+ 1. **Ingestion / normalization** - FFmpeg decodes the source to 16-bit PCM at
88
+ the working sample rate.
89
+ 2. **Spectrogram analysis** - a Hann-windowed
90
+ [Short-Time Fourier Transform](https://en.wikipedia.org/wiki/Short-time_Fourier_transform)
91
+ with overlap-add resynthesis (the
92
+ [Constant-OverLap-Add / COLA](https://www.dsprelated.com/freebooks/sasp/Overlap_Add_OLA_STFT_Processing.html)
93
+ condition keeps reconstruction transparent).
94
+ 3. **Psychoacoustic masking map** - a conservative
95
+ [simultaneous-masking](https://en.wikipedia.org/wiki/Auditory_masking) proxy
96
+ combining a near-masker threshold, an
97
+ [absolute-threshold-of-hearing](https://en.wikipedia.org/wiki/Absolute_threshold_of_hearing)
98
+ penalty, per-frame
99
+ [spectral flux](https://en.wikipedia.org/wiki/Spectral_flux) and
100
+ [spectral flatness](https://en.wikipedia.org/wiki/Spectral_flatness), and a
101
+ loudness estimate. Only dense, masked time-frequency regions are eligible.
102
+ 4. **Candidate perturbation** - a deterministic +/- lattice
103
+ ([NumPy PCG64 generator](https://numpy.org/doc/stable/reference/random/generator.html)),
104
+ phase-shifted a quarter turn from the host and scaled under the masking
105
+ budget.
106
+ 5. **Surrogate evaluation** - a small, explicitly labelled band-energy *proxy*
107
+ for an audio-analysis system. Divergence against it is suggestive, not
108
+ conclusive (see *Caveats*).
109
+ 6. **Robustness refinement** - the rendered probe is round-tripped through real
110
+ lossy codecs ([MP3 / LAME](https://lame.sourceforge.io/) and
111
+ [AAC](https://en.wikipedia.org/wiki/Advanced_Audio_Coding)) via FFmpeg and
112
+ re-measured, so robustness is observed rather than modelled.
113
+ 7. **Perceptual quality scoring** - residual RMS / peak in
114
+ [dBFS](https://en.wikipedia.org/wiki/DBFS), a
115
+ [log-spectral distance](https://en.wikipedia.org/wiki/Log-spectral_distance)
116
+ proxy, and a transparency gate that the refinement loop must satisfy.
117
+ 8. **Export** - the transformed WAV plus a +60 dB amplified residual WAV for
118
+ spectrogram inspection.
119
+ 9. **Human-listening verification** - the audit lists exactly which regions were
120
+ modified and why they were judged psychoacoustically safe, for blind ABX
121
+ listening.
122
+
123
+ ## Documented constants
124
+
125
+ All tunables live as documented module-level constants near the top of
126
+ `umbr.py`. The most important:
127
+
128
+ | Constant | Value | Reference |
129
+ | --- | --- | --- |
130
+ | `STRENGTH` presets (dB) | `-62 / -56 / -50` | dB relative to local host magnitude; see [dBFS](https://en.wikipedia.org/wiki/DBFS). |
131
+ | `TRANSPARENCY_GATE_DBFS` | `-85.0` | Residual RMS ceiling the refinement loop must meet. |
132
+ | `NEAR_MASKER_DB` | `-38.0` | Masking threshold below the per-frame peak ([auditory masking](https://en.wikipedia.org/wiki/Auditory_masking)). |
133
+ | `PERTURB_BAND_LOW/HIGH_HZ` | `120 / 15500` | Eligible band; avoids fragile sub-bass and codec-stripped air. |
134
+ | `ATH_PENALTY_*` | `0.40 / 0.70 / 0.55` | [Absolute threshold of hearing](https://en.wikipedia.org/wiki/Absolute_threshold_of_hearing) weighting. |
135
+ | `PERTURB_PHASE_OFFSET` | `pi / 2` | Quadrature offset from the host phase. |
136
+ | `SURROGATE_BAND_EDGES_HZ` | `80 .. 15500` | Log-band edges of the surrogate embedding. |
137
+ | `ROBUSTNESS_CODECS` | MP3 128k, AAC 128k | Codecs exercised by the robustness round-trip. |
138
+
139
+ `Strength` and `CoverType` are `enum.Enum` types rather than bare strings, so the
140
+ CLI choices, the dB levels, and the audit phrasing stay in sync.
141
+
142
+ ## Audit output
143
+
144
+ Written to the `--artifacts` directory:
145
+
146
+ - `umbr_audit.md` - human-readable report: transparency gates, surrogate
147
+ readout, codec robustness, and the top modified regions with their
148
+ psychoacoustic rationale.
149
+ - `umbr_metrics.json` - the full `Metrics` record.
150
+ - `umbr_regions.csv` - every modified STFT frame.
151
+ - `umbr_spectrogram_bins.csv` - the loudest modified bins for spectrogram
152
+ overlay.
153
+
154
+ ## Caveats
155
+
156
+ - The internal surrogate is **self-defined**; divergence against it does not
157
+ prove divergence against a real retrieval/fingerprinting system. Install
158
+ Chromaprint to enable the independent cross-check.
159
+ - Sub-audible energy is, by construction, the first thing lossy codecs discard,
160
+ so low surviving divergence is the expected result and is reported honestly.
161
+ - Exposed vocals, fades, and sparse instruments overrule every numeric score and
162
+ must be confirmed by blind listening.
163
+
164
+ ## License
165
+
166
+ MIT.
@@ -0,0 +1,7 @@
1
+ umbr.py,sha256=1QobEffOTmPiiA-UXq_n0w9YgObDnwatPfcy9CAWhU0,51569
2
+ umbr-0.1.0.dist-info/licenses/LICENSE,sha256=qAhPSLICBglWX3CqbA2oocNmcqYYuxNdvJNK1vYlVUI,1072
3
+ umbr-0.1.0.dist-info/METADATA,sha256=qM7BD8XTHPor8-I3dCtJjRCgW7VYwbZuBTGPa2XeORw,7827
4
+ umbr-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
5
+ umbr-0.1.0.dist-info/entry_points.txt,sha256=Q7LGw2UsV-FpxdiNR_BiN_Hm71ba_hcROSMO_TGjwvw,34
6
+ umbr-0.1.0.dist-info/top_level.txt,sha256=kSqChHWCRODaIM5YN7qdcbdQws9grF6RzYSXNOKAPoI,5
7
+ umbr-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (82.0.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ umbr = umbr:cli
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Stonehedge Labs
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1 @@
1
+ umbr