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 +21 -0
- umbr-0.1.0/PKG-INFO +166 -0
- umbr-0.1.0/README.md +145 -0
- umbr-0.1.0/pyproject.toml +86 -0
- umbr-0.1.0/setup.cfg +4 -0
- umbr-0.1.0/umbr.egg-info/PKG-INFO +166 -0
- umbr-0.1.0/umbr.egg-info/SOURCES.txt +10 -0
- umbr-0.1.0/umbr.egg-info/dependency_links.txt +1 -0
- umbr-0.1.0/umbr.egg-info/entry_points.txt +2 -0
- umbr-0.1.0/umbr.egg-info/requires.txt +1 -0
- umbr-0.1.0/umbr.egg-info/top_level.txt +1 -0
- umbr-0.1.0/umbr.py +1363 -0
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,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 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
numpy>=2.0
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
umbr
|