add detailed documentation

documentation/application_workflow.md

@@ -2,7 +2,27 @@ Application workflow
 ==============
 
 
-This is a proposal for how we can control the sound synthesis and effects via a drawing application.
+This is a proposal for how we can control the sound synthesis and effects via a drawing application. Here will be discussed the ways for the users to interact with the synthesizer and the effects using the drawing application **iDraw OSC** for Apple devices.
+
+The two possible types of interactions are:
+- drawing in the drawing area;
+- choosing the tool (especially the pens) and the color to draw with.
+
+The drawing area is represented in the following figure, with the 2 parameters describing the position of the pen (X coordinate and Y coordinate) and the pressure applied to the screen. Note that if the users are drawing with the finger instead of the pen, **the pressure variable is automatically set to 1 by default**.
+
+![Drawing area](rsc/drawing_area.jpeg)
+
+The different tools available and the sound parameters they controlled are represented in the following figure.
+
+![Different types of pens](rsc/pens.png)
+
+
+In the following sections we will describe in details all the parameters that can be controlled by the users using the drawing application, and how they can do so. In particular, we will talk about:
+
+- Sound synthesis: how to control the sound timbre using colors?
+- Envelopes: how to control one or many envelopes using different pens?
+- Effects: how to apply and control the effects by drawing?
+
 
 
 # 1) Sound synthesis
@@ -30,7 +50,36 @@ The choice of the waveforms is up to the users. The application lets the users c
 The users do not have the choice of the waveforms, they are predefined and can not be changed. In that case the waveforms should at least be very different from each other to allow the users create complex sounds.
 
 
-# 2) Effects control
+
+# 2) Envelopes
+
+Envelopes are often referred to as ADSR, standing for the four parameters Attack, Decay, Sustain, Release. While all these parameters allow the users to shape the sound as best as possible, implementing a way to control them by drawing on a pad is not an esay task, especially because the pad allows for the control of only 3 parameters: the X coordinate, the Y coordinate and the pressure. Therefore there is no way to directly map the pad parameters and the 4 parameters of the envelope.
+
+However, we can stick to a more basic envelope, called AR (Attack, Release). This way, we can imagine the following mapping:
+
+| Pad parameter | OSC address | Envelope parameter  | OSC range    | Envelope parameter range |
+| :------------ | :---------- | :------------------ | :----------- | :----------------------- |
+| X axis        | /aspectX    | Attack              | [-0.5; 0.5]  | [0; 5] seconds           |
+| Y axis        | /aspectY    | Release             | [-0.5; 0.5]  | [0; 10] seconds          |
+
+The control of the envelope can be done by selecting the appropriate pen (see below).
+
+#### - Proposal 1
+We can create 3 AR envelopes, each one controlled via a different type of pen, as follows:
+
+| Envelope name | Envelope type | Description                                     | Pen type |
+| :------------ | :----------   | :---------------------------------------------  | :------- |
+| Amp. Env.     | Amplitude     | Modulates the amplitude of the sound            | Pen      |
+| Filt. Env.    | Modulation    | Modulates the cutoff frequency of the LP filter | Monoline |
+| Pitch. Env.   | Modulation    | Modulates the pitch of the oscillators          | Marker   |
+
+
+#### - Proposal 2 (Easier)
+We only create one AR amplitude envelope, controlling the amplitude of the sound, controllable with the "pen" type of pen.
+
+
+
+# 3) Effects control
 
 The effects can change drastically the final sound. Using the drawing surface we can apply effects and modify their parameters live. By effects we mean:
 
@@ -47,26 +96,26 @@ The effects can change drastically the final sound. Using the drawing surface we
 
 Let's synthesize in the following table all the possible parameters that can be modified for each one of these effects:
 
-| Effect            | Parameters       | Description                                    |
-| :---------------  | :--------------- | :--------------------------------------------- |
-| LFO               | LFO Rate         | Frequency of the LFO (e.g. 0.01Hz to 20Hz)
-|                   | LFO Intensity    | Controls which amount of modulation we want
-|                   | LFO Waveform     | Waveform for the LFO
-|                   | LFO Target       | Target of the LFO (pitch or filter)
-| Filter (HP or LP) | Cutoff frequency | Cutoff frequency
-|                   | Resonance        | Q factor of the filter
-| Distortion        | Input level      | Level of the input signal (before distortion)
-|                   | Drive            | Shape of the distortion (soft, hard...)
-|                   | Dry/wet          | Controls the ratio between input signal and signal with distortion
-| Reverb            | Room size        | How long should the reverb go
-|                   | Dry/wet          | Controls the amount of reverb we want to apply
-| Chorus            | Amount           | Frequency and depth of the chorus 
-|                   | Dry/wet          | Controls the amount of chorus we want to apply
-| EQ                | Type             | Type of filter (shelf, peak/notch, ...)
-|                   | Frequency        | Central frequency of the filter
-|                   | Gain             | Gain to apply
-| Delay             | Time             | Time between each repetition of the sound
-|                   | Intensity        | Intensity of each repetition of the sound
+| Effect                | Parameters       | Description                                    |
+| :-------------------- | :--------------- | :--------------------------------------------- |
+| **LFO**               | LFO Rate         | Frequency of the LFO (e.g. 0.01Hz to 20Hz)
+|                       | LFO Intensity    | Controls which amount of modulation we want
+|                       | LFO Waveform     | Waveform for the LFO
+|                       | LFO Target       | Target of the LFO
+| **Filter (HP or LP)** | Cutoff frequency | Cutoff frequency
+|                       | Resonance        | Q factor of the filter
+| **Distortion**        | Input level      | Level of the input signal (before distortion)
+|                       | Drive            | Shape of the distortion (soft, hard...)
+|                       | Dry/wet          | Controls the mix between dry and wet signal
+| **Reverb**            | Room size        | How long should the reverb go
+|                       | Dry/wet          | Controls the mix between dry and wet signal
+| **Chorus**            | Amount           | Frequency and depth of the chorus 
+|                       | Dry/wet          | Controls the mix between dry and wet signal
+| **EQ**                | Type             | Type of filter (shelf, peak/notch, ...)
+|                       | Frequency        | Central frequency of the filter
+|                       | Gain             | Gain to apply
+| **Delay**             | Amount           | Controls the amount of delay we want to apply
+|                       | Dry/wet          | Controls the mix between dry and wet signal
 
 
 Since the colors are used for the sound synthesis, we are left with the following controls:
@@ -80,56 +129,58 @@ Since the colors are used for the sound synthesis, we are left with the followin
   - Pen thickness;
   - Pen opacity;
 
-Instead of applying each one of these effects individually, a more creative and fun interaction design is to create custom presets consisting of a combination of effects that can be modified simultaneously using the pen. Each preset can be selected using a different type of pen, thus offering 7 possibilities of presets (one per type of pen). The following sections describe a possible set of presets that can be good-sounding and fun for the users.
+A creative and fun interaction design is to create custom presets consisting of a combination of effects that can be modified simultaneously using the pen. Each preset can be selected using a different type of pen, thus offering 4 possibilities of presets (3 out of the 7 pen types are already used for the envelopes). The following sections describe a possible set of presets that can be good-sounding and fun for the users.
 
 
 
-### Preset 1 - Regular pen (/pen)
+### Preset 1 - Pencil (/pencil)
 
-This effect preset uses the LFO, the filter and the reverb as follows:
+This effect preset uses the LFO, the filter and the reverb as follows. The parameter ranges are given as examples but may be adjusted a posteriori.
 
-| Pad parameter | Effect parameter |
-| :------------ | :--------------- |
-| X axis        | Filter cutoff    |
-| X axis        | LFO Rate         |
-| Y axis        | Filter resonance |
-| Y axis        | Reverb depth     |
-| Pen pressure  | LFO intensity    |
+| Pad parameter | OSC address   | Effect parameter | OSC range    | Parameter range       |
+| :------------ | :------------ | :--------------- | :----------- | :-------------------- |
+| X axis        | /aspectX      | Filter cutoff    | [-0.5; 0.5]  | [20; 18000] Hz
+| X axis        | /aspectX      | LFO Rate         | [-0.5; 0.5]  | [0; 15] Hz
+| Y axis        | /aspectY      | Filter resonance | [-0.5; 0.5]  | [0; max]
+| Y axis        | /aspectY      | Reverb room size | [-0.5; 0.5]  | [min; max]
+| Pen pressure  | /pressure     | LFO intensity    | [1; 8]       | [0; max]
 
 When this preset is selected, the following parameters are set and remain the same (they are not changed in any way by the pen):
 
-| Effect parameter | Value            
+| Effect parameter | Value               |
 | :--------------- | :------------------ |
 | LFO Waveform     | Decreasing sawtooth |
 | LFO Target       | Filter cutoff       |
 
 
-### Preset 2 - Pencil (/pencil)
-
-
-
-### Preset 3 - Marker (/marker)
-
-
+### Preset 2 - Crayon (/crayon)
 
-### Preset 4 - Monoline (/monoline)
-
-
-
-### Preset 5 - Crayon (/crayon)
-
-
-
-### Preset 6 - Fountain Pen (/fountainPen)
+This effect preset uses the LFO, the filter, the reverb and the delay as follows. The parameter ranges are given as examples but may be adjusted a posteriori.
 
+| Pad parameter | OSC parameter | Effect parameter | OSC range    | Parameter range       |
+| :------------ | :------------ | :--------------- | :----------- | :-------------------- |
+| X axis        | /aspectX      | LFO Rate         | [-0.5; 0.5]  | [15; 1] Hz
+| X axis        | /aspectX      | LFO Intensity    | [-0.5; 0.5]  | [0; max]
+| X axis        | /aspectX      | Delay amount     | [-0.5; 0.5]  | [0; max]
+| Y axis        | /aspectY      | Filter cutoff    | [-0.5; 0.5]  | [20; 18000] Hz
+| Y axis        | /aspectY      | Reverb dry/wet   | [-0.5; 0.5]  | [dry; dry+wet]
+| Pen pressure  | /pressure     | Filter resonance | [1; 5]       | [0; max]
 
+When this preset is selected, the following parameters are set and remain the same (they are not changed in any way by the pen):
 
-### Preset 7 - Water Color (/waterColor)
+| Effect parameter | Value               |
+| :--------------- | :------------------ |
+| LFO Waveform     | Square              |
+| LFO Target       | Filter cutoff       |
 
 
 
+### Preset 3 - Fountain Pen (/fountainPen)
 
+TBD
 
 
+### Preset 4 - Water Color (/waterColor)
 
+TBD