documented how to run Applause in Jupyter Consoles and Notebooks

* This is at the very least cool to have and will be worthwile to write about in the dissertation.
* Added ilua-wrapper.sh script which can be used as the ILua interpreter and/or can be symlinked to `lua` in PATH,
  so ILua will pick up Applause even in Notebooks without any additional tweaks.

1 files changed, 62 insertions, 0 deletions

diff --git a/README.md b/README.md
index b97dd2d..2d0b7a5 100644
--- a/README.md
+++ b/README.md
@@ -72,3 +72,65 @@ to expose them as MIDI events.
 * evtest to find and test HID devices
 * listplugins and analyseplugin to inspect LADSPA plugins
 * dssi_list_plugins and dssi_analyse_plugin to inspect DSSI plugins
+
+## Jupyter Console and Notebook
+
+Applause can be run in [Jupyter](https://jupyter.org/) Consoles and even Notebooks thanks to
+[ILua](https://github.com/guysv/ilua).
+First, install ILua into a Python environment
+(see also this [ILua ticket](https://github.com/guysv/ilua/issues/28)):
+
+```bash
+git clone https://github.com/guysv/ilua.git --recurse-submodules
+cd ilua
+python3 -m venv env
+. env/bin/activate
+pip install twisted==22.10.0 ilua
+```
+
+You can now directly run an Applause Jupyter Console session:
+
+```
+cd ~/applause
+ilua --lua-interpreter=./applause
+```
+
+In order to tweak Applause command line parameters and be independant of the execution directory, use
+the included wrapper script:
+
+```
+ilua --lua-interpreter=./ilua-wrapper.sh
+```
+
+You can symlink this to `lua` in the Python environment to make Applause the default
+ILua interpreter in this Python environment:
+
+```
+ln -s ~/applause/ilua-wrapper.sh env/bin/lua
+```
+
+If you would like to launch a Jupyter Notebook (Web UI!), first install the following Pip package:
+
+```
+pip install notebook
+```
+
+Now launch a web server and follow the onscreen instructions:
+
+```
+jupyter notebook
+```
+
+In the Jupyter Notebook dashboard, when creating a new notebook, you will be asked to select the kernel.
+If you choose Lua, this will in fact launch Applause (assuming that you symlinked to `lua`
+as described above).
+An alternative might be to create a custom Jupyter kernel configuration (kernel.json).
+
+Please note the following restrictions/bugs:
+
+* You cannot publicly host the Jupyter Notebook as the sound is generated on the host machine.
+* You cannot currently interrupt an endlessly running stream without restarting the kernel (**FIXME**)
+* ILua does not work well with our custom Stream:tostring() metamethods
+* The output of other functions like Stream:toplot() is garbled.
+* You cannot currently output rich text or graphics
+  (it would be really cool if we could display SVG generated by gnuplot in notebook cells for instance).