umbr 0.1.0__tar.gz

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.
umbr-0.1.0/LICENSE ADDED
@@ -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.
umbr-0.1.0/PKG-INFO ADDED
@@ -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.
umbr-0.1.0/README.md ADDED
@@ -0,0 +1,145 @@
1
+ # umbr
2
+
3
+ Sub-audible, STFT-domain audio perturbation research console.
4
+
5
+ `umbr` (from *umbra*, the fully shadowed core of a shadow) takes an input track
6
+ and produces a transformed version that is intended to sound perceptually
7
+ identical to a human listener, while its machine-readable representation is
8
+ nudged away from the original. Every claim the tool makes about transparency,
9
+ representation divergence, and processing robustness is **measured** and written
10
+ to an audit report - nothing is asserted or simulated.
11
+
12
+ This is a research instrument for studying the tension between *inaudibility*
13
+ and *survivability under lossy processing*. It does **not** encode messages or
14
+ payloads: the perturbation is a deterministic, non-semantic sign lattice with no
15
+ recoverable content.
16
+
17
+ > Status: alpha / research prototype. Expect the honest finding that a
18
+ > perturbation quiet enough to be inaudible is largely erased by ordinary lossy
19
+ > compression. The point of the tool is to quantify that, not to hide it.
20
+
21
+ ## Installation
22
+
23
+ ```bash
24
+ pip install umbr
25
+ ```
26
+
27
+ `umbr` requires Python 3.12+ and depends on [NumPy](https://numpy.org/) (>= 2.0).
28
+
29
+ It also shells out to **FFmpeg** for decoding, codec round-trips, and duration
30
+ probing, so `ffmpeg` and `ffprobe` must be on your `PATH`
31
+ (<https://ffmpeg.org/download.html>). The optional fingerprint cross-check uses
32
+ the Chromaprint `fpcalc` binary if present
33
+ (<https://acoustid.org/chromaprint>); when it is missing the stage degrades
34
+ gracefully and says so in the audit.
35
+
36
+ ## Usage
37
+
38
+ The source track is required; everything else is derived or optional:
39
+
40
+ ```bash
41
+ # Output derives to <source-stem>.umbr.wav next to the source.
42
+ umbr song.flac
43
+
44
+ # Explicit output, a research-strength preset, first 60s only.
45
+ umbr song.flac -o out/song.umbr.wav --strength research --limit-seconds 60
46
+ ```
47
+
48
+ Key options (`umbr --help` for the full list):
49
+
50
+ | Option | Default | Meaning |
51
+ | --- | --- | --- |
52
+ | `source` | *(required)* | Input audio, any format FFmpeg can decode. |
53
+ | `-o, --output` | `<stem>.umbr.wav` | Rendered WAV. |
54
+ | `--delta-output` | `<output-stem>.delta_x60dB.wav` | Residual amplified +60 dB for spectrogram inspection. |
55
+ | `--artifacts` | `artifacts` | Directory for the CSV/JSON/Markdown audit. |
56
+ | `--strength` | `medium` | `conservative` / `medium` / `research` (quieter to louder). |
57
+ | `--n-fft` | `2048` | STFT window size (power of two, 512-8192). |
58
+ | `--hop` | `512` | STFT hop size. |
59
+ | `--sample-rate` | `44100` | Internal working rate (16000-96000). |
60
+ | `--limit-seconds` | `0` (full) | Process only the first N seconds. |
61
+
62
+ ## How it works
63
+
64
+ The pipeline mirrors the spec stages, all in the short-time Fourier domain.
65
+
66
+ 1. **Ingestion / normalization** - FFmpeg decodes the source to 16-bit PCM at
67
+ the working sample rate.
68
+ 2. **Spectrogram analysis** - a Hann-windowed
69
+ [Short-Time Fourier Transform](https://en.wikipedia.org/wiki/Short-time_Fourier_transform)
70
+ with overlap-add resynthesis (the
71
+ [Constant-OverLap-Add / COLA](https://www.dsprelated.com/freebooks/sasp/Overlap_Add_OLA_STFT_Processing.html)
72
+ condition keeps reconstruction transparent).
73
+ 3. **Psychoacoustic masking map** - a conservative
74
+ [simultaneous-masking](https://en.wikipedia.org/wiki/Auditory_masking) proxy
75
+ combining a near-masker threshold, an
76
+ [absolute-threshold-of-hearing](https://en.wikipedia.org/wiki/Absolute_threshold_of_hearing)
77
+ penalty, per-frame
78
+ [spectral flux](https://en.wikipedia.org/wiki/Spectral_flux) and
79
+ [spectral flatness](https://en.wikipedia.org/wiki/Spectral_flatness), and a
80
+ loudness estimate. Only dense, masked time-frequency regions are eligible.
81
+ 4. **Candidate perturbation** - a deterministic +/- lattice
82
+ ([NumPy PCG64 generator](https://numpy.org/doc/stable/reference/random/generator.html)),
83
+ phase-shifted a quarter turn from the host and scaled under the masking
84
+ budget.
85
+ 5. **Surrogate evaluation** - a small, explicitly labelled band-energy *proxy*
86
+ for an audio-analysis system. Divergence against it is suggestive, not
87
+ conclusive (see *Caveats*).
88
+ 6. **Robustness refinement** - the rendered probe is round-tripped through real
89
+ lossy codecs ([MP3 / LAME](https://lame.sourceforge.io/) and
90
+ [AAC](https://en.wikipedia.org/wiki/Advanced_Audio_Coding)) via FFmpeg and
91
+ re-measured, so robustness is observed rather than modelled.
92
+ 7. **Perceptual quality scoring** - residual RMS / peak in
93
+ [dBFS](https://en.wikipedia.org/wiki/DBFS), a
94
+ [log-spectral distance](https://en.wikipedia.org/wiki/Log-spectral_distance)
95
+ proxy, and a transparency gate that the refinement loop must satisfy.
96
+ 8. **Export** - the transformed WAV plus a +60 dB amplified residual WAV for
97
+ spectrogram inspection.
98
+ 9. **Human-listening verification** - the audit lists exactly which regions were
99
+ modified and why they were judged psychoacoustically safe, for blind ABX
100
+ listening.
101
+
102
+ ## Documented constants
103
+
104
+ All tunables live as documented module-level constants near the top of
105
+ `umbr.py`. The most important:
106
+
107
+ | Constant | Value | Reference |
108
+ | --- | --- | --- |
109
+ | `STRENGTH` presets (dB) | `-62 / -56 / -50` | dB relative to local host magnitude; see [dBFS](https://en.wikipedia.org/wiki/DBFS). |
110
+ | `TRANSPARENCY_GATE_DBFS` | `-85.0` | Residual RMS ceiling the refinement loop must meet. |
111
+ | `NEAR_MASKER_DB` | `-38.0` | Masking threshold below the per-frame peak ([auditory masking](https://en.wikipedia.org/wiki/Auditory_masking)). |
112
+ | `PERTURB_BAND_LOW/HIGH_HZ` | `120 / 15500` | Eligible band; avoids fragile sub-bass and codec-stripped air. |
113
+ | `ATH_PENALTY_*` | `0.40 / 0.70 / 0.55` | [Absolute threshold of hearing](https://en.wikipedia.org/wiki/Absolute_threshold_of_hearing) weighting. |
114
+ | `PERTURB_PHASE_OFFSET` | `pi / 2` | Quadrature offset from the host phase. |
115
+ | `SURROGATE_BAND_EDGES_HZ` | `80 .. 15500` | Log-band edges of the surrogate embedding. |
116
+ | `ROBUSTNESS_CODECS` | MP3 128k, AAC 128k | Codecs exercised by the robustness round-trip. |
117
+
118
+ `Strength` and `CoverType` are `enum.Enum` types rather than bare strings, so the
119
+ CLI choices, the dB levels, and the audit phrasing stay in sync.
120
+
121
+ ## Audit output
122
+
123
+ Written to the `--artifacts` directory:
124
+
125
+ - `umbr_audit.md` - human-readable report: transparency gates, surrogate
126
+ readout, codec robustness, and the top modified regions with their
127
+ psychoacoustic rationale.
128
+ - `umbr_metrics.json` - the full `Metrics` record.
129
+ - `umbr_regions.csv` - every modified STFT frame.
130
+ - `umbr_spectrogram_bins.csv` - the loudest modified bins for spectrogram
131
+ overlay.
132
+
133
+ ## Caveats
134
+
135
+ - The internal surrogate is **self-defined**; divergence against it does not
136
+ prove divergence against a real retrieval/fingerprinting system. Install
137
+ Chromaprint to enable the independent cross-check.
138
+ - Sub-audible energy is, by construction, the first thing lossy codecs discard,
139
+ so low surviving divergence is the expected result and is reported honestly.
140
+ - Exposed vocals, fades, and sparse instruments overrule every numeric score and
141
+ must be confirmed by blind listening.
142
+
143
+ ## License
144
+
145
+ MIT.
@@ -0,0 +1,86 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "umbr"
7
+ version = "0.1.0"
8
+ description = "Sub-audible STFT-domain audio perturbation research console."
9
+ readme = "README.md"
10
+ requires-python = ">=3.12"
11
+ license = "MIT"
12
+ license-files = ["LICENSE"]
13
+ authors = [{ name = "ra0x3", email = "ractz@pm.me" }]
14
+ keywords = [
15
+ "audio",
16
+ "psychoacoustics",
17
+ "stft",
18
+ "perturbation",
19
+ "robustness",
20
+ "research",
21
+ ]
22
+ classifiers = [
23
+ "Development Status :: 3 - Alpha",
24
+ "Intended Audience :: Science/Research",
25
+ "Programming Language :: Python :: 3.12",
26
+ "Topic :: Multimedia :: Sound/Audio :: Analysis",
27
+ "Topic :: Scientific/Engineering",
28
+ ]
29
+ dependencies = [
30
+ "numpy>=2.0",
31
+ ]
32
+
33
+ [project.urls]
34
+ Homepage = "https://github.com/ra0x3/umbr"
35
+ Documentation = "https://github.com/ra0x3/umbr#readme"
36
+ Repository = "https://github.com/ra0x3/umbr"
37
+
38
+ [project.scripts]
39
+ umbr = "umbr:cli"
40
+
41
+ [tool.setuptools]
42
+ py-modules = ["umbr"]
43
+
44
+ [dependency-groups]
45
+ dev = [
46
+ "mypy>=1.0",
47
+ "pylint>=3.0",
48
+ "build>=1.0",
49
+ "twine>=5.0",
50
+ ]
51
+
52
+ [tool.mypy]
53
+ python_version = "3.12"
54
+ strict = true
55
+
56
+ [tool.pylint.format]
57
+ max-line-length = 100
58
+
59
+ [tool.pylint.design]
60
+ # Metrics is a plain whole-render data record whose fields are inherent to the
61
+ # audit it serializes; splitting it would obscure rather than clarify.
62
+ max-attributes = 24
63
+ # The DSP/metrics functions carry a handful of named intermediate arrays
64
+ # (spectra, features, displacements) whose names document the math; inlining
65
+ # them to satisfy the default 20 would hurt readability, not help it.
66
+ max-locals = 25
67
+
68
+ [tool.pylint.main]
69
+ # The project is intentionally a single, fully documented module per the
70
+ # design brief; the line count reflects that choice, not tangled code.
71
+ max-module-lines = 1500
72
+
73
+ [tool.pylint."messages control"]
74
+ # Suppressed false positives only:
75
+ # no-member -- pylint cannot infer that ``wave.open(path, "wb")``
76
+ # returns a Wave_write (it assumes Wave_read), so every
77
+ # set*/writeframes call is mis-flagged.
78
+ # too-many-* args -- StftConfig/LatticeContext already bundle the shared
79
+ # parameters; the few remaining wide signatures pass a
80
+ # config plus distinct, non-groupable values and are
81
+ # clearer flat than wrapped in yet another record.
82
+ disable = [
83
+ "no-member",
84
+ "too-many-arguments",
85
+ "too-many-positional-arguments",
86
+ ]
umbr-0.1.0/setup.cfg ADDED
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -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,10 @@
1
+ LICENSE
2
+ README.md
3
+ pyproject.toml
4
+ umbr.py
5
+ umbr.egg-info/PKG-INFO
6
+ umbr.egg-info/SOURCES.txt
7
+ umbr.egg-info/dependency_links.txt
8
+ umbr.egg-info/entry_points.txt
9
+ umbr.egg-info/requires.txt
10
+ umbr.egg-info/top_level.txt
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ umbr = umbr:cli
@@ -0,0 +1 @@
1
+ numpy>=2.0
@@ -0,0 +1 @@
1
+ umbr