Updated docs

.gitignore

@@ -1,7 +1,6 @@
 lightning_logs/
 *.ckpt
 *.pickle
-*.wav
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

README.md

@@ -35,21 +35,51 @@ For a great explanation of how it works, check out blog post from original pedal
 http://teddykoker.com/2020/05/deep-learning-for-guitar-effect-emulation/
 
 
+## Setup
+
+> Jupyter Notebooks for Google Colab are available in [notebooks](notebooks)
+
+1. Install [Python 3](https://www.python.org/downloads/) with pip package manager
+2. Install [git](https://git-scm.com/downloads)
+3. Create and enter virtual environment
+   ```sh
+   python -m venv .
+   ```
+
+   ```sh
+   . bin/activate
+   ```
+4. Clone the repository
+   ```sh
+   git clone https://github.com/GuitarML/PedalNetRT.git src/
+   ```
+5. Enter the directory and install the dependencies using `pip` package manager
+   ```sh
+   cd src
+   ```
+
+   ```sh
+   python -m pip install -r requirements.txt
+   ```
+
+   (Optional development dependencies)
+
+   ```sh
+   python -m pip install -r requirements-dev.txt
+   ```
+
 ## Data
 
 `data/ts9_test1_in_FP32.wav` - Playing from a Fender Telecaster, bridge pickup, max tone and volume<br>
 `data/ts9_test1_out_FP32.wav` - Split with JHS Buffer Splitter to Ibanez TS9 Tube Screamer
 (max drive, mid tone and volume).<br>
-`models/ts9_epoch=1362.ckpt` - Pretrained model weights
-
+`models/pedalnet/pedalnet.ckpt` - Pretrained model weights
 
-## Usage
 
 **Run effect on .wav file**:
 Must be single channel, 44.1 kHz, FP32 wav data (not int16)
 ```bash
-# must be same data used to train
-python prepare_data.py data/ts9_test1_in_FP32.wav data/ts9_test1_out_FP32.wav
+python train.py data/ts9_test1_in_FP32.wav data/ts9_test1_out_FP32.wav
 
 # specify input file and desired output file
 python predict.py my_input_guitar.wav my_output.wav
@@ -60,21 +90,19 @@ python predict.py my_input_guitar.wav my_output.wav
 
 **Train**:
 ```bash
-python prepare_data.py data/ts9_test1_in_FP32.wav data/ts9_test1_out_FP32.wav  # or use your own!
-python train.py
+python train.py data/ts9_test1_in_FP32.wav data/ts9_test1_out_FP32.wav
 
-python train.py --resume_training=path_to_ckpt_file  # to continue training from .ckpt file
+python train.py --resume  # to resume training
 
 python train.py --gpus "0,1"  # for multiple gpus
-python train.py --cpu=1       # for cpu training
-python train.py -h  # help (see for other hyperparameters)
-
+python train.py --cpu # for cpu training
+python train.py -h # help (see for other hyperparameters)
 ```
 
 **Test**:
 ```bash
 python test.py # test pretrained model
-python test.py --model lightning_logs/version_{X}/epoch={EPOCH}.ckpt  # test trained model
+python test.py --model your_trained_model.ckpt  # test trained model
 ```
 Creates files `y_test.wav`, `y_pred.wav`, and `x_test.wav`, for the ground truth
 output, predicted output, and input signal respectively.
@@ -85,22 +113,21 @@ output, predicted output, and input signal respectively.
 The .ckpt model must be converted to a .json model to run in the plugin.
 Usage:
 
-	python convert_pedalnet_to_wavnetva.py --model=your_trained_model.ckpt
+	python export.py --model=your_trained_model.ckpt
 
 Generates a file named "converted_model.json" that can be loaded into the VST plugin.
 
 **Analysis**:
 
-You can also use "plot_wav.py" to evaluate the trained PedalNet model. By
+You can also use "plot.py" to evaluate the trained PedalNet model. By
 default, this will analyze the three .wav files from the test.py output. It
 will output analysis plots and calculate the error to signal ratio.
 
-Usage (after running "python test.py --model=your_model.ckpt"):
+Usage (after running "python test.py --model=your_trained_model.ckpt"):
 
-	python plot_wav.py
-
-![app](https://github.com/keyth72/pedalnet/blob/master/figures/example_plot.png)
+	python plot.py
 
+![plot.py output](figures/example_plot.png)
 
 Public spreadsheet for sharing analysis results (can request write access through google account):<br>
 https://docs.google.com/spreadsheets/d/1sIkhW3cdLkMc8bYrYspE8xzdCrJbyWXg_I0vAuJec88/edit?usp=sharing
@@ -137,8 +164,3 @@ Helpful tips on training models:
 6. This WaveNet model is effective at reproducing distortion/overdrive, but
    not reverb/delay effects (or other time-based effects). Mostly untested on
    compressor/limiter effects, but initial results seem promising.
-
-
- Note: Added an experimental Google Colab notebook to train pedalnet models on TPU's.
-       Upload "colab_TPU_training.ipynb" in Google Colab, and upload this pedalnet
-       repository to your Google Drive to use.

data/README.md

@@ -1 +1,18 @@
-here is the training data
+# Training data
+
+1. Must be single channel, 44.1 kHz, FP32 wav data (not int16)
+2. Wav files should be 3 - 4 minutes long, and contain a variety of
+   chords, individual notes, and playing techniques to get a full spectrum
+   of data for the model to "learn" from.
+3. A buffer splitter was used with pedals to obtain a pure guitar signal
+   and post effect signal.
+4. Obtaining sample data from an amp can be done by splitting off the original
+   signal, with the post amp signal coming from a microphone (I used a SM57).
+   Keep in mind that this captures the dynamic response of the mic and cabinet.
+   In the original research the sound was captured directly from within the amp
+   circuit to have a "pure" amp signal.
+5. When recording samples, try to maximize the volume levels without clipping.
+   The levels you train the model at will be reproduced by the plugin. Also try
+   to make the pre effect and post effect wav samples equal in volume levels.
+   Even though the actual amp or effect may raise the level significantly, this isn't
+   necessarily desirable in the end plugin.