Fast spectrogram phase reconstruction using Local Weighted Sums

## Project description

LWS

===

**Fast spectrogram phase recovery using Local Weighted Sums (LWS)**

Author: Jonathan Le Roux -- 2008-2018

.. image:: https://badge.fury.io/py/lws.svg

:target: https://badge.fury.io/py/lws

| LWS is a C/C++ library for which this package is a Python wrapper.

| A Matlab/Mex wrapper is also available.

License

-------

| Copyright (C) 2008-2018 Jonathan Le Roux

| Apache 2.0 (http://www.apache.org/licenses/LICENSE-2.0)

Reference

---------

If you use this code, please cite the following papers.

Batch LWS

~~~~~~~~~

| Jonathan Le Roux, Hirokazu Kameoka, Nobutaka Ono, Shigeki Sagayama,

| "Fast Signal Reconstruction from Magnitude STFT Spectrogram Based on Spectrogram Consistency,"

| in Proc. International Conference on Digital Audio Effects (DAFx), pp. 397--403, Sep. 2010.

.. code::

@InProceedings{LeRoux2010DAFx09,

author = {Jonathan {Le Roux} and Hirokazu Kameoka and Nobutaka Ono and Shigeki Sagayama},

title = {Fast Signal Reconstruction from Magnitude {STFT} Spectrogram Based on Spectrogram Consistency},

booktitle = {Proc. International Conference on Digital Audio Effects (DAFx)},

year = 2010,

pages = {397--403},

month = sep

}

Online LWS, "No future" LWS

~~~~~~~~~~~~~~~~~~~~~~~~~~~

| Jonathan Le Roux, Hirokazu Kameoka, Nobutaka Ono, Shigeki Sagayama,

| "Phase initialization schemes for faster spectrogram-consistency-based signal reconstruction,"

| in Proc. of ASJ Autumn Meeting, 3-10-3, Sep. 2010.

.. code::

@InProceedings{LeRoux2010ASJ09,

author = {Jonathan {Le Roux} and Hirokazu Kameoka and Nobutaka Ono and Shigeki Sagayama},

title = {Phase Initialization Schemes for Faster Spectrogram-Consistency-Based Signal Reconstruction},

year = 2010,

booktitle = {Proceedings of the Acoustical Society of Japan Autumn Meeting (ASJ)},

number = {3-10-3},

month = mar

}

Installation

------------

1. The easiest way to install `lws` is via `pip`:

.. code-block:: bash

pip install lws

2. To compile from source using cython (required if one modifies the code):

.. code-block:: bash

cd python

LWS_USE_CYTHON=1 make

3. To compile from source using the pre-generated c source file (which was obtained with cython):

.. code-block:: bash

cd python

make

4. Alternatively, one can first use cython to create a tarball, which can then be installed by pip:

.. code-block:: bash

cd python

make sdist

pip install dist/lws-1.2.tar.gz

**Note:** On Windows, the Microsoft Visual C++ Compiler for your version of Python needs to be installed. See `this page<https://wiki.python.org/moin/WindowsCompilers>`_ for more details.

Usage

-----

.. code:: python

import lws

import numpy as np

lws_processor=lws.lws(512,128, mode="speech") # 512: window length; 128: window shift

X = lws_processor.stft(x) # where x is a single-channel waveform

X0 = np.abs(X) # Magnitude spectrogram

print('{:6}: {:5.2f} dB'.format('Abs(X)', lws_processor.get_consistency(X0))

X1 = lws_processor.run_lws(X0) # reconstruction from magnitude (in general, one can reconstruct from an initial complex spectrogram)

print('{:6}: {:5.2f} dB'.format('LWS', lws_processor.get_consistency(X1)))

Options

-------

.. code:: python

lws_processor=lws.lws(awin_or_fsize, fshift, L = 5, swin = None, look_ahead = 3,

nofuture_iterations = 0, nofuture_alpha = 1, nofuture_beta = 0.1, nofuture_gamma = 1,

online_iterations = 0, online_alpha = 1, online_beta = 0.1, online_gamma = 1,

batch_iterations = 100, batch_alpha = 100, batch_beta = 0.1, batch_gamma = 1,

symmetric_win = True, mode= None, fftsize=None, perfectrec=True)

* ``awin_or_fsize``: either the analysis window, or a window length (in which case the sqrt(hann) window is used); the analysis window should be symmetric for the computations to be correct.

* ``fshift``: window shift

* ``L``: approximation order in the phase reconstruction algorithm, 5 should be good.

* ``swin``: synthesis window (if None, it gets computed from the analysis window for perfect reconstruction)

* ``look_ahead``: number of look-ahead frames in RTISI-LA-like algorithm, 3 should be good.

* ``xxx_iterations``, ``xxx_alpha``, ``xxx_beta``, ``xxx_gamma``: number of iterations of algorithm xxx (where xxx is one of ``nofuture``, ``online``, or ``batch``), and parameters alpha/beta/gamma of the decreasing sparsity curve that is used to determine which bins get updated at each iteration. Any bin with magnitude larger than a given threshold is updated, others are ignored (``thresholds = alpha * np.exp(- beta * np.arange(iterations)**gamma)``)

* ``symmetric_win``: determines whether to use a symmetric hann window or not

* ``mode``: ``None``, ``'speech'``, or ``'music'``. This sets default numbers of iterations of each algorithm that seem to be good for speech and music signals. Disclaimer: your mileage may vary.

* ``fftsize``: can be set longer than frame size to do 0-padding in the FFT. Note that 0-padding will be done symmetrically on the left and right of the window to enforce symmetry in the analysis window.

* ``perfectrec``: whether to pad with zeros on each side to ensure perfect reconstruction at the boundaries too.

Three steps are implemented, and they can be turned on/off independently by appropriately setting the corresponding number of iterations:

* "no future" LWS: phase initialization using LWS updates that only involve past frames

* online LWS: phase estimation using online LWS updates, corresponding to a fast time-frequency domain version of RTISI-LA

* LWS: phase estimation using batch LWS updates on the whole spectrogram

Remarks

-------

1) The .cpp files are actually C code with some C99 style comments, but the .cpp extension is needed on Windows for mex to acknowledge the c99 flag (with .c, it is discarded, and -ansi used instead, leading to compilation errors)

2) Because the module is a C extension, it cannot be reloaded (see <http://bugs.python.org/issue1144263>). In Jupyter Notebooks, in particular, autoreload will not work, and the kernel has to be restarted.

Acknowledgements

----------------

The recipe to wrap the LWS C code as a python module was largely inspired by the following post by Martin Sosic: <http://martinsosic.com/development/2016/02/08/wrapping-c-library-as-python-module.html>

===

**Fast spectrogram phase recovery using Local Weighted Sums (LWS)**

Author: Jonathan Le Roux -- 2008-2018

.. image:: https://badge.fury.io/py/lws.svg

:target: https://badge.fury.io/py/lws

| LWS is a C/C++ library for which this package is a Python wrapper.

| A Matlab/Mex wrapper is also available.

License

-------

| Copyright (C) 2008-2018 Jonathan Le Roux

| Apache 2.0 (http://www.apache.org/licenses/LICENSE-2.0)

Reference

---------

If you use this code, please cite the following papers.

Batch LWS

~~~~~~~~~

| Jonathan Le Roux, Hirokazu Kameoka, Nobutaka Ono, Shigeki Sagayama,

| "Fast Signal Reconstruction from Magnitude STFT Spectrogram Based on Spectrogram Consistency,"

| in Proc. International Conference on Digital Audio Effects (DAFx), pp. 397--403, Sep. 2010.

.. code::

@InProceedings{LeRoux2010DAFx09,

author = {Jonathan {Le Roux} and Hirokazu Kameoka and Nobutaka Ono and Shigeki Sagayama},

title = {Fast Signal Reconstruction from Magnitude {STFT} Spectrogram Based on Spectrogram Consistency},

booktitle = {Proc. International Conference on Digital Audio Effects (DAFx)},

year = 2010,

pages = {397--403},

month = sep

}

Online LWS, "No future" LWS

~~~~~~~~~~~~~~~~~~~~~~~~~~~

| Jonathan Le Roux, Hirokazu Kameoka, Nobutaka Ono, Shigeki Sagayama,

| "Phase initialization schemes for faster spectrogram-consistency-based signal reconstruction,"

| in Proc. of ASJ Autumn Meeting, 3-10-3, Sep. 2010.

.. code::

@InProceedings{LeRoux2010ASJ09,

author = {Jonathan {Le Roux} and Hirokazu Kameoka and Nobutaka Ono and Shigeki Sagayama},

title = {Phase Initialization Schemes for Faster Spectrogram-Consistency-Based Signal Reconstruction},

year = 2010,

booktitle = {Proceedings of the Acoustical Society of Japan Autumn Meeting (ASJ)},

number = {3-10-3},

month = mar

}

Installation

------------

1. The easiest way to install `lws` is via `pip`:

.. code-block:: bash

pip install lws

2. To compile from source using cython (required if one modifies the code):

.. code-block:: bash

cd python

LWS_USE_CYTHON=1 make

3. To compile from source using the pre-generated c source file (which was obtained with cython):

.. code-block:: bash

cd python

make

4. Alternatively, one can first use cython to create a tarball, which can then be installed by pip:

.. code-block:: bash

cd python

make sdist

pip install dist/lws-1.2.tar.gz

**Note:** On Windows, the Microsoft Visual C++ Compiler for your version of Python needs to be installed. See `this page<https://wiki.python.org/moin/WindowsCompilers>`_ for more details.

Usage

-----

.. code:: python

import lws

import numpy as np

lws_processor=lws.lws(512,128, mode="speech") # 512: window length; 128: window shift

X = lws_processor.stft(x) # where x is a single-channel waveform

X0 = np.abs(X) # Magnitude spectrogram

print('{:6}: {:5.2f} dB'.format('Abs(X)', lws_processor.get_consistency(X0))

X1 = lws_processor.run_lws(X0) # reconstruction from magnitude (in general, one can reconstruct from an initial complex spectrogram)

print('{:6}: {:5.2f} dB'.format('LWS', lws_processor.get_consistency(X1)))

Options

-------

.. code:: python

lws_processor=lws.lws(awin_or_fsize, fshift, L = 5, swin = None, look_ahead = 3,

nofuture_iterations = 0, nofuture_alpha = 1, nofuture_beta = 0.1, nofuture_gamma = 1,

online_iterations = 0, online_alpha = 1, online_beta = 0.1, online_gamma = 1,

batch_iterations = 100, batch_alpha = 100, batch_beta = 0.1, batch_gamma = 1,

symmetric_win = True, mode= None, fftsize=None, perfectrec=True)

* ``awin_or_fsize``: either the analysis window, or a window length (in which case the sqrt(hann) window is used); the analysis window should be symmetric for the computations to be correct.

* ``fshift``: window shift

* ``L``: approximation order in the phase reconstruction algorithm, 5 should be good.

* ``swin``: synthesis window (if None, it gets computed from the analysis window for perfect reconstruction)

* ``look_ahead``: number of look-ahead frames in RTISI-LA-like algorithm, 3 should be good.

* ``xxx_iterations``, ``xxx_alpha``, ``xxx_beta``, ``xxx_gamma``: number of iterations of algorithm xxx (where xxx is one of ``nofuture``, ``online``, or ``batch``), and parameters alpha/beta/gamma of the decreasing sparsity curve that is used to determine which bins get updated at each iteration. Any bin with magnitude larger than a given threshold is updated, others are ignored (``thresholds = alpha * np.exp(- beta * np.arange(iterations)**gamma)``)

* ``symmetric_win``: determines whether to use a symmetric hann window or not

* ``mode``: ``None``, ``'speech'``, or ``'music'``. This sets default numbers of iterations of each algorithm that seem to be good for speech and music signals. Disclaimer: your mileage may vary.

* ``fftsize``: can be set longer than frame size to do 0-padding in the FFT. Note that 0-padding will be done symmetrically on the left and right of the window to enforce symmetry in the analysis window.

* ``perfectrec``: whether to pad with zeros on each side to ensure perfect reconstruction at the boundaries too.

Three steps are implemented, and they can be turned on/off independently by appropriately setting the corresponding number of iterations:

* "no future" LWS: phase initialization using LWS updates that only involve past frames

* online LWS: phase estimation using online LWS updates, corresponding to a fast time-frequency domain version of RTISI-LA

* LWS: phase estimation using batch LWS updates on the whole spectrogram

Remarks

-------

1) The .cpp files are actually C code with some C99 style comments, but the .cpp extension is needed on Windows for mex to acknowledge the c99 flag (with .c, it is discarded, and -ansi used instead, leading to compilation errors)

2) Because the module is a C extension, it cannot be reloaded (see <http://bugs.python.org/issue1144263>). In Jupyter Notebooks, in particular, autoreload will not work, and the kernel has to be restarted.

Acknowledgements

----------------

The recipe to wrap the LWS C code as a python module was largely inspired by the following post by Martin Sosic: <http://martinsosic.com/development/2016/02/08/wrapping-c-library-as-python-module.html>

## Project details

## Release history Release notifications

## Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help | File type | Python version | Upload date |
---|---|---|---|

lws-1.2.tar.gz (133.5 kB) Copy SHA256 hash SHA256 | Source | None | Jan 23, 2018 |