WIP - Kapre 0.3.2 (#88)

* Add ReadTheDocs config and files (#87)

add napoleon

add readthedocs.yml

add version 2

fix readthedocs yaml

add setup_py_install

fix setup py install

diff doc

move rtd yml to docs/

add kapre source

add requirements.txt

ugh

mock the dependency

remove wrong line sys path add

add mock modules

rollback readthedocs.yaml;

fix pip path

gettinb back the mocks but ughhh

dd

update napoleon

fix recursive error at mocking

sdngfosdnfsdnf

remove unittest mocking

update doc

add more rsts

update

clean index

* add framing

* update doc and dostring

* update signal test;

* change testing python version

* more generous on numpy, upgrade pip at travis

* add ignore llvmlite

* black follow project config. py36 and 37 only

* remove black from travis

* update readme

* specify numpy to be >=1.19

* update readme

* update readme

* add references

* starting mu law

* add mu law backend

* done with mu law layers

* fix test. rename to LogmelToMFCC

* adding example. added alias at __init__ so that kapre.LAYERNAME could work

* all examples are added for layer classes

* fix docstring indentation

* fix more docs

* change to import directly

* fix typo

* fix docstrings more

* add examples for composed layer

* example format

* add custom css to be wider

Co-authored-by: forcecore <[email protected]>
Co-authored-by: Keunwoo Choi <[email protected]>

.travis.yml

@@ -1,15 +1,18 @@
 language: python
 python:
     - "3.6"
+    - "3.7"
 
 install:
+    - python -m pip install --upgrade pip
     - pip install --pre -e .
-    - pip install black
+#    - pip install black
 
 script:
     - pytest
-    - black --line-length 100 --diff --check --skip-string-normalization --target-version=py37 kapre
-    - black --line-length 100 --diff --check --skip-string-normalization --target-version=py37 tests
+#    - black --diff --check kapre
+#    - black --diff --check tests
+# there is inconsistency in travis black and my black
 
 after_success:
     - coveralls

README.md

@@ -1,49 +1,51 @@
 # Kapre
 Keras Audio Preprocessors - compute STFT, ISTFT, Melspectrogram, and others on GPU real-time.
 
-Tested on Python 3.3, 3.6, and 3.7.
-
-## Why?
-- Kapre enables you to optimize DSP parameters and makes model deployment simpler with less dependency.  
-- Kapre layers are consistent with 1D/2D tensorflow batch shapes.
-- Kapre layers are compatible with `'channels_first'` and `'channels_last'`
-- Kapre layers are tested against Librosa (stft, decibel, etc) - which is (trust me) *tricker* than you think.
-- Kapre layers have extended APIs from the default `tf.signals` implementation.
-- Kapre provides a perfectly invertible `STFT` and `InverseSTFT` pair.
-- You save your time implementing and testing all of these.
-- Kapre is available on pip with versioning; hence you keep your code reproducible.   
+Tested on Python 3.6 and 3.7
+
+## Why Kapre?
+
+### vs. Pre-computation
+
+* You can optimize DSP parameters
+* Your model deployment becomes much simpler and consistent.
+* Your code and model has less dependencies
+
+### vs. Your own implementation
+
+* Quick and easy!
+* Consistent with 1D/2D tensorflow batch shapes
+* Data format agnostic (`channels_first` and `channels_last`)
+* Less error prone - Kapre layers are tested against Librosa (stft, decibel, etc) - which is (trust me) *trickier* than you think.
+* Kapre layers have some extended APIs from the default `tf.signals` implementation such as..
+  - A perfectly invertible `STFT` and `InverseSTFT` pair
+  - Mel-spectrogram with more options
+* Reproducibility - Kapre is available on pip with versioning   
+
+## Workflow with Kapre
+
+1. Preprocess your audio dataset. Resample the audio to the right sampling rate and store the audio signals (waveforms).
+2. In your ML model, add Kapre layer e.g. `kapre.time_frequency.STFT()` as the first layer of the model.
+3. The data loader simply loads audio signals and feed them into the model
+4. In your hyperparameter search, include DSP parameters like `n_fft` to boost the performance.
+5. When deploying the final model, all you need to remember is the sampling rate of the signal. No dependency or preprocessing!
 
 ## Installation
 
 ```sh
 pip install kapre
 ```
 
-## Usage
-### Layers
-
-Audio preprocessing layers
-* Basic layers in [time_frequency.py](https://github.com/keunwoochoi/kapre/blob/master/kapre/time_frequency.py)
-  - `STFT`
-  - `Magnitude`
-  - `Phase`
-  - `MagnitudeToDecibel`
-  - `ApplyFilterbank`
-  - `Delta` 
-* Complicated layers are composed using time-frequency layers as in [composed.py](https://github.com/keunwoochoi/kapre/blob/master/kapre/composed.py).
-  - `kapre.composed.get_perfectly_reconstructing_stft_istft()`
-  - `kapre.composed.get_stft_mag_phase()`
-  - `kapre.composed.get_melspectrogram_layer()`
-  - `kapre.composed.get_log_frequency_spectrogram_layer()`. 
-
-(Note: Official documentation is coming soon)
+## API Documentation
+
+Please refer to Kapre API Documentation at (https://kapre.readthedocs.io/)[https://kapre.readthedocs.io/]
 
 ## One-shot example
 
 ```python
 from tensorflow.keras.models import Sequential
 from tensorflow.keras.layers import Conv2D, BatchNormalization, ReLU, GlobalAveragePooling2D, Dense, Softmax
-from kapre.time_frequency import STFT, Magnitude, MagnitudeToDecibel
+from kapre import STFT, Magnitude, MagnitudeToDecibel
 from kapre.composed import get_melspectrogram_layer, get_log_frequency_spectrogram_layer
 
 # 6 channels (!), maybe 1-sec audio signal, for an example.
@@ -56,7 +58,7 @@ model.add(STFT(n_fft=2048, win_length=2018, hop_length=1024,
                input_data_format='channels_last', output_data_format='channels_last',
                input_shape=input_shape))
 model.add(Magnitude())
-model.add(MagnitudeToDecibel())
+model.add(MagnitudeToDecibel())  # these three layers can be replaced with get_stft_magnitude_layer()
 # Alternatively, you may want to use a melspectrogram layer
 # melgram_layer = get_melspectrogram_layer()
 # or log-frequency layer
@@ -99,7 +101,15 @@ Please cite this paper if you use Kapre for your work.
 ```
 
 ## News
-
+* ?? Aug 2020
+  - 0.3.2
+    - `kapre.signal.Frame` and `kapre.signal.Energy` are added
+    - `kapre.signal.LogmelToMFCC` is added
+    - `kapre.signal.MuLawEncoder` and `kapre.signal.MuLawDecoder` are added
+    - `kapre.composed.get_stft_magnitude_layer()` is added 
+* 21 Aug 2020
+  - 0.3.1
+    - `Inverse STFT` is added
 * 15 Aug 2020
   - 0.3.0
     - Breaking and simplifying changes with Tensorflow 2.0 and more tests. Some features are removed.

docs/.readthedocs.yml

@@ -0,0 +1,7 @@
+version: 2
+
+python:
+   version: 3.7
+   install:
+      - requirements: docs/requirements.txt
+   system_packages: true

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_static/css/custom.css

@@ -0,0 +1,3 @@
+div.wy-nav-content {
+    max-width: 1200px;
+}

docs/backend.rst

@@ -0,0 +1,5 @@
+backend
+^^^^^^^
+
+.. automodule:: kapre.backend
+    :members:

docs/composed.rst

@@ -0,0 +1,7 @@
+composed
+^^^^^^^^
+
+.. automodule:: kapre.composed
+    :members:
+
+

docs/conf.py

@@ -0,0 +1,71 @@
+
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../'))
+import sphinx_rtd_theme
+autodoc_mock_imports = ['tensorflow', 'librosa', 'numpy']
+autodoc_member_order = 'bysource'
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'Kapre'
+copyright = '2020, Keunwoo Choi, Deokjin Joo and Juho Kim'
+author = 'Keunwoo Choi, Deokjin Joo and Juho Kim'
+
+# The full version, including alpha/beta/rc tags
+release = '2017'
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx_rtd_theme",
+    "sphinx.ext.viewcode",  # source linkage
+    "sphinx.ext.napoleon",
+    # "sphinx.ext.autosummary",
+    "sphinx.ext.viewcode",  # source linkage
+]
+
+# autosummary_generate = True
+
+# autoapi_type = 'python'
+# autoapi_dirs = ['../kapre']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+master_doc = 'index'

docs/index.rst

@@ -0,0 +1,95 @@
+.. Kapre documentation master file, created by
+   sphinx-quickstart on Thu Aug 27 19:40:10 2020.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Kapre
+=====
+
+Keras Audio Preprocessors - compute STFT, InverseSTFT, Melspectrogram, and others on GPU real-time.
+
+Tested on Python 3.6, and 3.7.
+
+Why Kapre?
+----------
+
+vs. Pre-computation
+^^^^^^^^^^^^^^^^^^^
+
+* You can optimize DSP parameters
+* Your model deployment becomes much simpler and consistent.
+* Your code and model has less dependencies
+
+vs. Your own implementation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* Quick and easy!
+* Consistent with 1D/2D tensorflow batch shapes
+* Data format agnostic (`channels_first` and `channels_last`)
+* Less error prone - Kapre layers are tested against Librosa (stft, decibel, etc) - which is (trust me) *trickier* than you think.
+* Kapre layers have some extended APIs from the default `tf.signals` implementation such as..
+  - A perfectly invertible `STFT` and `InverseSTFT` pair
+  - Mel-spectrogram with more options
+* Reproducibility - Kapre is available on pip with versioning
+
+Workflow with Kapre
+-------------------
+
+1. Preprocess your audio dataset. Resample the audio to the right sampling rate and store the audio signals (waveforms).
+2. In your ML model, add Kapre layer e.g. `kapre.time_frequency.STFT()` as the first layer of the model.
+3. The data loader simply loads audio signals and feed them into the model
+4. In your hyperparameter search, include DSP parameters like `n_fft` to boost the performance.
+5. When deploying the final model, all you need to remember is the sampling rate of the signal. No dependency or preprocessing!
+
+Installation
+------------
+
+.. code-block:: none
+
+  pip install kapre
+
+
+Example
+-------
+
+See the Jupyter notebook at the `example folder <https://github.com/keunwoochoi/kapre/tree/master/examples>`_
+
+
+Citation
+--------
+
+Please cite `this paper <https://arxiv.org/abs/1706.05781>`_ if you use Kapre for your work.
+
+
+.. code-block:: none
+
+  @inproceedings{choi2017kapre,
+    title={Kapre: On-GPU Audio Preprocessing Layers for a Quick Implementation of Deep Neural Network Models with Keras},
+    author={Choi, Keunwoo and Joo, Deokjin and Kim, Juho},
+    booktitle={Machine Learning for Music Discovery Workshop at 34th International Conference on Machine Learning},
+    year={2017},
+    organization={ICML}
+  }
+
+
+Contribution
+------------
+Visit `github.com/keunwoochoi/kapre <https://github.com/keunwoochoi/kapre>`_ and chat with us :)
+
+
+.. toctree::
+   :hidden:
+   :caption: Kapre
+
+   quickstart
+
+
+.. toctree::
+   :hidden:
+   :caption: API
+
+   time_frequency
+   signal
+   composed
+   backend
+

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd