README.rst: Adding first draft of README.

1 files changed, 102 insertions, 0 deletions

diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..1a72308
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,102 @@
+ZZZ
+###
+
+| |SuperCollider| classes to interface |expert_sleepers| devices.
+
+Supported devices
+-----------------
+
+* |es-3|
+
+Features
+--------
+
+* convenience methods to convert between frequency, amplitude and corresponding output voltage
+
+Installation
+------------
+
+The classes are an extension of the |supercollider| language, therefore their installation corresponds to |quark_installation|.
+
+Usage
+-----
+
+To create a new object interfacing your |es-3|, instantiate the *ZZZES3* class with an Array holding your eight ADAT output channels:
+
+  .. code:: supercollider
+
+    // RME Babyface example
+    ~es3 = ZZZES3(Array.series(8, 4, 1));
+
+To play a Synth on one of the eight |es-3| outputs you can use one of the *SynthDefs* added by the *ZZZ* class, such as *\ZZZConstant* (for constant notes) or *\ZZZClock* (for clock):
+
+  .. code:: supercollider
+
+    // play Synth 'ZZZClock' at ES-3 output 8 with a speed of 240bpm (defaults to 120bpm)
+    ~zzzClock = Synth(\ZZZClock, [\out, ~es3.out(8), \freq, (240/60)]);
+
+  .. code:: supercollider
+
+    // play Synth 'ZZZConstant' at ES-3 output 7 with a multiplacation factor corresponding to the note C5
+    ~zzzNote = Synth(\ZZZConstant, [\out, ~es3.out(7), \mul, ZZZ.cpsamp(523.251)]);
+
+  .. note::
+
+    | The convenience function *ZZZES3.out* accepts integers from 1 to 8 (corresponding to the numbering on the device itself) and returns the *Out* number connected to it.
+    | Generally, in |supercollider| channel numbering starts from 0, though!
+
+
+Just like with any other *Synth*, you can now change their settings:
+
+  .. code:: supercollider
+
+    // change clock speed to 300bpm
+    ~zzzClock.set(\freq, (300/60));
+
+  .. code:: supercollider
+
+    // change note to A4
+    ~zzzNote.set(\mul, ZZZ.cpsamp(69.midicps));
+
+
+Background
+----------
+| Modular synthesizers are controllable through several ranges of voltage.
+|
+| |cv_gate| as defined by |doepfer| in the |a100_manual| might not be coherently used throughout all Eurorack modules however.
+| The *ZZZ* classes nonetheless try to adhere to the standard, while at the same time provide convenience functions to low-level conversion.
+| By default the helper functions are able to convert frequencies in the |c_musical_note| (between *C-2* and *C10*) to an output between -5V and 7V (adhering to the 1V/octave scheme).
+| As the range is not fixed, but can be moved up and down (e.g. when using filters or oscillators), you might have to make some adjustments to your module, to get "in tune".
+
+.. |supercollider| raw:: html
+
+  <a href="https://supercollider.github.io/" target="_blank">SuperCollider</a>
+
+.. |expert_sleepers| raw:: html
+
+  <a href="http://www.expert-sleepers.co.uk/" target="_blank">Expert Sleepers</a>
+
+.. |es-3| raw:: html
+
+  <a href="http://www.expert-sleepers.co.uk/es3.html" target="_blank">ES-3</a>
+
+.. |quark_installation| raw:: html
+
+  <a href="https://github.com/supercollider-quarks/quarks#installing-a-quark" target="_blank">the way quarks are installed</a>
+
+.. |cv_gate| raw:: html
+
+  <a href="https://en.wikipedia.org/wiki/CV/gate" target="_blank">CV/Gate</a>
+
+.. |doepfer| raw:: html
+
+  <a href="http://www.doepfer.de" target="_blank">Doepfer</a>
+
+.. |a100_manual| raw:: html
+
+  <a href="http://www.doepfer.de/a100_man/a100t_e.htm" target="_blank">A100 manual</a>
+
+.. |c_musical_note| raw:: html
+
+  <a href="https://en.wikipedia.org/wiki/C_(musical_note)" target="_blank">range of 12 octaves</a>
+