From 4720e8847507acf4a63cfd7719c29101680df86f Mon Sep 17 00:00:00 2001
From: David Runge <dave@sleepmap.de>
Date: Sun, 3 Jul 2016 13:13:11 +0200
Subject: README.rst: Adding information about bowelyzer output, how to and
 where to install it and how to use it on Linux and MacOSX.

---
 README.rst | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 71 insertions(+), 6 deletions(-)

diff --git a/README.rst b/README.rst
index 9c535bf..8aec7ea 100644
--- a/README.rst
+++ b/README.rst
@@ -1,22 +1,42 @@
 bowelyzer
 #########
 
-| |supercollider| classes for analysis of several audio streams and sending of OSC messages based on amplitude thresholds and frequency maxima
+| |supercollider| classes for analysis of several audio streams and sending of |osc| messages based on amplitude and frequency thresholds and onset detection
 
 Features
 ________
 
+* |json| configuration file
+* multi-channel (channels are additionally selectable multiple times)
+* analysis of amplitude, pitch and onset settable
+* on-the-fly renaming and rerouting of channels
+
 Installation
 ____________
-Clone this repository to somewhere sclang will pick it up on recompiling its class library:
+
+Git
+***
+
+| Clone this repository to somewhere sclang will pick it up on recompiling its class library (such as your |supercollider_extension| folder):
+
+Linux
+-----
 
   .. code:: bash
 
     cd ~/.local/share/SuperCollider/Extensions/local
     git clone git://sleepmap.de/audio/bowelyzer.git
 
-If the local folder doesn't exist, create it, otherwise you can also directly clone into the Extensions folder (the folder and all of its children will get picked up on recompile).  
-Symlinking is fine, too!  
+MacOSX
+------
+
+  .. code:: bash
+
+    cd ~/Library/Application Support/SuperCollider/Extensions/local
+    git clone git://sleepmap.de/audio/bowelyzer.git
+
+| If the local folder doesn't exist, create it, otherwise you can also directly clone into the Extensions folder (the folder and all of its children will get picked up on recompile).
+| Symlinking is fine, too!
 
   .. code:: bash
 
@@ -25,13 +45,58 @@ Symlinking is fine, too!
     cd ./local/share/SuperCollider/Extensios/local/
     ln -s ~/some/other/directory/bowelyzer .
 
+Version
+*******
+
+| You can also try a specific version of bowelyzer, by downloading it from the |bowelyzer-git-repository| (version tar balls are listed under the **Tag** header).
+| Extract the tar ball into the above mentioned **Extensions/local** folder on your specific operating system.
+
 Usage
 _____
-Go to the cloned directory and open **bowelyzer.scd** in your favorite SuperCollider IDE.  
-All further steps are explained there.
+| Go to the cloned directory and open **bowelyzer.scd** in your favorite SuperCollider IDE.
+| How to start the application with and without configuration is explained there.
+
+Configuration
+*************
+| Bowelyzer is configured by a |json| file with pre-defined fields.
+| Have a look at the shipped example, to see how it works and what is available.
+| Generally there are some global options (such as *addresses* and *ports*) and per channel configurations (such as *inputs* and *controls*).
+
+* **Note**: The available inputs of |supercollider| are defined by your |supercollider_startupfile|. Make sure to set the correct amount of |supercollider_numinputbuschannels|.
 
+Output
+******
+Bowelyzer sends |osc| messages to a preconfigured host and port of the form
+**[/name, amplitude, pitch, hasPitch, onSet]**, where **/name** refers to the
+name of the channel, **amplitude** to the detected amplitude (0.0 - 1.0), **pitch** to
+the detected frequency (20Hz - 20kHz), **hasPitch** (0, 1) to whether a pitch was
+detected and **onSet** (0, 1) to whether an onset was detected.
+
+.. |supercollider_extension| raw:: html
+
+  <a href="http://doc.sccode.org/Guides/UsingExtensions.html" target="_blank">Extension</a>
+
+.. |supercollider_numinputbuschannels| raw:: html
+
+  <a href="http://doc.sccode.org/Classes/ServerOptions.html#-numInputBusChannels" target="_blank">numInputBusChannels</a>
+
+.. |supercollider_startupfile| raw:: html
+
+  <a href="http://doc.sccode.org/Reference/StartupFile.html" target="_blank">startupFile</a>
+
+.. |osc| raw:: html
+
+  <a href="https://en.wikipedia.org/wiki/Open_Sound_Control" target="_blank">OSC</a>
+
+.. |json| raw:: html
+
+  <a href="https://en.wikipedia.org/wiki/JSON" target="_blank">JSON</a>
 
 .. |supercollider| raw:: html
 
   <a href="https://supercollider.github.io/" target="_blank">SuperCollider</a>
 
+.. |bowelyzer-git-repository| raw:: html
+
+  <a href="https://git.sleepmap.de/audio/bowelyzer.git" target="_blank">bowelyzer git repository</a>
+
-- 
cgit v1.2.3