vndecorrelate 1.0.0__tar.gz

vndecorrelate-1.0.0/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+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 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.
+
+For more information, please refer to <http://unlicense.org/>

vndecorrelate-1.0.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: vndecorrelate
+Version: 1.0.0
+Summary: A Velvet-Noise Decorrelator for audio
+Author-email: Christian Konstantinov <ckonst98@gmail.com>
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib>=3.10.3
+Requires-Dist: numpy>=2.3.1
+Requires-Dist: pillow==12.2.0
+Requires-Dist: scipy>=1.16.0
+Dynamic: license-file
+
+# VNDecorrelate
+![Version](https://img.shields.io/badge/version-1.0.0-blue?style=for-the-badge)[![PyPI](https://img.shields.io/pypi/pyversions/vndecorrelate?style=for-the-badge)](https://pypi.org/project/vndecorrelate)![Tests](https://img.shields.io/github/actions/workflow/status/ckonst/VNDecorrelate/test-vnd.yaml?style=for-the-badge)
+
+A Velvet-Noise Decorrelator for audio.
+
+Decorrelation refers to the process of transforming an audio source signal into multiple output signals with different waveforms from each other, but with the same sound as the source signal [[1]](#1).
+
+In music production, decorrelation is typically applied to the left and right audio channels, creating the perception of stereo width and space. This, however, may come at the cost of potential coloration or transient smearing artifacts. 
+
+Velvet-Noise Decorrelation (VND) attempts to minimize these artifacts as well as computation cost while reducing the correlation of the outputs as much as possible [[2]](#2).
+
+## Velvet Noise
+
+Velvet Noise is a sparse noise sequence generated from randomly time-shifted impulses with a random value of either -1 or 1 [[2]](#2):
+
+![Basic Velvet Noise](tests/plots/Basic%20Velvet%20Noise%20Sequence.png)
+
+To reduce transient smearing and frequency coloration you can apply a segmented decay envelope [[2]](#2):
+
+![Segmented Decaying Velvet Noise](tests/plots/Segmented%20Decaying%20Velvet%20Noise%20Sequence.png)
+
+As well as logarithmically distributing the impulses towards the start of the sequence [[2]](#2):
+
+![Segmented Decaying Log Distributed Velvet Noise](tests/plots/Segmented%20Decaying%20Log%20Distributed%20Velvet%20Noise%20Sequence.png)
+
+## Quick Start
+
+First install the package into your environment:
+```pip install vndecorrelate```
+
+Then load an audio file.
+
+```python
+import scipy.io.wavfile as wavfile
+from vndecorrelate.decorrelation import *
+
+fs, input_signal = wavfile.read("audio/viola.wav")
+```
+
+Then you can simply use the `VelvetNoise` class:
+
+```python
+velvet_noise = VelvetNoise(
+    duration_seconds=0.03,
+    num_impulses=30,
+)
+output_signal = velvet_noise.decorrelate(input_signal)
+```
+Or:
+
+```python
+# manually generate the velvet noise as numpy NDArrays
+velvet_noise = generate_velvet_noise(
+    duration_seconds=0.03,
+    num_impulses=30,
+)
+# numerically equivalent to VelvetNoise.convolve
+output_signal = convolve_velvet_noise(input_signal, velvet_noise)
+```
+
+Or you can create a chain of signal processors:
+
+```python
+chain = (
+    SignalChain(sample_rate_hz=fs)
+    .velvet_noise(
+        duration_seconds=0.03,
+        num_impulses=30,
+        log_distribution_strength=1.0,
+        seed=1,
+    )
+    .haas_effect(
+        delay_time_seconds=0.02,
+        delayed_channel=1, # Right Channel
+        mode='LR',
+    )
+)
+# SignalChain is lazy, so instatiation of its signal processors happens here
+output_signal = chain(input_signal)
+```
+To listen back to the processed audio, simply save to a wav file locally.
+
+```python
+wavfile.write('audio/viola_out.wav', fs, output_signal)
+```
+
+## Optimization
+`optimization.py` contains functions for optimizing `VelvetNoise` or `HaasEffect` for maximizing stereo seperation while maintaining polar sample symmetry and mono compatiblilty.
+
+`optimize_velvet_noise` optimizes the concentration of impulses towards the start of the filter: $\kappa \in [0.0, 1.0]$, referred to as `log_distribution_strength`.
+
+`optimize_haas_delay` optimizes the `delay_time_seconds` parameter: $\tau \in [0.0, \text{max\\_delay\\_seconds}]$
+
+`symmetry_aware_objective` takes the input signal and converts it to polar samples to compute the scalar objective function defined by:
+
+$f(\alpha) = E_w[\theta^2] - \lambda_1(E_w[\theta])^2 - \lambda_2(E_w[\theta^3])^2  - \lambda_3r^2 - \lambda_4(max|{\theta}| - \phi)^2$
+
+where $\alpha$ is the input scalar to optimize, each $E_w[\theta^n]$ is a moment of the polar sample distribution: $E_w[\theta^2]$ is the weighted angular variance, $(E_w[\theta])^2$ is the weighted mean (centroid), and $(E_w[\theta^3])^2$ is the skewness. $r$ is the correlation between the input left and right channels, $\phi$ is the `angle_limit` parameter, and each $\lambda_n$ is a penalty weight.
+
+Sample runs of `VelvetNoise.decorrelate` with unoptimized and optimized filters can be compared by their polar sample plots generated from `plot_polar_sample`:
+
+![Unoptimized VN Vectorscope](tests/plots/Unoptimized%20VN%20Vectorscope.png)
+![VN Optimized Vectorscope](tests/plots/VN%20Optimized%20Vectorscope.png)
+
+## Visualization
+To provide further visualization of the effects decorrelation `plot_correlogram` is provided. Short windows of typically ~20ms are taken from two signals to calculate normalized cross-correlation values at various lag distances. `sine_sweep` can be used to generate a test signal that can be compared before and after applying a velvet noise decorrelation.
+![Sine Sweep Signal](tests/plots/Sine%20Sweep%20Signal.png)
+We can use the auto correlogram as a baseline:
+![Sine Sweep Auto Correlogram](tests/plots/Sine%20Sweep%20Auto%20Correlogram.png)
+Plot the cross correlogram after filtering each channel with velvet noise:
+![Velvet Noise Filtered Sine Sweep Cross Correlogram](tests/plots/Velvet%20Noise%20Filtered%20Sine%20Sweep%20Cross%20Correlogram.png)
+And compare to the behavior of filtering with white noise:
+![White Noise Filtered Sine Sweep Cross Correlogram](tests/plots/White%20Noise%20Filtered%20Sine%20Sweep%20Cross%20Correlogram.png)
+
+## References
+<a id="1"> </a>
+[1] “What is ‘Decorrelation’? | Sweetwater”. <a
+    href="https://www.sweetwater.com/insync/decorrelation/">
+    https://www.sweetwater.com/insync/decorrelation/</a> (accessed Aug. 10, 2020).
+
+<a id="2"> </a>
+    [2] “Velvet-Noise Decorrelator”. <a
+        href="http://www.dafx17.eca.ed.ac.uk/papers/DAFx17_paper_96.pdf">
+        http://www.dafx17.eca.ed.ac.uk/papers/DAFx17_paper_96.pdf</a> (accessed Aug. 04, 2020).

vndecorrelate-1.0.0/README.md

@@ -0,0 +1,124 @@
+# VNDecorrelate
+![Version](https://img.shields.io/badge/version-1.0.0-blue?style=for-the-badge)[![PyPI](https://img.shields.io/pypi/pyversions/vndecorrelate?style=for-the-badge)](https://pypi.org/project/vndecorrelate)![Tests](https://img.shields.io/github/actions/workflow/status/ckonst/VNDecorrelate/test-vnd.yaml?style=for-the-badge)
+
+A Velvet-Noise Decorrelator for audio.
+
+Decorrelation refers to the process of transforming an audio source signal into multiple output signals with different waveforms from each other, but with the same sound as the source signal [[1]](#1).
+
+In music production, decorrelation is typically applied to the left and right audio channels, creating the perception of stereo width and space. This, however, may come at the cost of potential coloration or transient smearing artifacts. 
+
+Velvet-Noise Decorrelation (VND) attempts to minimize these artifacts as well as computation cost while reducing the correlation of the outputs as much as possible [[2]](#2).
+
+## Velvet Noise
+
+Velvet Noise is a sparse noise sequence generated from randomly time-shifted impulses with a random value of either -1 or 1 [[2]](#2):
+
+![Basic Velvet Noise](tests/plots/Basic%20Velvet%20Noise%20Sequence.png)
+
+To reduce transient smearing and frequency coloration you can apply a segmented decay envelope [[2]](#2):
+
+![Segmented Decaying Velvet Noise](tests/plots/Segmented%20Decaying%20Velvet%20Noise%20Sequence.png)
+
+As well as logarithmically distributing the impulses towards the start of the sequence [[2]](#2):
+
+![Segmented Decaying Log Distributed Velvet Noise](tests/plots/Segmented%20Decaying%20Log%20Distributed%20Velvet%20Noise%20Sequence.png)
+
+## Quick Start
+
+First install the package into your environment:
+```pip install vndecorrelate```
+
+Then load an audio file.
+
+```python
+import scipy.io.wavfile as wavfile
+from vndecorrelate.decorrelation import *
+
+fs, input_signal = wavfile.read("audio/viola.wav")
+```
+
+Then you can simply use the `VelvetNoise` class:
+
+```python
+velvet_noise = VelvetNoise(
+    duration_seconds=0.03,
+    num_impulses=30,
+)
+output_signal = velvet_noise.decorrelate(input_signal)
+```
+Or:
+
+```python
+# manually generate the velvet noise as numpy NDArrays
+velvet_noise = generate_velvet_noise(
+    duration_seconds=0.03,
+    num_impulses=30,
+)
+# numerically equivalent to VelvetNoise.convolve
+output_signal = convolve_velvet_noise(input_signal, velvet_noise)
+```
+
+Or you can create a chain of signal processors:
+
+```python
+chain = (
+    SignalChain(sample_rate_hz=fs)
+    .velvet_noise(
+        duration_seconds=0.03,
+        num_impulses=30,
+        log_distribution_strength=1.0,
+        seed=1,
+    )
+    .haas_effect(
+        delay_time_seconds=0.02,
+        delayed_channel=1, # Right Channel
+        mode='LR',
+    )
+)
+# SignalChain is lazy, so instatiation of its signal processors happens here
+output_signal = chain(input_signal)
+```
+To listen back to the processed audio, simply save to a wav file locally.
+
+```python
+wavfile.write('audio/viola_out.wav', fs, output_signal)
+```
+
+## Optimization
+`optimization.py` contains functions for optimizing `VelvetNoise` or `HaasEffect` for maximizing stereo seperation while maintaining polar sample symmetry and mono compatiblilty.
+
+`optimize_velvet_noise` optimizes the concentration of impulses towards the start of the filter: $\kappa \in [0.0, 1.0]$, referred to as `log_distribution_strength`.
+
+`optimize_haas_delay` optimizes the `delay_time_seconds` parameter: $\tau \in [0.0, \text{max\\_delay\\_seconds}]$
+
+`symmetry_aware_objective` takes the input signal and converts it to polar samples to compute the scalar objective function defined by:
+
+$f(\alpha) = E_w[\theta^2] - \lambda_1(E_w[\theta])^2 - \lambda_2(E_w[\theta^3])^2  - \lambda_3r^2 - \lambda_4(max|{\theta}| - \phi)^2$
+
+where $\alpha$ is the input scalar to optimize, each $E_w[\theta^n]$ is a moment of the polar sample distribution: $E_w[\theta^2]$ is the weighted angular variance, $(E_w[\theta])^2$ is the weighted mean (centroid), and $(E_w[\theta^3])^2$ is the skewness. $r$ is the correlation between the input left and right channels, $\phi$ is the `angle_limit` parameter, and each $\lambda_n$ is a penalty weight.
+
+Sample runs of `VelvetNoise.decorrelate` with unoptimized and optimized filters can be compared by their polar sample plots generated from `plot_polar_sample`:
+
+![Unoptimized VN Vectorscope](tests/plots/Unoptimized%20VN%20Vectorscope.png)
+![VN Optimized Vectorscope](tests/plots/VN%20Optimized%20Vectorscope.png)
+
+## Visualization
+To provide further visualization of the effects decorrelation `plot_correlogram` is provided. Short windows of typically ~20ms are taken from two signals to calculate normalized cross-correlation values at various lag distances. `sine_sweep` can be used to generate a test signal that can be compared before and after applying a velvet noise decorrelation.
+![Sine Sweep Signal](tests/plots/Sine%20Sweep%20Signal.png)
+We can use the auto correlogram as a baseline:
+![Sine Sweep Auto Correlogram](tests/plots/Sine%20Sweep%20Auto%20Correlogram.png)
+Plot the cross correlogram after filtering each channel with velvet noise:
+![Velvet Noise Filtered Sine Sweep Cross Correlogram](tests/plots/Velvet%20Noise%20Filtered%20Sine%20Sweep%20Cross%20Correlogram.png)
+And compare to the behavior of filtering with white noise:
+![White Noise Filtered Sine Sweep Cross Correlogram](tests/plots/White%20Noise%20Filtered%20Sine%20Sweep%20Cross%20Correlogram.png)
+
+## References
+<a id="1"> </a>
+[1] “What is ‘Decorrelation’? | Sweetwater”. <a
+    href="https://www.sweetwater.com/insync/decorrelation/">
+    https://www.sweetwater.com/insync/decorrelation/</a> (accessed Aug. 10, 2020).
+
+<a id="2"> </a>
+    [2] “Velvet-Noise Decorrelator”. <a
+        href="http://www.dafx17.eca.ed.ac.uk/papers/DAFx17_paper_96.pdf">
+        http://www.dafx17.eca.ed.ac.uk/papers/DAFx17_paper_96.pdf</a> (accessed Aug. 04, 2020).

vndecorrelate-1.0.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "vndecorrelate"
+version = "1.0.0"
+description = "A Velvet-Noise Decorrelator for audio"
+readme = "README.md"
+requires-python = ">=3.12"
+authors = [
+    { name = "Christian Konstantinov", email = "ckonst98@gmail.com" }
+]
+
+dependencies = [
+    "matplotlib>=3.10.3",
+    "numpy>=2.3.1",
+    "pillow==12.2.0",
+    "scipy>=1.16.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "ruff>=0.12.1",
+    "snakeviz>=2.2.2",
+]
+
+[tool.ruff]
+exclude = [".venv"]
+fix = true
+
+[tool.ruff.format]
+quote-style = "single"
+
+[tool.ruff.lint.flake8-quotes]
+docstring-quotes = "single"
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"

vndecorrelate-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vndecorrelate-1.0.0/src/vndecorrelate/__init__.py

@@ -0,0 +1 @@
+__version__ = '0.0.0'