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.

3 files changed, 80 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).
diff --git a/TODO b/TODO
index 62cc4cb..99d4ad6 100644
--- a/TODO
+++ b/TODO
@@ -3,9 +3,18 @@
 * Stream:foreach() cannot be interrupted
   Perhaps C core should export an interrupted variable that we can check from Lua.
   For Stream:play() this is solved differently.
+* The MIDIStream should be flushed when starting via Stream:play().
+* There are lots of limitations with Jupyter servers (see README).
 
 # Features
 
+* RTNeural support. Should probably be a separate library or an optional dependency.
+  This is important to justify the thesis as related to AI.
+  Since it is a C++ library making extensive use of templates, there will have to be
+  a small C wrapper.
+  Since build time options are important (to choose the backend), it will have to be
+  added as a submodule.
+  Port the official RTNeural-example to Applause.
 * Real-time input. See inputstream branch.
 * Line Continuations on the CLI (like Lua's CLI)
 * CLI auto completions via libreadline.
@@ -30,6 +39,7 @@
 * Github pages (LDoc documentation).
   They can be automatically pushed by a Github action.
   Since they will always be public, copyright questions should be resolved first.
+* Allow limited operation without a running Jack server.
 
 # Improvements
 
diff --git a/ilua-wrapper.sh b/ilua-wrapper.sh
new file mode 100755
index 0000000..344de5d
--- /dev/null
+++ b/ilua-wrapper.sh
@@ -0,0 +1,8 @@
+#!/bin/sh
+# This wrapper exists, so you can pass additional arguments to Applause when
+# using it as an ILua interpreter.
+# Also, it's useful as you do not have to change the directory before invoking ILua.
+# Thirdly, if you create a symbolic link to lua in a Python environment of ILua, this invoke
+# Applause by default and it will even work with Jupyter Notebooks without further tweaks.
+cd $(dirname $(readlink -m "$0"))
+exec ./applause -o 2 "$@"