README.md 25.4 KB
Newer Older
FedericoDiMarzo's avatar
FedericoDiMarzo committed
1
2
3
4
5
6
7
8
# Gravity Drum Machine

*Jacopo Piccirillo*

*Federico Di Marzo*

*February 2020*

Federico Di Marzo's avatar
Federico Di Marzo committed
9
https://youtu.be/1Tvgzuj7Sq0
Federico Di Marzo's avatar
Federico Di Marzo committed
10

Federico Di Marzo's avatar
Federico Di Marzo committed
11
https://federicodimarzo.github.io/GravityDrumMachine/
Federico Di Marzo's avatar
Federico Di Marzo committed
12

Federico Di Marzo's avatar
Federico Di Marzo committed
13
https://github.com/FedericoDiMarzo/GravityDrumMachine/tree/master/Presets
Federico Di Marzo's avatar
Federico Di Marzo committed
14

FedericoDiMarzo's avatar
FedericoDiMarzo committed
15
16

## Introduction
Waddafunk's avatar
Waddafunk committed
17
Linearity is not the most enjoyed parameterization when it comes to perception of sound. *Complex* is -*somehow*- a more enjoyed and natural behavior. 
FedericoDiMarzo's avatar
FedericoDiMarzo committed
18

Waddafunk's avatar
Waddafunk committed
19
20
Even if modern drum-machines offer many different and inspiring tools devoted to rhythm, they seldom allow to explore sound generation in a *chaotic* 
fashion.
waddafunk's avatar
waddafunk committed
21
To create interesting and everchanging percussive textures, we thought it could be particularly useful to superimpose different chaotic rhythmic elements 
Waddafunk's avatar
Waddafunk committed
22
to simpler patterns.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
23

waddafunk's avatar
waddafunk committed
24
The concept of unpredictability has already been covered from hardware and software drum-machine manufactures in terms of conditional step triggering or 
Waddafunk's avatar
Waddafunk committed
25
geometrical pseudo randomization.
waddafunk's avatar
waddafunk committed
26
Anyway, we wandered more and thought about: *what if we could develop a system that automates sound morphing and generation according to the laws of nature?* 
FedericoDiMarzo's avatar
readmme    
FedericoDiMarzo committed
27
28

From these main ideas the gravity drum machine concept was born.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
29

FedericoDiMarzo's avatar
Readme    
FedericoDiMarzo committed
30
   <img src = "resources/images/galaxy.jpg" width = "600" >
FedericoDiMarzo's avatar
FedericoDiMarzo committed
31
32
33
34
35

* ### Main features
 
    *Gravity field*
    
Waddafunk's avatar
Waddafunk committed
36
37
38
39
40
41
42
43
44
   * The basic concept of this software is to simulate a universe in which motion is determined by a **gravity field**. The universe has a signature 
   associated (*e.g. 3/4:5/8*) which can be determined by the user. Every step in the signature is associated to a different system which starts its motion 
   when tempo triggers the associated step. In every system there is a black ball which generates a gravity field and, when not muted, gets triggered 
   emitting a sound every time the simulation starts. User can put other (*randomly coloured*) balls inside which will move according to the laws of gravitational 
   motion and sound when they'll collide with the black ball. 
   
   *Physical motion*
       
    * Every kind of (*complex esponential, solution of a second order differential equation, ..*) physical motion can be simulated with this software, from circular motion to damped oscillation, as better specified later.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
45
    
Waddafunk's avatar
Waddafunk committed
46
   *Polyrhythms*
FedericoDiMarzo's avatar
FedericoDiMarzo committed
47
    
Federico Di Marzo's avatar
Federico Di Marzo committed
48
   * The software can simulate more than a galaxy at the same time, each associated with his own time signature. This will result in the capability of 
Waddafunk's avatar
Waddafunk committed
49
50
   generating a universe sounding as every kind of **polyrhythm**, whith the possibility of the superposition of **linear** and **non-linear** behaviours with 
   the addition of moving balls by the user.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
51
52
53
   
    *Positional panning*
     
Waddafunk's avatar
Waddafunk committed
54
55
    * Sound emitted by moving objects are **panned as their position** in the simulation, resulting in a dynamic stereo pan effect, improving audio/video 
    perception.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
56
57
58
    
     *Motion modulation*
     
waddafunk's avatar
waddafunk committed
59
60
    * Behaviours can be automated following **gravity-motion equations patterns**, resulting in complex exponential behaviours. There will be damped 
    behaviours in colliding balls, which will go subject also to a friction force. Non-colliding balls will not be subject to friction. 
FedericoDiMarzo's avatar
FedericoDiMarzo committed
61
62
63
    
     *Double view*
     
Waddafunk's avatar
Waddafunk committed
64
65
    * There are two views in this drum machine, the first called **Galaxy view** which has a standard -*sequencer fashioned*- architecture. Inside the 
    **Galaxy view** there will be one or more systems (*e.g. three for a 3/4 galaxy, one for every step of the sequence*), and all of them will be 
waddafunk's avatar
waddafunk committed
66
67
    accessible via the **System view**. Inside the **System view** gravity motion happens. Systems get triggered, starting and ending their sound and 
    motion, by the **metronome**.
Waddafunk's avatar
Waddafunk committed
68
69
70
71
    
    *Dynamic forces*
         
     * Amplitude of gravitational and frictional forces can be changed (*via force constants scaling*), resulting in a **dynamic** physical model.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
72
73
 
* ### Limits and future features
Waddafunk's avatar
Waddafunk committed
74
   Along with the physical impossibility of subdividing time under certain orders, the "**tone.js**" library we used does not support infinitely dense time 
Federico Di Marzo's avatar
Federico Di Marzo committed
75
   subdivisions. Supporting polyrhythms leads to frequencies of the order from *pow(2,n)* to *pow(n,n)*, n being how many prime numbers are divisors of at 
Waddafunk's avatar
Waddafunk committed
76
77
78
   least one denominator, which tone magnifies 127 times by the "**tone.js**" library object used to handle tempo. Frequencies can become very high especially 
   when metric measure subdivisions (*i.e. denominator of metric signatures*) **are (or are divided by) lots of different prime numbers**, leading to very 
   small time subdivisions and possible errors.  
waddafunk's avatar
waddafunk committed
79
80
   
   *Hardware limits warning*: if one implements particularly complex sound patterns using this software having a not very powerful hardware on his machine, application can lag, especially if Operating System implements **GPU audio processing**. If so, try reducing size of the window in which application is loaded to avoid lagging. **If one has powerful hardware this is not an issue**.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
81
 
Waddafunk's avatar
Waddafunk committed
82
83
   We are currently focused on doppler-effect features, enhancement of modulation possibilities, harmonic and melodic sound pattern generation and overall 
   interface improvement.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
84
85
86
87
88
89
90
  
  *More will come*

## Overview

<figure>
  <figcaption>-->Figure 1: New project<-- </figcaption>
FedericoDiMarzo's avatar
Readme    
FedericoDiMarzo committed
91
  <img src = "resources/images/gdm.PNG" width = "600" >
FedericoDiMarzo's avatar
FedericoDiMarzo committed
92
93
</figure>

Waddafunk's avatar
Waddafunk committed
94
When loaded the software will display a black screen in which the universe will be composed of a single **galaxy** associated with a 1/4 signature. Therefore 
Federico Di Marzo's avatar
Federico Di Marzo committed
95
the newborn universe will be started containing one single galaxy which will itself contain one single system, this represented by the single green-margined 
Waddafunk's avatar
Waddafunk committed
96
97
central square shown in the center of Figure 1. We will call in this text what is shown in Figure 1 and 2 "***Galaxy view***" to distinguish it from the 
"***System view***", which usage will become clear later in this overview.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
98

Waddafunk's avatar
Waddafunk committed
99
100
On the top right corner we find an icon that will show a menu when clicked, giving the option of **saving** the current project or **loading** a previously 
saved one, along with the option of **creating** or destroying **sequences** (*i.e. **galaxies***). 
FedericoDiMarzo's avatar
FedericoDiMarzo committed
101

Waddafunk's avatar
Waddafunk committed
102
Under that icon we find the rhythmic metric associated with the newborn **galaxy**, which can be modified by clicking on it: a popup will appear in which the 
waddafunk's avatar
waddafunk committed
103
metric can be reset. By doing that new systems will be spawned (or canceled if the numerator of the metric gets decreased), all of them composed in the 
Waddafunk's avatar
Waddafunk committed
104
beginning just by a central, gravity attracting, black ball.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
105
106
107

<figure>
  <figcaption>-->Figure 2: 3/4 galaxy<-- </figcaption>
FedericoDiMarzo's avatar
Readme    
FedericoDiMarzo committed
108
  <img src = "resources/images/3_4.PNG" width = "600" >
FedericoDiMarzo's avatar
FedericoDiMarzo committed
109
110
</figure>

Waddafunk's avatar
Waddafunk committed
111
Moving towards the bottom right corner we find **play** and **stop** buttons, which can be toggled also by pressing the **spacebar**. **BPMs** are located 
waddafunk's avatar
waddafunk committed
112
left of them; a pop-up will spawn when clicking  giving the possibility of changing them. On the bottom left we find the **galaxy name**, which can be reset 
Waddafunk's avatar
Waddafunk committed
113
by clicking on it and typing the desired name in the pop-up that will appear.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
114

waddafunk's avatar
waddafunk committed
115
On the top-left we find just the name of the software and under that -*i.e. center left*- a thin **bar**. Usage of aforementioned **bar** will be clear when 
Waddafunk's avatar
Waddafunk committed
116
how to generate **polyrhythms** will be discussed.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
117
118
119
120
121
122
123



We have so covered the **galaxy view** and move now forward towards the **system view**.

<figure>
  <figcaption>-->Figure 3: System view<-- </figcaption>
FedericoDiMarzo's avatar
Readme    
FedericoDiMarzo committed
124
  <img src = "resources/images/empty.PNG" width = "600" >
FedericoDiMarzo's avatar
FedericoDiMarzo committed
125
126
</figure>

waddafunk's avatar
waddafunk committed
127
Clicking on one of the systems user will be projected into the **system view** which will appear as a blank space populated initially only by the central gravity ball.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
128

Waddafunk's avatar
Waddafunk committed
129
130
We here find the same already described features of the **galaxy view**, with no thin bar displayed and with the software name substituted by a left-pointing 
arrow, which gives the possibility of going back to galaxy view when clicked on.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
131

waddafunk's avatar
waddafunk committed
132
133
134
135
136
137
138
139
140
The central ball will emit a sound when the **metronome** triggers its system. Central balls can also be muted: when in pause, clicking on the central ball 
will cause it to go empty, representing the fact that the ball is now muted (but still attracting other balls). Clicking on it again will unmute it. 

<figure>
  <figcaption>-->Figure 5: Muted gravity ball<-- </figcaption>
  <img src = "resources/images/muted.PNG" width = "600" >
</figure>

Always 
Waddafunk's avatar
Waddafunk committed
141
142
when in pause, clicking everywhere in the blank space will generate other balls, that will be attracted by the central ball, emitting a sound when colliding. 
Clicking on them again will remove them, clicking and holding will give the possibility of dragging them around.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
143

Waddafunk's avatar
Waddafunk committed
144
145
146
Right clicking on a ball generates a pop-up menu which gives, among the other options, possibilities of choosing from a wide range of possible motions,
 choosing between a sampler and a monosynth and choosing triggered note. This menu will be better explained later in 
the **Sound Module** section.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
147
148
149

<figure>
  <figcaption>-->Figure 4: Adding balls<-- </figcaption>
FedericoDiMarzo's avatar
Readme    
FedericoDiMarzo committed
150
  <img src = "resources/images/niceballs.PNG" width = "600" >
FedericoDiMarzo's avatar
FedericoDiMarzo committed
151
152
</figure>

waddafunk's avatar
waddafunk committed
153
You are now **Up&Going**! Open your software, set your rhythmic signature, place balls inside the system and hit play to watch them sound as systems evolve, or enjoy a more broad view stepping in the galaxy. Have fun! 
FedericoDiMarzo's avatar
FedericoDiMarzo committed
154
155
156
157
158

## Advanced usage

<figure>
  <figcaption>-->Figure 6: Menu<-- </figcaption>
FedericoDiMarzo's avatar
Readme    
FedericoDiMarzo committed
159
  <img src = "resources/images/menu.PNG" width = "600" >
FedericoDiMarzo's avatar
FedericoDiMarzo committed
160
161
162
163
164
</figure>

We until now have understood how to initiate and make a single galaxy sound. Now we will focus on a deeper usage.

### Multiple galaxies and polyrhythms
Waddafunk's avatar
Waddafunk committed
165
166
We already talked about the possibility of simulating more than one galaxy in order to obtain a more-complex, polyrhythmical behaviour. To do so, all we have 
to do is to add other galaxies, set all of them as we already discussed previously for a single one and hit play.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
167
168
169

<figure>
  <figcaption>-->Figure 7: 3/4 galaxy in a 3/4:5/8 universe<-- </figcaption>
FedericoDiMarzo's avatar
Readme    
FedericoDiMarzo committed
170
  <img src = "resources/images/3_4_2.PNG" width = "600" >
FedericoDiMarzo's avatar
FedericoDiMarzo committed
171
172
</figure>

Waddafunk's avatar
Waddafunk committed
173
To create a new galaxy we have to click on "***New Sequence***" from the menu (Fig.6). This will generate an entire new galaxy, superimposed  with the previous
waddafunk's avatar
waddafunk committed
174
175
 one. We will see the white bar in the middle left now having the possibility of moving through 2 different states, indexing the two currently existing 
 galaxies. Every time we want to create a galaxy we have to iterate the process. States will increase by one every time a new galaxy gets created in the universe and decrease by one when destroyed. *Currently there is no limit for the number of states*. 
FedericoDiMarzo's avatar
FedericoDiMarzo committed
176
177
178
179

To remove a galaxy scroll to it and click "***Delete Sequence***" from the menu.

<figure>
waddafunk's avatar
waddafunk committed
180
  <figcaption>-->Figure 8: 5/8 galaxy in a 3/4:5/8 universe<-- </figcaption>
FedericoDiMarzo's avatar
Readme    
FedericoDiMarzo committed
181
  <img src = "resources/images/5_8.PNG" width = "600" >
FedericoDiMarzo's avatar
FedericoDiMarzo committed
182
183
184
185
</figure>

Hitting up and down arrow will scroll through the index, currispondent galaxy showing on the screen. 

Waddafunk's avatar
Waddafunk committed
186
187
188
189
190
191
192
193
194
195
### Sound FX settings

Selecting "**Sound FX settings**" from the **main menu** will spawn a pop-up containing three sliders: 

* *Delay time*

* *Delay feedback*

* *Reverb size*

waddafunk's avatar
waddafunk committed
196
These will be parameters of a shared **FX Channel Bus** to which sound signal can be sent from every **Sound module**, as described in next section. 
Federico Di Marzo's avatar
Federico Di Marzo committed
197
The *Fx Channel* is connected to **master channel** and user will perceive the superposition of the two signals. The send **gain** 
waddafunk's avatar
waddafunk committed
198
will be controlled via reverb and delay *send sliders* from the **Sound Module**'s setting menu.  
Waddafunk's avatar
Waddafunk committed
199

FedericoDiMarzo's avatar
FedericoDiMarzo committed
200
### Sound modules and their menu
Waddafunk's avatar
Waddafunk committed
201
Either attracting and moving balls contain a **sound module**. This will contain a sound source along with the possibilities of 
waddafunk's avatar
waddafunk committed
202
changing some of its parameters and automating them over time. Attack of sources will be triggered by **collisions** or **metronome**.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
203

Waddafunk's avatar
Waddafunk committed
204
205
206
207
208
**Right clicking** on a ball will pop-up a menu which will give the possibility of changing ball's size
(*we remind here that an increased size will not affect acceleration of the object*), triggered note, audio module contained 
(sample or monosynth right now). Along with the size slider there will be another two, one regulating delay send and the other reverb send. 

Finally we find two drop-down menus: one for selecting desired trajectory and one for choosing between different sources.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
209
210
211
212
213

* #### Every audio module will have some other options inside this menu:

   *Sampler*
    
Waddafunk's avatar
Waddafunk committed
214
215
216
217
218
219
   * Selectable sample via drop-down menu.
   
   * Release slider.
   
   * Randomize checkbox: selecting will trigger every time a random note.
   
Federico Di Marzo's avatar
Federico Di Marzo committed
220
   * Dynamic pitch checkbox: selecting will shift pitch according to distance from the gravity ball.
Waddafunk's avatar
Waddafunk committed
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
   
   *Mono Synth*
   
   * Amp attack slider.
   
   * Amp release slider.
   
   * Filter attack slider.
   
   * Filter release slider.
   
   * Filter cutoff slider.
   
   * Filter envelope amount slider.
   
   * Detune slider.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
237
   
Federico Di Marzo's avatar
Federico Di Marzo committed
238
239
   * Dynamic filter checkbox: selecting will change the cutoff frequency according to distance from the gravity ball.
   
FedericoDiMarzo's avatar
FedericoDiMarzo committed
240
### Copy-paste
Waddafunk's avatar
Waddafunk committed
241
242
Hitting left and right arrow in the galaxy view will scroll through galaxy's systems, the selected one being surrounded by a green margin. Pressing 
**cmd(ctrl) + c** will copy the selected system, which can be pasted in another one by moving over it and pressing **cmd(ctrl) + v**.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
243
244

### Saving and loading universes
Waddafunk's avatar
Waddafunk committed
245
246
It is possible to save the configuration obtained for future usages, by clicking on "***Save Universe***" from the menu. Doing so will spawn a pop-up containing 
a link which will download a "***.galaxy***" object. Name of the object will be the same as the universe.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
247

Waddafunk's avatar
Waddafunk committed
248
249
To reload the configuration, it is sufficient to click on "***Load Universe***" from the menu and load the object back from where it was stored through the 
pop-up that will appear. 
FedericoDiMarzo's avatar
FedericoDiMarzo committed
250
251
252
253
254
255
256
257
258

### Keyboard shortcuts

   - Press "***u***" to switch from **system** to **galaxy view** and vice-versa.
   - Press "***spacebar***" to toggle play and stop.
   - Press "***cmd(ctrl) + c***" to copy a system and "***cmd(ctrl) + v***" to paste it.
   - Select **System** with **left** and **right** arrow.
   - Select **Galaxy** with **up** and **down** arrow.
   
Waddafunk's avatar
Waddafunk committed
259
260
### Motion parameters

Federico Di Marzo's avatar
Federico Di Marzo committed
261
Selecting "**Motion Parameters**" from **main menu** will make appear a pop-up menu containing two sliders, giving the possibility to modify **gravity** and 
Waddafunk's avatar
Waddafunk committed
262
263
264
265
**friction**'s intensity.

"**G constant**" will modify **gravity**, while "**friction**" will modify **friction**.
   
FedericoDiMarzo's avatar
FedericoDiMarzo committed
266
267
## Physics' insights

Waddafunk's avatar
Waddafunk committed
268
269
Everything here works under rigorous physical laws. For a deeper understanding of the automation possibility of this software it is worth having a look at its 
physics. We will enumerate the different possible types of motion and what kind of automation one can get from it.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
270

waddafunk's avatar
waddafunk committed
271
Automations can be taken in this software as the temporal evolution of coordinates and velocities of the objects. The graph **coordinate(velocity)-time**
Waddafunk's avatar
Waddafunk committed
272
 will correspond to the **envelope** obtained.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
273

waddafunk's avatar
waddafunk committed
274
* #### Colliding Motions
Waddafunk's avatar
Waddafunk committed
275
276
   This motion will be an *harmonic damped oscillator*. An exact **harmonic damped envelope** can be found in the time-evolution of the radius of a colliding 
   ball.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
277
   
waddafunk's avatar
waddafunk committed
278
279
280
281
282
283
   We currently implemented three options for collisions:
   
   *Free fall*
   
   *  Ball will have zero initial velocity and simply fall towards the gravity ball.
   
waddafunk's avatar
waddafunk committed
284
   *Collision hard (coll-hard in sound module menu)*
waddafunk's avatar
waddafunk committed
285
286
287
   
   *  Energy will be above zero in this case and ball will be shooted with high velocity pointing to gravity ball, colliding only one time and then moving away without falling again (since Energy > 0).
   
waddafunk's avatar
waddafunk committed
288
   *Collision soft (coll-soft in sound module menu)*
waddafunk's avatar
waddafunk committed
289
290
291
   
   *  Energy will be below amount needed to orbit, so ball will collide more than one time. Initial velocity will have a random-generated angle between (-PI, PI) with respect to radius direction, since Energy balance allows us to be sure that shooting in every direction will make the ball collide, if it has enough time to do that (*if tempo is too fast it could happen that system resets its motion before ball actually falls*). This will result in lots of possibilities of trajectories and peculiar automations.
   
waddafunk's avatar
waddafunk committed
292
**All aforementioned trajectories will resent of friction and result in a damped oscillation behaviour; belove non-colliding orbits are described, which will not resent of friction**.
waddafunk's avatar
waddafunk committed
293
   
FedericoDiMarzo's avatar
FedericoDiMarzo committed
294
* #### Circular motion 
Waddafunk's avatar
Waddafunk committed
295
296
   Both x and y coordinates follow a periodic sine-cosine behaviour. From x and y coordinates we can get a **sine wave** behaviour (**y**) and a 
   **cosine wave** one (**x**), so the second one having PI/2 phase shift from the first one. Frequency will be the frequency of the motion.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
297
   
Waddafunk's avatar
Waddafunk committed
298
299
   *More*, from the angle we can get a linear behaviour, wich will result in a **sawtooth-wave modulation**. Frequency of the wave will be proportional 
   directly to velocity and inversely to radius of the ball, slope inverting according to clockwise/conuter-clockwise motion. 
FedericoDiMarzo's avatar
FedericoDiMarzo committed
300
301
   
* #### Elliptical motion
Waddafunk's avatar
Waddafunk committed
302
303
304
   Elliptical motion can be decomposed over the superposition of two perpendicular harmonic motions at different frequencies. This means that in general 
   one will get linear combinations of two different sine-fashioned waves in the time evolution of x and y, and so an automatization following a pattern of 
   the sum (or difference) of **two sine oscillators with a different gain**.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
305
   
Waddafunk's avatar
Waddafunk committed
306
307
  Radius and angle will follow more complex (and worth exploring) **periodic** patterns. Same can be said about the slope of the angular evolution as in the 
  circular case.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
308
309
  
* #### Hyperbolic motion
Waddafunk's avatar
Waddafunk committed
310
311
   The ball will describe a parabola with one focus situated where the gravity ball is. Radius will be equivalent to the distance of the ball by the focus. 
   From this case  can be computed a non.linear **hyperbolic** behaviour.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
312
313
   
* #### Parabolic motion
Waddafunk's avatar
Waddafunk committed
314
315
316
   In this case balls follow the pattern of a parabola in which the radius represents the distance from its focus. From this case can be computed a non-linear 
   ***pow(x,2)*** behaviour.
   
waddafunk's avatar
waddafunk committed
317
**Excepting collision hard, initial velocities are computed with inverse proportionality with respect to the radius, so velocity will be higher when near and slower when far. The opposite stands for collision hard**.
waddafunk's avatar
waddafunk committed
318
319
320

*In future we will implement the possibility for the user to decide velocity magnitude himself*.
   
Waddafunk's avatar
Waddafunk committed
321
322
323
324
325
##### Dynamic forces notes:

Initial velocity when selecting peculiar trajectory will be computed at the time one clicks on the desired one from the drop-down menu.
When scaling through the menu  gravity and friction it is suggestable first to scale forces and then select desired trajectory. Doing otherwise will compute
the trajectory using old data which will result in an unpredictable motion. 
FedericoDiMarzo's avatar
FedericoDiMarzo committed
326
   
Waddafunk's avatar
Waddafunk committed
327
328
##### Selectable trajectories notes:

waddafunk's avatar
waddafunk committed
329
Every aforementioned trajectory can be selected fom the drop-down trajectory menu. These will all have a random component, either in the angle or in
Waddafunk's avatar
Waddafunk committed
330
initial velocity or both. We used a trick in order not to have collisions from every point in which a ball can be dropped: under certain radiuses elliptic
waddafunk's avatar
waddafunk committed
331
orbit will decade in a circular one. This because motion's computations are made considering every ball as a single point in space. When placing a ball too near the gravity one,
Waddafunk's avatar
Waddafunk committed
332
333
334
elliptic orbits will be computed going through the portion of space occupied by the gravity ball and this will result in a collision.

This is not entirely resolvable if not by widening more the minor axis and compriming more the major one of the ellipsis, so in the end selecting elliptical motion
waddafunk's avatar
waddafunk committed
335
being too close to the gravity center will make the trajectory collapse in a circular one, in order to avoid collisions. 
Waddafunk's avatar
Waddafunk committed
336
337
338

*The possibility of collision when not desired is minimum but there is a tight area in which this could still happen, under very unfortunate conditions.
If so, try reducing ball's size in order to avoid it.*
Federico Di Marzo's avatar
Federico Di Marzo committed
339
340
   
## Code architecture
FedericoDiMarzo's avatar
Readme    
FedericoDiMarzo committed
341
342
343
344
345
346
Our **Gravity Drum Machine** has been developed as a dynamic web application, based on the *Web Audio API*.
The application is delivered to the user from the server as an index html page, connected to many styles and javascript modules.

In this section the code architecture is depicted broadly, to introduce the main interrelated components that form the final product.

* #### MVC structure
waddafunk's avatar
waddafunk committed
347
Scalability was one of our main concern during development; we aimed to gradually add new components and options to our drum machine, avoiding unnecessary complexity in the code structure.
FedericoDiMarzo's avatar
Readme    
FedericoDiMarzo committed
348

waddafunk's avatar
waddafunk committed
349
To pursue this intention, we arranged our code in a MVC fashion, exploiting many useful tools and proper schemes of web apps.
FedericoDiMarzo's avatar
Readme    
FedericoDiMarzo committed
350

FedericoDiMarzo's avatar
readmme    
FedericoDiMarzo committed
351
352
Our **view** is defined in many *html* pages, that can be composed in a modular way, allowing us to create a single isolated file for every component of the product.   
The graphical style has been enhanced with css style files.
FedericoDiMarzo's avatar
Readme    
FedericoDiMarzo committed
353

waddafunk's avatar
waddafunk committed
354
The **model** comprises many javascript modules, each one containing information about physical properties or audio parameters.
FedericoDiMarzo's avatar
Readme    
FedericoDiMarzo committed
355
356

All the logic in the application, that connects the user interaction in the view, with model updating, is delegated to two *controller* modules.
FedericoDiMarzo's avatar
readmme    
FedericoDiMarzo committed
357
To allow an automatic update of model properties, most html input tags have an *auto-update* class, used inside the controller to send input's values to a model object, that updates independently.
waddafunk's avatar
waddafunk committed
358
This design choice offers a clean and easy way to add functionalities to the application without worrying about updating the controller's code every time.  
FedericoDiMarzo's avatar
Readme    
FedericoDiMarzo committed
359
360

* #### Graphical rendering
waddafunk's avatar
waddafunk committed
361
362
The drum machine was designed to be fun to interact with and graphically appealing; to support these principles, we needed as much freedom as a web environment could offer.
We used an **html canvas** component to draw our evolving universes, all the rendering process delegated to the **GraphicRenderer** class.
FedericoDiMarzo's avatar
Readme    
FedericoDiMarzo committed
363

waddafunk's avatar
waddafunk committed
364
This class takes all the information needed for showing the evolution of the universe directly from the model. The rendering is completely independent from the rate at which the model is updated.
FedericoDiMarzo's avatar
Readme    
FedericoDiMarzo committed
365
 
waddafunk's avatar
waddafunk committed
366
The standard **window.requestAnimationFrame** function is used to exploit GPU acceleration, allowing for smooth animations even on high CPU load.   
FedericoDiMarzo's avatar
readmme    
FedericoDiMarzo committed
367
368

* #### Physical modeling
waddafunk's avatar
waddafunk committed
369
Our project started from a physical modeling of **gravity motion**, to which we added the possibility of **frictional forces**.
Federico Di Marzo's avatar
Federico Di Marzo committed
370

waddafunk's avatar
waddafunk committed
371
We hand-coded all the logic behind the simulation, without using external libraries, because we felt the need to design our model over our very specific needs, allowing for a **better integration** and **performance optimization**.  
FedericoDiMarzo's avatar
sync    
FedericoDiMarzo committed
372

FedericoDiMarzo's avatar
FedericoDiMarzo committed
373
374
* #### Step sequencing
Aside from the *GraphicRenderer*, many other components needed some mechanism to handle regular time updates.
waddafunk's avatar
waddafunk committed
375
To accomplish the task, we developed the **Metronome** class, that internally uses **Tone.Transport** (*a Tone.js component*) with a custom **event handling system**.
FedericoDiMarzo's avatar
sync    
FedericoDiMarzo committed
376
 
waddafunk's avatar
waddafunk committed
377
378
Every drum-machine is based on the concept of rhythmic **step triggering**; a *clock system* designed in order to synchronize sequencing correctly.
For our *Gravity Drum Machine* we took advantage of the clever design of the *Tone.Transport*  utility to implement a polyrhythmic step sequencer.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
379
380
381
382
383
384
385
386
387
388
389
390

*Tone.Transport* contains an event handling system based on a single *time signature* and *bpm*. 
In order to allow this component to fire step events, considering the possible presence of polyrhythms, our *Metronome* class performs a computation of a common *time signature* in a recursive fashion:

N3/D3 = mcm(N1xK1, N2xK2)/mcm(N1, N2)

K1 = mcm(N1, N2) / D1

K2 = mcm(N1, N2) / D2

where N1/D1 and N2/D2 are two different time divisions, N3/D3 is the new subdivision to be compared to the next one.

waddafunk's avatar
waddafunk committed
391
The resulting quarter note (*ie. "4n" in Tone.js alphabet*), becomes the **tatum** of the step sequencer.
Federico Di Marzo's avatar
Federico Di Marzo committed
392
For every independent sequence than, the *Metronome* calculate a multiplier *Mi*, that indicates the number of *tatum* needed to continue to the next step.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
393
394
395
396
397
398
399
400
401

Mi = D / Di

* #### State update
The **state evolution** of the model, is performed through the class **GridStateUpdater**. 
The metronome fires a *state update* event every *5ms*, calling a method inside *GridStateUpdater*, that updates the model according to the physical simulation.

Before every cycle, collisions checks between orbiting balls and the gravity center are performed, triggering a ball's *sound module* in case of impact.

waddafunk's avatar
waddafunk committed
402
* #### Saving and loading
FedericoDiMarzo's avatar
FedericoDiMarzo committed
403
404
405
406
The application offers the possibility to *save* the current universe's configuration locally in a file with a *.galaxy* extension. 
These files can be *loaded* later, allowing the users to recall a previous state for further editing, or just to enjoy again their complex creations.

All the process is handled by the **Screenshot** module. 
waddafunk's avatar
waddafunk committed
407
Every model's class, has a method to perform a *deep copy* of the object, used by the *Screenshot* module to create a JSON file, that can be downloaded by the user.  
FedericoDiMarzo's avatar
FedericoDiMarzo committed
408
409
This file, is used in the loading phase, to reconstruct all the objects that compose the model.

waddafunk's avatar
waddafunk committed
410
The *Screenshot* module is also used to perform a **copy/paste** operation between *systems*.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
411
412
   
* #### Sound modules
waddafunk's avatar
waddafunk committed
413
We chose to use **Tone.js** to develop all the audio features of our application.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
414
In order to adapt the library to our codebase, we designed the interface **SoundModule**.
waddafunk's avatar
waddafunk committed
415
Through this interface, we handled the problem of maintaining all the references between the connections of all *audio nodes*.
FedericoDiMarzo's avatar
FedericoDiMarzo committed
416

waddafunk's avatar
waddafunk committed
417
418
Every *SoundModule* is associated with a ball and it's directly connected to the *master output*.
In addiction, each of them is also connected with an **fx-bus** that contains a *delay* and a *reverb* module through two gain nodes (acting as a send gain).
FedericoDiMarzo's avatar
FedericoDiMarzo committed
419
420
  
<figure>
Federico Di Marzo's avatar
Federico Di Marzo committed
421
  <img src = "resources/images/SoundM.png"  >
waddafunk's avatar
waddafunk committed
422
  <figcaption>-->Figure 9: Audio flux scheme<-- </figcaption>
FedericoDiMarzo's avatar
FedericoDiMarzo committed
423
424
</figure>

FedericoDiMarzo's avatar
FedericoDiMarzo committed
425
426
427

## Authors' notes

waddafunk's avatar
waddafunk committed
428
This project started as an examination and ended up in something we will further develop and expand; believing its potential much bigger than the amount this first version is exploiting, and being a perfect playground for sound/gravity-motion experiments. 
FedericoDiMarzo's avatar
FedericoDiMarzo committed
429
430
431
432

*Jacopo Piccirillo*

*Federico Di Marzo*