merge, add license

Author: victor-shepardson

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Intelligent Instruments Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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 OR COPYRIGHT HOLDERS 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.

Readme.md

@@ -1,12 +1,13 @@
-# Structure
+# Repository Structure
 
 - iipyper: python package for easy MIDI, OSC, event loops
-- notochord: python package for defining+training pytorch RNN models
-    - notebooks: jupyter notebooks
+- notochord: python package for the Notochord MIDI performance model
+    - notochord: package source code
     - scripts: helper scripts for training, data preprocessing etc
 - examples:
     - iipyper: basic usage for iipyper
     - notochord: interactive MIDI apps with notochord and SuperCollider
+        - tidalcycles: notochord interface to TidalCycles
     - bela: [Bela](https://bela.io) examples in C++, Pure Data and so on
     - faust: [Faust](https://faustdoc.grame.fr/) examples
     - tidalcycles [TidalCycles](https://tidalcycles.org) examples
@@ -15,26 +16,75 @@
 
 # Setup
 
+clone the repository:
+```
+git clone https://github.com/Intelligent-Instruments-Lab/iil-python-tools.git
+cd iil-python-tools
+```
+
+we manage python dependencies with `conda`. If you don't have an anaconda/miniconda python install already, download an installer from https://docs.conda.io/en/latest/miniconda.html or use `brew install --cask miniconda` on mac.
+
+you can check that this worked with `which python` -- it should have 'miniconda' in the path
+
+now set up a python environment:
 ```
 conda env create -f environment.yml
 conda activate iil-python-tools
 pip install -e notochord
 pip install -e iipyper
 ```
+this will install all dependencies in a conda environment called `iil-python-tools`, and do an editable install of notochord and iipyper so you can hack on them.
 
 # notochord
-## Train a model
+download a model checkpoint (e.g. `notochord_lakh_20G.ckpt`) from the releases page: https://github.com/Intelligent-Instruments-Lab/iil-python-tools/releases
+
+## Run python server
+In a terminal, make sure the `iil-python-tools` conda environment is active (`conda activate iil-python-tools`) and run:
 ```
-python notochord/scripts/lakh_prep.py --data_path /path/to/midi/files --dest_path /path/to/data/storage
-python notochord/train.py --data_dir /path/to/data/storage --log_dir /path/for/tensorboard logs --model_dir /path/for/checkpoints train
+python -m notochord server --checkpoint ~/Downloads/notochord_lakh_20G.ckpt
+```
+this will run notochord and listen continously for OSC messages.
+
+`examples/notochord/generate-demo.scd` and `examples/notochord/harmonize-demo.scd` are example scripts for interacting with the notochord server from SuperCollider.
+
+## Tidal interface
+
+see `examples/notochord/tidalcycles`:
+
+add `Notochord.hs` to your tidal boot file. Probably replace the `tidal <- startTidal` line with something like:
 ```
+:script ~/iil-python-tools/examples/notochord/tidalcycles/Notochord.hs
 
-## Run OSC app
+let sdOscMap = (superdirtTarget, [superdirtShape])
+let oscMap = [sdOscMap,ncOscMap]
 
+tidal <- startStream defaultConfig {cFrameTimespan = 1/240} oscMap
+```
+
+In a terminal, start the python server as described above.
+
+In Supercollider, step through `examples/notochord/tidalcycles/tidal-notochord-demo.scd` which will receive from Tidal, talk to the python server, and send MIDI on to a synthesizer. There are two options, either send to fluidsynth to synthesize General MIDI, or specify your own mapping of instruments to channels and send on to your own DAW or synth.
+
+### Install fluidsynth (optional)
+fluidsynth (https://github.com/FluidSynth/fluidsynth) is a General MIDI synthesizer which you can install from the package manager. On mac:
+```
+brew install fluidsynth
+```
+fluidsynth needs a soundfont to run, like this one: https://drive.google.com/file/d/1-cwBWZIYYTxFwzcWFaoGA7Kjx5SEjVAa/view
+
+run fluidsynth in a terminal (see the fluidsynth block in `examples/notochord/tidalcycles/tidal-notochord.scd` for an example command).
+
+## Train your own Notochord model (GPU recommended)
+
+preprocess the data:
+```
+python notochord/scripts/lakh_prep.py --data_path /path/to/midi/files --dest_path /path/to/data/storage
+```
+launch a training job:
 ```
-python examples/notochord/server.py --checkpoint /path/to/my/model.ckpt
+python notochord/train.py --data_dir /path/to/data/storage --log_dir /path/for/tensorboard/logs --model_dir /path/for/checkpoints --results_dir /path/for/other/logs train
 ```
-step through `examples/notochord/generate.scd` in SuperCollider IDE
+progress can be monitored via tensorboard.
 
 # Develop