Merge pull request #8 from SonyCSL-Paris/refactor

Refactor

.gitignore

@@ -87,3 +87,7 @@ ENV/
 
 # Rope project settings
 .ropeproject
+
+# local files
+/stats/
+/datasets/Oll.xml

README.md

@@ -1,13 +1,16 @@
 # DeepBach
-This repository contains the implementation of the DeepBach model described in 
+Version 1.0 of this repository contains the implementation of the DeepBach model described in
 
 *DeepBach: a Steerable Model for Bach chorales generation*<br/>
 Gaëtan Hadjeres, François Pachet<br/>
 *arXiv preprint [arXiv:1612.01010](https://arxiv.org/abs/1612.01010)*
 
 The code uses python 3.5 together with [Keras](https://keras.io/) and [music21](http://web.mit.edu/music21/) libraries.
 
-# Installation
+Version 2.0 (this one) elaborates on this approach. Results will be presented in an upcoming paper.
+This version contains a Python Flask server and a MuseScore plugin providing an interactive use of DeepBach. 
+
+## Installation
 
 You can download and install DeepBach's dependencies with the following commands:
 
@@ -20,15 +23,16 @@ sudo pip3 install -r requirements.txt
 Make sure either  [Theano](<https://github.com/Theano/Theano>) or [Tensorflow](https://www.tensorflow.org/) is installed.
 You also need to [configure properly the music editor called by music21](http://web.mit.edu/music21/doc/moduleReference/moduleEnvironment.html). 
 
-# Usage
+## Usage
 
 ```
- usage: deepBach.py [-h] [--timesteps TIMESTEPS] [-b BATCH_SIZE_TRAIN]
+usage: deepBach.py [-h] [--timesteps TIMESTEPS] [-b BATCH_SIZE_TRAIN]
                    [-s SAMPLES_PER_EPOCH] [--num_val_samples NUM_VAL_SAMPLES]
                    [-u NUM_UNITS_LSTM [NUM_UNITS_LSTM ...]] [-d NUM_DENSE]
-                   [-n {deepbach,mlp,maxent}] [-i NUM_ITERATIONS] [-t [TRAIN]]
+                   [-n {deepbach,skip}] [-i NUM_ITERATIONS] [-t [TRAIN]]
                    [-p [PARALLEL]] [--overwrite] [-m [MIDI_FILE]] [-l LENGTH]
-                   [--ext EXT]
+                   [--ext EXT] [-o [OUTPUT_FILE]] [--dataset [DATASET]]
+                   [-r [REHARMONIZATION]]
 
 optional arguments:
   -h, --help            show this help message and exit
@@ -44,7 +48,7 @@ optional arguments:
                         number of lstm units (default: [200, 200])
   -d NUM_DENSE, --num_dense NUM_DENSE
                         size of non recurrent hidden layers (default: 200)
-  -n {deepbach,mlp,maxent}, --name {deepbach,mlp,maxent}
+  -n {deepbach,skip}, --name {deepbach,skip}
                         model name (default: deepbach)
   -i NUM_ITERATIONS, --num_iterations NUM_ITERATIONS
                         number of gibbs iterations (default: 20000)
@@ -60,10 +64,15 @@ optional arguments:
   --ext EXT             extension of model name
   -o [OUTPUT_FILE], --output_file [OUTPUT_FILE]
                         path to output file
+  --dataset [DATASET]   path to dataset folder
+  -r [REHARMONIZATION], --reharmonization [REHARMONIZATION]
+                        reharmonization of a melody from the corpus identified
+                        by its id
+
 
 ```
 
-# Examples
+## Examples
 Generate a chorale of length 100:
 ```
 python3 deepBach.py -l 100
@@ -75,9 +84,56 @@ python3 deepBach.py --ext big -u 200 200 200 -d 500 -t 10
 
 Generate chorale harmonization with soprano extracted from midi/file/path.mid using parallel Gibbs sampling with 10000 updates (total number of updates)
 ```
-python3 deepBach.py -m midi/file/path.mid -p -i 10000
+python3 deepBach.py -m midi/file/path.mid -p -i 20000
 ```
 
 
+Use another model with custom parameters:
+```
+python3 deepBach.py --ext  big  -t 30 --timesteps 32 -u 512 256 -d 256 -b 16
+```
+
+Use another database, your dataset folder must contain .xml or .mid files with the same number of voices:
+```
+python3 deepBach.py --dataset /path/to/dataset/folder/ --ext dowland -t 30 --timesteps 32 -u 256 256 -d 256 -b 32
+```
+
+Reharmonization of a melody from the training or testing set:
+```
+python3 deepBach.py  -p -i 40000 -r 25
+```
 
 Default values load pre-trained DeepBach model and generate a chorale using sequential Gibbs sampling with 20000 iterations
+
+
+# MuseScore plugin and Flask server
+Put  ``deepBachMuseScore.qml`` file in your ``MuseScore2/Plugins`` directory.
+
+Run local Flask server:
+```
+export FLASK_APP=plugin_flask_server.py
+flask run
+```
+or a public server (only one connection is supported for the moment).
+```
+export FLASK_APP=plugin_flask_server.py
+flask run --host 0.0.0.0
+```
+
+Open MuseScore and activate deepBachMuseScore plugin using the Plugin manager.
+Open a four-part chorale.
+Press enter on the server address, a list of computed models should appear.
+Select and (re)load a model.
+Select a zone in the chorale and click on the compose button.
+
+
+This plugin only generates C major/A minor chorales with cadences every to bars. This is a limitation of the plugin, not the model itself.
+
+
+Please consider citing this work or email me if you use DeepBach in musical projects. 
+
+### Issues
+ImportError issues: Make sure DeepBach project is in your PYTHONPATH
+```
+export PYTHONPATH=/Path/to/DeepBach/Project
+```